@rune-kit/rune 2.12.3 → 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__/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.12.3",
+  "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/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/graft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.2.0"

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/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"