@dujavi/ai-md 0.4.0 → 0.5.0

package/README.md

@@ -1,61 +1,133 @@
-# ai-md
+# @dujavi/ai-md
 
 Public **AXI-shaped** CLI for a **private** personal AI config directory (`~/.ai-md`).
 
+The npm package ships tooling only — no personal skills, rules, or secrets. Your content lives in a private git repo you point at with `--remote` (or machine config). Default reads are TOON + `help[]`; use `--json` when you need JSON.
+
+![Architecture](docs/architecture.png)
+
+## What it manages
+
 | Layer | Path | Purpose |
 |-------|------|---------|
-| **System** | `skills/`, `rules/` | Global base — linked to `~/.cursor/{skills,rules}` |
+| **System** | `skills/`, `rules/` | Global base — linked into agent harnesses |
 | **Templates** | `templates/<type>/` | Project-type starters (`base`, later `forms`, …) |
 | **Projects** | `projects/<name>/` | Per-app overlays (repo `.cursor` → here) |
+| **Scripts** | `scripts/<name>` | Private machine scripts via `ai-md script` / `setup --script` |
 
-No personal content ships in this package. Reads default to TOON + `help[]` (`--json` available).
+## Supported harnesses
 
-## New machine
+Skill (and for Cursor, rules) link targets via `--agents` (comma-separated):
+
+| Harness | Skills link | Notes |
+|---------|-------------|--------|
+| `cursor` | `~/.cursor/skills` | **Default.** Install also links `~/.cursor/rules` → `~/.ai-md/rules` |
+| `claude` | `~/.claude/skills` | Optional second harness |
+| `agents` | `~/.agents/skills` | Optional agents-skills layout |
 
 ```bash
-npm i -g @dujavi/ai-md
-ai-md setup --remote https://github.com/<you>/.ai-md.git --tools
-# persists ~/.config/ai-md/config.json then clones + links (+ optional grok/quota-axi)
+ai-md doctor --fix --agents cursor,claude
+ai-md install --agents cursor,claude,agents
 ```
 
-Or step by step:
+## Architecture
 
-```bash
-ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
-ai-md install
-ai-md ensure-tools
+```mermaid
+flowchart TB
+  subgraph publicPkg ["@dujavi/ai-md"]
+    cli["ai-md CLI"]
+    runner["lib/scripts.js"]
+  end
+  subgraph privateDir ["~/.ai-md"]
+    system["skills + rules"]
+    templates["templates/"]
+    projects["projects/"]
+    scripts["scripts/"]
+  end
+  subgraph harnesses ["Supported harnesses"]
+    cursor["cursor ~/.cursor"]
+    claude["claude ~/.claude"]
+    agents["agents ~/.agents"]
+  end
+  cli --> system
+  cli --> templates
+  cli --> projects
+  cli --> runner
+  runner --> scripts
+  system --> cursor
+  system --> claude
+  system --> agents
 ```
 
-Precedence: `--remote`/`--dir` flags > `AI_MD_*` env > `~/.config/ai-md/config.json` > defaults.
+Personal installers (Grok, quota-axi, etc.) are **not** baked into this package. Put them in `~/.ai-md/scripts/` and run with `--script` / `ai-md script`.
 
-## Layout idea
+## Quick start
 
-```text
-~/.ai-md/
-  skills/                 # system — all agents see these
-  rules/
-  templates/
-    base/                 # default project starter (customizable stubs only)
-    # forms/ …            # other use cases
-  projects/
-    presenter/
-    sendfolio/
+```bash
+npm i -g @dujavi/ai-md
+
+# First machine: persist config, clone, link, run a private script
+ai-md setup --remote https://github.com/<you>/.ai-md.git --script ensure-tools
+
+# Or step by step
+ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
+ai-md install
+ai-md script ensure-tools
 ```
 
-Put shared agentic skills/rules in **system** folders. Put only type-specific or per-project starters under **templates/**.
+Precedence: `--remote` / `--dir` flags > `AI_MD_*` env > `~/.config/ai-md/config.json` > defaults (`~/.ai-md`, package default remote).
 
 ## Commands
 
 ```bash
-ai-md                                      # status
+ai-md                                      # status (AXI)
+ai-md setup --remote <url> --script <name>
+ai-md config | config set --remote <url> --dir ~/.ai-md
+ai-md install [--agents cursor,claude]
+ai-md doctor --fix
+ai-md pull | push -m "why"
+ai-md script <name> [--] [args...]         # private ~/.ai-md/scripts/
 ai-md init-project --repo ~/app --from base
 ai-md apply-template --project app --from base
-ai-md doctor --fix --agents cursor,claude
-ai-md pull | push -m "why"
-ai-md ensure-tools
+ai-md link-project --repo ~/app --name app
+```
+
+### Private scripts
+
+```bash
+ai-md script ensure-tools
+ai-md script ensure-tools -- --dry-run
+ai-md setup --remote <url> --script ensure-tools -- --dry-run
+```
+
+- Resolves `$AI_MD_DIR/scripts/<name>` or `<name>.sh` (basename only; no `..` / paths).
+- Args after the script name (or after `--` on `setup` / `install`) are forwarded unchanged.
+- Repeat `--script` on setup/install; the same trailing args apply to each.
+
+## Machine config
+
+Persisted at `~/.config/ai-md/config.json` (override path with `AI_MD_CONFIG`):
+
+```json
+{ "dir": "/home/you/.ai-md", "remote": "https://github.com/you/.ai-md.git" }
+```
+
+Env one-shots: `AI_MD_DIR`, `AI_MD_REMOTE`.
+
+## Layout example
+
+```text
+~/.ai-md/
+  skills/                 # system — harnesses see these
+  rules/
+  scripts/
+    ensure-tools.sh       # your private tooling
+  templates/
+    base/
+  projects/
+    my-app/
 ```
 
-## Environment
+## License
 
-- `AI_MD_DIR` / `AI_MD_REMOTE` — override for one shot (also set by the CLI after reading config)
-- `AI_MD_CONFIG` — path to machine config JSON (default `~/.config/ai-md/config.json`)
+MIT

package/bin/ai-md.js

@@ -20,9 +20,78 @@ const {
   ensureCursorLinks,
   ensureAgentSkillLinks,
 } = require("../lib/commands");
+const { runScript, runScripts } = require("../lib/scripts");
 
 const scriptsDir = path.join(__dirname, "..", "scripts");
 
+function applyFlag(out, flag, args) {
+  switch (flag) {
+    case "--json":
+      out.json = true;
+      return true;
+    case "--full":
+      out.full = true;
+      return true;
+    case "--force":
+      out.force = true;
+      return true;
+    case "--dry-run":
+      out.dryRun = true;
+      return true;
+    case "--fix":
+      out.fix = true;
+      out.force = true;
+      return true;
+    case "-m":
+    case "--message":
+      out.message = args.shift();
+      return true;
+    case "--repo":
+      out.repo = args.shift();
+      return true;
+    case "--name":
+      out.name = args.shift();
+      return true;
+    case "--project":
+      out.project = args.shift();
+      return true;
+    case "--from":
+      out.from = args.shift();
+      return true;
+    case "--remote":
+      out.remote = args.shift();
+      return true;
+    case "--dir":
+      out.dir = expandHome(args.shift());
+      return true;
+    case "--agents":
+      out.agents = String(args.shift() || "cursor")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      return true;
+    case "--script": {
+      const name = args.shift();
+      if (!name) {
+        fail("--script requires a name", {
+          exitCode: 2,
+          json: out.json,
+          help: ["ai-md setup --script ensure-tools"],
+        });
+        process.exit(2);
+      }
+      out.scripts.push(name);
+      return true;
+    }
+    case "-h":
+    case "--help":
+      out.cmdHelp = true;
+      return true;
+    default:
+      return false;
+  }
+}
+
 function parseArgs(argv) {
   const out = {
     cmd: null,
@@ -31,7 +100,6 @@ function parseArgs(argv) {
     force: false,
     dryRun: false,
     fix: false,
-    tools: false,
     message: null,
     repo: null,
     name: null,
@@ -40,6 +108,9 @@ function parseArgs(argv) {
     remote: null,
     dir: null,
     agents: ["cursor"],
+    scripts: [],
+    scriptName: null,
+    scriptArgs: [],
     rest: [],
   };
   const args = [...argv];
@@ -57,67 +128,22 @@ function parseArgs(argv) {
   } else {
     out.cmd = args.shift();
   }
-  while (args.length) {
-    const a = args.shift();
-    switch (a) {
-      case "--json":
-        out.json = true;
-        break;
-      case "--full":
-        out.full = true;
-        break;
-      case "--force":
-        out.force = true;
-        break;
-      case "--dry-run":
-        out.dryRun = true;
-        break;
-      case "--fix":
-        out.fix = true;
-        out.force = true;
-        break;
-      case "--tools":
-        out.tools = true;
-        break;
-      case "-m":
-      case "--message":
-        out.message = args.shift();
-        break;
-      case "--repo":
-        out.repo = args.shift();
-        break;
-      case "--name":
-        out.name = args.shift();
-        break;
-      case "--project":
-        out.project = args.shift();
-        break;
-      case "--from":
-        out.from = args.shift();
-        break;
-      case "--remote":
-        out.remote = args.shift();
-        break;
-      case "--dir":
-        out.dir = expandHome(args.shift());
-        break;
-      case "--agents":
-        out.agents = String(args.shift() || "cursor")
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean);
-        break;
-      case "-h":
-      case "--help":
-        out.cmdHelp = true;
-        break;
-      case "set":
-      case "show":
-        // subcommand for `ai-md config set|show`
-        out.rest.push(a);
-        break;
-      default:
-        if (a.startsWith("-")) {
+
+  // `script <name> [--] [args...]` — ai-md flags only before the name
+  if (out.cmd === "script" || out.cmd === "run-script") {
+    while (args.length) {
+      const a = args[0];
+      if (a === "--") {
+        fail("script name required before `--`", {
+          exitCode: 2,
+          json: out.json,
+          help: ["ai-md script ensure-tools -- --dry-run"],
+        });
+        process.exit(2);
+      }
+      if (a.startsWith("-")) {
+        args.shift();
+        if (!applyFlag(out, a, args)) {
           fail(`unknown flag: ${a}`, {
             exitCode: 2,
             json: out.json,
@@ -125,9 +151,46 @@ function parseArgs(argv) {
           });
           process.exit(2);
         }
-        out.rest.push(a);
-        break;
+        continue;
+      }
+      out.scriptName = args.shift();
+      break;
+    }
+    if (!out.scriptName) {
+      fail("script requires a name", {
+        exitCode: 2,
+        json: out.json,
+        help: ["ai-md script <name> [--] [args...]"],
+      });
+      process.exit(2);
+    }
+    if (args[0] === "--") args.shift();
+    out.scriptArgs = args;
+    return out;
+  }
+
+  while (args.length) {
+    const a = args.shift();
+    if (a === "--") {
+      out.scriptArgs = args;
+      break;
+    }
+    if (a === "set" || a === "show") {
+      out.rest.push(a);
+      continue;
+    }
+    if (a.startsWith("-")) {
+      if (!applyFlag(out, a, args)) {
+        fail(`unknown flag: ${a}`, {
+          exitCode: 2,
+          json: out.json,
+          help: ["Run `ai-md --help`"],
+        });
+        process.exit(2);
+      }
+      continue;
     }
+    out.rest.push(a);
   }
   return out;
 }
@@ -143,19 +206,25 @@ Layout:
   ~/.ai-md/skills, rules     System (global) base — linked to ~/.cursor
   ~/.ai-md/templates/<type>  Project-type starters (default: base)
   ~/.ai-md/projects/<name>   Per-app overlays (repo .cursor → here)
+  ~/.ai-md/scripts/<name>    Private machine scripts (ai-md script / setup --script)
 
 Machine config (persisted):
   ~/.config/ai-md/config.json   dir + remote (override with AI_MD_CONFIG)
   Precedence: --flag > env > config file > defaults
 
+Supported harnesses (--agents):
+  cursor   ~/.cursor/skills (+ ~/.cursor/rules via install)  [default]
+  claude   ~/.claude/skills
+  agents   ~/.agents/skills
+
 Commands:
-  setup              First-time machine setup: save config, install, optional --tools
+  setup              First-time machine setup: save config, install, optional --script
   config             Show persisted config (or: config set --remote/--dir)
   status             Snapshot (default when no command) [AXI]
   doctor             Diagnose links/projects; --fix repairs
   install            Clone remote if needed; link ~/.cursor + optional agents
   pull | push        Sync private git repo
-  ensure-tools       Install/update grok + quota-axi (alias: tools)
+  script             Run ~/.ai-md/scripts/<name> (alias: run-script)
   init-project       Seed projects/<name> from templates/<from> + link .cursor/
   apply-template     Merge missing files from a template into a project
   link-project       Link repo .cursor/ without seeding (alias: link)
@@ -166,22 +235,26 @@ Options:
   --dir <path>       Local AI_MD_DIR (default ~/.ai-md; persisted same way)
   --json             JSON instead of TOON
   --full             Include paths and drift details
-  --agents <list>    Skill link targets: cursor,claude,agents (default: cursor)
-  --tools            With setup: also run ensure-tools
+  --agents <list>    Skill link harnesses: cursor,claude,agents (default: cursor)
+  --script <name>    With setup/install: run private script (repeatable)
   --repo <path>      App repository root
   --name <id>        Project id under projects/
   --project <id>     Target project for apply-template
   --from <id>        Template under templates/ (default: base)
   --force            Replace non-symlink paths
-  --dry-run          Preview without writing
+  --dry-run          Preview without writing (before script name / before --)
   --fix             doctor: repair symlinks
   -m, --message      push commit message
+  --                 End of ai-md options; remaining args go to private scripts
 
 Examples:
-  ai-md setup --remote https://github.com/<you>/.ai-md.git --tools
+  ai-md setup --remote https://github.com/<you>/.ai-md.git --script ensure-tools
+  ai-md setup --remote <url> --script ensure-tools -- --dry-run
+  ai-md script ensure-tools
+  ai-md script ensure-tools -- --dry-run
   ai-md config set --remote https://github.com/<you>/.ai-md.git --dir ~/.ai-md
-  ai-md config
   ai-md install --remote https://github.com/<you>/.ai-md.git
+  ai-md doctor --fix --agents cursor,claude
   ai-md init-project --repo ~/presenter --from base
 `);
 }
@@ -237,7 +310,6 @@ function main() {
     return;
   }
 
-  // Resolve after flags so --dir/--remote apply
   let cfg = resolveConfig(process.env, {
     dir: opts.dir || undefined,
     remote: opts.remote || undefined,
@@ -266,11 +338,18 @@ function main() {
           );
           cfg = resolveConfig(process.env);
           emit({
-            data: { ...saved, resolved: { dir: cfg.dir, remote: cfg.remote, sources: cfg.sources } },
+            data: {
+              ...saved,
+              resolved: {
+                dir: cfg.dir,
+                remote: cfg.remote,
+                sources: cfg.sources,
+              },
+            },
             json: opts.json,
             help: [
               "Run `ai-md install` if ~/.ai-md is not cloned yet",
-              "Run `ai-md setup --remote <url> --tools` for first-time machine bootstrap",
+              "Run `ai-md setup --remote <url> --script ensure-tools` for first-time bootstrap",
             ],
           });
           break;
@@ -296,9 +375,6 @@ function main() {
         break;
       }
       case "setup": {
-        if (!opts.remote && !cfg.machineConfig?.remote && cfg.sources.remote === "default") {
-          // Allow default for dujavi, but recommend explicit remote for others via help
-        }
         const saved = writeMachineConfig(
           {
             dir: opts.dir || cfg.dir,
@@ -312,18 +388,14 @@ function main() {
           remote: opts.remote || undefined,
         });
         applyEnvFromConfig(cfg);
-        const links = opts.dryRun
-          ? []
-          : runInstall(cfg, opts);
-        let tools = null;
-        if (opts.tools && !opts.dryRun) {
-          const tr = spawnSync(
-            "bash",
-            [path.join(scriptsDir, "ensure-agent-tools.sh")],
-            { stdio: "inherit", env: process.env }
-          );
-          tools = { exitCode: tr.status };
-        }
+        const links = opts.dryRun ? [] : runInstall(cfg, opts);
+        const scripts =
+          opts.scripts.length === 0
+            ? []
+            : runScripts(cfg, opts.scripts, opts.scriptArgs, {
+                dryRun: opts.dryRun,
+              });
+        const failed = scripts.find((s) => s.exitCode !== 0);
         const data = collectStatus({
           full: opts.full,
           agents: opts.agents,
@@ -334,17 +406,18 @@ function main() {
             setup: "ok",
             config: saved,
             links,
-            tools,
+            scripts,
             ...data,
           },
           json: opts.json,
           help: [
-            opts.tools
+            opts.scripts.length
               ? "Run `ai-md status` to verify"
-              : "Run `ai-md ensure-tools` (or re-run setup with --tools)",
+              : "Run `ai-md script <name>` for private machine scripts (e.g. ensure-tools)",
             "Run `ai-md init-project --repo <path> --from base` for a new app",
           ],
         });
+        if (failed) process.exit(failed.exitCode);
         break;
       }
       case "status": {
@@ -433,15 +506,23 @@ function main() {
           applyEnvFromConfig(cfg);
         }
         const links = runInstall(cfg, opts);
+        const scripts =
+          opts.scripts.length === 0
+            ? []
+            : runScripts(cfg, opts.scripts, opts.scriptArgs, {
+                dryRun: opts.dryRun,
+              });
+        const failed = scripts.find((s) => s.exitCode !== 0);
         const data = collectStatus({ full: opts.full, agents: opts.agents });
         emit({
-          data: { install: "ok", config: saved, links, ...data },
+          data: { install: "ok", config: saved, links, scripts, ...data },
           json: opts.json,
           help: [
-            "Run `ai-md ensure-tools` to install grok + quota-axi",
+            "Run `ai-md script <name>` for private machine scripts",
             "Run `ai-md init-project --repo <path>` for a new app",
           ],
         });
+        if (failed) process.exit(failed.exitCode);
         break;
       }
       case "pull":
@@ -458,14 +539,23 @@ function main() {
         runBash("sync-config.sh", args, process.env);
         break;
       }
-      case "ensure-tools":
-      case "tools":
-        runBash(
-          "ensure-agent-tools.sh",
-          [...(opts.dryRun ? ["--dry-run"] : [])],
-          process.env
-        );
+      case "script":
+      case "run-script": {
+        const result = runScript(cfg, opts.scriptName, opts.scriptArgs, {
+          dryRun: opts.dryRun,
+        });
+        emit({
+          data: { scripts: [result] },
+          json: opts.json,
+          help: [
+            "Scripts live in ~/.ai-md/scripts/ (private content repo)",
+            "ai-md script <name> -- [args...]",
+            "ai-md setup --script <name> -- [args...]",
+          ],
+        });
+        process.exit(result.exitCode);
         break;
+      }
       default:
         fail(`unknown command: ${opts.cmd}`, {
           exitCode: 2,
@@ -476,7 +566,7 @@ function main() {
     }
   } catch (err) {
     fail(err.message || String(err), {
-      exitCode: err.code === "EINVAL" ? 2 : 1,
+      exitCode: err.code === "EINVAL" || err.code === "ENOENT" ? 2 : 1,
       json: opts.json,
       help: ["Run `ai-md --help`"],
     });

package/docs/architecture.html

@@ -0,0 +1,316 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>@dujavi/ai-md architecture</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      background: #ffffff;
+      font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      color: #111827;
+      -webkit-font-smoothing: antialiased;
+    }
+
+    .canvas {
+      width: 1100px;
+      padding: 36px 40px 44px;
+      background: #ffffff;
+    }
+
+    h1 {
+      font-size: 22px;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      text-align: center;
+      margin-bottom: 28px;
+      color: #0f172a;
+    }
+
+    .columns {
+      display: grid;
+      grid-template-columns: 1fr 1fr 1fr;
+      gap: 28px;
+      align-items: start;
+    }
+
+    .column-label {
+      font-size: 12px;
+      font-weight: 600;
+      text-transform: none;
+      letter-spacing: 0.01em;
+      color: #475569;
+      margin-bottom: 10px;
+      text-align: center;
+    }
+
+    .panel {
+      border: 2px solid #1e293b;
+      border-radius: 10px;
+      background: #f8fafc;
+      padding: 14px 14px 16px;
+      min-height: 280px;
+    }
+
+    .panel-title {
+      font-size: 14px;
+      font-weight: 700;
+      color: #0f172a;
+      text-align: center;
+      margin-bottom: 12px;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    }
+
+    .stack {
+      display: flex;
+      flex-direction: column;
+      gap: 10px;
+    }
+
+    .box {
+      border: 1.5px solid #334155;
+      border-radius: 8px;
+      background: #ffffff;
+      padding: 12px 14px;
+      text-align: center;
+      font-size: 13px;
+      font-weight: 600;
+      color: #0f172a;
+      line-height: 1.35;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    }
+
+    .box.primary {
+      background: #eff6ff;
+      border-color: #1d4ed8;
+      color: #1e3a8a;
+    }
+
+    .box.system {
+      background: #ecfdf5;
+      border-color: #047857;
+      color: #064e3b;
+    }
+
+    .box.template {
+      background: #fffbeb;
+      border-color: #b45309;
+      color: #78350f;
+    }
+
+    .box.project {
+      background: #fdf2f8;
+      border-color: #be185d;
+      color: #831843;
+    }
+
+    .box.script {
+      background: #f1f5f9;
+      border-color: #475569;
+      color: #1e293b;
+    }
+
+    .box.harness {
+      background: #f5f3ff;
+      border-color: #5b21b6;
+      color: #4c1d95;
+    }
+
+    .flow {
+      position: relative;
+      margin-top: 8px;
+    }
+
+    /* SVG overlay for arrows spanning columns */
+    .arrows {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      pointer-events: none;
+      overflow: visible;
+    }
+
+    .diagram {
+      position: relative;
+    }
+
+    .legend {
+      margin-top: 22px;
+      display: flex;
+      justify-content: center;
+      gap: 28px;
+      flex-wrap: wrap;
+      font-size: 12px;
+      color: #475569;
+    }
+
+    .legend-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .legend-line {
+      width: 28px;
+      height: 0;
+      border-top: 2px solid #1e293b;
+      position: relative;
+    }
+
+    .legend-line::after {
+      content: "";
+      position: absolute;
+      right: -1px;
+      top: -4px;
+      border: 4px solid transparent;
+      border-left: 7px solid #1e293b;
+    }
+
+    .footer-note {
+      margin-top: 14px;
+      text-align: center;
+      font-size: 11px;
+      color: #64748b;
+    }
+  </style>
+</head>
+<body>
+  <div class="canvas" id="capture">
+    <h1>@dujavi/ai-md</h1>
+
+    <div class="diagram" id="diagram">
+      <div class="columns" id="columns">
+        <!-- Left: package -->
+        <div class="col" id="col-pkg">
+          <div class="column-label">npm package</div>
+          <div class="panel">
+            <div class="panel-title">@dujavi/ai-md</div>
+            <div class="stack">
+              <div class="box primary" id="box-cli">ai-md CLI</div>
+              <div class="box script" id="box-runner">lib/scripts.js</div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Center: private dir -->
+        <div class="col" id="col-private">
+          <div class="column-label">private config</div>
+          <div class="panel">
+            <div class="panel-title">~/.ai-md</div>
+            <div class="stack">
+              <div class="box system" id="box-system">skills + rules</div>
+              <div class="box template" id="box-templates">templates/</div>
+              <div class="box project" id="box-projects">projects/</div>
+              <div class="box script" id="box-scripts">scripts/</div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Right: harnesses -->
+        <div class="col" id="col-harness">
+          <div class="column-label">Supported harnesses</div>
+          <div class="panel">
+            <div class="panel-title">Supported harnesses</div>
+            <div class="stack">
+              <div class="box harness" id="box-cursor">cursor ~/.cursor</div>
+              <div class="box harness" id="box-claude">claude ~/.claude</div>
+              <div class="box harness" id="box-agents">agents ~/.agents</div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <svg class="arrows" id="arrows" xmlns="http://www.w3.org/2000/svg"></svg>
+    </div>
+
+    <div class="legend">
+      <div class="legend-item"><span class="legend-line"></span> manages / links</div>
+    </div>
+    <p class="footer-note">Public package tooling · private content in ~/.ai-md · linked into agent harnesses</p>
+  </div>
+
+  <script>
+    function centerOf(el, root) {
+      const r = el.getBoundingClientRect();
+      const b = root.getBoundingClientRect();
+      return {
+        x: r.left - b.left + r.width / 2,
+        y: r.top - b.top + r.height / 2,
+        left: r.left - b.left,
+        right: r.left - b.left + r.width,
+        top: r.top - b.top,
+        bottom: r.top - b.top + r.height,
+        width: r.width,
+        height: r.height,
+      };
+    }
+
+    function draw() {
+      const root = document.getElementById("diagram");
+      const svg = document.getElementById("arrows");
+      const rect = root.getBoundingClientRect();
+      svg.setAttribute("width", rect.width);
+      svg.setAttribute("height", rect.height);
+      svg.style.width = rect.width + "px";
+      svg.style.height = rect.height + "px";
+      svg.innerHTML = "";
+
+      const defs = document.createElementNS("http://www.w3.org/2000/svg", "defs");
+      defs.innerHTML = `
+        <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
+          markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+          <path d="M 0 0 L 10 5 L 0 10 z" fill="#1e293b"/>
+        </marker>
+      `;
+      svg.appendChild(defs);
+
+      const cli = centerOf(document.getElementById("box-cli"), root);
+      const runner = centerOf(document.getElementById("box-runner"), root);
+      const system = centerOf(document.getElementById("box-system"), root);
+      const templates = centerOf(document.getElementById("box-templates"), root);
+      const projects = centerOf(document.getElementById("box-projects"), root);
+      const scripts = centerOf(document.getElementById("box-scripts"), root);
+      const cursor = centerOf(document.getElementById("box-cursor"), root);
+      const claude = centerOf(document.getElementById("box-claude"), root);
+      const agents = centerOf(document.getElementById("box-agents"), root);
+
+      function line(x1, y1, x2, y2, opts = {}) {
+        const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+        const midX = (x1 + x2) / 2;
+        const d = opts.curve
+          ? `M ${x1} ${y1} C ${midX} ${y1}, ${midX} ${y2}, ${x2} ${y2}`
+          : `M ${x1} ${y1} L ${x2} ${y2}`;
+        path.setAttribute("d", d);
+        path.setAttribute("fill", "none");
+        path.setAttribute("stroke", opts.color || "#1e293b");
+        path.setAttribute("stroke-width", opts.width || "2");
+        path.setAttribute("marker-end", "url(#arrow)");
+        if (opts.dash) path.setAttribute("stroke-dasharray", "5 4");
+        svg.appendChild(path);
+      }
+
+      // CLI → skills+rules, templates, projects
+      line(cli.right, cli.y, system.left, system.y, { curve: true });
+      line(cli.right, cli.y + 2, templates.left, templates.y, { curve: true });
+      line(cli.right, cli.y + 4, projects.left, projects.y, { curve: true });
+
+      // CLI → lib/scripts.js (vertical within left panel)
+      line(cli.x, cli.bottom, runner.x, runner.top, { curve: false });
+
+      // lib/scripts.js → scripts/
+      line(runner.right, runner.y, scripts.left, scripts.y, { curve: true });
+
+      // skills+rules → each harness
+      line(system.right, system.y, cursor.left, cursor.y, { curve: true });
+      line(system.right, system.y + 2, claude.left, claude.y, { curve: true });
+      line(system.right, system.y + 4, agents.left, agents.y, { curve: true });
+    }
+
+    requestAnimationFrame(() => requestAnimationFrame(draw));
+    window.addEventListener("resize", draw);
+  </script>
+</body>
+</html>

package/lib/scripts.js

@@ -0,0 +1,104 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function scriptsDir(cfg) {
+  return path.join(cfg.dir, "scripts");
+}
+
+/**
+ * Resolve a private script by basename only (no path separators).
+ * Prefers exact name, then `<name>.sh`.
+ */
+function resolveScript(cfg, name) {
+  const raw = String(name || "").trim();
+  if (!raw || !NAME_RE.test(raw) || raw.includes("..")) {
+    const err = new Error(
+      `invalid script name: ${JSON.stringify(name)} (use a single basename)`
+    );
+    err.code = "EINVAL";
+    throw err;
+  }
+
+  const dir = scriptsDir(cfg);
+  const exact = path.join(dir, raw);
+  const withSh = raw.endsWith(".sh") ? null : path.join(dir, `${raw}.sh`);
+
+  if (fs.existsSync(exact) && fs.statSync(exact).isFile()) {
+    return { name: raw, path: exact, dir };
+  }
+  if (withSh && fs.existsSync(withSh) && fs.statSync(withSh).isFile()) {
+    return { name: raw, path: withSh, dir };
+  }
+
+  const err = new Error(
+    `script not found: ${raw} (looked in ${dir}/${raw} and ${dir}/${raw}.sh)`
+  );
+  err.code = "ENOENT";
+  throw err;
+}
+
+/**
+ * Run a private script with forwarded args. Returns { name, args, path, exitCode }.
+ * Uses bash for .sh; otherwise executes the file directly.
+ */
+function runScript(cfg, name, args = [], { dryRun = false } = {}) {
+  const resolved = resolveScript(cfg, name);
+  const scriptArgs = Array.isArray(args) ? args.map(String) : [];
+  const useBash = resolved.path.endsWith(".sh");
+  const argv = useBash
+    ? ["bash", resolved.path, ...scriptArgs]
+    : [resolved.path, ...scriptArgs];
+
+  if (dryRun) {
+    return {
+      name: resolved.name,
+      args: scriptArgs,
+      path: resolved.path,
+      exitCode: 0,
+      dryRun: true,
+      command: argv,
+    };
+  }
+
+  const result = spawnSync(argv[0], argv.slice(1), {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (result.error) {
+    const err = new Error(result.error.message);
+    err.code = result.error.code || "EEXEC";
+    throw err;
+  }
+
+  return {
+    name: resolved.name,
+    args: scriptArgs,
+    path: resolved.path,
+    exitCode: result.status === null ? 1 : result.status,
+  };
+}
+
+function runScripts(cfg, names, args = [], { dryRun = false } = {}) {
+  const results = [];
+  for (const name of names) {
+    const result = runScript(cfg, name, args, { dryRun });
+    results.push(result);
+    if (!dryRun && result.exitCode !== 0) {
+      break;
+    }
+  }
+  return results;
+}
+
+module.exports = {
+  scriptsDir,
+  resolveScript,
+  runScript,
+  runScripts,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dujavi/ai-md",
-  "version": "0.4.0",
-  "description": "AXI-shaped CLI for ~/.ai-md with persisted dir/remote machine config, templates/, and projects/",
+  "version": "0.5.0",
+  "description": "AXI-shaped CLI for a private ~/.ai-md: system skills/rules, templates, projects, and private script runner for agent harnesses (Cursor, Claude, agents)",
   "bin": {
     "ai-md": "bin/ai-md.js"
   },
@@ -9,6 +9,7 @@
     "bin/",
     "lib/",
     "scripts/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],
@@ -22,14 +23,16 @@
     "@toon-format/toon": "^2.3.1"
   },
   "keywords": [
+    "axi",
     "cursor",
-    "ai",
+    "claude",
+    "agents",
     "skills",
     "rules",
-    "quota-axi",
-    "grok",
+    "personal-config",
     "cli",
-    "axi"
+    "toon",
+    "ai-md"
   ],
   "author": "dujavi",
   "license": "MIT",

package/scripts/sync-config.sh

@@ -22,7 +22,7 @@ Commands:
   status    Show repo state, symlink health, and rule/skill counts
   doctor    Diagnose problems; with --fix, repair symlinks
 
-Also: ai-md ensure-tools  (grok + quota-axi)
+Private scripts: ai-md script <name>  (from ~/.ai-md/scripts/)
 
 Options:
   -m, --message <msg>  Commit message for push (default: generic update)
@@ -146,7 +146,7 @@ cmd_install() {
   log "Install complete."
   log "  rules:  $(count_rules)"
   log "  skills: $(count_skills)"
-  log "Next: ai-md ensure-tools  # grok + quota-axi"
+  log "Next: ai-md script <name>  # private ~/.ai-md/scripts/"
 }
 
 cmd_pull() {

package/scripts/ensure-agent-tools.sh

@@ -1,114 +0,0 @@
-#!/usr/bin/env bash
-# Ensure Grok Build CLI + quota-axi are installed on this machine.
-# Safe to re-run (idempotent). Does not print secrets.
-set -euo pipefail
-
-DRY_RUN=0
-
-usage() {
-  cat <<'EOF'
-Usage: ensure-agent-tools.sh [--dry-run]
-
-Installs or updates:
-  - grok   (Grok Build CLI) via https://x.ai/cli/install.sh
-  - quota-axi via volta (if present) or npm -g
-
-Then prints version + auth/quota smoke checks (no secrets).
-EOF
-}
-
-log() { printf '%s\n' "$*"; }
-err() { printf 'error: %s\n' "$*" >&2; }
-run() {
-  if [[ "$DRY_RUN" -eq 1 ]]; then
-    log "dry-run: $*"
-  else
-    "$@"
-  fi
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --dry-run) DRY_RUN=1; shift ;;
-    -h|--help|help) usage; exit 0 ;;
-    *) err "unknown argument: $1"; usage; exit 1 ;;
-  esac
-done
-
-ensure_path_hint() {
-  local need=0
-  case ":$PATH:" in
-    *":$HOME/.local/bin:"*) ;;
-    *) need=1; log "note: add \$HOME/.local/bin to PATH" ;;
-  esac
-  case ":$PATH:" in
-    *":$HOME/.grok/bin:"*) ;;
-    *) need=1; log "note: add \$HOME/.grok/bin to PATH (grok installer usually does)" ;;
-  esac
-  return 0
-}
-
-install_grok() {
-  if command -v grok >/dev/null 2>&1; then
-    log "grok present: $(grok --version 2>/dev/null || echo unknown)"
-    log "Updating grok via official installer…"
-  else
-    log "Installing grok via official installer…"
-  fi
-  if [[ "$DRY_RUN" -eq 1 ]]; then
-    log "dry-run: curl -fsSL https://x.ai/cli/install.sh | bash"
-    return 0
-  fi
-  curl -fsSL https://x.ai/cli/install.sh | bash
-}
-
-install_quota_axi() {
-  if command -v quota-axi >/dev/null 2>&1; then
-    log "quota-axi present: $(quota-axi --version 2>/dev/null || echo unknown)"
-  else
-    log "Installing quota-axi…"
-  fi
-  if command -v volta >/dev/null 2>&1; then
-    run volta install quota-axi
-  elif command -v npm >/dev/null 2>&1; then
-    run npm install -g quota-axi
-  else
-    err "Need volta or npm to install quota-axi"
-    return 1
-  fi
-}
-
-smoke() {
-  log ""
-  log "=== smoke checks ==="
-  if command -v grok >/dev/null 2>&1; then
-    log "grok: $(command -v grok)"
-    grok --version 2>&1 || true
-    if [[ -f "$HOME/.grok/auth.json" ]]; then
-      log "grok auth: ~/.grok/auth.json present"
-    else
-      log "grok auth: missing — run \`grok\` (browser) or set XAI_API_KEY"
-    fi
-  else
-    err "grok not on PATH after install"
-  fi
-
-  if command -v quota-axi >/dev/null 2>&1; then
-    log "quota-axi: $(command -v quota-axi)"
-    quota-axi auth 2>&1 || true
-    quota-axi --provider grok 2>&1 || true
-  else
-    err "quota-axi not on PATH after install"
-  fi
-
-  if ! command -v sqlite3 >/dev/null 2>&1; then
-    log "note: sqlite3 not found — Cursor quota via quota-axi may fail (install sqlite3)"
-  fi
-}
-
-ensure_path_hint
-install_grok
-install_quota_axi
-smoke
-log ""
-log "Done. Re-run anytime; pair with: ai-md install"