# flip

> CLI and plain-file format for reporter's notebooks — git-friendly research corpora (sources with custody and grading, claims with verification, the positions taken on them and the tests run against them, work/session logs and kept conversations) maintained by humans and agents in the same files. A notebook is natively an OKF v0.2 knowledge bundle: one markdown page per entity with YAML frontmatter, browsable by any OKF consumer or markdown editor (Obsidian works out of the box), no service required.

## Docs

- [README.md](README.md): Project overview — continuable research, harness-first installation, real use cases, notebook choices, and the portable artifact.
- [docs/getting-started.md](docs/getting-started.md): Human setup path — harness plugins, standalone CLI installation and PATH repair, URL-capture initialization, first verification, updates, removal, and supported environments.
- [docs/agent-orientation.md](docs/agent-orientation.md): Capabilities, workflow map, installation path, and operating contract for an agent putting flip to work in an existing repository.
- [SPEC.md](SPEC.md): The notebook format (profile 0.9) — directory layout, the root index.md manifest (uid, origin), source pages and capture provenance (§5.1 capture methods and derived fidelity), text derivatives (§5.5), claims and the verification bar with citation roles, absence claims, and derivation edges (§7), the stance/tests/exposure axes (§7.1), the question journey (§7.2), forecasts (§7.3), commission contracts (§7.4), logs, sessions and transcripts (§8–9), the flip lineage profile (§6), ids/slugs/links and handle:id cross-notebook refs, profiles, beats, CLI, integration contract, exports/import, and workspaces (§18).
- [AGENTS.md](AGENTS.md): Concise always-loaded agent contract — recognition, preflight, lineage rules, skill routing, the common loop, and handoff.
- [docs/agent-reference.md](docs/agent-reference.md): Complete agent reference — five-minute tour, full command map, lineage contract, and detailed task recipes.
- [docs/claude-code.md](docs/claude-code.md): The Claude Code and Codex plugins — installation and updates, the seven skills, custody-hook coverage by harness, attribution, and what a conversational session leaves behind.
- [docs/quickstart.md](docs/quickstart.md): Short, network-free CLI exercise — create a pursuit, capture and grade a local fixture, verify a claim, close the session, and run doctor.
- [docs/evidence-workflow.md](docs/evidence-workflow.md): The full reporting workflow — grades, claim gates, severe tests, positions, question journeys, conversations, stable ids, and renames.
- [docs/integrations.md](docs/integrations.md): Operator integration guide — config roles, bundled URL fetcher, placeholders, named lanes, failure ladder, envelopes, extraction, and lead handling.
- [docs/migration.md](docs/migration.md): Recognition and in-place migration for pre-page and older-profile notebooks.
- [docs/loops.md](docs/loops.md): Running a beat on a loop — the `auto:` policy block, `flip beat next` (the ranked frontier a pass re-grounds on instead of re-reading the notebook), the small harness contract, and what flip deliberately leaves to the scheduler.
- [docs/internals.md](docs/internals.md): Module map and code contracts for the reference implementation (normative for contributors).

## Optional

- [flip-examples](https://github.com/lavallee/flip-examples): Real, browsable notebooks built by agents in ordinary working conversations — the durable record the conversation leaves behind.
- [docs/wiki-alignment.md](docs/wiki-alignment.md): How flip relates to the LLM-wiki pattern — the notebook as a native OKF bundle, flip as a candidate OKF provenance profile, `flip export okf` as a policy filter, and coexistence with OpenWiki.
- [CONTRIBUTING.md](CONTRIBUTING.md): How to contribute; tests and style expectations.
- [CHANGELOG.md](CHANGELOG.md): Release history.
