ctxr-cli 0.20.1 → 0.21.0

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,26 @@ 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.
 
 One capture per item. Two meetings in one file cannot be cited separately, deduplicated separately, or
 retracted separately.
@@ -33,7 +55,9 @@ 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.
 

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
@@ -18,6 +20,10 @@ note's frontmatter travels unchanged (never rewrite it on the move). Retiring is
 not deletion. Verify with `git status --short` showing `R` (a rename, history preserved), not a delete
 plus an add, then `ctxr catalog check`.
 
+`ctxr archive` moves one note. A unit that lives as a folder of notes (a project with its supporting notes)
+is retired whole: `git mv <folder> __ARCHIVE_DESTINATION__<name>`, then record in its hub note, in the past
+tense, why it left. Archiving its notes one by one would scatter them across a flat destination.
+
 ## Stale rollups
 
 `ctxr lint`'s rollup-stale finding (and `ctxr rollup stale` directly) names entity notes whose backlinks

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.

package/templates/skills/ctxr-second-opinion.md

@@ -13,6 +13,11 @@ what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
 - **Poll** when the question is *which of these is better?* and being wrong costs mild regret: a name, a
   framing, a piece of copy, which of several tools fits. If all three agreeing would settle it, it is a poll.
   If you would still want each reviewer's top objections and a suggested edit, it is a critique.
+A critique is required, not optional, before implementing a change that is architectural, irreversible, or touches
+what may be disclosed and to whom — run it on the written plan before the work, never as a justification after it.
+Its verdict, and the reasoning behind the option chosen, land in the pull request's body: for a structural change
+the pull request and its commit are the decision record, and there is no separate governance step.
+
 - **Answer directly** when there is one right answer, when the operator has already decided and wants
   confirmation, or when the work is read-only investigation.
 

package/templates/skills/ctxr-submit.md

@@ -23,13 +23,25 @@ pull request?" — needing to ask is itself the answer: leave, and let the work
 Ending a turn without that signal is normal and is not this skill. Say in one line what is uncommitted
 and which worktree holds it, then stop. The work is safe on the branch and the next message picks it up.
 
+## Routes
+
+Every pull request takes one of three routes. Say which, and why, in its body:
+
+- **Session** (the default): the session's work plus the capture it approved.
+- **Own**: a new skill, a structural change (folders, the entry document, conventions), or a refactor touching five
+  or more files — reviewed on its own so it is not buried in content.
+- **Housekeeping**: small appends nothing else depends on (a log line, a stray link fix), batched rather than folded
+  into unrelated work.
+
 ## Steps
 
 1. Re-scan (mandatory — never replay a plan from an earlier snapshot): `git fetch origin`,
    `git status --short`, `git diff --stat`, `git diff --cached --stat`,
    `git ls-files --others --exclude-standard`, `git log --oneline origin/__DEFAULT_BRANCH__..HEAD`. State moves
    under you while you work; name the delta from the previous scan rather than silently folding new work
-   into old buckets.
+   into old buckets. If the session touched or linked to an entity note, run `ctxr rollup stale --for <entity>`
+   (or a plain `ctxr rollup stale` when unsure which), and offer `ctxr-rollup` on anything flagged — never run a
+   rollup unasked; the operator decides.
 2. Capture pass: run `ctxr-session-capture` exactly once here — closing a session is itself a capture
    trigger; do not fire it again after submitting.
 3. Stage surgically: `git add <paths>`, never `git add -A`; confirm with `git status --short` that the
@@ -39,11 +51,23 @@ and which worktree holds it, then stop. The work is safe on the branch and the n
 5. Validate: run `ctxr doctor` (store scope, not `--staged` — a session's job is to leave the whole store
    healthy, not merely pass one commit's gate). Fix a failure; never bypass it, and never proceed past it.
 6. Commit: `git commit -m "<message>"`, describing the unit staged in step 3.
-7. Name the branch: if it still carries a generated name, `git branch -m "<name>"` before pushing — never
+7. Name the branch: `<prefix>/<short-slug>`, with a prefix from `skill/` `feat/` `project/` `notes/` `chore/`
+   `refactor/` `fix/` unless this store's conventions say otherwise. If it still carries a generated name,
+   `git branch -m "<name>"` before pushing — never
    let a generated name reach the forge. A name given at `ctxr session start` does not settle this: it
    named a worktree when the work began, and what ships is decided here.
-8. Run: `git push -u origin "<branch>"`, then `gh pr create --base __DEFAULT_BRANCH__ --title "<title>" --body
-   "<why / what changed / verification / follow-ups>"`. Do not stop to confirm first — the request to
+8. Before opening the pull request, run `ctxr publish urls --since origin/__DEFAULT_BRANCH__ --json`. When it
+   lists any page, the body gets a **Pages** section: a table with one row per page giving its status, its
+   preview address, and its published address — copied from the report, never rebuilt by hand. Mark a moved
+   page's old address as one that stops working, and a removed page's the same. Under the table state the
+   condition once: a preview resolves only while this pull request is open and the server can see this
+   session's worktree, and the published address resolves once the served checkout takes the landed commit.
+   When the report carries no preview, leave that column out; when it says no base URL is declared, say the
+   addresses are bare routes. When it lists no page, add no section.
+   Then run: `git push -u origin "<branch>"`, then `gh pr create --base __DEFAULT_BRANCH__ --title "<title>" --body
+   "<why / what changed / route / verification / follow-ups>"`. `gh` authenticates from its own credential
+   file: never export or interpolate a token, and never rewrite the origin's URL — it is a credential. The body answers those five questions; write the
+   why so a reviewer need not re-derive it. Do not stop to confirm first — the request to
    submit is the consent for both, and `ctxr doctor` in step 5 is the gate on this path. If `gh` has no
    reachable GitHub remote for this repository, `git push` still succeeds on its own — report the pushed
    branch and give the operator the manual pull-request instructions instead of retrying `gh`.