# FablePool Usability Guide This document is the task-oriented companion to the command-by-command [CLI reference](cli-reference.md) and the scripted [walkthrough](walkthrough.md). The reference tells you *what each command does*; this guide tells you *how to get things done*, how to read what the tool shows you, how to recover when something goes wrong, and how to drive the tool from scripts. It is written for two audiences: 1. **End users** inspecting and correcting what their node believes about them. 2. **Integrators** building on top of the CLI (automation, other UIs, audits). --- ## 1. The mental model in 60 seconds Everything the node knows lives in an **append-only operation log**. Three kinds of things matter when you are using this interface: - **Evidence** — raw imported facts: a calendar event, a note, photo metadata. Evidence is never edited; it is what the node *saw*. - **Claims** — statements the derivation engine inferred *about you* ("regularly attends a Tuesday evening class", "works primarily from home"), each carrying a **confidence** score and a **provenance** trail pointing at the evidence and intermediate claims it was derived from. - **Your interventions** — corrections and refutations. These are first-class signed operations, not edits. When you refute a claim, the claim is marked refuted and every claim *derived from it* is re-evaluated: some are invalidated outright, others drop in confidence. Nothing is silently deleted; the log records that you intervened, and why downstream beliefs changed. If you keep one rule in mind, everything in the interface makes sense: > **You never edit the past. You append your judgment, and beliefs cascade.** --- ## 2. First run ```console $ fablepool init # create a node home (keys + empty log) $ fablepool seed # load the bundled sample dataset $ fablepool topics # see what the node believes, grouped by topic ``` By default the node home is created under your platform data directory. To keep an experiment isolated (recommended while learning), point the tool at a scratch directory: ```console $ export FABLEPOOL_HOME=/tmp/fp-demo $ fablepool init && fablepool seed ``` Every example below works identically inside the interactive shell (`fablepool shell`) — drop the `fablepool` prefix once inside. The shell is the more comfortable surface for exploratory sessions because claim and evidence identifiers from the previous command can be referenced by their short index instead of being retyped. --- ## 3. The five core tasks ### 3.1 "What do you know about me?" Start broad, then narrow: ```console $ fablepool topics # topic → claim count + avg confidence $ fablepool claims --topic health # claims within one topic $ fablepool claims --min-confidence 0.8 # only what the node is sure of ``` A claim listing shows, for each claim: a short id, the statement, the topic, the confidence, and its status (`active`, `refuted`, `invalidated`, `corrected`). Refuted and invalidated claims are hidden by default; pass `--all` to include them — this is the fastest way to review the history of your own corrections. ### 3.2 "Why do you believe that?" This is the heart of the interface. Given a claim id: ```console $ fablepool explain ``` You get the **derivation tree**: the rule that produced the claim, the inputs it consumed (other claims and/or raw evidence), each input's own confidence, and a plain-language sentence explaining the inference step. The tree bottoms out at evidence rows. To see the raw evidence itself: ```console $ fablepool evidence ``` This prints the original imported record verbatim (the calendar event JSON, the note body, the photo EXIF subset), plus *which adapter imported it, when, and under which signed operation*. Provenance is never summarized away — you can always reach the raw bytes the belief stands on. ### 3.3 Refuting a claim Refutation means "this is false, and I am telling you so": ```console $ fablepool refute --reason "I stopped attending in March" ``` The command prints a **cascade report** before returning: - the refuted claim, - every downstream claim that was **invalidated** (it depended essentially on the refuted claim), - every downstream claim whose **confidence was reduced** (it had other supporting inputs), - the operation id of your refutation, so you can find it later in the audit log. Refutations are dry-run-able. If you want to see the blast radius without committing: ```console $ fablepool refute --dry-run ``` Nothing is written in dry-run mode; the cascade report is computed and shown, then discarded. ### 3.4 Correcting a claim Correction means "the claim is wrong in a specific way; here is the truth": ```console $ fablepool correct --statement "I attend on Wednesdays, not Tuesdays" \ --reason "schedule changed" ``` A correction does two things atomically: it supersedes the old claim (status `corrected`, with a pointer to its replacement) and appends a new user-asserted claim with confidence 1.0 — user assertions outrank inference. The cascade then re-runs: downstream claims that depended on the old value are re-derived against the corrected one where the rule permits, and invalidated where it does not. The cascade report distinguishes **re-derived**, **invalidated**, and **weakened** outcomes. ### 3.5 Auditing and exporting ```console $ fablepool audit # full operation log, newest first $ fablepool audit --type refute # only your refutations $ fablepool audit --verify # re-check every signature and hash link $ fablepool export -o my-graph.fpwire ``` `export` writes the complete graph — evidence, claims, derivations, corrections, permissions — in the wire format defined in milestone 2. The export is self-contained and signed; another conforming implementation can ingest it. `audit --verify` exits non-zero if any operation fails verification, which makes it suitable for cron jobs and CI. --- ## 4. Reading the output ### 4.1 Confidence Confidence is a number in (0, 1]. The renderer buckets it visually: | Range | Label | Meaning in practice | |-------------|------------|--------------------------------------------------| | ≥ 0.90 | high | Multiple independent evidence paths agree. | | 0.70 – 0.89 | moderate | Solid single-source inference; worth a glance. | | 0.40 – 0.69 | tentative | Pattern detected but thin; treat as a suggestion. | | < 0.40 | weak | Usually only visible with `--all`. | A claim of confidence 1.0 is always a **user assertion** — something you stated directly via `correct`. The engine never assigns 1.0 on its own. ### 4.2 Status - `active` — currently believed. - `refuted` — you said it is false. Kept for the record, excluded from inference. - `invalidated` — a claim it depended on was refuted or corrected, and it could not survive re-derivation. - `corrected` — superseded; the listing shows `→ `. ### 4.3 Provenance trees `explain` renders the derivation as an indented tree. Each line is one node: claims show `id statement (confidence, rule)`, evidence leaves show `id source-adapter summary`. A `✗` marker on an input means that input has since been refuted or invalidated — which is exactly what you will see when you re-run `explain` on a downstream claim after a correction: the tree shows you *why* the cascade touched it. --- ## 5. Scripting and machine-readable output Every read command accepts `--json`, which switches output to one JSON document on stdout with no decoration. Mutating commands print their cascade report as JSON under `--json` as well. Schemas are stable within a minor version and documented in the CLI reference. ```console $ fablepool claims --topic schedule --json | jq '.claims[] | .id' $ fablepool refute c_3f9a --reason "wrong" --json | jq '.cascade.invalidated' ``` **Exit codes** are uniform across all commands: | Code | Meaning | |------|----------------------------------------------------| | 0 | Success. | | 1 | Domain error (unknown id, already refuted, etc.). | | 2 | Usage error (bad arguments; argparse convention). | | 3 | Integrity failure (`audit --verify` found a bad op).| Human-facing decoration (color, tables, tree glyphs) goes to stdout only in interactive mode; warnings and errors always go to stderr, so `fablepool ... --json 2>/dev/null | jq` is safe. The canonical end-to-end script is `scripts/demo_walkthrough.py`, which runs the full "what do you know about me and why → correct → watch the cascade" flow non-interactively and asserts on the outcomes. Use it as a template for your own automation. --- ## 6. Terminal compatibility and accessibility - **Color** is auto-detected. Set `NO_COLOR=1` (or pass `--no-color`) to disable it; all information conveyed by color is also conveyed by text labels, so nothing is lost. - **Unicode** tree glyphs degrade to ASCII when the terminal encoding is not UTF-8 (or with `--ascii`). Output remains line-oriented and screen-reader friendly: one fact per line, label before value. - **Width**: tables wrap rather than truncate identifiers; ids printed by one command are always valid inputs to the next, even on narrow terminals. - The interactive shell supports plain line editing everywhere Python's `readline` is available and falls back gracefully where it is not; no command *requires* the shell. --- ## 7. When something goes wrong | Symptom | Cause | Recovery | |---|---|---| | `unknown claim id` | Typo, or you used a short index outside the shell. | Re-list with `claims` and copy the full id; short indices only resolve inside one shell session. | | `claim already refuted` | Double refutation. | Nothing to do — the log already records your judgment. Use `claims --all` to see it. | | `cannot correct a refuted claim` | Refute and correct are exclusive endpoints. | If you have a replacement statement, the original should have been *corrected*, not refuted. Append the truth as a correction to the nearest active ancestor shown by `explain`. | | `audit --verify` exits 3 | An operation fails signature or hash-chain checks. | The log is tamper-evident, not self-healing: do not keep writing. Export what verifies, and restore from your other node (sync arrives in milestone 6). | | Output looks garbled | Terminal without UTF-8/color support. | `NO_COLOR=1 fablepool ... --ascii`. | | "I refuted the wrong claim" | Human error. | There is no delete — append a correction re-asserting the true statement. The audit log will honestly show both interventions, which is by design. | --- ## 8. FAQ **Why can't I just delete a claim?** Because the log is the trust anchor. A deletable log cannot be audited or synced safely. Refutation gives you the same practical outcome (the claim is excluded from all inference and hidden by default) while keeping the record honest. **Why did refuting one claim weaken, but not kill, another?** The downstream claim had other independent evidence paths. `explain` on the weakened claim shows the surviving inputs and the `✗`-marked one you removed. **Does correcting a claim retrain anything?** No. The derivation engine is deterministic rules over the graph. A correction changes an input; affected claims are mechanically re-derived. That is what makes the cascade explainable. **Can someone with my export see my raw evidence?** The full export (`export`) includes evidence — it is *your* complete graph for *your* backup and portability. Narrow, evidence-free sharing is the capability system, demonstrated in milestone 6. --- ## 9. Glossary - **Operation** — one signed, hash-chained entry in the append-only log. - **Evidence** — an imported raw record; a leaf in every provenance tree. - **Claim** — a derived or user-asserted statement about the user. - **Provenance** — the exact inputs and rule that produced a claim. - **Cascade** — mechanical re-evaluation of downstream claims after a refutation or correction. - **Refute** — assert a claim is false. - **Correct** — supersede a claim with a user-asserted truth. - **Wire format** — the interoperable serialization (milestone 2) used by `export`.