@rune-kit/rune 2.29.0 → 2.29.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rune",
-  "version": "2.29.0",
+  "version": "2.29.1",
   "description": "66-skill engineering mesh with Codex-native skills, subagents, synchronous lifecycle hooks, security gates, MCP-aware workflows, and project memory.",
   "author": {
     "name": "Rune Contributors"

package/README.md

@@ -103,11 +103,15 @@ Plus **9 domain packs** (product, sales, data-science, support, growth, media, p
 
 ---
 
-## What's New (v2.29.0 — Codex Native)
+## What's New (v2.29.1 — One-Command Update)
+
+> **v2.29.1 (2026-07-24):** v2.29.0 documented the update flow; this release automates it. New **`rune update`** command — one-shot updater for an already-configured project: `git pull --ff-only` any detected Pro/Business tier repos (env var → sibling dir, same detection as setup; a failed pull **aborts loudly**, never a silent half-update), re-runs the managed setup rewrite in place non-interactively (your installed platforms, preset, and tiers are detected from the existing hook config — no prompts), then verifies with doctor + hook drift and reminds Codex users to re-trust `/hooks` only when `.codex/hooks.json` actually changed. Flags: `--no-pull`, `--preset`, `--tier`, `--dry`. Plus: "Updating" sections in all three tier READMEs. Docs-and-CLI patch — no skill or mesh changes. 1,638 tests.
+
+### Previous (v2.29.0 — Codex Native)
 
 > **v2.29.0 (2026-07-23):** Codex stops being a compile target that happens to work and becomes a **first-class native runtime**. The Codex adapter now emits everything current Codex supports natively — `.agents/skills/`, project-scoped agent TOML (`.codex/agents/rune-{heavy,standard,fast}.toml`), a dedicated synchronous hook adapter targeting `.codex/hooks.json` (Codex silently skips async handlers), MCP config, and tier-aware compilation so Free/Pro/Business stacks resolve exactly as on Claude Code. The mesh validator was fixed at the root — `Calls (outbound)` is now the single authoritative edge inventory, acknowledged by the target's `Called By` — moving the canonical count from 209 to **248 connections** (same mesh, honest count; doctor now fails CI on any stale claim). Doctor also grew a cross-tier audit: Business metadata (28 pack skills, 4 orchestrators), $149 pricing, 13-platform count, and JSON-schema validation of the new `docs/config-schema.json` + hooks manifest schema. All XLabs remote-MCP references now go through `XLABS_MCP_TOKEN` — plaintext bearer values are forbidden. 1,615 tests pass.
 
-### Previous (v2.28.0 — Reasoner's Blind Spots)
+#### Earlier (v2.28.0 — Reasoner's Blind Spots)
 
 > **v2.28.0 (2026-07-22):** Completes the reasoning wave. Every addition targets one failure class: **a check that feels done because the model re-read its own work and agreed with itself.** `problem-solver` (v0.6.0) gains a **model failure-mode table** beside its human-bias table — pattern-match satisfaction, template hijack, fluent≠true, prior-as-fact, completion pressure, surface blindness — plus three tells that you are inside one right now (instant confident answer; a stated detail your draft never used; two failed attempts in the same framing). `verification` (v0.8.0) gains the **Constraint Loop** for deliverables carrying a mechanically checkable constraint on their own surface form (banned characters, exact counts, strict formats) — a class Rune had no coverage for: expand the constraint before drafting, verify with a tool, re-scan the whole artifact, ship byte-for-byte. `design` (v0.9.0) gains **render blindness** — a checklist item ticked from source is a prediction, and the imagined render is always flattering; visual items are marked 👁 and are ticked from a render or marked ASSUMED. Advisory throughout, no new skills.
 
@@ -407,6 +411,45 @@ This compiles all 66 skills into your IDE's rules format. Same knowledge, same w
 lifecycle hooks; the remaining adapters preserve the workflows and constraints in the best
 format each runtime supports.
 
+## Updating
+
+New releases are announced on [Telegram](https://t.me/xlabs_updates) and [GitHub Releases](https://github.com/rune-kit/rune/releases); see [`CHANGELOG.md`](CHANGELOG.md) for what changed.
+
+> **One-liner alternative**: `npx @rune-kit/rune@latest update` runs the whole flow below for an already-configured project — git-pulls detected Pro/Business repos, re-runs the managed setup rewrite in place (reusing your installed platforms/preset/tiers), and verifies with doctor. The platform-specific commands below remain the canonical path.
+
+### Claude Code (plugin)
+
+```bash
+claude plugin update rune
+```
+
+Restart Claude Code to load the new version, then re-run the wizard once so hooks and tier skills match the new release:
+
+```bash
+npx @rune-kit/rune@latest setup
+```
+
+### Codex / Cursor / Windsurf / other compiled platforms
+
+Re-running setup with `@latest` fetches the newest compiler and rewrites everything Rune manages **in place** — it is idempotent, and never touches your own config or the human-authored parts of `AGENTS.md`:
+
+```bash
+# same flags you installed with, e.g.:
+npx @rune-kit/rune@latest setup --here
+npx @rune-kit/rune@latest setup --here --platform codex --tier pro
+```
+
+If you use the build pipeline (`rune init` route) instead of the wizard: `npx @rune-kit/rune@latest init --force` regenerates platform files without touching your `.rune/` state.
+
+### Verify after updating
+
+```bash
+npx @rune-kit/rune@latest doctor          # compiled output + mesh integrity
+npx @rune-kit/rune@latest doctor --hooks  # hook drift vs the canonical preset
+```
+
+On Codex, review and re-trust changed hooks with `/hooks`.
+
 ## Quick Start
 
 ```bash

package/compiler/__tests__/update.test.js

@@ -0,0 +1,416 @@
+import assert from 'node:assert';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, test } from 'node:test';
+import { installHooks } from '../commands/hooks/install.js';
+import { detectTiers } from '../commands/setup.js';
+import {
+  detectInstalledPreset,
+  detectInstalledTiers,
+  formatUpdateResult,
+  pullTierRepos,
+  runUpdate,
+} from '../commands/update.js';
+
+let tmpRoot;
+
+/** Seed a tier repo sibling (../Pro or ../Business) with a manifest whose
+ * entries reference the tier env var — matching what real tier manifests emit. */
+async function seedTierRepo(projectRoot, tier, opts = {}) {
+  const tierRoot = path.join(projectRoot, '..', tier === 'pro' ? 'Pro' : 'Business');
+  await mkdir(path.join(tierRoot, 'hooks'), { recursive: true });
+  const envVar = tier === 'pro' ? 'RUNE_PRO_ROOT' : 'RUNE_BUSINESS_ROOT';
+  await writeFile(
+    path.join(tierRoot, 'hooks', 'manifest.json'),
+    JSON.stringify({
+      tier,
+      version: '1.0.0',
+      minFreeVersion: '2.0.0',
+      requires: [envVar],
+      entries: [
+        {
+          id: `${tier}-pulse`,
+          event: 'PreToolUse',
+          matcher: 'Edit|Write',
+          command: `node "\${${envVar}}/hooks/pulse.js"`,
+        },
+      ],
+    }),
+  );
+  if (opts.git) {
+    await mkdir(path.join(tierRoot, '.git'), { recursive: true });
+  }
+  return tierRoot;
+}
+
+async function seedFakeRuneRoot(root) {
+  const runeRoot = path.join(root, 'fake-rune');
+  await mkdir(path.join(runeRoot, 'skills'), { recursive: true });
+  return runeRoot;
+}
+
+/** Install real Free hooks (optionally + tier) into the tmp project so the
+ * "already installed" detection paths have something real to read. */
+async function installProjectHooks(projectRoot, { preset = 'gentle', tier } = {}) {
+  await mkdir(path.join(projectRoot, '.claude'), { recursive: true });
+  await installHooks(projectRoot, { preset, tier, platform: 'claude' });
+}
+
+beforeEach(async () => {
+  delete process.env.RUNE_PRO_ROOT;
+  delete process.env.RUNE_BUSINESS_ROOT;
+  tmpRoot = await mkdtemp(path.join(tmpdir(), 'rune-update-'));
+  await mkdir(path.join(tmpRoot, 'project'), { recursive: true });
+});
+
+afterEach(async () => {
+  if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  delete process.env.RUNE_PRO_ROOT;
+  delete process.env.RUNE_BUSINESS_ROOT;
+});
+
+describe('detectInstalledTiers', () => {
+  test('returns [] for a project with no Rune hook configs', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    assert.deepStrictEqual(await detectInstalledTiers(projectRoot), []);
+  });
+
+  test('returns [] when only Free preset hooks are installed (no false positive)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await installProjectHooks(projectRoot, { preset: 'gentle' });
+    assert.deepStrictEqual(await detectInstalledTiers(projectRoot), []);
+  });
+
+  test('detects pro from RUNE_PRO_ROOT tokens in .claude/settings.json', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedTierRepo(projectRoot, 'pro');
+    await installProjectHooks(projectRoot, { preset: 'gentle', tier: ['pro'] });
+    assert.deepStrictEqual(await detectInstalledTiers(projectRoot), ['pro']);
+  });
+
+  test('detects business from tier token in .codex/hooks.json', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await mkdir(path.join(projectRoot, '.codex'), { recursive: true });
+    await writeFile(
+      path.join(projectRoot, '.codex', 'hooks.json'),
+      JSON.stringify({
+        hooks: {
+          PreToolUse: [
+            {
+              matcher: '.*',
+              // biome-ignore lint/suspicious/noTemplateCurlyInString: literal env token by design
+              hooks: [{ type: 'command', command: 'node "${RUNE_BUSINESS_ROOT}/hooks/gate.js"' }],
+            },
+          ],
+        },
+      }),
+    );
+    assert.deepStrictEqual(await detectInstalledTiers(projectRoot), ['business']);
+  });
+
+  test('detects pro from rune-tier frontmatter in .cursor/rules', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const rulesDir = path.join(projectRoot, '.cursor', 'rules');
+    await mkdir(rulesDir, { recursive: true });
+    await writeFile(path.join(rulesDir, 'rune-pro-pulse.mdc'), '---\nrune-managed: true\nrune-tier: pro\n---\n# x\n');
+    assert.deepStrictEqual(await detectInstalledTiers(projectRoot), ['pro']);
+  });
+});
+
+describe('detectInstalledPreset', () => {
+  test('returns null when nothing is installed', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    assert.strictEqual(await detectInstalledPreset(projectRoot), null);
+  });
+
+  test('returns the installed preset (strict)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await installProjectHooks(projectRoot, { preset: 'strict' });
+    assert.strictEqual(await detectInstalledPreset(projectRoot), 'strict');
+  });
+
+  test('returns gentle for a gentle install', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await installProjectHooks(projectRoot, { preset: 'gentle' });
+    assert.strictEqual(await detectInstalledPreset(projectRoot), 'gentle');
+  });
+});
+
+describe('pullTierRepos', () => {
+  test('reports absent tiers as skipped without calling git', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const calls = [];
+    const exec = async (...args) => {
+      calls.push(args);
+      return { code: 0, stdout: '', stderr: '' };
+    };
+    const detected = detectTiers(projectRoot, { wellKnownPaths: { pro: [], business: [] } });
+    const result = await pullTierRepos({ detected, exec });
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(calls.length, 0);
+    for (const r of result.results) {
+      assert.strictEqual(r.status, 'absent');
+    }
+  });
+
+  test('skips (with note) a detected tier that is not a git repo', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedTierRepo(projectRoot, 'pro'); // no .git
+    const exec = async () => {
+      throw new Error('git must not be called');
+    };
+    const detected = detectTiers(projectRoot, { wellKnownPaths: { pro: [], business: [] } });
+    const result = await pullTierRepos({ detected, exec });
+    assert.strictEqual(result.ok, true);
+    const pro = result.results.find((r) => r.tier === 'pro');
+    assert.strictEqual(pro.status, 'skipped');
+    assert.match(pro.detail, /not a git repo/i);
+  });
+
+  test('pulls a detected git tier with git -C <root> pull --ff-only', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const tierRoot = await seedTierRepo(projectRoot, 'pro', { git: true });
+    const calls = [];
+    const exec = async (cmd, argv) => {
+      calls.push([cmd, argv]);
+      return { code: 0, stdout: 'Already up to date.\n', stderr: '' };
+    };
+    const detected = detectTiers(projectRoot, { wellKnownPaths: { pro: [], business: [] } });
+    const result = await pullTierRepos({ detected, exec });
+    assert.strictEqual(result.ok, true);
+    const pro = result.results.find((r) => r.tier === 'pro');
+    assert.strictEqual(pro.status, 'pulled');
+    assert.strictEqual(calls.length, 1);
+    assert.strictEqual(calls[0][0], 'git');
+    assert.deepStrictEqual(calls[0][1], ['-C', path.resolve(tierRoot), 'pull', '--ff-only']);
+  });
+
+  test('fails loud when git pull fails (dirty tree, auth, ...)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    await seedTierRepo(projectRoot, 'pro', { git: true });
+    const exec = async () => ({ code: 1, stdout: '', stderr: 'error: Your local changes would be overwritten' });
+    const detected = detectTiers(projectRoot, { wellKnownPaths: { pro: [], business: [] } });
+    const result = await pullTierRepos({ detected, exec });
+    assert.strictEqual(result.ok, false);
+    const pro = result.results.find((r) => r.tier === 'pro');
+    assert.strictEqual(pro.status, 'failed');
+    assert.match(pro.detail, /local changes/);
+  });
+});
+
+describe('runUpdate', () => {
+  test('fails with guidance when no Rune installation is detected', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: {},
+      deps: { wellKnownPaths: { pro: [], business: [] } },
+    });
+    assert.strictEqual(result.ok, false);
+    assert.match(result.reason, /setup/i);
+  });
+
+  test('re-runs setup reusing installed preset + tier, pulls tier repo', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTierRepo(projectRoot, 'pro', { git: true });
+    await installProjectHooks(projectRoot, { preset: 'strict', tier: ['pro'] });
+    const execCalls = [];
+    const exec = async (cmd, argv) => {
+      execCalls.push([cmd, argv]);
+      return { code: 0, stdout: 'Already up to date.\n', stderr: '' };
+    };
+
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: {},
+      deps: { exec, skillTarget: runeRoot, wellKnownPaths: { pro: [], business: [] } },
+    });
+
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.preset, 'strict');
+    assert.deepStrictEqual(result.tiers, ['pro']);
+    assert.strictEqual(execCalls.length, 1);
+    assert.ok(result.setup, 'setup result expected');
+    assert.deepStrictEqual(result.setup.tiers, ['pro']);
+    assert.strictEqual(result.setup.preset, 'strict');
+    assert.ok(result.drift, 'drift result expected');
+    const pro = result.pull.results.find((r) => r.tier === 'pro');
+    assert.strictEqual(pro.status, 'pulled');
+  });
+
+  test('does NOT run setup when a tier pull fails', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTierRepo(projectRoot, 'pro', { git: true });
+    await installProjectHooks(projectRoot, { preset: 'gentle', tier: ['pro'] });
+    let setupRan = false;
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: {},
+      deps: {
+        exec: async () => ({ code: 128, stdout: '', stderr: 'fatal: could not read Username' }),
+        runSetupFn: async () => {
+          setupRan = true;
+          return {};
+        },
+        wellKnownPaths: { pro: [], business: [] },
+      },
+    });
+    assert.strictEqual(result.ok, false);
+    assert.strictEqual(setupRan, false);
+    assert.match(result.reason, /pull failed/i);
+  });
+
+  test('--no-pull skips git pulls entirely', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await seedTierRepo(projectRoot, 'pro', { git: true });
+    await installProjectHooks(projectRoot, { preset: 'gentle', tier: ['pro'] });
+    const exec = async () => {
+      throw new Error('git must not be called with --no-pull');
+    };
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: { 'no-pull': true },
+      deps: { exec, skillTarget: runeRoot, wellKnownPaths: { pro: [], business: [] } },
+    });
+    assert.strictEqual(result.ok, true);
+    for (const r of result.pull.results) {
+      assert.notStrictEqual(r.status, 'pulled');
+    }
+  });
+
+  test('skips (with note) an installed tier whose repo is no longer found', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    // Install hooks WITH the pro tier while the repo exists...
+    await seedTierRepo(projectRoot, 'pro');
+    await installProjectHooks(projectRoot, { preset: 'gentle', tier: ['pro'] });
+    // ...then the repo disappears (user deleted the clone).
+    await rm(path.join(projectRoot, '..', 'Pro'), { recursive: true, force: true });
+
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: {},
+      deps: { skillTarget: runeRoot, wellKnownPaths: { pro: [], business: [] } },
+    });
+
+    assert.strictEqual(result.ok, true);
+    assert.deepStrictEqual(result.tiers, []);
+    assert.ok(
+      result.notes.some((n) => /pro/.test(n) && /not found/i.test(n)),
+      `expected a "repo not found" note, got: ${JSON.stringify(result.notes)}`,
+    );
+  });
+
+  test('--dry passes dry through to setup (no writes)', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await installProjectHooks(projectRoot, { preset: 'gentle' });
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: { dry: true, 'no-pull': true },
+      deps: { skillTarget: runeRoot, wellKnownPaths: { pro: [], business: [] } },
+    });
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.setup.written, false);
+  });
+
+  test('flags Codex re-trust when .codex/hooks.json content changed', async () => {
+    const projectRoot = path.join(tmpRoot, 'project');
+    const runeRoot = await seedFakeRuneRoot(tmpRoot);
+    await mkdir(path.join(projectRoot, '.codex'), { recursive: true });
+    // Stale/no hooks file → setup rewrite will change it.
+    const result = await runUpdate({
+      projectRoot,
+      runeRoot,
+      args: { 'no-pull': true },
+      deps: { skillTarget: runeRoot, wellKnownPaths: { pro: [], business: [] } },
+    });
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.codexReTrust, true);
+  });
+});
+
+describe('formatUpdateResult', () => {
+  test('renders pull, setup, and verification summary', () => {
+    const out = formatUpdateResult({
+      ok: true,
+      pull: {
+        ok: true,
+        results: [
+          { tier: 'pro', status: 'pulled', detail: 'Already up to date.' },
+          { tier: 'business', status: 'absent', detail: 'not detected' },
+        ],
+      },
+      platforms: ['claude'],
+      preset: 'gentle',
+      tiers: ['pro'],
+      setup: {
+        scope: 'current',
+        targetRoot: '/p',
+        tiers: ['pro'],
+        preset: 'gentle',
+        platforms: ['claude'],
+        written: true,
+        skillResults: [],
+      },
+      drift: {
+        findings: [],
+        summary: { drifted: 0, missing: 0, errors: 0 },
+        platforms: [{ platform: 'claude', preset: 'gentle' }],
+      },
+      doctor: { skipped: true, reason: 'no rune.config.json' },
+      codexReTrust: false,
+      notes: [],
+    });
+    assert.match(out, /Rune Update/);
+    assert.match(out, /pro.*pulled/i);
+    assert.match(out, /business.*not detected/i);
+    assert.match(out, /preset.*gentle/i);
+    assert.match(out, /0 drifted, 0 missing/);
+    assert.doesNotMatch(out, /\/hooks/);
+  });
+
+  test('renders the Codex re-trust reminder when hooks.json changed', () => {
+    const out = formatUpdateResult({
+      ok: true,
+      pull: { ok: true, results: [] },
+      platforms: ['codex'],
+      preset: 'gentle',
+      tiers: [],
+      setup: { platforms: ['codex'], written: true, skillResults: [] },
+      drift: { findings: [], summary: { drifted: 0, missing: 0, errors: 0 }, platforms: [] },
+      doctor: { skipped: true, reason: 'no rune.config.json' },
+      codexReTrust: true,
+      notes: [],
+    });
+    assert.match(out, /\/hooks/);
+    assert.match(out, /re-trust/i);
+  });
+
+  test('renders loud failure for a failed pull', () => {
+    const out = formatUpdateResult({
+      ok: false,
+      reason: 'tier pull failed — resolve manually and re-run `rune update`',
+      pull: {
+        ok: false,
+        results: [{ tier: 'pro', status: 'failed', detail: 'error: Your local changes would be overwritten' }],
+      },
+      notes: [],
+    });
+    assert.match(out, /✗/);
+    assert.match(out, /pro/);
+    assert.match(out, /local changes/);
+    assert.match(out, /re-run/i);
+  });
+});

package/compiler/bin/rune.js

@@ -25,6 +25,7 @@ import { installHooks } from '../commands/hooks/install.js';
 import { hookStatus } from '../commands/hooks/status.js';
 import { uninstallHooks } from '../commands/hooks/uninstall.js';
 import { formatSetupResult, runSetup } from '../commands/setup.js';
+import { formatUpdateResult, runUpdate } from '../commands/update.js';
 import { generateComprehensionHTML } from '../comprehension.js';
 import { generateDashboardHTML } from '../dashboard.js';
 import { checkMeshIntegrity, formatDoctorResults, formatMeshResults, runDoctor } from '../doctor.js';
@@ -338,6 +339,18 @@ async function cmdSetup(projectRoot, args) {
   }
 }
 
+async function cmdUpdate(projectRoot, args) {
+  try {
+    const result = await runUpdate({ projectRoot, runeRoot: RUNE_ROOT, args });
+    log(formatUpdateResult(result));
+    if (!result.ok) process.exit(1);
+  } catch (err) {
+    log('');
+    log(`  ✗ Update failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 async function readVersion() {
   try {
     const pkg = JSON.parse(await readFile(path.join(RUNE_ROOT, 'package.json'), 'utf-8'));
@@ -852,6 +865,9 @@ async function main() {
     case 'setup':
       await cmdSetup(projectRoot, args);
       break;
+    case 'update':
+      await cmdUpdate(projectRoot, args);
+      break;
     case 'status':
       await cmdStatus(projectRoot, args);
       break;
@@ -887,6 +903,9 @@ async function main() {
         '    setup    Interactive wizard — auto-detect tiers, pick scope, install hooks (recommended for first-time)',
       );
       log('             [--here|--global] [--tier pro,business] [--preset gentle|strict] [--dry]');
+      log('    update   Update an existing install — git-pull detected tier repos, re-run the managed');
+      log('             setup rewrite in place (reuses installed platforms/preset/tiers), verify with doctor');
+      log('             [--no-pull] [--preset gentle|strict] [--tier pro,business] [--dry]');
       log('    init     Interactive setup for build pipeline (auto-detects platform)');
       log('    build    Compile skills for configured platform');
       log('    doctor   Validate compiled output + mesh integrity');

package/compiler/commands/update.js

@@ -0,0 +1,354 @@
+/**
+ * `rune update` — one-shot updater for an already-configured project.
+ *
+ * Mirrors the manual "Updating" flow from the README in a single command:
+ *   1. `git pull --ff-only` any detected paid tier repos (Pro / Business).
+ *      Detection reuses setup's logic: $RUNE_PRO_ROOT / $RUNE_BUSINESS_ROOT
+ *      env vars, then sibling dirs (../Pro, ../Business), then well-known
+ *      paths. Absent tiers and non-git checkouts are skipped with a note;
+ *      a FAILED pull aborts the update (fail loud — never silently continue).
+ *   2. Re-run the managed setup rewrite in place, non-interactively: the
+ *      installed platforms, preset, and tiers are detected from the project's
+ *      existing hook config instead of prompting. Delegates to `runSetup`.
+ *   3. Verify: compiled-output doctor (when a rune.config.json build exists)
+ *      + hook drift report, then print a short summary. Codex users are
+ *      reminded to re-trust hooks via `/hooks` when `.codex/hooks.json`
+ *      changed.
+ *
+ * Non-interactive by design — safe to run from scripts. Flags:
+ *   --no-pull            skip step 1 (tier repos managed some other way)
+ *   --preset <p>         override the detected preset
+ *   --tier <t>[,<t>]     override the detected tier list
+ *   --dry                preview: skip pulls, pass dry to setup (no writes)
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ADAPTERS, detectPlatforms } from '../adapters/hooks/index.js';
+import { checkHookDrift } from './hooks/drift.js';
+import { TIER_ENV_VARS } from './hooks/tiers.js';
+import { detectTiers, runSetup } from './setup.js';
+
+/** Installed hook configs that may carry tier tokens (env var references). */
+const TIER_SCAN_FILES = ['.claude/settings.json', '.codex/hooks.json'];
+
+/** Rule/workflow dirs whose Rune-managed files carry `rune-tier:` frontmatter. */
+const TIER_SCAN_DIRS = ['.cursor/rules', '.windsurf/rules', '.windsurf/workflows', '.antigravity/rules'];
+
+const CODEX_HOOKS_REL_PATH = '.codex/hooks.json';
+
+/**
+ * Detect which paid tiers are wired into this project's installed hook config.
+ * Reads the config files Rune manages and looks for tier env-var tokens
+ * (`RUNE_PRO_ROOT` / `RUNE_BUSINESS_ROOT`) or `rune-tier:` frontmatter.
+ * Free preset entries never contain either marker, so a Free-only install
+ * returns [].
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>} tier names, e.g. ['pro']
+ */
+export async function detectInstalledTiers(projectRoot) {
+  const chunks = [];
+  for (const rel of TIER_SCAN_FILES) {
+    const filePath = path.join(projectRoot, rel);
+    if (existsSync(filePath)) {
+      chunks.push(await readFile(filePath, 'utf-8').catch(() => ''));
+    }
+  }
+  for (const rel of TIER_SCAN_DIRS) {
+    const dir = path.join(projectRoot, rel);
+    if (!existsSync(dir)) continue;
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isFile() || !/\.(md|mdc)$/.test(entry.name)) continue;
+      chunks.push(await readFile(path.join(dir, entry.name), 'utf-8').catch(() => ''));
+    }
+  }
+  const text = chunks.join('\n');
+  const tiers = [];
+  for (const [tier, envVar] of Object.entries(TIER_ENV_VARS)) {
+    const marker = new RegExp(`${envVar}|rune-tier:\\s*${tier}\\b`);
+    if (marker.test(text)) tiers.push(tier);
+  }
+  return tiers;
+}
+
+/**
+ * Detect the preset the project was installed with, by asking each detected
+ * platform adapter for its status. A `mixed` install resolves to `gentle`
+ * (same fallback the drift reporter uses for canonical comparison).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<'gentle'|'strict'|null>} null when nothing is installed
+ */
+export async function detectInstalledPreset(projectRoot) {
+  for (const id of detectPlatforms(projectRoot)) {
+    const status = await ADAPTERS[id].status(projectRoot);
+    if (!status.installed || !status.preset) continue;
+    if (status.preset === 'mixed') return 'gentle';
+    if (status.preset === 'gentle' || status.preset === 'strict') return status.preset;
+  }
+  return null;
+}
+
+/**
+ * Default command runner — thin execFile wrapper that never throws.
+ * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+ */
+function defaultExec(cmd, argv) {
+  return new Promise((resolve) => {
+    execFile(cmd, argv, { windowsHide: true }, (err, stdout, stderr) => {
+      if (err) {
+        resolve({
+          code: typeof err.code === 'number' ? err.code : 1,
+          stdout: stdout ?? '',
+          stderr: stderr || err.message,
+        });
+      } else {
+        resolve({ code: 0, stdout: stdout ?? '', stderr: stderr ?? '' });
+      }
+    });
+  });
+}
+
+/**
+ * `git pull --ff-only` each detected tier repo.
+ *
+ * Statuses per tier:
+ *   - absent  — tier not detected (no env var / sibling / well-known path)
+ *   - skipped — detected but not a git checkout (npx/tarball install)
+ *   - pulled  — git pull succeeded
+ *   - failed  — git pull failed (dirty tree, auth, diverged…) → result.ok=false
+ *
+ * @param {{ detected: ReturnType<typeof detectTiers>, exec?: typeof defaultExec }} opts
+ * @returns {Promise<{ ok: boolean, results: Array<{tier: string, root: string|null, status: string, detail: string}> }>}
+ */
+export async function pullTierRepos({ detected, exec = defaultExec }) {
+  const results = [];
+  for (const tier of Object.keys(TIER_ENV_VARS)) {
+    const info = detected[tier];
+    if (!info) {
+      results.push({ tier, root: null, status: 'absent', detail: 'not detected — skipping' });
+      continue;
+    }
+    // detectTiers points at <tierRoot>/hooks/manifest.json — walk back to the root.
+    const tierRoot = path.resolve(path.dirname(path.dirname(info.path)));
+    if (!existsSync(path.join(tierRoot, '.git'))) {
+      results.push({
+        tier,
+        root: tierRoot,
+        status: 'skipped',
+        detail: `${tierRoot} is not a git repo — pull skipped (update it the way it was installed)`,
+      });
+      continue;
+    }
+    const { code, stdout, stderr } = await exec('git', ['-C', tierRoot, 'pull', '--ff-only']);
+    if (code === 0) {
+      const summary = (stdout.trim().split('\n').pop() || 'done').trim();
+      results.push({ tier, root: tierRoot, status: 'pulled', detail: summary });
+    } else {
+      results.push({ tier, root: tierRoot, status: 'failed', detail: (stderr || stdout).trim() });
+    }
+  }
+  return { ok: results.every((r) => r.status !== 'failed'), results };
+}
+
+/**
+ * Compiled-output verification. Only meaningful for build-pipeline projects
+ * (rune.config.json with a non-Claude platform) — Claude Code loads source
+ * SKILL.md files natively, so there is no compiled output to check.
+ */
+async function defaultDoctorCheck(projectRoot, runeRoot) {
+  const configPath = path.join(projectRoot, 'rune.config.json');
+  if (!existsSync(configPath)) {
+    return { skipped: true, reason: 'no rune.config.json — compiled-output check skipped' };
+  }
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf-8'));
+  } catch (err) {
+    return { skipped: true, reason: `rune.config.json unreadable (${err.message}) — compiled-output check skipped` };
+  }
+  if (!config.platform || config.platform === 'claude') {
+    return { skipped: true, reason: 'Claude Code native — no compiled output to check' };
+  }
+  const { runDoctor } = await import('../doctor.js');
+  const { getAdapter } = await import('../adapters/index.js');
+  const resolvedRuneRoot = config.source === '@rune-kit/rune' ? runeRoot : config.source || runeRoot;
+  const results = await runDoctor({
+    outputRoot: projectRoot,
+    adapter: getAdapter(config.platform),
+    config,
+    runeRoot: resolvedRuneRoot,
+  });
+  return { skipped: false, healthy: results.healthy, results };
+}
+
+/**
+ * The full update flow. Pure orchestration — every side-effecting collaborator
+ * is injectable via `deps` for tests.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.runeRoot
+ * @param {object} [opts.args] — CLI flags: no-pull, preset, tier, dry
+ * @param {object} [opts.deps] — { exec, runSetupFn, checkHookDriftFn, doctorFn, skillTarget, wellKnownPaths }
+ * @returns {Promise<object>} structured result for formatUpdateResult
+ */
+export async function runUpdate({ projectRoot, runeRoot, args = {}, deps = {} }) {
+  const notes = [];
+
+  // ── 0. Something to update? ──
+  const platforms = detectPlatforms(projectRoot);
+  if (platforms.length === 0) {
+    return {
+      ok: false,
+      reason:
+        'No Rune installation detected in this project — nothing to update. Run `npx @rune-kit/rune setup` first.',
+      pull: { ok: true, results: [] },
+      notes,
+    };
+  }
+
+  // ── 1. Pull tier repos (fail loud on pull errors) ──
+  const detected = detectTiers(projectRoot, deps.wellKnownPaths ? { wellKnownPaths: deps.wellKnownPaths } : {});
+  let pull;
+  if (args['no-pull'] || args.dry) {
+    const why = args['no-pull'] ? '--no-pull' : '--dry';
+    pull = {
+      ok: true,
+      results: Object.keys(TIER_ENV_VARS).map((tier) => ({
+        tier,
+        root: null,
+        status: detected[tier] ? 'skipped' : 'absent',
+        detail: detected[tier] ? `pull skipped (${why})` : 'not detected — skipping',
+      })),
+    };
+  } else {
+    pull = await pullTierRepos({ detected, exec: deps.exec });
+  }
+  if (!pull.ok) {
+    return {
+      ok: false,
+      reason: 'tier pull failed — resolve it manually (dirty tree? auth?) then re-run `rune update`',
+      pull,
+      notes,
+    };
+  }
+
+  // ── 2. Re-run managed setup, reusing what is already installed ──
+  const preset = args.preset || (await detectInstalledPreset(projectRoot)) || 'gentle';
+  let tiers;
+  if (args.tier) {
+    tiers = String(args.tier)
+      .split(',')
+      .map((t) => t.trim())
+      .filter(Boolean);
+  } else {
+    const installed = await detectInstalledTiers(projectRoot);
+    tiers = installed.filter((tier) => detected[tier]);
+    for (const tier of installed) {
+      if (!detected[tier]) {
+        const envVar = TIER_ENV_VARS[tier] || `RUNE_${tier.toUpperCase()}_ROOT`;
+        notes.push(
+          `${tier}: hooks are installed but the tier repo was not found — skipping. Set $${envVar} or clone the repo next to Free, then re-run \`rune update\`.`,
+        );
+      }
+    }
+  }
+
+  const codexHooksPath = path.join(projectRoot, CODEX_HOOKS_REL_PATH);
+  const codexBefore = existsSync(codexHooksPath) ? await readFile(codexHooksPath, 'utf-8').catch(() => null) : null;
+
+  const setupArgs = {
+    here: true,
+    preset,
+    dry: args.dry,
+    ...(tiers.length > 0 ? { tier: tiers.join(',') } : { 'no-tier': true }),
+  };
+  const setup = await (deps.runSetupFn || runSetup)({
+    projectRoot,
+    runeRoot,
+    args: setupArgs,
+    skillTarget: deps.skillTarget,
+  });
+
+  const codexAfter = existsSync(codexHooksPath) ? await readFile(codexHooksPath, 'utf-8').catch(() => null) : null;
+  const codexReTrust = platforms.includes('codex') && codexBefore !== codexAfter;
+
+  // ── 3. Verify: compiled output + hook drift ──
+  const doctor = await (deps.doctorFn || defaultDoctorCheck)(projectRoot, runeRoot);
+  const drift = await (deps.checkHookDriftFn || checkHookDrift)(projectRoot);
+
+  return { ok: true, pull, platforms, preset, tiers, setup, drift, doctor, codexReTrust, notes };
+}
+
+const PULL_ICONS = { pulled: '✓', absent: '·', skipped: '·', failed: '✗' };
+
+/**
+ * Render a runUpdate result for console output.
+ * @param {Awaited<ReturnType<typeof runUpdate>>} result
+ * @returns {string}
+ */
+export function formatUpdateResult(result) {
+  const lines = [];
+  lines.push('');
+  lines.push('  Rune Update');
+  lines.push('  ────────────');
+
+  if (result.pull?.results?.length > 0) {
+    lines.push('  Tier repos:');
+    for (const r of result.pull.results) {
+      const icon = PULL_ICONS[r.status] || '·';
+      const label = r.status === 'failed' ? 'pull FAILED' : r.status;
+      lines.push(`    ${icon} ${r.tier} — ${label}: ${r.detail}`);
+    }
+  }
+
+  if (!result.ok) {
+    lines.push('');
+    lines.push(`  ✗ Update aborted: ${result.reason}`);
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('  Setup rewrite:');
+  lines.push(
+    `    Platforms: ${(result.setup?.platforms || result.platforms || []).join(', ') || '—'} | Preset: ${result.preset} | Tiers: Free${result.tiers?.length ? ` + ${result.tiers.join(' + ')}` : ''}`,
+  );
+  for (const sr of result.setup?.skillResults || []) {
+    if (sr.installed?.length > 0) {
+      lines.push(`    Skills: ${sr.tier}: ${sr.installed.length} installed`);
+    } else if (sr.skipped?.length > 0) {
+      lines.push(`    Skills: ${sr.tier}: ${sr.skipped.length} already present / skipped`);
+    }
+  }
+  if (result.setup && result.setup.written === false) {
+    lines.push('    (dry-run — no files written)');
+  }
+
+  lines.push('  Verify:');
+  if (result.doctor?.skipped) {
+    lines.push(`    Doctor: skipped — ${result.doctor.reason}`);
+  } else if (result.doctor) {
+    lines.push(`    Doctor: ${result.doctor.healthy ? '✓ healthy' : '✗ issues found — run `rune doctor` for detail'}`);
+  }
+  if (result.drift?.summary) {
+    const s = result.drift.summary;
+    lines.push(`    Hook drift: ${s.drifted} drifted, ${s.missing} missing, ${s.errors} error(s)`);
+  }
+
+  for (const note of result.notes || []) {
+    lines.push(`  ⚠ ${note}`);
+  }
+
+  if (result.codexReTrust) {
+    lines.push('');
+    lines.push('  ⚠ Codex: .codex/hooks.json changed — open /hooks in Codex to review and re-trust the definitions.');
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.29.0",
+  "version": "2.29.1",
   "description": "66-skill mesh for AI coding assistants — native lifecycle hooks for Claude Code and Codex, 5-layer architecture, 248 connections + 45 signals, and a 13-platform compiler.",
   "type": "module",
   "bin": {