flip site — claims and their sources
Bundle OKF 0.2 · 6 conceitos · lavallee/flip
Open source Repository Open in the app JSON README (API)
About
# flip site — claims and their sources
* [References](references/) - 7 captured sources with custody and grading
* [Claims](claims/) - 9 claims with status and citations
* [Decisions](decisions/) - 1 recorded decision
* [Questions](questions/) - 1 question, 1 open
* [Sessions](sessions/) - 2 work sessions
* [Update Log](log.md) - 4 logged events, newest first
Details
- Kind
- OKF bundles
- Topic
- No topic detected
- Publisher
- lavallee
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Last push
- 2026-09-05T04:16:34Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 09:04:14
- Updated
- 2026-09-08 09:04:14
- Origin id
lavallee/flip:website/notebook/index.md
README
# flip ## Help your agent be a reporter, not a stenographer Deep-research agents hand you a fluent report and a list of URLs. flip keeps the record underneath: every source captured and judged, every claim at an honest status, every open question named, in plain files that outlive the session. flip's CLI tools and skills help agents assess the quality of the research they build on, track the provenance and validity of claims, formulate and refine research questions, and pursue complete answers. You steer the research; the agent maintains the record. The spec defines a notebook format agent harnesses can operate: a conformant OKF bundle that also opens as an Obsidian vault. In Claude Code, Codex, or another agent harness, the agent operates flip: it captures the material the work relies on, records how each source was judged, keeps claims and questions at honest states, and leaves an attributed trail in plain files. Humans rarely need to type the CLI commands. **[See flip in action](https://lavallee.github.io/flip/flipbook.html)** · **[Explore real notebooks](https://lavallee.github.io/flip-examples/)** · **[Give flip to your agent](docs/agent-orientation.md)** · **[Get started](docs/getting-started.md)** ## Start with your agent ### Put flip to work in your repository **[Hand the orientation guide to your agent.](https://raw.githubusercontent.com/lavallee/flip/main/docs/agent-orientation.md)** ### Install for your harness Install the plugin in Claude Code: ```text /plugin marketplace add lyra-forge/marketplace /plugin install flip@lyra-forge ``` Or in Codex: ```bash codex plugin marketplace add lyra-forge/marketplace codex plugin add flip@lyra-forge ``` Start a new agent session after installing. The plugin ships ten procedural skills covering notebook practice plus reusable workflow and plugin authoring. The [harness guide](docs/claude-code.md) explains the custody-hook difference between Claude Code and Codex. To use the CLI directly, install the PyPI package as a standalone Python 3.12+ tool (the package is `flip-notebook`; the command is `flip`): ```bash uv tool install --python 3.12 flip-notebook flip --version ``` If the shell cannot find it, run `uv tool update-shell` and open a new shell. The [getting-started guide](docs/getting-started.md) also covers pipx, URL capture setup, upgrades, removal, and the first verification. When the first flip-backed investigation starts, the creation skill checks whether the `flip` CLI is available and guides its one-time installation as a standalone tool if needed. The executable enforces the notebook contract; the human does not have to assemble the two layers up front. Other harnesses can read [AGENTS.md](AGENTS.md) as the runtime-neutral contract and load the plain [`SKILL.md` files](src/flip/skills/) directly or through the [spindle](https://github.com/lavallee/spindle) package named `flip`. ### Use it conversationally > **You:** People keep saying NJ school enrollment dipped in the pandemic. Did > it? Did it come back? Use flip so someone else can audit and continue the work. > > **Agent:** *starts a notebook, captures four NJ DOE enrollment files, grades > them, computes the totals two independent ways, records three verified claims, > answers the question, and opens the logical follow-on: what is driving the more > recent decline?* What remains is not a transcript or a final report. It is a browsable notebook with the captured workbooks, hashes, derivations, claims, question journey, session record, and named actor. [Read the real notebook](https://github.com/lavallee/flip-examples/tree/main/nj-schools) or [browse its rendered form](https://lavallee.github.io/flip-examples/). Useful directions include: - “Start a pursuit notebook for this question.” - “Capture that before relying on it, then tell me how strong it is.” - “What did this evidence answer: the question as worded, a narrower one, or an adjacent one?” - “Try to disprove the load-bearing claims and record the probes that fail too.” - “Keep the unresolved branch open and say what would resolve it.” - “Hand this off so a cold agent can continue without reconstructing the trail.” The full harness guide is [docs/claude-code.md](docs/claude-code.md). ## What flip changes ### Work the question, not just the first answer A polished report is not the research record. In a 2026 benchmark of 100 deep-research tasks, the best evaluated system achieved 0.55 overall F1 and systems covered only about half of the necessary search queries ([LiveDRBench](https://proceedings.iclr.cc/paper_files/paper/2026/file/114e1dc345fe31b8b9b0c6f7b55a0644-Paper-Conference.pdf)). In DeepTRACE's dated August 2025 snapshot of 303 questions and 2,727 system-query samples, evaluated deep-research configurations were one-sided on 54.7%–94.8% of debate queries, while citation accuracy ranged from 31.4%–79.1% ([DeepTRACE](https://proceedings.iclr.cc/paper_files/paper/2026/file/ad08767706825033b99122332293033d-Paper-Conference.pdf)). flip makes the route durable: follow-on questions, corroboration gaps, closer reads, recomputations, failed tests, narrower and adjacent answers, reopen conditions, and bounded continuation work remain available to the next session. ### Keep useful signals without promoting them prematurely Capture and judgment are separate acts. A source can be held but ungraded; a promising synthesis can remain a grade-C lead; a claim can be asserted, challenged, corroborated, superseded, or rejected; an audience's belief can be recorded without becoming the notebook's belief. Ungraded material counts toward nothing, but it is not thrown away merely because it needs more work. Claims record more than truth status. Tests say which error they looked for and how it would have appeared. Stances say what someone is doing with a claim. Absence claims name the surfaces searched, because a null is only as strong as its coverage. ### Let the research outlive the session, agent, or model Every source, claim, decision, question, and session is a Markdown page with an immutable id. Every event names its actor. Raw captures and hashes establish custody; append-only JSONL preserves history; generated views provide a bounded cold-start surface. Different agents can continue the same notebook without silently replacing one another's reasoning or reconstructing the investigation from chat logs. At rest, a notebook is a conformant [Open Knowledge Format (OKF v0.2)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge bundle. It works in Git, opens as an Obsidian vault, and remains readable with `less` if flip disappears. ## Real notebook outcomes - **Data investigation:** the NJ schools notebook captured four state workbooks, found file oddities, recomputed totals two ways, corrected the popular pandemic framing, and opened a more consequential follow-on question. - **Literature review:** the RAG/hallucination review froze criteria before searching and preserved its denominator—2,600+ records identified, 31 examined, seven advanced, four excluded, three included—including a canonical paper excluded on license alone. - **Honest non-answer:** the EV-charger pursuit distinguished failed-visit data from measured uptime, answered the narrower question, left the national trend unresolved, and armed conditions that should reopen it. - **Long-running work:** an unattended loop ran 43 sessions over nearly 67 hours, keeping 380 sources, 82 claims, 47 questions, corrections, bounded nulls, and two deliberately unconfirmed load-bearing claims coherent. [Browse every example and its receipts](https://github.com/lavallee/flip-examples). They show the research states, corrections, and continuations flip preserved in real work. A controlled comparison of final research quality is a separate question. ## Start from the outcome Profiles define the notebook's rigor and operating contract. Outcome kinds add a collection contract for a particular deliverable. | What you need | Start with | |---|---| | Screen whether an angle is worth pursuing | `scout` | | Run one question to ground | `pursuit` | | Survey a field or prepare a publishable review | `research-review` or `lit-review` | | Recompute, reconcile, or investigate data | `data-investigation` | | Prepare an evidence-backed choice | `decision-packet` | | Record forecasts and what will resolve them | `forward-set` | | Maintain a shared source spine | `ledger` | | Work inside confidential boundaries | `engagement` | A **beat** sits above notebooks when the mission recurs. It keeps coverage memory and computes the next bounded item—an unmet load-bearing claim, returned commission, due forecast, open question, or ungraduated thread—so each pass does not begin by rereading the whole corpus. A **workspace** binds many notebooks under stable handles so agents can resolve and audit them together. ## What the agent maintains under the hood The core loop is orient → select → open → work → check → close → continue or stop: ```bash export FLIP_ACTOR="agent:codex" # set before `flip new`; pursuit seeds Q1 immediately flip new nj-schools --kind pursuit --title "What changed in NJ enrollment?" cd nj-schools flip next --explain flip session start enrollment-sweep --model <model> --tools <tools> \ --workflow question-pursuit --phase orient --item Q1 flip add-source ./districts.csv --note "district enrollment table" flip grade F1 --independence independent --basis official-record --base-defined flip claim add "Enrollment fell 4.2% since 2021" --source F1 --load-bearing flip question add "What is driving the decline?" --resolves-via "NJ DOE fall snapshot" flip show flip doctor flip session end enrollment-sweep --summary "..." --output Q1 --check doctor flip next ``` Humans generally direct those acts rather than typing them. `flip cli` prints an always-current command map. The [CLI quickstart](docs/quickstart.md) is a local, copy-and-run first notebook; the [evidence workflow](docs/evidence-workflow.md) explains every legitimate path through the verification gates. ## The portable artifact A notebook is one directory: ```text index.md # OKF manifest + generated hot view notebook.md # prose working memory references/ # one page per source claims/ # one page per assertion questions/ # the question journey decisions/ # forks resolved, with reasons sessions/ # attributed working episodes sources/raw/ # captured bytes, immutable sources/_provenance.jsonl # append-only custody history derived/ # extraction and recomputation receipts log/ # append-only work and negative evidence ``` Human-slug filenames stay readable; immutable ids such as `F1`, `C3`, and `Q2` keep citations stable through sanctioned renames. Unknown frontmatter keys and page bodies survive round trips, so humans, editors, and other tools can work in the same files. Notebooks can be exported as BagIt, CSL JSON, render JSON, or a policy-filtered OKF copy. The public export can withhold raw custody and private event history; rights still have to be established by the workflow's source-selection and licensing policy. It is rights-aware publishing infrastructure, not an automatic legal-clearance system. ## What flip works alongside Retrieval systems, vector stores, schedulers, agent frameworks, databases, and publishing platforms keep serving their existing roles. flip connects their research outputs through a durable record. Integrations for capture, extraction, research, and local knowledge remain operator-configured. The core makes no LLM calls and requires no service; its two third-party libraries are Click and PyYAML. The CLI enforces structural invariants and exposes missing work. Source grades and conclusions remain research judgments rather than claims the software can make. Generated views and scope-aware `flip next` support bounded re-grounding; the expected token-efficiency benefit has not yet been benchmarked. ## Documentation - [Getting started](docs/getting-started.md) — plugin and CLI installation, PATH fixes, URL setup, updates, removal, and first verification - [CLI quickstart](docs/quickstart.md) — a network-free first notebook from capture through `flip doctor` - [Evidence workflow](docs/evidence-workflow.md) — grades, claims, tests, questions, transcripts, ids, and renames - [Integrations](docs/integrations.md) — capture, extraction, research, and local-knowledge lanes - [Public source plugins](docs/plugins.md) — source adapters, installation, named lanes, and editorial handoffs - [Agent orientation](docs/agent-orientation.md) — capabilities, workflow map, and operating contract for agents - [Claude Code and Codex](docs/claude-code.md) — plugin behavior, skills, updates, and custody-hook boundary - [AGENTS.md](AGENTS.md) — concise runtime-neutral contract loaded in a repo - [Complete agent reference](docs/agent-reference.md) — command tour, lineage contract, and detailed task recipes - [Specification](SPEC.md) — OKF bundle, entities, profiles, beats, workspaces, exports, and integration contract - [Migration](docs/migration.md) — recognize and upgrade older notebooks - [Obsidian](docs/obsidian.md) — human editing and the companion plugin - [The core loop](docs/core-loop.md) — orient through receipt and stop decision - [Workflows and extensions](docs/extensions.md) — registries, hooks, trust, and authoring - [Make the next run easier](docs/repeatable-gains.md) — preserve fixes and build useful plugins from recurring problems - [Running a beat on a loop](docs/loops.md) — standing policy and unattended passes - [llms.txt](llms.txt) — compact documentation map for agents Status: spec draft v0.22; package 0.22.0; Python 3.12+; MIT licensed. Built and maintained by [Marc Lavallee](https://github.com/lavallee). Changes are tracked in [CHANGELOG.md](CHANGELOG.md); [issues](https://github.com/lavallee/flip/issues) and contributions through [CONTRIBUTING.md](CONTRIBUTING.md) are welcome.