@clauderecallhq/cli 0.0.1 → 0.12.0

package/LICENSE

@@ -0,0 +1,33 @@
+Claude Recall — Proprietary License (pre-release)
+
+Copyright (c) 2026 Claude Recall HQ. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+No part of this software may be reproduced, distributed, modified,
+sublicensed, or used for commercial purposes without the prior written
+permission of the copyright holder.
+
+Access to the source code does not grant any rights of reuse,
+redistribution, or derivative work. Forking for the purpose of
+personal evaluation on the forker's own machine is permitted; any
+redistribution, public hosting, or resale is not.
+
+Until a formal commercial license is published alongside the v0.6
+commercialization milestone, this notice governs all use of the
+software. The commercial license, once published, will supersede
+this notice.
+
+Trademarks: "Claude Recall" and the Claude Recall logo are trademarks
+of Claude Recall HQ. Nothing in this notice grants any trademark
+rights.
+
+No warranty: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
+AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries: hello@clauderecall.com.

package/README.md

@@ -1,5 +1,545 @@
-# Claude Recall
+<div align="center">
 
-Local, searchable memory for every Claude Code session you run.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="marketing/logos/wordmark-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="marketing/logos/wordmark-light.svg">
+  <img src="marketing/logos/wordmark-dark.svg" alt="Claude Recall" width="360">
+</picture>
 
-Public release coming soon. Visit [clauderecall.com](https://clauderecall.com) for updates.
+### The memory layer for the agent you're steering.
+
+[![site-ci](https://github.com/clauderecallhq/clauderecall/actions/workflows/site-ci.yml/badge.svg)](https://github.com/clauderecallhq/clauderecall/actions/workflows/site-ci.yml)
+[![deploy-site](https://github.com/clauderecallhq/clauderecall/actions/workflows/deploy-site.yml/badge.svg)](https://github.com/clauderecallhq/clauderecall/actions/workflows/deploy-site.yml)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/typescript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Local-first](https://img.shields.io/badge/local--first-127.0.0.1%20only-0b0c0f)](#the-never-delete-data-invariant)
+[![Site](https://img.shields.io/badge/site-clauderecall.com-f97316)](https://clauderecall.com)
+
+</div>
+
+---
+
+> **Stop re-explaining your project to Claude every morning.**
+> Claude Recall indexes every session, surfaces what matters, and pipes the right context back in with one command.
+
+100% local-first. The daemon binds to `127.0.0.1`, your conversations never leave your machine, and the only outbound call Recall will ever make is a one-time license check when you activate a Pro key (v0.6). No cloud, no account, no telemetry.
+
+## Why Claude Recall
+
+Claude Code is magic until the conversation ends. Then you're back to the same three problems.
+
+### 1. Context amnesia
+
+Every new `claude` invocation starts from zero. You re-explain the project layout, re-paste the key files, re-describe the bug you already fixed yesterday. You built that context pyramid once — now you're building it again.
+
+**Fixed by `recall context <id> | claude`** — pipe any past session into a new conversation as condensed markdown. Claude picks up where you left off instead of asking you to explain it again. Runs locally, never touches the network.
+
+```bash
+recall context abc12345 | claude          # moat: past session → new conversation
+recall context abc12345 --prelude "continue this" | claude
+```
+
+### 2. Cost anxiety
+
+Claude Code tells you nothing about spend after a session ends. Which session was the expensive one? Which project is quietly burning half your Anthropic bill? You're guessing.
+
+**Fixed by the stats dashboard** (v0.10a) — tokens, dollars, primary model, a daily sparkline, and the top-10 heaviest sessions. There's a 📊 pill in every transcript header and a `recall stats` subcommand if you prefer the terminal.
+
+```bash
+recall stats abc12345           # one session
+recall stats --project Tools    # one project
+recall stats --days 7           # last week across everything
+```
+
+### 3. Org sprawl
+
+Claude Code scatters every conversation into `~/.claude/projects/**/*.jsonl` — a write-only log with no titles, no search, no way to find the session where you finally got the auth flow right. Dozens of projects × hundreds of sessions × zero hope of finding anything manually.
+
+**Fixed by search, tags, collections, and semantic recall** — full-text search with highlighted snippets in milliseconds, conceptual search for "the session where I debugged the worker memory leak," human-readable aliases, `#tag` tokens in the search box, hand-curated collections that cut across projects, and `Cmd+K` to jump to anything.
+
+```bash
+recall search "zod schema"         # full-text across every message
+recall search "auth #auth-fix"     # combine text + tag filter
+recall semantic on                 # enable conceptual search
+```
+
+All local. All offline. All invisible enough for vibe coders and powerful enough for engineers.
+
+## Install (dev)
+
+```bash
+# 1. Install deps
+npm install
+
+# 2. Build
+npm run build
+
+# 3. Make `recall` globally available
+npm link
+
+# 4. Start the background daemon (watcher + HTTP server)
+recall start
+
+# 5. Open the web UI in your browser
+recall open
+```
+
+## Usage
+
+### Terminal
+
+```bash
+# lifecycle
+recall start              # start daemon (watcher + local HTTP)
+recall stop               # stop daemon
+recall open               # open web UI (starts daemon if needed)
+recall status             # db + daemon health
+
+# indexing (daemon auto-indexes; manual is a fallback)
+recall index              # scan for new/changed session files
+recall index --force      # reindex everything
+recall index -v           # verbose
+
+# explore
+recall projects           # list projects with session counts
+recall list               # 30 most-recent sessions
+recall list -p Tools      # filter by project substring
+recall list -n 100        # higher limit
+
+# read
+recall show <id>          # pretty transcript, auto-pages through `less` if long
+recall show <id> --raw    # raw JSONL
+recall show <id> --no-pager  # dump to stdout
+
+# search (full-text over every message)
+recall search "zod schema"
+recall search "auth" -p Pest-Control
+recall search bug -n 50
+
+# context re-injection (the moat)
+recall context <id>                       # condensed markdown to stdout
+recall context <id> | pbcopy              # to clipboard (macOS)
+recall context <id> | claude              # pipe into a new Claude Code session
+recall context <id> --full                # full transcript (bigger)
+recall context <id> --since 2h            # only last 2 hours
+recall context <id> --prelude "continue this" # prepend an instruction
+recall context <id> --subagents           # include subagent messages
+
+# stats (v0.10a)
+recall stats <id>                         # tokens + dollars for one session
+recall stats --project Tools              # per-project rollup
+recall stats --days 7                     # 7-day overview
+recall stats --backfill                   # one-shot usage backfill for older messages
+
+# git correlation (v0.10b)
+recall correlate                          # link sessions to commits in their cwd
+recall blame <sha>                        # reverse lookup: commit → session
+
+# semantic search (v0.11)
+recall semantic on                        # enable conceptual search
+recall semantic off                       # disable
+recall semantic status                    # backfill progress
+recall semantic backfill                  # run now
+recall semantic pause                     # pause background worker
+recall semantic resume                    # resume worker
+recall semantic install                   # download the local embedding model
+recall semantic uninstall                 # remove the local model
+recall semantic reindex                   # regenerate all summaries
+
+# similar sessions (Pro, requires vector model)
+recall similar <id>                       # sessions related to this one
+recall similar <id> -n 5                  # top 5 results
+
+# clipboard archiving (opt-in)
+recall paste                              # archive clipboard contents
+recall paste --label "zod fix"            # attach a short description
+recall paste --dry-run                    # preview without writing
+recall paste --pipe                       # echo content to stdout after archiving
+recall paste --force                      # skip secret-scan confirmation
+recall paste --list                       # list archived pastes
+recall paste --purge <id>                 # permanently delete one paste
+
+# security scanning
+recall audit-secrets                      # scan db for leaked secrets (read-only)
+recall audit-secrets --redact             # scrub hits in place (source JSONLs untouched)
+recall audit-secrets -v                   # verbose per-session output
+
+# rediscovery ("For you" picks)
+recall digest                             # today's picks (rediscovered session, costliest, HEAD author)
+recall digest --json                      # machine-readable output
+
+# VS Code / Cursor / Windsurf extension sideloading
+recall install-extension                  # install into all detected editors
+recall install-extension --editor cursor  # target one editor
+recall install-extension --print-path     # print .vsix path and exit
+
+# memory health scores
+recall health                             # all projects, worst health first
+recall health "My Project"                # single-project breakdown
+recall health --json                      # machine-readable output
+
+# verification badges (opt-in preview)
+recall verify                             # show current status (default)
+recall verify on                          # enable
+recall verify off                         # disable
+
+# Pro licensing
+recall activate <license-key>             # activate a Pro license (one-time)
+recall license                            # show current tier (default: status)
+recall license status                     # same as above
+recall license deactivate                 # remove license from this machine
+
+# threads (v0.15a) - intent-grouped session clusters
+recall thread list                        # list threads (most recent first)
+recall thread list --archived             # include archived threads
+recall thread show <id>                   # thread header + session tree
+recall thread new "Auth refactor"         # create a thread
+recall thread new "Auth" --origin <sid>   # create with an origin session
+recall thread new "Auth" --summary "..."  # create with a summary
+recall thread link <sid> --thread <tid>   # link a session into a thread
+recall thread link <sid> --thread <tid> --parent <pid>   # link as child of another session
+recall thread unlink <sid> --thread <tid> # remove session from thread
+recall thread set-parent <sid> --thread <tid> --parent <pid>  # re-parent within thread
+recall thread set-parent <sid> --thread <tid> --parent none   # promote to origin
+recall thread rename <id> "New name"      # rename a thread
+recall thread close <id>                  # mark work complete
+recall thread reopen <id>                 # reopen a closed thread
+recall thread archive <id>                # soft-delete (hidden from list, never hard-deleted)
+recall thread merge <source> --into <dest>                    # merge two threads
+recall thread split <id> --sessions s1,s2 --name "New thread" # split sessions into new thread
+```
+
+### MCP server (v0.9, bidirectional v0.13)
+
+Point any Model Context Protocol client — Claude Desktop, Claude Code, or your own — at the `claude-recall-mcp` binary and the model calls Recall as native tools.
+
+```bash
+# Runs over stdio, never touches the network
+claude-recall-mcp
+
+# Or via the CLI shim
+recall mcp
+
+# Opt in to write tools (tag, alias, note, collection) — off by default
+recall mcp --allow-writes
+```
+
+Minimal Claude Code / Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "recall": {
+      "command": "claude-recall-mcp"
+    }
+  }
+}
+```
+
+13 read-only tools (always available):
+
+| Tool | Purpose |
+|---|---|
+| `list_projects` | Every indexed project with session/message counts |
+| `list_sessions` | Recent sessions, filterable by project / tag / date range |
+| `list_tags` | Tag cloud with counts, most popular first |
+| `list_sessions_to_tag` | Sessions formatted for an agent to propose tags (auto-tag must be enabled) |
+| `apply_tags` | Merge-add tags to a session (auto-tag must be enabled) |
+| `search` | Full-text search; supports inline `#tag-name` tokens; fuses with vector lane when available |
+| `find_similar_sessions` | Vector-similarity search for related sessions (Pro) |
+| `semantic_status` | Health snapshot of the semantic vector tier (Pro) |
+| `get_session` | Full transcript with metadata and tags (accepts 8+-char id prefix) |
+| `context_for_session` | Condensed-markdown export - the moat, callable as a tool |
+| `thread_list` | All threads, newest first (excludes archived by default) |
+| `thread_get` | Full thread detail with every session edge |
+| `thread_for_session` | Threads containing a given session |
+
+18 write tools (v0.13+, require `--allow-writes`):
+
+| Tool | Purpose |
+|---|---|
+| `add_tag` / `remove_tag` | Organize sessions from inside Claude |
+| `set_alias` | Rename a session (archives previous name) |
+| `append_note` | Append to a session's markdown note |
+| `create_collection` | Make a new collection, optionally under a parent |
+| `add_session_to_collection` / `remove_session_from_collection` | Curate collection memberships |
+| `thread_create` | Create a new thread, optionally seeded with an origin session |
+| `thread_add_session` | Attach a session to a thread (origin or child) |
+| `thread_set_parent` | Change a session's parent within a thread (null to promote) |
+| `thread_remove_session` | Detach a session from a thread |
+| `thread_rename` | Change thread display name |
+| `thread_close` / `thread_reopen` | Mark work complete or reopen |
+| `thread_archive` | Soft-delete a thread (hidden, never hard-deleted) |
+| `thread_merge` | Dissolve one thread into another |
+| `thread_split` | Peel sessions into a new thread |
+| `generate_thread_titles` | Walk the thread DAG and generate coherent titles for each session |
+
+Every write is rate-limited (default 60/min), zod-validated, audited to `mcp_audit_events`, and scoped to Recall's own metadata layer - session content is never mutated and no file paths are accepted as input.
+
+### Web UI
+
+Press **`?`** anywhere to open the Command Center — full docs with sections for Quickstart, Web UI tour, CLI commands, Keyboard shortcuts, Collections, Your data, Exporting, Security, Pro tips, MCP server, VS Code extension, Pricing, FAQ, and Troubleshooting.
+
+Keyboard shortcuts:
+
+| Key | Action |
+|---|---|
+| `/` | Focus the search box |
+| `?` | Open Command Center |
+| `Cmd+K` / `Ctrl+K` | Open the command palette (jump to any session, action, or setting) |
+| `Esc` | Close/clear/dismiss |
+| `n` / `p` | Next / previous match (during search) |
+| `c` | New collection |
+| `Cmd+Shift+A` | Add current session to a collection |
+| `Cmd+Enter` | Save note |
+| `Cmd+Click` / `Ctrl+Click` (sessions list) | Toggle row in a multi-selection |
+| `Shift+Click` (sessions list) | Extend the multi-selection as a range |
+
+## Features
+
+Everything the CLI and UI surface — demoted to reference material because the three pains above are the actual reason you'd install this.
+
+- **Indexes every past session** into SQLite + FTS5 at `~/.recall/db.sqlite`
+- **Full-text search** across 100,000+ messages in milliseconds with `bm25()` ranking and highlighted snippets
+- **Semantic search** (v0.11) — 3-sentence summary + ~15 keywords per session via your local `claude` CLI; off by default
+- **Context re-injection** (v0.4) — `recall context <id> | claude`. The moat
+- **Cost analytics** (v0.10a) — per-session and per-project token + dollar totals, daily sparkline, top-10 heaviest sessions
+- **Git correlation** (v0.10b) — every session links to commits authored in its `cwd` during its time window; `recall blame <sha>` reverse-maps
+- **MCP server** (v0.9, bidirectional v0.13) — expose Recall to Claude Desktop / Claude Code as native tools
+- **Collections** (v0.8) — hand-picked hierarchical groupings of sessions that cut across projects
+- **Aliases, tags, notes, pins** — every metadata layer keeps history; UUIDs stay the immutable primary key
+- **Auto-tagging** (v0.9, off by default) — propose tags via your Anthropic API key or your local `claude` CLI through MCP (zero extra cost)
+- **Cmd+K command palette** (v0.12a) — jump to any session, action, or setting in one keystroke
+- **Multi-select sessions** — `Cmd+Click` to toggle, `Shift+Click` for a range, then right-click for a copy-IDs menu (newline / space / comma separated) or use the inline "copy IDs" button — paste straight into a new Claude prompt
+- **Cross-session diff** (v0.4.4) — split view of two transcripts with shareable `cmp=` URL
+- **VS Code / Cursor / Windsurf extension** (v0.7) — auto-name sessions using the terminal tab name via process-tree matching
+- **First-run onboarding** (v0.14a) — a 3-step tour that demos the moat in the first 60 seconds
+- **Beautiful dark-mode web UI** — three-pane layout with virtualized transcript (10,000-message sessions open instantly)
+- **Export** — condensed markdown, full markdown, self-contained dark-mode HTML, print-ready PDF
+
+## Architecture
+
+### Two surfaces — don't confuse them
+
+Claude Recall spans two independent frontends that share the `clauderecall.com` brand:
+
+| Surface | Stack | Lives at | Purpose |
+|---|---|---|---|
+| **Local product** (this repo, `src/web/`) | Vite 8 + React 19 + Tailwind, served by the Hono daemon | `http://127.0.0.1:<random-port>` on the user's machine | The actual `recall` experience — the UI the user opens when they type `recall open` |
+| **Marketing / docs site** (separate deploy) | Next.js | `clauderecall.com` | Public landing, SEO, MDX docs, AI-search citability, checkout (v0.6) |
+
+**Why Vite for the local product**: the UI is embedded in an offline CLI. No SEO, no public traffic, no SSR — a small static bundle the daemon serves from `dist/web/` is the right shape, and keeps the packaged `@clauderecallhq/cli` footprint lean.
+
+**Why Next.js for the public site**: SEO, social previews, SSG/MDX, edge hosting — Next.js's sweet spot. It gets its own repo (or at minimum a separate `site/` directory with its own `package.json`) so the CLI install never pulls in a Next.js runtime.
+
+### Local product internals
+
+```
+~/.claude/projects/**/*.jsonl   ← Claude Code's own output (read-only to us)
+        │
+        ▼ chokidar file watcher
+~/.recall/db.sqlite             ← our indexed database
+        │
+  ┌─────┴─────┐
+  │           │
+  CLI         HTTP server (Hono, on random localhost port)
+  │           │
+  recall …    http://127.0.0.1:<port>
+              │
+              ▼
+              React + Tailwind SPA (Vite build, served from dist/web/)
+```
+
+### Data layout (all under `~/.recall/`)
+
+| Path | What |
+|---|---|
+| `db.sqlite` | The indexed database (projects, sessions, messages, FTS5, aliases, notes, tags, collections, semantic summaries, commit links, usage rollups, audit logs) |
+| `aliases.json` | Plain-text mirror of every alias with full edit history |
+| `notes/<session>.md` | One markdown file per session note |
+| `tags.json` | Current tag state + append-only event log of every add/remove |
+| `collections.json` | Current tree state + append-only event log of every mutation |
+| `semantic/<session>.json` | Per-session summary + keywords (only when semantic mode is on) |
+| `daemon.pid` | Running daemon metadata |
+| `daemon.port` | Port the daemon picked |
+| `daemon.log` | Daemon logs |
+
+## The "never delete data" invariant
+
+Every user-created write feature enforces **three independent durability layers**:
+
+1. **SQLite** — primary storage with history columns (`previous_aliases`, `previous_versions`, `tag_events`, `collection_events`)
+2. **Plain-text mirror on disk** — JSON or markdown files so the data is greppable, editable, and recoverable if the database is wiped
+3. **Source JSONLs are never modified** — Claude Code's own files at `~/.claude/projects/` are strictly read-only to Recall
+
+Renaming, clearing, or removing anything is always additive — the prior value is archived, never destroyed.
+
+## Tech stack
+
+### CLI + daemon (Node, ESM)
+- **TypeScript 5** strict mode, compiled with `tsc` to `dist/`
+- **better-sqlite3** — synchronous SQLite with FTS5 full-text search
+- **Hono** + **@hono/node-server** — HTTP server on a random ephemeral port (never a well-known dev port)
+- **chokidar** — filesystem watcher
+- **commander** — CLI parsing
+- **@modelcontextprotocol/sdk** — MCP stdio server (v0.9 read-only, v0.13 bidirectional)
+- **zod** — schema validation on every MCP write
+- **chalk**, **cli-table3**, **date-fns** — terminal formatting
+
+### Web UI (bundled into daemon)
+- **Vite 8** + **React 19** + **TypeScript**
+- **Tailwind CSS 3** — dark palette matching the app brand (`#0b0c0f` / `#f97316` accent)
+- **@tanstack/react-query** — data fetching with caching
+- **@tanstack/react-virtual** — virtualized message list (handles 10k+ message sessions)
+- **marked** + **highlight.js** + **DOMPurify** — markdown rendering with syntax highlighting and XSS hardening
+- **clsx** — conditional class names
+- Inter + JetBrains Mono fonts from Google Fonts
+
+### Storage
+- SQLite with FTS5 porter/unicode61 tokenization
+- `~/.recall/` as the root for everything user-generated
+- `~/.claude/projects/` as the external read-only source of truth
+
+## Auto-tagging (v0.9)
+
+Propose tags for your sessions with an LLM, then review before anything is written. Two backends: your Anthropic API key OR your Claude Code agent via MCP (zero extra cost). Off by default.
+
+See [`docs/auto-tagging.md`](./docs/auto-tagging.md) for setup.
+
+## Roadmap
+
+See [ROADMAP.md](./ROADMAP.md) for the full plan. Shipped so far:
+
+- ✅ v0.1–v0.5 — CLI, daemon, web UI, context re-injection (the moat), aliases, notes, tags, cross-session diff, MCP read-only server
+- ✅ v0.7 — VS Code / Cursor / Windsurf extension (process-tree tab correlation)
+- ✅ v0.8 — Collections (hand-curated hierarchical groupings across projects)
+- ✅ v0.9 — Auto-tagging (API key or MCP backend, off by default)
+- ✅ v0.10a — Cost / token analytics (dashboard + `recall stats`)
+- ✅ v0.10b — Git correlation (session ↔ commit, `recall blame`)
+- ✅ v0.11 — Semantic search via local `claude` CLI
+- ✅ v0.12a — `Cmd+K` command palette
+- ✅ v0.13 — Bidirectional MCP write tools (opt-in, rate-limited, audited)
+- ✅ v0.14a — First-60-seconds onboarding flow
+- ✅ **v0.14c — Positioning rewrite (this pass)**
+- ⬜ v0.6 — Commercialize: Next.js landing at `clauderecall.com` + LemonSqueezy license flow
+
+## Production deployment & CI/CD
+
+The marketing / docs site at [clauderecall.com](https://clauderecall.com) is the only piece of Claude Recall with a remote deploy — the local CLI ships through npm. The deploy is fully automated through GitHub Actions and lands on a dedicated isolated user on a DigitalOcean droplet behind a Cloudflare Tunnel.
+
+### Pipeline
+
+```
+push to main (touching site/** | site-ci.yml | src/web/components/HelpView.tsx)
+        │
+        ▼
+site-ci         typecheck → lint → sync:docs → unit tests → e2e (Playwright)
+                → build → Lighthouse → bundle size                ~3 min
+        │
+        ▼  workflow_run on success only
+deploy-site     setup Node 22 → npm ci → next build → load deploy SSH key
+                → ssh-keyscan droplet → rsync .next/ + public/ + manifests
+                → npm install --omit=dev on droplet → pm2 restart
+                → curl 5 routes for 200 → cleanup SSH key             ~1 min
+        │
+        ▼
+clauderecall.com is live
+```
+
+`site-ci` and `deploy-site` are decoupled — `site-ci` always runs on PRs and on `main`; `deploy-site` only runs after `site-ci` succeeds on `main` (via `workflow_run`), so a red test gate blocks the deploy automatically.
+
+### Manual triggers
+
+```bash
+# Re-run the full test suite against main (e.g. after rotating a secret).
+gh workflow run site-ci --ref main
+
+# Bypass site-ci and re-deploy main as-is (useful after editing
+# /opt/clauderecall/.env.production on the droplet without a code change).
+gh workflow run deploy-site --ref main
+```
+
+You can also trigger both from the Actions tab in the GitHub UI ("Run workflow" button).
+
+### Droplet topology
+
+The droplet is multi-tenant, with each app fully isolated:
+
+| Concern | Boundary |
+|---|---|
+| **Linux user** | Dedicated `clauderecall` user (uid 1004). No sudo, no extra groups. |
+| **App path** | `/opt/clauderecall/` — owned by `clauderecall:clauderecall`. |
+| **Logs** | `/var/log/clauderecall/{out,error}.log`. |
+| **License DB** | `/var/lib/clauderecall/licenses.db` — SQLite, owned by `clauderecall`. |
+| **Network** | Next.js bound to `127.0.0.1:3010` only. No public port; reached exclusively through the Cloudflare Tunnel. |
+| **Cloudflare Tunnel** | Dedicated tunnel `clauderecall` (its own systemd unit `cloudflared-clauderecall.service`), independent of every other tenant on the box. |
+| **SSH** | `clauderecall-prod` host alias backed by a dedicated ed25519 key. CI uses a separate ed25519 key (rotatable without disturbing local deploys). Key-only auth — `PasswordAuthentication no` droplet-wide. |
+| **Secrets** | `.env.production` lives only on the droplet (`0600`, never in git, never in CI artifacts). Rotate via `site/scripts/admin/swap-env-var.sh`. |
+
+### Local deploy (escape hatch)
+
+When CI is the wrong tool — emergency hotfix while CI is down, swapping live keys, etc. — the same script CI uses runs from a Mac:
+
+```bash
+cd site
+bash scripts/deploy/deploy-to-production.sh           # full deploy
+bash scripts/deploy/deploy-to-production.sh --dry-run # show plan only
+bash scripts/deploy/deploy-to-production.sh --skip-build  # reuse current .next/
+```
+
+Pre-reqs: the `clauderecall-prod` SSH alias in `~/.ssh/config` and the matching ed25519 key in `~/.ssh/clauderecall_deploy`.
+
+### Swapping a single env var on the droplet
+
+```bash
+# Reads value from stdin, never argv → never lands in shell history.
+echo -n 'sk_live_...' | bash site/scripts/admin/swap-env-var.sh STRIPE_SECRET_KEY
+
+# Or interactive (hidden prompt).
+bash site/scripts/admin/swap-env-var.sh STRIPE_SECRET_KEY
+```
+
+The script edits the file atomically on the droplet via Python, restarts PM2 with `--update-env` so the new value takes effect, and prints a `[set, N chars]` confirmation that never reveals the value.
+
+## Contributing / local development
+
+```bash
+# Develop CLI
+npm run dev             # tsx runs src/cli.ts
+
+# Develop web UI with hot reload
+recall start            # keep daemon running on port X
+RECALL_DAEMON_PORT=X npm run dev:web   # vite dev server on 5174, proxies /api → daemon
+
+# Typecheck
+npm run typecheck
+
+# Full build
+npm run build           # tsc + vite
+```
+
+Key files:
+- `src/cli.ts` — CLI entry (commander)
+- `src/daemon/` — background server + file watcher
+- `src/db/schema.ts` — SQL schema (single source of truth, `IF NOT EXISTS` migrations)
+- `src/parser/jsonl.ts` — JSONL → structured records (tool_use captured as markdown, ANSI stripped, usage counters extracted, secrets auto-redacted at ingest)
+- `src/context/formatter.ts` — shared markdown formatter used by `recall context` CLI + `/api/sessions/:id/context` HTTP + MCP
+- `src/utils/aliases.ts`, `notes.ts`, `tags.ts`, `collections.ts` — write features with three-layer durability
+- `src/utils/pricing.ts` — static ¢/Mtok pricing table (derived, not persisted)
+- `src/semantic/pipeline.ts` — Claude-CLI-backed semantic summaries
+- `src/mcp/` — MCP stdio server (read-only tools + opt-in write tools + audit + rate limiter)
+- `src/commands/*.ts` — individual CLI subcommands
+- `src/web/App.tsx` — root React component
+- `src/web/commands/` — command palette registry + built-ins
+- `src/web/components/` — each pane and feature
+- `src/web/hooks/` — `useHashRoute`, `usePinned`, `useAlias`, `useNotes`, `useTags`, `useOnboarding`, `useDebounced`
+
+## Brand, registries, and identities
+
+See [`BRAND.md`](./BRAND.md) for the complete inventory of npm packages, VS Code / Open VSX extension listings, domain names, and social handles that make up the official Claude Recall presence — plus the outstanding defensive work and the 2026-04-23 npm-squatter incident that triggered the scoped-package pivot.
+
+Short version: official CLI ships as **`@clauderecallhq/cli`** on npm, the canonical VS Code extension is **`clauderecallhq.clauderecall-vscode`**, and the product site lives at **[clauderecall.com](https://clauderecall.com)**. Anything else using the Claude Recall name is not us.
+
+## License
+
+UNLICENSED, private until v0.6 launch.