seam-code 0.3.0__py3-none-any.whl

seam/watcher/__main__.py

@@ -0,0 +1,56 @@
+"""Watcher subprocess entry point.
+
+Launched by `seam start` as:  python -m seam.watcher <db_path> <root_path>
+
+Passing paths as argv (not interpolated into a `python -c` string) avoids
+breakage on paths containing spaces, quotes, or backslashes. Logs go to
+<db_path.parent>/watcher.log so failures are visible (the parent redirects
+this process's stdio to DEVNULL).
+"""
+
+import logging
+import signal
+import sys
+import time
+from pathlib import Path
+
+import seam.config as config
+from seam.watcher.daemon import SeamWatcher
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print("usage: python -m seam.watcher <db_path> <root_path>", file=sys.stderr)
+        return 2
+
+    db_path = Path(argv[0])
+    root_path = Path(argv[1])
+
+    logging.basicConfig(
+        level=getattr(logging, config.SEAM_LOG_LEVEL, logging.INFO),
+        filename=str(db_path.parent / "watcher.log"),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+
+    watcher = SeamWatcher(db_path=db_path, root_path=root_path)
+    watcher.start()
+
+    # Stop cleanly on signals so the PID file and observer are torn down.
+    def _stop(signum: int, frame: object) -> None:  # noqa: ARG001
+        watcher.stop()
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, _stop)
+    signal.signal(signal.SIGINT, _stop)
+
+    # Block forever; events are handled on the observer's threads.
+    try:
+        while True:
+            time.sleep(3600)
+    finally:
+        watcher.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

seam/watcher/daemon.py

@@ -0,0 +1,237 @@
+"""File watcher daemon — watchdog-based auto-sync for the Seam index.
+
+SeamWatcher extends watchdog's FileSystemEventHandler.
+
+Debounce strategy:
+  - Each source file that fires an event gets its own threading.Timer.
+  - If the same file fires again before the timer expires the old timer is
+    cancelled and a new one is started. This prevents hammering the indexer
+    on rapid editor saves (which often write the file several times per save).
+  - Debounce delay is read from config.SEAM_DEBOUNCE_MS (default 500 ms).
+
+DB lifetime:
+  - One SQLite connection is opened at start() and closed at stop().
+  - All debounce callbacks run on the watchdog Observer thread pool, so the
+    connection is shared across callbacks. SQLite handles this safely because
+    watchdog's per-directory threads serialise event delivery.
+
+PID file:
+  - start() writes os.getpid() to <db_path.parent>/watcher.pid
+  - stop() removes it; seam status reads it to show watcher state.
+"""
+
+import logging
+import os
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Any
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+import seam.config as config
+from seam.indexer.db import connect, delete_file
+from seam.indexer.pipeline import index_one_file
+
+logger = logging.getLogger(__name__)
+
+
+class SeamWatcher(FileSystemEventHandler):
+    """Watchdog event handler with per-file debounced re-indexing.
+
+    Usage:
+        watcher = SeamWatcher(db_path=..., root_path=...)
+        watcher.start()
+        # ... file system events are handled automatically ...
+        watcher.stop()
+    """
+
+    def __init__(self, db_path: Path, root_path: Path) -> None:
+        super().__init__()
+
+        self._db_path = db_path
+        # Resolve the root so watchdog event paths (watched-root + relative)
+        # match the resolved-absolute paths that `seam init` stores. Without
+        # this, macOS /var vs /private/var divergence produces duplicate
+        # `files` rows and orphaned symbols on the watcher path.
+        self._root_path = root_path.resolve()
+
+        # DB connection — opened by start(), closed by stop()
+        self._conn: sqlite3.Connection | None = None
+
+        # Watchdog observer — created at start(), joined at stop()
+        # Typed as Any because watchdog's Observer is a module-level variable
+        # resolved at runtime (not a stable class in stub), causing mypy error.
+        self._observer: Any = None
+
+        # Per-file debounce timers. key = str(absolute path), value = active Timer.
+        self._timers: dict[str, threading.Timer] = {}
+
+        # Lock to serialise access to _timers dict (safety for multi-threaded watchdog)
+        self._timer_lock = threading.Lock()
+
+        # Debounce delay in seconds (config is in ms)
+        self._debounce_s: float = config.SEAM_DEBOUNCE_MS / 1000.0
+
+        # PID file path sits next to the DB
+        self._pid_file: Path = db_path.parent / "watcher.pid"
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        """Start the watchdog Observer in a background thread.
+
+        Opens the DB connection, writes the PID file, schedules the observer
+        to watch root_path recursively, then starts the observer thread.
+        """
+        logger.info("SeamWatcher starting — root=%s db=%s", self._root_path, self._db_path)
+
+        # Open via connect() (sets foreign_keys=ON + busy_timeout) with
+        # check_same_thread=False so the observer thread and timer callbacks
+        # can share it. foreign_keys MUST be on here — this is the only
+        # long-lived WRITER, so without it re-index/delete don't cascade.
+        self._conn = connect(self._db_path, check_same_thread=False)
+
+        # Write PID file so `seam status` can report watcher state
+        self._pid_file.write_text(str(os.getpid()))
+        logger.debug("PID file written: %s (pid=%d)", self._pid_file, os.getpid())
+
+        # Create and start the watchdog observer
+        self._observer = Observer()
+        self._observer.schedule(self, str(self._root_path), recursive=True)
+        self._observer.start()
+
+        logger.info("SeamWatcher started (debounce=%.0f ms)", config.SEAM_DEBOUNCE_MS)
+
+    def stop(self) -> None:
+        """Stop the watchdog Observer, cancel pending timers, and clean up.
+
+        Idempotent — safe to call multiple times.
+        """
+        logger.info("SeamWatcher stopping")
+
+        # Cancel any pending debounce timers
+        with self._timer_lock:
+            for timer in self._timers.values():
+                timer.cancel()
+            self._timers.clear()
+
+        # Stop the watchdog observer
+        if self._observer is not None:
+            self._observer.stop()
+            self._observer.join()
+            self._observer = None
+            logger.debug("Observer stopped and joined")
+
+        # Close DB connection
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None
+            logger.debug("DB connection closed")
+
+        # Remove PID file
+        try:
+            self._pid_file.unlink(missing_ok=True)
+            logger.debug("PID file removed: %s", self._pid_file)
+        except OSError as exc:
+            logger.warning("Could not remove PID file %s: %s", self._pid_file, exc)
+
+        logger.info("SeamWatcher stopped")
+
+    # ── watchdog event handlers ────────────────────────────────────────────────
+
+    def on_created(self, event: FileSystemEvent) -> None:
+        """Handle file creation — schedule a debounced index of the new file."""
+        if event.is_directory:
+            return
+        self._schedule_index(Path(str(event.src_path)))
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        """Handle file modification — schedule a debounced re-index."""
+        if event.is_directory:
+            return
+        self._schedule_index(Path(str(event.src_path)))
+
+    def on_deleted(self, event: FileSystemEvent) -> None:
+        """Handle file deletion — remove from the DB immediately (no debounce needed)."""
+        if event.is_directory:
+            return
+
+        path = Path(str(event.src_path))
+
+        # Cancel any pending index timer for this file (it no longer exists)
+        with self._timer_lock:
+            timer = self._timers.pop(str(path), None)
+        if timer is not None:
+            timer.cancel()
+
+        logger.debug("File deleted: %s — removing from DB", path)
+        self._do_delete(path)
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _schedule_index(self, path: Path) -> None:
+        """Cancel any existing timer for path, start a fresh debounce timer.
+
+        Only schedules for extensions in config.SEAM_LANGUAGE_MAP.
+        """
+        if path.suffix.lower() not in config.SEAM_LANGUAGE_MAP:
+            return  # not a file we care about
+
+        key = str(path)
+        with self._timer_lock:
+            # Cancel existing timer for this path if any
+            existing = self._timers.pop(key, None)
+            if existing is not None:
+                existing.cancel()
+
+            # Schedule new timer — callback runs after debounce delay
+            timer = threading.Timer(self._debounce_s, self._do_index, args=(path,))
+            self._timers[key] = timer
+            timer.start()
+            logger.debug("Debounce timer set for %s (%.0f ms)", path.name, config.SEAM_DEBOUNCE_MS)
+
+    def _do_index(self, path: Path) -> None:
+        """Debounce callback: index a single file into the DB.
+
+        Runs on a timer thread. Guards against missing conn (watcher was stopped).
+        """
+        # Remove the timer entry (it has already fired)
+        with self._timer_lock:
+            self._timers.pop(str(path), None)
+
+        conn = self._conn
+        if conn is None:
+            logger.debug("_do_index: watcher stopped, skipping %s", path)
+            return
+
+        # Runs on a Timer thread with no caller — any unhandled exception would
+        # die silently and leave the index stale without warning. Log it.
+        try:
+            logger.debug("Indexing file: %s", path)
+            result = index_one_file(conn, path)
+            if result is None:
+                logger.debug("Skipped %s (unsupported/binary/error)", path)
+            else:
+                logger.info("Indexed %s — %d symbols, %d edges", path.name, result[0], result[1])
+        except Exception:  # noqa: BLE001 — never let a re-index failure crash the daemon silently
+            logger.exception("re-index failed for %s — index may be stale", path)
+
+    def _do_delete(self, path: Path) -> None:
+        """Remove a file's index entries from the DB.
+
+        Runs on the watchdog event thread. Guards against missing conn.
+        """
+        conn = self._conn
+        if conn is None:
+            logger.debug("_do_delete: watcher stopped, skipping %s", path)
+            return
+
+        # Runs on the watchdog event thread — guard so a delete failure is
+        # logged rather than killing the event dispatch thread silently.
+        try:
+            delete_file(conn, path)
+            logger.info("Removed %s from index", path.name)
+        except Exception:  # noqa: BLE001
+            logger.exception("delete failed for %s", path)

seam_code-0.3.0.dist-info/METADATA

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: seam-code
+Version: 0.3.0
+Summary: Local code intelligence MCP server for AI agents
+Project-URL: Homepage, https://github.com/Catafal/seam
+Project-URL: Repository, https://github.com/Catafal/seam
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-intelligence,mcp,sqlite,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: tree-sitter-c-sharp>=0.23.5
+Requires-Dist: tree-sitter-c>=0.24.2
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Requires-Dist: tree-sitter-go>=0.25.0
+Requires-Dist: tree-sitter-java>=0.23.5
+Requires-Dist: tree-sitter-javascript>=0.22.0
+Requires-Dist: tree-sitter-php>=0.24.1
+Requires-Dist: tree-sitter-python>=0.22.0
+Requires-Dist: tree-sitter-ruby>=0.23.1
+Requires-Dist: tree-sitter-rust>=0.24.2
+Requires-Dist: tree-sitter-swift>=0.7.3
+Requires-Dist: tree-sitter-typescript>=0.22.0
+Requires-Dist: tree-sitter>=0.22.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: semantic
+Requires-Dist: fastembed>=0.4; extra == 'semantic'
+Provides-Extra: server
+Requires-Dist: mcp>=1.0.0; extra == 'server'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn>=0.30; extra == 'web'
+Description-Content-Type: text/markdown
+
+# Seam
+
+<p align="center">
+  <img src="docs/assets/seam-hero.png" alt="A codebase as a graph: hexagonal symbol nodes connected by typed edges around a central indexed core; a queried symbol (chartreuse) traces through the core to an impacted dependent (magenta)" width="100%">
+</p>
+
+**Local code intelligence for AI agents.** Index a codebase once; agents query its structure instead of re-discovering it with `grep` every session.
+
+`v0.3.0` · 12 languages · 12 MCP tools · SQLite-backed · **zero network calls at query time** · gate-green (~3,055 tests)
+
+---
+
+## The problem
+
+An AI coding agent starts every session blind. To answer "what breaks if I change `init_db`?" it greps for the name, opens each hit, reads the surrounding code, follows the imports, and reconstructs the call graph by hand — spending thousands of tokens rebuilding structural knowledge that was true last session and the session before.
+
+That structure is *computable*. A parser already knows that `index_one_file` calls `init_db`, that `Server` holds a `Client`, that `UserView` implements `Renderable`. Seam computes it once, stores it in a local SQLite graph, and exposes it over a handful of MCP tools so the agent **asks instead of greps**.
+
+```text
+Without Seam:  "what calls init_db?"  → grep → 14 files → read each → trace imports → ~30k tokens, often wrong
+With Seam:     seam_impact init_db    → blast radius by risk tier → ~4.5k tokens, graph-accurate
+```
+
+The win compounds: every structural question — callers, blast radius, call paths, functional areas, which tests to run — is one tool call against a graph that stays fresh automatically.
+
+## The mental model
+
+Think of Seam as **a compiler's symbol table and call graph for your whole repository**, kept fresh in the background and exposed over MCP and a CLI.
+
+```text
+  source files                tree-sitter            .seam/seam.db
+  (12 languages)   ─────────▶  structural    ─────▶  SQLite + FTS5        ◀── file watcher
+                               parsing               (symbols + edges          (debounced
+                                                       + clusters + FTS)         re-index)
+                                                            │
+                                            ┌───────────────┴───────────────┐
+                                            ▼                               ▼
+                                     MCP server (stdio)              CLI read commands
+                                     12 read-only tools              query / impact / trace …
+                                            │                               │
+                                            └──────────────┬────────────────┘
+                                                           ▼
+                                            AI agent (Claude Code · Cursor · Codex)
+```
+
+Three properties define it:
+
+- **Indexed once, fresh forever.** `seam init` builds the graph; an optional `watchdog` daemon re-indexes edited files in the background. The agent never thinks about staleness — and graph-traversal tools surface a banner if the index *is* stale.
+- **100% local.** The index is a per-project SQLite file (`.seam/seam.db`). The read path makes **no network calls** — no API keys, no cloud, no telemetry.
+- **A graph, not a search box.** Symbols are nodes; calls, imports, inheritance, composition, and field access are typed edges. Every answer is graph traversal, not string matching.
+
+---
+
+## Quickstart
+
+> **Not yet on PyPI.** The distribution name will be `seam-mcp` (the name `seam` belongs to an unrelated package); the import package and the `seam` command keep the short name. Install from source for now.
+
+```bash
+git clone <repo-url> && cd seam
+uv sync                     # CLI only — no MCP server, no semantic search
+uv sync --extra server      # + the MCP server (`seam start`) — adds the `mcp` package
+uv sync --extra semantic    # + semantic search (fastembed, ONNX/CPU, no torch, ~67 MB model on first run)
+uv sync --extra web         # + the Seam Explorer web UI (FastAPI)
+# everything: uv sync --extra server --extra semantic --extra web
+```
+
+### Use it from the CLI (no server needed)
+
+Every read command queries the SQLite index directly — the full feature set works with no MCP server running:
+
+```bash
+cd /path/to/your/project
+uv run seam init                       # index the project (writes .seam/seam.db)
+uv run seam search "auth token"        # full-text (hybrid semantic when enabled)
+uv run seam query "verify user login"  # concept search + 1-hop graph expansion
+uv run seam context authenticate_user  # 360° view: callers, callees, cluster, signature
+uv run seam impact  authenticate_user  # blast radius by risk tier
+uv run seam structure                  # whole-repo directory/container map
+# also: trace · changes · why · clusters · affected · flows · pack · status · sync
+```
+
+### Wire it to an AI agent
+
+`seam install` defaults to writing a **token-lean CLI playbook** into the repo so the agent queries via the `seam` CLI (cheaper than MCP — the CLI's `--quiet` mode is ~14× leaner than the leanest MCP call, and there's no ~6k-token standing tool-schema cost). It renders into each agent's cheapest native mechanism: a Claude Code skill, a Cursor agent-requested rule, and an `AGENTS.md` block for Codex.
+
+```bash
+uv run seam install                       # CLI guidance for Claude Code (skill + CLAUDE.md hook)
+uv run seam install --target all          # guidance for Claude Code + Cursor + Codex
+uv run seam install --with-mcp            # ALSO wire the MCP server (needs the `server` extra)
+uv run seam install --print-config        # preview everything, write nothing
+uv run seam uninstall                     # reverse it (removes guidance + MCP config)
+```
+
+The guidance teaches the agent the escalation ladder (`--quiet` → `--json --lean` → full `--json`), how to keep the index fresh (`seam init` / `seam sync`), and when to reach for each command. It's idempotent (a marker-delimited block in `AGENTS.md`/`CLAUDE.md`, never duplicated, foreign content preserved) and reversible.
+
+Prefer native tool-calling? Add `--with-mcp` (install the `server` extra first). To wire MCP by hand, add to `.mcp.json` at the repo root:
+
+```json
+{
+  "mcpServers": {
+    "seam": { "type": "stdio", "command": "seam", "args": ["start", "/path/to/your/project"] }
+  }
+}
+```
+
+---
+
+## The 12 MCP tools
+
+Grouped by the question an agent is asking. Every tool is **read-only**; the server never writes the index.
+
+### Find code
+
+| Tool | Answers | Key args |
+|------|---------|----------|
+| `seam_search` | "Where is text X mentioned?" — FTS5 over names + docstrings + signatures, with fuzzy fallback; hybrid keyword+semantic when enabled. | `text`, `limit`, `semantic` |
+| `seam_query` | "Find all code related to concept X." — FTS5 match + 1-hop graph expansion, rescored by name/path/cluster signals. | `concept`, `limit`, `semantic` |
+
+### Understand a symbol
+
+| Tool | Answers | Key args |
+|------|---------|----------|
+| `seam_context` | "Show me everything about symbol X." — callers, callees, signature, cluster, `field_readers`/`field_writers`. Resolves bare/qualified/class names and merges homonyms. | `symbol` or `uid` |
+| `seam_context_pack` | "Give me a paste-ready bundle for X." — `seam_context` + WHY comments + enriched neighbors + cluster peers in one call; neighbors ranked by relevance to the seed. | `symbol` |
+| `seam_why` | "Why is this code like this?" — the `WHY`/`HACK`/`NOTE`/`TODO`/`FIXME` comments. | `symbol`, `path` |
+
+### Assess change risk
+
+| Tool | Answers | Key args |
+|------|---------|----------|
+| `seam_impact` | "What breaks if I change X?" — blast radius bucketed into risk tiers, with provenance, summary counts, and a hard byte/entry budget. | `target`, `direction`, `max_depth`, `limit`, `max_bytes` |
+| `seam_changes` | "Is my current diff risky?" — git diff → changed symbols → overall risk level. | `scope`, `base_ref` |
+| `seam_affected` | "Which tests should I run?" — changed files → impacted test files via reverse-dependency traversal. | `changed_files`, `depth` |
+
+### Navigate the graph
+
+| Tool | Answers | Key args |
+|------|---------|----------|
+| `seam_trace` | "How does X reach Y?" — shortest call/dependency path, hop by hop, with edge kind + confidence. | `source`, `target`, `max_depth` |
+| `seam_flows` | "Where does execution start, and where does it go?" — entry points ranked by reach, or one entry's forward call-chain tree. | `entry` (optional) |
+
+### Map the repository
+
+| Tool | Answers | Key args |
+|------|---------|----------|
+| `seam_clusters` | "What are the functional areas?" — Louvain communities (semantic coupling), or the members of one. | `cluster_id` (optional) |
+| `seam_structure` | "How is the repo laid out?" — the filesystem → directory → file → container tree with symbol counts and area labels. | `path`, `depth`, `nodes` |
+
+> **Lean mode.** The enrichment-carrying tools (`seam_context`, `seam_trace`, `seam_impact`, `seam_context_pack`) accept `verbose=false` (CLI `--lean`) to drop heavy provenance fields and shrink the response for tight token budgets. `seam_impact` additionally supports a hard `max_bytes` ceiling and emits `next_actions` hints when results are trimmed.
+
+---
+
+## Supported languages
+
+Twelve languages, parsed with [tree-sitter](https://tree-sitter.github.io/). All share the same tools, symbol kinds, edge kinds, and enrichment fields.
+
+| Language | Extensions | | Language | Extensions |
+|----------|-----------|-|----------|-----------|
+| Python | `.py` | | C# | `.cs` |
+| TypeScript | `.ts` `.tsx` | | Ruby | `.rb` |
+| JavaScript | `.js` `.mjs` `.cjs` | | C | `.c` `.h` |
+| Go | `.go` | | C++ | `.cpp` `.cc` `.cxx` `.c++` `.hpp` `.hh` `.hxx` |
+| Rust | `.rs` | | PHP | `.php` |
+| Java | `.java` | | Swift | `.swift` |
+
+> **Kotlin is not yet supported** — the available tree-sitter-kotlin grammar mis-parses common constructs (interfaces, objects, classes with constructors). Tracked for a future release. See [`docs/adr/009-swift-support.md`](docs/adr/009-swift-support.md).
+>
+> Per-language extraction caveats (e.g. `.h` maps to C; C++ method visibility; Ruby dynamic visibility) are documented in [`docs/CONCEPTS.md`](docs/CONCEPTS.md#per-language-notes).
+
+---
+
+## Core concepts
+
+A short tour — the full treatment is in [`docs/CONCEPTS.md`](docs/CONCEPTS.md).
+
+**The graph.** Nodes are symbols (`function`, `class`, `method`, `interface`, `type`, `field`). Edges are **typed** and capture nine relationships:
+
+| Edge kind | Captures |
+|-----------|----------|
+| `call` | one symbol invokes another |
+| `import` | a module/symbol import |
+| `extends` · `implements` | class inheritance / interface conformance |
+| `instantiates` | `new Foo()` / struct-literal construction |
+| `holds` | a class **stores** a typed field/property (composition / DI) |
+| `uses` | a function **references** a user type as a parameter (signature coupling) |
+| `reads` · `writes` | a field/property is read or written (data-flow) |
+
+Edges are keyed by **symbol name**, not row id — this is what lets the watcher re-index one file independently without rewriting the whole graph. All traversal is kind-agnostic, so every tool picks up every edge kind automatically.
+
+**Confidence tiers.** Each edge resolves to `EXTRACTED` (target is unambiguous), `AMBIGUOUS` (name collides — verify), or `INFERRED` (heuristic / cross-module). A multi-hop path is only as strong as its weakest hop. Each result carries `resolved_by` provenance explaining *how* the tier was decided.
+
+**Risk tiers.** `seam_impact` and `seam_changes` bucket dependents by distance: `WILL_BREAK` (d=1, must update), `LIKELY_AFFECTED` (d=2, should test), `MAY_NEED_TESTING` (d≥3, test if critical). `seam_changes` rolls these up into `low` → `medium` → `high` → `critical`.
+
+**Clusters.** A pure-Python Louvain pass groups symbols into functional areas by coupling. Labels are deterministic by default (`dir/file — top symbol`) or, opt-in, LLM-generated at index time only.
+
+**Edge synthesis.** Static parsing can't see runtime polymorphism. A post-pass over the whole graph synthesizes the edges parsing structurally misses — interface→implementation fan-out, closure-collection dispatch, event-emitter handlers — tagged with their provenance channel.
+
+**Semantic search.** Opt-in local embeddings (fastembed, ONNX on CPU) merge with FTS5 via Reciprocal Rank Fusion, so `"retry logic"` can surface `_backoff_with_jitter` even with no shared token. The model downloads once, then runs 100% locally.
+
+**Staleness banner.** Graph-traversal tools attach an `index_status` banner when the index has drifted from disk — so an agent is never silently handed wrong blast-radius answers.
+
+---
+
+## Configuration
+
+Everything is environment-variable driven with sensible defaults — see [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full reference (~50 knobs). The few you might actually set:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `SEAM_SEMANTIC` | `off` | Enable hybrid keyword + semantic search (needs the `semantic` extra + `seam init --semantic`). |
+| `SEAM_CLUSTER_NAMING` | `deterministic` | `llm` opts into LLM cluster labels at index time (needs `SEAM_LLM_API_KEY`). Read path stays 100% local regardless. |
+| `SEAM_IMPACT_MAX_BYTES` | `0` (off) | Hard character ceiling on `seam_impact` output for tight context budgets. |
+
+Most knobs are gated `on` by default and have an `off` that restores byte-identical pre-feature behavior — a deliberate discipline so upgrades never silently change tool output.
+
+---
+
+## Seam Explorer — local visual graph UI
+
+`seam serve` (the `[web]` extra) starts a read-only, `127.0.0.1`-only browser explorer for the index.
+
+```bash
+uv sync --extra web
+seam init          # index first
+seam serve         # opens http://127.0.0.1:7420
+seam serve --no-open --port 8000
+```
+
+A React + TypeScript SPA (React Flow) served by FastAPI. Nothing leaves the machine. Features: command-palette search, a depth-1 caller/callee card-canvas with confidence-styled edges, lazy expand, a detail panel, an impact overlay that paints blast radius by risk tier, a trace-path highlighter, a git-changes drawer, and a whole-repo cluster constellation. All four analyses reuse the **same handlers** that power the CLI/MCP tools — a third transport, no query logic duplicated.
+
+---
+
+## Architecture
+
+The import hierarchy is strictly layered — read flows down, never up:
+
+```text
+cli / server / web  →  analysis  →  query  →  indexer / db
+```
+
+`analysis` is built from **pure leaf modules** (no DB, no IO, never raise) — clustering, RWR neighbor ranking, byte budgeting, the truncation steer, staleness detection. This makes each piece testable in isolation and keeps the failure surface tiny.
+
+- **Read it as a narrative:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — current system overview, then the full phase-by-phase history.
+- **Read it as a diagram:** [`docs/architecture.html`](docs/architecture.html) — a standalone illustrated page (system pipeline, layered hierarchy, data-flow, edge-kind graph, schema).
+- **Decision rationale:** [`docs/adr/`](docs/adr/) — architecture decision records.
+- **Concepts in depth:** [`docs/CONCEPTS.md`](docs/CONCEPTS.md) — how and why each subsystem works.
+
+---
+
+## Design principles
+
+These are the non-negotiables — and they are guarantees to the user, not just internal rules:
+
+1. **Zero external services at runtime.** The MCP read path makes no network calls. The only optional outbound call (LLM cluster naming) runs at index time, is off by default, and falls back to deterministic labels on any error.
+2. **SQLite only.** No graph DB, no vector DB to babysit, no ORM. One file per project, gitignored.
+3. **Parsers never raise.** A malformed file is skipped, not fatal. The indexer degrades gracefully; analysis leaves return empty rather than throw.
+4. **Edges are keyed by name.** This is what makes independent per-file re-indexing correct — the watcher can rewrite one file's symbols and edges without touching the rest of the graph.
+5. **Additive by default.** New features ship behind a defaulted-on switch with an `off` that is byte-identical to before. Schema changes are additive migrations that auto-run on open.
+
+---
+
+## Development
+
+```bash
+uv sync --dev      # install dev dependencies
+make gate          # lint (ruff) + typecheck (mypy) + tests — must be green before every commit
+make fmt           # format + autofix (not part of the gate)
+make build-web     # build the Explorer SPA into seam/_web/ (requires Node.js — build-time only)
+make eval          # run the recall-regression harness
+```
+
+**Conventions:** max 200 lines/function, 1000 lines/file · all imports at top · config only from `seam/config.py` · type hints required (`X | None`, not `Optional[X]`) · tests in `tests/` mirroring the package.
+
+## License
+
+See [LICENSE](LICENSE).