@raymondchins/agentmap 0.6.0 → 0.7.0

package/README.md

@@ -185,6 +185,25 @@ 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)
+
+```bash
+npx @raymondchins/agentmap --install-skill
+```
+
+Copies a packaged **SKILL.md** (Claude Code / Codex / OpenCode) and a **Cursor rule**
+(`.cursor/rules/agentmap.mdc`, `alwaysApply: true`) into the current repo or global
+agent directories. Options:
+
+```bash
+agentmap --install-skill --platform cursor      # Cursor rule only
+agentmap --install-skill --platform claude      # .claude/skills/agentmap/SKILL.md
+agentmap --install-skill --global --platform claude  # ~/.claude/skills/...
+agentmap --install-skill --dry-run              # preview paths, no writes
+```
+
+Pair with `--install-hooks` (Claude Code) or `--mcp` (Cursor MCP).
+
 ---
 
 ## Quickstart
@@ -481,6 +500,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 packaged agent skill + Cursor rule (`--platform claude\|cursor\|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

@@ -64,6 +64,10 @@ const sh = (c) => { try { return execSync(c, { stdio: ["ignore", "pipe", "ignore
 // Live content search for the --any fallback. `git grep` over tracked +
 // untracked files (skips gitignored paths like node_modules). Reads DISK, so
 // never stale. -F = fixed-string so literals like "bg-[#faf8f2]" aren't regex.
+// -i = case-insensitive BY DESIGN (discovery ergonomics, matches --find which
+// lowercases its query): a "content" hit may differ in case from the query as
+// typed, but every match is printed verbatim with file:line so the true casing
+// is always visible — results are a superset, never a falsified exact-case hit.
 // stderr ignored so "fatal: not a git repository" stays quiet in non-git repos.
 // Exclude sensitive files from the --untracked sweep so a local .env / key /
 // secrets file never gets scanned and surfaced (and via MCP fed to an LLM).
@@ -88,8 +92,11 @@ const dirtyCount = () =>
   // listed individually (default "all" folds it to "?? newdir/" and the
   // extension regex misses it → a STALE cache would be served).
   sh("git status --porcelain --untracked-files=all").split("\n").filter(Boolean).filter((l) => {
+    const xy = l.slice(0, 2);                            // porcelain status code (XY)
     let p = l.slice(3);                                  // strip "XY " status prefix
-    if (p.includes(" -> ")) p = p.split(" -> ").pop();   // rename: keep the new path
+    // only rename/copy entries use the ` old -> new ` form — gating on the status
+    // code avoids falsely splitting a plain file whose NAME contains " -> ".
+    if (/[RC]/.test(xy) && p.includes(" -> ")) p = p.split(" -> ").pop(); // rename/copy: keep new path
     p = p.replace(/^"|"$/g, "");                         // unquote space/special paths
     return /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|vue)$/.test(p);
   }).length;
@@ -107,8 +114,13 @@ const SRC_EXT = /\.(ts|tsx|mts|cts|jsx|js|mjs|cjs|vue)$/;
 function sourceFingerprint() {
   try {
     const entries = [];
-    const walk = (dir) => {
-      for (const name of readdirSync(dir)) {
+    const walk = (dir, depth) => {
+      if (depth > 40) return; // depth cap — don't fully walk a pathologically deep tree
+      // per-directory try/catch: a single permission-denied subdir must NOT abort
+      // the WHOLE walk (that would return "" and silently disable caching) — skip
+      // the unreadable dir and keep going so the fingerprint stays usable.
+      let names; try { names = readdirSync(dir); } catch { return; }
+      for (const name of names) {
         if (name === "node_modules" || name === ".git" || name === ".next") continue;
         const full = dir + "/" + name;
         let st;
@@ -118,11 +130,11 @@ function sourceFingerprint() {
         // recursion / stack overflow.
         try { st = lstatSync(full); } catch { continue; }
         if (st.isSymbolicLink()) continue;
-        if (st.isDirectory()) walk(full);
+        if (st.isDirectory()) walk(full, depth + 1);
         else if (SRC_EXT.test(name)) entries.push(`${full}:${st.mtimeMs}:${st.size}`);
       }
     };
-    walk(".");
+    walk(".", 0);
     entries.sort();
     return createHash("sha1").update(entries.join("\n")).digest("hex");
   } catch { return ""; }
@@ -347,19 +359,21 @@ function makeProject() {
     ]);
     // Non-git `.vue` fallback: walk the tree like sourceFingerprint() does.
     try {
-      const walk = (dir) => {
-        for (const name of readdirSync(dir)) {
+      const walk = (dir, depth) => {
+        if (depth > 40) return; // depth cap, matching sourceFingerprint()
+        let names; try { names = readdirSync(dir); } catch { return; } // skip unreadable dir, don't abort the whole walk
+        for (const name of names) {
           if (name === "node_modules" || name === ".git" || name === ".next") continue;
           const full = dir + "/" + name;
           // lstatSync (NOT statSync) + skip symlinks, matching sourceFingerprint():
           // a circular symlink would otherwise recurse until the stack overflows.
           let st; try { st = lstatSync(full); } catch { continue; }
           if (st.isSymbolicLink()) continue;
-          if (st.isDirectory()) walk(full);
+          if (st.isDirectory()) walk(full, depth + 1);
           else if (name.endsWith(".vue")) vueFiles.push(full.replace(/^\.\//, ""));
         }
       };
-      walk(".");
+      walk(".", 0);
     } catch { /* ignore — proceed without Vue */ }
   }
   // Build the virtual→real map and register each `<script>` block as a virtual
@@ -376,7 +390,7 @@ function makeProject() {
     vueMap[`${cwdp}/${vpath}`] = `${cwdp}/${f}`;
     vueReal[`${cwdp}/${f}`] = true;
   }
-  return { project, vueMap, vueReal };
+  return { project, vueMap, vueReal, aliasOpts };
 }
 
 // ---------------------------------------------------------------------------
@@ -386,7 +400,7 @@ function makeProject() {
 // ---------------------------------------------------------------------------
 function build() {
   const t0 = Date.now();
-  const { project, vueMap, vueReal } = makeProject();
+  const { project, vueMap, vueReal, aliasOpts } = makeProject();
   const { SyntaxKind } = tsMorph();
   const CallExpression = SyntaxKind.CallExpression;
   const cwd = process.cwd().replace(/\\/g, "/");
@@ -408,8 +422,51 @@ function build() {
   // /index.*. Returns the rel key or null. Powers side-effect (6b) + dynamic
   // import()/require() (6c) edges that ts-morph's specifier resolution skips.
   const RES_EXT = ["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"];
+  // posix-join that collapses "" / "." / ".." segments (no fs access).
+  const joinPosix = (a, b) => {
+    const parts = (a + "/" + b).split("/"); const st = [];
+    for (const seg of parts) { if (seg === "" || seg === ".") continue; if (seg === "..") st.pop(); else st.push(seg); }
+    return (a.startsWith("/") ? "/" : "") + st.join("/");
+  };
+  // resolve an absolute-ish path to an in-project source file, honoring
+  // extensionless + /index.* + .vue resolution (shared by relative + alias paths).
+  const tryResolveAt = (abs) => {
+    if (vueReal[abs]) return rel(abs);
+    let sf = project.getSourceFile(abs);
+    if (!sf) for (const e of RES_EXT) { sf = project.getSourceFile(`${abs}.${e}`); if (sf) break; }
+    if (!sf) for (const e of RES_EXT) { sf = project.getSourceFile(`${abs}/index.${e}`); if (sf) break; }
+    if (sf) return rel(sf.getFilePath());
+    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.
+  const ROOTABS = process.cwd().replace(/\\/g, "/");
+  const aliasBase = aliasOpts.baseUrl ? joinPosix(ROOTABS, aliasOpts.baseUrl) : ROOTABS;
+  const aliasEntries = Object.entries(aliasOpts.paths || {});
+  const resolveAlias = (spec) => {
+    for (const [pat, targets] of aliasEntries) {
+      const star = pat.indexOf("*");
+      let sub = null;
+      if (star === -1) { if (spec === pat) sub = ""; else continue; }
+      else {
+        const pre = pat.slice(0, star), suf = pat.slice(star + 1);
+        if (spec.length < pre.length + suf.length || !spec.startsWith(pre) || !spec.endsWith(suf)) continue;
+        sub = spec.slice(pre.length, spec.length - suf.length);
+      }
+      for (const tRaw of (Array.isArray(targets) ? targets : [targets])) {
+        const tStar = tRaw.indexOf("*");
+        const candidate = tStar === -1 ? tRaw : tRaw.slice(0, tStar) + sub + tRaw.slice(tStar + 1);
+        const hit = tryResolveAt(joinPosix(aliasBase, candidate));
+        if (hit) return hit;
+      }
+    }
+    return null;
+  };
   const resolveSpec = (fromAbsDir, spec) => {
-    if (!spec.startsWith(".")) return null; // only relative, in-project specifiers
+    if (!spec.startsWith(".")) return resolveAlias(spec); // 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 = [];
@@ -438,7 +495,9 @@ function build() {
   for (const sf of sourceFiles) {
     const path = rel(sf.getFilePath());
     if (excluded(path)) continue;
+    try {
     const fromDir = sf.getDirectoryPath().replace(/\\/g, "/");
+    const reExports = new Set(); // #2: names that are pass-through re-exports, not real uses
     // exports, remembering which exported name was the file's DEFAULT export so
     // default-import edges can later resolve "default" → the real symbol name.
     let defaultExportName = null;
@@ -475,7 +534,11 @@ function build() {
     for (const exp of sf.getExportDeclarations()) {
       if (exp.isTypeOnly()) continue; // type-only re-exports excluded from edges
       const t = exp.getModuleSpecifierSourceFile();
-      if (t) addEdge(rel(t.getFilePath()), exp.getNamedExports().filter((n) => !n.isTypeOnly()).map((n) => n.getName()));
+      if (t) {
+        const names = exp.getNamedExports().filter((n) => !n.isTypeOnly()).map((n) => n.getName());
+        addEdge(rel(t.getFilePath()), names);   // keep the FILE-level edge (barrel depends on origin)
+        for (const n of names) reExports.add(n); // #2: mark as re-export so rankSymbols won't count it as a reference
+      }
     }
     // 6c: dynamic import("./x") and require("./x") with relative, in-project
     // string-literal specifiers → edge with names ["*"]. Prefilter on raw text
@@ -494,9 +557,15 @@ function build() {
     }
     const imports = Object.keys(importedSymbols);
     for (const tp of imports) (dependents[tp] ??= []).push(path);
-    files[path] = { exports, imports, importedSymbols, defaultExportName };
+    files[path] = { exports, imports, importedSymbols, defaultExportName, reExports: [...reExports] };
     const feat = featureOf(path);
     if (feat) (features[feat] ??= []).push(path);
+    } catch (e) {
+      // #1 fix: a single pathological file (malformed import specifier, ts-morph
+      // edge case) must NOT abort the whole map — skip it + warn, preserving the
+      // graceful-degradation contract agentmap advertises.
+      process.stderr.write(`# agentmap: skipped ${path} (parse error: ${e?.message ?? e})\n`);
+    }
   }
   // 7: resolve default-import edges. A default import was recorded literally as
   // "default"; rankSymbols skips "default", so default-exported symbols (the
@@ -564,10 +633,12 @@ function rankSymbols(files, focus) {
       definition.set(`${p}|${e.name}`, { file: p, name: e.name, kind: e.kind });
     }
   }
-  for (const [p, f] of Object.entries(files))
+  for (const [p, f] of Object.entries(files)) {
+    const reExp = new Set(f.reExports || []); // #2: pass-through re-exports aren't real references
     for (const tp of f.imports)
       for (const name of f.importedSymbols[tp] || [])
-        if (name !== "*" && name !== "default") getOrSet(references, name, () => []).push(p);
+        if (name !== "*" && name !== "default" && !reExp.has(name)) getOrSet(references, name, () => []).push(p);
+  }
 
   // mentioned idents from focus files' exports + their basenames
   let mentioned = null;
@@ -846,6 +917,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).
@@ -927,7 +1052,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",
 ]);
@@ -936,7 +1062,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);
 
@@ -964,6 +1090,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|agents|all] [--project|--global] [--dry-run]
+                       install SKILL.md / Cursor rule for coding agents
+  --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)
@@ -1002,6 +1131,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); }
@@ -1157,11 +1309,19 @@ else if (has("--any")) {
         // omitted. Otherwise `continue` so smaller lower-ranked files can still
         // fill the remaining budget (don't `break` on the first overflow).
         if (first && budget > 0) {
-          let partial = capped;
-          while (partial.length > 1) {
-            partial = partial.slice(0, partial.length - 1);
+          // #6 fix: try progressively fewer symbols DOWN TO ONE. The old
+          // `while (partial.length > 1)` sliced before testing and never tried
+          // the single-symbol block, so a tiny --tokens could emit NOTHING for
+          // the top file despite the "never wholly omitted" intent. If even one
+          // symbol overflows the budget, nothing fits (correct) — but we now try.
+          for (let k = capped.length - 1; k >= 1; k--) {
+            const partial = capped.slice(0, k);
             const pt = tokEst(lineOf(partial));
-            if (used + pt <= budget) { used += pt; shownFiles.push({ file, symbols: partial.map((s) => ({ name: s.name, kind: s.kind })) }); break; }
+            if (used + pt <= budget) {
+              used += pt;
+              shownFiles.push({ file, symbols: partial.map((s) => ({ name: s.name, kind: s.kind })) });
+              break;
+            }
           }
           first = false;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raymondchins/agentmap",
-  "version": "0.6.0",
+  "version": "0.7.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/install.mjs

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// --install-skill: copy packaged SKILL.md / Cursor rule into project or global
+// agent directories (project or global scope).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SKILLS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** @type {Record<string, { label: string; src: string; dest: (root: string) => string; projectOnly?: boolean }>} */
+const PLATFORMS = {
+  claude: {
+    label: "Claude Code",
+    src: join(SKILLS_DIR, "SKILL.md"),
+    dest: (root) => join(root, ".claude", "skills", "agentmap", "SKILL.md"),
+  },
+  agents: {
+    label: "Codex / OpenCode (.agents)",
+    src: join(SKILLS_DIR, "SKILL.md"),
+    dest: (root) => join(root, ".agents", "skills", "agentmap", "SKILL.md"),
+  },
+  cursor: {
+    label: "Cursor",
+    src: join(SKILLS_DIR, "cursor-rule.mdc"),
+    dest: (root) => join(root, ".cursor", "rules", "agentmap.mdc"),
+    projectOnly: true,
+  },
+};
+
+function atomicWrite(dest, body) {
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.tmp`;
+  writeFileSync(tmp, body, "utf8");
+  renameSync(tmp, dest);
+}
+
+function parsePlatforms(raw) {
+  if (!raw || raw === "all") return ["claude", "cursor", "agents"];
+  const names = raw.split(/[,+]/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+  for (const n of names) {
+    if (!PLATFORMS[n]) {
+      throw new Error(`unknown platform '${n}' — choose: ${Object.keys(PLATFORMS).join(", ")}, all`);
+    }
+  }
+  return names;
+}
+
+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(" ")}`);
+}
+
+/**
+ * @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");
+  // read version lazily (inside the function, not at module load) so importing
+  // this module is side-effect-free / off the CLI hot path.
+  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 = [];
+
+  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);
+    const body = readFileSync(cfg.src, "utf8");
+    const versionFile = join(dirname(dest), ".agentmap_version");
+
+    if (dryRun) {
+      console.log(`  ${cfg.label}: ${dest}`);
+      continue;
+    }
+
+    atomicWrite(dest, body);
+    writeFileSync(versionFile, VERSION + "\n", "utf8");
+    console.log(`  ${cfg.label} → ${dest}`);
+    targets.push(dest);
+  }
+
+  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).");
+  }
+}