Metadata-Version: 2.4
Name: flip-notebook
Version: 0.5.0
Summary: Reporter's notebooks: git-friendly research corpora maintained by humans and agents
Project-URL: Homepage, https://github.com/lavallee/flip
Project-URL: Repository, https://github.com/lavallee/flip
Author: Marc Lavallee
License: MIT
License-File: LICENSE
Keywords: agents,journalism,knowledge,notebook,provenance,research
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# flip

Format and tooling for **reporter's notebooks** — source-controlled research
corpora created and maintained by any mix of humans and agents.

A flip notebook **is an
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
(OKF v0.1) knowledge bundle at rest**: a directory of markdown pages with
YAML frontmatter, an `index.md` root, and a generated `log.md`. Any OKF
consumer can browse one; any markdown editor can edit one. What flip adds is
an **extension profile for lineage** — the discipline the LLM-wiki pattern
(Karpathy's framing, OKF, LangChain's OpenWiki) deliberately leaves open:
custody of the sources you rely on (local bytes, hashed at capture),
explicit source grading, claims gated by a corroboration bar, work and
LLM-session logs, and a timestamped history. A wiki tells an agent what we
know; a notebook can prove where it came from.

Humans and agents work **in the same files**. Every source, claim, decision,
question, and session is one page with a human-slug filename and its
immutable id in frontmatter — open the notebook as an
[Obsidian](https://obsidian.md) vault and frontmatter is the properties
panel, `aliases` make `[[A3]]`-style id links resolve, and relative links
light up the graph view. Re-grading a source from the properties panel is a
legitimate flip operation; `flip doctor` validates after the fact instead of
gatekeeping before.

**[SPEC.md](SPEC.md)** has the full format: directory layout, the manifest
(root `index.md` frontmatter), source pages and capture provenance, claims
and the verification bar, logs and sessions, the flip lineage profile
(SPEC §6), profiles, the beat layer, the CLI, skills, and the integration
contract.

Design commitments:

- **Plain files, no services.** Markdown + YAML frontmatter for entities,
  append-only JSONL for events. Readable with `less`, diffable with `git`,
  browsable by any OKF consumer or markdown tool. Standards (BagIt, CSL,
  RO-Crate, Web Annotation) are generated exports, never the canonical
  format — except OKF, which the notebook natively is.
- **No proprietary dependencies.** Capture tools, retrieval services, and
  render targets are all pluggable; a notebook is intelligible from its
  local files alone.
- **Custody first.** Local archival copies with hashes at capture; processing
  is logged and re-runnable; LLM output is a lead, not evidence, until
  promoted through `references/` and graded.
- **Graceful co-editing.** One entity per file, metadata in frontmatter,
  prose in the body; tools preserve frontmatter keys they don't own, so
  human edits and agent edits round-trip through each other.

## Install

```bash
uv tool install flip-notebook      # or: pipx install flip-notebook
```

From source: `git clone https://github.com/lavallee/flip && cd flip && uv sync`,
then `uv run flip --help`. Python 3.12+; the core is stdlib + click + PyYAML.

## Quickstart

```bash
flip new nj-schools --kind scout --title "NJ enrollment dip"
cd nj-schools
flip add-source ./districts.csv --note "district enrollment table"
# F1 · sources/raw/F1.csv · references/districts.md (grade ?)
flip grade F1 --grade A --independence original         # judge it after reading
flip claim add "Enrollment fell 4.2% since 2021" --source F1 --load-bearing
# C1 asserted · sources: F1 · corroboration: 1
flip claim status C1 verified      # gated: refused until the corroboration bar is met
flip decide --question "Which county first?" --decision "Start with Essex" --why "largest swing"
flip pass "2019 funding blog post" --reason "republishes state PR verbatim"
flip show                          # the hot view: open questions, claims needing work, recent log
flip doctor                        # lint: OKF conformance, profile minimums, verification bar
```

Filenames are human slugs (`references/districts.md`); the immutable id
(`F1`) lives in frontmatter. `flip open F1` resolves an id to its page;
`flip rename F1 district-enrollment-table` renames the file and rewrites
every link to it. `flip migrate` upgrades a pre-0.4 notebook in place.

URL and DOI capture route through fetchers you configure (e.g.
[SingleFile](https://github.com/gildas-lormeau/single-file-cli) for web
pages) — see [docs/quickstart.md](docs/quickstart.md) for the walkthrough,
fetcher config, profiles, and the Obsidian setup.

## For agents

Notebooks are built to be maintained by humans and agents together:

- **[AGENTS.md](AGENTS.md)** — the five-minute tour, the lineage rules
  agents must honor (capture before cite, grade-C-until-promoted, the
  verification bar, the round-trip rule, `flip doctor`, `FLIP_ACTOR`), and
  task recipes.
- **[llms.txt](llms.txt)** — doc map for LLM consumption.
- **[src/flip/skills/](src/flip/skills/)** — procedural skills
  (`notebook-create`, `notebook-source`, `notebook-log`, `notebook-audit`,
  `notebook-handoff`, `notebook-lessons`) as plain `SKILL.md` files usable by
  any agent runtime. The skills also ship as a
  [spindle](https://github.com/lavallee/spindle) package named `flip`.

Status: spec draft v0.5 — notebooks are native OKF v0.1 bundles. The CLI
covers the full surface (`new`, `add-source`, `grade`, `log`, `decide`,
`pass`, `question`, `claim`, `session`, `show`, `open`, `rename`, `doctor`,
`index`, `migrate`, `export bag|csl|okf`), plus **beats** — the standing
layer above notebooks (`flip beat new / thread add / graduate / show`): a
mission with weighted-triage threads that graduate into notebooks and keep
cross-notebook coverage memory. `flip migrate` converts v0.3 notebooks in
place. See [docs/wiki-alignment.md](docs/wiki-alignment.md) for how flip
relates to OKF and OpenWiki, and
[docs/okf-provenance-profile.md](docs/okf-provenance-profile.md) for flip's
vocabulary as a draft OKF provenance profile. Next: an Obsidian plugin
surfacing doctor findings inline.

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Changes are
tracked in [CHANGELOG.md](CHANGELOG.md). [MIT licensed](LICENSE).
