@jafreck/lore 0.1.0 → 0.2.1

package/README.md

@@ -1,20 +1,25 @@
 # Lore
 
 [![CI](https://github.com/jafreck/Lore/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jafreck/Lore/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@jafreck/lore)](https://www.npmjs.com/package/@jafreck/lore)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue)](https://www.typescriptlang.org)
 
-**The teammate that has seen it all** Lore is your agent's institutional knowledge over the codebase — it knows what was built, why it changed, and how it all connects. Lore indexes your code and git history into a structured knowledge base that agents query through MCP. It maps symbols, imports, call relationships, and git history — with optional embeddings for semantic search — so agents can reason about your codebase
+**The teammate that has seen it all** 
+
+Lore is your agent's institutional knowledge over the codebase — it knows what was built, why it changed, and how it all connects. Lore indexes your code and git history into a structured knowledge base that agents query through MCP. It maps symbols, imports, call relationships, and git history — with optional embeddings for semantic search — so agents can reason about your codebase
 without re-reading it from scratch.
 
 ## What Lore does
 
 - Parses source files and extracts symbols, imports, and call refs
 - Resolves internal vs external imports and builds call/import graph edges
+- Discovers and indexes documentation (`.md`, `.rst`, `.adoc`, `.txt`) with inferred kinds/titles
 - Stores everything in a normalized SQL schema with optional vector search
-- Enables RAG-style retrieval with semantic/fused search
+- Enables RAG-style retrieval with semantic/fused search across symbols and doc sections
 - Indexes git history (commits, touched files, refs/branches/tags)
+- Enriches symbols with resolved type signatures and definitions via optional index-time LSP integration
 - Supports line-level git blame through MCP
 - Supports automatic refresh via watch mode, poll mode, and git hooks
 
@@ -24,70 +29,72 @@ without re-reading it from scratch.
 flowchart LR
     subgraph Codebase
         SRC[Source Files]
+        DOCS[Documentation<br/>md · rst · adoc · txt]
         GIT[Git Repo]
         COV[Coverage Reports]
     end
 
     subgraph Lore Indexer
-        WALK[Walker]
-        PARSE[Parser]
-        EXTRACT[Extractors<br/>symbols · imports · call refs]
-        RESOLVE[Import Resolver<br/>internal ↔ external]
-        CALLGRAPH[Call-Graph Builder]
-        EMBED[Embedder]
+        WALK[Walker] --> PARSE[Parser] --> EXTRACT[Extractors<br/>symbols · imports · call refs]
+        EXTRACT --> RESOLVE[Import Resolver<br/>internal ↔ external]
+        EXTRACT --> CALLGRAPH[Call-Graph Builder]
+        EXTRACT -.-> LSPENRICH[LSP Enrichment<br/>type signatures · definition locations]
+        DOCSINGEST[Docs Ingest<br/>sections · headings · notes]
         GITHIST[Git History Ingest<br/>commits · diffs · refs]
         COVINGEST[Coverage Ingest<br/>lcov · cobertura]
     end
 
     DB[(SQL DB)]
+    EMBED([Embedding Model])
 
     subgraph MCP Server
-        LOOKUP[kb_lookup]
-        SEARCH[kb_search]
-        GRAPH[kb_graph]
-        SNIPPET[kb_snippet]
-        BLAME[kb_blame]
-        HISTORY[kb_history]
-        METRICS[kb_metrics]
-        WRITEBACK[kb_writeback]
-    end
-
-    subgraph LLM_AGENTS[Agents]
-        CLAUDE[Claude]
-        COPILOT[GitHub Copilot]
-        CUSTOM_AGENT[Custom Agents]
-        CLAUDE ~~~ COPILOT ~~~ CUSTOM_AGENT
+        LOOKUP[lore_lookup]
+        SEARCH[lore_search]
+        DOCS_TOOL[lore_docs]
+        GRAPH[lore_graph]
+        TESTMAP[lore_test_map]
+        SNIPPET[lore_snippet]
+        BLAME[lore_blame]
+        HISTORY[lore_history]
+        COMMITSTATS[lore_commit_stats]
+        METRICS[lore_metrics]
+        COVERAGE[lore_coverage]
+        WRITEBACK[lore_writeback]
     end
 
-    subgraph ENTRY[User Entrypoints]
-        VSCODE[VS Code]
+    subgraph MCP_CLIENTS[MCP Clients — Agents]
+        CLAUDE_CODE[Claude Code / Desktop]
+        COPILOT[VS Code + Copilot]
         CURSOR[Cursor]
-        CHAT[Chat UI]
-        ORCH[Agent Frameworks]
-        VSCODE ~~~ CURSOR ~~~ CHAT ~~~ ORCH
+        CUSTOM[Custom Agent Frameworks]
+        CLAUDE_CODE ~~~ COPILOT ~~~ CURSOR ~~~ CUSTOM
     end
 
-    SRC --> WALK --> PARSE --> EXTRACT
-    EXTRACT --> RESOLVE & CALLGRAPH
-    EXTRACT & RESOLVE & CALLGRAPH --> DB
-    EMBED -.->|optional| DB
+    SRC --> WALK
+    DOCS --> DOCSINGEST --> DB
     GIT --> GITHIST --> DB
     COV --> COVINGEST --> DB
 
-    DB --- LOOKUP & SEARCH & GRAPH & SNIPPET & BLAME & HISTORY & METRICS & WRITEBACK
+    RESOLVE & CALLGRAPH --> DB
+    LSPENRICH -.->|optional| DB
+    RESOLVE -.->|optional| EMBED
+    EMBED -.-> DB
 
-    LOOKUP & SEARCH & GRAPH & SNIPPET & BLAME & HISTORY & METRICS & WRITEBACK <--> LLM_AGENTS
+    DB --- LOOKUP & SEARCH & DOCS_TOOL & GRAPH & TESTMAP & SNIPPET & BLAME & HISTORY & COMMITSTATS & METRICS & COVERAGE & WRITEBACK
+    EMBED <-.->|semantic/fused| SEARCH
 
-    LLM_AGENTS <--- ENTRY
+    LOOKUP & SEARCH & DOCS_TOOL & GRAPH & TESTMAP & SNIPPET & BLAME & HISTORY & COMMITSTATS & METRICS & COVERAGE & WRITEBACK <--> MCP_CLIENTS
 ```
 
 Lore sits between your codebase and any LLM-powered tool. The **indexer**
 pipeline walks source files, parses them into ASTs, and extracts
 symbols/imports/call-refs via language-specific extractors, then resolves
 imports (internal vs external) and builds the call graph. An optional
-**embedder** generates dense vectors for semantic search, and a parallel
-**git history** ingest captures commits, diffs, and refs. Everything is
-persisted to a normalized SQL database. The **MCP server** then exposes that
+**LSP enrichment** pass queries language servers to resolve type signatures
+and jump-to-definition URIs for extracted symbols. An optional **embedder**
+generates dense vectors for semantic search, and a parallel **git history**
+ingest captures commits, diffs, and refs. Everything is persisted to a
+normalized SQL database. The **MCP server** then exposes that
 database as a set of tools that any MCP-compatible client can call to look up
 symbols, search code, traverse call graphs, read snippets, query
 blame/history, and write summaries back.
@@ -120,44 +127,6 @@ npm install @jafreck/lore
 Note: Lore uses native add-ons (`tree-sitter`, `better-sqlite3`). A working
 C/C++ toolchain is required the first time dependencies are built.
 
-## Publish authentication (npm)
-
-Lore publish operations use `NODE_AUTH_TOKEN` (see `.npmrc`) and never commit
-tokens to the repository.
-
-Local publish flow:
-
-```bash
-export NODE_AUTH_TOKEN=<npm automation token>
-npm publish --access public
-```
-
-CI publish flow:
-
-- Add `NODE_AUTH_TOKEN` as a secret in your CI provider (for GitHub Actions,
-  use a repository or environment secret).
-- Ensure publish jobs expose that secret as the `NODE_AUTH_TOKEN` environment
-  variable before running `npm publish`.
-
-## Release publish workflow (`@jafreck/lore@0.1.0`)
-
-Publishing is automated by `.github/workflows/publish.yml`. Creating a version
-tag (for example, `v0.1.0`) or publishing a GitHub Release triggers the npm
-publish job.
-
-Release steps for `@jafreck/lore@0.1.0`:
-
-1. Ensure `package.json` has `"version": "0.1.0"`.
-2. Push the tag: `git tag v0.1.0 && git push origin v0.1.0` (or publish a
-   GitHub Release for `v0.1.0`).
-3. Confirm the workflow logs show `npm publish --dry-run` output before the
-   live `npm publish` step.
-
-Post-publish verification:
-
-- Check the package metadata: `npm view @jafreck/lore version` returns `0.1.0`.
-- Confirm installability: `npm view @jafreck/lore@0.1.0 name version`.
-
 ## Quick start (CLI)
 
 ```bash
@@ -183,196 +152,318 @@ const builder = new IndexBuilder(
 await builder.build();
 ```
 
-### Programmatic configuration examples
+## MCP tools
 
-```ts
-import { IndexBuilder } from '@jafreck/lore';
+| Tool | Purpose |
+|------|---------|
+| `lore_lookup` | Find symbols by name or files by path, including external dependency API symbols and LSP-resolved metadata when available |
+| `lore_search` | Structural BM25, semantic vector, or fused RRF search across symbols and doc sections |
+| `lore_docs` | List, fetch, or search indexed documentation with branch, kind, and path filters |
+| `lore_graph` | Query call/import/module/inheritance edges; call edges include `callee_coverage_percent` |
+| `lore_snippet` | Return source snippets by file path and line range |
+| `lore_test_map` | Return mapped test files (with confidence) for a given source file path |
+| `lore_blame` | Return git blame metadata for a line or line range |
+| `lore_history` | Query commit history by file, commit, author, ref, or recency |
+| `lore_commit_stats` | Git commit analytics: cadence, size, churn, top authors, message patterns, schedule heatmaps, branch activity |
+| `lore_metrics` | Aggregate index metrics plus coverage/staleness fields |
+| `lore_coverage` | Symbol-level coverage, uncovered lines, and staleness metadata |
+| `lore_writeback` | Persist agent-authored symbol summaries |
 
-// Index with embedding model + history options
-await new IndexBuilder(
-  './kb.db',
-  {
-    rootDir: './my-project',
-    includeGlobs: ['src/**'],
-    excludeGlobs: ['**/*.gen.ts'],
-    extensions: ['.ts', '.tsx'],
-  },
-  undefined,
-  {
-    embeddingModel: 'Qwen/Qwen3-Embedding-4B',
-    history: { all: true, depth: 2000 },
-  },
-).build();
+### MCP config example
+
+```json
+{
+  "mcpServers": {
+    "lore": {
+      "command": "npx",
+      "args": ["@jafreck/lore", "mcp", "--db", "/path/to/kb.db"]
+    }
+  }
+}
 ```
 
-## CLI reference
+### lore_docs examples
 
-### lore index
+```json
+{ "action": "list", "branch": "main", "kinds": ["readme", "architecture"] }
+{ "action": "get", "path": "/repo/docs/architecture.md", "branch": "main", "include_sections": true }
+{ "action": "search", "query": "incremental refresh", "kinds": ["guide", "architecture"], "limit": 10 }
+```
 
-Build or update a knowledge base.
+### lore_history modes
 
-```bash
-npx @jafreck/lore index --root <dir> --db <path> [--embedding-model <id>] [--history] [--history-depth <n>] [--history-all] [--include <glob>] [--exclude <glob>] [--language <lang>]
+| Mode | Query |
+|------|-------|
+| `recent` | Newest commits |
+| `file` | Commits that touched a path |
+| `commit` | Full/prefix SHA lookup (+files +refs) |
+| `author` | Commits by author/email substring |
+| `ref` | Commits matching branch/tag ref name |
+
+### lore_blame examples
+
+```json
+{ "path": "/repo/src/index.ts", "line": 120 }
+{ "path": "/repo/src/index.ts", "start_line": 120, "end_line": 140 }
+{ "path": "/repo/src/index.ts", "line": 120, "ref": "main" }
 ```
 
-Key flags:
+## Data ingestion
 
-- `--root <dir>` required source root
-- `--db <path>` required SQLite output path
-- `--embedding-model <id>` embedding model identifier
-- `--history` enable git history ingestion
-- `--history-depth <n>` cap number of ingested commits
-- `--history-all` traverse all refs (branches/tags)
-- `--include` repeatable glob include filter
-- `--exclude` repeatable glob exclude filter
-- `--language` repeatable language filter (mapped to extensions)
+Lore indexes multiple data sources into a normalized SQLite schema. Each source
+has its own ingestion pipeline and can be enabled independently.
 
-### lore refresh
+### Source code
 
-Incremental refresh flow for an existing index.
+The indexer walks source files, parses them into ASTs via tree-sitter, and
+extracts symbols, imports, and call references through language-specific
+extractors. The import resolver classifies each import as internal or external,
+and a call-graph builder creates edges between symbols.
 
-```bash
-npx @jafreck/lore refresh --db <path> --root <dir> [--history] [--history-depth <n>] [--history-all]
-npx @jafreck/lore refresh --db <path> --root <dir> --watch [--history]
-npx @jafreck/lore refresh --db <path> --root <dir> --poll [--history]
+Programmatic example:
+
+```ts
+import { IndexBuilder } from '@jafreck/lore';
+
+await new IndexBuilder('./kb.db', {
+  rootDir: './my-project',
+  includeGlobs: ['src/**'],
+  excludeGlobs: ['**/*.gen.ts'],
+  extensions: ['.ts', '.tsx'],
+}).build();
 ```
 
-Modes:
+### Documentation
 
-- Manual: one-shot incremental refresh and exit
-- Watch: filesystem event driven (`fs.watch`), low latency
-- Poll: periodic mtime diffing, most reliable across filesystems
+Lore discovers and indexes documentation files (`.md`, `.rst`, `.adoc`, `.txt`)
+during both `index` and `refresh` flows. By default it scans:
 
-Coverage reports are auto-detected during build/update/refresh from known paths (`coverage/lcov.info`, `coverage/cobertura-coverage.xml`, `coverage.xml`) and only ingested when newer than the last stored coverage run.
+- `README*` variants
+- `docs/**/*.{md,rst,adoc,txt}`
+- ADR-style paths (`**/{adr,adrs,ADR,ADRS}/**/*` and `**/{ADR,adr}-*`)
+- Top-level architecture/design/overview/changelog/guide files
 
-### lore hooks
+Indexed docs are stored per `(path, branch)` in `docs`, with heading-based
+chunks in `doc_sections`. When embeddings are enabled, section vectors are stored
+in `doc_section_embeddings`.
 
-Install repo-local git hooks that trigger Lore refresh automatically on:
+CLI discovery controls:
 
-- `post-commit`
-- `post-merge`
-- `post-checkout`
-- `post-rewrite`
+- `--docs-include <glob>` / `--docs-exclude <glob>` — repeatable include/exclude filters
+- `--docs-extension <ext>` — repeatable extension filter (e.g. `.md`)
+- `--docs-auto-notes` / `--no-docs-auto-notes` — toggle seeded doc-note upserts (default: enabled)
 
-```bash
-npx @jafreck/lore hooks --root <repo> --db <path>
-npx @jafreck/lore hooks --root <repo> --db <path> --history
+When auto-notes are enabled, Lore seeds `notes` rows for README, architecture,
+and ADR docs using deterministic keys. Each note tracks a `source_hash` for
+staleness detection — `lore_notes_read` reports doc-scoped notes as stale when
+the backing document changes or disappears.
+
+Programmatic example:
+
+```ts
+await new IndexBuilder('./kb.db', {
+  rootDir: './my-project',
+  docsIncludeGlobs: ['**/README*', 'handbook/**/*.rst'],
+  docsExcludeGlobs: ['**/docs/private/**'],
+  docsExtensions: ['.md', '.rst'],
+}).build();
 ```
 
-Note: for `lore hooks`, any history-related flag currently enables history in
-hook-triggered refreshes.
+### Git history
 
-### lore ingest-coverage
+Lore ingests commits, touched files (with change type and diff stats), and
+refs (branches/tags). Enable with `--history`; use `--history-all` to traverse
+all refs and `--history-depth <n>` to cap the number of commits.
 
-Manually ingest an explicit coverage report (useful for CI or non-standard report locations).
+Indexed tables:
 
-```bash
-npx @jafreck/lore ingest-coverage --db <path> --root <dir> --file <path> --format <lcov|cobertura> [--commit <sha>]
+- `commits` — sha, author, author_email, timestamp, message, parents
+- `commit_files` — per-commit touched paths with change type and diff stats
+- `commit_refs` — refs currently pointing at commits (`branch`/`tag`/`other`)
+
+Programmatic example:
+
+```ts
+await new IndexBuilder('./kb.db', {
+  rootDir: './my-project',
+}, undefined, {
+  history: { all: true, depth: 2000 },
+}).build();
 ```
 
-Key flags:
+### Coverage
 
-- `--db <path>` required SQLite output path
-- `--root <dir>` required repository root used to normalize relative coverage paths
-- `--file <path>` required coverage report file path
-- `--format <lcov|cobertura>` required coverage format
-- `--commit <sha>` optional commit override (defaults to `HEAD`)
+Coverage reports are auto-detected during build/update/refresh from known paths
+(`coverage/lcov.info`, `coverage/cobertura-coverage.xml`, `coverage.xml`) and
+only ingested when newer than the last stored coverage run.
 
-### lore mcp
+For non-standard report locations, use `lore ingest-coverage`:
+
+```bash
+npx @jafreck/lore ingest-coverage --db ./kb.db --root ./my-project \
+  --file ./custom/coverage.xml --format cobertura
+```
 
-Start the built-in MCP server over stdio.
+### Embeddings
+
+Lore optionally generates dense vector embeddings for semantic search using a
+sentence-transformers model. The embedding model is downloaded and managed
+automatically — specify it with `--embedding-model`:
 
 ```bash
-npx @jafreck/lore mcp --db <path>
+npx @jafreck/lore index --root ./my-project --db ./kb.db \
+  --embedding-model 'Qwen/Qwen3-Embedding-4B'
 ```
 
-If the embedding model cannot initialize at runtime, semantic/fused search
-gracefully degrades to structural search.
+At query time, `lore_search` in `semantic` or `fused` mode embeds the query
+and performs cosine similarity against stored vectors. If the model cannot
+initialize, search gracefully degrades to structural BM25.
 
-## MCP tools
+### LSP enrichment
 
-| Tool | Purpose |
-|------|---------|
-| `kb_lookup` | Find symbols by name or files by path (optional branch filter) |
-| `kb_search` | Structural BM25, semantic vector, or fused RRF search |
-| `kb_graph` | Query call/import/module/inheritance edges; call edges include `callee_coverage_percent` |
-| `kb_snippet` | Return source snippets by file path and line range |
-| `kb_blame` | Return git blame metadata for a line or line range |
-| `kb_history` | Query history by file, commit, author, ref, or recency |
-| `kb_metrics` | Return aggregate index metrics plus coverage/staleness fields (`coverage_available`, `coverage_commit`, `current_commit`, `commits_behind`, `stale`, global coverage totals) |
-| `kb_coverage` | Return symbol-level coverage, uncovered lines, and staleness metadata for the latest coverage run |
-| `kb_writeback` | Persist symbol summaries into `symbol_summaries` |
+Lore can enrich symbols and call refs with resolved type metadata at index time
+by querying language servers via the Language Server Protocol. Enriched columns:
 
-### MCP config example
+- `resolved_type_signature`, `resolved_return_type`
+- `definition_uri`, `definition_path`
+
+These are persisted in `symbols`, `symbol_refs`, and `external_symbols` tables.
+`lore_lookup` and `lore_search` return them when present. Query handlers stay
+SQLite-only — language servers are never invoked at runtime.
+
+LSP precedence:
+
+1. CLI flags (`--lsp` / `--no-lsp`)
+2. `.lore.config` `lsp.enabled`
+3. Built-in default (`false`)
+
+`.lore.config` example:
 
 ```json
 {
-  "mcpServers": {
-    "lore": {
-      "command": "npx",
-      "args": ["@jafreck/lore", "mcp", "--db", "/path/to/kb.db"]
+  "lsp": {
+    "enabled": true,
+    "timeoutMs": 5000,
+    "servers": {
+      "typescript": { "command": "typescript-language-server", "args": ["--stdio"] },
+      "python": { "command": "pyright-langserver", "args": ["--stdio"] }
     }
   }
 }
 ```
 
-## Git history indexing
+Default server mappings cover all supported extractor languages:
 
-Lore can ingest full git history and expose it through `kb_history`.
+| Language(s) | Default command |
+|-------------|------------------|
+| `c`, `cpp`, `objc` | `clangd` |
+| `rust` | `rust-analyzer` |
+| `python` | `pyright-langserver --stdio` |
+| `typescript`, `javascript` | `typescript-language-server --stdio` |
+| `go` | `gopls` |
+| `java` | `jdtls` |
+| `csharp` | `csharp-ls` |
+| `ruby` | `solargraph stdio` |
+| `php` | `intelephense --stdio` |
+| `swift` | `sourcekit-lsp` |
+| `kotlin` | `kotlin-language-server` |
+| `scala` | `metals` |
+| `lua` | `lua-language-server` |
+| `bash` | `bash-language-server start` |
+| `elixir` | `elixir-ls` |
+| `zig` | `zls` |
+| `dart` | `dart language-server --protocol=lsp` |
+| `ocaml` | `ocamllsp` |
+| `haskell` | `haskell-language-server-wrapper --lsp` |
+| `julia` | `julia --startup-file=no --history-file=no --quiet --eval "using LanguageServer, SymbolServer; runserver()"` |
+| `elm` | `elm-language-server` |
 
-### Indexed history tables
+Install whichever language servers you need on `PATH`; unavailable servers are
+auto-detected and skipped without failing indexing.
 
-- `commits`: sha, author, author_email, timestamp, message, parents
-- `commit_files`: per-commit touched paths with change type and diff stats
-- `commit_refs`: refs currently pointing at commits (`branch`/`tag`/`other`)
+### Dependency APIs
 
-### kb_history modes
+Lore can index declaration-level public API surface from direct dependencies.
+Enable with `--index-deps` or `indexDependencies: true` programmatically.
 
-- `recent`: newest commits
-- `file`: commits that touched a path
-- `commit`: full/prefix sha lookup (+files +refs)
-- `author`: commits by author/email substring
-- `ref`: commits matching branch/tag ref name substring
+Supported ecosystems:
 
-## Blame queries
+- **TypeScript/JavaScript** — exported declarations from `.d.ts` files in direct npm dependencies
+- **Python** — stubbed/public declarations from direct dependencies via `.pyi` and `py.typed`
+- **Go** — exported declarations from direct module requirements in `go.mod`
+- **Rust** — `pub` declarations from crates in `Cargo.toml`
 
-Use `kb_blame` for line-level attribution.
+Implementation bodies are excluded and transitive dependencies are not crawled.
 
-Examples:
+## Keeping the index fresh
 
-```json
-{ "path": "/repo/src/index.ts", "line": 120 }
-{ "path": "/repo/src/index.ts", "start_line": 120, "end_line": 140 }
-{ "path": "/repo/src/index.ts", "line": 120, "ref": "main" }
+The index stays current automatically through three mechanisms:
+
+**Git hooks** — install once with `lore hooks`, and Lore refreshes on every
+`post-commit`, `post-merge`, `post-checkout`, and `post-rewrite`:
+
+```bash
+npx @jafreck/lore hooks --root ./my-project --db ./kb.db --history
 ```
 
-## Automatic freshness patterns
+**Watch mode** — reacts to filesystem events in real time:
 
-If you want Lore to stay updated without explicit requests:
+```bash
+npx @jafreck/lore refresh --db ./kb.db --root ./my-project --watch
+```
 
-1. Run `lore hooks` once in the repo (git lifecycle updates)
-2. Optionally run `lore refresh --watch` in a background session for near-real-time updates during active editing
-3. Use `--poll` on filesystems where watch events are unreliable
+**Poll mode** — periodic mtime diffing, most reliable across filesystems:
 
-## Benchmarking index performance (500+ file repos)
+```bash
+npx @jafreck/lore refresh --db ./kb.db --root ./my-project --poll
+```
 
-Use this procedure when you need measurable before/after evidence for indexing changes:
+Each refresh only re-processes files whose content hash has changed, so updates
+are fast even on large repositories.
 
-1. Pick a repository with at least 500 source files and note the exact commit SHA you will test.
-2. Capture a baseline timing from the same machine and environment:
+## CLI reference
+
+### lore index
+
+Build or update a knowledge base.
 
 ```bash
-time npx @jafreck/lore index --root /path/to/repo --db ./kb-baseline.db
+npx @jafreck/lore index --root <dir> --db <path> [--embedding-model <id>] [--index-deps] [--history] [--history-depth <n>] [--history-all] [--include <glob>] [--exclude <glob>] [--language <lang>] [--docs-include <glob>] [--docs-exclude <glob>] [--docs-extension <ext>] [--docs-auto-notes|--no-docs-auto-notes] [--lsp] [--no-lsp]
 ```
 
-3. Apply your change, rebuild Lore, then capture a post-change timing against the same repository commit:
+### lore refresh
+
+Incremental refresh (one-shot, watch, or poll).
 
 ```bash
-npm run build
-time npx @jafreck/lore index --root /path/to/repo --db ./kb-after.db
+npx @jafreck/lore refresh --db <path> --root <dir> [--index-deps] [--history] [--history-depth <n>] [--history-all] [--docs-include <glob>] [--docs-exclude <glob>] [--docs-extension <ext>] [--docs-auto-notes|--no-docs-auto-notes] [--lsp] [--no-lsp]
+npx @jafreck/lore refresh --db <path> --root <dir> --watch [--index-deps] [--history] [--docs-include <glob>] [--docs-exclude <glob>] [--docs-extension <ext>] [--lsp] [--no-lsp]
+npx @jafreck/lore refresh --db <path> --root <dir> --poll [--index-deps] [--history] [--docs-include <glob>] [--docs-exclude <glob>] [--docs-extension <ext>] [--lsp] [--no-lsp]
 ```
 
-4. Record both timings (baseline and post-change) in the related GitHub issue or PR under an "Acceptance Evidence" section, including repo name, commit SHA, and command used.
+### lore hooks
+
+Install repo-local git hooks for automatic refresh.
+
+```bash
+npx @jafreck/lore hooks --root <repo> --db <path> [--history] [--lsp] [--no-lsp]
+```
+
+### lore ingest-coverage
+
+Manually ingest a coverage report.
+
+```bash
+npx @jafreck/lore ingest-coverage --db <path> --root <dir> --file <path> --format <lcov|cobertura> [--commit <sha>]
+```
+
+### lore mcp
+
+Start the MCP server over stdio.
+
+```bash
+npx @jafreck/lore mcp --db <path>
+```
 
 ## Build from source
 
@@ -400,6 +491,64 @@ npm run coverage
 
 CI enforces a minimum 95% coverage threshold.
 
+## Publish authentication (npm)
+
+Lore publish operations use `NODE_AUTH_TOKEN` (see `.npmrc`) and never commit
+tokens to the repository.
+
+Local publish flow:
+
+```bash
+export NODE_AUTH_TOKEN=<npm automation token>
+npm publish --access public
+```
+
+CI publish flow:
+
+- Add `NODE_AUTH_TOKEN` as a secret in your CI provider (for GitHub Actions,
+  use a repository or environment secret).
+- Ensure publish jobs expose that secret as the `NODE_AUTH_TOKEN` environment
+  variable before running `npm publish`.
+
+## Release publish workflow (`@jafreck/lore@0.1.0`)
+
+Publishing is automated by `.github/workflows/publish.yml`. Creating a version
+tag (for example, `v0.1.0`) or publishing a GitHub Release triggers the npm
+publish job.
+
+Release steps for `@jafreck/lore@0.1.0`:
+
+1. Ensure `package.json` has `"version": "0.1.0"`.
+2. Push the tag: `git tag v0.1.0 && git push origin v0.1.0` (or publish a
+   GitHub Release for `v0.1.0`).
+3. Confirm the workflow logs show `npm publish --dry-run` output before the
+   live `npm publish` step.
+
+Post-publish verification:
+
+- Check the package metadata: `npm view @jafreck/lore version` returns `0.1.0`.
+- Confirm installability: `npm view @jafreck/lore@0.1.0 name version`.
+
+## Benchmarking index performance (500+ file repos)
+
+Use this procedure when you need measurable before/after evidence for indexing changes:
+
+1. Pick a repository with at least 500 source files and note the exact commit SHA you will test.
+2. Capture a baseline timing from the same machine and environment:
+
+```bash
+time npx @jafreck/lore index --root /path/to/repo --db ./kb-baseline.db
+```
+
+3. Apply your change, rebuild Lore, then capture a post-change timing against the same repository commit:
+
+```bash
+npm run build
+time npx @jafreck/lore index --root /path/to/repo --db ./kb-after.db
+```
+
+4. Record both timings (baseline and post-change) in the related GitHub issue or PR under an "Acceptance Evidence" section, including repo name, commit SHA, and command used.
+
 ## License
 
 [MIT](LICENSE)