cairn-intel 0.6.1__tar.gz

cairn_intel-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Tan Le
+
+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.

cairn_intel-0.6.1/NOTICE

@@ -0,0 +1,82 @@
+cairn
+Copyright (c) 2025–2026 Tan Le
+
+Licensed under the MIT License; see LICENSE for full text.
+
+This NOTICE file documents the third-party open-source software used by cairn.
+cairn depends on these packages at runtime (resolved via pip/uv from PyPI) and
+does not redistribute their source. Each package retains its own license; the
+summaries below are for convenience and are not legal substitutes for the
+upstream license texts.
+
+================================================================================
+Dependencies (by license family)
+================================================================================
+
+This product depends on software distributed under the following licenses. Each
+entry lists the package and its declared license.
+
+----------------------------------------
+MIT License
+----------------------------------------
+  annotated-types, anyio, attrs, build, h11, httpx-sse, iniconfig, jsonschema,
+  jsonschema-specifications, markdown-it-py, mcp, mdurl, pluggy, pydantic,
+  pydantic-settings, pydantic_core, PyJWT, pyproject_hooks, pytest,
+  referencing, rich, rpds-py, ruff, PyYAML, tree-sitter, tree-sitter-dart,
+  tree-sitter-go, tree-sitter-java, tree-sitter-javascript, tree-sitter-kotlin,
+  tree-sitter-objc, tree-sitter-python, tree-sitter-swift, tree-sitter-typescript,
+  typing-inspection, cffi (MIT-0)
+
+----------------------------------------
+BSD License (BSD-2-Clause / BSD-3-Clause)
+----------------------------------------
+  click (BSD-3-Clause), httpcore (BSD-3-Clause), httpx (BSD-3-Clause),
+  idna (BSD-3-Clause), pycparser (BSD-3-Clause), Pygments (BSD-2-Clause),
+  python-dotenv (BSD-3-Clause), sse-starlette (BSD-3-Clause),
+  starlette (BSD-3-Clause), uvicorn (BSD-3-Clause)
+
+----------------------------------------
+Apache License 2.0
+----------------------------------------
+  python-multipart (Apache-2.0), watchdog (Apache-2.0)
+
+----------------------------------------
+Dual: Apache License 2.0 OR BSD
+----------------------------------------
+  cryptography (Apache-2.0 OR BSD-3-Clause)
+  packaging (Apache-2.0 OR BSD-2-Clause)
+
+----------------------------------------
+Mozilla Public License 2.0 (MPL-2.0)
+----------------------------------------
+  certifi, pathspec
+  Note: MPL-2.0 is file-level weak copyleft. It is satisfied by keeping the
+  MPL-licensed files' source and notice available (they remain in the upstream
+  PyPI packages). cairn does not copy or vendor these files into its source
+  tree, so no additional obligation attaches to distributing cairn itself.
+
+----------------------------------------
+Python Software Foundation License (PSF-2.0)
+----------------------------------------
+  typing_extensions
+
+----------------------------------------
+Dual: MIT License OR Apache License 2.0
+----------------------------------------
+  sqlite-vec
+
+================================================================================
+Optional extras
+================================================================================
+
+The `[semantic]` extra (sentence-transformers, numpy) is not installed by
+default. On Linux it additionally pulls torch and its transitive NVIDIA CUDA
+runtime packages (e.g. nvidia-cublas, nvidia-cudnn, nvidia-cufft, triton),
+which are governed by NVIDIA's CUDA EULA / Apache-2.0 and torch's BSD-style
+license. These are resolved and accepted by the end user; cairn does not
+bundle or redistribute them.
+
+The embedding model `BAAI/bge-m3` (referenced by name, downloaded on demand
+to ~/.cairn/lib/ when a user runs `cg embed --install-deps`) is released
+under the MIT License on Hugging Face. cairn does not redistribute the
+model weights.

cairn_intel-0.6.1/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: cairn-intel
+Version: 0.6.1
+Summary: Local codebase intelligence system: structural graph + compass + wiki + agent memory
+Author: Tan Le
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tanlnm512/cairn
+Keywords: code-intelligence,tree-sitter,mcp,knowledge-graph,code-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: tree-sitter==0.26.0
+Requires-Dist: tree-sitter-kotlin==1.1.0
+Requires-Dist: tree-sitter-java==0.23.5
+Requires-Dist: tree-sitter-python==0.23.6
+Requires-Dist: tree-sitter-swift==0.7.3
+Requires-Dist: tree-sitter-typescript==0.23.2
+Requires-Dist: tree-sitter-javascript==0.23.0
+Requires-Dist: tree-sitter-dart==0.1.0
+Requires-Dist: tree-sitter-objc==3.0.2
+Requires-Dist: tree-sitter-go==0.25.0
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: mcp<2.0.0,>=0.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pathspec>=0.12
+Requires-Dist: packaging>=21.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: questionary>=2.0
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == "watch"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: watchdog>=3.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: grpcio-tools>=1.60; extra == "dev"
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=3.0; extra == "semantic"
+Requires-Dist: numpy>=1.24; extra == "semantic"
+Provides-Extra: ann
+Requires-Dist: sqlite-vec>=0.1.0; extra == "ann"
+Provides-Extra: scip
+Requires-Dist: protobuf>=7.35.1; extra == "scip"
+Dynamic: license-file
+
+# cairn
+
+> Local codebase intelligence system: structural graph + compass + wiki + agent memory.
+
+[![PyPI version](https://img.shields.io/pypi/v/cairn-intel.svg)](https://pypi.org/project/cairn-intel/)
+[![License: MIT](https://img.shields.io/pypi/l/cairn-intel.svg)](LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/cairn-intel.svg)](https://pypi.org/project/cairn-intel/)
+[![CI](https://img.shields.io/github/actions/workflow/status/tanlnm512/cairn/ci.yml?branch=main&label=CI)](https://github.com/tanlnm512/cairn/actions/workflows/ci.yml)
+
+cairn builds a precise, language-aware structural graph of your codebase and
+exposes it to both humans (the `cairn` CLI) and AI agents (a stdio MCP server with
+27 tools). Symbols, call edges, definitions, blast radius, and tribal memory all
+live in a local SQLite store — no network call, no torch in the default install.
+
+## What is cairn?
+
+cairn is a **local** codebase intelligence system. It parses your repos with
+tree-sitter into a **structural graph** (definitions, call edges, cross-repo
+dependencies) stored in SQLite, then layers a **compass** (per-module navigation
+guides), a **wiki** (architecture docs), **memory** (decisions / patterns /
+mistakes / workarounds), and a **knowledge** store on top. It is **MCP-native**:
+the same store backs the `cairn` CLI and a 27-tool MCP server, making it
+**agent-first** — your coding agents query one local source of truth instead of
+re-reading the whole repo every turn.
+
+## Why cairn? Resolution-labeled edges
+
+Every code graph can tell you "who calls this." cairn is the one that tells
+you **whether to trust the answer.** The resolver labels each call edge:
+
+- **`exact`** — pinned to one definition. Trusted.
+- **`ambiguous`** — multiple candidates; the resolver declined to guess.
+- **`unresolved`** — external or stdlib.
+
+Graph tools default to **precise mode** — they follow *only* `exact` edges. So
+blast radius is **never inflated by name collisions**. A common name like
+`invoke` can have hundreds of call sites across a polyglot repo that merely
+share the name; precise mode returns only the real callers, while **fuzzy mode**
+(`--fuzzy` / `fuzzy=True`) adds the name-only matches as an explicitly-labelled
+candidate list to verify.
+
+```bash
+cairn impact invoke              # precise (default): real callers only — ground truth
+cairn impact invoke --fuzzy      # candidate list (name matches), each labelled unverified
+```
+
+An empty precise result means "no *resolvable* callers," **not** "unused" —
+retry with `--fuzzy` before concluding a symbol is dead. And `explore` surfaces
+`ambiguous` dispatch hops — polymorphism that grep fundamentally cannot see.
+
+This is measurable: see [docs/benchmarks.md](docs/benchmarks.md#the-resolution-label-methodology-cairns-differentiator)
+for the precise-vs-fuzzy false-positive methodology, and
+[docs/examples/resolution-walkthrough.md](docs/examples/resolution-walkthrough.md)
+for a worked example. Full design at
+[docs/architecture.md § Resolution model](docs/architecture.md#resolution-model).
+
+## Quick start
+
+```bash
+pip install cairn-intel              # install from PyPI (the recommended path)
+cairn build                         # parse the workspace and build the graph (first run)
+cairn update                        # incremental reindex after the first build
+cairn def SomeSymbol                # find where a symbol is defined
+cairn ask "how does auth work"      # natural-language query across all layers
+```
+
+The graph lives under `~/.cairn` by default (override with `CAIRN_HOME`).
+
+> **First run vs later runs.** `cairn build` parses every file from scratch.
+> `cairn update` reindexes only what changed since the last build (via `git diff
+> HEAD` plus the existing graph) — so on a fresh clone with a clean working tree,
+> use `cairn build` first, since `cairn update` would see no changes.
+
+## Upgrading
+
+cairn can update itself in place — it detects how it was installed
+(`uv tool`, `pipx`, or `pip`) and re-installs the latest version from PyPI:
+
+```bash
+cairn upgrade          # update to the latest published version
+cairn upgrade --check  # only check what's latest, don't change anything
+cairn version          # print the installed version
+```
+
+If PyPI is unreachable, `cairn upgrade` prints the manual command instead.
+
+## Install for AI agents
+
+cairn ships a stdio MCP server (`cairn serve`). To wire it into your AI coding
+clients (Claude Code, Cursor, Droid, ZCode, Claude Desktop, agy, opencode):
+
+```bash
+cairn install-agents
+```
+
+This detects which clients are installed, shows whether cairn is already
+wired in, and interactively prompts you to choose:
+
+```
+Client detection:
+  [✓] claude           claude CLI on PATH              cairn: [ ] not installed
+  [✓] cursor           Cursor.app in /Applications     cairn: [ ] not installed
+  [✓] zcode            ~/.zcode exists                 cairn: [✓] installed
+
+Install cairn for which clients?
+Clients [claude,cursor]:
+
+Config scope:
+  workspace  — write to ./.claude/, ./.cursor/ etc. (per-project)
+  global     — write to ~/.claude/, ~/.cursor/ etc. (all projects inherit)
+Scope [workspace]:
+```
+
+**Scope:** `workspace` (default) writes configs to the current project dir
+(`./.claude/`, `./.cursor/`); `global` writes to your home dir (`~/.claude/`,
+`~/.cursor/`) so all projects inherit cairn without per-project setup.
+
+Non-interactive flags for scripts/CI:
+
+```bash
+cairn install-agents --yes                          # auto-install detected-not-installed
+cairn install-agents --client claude --client cursor  # force specific clients
+cairn install-agents --scope global                 # write to ~/.claude/ etc.
+cairn install-agents --force                        # overwrite existing files
+cairn install-agents --dry-run                      # preview without writing
+```
+
+Or wire manually — the MCP config is:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+The recommended first call from an agent is `explore(query)`, which returns
+matching symbols' verbatim source, the call paths between them, and a
+blast-radius summary in a single round trip.
+
+## Supported languages
+
+Kotlin, Java, Python, Swift, TypeScript, JavaScript, Dart, Objective-C, Go
+
+## Optional features
+
+The default install is dependency-light and network-free. Opt in with extras:
+
+| Extra | Adds | Key env var |
+|-------|------|-------------|
+| `[semantic]` | `sentence-transformers` + `numpy` — real embeddings and CrossEncoder reranking | `CAIRN_RERANK=1`; fusion is governed by `CAIRN_FUSION` (default on) |
+| `[ann]` | `sqlite-vec` — native approximate-nearest-neighbour index for large corpora | `CAIRN_ANN_BACKEND=sqlite-vec` |
+| `[scip]` | `protobuf` — consume pre-built [SCIP](docs/scip.md) indexes for compiler-grade exact call edges (Kotlin/Java/Swift/TypeScript) alongside tree-sitter | declare indexes in `cairn.json` under `scip` |
+| `[watch]` | `watchdog` — live graph rebuilds on filesystem change | — |
+
+## Architecture (5 layers)
+
+The MCP server exposes 27 tools across five layers:
+
+| Layer | Purpose |
+|-------|---------|
+| **graph** (9 tools) | Structural graph: `find_definition`, `get_callers` / `get_callees`, `impact_analysis`, `cross_repo_deps`, `semantic_search`, `search_symbols`, `explore` (the graph aggregator and recommended first call), and `visualize_graph` |
+| **compass + knowledge base** (5 tools) | `get_compass`, `search_knowledge`, `ask_compass` (cross-layer router), `trace_flow`, `generate_flow` |
+| **memory** (8 tools) | Tribal memory: recall / record / lifecycle (promote, demote, evolve, decay, delete, digest) |
+| **knowledge** (5 tools) | The OKF knowledge store — add / search / status business docs and workflows |
+
+## CLI
+
+The `cairn` command groups the main functionality. Run `cairn --help`
+(or `cairn <group> --help`) for the authoritative, full list.
+
+| Command | What it does |
+|---------|--------------|
+| `cairn serve` | Run the stdio MCP server |
+| `cairn build` | Parse the workspace and build the graph (full; first run) |
+| `cairn update` | Incremental reindex of changed files (after the first build) |
+| `cairn def <symbol>` | Find a symbol's definition |
+| `cairn impact <symbol>` | Within-repo blast radius (precise by default; `--fuzzy` to audit) |
+| `cairn ask "<question>"` | Natural-language query routed across all layers |
+| `cairn context <file>` | Load compass + memory + wiki context for a file |
+| `cairn memory …` | Record / list / search tribal memory |
+| `cairn task …` | Optional LLM task queue (`list` / `show` / `claim` / `complete`) |
+| `cairn knowledge …` | Inspect and export the knowledge store |
+| `cairn compass …` | Generate / list / validate module compass guides |
+| `cairn wiki …` | Generate / search the architecture wiki |
+| `cairn install-agents` | Drop integration files into supported AI agents |
+| `cairn upgrade` | Update cairn in place from PyPI (detects install method; `--check` to preview) |
+| `cairn bench` | Performance / scalability benchmarks (`--save`/`--compare` for regression checks) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # pytest + watchdog + build
+pytest -m core            # fast <3s smoke subset (one test per core function)
+```
+
+## Semantic search
+
+The default install is network- and torch-free. Semantic search deps
+(torch + sentence-transformers) are a one-time separate download that
+persists in `~/.cairn/lib/` (survives reinstalls):
+
+```bash
+cairn embed --install-deps    # one-time: downloads bge-m3 (~836 MB)
+cairn embed                   # builds the embedding index
+```
+
+## Development
+
+cairn is developed on GitHub and released to PyPI. The recommended install
+for end users is `pip install cairn-intel` (see Quick start above). The
+following is for contributors only:
+
+```bash
+pip install -e ".[dev]"   # editable install: pytest + watchdog + build + ruff
+pytest -m core            # fast <3s smoke subset (one test per core function)
+pytest                    # full suite (the CI path)
+make dist                 # build wheel + sdist into dist/ (for releases)
+```
+
+Releases are cut by tagging `vX.Y.Z` — see the tag-triggered workflow in
+`.github/workflows/release.yml` and the pre-release checklist in
+`docs/release-checklist.md`.
+
+## Dependency licenses
+
+cairn is MIT-licensed. Its dependencies are all permissive (MIT, BSD,
+Apache-2.0, MPL-2.0, PSF); see [NOTICE](NOTICE) for the full list.
+
+The optional `[semantic]` extra is not installed by default. If you opt into it
+on Linux, `pip` resolves `torch` and its transitive NVIDIA CUDA runtime
+packages, which carry their own licenses (torch: BSD; NVIDIA CUDA components:
+NVIDIA EULA / Apache-2.0). The embedding model `BAAI/bge-m3` (MIT) is
+downloaded on demand to `~/.cairn/lib/` and is not redistributed with cairn.
+None of these are bundled with cairn — they are resolved and accepted by the
+end user at install time.
+
+## Status
+
+**Beta — pre-1.0 (v0.6.1).** Public surfaces (CLI flags, MCP tool shapes,
+knowledge-file layout) may still shift before 1.0. Feedback welcome via
+[GitHub issues](https://github.com/tanlnm512/cairn/issues).
+
+## License
+
+[MIT](LICENSE) — © 2025–2026 Tan Le

cairn_intel-0.6.1/README.md

@@ -0,0 +1,250 @@
+# cairn
+
+> Local codebase intelligence system: structural graph + compass + wiki + agent memory.
+
+[![PyPI version](https://img.shields.io/pypi/v/cairn-intel.svg)](https://pypi.org/project/cairn-intel/)
+[![License: MIT](https://img.shields.io/pypi/l/cairn-intel.svg)](LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/cairn-intel.svg)](https://pypi.org/project/cairn-intel/)
+[![CI](https://img.shields.io/github/actions/workflow/status/tanlnm512/cairn/ci.yml?branch=main&label=CI)](https://github.com/tanlnm512/cairn/actions/workflows/ci.yml)
+
+cairn builds a precise, language-aware structural graph of your codebase and
+exposes it to both humans (the `cairn` CLI) and AI agents (a stdio MCP server with
+27 tools). Symbols, call edges, definitions, blast radius, and tribal memory all
+live in a local SQLite store — no network call, no torch in the default install.
+
+## What is cairn?
+
+cairn is a **local** codebase intelligence system. It parses your repos with
+tree-sitter into a **structural graph** (definitions, call edges, cross-repo
+dependencies) stored in SQLite, then layers a **compass** (per-module navigation
+guides), a **wiki** (architecture docs), **memory** (decisions / patterns /
+mistakes / workarounds), and a **knowledge** store on top. It is **MCP-native**:
+the same store backs the `cairn` CLI and a 27-tool MCP server, making it
+**agent-first** — your coding agents query one local source of truth instead of
+re-reading the whole repo every turn.
+
+## Why cairn? Resolution-labeled edges
+
+Every code graph can tell you "who calls this." cairn is the one that tells
+you **whether to trust the answer.** The resolver labels each call edge:
+
+- **`exact`** — pinned to one definition. Trusted.
+- **`ambiguous`** — multiple candidates; the resolver declined to guess.
+- **`unresolved`** — external or stdlib.
+
+Graph tools default to **precise mode** — they follow *only* `exact` edges. So
+blast radius is **never inflated by name collisions**. A common name like
+`invoke` can have hundreds of call sites across a polyglot repo that merely
+share the name; precise mode returns only the real callers, while **fuzzy mode**
+(`--fuzzy` / `fuzzy=True`) adds the name-only matches as an explicitly-labelled
+candidate list to verify.
+
+```bash
+cairn impact invoke              # precise (default): real callers only — ground truth
+cairn impact invoke --fuzzy      # candidate list (name matches), each labelled unverified
+```
+
+An empty precise result means "no *resolvable* callers," **not** "unused" —
+retry with `--fuzzy` before concluding a symbol is dead. And `explore` surfaces
+`ambiguous` dispatch hops — polymorphism that grep fundamentally cannot see.
+
+This is measurable: see [docs/benchmarks.md](docs/benchmarks.md#the-resolution-label-methodology-cairns-differentiator)
+for the precise-vs-fuzzy false-positive methodology, and
+[docs/examples/resolution-walkthrough.md](docs/examples/resolution-walkthrough.md)
+for a worked example. Full design at
+[docs/architecture.md § Resolution model](docs/architecture.md#resolution-model).
+
+## Quick start
+
+```bash
+pip install cairn-intel              # install from PyPI (the recommended path)
+cairn build                         # parse the workspace and build the graph (first run)
+cairn update                        # incremental reindex after the first build
+cairn def SomeSymbol                # find where a symbol is defined
+cairn ask "how does auth work"      # natural-language query across all layers
+```
+
+The graph lives under `~/.cairn` by default (override with `CAIRN_HOME`).
+
+> **First run vs later runs.** `cairn build` parses every file from scratch.
+> `cairn update` reindexes only what changed since the last build (via `git diff
+> HEAD` plus the existing graph) — so on a fresh clone with a clean working tree,
+> use `cairn build` first, since `cairn update` would see no changes.
+
+## Upgrading
+
+cairn can update itself in place — it detects how it was installed
+(`uv tool`, `pipx`, or `pip`) and re-installs the latest version from PyPI:
+
+```bash
+cairn upgrade          # update to the latest published version
+cairn upgrade --check  # only check what's latest, don't change anything
+cairn version          # print the installed version
+```
+
+If PyPI is unreachable, `cairn upgrade` prints the manual command instead.
+
+## Install for AI agents
+
+cairn ships a stdio MCP server (`cairn serve`). To wire it into your AI coding
+clients (Claude Code, Cursor, Droid, ZCode, Claude Desktop, agy, opencode):
+
+```bash
+cairn install-agents
+```
+
+This detects which clients are installed, shows whether cairn is already
+wired in, and interactively prompts you to choose:
+
+```
+Client detection:
+  [✓] claude           claude CLI on PATH              cairn: [ ] not installed
+  [✓] cursor           Cursor.app in /Applications     cairn: [ ] not installed
+  [✓] zcode            ~/.zcode exists                 cairn: [✓] installed
+
+Install cairn for which clients?
+Clients [claude,cursor]:
+
+Config scope:
+  workspace  — write to ./.claude/, ./.cursor/ etc. (per-project)
+  global     — write to ~/.claude/, ~/.cursor/ etc. (all projects inherit)
+Scope [workspace]:
+```
+
+**Scope:** `workspace` (default) writes configs to the current project dir
+(`./.claude/`, `./.cursor/`); `global` writes to your home dir (`~/.claude/`,
+`~/.cursor/`) so all projects inherit cairn without per-project setup.
+
+Non-interactive flags for scripts/CI:
+
+```bash
+cairn install-agents --yes                          # auto-install detected-not-installed
+cairn install-agents --client claude --client cursor  # force specific clients
+cairn install-agents --scope global                 # write to ~/.claude/ etc.
+cairn install-agents --force                        # overwrite existing files
+cairn install-agents --dry-run                      # preview without writing
+```
+
+Or wire manually — the MCP config is:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+The recommended first call from an agent is `explore(query)`, which returns
+matching symbols' verbatim source, the call paths between them, and a
+blast-radius summary in a single round trip.
+
+## Supported languages
+
+Kotlin, Java, Python, Swift, TypeScript, JavaScript, Dart, Objective-C, Go
+
+## Optional features
+
+The default install is dependency-light and network-free. Opt in with extras:
+
+| Extra | Adds | Key env var |
+|-------|------|-------------|
+| `[semantic]` | `sentence-transformers` + `numpy` — real embeddings and CrossEncoder reranking | `CAIRN_RERANK=1`; fusion is governed by `CAIRN_FUSION` (default on) |
+| `[ann]` | `sqlite-vec` — native approximate-nearest-neighbour index for large corpora | `CAIRN_ANN_BACKEND=sqlite-vec` |
+| `[scip]` | `protobuf` — consume pre-built [SCIP](docs/scip.md) indexes for compiler-grade exact call edges (Kotlin/Java/Swift/TypeScript) alongside tree-sitter | declare indexes in `cairn.json` under `scip` |
+| `[watch]` | `watchdog` — live graph rebuilds on filesystem change | — |
+
+## Architecture (5 layers)
+
+The MCP server exposes 27 tools across five layers:
+
+| Layer | Purpose |
+|-------|---------|
+| **graph** (9 tools) | Structural graph: `find_definition`, `get_callers` / `get_callees`, `impact_analysis`, `cross_repo_deps`, `semantic_search`, `search_symbols`, `explore` (the graph aggregator and recommended first call), and `visualize_graph` |
+| **compass + knowledge base** (5 tools) | `get_compass`, `search_knowledge`, `ask_compass` (cross-layer router), `trace_flow`, `generate_flow` |
+| **memory** (8 tools) | Tribal memory: recall / record / lifecycle (promote, demote, evolve, decay, delete, digest) |
+| **knowledge** (5 tools) | The OKF knowledge store — add / search / status business docs and workflows |
+
+## CLI
+
+The `cairn` command groups the main functionality. Run `cairn --help`
+(or `cairn <group> --help`) for the authoritative, full list.
+
+| Command | What it does |
+|---------|--------------|
+| `cairn serve` | Run the stdio MCP server |
+| `cairn build` | Parse the workspace and build the graph (full; first run) |
+| `cairn update` | Incremental reindex of changed files (after the first build) |
+| `cairn def <symbol>` | Find a symbol's definition |
+| `cairn impact <symbol>` | Within-repo blast radius (precise by default; `--fuzzy` to audit) |
+| `cairn ask "<question>"` | Natural-language query routed across all layers |
+| `cairn context <file>` | Load compass + memory + wiki context for a file |
+| `cairn memory …` | Record / list / search tribal memory |
+| `cairn task …` | Optional LLM task queue (`list` / `show` / `claim` / `complete`) |
+| `cairn knowledge …` | Inspect and export the knowledge store |
+| `cairn compass …` | Generate / list / validate module compass guides |
+| `cairn wiki …` | Generate / search the architecture wiki |
+| `cairn install-agents` | Drop integration files into supported AI agents |
+| `cairn upgrade` | Update cairn in place from PyPI (detects install method; `--check` to preview) |
+| `cairn bench` | Performance / scalability benchmarks (`--save`/`--compare` for regression checks) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # pytest + watchdog + build
+pytest -m core            # fast <3s smoke subset (one test per core function)
+```
+
+## Semantic search
+
+The default install is network- and torch-free. Semantic search deps
+(torch + sentence-transformers) are a one-time separate download that
+persists in `~/.cairn/lib/` (survives reinstalls):
+
+```bash
+cairn embed --install-deps    # one-time: downloads bge-m3 (~836 MB)
+cairn embed                   # builds the embedding index
+```
+
+## Development
+
+cairn is developed on GitHub and released to PyPI. The recommended install
+for end users is `pip install cairn-intel` (see Quick start above). The
+following is for contributors only:
+
+```bash
+pip install -e ".[dev]"   # editable install: pytest + watchdog + build + ruff
+pytest -m core            # fast <3s smoke subset (one test per core function)
+pytest                    # full suite (the CI path)
+make dist                 # build wheel + sdist into dist/ (for releases)
+```
+
+Releases are cut by tagging `vX.Y.Z` — see the tag-triggered workflow in
+`.github/workflows/release.yml` and the pre-release checklist in
+`docs/release-checklist.md`.
+
+## Dependency licenses
+
+cairn is MIT-licensed. Its dependencies are all permissive (MIT, BSD,
+Apache-2.0, MPL-2.0, PSF); see [NOTICE](NOTICE) for the full list.
+
+The optional `[semantic]` extra is not installed by default. If you opt into it
+on Linux, `pip` resolves `torch` and its transitive NVIDIA CUDA runtime
+packages, which carry their own licenses (torch: BSD; NVIDIA CUDA components:
+NVIDIA EULA / Apache-2.0). The embedding model `BAAI/bge-m3` (MIT) is
+downloaded on demand to `~/.cairn/lib/` and is not redistributed with cairn.
+None of these are bundled with cairn — they are resolved and accepted by the
+end user at install time.
+
+## Status
+
+**Beta — pre-1.0 (v0.6.1).** Public surfaces (CLI flags, MCP tool shapes,
+knowledge-file layout) may still shift before 1.0. Feedback welcome via
+[GitHub issues](https://github.com/tanlnm512/cairn/issues).
+
+## License
+
+[MIT](LICENSE) — © 2025–2026 Tan Le