stainless-code · SutuSebastian · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026
diff --git a/.changeset/agents-init-gitignore.md b/.changeset/agents-init-gitignore.md
@@ -0,0 +1,7 @@
+---
+"@stainless-code/codemap": patch
+---
+
+**`codemap agents init`:** For Git repos, ensure **`.codemap.*`** is in **`.gitignore`** (create the file or append the line once). **`--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. Depends on **`@clack/prompts`**.
+
+**Docs:** New hub section **[`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.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -52,7 +52,7 @@ Releases: **[@changesets/cli](https://github.com/changesets/changesets)** — ru
 
 ## Agent rules and skills (`.agents/`)
 
-**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
+**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm; see [docs/agents.md](../docs/agents.md)) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
 
 Rules live under **`.agents/rules/`**; skills under **`.agents/skills/<name>/SKILL.md`**. Symlink each into **`.cursor/`** (see [agents-first-convention.mdc](../.agents/rules/agents-first-convention.mdc)):
 

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,7 +6,7 @@
 
 - [ ] `bun run check` passes (format, lint, test, typecheck, build)
 - [ ] User-facing change? **Add a [Changeset](https://github.com/changesets/changesets)** (`bun run changeset`) and commit the `.changeset/*.md` file
-- [ ] Docs updated if behavior or public API changed
+- [ ] Docs updated if behavior or public API changed — hub: [`docs/README.md`](../docs/README.md); CLI/agents: [`docs/agents.md`](../docs/agents.md)
 
 ## Notes
 

diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,5 @@
 node_modules/
-.codemap.db
-.codemap.db-wal
-.codemap.db-shm
+.codemap.*
 .DS_Store
 dist/
 *.tgz

diff --git a/README.md b/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) indexes technical docs (architecture, **[`docs/agents.md`](docs/agents.md)** for `codemap agents init`, packaging, roadmap, benchmarks). **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).

diff --git a/bun.lock b/bun.lock
diff --git a/docs/README.md b/docs/README.md
@@ -5,11 +5,12 @@ Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code
 | File                                 | Topic                                                                                                                                                                               |
 | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [architecture.md](./architecture.md) | Schema, layering, CLI, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files)                                               |
+| [agents.md](./agents.md)             | **`codemap agents init`**, **`--interactive`**, **`.gitignore` / `.codemap.*`**, IDE wiring (Cursor, Copilot, Windsurf, …), **`templates/agents`**                                  |
 | [benchmark.md](./benchmark.md)       | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
 | [packaging.md](./packaging.md)       | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets)                |
 | [roadmap.md](./roadmap.md)           | Forward-looking backlog (not a `src/` inventory)                                                                                                                                    |
 | [why-codemap.md](./why-codemap.md)   | Why index + SQL for agents (speed, tokens, accuracy)                                                                                                                                |
 
-**Cross-cutting:** Runtime splits (SQLite, workers, globs, JSON config I/O) — [packaging § Node vs Bun](./packaging.md#node-vs-bun) only (link it; don’t copy the table). **User config** shape/validation — [architecture § User config](./architecture.md#user-config) only.
+**Cross-cutting:** Runtime splits (SQLite, workers, globs, JSON config I/O) — [packaging § Node vs Bun](./packaging.md#node-vs-bun) only (link it; don’t copy the table). **User config** shape/validation — [architecture § User config](./architecture.md#user-config) only. **Agent templates / `agents init`** — [agents.md](./agents.md) only (don’t duplicate the IDE table elsewhere).
 
 **Conventions:** One topic per file; relative links; avoid stale file/symbol counts in narrative docs (use `codemap query` / `bun run dev query` after indexing; methodology tables in [benchmark.md](./benchmark.md) are fine). **This repo:** `bun run dev` → `bun src/index.ts`; `bun run build` → tsdown → `dist/`; `bun run clean` / `bun run check-updates` — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md). **Contributors:** branch + PR into **`main`** ([CI](../.github/workflows/ci.yml)), `bun run check`, JSDoc on public API.
diff --git a/docs/agents.md b/docs/agents.md
@@ -0,0 +1,59 @@
+# Agent templates and `codemap agents init`
+
+Hub: [README.md](./README.md). **Package layout:** [packaging.md](./packaging.md) (`templates/` on npm). **CLI layering:** [architecture.md § Key Files](./architecture.md#key-files).
+
+## What it does
+
+The published package ships **`templates/agents/`** (rules + skills; mirrored in this repo under [`.agents/`](../.agents/)). The command **`codemap agents init`** copies that tree into **`<project>/.agents/`** — the **canonical** copy consumers edit (SQL, team conventions, paths).
+
+```bash
+codemap agents init
+codemap agents init --force
+codemap agents init --interactive   # or -i; requires a TTY
+```
+
+- **`--force`** — replace an existing **`.agents/`** directory.
+- **`--interactive`** — multiselect which tools to wire (see below); choose **symlink** vs **copy** for integrations that mirror **`.agents/rules`** (and Cursor also **`.agents/skills`**). Uses [**@clack/prompts**](https://github.com/bombshell-dev/clack); **non-TTY** runs exit with an error.
+
+## Git and `.gitignore`
+
+If **`<project>/.git`** exists, Codemap ensures **`.codemap.*`** is listed so SQLite artifacts (e.g. **`.codemap.db`**, WAL/SHM) stay untracked:
+
+- No **`.gitignore`** → create one containing **`.codemap.*`**.
+- **`.gitignore`** exists → append **`.codemap.*`** once if missing.
+
+If the project is **not** a Git working tree, **`.gitignore`** is not created.
+
+## Optional IDE / tool wiring
+
+All integrations reuse the **same** bundled content under **`.agents/`**. Symlink-style rows use one **link mode** for the whole run (**symlink** or **copy**) when any of them is selected.
+
+| Integration                           | What gets created                                          | Notes                                                                                                                               |
+| ------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **Cursor**                            | **`.cursor/rules`**, **`.cursor/skills`** → **`.agents/`** | Symlink or copy both trees.                                                                                                         |
+| **Windsurf**                          | **`.windsurf/rules`** → **`.agents/rules`**                | Rules only.                                                                                                                         |
+| **Continue**                          | **`.continue/rules`** → **`.agents/rules`**                | [Continue rules](https://docs.continue.dev/customize/rules).                                                                        |
+| **Cline**                             | **`.clinerules`** → **`.agents/rules`**                    | Directory symlink/copy.                                                                                                             |
+| **Amazon Q**                          | **`.amazonq/rules`** → **`.agents/rules`**                 | [AWS rules](https://aws.amazon.com/blogs/devops/mastering-amazon-q-developer-with-rules/).                                          |
+| **GitHub Copilot**                    | **`.github/copilot-instructions.md`**                      | Pointer + link to [GitHub Docs](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot). |
+| **Claude Code**                       | **`CLAUDE.md`**                                            | Root onboarding pointer.                                                                                                            |
+| **Zed / JetBrains / Aider (generic)** | **`AGENTS.md`**                                            | Many tools read root **`AGENTS.md`**; JetBrains/Aider have no single mandated path — this file is the shared hook.                  |
+| **Gemini**                            | **`GEMINI.md`**                                            | For integrations that load **`GEMINI.md`**.                                                                                         |
+
+Pointer files (**`CLAUDE.md`**, **`AGENTS.md`**, **`GEMINI.md`**, Copilot instructions) are **skipped** if the file already exists unless **`--force`** (then overwritten where applicable).
+
+## Implementation (for contributors)
+
+| Source                               | Role                                                                                                                                                 |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`src/agents-init.ts`**             | Copy **`templates/agents`** → **`.agents/`**, **`applyAgentsInitTargets`**, **`ensureGitignoreCodemapPattern`**, exported **`targetsNeedLinkMode`**. |
+| **`src/agents-init-interactive.ts`** | **`@clack/prompts`** flow; calls **`runAgentsInit`**.                                                                                                |
+| **`src/cli/cmd-agents.ts`**          | Lazy-loaded from **`src/cli/main.ts`**.                                                                                                              |
+
+Do **not** duplicate long IDE matrices in **README.md** or **packaging.md** — link **here** instead.
+
+## Related
+
+- [architecture.md](./architecture.md) — CLI chunks, layering.
+- [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md) — Cursor symlink notes, **`main`** / PR workflow.
+- [why-codemap.md](./why-codemap.md) — why SQL + index for agents.