Your first notebook

1. Install it

   A tool install keeps flip off your project's dependency list, which is where it belongs — flip is something you run, not something you import.

   uv tool install flip-notebook

   Or pipx install flip-notebook, or pip install flip-notebook inside a virtualenv. From source: git clone https://github.com/lavallee/flip && cd flip && uv sync.

   flip --version

2. Tell it who you are

   Every event and every entity page records an actor. Set it once in your shell profile and stop thinking about it; agents set it per-invocation so their work is distinguishable from yours.

   export FLIP_ACTOR="human:yourname"

   Precedence is --actor, then FLIP_ACTOR, then a detected default.

3. Write a starter config, if you want URL capture

   Local files always copy with no config. For URLs, this writes a config.toml whose web lane uses the bundled zero-dependency flip-fetch helper, so capture works immediately and you can swap in curl, wget, a headless browser, or your own fetcher later.

   flip config init

   The same file carries a commented [extractors] stanza — the lane flip extract uses to turn a captured PDF into readable text under sources/text/, keyed by media family. flip ships no extractor and picks no default, because a package that has an opinion about PDF libraries is a package you have to fight.

   flip's core makes no network calls and no LLM calls. It runs exactly what you configure, and records which tool ran in the provenance ledger.

4. Open a notebook

   Pick a profile with --kind. A scout screens an angle fast and needs one judged source per claim; a research-review is headed for publication and demands two. You can change your mind later — flip migrate upgrades in place.

   flip new my-question --kind scout --title "The thing I am trying to find out"

   Kinds answer to what people actually say: --kind "literature review" lands on lit-review, whose doctor knows from day one what a finished review must contain. flip kind list shows them all; open-ended is first-class (scout).

   cd my-question

5. Capture something, before you cite it

   A local file, a URL, or a DOI. flip copies the bytes in, hashes them, appends a provenance line, and opens a source page at grade ?. From this point the notebook does not depend on that thing still existing anywhere else.

   flip add-source ./some-report.pdf --note "why I grabbed this"
   flip add-source https://example.org/a-page

6. Read it, then grade it

   Capture is custody; grading is judgment, and they are deliberately separate acts. Grading describes the evidence — how independent, what basis, whether the measured quantity is even defined — and the letter grade is derived from the description, never handed out. Until then the source counts toward nothing at all — which is the point, because a source you have not read should not be able to prop up a claim.

   flip grade F1 --independence independent --basis official-record --base-defined --notes "why this reading"

7. Make a claim, and try to promote it

   Claims enter as asserted. Mark the ones your work would fall over without as --load-bearing, because those are the ones flip doctor audits. Then find out what your profile demands.

   flip claim add "The assertion, in one sentence" --source F1 --load-bearing
   flip claim status C1 verified

   If it refuses, that is the system working. Add an independent source with flip claim source add C1 F2, or record a real check with flip claim verify C1 --method adversarial — a skeptic pass that went looking for disconfirming evidence.

   Two more moves belong here. A claim that is about a document rather than supported by one cites it with --about, and owes an attribution test instead of a second witness that cannot exist. And flip claim test records a probe that could have come out the other way — the error you hunted, how it would have shown up, and what you would have seen instead — which is the one place a check that found the error can be written down. flip claim exposure C1 reads the result back.

8. Audit, and see where you are

   doctor validates after the fact rather than gatekeeping before, which is what makes it safe for a human to edit the same files in a markdown editor. show computes the hot view every time; add --json and it becomes an agent's context primer.

   flip doctor
   flip show

The outputs shown above are real, captured by running these commands against a scratch notebook when this page was built. Ids and timestamps will differ in yours.