somtum 1.0.0 → 1.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 **Local-first memory and prompt-cache layer for Claude Code.**
 
+[**Landing Page & Demo**](https://riz007.github.io/somtum/)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/somtum.svg)](https://www.npmjs.com/package/somtum)
 
@@ -18,6 +20,8 @@ Zero-config: one `somtum init` in an existing Claude Code project and every sess
 - [Requirements](#requirements)
 - [Install](#install)
 - [Quickstart](#quickstart)
+- [Verifying the setup](#verifying-the-setup)
+- [Dashboard](#dashboard)
 - [CLI Reference](#cli-reference)
 - [MCP Server](#mcp-server)
 - [Storage Layout](#storage-layout)
@@ -99,17 +103,17 @@ LLM agents like Claude Code typically start every session with a "blank slate."
 ## Requirements
 
 - **Node 20+**
-- **pnpm** (`npm i -g pnpm`)
-- **`ANTHROPIC_API_KEY`** — used by the capture hook to summarise session transcripts via Claude Haiku, and optionally by the `index` and `hybrid` retrieval strategies
+- **Claude Code** — Somtum hooks into Claude Code's `SessionEnd`, `UserPromptSubmit`, and `PreToolUse` events
+- **`ANTHROPIC_API_KEY`** — used by the capture hook to summarise session transcripts via Claude Haiku, and optionally by the `index` and `hybrid` retrieval strategies. **Must be exported in your shell profile** (see [Quickstart](#quickstart) — step 1 explains why)
+
+> `pnpm` is only required if building from source. Global npm/yarn installs have no pnpm dependency.
 
 ---
 
 ## Install
 
-### From npm / yarn / pnpm
-
 ```bash
-# npm
+# npm (recommended for global install)
 npm install -g somtum
 
 # yarn
@@ -123,8 +127,6 @@ Or as a project dependency:
 
 ```bash
 npm install somtum
-yarn add somtum
-pnpm add somtum
 ```
 
 ### From source
@@ -134,64 +136,173 @@ git clone https://github.com/riz007/somtum
 cd somtum
 pnpm install
 pnpm build
-# Optional: link globally
 pnpm link --global
 ```
 
 ### Native module note
 
-Somtum uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3), which contains a native C++ addon. On most platforms (macOS, Linux x64/arm64, Windows x64) a prebuilt binary is downloaded automatically. On Alpine Linux / musl or unusual architectures the addon compiles from source, which requires `python`, `make`, and `gcc` to be available. If the install fails with a node-gyp error, install those build tools and retry.
+Somtum uses [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3), which contains a native C++ addon. On most platforms (macOS, Linux x64/arm64, Windows x64) a prebuilt binary is downloaded automatically. On Alpine Linux / musl or unusual architectures the addon compiles from source — `python`, `make`, and `gcc` must be available. If the install fails with a node-gyp error, install those build tools and retry.
 
 ---
 
 ## Quickstart
 
+### Step 1 — Set your Anthropic API key in your shell profile
+
+> **This is the most important step.** When a Claude Code session ends, the `SessionEnd` hook runs as a subprocess launched by Claude Code. That subprocess inherits its environment from the shell that _started_ Claude Code — not from the current terminal window. If the key is only `export`-ed in an interactive session, the hook will not see it and extraction will silently fail.
+
+Add to `~/.zshrc` (or `~/.bashrc`, `~/.bash_profile`):
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+Then reload your shell:
+
+```bash
+source ~/.zshrc   # or open a new terminal
+```
+
+Confirm it's available:
+
+```bash
+echo $ANTHROPIC_API_KEY   # should print your key
+```
+
+### Step 2 — Install inside a Claude Code project
+
+Run this from the **root of the project you work in with Claude Code**:
+
 ```bash
-# 1. Inside an existing Claude Code project:
 somtum init
+```
+
+This writes a `SessionEnd` hook into `.claude/settings.json` in the current directory. Claude Code reads that file automatically when you open a session from the same directory.
 
-# Installs a SessionEnd hook in .claude/settings.json.
-# Use Claude Code as normal — observations are captured at session end.
+To enable all features at once:
 
-# 2. Search your memory
+```bash
+somtum init --all
+# Installs:
+#   - SessionEnd capture hook     (memory extraction)
+#   - UserPromptSubmit cache hook (prompt cache lookup)
+#   - PreToolUse file-gating hook (file read summaries)
+#   - MCP server in .mcp.json     (Claude can call recall/remember tools)
+```
+
+### Step 3 — Use Claude Code normally
+
+Open a Claude Code session **from the same directory** where you ran `somtum init`. Work as you normally would. When the session ends, the hook extracts observations automatically in the background (capped at 90 seconds so it never blocks you).
+
+### Step 4 — Check your memory
+
+```bash
+# How many observations were captured?
+somtum stats
+
+# Search memory
 somtum search "auth jwt rotation"
 somtum search "why we use pnpm" --strategy hybrid
 
-# 3. Read a full observation
-somtum show 01JBZ...
+# Open the visual dashboard
+somtum serve
+```
+
+If `somtum stats` shows `memories 0` after a session, see [Troubleshooting](#troubleshooting).
+
+### Step 5 — Diagnose any issues
+
+```bash
+somtum doctor
+```
+
+This checks your API key, DB health, hook installation, migrations, cache, and breakeven ratio. It will tell you exactly what is misconfigured and how to fix it.
+
+---
 
-# 4. Check your token savings
+## Verifying the setup
+
+After your **first** Claude Code session ends:
+
+**1. Check the hook log**
+
+Every hook run appends a timestamped line to `~/.somtum/hook.log`:
+
+```bash
+cat ~/.somtum/hook.log
+```
+
+A successful run looks like:
+
+```
+2026-04-30T10:15:42.123Z [post_session] starting
+2026-04-30T10:15:44.891Z [post_session] ok — inserted=4 cache=2 summaries=1
+```
+
+A failed run with a missing API key looks like:
+
+```
+2026-04-30T10:15:42.123Z [post_session] WARN: ANTHROPIC_API_KEY not set — extraction will fail
+2026-04-30T10:15:42.131Z [post_session] ERROR: 401 authentication_error
+```
+
+**2. Check stats**
+
+```bash
 somtum stats
+```
+
+You should see `memories` > 0 after a substantive session. Short test sessions may yield 0 observations if there is nothing worth extracting (Claude Code did not make decisions, fix bugs, or learn anything the extractor considers durable).
 
-# 5. Diagnose any issues
+**3. Run doctor**
+
+```bash
 somtum doctor
 ```
 
-### Enable all features at once
+All checks should show `✓`. The `api_key` and `hooks_installed` checks are the two most commonly failing.
+
+---
+
+## Dashboard
+
+Somtum includes a visual memory browser you can open at any time:
 
 ```bash
-somtum init --all
-# Installs:
-#   - SessionEnd capture hook
-#   - UserPromptSubmit prompt-cache hook
-#   - PreToolUse file-gating hook
-#   - MCP server registration in .mcp.json
+somtum serve
+# Opens http://localhost:3000 in your browser
 ```
 
+The dashboard provides:
+
+- **Memory browser** — searchable, filterable list of all captured observations. Supports BM25, hybrid, and embeddings strategies live. Click any memory to see its full body, files touched, and tags.
+- **Knowledge graph** — vis-network graph where nodes are memories and edges connect memories that share files or tags. Clicking a node opens the detail panel.
+- **Analytics** — kind breakdown, cache hit rate, retrieval strategy usage, and top-referenced files.
+- **Forget button** — soft-delete any memory directly from the browser.
+
+Options:
+
+| Flag         | Description                            |
+| ------------ | -------------------------------------- |
+| `--port <n>` | Listen on a custom port (default 3000) |
+| `--no-open`  | Don't auto-open the browser            |
+
+Press `Ctrl-C` to stop the server.
+
 ---
 
-## CLI reference
+## CLI Reference
 
 ### Setup
 
-| Command                     | Description                                         |
-| --------------------------- | --------------------------------------------------- |
-| `somtum init`               | Install the SessionEnd capture hook                 |
-| `somtum init --cache`       | Also install the UserPromptSubmit cache hook        |
-| `somtum init --file-gating` | Also install the PreToolUse file-gating hook        |
-| `somtum init --all`         | Install all hooks + MCP server                      |
-| `somtum init --force`       | Reinstall even if hooks already present             |
-| `somtum doctor`             | Check DB health, migrations, hooks, breakeven ratio |
+| Command                     | Description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
+| `somtum init`               | Install the SessionEnd capture hook                          |
+| `somtum init --cache`       | Also install the UserPromptSubmit cache hook                 |
+| `somtum init --file-gating` | Also install the PreToolUse file-gating hook                 |
+| `somtum init --all`         | Install all hooks + MCP server                               |
+| `somtum init --force`       | Reinstall even if hooks already present                      |
+| `somtum doctor`             | Check DB health, migrations, hooks, API key, breakeven ratio |
 
 ### Memory
 
@@ -204,6 +315,17 @@ somtum init --all
 | `somtum forget <id>`                    | Soft-delete an observation                       |
 | `somtum edit <id>`                      | Open an observation body in `$EDITOR`            |
 | `somtum rebuild`                        | Regenerate `index.md` from all observations      |
+| `somtum reindex`                        | Recompute embeddings (after a model change)      |
+
+### Stats & Visibility
+
+| Command                   | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `somtum stats`            | Tokens saved, cache hit rate, retrieval breakdown |
+| `somtum stats --json`     | Machine-readable JSON output                      |
+| `somtum serve`            | Open the visual dashboard in the browser          |
+| `somtum serve --port <n>` | Use a custom port (default 3000)                  |
+| `somtum serve --no-open`  | Start server without opening the browser          |
 
 ### Data management
 
@@ -217,19 +339,12 @@ somtum init --all
 | `somtum purge --older-than 30d`                   | Hard-delete soft-deleted entries older than 30 days |
 | `somtum purge --older-than 30d --dry-run`         | Preview without deleting                            |
 
-### Embeddings
+### Stats & visibility
 
 | Command          | Description                                 |
 | ---------------- | ------------------------------------------- |
 | `somtum reindex` | Embed observations that are missing vectors |
 
-### Stats
-
-| Command               | Description                                       |
-| --------------------- | ------------------------------------------------- |
-| `somtum stats`        | Tokens saved, cache hit rate, retrieval breakdown |
-| `somtum stats --json` | Machine-readable JSON output                      |
-
 ### Configuration
 
 | Command                                                        | Description                       |
@@ -247,7 +362,7 @@ somtum init --all
 | `somtum sync push`   | Export and scp observations to remote     |
 | `somtum sync pull`   | scp from remote and merge into local DB   |
 
-Remote configured in config: `somtum config set sync.remote "user@host:/path/.somtum/projects/<id>"`
+Remote configured in config: `somtum config set sync.remote "user@host:/path/.somtum/projects/<id>"`  
 Somtum uses hostname-aware syncing to prevent data loss when using multiple devices.
 
 ---
@@ -256,12 +371,33 @@ Somtum uses hostname-aware syncing to prevent data loss when using multiple devi
 
 Somtum includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. When you run `somtum init --all`, it registers tools that Claude can use autonomously:
 
-- `recall`: Claude can search your memories when it's unsure about a project detail.
-- `get`: Retrieve the full body of specific observations.
-- `remember`: Claude can manually store a specific observation.
-- `cache_lookup`: Used internally to check the prompt cache.
-- `forget`: Soft-delete an observation.
-- `stats`: Claude can report on how much it has "learned" from you.
+| Tool           | What Claude can do with it                                             |
+| -------------- | ---------------------------------------------------------------------- |
+| `recall`       | Search memories by natural language when unsure about a project detail |
+| `get`          | Retrieve the full body of specific observations by ID                  |
+| `remember`     | Manually store an observation from within a session                    |
+| `cache_lookup` | Check the prompt cache directly                                        |
+| `forget`       | Soft-delete an observation                                             |
+| `stats`        | Report on tokens saved, cache hit rate, and corpus size                |
+
+Every MCP response includes a `tokens` field so Claude can account for retrieval cost.
+
+---
+
+## Dashboard
+
+`somtum serve` opens a local web dashboard at `http://localhost:3000`:
+
+- **Memory browser** — search across all observations using BM25, hybrid, or embedding-based retrieval; filter by kind (decision, bugfix, learning, command, file_summary); forget memories directly from the UI.
+- **Knowledge graph** — vis-network graph where nodes are observations, edges represent shared files or tags. Clicking a node selects the memory in the list and vice versa.
+- **Analytics tab** — kind breakdown, token ROI (saved vs. spent), cache hit rate + entry count, retrieval strategy usage, and top files by reference count.
+- **Stat bar** — live counts for total memories, tokens saved, tokens spent, ROI ratio, and cache hit %.
+
+```bash
+somtum serve              # opens on port 3000
+somtum serve --port 4000  # custom port
+somtum serve --no-open    # don't auto-open the browser
+```
 
 ---
 
@@ -270,6 +406,7 @@ Somtum includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io
 ```
 ~/.somtum/
 ├── config.json                    ← global config (overridden by project config)
+├── hook.log                       ← timestamped log of every hook execution
 └── projects/
     └── <project_id>/
         ├── db.sqlite              ← source of truth (SQLite WAL)
@@ -279,6 +416,8 @@ Somtum includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io
                 └── <ulid>.md      ← per-observation markdown files
 ```
 
+The project ID is derived from the git remote URL (if present) or the directory path — the same project always maps to the same ID regardless of which machine you're on, as long as the remote URL matches.
+
 SQLite is the source of truth. `index.md` and `memories/*.md` are derived mirrors regenerated on each capture. Edit observations with `somtum edit <id>`, not by hand.
 
 ---
@@ -297,7 +436,7 @@ Global config lives at `~/.somtum/config.json`. Per-project config at `.somtum/c
   "cache": {
     "enabled": true,
     "fuzzy_match": true,
-    "fuzzy_threshold": 0.92, // conservative — raise to 0.95 once you have signal
+    "fuzzy_threshold": 0.92, // raise to 0.95 once you have signal
     "max_entries": 10000,
     "ttl_days": 90,
   },
@@ -361,17 +500,18 @@ somtum reindex   # embed existing observations
 
 Every `stats` figure is labelled _estimated_. Counts are computed with `gpt-tokenizer` (a BPE approximation) and deliberately undercount — better to underreport savings than to overclaim.
 
-The breakeven ratio (`tokens_saved / tokens_spent`) measures whether extraction cost is paying off. A ratio below 1.5x triggers a warning in `somtum stats` and `somtum doctor`.
+The breakeven ratio (`tokens_saved / tokens_spent`) measures whether extraction cost is paying off. A ratio below 1.5× triggers a warning in `somtum stats` and `somtum doctor`.
 
 ---
 
 ## Performance
 
-| Scenario                                | p95 budget | Actual (benchmark) |
-| --------------------------------------- | ---------- | ------------------ |
-| `UserPromptSubmit` hook at 1k memories  | 150 ms     | < 2 ms (BM25 k=8)  |
-| `UserPromptSubmit` hook at 10k memories | 300 ms     | < 30 ms (BM25 k=8) |
-| Exact cache hash lookup                 | —          | < 0.1 ms           |
+| Scenario                                | p95 budget    | Actual (benchmark)       |
+| --------------------------------------- | ------------- | ------------------------ |
+| `UserPromptSubmit` hook at 1k memories  | 150 ms        | < 2 ms (BM25 k=8)        |
+| `UserPromptSubmit` hook at 10k memories | 300 ms        | < 30 ms (BM25 k=8)       |
+| Exact cache hash lookup                 | —             | < 0.1 ms                 |
+| `SessionEnd` hook (extract + embed)     | 90 s hard cap | Exits cleanly on timeout |
 
 Run benchmarks yourself:
 
@@ -391,38 +531,49 @@ pnpm test:golden      # retrieval recall@k per strategy
 pnpm test:bench       # hot-path latency benchmarks
 pnpm lint             # eslint
 pnpm fmt              # prettier
-pnpm build            # tsc + copy migrations → dist/
+pnpm build            # tsc + copy migrations + copy dashboard → dist/
 ```
 
 ### Project layout
 
 ```
 src/
-  cli/            # commander-based CLI commands
+  cli/
+    index.ts          # commander CLI entry point
+    init.ts           # somtum init — installs hooks + MCP config
+    serve.ts          # somtum serve — local dashboard server
+    stats.ts          # somtum stats
+    doctor.ts         # somtum doctor — health checks
+    hook.ts           # internal: dispatches hook events by name
+    search.ts / show.ts / forget.ts / edit.ts
+    export.ts / import.ts / purge.ts / sync.ts / rebuild.ts / reindex.ts
+    config_cmd.ts
   core/
-    db.ts         # SQLite setup, migration runner
-    store.ts      # MemoryStore — CRUD for observations
-    cache.ts      # PromptCache — exact + fuzzy lookup
-    retriever/    # bm25, embeddings, hybrid, index, factory
-    extractor.ts  # session transcript → observations (Claude)
-    index_gen.ts  # renders index.md (incremental past 1k obs)
-    memory_files.ts  # writes memories/<YYYY-MM>/<ulid>.md
-    retrieval_stats.ts  # per-strategy call counters
-    embeddings.ts    # Embedder interface + encode/decode utils
-    privacy.ts       # redact() — runs on every capture
-    tokens.ts        # gpt-tokenizer wrapper
+    db.ts             # SQLite setup, migration runner
+    store.ts          # MemoryStore — CRUD for observations
+    cache.ts          # PromptCache — exact + fuzzy lookup
+    retriever/        # bm25, embeddings, hybrid, index, factory
+    extractor.ts      # session transcript → observations (Claude Haiku)
+    index_gen.ts      # renders index.md (incremental past 1k obs)
+    memory_files.ts   # writes memories/<YYYY-MM>/<ulid>.md
+    retrieval_stats.ts
+    embeddings.ts     # Embedder interface + encode/decode utils
+    privacy.ts        # redact() — runs on every capture
+    tokens.ts         # gpt-tokenizer wrapper
   hooks/
-    post_session.ts  # SessionEnd: extract → store → index
-    pre_prompt.ts    # UserPromptSubmit: cache lookup
-    pre_read.ts      # PreToolUse: file gating
-  mcp/             # MCP server + tool implementations
-  config.ts        # global + project config merge
-  index.ts         # public API for embedding Somtum
-src/db/migrations/ # NNN_name.sql migration files
+    post_session.ts   # SessionEnd: extract → store → index → log
+    pre_prompt.ts     # UserPromptSubmit: cache lookup
+    pre_read.ts       # PreToolUse: file gating
+  mcp/               # MCP server + tool implementations
+  dashboard/
+    index.html        # single-page dashboard (served by somtum serve)
+  config.ts          # global + project config merge
+  index.ts           # public API for embedding Somtum
+src/db/migrations/   # NNN_name.sql migration files
 test/
-  golden/          # per-strategy retrieval golden sets
-  bench/           # hot-path latency benchmarks
-  fixtures/        # synthetic session transcripts
+  golden/            # per-strategy retrieval golden sets
+  bench/             # hot-path latency benchmarks
+  fixtures/          # synthetic session transcripts
 ```
 
 ### Adding a new observation kind
@@ -441,36 +592,155 @@ test/
 
 ---
 
-...
-
 ## Troubleshooting
 
+### `somtum stats` shows `memories 0` after a session
+
+This almost always means the hook ran but extraction failed. Check the log first:
+
+```bash
+cat ~/.somtum/hook.log
+```
+
+Common causes:
+
+**`ANTHROPIC_API_KEY` not set in shell profile**
+
+The most common cause. The hook runs as a subprocess of Claude Code and inherits the environment from the shell that launched Claude Code. If you only `export`-ed the key in the current terminal session (not in `.zshrc` / `.bashrc`), the hook won't see it.
+
+Fix:
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
+source ~/.zshrc
+
+# Confirm it's set
+echo $ANTHROPIC_API_KEY
+
+# Then open a new Claude session
+```
+
+**Hook not installed in the right directory**
+
+`somtum init` writes the hook to `.claude/settings.json` in the directory where you ran it. If you run Claude Code from a _different_ directory, it reads a different (or absent) settings file.
+
+Fix: run `somtum init` from the same directory you use to launch Claude Code.
+
+```bash
+cd ~/my-project
+somtum init
+claude   # must be launched from ~/my-project
+```
+
+**Short or trivial session**
+
+If the session didn't contain any decisions, bug fixes, or learnings (e.g. you just asked Claude to say hello), the extractor correctly returns 0 observations.
+
+Try a real working session, then re-check.
+
+**Run `somtum doctor`** for a full diagnostic:
+
+```bash
+somtum doctor
+```
+
+It checks the API key, hook installation, DB health, embeddings, breakeven ratio, and more, with specific fix instructions for each failing check.
+
+---
+
+### `somtum serve` opens the browser but shows "Connection refused"
+
+This was a bug fixed in v1.1.0. Upgrade:
+
+```bash
+npm install -g somtum@latest
+```
+
+If you installed from source, rebuild:
+
+```bash
+pnpm build
+```
+
+---
+
+### `somtum serve` — port already in use
+
+If port 3000 is busy, use `--port`:
+
+```bash
+somtum serve --port 3001
+```
+
+---
+
+### Agent appears to keep running after session ends
+
+The `SessionEnd` hook has a hard 90-second timeout — it cannot block Claude Code indefinitely. If sessions appear stuck immediately after installing Somtum, verify you are on v1.1.0+:
+
+```bash
+somtum --version
+```
+
+And check the log for any long-running operations:
+
+```bash
+tail -20 ~/.somtum/hook.log
+```
+
+---
+
+
 ### Installation fails (node-gyp / better-sqlite3)
 
-If you see errors related to building `better-sqlite3`, ensure you have build tools installed:
+If you see errors related to building `better-sqlite3`, ensure build tools are installed:
 
 - **macOS:** `xcode-select --install`
 - **Ubuntu/Debian:** `sudo apt-get install build-essential python3`
 - **Windows:** `npm install --global --production windows-build-tools`
 
-### "Anthropic API Key not found"
+---
+
+### Embeddings are slow or the model won't download
+
+The first `somtum reindex` downloads a ~30 MB ONNX model (`bge-small-en-v1.5`) from Hugging Face. This requires internet access and may be slow on first run. Subsequent runs use the cached model.
+
+If you are on an air-gapped machine or prefer not to use embeddings, disable them:
 
-The capture hook requires `ANTHROPIC_API_KEY` to be set in your environment. Add it to your `.zshrc`, `.bashrc`, or `.env` file.
+```bash
+somtum config set retrieval.embeddings.enabled false
+somtum config set retrieval.strategy bm25
+```
+
+BM25 retrieval works fully offline and is fast at any reasonable corpus size.
+
+---
 
 ### Claude isn't using the memories
 
-Run `somtum doctor` to verify that hooks are correctly installed in your project.
+If you are using the MCP server (`somtum init --all`), Claude will automatically call `recall` when it's uncertain about project details. If it's not happening:
+
+1. Confirm `.mcp.json` exists in your project root: `cat .mcp.json`
+2. Restart Claude Code so it picks up the new MCP config
+3. Try prompting Claude explicitly: _"Check your Somtum memory for anything related to our auth setup"_
+
+If you are not using the MCP server, memories are injected via the `index.md` file — add it to your CLAUDE.md or Claude Code context with:
+
+```
+See ~/.somtum/projects/<project_id>/index.md for prior session learnings.
+```
 
 ---
 
 ## Contributing
 
-Contributions are welcome! If you'd like to help improve Somtum, please see our [CONTRIBUTING.md](CONTRIBUTING.md) for a guide on how to get started.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for the guide.
 
-**Important Note for Contributors:** This project uses `changesets` for versioning. Every PR must include a changeset file generated by running `pnpm changeset`.
+**Important:** This project uses `changesets` for versioning. Every PR must include a changeset file generated by running `pnpm changeset`.
 
 ---
 
 ## License
 
-Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
+Licensed under the [MIT License](LICENSE).

package/dist/cli/config_cmd.js.map

@@ -1 +1 @@
-{"version":3,"file":"config_cmd.js","sourceRoot":"","sources":["../../src/cli/config_cmd.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config_cmd.js","sourceRoot":"","sources":["../../src/cli/config_cmd.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,SAAS,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAyJnE;AAED,wBAAsB,aAAa,CACjC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,MAAM,CAAC,CAiBjB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,SAAS,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAoKnE;AAED,wBAAsB,aAAa,CACjC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/cli/doctor.js

@@ -113,7 +113,16 @@ export function runDoctor(opts = {}) {
                 ? `enabled (model: ${config.retrieval.embeddings.model}) — run \`somtum reindex\` to embed missing`
                 : 'disabled (set retrieval.embeddings.enabled=true to enable)',
         });
-        // 11. Hook files in .claude/settings.json
+        // 11. ANTHROPIC_API_KEY present
+        const apiKey = process.env['ANTHROPIC_API_KEY'];
+        checks.push({
+            name: 'api_key',
+            ok: Boolean(apiKey && apiKey.trim().length > 0),
+            detail: apiKey && apiKey.trim().length > 0
+                ? 'ANTHROPIC_API_KEY is set'
+                : 'ANTHROPIC_API_KEY is not set — the SessionEnd hook needs it to extract observations. Set it in your shell profile (e.g. export ANTHROPIC_API_KEY=sk-ant-...).',
+        });
+        // 12. Hook files in .claude/settings.json
         const settingsPath = join(cwd, '.claude', 'settings.json');
         if (existsSync(settingsPath)) {
             try {