@stainless-code/codemap 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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.2";
+const CODEMAP_VERSION = "0.1.3";
 //#endregion
 //#region src/cli/bootstrap.ts
 /** Printed for `codemap --help` / `-h` (must run before config or DB access). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-code/codemap",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Query your codebase — structural SQLite index for AI agents",
   "keywords": [
     "agents",

package/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.

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/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.