chore: npm agent templates vs dev .agents, patch changeset

.agents/rules/codemap.mdc

@@ -8,17 +8,18 @@ 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.
+**This file** is for **developing Codemap** in this clone. **End users** of the published package get the agent rule from **`templates/agents/`** (via **`codemap agents init`**). **Generic defaults:** SQL and triggers stay project-agnostic — **edit** this rule for repo-specific paths and queries.
 
-## CLI (this repo vs installed package)
+## CLI (this repository)
 
 | 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>"` |
+| **Default** — from this clone | `bun src/index.ts` | `bun src/index.ts query "<SQL>"` |
+| Same entry | `bun run dev` | (same as first row) |
 
-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`**.
+After **`bun run build`**, **`node dist/index.mjs`** matches the published **`codemap`** binary (same flags). **`bun link`** / global **`codemap`** also work when testing the packaged CLI.
+
+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`**.
 
 ## Session start (do this ONCE per conversation)
 

.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.
+**This repository:** run the CLI with **`bun src/index.ts`** (same as **`bun run dev`**). **Consumer / npm** copy of this skill lives under **`templates/agents/skills/codemap/`** (installed with **`codemap agents init`**). Edit **`.agents/`** here for Codemap development; **do not** treat it as the published package layout.
 
-**Run queries**
+**Run queries:**
 
 ```bash
 bun src/index.ts 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.
+After **`bun run build`**, **`node dist/index.mjs query …`** or a linked **`codemap`** binary matches the published CLI. Use **`--root`** / **`CODEMAP_ROOT`** to index another tree.
 
 ## Schema
 
@@ -282,7 +282,7 @@ SELECT kind, COUNT(*) as count FROM markers GROUP BY kind;
 
 ## Maintenance
 
-From this repository:
+From this repository (same flags as the published **`codemap`** binary):
 
 ```bash
 # Targeted — re-index only specific files you just modified
@@ -300,13 +300,13 @@ bun src/index.ts 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).
+**End-user / npm** commands: **`templates/agents/skills/codemap/SKILL.md`** ( **`npx @stainless-code/codemap`**, **`codemap`** on **`PATH`**, etc.).
 
 ## Troubleshooting
 
 | Problem                    | Solution                                                                                                               |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Stale results after rebase | Run `bun src/index.ts --full` (or `codemap --full` when installed)                                                     |
+| Stale results after rebase | Run **`bun src/index.ts --full`** (or **`codemap --full`** when exercising the packaged CLI)                           |
 | 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                                  |

.changeset/agent-templates-npm-dev-split.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+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`.

docs/agents.md

@@ -4,7 +4,7 @@
 
 ## What it does
 
-The published package ships **`templates/agents/`** (rules + skills; mirrored in this repo under [`.agents/`](../.agents/)). The command **`codemap agents init`** writes each bundled file into **`<project>/.agents/`** with per-file copies (not a wholesale directory sync) — the **canonical** copy consumers edit (SQL, team conventions, paths).
+The published package ships **`templates/agents/`** (rules + skills). This repo also has [`.agents/`](../.agents/) for **Codemap development** (CLI from source); it is **not** identical to **`templates/agents/`** for every file (e.g. the **codemap** rule/skill). The command **`codemap agents init`** writes each bundled template file into **`<project>/.agents/`** with per-file copies (not a wholesale directory sync) — the **canonical** copy consumers edit (SQL, team conventions, paths).
 
 ```bash
 codemap agents init

templates/agents/README.md

@@ -1,7 +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.).
+
+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, **edit** `.agents/` in your project (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.
+After running the command in **your** project, **edit** **`.agents/`** there (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.

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

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                                 |