@ericrisco/rsc 2.1.0 → 2.2.0

package/README.md

@@ -355,8 +355,9 @@ pinned version. It asks; it does not install anything on its own and it does not
 whatever you sat down to do. Say no and it stops asking on that machine.
 
 Not `@latest`, and the difference is the whole point of sharing: a teammate who clones in three
-months gets what you had, not what shipped since. Upgrading is something a person decides, writes
-into `.rsc.json`, and commits — and then it reaches everyone through git, like any other change.
+months gets what you had, not what shipped since. Once it is built, the same rules as any project
+apply: releases in the same major install themselves (see [Update](#update)), and the new
+`catalogVersion` in `.rsc.json` reaches everyone when somebody commits it.
 
 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.
@@ -403,8 +404,26 @@ so rsc does not repair, move or delete them — not even when rebuilding from sc
 
 ## Update
 
-`rsc` is an npm package, so updating is two steps — bump the package, then
-re-sync what's already wired into your project:
+**rsc updates itself.** When a session starts, rsc checks npm for a newer version:
+
+- **Same major** (`2.1.0 → 2.1.1` or `2.2.0`): it installs that exact version in the background.
+  It takes effect in the next session, and that session tells you it happened.
+- **New major** (`2.x → 3.0.0`): it can change how the harness works, so the assistant asks first.
+- **Failed:** the assistant asks instead, and rsc retries once a day. The output is in
+  `.rsc/auto-update.log`.
+
+A new install asks whether you want this (yes by default). To turn it off later, create
+`.rsc/.no-auto-update`; every release then asks. It is a project decision: it travels in
+`.rsc.json` like the other switches. The update can leave harness files changed in git; rsc never
+commits them for you.
+
+Where it runs on its own: **Claude Code, Codex, Gemini CLI, Cursor and OpenCode**, from a
+session-start hook. Every other assistant has no such hook, so the always-on instructions ask the
+agent to run `node .rsc/auto-update.mjs` on its first turn — same rules, but it depends on the agent
+doing it (and some assistants ask your permission before running a command). Codex asks you to
+trust new hooks once.
+
+To update by hand, bump the package, then re-sync what's already wired into your project:
 
 ```bash
 npm install -g @ericrisco/rsc@latest   # global install: pull the newest catalog

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.0",
+  "version": "2.2.0",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/install-apply.js

@@ -22,6 +22,7 @@ import {
 import {
   wireMemory, unwireMemory, memoryManagedPaths, memoryModeFor, memoryEnabledForProject, memoryArtifactsPresent,
 } from '../targets/memory.js';
+import { wireUpdate, unwireUpdate, updateManagedPaths, updateArtifactsPresent } from '../targets/update-wiring.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CLI_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
@@ -78,6 +79,7 @@ export function generatedHookFiles({ target, cwd, policy }) {
     join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
     join(cwd, '.rsc', 'hook-once.mjs'),
     join(cwd, '.rsc', 'worktree-reaper.mjs'),
+    join(cwd, '.rsc', 'auto-update.mjs'),
   ];
   // The danger guard is declared on its own terms (#273): present unless the plan says otherwise,
   // whether or not the code guards are.
@@ -95,6 +97,7 @@ export function managedPathsForInstall({ skillIds, agentIds = [], target, home,
   const out = [paths.stateFile, versionFile(cwd), baseVersionsFile(cwd)];
   if (policy?.context7 === false) out.push(join(cwd, '.rsc', '.no-context7'));
   if (policy?.memory !== false) out.push(...memoryManagedPaths(target, cwd));
+  out.push(...updateManagedPaths(target, cwd));
   if (targetHasAgents(target)) {
     const state = readState(paths.stateFile);
     const explicit = [...new Set([...(state.explicitAgents || readManifest(cwd)?.agents || []), ...agentIds])];
@@ -297,6 +300,8 @@ export async function applyInstall({ skillIds = [], agentIds = [], target, home,
     ? { mode: 'disabled', reason: 'onboarding-policy', paths: unwireMemory(target, cwd) }
     : wireMemory(target, cwd);
   state.memory = { mode: memoryResult.mode, reason: memoryResult.reason, paths: memoryResult.paths };
+  const updateResult = wireUpdate(target, cwd);
+  state.update = { mode: updateResult.mode, ...(updateResult.reason ? { reason: updateResult.reason } : {}) };
   const context7OptOut = join(cwd, '.rsc', '.no-context7');
   if (policy?.context7 === false) {
     mkdirSync(dirname(context7OptOut), { recursive: true });
@@ -596,6 +601,7 @@ export function removeTargetInstall({ target, home, cwd = process.cwd() }) {
   }
   unwireHook(target, paths);
   unwireMemory(target, cwd);
+  unwireUpdate(target, cwd);
   rmSync(paths.stateFile, { force: true });
   const gitignore = join(cwd, '.gitignore');
   if (existsSync(gitignore)) {
@@ -704,8 +710,10 @@ export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRu
     if (!dryRun) {
       removed.push(...unwireHook(target, paths));
       removed.push(...unwireMemory(target, cwd));
+      removed.push(...unwireUpdate(target, cwd));
     } else {
       removed.push(...memoryArtifactsPresent(target, cwd));
+      removed.push(...updateArtifactsPresent(target, cwd));
     }
     // A lost state file also loses proof of ownership. Leave same-named user files
     // behind rather than guessing from a catalog id and deleting their work.

package/skills/init/SKILL.md

@@ -137,7 +137,7 @@ cargan al arrancar la sesión."* Full skill map and sample printouts → `refere
 
 ### Phase 4 — GROUND
 
-Four checks once the skills are in. The SessionStart hook nudges each of these too; doing them here
+Five checks once the skills are in. The SessionStart hook nudges each of these too; doing them here
 means the user starts clean.
 
 1. **Version control.** No `.git/` → offer `git init`; the SDD chain and the ship guard assume it.
@@ -154,6 +154,15 @@ means the user starts clean.
    `WHERE`, `dd` to a device, `curl | bash` — and asks for a safer alternative. A fully `technical`
    user is never guarded. It turns off only if the user explicitly asks: `.rsc/.no-danger-guard`.
    Mention it when you record `non-technical`, so a later block is not a surprise.
+5. **Automatic updates.** Ask once, yes by default:
+   > *"Cuando salga una versión nueva de rsc, ¿la instalo sola? Las que cambian mucho (major) te las
+   > preguntaré siempre. (sí/no)"*
+
+   > *"When a new rsc version comes out, should I install it on my own? Big ones (major) I will
+   > always ask about. (yes/no)"*
+
+   Yes, or no clear answer → do nothing; it is on. No → create `.rsc/.no-auto-update`: every
+   release then asks. It is a project switch, recorded in `.rsc.json` on the next sync.
 
 ### Phase 5 — HANDOFF
 

package/targets/_md-block.js

@@ -13,6 +13,12 @@ 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';
+// Most assistants that read a rules file have no session-start hook, so nothing checks for a new rsc
+// on its own. The agent does it instead. Here and not in suggest's body: the body is paid on every
+// turn by every assistant, Claude Code included, which already checks from its hook.
+export const UPDATE_NOTE = '**rsc updates.** Claude Code, Codex, Gemini CLI, Cursor and OpenCode check for a new rsc on their '
+  + 'own. In any other assistant, run `node .rsc/auto-update.mjs` once on the first turn of a session and relay any '
+  + 'notice it prints in one line; "up to date" needs no mention.\n';
 
 export function writeSkill(id, fromDir, toPath) {
   return linkOrCopy(fromDir, toPath);
@@ -23,7 +29,7 @@ export function wireHook(paths, sourceMd, policy = {}) {
   const body = policy.codeHooks === false
     ? `# rsc-suggest — always-on operations layer\n\nRead \`02-DOCS/wiki/harness/user-profile.md\` before acting. Use \`orient\` to keep the user situated and \`suggest\` to offer a missing skill only when the current task needs it. Close with the configured orientation block.\n`
     : full;
-  const block = `${MARK_START}\n${body}\n${MARK_END}`;
+  const block = `${MARK_START}\n${body}\n${UPDATE_NOTE}\n${MARK_END}`;
   let doc = existsSync(paths.hookTarget) ? readFileSync(paths.hookTarget, 'utf8') : '';
   if (doc.includes(MARK_START)) {
     doc = doc.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);

package/targets/auto-update.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// rsc update check, shared by every assistant that can run it. Standalone (Node built-ins only),
+// copied to `.rsc/auto-update.mjs` at install, like the other hooks.
+//
+// Three ways in, one rule:
+//   - Claude Code: `session-start.mjs` imports `updateNotice` and prints it with the always-on body.
+//   - Codex, Gemini CLI, Cursor: a session-start hook runs `node .rsc/auto-update.mjs hook <target>`
+//     and gets the notice back in that assistant's own output shape.
+//   - OpenCode: its plugin imports `updateNotice` and hands the notice to the model.
+//   - Any other assistant has no hook. The always-on body asks the agent to run
+//     `node .rsc/auto-update.mjs` on its first turn, and to relay what it prints.
+import { readFileSync, existsSync, writeFileSync, openSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Update check: compare the installed version (.rsc/.version, written at install)
+// against the latest published on npm, and nudge the agent to offer an update.
+// Fail-silent (offline / missing baseline / parse error → nothing). Disable with
+// RSC_NO_UPDATE_CHECK=1. RSC_LATEST overrides the npm lookup (tests / mirrors).
+function isNewer(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+// "rsc X is out" was being ignored — the maintainer's own workspace sat on 2.0.4 for days with this
+// notice on every session, and two people in two days reported bugs that were already fixed. A
+// version number names nothing anyone recognises. A symptom does: someone who sees a red error after
+// every turn updates the moment they are told that is what the update fixes (`suggest` §3: say what
+// is wrong as a symptom, not as a cause).
+//
+// The symptoms travel for free: the registry's `/latest` document is the published package.json, so
+// its `rscFixes` field — `{ fixedIn, symptom }` — arrives in the response this check already makes.
+// It is text a model will read, so every entry is reduced to one short plain line or dropped.
+const SEMVER_ONLY = /^\d+\.\d+\.\d+$/;
+function fixesSince(list, installed, latest) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const item of list) {
+    if (!item || typeof item !== 'object' || typeof item.symptom !== 'string') continue;
+    if (!SEMVER_ONLY.test(String(item.fixedIn))) continue;
+    if (!isNewer(item.fixedIn, installed) || isNewer(item.fixedIn, latest)) continue;
+    const symptom = item.symptom.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200);
+    if (symptom) out.push({ fixedIn: item.fixedIn, symptom });
+  }
+  return out.slice(0, 8);
+}
+
+// Auto-update. Asking was not enough: the notice depended on an agent relaying it, and people kept
+// running bugs that were already fixed. So a release in the SAME major installs itself; a new major
+// can change how the harness works, and still asks. On by default; `.rsc/.no-auto-update` (a project
+// decision, travels in `optOuts`) brings back the question for every release.
+//
+// It runs in the background because `npx` can take longer than a hook may, and it changes nothing in
+// this session anyway: the skills are already loaded. The version is the exact one seen here, never
+// `@latest` — what is published in between does not slip in. One attempt per version: a failure falls
+// back to asking, and is retried at most once a day.
+const stateFile = (root) => join(root, '.rsc', 'auto-update.json');
+const logFile = (root) => join(root, '.rsc', 'auto-update.log');
+const AUTO_RUNNING_MS = 15 * 60 * 1000;
+const AUTO_RETRY_MS = 24 * 60 * 60 * 1000;
+const majorOf = (v) => Number(String(v).split('.')[0]) || 0;
+
+function readAutoState(root) {
+  try { return JSON.parse(readFileSync(stateFile(root), 'utf8')); } catch { return null; }
+}
+function writeAutoState(root, state) {
+  try { writeFileSync(stateFile(root), `${JSON.stringify(state, null, 2)}\n`); } catch { /* best effort */ }
+}
+function declaredTargets(root) {
+  try {
+    const list = JSON.parse(readFileSync(join(root, '.rsc.json'), 'utf8')).targets;
+    return Array.isArray(list) ? list.filter((t) => typeof t === 'string' && /^[a-z0-9-]+$/.test(t)) : [];
+  } catch { return []; }
+}
+function launchUpdate(root, version, env) {
+  // RSC_AUTO_UPDATE_CMD (a JSON argv) replaces npx in tests; the arguments after it are the real ones.
+  const base = env.RSC_AUTO_UPDATE_CMD
+    ? JSON.parse(env.RSC_AUTO_UPDATE_CMD)
+    : ['npx', '-y', `@ericrisco/rsc@${version}`];
+  const targets = declaredTargets(root);
+  const args = [...base.slice(1), 'sync', ...(targets.length ? ['--target', targets.join(',')] : [])];
+  const log = openSync(logFile(root), 'w');
+  const child = spawn(base[0], args, {
+    cwd: root,
+    detached: true,
+    stdio: ['ignore', log, log],
+    windowsHide: true,
+    shell: process.platform === 'win32', // npx is npx.cmd there; every argument was validated above
+    env: { ...env, RSC_NO_UPDATE_CHECK: '1', RSC_AUTO_UPDATE_TO: version },
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+
+export async function updateNotice(root, env = process.env) {
+  let out = '';
+  const say = (text) => { out += text; };
+  try {
+    const installed = readFileSync(join(root, '.rsc', '.version'), 'utf8').trim();
+    // A background update that finished since the last session: say so once, then keep quiet.
+    const prior = readAutoState(root);
+    if (prior && !prior.reported && SEMVER_ONLY.test(String(prior.to)) && !isNewer(prior.to, installed)) {
+      say(`
+===== rsc updated =====
+rsc updated itself in the background, from ${prior.from} to ${installed}. It is active in this session.
+ACTION: tell the user in one line. Files of the harness may show as changed in git.
+=======================
+`);
+      writeAutoState(root, { ...prior, reported: true });
+    }
+    let doc = null;
+    if (env.RSC_LATEST_JSON) doc = JSON.parse(env.RSC_LATEST_JSON);
+    else if (env.RSC_LATEST) doc = { version: env.RSC_LATEST };
+    else {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 1500);
+      const res = await fetch('https://registry.npmjs.org/@ericrisco%2frsc/latest', { signal: ctrl.signal });
+      clearTimeout(timer);
+      doc = await res.json();
+    }
+    const latest = doc?.version;
+    if (installed && SEMVER_ONLY.test(String(latest)) && isNewer(latest, installed)) {
+      const newMajor = majorOf(latest) !== majorOf(installed);
+      const auto = !existsSync(join(root, '.rsc', '.no-auto-update')) && !newMajor;
+      const now = Date.now();
+      const since = prior && prior.to === latest ? now - new Date(prior.startedAt).getTime() : Infinity;
+      if (auto && since >= AUTO_RETRY_MS) {
+        launchUpdate(root, latest, env);
+        writeAutoState(root, { from: installed, to: latest, startedAt: new Date(now).toISOString() });
+        say(`
+===== rsc updating =====
+rsc ${latest} is out — you have ${installed}. It is installing itself in the background now and
+takes effect in the next session. Nothing to do.
+ACTION: tell the user in one line, then continue with the task.
+========================
+`);
+      } else if (auto && since < AUTO_RUNNING_MS) {
+        say(`
+===== rsc updating =====
+rsc ${latest} is still installing itself in the background. It takes effect in the next session.
+========================
+`);
+      } else {
+        // Asking: auto-update is off here, the release is a new major, or the background attempt failed.
+        let why = '';
+        if (auto) why = `The automatic update did not finish (log: .rsc/auto-update.log); it retries once a day.\n`;
+        else if (newMajor) why = 'It is a new major version: it can change how the harness works, so it asks first.\n';
+        let fixes = [];
+        try { fixes = fixesSince(doc.rscFixes, installed, latest); } catch { fixes = []; }
+        if (fixes.length) {
+          say(`
+===== rsc update available =====
+rsc ${latest} is out — you have ${installed}. It fixes problems this install still has:
+${fixes.map((f) => `  - ${f.symptom} (fixed in ${f.fixedIn})`).join('\n')}
+${why}ACTION: before starting the task, tell the user in one line that the update fixes what they
+may be seeing, and if they say yes, run it in this project:
+  npx @ericrisco/rsc@latest
+================================
+`);
+        } else {
+          say(`
+===== rsc update available =====
+rsc ${latest} is out — you have ${installed}.
+${why}ACTION: tell the user a new version is available and, if they say yes, run:
+  npx @ericrisco/rsc@latest
+(That reinstalls and refreshes the skill content to the latest.)
+================================
+`);
+        }
+      }
+    }
+  } catch { /* offline / no baseline / parse error → stay silent */ }
+  return out;
+}
+
+// What each assistant's session-start hook accepts. Codex and Gemini take Claude's shape; Cursor has
+// its own field names. Plain text for an agent that runs this by hand.
+export function hookOutput(target, notice) {
+  if (!notice) return target === 'agent' ? '' : '{}';
+  if (target === 'agent') return notice;
+  if (target === 'cursor') return JSON.stringify({ additional_context: notice });
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: notice } });
+}
+
+// Run as a script: `node auto-update.mjs [hook <target>] [root]`. Never fails a session.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const hook = process.argv[2] === 'hook';
+  const target = hook ? String(process.argv[3] || 'agent') : 'agent';
+  const root = (hook ? process.argv[4] : process.argv[2]) || process.cwd();
+  let notice = '';
+  try { if (!process.env.RSC_NO_UPDATE_CHECK) notice = (await updateNotice(root)).trim(); } catch { /* fail open */ }
+  if (!hook && !notice) notice = 'rsc is up to date.';
+  process.stdout.write(`${hookOutput(target, notice)}\n`);
+}

package/targets/claude.js

@@ -118,6 +118,8 @@ export function wireHook(paths, sourceMd, policy = {}) {
   // Same reason: session-start imports the reaper for the landed-worktree sweep, so it travels as a
   // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
   copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
+  // session-start imports the shared update check, so it travels as a sibling too.
+  copyFileSync(join(HERE, 'auto-update.mjs'), join(paths.projectRoot, '.rsc', 'auto-update.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
   // The one harness file that belongs in the committed tree rather than in `.rsc/`: it is the only
   // thing standing between a clone and seven stack traces, so it has to survive `git clone`.

package/targets/clone-bootstrap.mjs

@@ -43,7 +43,7 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i;
  * nothing checks is just drift with a head start.
  */
 export const PROJECT_OPT_OUTS = [
-  'audit', 'claudemd-check', 'danger-guard', 'feature-gate', 'gitmoji', 'ship-guard', 'worktree-cleanup',
+  'audit', 'auto-update', 'claudemd-check', 'danger-guard', 'feature-gate', 'gitmoji', 'ship-guard', 'worktree-cleanup',
 ];
 
 /**

package/targets/opt-outs.js

@@ -18,6 +18,7 @@
 /** Decisions of the project: they belong in `.rsc.json` and are rebuilt in a clone. */
 export const PROJECT_OPT_OUTS = [
   'audit',            // cadence of this project's skill audit
+  'auto-update',      // installing new rsc releases alone: one machine ahead moves the team's catalogVersion
   'claudemd-check',   // the root CLAUDE.md context budget
   'danger-guard',     // foot-gun denial, keyed to the committed user profile
   'feature-gate',     // per-turn re-injection of the SDD gate

package/targets/session-start.mjs

@@ -6,6 +6,7 @@
 // workspace has no harness profile yet, and an auto-ingest nudge when there is
 // un-ingested material waiting in the inbox.
 import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { updateNotice } from './auto-update.mjs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { claimOnce, readHookInput } from './hook-once.mjs';
@@ -252,80 +253,6 @@ A no holds for this session. Permanent off: .rsc/.no-worktree-cleanup
   } catch { /* reaper missing or git unhappy → say nothing; this is never worth breaking startup for */ }
 }
 
-// Update check: compare the installed version (.rsc/.version, written at install)
-// against the latest published on npm, and nudge the agent to offer an update.
-// Fail-silent (offline / missing baseline / parse error → nothing). Disable with
-// RSC_NO_UPDATE_CHECK=1. RSC_LATEST overrides the npm lookup (tests / mirrors).
-function isNewer(a, b) {
-  const pa = String(a).split('.').map(Number);
-  const pb = String(b).split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) > (pb[i] || 0)) return true;
-    if ((pa[i] || 0) < (pb[i] || 0)) return false;
-  }
-  return false;
-}
-
-// "rsc X is out" was being ignored — the maintainer's own workspace sat on 2.0.4 for days with this
-// notice on every session, and two people in two days reported bugs that were already fixed. A
-// version number names nothing anyone recognises. A symptom does: someone who sees a red error after
-// every turn updates the moment they are told that is what the update fixes (`suggest` §3: say what
-// is wrong as a symptom, not as a cause).
-//
-// The symptoms travel for free: the registry's `/latest` document is the published package.json, so
-// its `rscFixes` field — `{ fixedIn, symptom }` — arrives in the response this check already makes.
-// It is text a model will read, so every entry is reduced to one short plain line or dropped.
-const SEMVER_ONLY = /^\d+\.\d+\.\d+$/;
-function fixesSince(list, installed, latest) {
-  if (!Array.isArray(list)) return [];
-  const out = [];
-  for (const item of list) {
-    if (!item || typeof item !== 'object' || typeof item.symptom !== 'string') continue;
-    if (!SEMVER_ONLY.test(String(item.fixedIn))) continue;
-    if (!isNewer(item.fixedIn, installed) || isNewer(item.fixedIn, latest)) continue;
-    const symptom = item.symptom.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200);
-    if (symptom) out.push({ fixedIn: item.fixedIn, symptom });
-  }
-  return out.slice(0, 8);
-}
-
-if (!process.env.RSC_NO_UPDATE_CHECK) {
-  try {
-    const installed = readFileSync(join(root, '.rsc', '.version'), 'utf8').trim();
-    let doc = null;
-    if (process.env.RSC_LATEST_JSON) doc = JSON.parse(process.env.RSC_LATEST_JSON);
-    else if (process.env.RSC_LATEST) doc = { version: process.env.RSC_LATEST };
-    else {
-      const ctrl = new AbortController();
-      const timer = setTimeout(() => ctrl.abort(), 1500);
-      const res = await fetch('https://registry.npmjs.org/@ericrisco%2frsc/latest', { signal: ctrl.signal });
-      clearTimeout(timer);
-      doc = await res.json();
-    }
-    const latest = doc?.version;
-    if (installed && latest && isNewer(latest, installed)) {
-      let fixes = [];
-      try { fixes = fixesSince(doc.rscFixes, installed, latest); } catch { fixes = []; }
-      if (fixes.length) {
-        process.stdout.write(`
-===== rsc update available =====
-rsc ${latest} is out — you have ${installed}. It fixes problems this install still has:
-${fixes.map((f) => `  - ${f.symptom} (fixed in ${f.fixedIn})`).join('\n')}
-ACTION: before starting the task, tell the user in one line that the update fixes what they
-may be seeing, and if they say yes, run it in this project:
-  npx @ericrisco/rsc@latest
-================================
-`);
-      } else {
-        process.stdout.write(`
-===== rsc update available =====
-rsc ${latest} is out — you have ${installed}.
-ACTION: tell the user a new version is available and, if they say yes, run:
-  npx @ericrisco/rsc@latest
-(That reinstalls and refreshes the skill content to the latest.)
-================================
-`);
-      }
-    }
-  } catch { /* offline / no baseline / parse error → stay silent */ }
-}
+// Update check and auto-update: the rule lives in auto-update.mjs, shared with the other assistants.
+// Disable with RSC_NO_UPDATE_CHECK=1.
+if (!process.env.RSC_NO_UPDATE_CHECK) process.stdout.write(await updateNotice(root));

package/targets/update-wiring.js

@@ -0,0 +1,153 @@
+// Wiring for the update check (`auto-update.mjs`). Every assistant gets the module in `.rsc/`; the
+// ones with a session-start event also get a hook that runs it, in the same project-local config
+// files the session memory uses, under a needle of its own so either can be wired or removed
+// without touching the other.
+//
+// Kept apart from `memory.js` on purpose: the memory promises it makes no network request, and a
+// test holds every file it wires to that. The update check exists to ask npm.
+//
+// Claude Code is not in CONFIG: its `session-start.mjs` already imports the module. An assistant
+// with no hook at all is told by the always-on body to run the module on its first turn.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const NEEDLE = '.rsc/auto-update.mjs';
+const PLUGIN_MARKER = 'rsc-update:managed';
+
+const CONFIG = Object.freeze({
+  codex: '.codex/hooks.json',
+  cursor: '.cursor/hooks.json',
+  gemini: '.gemini/settings.json',
+  opencode: '.opencode/plugins/rsc-update.js',
+});
+
+const EVENT = Object.freeze({ codex: 'SessionStart', gemini: 'SessionStart', cursor: 'sessionStart' });
+
+/** Assistants where the update runs on its own. Every other one depends on the agent running it. */
+export const UPDATE_HOOK_TARGETS = Object.freeze(['claude', ...Object.keys(CONFIG)].sort());
+
+const git = (cwd, args) => {
+  try { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; }
+};
+const rel = (cwd, path) => relative(cwd, path).split(sep).join('/');
+const tracked = (cwd, path) => Boolean(git(cwd, ['ls-files', '--', rel(cwd, path)]));
+
+function exclude(cwd, path) {
+  if (git(cwd, ['rev-parse', '--is-inside-work-tree']) !== 'true') return;
+  const value = git(cwd, ['rev-parse', '--git-path', 'info/exclude']);
+  if (!value) return;
+  const file = isAbsolute(value) ? value : resolve(cwd, value);
+  const pattern = `/${rel(cwd, path)}`;
+  mkdirSync(dirname(file), { recursive: true });
+  const body = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (!body.split('\n').includes(pattern)) appendFileSync(file, `${body && !body.endsWith('\n') ? '\n' : ''}${pattern}\n`);
+}
+
+function readConfig(path) {
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+const validHookConfig = (c) => Boolean(c) && typeof c === 'object' && !Array.isArray(c)
+  && (!Object.hasOwn(c, 'hooks') || (c.hooks && typeof c.hooks === 'object' && !Array.isArray(c.hooks) && Object.values(c.hooks).every(Array.isArray)));
+
+function handler(target) {
+  const script = target === 'codex'
+    ? '"$(git rev-parse --show-toplevel)/.rsc/auto-update.mjs"'
+    : '".rsc/auto-update.mjs"';
+  const value = { type: 'command', command: `node ${script} hook ${target}`, timeout: target === 'gemini' ? 10000 : 10 };
+  if (target === 'codex') value.commandWindows = `node "$((git rev-parse --show-toplevel).Trim())/.rsc/auto-update.mjs" hook ${target}`;
+  if (target === 'gemini') value.name = 'rsc-update';
+  return value;
+}
+
+function strip(config) {
+  if (!validHookConfig(config) || !config.hooks) return config;
+  for (const event of Object.keys(config.hooks)) {
+    config.hooks[event] = config.hooks[event].filter((e) => !JSON.stringify(e).replaceAll('\\\\', '/').includes(NEEDLE));
+    if (!config.hooks[event].length) delete config.hooks[event];
+  }
+  if (!Object.keys(config.hooks).length) delete config.hooks;
+  return config;
+}
+
+const PLUGIN = `// ${PLUGIN_MARKER}
+// rsc update check for OpenCode: checked once per OpenCode run, and the notice goes to the model to be
+// relayed. It rides on EVERY system prompt of the run, not just the first: OpenCode's first call is
+// its title generator, which would swallow a once-only notice before the agent ever sees it.
+// Turn auto-update off with .rsc/.no-auto-update.
+import { updateNotice } from '../../.rsc/auto-update.mjs';
+
+export const RscUpdatePlugin = async ({ directory, worktree }) => {
+  const cwd = worktree || directory;
+  const pending = process.env.RSC_NO_UPDATE_CHECK ? Promise.resolve('') : updateNotice(cwd).catch(() => '');
+  return {
+    'experimental.chat.system.transform': async (_input, output) => {
+      const said = (await pending).trim();
+      if (said && Array.isArray(output?.system)) output.system.push(said + '\\nMention this only in your first reply of the session.');
+    },
+  };
+};
+`;
+
+export function updateManagedPaths(target, cwd = process.cwd()) {
+  const module = join(cwd, '.rsc', 'auto-update.mjs');
+  return CONFIG[target] ? [module, join(cwd, ...CONFIG[target].split('/'))] : [module];
+}
+
+/** Wire it. Always: being off is the runtime's `.no-auto-update`, and the check itself stays on. */
+export function wireUpdate(target, cwd = process.cwd()) {
+  const module = join(cwd, '.rsc', 'auto-update.mjs');
+  mkdirSync(dirname(module), { recursive: true });
+  copyFileSync(join(HERE, 'auto-update.mjs'), module);
+  if (!CONFIG[target]) {
+    return { mode: target === 'claude' ? 'hook' : 'agent', paths: [module] };
+  }
+  const configPath = join(cwd, ...CONFIG[target].split('/'));
+  if (tracked(cwd, configPath)) return { mode: 'agent', reason: 'config-tracked', paths: [module] };
+  if (target === 'opencode' && existsSync(configPath) && !readFileSync(configPath, 'utf8').includes(PLUGIN_MARKER)) {
+    return { mode: 'agent', reason: 'plugin-collision', paths: [module] };
+  }
+  const config = target === 'opencode' ? null : readConfig(configPath);
+  if (target !== 'opencode' && !validHookConfig(config)) return { mode: 'agent', reason: 'config-invalid', paths: [module] };
+
+  mkdirSync(dirname(configPath), { recursive: true });
+  if (target === 'opencode') writeFileSync(configPath, PLUGIN);
+  else {
+    strip(config);
+    config.hooks ||= {};
+    const event = EVENT[target];
+    config.hooks[event] ||= [];
+    const h = handler(target);
+    if (target === 'cursor') { config.version ||= 1; delete h.type; delete h.timeout; config.hooks[event].push(h); }
+    else config.hooks[event].push({ hooks: [h] });
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  }
+  const paths = updateManagedPaths(target, cwd);
+  for (const path of paths) exclude(cwd, path);
+  return { mode: 'hook', paths };
+}
+
+export function unwireUpdate(target, cwd = process.cwd()) {
+  if (!CONFIG[target]) return [];
+  const path = join(cwd, ...CONFIG[target].split('/'));
+  const touched = [];
+  if (target === 'opencode') {
+    if (existsSync(path) && readFileSync(path, 'utf8').includes(PLUGIN_MARKER)) { rmSync(path, { force: true }); touched.push(path); }
+  } else if (existsSync(path) && readFileSync(path, 'utf8').replaceAll('\\\\', '/').includes(NEEDLE)) {
+    const config = readConfig(path);
+    if (config) { strip(config); writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`); touched.push(path); }
+  }
+  return touched;
+}
+
+export function updateArtifactsPresent(target, cwd = process.cwd()) {
+  if (!CONFIG[target]) return [];
+  const path = join(cwd, ...CONFIG[target].split('/'));
+  if (!existsSync(path)) return [];
+  const body = readFileSync(path, 'utf8').replaceAll('\\\\', '/');
+  return body.includes(NEEDLE) || body.includes(PLUGIN_MARKER) ? [path] : [];
+}