@stainless-code/codemap 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @stainless-code/codemap
 
+## 0.1.3
+
+### Patch Changes
+
+- [#6](https://github.com/stainless-code/codemap/pull/6) [`ad29694`](https://github.com/stainless-code/codemap/commit/ad2969481d4bd4e60d4f29818e4f1e64986216f9) Thanks [@SutuSebastian](https://github.com/SutuSebastian)! - Align shipped agent templates with the published CLI (`codemap`, `npx @stainless-code/codemap`, …). Keep this repository’s `.agents/` rule and skill dev-oriented (`bun src/index.ts`). Remove the redundant `agents-first-convention` template. Document the dev vs `templates/agents/` split in `templates/agents/README.md` and `docs/agents.md`.
+
+## 0.1.2
+
+### Patch Changes
+
+- [#4](https://github.com/stainless-code/codemap/pull/4) [`0a9d829`](https://github.com/stainless-code/codemap/commit/0a9d82935e775edfb942029c03b8a427f18f9e71) Thanks [@SutuSebastian](https://github.com/SutuSebastian)! - **`codemap agents init`:** For Git repos, ensure **`.codemap.*`** is in **`.gitignore`** (create the file or append the line once). **`--force`** removes only template file paths (same relpaths under **`.agents/rules/`** and **`.agents/skills/`** as **`templates/agents`**) before merging; other files under **`.agents/`**, **`rules/`**, or **`skills/`** are kept. **`--interactive` / `-i`** — pick IDE integrations (Cursor, GitHub Copilot, Windsurf, Continue, Cline, Amazon Q, **`CLAUDE.md`**, **`AGENTS.md`**, **`GEMINI.md`**) and symlink vs copy for rule mirrors; requires a TTY. Unknown positional arguments (e.g. `interactive` without `--interactive`) are rejected. Depends on **`@clack/prompts`**.
+
+  **Docs:** **[`docs/agents.md`](https://github.com/stainless-code/codemap/blob/main/docs/agents.md)**; **[`docs/README.md`](https://github.com/stainless-code/codemap/blob/main/docs/README.md)** index updated. Root **[`.gitignore`](https://github.com/stainless-code/codemap/blob/main/.gitignore)** uses a single **`.codemap.*`** line.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -5,7 +5,7 @@
 - **Not** full-text search or grep on arbitrary strings — use those when you need raw file-body search.
 - **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, components, and other extracted facts.
 
-**Documentation:** [docs/README.md](docs/README.md) is the index for technical docs (architecture, packaging, roadmap, benchmarks). **AI / editor agents:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md); Cursor uses `.cursor/` symlinks — [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
+**Documentation:** [docs/README.md](docs/README.md) is the hub (topic index + single-source rules). Topics: [architecture](docs/architecture.md), [agents](docs/agents.md) (`codemap agents init`), [benchmark](docs/benchmark.md), [packaging](docs/packaging.md), [roadmap](docs/roadmap.md), [why Codemap](docs/why-codemap.md). **Bundled rules/skills:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md). **Consumers:** [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
 
 ---
 
@@ -47,9 +47,10 @@ codemap --config /path/to/codemap.config.json --full
 # Re-index only given paths (relative to project root)
 codemap --files src/a.ts src/b.tsx
 
-# Scaffold .agents/ rules and skills from bundled templates (see CONTRIBUTING)
+# Scaffold .agents/ from bundled templates — full matrix: docs/agents.md
 codemap agents init
 codemap agents init --force
+codemap agents init --interactive   # -i; IDE wiring + symlink vs copy
 ```
 
 **Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).

package/dist/agents-init-COkjrzc5.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+//#region src/agents-init.ts
+/**
+* Directory containing `rules/` and `skills/` (next to `dist/` in published packages).
+*/
+function resolveAgentsTemplateDir() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "agents");
+}
+/**
+* Every regular file path under `dir` relative to `dir` (POSIX-style `/`).
+* Used for template paths (`--force` removal), template writes, and copy-mode IDE sync.
+*/
+function listRegularFilesRecursive(dir, relPrefix = "") {
+	const out = [];
+	if (!existsSync(dir)) return out;
+	for (const ent of readdirSync(dir, { withFileTypes: true })) {
+		const name = ent.name;
+		const rel = relPrefix ? `${relPrefix}/${name}` : name;
+		const full = join(dir, name);
+		if (ent.isDirectory()) out.push(...listRegularFilesRecursive(full, rel));
+		else if (ent.isFile()) out.push(rel);
+	}
+	return out;
+}
+function relPathToAbsSegments(rel) {
+	return rel.split("/").filter(Boolean);
+}
+/** Copy only listed relative paths from `srcRoot` into `destRoot` (mkdir parents per file). */
+function copyFilesGranular(srcRoot, destRoot, relPaths) {
+	for (const rel of relPaths) {
+		const from = join(srcRoot, ...relPathToAbsSegments(rel));
+		const to = join(destRoot, ...relPathToAbsSegments(rel));
+		mkdirSync(dirname(to), { recursive: true });
+		copyFileSync(from, to);
+	}
+}
+/** Symlink each file: `destRoot/<rel>` → relative path to `srcRoot/<rel>` (mkdir parents per file). */
+function symlinkFilesGranular(srcRoot, destRoot, relPaths, labelForErrors) {
+	mkdirSync(destRoot, { recursive: true });
+	for (const rel of relPaths) {
+		const srcFile = join(srcRoot, ...relPathToAbsSegments(rel));
+		const destFile = join(destRoot, ...relPathToAbsSegments(rel));
+		mkdirSync(dirname(destFile), { recursive: true });
+		const target = relative(dirname(destFile), srcFile);
+		try {
+			symlinkSync(target, destFile, "file");
+		} catch (err) {
+			throw new Error(`Codemap: symlink failed for ${labelForErrors} (${destFile}): ${String(err)}. Try copy mode or check permissions on Windows.`, { cause: err });
+		}
+	}
+}
+function removeBundledPathsIfExist(destBase, relPaths) {
+	for (const rel of relPaths) {
+		const abs = join(destBase, ...relPathToAbsSegments(rel));
+		if (!existsSync(abs)) continue;
+		rmSync(abs, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Default DB basename `.codemap` plus SQLite sidecars (`.db`, `-wal`, `-shm`, …). */
+const GITIGNORE_CODEMAP_PATTERN = ".codemap.*";
+/** Targets that mirror `.agents/rules` (and Cursor also `.agents/skills`) via per-file symlink or copy. */
+const AGENTS_INIT_SYMLINK_TARGETS = [
+	"cursor",
+	"windsurf",
+	"continue",
+	"cline",
+	"amazon-q"
+];
+function targetsNeedLinkMode(targets) {
+	return targets.some((t) => AGENTS_INIT_SYMLINK_TARGETS.includes(t));
+}
+const POINTER_BODY = `This project uses [Codemap](https://github.com/stainless-code/codemap) — a structural SQLite index for AI agents.
+
+- **Skill:** \`.agents/skills/codemap/SKILL.md\`
+- **CLI:** \`codemap\` to index, \`codemap query "SELECT …"\` for SQL
+- **Rules:** \`.agents/rules/\`
+
+`;
+const CLAUDE_MD_TEMPLATE = `# Codemap\n\n${POINTER_BODY}`;
+const AGENTS_MD_TEMPLATE = `# Agent instructions (Codemap)
+
+${POINTER_BODY}
+Also referenced by **Zed**, **JetBrains AI**-style tools, **Aider**, and other agents that read \`AGENTS.md\` at the repo root.
+
+`;
+const GEMINI_MD_TEMPLATE = `# Codemap (Gemini)
+
+${POINTER_BODY}
+Use this file if your **Gemini** CLI or IDE loads \`GEMINI.md\` at the repo root.
+
+`;
+const COPILOT_TEMPLATE = `# Codemap — GitHub Copilot custom instructions
+
+${POINTER_BODY}
+See [GitHub Docs: custom instructions for Copilot](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot).
+
+`;
+/** HTML comments — invisible in most Markdown renderers; used to upsert without duplicating on re-run. */
+const CODMAP_POINTER_BEGIN = "<!-- codemap-pointer:begin -->";
+const CODMAP_POINTER_END = "<!-- codemap-pointer:end -->";
+function wrapCodemapPointerBlock(inner) {
+	return `${CODMAP_POINTER_BEGIN}\n${inner.trim()}\n${CODMAP_POINTER_END}\n`;
+}
+function escapeRegexChars(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function codemapPointerBlockRegex() {
+	return new RegExp(`${escapeRegexChars(CODMAP_POINTER_BEGIN)}\\s*[\\s\\S]*?${escapeRegexChars(CODMAP_POINTER_END)}`, "m");
+}
+/** Heuristic: file looks like a prior Codemap pointer file before we added markers (upgrade → single managed block). */
+function looksLikeLegacyCodemapPointer(content) {
+	const t = content.trim();
+	if (t.length < 80) return false;
+	return t.includes("stainless-code/codemap") && t.includes(".agents/skills/codemap") && t.includes("codemap query");
+}
+/**
+* Create or merge a Codemap pointer file. Idempotent: managed section is between
+* {@link CODMAP_POINTER_BEGIN} / {@link CODMAP_POINTER_END}; re-runs replace that section only.
+* - **No file:** write managed block.
+* - **Existing + markers:** replace inner section (updates stale template text).
+* - **Existing, no markers, legacy Codemap content:** replace whole file with managed block.
+* - **Existing, other content:** append managed block once.
+* - **`force`:** replace entire file with the latest managed block (same as a fresh write).
+*/
+function upsertCodemapPointerFile(path, innerTemplate, label, force) {
+	const wrapped = wrapCodemapPointerBlock(innerTemplate);
+	if (!existsSync(path)) {
+		writeFileSync(path, wrapped, "utf-8");
+		console.log(`  Wrote ${label} with Codemap pointers`);
+		return;
+	}
+	if (force) {
+		writeFileSync(path, wrapped, "utf-8");
+		console.log(`  Replaced ${label} (--force)`);
+		return;
+	}
+	const content = readFileSync(path, "utf-8");
+	const re = codemapPointerBlockRegex();
+	if (content.match(re)) {
+		const next = content.replace(re, wrapped);
+		if (next === content) {
+			console.log(`  Codemap section in ${label} already up to date`);
+			return;
+		}
+		writeFileSync(path, next, "utf-8");
+		console.log(`  Updated Codemap section in ${label}`);
+		return;
+	}
+	if (looksLikeLegacyCodemapPointer(content)) {
+		writeFileSync(path, wrapped, "utf-8");
+		console.log(`  Migrated ${label} to managed Codemap section`);
+		return;
+	}
+	writeFileSync(path, content + (content.endsWith("\n") ? "\n" : "\n\n") + wrapped, "utf-8");
+	console.log(`  Appended Codemap section to ${label}`);
+}
+/**
+* Ensure `.codemap.*` is listed in `.gitignore` when the project uses Git:
+* - If `<projectRoot>/.git` exists and there is no `.gitignore`, create one with `.codemap.*`.
+* - If `.gitignore` exists, append `.codemap.*` once when missing.
+* - If there is no `.git`, do nothing (not a Git working tree).
+*/
+function ensureGitignoreCodemapPattern(projectRoot) {
+	const gitDir = join(projectRoot, ".git");
+	const gitignorePath = join(projectRoot, ".gitignore");
+	if (!existsSync(gitDir)) return;
+	if (!existsSync(gitignorePath)) {
+		writeFileSync(gitignorePath, `${GITIGNORE_CODEMAP_PATTERN}\n`, "utf-8");
+		console.log(`  Created .gitignore with ${GITIGNORE_CODEMAP_PATTERN} (Git repo, no .gitignore yet)`);
+		return;
+	}
+	const content = readFileSync(gitignorePath, "utf-8");
+	if (content.split(/\r?\n/).some((line) => line.trim() === GITIGNORE_CODEMAP_PATTERN)) return;
+	appendFileSync(gitignorePath, `${content.length > 0 && !content.endsWith("\n") ? "\n" : ""}${GITIGNORE_CODEMAP_PATTERN}\n`, "utf-8");
+	console.log(`  Appended ${GITIGNORE_CODEMAP_PATTERN} to .gitignore`);
+}
+function removePathForRewrite(path, force, label) {
+	if (!existsSync(path)) return;
+	if (!force) throw new Error(`Codemap: ${label} already exists — use --force to replace, or remove it manually.`);
+	rmSync(path, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Map `.agents/rules` into a destination directory (symlink or copy).
+*/
+function wireAgentsRulesTo(projectRoot, destPath, label, linkMode, force) {
+	const agentsRules = join(projectRoot, ".agents", "rules");
+	mkdirSync(dirname(destPath), { recursive: true });
+	removePathForRewrite(destPath, force, label);
+	if (linkMode === "symlink") {
+		const ruleFiles = listRegularFilesRecursive(agentsRules);
+		symlinkFilesGranular(agentsRules, destPath, ruleFiles, label);
+		console.log(`  Linked each file under ${label} → .agents/rules (${ruleFiles.length} files)`);
+		return;
+	}
+	copyFilesGranular(agentsRules, destPath, listRegularFilesRecursive(agentsRules));
+	console.log(`  Copied .agents/rules → ${label}`);
+}
+/**
+* Wire Cursor or other tools after `.agents/` exists.
+*/
+function applyAgentsInitTargets(projectRoot, targets, linkMode, force) {
+	const agentsRules = join(projectRoot, ".agents", "rules");
+	const agentsSkills = join(projectRoot, ".agents", "skills");
+	if (!existsSync(agentsRules) || !existsSync(agentsSkills)) throw new Error("Codemap: .agents/rules and .agents/skills must exist before wiring integrations");
+	for (const t of targets) switch (t) {
+		case "cursor":
+			applyCursorIntegration(projectRoot, linkMode, force);
+			break;
+		case "windsurf":
+			wireAgentsRulesTo(projectRoot, join(projectRoot, ".windsurf", "rules"), ".windsurf/rules", linkMode, force);
+			break;
+		case "continue":
+			wireAgentsRulesTo(projectRoot, join(projectRoot, ".continue", "rules"), ".continue/rules", linkMode, force);
+			break;
+		case "cline":
+			wireAgentsRulesTo(projectRoot, join(projectRoot, ".clinerules"), ".clinerules", linkMode, force);
+			break;
+		case "amazon-q":
+			wireAgentsRulesTo(projectRoot, join(projectRoot, ".amazonq", "rules"), ".amazonq/rules", linkMode, force);
+			break;
+		case "claude-md":
+			upsertCodemapPointerFile(join(projectRoot, "CLAUDE.md"), CLAUDE_MD_TEMPLATE, "CLAUDE.md", force);
+			break;
+		case "copilot":
+			mkdirSync(join(projectRoot, ".github"), { recursive: true });
+			upsertCodemapPointerFile(join(projectRoot, ".github", "copilot-instructions.md"), COPILOT_TEMPLATE, ".github/copilot-instructions.md", force);
+			break;
+		case "agents-md":
+			upsertCodemapPointerFile(join(projectRoot, "AGENTS.md"), AGENTS_MD_TEMPLATE, "AGENTS.md", force);
+			break;
+		case "gemini-md":
+			upsertCodemapPointerFile(join(projectRoot, "GEMINI.md"), GEMINI_MD_TEMPLATE, "GEMINI.md", force);
+			break;
+	}
+}
+function applyCursorIntegration(projectRoot, linkMode, force) {
+	const agentsRules = join(projectRoot, ".agents", "rules");
+	const agentsSkills = join(projectRoot, ".agents", "skills");
+	const cursorRules = join(projectRoot, ".cursor", "rules");
+	const cursorSkills = join(projectRoot, ".cursor", "skills");
+	mkdirSync(join(projectRoot, ".cursor"), { recursive: true });
+	if (linkMode === "symlink") {
+		removePathForRewrite(cursorRules, force, ".cursor/rules");
+		removePathForRewrite(cursorSkills, force, ".cursor/skills");
+		const ruleFiles = listRegularFilesRecursive(agentsRules);
+		const skillFiles = listRegularFilesRecursive(agentsSkills);
+		symlinkFilesGranular(agentsRules, cursorRules, ruleFiles, ".cursor/rules");
+		symlinkFilesGranular(agentsSkills, cursorSkills, skillFiles, ".cursor/skills");
+		console.log(`  Linked ${ruleFiles.length} rule file(s) and ${skillFiles.length} skill file(s) under .cursor/ → .agents/`);
+		return;
+	}
+	removePathForRewrite(cursorRules, force, ".cursor/rules");
+	removePathForRewrite(cursorSkills, force, ".cursor/skills");
+	copyFilesGranular(agentsRules, cursorRules, listRegularFilesRecursive(agentsRules));
+	copyFilesGranular(agentsSkills, cursorSkills, listRegularFilesRecursive(agentsSkills));
+	console.log("  Copied rules and skills into .cursor/rules and .cursor/skills");
+}
+/**
+* Copy bundled `rules/` and `skills/` into `<projectRoot>/.agents/`, optional integrations, `.gitignore` hint.
+* **`--force`** deletes only template-backed files, then writes those files again with per-file copies — your other files under **`.agents/`**, **`rules/`**, or **`skills/`** stay.
+* @returns `false` when `.agents/` exists and `--force` was not used.
+*/
+function runAgentsInit(options) {
+	const templateRoot = resolveAgentsTemplateDir();
+	if (!existsSync(templateRoot)) throw new Error(`Codemap: agent templates not found at ${templateRoot} (expected npm package layout: templates/agents next to dist/)`);
+	const templateRules = join(templateRoot, "rules");
+	const templateSkills = join(templateRoot, "skills");
+	const bundledRuleFiles = listRegularFilesRecursive(templateRules);
+	const bundledSkillFiles = listRegularFilesRecursive(templateSkills);
+	const destRoot = join(options.projectRoot, ".agents");
+	const destRules = join(destRoot, "rules");
+	const destSkills = join(destRoot, "skills");
+	if (existsSync(destRoot)) {
+		if (!statSync(destRoot).isDirectory()) throw new Error(`Codemap: ${destRoot} exists but is not a directory — remove or rename it, then retry.`);
+		if (!options.force) {
+			console.error(`  .agents/ already exists at ${destRoot}. Re-run with --force to refresh bundled template files under rules/ and skills/, or remove the directory.`);
+			return false;
+		}
+		removeBundledPathsIfExist(destRules, bundledRuleFiles);
+		removeBundledPathsIfExist(destSkills, bundledSkillFiles);
+	} else mkdirSync(destRoot, { recursive: true });
+	copyFilesGranular(templateRules, destRules, bundledRuleFiles);
+	copyFilesGranular(templateSkills, destSkills, bundledSkillFiles);
+	console.log(`  Wrote agent templates to ${destRoot}`);
+	const targets = options.targets ?? [];
+	const linkMode = options.linkMode ?? "symlink";
+	if (targets.length > 0) applyAgentsInitTargets(options.projectRoot, targets, linkMode, !!options.force);
+	else console.log("  Tip: run `codemap agents init --interactive` to wire editors (Cursor, Copilot, …) or add CLAUDE.md / AGENTS.md");
+	ensureGitignoreCodemapPattern(options.projectRoot);
+	return true;
+}
+//#endregion
+export { targetsNeedLinkMode as n, runAgentsInit as t };

package/dist/agents-init-interactive-HLqgP8gL.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { n as targetsNeedLinkMode, t as runAgentsInit } from "./agents-init-COkjrzc5.mjs";
+import { cancel, confirm, intro, isCancel, multiselect, note, outro, select } from "@clack/prompts";
+//#region src/agents-init-interactive.ts
+const INTEGRATION_OPTIONS = [
+	{
+		value: "cursor",
+		label: "Cursor",
+		hint: ".cursor/rules + skills → .agents/"
+	},
+	{
+		value: "claude-md",
+		label: "Claude Code",
+		hint: "CLAUDE.md"
+	},
+	{
+		value: "copilot",
+		label: "GitHub Copilot",
+		hint: ".github/copilot-instructions.md"
+	},
+	{
+		value: "windsurf",
+		label: "Windsurf (Cascade)",
+		hint: ".windsurf/rules → .agents/rules"
+	},
+	{
+		value: "continue",
+		label: "Continue",
+		hint: ".continue/rules → .agents/rules"
+	},
+	{
+		value: "cline",
+		label: "Cline",
+		hint: ".clinerules → .agents/rules"
+	},
+	{
+		value: "amazon-q",
+		label: "Amazon Q Developer",
+		hint: ".amazonq/rules → .agents/rules"
+	},
+	{
+		value: "agents-md",
+		label: "AGENTS.md (Zed, JetBrains, Aider, …)",
+		hint: "Root AGENTS.md"
+	},
+	{
+		value: "gemini-md",
+		label: "Gemini",
+		hint: "GEMINI.md"
+	}
+];
+function summarizeTargets(targets) {
+	const lines = [];
+	for (const t of targets) {
+		const opt = INTEGRATION_OPTIONS.find((o) => o.value === t);
+		lines.push(opt ? `${opt.label}: ${opt.hint}` : t);
+	}
+	return lines;
+}
+/**
+* Interactive `codemap agents init`: choose integrations and symlink vs copy for rule mirrors.
+*/
+async function runAgentsInitInteractive(opts) {
+	intro("codemap agents init");
+	note("Canonical templates always install to .agents/ (rules + skills).\nOptional steps wire other tools to the same content.", "Codemap");
+	const targetsRaw = await multiselect({
+		message: "Integrations (space to toggle, enter to confirm)",
+		options: INTEGRATION_OPTIONS,
+		required: false,
+		initialValues: []
+	});
+	if (isCancel(targetsRaw)) {
+		cancel("Cancelled.");
+		return false;
+	}
+	const targets = targetsRaw;
+	let linkMode = "symlink";
+	if (targetsNeedLinkMode(targets)) {
+		const mode = await select({
+			message: "How should tools that mirror .agents/rules (and Cursor skills) link?",
+			options: [{
+				value: "symlink",
+				label: "Symlink",
+				hint: "One source of truth; best on macOS / Linux"
+			}, {
+				value: "copy",
+				label: "Copy",
+				hint: "Duplicate files; safest on Windows / sandboxes"
+			}],
+			initialValue: "symlink"
+		});
+		if (isCancel(mode)) {
+			cancel("Cancelled.");
+			return false;
+		}
+		linkMode = mode;
+	}
+	note([
+		`Project: ${opts.projectRoot}`,
+		"Will write: .agents/rules, .agents/skills",
+		...summarizeTargets(targets).map((l) => `• ${l}`)
+	].join("\n"), "Summary");
+	const ok = await confirm({
+		message: "Proceed?",
+		initialValue: true
+	});
+	if (isCancel(ok) || !ok) {
+		cancel("Cancelled.");
+		return false;
+	}
+	const success = runAgentsInit({
+		projectRoot: opts.projectRoot,
+		force: opts.force,
+		targets,
+		linkMode
+	});
+	if (success) outro("Done. Edit .agents/ for your team; restart IDEs if rules did not reload.");
+	return success;
+}
+//#endregion
+export { runAgentsInitInteractive };

package/dist/cmd-agents-Dph66vnf.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { t as runAgentsInit } from "./agents-init-COkjrzc5.mjs";
+//#region src/cli/cmd-agents.ts
+async function runAgentsInitCmd(opts) {
+	if (opts.interactive) {
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			console.error("codemap: --interactive requires an interactive terminal (TTY).");
+			process.exit(1);
+		}
+		const { runAgentsInitInteractive } = await import("./agents-init-interactive-HLqgP8gL.mjs");
+		return runAgentsInitInteractive(opts);
+	}
+	return runAgentsInit(opts);
+}
+//#endregion
+export { runAgentsInitCmd };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 
-import { n as CodemapDatabase, t as ParsedFile } from "./parsed-types-udxNyD9e.mjs";
+import { n as CodemapDatabase, t as ParsedFile } from "./parsed-types-CtqqGr-K.mjs";
 import { z } from "zod";
 
 //#region src/application/types.d.ts

package/dist/index.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 //#endregion
 //#region src/version.ts
 /** Package version from `package.json` (inlined at build time). */
-const CODEMAP_VERSION = "0.1.1";
+const CODEMAP_VERSION = "0.1.3";
 //#endregion
 //#region src/cli/bootstrap.ts
 /** Printed for `codemap --help` / `-h` (must run before config or DB access). */
@@ -23,7 +23,7 @@ Query:
   codemap query "<SQL>"
 
 Agents:
-  codemap agents init [--force]
+  codemap agents init [--force] [--interactive|-i]
 
 Other:
   codemap version
@@ -48,7 +48,7 @@ function validateIndexModeArgs(rest) {
 	if (rest[0] === "query") return;
 	if (rest[0] === "agents") {
 		if (rest[1] === "init") return;
-		console.error(`codemap: unknown agents command "${rest[1] ?? "(missing)"}". Expected: codemap agents init [--force]`);
+		console.error(`codemap: unknown agents command "${rest[1] ?? "(missing)"}". Expected: codemap agents init [--force] [--interactive|-i]`);
 		process.exit(1);
 	}
 	let i = 0;
@@ -116,17 +116,34 @@ async function main() {
 	}
 	if (rest[0] === "agents" && rest[1] === "init") {
 		if (rest.includes("--help") || rest.includes("-h")) {
-			console.log(`Usage: codemap agents init [--force]
+			console.log(`Usage: codemap agents init [--force] [--interactive|-i]
 
 Copies bundled agent templates into .agents/ under the project root.
-Use --force to overwrite an existing .agents/ directory.
+  --force        Refresh only files that ship in templates/agents (merge into rules/ & skills/)
+  --interactive  Pick IDEs (Cursor, Copilot, Windsurf, …) and symlink vs copy
 `);
 			return;
 		}
-		const { runAgentsInitCmd } = await import("./cmd-agents-BJPx1vGG.mjs");
-		if (!runAgentsInitCmd({
+		const initRest = rest.slice(2);
+		const knownInit = new Set([
+			"--force",
+			"--interactive",
+			"-i",
+			"--help",
+			"-h"
+		]);
+		for (const a of initRest) {
+			if (knownInit.has(a)) continue;
+			if (a.startsWith("-")) console.error(`codemap: unknown option "${a}"`);
+			else console.error(`codemap: unexpected argument "${a}"`);
+			console.error("Run codemap agents init --help for usage.");
+			process.exit(1);
+		}
+		const { runAgentsInitCmd } = await import("./cmd-agents-Dph66vnf.mjs");
+		if (!await runAgentsInitCmd({
 			projectRoot: root,
-			force: rest.includes("--force")
+			force: rest.includes("--force"),
+			interactive: rest.includes("--interactive") || rest.includes("-i")
 		})) process.exit(1);
 		return;
 	}
@@ -140,7 +157,7 @@ Example: codemap query "SELECT name, file_path FROM symbols LIMIT 10"
 `);
 			return;
 		}
-		const { runQueryCmd } = await import("./cmd-query-D3zXZu7K.mjs");
+		const { runQueryCmd } = await import("./cmd-query-lSSRXMX8.mjs");
 		await runQueryCmd({
 			root,
 			configFile,
@@ -148,7 +165,7 @@ Example: codemap query "SELECT name, file_path FROM symbols LIMIT 10"
 		});
 		return;
 	}
-	const { runIndexCmd } = await import("./cmd-index-oyoHr0c4.mjs");
+	const { runIndexCmd } = await import("./cmd-index-UeGdciH7.mjs");
 	await runIndexCmd({
 		root,
 		configFile,

package/dist/parse-worker.d.mts

@@ -1,5 +1,5 @@
 
-import { t as ParsedFile } from "./parsed-types-udxNyD9e.mjs";
+import { t as ParsedFile } from "./parsed-types-CtqqGr-K.mjs";
 
 //#region src/parse-worker-core.d.ts
 interface WorkerInput {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-code/codemap",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Query your codebase — structural SQLite index for AI agents",
   "keywords": [
     "agents",
@@ -66,6 +66,7 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
+    "@clack/prompts": "^1.2.0",
     "better-sqlite3": "^12.8.0",
     "fast-glob": "^3.3.3",
     "lightningcss": "^1.32.0",

package/templates/agents/README.md

@@ -1,5 +1,9 @@
 # Bundled agent templates
 
-These files are **copies** of the upstream [`.agents/`](../../.agents/) rules and skills shipped with `@stainless-code/codemap` for `codemap agents init`.
+These files ship with **`@stainless-code/codemap`** for **`codemap agents init`** — written for **npm consumers** ( **`codemap`**, **`npx @stainless-code/codemap`**, etc.).
 
-After running the command, **edit** `.agents/` in your project (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.
+In **this** repository, **`.agents/`** (and **`.cursor/`** symlinks) are **maintainer / dev** copies: examples use **`bun src/index.ts`** where that matters. **`templates/agents/`** is the **published** agent surface and is **not** required to match **`.agents/`** byte-for-byte (the **codemap** rule and skill intentionally differ).
+
+**Documentation:** [docs/agents.md](../../docs/agents.md) — interactive setup, **`.gitignore`**, and optional IDE wiring (Cursor, Copilot, …).
+
+After running the command in **your** project, **edit** **`.agents/`** there (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.

package/templates/agents/rules/codemap.mdc

@@ -8,24 +8,33 @@ alwaysApply: true
 
 A local database (default **`.codemap.db`**) indexes structure: symbols, imports, exports, components, dependencies, markers, CSS variables, CSS classes, CSS keyframes.
 
-**Generic defaults:** This rule is **project-agnostic**. After you vendor or symlink it (or use a future `codemap` CLI that writes agent files), **edit your copy** to add app-specific triggers and SQL — upstream text is only a baseline.
+**Generic defaults:** This rule is **project-agnostic**. After **`codemap agents init`** (or copying these files into **`.agents/`**), **edit your copy** to add app-specific triggers and SQL — upstream text is only a baseline.
 
-## CLI (this repo vs installed package)
+## CLI (npm package **`@stainless-code/codemap`**)
 
-| Context | Incremental index | Query |
-| ------- | ----------------- | ----- |
-| Developing in this repo | `bun src/index.ts` | `bun src/index.ts query "<SQL>"` |
-| After `bun link` / global `codemap` | `codemap` | `codemap query "<SQL>"` |
-| Published package (when available) | `bunx @stainless-code/codemap` | `bunx @stainless-code/codemap query "<SQL>"` |
+Install **[@stainless-code/codemap](https://www.npmjs.com/package/@stainless-code/codemap)** from npm. The executable name is **`codemap`**.
 
-Index another project: **`--root /path/to/repo`**, or set **`CODEMAP_ROOT`** or **`CODEMAP_TEST_BENCH`** (e.g. in **`.env`** in this repo — see [docs/benchmark.md § Indexing another project](../../docs/benchmark.md#indexing-another-project)). Full rebuild: **`--full`**. Targeted re-index: **`--files path/to/a.ts path/to/b.tsx`**.
+**Run without a global install:** **`npx @stainless-code/codemap`** (npm), **`pnpm dlx @stainless-code/codemap`** (pnpm), **`yarn dlx @stainless-code/codemap`** (Yarn 2+), or **`bunx @stainless-code/codemap`** (Bun) — same flags everywhere. With a **local** devDependency, **`npx codemap`** / **`pnpm exec codemap`**. With a **global** install, **`codemap`** on your **`PATH`**.
+
+**Examples below use `codemap`** — prefix with **`npx @stainless-code/codemap`** (or **`pnpm dlx`**, **`yarn dlx`**, **`bunx`**) when the CLI is not on your **`PATH`**.
+
+| Action | Command |
+| ------ | ------- |
+| Incremental index | `codemap` |
+| Query | `codemap query "<SQL>"` |
+
+**Bundled rules/skills:** **`codemap agents init`** writes **`.agents/`** from the package (see [docs/agents.md](../../../docs/agents.md)).
+
+Index another project: **`--root /path/to/repo`**, or set **`CODEMAP_ROOT`** or **`CODEMAP_TEST_BENCH`** (e.g. in **`.env`** — see [docs/benchmark.md § Indexing another project](../../../docs/benchmark.md#indexing-another-project)). Full rebuild: **`--full`**. Targeted re-index: **`--files path/to/a.ts path/to/b.tsx`**.
+
+**Developing the Codemap repo itself:** from a clone, **`bun src/index.ts`** matches **`codemap`** (same flags); see the repository README.
 
 ## Session start (do this ONCE per conversation)
 
 Run incremental indexing to catch changes made outside this session:
 
 ```bash
-bun src/index.ts
+codemap
 ```
 
 ## Pre-flight check (do this EVERY time before searching)
@@ -62,7 +71,7 @@ If the question looks like any of these → use the index:
 ## How to query
 
 ```bash
-bun src/index.ts query "<SQL>"
+codemap query "<SQL>"
 ```
 
 ## Quick reference queries
@@ -94,13 +103,13 @@ For the full schema, advanced query patterns, and troubleshooting, read the skil
 
 ```bash
 # Targeted — re-index only the files you just touched
-bun src/index.ts --files path/to/file1.tsx path/to/file2.ts
+codemap --files path/to/file1.tsx path/to/file2.ts
 
 # Incremental — auto-detects changed files via git
-bun src/index.ts
+codemap
 
 # Full rebuild — after rebase, branch switch, or stale index
-bun src/index.ts --full
+codemap --full
 ```
 
 ### When to re-index

package/templates/agents/skills/codemap/SKILL.md

@@ -6,15 +6,15 @@ Query codebase structure via SQLite instead of scanning files. Use when explorin
 
 Examples below use **placeholders** (`'...'`, `getConfig`, `~/lib/api`, etc.) — not a real product tree. **Shipped skill and rules stay generic** so they apply to any repo.
 
-**In your project:** copy or symlink these files into `.agents/` / `.cursor/` (see **`.github/CONTRIBUTING.md`**), or use a future **`codemap` CLI** that vendors agent files. Then **edit your copy** to add your team’s tsconfig aliases, directory conventions, and SQL snippets you reuse. Treat upstream updates as a reference; merge deliberately.
+**In your project:** run **`codemap agents init`** (ships **`.agents/`** from **[@stainless-code/codemap](https://www.npmjs.com/package/@stainless-code/codemap)**), or copy/symlink rules and skills manually (see your repo’s contributor docs). Then **edit your copy** to add your team’s tsconfig aliases, directory conventions, and SQL snippets you reuse. Treat upstream updates as a reference; merge deliberately.
 
-**Run queries**
+**Run queries** (same CLI everywhere — use **`npx @stainless-code/codemap`**, **`pnpm dlx @stainless-code/codemap`**, **`yarn dlx @stainless-code/codemap`**, or **`bunx @stainless-code/codemap`** if **`codemap`** is not on your **`PATH`**):
 
 ```bash
-bun src/index.ts query "<SQL>"
+codemap query "<SQL>"
 ```
 
-When the package is installed globally or via `bunx`: `codemap query "<SQL>"` or `bunx @stainless-code/codemap query "<SQL>"`. Use **`--root`** to point at another project.
+Use **`codemap --root /path/to/project`** (or **`CODEMAP_ROOT`**) to index another tree.
 
 ## Schema
 
@@ -282,31 +282,31 @@ SELECT kind, COUNT(*) as count FROM markers GROUP BY kind;
 
 ## Maintenance
 
-From this repository:
+From the **[@stainless-code/codemap](https://www.npmjs.com/package/@stainless-code/codemap)** CLI (see the **codemap** rule for **`npx` / `pnpm dlx` / `yarn dlx` / `bunx`** invocations):
 
 ```bash
 # Targeted — re-index only specific files you just modified
-bun src/index.ts --files path/to/file.tsx path/to/other.ts
+codemap --files path/to/file.tsx path/to/other.ts
 
 # Incremental — auto-detects changes via git
-bun src/index.ts
+codemap
 
 # Full rebuild — after rebase, branch switch, or stale index
-bun src/index.ts --full
+codemap --full
 
 # Check index freshness
-bun src/index.ts query "SELECT key, value FROM meta"
+codemap query "SELECT key, value FROM meta"
 ```
 
 **Prefer `--files`** when you know which files you changed — it skips git diff and filesystem scanning for the rest of the tree. Deleted files passed to `--files` are auto-removed from the index.
 
-When Codemap is installed as a package: `codemap`, `codemap --root /path/to/project`, or `bunx @stainless-code/codemap …` (same flags).
+Same flags as **`npx @stainless-code/codemap`**, **`pnpm dlx @stainless-code/codemap`**, etc. **`codemap --root /path/to/project`** indexes another working tree.
 
 ## Troubleshooting
 
-| Problem                    | Solution                                                                                                               |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Stale results after rebase | Run `bun src/index.ts --full` (or `codemap --full` when installed)                                                     |
-| Missing file in results    | Check exclude / include globs in **`codemap.config.ts`**, **`codemap.config.json`**, or defaults in **`src/index.ts`** |
-| `resolved_path` is NULL    | Import is an external package (not in project)                                                                         |
-| Resolver errors            | Verify `tsconfig.json` paths (or **`tsconfigPath`** in config) when resolving aliases                                  |
+| Problem                    | Solution                                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Stale results after rebase | Run **`codemap --full`** (see **`npx @stainless-code/codemap`** / **`pnpm dlx`** / … above if needed)                 |
+| Missing file in results    | Check exclude / include globs in **`codemap.config.ts`**, **`codemap.config.json`**, or **`codemap --help`** defaults |
+| `resolved_path` is NULL    | Import is an external package (not in project)                                                                        |
+| Resolver errors            | Verify `tsconfig.json` paths (or **`tsconfigPath`** in config) when resolving aliases                                 |

package/dist/cmd-agents-BJPx1vGG.mjs

@@ -1,38 +0,0 @@
-#!/usr/bin/env node
-
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { cpSync, existsSync, mkdirSync } from "node:fs";
-//#region src/agents-init.ts
-/**
-* Directory containing `rules/` and `skills/` (next to `dist/` in published packages).
-*/
-function resolveAgentsTemplateDir() {
-	return join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "agents");
-}
-/**
-* Copy bundled rules and skills into `<projectRoot>/.agents/`.
-* @returns `false` when `.agents/` exists and `--force` was not used.
-*/
-function runAgentsInit(options) {
-	const templateRoot = resolveAgentsTemplateDir();
-	if (!existsSync(templateRoot)) throw new Error(`Codemap: agent templates not found at ${templateRoot} (expected npm package layout: templates/agents next to dist/)`);
-	const destRoot = join(options.projectRoot, ".agents");
-	if (existsSync(destRoot) && !options.force) {
-		console.error(`  .agents/ already exists at ${destRoot}. Re-run with --force to overwrite, or remove the directory.`);
-		return false;
-	}
-	mkdirSync(destRoot, { recursive: true });
-	cpSync(join(templateRoot, "rules"), join(destRoot, "rules"), { recursive: true });
-	cpSync(join(templateRoot, "skills"), join(destRoot, "skills"), { recursive: true });
-	console.log(`  Wrote agent templates to ${destRoot}`);
-	console.log(`  Symlink into .cursor/ if needed — see https://github.com/stainless-code/codemap/blob/main/.github/CONTRIBUTING.md`);
-	return true;
-}
-//#endregion
-//#region src/cli/cmd-agents.ts
-function runAgentsInitCmd(opts) {
-	return runAgentsInit(opts);
-}
-//#endregion
-export { runAgentsInitCmd };

package/templates/agents/rules/agents-first-convention.mdc

@@ -1,37 +0,0 @@
----
-description: When creating or moving rules/skills, always store the source file in .agents/ and symlink from .cursor/
-alwaysApply: true
----
-
-# Agents-First File Convention
-
-When creating **any** new rule or skill, follow this convention:
-
-## Rules (`.mdc` files)
-
-1. Create the file in `.agents/rules/<name>.mdc`
-2. Create a symlink in `.cursor/rules/`:
-
-   ```bash
-   ln -s ../../.agents/rules/<name>.mdc .cursor/rules/<name>.mdc
-   ```
-
-## Skills (`SKILL.md` files)
-
-1. Create the directory and file in `.agents/skills/<name>/SKILL.md`
-2. Create a symlink in `.cursor/skills/`:
-
-   ```bash
-   ln -s ../../.agents/skills/<name> .cursor/skills/<name>
-   ```
-
-## Why
-
-- `.agents/` is the **source of truth** — it is IDE-agnostic and works across different AI coding tools.
-- `.cursor/` only contains **symlinks** pointing back to `.agents/`.
-- This keeps configuration portable and avoids duplication.
-
-## Never
-
-- Never place original rule/skill content directly in `.cursor/rules/` or `.cursor/skills/`.
-- Never create a rule or skill without both the `.agents/` file and the `.cursor/` symlink.