The format
A notebook, opened
This is a way into SPEC.md, not a replacement for it. Every region below links to the section that governs it, and the frontmatter keys shown are the keys the implementation actually wrote when this page was built — if they drift apart, the site fails to build rather than quietly misleading you.
The bundle on disk
Only index.md and notebook.md are universally
required. Directories appear when they are first needed, and a profile decides
what a notebook of that kind must contain before it can be called done. Select a
region to see what lives there.
What a source has to survive
The single most important thing to understand about flip is that these are separate acts, in this order, and that skipping one is visible rather than silent. A static layout diagram cannot show sequence, so:
The two stages marked in accent are gates: one is refused if the source is unjudged, the other is refused if the evidence does not meet the profile's bar. Watch the refusal →
The append-only ledgers
Entity pages are the canonical record and they get rewritten. Events are not:
the ledgers only ever grow, and the generated views (log.md, every
index.md body) are disposable projections of them.
Profiles set the bar
A profile is required files, plus notebook.md sections, plus the
claim-verification bar. They are plain TOML shipped with flip and overridable
per notebook. Profile minimums are completion requirements, not creation
requirements: a missing path warns while a notebook is active and only
errors once it is marked done, published, or archived.
Two axes, never collapsed
Source reliability and claim credibility are separate judgments, after Admiralty practice [C4]. A source carries reliability; the claim carries credibility. Nothing multiplies them into a trust score, because a composite score is exactly the thing that lets a careless grade disappear into an average.
the support tuple
Judgment describes the evidence; the letter is derived from the
description, never authored.
basis — official-record, platform-data, measured, survey,
panel, single-operator, synthesis.
n — as stated, a string: a sample size must not masquerade
as the base.
base_defined — the first question to ask of any number.
? still means not yet judged — and counting toward
nothing.
independence
independent · corroborated ·
self-reported · derivative.
Four derivatives of one wire story are one source, and only
independent counts toward the bar. This axis is what
lets the corroboration count mean something.
claim status
asserted → verified · needs-2nd ·
unconfirmed · false-positive ·
retracted · superseded.
Machine-generated assertions enter as asserted. Two moves are
gated: verified on the evidence, and superseded on
naming the claim that replaced it — letting go is comparative, so there is no
way to record only that the notebook got tired of a claim.
verification methods
adversarial — a skeptic pass that sought disconfirming
evidence.
recomputation — the result re-derived independently.
independent-sources — documents the reasoning, and never
satisfies the gate on its own.
A verification is a confirmation; a probe that found the error
belongs in tests: instead.
tests, stance, exposure
What was asked of a claim and what is done
with it, orthogonal to status and to each other.
probes — attribution · substance ·
scope; each has a different repair.
stance — pursuing · holding ·
abstaining · rejecting, with a holder, so a belief
the notebook rejects can be kept as data.
exposure — bent · severely-tested
· misattributed · refuted ·
untestable, derived from the test record and never stored.
what a citation is for
evidence (the default) or subject — the role sits
on the citation, because the same document is what one claim is about and a
witness for the next.
A claim citing only subjects reports no corroboration
number rather than zero: absent means the axis does not apply, and the audit
that replaces it is an attribution test anyone can re-run against the same
bytes.
The whole CLI
Generated from flip cli --json at build time, so this page cannot
describe a command that does not exist. The core is filesystem-only: no network
calls and no LLM calls live in the library. Capture, text extraction, research
and recall are four pluggable roles that run whatever you configure, and nothing
else — flip ships a stdlib web fetcher and no opinion at all about PDF
libraries.
Above and beside a notebook
Beats
A standing mission that outlives any single notebook, holding the cross-notebook memory that makes the eleventh notebook cheaper than the first. Threads are its unit of attention; graduation turns one into a notebook; dropping one records negative coverage so a dead angle is not re-scouted.
Workspaces
Many notebooks under one root — a vault, a repo, a share. A local table
binds short handles you choose, the way git remote names work, so a
cross-notebook reference reads recipes:A3 and resolves exactly
or fails loudly. Handles never travel with the bundle.
Exports
Projections, never the canonical form: a BagIt bag for cold archival, CSL
JSON for citation managers, a policy-filtered OKF bundle for outside
consumption, and flip-render/1 JSON for renderers — with
--render-version 2 adding support tuples, exposure and stances
for a renderer that wants them, which is how the whole-notebook view on this
site is drawn.
Humans
A notebook is already a valid Obsidian vault. Frontmatter is the properties panel, the folder taxonomy reads as intended structure, and flip round-trips frontmatter keys it does not own — so a human editing beside an agent is the designed case, not a hazard.