trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/claude/settings-merge.js

@@ -0,0 +1,283 @@
+import { isGraftEntry } from '../hosts/config-write.js';
+const slCmd = (name = 'graft') => `node "\${CLAUDE_PROJECT_DIR:-.}/.claude/helpers/${name}-statusline.cjs"`;
+/** trail's status line, from the shim in `.trail/` (see claude/init.ts). */
+const TRAIL_SL_CMD = 'node "${CLAUDE_PROJECT_DIR:-.}/.trail/statusline.cjs"';
+/** Stable marker for "this statusLine is Graft's", not the full command string —
+ * an older shim path or a GRAFT_DIR wrapper still names this file. Either name. */
+const STATUSLINE_HELPER = /(graft|trail)-statusline\.cjs|\.trail\/statusline\.cjs/;
+const FOOTER = 'graft/[\\w./-]+\\.md';
+// Every form graft is actually invoked as. 'graft:*' covers a global install;
+// the other two cover a repo working on graft itself (or any consumer running it
+// from a checkout), where the binary is not on PATH under that name. A retrieval
+// call that raises a permission prompt loses to grep, which never does.
+const ALLOW_ENTRIES = [
+    'Bash(trail:*)',
+    'Bash(graft:*)',
+    'Bash(npx graft:*)',
+    'Bash(graft-dev:*)',
+    'Bash(node dist/cli.js:*)',
+];
+/** Where the repo-level install's shims sit, relative to whatever project is open. */
+const REPO_HELPERS = '${CLAUDE_PROJECT_DIR:-.}/.claude/helpers';
+/**
+ * `helpers` is the directory holding `graft-hooks.cjs`, and it is a parameter for
+ * one reason: the user-level install (see hosts/claude-global.ts) has to name an
+ * absolute path. A `${CLAUDE_PROJECT_DIR}` command works only where a previous
+ * `graft init` wrote a shim into that project — which is exactly the case the
+ * global copy exists to cover, so it cannot reuse the repo form.
+ */
+function hookCmd(arg, helpers = REPO_HELPERS, name = 'graft') {
+    return `node "${helpers}/${name}-hooks.cjs" ${arg}`;
+}
+/**
+ * A hook command that exits 0 whatever happens to it (every event since D116 item 6; PreToolUse first, for this). Copilot CLI reads
+ * the repo's `.claude/settings.json` and denies the tool call when a
+ * PreToolUse hook exits non-zero, so a shim that can't be found (a host
+ * started in a subfolder without CLAUDE_PROJECT_DIR, the shim gone after an
+ * uninstall) or a missing node would deny every shell command. `|| exit 0`
+ * means the same in sh and Windows cmd. The hook's answer travels as JSON on
+ * stdout, never as an exit code, so nothing is lost by it.
+ */
+export function failOpen(command) {
+    return `${command} || exit 0`;
+}
+/** trail's committed hook, `.trail/hook.cjs`, run for one event. */
+export function trailHookCmd(arg) {
+    return `node "\${CLAUDE_PROJECT_DIR:-.}/.trail/hook.cjs" ${arg}`;
+}
+function graftBlocks(helpers, name = 'graft') {
+    return hookBlocks((arg) => hookCmd(arg, helpers, name));
+}
+/**
+ * Every hook event, each running `command(<event arg>)`.
+ *
+ * Every `timeout` here is in seconds: Claude Code and Codex read it that way.
+ * Versions before 0.23 wrote 8000-15000 meaning milliseconds, which the host
+ * read as hours; merging again replaces them. The prompt hook also keeps to a
+ * hard budget of its own (prompt-hook.ts PROMPT_BUDGET_MS), well inside this.
+ */
+function hookBlocks(command) {
+    // D116 item 6: every event fails open, not only PreToolUse: a `git stash -u` or `git clean` before the wiring is
+    // committed takes the untracked shim while settings.json still names it, and a missing shim must stay quiet.
+    const hookCmd_ = (arg) => failOpen(command(arg));
+    return {
+        PostToolUse: [
+            { matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: hookCmd_('post-edit'), timeout: 10 }] },
+            // Score the usage mix and sum token savings. A graft retrieval (CLI `graft …`
+            // via Bash, or the `graft_*` MCP tools) prints a `[graft] tokens saved ≈ N`
+            // footer this hook sums into the session total; the same hook classifies
+            // Read/Grep/Glob as source reads vs graft as graft reads, which is what feeds
+            // `graft stats` and the `session_summary` graft-vs-grep ratio. Broad matcher,
+            // but the handler no-ops instantly unless there is something to record, so an
+            // unrelated Bash or a plain Read costs only a stdin read. `Skill` is the
+            // agent using a skill: one of the repo's goes to the workspace as a run.
+            { matcher: 'Bash|mcp__graft__|mcp__trail__|Read|Grep|Glob|Skill', hooks: [{ type: 'command', command: hookCmd_('tool-savings'), timeout: 8 }] },
+        ],
+        // Longer than the other hooks: its `graft ask` is a real query, and a query
+        // brings the graph up to date first (graph/refresh.ts). The hook itself
+        // stops at its own total budget (PROMPT_BUDGET_MS) and reads this number
+        // back (promptAskTimeout) so its ask child always fits inside it.
+        UserPromptSubmit: [{ hooks: [{ type: 'command', command: hookCmd_('prompt'), timeout: 15 }] }],
+        // Before every shell command: pre-bash.js, which fails open, behind a
+        // command that fails open too (see failOpen). Claude Code reads `timeout`
+        // in seconds, so 5 caps the wait a wedged hook could add to one command,
+        // after which the command runs anyway.
+        PreToolUse: [
+            // The learnings on a file, before the agent changes it: while they can still change the edit.
+            { matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: hookCmd_('pre-edit'), timeout: 5 }] },
+            { matcher: 'Bash', hooks: [{ type: 'command', command: hookCmd_('pre-bash'), timeout: 5 }] },
+        ],
+        // A Bash call that failed fires this, never PostToolUse (D34): learned
+        // skills mark the outcome for the next catch-up. Fails open like
+        // PreToolUse, since some hosts read a non-zero exit as a refusal.
+        PostToolUseFailure: [{ matcher: 'Bash', hooks: [{ type: 'command', command: hookCmd_('post-bash-fail'), timeout: 5 }] }],
+        SessionStart: [{ hooks: [{ type: 'command', command: hookCmd_('session-start'), timeout: 10 }] }],
+        Stop: [{ hooks: [{ type: 'command', command: hookCmd_('stop'), timeout: 10 }] }],
+        // Sends the telemetry queue in a detached child, so closing Claude isn't
+        // slowed. Not fired when the terminal is killed; session start sends what's left.
+        SessionEnd: [{ hooks: [{ type: 'command', command: hookCmd_('session-end'), timeout: 5 }] }],
+    };
+}
+/**
+ * Is this allowlist entry one graft wrote?
+ *
+ * Scoped to the forms graft is actually invoked as — NOT any rule mentioning
+ * "graft". A user who allowlists their own `Bash(graft-mytool:*)` keeps it; only
+ * graft's own set is replaced, which is what lets a renamed entry disappear on
+ * upgrade instead of accumulating beside its replacement.
+ */
+export function isGraftAllowEntry(entry) {
+    return /^Bash\((?:trail|graft|npx graft|graft-dev|node dist\/cli\.js)(?::|\))/.test(String(entry));
+}
+/** Is this footer regex graft's? It points at the card tree, which is graft's alone. */
+export function isGraftFooterRegex(re) {
+    return String(re).includes('graft/');
+}
+function envNoStatusline() {
+    const v = process.env.GRAFT_NO_STATUSLINE;
+    return v !== undefined && v !== '' && v !== '0' && v !== 'false';
+}
+/** True when init should write (or refresh) Graft's Claude Code statusLine. */
+export function statuslineWanted(opts = {}) {
+    return opts.statusline !== false && !envNoStatusline();
+}
+function isGraftStatusline(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const command = value.command;
+    return typeof command === 'string' && STATUSLINE_HELPER.test(command);
+}
+function applyStatusline(merged, key, warnings, wanted, foreignWarning, name = 'graft') {
+    const current = merged[key];
+    const ours = isGraftStatusline(current);
+    if (!wanted) {
+        if (!current || ours)
+            delete merged[key];
+        else
+            warnings.push(foreignWarning);
+        return;
+    }
+    if (!current || ours) {
+        merged[key] = { type: 'command', command: slCmd(name) };
+        return;
+    }
+    warnings.push(foreignWarning);
+}
+export function mergeGraftSettings(existing, opts = {}) {
+    const merged = { ...(existing ?? {}) };
+    const name = opts.name ?? 'graft';
+    const warnings = [];
+    const wanted = statuslineWanted(opts);
+    applyStatusline(merged, 'statusLine', warnings, wanted, `Existing statusLine left untouched (a session allows only one). To use ${name === 'trail' ? 'Trail' : 'Graft'}, point it at .claude/helpers/${name}-statusline.cjs.`, name);
+    applyStatusline(merged, 'subagentStatusLine', warnings, wanted, 'Existing subagentStatusLine left untouched.', name);
+    merged.hooks = { ...(merged.hooks ?? {}) };
+    for (const [event, blocks] of Object.entries(graftBlocks(undefined, name))) {
+        const prior = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+        const foreign = prior.filter((e) => !isGraftEntry(e)); // drop old Graft entries → idempotent
+        merged.hooks[event] = [...foreign, ...blocks];
+    }
+    // Drop graft's own prior regex before re-adding, so a change to FOOTER replaces
+    // the old pattern instead of stacking beside it. The user's regexes are kept.
+    const priorFooter = Array.isArray(merged.footerLinksRegexes) ? merged.footerLinksRegexes : [];
+    merged.footerLinksRegexes = [...priorFooter.filter((r) => !isGraftFooterRegex(r)), FOOTER];
+    // headless/subagent runs hard-deny Bash by default; without an allowlist entry
+    // `graft ask`'s own Bash calls (and the skill it installs) can't run out-of-box.
+    // Same shape as the hooks merge above: drop graft's prior entries, then add the
+    // current set. Append-only left a renamed invocation form in the user's settings
+    // forever, with nothing able to remove it.
+    merged.permissions = { ...(merged.permissions ?? {}) };
+    const priorAllow = Array.isArray(merged.permissions.allow) ? merged.permissions.allow : [];
+    merged.permissions.allow = [...priorAllow.filter((e) => !isGraftAllowEntry(e)), ...ALLOW_ENTRIES];
+    return { merged, warnings };
+}
+/**
+ * The hook blocks alone, merged into a settings file, with the shims addressed by
+ * absolute path — `~/.claude/settings.json`, where a write reaches every project on
+ * the machine (see hosts/claude-global.ts for why that copy has to exist).
+ *
+ * Hooks only, deliberately. `mergeGraftSettings` also claims the statusline, the
+ * footer regex and a Bash allowlist, and each of those is a reasonable thing to
+ * accept for a repo you ran `graft init` in and an unreasonable thing to impose on
+ * every repo you ever open — a statusline especially, since a session allows exactly
+ * one and taking it globally would silently outrank the user's own. The hooks are the
+ * piece that has to be global, because they are what a worktree loses.
+ *
+ * Same idempotent shape as the repo merge: graft's prior entries are dropped before
+ * the current set is added, so re-running converges instead of stacking.
+ */
+export function mergeGraftHooks(existing, helpers) {
+    const merged = { ...(existing ?? {}) };
+    merged.hooks = { ...(merged.hooks ?? {}) };
+    for (const [event, blocks] of Object.entries(graftBlocks(helpers))) {
+        const prior = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+        const foreign = prior.filter((e) => !isGraftEntry(e));
+        merged.hooks[event] = [...foreign, ...blocks];
+    }
+    return { merged };
+}
+/** Drop every fragment graft or trail wrote from a settings object, keeping the user's. */
+function withoutOurs(existing) {
+    const merged = { ...(existing ?? {}) };
+    for (const key of ['statusLine', 'subagentStatusLine'])
+        if (isGraftStatusline(merged[key]))
+            delete merged[key];
+    if (merged.hooks && typeof merged.hooks === 'object' && !Array.isArray(merged.hooks)) {
+        const hooks = {};
+        for (const [event, prior] of Object.entries(merged.hooks)) {
+            const kept = Array.isArray(prior) ? prior.filter((e) => !isGraftEntry(e)) : prior;
+            if (!Array.isArray(kept) || kept.length)
+                hooks[event] = kept;
+        }
+        if (Object.keys(hooks).length)
+            merged.hooks = hooks;
+        else
+            delete merged.hooks;
+    }
+    if (Array.isArray(merged.footerLinksRegexes)) {
+        const kept = merged.footerLinksRegexes.filter((r) => !isGraftFooterRegex(r));
+        if (kept.length)
+            merged.footerLinksRegexes = kept;
+        else
+            delete merged.footerLinksRegexes;
+    }
+    if (merged.permissions && typeof merged.permissions === 'object' && Array.isArray(merged.permissions.allow)) {
+        const allow = merged.permissions.allow.filter((e) => !isGraftAllowEntry(e));
+        const permissions = { ...merged.permissions };
+        if (allow.length)
+            permissions.allow = allow;
+        else
+            delete permissions.allow;
+        if (Object.keys(permissions).length)
+            merged.permissions = permissions;
+        else
+            delete merged.permissions;
+    }
+    return merged;
+}
+/**
+ * trail's part of the committed `.claude/settings.json`: one SessionStart entry
+ * running `.trail/hook.cjs`, and nothing else. For a teammate without trail it
+ * shows the learnings and offers trail; with trail it hands off to the install.
+ * Anything an older init put here (status line, the other hooks, allowlist,
+ * footer regex) comes out, so the file a team commits is the same on every machine.
+ */
+export function mergeTrailShared(existing) {
+    const merged = withoutOurs(existing);
+    merged.hooks = { ...(merged.hooks ?? {}) };
+    merged.hooks.SessionStart = [
+        ...(Array.isArray(merged.hooks.SessionStart) ? merged.hooks.SessionStart : []),
+        ...hookBlocks(trailHookCmd).SessionStart,
+    ];
+    return merged;
+}
+/**
+ * trail's part of `.claude/settings.local.json`, the person's own: the status
+ * line, the footer regex and the allowlist, plus, when `~/.claude` doesn't carry
+ * them (`--no-global`), the hooks for every event but session start, which the
+ * shared file already runs once.
+ */
+export function mergeTrailLocal(existing, opts = {}) {
+    const merged = withoutOurs(existing);
+    const warnings = [];
+    if (statuslineWanted(opts)) {
+        for (const key of ['statusLine', 'subagentStatusLine']) {
+            if (!merged[key])
+                merged[key] = { type: 'command', command: TRAIL_SL_CMD };
+            else if (key === 'statusLine')
+                warnings.push('Existing statusLine left untouched (a session allows only one). To use Trail, point it at .trail/statusline.cjs.');
+        }
+    }
+    if (opts.hooks) {
+        merged.hooks = { ...(merged.hooks ?? {}) };
+        for (const [event, blocks] of Object.entries(hookBlocks(trailHookCmd))) {
+            if (event === 'SessionStart')
+                continue;
+            merged.hooks[event] = [...(Array.isArray(merged.hooks[event]) ? merged.hooks[event] : []), ...blocks];
+        }
+    }
+    merged.footerLinksRegexes = [...(merged.footerLinksRegexes ?? []), FOOTER];
+    merged.permissions = { ...(merged.permissions ?? {}) };
+    merged.permissions.allow = [...(merged.permissions.allow ?? []), ...ALLOW_ENTRIES];
+    return { merged, warnings };
+}
+//# sourceMappingURL=settings-merge.js.map

package/dist/claude/settings-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-merge.js","sourceRoot":"","sources":["../../src/claude/settings-merge.ts"],"names":[],"mappings":"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"}

package/dist/claude/skill-template.d.ts

@@ -0,0 +1,13 @@
+import { type Brand } from "../brand.js";
+export declare function skillTemplate(brand?: Brand): string;
+/**
+ * Agent-facing graft text in trail's spelling, for every file trail writes
+ * for an agent: the commands as trail spells them (`graft stats` is
+ * `trail status`, and the freshness gate is `trail build --check`, see `cmd`),
+ * and the name in prose. Under trail the
+ * code map is in `.trail/cache/` (context/map-dir.ts), so the folder's name
+ * changes too; any other `graft` followed by `/` stays, as do `graft-…`
+ * names. `graft_…` MCP tool names ARE replaced — the fork exposes them as `trail_*`.
+ */
+export declare function trailSpelling(text: string): string;
+//# sourceMappingURL=skill-template.d.ts.map

package/dist/claude/skill-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-template.d.ts","sourceRoot":"","sources":["../../src/claude/skill-template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAc9C,wBAAgB,aAAa,CAAC,KAAK,GAAE,KAAe,GAAG,MAAM,CAE5D;AAuFD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUlD"}

package/dist/claude/skill-template.js

@@ -0,0 +1,290 @@
+import { cmd } from "../brand.js";
+// The graft Claude Code skill, bundled as a string so `graft init` can write it into a
+// consumer repo's .claude/skills/graft/SKILL.md (no network fetch, version-locked to the
+// installed graft). This is the single source of truth for the skill text; graft's own
+// repo copy is regenerated from here when `init` runs in this repo. Mirrors the `.cjs`
+// shim pattern in shim-template.ts.
+//
+// `brand` is the repo's name for the tool, not the machine's: a repo wired by
+// `trail init` gets the trail text, whoever refreshes it, so teammates on graft
+// and trail never flip the committed file back and forth.
+//
+// trail-solo-grafo: the skill describes the code map only. The learnings, skills
+// and pre-review sections are gone with the layers they documented, so every
+// command and tool named below exists in the binary.
+export function skillTemplate(brand = "graft") {
+    return brand === "trail" ? trailSkill(graftSkill()) : graftSkill();
+}
+/**
+ * When Claude Code loads the trail skill. It reads only the description up
+ * front and opens the body when the description fits the moment, so the
+ * description names the moments a trail command belongs to, not just code
+ * search. It's also the one line every teammate's Claude sees in a repo where
+ * trail is wired, installed or not, so it says how to get the command. A plain
+ * YAML scalar: no ": " and no " #".
+ */
+const TRAIL_DESCRIPTION = `Use for ANY task in this repo. Run trail ask before grepping or reading
+  source: it returns ranked nodes with exact file:line spans, plus the call
+  graph, a semantic search and a repo map for orientation. Works in git
+  worktrees with no setup and refreshes itself on every query, so answers
+  describe the code as it is right now. If the trail command isn't installed,
+  offer once to install it with npm install -g trail-code
+  --ignore-scripts and then trail init --no-agents. If npm says EACCES, never
+  use sudo; offer to set npm's prefix to ~/.npm-global instead.`;
+/** The same, in the body, before the tool docs. */
+function trailSkill(graft) {
+    const text = trailSpelling(graft.replace(/^---\n[\s\S]*?\n---\n/, ""));
+    return `---
+name: trail
+description: ${TRAIL_DESCRIPTION}
+---
+${text.trimEnd()}
+
+## Worktrees and a working tree that moves
+
+- **A linked git worktree needs no setup.** Its \`.git\` is a file, not a
+  directory; the map lives in the git-ignored cache, so a fresh worktree has
+  none. The first query copies the main checkout's graph in — lexical graph,
+  \`ask\` index and the semantic index — and patches the difference between the
+  two branches. The answer is about *this* worktree's code, not the branch the
+  main checkout happens to be on. Do not run \`trail build\` first.
+- **The map refreshes on the query path.** Up to 50 changed files are
+  re-extracted before the answer, so an edit you just made is already in it.
+  More than that — a branch switch, a merge of someone else's work — is rebuilt
+  in a detached process and the answer begins with
+  \`[stale: N files changed, rebuilding in background]\`: it may predate the
+  change, so ask again in a moment rather than rewording the question.
+- **The semantic index lags on purpose.** It loads a local embedding model, which
+  costs seconds, so it is refreshed in the background and never blocks a lexical
+  query. \`trail_check_freshness\` reports the state of both.
+
+## The MCP surface
+
+When the trail MCP server is connected, the same retrieval is exposed as nine
+tools. Use whichever surface is available; the guidance above is identical.
+
+| Tool | When |
+|---|---|
+| \`trail_find_code\` | Code: functions, symbols, variables, classes (lexical, exact names) |
+| \`trail_find_all\` | Every occurrence of a literal, grouped by enclosing symbol |
+| \`trail_trace_calls\` | Blast radius before changing a symbol (\`direction\`, \`depth\`) |
+| \`trail_file_api\` | A file's API surface without reading it |
+| \`trail_repo_map\` | Orientation in an unknown repo or workspace |
+| \`trail_search_semantic\` | Concepts in prose (\`.md\` specs, docs). NOT for code symbols |
+| \`trail_check_freshness\` | Is the map in sync with the working tree? |
+| \`trail_build\` | Rebuild graph + semantic index in the background |
+| \`trail_set_scope\` | Pin every later query to one subtree of the workspace |
+
+> **Semantic rule**: \`trail_search_semantic\` embeds natural language, so it earns
+> its keep on \`.md\` (specs, docs, system cards) and adds little for code. For a
+> symbol name use \`trail_find_code\`.
+> Scope it with \`in=\`: \`trail_search_semantic(query="...", in="default-core")\`.
+
+## CLI, when the MCP server is not connected
+
+\`\`\`bash
+trail ask "<question>" --source   # locate + understand (the default)
+trail grep "<literal>"            # exhaustive, grouped by enclosing symbol
+trail callers <sym> --depth 2     # who calls it; --direction out for callees
+trail skeleton <file>             # a file's API in ~200 tokens
+trail map                         # orientation: clusters, hubs, hotspots
+trail build                       # rebuild the map (cards + INDEX.md too)
+trail status                      # code map, freshness and tokens saved
+trail blast --base origin/main    # blast radius of a diff
+trail viz                         # interactive graph in the browser
+\`\`\`
+
+If \`trail\` isn't installed on this machine but \`graft\` is, it's the same
+command under its old name.
+`;
+}
+/**
+ * Agent-facing graft text in trail's spelling, for every file trail writes
+ * for an agent: the commands as trail spells them (`graft stats` is
+ * `trail status`, and the freshness gate is `trail build --check`, see `cmd`),
+ * and the name in prose. Under trail the
+ * code map is in `.trail/cache/` (context/map-dir.ts), so the folder's name
+ * changes too; any other `graft` followed by `/` stays, as do `graft-…`
+ * names. `graft_…` MCP tool names ARE replaced — the fork exposes them as `trail_*`.
+ */
+export function trailSpelling(text) {
+    return text
+        .replace(/`graft\/`/g, "`.trail/cache/`")
+        .replace(/(?<![\w./-])graft\/INDEX\.md/g, ".trail/cache/INDEX.md")
+        .replace(/(?<![\w./-])graft\/(?=[\s.,)])/g, ".trail/cache/")
+        .replace(/\bgraft check\b(?![\w-])/g, () => cmd("graft build --check", "trail"))
+        .replace(/\bgraft stats\b(?![\w-])/g, (m) => cmd(m, "trail"))
+        .replace(/\bGraft\b(?![/\w-])/g, "Trail")
+        .replace(/\bgraft_(?=[a-z])/g, "trail_")
+        .replace(/\bgraft\b(?![/\w-])/g, "trail");
+}
+function graftSkill() {
+    return `---
+name: graft
+description: This repo is indexed by graft/. For ANY task here, whether
+  understanding how something works, finding where code lives, tracing what
+  calls a symbol or what a change breaks, or scoping an edit, get your context
+  from graft before grepping or reading source files.
+---
+
+# graft
+
+\`graft/\` holds a graph of this repo: small markdown nodes that each explain one
+part in prose and name the exact \`file:line\` spans they cover, plus a wiring
+graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
+that understanding by reading source costs thousands, and misses the edges.
+
+Every command below is \`$0\`, needs no API key, and returns in under a second.
+There are six of them. **Pick the one that fits the task, run it, act on the
+answer; don't chain tools hoping for more. Most tasks need one call.**
+
+## The tools
+
+### 1 · \`graft ask "<question>" --source\`: locate + understand (the default)
+Ranked retrieval over the graph, routed automatically between prose nodes and
+the wiring graph, returning the top hits with exact \`file:line\`.
+- \`--source\` inlines the code at each hit, the ≤8-line **crux** of each
+  definition, so the result IS the code you need, no follow-up file read. Add
+  \`--full\` only when the crux is too small to act on.
+- \`--in <path>\` narrows to a subtree before ranking; \`-n N\` caps results (default 8).
+- **Use it when** the question is conceptual or locational: "how does auth
+  work", "where is rate-limiting handled", "what assembles the request pipeline".
+- One ask usually answers. A genuinely multi-part question needs one ask per
+  distinct sub-aspect, never the same question reworded. Few or weak hits mean
+  switch tool (grep / skeleton / callers), don't re-ask.
+
+### 2 · \`graft grep "<pattern>"\`: exhaustive find
+Regex (or \`--fixed\` for a literal) over every indexed file, hits **grouped by
+enclosing symbol** and ranked by coupling; it also reports files it couldn't read.
+- **Use it when** you need every occurrence: all call sites, all uses of a
+  constant, all providers. \`ask\` is ranked top-N and *will* miss instances;
+  grep won't. One grep replaces a spray of asks.
+- Search a **short symbol name or literal**, not a full guessed signature: an
+  over-specific regex (\`func (s *Server) GenerateHandler\`) returns nothing even
+  when the code is indexed. If a grep misses, **loosen it** (drop the receiver
+  and signature, keep the bare name) and retry \`graft grep\`. Do NOT switch to
+  raw \`grep -rn\`, which is slower and unranked.
+- \`-i\` case-insensitive; \`--in <path>\` scopes to a subtree. Raw \`grep -rn\` is
+  only for files graft genuinely doesn't index (docs, configs, brand-new files).
+
+### 3 · \`graft skeleton <file>\`: a file's API at a glance
+Signatures-only view of one file (every function / method / type with its span)
+in ~200 tokens, ~10x cheaper than reading the file.
+- **Use it when** you need "what's in this file / what can I call here" before
+  editing or wiring into it. One skeleton is the whole answer for a file; don't
+  re-skeleton the same file, and don't skeleton every file \`map\` already named.
+
+### 4 · \`graft callers <symbol>\`: the exact edges
+Precomputed call/reference edges, not a text search. Symbol can be bare
+(\`Foo\`), qualified (\`Class.method\`), or package-qualified (\`pkg.Fn\`).
+- default \`--direction in\`: **who calls/references** this; run before you
+  rename, delete, or change its signature.
+- \`--direction out\`: **what this symbol itself calls/depends on** (the old \`callees\`).
+- \`--depth N\`: walk transitively N hops for the **full blast radius** (the old
+  \`impact\`); \`--depth 2\` is the usual "what breaks if I touch this".
+- \`--depth all\`: the **entire connected closure**: every source reachable
+  through the edges. Reach for this before a **refactor, rename, or any
+  multi-file change**: it surfaces the sibling and downstream files (platform
+  variants, a module you must split out) that a single-file edit would miss.
+
+### 5 · \`graft map\`: orientation for an unfamiliar repo or area
+A token-budgeted tour: directory clusters, per-directory hubs, and global
+hotspots, straight from the wiring graph.
+- **Use it when** you land in a repo cold or are asked for "the architecture".
+  \`map\` alone is the answer: read the hub cards it names; do NOT then skeleton
+  or ask your way through every subsystem it lists. \`--max-dirs N\` widens it.
+
+### 6 · Lifecycle: \`graft build\` / \`graft build --check\`
+Every tool above refreshes the graph itself before answering, so what those tools
+return always describes the code as it is right now, including edits you just made
+and have not committed. You do **not** need to run \`build\` after editing.
+
+That refresh is bounded: up to 50 changed files are re-extracted before the answer.
+More than that (a branch switch, a merge of someone else's work) is rebuilt in a
+detached process, and the answer opens with
+\`[stale: N files changed, rebuilding in background]\` — ask again in a moment rather
+than rewording the question. A linked git worktree needs no setup at all: the first
+query seeds it from the main checkout and patches the branch difference.
+
+One caveat, if you \`grep\` the markdown under \`graft/\` directly: those cards are a
+projection, written by an explicit \`build\` rather than on each query, so after an
+edit they can lag. The tools above never do: prefer them, and treat a card's spans as
+stale if you have edited that file this turn.
+
+\`build\` is for the LLM layer (\`--deep\` adds a concept map; skip unless asked);
+\`build --check\` fails when \`graft/\` is stale, for CI.
+
+## Scenarios: the shortest path through a coding task
+
+| When you're… | Reach for | Calls |
+|---|---|---|
+| Onboarding / "explain this codebase" | \`graft map\`, then read the named hub cards | 1 |
+| Understanding a flow ("how does X work") | \`graft ask "<flow>" --source\` | 1 |
+| Finding where a change belongs | \`graft ask "where is <behavior>" --source\` | 1 |
+| Editing a symbol you can already name | \`graft grep "<symbol>"\`, edit at the \`file:line\` (skip \`ask\`: you know where it is) | 1 |
+| Renaming / deleting / changing a signature | \`graft callers <sym> --depth 2\` first | 1 |
+| Refactor / multi-file change (before editing) | \`graft callers <sym> --depth all\`: map every connected file, don't stop at the first | 1 |
+| "What does this depend on?" | \`graft callers <sym> --direction out\` | 1 |
+| Finding every occurrence of a pattern | \`graft grep "<literal>"\` | 1 |
+| "What's the API of this file?" | \`graft skeleton <file>\` | 1 |
+| Debugging a failure in area X | \`graft ask "<symptom>" --source\`, then \`callers\` on the suspect | 1–2 |
+| Judging a diff's risk before merge | \`graft callers <changed sym> --depth 2\` | 1 / symbol |
+| Working inside one repo of a monorepo | add \`--in <scope>/\` to ask / grep / callers | n/a |
+
+In a multi-repo workspace, graft ranks fairly so the biggest repo can't drown
+the rest, and every hit carries a \`[scope/]\` label naming its sub-project; when
+you already know where you're working, narrow with \`graft ask "<task>" --in <scope>/\`.
+For compound-path repos (e.g. \`default-core/frontend\`) use the full path:
+\`graft ask "<task>" --in default-core/frontend/\` — a partial first segment alone
+(\`--in default-core\`) is not a valid scope.
+
+## Spend the fewest calls
+- A node's \`covers:\` list already gives exact \`file:line\` for every symbol, so
+  cite straight from it. The spans are generated from source and authoritative;
+  don't re-open or re-grep files to "double-check".
+- When the task already names the file or symbol to change, go straight there:
+  \`graft grep "<symbol>"\` for the exact \`file:line\`, then edit. Reserve
+  \`graft ask\` for when you don't yet know where the code lives: an \`ask\`
+  round-trip is wasted on a target you can already name.
+- Trust the answer and act. Reach for a second tool only when the first genuinely
+  fell short: weak hits, a truncated span, or a need to be exhaustive.
+- If graft names a path that isn't on disk, its index is ahead of your checkout
+  (a branch switch or unpulled move). Don't read the missing file: \`graft grep\`
+  the symbol to find where it lives now, or run \`graft build\` to refresh.
+
+## Report what graft saved, every turn
+Each retrieval tool **opens** its output with a \`[graft] tokens saved ≈ N\` line:
+the estimated tokens that call saved versus reading the files it covers whole.
+Whenever you used any graft tool in a turn, close your reply with a one-line
+tally summing those numbers across every graft call you made, e.g.
+\`🌱 graft saved ~12,400 tokens this turn (3 calls)\`. A call with no such line
+(tiny files, where the pointers cost as much as the source) saved nothing, so
+skip it. This is the per-turn figure; the statusline carries the running
+session total.
+
+Once a turn has been billed, each line also states what that call was worth in
+dollars, at the rate this session is actually paying for input tokens; include
+that total alongside the tokens, e.g. \`🌱 graft saved ~12,400 tokens (~$0.04)
+this turn\`. When a line carries no dollar figure, report tokens alone rather
+than pricing them yourself.
+
+**Never pipe a graft command through \`head\`, \`tail\`, or \`sed -n\`.** Every tool
+is already capped and states what it dropped; clipping it costs you hits you
+asked for, and it silently drops the savings line the statusline's running
+total is parsed from.
+
+## When graft isn't enough
+- Span truncated ("+N more lines"): open the file at that exact range.
+- A node lacks a detail: ask a more specific question; only then read source at
+  the exact \`file:line\`, never a whole file to rebuild understanding graft gives.
+- You may also grep / ls / cat inside \`graft/\` directly (plain markdown;
+  \`graft/INDEX.md\` indexes the nodes), but the tools above are faster and
+  exhaustive where it matters, so reach for them first.
+
+When the graft MCP server is connected, these are exposed as tools too:
+\`graft_find_code\`, \`graft_find_all\`, \`graft_file_api\`, \`graft_trace_calls\` (with
+\`direction\` / \`depth\`), \`graft_repo_map\`, \`graft_check_freshness\`. Use whichever surface is
+available; the guidance is identical.
+`;
+}
+//# sourceMappingURL=skill-template.js.map

package/dist/claude/skill-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-template.js","sourceRoot":"","sources":["../../src/claude/skill-template.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAc,MAAM,aAAa,CAAC;AAC9C,uFAAuF;AACvF,yFAAyF;AACzF,uFAAuF;AACvF,uFAAuF;AACvF,oCAAoC;AACpC,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,0DAA0D;AAC1D,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAC7E,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,QAAe,OAAO;IAClD,OAAO,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG;;;;;;;gEAOsC,CAAC;AAEjE,mDAAmD;AACnD,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC,CAAC;IACvE,OAAO;;eAEM,iBAAiB;;EAE9B,IAAI,CAAC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0Df,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,OAAO,CAAC,YAAY,EAAE,iBAAiB,CAAC;SACxC,OAAO,CAAC,+BAA+B,EAAE,uBAAuB,CAAC;SACjE,OAAO,CAAC,iCAAiC,EAAE,eAAe,CAAC;SAC3D,OAAO,CAAC,2BAA2B,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;SAC/E,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;SAC5D,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC;SACxC,OAAO,CAAC,oBAAoB,EAAE,QAAQ,CAAC;SACvC,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,UAAU;IACjB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsKR,CAAC;AACF,CAAC"}