ricord 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricord AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,213 @@
+# ricord-mcp
+
+Persistent memory for AI coding assistants. Ricord gives your AI tools long-term knowledge, episodic memory, a knowledge graph, integrations, and more — all via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+This package ships **two binaries**:
+
+- **`ricord-mcp`** — the MCP server, for Claude Code / Cursor / Windsurf / VS Code
+- **`ricord`** — a CLI for repo ingestion (`ricord init`), auth (`ricord login`), and account info (`ricord whoami`)
+
+Both share `~/.ricord/credentials.json`, so logging in once authorizes everything.
+
+## Quick Start (One Command)
+
+```bash
+npx ricord-mcp --setup --client claude --api-key YOUR_API_KEY
+```
+
+Supported clients: `claude-code`, `claude-desktop`, `cursor`, `windsurf`, `vscode`
+
+This auto-writes the correct config file for your editor. Get your API key at [ricord.ai/dashboard/api-keys](https://ricord.ai/dashboard/api-keys).
+
+### Manual Setup
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add ricord -- npx ricord-mcp --api-key YOUR_API_KEY
+```
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "ricord": {
+      "command": "npx",
+      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ricord": {
+      "command": "npx",
+      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ricord": {
+      "command": "npx",
+      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>VS Code (Copilot)</summary>
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "ricord": {
+      "command": "npx",
+      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
+    }
+  }
+}
+```
+</details>
+
+## Options
+
+| Flag | Env Var | Default | Description |
+|------|---------|---------|-------------|
+| `--api-key` | `RICORD_API_KEY` | required | Your Ricord API key |
+| `--api-base` | `RICORD_API_BASE` | `https://api.ricord.ai` | API endpoint |
+| `--mode` | — | `auto` | `auto`, `manual`, or `hybrid` |
+| `--project` | `RICORD_PROJECT` | — | Project namespace |
+
+### Modes
+
+- **auto** (default) — AI automatically saves knowledge when you make decisions, state preferences, or discuss architecture
+- **manual** — Only saves when explicitly asked
+- **hybrid** — Auto-extracts knowledge but marks it as draft for your review
+
+## Tools (9)
+
+| Tool | Description | Credits |
+|------|-------------|---------|
+| `ricord_remember` | Save facts, preferences, decisions, procedures, references, playbooks, anti-patterns, episodes | 3 |
+| `ricord_recall` | Retrieve relevant knowledge (hybrid vector + graph search) | 1 |
+| `ricord_correct` | Update existing knowledge by ID | 3 |
+| `ricord_forget` | Delete knowledge items by ID | 0 |
+| `ricord_list` | Browse stored items with optional type filter | 0 |
+| `ricord_profile` | Get or update aggregated user profile | 0 |
+| `ricord_graph` | Explore knowledge graph: entities, neighborhoods, stats, communities | 0 |
+| `ricord_usage` | Check credit balance, tier, and usage stats | 0 |
+
+## Prompts
+
+Setup prompts are included for each supported client:
+- `setup-claude-code`
+- `setup-claude-desktop`
+- `setup-cursor`
+- `setup-windsurf`
+- `setup-vscode`
+
+## Repo ingestion (`ricord init` + `/ricord-init` slash command)
+
+Two paths, one mental model — both follow Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: the agent (LLM) does the bookkeeping, Ricord stores the persistent wiki, and the schema (the slash command markdown) is the protocol.
+
+### Path A — inside Claude Code / Codex / OpenCode (preferred)
+
+The host agent IS the LLM. Zero external API spend.
+
+```bash
+# In Claude Code
+/ricord-init .            # walks repo, agent extracts each bundle
+/ricord-lint              # Karpathy lint: contradictions, orphans, stale claims
+/ricord-query "<question>"   # ask the wiki, optionally file the answer back
+```
+
+Under the hood, `/ricord-init` runs `ricord init --emit-bundles` to stage `.ricord-cache/bundles/*.md` + `manifest.json`, then iterates the manifest: the agent reads each bundle, applies Ricord's canonical extraction prompt (fetched from `/v1/extraction/prompt`) in-context, and POSTs the structured result to `/v1/ingest/extracted`. The agent also maintains `index.md` (catalog) and `log.md` (chronological) per Karpathy's pattern.
+
+### Path B — headless CLI (for CI, scripts, no host agent)
+
+```bash
+ricord login              # one-time OAuth
+ricord init               # uses OPENAI_API_KEY (or ANTHROPIC_API_KEY)
+ricord init --dry-run     # walk + parse, no POST
+ricord init --no-ingest   # also write summaries to disk for review
+ricord init --llm-model claude-sonnet-4-6   # override LLM
+```
+
+In Path B the CLI fetches the same `/v1/extraction/prompt`, runs it through your LLM (~$0.05–0.15 for a small-medium repo with gpt-4o), and POSTs to `/v1/ingest/extracted`. Ricord ships zero generative LLM calls — the only thing the server does is embed bundle text for hybrid search (Vertex, ~$0.025 / 1M chars).
+
+Both paths cache by content hash at `<root>/.ricord-cache/`, so re-runs only touch changed directories.
+
+After ingest, query your graph:
+- `ricord_search` (MCP tool, or `POST /v1/search`) for hybrid recall
+- `POST /v1/kb/global-query` for GraphRAG map-reduce questions ("What's the architecture?")
+- The Ricord dashboard at [ricord.ai/dashboard](https://ricord.ai/dashboard) for the visual graph
+
+## Hooks (opt-in)
+
+Ricord ships two Claude Code hook scripts in `dist/hooks/`. Hooks are opt-in — installing the npm package does not activate them. You wire them into your project's `.claude/settings.json` yourself.
+
+### Available hooks
+
+**SessionStart** — injects a compact memory digest at the start of every Claude session. Adds top SOPs, preferences, recent activity, and open tasks to the system prompt.
+
+**PreToolUse** — blocks any Write, Edit, or MultiEdit call whose `file_path` targets `MEMORY.md` or the Claude auto-memory paths (`.claude/projects/*/memory/*`, `.ricord/memory/*`). Prevents the AI from silently overwriting your memory files instead of saving knowledge through the Ricord API.
+
+### Wiring hooks into Claude Code
+
+Add this to your project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node node_modules/ricord-mcp/dist/hooks/session-start.js"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "matcher": "Write|Edit|MultiEdit",
+        "command": "node node_modules/ricord-mcp/dist/hooks/pre-tool-use.js"
+      }
+    ]
+  }
+}
+```
+
+Or, if you installed globally (`npm install -g ricord-mcp`), replace the `node node_modules/...` path with the global install path (e.g. `$(npm root -g)/ricord-mcp/dist/hooks/session-start.js`).
+
+**Note:** both hooks require that `RICORD_API_KEY` is set in your environment (or that `~/.ricord/credentials.json` exists from `ricord login`).
+
+## License
+
+MIT

package/commands/ricord-flush.md

@@ -0,0 +1,29 @@
+---
+description: Flush this conversation to Ricord — extract anchors + connections, write graph, and roll up affected pages
+---
+
+Run the Ricord client-extraction flush flow on the **current conversation**:
+
+1. Call `ricord_extract` with `action="fetch_prompt"`. Save the returned `prompt`, `output_schema`, and `schema_version`.
+
+2. Build the message list to extract from:
+   - All `role=user` messages from this conversation.
+   - The **final** `role=assistant` message only (the one followed by Stop, not the intermediate tool-using turns).
+   - Skip every other assistant turn, every tool-result block, every system message.
+
+3. Apply the prompt locally (do the extraction yourself). Substitute `{TEXT}` with the message list joined by `\n\n` lines of `<role>: <content>`. Emit a JSON object exactly matching `output_schema`: `{ anchors: [...], connections: [...], tasks: [...] }`. Do not invent facts not stated in the messages.
+
+4. Call `ricord_extract` with `action="flush"`, passing:
+   - `messages`: the same filtered list from step 2
+   - `extracted`: your JSON from step 3
+   - `extraction_meta`: `{ model: "<your model id>", client: "claude-code", schema_version: <from step 1> }`
+
+5. The response includes `pages_written` and any `pages_needing_rollup` ids. For each page id in `pages_needing_rollup`:
+   - `GET /v1/kb/pages/<id>/rollup-prompt` (use Bash + curl with the API key from `~/.ricord/credentials.json`)
+   - Apply the returned `prompt` locally, emit JSON matching its `output_schema`
+   - `POST /v1/kb/pages/<id>/body` with that JSON
+
+6. Report a one-line summary:
+   `Flushed: <pages_written> pages, <links_written> edges, <rolled_up> rollups, <tasks_written> tasks.`
+
+Do not narrate intermediate steps. Just do the work and produce the summary line.

package/commands/ricord-init.md

@@ -0,0 +1,129 @@
+---
+description: Build / refresh a Ricord knowledge wiki from a repo, URL, file, or conversation — the host LLM (you) is the worker.
+argument-hint: [. | repo | <url> | <file path> | (omit for conversation)]
+---
+
+You are the worker. Ricord is the **wiki store** and the **schema** (extraction prompt + ingest endpoints). This command is the **protocol** — Karpathy's "LLM Wiki" pattern: the agent (you) reads sources, extracts structured knowledge, and the wiki compounds over time. You never call an external LLM API — *you* are the LLM.
+
+Target: `$ARGUMENTS` (default: this conversation).
+
+## Source modes
+
+- **No argument** → use this conversation. Build a single bundle from `role=user` messages plus the final `role=assistant` message. Skip to "Single-bundle flow" below.
+- **`.` or `repo`** → walk the cwd repo. Use "Multi-bundle flow" below.
+- **URL** (starts with `http://` / `https://`) → `WebFetch` the URL → single bundle.
+- **File path** (anything else) → `Read` it. If it's a directory, treat as repo (multi-bundle).
+
+## Multi-bundle flow (repo mode)
+
+This is the Karpathy pattern: the wiki is the agent's persistent artifact, refreshed incrementally.
+
+### Step 1 — Stage bundles
+
+```bash
+ricord init --emit-bundles
+```
+
+This walks the repo with no LLM, no POST. It writes:
+- `.ricord-cache/bundles/<slug>.md` — one structural summary per meaningful directory
+- `.ricord-cache/manifest.json` — `{root, repo, api_base, bundles:[{rel, slug, bundlePath, chars, hash}]}`
+
+If `.ricord-cache/manifest.json` already exists and the user hasn't said "re-walk", reuse it.
+
+### Step 2 — Fetch the extraction prompt (once)
+
+```bash
+TOKEN=$(jq -r .api_key ~/.ricord/credentials.json)
+API=$(jq -r .api_base ~/.ricord/credentials.json 2>/dev/null || echo https://api.ricord.ai)
+curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/extraction/prompt" > .ricord-cache/extraction-prompt.json
+SCHEMA_VERSION=$(jq -r .schema_version .ricord-cache/extraction-prompt.json)
+```
+
+Read `.ricord-cache/extraction-prompt.json` once. Hold the `prompt`, `output_schema`, and `caps` in mind for every bundle.
+
+### Step 3 — Per bundle, extract + POST
+
+For each bundle in the manifest (iterate, don't parallelize with the Task tool — sequential is fine and keeps the log linear):
+
+1. `Read` the bundle file at `bundlePath`.
+2. Mentally apply the extraction prompt to the bundle text. Substitute `{TEXT}` with the bundle. Emit JSON matching `output_schema`: `{ anchors: [...], connections: [...], tasks: [...] }`.
+   - **Quality bar**: every anchor must be a named concept a human would recognize as a wiki article title (Karpathy: "you are a writer, not a filing clerk").
+   - **Type discipline**: `type` must be exactly `"entity"`, `"topic"`, or `"epoch"`. Put finer-grained classification into `subtype` (`"person"`, `"company"`, `"library"`, `"decision"`, `"pattern"`, etc.).
+   - **Caps**: max 10 anchors, 30 connections, 5 tasks per bundle. The server rejects more.
+   - Skip bundles where there is genuinely nothing to extract (e.g. a 50-char README stub). Note the skip in `log.md` (step 4).
+3. POST via curl. Build the payload as a JSON file first so quoting in the bundle text doesn't corrupt the call:
+
+   ```bash
+   # Write payload to a temp file, then POST it
+   Write /tmp/ricord-payload.json with the JSON body
+   curl -sS -X POST "$API/v1/ingest/extracted" \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     --data-binary @/tmp/ricord-payload.json
+   ```
+
+   The JSON body:
+   ```json
+   {
+     "messages": [{"role": "user", "content": "<full bundle text>"}],
+     "extracted": { "anchors": [...], "connections": [...], "tasks": [...] },
+     "extraction_meta": { "model": "<your model id, e.g. claude-opus-4-7>", "client": "claude-code", "schema_version": <from step 2> },
+     "tags": ["repo:<repo>", "dir:<rel>", "kind:dir-summary"]
+   }
+   ```
+
+4. Parse the response. Track `pages_written`, `links_written`, `tasks_written`, and `pages_needing_rollup: [<page_id>, …]`.
+
+5. For each `page_id` in `pages_needing_rollup`, do the rollup pair (Karpathy: "the LLM owns the wiki layer entirely"):
+
+   ```bash
+   curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/kb/pages/$PAGE_ID/rollup-prompt"
+   ```
+   Read the prompt, mentally produce the rollup body (markdown, citing source bundles), write the body JSON to a temp file, then:
+   ```bash
+   curl -sS -X POST "$API/v1/kb/pages/$PAGE_ID/body" \
+     -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+     --data-binary @/tmp/ricord-rollup.json
+   ```
+
+### Step 4 — Maintain `index.md` and `log.md`
+
+Karpathy's two special files. They live at `.ricord-cache/wiki/`:
+
+- **`index.md`** — catalog. After all bundles are POSTed, write a markdown index: heading per anchor type (Entities, Topics, Epochs), bullet list with a one-line description per anchor. If this is a re-run, *update* the existing file: merge new anchors in, drop ones the new ingest didn't see.
+- **`log.md`** — chronological. Append a single block:
+  ```
+  ## [<YYYY-MM-DD HH:MM>] ingest | <mode> | <repo or url or file>
+  bundles: <N>, anchors: <A>, connections: <C>, tasks: <T>, rollups: <R>, skipped: <S>
+  ```
+  Karpathy's tip: the consistent `## [date]` prefix makes this greppable (`grep "^## \[" log.md | tail -5`).
+
+### Step 5 — Final summary
+
+Emit one line. Nothing more, no intermediate narration:
+
+```
+Init repo: <N> bundles → <A> anchors, <C> connections, <T> tasks, <R> rollups. (skipped: <S>)
+```
+
+## Single-bundle flow (URL / file / conversation)
+
+Skip steps 1, 4-style index. Do:
+
+1. Build one bundle text. Cap at ~30 KB.
+2. Fetch the extraction prompt (step 2 above).
+3. Mentally apply prompt → emit JSON → POST `/v1/ingest/extracted` with appropriate tags (`source:url`, `source:file`, or `source:conversation`).
+4. Handle any `pages_needing_rollup`.
+5. Append to `log.md` (in `~/.ricord/log.md` for non-repo modes — there's no repo cwd to anchor to).
+6. Emit a one-line summary.
+
+## Hard rules
+
+- Do not call any external LLM API. You are the LLM. The whole point is that the agent does the work and Ricord stores it.
+- Do not invent facts the source doesn't state. Skip bundles where there's nothing real to extract; log the skip.
+- Stay within caps (10 anchors / 30 connections / 5 tasks per call). The server enforces them.
+- Do not narrate intermediate work. The user sees the final summary line only. Errors get reported; progress doesn't.
+
+## Why this design
+
+This is Karpathy's "LLM Wiki" applied to Ricord. The repo is the **raw source** (immutable). Ricord stores the **wiki** (KG pages, edges, tasks). This file is the **schema** — the protocol that turns you from a generic chatbot into a disciplined wiki maintainer. The CLI (`ricord init --emit-bundles`) is just the walker; you do the thinking.

package/commands/ricord-lint.md

@@ -0,0 +1,64 @@
+---
+description: Karpathy lint pass over the Ricord wiki — surface contradictions, orphans, stale claims, missing cross-refs.
+argument-hint: [(optional) topic or anchor name to focus on]
+---
+
+You are the worker. This is the **Lint** operation from Karpathy's "LLM Wiki": periodically health-check the wiki and surface what's wrong, so it stays useful as it grows.
+
+Scope: `$ARGUMENTS` (optional — if given, focus the lint pass on pages mentioning this anchor / topic; if empty, do a full pass).
+
+## Sources to read
+
+```bash
+TOKEN=$(jq -r .api_key ~/.ricord/credentials.json)
+API=$(jq -r .api_base ~/.ricord/credentials.json 2>/dev/null || echo https://api.ricord.ai)
+
+# Wiki shape
+curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/kb/pages" > /tmp/ricord-pages.json
+curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/kb/graph" > /tmp/ricord-graph.json
+
+# Recent ingest log (last 10 entries if local file exists)
+[ -f .ricord-cache/wiki/log.md ] && grep "^## \[" .ricord-cache/wiki/log.md | tail -10
+```
+
+If a focus argument was given, additionally:
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  "$API/v1/search?q=$(jq -nr --arg q "$ARGUMENTS" '$q|@uri')&k=20" > /tmp/ricord-focus.json
+```
+
+## What to look for
+
+Walk the page list + graph and produce a report under five headings. Be specific — cite page titles and ids. Don't pad. If a category is empty, say "(none)" and move on.
+
+### 1. Contradictions
+Pages that state mutually exclusive facts about the same anchor. E.g. one page says project X uses Postgres, another says SQLite. List the conflict + both citations.
+
+### 2. Stale claims
+Pages whose claims are likely outdated based on more recent ingests. Look at `last_updated` and `mentioned_in_log_since` to spot pages that haven't been touched in a long time but cover anchors that have appeared in recent log entries.
+
+### 3. Orphans
+Pages with zero inbound edges in the graph. Either they should be deleted, merged into a broader topic, or new cross-references should be added.
+
+### 4. Missing pages
+Concepts mentioned >= 3 times across the wiki (look at anchor mentions in page bodies) that don't yet have their own page. Karpathy: "important concepts mentioned but lacking their own page."
+
+### 5. Suggested next steps
+A short list of:
+- Questions worth investigating (gaps in the wiki where the user would benefit from a new source)
+- Sources worth ingesting (URLs / docs / files the wiki keeps pointing at but hasn't absorbed)
+- Cross-references worth adding (page pairs that should link but don't)
+
+## Output format
+
+A single markdown report. Save it to `.ricord-cache/wiki/lint-<YYYY-MM-DD>.md` and print it. Append a one-liner to `log.md`:
+```
+## [<YYYY-MM-DD HH:MM>] lint | scope: <focus or "full">
+contradictions: <X>, stale: <Y>, orphans: <Z>, missing: <W>, suggestions: <N>
+```
+
+## Hard rules
+
+- Do not modify wiki pages in a lint pass. Lint surfaces problems; the user decides which to fix.
+- Do not invent contradictions. Two pages saying different things about *different* aspects of an anchor is not a contradiction.
+- Do not narrate. Output the report.

package/commands/ricord-query.md

@@ -0,0 +1,71 @@
+---
+description: Ask the Ricord wiki a question — search, synthesize an answer with citations, optionally file it back as a new page.
+argument-hint: <your question>
+---
+
+You are the worker. This is the **Query** operation from Karpathy's "LLM Wiki": ask the wiki a question, get an answer synthesized from the relevant pages, and (optionally) file the answer back into the wiki so explorations compound.
+
+Question: `$ARGUMENTS`
+
+If `$ARGUMENTS` is empty, ask the user what they want to know.
+
+## Search → Read → Synthesize
+
+```bash
+TOKEN=$(jq -r .api_key ~/.ricord/credentials.json)
+API=$(jq -r .api_base ~/.ricord/credentials.json 2>/dev/null || echo https://api.ricord.ai)
+
+# Hybrid search: semantic + graph + memory
+Q=$(jq -nr --arg q "$ARGUMENTS" '$q|@uri')
+curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/search?q=$Q&k=12" > /tmp/ricord-search.json
+
+# For each top hit, fetch the full page body if it's a KB page
+# (search results return excerpts; full body lives at /v1/kb/pages/<id>)
+```
+
+For each top-ranked result:
+1. If it's a memory excerpt, use it directly.
+2. If it's a KB page id, fetch the body: `curl -sS -H "Authorization: Bearer $TOKEN" "$API/v1/kb/pages/<id>"`.
+
+Synthesize an answer. **Cite every claim** with the source memory id or KB page title in brackets, e.g. `[mem:abc123]` or `[kb: Vertex migration]`. If the wiki doesn't have enough to answer well, say so — don't fabricate.
+
+## Output
+
+Print the answer as markdown:
+
+```markdown
+## <one-line restatement of the question>
+
+<2-5 paragraphs of synthesis with inline citations>
+
+### Sources
+- [page or memory title 1] (<id>)
+- [page or memory title 2] (<id>)
+- …
+
+### Gaps
+- <what the wiki doesn't yet know that would improve this answer, if anything>
+```
+
+## File the answer back? (optional)
+
+Karpathy: "good answers can be filed back into the wiki as new pages."
+
+After printing, ask the user one short question: **"File this answer back into the wiki as a page? (y/n)"**
+
+If yes:
+1. POST to `/v1/ingest/extracted` with the answer text as a single message, treating it as a synthesis source. Tag it `kind:synthesis`, `source:query`, and include the original question in metadata.
+2. Append to `log.md`:
+   ```
+   ## [<YYYY-MM-DD HH:MM>] query | filed-back
+   question: <the question>
+   sources_used: <N>, gaps_noted: <Y/N>
+   ```
+
+If no, just append the query log entry without the filed-back bit.
+
+## Hard rules
+
+- Cite everything. Uncited claims are worse than no answer.
+- If the wiki has nothing relevant, say "The wiki doesn't have material on this yet." Suggest sources to ingest.
+- Do not call external search engines or LLM APIs. The only ground truth is the Ricord wiki.

package/dist/cli/auth.d.ts

@@ -0,0 +1,16 @@
+export interface Credentials {
+    api_key: string;
+    api_base?: string;
+    created_at: string;
+}
+/**
+ * Resolve the Ricord token in this order:
+ *   1. explicit `--token` flag
+ *   2. RICORD_TOKEN env var
+ *   3. RICORD_API_KEY env var (matches what `ricord-mcp` reads)
+ *   4. ~/.ricord/credentials.json (written by `ricord login`)
+ */
+export declare function resolveToken(explicit?: string): string | undefined;
+export declare function resolveApiBase(explicit?: string): string;
+export declare function loadCredentials(): Credentials | null;
+export declare function maskKey(key: string): string;

package/dist/cli/auth.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const CREDENTIALS_FILE = join(homedir(), ".ricord", "credentials.json");
+/**
+ * Resolve the Ricord token in this order:
+ *   1. explicit `--token` flag
+ *   2. RICORD_TOKEN env var
+ *   3. RICORD_API_KEY env var (matches what `ricord-mcp` reads)
+ *   4. ~/.ricord/credentials.json (written by `ricord login`)
+ */
+export function resolveToken(explicit) {
+    if (explicit && explicit.length > 0)
+        return explicit;
+    if (process.env.RICORD_TOKEN)
+        return process.env.RICORD_TOKEN;
+    if (process.env.RICORD_API_KEY)
+        return process.env.RICORD_API_KEY;
+    return loadCredentials()?.api_key;
+}
+export function resolveApiBase(explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.RICORD_API_BASE)
+        return process.env.RICORD_API_BASE;
+    return loadCredentials()?.api_base ?? "https://api.ricord.ai";
+}
+export function loadCredentials() {
+    try {
+        if (existsSync(CREDENTIALS_FILE)) {
+            return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf8"));
+        }
+    }
+    catch { }
+    return null;
+}
+export function maskKey(key) {
+    if (key.length <= 16)
+        return "***";
+    return `${key.slice(0, 12)}...${key.slice(-4)}`;
+}
+//# sourceMappingURL=auth.js.map

package/dist/cli/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/cli/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,QAAiB;IAC5C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAC9D,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAClE,OAAO,eAAe,EAAE,EAAE,OAAO,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAiB;IAC9C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IACpE,OAAO,eAAe,EAAE,EAAE,QAAQ,IAAI,uBAAuB,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAClD,CAAC"}

package/dist/cli/bundle.d.ts

@@ -0,0 +1,25 @@
+import { DirGroup } from "./walker.js";
+import { ParsedFile } from "./parse.js";
+export interface DirBundle {
+    rel: string;
+    fileTree: string;
+    readme?: string;
+    parsedFiles: ParsedFile[];
+    externalDeps: string[];
+    internalImports: string[];
+    usedBy: string[];
+}
+export declare function buildBundle(group: DirGroup, root: string): Promise<DirBundle>;
+/**
+ * After all bundles are built, populate `usedBy` on each by inverting the
+ * `internalImports` maps. This is the magic that gives the LLM ground-truth
+ * "Used by" instead of forcing it to guess.
+ */
+export declare function invertUsedBy(bundles: DirBundle[]): void;
+/**
+ * Render a bundle to the prompt-ready text the summarizer LLM will see.
+ * This is the contract that defines summary quality — keep it tight.
+ */
+export declare function renderBundleForPrompt(b: DirBundle, opts?: {
+    maxChars?: number;
+}): string;