From f340ff941ff33299ca4b7bd56d07b0816d8a3695 Mon Sep 17 00:00:00 2001
From: Aleksei Kudriashov <akud.soft@gmail.com>
Date: Sat, 20 Jun 2026 17:24:22 +0200
Subject: [PATCH] Add codespaces skill for belief-map architecture discovery

Initial import of the codespaces skill: query .belief_map.sexp for module
boundaries, dependencies, blast radius, and the minimal files to read before
non-trivial code changes.

Includes the belief-map and infra-topology builders, the belief-search query
engine and its tests, and reference docs for the S-expression notation and
query patterns.
---
 .agents/designs/infra-topology-builders.md |  288 ++
 .gitignore                                 |   11 +
 LOG.md                                     |    9 +
 SKILL.md                                   |  254 ++
 references/scheme-queries.md               |   88 +
 references/sexp-notation.md                |  176 ++
 scripts/belief_search.py                   | 2256 ++++++++++++++
 scripts/build_belief_map.py                | 3182 ++++++++++++++++++++
 scripts/build_infra_topology.py            |  853 ++++++
 scripts/git_descendants.py                 |  124 +
 tests/test_belief_search.py                |  152 +
 11 files changed, 7393 insertions(+)
 create mode 100644 .agents/designs/infra-topology-builders.md
 create mode 100644 .gitignore
 create mode 100644 LOG.md
 create mode 100644 SKILL.md
 create mode 100644 references/scheme-queries.md
 create mode 100644 references/sexp-notation.md
 create mode 100644 scripts/belief_search.py
 create mode 100755 scripts/build_belief_map.py
 create mode 100644 scripts/build_infra_topology.py
 create mode 100755 scripts/git_descendants.py
 create mode 100644 tests/test_belief_search.py

diff --git a/.agents/designs/infra-topology-builders.md b/.agents/designs/infra-topology-builders.md
new file mode 100644
index 0000000..f7ef7e5
--- /dev/null
+++ b/.agents/designs/infra-topology-builders.md
@@ -0,0 +1,288 @@
+Infrastructure Topology Builders for Belief Map
+=================================================
+
+Context and motivation
+----------------------
+
+The belief map currently models **source-code** relationships: imports, entity references, data flows, and interface implementations. It has no visibility into **infrastructure topology** -- which services exist, how they connect at the network level, what databases/queues/caches they depend on, and how they are deployed.
+
+This creates a blind spot: when an agent investigates a cross-service issue or plans a deployment change, the belief map shows code dependencies but not the runtime service graph. The data exists in three IaC formats already present in the codebase:
+
+- **Kustomize** (`.k8s/base/kustomization.yaml`): 20+ services in the mono workspace, each with deployment manifests declaring env vars, service endpoints, and resource dependencies (postgres, rabbitmq, minio, vault)
+- **Helm charts** (`charts/*/Chart.yaml`): avionica streaming services (sara-mock, transformer, ergoss-push, nats, prometheus, dashboard)
+- **Terraform** (`infra/terraform/*.tf`): infrastructure prerequisites (namespaces, secrets, PVCs, configmaps) with module dependencies
+
+Goals:
+- Extract service topology from all three IaC formats and emit sexp edges into the belief map
+- Detect service-to-service dependencies: env var references, service DNS names, port mappings
+- Detect service-to-infrastructure dependencies: databases, message queues, object stores, vaults
+- Output is the same `.belief_map.sexp` format, appended or merged by the main builder
+
+Non-goals for first implementation (v1):
+- No runtime service discovery (no kubectl, no cluster queries)
+- No Tilt/docker-compose parsing (separate effort)
+- No ingress/route topology (just service-to-service and service-to-infra)
+- No multi-cluster or multi-namespace topology
+- No cost or resource quota analysis
+
+
+Implementation considerations
+------------------------------
+
+**Pure static analysis.** All three parsers read YAML/HCL files from disk. No cluster access needed.
+
+**Additive to existing graph.** Infrastructure edges are a new layer on top of the source-code graph. They use new edge types (`k8s-service`, `k8s-depends`, `infra-resource`) that don't conflict with existing `imports`/`calls-api`/`data-flow` edges.
+
+**Node identity.** Infrastructure nodes use the service name from k8s metadata (e.g., `app-service`, `drive-postgres`, `nats`) prefixed with `infra/` to distinguish from source-code module IDs. Example: `infra/app-service`, `infra/drive-postgres`.
+
+**Minimal dependencies.** Kustomize and Helm parsers use only PyYAML (already available). Terraform parser uses `hcl2` Python library or falls back to regex if unavailable.
+
+**Invocation.** Each script is standalone but designed to be called from `build_belief_map.py` as an optional post-pass:
+
+```bash
+python3 scripts/build_infra_topology.py [--kustomize PATH] [--helm PATH] [--terraform PATH]
+```
+
+Or integrated into the main builder via `--infra` flag.
+
+
+High-level behavior
+-------------------
+
+### Discovery
+
+1. Scanner walks the workspace looking for:
+   - `kustomization.yaml` / `kustomization.yml` files (kustomize)
+   - `Chart.yaml` files (helm)
+   - `*.tf` files in directories containing `main.tf` (terraform)
+
+2. For each discovered IaC root, the appropriate parser runs.
+
+3. All parsers emit the same intermediate format: a list of `InfraNode` and `InfraEdge` dataclasses.
+
+4. A merge step deduplicates nodes by service name and writes sexp output.
+
+### Kustomize parser
+
+Reads each kustomization.yaml and its referenced resources:
+
+1. Parse `kustomization.yaml` -> extract `resources` list
+2. For each resource directory, parse `deployment.yaml` / `statefulset.yaml`:
+   - Extract service name from `metadata.name` or `app.kubernetes.io/name` label
+   - Extract container image -> maps service to codebase repo
+   - Extract `env` and `envFrom` -> detect service endpoint references:
+     - `*_HOST`, `*_URL`, `*_SERVICE_HOST` -> depends-on target service
+     - `DATABASE_URL`, `POSTGRES_*` -> depends-on database
+     - `RABBITMQ_*`, `AMQP_*`, `NATS_*` -> depends-on message queue
+     - `REDIS_*` -> depends-on cache
+     - `S3_*`, `MINIO_*` -> depends-on object store
+3. Parse `service.yaml` -> extract ports and service type
+
+Output edges:
+```scheme
+(infra-node infra/app-service :kind deployment :image upgraide/app-service :port 3001 :component api)
+(infra-node infra/app-postgres :kind deployment :image postgres:16 :port 5432 :component database)
+(k8s-depends infra/app-service infra/app-postgres :via env :transport tcp)
+(k8s-depends infra/app-service infra/drive-service :via env :transport http)
+(k8s-service infra/app-service app-service :namespace upgraide :port 3001)
+```
+
+### Helm parser
+
+Reads Chart.yaml and values.yaml:
+
+1. Parse `Chart.yaml` -> extract chart name, version, dependencies
+2. Parse `values.yaml` -> extract:
+   - `image.repository` / `image.tag` -> container image
+   - `env.*` -> service endpoint references (same heuristics as kustomize)
+   - `service.port` -> exposed port
+3. Parse `Chart.yaml` `dependencies` -> direct chart-to-chart edges
+
+Output edges:
+```scheme
+(infra-node infra/sara-mock :kind helm-chart :image sara-mock :port 8080 :chart sara-mock)
+(helm-depends infra/sara-mock infra/nats :via chart-dependency)
+```
+
+### Terraform parser
+
+Reads `*.tf` files:
+
+1. Find all `module` blocks -> extract module name and source
+2. Find all `resource` blocks -> extract resource type and name
+3. Build dependency graph from:
+   - `module.X.output_name` references in other modules
+   - `depends_on` explicit declarations
+   - Variable references across modules
+
+Output edges:
+```scheme
+(infra-node infra/tf-namespace :kind terraform :resource kubernetes_namespace)
+(infra-node infra/tf-secrets :kind terraform :resource module)
+(tf-depends infra/tf-secrets infra/tf-namespace :via module-reference)
+```
+
+
+S-expression output format
+---------------------------
+
+New fact types (appended to `.belief_map.sexp`):
+
+```scheme
+; Infrastructure nodes
+(infra-node <id> :kind <deployment|statefulset|helm-chart|terraform> :image <image> :port <port> :component <label>)
+
+; Kustomize service dependencies
+(k8s-depends <src-service> <tgt-service> :via <env|dns|volume> :transport <http|tcp|amqp|grpc>)
+
+; Kustomize service declarations
+(k8s-service <service-id> <dns-name> :namespace <ns> :port <port>)
+
+; Helm chart dependencies
+(helm-depends <src-chart> <tgt-chart> :via <chart-dependency|values-ref>)
+
+; Terraform module dependencies
+(tf-depends <src-module> <tgt-module> :via <module-reference|depends-on|variable>)
+
+; Cross-layer: maps infra service to source-code repo
+(infra-maps infra/app-service app-service :via image-name)
+```
+
+The `infra-maps` edge connects infrastructure nodes to source-code nodes, enabling queries like:
+```scheme
+(deps "infra/app-service" 2)  ; what infra does app-service depend on?
+(rdeps "infra/drive-postgres" 1)  ; which services use this database?
+```
+
+
+Error handling and UX
+---------------------
+
+- Missing YAML files: skip with `; warning: skipped <path>: file not found` comment in output
+- Malformed YAML: skip resource, emit `; error: parse failed <path>: <reason>`
+- Missing PyYAML: exit with clear error message and install instructions
+- Missing hcl2 (for terraform): fall back to regex-based parsing, emit `; warning: terraform parsed with regex fallback`
+- No IaC files found: emit `; info: no infrastructure files found` and exit cleanly
+
+
+Update cadence / Lifecycle
+--------------------------
+
+Infrastructure topology changes rarely compared to source code. The scripts should:
+- Run only when `--infra` flag is passed to `build_belief_map.py`
+- OR when the user explicitly runs `build_infra_topology.py`
+- Cache results alongside `.belief_map_cache.json` using mtime-based invalidation on IaC files
+
+
+Future-proofing
+---------------
+
+- **Tilt / docker-compose**: same intermediate format, different parser. Add `--tilt` and `--compose` flags.
+- **Ingress topology**: parse `ingress.yaml` / `Ingress` resources for external routing
+- **Multi-namespace**: extend `infra-node` with `:namespace` field
+- **Service mesh**: parse Istio/Linkerd VirtualService/DestinationRule for traffic routing edges
+- **GitOps**: parse ArgoCD Application manifests for deployment pipeline edges
+- **Runtime enrichment**: optional `--live` flag to query kubectl for actual pod status
+
+
+Implementation outline
+----------------------
+
+### Phase 1: Core infrastructure (shared)
+
+1. Define `InfraNode` and `InfraEdge` dataclasses in `build_infra_topology.py`
+2. Define env-var heuristic patterns for service/infra detection
+3. Implement sexp writer for new fact types
+4. Add `--infra` flag to `build_belief_map.py` that calls the topology builder post-pass
+
+### Phase 2: Kustomize parser
+
+1. Walk directories for `kustomization.yaml`
+2. Parse resource references -> find deployment/service YAML
+3. Extract service names, images, ports, env vars
+4. Apply env-var heuristics to detect dependencies
+5. Emit `infra-node`, `k8s-depends`, `k8s-service` facts
+
+### Phase 3: Helm parser
+
+1. Walk directories for `Chart.yaml`
+2. Parse Chart.yaml dependencies
+3. Parse values.yaml for image/port/env configuration
+4. Parse templates/*.yaml for env var references (handle Go template syntax)
+5. Emit `infra-node`, `helm-depends` facts
+
+### Phase 4: Terraform parser
+
+1. Walk directories for `main.tf`
+2. Parse module blocks and resource blocks (via hcl2 or regex)
+3. Build dependency graph from cross-module references
+4. Emit `infra-node`, `tf-depends` facts
+
+### Phase 5: Cross-layer mapping
+
+1. For each `infra-node` with `:image`, match image name against known repo names
+2. Emit `infra-maps` edges connecting infrastructure to source-code graph
+3. Update `belief_search.py` to parse new edge types
+
+### Phase 6: Integration
+
+1. Add new edge types to `belief_search.py` edge parser
+2. Update `sexp-notation.md` reference with new fact types
+3. Update SKILL.md with infrastructure query examples
+
+
+Testing approach
+----------------
+
+**Unit tests:**
+- Kustomize parser: fixture kustomization.yaml + deployment.yaml -> expected InfraNode/InfraEdge list
+- Helm parser: fixture Chart.yaml + values.yaml -> expected output
+- Terraform parser: fixture main.tf with modules -> expected dependency graph
+- Env-var heuristics: input env var name/value -> expected dependency type
+
+**Integration tests:**
+- Run kustomize parser against `mono/app-service/.k8s/base/` -> verify app-service depends on postgres
+- Run helm parser against `nextnet-avsync-streaming/charts/` -> verify chart dependencies
+- Run terraform parser against `avsync-stream-lab/infra/terraform/` -> verify module dependencies
+
+**Manual verification:**
+- Run `build_infra_topology.py` on mono workspace
+- Query `belief_search.py rdeps infra/drive-postgres 1` -> verify all drive consumers listed
+- Query `belief_search.py deps infra/app-service 2` -> verify database + queue dependencies shown
+
+
+Acceptance criteria
+-------------------
+
+1. Given a workspace with `.k8s/base/` directories, when running `build_infra_topology.py --kustomize .`, then `infra-node` facts are emitted for each deployment with correct service name, image, and port.
+
+2. Given a deployment.yaml with `DATABASE_URL` env var, when parsing, then a `k8s-depends` edge is emitted to the postgres service with `:transport tcp`.
+
+3. Given a kustomization.yaml with `resources: [app-service, app-web, postgres]`, when parsing, then all three services appear as `infra-node` facts.
+
+4. Given a Helm Chart.yaml with `dependencies`, when parsing, then `helm-depends` edges are emitted for each dependency.
+
+5. Given Terraform modules with cross-references (`module.namespace.name`), when parsing, then `tf-depends` edges reflect the dependency order.
+
+6. Given an `infra-node` with `:image upgraide/app-service`, when cross-layer mapping runs, then an `infra-maps` edge connects `infra/app-service` to the source-code `app-service` node.
+
+7. Given `--infra` flag passed to `build_belief_map.py`, when building completes, then infrastructure facts appear in `.belief_map.sexp` alongside source-code facts.
+
+8. Given no IaC files in the workspace, when running the topology builder, then it exits cleanly with an informational message and no errors.
+
+9. `belief_search.py` correctly loads and queries `infra-node`, `k8s-depends`, `helm-depends`, `tf-depends`, and `infra-maps` edges.
+
+
+Estimated scope
+---------------
+
+| Component | Lines | Effort |
+|-----------|-------|--------|
+| Shared infra types + sexp writer | ~80 | Small |
+| Kustomize parser | ~200 | Medium |
+| Helm parser | ~150 | Medium |
+| Terraform parser | ~120 | Medium |
+| Cross-layer mapping | ~40 | Small |
+| belief_search.py integration | ~10 | Trivial |
+| Tests | ~150 | Medium |
+| **Total** | **~750** | ~2 days |
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..787bdba
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,11 @@
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+.ruff_cache/
+
+# Generated belief-map artifacts (produced by scripts/build_belief_map.py)
+.belief_map.sexp
+.belief_map_cache.json
diff --git a/LOG.md b/LOG.md
new file mode 100644
index 0000000..9cb8dd4
--- /dev/null
+++ b/LOG.md
@@ -0,0 +1,9 @@
+## 2026-06-19
+
+### Changes
+- Updated the codespaces skill workflow so agents are directed to query the belief map before reading source and to use `quick` as a first-pass `analyze` shortcut.
+- Changed `belief_search.py quick` to run full `analyze` output instead of boundary-only output, and made it resolve legacy path-map aliases found in raw belief-map hits.
+- Added focused unit coverage for quick analyze output, alias resolution from raw hits, boundary files-only output, and no-match suggestions.
+
+### Motivation
+- Session-log review showed that agents usually used `search` and `analyze` after activation, but often queried too late and did not discover shortcut or boundary commands.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..571682d
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,254 @@
+---
+name: codespaces
+description: >
+  Query `.belief_map.sexp` before non-trivial code changes to find module boundaries,
+  dependencies, blast radius, and the minimal files to read. Use for architecture
+  discovery, impact analysis, and boundary checks.
+---
+
+# Codespaces -- Belief Map Architecture Discovery
+
+Query `.belief_map.sexp` to discover modules, boundaries, and dependencies before reading source files. Never read code blindly -- query the graph first.
+
+## Scripts
+
+This skill bundles Python scripts. Run them from the skill's base directory:
+
+- `scripts/belief_search.py` -- query the belief map graph
+- `scripts/build_belief_map.py` -- generate the belief map from source
+- `scripts/build_infra_topology.py` -- extract Kustomize, Helm, and Terraform topology facts
+- `scripts/git_descendants.py` -- find all commits descending from HEAD (or a given ref)
+
+Never use project-local copies of these scripts -- they may be outdated and output JSON instead of sexp.
+
+## Prerequisite
+
+Locate the belief map. If absent, build it:
+
+```bash
+ls .belief_map.sexp belief_map.sexp 2>/dev/null
+# Build: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
+python3 scripts/build_belief_map.py          # incremental ~5s
+python3 scripts/build_belief_map.py --full   # full rebuild ~30s
+```
+
+## Mandatory Workflow: Query Before Code
+
+For non-trivial code work, run a belief-map query before `rg`, `find`, `sed`,
+`cat`, `nl`, opening directories, or reading source files. The skill only helps
+when it is used as the first scoping step, not as confirmation after source has
+already been inspected.
+
+**Fast first pass when the task has a clear keyword:**
+```bash
+python3 scripts/belief_search.py quick "keyword"
+```
+`quick` searches for the first matching module and immediately runs `analyze`.
+Use it to get boundary files, dependencies, reverse dependencies, layers, and
+violations in one step. If `quick` returns the wrong module or no match, use the
+explicit `search` -> `analyze` flow below.
+
+**Step 1 -- Find the module ID:**
+```bash
+python3 scripts/belief_search.py search "keyword"
+python3 scripts/belief_search.py entity EntityName
+```
+Use `search` or `entity` to locate the module ID. Module IDs are **full relative paths** like `pki-service/src/modules/ca/ca.service`, not short codes like `ps34`. The belief map may contain short path-map IDs internally, but they are resolved automatically -- always pass human-readable path-like strings. Do NOT guess or invent module IDs -- always confirm with `search` first.
+
+**Step 2 -- Analyze the module (do this IMMEDIATELY, not optionally):**
+```bash
+python3 scripts/belief_search.py analyze <module-id>
+```
+`analyze` is the PRIMARY command. It returns the full context: boundary files, dependencies, reverse dependencies, architecture layer, and violations. Always run it before reading any source.
+
+**Step 3 -- Read only the boundary files listed in the analyze output.**
+
+**Step 4 -- Do NOT read entire directories.** If the boundary shows 2-3 relevant files, read only those files. Ignore everything else in the directory.
+
+## Command Reference
+
+| Command | Purpose | Example |
+|---|---|---|
+| `search "<pattern>"` | Regex grep on graph (find module IDs) | `search "operative.*service"` |
+| `analyze <id>` | Full module analysis (PRIMARY command) | `analyze drive/modules/drive/drive_schema` |
+| `quick <keyword>` | Search + analyze first match (shortcut) | `quick operatives` |
+| `boundary <id>` | Files to read for a change | `boundary operatives.service` |
+| `boundary <id> --files-only` | File paths only (compact) | `boundary operatives.service --files-only` |
+| `entity <Name>` | Find definitions + references | `entity DrivePath` |
+| `deps <id> [depth]` | Outgoing dependency tree | `deps operatives.service 3` |
+| `rdeps <id> [depth]` | Blast radius (who depends on this) | `rdeps drive_schema 2` |
+| `flow <id> <fn>` | Trace call/data flow | `flow drive_api fetchFiles` |
+| `module <id>` | Single module with edges | `module operatives.controller` |
+| `boundaries [id\|all]` | Check architecture violations | `boundaries all` |
+| `invariants [id\|all]` | Check naming convention violations | `invariants all` |
+| `layers` | Show all modules by layer | `layers` |
+| `find_function <name>` | Find function/method definitions | `find_function createOrder` |
+| `find_type <name>` | Find type/class/ifc/enum definitions | `find_type DriveDbCommitResponse` |
+| `find_callchain <src> <tgt> [depth]` | Trace call path between functions | `find_callchain createOrder processPayment` |
+| `find_callers <fn> [depth]` | Who calls this function | `find_callers handleRequest 3` |
+| `find_calls <fn> [depth]` | What does this function call | `find_calls createOrder 2` |
+| `grep_functions <pattern>` | Search function bodies in source | `grep_functions "validate.*input"` |
+| `diff_functions [ref]` | Changed functions in git diff | `diff_functions HEAD~3` |
+| `query '<sexp>'` | Composable Scheme query | `query '(count (boundary "X"))'` |
+| `repl` | Interactive Scheme REPL | `repl` |
+
+## Quick Reference: rg Queries
+
+When you need fast, targeted lookups without invoking the Python script, query the belief map directly with `rg`. The bundled builder writes `.belief_map.sexp`; if a repo still uses the legacy `belief_map.sexp`, substitute that filename in the commands below:
+
+```bash
+# All facts about a module
+rg 'drive/modules/drive_db/api ' .belief_map.sexp
+
+# Who imports a module
+rg 'imports .* drive/modules/commons/result' .belief_map.sexp
+
+# What does a module import
+rg 'imports drive/modules/drive_db/api' .belief_map.sexp
+
+# All references to an entity
+rg 'DriveDbCommitResponse' .belief_map.sexp
+
+# All classes in a repo
+rg '^\(cls drive/' .belief_map.sexp
+
+# Data flow edges
+rg 'data-flow' .belief_map.sexp
+```
+
+These one-liners are useful for quick checks. For structured output and full analysis, use the Python script commands.
+
+## Output Notation
+
+All output is S-expression facts, one per line. See [references/sexp-notation.md](references/sexp-notation.md) for the full format.
+
+Key patterns:
+```scheme
+(boundary <mod> :lang py :file <path> :purpose "<desc>")
+(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
+(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
+(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
+(entity-def cls <mod> <Name> <line> :lang py :file <path>)
+(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
+(result <module-or-path>)
+(result-count 42)
+```
+
+**`:lang` values**: `py` = Python (snake_case), `ts` = TypeScript (camelCase), `tsx` = TSX (PascalCase).
+
+## Scheme Query Language
+
+Compose queries for complex analysis. See [references/scheme-queries.md](references/scheme-queries.md) for full reference.
+
+**Essentials:**
+```scheme
+(boundary "id")                ; target + deps + rdeps (change boundary)
+(entity "Name")                ; modules defining entity
+(deps "id" depth)              ; outgoing dependencies
+(rdeps "id" depth)             ; reverse dependencies
+(find-function "name")         ; modules with matching function defs
+(find-type "name")             ; modules with matching type defs
+(find-callers "fn" depth)      ; modules calling a function
+(find-calls "fn" depth)        ; modules a function calls
+(intersect A B)                ; set intersection
+(filter SET "pattern")         ; regex filter
+(files SET)                    ; resolve to file paths
+(count SET)                    ; count members
+(violations)                   ; modules with boundary violations
+(layer "id")                   ; architecture layer of a module
+```
+
+## Analysis Plan Pattern
+
+Before modifying code, compose a plan from queries:
+
+```scheme
+; 1. Scope
+(boundary "operatives.service")
+(count (boundary "operatives.service"))
+
+; 2. Architecture constraints
+(violations "operatives.service")
+(layer "operatives.service")
+
+; 3. Cross-language boundaries
+(filter (refs-to "DrivePath") "app-service")
+
+; 4. Narrow to actionable files
+(filter (boundary "operatives.service") "dto")
+(intersect (deps "controller" 2) (deps "service" 2))
+
+; 5. After changes: verify
+(violations "operatives.service")
+```
+
+## Trigger Examples
+
+Use this skill before reading source for:
+
+- Root-cause investigations that mention services, APIs, jobs, events, UI flows, or failing behavior.
+- Cross-service or cross-module questions, including "how does X call Y?" and "where is this stored?"
+- Redmine clarification when the answer depends on code behavior.
+- Architecture reviews, impact analysis, public contract changes, or blast-radius checks.
+- Reviews of non-trivial staged changes when dependency direction or module ownership matters.
+
+Do not force it for commit-only tasks, git-log summaries, manual demo/server runs, pure browser testing, or session-log analysis.
+
+## Error Recovery
+
+If a command returns `(error no-match ...)`:
+1. Do NOT retry with the same ID or guess another ID
+2. Run `search` with a broader keyword to find the correct module ID
+3. Use the `:suggestions` field if present -- it lists similar module IDs
+
+```bash
+# Wrong: guessing IDs
+python3 scripts/belief_search.py analyze ps34        # fails: ps34 is a short path-map ID
+python3 scripts/belief_search.py analyze ca.service  # fails: incomplete path
+
+# Right: search first, then use the full path from results
+python3 scripts/belief_search.py search "ca.*service"
+# Output shows: pki-service/src/modules/ca/ca.service
+python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service
+```
+
+## Anti-patterns
+
+- **Guessing module IDs.** Module IDs are full relative paths (e.g., `pki-service/src/modules/ca/ca.service`). Short codes like `ps34` are internal path-map IDs and must not be used directly. Always `search` first.
+- **Build but never query.** Building the belief map and then never running `search`, `analyze`, or `boundary` provides zero value.
+- **Querying after reading source.** The first source-code read should come from `boundary-file` lines in `analyze` output.
+- **Reading `.belief_map.sexp` as a whole file.** Use `search`, `analyze`, or `rg` to query specific facts.
+- **Skipping the belief map for cross-module tasks.** Always query the graph to understand boundaries before reading source files.
+- **Reading all files in a directory.** When the boundary shows 2-3 files, read only those.
+- **Using project-local scripts.** Always use this skill's bundled scripts. Project copies may output JSON instead of sexp.
+
+## Rebuilding the Graph
+
+```bash
+python3 scripts/build_belief_map.py          # incremental (~5s)
+python3 scripts/build_belief_map.py --full   # full rebuild (~30s)
+python3 scripts/build_belief_map.py ./drive  # single sub-repo
+python3 scripts/build_belief_map.py --lsp    # with LSP call hierarchy (~1-5min)
+```
+
+Rebuild after structural changes (add/remove files, change imports, add classes).
+
+## Infrastructure Topology
+
+Extract service topology from Kustomize, Helm, and Terraform files. This script requires `PyYAML` (`pip3 install pyyaml`).
+
+```bash
+python3 scripts/build_infra_topology.py                    # auto-detect all IaC
+python3 scripts/build_infra_topology.py --kustomize .      # kustomize only
+python3 scripts/build_infra_topology.py --helm ./charts    # helm charts only
+python3 scripts/build_infra_topology.py --terraform ./infra # terraform only
+python3 scripts/build_infra_topology.py --append .belief_map.sexp  # merge into graph
+```
+
+Emits `infra-node`, `k8s-depends`, `k8s-service`, `helm-depends`, `tf-depends`, and `infra-maps` edges. Query with:
+```bash
+rg 'infra-node' .belief_map.sexp                  # all services
+rg 'k8s-depends' .belief_map.sexp                 # service dependencies
+rg 'infra-node.*:component database' .belief_map.sexp  # all databases
+rg 'infra-maps.*app-service' .belief_map.sexp     # infra -> source code mapping
+```
diff --git a/references/scheme-queries.md b/references/scheme-queries.md
new file mode 100644
index 0000000..08517d2
--- /dev/null
+++ b/references/scheme-queries.md
@@ -0,0 +1,88 @@
+# Scheme Query Language Reference
+
+Use `query '<expr>'` for one-shot or `repl` for interactive mode.
+
+## Primitives (return module sets)
+
+```scheme
+(resolve "pattern")         ; find module IDs matching pattern (suffix > substring)
+(boundary "id")             ; target + imports + dependents (change boundary)
+(deps "id" depth)           ; outgoing dependencies (default depth 2)
+(rdeps "id" depth)          ; reverse dependencies (default depth 1)
+(imports "id")              ; direct import targets only
+(dependents "id")           ; direct dependents only
+(entity "Name")             ; modules defining an entity
+(refs-to "Name")            ; modules referencing an entity
+```
+
+## Set Operations
+
+```scheme
+(intersect A B)             ; set intersection
+(union A B ...)             ; set union (variadic)
+(diff A B)                  ; A minus B
+(filter SET "pattern")      ; keep members matching regex (case-insensitive)
+```
+
+## Boundary Analysis
+
+```scheme
+(layer "id")                ; architecture layer: domain/api/service/infra/shared/test/ui/config/other
+(layer-of SET "layer")      ; filter set to modules in a specific layer
+(violations)                ; all modules with boundary violations
+(violations "id")           ; violations for a specific module's scope
+```
+
+## Function & Type Search (return module-set)
+
+```scheme
+(find-function "name")      ; modules containing matching function definitions
+(find-type "name")          ; modules containing matching type/class/ifc/enum defs
+(find-callers "fn" depth)   ; modules that call a function (default depth 2)
+(find-calls "fn" depth)     ; modules that a function calls (default depth 2)
+(diff-functions "ref")      ; print changed functions (side-effect, returns empty)
+```
+
+## Output Transforms
+
+```scheme
+(files SET)                 ; resolve module IDs to file paths
+(count SET)                 ; count set members (returns int)
+(analyze "id")              ; run full analysis (prints sexp, returns empty set)
+(search "pattern")          ; grep .belief_map.sexp (prints matches, returns empty set)
+```
+
+## Composition Examples
+
+```scheme
+; Files shared between two modules
+(intersect (deps "controller" 2) (deps "service" 2))
+
+; Only DTOs in a boundary
+(filter (boundary "operatives.service") "dto")
+
+; How many files in the blast radius?
+(count (deps "drive_schema" 3))
+
+; Which TS modules reference a Python entity?
+(filter (refs-to "DrivePath") "app-service")
+
+; Domain modules that violate boundaries
+(violations "all")
+
+; Infra files in the boundary
+(layer-of (boundary "operatives.service") "infra")
+
+; Files to read (resolved paths)
+(files (filter (boundary "X") "service"))
+```
+
+## Result Format
+
+```scheme
+(result <module-or-path>)   ; one per set member
+(result-empty)              ; empty set
+(result-count 42)           ; from (count ...)
+```
+
+String results (from `layer`) print as `(result <value>)`.
diff --git a/references/sexp-notation.md b/references/sexp-notation.md
new file mode 100644
index 0000000..1f74f08
--- /dev/null
+++ b/references/sexp-notation.md
@@ -0,0 +1,176 @@
+# S-expression Output Notation
+
+Every output line is a self-contained fact. Each fact that references a module carries `:lang` (py/ts/tsx).
+
+**Module ID**: relative path from workspace root, no extension, no `/index`. Example: `drive/modules/drive_db/api/drive_db_api.ts` -> `drive/modules/drive_db/api/drive_db_api`.
+
+## Raw Graph Facts (in .belief_map.sexp)
+
+```scheme
+(node <id> <lang> "<purpose>" :naming <convention> :pkg <repo>)
+(fn <mod> <name> <line> :eid <uuid>)
+(cls <mod> <name> <line> :eid <uuid> (:bases A) (:deco D) (:methods m1 m2))
+(ifc <mod> <name> <line> :eid <uuid> (:methods m1 m2))
+(typ <mod> <name> <line> :eid <uuid>)
+(enm <mod> <name> <line> :eid <uuid>)
+(imports <src> <tgt> [:via-base] [:lsp])
+(calls-api <src> <tgt> :via-ifc [:lsp])
+(data-flow <src> <tgt> [:validated])
+(refs <src> <tgt>::<Entity> [:lsp])
+(calls <src>::<fn> <tgt>::<fn> :lines L1 L2 :lsp)
+```
+
+## boundary Output
+
+```scheme
+(boundary <mod> :lang py :file <path> :purpose "<desc>")
+(cls <mod> <Name> <line> :lang py (:bases A) (:deco D) (:methods m1 m2))
+(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
+(boundary-rdep <mod> <rdep> :lang py :file <path> :relation imports)
+(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
+```
+
+## analyze Output
+
+```scheme
+(analyze <mod> :lang py "<purpose>" :file <path>)
+(cls <mod> <Name> <line> :lang py (:bases A) (:deco D) (:methods m1 m2))
+(analyze-import <mod> <tgt> :lang ts :file <path>)
+(analyze-dataflow <mod> <tgt> :lang py :validated)
+(refs <src> <tgt>::<Entity>)
+(analyze-dependent <mod> <src> :lang tsx :via imports refs :file <path>)
+(dep <root> <tgt> :lang py :via imports :depth 1)
+(rdep <root> <src> :lang tsx :via imports :depth 1)
+(key-entity <mod> <Name> :lang py :kind cls :line 32 :refs 7 :modules 4)
+(key-entity-ref <Name> <ref-mod> :lang ts)
+(boundary-file <mod> <file-path>)
+(layer <mod> <dep-name> :layer domain)
+(analyze-summary <mod> :entities 31 :imports 1 :dataflows 0 :refs 1 :dependents 50 :boundary-files 52)
+```
+
+## entity Output
+
+```scheme
+(entity-def cls <mod> <Name> <line> :lang py :file <path>)
+(entity-def ifc <mod> <Name> <line> :lang ts :file <path>)
+(refs <src-mod> <tgt-mod>::<Name>)
+```
+
+## deps / rdeps Output
+
+```scheme
+(deps-root <mod> :lang py)
+(dep <root> <tgt> :lang ts :via imports :depth 1)
+(dep <root> <tgt> :lang py :via data-flow :depth 2 :cycle)
+(rdeps-root <mod> :lang ts)
+(rdep <root> <src> :lang tsx :via imports :depth 1)
+```
+
+## flow Output
+
+```scheme
+(flow <src>::<fn> <tgt>::<fn> :lang py :via calls :depth 0)
+(flow <src>::<fn> <tgt> :lang ts :via imports :depth 1 :module-level)
+```
+
+## boundaries Output
+
+```scheme
+(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
+(boundaries-summary :violations 2 :checked 3587)
+(boundaries-ok :checked 3587)
+```
+
+## invariants Output
+
+```scheme
+(invariant-violation <mod> :expected snake_case :actual PascalCase :lang py :pkg <repo>)
+(invariants-summary :violations 12 :checked 3587)
+(invariants-ok :checked 3587)
+```
+
+## layers Output
+
+```scheme
+(layer-group api :count 144)
+(layer-member api <mod> :lang ts)
+```
+
+## find_function / find_type Output
+
+```scheme
+(fn-def <mod>::<name> :line 42 :lang ts :file <path> :kind function)
+(fn-def <mod>::<cls>.<method> :line 42 :lang py :file <path> :kind method)
+(type-def cls <mod>::<Name> :line 10 :lang ts :file <path> (:bases A) (:methods m1 m2))
+(type-def ifc <mod>::<Name> :line 10 :lang ts :file <path>)
+```
+
+## find_callers / find_calls Output
+
+```scheme
+(callers-target <mod>::<fn> :line 42 :lang ts :file <path>)
+(caller <src>::<fn> -> <tgt>::<fn> :lang ts :file <path> :lines L1 L2 :lsp)
+(caller-module <src> -> <tgt> :via imports :depth 1 :lang ts :file <path>)
+(calls-source <mod>::<fn> :line 42 :lang ts :file <path>)
+(calls-target <src>::<fn> -> <tgt>::<fn> :lang ts :file <path>)
+(calls-module <src> -> <tgt> :via imports :depth 1 :lang ts :file <path>)
+```
+
+## find_callchain Output
+
+```scheme
+(callchain-step 0 <mod>::<fn> :lang ts :file <path>)
+(callchain-step 1 <mod>::<fn> :lang py :file <path>)
+(callchain-summary :length 3 :hops 2)
+(callchain-module-step 0 <mod> :lang ts :file <path>)
+(callchain-module-summary :length 2 :hops 1)
+(callchain-none "srcFn" -> "tgtFn" :max-depth 5)
+```
+
+## grep_functions Output
+
+```scheme
+(grep-fn <mod>::<fn> :line 55 :lang ts :file <path> :match "matched line text")
+(grep-functions-summary :matches 12 :pattern "pattern")
+(grep-functions-empty "pattern")
+```
+
+## diff_functions Output
+
+```scheme
+(diff-fn <mod>::<name> :kind fn :line 42 :lang ts :file <path>)
+(diff-functions-summary :changed 5 :files 3 :ref "HEAD")
+(diff-file <path> :hunks 2)
+(diff-functions-no-match :files 3 :ref "HEAD")
+(diff-functions-empty "HEAD")
+```
+
+## query / repl Output
+
+```scheme
+(result <module-or-path>)
+(result-empty)
+(result-count 42)
+```
+
+## :lang Values
+
+| Value | Language | Naming | Example |
+|---|---|---|---|
+| `py` | Python | snake_case fns, PascalCase classes | `drive_path_to_entry`, `DrivePath` |
+| `ts` | TypeScript | camelCase fns, PascalCase classes | `calculateTotal`, `OperativesService` |
+| `tsx` | TSX/React | PascalCase components, camelCase hooks | `FileBrowser`, `useQuery` |
+
+## Architecture Layers
+
+| Layer | Path patterns | Role |
+|---|---|---|
+| `domain` | `/domain/`, `/entities/`, `_schema` | Pure business logic |
+| `api` | `/api/`, `/routes/`, `/controllers/` | HTTP/RPC handlers |
+| `service` | `/services/`, `/application/` | Business orchestration |
+| `infra` | `/repositories/`, `/db/`, `/infra/` | Database, storage, messaging |
+| `shared` | `/commons/`, `/utils/`, `/types/` | Cross-cutting utilities |
+| `test` | `/tests/`, `.test.`, `.spec.` | Test files |
+| `ui` | `/components/`, `/pages/`, `/hooks/` | Frontend UI |
+| `config` | `/config/`, `/env/` | Configuration |
+| `other` | (no match) | Unclassified |
diff --git a/scripts/belief_search.py b/scripts/belief_search.py
new file mode 100644
index 0000000..2dd56ad
--- /dev/null
+++ b/scripts/belief_search.py
@@ -0,0 +1,2256 @@
+#!/usr/bin/env python3
+"""
+Belief Map Search -- query tool for S-expression belief maps.
+
+Reads ``.belief_map.sexp`` and provides structured queries: module views,
+dependency trees, reverse dependency analysis, entity lookups, data flow
+tracing, and boundary discovery for minimal context loading.
+
+Output is S-expression facts (one per line, greppable).
+
+Usage::
+
+    belief_search.py analyze <id>           Full analysis in one step
+    belief_search.py boundary <id>          File paths for change boundary
+    belief_search.py quick <keyword>        Search + analyze in one step
+    belief_search.py module <id>            Show module with entities and edges
+    belief_search.py deps <id> [depth]      Outgoing dependency tree (default depth 2)
+    belief_search.py rdeps <id> [depth]     Reverse dependency tree (default depth 2)
+    belief_search.py entity <name>          Find entity: definition + all usages
+    belief_search.py flow <id> <entity>     Trace data/call flow from entity
+    belief_search.py search <pattern>       Regex search across all facts
+    belief_search.py invariants [scope]     Check naming-convention violations (default: all)
+    belief_search.py find_function <name>   Find function/method definitions by name
+    belief_search.py find_type <name>       Find type/class/interface/enum definitions by name
+    belief_search.py find_callchain <src_fn> <tgt_fn> [depth]  Trace call path between two functions
+    belief_search.py find_callers <fn_name> [depth]  Who calls this function (incoming calls)
+    belief_search.py find_calls <fn_name> [depth]    What does this function call (outgoing calls)
+    belief_search.py grep_functions <pattern>         Search function bodies in source files
+    belief_search.py diff_functions [ref]             Identify changed functions in git diff (default: HEAD)
+    belief_search.py query <scheme-expr>    Evaluate a Scheme query expression
+    belief_search.py repl                   Interactive Scheme REPL
+
+Scheme query examples::
+
+    belief_search.py query '(boundary "operatives.controller")'
+    belief_search.py query '(files (intersect (deps "A" 2) (rdeps "B" 1)))'
+    belief_search.py query '(filter (boundary "operatives.service") "dto")'
+    belief_search.py query '(count (deps "operatives.service" 3))'
+
+CLI examples::
+
+    belief_search.py analyze drive/tools/drive_vsearch
+    belief_search.py boundary operatives.service
+    belief_search.py entity DriveDbCommitResponse
+    belief_search.py deps drive/modules/drive_db/services/database_service 3
+    belief_search.py find_function createOrder
+    belief_search.py find_type DriveDbCommitResponse
+    belief_search.py find_callchain createOrder processPayment
+    belief_search.py find_callers handleRequest 3
+    belief_search.py find_calls createOrder 2
+    belief_search.py grep_functions "validate.*input"
+    belief_search.py diff_functions HEAD~3
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Node:
+    nid: str
+    lang: str
+    purpose: str
+    naming: str = ""   # snake_case, camelCase, PascalCase, kebab-case, mixed
+    pkg: str = ""      # repository/package name
+
+
+@dataclass
+class EntityFact:
+    module: str
+    name: str
+    kind: str  # fn, cls, ifc, typ, enm
+    line: int
+    bases: list[str] = field(default_factory=list)
+    deco: list[str] = field(default_factory=list)
+    methods: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Edge:
+    etype: str   # imports, calls-api, data-flow, refs, calls
+    source: str
+    target: str
+    flags: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# S-expression line parser
+# ---------------------------------------------------------------------------
+
+def tokenize(line: str) -> list[str]:
+    """Tokenize a single-line S-expression into a flat list of tokens."""
+    line = line.strip()
+    if not line or line.startswith(";"):
+        return []
+    if not line.startswith("(") or not line.endswith(")"):
+        return []
+    inner = line[1:-1]
+    tokens: list[str] = []
+    i = 0
+    while i < len(inner):
+        ch = inner[i]
+        if ch == " ":
+            i += 1
+        elif ch == '"':
+            j = i + 1
+            while j < len(inner):
+                if inner[j] == "\\" and j + 1 < len(inner):
+                    j += 2
+                elif inner[j] == '"':
+                    break
+                else:
+                    j += 1
+            tokens.append(inner[i + 1 : j].replace('\\"', '"').replace("\\\\", "\\"))
+            i = j + 1
+        elif ch == "(":
+            depth = 1
+            j = i + 1
+            while j < len(inner) and depth > 0:
+                if inner[j] == "(":
+                    depth += 1
+                elif inner[j] == ")":
+                    depth -= 1
+                j += 1
+            tokens.append(inner[i:j])
+            i = j
+        else:
+            j = i
+            while j < len(inner) and inner[j] not in (" ", ")"):
+                j += 1
+            tokens.append(inner[i:j])
+            i = j
+    return tokens
+
+
+def parse_sub_list(token: str) -> list[str]:
+    """Parse a (:key a b c) token into ['a', 'b', 'c']."""
+    if token.startswith("(") and token.endswith(")"):
+        parts = token[1:-1].split()
+        return [p for p in parts if not p.startswith(":")]
+    return []
+
+
+# ---------------------------------------------------------------------------
+# S-expression output helpers
+# ---------------------------------------------------------------------------
+
+def _q(s: str) -> str:
+    """Quote a string for S-expression output if it contains spaces."""
+    if " " in s or '"' in s:
+        return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return s
+
+
+def _sexp_list(tag: str, items: list[str]) -> str:
+    """Format a tagged list: (:tag a b c)."""
+    if not items:
+        return ""
+    return f"(:{tag} {' '.join(items)})"
+
+
+# ---------------------------------------------------------------------------
+# No-match error helper
+# ---------------------------------------------------------------------------
+
+def _print_no_match(g: BeliefGraph, pattern: str) -> None:
+    """Print a structured no-match error with fuzzy suggestions."""
+    suggestions = BeliefGraph._suggest_similar(pattern, g.nodes)
+    if suggestions:
+        sug_str = " ".join(suggestions)
+        print(f"(error no-match {_q(pattern)} :suggestions {sug_str})")
+    else:
+        print(f"(error no-match {_q(pattern)})")
+
+
+# ---------------------------------------------------------------------------
+# File-path resolution helpers
+# ---------------------------------------------------------------------------
+
+_TS_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx")
+_PY_EXTENSIONS = (".py",)
+
+
+def _module_id_to_file(module_id: str, root: str) -> str:
+    """Convert a module ID back to a file path relative to root."""
+    base = os.path.join(root, module_id)
+    for ext in _TS_EXTENSIONS + _PY_EXTENSIONS:
+        candidate = base + ext
+        if os.path.isfile(candidate):
+            return candidate
+    for idx in ("index.ts", "index.tsx", "index.js", "__init__.py"):
+        candidate = os.path.join(base, idx)
+        if os.path.isfile(candidate):
+            return candidate
+    return module_id
+
+
+# ---------------------------------------------------------------------------
+# Graph loader
+# ---------------------------------------------------------------------------
+
+class BeliefGraph:
+    """In-memory belief map graph built from S-expression facts."""
+
+    def __init__(self) -> None:
+        self.nodes: dict[str, Node] = {}
+        self.entities: dict[str, list[EntityFact]] = {}  # module -> entities
+        self.entity_by_name: dict[str, list[EntityFact]] = {}  # name -> entities
+        self.edges_from: dict[str, list[Edge]] = {}  # source module -> edges
+        self.edges_to: dict[str, list[Edge]] = {}  # target module -> edges
+        self.edges_from_entity: dict[str, list[Edge]] = {}  # entity-qualified source -> edges
+        self.edges_by_entity_name: dict[str, list[Edge]] = {}  # entity name -> edges
+        self.all_edges: list[Edge] = []
+        self.pmap: dict[str, str] = {}
+        self._root: str = ""
+
+    def load(self, path: str) -> None:
+        self._root = os.path.dirname(os.path.dirname(os.path.abspath(path)))
+        pmap: dict[str, str] = {}
+
+        in_paths = False
+        path_stack: list[str] = []
+
+        with open(path, "r") as f:
+            for line in f:
+                stripped = line.strip()
+                if not stripped or stripped.startswith(";"):
+                    continue
+
+                if stripped == "(paths":
+                    in_paths = True
+                    path_stack = []
+                    continue
+
+                if in_paths:
+                    if stripped == ")":
+                        if path_stack:
+                            path_stack.pop()
+                        else:
+                            in_paths = False
+                        continue
+
+                    tokens = tokenize(stripped)
+                    if not tokens:
+                        inner = stripped.lstrip("(").rstrip()
+                        if inner:
+                            path_stack.append(inner)
+                        continue
+
+                    if len(tokens) == 2 and not tokens[0].startswith(":"):
+                        sid, leaf = tokens[0], tokens[1]
+                        if leaf == ":self":
+                            # Directory-as-module (index.ts stripped to dir name)
+                            full = "/".join(path_stack) if path_stack else sid
+                            pmap[sid] = full
+                        else:
+                            full = "/".join(path_stack + [leaf]) if path_stack else leaf
+                            pmap[sid] = full
+                    elif len(tokens) == 1:
+                        path_stack.append(tokens[0])
+                    continue
+
+                tokens = tokenize(stripped)
+                if tokens and tokens[0] == "def" and len(tokens) >= 3:
+                    pmap[tokens[1]] = tokens[2]
+
+        self.pmap = pmap
+
+        def _resolve(sid: str) -> str:
+            if "::" in sid:
+                mod, ent = sid.split("::", 1)
+                return f"{pmap.get(mod, mod)}::{ent}"
+            return pmap.get(sid, sid)
+
+        with open(path, "r") as f:
+            for line in f:
+                tokens = tokenize(line)
+                if not tokens:
+                    continue
+                kind = tokens[0]
+
+                if kind in ("paths", "def", ")"):
+                    continue
+
+                if kind == "node" and len(tokens) >= 4:
+                    nid = _resolve(tokens[1])
+                    lang, purpose = tokens[2], tokens[3]
+                    naming, pkg = "", ""
+                    rest = tokens[4:]
+                    for i, t in enumerate(rest):
+                        if t == ":naming" and i + 1 < len(rest):
+                            naming = rest[i + 1]
+                        elif t == ":pkg" and i + 1 < len(rest):
+                            pkg = rest[i + 1]
+                    self.nodes[nid] = Node(nid, lang, purpose, naming, pkg)
+
+                elif kind in ("fn", "cls", "ifc", "typ", "enm") and len(tokens) >= 4:
+                    module = _resolve(tokens[1])
+                    name = tokens[2]
+                    line_num = int(tokens[3]) if tokens[3].isdigit() else 0
+                    bases, deco, methods = [], [], []
+                    for t in tokens[4:]:
+                        if t.startswith("(:bases"):
+                            bases = parse_sub_list(t)
+                        elif t.startswith("(:deco"):
+                            deco = parse_sub_list(t)
+                        elif t.startswith("(:methods"):
+                            methods = parse_sub_list(t)
+                    ent = EntityFact(module, name, kind, line_num, bases, deco, methods)
+                    self.entities.setdefault(module, []).append(ent)
+                    self.entity_by_name.setdefault(name, []).append(ent)
+
+                elif kind in ("imports", "calls-api", "data-flow", "refs", "calls", "http-calls") and len(tokens) >= 3:
+                    source = _resolve(tokens[1])
+                    target = _resolve(tokens[2])
+                    flags = [t for t in tokens[3:] if t.startswith(":")]
+                    edge = Edge(kind, source, target, flags)
+                    self.all_edges.append(edge)
+                    src_mod = source.split("::")[0]
+                    tgt_mod = target.split("::")[0]
+                    self.edges_from.setdefault(src_mod, []).append(edge)
+                    self.edges_to.setdefault(tgt_mod, []).append(edge)
+                    self.edges_from_entity.setdefault(source, []).append(edge)
+                    for part in (source, target):
+                        if "::" in part:
+                            ent_name = part.split("::", 1)[1]
+                            self.edges_by_entity_name.setdefault(ent_name, []).append(edge)
+
+                elif kind == "violation" and len(tokens) >= 5:
+                    source = _resolve(tokens[2])
+                    target = _resolve(tokens[3])
+                    edge = Edge("violation", source, target, [f":rule={tokens[1]}"])
+                    self.all_edges.append(edge)
+
+    def resolve_alias(self, module_id: str) -> str:
+        """Resolve an internal path-map alias to a module ID when possible."""
+        if "::" in module_id:
+            mod, ent = module_id.split("::", 1)
+            return f"{self.pmap.get(mod, mod)}::{ent}"
+        return self.pmap.get(module_id, module_id)
+
+    def resolve_module(self, pattern: str) -> list[str]:
+        """Find module IDs: exact > suffix > substring > case-insensitive substring.
+
+        Returns an empty list when nothing matches (caller should use
+        _print_no_match to report the failure with suggestions).
+        """
+        resolved_pattern = self.resolve_alias(pattern)
+        if resolved_pattern in self.nodes:
+            return [resolved_pattern]
+        if pattern in self.nodes:
+            return [pattern]
+        suffix_matches = [nid for nid in self.nodes if nid.endswith("/" + pattern) or nid.endswith(pattern)]
+        if suffix_matches:
+            return sorted(suffix_matches)
+        sub_matches = [nid for nid in self.nodes if pattern in nid]
+        if sub_matches:
+            if len(sub_matches) > 10:
+                print(f"; warning: '{pattern}' matches {len(sub_matches)} modules, showing first 10", file=sys.stderr)
+                return sorted(sub_matches)[:10]
+            return sorted(sub_matches)
+        # Case-insensitive substring fallback
+        lp = pattern.lower()
+        ci_matches = [nid for nid in self.nodes if lp in nid.lower()]
+        if ci_matches:
+            if len(ci_matches) > 10:
+                print(f"; warning: '{pattern}' (case-insensitive) matches {len(ci_matches)} modules, showing first 10", file=sys.stderr)
+                return sorted(ci_matches)[:10]
+            return sorted(ci_matches)
+        return []
+
+    def search_modules(self, pattern: str) -> list[str]:
+        """Find module IDs whose path or basename matches the regex pattern."""
+        regex = re.compile(pattern, re.IGNORECASE)
+        matches = [
+            nid for nid in self.nodes
+            if regex.search(nid) or regex.search(nid.rsplit("/", 1)[-1])
+        ]
+        return sorted(matches)
+
+    @staticmethod
+    def _suggest_similar(pattern: str, nodes: "dict[str, Node]", max_results: int = 5) -> list[str]:
+        """Return up to max_results node IDs whose path segments overlap with pattern.
+
+        Splits pattern by '/', '.', '_', '-' and counts how many parts appear
+        (case-insensitively) in each candidate node ID.  Returns the top N
+        nodes with at least one matching part, sorted by match count descending.
+        """
+        import re as _re
+        parts = [p for p in _re.split(r"[/._-]", pattern.lower()) if p]
+        if not parts:
+            return []
+        scored: list[tuple[int, str]] = []
+        for nid in nodes:
+            nid_lower = nid.lower()
+            count = sum(1 for p in parts if p in nid_lower)
+            if count > 0:
+                scored.append((count, nid))
+        scored.sort(key=lambda x: (-x[0], x[1]))
+        return [nid for _, nid in scored[:max_results]]
+
+    def module_to_file(self, module_id: str) -> str:
+        """Resolve a module ID to a file path on disk."""
+        return _module_id_to_file(module_id, self._root)
+
+    def module_purpose(self, module_id: str) -> str:
+        """Return the purpose string of a module. Empty if unknown."""
+        node = self.nodes.get(module_id)
+        return node.purpose if node else ""
+
+    def module_lang(self, module_id: str) -> str:
+        """Return the language of a module ('py', 'ts', 'tsx'). Empty if unknown."""
+        node = self.nodes.get(module_id)
+        if not node:
+            return ""
+        # Normalize legacy 'ty' -> 'ts', 'tx' -> 'tsx'
+        return {"ty": "ts", "tx": "tsx"}.get(node.lang, node.lang)
+
+
+# ---------------------------------------------------------------------------
+# Shared tree collectors
+# ---------------------------------------------------------------------------
+
+def _collect_dep_mods(g: BeliefGraph, nid: str) -> dict[str, str]:
+    """Outgoing dependency modules (deduped): module -> edge_type."""
+    seen: dict[str, str] = {}
+    for e in g.edges_from.get(nid, []):
+        tgt_mod = e.target.split("::")[0]
+        if tgt_mod != nid and tgt_mod not in seen:
+            seen[tgt_mod] = e.etype
+    return seen
+
+
+def _collect_rdep_mods(g: BeliefGraph, nid: str) -> dict[str, str]:
+    """Incoming dependency modules (deduped): module -> edge_type."""
+    seen: dict[str, str] = {}
+    for e in g.edges_to.get(nid, []):
+        src_mod = e.source.split("::")[0]
+        if src_mod != nid and src_mod not in seen:
+            seen[src_mod] = e.etype
+    return seen
+
+
+def _walk_deps(
+    g: BeliefGraph, nid: str, visited: set[str], max_depth: int, depth: int,
+    emit: Callable[[int, str, str, bool], None],
+) -> None:
+    if depth > max_depth:
+        return
+    for tgt, etype in sorted(_collect_dep_mods(g, nid).items()):
+        cycle = tgt in visited
+        emit(depth, etype, tgt, cycle)
+        if not cycle:
+            visited.add(tgt)
+            _walk_deps(g, tgt, visited, max_depth, depth + 1, emit)
+
+
+def _walk_rdeps(
+    g: BeliefGraph, nid: str, visited: set[str], max_depth: int, depth: int,
+    emit: Callable[[int, str, str, bool], None],
+) -> None:
+    if depth > max_depth:
+        return
+    for src, etype in sorted(_collect_rdep_mods(g, nid).items()):
+        cycle = src in visited
+        emit(depth, etype, src, cycle)
+        if not cycle:
+            visited.add(src)
+            _walk_rdeps(g, src, visited, max_depth, depth + 1, emit)
+
+
+# ---------------------------------------------------------------------------
+# Layer classifier + boundary rules
+# ---------------------------------------------------------------------------
+
+def _classify_layer_fallback(p: str) -> str:
+    """Classify a module into an architecture layer from its path.
+
+    Order matters: test/config checked first (override other patterns).
+    NestJS conventions: guards/controllers are api, .module files are config,
+    /interface/ folders are shared contracts (not api).
+    """
+    # High-priority overrides (tests, config)
+    if "/tests/" in p or "/test_" in p or ".test." in p or ".spec." in p or "/e2e/" in p:
+        return "test"
+    if "/config/" in p or "/env/" in p:
+        return "config"
+    # NestJS .module files are wiring/config, not service
+    if ".module" in p and "/modules/" in p:
+        return "config"
+    # Interface folders are shared contracts, not api
+    if "/interface/" in p or "/interfaces/" in p:
+        return "shared"
+    # Architecture layers
+    if "/api/" in p or "/routes/" in p or "/controllers/" in p:
+        return "api"
+    if "/services/" in p or "/application/" in p:
+        return "service"
+    if "/domain/" in p or "/entities/" in p or "/schema" in p or "_schema" in p:
+        return "domain"
+    if "/repositories/" in p or "/db/" in p or "/infra/" in p or "/infrastructure/" in p or "rabbitmq" in p or "s3" in p:
+        return "infra"
+    if "/commons/" in p or "/common/" in p or "/utils/" in p or "/result" in p or "/types/" in p:
+        return "shared"
+    if "/components/" in p or "/pages/" in p or "/ui/" in p or "/hooks/" in p or "/stores/" in p:
+        return "ui"
+    # NestJS / backend patterns
+    if "/dto/" in p or "/dtos/" in p:
+        return "domain"
+    if "/guards/" in p or "/guard." in p:
+        return "api"
+    if "/middleware/" in p or "/middlewares/" in p or "/interceptors/" in p or "/pipes/" in p:
+        return "api"
+    if "/adapters/" in p or "/adapter." in p:
+        return "infra"
+    if "/gateways/" in p or "/gateway." in p:
+        return "infra"
+    if "/migrations/" in p or "/seeds/" in p or "/seeders/" in p:
+        return "infra"
+    # Domain patterns
+    if "/models/" in p or "/schemas/" in p or "/events/" in p or "/commands/" in p or "/queries/" in p:
+        return "domain"
+    if "/handlers/" in p:
+        return "service"
+    # Shared patterns
+    if "/lib/" in p or "/helpers/" in p or "/constants/" in p or "/decorators/" in p or "/mappers/" in p:
+        return "shared"
+    # UI patterns (state management tied to UI)
+    if ("/stores/" in p or "/store/" in p or "/contexts/" in p or "/providers/" in p) and "/ui/" in p:
+        return "ui"
+    # Test patterns
+    if "/fixtures/" in p or "/mocks/" in p or "/__mocks__/" in p or "/factories/" in p:
+        return "test"
+    # Config / tooling patterns
+    if "/scripts/" in p or "/tools/" in p or "/cli/" in p:
+        return "config"
+    return "other"
+
+
+_PURPOSE_TO_LAYER: dict[str, str] = {
+    # Domain layer
+    "domain logic": "domain",
+    "domain entity": "domain",
+    "data model": "domain",
+    "data transfer object": "domain",
+    "schema": "domain",
+    "enum definitions": "domain",
+    "policy": "domain",
+    "value object": "domain",
+    "aggregate root": "domain",
+    "domain event": "domain",
+    "Specification pattern": "domain",
+    # Infrastructure layer
+    "infrastructure adapter": "infra",
+    "database migration": "infra",
+    "database seed": "infra",
+    "repository": "infra",
+    "adapter": "infra",
+    "gateway": "infra",
+    "client": "infra",
+    "connector": "infra",
+    "scheduler": "infra",
+    "worker": "infra",
+    "Unit of Work": "infra",
+    "Identity Map": "infra",
+    "Proxy pattern": "infra",
+    "SDK": "infra",
+    "API client": "infra",
+    # API layer
+    "API layer": "api",
+    "API controller": "api",
+    "router": "api",
+    "access guard": "api",
+    "middleware": "api",
+    "interceptor": "api",
+    "validation pipe": "api",
+    "resolver": "api",
+    # Service layer
+    "service": "service",
+    "application service": "service",
+    "event handler": "service",
+    "handler": "service",
+    "event listener": "service",
+    "processor": "service",
+    "provider": "service",
+    "registry": "service",
+    "agent": "service",
+    "manager": "service",
+    "subscriber": "service",
+    "dispatcher": "service",
+    "emitter": "service",
+    "Facade pattern": "service",
+    "Mediator pattern": "service",
+    "Observer pattern": "service",
+    "Command pattern": "service",
+    "Chain of Responsibility": "service",
+    "Memento pattern": "service",
+    # Config layer
+    "NestJS wiring module": "config",
+    "NestJS injectable": "config",
+    "configuration": "config",
+    "application bootstrap": "config",
+    "module entry point": "config",
+    # UI layer
+    "UI component": "ui",
+    "page/route": "ui",
+    "React hook": "ui",
+    "state store": "ui",
+    # Test layer
+    "test": "test",
+    "test fixture": "test",
+    "test mock": "test",
+    # Shared layer
+    "shared utilities": "shared",
+    "utility helpers": "shared",
+    "constants": "shared",
+    "type definitions": "shared",
+    "interface definitions": "shared",
+    "decorator": "shared",
+    "data mapper": "shared",
+    "barrel re-exports": "shared",
+    "plugin": "shared",
+    "Factory pattern": "shared",
+    "Builder pattern": "shared",
+    "Strategy pattern": "shared",
+    "Singleton pattern": "shared",
+    "Composite pattern": "shared",
+    "Visitor pattern": "shared",
+    "Iterator pattern": "shared",
+    "Decorator pattern": "shared",
+}
+
+
+def _levenshtein(a: str, b: str) -> int:
+    """Compute Levenshtein edit distance between two strings."""
+    if len(a) < len(b):
+        return _levenshtein(b, a)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a):
+        curr = [i + 1]
+        for j, cb in enumerate(b):
+            curr.append(min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (ca != cb)))
+        prev = curr
+    return prev[-1]
+
+
+def _classify_layer_by_purpose(purpose: str) -> str:
+    """Classify layer from the module's purpose string using fuzzy matching.
+
+    Tries exact match, then substring, then Levenshtein distance on
+    individual words from the purpose against the keyword map.
+    """
+    if not purpose or purpose == "general module":
+        return "other"
+    pl = purpose.lower()
+    # 1. Exact match
+    for key, layer in _PURPOSE_TO_LAYER.items():
+        if key.lower() == pl:
+            return layer
+    # 2. Substring match
+    for key, layer in _PURPOSE_TO_LAYER.items():
+        if key.lower() in pl:
+            return layer
+    # 3. Fuzzy word match: split purpose into words, compare each word
+    #    against keywords from the map using Levenshtein distance.
+    #    Threshold: distance <= 2 for words >= 5 chars, <= 1 for shorter.
+    purpose_words = re.split(r"[\s;,/]+", pl)
+    best_layer = "other"
+    best_dist = 999
+    for key, layer in _PURPOSE_TO_LAYER.items():
+        key_words = key.lower().split()
+        for kw in key_words:
+            if len(kw) < 4:
+                continue  # skip short keywords (api, ui, dto) -- too ambiguous for fuzzy
+            threshold = 2 if len(kw) >= 5 else 1
+            for pw in purpose_words:
+                if len(pw) < 4:
+                    continue
+                dist = _levenshtein(pw, kw)
+                if dist <= threshold and dist < best_dist:
+                    best_dist = dist
+                    best_layer = layer
+    return best_layer
+
+
+def _classify_layer(module_path: str, purpose: str = "") -> str:
+    """Classify using path patterns first, fall back to purpose string."""
+    result = _classify_layer_fallback(module_path.lower())
+    if result == "other" and purpose:
+        result = _classify_layer_by_purpose(purpose)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Commands -- S-expression output (default)
+# ---------------------------------------------------------------------------
+
+def _entity_sexp(e: EntityFact, lang: str = "") -> str:
+    """Format an entity as an S-expression fact with :lang."""
+    parts = [e.kind, e.module, e.name, str(e.line)]
+    if lang:
+        parts.append(f":lang {lang}")
+    if e.bases:
+        parts.append(_sexp_list("bases", e.bases))
+    if e.deco:
+        parts.append(_sexp_list("deco", e.deco))
+    if e.methods:
+        parts.append(_sexp_list("methods", e.methods))
+    return f"({' '.join(parts)})"
+
+
+def _edge_sexp(e: Edge) -> str:
+    """Format an edge as an S-expression fact."""
+    flags = " " + " ".join(e.flags) if e.flags else ""
+    return f"({e.etype} {e.source} {e.target}{flags})"
+
+
+def cmd_module(g: BeliefGraph, module_id: str) -> None:
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    for nid in matches:
+        node = g.nodes[nid]
+        fpath = g.module_to_file(nid)
+        mod_lang = g.module_lang(nid)
+        print(f"(node {nid} :lang {mod_lang} {_q(node.purpose)} :file {_q(fpath)})")
+        for e in sorted(g.entities.get(nid, []), key=lambda x: x.line):
+            print(_entity_sexp(e, mod_lang))
+        for e in sorted(g.edges_from.get(nid, []), key=lambda x: (x.etype, x.target)):
+            print(_edge_sexp(e))
+        for e in sorted(g.edges_to.get(nid, []), key=lambda x: (x.etype, x.source)):
+            if e.source.split("::")[0] != nid:
+                print(_edge_sexp(e))
+
+
+def cmd_deps(g: BeliefGraph, module_id: str, max_depth: int) -> None:
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    for start in matches:
+        visited: set[str] = {start}
+        print(f"(deps-root {start} :lang {g.module_lang(start)})")
+        _walk_deps(g, start, visited, max_depth, 1,
+                   lambda d, et, tgt, cyc: print(f"(dep {start} {tgt} :lang {g.module_lang(tgt)} :via {et} :depth {d}{' :cycle' if cyc else ''})"))
+
+
+def cmd_rdeps(g: BeliefGraph, module_id: str, max_depth: int) -> None:
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    for start in matches:
+        visited: set[str] = {start}
+        print(f"(rdeps-root {start} :lang {g.module_lang(start)})")
+        _walk_rdeps(g, start, visited, max_depth, 1,
+                    lambda d, et, src, cyc: print(f"(rdep {start} {src} :lang {g.module_lang(src)} :via {et} :depth {d}{' :cycle' if cyc else ''})"))
+
+
+def cmd_entity(g: BeliefGraph, name: str) -> None:
+    # Always try exact match first, then regex fallback
+    definitions: list[EntityFact] = []
+    if name in g.entity_by_name:
+        definitions = g.entity_by_name[name]
+    else:
+        pattern = re.compile(name, re.IGNORECASE)
+        for ename, ents in g.entity_by_name.items():
+            if pattern.search(ename):
+                definitions.extend(ents)
+
+    if not definitions:
+        _print_no_match(g, name)
+        return
+
+    # Collect refs via index
+    matched_names: set[str] = {d.name for d in definitions}
+    seen_edge_ids: set[int] = set()
+    unique_refs: list[Edge] = []
+    for ent_name in matched_names:
+        for e in g.edges_by_entity_name.get(ent_name, []):
+            eid = id(e)
+            if eid not in seen_edge_ids:
+                seen_edge_ids.add(eid)
+                unique_refs.append(e)
+
+    for defn in definitions:
+        print(f"(entity-def {defn.kind} {defn.module} {defn.name} {defn.line} :lang {g.module_lang(defn.module)} :file {_q(g.module_to_file(defn.module))})")
+    for e in sorted(unique_refs, key=lambda x: (x.etype, x.source)):
+        print(_edge_sexp(e))
+
+
+def cmd_flow(g: BeliefGraph, module_id: str, entity_name: str) -> None:
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    start_mod = matches[0]
+    full_id = f"{start_mod}::{entity_name}"
+
+    visited: set[str] = set()
+    _trace_flow(g, full_id, visited, 0)
+
+
+def _trace_flow(
+    g: BeliefGraph, entity_id: str, visited: set[str], depth: int,
+) -> None:
+    if entity_id in visited or depth > 5:
+        return
+    visited.add(entity_id)
+
+    # Entity-level edges via index
+    for edge in g.edges_from_entity.get(entity_id, []):
+        tgt_lang = g.module_lang(edge.target.split("::")[0])
+        print(f"(flow {entity_id} {edge.target} :lang {tgt_lang} :via {edge.etype} :depth {depth})")
+        _trace_flow(g, edge.target, visited, depth + 1)
+
+    # Module-level edges for cross-module flow
+    mod = entity_id.split("::")[0] if "::" in entity_id else entity_id
+    if "::" in entity_id:
+        for edge in g.edges_from.get(mod, []):
+            if "::" in edge.source:
+                continue
+            tgt_mod = edge.target.split("::")[0]
+            if tgt_mod not in visited:
+                print(f"(flow {entity_id} {edge.target} :lang {g.module_lang(tgt_mod)} :via {edge.etype} :depth {depth} :module-level)")
+                _trace_flow(g, edge.target, visited, depth + 1)
+
+
+def cmd_boundary(g: BeliefGraph, module_id: str, files_only: bool = False) -> None:
+    """Output the minimal set of files for a change boundary.
+
+    When files_only is True, emit one bare file path per line instead of sexp.
+    """
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    nid = matches[0]
+    node = g.nodes.get(nid)
+    if not node:
+        print(f"(error no-node {_q(nid)})")
+        return
+
+    target_file = g.module_to_file(nid)
+    import_mods = _collect_dep_mods(g, nid)
+    dependent_mods = _collect_rdep_mods(g, nid)
+    ents = g.entities.get(nid, [])
+
+    if files_only:
+        # Compact output: one file path per line, no sexp wrapping.
+        seen: set[str] = set()
+        for path in [target_file] + [g.module_to_file(m) for m in sorted(import_mods)] + [g.module_to_file(m) for m in sorted(dependent_mods)]:
+            if path not in seen:
+                seen.add(path)
+                print(path)
+        return
+
+    lang = g.module_lang(nid)
+    print(f"(boundary {nid} :lang {lang} :file {_q(target_file)} :purpose {_q(node.purpose)})")
+    for e in sorted(ents, key=lambda x: x.line):
+        print(_entity_sexp(e, lang))
+    for mod, etype in sorted(import_mods.items()):
+        print(f"(boundary-dep {nid} {mod} :lang {g.module_lang(mod)} :file {_q(g.module_to_file(mod))} :relation {etype})")
+    for mod, etype in sorted(dependent_mods.items()):
+        print(f"(boundary-rdep {nid} {mod} :lang {g.module_lang(mod)} :file {_q(g.module_to_file(mod))} :relation {etype})")
+    print(f"(boundary-summary {nid} :total {1 + len(import_mods) + len(dependent_mods)} :deps {len(import_mods)} :rdeps {len(dependent_mods)})")
+
+
+def cmd_analyze(g: BeliefGraph, module_id: str) -> None:
+    """Full architectural analysis of a module."""
+    matches = g.resolve_module(module_id)
+    if not matches:
+        _print_no_match(g, module_id)
+        return
+
+    nid = matches[0]
+    node = g.nodes.get(nid)
+    if not node:
+        print(f"(error no-node {_q(nid)})")
+        return
+
+    target_file = g.module_to_file(nid)
+    ents = g.entities.get(nid, [])
+    out_edges = g.edges_from.get(nid, [])
+    in_edges = g.edges_to.get(nid, [])
+
+    # Classify outgoing edges
+    import_targets: list[str] = []
+    ref_targets: list[tuple[str, str]] = []
+    data_flow_targets: list[str] = []
+    call_targets: list[tuple[str, str]] = []
+    for e in out_edges:
+        tgt_mod = e.target.split("::")[0]
+        if e.etype == "imports" and tgt_mod not in import_targets:
+            import_targets.append(tgt_mod)
+        elif e.etype == "refs":
+            ref_targets.append((e.source, e.target))
+        elif e.etype == "data-flow" and tgt_mod not in data_flow_targets:
+            data_flow_targets.append(tgt_mod)
+        elif e.etype == "calls":
+            call_targets.append((e.source, e.target))
+
+    # Classify incoming edges
+    importers: set[str] = set()
+    referencers: set[str] = set()
+    for e in in_edges:
+        src_mod = e.source.split("::")[0]
+        if src_mod == nid:
+            continue
+        if e.etype == "imports":
+            importers.add(src_mod)
+        else:
+            referencers.add(src_mod)
+
+    # Key entities cross-repo usage (indexed)
+    exported_types = [e for e in ents if e.kind in ("cls", "ifc", "typ") and not e.name.startswith("_")]
+    key_entity_usage: list[tuple[EntityFact, int, set[str]]] = []
+    for et in exported_types:
+        edges_for_name = g.edges_by_entity_name.get(et.name, [])
+        ref_mods: set[str] = set()
+        ref_count = 0
+        for e in edges_for_name:
+            src_mod = e.source.split("::")[0]
+            if src_mod != nid:
+                ref_count += 1
+                ref_mods.add(src_mod)
+        if ref_count > 0:
+            key_entity_usage.append((et, ref_count, ref_mods))
+
+    # Boundary files
+    boundary_files: list[str] = [target_file]
+    for t in sorted(import_targets):
+        f = g.module_to_file(t)
+        if f not in boundary_files:
+            boundary_files.append(f)
+    for src in sorted(importers | referencers):
+        f = g.module_to_file(src)
+        if f not in boundary_files:
+            boundary_files.append(f)
+
+    _analyze_sexp(g, nid, node, target_file, ents, import_targets,
+                  ref_targets, data_flow_targets, call_targets,
+                  importers, referencers, key_entity_usage,
+                  boundary_files)
+
+
+def _analyze_sexp(
+    g: BeliefGraph, nid: str, node: Node, target_file: str,
+    ents: list[EntityFact],
+    import_targets: list[str], ref_targets: list[tuple[str, str]],
+    data_flow_targets: list[str], call_targets: list[tuple[str, str]],
+    importers: set[str], referencers: set[str],
+    key_entity_usage: list[tuple[EntityFact, int, set[str]]],
+    boundary_files: list[str],
+) -> None:
+    # Module header
+    lang = g.module_lang(nid)
+    print(f"(analyze {nid} :lang {lang} {_q(node.purpose)} :file {_q(target_file)})")
+
+    # Entities
+    for e in sorted(ents, key=lambda x: x.line):
+        print(_entity_sexp(e, lang))
+
+    # Imports
+    for t in sorted(import_targets):
+        print(f"(analyze-import {nid} {t} :lang {g.module_lang(t)} :file {_q(g.module_to_file(t))})")
+
+    # Data flows
+    for t in sorted(data_flow_targets):
+        print(f"(analyze-dataflow {nid} {t} :lang {g.module_lang(t)} :validated)")
+
+    # Entity refs
+    for src, tgt in sorted(ref_targets):
+        print(f"(refs {src} {tgt})")
+
+    # Call edges
+    for src, tgt in sorted(call_targets):
+        print(f"(calls {src} {tgt})")
+
+    # Dependents
+    all_dependents = importers | referencers
+    for src in sorted(all_dependents):
+        kinds = []
+        if src in importers:
+            kinds.append("imports")
+        if src in referencers:
+            kinds.append("refs")
+        print(f"(analyze-dependent {nid} {src} :lang {g.module_lang(src)} :via {' '.join(kinds)} :file {_q(g.module_to_file(src))})")
+
+    # Dependency tree (depth 2)
+    visited: set[str] = {nid}
+    _walk_deps(g, nid, visited, 2, 1,
+               lambda d, et, tgt, cyc: print(f"(dep {nid} {tgt} :lang {g.module_lang(tgt)} :via {et} :depth {d}{' :cycle' if cyc else ''})"))
+
+    # Reverse deps (depth 1)
+    visited_r: set[str] = {nid}
+    _walk_rdeps(g, nid, visited_r, 1, 1,
+                lambda d, et, src, cyc: print(f"(rdep {nid} {src} :lang {g.module_lang(src)} :via {et} :depth {d}{' :cycle' if cyc else ''})"))
+
+    # Key entities
+    for et, ref_count, ref_mods in key_entity_usage:
+        print(f"(key-entity {nid} {et.name} :lang {lang} :kind {et.kind} :line {et.line} :refs {ref_count} :modules {len(ref_mods)})")
+        for rm in sorted(ref_mods):
+            print(f"(key-entity-ref {et.name} {rm} :lang {g.module_lang(rm)})")
+
+    # Boundary files
+    for f in boundary_files:
+        print(f"(boundary-file {nid} {_q(f)})")
+
+    # Architecture layers
+    for t in sorted(import_targets):
+        layer = _classify_layer(t, g.module_purpose(t))
+        print(f"(layer {nid} {t.split('/')[-1]} :layer {layer})")
+
+    # Summary
+    print(f"(analyze-summary {nid} :entities {len(ents)} :imports {len(import_targets)} :dataflows {len(data_flow_targets)} :refs {len(ref_targets)} :dependents {len(all_dependents)} :boundary-files {len(boundary_files)})")
+
+
+def cmd_quick(g: BeliefGraph, keyword: str, sexp_path: str) -> None:
+    """Search for keyword then run analyze for the first match.
+
+    Resolution order:
+    1. resolve_module (exact/suffix/substring/case-insensitive)
+    2. Regex search across the raw sexp file, extract module IDs from matches
+
+    Runs cmd_analyze on the first unique module found.
+    """
+    matches = g.resolve_module(keyword)
+    if matches:
+        cmd_analyze(g, matches[0])
+        return
+
+    # Fallback: grep the sexp file for the keyword and extract module IDs from lines
+    regex = re.compile(re.escape(keyword), re.IGNORECASE)
+    seen_modules: list[str] = []
+    seen_set: set[str] = set()
+    with open(sexp_path, "r") as f:
+        for line in f:
+            if not regex.search(line):
+                continue
+            tokens = tokenize(line)
+            if not tokens:
+                continue
+            # Heuristically grab module-like tokens and resolve legacy path-map aliases.
+            for tok in tokens[1:3]:
+                resolved = g.resolve_alias(tok)
+                if resolved in g.nodes and resolved not in seen_set:
+                    seen_set.add(resolved)
+                    seen_modules.append(resolved)
+                    break
+
+    if not seen_modules:
+        _print_no_match(g, keyword)
+        return
+
+    cmd_analyze(g, seen_modules[0])
+
+
+def cmd_search(_g: BeliefGraph, pattern: str, sexp_path: str) -> None:
+    """Search module IDs first, then fall back to raw fact grep."""
+    module_matches = _g.search_modules(pattern)
+    if module_matches:
+        for nid in module_matches:
+            print(f"(result {nid})")
+        print(f"(result-count {len(module_matches)})")
+        return
+
+    regex = re.compile(pattern, re.IGNORECASE)
+    with open(sexp_path, "r") as f:
+        for line in f:
+            if regex.search(line):
+                print(line.rstrip())
+
+
+def cmd_boundaries(g: BeliefGraph, module_id: str) -> None:
+    """Check boundary violations inferred from architecture layer patterns.
+
+    Uses path-based layer classification and well-known architecture rules:
+    - domain must not import infra/api/ui
+    - ui must not import infra
+    - service must not import api
+    - infra must not import api
+    """
+    # Well-known deny rules (src_layer, tgt_layer, reason)
+    deny_rules = [
+        ("domain", "infra",   "domain imports infrastructure directly"),
+        ("domain", "api",     "domain imports API layer"),
+        ("domain", "ui",      "domain imports UI layer"),
+        ("ui",     "infra",   "UI imports infrastructure directly"),
+        ("service","api",     "service imports API layer (inversion)"),
+        ("infra",  "api",     "infrastructure imports API layer"),
+    ]
+
+    if module_id == "all":
+        scope_mods = set(g.nodes.keys())
+    else:
+        matches = g.resolve_module(module_id)
+        if not matches:
+            _print_no_match(g, module_id)
+            return
+        scope_mods = set(matches)
+
+    violations: list[tuple[str, str, str, str, str, str]] = []
+
+    for src_mod in sorted(scope_mods):
+        src_layer = _classify_layer(src_mod, g.module_purpose(src_mod))
+        for edge in g.edges_from.get(src_mod, []):
+            if edge.etype not in ("imports", "data-flow"):
+                continue
+            tgt_mod = edge.target.split("::")[0]
+            if tgt_mod == src_mod:
+                continue
+            tgt_layer = _classify_layer(tgt_mod, g.module_purpose(tgt_mod))
+            if src_layer == tgt_layer:
+                continue
+            for deny_src, deny_tgt, reason in deny_rules:
+                if src_layer == deny_src and tgt_layer == deny_tgt:
+                    violations.append((src_mod, tgt_mod, src_layer, tgt_layer, edge.etype, reason))
+                    break
+
+    if not violations:
+        print(f"(boundaries-ok :checked {len(scope_mods)})")
+        return
+    for src, tgt, sl, tl, etype, reason in sorted(violations):
+        src_file = g.module_to_file(src)
+        tgt_file = g.module_to_file(tgt)
+        print(f"(violation {src} {tgt} :src-layer {sl} :tgt-layer {tl} :via {etype} :lang {g.module_lang(src)} :src-file {_q(src_file)} :tgt-file {_q(tgt_file)} {_q(reason)})")
+    print(f"(boundaries-summary :violations {len(violations)} :checked {len(scope_mods)})")
+
+
+def cmd_layers(g: BeliefGraph) -> None:
+    """Show layer classification for all modules, grouped by layer."""
+    by_layer: dict[str, list[str]] = {}
+    for nid in sorted(g.nodes.keys()):
+        layer = _classify_layer(nid, g.module_purpose(nid))
+        by_layer.setdefault(layer, []).append(nid)
+
+    for layer_name in sorted(by_layer.keys()):
+        mods = by_layer[layer_name]
+        print(f"(layer-group {layer_name} :count {len(mods)})")
+        for m in mods:
+            print(f"(layer-member {layer_name} {m} :lang {g.module_lang(m)})")
+
+
+# ---------------------------------------------------------------------------
+# Naming convention invariant checker
+# ---------------------------------------------------------------------------
+
+# Allowed naming conventions per language.  A module whose :naming value is
+# NOT in the allowed set is a violation.  Languages absent from this map have
+# no strict rule and are always considered conforming.
+_NAMING_RULES: dict[str, set[str]] = {
+    "py":  {"snake_case", "mixed", "kebab-case"},
+    "tsx": {"PascalCase", "camelCase", "kebab-case", "mixed"},
+    "ts":  {"camelCase", "PascalCase", "kebab-case", "mixed", "snake_case"},
+}
+
+
+def cmd_invariants(g: BeliefGraph, scope: str) -> None:
+    """Check naming-convention violations across modules.
+
+    For each module that has a :naming annotation, validate the value against
+    the allowed set for its language.  Modules without a :naming annotation
+    are silently skipped (no data, no opinion).
+
+    Output format::
+
+        (invariant-violation <mod> :expected snake_case :actual PascalCase :lang py :pkg <pkg>)
+        (invariants-summary :violations 12 :checked 3587)
+        (invariants-ok :checked 3587)
+    """
+    if scope == "all":
+        candidates = list(g.nodes.values())
+    else:
+        matches = g.resolve_module(scope)
+        if not matches:
+            _print_no_match(g, scope)
+            return
+        candidates = [g.nodes[nid] for nid in matches if nid in g.nodes]
+
+    checked = 0
+    violations: list[tuple[str, str, str, str, str]] = []  # (nid, expected, actual, lang, pkg)
+
+    for node in candidates:
+        if not node.naming:
+            continue
+        checked += 1
+        lang = {"ty": "ts", "tx": "tsx"}.get(node.lang, node.lang)
+        allowed = _NAMING_RULES.get(lang)
+        if allowed is None:
+            # No rule defined for this language -- always conforming.
+            continue
+        if node.naming not in allowed:
+            expected_repr = " ".join(sorted(allowed))
+            violations.append((node.nid, expected_repr, node.naming, lang, node.pkg))
+
+    if not violations:
+        print(f"(invariants-ok :checked {checked})")
+        return
+
+    for nid, expected, actual, lang, pkg in sorted(violations):
+        pkg_part = f" :pkg {_q(pkg)}" if pkg else ""
+        print(
+            f"(invariant-violation {nid}"
+            f" :expected {_q(expected)}"
+            f" :actual {actual}"
+            f" :lang {lang}"
+            f"{pkg_part})"
+        )
+    print(f"(invariants-summary :violations {len(violations)} :checked {checked})")
+
+
+# ---------------------------------------------------------------------------
+# Function / type search and call graph commands
+# ---------------------------------------------------------------------------
+
+def cmd_find_function(g: BeliefGraph, name: str) -> None:
+    """Find function/method definitions matching a name pattern.
+
+    Searches fn entities and cls methods. Exact match first, then regex.
+    """
+    pattern = re.compile(name, re.IGNORECASE)
+    results: list[tuple[EntityFact, str]] = []
+
+    for ent_name, ent_list in g.entity_by_name.items():
+        for ent in ent_list:
+            if ent.kind == "fn":
+                if ent_name == name or pattern.search(ent_name):
+                    results.append((ent, ""))
+
+    # Also search methods inside classes
+    for _mod, ent_list in g.entities.items():
+        for ent in ent_list:
+            if ent.kind == "cls" and ent.methods:
+                for method in ent.methods:
+                    if method == name or pattern.search(method):
+                        results.append((ent, method))
+
+    if not results:
+        _print_no_match(g, name)
+        return
+
+    seen: set[str] = set()
+    for ent, method in sorted(results, key=lambda x: (x[0].module, x[0].line)):
+        lang = g.module_lang(ent.module)
+        fpath = g.module_to_file(ent.module)
+        if method:
+            key = f"{ent.module}::{ent.name}.{method}"
+            if key not in seen:
+                seen.add(key)
+                print(f"(fn-def {ent.module}::{ent.name}.{method} :line {ent.line} :lang {lang} :file {_q(fpath)} :kind method)")
+        else:
+            key = f"{ent.module}::{ent.name}"
+            if key not in seen:
+                seen.add(key)
+                print(f"(fn-def {ent.module}::{ent.name} :line {ent.line} :lang {lang} :file {_q(fpath)} :kind function)")
+
+
+def cmd_find_type(g: BeliefGraph, name: str) -> None:
+    """Find type/class/interface/enum definitions matching a name pattern.
+
+    Searches cls, ifc, typ, enm entities.
+    """
+    pattern = re.compile(name, re.IGNORECASE)
+    results: list[EntityFact] = []
+
+    for ent_name, ent_list in g.entity_by_name.items():
+        for ent in ent_list:
+            if ent.kind in ("cls", "ifc", "typ", "enm"):
+                if ent_name == name or pattern.search(ent_name):
+                    results.append(ent)
+
+    if not results:
+        _print_no_match(g, name)
+        return
+
+    for ent in sorted(results, key=lambda x: (x.module, x.line)):
+        lang = g.module_lang(ent.module)
+        fpath = g.module_to_file(ent.module)
+        extras = ""
+        if ent.bases:
+            extras += " " + _sexp_list("bases", ent.bases)
+        if ent.methods:
+            extras += " " + _sexp_list("methods", ent.methods)
+        print(f"(type-def {ent.kind} {ent.module}::{ent.name} :line {ent.line} :lang {lang} :file {_q(fpath)}{extras})")
+
+
+def _resolve_fn_entity(g: BeliefGraph, fn_name: str) -> list[tuple[str, EntityFact]]:
+    """Resolve a function name to (qualified_id, entity) pairs.
+
+    Returns entity-qualified IDs like 'module::fnName'. Searches both
+    standalone functions and class methods.
+    """
+    pattern = re.compile(re.escape(fn_name), re.IGNORECASE)
+    results: list[tuple[str, EntityFact]] = []
+
+    for ent_name, ent_list in g.entity_by_name.items():
+        for ent in ent_list:
+            if ent.kind == "fn" and (ent_name == fn_name or pattern.search(ent_name)):
+                results.append((f"{ent.module}::{ent_name}", ent))
+
+    # Also search class methods
+    for _mod, ent_list in g.entities.items():
+        for ent in ent_list:
+            if ent.kind == "cls" and ent.methods:
+                for method in ent.methods:
+                    if method == fn_name or pattern.search(method):
+                        results.append((f"{ent.module}::{method}", ent))
+
+    return results
+
+
+def cmd_find_callers(g: BeliefGraph, fn_name: str, max_depth: int) -> None:
+    """Find all callers of a function (incoming call graph).
+
+    Uses 'calls' edges from the belief map. Falls back to refs edges
+    when calls edges are unavailable.
+    """
+    targets = _resolve_fn_entity(g, fn_name)
+    if not targets:
+        _print_no_match(g, fn_name)
+        return
+
+    target_mods: set[str] = set()
+    target_qualified: set[str] = set()
+    for qid, ent in targets:
+        target_mods.add(ent.module)
+        target_qualified.add(qid)
+        lang = g.module_lang(ent.module)
+        fpath = g.module_to_file(ent.module)
+        print(f"(callers-target {qid} :line {ent.line} :lang {lang} :file {_q(fpath)})")
+
+    # Collect direct callers via calls edges
+    direct_callers: list[Edge] = []
+    for e in g.all_edges:
+        if e.etype == "calls":
+            tgt_fn = e.target.split("::")[-1] if "::" in e.target else ""
+            if e.target in target_qualified or tgt_fn == fn_name:
+                direct_callers.append(e)
+
+    if direct_callers:
+        for e in sorted(direct_callers, key=lambda x: (x.source, x.target)):
+            src_mod = e.source.split("::")[0]
+            print(f"(caller {e.source} -> {e.target} :lang {g.module_lang(src_mod)} :file {_q(g.module_to_file(src_mod))} {' '.join(e.flags)})")
+    else:
+        # Fallback: use module-level edges (imports/refs) pointing at target modules
+        print("; no calls edges found, showing module-level callers via imports/refs")
+
+    # Walk reverse deps to given depth
+    for tgt_mod in target_mods:
+        visited: set[str] = {tgt_mod}
+        _walk_rdeps(g, tgt_mod, visited, max_depth, 1,
+                    lambda d, et, src, cyc: print(
+                        f"(caller-module {src} -> {tgt_mod} :via {et} :depth {d} "
+                        f":lang {g.module_lang(src)} :file {_q(g.module_to_file(src))}"
+                        f"{' :cycle' if cyc else ''})"))
+
+
+def cmd_find_calls(g: BeliefGraph, fn_name: str, max_depth: int) -> None:
+    """Find all functions called by a given function (outgoing call graph).
+
+    Uses 'calls' edges from the belief map.
+    """
+    sources = _resolve_fn_entity(g, fn_name)
+    if not sources:
+        _print_no_match(g, fn_name)
+        return
+
+    source_mods: set[str] = set()
+    source_qualified: set[str] = set()
+    for qid, ent in sources:
+        source_mods.add(ent.module)
+        source_qualified.add(qid)
+        lang = g.module_lang(ent.module)
+        fpath = g.module_to_file(ent.module)
+        print(f"(calls-source {qid} :line {ent.line} :lang {lang} :file {_q(fpath)})")
+
+    # Collect direct calls via calls edges
+    direct_calls: list[Edge] = []
+    for e in g.all_edges:
+        if e.etype == "calls":
+            src_fn = e.source.split("::")[-1] if "::" in e.source else ""
+            if e.source in source_qualified or src_fn == fn_name:
+                direct_calls.append(e)
+
+    if direct_calls:
+        for e in sorted(direct_calls, key=lambda x: (x.source, x.target)):
+            tgt_mod = e.target.split("::")[0]
+            print(f"(calls-target {e.source} -> {e.target} :lang {g.module_lang(tgt_mod)} :file {_q(g.module_to_file(tgt_mod))} {' '.join(e.flags)})")
+    else:
+        print("; no calls edges found, showing module-level deps via imports")
+
+    # Walk forward deps to given depth
+    for src_mod in source_mods:
+        visited: set[str] = {src_mod}
+        _walk_deps(g, src_mod, visited, max_depth, 1,
+                   lambda d, et, tgt, cyc: print(
+                       f"(calls-module {src_mod} -> {tgt} :via {et} :depth {d} "
+                       f":lang {g.module_lang(tgt)} :file {_q(g.module_to_file(tgt))}"
+                       f"{' :cycle' if cyc else ''})"))
+
+
+def cmd_find_callchain(g: BeliefGraph, src_fn: str, tgt_fn: str, max_depth: int) -> None:
+    """Trace a call path between two functions via BFS on calls edges.
+
+    Falls back to module-level path if no function-level calls edges exist.
+    """
+    src_entities = _resolve_fn_entity(g, src_fn)
+    tgt_entities = _resolve_fn_entity(g, tgt_fn)
+
+    if not src_entities:
+        print(f"(error no-match-source {_q(src_fn)})")
+        return
+    if not tgt_entities:
+        print(f"(error no-match-target {_q(tgt_fn)})")
+        return
+
+    src_ids = {qid for qid, _ in src_entities}
+    tgt_ids = {qid for qid, _ in tgt_entities}
+    tgt_fn_names = {qid.split("::")[-1] for qid in tgt_ids}
+
+    # Build adjacency from calls edges
+    call_adj: dict[str, list[str]] = {}
+    for e in g.all_edges:
+        if e.etype == "calls":
+            call_adj.setdefault(e.source, []).append(e.target)
+
+    # BFS from source to target
+    from collections import deque
+
+    found_path: list[str] = []
+    for start in src_ids:
+        queue: deque[list[str]] = deque([[start]])
+        visited: set[str] = {start}
+        while queue:
+            path = queue.popleft()
+            if len(path) - 1 > max_depth:
+                break
+            current = path[-1]
+            cur_fn = current.split("::")[-1] if "::" in current else ""
+            if current in tgt_ids or cur_fn in tgt_fn_names:
+                found_path = path
+                break
+            for nxt in call_adj.get(current, []):
+                if nxt not in visited:
+                    visited.add(nxt)
+                    queue.append(path + [nxt])
+        if found_path:
+            break
+
+    if found_path:
+        for i, node in enumerate(found_path):
+            mod = node.split("::")[0]
+            lang = g.module_lang(mod)
+            fpath = g.module_to_file(mod)
+            print(f"(callchain-step {i} {node} :lang {lang} :file {_q(fpath)})")
+        print(f"(callchain-summary :length {len(found_path)} :hops {len(found_path) - 1})")
+        return
+
+    # Fallback: module-level BFS using both forward deps AND reverse deps
+    src_mods = {ent.module for _, ent in src_entities}
+    tgt_mods = {ent.module for _, ent in tgt_entities}
+
+    print("; no function-level call path found, trying module-level path")
+
+    # Build module adjacency (forward deps + shared entity refs for better connectivity)
+    mod_adj: dict[str, set[str]] = {}
+    for mod in g.nodes:
+        neighbors = set(_collect_dep_mods(g, mod).keys())
+        # Also add reverse deps (bidirectional search for reachability)
+        neighbors.update(_collect_rdep_mods(g, mod).keys())
+        mod_adj[mod] = neighbors
+
+    for start_mod in src_mods:
+        queue_m: deque[list[str]] = deque([[start_mod]])
+        visited_m: set[str] = {start_mod}
+        mod_path: list[str] = []
+        while queue_m:
+            path_m = queue_m.popleft()
+            if len(path_m) - 1 > max_depth:
+                break
+            current_m = path_m[-1]
+            if current_m in tgt_mods:
+                mod_path = path_m
+                break
+            for nxt_m in sorted(mod_adj.get(current_m, set())):
+                if nxt_m not in visited_m:
+                    visited_m.add(nxt_m)
+                    queue_m.append(path_m + [nxt_m])
+        if mod_path:
+            for i, mod in enumerate(mod_path):
+                lang = g.module_lang(mod)
+                fpath = g.module_to_file(mod)
+                print(f"(callchain-module-step {i} {mod} :lang {lang} :file {_q(fpath)})")
+            print(f"(callchain-module-summary :length {len(mod_path)} :hops {len(mod_path) - 1})")
+            return
+
+    print(f"(callchain-none {_q(src_fn)} -> {_q(tgt_fn)} :max-depth {max_depth})")
+
+
+def cmd_grep_functions(g: BeliefGraph, pattern: str) -> None:
+    """Search function bodies in source files for a regex pattern.
+
+    For each function in the belief map, reads the source file and searches
+    the function body (from definition line to next entity or EOF).
+    """
+    regex = re.compile(pattern, re.IGNORECASE)
+    results: list[tuple[str, str, int, str]] = []  # (module::fn, file, match_line, match_text)
+
+    # Group entities by file for efficient reading
+    file_entities: dict[str, list[tuple[str, EntityFact]]] = {}
+    for mod, ent_list in g.entities.items():
+        fpath = g.module_to_file(mod)
+        if fpath == mod:
+            continue  # file not found on disk
+        for ent in ent_list:
+            if ent.kind == "fn":
+                file_entities.setdefault(fpath, []).append((mod, ent))
+
+    for fpath, fn_list in sorted(file_entities.items()):
+        if not os.path.isfile(fpath):
+            continue
+        try:
+            with open(fpath, "r", errors="replace") as f:
+                lines = f.readlines()
+        except OSError:
+            continue
+
+        # Sort functions by line number to determine body ranges
+        sorted_fns = sorted(fn_list, key=lambda x: x[1].line)
+
+        for idx, (mod, ent) in enumerate(sorted_fns):
+            start = ent.line - 1  # 0-indexed
+            if start < 0 or start >= len(lines):
+                continue
+            # End at next entity's line or +100 lines, whichever is smaller
+            if idx + 1 < len(sorted_fns):
+                end = min(sorted_fns[idx + 1][1].line - 1, start + 100, len(lines))
+            else:
+                end = min(start + 100, len(lines))
+
+            for line_idx in range(start, end):
+                line = lines[line_idx]
+                if regex.search(line):
+                    results.append((
+                        f"{mod}::{ent.name}",
+                        fpath,
+                        line_idx + 1,
+                        line.rstrip(),
+                    ))
+
+    if not results:
+        print(f"(grep-functions-empty {_q(pattern)})")
+        return
+
+    for qid, fpath, line_num, text in results:
+        lang = g.module_lang(qid.split("::")[0])
+        print(f"(grep-fn {qid} :line {line_num} :lang {lang} :file {_q(fpath)} :match {_q(text)})")
+    print(f"(grep-functions-summary :matches {len(results)} :pattern {_q(pattern)})")
+
+
+def cmd_diff_functions(g: BeliefGraph, ref: str) -> None:
+    """Identify which functions were changed in a git diff.
+
+    Parses 'git diff <ref>' output to find changed line ranges,
+    then maps those ranges to function definitions in the belief map.
+    """
+    import subprocess
+
+    # Use the belief map root as git working directory (not cwd)
+    git_cwd = g._root or None
+
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--unified=0", ref],
+            capture_output=True, text=True, timeout=30, cwd=git_cwd,
+        )
+        if result.returncode != 0:
+            # Try as a commit ref
+            result = subprocess.run(
+                ["git", "diff", "--unified=0", ref, "HEAD"],
+                capture_output=True, text=True, timeout=30, cwd=git_cwd,
+            )
+            if result.returncode != 0:
+                print(f"(error git-diff-failed {_q(result.stderr.strip())})")
+                return
+    except FileNotFoundError:
+        print("(error git-not-found)")
+        return
+    except subprocess.TimeoutExpired:
+        print("(error git-diff-timeout)")
+        return
+
+    # Parse diff output to extract file -> changed line ranges
+    changed_ranges: dict[str, list[tuple[int, int]]] = {}  # file -> [(start, end)]
+    current_file = ""
+
+    for line in result.stdout.splitlines():
+        if line.startswith("+++ b/"):
+            current_file = line[6:]
+        elif line.startswith("@@ ") and current_file:
+            # Parse hunk header: @@ -old,count +new,count @@
+            parts = line.split(" ")
+            for part in parts:
+                if part.startswith("+") and "," in part:
+                    nums = part[1:].split(",")
+                    start = int(nums[0])
+                    count = int(nums[1]) if len(nums) > 1 else 1
+                    if count > 0:
+                        changed_ranges.setdefault(current_file, []).append(
+                            (start, start + count - 1)
+                        )
+                elif part.startswith("+") and part[1:].isdigit():
+                    start = int(part[1:])
+                    changed_ranges.setdefault(current_file, []).append(
+                        (start, start)
+                    )
+
+    if not changed_ranges:
+        print(f"(diff-functions-empty {_q(ref)})")
+        return
+
+    # Map changed lines to functions
+    # Build file -> sorted entities index
+    file_entities: dict[str, list[tuple[str, EntityFact]]] = {}
+    for mod, ent_list in g.entities.items():
+        fpath = g.module_to_file(mod)
+        for ent in ent_list:
+            file_entities.setdefault(fpath, []).append((mod, ent))
+
+    # Normalize paths for matching (diff paths are relative to repo root)
+    repo_root = g._root
+    results: list[tuple[str, EntityFact, str]] = []  # (qualified_id, entity, file)
+
+    for diff_file, ranges in changed_ranges.items():
+        # Try matching against belief map files
+        abs_path = os.path.join(repo_root, diff_file)
+        # Also try relative path
+        candidates = [abs_path, diff_file]
+
+        matched_ents: list[tuple[str, EntityFact]] = []
+        for candidate in candidates:
+            if candidate in file_entities:
+                matched_ents = file_entities[candidate]
+                break
+
+        if not matched_ents:
+            # Try suffix matching
+            for fpath, ent_list in file_entities.items():
+                if fpath.endswith(diff_file) or diff_file.endswith(fpath.lstrip("./")):
+                    matched_ents = ent_list
+                    break
+
+        if not matched_ents:
+            continue
+
+        # Sort entities by line to determine body ranges
+        sorted_ents = sorted(matched_ents, key=lambda x: x[1].line)
+
+        for start, end in ranges:
+            for idx, (mod, ent) in enumerate(sorted_ents):
+                ent_start = ent.line
+                if idx + 1 < len(sorted_ents):
+                    ent_end = sorted_ents[idx + 1][1].line - 1
+                else:
+                    ent_end = ent_start + 200  # approximate
+
+                # Check overlap
+                if start <= ent_end and end >= ent_start:
+                    qid = f"{mod}::{ent.name}"
+                    if not any(r[0] == qid for r in results):
+                        results.append((qid, ent, diff_file))
+
+    if not results:
+        # Report changed files even if no function mapping
+        for diff_file in sorted(changed_ranges.keys()):
+            print(f"(diff-file {_q(diff_file)} :hunks {len(changed_ranges[diff_file])})")
+        print(f"(diff-functions-no-match :files {len(changed_ranges)} :ref {_q(ref)})")
+        return
+
+    for qid, ent, diff_file in sorted(results, key=lambda x: (x[2], x[1].line)):
+        lang = g.module_lang(ent.module)
+        fpath = g.module_to_file(ent.module)
+        print(f"(diff-fn {qid} :kind {ent.kind} :line {ent.line} :lang {lang} :file {_q(fpath)})")
+    print(f"(diff-functions-summary :changed {len(results)} :files {len(changed_ranges)} :ref {_q(ref)})")
+
+
+# ---------------------------------------------------------------------------
+# Scheme query REPL -- composable S-expression queries on the graph
+# ---------------------------------------------------------------------------
+#
+# A tiny Scheme-dialect evaluator that exposes the belief graph as queryable
+# data. Every value is either a string, int, bool, list, or a "module-set"
+# (set of module IDs). Functions compose naturally:
+#
+#   (deps "operatives.controller" 2)        -> module-set of dependencies
+#   (rdeps "operatives.controller" 1)       -> module-set of reverse deps
+#   (boundary "operatives.controller")      -> module-set (target + deps + rdeps)
+#   (entity "OperativesService")            -> list of module IDs defining it
+#   (imports "operatives.controller")       -> module-set of direct imports
+#   (dependents "operatives.controller")    -> module-set of direct dependents
+#   (intersect (deps "A" 2) (rdeps "B" 1)) -> set intersection
+#   (union A B)                             -> set union
+#   (diff A B)                              -> set difference
+#   (filter SET "pattern")                  -> grep within set
+#   (files SET)                             -> resolve module IDs to file paths
+#   (count SET)                             -> cardinality
+#   (analyze "id")                          -> full analysis (prints sexp)
+#   (search "pattern")                      -> raw grep on sexp file
+
+_QUERY_HELP = """\
+; Scheme query language for .belief_map.sexp
+;
+; Primitives (return module-set or list):
+;   (resolve "pattern")                Find module IDs matching pattern
+;   (deps "id" depth)                  Outgoing dependency set (default depth 2)
+;   (rdeps "id" depth)                 Reverse dependency set (default depth 1)
+;   (imports "id")                     Direct import targets
+;   (dependents "id")                  Direct dependents (who imports this)
+;   (boundary "id")                    Target + deps + rdeps (change boundary)
+;   (entity "Name")                    Modules defining entity
+;   (refs-to "Name")                   Modules referencing entity
+;   (search "pattern")                 Grep .belief_map.sexp
+;
+; Function & type search (return module-set):
+;   (find-function "name")             Modules containing function definitions
+;   (find-type "name")                 Modules containing type/class/ifc/enum defs
+;   (find-callers "fn" depth)          Modules that call a function (default depth 2)
+;   (find-calls "fn" depth)            Modules that a function calls (default depth 2)
+;   (diff-functions "ref")             Print changed functions (side-effect, returns empty)
+;
+; Set operations:
+;   (intersect A B)                    Set intersection
+;   (union A B ...)                    Set union
+;   (diff A B)                         A minus B
+;   (filter SET "pattern")             Keep members matching regex
+;
+; Output:
+;   (files SET)                        Resolve to file paths
+;   (count SET)                        Count members
+;   (analyze "id")                     Full analysis output
+;
+; Composition:
+;   (files (intersect (deps "A" 2) (rdeps "B" 1)))
+;   (filter (boundary "X") "dto")
+;   (count (deps "operatives.service" 3))
+;   (files (find-callers "createOrder" 3))
+;   (intersect (find-function "handle") (deps "api" 2))
+"""
+
+
+class _SchemeEval:
+    """Tiny Scheme evaluator for belief graph queries."""
+
+    def __init__(self, g: BeliefGraph, sexp_path: str) -> None:
+        self._g = g
+        self._sexp_path = sexp_path
+
+    def eval_str(self, expr_str: str) -> object:
+        tokens = self._tokenize(expr_str)
+        ast = self._parse(tokens)
+        return self._eval(ast)
+
+    # -- Tokenizer --
+
+    @staticmethod
+    def _tokenize(s: str) -> list[str]:
+        tokens: list[str] = []
+        i = 0
+        while i < len(s):
+            ch = s[i]
+            if ch in (" ", "\t", "\n", "\r"):
+                i += 1
+            elif ch == ";":
+                while i < len(s) and s[i] != "\n":
+                    i += 1
+            elif ch in ("(", ")"):
+                tokens.append(ch)
+                i += 1
+            elif ch == '"':
+                j = i + 1
+                while j < len(s) and s[j] != '"':
+                    if s[j] == "\\":
+                        j += 1
+                    j += 1
+                tokens.append(s[i + 1 : j])
+                i = j + 1
+            else:
+                j = i
+                while j < len(s) and s[j] not in (" ", "\t", "\n", "\r", "(", ")", '"', ";"):
+                    j += 1
+                tokens.append(s[i:j])
+                i = j
+        return tokens
+
+    # -- Parser: tokens -> nested lists --
+
+    @staticmethod
+    def _parse(tokens: list[str]) -> object:
+        if not tokens:
+            return []
+        pos = [0]
+
+        def _read() -> object:
+            if pos[0] >= len(tokens):
+                return None
+            tok = tokens[pos[0]]
+            if tok == "(":
+                pos[0] += 1
+                lst: list[object] = []
+                while pos[0] < len(tokens) and tokens[pos[0]] != ")":
+                    lst.append(_read())
+                pos[0] += 1  # skip )
+                return lst
+            if tok == ")":
+                pos[0] += 1
+                return None
+            pos[0] += 1
+            # Try int
+            try:
+                return int(tok)
+            except ValueError:
+                return tok
+
+        result = _read()
+        return result
+
+    # -- Evaluator --
+
+    def _eval(self, ast: object) -> object:
+        if isinstance(ast, (int, float)):
+            return ast
+        if isinstance(ast, str):
+            return ast
+        if not isinstance(ast, list) or len(ast) == 0:
+            return set()
+
+        head = ast[0]
+        args = ast[1:]
+
+        # Evaluate args (eager)
+        evaled = [self._eval(a) for a in args]
+
+        return self._apply(head, evaled)
+
+    def _apply(self, fn: str, args: list[object]) -> object:
+        g = self._g
+
+        if fn == "resolve":
+            pattern = str(args[0]) if args else ""
+            return set(g.resolve_module(pattern))
+
+        if fn == "deps":
+            pattern = str(args[0]) if args else ""
+            depth = int(str(args[1])) if len(args) > 1 else 2
+            matches = g.resolve_module(pattern)
+            result: set[str] = set()
+            for m in matches:
+                visited: set[str] = {m}
+                self._collect_deps(m, visited, depth, 1, result)
+            return result
+
+        if fn == "rdeps":
+            pattern = str(args[0]) if args else ""
+            depth = int(str(args[1])) if len(args) > 1 else 1
+            matches = g.resolve_module(pattern)
+            result = set()
+            for m in matches:
+                visited = {m}
+                self._collect_rdeps(m, visited, depth, 1, result)
+            return result
+
+        if fn == "imports":
+            pattern = str(args[0]) if args else ""
+            matches = g.resolve_module(pattern)
+            result = set()
+            for m in matches:
+                result.update(_collect_dep_mods(g, m).keys())
+            return result
+
+        if fn == "dependents":
+            pattern = str(args[0]) if args else ""
+            matches = g.resolve_module(pattern)
+            result = set()
+            for m in matches:
+                result.update(_collect_rdep_mods(g, m).keys())
+            return result
+
+        if fn == "boundary":
+            pattern = str(args[0]) if args else ""
+            matches = g.resolve_module(pattern)
+            result = set()
+            for m in matches:
+                result.add(m)
+                result.update(_collect_dep_mods(g, m).keys())
+                result.update(_collect_rdep_mods(g, m).keys())
+            return result
+
+        if fn == "entity":
+            name = str(args[0]) if args else ""
+            defs = g.entity_by_name.get(name, [])
+            if not defs:
+                pattern = re.compile(name, re.IGNORECASE)
+                for ename, ents in g.entity_by_name.items():
+                    if pattern.search(ename):
+                        defs.extend(ents)
+            return set(d.module for d in defs)
+
+        if fn == "refs-to":
+            name = str(args[0]) if args else ""
+            edges = g.edges_by_entity_name.get(name, [])
+            return set(e.source.split("::")[0] for e in edges)
+
+        if fn == "intersect":
+            a = self._to_set(args[0])
+            b = self._to_set(args[1]) if len(args) > 1 else set()
+            return a & b
+
+        if fn == "union":
+            result = set()
+            for a in args:
+                result |= self._to_set(a)
+            return result
+
+        if fn == "diff":
+            a = self._to_set(args[0])
+            b = self._to_set(args[1]) if len(args) > 1 else set()
+            return a - b
+
+        if fn == "filter":
+            s = self._to_set(args[0])
+            pattern = str(args[1]) if len(args) > 1 else ""
+            regex = re.compile(pattern, re.IGNORECASE)
+            return {m for m in s if regex.search(m)}
+
+        if fn == "files":
+            s = self._to_set(args[0])
+            return set(g.module_to_file(m) for m in s)
+
+        if fn == "count":
+            s = self._to_set(args[0])
+            return len(s)
+
+        if fn == "analyze":
+            pattern = str(args[0]) if args else ""
+            cmd_analyze(g, pattern)
+            return set()
+
+        if fn == "search":
+            pattern = str(args[0]) if args else ""
+            cmd_search(g, pattern, self._sexp_path)
+            return set()
+
+        if fn == "layer":
+            pattern = str(args[0]) if args else ""
+            matches = g.resolve_module(pattern)
+            if matches:
+                return _classify_layer(matches[0], g.module_purpose(matches[0]))
+            return "unknown"
+
+        if fn == "violations":
+            pattern = str(args[0]) if args else "all"
+            scope = set(g.nodes.keys()) if pattern == "all" else set(g.resolve_module(pattern))
+            deny_rules = [
+                ("domain", "infra"), ("domain", "api"), ("domain", "ui"),
+                ("ui", "infra"), ("service", "api"), ("infra", "api"),
+            ]
+            result: set[str] = set()
+            for src_mod in scope:
+                sl = _classify_layer(src_mod, g.module_purpose(src_mod))
+                for edge in g.edges_from.get(src_mod, []):
+                    if edge.etype not in ("imports", "data-flow"):
+                        continue
+                    tgt_mod = edge.target.split("::")[0]
+                    tl = _classify_layer(tgt_mod, g.module_purpose(tgt_mod))
+                    if sl != tl and (sl, tl) in deny_rules:
+                        result.add(src_mod)
+            return result
+
+        if fn == "layer-of":
+            s = self._to_set(args[0])
+            target_layer = str(args[1]) if len(args) > 1 else ""
+            return {m for m in s if _classify_layer(m, g.module_purpose(m)) == target_layer}
+
+        if fn == "find-function" or fn == "find_function":
+            name = str(args[0]) if args else ""
+            pattern = re.compile(name, re.IGNORECASE)
+            result: set[str] = set()
+            for ent_name, ent_list in g.entity_by_name.items():
+                for ent in ent_list:
+                    if ent.kind == "fn" and (ent_name == name or pattern.search(ent_name)):
+                        result.add(ent.module)
+            return result
+
+        if fn == "find-type" or fn == "find_type":
+            name = str(args[0]) if args else ""
+            pattern = re.compile(name, re.IGNORECASE)
+            result = set()
+            for ent_name, ent_list in g.entity_by_name.items():
+                for ent in ent_list:
+                    if ent.kind in ("cls", "ifc", "typ", "enm") and (ent_name == name or pattern.search(ent_name)):
+                        result.add(ent.module)
+            return result
+
+        if fn == "find-callers" or fn == "find_callers":
+            fn_name = str(args[0]) if args else ""
+            depth = int(str(args[1])) if len(args) > 1 else 2
+            targets = _resolve_fn_entity(g, fn_name)
+            result = set()
+            for _qid, ent in targets:
+                result.add(ent.module)
+            # Collect callers via calls edges
+            tgt_qualified = {qid for qid, _ in targets}
+            for e in g.all_edges:
+                if e.etype == "calls" and e.target in tgt_qualified:
+                    result.add(e.source.split("::")[0])
+            # Also walk reverse deps
+            for _qid, ent in targets:
+                visited: set[str] = {ent.module}
+                self._collect_rdeps(ent.module, visited, depth, 1, result)
+            return result
+
+        if fn == "find-calls" or fn == "find_calls":
+            fn_name = str(args[0]) if args else ""
+            depth = int(str(args[1])) if len(args) > 1 else 2
+            sources = _resolve_fn_entity(g, fn_name)
+            result = set()
+            src_qualified = {qid for qid, _ in sources}
+            for e in g.all_edges:
+                if e.etype == "calls" and e.source in src_qualified:
+                    result.add(e.target.split("::")[0])
+            for _qid, ent in sources:
+                visited = {ent.module}
+                self._collect_deps(ent.module, visited, depth, 1, result)
+            return result
+
+        if fn == "diff-functions" or fn == "diff_functions":
+            ref = str(args[0]) if args else "HEAD"
+            cmd_diff_functions(g, ref)
+            return set()
+
+        print(f"; unknown function: {fn}")
+        return set()
+
+    def _collect_deps(
+        self, nid: str, visited: set[str], max_depth: int, depth: int, result: set[str],
+    ) -> None:
+        if depth > max_depth:
+            return
+        for tgt in _collect_dep_mods(self._g, nid):
+            result.add(tgt)
+            if tgt not in visited:
+                visited.add(tgt)
+                self._collect_deps(tgt, visited, max_depth, depth + 1, result)
+
+    def _collect_rdeps(
+        self, nid: str, visited: set[str], max_depth: int, depth: int, result: set[str],
+    ) -> None:
+        if depth > max_depth:
+            return
+        for src in _collect_rdep_mods(self._g, nid):
+            result.add(src)
+            if src not in visited:
+                visited.add(src)
+                self._collect_rdeps(src, visited, max_depth, depth + 1, result)
+
+    @staticmethod
+    def _to_set(val: object) -> set[str]:
+        if isinstance(val, set):
+            return val
+        if isinstance(val, str):
+            return {val}
+        if isinstance(val, (list, tuple)):
+            return set(str(v) for v in val)
+        return set()
+
+
+def _format_result(val: object) -> None:
+    """Print a Scheme query result as S-expression facts."""
+    if isinstance(val, set):
+        for item in sorted(val):
+            print(f"(result {_q(item)})")
+        if not val:
+            print("(result-empty)")
+    elif isinstance(val, int):
+        print(f"(result-count {val})")
+    elif isinstance(val, str):
+        print(f"(result {_q(val)})")
+    elif isinstance(val, list):
+        for item in val:
+            print(f"(result {_q(str(item))})")
+    else:
+        print(f"(result {_q(str(val))})")
+
+
+def cmd_query(g: BeliefGraph, expr: str, sexp_path: str) -> None:
+    """Evaluate a single Scheme query expression."""
+    evaluator = _SchemeEval(g, sexp_path)
+    result = evaluator.eval_str(expr)
+    _format_result(result)
+
+
+def cmd_repl(g: BeliefGraph, sexp_path: str) -> None:
+    """Interactive Scheme REPL for belief map queries."""
+    evaluator = _SchemeEval(g, sexp_path)
+    print("; belief-map query REPL")
+    print("; type (help) for available functions, (quit) to exit")
+    print()
+
+    while True:
+        try:
+            expr = input("bm> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not expr or expr.startswith(";"):
+            continue
+        if expr in ("(quit)", "(exit)", "quit", "exit"):
+            break
+        if expr in ("(help)", "help"):
+            print(_QUERY_HELP)
+            continue
+
+        result = evaluator.eval_str(expr)
+        _format_result(result)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def find_sexp_file() -> str:
+    """Find belief_map.sexp in current or parent dirs.
+
+    Searches for (in priority order per directory):
+      .belief_map.sexp, belief_map.sexp
+
+    If only a JSON belief map is found, prints a migration hint.
+    """
+    _SEXP_NAMES = (".belief_map.sexp", "belief_map.sexp")
+    _JSON_NAMES = (".belief_map.json", "belief_map.json")
+    cur = os.getcwd()
+    json_found = ""
+    while True:
+        for name in _SEXP_NAMES:
+            candidate = os.path.join(cur, name)
+            if os.path.isfile(candidate):
+                return candidate
+        if not json_found:
+            for name in _JSON_NAMES:
+                candidate = os.path.join(cur, name)
+                if os.path.isfile(candidate):
+                    json_found = candidate
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            break
+        cur = parent
+    if json_found:
+        print(f"Error: found JSON belief map at {json_found} but this script requires sexp format.", file=sys.stderr)
+        print("Rebuild with the sexp builder:", file=sys.stderr)
+        print(f"  python3 ~/.claude/skills/codespaces/scripts/build_belief_map.py", file=sys.stderr)
+    else:
+        print("Error: .belief_map.sexp not found. Run build_belief_map.py first.", file=sys.stderr)
+    sys.exit(1)
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(__doc__)
+        sys.exit(0)
+
+    sexp_path = find_sexp_file()
+    g = BeliefGraph()
+    g.load(sexp_path)
+
+    cmd = args[0]
+    if cmd == "analyze" and len(args) >= 2:
+        cmd_analyze(g, args[1])
+    elif cmd == "boundary" and len(args) >= 2:
+        files_only = "--files-only" in args
+        module_arg = [a for a in args[1:] if a != "--files-only"][0]
+        cmd_boundary(g, module_arg, files_only=files_only)
+    elif cmd == "quick" and len(args) >= 2:
+        cmd_quick(g, args[1], sexp_path)
+    elif cmd == "module" and len(args) >= 2:
+        cmd_module(g, args[1])
+    elif cmd == "deps" and len(args) >= 2:
+        depth = int(args[2]) if len(args) >= 3 else 2
+        cmd_deps(g, args[1], depth)
+    elif cmd == "rdeps" and len(args) >= 2:
+        depth = int(args[2]) if len(args) >= 3 else 2
+        cmd_rdeps(g, args[1], depth)
+    elif cmd == "entity" and len(args) >= 2:
+        cmd_entity(g, args[1])
+    elif cmd == "flow" and len(args) >= 3:
+        cmd_flow(g, args[1], args[2])
+    elif cmd == "search" and len(args) >= 2:
+        cmd_search(g, args[1], sexp_path)
+    elif cmd == "boundaries":
+        target = args[1] if len(args) >= 2 else "all"
+        cmd_boundaries(g, target)
+    elif cmd == "layers":
+        cmd_layers(g)
+    elif cmd == "invariants":
+        target = args[1] if len(args) >= 2 else "all"
+        cmd_invariants(g, target)
+    elif cmd == "find_function" and len(args) >= 2:
+        cmd_find_function(g, args[1])
+    elif cmd == "find_type" and len(args) >= 2:
+        cmd_find_type(g, args[1])
+    elif cmd == "find_callchain" and len(args) >= 3:
+        depth = int(args[3]) if len(args) >= 4 else 5
+        cmd_find_callchain(g, args[1], args[2], depth)
+    elif cmd == "find_callers" and len(args) >= 2:
+        depth = int(args[2]) if len(args) >= 3 else 2
+        cmd_find_callers(g, args[1], depth)
+    elif cmd == "find_calls" and len(args) >= 2:
+        depth = int(args[2]) if len(args) >= 3 else 2
+        cmd_find_calls(g, args[1], depth)
+    elif cmd == "grep_functions" and len(args) >= 2:
+        cmd_grep_functions(g, args[1])
+    elif cmd == "diff_functions":
+        ref = args[1] if len(args) >= 2 else "HEAD"
+        cmd_diff_functions(g, ref)
+    elif cmd == "query" and len(args) >= 2:
+        cmd_query(g, " ".join(args[1:]), sexp_path)
+    elif cmd == "repl":
+        cmd_repl(g, sexp_path)
+    else:
+        print(f"(error unknown-command {_q(cmd if args else 'none')})")
+        print("; Commands: analyze, boundary, quick, boundaries, layers, invariants, module, deps, rdeps, entity, flow, search,")
+        print(";          find_function, find_type, find_callchain, find_callers, find_calls, grep_functions, diff_functions,")
+        print(";          query, repl")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build_belief_map.py b/scripts/build_belief_map.py
new file mode 100755
index 0000000..5c54b14
--- /dev/null
+++ b/scripts/build_belief_map.py
@@ -0,0 +1,3182 @@
+#!/usr/bin/env python3
+"""
+Belief Map Builder -- Architecture Graph Generator.
+
+Generates ``belief_map.sexp``, a flat S-expression graph of all modules,
+entities, and relationships in a codebase. Each line is a self-contained
+fact, queryable with ``rg`` or ``scripts/belief_search.py``.
+
+Based on the Theory of Code Space (ToCS) methodology for reducing the
+"Active-Passive Gap" in AI code agents.
+
+Parsers
+-------
+- **TypeScript/TSX**: tree-sitter (``tree-sitter-typescript``). Handles
+  decorators, heritage, all methods, object literals, arrow functions.
+- **Python**: stdlib ``ast``. Full class/function/import extraction.
+
+Modes
+-----
+**Default** (fast, ~5-8s for full workspace):
+    Parses all .py/.ts/.tsx files, builds import/reference/data-flow edges.
+
+**LSP-enhanced** (``--lsp``, ~1-5min):
+    After default pass, starts ``typescript-language-server`` and
+    ``pyright-langserver`` per project to query call hierarchy and
+    references. Adds precise ``calls`` edges and ``:lsp`` annotations.
+
+Edge Types
+----------
+- ``imports`` -- module imports module. ``:via-base`` if target exports
+  abstract types.
+- ``calls-api`` -- implements/extends abstract type. ``:via-ifc``.
+- ``data-flow`` -- data flows to validation module. ``:validated``.
+- ``refs`` -- entity-level cross-file reference (``Module::Entity``).
+- ``calls`` (LSP only) -- function calls function with call-site lines.
+
+Output Format
+-------------
+Flat S-expression facts (``belief_map.sexp``)::
+
+    (node module/id ts "purpose description")
+    (cls module/id ClassName 49 (:deco Injectable) (:methods create update delete))
+    (fn module/id functionName 126)
+    (imports module/a module/b :via-base)
+    (refs module/a module/b::EntityName)
+    (calls module/a::fnA module/b::fnB :lines 52 67 :lsp)
+
+Requirements
+------------
+::
+
+    pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
+
+Optional for ``--lsp``: ``typescript-language-server``, ``pyright-langserver``.
+
+Usage
+-----
+::
+
+    python3 scripts/build_belief_map.py              # incremental (~5-8s)
+    python3 scripts/build_belief_map.py --full        # full rebuild
+    python3 scripts/build_belief_map.py --lsp         # with call hierarchy
+    python3 scripts/build_belief_map.py ./app-service  # target sub-repo
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import quote, unquote
+
+import tree_sitter_typescript as _tst
+from tree_sitter import Language as _TsLanguage, Parser as _TsParser
+
+_TS_LANG = _TsLanguage(_tst.language_typescript())
+_TSX_LANG = _TsLanguage(_tst.language_tsx())
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+SKIP_DIRS = {
+    "node_modules", ".venv", "venv", "__pycache__", ".git", "dist",
+    ".next", ".turbo", "build", "coverage", ".tox", "site-packages",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", "target",
+    ".worktrees", ".ralphy-worktrees", ".ralphy-sandboxes",
+}
+
+CACHE_FILE = ".belief_map_cache.json"
+OUTPUT_FILE = ".belief_map.sexp"
+
+# Default timeout for LSP requests (seconds)
+LSP_REQUEST_TIMEOUT = 15.0
+# Timeout for LSP server initialization (seconds)
+LSP_INIT_TIMEOUT = 60.0
+
+# -- Python regex patterns --
+
+PY_ABC_RE = re.compile(r"""class\s+\w+\s*\(.*(?:ABC|ABCMeta|Protocol).*\)""")
+PY_INHERITS_RE = re.compile(r"""class\s+(\w+)\s*\(([^)]+)\)""")
+
+# Naming convention detectors
+SNAKE_CASE_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+CAMEL_CASE_RE = re.compile(r"^[a-z][a-zA-Z0-9]*$")
+PASCAL_CASE_RE = re.compile(r"^[A-Z][a-zA-Z0-9]*$")
+KEBAB_CASE_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Entity:
+    name: str
+    kind: str  # class, function, interface, type, enum, method, decorator
+    line: int
+    methods: list[str]  # method names (for classes)
+    decorators: list[str]  # decorator names
+    bases: list[str]  # parent classes / implemented interfaces
+
+    def to_dict(self) -> dict:
+        d: dict = {"name": self.name, "kind": self.kind, "line": self.line}
+        if self.methods:
+            d["methods"] = self.methods
+        if self.decorators:
+            d["decorators"] = self.decorators
+        if self.bases:
+            d["bases"] = self.bases
+        return d
+
+
+@dataclass
+class ImportedName:
+    """A single name imported from another module."""
+    local_name: str      # name used locally
+    original_name: str   # name in source module ("default" for default imports)
+    module: str          # raw import specifier
+
+    def to_dict(self) -> dict:
+        return {
+            "local": self.local_name,
+            "original": self.original_name,
+            "module": self.module,
+        }
+
+
+@dataclass
+class FileResult:
+    path: str
+    language: str
+    repo: str
+    mtime: float
+    content_hash: str
+    imports: list[str]
+    exports_abstract: list[str]
+    implements: list[str]
+    extends: list[str]
+    purpose: str
+    naming_convention: str
+    has_validation: bool
+    entities: list[dict]          # Entity.to_dict() results
+    imported_names: list[dict]    # ImportedName.to_dict() results
+    exported_names: list[str]     # names exported from this file
+
+
+@dataclass
+class LspEdge:
+    """An edge discovered by LSP analysis."""
+    source: str       # "node_id::entity_name" or "node_id"
+    target: str       # "node_id::entity_name" or "node_id"
+    edge_type: str    # "CALLS", "REFERENCES"
+    metadata: dict = field(default_factory=dict)
+
+
+@dataclass
+class ProjectGroup:
+    """A group of files belonging to the same LSP project."""
+    root: str              # absolute path to project root
+    language: str          # "typescript" or "python"
+    config_file: str       # path to tsconfig.json or pyrightconfig.json
+    files: list[FileResult] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def file_hash(path: str) -> str:
+    try:
+        st = os.stat(path)
+        with open(path, "rb") as f:
+            chunk = f.read(8192)
+        return hashlib.md5(chunk + str(st.st_size).encode()).hexdigest()
+    except OSError:
+        return ""
+
+
+def detect_naming(filename: str) -> str:
+    stem = Path(filename).stem
+    for suffix in (".test", ".spec", ".e2e", ".stories", ".d"):
+        if stem.endswith(suffix):
+            stem = stem[: -len(suffix)]
+    if SNAKE_CASE_RE.match(stem):
+        return "snake_case"
+    if KEBAB_CASE_RE.match(stem):
+        return "kebab-case"
+    if PASCAL_CASE_RE.match(stem):
+        return "PascalCase"
+    if CAMEL_CASE_RE.match(stem):
+        return "camelCase"
+    return "mixed"
+
+
+def _levenshtein(a: str, b: str) -> int:
+    """Compute Levenshtein edit distance between two strings."""
+    if len(a) < len(b):
+        return _levenshtein(b, a)
+    if not b:
+        return len(a)
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a):
+        curr = [i + 1]
+        for j, cb in enumerate(b):
+            curr.append(min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (ca != cb)))
+        prev = curr
+    return prev[-1]
+
+
+def _fuzzy_suffix_match(name: str, suffix: str, max_dist: int = 1) -> bool:
+    """Check if the tail of `name` fuzzy-matches `suffix` within edit distance."""
+    if len(suffix) < 6:
+        return False  # too short for fuzzy -- "Store"/"Storey" false positives
+    tail = name[-len(suffix) - max_dist:]  # grab suffix + slack for insertions
+    return _levenshtein(tail.lower(), suffix.lower()) <= max_dist
+
+
+def infer_purpose(path: str, content: str, language: str, entities: Optional[list] = None) -> str:
+    """Infer architectural purpose from path, content, and entity names."""
+    parts = []
+    rel = path.lower()
+
+    # Path-based heuristics
+    if "/domain/" in rel:
+        parts.append("domain logic")
+    elif "/infrastructure/" in rel or "/infra/" in rel:
+        parts.append("infrastructure adapter")
+    elif "/api/" in rel:
+        parts.append("API layer")
+    elif "/app/" in rel or "/application/" in rel:
+        parts.append("application service")
+    elif "/components/" in rel or "/ui/" in rel:
+        parts.append("UI component")
+    elif "/hooks/" in rel:
+        parts.append("React hook")
+    elif "/pages/" in rel or "/routes/" in rel:
+        parts.append("page/route")
+    elif "/migrations/" in rel:
+        parts.append("database migration")
+    elif "/test" in rel or ".test." in rel or ".spec." in rel:
+        parts.append("test")
+    elif "/config" in rel:
+        parts.append("configuration")
+    elif "/utils/" in rel or "/helpers/" in rel or "/commons/" in rel:
+        parts.append("shared utilities")
+    elif "/repositories/" in rel or "/repo/" in rel:
+        parts.append("repository")
+    elif "/services/" in rel:
+        parts.append("service")
+    elif "/dto/" in rel:
+        parts.append("DTO")
+    elif "/guards/" in rel or "guard" in rel:
+        parts.append("access guard")
+    elif "/store/" in rel or "/stores/" in rel:
+        parts.append("state store")
+    elif "/schema" in rel:
+        parts.append("schema")
+    elif "/sdk/" in rel:
+        parts.append("SDK")
+    elif "/api-client/" in rel or "/api_client/" in rel:
+        parts.append("API client")
+
+    # Docstring extraction
+    head = content[:2048]
+    if language == "python":
+        match = re.search(r'^"""(.*?)"""', head, re.DOTALL)
+        if not match:
+            match = re.search(r"^'''(.*?)'''", head, re.DOTALL)
+        if match:
+            parts.append(match.group(1).strip().split("\n")[0][:120])
+    else:
+        match = re.search(r"/\*\*\s*\n?\s*\*?\s*(.+?)(?:\n|\*/)", head)
+        if match:
+            parts.append(match.group(1).strip()[:120])
+
+    # Entity-name heuristics (Gap 3 fix: reduces "general module" fallback)
+    # -- Suffix -> (purpose label, dedup keyword) --
+    _ENTITY_SUFFIX_MAP = [
+        # Core architecture roles
+        ("Service", "service", "service"),
+        ("Controller", "API controller", "controller"),
+        ("Repository", "repository", "repository"),
+        ("Repo", "repository", "repository"),
+        ("Gateway", "gateway", "gateway"),
+        ("Registry", "registry", "registry"),
+        ("Store", "state store", "store"),
+        ("Guard", "access guard", "guard"),
+        ("Module", "module", "module"),
+        ("Adapter", "adapter", "adapter"),
+        ("Provider", "provider", "provider"),
+        ("Processor", "processor", "processor"),
+        ("Agent", "agent", "agent"),
+        ("Resolver", "resolver", "resolver"),
+        ("Scheduler", "scheduler", "scheduler"),
+        ("Worker", "worker", "worker"),
+        ("Client", "client", "client"),
+        ("Connector", "connector", "connector"),
+        ("Manager", "manager", "manager"),
+        ("Subscriber", "subscriber", "subscriber"),
+        ("Dispatcher", "dispatcher", "dispatcher"),
+        ("Emitter", "emitter", "emitter"),
+        ("Interceptor", "interceptor", "interceptor"),
+        ("Pipe", "validation pipe", "pipe"),
+        ("Handler", "handler", "handler"),
+        ("Listener", "event listener", "listener"),
+        # GoF patterns
+        ("Factory", "Factory pattern", "factory"),
+        ("Builder", "Builder pattern", "builder"),
+        ("Singleton", "Singleton pattern", "singleton"),
+        ("Observer", "Observer pattern", "observer"),
+        ("Strategy", "Strategy pattern", "strategy"),
+        ("Command", "Command pattern", "command"),
+        ("Mediator", "Mediator pattern", "mediator"),
+        ("Visitor", "Visitor pattern", "visitor"),
+        ("Decorator", "Decorator pattern", "decorator"),
+        ("Proxy", "Proxy pattern", "proxy"),
+        ("Facade", "Facade pattern", "facade"),
+        ("Composite", "Composite pattern", "composite"),
+        ("Iterator", "Iterator pattern", "iterator"),
+        ("ChainHandler", "Chain of Responsibility", "chain"),
+        # Fowler / DDD patterns
+        ("Specification", "Specification pattern", "specification"),
+        ("Spec", "Specification pattern", "specification"),
+        ("ValueObject", "value object", "value"),
+        ("Aggregate", "aggregate root", "aggregate"),
+        ("UnitOfWork", "Unit of Work", "unitofwork"),
+        ("DomainEvent", "domain event", "domainevent"),
+        ("IdentityMap", "Identity Map", "identitymap"),
+        ("Policy", "policy", "policy"),
+        ("Plugin", "plugin", "plugin"),
+        # SDK / API
+        ("Sdk", "SDK", "sdk"),
+        ("SDK", "SDK", "sdk"),
+        ("Api", "API client", "api client"),
+        ("API", "API client", "api client"),
+    ]
+
+    if entities:
+        joined_lower = " ".join(parts).lower()
+        for ent in entities:
+            ename = ent.get("name", "") if isinstance(ent, dict) else ent.name
+            ekind = ent.get("kind", "") if isinstance(ent, dict) else ent.kind
+            if ekind not in ("class", "interface"):
+                continue
+            # Exact suffix match first
+            matched = False
+            for suffix, purpose_label, dedup_kw in _ENTITY_SUFFIX_MAP:
+                if ename.endswith(suffix):
+                    if dedup_kw not in joined_lower:
+                        parts.append(purpose_label)
+                        joined_lower = " ".join(parts).lower()
+                    matched = True
+                    break
+            # Fuzzy suffix fallback (distance <= 1, suffixes >= 4 chars)
+            if not matched and len(ename) >= 5:
+                for suffix, purpose_label, dedup_kw in _ENTITY_SUFFIX_MAP:
+                    if _fuzzy_suffix_match(ename, suffix):
+                        if dedup_kw not in joined_lower:
+                            parts.append(purpose_label)
+                            joined_lower = " ".join(parts).lower()
+                        break
+
+    # Pattern detection -- only flag patterns when the file DEFINES one,
+    # not when it merely imports from a module named factory/strategy.
+    joined_check = " ".join(parts).lower()
+
+    # GoF Creational
+    if "factory" not in joined_check:
+        if re.search(r"class \w*Factory|def (?:create|make|build)_\w+.*->|def get_\w+.*factory", head):
+            parts.append("Factory pattern")
+    if "strategy" not in joined_check:
+        if re.search(r"class \w*Strategy|strategy_map|STRATEGIES", head):
+            parts.append("Strategy pattern")
+    if "builder" not in joined_check:
+        if re.search(r"class \w+Builder\b", head):
+            parts.append("Builder pattern")
+    if "singleton" not in joined_check:
+        if re.search(r"getInstance\s*\(|_instance\s*[:=]|private\s+static\s+instance", head):
+            parts.append("Singleton pattern")
+
+    # GoF Structural
+    if "composite" not in joined_check:
+        if re.search(r"class \w+Composite\b|addChild\s*\(|getChildren\s*\(", head):
+            parts.append("Composite pattern")
+    if "proxy" not in joined_check:
+        if re.search(r"class \w+Proxy\b", head):
+            parts.append("Proxy pattern")
+    if "facade" not in joined_check:
+        if re.search(r"class \w+Facade\b", head):
+            parts.append("Facade pattern")
+
+    # GoF Behavioral
+    if "observer" not in joined_check:
+        if re.search(r"class \w+Observer\b|\.subscribe\s*\(|EventEmitter", head):
+            parts.append("Observer pattern")
+    if "command" not in joined_check:
+        if re.search(r"class \w+Command\b", head):
+            parts.append("Command pattern")
+    if "mediator" not in joined_check:
+        if re.search(r"class \w+Mediator\b", head):
+            parts.append("Mediator pattern")
+    if "visitor" not in joined_check:
+        if re.search(r"class \w+Visitor\b|\.accept\s*\(\s*visitor", head):
+            parts.append("Visitor pattern")
+    if "chain" not in joined_check:
+        if re.search(r"class \w+Chain\w*\b|setNext\s*\(|handleNext\s*\(", head):
+            parts.append("Chain of Responsibility")
+    if "memento" not in joined_check:
+        if re.search(r"class \w+Memento\b", head):
+            parts.append("Memento pattern")
+
+    # Fowler / DDD patterns
+    if "specification" not in joined_check:
+        if re.search(r"class \w+Specification\b|isSatisfiedBy\s*\(", head):
+            parts.append("Specification pattern")
+    if "aggregate" not in joined_check:
+        if re.search(r"class \w+Aggregate\b", head):
+            parts.append("aggregate root")
+    if "unitofwork" not in joined_check.replace(" ", ""):
+        if re.search(r"class \w+UnitOfWork\b", head):
+            parts.append("Unit of Work")
+    if "domainevent" not in joined_check.replace(" ", ""):
+        if re.search(r"class \w+DomainEvent\b|class \w+Event\b(?!Emitter|Handler|Listener)", head):
+            parts.append("domain event")
+    if "identitymap" not in joined_check.replace(" ", ""):
+        if re.search(r"class \w+IdentityMap\b", head):
+            parts.append("Identity Map")
+    if "value object" not in joined_check:
+        if re.search(r"class \w+ValueObject\b", head):
+            parts.append("value object")
+
+    # NestJS decorators -- only label when entity-name heuristics didn't
+    # provide a more specific purpose (controller, service, gateway, etc.)
+    _specific_kws = {"controller", "service", "repository", "guard", "gateway",
+                     "adapter", "provider", "processor", "registry", "agent",
+                     "resolver", "scheduler", "worker", "store", "handler",
+                     "interceptor", "pipe", "listener", "subscriber",
+                     "dispatcher", "emitter", "factory", "builder", "observer",
+                     "strategy", "command", "mediator", "visitor", "proxy",
+                     "facade", "composite", "specification", "aggregate",
+                     "policy", "plugin", "manager", "client", "connector",
+                     "sdk", "api client"}
+    joined_after = " ".join(parts).lower()
+    has_specific = any(kw in joined_after for kw in _specific_kws)
+    if not has_specific:
+        if re.search(r"@Controller\b", head):
+            parts.append("API controller")
+        elif re.search(r"@Module\b", head):
+            parts.append("NestJS wiring module")
+        elif re.search(r"@Injectable\b", head):
+            parts.append("NestJS injectable")
+
+    if re.search(r"Router|router\s*\(|createRouter", head):
+        if "router" not in " ".join(parts).lower():
+            parts.append("router")
+    if re.search(r"middleware|Middleware", head):
+        if "middleware" not in " ".join(parts).lower():
+            parts.append("middleware")
+
+    # --- File-stem based heuristics ---
+    stem = Path(path).stem.lower()
+    for sfx in (".test", ".spec", ".e2e", ".stories", ".d"):
+        if stem.endswith(sfx):
+            stem = stem[: -len(sfx)]
+
+    if not parts:
+        if stem.endswith("dto") or stem.endswith("dtos"):
+            parts.append("data transfer object")
+        elif stem.endswith("mapper") or stem.endswith("mappers"):
+            parts.append("data mapper")
+        elif stem.endswith("helpers") or stem.endswith("helper") or stem.endswith("utils") or stem.endswith("util"):
+            parts.append("utility helpers")
+        elif stem.endswith("constants") or stem.endswith("const"):
+            parts.append("constants")
+        elif stem.endswith("types") or stem.endswith("type"):
+            parts.append("type definitions")
+        elif stem.endswith("interfaces") or stem.endswith("interface"):
+            parts.append("interface definitions")
+        elif stem.endswith("enums") or stem.endswith("enum"):
+            parts.append("enum definitions")
+        elif stem.endswith("models") or stem.endswith("model"):
+            parts.append("data model")
+        elif stem.endswith("entities") or stem.endswith("entity"):
+            parts.append("domain entity")
+        elif stem.endswith("errors") or stem.endswith("error") or stem.endswith("exceptions") or stem.endswith("exception"):
+            parts.append("error definitions")
+        elif stem.endswith("factories") or stem.endswith("factory"):
+            parts.append("factory")
+        elif stem.endswith("validators") or stem.endswith("validator"):
+            parts.append("validation")
+        elif stem.endswith("handlers") or stem.endswith("handler"):
+            parts.append("event handler")
+        elif stem.endswith("listeners") or stem.endswith("listener"):
+            parts.append("event listener")
+        elif stem.endswith("middleware"):
+            parts.append("middleware")
+        elif stem.endswith("interceptor"):
+            parts.append("interceptor")
+        elif stem.endswith("guard"):
+            parts.append("access guard")
+        elif stem.endswith("pipe"):
+            parts.append("validation pipe")
+        elif stem.endswith("decorators") or stem.endswith("decorator"):
+            parts.append("decorator")
+        elif stem.endswith("migration"):
+            parts.append("database migration")
+        elif stem.endswith("seed") or stem.endswith("seeder"):
+            parts.append("database seed")
+        elif stem.endswith("fixtures") or stem.endswith("fixture"):
+            parts.append("test fixture")
+        elif stem.endswith("mocks") or stem.endswith("mock"):
+            parts.append("test mock")
+        # Core architecture roles (stem-based)
+        elif stem.endswith("controller") or stem.endswith("controllers"):
+            parts.append("API controller")
+        elif stem.endswith("service") or stem.endswith("services"):
+            parts.append("service")
+        elif stem.endswith("repository") or stem.endswith("repositories"):
+            parts.append("repository")
+        elif stem.endswith("gateway") or stem.endswith("gateways"):
+            parts.append("gateway")
+        elif stem.endswith("registry") or stem.endswith("registries"):
+            parts.append("registry")
+        elif stem.endswith("agent") or stem.endswith("agents"):
+            parts.append("agent")
+        elif stem.endswith("store") or stem.endswith("stores"):
+            parts.append("state store")
+        elif stem.endswith("policy") or stem.endswith("policies"):
+            parts.append("policy")
+        elif stem.endswith("resolver") or stem.endswith("resolvers"):
+            parts.append("resolver")
+        elif stem.endswith("scheduler") or stem.endswith("schedulers"):
+            parts.append("scheduler")
+        elif stem.endswith("worker") or stem.endswith("workers"):
+            parts.append("worker")
+        elif stem.endswith("client") or stem.endswith("clients"):
+            parts.append("client")
+        elif stem.endswith("connector") or stem.endswith("connectors"):
+            parts.append("connector")
+        elif stem.endswith("manager") or stem.endswith("managers"):
+            parts.append("manager")
+        elif stem.endswith("subscriber") or stem.endswith("subscribers"):
+            parts.append("subscriber")
+        elif stem.endswith("dispatcher") or stem.endswith("dispatchers"):
+            parts.append("dispatcher")
+        elif stem.endswith("emitter") or stem.endswith("emitters"):
+            parts.append("emitter")
+        elif stem.endswith("adapter") or stem.endswith("adapters"):
+            parts.append("adapter")
+        elif stem.endswith("provider") or stem.endswith("providers"):
+            parts.append("provider")
+        elif stem.endswith("processor") or stem.endswith("processors"):
+            parts.append("processor")
+        # GoF pattern stems
+        elif stem.endswith("observer"):
+            parts.append("Observer pattern")
+        elif stem.endswith("builder"):
+            parts.append("Builder pattern")
+        elif stem.endswith("visitor"):
+            parts.append("Visitor pattern")
+        elif stem.endswith("mediator"):
+            parts.append("Mediator pattern")
+        elif stem.endswith("facade"):
+            parts.append("Facade pattern")
+        elif stem.endswith("proxy"):
+            parts.append("Proxy pattern")
+        elif stem.endswith("strategy") or stem.endswith("strategies"):
+            parts.append("Strategy pattern")
+        elif stem.endswith("command") or stem.endswith("commands"):
+            parts.append("Command pattern")
+        elif stem.endswith("singleton"):
+            parts.append("Singleton pattern")
+        elif stem.endswith("composite"):
+            parts.append("Composite pattern")
+        # Fowler / DDD pattern stems
+        elif stem.endswith("aggregate") or stem.endswith("aggregates"):
+            parts.append("aggregate root")
+        elif stem.endswith("specification") or stem.endswith("specifications"):
+            parts.append("Specification pattern")
+        elif stem.endswith("plugin") or stem.endswith("plugins"):
+            parts.append("plugin")
+        elif stem.endswith("sdk"):
+            parts.append("SDK")
+        elif stem.endswith("api"):
+            parts.append("API client")
+        elif stem in ("index", "__init__"):
+            parts.append("module entry point")
+        elif stem in ("main", "app"):
+            parts.append("application entry point")
+        elif stem in ("setup", "bootstrap"):
+            parts.append("application bootstrap")
+
+    # --- Fuzzy stem fallback (distance <= 1, stems >= 4 chars) ---
+    _STEM_SUFFIX_MAP = [
+        ("controller", "API controller"), ("service", "service"),
+        ("repository", "repository"), ("gateway", "gateway"),
+        ("registry", "registry"), ("agent", "agent"),
+        ("store", "state store"), ("factory", "factory"),
+        ("strategy", "Strategy pattern"), ("observer", "Observer pattern"),
+        ("builder", "Builder pattern"), ("command", "Command pattern"),
+        ("mediator", "Mediator pattern"), ("visitor", "Visitor pattern"),
+        ("facade", "Facade pattern"), ("proxy", "Proxy pattern"),
+        ("composite", "Composite pattern"), ("aggregate", "aggregate root"),
+        ("specification", "Specification pattern"), ("adapter", "adapter"),
+        ("provider", "provider"), ("processor", "processor"),
+        ("handler", "event handler"), ("listener", "event listener"),
+        ("middleware", "middleware"), ("interceptor", "interceptor"),
+        ("scheduler", "scheduler"), ("worker", "worker"),
+        ("dispatcher", "dispatcher"), ("subscriber", "subscriber"),
+        ("resolver", "resolver"), ("manager", "manager"),
+        ("connector", "connector"), ("client", "client"),
+        ("policy", "policy"), ("plugin", "plugin"),
+    ]
+    if not parts and len(stem) >= 5:
+        for sfx, purpose_label in _STEM_SUFFIX_MAP:
+            if _fuzzy_suffix_match(stem, sfx):
+                parts.append(purpose_label)
+                break
+
+    # --- Content-based heuristics (checked against first 4K) ---
+    head4k = content[:4096]
+    if not parts:
+        if re.search(r"export\s+(?:const\s+)?enum\s+", head4k):
+            parts.append("enum definitions")
+        elif re.search(r"export\s+(?:type|interface)\s+", head4k) and not re.search(
+            r"export\s+(?:class|function|const\s+\w+\s*=)", head4k
+        ):
+            parts.append("type definitions")
+        elif re.search(r"^export\s+\{", head4k, re.MULTILINE) and not re.search(
+            r"^(?:class|function|const|let|var)\s", head4k, re.MULTILINE
+        ):
+            parts.append("barrel re-exports")
+        elif re.search(r"export\s+(?:default\s+)?(?:const\s+)?(?:config|CONFIG|configuration)\b", head4k):
+            parts.append("configuration")
+        elif (
+            language == "python"
+            and re.search(r"^from\s+\.\w+\s+import\s+", head4k, re.MULTILINE)
+            and len(content) < 500
+        ):
+            parts.append("package re-exports")
+
+    # --- Entity-kind heuristic: only type/interface/enum entities => type definitions ---
+    if not parts and entities:
+        kinds = {
+            (ent.get("kind", "") if isinstance(ent, dict) else ent.kind)
+            for ent in entities
+        }
+        if kinds and kinds <= {"interface", "type", "enum"}:
+            if kinds == {"enum"}:
+                parts.append("enum definitions")
+            else:
+                parts.append("type definitions")
+
+    return "; ".join(parts) if parts else "general module"
+
+
+def detect_validation(content: str, language: str) -> bool:
+    if language == "python":
+        # Explicit validation frameworks
+        if re.search(
+            r"pydantic|BaseModel|validator|field_validator|Annotated\[|attrs|@attr",
+            content[:4096],
+        ):
+            return True
+        # Typed dataclass schemas used as validation boundary (frozen=True or type-annotated)
+        if re.search(r"@dataclass", content[:4096]) and re.search(
+            r"frozen\s*=\s*True|def\s+__post_init__|:\s*(?:str|int|float|bool|list|dict|Optional)", content[:4096],
+        ):
+            return True
+        # TypedDict / NamedTuple schemas
+        if re.search(r"TypedDict|NamedTuple", content[:4096]):
+            return True
+        return False
+    return bool(re.search(
+        r"\.safeParse|\.parse\(|zod\.|z\.|Joi\.|yup\.|ajv|validateSchema",
+        content[:4096],
+    ))
+
+
+def path_to_uri(path: str) -> str:
+    """Convert an absolute file path to a file:// URI."""
+    abs_path = os.path.abspath(path)
+    return "file://" + quote(abs_path, safe="/:")
+
+
+def uri_to_path(uri: str) -> str:
+    """Convert a file:// URI to an absolute file path."""
+    if uri.startswith("file://"):
+        return unquote(uri[7:])
+    return uri
+
+
+def find_entity_column(content: str, entity_name: str, line_1based: int) -> int:
+    """Find the 0-based column of *entity_name* on the given 1-based line."""
+    lines = content.split("\n")
+    if line_1based < 1 or line_1based > len(lines):
+        return 0
+    line_text = lines[line_1based - 1]
+    idx = line_text.find(entity_name)
+    return max(idx, 0)
+
+
+# ---------------------------------------------------------------------------
+# Python parser
+# ---------------------------------------------------------------------------
+
+def parse_python(path: str, content: str, repo: str, mtime: float) -> FileResult:
+    imports: list[str] = []
+    exports_abstract: list[str] = []
+    implements: list[str] = []
+    extends: list[str] = []
+    entities: list[Entity] = []
+    imported_names: list[ImportedName] = []
+    exported_names: list[str] = []
+
+    try:
+        tree = ast.parse(content, filename=path)
+
+        for node in ast.iter_child_nodes(tree):
+            # -- imports --
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append(alias.name)
+                    local = alias.asname or alias.name.split(".")[-1]
+                    imported_names.append(ImportedName(
+                        local_name=local,
+                        original_name=alias.name,
+                        module=alias.name,
+                    ))
+            elif isinstance(node, ast.ImportFrom):
+                mod = node.module or ""
+                if mod:
+                    imports.append(mod)
+                for alias in node.names:
+                    local = alias.asname or alias.name
+                    imported_names.append(ImportedName(
+                        local_name=local,
+                        original_name=alias.name,
+                        module=mod,
+                    ))
+
+            # -- classes --
+            elif isinstance(node, ast.ClassDef):
+                methods = []
+                decorators = [
+                    _decorator_name(d) for d in node.decorator_list
+                ]
+                for item in node.body:
+                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        methods.append(item.name)
+                bases_list = [_name_of(b) for b in node.bases if _name_of(b)]
+                entities.append(Entity(
+                    name=node.name,
+                    kind="class",
+                    line=node.lineno,
+                    methods=methods,
+                    decorators=decorators,
+                    bases=bases_list,
+                ))
+                exported_names.append(node.name)
+                extends.extend(bases_list)
+                for b in bases_list:
+                    if b in ("ABC", "Protocol") or "Base" in b:
+                        implements.append(b)
+
+            # -- functions --
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                decorators = [
+                    _decorator_name(d) for d in node.decorator_list
+                ]
+                entities.append(Entity(
+                    name=node.name,
+                    kind="function",
+                    line=node.lineno,
+                    methods=[],
+                    decorators=decorators,
+                    bases=[],
+                ))
+                exported_names.append(node.name)
+
+            # -- top-level assignments (constants, type aliases) --
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.isupper():
+                        exported_names.append(target.id)
+
+    except SyntaxError:
+        # Fallback: regex for imports only
+        for m in re.finditer(
+            r"^\s*(?:from\s+([\w.]+)\s+import|import\s+([\w.]+))",
+            content, re.MULTILINE,
+        ):
+            imp = m.group(1) or m.group(2)
+            if imp:
+                imports.append(imp)
+
+    # Detect ABC / Protocol definitions
+    for m in PY_ABC_RE.finditer(content):
+        name = m.group(0).split("(")[0].split()[-1]
+        if name not in exports_abstract:
+            exports_abstract.append(name)
+
+    return FileResult(
+        path=path, language="python", repo=repo, mtime=mtime,
+        content_hash=file_hash(path),
+        imports=imports, exports_abstract=exports_abstract,
+        implements=implements, extends=extends,
+        purpose=infer_purpose(path, content, "python", [e.to_dict() for e in entities]),
+        naming_convention=detect_naming(path),
+        has_validation=detect_validation(content, "python"),
+        entities=[e.to_dict() for e in entities],
+        imported_names=[n.to_dict() for n in imported_names],
+        exported_names=exported_names,
+    )
+
+
+def _decorator_name(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    if isinstance(node, ast.Call):
+        return _decorator_name(node.func)
+    return ""
+
+
+def _name_of(node: ast.expr) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# TypeScript parser (tree-sitter)
+# ---------------------------------------------------------------------------
+
+def _ts_get_decorators(node) -> list[str]:  # type: ignore[no-untyped-def]
+    """Extract @Decorator names from a node's preceding decorator nodes."""
+    decorators = []
+    for child in node.children:
+        if child.type == "decorator":
+            # decorator -> @expression -- get the identifier
+            for dchild in child.children:
+                if dchild.type == "identifier":
+                    decorators.append(dchild.text.decode("utf-8"))
+                elif dchild.type == "call_expression":
+                    fn = dchild.child_by_field_name("function")
+                    if fn:
+                        decorators.append(fn.text.decode("utf-8").split(".")[-1])
+    return decorators
+
+
+def _ts_get_heritage(node) -> tuple[list[str], list[str]]:  # type: ignore[no-untyped-def]
+    """Extract extends and implements from class_heritage."""
+    extends: list[str] = []
+    implements: list[str] = []
+    for child in node.children:
+        if child.type == "class_heritage":
+            for hchild in child.children:
+                if hchild.type == "extends_clause":
+                    for t in hchild.children:
+                        if t.type in ("type_identifier", "identifier"):
+                            extends.append(t.text.decode("utf-8"))
+                elif hchild.type == "implements_clause":
+                    for t in hchild.children:
+                        if t.type in ("type_identifier", "identifier"):
+                            implements.append(t.text.decode("utf-8"))
+    return extends, implements
+
+
+def _ts_get_methods(node) -> list[str]:  # type: ignore[no-untyped-def]
+    """Extract method/property names from a class or interface body."""
+    methods = []
+    body = node.child_by_field_name("body")
+    if not body:
+        return methods
+    skip = {"constructor", "if", "for", "while", "switch", "return"}
+    for member in body.children:
+        if member.type in ("method_definition", "method_signature",
+                           "public_field_definition", "property_signature",
+                           "abstract_method_signature"):
+            name_node = member.child_by_field_name("name")
+            if name_node:
+                name = name_node.text.decode("utf-8")
+                if name not in skip:
+                    methods.append(name)
+    return methods
+
+
+# NestJS decorators that imply constructor-parameter dependency injection.
+_NESTJS_INJECTION_DECOS: frozenset[str] = frozenset({
+    "Injectable", "Controller", "Module", "Guard", "Interceptor", "Pipe", "Resolver",
+})
+
+
+def _ts_get_constructor_injections(node) -> list[str]:  # type: ignore[no-untyped-def]
+    """Extract interface/type names from constructor parameter types and @Inject decorators.
+
+    Handles NestJS constructor injection patterns where typed constructor parameters
+    declare interface dependencies. Only PascalCase names are returned to avoid
+    tracking primitive or built-in types.
+    """
+    injected: list[str] = []
+    body = node.child_by_field_name("body")
+    if not body:
+        return injected
+    for member in body.children:
+        if member.type != "method_definition":
+            continue
+        name_node = member.child_by_field_name("name")
+        if not name_node or not name_node.text:
+            continue
+        if name_node.text.decode("utf-8") != "constructor":
+            continue
+        params = member.child_by_field_name("parameters")
+        if not params:
+            continue
+        for param in params.children:
+            if param.type not in ("required_parameter", "optional_parameter"):
+                continue
+            # Check for @Inject(TOKEN) decorator on the parameter
+            for child in param.children:
+                if child.type == "decorator":
+                    for dc in child.children:
+                        if dc.type == "call_expression":
+                            fn = dc.child_by_field_name("function")
+                            if fn and fn.text and fn.text.decode("utf-8") == "Inject":
+                                args = dc.child_by_field_name("arguments")
+                                if args:
+                                    for arg in args.children:
+                                        if arg.type in ("identifier", "string", "template_string"):
+                                            text = arg.text
+                                            if text:
+                                                token = text.decode("utf-8").strip("'\"`")
+                                                if token and token[0].isupper():
+                                                    injected.append(token)
+            # Check type annotation on the parameter
+            type_ann = param.child_by_field_name("type")
+            if type_ann:
+                for tc in type_ann.children:
+                    if tc.type in ("type_identifier", "identifier"):
+                        ttext = tc.text
+                        if ttext:
+                            tname = ttext.decode("utf-8")
+                            if tname and tname[0].isupper():
+                                injected.append(tname)
+    return injected
+
+
+def _ts_get_obj_keys(node) -> list[str]:  # type: ignore[no-untyped-def]
+    """Extract top-level property names from an object literal."""
+    keys = []
+    for child in node.children:
+        if child.type in ("pair", "method_definition", "shorthand_property_identifier"):
+            if child.type == "shorthand_property_identifier":
+                keys.append(child.text.decode("utf-8"))
+            else:
+                key = child.child_by_field_name("key")
+                if key:
+                    keys.append(key.text.decode("utf-8"))
+    return keys
+
+
+def parse_typescript_treesitter(
+    path: str, content: str, repo: str, mtime: float,
+) -> FileResult:
+    """Parse a TypeScript file using tree-sitter for precise entity extraction."""
+    lang = _TSX_LANG if path.endswith(".tsx") else _TS_LANG
+    parser = _TsParser(lang)
+    tree = parser.parse(content.encode("utf-8"))
+    root = tree.root_node
+
+    imports: list[str] = []
+    exports_abstract: list[str] = []
+    implements_list: list[str] = []
+    extends_list: list[str] = []
+    entities: list[Entity] = []
+    imported_names: list[ImportedName] = []
+    exported_names: list[str] = []
+
+    for node in root.children:
+        is_export = node.type == "export_statement"
+        target = node
+        if is_export:
+            # The actual declaration is a child of export_statement.
+            # Skip keywords, decorators, and punctuation to find the declaration.
+            for child in node.children:
+                if child.type in ("export", "default", "comment", "decorator",
+                                  "{", "}", ",", ";"):
+                    continue
+                target = child
+                break
+
+        # -- Imports --
+        if node.type == "import_statement":
+            source_node = node.child_by_field_name("source")
+            if source_node:
+                specifier = source_node.text.decode("utf-8").strip("'\"")
+                imports.append(specifier)
+                # Extract named imports
+                for child in node.children:
+                    if child.type == "import_clause":
+                        for ic in child.children:
+                            if ic.type == "identifier":
+                                # default import
+                                imported_names.append(ImportedName(
+                                    local_name=ic.text.decode("utf-8"),
+                                    original_name="default",
+                                    module=specifier,
+                                ))
+                            elif ic.type == "named_imports":
+                                for spec in ic.children:
+                                    if spec.type == "import_specifier":
+                                        name_node = spec.child_by_field_name("name")
+                                        alias_node = spec.child_by_field_name("alias")
+                                        if name_node:
+                                            orig = name_node.text.decode("utf-8")
+                                            local = alias_node.text.decode("utf-8") if alias_node else orig
+                                            imported_names.append(ImportedName(
+                                                local_name=local,
+                                                original_name=orig,
+                                                module=specifier,
+                                            ))
+
+        # -- Class --
+        elif target.type == "class_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = name_node.text.decode("utf-8")
+            line = target.start_point[0] + 1
+            decorators = _ts_get_decorators(node if is_export else target)
+            ext, impl = _ts_get_heritage(target)
+            methods = _ts_get_methods(target)
+            extends_list.extend(ext)
+            implements_list.extend(impl)
+            # NestJS @Injectable/@Controller/@Module: constructor param types are
+            # interface dependencies that should create CALLS_API edges.
+            if _NESTJS_INJECTION_DECOS.intersection(decorators):
+                constructor_deps = _ts_get_constructor_injections(target)
+                implements_list.extend(constructor_deps)
+            # Check if abstract
+            is_abstract = any(c.type == "abstract" for c in target.children)
+            if is_abstract:
+                exports_abstract.append(name)
+            entities.append(Entity(
+                name=name, kind="class", line=line,
+                methods=methods, decorators=decorators, bases=ext + impl,
+            ))
+            exported_names.append(name)
+
+        # -- Interface --
+        elif target.type == "interface_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = name_node.text.decode("utf-8")
+            line = target.start_point[0] + 1
+            methods = _ts_get_methods(target)
+            exports_abstract.append(name)
+            entities.append(Entity(
+                name=name, kind="interface", line=line,
+                methods=methods, decorators=[], bases=[],
+            ))
+            exported_names.append(name)
+
+        # -- Type alias --
+        elif target.type == "type_alias_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = name_node.text.decode("utf-8")
+            line = target.start_point[0] + 1
+            entities.append(Entity(
+                name=name, kind="type", line=line,
+                methods=[], decorators=[], bases=[],
+            ))
+            exported_names.append(name)
+
+        # -- Enum --
+        elif target.type == "enum_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = name_node.text.decode("utf-8")
+            line = target.start_point[0] + 1
+            entities.append(Entity(
+                name=name, kind="enum", line=line,
+                methods=[], decorators=[], bases=[],
+            ))
+            exported_names.append(name)
+
+        # -- Function --
+        elif target.type == "function_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = name_node.text.decode("utf-8")
+            line = target.start_point[0] + 1
+            decorators = _ts_get_decorators(node if is_export else target)
+            entities.append(Entity(
+                name=name, kind="function", line=line,
+                methods=[], decorators=decorators, bases=[],
+            ))
+            exported_names.append(name)
+
+        # -- Lexical declaration (const/let) --
+        elif target.type == "lexical_declaration":
+            for declarator in target.children:
+                if declarator.type != "variable_declarator":
+                    continue
+                name_node = declarator.child_by_field_name("name")
+                if not name_node or name_node.type != "identifier":
+                    continue
+                name = name_node.text.decode("utf-8")
+                line = declarator.start_point[0] + 1
+                value = declarator.child_by_field_name("value")
+                if not value:
+                    continue
+                # Object literal: extract keys as methods
+                if value.type == "object":
+                    obj_keys = _ts_get_obj_keys(value)
+                    entities.append(Entity(
+                        name=name, kind="function", line=line,
+                        methods=obj_keys, decorators=[], bases=[],
+                    ))
+                # new Constructor(...)
+                elif value.type == "new_expression":
+                    entities.append(Entity(
+                        name=name, kind="function", line=line,
+                        methods=[], decorators=[], bases=[],
+                    ))
+                # Arrow function or call expression
+                elif value.type in ("arrow_function", "call_expression"):
+                    entities.append(Entity(
+                        name=name, kind="function", line=line,
+                        methods=[], decorators=[], bases=[],
+                    ))
+                # Other const (e.g., z.object, string literal, etc.)
+                else:
+                    entities.append(Entity(
+                        name=name, kind="function", line=line,
+                        methods=[], decorators=[], bases=[],
+                    ))
+                exported_names.append(name)
+
+    file_lang = "tsx" if path.endswith(".tsx") else "typescript"
+    return FileResult(
+        path=path, language=file_lang, repo=repo, mtime=mtime,
+        content_hash=file_hash(path),
+        imports=imports, exports_abstract=exports_abstract,
+        implements=implements_list, extends=extends_list,
+        purpose=infer_purpose(path, content, "typescript", [e.to_dict() for e in entities]),
+        naming_convention=detect_naming(path),
+        has_validation=detect_validation(content, "typescript"),
+        entities=[e.to_dict() for e in entities],
+        imported_names=[n.to_dict() for n in imported_names],
+        exported_names=exported_names,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Worker
+# ---------------------------------------------------------------------------
+
+def parse_file(args: tuple[str, str, str]) -> Optional[FileResult]:
+    path, language, repo = args
+    try:
+        mtime = os.path.getmtime(path)
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            content = f.read()
+        if language == "python":
+            return parse_python(path, content, repo, mtime)
+        return parse_typescript_treesitter(path, content, repo, mtime)
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# File discovery
+# ---------------------------------------------------------------------------
+
+def discover_files(root: str) -> list[tuple[str, str, str]]:
+    results: list[tuple[str, str, str]] = []
+    root_path = Path(root).resolve()
+
+    def _walk(dir_path: Path, repo: str):
+        try:
+            with os.scandir(dir_path) as it:
+                for entry in it:
+                    if entry.name in SKIP_DIRS:
+                        continue
+                    if entry.is_dir(follow_symlinks=False):
+                        child_repo = repo
+                        if entry.name != ".git" and (dir_path / entry.name / ".git").exists():
+                            child_repo = entry.name
+                        _walk(dir_path / entry.name, child_repo)
+                    elif entry.is_file(follow_symlinks=False):
+                        name = entry.name
+                        if name.endswith(".py"):
+                            results.append((entry.path, "python", repo))
+                        elif (name.endswith(".ts") or name.endswith(".tsx")) and not name.endswith(".d.ts"):
+                            results.append((entry.path, "typescript", repo))
+        except PermissionError:
+            pass
+
+    _walk(root_path, root_path.name)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Incremental cache
+# ---------------------------------------------------------------------------
+
+def load_cache(root: str) -> dict:
+    cache_path = os.path.join(root, CACHE_FILE)
+    if os.path.exists(cache_path):
+        try:
+            with open(cache_path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {}
+
+
+def save_cache(root: str, cache: dict):
+    cache_path = os.path.join(root, CACHE_FILE)
+    with open(cache_path, "w") as f:
+        json.dump(cache, f)
+
+
+# ---------------------------------------------------------------------------
+# Import resolution
+# ---------------------------------------------------------------------------
+# TypeScript path alias resolution (tsconfig.json "paths")
+# ---------------------------------------------------------------------------
+
+def _load_ts_path_aliases(root: str) -> dict[str, str]:
+    """Scan for tsconfig.json files and build a global alias -> absolute directory map.
+
+    For each tsconfig with compilerOptions.paths, resolves alias patterns like
+    ``@sdk/* -> ['../../sdk/src/*']`` relative to the tsconfig's directory.
+
+    Returns {alias_prefix: absolute_directory} e.g. {"@sdk/": "/abs/path/to/sdk/src/"}.
+    """
+    import json as _json
+
+    alias_map: dict[str, str] = {}
+    # Walk up to 4 directory levels for tsconfig files (covers monorepo structures)
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Skip node_modules, .git, dist, build
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in ("node_modules", ".git", "dist", "build", ".next", ".cache")
+        ]
+        depth = dirpath[len(root):].count(os.sep)
+        if depth > 5:
+            dirnames.clear()
+            continue
+        for fname in filenames:
+            if fname == "tsconfig.json":
+                tsconfig_path = os.path.join(dirpath, fname)
+                try:
+                    with open(tsconfig_path, "r") as f:
+                        raw = f.read()
+                    # Strip single-line comments (tsconfig allows them)
+                    raw = re.sub(r"//.*$", "", raw, flags=re.MULTILINE)
+                    # Strip trailing commas before } or ]
+                    raw = re.sub(r",(\s*[}\]])", r"\1", raw)
+                    data = _json.loads(raw)
+                    paths = data.get("compilerOptions", {}).get("paths", {})
+                    for alias_pattern, targets in paths.items():
+                        if not alias_pattern.endswith("/*") or not targets:
+                            continue
+                        prefix = alias_pattern[:-1]  # "@sdk/*" -> "@sdk/"
+                        target = targets[0]  # Take first target
+                        if not target.endswith("/*"):
+                            continue
+                        target_dir = target[:-2]  # "./*" -> ".", "../../sdk/src/*" -> "../../sdk/src"
+                        abs_target = os.path.normpath(os.path.join(dirpath, target_dir))
+                        # If target dir has a `src/` subdirectory, prefer it
+                        # (common monorepo pattern: @sdk/* -> ['./*'] maps to pkg root,
+                        # but actual source lives in pkg/src/)
+                        src_subdir = os.path.join(abs_target, "src")
+                        effective_target = src_subdir if os.path.isdir(src_subdir) else abs_target
+                        if os.path.isdir(abs_target):
+                            # Longer (more specific) prefixes take priority
+                            if prefix not in alias_map or len(effective_target) > len(alias_map[prefix]):
+                                alias_map[prefix] = effective_target
+                except Exception:
+                    continue
+    return alias_map
+
+
+def _resolve_ts_path_alias(
+    imp: str,
+    source_path: str,
+    root: str,
+    path_to_id: dict[str, str],
+    alias_map: dict[str, str],
+) -> Optional[str]:
+    """Resolve a TypeScript import like '@sdk/llm/llmClientApi' using tsconfig paths.
+
+    Tries the most specific alias prefix first (longest match).
+    """
+    if not alias_map:
+        return None
+
+    # Sort by prefix length descending so "@agent-upgraide/" matches before "@a/"
+    for prefix in sorted(alias_map, key=len, reverse=True):
+        if imp.startswith(prefix):
+            remainder = imp[len(prefix):]
+            base_dir = alias_map[prefix]
+            resolved = os.path.normpath(os.path.join(base_dir, remainder))
+            for ext in ("", ".ts", ".tsx", "/index.ts", "/index.tsx", ".js", "/index.js"):
+                candidate = resolved + ext
+                if candidate in path_to_id:
+                    return path_to_id[candidate]
+                # path_to_id may use relative paths -- try relative form too
+                try:
+                    rel_candidate = os.path.relpath(candidate, root) if root else candidate
+                except ValueError:
+                    rel_candidate = candidate
+                if rel_candidate in path_to_id:
+                    return path_to_id[rel_candidate]
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+def resolve_import(
+    imp: str,
+    source_path: str,
+    root: str,
+    path_to_id: dict[str, str],
+    language: str,
+    ts_path_aliases: "dict[str, str] | None" = None,
+) -> Optional[str]:
+    if language == "typescript":
+        if not imp.startswith(".") and not imp.startswith("/"):
+            # Try tsconfig paths alias resolution before giving up
+            resolved_via_alias = _resolve_ts_path_alias(
+                imp, source_path, root, path_to_id, ts_path_aliases or {},
+            )
+            if resolved_via_alias:
+                return resolved_via_alias
+            return None
+        source_dir = os.path.dirname(source_path)
+        resolved = os.path.normpath(os.path.join(source_dir, imp))
+        for ext in ("", ".ts", ".tsx", "/index.ts", "/index.tsx", ".js", "/index.js"):
+            candidate = resolved + ext
+            if candidate in path_to_id:
+                return path_to_id[candidate]
+    elif language == "python":
+        parts = imp.split(".")
+        # Build candidate base directories: walk up from source_dir to root,
+        # collecting every directory that contains the first import segment.
+        bases: list[str] = [root, os.path.dirname(source_path)]
+        first_segment = parts[0] if parts else ""
+        cur = os.path.dirname(source_path)
+        while cur and cur >= root:
+            if os.path.isdir(os.path.join(cur, first_segment)):
+                if cur not in bases:
+                    bases.append(cur)
+            parent = os.path.dirname(cur)
+            if parent == cur:
+                break
+            cur = parent
+        for base in bases:
+            # Try direct .py file first, then __init__.py
+            for ext in (".py", "/__init__.py"):
+                if ext == ".py":
+                    candidate = os.path.join(base, *parts) + ext
+                else:
+                    candidate = os.path.join(base, *parts, "__init__.py")
+                candidate = os.path.normpath(candidate)
+                if candidate in path_to_id:
+                    return path_to_id[candidate]
+            # Gap 4 fix: "from modules.commons import json_doc_sqlite"
+            # The AST records module="modules.commons", name="json_doc_sqlite".
+            # Check if the imported names include a sub-module file.
+            if len(parts) >= 2:
+                pkg_dir = os.path.join(base, *parts)
+                if os.path.isdir(pkg_dir):
+                    # This is a package -- imported names may be sub-modules.
+                    # resolve_import is called per import specifier (module level),
+                    # so we already resolved to __init__.py above. The sub-module
+                    # resolution happens in _resolve_submodule_imports below.
+                    pass
+    return None
+
+
+def _resolve_submodule_imports(
+    result: "FileResult",
+    root: str,
+    path_to_id: dict[str, str],
+) -> list[str]:
+    """
+    Fix Python 'from package import submodule' patterns.
+
+    When `from modules.commons import json_doc_sqlite` is parsed, the AST
+    records module='modules.commons' and name='json_doc_sqlite'. If
+    json_doc_sqlite.py exists as a sibling file, add it as an extra import.
+    """
+    extra_imports: list[str] = []
+    if result.language != "python":
+        return extra_imports
+
+    # Build base dirs: walk up from source to root (same as resolve_import)
+    all_bases: list[str] = [root, os.path.dirname(result.path)]
+    for imp_name in result.imported_names:
+        mod = imp_name.get("module", "") if isinstance(imp_name, dict) else imp_name.module
+        orig = imp_name.get("original", "") if isinstance(imp_name, dict) else imp_name.original_name
+        if not mod or not orig:
+            continue
+        parts = mod.split(".")
+        first_seg = parts[0] if parts else ""
+
+        # Collect all viable bases including walk-up
+        bases = list(all_bases)
+        cur = os.path.dirname(result.path)
+        while cur and cur >= root:
+            if os.path.isdir(os.path.join(cur, first_seg)):
+                if cur not in bases:
+                    bases.append(cur)
+            parent = os.path.dirname(cur)
+            if parent == cur:
+                break
+            cur = parent
+
+        for base in bases:
+            submod_path = os.path.normpath(os.path.join(base, *parts, orig + ".py"))
+            if submod_path in path_to_id:
+                target_id = path_to_id[submod_path]
+                if target_id not in extra_imports:
+                    extra_imports.append(target_id)
+                break
+
+    return extra_imports
+
+
+def make_node_id(path: str, root: str) -> str:
+    rel = os.path.relpath(path, root).replace(os.sep, "/")
+    for ext in (".tsx", ".ts", ".py"):
+        if rel.endswith(ext):
+            rel = rel[: -len(ext)]
+            break
+    if rel.endswith("/index"):
+        rel = rel[: -len("/index")]
+    return rel
+
+
+# ---------------------------------------------------------------------------
+# Graph building
+# ---------------------------------------------------------------------------
+
+def build_graph(
+    results: list[FileResult], root: str,
+) -> tuple[list[dict], list[dict]]:
+    path_to_id: dict[str, str] = {}
+    id_to_result: dict[str, FileResult] = {}
+
+    for r in results:
+        node_id = make_node_id(r.path, root)
+        path_to_id[r.path] = node_id
+        id_to_result[node_id] = r
+
+    # Load tsconfig.json path aliases for resolving @sdk/*, @agent-*/* etc.
+    ts_path_aliases = _load_ts_path_aliases(root)
+    if ts_path_aliases:
+        print(f"[belief-map] Loaded {len(ts_path_aliases)} TS path aliases", file=sys.stderr)
+
+    # Map: abstract/interface name -> defining node id
+    abstract_providers: dict[str, str] = {}
+    for nid, r in id_to_result.items():
+        for ab in r.exports_abstract:
+            abstract_providers[ab] = nid
+
+    # Also register ALL interface-kind entities regardless of whether they are in
+    # exports_abstract (which only captures explicit exports). Non-exported interfaces
+    # used locally and interfaces from imported modules are resolved by bare name at
+    # the CALLS_API detection step, so they must be present in this map.
+    for nid, r in id_to_result.items():
+        for ent in r.entities:
+            ent_kind = ent.get("kind", "") if isinstance(ent, dict) else getattr(ent, "kind", "")
+            ent_name = ent.get("name", "") if isinstance(ent, dict) else getattr(ent, "name", "")
+            if ent_kind == "interface" and ent_name and ent_name not in abstract_providers:
+                abstract_providers[ent_name] = nid
+
+    # Map: (node_id, entity_name) -> True  (for cross-file entity lookups)
+    entity_index: dict[str, str] = {}  # "EntityName" -> "node_id"
+    for nid, r in id_to_result.items():
+        for name in r.exported_names:
+            # First definition wins (avoids overwrites from re-exports)
+            if name not in entity_index:
+                entity_index[name] = nid
+
+    # Register any entity that is used as a base class by other classes.
+    # This catches BaseModel, CanActivate, BaseProcessor, BaseAgent, etc.
+    # that are defined in the codebase but not marked as abstract/interface.
+    all_bases: set[str] = set()
+    for r in results:
+        for base in r.implements + r.extends:
+            all_bases.add(base)
+    for base_name in all_bases:
+        if base_name not in abstract_providers and base_name in entity_index:
+            abstract_providers[base_name] = entity_index[base_name]
+
+    nodes: list[dict] = []
+    edges: list[dict] = []
+    seen_edges: set[tuple] = set()
+
+    for node_id, r in id_to_result.items():
+        rel_path = os.path.relpath(r.path, root)
+
+        # Gap 3 fix: enrich purpose with entity-name heuristics
+        purpose = r.purpose
+        if r.entities and purpose in ("general module", "NestJS wiring module", "NestJS injectable"):
+            enhanced = infer_purpose(r.path, "", r.language, r.entities)
+            if enhanced not in ("general module", "NestJS wiring module", "NestJS injectable"):
+                purpose = enhanced
+
+        # -- build node with entities --
+        node: dict = {
+            "id": node_id,
+            "language": r.language,
+            "path": rel_path,
+            "repo": r.repo,
+            "invariant": {
+                "naming": r.naming_convention,
+                "package": r.repo,
+            },
+            "purpose": purpose,
+        }
+        if r.entities:
+            node["entities"] = r.entities
+        nodes.append(node)
+
+        # -- Gap 4: sub-module Python imports --
+        extra_submod_ids = _resolve_submodule_imports(r, root, path_to_id)
+        for target_id in extra_submod_ids:
+            if target_id != node_id:
+                edge_key = (node_id, target_id, "IMPORTS")
+                if edge_key not in seen_edges:
+                    seen_edges.add(edge_key)
+                    target_r = id_to_result.get(target_id)
+                    via_base = bool(target_r and target_r.exports_abstract)
+                    edges.append({
+                        "source": node_id,
+                        "target": target_id,
+                        "type": "IMPORTS",
+                        "via_base": via_base,
+                    })
+
+        # -- module-level IMPORTS edges --
+        for imp in r.imports:
+            target_id = resolve_import(imp, r.path, root, path_to_id, r.language, ts_path_aliases)
+            if target_id and target_id != node_id:
+                edge_key = (node_id, target_id, "IMPORTS")
+                if edge_key not in seen_edges:
+                    seen_edges.add(edge_key)
+                    target_r = id_to_result.get(target_id)
+                    via_base = bool(target_r and target_r.exports_abstract)
+                    edges.append({
+                        "source": node_id,
+                        "target": target_id,
+                        "type": "IMPORTS",
+                        "via_base": via_base,
+                    })
+
+        # -- CALLS_API edges (implements/extends + entity :bases) --
+        # Source 1: FileResult.implements + extends (from heritage clauses)
+        calls_api_targets: set[str] = set()
+        for iface in r.implements + r.extends:
+            provider_id = abstract_providers.get(iface)
+            if provider_id and provider_id != node_id:
+                calls_api_targets.add(provider_id)
+
+        # Source 2: Entity :bases cross-reference (catches bases not in
+        # heritage clauses, and bases defined in other modules)
+        for ent in r.entities:
+            for base_name in ent.get("bases", []):
+                provider_id = abstract_providers.get(base_name)
+                if provider_id and provider_id != node_id:
+                    calls_api_targets.add(provider_id)
+
+        for provider_id in calls_api_targets:
+            edge_key = (node_id, provider_id, "CALLS_API")
+            if edge_key not in seen_edges:
+                seen_edges.add(edge_key)
+                edges.append({
+                    "source": node_id,
+                    "target": provider_id,
+                    "type": "CALLS_API",
+                    "via_interface": True,
+                })
+
+        # -- DATA_FLOWS_TO edges --
+        for imp in r.imports:
+            target_id = resolve_import(imp, r.path, root, path_to_id, r.language, ts_path_aliases)
+            if target_id and target_id != node_id:
+                target_r = id_to_result.get(target_id)
+                if target_r and target_r.has_validation:
+                    edge_key = (node_id, target_id, "DATA_FLOWS_TO")
+                    if edge_key not in seen_edges:
+                        seen_edges.add(edge_key)
+                        edges.append({
+                            "source": node_id,
+                            "target": target_id,
+                            "type": "DATA_FLOWS_TO",
+                            "validated": True,
+                        })
+
+        # -- entity-level REFERENCES edges --
+        # For each imported name, link source_entity -> target_entity
+        for imp_name in r.imported_names:
+            target_id = resolve_import(
+                imp_name["module"], r.path, root, path_to_id, r.language, ts_path_aliases,
+            )
+            if not target_id or target_id == node_id:
+                continue
+            target_r = id_to_result.get(target_id)
+            if not target_r:
+                continue
+
+            orig = imp_name["original"]
+            local = imp_name["local"]
+
+            # Find matching entity in target
+            target_entity = None
+            for ent in target_r.entities:
+                if ent["name"] == orig or (orig == "default" and ent["name"] == local):
+                    target_entity = ent["name"]
+                    break
+            if not target_entity:
+                # Still useful: the name is exported even if not a class/function entity
+                if orig in target_r.exported_names:
+                    target_entity = orig
+                elif orig == "default" and target_r.exported_names:
+                    target_entity = target_r.exported_names[0]
+                else:
+                    continue
+
+            # Find which local entities reference this imported name
+            referencing_entities = _find_local_references(r.entities, local)
+
+            if referencing_entities:
+                for ref_ent in referencing_entities:
+                    edge_key = (
+                        f"{node_id}::{ref_ent}",
+                        f"{target_id}::{target_entity}",
+                        "REFERENCES",
+                    )
+                    if edge_key not in seen_edges:
+                        seen_edges.add(edge_key)
+                        edges.append({
+                            "source": f"{node_id}::{ref_ent}",
+                            "target": f"{target_id}::{target_entity}",
+                            "type": "REFERENCES",
+                        })
+            else:
+                # Module-level reference (not inside a specific entity)
+                edge_key = (node_id, f"{target_id}::{target_entity}", "REFERENCES")
+                if edge_key not in seen_edges:
+                    seen_edges.add(edge_key)
+                    edges.append({
+                        "source": node_id,
+                        "target": f"{target_id}::{target_entity}",
+                        "type": "REFERENCES",
+                    })
+
+    # -- Gap 2: BOUNDARY violation detection --
+    # -- HTTP_CALLS edges (cross-service HTTP client detection) --
+    # Detect modules with entities named *Client, *ClientService, *ClientApi,
+    # *External, *Remote and infer the target service from the class name.
+    _HTTP_CLIENT_SUFFIXES = ("Client", "ClientService", "ClientApi", "External", "Remote")
+    _REPO_NAMES = {r.repo for r in results}
+    for node_id, r in id_to_result.items():
+        for ent in r.entities:
+            ent_name = ent.get("name", "")
+            if not any(ent_name.endswith(sfx) for sfx in _HTTP_CLIENT_SUFFIXES):
+                continue
+            # Extract target service name from class name:
+            # AgentExternalClient -> agent, McpHubClientService -> mcp-hub
+            # LLMClientRemote -> llm
+            stem = ent_name
+            for sfx in sorted(_HTTP_CLIENT_SUFFIXES, key=len, reverse=True):
+                if stem.endswith(sfx):
+                    stem = stem[: -len(sfx)]
+                    break
+            if not stem:
+                continue
+            # Convert PascalCase to kebab-case for repo matching
+            kebab = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", stem).lower()
+            # Try to match against known repo names
+            target_repo = None
+            for repo in _REPO_NAMES:
+                if repo == r.repo:
+                    continue  # skip self
+                repo_lower = repo.lower()
+                if kebab == repo_lower or kebab.startswith(repo_lower) or repo_lower.startswith(kebab):
+                    target_repo = repo
+                    break
+            if target_repo:
+                edge_key = (node_id, target_repo, "HTTP_CALLS")
+                if edge_key not in seen_edges:
+                    seen_edges.add(edge_key)
+                    edges.append({
+                        "source": node_id,
+                        "target": target_repo,
+                        "type": "HTTP_CALLS",
+                        "transport": "http",
+                        "client_entity": ent_name,
+                    })
+
+    # Domain modules should not import directly from infrastructure without
+    # going through an interface (via_base). Flag violations.
+    for edge in edges:
+        if edge["type"] != "IMPORTS":
+            continue
+        src = edge["source"]
+        tgt = edge["target"]
+        src_purpose = id_to_result.get(src, None)
+        tgt_purpose = id_to_result.get(tgt, None)
+        if not src_purpose or not tgt_purpose:
+            continue
+        src_p = (src_purpose.purpose or "").lower()
+        tgt_p = (tgt_purpose.purpose or "").lower()
+        # Domain importing infrastructure without going through base class
+        if ("domain" in src_p and "infrastructure" in tgt_p and not edge.get("via_base")):
+            edges.append({
+                "source": src, "target": tgt,
+                "type": "VIOLATION",
+                "rule": "boundary",
+                "detail": "domain imports infrastructure without abstract base",
+            })
+        # UI/component importing infrastructure directly
+        if ("ui component" in src_p and "infrastructure" in tgt_p and not edge.get("via_base")):
+            edges.append({
+                "source": src, "target": tgt,
+                "type": "VIOLATION",
+                "rule": "boundary",
+                "detail": "UI imports infrastructure without abstract base",
+            })
+
+    return nodes, edges
+
+
+def _find_local_references(entities: list[dict], name: str) -> list[str]:
+    """
+    Heuristic: check which local entities might reference the imported name.
+    If a class extends/implements the name, or has it in bases, it references it.
+    """
+    refs = []
+    for ent in entities:
+        # Class extends/implements
+        if name in ent.get("bases", []):
+            refs.append(ent["name"])
+        # Decorator usage
+        if name in ent.get("decorators", []):
+            refs.append(ent["name"])
+    return refs
+
+
+# ---------------------------------------------------------------------------
+# LSP Client -- JSON-RPC over stdio
+# ---------------------------------------------------------------------------
+
+class LspClient:
+    """
+    Minimal Language Server Protocol client using JSON-RPC over stdio.
+
+    Starts an LSP server as a subprocess, communicates via Content-Length
+    framed JSON-RPC messages, and dispatches responses to waiting callers
+    via a background reader thread.
+
+    Supports:
+    - initialize / initialized / shutdown / exit lifecycle
+    - textDocument/didOpen, textDocument/didClose
+    - textDocument/prepareCallHierarchy
+    - callHierarchy/outgoingCalls, callHierarchy/incomingCalls
+    - textDocument/references
+    """
+
+    def __init__(self, cmd: list[str], cwd: str):
+        self._proc = subprocess.Popen(
+            cmd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=cwd,
+        )
+        assert self._proc.stdin is not None
+        assert self._proc.stdout is not None
+        assert self._proc.stderr is not None
+        self._stdin = self._proc.stdin
+        self._stdout = self._proc.stdout
+        self._stderr = self._proc.stderr
+        self._msg_id = 0
+        self._lock = threading.Lock()
+        self._events: dict[int, threading.Event] = {}
+        self._results: dict[int, Any] = {}
+        self._errors: dict[int, Any] = {}
+        self._alive = True
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+        self._stderr_reader = threading.Thread(target=self._drain_stderr, daemon=True)
+        self._stderr_reader.start()
+
+    # -- Transport layer --
+
+    def _next_id(self) -> int:
+        with self._lock:
+            self._msg_id += 1
+            return self._msg_id
+
+    def _send(self, msg: dict) -> None:
+        """Send a JSON-RPC message with Content-Length header."""
+        body = json.dumps(msg).encode("utf-8")
+        header = f"Content-Length: {len(body)}\r\n\r\n".encode("ascii")
+        try:
+            self._stdin.write(header + body)
+            self._stdin.flush()
+        except (BrokenPipeError, OSError):
+            self._alive = False
+
+    def _read_loop(self) -> None:
+        """Background thread: read Content-Length framed messages from stdout."""
+        # Use os.read() for non-blocking reads. Python's BufferedReader.read(n)
+        # blocks until exactly n bytes are available, which deadlocks on pipes.
+        fd = self._stdout.fileno()
+        buf = b""
+        while self._alive:
+            try:
+                # Read until we have the full header separator
+                while b"\r\n\r\n" not in buf:
+                    chunk = os.read(fd, 65536)
+                    if not chunk:
+                        self._alive = False
+                        self._wake_all()
+                        return
+                    buf += chunk
+
+                header_end = buf.index(b"\r\n\r\n")
+                headers = buf[:header_end].decode("ascii")
+                buf = buf[header_end + 4:]
+
+                content_length = 0
+                for line in headers.split("\r\n"):
+                    if line.lower().startswith("content-length:"):
+                        content_length = int(line.split(":", 1)[1].strip())
+
+                # Read body
+                while len(buf) < content_length:
+                    chunk = os.read(fd, 65536)
+                    if not chunk:
+                        self._alive = False
+                        self._wake_all()
+                        return
+                    buf += chunk
+
+                body = buf[:content_length]
+                buf = buf[content_length:]
+
+                try:
+                    msg = json.loads(body.decode("utf-8"))
+                except json.JSONDecodeError:
+                    continue
+
+                # Dispatch response
+                msg_id = msg.get("id")
+                if msg_id is not None and msg_id in self._events:
+                    if "result" in msg:
+                        self._results[msg_id] = msg["result"]
+                    elif "error" in msg:
+                        self._errors[msg_id] = msg["error"]
+                    else:
+                        # Null result is valid (e.g., empty references)
+                        self._results[msg_id] = None
+                    self._events[msg_id].set()
+                # Server-initiated notifications (diagnostics, progress) are ignored.
+
+            except Exception:
+                if self._alive:
+                    continue
+                return
+
+    def _drain_stderr(self) -> None:
+        """Drain stderr to prevent buffer deadlock."""
+        fd = self._stderr.fileno()
+        try:
+            while self._alive:
+                data = os.read(fd, 65536)
+                if not data:
+                    return
+        except Exception:
+            pass
+
+    def _wake_all(self) -> None:
+        """Wake all pending requests (server died or shutting down)."""
+        for event in self._events.values():
+            event.set()
+
+    # -- Request / Notification helpers --
+
+    def _request(self, method: str, params: Any, timeout: float = LSP_REQUEST_TIMEOUT) -> Any:
+        """Send a request and wait for the response (blocking)."""
+        if not self._alive:
+            return None
+        msg_id = self._next_id()
+        event = threading.Event()
+        self._events[msg_id] = event
+        self._send({"jsonrpc": "2.0", "id": msg_id, "method": method, "params": params})
+        if event.wait(timeout):
+            self._events.pop(msg_id, None)
+            if msg_id in self._errors:
+                self._errors.pop(msg_id)
+                return None
+            return self._results.pop(msg_id, None)
+        # Timeout
+        self._events.pop(msg_id, None)
+        return None
+
+    def _request_fire(self, method: str, params: Any) -> int:
+        """Send a request without waiting. Returns the message ID for later collection."""
+        if not self._alive:
+            return -1
+        msg_id = self._next_id()
+        event = threading.Event()
+        self._events[msg_id] = event
+        self._send({"jsonrpc": "2.0", "id": msg_id, "method": method, "params": params})
+        return msg_id
+
+    def _request_collect(self, msg_id: int, timeout: float = LSP_REQUEST_TIMEOUT) -> Any:
+        """Wait for a previously fired request's response."""
+        if msg_id < 0 or msg_id not in self._events:
+            return None
+        event = self._events[msg_id]
+        if event.wait(timeout):
+            self._events.pop(msg_id, None)
+            if msg_id in self._errors:
+                self._errors.pop(msg_id)
+                return None
+            return self._results.pop(msg_id, None)
+        self._events.pop(msg_id, None)
+        return None
+
+    def _notify(self, method: str, params: Any) -> None:
+        """Send a notification (no response expected)."""
+        self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    # -- LSP lifecycle --
+
+    def initialize(self, root_uri: str) -> bool:
+        """Send initialize request. Returns True on success."""
+        result = self._request("initialize", {
+            "processId": os.getpid(),
+            "rootUri": root_uri,
+            "capabilities": {
+                "textDocument": {
+                    "callHierarchy": {
+                        "dynamicRegistration": False,
+                    },
+                    "references": {
+                        "dynamicRegistration": False,
+                    },
+                    "synchronization": {
+                        "didOpen": True,
+                        "didClose": True,
+                    },
+                },
+            },
+            "workspaceFolders": [{"uri": root_uri, "name": os.path.basename(uri_to_path(root_uri))}],
+        }, timeout=LSP_INIT_TIMEOUT)
+        if result is not None:
+            self._notify("initialized", {})
+            return True
+        return False
+
+    def shutdown(self) -> None:
+        """Gracefully shut down the LSP server."""
+        if self._alive:
+            self._request("shutdown", None, timeout=5.0)
+            self._notify("exit", None)
+        self._alive = False
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5)
+        except Exception:
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+
+    @property
+    def alive(self) -> bool:
+        return self._alive and self._proc.poll() is None
+
+    # -- Document operations --
+
+    def did_open(self, uri: str, language_id: str, text: str) -> None:
+        """Notify server that a document was opened."""
+        self._notify("textDocument/didOpen", {
+            "textDocument": {
+                "uri": uri,
+                "languageId": language_id,
+                "version": 1,
+                "text": text,
+            },
+        })
+
+    def did_close(self, uri: str) -> None:
+        """Notify server that a document was closed."""
+        self._notify("textDocument/didClose", {
+            "textDocument": {"uri": uri},
+        })
+
+    # -- Query operations --
+
+    def document_symbols(
+        self, uri: str, timeout: float = LSP_REQUEST_TIMEOUT,
+    ) -> list[dict]:
+        """
+        Get all symbols in a document. Returns a tree of DocumentSymbol objects.
+
+        Each symbol has: name, kind (int), range, selectionRange, children.
+        SymbolKind: 5=Class, 6=Method, 11=Interface, 12=Function, 13=Variable,
+                    10=Enum, 26=TypeParameter, 15=Namespace.
+        """
+        result = self._request("textDocument/documentSymbol", {
+            "textDocument": {"uri": uri},
+        }, timeout=timeout)
+        return result if isinstance(result, list) else []
+
+    def prepare_call_hierarchy(
+        self, uri: str, line: int, character: int, timeout: float = LSP_REQUEST_TIMEOUT,
+    ) -> list[dict]:
+        """
+        Prepare call hierarchy at position. Returns list of CallHierarchyItem.
+        Line and character are 0-based (LSP convention).
+        """
+        result = self._request("textDocument/prepareCallHierarchy", {
+            "textDocument": {"uri": uri},
+            "position": {"line": line, "character": character},
+        }, timeout=timeout)
+        return result if isinstance(result, list) else []
+
+    def outgoing_calls(
+        self, item: dict, timeout: float = LSP_REQUEST_TIMEOUT,
+    ) -> list[dict]:
+        """Get outgoing calls from a CallHierarchyItem."""
+        result = self._request("callHierarchy/outgoingCalls", {
+            "item": item,
+        }, timeout=timeout)
+        return result if isinstance(result, list) else []
+
+    def incoming_calls(
+        self, item: dict, timeout: float = LSP_REQUEST_TIMEOUT,
+    ) -> list[dict]:
+        """Get incoming calls to a CallHierarchyItem."""
+        result = self._request("callHierarchy/incomingCalls", {
+            "item": item,
+        }, timeout=timeout)
+        return result if isinstance(result, list) else []
+
+    def references(
+        self, uri: str, line: int, character: int, timeout: float = LSP_REQUEST_TIMEOUT,
+    ) -> list[dict]:
+        """
+        Find all references to the symbol at position.
+        Returns list of Location {uri, range}.
+        """
+        result = self._request("textDocument/references", {
+            "textDocument": {"uri": uri},
+            "position": {"line": line, "character": character},
+            "context": {"includeDeclaration": False},
+        }, timeout=timeout)
+        return result if isinstance(result, list) else []
+
+
+# ---------------------------------------------------------------------------
+# Project discovery for LSP
+# ---------------------------------------------------------------------------
+
+def discover_projects(root: str, file_results: list[FileResult]) -> list[ProjectGroup]:
+    """
+    Group files by LSP project root, detected by presence of config files.
+
+    For TypeScript: looks for tsconfig.json.
+    For Python: looks for pyrightconfig.json or pyproject.toml.
+
+    Files that do not belong to any detected project are skipped.
+    """
+    # Find all config files
+    ts_configs: list[str] = []
+    py_configs: list[str] = []
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Skip unwanted directories
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for fname in filenames:
+            full = os.path.join(dirpath, fname)
+            if fname == "tsconfig.json":
+                ts_configs.append(full)
+            elif fname in ("pyrightconfig.json", "pyproject.toml"):
+                py_configs.append(full)
+
+    # Sort configs by depth (deepest first) so files match the most specific project
+    ts_configs.sort(key=lambda p: -p.count(os.sep))
+    py_configs.sort(key=lambda p: -p.count(os.sep))
+
+    projects: list[ProjectGroup] = []
+    assigned_files: set[str] = set()
+
+    # Assign TypeScript files to projects
+    for config in ts_configs:
+        proj_root = os.path.dirname(config)
+        proj = ProjectGroup(
+            root=proj_root,
+            language="typescript",
+            config_file=config,
+        )
+        for r in file_results:
+            if r.language == "typescript" and r.path not in assigned_files:
+                if r.path.startswith(proj_root + os.sep):
+                    proj.files.append(r)
+                    assigned_files.add(r.path)
+        if proj.files:
+            projects.append(proj)
+
+    # Assign Python files to projects
+    for config in py_configs:
+        proj_root = os.path.dirname(config)
+        proj = ProjectGroup(
+            root=proj_root,
+            language="python",
+            config_file=config,
+        )
+        for r in file_results:
+            if r.language == "python" and r.path not in assigned_files:
+                if r.path.startswith(proj_root + os.sep):
+                    proj.files.append(r)
+                    assigned_files.add(r.path)
+        if proj.files:
+            projects.append(proj)
+
+    return projects
+
+
+# ---------------------------------------------------------------------------
+# LSP analysis -- call hierarchy + references
+# ---------------------------------------------------------------------------
+
+def _language_id(language: str, path: str) -> str:
+    """Map internal language + file extension to LSP languageId."""
+    if language == "python":
+        return "python"
+    if path.endswith(".tsx"):
+        return "typescriptreact"
+    return "typescript"
+
+
+# LSP SymbolKind constants
+_SK_CLASS = 5
+_SK_METHOD = 6
+_SK_PROPERTY = 7
+_SK_ENUM = 10
+_SK_INTERFACE = 11
+_SK_FUNCTION = 12
+_SK_VARIABLE = 13
+_SK_CONSTANT = 14
+_SK_ENUM_MEMBER = 22
+_SK_TYPE_PARAMETER = 26
+
+_SK_TO_KIND = {
+    _SK_CLASS: "class",
+    _SK_METHOD: "method",
+    _SK_INTERFACE: "interface",
+    _SK_FUNCTION: "function",
+    _SK_VARIABLE: "function",   # const exports
+    _SK_CONSTANT: "function",
+    _SK_ENUM: "enum",
+    _SK_TYPE_PARAMETER: "type",
+    _SK_PROPERTY: "function",
+}
+
+
+def _sym_line(sym: dict) -> int:
+    """Extract 1-based line from a DocumentSymbol or SymbolInformation."""
+    # DocumentSymbol format: { selectionRange: { start: { line } } }
+    sel = sym.get("selectionRange")
+    if sel:
+        return sel.get("start", {}).get("line", 0) + 1
+    # SymbolInformation format: { location: { range: { start: { line } } } }
+    loc = sym.get("location")
+    if loc:
+        return loc.get("range", {}).get("start", {}).get("line", 0) + 1
+    # Fallback to range
+    rng = sym.get("range")
+    if rng:
+        return rng.get("start", {}).get("line", 0) + 1
+    return 0
+
+
+def _lsp_symbols_to_entities(symbols: list[dict]) -> tuple[list[dict], list[str]]:
+    """
+    Convert LSP symbol results into Entity dicts and exported names.
+
+    Handles both DocumentSymbol (nested, has children) and SymbolInformation
+    (flat, has location) formats. Filters to top-level definitions only:
+    classes, interfaces, functions, types, enums, and exported constants.
+    """
+    entities: list[dict] = []
+    exported_names: list[str] = []
+    seen_names: set[str] = set()
+
+    # Detect format: DocumentSymbol has "children" or "selectionRange",
+    # SymbolInformation has "location"
+    is_doc_symbol = any("selectionRange" in s or "children" in s for s in symbols[:5])
+
+    if is_doc_symbol:
+        # DocumentSymbol: only process top-level symbols
+        for sym in symbols:
+            _process_doc_symbol(sym, entities, exported_names, seen_names)
+    else:
+        # SymbolInformation: flat list, filter to top-level kinds
+        for sym in symbols:
+            # Skip methods/properties (they belong to a class, not top-level)
+            if sym.get("containerName", ""):
+                continue
+            _process_symbol_info(sym, entities, exported_names, seen_names)
+
+    return entities, exported_names
+
+
+def _process_doc_symbol(
+    sym: dict,
+    entities: list[dict],
+    exported_names: list[str],
+    seen_names: set[str],
+) -> None:
+    """Process a single DocumentSymbol (with children)."""
+    kind_int = sym.get("kind", 0)
+    name = sym.get("name", "")
+    line = _sym_line(sym)
+
+    if not name or name in seen_names:
+        return
+
+    children = sym.get("children", [])
+
+    if kind_int in (_SK_CLASS, _SK_INTERFACE):
+        methods = []
+        for child in children:
+            child_kind = child.get("kind", 0)
+            child_name = child.get("name", "")
+            if child_kind in (_SK_METHOD, _SK_PROPERTY, _SK_FUNCTION) and child_name:
+                methods.append(child_name)
+        kind = "class" if kind_int == _SK_CLASS else "interface"
+        entities.append({
+            "name": name, "kind": kind, "line": line,
+            "methods": methods, "bases": [], "decorators": [],
+        })
+        seen_names.add(name)
+        exported_names.append(name)
+
+    elif kind_int == _SK_ENUM:
+        members = [c.get("name", "") for c in children if c.get("kind") == _SK_ENUM_MEMBER]
+        entities.append({
+            "name": name, "kind": "enum", "line": line,
+            "methods": members, "bases": [], "decorators": [],
+        })
+        seen_names.add(name)
+        exported_names.append(name)
+
+    elif kind_int == _SK_FUNCTION:
+        entities.append({
+            "name": name, "kind": "function", "line": line,
+            "methods": [], "bases": [], "decorators": [],
+        })
+        seen_names.add(name)
+        exported_names.append(name)
+
+    elif kind_int in (_SK_VARIABLE, _SK_CONSTANT):
+        # Only capture exported-looking names (PascalCase or camelCase identifiers)
+        # Skip destructured locals, parameters, etc.
+        if len(name) >= 2 and (name[0].isupper() or not name.startswith("_")):
+            ent_kind = "type" if name[0].isupper() and not children else "function"
+            methods = []
+            if children:
+                for child in children:
+                    child_name = child.get("name", "")
+                    if child_name:
+                        methods.append(child_name)
+            entities.append({
+                "name": name, "kind": ent_kind, "line": line,
+                "methods": methods, "bases": [], "decorators": [],
+            })
+            seen_names.add(name)
+            exported_names.append(name)
+
+    elif kind_int == _SK_TYPE_PARAMETER:
+        entities.append({
+            "name": name, "kind": "type", "line": line,
+            "methods": [], "bases": [], "decorators": [],
+        })
+        seen_names.add(name)
+        exported_names.append(name)
+
+
+def _process_symbol_info(
+    sym: dict,
+    entities: list[dict],
+    exported_names: list[str],
+    seen_names: set[str],
+) -> None:
+    """Process a single SymbolInformation (flat, no children)."""
+    kind_int = sym.get("kind", 0)
+    name = sym.get("name", "")
+    line = _sym_line(sym)
+
+    if not name or name in seen_names:
+        return
+
+    kind = _SK_TO_KIND.get(kind_int)
+    if not kind:
+        return
+
+    entities.append({
+        "name": name, "kind": kind, "line": line,
+        "methods": [], "bases": [], "decorators": [],
+    })
+    seen_names.add(name)
+    exported_names.append(name)
+
+
+def _drain_prepare_batch(
+    client: "LspClient",
+    batch: list[tuple[int, str, dict]],
+    path_to_node_id: dict[str, str],
+    source_node_id: str,
+    lsp_edges: list[LspEdge],
+    timeout: float,
+) -> int:
+    """
+    Collect prepareCallHierarchy results, pipeline outgoingCalls, collect those.
+
+    Returns number of CALLS edges found.
+    """
+    calls_found = 0
+    # Collect prepare results and fire outgoingCalls
+    outgoing_pending: list[tuple[int, str, str]] = []  # (msg_id, ent_name, node_id)
+    for mid, ent_name, _ent in batch:
+        items = client._request_collect(mid, timeout=timeout)
+        if not isinstance(items, list):
+            continue
+        for item in items:
+            if item.get("name") != ent_name:
+                continue
+            oc_mid = client._request_fire("callHierarchy/outgoingCalls", {"item": item})
+            if oc_mid >= 0:
+                outgoing_pending.append((oc_mid, ent_name, source_node_id))
+
+    # Collect outgoingCalls results
+    for oc_mid, ent_name, node_id in outgoing_pending:
+        outgoing = client._request_collect(oc_mid, timeout=timeout)
+        if not isinstance(outgoing, list):
+            continue
+        for call in outgoing:
+            target = call.get("to", {})
+            target_uri = target.get("uri", "")
+            target_name = target.get("name", "")
+            target_path = uri_to_path(target_uri)
+            target_node_id = path_to_node_id.get(target_path)
+            if not target_node_id:
+                continue
+            from_ranges = [fr["start"]["line"] + 1 for fr in call.get("fromRanges", [])]
+            lsp_edges.append(LspEdge(
+                source=f"{node_id}::{ent_name}",
+                target=f"{target_node_id}::{target_name}",
+                edge_type="CALLS",
+                metadata={"from_lines": from_ranges, "lsp_verified": True},
+            ))
+            calls_found += 1
+    return calls_found
+
+
+def _find_enclosing_entity(
+    entities: list[dict], line_0based: int,
+) -> Optional[str]:
+    """
+    Find the entity that encloses the given 0-based line.
+
+    Uses a simple heuristic: the entity whose line is closest to (but not
+    after) the target line.
+    """
+    best: Optional[dict] = None
+    for ent in entities:
+        ent_line_0 = ent["line"] - 1  # entity lines are 1-based
+        if ent_line_0 <= line_0based:
+            if best is None or ent_line_0 > best["line"] - 1:
+                best = ent
+    return best["name"] if best else None
+
+
+def analyze_project_lsp(
+    project: ProjectGroup,
+    root: str,
+    path_to_node_id: dict[str, str],
+    node_id_to_result: dict[str, FileResult],
+    request_timeout: float,
+) -> list[LspEdge]:
+    """
+    Analyze a single project with LSP for precise call graph and references.
+
+    Returns a list of LspEdge instances to merge into the main graph.
+    """
+    # Determine LSP server command
+    if project.language == "typescript":
+        cmd = ["typescript-language-server", "--stdio"]
+    else:
+        cmd = ["pyright-langserver", "--stdio"]
+
+    # Check server availability
+    server_bin = cmd[0]
+    from shutil import which
+    if not which(server_bin):
+        print(f"  [lsp] WARNING: {server_bin} not found, skipping {project.root}")
+        return []
+
+    proj_name = os.path.relpath(project.root, root)
+    print(f"  [lsp] Starting {server_bin} for {proj_name} ({len(project.files)} files)")
+
+    client = LspClient(cmd, cwd=project.root)
+    lsp_edges: list[LspEdge] = []
+
+    try:
+        # Initialize
+        root_uri = path_to_uri(project.root)
+        if not client.initialize(root_uri):
+            print(f"  [lsp] WARNING: initialize failed for {proj_name}")
+            return []
+
+        # Open all project files (batch)
+        file_contents: dict[str, str] = {}
+        for r in project.files:
+            try:
+                with open(r.path, "r", encoding="utf-8", errors="replace") as f:
+                    content = f.read()
+                file_contents[r.path] = content
+                uri = path_to_uri(r.path)
+                lang_id = _language_id(r.language, r.path)
+                client.did_open(uri, lang_id, content)
+            except OSError:
+                continue
+
+        # Give the server a moment to process opened files
+        time.sleep(1.0)
+
+        # -- Phase 1: Merge LSP documentSymbol with regex entities --
+        # LSP gives precise line numbers and finds entities regex misses
+        # (object literals, Zod schemas). Regex gives method lists via
+        # brace scanning. Merge: take LSP entities as base, carry over
+        # regex methods for classes/interfaces that LSP returns without children.
+        symbols_replaced = 0
+        for r in project.files:
+            if not client.alive:
+                break
+            node_id = path_to_node_id.get(r.path)
+            if not node_id:
+                continue
+            uri = path_to_uri(r.path)
+            lsp_syms = client.document_symbols(uri, timeout=request_timeout)
+            if lsp_syms:
+                new_entities, new_exports = _lsp_symbols_to_entities(lsp_syms)
+                # Build regex method index: entity_name -> methods list
+                regex_methods: dict[str, list[str]] = {}
+                for old_ent in r.entities:
+                    if old_ent.get("methods"):
+                        regex_methods[old_ent["name"]] = old_ent["methods"]
+                # Merge: carry over regex methods when LSP has none
+                for ent in new_entities:
+                    if ent["kind"] in ("class", "interface") and not ent.get("methods"):
+                        regex_m = regex_methods.get(ent["name"])
+                        if regex_m:
+                            ent["methods"] = regex_m
+                    # Also carry over bases/decorators from regex
+                    if not ent.get("bases") or not ent.get("decorators"):
+                        for old_ent in r.entities:
+                            if old_ent["name"] == ent["name"]:
+                                if not ent.get("bases") and old_ent.get("bases"):
+                                    ent["bases"] = old_ent["bases"]
+                                if not ent.get("decorators") and old_ent.get("decorators"):
+                                    ent["decorators"] = old_ent["decorators"]
+                                break
+                # Add regex entities not found by LSP (e.g., Zod schemas)
+                lsp_names = {e["name"] for e in new_entities}
+                for old_ent in r.entities:
+                    if old_ent["name"] not in lsp_names:
+                        new_entities.append(old_ent)
+                        if old_ent["name"] not in new_exports:
+                            new_exports.append(old_ent["name"])
+                r.entities = new_entities
+                r.exported_names = list(set(new_exports))
+                symbols_replaced += 1
+
+        if symbols_replaced:
+            print(f"  [lsp] {proj_name}: merged entities in {symbols_replaced} files via documentSymbol")
+
+        # -- Phase 2: Pipelined call hierarchy + references --
+        # Strategy: for each file, fire all prepareCallHierarchy and
+        # references requests at once (pipelined), then collect results.
+        # This overlaps network round-trips with server processing.
+        total_entities = sum(len(r.entities) for r in project.files)
+        processed = 0
+        calls_found = 0
+        refs_found = 0
+        PIPELINE_BATCH = 40  # max concurrent in-flight requests
+
+        for r in project.files:
+            if not client.alive:
+                print(f"  [lsp] WARNING: server died while processing {proj_name}")
+                break
+
+            content = file_contents.get(r.path)
+            if not content:
+                continue
+
+            node_id = path_to_node_id.get(r.path)
+            if not node_id:
+                continue
+
+            uri = path_to_uri(r.path)
+
+            # -- Batch 1: fire prepareCallHierarchy + references for all entities --
+            pending_prepare: list[tuple[int, str, dict]] = []  # (msg_id, ent_name, ent)
+            pending_refs: list[tuple[int, str, str]] = []  # (msg_id, ent_name, node_id)
+
+            for ent in r.entities:
+                ent_name = ent["name"]
+                ent_line_0 = ent["line"] - 1
+                ent_col = find_entity_column(content, ent_name, ent["line"])
+
+                if ent["kind"] in ("function", "class"):
+                    mid = client._request_fire("textDocument/prepareCallHierarchy", {
+                        "textDocument": {"uri": uri},
+                        "position": {"line": ent_line_0, "character": ent_col},
+                    })
+                    if mid >= 0:
+                        pending_prepare.append((mid, ent_name, ent))
+
+                if ent_name in r.exported_names:
+                    mid = client._request_fire("textDocument/references", {
+                        "textDocument": {"uri": uri},
+                        "position": {"line": ent_line_0, "character": ent_col},
+                        "context": {"includeDeclaration": False},
+                    })
+                    if mid >= 0:
+                        pending_refs.append((mid, ent_name, node_id))
+
+                # Drain pipeline if too many in-flight
+                while len(pending_prepare) + len(pending_refs) >= PIPELINE_BATCH:
+                    calls_found += _drain_prepare_batch(
+                        client, pending_prepare[:PIPELINE_BATCH // 2],
+                        path_to_node_id, node_id, lsp_edges, request_timeout,
+                    )
+                    pending_prepare = pending_prepare[PIPELINE_BATCH // 2:]
+
+            # -- Collect remaining prepareCallHierarchy results --
+            calls_found += _drain_prepare_batch(
+                client, pending_prepare, path_to_node_id, node_id, lsp_edges, request_timeout,
+            )
+
+            # -- Collect references results --
+            for mid, ent_name, src_node_id in pending_refs:
+                ref_locations = client._request_collect(mid, timeout=request_timeout)
+                if not isinstance(ref_locations, list):
+                    continue
+                for loc in ref_locations:
+                    ref_uri = loc.get("uri", "")
+                    ref_path = uri_to_path(ref_uri)
+                    ref_node_id = path_to_node_id.get(ref_path)
+                    if not ref_node_id or ref_node_id == src_node_id:
+                        continue
+                    ref_result = node_id_to_result.get(ref_node_id)
+                    ref_line_0 = loc.get("range", {}).get("start", {}).get("line", 0)
+                    ref_entity_name = None
+                    if ref_result:
+                        ref_entity_name = _find_enclosing_entity(
+                            ref_result.entities, ref_line_0,
+                        )
+                    source_key = f"{ref_node_id}::{ref_entity_name}" if ref_entity_name else ref_node_id
+                    target_key = f"{src_node_id}::{ent_name}"
+                    lsp_edges.append(LspEdge(
+                        source=source_key,
+                        target=target_key,
+                        edge_type="REFERENCES",
+                        metadata={"lsp_verified": True, "ref_line": ref_line_0 + 1},
+                    ))
+                    refs_found += 1
+
+            processed += len(r.entities)
+            if processed % 200 < len(r.entities):
+                print(f"  [lsp] {proj_name}: {processed}/{total_entities} entities "
+                      f"({calls_found} calls, {refs_found} refs)")
+
+            client.did_close(uri)
+
+        print(f"  [lsp] {proj_name}: done -- {calls_found} calls, {refs_found} refs from {processed} entities")
+
+    except Exception as exc:
+        print(f"  [lsp] ERROR in {proj_name}: {exc}")
+    finally:
+        client.shutdown()
+
+    return lsp_edges
+
+
+# ---------------------------------------------------------------------------
+# LSP merge -- integrate LSP edges into the graph
+# ---------------------------------------------------------------------------
+
+def merge_lsp_edges(
+    edges: list[dict],
+    lsp_edges: list[LspEdge],
+) -> list[dict]:
+    """
+    Merge LSP-derived edges into the existing edge list.
+
+    - New CALLS edges are added directly.
+    - REFERENCES edges that match existing ones get ``lsp_verified: true``.
+    - New REFERENCES edges not found by the regex pass are added.
+    """
+    # Index existing edges for fast lookup
+    existing_keys: dict[tuple, int] = {}
+    for idx, edge in enumerate(edges):
+        key = (edge["source"], edge["target"], edge["type"])
+        existing_keys[key] = idx
+
+    new_edges: list[dict] = []
+    verified_count = 0
+    new_count = 0
+
+    for le in lsp_edges:
+        key = (le.source, le.target, le.edge_type)
+        if key in existing_keys:
+            # Mark existing edge as LSP-verified
+            edges[existing_keys[key]]["lsp_verified"] = True
+            verified_count += 1
+        else:
+            # Add new edge
+            edge_dict: dict = {
+                "source": le.source,
+                "target": le.target,
+                "type": le.edge_type,
+            }
+            edge_dict.update(le.metadata)
+            new_edges.append(edge_dict)
+            new_count += 1
+            # Track so we don't add duplicates
+            existing_keys[key] = -1
+
+    print(f"[belief-map] LSP merge: {verified_count} verified, {new_count} new edges")
+    return edges + new_edges
+
+
+# ---------------------------------------------------------------------------
+# LSP enrichment orchestrator
+# ---------------------------------------------------------------------------
+
+def enrich_with_lsp(
+    root: str,
+    results: list[FileResult],
+    nodes: list[dict],
+    edges: list[dict],
+    request_timeout: float,
+) -> tuple[list[dict], list[dict]]:
+    """
+    Run LSP analysis on all detected projects and merge edges into the graph.
+
+    For TypeScript: replaces regex-extracted entities with LSP documentSymbol
+    results, then queries call hierarchy and references for precise edges.
+    For Python: queries call hierarchy and references only (keeps AST entities).
+    """
+    # Build lookup tables
+    path_to_node_id: dict[str, str] = {}
+    node_id_to_result: dict[str, FileResult] = {}
+    for r in results:
+        nid = make_node_id(r.path, root)
+        path_to_node_id[r.path] = nid
+        node_id_to_result[nid] = r
+
+    # Discover projects
+    projects = discover_projects(root, results)
+    if not projects:
+        print("[belief-map] No LSP-compatible projects found (no tsconfig.json or pyrightconfig.json)")
+        return nodes, edges
+
+    ts_projects = [p for p in projects if p.language == "typescript"]
+    py_projects = [p for p in projects if p.language == "python"]
+    ts_files = sum(len(p.files) for p in ts_projects)
+    py_files = sum(len(p.files) for p in py_projects)
+    print(f"[belief-map] LSP: {len(projects)} projects "
+          f"({len(ts_projects)} TS/{ts_files} files, {len(py_projects)} Py/{py_files} files)")
+
+    all_lsp_edges: list[LspEdge] = []
+
+    for project in projects:
+        proj_edges = analyze_project_lsp(
+            project, root, path_to_node_id, node_id_to_result, request_timeout,
+        )
+        all_lsp_edges.extend(proj_edges)
+
+    if all_lsp_edges:
+        edges = merge_lsp_edges(edges, all_lsp_edges)
+
+    # Rebuild nodes with LSP-replaced entities
+    node_by_id = {n["id"]: n for n in nodes}
+    for r in results:
+        nid = path_to_node_id.get(r.path)
+        if nid and nid in node_by_id:
+            node_by_id[nid]["entities"] = r.entities
+    nodes = list(node_by_id.values())
+
+    return nodes, edges
+
+
+# ---------------------------------------------------------------------------
+# Output formatters
+# ---------------------------------------------------------------------------
+
+def _sexp_escape(s: str) -> str:
+    """Escape a string for S-expression output (double-quote delimited)."""
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _entity_id(module_path: str, entity_name: str) -> str:
+    """Generate a short unique ID for an entity based on path + name SHA."""
+    raw = f"{module_path}::{entity_name}"
+    return hashlib.sha1(raw.encode()).hexdigest()[:8]
+
+
+# ---------------------------------------------------------------------------
+# Path trie for compressed path definitions
+# ---------------------------------------------------------------------------
+
+def _build_path_tree(path_sid_pairs: list[tuple[str, str]]) -> list[str]:
+    """
+    Build a compressed path trie and emit as indented S-expression tree.
+
+    Shares common path prefixes to reduce repetition. Collapses single-child
+    chains into combined segments (path compression).
+
+    Output format::
+
+        (paths
+          (agent-hub/packages/agent-research/src
+            (ah0 ReasoningEngine)
+            (ah1 ResearchAgent))
+          (app-service/app-service/src/operatives
+            (asp340 operatives.controller)))
+    """
+    # Build trie: dict of dicts, leaves are {"_sid": "ah0"}
+    # A node can be BOTH a directory (has children) and a leaf (has _sid)
+    # when index.ts strips to the directory name.
+    root: dict = {}
+    for full_path, sid in path_sid_pairs:
+        segments = full_path.split("/")
+        node = root
+        for seg in segments[:-1]:
+            node = node.setdefault(seg, {})
+        # Leaf: store sid. If the key already exists as a dict (directory),
+        # merge _sid into it rather than overwriting children.
+        leaf_key = segments[-1]
+        existing = node.get(leaf_key)
+        if isinstance(existing, dict) and "_sid" not in existing:
+            existing["_sid"] = sid
+        else:
+            node[leaf_key] = {"_sid": sid}
+
+    # Compress: collapse single-child internal nodes
+    def compress(node: dict) -> dict:
+        result: dict = {}
+        for key, child in node.items():
+            if isinstance(child, dict) and "_sid" in child:
+                result[key] = child  # leaf, keep as-is
+            elif isinstance(child, dict):
+                compressed = compress(child)
+                # If single non-leaf child, merge keys
+                while len(compressed) == 1:
+                    only_key, only_val = next(iter(compressed.items()))
+                    if isinstance(only_val, dict) and "_sid" not in only_val:
+                        key = f"{key}/{only_key}"
+                        compressed = only_val
+                    else:
+                        break
+                result[key] = compressed
+            else:
+                result[key] = child
+        return result
+
+    compressed = compress(root)
+
+    # Emit as indented S-expressions
+    def emit(node: dict, depth: int) -> list[str]:
+        lines: list[str] = []
+        indent = "  " * depth
+        for key in sorted(node.keys()):
+            if key == "_sid":
+                continue  # handled by parent
+            child = node[key]
+            if isinstance(child, dict) and "_sid" in child:
+                # Check if this is BOTH a leaf and a directory (has other keys)
+                other_keys = [k for k in child if k != "_sid"]
+                if other_keys:
+                    # Emit the _sid as a :self entry, then recurse for children
+                    lines.append(f"{indent}({key}")
+                    lines.append(f"{indent}  ({child['_sid']} :self)")
+                    lines.extend(emit(child, depth + 1))
+                    lines.append(f"{indent})")
+                else:
+                    lines.append(f"{indent}({child['_sid']} {key})")
+            elif isinstance(child, dict):
+                lines.append(f"{indent}({key}")
+                lines.extend(emit(child, depth + 1))
+                lines.append(f"{indent})")
+        return lines
+
+    return emit(compressed, 1)
+
+
+def write_sexp(
+    output_path: str,
+    nodes: list[dict],
+    edges: list[dict],
+    _root: str,
+    mode: str,
+    total_files: int,
+) -> None:
+    """
+    Write the belief map as flat S-expression facts with path-map compression.
+
+    The file starts with ``(def <id> <full-path>)`` bindings that assign short
+    numeric IDs to every module path. All subsequent lines use these IDs instead
+    of full paths, reducing file size by ~60-70%.
+
+    Format::
+
+        ; --- paths ---
+        (def 0 agent-hub/packages/agent-research/src/ReasoningEngine)
+        (def 1 agent-hub/packages/agent-research/src/ResearchAgent)
+
+        ; --- nodes ---
+        (node 0 ty "general module" :naming PascalCase :pkg agent-hub)
+
+        ; --- entities ---
+        (fn 0 isToolIncluded 5)
+        (cls 1 ResearchAgent 322 (:bases BaseAgent) (:methods ...))
+
+        ; --- edges ---
+        (imports 1 0 :via-base)
+        (refs 1 0::ReasoningSchemaType)
+
+        ; --- violations ---
+        (violation boundary 42 99 "domain imports infrastructure without abstract base")
+    """
+    sorted_nodes = sorted(nodes, key=lambda n: n["id"])
+
+    # Build path map: full path -> short prefixed ID (repo-prefix + seq number)
+    # e.g. ah0 = agent-hub first module, dr42 = drive 43rd module
+    _REPO_PREFIX: dict[str, str] = {}
+    _repo_counters: dict[str, int] = {}
+    path_to_sid: dict[str, str] = {}
+
+    for node in sorted_nodes:
+        repo = node.get("repo", "unknown")
+        if repo not in _REPO_PREFIX:
+            # Build 2-char prefix from repo name
+            parts = repo.replace("-", " ").split()
+            if len(parts) >= 2:
+                prefix = parts[0][0] + parts[1][0]
+            else:
+                prefix = repo[:2]
+            # Deduplicate prefixes
+            base = prefix
+            idx = 2
+            while prefix in _REPO_PREFIX.values():
+                prefix = base + repo[idx:idx + 1] if idx < len(repo) else base + str(idx)
+                idx += 1
+            _REPO_PREFIX[repo] = prefix
+            _repo_counters[repo] = 0
+
+        seq = _repo_counters[repo]
+        _repo_counters[repo] = seq + 1
+        sid = f"{_REPO_PREFIX[repo]}{seq}"
+        path_to_sid[node["id"]] = sid
+
+    def _pid(path: str) -> str:
+        """Resolve a path (possibly with ::entity suffix) to short ID."""
+        if "::" in path:
+            mod, ent = path.split("::", 1)
+            sid = path_to_sid.get(mod)
+            return f"{sid}::{ent}" if sid is not None else path
+        sid = path_to_sid.get(path)
+        return sid if sid is not None else path
+
+    lines: list[str] = []
+    violations = [e for e in edges if e.get("type") == "VIOLATION"]
+    real_edges = [e for e in edges if e.get("type") != "VIOLATION"]
+
+    lines.append(f"; Belief Map")
+    lines.append(f"; generated {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}")
+    lines.append(f"; mode {mode}")
+    lines.append(f"; {total_files} files {len(sorted_nodes)} nodes {len(real_edges)} edges {len(violations)} violations")
+    lines.append("")
+
+    # -- Path tree (compressed trie) --
+    lines.append("; --- paths ---")
+    trie_pairs = [(node["id"], path_to_sid[node["id"]]) for node in sorted_nodes]
+    lines.append("(paths")
+    lines.extend(_build_path_tree(trie_pairs))
+    lines.append(")")
+    lines.append("")
+
+    # -- Nodes with invariant (Gap 1 fix) --
+    lines.append("; --- nodes ---")
+    for node in sorted_nodes:
+        sid = path_to_sid[node["id"]]
+        _LANG_SHORT = {"python": "py", "typescript": "ts", "tsx": "tsx", "jsx": "jsx", "javascript": "js"}
+        lang = _LANG_SHORT.get(node["language"], node["language"][:2])
+        purpose = _sexp_escape(node.get("purpose", ""))
+        inv = node.get("invariant", {})
+        naming = inv.get("naming", "mixed")
+        pkg = inv.get("package", "")
+        lines.append(f'(node {sid} {lang} "{purpose}" :naming {naming} :pkg {pkg})')
+    lines.append("")
+
+    # -- Entities (each has a unique eid based on sha(path::name)) --
+    lines.append("; --- entities ---")
+    for node in sorted_nodes:
+        sid = path_to_sid[node["id"]]
+        for ent in node.get("entities", []):
+            kind = ent["kind"]
+            name = ent["name"]
+            line_num = ent.get("line", 0)
+            eid = _entity_id(node["id"], name)
+            kind_tag = {
+                "class": "cls", "function": "fn", "interface": "ifc",
+                "type": "typ", "enum": "enm",
+            }.get(kind, kind[:3])
+
+            bases = ent.get("bases", [])
+            deco = ent.get("decorators", [])
+            methods = ent.get("methods", [])
+
+            if not bases and not deco and not methods:
+                lines.append(f"({kind_tag} {sid} {name} {line_num} :eid {eid})")
+            else:
+                parts = [f"({kind_tag} {sid} {name} {line_num} :eid {eid}"]
+                if bases:
+                    parts.append(f"(:bases {' '.join(bases)})")
+                if deco:
+                    parts.append(f"(:deco {' '.join(deco)})")
+                if methods:
+                    parts.append(f"(:methods {' '.join(methods)})")
+                lines.append(" ".join(parts) + ")")
+    lines.append("")
+
+    # -- Edges --
+    lines.append("; --- edges ---")
+    sorted_edges = sorted(real_edges, key=lambda e: (e["type"], e["source"], e["target"]))
+    for edge in sorted_edges:
+        src = _pid(edge["source"])
+        tgt = _pid(edge["target"])
+        etype = edge["type"]
+
+        if etype == "IMPORTS":
+            flags = " :via-base" if edge.get("via_base") else ""
+            lsp = " :lsp" if edge.get("lsp_verified") else ""
+            lines.append(f"(imports {src} {tgt}{flags}{lsp})")
+        elif etype == "CALLS_API":
+            lsp = " :lsp" if edge.get("lsp_verified") else ""
+            lines.append(f"(calls-api {src} {tgt} :via-ifc{lsp})")
+        elif etype == "DATA_FLOWS_TO":
+            flags = " :validated" if edge.get("validated") else ""
+            lines.append(f"(data-flow {src} {tgt}{flags})")
+        elif etype == "REFERENCES":
+            lsp = " :lsp" if edge.get("lsp_verified") else ""
+            lines.append(f"(refs {src} {tgt}{lsp})")
+        elif etype == "CALLS":
+            fl = edge.get("from_lines", [])
+            lns = f" :lines {' '.join(str(l) for l in fl)}" if fl else ""
+            lines.append(f"(calls {src} {tgt}{lns} :lsp)")
+        elif etype == "HTTP_CALLS":
+            client = edge.get("client_entity", "")
+            client_str = f" :client {client}" if client else ""
+            lines.append(f"(http-calls {src} {tgt} :transport http{client_str})")
+
+    # -- Violations (Gap 2 fix) --
+    if violations:
+        lines.append("")
+        lines.append("; --- violations ---")
+        for v in violations:
+            src = _pid(v["source"])
+            tgt = _pid(v["target"])
+            rule = v.get("rule", "unknown")
+            detail = _sexp_escape(v.get("detail", ""))
+            lines.append(f'(violation {rule} {src} {tgt} "{detail}")')
+
+    with open(output_path, "w") as f:
+        f.write("\n".join(lines))
+        f.write("\n")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    args = sys.argv[1:]
+    full_rebuild = "--full" in args
+    use_lsp = "--lsp" in args
+    lsp_timeout = LSP_REQUEST_TIMEOUT
+
+    # Parse --lsp-timeout N
+    known_flags = {"--full", "--lsp"}
+    clean_args = []
+    i = 0
+    while i < len(args):
+        if args[i] == "--lsp-timeout" and i + 1 < len(args):
+            try:
+                lsp_timeout = float(args[i + 1])
+            except ValueError:
+                print(f"Error: invalid --lsp-timeout value: {args[i + 1]}", file=sys.stderr)
+                sys.exit(1)
+            i += 2
+            continue
+        if args[i] not in known_flags:
+            clean_args.append(args[i])
+        i += 1
+
+    root = os.path.abspath(clean_args[0] if clean_args else ".")
+    if not os.path.isdir(root):
+        print(f"Error: {root} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    t0 = time.monotonic()
+    mode = "LSP-enhanced" if use_lsp else "regex/AST"
+    print(f"[belief-map] Scanning {root} ... (mode: {mode})")
+
+    files = discover_files(root)
+    py_count = sum(1 for _, l, _ in files if l == "python")
+    ts_count = sum(1 for _, l, _ in files if l == "typescript")
+    print(f"[belief-map] Found {len(files)} source files ({py_count} py, {ts_count} ts)")
+
+    cache = {} if full_rebuild else load_cache(root)
+    to_parse: list[tuple[str, str, str]] = []
+    cached_results: list[FileResult] = []
+
+    for path, lang, repo in files:
+        entry = cache.get(path)
+        if entry and not full_rebuild:
+            try:
+                cur_mtime = os.path.getmtime(path)
+                if cur_mtime <= entry.get("mtime", 0):
+                    cached_results.append(FileResult(**entry["result"]))
+                    continue
+            except OSError:
+                pass
+        to_parse.append((path, lang, repo))
+
+    print(f"[belief-map] Parsing {len(to_parse)} changed files ({len(cached_results)} cached)")
+
+    new_results: list[FileResult] = []
+    if to_parse:
+        workers = min(os.cpu_count() or 4, len(to_parse))
+        with ProcessPoolExecutor(max_workers=workers) as pool:
+            futures = {pool.submit(parse_file, item): item for item in to_parse}
+            for fut in as_completed(futures):
+                result = fut.result()
+                if result:
+                    new_results.append(result)
+
+    # Update cache
+    new_cache: dict = {}
+    all_results = cached_results + new_results
+    for r in all_results:
+        new_cache[r.path] = {
+            "mtime": r.mtime,
+            "result": {
+                "path": r.path,
+                "language": r.language,
+                "repo": r.repo,
+                "mtime": r.mtime,
+                "content_hash": r.content_hash,
+                "imports": r.imports,
+                "exports_abstract": r.exports_abstract,
+                "implements": r.implements,
+                "extends": r.extends,
+                "purpose": r.purpose,
+                "naming_convention": r.naming_convention,
+                "has_validation": r.has_validation,
+                "entities": r.entities,
+                "imported_names": r.imported_names,
+                "exported_names": r.exported_names,
+            },
+        }
+    save_cache(root, new_cache)
+
+    # Build graph (regex/AST pass)
+    nodes, edges = build_graph(all_results, root)
+
+    t_regex = time.monotonic() - t0
+    print(f"[belief-map] Regex/AST pass: {t_regex:.2f}s -- {len(nodes)} nodes, {len(edges)} edges")
+
+    # LSP enrichment pass (if requested)
+    if use_lsp:
+        t_lsp_start = time.monotonic()
+        print(f"[belief-map] Starting LSP enrichment (timeout={lsp_timeout}s per request) ...")
+        nodes, edges = enrich_with_lsp(root, all_results, nodes, edges, lsp_timeout)
+        t_lsp = time.monotonic() - t_lsp_start
+        print(f"[belief-map] LSP pass: {t_lsp:.2f}s")
+
+    # Write output
+    output_path = os.path.join(root, OUTPUT_FILE)
+    write_sexp(output_path, nodes, edges, root, mode, len(all_results))
+
+    elapsed = time.monotonic() - t0
+    print(f"[belief-map] Done in {elapsed:.2f}s -- {len(nodes)} nodes, {len(edges)} edges")
+    print(f"[belief-map] Output: {output_path}")
+
+    # Stats
+    repos = sorted(set(n["repo"] for n in nodes))
+    print(f"[belief-map] Repos: {', '.join(repos)}")
+
+    from collections import Counter
+    edge_types = Counter(e["type"] for e in edges)
+    total_entities = sum(len(n.get("entities", [])) for n in nodes)
+    lsp_verified = sum(1 for e in edges if e.get("lsp_verified"))
+    print(f"[belief-map] Entities: {total_entities}")
+    for etype, count in sorted(edge_types.items()):
+        print(f"[belief-map]   {etype}: {count}")
+    if lsp_verified:
+        print(f"[belief-map]   LSP-verified: {lsp_verified}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build_infra_topology.py b/scripts/build_infra_topology.py
new file mode 100644
index 0000000..72a0fa3
--- /dev/null
+++ b/scripts/build_infra_topology.py
@@ -0,0 +1,853 @@
+from __future__ import annotations
+
+"""build_infra_topology.py -- scan Kustomize, Helm, and Terraform files and
+emit infra topology facts in sexp format.
+
+Usage:
+    python3 build_infra_topology.py [ROOT] [OPTIONS]
+
+Options:
+    ROOT          Workspace root (default: .)
+    --kustomize   Scan for kustomize files (default: auto-detect)
+    --helm        Scan for helm charts (default: auto-detect)
+    --terraform   Scan for terraform files (default: auto-detect)
+    --append FILE Append output to existing sexp file
+    --stdout      Print to stdout (default if no --append)
+"""
+
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# PyYAML guard
+# ---------------------------------------------------------------------------
+
+try:
+    import yaml  # type: ignore[import-untyped]
+except ImportError:
+    print(
+        "Error: PyYAML is required. Install it with: pip install pyyaml",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SKIP_DIRS: frozenset[str] = frozenset(
+    {"node_modules", ".git", ".venv", "dist", "build", "coverage", "target", "__pycache__"}
+)
+
+KUSTOMIZE_FILENAMES: tuple[str, ...] = ("kustomization.yaml", "kustomization.yml")
+HELM_CHART_FILENAME = "Chart.yaml"
+TERRAFORM_MAIN_FILENAME = "main.tf"
+
+# Env-var heuristic patterns: (compiled_regex, inferred_dep_kind, transport)
+# The dep_kind is either a generic service hint or a named infrastructure type.
+_ENV_HEURISTICS: list[tuple[re.Pattern[str], str, str]] = [
+    (re.compile(r"DATABASE_URL|POSTGRES_HOST|POSTGRES_URL|PG_HOST|PG_URL|PGHOST"), "postgres", "tcp"),
+    (re.compile(r"RABBITMQ_HOST|RABBITMQ_URL|AMQP_HOST|AMQP_URL|AMQP_URI"), "rabbitmq", "amqp"),
+    (re.compile(r"NATS_URL|NATS_HOST|NATS_URI"), "nats", "tcp"),
+    (re.compile(r"REDIS_HOST|REDIS_URL|REDIS_URI"), "redis", "tcp"),
+    (re.compile(r"S3_ENDPOINT|S3_HOST|MINIO_HOST|MINIO_URL|AWS_S3_ENDPOINT"), "minio", "http"),
+    (re.compile(r"VAULT_ADDR|VAULT_HOST|VAULT_URL"), "vault", "http"),
+    # Generic service references come last to avoid shadowing the above
+    (re.compile(r"(.+?)_HOST$|(.+?)_URL$|(.+?)_SERVICE_HOST$|(.+?)_ENDPOINT$"), "service", "http"),
+]
+
+# Module-reference pattern inside Terraform: module.<name>.<attr>
+_TF_MODULE_REF_RE = re.compile(r"module\.(\w+)\.")
+
+# Terraform block parsers (no hcl2 dependency)
+_TF_MODULE_BLOCK_RE = re.compile(r'module\s+"(\w+)"\s*\{([^}]*)\}', re.DOTALL)
+_TF_MODULE_SOURCE_RE = re.compile(r'source\s*=\s*"([^"]+)"')
+_TF_RESOURCE_BLOCK_RE = re.compile(r'resource\s+"(\w+)"\s+"(\w+)"\s*\{')
+
+
+# ---------------------------------------------------------------------------
+# Domain types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class InfraNode:
+    id: str           # infra/<name>
+    kind: str         # deployment | statefulset | helm-chart | terraform
+    image: str        # container image or ""
+    port: int         # primary port or 0
+    component: str    # k8s app.kubernetes.io/component label or ""
+    source_file: str  # path to the manifest
+
+
+@dataclass(frozen=True)
+class InfraEdge:
+    source: str       # infra/<name>
+    target: str       # infra/<name>
+    edge_type: str    # k8s-depends | helm-depends | tf-depends | infra-maps | k8s-service
+    via: str          # env | dns | chart-dependency | module-reference | image-name
+    transport: str    # http | tcp | amqp | grpc | ""
+    # For k8s-service facts the target holds the dns-name and extra is namespace
+    extra: str = ""
+
+
+@dataclass
+class TopologyResult:
+    nodes: list[InfraNode] = field(default_factory=list)
+    edges: list[InfraEdge] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Pure utilities
+# ---------------------------------------------------------------------------
+
+
+def _infra_id(name: str) -> str:
+    """Return the canonical infra/ prefixed node id for a service name."""
+    return f"infra/{name}"
+
+
+def _safe_load_yaml(path: Path, warnings: list[str]) -> Optional[dict]:
+    """Load a YAML file, appending a warning on failure and returning None."""
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            data = yaml.safe_load(fh)
+        if not isinstance(data, dict):
+            return None
+        return data
+    except FileNotFoundError:
+        warnings.append(f"; warning: skipped {path}: file not found")
+        return None
+    except yaml.YAMLError as exc:
+        warnings.append(f"; error: parse failed {path}: {exc}")
+        return None
+
+
+def _walk_dirs(root: Path) -> list[Path]:
+    """Yield all sub-directories under root, skipping SKIP_DIRS."""
+    results: list[Path] = []
+    for dirpath, dirnames, _ in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        results.append(Path(dirpath))
+    return results
+
+
+def _infer_dep_from_env(env_name: str) -> Optional[tuple[str, str]]:
+    """Return (dep_kind, transport) inferred from an env var name, or None."""
+    for pattern, dep_kind, transport in _ENV_HEURISTICS:
+        m = pattern.match(env_name)
+        if m:
+            if dep_kind == "service":
+                # Extract the service name from the prefix captured group
+                prefix = next((g for g in m.groups() if g), None)
+                if prefix:
+                    # Convert SCREAMING_SNAKE to kebab-case service name
+                    service_name = prefix.lower().replace("_", "-")
+                    return (service_name, transport)
+                return None
+            return (dep_kind, transport)
+    return None
+
+
+def _extract_env_deps(
+    env_list: list[dict],
+    source_id: str,
+    known_node_names: frozenset[str],
+) -> list[InfraEdge]:
+    """Return dependency edges inferred from a list of k8s env var dicts."""
+    edges: list[InfraEdge] = []
+    seen: set[str] = set()
+
+    for env in env_list:
+        name = env.get("name", "")
+        if not name:
+            continue
+        result = _infer_dep_from_env(name)
+        if result is None:
+            continue
+        dep_kind, transport = result
+
+        # Resolve target: prefer a known infra node by name, else use the dep_kind
+        target_name = dep_kind
+        # Check if any known node name contains the dep_kind as a substring
+        for node_name in known_node_names:
+            if dep_kind in node_name or node_name.endswith(dep_kind):
+                target_name = node_name
+                break
+
+        target_id = _infra_id(target_name)
+        key = f"{source_id}->{target_id}"
+        if key in seen:
+            continue
+        seen.add(key)
+
+        edges.append(
+            InfraEdge(
+                source=source_id,
+                target=target_id,
+                edge_type="k8s-depends",
+                via="env",
+                transport=transport,
+            )
+        )
+    return edges
+
+
+# ---------------------------------------------------------------------------
+# Kustomize parser
+# ---------------------------------------------------------------------------
+
+
+def _parse_kustomization_resources(
+    kustom_path: Path,
+    warnings: list[str],
+) -> list[str]:
+    """Return the list of resource paths declared in a kustomization.yaml."""
+    data = _safe_load_yaml(kustom_path, warnings)
+    if data is None:
+        return []
+    resources = data.get("resources", []) or []
+    return [str(r) for r in resources if r]
+
+
+def _find_workload_manifest(resource_dir: Path) -> Optional[Path]:
+    """Find the primary workload manifest inside a resource directory."""
+    candidates = (
+        "deployment.yaml",
+        "deployment.yml",
+        "statefulset.yaml",
+        "statefulset.yml",
+    )
+    for name in candidates:
+        p = resource_dir / name
+        if p.is_file():
+            return p
+    return None
+
+
+def _find_service_manifest(resource_dir: Path) -> Optional[Path]:
+    """Find the service manifest inside a resource directory."""
+    for name in ("service.yaml", "service.yml"):
+        p = resource_dir / name
+        if p.is_file():
+            return p
+    return None
+
+
+def _parse_service_port(service_path: Path, warnings: list[str]) -> tuple[int, str]:
+    """Return (port, namespace) from a Service manifest."""
+    data = _safe_load_yaml(service_path, warnings)
+    if data is None:
+        return (0, "")
+    namespace: str = (data.get("metadata") or {}).get("namespace", "")
+    ports: list[dict] = ((data.get("spec") or {}).get("ports") or [])
+    port: int = 0
+    if ports:
+        port = int(ports[0].get("port", 0))
+    return (port, namespace)
+
+
+def _extract_container_env(container: dict) -> list[dict]:
+    """Return the flat env list from a container spec (env only, not envFrom)."""
+    return container.get("env", []) or []
+
+
+def parse_kustomize(root: Path) -> TopologyResult:
+    """Scan root for kustomization.yaml files and extract infra topology."""
+    result = TopologyResult()
+
+    kustom_files: list[Path] = []
+    for d in _walk_dirs(root):
+        for fname in KUSTOMIZE_FILENAMES:
+            p = d / fname
+            if p.is_file():
+                kustom_files.append(p)
+
+    if not kustom_files:
+        return result
+
+    # First pass: collect all node names for dependency resolution
+    workload_data: list[tuple[Path, Path, dict]] = []  # (kustom_path, manifest, data)
+    for kustom_path in kustom_files:
+        kustom_dir = kustom_path.parent
+        for resource_str in _parse_kustomization_resources(kustom_path, result.warnings):
+            resource_dir = kustom_dir / resource_str
+            if not resource_dir.is_dir():
+                # Could be a direct file reference
+                continue
+            manifest = _find_workload_manifest(resource_dir)
+            if manifest is None:
+                continue
+            data = _safe_load_yaml(manifest, result.warnings)
+            if data and data.get("kind") in ("Deployment", "StatefulSet"):
+                workload_data.append((kustom_path, manifest, data))
+
+    # Collect known names for env heuristic resolution
+    known_names: set[str] = set()
+    for _, _, data in workload_data:
+        name = (data.get("metadata") or {}).get("name", "")
+        if name:
+            known_names.add(name)
+    known_names_frozen = frozenset(known_names)
+
+    # Second pass: emit nodes and edges
+    for kustom_path, manifest, data in workload_data:
+        kustom_dir = kustom_path.parent
+        k8s_kind = data.get("kind", "Deployment").lower()
+        metadata = data.get("metadata", {}) or {}
+        name: str = metadata.get("name", "")
+        if not name:
+            continue
+
+        labels = metadata.get("labels", {}) or {}
+        component: str = labels.get("app.kubernetes.io/component", "")
+
+        spec = data.get("spec", {}) or {}
+        template = spec.get("template", {}) or {}
+        pod_spec = template.get("spec", {}) or {}
+        containers: list[dict] = pod_spec.get("containers", []) or []
+        if not containers:
+            continue
+
+        first_container = containers[0]
+        image: str = first_container.get("image", "")
+        ports: list[dict] = first_container.get("ports", []) or []
+        port: int = int(ports[0].get("containerPort", 0)) if ports else 0
+
+        node_id = _infra_id(name)
+        result.nodes.append(
+            InfraNode(
+                id=node_id,
+                kind=k8s_kind,
+                image=image,
+                port=port,
+                component=component,
+                source_file=str(manifest.relative_to(root) if manifest.is_relative_to(root) else manifest),
+            )
+        )
+
+        # Service manifest for k8s-service fact
+        # Determine the resource dir from the manifest's parent
+        resource_dir = manifest.parent
+        svc_manifest = _find_service_manifest(resource_dir)
+        if svc_manifest:
+            svc_port, namespace = _parse_service_port(svc_manifest, result.warnings)
+            if svc_port == 0:
+                svc_port = port
+            result.edges.append(
+                InfraEdge(
+                    source=node_id,
+                    target=name,
+                    edge_type="k8s-service",
+                    via="service-manifest",
+                    transport="",
+                    extra=namespace,
+                )
+            )
+
+        # Env-var dependency edges
+        env_list = _extract_container_env(first_container)
+        dep_edges = _extract_env_deps(env_list, node_id, known_names_frozen)
+        result.edges.extend(dep_edges)
+
+        # infra-maps cross-layer edge (image name -> source code node)
+        if image:
+            image_base = image.split(":")[0].split("/")[-1]
+            if image_base:
+                result.edges.append(
+                    InfraEdge(
+                        source=node_id,
+                        target=image_base,
+                        edge_type="infra-maps",
+                        via="image-name",
+                        transport="",
+                    )
+                )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Helm parser
+# ---------------------------------------------------------------------------
+
+
+def _parse_chart_yaml(chart_path: Path, warnings: list[str]) -> Optional[dict]:
+    """Load and return Chart.yaml contents."""
+    return _safe_load_yaml(chart_path, warnings)
+
+
+def _parse_values_yaml(values_path: Path, warnings: list[str]) -> dict:
+    """Load values.yaml; return empty dict on failure."""
+    if not values_path.is_file():
+        return {}
+    data = _safe_load_yaml(values_path, warnings)
+    return data if isinstance(data, dict) else {}
+
+
+def _extract_helm_image(values: dict) -> str:
+    """Extract image string from values.yaml using common conventions."""
+    image_section = values.get("image", {}) or {}
+    if isinstance(image_section, dict):
+        repo = image_section.get("repository", "")
+        tag = image_section.get("tag", "")
+        if repo:
+            return f"{repo}:{tag}" if tag else repo
+    return ""
+
+
+def _extract_helm_port(values: dict) -> int:
+    """Extract primary service port from values.yaml."""
+    svc = values.get("service", {}) or {}
+    if isinstance(svc, dict):
+        return int(svc.get("port", 0))
+    return 0
+
+
+def _extract_helm_env_deps(
+    values: dict,
+    source_id: str,
+    known_chart_names: frozenset[str],
+) -> list[InfraEdge]:
+    """Infer service dependencies from env entries in values.yaml."""
+    env_section = values.get("env", {}) or {}
+    if not isinstance(env_section, dict):
+        return []
+    env_list = [{"name": k, "value": str(v)} for k, v in env_section.items()]
+    return _extract_env_deps(env_list, source_id, known_chart_names)
+
+
+def parse_helm(root: Path) -> TopologyResult:
+    """Scan root for Chart.yaml files and extract Helm chart topology."""
+    result = TopologyResult()
+
+    chart_files: list[Path] = []
+    for d in _walk_dirs(root):
+        p = d / HELM_CHART_FILENAME
+        if p.is_file():
+            chart_files.append(p)
+
+    if not chart_files:
+        return result
+
+    # Collect chart names for cross-reference resolution
+    chart_names: dict[str, Path] = {}
+    chart_data_map: dict[Path, dict] = {}
+    for chart_path in chart_files:
+        data = _parse_chart_yaml(chart_path, result.warnings)
+        if data is None:
+            continue
+        chart_name: str = data.get("name", "")
+        if chart_name:
+            chart_names[chart_name] = chart_path
+            chart_data_map[chart_path] = data
+
+    known_chart_names = frozenset(chart_names.keys())
+
+    for chart_path, data in chart_data_map.items():
+        chart_dir = chart_path.parent
+        chart_name = data.get("name", "")
+        if not chart_name:
+            continue
+
+        values = _parse_values_yaml(chart_dir / "values.yaml", result.warnings)
+        image = _extract_helm_image(values)
+        port = _extract_helm_port(values)
+
+        node_id = _infra_id(chart_name)
+        result.nodes.append(
+            InfraNode(
+                id=node_id,
+                kind="helm-chart",
+                image=image,
+                port=port,
+                component="",
+                source_file=str(chart_path.relative_to(root) if chart_path.is_relative_to(root) else chart_path),
+            )
+        )
+
+        # Chart dependency edges
+        dependencies: list[dict] = data.get("dependencies", []) or []
+        for dep in dependencies:
+            dep_name: str = dep.get("name", "")
+            if not dep_name:
+                continue
+            target_id = _infra_id(dep_name)
+            result.edges.append(
+                InfraEdge(
+                    source=node_id,
+                    target=target_id,
+                    edge_type="helm-depends",
+                    via="chart-dependency",
+                    transport="",
+                )
+            )
+
+        # Env-var dependency edges from values
+        env_edges = _extract_helm_env_deps(values, node_id, known_chart_names)
+        result.edges.extend(env_edges)
+
+        # infra-maps cross-layer edge
+        if image:
+            image_base = image.split(":")[0].split("/")[-1]
+            if image_base:
+                result.edges.append(
+                    InfraEdge(
+                        source=node_id,
+                        target=image_base,
+                        edge_type="infra-maps",
+                        via="image-name",
+                        transport="",
+                    )
+                )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Terraform parser (regex-based, no hcl2 dependency)
+# ---------------------------------------------------------------------------
+
+
+def _read_tf_files(tf_dir: Path) -> str:
+    """Concatenate all .tf files in a directory into one string."""
+    parts: list[str] = []
+    for p in sorted(tf_dir.glob("*.tf")):
+        try:
+            parts.append(p.read_text(encoding="utf-8", errors="replace"))
+        except OSError:
+            pass
+    return "\n".join(parts)
+
+
+def _parse_tf_modules(content: str) -> dict[str, str]:
+    """Return {module_name: source_path} from HCL content."""
+    modules: dict[str, str] = {}
+    for m in _TF_MODULE_BLOCK_RE.finditer(content):
+        mod_name = m.group(1)
+        body = m.group(2)
+        src_match = _TF_MODULE_SOURCE_RE.search(body)
+        source = src_match.group(1) if src_match else ""
+        modules[mod_name] = source
+    return modules
+
+
+def _parse_tf_resources(content: str) -> list[tuple[str, str]]:
+    """Return [(resource_type, resource_name)] from HCL content."""
+    return [
+        (m.group(1), m.group(2))
+        for m in _TF_RESOURCE_BLOCK_RE.finditer(content)
+    ]
+
+
+def _find_cross_module_refs(
+    content: str,
+    all_module_names: frozenset[str],
+) -> set[str]:
+    """Return set of module names referenced via module.<name>. syntax."""
+    refs: set[str] = set()
+    for m in _TF_MODULE_REF_RE.finditer(content):
+        ref_name = m.group(1)
+        if ref_name in all_module_names:
+            refs.add(ref_name)
+    return refs
+
+
+def parse_terraform(root: Path) -> TopologyResult:
+    """Scan root for Terraform directories and extract module topology."""
+    result = TopologyResult()
+
+    # Find all directories containing main.tf
+    tf_dirs: list[Path] = []
+    for d in _walk_dirs(root):
+        if (d / TERRAFORM_MAIN_FILENAME).is_file():
+            tf_dirs.append(d)
+
+    if not tf_dirs:
+        return result
+
+    result.warnings.append(
+        "; warning: terraform parsed with regex fallback (no hcl2 dependency)"
+    )
+
+    # Each tf_dir is an independent Terraform root; we treat module blocks as nodes
+    # and cross-module references as edges within the same root.
+    for tf_dir in tf_dirs:
+        content = _read_tf_files(tf_dir)
+        if not content.strip():
+            continue
+
+        modules = _parse_tf_modules(content)
+        resources = _parse_tf_resources(content)
+        all_module_names = frozenset(modules.keys())
+
+        rel_dir = str(tf_dir.relative_to(root) if tf_dir.is_relative_to(root) else tf_dir)
+
+        # If there are resource blocks, emit per-resource nodes
+        for res_type, res_name in resources:
+            node_name = f"tf-{res_name}"
+            node_id = _infra_id(node_name)
+            result.nodes.append(
+                InfraNode(
+                    id=node_id,
+                    kind="terraform",
+                    image="",
+                    port=0,
+                    component=res_type,
+                    source_file=rel_dir,
+                )
+            )
+
+        # Emit a node for each module block
+        for mod_name in modules:
+            node_name = f"tf-{mod_name}"
+            node_id = _infra_id(node_name)
+            result.nodes.append(
+                InfraNode(
+                    id=node_id,
+                    kind="terraform",
+                    image="",
+                    port=0,
+                    component="module",
+                    source_file=rel_dir,
+                )
+            )
+
+        # Find cross-module dependencies: for each module block, scan its body
+        # for references to other modules
+        for m in _TF_MODULE_BLOCK_RE.finditer(content):
+            src_mod_name = m.group(1)
+            body = m.group(2)
+            refs = _find_cross_module_refs(body, all_module_names - {src_mod_name})
+            src_id = _infra_id(f"tf-{src_mod_name}")
+            for ref in sorted(refs):
+                tgt_id = _infra_id(f"tf-{ref}")
+                result.edges.append(
+                    InfraEdge(
+                        source=src_id,
+                        target=tgt_id,
+                        edge_type="tf-depends",
+                        via="module-reference",
+                        transport="",
+                    )
+                )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Sexp writer
+# ---------------------------------------------------------------------------
+
+
+def _quote(s: str) -> str:
+    """Wrap s in double quotes, escaping inner quotes and backslashes."""
+    escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _needs_quoting(s: str) -> bool:
+    """Return True if s contains whitespace or sexp-special characters."""
+    return bool(re.search(r'[\s"()\\]', s))
+
+
+def _atom(s: str) -> str:
+    """Return s as a sexp atom, quoting if necessary."""
+    if not s:
+        return '""'
+    return _quote(s) if _needs_quoting(s) else s
+
+
+def render_sexp(nodes: list[InfraNode], edges: list[InfraEdge]) -> list[str]:
+    """Return a list of sexp lines representing the infra topology."""
+    lines: list[str] = ["", "; --- infrastructure topology ---"]
+
+    # Deduplicate nodes by id, keeping first occurrence
+    seen_nodes: set[str] = set()
+    unique_nodes: list[InfraNode] = []
+    for node in nodes:
+        if node.id not in seen_nodes:
+            seen_nodes.add(node.id)
+            unique_nodes.append(node)
+
+    for node in sorted(unique_nodes, key=lambda n: n.id):
+        parts: list[str] = [f"(infra-node {node.id}"]
+        parts.append(f":kind {node.kind}")
+        if node.image:
+            parts.append(f":image {_atom(node.image)}")
+        if node.port:
+            parts.append(f":port {node.port}")
+        if node.component:
+            parts.append(f":component {_atom(node.component)}")
+        lines.append(" ".join(parts) + ")")
+
+    if unique_nodes:
+        lines.append("")
+
+    # Deduplicate edges by (source, target, edge_type, via)
+    seen_edges: set[tuple[str, str, str, str]] = set()
+    unique_edges: list[InfraEdge] = []
+    for edge in edges:
+        key = (edge.source, edge.target, edge.edge_type, edge.via)
+        if key not in seen_edges:
+            seen_edges.add(key)
+            unique_edges.append(edge)
+
+    for edge in sorted(unique_edges, key=lambda e: (e.edge_type, e.source, e.target)):
+        if edge.edge_type == "k8s-depends":
+            transport_str = f" :transport {edge.transport}" if edge.transport else ""
+            lines.append(
+                f"({edge.edge_type} {edge.source} {edge.target}"
+                f" :via {edge.via}{transport_str})"
+            )
+        elif edge.edge_type == "k8s-service":
+            ns_str = f" :namespace {_atom(edge.extra)}" if edge.extra else ""
+            # target holds the dns service name for k8s-service facts
+            lines.append(
+                f"(k8s-service {edge.source} {_atom(edge.target)}{ns_str})"
+            )
+        elif edge.edge_type == "helm-depends":
+            lines.append(
+                f"(helm-depends {edge.source} {edge.target} :via {edge.via})"
+            )
+        elif edge.edge_type == "tf-depends":
+            lines.append(
+                f"(tf-depends {edge.source} {edge.target} :via {edge.via})"
+            )
+        elif edge.edge_type == "infra-maps":
+            lines.append(
+                f"(infra-maps {edge.source} {_atom(edge.target)} :via {edge.via})"
+            )
+
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Merge results
+# ---------------------------------------------------------------------------
+
+
+def merge_results(results: list[TopologyResult]) -> TopologyResult:
+    """Combine multiple TopologyResult instances into one."""
+    merged = TopologyResult()
+    for r in results:
+        merged.nodes.extend(r.nodes)
+        merged.edges.extend(r.edges)
+        merged.warnings.extend(r.warnings)
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def _parse_args(argv: list[str]) -> tuple[Path, bool, bool, bool, Optional[Path], bool]:
+    """Parse CLI arguments.
+
+    Returns (root, do_kustomize, do_helm, do_terraform, append_file, stdout_mode).
+    """
+    root = Path(".")
+    do_kustomize: Optional[bool] = None
+    do_helm: Optional[bool] = None
+    do_terraform: Optional[bool] = None
+    append_file: Optional[Path] = None
+    stdout_mode = False
+
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--kustomize":
+            do_kustomize = True
+        elif arg == "--helm":
+            do_helm = True
+        elif arg == "--terraform":
+            do_terraform = True
+        elif arg == "--stdout":
+            stdout_mode = True
+        elif arg == "--append":
+            i += 1
+            if i < len(argv):
+                append_file = Path(argv[i])
+        elif not arg.startswith("--"):
+            root = Path(arg)
+        i += 1
+
+    # Auto-detect mode: run all parsers unless explicitly requested
+    if do_kustomize is None and do_helm is None and do_terraform is None:
+        do_kustomize = True
+        do_helm = True
+        do_terraform = True
+
+    return (
+        root,
+        bool(do_kustomize),
+        bool(do_helm),
+        bool(do_terraform),
+        append_file,
+        stdout_mode or (append_file is None),
+    )
+
+
+def main() -> None:
+    root, do_kustomize, do_helm, do_terraform, append_file, stdout_mode = _parse_args(
+        sys.argv[1:]
+    )
+
+    if not root.is_dir():
+        print(f"Error: root directory not found: {root}", file=sys.stderr)
+        sys.exit(1)
+
+    results: list[TopologyResult] = []
+
+    if do_kustomize:
+        results.append(parse_kustomize(root))
+    if do_helm:
+        results.append(parse_helm(root))
+    if do_terraform:
+        results.append(parse_terraform(root))
+
+    merged = merge_results(results)
+
+    # Emit warnings to stderr
+    for w in merged.warnings:
+        print(w, file=sys.stderr)
+
+    if not merged.nodes and not merged.edges:
+        print("; info: no infrastructure files found", file=sys.stderr)
+        if not stdout_mode and append_file is None:
+            return
+        # Still write the comment so callers know the script ran
+        output_lines = ["", "; --- infrastructure topology ---", "; info: no infrastructure files found"]
+    else:
+        output_lines = render_sexp(merged.nodes, merged.edges)
+
+    output_text = "\n".join(output_lines) + "\n"
+
+    if stdout_mode:
+        sys.stdout.write(output_text)
+
+    if append_file is not None:
+        try:
+            with append_file.open("a", encoding="utf-8") as fh:
+                fh.write(output_text)
+        except OSError as exc:
+            print(f"Error: could not append to {append_file}: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    node_count = len({n.id for n in merged.nodes})
+    edge_count = len(merged.edges)
+    print(
+        f"[infra-topology] Done: {node_count} nodes, {edge_count} edges",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/git_descendants.py b/scripts/git_descendants.py
new file mode 100755
index 0000000..ed07e0b
--- /dev/null
+++ b/scripts/git_descendants.py
@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Git Descendants Finder -- find all commits that descend from HEAD.
+
+Builds a parent-child graph from git rev-list, then BFS-walks forward
+from HEAD to find all descendant commits. Useful for understanding
+what work was built on top of a given commit.
+
+Usage::
+
+    git_descendants.py              # descendants of HEAD
+    git_descendants.py <ref>        # descendants of a specific commit/ref
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def run_git(cmd: str, cwd: str | None = None) -> list[str]:
+    """Run a git command and return output lines."""
+    result = subprocess.run(cmd, shell=True, capture_output=True, text=True, cwd=cwd)
+    if result.returncode != 0:
+        print(f"Error running: {cmd}", file=sys.stderr)
+        print(result.stderr, file=sys.stderr)
+        sys.exit(1)
+    return result.stdout.strip().split("\n") if result.stdout.strip() else []
+
+
+def get_commit_sha(ref: str = "HEAD", cwd: str | None = None) -> str:
+    """Resolve a ref to a full SHA."""
+    result = subprocess.run(
+        ["git", "rev-parse", ref], capture_output=True, text=True, cwd=cwd,
+    )
+    if result.returncode != 0:
+        print(f"Error: cannot resolve ref '{ref}'", file=sys.stderr)
+        sys.exit(1)
+    return result.stdout.strip()
+
+
+def build_parent_child_map(
+    cwd: str | None = None,
+) -> tuple[dict[str, str], dict[str, list[str]]]:
+    """Build a map of commit -> leftmost parent and parent -> children."""
+    print("Building commit graph...", file=sys.stderr)
+
+    commits = run_git("git rev-list --all --reflog --parents", cwd=cwd)
+
+    parent_map: dict[str, str] = {}
+    children_map: dict[str, list[str]] = {}
+
+    for line in commits:
+        parts = line.split()
+        if not parts:
+            continue
+
+        commit = parts[0]
+        parents = parts[1:]
+
+        if parents:
+            leftmost_parent = parents[0]
+            parent_map[commit] = leftmost_parent
+
+            if leftmost_parent not in children_map:
+                children_map[leftmost_parent] = []
+            children_map[leftmost_parent].append(commit)
+
+    print(f"Found {len(parent_map)} commits with parents", file=sys.stderr)
+    return parent_map, children_map
+
+
+def find_all_descendants(
+    commit: str, children_map: dict[str, list[str]],
+) -> set[str]:
+    """Find all descendants of a commit using BFS."""
+    descendants: set[str] = set()
+    queue = [commit]
+
+    while queue:
+        current = queue.pop(0)
+
+        if current in children_map:
+            for child in children_map[current]:
+                if child not in descendants:
+                    descendants.add(child)
+                    queue.append(child)
+
+    return descendants
+
+
+def main() -> None:
+    ref = sys.argv[1] if len(sys.argv) > 1 else "HEAD"
+
+    full_sha = get_commit_sha(ref)
+    short_sha = subprocess.run(
+        ["git", "rev-parse", "--short", full_sha],
+        capture_output=True, text=True,
+    ).stdout.strip()
+
+    print(f"Finding descendants of {ref}: {short_sha}", file=sys.stderr)
+    print(f"Full SHA: {full_sha}", file=sys.stderr)
+    print(file=sys.stderr)
+
+    _parent_map, children_map = build_parent_child_map()
+
+    descendants = find_all_descendants(full_sha, children_map)
+
+    print(f"Found {len(descendants)} descendant commits", file=sys.stderr)
+    print(file=sys.stderr)
+
+    if descendants:
+        for commit in sorted(descendants):
+            commit_info = subprocess.run(
+                ["git", "log", "-1", "--format=%h %s", commit],
+                capture_output=True, text=True,
+            ).stdout.strip()
+            print(commit_info)
+    else:
+        print("No descendants found", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/test_belief_search.py b/tests/test_belief_search.py
new file mode 100644
index 0000000..90eedfe
--- /dev/null
+++ b/tests/test_belief_search.py
@@ -0,0 +1,152 @@
+import importlib.util
+import io
+import sys
+import tempfile
+import textwrap
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+
+SCRIPT_PATH = Path("/Users/alexeus/.codex/skills/codespaces/scripts/belief_search.py")
+SPEC = importlib.util.spec_from_file_location("belief_search", SCRIPT_PATH)
+belief_search = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+sys.modules[SPEC.name] = belief_search
+SPEC.loader.exec_module(belief_search)
+
+
+class BeliefSearchAliasTest(unittest.TestCase):
+    def _load_graph(self) -> tuple[object, str]:
+        tmpdir = tempfile.TemporaryDirectory()
+        self.addCleanup(tmpdir.cleanup)
+
+        sexp_path = Path(tmpdir.name) / ".belief_map.sexp"
+        sexp_path.write_text(
+            textwrap.dedent(
+                """
+                (paths
+                  (app-service
+                    (app-service
+                      (src
+                        (workspace-operatives
+                          (asp543 workspace-operative.service)
+                          (asp544 workspace-operative.service.spec)
+                        )
+                      )
+                    )
+                  )
+                )
+                (node asp543 ts service)
+                (node asp544 ts test)
+                (cls asp543 WorkspaceOperativeService 16)
+                (imports asp544 asp543)
+                """
+            ).strip()
+            + "\n",
+            encoding="utf-8",
+        )
+
+        graph = belief_search.BeliefGraph()
+        graph.load(str(sexp_path))
+        return graph, str(sexp_path)
+
+    def test_resolve_module_accepts_path_aliases(self) -> None:
+        """/* REQ-CS-001: analyze must accept internal path-map aliases returned by older belief maps. */"""
+        graph, _sexp_path = self._load_graph()
+
+        self.assertEqual(
+            graph.resolve_module("asp543"),
+            ["app-service/app-service/src/workspace-operatives/workspace-operative.service"],
+        )
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_analyze(graph, "asp543")
+
+        self.assertIn(
+            "(analyze app-service/app-service/src/workspace-operatives/workspace-operative.service",
+            output.getvalue(),
+        )
+
+    def test_search_returns_resolved_module_ids(self) -> None:
+        """/* REQ-CS-002: search must emit resolved module IDs instead of raw path-map aliases. */"""
+        graph, sexp_path = self._load_graph()
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_search(graph, "workspace-operative.service", sexp_path)
+
+        lines = output.getvalue().strip().splitlines()
+        self.assertEqual(
+            lines,
+            [
+                "(result app-service/app-service/src/workspace-operatives/workspace-operative.service)",
+                "(result app-service/app-service/src/workspace-operatives/workspace-operative.service.spec)",
+                "(result-count 2)",
+            ],
+        )
+
+    def test_quick_runs_analyze_for_first_resolved_module(self) -> None:
+        """/* REQ-CS-003: quick must provide full analyze output for the first matching module. */"""
+        graph, sexp_path = self._load_graph()
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_quick(graph, "workspace-operative.service", sexp_path)
+
+        text = output.getvalue()
+        self.assertIn(
+            "(analyze app-service/app-service/src/workspace-operatives/workspace-operative.service",
+            text,
+        )
+        self.assertIn(
+            "(boundary-file app-service/app-service/src/workspace-operatives/workspace-operative.service",
+            text,
+        )
+        self.assertNotIn("(boundary app-service/app-service/src/workspace-operatives/workspace-operative.service", text)
+
+    def test_quick_resolves_alias_from_raw_search_hits(self) -> None:
+        """/* REQ-CS-004: quick must resolve legacy path-map aliases found in raw belief-map facts. */"""
+        graph, sexp_path = self._load_graph()
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_quick(graph, "WorkspaceOperativeService", sexp_path)
+
+        self.assertIn(
+            "(analyze app-service/app-service/src/workspace-operatives/workspace-operative.service",
+            output.getvalue(),
+        )
+
+    def test_boundary_files_only_emits_minimal_file_list(self) -> None:
+        """/* REQ-CS-005: boundary --files-only must emit the target and directly related files only. */"""
+        graph, _sexp_path = self._load_graph()
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_boundary(graph, "workspace-operative.service", files_only=True)
+
+        self.assertEqual(
+            output.getvalue().strip().splitlines(),
+            [
+                "app-service/app-service/src/workspace-operatives/workspace-operative.service",
+                "app-service/app-service/src/workspace-operatives/workspace-operative.service.spec",
+            ],
+        )
+
+    def test_no_match_includes_suggestions(self) -> None:
+        """/* REQ-CS-006: no-match errors must surface actionable module suggestions. */"""
+        graph, _sexp_path = self._load_graph()
+
+        output = io.StringIO()
+        with redirect_stdout(output):
+            belief_search.cmd_analyze(graph, "workspace-operative.controller")
+
+        text = output.getvalue()
+        self.assertIn("(error no-match workspace-operative.controller :suggestions", text)
+        self.assertIn("workspace-operative.service", text)
+
+
+if __name__ == "__main__":
+    unittest.main()