flip-notebook 0.5.0__tar.gz

flip_notebook-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run ruff check src tests --output-format=github
+      - run: uv run pytest -q

flip_notebook-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+# Publishes flip-notebook to PyPI via trusted publishing (OIDC — no stored
+# API tokens).
+#
+# PREREQUISITE (one-time, on pypi.org): register a pending trusted publisher
+# at PyPI → Account settings → Publishing with owner "lavallee", repo
+# "flip", workflow "publish.yml", environment "pypi-flip-notebook". The
+# GitHub environment is created automatically on first workflow run.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-flip-notebook
+      url: https://pypi.org/p/flip-notebook
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          enable-cache: true
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          # Idempotent re-runs: a version already on PyPI is skipped, not an
+          # error — needed when a partial publish is completed by
+          # re-dispatching after the pending publisher is registered.
+          skip-existing: true

flip_notebook-0.5.0/.gitignore

@@ -0,0 +1,20 @@
+# session/tool state
+.gstack/
+
+# local-only scratch — never commit
+_private/
+*.local.*
+
+# generated artifacts
+renders/
+dist/
+
+# python
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# agent harness state
+.claude/

flip_notebook-0.5.0/AGENTS.md

@@ -0,0 +1,269 @@
+# AGENTS.md — flip for agents
+
+flip is a CLI and plain-file format for **reporter's notebooks**: research
+corpora (sources, claims, decisions, questions, sessions) maintained by
+humans and agents together.
+
+A notebook is one directory and a conformant OKF v0.1 knowledge bundle: a
+root `index.md` whose frontmatter is the manifest, `notebook.md` as prose
+working memory, and **one markdown page per entity** with YAML frontmatter —
+`references/`, `claims/`, `decisions/`, `questions/`, `sessions/`. Event
+history is append-only JSONL under `log/` and `sources/`. Readable with
+`less`, diffable with `git`, no service required. [SPEC.md](SPEC.md) is the
+format; [docs/internals.md](docs/internals.md) is the code map; this file is
+how you, an agent, should use it.
+
+## When to reach for flip
+
+- You are doing research whose sources, reasoning, and claims must survive
+  your context window: capture into a notebook, don't summarize into the void.
+- You are asked to "start a notebook," "log this," "capture that source,"
+  "verify the claims," or to pick up work someone else left in a directory
+  whose `index.md` frontmatter declares a `flip:` version.
+- You produced LLM synthesis that later work will lean on. It is a **lead,
+  grade C, not evidence** — a notebook is where it gets promoted or killed.
+
+If a directory (or any parent) holds an `index.md` with `flip:` in its
+frontmatter, you are inside a notebook and every `flip` command works from
+there — flip walks up to find the root. (A directory with `notebook.toml` is
+a pre-0.4 notebook: run `flip migrate` first.)
+
+## The five-minute tour
+
+Everything below is real output (paths shortened). Read commands take
+`--json`.
+
+```console
+$ flip new nj-schools --kind scout --title "NJ enrollment dip"
+created scout notebook 'nj-schools' at /work/nj-schools
+next: cd /work/nj-schools && flip log "started" — see `flip --help` for the toolkit
+
+$ flip log "started scouting the angle"
+logged 2026-07-10T19:59:41Z · agent:claude
+
+$ flip add-source ./districts.csv --note "district enrollment table"
+F1 · sources/raw/F1.csv · references/districts.md (grade ?)
+judge it: flip grade F1 --grade A|B|C --independence original|republisher|derivative|self-interested
+
+$ flip grade F1 --grade A --independence original --notes "state data, extracted ourselves"
+F1 · grade A · original · fresh
+
+$ flip claim add "District enrollment fell 4.2% since 2021" --source F1 --load-bearing
+C1 asserted · sources: F1 · corroboration: 1
+
+$ flip claim status C1 verified
+C1 → verified · corroboration: 1
+
+$ flip decide --question "Which county first?" --decision "Start with Essex" --why "largest enrollment swing"
+D1 · Start with Essex
+
+$ flip pass "2019 funding blog post" --reason "republishes state PR verbatim, no added data"
+passed 2026-07-10T19:59:41Z · republishes state PR verbatim, no added data
+
+$ flip question add "Does the fall predate the funding change?"
+Q1 open · Does the fall predate the funding change?
+
+$ flip show
+nj-schools · scout · active · 2026-07-10
+
+OPEN QUESTIONS
+  Q1 · Does the fall predate the funding change?
+
+RECENT LOG
+  2026-07-10T19:59:41Z · agent:claude · started scouting the angle
+
+$ flip doctor
+ok: no findings
+```
+
+Every entity is a page whose **filename is a human slug and whose id is
+immutable frontmatter**: the capture above created
+`references/districts.md` with `id: F1` and `aliases: [F1]`. Cite ids in
+prose as `[F1]`, `[C1]` — greppable both directions — and resolve them with
+`flip open`:
+
+```console
+$ flip open F1
+/work/nj-schools/references/districts.md
+
+$ flip rename F1 district-enrollment-table
+F1: references/districts.md → references/district-enrollment-table.md
+rewrote links in 2 file(s)
+```
+
+`flip rename` is the **only sanctioned rename**: it moves the page (id and
+aliases untouched, so `[F1]` cites keep resolving) and rewrites every
+markdown link and `supports` path notebook-wide. Never `mv` a page yourself.
+An unknown id fails helpfully:
+
+```console
+$ flip open Z9
+no page with id 'Z9' (known ids: C1, D1, F1, Q1)
+```
+
+(Source ids use `P`/`A`/`F`/`T`/`S` prefixes by kind; `C#` claims, `D#`
+decisions, `Q#` questions — prefixes are disjoint, so a bare `[F1]` or `[D2]`
+cite is never ambiguous.) `flip doctor` tracks the profile's minimums: while
+a notebook's status is `active` or `dormant`, missing required files are
+WARNs (they appear with use — the first `flip decide` and `flip pass` create
+a scout's); once status is `done`, `published`, or `archived`, they become
+ERRORs.
+
+When verification isn't earned, flip refuses and says what to do:
+
+```console
+$ flip claim status C2 verified
+cannot verify C2: 0 independent original source(s) of 1 required and no
+grade-A source among its sources (sources: none); add independent original
+sources to the claim or upgrade one to grade A via `flip grade`
+```
+
+The rest of the surface: `flip source list` (every source at a glance:
+`F1 · A/original/fresh · districts.csv · references/district-enrollment-table.md`),
+`flip question list` / `flip question answer Q1 --note "..."`,
+`flip session start|end` (working-episode pages under `sessions/`),
+`flip profiles` (available kinds), `flip index` (per-user notebook registry),
+`flip migrate` (v0.3 → v0.4 in place),
+`flip export bag|csl|okf` (BagIt / CSL JSON / policy-filtered public bundle),
+`flip show --claims|--stale`, and `--json` on every read command.
+
+## The contract — lineage rules you MUST honor (SPEC §6)
+
+1. **Capture before cite.** A page may only cite what the notebook has
+   custody of: a `references/` page backed by raw bytes under `sources/raw/`
+   and a provenance event. Never paste fetched text into the notebook as if
+   it were a source — `flip add-source` records bytes, hash, and provenance.
+   Dangling citations are legal but counted; `flip doctor` reports them.
+2. **Judgment is explicit and separate from capture.** Every capture opens at
+   grade `?`, which counts toward **nothing** — read the source, then
+   `flip grade` it. Capture is custody, not judgment.
+3. **LLM output is grade C until promoted.** Anything you synthesized — or
+   pulled from a retrieval service — enters as a lead in a session page or a
+   grade-`C` source. Under `citation_rule: public-terminus` every
+   load-bearing chain must end at a public, independently verifiable source.
+4. **Claims carry status, and verification is gated.** Assert claims with
+   `flip claim add --source <id>` the moment the work leans on them.
+   `verified` is refused until the profile's corroboration bar is met
+   (default: two independent original sources, or one grade-A primary),
+   counting judged sources only. Don't argue with the gate — go get
+   corroboration.
+5. **Generation is logged.** Wrap every LLM run or research sweep in
+   `flip session start` / `flip session end` — the reasoning chain is
+   evidence too.
+6. **Events append, views regenerate.** `log/*.jsonl`,
+   `sources/_provenance.jsonl`, and `derived/_derivations.jsonl` are
+   append-only: never edit, rewrite, or delete a line. `index.md` bodies and
+   `log.md` are **generated** — flip overwrites them on every mutating
+   command, so hand-edits there don't survive; edit pages and ledgers, not
+   listings.
+7. **The round-trip rule: preserve keys you don't own.** Entity pages are
+   edited by humans, editors, and other tools. When you edit one — by hand or
+   programmatically — change only the keys and prose you mean to change;
+   frontmatter keys you don't understand MUST survive, and so must the body.
+   flip's own commands obey this; so must you.
+8. **Attribution everywhere.** Every event and page records its `actor`. flip
+   auto-detects known agent harnesses, but be explicit:
+   `export FLIP_ACTOR="agent:claude"` (or `agent:<your-name>`). Humans are
+   `human:<name>`, tools `tool:<name>`.
+
+Also: ids are never reused, even after retraction; never hand-edit anything
+under `sources/raw/` (verbatim bytes, immutable — recapture instead); and
+run `flip doctor` before finishing — fix every ERROR (doctor exits 1), read
+every WARN and either fix it or note in the log why it stands.
+
+## Recipes
+
+### Start a notebook
+
+```bash
+flip profiles                              # pick a kind: ledger|scout|research-review|engagement|data-investigation
+flip new <slug> --kind scout --title "..."
+cd <slug>
+export FLIP_ACTOR="agent:claude"
+flip log "started: <one-line mission>"
+# fill in notebook.md's section stubs — 'The tip' and 'Hypotheses & falsifiers' first
+flip doctor   # expect missing-required WARNs until the profile's files exist through use
+```
+
+Profiles require files that appear through use: on a fresh `scout`, doctor
+WARNs (`missing-required decisions`, `missing-required log/passed.jsonl`)
+until the first `flip decide` and `flip pass`; on a fresh `research-review`,
+until `add-source`, `claim add`, and `session start` have each run once and
+you've created `drafts/` yourself. The WARN lines name exactly what's
+missing — and they harden into ERRORs the moment the manifest status becomes
+`done`, `published`, or `archived` (SPEC §13: completion requirements, not
+creation requirements).
+
+### Capture + grade a source
+
+```bash
+flip add-source https://example.com/report --note "why captured"   # runs your configured web fetcher
+flip add-source ./filing.pdf                                       # local file: builtin copy + hash
+flip add-source doi:10.1234/abcd                                   # paper: configured doi fetcher
+# read it, then judge it — grading is a judgment, not a formality:
+flip grade A1 --grade B --independence original --freshness fresh --notes "official docs; original publisher"
+flip source list           # audit: any grade "?" line is captured but unjudged
+flip source list --json    # same rows for machine consumption
+```
+
+Each capture opens a `references/<slug>.md` page — custody and judgment in
+frontmatter, your capture notes in the body. URL/DOI capture needs a
+`[fetchers]` entry in `$FLIP_HOME/config.toml` (default `~/.flip/config.toml`)
+— see [docs/quickstart.md](docs/quickstart.md). If the fetcher isn't
+configured, flip's error shows the exact stanza to add.
+`republisher`/`derivative` sources don't count toward corroboration — prefer
+the original — and neither does anything still graded `?`.
+
+### Assert and verify a claim
+
+```bash
+flip claim add "<one-sentence assertion>" --source A1 --source F2 --load-bearing
+flip claim status C1 verified          # refused until the profile's bar is met
+flip claim status C1 needs-2nd         # honest fallback while you hunt corroboration
+flip claim list --status needs-2nd --json
+```
+
+The claim page (`claims/<slug>.md`) carries `sources: [ids]` and a generated
+`# Citations` block linking the reference pages; flip recomputes
+`independent_corroboration` on status changes and doctor flags drift.
+
+### Record a session
+
+Before an LLM run or research sweep:
+
+```bash
+flip session start landscape-scan --model claude-fable-5 --tools web-search
+# prints sessions/2026-07-10T2000-landscape-scan.md
+# fill in its Goal / Prompt / Key outputs sections as you work
+flip session end landscape-scan --summary "3 candidate districts; Essex strongest signal"
+```
+
+Promote anything from the session the work will rely on: leads →
+`flip add-source` + `flip grade`, follow-ups → `flip question add`, forks
+resolved → `flip decide`, dead ends → `flip pass`.
+
+### Hand off
+
+```bash
+flip doctor                 # fix ERRORs first
+flip show                   # this is what the next reader sees
+# write/refresh HANDOFF.md: state of play, open questions (Q#), claims
+# needing work (C#), next actions — the cold-start view
+flip log "handoff: <where things stand in one line>"
+```
+
+### Pick up a pre-0.4 notebook
+
+```bash
+flip migrate      # from anywhere inside it; finds the notebook.toml root
+# migrated /work/legacy to v0.4 · 1 sources, 1 claims, 1 decisions, 1 questions, 1 sessions
+flip doctor       # audit the result; migration preserves ids and history
+```
+
+## Skills
+
+Procedural checklists for these workflows ship in
+[src/flip/skills/](src/flip/skills/) — `notebook-create`, `notebook-source`,
+`notebook-log`, `notebook-audit`, `notebook-handoff`, `notebook-lessons` —
+as plain `SKILL.md` files usable by any agent runtime, and as a
+[spindle](https://github.com/lavallee/spindle) package named `flip`.

flip_notebook-0.5.0/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to the flip spec and tooling are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning follows [Semantic Versioning](https://semver.org/).
+
+## [0.5.0] — 2026-07-10
+
+### Added
+- **Beats** (SPEC §14): the grouping layer above notebooks. A beat is itself
+  an OKF bundle — `flip_beat:` manifest in its root `index.md`, a `beat.md`
+  mission page, and one **thread** page per line of attention (`TH#`, kind
+  `arc`/`vein`, weighted triage scores). `flip beat new / thread add|update|
+  drop / graduate / show / log`. Graduation scaffolds a child notebook under
+  `notebooks/`, back-links both ways (`links.beat: <beat>#<thread>`), and
+  records coverage; drops record the reason as negative coverage. Beat and
+  notebook commands resolve correctly from inside each other.
+- Notebook doctor WARNs `broken-beat-link` when a manifest's `links.beat` no
+  longer resolves.
+- Trusted-publishing workflow (`publish.yml`): GitHub releases publish
+  `flip-notebook` to PyPI via OIDC.
+- [docs/okf-provenance-profile.md](docs/okf-provenance-profile.md): flip's
+  extension vocabulary written up as a draft OKF provenance profile.
+
+### Fixed
+- File captures slug from the stem: `districts.csv` →
+  `references/districts.md` (was `districts-csv.md`; found dogfooding).
+
+## [0.4.0] — 2026-07-10
+
+**A flip notebook is now natively an
+[OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+knowledge bundle** — flip becomes an extension profile of OKF (lineage rules
+for LLM-built wikis, SPEC §6) rather than an exporter to it. Breaking
+release; `flip migrate` converts v0.3 notebooks.
+
+### Changed (breaking)
+- **Entities are pages.** Sources, claims, decisions, questions, and sessions
+  are one markdown file each with YAML frontmatter — the canonical record —
+  in `references/`, `claims/`, `decisions/`, `questions/`, `sessions/`.
+  The JSONL entity ledgers (`sources/ledger.jsonl`, `analysis/claims.jsonl`,
+  `log/decisions.jsonl`, `log/questions.jsonl`) are gone; event logs
+  (`log/log.jsonl`, `log/passed.jsonl`, `_provenance.jsonl`,
+  `_derivations.jsonl`) remain append-only JSONL sidecars.
+- **Filenames are human slugs** (`references/lecun-jepa-keynote.md`); the
+  immutable compact id lives in frontmatter with `aliases: [<id>]`, so id
+  wikilinks resolve in Obsidian-style editors. `flip rename` moves a page and
+  rewrites links; `flip open <id>` resolves ids.
+- **The manifest moved into the root `index.md` frontmatter** (OKF's
+  sanctioned identity slot); `notebook.toml` is retired. Policy keys are
+  flat (`visibility`, `source_trail_public`, …) and edit cleanly as
+  Obsidian properties.
+- **`index.md` bodies and `log.md` are generated views**, regenerated on
+  every mutating command.
+- **`flip export okf` is now a policy filter** (visibility gate + source-
+  trail stripping) over an already-conformant bundle, not a format transform.
+- PyYAML joins click as a core dependency (faithful reading of human/editor-
+  authored frontmatter); flip writes a deterministic strict subset.
+
+### Security
+- Stripped exports (`source_trail_public: false`) withhold **derived views of
+  withheld data**, not just the data: `log.md` (a rendering of the withheld
+  work log), reference titles/descriptions (capture notes, private file
+  basenames), and any prior export or bag nested inside the notebook are all
+  excluded; the references listing is regenerated from the stripped pages.
+  Known residual: a claim's `# Citations` label text is frozen at claim-add
+  time and ships as written.
+
+### Added
+- **The flip profile for OKF** (SPEC §6): eight lineage rules — capture
+  before cite, explicit judgment, status-carrying claims, logged generation,
+  append-only events, key preservation, attribution, render discipline —
+  plus the extension frontmatter vocabulary.
+- **Round-trip guarantee**: flip preserves frontmatter keys and bodies it
+  doesn't own, so humans (Obsidian) and other agents can edit the same
+  files (SPEC §12).
+- `flip open`, `flip rename`, `flip migrate`; doctor checks for OKF
+  conformance, id/alias integrity, dangling citations, corroboration drift.
+
+## [0.3.0] — 2026-07-10
+
+### Added
+- **Reference implementation**: the `flip` CLI (`new`, `add-source`, `grade`,
+  `log`, `decide`, `pass`, `question`, `claim`, `session`, `show`, `doctor`,
+  `index`, `export`, `profiles`, `source list`, `question list`) as a Python
+  package (`flip-notebook`, stdlib + click, no network in the core), with a
+  full test suite and CI.
+- **OKF export** (`flip export okf`): project a notebook as an
+  [Open Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+  knowledge bundle — sources as `references/` concepts with custody
+  frontmatter, claims with `# Citations`, decisions, `log.md`, policy-gated
+  source trail, and `--announce` marker blocks for AGENTS.md. Design:
+  [docs/wiki-alignment.md](docs/wiki-alignment.md).
+- **Agent-learnability layer**: `AGENTS.md`, `llms.txt`,
+  [docs/quickstart.md](docs/quickstart.md), and six procedural skills under
+  `src/flip/skills/` (also declared as a spindle package in `pyproject.toml`).
+- BagIt export (`flip export bag`), CSL JSON export (`flip export csl`),
+  per-user notebook registry (`flip index`).
+
+### Changed
+- **Breaking (spec §3/§9):** file/dataset source ids now use the `F#` prefix;
+  `D#` is reserved for decisions (the two collided in prose cites).
+- **Spec §7.2 hardened:** ungraded (`?`) sources never count toward claim
+  corroboration — capture is custody, not judgment.
+- **Spec §12:** profile minimums are completion requirements — missing
+  required files WARN while a notebook is `active`/`dormant` and ERROR once
+  it is `done`/`published`/`archived`.
+
+### Fixed
+- Ten findings from an adversarial review of the initial implementation,
+  including manifest round-trip data loss, TOML escaping that could brick a
+  notebook, session-slug suffix collisions, corroboration dedupe, and BagIt
+  symlink handling.
+
+## [0.2.0] — 2026-07-09
+
+### Added
+- **Beats** (§13): a grouping layer above notebooks — a standing mission with
+  a thread ledger that spawns notebooks as threads get real.
+- **Detached notebooks** (§3): convention for notebooks whose visibility
+  exceeds their host repo's (private notebook, public repo).
+- **Pluggable fetchers** (§14): `flip add-source` routes through commands
+  registered in `~/.flip/config.toml`; only `builtin:copy` is built in.
+- **Dependency-free registry** (§14): `flip index` writes a plain per-user
+  `~/.flip/index.jsonl` by scanning; no services.
+
+### Changed
+- Removed the `agent-beat` profile; that territory belongs to the beat layer.
+- Hardened the no-proprietary-dependencies commitment throughout (§15).
+
+## [0.1.0] — 2026-07-09
+
+### Added
+- Initial spec draft: principles, directory layout, manifest, source custody +
+  capture provenance, source-quality model (reliability/credibility split),
+  derivations log, claim ledger, work/decision/negative-evidence/session logs,
+  IDs, hot/cold views, drafts and renders, profiles, CLI sketch, skills layer,
+  git conventions, interop exports.

flip_notebook-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to flip
+
+flip is at the **spec stage** — the highest-value contributions right now are
+critiques of the format itself: places where the spec would fight real
+reporting or research practice, gaps in the provenance model, profile shapes
+you'd need that don't fit.
+
+## How
+
+- **Open an issue** for design discussion — the smaller and more concrete the
+  scenario, the better ("here's a capture case the provenance record can't
+  express" beats "custody should be more flexible").
+- **PRs against SPEC.md** are welcome for wording, structure, and fixes. For
+  substantive design changes, open an issue first; accepted changes land with
+  a CHANGELOG entry and, when they alter meaning, a version bump.
+- Spec changes that alter the meaning of existing files on disk (ledger
+  fields, status enums, layout) are **breaking** and versioned accordingly —
+  notebooks in the wild must never be silently reinterpreted.
+
+## Style
+
+- Plain text first; examples over abstractions; every normative rule should
+  say what failure it prevents.
+- Keep the core small. New requirements belong in a profile unless every
+  notebook needs them.
+
+## Code (upcoming)
+
+The `flip` CLI will live in this repo. Once it lands: tests required for
+behavior changes, CI must be green, and the library core stays
+filesystem-only — no network calls, no LLM calls, no required services.

flip_notebook-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Lavallee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flip_notebook-0.5.0/PKG-INFO

@@ -0,0 +1,130 @@
+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).