@remits/remits-cli 0.1.114 → 0.1.116

package/skills/remits-cli/references/development-loop.md

@@ -16,11 +16,14 @@
     - [Step 1: Understand the Request](#step-1-understand-the-request)
     - [Step 2: Make the Change](#step-2-make-the-change)
     - [Step 3: Stage to Platform](#step-3-stage-to-platform)
+      - [Stage your workset, not the whole repo](#stage-your-workset-not-the-whole-repo)
+      - [Three numbers, three questions](#three-numbers-three-questions)
     - [Step 4: Verify the Change](#step-4-verify-the-change)
     - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
     - [Step 6: Update Documentation](#step-6-update-documentation)
     - [Temporary Experiment Workflow](#temporary-experiment-workflow)
     - [Step 7: Commit and Durable Sync](#step-7-commit-and-durable-sync)
+      - [Verifying the COMMITTED variant, not your staging](#verifying-the-committed-variant-not-your-staging)
     - [Step 8: Close the Ticket](#step-8-close-the-ticket)
   - [User Confirmation Preferences](#user-confirmation-preferences)
 
@@ -93,6 +96,22 @@ This is how every development task should flow:
 #### Step 1: Understand the Request
 Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
 
+**Establish a steady git baseline before the first edit.** The platform syncs from the GitHub remote, not
+from your local files, and a worktree can be stale even when its staging lane is isolated. In the checkout
+you will edit:
+
+```bash
+git fetch origin
+git status --porcelain                         # empty, or only generated guide files you will discard
+git log origin/<branch>..<branch>              # empty: no local commits invisible to the platform
+git log <branch>..origin/<branch>              # empty: not behind the remote the platform syncs
+remits-cli components status
+```
+
+For a non-trunk variant branch, also run `remits-cli components promotion --branch <branch>`. If it reports
+that the branch is behind trunk or that overlays were computed from an old SHA, settle that before changing
+code. A workspace prevents staged-cache collisions; it does not make a stale branch current.
+
 **Establish the account's shape too, not just its components.** Read the `resolution` block in
 `account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
 place to change code, `resolution.relationships` shows whether the account has more than one parent (and
@@ -108,6 +127,11 @@ variants of these components exist: editing an origin component will drift them,
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
 
+Before changing a displayed value, helper, calculation, schema field, or prompt contract, read that
+component's existing `.meta.yml` sidecar too. Descriptions often carry dated decisions and line-number
+references explaining why a value looks odd. If you are reversing one, say so in the new sidecar text;
+otherwise you are probably reopening a closed bug.
+
 **Creating a component that does not exist yet.** Files are named `<id>_<Name>.<ext>`, where the numeric
 prefix is the platform's component id. A new component has no id, so name its files with the **`new_`
 prefix** and let the sync assign one (it then renames the files to that id):
@@ -153,10 +177,63 @@ overlay instead of pruning cleanly.
 #### Step 3: Stage to Platform
 
 ```bash
-remits-cli components stage
+remits-cli workspace use --auto          # once per checkout: your own lane
+remits-cli components stage --workset    # every edit: stage what you changed
 ```
 
-This uploads your local file changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+This uploads your local component changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+
+##### Stage your workset, not the whole repo
+
+There are three stage modes, and the difference decides what a run in your lane resolves and what a
+human watching the console sees:
+
+| Command | What it uploads | What the lane holds afterwards |
+|---|---|---|
+| `components stage --workset` | only the components git reports changed | **exactly those** — the lane is reconciled to your workset |
+| `components stage` | the whole repository manifest | **every component in the repo** (a full snapshot) |
+| `components stage --changed-only` | only the changed components | the changed ones **merged into whatever was already there** |
+
+**Use `--workset` for normal iteration.** A full stage is correct and safe, but on a real repository it
+puts a hundred-plus components into your lane, and every one of them then shadows committed source for
+any run in that lane until it expires. A human looking at `/admin/platforms` sees "115 staged" and cannot
+tell whether you edited 115 components or five.
+
+`--changed-only` MERGES. It cannot shrink a lane it inherited from an earlier full stage, so a lane can
+sit at 115 overlay entries while you are working on seven. The command warns when that happens; the fix
+is `--workset` (or `components clear --all` once, then keep using `--workset`).
+
+**When a full stage is the right answer:**
+
+- you deliberately want a complete snapshot of the repo in the lane;
+- you changed a `.meta.yml` sidecar and want removed keys reconciled against the whole repo;
+- you cannot tell what is stale in the lane and want a clean, known state (then `components clear --all`
+  when you are done).
+
+**An empty workset never clears your lane.** `--workset` on a clean working tree stages nothing and
+leaves the lane alone — reconciling to an empty manifest would delete the overlay your next test run
+depends on. Clearing stays explicit: `components clear --all`.
+
+**Deleting a component file cannot be verified by staging.** There is no staged "removal": clearing a
+staged entry falls back to the committed row, so the component still resolves. `stage --workset` reports
+those changes as NOT REPRESENTABLE.
+
+On a non-trunk variant branch, prove the removal through the durable variant plan:
+`remits-cli components sync --dry-run --summary --fail-on-errors` and read the removed/tombstone bucket.
+On trunk there is no dry-run plan; treat deletion as a high-risk durable reconcile and pass the full
+pre-sync safety check before running any mutating sync.
+
+##### Three numbers, three questions
+
+`components stage` and `components status` report all three, and so does the admin console. They are not
+interchangeable:
+
+- **workset** — components git reports this working tree changed. The work in flight.
+- **submitted** — what this command uploaded.
+- **overlay** — every staged entry the lane now holds. **This is what a run resolves.**
+
+A missing answer is printed as `unknown`, never as `0`: "git could not answer" and "git says nothing
+changed" are different facts and only one of them is a number.
 
 **THE STAGE-BEFORE-RUN RULE:** You MUST run `remits-cli components stage` after EVERY file edit and BEFORE any test run or verification. The platform executes whatever version is in the staging cache at the moment the test starts. If you edit a file and run a test without staging first, the test runs the OLD code — not your changes. This is the single most common mistake. Never skip staging. The sequence is always: **edit → stage → run**.
 
@@ -272,7 +349,7 @@ If the work is tied to a support ticket:
 
 Before committing, update metadata so the next session understands what changed:
 
-1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file.
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
 2. **`README.md`** — If the change affects account-level capabilities or workflows.
 3. **New components** — Always fill in `.meta.yml` immediately.
 
@@ -289,13 +366,16 @@ Redis cache can affect later test/tool runs, so always clear it after restoring
 
 ```bash
 # make temporary local edit
-remits-cli components stage
+remits-cli components stage --workset
 remits-cli test run --test <id-or-name> --names "<case name>"
 git restore <file>
 remits-cli components clear --all
 remits-cli components status
 ```
 
+With `--workset` the restore-and-clear is belt and braces rather than the only thing standing between
+the experiment and a later run: the lane only ever held the component you were experimenting on.
+
 For narrower cleanup when only one staged component should be cleared:
 
 ```bash
@@ -316,17 +396,56 @@ This separates the local failure boundaries cleanly:
 1. Local git commit
 2. Remote push
 
-After the push, run the **`component-integrity.md`** safety checks before any durable platform sync. Do not run
+After the push, run `git fetch origin` and confirm both local and remote agree on the branch you are about
+to sync:
+
+```bash
+git log origin/<branch>..<branch>              # empty
+git log <branch>..origin/<branch>              # empty
+```
+
+Then run the **`component-integrity.md`** safety checks before any durable platform sync. Do not run
 `remits-cli components sync` when local files, `account-info.json`, and live inventory disagree about component
 IDs or when unexpected deletes/renumbers are present.
 
 Only after those checks pass, and only when the user intends to promote the repo to the platform database:
 
 ```bash
+# On a VARIANT branch — the recommended path. Dry-runs first and refuses a surprising plan.
+remits-cli components sync --safe
+git pull --ff-only origin <branch>
+
+# On TRUNK — there is no plan to gate, so --safe explains what a trunk reconcile does and needs --yes.
 remits-cli components sync
 git pull --ff-only origin <branch>
 ```
 
+`--safe` expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves the
+comparison base from this branch's merge base with trunk when you did not pass `--changed-since`, and
+prints the planned writes before mutating unless you pass `--yes`. It refuses when the plan would write
+components this checkout did not change — which is exactly what a branch that is BEHIND trunk produces,
+because it still physically carries old copies of files nobody on it touched, and a variant sync turns
+each of those into an unrelated override. When it refuses that way, merge trunk into your branch, push,
+and re-run the same command.
+
+When a removal is intended, name it rather than disabling the gate:
+
+```bash
+remits-cli components sync --safe --expected-removed action:50
+```
+
+`--force-tombstones` stays explicit and human-owned. Never pass it to get past a refusal.
+
+##### Verifying the COMMITTED variant, not your staging
+
+After a sync, staged entries still win for CLI-scoped runs, so a test that passes may be testing your
+staging rather than what you just committed. Clear the lane first:
+
+```bash
+remits-cli components clear --all
+remits-cli test run --test <id-or-name> --as-account <subscriber-id>
+```
+
 `remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations,
 and it is capable of reconciling creates/deletes/renames from the remote repository into the database. Treat it
 as a gated promote/reconciliation command, not as an exploratory command or fallback.
@@ -340,6 +459,29 @@ unexpectedly, stop and inspect the repo-local session log before running any mut
 
 **Git is required for durable sync.** The platform syncs by pulling from the git remote (`GitHubClient.syncFromRepository`). If `git push` fails, the server has nothing new to sync. You can still **stage** and **test** without git — only durable sync requires it.
 
+**Landing is serial, and the platform now enforces it.** `components commit` takes a short exclusive
+landing lease on `(account, branch)` before it pushes, and `components sync` takes it too. If another agent
+is landing that branch you are refused with a sentence naming who holds it and how long is left:
+
+```
+Refused: Branch 'forked' on account 33 is being landed by dev@acme.test in /Users/dev/wt/acme-a ...
+Keep staging and iterating — staging is lane-isolated — and land when this clears.
+```
+
+Do exactly that. **Do not loop on the refusal**: the lease is minutes at most, staging and testing are
+unaffected because they are lane-isolated, and retrying in a tight loop just burns the run. The reason it
+is serial at all is that `git add -A` sweeps a shared checkout and the platform pushes a regenerated
+`account-info.json` back to the branch during sync, so two commits racing one branch collide on the remote.
+
+**Staging also refreshes your presence.** You do not need `remits-cli agent register` for other agents to
+see you: `components stage` records `(user, checkout, branch, workspace)` so headless workers on other
+machines find you in their "current repository activity" block instead of assuming the repository is
+theirs. A derived record is never routed work.
+
+**An account may make `commit` a refusal outright.** A `no-commit` rule in its `OPERATIONS` process means
+the platform refuses the landing lease and the sync — leave your changes in the working tree and describe
+them on the ticket. Read `support-tickets.md` §"Some of that process is enforced, not requested".
+
 #### Step 8: Close the Ticket
 
 If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:

package/skills/remits-cli/references/investigation.md

@@ -187,7 +187,10 @@ Before starting an investigation outside the confirmed current repo:
 8. `mcp_user_activity` — for "user X is slow right now" reports, list sessions by `userId`/`accountId`, open the session story, and use the returned beat pivots.
 9. `mcp_performance_trace` — for slow/sluggish reports, open the beat `traceId` with `action:"trace"`; use `action:"slowest"` when you only have a broad time window.
 10. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
-11. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+11. If no local checkout exists for the responsible implementation account, use
+    `mcp_component_view`/`mcp_component_grep` to explain how the component works. If the repo exists on
+    this machine, inspect the branch/files there instead; the remote component tools are fallback and
+    live-DB comparison surfaces, not the starting point for source comprehension.
 
 **Slow / sluggish user report:**
 

package/skills/remits-cli/references/support-tickets.md

@@ -11,10 +11,12 @@
 - [Support Ticket Mental Model](#support-ticket-mental-model)
   - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
   - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
+  - [Serving only some workstreams](#serving-only-some-workstreams)
   - [The manual loop](#the-manual-loop)
   - [If you are the worker](#if-you-are-the-worker)
   - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
   - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
+  - [Some of that process is enforced, not requested](#some-of-that-process-is-enforced-not-requested)
   - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
   - [Agent components are workers too](#agent-components-are-workers-too)
   - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
@@ -80,10 +82,17 @@ and it expires on its own so a killed worker cannot park a ticket forever. You d
 remits-cli agent serve                          # workers are whichever agent THIS session is
 remits-cli agent serve --worker-agent codex --max-concurrent 2
 remits-cli agent serve --mode investigate       # read-only workers: no file edits
+remits-cli agent serve --serves support,sdlc    # only these workstreams are routed here
 remits-cli agent workers                        # what is running right now
 remits-cli agent release                        # stop serving, go offline
 ```
 
+`--mode investigate` is still autonomous ticket work. The supervisor claims a ticket, launches a
+worker, and the worker should read/reproduce/localize the issue and update the ticket with useful
+findings or a handoff. What it must **not** do is become the repository editor: investigation-mode
+polls do not acquire or renew the repo edit lease, and the brief explicitly forbids file edits,
+component staging, commits, and `remits-cli ticket lease`.
+
 **Run it in a plain terminal tab.** That tab becomes the agent host: `serve` returns immediately, a
 detached supervisor is anchored to the tab's shell, and closing the tab stops the agent. Nothing in
 that tab is an AI session — the AI only ever appears as the worker processes the supervisor spawns.
@@ -111,6 +120,33 @@ runs, reporting the worker's activity to the dashboard, dropping the claim when
 failed ticket once, and releasing a ticket back to the queue when it has failed too often. Closing
 the terminal stops everything and hands any in-flight work back.
 
+### Serving only some workstreams
+
+`--serves` declares which of the account's **workstreams** this machine covers, so a fleet can be a
+set of queues rather than a pool of interchangeable machines:
+
+```bash
+remits-cli agent serve --serves support,incident --mode investigate   # the support desk box
+remits-cli agent serve --serves sdlc --max-concurrent 2               # the engineering box
+```
+
+The names are the account's own — the platform compares them and learns nothing about any of them.
+Read `remits-cli ticket queue --workstream ...` or the account's `OPERATIONS` prompts to find out
+what this account calls its processes; do not invent names.
+
+**Omit it unless the user asked for it.** A session that declares nothing is a generalist and takes
+everything, which is the right default and what every existing fleet does. Specialising has a real
+cost: a specialist is only routed tickets in its workstreams *and its unrouted sweep takes only
+those*, so a workstream no live session covers is routed to nobody. The platform reports that rather
+than quietly overriding the declaration —
+
+- `dispatch` answers `reason: 'no_agent_serves_workstream'` and names what the live sessions do cover;
+- `agent map` prints each session's declared queues;
+- the supervisor logs `serve.out_of_scope` when it passes over unrouted work it does not serve.
+
+**So after specialising a fleet, run `remits-cli agent map`** and confirm every workstream the
+account ingests is covered by something.
+
 ### The manual loop
 
 Only when the session registered with `agent register` rather than `agent serve`.
@@ -137,6 +173,15 @@ timer.
 local directory through `~/.remits-cli/account-repos.json` and `cd` there before making changes. You
 registered from anywhere; you do not fix anything from anywhere.
 
+For subscriber/fork tickets, this is also the investigation starting point. The reporting account may be
+the fork or client that observed the issue, while `implementationAccountId` names the repo whose branch
+contains the front-stage source. Read the ticket, run/inspect the run context (`ticket where` when useful),
+open the indexed implementation repo, then establish the relevant branch's steady starting state before
+the first edit: fetch origin, fast-forward the branch, and confirm local and remote have no commits missing
+from either side. Then read `account-info.json` and the component files. Use `mcp_component_view` /
+`mcp_component_grep` only when that repo is unavailable locally or when explicitly comparing live DB source
+to the files.
+
 **Capacity is real, not advisory.** A serving session tells the platform how many workers it can run
 (`--max-concurrent`, default 1), and the router will not send it more than that. So a session at
 capacity is skipped in favour of one that is free, rather than accumulating tickets it will never
@@ -155,6 +200,14 @@ headless run is invisible otherwise), and **end in a terminal state** — `compl
 resolution, or `update_status` with what you established and what the next agent should try. Exiting
 quietly leaves a ticket that looks in-flight forever.
 
+**If your brief says this is not the first autonomous run on this ticket, believe it.** Earlier runs
+picked it up and handed it back unfinished; whatever they tried did not work, so repeating it will not
+work either. Read what they recorded, then either take a genuinely different approach or **stop and
+ask** (`remits-cli ticket ask`). Asking is a complete, successful outcome, and it is the right one when
+the obstacle is not something a run can remove. Accounts cap how many times a ticket may be picked up
+and handed back — past that the ticket stops being offered to workers at all and waits for a person, so
+a run that exits quietly at the limit has cost every earlier run as well as its own.
+
 ### Before you edit anything: where you are, and whether you may
 
 Presence answers *who*. Two more facts answer *whether you may edit*, and with git worktrees and
@@ -185,12 +238,31 @@ Four things are worth knowing and are not obvious:
 - **A staging workspace does not replace the lease.** Separate lanes stop two runs *resolving* each
   other's staged code; they do nothing about two processes writing the same files or pushing the same
   branch, which is what actually destroys work.
-- **One editing worker per repository account per lane — worktrees do not change this.** Two worktrees
-  of one repo push to the same branch on the same remote, so per-directory leases would trade file
-  conflicts for non-fast-forward push conflicts, which surface later and are worse.
-- **A spawned ticket worker already has its own staging lane** (`REMITS_WORKSPACE=ticket-<id>`). You do
-  not set it, and your brief states it. Say which lane you staged into when you report what you verified
-  — somebody looking at the shared lane will not see your changes.
+- **You are not restricted to trunk, and you do not choose the branch.** You work on whatever branch your
+  checkout is on — `ticket where` prints it — and nothing switches it underneath you. Separately, if this
+  account subscribes to a **component variant branch**, its variant components (including its
+  `OPERATIONS` process) resolve for you automatically, server-side, without you doing anything. Those are
+  two different facts and only the first is about your files. Load `branch-variants.md` before working in
+  a non-trunk checkout.
+- **The edit lease excludes per repository account and lane, NOT per branch.** So an agent editing a
+  different branch of this same repository still blocks you, even though your files and your pushes would
+  not collide. That is deliberate over-exclusion, not a bug — investigate read-only and hand off, exactly
+  as for any other refusal.
+- **A spawned local ticket worker owns its checkout grounding and already has its staging lane.** For
+  repository work, `remits-cli agent serve` appends the local repository checkout, target branch and a
+  suggested per-ticket worktree path. Before editing, create or choose an isolated worktree appropriate to
+  the ticket. For a ticket with no component branch subscription, the target branch is the repository
+  default before it is the launch checkout's current branch. The supervisor sets
+  `REMITS_WORKSPACE=ticket-<id>` for you; if you choose a detached worktree, export
+  `REMITS_GIT_BRANCH=<branch>` before running `remits-cli`. A worktree is a checkout-isolation tool, not
+  a freshness proof: fetch, fast-forward and prove `HEAD...origin/<branch>` is `0  0` before the first
+  edit, following `multi-agent-development.md`.
+- **GCP Agent components do not get a local checkout.** The same ticket brief can name a component branch
+  subscription, but for a GCP Agent component that is component-resolution context, not a filesystem
+  instruction.
+- **One editing worker per repository account per lane is still the server lease rule.** The worker-owned
+  worktree protects a human's checkout from the spawned worker; it does not make the edit lease
+  per-directory. A branch-aware edit lease with same-branch exclusion is a separate design.
 
 `unlease` returns **your own** lease and deliberately cannot touch anybody else's. Breaking a stale one
 is a separate, human verb: `remits-cli ticket force-unlease --ticket ID --reason "..."`.
@@ -213,6 +285,27 @@ from the prompt, so **edit the prompt, not the file**.
 `workstream` is not `type`: a type classifies the request, a workstream names the procedure, and they
 cross — a `defect` handled by incident response out of hours goes through the SDLC in the morning.
 
+### Some of that process is enforced, not requested
+
+Part of an account's process can be **deterministic**. If your brief has a `## Rules you will be held to`
+section, those rules are enforced by the platform at the write door — the verb is refused, not
+discouraged.
+
+- **Read that section before you act.** A refusal you were warned about costs one command; a refusal you
+  were not costs the run.
+- **A refusal is an ANSWER.** The message names the rule and says what to do instead. Act on that
+  sentence. Do not retry the identical call, and do not go looking for another door — the rules govern the
+  DSL, the MCP tools and this CLI identically.
+- **`[require]` rules mean a human.** You cannot acknowledge one: the platform decides "human" from the
+  absence of an agent run identity, which your commands always carry. Record what you found with
+  `ticket progress` and hand off.
+- **`[warn]` rules let the call through and write a `policy` worklog entry.** Mention it in your handoff.
+- **If you see "POLICY NOT ENFORCED"**, the account's rules could not be parsed. Do not read the absence
+  of a refusal as permission — say so on the ticket. It is a defect in the account's `OPERATIONS` prompt.
+
+The same rules govern `components stage` and `components commit`. A `no-commit` rule is why
+`remits-cli components commit` refuses rather than asks.
+
 ### Seeing the queue as a human does
 
 `remits-cli start` opens a browser control center showing the same facts you are acting on: which
@@ -385,5 +478,6 @@ Sandbox note:
 Use the same repo/context rules as other tools:
 - If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
 - Read `~/.remits-cli/account-repos.json` before choosing which local repo to open.
-- If the correct repo for the relevant account type exists locally, switch there and inspect `account-info.json` and `/components`.
+- If the correct repo for the relevant account type exists locally, switch there, confirm/pull the relevant
+  branch when clean, and inspect `account-info.json` and `/components`.
 - If the repo is not available locally, use `mcp_account_view`, `mcp_component_view`, and `mcp_component_grep`.

package/skills/remits-cli/references/tool-reference.md

@@ -880,7 +880,7 @@ When a component "can't find" an obviously-present document, run `action:'inspec
 first — that shows what was indexed, which is usually the answer.
 
 ### `mcp_get_guide`
-Load the packaged front-stage guides — the same `docs/guides/` set `remits-cli` syncs into a repo. Use it when
+Load the packaged front-stage guides — the same `docs/front-stage/` set `remits-cli` syncs into a repo. Use it when
 you are working **outside a repo** (or the repo's `guides/` is stale) and need the authoritative guidance
 before writing a component.
 

package/skills/remits-cli/references/troubleshooting.md

@@ -81,7 +81,7 @@ with `REMITS_PLATFORM_DIR`); `remits-cli` clones it on first authenticated run i
 
 Apply the boy-scout rule to the guides themselves: **whenever you only solved the problem by reading the
 core back stage because a front-stage guide was unclear or missing — even when there was no platform
-defect at all — open a guide-only PR** updating the relevant guide in the platform repo's `docs/guides/`,
+defect at all — open a guide-only PR** updating the relevant guide in the platform repo's `docs/front-stage/`,
 which is the source served to every account repo. Better guides over time are an explicit goal.
 
 #### Escalation Bundle (tooling/operational issue)