ctxr-cli 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,14 @@
 # Contexture (`ctxr`)
 
-The structured context platform for the organization — a context store that ingests, organizes, and retrieves context for any AI agent harness (Claude Code, Codex, Cursor, Cline, Gemini CLI, a cron job, a human at a terminal).
+[![npm](https://img.shields.io/npm/v/ctxr-cli)](https://www.npmjs.com/package/ctxr-cli) [![CI](https://github.com/ayxuerui/contexture/actions/workflows/ci.yml/badge.svg)](https://github.com/ayxuerui/contexture/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/ctxr-cli)](LICENSE)
+
+**Your agents' long-term knowledge — they write it, you review it before it lands.**
+
+Contexture turns a git repository into shared, durable knowledge, and ships the operating procedures an AI agent needs to work it: what to do with a new source, where a note belongs, when a synthesis has gone stale, how a change gets reviewed and landed. Every write lands the way code does — in a branch, past a health check, through a pull request you approve.
+
+This is one layer of agent memory — the shared one. Your harness keeps what an agent knows about you and itself; contexture keeps what *you* know, reviewed and versioned, outliving any single agent or session. Claude Code, Codex, Cursor, Cline, Gemini CLI, a cron job, or you at a terminal all operate the same store through the same files.
+
+A **store** is an ordinary git repository: markdown notes joined by `[[wikilinks]]`, with `contexture.yaml` as the single source of truth for how that particular store is shaped — its taxonomy, its paths, its relation vocabulary. `ctxr` is a mechanism-only CLI over it — it builds indexes, enforces invariants, and performs validated writes, but it makes no editorial decisions. The judgment lives in **skills**: portable markdown decision procedures that `ctxr init` installs into the store, which whatever agent you're talking to reads and follows. That split is the whole design, and it's what makes the same store operable from any harness.
 
 ## Install
 
@@ -8,36 +16,319 @@ The structured context platform for the organization — a context store that in
 npm install -g ctxr-cli
 ```
 
-The npm package is `ctxr-cli`, the executable it installs is `ctxr`, and the project is Contexture. Everything a store contains keeps the project name — `contexture.yaml`, the `.contexture/` home directory, `CONTEXTURE_*` environment variables — while `ctxr` is what you type. A `contexture` alias executable is also installed for compatibility; docs and generated files always say `ctxr`.
+Requires Node 22.13 or newer.
+
+The package is `ctxr-cli`, the command it installs is `ctxr`, and the project is Contexture — which is why a store’s own files keep the full name (`contexture.yaml`, `.contexture/`, `CONTEXTURE_*`). A `contexture` alias executable is installed too; docs and generated files always say `ctxr`.
+
+## Quickstart
+
+```sh
+mkdir my-store && cd my-store
+ctxr init
+ctxr adapters generate   # writes the harness entry file (CLAUDE.md) and its permission config
+```
+
+`ctxr init` asks two questions, then creates the git repository (if there isn't one), scaffolds the store, and commits it:
+
+- **Which taxonomy profile?** `para` (Projects / Areas / Resources / Archives — the default), `zettelkasten` (no layers at all; structure emerges from links), or `diataxis` (Tutorials / How-to / Reference / Explanation). Or bring your own layer list with `--taxonomy <file.yaml>`.
+- **Which agent harnesses?** `claude-code` (default — its adapter generates `CLAUDE.md` plus a `.claude/settings.json` wiring up the write-gate hook) and/or `hermes-agent` (reads `AGENTS.md` directly, so it needs no entry file at all). `--harness none` opts out.
+
+Harness adapter output is the one part `init` doesn't write itself, which is why `ctxr adapters generate` is a separate line above; `ctxr update` regenerates it from then on.
+
+Non-interactively, pass them as flags — nothing ever blocks on a prompt:
+
+```sh
+ctxr init --profile para --harness claude-code
+```
+
+`init` is idempotent. Re-running it against an existing store reconciles it instead (the same code path as `ctxr update`) rather than overwriting anything.
+
+## What a store looks like on disk
+
+After `ctxr init --profile para`, plus `ctxr adapters generate`:
+
+```
+contexture.yaml               single source of truth — what this store chose; the rest takes shipped defaults
+AGENTS.md                     generated entry document — six managed sections
+CLAUDE.md                     harness entry file; a one-line managed import of AGENTS.md
+.claude/
+  settings.json               PreToolUse hook wiring for the write gate
+  hooks/                      the write-gate shim
+  skills/ -> ../.agents/skills   a bridge, so Claude Code auto-discovers the canonical skills
+.agents/skills/               THE canonical skills location, read natively by most harnesses
+  ctxr-*/SKILL.md               13 contexture-owned skills (refreshed by `ctxr update`)
+  frontend-design/, eli5/       vendored third-party skills, with licenses and provenance
+.contexture/guidance/
+  house-conventions.md        your store's own rules — inlined into AGENTS.md verbatim
+  mission.md                  the standing "what's active right now" document
+.githooks/
+  pre-commit                  runs `doctor --staged`
+  pre-push                    refuses a push to the default branch
+projects/ areas/ resources/ archives/     the taxonomy's layers
+raw/inbox/                    where captured material lands, before ingest
+```
+
+These appear the first time they're needed rather than at init:
+
+```
+raw/<YYYYMM>/                 retained captures, one directory per month of ingest
+.contexture/catalog/*.md      one section per layer, plus uncategorized — tracked in git
+.contexture/publish/          published pages
+.contexture/cache/            gitignored — graph.json and the human-readable graph.md
+.worktrees/                   gitignored — session worktrees
+```
+
+Two distinctions make the rest of this readable:
+
+**Derived vs. authored.** Never hand-edit inside a `contexture:<region>` fence — the next build overwrites it. Edits *outside* a fence survive every rebuild, and that's where they belong: the catalog generates each note's entry line but preserves the one-line gloss you write next to it, forever.
+
+**`.contexture/` is not content, and neither is `raw/`.** The store's own home directory, the skills directory, and the worktrees path are excluded from every retrieval leg by default (`retrieval.exclude_paths`), so the store's plumbing never shows up as an answer to a question about the store's subject matter. `raw/` — the capture tier — is excluded for a different reason: what arrived is not yet what you know. It is tracked in git all the same, because a retained capture is the provenance behind a note.
+
+## How agents drive it
+
+`ctxr init` writes two things an agent reads, both generated from your store's own config — never from a hardcoded layout:
+
+**`AGENTS.md`**, with six managed sections: *Store fundamentals* (root resolution, the frontmatter schema, the write path), *Mission*, *Retrieval: which leg to use*, *Capturing and ingesting*, *Placing a new note* (rendered from your actual taxonomy layers), and *Store conventions*.
+
+**The skills**, installed as full copies at `.agents/skills/ctxr-<name>/SKILL.md`. That path is the cross-harness canonical location; a harness that reads its own branded directory instead gets that directory bridged to it (`.claude/skills/` is a symlink), so skill auto-discovery works with no wrapper and no second copy. A harness without auto-discovery reaches the same file by path from `AGENTS.md`. They're contexture-owned — refreshed by `ctxr update`, never hand-edited — and they're written against *your* store's configured taxonomy and relation vocabulary, so no shipped profile's layer names leak into them. Your own skills live alongside, untouched by sync.
+
+| Skill | What it decides |
+| --- | --- |
+| `ctxr-ingest-orchestration` | What the store should know after a source — not where to file it |
+| `ctxr-placement` | Which layer and location a note belongs in, and why |
+| `ctxr-connection-finding` | Traversing links that already exist |
+| `ctxr-connection-proposal` | Discovering links a note *should* have |
+| `ctxr-rollup` | Synthesizing an entity's current state from every note referencing it |
+| `ctxr-mission` | Keeping the store's priorities / back burner / debt document current |
+| `ctxr-organize-audit` | Placement review, retiring, classifying broken links |
+| `ctxr-derived-artifacts` | Rebuilding catalog, graph, and generated docs without clobbering them |
+| `ctxr-publish` | Whether a subject earns a page, and what may appear on it |
+| `ctxr-session-lifecycle` | Starting a session, re-scanning, conflicts, sequencing several PRs |
+| `ctxr-submit` | Everything up to and including opening the pull request |
+| `ctxr-land` | Merging after review, and reclaiming the worktree |
+| `ctxr-session-capture` | What a finished session produced that is worth keeping |
+
+Your house rules go in `.contexture/guidance/house-conventions.md`. It's inlined into `AGENTS.md`'s *Store conventions* section in full, so it loads for every harness at the start of every session — there's no separate file an agent has to remember to open.
+
+## A session, end to end
+
+This is the loop you actually live in: start a session, talk to the agent, publish, submit, land.
+
+```mermaid
+flowchart LR
+  S["1 · ctxr session start<br/><small>new worktree</small>"]
+  C["2 · chat with the agent<br/><small>AGENTS.md + skills</small>"]
+  K["3 · capture<br/><small>approve by ID</small>"]
+  P["4 · publish<br/><small>optional</small>"]
+  U["5 · submit<br/><small>doctor, commit, PR</small>"]
+  R(["review"])
+  L["6 · land<br/><small>merge, reclaim</small>"]
+
+  S --> C --> K --> P --> U --> R --> L
+
+  G1["write-gate hook"]
+  G2["pre-commit · pre-push"]
+  C -.- G1
+  U -.- G2
+
+  classDef gate fill:#fbfbfb,stroke:#bbb,stroke-dasharray:4 3,color:#666
+  class G1,G2 gate
+```
+
+
+**1. Start.** `ctxr session start` creates a git worktree on a generated `session/…` branch off a freshly fetched `origin/<default-branch>`, and prints its path:
+
+```
+Session worktree at "/path/to/my-store/.worktrees/session-20260903-060120-5ccbd6"
+on branch "session/20260903-060120-5ccbd6" (from master).
+```
+
+With no remote configured it falls back honestly to the local branch tip rather than failing. `cd` there and open your agent. Never work in the canonical clone — `ctxr session list` shows what's active. (The default branch is whatever `git init` actually created, recorded once at init; nothing hardcodes `main`.)
+
+**2. Chat.** Your harness loads `AGENTS.md` — or `CLAUDE.md`, which imports it — at session start, and discovers the skills through the bridged directory. Describe what you want in plain language: *"read this article and file it"*, *"what do we know about Acme"*, *"roll up this entity"*, *"make me a page comparing these three"*. The agent picks the skill. There's nothing to memorize; the [knowledge loop](#the-knowledge-loop) below is what it runs on your behalf, documented for when you want to drive a step yourself.
+
+**3. Wrap.** On *your* closing signal — "done", "ship it", a sign-off; never the agent's own summary — `ctxr-session-capture` fires exactly once. It proposes, in a single message with IDs, what the session produced that is durable, split by kind: a **fact** about what happened becomes a store note, a **rule for future work** becomes a house convention. Nothing is written until you approve by ID. Approved notes go through:
+
+```sh
+ctxr session capture --proposal approved.yaml
+```
+
+```yaml
+notes:
+  - id: A1
+    path: resources/Acme.md
+    mode: create          # or: append
+    frontmatter:
+      title: Acme
+    body: |
+      # Acme
+```
+
+Each item is validated and applied independently, so one bad path refuses that item alone rather than the whole proposal. Approved *conventions* aren't notes — they're a direct edit to `house-conventions.md` followed by `ctxr update`, staged in the same commit. (A guidance edit without the matching `AGENTS.md` regeneration fails `doctor --staged`, and the pre-commit hook refuses it.)
+
+**4. Publish**, if the session earned a page. Run it before submit so the page rides the same pull request. See [Express](#5-express--publish-a-page) below.
+
+**5. Submit.** `ctxr-submit`: re-scan git state (never replay a plan from an earlier snapshot), run the capture pass, stage surgically with `git add <paths>` — never `-A`, and derived cache paths never stage — then `ctxr doctor` over the whole store, not `--staged`: a session's job is to leave the *store* healthy, not merely to pass one commit's gate. Then commit, rename the generated branch to something meaningful before it reaches the forge, `git push -u origin <branch>`, and `gh pr create`. If `gh` has no reachable GitHub remote, the push still succeeds on its own and you get manual pull-request instructions instead of a retry loop.
+
+**6. Land.** `ctxr-land`, after review: name the pull request explicitly rather than inferring it from whichever checkout you're standing in, read its state and mergeability with `gh pr view`, then wait for an explicit go — plan consent is not fire consent. `gh pr merge --squash`, then re-read state to confirm the forge reports `MERGED`; a transport error can arrive after a merge already succeeded, so the exit code alone is never enough. Finally fast-forward the canonical clone (`git fetch origin && git merge --ff-only`) and reclaim the worktree (`git worktree remove`, `git branch -d`) — nothing sweeps up afterward, so a worktree left here is left indefinitely.
+
+`ctxr-session-lifecycle` covers what surrounds both halves: when to re-scan, the conflict playbook, and sequencing several pull requests.
+
+### Why steps 5 and 6 aren't CLI commands
+
+They're ordinary `git` and `gh`. The CLI owns only what git cannot do — creating the worktree, applying validated note writes, running the health gates — and the sequencing, the confirmation gates, and the judgment live in the skills, where you can read and change them. That's why `ctxr session` has exactly three subcommands: `start`, `capture`, and `list`.
+
+Three mechanical backstops hold the line underneath all of it: the **pre-commit** hook runs `doctor --staged`; the **pre-push** hook refuses a push to the default branch (`CONTEXTURE_ALLOW_DEFAULT_BRANCH_PUSH=1` is the emergency override, for emergencies); and for Claude Code the **write-gate** PreToolUse hook denies any edit under the store root made outside the active session worktree.
+
+## The knowledge loop
+
+What the agent is doing inside step 2 — and how to drive any of it by hand.
+
+Four of these are the moves knowledge work is made of: **capture** what arrives, **organize** it so it stays navigable, **distill** it into something that answers a question, **express** it for a reader who wasn't there. Retrieval isn't a stage — it's what makes the other four worth doing — but it sits second here because it's the one you reach for constantly.
+
+### 1. Capture — get material in without duplicating it
+
+Capture is just writing the material into `raw/inbox/`; no CLI wraps it. It may already carry `source_type` and `source_id` — whatever fetched it usually knows them — but never `source_hash` or `ingested`, which contexture assigns once, at ingest. Then:
+
+```sh
+ctxr source check raw/inbox/note.md --source-id https://example.com/a
+# ...read the cluster, decide, write or extend the note...
+ctxr ingest raw/inbox/note.md --into resources/topic.md --source-type article --source-id https://example.com/a
+```
+
+`source check` returns one of five verdicts: `new`, `already_ingested`, `drift` (same source, its content moved — read what changed before deciding), `alternate_source_match` (this content is already here under a different identity), or `multiple_matches` — which exits non-zero and means *stop and resolve the ambiguity yourself*, never guess which existing record it is. URLs are canonicalized first, with tracking parameters stripped (`ingest.tracking_params`). `ctxr source stamp` backfills a record with no hash on file; `ctxr source add-alt` records material re-published at a new URL, rather than ingesting it twice.
+
+`ctxr ingest` stamps the four identity fields **onto the capture**, moves it out of the inbox into `raw/<YYYYMM>/`, records its path in the destination note's `sources` list, and rebuilds the catalog. The note carries no source identity of its own, which is what lets it be rewritten, merged or restructured without invalidating the frozen hash — and what lets one note cite the several captures it was built from. `--into` is required: ingest never creates the note, because deciding what the store should know is the work.
+
+Material that isn't markdown can't carry frontmatter, so it travels with a markdown sidecar naming it in `capture_file`; the hash is taken over that file's bytes and the two move together.
+
+The commands are the easy part. `ctxr-ingest-orchestration` exists because ingest is **synthesis, not filing** — "create a new note" is one option among several, and the skill's decision table (new note / expand an existing one / merge two / restructure / add a section to a hub) is the actual work. Every row of that table ends in the same `ingest` call, so provenance is recorded whichever one you take. `ctxr-placement` decides where the result lives, and says why.
+
+### 2. Retrieve — three legs, no ranker
+
+```sh
+ctxr catalog show --section projects      # curated index, one section per layer
+ctxr graph build                          # then query it, or read .contexture/cache/graph.md
+ctxr graph query neighbors <path> --depth 2
+ctxr graph query hubs
+ctxr graph query orphans
+```
+
+The **catalog** is coverage-guaranteed: every retrievable note has exactly one section, so nothing is silently unindexed. Section ids are your layer paths plus `uncategorized` (or a single `notes` section under a zero-layer profile). The **graph** enumerates structure and ranks nothing — neighbors, shortest path, hubs, clusters, bridges, orphans; `--type <relation>` follows one configured relation. `graph build` also writes a human-readable `graph.md` summarizing hubs by cluster. The third leg is **your own grep**, for literal strings the first two can't answer, scoped to exclude `.contexture/`.
+
+There is no `ctxr search`, and no semantic ranking. That's deliberate, not missing.
+
+→ `ctxr-connection-finding` (traverse what exists), `ctxr-connection-proposal` (discover what should).
+
+### 3. Organize — keep it navigable as it grows
+
+```sh
+ctxr lint          # observations — orphans, broken links, material still in the inbox; always exits 0
+ctxr doctor        # invariants — exits non-zero, and gates every commit
+ctxr catalog check --stale
+ctxr archive <path>
+```
+
+The `lint` / `doctor` split is the point: lint reports what's *worth reviewing* and never blocks; doctor reports what's *broken* and does. `ctxr archive` retires a note as a single tracked rename into `organize.archive_destination`, leaving its frontmatter byte-identical and reporting every note that linked to it — move it, don't tag it, or the active layers stop meaning anything. (The note must be committed first; archive won't rename something git isn't tracking.)
 
-## Usage
+→ `ctxr-organize-audit`, `ctxr-derived-artifacts`.
+
+### 4. Distill — rollups and the mission document
 
 ```sh
-ctxr init                 # create a store (or reconcile an existing one)
-ctxr doctor               # check the store's invariants
-ctxr catalog show         # the curated index of retrievable notes
-ctxr graph build          # rebuild the wikilink graph
-ctxr graph query hubs     # ...and query it
-ctxr session start        # every write lands via a session worktree and a PR
-ctxr --help               # the full command list
+ctxr rollup stale                                   # entities whose backlinks moved since last synthesis
+ctxr rollup gather <entity>                         # enumerate the source notes
+ctxr rollup write <entity> --content-file draft.md  # idempotent fenced write
 ```
 
-Every command accepts `--root <path>` (or `CONTEXTURE_ROOT`) and `--json`.
+Gather and write are deterministic; the synthesis in between is the agent's, over *every* source rather than a sample. The write only ever touches the fenced region — hand-written content elsewhere in the note is never disturbed, and re-writing identical content reports `changed: false` and leaves the file byte-identical.
+
+The store's own `.contexture/guidance/mission.md` uses the same write path, but is reported stale on elapsed time (`organize.rollup_stale_days`) rather than on backlinks.
+
+→ `ctxr-rollup`, `ctxr-mission`.
+
+### 5. Express — publish a page
 
-## Releasing
+```sh
+ctxr publish gather --under resources/    # or --note <path>, or --entity <name>
+ctxr publish new comparison               # scaffolds the page folder and its sibling README
+ctxr publish check .contexture/publish/comparison
+```
 
-Publishing to npm is automated: merging to `main` publishes whenever `package.json`'s version isn't
-already on the registry, via [`.github/workflows/release.yml`](.github/workflows/release.yml).
-Ordinary merges are a no-op — only a version bump triggers a publish.
+`gather` resolves a subject to its note set — never a hand-picked list, which is how an unintended note slips onto a page unnoticed. `check` runs the structural gates: no external references, viewport meta, a print rule, provenance, the sibling README, script syntax. What a page may *contain*, given who will read it, is a judgment `ctxr-publish` walks you through and no check can make.
 
-To cut a release:
+→ `ctxr-publish`, plus the vendored `frontend-design` and `eli5` skills for the craft contexture supplies none of.
+
+## Reading a store in a browser
 
 ```sh
-git checkout -b chore/release-X.Y.Z
-npm version X.Y.Z --no-git-tag-version   # bumps package.json and package-lock.json together
-# hand-edit src/version.ts's CLI_VERSION to match X.Y.Z
+ctxr serve
 ```
 
-Open a PR and merge it. The workflow then builds, tests, publishes to npm (via trusted publishing —
-no stored token), tags the commit `vX.Y.Z`, and creates a GitHub Release. `test/unit/version-sync.test.ts`
-guards against `CLI_VERSION` drifting from `package.json`'s version on every PR.
+Renders notes, catalog sections, the graph document, and published pages as cross-linked HTML. It binds loopback (`127.0.0.1`) by default. `--host` widens that, but note what it does not change: `serve` applies **no per-requester filtering at any bind address**. Widening it exposes the whole store to whatever can reach that address, so only do it behind a front end you've arranged yourself.
+
+A published page's navigation label follows its own declared `<title>`, falling back to its folder name when it declares none. The header's light/dark/system links choose a display theme, and the ☰ control shows and hides the navigation — both persist across pages via cookies, and neither requires client-side script. A published page itself is still served byte-verbatim, so neither the theme nor the navigation reaches into it; `ctxr publish new`'s scaffold instead follows the viewer's own system preference on its own.
+
+## Keeping a store current
+
+```sh
+ctxr version           # the installed version, and where it is installed from
+ctxr version --check   # compare it against the latest published release
+ctxr update            # refresh every contexture-owned file to the installed version
+ctxr verify --portable # prove the store works from a harness with no harness-specific state
+```
+
+`ctxr update` re-renders the `AGENTS.md` sections, skill copies, hooks, and adapter outputs — run it after upgrading the CLI, and after editing your house conventions.
+
+### Upgrading the CLI
+
+`ctxr session start` and `ctxr update` check whether a newer release has been published and say so, once per session and once per update. The notice goes to stderr and appears as an `info` finding in `--json` output; it never changes either command's exit code, and a registry that is slow, unreachable, or behind a proxy simply produces no advice rather than a failure. `ctxr doctor` and `ctxr init` never make the request at all — a commit must not depend on the network, and `init` stays offline.
+
+The `ctxr-upgrade` skill performs the upgrade: it reads the live answer, refuses to instruct a global install when the executable it finds is a linked working copy, asks before changing anything, and re-renders the store *after* the package upgrade rather than before. By hand, that is `npm install -g ctxr-cli@latest` followed by `ctxr update`, in that order.
+
+To turn the check off, set `update_check.enabled` to `false` in `contexture.yaml`, or set `CONTEXTURE_UPDATE_CHECK=0` for a single invocation. `update_check.ttl_hours` sets how long a resolved answer is reused (a day by default); the cache lives in the store's gitignored `.contexture/cache/`.
+
+`schema_version` in `contexture.yaml` versions *store state* — the config shape and frontmatter conventions — as a monotonic integer independent of the npm package version. contexture ships no migration mechanism, so the number is a gate: a store whose recorded version is not the one your CLI supports is refused rather than half-read, in **either** direction. Newer, because the CLI cannot know that shape; older, because it no longer reads it. A release that changes the store's shape bumps the version and documents the one-time fixup in its release notes.
+
+### The config records decisions, not values
+
+A generated `contexture.yaml` is short, and that's the design: **any key it doesn't declare takes contexture's shipped default.** So everything the file *does* contain is a choice someone made, and a store that simply agrees with a convention follows it as the convention improves — a later release that changes a shipped default reaches every store that never overrode it, with no edit to its config file.
+
+Three kinds of key are always written out, because no constant could be right for them:
+
+- **Store facts** — `taxonomy`, and `git.default_branch`, which records whatever branch your repository actually uses rather than a guess.
+- **Taxonomy-derived** — `organize.archive_destination`, resolved from the profile at init. Defaulting it to a flat constant would send a PARA store's archived notes to `archive/` while its own taxonomy declares `archives/`.
+- **Opt-ins** — `organize.mission_path`, where *not* declaring the key is what says the store has no mission document.
+
+To pin a value against a future default change, declare it. Nothing rewrites what you declared: `ctxr init` against a directory with no configuration is the only thing that ever writes `contexture.yaml`, and reconciling an existing store leaves the file alone.
+
+## Command reference
+
+| Command | What it does |
+| --- | --- |
+| `init` | Create a store, or reconcile an existing one |
+| `doctor [--staged]` | Check real invariants; non-zero on any failure |
+| `lint` | Health observations; always exits 0 |
+| `catalog build \| check \| show` | Build, verify coverage, print a section |
+| `graph build` | Rebuild the wikilink graph and its document |
+| `graph query …` | `neighbors`, `path`, `subgraph`, `hubs`, `clusters`, `bridges`, `orphans` |
+| `ingest <path> --into <note>` | Retain a capture with its source identity, and cite it from a note |
+| `source hash \| check \| stamp \| add-alt` | Dedupe and source identity, ahead of ingest |
+| `archive <path>` | Retire a note via one tracked rename |
+| `entry append <path>` | Append a line into a `contexture:<region>` fenced region |
+| `rollup gather \| write \| stale` | Entity synthesis: enumerate, write, find what's out of date |
+| `publish gather \| new \| check` | Resolve a subject, scaffold a page, run the structural gates |
+| `session start \| capture \| list` | Session worktrees, and applying an approved capture proposal |
+| `adapters generate \| write-gate` | Regenerate harness outputs; the write-gate hook target |
+| `serve` | Read the store in a browser |
+| `update` | Bring contexture-owned files up to the installed version |
+| `version [--check]` | Report the installed version; `--check` compares it against the latest published release |
+| `verify [--portable]` | Exercise core store operations end to end |
+
+Every command accepts `--root <path>`, `--json`, and `--no-input`. The store root resolves in exactly one order: `--root`, then `CONTEXTURE_STORE_ROOT`, then walking up from the current directory looking for `contexture.yaml`. Nothing else selects it.
+
+Exit codes are a fixed taxonomy, so scripts and hooks can rely on them: `0` success, `1` an internal error (a bug), `2` a usage error (bad arguments, no store root, not a git repository), `3` a check that ran correctly and found a real problem. Success never masks a finding — `doctor` and `catalog check` exit `3` on a violation, never `0`.
+
+## Contributing
+
+Build, test, the spec-first workflow, and the release process are in [CONTRIBUTING.md](CONTRIBUTING.md). Contexture is MIT licensed — see [LICENSE](LICENSE).

package/dist/adapters/types.d.ts

@@ -43,16 +43,11 @@ export declare const SUPPORTED_ADAPTER_INTERFACE_VERSION: Record<AdapterKind, nu
  * itself is invoked by (a hook command): `root` is deleted the moment the
  * session worktree that generated it lands, so a path anchored there goes
  * stale as soon as that happens.
- *
- * `binPath` is this installation's own resolved CLI entrypoint, for a
- * harness whose config needs to shell out back to `ctxr` (a generated hook
- * script). See claude-code.ts's permissionConfig for the concrete case.
  */
 export interface PermissionConfigInput {
     root: string;
     mainRoot: string;
     worktreesPath: string;
-    binPath: string;
 }
 export interface HarnessGenerationAdapter extends Adapter<'harness-generation'> {
     /**

package/dist/adapters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAE/C,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC1D,IAAI,EAAE,CAAC,CAAC;IACR,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAI3E,CAAC;AAEF;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAyB,SAAQ,OAAO,CAAC,oBAAoB,CAAC;IAC7E;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,0LAA0L;IAC1L,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE;QACjB,iEAAiE;QACjE,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9D;;;;;;WAMG;QACH,YAAY,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpE,0GAA0G;QAC1G,QAAQ,CAAC,EAAE;YACT,uCAAuC;YACvC,gBAAgB,EAAE,MAAM,CAAC;YACzB,2EAA2E;YAC3E,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oBAAoB,EAAE,wBAAwB,CAAC;CAChD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAE/C,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC1D,IAAI,EAAE,CAAC,CAAC;IACR,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAI3E,CAAC;AAEF;;;;;;;;;GASG;AACH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAyB,SAAQ,OAAO,CAAC,oBAAoB,CAAC;IAC7E;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,0LAA0L;IAC1L,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE;QACjB,iEAAiE;QACjE,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9D;;;;;;WAMG;QACH,YAAY,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpE,0GAA0G;QAC1G,QAAQ,CAAC,EAAE;YACT,uCAAuC;YACvC,gBAAgB,EAAE,MAAM,CAAC;YACzB,2EAA2E;YAC3E,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oBAAoB,EAAE,wBAAwB,CAAC;CAChD"}

package/dist/commands/adapters-generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters-generate.d.ts","sourceRoot":"","sources":["../../src/commands/adapters-generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,QAAQ,EAAE,eAAuC,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,0BAA0B,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wDAAwD;AACxD,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAkDhH;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC,CAWtG"}
+{"version":3,"file":"adapters-generate.d.ts","sourceRoot":"","sources":["../../src/commands/adapters-generate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,QAAQ,EAAE,eAAuC,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,0BAA0B,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wDAAwD;AACxD,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAgDhH;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC,CAWtG"}

package/dist/commands/adapters-generate.js

@@ -4,7 +4,7 @@ import { agentsMdPath } from '../core/agents-doc.js';
 import { ExitCode } from '../core/exit-codes.js';
 import { upsertFencedRegionInFile } from '../core/fs/fenced-region.js';
 import { mainWorktreePath } from '../core/git/worktree.js';
-import { installTemplatedHookScript, resolveOwnBinPath } from '../core/hooks.js';
+import { installTemplatedHookScript } from '../core/hooks.js';
 import { mergeJsonArrayLists } from '../core/json-config-merge.js';
 import { harnessEntryFence } from '../core/markers.js';
 export const requires = { store: 'required' };
@@ -33,11 +33,10 @@ export async function generateAdapterOutputs(git, store) {
                 root: store.root,
                 mainRoot,
                 worktreesPath: store.config.session.worktrees_path,
-                binPath: resolveOwnBinPath(),
             };
             let permChanged = false;
             if (adapter.permissionConfig.hookFile) {
-                const { changed: hookScriptChanged } = await installTemplatedHookScript(store.root, adapter.permissionConfig.hookFile.targetPath, adapter.permissionConfig.hookFile.templateFileName, { __CONTEXTURE_BIN__: input.binPath });
+                const { changed: hookScriptChanged } = await installTemplatedHookScript(store.root, adapter.permissionConfig.hookFile.targetPath, adapter.permissionConfig.hookFile.templateFileName);
                 permChanged = permChanged || hookScriptChanged;
             }
             const permPath = path.join(store.root, adapter.permissionConfig.path);

package/dist/commands/adapters-generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters-generate.js","sourceRoot":"","sources":["../../src/commands/adapters-generate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapters-generate.js","sourceRoot":"","sources":["../../src/commands/adapters-generate.ts"],"names":[],"mappings":"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"}

package/dist/commands/context-gather.d.ts

@@ -0,0 +1,22 @@
+import type { CommandOutcome, CommandRequires } from '../core/command.js';
+import { type GatherOutcome } from '../core/retrieval/pass.js';
+import type { Store } from '../core/store.js';
+export declare const requires: CommandRequires;
+export interface ContextGatherFlags {
+    seed?: string[];
+    section?: string[];
+    under?: string[];
+    entity?: string[];
+    hops?: number;
+    direction?: 'in' | 'out' | 'both';
+    type?: string;
+    maxNotes?: number;
+}
+/**
+ * compose-the-retrieval-pass spec: entry selectors in, the graph-expanded
+ * neighbourhood out, each note carrying its gloss and the evidence for why it
+ * is there. Agent-facing enumeration only — like `rollup gather` and `publish
+ * gather`, it finds and orders candidates and never reads or synthesizes them.
+ */
+export declare function execute(store: Store, flags?: ContextGatherFlags): Promise<CommandOutcome<GatherOutcome>>;
+//# sourceMappingURL=context-gather.d.ts.map

package/dist/commands/context-gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-gather.d.ts","sourceRoot":"","sources":["../../src/commands/context-gather.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1E,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,QAAQ,EAAE,eAAuC,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,kBAAuB,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAyBlH"}

package/dist/commands/context-gather.js

@@ -0,0 +1,36 @@
+import { ExitCode } from '../core/exit-codes.js';
+import { readAdmittedGraph } from '../core/graph/persist.js';
+import { listNotes } from '../core/notes/list.js';
+import { gather } from '../core/retrieval/pass.js';
+export const requires = { store: 'required' };
+/**
+ * compose-the-retrieval-pass spec: entry selectors in, the graph-expanded
+ * neighbourhood out, each note carrying its gloss and the evidence for why it
+ * is there. Agent-facing enumeration only — like `rollup gather` and `publish
+ * gather`, it finds and orders candidates and never reads or synthesizes them.
+ */
+export async function execute(store, flags = {}) {
+    const notes = await listNotes(store.root, store.config);
+    const graph = await readAdmittedGraph(store);
+    const options = {
+        seeds: flags.seed,
+        sections: flags.section,
+        under: flags.under,
+        entities: flags.entity,
+        hops: flags.hops,
+        direction: flags.direction,
+        type: flags.type,
+        maxNotes: flags.maxNotes,
+    };
+    const data = await gather(store, notes, graph, options);
+    const truncated = data.budget.truncated ? `, ${data.budget.omitted} omitted by the cap of ${data.budget.maxNotes}` : '';
+    return {
+        exitCode: ExitCode.Ok,
+        data,
+        findings: [],
+        humanSummary: `${data.budget.returned} note(s) within ${data.hops} hop(s)${truncated}.`,
+        storeRoot: store.root,
+        schemaVersion: store.config.schema_version,
+    };
+}
+//# sourceMappingURL=context-gather.js.map

package/dist/commands/context-gather.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-gather.js","sourceRoot":"","sources":["../../src/commands/context-gather.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,MAAM,EAA0C,MAAM,2BAA2B,CAAC;AAG3F,MAAM,CAAC,MAAM,QAAQ,GAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAa/D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAY,EAAE,KAAK,GAAuB,EAAE;IACxE,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAE7C,MAAM,OAAO,GAAkB;QAC7B,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,QAAQ,EAAE,KAAK,CAAC,OAAO;QACvB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,KAAK,CAAC,MAAM;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,0BAA0B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxH,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,EAAE;QACrB,IAAI;QACJ,QAAQ,EAAE,EAAE;QACZ,YAAY,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,mBAAmB,IAAI,CAAC,IAAI,UAAU,SAAS,GAAG;QACvF,SAAS,EAAE,KAAK,CAAC,IAAI;QACrB,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,cAAc;KAC3C,CAAC;AACJ,CAAC"}

package/dist/commands/graph-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-query.d.ts","sourceRoot":"","sources":["../../src/commands/graph-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,QAAQ,EAAE,eAAuC,CAAC;AA2B/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAKlD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,CAUpD;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC,CAKnH;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,SAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAAC,CAIpH;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEjD,wBAAsB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAI3H;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAElD,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,aAAkB,GACxB,OAAO,CAAC,cAAc,CAAC;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAAC,CAIvD;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,YAAiB,GACvB,OAAO,CAAC,cAAc,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAAC,CAIrD"}
+{"version":3,"file":"graph-query.d.ts","sourceRoot":"","sources":["../../src/commands/graph-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1E,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,eAAO,MAAM,QAAQ,EAAE,eAAuC,CAAC;AA0B/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAKlD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,CAUpD;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC,CAKnH;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,SAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAC,CAAC,CAIpH;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEjD,wBAAsB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,YAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC,CAI3H;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAElD,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,aAAkB,GACxB,OAAO,CAAC,cAAc,CAAC;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAAC,CAIvD;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,KAAK,EACZ,KAAK,GAAE,YAAiB,GACvB,OAAO,CAAC,cAAc,CAAC;IAAE,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAAC,CAIrD"}

package/dist/commands/graph-query.js

@@ -1,17 +1,15 @@
-import { GraphNodeNotFoundError, GraphNotBuiltError } from '../core/errors.js';
+import { GraphNodeNotFoundError } from '../core/errors.js';
 import { ExitCode } from '../core/exit-codes.js';
 import { bridges, clusters, hubs, neighbors, orphans, shortestPath, subgraph, } from '../core/graph/query.js';
-import { readGraph } from '../core/graph/persist.js';
+import { readAdmittedGraph } from '../core/graph/persist.js';
 export const requires = { store: 'required' };
 /**
- * Every subcommand below routes through this one loader, so a query can
- * never read a graph the store has not built.
+ * Every subcommand below routes through this one loader, so a query can never
+ * read a graph the store has not built — nor one carrying a note the store no
+ * longer admits, which `readAdmittedGraph` refuses on behalf of every caller.
  */
 async function loadGraph(store) {
-    const graph = await readGraph(store);
-    if (!graph)
-        throw new GraphNotBuiltError();
-    return graph;
+    return readAdmittedGraph(store);
 }
 function assertNode(graph, nodeId) {
     if (!graph.nodes.some((n) => n.id === nodeId))

package/dist/commands/graph-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-query.js","sourceRoot":"","sources":["../../src/commands/graph-query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graph-query.js","sourceRoot":"","sources":["../../src/commands/graph-query.ts"],"names":[],"mappings":"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"}

package/dist/commands/ingest.d.ts

@@ -4,25 +4,38 @@ import type { Store } from '../core/store.js';
 export declare const requires: CommandRequires;
 export interface IngestFlags {
     path: string;
+    into: string;
     sourceType: string;
     sourceId: string;
 }
 export interface IngestData {
-    path: string;
+    /** Where the capture was retained — its path after the move out of the inbox. */
+    capture: string;
+    /** The note that now cites it. */
+    note: string;
     sourceType: string;
     sourceId: string;
     sourceHash: string;
     ingested: string;
 }
 /**
- * context-ingest spec: identity fields are assigned once, here, and never
- * recomputed from the live body afterward — the hash computed in this
- * function IS the frozen source-hash for this note's lifetime. Rebuilding
- * the catalog before returning (rather than documenting it as a required
- * next step) is this codebase's choice for task 6.6: a successful write
- * leaves its own derived-artifact consequence consistent immediately,
- * matching every other writer in the system (init's .gitignore/AGENTS.md
- * reconciliation, catalog build itself).
+ * context-ingest spec: identity is assigned once, here, onto the CAPTURE —
+ * the file that arrived — and never recomputed from it afterwards. The
+ * destination note is the synthesis, free to be rewritten without touching
+ * the hash, and it may already exist: expanding, merging and restructuring
+ * record provenance on the same footing as creating, which is the whole point
+ * of retaining the capture rather than consuming it.
+ *
+ * Order matters for resumability. The capture is written to its retained
+ * location before the old one is removed, and the note is cited last, so an
+ * interruption leaves either an un-ingested capture or a retained one that a
+ * re-run can cite — never a note citing a path that does not exist.
+ *
+ * Rebuilding the catalog before returning (rather than documenting it as a
+ * required next step) is this codebase's choice: a successful write leaves
+ * its own derived-artifact consequence consistent immediately, matching every
+ * other writer in the system. The retained capture takes no catalog entry —
+ * the capture root is a retrieval exclusion, so it is not a note.
  */
 export declare function execute(env: RunEnv, store: Store, flags: IngestFlags): Promise<CommandOutcome<IngestData>>;
 //# sourceMappingURL=ingest.d.ts.map