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