@ericrisco/rsc 2.0.19 → 2.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 [![npm](https://img.shields.io/npm/v/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=npm)](https://www.npmjs.com/package/@ericrisco/rsc)
 [![downloads](https://img.shields.io/npm/dm/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=downloads)](https://www.npmjs.com/package/@ericrisco/rsc)
-[![skills](https://img.shields.io/badge/skills-273-63d68a?labelColor=12161c)](#the-catalog)
+[![skills](https://img.shields.io/badge/skills-270-63d68a?labelColor=12161c)](#the-catalog)
 [![license](https://img.shields.io/badge/license-MIT-63d68a?labelColor=12161c)](LICENSE)
 [![stars](https://img.shields.io/github/stars/ericrisco/rsc-harness?color=63d68a&labelColor=12161c)](https://github.com/ericrisco/rsc-harness/stargazers)
 
@@ -42,8 +42,8 @@ Open standards already cover individual parts — [Agent Skills](https://agentsk
 which complete harness this project needs. rsc-harness does that job through one guided flow:
 
 1. **You state the outcome.** No skill, hook or MCP vocabulary required.
-2. **The wizard reads only the project root** and asks technical level, accompaniment, project kind,
-   goal and assistants.
+2. **The wizard reads only the project root** and asks how technical to talk, project kind, goal and
+   assistants.
 3. **A proportional plan explains every choice.** Selected, deferred and excluded pieces all have a
    reason. Nothing writes before you accept the exact plan.
 4. **The result is verified.** Shared sources prevent duplication; knowledge loads progressively;
@@ -66,8 +66,8 @@ project they're equipping** — not inside a clone of this repo (see the note un
 npx @ericrisco/rsc@latest onboard
 ```
 
-That launches the binding plain-language onboarding. It asks the user for technical level,
-accompaniment, project kind and goal **before it writes anything**, reads only the selected project
+That launches the binding plain-language onboarding. It asks the user how technical to talk
+(technical or with analogies), project kind and goal **before it writes anything**, reads only the selected project
 root, and shows every selected or deferred skill, agent and hook with its reason. Relay those
 questions to the user; never invent or default their answers. The first pass writes nothing and
 prints a SHA-256 plan id. Only rerun with `--accept-plan <id>` after the user accepts that exact plan.
@@ -78,11 +78,11 @@ regenerating the plan keeps theirs.
 For a non-interactive agent, collect the answers and preview the same plan explicitly:
 
 ```bash
-npx @ericrisco/rsc@latest onboard --technical-level mixed --accompaniment L1 \
+npx @ericrisco/rsc@latest onboard --technical-level technical \
   --project-kind software --goal "small compound-interest website" \
   --software-scope small --target codex
 # After the user accepts the printed plan:
-npx @ericrisco/rsc@latest onboard --technical-level mixed --accompaniment L1 \
+npx @ericrisco/rsc@latest onboard --technical-level technical \
   --project-kind software --goal "small compound-interest website" \
   --software-scope small --target codex --accept-plan PRINTED_SHA256_ID
 ```
@@ -131,6 +131,24 @@ is which one you land in by default, and who decides.
 
 ---
 
+## 🗣️ It talks so you understand
+
+Agents assume you saw their reasoning, and they write too much. rsc fixes the voice, not the reader.
+
+- **Short sentences, one idea each.** The style comes from ASD-STE100, the controlled writing of
+  aircraft maintenance manuals, applied at about 80% and in your language.
+- **Every answer stands alone.** No "that fix" or "the second commit": the answer names the thing,
+  with the minimum context to understand it.
+- **One question at install:** technical, or with analogies. That is the only setting.
+- **A ladder when you do not follow.** Text first. Then one diagram. Then one HTML page. A video
+  only if you ask for it.
+
+Every turn still closes with the compass: where you are, and the next step as a question. The voice
+lives in `orient`, which every harness installs. Text you send to other people (emails, posts,
+READMEs) goes through `unslop` instead: it sounds like a person and carries no AI tells.
+
+---
+
 ## Why this exists
 
 An improvised harness tends to grow by accumulation: more files, more context and more rules, with
@@ -211,7 +229,7 @@ cd ~/rsc-skills && npm install && npm link
 > `node scripts/rsc.js …`, the `npm link` above, or pin the published build with
 > `npx @ericrisco/rsc@latest …`.
 
-The first run asks **how technical the conversation should be**, the accompaniment level, what the
+The first run asks **one** question about conversation: technical, or with analogies. Then what the
 project is for, its goal and the assistants to target. It then presents the complete plan. A small
 website can defer SDD, agents and code guards; an operations harness does not receive them merely
 because it lives in a repository. Deferred components record the evidence that would make rsc
@@ -235,10 +253,9 @@ $ rsc onboard
  ██████╗ ███████╗ ██████╗     ← animated gradient wordmark
  ██╔══██╗██╔════╝██╔════╝
  ██████╔╝███████╗██║
-  273 skills · one CLI · zero bloat
+  270 skills · one CLI · zero bloat
 
-How technical should the conversation be?
-How much accompaniment do you want?
+How should I talk to you?
 What are you building or running?
 What do you want this project to achieve?
 
@@ -404,6 +421,11 @@ Running through `npx` (no global install)? There's nothing to upgrade —
 `npx @ericrisco/rsc@latest` always fetches the latest published catalog; just run
 `rsc sync` afterwards if the project already has skills installed.
 
+**From 2.0.x to 2.1.0:** `eli5` and `show-me` became part of `orient`, and `bro` became part of
+`unslop`. The update removes the three old skills (only the copies rsc installed) and installs the
+ones that replace them. An `accompaniment_level` line in your profile is ignored: the only setting
+now is `technical_level`.
+
 Every sync snapshots the project first, so a bad update is always reversible:
 
 ```bash
@@ -434,20 +456,21 @@ just asks in plain language.
 
 ## The catalog
 
-273 skills, grouped by what you're trying to do. Click any skill to read its
+270 skills, grouped by what you're trying to do. Click any skill to read its
 `SKILL.md`. It fires on its own when a task matches.
 
 ### 🧭 Core & control plane
 The front door and the workspace brain.
 
-[init](skills/init/) · [harness](skills/harness/) · [orient](skills/orient/) · [suggest](skills/suggest/) · [bro](skills/bro/) · [unslop](skills/unslop/) · [author-skill](skills/author-skill/) · [sdd-init](skills/sdd-init/)
+[init](skills/init/) · [harness](skills/harness/) · [orient](skills/orient/) · [suggest](skills/suggest/) · [unslop](skills/unslop/) · [author-skill](skills/author-skill/) · [sdd-init](skills/sdd-init/)
 
 > **harness** is the Karpathy *chaos→knowledge* engine — a `01-TOOLS/` layer (one
 > folder per provider, each with a working `test_connection`) and a `02-DOCS/`
 > self-improving wiki. It governs software *or* a whole company. **orient** is the
-> always-on compass that keeps a non-technical human oriented after every step.
-> **bro** is installed with every profile and rewrites any answer in plain, natural
-> language when the user asks — without making its full body always-on.
+> always-on voice: short STE-style sentences, every answer understandable on its own,
+> technical or with analogies, and a diagram or an HTML page when you do not follow.
+> **unslop** is installed with every profile and makes text you send to others sound
+> like a person, with no AI tells.
 
 <img src="https://raw.githubusercontent.com/ericrisco/rsc-harness/main/site/company-brain.svg" alt="The rsc company brain as a 3D knowledge graph: loose material drifts in from the inbox on the left and is absorbed into the bright green wiki cluster, whose brightest hubs are its .base views; dim clusters behind are raw sources and the agent's own captured worklog; an amber cluster is gaps.md, what the wiki knows it is missing." width="960">
 
@@ -571,7 +594,7 @@ Three engines + engine-agnostic disciplines. Every engine skill pins the current
 
 ### 🧠 Knowledge & meta
 
-[knowledge-ops](skills/knowledge-ops/) · [codebase-onboarding](skills/codebase-onboarding/) · [research-ops](skills/research-ops/) · [decision-records](skills/decision-records/) · [continuous-learning](skills/continuous-learning/) · [skill-scout](skills/skill-scout/) · [context-budget](skills/context-budget/) · [roast-me](skills/roast-me/) · [show-me](skills/show-me/) · [eli5](skills/eli5/) · [fable-operator](skills/fable-operator/)
+[knowledge-ops](skills/knowledge-ops/) · [codebase-onboarding](skills/codebase-onboarding/) · [research-ops](skills/research-ops/) · [decision-records](skills/decision-records/) · [continuous-learning](skills/continuous-learning/) · [skill-scout](skills/skill-scout/) · [context-budget](skills/context-budget/) · [roast-me](skills/roast-me/) · [fable-operator](skills/fable-operator/)
 
 ---
 

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "version": "2.0.19",
+  "version": "2.1.0",
   "counts": {
-    "skills": 273,
+    "skills": 270,
     "agents": 33,
     "commands": 53,
     "fixedCommands": 20
@@ -461,30 +461,6 @@
       ],
       "profiles": []
     },
-    {
-      "id": "bro",
-      "description": "Use whenever the user asks to make an answer or draft sound human, natural, plain-spoken or less AI-written — including a terse bro after the last response. Rewrites or drafts in the same language while preserving meaning, facts and channel. NOT a reusable brand voice (that is `brand-voice`), NOT translation (that is `translation-l10n`).",
-      "tags": [
-        "bro",
-        "human-writing",
-        "humano",
-        "plain-language",
-        "natural-language",
-        "rewrite",
-        "no-jargon"
-      ],
-      "recommends": [
-        "unslop",
-        "brand-voice",
-        "technical-writing",
-        "translation-l10n"
-      ],
-      "profiles": [
-        "minimal",
-        "core",
-        "full"
-      ]
-    },
     {
       "id": "building-agents",
       "description": "Use when building or restructuring an LLM agent — provider adapter, tool calling, structured output, RAG, agent loop, eval gate, cost routing, tracing, MCP server — model-agnostic across OpenAI/Anthropic/Gemini/OSS so a model swap is a config change. NOT vector-store SQL alone (that is `postgresdb`) or service deployment (that is `deployment`).",
@@ -1599,29 +1575,6 @@
       ],
       "profiles": []
     },
-    {
-      "id": "eli5",
-      "description": "Use when a topic must be explained from zero to someone who knows nothing about it: one page, big pictures, very few words, everyday analogies, no jargon and nothing assumed. NOT the smallest in-conversation visual for someone already following (that is `show-me`), NOT a course with exercises (that is `course-builder`).",
-      "tags": [
-        "eli5",
-        "explain",
-        "beginner",
-        "simple",
-        "analogy",
-        "no-jargon",
-        "explicame"
-      ],
-      "recommends": [
-        "show-me",
-        "technical-writing",
-        "course-builder"
-      ],
-      "profiles": [
-        "minimal",
-        "core",
-        "full"
-      ]
-    },
     {
       "id": "elixir",
       "description": "Use when writing or refactoring Elixir/OTP on the BEAM — GenServers, supervision trees and restart strategies, pattern matching, mix projects and releases — or when processes misbehave (restart loops, mailbox growth, call timeouts). NOT a Phoenix web app, LiveView, Ecto or channels (that is `phoenix`).",
@@ -2475,7 +2428,7 @@
     },
     {
       "id": "init",
-      "description": "Use when starting from nothing or pointing rsc at an existing project — the front door. Gauges technical level and the accompaniment dial first (non-technical by default), discovers what the user wants to build or govern (any stack, or a non-code harness: company/ops, research, knowledge, content), writes the profile to 02-DOCS, and installs the skills discovery justified. NOT the scaffolder (that is `harness`), NOT a stack skill.",
+      "description": "Use when starting from nothing or pointing rsc at an existing project — the front door. First asks one question — technical terms or analogies (analogies by default) — then discovers what the user wants to build or govern (any stack, or a non-code harness: company/ops, research, knowledge, content), writes the profile to 02-DOCS, and installs the skills discovery justified. NOT the scaffolder (that is `harness`), NOT a stack skill.",
       "tags": [
         "init",
         "bootstrap",
@@ -3448,13 +3401,16 @@
     },
     {
       "id": "orient",
-      "description": "Always-on. The brújula: close every turn by situating the person — where they are, what just happened, why it mattered, and the next step as a question, never a dead end. Reads the accompaniment and technical dials from 02-DOCS and calibrates how much it explains, rewriting the dial when the user asks for more or less. NOT the missing-skill installer (that is `suggest`).",
+      "description": "Always-on. How the harness talks to the person: STE-style short sentences, every answer understandable on its own, technical or with analogies by the profile, and a ladder (text → diagram → HTML page → video on request) when the person does not follow. Closes every turn with the brújula. Fires on 'no entiendo', 'explícamelo', 'enséñame', 'dibújamelo', 'explain it from zero', '¿dónde estamos?'. NOT the missing-skill installer (that is `suggest`), NOT a text the user sends to others (that is `unslop`).",
       "tags": [
         "orient",
-        "guide",
+        "voice",
+        "ste",
+        "explain",
+        "diagram",
+        "eli5",
+        "show-me",
         "compass",
-        "dial",
-        "meta",
         "always-on"
       ],
       "recommends": [],
@@ -4316,7 +4272,7 @@
     },
     {
       "id": "sdd",
-      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the accompaniment dial from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill.",
+      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the user's register from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill.",
       "tags": [
         "sdd",
         "spec",
@@ -4542,31 +4498,6 @@
       ],
       "profiles": []
     },
-    {
-      "id": "show-me",
-      "description": "Use when the user needs to see how something works instead of reading about it: picks the smallest visual that carries the point — pseudocode, call tree, file tree, component tree, Mermaid, a shaped diff, or one HTML page. NOT visual identity (that is `design-loop`), NOT slides (that is `presentations`), NOT a from-zero explainer (that is `eli5`).",
-      "tags": [
-        "show-me",
-        "explain",
-        "diagram",
-        "visual",
-        "mermaid",
-        "diff",
-        "call-tree",
-        "ensename"
-      ],
-      "recommends": [
-        "eli5",
-        "presentations",
-        "technical-writing",
-        "codebase-onboarding"
-      ],
-      "profiles": [
-        "minimal",
-        "core",
-        "full"
-      ]
-    },
     {
       "id": "simplify-code",
       "description": "Use when correct working code is unnecessarily hard to read, change or verify and needs behaviour-preserving simplification in a bounded scope. Characterizes the observable contract, removes accidental complexity one concept at a time and proves equivalence. NOT fixing a failure (`debug`), NOT read-only diff judgment (`review`/`code-review`).",
@@ -5264,18 +5195,20 @@
     },
     {
       "id": "unslop",
-      "description": "Use when a written text must be audited against a named catalogue of AI tells before it ships: puffery, `not just X but Y`, the rule of three, em dashes, filler, hedging, abstract metaphor nouns. Names each hit and fixes it. NOT the register rewrite in the user's own voice (that is `bro`), NOT a reusable voice guide (that is `brand-voice`).",
+      "description": "Use when a text that leaves the session (email, post, README, message, landing copy) must sound like a person and carry no AI tells: rewrites it in the user's language fitted to the channel and relationship, and audits it against a named catalogue of tells (puffery, `not just X but Y`, rule of three, em dashes, filler, hedging). Fires on 'bro', 'hazlo más humano', 'que no suene a IA', 'más natural', 'unslop this'. NOT how the harness talks to the user (that is `orient`), NOT a reusable voice guide (that is `brand-voice`).",
       "tags": [
         "unslop",
+        "human-writing",
+        "humano",
+        "natural-language",
+        "plain-language",
         "ai-tells",
         "editing",
-        "audit",
-        "slop",
-        "publish-check",
+        "rewrite",
+        "bro",
         "revisar-texto"
       ],
       "recommends": [
-        "bro",
         "brand-voice",
         "technical-writing"
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.0.19",
+  "version": "2.1.0",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {
@@ -105,6 +105,14 @@
     {
       "fixedIn": "2.0.19",
       "symptom": "rsc doctor reported missing pieces or an unwired hook but still exited with 0, so a CI or an editor extension could not tell"
+    },
+    {
+      "fixedIn": "2.0.20",
+      "symptom": "In a project whose path contains a space, rsc doctor reported every hook script as missing and exited 1, though the scripts were there and the hooks ran"
+    },
+    {
+      "fixedIn": "2.1.0",
+      "symptom": "Answers were long and leaned on hidden reasoning, and onboarding asked an accompaniment level few could answer; now: short stand-alone sentences, one question"
     }
   ]
 }

package/scripts/consult.js

@@ -43,14 +43,14 @@ const SYNONYMS = {
   presentacion: ['presentations'], 'presentación': ['presentations'], diapositivas: ['slides'],
   curso: ['course', 'teaching'], 'enseñar': ['teaching'], ensenar: ['teaching'],
   marketing: ['marketing'], copy: ['copywriting'], texto: ['copywriting'], textos: ['copywriting'],
-  human: ['bro', 'human-writing', 'natural-language', 'plain-language'],
-  humano: ['bro', 'human-writing', 'natural-language', 'plain-language'],
-  humana: ['bro', 'human-writing', 'natural-language', 'plain-language'],
-  huma: ['bro', 'human-writing', 'natural-language', 'plain-language'],
-  natural: ['bro', 'human-writing', 'natural-language', 'plain-language'],
-  robotico: ['bro', 'human-writing'], robotica: ['bro', 'human-writing'],
-  robotic: ['bro', 'human-writing'], roboticamente: ['bro', 'human-writing'],
-  jerga: ['bro', 'plain-language', 'no-jargon'], jargon: ['bro', 'plain-language', 'no-jargon'],
+  human: ['unslop', 'human-writing', 'natural-language', 'plain-language'],
+  humano: ['unslop', 'human-writing', 'natural-language', 'plain-language'],
+  humana: ['unslop', 'human-writing', 'natural-language', 'plain-language'],
+  huma: ['unslop', 'human-writing', 'natural-language', 'plain-language'],
+  natural: ['unslop', 'human-writing', 'natural-language', 'plain-language'],
+  robotico: ['unslop', 'human-writing'], robotica: ['unslop', 'human-writing'],
+  robotic: ['unslop', 'human-writing'], roboticamente: ['unslop', 'human-writing'],
+  jerga: ['unslop', 'plain-language', 'no-jargon'], jargon: ['unslop', 'plain-language', 'no-jargon'],
   // Cross-cutting workflow vocabulary. These map multilingual/colloquial
   // wording to the exact compound tags used by the catalog.
   challenge: ['adversarial-review', 'decision-quality', 'preflight'], challenged: ['adversarial-review'],

package/scripts/doctor.js

@@ -65,6 +65,10 @@ function selloStatus(root) {
 //
 // Hookless targets get an empty list by construction: their always-on surface is a
 // markdown block with no script behind it, so there is nothing that can go missing.
+// A quoted span counts as a path only if it starts like one and holds no shell operator: a whole
+// `sh -c '…'` snippet is not a path, and reading it as one reports a present script missing.
+const SCRIPT_RE =
+  /"((?:[A-Za-z]:)?[\\/~][^"&;|]*[\\/]\.rsc[\\/][^"\s]+?\.mjs)"|'((?:[A-Za-z]:)?[\\/~][^'&;|]*[\\/]\.rsc[\\/][^'\s]+?\.mjs)'|([^"'\s]*[\\/]\.rsc[\\/][^"'\s]+\.mjs)/g;
 export function missingHookScripts({ target, home = homedir(), cwd = process.cwd() } = {}) {
   if (HOOKLESS_TARGETS.has(target)) return [];
   const file = targetPaths(target, home, cwd).hookTarget;
@@ -84,8 +88,10 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
   const expand = (c) => c.split('${CLAUDE_PROJECT_DIR}').join(cwd);
   for (const raw of commands) {
     const cmd = expand(raw);
-    for (const m of cmd.matchAll(/["']?([^"'\s]*[\\/]\.rsc[\\/][^"'\s]+\.mjs)["']?/g)) {
-      const script = m[1];
+    // Quoted forms first: a project path may hold a space, and stopping at whitespace kept only
+    // the tail (`entreno/.rsc/x.mjs`), which then resolved against the cwd and read as missing (#283).
+    for (const m of cmd.matchAll(SCRIPT_RE)) {
+      const script = m[1] ?? m[2] ?? m[3];
       if (!existsSync(script)) seen.add(script);
     }
   }

package/scripts/install-apply.js

@@ -13,6 +13,7 @@ import {
 import { projectOptOuts } from '../targets/opt-outs.js';
 import { readState, writeState } from './lib/state.js';
 import { withDefaultSkillFloor } from './lib/default-skill-floor.js';
+import { isRetired, replaceRetired } from './lib/retired-skills.js';
 import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { createBackup } from './lib/backups.js';
 import {
@@ -196,7 +197,9 @@ export function recordInManifest({ cwd, target, skillIds, agentIds = [], catalog
     // `dropTarget` is the one exception — a MOVE, where leaving the old one declared would
     // have every clone rebuild a harness that was deliberately abandoned.
     targets: union(prev.targets, [target]).filter((t) => t !== dropTarget),
-    skills: union(prev.skills, skillIds),
+    // Through the retirement map: the living list must stop naming a skill the catalog no longer
+    // ships, or every clone would go looking for it.
+    skills: replaceRetired(union(prev.skills, skillIds)).sort(),
     agents: union(prev.agents, agentIds),
     ownSkills: prev.ownSkills || [],
     catalogVersion,
@@ -215,7 +218,23 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   const fromScratch = !existsSync(join(cwd, '.rsc'));
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd, hooks: policy?.alwaysOn !== false });
-  const managedPaths = managedPathsForInstall({ skillIds, agentIds, target, home, cwd, policy });
+  // What this pass prunes, decided BEFORE the backup so the backup holds it: a skill link this
+  // target's state proves is ours and that is no longer wanted (always for a retired skill, and for
+  // any skill when a plan governs), and the shared base of a retired skill once no other assistant
+  // in this project still records it. Taking a base another assistant links to would leave that
+  // assistant dangling until its own sync.
+  const priorState = readState(paths.stateFile);
+  const prunedSkills = Object.keys(priorState.skills || {})
+    .filter((id) => !skillIds.includes(id) && (policy || isRetired(id)));
+  const stillRecordedElsewhere = (id) => TARGET_IDS.some((other) => other !== target
+    && Object.hasOwn(readState(targetPaths(other, home, cwd).stateFile).skills || {}, id));
+  const prunedBases = Object.keys(readBaseVersions(cwd))
+    .filter((id) => isRetired(id) && !skillIds.includes(id) && !stillRecordedElsewhere(id));
+  const managedPaths = [...new Set([
+    ...managedPathsForInstall({ skillIds, agentIds, target, home, cwd, policy }),
+    ...prunedSkills.map((id) => paths.skillDir(id)),
+    ...prunedBases.map((id) => baseDir(id, cwd)),
+  ])];
   if (dryRun) return { dryRun: true, skills: skillIds, agents: agentIds, paths: managedPaths };
   // Rebuild the declared decisions first, so everything below (the agent tier especially) reads
   // the state the team declared rather than the default it would otherwise assume.
@@ -227,12 +246,17 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
   // syncs — a single global marker would be bumped by the first target and make later
   // targets skip refreshing their exclusive skills' bases.
   const baseVersions = readBaseVersions(cwd);
-  if (policy) {
-    for (const id of Object.keys(state.skills || {})) {
-      if (skillIds.includes(id)) continue;
-      rmSync(paths.skillDir(id), { recursive: true, force: true });
-      delete state.skills[id];
-    }
+  // A retired skill is pruned even without a governing plan: nothing can install it any more, so
+  // keeping it would only leave a dead copy behind. Ownership is proven by the state file — a
+  // same-named directory rsc never recorded is somebody's own work and is not touched.
+  for (const id of prunedSkills) {
+    rmSync(paths.skillDir(id), { recursive: true, force: true });
+    delete state.skills[id];
+  }
+  // Its shared base too, proven ours by the base-version ledger rather than by its name.
+  for (const id of prunedBases) {
+    rmSync(baseDir(id, cwd), { recursive: true, force: true });
+    delete baseVersions[id];
   }
   for (const step of plan) {
     if (step.kind === 'skill') {
@@ -528,7 +552,9 @@ export function removeTargetInstall({ target, home, cwd = process.cwd() }) {
   ];
   const declaredLocationsAreExact = Object.entries(state.skills || {}).every(([id, entry]) =>
     /^[a-z0-9][a-z0-9._-]*$/i.test(id)
-    && existsSync(join(ROOT, 'skills', id))
+    // A retired id no longer has a catalog directory, but `paths.skillDir` below still proves where
+    // it lives — refusing it made every re-onboard that drops an old assistant loop on recovery.
+    && (existsSync(join(ROOT, 'skills', id)) || isRetired(id))
     && (entry.files || []).every((file) => resolve(file) === resolve(paths.skillDir(id))))
     && (state.agents || []).every((name) => {
       if (!allAgentNames().includes(name)) return false;
@@ -607,9 +633,12 @@ export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun
   // then rebuilt from a governed list that predated it and pruned the difference, recursively.
   // Reported by a user and reproduced 2026-09-17. The receipt stays untouched, because it is
   // hash-checked against what the user accepted and is not a log of what happened since.
-  const declaredRaw = governedSkills
+  //
+  // Read through the retirement map: a declaration older than the retirement of eli5, show-me and
+  // bro names skills the catalog no longer ships, and the receipt that names them is never rewritten.
+  const declaredRaw = replaceRetired(governedSkills
     ? [...new Set([...governedSkills, ...(manifest?.skills || [])])].sort()
-    : (ids.length ? ids : (manifest?.skills || []));
+    : (ids.length ? ids : (manifest?.skills || []))).sort();
   // A declaration is frozen at the moment it was written, so a skill the catalog later makes
   // mandatory never reaches an existing harness: `add` and `install` apply the floor, sync did
   // not, and sync is the only one an upgrade runs. 2.0.0 shipped the three-lane decisor inside

package/scripts/lib/default-skill-floor.js

@@ -1,15 +1,16 @@
 // Skills every installation path equips, even when the user picks a profile,
 // adds one skill directly, or browses the catalog by hand.
 //
-// `orient` and `suggest` are runtime always-on. `bro` is installed by default
-// but remains conditionally loaded: its description routes human-language asks
-// without paying for its body on unrelated turns.
+// `orient` and `suggest` are runtime always-on. `unslop` is installed by default
+// but remains conditionally loaded: its description routes "rewrite this for
+// other people" asks without paying for its body on unrelated turns. It took the
+// place of `bro`, which was retired into it (see retired-skills.js).
 //
 // `ftd` joined in 2.0.1 by the same criterion as `suggest`: the always-on decisor
 // routes ordinary work to `../ftd/SKILL.md`, so a harness without it has a default
 // lane that points at nothing. Membership of every profile was not enough — a
 // declaration written before the skill existed never gains it (see `syncInstalled`).
-export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'bro', 'ftd']);
+export const DEFAULT_SKILL_FLOOR = Object.freeze(['orient', 'suggest', 'unslop', 'ftd']);
 
 export function withDefaultSkillFloor(skillIds = []) {
   return [...new Set([...DEFAULT_SKILL_FLOOR, ...skillIds])];

package/scripts/lib/divergence.js

@@ -3,6 +3,7 @@ import { readState } from './state.js';
 import { targetPaths } from '../../targets/index.js';
 import { existsSync } from 'node:fs';
 import { DEFAULT_SKILL_FLOOR } from './default-skill-floor.js';
+import { replaceRetired } from './retired-skills.js';
 
 // What the team declared versus what is on this machine.
 //
@@ -28,13 +29,16 @@ export function divergence({ cwd = process.cwd(), target, home } = {}) {
 
   const paths = targetPaths(target, home, cwd);
   const installed = new Set(Object.keys(readState(paths.stateFile).skills || {}));
+  // A declaration written before eli5, show-me and bro were retired names them; it is read as
+  // their successors, so a teammate who has not synced yet is not told to install a ghost.
+  const declared = replaceRetired(manifest.skills || []);
 
   return {
-    missing: (manifest.skills || []).filter((id) => !installed.has(id)),
-    extra: [...installed].filter((id) => !(manifest.skills || []).includes(id)),
+    missing: declared.filter((id) => !installed.has(id)),
+    extra: [...installed].filter((id) => !declared.includes(id)),
     ownMissing: (manifest.ownSkills || []).filter((name) => !existsSync(paths.skillDir(name))),
     // Read off the declaration, not off the disk: a skill installed by hand into a harness
     // that still does not declare it is one sync away from being pruned again.
-    floorMissing: DEFAULT_SKILL_FLOOR.filter((id) => !(manifest.skills || []).includes(id)),
+    floorMissing: DEFAULT_SKILL_FLOOR.filter((id) => !declared.includes(id)),
   };
 }

package/scripts/lib/domains.js

@@ -4,7 +4,7 @@
 // catalog grows deliberately, never silently.
 
 export const DOMAINS = [
-  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'bro', 'unslop', 'author-skill', 'sdd-init'] },
+  { title: 'Core & control plane', ids: ['init', 'harness', 'orient', 'suggest', 'unslop', 'author-skill', 'sdd-init'] },
   { title: 'Spec-Driven Development', ids: ['ftd', 'sdd', 'constitution', 'idea-refinement', 'specify', 'clarify', 'plan', 'tasks', 'analyze', 'decision-challenge', 'implement', 'source-grounded-development', 'verify', 'review', 'simplify-code', 'ship', 'debug', 'worktrees', 'parallel'] },
   { title: 'Run a business', ids: ['finance-ops', 'invoicing', 'bookkeeping', 'pricing', 'sales-pipeline', 'lead-gen', 'cold-outreach', 'proposals', 'contracts', 'customer-support', 'client-onboarding', 'retention', 'hiring', 'people-ops', 'inventory', 'logistics-ops', 'procurement', 'meeting-notes', 'sop-builder', 'project-ops'] },
   { title: 'Raise & model money', ids: ['pitch-deck', 'investor-materials', 'financial-model', 'fundraising', 'unit-economics', 'grants'] },
@@ -26,7 +26,7 @@ export const DOMAINS = [
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
   { title: 'Motion & interface craft', ids: ['motion-craft', 'ui-engineering', 'variant-explorer'] },
   { title: 'Design & content craft', ids: ['design-loop', 'design', 'design-dna', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
-  { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'show-me', 'eli5', 'fable-operator'] },
+  { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },
 ];
 
 export function allDomainIds() {