@rune-kit/rune 2.12.2 → 2.13.0

package/README.md

@@ -83,7 +83,15 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.12.0 — Auto-Discipline)
+## What's New (v2.13.0 — Script Contract + Media Pack)
+
+- **`@rune-pro/media` pack v1.0.0** — new Pro pack: raster image generation across 5 providers (Codex CLI, DALL-E, Replicate, Stability AI, local SD), prompt engineering with 4-gate safety check (trademark, public-figure, prompt-injection, uncanny-precondition), batch asset pipeline with multi-resolution variants + WebP/AVIF conversion + EXIF strip. Fills the raster gap left by `asset-creator` (SVG/HTML only) and `video-creator` (planning only).
+- **`sentinel-env` v0.3.0** — 9-tier binary detection for hard-dependency checks. Catches desktop-app bundles (macOS `.app`), npm-global on Windows (PATH oversight), platform release archives. Eliminates the "binary installed but not detected" failure class.
+- **`skill-forge` v1.8.0** — new Phase 5.25 "Script Contract" — helper scripts must follow stdout=paths / stderr=diagnostics / `--json` opt-in / `--debug` opt-in pattern, implement semantic exit codes (including `4` timeout-partial vs `124` timeout-zero), honor OpenClaw artifact-directory fallback chain. HARD-GATE on pre-ship verification.
+- **OpenClaw adapter** — `generateManifest` now declares `artifactConvention` (output-dir fallback order, output contract, exit-code vocabulary). Formalizes the de-facto in-the-wild convention from [codex-imagen](https://github.com/darkamenosa/codex-imagen).
+- **Skill-count scaling** — OpenClaw manifest description now scales with actual skill count rather than hardcoded.
+
+### Previous (v2.12.0 — Auto-Discipline)
 
 - **Runtime auto-discipline** — `rune hooks install` wires native hooks on Claude Code, Cursor, Windsurf, Antigravity so `preflight`, `sentinel`, `completion-gate` auto-fire before tool use. No more "remember to invoke the skill."
 - **Three presets** — `strict` (blocking gates), `gentle` (warnings, default), `off` (uninstall). Idempotent install / uninstall with full restore of user hooks.
@@ -548,17 +556,32 @@ npx @rune-kit/rune doctor
 
 See [docs/MULTI-PLATFORM.md](docs/MULTI-PLATFORM.md) for the full architecture.
 
+## Documentation
+
+| Doc | What's inside |
+|-----|---------------|
+| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | Your first 5 minutes with Rune — install to first `/rune cook` |
+| [`docs/SKILLS.md`](docs/SKILLS.md) | All 62 skills, searchable by intent and layer |
+| [`docs/SIGNALS.md`](docs/SIGNALS.md) | Canonical signal inventory — 25 events, emit/listen graph |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 5-layer mesh architecture reference |
+| [`docs/VISION.md`](docs/VISION.md) | Philosophy — what Rune is and isn't |
+| [`docs/HOOKS.md`](docs/HOOKS.md) | Auto-discipline hooks per platform |
+| [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) | Common issues + fixes |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute skills, packs, fixes |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+| [`ROADMAP.md`](ROADMAP.md) | What's next |
+
 ## Numbers
 
 ```
 Core Skills:       62 (L0: 1 │ L1: 5 │ L2: 29 │ L3: 27)
 Extension Packs:   14 free + 5 pro + 4 business
 Mesh Connections:  215+ cross-references
-Mesh Signals:      23 signals across 62 skills (emit/listen graph)
+Mesh Signals:      25 signals across 62 skills (emit/listen graph)
 Connections/Skill: 3.4 avg
 Platforms:         8 (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)
 Compiler:          ~1400 LOC (parser + 8 transforms + 8 adapters + CLI)
-Tests:             946 (compiler + signals + status + visualizer + hooks + scripts)
+Tests:             1,152+ (compiler + signals + status + visualizer + hooks + scripts + tier-hooks)
 Pack Depth:        23 packs total (14 free + 5 pro + 4 business, all free packs rated Deep)
 ```
 

package/compiler/__tests__/hooks-doctor-tier.test.js

@@ -0,0 +1,214 @@
+/**
+ * Doctor tier-coverage check — warns when a tier's hooks are installed on
+ * Claude but missing on other detected platforms, or when required env vars
+ * are unset so installed hooks would fail at runtime.
+ *
+ * Checks are advisory (WARN) — never block the doctor pipeline.
+ */
+
+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 { listDetectedTiers } from '../commands/hooks/tiers.js';
+import { checkTierCoverage } from '../doctor.js';
+
+const PRO_MANIFEST = {
+  name: 'Rune Pro Hooks',
+  description: 'Pro tier hooks',
+  tier: 'pro',
+  version: '1.0.0',
+  requires: ['RUNE_PRO_ROOT'],
+  entries: [
+    {
+      id: 'context-inject',
+      skill: 'context-inject',
+      event: 'UserPromptSubmit',
+      matcher: '.*',
+      command: 'node "${RUNE_PRO_ROOT}/hooks/run-hook.cjs" context-inject',
+    },
+    {
+      id: 'context-sense',
+      skill: 'context-sense',
+      event: 'PreToolUse',
+      matcher: 'Edit|Write',
+      command: 'node "${RUNE_PRO_ROOT}/hooks/run-hook.cjs" context-sense',
+    },
+  ],
+};
+
+let tmpRoot;
+let tierRoot;
+let originalRunePro;
+
+async function seedTierRoot(tier, manifest) {
+  const dir = await mkdtemp(path.join(tmpdir(), `rune-doc-${tier}-`));
+  await mkdir(path.join(dir, 'hooks'), { recursive: true });
+  await writeFile(path.join(dir, 'hooks', 'manifest.json'), JSON.stringify(manifest, null, 2));
+  return dir;
+}
+
+async function seedPlatform(root, platform) {
+  const map = {
+    claude: { dir: '.claude', settings: true },
+    cursor: { dir: '.cursor/rules' },
+    windsurf: { dir: '.windsurf/workflows' },
+    antigravity: { dir: '.antigravity/rules' },
+  };
+  const spec = map[platform];
+  await mkdir(path.join(root, spec.dir), { recursive: true });
+  if (spec.settings) {
+    await writeFile(path.join(root, '.claude', 'settings.json'), '{}');
+  }
+}
+
+async function seedTierHooksOn(root, platform, tier) {
+  if (platform === 'claude') {
+    const settingsPath = path.join(root, '.claude', 'settings.json');
+    const settings = {
+      hooks: {
+        UserPromptSubmit: [
+          {
+            matcher: '.*',
+            hooks: [
+              { type: 'command', command: 'node "${RUNE_' + tier.toUpperCase() + '_ROOT}/hooks/run-hook.cjs" ctx' },
+            ],
+          },
+        ],
+      },
+    };
+    await mkdir(path.dirname(settingsPath), { recursive: true });
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    return;
+  }
+  const dirs = {
+    cursor: path.join(root, '.cursor/rules'),
+    windsurf: path.join(root, '.windsurf/workflows'),
+    antigravity: path.join(root, '.antigravity/rules'),
+  };
+  const ext = { cursor: '.mdc', windsurf: '.md', antigravity: '.md' }[platform];
+  const dir = dirs[platform];
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, `rune-${tier}-context-inject${ext}`), '# tier hook\n');
+}
+
+beforeEach(async () => {
+  tmpRoot = await mkdtemp(path.join(tmpdir(), 'rune-doctor-tier-'));
+  tierRoot = await seedTierRoot('pro', PRO_MANIFEST);
+  originalRunePro = process.env.RUNE_PRO_ROOT;
+  process.env.RUNE_PRO_ROOT = tierRoot;
+});
+
+afterEach(async () => {
+  if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  if (tierRoot) await rm(tierRoot, { recursive: true, force: true });
+  if (originalRunePro === undefined) delete process.env.RUNE_PRO_ROOT;
+  else process.env.RUNE_PRO_ROOT = originalRunePro;
+});
+
+describe('listDetectedTiers', () => {
+  test('returns empty array when no tier env vars set and no monorepo sibling', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    const result = await listDetectedTiers(tmpRoot);
+    assert.deepStrictEqual(result, []);
+  });
+
+  test('returns Pro tier when RUNE_PRO_ROOT resolves', async () => {
+    const result = await listDetectedTiers(tmpRoot);
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].tier, 'pro');
+    assert.strictEqual(result[0].found, true);
+    assert.strictEqual(result[0].requiresOk, true);
+    assert.deepStrictEqual(result[0].requiresMissing, []);
+  });
+
+  test('reports requiresMissing when env var gets unset after locate', async () => {
+    // Manifest locates via a secondary path (env set at locate, unset at requires check).
+    // Simulate by forcing a manifest with extra required env.
+    const extraReq = { ...PRO_MANIFEST, requires: ['RUNE_PRO_ROOT', 'SOME_OTHER_VAR'] };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(extraReq, null, 2));
+    const result = await listDetectedTiers(tmpRoot);
+    assert.strictEqual(result[0].requiresOk, false);
+    assert.deepStrictEqual(result[0].requiresMissing, ['SOME_OTHER_VAR']);
+  });
+});
+
+describe('checkTierCoverage', () => {
+  test('silent when no tiers detected', async () => {
+    delete process.env.RUNE_PRO_ROOT;
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    assert.strictEqual(result.checks.length, 0);
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('silent when tier detected but no platform dirs exist', async () => {
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    assert.strictEqual(result.checks.length, 0);
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('pass when Pro installed on every detected platform', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    await seedTierHooksOn(tmpRoot, 'cursor', 'pro');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.ok(tierCheck, 'should emit a tier-coverage check');
+    assert.strictEqual(tierCheck.status, 'pass');
+    assert.strictEqual(result.warnings.length, 0);
+  });
+
+  test('warns when Pro on Claude but missing on detected Cursor', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    // Cursor platform seeded but NO pro-prefixed files — the gap we want to catch.
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.strictEqual(tierCheck.status, 'warn');
+    assert.strictEqual(result.warnings.length >= 1, true);
+    const msg = result.warnings.join('\n');
+    assert.match(msg, /pro/);
+    assert.match(msg, /cursor/);
+    assert.match(msg, /rune hooks install/);
+  });
+
+  test('warns when tier manifest requires unset env var', async () => {
+    await seedPlatform(tmpRoot, 'claude');
+    await seedTierHooksOn(tmpRoot, 'claude', 'pro');
+    // Rewrite manifest to add a req that is definitely unset.
+    const extraReq = { ...PRO_MANIFEST, requires: ['RUNE_PRO_ROOT', 'DOCTOR_TIER_MISSING_ENV'] };
+    await writeFile(path.join(tierRoot, 'hooks', 'manifest.json'), JSON.stringify(extraReq, null, 2));
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const envWarn = result.warnings.find((w) => w.includes('DOCTOR_TIER_MISSING_ENV'));
+    assert.ok(envWarn, `expected missing-env warning, got: ${result.warnings.join('\n')}`);
+    assert.match(envWarn, /pro/);
+    assert.match(envWarn, /will FAIL at runtime/);
+  });
+
+  test('no false-positive: Pro on Cursor alone (no Claude dir) is not a gap', async () => {
+    await seedPlatform(tmpRoot, 'cursor');
+    await seedTierHooksOn(tmpRoot, 'cursor', 'pro');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    // Installed on every detected platform (just cursor) → pass, not warn.
+    assert.strictEqual(tierCheck.status, 'pass');
+  });
+
+  test('windsurf workflow OR rule file counts as installed', async () => {
+    await seedPlatform(tmpRoot, 'windsurf');
+    const rulesDir = path.join(tmpRoot, '.windsurf/rules');
+    await mkdir(rulesDir, { recursive: true });
+    await writeFile(path.join(rulesDir, 'rune-pro-context-inject-rule.md'), '# rule\n');
+
+    const result = await checkTierCoverage({ projectRoot: tmpRoot });
+    const tierCheck = result.checks.find((c) => c.name === 'Tier coverage');
+    assert.strictEqual(tierCheck.status, 'pass');
+  });
+});

package/compiler/__tests__/openclaw-adapter.test.js

@@ -114,6 +114,32 @@ test('generateManifest defaults version when missing', () => {
   assert.strictEqual(manifest.version, '0.0.0');
 });
 
+test('generateManifest declares artifact convention for OpenClaw skills', () => {
+  const manifest = openclaw.generateManifest(
+    [{ name: 'cook', layer: 'L1', group: 'orchestrator' }],
+    { version: '1.0.0' },
+  );
+  assert.ok(manifest.artifactConvention, 'artifactConvention field exists');
+  assert.ok(Array.isArray(manifest.artifactConvention.outputDirPriority), 'outputDirPriority is array');
+  assert.ok(manifest.artifactConvention.outputDirPriority.length >= 4, 'at least 4 fallback tiers');
+  assert.ok(
+    manifest.artifactConvention.outputDirPriority.some((tier) => tier.includes('OPENCLAW_AGENT_DIR')),
+    'OPENCLAW_AGENT_DIR is a tier',
+  );
+  assert.ok(manifest.artifactConvention.outputContract, 'outputContract documented');
+  assert.strictEqual(manifest.artifactConvention.outputContract.exitCodes[0], 'success');
+  assert.strictEqual(manifest.artifactConvention.outputContract.exitCodes[4], 'timeout with partial results (accept)');
+  assert.strictEqual(manifest.artifactConvention.outputContract.exitCodes[124], 'timeout with zero results (retry or abort)');
+});
+
+test('generateManifest description scales with skill count', () => {
+  const fewSkills = openclaw.generateManifest(
+    [{ name: 'cook', layer: 'L1' }, { name: 'plan', layer: 'L2' }],
+    { version: '1.0.0' },
+  );
+  assert.ok(fewSkills.description.includes('2-skill'), 'description reflects actual skill count');
+});
+
 // --- generateEntryPoint ---
 
 test('generateEntryPoint returns valid TypeScript with register(api)', () => {

package/compiler/adapters/openclaw.js

@@ -7,6 +7,25 @@
  *   .openclaw/rune/skills/*.md           (transformed skill files)
  *
  * Follows the NeuralMemory OpenClaw plugin pattern.
+ *
+ * ARTIFACT CONVENTION (v2.13+):
+ * OpenClaw skills that produce file artifacts (images, reports, data) should
+ * resolve output directory in this fallback order — honored by the Rune script
+ * output contract (see skills/skill-forge Phase 5.25):
+ *
+ *   1. --out-dir <path>                       (explicit caller intent)
+ *   2. <SKILL>_OUT_DIR                        (skill-specific env var)
+ *   3. OPENCLAW_OUTPUT_DIR                    (platform-wide override)
+ *   4. OPENCLAW_AGENT_DIR/artifacts/<skill>   (per-agent scoped default)
+ *   5. OPENCLAW_STATE_DIR/artifacts/<skill>   (state-scoped fallback)
+ *   6. ./.rune/<skill>/                       (project-local default)
+ *
+ * Reference implementations in @rune-pro/media/scripts/:
+ *   - codex_imagen_bridge.mjs (full resolution + 9-tier binary detection)
+ *   - image_optimizer.py (Python equivalent)
+ *
+ * Reference codex-imagen repo (darkamenosa/codex-imagen) documents the
+ * de-facto in-the-wild convention this adapter formalizes.
  */
 
 import { BRANDING_FOOTER } from '../transforms/branding.js';
@@ -67,15 +86,36 @@ export default {
    * @param {object} pluginJson - Rune's .claude-plugin/plugin.json
    * @returns {object} manifest object
    */
-  generateManifest(_skills, pluginJson) {
+  generateManifest(skills, pluginJson) {
     return {
       id: 'rune',
       name: 'Rune',
       kind: 'skills',
-      description:
-        '62-skill mesh for AI coding assistants. Routes all code tasks through specialized skills. 215+ connections, 14 extension packs.',
+      description: `${skills.length}-skill mesh for AI coding assistants. Routes all code tasks through specialized skills. 215+ connections, 14 extension packs.`,
       version: pluginJson.version || '0.0.0',
       skills: ['./skills'],
+      artifactConvention: {
+        outputDirPriority: [
+          '--out-dir <path>',
+          '<SKILL>_OUT_DIR',
+          'OPENCLAW_OUTPUT_DIR',
+          'OPENCLAW_AGENT_DIR/artifacts/<skill>',
+          'OPENCLAW_STATE_DIR/artifacts/<skill>',
+          './.rune/<skill>/',
+        ],
+        outputContract: {
+          stdout: 'one artifact path per line (default) or JSON (--json mode)',
+          stderr: 'diagnostics + warnings',
+          exitCodes: {
+            0: 'success',
+            1: 'execution failed (retryable)',
+            2: 'usage error (bug)',
+            3: 'data-integrity error (halt)',
+            4: 'timeout with partial results (accept)',
+            124: 'timeout with zero results (retry or abort)',
+          },
+        },
+      },
       configSchema: {
         jsonSchema: {
           type: 'object',

package/compiler/commands/hooks/tiers.js

@@ -255,6 +255,48 @@ export function checkManifestRequires(manifest) {
   return { ok: missing.length === 0, missing };
 }
 
+/**
+ * Enumerate known tiers and return status for each that can be located.
+ * Tiers that can't be found (no env var, no monorepo sibling) are skipped.
+ * Invalid/corrupt manifests are reported with { found: false, error }.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Array<{tier: string, found: boolean, manifestPath: string|null, version?: string, requires: string[], requiresOk: boolean, requiresMissing: string[], entries: number, error?: string}>>}
+ */
+export async function listDetectedTiers(projectRoot) {
+  const out = [];
+  for (const tier of Object.keys(TIER_ENV_VARS)) {
+    const manifestPath = locateTierManifest(tier, projectRoot);
+    if (!manifestPath) continue;
+    try {
+      const manifest = await loadTierManifest(manifestPath);
+      const req = checkManifestRequires(manifest);
+      out.push({
+        tier,
+        found: true,
+        manifestPath,
+        version: manifest.version,
+        requires: [...(manifest.requires || [])],
+        requiresOk: req.ok,
+        requiresMissing: req.missing,
+        entries: manifest.entries.length,
+      });
+    } catch (err) {
+      out.push({
+        tier,
+        found: false,
+        manifestPath,
+        requires: [],
+        requiresOk: false,
+        requiresMissing: [],
+        entries: 0,
+        error: err.message,
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Resolve a tier request (`--tier pro`) into a loaded, validated manifest,
  * or throw with a helpful upgrade/missing-env message.

package/compiler/doctor.js

@@ -8,6 +8,8 @@
 import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { detectPlatforms } from './adapters/hooks/index.js';
+import { listDetectedTiers } from './commands/hooks/tiers.js';
 import { parseOrgConfig, parsePack, parseTemplate } from './parser.js';
 
 /**
@@ -46,6 +48,9 @@ export async function runDoctor({ outputRoot, adapter, config, runeRoot }) {
   // Check 2: Output directory exists
   if (adapter.name === 'claude') {
     results.checks.push({ name: 'Output directory', status: 'skip', detail: 'Claude Code uses source directly' });
+    const tierCoverage = await checkTierCoverage({ projectRoot: outputRoot });
+    for (const check of tierCoverage.checks) results.checks.push(check);
+    for (const warn of tierCoverage.warnings) results.warnings.push(warn);
     return results;
   }
 
@@ -164,11 +169,137 @@ export async function runDoctor({ outputRoot, adapter, config, runeRoot }) {
     results.warnings.push(...orgErrors);
   }
 
+  // Check 11: Tier hook coverage across detected platforms (advisory)
+  const tierCoverage = await checkTierCoverage({ projectRoot: outputRoot });
+  for (const check of tierCoverage.checks) results.checks.push(check);
+  for (const warn of tierCoverage.warnings) results.warnings.push(warn);
+
   if (results.errors.length > 0) results.healthy = false;
 
   return results;
 }
 
+const PLATFORM_TIER_DIRS = Object.freeze({
+  cursor: '.cursor/rules',
+  windsurf: '.windsurf/workflows',
+  antigravity: '.antigravity/rules',
+});
+
+const PLATFORM_TIER_EXTS = Object.freeze({
+  cursor: '.mdc',
+  windsurf: '.md',
+  antigravity: '.md',
+});
+
+/**
+ * True if the platform's config shows tier hooks installed for `tier`.
+ * Claude: scans `.claude/settings.json` for the `${RUNE_<TIER>_ROOT}` substring
+ *         that the installer emits into every tier command string.
+ * Others: scans the platform's rules/workflow dir for a `rune-<tier>-*` file.
+ *         Windsurf additionally checks `.windsurf/rules` since a tier entry
+ *         writes both a workflow and a rule file.
+ */
+async function platformHasTier(platformId, projectRoot, tier) {
+  if (platformId === 'claude') {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) return false;
+    const raw = await readFile(settingsPath, 'utf-8');
+    return raw.includes(`\${RUNE_${tier.toUpperCase()}_ROOT}`);
+  }
+  const relDir = PLATFORM_TIER_DIRS[platformId];
+  if (!relDir) return false;
+  const ext = PLATFORM_TIER_EXTS[platformId];
+  const prefix = `rune-${tier}-`;
+
+  const scanDir = async (dir) => {
+    if (!existsSync(dir)) return false;
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.some((e) => e.isFile() && e.name.startsWith(prefix) && e.name.endsWith(ext));
+  };
+
+  if (await scanDir(path.join(projectRoot, relDir))) return true;
+  if (platformId === 'windsurf') {
+    if (await scanDir(path.join(projectRoot, '.windsurf/rules'))) return true;
+  }
+  return false;
+}
+
+/**
+ * Advisory tier-coverage check. Silent when no tiers are detected or no
+ * tier hooks are installed anywhere. Warns when:
+ *   1. A tier's hooks are installed on some detected platforms but missing
+ *      on others — suggests re-running `rune hooks install --tier ... --platform all`.
+ *   2. A tier manifest requires env vars that are unset — installed hooks
+ *      will fail at runtime, and `rune hooks install` surfaces this too.
+ *
+ * Advisory only: emits WARN, never blocks the doctor pipeline.
+ *
+ * @param {{projectRoot: string}} options
+ * @returns {Promise<{checks: object[], warnings: string[]}>}
+ */
+export async function checkTierCoverage({ projectRoot }) {
+  const result = { checks: [], warnings: [] };
+  const tiers = await listDetectedTiers(projectRoot);
+  if (tiers.length === 0) return result;
+
+  const detected = detectPlatforms(projectRoot);
+  const gaps = [];
+  let installedSomewhere = false;
+  const coverageByTier = [];
+
+  for (const tierInfo of tiers) {
+    if (!tierInfo.found) {
+      result.warnings.push(
+        `tier ${tierInfo.tier}: manifest at ${tierInfo.manifestPath} failed to load — ${tierInfo.error}`,
+      );
+      continue;
+    }
+
+    const coverage = { tier: tierInfo.tier, installedOn: [], missingOn: [] };
+    for (const id of detected) {
+      const has = await platformHasTier(id, projectRoot, tierInfo.tier);
+      if (has) coverage.installedOn.push(id);
+      else coverage.missingOn.push(id);
+    }
+    if (coverage.installedOn.length > 0) installedSomewhere = true;
+    if (coverage.installedOn.length > 0 && coverage.missingOn.length > 0) {
+      gaps.push(coverage);
+    }
+    coverageByTier.push(coverage);
+
+    if (!tierInfo.requiresOk && coverage.installedOn.length > 0) {
+      result.warnings.push(
+        `tier ${tierInfo.tier}: required env var${tierInfo.requiresMissing.length === 1 ? '' : 's'} unset (${tierInfo.requiresMissing.join(', ')}) — hooks will FAIL at runtime. Fix: export ${tierInfo.requiresMissing[0]}=/path/to/${tierInfo.tier} then re-run your shell.`,
+      );
+    }
+  }
+
+  if (!installedSomewhere) return result;
+
+  if (gaps.length === 0) {
+    result.checks.push({
+      name: 'Tier coverage',
+      status: 'pass',
+      detail: coverageByTier.map((c) => `${c.tier}:${c.installedOn.join('+') || 'none'}`).join(', '),
+    });
+    return result;
+  }
+
+  const detailParts = gaps.map((g) => `${g.tier} missing on ${g.missingOn.join(', ')}`);
+  result.checks.push({
+    name: 'Tier coverage',
+    status: 'warn',
+    detail: detailParts.join('; '),
+  });
+  for (const gap of gaps) {
+    const plural = gap.missingOn.length === 1 ? 'platform' : 'platforms';
+    result.warnings.push(
+      `tier ${gap.tier} installed on ${gap.installedOn.join(', ')} but missing on detected ${plural} ${gap.missingOn.join(', ')}. Re-run: rune hooks install --preset gentle --tier ${gap.tier} --platform all`,
+    );
+  }
+  return result;
+}
+
 /**
  * Check that all cross-references in compiled files point to existing files
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.12.2",
+  "version": "2.13.0",
   "description": "62-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler.",
   "type": "module",
   "bin": {

package/skills/adversary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adversary
-description: Pre-implementation red-team analysis. Challenges plans before code is written — finds edge cases, security holes, scalability bottlenecks, error propagation risks, and integration conflicts. Catches flaws at plan time (10x cheaper than post-implementation).
+description: "Pre-implementation red-team analysis. Use when a plan is high-risk, critical path, or expensive to reverse. Challenges plans before code is written — finds edge cases, security holes, scalability bottlenecks, error propagation risks, and integration conflicts. Catches flaws at plan time (10x cheaper than post-implementation)."
 metadata:
   author: runedev
   version: "0.1.0"

package/skills/autopsy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autopsy
-description: Full codebase health assessment. Analyzes complexity, dependencies, dead code, tech debt, and git hotspots. Produces a health score and rescue plan.
+description: Full codebase health assessment. Use when diagnosing project health or starting a rescue workflow on legacy code. Analyzes complexity, dependencies, dead code, tech debt, and git hotspots. Produces a health score and rescue plan.
 metadata:
   author: runedev
   version: "0.4.0"

package/skills/ba/SKILL.md

@@ -3,7 +3,7 @@ name: ba
 description: Business Analyst agent. Deeply understands user requirements before any planning or coding begins. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume.
 metadata:
   author: runedev
-  version: "0.6.0"
+  version: "0.7.0"
   layer: L2
   model: opus
   group: creation
@@ -87,6 +87,23 @@ Each question must be asked separately, wait for answer before next.
 Exception: if user provides a detailed spec/PRD → extract answers from it, confirm with user.
 </HARD-GATE>
 
+#### Question Discipline (MANDATORY)
+
+Every question the user answers burns attention you don't get back. Protect it.
+
+1. **Max 5 questions total across the whole BA session.** If you find yourself wanting a 6th, the answer is in the first 5 or you're stalling — re-read, don't re-ask.
+2. **Prefer yes/no or multiple-choice over open-ended.** An open-ended question is a last resort when no reasonable option set exists.
+   - BAD: "What auth strategy do you want?"
+   - GOOD: "Auth: **(a)** email+password with JWT, **(b)** OAuth (Google/GitHub), **(c)** magic link, **(d)** I'll decide — pick one."
+3. **Never ask what you can infer.** If the answer is in the repo, the user's message, or the classification from Step 1 — don't ask it.
+   - Wrong stack? → read `package.json`, don't ask.
+   - Wrong audience? → check the `README`, don't ask.
+   - Wrong framework? → check config files, don't ask.
+4. **Cache the answer.** Write each Q→A pair into the Requirements Document verbatim. If the user restarts the BA session on the same feature, reuse the cached answers — never re-ask what was already answered.
+5. **Bundle yes/no questions after Q1 if the user is concise.** A user who replies "y" / "n" / "skip" in 1-2 words tolerates a bundle. A user who replies with paragraphs wants the slow pace — keep one-at-a-time.
+
+Every Q should earn its slot: removing it must leave the Requirements Document materially worse. If it wouldn't, cut the question.
+
 #### Structured Elicitation Frameworks
 
 Choose the framework that fits the requirement type. Use it to STRUCTURE the 5 Questions above, not replace them.
@@ -449,13 +466,16 @@ Saved to `.rune/features/<feature-name>/requirements.md`
 
 ## Constraints
 
-1. MUST ask 5 probing questions before producing requirements — no assumptions
-2. MUST identify hidden requirements — the obvious ones are never the full picture
-3. MUST define out-of-scope explicitly — prevents scope creep
-4. MUST produce testable acceptance criteria — they become test cases
-5. MUST NOT write code or plan implementation — BA produces WHAT, plan produces HOW
-6. MUST ask ONE question at a time — don't overwhelm user with 5 questions at once
-7. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
+1. MUST ask up to 5 probing questions before producing requirements — never more, skip any you can infer from context
+2. MUST prefer yes/no or multiple-choice questions — open-ended only when no reasonable option set exists
+3. MUST NOT ask for information already present in the user's message, the repo, or classification — read/grep first, ask second
+4. MUST cache each Q→A pair in the Requirements Document and reuse on subsequent BA sessions for the same feature
+5. MUST identify hidden requirements — the obvious ones are never the full picture
+6. MUST define out-of-scope explicitly — prevents scope creep
+7. MUST produce testable acceptance criteria — they become test cases
+8. MUST NOT write code or plan implementation — BA produces WHAT, plan produces HOW
+9. MUST ask ONE question at a time by default; bundle yes/no batches only after user shows concise replies
+10. MUST NOT skip BA for non-trivial tasks — "just build it" gets redirected to Question 1
 
 ## Returns
 
@@ -476,6 +496,10 @@ Known failure modes for this skill. Check these before declaring done.
 | Answering own questions instead of asking user | HIGH | Questions require USER input — BA doesn't guess |
 | Producing implementation details (HOW) instead of requirements (WHAT) | HIGH | BA outputs requirements doc → plan outputs implementation |
 | All-at-once question dump (asking 5 questions in one message) | MEDIUM | One question at a time, wait for answer before next |
+| Asking open-ended questions when yes/no or multiple-choice would work | HIGH | Question Discipline rule 2 — option sets are faster to answer and easier to cache |
+| Asking for info already in the repo/message (stack, framework, audience) | HIGH | Question Discipline rule 3 — read `package.json`/README/config first, ask only what you genuinely can't find |
+| Exceeding 5 questions when the user seems "engaged" | MEDIUM | Question Discipline rule 1 — hard cap at 5. A 6th question is a sign of stalling, not thoroughness |
+| Re-asking on session restart when answers were cached | MEDIUM | Question Discipline rule 4 — load `.rune/features/<name>/requirements.md` and reuse cached Q→A pairs |
 | Missing hidden requirements (auth, error handling, edge cases) | HIGH | Step 3 checklist is mandatory scan |
 | Requirements doc too verbose (>500 lines) | MEDIUM | Max 200 lines — concise, actionable, testable |
 | Skipping BA for "simple" features that turn out complex | HIGH | Let cook's complexity detection trigger BA, not user judgment |

package/skills/context-pack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context-pack
-description: "Creates structured handoff briefings between agents. Packages task context, constraints, and progress into a compact packet that subagents can consume without re-reading the full conversation. Prevents the 'lost context' problem in multi-agent delegation."
+description: "Creates structured handoff briefings between agents. Use when delegating complex work to subagents that would otherwise lose context. Packages task context, constraints, and progress into a compact packet that subagents can consume without re-reading the full conversation. Prevents the 'lost context' problem in multi-agent delegation."
 user-invocable: false
 metadata:
   author: runedev

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.4.0"
+  version: "2.5.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -307,9 +307,10 @@ Contract violations are NON-NEGOTIABLE. If `.rune/contract.md` exists and a plan
 2. **Feature workspace** (opt-in) — for non-trivial features (3+ phases), suggest creating `.rune/features/<feature-name>/` with `spec.md`, `plan.md`, `decisions.md`, `status.md`. Skip for simple bug fixes, fast mode.
 3. Create implementation plan: exact files to create/modify, change order, dependencies, active decision constraints
 4. If multiple valid approaches exist → invoke `rune:brainstorm` for trade-off analysis
-5. Present plan to user for approval
-6. If feature workspace was created, write approved plan to `.rune/features/<name>/plan.md`
-7. Mark Phase 2 as `completed`
+5. **Frontend detection** — if task touches `.tsx/.jsx/.vue/.svelte/.css`, component files, or mentions "UI/page/screen/design/layout/landing": invoke `rune:design` BEFORE plan approval. Pass hint `mode: "tweaks-default"` — design proposes ONE opinionated default per `.rune/design-system.md` (Step 2.7), not a 5-option menu. User replies with tweaks ("more professional", "darker") rather than picking from a list. If `.rune/design-system.md` is missing, design creates it first.
+6. Present plan to user for approval
+7. If feature workspace was created, write approved plan to `.rune/features/<name>/plan.md`
+8. Mark Phase 2 as `completed`
 
 **Gate**: User MUST approve the plan before proceeding. Do NOT skip this.
 
@@ -751,7 +752,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
 | 1 | `logic-guardian` | L2 | Conditional: when `.rune/logic-manifest.json` exists — protect complex business logic before any edits |
 | 2 | `plan` | L2 | Create implementation plan |
 | 2 | `brainstorm` | L2 | Trade-off analysis / rescue mode |
-| 2 | `design` | L2 | UI/design phase for frontend features |
+| 2 | `design` | L2 | UI/design phase for frontend features — invoke with `mode: "tweaks-default"` (one opinionated default + accept natural-language tweaks, not a 5-option menu) |
 | 2.5 | `adversary` | L2 | Red-team challenge on approved plan |
 | 3 | `test` | L2 | Write failing tests (RED phase) |
 | 4 | `fix` | L2 | Implement code changes (GREEN phase) |

package/skills/design/SKILL.md

@@ -3,7 +3,7 @@ name: design
 description: Design system reasoning. Maps product domain to style, palette, typography, and platform-specific patterns. Generates .rune/design-system.md as the shared design contract for all UI-generating skills.
 metadata:
   author: runedev
-  version: "0.4.0"
+  version: "0.5.0"
   layer: L2
   model: sonnet
   group: creation
@@ -125,6 +125,84 @@ Accept a single mood keyword (or infer from context if obvious). Map mood to con
 
 **Skip if**: User says "no preference" or "just follow domain defaults" — proceed to Step 3 with domain-only reasoning.
 
+### Step 2.7 — Tweaks, Not Menus (Default Style Pattern)
+
+Picking from a 10-option style menu is how AI UI gets generic. Instead:
+
+1. **Propose ONE opinionated default** based on domain + mood (from Step 2.5). Describe it in 2-3 lines — style, palette direction, typography pairing.
+2. **Ask for tweaks, not choices.** The question is **"Any tweaks to this, or ship it?"** — not "Which of these do you prefer?"
+3. **Accept natural-language adjustments.** Map phrases → design system edits:
+   - "more professional" → heavier type weights, reduce saturation, tighter spacing
+   - "less corporate" → looser weights, brighter accent, more whitespace
+   - "darker" → swap base for darker neutral, raise contrast on elevated surfaces
+   - "more playful" → add subtle animation, soften corners, bolder accent
+   - "more trust" → cooler palette (slate/blue), heavier headers, smaller radius
+4. **If the user asks for a menu**, provide max 3 options — but mark one as the recommended default. Never present a neutral list of 5+ equivalent styles.
+
+Why: Every menu option dilutes commitment. A single confident default gets committed, tweaked, and shipped. A menu gets deliberated, A/B'd, and abandoned. This is the **Tweaks Default** pattern from Anthropic's design system guidance — the AI commits first, humans steer second.
+
+### Step 2.9 — Universal Anti-AI Rules (apply to ALL domains)
+
+These rules apply regardless of domain, mood, or platform. Every generated design system MUST comply.
+
+**Enforcement**: `rune:review` v1.1.0+ reads `.rune/design-system.md` § Scale Minimums and flags violations of all 3 rules below as MEDIUM/HIGH findings. Design defines, review enforces — this is the contract.
+
+#### Rule 1 — Scale Minimums
+
+Below these thresholds, designs read as "AI boilerplate" no matter how good the palette is.
+
+| Element | Minimum | Ideal |
+|---------|---------|-------|
+| Hero/display text | 48px | 56-72px |
+| H1 (page title) | 32px | 36-40px |
+| Body text | 16px (never 14px for primary content) | 16-18px |
+| Secondary/meta text | 14px | 14-15px |
+| Touch targets (mobile) | 44×44px | 48×48px |
+| Touch target gap (mobile) | 8px | 12px |
+| Focus-visible ring | 2px | 3px |
+
+Write these minimums to `.rune/design-system.md` under `## Scale Minimums`. Downstream skills (`cook`, `fix`) treat violations as review findings.
+
+#### Rule 2 — Placeholder Over Bad SVG
+
+If the design calls for an icon, illustration, or graphic that the agent cannot generate at high quality, **ship a boxed placeholder, not a malformed SVG**.
+
+```html
+<!-- GOOD: placeholder -->
+<div class="placeholder" data-icon="dashboard" aria-label="Dashboard icon — design pass needed">
+  [ ICON: dashboard ]
+</div>
+
+<!-- BAD: AI-generated SVG with broken geometry -->
+<svg viewBox="0 0 24 24">
+  <path d="M12 2L2 7l10 5 10-5-10-5z M2 17l10 5 10-5 M2 12l10 5 10-5"/>
+</svg>
+```
+
+- Use **Phosphor Icons** (`@phosphor-icons/react`) or **Huge Icons** as the library default. Never generate custom SVG for standard iconography.
+- For illustrations, reference a placeholder string (e.g., `[ILLUSTRATION: empty-state-dashboard]`) that a human or asset-creator pass fills in later.
+- Malformed SVG is the #1 AI tell. A clean labeled placeholder is honest and professional.
+
+#### Rule 3 — Color Derivation via oklch(), not Manual Shading
+
+When the design needs a darker hover, lighter surface, or tinted state, **derive from the accent via oklch()** — never eyeball a hex value.
+
+```css
+/* GOOD: relative derivation */
+--accent: oklch(65% 0.2 255);
+--accent-hover:  oklch(from var(--accent) calc(l - 0.08) c h);
+--accent-pressed: oklch(from var(--accent) calc(l - 0.15) c h);
+--accent-subtle:  oklch(from var(--accent) calc(l + 0.3) calc(c * 0.4) h);
+
+/* BAD: manual hex shading — breaks hue/chroma consistency */
+--accent: #3b82f6;
+--accent-hover: #2563eb;  /* guessed darker */
+```
+
+Why: HSL shading distorts perceived brightness at different hues. oklch() keeps perceptual lightness consistent, so derived states look intentional rather than "kinda close." Write derived tokens to `.rune/design-system.md` — downstream skills reuse these, not re-derive.
+
+Bonus: use `text-wrap: pretty` on headings to prevent widow words. One line, zero ceremony.
+
 ### Step 3 — Apply Domain Reasoning Rules
 
 Map domain to design system parameters:
@@ -532,6 +610,10 @@ Trading/Fintech — Data-Dense Dark — Web
 4. MUST write `.rune/design-system.md` — ephemeral design decisions evaporate; persistence is the point
 5. MUST NOT overwrite existing design-system.md without user confirmation
 6. MUST include platform-specific overrides when platform is iOS or Android
+7. MUST propose ONE opinionated default and ask for tweaks — never present a neutral 5+ option menu (Step 2.7 Tweaks Default)
+8. MUST enforce Scale Minimums (hero ≥48px, body ≥16px, touch targets ≥44px) in every design system (Step 2.9 Rule 1)
+9. MUST use Phosphor/Huge icons or boxed placeholders — NEVER generate custom SVG for standard iconography (Step 2.9 Rule 2)
+10. MUST derive accent variants via `oklch(from var(--accent) ...)` — NEVER hand-shade hex values (Step 2.9 Rule 3)
 
 ## Mesh Gates (L1/L2 only)
 
@@ -541,6 +623,10 @@ Trading/Fintech — Data-Dense Dark — Web
 | Anti-Pattern Gate | Anti-pattern list derived from domain rules (not generic) | Domain-specific list required |
 | Persistence Gate | .rune/design-system.md written before reporting done | Write file first |
 | Platform Gate | Platform detected before generating tokens | Default to web, note assumption |
+| Tweaks-Default Gate | One opinionated default proposed before asking for tweaks | Do NOT present neutral 5-option menus |
+| Scale-Minimums Gate | Hero ≥48px, body ≥16px, touch ≥44px written into design-system.md | Emit minimums block in output |
+| SVG-Placeholder Gate | No hand-rolled SVG for standard icons — Phosphor/Huge or placeholder | Swap to icon library or `[ ICON: name ]` box |
+| oklch-Derivation Gate | All accent variants derived via `oklch(from ...)` | Rewrite manual hex shades as relative oklch |
 
 ## Returns
 
@@ -568,13 +654,20 @@ Known failure modes for this skill. Check these before declaring done.
 | Visual audit score < 18 shipped without improvement plan | MEDIUM | Step 6.5 flags weak pillars and creates backlog items |
 | iOS target generating solid-background cards | MEDIUM | Platform Gate: iOS 26 Liquid Glass deprecates this pattern |
 | Android target using hardcoded hex colors | MEDIUM | Platform Gate: MaterialTheme.colorScheme is mandatory for dynamic color |
+| Presenting a neutral 5+ option style menu (deliberation death) | HIGH | Step 2.7 Tweaks Default — propose ONE opinionated default, ask for tweaks |
+| Body text at 14px or hero at <40px (AI boilerplate scale) | HIGH | Step 2.9 Rule 1 — enforce Scale Minimums table in every design system |
+| Hand-rolled SVG for dashboard/menu/close icons (malformed geometry) | HIGH | Step 2.9 Rule 2 — Phosphor/Huge Icons or `[ ICON: name ]` placeholder, never custom |
+| Accent variants shaded by eyeball (inconsistent perceived brightness) | MEDIUM | Step 2.9 Rule 3 — `oklch(from var(--accent) calc(l - 0.1) c h)` |
+| Missing `text-wrap: pretty` on headings (widow words) | LOW | One-line CSS — add to base heading styles |
 
 ## Done When
 
 - Design reference loaded (user override or baseline)
 - Domain classified (one of the 10 categories or explicit custom reasoning)
 - Mood mapped to constraints (or explicitly skipped with "domain defaults")
-- Design system generated with: colors (primitive + semantic), typography, spacing, effects, anti-patterns
+- Opinionated default proposed (Step 2.7) — user confirmed or requested tweaks
+- Universal anti-AI rules applied (Step 2.9): Scale Minimums, Placeholder-over-bad-SVG, oklch() color derivation
+- Design system generated with: colors (primitive + semantic, oklch-derived variants), typography, spacing, effects, anti-patterns
 - Platform-specific overrides applied (if iOS/Android target)
 - UI-SPEC.md written with locked layout, hierarchy, and component decisions
 - Accessibility review completed (6 checks: contrast, focus, touch targets, labels, semantic HTML, motion)

package/skills/graft/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: graft
-description: "Clone, port, or convert features from any GitHub repo into your project. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
+description: "Clone, port, or convert features from any GitHub repo into your project. Use when stealing patterns from external repos or porting proven code. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: sonnet
   group: creation
@@ -18,6 +18,17 @@ metadata:
 
 External code intelligence — structured workflow for learning from, adapting, and integrating features from any public repository into your project. Graft is NOT a copy-paste tool. It enforces understanding before adoption through a mandatory challenge gate that evaluates license compatibility, stack fit, scope, quality, and maintenance health before any code touches your codebase.
 
+## Core Rule: The Tree is a Menu, Not the Meal
+
+When you clone a repo you see hundreds of files. **That tree is a menu — options to order from, not a meal to eat.** Grafting the whole tree is how context windows die and foreign patterns leak into your codebase.
+
+- Read the README + the **2-5 files that implement the target feature**. Skip the rest.
+- If you cannot name the specific files you need before reading, you do not know what you want yet — go back to Step 0 and narrow scope.
+- `WebFetch` on raw GitHub URLs beats `git clone` whenever you know the exact files. Use clone only when discovery is genuinely needed.
+- A graft that reads >10 source files is almost always a scoping failure, not a thorough one.
+
+This rule applies to ALL modes. Copy mode is not an excuse to import a directory wholesale — you still select files deliberately.
+
 <HARD-GATE>
 Challenge gate (Step 4) MUST complete before adaptation planning (Step 5).
 No implementation without confronting trade-offs. This applies to ALL modes except compare.
@@ -123,14 +134,16 @@ git sparse-checkout set <target-dir>
 
 For specific files or small repos: use `WebFetch` on raw GitHub URLs instead of cloning.
 
-**Read in this order** (stop when you have enough context):
+**Read in this order** (stop when you have enough context — see Core Rule: the tree is a menu):
 1. README.md — purpose, architecture overview
-2. Target dir's files — the actual code to graft
+2. Target dir's files — the actual code to graft (aim for 2-5 files, hard-cap at 10)
 3. package.json / pyproject.toml / Cargo.toml — dependencies and stack
 4. Tests for target feature — understand expected behavior
 
 **Scope guard**: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?"
 
+**Menu discipline**: Before reading file #6, pause and ask "do I actually need this, or am I eating the menu?" If the answer isn't a concrete reason tied to the target feature, stop reading and move to Step 2.
+
 ### Step 2 — Analyze Source
 
 Understand the target feature's architecture:
@@ -289,6 +302,7 @@ graft.complete:
 5. MUST respect local conventions — grafted code should look native, not foreign
 6. MUST NOT modify the source repository — read-only access only
 7. MUST NOT graft without scoping — always narrow to specific feature/module
+8. MUST treat the source file tree as a menu, not a meal — read the 2-5 files the feature actually needs, not every file you can see
 
 ## Mesh Gates
 
@@ -305,6 +319,7 @@ graft.complete:
 | Grafting GPL code into MIT project | CRITICAL | Challenge gate checks license — blocks incompatible |
 | Blindly copying code without understanding | CRITICAL | HARD-GATE: challenge before implement |
 | Context overflow from large source files | HIGH | Scope guard: >15 files or >2000 LOC triggers warning |
+| Reading the whole repo instead of the feature | HIGH | "Tree is a menu" rule — pause before file #6, justify each read |
 | Grafted code doesn't match local conventions | HIGH | Step 3 scans local patterns, Step 5 plans adaptation |
 | Stale source (abandoned repo) | MEDIUM | Maintenance dimension in challenge gate |
 | Private repo URL fails | MEDIUM | Fallback to WebFetch raw URLs or manual paste |
@@ -320,6 +335,7 @@ SELF-VALIDATION (run before emitting graft.complete):
 - [ ] License compatibility confirmed (or user override documented)
 - [ ] Temp clone directory cleaned up
 - [ ] Grafted code compiles/lints without new errors
+- [ ] Source files read count ≤10 (menu discipline) — if >10, document why in the output
 IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
 ```
 

package/skills/journal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: journal
-description: Persistent state tracking and Architecture Decision Records across sessions. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
+description: Persistent state tracking and Architecture Decision Records across sessions. Use when recording a decision, ADR, or progress that must survive session boundaries. Manages progress state, module health, dependency graphs, and ADRs for any workflow.
 metadata:
   author: runedev
   version: "0.3.0"

package/skills/marketing/SKILL.md

@@ -3,11 +3,12 @@ name: marketing
 description: Create marketing assets and execute launch strategy. Generates landing copy, social banners, SEO meta, blog posts, and video scripts.
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L2
   model: sonnet
   group: delivery
   tools: "Read, Write, Edit, Glob, Grep, WebFetch, WebSearch"
+  emit: media.request
 ---
 
 # marketing

package/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 description: Pre-commit quality gate that catches "almost right" code. Goes beyond linting — checks logic correctness, error handling, regressions, and completeness.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: quality
@@ -224,14 +224,20 @@ For each detected domain, run its checks on the relevant files in the diff:
 
 #### UI/Frontend Domain Checks
 
-When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svelte`/`.vue` files in the diff:
+When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svelte`/`.vue` files in the diff.
+
+**Preamble — load design contract**: If `.rune/design-system.md` exists, read it once. Apply the project's **Scale Minimums** block over the defaults below (e.g., a project declaring `body ≥18px` should flag 16px body text). If the file is absent, use defaults and emit a LOW advisory: "No `.rune/design-system.md` — run `rune design` to lock visual decisions."
 
 | Check | What to Scan | Severity |
 |-------|-------------|----------|
 | **Design token compliance** | Hardcoded colors (`#fff`, `rgb(`, `hsl(`) instead of CSS variables or Tailwind tokens | WARN: "Hardcoded color at {file}:{line} — use design token" |
 | **UI-SPEC drift** | If `.rune/ui-spec.md` exists, compare component decisions (card style, form layout, nav type) against spec | BLOCK: "Component at {file} uses bordered cards but UI-SPEC locks elevated cards" |
 | **Animation accessibility** | Animations/transitions without `prefers-reduced-motion` guard | WARN: "Animation at {file}:{line} missing reduced-motion check" |
-| **Touch target size** | Interactive elements with explicit small sizing (`w-5 h-5`, `p-0.5` on buttons/links) < 44×44px | WARN: "Touch target too small at {file}:{line}" |
+| **Touch target size** | Interactive elements with explicit small sizing (`w-5 h-5`, `p-0.5` on buttons/links) < 44×44px (or project override from design-system.md) | WARN: "Touch target too small at {file}:{line}" |
+| **Scale Minimum — body text** | `text-sm` / `text-xs` / explicit `font-size: 14px` on `<p>` or primary body regions (not meta/secondary) | WARN: "Body text below 16px at {file}:{line} — reads as AI boilerplate" |
+| **Scale Minimum — hero display** | `<h1>` with `text-3xl` or smaller (30px) when the heading is in a hero/landing section | WARN: "Hero heading below 48px at {file}:{line} — insufficient visual hierarchy" |
+| **Hand-rolled SVG for standard icons** | Inline `<svg viewBox=` in JSX when the surrounding comment/class names indicate standard iconography (dashboard, menu, close, chevron, arrow, search, home, user, settings, bell, trash) | WARN: "Hand-rolled SVG at {file}:{line} — use @phosphor-icons/react or huge-icons, or ship boxed placeholder" |
+| **Manual hex accent shading** | CSS/Tailwind config defining 2+ sibling `--accent-hover` / `--accent-pressed` / `--accent-active` with hex literals (no `oklch(from ...)` or design-token chain) | WARN: "Manual hex shade at {file}:{line} — derive via oklch(from var(--accent) calc(l - 0.08) c h)" |
 | **Missing states** | Components fetching data without loading/error/empty states | WARN: "Async component at {file} missing [loading|error|empty] state" |
 | **Icon accessibility** | Decorative icons without `aria-hidden="true"`, functional icons without `aria-label` | WARN: "Icon at {file}:{line} missing aria attribute" |
 | **Inline styles** | `style={{` or `style=` attribute usage instead of classes/tokens | WARN: "Inline style at {file}:{line} — use CSS class or Tailwind" |
@@ -240,6 +246,10 @@ When UI/Frontend hook is triggered, run these checks on all `.tsx`/`.jsx`/`.svel
 
 **Skip if**: Diff contains only test files, config files, or non-UI code (detected by absence of JSX/template syntax).
 
+**Exception for Scale Minimums**: Secondary/meta text (`<time>`, `<small>`, form hints, table captions) is allowed at 14px. The check only fires on primary body regions — paragraphs inside `<main>`, `<article>`, card body, marketing hero/features. Use common sense or an explicit `data-scale="meta"` attribute to opt out.
+
+**Exception for hand-rolled SVG**: Project logos, data visualizations (charts/graphs via d3/recharts/visx), and human-designed illustrations are never flagged. The check fires only when class/comment context names a standard icon.
+
 #### Pack Integration
 
 When a domain pack is installed (e.g., `@rune-pro/finance`, `@rune-pro/legal`), preflight checks the pack's **Hard-Stop Thresholds** table and applies matching rules to staged files. This means:

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: Code quality review — patterns, security, performance, correctness. Finds bugs, suggests improvements, triggers fix for issues found. Escalates to opus for security-critical code.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.1.0"
   layer: L2
   model: sonnet
   group: development
@@ -381,6 +381,9 @@ Apply **only** when `.tsx`, `.jsx`, `.svelte`, `.vue`, or `.html` files are in t
 
 These are the **"AI UI signature"** — patterns that make AI-generated frontends visually identifiable as non-human-designed. Flag each as MEDIUM severity.
 
+**Preamble — load design contract first:**
+If `.rune/design-system.md` exists, read it first. Pull the project's **Scale Minimums** block (if authored by `rune:design` v0.5.0+) and apply those thresholds instead of the defaults below. Missing design-system.md → use defaults and add a LOW finding: "Project has no design-system.md — run `rune design` to lock visual decisions." Never enforce stale defaults against a project that has already declared stricter/looser minimums.
+
 **AI_ANTIPATTERN — Purple/indigo default accent with no domain justification:**
 ```tsx
 // BAD: LLM default color bias — signals "AI-generated" to experienced designers
@@ -415,6 +418,55 @@ className="bg-indigo-600 text-white"  // every button/CTA is indigo
 <span className="font-mono text-2xl font-bold">${price}</span>
 ```
 
+**AI_ANTIPATTERN — Scale Minimum violations (AI boilerplate tell):**
+```tsx
+// BAD: body text at 14px (AI default) — primary content must be ≥16px
+<p className="text-sm">Welcome to the dashboard.</p>
+
+// BAD: hero/display text below 40px — reads as "section heading", not "hero"
+<h1 className="text-3xl font-bold">Ship Faster</h1>  // 30px
+
+// BAD: touch target below 44×44px on mobile
+<button className="w-8 h-8"><XIcon /></button>  // 32px — WCAG 2.5.8 failure
+
+// GOOD: hero ≥48px, body ≥16px, touch ≥44×44px
+<h1 className="text-5xl md:text-6xl font-bold">Ship Faster</h1>   // 48-60px
+<p className="text-base">Welcome to the dashboard.</p>             // 16px
+<button className="w-11 h-11"><XIcon /></button>                   // 44px
+```
+Pull project-specific overrides from `.rune/design-system.md` § Scale Minimums.
+
+**AI_ANTIPATTERN — Hand-rolled SVG for standard iconography:**
+```tsx
+// BAD: custom <svg> for dashboard/menu/close/chevron — AI geometry almost always malformed
+<svg viewBox="0 0 24 24"><path d="M3 3h18v18H3z M3 9h18 M9 3v18"/></svg>
+
+// GOOD: Phosphor Icons (preferred) or Huge Icons
+import { House, List, X } from '@phosphor-icons/react';
+<House weight="bold" size={24} />
+
+// GOOD: labeled placeholder when no icon library available yet
+<span className="icon-placeholder" aria-label="Dashboard icon — design pass needed">
+  [ ICON: dashboard ]
+</span>
+```
+Exceptions: inline SVG for project-unique logos, data visualizations (charts/graphs), or decorative illustrations generated by a human designer — these are not "standard iconography."
+
+**AI_ANTIPATTERN — Manual hex shading for accent states (oklch() violation):**
+```css
+/* BAD: hand-darkened hex — breaks perceived lightness consistency */
+--accent: #3b82f6;
+--accent-hover: #2563eb;    /* guessed darker */
+--accent-pressed: #1d4ed8;  /* guessed even darker */
+
+/* GOOD: relative oklch() derivation */
+--accent: oklch(62% 0.19 258);
+--accent-hover:   oklch(from var(--accent) calc(l - 0.08) c h);
+--accent-pressed: oklch(from var(--accent) calc(l - 0.15) c h);
+--accent-subtle:  oklch(from var(--accent) calc(l + 0.3) calc(c * 0.4) h);
+```
+Flag any CSS file defining 2+ hover/pressed/active variants with sibling hex literals. Not a finding if accent uses a design-token library (Radix Colors, Tailwind palette) that already ships perceptually-tuned scales.
+
 **AI_ANTIPATTERN — Missing UI states (only happy path rendered):**
 ```tsx
 // BAD: data rendering without empty/error/loading states

package/skills/safeguard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: safeguard
-description: Build safety nets before refactoring. Creates characterization tests, boundary markers, config freezes, and rollback points.
+description: Build safety nets before refactoring. Use when running surgeon or any risky refactor that needs a rollback point. Creates characterization tests, boundary markers, config freezes, and rollback points.
 metadata:
   author: runedev
   version: "0.2.0"

package/skills/sentinel-env/SKILL.md

@@ -3,7 +3,7 @@ name: sentinel-env
 description: Environment-aware pre-flight check. Validates OS, runtime versions, installed tools, port availability, env vars, and disk space BEFORE coding starts. Prevents "works on my machine" failures. Like sentinel but for the environment, not the code.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L3
   model: haiku
   group: validation
@@ -117,25 +117,36 @@ Detect and verify tools the project depends on:
    - `Grep` for `subprocess.run(`, `child_process.exec(`, `Deno.Command(` → project invokes external CLI
    - `Read` README/docs for "requires X installed" or "depends on X"
 
-   For each detected hard dependency:
-   ```bash
-   # Verify the tool exists on PATH
-   which <tool-name> 2>/dev/null || echo "MISSING: <tool-name>"
-   # If found, check version
-   <tool-name> --version 2>/dev/null
-   ```
+   For each detected hard dependency, apply the **9-tier binary detection** below — checking only `which`/`where` is insufficient and produces the largest category of "works on my machine" false-negatives (user has binary installed but PATH is stale, or installed via a package manager that didn't register it, or installed as a desktop app with a bundled binary).
+
+   **9-Tier Binary Detection** (stop at first hit):
+
+   | Tier | Source | Catches |
+   |------|--------|---------|
+   | 1 | Explicit `--<tool>-bin <path>` flag | CI, automation, manual override |
+   | 2 | Skill-specific env var `<SKILL>_<TOOL>_BIN` | Per-project pinning |
+   | 3 | Tool-family env var `<TOOL>_APP_BIN` | Ecosystem conventions |
+   | 4 | Generic tool env var `<TOOL>_BIN` | Legacy overrides |
+   | 5 | Platform desktop-app bundle (macOS `.app/Contents/Resources`, Windows `%LOCALAPPDATA%\Programs`, Linux `/opt`) | Desktop app users (~40% of population) |
+   | 6 | PATH lookup (`which`/`where.exe`) | Standard shell users |
+   | 7 | Package manager global bin (`npm config get prefix`, `pnpm`, `pipx --list`, `cargo install --root`) | npm-global on Windows (PATH oversight) |
+   | 8 | Platform common directories (`~/.local/bin`, `~/.npm-global/bin`, Homebrew, `%APPDATA%\npm`, `%LOCALAPPDATA%\Microsoft\WindowsApps`, `%ProgramFiles%\nodejs`) | Manual installers |
+   | 9 | Platform release archive names (e.g., `codex-x86_64-unknown-linux-musl`, `<tool>-aarch64-apple-darwin`) | Release-tarball downloaders |
 
    **Verdict:**
-   - Tool found on PATH → PASS (log version)
-   - Tool NOT found → **BLOCK** with clear install instructions per OS:
+   - Tool found via any tier → PASS (log which tier + version)
+   - Tool NOT found → **BLOCK** with per-OS install guidance:
      ```
-     [ENV-XXX] Required tool '<tool>' not found on PATH
+     [ENV-XXX] Required tool '<tool>' not found (9-tier lookup exhausted)
        → Debian/Ubuntu: sudo apt install <tool>
-       → macOS: brew install <tool>
+       → macOS: brew install <tool> (or desktop app: <URL>)
        → Windows: winget install <tool> (or choco install <tool>)
-       → Manual: <download URL if known>
+       → Any platform: npm install -g <package> (if Node tool)
+       → Manual: <download URL>
+       → Pin explicitly: export <TOOL>_BIN=/path/to/binary
      ```
    - This prevents the entire class of "it worked in CI but not locally" failures where `subprocess.run()` silently fails
+   - Reference implementation: `scripts/codex_imagen_bridge.mjs` in `@rune-pro/media` ports this pattern
 
 ### Step 4: Port Availability Check
 

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "1.8.0"
   layer: L2
   model: opus
   group: creation
@@ -277,6 +277,113 @@ Research (Meincke et al., 2025, 28,000 conversations) shows 33% → 72% complian
 
 **Ethical test**: Would this serve the user's genuine interests if they fully understood the technique?
 
+### Phase 5.25 — SCRIPT CONTRACT (skills with helper scripts only)
+
+If the skill bundles executable scripts in its `scripts/` directory, those scripts MUST follow the Rune script output contract. This is a testable contract — orchestrators (cook, team, marketing) rely on it for piping and retry logic.
+
+#### The Three-Mode Contract
+
+Every helper script supports three output modes:
+
+| Mode | Stdout | Stderr | File Artifacts |
+|------|--------|--------|----------------|
+| default | One artifact path per line | Diagnostics + warnings | Artifacts in declared out-dir |
+| `--json` | Structured JSON summary | Diagnostics (unchanged) | Artifacts (unchanged) |
+| `--debug` | Default stdout (paths) | Verbose trace + diagnostics | Default + JSONL redacted trace at `<out-dir>/<slug>.jsonl` |
+
+**Why**: default-mode stdout-as-paths is the Unix way. Downstream skills pipe directly without log-parsing. `--json` is opt-in for callers that need metadata.
+
+#### Required Flags
+
+Every helper script MUST accept at least these flags:
+
+```
+--help              Print usage + exit 0
+--version           Print version + exit 0
+--json              Structured JSON on stdout
+--debug             Write JSONL redacted trace
+--dry-run           Report plan, make no changes, exit 0
+--smoke             Pre-flight check (validate deps, exit 0 if healthy)
+--out-dir <path>    Override default artifact directory
+```
+
+And SHOULD accept when applicable:
+```
+--prompt-file <path>  Read long text input from file (avoids shell-quoting hell on Windows)
+--confirm             Skip confirmation gate for expensive/destructive ops
+--timeout-ms <n>      Operation timeout (with semantic exit codes below)
+```
+
+#### Semantic Exit Codes
+
+Adopt the standard Rune exit-code vocabulary:
+
+| Code | Meaning | Orchestrator Response |
+|------|---------|-----------------------|
+| `0` | Success | Accept + chain to next |
+| `1` | Execution failed (retryable) | Log + retry with alternate config |
+| `2` | Usage error (bug) | Abort — don't retry |
+| `3` | Data-integrity error | Halt — don't retry |
+| `4` | Timeout with partial results | **Accept partial + continue** |
+| `124` | Timeout with zero results | Retry with longer timeout or alternate provider |
+
+Codes `5-63` are skill-specific. Document every code used in `references/<skill>/exit-codes.md`.
+
+**Why `4` vs `124` matters**: Standard Unix collapses "timeout-with-2-of-3-images" and "timeout-with-0-images" into `124`. They are fundamentally different outcomes. Split them.
+
+#### Default Artifact Directory Resolution
+
+Resolve `--out-dir` in this fallback order:
+
+1. `--out-dir <path>` explicit flag
+2. `<SKILL>_OUT_DIR` env var (skill-specific)
+3. `OPENCLAW_OUTPUT_DIR` (OpenClaw platform convention)
+4. `OPENCLAW_AGENT_DIR/artifacts/<skill>` (OpenClaw default)
+5. `OPENCLAW_STATE_DIR/artifacts/<skill>` (OpenClaw state fallback)
+6. `./.rune/<skill>/` (project-local default)
+
+**Why**: OpenClaw is one of Rune's adapter targets. Scripts that honor this convention work across adapters without modification.
+
+#### Sensitive-Data Redaction
+
+`--debug` trace MUST redact sensitive fields before write:
+- Regex: `/authorization|bearer|token|api[_-]?key|secret|cookie|session[_-]?id|chatgpt[_-]?account/i` (key names)
+- Any value exceeding 500 chars truncates to `<first-500>...`
+- Never log env var VALUES — only presence check
+
+#### Contract Test
+
+Before shipping a helper script, verify:
+
+```bash
+# Contract smoke test:
+node scripts/<script>.mjs --help          # exit 0
+node scripts/<script>.mjs --version       # exit 0, prints version only
+node scripts/<script>.mjs --smoke         # exit 0 or 1, human-readable stderr
+node scripts/<script>.mjs --dry-run ...   # exit 0, no side effects
+node scripts/<script>.mjs ... --json      # stdout is parseable JSON
+node scripts/<script>.mjs ... | head -1   # stdout default mode = path
+```
+
+<HARD-GATE>
+Scripts that don't honor the contract cannot be shipped.
+Specifically:
+- Mixing paths and progress on stdout = BLOCK
+- Silent failure (no install guidance on miss) = BLOCK
+- Logging credentials in trace = CRITICAL-BLOCK
+- Binary exit code (0/1 only) when timeout semantics apply = BLOCK
+</HARD-GATE>
+
+**Reference implementations**:
+- `@rune-pro/media/scripts/codex_imagen_bridge.mjs` — full 9-tier binary detection + contract
+- `@rune-pro/media/scripts/provider_probe.mjs` — `--smoke` convention exemplar
+- `@rune-pro/media/scripts/image_optimizer.py` — Python contract implementation
+
+**Reference docs**:
+- `references/image-generator/script-contract.md` (pack-level contract)
+- `references/image-generator/exit-codes.md` (exit-code vocabulary)
+- `references/image-generator/binary-detection.md` (9-tier lookup)
+
 ### Phase 5.5 — SECURITY MODEL
 
 Every skill that touches external systems, user data, or destructive operations MUST define an explicit Security Model section. This is a contract — not aspirational, but testable.

package/skills/surgeon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: surgeon
-description: Incremental refactorer. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract.
+description: Incremental refactorer. Use within a rescue workflow after safeguard has set up safety nets. Refactors ONE module per session using proven patterns — Strangler Fig, Branch by Abstraction, Expand-Migrate-Contract.
 metadata:
   author: runedev
   version: "0.2.0"