ctxr-cli 0.8.0 → 0.9.0

package/templates/agents/capture-and-ingest.md

@@ -1,17 +1,36 @@
 ## Capturing and ingesting new material
 
-To capture something new, write a plain markdown file directly into `__INBOX_PATH__` —
-no CLI command wraps this. That file MUST NOT contain any of these frontmatter fields; contexture assigns
-them once, at ingest, and never before:
+Captures live under `__CAPTURE_ROOT__`, which is excluded from retrieval: nothing in it is a note, and
+nothing in it is returned by a search, listed in the catalog, or drawn in the graph. It is tracked in git
+all the same — a capture is the provenance behind a note, not scratch space.
+
+To capture something new, write the material into `__INBOX_PATH__` — no CLI command wraps this. It may
+already carry these two fields, since whatever fetched it usually knows them:
 
 - `source_type`
 - `source_id`
+
+It MUST NOT carry either of these; contexture assigns them once, at ingest, and never before:
+
 - `source_hash`
 - `ingested`
 
-Before ingesting, run `ctxr source check <path> --source-id <id>` to get one of four verdicts:
-`new`, `already_ingested`, `alternate_source_match`, or `multiple_matches` — the last one means stop and
-resolve the ambiguity yourself rather than guessing which existing note it is.
+Before ingesting, run `ctxr source check <path> --source-id <id>` to get one of five verdicts: `new`,
+`already_ingested`, `drift` (same identity, the source's content moved), `alternate_source_match`, or
+`multiple_matches` — the last one means stop and resolve the ambiguity yourself rather than guessing which
+existing record it is.
+
+Then write, or extend, the note this material informed. Ingest does not create it: deciding what the store
+should know is the work, and "a new note" is only one of the answers.
+
+```
+ctxr ingest <path> --into <note> --source-type <type> --source-id <id>
+```
+
+That stamps the four fields onto the capture, moves it out of the inbox into `__CAPTURE_ROOT__` under the
+month it was ingested, and records its path in the note's `sources` list. The note itself carries no source
+identity — it is free to be rewritten, merged, or restructured without ever invalidating the frozen hash.
+A note may cite as many captures as it was built from.
 
-To ingest, run `ctxr ingest <path> --source-type <type> --source-id <id>`. It stamps the four fields
-above onto the file in place and rebuilds the catalog, so the result already has a catalog entry.
+Material that is not markdown cannot carry frontmatter, so it travels with a markdown sidecar beside it
+naming the file in `capture_file`. The hash is taken over that file's bytes, and the two move together.

package/templates/agents/retrieval-leg-routing.md

@@ -1,14 +1,40 @@
-## Retrieval: which leg to use
+## Retrieval: one pass, three steps
 
-contexture builds and maintains two retrieval tools ahead of time — consult them first:
+Retrieval is a single pass — **enter**, **expand**, **widen** — not three tools to choose between.
+contexture builds and maintains the first two ahead of time; the third is yours.
 
-- **Catalog** (`ctxr catalog show --section <id>`): a curated, coverage-guaranteed index of every retrievable note, one section per taxonomy layer.
-- **Graph** (`ctxr graph query ...`): the wikilink graph between notes — neighbors, shortest path, hubs, orphans, clusters, bridges; `--type <relation>` follows one configured relation.
-- **Graph document** (`__GRAPH_DOCUMENT_PATH__`, rebuilt by `ctxr graph build`): hub notes by cluster, cross-cluster bridges, and orphans — read it for cluster context before writing.
+**1. Enter.** Name where to start, positionally or relationally:
 
-For a literal or entity question the catalog and graph do not answer (a specific string, an exact identifier, a phrase),
-use your own direct content-matching tool (e.g. grep/ripgrep) against the store, scoped to exclude:
+- `--section <id>` — every note a catalog section lists (`ctxr catalog show --section <id>` reads one directly)
+- `--under <prefix>` — every retrievable note under a path prefix
+- `--seed <path>` — a note you already hold, including one your own search just found
+- `--entity <name>` — every note linking to a concept
+
+**2. Expand.** `ctxr context gather` takes those selectors and walks the wikilink graph out from them,
+returning each reachable note with its catalog gloss, its hop distance, and labels saying why it is
+there — so you can triage the set without opening a single file, then read only what the glosses
+justify:
+
+```
+ctxr context gather --section <id> --hops 1
+ctxr context gather --seed <path> --hops 2 --type <relation>
+```
+
+Results are ordered: live material before demoted (archived) material, nearer hops before farther,
+then by how the note was reached, then by path. `no_gloss` on a result means the catalog has no
+description for that note yet — the pass found it structurally, not by what it says.
+
+For structure on its own — shortest path, hubs, orphans, clusters, bridges — query the graph directly
+with `ctxr graph query ...`, and read the graph document at `__GRAPH_DOCUMENT_PATH__` (rebuilt by
+`ctxr graph build`) for cluster context before writing.
+
+**3. Widen.** For a literal or entity question the first two steps do not answer — a specific string,
+an exact identifier, a phrase — use your own content-matching tool (e.g. grep/ripgrep) against the
+store, scoped to exclude:
 
 __EXCLUSION_PATHS__
 
-There is no `ctxr search` command. Ranked or semantic search is deferred to a future version — do not look for one.
+Feed anything it finds back in as `--seed` to pick the pass up again from there.
+
+There is no `ctxr search` command. Nothing here takes a free-text query, and no result carries a
+relevance score. Ranked or semantic search is deferred to a future version — do not look for one.

package/templates/hooks/_resolve-ctxr.sh

@@ -0,0 +1,37 @@
+# --- shared: resolve the ctxr CLI ------------------------------------------
+# Authored in templates/hooks/_resolve-ctxr.sh and inlined verbatim into every
+# hook that needs it at render time (src/core/hooks.ts) — one copy of a
+# security decision, never two that can drift apart. Do not edit the inlined
+# copy; re-run `ctxr init` / `ctxr update` to regenerate it.
+#
+# Resolves at RUN time, so the rendered hook is byte-identical in every
+# checkout of this store: a path baked in when the file was generated is
+# valid only on the machine that generated it, and this file is committed.
+#
+# Order: $CONTEXTURE_BIN, then `ctxr` on PATH. Nothing else is consulted, and
+# there is no "give up and continue" branch — when neither resolves, this
+# calls ctxr_unavailable <reason>, which each hook defines above and which
+# must not return. A CONTEXTURE_BIN that is set but broken is terminal: it is
+# a deliberate pin, and silently running a different binary instead would
+# defeat the operator who set it.
+#
+# Leaves the resolved command in the positional parameters ("$@"). Neither
+# hook that inlines this reads its own arguments.
+if [ -n "${CONTEXTURE_BIN:-}" ]; then
+  if [ ! -f "$CONTEXTURE_BIN" ]; then
+    ctxr_unavailable "CONTEXTURE_BIN names a path that is not a file: $CONTEXTURE_BIN"
+  elif [ -x "$CONTEXTURE_BIN" ]; then
+    set -- "$CONTEXTURE_BIN"
+  elif command -v node >/dev/null 2>&1; then
+    # A plain dist/bin.js: tsc emits it non-executable, and only npm's
+    # bin-linking sets the bit, so a dev checkout needs node to run it.
+    set -- node "$CONTEXTURE_BIN"
+  else
+    ctxr_unavailable "CONTEXTURE_BIN is not executable and no node is on PATH to run it: $CONTEXTURE_BIN"
+  fi
+elif command -v ctxr >/dev/null 2>&1; then
+  set -- ctxr
+else
+  ctxr_unavailable "no ctxr on PATH, and CONTEXTURE_BIN is not set"
+fi
+# --- end shared: resolve the ctxr CLI --------------------------------------

package/templates/hooks/claude-code-write-gate.sh

@@ -3,13 +3,41 @@
 # controlled — do not edit by hand; re-run to regenerate. A PreToolUse hook:
 # relays the tool-call envelope on stdin to `ctxr adapters write-gate`, which
 # decides whether to deny it, and relays its stdout and exit code unchanged.
+# Carries no path specific to the machine that generated it — `ctxr` is
+# resolved at run time, and an edit this gate could not evaluate is denied,
+# not allowed unchecked.
 set -eu
 
-CONTEXTURE_BIN="__CONTEXTURE_BIN__"
-
-if [ ! -f "$CONTEXTURE_BIN" ]; then
-  echo "ctxr: warning — could not find $CONTEXTURE_BIN; skipping write-gate check." >&2
+# The write gate is an enforcement primitive, and a gate that cannot run is
+# not a passing decision (adapters spec). This speaks the same PreToolUse deny
+# protocol `ctxr adapters write-gate` does — a JSON body on stdout, exit 0 —
+# because that is the only vocabulary the harness reads as "denied, and here
+# is why". A nonzero exit other than 2 is reported as a hook error and the
+# edit proceeds, which is the failure this replaces; exit 2 hard-blocks
+# regardless of output and would conflate a broken install with a decision.
+ctxr_unavailable() {
+  # Drain the envelope the harness is writing to us before exiting: the
+  # normal path reads stdin to EOF via `ctxr adapters write-gate`, and a
+  # harness that writes the full envelope before checking our exit code
+  # would otherwise see its own write fail (EPIPE/SIGPIPE) once we exit
+  # without ever reading it.
+  cat >/dev/null 2>&1 || true
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"contexture: the write gate could not run (%s), so this edit is denied rather than allowed unchecked. Install the CLI (npm install -g ctxr-cli) or set CONTEXTURE_BIN to its dist/bin.js, then retry."}}\n' "$1"
   exit 0
-fi
+}
 
-node "$CONTEXTURE_BIN" adapters write-gate
+__RESOLVE_CTXR__
+
+# Not `exec`: a resolved command can still fail to execute (a broken symlink,
+# a non-executable file found on PATH), and exec's 126/127 would reach the
+# harness as an ordinary hook error — fail-open, the bug this file exists to
+# close. Every other exit code and all of stdout are relayed unchanged, so the
+# gate's own deliberate "I could not decide, apply normal permission flow"
+# exits (never 2) keep their documented meaning.
+status=0
+out=$("$@" adapters write-gate) || status=$?
+if [ "$status" -eq 126 ] || [ "$status" -eq 127 ]; then
+  ctxr_unavailable "the resolved ctxr could not be executed (exit $status)"
+fi
+printf '%s' "$out"
+exit "$status"

package/templates/hooks/pre-commit.sh

@@ -1,18 +1,25 @@
 #!/bin/sh
 # Installed by `ctxr init` (write-lifecycle spec). Version-controlled —
 # do not edit by hand; re-run `ctxr init` or `ctxr doctor` to
-# regenerate. Runs `doctor --staged` against the exact contexture install
-# that wrote this hook, and refuses the commit if it finds a real problem.
+# regenerate. Runs `doctor --staged` with the ctxr this machine resolves at
+# run time, and refuses the commit if it finds a real problem — or if it
+# could not run that validation at all.
 set -eu
 
-CONTEXTURE_BIN="__CONTEXTURE_BIN__"
+# A commit this hook could not check is refused, not passed: the point of the
+# hook is that no unvalidated change is committed, and "ctxr is not installed
+# here" is not evidence that the staged diff is clean.
+ctxr_unavailable() {
+  echo "ctxr: commit refused — $1" >&2
+  echo "ctxr: this hook validates staged changes with 'ctxr doctor --staged', and will not pass a commit it could not check." >&2
+  echo "ctxr: install the CLI with 'npm install -g ctxr-cli', or set CONTEXTURE_BIN to its dist/bin.js." >&2
+  echo "ctxr: 'git commit --no-verify' bypasses this hook if you must commit before repairing the install." >&2
+  exit 1
+}
 
-if [ ! -f "$CONTEXTURE_BIN" ]; then
-  echo "ctxr: warning — could not find $CONTEXTURE_BIN; skipping pre-commit validation." >&2
-  exit 0
-fi
+__RESOLVE_CTXR__
 
-if ! output=$(node "$CONTEXTURE_BIN" doctor --staged --json 2>&1); then
+if ! output=$("$@" doctor --staged --json 2>&1); then
   echo "$output" >&2
   echo "ctxr: commit refused — staged changes failed 'doctor --staged'." >&2
   exit 1

package/templates/skills/ctxr-connection-finding.md

@@ -5,11 +5,13 @@ to synthesize an entity's current state from its sources, use `ctxr-rollup`.
    document it writes at `__GRAPH_DOCUMENT_PATH__` — hub notes by cluster, cross-cluster bridges,
    orphans — for the cluster context the point queries below do not summarize.
 2. To find what a note connects to or from, run `ctxr graph query neighbors <path>` (add `--depth` for
-   further hops, `--direction in|out|both`, `--type <relation>` to follow one configured relation,
-   `--as <context>` to see only what that context can see).
-3. To find a path between two notes, run `ctxr graph query path <from> <to>`.
-4. To find the most-referenced notes, run `ctxr graph query hubs`; to find unlinked ones,
+   further hops, `--direction in|out|both`, `--type <relation>` to follow one configured relation).
+3. To read a neighbourhood rather than enumerate one — every reachable note with its catalog gloss,
+   hop distance, and why it was reached — run `ctxr context gather --seed <path> --hops <n>`. Use it
+   when you need to judge which links matter; use the point queries below when you need the structure.
+4. To find a path between two notes, run `ctxr graph query path <from> <to>`.
+5. To find the most-referenced notes, run `ctxr graph query hubs`; to find unlinked ones,
    `ctxr graph query orphans`; `ctxr graph query clusters` and `ctxr graph query bridges` show the
    cluster structure and the notes that span it.
-5. Report what the graph says — it enumerates structure and ranks nothing; judgment about which links
+6. Report what the graph says — it enumerates structure and ranks nothing; judgment about which links
    matter is yours.

package/templates/skills/ctxr-ingest-orchestration.md

@@ -1,15 +1,16 @@
 Ingest is synthesis, not filing. The question is what the store should know after this source, not where
 to put the file — "create a new note" is one option among several, never the default.
 
-1. Capture: write a plain markdown file directly into the inbox (see AGENTS.md's capture section) — no
-   provenance frontmatter; contexture assigns it at ingest.
+1. Capture: write the material into the inbox (see AGENTS.md's capture section). It may already carry
+   `source_type` and `source_id`; it must carry neither `source_hash` nor `ingested`, which ingest assigns.
+   The capture is kept — it is the store's record of what arrived, and it never becomes the note.
 2. Check: run `ctxr source check <path> --source-id <id>` and read the verdict — `new`, `already_ingested`,
    `drift` (same identity, the source's content moved — read what changed and decide whether to update the
    note, then `ctxr source stamp <path> --id <id>` once resolved), `alternate_source_match`, or
    `multiple_matches`. On `multiple_matches`, stop and resolve the ambiguity yourself; never guess which
-   existing note it is. A legacy note with an identity but no hash on file: `ctxr source stamp` backfills
-   it. A source re-published under a new URL you've confirmed is the same material:
-   `ctxr source add-alt <path> --id <new-id>` on the existing note, not a second ingest.
+   existing record it is. A record with an identity but no hash on file: `ctxr source stamp` backfills it.
+   A source re-published under a new URL you've confirmed is the same material:
+   `ctxr source add-alt <path> --id <new-id>` on the existing capture, not a second ingest.
 3. Read the source fully. Then read the existing cluster BEFORE writing anything: the catalog section for
    the domain (`ctxr catalog show --section <id>`), every related note in it (all of them, not one or two),
    and the graph (`ctxr graph build`, then read the graph document it writes at
@@ -36,7 +37,12 @@ to put the file — "create a new note" is one option among several, never the d
      headline is worse than either alone.
    - Source discipline: a field the source does not confirm is "not reported" — never inferred from
      silence in either direction.
-5. Write: for a new note, `ctxr ingest <path> --source-type <type> --source-id <id>` (stamps provenance and
-   gives it a catalog entry). Updates to existing notes are ordinary edits that preserve prior content
-   (a deliberate ingest despite an `alternate_source_match` is the same command).
-6. Verify: `ctxr lint` (orphans, broken links, leftover inbox material) and `ctxr catalog check`.
+5. Write the note the decision calls for — create it, expand it, merge, restructure, or add a section —
+   preserving prior content in every case but the deliberate rewrite.
+6. Register the source against whatever note you just wrote:
+   `ctxr ingest <path> --into <note> --source-type <type> --source-id <id>`. Every row of the table above
+   ends here, not just the first: the command retains the capture under the capture tier's month, freezes
+   its hash, cites it from the note, and rebuilds the catalog. A note that was expanded rather than created
+   records its provenance exactly as a new one does, and a note built from several sources cites all of
+   them. A deliberate ingest despite an `alternate_source_match` is the same command.
+7. Verify: `ctxr lint` (orphans, broken links, material still in the inbox) and `ctxr catalog check`.

package/templates/skills/ctxr-publish.md

@@ -1,7 +1,6 @@
-Turn store content into a shareable HTML page for a subject — a store subtree, a single note, a
-concept whose sources aren't co-located, or everything a named context admits. The gate below is the
-one step no convention can enforce by itself; everything else here is a decision procedure, not a
-mechanism.
+Turn store content into a shareable HTML page for a subject — a store subtree, a single note, or a
+concept whose sources aren't co-located. Deciding what belongs on the page is the one step no
+convention can enforce for you; everything else here is a decision procedure, not a mechanism.
 
 ## 1. Does this earn a page over a note?
 
@@ -51,10 +50,10 @@ notes came from, so the notes' shorthand does not survive the copy out. Load the
 store carries by default (or whichever explanation-focused skill it's configured instead), settle who
 the reader is before writing, and pitch every definition, analogy, and level of detail at them.
 
-Both skills say "audience", and neither means step 3's. There, `--audience` names who the store is
-being asked to disclose to and the answer is a verdict; here it names how much a reader already knows
-and the answer is a register. A comprehension level is never a value you pass to `--audience`, and
-writing plainly never widens what the page may contain — the gate in step 3 already settled that.
+Both skills say "audience", and here it means one thing only: how much the reader already knows,
+which is a question about register. It is never a reason to put more on the page. Step 3 settled what
+the page may carry, and writing that content more plainly never widens it — an explanation pitched
+lower is the same material in shorter words.
 
 ## 6. Verify the output invariants