ctxr-cli 0.20.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxr-cli",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "Context store for AI coding agents — markdown and git, catalog and graph retrieval, no vector database.",
   "type": "module",
   "license": "MIT",
@@ -52,9 +52,9 @@
   },
   "devDependencies": {
     "@types/markdown-it": "^14.2.0",
-    "@types/node": "^22.20.1",
+    "@types/node": "^26.6.4",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "keywords": [
     "contexture",

package/templates/agents/canonical.md

@@ -2,9 +2,7 @@
 
 ### Root resolution
 
-Every contexture command resolves the store root in this order: an explicit `--root <path>` flag; the store found by walking up from the current directory when it is a linked git worktree of the store named by `CONTEXTURE_STORE_ROOT`; the `CONTEXTURE_STORE_ROOT` environment variable; walking up from the current directory looking for `__CONFIG_FILE_NAME__`. No other flag or environment variable selects the root.
-
-The worktree step is why a command run inside a session worktree operates on that worktree rather than on the canonical clone, even with `CONTEXTURE_STORE_ROOT` exported: the variable names which *store*, and a worktree raises which *checkout* of it. Standing in a different store still resolves the variable, unchanged. To target the canonical clone from inside a worktree, name it: `--root "$CONTEXTURE_STORE_ROOT"`.
+Every contexture command resolves the store root in this order: an explicit `--root <path>` flag; the store found by walking up from the current directory when it is a linked git worktree of the store named by `CONTEXTURE_STORE_ROOT`; the `CONTEXTURE_STORE_ROOT` environment variable; walking up from the current directory looking for `__CONFIG_FILE_NAME__`. No other flag or environment variable selects the root. Inside a session worktree, commands therefore act on that worktree; to target the canonical clone from there, pass `--root "$CONTEXTURE_STORE_ROOT"`.
 
 ### Frontmatter schema
 
@@ -12,15 +10,12 @@ The worktree step is why a command run inside a session worktree operates on tha
 
 ### Note templates
 
-A new note starts from a template under `__TEMPLATES_PATH__`, not from a blank file and not by copying whatever sibling happens to be nearby. Substitute `{{title}}` and `{{date}}` as you write it — no command expands them, and a note that lands with one still in it is reported by `ctxr lint`. A template is never a note: nothing under that path is catalogued, graphed, or retrieved. Add your own kinds there alongside the shipped ones; contexture only ever rewrites the ones it delivered.
-
-Every shipped template except the base, `Note`, stamps the kind it is for into the note's `tags`. Keep it when you start a note: it is how you find every note of a kind, with your own search, since no `ctxr` command filters by it. A kind you cut from the base should stamp its own name the same way, and any further tags are this store's own.
+Start a new note from a template under `__TEMPLATES_PATH__`, never a blank file or a copied sibling, and substitute `{{title}}` and `{{date}}` yourself — `ctxr lint` reports one left in. Keep the kind the template stamps into `tags`: it is how your own search finds every note of a kind, since no `ctxr` command filters by it.
 
 ### Write path
 
-Every write to this store happens inside a session worktree, never directly on the default branch: `ctxr session start` creates one, and the work stays there for as long as the session runs. When the operator asks to wrap up, `ctxr-submit` validates with `ctxr doctor`, commits, pushes, and opens (or reports how to open) a pull request — that request is what triggers it, not having finished a piece of work. Do not edit files in the store root directly.
+Every write happens inside a session worktree (`ctxr session start`), never on the default branch, and lands through a reviewed pull request that `ctxr-submit` opens when the operator asks to wrap up. Do not edit files in the store root directly.
 
 ### Identity and recall
 
 Identity, persona, and the agent's conversational recall — what it remembers of the user and of itself from one session to the next — belong to its harness, not to this store. Subject-matter knowledge belongs here, including anything worth finding again in a later session: the store holds knowledge and skills, documented as portable markdown under `__SKILLS_PATH__`, and never a persona or recall file of its own.
-__MISSION_POINTER__

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

@@ -1,38 +1,3 @@
 ## Capturing and ingesting new material
 
-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, but
-`ctxr-capture` carries the procedure: what counts as the record rather than a summary of it, how to
-identify it, and where capture stops. The material 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 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.
-
-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.
+Capture new material as a file in `__INBOX_PATH__`. Everything under `__CAPTURE_ROOT__` is tracked in git as provenance but excluded from retrieval — nothing there is a note. A capture may carry `source_type` and `source_id`; it must never carry `source_hash` or `ingested`, which `ctxr ingest` assigns once. `ctxr-capture` carries the capture procedure and `ctxr-ingest-orchestration` the dedupe check and the ingest; the note a capture informs carries no source identity of its own.

package/templates/agents/conventions.md

@@ -1,5 +1,7 @@
 ## Store conventions
 
+The rules that hold on every turn: contexture's baseline, then this store's own. Operator conventions are markdown files under `__GUIDANCE_PATH__`; each is inlined here unless its frontmatter declares `read_when`, in which case it is listed under "Read when" instead.
+
 __CONVENTION_BODY__
 
-A note that applies to only one agent harness (not every harness reading this store) belongs below that harness's own managed import in its own entry file, never here — every file in this directory is inlined into every harness's entry document equally.
+A note for only one agent harness belongs in that harness's own entry file, below its managed import — never here.

package/templates/agents/guidance-index.md

@@ -0,0 +1,5 @@
+## Read when
+
+This store's other guidance loads on demand. When a row's trigger matches what you are about to do, read that document first:
+
+__GUIDANCE_ROWS__

package/templates/agents/mission.md

@@ -1,5 +1,7 @@
 ## Mission
 
+__MISSION_CONFIRMED__
+
 __MISSION_BODY__
 
 _Source: __MISSION_PATH___

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

@@ -1,46 +1,11 @@
-## Retrieval: one pass, three steps
+## Retrieval
 
-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.
+Find before you write. contexture builds and maintains the catalog and the wikilink graph; consult them before your own search.
 
-**1. Enter.** Name where to start, positionally or relationally:
+1. **Enter and expand** with `ctxr context gather`. It takes entry selectors — `--section <id>`, `--under <prefix>`, `--seed <path>`, `--entity <name>` — walks the graph out from them (`--hops`, `--type <relation>`), and returns each note with its catalog gloss and hop distance, so you open only what the glosses justify. Start an open conceptual question from a catalog section (`ctxr catalog show --section <id>`).
+2. **Structure** — paths, hubs, orphans, clusters, bridges — comes from `ctxr graph query`; read the graph document at `__GRAPH_DOCUMENT_PATH__` for cluster context before writing.
+3. **Widen** with your own content matching (e.g. ripgrep) for a literal string or identifier, excluding __EXCLUSION_PATHS__, and feed a hit back in as `--seed`. Captures under `__CAPTURE_ROOT__` are excluded because they are provenance, not notes: to learn whether the store already holds some material, search `__CAPTURE_ROOT__` directly, by content and by the `capture_file` a capture names.
 
-- `--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
+When a search finds nothing, retry with the vocabulary the note itself would use, expand acronyms, and walk the graph from the nearest note you did find.
 
-**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__
-
-Feed anything it finds back in as `--seed` to pick the pass up again from there.
-
-Those exclusions are for finding knowledge. Captures under `__CAPTURE_ROOT__` are left out because they
-are provenance, not notes, so a search scoped this way never finds one. When the question is whether
-the store already holds some material — a document, a meeting, a thread — search `__CAPTURE_ROOT__`
-directly, by content and by the `capture_file` a capture names. Finding nothing in the notes is not
-evidence that it was never captured.
-
-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.
+There is no `ctxr search` command: nothing takes a free-text query, and no result carries a relevance score.

package/templates/conventions/baseline-conventions.md

@@ -2,26 +2,37 @@
 title: Baseline conventions
 description: Contexture's shipped conventions, rendered from this store's own configuration.
 ---
-These are the rules that hold regardless of which operation you're doing; a skill states the procedure for one operation.
+## Writing notes
+
+- Write in outliner bullets, not prose paragraphs, unless asked otherwise. Link liberally with wikilinks, and when you create a note, search the store and suggest links to what already exists.
+- Extend what a note says rather than overwrite it, unless a rewrite is asked for.
+- Keep a note's `title:` equal to its filename stem, unique in the store: the catalog builds each entry's wikilink from `title:`, so a divergent title links to nothing.
+- A task is a checkbox with a dated parenthetical: `- [ ] Task (added YYYY-MM-DD, due YYYY-MM-DD)`, `- [~] Task (added YYYY-MM-DD)` while in progress, `- [x] Task (done YYYY-MM-DD)`. Omit a date that does not apply.
+
+## What stays out of the store
+
+- Credentials and full card or account numbers never enter it — the last four digits only.
+- Scratch and intermediate files go in `__SCRATCH_PATH__`, never the store or `$HOME`. Deliverables are not scratch: a page goes under `__PUBLISH_PATH__`, a note into the store.
+- Notes carry no access control — whoever reads the store reads all of it. Place sensitive material deliberately, and say in the note when it must not be quoted onward.
+
+## The store log
+
+`__LOG_PATH__` is append-only: after an ingest, a lint pass, or a structural change, add `## [YYYY-MM-DD] <kind> | <title>` and a few bullets. At session start, if its last `lint` entry is more than seven days old or missing, suggest a lint pass.
 
 ## Links and the relation vocabulary
 
-Wikilinks (`[[Note Name]]`) are the edge substrate the graph is built from. A dangling link — pointing at a note that doesn't yet exist — is a candidate for a new note or a typo, not an error; nothing about it needs fixing before a commit.
+Wikilinks (`[[Note Name]]`) are the edges the graph is built from. A dangling link is a candidate note or a typo, not an error.
 
 __RELATION_VOCABULARY__
 
 ## Archiving
 
-`ctxr archive <path>` retires a note via a single tracked rename into `__ARCHIVE_DESTINATION__`, preserving its git history and its frontmatter unchanged — never a status tag on a note that stays in place. It reports every other note that links to the archived one, so those links can be reviewed; a dangling link left behind is not itself an error (see Links, above).
+Retire a note with `ctxr archive <path>` — one tracked rename into `__ARCHIVE_DESTINATION__`, the note unchanged — never a status tag on a note left in place.
 
 ## Git and sessions
 
-Nothing reaches `__DEFAULT_BRANCH__` un-gated — every write happens inside a session worktree under `__WORKTREES_PATH__`, landed only through a reviewed pull request (see the Write path rule above).
-
-Landing (`ctxr-land`) fast-forwards the store's canonical clone itself once a PR merges — `git fetch origin && git merge --ff-only origin/__DEFAULT_BRANCH__`, run from that clone — as long as it is on `__DEFAULT_BRANCH__` and can fast-forward cleanly from its remote; if it can't (diverged, no remote, or already elsewhere), the skill reports why instead of forcing it, and the clone is never checked out, reset, or discarded to make it fast-forward.
-
-The pre-push hook refuses a direct push to `__DEFAULT_BRANCH__`; `CONTEXTURE_ALLOW_DEFAULT_BRANCH_PUSH=1` is its emergency override — for genuine emergencies, not routine use.
+Nothing reaches `__DEFAULT_BRANCH__` un-gated: work happens in a session worktree under `__WORKTREES_PATH__` and lands through a reviewed pull request (`ctxr-submit`, then `ctxr-land`). The pre-push hook refuses a direct push to `__DEFAULT_BRANCH__`; `CONTEXTURE_ALLOW_DEFAULT_BRANCH_PUSH=1` overrides it, for genuine emergencies only.
 
 ## Directory-scoped conventions
 
-Some folders may carry their own conventions that apply only when working within them — typically as a `README.md` at that folder's root. Read a folder's own `README.md`, if it has one, before making changes inside it; nothing else in this store scans for these automatically.
+A folder may carry its own `README.md`; read it before changing anything inside that folder.

package/templates/conventions/house-conventions-seed.md

@@ -11,6 +11,16 @@ Each entry states the rule, why it exists, and how to apply it:
   Why: <what goes wrong without it — the observation that earned it>
   Apply: <what to actually do, concretely>
 
+Every rule in this file is inlined into AGENTS.md and loads on every turn of every session. A rule that
+matters only for one task belongs in its own file here, whose frontmatter declares when to read it:
+
+    ---
+    title: Content style
+    read_when: Before writing or restructuring a note's body
+    ---
+
+A file with `read_when` is not inlined; AGENTS.md lists it under "Read when", by its trigger and its path.
+
 The Why is not decoration. Without the observation that earned a rule, no future reader can tell
 whether it still holds or whether a one-off calcified into a convention — so it never gets retired,
 and this file only ever grows. `ctxr-session-capture` proposes additions and removals at the end of a

package/templates/skills/ctxr-capture.md

@@ -9,6 +9,10 @@ on disk, a URL the user handed you. Do not assume any particular one is availabl
 one: look at what is there, and if nothing can reach the material, say so and ask rather than
 reconstructing it from memory or from what the user said about it.
 
+Before a research pass on a topic, query the connected meeting and note sources for it first, and capture
+what they hold. Desk research is the expensive move, and nothing else catches primary material that was
+never captured, because every other check runs on what the store already holds.
+
 When a source system returns several items and the request named one, confirm which before writing.
 Capturing the wrong meeting is not recoverable by a later ingest — it is a record of something that did
 not happen.
@@ -22,8 +26,29 @@ that has been improved is no longer evidence of anything.
 Where the source supplies a summary of its own, keep it, clearly marked as the source's derivation, in
 its own section beside the record rather than instead of it. A summary is what a service concluded; the
 record is what happened. A store may require, per source type, the section its captures must carry — if
-it does, a capture missing that section is refused at ingest, so check the store's configuration before
-deciding a summary is enough.
+it does, a capture missing that section is refused at ingest, and so is one whose heading has nothing under
+it or appears only inside a code block, so check the store's configuration before deciding a summary is
+enough.
+
+Perishable material — a promotion, a price, an offer with an end date — is kept for its durable mechanic,
+not its momentary state: capture how it works, and keep the state that will change in a section a later
+capture overwrites.
+
+A file a note links to or displays (a PDF it cites, an image it shows) lives under `__CAPTURE_ROOT__assets/`,
+never in a folder of its own beside the notes.
+
+Several items from one source system covering the same occasion (two recordings of one meeting, a
+transcript and its summary) are one source. Check them against each other by content and named entities —
+string matching misses the same speech transcribed twice — and when they share an event, say so in each
+capture and name which governs. A fact appearing in both is never corroborated by the pair. Where one
+rendering is demonstrably worse, keep it and record its specific errors rather than discarding it.
+
+When a source does not separate speakers, say so in the capture as a caveat on the whole file. Any
+attribution built from it is inference, and a service's own summary attributing positions to named people
+is not the record.
+
+A slide deck is read as images, not extracted text: render its pages and read those, since a deck's meaning
+lives in its layout.
 
 One capture per item. Two meetings in one file cannot be cited separately, deduplicated separately, or
 retracted separately.
@@ -33,9 +58,15 @@ retracted separately.
 In the capture's frontmatter:
 
 - `source_type` — the source system's own name, lowercased. Use the same value the store already uses
-  for that system; a second spelling silently defeats deduplication.
+  for that system; a second spelling silently defeats deduplication. Name the same value on
+  `ctxr ingest --source-type`: a capture that says one source type and is ingested as another is refused,
+  and a store's required section is looked up under the type the capture is recorded under.
 - `source_id` — that source type, then a slash, then the identifier the source system itself uses for
-  this item. Prefer an opaque, stable id over a title or a date, which get edited.
+  this item. Prefer an opaque, stable id over a title or a date, which get edited. Material no system
+  identifies takes a hash instead: a file its SHA-1 (`pdf/<sha1 of the file>`), pasted text the SHA-1 of the
+  text (`manual/<sha1>`). An email is its `Message-ID`; a web page is its URL, which `ctxr source check`
+  compares with the store's tracking parameters (`ingest.tracking_params`) removed. Pass the same prefixed form
+  to `ctxr ingest --source-id`, which refuses one that does not begin with its source type.
 
 Do not write `source_hash` or `ingested`. Ingest assigns both, once, and a capture that arrives
 claiming them is treated as already ingested.

package/templates/skills/ctxr-derived-artifacts.md

@@ -13,6 +13,12 @@ edit inside a fence that the next build erases).
    or hand-add only your entries, matching the committed structure, and say so in the commit message.
 3. Build, then read the result back: reported counts against the source (notes vs catalog entries, graph
    nodes vs notes); your new notes present with non-zero links; nothing else lost.
+   A gloss flagged stale (`ctxr catalog check --stale`, or `ctxr doctor`'s catalog finding) is confirmed by
+   reviewing it, then stripping its `<!-- hash:… -->` marker once, so the next `ctxr catalog build` stamps a fresh
+   one. The marker is frozen on purpose — editing the gloss and rebuilding does not clear the finding, and
+   stripping it without reviewing the gloss confirms nothing. The graph is a per-checkout cache under the cache
+   paths: every clone and worktree starts without one, so build it at the point of use when `ctxr doctor` reports
+   it stale; no schedule keeps it fresh.
 4. Fences: never hand-edit inside a `contexture:<region>` fence — the next build overwrites it. Hand
    edits OUTSIDE a fence (catalog glosses, prose around a generated section) are preserved by every
    build and are the right place for them. A note's own operator-defined fenced region (a ledger, a

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

@@ -36,7 +36,9 @@ to put the file — "create a new note" is one option among several, never the d
      hunt down the now-stale verdict language further down. A corrected body under an uncorrected
      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.
+     silence in either direction. A quantity the store did not verify carries who claimed it, when, and
+     in what setting ("founder-claimed, 2026-09-16, recruiting pitch"): stripped of its setting, a pitch
+     number and a filed number look identical later. Say when a figure is checkable and unchecked.
 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. A NEW note starts from a template
    under `__TEMPLATES_PATH__`, with `{{title}}` and `{{date}}` substituted as you write (`ctxr-placement`
@@ -49,3 +51,5 @@ to put the file — "create a new note" is one option among several, never the d
    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`.
+8. Log it: append `## [YYYY-MM-DD] ingest | <title>` to `__LOG_PATH__`, with a bullet naming the note it informed
+   and what changed there.

package/templates/skills/ctxr-mission.md

@@ -1,36 +1,45 @@
-Keep this store's mission document — the standing "what's active right now" map AGENTS.md names at
-`organize.mission_path` when configured — current: priorities, active builds, back burner, sunset
-candidates, and debt. Hand-written content outside the fenced region is never touched.
+Keep this store's mission current: the short core every agent sees on every turn, inlined into AGENTS.md's
+"Mission" section from the document named on its source line. The core is the operator's statement of what
+matters now, so it is small, ranked, and dated. Everything else it once carried lives in a register note it
+links to. Hand-written content outside the fenced region is never touched.
 
-Run `ctxr rollup stale` (or `--for <mission_path>`) first — a never-written mission document, or one whose
-recorded timestamp has aged past `organize.rollup_stale_days`, is reported stale on elapsed time alone (no
-backlinks compared, unlike an entity rollup); use it instead of guessing from memory whether the document
-is out of date.
+Run `ctxr rollup stale` (or `--for <mission_path>`) first. A mission never confirmed, or one confirmed more than
+`organize.rollup_stale_days` ago, is reported stale on elapsed time alone; `ctxr lint` also reports any due date
+in it that has passed. Use those rather than guessing from memory whether it is out of date.
 
-1. Resolve `<mission_path>` from AGENTS.md's canonical section. If no mission document is configured for
-   this store, STOP — this skill has nothing to maintain; do not invent a path or create one unasked.
-2. Gather from recent work: the current session's own changes, and every store location the taxonomy
-   declares (read AGENTS.md's "Placing a new note" section for the configured layers) — not backlinks, and
-   not a sample. A priority absent from every configured layer is not a store priority; treat it as the
-   operator's own working memory instead and leave it out.
-3. For each active priority, state its status, its purpose, and its next useful action — a priority with no
-   next action is not actionable, and one with no purpose is not a priority; resolve or downgrade it rather
-   than carry it silently.
-4. For each back-burner item, state plainly why it is not active right now — a size cutoff, a blocking
-   dependency, a deliberate deprioritization. An item with no stated reason for being dormant reads as
-   simply forgotten; do not leave one that way.
-5. Carry sunset candidates (work whose end state is in sight or whose relevance is fading) and operational
-   debt (deferred cleanup, known gaps, workarounds owed a real fix) as their own sections, separate from
-   active and back-burner priorities — never folded into either.
-6. Synthesize into a file — bullets throughout, short clauses; skip any empty section silently (never
-   "N/A", "none", or "TBD"). Nothing dated later than today; no editorializing beyond the status/purpose/
-   next-action shape above.
-7. Write: `ctxr rollup write <mission_path> --content-file <file>` — the same command `ctxr-rollup` uses for
-   an entity, applied here to the store's own mission path; an idempotent fenced write (`changed: false` and
-   a byte-identical file when the content matches; mismatched markers abort with nothing written).
+1. Resolve `<mission_path>` from the source line of AGENTS.md's "Mission" section. If no mission document is
+   configured for this store, STOP — this skill has nothing to maintain; do not invent a path or create one
+   unasked.
+2. Gather from recent work: the current session's own changes, the store log at `__LOG_PATH__`, and every store
+   location the taxonomy declares (read AGENTS.md's "Placing a new note" section for the configured layers) —
+   not backlinks, and not a sample. A priority absent from every configured layer is not a store priority; treat
+   it as the operator's own working memory instead and leave it out.
+3. Write the core, and only the core:
+   - **Primary mission** — one or two lines on what this store is for, right now.
+   - **Top priorities, in rank order** — three to five. Each names its status, its purpose, and its next useful
+     action; a priority with no next action is not actionable, and one with no purpose is not a priority —
+     resolve or downgrade it rather than carry it silently.
+   - **Not now** — what is deliberately set aside, one line each, so it is not mistaken for forgotten.
+
+   The core stays under `__MISSION_MAX_BYTES__` bytes; `ctxr doctor` fails above it. Per-item detail an agent
+   already finds elsewhere (a project's own next action, a status its note carries) is linked, not copied.
+4. Keep the register in a note the core links to, placed by `ctxr-placement` like any other: back-burner items,
+   each stating plainly why it is not active right now (a size cutoff, a blocking dependency, a deliberate
+   deprioritization); sunset candidates (work whose end state is in sight or whose relevance is fading); and
+   open operational debt (deferred cleanup, known gaps, workarounds owed a real fix). Debt that is closed is
+   history: record it in `__LOG_PATH__` and remove it.
+5. Propose, then write. The ranking and the mission are the operator's: show the proposed core and say what
+   moved and why, and write only once the operator confirms. A factual correction — a priority shipped,
+   blocked, or archived — is yours to make, and you say so in the report.
+6. Synthesize into a file — bullets throughout, short clauses; skip any empty section silently (never "N/A",
+   "none", or "TBD"). Nothing dated later than today; no editorializing beyond the shape above.
+7. Write: `ctxr rollup write <mission_path> --content-file <file>` — the same command `ctxr-rollup` uses for an
+   entity, applied here to the store's own mission path. It stamps the confirmation date AGENTS.md shows, and
+   is an idempotent fenced write (`changed: false` and a byte-identical file when the content matches;
+   mismatched markers abort with nothing written).
 
 ## Report
 
-Mission path, `changed` or unchanged, and what moved since the last write (a priority resolved, a new
-back-burner addition, a sunset candidate promoted or dropped). Anything outside the fence you want to fix
-is a separate, explicit edit.
+Mission path, `changed` or unchanged, what moved since the last write (a priority resolved, re-ranked, or
+added; an item moved to the register), and any factual correction made without confirmation. Anything outside
+the fence you want to fix is a separate, explicit edit.

package/templates/skills/ctxr-organize-audit.md

@@ -1,5 +1,7 @@
 1. Run `ctxr lint` for the full health report — orphan notes, broken links, uningested inbox material,
    catalog gaps. It always exits 0; its findings are observations for judgment, never a block.
+   After a lint pass, append `## [YYYY-MM-DD] lint | <one-line summary>` to `__LOG_PATH__`, with a bullet per
+   finding class you acted on — the log's last `lint` entry is how the next session knows one is due.
 2. Run `ctxr doctor` for the invariants that DO block: catalog coverage, hook health, and more. Address doctor's failures before `ctxr-submit`; it runs the same checks.
 
 ## Placement review
@@ -13,11 +15,19 @@ organized by actionability. Single-note calls go through `ctxr-placement`.
 ## Retiring: move, don't tag
 
 A status tag left in place defeats the layer — the active layers must show only active work.
-`ctxr archive <path>` moves the note into the configured archive location as a tracked rename; the
-note's frontmatter travels unchanged (never rewrite it on the move). Retiring is reversible cold storage,
-not deletion. Verify with `git status --short` showing `R` (a rename, history preserved), not a delete
+`ctxr archive <path>` moves the note to the same path beneath `__ARCHIVE_DESTINATION__` as a tracked rename, so
+the archive still shows where it lived and the reverse rename restores it. The note's frontmatter travels unchanged
+(never rewrite it on the move). Retiring is reversible cold storage, not deletion. Verify with `git status --short` showing `R` (a rename, history preserved), not a delete
 plus an add, then `ctxr catalog check`.
 
+A unit that lives as a folder of notes (a project with its supporting notes) is retired whole —
+`ctxr archive <folder>` moves it to `__ARCHIVE_DESTINATION__<folder>` as one tracked rename. Archiving its notes
+one by one leaves the unit half-retired until the last one moves.
+
+Every retirement records, in the past tense, what happened and when it was retired — in the hub note for a
+folder, as a blockquote at the top of a single note — so the item reads as a record, not as live work. When the
+item was one of the mission's priorities, hand it to `ctxr-mission`, which proposes what takes the freed slot.
+
 ## Stale rollups
 
 `ctxr lint`'s rollup-stale finding (and `ctxr rollup stale` directly) names entity notes whose backlinks
@@ -36,6 +46,20 @@ have moved since their last synthesis, or which have never been rolled up — ha
 
 ## Moves at scale
 
-Two commits, never a broken intermediate: commit 1 = the moves PLUS the wikilink fixes they require;
-commit 2 = tooling and doc patches. Before the moves, grep for hardcoded references to the old paths.
-After they land, rebuild the derived artifacts (`ctxr-derived-artifacts`) and re-run `ctxr lint`.
+A restructure that moves folders between layers is a migration. Run it in this order.
+
+1. **Snapshot, don't abort.** If the worktree holds unrelated uncommitted work, commit it first as
+   `WIP: pre-<slug> snapshot` and note that commit. It is the rollback anchor, and the baseline step 4 diffs
+   against.
+2. **Preflight.** Grep the whole store for the old path prefixes. That covers notes, skills, scripts and
+   generated config, but not `.git` or the session worktrees path. Every hit is a hardcoded reference the
+   move will break. A wikilink written with a path (`[[old/folder/Note]]`) breaks on the move, so rewrite it
+   to the bare name first. `ctxr doctor` reports links that resolve ambiguously; a collision the move would
+   create shows there afterwards.
+3. **Two commits, never a broken intermediate.** Commit 1 is the moves plus the wikilink fixes they
+   require, so the store is consistent after it alone. Commit 2 is tooling and doc patches.
+4. **Stage surgically.** Diff each staged file against the snapshot. A file whose diff is larger than the
+   migration's own edit is carrying unrelated drift: unstage it, restore it from the snapshot, re-apply only
+   the migration edit, and leave the drift for its own commit.
+5. **After they land,** rebuild the derived artifacts (`ctxr-derived-artifacts`), re-run `ctxr lint` and
+   `ctxr doctor`, and log the migration in the store log with the snapshot, move, and tooling commits.

package/templates/skills/ctxr-placement.md

@@ -31,6 +31,11 @@ clutter — worse than a slightly crowded existing one. Starting small and promo
 starting big and hollow is not. Make the promotion trigger a rule, not a vibe, and write it INTO the
 note: "Promote to its own top-level location the moment this holds 3+ distinct notes or topics."
 
+A unit that will carry supporting notes (a project with its research, an exploration with its evidence)
+gets a folder of its own. The graph clusters notes by their first __CLUSTER_DEPTH__ path segments, so
+grouping such units under one common parent at that depth merges their clusters, and the graph then asserts
+a relationship between them that does not exist.
+
 ## 4. What must never enter the store?
 
 Credentials, full account numbers, and secrets never enter the store — last-4 only. This is a placement

package/templates/skills/ctxr-publish.md

@@ -51,7 +51,8 @@ says something.
 When `gather` reports that an existing page belongs at the reported path too, it is because this
 subject is acquiring a second page, and a subject's pages collect under one folder naming it. Move
 that page there before you scaffold the new one, and tell the operator its URL changed — somebody
-may already be holding that link. `gather` moves nothing itself, and it names which signal counted
+may already be holding that link. `ctxr publish urls` reports the old address beside the new one, and
+`ctxr-submit` carries both into the pull request. `gather` moves nothing itself, and it names which signal counted
 the page as this subject's; read that before you move anything, because the signal is a reading of
 the page's README and can be wrong. Lead a page's source notes with the note it is a representation
 of — that lead link is what says whose page this is, and everything after it is a citation.