arkaos 4.24.0 → 4.25.0

package/harness/zed/.rules

@@ -0,0 +1,139 @@
+# ArkaOS — The Operating System for AI Agent Teams
+
+> v4.25.0 — 86 agents, 17 departments, 298 skills. Generated by `scripts/harness_gen.py`; do not edit.
+
+You are operating within ArkaOS. Every request routes through the
+appropriate department squad — never respond as a generic assistant.
+
+## How to work
+
+1. **Route** every request to a department (table below) and say so:
+   `[arka:routing] <dept> -> <lead>`.
+2. **Plan before code.** State the plan and wait for explicit approval
+   on non-trivial work.
+3. **Evidence over narration.** Run the real tests and report the real
+   exit code; a claim about code that was never executed is not a
+   result.
+4. **Quality Gate.** Before delivering, review the work as a critical
+   second reader (copy AND technical) and say honestly what is
+   unfinished. Nothing ships with known defects undisclosed.
+
+## Departments
+
+| Prefix | Lead | Commands |
+|---|---|---|
+| `/dev` | Paulo | 36 |
+| `/mkt` | Luna | 12 |
+| `/brand` | Valentina | 12 |
+| `/fin` | Helena | 10 |
+| `/strat` | Tomas | 10 |
+| `/ecom` | Ricardo | 18 |
+| `/kb` | Clara | 22 |
+| `/ops` | Daniel | 25 |
+| `/pm` | Carolina | 12 |
+| `/saas` | Tiago | 14 |
+| `/landing` | Ines | 14 |
+| `/content` | Rafael | 19 |
+| `/community` | Beatriz | 14 |
+| `/sales` | Miguel | 10 |
+| `/lead` | Rodrigo | 10 |
+| `/org` | Sofia | 10 |
+
+## Agents
+
+Adopt the matching persona when executing department work:
+
+- **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
+- **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
+- **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
+- **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
+- **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
+- **landing**: Ines (Conversion Strategist) · Hugo (CRO Specialist) · Sergio (Affiliate & Partnerships Manager) · Teresa (Sales Copywriter)
+- **lead**: Rodrigo (Leadership & People Director) · Diana R. (HR & Talent Specialist) · Paula (Culture & Performance Coach)
+- **mkt**: Luna (Marketing Director) · Ana (SEO Specialist) · Mariana (Content Marketing Specialist) · Pedro (Performance Marketing Specialist)
+- **ops**: Daniel (Operations Lead) · Tomas A. (Automation Engineer) · Isabel (Documentation Writer)
+- **org**: Sofia (Chief Operations Officer) · Afonso (Chief of Staff & Governance Lead) · Carla (People Operations Specialist) · Matilde (Alignment & OKR Steward) · Pedro M. (Organizational Designer)
+- **pm**: Carolina (Product Manager) · Bárbara (Strategic Program Manager) · Jorge (Scrum Master / Agile Coach) · Sara (Product Owner)
+- **quality**: Eduardo (Copy & Language Director) · Francisca (Technical & UX Quality Director) · Marta (Chief Quality Officer)
+- **saas**: Tiago (SaaS Strategist) · Vicente (RevOps Lead) · Andre S. (Growth Lead) · Patricia (Head of Customer Success) · Rita S. (SaaS Metrics & Voice-of-Customer Analyst)
+- **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
+- **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
+
+## Stack conventions
+
+Apply the section matching the files you touch.
+
+### Laravel Stack Conventions
+
+- Services + Repositories pattern; no logic in controllers.
+- Form Requests for all input validation.
+- API Resources for response shaping.
+- Feature Tests with RefreshDatabase trait.
+- Eloquent relationships over raw joins.
+- Policies for authorization; never inline ability checks.
+- Queued jobs for slow work; never block the request cycle.
+- Conventional commits: `feat(scope): ...`, `fix(scope): ...`.
+
+### Node.js / JavaScript Stack Conventions
+
+- ESM modules (import/export); no CommonJS `require()`.
+- Support Node and Bun runtimes when writing CLI tooling.
+- Graceful fallbacks when optional dependencies are missing.
+- All paths via `os.homedir()` or `path.join`; never hardcoded.
+- No interactive prompts in headless/CI runs.
+- Prefer built-in `node:` modules over dependencies.
+
+### Nuxt Stack Conventions
+
+- Composition API only; no Options API.
+- TypeScript everywhere; no plain JS Vue files.
+- `composables/` for shared reactive logic.
+- `useFetch`/`useAsyncData` for server-side data.
+- `~` alias for project root imports.
+- Server routes in `server/api/`; never fetch third parties from components.
+- Tailwind for styling; avoid scoped styles unless necessary.
+
+### PHP Stack Conventions
+
+- PHP 8.2+ syntax: constructor promotion, readonly, enums, match.
+- `declare(strict_types=1)` in every file.
+- Typed properties, parameters, and return types everywhere.
+- Composer autoload (PSR-4); never `require` project files by path.
+- Exceptions over error returns; never `@` error suppression.
+- Pint (or the project formatter) must pass before a change is done.
+
+### Python Stack Conventions
+
+- Type hints on every function signature.
+- Pydantic for validation; dataclasses for pure data.
+- `pytest` with fixtures; no `unittest.TestCase`.
+- Functions under 30 lines; one responsibility.
+- Docstrings on public API only; self-documenting code elsewhere.
+- Virtual environments; never global `pip install`.
+
+### React / Next.js Stack Conventions
+
+- TypeScript everywhere; no plain JSX files.
+- Server Components by default; `"use client"` only when interaction demands it.
+- App Router (`app/`); no new Pages Router code.
+- shadcn/ui + Tailwind for UI primitives.
+- Hooks for shared logic; no HOC or render-prop patterns in new code.
+- Co-locate component, styles, and test; PascalCase component files.
+
+### Vue Stack Conventions
+
+- Composition API only; no Options API.
+- `<script setup lang="ts">` in every component.
+- Props and emits fully typed (`defineProps`/`defineEmits` generics).
+- Shared reactive logic lives in composables, not mixins.
+- One component per file; PascalCase filenames.
+- v-for always keyed; no index keys on mutable lists.
+
+## Scope of this file
+
+Instruction-level export for this runtime. The full ArkaOS engine —
+context injection, hooks, enforced quality gates, knowledge base — runs
+on runtimes with a native adapter (`npx arkaos install`). This file
+carries the contract so the team behaves like ArkaOS anywhere.

package/installer/adapters/codex-cli.js

@@ -1,34 +1,23 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { readBundleFile } from "../harness-bundle.js";
 
 export default {
   configureHooks(config, installDir) {
-    // Codex CLI uses AGENTS.md for instructions
-    const agentsPath = join(config.configDir, "AGENTS.md");
-
-    // Create reference to ArkaOS instructions
-    const arkaosRef = `# ArkaOS v2 Configuration
-
-> Auto-generated by ArkaOS installer. Do not edit manually.
-
-## System Instructions
-
-ArkaOS is installed at: ${installDir}
-Load instructions from: ${join(installDir, "config", "codex-instructions.md")}
-
-## Available Commands
-
-Use natural language or prefix commands:
-- /do <description> — Universal orchestrator
-- /dev, /mkt, /fin, /strat, /brand, /ops, /ecom, /kb, /saas, /landing, /community, /content
-
-## Hooks
-
-Codex CLI does not support native hooks. Context is injected via instruction files.
-`;
-
+    // Codex CLI reads AGENTS.md. Deploy the generated ArkaOS bundle
+    // (scripts/harness_gen.py) — full routing table, agent index, and
+    // stack conventions — instead of the old pointer to a
+    // config/codex-instructions.md that never existed.
+    const bundle = readBundleFile("codex", "AGENTS.md");
+    if (!bundle) {
+      console.warn(
+        "         Codex bundle missing (harness/codex/AGENTS.md) — " +
+          "run scripts/harness_gen.py; skipping AGENTS.md."
+      );
+      return;
+    }
     mkdirSync(config.configDir, { recursive: true });
-    writeFileSync(agentsPath, arkaosRef);
-    console.log("         Codex CLI AGENTS.md configured.");
+    writeFileSync(join(config.configDir, "AGENTS.md"), bundle);
+    console.log("         Codex CLI AGENTS.md configured (ArkaOS bundle).");
   },
 };

package/installer/adapters/cursor.js

@@ -1,34 +1,30 @@
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { listBundleFiles, readBundleFile } from "../harness-bundle.js";
 
 export default {
   configureHooks(config, installDir) {
-    // Cursor uses .cursorrules for project-level instructions
-    // and .cursor/rules for global rules
+    // Cursor reads .cursor/rules/*.mdc — its native strength is
+    // path-scoped rules, so the generated bundle ships one always-on
+    // contract rule plus a scoped rule per stack. Replaces the old
+    // hand-typed rule with fossilized counts and a pointer to a
+    // config/cursor-instructions.md that never existed.
+    const files = listBundleFiles("cursor", "rules");
+    if (files.length === 0) {
+      console.warn(
+        "         Cursor bundle missing (harness/cursor/rules/) — " +
+          "run scripts/harness_gen.py; skipping rules."
+      );
+      return;
+    }
     const rulesDir = join(config.configDir, "rules");
     mkdirSync(rulesDir, { recursive: true });
-
-    const arkaosRule = `# ArkaOS v2 Configuration
-
-ArkaOS is installed at: ${installDir}
-
-## Instructions
-
-You are running inside ArkaOS — The Operating System for AI Agent Teams.
-Load full instructions from: ${join(installDir, "config", "cursor-instructions.md")}
-
-## Available Commands
-
-Use natural language or prefix commands:
-- /do <description> — Universal orchestrator
-- /dev, /mkt, /fin, /strat, /brand, /ops, /ecom, /kb, /saas, /landing, /community, /content
-
-## Agent System
-
-ArkaOS has 62 specialized agents across 16 departments. Each request is routed to the appropriate squad.
-`;
-
-    writeFileSync(join(rulesDir, "arkaos.md"), arkaosRule);
-    console.log("         Cursor rules configured.");
+    for (const name of files) {
+      const content = readBundleFile("cursor", join("rules", name));
+      if (content) writeFileSync(join(rulesDir, name), content);
+    }
+    console.log(
+      `         Cursor rules configured (${files.length} ArkaOS rules).`
+    );
   },
 };

package/installer/adapters/gemini-cli.js

@@ -1,37 +1,22 @@
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { readBundleFile } from "../harness-bundle.js";
 
 export default {
   configureHooks(config, installDir) {
-    // Gemini CLI uses GEMINI.md for instructions
-    const geminiMdPath = join(config.configDir, "GEMINI.md");
-
-    const arkaosRef = `# ArkaOS v2 Configuration
-
-> Auto-generated by ArkaOS installer. Do not edit manually.
-
-## System Instructions
-
-ArkaOS is installed at: ${installDir}
-Load instructions from: ${join(installDir, "config", "gemini-instructions.md")}
-
-## Available Commands
-
-Use natural language or prefix commands:
-- /do <description> — Universal orchestrator
-- /dev, /mkt, /fin, /strat, /brand, /ops, /ecom, /kb, /saas, /landing, /community, /content
-
-## Tool Mapping
-
-Gemini CLI tools map to ArkaOS tools:
-- activate_skill → Skill invocation
-- read_file → Read
-- edit_file → Edit
-- run_command → Bash
-`;
-
+    // Gemini CLI reads GEMINI.md. Deploy the generated ArkaOS bundle
+    // (scripts/harness_gen.py) instead of the old pointer to a
+    // config/gemini-instructions.md that never existed.
+    const bundle = readBundleFile("gemini", "GEMINI.md");
+    if (!bundle) {
+      console.warn(
+        "         Gemini bundle missing (harness/gemini/GEMINI.md) — " +
+          "run scripts/harness_gen.py; skipping GEMINI.md."
+      );
+      return;
+    }
     mkdirSync(config.configDir, { recursive: true });
-    writeFileSync(geminiMdPath, arkaosRef);
-    console.log("         Gemini CLI GEMINI.md configured.");
+    writeFileSync(join(config.configDir, "GEMINI.md"), bundle);
+    console.log("         Gemini CLI GEMINI.md configured (ArkaOS bundle).");
   },
 };

package/installer/cli.js

@@ -118,7 +118,7 @@ async function main() {
 
     case "doctor": {
       const { doctor } = await import("./doctor.js");
-      await doctor({ fix: values.fix === true });
+      await doctor({ fix: values.fix === true, json: values.json === true });
       break;
     }
 

package/installer/doctor.js

@@ -48,6 +48,106 @@ export function corruptDbBackups(baseDir = INSTALL_DIR) {
   }
 }
 
+// ─── Claude-layer probes (issue #358 migration) ─────────────────────────
+// Migrated from the retired bash doctor's Claude-skills layer. Paths are
+// injectable for tests. Three bash checks were deliberately NOT migrated
+// because they audit v1-only artifacts with no v2 counterpart:
+//   personas      — v2 deploys agents per-project via the sync engine
+//   agent-memory  — superseded by the claude-mem plugin
+//   capabilities  — v1 KB artifact (~/.arka-os/capabilities.json)
+
+// The hook FILES living in ~/.arkaos/config/hooks (the hooks-dir check)
+// prove nothing about whether Claude Code RUNS them. Governance is only
+// live when ~/.claude/settings.json references the chain — a machine can
+// have every script present, nothing wired, and a green doctor.
+export function hooksWired(
+  settingsPath = join(homedir(), ".claude", "settings.json")
+) {
+  if (!existsSync(settingsPath)) return true; // no Claude Code — not applicable
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    return !!(settings.hooks && settings.hooks.UserPromptSubmit);
+  } catch {
+    return false; // unreadable settings = unverifiable wiring, surface it
+  }
+}
+
+// Status line: configured AND the command it points at exists on disk.
+export function statuslineConfigured(
+  settingsPath = join(homedir(), ".claude", "settings.json")
+) {
+  if (!existsSync(settingsPath)) return true; // no Claude Code — not applicable
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const cmd = settings.statusLine && settings.statusLine.command;
+    if (!cmd) return false;
+    return existsSync(cmd);
+  } catch {
+    return false;
+  }
+}
+
+// gotchas.json is live v2 state: capture/collector.py appends to it and
+// `/arka evolve` (#348) ingests it. Missing means capture never ran;
+// corrupt means evolve will choke.
+export function gotchasHealthy(
+  gotchasPath = join(INSTALL_DIR, "gotchas.json")
+) {
+  if (!existsSync(gotchasPath)) return false;
+  try {
+    return Array.isArray(JSON.parse(readFileSync(gotchasPath, "utf-8")));
+  } catch {
+    return false;
+  }
+}
+
+// The MCP registry ships inside the read-only arka skill bundle.
+export function mcpRegistryHealthy(
+  registryPath = join(
+    homedir(), ".claude", "skills", "arka", "mcps", "registry.json")
+) {
+  if (!existsSync(registryPath)) return false;
+  try {
+    const reg = JSON.parse(readFileSync(registryPath, "utf-8"));
+    return !!reg.mcpServers;
+  } catch {
+    return false;
+  }
+}
+
+// Floor for "an ArkaOS skill set is deployed at all" — curated mode
+// ships 37 core skills, so 7 is a deliberately low absence detector,
+// not a completeness gauge (skills-surface judges completeness).
+export function deployedSkillCount(
+  skillsDir = join(homedir(), ".claude", "skills")
+) {
+  try {
+    return readdirSync(skillsDir).filter(
+      (dir) =>
+        dir.startsWith("arka-") &&
+        existsSync(join(skillsDir, dir, "SKILL.md"))
+    ).length;
+  } catch {
+    return 0;
+  }
+}
+
+// Recommended companion plugins (Superpowers + Claude-Mem). Probing
+// spawns the claude CLI, so keep a hard timeout — a hung CLI must not
+// stall the doctor (same rule as arka-tools-runner).
+export function companionPluginsInstalled() {
+  if (!commandExists("claude")) return true; // no Claude Code — not applicable
+  try {
+    const out = execSync("claude plugin list", {
+      stdio: ["pipe", "pipe", "ignore"],
+      timeout: 15000,
+    }).toString();
+    return out.includes("superpowers") && out.includes("claude-mem");
+  } catch {
+    return false;
+  }
+}
+
 export const checks = [
   {
     name: "install-dir",
@@ -405,6 +505,80 @@ export const checks = [
     },
     fix: () => "Run: npx arkaos keys set HIGGSFIELD_API_KEY <key> (https://higgsfield.ai) — needed for Higgsfield MCP generation",
   },
+  // ─── Claude-layer checks (issue #358) — migrated from the bash doctor.
+  // All warn-only: ArkaOS is multi-runtime, so absence of the Claude
+  // surface must never fail an install that targets codex/gemini/cursor.
+  {
+    name: "claude-cli",
+    description: "Claude Code CLI installed",
+    severity: "warn",
+    check: () => commandExists("claude"),
+    fix: () => "Install: npm install -g @anthropic-ai/claude-code (or use another supported runtime)",
+  },
+  {
+    name: "arka-skill",
+    description: "arka orchestrator skill bundle deployed (~/.claude/skills/arka)",
+    severity: "warn",
+    check: () =>
+      existsSync(join(homedir(), ".claude", "skills", "arka", "SKILL.md")),
+    fix: () => "Run: npx arkaos install --force",
+  },
+  {
+    name: "jq",
+    description: "jq available (bash hooks parse JSON with it; python3 is the fallback)",
+    severity: "warn",
+    check: () => commandExists("jq"),
+    fix: () => "Install jq: brew install jq (macOS) / apt install jq (Linux)",
+  },
+  {
+    name: "statusline",
+    description: "Status line configured and its command exists",
+    severity: "warn",
+    check: () => statuslineConfigured(),
+    fix: () => "Run: npx arkaos install --force (redeploys and wires the statusline)",
+  },
+  {
+    name: "hooks-wired",
+    description: "Hook chain referenced by ~/.claude/settings.json (governance live)",
+    severity: "warn",
+    check: () => hooksWired(),
+    fix: () => "Run: npx arkaos install --force (rewires hooks into settings.json)",
+  },
+  {
+    name: "skills-deployed",
+    description: "ArkaOS skill set deployed (>= 7 arka-* skills)",
+    severity: "warn",
+    check: () => deployedSkillCount() >= 7,
+    fix: () => "Run: npx arkaos@latest update (redeploys the curated skill set)",
+  },
+  {
+    name: "mcp-registry",
+    description: "MCP registry present in the arka skill bundle",
+    severity: "warn",
+    check: () => mcpRegistryHealthy(),
+    fix: () => "Run: npx arkaos install --force",
+  },
+  {
+    name: "yt-dlp",
+    description: "yt-dlp present (video reference analysis + content ingestion)",
+    severity: "warn",
+    check: () => commandExists("yt-dlp"),
+    fix: () => "Install yt-dlp: brew install yt-dlp (macOS) / pipx install yt-dlp — only needed for video/content workflows",
+  },
+  {
+    name: "gotchas",
+    description: "gotchas.json valid (capture layer output, ingested by /arka evolve)",
+    severity: "warn",
+    check: () => gotchasHealthy(),
+    fix: () => "Missing: capture has not run yet (created automatically). Corrupt: inspect ~/.arkaos/gotchas.json — /arka evolve cannot ingest it",
+  },
+  {
+    name: "companion-plugins",
+    description: "Companion plugins installed (Superpowers + Claude-Mem)",
+    severity: "warn",
+    check: () => companionPluginsInstalled(),
+    fix: () => "claude plugin marketplace add obra/superpowers-marketplace && claude plugin install superpowers@superpowers-marketplace; claude plugin marketplace add thedotmack/claude-mem && claude plugin install claude-mem@thedotmack",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────
@@ -464,6 +638,8 @@ if (IS_WINDOWS) {
 
 export async function doctor(options = {}) {
   const fixMode = !!options.fix;
+  const jsonMode = !!options.json;
+  if (jsonMode) return doctorJson();
   console.log(`\n  ArkaOS Doctor — Health Checks${fixMode ? " (--fix)" : ""}\n`);
 
   // ─── --fix: repair the venv before reporting checks (PR2 v3.73.1) ────
@@ -535,6 +711,54 @@ export async function doctor(options = {}) {
   if (failed > 0) process.exit(1);
 }
 
+// Machine-readable run (issue #358 step 4). Same checks, same exit-code
+// contract as the human run; the security advisory stays out — it is a
+// human-facing print, and the scanner already has its own --json
+// (core.governance.harness_scanner_cli).
+function doctorJson() {
+  const results = [];
+  let passed = 0;
+  let warned = 0;
+  let failed = 0;
+  for (const check of checks) {
+    let ok = false;
+    let error = null;
+    try {
+      ok = !!check.check();
+    } catch (err) {
+      error = err && err.message
+        ? String(err.message).split("\n")[0].slice(0, 120)
+        : String(err);
+    }
+    const status = ok ? "pass" : check.severity === "fail" ? "fail" : "warn";
+    if (ok) passed++;
+    else if (check.severity === "fail") failed++;
+    else warned++;
+    const entry = {
+      name: check.name,
+      status,
+      severity: check.severity,
+      description: check.description,
+      fix: ok ? "" : safeFix(check),
+    };
+    if (error) entry.error = error;
+    results.push(entry);
+  }
+  console.log(JSON.stringify({
+    checks: results,
+    summary: { passed, warned, failed, total: results.length },
+  }));
+  if (failed > 0) process.exit(1);
+}
+
+function safeFix(check) {
+  try {
+    return check.fix();
+  } catch {
+    return "(fix hint unavailable)";
+  }
+}
+
 // Doctor answers "is the install healthy?". It never answered "is the
 // install SAFE?" — a config can be perfectly healthy and still hand a
 // third party the right to run code on this machine. The scanner does

package/installer/harness-bundle.js

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Multi-runtime instruction bundles, generated by scripts/harness_gen.py
+// and shipped inside the npm package under harness/<target>/. The
+// adapters deploy these VERBATIM — before this module existed they wrote
+// pointers at ~/.arkaos/config/<runtime>-instructions.md, a file nothing
+// ever created (issue found during the harness-generator work).
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function bundleDir(target) {
+  return join(PKG_ROOT, "harness", target);
+}
+
+// Content of one bundle file, or null when the bundle is absent (a
+// source tree without a generated harness/ — callers must fall back
+// loudly, never write a pointer to a file that does not exist).
+export function readBundleFile(target, rel) {
+  const path = join(bundleDir(target), rel);
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+// Flat file listing of a bundle subdirectory (e.g. cursor "rules").
+export function listBundleFiles(target, subdir = "") {
+  const base = join(bundleDir(target), subdir);
+  try {
+    return readdirSync(base).filter((name) =>
+      existsSync(join(base, name)) && !name.startsWith(".")
+    );
+  } catch {
+    return [];
+  }
+}

package/knowledge/agents-registry-v2.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "version": "2.0.0",
-    "generated": "2026-07-14T23:46:28.709940",
+    "generated": "2026-07-20T21:08:57.022558",
     "total_agents": 86,
     "generator": "core/agents/registry_gen.py",
     "tiers": {
@@ -251,7 +251,7 @@
     {
       "id": "shadcn-padronizer-leo",
       "name": "Leo",
-      "role": "Component Library Padronizer",
+      "role": "Component Library Standardizer",
       "department": "brand",
       "tier": 2,
       "model": "sonnet",