@ericrisco/rsc 1.1.4 → 1.1.5

package/README.md

@@ -52,6 +52,7 @@ user wants**, reads the repo, then installs the floor (`orient` + `rsc-suggest`
 `init`) plus only the skills that fit — one at a time. No global install and no API key needed.
 
 - **Choose assistants non-interactively:** `npx @ericrisco/rsc@latest --target claude` (comma-separate for several).
+- **Two assistants already installed?** rsc asks instead of guessing. `--target` settles it in one word.
 - **Already installed, just refreshing skills + hooks:** `rsc sync` (or re-run the command above).
 - **Add one skill by id:** `rsc add <id>` · **browse the catalog:** `rsc consult "<what you want>"` or `rsc list`.
 
@@ -203,6 +204,75 @@ rsc uninstall postgresdb --dry-run   # preview a removal
 
 ---
 
+
+## 👥 Sharing a harness with your team
+
+The harness travels by git, but not all of it — and the split is the point.
+
+**Commit these:**
+
+| | |
+| --- | --- |
+| `.rsc.json` | The decision: which assistants, which skills, **which catalog version**, the developer tier, which gates you disarmed |
+| `01-TOOLS/` · `02-DOCS/` | Your tooling and your wiki, if you use them |
+| Skills and agents you wrote by hand | They are yours. rsc does not claim them, does not count them as drift, and does not touch them |
+
+**Do not commit these** — rsc adds them to `.gitignore` for you:
+
+| | Why |
+| --- | --- |
+| `.rsc/` | Machine state: hook scripts, seals, logs |
+| The skill entries rsc manages | Symlinks on macOS/Linux, real copies on Windows — two incompatible shapes of one thing |
+
+Whoever clones runs **one command** and ends up with the same harness:
+
+```bash
+npx @ericrisco/rsc@latest sync
+```
+
+Same skills, same version — `.rsc.json` pins the catalog, so a teammate who clones in three
+months gets what you had, not what shipped since. Upgrading is a deliberate act, never a side
+effect of rebuilding.
+
+When someone changes the harness and you `git pull`, `rsc doctor` tells you what no longer
+matches. **Nothing is ever written to your machine by a pull** — you are told, and you decide.
+
+**Own skills.** A skill your team wrote lives in the repo and already works for whoever clones,
+with no command at all. Declare it in `.rsc.json` under `ownSkills` and `doctor` will also say
+when someone is missing it — that is all declaring does. rsc never installs, updates or
+overwrites it: its version is the commit.
+
+
+## 🩹 Something's off? One command
+
+Recognise any of these? They are all the same fix.
+
+| What you see | |
+| --- | --- |
+| `"target": "codex"` when you work in Claude Code | |
+| `This target has no hook injection` and you did not expect that | |
+| Skills appear that you never asked for | |
+| You cloned a repo and your assistant sees no skills at all | |
+| A hook seems to run several times per turn | |
+| Template lines showed up inside your hand-written `AGENTS.md` | |
+
+```bash
+npx @ericrisco/rsc@latest repair
+```
+
+Safe in any folder: with no rsc there, it says so and writes nothing. It shows what it
+found before touching anything, keeps a recoverable copy, and running it twice changes
+nothing the second time. Add `--dry-run` to see the whole pass without a single write.
+
+**What it fixes on its own** — putting the harness back to what was already declared:
+dangling links from a clone, hooks wired several times, the 0.1 layout no assistant reads.
+
+**What it asks about** — anything that changes a decision: moving the harness to another
+assistant, or touching files you already committed.
+
+**What it never touches:** skills and agents you wrote by hand. rsc did not install them,
+so rsc does not repair, move or delete them — not even when rebuilding from scratch.
+
 ## Update
 
 `rsc` is an npm package, so updating is two steps — bump the package, then

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.4",
+  "version": "1.1.5",
   "counts": {
     "skills": 281
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
+import { divergence } from './lib/divergence.js';
 import { loadManifest } from './lib/manifest.js';
 import { listBackups } from './lib/backups.js';
 import { SDD_GATE_TEXT } from '../targets/hook-once.mjs';
@@ -40,6 +41,40 @@ function selloStatus(root) {
   } catch { return { enabled: false }; }
 }
 
+// A wired hook is a promise to run a file. `settings.json` existing only proves the
+// promise was made — and a fresh clone brings that file (committed) without .rsc/
+// (ignored), so every session start fails while the report says all-clear. Read the
+// commands we wired and check the files they name actually exist.
+//
+// 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.
+export function missingHookScripts({ target, home = homedir(), cwd = process.cwd() } = {}) {
+  if (HOOKLESS_TARGETS.has(target)) return [];
+  const file = targetPaths(target, home, cwd).hookTarget;
+  let settings;
+  try { settings = JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
+  const commands = [];
+  for (const entries of Object.values(settings?.hooks || {})) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) for (const h of entry?.hooks || []) {
+      if (typeof h?.command === 'string') commands.push(h.command);
+    }
+  }
+  const seen = new Set();
+  // Commands name the project through ${CLAUDE_PROJECT_DIR}, which only the client
+  // expands. Resolve it here or every wired script reads as missing and the report
+  // calls a healthy install broken — the mirror image of the bug this check fixes.
+  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];
+      if (!existsSync(script)) seen.add(script);
+    }
+  }
+  return [...seen];
+}
+
 export function doctor({ target, home, cwd }) {
   const root = cwd || process.cwd();
   const paths = targetPaths(target, home, cwd);
@@ -50,7 +85,8 @@ export function doctor({ target, home, cwd }) {
     target,
     installed: Object.keys(state.skills),
     missing: [],
-    hookWired: existsSync(paths.hookTarget),
+    // Wired means it can actually run, not merely that the file declaring it is there.
+    hookWired: existsSync(paths.hookTarget) && missingHookScripts({ target, home, cwd }).length === 0,
     manifestSkills: manifest.counts.skills,
     backups: {
       exists: existsSync(join(root, '.rsc', 'backups')),
@@ -285,6 +321,37 @@ export function contextBudget({ target, home = homedir(), cwd = process.cwd() }
         + 'root, or update both to a version that de-duplicates at runtime.',
     });
   }
+  const orphanScripts = missingHookScripts({ target, home, cwd });
+  if (orphanScripts.length) {
+    // ONE finding, not one per file: a clone is missing all eight at once, and a list of
+    // eight paths buries the single thing the reader has to do (principle 5).
+    findings.push({
+      id: 'hook-scripts-missing',
+      severity: 'high',
+      summary: `${orphanScripts.length} hook script(s) named by the wiring are not on disk, so those hooks `
+        + 'fail every time they fire. This is what a fresh clone looks like: the settings travelled, the '
+        + 'scripts did not.',
+      action: 'Rebuild them with `npx @ericrisco/rsc repair` from this project root.',
+    });
+  }
+  const drift = divergence({ cwd, target, home });
+  if (drift.missing.length || drift.extra.length || drift.ownMissing.length) {
+    // The day-two case: a teammate changed the harness and this checkout has not caught
+    // up. Reported always, even after someone declines to align — the divergence does not
+    // stop being true because they said no.
+    const parts = [];
+    if (drift.missing.length) parts.push(`missing ${drift.missing.join(', ')}`);
+    if (drift.ownMissing.length) parts.push(`${drift.ownMissing.join(', ')} declared by the team but not in this repo`);
+    if (drift.extra.length) parts.push(`${drift.extra.join(', ')} installed but no longer declared`);
+    findings.push({
+      id: 'manifest-divergence',
+      severity: 'medium',
+      summary: `This checkout does not match what .rsc.json declares: ${parts.join('; ')}.`,
+      action: drift.ownMissing.length && !drift.missing.length && !drift.extra.length
+        ? 'Those come from the repo, not from rsc — pull, or ask whoever wrote them.'
+        : 'Align with `npx @ericrisco/rsc sync`. Nothing is written until you run it.',
+    });
+  }
   findings.push(...duplicateEntryFindings(scopes));
   for (const s of scopes) {
     if (s.hookCountsUnknown) {

package/scripts/install-apply.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { rmSync, existsSync, cpSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, readdirSync } from 'node:fs';
+import { join, dirname, basename, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import { targetHasAgents, writeAgents, removeAgents, agentPath, agentNames } from '../targets/agents.js';
 import { readState, writeState } from './lib/state.js';
+import { readManifest, writeManifest } from './lib/manifest-file.js';
 import { createBackup } from './lib/backups.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -67,7 +68,7 @@ function generatedHookFiles({ target, cwd }) {
   ];
 }
 
-function managedPathsForInstall({ skillIds, target, home, cwd }) {
+export function managedPathsForInstall({ skillIds, target, home, cwd }) {
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
   const out = [paths.stateFile, versionFile(cwd), baseVersionsFile(cwd)];
@@ -82,6 +83,43 @@ function managedPathsForInstall({ skillIds, target, home, cwd }) {
   return [...new Set(out)];
 }
 
+// The opt-outs a team disarmed and the developer tier live as marker files under .rsc/,
+// which is machine-local and therefore lost on every clone: a team that disarmed the
+// gitmoji guard found it armed again on the next checkout, with nobody having decided
+// that. They are decisions, so they belong in the committed declaration.
+function localDecisions(cwd) {
+  const dir = join(cwd, '.rsc');
+  let optOuts = [];
+  try {
+    optOuts = readdirSync(dir).filter((f) => f.startsWith('.no-')).map((f) => f.slice(4)).sort();
+  } catch { /* no .rsc yet */ }
+  let tier = null;
+  try { tier = JSON.parse(readFileSync(join(dir, 'developer.json'), 'utf8')).tier ?? null; } catch { /* unset */ }
+  return { optOuts, tier };
+}
+
+// Record the decision, merging so a second assistant never erases the first: installing
+// into codex on a machine that already had claude is adding, not replacing. Union, sorted
+// where order carries no meaning, so the file stays diffable and a merge conflict stays
+// readable.
+export function recordInManifest({ cwd, target, skillIds, catalogVersion = CLI_VERSION, dropTarget }) {
+  const prev = readManifest(cwd) || { targets: [], skills: [], ownSkills: [], optOuts: [] };
+  const { optOuts, tier } = localDecisions(cwd);
+  const union = (a, b) => [...new Set([...(a || []), ...(b || [])])].sort();
+  return writeManifest(cwd, {
+    version: 1,
+    // Union by default: installing into a second assistant is adding, not replacing.
+    // `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),
+    ownSkills: prev.ownSkills || [],
+    catalogVersion,
+    tier: tier ?? prev.tier ?? null,
+    optOuts: optOuts.length ? optOuts : (prev.optOuts || []),
+  });
+}
+
 export async function applyInstall({ skillIds, target, home, cwd = process.cwd(), operation = 'install', dryRun = false }) {
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
@@ -120,7 +158,8 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
-  ignoreLocalState(cwd);
+  recordInManifest({ cwd, target, skillIds });
+  ignoreLocalState(cwd, target);
   return { ...state, backup };
 }
 
@@ -132,23 +171,54 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
 // Additive and idempotent by construction: append one line to an existing
 // .gitignore, never rewrite or reorder it, and never create the file in a directory
 // that is not a git repository.
-export function ignoreLocalState(cwd = process.cwd()) {
+export function ignoreLocalState(cwd = process.cwd(), target) {
   if (!existsSync(join(cwd, '.git'))) return null;
   const gi = join(cwd, '.gitignore');
   let text = '';
   try { text = existsSync(gi) ? readFileSync(gi, 'utf8') : ''; } catch { return null; }
-  const already = text.split('\n').some((l) => {
-    const s = l.trim().replace(/\/$/, '');
-    return s === '.rsc' || s === '/.rsc';
-  });
-  if (already) return null;
+
+  // `.rsc/` is machine state. The per-target skill entries are derived: symlinks here,
+  // real copies on Windows, so committing either shape puts two incompatible forms of the
+  // same thing into one repo.
+  //
+  // But `claude` writes into `.claude/skills/` and `cursor` into `.cursor/rules/`, which
+  // are SHARED with the user — their own skills and rules live there too. Excluding the
+  // whole directory would quietly stop versioning their work, which is the same sin this
+  // release exists to fix: treating what is theirs as if it were ours. So shared
+  // directories are excluded entry by entry, and only the entries rsc manages.
+  const wanted = ['.rsc/'];
+  if (target) {
+    const paths = targetPaths(target, undefined, cwd);
+    const rel = (abs) => relative(cwd, abs).split(sep).join('/');
+    for (const id of Object.keys(readState(paths.stateFile).skills || {})) wanted.push(rel(paths.skillDir(id)));
+    // The per-file ledger is derived AND platform-shaped (symlink here, real copy on
+    // Windows), so committing it puts two incompatible inventories of one thing in one
+    // repo. The declaration that does travel is .rsc.json, in the root.
+    wanted.push(rel(paths.stateFile));
+    // Subagents are catalog content, re-materialised by every install and sync.
+    for (const f of agentNames()) wanted.push(rel(agentPath(target, cwd, f)));
+  }
+  // `.rsc`, `/.rsc` and `.rsc/` are the same rule to git. Normalising both ends is what
+  // keeps this idempotent against a .gitignore a human wrote in their own spelling.
+  const norm = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
+  const present = new Set(text.split('\n').map(norm));
+  const add = wanted.filter((w) => !present.has(norm(w)));
+  if (!add.length) return null;
+
+  // Append only. Never rewrite, never reorder: the rest of that file is theirs.
   const prefix = text === '' ? '' : (text.endsWith('\n') ? '' : '\n');
   try {
-    appendFileSync(gi, `${prefix}\n# rsc local state (hooks, seals, logs) — machine-local, never committed\n.rsc/\n`);
+    appendFileSync(gi, `${prefix}\n# rsc local state (hooks, seals, logs) and managed skill links — machine-local\n${add.join('\n')}\n`);
     return gi;
   } catch { return null; }
 }
 
+export function collisions({ cwd = process.cwd(), target, home, skillIds = [] }) {
+  const paths = targetPaths(target, home, cwd);
+  const managed = new Set(Object.keys(readState(paths.stateFile).skills || {}));
+  return skillIds.filter((id) => !managed.has(id) && existsSync(paths.skillDir(id)));
+}
+
 export function listInstalled({ target, home, cwd = process.cwd() }) {
   const paths = targetPaths(target, home, cwd);
   return Object.keys(readState(paths.stateFile).skills);
@@ -185,17 +255,22 @@ export async function uninstall({ skillIds, target, home, cwd = process.cwd(), d
 export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun = false }) {
   const paths = targetPaths(target, home, cwd);
   const state = readState(paths.stateFile);
+  // The per-target state is machine wiring and does not travel, so a fresh clone has
+  // none of it: sync found zero skills and did nothing, leaving someone with a repo that
+  // declares a harness and has none. The committed manifest is exactly the declaration
+  // to rebuild from, and it is sitting right there.
   const ids = Object.keys(state.skills || {});
-  if (!ids.length) return dryRun ? { dryRun: true, synced: [], paths: [] } : { synced: [], backup: null };
+  const declared = ids.length ? ids : (readManifest(cwd)?.skills || []);
+  if (!declared.length) return dryRun ? { dryRun: true, synced: [], paths: [] } : { synced: [], backup: null };
   if (dryRun) {
     return {
       dryRun: true,
-      synced: ids,
-      paths: managedPathsForInstall({ skillIds: ids, target, home, cwd }),
+      synced: declared,
+      paths: managedPathsForInstall({ skillIds: declared, target, home, cwd }),
     };
   }
-  const nextState = await applyInstall({ skillIds: ids, target, home, cwd, operation: 'sync' });
-  return { synced: ids, backup: nextState.backup };
+  const nextState = await applyInstall({ skillIds: declared, target, home, cwd, operation: 'sync' });
+  return { synced: declared, backup: nextState.backup };
 }
 
 // Remove EVERYTHING rsc put in this project: installed skills across all targets,

package/scripts/lib/divergence.js

@@ -0,0 +1,33 @@
+import { readManifest } from './manifest-file.js';
+import { readState } from './state.js';
+import { targetPaths } from '../../targets/index.js';
+import { existsSync } from 'node:fs';
+
+// What the team declared versus what is on this machine.
+//
+// The everyday case is not cloning — it is a teammate changing the harness and everyone
+// else running `git pull`. The clone is day one; divergence is every other day. Nothing
+// used to notice, so two people drifted apart in silence.
+//
+// Three buckets, because the three need different answers, and collapsing them is how a
+// report starts nagging someone about their own work:
+//   missing    — declared catalog skill, not installed here. Aligning installs it.
+//   ownMissing — declared team skill, absent from the repo. Aligning says so and writes
+//                nothing: it comes from the repo, not from us.
+//   extra      — installed BY RSC, no longer declared.
+// A hand-written skill that nobody declared is in none of them. Not declaring is a valid
+// way to keep things of your own, not an oversight to correct.
+export function divergence({ cwd = process.cwd(), target, home } = {}) {
+  const empty = { missing: [], extra: [], ownMissing: [] };
+  const manifest = readManifest(cwd);
+  if (!manifest) return empty;
+
+  const paths = targetPaths(target, home, cwd);
+  const installed = new Set(Object.keys(readState(paths.stateFile).skills || {}));
+
+  return {
+    missing: (manifest.skills || []).filter((id) => !installed.has(id)),
+    extra: [...installed].filter((id) => !(manifest.skills || []).includes(id)),
+    ownMissing: (manifest.ownSkills || []).filter((name) => !existsSync(paths.skillDir(name))),
+  };
+}

package/scripts/lib/manifest-file.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// `.rsc.json` — the team's decision about this project's harness, committed.
+//
+// It exists because nothing else could travel. The per-target state lives inside the
+// assistant's own directory, which is machine wiring; `syncInstalled()` reads it, so a
+// clone finds zero skills and does nothing. The declaration had to move to the root.
+//
+// It is a DECLARATION, never an inventory: ids and names only, no paths and no file
+// lists. Two reasons. Paths differ by platform (some machines symlink, others copy), so
+// committing them reproduces in the manifest the very conflict this removes from the
+// skill directories. And a committed file gets merge conflicts by nature — one entry per
+// line, stable key order, so resolving one means reading it, not understanding a format.
+export const MANIFEST = '.rsc.json';
+export const manifestPath = (cwd = process.cwd()) => join(cwd, MANIFEST);
+
+const KEYS = ['version', 'targets', 'skills', 'ownSkills', 'catalogVersion', 'tier', 'optOuts'];
+
+export function readManifest(cwd = process.cwd()) {
+  const file = manifestPath(cwd);
+  if (!existsSync(file)) return null;
+  let raw;
+  // An unreadable manifest is NOT the same as an absent one. Absent means "not adopted
+  // yet" and is normal; corrupt means the file that governs this project cannot be
+  // trusted, and silently treating it as absent would then overwrite it on the next
+  // install. Say it and stop.
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch {
+    throw new Error(`${MANIFEST} exists but is not readable JSON — fix or delete it; rsc will not overwrite it`);
+  }
+  return {
+    version: raw.version ?? 1,
+    targets: raw.targets || [],
+    skills: raw.skills || [],
+    ownSkills: raw.ownSkills || [],
+    catalogVersion: raw.catalogVersion ?? null,
+    tier: raw.tier ?? null,
+    optOuts: raw.optOuts || [],
+  };
+}
+
+// Stable output: fixed key order, arrays one entry per line, order as given. Rewriting an
+// unchanged manifest must produce identical bytes, or every install shows up as a diff.
+export function writeManifest(cwd, manifest) {
+  const out = {};
+  for (const k of KEYS) if (manifest[k] !== undefined) out[k] = manifest[k];
+  out.version ??= 1;
+  const ordered = {};
+  for (const k of KEYS) if (out[k] !== undefined) ordered[k] = out[k];
+  const file = manifestPath(cwd);
+  writeFileSync(file, JSON.stringify(ordered, null, 2) + '\n');
+  return file;
+}

package/scripts/lib/repair.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { targetPaths, installedTargets, detectTarget, unwireHook } from '../../targets/index.js';
+import { readState } from './state.js';
+import { readManifest } from './manifest-file.js';
+import { createBackup } from './backups.js';
+import { countHookEntries } from '../doctor.js';
+import { applyInstall, recordInManifest, managedPathsForInstall } from '../install-apply.js';
+
+// Fixing a harness that came from an earlier version.
+//
+// The other two deliveries fix the future and fix nobody: everyone who built a harness on
+// 0.1 or 1.0 wakes up the day after with exactly what they had, and does not know it. This
+// is the one command for them — no flags, no need to know what is wrong.
+//
+// EVERY finding is born with its class, and the executor only reads that field. It never
+// decides:
+//
+//   restore — put the harness back to what was ALREADY declared. Nobody decides anything,
+//             so it happens on its own, after a recoverable copy.
+//   change  — alter something a person or a team chose. Always asked, one by one.
+//
+// Putting the boundary in the data instead of the executor means it can be tested without
+// running anything, and it cannot drift apart between branches.
+
+const finding = (id, cls, summary, action) => ({ id, class: cls, summary, action });
+
+export function diagnose({ cwd = process.cwd(), target, home = homedir(), invoked = false } = {}) {
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const installed = Object.keys(state.skills || {});
+  const manifest = readManifest(cwd);
+  const out = [];
+
+  // Nothing of ours here at all: say so and touch nothing. Running this in the wrong
+  // folder must be harmless.
+  if (!installed.length && !manifest && !existsSync(join(cwd, '.rsc'))) return out;
+
+  // The 0.1 layout Claude Code never discovered. writeSkill() sweeps it, but only when
+  // that skill is reinstalled — so anyone who never reinstalled still carries it.
+  if (existsSync(join(paths.root, 'rsc'))) {
+    out.push(finding('nested-layout', 'restore',
+      'A .claude/skills/rsc/ directory from the 0.1 layout is still here; no assistant ever read it.',
+      'It gets removed. Nothing that works today lives in it.'));
+  }
+
+  // Repeated wiring. On Windows the needle never matched, so every install ADDED a hook
+  // instead of replacing it: there were real machines running each hook four times.
+  const repeated = duplicatedHooks(paths.hookTarget);
+  if (repeated.length) {
+    out.push(finding('duplicate-hooks', 'restore',
+      `${repeated.join(', ')} wired more than once, so those hooks run several times per event.`,
+      'The extra copies are removed, leaving one of each.'));
+  }
+
+  // A clone: the declaration travelled, the materialised skills did not.
+  const dangling = installed.filter((id) => !existsSync(paths.skillDir(id)))
+    .concat((manifest?.skills || []).filter((id) => !existsSync(paths.skillDir(id))));
+  if (dangling.length) {
+    out.push(finding('dangling-links', 'restore',
+      `${[...new Set(dangling)].join(', ')} are declared but not on disk — what a fresh clone looks like.`,
+      'They get rebuilt from the catalog at the version the manifest pins.'));
+  }
+
+  // Writing the manifest records something already true, which sounds like a restoration.
+  // But it makes a new committable file appear in someone's root, and that surprises —
+  // and surprising people is what started all of this. So: automatic when they typed the
+  // command (they already said yes), asked when we are the ones who noticed.
+  if (!manifest && installed.length) {
+    out.push(finding('no-manifest', invoked ? 'restore' : 'change',
+      'This harness predates .rsc.json, so it cannot be shared by git yet.',
+      'A manifest is written from what is already installed here.'));
+  }
+
+  // Installed somewhere the project does not look like. This is #249: `harness` writes an
+  // AGENTS.md, detection read it as codex, and people ended up wired to an assistant they
+  // never chose. Moving is a change — it is where the harness lives.
+  const others = installedTargets(cwd).filter((t) => t !== target);
+  const looksLike = detectTarget(cwd);
+  if (!others.length && installed.length && looksLike !== target && !manifest) {
+    out.push(finding('wrong-target', 'change',
+      `The harness is installed for ${target}, but this project looks like ${looksLike}.`,
+      `It moves to ${looksLike}, and the old wiring — including the block in the root file — is removed.`),
+    );
+    out[out.length - 1].to = looksLike;
+  }
+  return out;
+}
+
+// Remove the old wiring's skills. The list comes from the target's OWN state, which by
+// construction holds only what rsc installed — so "we never touch what we did not write"
+// is a property of the input here, not a check that could be forgotten or drift.
+//
+// It was a check, once, sitting on a list that mixed state and manifest ids. A mutant that
+// deleted the check killed no test, and chasing that revealed the branch was unreachable
+// anyway. A guard that cannot be seen to fail is worse than no guard (principle 2), so it
+// became structure instead.
+function removeManagedSkills(paths) {
+  for (const id of Object.keys(readState(paths.stateFile).skills || {})) {
+    rmSync(paths.skillDir(id), { recursive: true, force: true });
+  }
+  rmSync(paths.stateFile, { force: true });
+}
+
+function duplicatedHooks(hookTarget) {
+  let settings;
+  try { settings = JSON.parse(readFileSync(hookTarget, 'utf8')); } catch { return []; }
+  const { perEvent } = countHookEntries(settings);
+  const dup = [];
+  for (const [event, ids] of Object.entries(perEvent)) {
+    for (const [id, n] of Object.entries(ids)) if (n > 1) dup.push(`${event}/${id}`);
+  }
+  return dup;
+}
+
+export async function repair({ cwd = process.cwd(), target, home = homedir(), dryRun = false, invoked = false, accept } = {}) {
+  const found = diagnose({ cwd, target, home, invoked });
+  const restores = found.filter((f) => f.class === 'restore');
+  const changes = found.filter((f) => f.class === 'change');
+
+  // Anything the person has to decide is only applied if they actually said yes. With
+  // nobody to ask, it stays pending — and the restorations still get done, because they
+  // never depended on that decision.
+  const okChanges = [];
+  for (const c of changes) if (accept && await accept(c)) okChanges.push(c);
+  const todo = [...restores, ...okChanges];
+  if (!todo.length || dryRun) {
+    return { applied: todo, pending: changes.filter((c) => !okChanges.includes(c)), backup: null };
+  }
+
+  const paths = targetPaths(target, home, cwd);
+  const ids = [...new Set([...Object.keys(readState(paths.stateFile).skills || {}), ...(readManifest(cwd)?.skills || [])])];
+  const backup = createBackup({
+    cwd, operation: 'repair', target,
+    paths: managedPathsForInstall({ skillIds: ids, target, home, cwd }),
+  });
+
+  for (const f of todo) {
+    if (f.id === 'nested-layout') rmSync(join(paths.root, 'rsc'), { recursive: true, force: true });
+    if (f.id === 'duplicate-hooks') { unwireHook(target, paths); await applyInstall({ skillIds: ids, target, home, cwd, operation: 'repair' }); }
+    if (f.id === 'dangling-links') await applyInstall({ skillIds: ids, target, home, cwd, operation: 'repair' });
+    if (f.id === 'no-manifest') recordInManifest({ cwd, target, skillIds: ids });
+    if (f.id === 'wrong-target') {
+      // Install where the project actually points, THEN take the old wiring down — in that
+      // order, so a failure halfway leaves a working harness rather than none. Taking the
+      // block out of the old file gives it back byte-identical: in #249 that file was the
+      // project's hand-written constitution, and it had already been written into once.
+      await applyInstall({ skillIds: ids, target: f.to, home, cwd, operation: 'repair' });
+      unwireHook(target, paths);
+      removeManagedSkills(paths);
+      recordInManifest({ cwd, target: f.to, skillIds: ids, dropTarget: target });
+    }
+  }
+  return { applied: todo, pending: changes.filter((c) => !okChanges.includes(c)), backup };
+}

package/scripts/lib/ui.js

@@ -29,6 +29,11 @@ function interactive() {
   return Boolean(stdin.isTTY && stdout.isTTY);
 }
 
+// The one criterion for "is a human here to answer". Exported so target resolution
+// asks the same question the TUI already asks — two criteria for one question is how
+// a terminal run and a CI run drift apart.
+export const isInteractive = interactive;
+
 const C = {
   dim: (s) => `\x1b[2m${s}\x1b[22m`,
   bold: (s) => `\x1b[1m${s}\x1b[22m`,

package/scripts/rsc.js

@@ -1,22 +1,32 @@
 #!/usr/bin/env node
 import { loadManifest, skillsForProfile } from './lib/manifest.js';
-import { detectTarget, TARGETS } from '../targets/index.js';
+import { detectTarget, resolveTargets, TARGETS } from '../targets/index.js';
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, uninstall, syncInstalled, purge } from './install-apply.js';
+import { applyInstall, listInstalled, uninstall, syncInstalled, purge, collisions } from './install-apply.js';
 import { doctor } from './doctor.js';
-import { say, select, pickFrom, banner, confirm } from './lib/ui.js';
+import { say, select, pickFrom, banner, confirm, isInteractive } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
 import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
 import { listBackups, restoreBackup } from './lib/backups.js';
 import { runUpgrade } from './lib/upgrade.js';
+import { diagnose, repair } from './lib/repair.js';
 import { DEFAULT_SKILL_FLOOR, withDefaultSkillFloor } from './lib/default-skill-floor.js';
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 
+const targetLabel = (id) => TARGETS.find((t) => t.id === id)?.label || id;
+
+// Commands that act ON one assistant. Only these stop when two are installed and no
+// flag says which: `purge` sweeps every target by design, and the catalog/consult
+// side barely touches one, so blocking them would be a regression, not a safeguard.
+const NEEDS_TARGET = new Set([
+  'add', 'install', 'list', 'doctor', 'sync', 'uninstall', 'capabilities', 'catalog', 'registry',
+]);
+
 function flag(name) {
   const i = argv.indexOf(`--${name}`);
   return i >= 0 ? (argv[i + 1] || true) : undefined;
@@ -157,7 +167,7 @@ function printContextBudget(b) {
   say('════════════════════════════════════════════════\n');
 }
 
-async function wizard() {
+async function wizard(flagTargets) {
   const m = loadManifest();
   await banner(m.counts.skills);
   say('  the skill catalog for your assistant (Claude Code · Codex · Cursor · Gemini · Antigravity)\n');
@@ -190,7 +200,7 @@ async function wizard() {
       continue;
     }
 
-    const targets = await selectAgents();
+    const targets = flagTargets || await selectAgents();
     if (targets === null) continue;           // esc in the assistant picker → back to menu
     say(`\nI'll install ${ids.length} skills for: ${targets.join(', ')}`);
     say('   ' + ids.join(', '));
@@ -209,16 +219,54 @@ async function wizard() {
   }
 }
 
+// Installing replaces whatever sits where a skill goes. If that is something the user
+// wrote by hand, it is the one thing an install can destroy — so it is named first and
+// they decide. Silence here is what made someone lose three months of work with a backup
+// they never knew to restore.
+async function guardCollisions(targets, ids) {
+  const hit = [...new Set(targets.flatMap((t) => collisions({ target: t, skillIds: ids })))];
+  if (!hit.length) return true;
+  say(`\n⚠️  These are already here and rsc did not put them — they look like your own work:`);
+  for (const id of hit) say(`     ${id}`);
+  say('   Installing would replace them. A backup is kept, but you would have to know to restore it.');
+  if (!isInteractive()) {
+    console.error('rsc: refusing to overwrite hand-written skills. Rename them, or re-run with --force.');
+    process.exitCode = 1;
+    return false;
+  }
+  return confirm('Replace them anyway?');
+}
+
 async function main() {
-  // --target accepts one id or a comma list (e.g. --target claude,codex). No flag → detect.
+  // One resolution for every command, doctor included: `doctor` used to resolve on its
+  // own and could report a different assistant than the one just installed into.
+  // --target accepts one id or a comma list (e.g. --target claude,codex).
   const f = flag('target');
-  const targets = typeof f === 'string'
-    ? f.split(',').map((s) => s.trim()).filter(Boolean)
-    : [detectTarget()];
+  const resolved = resolveTargets({ flagValue: typeof f === 'string' ? f : undefined });
+  let targets = resolved.ids;
+  if (resolved.ambiguous && NEEDS_TARGET.has(cmd)) {
+    // Two installations, no flag: the whole point of this release is that we do NOT pick.
+    if (isInteractive()) {
+      const picked = await pickFrom(
+        'Two assistants are installed here. Which one do you mean?',
+        resolved.ambiguous.map((id) => ({ id, label: `${targetLabel(id)}  (${listInstalled({ target: id }).length} skills)` })),
+      );
+      if (!picked || !picked.length) return void say('Cancelled — nothing was touched.');
+      targets = picked;
+    } else {
+      console.error(
+        `rsc: ${resolved.ambiguous.join(' and ')} are both installed here, so I will not guess.\n` +
+        `     Say which one:  npx @ericrisco/rsc ${cmd} --target ${resolved.ambiguous[0]}`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+  if (!targets.length) targets = [detectTarget()];
   const target = targets[0];
   switch (cmd) {
     case undefined:
-      return wizard();
+      return wizard(f ? targets : null);
     case 'add': {
       // Positional args = skill ids; skip flags and any flag value (the token after a --flag).
       const requested = [];
@@ -227,6 +275,7 @@ async function main() {
         requested.push(argv[i]);
       }
       const ids = withDefaultSkillFloor(requested);
+      if (!argv.includes('--force') && !(await guardCollisions(targets, ids))) return;
       for (const t of targets) await applyInstall({ skillIds: ids, target: t });
       say(`✅ Installed for ${targets.join(', ')}: ${requested.join(', ')}`);
       return void say('   ↻ Reload/restart your assistant so the new skill activates.');
@@ -236,6 +285,7 @@ async function main() {
       const without = argv.filter((a, i) => argv[i - 1] === '--without');
       let ids = skillsForProfile(loadManifest(), profile);
       ids = withDefaultSkillFloor(ids).filter((id) => !without.includes(id));
+      if (!argv.includes('--force') && !(await guardCollisions(targets, ids))) return;
       for (const t of targets) await applyInstall({ skillIds: ids, target: t });
       say(`✅ Profile '${profile}' installed for ${targets.join(', ')} (${ids.length} skills)`);
       printAgentHandoff();
@@ -577,11 +627,34 @@ async function main() {
       const removed = await uninstall({ skillIds: ids, target, dryRun: dry });
       return void say((dry ? 'Would remove:\n' : 'Removed:\n') + (removed.join('\n') || '(nothing)'));
     }
+    case 'repair': {
+      // One command, no flags, for someone who does not know what is wrong. Restorations
+      // happen on their own; anything that changes a decision is asked, one by one.
+      const dry = argv.includes('--dry-run');
+      const yes = argv.includes('--yes');
+      const found = diagnose({ target, invoked: true });
+      if (!found.length) return void say('Nothing to repair — this harness is healthy.');
+      say(`\nFound ${found.length} thing(s):\n`);
+      for (const f of found) say(`  [${f.class === 'restore' ? 'fix' : 'ask'}] ${f.summary}\n      → ${f.action}`);
+      const accept = async (f) => {
+        if (yes) return true;
+        if (!isInteractive()) return false;
+        return confirm(`\nApply: ${f.summary}`);
+      };
+      const r = await repair({ target, dryRun: dry, invoked: true, accept });
+      say('');
+      if (dry) return void say(`Dry run — nothing written. Would apply ${r.applied.length}.`);
+      say(`Repaired ${r.applied.length} thing(s).${r.backup ? ' A copy of the previous state was kept.' : ''}`);
+      for (const p of r.pending) say(`  still pending (your call): ${p.summary}\n      → ${p.action}`);
+      return void say('   ↻ Reload/restart your assistant.');
+    }
     case 'purge':
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
+      say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
+      say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
       process.exitCode = 1;
   }
 }

package/skills/suggest/SKILL.md

@@ -79,7 +79,31 @@ Not covered → one line, skill or agent. Rules: `skill-scout`.
 
 ---
 
-## 3. First contact
+## 3. A harness that is broken fixes itself
+
+You are injected into every session, so you are the only thing that can notice a broken
+harness before its owner does — and its owner usually cannot, because the symptoms name
+nothing they recognise. When any of these is true, act on it **once** in the session:
+
+- the assistant sees no skills in a project that clearly has a harness;
+- `.rsc.json` exists and what it declares is not what is installed;
+- the same hook seems to run several times;
+- the harness is wired for an assistant that is not the one running.
+
+Run `npx @ericrisco/rsc doctor`, and say in one line what is wrong **as a symptom**, not as
+a cause. Then:
+
+- Anything that only puts the harness back to what was already declared — dangling links, a
+  repeated hook, a layout no version uses — say you are fixing it and run
+  `npx @ericrisco/rsc repair`. Restoring is not deciding, and a recoverable copy is kept.
+- Anything that would change a decision — moving to another assistant, adopting a skill a
+  teammate added, disarming a gate — **ask first**. A `git pull` never rewrites someone's
+  machine.
+
+Offer once. A "no" holds for the session; a new session may look again, because the problem
+has not gone away. Never mention it when the harness is healthy.
+
+## 4. First contact
 
 Before handling the first request of a session, check the workspace:
 

package/targets/_md-block.js

@@ -9,6 +9,9 @@ import { linkOrCopy } from './index.js';
 // multiple assistants sharing one file never duplicate it.
 const MARK_START = '<!-- rsc-suggest:start -->';
 const MARK_END = '<!-- rsc-suggest:end -->';
+// The exact separator wireHook writes before an appended block, so unwireHook can take
+// back precisely what it gave and leave the rest of the file untouched.
+const SEAM = '\n\n';
 
 export function writeSkill(id, fromDir, toPath) {
   return linkOrCopy(fromDir, toPath);
@@ -21,7 +24,9 @@ export function wireHook(paths, sourceMd) {
   if (doc.includes(MARK_START)) {
     doc = doc.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);
   } else {
-    doc += `\n\n${block}\n`;
+    // Append with a fixed seam, and record nothing else. unwireHook removes exactly this
+    // seam and this block, which is what lets the file come back byte-identical.
+    doc += `${SEAM}${block}\n`;
   }
   mkdirSync(dirname(paths.hookTarget), { recursive: true });
   writeFileSync(paths.hookTarget, doc);
@@ -34,9 +39,17 @@ export function unwireHook(paths) {
   if (!existsSync(paths.hookTarget)) return [];
   const doc = readFileSync(paths.hookTarget, 'utf8');
   if (!doc.includes(MARK_START)) return [];
-  const cleaned = doc
-    .replace(new RegExp(`\\n*${MARK_START}[\\s\\S]*?${MARK_END}\\n*`), '\n')
-    .replace(/\n{3,}/g, '\n\n');
+  // Remove the block and the seam that introduced it — nothing more.
+  //
+  // This used to end with a document-wide `\n{3,}` -> `\n\n` pass, which tidied blank
+  // lines the author had put hundreds of lines away from anything of ours. In #249 that
+  // file was the project's hand-written constitution: it had already received 95 lines it
+  // never asked for, and giving it back reformatted is the second half of the same damage.
+  // A slightly larger gap is cosmetic; rewriting someone's document is not.
+  const cleaned = doc.replace(
+    new RegExp(`${SEAM.replace(/\n/g, '\\n')}?${MARK_START}[\\s\\S]*?${MARK_END}\\n?`),
+    '',
+  );
   writeFileSync(paths.hookTarget, cleaned);
   return [paths.hookTarget];
 }

package/targets/claude.js

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { linkOrCopy } from './index.js';
 
@@ -70,6 +70,15 @@ export function unwireHook(paths) {
 // entry (the old `cat …/suggest/SKILL.md` form, or a previous `.sh`/`.mjs` script
 // form) is dropped before we add the current one — idempotent, migrating legacy and
 // bash-era hooks in place. Other (non-rsc) SessionStart hooks are preserved.
+// Commands name the project through ${CLAUDE_PROJECT_DIR}, never through the absolute
+// path of the folder it happened to be installed in. Baking that path in is what made a
+// harness unshareable: a committed settings.json was broken in every other checkout, and
+// even renaming your own folder broke it. The variable is resolved by the client at run
+// time, so the same bytes work on every machine — which is the precondition for the
+// manifest being worth committing at all.
+const P = '${CLAUDE_PROJECT_DIR}';
+const at = (...seg) => `${P}/${seg.join('/')}`;
+
 export function wireHook(paths) {
   const scriptDest = join(paths.projectRoot, '.rsc', 'session-start.mjs');
   mkdirSync(dirname(scriptDest), { recursive: true });
@@ -79,7 +88,8 @@ export function wireHook(paths) {
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
   const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;
-  const cmd = `node "${scriptDest}" "${suggestMd}" "${paths.projectRoot}"`;
+  const suggestRel = at(relative(paths.projectRoot, paths.skillDir('suggest')).split(sep).join('/'), 'SKILL.md');
+  const cmd = `node "${at('.rsc', 'session-start.mjs')}" "${suggestRel}" "${P}"`;
 
   const file = paths.hookTarget;
   const settings = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
@@ -99,7 +109,7 @@ export function wireHook(paths) {
   // any prior rsc worklog-checkpoint entry (.sh or .mjs) dropped first.
   const wlDest = join(paths.projectRoot, '.rsc', 'worklog-checkpoint.mjs');
   copyFileSync(join(HERE, 'worklog-checkpoint.mjs'), wlDest);
-  const wlCmd = `node "${wlDest}" "${paths.projectRoot}"`;
+  const wlCmd = `node "${at('.rsc', 'worklog-checkpoint.mjs')}" "${P}"`;
   for (const event of ['PreCompact', 'SessionEnd']) {
     settings.hooks[event] ||= [];
     settings.hooks[event] = settings.hooks[event].filter(
@@ -118,7 +128,7 @@ export function wireHook(paths) {
   // sello.mjs is ship-guard's sibling import (hooks are materialized file-by-file,
   // so the deterministic sello core must land next to the guard that loads it).
   copyFileSync(join(HERE, 'sello.mjs'), join(paths.projectRoot, '.rsc', 'sello.mjs'));
-  const sgCmd = `node "${sgDest}" "${paths.projectRoot}"`;
+  const sgCmd = `node "${at('.rsc', 'ship-guard.mjs')}" "${P}"`;
   settings.hooks.PreToolUse ||= [];
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/ship-guard.'),
@@ -132,7 +142,7 @@ export function wireHook(paths) {
   // node-run (Windows-safe), idempotent, fail-open, opt-out via .rsc/.no-danger-guard.
   const dgDest = join(paths.projectRoot, '.rsc', 'danger-guard.mjs');
   copyFileSync(join(HERE, 'danger-guard.mjs'), dgDest);
-  const dgCmd = `node "${dgDest}" "${paths.projectRoot}"`;
+  const dgCmd = `node "${at('.rsc', 'danger-guard.mjs')}" "${P}"`;
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/danger-guard.'),
   );
@@ -147,7 +157,7 @@ export function wireHook(paths) {
   // .rsc/.no-gitmoji.
   const gmDest = join(paths.projectRoot, '.rsc', 'gitmoji-guard.mjs');
   copyFileSync(join(HERE, 'gitmoji-guard.mjs'), gmDest);
-  const gmCmd = `node "${gmDest}" "${paths.projectRoot}"`;
+  const gmCmd = `node "${at('.rsc', 'gitmoji-guard.mjs')}" "${P}"`;
   settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(
     (e) => !hookWiringOf(e).includes('.rsc/gitmoji-guard.'),
   );
@@ -163,7 +173,7 @@ export function wireHook(paths) {
   // (non-rsc) UserPromptSubmit hooks are preserved.
   const fgDest = join(paths.projectRoot, '.rsc', 'userprompt-gate.mjs');
   copyFileSync(join(HERE, 'userprompt-gate.mjs'), fgDest);
-  const fgCmd = `node "${fgDest}" "${paths.projectRoot}"`;
+  const fgCmd = `node "${at('.rsc', 'userprompt-gate.mjs')}" "${P}"`;
   settings.hooks.UserPromptSubmit ||= [];
   settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
     (e) => !hookWiringOf(e).includes('.rsc/userprompt-gate.'),

package/targets/index.js

@@ -1,9 +1,10 @@
-import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync, readFileSync } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { homedir } from 'node:os';
 import * as claudeAdapter from './claude.js';
 import * as cursorAdapter from './cursor.js';
 import * as mdAdapter from './_md-block.js';
+import { readManifest } from '../scripts/lib/manifest-file.js';
 
 // Project-local single source of truth. Real skill files live here exactly once;
 // every assistant gets a lightweight pointer (symlink) back to it — no duplication.
@@ -83,28 +84,74 @@ export const TARGETS = [
   { id: 'aider', label: 'Aider', hint: 'CONVENTIONS.md' },
 ];
 
-// Best-effort default for the wizard's pre-mark. Unique config dirs win; the
-// shared AGENTS.md / GEMINI.md fall through to codex / gemini.
+// Which assistants are actually installed here, read from the state file each one
+// writes. This is evidence: only an install of ours writes it. Everything below
+// (detectTarget) is inference from files a human — or our own `harness` skill —
+// may have written for unrelated reasons. Order follows SPEC so the ambiguity
+// message is deterministic. A missing, empty or unreadable state means "not
+// installed", never an error: a half-written file must not break resolution.
+export function installedTargets(cwd = process.cwd()) {
+  return TARGET_IDS.filter((id) => {
+    try {
+      const state = JSON.parse(readFileSync(targetPaths(id, undefined, cwd).stateFile, 'utf8'));
+      return Object.keys(state.skills || {}).length > 0;
+    } catch { return false; }
+  });
+}
+
+// Inference, used only when there is no evidence. Unique config dirs win.
+//
+// Two rules here are scar tissue from issue #249. Claude Code had NO signal at
+// all — it was merely the final fallthrough — so any repo with a root AGENTS.md
+// resolved to codex even with .claude/ full of skills. And AGENTS.md is the
+// weakest signal on purpose: our own `harness` skill writes one into every repo
+// it equips, so treating it as a strong hint made the harness poison its own
+// detection the moment it ran once.
 export function detectTarget(cwd = process.cwd()) {
-  const dir = (d) => existsSync(join(cwd, d));
-  if (dir('.cursor')) return 'cursor';
-  if (dir('.windsurf')) return 'windsurf';
-  if (dir('.clinerules')) return 'cline';
-  if (dir('.roo')) return 'roo';
-  if (dir('.continue')) return 'continue';
-  if (dir('.junie')) return 'junie';
-  if (dir('.kiro')) return 'kiro';
-  if (dir('.zed')) return 'zed';
-  if (dir('.opencode')) return 'opencode';
-  if (dir('.amp')) return 'amp';
-  if (dir('.jules')) return 'jules';
-  if (dir('.antigravity')) return 'antigravity';
-  if (existsSync(join(cwd, '.github', 'copilot-instructions.md'))) return 'copilot';
-  if (dir('.codex') || dir('AGENTS.md')) return 'codex';
-  if (dir('.gemini') || dir('GEMINI.md')) return 'gemini';
+  const has = (p) => existsSync(join(cwd, p));
+  if (has('.cursor')) return 'cursor';
+  if (has('.windsurf')) return 'windsurf';
+  if (has('.clinerules')) return 'cline';
+  if (has('.roo')) return 'roo';
+  if (has('.continue')) return 'continue';
+  if (has('.junie')) return 'junie';
+  if (has('.kiro')) return 'kiro';
+  if (has('.zed')) return 'zed';
+  if (has('.opencode')) return 'opencode';
+  if (has('.amp')) return 'amp';
+  if (has('.jules')) return 'jules';
+  if (has('.antigravity')) return 'antigravity';
+  if (has(join('.github', 'copilot-instructions.md'))) return 'copilot';
+  if (has('.claude') || has('CLAUDE.md')) return 'claude';
+  if (has('.codex')) return 'codex';
+  if (has('.gemini') || has('GEMINI.md')) return 'gemini';
+  if (has('AGENTS.md')) return 'codex';       // weakest: our own harness writes this
   return 'claude';
 }
 
+// The single point of truth for "which assistant are we acting on". Every command
+// goes through here — including doctor, which used to resolve on its own and so
+// could report a different target than the one just installed into.
+//
+// Ambiguity is a distinct outcome, not a value the caller might mistake for an id:
+// returning a sentinel string would let a forgetful caller pass it to targetPaths()
+// and die with `unknown target`. `ids` empty + `ambiguous` set cannot be used by
+// accident.
+export function resolveTargets({ cwd = process.cwd(), flagValue } = {}) {
+  if (typeof flagValue === 'string' && flagValue.trim()) {
+    const ids = flagValue.split(',').map((s) => s.trim()).filter(Boolean);
+    return { ids, ambiguous: null, source: 'flag' };
+  }
+  // The committed manifest is what the team decided, so it outranks what happens to be
+  // on this machine. Two targets here is not ambiguity — it is the team saying "both".
+  const declared = readManifest(cwd)?.targets || [];
+  if (declared.length) return { ids: declared, ambiguous: null, source: 'manifest' };
+  const found = installedTargets(cwd);
+  if (found.length === 1) return { ids: found, ambiguous: null, source: 'evidence' };
+  if (found.length > 1) return { ids: [], ambiguous: found, source: 'evidence' };
+  return { ids: [detectTarget(cwd)], ambiguous: null, source: 'heuristic' };
+}
+
 export function targetPaths(target, home = homedir(), cwd = process.cwd()) {
   const s = SPEC[target];
   if (!s) throw new Error(`unknown target ${target}`);