@rune-kit/rune 2.3.3 → 2.4.0

package/README.md

@@ -32,7 +32,57 @@ Mesh:      A ↔ B ↔ C             (B fails = A reaches C via D→E)
            D ↔ E ↔ F
 ```
 
-## What's New (v2.3.3)
+## Benchmark: With Rune vs Without Rune
+
+We ran 10 standardized coding tasks on Claude Code — once **without** Rune (vanilla), once **with** Rune — and measured tokens, cost, duration, and correctness.
+
+### Headline Results
+
+```
+                Without Rune    With Rune     Delta
+Avg Tokens:     541,400         454,491       ↓ 16%
+Avg Cost:       $0.69           $0.65         ↓ 6%
+Avg Duration:   2.3 min         2.1 min       ↓ 9%
+Avg Tool Calls: 14              13            ↓ 7%
+Correctness:    9/10            9/10          =
+```
+
+### Where Rune Shines: Complex Tasks
+
+| Task | Difficulty | Tokens | Cost | Duration | Tools |
+|------|-----------|--------|------|----------|-------|
+| Refactor 450-line component | Medium | **-62%** | **-17%** | **-32%** | **-27%** |
+| Full feature (auth + API + tests) | Complex | **-36%** | **-29%** | **-31%** | **-27%** |
+| Add Zod validation | Easy | -9% | **-28%** | **-32%** | 0% |
+| Dark mode across 6 components | Hard | ~0% | +10% | -7% | -6% |
+
+Rune doesn't make Claude smarter — Claude already knows how to code. Rune makes Claude **disciplined**. The more complex the task, the more discipline matters.
+
+> _"Without Rune, Claude writes code that works. With Rune, Claude writes code that lasts."_
+
+<details>
+<summary>Full 10-task breakdown</summary>
+
+| # | Task | Diff | Tokens | Cost | Time | Correct |
+|---|------|------|--------|------|------|---------|
+| 1 | Zod Validation | Easy | -9% | -28% | -32% | ✅ → ✅ |
+| 2 | Fix N+1 Query | Easy | +12% | +25% | +3% | ❌ → ❌ |
+| 3 | Cursor Pagination | Med | +12% | +19% | -9% | ✅ → ✅ |
+| 4 | Security Review | Med | +13% | +32% | +3% | ✅ → ✅ |
+| 5 | Rate Limiting | Med | +12% | +5% | +5% | ✅ → ✅ |
+| 6 | Refactor Component | Med | **-62%** | **-17%** | **-32%** | ✅ → ✅ |
+| 7 | Dark Mode (6 files) | Hard | ~0% | +10% | -7% | ✅ → ✅ |
+| 8 | DB Migration | Hard | +52% | +11% | +49% | ✅ → ✅ |
+| 9 | Memory Leak Debug | Hard | +13% | +28% | -2% | ✅ → ✅ |
+| 10 | Full Auth System | Complex | **-36%** | **-29%** | **-31%** | ✅ → ✅ |
+
+_Methodology: Claude Code CLI headless mode (`claude -p --output-format json`), 10 tasks with fixture code, pattern-based correctness evaluation. Source: [`Benchmark/`](Benchmark/)_
+
+</details>
+
+---
+
+## What's New (v2.4.0)
 
 - **UI/UX Pro Max Integration** — 161 palettes, 84 styles, 73 font pairings, 161 reasoning rules from [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT, 42.8k★) meshed into `design` skill + `@rune/ui` pack
 - **11 Core Skill Enrichments** — deviation rules, repair operators, evidence quality gate, decision classification, debug knowledge base, CSO discipline, YAGNI pushback, formal pause/resume

package/compiler/__tests__/scripts-bundling.test.js

@@ -0,0 +1,284 @@
+/**
+ * Scripts Bundling Tests
+ *
+ * Tests the scripts/ directory copy pipeline:
+ * - copyScriptsDir helper
+ * - scriptsDir adapter method
+ * - {scripts_dir} placeholder resolution
+ * - End-to-end buildAll with scripts
+ */
+
+import assert from 'node:assert';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, test } from 'node:test';
+import { getAdapter } from '../adapters/index.js';
+import { buildAll } from '../emitter.js';
+import { resolveScriptsPath } from '../transforms/scripts-path.js';
+
+// --- resolveScriptsPath transform ---
+
+describe('resolveScriptsPath', () => {
+  test('replaces {scripts_dir} with resolved path', () => {
+    const body = 'Run: `node {scripts_dir}/build-deck.js`';
+    const result = resolveScriptsPath(body, '.cursor/rules/rune-slides-scripts');
+    assert.strictEqual(result, 'Run: `node .cursor/rules/rune-slides-scripts/build-deck.js`');
+  });
+
+  test('replaces multiple occurrences', () => {
+    const body = '{scripts_dir}/a.js and {scripts_dir}/b.js';
+    const result = resolveScriptsPath(body, 'scripts');
+    assert.strictEqual(result, 'scripts/a.js and scripts/b.js');
+  });
+
+  test('returns body unchanged when no placeholder', () => {
+    const body = 'No placeholders here';
+    const result = resolveScriptsPath(body, 'some/path');
+    assert.strictEqual(result, body);
+  });
+
+  test('returns body unchanged when scriptsPath is null', () => {
+    const body = 'Has {scripts_dir} but no path';
+    const result = resolveScriptsPath(body, null);
+    assert.strictEqual(result, body);
+  });
+
+  test('returns body unchanged when body is empty', () => {
+    assert.strictEqual(resolveScriptsPath('', 'path'), '');
+  });
+});
+
+// --- scriptsDir adapter method ---
+
+describe('adapter scriptsDir', () => {
+  test('flat-file adapters return sibling dir pattern', () => {
+    for (const name of ['cursor', 'windsurf', 'antigravity', 'generic', 'openclaw']) {
+      const adapter = getAdapter(name);
+      assert.ok(adapter.scriptsDir, `${name} should have scriptsDir`);
+      assert.strictEqual(adapter.scriptsDir('slides'), 'rune-slides-scripts', `${name} scriptsDir mismatch`);
+    }
+  });
+
+  test('directory-per-skill adapters return nested dir pattern', () => {
+    for (const name of ['codex', 'opencode']) {
+      const adapter = getAdapter(name);
+      assert.ok(adapter.scriptsDir, `${name} should have scriptsDir`);
+      assert.strictEqual(adapter.scriptsDir('slides'), 'rune-slides/scripts', `${name} scriptsDir mismatch`);
+    }
+  });
+
+  test('claude adapter has no scriptsDir (passthrough)', () => {
+    const adapter = getAdapter('claude');
+    assert.ok(!adapter.scriptsDir, 'claude should not have scriptsDir');
+  });
+});
+
+// --- Integration: buildAll with scripts ---
+
+describe('buildAll with scripts', () => {
+  async function createTempSkillTree() {
+    const tmp = path.join(tmpdir(), `rune-scripts-test-${Date.now()}`);
+    const skillsDir = path.join(tmp, 'skills');
+    const slideSkillDir = path.join(skillsDir, 'test-slide');
+    const scriptsDir = path.join(slideSkillDir, 'scripts');
+    const plainSkillDir = path.join(skillsDir, 'test-plain');
+
+    await mkdir(scriptsDir, { recursive: true });
+    await mkdir(plainSkillDir, { recursive: true });
+
+    // Skill with scripts/
+    await writeFile(
+      path.join(slideSkillDir, 'SKILL.md'),
+      [
+        '---',
+        'name: test-slide',
+        'description: "Test slide skill"',
+        'layer: L3',
+        'group: utility',
+        'connections: []',
+        'tags: [test]',
+        '---',
+        '',
+        '# test-slide',
+        '',
+        'Run: `node {scripts_dir}/build-deck.js --input slides.json`',
+        '',
+        'Also: `{scripts_dir}/helper.py`',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    await writeFile(path.join(scriptsDir, 'build-deck.js'), '// build deck script\nconsole.log("hello");\n', 'utf-8');
+    await writeFile(path.join(scriptsDir, 'helper.py'), '# helper\nprint("hi")\n', 'utf-8');
+
+    // Skill without scripts/
+    await writeFile(
+      path.join(plainSkillDir, 'SKILL.md'),
+      [
+        '---',
+        'name: test-plain',
+        'description: "Test plain skill"',
+        'layer: L3',
+        'group: utility',
+        'connections: []',
+        'tags: [test]',
+        '---',
+        '',
+        '# test-plain',
+        '',
+        'No scripts here.',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    // Minimal extensions dir (empty — no packs needed for test)
+    await mkdir(path.join(tmp, 'extensions'), { recursive: true });
+
+    // Minimal .claude-plugin for openclaw
+    await mkdir(path.join(tmp, '.claude-plugin'), { recursive: true });
+    await writeFile(
+      path.join(tmp, '.claude-plugin', 'plugin.json'),
+      JSON.stringify({ version: '0.0.1' }),
+      'utf-8',
+    );
+
+    return tmp;
+  }
+
+  test('cursor: scripts copied to sibling dir, placeholder resolved', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('cursor');
+      const stats = await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      // Scripts copied
+      assert.ok(stats.scriptsCopied >= 2, `expected 2+ scripts copied, got ${stats.scriptsCopied}`);
+
+      // Scripts dir exists with files
+      const scriptsOut = path.join(outputRoot, adapter.outputDir, 'rune-test-slide-scripts');
+      assert.ok(existsSync(path.join(scriptsOut, 'build-deck.js')), 'build-deck.js missing in output');
+      assert.ok(existsSync(path.join(scriptsOut, 'helper.py')), 'helper.py missing in output');
+
+      // Placeholder resolved in .mdc output
+      const mdc = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-test-slide.mdc'), 'utf-8');
+      assert.ok(!mdc.includes('{scripts_dir}'), 'placeholder should be resolved');
+      assert.ok(mdc.includes('.cursor/rules/rune-test-slide-scripts/build-deck.js'), 'resolved path missing');
+
+      // Plain skill: no scripts dir created
+      assert.ok(!existsSync(path.join(outputRoot, adapter.outputDir, 'rune-test-plain-scripts')), 'plain skill should not have scripts dir');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('codex: scripts inside skill directory', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('codex');
+      const stats = await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      assert.ok(stats.scriptsCopied >= 2);
+
+      // Scripts inside skill dir: .codex/skills/rune-test-slide/scripts/
+      const scriptsOut = path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'scripts');
+      assert.ok(existsSync(path.join(scriptsOut, 'build-deck.js')), 'build-deck.js missing');
+      assert.ok(existsSync(path.join(scriptsOut, 'helper.py')), 'helper.py missing');
+
+      // Placeholder resolved
+      const md = await readFile(
+        path.join(outputRoot, adapter.outputDir, 'rune-test-slide', 'SKILL.md'),
+        'utf-8',
+      );
+      assert.ok(!md.includes('{scripts_dir}'), 'placeholder should be resolved');
+      assert.ok(md.includes('.codex/skills/rune-test-slide/scripts/build-deck.js'), 'resolved path missing');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('skill without scripts: no error, no empty dirs', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('windsurf');
+      const stats = await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      // Should still build both skills
+      assert.strictEqual(stats.skillCount, 2);
+
+      // No scripts dir for plain skill
+      assert.ok(!existsSync(path.join(outputRoot, adapter.outputDir, 'rune-test-plain-scripts')));
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('stats include scriptsCopied count', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('generic');
+      const stats = await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      assert.strictEqual(typeof stats.scriptsCopied, 'number');
+      assert.strictEqual(stats.scriptsCopied, 2);
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('claude adapter: passthrough, no scripts processing', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('claude');
+      const stats = await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      // Claude is passthrough — no build
+      assert.strictEqual(stats.platform, 'claude');
+      assert.strictEqual(stats.skillCount, 0);
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('scripts content copied as-is (byte-for-byte)', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      const outputRoot = path.join(tmp, 'out');
+      const adapter = getAdapter('cursor');
+      await buildAll({ runeRoot: tmp, outputRoot, adapter });
+
+      const original = await readFile(path.join(tmp, 'skills', 'test-slide', 'scripts', 'build-deck.js'), 'utf-8');
+      const copied = await readFile(path.join(outputRoot, adapter.outputDir, 'rune-test-slide-scripts', 'build-deck.js'), 'utf-8');
+      assert.strictEqual(copied, original, 'script content should be identical');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('multiple adapters resolve different paths', async () => {
+    const tmp = await createTempSkillTree();
+    try {
+      // Cursor (flat)
+      const cursorOut = path.join(tmp, 'out-cursor');
+      const cursorAdapter = getAdapter('cursor');
+      await buildAll({ runeRoot: tmp, outputRoot: cursorOut, adapter: cursorAdapter });
+      const cursorMdc = await readFile(path.join(cursorOut, '.cursor/rules/rune-test-slide.mdc'), 'utf-8');
+      assert.ok(cursorMdc.includes('.cursor/rules/rune-test-slide-scripts/'), 'cursor path');
+
+      // Codex (directory)
+      const codexOut = path.join(tmp, 'out-codex');
+      const codexAdapter = getAdapter('codex');
+      await buildAll({ runeRoot: tmp, outputRoot: codexOut, adapter: codexAdapter });
+      const codexMd = await readFile(path.join(codexOut, '.codex/skills/rune-test-slide/SKILL.md'), 'utf-8');
+      assert.ok(codexMd.includes('.codex/skills/rune-test-slide/scripts/'), 'codex path');
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/compiler/__tests__/tier-override.test.js

@@ -155,4 +155,45 @@ describe('discoverTieredPacks', () => {
       rmSync(root, { recursive: true, force: true });
     }
   });
+
+  test('pro override tracks free pack in overrides array', async () => {
+    const { freePacks, proPacks, root } = createTierFixture();
+    try {
+      const packs = await discoverTieredPacks(freePacks, { pro: proPacks });
+      const saasPack = packs.find((p) => p.dirName === 'pro-saas');
+      assert.ok(saasPack, 'pro-saas should exist');
+      assert.strictEqual(saasPack.overrides.length, 1);
+      assert.strictEqual(saasPack.overrides[0].tier, 'free');
+      assert.strictEqual(saasPack.overrides[0].dirName, 'saas');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('business override tracks both pro and free in overrides array', async () => {
+    const { freePacks, proPacks, bizPacks, root } = createTierFixture();
+    try {
+      const packs = await discoverTieredPacks(freePacks, { pro: proPacks, business: bizPacks });
+      const saasPack = packs.find((p) => p.dirName === 'business-saas');
+      assert.ok(saasPack, 'business-saas should exist');
+      // Should have both free and pro overrides (free was overridden by pro, then pro by business)
+      assert.strictEqual(saasPack.overrides.length, 2);
+      const overrideTiers = saasPack.overrides.map((o) => o.tier).sort();
+      assert.deepStrictEqual(overrideTiers, ['free', 'pro']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('free-only packs have empty overrides array', async () => {
+    const { freePacks, proPacks, root } = createTierFixture();
+    try {
+      const packs = await discoverTieredPacks(freePacks, { pro: proPacks });
+      const tradingPack = packs.find((p) => p.dirName === 'trading');
+      assert.ok(tradingPack, 'trading should exist');
+      assert.deepStrictEqual(tradingPack.overrides, []);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });

package/compiler/adapters/antigravity.js

@@ -47,6 +47,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/codex.js

@@ -58,6 +58,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}/scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/cursor.js

@@ -55,6 +55,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/generic.js

@@ -48,6 +48,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/openclaw.js

@@ -52,6 +52,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/opencode.js

@@ -67,6 +67,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}/scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/adapters/windsurf.js

@@ -48,6 +48,10 @@ export default {
     return text;
   },
 
+  scriptsDir(skillName) {
+    return `rune-${skillName}-scripts`;
+  },
+
   postProcess(content) {
     return content.replace(/^context: fork\n/gm, '').replace(/^agent: general-purpose\n/gm, '');
   },

package/compiler/emitter.js

@@ -6,10 +6,11 @@
  */
 
 import { existsSync } from 'node:fs';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { extractCrossRefs, extractToolRefs, parsePack, parseSkill } from './parser.js';
 import { transformSkill } from './transformer.js';
+import { resolveScriptsPath } from './transforms/scripts-path.js';
 
 /**
  * Discover all SKILL.md files in the skills directory
@@ -59,6 +60,29 @@ async function discoverPacks(extensionsDir, enabledPacks = null) {
   return paths.sort();
 }
 
+/**
+ * Copy scripts directory from skill source to output.
+ *
+ * @param {string} sourceScriptsDir - e.g. skills/slides/scripts/
+ * @param {string} outputScriptsDir - e.g. .cursor/rules/rune-slides-scripts/
+ * @returns {Promise<string[]>} list of copied file paths
+ */
+async function copyScriptsDir(sourceScriptsDir, outputScriptsDir) {
+  if (!existsSync(sourceScriptsDir)) return [];
+
+  const entries = await readdir(sourceScriptsDir, { recursive: true, withFileTypes: true });
+  const files = entries.filter((e) => e.isFile());
+  if (entries.length === 0) return [];
+
+  await cp(sourceScriptsDir, outputScriptsDir, { recursive: true });
+
+  // Return relative paths within the scripts dir (same structure as source after recursive cp)
+  return files.map((e) => {
+    const parent = e.parentPath || e.path;
+    return path.relative(sourceScriptsDir, path.join(parent, e.name));
+  });
+}
+
 /**
  * Tier priority: higher number = higher priority (wins override)
  */
@@ -104,9 +128,12 @@ export async function discoverTieredPacks(freeExtDir, tierSources = {}, enabledP
       const priority = TIER_PRIORITY[tier] ?? 0;
       const existing = packMap.get(normalized);
 
-      // Higher priority tier wins
+      // Higher priority tier wins — track overridden lower-tier entries for skill-level merging
       if (!existing || priority > existing.priority) {
-        packMap.set(normalized, { path: packFile, tier, priority, dirName: entry.name });
+        const overrides = existing
+          ? [...(existing.overrides || []), { path: existing.path, tier: existing.tier, dirName: existing.dirName }]
+          : [];
+        packMap.set(normalized, { path: packFile, tier, priority, dirName: entry.name, overrides });
       }
     }
   }
@@ -187,6 +214,7 @@ export async function buildAll({
     packCount: 0,
     crossRefsResolved: 0,
     toolRefsResolved: 0,
+    scriptsCopied: 0,
     files: [],
     skipped: [],
     errors: [],
@@ -205,7 +233,25 @@ export async function buildAll({
         continue;
       }
 
-      const { header, body, footer } = transformSkill(parsed, adapter);
+      const { header, body: rawBody, footer } = transformSkill(parsed, adapter);
+
+      // Resolve {scripts_dir} placeholder if adapter supports scripts
+      const skillSourceDir = path.dirname(skillPath);
+      const scriptsSource = path.join(skillSourceDir, 'scripts');
+      const hasScripts = existsSync(scriptsSource) && adapter.scriptsDir;
+      const scriptsRelPath = hasScripts
+        ? path.join(adapter.outputDir, adapter.scriptsDir(parsed.name)).replaceAll('\\', '/')
+        : null;
+      const body = hasScripts ? resolveScriptsPath(rawBody, scriptsRelPath) : rawBody;
+
+      // Warn if {scripts_dir} placeholder exists but no scripts/ folder to resolve it
+      if (!hasScripts && rawBody.includes('{scripts_dir}')) {
+        stats.errors.push({
+          file: skillPath,
+          error: `{scripts_dir} placeholder found but no scripts/ directory exists for skill "${parsed.name}"`,
+        });
+      }
+
       const output = [header, body, footer].filter(Boolean).join('\n');
 
       let outputPath;
@@ -226,6 +272,13 @@ export async function buildAll({
 
       await writeFile(outputPath, output, 'utf-8');
 
+      // Copy scripts/ directory if present
+      if (hasScripts) {
+        const scriptsOutput = path.join(outputDir, adapter.scriptsDir(parsed.name));
+        const copied = await copyScriptsDir(scriptsSource, scriptsOutput);
+        stats.scriptsCopied += copied.length;
+      }
+
       stats.skillCount++;
       stats.crossRefsResolved += parsed.crossRefs.length;
       stats.toolRefsResolved += parsed.toolRefs.length;
@@ -249,11 +302,38 @@ export async function buildAll({
         stats.tierOverrides.push({ pack: packName, tier: packEntry.tier });
       }
 
+      // Tier Override: merge skill manifests from lower tiers
+      // If a Pro/Business pack overrides a Free pack, inherit skills the higher tier doesn't provide
+      if (packEntry.overrides?.length > 0 && parsed.isSplit && parsed.skillManifest.length > 0) {
+        const winnerSkillNames = new Set(parsed.skillManifest.map((s) => s.name));
+        for (const lower of packEntry.overrides) {
+          try {
+            const lowerContent = await readFile(lower.path, 'utf-8');
+            const lowerParsed = parsePack(lowerContent, lower.path);
+            if (lowerParsed.isSplit) {
+              const lowerPackDir = path.dirname(lower.path);
+              for (const lowerSkill of lowerParsed.skillManifest) {
+                if (!winnerSkillNames.has(lowerSkill.name)) {
+                  // Inherit skill from lower tier — track source directory for file resolution
+                  parsed.skillManifest.push({ ...lowerSkill, _sourceDir: lowerPackDir });
+                  winnerSkillNames.add(lowerSkill.name);
+                  stats.tierOverrides.push({ pack: packName, skill: lowerSkill.name, inherited: lower.tier });
+                }
+              }
+            }
+          } catch {
+            // Lower-tier pack unreadable — skip gracefully
+          }
+        }
+      }
+
       // For split packs, load individual skill files and concatenate into body
       if (parsed.isSplit && parsed.skillManifest.length > 0) {
         const skillBodies = [];
         for (const skill of parsed.skillManifest) {
-          const skillPath = path.join(packDir, skill.file);
+          // Resolve skill file path — use _sourceDir for inherited lower-tier skills
+          const sourceDir = skill._sourceDir || packDir;
+          const skillPath = path.join(sourceDir, skill.file);
           if (existsSync(skillPath)) {
             const skillContent = await readFile(skillPath, 'utf-8');
             // Strip frontmatter from skill file — we only need the body

package/compiler/transforms/scripts-path.js

@@ -0,0 +1,18 @@
+/**
+ * Scripts Path Transform
+ *
+ * Replaces {scripts_dir} placeholder in skill body with the
+ * platform-resolved scripts directory path.
+ */
+
+/**
+ * Replace {scripts_dir} placeholder with platform-resolved path.
+ *
+ * @param {string} body - skill body text
+ * @param {string} scriptsPath - resolved path for this platform
+ * @returns {string} body with placeholders resolved
+ */
+export function resolveScriptsPath(body, scriptsPath) {
+  if (!body || !scriptsPath) return body;
+  return body.replaceAll('{scripts_dir}', scriptsPath);
+}

package/extensions/zalo/PACK.md

@@ -3,7 +3,7 @@ name: "@rune/zalo"
 description: Zalo platform integration — Official Account API (OAuth2, messaging, webhooks, MCP server) and personal account automation (zca-js). Dual-track with explicit risk gating.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L4
   price: free
   target: Vietnamese developers building Zalo bots, OA automation, and AI agent integrations
@@ -116,6 +116,25 @@ Called By ← mcp-builder (L2): when building Zalo-specific MCP server
 | Webhook signature verification skipped in development, then deployed to production unsigned | HIGH | Always validate `X-Zalo-Signature` header from first commit — skip in dev only via explicit `SKIP_WEBHOOK_VERIFY=true` env flag |
 | Rate limit hit causes account ban with no warning (HTTP 429 mishandled as transient error) | HIGH | Implement token bucket per endpoint; treat sustained 429s as ban-risk signal and back off for 60+ seconds |
 
+## References
+
+| Reference | Trigger |
+|-----------|---------|
+| [VietQR & Banking](references/vietqr-banking.md) | Payment, bank transfer, QR code patterns detected |
+| [Conversation Management](references/conversation-management.md) | Polls, auto-reply, mute/archive, advanced messaging |
+| [MCP Production](references/mcp-production.md) | MCP server deployment, cursor pagination, pm2 setup |
+| [Multi-Account & Proxy](references/multi-account-proxy.md) | Multi-account setup, proxy configuration, VPS deployment |
+| [Listen Mode](references/listen-mode.md) | WebSocket listener, real-time events, webhook forwarding |
+| [Eval Scenarios](references/eval-scenarios.md) | Quality gate — 24 test scenarios (functional + security) |
+
+## Credits
+
+This pack was originally inspired by and incorporates patterns from:
+
+- **[zalo-agent-cli](https://github.com/PhucMPham/zalo-agent-cli)** by PhucMPham (MIT) — CLI tool for Zalo automation, 90+ commands, MCP server, VietQR banking integration
+- **[openzalo](https://github.com/darkamenosa/openzalo)** by darkamenosa — OpenClaw channel plugin for Zalo personal accounts via openzca CLI
+- **[zca-js](https://github.com/RFS-ADRENO/zca-js)** — Unofficial Zalo client library (reverse-engineered API)
+
 ## Done When
 
 - OA OAuth2 flow working with auto-refresh