@ericrisco/rsc 1.1.4 → 1.1.6

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/domains.js

@@ -17,14 +17,14 @@ export const DOMAINS = [
   { title: 'AI — build it in', ids: ['building-agents', 'rag', 'embeddings-search', 'prompt-engineering', 'llm-pipeline', 'agent-eval', 'chatbot', 'ai-media', 'replicate-images', 'structured-extraction', 'agent-safety', 'cost-tracking'] },
   { title: 'AI — run it on', ids: ['replicate', 'runpod', 'modal', 'huggingface', 'ollama', 'together-fireworks', 'fal'] },
   { title: 'AI — train it', ids: ['machine-learning', 'deep-learning', 'nlp', 'finetuning', 'training-data', 'unsloth', 'open-weights', 'vllm'] },
-  { title: 'Languages', ids: ['typescript', 'python', 'java', 'csharp-dotnet', 'php', 'ruby', 'cpp', 'elixir', 'bash-scripting', 'sql', 'go', 'write-swift'] },
-  { title: 'Frameworks & app stacks', ids: ['fastapi', 'nextjs', 'react', 'react-native', 'vue-nuxt', 'angular', 'svelte', 'astro', 'solid-js', 'htmx', 'nodejs', 'nestjs', 'django', 'laravel', 'rails', 'spring-boot', 'phoenix', 'flutter', 'swift-ios', 'kotlin-android', 'compose-multiplatform', 'expo', 'tauri', 'electron', 'rust', 'wordpress', 'shopify', 'no-code-app', 'chrome-extension', 'api-design', 'pick-ui-library', 'ask-sonner'] },
+  { title: 'Languages', ids: ['typescript', 'python', 'java', 'csharp-dotnet', 'php', 'ruby', 'cpp', 'elixir', 'bash-scripting', 'sql', 'go'] },
+  { title: 'Frameworks & app stacks', ids: ['fastapi', 'nextjs', 'react', 'react-native', 'vue-nuxt', 'angular', 'svelte', 'astro', 'solid-js', 'htmx', 'nodejs', 'nestjs', 'django', 'laravel', 'rails', 'spring-boot', 'phoenix', 'flutter', 'swift-ios', 'kotlin-android', 'compose-multiplatform', 'expo', 'tauri', 'electron', 'rust', 'wordpress', 'shopify', 'no-code-app', 'chrome-extension', 'api-design'] },
   { title: 'Game development', ids: ['godot', 'unity', 'unreal', 'game-design', 'game-storytelling', 'level-design', 'gamedev-shaders', 'gamedev-multiplayer', 'gamedev-physics', 'gamedev-pathing', 'gamedev-shipping'] },
   { title: 'Databases & data layer', ids: ['postgresdb', 'mysql', 'mongodb', 'redis', 'supabase', 'neon', 'planetscale', 'sqlite-turso', 'prisma-orm', 'drizzle-orm', 'firebase', 'dynamodb', 'vector-db', 'clickhouse-analytics', 'duckdb', 'db-migrations', 'backups'] },
   { title: 'Ship & operate — platforms', ids: ['vercel', 'netlify', 'cloudflare', 'railway', 'render', 'fly-io', 'coolify', 'hetzner', 'digitalocean', 'aws-essentials', 'gcp-essentials'] },
   { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { 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: ['design-eng', 'animate', 'animate-expo', 'review-animations', 'improve-animations', 'find-animation-opportunities', 'animation-vocabulary', 'apple-design', 'prototype'] },
+  { 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'] },
 ];

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/design/SKILL.md

@@ -11,9 +11,9 @@ origin: risco
 
 **Hand-off — the visual system vs the craft of motion.** This skill owns the visual system and page
 composition, and sets motion *intent + budget* only. The **implementation** of an animation is
-`../animate/SKILL.md`'s; reviewing motion is `../review-animations/SKILL.md`'s; gesture physics and
-translucent materials are `../apple-design/SKILL.md`'s. When a frontend request could belong to
-several of those, `../design-eng/SKILL.md` is the umbrella that routes it. The motion reference in
+`../motion-craft/SKILL.md`'s; how a piece of interface should be BUILT — boundaries, state, the
+loading and empty and error states — is `../ui-engineering/SKILL.md`'s. When a request could belong to
+several of those, start from the one that owns the decision, not the one that owns the file. The motion reference in
 this skill defers its mechanics to them rather than restating them.
 
 

package/skills/design/references/design-systems.md

@@ -42,7 +42,7 @@ not settle whether the page says anything.
 
 ## Where to browse for component ideas
 
-When a surface needs an idea rather than a primitive, `../../pick-ui-library/references/component-galleries.md`
+When a surface needs an idea rather than a primitive, a gallery of shipped products
 names where to go — Aceternity for marketing effects, 21st.dev for breadth, React Bits for tunable
 animation — and what each is good for. Take the technique and rebuild it in this project's tokens;
 check the brand study for what it refuses first, because a component that contradicts a stated ban