fusion-cli 1.1.0__tar.gz

fusion_cli-1.1.0/.gitignore

@@ -0,0 +1 @@
+src/fusion/_skills/

fusion_cli-1.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: fusion-cli
+Version: 1.1.0
+Summary: The Fusion reference CLI — the notary of the Fusion Convention.
+Author: Bluewaves Boutique
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# fusion — the notary of the Fusion Convention
+
+The reference CLI. It records, checks, and composes; it never judges —
+judgment belongs to the skill family. Buckets that follow
+[the convention](../SPEC.md) are Fusion whether or not this tool ever
+touches them.
+
+## Install
+
+One line, installs the CLI and the four skills into every agent that
+reads them:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/bluewaves-creations/fusion/main/install.sh | sh
+```
+
+Just the CLI, from PyPI:
+
+```sh
+uv tool install fusion-cli
+```
+
+From a clone:
+
+```sh
+git clone https://github.com/bluewaves-creations/fusion.git
+uv tool install ./fusion/cli
+fusion --version
+```
+
+## The nine commands (there is no tenth)
+
+| Command | Does |
+|---|---|
+| `fusion new <path>` | Scaffold a complete bucket + register it in the hub |
+| `fusion hub` | List / register (`add <path>`) / retire (`remove <name>`) buckets |
+| `fusion log <verb> <object>` | Append a ledger entry — the only writer. No args: read the ledger |
+| `fusion index [path]` | Regenerate `INDEX.md` in `library/` and `activities/` |
+| `fusion check [path]` | Audit a bucket against SPEC §11 — exit 1 on errors |
+| `fusion status [path]` | One bucket at a glance |
+| `fusion today` | The composed day, across every bucket in the hub |
+| `fusion agenda` | The wider horizon — dated and active, across the hub |
+| `fusion setup` | Install the skills into every detected agent — the installer's brain. `--remove` undoes it |
+
+Every command takes `--json` (agents parse, never scrape). `log`, `new`,
+and `index` take `--as <actor>`; the pen defaults to `FUSION_ACTOR`, then
+the OS username. `status` and `log` take `--since <date|last-reflection>`.
+`log` also takes `--bucket` (resolves the ledger; default: walk up from the current directory).
+The hub lives at `~/.fusion/hub.md` (`FUSION_HUB` overrides).
+
+## Development
+
+```sh
+cd cli
+uv run pytest        # the suite — golden tests run against ../examples/crazy-ones
+uv run fusion check ../examples/crazy-ones
+```

fusion_cli-1.1.0/README.md

@@ -0,0 +1,57 @@
+# fusion — the notary of the Fusion Convention
+
+The reference CLI. It records, checks, and composes; it never judges —
+judgment belongs to the skill family. Buckets that follow
+[the convention](../SPEC.md) are Fusion whether or not this tool ever
+touches them.
+
+## Install
+
+One line, installs the CLI and the four skills into every agent that
+reads them:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/bluewaves-creations/fusion/main/install.sh | sh
+```
+
+Just the CLI, from PyPI:
+
+```sh
+uv tool install fusion-cli
+```
+
+From a clone:
+
+```sh
+git clone https://github.com/bluewaves-creations/fusion.git
+uv tool install ./fusion/cli
+fusion --version
+```
+
+## The nine commands (there is no tenth)
+
+| Command | Does |
+|---|---|
+| `fusion new <path>` | Scaffold a complete bucket + register it in the hub |
+| `fusion hub` | List / register (`add <path>`) / retire (`remove <name>`) buckets |
+| `fusion log <verb> <object>` | Append a ledger entry — the only writer. No args: read the ledger |
+| `fusion index [path]` | Regenerate `INDEX.md` in `library/` and `activities/` |
+| `fusion check [path]` | Audit a bucket against SPEC §11 — exit 1 on errors |
+| `fusion status [path]` | One bucket at a glance |
+| `fusion today` | The composed day, across every bucket in the hub |
+| `fusion agenda` | The wider horizon — dated and active, across the hub |
+| `fusion setup` | Install the skills into every detected agent — the installer's brain. `--remove` undoes it |
+
+Every command takes `--json` (agents parse, never scrape). `log`, `new`,
+and `index` take `--as <actor>`; the pen defaults to `FUSION_ACTOR`, then
+the OS username. `status` and `log` take `--since <date|last-reflection>`.
+`log` also takes `--bucket` (resolves the ledger; default: walk up from the current directory).
+The hub lives at `~/.fusion/hub.md` (`FUSION_HUB` overrides).
+
+## Development
+
+```sh
+cd cli
+uv run pytest        # the suite — golden tests run against ../examples/crazy-ones
+uv run fusion check ../examples/crazy-ones
+```

fusion_cli-1.1.0/hatch_build.py

@@ -0,0 +1,50 @@
+"""Build hook: bundle the repo's skills/fusion-* into the wheel as
+fusion/_skills/. The repo's skills/ directory is the single source of
+truth; this hook re-stages it at every build, so the wheel cannot drift.
+
+Source resolution order:
+  1. <cli>/../skills   — normal repo build
+  2. <cli>/skills      — building from an sdist (the sdist hook below
+                         copies skills/ inside so wheel-from-sdist works)
+"""
+import shutil
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+EXCLUDE = ("tests", "__pycache__", ".pytest_cache")
+
+
+def _skills_source(root: Path) -> Path:
+    for candidate in (root.parent / "skills", root / "skills"):
+        if sorted(candidate.glob("fusion-*")):
+            return candidate
+    raise RuntimeError(
+        f"no fusion-* skills found beside {root} — cannot build fusion-cli"
+    )
+
+
+class SkillsBundleHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        src = _skills_source(root)
+        if self.target_name == "sdist":
+            # ship skills/ inside the sdist so a wheel built from it
+            # finds them via resolution order #2
+            build_data.setdefault("force_include", {})
+            for skill in sorted(src.glob("fusion-*")):
+                build_data["force_include"][str(skill)] = f"skills/{skill.name}"
+            return
+        staged = root / "src" / "fusion" / "_skills"
+        if staged.exists():
+            shutil.rmtree(staged)
+        for skill in sorted(src.glob("fusion-*")):
+            shutil.copytree(skill, staged / skill.name,
+                            ignore=shutil.ignore_patterns(*EXCLUDE))
+
+    def finalize(self, version, build_data, artifact_path):
+        staged = Path(self.root) / "src" / "fusion" / "_skills"
+        if staged.exists():
+            shutil.rmtree(staged)

fusion_cli-1.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "fusion-cli"
+version = "1.1.0"
+description = "The Fusion reference CLI — the notary of the Fusion Convention."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Bluewaves Boutique" }]
+dependencies = ["pyyaml>=6.0"]
+
+[project.scripts]
+fusion = "fusion.cli:main_entry"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fusion"]
+artifacts = ["src/fusion/_skills"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist.hooks.custom]
+path = "hatch_build.py"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fusion_cli-1.1.0/skills/fusion-analyst/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: fusion-analyst
+description: "The Fusion analyst — deliverables out of the bucket. Four gears: report (multi-section analysis from library + activities — the default), assess (scored assessment with explicit criteria and scale), compare (side-by-side matrix with deltas and red flags), export (CSV/JSON/XLSX data extracts). Everything lands in output/ as a summary-first document, cites every source path in data_sources, and ships signed in the ledger. Use for 'report on', 'analyze and write up', 'brief', 'assess', 'evaluate', 'score', 'compare X and Y', 'export as csv/excel'. For searching without producing a deliverable use fusion-librarian's query; for new documents of record use fusion-librarian's create. Applies only inside a Fusion bucket — a directory tree with BUCKET.md and LEDGER.md at its root; if there is no such bucket in play, this skill does not apply."
+license: MIT
+compatibility: "Requires the fusion CLI on PATH; uv for the export script (PEP 723: openpyxl)."
+---
+
+# fusion-analyst — the output
+
+Deliverables leave the bucket; their evidence never does. Every analyst
+document cites the exact paths it was built from, and ships with a
+`shipped` ledger entry.
+
+Read `references/fusion-conventions.md` once per session; read
+`BUCKET.md ## Conventions` before acting. No `BUCKET.md` up the tree and
+none named? Stop — this is not a Fusion bucket, and no Fusion skill
+applies (`fusion hub` lists the real ones).
+
+## Pick the gear
+
+| Signal | Gear | Load |
+|---|---|---|
+| report / analyze / write up / brief (default) | report | references/report.md |
+| assess / evaluate / score / rate | assess | references/assess.md |
+| compare / versus / side by side | compare | references/compare.md |
+| export / as csv / as excel / as json | export | references/export.md |
+
+## The output contract (all four gears)
+
+- Deliverables are documents in `output/` — frontmatter `title`, `type`,
+  `aurora` (usually `library` for reference-grade output, `commitments`
+  when it answers a promise), `created`, and **`data_sources`: the YAML
+  list of every bucket path the deliverable was built from.** No
+  uncited claims: if it isn't in a listed source, it is labelled as the
+  analyst's own inference.
+- Drafts live in `workbench/` while the human iterates; the finished
+  piece moves to `output/` (that move is the librarian's promote gear if
+  the human asks for the full ceremony, or written directly to `output/`
+  when the ask was a deliverable from the start).
+- Sign every deliverable:
+  `fusion log shipped "output/<path>" --bucket <root> --as <you>` ·
+  `fusion index <root>` · `fusion check <root>` green.
+
+## Never
+
+- Never invent data — the bucket is the evidence, `data_sources` is the
+  warrant.
+- Never overwrite an existing deliverable silently; new version, new
+  name, or an explicit yes.
+- Never hand-edit the registers.

fusion_cli-1.1.0/skills/fusion-analyst/references/assess.md

@@ -0,0 +1,12 @@
+# assess — scored, scaled, evidenced
+
+1. Subject + criteria + scale. No scale given → 1–5 integers
+   (1 very poor … 5 excellent) and SAY SO at the top of the document.
+2. Evidence per criterion from the bucket (paths kept for data_sources).
+   A criterion without evidence scores nothing — mark it "no evidence
+   in bucket" instead of guessing.
+3. Write `output/assessments/<slug>.md`: summary + `---` + scores table
+   (criterion · score · evidence path) + per-criterion rationale +
+   `## Sources`.
+4. `fusion log shipped … --bucket <root> --as <you>` · `fusion index <root>`
+   · `fusion check <root>`.

fusion_cli-1.1.0/skills/fusion-analyst/references/compare.md

@@ -0,0 +1,12 @@
+# compare — the matrix that shows its work
+
+1. Items + criteria (ask for criteria only if the obvious set is
+   ambiguous). Normalize units and scales before comparing; say when a
+   normalization changes a number's face.
+2. Matrix: criterion · item A · item B · delta. Below it: strengths,
+   weaknesses, and red flags (crippling conditions get named, not
+   averaged away).
+3. Inline answer for a quick question; `output/reports/<slug>.md` with
+   the full contract when it is a deliverable.
+4. Deliverable path: `fusion log shipped … --bucket <root> --as <you>` ·
+   `fusion index <root>` · `fusion check <root>`.

fusion_cli-1.1.0/skills/fusion-analyst/references/export.md

@@ -0,0 +1,18 @@
+# export — data that leaves as data
+
+1. Scope the rows: which documents, which frontmatter fields / table
+   columns. Collect into JSON: `{"headers": […], "rows": [[…], …]}`.
+2. Pipe through the script:
+
+   ```bash
+   echo '<json>' | uv run <skill>/scripts/export.py --format xlsx \
+     --output output/exports/<slug>.xlsx
+   ```
+
+   Formats: csv (default), json, xlsx.
+3. Write the companion document `output/exports/<slug>.md` — summary of
+   what the export contains + `resource:` naming the binary +
+   `data_sources` listing every source path. The binary is data; the
+   document is its passport.
+4. `fusion log shipped "output/exports/<slug>.xlsx" --bucket <root>
+   --as <you>` · `fusion index <root>` · `fusion check <root>`.

fusion_cli-1.1.0/skills/fusion-analyst/references/fusion-conventions.md

@@ -0,0 +1,149 @@
+# The Fusion Conventions — operator's card
+
+> Carried byte-identical by all four Fusion skills. SPEC.md in the Fusion
+> repository is normative; this card is the working summary. When they
+> disagree, SPEC.md wins and this card has a bug.
+
+**The contract:** the human judges, the AI operates, the files remember.
+
+**Liberal reader, strict writer.** Never refuse to read a bucket because
+something is missing or unknown. Never write into `library/`, `activities/`,
+`output/`, or a register without satisfying every rule below first.
+
+## The bucket
+
+```
+<bucket>/
+├── BUCKET.md        # identity card + learned conventions
+├── LEDGER.md        # append-only collaboration record
+├── inbox/           # drop zone — things arrive, nothing lives here
+├── sources/         # immutable originals + MANIFEST.md
+├── library/         # settled knowledge — documents
+├── activities/      # live work — documents + status
+├── workbench/       # ephemeral human+AI space — NO format rules
+└── output/          # finished deliverables — documents
+```
+
+- `sources/` is immutable: never modify, rename, or delete a registered file.
+- `workbench/` has no rules; leaving it (promotion) is a deliberate,
+  ledger-logged act.
+- Fusion holds knowledge and work, never media or code — documents point
+  (`resource:`) at big things, they never swallow them.
+- `output/` may also hold non-markdown deliverable files (exports); their
+  names are still lowercase-hyphen slugs with a lowercase extension.
+
+## Before acting — always
+
+1. Read `BUCKET.md`: the identity card, then `## Conventions` — `### Rules`
+   are how this bucket works; `### Delegations` are your standing autonomy
+   grants. They bind you.
+2. Triage through `library/INDEX.md` and `activities/INDEX.md` plus document
+   summaries before opening bodies.
+
+## The document format
+
+Every `.md` in `library/`, `activities/`, `output/` (except INDEX.md):
+
+```markdown
+---
+title: Human-readable name
+type: what-it-is        # open vocabulary, curated per bucket
+aurora: library         # one of the eight — closed set
+---
+
+## Summary
+
+Two or three lines a human or agent reads in two seconds.
+
+---
+
+Full body. Cross-links are plain relative markdown links.
+```
+
+- Required: `title`, `type`, `aurora` — exactly three.
+- Optional: `tags`, `created`/`updated` (ISO dates), `due` (ISO date the
+  thing falls due — `fusion agenda` surfaces it), `source` (path into
+  `sources/`), `resource` (URI or bucket path of the thing this document
+  describes), `status` (`active`|`done`|`dormant`, activities only),
+  `data_sources` (paths list, output only).
+- Body MUST be summary-first: `## Summary`, the lines, a `---` separator,
+  then everything else.
+- Filenames: lowercase, hyphen-separated, `.md`, stem ≤60 chars.
+- Preserve frontmatter keys you don't recognize.
+
+## Aurora — the eight (closed)
+
+| Aurora | Meaning |
+|---|---|
+| `commitments` | Obligations, promises, deadlines |
+| `focus` | Deep work, what deserves full attention |
+| `ops` | Operations, process, the recurring |
+| `collab` | Shared work, other people involved |
+| `life` | Personal, wellbeing, the non-work |
+| `explore` | Curiosity, research, the not-yet-settled |
+| `archive` | Done, kept, out of the way |
+| `library` | Reference, the settled knowledge |
+
+Aurora says what a document means for the human's attention — never invent
+a ninth value.
+
+## Archive
+
+No archive zone: archived items move to an `archive/` subfolder inside their
+zone AND take `aurora: archive`. Path is the truth, aurora is the signal —
+both, always.
+
+## The registers — single writers, no exceptions
+
+| File | Only writer | Your move |
+|---|---|---|
+| `LEDGER.md` | `fusion log` | `fusion log <verb> "<object>" [--note "…"] --as <you>` |
+| `library/INDEX.md`, `activities/INDEX.md` | `fusion index` | run it after any add/move/edit that changes titles or summaries |
+| `sources/MANIFEST.md` | fusion-intake's `scripts/convert.py` | everything enters `sources/` through the intake gate |
+
+Never edit these three files by hand — not with an editor tool, not with
+shell. The ledger verbs (closed set of eleven): `created`, `converted`,
+`classified`, `indexed`, `moved`, `promoted`, `archived`, `restructured`,
+`shipped`, `reflected`, `noted`. Sign with your agent name (`--as claude`,
+or set `FUSION_ACTOR`).
+
+## The CLI crib
+
+| Command | What it does |
+|---|---|
+| `fusion new <path>` | scaffold a conformant bucket |
+| `fusion hub [add\|remove]` | list / register / retire buckets |
+| `fusion log <verb> <object>` | append a signed ledger entry |
+| `fusion index` | regenerate INDEX files (logs `indexed` when changed) |
+| `fusion check [path]` | conformance: errors, warnings, honest exit codes |
+| `fusion status [--since …]` | one bucket at a glance |
+| `fusion today` | the composed morning across all hub buckets |
+| `fusion agenda` | dated + active items across buckets |
+| `fusion setup` | install/refresh the skills into detected agents |
+
+All take `--json`. `--since last-reflection` scopes to the current
+reflection window. **Exit gate for every skill scenario: `fusion check`
+green before you call the work done.**
+
+## When you're blocked
+
+- `fusion` not on PATH: stop and tell the human — the install is
+  `uv tool install ./fusion/cli` from a clone of the Fusion repository.
+  Never imitate the notary by hand: no register writes while the CLI is
+  missing.
+- `fusion check` red and you cannot fix it: stop, show the findings
+  verbatim, leave the bucket as it stands, and sign nothing that claims
+  the work is done. A bucket is a git repo — nothing is unrecoverable.
+- The human rejects a proposal: that is a result, not a failure. Record
+  it if the gear's protocol says to (`noted`), and move on.
+
+## The four accountabilities
+
+| Skill | Owns |
+|---|---|
+| fusion-intake | The gate. Everything that enters, enters through it. |
+| fusion-librarian | The order. Placement, curation, restructuring, reflection. |
+| fusion-planner | The horizon. Activities, agendas, what today looks like. |
+| fusion-analyst | The output. Deliverables that cite their sources. |
+
+One skill, one accountability — the ledger says which hat was worn.

fusion_cli-1.1.0/skills/fusion-analyst/references/report.md

@@ -0,0 +1,13 @@
+# report — from bucket to briefing
+
+1. Scope: topic, audience, depth. A "brief" is a report whose audience
+   is management: two pages, headline numbers first, no methodology.
+2. Gather: INDEX triage → grep → read the relevant documents. Keep the
+   list of every path you actually used — that IS `data_sources`.
+3. Write to `output/reports/<slug>.md` (or workbench first if the human
+   is iterating):
+   `## Summary` (the 2–3-line triage), `---`, then: Key findings
+   (numbers verbatim from sources) · Analysis · Recommendations ·
+   `## Sources` (path · contribution — mirrors data_sources).
+4. Close: `fusion log shipped "output/reports/<slug>.md" --bucket <root>
+   --as <you>` · `fusion index <root>` · `fusion check <root>`.

fusion_cli-1.1.0/skills/fusion-analyst/scripts/export.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["openpyxl>=3.1.0"]
+# ///
+"""fusion-analyst export: stdin JSON {"headers": [...], "rows": [[...]]}
+-> csv / json / xlsx on disk. Deterministic; the judgment (what to export)
+happened before the pipe."""
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="fusion-analyst data export")
+    ap.add_argument("--format", "-f", choices=("csv", "json", "xlsx"),
+                    default="csv")
+    ap.add_argument("--output", "-o", required=True)
+    args = ap.parse_args(argv)
+
+    payload = json.load(sys.stdin)
+    headers = payload.get("headers") or []
+    rows = payload.get("rows") or []
+
+    if headers:
+        bad = [i for i, r in enumerate(rows) if len(r) != len(headers)]
+        if bad:
+            print(f"export: row(s) {bad} have wrong length vs headers", file=sys.stderr)
+            return 1
+
+    out = Path(args.output)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    if args.format == "csv":
+        with open(out, "w", encoding="utf-8", newline="") as fh:
+            w = csv.writer(fh)
+            if headers:
+                w.writerow(headers)
+            w.writerows(rows)
+    elif args.format == "json":
+        records = ([dict(zip(headers, r)) for r in rows]
+                   if headers else rows)
+        out.write_text(json.dumps(records, indent=2, ensure_ascii=False),
+                       encoding="utf-8", newline="\n")
+    else:
+        import openpyxl
+        wb = openpyxl.Workbook()
+        ws = wb.active
+        ws.title = "export"
+        if headers:
+            ws.append(headers)
+        for r in rows:
+            ws.append(r)
+        wb.save(out)
+
+    print(json.dumps({"written": str(out), "rows": len(rows),
+                      "format": args.format}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fusion_cli-1.1.0/skills/fusion-intake/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: fusion-intake
+description: "The Fusion intake gate — everything that enters a bucket enters through it, losslessly. Classify what landed in inbox/ (new, updated, duplicate, conflicting), preserve the original in sources/ with its sha256 in the MANIFEST, convert to a faithful summary-first document (xlsx, csv, docx, pptx, pdf, html, images, .eml mail, markdown/text exports), propose type and aurora, sign the ledger, clear the inbox. Use when the user says 'process the inbox', 'intake', 'ingest', 'convert this file', or drops files into a Fusion bucket's inbox/. For placement, curation, or restructuring of what is already inside, use fusion-librarian; for deliverables out of the bucket, use fusion-analyst. Applies only inside a Fusion bucket — a directory tree with BUCKET.md and LEDGER.md at its root; if there is no such bucket in play, this skill does not apply."
+license: MIT
+compatibility: "Requires the fusion CLI on PATH and uv. LibreOffice (soffice on PATH) required for docx/pptx/legacy office/html formats — fails fast when missing, never silently degrades. Script deps via PEP 723 (openpyxl, PyYAML, pymupdf)."
+---
+
+# fusion-intake — the gate
+
+Nothing enters the library except through the gate. The gate preserves
+originals forever, converts losslessly, and asks before it acts on anything
+that isn't clean and new.
+
+Read `references/fusion-conventions.md` once per session. Then, before
+touching anything: read the bucket's `BUCKET.md` — `## Conventions` may
+contain filing rules and standing delegations that bind this whole run.
+No `BUCKET.md` up the tree and none named? Stop — this is not a Fusion
+bucket, and no Fusion skill applies (`fusion hub` lists the real ones).
+
+## The pipeline
+
+```
+inbox/ ─► STAGE 1 gate (scripts/gate.py)      deterministic: hash, similarity
+              │        six buckets → gate-<runid>.json
+              ▼
+          STAGE 2 gate (references/gate.md)   judgment: final class + intake report
+              │        new → auto-proceed · exact dup → auto-skip
+              │        near-dup / updated / conflicting → ASK FIRST
+              ▼
+          ADMIT + CONVERT (scripts/convert.py) original → sources/ + MANIFEST row
+              │        xlsx/csv finish here; everything else stages pages
+              ▼
+          STAGE 2 convert (references/convert.md)  vision reconstruction,
+              │        fidelity checklist, summary, type + aurora
+              ▼
+          CLOSE       link MANIFEST → fusion log → fusion index → fusion check
+                      admit already moved the original into sources/ —
+                      close just needs the register trail green
+```
+
+## Running it
+
+`admit`, `prepare`, `link`, `unpack`, and `gate.py` take the bucket root as
+`--bucket`; `cleanup` takes only `--run-dir` — resolve it against the
+bucket root before calling (the manifest's `run_dir` is bucket-relative).
+`<skill>` is this skill's directory.
+
+A delivery — a container or folder holding dozens to hundreds of files
+arriving together — walks this same pipeline, but its mechanical halves
+(admit, link) run once each as a single validated batch instead of one
+call per file: `convert.py batch --bucket <root> --ops <ops.json>`. Read
+`references/delivery.md` for the full protocol (dedupe, per-folder
+categories on basename collision, batch schema) before working a
+delivery.
+
+Containers (`.zip`, `.athena`) are delivery vehicles, not originals:
+`uv run <skill>/scripts/convert.py unpack --bucket <root> --file <name>`
+extracts one beside the container (`inbox/<stem>/` for top-level drops)
+and deletes the container — the members become the originals, signed
+`noted` in the ledger — then gate the contents normally (step 1).
+
+1. **Classify:** `uv run <skill>/scripts/gate.py --bucket <root>`
+   → read the printed manifest path, then load `references/gate.md` and
+   follow it to the intake report. Stop for confirmation where it says stop.
+2. **Admit** each approved file:
+   `uv run <skill>/scripts/convert.py admit --bucket <root> --file <name> --category <cat> --actor <you>`
+   Category follows the bucket's filing rules (BUCKET.md), else a short
+   plural noun (`reports`, `mails`, `gear`). The MANIFEST row is the
+   script's job — never edit MANIFEST.md yourself.
+3. **Prepare:**
+   `uv run <skill>/scripts/convert.py prepare --bucket <root> --source <cat>/<name> [--dest …] [--slug …] [--type …] [--aurora …] [--reconcile]`
+   Extractive files (`done: true`) are already conformant documents.
+   Everything else returns a work-dir manifest — load
+   `references/convert.md` and reconstruct. `--reconcile` (with the
+   existing doc's `--dest`/`--slug`) is the confirmed-update path —
+   prepare refuses an existing destination without it.
+4. **Close** (per file): refine the document summary if it's the
+   deterministic placeholder, then — admit already moved the original into
+   `sources/`, so closing is just the register trail:
+   `uv run <skill>/scripts/convert.py link --bucket <root> --source <cat>/<name> --doc <zone-rel-doc>`
+   `fusion log converted "sources/<cat>/<name> → <doc>" --bucket <root> --as <you>`
+   `fusion index <root>` · `fusion check <root>` — green, then
+   `cleanup --run-dir <dir>`. Nothing remains in inbox for this file.
+
+## The four classes (locked)
+
+| Class | Meaning | Action |
+|---|---|---|
+| new | nothing matches | auto-proceed |
+| duplicate — exact | byte-identical to a source | auto-skip, recorded |
+| duplicate — near | re-export / trivial edit | ASK: skip / update / new |
+| updated | newer version of an existing source | ASK, then supersede |
+| conflicting | claims contradict the library | ASK — the gate never picks a winner |
+
+Four classes — `duplicate` splits into exact (auto-skip) and near (ask).
+
+The four classes cover matches against `sources/`; the same bytes dropped
+twice within one inbox batch are reported separately as `inbox_dups` and
+cleaned per the bucket's rules (`references/gate.md`).
+
+**Supersede, the Fusion way:** `sources/` is immutable — a confirmed update
+ADMITS THE NEW FILE as its own source (rename it first if the name
+collides) and RECONCILES the existing library document in place
+(`prepare --reconcile`): same path, content updated, `updated:` bumped,
+`source:` repointed to the new original. One document, no `-v2` twin.
+The old original stays in `sources/` and the MANIFEST, superseded but
+never erased.
+
+## The fidelity contract (lossless, non-negotiable)
+
+- The original lands in `sources/` byte-identical, full sha256 in MANIFEST.
+- Every page is accounted for (`page_count == len(pages)`); a page the
+  text layer can't cover is flagged `needs_vision` and YOU read its image.
+- Tables: every row, every column. Numbers verbatim — never rounded,
+  never paraphrased. Figures get a one-line caption.
+- Doubtful fidelity (blurry scan, unreadable region)? If caught BEFORE
+  admit, the file simply stays in inbox. If caught AFTER admit, the
+  original is already safe in `sources/` — withhold the document instead
+  (or flag the gap loudly inside it) and leave the MANIFEST row unlinked
+  (`—`) until the human decides. A lossy conversion is a failed conversion.
+- Close only after MANIFEST link + ledger + green `fusion check`.
+
+## Never
+
+- Never modify, rename, or delete anything in `sources/`.
+- Never hand-edit `MANIFEST.md`, `LEDGER.md`, or any `INDEX.md`.
+- Never convert a near-dup, update, or conflict without a yes.
+- Never leave a converted file's ledger entry unsigned.