diff --git a/README.md b/README.md
index 529e44e..9f239df 100644
--- a/README.md
+++ b/README.md
@@ -6,676 +6,186 @@
 [![Rust Version](https://img.shields.io/badge/rust-1.91%2B-orange)](https://www.rust-lang.org)
 [![Docs](https://img.shields.io/badge/docs-docs.agentis.tools-blue)](https://docs.agentis.tools/)
 
-**AI coding agents write fast, sloppy code** — they duplicate logic that already exists, drift the architecture, and declare "done" without proof. **`ctx` is the local quality authority for AI-written code**: a single local binary that builds a queryable model of your codebase and uses it to both *guide* your agent (a map before it starts, the blast radius of every edit) and *govern* it (your architecture rules and quality thresholds as deterministic gates it can't ship past). Rules live in your repo as code; checks run in milliseconds inside the agent's loop; nothing leaves your machine.
+**AI coding agents write fast, sloppy code.** They duplicate logic that already exists, drift the
+architecture, and declare "done" without proof.
 
-> Unlike code-graph tools, ctx governs what agents *write* — not just what they read. Unlike quality platforms, it does so in milliseconds, locally, with gates you own.
+**`ctx` is the local quality authority for AI-written code.** It's a single local binary that turns
+your repo into a queryable model (every symbol, call, and dependency) and uses it to **ground**
+your agent and **gate** its output on every turn:
 
-📖 **Documentation:** https://docs.agentis.tools/
-
-## Two Tools in One
-
-**Context Generation** - Select files using glob patterns and get formatted output perfect for LLMs:
-```bash
-ctx src/ | pbcopy  # Copy source files to clipboard
-```
-
-**Code Intelligence** - Build a searchable index of your codebase with call graphs and impact analysis:
-```bash
-ctx index          # Index your codebase
-ctx search "auth"  # Find symbols
-ctx query callers handleLogin  # Who calls this function?
-```
-
-## Features
-
-### Context Generation
-- **Glob pattern support** - Select files with patterns like `"src/**/*.rs"` or `"**/*.ts"`
-- **Smart ignore system** - Respects `.gitignore` and `.contextignore`
-- **Built-in filtering** - Excludes binary files, `node_modules`, build artifacts, and 170+ patterns
-- **Multiple output formats** - XML (default), Markdown, JSON, or plain text
-- **Project tree visualization** - ASCII tree showing file structure
-- **Streaming output** - Files output as processed, pipeable to clipboard
-- **Token counting** - Count tokens for LLM context window management
-
-### Code Intelligence
-- **Multi-language parsing** - Rust, TypeScript, JavaScript, JSX/TSX, Python, Go, Solidity, YAML
-- **Symbol extraction** - Functions, classes, interfaces, structs, enums, traits
-- **Rich relationship tracking** - Calls, extends, implements, and imports edges
-- **Call graph analysis** - Track function calls and dependencies
-- **Impact analysis** - See what would be affected by changing a symbol
-- **Keyword search** - FTS5-powered search across symbols and documentation
-- **Semantic search** - Embedding-based natural language search (local or OpenAI)
-- **Watch mode** - Automatic reindexing on file changes
-
-### Advanced Features
-- **Smart context selection** - AI-powered file selection based on task description
-- **Diff-aware context** - Generate context focused on git changes
-- **PR review context** - GitHub integration for pull request analysis
-- **Code quality audit** - Automated quality analysis with CI integration
-- **Quality gates** - Architecture rules (`ctx check`) and change scoring (`ctx score`) with a 0/1/2 exit-code convention for CI and AI agents
-- **Interactive shell** - REPL for codebase exploration
-- **MCP server** - Claude Desktop integration via Model Context Protocol
-
-## Feature Flags
-
-- **`duckdb`** (enabled by default) — Enables DuckDB-powered analytics (call graphs, impact analysis, complexity analysis). Disable with `--no-default-features` on platforms where DuckDB cannot compile (e.g. Windows MSVC without C++ build tools).
-- **`mcp`** — Enable Model Context Protocol server support for Claude Desktop integration.
-
-## Installation
-
-From crates.io (the package is `agentis-ctx`; it installs the `ctx` binary):
-
-```bash
-cargo install agentis-ctx
-
-# On Windows (MSVC without C++ build tools), skip the DuckDB feature:
-cargo install agentis-ctx --no-default-features
-```
-
-From a local checkout:
-
-```bash
-cargo install --path .
-```
-
-Or build from source:
-```bash
-cargo build --release
-# Binary at ./target/release/ctx
-```
-
-### With MCP Support (for Claude Desktop)
-```bash
-cargo build --release --features mcp
-```
-
-### Updating
-
-If you installed a release binary, ctx can update itself from GitHub releases:
-
-```bash
-ctx self-update                    # update to the latest release
-ctx self-update --version 0.3.0    # pin an exact release
-ctx --version --check              # just compare, never install
-```
-
-Every download is verified against the release's `SHA256SUMS` file before the
-binary is replaced; on mismatch the update aborts (exit 2) and the installed
-binary is untouched. Cargo installs should update with
-`cargo install agentis-ctx` instead.
-
-**ctx never updates itself automatically.** On interactive runs it checks for
-a newer release at most once per 24h (1s timeout, silent failure) and prints a
-one-line notice to stderr — nothing more. Set `CTX_NO_UPDATE_CHECK=1` to
-silence the notice entirely; it is also suppressed in `--json` mode, when
-stderr is not a terminal, and inside Claude Code hooks.
-
-The Claude Code plugin generated by `ctx harness init --mode plugin` is
-versioned in lockstep with the binary and updates through Claude Code itself
-via `/plugin update ctx`. For frozen, reproducible installs, pin the
-marketplace entry to a commit SHA when adding it
-(`/plugin marketplace add agentis-tools/ctx@<commit-sha>`) — the plugin
-then never moves until you re-pin, and the generated permissions deny
-`Bash(ctx self-update*)` so agents cannot update the binary either. See
-[`docs/commands/self-update.md`](docs/commands/self-update.md).
-
-## Using ctx as a Library
-
-Everything the CLI does is available as a Rust library, so you can embed
-indexing, search, and context generation in your own tools. The package is
-`agentis-ctx`, but the library target is named `ctx`:
-
-```toml
-[dependencies]
-agentis-ctx = "0.3"
-
-# On Windows (or to skip DuckDB analytics):
-# agentis-ctx = { version = "0.3", default-features = false }
-```
-
-```rust
-use ctx::prelude::*;
-use std::path::Path;
-
-fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
-    let root = Path::new("./my-project");
-
-    // Build (or incrementally update) the index at .ctx/codebase.sqlite
-    let mut indexer = Indexer::with_config(root, false, WalkerConfig::default())?;
-    let result = indexer.index()?;
-    println!("{} symbols extracted", result.symbols_extracted);
-
-    // Keyword search over the indexed symbols
-    let db = open_database(root)?;
-    for symbol in db.find_symbols("authenticate", 10)? {
-        println!("{} ({}:{})", symbol.name, symbol.file_path, symbol.line_start);
-    }
-    Ok(())
-}
-```
-
-The [API documentation](https://docs.rs/agentis-ctx) covers the full surface:
-smart context selection (`smart`), diff-aware context (`diff`), semantic
-search via local or OpenAI embeddings (`embeddings`), call-graph analytics
-(`analytics`), token counting (`tokens`), and output formatting
-(`formatter`/`output`).
-
-## Quick Start
-
-### Generate Context for LLMs
-
-```bash
-# All files in current directory
-ctx
-
-# Specific patterns
-ctx "src/**/*.rs" "**/*.ts"
-
-# Copy to clipboard (macOS)
-ctx src/ | pbcopy
-
-# Markdown format
-ctx --format markdown src/
-
-# JSON format
-ctx --format json src/
-
-# Count tokens only
-ctx --count-only src/
-
-# Limit output to token budget
-ctx --max-tokens 8000 src/
-```
-
-### Code Intelligence
-
-```bash
-# Build the index (creates .ctx/codebase.sqlite)
-ctx index
-
-# Search for symbols (keyword matching)
-ctx search "handleRequest"
-
-# Generate embeddings for semantic search
-ctx embed                          # Local model (default, ~90MB download)
-ctx embed --openai                 # OpenAI API (requires OPENAI_API_KEY)
-
-# Semantic search (natural language)
-ctx semantic "authentication logic"
-ctx semantic "error handling" --openai
-
-# Find all callers of a function
-ctx query callers authenticate
-
-# See what a function depends on
-ctx query deps processPayment
-
-# Visualize call graph
-ctx query graph main --depth 3
-
-# Impact analysis - what breaks if I change this?
-ctx query impact validateInput
-
-# Watch for changes and auto-reindex
-ctx index --watch
-```
-
-## Output Formats
-
-### XML (default)
-```xml
-<context>
-<project_tree>
-my-project/
-├── src/
-│   ├── main.rs
-│   └── lib.rs
-└── Cargo.toml
-</project_tree>
-<project_files>
-<file name="main.rs" path="/src/main.rs">
-fn main() {
-    println!("Hello, world!");
-}
-</file>
-</project_files>
-</context>
-```
-
-### Markdown
-```markdown
-# Project Context
-
-## Project Tree
-```
-my-project/
-├── src/
-│   └── main.rs
-└── Cargo.toml
-```
-
-## /src/main.rs
-```rust
-fn main() {
-    println!("Hello, world!");
-}
-```
-```
-
-### JSON
-```json
-{
-  "project_tree": "my-project/\n├── src/\n│   └── main.rs\n└── Cargo.toml",
-  "files": [
-    {
-      "name": "main.rs",
-      "path": "/src/main.rs",
-      "content": "fn main() {\n    println!(\"Hello, world!\");\n}"
-    }
-  ]
-}
-```
-
-## Code Intelligence Commands
-
-### `ctx index`
-Build or update the code intelligence database.
-
-```bash
-ctx index                    # Incremental index
-ctx index --force            # Full reindex (clears database)
-ctx index --watch            # Watch mode with auto-reindex
-ctx index --verbose          # Show files being indexed
-ctx index --parallel         # Use parallel parsing (faster on multi-core)
-ctx index --no-gitignore     # Include gitignored files
-ctx index -i "tests/"        # Additional ignore patterns
-ctx index -p "src/**/*.rs"   # Only index specific patterns
-```
+- **Ground:** hand the agent a map before it starts, and the right ~8k tokens of context instead of
+  the wrong 233k.
+- **Govern:** show the blast radius of every edit, and enforce your architecture rules as
+  deterministic gates it can't ship past.
 
-### `ctx search <query>`
-Search for symbols using keyword matching (FTS5).
+Rules live in your repo as code, checks run in milliseconds inside the agent's loop, and nothing
+leaves your machine.
 
-```bash
-ctx search "auth"                  # Find symbols related to auth
-ctx search "handleRequest"         # Find exact symbol names
-ctx search "parse config" --limit 10
-ctx search "handler" --output json # JSON output
-```
-
-### `ctx semantic <query>`
-Search using embeddings for natural language queries.
-
-```bash
-ctx semantic "authentication logic"     # Local embeddings (default)
-ctx semantic "error handling" --openai  # OpenAI embeddings
-ctx semantic "database queries" --limit 20
-```
-
-### `ctx similar <description>`
-Find existing functions similar to a description — reuse before you write. Before writing a new function, run `ctx similar` with its intended purpose; if a strong match exists (high similarity and fan-in), extend or reuse it instead.
+> Unlike code-graph tools, ctx governs what agents *write*, not just what they read. Unlike quality
+> platforms, it does so in milliseconds, locally, with gates you own.
 
-```bash
-ctx similar "parse a config file into a struct"   # Embedding search (functions/methods only)
-ctx similar "retry with backoff" --keyword        # FTS5 fallback, no embeddings needed
-ctx similar "count tokens" --limit 5 --json       # Machine-readable output
-```
-
-Each hit shows the symbol, similarity score, fan-in (how many callers it already has), and a one-line doc. Requires `ctx embed` first (exits with code 2 otherwise); `--keyword` works without embeddings.
+📖 **Documentation:** https://docs.agentis.tools/
 
-### `ctx embed`
-Generate embeddings for semantic search.
+## Install
 
 ```bash
-ctx embed                    # Generate with local model
-ctx embed --openai           # Generate with OpenAI API
-ctx embed --force            # Re-embed all symbols
-ctx embed --verbose          # Show progress
-ctx embed --batch-size 100   # Custom batch size
-ctx embed --watch            # Watch for index changes and auto-embed
+cargo install agentis-ctx        # crate is `agentis-ctx`; it installs the `ctx` binary
 ```
 
-### `ctx query`
-Query the code intelligence database.
+Prebuilt binaries for Linux (x86_64), macOS (Intel + Apple Silicon), and Windows (x86_64) are
+attached to each [GitHub release](https://github.com/agentis-tools/ctx/releases). Once installed,
+`ctx self-update` upgrades in place (every download is checksum-verified against the release's
+`SHA256SUMS` before replacing the binary).
 
 ```bash
-# Find symbols by name pattern
-ctx query find "handle*" --kind function
-ctx query find "User*" --file "src/models/*.rs"
-
-# Show callers of a function
-ctx query callers myFunction --depth 3
-
-# Show dependencies of a symbol
-ctx query deps MyClass --depth 2
-
-# Visualize call graph (text, json, or dot format)
-ctx query graph entryPoint --depth 5 --output dot
-
-# Impact analysis
-ctx query impact criticalFunction --depth 5
-
-# Codebase statistics
-ctx query stats
-
-# List all indexed files
-ctx query files
+# On Windows (MSVC), DuckDB analytics aren't available, so skip the default feature:
+cargo install agentis-ctx --no-default-features
 ```
 
-### `ctx sql`
-Run read-only SQL against the code intelligence index through DuckDB, over a
-stable `v1` view layer (`v1.symbols`, `v1.edges`, `v1.files`, `v1.meta`). Reach
-for `ctx sql` instead of the canned `ctx query` subcommands whenever you need an
-aggregation, a join, or a custom `WHERE` condition. Query `v1.*` only — anything
-else (e.g. `code.*`) is internal and unstable. For agents and scripts, use
-`--json` with `--max-rows`. Run `ctx sql --schema` for the full column reference.
+See the [Getting Started guide](https://docs.agentis.tools/docs/getting-started) for the full
+platform matrix.
 
-```bash
-# Ten most complex symbols
-ctx sql "SELECT name, file, complexity FROM v1.symbols ORDER BY complexity DESC LIMIT 10;"
-
-# Symbol counts by kind
-ctx sql "SELECT kind, COUNT(*) AS n FROM v1.symbols GROUP BY kind ORDER BY n DESC;"
+## The loop: index → ground → govern
 
-# Public functions that nothing calls (dead-code candidates)
-ctx sql "SELECT name, file FROM v1.symbols WHERE kind IN ('function', 'method') AND is_public AND fan_in = 0 ORDER BY file, name;"
-```
-
-Use `--fail-on-rows` to turn a query into a gate: any returned row is a
-violation, and the command exits `1`.
+**Build the model first.** Every intelligence and governance command reads a prebuilt index, so
+`ctx index` always comes first (it writes a single `.ctx/codebase.sqlite`). On this repo it indexes
+**870 symbols and 5,463 call edges in 0.36s.** Run it once, then keep it warm with `--watch`.
 
 ```bash
-# Fails (exit 1) if the query returns any row
-ctx sql --fail-on-rows --file .ctx/gates/no-utils-imports.sql
+ctx index                        # build the world model (or `ctx index --watch` in the background)
 ```
 
-Access is read-only and engine-hardened (filesystem access, extension loading,
-and file-based `ATTACH` are disabled; the index cannot be modified), so
-`Bash(ctx sql *)` is safe to add to a Claude Code allow-list.
-
-### `ctx explain <symbol>`
-Get detailed information about a symbol including its relationships.
+**Ground:** feed the agent the right context, selected by meaning *and* call-graph relevance:
 
 ```bash
-ctx explain handleAuth
-ctx explain MyClass --file "src/models/*.rs"
-ctx explain process --kind function
+ctx smart "add rate limiting" --max-tokens 8000   # ~8.7k tokens instead of 233k, about 27× smaller
+ctx diff --summary                                # context for what changed, with dependency expansion
+ctx similar "retry with backoff"                  # reuse before you write: find it if it already exists
 ```
 
-### `ctx source <symbol>`
-Retrieve the source code for a symbol.
+**Govern:** guardrail what the agent changes, with deterministic pass/fail gates:
 
 ```bash
-ctx source MyClass::processData
-ctx source authenticate --file "src/auth/*.rs"
+ctx check --against origin/main                                   # enforce architecture rules
+ctx score --fail-on "check_violations>0,new_duplication>0"       # one composite quality gate
 ```
 
-## Smart Context Selection
-
-Intelligently select files relevant to a task using semantic search and call graph analysis:
+## One model, two jobs
 
-```bash
-ctx smart "add user authentication" --max-tokens 8000
-ctx smart "fix login bug" --explain      # Show selection reasoning
-ctx smart "refactor parser" --dry-run    # Preview without output
-ctx smart "add caching" --openai         # Use OpenAI embeddings
-ctx smart "update API" --depth 3         # Deeper call graph expansion
-ctx smart "fix tests" --top 20           # More initial semantic matches
-```
+ctx indexes your repo into a structured, queryable model: symbols, call graphs, relationships, and
+semantics. Not a bag of files, but a model an agent (or you) can ask questions of. That one model
+does two jobs: it feeds the model the right context going *in*, and guardrails what it changes coming
+*out*.
 
-**Options:**
-- `--max-tokens <N>` - Maximum tokens in output (default: 8000)
-- `--depth <N>` - Call graph expansion depth (default: 2)
-- `--top <N>` - Number of initial semantic matches (default: 10)
-- `--explain` - Show selection reasoning for each file
-- `--dry-run` - Preview selection without generating context
-- `--openai` - Use OpenAI embeddings instead of local model
+### Ground: the right context, in
 
-## Diff-Aware Context
+| Command | What it does |
+|---|---|
+| [`ctx smart "<task>"`](https://docs.agentis.tools/docs/commands/smart) | Rank files by semantic + call-graph relevance, fit to a token budget |
+| [`ctx map`](https://docs.agentis.tools/docs/commands/map) | Token-budgeted architectural overview (PageRank over the symbol graph) |
+| [`ctx diff`](https://docs.agentis.tools/docs/commands/diff) | Context for git changes, with automatic dependency expansion |
+| [`ctx similar "<description>"`](https://docs.agentis.tools/docs/commands/similar) | Find existing functions before writing new ones (with fan-in) |
+| `ctx search` / `ctx semantic` | Keyword (FTS5) and embedding-based symbol search |
+| `ctx query impact / callers / deps / graph` | Walk the call graph: blast radius, callers, dependencies |
 
-Get context for changed files with automatic dependency expansion:
+Plain `ctx` is also a **context generator:** select files by glob and stream LLM-ready output:
 
 ```bash
-ctx diff                      # Changes since HEAD~1
-ctx diff main                 # Changes vs main branch
-ctx diff HEAD~3               # Changes in last 3 commits
-ctx diff --staged             # Only staged changes
-ctx diff --summary            # Include change summary
-ctx diff --changes-only       # No context expansion
-ctx diff --max-tokens 10000   # Custom token budget
-ctx diff --depth 2            # Call graph context depth
+ctx src/ | pbcopy                 # copy source to the clipboard (XML by default)
+ctx --format markdown src/        # or Markdown / JSON / plain
+ctx --count-only src/             # just count tokens against your model's window
+ctx --max-tokens 8000 "src/**/*.rs"
 ```
 
-## PR Review Context
-
-Generate context for GitHub pull request review:
+Semantic search and `ctx smart`/`ctx similar` need embeddings first. Generate them with
+`ctx embed` (a ~90 MB local model by default, or `--openai` with `OPENAI_API_KEY`). See
+[Index & embed first](https://docs.agentis.tools/docs/guides/indexing).
 
-```bash
-ctx review 123                      # PR #123 in current repo
-ctx review 123 --repo owner/name    # Specify repository
-ctx review 123 --include-comments   # Include PR comments
-ctx review 123 --summary            # Include change summary
-ctx review 123 --changes-only       # Only changed files
-```
+### Govern: guardrails on what changes
 
-**Requirements:** GitHub CLI (`gh`) must be installed and authenticated.
+| Command | What it does | Gate |
+|---|---|---|
+| [`ctx check`](https://docs.agentis.tools/docs/commands/check) | Enforce architecture rules from `.ctx/rules.toml` over the real edge graph | Exit 1 on any violation |
+| [`ctx score`](https://docs.agentis.tools/docs/commands/score) | Composite delta: check violations + new duplication + complexity/fan-out | `--fail-on "<expr>"` |
+| [`ctx duplicates`](https://docs.agentis.tools/docs/commands/duplicates) | MinHash near-duplicate detection over normalized token shingles | `--fail-on-found` |
+| [`ctx hotspots`](https://docs.agentis.tools/docs/commands/hotspots) | Rank refactoring targets by churn × complexity | informational |
+| [`ctx sql`](https://docs.agentis.tools/docs/commands/sql) | Read-only SQL over the stable `v1.*` views for custom queries and gates | `--fail-on-rows` |
 
-## Quality Gates
+Architecture rules live in your repo as code (`.ctx/rules.toml`: layers, forbidden dependencies,
+fan-in/complexity limits) and `--against <ref>` scopes any gate to only what a diff changed, so a PR
+or an agent is judged on its *new* violations, not the repo's history.
 
-A suite of quality commands designed to be composed into CI pipelines and AI
-agent hooks: `ctx check` (architecture rules from `.ctx/rules.toml`),
-`ctx score` (quality delta of your changes vs. a git reference),
-`ctx duplicates` (MinHash near-duplicate detection), `ctx hotspots`
-(churn x complexity refactoring targets), `ctx similar` (find existing
-functions before writing new ones), and `ctx map` (token-budgeted codebase
-overview for LLM sessions).
-
-All of them share a three-way exit-code convention -- that convention is the
-integration API:
+**Exit codes are the integration API.** Every governance command shares one convention, so CI and
+agents read the result the same way:
 
 | Code | Meaning |
 |------|---------|
-| 0 | Success, nothing to report |
-| 1 | Ran successfully but produced findings |
-| 2 | Operational error (bad arguments, missing index, git failure, ...) |
-
-```bash
-# Enforce architecture rules; --against reports only new violations
-ctx check --against main
-
-# Score your changes: complexity/fan-out deltas, new duplication,
-# rule violations, symbol churn -- with CI gate conditions
-ctx score --against main --fail-on "check_violations>0,new_duplication>0"
-
-# Wire the whole suite into Claude Code (hooks, permissions, plugin scaffold)
-ctx harness init
-```
-
-See the [Quality Gates guide](https://docs.agentis.tools/docs/integrations/quality-gates)
-for the full suite, CI recipes, and the reference Claude Code hook
-configuration, and [`docs/json-output.md`](docs/json-output.md) for the
-machine-readable `--json` contract.
-
-## Code Quality Audit
-
-Automated quality analysis with CI integration:
-
-```bash
-ctx audit                          # Full quality report
-ctx audit --min-score 7.0          # Quality gate (exit 1 if below)
-ctx audit --output json            # JSON output for CI
-ctx audit --output markdown        # Markdown report
-ctx audit --categories complexity,duplication  # Specific categories
-ctx audit --incremental            # Only changed files (pre-commit)
-```
+| `0` | Success, nothing to report |
+| `1` | Ran successfully but produced findings (rule violations, gate hit) |
+| `2` | Operational error (bad arguments, missing index, git failure) |
+| `3` | Version requirement not met (reserved for `ctx harness compat --require`) |
 
-**Categories:**
-- `complexity` - Function complexity (fan-out/fan-in analysis)
-- `duplication` - Potential code duplication
-- `coverage` - Documentation coverage
-- `modularity` - Module coupling analysis
-- `naming` - Naming convention checks
+See the [Quality Gates guide](https://docs.agentis.tools/docs/integrations/quality-gates) for CI
+recipes and the [`--json` contract](https://docs.agentis.tools/docs/json-output).
 
-## Complexity Analysis
+## Drop it into Claude Code
 
-Analyze code complexity and identify high fan-out functions:
+The point of ctx is to run *inside the agent's loop*, not beside it. One command wires the whole
+suite into Claude Code as hooks, with the guardrails already set:
 
 ```bash
-ctx complexity                     # Default threshold (10)
-ctx complexity --threshold 20      # Custom threshold
-ctx complexity --warnings-only     # Only show issues
-ctx complexity --output json       # JSON output
+ctx harness init --target claude          # local hooks in .claude/ (or --mode plugin for a shareable plugin)
 ```
 
-## Duplicate Detection
-
-Detect structurally similar functions with MinHash fingerprints built during
-`ctx index`. Functions are compared by the Jaccard similarity of their
-normalized token shingles (identifiers -> `ID`, literals -> `LIT`, comments
-dropped), so renamed variables and changed string literals still match.
-Solidity functions are skipped (no tree-sitter grammar).
-
-```bash
-ctx duplicates                     # Default: Jaccard >= 0.85, >= 50 tokens
-ctx duplicates --threshold 0.9     # Require 90% shingle overlap (0.0-1.0)
-ctx duplicates --min-tokens 80     # Ignore functions under 80 tokens
-ctx duplicates --against main      # Only pairs touching files changed vs main
-ctx duplicates --fail-on-found     # Exit 1 when any pair is found (CI gate)
-ctx duplicates --json              # Machine-readable JSON envelope
-```
-
-> **Breaking change:** the old line-based `--similarity <PERCENT>` /
-> `--min-lines <N>` flags are gone. `--threshold` is a 0.0-1.0 Jaccard
-> similarity over 5-token shingles, not a percentage of matching lines.
-> Rebuild the index once with `ctx index --force` after upgrading.
-
-## Change Scoring
-
-Score the quality delta of your working tree (or branch) against a git
-reference. Baselines are parsed in memory at the reference with the same
-parser, so the deltas compare like with like:
-
-```bash
-ctx score                          # Score uncommitted changes (vs HEAD)
-ctx score --against main           # Score the whole branch / PR
-ctx score --fail-on "new_duplication>0,complexity_delta>=25"   # CI gate
-ctx score --against main --json    # Machine-readable JSON envelope
-```
-
-**Metrics** (usable in `--fail-on` as `metric OP value` with `>=`, `<=`, `>`, `<`):
-`complexity_delta`, `fan_out_delta`, `new_duplication`, `check_violations`,
-`symbols_added`, `symbols_removed`, `files_changed`.
-
-The index is refreshed incrementally before scoring; exit codes are 0 (clean),
-1 (a `--fail-on` condition was met), 2 (operational error).
-
-## Dependency Graph
+This scaffolds three hooks and a starter `.ctx/rules.toml`:
 
-Generate dependency graph visualizations:
+- **SessionStart** → `ctx map` primes the agent with a codebase map before it does anything.
+- **PostToolUse** (on Edit/Write) → `ctx index` reindexes, then `ctx check --against HEAD` flags any
+  architecture violation the edit just introduced.
+- **Stop** → `ctx score --fail-on "check_violations>0,new_duplication>0"`: a quality scorecard on
+  the whole change before the agent calls it done.
 
-```bash
-ctx graph                          # DOT format (default)
-ctx graph --output mermaid         # Mermaid diagram
-ctx graph --output json            # JSON format
-ctx graph --by-file                # Group by file/module
-ctx graph --filter "src/auth/*"    # Filter to specific files
-ctx graph --depth 5                # Maximum depth
-```
+The generated permissions let the agent run `ctx *` but **deny** `ctx self-update` and edits to the
+rules, hooks, and settings, so an agent can't weaken the policy that governs it. `ctx harness
+doctor` diagnoses the integration. Details in the
+[Claude integration guide](https://docs.agentis.tools/docs/integrations/claude) and
+[Using ctx with agents](https://docs.agentis.tools/docs/guides/using-ctx-with-agents).
 
-## Interactive Shell
+### MCP server (Claude Desktop)
 
-REPL for codebase exploration:
+ctx can also expose the world model over the Model Context Protocol. MCP is **feature-gated** and not
+in the default/release binaries, so build with the `mcp` feature:
 
 ```bash
-ctx shell                   # Start shell
-ctx shell --vi              # Vi editing mode
-ctx shell --no-history      # Disable history
-ctx shell --history ~/.my_ctx_history  # Custom history file
-```
-
-**Shell Commands:**
-- `find <pattern>` - Find symbols by name
-- `search <query>` - Hybrid search (text + semantic)
-- `source <symbol>` - Show source code
-- `explain <symbol>` - Explain symbol with relationships
-- `callers <fn>` - Show function callers
-- `callees <fn>` - Show function callees
-- `impact <symbol>` - Impact analysis
-- `complexity` - Show high-complexity functions
-- `stats` - Codebase statistics
-- `audit` - Run code quality audit
-- `cd <path>` - Set file path context
-- `pwd` - Show current context
-- `clear` - Clear screen
-- `help` - Show help
-- `exit` - Exit shell
-
-## MCP Server (Claude Desktop)
-
-Expose ctx to AI assistants via Model Context Protocol:
-
-```bash
-# Build with MCP support
-cargo build --release --features mcp
-
-# Run MCP server
+cargo install agentis-ctx --features mcp
 ctx serve --mcp
 ```
 
-Configure Claude Desktop (`claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "ctx": {
-      "command": "ctx",
-      "args": ["serve", "--mcp"],
-      "cwd": "/path/to/project"
-    }
-  }
-}
-```
-
-**Available MCP Tools:**
-- `search_symbols` - Search for symbols by name pattern
-- `get_definition` - Get the source code for a symbol
-- `find_references` - Find all references to a symbol
-- `get_callers` - Get functions that call a given function
-- `get_callees` - Get functions called by a given function
-- `get_file` - Read a file's contents
-- `get_file_tree` - List files in the project
-- `smart_context` - Intelligently select files for a task
-
-## Ignore System
-
-Three-tier ignore system:
-
-1. **`.gitignore`** - Respected by default (disable with `--no-gitignore`)
-2. **`.contextignore`** - Project-specific ignores, same syntax as `.gitignore`
-3. **Built-in patterns** - Common non-source files (disable with `--no-default-ignores`)
-
-### Example `.contextignore`
-```gitignore
-# Exclude test fixtures
-fixtures/
-__mocks__/
-
-# Exclude generated code
-*.generated.ts
-*.pb.go
-
-# Exclude vendored dependencies
-vendor/
-third_party/
-```
-
-### Built-in Ignore Patterns
-The tool automatically ignores:
-- Version control (`.git/`, `.svn/`, `.hg/`)
-- IDE directories (`.vscode/`, `.idea/`)
-- Lock files (`package-lock.json`, `yarn.lock`, `Cargo.lock`)
-- Dependencies (`node_modules/`, `vendor/`, `Pods/`)
-- Build outputs (`dist/`, `build/`, `target/`, `.next/`)
-- Cache directories (`.cache/`, `tmp/`)
-- Binary files and media
+Configure Claude Desktop and see the available tools in the
+[Claude integration guide](https://docs.agentis.tools/docs/integrations/claude).
+
+## Command reference
+
+The full flag reference for every command lives at
+[docs.agentis.tools](https://docs.agentis.tools/). At a glance:
+
+| | Command | Purpose |
+|---|---|---|
+| **Ground** | `index` / `embed` | Build the index; generate embeddings (`--watch` to keep them warm) |
+| | `smart` | Select files for a task by semantic + call-graph relevance |
+| | `map` | Token-budgeted architectural overview |
+| | `diff` / `review` | Context for git changes / a GitHub PR |
+| | `similar` | Find existing functions before writing new ones |
+| | `search` / `semantic` / `query` / `source` / `explain` | Search and navigate the model |
+| **Govern** | `check` | Enforce architecture rules from `.ctx/rules.toml` |
+| | `score` | Composite quality gate for a change vs a git ref |
+| | `duplicates` | MinHash near-duplicate detection |
+| | `hotspots` | Churn × complexity refactoring targets |
+| | `sql` | Read-only SQL over the `v1.*` views (and SQL gates) |
+| **Integrate** | `harness` | Wire ctx into Claude Code (`init` / `doctor` / `compat`) |
+| | `serve --mcp` | MCP server (requires the `mcp` feature) |
+| | `shell` | Interactive REPL for exploring the codebase |
+| | `self-update` | Update to the latest release (checksum-verified) |
 
 ## Supported Languages
 
@@ -691,130 +201,74 @@ The tool automatically ignores:
 | Solidity | `.sol` | Contracts, functions, events, structs | Calls |
 | YAML | `.yaml`, `.yml` | File tracking (no symbols) | N/A |
 
-## Architecture
+See [Language Support](https://docs.agentis.tools/docs/language-support) for detail.
 
-```
-.ctx/
-└── codebase.sqlite    # SQLite database with FTS5 search and embeddings
-```
+## Using ctx as a library
 
-- **SQLite** - Persistent storage for symbols, edges, embeddings, and compressed source
-- **DuckDB** - In-memory analytical engine for recursive graph queries
-- **Tree-sitter** - Fast, accurate parsing for all supported languages
-- **fastembed** - Local embedding generation (all-MiniLM-L6-v2, 384 dimensions)
-- **OpenAI** - Optional embedding generation (text-embedding-3-small, 1536 dimensions)
-- **sqlite-vec** - Fast vector similarity search
+Everything the CLI does is available as a Rust library, so you can embed indexing, search, and
+context generation in your own tools. The package is `agentis-ctx`; the library target is named
+`ctx`:
 
-## CLI Reference
+```toml
+[dependencies]
+agentis-ctx = "0.3"
 
+# On Windows (or to skip DuckDB analytics):
+# agentis-ctx = { version = "0.3", default-features = false }
 ```
-ctx - Generate AI-ready context from your codebase
-
-USAGE:
-    ctx [OPTIONS] [PATTERNS]...
-    ctx <COMMAND>
-
-COMMANDS:
-    index       Build or update the code intelligence index
-    query       Query the code intelligence database
-    sql         Run read-only SQL against the index (v1 schema)
-    search      Search for symbols using keyword matching
-    semantic    Search using embeddings (natural language)
-    embed       Generate embeddings for semantic search
-    source      Get the source code for a symbol
-    explain     Explain a symbol with its relationships
-    smart       Intelligently select files for a task
-    diff        Generate context for changed files
-    review      Generate context for PR review (GitHub)
-    audit       Run code quality analysis
-    check       Check architecture rules from .ctx/rules.toml
-    score       Score the quality delta of changes vs a git reference
-    complexity  Analyze code complexity
-    duplicates  Detect structurally similar functions (MinHash)
-    graph       Generate dependency graph
-    shell       Interactive codebase explorer
-    serve       Start MCP server (with --mcp flag, requires mcp feature)
-
-CONTEXT OPTIONS:
-    -f, --format <FORMAT>    Output format [default: xml] [values: xml, markdown, md, plain, json]
-        --no-gitignore       Disable .gitignore pattern matching
-    -i, --ignore <PATTERN>   Additional ignore patterns
-        --no-default-ignores Disable built-in ignore patterns
-        --show-sizes         Show file sizes in project tree
-        --no-tree            Disable project tree in output
-        --no-stream          Buffer output instead of streaming
-        --stats              Print stats after completion
-        --count-only         Only count tokens, don't output
-        --max-tokens <N>     Limit output to N tokens
-        --encoding <ENC>     Tokenizer encoding [default: cl100k_base]
-
-INDEX OPTIONS:
-    -w, --watch              Watch for changes and reindex automatically
-    -v, --verbose            Show verbose output
-        --force              Force full reindex (clears existing database)
-    -j, --parallel           Use parallel parsing (faster on multi-core)
-        --no-gitignore       Disable .gitignore pattern matching
-        --no-default-ignores Disable built-in ignore patterns
-    -i, --ignore <PATTERN>   Additional ignore patterns
-    -p, --pattern <PATTERN>  File patterns to include
-```
 
-## Performance
+```rust
+use ctx::prelude::*;
+use std::path::Path;
+
+fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    let root = Path::new("./my-project");
 
-- Indexes ~2000 files in under 10 seconds
-- Parallel indexing with `--parallel` flag (~1.7x speedup)
-- Incremental updates only reindex changed files
-- Fast vector search with sqlite-vec
-- Compressed source storage (~70% size reduction)
-- In-memory DuckDB for fast analytical queries
-- Local embeddings with fastembed (~90MB model, runs offline)
+    // Build (or incrementally update) the index at .ctx/codebase.sqlite
+    let mut indexer = Indexer::with_config(root, false, WalkerConfig::default())?;
+    let result = indexer.index()?;
+    println!("{} symbols extracted", result.symbols_extracted);
 
-## Environment Variables
+    // Keyword search over the indexed symbols
+    let db = open_database(root)?;
+    for symbol in db.find_symbols("authenticate", 10)? {
+        println!("{} ({}:{})", symbol.name, symbol.file_path, symbol.line_start);
+    }
+    Ok(())
+}
+```
 
-| Variable | Description |
-|----------|-------------|
-| `OPENAI_API_KEY` | Required for `--openai` flag with `embed` and `semantic` commands |
-| `GITHUB_TOKEN` | Optional for `review` command (uses `gh` CLI auth by default) |
+The [API documentation](https://docs.rs/agentis-ctx) covers the full surface: smart context
+selection, diff-aware context, semantic search (local or OpenAI embeddings), call-graph analytics,
+token counting, and output formatting.
 
-## Examples
+## How it works
 
-### Generate context for a bug fix
-```bash
-# Find relevant code and generate context
-ctx smart "fix authentication timeout bug" --max-tokens 10000 | pbcopy
 ```
-
-### Review a pull request
-```bash
-# Get context for PR review
-ctx review 42 --summary --include-comments
+.ctx/
+├── codebase.sqlite    # symbols, edges, embeddings, compressed source (FTS5 + sqlite-vec)
+└── rules.toml         # your architecture rules (created by `ctx harness init`)
 ```
 
-### Pre-commit quality check
-```bash
-# Add to .git/hooks/pre-commit
-ctx audit --min-score 7.0 --incremental || exit 1
-```
+- **Tree-sitter** parses every supported language into symbols and relationship edges.
+- **SQLite** (with FTS5 and `sqlite-vec`) is the persistent, single-file store.
+- **DuckDB** runs the recursive graph and analytical queries (default-on; not available on Windows).
+- **fastembed** generates local embeddings offline (all-MiniLM-L6-v2, 384-dim); OpenAI is optional.
 
-### CI/CD integration
-```bash
-# In your CI pipeline
-ctx audit --output json > quality-report.json
-ctx audit --min-score 8.0 || exit 1
-```
+Indexing respects `.gitignore`, an optional `.contextignore`, and 170+ built-in patterns. See
+[Configuration](https://docs.agentis.tools/docs/configuration) and
+[Architecture](https://docs.agentis.tools/docs/architecture).
 
-### Explore codebase interactively
-```bash
-ctx shell
-ctx> find handleAuth
-ctx> callers handleAuth
-ctx> impact handleAuth
-ctx> source handleAuth
-```
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | Required for the `--openai` flag on `embed` / `semantic` / `smart` / `similar` |
+| `GITHUB_TOKEN` | Optional for `review` (uses `gh` CLI auth by default) |
+| `CTX_NO_UPDATE_CHECK` | Silence the passive "new release available" notice |
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on development setup, coding style, and the pull request process.
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on development
+setup, coding style, and the pull request process.
 
 ## Security