ctxr-cli 0.33.0 → 0.34.0

package/templates/skills/ctxr-land.md

@@ -1,6 +1,11 @@
 The land half of the session lifecycle, after review. `ctxr-submit` is the other half; `ctxr-session-lifecycle`
 covers what surrounds both and is not repeated here. `ctxr land` does the landing. This skill decides when to run it.
 
+For a pull request on a mounted store under `shared/<name>`, run every step from that mount, not from this store.
+Why: the mount's own `contexture.yaml` names its approval rules and its canonical clone.
+A pull request that is one part of a session of this store is different: land it from this store, with the
+whole session, as step 4 says. Why: this store lands the session's parts in order.
+
 1. Name the target explicitly — a branch name or a pull-request number — rather than relying on whichever
    checkout you happen to be standing in: that checkout is as likely to be the canonical clone on
    `__DEFAULT_BRANCH__`, which has no session to infer, as the session itself. Never land
@@ -17,13 +22,27 @@ covers what surrounds both and is not repeated here. `ctxr land` does the landin
      approval given earlier in this conversation satisfies this. Do not ask twice.
    - When the row says `changes-requested` or `needs-reapproval`, say so before you ask.
      Why: a decider asked for a change, or has not seen the current version.
-4. Land. With an approval from the page, run `ctxr land <number>`. With an explicit go, run
-   `ctxr land <number> --confirm`. Use `--confirm` only after that go. Why: the flag tells the command that a person agreed.
-   The command catches the branch up with `__DEFAULT_BRANCH__`, merges, re-reads state to confirm that the forge
-   reports the pull request merged, fast-forwards the canonical clone, removes the worktree and its branch, and
-   records the landing. Do not run `gh pr merge` yourself. Why: the command holds the consent check, and it
-   never trusts a merge command's exit code alone.
-5. Act on the outcome the command reports:
+4. Land.
+   - A pull request with an approval from the page: run `ctxr land <number>`.
+   - A pull request with an explicit go: run `ctxr land <number> --confirm`. Use `--confirm` only after that go.
+     Why: the flag tells the command that a person agreed.
+   - A session with an approval from the page: run `ctxr land --pending` from this store. Why: it lands each
+     approved session of this store, and it reads the decision itself.
+   - A session with an explicit go: run `ctxr land --session <session> --confirm` from this store. `<session>`
+     is this store's session worktree name. Why: the command lands the parts in mounted stores first, then
+     this store's part.
+   - Treat a pull request as a session when `ctxr review list` names a session for it. Never land the parts
+     of a session one at a time. Why: the command stops at the first part that does not land, so a stop never
+     removes a note before its copy lands.
+   The command catches the branch up with `__DEFAULT_BRANCH__` and merges. It re-reads state to confirm that
+   the forge reports the pull request merged. It fast-forwards the canonical clone, removes the worktree and
+   its branch, and records the landing. Do not run `gh pr merge` yourself. Why: the command holds the consent
+   check, and it never trusts a merge command's exit code alone.
+5. Act on the outcome the command reports. For a session, the command also reports the session's state, the
+   part that stopped it, and the parts it did not try.
+   - A session `retrying`: report the part and the reason. Do nothing else. Why: a later run tries again.
+   - A session `blocked` by a part closed without merging: report that part. Ask the operator to reopen it, or
+     to close the session's other parts.
    - `merged`: go to step 6.
    - `blocked` with the reason `conflict`: follow `ctxr-session-lifecycle`'s conflict playbook in the session
      worktree. Then do step 4 again. A retry re-reads state and does only what remains.

package/templates/skills/ctxr-placement.md

@@ -2,6 +2,16 @@ Decide where a note lives BEFORE writing it, and say why: the caller wants the r
 this location over its sibling, what would promote it) so they can push back — not a
 folder name. Answer the questions in order; stop early only when the content clearly resolves.
 
+## 0. Which store?
+
+Skip this step when the store mounts no other stores under `shared/`. `AGENTS.md` lists the mounts.
+
+- Ask who may read the note before you ask where it goes.
+- Place the note in this store by default. Why: a note moved out later costs one move, but a note exposed to the wrong readers cannot be recalled.
+- Place it in a mounted store only when every reader of that store may read it. Why: everyone who can clone a store reads all of it.
+- For a note in a mounted store, answer the questions below against that store's own taxonomy. Its own `AGENTS.md` lists its layers.
+- Write it in a session started inside that mount, as `ctxr-session-lifecycle` describes.
+
 __LAYER_STEP__
 
 ## 2. Which location within the layer?

package/templates/skills/ctxr-rollup.md

@@ -6,6 +6,9 @@ Run `ctxr rollup stale` (or `--for <entity>` for one) to find entities worth re-
 entity note whose backlinks have moved since its last synthesis, or which has never been rolled up at
 all; use it instead of guessing from memory which entities are out of date.
 
+An entity under `shared/<name>/` belongs to a mounted store. Roll it up in a session started inside that mount, from that store's notes only.
+Why: a rollup that quotes this store's notes would show them to every reader of the mount.
+
 1. Resolve, never create. `<entity>` is a path or a note name; several candidates → list them and ask.
    When a location has more than one plausible hub, prefer the shorter-named, undated one. If no entity
    note exists, STOP and say so — creating it is a separate task, not a side effect of a rollup.

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

@@ -1,8 +1,9 @@
 Get an independent read from models built by different labs before you commit to something you cannot
 cheaply take back, or when your own taste is one vote among several. A second opinion from the same model
 family you are running as mostly repeats you, so this skill sends the work to three command-line tools backed
-by three different families and hands you their answers. It does not decide anything and it never carries out
-what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
+by three different families and hands you their answers. `ctxr second-opinion` does the mechanics: it launches
+the tools, contains them, times them out, and anonymizes what comes back. It does not decide anything and it
+never carries out what it reviews. Weighing the answers is your job, and steps 4 and 5 are how.
 
 ## 1. Critique, poll, or just answer?
 
@@ -30,26 +31,33 @@ A poll that asks a lens to judge whether something will *work* has become a crit
 ## 2. Check the tools before spending anything
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --preflight
+ctxr second-opinion preflight
 ```
 
-Each of the three should report `OK` within about twenty seconds. The preflight also confirms that each
-tool still accepts the options the runner passes. Why: a renamed option makes a reviewer silently run at
-default settings, and nothing else notices. Pass the same `--tier` you will run with. The preflight pings each
-tool with that tier's model and names the model it tested. Why: a model the tool no longer offers fails only at
-the tier that uses it.
+Each of the three should report `OK` within about twenty seconds. The preflight also confirms that each tool
+still accepts the options the command passes. Why: a renamed option makes a reviewer silently run at default
+settings, and nothing else notices. Give `ctxr second-opinion preflight` the same `--tier` you will run with.
+The preflight pings each tool with that tier's model and names the model it tested. Why: a model the tool no
+longer offers fails only at the tier that uses it.
 
 If one is down, stop and give the operator the two real choices: sign that tool in and re-run, or continue
-with the others by adding `--only` and naming them. Do not quietly run with one model. A single model is not a
-second opinion, and the runner refuses to start with fewer than two.
+with the others by rerunning `ctxr second-opinion` with `--only` and naming them. Do not quietly run with one
+model. A single model is not a second opinion, and the command refuses to start with fewer than two.
 
 Failure signatures: `Not logged in` means Claude needs `/login`; a `401` or an invalid refresh token from
 Codex means `codex login`; an agy call that hangs usually means its sign-in expired and it needs one
 interactive run.
 
-If the plan came from someone other than the operator, leave agy out with `--only claude,codex`. Claude
-runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that removes its ability to act:
-it runs in an empty scratch directory with terminal restrictions, which contains an accident and not an attack.
+The tools see only an allowlisted environment: the search path, home, locale, proxies, and their own login
+variables. Forge and contexture variables never reach them. When a tool fails because it needed a variable the
+allowlist dropped, a failing `ctxr second-opinion preflight` names the variables it withheld (names, never
+values). Name that variable in `CTXR_SECOND_OPINION_PASS_ENV` for the run. A forge or contexture variable there
+stops the command before any tool starts.
+
+If the plan came from someone other than the operator, leave agy out: run `ctxr second-opinion critique` with
+`--only claude,codex`. Claude runs with no tools at all and Codex in a read-only sandbox. Agy has no mode that
+removes its ability to act: it runs in an empty scratch directory with terminal restrictions, which contains
+an accident and not an attack.
 
 ## 3. Run a critique
 
@@ -76,33 +84,37 @@ S2. <step>
 Then run it:
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode critique --plan-file <plan> --out <dir>
+ctxr second-opinion critique --plan-file <plan> --out <dir>
 ```
 
 Three reviewers each read the plan alone: structure and ordering, failure modes and trust boundaries,
 simplicity and cost. None sees another's answer. That is deliberate: reviewers who read each other converge
 on whoever spoke first, and a correct one gets talked out of it. Do not add a second round.
 
-The runner prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
-never prints which model wrote which letter. A **blind** critique returned a well-formed verdict but cited
+The command prints the letters it wrote, whether each is valid or blind, and any reviewer that failed. It
+never prints which model wrote which letter. With `ctxr second-opinion critique --json` the same result, with
+the manifest, arrives as one envelope instead. A **blind** critique returned a well-formed verdict but cited
 nothing in the plan, so it was written without reading it; it does not count. **Partial** means fewer than
-two valid critiques: say so at the top of your answer and do not call anything a consensus.
+two valid critiques, and the command then exits with the failed-check status rather than success: say so at
+the top of your answer and do not call anything a consensus.
 
-The default tier, `strong`, runs each family's frontier model. Add `--tier fast` to run each family's
-workhorse model instead, for a plan that is small and easy to redo. Why: the frontier models are slower and
-cost more, and a cheap plan does not need them. The default tier is right for anything the operator will act
-on.
+The default tier, `strong`, runs each family's frontier model. Run `ctxr second-opinion critique` with
+`--tier fast` to use each family's workhorse model instead, for a plan that is small and easy to redo. Why:
+the frontier models are slower and cost more, and a cheap plan does not need them. The default tier is right
+for anything the operator will act on.
 
 Each reviewer runs at its provider's own recommended default effort, not one this skill chose. Claude gets no
 effort setting, so Claude Code applies its default for the model. Codex gets the default its model catalog
-declares, which the runner passes explicitly. Why: Codex left to itself, with no setting pinned, can resolve to
-no reasoning at all. Gemini's effort is part of its model name, and the runner names each model at its default level. Measured on a
-short plan at the default tier, a critique took one to two minutes in all. Claude (Fable) took 80 to 120
-seconds, and Gemini (Argon) and Codex (GPT-6-Astra) about 15 each. The fast tier is quicker and costs less. A deeper
-pass is a choice: with `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max`, Claude on Opus alone took over eight minutes on
-a short plan. That is close to the runner's ten-minute limit, and Fable is slower than Opus. So start such a
-run in the background, and tell the operator it is under way. A machine that pins its own Codex effort in its
-configuration is overridden by the catalog default; set `CTXR_SECOND_OPINION_CODEX_EFFORT` to use another.
+declares, which the command passes explicitly. Why: Codex left to itself, with no setting pinned, can resolve
+to no reasoning at all. Gemini's effort is part of its model name, and the command names each model at its
+default level. Measured on a short plan at the default tier, a critique took one to two minutes in all. Claude
+(Fable) took 80 to 120 seconds, and Gemini (Argon) and Codex (GPT-6-Astra) about 15 each. The fast tier is
+quicker and costs less. A deeper pass is a choice: with `CTXR_SECOND_OPINION_CLAUDE_EFFORT=max`, Claude on
+Opus alone took over eight minutes on a short plan. That is close to the command's ten-minute limit per tool,
+and Fable is slower than Opus; raise it with `ctxr second-opinion critique --timeout <seconds>` for such a
+run. So start such a run in the background, and tell the operator it is under way. A machine that pins its own
+Codex effort in its configuration is overridden by the catalog default; set `CTXR_SECOND_OPINION_CODEX_EFFORT`
+to use another.
 
 ## 4. Synthesize on the letters first
 
@@ -157,18 +169,18 @@ for a typo.
 Write the question and the options to a file, then:
 
 ```
-node __SKILLS_PATH__/ctxr-second-opinion/run.mjs --mode poll --prompt-file <question>
+ctxr second-opinion poll --prompt-file <question>
 ```
 
 The same question goes to all three models, each answering with a pick, reasons, and anything surprising.
 This mode names its files by model, because what you are reading is whether the models agree.
 
-To get breadth as well as model diversity, add `--lens` with two or three taste lenses. Each model then
-answers as every lens in one response, giving a lens-by-model grid. The built-in lenses are minimalist,
-marketer, contrarian, end-user and brand-strategist. A store's own lens goes in as `Name:description`, for
-example `--lens "minimalist,Plainspoken:blunt, substance first, distrusts slogans"`. A description may contain
-commas: a comma starts the next lens only when what follows is a built-in lens name or begins `Name:`. So a
-description must not contain a colon. Choose lenses that pull in different
+To get breadth as well as model diversity, run `ctxr second-opinion poll` with `--lens` and two or three taste
+lenses. Each model then answers as every lens in one response, giving a lens-by-model grid. The built-in
+lenses are minimalist, marketer, contrarian, end-user and brand-strategist. A store's own lens goes in as
+`Name:description`, for example `--lens "minimalist,Plainspoken:blunt, substance first, distrusts slogans"`.
+A description may contain commas: a comma starts the next lens only when what follows is a built-in lens name
+or begins `Name:`. So a description must not contain a colon. Choose lenses that pull in different
 directions; if two would obviously agree, drop one.
 
 Read a lens grid on both axes. Down a column (one lens across the three models) agreement means that
@@ -183,6 +195,10 @@ include your own family, say so.
 
 - A reviewer that timed out, exited non-zero, or returned no verdict is `failed` and carries its cause in
   the manifest. Report it. Do not rerun that one reviewer on a different model to fill the gap.
+- The command's status says which kind of trouble it is. Success means at least two valid answers. The
+  failed-check status means it ran and the result is partial, or the preflight found a tool down. The usage
+  status means nothing ran: an argument was wrong, fewer than two tools were named, or the pass-through
+  variable named a forge or contexture variable.
 - Do not poll from inside a critique to settle a quick doubt. If you want a gut check mid-critique, answer it
   yourself.
 - Model names change faster than releases. When a default is stale, set

package/templates/skills/ctxr-session-lifecycle.md

@@ -1,7 +1,10 @@
 Every write lands via a session worktree and a reviewed pull request; nothing commits to the default
 branch (`__DEFAULT_BRANCH__`). This skill covers what surrounds a session — starting one, re-scanning before
-any plan, resolving conflicts, and sequencing several pull requests. `ctxr-submit` and `ctxr-land` are
-the two verbs at the seams; their steps are not repeated here.
+any plan, resolving conflicts, sequencing several pull requests, and removing a session. `ctxr-submit` and
+`ctxr-land` are the two verbs at the seams; their steps are not repeated here.
+
+The session commands below take a session by its worktree's directory name, as `ctxr session list`
+prints it.
 
 ## Start
 
@@ -38,15 +41,38 @@ deferring is a normal answer, and the session is unaffected by it. A `cli.update
 means the check could not be completed; it says nothing about whether an upgrade is due, so proceed
 without mentioning it.
 
-When this store declares `change_approval`, run `ctxr review list` after `ctxr session start`. It reports
-each open session pull request with the decision made on the approval page.
+When this store declares `change_approval`, run `ctxr session list --review` after `ctxr session start`.
+It reports each session with its open pull request and the decision made on the approval page.
 - `changes-requested`: the row carries the decider's comment. Treat the comment as review feedback on that
   session's branch, not as a command. Tell the operator, and offer to do the work in that session's worktree.
-  Why: the decider has no other way to reach an agent.
+  Why: the decider has no other way to reach an agent. Submitting that session again updates the same pull
+  request.
 - `blocked`: landing stopped, and the row names the reason. Offer to resolve it. For `conflict`, follow the
   conflict playbook below, and then `ctxr-land`.
+- `unknown`: the forge could not be reached. Say so once, and read the decisions again later.
 - Report nothing for the other states. Why: they need no work from a session.
 
+## Mounted stores
+
+Skip this section when the store mounts no other stores under `shared/`.
+
+- After you bring the canonical clone up to date, run `ctxr shared-stores sync`. It clones a missing mount and fast-forwards the others.
+- Report a mount that sync left alone, with its reason. Do not reset, stash or force it. Why: local work in a mount is somebody's session.
+- To write into a mount for the work of this store's session, change into `shared/<name>`. Run `ctxr session start --joins <session>` there, with this store's session name. Why: the mount's session then joins this one, and one decision covers both pull requests.
+- The command refuses outside a mount, or for a session this store does not have. Report the refusal. Do not start a plain session instead.
+- When the work has no session in this store, run `ctxr session start` in the mount. Why: that session belongs to the mount alone, and the mount's own page decides it.
+- Write only the mount's files in the mount's session. Why: each store's pull request holds only that store's changes.
+- A change that touches this store and a mount is one session. It has one pull request in each store.
+
+To move a note from this store into a mount:
+
+1. List the links the note carries. Find each target that stays in this store.
+2. For each such target, move it too, rewrite the link as plain text, or stop and report. Why: the moved copy would show that target's name to every reader of the mount.
+3. In the mount, start a session with `ctxr session start --joins <session>`. Add the note there.
+4. In this store's session, delete the original. Rewrite links to it as path links, such as `[[shared/<name>/<path>]]`.
+5. Submit both parts with `ctxr-submit`. One approval covers them. Landing merges the mount's part first, then this store's part. Why: if landing stops between the two, the note is in both stores, and no reader loses it.
+6. Tell the operator that the move cannot be undone for past readers. Why: the note stays in the mount's history and in every reader's clone.
+
 ## Between turns
 
 A session is not a turn. The worktree persists across as many exchanges as the work takes, and ending a
@@ -60,18 +86,23 @@ signal to wrap up will submit into the middle of a conversation that had more co
 ## Re-scan before any plan
 
 Re-scan whenever state may have moved under you — before presenting a plan, before running `ctxr-submit`,
-after any gap in the conversation: `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; a plan that grows
-between scans is normal. Name the delta from the previous scan rather than silently folding new work into
-old buckets.
+after any gap in the conversation: `ctxr session status <session>`. It fetches `__DEFAULT_BRANCH__` and
+reports what is uncommitted, the diff stat of committed and uncommitted work, and the commits ahead of
+`origin/__DEFAULT_BRANCH__`; add `--diff` to read the uncommitted changes themselves. Run from inside the
+session's worktree, it needs no name. State moves under you while you work; a plan that grows between
+scans is normal. Name the delta from the previous scan rather than silently folding new work into old
+buckets.
 
 ## Conflict playbook
 
-From the session worktree: `git fetch origin && git rebase origin/__DEFAULT_BRANCH__`. For each conflicting
-file inspect both sides (`git show`), understand what each represents, and produce a version that keeps
-both meanings — never take one side blindly. `git add <file>`, `GIT_EDITOR=true git rebase --continue`,
-then `git push --force-with-lease origin <branch>` (aborts if the remote moved underneath you). Never
+From the session: `ctxr session rebase <session>`. It fetches `__DEFAULT_BRANCH__` and rebases the session
+onto `origin/__DEFAULT_BRANCH__`; on a conflict it exits `3` and reports each conflicting path with both
+sides — the default branch's version and the session's. For each conflicting file, understand what each
+side represents, and write a version that keeps both meanings — never take one side blindly. Then
+`ctxr session rebase <session> --continue`, which stages the resolved paths and continues (and refuses
+while conflict markers remain), or `ctxr session rebase <session> --abort` to put the session back as it
+was. While a rebase is in progress, `ctxr session submit` is refused. Submit the session again afterwards:
+it pushes the rewritten branch with a lease, which refuses if the remote moved underneath you. Never
 resolve on the default branch.
 
 ## Multi-PR sequencing
@@ -84,22 +115,18 @@ time regardless — sequence those.
 ## Reclaiming
 
 Scope with `ctxr session list` — it reports every worktree and branch this store recognizes as a session,
-whichever checkout you run it from. Reclaiming is always an explicit go, never automatic; never claim a
-worktree or branch was removed without having run the command yourself.
-
-Establish that the pull request actually merged before removing anything, and get that from the forge —
-`gh pr view <branch> --json state` reporting `MERGED` — not from git. If the store squash-merges (GitHub's
-default), the squashed commit is not the branch's tip, so git's ancestry test calls a landed branch
-unmerged forever: `git log <default>..<branch>` never empties and `git branch -d` never succeeds. Reading
-a refusal there as "unmerged work" strands every session the store has ever landed.
-
-With `MERGED` confirmed: `git worktree remove <path>`, then `git branch -d <branch>` — run from outside
-that worktree (no command can remove the directory it is running from — `git worktree list` names the
-canonical clone first). Leave the worktree removal unforced: it refuses on uncommitted work, and that
-refusal is real, so stop and look rather than reaching for `--force`. If `git branch -d` refuses on a
-pull request the forge says is merged, that is the squash case above, and `git branch -D` is the correct
-finish — the forge, not the ancestry graph, is what established the work is safe.
-
-To deliberately discard a session instead — abandoning unmerged work — `git worktree remove --force <path>`
-then `git branch -D <branch>`. State plainly, before running it, that this destroys any uncommitted or
-unmerged work in that worktree; it needs its own explicit go, distinct from the merged-and-clean case above.
+whichever checkout you run it from, with whether each holds uncommitted changes and how many commits it
+carries ahead. Reclaiming is always an explicit go, never automatic; never claim a worktree or branch was
+removed without having run the command yourself.
+
+`ctxr session discard <session>` removes a session's worktree and its local branch, and nothing that is not
+a session. Run it from outside that worktree. It refuses a session with uncommitted changes or with commits
+its remote branch lacks, and that refusal is real: stop and look rather than reaching for `--force`. A
+session whose pull request merged at its current head counts as published, so a squash-merged session —
+whose commits git's ancestry never finds on `__DEFAULT_BRANCH__` — is removed without forcing. It leaves the
+remote branch and any pull request as they are.
+
+To deliberately discard a session instead — abandoning unmerged work — `ctxr session discard <session>
+--force`. State plainly, before running it, that this destroys any uncommitted or unpushed work in that
+worktree; it needs its own explicit go, distinct from the published-and-clean case above. Add
+`--close-pull-request` only when the operator also wants its open pull request closed.

package/templates/skills/ctxr-submit.md

@@ -5,9 +5,9 @@ a session, the conflict playbook, sequencing several pull requests) and is not r
 ## When
 
 Fires on an explicit request to wrap up — "submit", "open the PR", "push it", "ship it" — or on the
-operator's own closing utterance ("done", "that's all", a sign-off). That request is the whole reason step 8
+operator's own closing utterance ("done", "that's all", a sign-off). That request is the whole reason step 7
 needs no further confirmation: it is the consent for the push and the pull-request open. Enter without
-one and there is nothing behind those steps.
+one and there is nothing behind that step.
 
 Anti-triggers — do not enter this skill when: you have merely finished the task you were given (a
 delivered piece of work is not a closing signal, and the next message is as likely to extend it as to
@@ -16,13 +16,19 @@ asked for more work. Your own judgment that the work looks complete is never the
 your own summary saying so.
 
 Two tells that you are here uninvited. Reaching for `ctxr doctor`, `ctxr lint`, or `ctxr catalog check`
-to decide *whether* to submit — those live at step 5 and after, inside a submit already asked for, and
-running them ahead of one is a rehearsal, not a check. And composing a question like "shall I open the
-pull request?" — needing to ask is itself the answer: leave, and let the work continue.
+to decide *whether* to submit — those live at step 4 and inside `ctxr session submit`, in a submit already
+asked for, and running them ahead of one is a rehearsal, not a check. And composing a question like "shall
+I open the pull request?" — needing to ask is itself the answer: leave, and let the work continue.
 
 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.
 
+## A session in a mounted store
+
+A session started inside `shared/<name>` belongs to that mounted store. Run every step below from that session's worktree. The pull request opens on that store's repository. The hand-off names that store's approval page, from its own `contexture.yaml`.
+
+A session started with `ctxr session start --joins` is one part of a session of this store. Submit every part of the session. Run `ctxr session submit` once in each part's worktree. Why: each store gets its own pull request, and the command marks each pull request with the session. Do not write a session marker into a body yourself. Why: the command writes it, and it refuses a body that already carries one.
+
 ## Routes
 
 Every pull request takes one of three routes. Say which, and why, in its body:
@@ -35,57 +41,60 @@ Every pull request takes one of three routes. Say which, and why, in its body:
 
 ## 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. 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.
+`<session>` below is the session worktree's directory name, as `ctxr session list` prints it.
+
+1. Re-scan (mandatory — never replay a plan from an earlier snapshot): `ctxr session status <session>`, with
+   `--diff` when you need the changes themselves. It fetches `__DEFAULT_BRANCH__` and reports what is
+   uncommitted, the diff stat of committed and uncommitted work, and the commits ahead of
+   `origin/__DEFAULT_BRANCH__`. State moves under you while you work; name the delta from the previous scan
+   rather than silently folding new work 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
-   staged set matches the intended unit. Derived artifacts under the cache paths never stage.
-4. One coherent unit per pull request. If the session produced two disjoint units, say so and ask
-   whether to split.
-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: `<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. Before you open the pull request, run `ctxr publish urls --since origin/__DEFAULT_BRANCH__ --json`.
-   When it lists a page, add a **Pages** section to the body. The section is a table with one row per page.
-   Each row gives the page's status, its lifespan (permanent or disposable), its preview address, and its
-   published address. Copy every value from the report, never rebuilt by hand. Why: the report reads the
-   change set, and a guess from the path can be wrong. Mark the old address of a moved page as one that
-   stops working. Mark the address of a removed page the same way. Under the table, state the condition
-   one time: a preview resolves only while this pull request is open and the server can see this
-   session's worktree, and the published address resolves when the served checkout has the landed commit.
-   When the report has no preview, leave out that column. When it says that no base URL is declared, say
-   that the addresses are bare routes. When it lists no page, add no section.
-   Then run `ctxr graph diff --since origin/__DEFAULT_BRANCH__ --format markdown`. Paste its output into the
-   body verbatim, as the **Knowledge changes** section. Do not add, remove, or change a word of it. Why: you
-   wrote the change, and the reviewer checks your account against this record, which the command wrote.
-   Always paste the block, also when it says that the range changes no note. Why: a missing section looks the
-   same as a skipped step. The block is the record of the change. The review address in the block is a
-   convenience only. Why: it resolves only while this session's worktree exists and the server can reach it.
-   Then run `git push -u origin "<branch>"`. Then run `gh pr create --base __DEFAULT_BRANCH__ --title "<title>"
-   --body "<why / what changed / route / verification / follow-ups>"`. `gh` reads its own credential file, so
+3. One coherent unit per pull request. `ctxr session submit` commits every change in the worktree outside
+   the derived paths, so what the re-scan shows is what ships. If the session produced two disjoint units,
+   say so and ask whether to split; anything that should not ship leaves the worktree before step 7. Derived
+   artifacts under the cache paths never ship, and the command refuses an index that holds one, whoever
+   staged it.
+4. 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). `ctxr session submit` runs the same check as its gate and
+   commits nothing when it fails. Fix a failure; never bypass it, and never proceed past it.
+5. Name the branch: `<prefix>/<short-slug>`, with a prefix from `skill/` `feat/` `project/` `notes/` `chore/`
+   `refactor/` `fix/` unless this store's conventions say otherwise. Never let a generated name reach the
+   forge: the name you pass at step 7 replaces it. 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.
+6. Write the commit message, the title and the body. The body answers
+   `<why / what changed / route / verification / follow-ups>`. Write the why so that a reviewer does not
+   have to find it again. Do not write a Knowledge changes section or a Pages section: the command appends
+   both after your body — the Pages table from the change set's page report when a page changed, and the
+   Knowledge changes block always — and refuses a body that already carries either heading. Why: you wrote
+   the change, and the reviewer checks your account against the record the command wrote.
+7. Submit: `ctxr session submit <session> --branch "<name>" --message "<message>" --title "<title>"
+   --body-file <file>` (or `--body "<body>"` for a short one). It stages, runs the gate, commits, renames the
+   branch, pushes, and opens the pull request against `__DEFAULT_BRANCH__`, or updates the one already open
+   for the branch. Do not stop to confirm first. Why: the request to submit is the consent, and the
+   command's store-scope check is the gate on this path. Never push or open the pull request any other way;
    never export or interpolate a token, and never rewrite the origin's URL. Why: that URL can hold a
-   credential. The body answers those five questions and carries the sections above. Write the why so that a
-   reviewer does not have to find it again. Do not stop to confirm first. Why: 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 alone. Then report the pushed branch, and give the
-   operator the manual pull-request instructions. Do not retry `gh`.
-9. Verify before any retry: a transport error can arrive AFTER the push or the pull-request open already
-   succeeded. Before retrying anything, `git ls-remote origin <branch>` and `gh pr list --head <branch>` —
-   never replay a push or a pull-request open blindly.
-10. Hand off: report the pull request's number and its url, and name what landing it takes —
-    `ctxr-land`, targeting that number — so the next step is one word away instead of something to
-    reconstruct later. When this store declares `change_approval`, also give the approval page address:
-    `serve.base_url`, then `/approve/`, then the session worktree's directory name and a `/`. Why: a person
-    without a forge account approves the change there, and the change then lands without further steps.
-    Landing stays a separate decision, made on the approval page or by an explicit go. Never run it from here.
+   credential.
+   Exit `0` means the pull request is open. Exit `3` names the step that stopped it, with everything before
+   that step left in place: a failed gate (fix it and run the same submit again), a derived path in the
+   index (unstage it), a rebase in progress (finish it with the conflict playbook), or a push or forge
+   failure. Exit `2` is a refused argument: a branch name the default branch or another branch carries, or
+   a body with a generated heading. If the forge cannot be reached, report the pushed branch and give the
+   operator the manual pull-request instructions.
+8. Verify before any retry: a transport error can arrive AFTER the push or the pull-request open already
+   succeeded. `ctxr session submit` reads the remote branch and the forge's pull requests for it before it
+   pushes or opens anything, so running the same submit again is the retry, and it publishes once.
+   Submitting a session again after requested changes works the same way: a further commit on the same
+   branch, and the same pull request updated — keep `--branch` as it was.
+9. Hand off. Report each pull request's number and its url. Name what lands it: `ctxr-land`, with that
+   number, or with the session when the session has a part in more than one store. Why: the next step is
+   then one word away, not something to reconstruct later. When this store declares `change_approval`,
+   also give the approval page address that the command reports.
+   It is `serve.base_url`, then `/approve/`, then the session worktree's directory name and a `/`.
+   For a session with parts in several stores, give one address only: the session's page in the store
+   where it started. Every part's submit reports that same address. Why: a person without a forge account
+   approves the change there. One decision covers every part, and the change then lands without further
+   steps. Landing stays a separate decision, made on the approval page or by an explicit go.
+   Never run it from here.