@cstart/coldstart 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,27 @@
-# coldstart
+<div align="center">
 
-Codebase navigation **and a codebase notebook** for AI agents.
+<h1>❄️&nbsp; coldstart</h1>
+
+<p>
+  <b>Codebase navigation and a codebase notebook for AI agents.</b><br/>
+  Find the right file in milliseconds — and remember what the last session figured out.
+</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/@cstart/coldstart"><img alt="npm version" src="https://img.shields.io/npm/v/%40cstart%2Fcoldstart?style=flat-square&amp;label=npm&amp;color=16708f&amp;labelColor=0d1520"></a>
+  <img alt="node &gt;= 18" src="https://img.shields.io/badge/node-%E2%89%A5%2018-16708f?style=flat-square&amp;labelColor=0d1520">
+  <a href="#license"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-16708f?style=flat-square&amp;labelColor=0d1520"></a>
+  <img alt="for Claude Code, Codex, Cursor" src="https://img.shields.io/badge/for-Claude%20Code%2C%20Codex%2C%20Cursor-c26714?style=flat-square&amp;labelColor=0d1520">
+</p>
+
+<p>
+  <a href="https://akashgoenka.github.io/coldstart/"><b>Website</b></a> &nbsp;·&nbsp;
+  <a href="https://akashgoenka.github.io/coldstart/docs.html"><b>Docs</b></a> &nbsp;·&nbsp;
+  <a href="./PHILOSOPHY.md"><b>Philosophy</b></a> &nbsp;·&nbsp;
+  <a href="https://www.npmjs.com/package/@cstart/coldstart"><b>npm</b></a>
+</p>
+
+</div>
 
 Two layers, one tool:
 
@@ -11,6 +32,43 @@ No embeddings, no model to run, no service to babysit. Agents are already good a
 
 ---
 
+## Install
+
+Requires Node.js 18+.
+
+```bash
+npm install -g @cstart/coldstart --legacy-peer-deps
+cd your-project
+coldstart init      # navigation: coldstart.md + client wiring + background index warm-up
+coldstart kb init   # notebook: skeleton + capture/recall hooks (optional but recommended)
+```
+
+`init` asks two things — the **experience** (`cli`, recommended, or `mcp`) and the **client** — then writes a single `coldstart.md` at your repo root (the agent-facing guidance) and wires it in. Pass `--experience` / `--client` to skip the prompts. The client is never auto-detected; you always pick it.
+
+- **Claude Code** → ensures `CLAUDE.md` imports it via `@coldstart.md`, and registers the find/gs search hooks in `.claude/settings.json` (a PostToolUse nudge + a PreToolUse find-dedup guard — merged into any existing settings, never overwriting them). The `mcp` experience also writes `.mcp.json`.
+- **Codex** → adds a coldstart section to `AGENTS.md` and registers Codex-specific navigation plus notebook hooks in `.codex/hooks.json`. The capture hook understands Codex rollout and subagent transcripts. The `mcp` experience also writes `[mcp_servers.coldstart]` into `.codex/config.toml`.
+- **Cursor** → writes `.cursor/rules/coldstart.mdc` (an always-applied rule referencing `@coldstart.md`) and registers Cursor-specific navigation plus notebook hooks in `.cursor/hooks.json` (a `preToolUse` find-dedup guard, a `postToolUse` nudge, `beforeSubmitPrompt` recall, and `stop`/`subagentStop` capture — merged into any existing hooks). The capture hook parses Cursor's own conversation transcript. The `mcp` experience also writes `.cursor/mcp.json`.
+- **Other** → writes `coldstart.md` only, and prints the wiring directions (plus the MCP server entry for the `mcp` experience).
+
+`init` then warms the index in the background, so your first lookup is instant. Re-running either init is safe — they never duplicate entries.
+
+> [!IMPORTANT]
+> **Why `--legacy-peer-deps`?** The tree-sitter grammar packages under-declare their peer-dep ranges (some say `^0.21.x`, others `^0.22.x`). Without the flag npm's strict resolver enters a long retry loop on a cold cache and can appear to hang. The flag tells npm to use our tested versions as-is. We can't set it from inside the package — npm reads install config only from your environment.
+
+### Upgrading
+
+```bash
+npm install -g @cstart/coldstart@latest --legacy-peer-deps
+coldstart init   # re-run in each project to refresh coldstart.md
+```
+
+A version stamp in the keeper's lockfile makes the old background keeper shut down on the next lookup; a fresh one spawns from the new binary. No manual restart needed.
+
+> [!NOTE]
+> **Migrating from `coldstart-mcp`:** the package was renamed `coldstart-mcp` → **`coldstart`** at 2.0.0 (the CLI is now the primary surface). `coldstart-mcp` is deprecated but still installs; switch with `npm uninstall -g coldstart-mcp && npm install -g coldstart --legacy-peer-deps && coldstart init`. The `coldstart-mcp` binary name is kept as an alias, so existing MCP configs keep working.
+
+---
+
 ## The notebook
 
 A repo-local knowledge base written and read by agents, in `.coldstart/notebook/`:
@@ -44,7 +102,8 @@ coldstart kb status / lint / render / init / migrate
 
 **Language-agnostic.** The notebook's freshness machinery is content-hash based, so it works on any codebase — including languages the navigation index doesn't parse. Where the index does parse, notes additionally get symbol-level freshness.
 
-The notebook is young. What's verified today: notes written by agents in real sessions checked out accurate against the code; the stale-note loop closes end-to-end (flag → re-read → correction); capture, recall, and concurrent writes hold up under stress. The bet — stated as a bet — is that a corpus like this compounds over a repo's lifetime: the second time any question comes up, the answer is one `Read` away instead of a re-derivation.
+> [!NOTE]
+> **The notebook is young.** What's verified today: notes written by agents in real sessions checked out accurate against the code; the stale-note loop closes end-to-end (flag → re-read → correction); capture, recall, and concurrent writes hold up under stress. The bet — stated as a bet — is that a corpus like this compounds over a repo's lifetime: the second time any question comes up, the answer is one `Read` away instead of a re-derivation.
 
 ---
 
@@ -57,13 +116,23 @@ The notebook is young. What's verified today: notes written by agents in real se
 
 The intended flow: **`find`** a concept → pick the best path → **`gs`** that file for its shape and who uses it → `Read` only for the implementation inside a method body. Notebook summaries ride along on `find` results, so often the orientation step answers itself.
 
+```mermaid
+flowchart LR
+    A["coldstart find<br/>which files?"] --> B["coldstart gs<br/>what is it? who uses it?"] --> C["Read<br/>just the method body"]
+    class A,B cold
+    class C warm
+    classDef cold stroke:#16708f,stroke-width:2px
+    classDef warm stroke:#c26714,stroke-width:2px
+```
+
 ### `find` — locate the files for a concept
 
 ```bash
 coldstart find auth session cookie
 ```
 
-Pass **every salient identifier** from your task — the symbol, the domain noun, the rare token you half-remember — not one distilled keyword. `find` ranks files by how many of your terms each one covers and shows, per file, which terms it defines vs. imports and a preview of the lines where they cluster. Often that's enough to answer without opening anything.
+> [!TIP]
+> **Pass every salient identifier** from your task — the symbol, the domain noun, the rare token you half-remember — not one distilled keyword. `find` ranks files by how many of your terms each one covers and shows, per file, which terms it defines vs. imports and a preview of the lines where they cluster. Often that's enough to answer without opening anything.
 
 Speed-wise, `find` competes with raw grep: its repo-wide reference pass runs on **ripgrep** — yours from PATH, the bundled copy, or an editor's (`COLDSTART_RG` overrides) — with `git grep`/`grep` fallbacks, and the ranked page comes from the pre-built index, not a scan.
 
@@ -108,55 +177,18 @@ The notebook is the same philosophy applied to memory: coldstart still computes
 
 ---
 
-## Install
-
-Requires Node.js 18+.
-
-```bash
-npm install -g @cstart/coldstart --legacy-peer-deps
-cd your-project
-coldstart init      # navigation: coldstart.md + client wiring + background index warm-up
-coldstart kb init   # notebook: skeleton + capture/recall hooks (optional but recommended)
-```
-
-`init` asks two things — the **experience** (`cli`, recommended, or `mcp`) and the **client** — then writes a single `coldstart.md` at your repo root (the agent-facing guidance) and wires it in. Pass `--experience` / `--client` to skip the prompts. The client is never auto-detected; you always pick it.
-
-- **Claude Code** → ensures `CLAUDE.md` imports it via `@coldstart.md`, and registers the find/gs search hooks in `.claude/settings.json` (a PostToolUse nudge + a PreToolUse find-dedup guard — merged into any existing settings, never overwriting them). The `mcp` experience also writes `.mcp.json`.
-- **Codex** → adds a coldstart section to `AGENTS.md` and registers Codex-specific navigation plus notebook hooks in `.codex/hooks.json`. The capture hook understands Codex rollout and subagent transcripts. The `mcp` experience also writes `[mcp_servers.coldstart]` into `.codex/config.toml`.
-- **Cursor** → writes `.cursor/rules/coldstart.mdc` (an always-applied rule referencing `@coldstart.md`) and registers Cursor-specific navigation plus notebook hooks in `.cursor/hooks.json` (a `preToolUse` find-dedup guard, a `postToolUse` nudge, `beforeSubmitPrompt` recall, and `stop`/`subagentStop` capture — merged into any existing hooks). The capture hook parses Cursor's own conversation transcript. The `mcp` experience also writes `.cursor/mcp.json`.
-- **Other** → writes `coldstart.md` only, and prints the wiring directions (plus the MCP server entry for the `mcp` experience).
-
-`init` then warms the index in the background, so your first lookup is instant. Re-running either init is safe — they never duplicate entries.
-
-> **Why `--legacy-peer-deps`?** The tree-sitter grammar packages under-declare their peer-dep ranges (some say `^0.21.x`, others `^0.22.x`). Without the flag npm's strict resolver enters a long retry loop on a cold cache and can appear to hang. The flag tells npm to use our tested versions as-is. We can't set it from inside the package — npm reads install config only from your environment.
-
-### Upgrading
-
-```bash
-npm install -g @cstart/coldstart@latest --legacy-peer-deps
-coldstart init   # re-run in each project to refresh coldstart.md
-```
-
-A version stamp in the keeper's lockfile makes the old background keeper shut down on the next lookup; a fresh one spawns from the new binary. No manual restart needed.
-
-> **Migrating from `coldstart-mcp`:** the package was renamed `coldstart-mcp` → **`coldstart`** at 2.0.0 (the CLI is now the primary surface). `coldstart-mcp` is deprecated but still installs; switch with `npm uninstall -g coldstart-mcp && npm install -g coldstart --legacy-peer-deps && coldstart init`. The `coldstart-mcp` binary name is kept as an alias, so existing MCP configs keep working.
-
----
-
 ## How the index stays fresh
 
 coldstart is **one keeper, thin readers**:
 
-```
-            ┌─────────────────────────────────────────────┐
-            │  keeper  (coldstart --daemon)                │
-            │  watches repo → patch/rebuild → save cache   │   ← keeps the cache fresh, serves nothing
-            └───────────────────────┬─────────────────────┘
-                                    │ on-disk cache
-        ┌───────────────────────────┼───────────────────────────┐
-        │                           │                           │
-  coldstart find            coldstart gs                  MCP server
-  (reads cache, prints)     (reads cache, prints)   (reads cache, stdio to client)
+```mermaid
+flowchart TD
+    K["keeper — coldstart --daemon<br/>watches repo, patches/rebuilds, saves cache<br/>serves nothing"] -->|debounced save| C[("on-disk cache")]
+    C --> F["coldstart find<br/>reads cache, prints"]
+    C --> G["coldstart gs<br/>reads cache, prints"]
+    C --> M["MCP server<br/>reads cache, stdio"]
+    class K cold
+    classDef cold stroke:#16708f,stroke-width:2px
 ```
 
 - A single **keeper** process per repo watches the filesystem and keeps the on-disk cache current. It does **not** answer queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cstart/coldstart",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "publishConfig": {
     "access": "public"
   },
@@ -29,10 +29,14 @@
     "tree-sitter"
   ],
   "license": "MIT",
+  "homepage": "https://akashgoenka.github.io/coldstart/",
   "repository": {
     "type": "git",
     "url": "https://github.com/AkashGoenka/coldstart"
   },
+  "bugs": {
+    "url": "https://github.com/AkashGoenka/coldstart/issues"
+  },
   "scripts": {
     "build": "tsc --noEmit false",
     "dev": "tsc --watch",