arkgate 4.6.1 → 4.6.3

package/templates/agent-skills/ark-explore/SKILL.md

@@ -5,6 +5,15 @@ description: Map skill — decision-grade recon of layers + ArkRules opportuniti
 
 # /ark-explore — Recon the real project (map only)
 
+**When:** you need a map, or leftover design work remains after imports look green.
+**Not when:** the user wants edits applied (`/ark-autopilot`) or session 0 (`/ark-adopt`).
+
+## Steps
+
+1. Read `arkgate-check --doctor`.
+2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
+3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is
@@ -308,7 +317,7 @@ Prefer bets the user can run next (`command` / skill), not vague “improve DX
 | **Stabilize** | ENFORCE + honest baseline only for real debt | 0 new edges; doctor not lying about write path/CI |
 | **Shape** | One **golden** pattern + pilot cluster | Pilot smells cleared; rest is migrate-on-touch; B bets have success signals |
 
-ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out loud. It is **not** “healthy finished.”
+ENFORCE without Shape progress is leftover design work — say that out loud. It is **not** “healthy finished.”
 
 **Agent-detected design smells** (list any that apply; paths required — these may predate doctor IDs):
 
@@ -374,16 +383,16 @@ and the ranked **`pilotLoop.nextPilot`**.
 
 State **Mode: recon | dual-plan seed | shape-focus** and **Phase: Align | Stabilize | Shape** in the first lines.
 
-1. **Headline** — product one sentence + honesty (mode, governed%, false-green / semantic false-green / **ENFORCE·design-weak** / false-promise risk). ENFORCE is context, not the story.
+1. **Headline** — product one sentence + honesty (mode, governed%, false-green / leftover design work / false-promise risk). ENFORCE is context, not the story.
 2. **Map** — entry points, major dirs, shape name (or “no honest shape yet”). One screen. **Patterns concurrent** table when §B/§G requires it.
 3. **What I opened** — paths + sensors (include field/hook/origin when used).
 4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows.
 
-| # | Kind | Finding | Evidence (path) | Así te lo re-soluciono | Success signal | Next skill / command |
+| # | Kind | Finding | Evidence (path) | How to fix | Success signal | Next skill / command |
 
 Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto` | `agent-dx` | `design-weak`
 
-**Así te lo re-soluciono** must be concrete: files to touch, command to run.  
+**How to fix** must be concrete: files to touch, command to run.  
 **Success signal** must be falsifiable (see §F).
 
 5. **Field path summary**.

package/templates/agent-skills/ark-fix/SKILL.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for a small violation cluster. Deprecate
 
 # /ark-fix — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Gate violations and judgment remediations are
+**Not a first-run door.** This leftover name is a shortcut. Gate violations are
 **`/ark-autopilot`**. Do that job now. CLI only validates.
 
 ## Autonomy contract

package/templates/agent-skills/ark-loop/SKILL.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for driving plan A to zero. Deprecated a
 
 # /ark-loop — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
+**Not a first-run door.** This leftover name is a shortcut. Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
 Do that job now. Auto-apply only the four `mechanical-safe` kinds; judgment you write.
 
 ## Autonomy contract

package/templates/agent-skills/ark-place/SKILL.md

@@ -5,6 +5,15 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 # /ark-place — Where does this code go?
 
+**When:** you are adding a new file or artifact and need the layer, folder, and name.
+**Not when:** session 0 / config is missing or lying (`/ark-adopt`) or an existing violation cluster (`/ark-autopilot`).
+
+## Steps
+
+1. Bind identity if using MCP (`ark_identity` with the exact project root).
+2. Place the file (`ark_place` or read `ark.config.json`).
+3. Write it there. Then `arkgate-check`.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval. If the user described an artifact, **write the
@@ -155,7 +164,7 @@ the same files or weaken the gate.
 
 - If the user needs bulk adoption / wrong config, not a single artifact: **STOP — do not continue this skill as complete.** Switch to **`/ark-adopt`** (write the path) instead of ad-hoc multi-file grinding without a plan.
 - If the config lacks a home for the artifact: add the layer **in this turn**, then write the file.
-- If doctor is **ENFORCE · design-weak** and the user is asking to reshape existing structure
+- If doctor shows leftover design work and the user is asking to reshape existing structure
   (not place one new artifact): place only the new file under the golden/contract home, then
   hand off **one** pilot via `pilotLoop.nextPilot` / `/ark-explore` shape-focus — never multi-pilot
   batch reshape from this skill.

package/templates/agent-skills/ark-think/SKILL.md

@@ -5,8 +5,9 @@ description: Host-side architectural reasoning — 2–3 enforceable options on
 
 # /ark-think — Architectural reasoning (host LLM only)
 
-**Shortcut.** One decision only. Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** One decision only. Session 0 → **`/ark-adopt`**.
+Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You are the user's architecture thinking partner **inside** the project's Ark contract.
 This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -5,9 +5,16 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 # /ark-upgrade — managed ArkGate upgrade
 
-Upgrade the published `arkgate` package and its managed gates without treating a
-filename, package version, or similar-looking file as proof of ownership. The
-preview is the source of truth: inspect it before applying anything.
+**When:** bump the published `arkgate` package and refresh managed gates.
+**Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
+
+## Steps
+
+1. Preview: `arkgate upgrade` (no writes).
+2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
+
+The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
 
 ## Autonomy contract
 

package/templates/skills/ark-adopt.md

@@ -5,8 +5,17 @@ description: Session 0 — mark the Ark path. Greenfield scaffold or brownfield
 
 # /ark-adopt — Mark the path (session 0)
 
+**When:** empty tree, or the architecture config does not match the real folders (session 0).
+**Not when:** a single new file (`/ark-place`) or leftover design after the path is honest (`/ark-explore` then `/ark-autopilot`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (one light, one next action).
+2. Write `ark.config.json` (and a baseline only for genuine debt) in this turn.
+3. Re-run doctor. Day-to-day new files: `/ark-place`.
+
 Invoking this skill **is** the approval. Write the architecture config in this turn.
-Greenfield: scaffold like `--recommend` / today’s architect. Brownfield: match **product
+Greenfield: scaffold like `--recommend`. Brownfield: match **product
 reality**, freeze only genuine debt. A green check over a wrong config is a **false green**.
 
 ## Autonomy contract
@@ -36,7 +45,7 @@ write them in this turn. If they say the list is still right, leave it. Never in
 or auto-remove stewards.
 
 **Adopt is Align + Stabilize, then seed Shape.** Freezing debt without a pattern plan leaves
-spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
+spaghetti leftover design work. Always end with dual-plan **B** seeds (or handoff explore)
 when design smells remain after the contract is honest.
 
 ## Improvement compass (process preflight)
@@ -152,7 +161,7 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 2. **Product map** — what ships, which apps/packages, entry routes/CLIs.
 3. **Read real source** in largest ungoverned dirs and top import edges (min **12 files**
    across **≥4 dirs**).
-4. **“Así te lo re-soluciono”** — concrete layer globs, file moves, manifest/intent proposals.
+4. **“How to fix”** — concrete layer globs, file moves, manifest/intent proposals.
 5. **Suggestive burn-down** — ranked next steps after adopt (not only “baseline done”).
 6. Never freeze a concentrated edge without investigating contract smell / false-green.
 
@@ -182,7 +191,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    - Propose: Domain files, `intentPrefixes`, intent names (`Domain.*` / `Application.*`), kernel `defineIntent` stubs if runtime is used;
      land structure/invariant entries under `arkrules/<Layer>.json` **in this turn** (ADR 0015 routing).
    - Write the config; move pure rules into Domain when safe; validate with ark-check.
-   - Deliver section **“Así te lo re-soluciono en el manifiesto”** with before/after contract snippets.
+   - Deliver section **How to fix the architecture config** with before/after contract snippets.
 5. **Freeze only real debt** — `--update-baseline` (zero debt → **no empty baseline file** left behind).
 6. **Gates + skills** — `--install-agent-gates` (CI monorepo-aware when `frontend/package.json` exists).
 7. **Ratchet + Shape seed (mandatory exploratory close)** — after freeze/gates:
@@ -197,7 +206,7 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
 ## Operating modes
 
 Explain modes as **detected stages** (Setup / Align / Guard), not user settings.
-**Guard on the contract ≠ Shape done.** Say `ENFORCE · design-weak` when B residual remains.
+**Guard on the contract ≠ Shape done.** Say leftover design work remains when B residual remains.
 
 ## Verify
 

package/templates/skills/ark-architect.md

@@ -5,8 +5,8 @@ description: Shortcut to /ark-adopt for greenfield shape. Deprecated as a first-
 
 # /ark-architect — Shortcut to /ark-adopt
 
-**Deprecated as a first-class door.** Session 0 is **`/ark-adopt`**. Do that job now
-(greenfield scaffold via `ark-check --recommend` / MCP `ark_recommend` after `ark_identity`).
+**Not a first-run door.** This leftover name is a shortcut. Session 0 is **`/ark-adopt`**.
+Do that job now. Do not send the user to `/ark-contract` or `/ark-fix`.
 
 ## Autonomy contract
 

package/templates/skills/ark-autopilot.md

@@ -5,9 +5,16 @@ description: Apply Ark end-to-end — explore first; dual plan A (edges) + B (sh
 
 # /ark-autopilot — Apply the path
 
-**This is the apply door.** Invoking it **is** the approval. Prefer it when the user wants
-architecture cleaned end-to-end, not when they only need a map (`/ark-explore`). Doctor
-remains the control plane: re-check status after each major step.
+**When:** the user wants architecture cleaned end-to-end, or leftover design after a map.
+**Not when:** map only (`/ark-explore`), session 0 / config lying (`/ark-adopt`), or one new file (`/ark-place`).
+
+## Steps
+
+1. Read `arkgate-check --doctor` (do #1).
+2. Fix import-rule debt; if leftover design remains, apply **one** small refactor.
+3. Re-run doctor. Never weaken `ark.config.json`.
+
+**This is the apply door.** Invoking it **is** the approval. Doctor remains the control plane.
 
 ## Autonomy contract
 
@@ -81,7 +88,7 @@ decision-grade explore pass **and** without opening violating files.
 2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
 3. **Dual plan** always emitted (sections A and B).
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
-5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+5. **“How to fix”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 7. **One-pilot loop for B:** when leftover design / design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
    → apply **only** that pilot **in this turn** → **re-doctor**. Never multi-pilot batch B; residual
@@ -153,7 +160,7 @@ Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot rep
 Include explore **§G** when spaghetti / design-weak signals fire.
 
 1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise /
-   **ENFORCE·design-weak** risk).
+   leftover design work risk).
 2. **Map** — entry points, lived layout vs globs (one screen). **Concurrent patterns** table when ≥2 styles.
 3. **Phase ladder** — name **Align | Stabilize | Shape** (explore §G).
 4. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a` + internal norm.

package/templates/skills/ark-contract.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-adopt (session 0) or /ark-autopilot (later config
 
 # /ark-contract — Shortcut to adopt / autopilot
 
-**Deprecated as a first-class door.** Writing `ark.config.json` / `arkrules/*` is
+**Not a first-run door.** This leftover name is a shortcut. Writing `ark.config.json` is
 **`/ark-adopt`** at session 0 and **`/ark-autopilot`** afterward. Do that job now.
 
 ## Autonomy contract

package/templates/skills/ark-coverage.md

@@ -5,8 +5,9 @@ description: Ark adoption fitness audit — governed%, gates, baseline honesty,
 
 # /ark-coverage — Ark adoption fitness (not full recon)
 
-**Shortcut.** Fitness numbers only. Full map / leftover design → **`/ark-explore`**.
-Apply → **`/ark-autopilot`**. Session 0 → **`/ark-adopt`**. This is not `/ark-explore`.
+**Not a first-run door.** Fitness numbers only (governed files, gates, baseline).
+Session 0 → **`/ark-adopt`**. Leftover design → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You audit **how this repo uses ArkGate** (coverage, gates, baseline, host write path) and
 what adoption gaps remain. Work autonomously. End with a ranked fitness report.
@@ -56,7 +57,7 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 2. **Product surface** — name the app/package(s) in one line (not a full recon).
 3. **Read real source** in the top ungoverned / high-risk clusters (minimum **10 files**
    across at least **4 directories**). Prefer domain, features, adapters, routes — not only config.
-4. **“Así te lo re-soluciono”** for adoption gaps (globs, install, baseline, intents).
+4. **“How to fix”** for adoption gaps (globs, install, baseline, intents).
 5. If plan A is empty but you see design-weak / concurrent patterns / god modules:
    list them briefly and **STOP — do not continue this skill as complete** for pattern work —
    **handoff `/ark-explore` (dual-plan seed or shape-focus)**. Do not invent a second explore report here.
@@ -127,9 +128,10 @@ because governed% is 100% and plan is empty.
 **Honesty hard lines (doctor JSON):**
 - `coverageHonesty.worseThanNoGate` / weak coverage (~<50%): green is **worse than no gate**.
 - `baseline.honesty.dirtyBaselineRisk`: green-via-freeze may hide false-positive debt.
-- `writePath.honesty.softWriteHost` (Cursor / Codex / OpenCode): write path is **advisory /
-  best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
-- Do not invent hard write guarantees for soft hosts.
+- `writePath.honesty.softWriteHost` (OpenCode or another uncovered path): write path is
+  **advisory / best-effort**, not hard PreToolUse — required CI status is the hard merge boundary.
+- Cursor hard evidence is limited to trusted Write/StrReplace; Codex is limited to a complete,
+  trusted, runtime-observed local `apply_patch`. Do not borrow either claim for other paths.
 
 ## Related onboarding
 
@@ -159,7 +161,7 @@ because governed% is 100% and plan is empty.
 2. **Adoption map** — clusters you read for *fitness* (paths) — keep short.
 3. **Ranked table** (adoption residual + install/capability opportunities)
 
-| # | Kind | Gap / opportunity | Evidence (path or CLI) | Así te lo re-soluciono (concrete) | Next |
+| # | Kind | Gap / opportunity | Evidence (path or CLI) | How to fix (concrete) | Next |
 
 Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity` | `design-weak`
 
@@ -169,7 +171,7 @@ Kinds: `debt` | `false-green` | `shape` | `manifiesto` | `gates` | `opportunity`
 ## Done criteria
 
 - ≥10 source files read and cited; product surface named.
-- At least one **Así te lo re-soluciono** block with real paths or install commands.
+- At least one **How to fix** block with real paths or install commands.
 - CLI numbers used as evidence, not as the whole report.
 - Design residual either absent with evidence or explicitly handed to `/ark-explore`.
 

package/templates/skills/ark-explain.md

@@ -5,8 +5,9 @@ description: Explain this project's architecture in plain language and generate
 
 # /ark-explain — Understand this project's architecture
 
-**Shortcut.** Teach / HTML tour only. Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** Teach / HTML tour only. Session 0 → **`/ark-adopt`**.
+Map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.
 

package/templates/skills/ark-explore.md

@@ -5,6 +5,15 @@ description: Map skill — decision-grade recon of layers + ArkRules opportuniti
 
 # /ark-explore — Recon the real project (map only)
 
+**When:** you need a map, or leftover design work remains after imports look green.
+**Not when:** the user wants edits applied (`/ark-autopilot`) or session 0 (`/ark-adopt`).
+
+## Steps
+
+1. Read `arkgate-check --doctor`.
+2. Open the real tree (≥12 files across ≥4 dirs). CLI JSON alone is incomplete.
+3. Rank leftover work. Hand off to `/ark-autopilot` to apply one refactor. Do not write config or product code here.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval to **map**. Open the real tree. CLI JSON alone is
@@ -308,7 +317,7 @@ Prefer bets the user can run next (`command` / skill), not vague “improve DX
 | **Stabilize** | ENFORCE + honest baseline only for real debt | 0 new edges; doctor not lying about write path/CI |
 | **Shape** | One **golden** pattern + pilot cluster | Pilot smells cleared; rest is migrate-on-touch; B bets have success signals |
 
-ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out loud. It is **not** “healthy finished.”
+ENFORCE without Shape progress is leftover design work — say that out loud. It is **not** “healthy finished.”
 
 **Agent-detected design smells** (list any that apply; paths required — these may predate doctor IDs):
 
@@ -374,16 +383,16 @@ and the ranked **`pilotLoop.nextPilot`**.
 
 State **Mode: recon | dual-plan seed | shape-focus** and **Phase: Align | Stabilize | Shape** in the first lines.
 
-1. **Headline** — product one sentence + honesty (mode, governed%, false-green / semantic false-green / **ENFORCE·design-weak** / false-promise risk). ENFORCE is context, not the story.
+1. **Headline** — product one sentence + honesty (mode, governed%, false-green / leftover design work / false-promise risk). ENFORCE is context, not the story.
 2. **Map** — entry points, major dirs, shape name (or “no honest shape yet”). One screen. **Patterns concurrent** table when §B/§G requires it.
 3. **What I opened** — paths + sensors (include field/hook/origin when used).
 4. **Ranked table** — **only rows that change a decision**. Prefer **3–6** hard rows.
 
-| # | Kind | Finding | Evidence (path) | Así te lo re-soluciono | Success signal | Next skill / command |
+| # | Kind | Finding | Evidence (path) | How to fix | Success signal | Next skill / command |
 
 Kinds: `risk` | `false-green` | `debt` | `opportunity` | `shape` | `manifiesto` | `agent-dx` | `design-weak`
 
-**Así te lo re-soluciono** must be concrete: files to touch, command to run.  
+**How to fix** must be concrete: files to touch, command to run.  
 **Success signal** must be falsifiable (see §F).
 
 5. **Field path summary**.

package/templates/skills/ark-fix.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for a small violation cluster. Deprecate
 
 # /ark-fix — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Gate violations and judgment remediations are
+**Not a first-run door.** This leftover name is a shortcut. Gate violations are
 **`/ark-autopilot`**. Do that job now. CLI only validates.
 
 ## Autonomy contract

package/templates/skills/ark-loop.md

@@ -5,7 +5,7 @@ description: Shortcut to /ark-autopilot for driving plan A to zero. Deprecated a
 
 # /ark-loop — Shortcut to /ark-autopilot
 
-**Deprecated as a first-class door.** Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
+**Not a first-run door.** This leftover name is a shortcut. Driving `--plan` to `goal.met` is **`/ark-autopilot`**.
 Do that job now. Auto-apply only the four `mechanical-safe` kinds; judgment you write.
 
 ## Autonomy contract

package/templates/skills/ark-place.md

@@ -5,6 +5,15 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 # /ark-place — Where does this code go?
 
+**When:** you are adding a new file or artifact and need the layer, folder, and name.
+**Not when:** session 0 / config is missing or lying (`/ark-adopt`) or an existing violation cluster (`/ark-autopilot`).
+
+## Steps
+
+1. Bind identity if using MCP (`ark_identity` with the exact project root).
+2. Place the file (`ark_place` or read `ark.config.json`).
+3. Write it there. Then `arkgate-check`.
+
 ## Autonomy contract
 
 Invoking this skill **is** the approval. If the user described an artifact, **write the
@@ -155,7 +164,7 @@ the same files or weaken the gate.
 
 - If the user needs bulk adoption / wrong config, not a single artifact: **STOP — do not continue this skill as complete.** Switch to **`/ark-adopt`** (write the path) instead of ad-hoc multi-file grinding without a plan.
 - If the config lacks a home for the artifact: add the layer **in this turn**, then write the file.
-- If doctor is **ENFORCE · design-weak** and the user is asking to reshape existing structure
+- If doctor shows leftover design work and the user is asking to reshape existing structure
   (not place one new artifact): place only the new file under the golden/contract home, then
   hand off **one** pilot via `pilotLoop.nextPilot` / `/ark-explore` shape-focus — never multi-pilot
   batch reshape from this skill.

package/templates/skills/ark-think.md

@@ -5,8 +5,9 @@ description: Host-side architectural reasoning — 2–3 enforceable options on
 
 # /ark-think — Architectural reasoning (host LLM only)
 
-**Shortcut.** One decision only. Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
-Session 0 → **`/ark-adopt`**.
+**Not a first-run door.** One decision only. Session 0 → **`/ark-adopt`**.
+Full map → **`/ark-explore`**. Apply → **`/ark-autopilot`**.
+Do not send the user to leftover `/ark-contract` or `/ark-fix`.
 
 You are the user's architecture thinking partner **inside** the project's Ark contract.
 This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)

package/templates/skills/ark-upgrade.md

@@ -5,9 +5,16 @@ description: Upgrade ArkGate through a content-identity preview, preserve custom
 
 # /ark-upgrade — managed ArkGate upgrade
 
-Upgrade the published `arkgate` package and its managed gates without treating a
-filename, package version, or similar-looking file as proof of ownership. The
-preview is the source of truth: inspect it before applying anything.
+**When:** bump the published `arkgate` package and refresh managed gates.
+**Not when:** session 0 (`/ark-adopt`) or leftover design (`/ark-explore`).
+
+## Steps
+
+1. Preview: `arkgate upgrade` (no writes).
+2. Apply in this turn: `arkgate upgrade --apply` (needs `--plan-digest` when applying managed files).
+3. Re-run `arkgate-check --doctor`. Customized files stay unless you pass `--accept-conflicts` / `--refresh-skills`.
+
+The preview is the source of truth. Do not treat a filename or package version as proof of ownership.
 
 ## Autonomy contract