@raymondchins/agentmap 0.6.1 → 0.8.0

package/README.md

@@ -185,6 +185,43 @@ internally on `tool_name`. For reference, or to wire it by hand:
 That's the "forced to use it" in the tagline: the map stays current on its own, and the
 agent is steered to it the moment it reaches for a dependency-shaped grep or Bash search.
 
+### 3. Agent skills (Cursor, Claude Code, Codex, OpenCode, Gemini, Antigravity, Copilot)
+
+```bash
+npx @raymondchins/agentmap --install-skill
+```
+
+Copies packaged **SKILL.md** files and a **Cursor rule** (`.cursor/rules/agentmap.mdc`,
+`alwaysApply: true`) into the current repo or global agent directories. Paths follow
+each platform's official skill-directory conventions. Options:
+
+```bash
+agentmap --install-skill --platform cursor           # Cursor rule only (project)
+agentmap --install-skill --platform claude           # .claude/skills/agentmap/SKILL.md
+agentmap --install-skill --platform codex            # .codex/skills/ (project) or ~/.codex/skills/ (global)
+agentmap --install-skill --platform opencode         # .opencode/skills/ (project) or ~/.config/opencode/skills/ (global)
+agentmap --install-skill --platform gemini           # .gemini/skills/ (project); global ~/.gemini/skills/ (Windows global: ~/.agents/skills/)
+agentmap --install-skill --platform antigravity      # .agents/skills/ (project) or ~/.gemini/config/skills/ (global)
+agentmap --install-skill --platform copilot          # .copilot/skills/ or ~/.copilot/skills/
+agentmap --install-skill --global --platform claude  # ~/.claude/skills/...
+agentmap --install-skill --platform agents           # legacy .agents/skills/ (project or global); excluded from default `all`
+agentmap --install-skill --dry-run                   # preview paths, no writes
+```
+
+`--platform all` installs: claude, cursor, codex, opencode, gemini, antigravity, copilot (not legacy `agents`).
+
+Some platforms also get **always-on** docs and hooks in the same command:
+
+| `--platform` | Skill | Also installs (project) | Global docs |
+|--------------|-------|-------------------------|-------------|
+| `gemini` | `.gemini/skills/…/SKILL.md` | `GEMINI.md` + `.gemini/settings.json` BeforeTool nudge | `~/.gemini/GEMINI.md` |
+| `codex` | `.codex/skills/…/SKILL.md` | `AGENTS.md` merge-safe `<!-- agentmap:begin/end -->` block | `~/.codex/AGENTS.md` |
+| `opencode` | `.opencode/skills/…/SKILL.md` | `AGENTS.md` + `.opencode/plugins/agentmap-nudge.js` | `~/.config/opencode/AGENTS.md` |
+
+Codex and OpenCode share one repo-root `AGENTS.md` on project install. Existing content outside the marked block is preserved.
+
+Pair with `--install-hooks` (Claude Code) or `--mcp` (Cursor MCP).
+
 ---
 
 ## Quickstart
@@ -481,6 +518,8 @@ $ node agentmap.mjs --print | jq '.hubs[0]'
 | `--version` / `-v` | Print the version from `package.json` and exit 0. |
 | `--json` | **Global modifier.** When present, every command prints exactly one JSON object to stdout (no prose). Shapes vary per command: `--json --hubs` → `{command,fileCount,sha,hubs:[string]}`, `--json --find X` → `{command,query,matches:[{file,name,kind}]}`, `--json --relates X` → `{command,file,pagerank,exports,imports,dependents,related}`, `--json --any X` → `{command,query,kind,…payload}`, etc. Bare `--json` (no query flag) → `{command:"build",fileCount,features,topHub}`. |
 | `--install-hooks` | Copy `hooks/post-commit` into `.git/hooks/` (chmod 0755), ensure `.claude/agentmap.json` is in `.gitignore`, and auto-wire the Claude Code `PreToolUse(Grep)` nudge into `.claude/settings.json` (merge-safe + idempotent). Exit 0 on success, stderr + exit 1 on failure. |
+| `--hook-status` | Report whether the post-commit hook, PreToolUse nudge, and `.gitignore` entry are installed (no writes). |
+| `--install-skill` | Install skills + always-on docs/hooks per platform (`--platform claude\|cursor\|codex\|opencode\|gemini\|antigravity\|copilot\|agents\|all`, default `all`; `--project` default, or `--global`; `--dry-run` preview). |
 | `--mcp` | Start agentmap as a **stdio MCP server** so non-Claude-Code agents (Cursor, Cline, any MCP client) can call every flag as a first-class tool. |
 
 **Exit-code contract:** `0` = success / match / help / version; `1` = query returned zero results (`--any`, `--find`, `--relates`, `--feature` with no match); `2` = usage error (missing required arg, unknown flag). Any token starting with `-` that matches no known flag prints an error to stderr and exits 2.

package/agentmap.mjs

@@ -281,6 +281,77 @@ function identMul(ident, defineCount, mentioned) {
   return mul;
 }
 
+// Read baseUrl+paths from a tsconfig/jsconfig file. Returns null when absent.
+// Follows `extends` recursively (depth-capped) so a package tsconfig that only
+// `extends` a shared base (Turborepo tsconfig.base.json holding all `paths`)
+// still contributes its inherited baseUrl/paths. Child overrides parent.
+function readTsconfigAliasOpts(cfgPath, _depth = 0) {
+  try {
+    const raw = JSON.parse(readFileSync(cfgPath, "utf8")) || {};
+    const co = raw.compilerOptions || {};
+    // Resolve inherited opts from `extends` first (parent), then layer self on top.
+    let inherited = null;
+    if (raw.extends && _depth < 10) {
+      const exts = Array.isArray(raw.extends) ? raw.extends : [raw.extends];
+      const here = dirname(cfgPath);
+      for (const ext of exts) {
+        if (typeof ext !== "string" || !ext) continue;
+        // Only resolve path-like extends (./, ../, absolute). Bare package
+        // extends (e.g. "@tsconfig/strict") live in node_modules and don't
+        // carry repo-local `paths`, so skip them safely.
+        if (!/^(\.\.?\/|\/)/.test(ext)) continue;
+        let base = join(here, ext);
+        if (!existsSync(base) && existsSync(base + ".json")) base += ".json";
+        else if (!/\.json$/.test(base) && existsSync(join(base, "tsconfig.json"))) base = join(base, "tsconfig.json");
+        if (!existsSync(base)) continue;
+        const parent = readTsconfigAliasOpts(base, _depth + 1);
+        if (parent) inherited = { ...(inherited || {}), ...parent };
+      }
+    }
+    const self = {};
+    if (co.baseUrl) self.baseUrl = co.baseUrl;
+    if (co.paths) self.paths = co.paths;
+    const out = { ...(inherited || {}), ...self };
+    if (!Object.keys(out).length) return null;
+    return out;
+  } catch { return null; }
+}
+
+// Collect package-level alias configs from tsconfig/jsconfig files in the repo.
+// Deepest-dir-first sort so nearestAliasConfig can pick the longest prefix match.
+function discoverPackageAliasConfigs(rootAbs, listed) {
+  const root = rootAbs.replace(/\\/g, "/");
+  const configs = [];
+  const cfgRels = listed.length
+    ? listed.filter((f) => /(^|\/)tsconfig\.json$/.test(f) || /(^|\/)jsconfig\.json$/.test(f))
+    : [];
+  for (const rel of cfgRels) {
+    const full = join(root, rel);
+    if (!existsSync(full)) continue;
+    const opts = readTsconfigAliasOpts(full);
+    if (!opts) continue;
+    configs.push({
+      dir: join(root, dirname(rel)).replace(/\\/g, "/"),
+      baseUrl: opts.baseUrl || ".",
+      paths: opts.paths || {},
+    });
+  }
+  configs.sort((a, b) => b.dir.length - a.dir.length);
+  return configs;
+}
+
+// Longest matching tsconfig dir wins (monorepo package boundary).
+function nearestAliasConfig(fromAbsDir, configs, rootAbs, rootOpts) {
+  const norm = fromAbsDir.replace(/\\/g, "/");
+  let best = null;
+  for (const c of configs) {
+    const d = c.dir;
+    if (norm === d || norm.startsWith(d + "/")) { best = c; break; } // configs sorted deepest-first
+  }
+  if (best) return best;
+  return { dir: rootAbs, baseUrl: rootOpts.baseUrl || ".", paths: rootOpts.paths || {} };
+}
+
 // Construct a ts-morph Project robustly: use tsconfig.json when present + valid;
 // else (missing / malformed / solution-style references that index 0 files) fall
 // back to broad source globs so the tool degrades gracefully instead of crashing.
@@ -296,11 +367,8 @@ function makeProject() {
     for (const cfg of ["tsconfig.json", "jsconfig.json"]) {
       try {
         if (!existsSync(cfg)) continue;
-        const co = (JSON.parse(readFileSync(cfg, "utf8")) || {}).compilerOptions || {};
-        const out = {};
-        if (co.baseUrl) out.baseUrl = co.baseUrl;
-        if (co.paths) out.paths = co.paths;
-        if (Object.keys(out).length) return out;
+        const opts = readTsconfigAliasOpts(cfg);
+        if (opts) return opts;
       } catch { /* ignore — proceed without paths */ }
     }
     return {};
@@ -329,6 +397,7 @@ function makeProject() {
   const loaded = new Set(project.getSourceFiles().map((s) => s.getFilePath()));
   const cwdp = process.cwd().replace(/\\/g, "/");
   const listed = sh("git ls-files --cached --others --exclude-standard").split("\n").filter(Boolean);
+  const packageAliasConfigs = discoverPackageAliasConfigs(cwdp, listed);
   // `.vue` discovery: same channel as TS/JS (git ls-files when available, else
   // a broad glob fallback). We do NOT hand `.vue` straight to ts-morph (it is
   // not TS/JS). Instead, for each `.vue` file we read its `<script>` block via
@@ -390,7 +459,7 @@ function makeProject() {
     vueMap[`${cwdp}/${vpath}`] = `${cwdp}/${f}`;
     vueReal[`${cwdp}/${f}`] = true;
   }
-  return { project, vueMap, vueReal, aliasOpts };
+  return { project, vueMap, vueReal, aliasOpts, packageAliasConfigs };
 }
 
 // ---------------------------------------------------------------------------
@@ -400,7 +469,7 @@ function makeProject() {
 // ---------------------------------------------------------------------------
 function build() {
   const t0 = Date.now();
-  const { project, vueMap, vueReal, aliasOpts } = makeProject();
+  const { project, vueMap, vueReal, aliasOpts, packageAliasConfigs } = makeProject();
   const { SyntaxKind } = tsMorph();
   const CallExpression = SyntaxKind.CallExpression;
   const cwd = process.cwd().replace(/\\/g, "/");
@@ -439,14 +508,15 @@ function build() {
     if (vueReal[`${abs}.vue`]) return rel(`${abs}.vue`);
     return null;
   };
-  // #3 fix: tsconfig/jsconfig baseUrl+paths alias resolution ("@/x", "~/x") for
-  // the side-effect/dynamic/require edges too. Static imports already resolve via
-  // ts-morph's getModuleSpecifierSourceFile(); without this, `import "@/lib/x"`,
-  // `import("@/lib/x")` and `require("@/lib/x")` silently formed NO edge.
+  // #3 fix + monorepo: tsconfig/jsconfig baseUrl+paths alias resolution ("@/x",
+  // "#/x", "~/x") for side-effect/dynamic/require edges AND static imports when
+  // ts-morph can't resolve (cwd tsconfig lacks package paths). Per importing
+  // file, use the nearest discovered tsconfig paths.
   const ROOTABS = process.cwd().replace(/\\/g, "/");
-  const aliasBase = aliasOpts.baseUrl ? joinPosix(ROOTABS, aliasOpts.baseUrl) : ROOTABS;
-  const aliasEntries = Object.entries(aliasOpts.paths || {});
-  const resolveAlias = (spec) => {
+  const resolveAlias = (spec, fromAbsDir) => {
+    const cfg = nearestAliasConfig(fromAbsDir, packageAliasConfigs, ROOTABS, aliasOpts);
+    const aliasBase = joinPosix(cfg.dir, cfg.baseUrl || ".");
+    const aliasEntries = Object.entries(cfg.paths || {});
     for (const [pat, targets] of aliasEntries) {
       const star = pat.indexOf("*");
       let sub = null;
@@ -466,7 +536,7 @@ function build() {
     return null;
   };
   const resolveSpec = (fromAbsDir, spec) => {
-    if (!spec.startsWith(".")) return resolveAlias(spec); // alias (baseUrl/paths) or null for non-relative
+    if (!spec.startsWith(".")) return resolveAlias(spec, fromAbsDir); // alias (baseUrl/paths) or null for non-relative
     // normalize fromAbsDir + spec into an absolute-ish posix path
     const join = (a, b) => {
       const parts = (a + "/" + b).split("/"); const st = [];
@@ -524,11 +594,16 @@ function build() {
         if (imp.getNamespaceImport()) names.push("*");
         addEdge(rel(t.getFilePath()), names.length ? names : ["*"]);
       } else {
-        // 6b: side-effect import (`import "./x"`) — no source file via ts-morph,
-        // but a relative specifier resolving in-project still counts as an edge.
+        // 6b: side-effect or alias import — ts-morph may not resolve when cwd
+        // tsconfig lacks package paths; resolveSpec uses nearest tsconfig paths.
         const spec = imp.getModuleSpecifierValue();
         const tp = resolveSpec(fromDir, spec);
-        if (tp) addEdge(tp, ["*"]);
+        if (tp) {
+          const names = imp.getNamedImports().filter((n) => !n.isTypeOnly()).map((n) => n.getName());
+          if (imp.getDefaultImport()) names.push("default");
+          if (imp.getNamespaceImport()) names.push("*");
+          addEdge(tp, names.length ? names : ["*"]);
+        }
       }
     }
     for (const exp of sf.getExportDeclarations()) {
@@ -917,6 +992,60 @@ function installHooks({ dryRun = false } = {}) {
   console.log("\nDone — the map auto-refreshes on commit, and greps are nudged to agentmap first.");
 }
 
+// Marker string baked into hooks/post-commit — used by --hook-status to detect our
+// hook even when chained with other tools in the same file.
+const POST_COMMIT_MARKER = "agentmap — git post-commit hook";
+const NUDGE_REL = ".claude/hooks/agentmap-nudge.mjs";
+const MAP_IGNORE_LINE = ".claude/agentmap/";
+
+function hookStatus() {
+  const gitDir = sh("git rev-parse --git-dir");
+  if (!gitDir) {
+    console.log("not a git repository — run inside the repo you want to check");
+    return;
+  }
+  const hooksDir = `${gitDir}/hooks`;
+  const postCommitPath = `${hooksDir}/post-commit`;
+
+  let postCommit = "not installed";
+  if (existsSync(postCommitPath)) {
+    const body = readFileSync(postCommitPath, "utf8");
+    postCommit = body.includes(POST_COMMIT_MARKER) ? "installed" : "not installed (hook exists but agentmap not found)";
+  }
+
+  let nudge = existsSync(NUDGE_REL) ? "installed" : "not installed";
+
+  let grepWire = "not wired";
+  let bashWire = "not wired";
+  const settingsPath = ".claude/settings.json";
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
+      const entries = settings.hooks?.PreToolUse || [];
+      const has = (matcher) => entries.some(
+        (e) => e?.matcher === matcher && Array.isArray(e?.hooks) && e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+      );
+      grepWire = has("Grep") ? "wired" : "not wired";
+      bashWire = has("Bash") ? "wired" : "not wired";
+    } catch {
+      grepWire = "not wired (invalid settings.json)";
+      bashWire = "not wired (invalid settings.json)";
+    }
+  }
+
+  let gitignore = "missing entry";
+  if (existsSync(".gitignore")) {
+    const ok = readFileSync(".gitignore", "utf8").split(/\r?\n/).some((l) => l.trim() === MAP_IGNORE_LINE);
+    gitignore = ok ? "ok" : "missing entry";
+  }
+
+  console.log(`post-commit: ${postCommit}`);
+  console.log(`nudge (${NUDGE_REL}): ${nudge}`);
+  console.log(`PreToolUse(Grep): ${grepWire}`);
+  console.log(`PreToolUse(Bash): ${bashWire}`);
+  console.log(`.gitignore (${MAP_IGNORE_LINE}): ${gitignore}`);
+}
+
 // ---------------------------------------------------------------------------
 // --setup-mcp: register the agentmap MCP server in the global configs of
 // MCP-capable IDEs that aren't Claude Code (which uses --install-hooks instead).
@@ -998,7 +1127,8 @@ const out = (obj, prose) => { if (wantJson) console.log(JSON.stringify(obj)); el
 // NOT in this set is an unknown flag → usage error (exit 2), not a silent build.
 const KNOWN = new Set([
   "--json", "--print",
-  "--help", "-h", "--version", "-v", "--install-hooks", "--dry-run", "--setup-mcp", "--mcp",
+  "--help", "-h", "--version", "-v", "--install-hooks", "--hook-status", "--install-skill", "--platform", "--project", "--global",
+  "--dry-run", "--setup-mcp", "--mcp",
   "--any", "--find", "--relates", "--map", "--focus", "--tokens",
   "--symbols", "--feature", "--features", "--hubs",
 ]);
@@ -1007,7 +1137,7 @@ const KNOWN = new Set([
 // so a dash-leading query like `--any "-O/bin/sh"` is bound as the query, not
 // mistaken for an unknown flag. (arg() already rejects a "--"-leading value, so
 // `--any --foo` still falls through to the missing-arg guard instead.)
-const VALUE_FLAGS = new Set(["--any", "--find", "--relates", "--feature", "--focus", "--tokens", "--symbols"]);
+const VALUE_FLAGS = new Set(["--any", "--find", "--relates", "--feature", "--focus", "--tokens", "--symbols", "--platform"]);
 const valueIdx = new Set();
 for (let i = 0; i < args.length - 1; i++) if (VALUE_FLAGS.has(args[i])) valueIdx.add(i + 1);
 
@@ -1035,6 +1165,9 @@ Maintenance:
   --install-hooks [--dry-run]
                        install git post-commit + copy the PreToolUse nudge +
                        wire .claude/settings.json (--dry-run = preview, no writes)
+  --install-skill [--platform claude|cursor|codex|opencode|gemini|antigravity|copilot|agents|all] [--project|--global] [--dry-run]
+                       install skills + always-on docs/hooks per platform
+  --hook-status          report whether agentmap git/nudge wiring is installed
   --setup-mcp [--dry-run]
                        configure MCP server for OpenCode & Antigravity IDE
                        (--dry-run = preview, no writes)
@@ -1073,6 +1206,29 @@ else if (has("--install-hooks")) {
   try { installHooks({ dryRun: has("--dry-run") }); process.exit(0); }
   catch (e) { console.error(`agentmap --install-hooks failed: ${e?.message || e}`); process.exit(1); }
 }
+// --install-skill: copy packaged SKILL.md / Cursor rule (see skills/install.mjs).
+else if (has("--install-skill")) {
+  try {
+    // lazy import keeps skills/install.mjs (and its package.json read) OFF the
+    // hot path — warm --any/--find queries must not load it.
+    const { installSkill } = await import("./skills/install.mjs");
+    installSkill({
+      platforms: arg("--platform") || "all",
+      project: !has("--global"),
+      global: has("--global"),
+      dryRun: has("--dry-run"),
+    });
+    process.exit(0);
+  } catch (e) {
+    console.error(`agentmap --install-skill failed: ${e?.message || e}`);
+    process.exit(1);
+  }
+}
+// --hook-status: report post-commit / nudge / settings wiring (no writes).
+else if (has("--hook-status")) {
+  try { hookStatus(); process.exit(0); }
+  catch (e) { console.error(`agentmap --hook-status failed: ${e?.message || e}`); process.exit(1); }
+}
 // --setup-mcp: configure MCP server for OpenCode & Antigravity IDE.
 else if (has("--setup-mcp")) {
   try { setupMcp({ dryRun: has("--dry-run") }); process.exit(0); }

package/hooks/agentmap-gemini-nudge.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Gemini CLI BeforeTool nudge — non-blocking context when a search looks like
+// dependency / blast-radius / reuse work. Stdlib only; copied into the project
+// by `agentmap --install-skill --platform gemini`.
+
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (c) => (raw += c));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(raw || "{}");
+    const tool = String(payload.tool_name || "");
+    const ti = payload.tool_input || {};
+
+    const DEP_RE =
+      /\b(import|require\s*\(|imported\s+by|depends|dependents?|dependency)\b|from\s+["']|(^|\|)\s*export\b/i;
+    const GENERIC_DENYLIST =
+      /<(Promise|Array|Map|Set|Record|Partial|Readonly|Pick|Omit|Required|Exclude|Extract|NonNullable|ReturnType|Awaited|Parameters|InstanceType)\b/;
+    const COMPONENT_TAG_RE = /<[A-Z][\w.]*/;
+    const INTENT_RE =
+      /\bwhere\s+is\b|\bwho\s+(imports|uses|renders)\b|\breuse\b|\b(existing|shared)\s+(util|component|hook|helper)\b|\bis\s+there\s+(an?\s+)?(existing|shared)\b/i;
+    const SYMBOL_RE = /\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b/;
+
+    let fire = false;
+    const pattern = String(ti.pattern || ti.query || ti.content || "");
+    const cmd = String(ti.command || ti.cmd || "");
+
+    if (/grep|search|ripgrep/i.test(tool)) {
+      if (pattern.length > 0 && pattern.length <= 2000) {
+        fire =
+          DEP_RE.test(pattern) ||
+          (COMPONENT_TAG_RE.test(pattern) && !GENERIC_DENYLIST.test(pattern)) ||
+          INTENT_RE.test(pattern);
+      }
+    } else if (/shell|bash|terminal|command/i.test(tool) && cmd) {
+      const SEARCHER_RE = /(^|[;&]\s*)(rg|ripgrep|grep|egrep|fgrep|ag|ack)\b/;
+      if (SEARCHER_RE.test(cmd)) {
+        const DATA_FILE_RE = /\.(log|txt|out|csv|tsv|jsonl|ndjson|json|md|ya?ml|xml)(\b|$)/i;
+        const hasDataFileTarget = cmd.split(/\s+/).some((tok) => DATA_FILE_RE.test(tok));
+        if (!hasDataFileTarget) {
+          fire =
+            DEP_RE.test(cmd) ||
+            (COMPONENT_TAG_RE.test(cmd) && !GENERIC_DENYLIST.test(cmd)) ||
+            INTENT_RE.test(cmd) ||
+            SYMBOL_RE.test(cmd);
+        }
+      }
+    }
+
+    if (fire) {
+      const msg =
+        "Dependency / blast-radius / reuse search detected. Prefer agentmap first: " +
+        "`npx @raymondchins/agentmap --any <query>` (file → symbol → feature → git-grep), " +
+        "`--relates <path>`, `--find <symbol>`. Rebuild with `npx @raymondchins/agentmap` if stale.";
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "BeforeTool",
+            additionalContext: msg,
+          },
+        }),
+      );
+    } else {
+      process.stdout.write("{}");
+    }
+  } catch {
+    process.stdout.write("{}");
+  }
+  process.exit(0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -14,6 +14,7 @@
     "agentmap.mjs",
     "mcp.mjs",
     "hooks",
+    "skills",
     "NOTICE"
   ],
   "scripts": {

package/skills/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: agentmap
+description: >-
+  Use for TypeScript/JavaScript codebase navigation — symbol lookup, blast radius,
+  reuse checks, and repo orientation. Prefer agentmap before serial grep when
+  exploring imports, exports, or where a symbol lives. Package is
+  @raymondchins/agentmap (not the unrelated npm package agentmap).
+---
+
+# agentmap
+
+Queryable, ranked **import graph** for TS/JS repos (PageRank hubs, symbol ranking, token-budgeted digest). Faster and more accurate than grep for structural questions.
+
+## When to use
+
+- **Where is X defined?** / **who imports this file?** / **what breaks if I edit this?**
+- **Reuse check** before adding a util, component, or type
+- **Session start** — orient to a large monorepo cheaply
+
+## When not to use
+
+- Raw string / config value search (try `agentmap --any` first — layer 4 is live `git grep`)
+- Non-TS/JS files, runtime call graphs, or full semantic "how does it work?" (use codebase search)
+- Next-style `--feature` on TanStack Router / non-`app/` layouts (often empty)
+
+## Commands (run in repo root)
+
+```bash
+# Smart router — default first move
+agentmap --any <query>
+
+# Reuse / symbol definition
+agentmap --find <SymbolName>
+
+# Blast radius (exports, imports, dependents, related files)
+agentmap --relates <path/to/file.ts>
+
+# Token-budgeted ranked digest
+agentmap --map --tokens 400
+agentmap --map --focus <path> --tokens 400
+
+# Hub files (PageRank)
+agentmap --hubs
+
+# JSON for tools
+agentmap --json --any <query>
+```
+
+Install: `npm i -g @raymondchins/agentmap` or `npx @raymondchins/agentmap`. Map cache: `.claude/agentmap/` (gitignored).
+
+## Agent platforms
+
+| Platform | Setup |
+|----------|--------|
+| **Claude Code** | `agentmap --install-hooks` (post-commit refresh + PreToolUse grep nudge) |
+| **Cursor / MCP clients** | `agentmap --mcp` in MCP config, or Shell + commands above |
+| **This skill** | `agentmap --install-skill` |
+
+## Workflow
+
+1. If the map may be stale after edits, run `agentmap` (no flags) or rely on post-commit hook.
+2. Start with `agentmap --any <symbol or topic>`.
+3. Before editing a hub file, run `agentmap --relates <that-file>`.
+4. Fall back to grep only when agentmap returns no useful structure hit.
+
+## Package name
+
+```bash
+npx @raymondchins/agentmap --any Procedure
+# NOT: npm install agentmap  (different package)
+```

package/skills/cursor-rule.mdc

@@ -0,0 +1,27 @@
+---
+description: agentmap ranked TS/JS repo map
+alwaysApply: true
+---
+
+This project can use **agentmap** (`@raymondchins/agentmap`) — a queryable import/symbol map at `.claude/agentmap/`.
+
+**Before Grep/Glob for structural questions** (where is a symbol, who imports a file, reuse check, blast radius), prefer:
+
+```bash
+agentmap --any <query>          # file → symbol → feature → git-grep fallback
+agentmap --find <Symbol>        # exported symbols matching name
+agentmap --relates <file.ts>    # imports, dependents, related files
+agentmap --map --tokens 400     # cheap repo orientation
+```
+
+Use Read/Grep directly when:
+
+1. agentmap already oriented you and you need exact lines to edit
+2. The map is missing — run `agentmap` once to build `.claude/agentmap/`
+3. Searching raw strings, logs, or non-TS files
+
+**Cursor MCP (optional):** `agentmap --mcp` exposes the same queries as tools.
+
+**Note:** `--features` only detects Next.js `app/` routes; TanStack `src/routes/` repos often show `features (0)`.
+
+Package: `@raymondchins/agentmap` — not the unrelated PyPI/npm `agentmap` package.

package/skills/guidance.md

@@ -0,0 +1,24 @@
+## agentmap (repo map)
+
+This project can use **agentmap** (`@raymondchins/agentmap`) — a queryable import/symbol map at `.claude/agentmap/`.
+
+**Before Grep/Glob for structural questions** (where is a symbol, who imports a file, reuse check, blast radius), prefer:
+
+```bash
+agentmap --any <query>          # file → symbol → feature → git-grep fallback
+agentmap --find <Symbol>        # exported symbols matching name
+agentmap --relates <file.ts>    # imports, dependents, related files
+agentmap --map --tokens 400     # cheap repo orientation
+```
+
+Use Read/Grep directly when:
+
+1. agentmap already oriented you and you need exact lines to edit
+2. The map is missing — run `agentmap` once to build `.claude/agentmap/`
+3. Searching raw strings, logs, or non-TS files
+
+**MCP (optional):** `agentmap --mcp` exposes the same queries as tools.
+
+**Note:** `--features` only detects Next.js `app/` routes; TanStack `src/routes/` repos often show `features (0)`.
+
+Package: `@raymondchins/agentmap` — not the unrelated PyPI/npm `agentmap` package.

package/skills/install-helpers.mjs

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+// Shared helpers for --install-skill (docs merge, hooks, plugins).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILLS_DIR = dirname(fileURLToPath(import.meta.url));
+export const GUIDANCE = join(SKILLS_DIR, "guidance.md");
+const GEMINI_NUDGE_SRC = join(SKILLS_DIR, "..", "hooks", "agentmap-gemini-nudge.mjs");
+const OPENCODE_PLUGIN_SRC = join(SKILLS_DIR, "opencode-agentmap-nudge.js");
+
+export const MARK_BEGIN = "<!-- agentmap:begin -->";
+export const MARK_END = "<!-- agentmap:end -->";
+
+export function atomicWrite(dest, body) {
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.tmp`;
+  writeFileSync(tmp, body, "utf8");
+  renameSync(tmp, dest);
+}
+
+function stripJsonComments(src) {
+  let out = "";
+  let inStr = false, esc = false, inLine = false, inBlock = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i], n = src[i + 1];
+    if (inLine) { if (c === "\n") { inLine = false; out += c; } continue; }
+    if (inBlock) { if (c === "*" && n === "/") { inBlock = false; i++; } continue; }
+    if (inStr) {
+      out += c;
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') { inStr = true; out += c; continue; }
+    if (c === "/" && n === "/") { inLine = true; i++; continue; }
+    if (c === "/" && n === "*") { inBlock = true; i++; continue; }
+    out += c;
+  }
+  return out;
+}
+
+function parseSettings(text, settingsPath) {
+  try { return JSON.parse(text) || {}; }
+  catch {
+    try { return JSON.parse(stripJsonComments(text)) || {}; }
+    catch { throw new Error(`${settingsPath} is not valid JSON — fix or remove it, then re-run`); }
+  }
+}
+
+export function readGuidanceSection() {
+  if (!existsSync(GUIDANCE)) throw new Error(`packaged guidance missing: ${GUIDANCE}`);
+  return readFileSync(GUIDANCE, "utf8");
+}
+
+export function mergeGuidanceBlock(existing, section, title) {
+  const block = `${MARK_BEGIN}\n${section.trim()}\n${MARK_END}`;
+  const re = /<!-- agentmap:begin -->[\s\S]*?<!-- agentmap:end -->/;
+  if (existing && re.test(existing)) return existing.replace(re, block);
+  const header = title ? `# ${title}\n\n` : "";
+  if (!existing?.trim()) return `${header}${block}\n`;
+  return `${existing.trimEnd()}\n\n${block}\n`;
+}
+
+/** @returns {string[]} relative paths touched */
+export function installGeminiHooks(root, dryRun) {
+  if (root !== process.cwd()) return [];
+  const nudgeRel = ".gemini/hooks/agentmap-nudge.mjs";
+  const nudgeDest = join(root, nudgeRel);
+  const settingsPath = ".gemini/settings.json";
+  const NUDGE_CMD = `node "$GEMINI_PROJECT_DIR/.gemini/hooks/agentmap-nudge.mjs"`;
+  const targets = [nudgeRel, settingsPath];
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    settings = parseSettings(readFileSync(settingsPath, "utf8"), settingsPath);
+  }
+  settings.hooks ??= {};
+  settings.hooks.BeforeTool ??= [];
+  const matcher = "run_shell_command|grep|search";
+  const already = settings.hooks.BeforeTool.some(
+    (e) => e?.matcher === matcher && Array.isArray(e?.hooks) &&
+      e.hooks.some((h) => typeof h?.command === "string" && h.command.includes("agentmap-nudge")),
+  );
+
+  if (dryRun) return targets;
+  if (!existsSync(GEMINI_NUDGE_SRC)) throw new Error(`packaged hook missing: ${GEMINI_NUDGE_SRC}`);
+  mkdirSync(dirname(nudgeDest), { recursive: true });
+  writeFileSync(nudgeDest, readFileSync(GEMINI_NUDGE_SRC, "utf8"));
+
+  if (!already) {
+    settings.hooks.BeforeTool.push({
+      matcher,
+      hooks: [{
+        name: "agentmap-nudge",
+        type: "command",
+        command: NUDGE_CMD,
+        timeout: 5000,
+        description: "Nudge structural searches toward agentmap",
+      }],
+    });
+    atomicWrite(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  }
+  return targets;
+}
+
+/** @returns {string[]} relative paths touched */
+export function installOpencodePlugin(root, dryRun) {
+  if (root !== process.cwd()) return [];
+  const dest = ".opencode/plugins/agentmap-nudge.js";
+  if (dryRun) return [dest];
+  if (!existsSync(OPENCODE_PLUGIN_SRC)) throw new Error(`packaged plugin missing: ${OPENCODE_PLUGIN_SRC}`);
+  atomicWrite(join(root, dest), readFileSync(OPENCODE_PLUGIN_SRC, "utf8"));
+  return [dest];
+}

package/skills/install.mjs

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: MIT
+// --install-skill: skill files + always-on docs/hooks per platform (project or global).
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir, platform as osPlatform } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  atomicWrite,
+  readGuidanceSection,
+  mergeGuidanceBlock,
+  installGeminiHooks,
+  installOpencodePlugin,
+} from "./install-helpers.mjs";
+
+const SKILLS_DIR = dirname(fileURLToPath(import.meta.url));
+const SKILL_MD = join(SKILLS_DIR, "SKILL.md");
+const CURSOR_RULE = join(SKILLS_DIR, "cursor-rule.mdc");
+
+/** @param {string} root @param {boolean} _globalScope */
+function skillPath(root, _globalScope, ...segments) {
+  return join(root, ...segments);
+}
+
+/** @type {Record<string, {
+ *   label: string;
+ *   src: string;
+ *   dest: (root: string, globalScope: boolean) => string;
+ *   projectOnly?: boolean;
+ *   legacy?: boolean;
+ *   docs?: (root: string, globalScope: boolean) => string;
+ *   hooks?: boolean;
+ *   plugin?: boolean;
+ * }>} */
+const PLATFORMS = {
+  claude: {
+    label: "Claude Code",
+    src: SKILL_MD,
+    dest: (root) => skillPath(root, false, ".claude", "skills", "agentmap", "SKILL.md"),
+  },
+  cursor: {
+    label: "Cursor",
+    src: CURSOR_RULE,
+    dest: (root) => skillPath(root, false, ".cursor", "rules", "agentmap.mdc"),
+    projectOnly: true,
+  },
+  codex: {
+    label: "OpenAI Codex",
+    src: SKILL_MD,
+    dest: (root) => skillPath(root, false, ".codex", "skills", "agentmap", "SKILL.md"),
+    docs: (root, globalScope) =>
+      globalScope ? join(root, ".codex", "AGENTS.md") : join(root, "AGENTS.md"),
+  },
+  opencode: {
+    label: "OpenCode",
+    src: SKILL_MD,
+    dest: (root, globalScope) =>
+      globalScope
+        ? join(root, ".config", "opencode", "skills", "agentmap", "SKILL.md")
+        : join(root, ".opencode", "skills", "agentmap", "SKILL.md"),
+    docs: (root, globalScope) =>
+      globalScope ? join(root, ".config", "opencode", "AGENTS.md") : join(root, "AGENTS.md"),
+    plugin: true,
+  },
+  gemini: {
+    label: "Gemini CLI",
+    src: SKILL_MD,
+    dest: (root, globalScope) => {
+      if (!globalScope) return skillPath(root, false, ".gemini", "skills", "agentmap", "SKILL.md");
+      if (osPlatform() === "win32") return skillPath(root, true, ".agents", "skills", "agentmap", "SKILL.md");
+      return skillPath(root, true, ".gemini", "skills", "agentmap", "SKILL.md");
+    },
+    docs: (root, globalScope) => {
+      if (!globalScope) return join(root, "GEMINI.md");
+      if (osPlatform() === "win32") return join(root, ".agents", "GEMINI.md");
+      return join(root, ".gemini", "GEMINI.md");
+    },
+    hooks: true,
+  },
+  antigravity: {
+    label: "Antigravity",
+    src: SKILL_MD,
+    dest: (root, globalScope) =>
+      globalScope
+        ? skillPath(root, true, ".gemini", "config", "skills", "agentmap", "SKILL.md")
+        : skillPath(root, false, ".agents", "skills", "agentmap", "SKILL.md"),
+  },
+  agents: {
+    label: "Amp / legacy .agents",
+    src: SKILL_MD,
+    dest: (root) => skillPath(root, false, ".agents", "skills", "agentmap", "SKILL.md"),
+    legacy: true,
+  },
+  copilot: {
+    label: "GitHub Copilot CLI",
+    src: SKILL_MD,
+    dest: (root) => skillPath(root, false, ".copilot", "skills", "agentmap", "SKILL.md"),
+  },
+};
+
+const DEFAULT_PLATFORMS = ["claude", "cursor", "codex", "opencode", "gemini", "antigravity", "copilot"];
+
+function parsePlatforms(raw) {
+  const keys = Object.keys(PLATFORMS).join(", ");
+  if (!raw || raw === "all") return [...DEFAULT_PLATFORMS];
+  const tokens = raw.split(/[,+]/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (tokens.includes("all")) {
+    const extra = tokens.filter((t) => t !== "all");
+    for (const n of extra) {
+      if (!PLATFORMS[n]) throw new Error(`unknown platform '${n}' — choose: ${keys}, all`);
+    }
+    return [...new Set([...DEFAULT_PLATFORMS, ...extra])];
+  }
+  for (const n of tokens) {
+    if (!PLATFORMS[n]) {
+      throw new Error(`unknown platform '${n}' — choose: ${keys}, all`);
+    }
+  }
+  return tokens;
+}
+
+function gitAddHint(paths) {
+  const unique = [...new Set(paths.map((p) => p.replace(/\/[^/]+$/, "") || p))];
+  if (unique.length) console.log(`\nOptional: git add ${unique.map((p) => `"${p}"`).join(" ")}`);
+}
+
+function installDocsForPlatform(cfg, { root, globalScope, dryRun, guidance, mergedDocs, targets }) {
+  if (!cfg.docs) return;
+  const dest = cfg.docs(root, globalScope);
+  if (mergedDocs.has(dest)) return;
+  mergedDocs.add(dest);
+  const title = dest.endsWith("GEMINI.md") ? "agentmap" : undefined;
+  if (dryRun) {
+    console.log(`  ${cfg.label} docs: ${dest}`);
+    return;
+  }
+  const existing = existsSync(dest) ? readFileSync(dest, "utf8") : "";
+  atomicWrite(dest, mergeGuidanceBlock(existing, guidance, title));
+  console.log(`  ${cfg.label} docs → ${dest}`);
+  targets.push(dest);
+}
+
+function installExtrasForPlatform(name, cfg, { root, globalScope, dryRun, targets }) {
+  if (cfg.hooks && !globalScope) {
+    const hookTargets = installGeminiHooks(root, dryRun);
+    for (const t of hookTargets) {
+      if (dryRun) console.log(`  ${cfg.label} hooks: ${t}`);
+      else {
+        console.log(`  ${cfg.label} hooks → ${t}`);
+        targets.push(t);
+      }
+    }
+  }
+  if (cfg.plugin && !globalScope) {
+    const pluginTargets = installOpencodePlugin(root, dryRun);
+    for (const t of pluginTargets) {
+      if (dryRun) console.log(`  ${cfg.label} plugin: ${t}`);
+      else {
+        console.log(`  ${cfg.label} plugin → ${t}`);
+        targets.push(t);
+      }
+    }
+  }
+}
+
+/**
+ * @param {{ platforms?: string; project?: boolean; global?: boolean; dryRun?: boolean }} opts
+ */
+export function installSkill({ platforms: platformsArg = "all", project = true, global: globalScope = false, dryRun = false } = {}) {
+  if (project && globalScope) throw new Error("use either --project or --global, not both");
+  const VERSION = JSON.parse(readFileSync(join(SKILLS_DIR, "..", "package.json"), "utf8")).version;
+  const scope = globalScope ? "global" : "project";
+  const root = globalScope ? homedir() : process.cwd();
+  const names = parsePlatforms(platformsArg);
+  const targets = [];
+  const seenDest = new Set();
+  const mergedDocs = new Set();
+  const guidance = readGuidanceSection();
+
+  if (dryRun) console.log(`--dry-run: would install agentmap skill (${scope} scope):`);
+
+  for (const name of names) {
+    const cfg = PLATFORMS[name];
+    if (cfg.projectOnly && globalScope) {
+      console.log(`  skip ${cfg.label}: Cursor rule is project-scoped only (re-run with --project)`);
+      continue;
+    }
+    if (!existsSync(cfg.src)) throw new Error(`packaged skill missing: ${cfg.src}`);
+    const dest = cfg.dest(root, globalScope);
+    const skipSkill = seenDest.has(dest);
+    if (skipSkill) {
+      console.log(`  skip ${cfg.label} skill: same path as another platform (${dest})`);
+    } else {
+      seenDest.add(dest);
+      if (dryRun) {
+        console.log(`  ${cfg.label} skill: ${dest}`);
+      } else {
+        atomicWrite(dest, readFileSync(cfg.src, "utf8"));
+        writeFileSync(join(dirname(dest), ".agentmap_version"), VERSION + "\n", "utf8");
+        console.log(`  ${cfg.label} skill → ${dest}`);
+        targets.push(dest);
+      }
+    }
+
+    installDocsForPlatform(cfg, { root, globalScope, dryRun, guidance, mergedDocs, targets });
+    installExtrasForPlatform(name, cfg, { root, globalScope, dryRun, targets });
+  }
+
+  if (!dryRun && targets.length) {
+    console.log(`\nagentmap --install-skill: installed ${targets.length} file(s) (${scope}).`);
+    if (!globalScope) gitAddHint(targets);
+    console.log("Pair with: agentmap --install-hooks (Claude Code) or agentmap --mcp (Cursor MCP).");
+  }
+}

package/skills/opencode-agentmap-nudge.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// OpenCode plugin — logs a reminder when bash/grep looks like a structural search.
+// Always-on guidance lives in AGENTS.md (installed by --install-skill).
+// Non-blocking: uses client.app.log when available.
+
+const DEP_RE =
+  /\b(import|require\s*\(|imported\s+by|depends|dependents?|dependency)\b|from\s+["']|(^|\|)\s*export\b/i;
+const INTENT_RE =
+  /\bwhere\s+is\b|\bwho\s+(imports|uses|renders)\b|\breuse\b|\b(existing|shared)\s+(util|component|hook|helper)\b/i;
+const SYMBOL_RE = /\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b/;
+
+function shouldNudge(tool, args) {
+  const pattern = String(args?.pattern || args?.query || "");
+  const cmd = String(args?.command || "");
+  if (tool === "grep" && pattern) return DEP_RE.test(pattern) || INTENT_RE.test(pattern);
+  if (tool === "bash" && cmd) {
+    if (!/(^|[;&]\s*)(rg|ripgrep|grep|egrep|fgrep|ag|ack)\b/.test(cmd)) return false;
+    return DEP_RE.test(cmd) || INTENT_RE.test(cmd) || SYMBOL_RE.test(cmd);
+  }
+  return false;
+}
+
+export const AgentmapNudge = async ({ client }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (!shouldNudge(input.tool, output.args)) return;
+      const message =
+        "Structural search: prefer agentmap --any <query>, --relates <path>, or --find <symbol> before serial grep.";
+      try {
+        await client?.app?.log?.({
+          body: { service: "agentmap", level: "info", message },
+        });
+      } catch {
+        // advisory only
+      }
+    },
+  };
+};