@drafthq/draft 3.2.0 → 3.3.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.2.0",
+      "version": "3.3.0",
       "author": {
         "name": "mayurpise"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "author": {
     "name": "mayurpise"
   },

package/.cursor-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "draft",
+  "displayName": "Draft",
+  "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
+  "version": "3.3.0",
+  "skills": "./skills/",
+  "agents": "./core/agents/",
+  "author": {
+    "name": "mayurpise"
+  },
+  "homepage": "https://github.com/drafthq/draft",
+  "license": "MIT",
+  "keywords": [
+    "context-driven-development",
+    "ai-assisted",
+    "planning",
+    "specifications",
+    "architecture",
+    "code-review",
+    "monorepo",
+    "tdd",
+    "validation",
+    "enterprise",
+    "incremental-refresh",
+    "signal-detection",
+    "state-management"
+  ]
+}

package/README.md

@@ -67,7 +67,7 @@ Each host installs the way that host actually loads extensions — no manual ste
 | Host | `draft install …` | What it does |
 |------|-------------------|--------------|
 | **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (user scope). Restart Claude Code. |
-| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/` (auto-loaded). Restart Cursor. |
+| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). |
 | **Codex** | `codex` | Writes `./AGENTS.md`, which Codex reads automatically. |
 | **opencode** | `opencode` | Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
 
@@ -92,7 +92,7 @@ Run `/draft` for the full command map.
 ```
 
 ### Cursor — from GitHub
-Cursor natively supports the `.claude-plugin/` structure. Add via *Settings > Rules, Skills, Subagents > Rules > New > Add from Github*:
+Cursor requires `.cursor-plugin/plugin.json`; the `draft install cursor` command also registers the plugin via the shared Claude plugin registry that Cursor reads on many builds. To add from source instead, use *Settings > Rules, Skills, Subagents > Rules > New > Add from Github*:
 ```
 https://github.com/drafthq/draft.git
 ```

package/cli/src/hosts/cursor.js

@@ -2,11 +2,15 @@
 
 const path = require('path');
 const { asset } = require('../lib/paths');
+const { readPluginVersion } = require('../lib/plugin-manifest');
+const { applyCursorRegistration } = require('../lib/cursor-registry');
 
-// Cursor natively understands the .claude-plugin structure. Install the same
-// native plugin tree, by default to the user-level plugin directory so it is
-// available across all projects.
+// Cursor discovers Draft through two layers, both shipped here: the native
+// .cursor-plugin/plugin.json manifest, and the shared Claude plugin registry
+// under ~/.claude/ (written in postInstall). A file copy alone is not enough —
+// current Cursor builds never surface /draft:* commands without registration.
 const ITEMS = [
+  { p: '.cursor-plugin', kind: 'copyTree' },
   { p: '.claude-plugin', kind: 'copyTree' },
   { p: 'skills', kind: 'copyTree' },
   { p: 'core', kind: 'copyTree' },
@@ -37,14 +41,40 @@ module.exports = {
       dest: path.join(base, it.p),
       label: it.p,
     }));
-    // Guard the whole install dir on the manifest's presence.
+    // Guard the whole install dir on the .cursor-plugin manifest's presence.
     actions[0].guard = true;
 
     return {
       targetSummary: `${base} (${ctx.scope})`,
       actions,
       graph: true,
-      done: `Draft installed to ${base}. Restart Cursor to detect the plugin.`,
+      // Runs after the file copies: register + enable the plugin in the shared
+      // Claude registry. On a dry run it computes the merges and writes nothing.
+      postInstall(c) {
+        const installedManifest = path.join(base, '.cursor-plugin', 'plugin.json');
+        const version = readPluginVersion(
+          c.dryRun ? asset('.cursor-plugin', 'plugin.json') : installedManifest
+        );
+        return applyCursorRegistration({
+          home: c.home,
+          installPath: base,
+          version,
+          scope: c.scope,
+          dryRun: c.dryRun,
+        });
+      },
+      done: [
+        `Draft installed to ${base}.`,
+        'Plugin registered and enabled in ~/.claude/plugins/.',
+        'Restart Cursor (Developer: Reload Window) to load /draft:* commands.',
+      ].join(' '),
+      fallbackTitle: 'If /draft commands do not appear after restart:',
+      fallback: [
+        `Confirm ${base}/.cursor-plugin/plugin.json exists`,
+        'Confirm ~/.claude/plugins/installed_plugins.json contains "draft@draft-plugins"',
+        'Confirm ~/.claude/settings.json has "draft@draft-plugins": true',
+        'Run Developer: Reload Window in Cursor',
+      ],
     };
   },
 };

package/cli/src/installer.js

@@ -4,6 +4,7 @@ const { spawnSync } = require('child_process');
 const fsx = require('./lib/fsx');
 const log = require('./lib/log');
 const { fetchGraph } = require('./lib/graph');
+const { writePluginRootMarker } = require('./lib/marker');
 
 // A short ceiling so a wedged `claude --version` can't hang the installer
 // before we even reach the real (separately-timed) install steps.
@@ -107,6 +108,25 @@ function install(host, ctx) {
     fetchGraph(ctx);
   }
 
+  // Host-specific registration (e.g. Cursor's plugin registry). On a real
+  // install the hook performs the writes (logging each path); on a dry run it
+  // returns the planned paths so we can surface them without touching disk.
+  if (plan.postInstall) {
+    const reg = plan.postInstall(ctx);
+    if (reg && ctx.dryRun) {
+      log.plan(`would update registry: ${reg.kmPath}`);
+      log.plan(`would update registry: ${reg.ipPath}`);
+      log.plan(`would update registry: ${reg.settingsPath}`);
+    }
+  }
+
+  // Record the install path so skills can locate scripts/tools/ from the user's
+  // project cwd (best-effort; graph skills glob-fallback if the marker is absent).
+  if (!ctx.dryRun) {
+    const root = writePluginRootMarker(host.id);
+    if (root) log.note(`Recorded plugin path for graph tooling: ${root}`);
+  }
+
   (plan.notes || []).forEach((n) => log.note(n));
 
   if (ctx.dryRun) {

package/cli/src/lib/cursor-registry.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// Cursor reads plugins from the shared Claude plugin registry under ~/.claude/
+// on many builds, so a file copy alone never surfaces /draft:* commands. This
+// module merges Draft into the three registry files non-destructively:
+//   - ~/.claude/plugins/known_marketplaces.json   (marketplace entry)
+//   - ~/.claude/plugins/installed_plugins.json     (install record)
+//   - ~/.claude/settings.json                       (enabledPlugins flag)
+// Every write preserves all other plugins, hooks, and unknown keys. Reads of a
+// corrupt JSON file fail loud rather than silently clobbering user data.
+const fs = require('fs');
+const path = require('path');
+const log = require('./log');
+
+const MARKETPLACE_KEY = 'draft-plugins';
+const PLUGIN_KEY = `draft@${MARKETPLACE_KEY}`; // name@<marketplace name>
+
+function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return fallback;
+    throw new Error(`Cannot parse ${filePath}: ${err.message}`);
+  }
+}
+
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+function claudeHome(home) {
+  return path.join(home, '.claude');
+}
+
+function registryPaths(home) {
+  const base = path.join(claudeHome(home), 'plugins');
+  return {
+    kmPath: path.join(base, 'known_marketplaces.json'),
+    ipPath: path.join(base, 'installed_plugins.json'),
+    settingsPath: path.join(claudeHome(home), 'settings.json'),
+  };
+}
+
+function registryScope(scope) {
+  return scope === 'project' ? 'project' : 'user';
+}
+
+// Pure: compute the merged registry objects without touching disk. Callers that
+// want to persist them use applyCursorRegistration (which delegates here first).
+function registerCursorPlugin(opts) {
+  const { home, version, scope } = opts;
+  const installPath = path.resolve(opts.installPath);
+  const now = new Date().toISOString();
+  const paths = registryPaths(home);
+
+  // --- known_marketplaces.json: overwrite only our key. ---
+  const km = readJson(paths.kmPath, {});
+  km[MARKETPLACE_KEY] = {
+    source: { source: 'directory', path: installPath },
+    installLocation: installPath,
+    lastUpdated: now,
+  };
+
+  // --- installed_plugins.json: merge our key, preserve installedAt on upgrade. ---
+  const ip = readJson(paths.ipPath, { version: 2, plugins: {} });
+  if (typeof ip.version !== 'number') ip.version = 2;
+  if (!ip.plugins || typeof ip.plugins !== 'object') ip.plugins = {};
+  const existing = Array.isArray(ip.plugins[PLUGIN_KEY]) ? ip.plugins[PLUGIN_KEY][0] : null;
+  const installedAt = existing && existing.installedAt ? existing.installedAt : now;
+  ip.plugins[PLUGIN_KEY] = [
+    {
+      scope: registryScope(scope),
+      installPath,
+      version,
+      installedAt,
+      lastUpdated: now,
+    },
+  ];
+
+  // --- settings.json: flip our enabledPlugins flag, preserve everything else. ---
+  const settings = readJson(paths.settingsPath, {});
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+    settings.enabledPlugins = {};
+  }
+  settings.enabledPlugins[PLUGIN_KEY] = true;
+
+  return {
+    kmPath: paths.kmPath,
+    km,
+    ipPath: paths.ipPath,
+    ip,
+    settingsPath: paths.settingsPath,
+    settings,
+  };
+}
+
+// Compute the merges and, unless dryRun, persist them atomically. Returns the
+// same shape as registerCursorPlugin so the installer can log the paths.
+function applyCursorRegistration(opts) {
+  const result = registerCursorPlugin(opts);
+  if (opts.dryRun) return result;
+
+  log.plan(`writing: ${result.kmPath}`);
+  writeJsonAtomic(result.kmPath, result.km);
+  log.plan(`writing: ${result.ipPath}`);
+  writeJsonAtomic(result.ipPath, result.ip);
+  log.plan(`writing: ${result.settingsPath}`);
+  writeJsonAtomic(result.settingsPath, result.settings);
+
+  return result;
+}
+
+module.exports = {
+  PLUGIN_KEY,
+  MARKETPLACE_KEY,
+  registerCursorPlugin,
+  applyCursorRegistration,
+};

package/cli/src/lib/marker.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// Write the install-path marker (~/.cache/draft/plugin-root) so a draft skill can
+// locate its bundled scripts/tools/ from the user's project cwd. Skills run with
+// cwd = the user's project and ${CLAUDE_PLUGIN_ROOT} is NOT exported into skill Bash,
+// so without this marker resolution falls back to globbing the plugin cache. The
+// marker is the fast, authoritative path; see core/shared/tool-resolver.md.
+//
+// Best-effort: any failure is swallowed — graph skills still resolve via the glob
+// fallback, so a missing marker is never fatal.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Resolve the installed draft plugin root for a given host, or null if unknown.
+function resolvePluginRoot(hostId) {
+  const home = os.homedir();
+
+  if (hostId === 'claude-code') {
+    // 1. Claude Code's own registry holds the authoritative installPath.
+    const reg = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+    try {
+      const data = JSON.parse(fs.readFileSync(reg, 'utf8'));
+      const key = Object.keys(data.plugins || {}).find((k) => k.startsWith('draft@'));
+      const ip = key && data.plugins[key] && data.plugins[key][0] && data.plugins[key][0].installPath;
+      if (ip && fs.existsSync(path.join(ip, 'scripts', 'tools'))) return ip;
+    } catch {
+      /* registry missing or unparseable — fall through to the cache scan */
+    }
+    // 2. Fallback: newest versioned dir under the plugin cache.
+    return newestCacheRoot(path.join(home, '.claude', 'plugins', 'cache'));
+  }
+
+  if (hostId === 'cursor') {
+    const p = path.join(home, '.cursor', 'plugins', 'local', 'draft');
+    return fs.existsSync(path.join(p, 'scripts', 'tools')) ? p : null;
+  }
+
+  return null;
+}
+
+// Newest <cache>/<marketplace>/draft/<version> dir that carries scripts/tools.
+function newestCacheRoot(cacheDir) {
+  try {
+    const candidates = [];
+    for (const mkt of fs.readdirSync(cacheDir)) {
+      const draftDir = path.join(cacheDir, mkt, 'draft');
+      let versions;
+      try {
+        versions = fs.readdirSync(draftDir);
+      } catch {
+        continue;
+      }
+      for (const v of versions) {
+        const root = path.join(draftDir, v);
+        if (fs.existsSync(path.join(root, 'scripts', 'tools'))) candidates.push({ v, root });
+      }
+    }
+    if (!candidates.length) return null;
+    candidates.sort((a, b) => compareVersions(a.v, b.v));
+    return candidates[candidates.length - 1].root;
+  } catch {
+    return null;
+  }
+}
+
+// Numeric-aware version compare (no semver dependency).
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+// Write ~/.cache/draft/plugin-root for the host. Returns the path written, or null.
+function writePluginRootMarker(hostId) {
+  try {
+    const root = resolvePluginRoot(hostId);
+    if (!root) return null;
+    const dest = path.join(os.homedir(), '.cache', 'draft', 'plugin-root');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, root + '\n');
+    return root;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { writePluginRootMarker, resolvePluginRoot };

package/cli/src/lib/plugin-manifest.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// Read name/version from a plugin manifest JSON (.cursor-plugin/plugin.json or
+// .claude-plugin/plugin.json). Fails loud if either required field is missing —
+// a manifest without a version would corrupt the registry's install record.
+const fs = require('fs');
+
+function readPluginManifest(manifestPath) {
+  const raw = fs.readFileSync(manifestPath, 'utf8');
+  const data = JSON.parse(raw);
+  if (!data.name) throw new Error(`Missing name in ${manifestPath}`);
+  if (!data.version) throw new Error(`Missing version in ${manifestPath}`);
+  return data;
+}
+
+function readPluginVersion(manifestPath) {
+  return readPluginManifest(manifestPath).version;
+}
+
+module.exports = { readPluginManifest, readPluginVersion };

package/core/methodology.md

@@ -300,7 +300,7 @@ You should see the list of available Draft commands. If not, check that the plug
 
 ### Supported Platforms
 
-Draft works with **Claude Code** (native `.claude-plugin/` support) and **Cursor** (supports `.claude/` plugin structure natively). No build pipeline required.
+Draft works with **Claude Code** (native `.claude-plugin/` support) and **Cursor** (requires `.cursor-plugin/plugin.json` plus registration in the shared Claude plugin registry, both handled by `draft install cursor`). No build pipeline required.
 
 ---
 

package/core/shared/condensation.md

@@ -180,8 +180,9 @@ Write the completed content to `draft/.ai-context.md`.
 After writing both output files, strip trailing whitespace and blank lines at EOF to prevent GitHub upload failures. Resolve the script via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 [ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" draft/architecture.md draft/.ai-context.md draft/.ai-profile.md 2>/dev/null || true
 ```

package/core/shared/git-report-metadata.md

@@ -16,8 +16,9 @@ Referenced by: All skills that generate Draft reports — including `/draft:bugh
 Use `git-metadata.sh` from the plugin install, resolved via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 bash "$DRAFT_TOOLS/git-metadata.sh" --yaml \
     --project "$PROJECT" --module "$MODULE" \

package/core/shared/graph-query.md

@@ -92,11 +92,12 @@ These fields are appended to `~/.draft/metrics.jsonl` along with the existing sk
 
 ## Tooling Wrappers
 
-For common query modes, prefer the deterministic wrappers that ship with the plugin. Resolve their location via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)) before invoking:
+For common query modes, prefer the deterministic wrappers that ship with the plugin. Resolve their location via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)) before invoking. Skills run with cwd = the user's project and `${CLAUDE_PLUGIN_ROOT}` is **not** exported into skill Bash, so a bare `scripts/tools/foo.sh` fails — establish `DRAFT_TOOLS` once before the first helper call, in the same Bash session as your tool calls (re-establish it if you split helper calls into a separate, later Bash block):
 
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 ```
 

package/core/shared/tool-resolver.md

@@ -1,10 +1,77 @@
 ---
 shared: tool-resolver
-applies_to: quality + init + graph skills
+applies_to: every skill that invokes scripts/tools/*
 ---
 
-# tool-resolver (Foundations Stub)
+# tool-resolver
 
-Portable generalized stub per manifest §2.1. Full content will be expanded in later agent tranche or manual follow-up.
+Canonical procedure for locating Draft's bundled shell helpers (`scripts/tools/*.sh`)
+from inside a skill.
 
-See verification-gates.md and template-hygiene.md for usage contracts.
+## Why this exists
+
+When Claude runs a draft skill, the shell's **working directory is the user's
+project**, not the plugin. The helpers live inside the plugin install directory,
+which on a marketplace/npm install is `~/.claude/plugins/cache/<marketplace>/draft/<version>/`
+— never the cwd. `${CLAUDE_PLUGIN_ROOT}` is **not** exported into skill-driven Bash
+(it is only set for hooks, MCP/LSP servers, and monitor commands), so a bare
+`scripts/tools/foo.sh` or `${CLAUDE_PLUGIN_ROOT}/...` invocation silently fails.
+
+Every skill MUST resolve `DRAFT_TOOLS` and invoke helpers as `"$DRAFT_TOOLS/<tool>.sh"`.
+
+## Resolution order
+
+`DRAFT_TOOLS` resolves to the first directory that exists, in this order:
+
+1. `${DRAFT_PLUGIN_ROOT}/scripts/tools` — explicit override (testing / pinned installs)
+2. `$(cat ~/.cache/draft/plugin-root)/scripts/tools` — install marker written by `draft install` (authoritative)
+3. `${CLAUDE_PLUGIN_ROOT}/scripts/tools` — set in hook/MCP contexts; harmless to probe
+4. `installed_plugins.json → installPath` for `draft@*` — Claude Code's own registry (needs `jq`)
+5. `~/.claude/plugins/cache/*/draft/*/scripts/tools` — newest cache install (glob, `sort -V`)
+6. `~/.claude/plugins/marketplaces/*draft*/scripts/tools` — marketplace clone
+7. `~/.cursor/plugins/local/draft/scripts/tools` — Cursor local install
+8. `$PWD/scripts/tools` — dev / dogfooding (running inside the draft repo itself)
+
+The marker (step 2) is the fast, authoritative path; steps 5–6 are the glob fallback
+that keeps resolution working on installs predating the marker (no reinstall required).
+
+## Skill preamble (copy verbatim)
+
+Establish `DRAFT_TOOLS` once, before the first helper call, in the **same Bash
+session** that runs your tool calls — exactly as skills already define `REPO_ABS`
+once and reuse it. Env vars do not persist across **separate** Bash tool
+invocations (only the cwd does), so if you split helper calls into a later, separate
+Bash block, re-establish `DRAFT_TOOLS` there too:
+
+```bash
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
+Then invoke helpers through the variable:
+
+```bash
+"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 5
+"$DRAFT_TOOLS/graph-arch.sh"   --repo .
+```
+
+The four-line inline preamble is self-contained and is the recommended form for
+skills — it needs no marker file and no prior `source`. The full 8-step resolver
+(adding the `${DRAFT_PLUGIN_ROOT}` override, `${CLAUDE_PLUGIN_ROOT}`, the jq-registry
+lookup, and the Cursor path) is shipped as `scripts/tools/resolve-tools.sh` for tests
+and for callers that prefer a single source of truth:
+
+```bash
+DRAFT_TOOLS="$("$PWD/scripts/tools/resolve-tools.sh" 2>/dev/null)"   # dev/dogfood
+# installed: "$(cat ~/.cache/draft/plugin-root)/scripts/tools/resolve-tools.sh"
+```
+
+## The engine binary is separate
+
+`DRAFT_TOOLS` locates the **wrapper scripts**. Each wrapper then resolves the
+`codebase-memory-mcp` **engine binary** itself via `_lib.sh:find_memory_bin`
+(`DRAFT_MEMORY_BIN` → `$PATH` → `~/.cache/draft/bin/` → vendored). Do not conflate
+the two: a wrapper that runs but reports `source: unavailable` means the engine
+binary is missing, not the wrapper.

package/core/templates/okf/ai-context-index.md

@@ -0,0 +1,48 @@
+---
+project: "{PROJECT_NAME}"
+module: "{MODULE_NAME or 'root'}"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+draft_init_mode: okf
+---
+
+# {PROJECT_NAME} — AI Context Index
+
+> Index root for the OKF taxonomy bundle (`wiki/`). Read **Synopsis** for broad
+> tasks (they usually terminate here). For focused tasks, route through the
+> **Concept Map** to ≤N concept pages — each lists `x-grounded-paths`. This is
+> both the cheap broad-context path AND the progressive-disclosure entry point.
+
+## Synopsis
+
+<!-- 150–250 lines: the cheap broad-context path (prior .ai-context.md value
+     preserved). Architecture in brief, key invariants, where to start, top
+     hotspots. A broad task should be answerable from this section alone. -->
+
+- **Architecture in brief:** {2–4 sentences}
+- **Key invariants:** {bullet list, provenance-tagged}
+- **Where to start:** {entrypoints + core subsystems}
+- **Top hotspots:** {from hotspot-rank.sh — symbol, fan-in}
+
+## Concept Map
+
+<!-- Routing table built from each concept's frontmatter `description`.
+     Open a section index for the full per-concept list. -->
+
+| Section | Routing |
+|---------|---------|
+| `wiki/systems/` | {one-line per subsystem — what it owns, when to open} |
+| `wiki/features/` | {one-line per feature} |
+| `wiki/reference/` | config, schemas, APIs, ADRs, runbooks |
+| `wiki/entrypoints/` | binaries / CLIs / handler roots |
+
+Full taxonomy: [wiki/index.md](wiki/index.md).
+
+## How to navigate
+
+1. **Broad task** (summarize, "what owns X", topology) → answer from **Synopsis**.
+2. **Focused task** ("what breaks if I change Y", "add a field to Z") → open the
+   matching concept via the **Concept Map**; follow its `x-grounded-paths` and
+   `Used by` cross-links. Do not read the whole bundle.
+3. Every concept page is verified against the live call graph; trust its
+   `Blast radius` section over re-deriving by hand.

package/core/templates/okf/concept.md

@@ -0,0 +1,54 @@
+---
+type: Subsystem                    # required (OKF) — one of the frozen vocab below
+title: "{CONCEPT_TITLE}"           # OKF
+description: >                     # OKF — LOAD-BEARING: the agent's routing key.
+  Write this as a ROUTING DECISION, not a summary. It must answer
+  "should the agent open this file for the task at hand?" from the index
+  alone. Name the responsibilities and the words a task would use.
+resource: "{CANONICAL_SOURCE_PATH}"   # OKF — canonical source path(s)
+tags: [tag1, tag2]                 # OKF
+timestamp: "{ISO_TIMESTAMP}"       # OKF — last regeneration
+# Draft extensions (ignored by generic OKF consumers; namespaced x-):
+x-grounded-paths: ["{path/a}", "{path/b}"]   # exact source files this page grounds
+x-hotspot-score: 0.0                          # from hotspot-rank.sh (0..1)
+x-callers: ["{module/a}", "{module/b}"]       # from graph-callers.sh
+---
+
+# {CONCEPT_TITLE}
+
+<!--
+Frozen `type` vocabulary (changing it churns every file — versioned via
+index.md: okf_types_version):
+  Subsystem  — major graph cluster / package boundary        → systems/
+  Module     — single package/dir with cohesive responsibility → systems/
+  Feature    — user-facing capability spanning modules         → features/
+  Entrypoint — binary / main / CLI / handler root              → entrypoints/
+  API        — public interface, route group, RPC surface      → reference/
+  DataModel  — schema, table, core struct/type                 → reference/
+  Dependency — notable external dep + how it's used            → reference/
+  ADR        — architecture decision record                    → reference/
+  Runbook    — operational procedure                           → reference/
+-->
+
+## What it is
+
+One paragraph: the concept's responsibility and boundary. Graph-grounded.
+
+## How it works
+
+Primary control/data flow. At least one Mermaid diagram for a significant
+concept (workflow, state, or sequence). Grounded in the call graph.
+
+## Used by
+
+Cross-links to callers (from `x-callers`). Each link is a relative path to
+another concept page so `okf-validate.sh` can resolve it.
+
+## Blast radius
+
+What breaks if this changes (from `graph-impact.sh`). Lists `x-grounded-paths`
+so a focused task knows exactly which source files to open.
+
+## See also
+
+- [Related concept](../systems/other.md)