@ctxo/cli 0.11.5 → 0.13.0

package/dist/json-index-reader-OXTRTGE6.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  COMMUNITY_HISTORY_DIR,
+  INDEX_ARTIFACT_FILES,
+  JsonIndexReader
+} from "./chunk-DT3ZH4AU.js";
+import "./chunk-5DSKZJNN.js";
+export {
+  COMMUNITY_HISTORY_DIR,
+  INDEX_ARTIFACT_FILES,
+  JsonIndexReader
+};
+//# sourceMappingURL=json-index-reader-OXTRTGE6.js.map

package/llms-full.txt

@@ -1,15 +1,17 @@
 # Ctxo MCP Server — Full Reference
 
 > AI agents don't fail because they can't code. They fail because they code blind. Ctxo gives them the full picture before they write a single line.
-> npm: @ctxo/cli (v0.7.0-alpha.0) | GitHub: https://github.com/alperhankendi/Ctxo
+> npm: @ctxo/cli | GitHub: https://github.com/alperhankendi/Ctxo
 
 ## Setup
 
 ```bash
 npm install -g @ctxo/cli      # One-time global install (gives you the `ctxo` command)
-ctxo init                     # Detect languages + install plugins + wire MCP
+ctxo init                     # Rules, skills, guard, MCP config, git hooks, plugins
 ctxo index                    # Build codebase index (required once)
-ctxo index --check            # CI gate: fail if index stale
+ctxo index --check            # CI gate: fail if index stale (writes nothing, records no snapshot)
+ctxo index --commit HEAD      # Re-index the files one commit changed (what the post-commit hook runs)
+ctxo index --files a.ts b.ts  # Re-index only these files (alias: --file <path>)
 ctxo                          # Start MCP server (stdio transport)
 ```
 
@@ -22,21 +24,25 @@ MCP client configuration:
 
 ## Monorepo & Plugin Architecture (v0.7+)
 
-Ctxo is a pnpm workspace monorepo with six packages:
+Ctxo is a pnpm workspace monorepo:
 
-- `@ctxo/cli` (packages/cli) — CLI entry, composition root, MCP server, tool handlers
-- `@ctxo/plugin-api` (packages/plugin-api) — `CtxoLanguagePlugin` v1 protocol interface
-- `@ctxo/lang-typescript` — ts-morph (full tier) plugin for TS/JS
-- `@ctxo/lang-go` — tree-sitter / gopls plugin for Go
-- `@ctxo/lang-csharp` — Roslyn plugin for C#
+- `@ctxo/cli` (packages/cli) - CLI entry, composition root, MCP server, tool handlers
+- `@ctxo/plugin-api` (packages/plugin-api) - `CtxoLanguagePlugin` protocol interface (v1 and v2)
+- `@ctxo/lang-typescript` - ts-morph (full tier) plugin for TS/JS
+- `@ctxo/lang-go` - tree-sitter / gopls plugin for Go
+- `@ctxo/lang-csharp` - Roslyn plugin for C# (attribute annotations; SQL edges at known call sites when `@ctxo/lang-sql` is installed)
 - `@ctxo/lang-java` - tree-sitter Java plugin (syntax tier); full tier via `@ctxo/lang-java-analyzer` companion package (JRE 11+ required)
+- `@ctxo/lang-sql` (packages/lang-sql) - T-SQL plugin for `.sql` files, protocol v2 (`ctxo install sql`, alias `tsql`)
+- `@ctxo/sql-extract` (packages/sql-extract) - zero-dependency T-SQL tokenizer and recognizers; a library, not a plugin, never discovered
 
-Plugin protocol v1 (`CtxoLanguagePlugin`):
-- `apiVersion: 1`
+Plugin protocol (`CtxoLanguagePlugin`):
+- `apiVersion`: `'1'` or `'2'`, the lowest version the plugin works on. The CLI accepts both (`SUPPORTED_API_VERSIONS = ['1', '2']`) and handles their output identically; `'1'` stays accepted for at least 12 months after `'2'` ships. The official plugins declare `'1'`; `@ctxo/lang-sql` declares `'2'`.
 - `id`: unique plugin identifier
 - `extensions`: file extensions handled (e.g. `['.ts', '.tsx']`)
 - `tier`: `'syntax'` | `'full'`
 - `createAdapter(ctx)`: factory returning an `ILanguageAdapter` instance
+- v2 additions (all additive): the data kinds, `SymbolNode.annotations`, optional `extractFacts`, and `ctx.capabilities` (`facts`, `sqlCallSites`). See "Plugin Protocol v2, Data Coupling and SQL" below.
+- Dependencies: plugins import only from `@ctxo/plugin-api`; the one exception is `@ctxo/sql-extract` (ADR-017).
 
 Discovery: at startup Ctxo scans the project's `package.json` dependencies for names matching `@ctxo/lang-*` or `ctxo-lang-*` and registers them. `ctxo install` adds plugins; `ctxo index --install-missing` auto-installs plugins required by detected languages. New CLI: `ctxo doctor --fix`, `ctxo version`, and `ctxo --version --verbose|--json` for plugin/runtime diagnostics.
 
@@ -55,6 +61,8 @@ Parameters:
 - level (number 1-4, default 3): L1=signature, L2=direct deps, L3=full closure, L4=with token budget
 - intent (string, optional): Filter dependencies by keyword
 
+Nodes carry their `annotations` (C# attributes, SQL table `columns`) at L4 only; L1-L3 omit them (and nodes from the SQLite fallback have none). A 2-part data ID such as `dbo.usp_closeloan::procedure` walks the body of the winning definition; a copy's full ID walks that copy's own body.
+
 When to use: Understanding what a symbol depends on (downstream view).
 Instead of: get_blast_radius (upstream/impact), get_context_for_task (task-specific).
 
@@ -62,14 +70,16 @@ Instead of: get_blast_radius (upstream/impact), get_context_for_task (task-speci
 Find all symbols that would break if a target changes.
 
 Parameters:
-- symbolId (string, required): Symbol ID
+- symbolId (string, required): Symbol ID, or the 2-part ID of a table, view or procedure (`dbo.loans::table`)
 - confidence (enum: confirmed|likely|potential, optional): Filter by tier
 - intent (string, optional): Filter by keyword
 
-Returns: impactedSymbols array with symbolId, depth, riskScore, confidence, edgeKinds.
-3-tier model: confirmed (calls/extends/implements), likely (uses/co-changed), potential (imports-only).
+Returns: impactedSymbols array with symbolId, depth, riskScore, confidence, edgeKinds, coChangeFrequency (when the dependent's file co-changes with the target's file).
+3-tier model by the strongest edge that reaches each dependent: confirmed (calls/extends/implements and the data edges reads/writes/executes), likely (uses/co-changed), potential (imports-only). A potential dependent whose file co-changes with the target's file at frequency above 0.5 is promoted to likely. The traversal is transitive across all tiers; riskScore falls with depth.
+Also returns coChangedFiles (when co-change data exists): up to 10 files that co-change with the target's file at frequency >= 0.5 but have no graph path to it, each with file, frequency, sharedCommits. Informational: not counted in tiers, risk scores or the safe-edit gate.
+Every copy of a table, view or procedure that several files define, and its 2-part ID, reports the same dependents (those of the winning definition).
 
-When to use: BEFORE modifying any function or class.
+When to use: BEFORE modifying any symbol, including a SQL table, view or procedure.
 Instead of: get_logic_slice (forward deps), get_pr_impact (PR-level).
 
 ### get_architectural_overlay
@@ -77,10 +87,12 @@ Get project architectural layer map.
 
 Parameters:
 - layer (string, optional): Filter by layer name
+- mode (enum: both|regex|communities|contexts, default both): "regex" layer map, "communities" Louvain clusters, "contexts" candidate bounded contexts (file level), "both" layers plus communities
+- candidate (number, optional): With mode "contexts", the id of one candidate to return in full
 
-Returns: Symbols grouped into Domain, Infrastructure, Adapter, Test, Composition, Configuration layers.
+Returns: Symbols grouped into Domain, Infrastructure, Adapter, Test, Composition, Configuration layers; with communities, data-driven clusters and god nodes. With mode "contexts", a summary: `commitSha`, `coverage`, `candidates` (`id`, `label`, `fingerprint`, `fileCount`, `cohesion`, top 5 `topTerms`), `hubs` (capped at 50, with `hubsTotal`), `collisions` (capped at 50, with `collisionsTotal`), `unclustered` count and a `hint`. Data coupling appears in the summary as counts only: `sharedTableCount` on each candidate that has shared tables, plus `dataResourcesTotal`, `sharedResourcesTotal` (resources of two or more candidates) and `externalResourcesTotal` (resources no `.sql` file defines). With `candidate: <id>`, that candidate in full (files capped at 15 with `fileCount`, cross-candidate edges, co-change pairs, `sharedTables` with `sharedTableCount`), its hubs (50), its collisions (10, each with only that candidate's own occurrences: `symbolId`, first 5 members, `memberCount`) and its own `dataResources` with `dataResourcesTotal`. `sharedTables`: the first 15 by name, each `{ name, kind?, external, accesses: [{ candidate, modes }], owner?, accessCount }` with up to 10 accesses (the asking candidate's own access always kept). `dataResources`: the first 15 by name, each `{ name, kind?, external, modes, owner?, writerCount }`. When the detail is still larger than the response limit, trailing entries are dropped by name order from the longer of the two lists (dataResources on a tie); the counts keep the totals. An unknown id or no contexts view returns `found: false` with a hint (run `ctxo index`). `ctxo contexts --json` prints the full artifact.
 
-When to use: Onboarding to a new codebase, validating layer boundaries.
+When to use: Onboarding to a new codebase, validating layer boundaries, preparing a context map (mode "contexts").
 
 ### get_why_context
 Retrieve git commit history and anti-pattern warnings for a symbol.
@@ -89,7 +101,7 @@ Parameters:
 - symbolId (string, required): Symbol ID
 - maxCommits (number, optional): Limit to N most recent commits
 
-Returns: commitHistory array + antiPatternWarnings (reverts, rollbacks, undo patterns).
+Returns: commitHistory array + antiPatternWarnings (reverts, rollbacks, undo patterns), and driftSignals when a community snapshot exists. driftSignals carries confidence (low below 3 distinct commits, medium 3-6, high 7+), distinctCommits (different commits in the snapshot history, other than the current one), snapshotsAvailable (history entries passed in, kept for compatibility) and an optional hint.
 
 When to use: Understanding WHY code was written this way, checking for problem history.
 Pair with: get_change_intelligence (complexity/churn scores).
@@ -111,7 +123,7 @@ Parameters:
 - includeTests (boolean, default false): Include test files
 - intent (string, optional): Filter results by keyword
 
-Returns: deadSymbols (with confidence 1.0/0.9/0.7 and reason), deadFiles, unusedExports, scaffolding markers.
+Returns: deadSymbols (with confidence 1.0/0.9/0.7 and reason), deadFiles, unusedExports, scaffolding markers. Symbols in .sql files are never reported (their consumers may live outside the index).
 
 When to use: Cleanup, refactoring, confirming code is truly unused.
 Instead of: find_importers (specific symbol reverse lookup).
@@ -130,6 +142,8 @@ Task types:
 - refactor: Importers + complexity + churn (restructuring)
 - understand: Full slice + architecture (learning)
 
+Context entries that depend on the symbol (its blast radius) carry an optional confidence tier (confirmed|likely|potential); co-change history can raise potential to likely. Entries carry no symbol annotations (use get_logic_slice level 4). A 2-part data ID (`dbo.loans::table`) is accepted.
+
 When to use: BEST starting point when you know the symbol AND your intent.
 
 ### get_ranked_context
@@ -139,6 +153,7 @@ Parameters:
 - query (string, required): Natural language search query
 - tokenBudget (number, default 4000): Max tokens for results
 - strategy (enum: combined|dependency|importance, default combined): Ranking strategy
+- searchMode (enum: fts|legacy, default fts): "fts" is BM25 with camelCase splitting, trigram fallback and automatic typo correction (reported in `fuzzyCorrection`); "legacy" is substring matching
 
 Returns: Symbols ranked by BM25 relevance + PageRank importance, packed within budget.
 
@@ -150,9 +165,10 @@ Search symbols by name or regex pattern.
 
 Parameters:
 - pattern (string, required): Substring or regex pattern
-- kind (enum: function|class|interface|method|variable|type, optional): Filter by kind
+- kind (enum: function|class|interface|method|variable|type|table|view|procedure, optional): Filter by kind (table, view and procedure come from SQL plugins)
 - filePattern (string, optional): Filter by file path substring
 - limit (number 1-100, default 25): Max results
+- mode (enum: regex|fts, default regex): "regex" is a case-insensitive regex or substring match on names; "fts" is BM25 relevance search with typo correction
 
 When to use: Know (part of) the symbol name, need its ID for other tools.
 Instead of: get_ranked_context (semantic/relevance search).
@@ -171,8 +187,8 @@ Instead of: get_pr_impact (full PR risk assessment).
 Find all symbols that depend on a given symbol (reverse dependency).
 
 Parameters:
-- symbolId (string, required): Symbol ID
-- edgeKinds (string[], optional): Filter by imports|calls|extends|implements|uses
+- symbolId (string, required): Symbol ID, or the 2-part ID of a table, view or procedure (`dbo.loans::table`; every copy gives the same importers)
+- edgeKinds (string[], optional): Filter by imports|calls|extends|implements|uses|reads|writes|executes (the last three are data access)
 - transitive (boolean, default false): Follow transitive reverse edges
 - maxDepth (number 1-10, default 5): Max BFS depth
 - intent (string, optional): Filter by keyword
@@ -194,7 +210,7 @@ Rank symbols by PageRank centrality.
 
 Parameters:
 - limit (number 1-200, default 25): Max results
-- kind (enum: function|class|interface|method|variable|type, optional): Filter
+- kind (enum: function|class|interface|method|variable|type|table|view|procedure, optional): Filter (PageRank runs on the whole graph, data edges included)
 - filePattern (string, optional): Filter by file path
 - damping (number 0-1, default 0.85): PageRank damping factor
 
@@ -209,7 +225,7 @@ Parameters:
 - maxFiles (number, default 50): Max files
 - confidence (enum: confirmed|likely|potential, optional): Filter tier
 
-Returns: changedFiles, changedSymbols, totalImpact, riskLevel (low|medium|high), per-file blast radius, co-change data.
+Returns: changedFiles, changedSymbols, totalImpact, riskLevel (low|medium|high), per-file blast radius, co-change data (coChangedWith per file), boundaryViolations (confidence from distinctCommits) and clustersAffected.
 
 When to use: FIRST tool when reviewing a PR or evaluating recent commits.
 
@@ -246,6 +262,10 @@ Onboarding to a new codebase?
   -> get_architectural_overlay (layer map)
   -> get_symbol_importance (most critical symbols)
 
+Preparing a context map?
+  -> get_architectural_overlay(mode: "contexts") (candidate bounded contexts)
+  -> then candidate: <id> for one in full
+
 Cleaning up code?
   -> find_dead_code (unused symbols)
   -> get_change_intelligence (complexity hotspots)
@@ -269,6 +289,7 @@ All tool responses include:
 ```
 - Default truncation threshold: 8KB
 - Configurable via CTXO_RESPONSE_LIMIT environment variable
+- In `get_architectural_overlay` mode "contexts", only `candidates` is truncatable (hint: use `candidate: <id>` or `ctxo contexts --json`); `hubs` and `collisions` are capped at the source and never truncated. In the `candidate: <id>` detail, `sharedTables` and `dataResources` are not truncatable either: they are capped at 15 each and shortened from the end until the detail fits the limit, with `sharedTableCount` and `dataResourcesTotal` keeping the totals
 
 ### Intent Filtering
 4 tools accept `intent` parameter: get_blast_radius, get_logic_slice, find_importers, find_dead_code.
@@ -278,15 +299,151 @@ All tool responses include:
 
 ### Symbol ID Format
 All symbols use deterministic IDs: `"<relativePath>::<name>::<kind>"`
-- Example: `"src/core/graph/symbol-graph.ts::SymbolGraph::class"`
-- Valid kinds: function, class, interface, method, variable, type
-- Valid edge kinds: imports, calls, extends, implements, uses
+- Example: `"src/core/graph/symbol-graph.ts::SymbolGraph::class"`, `"db/lending.sql::dbo.loans::table"`
+- Valid kinds: function, class, interface, method, variable, type, table, view, procedure
+- Valid edge kinds: imports, calls, extends, implements, uses, reads, writes, executes
+- Edge targets may also be 2-part name references (`<name>::<kind>`); data edges point at canonical names such as `dbo.loans::table` (lowercase, delimiters stripped, default schema `dbo`), resolved to the defining `table` or `view`. With several definitions, the winner is a copy outside test files (default test globs; `index.tests` is not consulted), then outside `docs`/`doc`/`documentation` folders, then the codepoint-smallest symbol ID
+- Impact tools (get_blast_radius, find_importers, get_pr_impact, get_context_for_task, the gate, `ctxo blast-radius`) accept a 2-part data ID and give every copy of a multi-defined object the winner's dependents; forward edges (get_logic_slice) stay per copy; get_why_context with a 2-part ID reads the winner's file
 
 ### Resources
 - `ctxo://status` — Health check resource (confirms server is running)
 
 ---
 
+## Co-change, Incremental Indexing and Snapshots (v0.13, #157)
+
+Co-change (files that change together in git history) feeds every blast-radius path: get_blast_radius, get_pr_impact, get_context_for_task, `ctxo blast-radius`, the gate hook and `ctxo gate --preview`.
+
+### The co-change window
+
+Built by `ctxo index` from one `git log --no-merges -M --name-status` pass over the commits reachable from HEAD. The same pass fills each file's `intent[]`, and both follow renames. The window is independent of `--max-history` (which only limits commits kept per file in `intent[]`, default 20). Config in `.ctxo/config.yaml` (all optional):
+
+```yaml
+cochange:
+  maxCommits: 2000        # last N non-merge commits from HEAD, or "all"
+  # since: 12m            # also limit by age; d, w, m, y; counted back from HEAD's committer date
+  maxFilesPerCommit: 30   # commits touching more analysed files are skipped (massSkipped)
+  minShared: 2            # shared commits needed for a pair
+  include: []             # extra tracked, non-indexed files to analyse (globs)
+  exclude: []             # indexed files to leave out (globs); also vetoes include-added files
+```
+
+- CLI overrides: `ctxo index --cochange-commits <n|all>`, `ctxo index --cochange-since <duration>` (30d, 2w, 12m, 1y).
+- A pair becomes an entry at `shared >= minShared` and `frequency = shared / min(countA, countB) >= 0.1`. The applied window is recorded in `.ctxo/index/co-changes.json` under `window`; the file is only rewritten when entries or window change.
+- `commitsScanned` counts every non-merge commit of the repository, so in a monorepo a numeric maxCommits covers fewer relevant commits than its value suggests.
+- Sparse checkout: files outside the cone are absent from the matrix, and their committed index entries are never pruned.
+- `ctxo verify-index` reports files with a rename in their history as STALE until the next `ctxo index` after upgrading, because `intent[]` now follows renames.
+
+### Incremental indexing and the post-commit hook
+
+- `ctxo index --files <path...>` (alias `--file <path>`) re-indexes the listed files. `ctxo index --commit <rev>` re-indexes the files one commit changed and removes the ones it deleted or renamed away. Both load the symbol registry from the committed index and compute co-change, communities, the snapshot, the drift and boundary artifacts and the SQLite cache from the merged index. Candidates pass the same filters as a full run.
+- A full `ctxo index` uses only the files it discovers and prunes index entries of deleted or newly ignored sources (never of skip-worktree paths).
+- `ctxo init` installs a versioned post-commit block (`# ctxo-start v2`) that runs `ctxo index --commit HEAD` once per commit, guarded by `[ -d .ctxo ]`. `ctxo init` and `ctxo doctor --fix` upgrade an older block in place, collapse duplicate blocks, and follow `core.hooksPath`. A global or system `core.hooksPath` is shared by every repository, so ctxo writes nothing there and prints the blocks to add by hand (scope detection needs git 2.26+).
+- `ctxo doctor` has a `git_hooks` check: warns on a missing, outdated or duplicated post-commit block.
+- `ctxo <command> --help` (and `-h`) prints the help and runs nothing.
+
+### One snapshot per commit
+
+`.ctxo/index/communities.json` is the current snapshot and `communities.history/` keeps at most one earlier snapshot per commit. A second run on the same commit replaces the current snapshot without archiving. Drift compares against the newest history entry from a different commit. Drift and boundary confidence count `distinctCommits` (low below 3, medium 3-6, high 7+; boundary needs at least 2). `ctxo index --check` writes nothing and records no snapshot. The first write after upgrading removes older same-commit duplicates from `communities.history/`.
+
+### Gate consequence
+
+The safe-edit gate counts confirmed + likely dependents, so co-change-upgraded dependents count and the gate may fire somewhat more often. `ctxo gate --preview` shows the effect.
+
+Design record: docs/architecture/ADR/adr-016-co-change-engine-and-snapshot-policy.md
+
+---
+
+## Contexts View (v0.13, #156)
+
+Candidate bounded contexts, computed by `ctxo index` and written to `.ctxo/index/contexts-view.json` (committed). Louvain runs on a file graph whose edges blend dependency weight (distinct symbol edges, log-normalised) and co-change frequency; hub files (fan-in or god nodes) have their edges damped by `1 / log2(2 + dependents)` and are listed separately. Groups smaller than `minCandidateFiles` fold into a neighbour; files with no edge are `unclustered`. Each candidate has a suggested label (longest common directory; PageRank fallback at the repo root), a `fingerprint`, cohesion, top terms, cross-candidate edges and co-change pairs. Collisions are type names that appear in two candidates with different member shapes (Jaccard below 0.5). No domain is named automatically.
+
+Refresh: every index run that re-indexes files (full, `--files`, `--commit`, so also every post-commit hook run); skipped by `--skip-community`; not refreshed by `ctxo watch`.
+
+Surfaces: `get_architectural_overlay({ mode: "contexts" })` (summary first, `candidate: <id>` for one in full) and `ctxo contexts [--json]` (table to stderr, full artifact to stdout; without a view it exits 0 with `found: false`).
+
+Config in `.ctxo/config.yaml` (all optional, defaults shown):
+
+```yaml
+communities:               # symbol-level Louvain
+  resolution: 1.0
+  godNodeMinBridged: 3
+  godNodeMaxResults: 25
+contextsView:
+  weights: { dependency: 1.0, coChange: 1.0, data: 0 }   # data: weight of data edges (0 = shared tables never merge candidates)
+  exclude: []              # files left out of the file graph (globs)
+  hubs: { auto: true, topPercent: 1, minDependents: 10, paths: [] }   # paths lose all their edges
+  resolution: 1.0
+  minCandidateFiles: 3
+  technicalTerms: []       # replaces the default list (Service, Repository, Controller, Handler, Manager, Dto, Impl, Async)
+index:
+  tests: []                # extra test-file globs; test files are never graph nodes
+  facts: false             # true asks plugins for code facts (protocol v2, index JSON only)
+```
+
+Design record and evidence: docs/architecture/ADR/adr-016-co-change-engine-and-snapshot-policy.md (addendum "Contexts view defaults (PR 1A)").
+
+---
+
+## Plugin Protocol v2, Data Coupling and SQL (v0.13, #156)
+
+Two services can look independent in the graph while both write the same table. Phase 1 of the domain knowledge layer makes that data coupling visible. Feature doc: docs/features/domain-knowledge.md. Design record: docs/architecture/ADR/adr-017-plugin-protocol-v2-and-data-coupling.md.
+
+### Protocol v2 (`@ctxo/plugin-api`)
+
+- Kinds: `SYMBOL_KINDS` adds `table`, `view`, `procedure`; `EDGE_KINDS` adds `reads`, `writes`, `executes`; `DATA_RESOURCE_KINDS = ['table', 'view']` is what core analyses use.
+- Annotations: `SymbolNode.annotations?: { name, args?, named? }[]`. Always on. Host-language attributes are capped at 20 per symbol, 10 positional entries and 10 named entries plus the reserved `type`, 200 characters per value; `named.type` is reserved for the fully qualified type name, and a source argument named `type` is not kept. lang-sql's `columns` annotation lists every column of a table. Core checks shape only; JSON index only.
+- Facts: `FACT_KINDS = ['literal-comparison', 'normalization', 'retry-timeout', 'endpoint']`, `CodeFact { kind, symbolId, line (0-based), text (single line, trimmed, max 200 chars), detail? }`, optional `ILanguageAdapter.extractFacts`. Called only when `index.facts: true`; results go to the file's index JSON under `facts`. No official plugin implements it yet.
+- Capabilities: `PluginContext.capabilities?: { facts?, sqlCallSites? }`, computed before any `createAdapter` call and offered to every plugin. `sqlCallSites` is set only when a plugin for `.sql` is installed.
+- Versioning: `SUPPORTED_API_VERSIONS = ['1', '2']`; plugins declare the lowest version they work on. Older CLIs skip `@ctxo/lang-sql` with a warning and drop the new kinds from a newer index with a warning.
+
+### `@ctxo/lang-sql`
+
+- `ctxo install sql` (alias `tsql`). Syntax tier, no database, no .NET. Detection, `ctxo doctor` and `ctxo index --install-missing` suggest it when the repository has at least 5 `.sql` files that are also at least 2% of its files (as `git ls-files` lists them).
+- Definitions: `CREATE [OR ALTER] TABLE | VIEW | PROC[EDURE] | FUNCTION`, `ALTER VIEW | PROC[EDURE] | FUNCTION`. Symbol IDs carry the canonical name (`db/lending.sql::dbo.loans::table`); `name` keeps the declared spelling. Functions map to `function`.
+- Accesses from view, procedure and function bodies: `FROM`, `JOIN`, `APPLY`, `MERGE ... USING` -> reads; `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `TRUNCATE TABLE`, `SELECT ... INTO`, `OUTPUT ... INTO` -> writes; `EXEC` / `EXECUTE` -> executes. Temp tables, table variables, CTE names, aliases, 3- and 4-part names and the `sys` / `information_schema` schemas are skipped. Only ASCII A-Z is case-folded.
+- Limits: T-SQL only with `dbo` as the default schema; top-level DML in scripts is skipped; `ALTER TABLE ... ADD` columns count only in the defining file; a CTE name reused later in a batch without `;` is skipped by sql-extract but read by ScriptDom.
+- Size limit: a `.sql` file larger than 5 MiB is skipped (no symbols, edges or facts) with one warning per file: `skipped <file>: <n> MiB is over the 5 MiB SQL size limit`. Use `index.ignore` for dumps to silence it.
+- Several definitions of one object (migrations, docs or test copies): see "Symbol ID Format" above for the winner; every copy reports the winner's dependents, each copy keeps its own forward edges, and the contexts view gives an executing candidate the bodies of every production copy of a procedure (the winner's alone when no copy is production; docs and test copies add nothing when a production copy exists). The winner among production copies is the codepoint-smallest path, not necessarily the newest migration (`V10__` sorts before `V7__`).
+
+### SQL at C# call sites
+
+With lang-sql installed and the Roslyn tier (.NET SDK 8+), the C# helper parses constant SQL with ScriptDom at: `SqlCommand` constructor `cmdText`; `CommandText` assignments on `SqlCommand`, `DbCommand`, `IDbCommand` and subtypes (a procedure name when `CommandType = StoredProcedure` is set on the same local or in the same object initializer); Dapper `SqlMapper` methods starting with `Query` or `Execute` (`sql` argument; `commandType: CommandType.StoredProcedure` means a procedure name); the Dapper `CommandDefinition` constructor (`commandText` argument; a named or positional `commandType` of `StoredProcedure` means a procedure name; the edge belongs to the method that constructs it); `SqlBulkCopy.DestinationTableName` (writes); EF Core `FromSqlRaw`, `ExecuteSqlRaw`, `ExecuteSqlRawAsync`, `SqlQueryRaw` (EF `{0}` placeholders become parameters before parsing). Only compile-time constants count: use `const string`; `static readonly` fields, runtime strings and `CommandText +=` are non-constant. Dapper `IN @ids` is read as `IN (@ids)`. The tree-sitter fallback gives no SQL edges. `DEBUG=ctxo:roslyn` logs the constant, non-constant and unparsable counts.
+
+### C# annotations and test files
+
+- The C# plugin reports attributes in both tiers. Roslyn keeps constant arguments (strings and characters as their value, numbers in invariant culture, booleans, enum constants as `Type.Member`, `typeof(T)` as a display string, arrays flattened, nulls skipped); tree-sitter keeps literal arguments only (strings, numbers, booleans). In the Roslyn semantic path a `name:` argument arrives in `args`; tree-sitter puts it in `named`. Roslyn formats real-number exponents its own way. A source argument named `type` is dropped in both tiers (`named.type` is reserved).
+- Test files (contexts view): a test glob match, or any symbol carrying `Fact`, `Theory`, `SkippableFact`, `SkippableTheory`, `Test`, `TestCase`, `TestCaseSource`, `TestFixture`, `TestMethod`, `DataTestMethod` or `TestClass`. Once C# annotations exist in the index, a file matched only by `**/*Test.cs` or `**/*Tests.cs` needs a test annotation. Missed: test classes with only other attributes (FsCheck `[Property]`), custom attributes derived from `Fact` or `Theory` (names match exactly, base types are not resolved) and unannotated `*Tests.cs` in a bare capital `Tests/` or `Test/` folder (not a default test glob); fix with an `index.tests` glob.
+- Run a full `ctxo index` after upgrading `@ctxo/lang-csharp`: an incremental run annotates only the files it re-indexes, while the contexts view already counts the index as annotated, so name-only test matches that were not re-indexed show up as production files until the full run.
+
+### Data coupling in core and the contexts view
+
+- `reads`, `writes`, `executes` are confirmed blast-radius dependents, so the safe-edit gate also guards heavily used tables and procedures. Data edges stay out of symbol-level communities, god nodes, cross-cluster counts and boundary violations. `.sql` symbols are never dead code.
+- Contexts view artifact: top-level `dataResources` (`name`, `kind?`, `external`, `accesses` per candidate with `modes`, `writers`, `owner?` when exactly one candidate writes it) and per-candidate `sharedTables` (resources of two or more candidates). An `executes` edge to an indexed procedure adds that procedure's reads and writes, transitively; reading a view does not expand to its tables; unclustered files and test files are ignored and hubs count for their assigned candidate.
+- Procedure attribution: procedure bodies count only for the candidates that execute them, decided by canonical name (no copy of an executed procedure credits its own candidate). With several definitions, an executing candidate takes the union of the bodies of every production copy (outside test files and `docs`, `doc` or `documentation` folders), or the winner's body alone when no copy is production; docs and test copies of a procedure that has a production copy add nothing. A procedure that no candidate executes, directly or through other procedures, credits the candidate whose file holds it (with several copies, the candidate of each production copy, or of the winner when none is production); procedures that only execute each other each credit their own candidate. A procedure that only tests or unclustered files execute therefore still credits the script's candidate.
+- `contextsView.weights.data` (default 0) weights data edges between an accessing file and the defining `.sql` file in the file graph. At 0, a `.sql` file joins a candidate only through co-change, so scripts without a co-change partner stay unclustered and lower `coverage` (0.99 to 0.91 on one fixture, candidates unchanged); `contextsView.exclude` leaves them out. Table and view names and columns join the term harvest; tables take part in collisions with their columns, so a C# class and a same-name table can collide (often an entity mapped to its table: possible noise).
+- `ctxo index` appends `, <S> shared tables` to its contexts line; `ctxo contexts` prints the count and one `shared` line per shared resource (owner, several writers or read only).
+- Size: a table shared by k candidates is listed k times with k accesses each in the artifact (k squared growth); the MCP responses are capped.
+
+### Doctor: `csharp_tier`
+
+Five outcomes:
+1. No C# sources: pass, "no C# sources detected".
+2. No .NET 8+ SDK: pass, "syntax tier (install the .NET 8+ SDK for the full tier)".
+3. `@ctxo/lang-csharp` not resolvable from the project: pass, "syntax tier (@ctxo/lang-csharp not installed)".
+4. `dotnet restore` of the helper succeeds: pass, "full tier (.NET SDK <version>, Roslyn helper restores)".
+5. The restore fails or times out (120 s): warn, "syntax tier: the Roslyn helper could not restore (<first error line>)". Fix: make `Microsoft.SqlServer.TransactSql.ScriptDom` and the `Microsoft.CodeAnalysis` packages reachable from your NuGet sources (nuget.org or a mirror), then run `ctxo index`.
+
+When the helper cannot restore or build during `ctxo index`, the C# plugin falls back to tree-sitter (symbols and attribute annotations with literal arguments kept; `named.type`, non-literal argument values and SQL edges lost) and the summary reads `C#: N files (syntax tier - the Roslyn helper failed, run "ctxo doctor")`. In `ctxo watch`, a keep-alive that shut down for inactivity or crashed is restarted once on the next re-index; if that fails, the file falls back to tree-sitter instead of being written with zero symbols. The helper targets `net8.0` with `RollForward` `Major`, so the .NET host can roll forward to a newer major runtime when no 8.x is installed; the built helper has been run with `dotnet exec --fx-version` on .NET 8, 9 and 10. A lone `.csproj` without a solution now indexes in the Roslyn tier.
+
+### Upgrade notes
+
+- First re-index after upgrading rewrites the committed JSON of C# files once (annotations). Make it a full `ctxo index` (see "C# annotations and test files").
+- UTF-16 files with a BOM are decoded; their hash changes once, so `ctxo index --check` reports them stale until the next `ctxo index`.
+- Shared conformance corpus: packages/sql-extract/corpus (`<case>.sql` + `<case>.expected.json`, modes `statement` and `file`), run by sql-extract, lang-sql and (with .NET) ScriptDom.
+
+---
+
 ## Safe-Edit Guard (v0.8+)
 
 The safe-edit guard closes the loop between MCP tool availability and agent compliance. An agent with access to get_blast_radius can still skip it. The guard makes skipping impossible for high-impact symbols on Claude Code.
@@ -300,6 +457,10 @@ The safe-edit guard closes the loop between MCP tool availability and agent comp
 
 On every Edit call, `ctxo gate-hook` checks whether get_blast_radius has been called for that symbol in the current session. If not, the hook blocks the edit and returns a message: "High-impact symbol - run get_blast_radius first." Once the agent calls the tool, the edit goes through. Fires once per symbol per session. Fail-open on any error.
 
+- Matcher `Edit` only: `ctxo gate-hook` ignores every other tool, so `Write` (new files, whole-file rewrites) and `NotebookEdit` are not gated.
+- Session state is a file store: the hook runs as a new process per Edit call, records the symbols it already warned about in `.ctxo/.cache/gate/<session_id>.json`, and also accepts a get_blast_radius call found in the session transcript. It survives MCP server restarts.
+- A `.claude/settings.json` that is not valid JSON (JSONC comments included) or not a settings object is never overwritten; `ctxo init` warns and leaves it. The guard is also detected in `.claude/settings.local.json` (read only).
+
 ### Gate decision
 
 A symbol is flagged if it exceeds both thresholds:
@@ -319,7 +480,7 @@ Sensitivity levels (configured in `.ctxo/config.yaml`):
 ### Skills
 
 Three model-invoked skill files installed to `.claude/skills/` (Claude Code) and `.cursor/rules/` (Cursor):
-- `ctxo-understand`: run get_context_for_task before reading source files
+- `ctxo-understand`: run get_context_for_task at the start of a task, and pick the right tool for a structural question from a question-to-tool table that covers all 14 tools (reading a file to see its contents needs no index call)
 - `ctxo-safe-edit`: run get_blast_radius and get_why_context before any edit
 - `ctxo-review-pr`: run get_pr_impact before reviewing a diff
 
@@ -330,3 +491,34 @@ Three model-invoked skill files installed to `.claude/skills/` (Claude Code) and
 | Claude Code | Yes (PreToolUse) | Yes | Yes |
 | Cursor | No (no blocking pre-edit hook in v3.6) | Yes | Yes |
 | Other platforms | No | Where supported | Yes |
+
+### Tiered rules (v0.13, #159)
+
+`ctxo init` writes one ctxo block into each AI tool's rules file, between `<!-- ctxo-rules-start v<version> -->` and `<!-- ctxo-rules-end -->`. The version is the rules template version, the CLI minor in which the rules text last changed.
+
+- Compact tier, Claude Code only (`CLAUDE.md`, 4 lines of text; at most 8 non-blank lines including the markers, 6 today): written when the guard hook is registered (`.claude/settings.json` or `.claude/settings.local.json`), all three skills are in `.claude/skills/`, and `gate.enabled` is not false. It says the repo has a ctxo index, to use the ctxo tools for structural questions before grepping, that the guard blocks the first edit to a high-impact symbol until get_blast_radius is called, and names the three skills.
+- Full tier: every other client, Claude Code without one of those three, and a rules file several clients share (an `AGENTS.md` or `GEMINI.md` that is a hard link or a symlink to `CLAUDE.md`). First rule: "For structural questions (dependencies, impact, history), use ctxo tools first; reading a file to see its contents needs no index call." Then the tool guide; its modification steps end with "Only then edit the source".
+- The tier follows the disk after the skills and guard steps; `--no-guard` and `--skip skills` give the full block unless the guard and skills are already installed (they remove nothing).
+- Re-runs replace the first ctxo block in place (versioned, unversioned `<!-- ctxo-rules-start -->`, or the old unmarked body), collapse later blocks into it, and keep every byte outside the blocks, including a UTF-8 BOM and CRLF line endings. Create-mode files (`.cursor/rules/ctxo.mdc`, `AGENTS.md` and the rest) keep user content. A block from a newer ctxo, a start marker without an end marker, or an end marker without a start marker leaves the file unchanged with a warning.
+- Formatter stable: blocks and skills are written in the layout Prettier prints, and blocks, the old unmarked body and skills are compared with formatting ignored (line endings, BOM, trailing whitespace, blank lines, table padding; blocks and skills also ignore line wrapping, so `proseWrap: always` or `never` is no edit). A block a formatter reshaped is current and `unchanged`, and the tier is read from the first non-blank line. The compact tier counts a skill only when it is readable and current. A rules file ctxo cannot read is left unchanged with one warning, and init goes on.
+- Held blocks: init (real run, dry run, `--only rules`, `--rules`) and `ctxo doctor --fix` leave `CLAUDE.md` or `.cursor/rules/ctxo.mdc` unchanged when its block is pre-tier or compact, the user has not declined the guard or skills (`--no-guard`, the guard question answered no, `gate.enabled: false`, `--skip skills`), and after the skills and guard steps they are still not on disk (an unreadable `.claude/settings.json` counts as no guard). Init warns `<file>: left unchanged until the guard and skills are installed; run "ctxo init --only rules,skills,guard" or "ctxo doctor --fix"`; the dry run prints `unchanged (held)`. A file linked to a held one is held too. A file without a ctxo block is never held.
+- Skills carry a version marker, `<!-- ctxo-skill v<version> -->` (SKILLS_TEMPLATE_VERSION). An installed skill with a newer marker is left alone with a warning and is not outdated; no marker or an older one is outdated and replaced.
+
+### Granular init (v0.13, #159)
+
+- Parts, run in this order: `config` (`.ctxo/config.yaml`, `.gitignore` entry, `.ctxo/index/`), `skills`, `guard`, `rules`, `mcp`, `git-hooks`.
+- `ctxo init --only <parts>` installs exactly those parts (and skips the plugin step); `ctxo init --skip <parts>` installs the rest (the plugin step still runs); `ctxo init --no-guard` does not install the guard and never asks. `-y` without `--tools` sets up all nine tools, the same set the dry run previews. `--only` cannot be combined with `--skip` or `--rules`; an unknown part exits 1.
+- `ctxo init --rules` is deprecated: the same as `--skip git-hooks,guard`, prints a notice, and still skips the plugin step.
+- The interactive guard question appears only when Claude Code is selected. Cursor gets the skills and the full block, but no guard question and no hook.
+- `ctxo init --dry-run` lists every file init would create or change (`would create`, `would update`, `unchanged`) and writes nothing.
+- Init output: `[ctxo] ✓ <file> (<created|updated|unchanged>)`, warnings as `[ctxo] ⚠ <text>`.
+
+### Agent-setup doctor checks (v0.13, #159)
+
+- `ai_rules`: an outdated block (unversioned, older template, or edited), a `CLAUDE.md` block that expects the guard while it is missing, a current block in the wrong tier, several blocks in one file, a start marker without an end marker, an end marker without a start marker. A block from a newer ctxo passes, and so does a file with no ctxo block. Linked files are reported once.
+- `skills`: missing or outdated ctxo skills for Claude Code and Cursor, where expected (one ctxo skill installed, or the rules block is pre-tier or compact). Formatting is ignored, and a skill from a newer ctxo is not reported.
+- `claude_guard_hook`: an unreadable `.claude/settings.json`, or a missing guard while the `CLAUDE.md` block expects it and the gate is enabled.
+- All three warn, never fail. A versioned full block and `gate.enabled: false` are opt-outs and pass.
+- `ctxo doctor --fix` order: Config, Git hooks, Skills, Claude guard hook, AI rules, then plugins, index and cache. AI rules re-render whenever any of the three checks warned, so the tier follows the fixes. A block is held unchanged by the same rule as init while the guard or the skills it expects are not in place (unreadable settings, failed install); doctor keeps reporting them until fixed. The Skills step reports a skill from a newer ctxo as a warning line and fails on a skill path it cannot write. `--fix` never installs what the user declined, never writes an unreadable `.claude/settings.json`, and replaces edited ctxo skills with the bundled copy (copy a customised skill under another name).
+
+Design record: docs/architecture/ADR/adr-015-safe-edit-guard.md (amendment: tiered rules)

package/llms.txt

@@ -8,27 +8,29 @@ Ctxo is a Model Context Protocol (MCP) server that gives AI agents structured co
 
 ```
 npm install -g @ctxo/cli   # One-time global install (gives you the `ctxo` command)
-ctxo init                  # Detect languages, install plugins, wire MCP
+ctxo init                  # Rules, skills, guard, MCP config, git hooks, plugins
 ctxo index                 # Build codebase index
 ctxo                       # Start MCP server (stdio)
 ```
 
-## Package Layout (v0.7.0-alpha.0, pnpm monorepo)
+## Package Layout (pnpm monorepo)
 
-- `@ctxo/cli` — CLI + MCP server (formerly `ctxo-mcp`)
-- `@ctxo/plugin-api` — `CtxoLanguagePlugin` v1 interface (apiVersion, id, extensions, tier, createAdapter)
-- `@ctxo/lang-typescript` — ts-morph full-tier plugin
-- `@ctxo/lang-go` — tree-sitter / gopls plugin
-- `@ctxo/lang-csharp` — Roslyn plugin
+- `@ctxo/cli` - CLI + MCP server (formerly `ctxo-mcp`)
+- `@ctxo/plugin-api` - `CtxoLanguagePlugin` interface, protocol v1 and v2 (`SUPPORTED_API_VERSIONS = ['1', '2']`; v2 adds data kinds, annotations, facts on request and host capabilities)
+- `@ctxo/lang-typescript` - ts-morph full-tier plugin
+- `@ctxo/lang-go` - tree-sitter / gopls plugin
+- `@ctxo/lang-csharp` - Roslyn plugin (attribute annotations; SQL edges at known call sites when `@ctxo/lang-sql` is installed)
 - `@ctxo/lang-java` - tree-sitter Java plugin (syntax tier built-in; full tier via `@ctxo/lang-java-analyzer` companion, requires JRE 11+)
+- `@ctxo/lang-sql` - T-SQL plugin for `.sql` files (protocol v2): tables, views, procedures, functions and their reads/writes/executes
+- `@ctxo/sql-extract` - zero-dependency T-SQL tokenizer and recognizers (a library, not a plugin; the one dependency plugins may take besides `@ctxo/plugin-api`)
 
 Language adapters ship as separate npm packages and are discovered by scanning the project `package.json` for `@ctxo/lang-*` or `ctxo-lang-*` dependencies.
 
 ## 14 Tools
 
 - get_logic_slice: Symbol + transitive dependencies (L1-L4 detail levels)
-- get_blast_radius: What breaks if a symbol changes (3-tier: confirmed/likely/potential)
-- get_architectural_overlay: Project layer map (Domain/Infrastructure/Adapter)
+- get_blast_radius: What breaks if a symbol changes (3-tier: confirmed/likely/potential; data edges are confirmed)
+- get_architectural_overlay: Project layer map (Domain/Infrastructure/Adapter), Louvain communities, and candidate bounded contexts (mode: "contexts")
 - get_why_context: Git commit intent + anti-pattern warnings (reverts, rollbacks)
 - get_change_intelligence: Complexity x churn composite score
 - find_dead_code: Unreachable symbols and files
@@ -51,6 +53,45 @@ Language adapters ship as separate npm packages and are discovered by scanning t
 - Don't know the symbol name? -> search_symbols or get_ranked_context
 - Finding unused code? -> find_dead_code
 - Safe to delete? -> find_importers
+- Preparing a context map? -> get_architectural_overlay(mode: "contexts")
+
+## New in v0.13
+
+### Tiered agent rules, granular init, agent-setup doctor checks (#159)
+
+- Two rules tiers inside versioned markers (`<!-- ctxo-rules-start v<version> -->` / `<!-- ctxo-rules-end -->`). Claude Code gets a compact block (4 lines in `CLAUDE.md`) when the safe-edit guard hook, all three skills and an enabled gate (`gate.enabled` not false) are in place; every other client, and Claude Code without them, gets the full block. The full block's first rule is narrowed: "For structural questions (dependencies, impact, history), use ctxo tools first; reading a file to see its contents needs no index call."
+- The rules writer replaces the ctxo block in place in every rules file (versioned, unversioned or the old unmarked body), collapses duplicates, keeps everything outside the block (BOM and line endings included), and leaves a block from a newer ctxo or a damaged block (a start or end marker without its partner) unchanged with a warning. `ctxo-understand` carries a question-to-tool table for all 14 tools.
+- Blocks and skills are written in Prettier's layout and compared with formatting ignored (line endings, BOM, trailing whitespace, blank lines, table padding, line wrapping), so a markdown formatter and ctxo never rewrite each other. The compact block is at most 8 non-blank lines including the markers (6 today).
+- A rules file several clients share (an `AGENTS.md` or `GEMINI.md` hard-linked or symlinked to `CLAUDE.md`) gets the full block; init and doctor treat it as one file.
+- Each bundled skill ends with `<!-- ctxo-skill v<version> -->`; a skill from a newer ctxo is left alone and not reported as outdated.
+- No silent opt-out: init (real run, dry run, `--only rules`, `--rules`) and `doctor --fix` leave a pre-tier or compact block unchanged while the guard or skills it expects are missing and not declined, with the warning `<file>: left unchanged until the guard and skills are installed; run "ctxo init --only rules,skills,guard" or "ctxo doctor --fix"`. A file linked to a held one is held too.
+- `ctxo init` parts: `rules`, `skills`, `guard`, `mcp`, `git-hooks`, `config`. New flags `--only <parts>`, `--skip <parts>`, `--no-guard` (does not install the guard); `--rules` is a deprecated alias for `--skip git-hooks,guard`. `-y` without `--tools` sets up all nine tools. `--dry-run` lists every file init would create or change. A corrupt or oddly shaped `.claude/settings.json` is never overwritten.
+- New doctor checks `ai_rules`, `skills` and `claude_guard_hook` (warn only). `ctxo doctor --fix` installs the skills and the guard, then re-renders the rules blocks; it holds a block by the same rule as init, installs nothing the user declined (a versioned full block or `gate.enabled: false`), and replaces edited ctxo skills with the bundled copy.
+
+### Contexts view, plugin protocol v2 and T-SQL data coupling (#156)
+
+- **Contexts view (#156)** - `ctxo index` writes `.ctxo/index/contexts-view.json`: candidate bounded contexts from file-level clustering of dependency and co-change edges, with hub files damped. Each candidate has a suggested label, cohesion, top terms, cross-candidate edges and co-change pairs; type names with different shapes in different candidates are listed as collisions. Recomputed on every index run that re-indexes files (and every post-commit hook run); skipped by `--skip-community`; not refreshed by `ctxo watch`.
+- `get_architectural_overlay` `mode: "contexts"` returns a summary of all candidates (hubs and collisions capped at 50); `candidate: <id>` returns one candidate in full. `mode` (overlay), `searchMode` (get_ranked_context) and `mode` (search_symbols) are now registered, so clients can send them. The unused `fuzzy` parameter is gone (typo correction is automatic in `fts` mode).
+- `ctxo contexts [--json]` - candidates as a table (stderr) or the full artifact (stdout).
+- New config in `.ctxo/config.yaml`: `communities:` (resolution, godNodeMinBridged, godNodeMaxResults), `contextsView:` (weights, exclude, hubs, resolution, minCandidateFiles, technicalTerms) and `index.tests` (extra test globs).
+- **Plugin protocol v2 (#156)** - new symbol kinds `table`, `view`, `procedure` and edge kinds `reads`, `writes`, `executes`; typed symbol `annotations` (`name`, `args`, `named`); code facts on request (`index.facts: true`); host capabilities (`facts`, `sqlCallSites`). The CLI loads plugins declaring `apiVersion` '1' or '2'; a plugin declares the lowest version it works on.
+- **`@ctxo/lang-sql`** - `ctxo install sql` (alias `tsql`). T-SQL definitions become symbols (tables with a `columns` annotation); view, procedure and function bodies give reads/writes/executes edges to canonical `schema.name` targets (default `dbo`). T-SQL only; top-level DML in scripts is skipped. Suggested by detection when the repository has at least 5 `.sql` files that are also at least 2% of its files.
+- **SQL size limit** - a `.sql` file larger than 5 MiB is skipped with one warning (`skipped <file>: <n> MiB is over the 5 MiB SQL size limit`) and gets no symbols or edges, so a data dump cannot crash `ctxo index`.
+- **SQL at C# call sites** - with lang-sql installed and the .NET SDK 8+, constant SQL at ADO.NET, Dapper (including the `CommandDefinition` constructor), `SqlBulkCopy` and EF Core raw SQL call sites becomes data edges (ScriptDom). Use `const string`; `static readonly` SQL is invisible. The C# plugin also reports attribute annotations (10 named entries plus the reserved `type`).
+- **Data coupling** - data edges are `confirmed` blast-radius dependents (the gate guards heavily used tables) and stay out of symbol-level communities; `.sql` symbols are never dead code. The contexts view adds `dataResources` and per-candidate `sharedTables` (ownership, external resources); `contextsView.weights.data` defaults to 0. Overlay summary: `sharedTableCount`, `dataResourcesTotal`, `sharedResourcesTotal`, `externalResourcesTotal`; `candidate: <id>` detail: up to 15 `sharedTables` and 15 `dataResources`, fewer when the response limit requires.
+- **Procedures in the contexts view** - a stored procedure's reads and writes count for the candidates that execute it (by canonical name), not for the candidate holding the script; a procedure nobody executes credits its own candidate. With several copies, the bodies of every production copy count (the winner's alone when no copy is production), and docs and test copies add nothing when a production copy exists. A C# class and a same-name table can show up as a collision (possible noise).
+- **One identity per data resource** - when several files define a table, view or procedure, references resolve to a copy outside test files, then outside docs folders, then the codepoint-smallest path (`index.tests` is not consulted). Every copy, and the 2-part ID (`dbo.loans::table`), gives the same dependents in get_blast_radius, find_importers, get_pr_impact, get_context_for_task, the gate and `ctxo blast-radius`. get_logic_slice walks each copy's own body (the winner's for a 2-part ID); get_why_context with a 2-part ID reads the winner's file history.
+- **Annotations in MCP output** - get_logic_slice includes node `annotations` at L4 only; L1-L3 and get_context_for_task omit them.
+- **Test files by annotation** - `Fact`, `Theory`, `SkippableFact`, `SkippableTheory`, `Test`, `TestCase`, `TestCaseSource`, `TestFixture`, `TestMethod`, `DataTestMethod`, `TestClass` mark test files; name-only `*Test.cs` / `*Tests.cs` matches need one once C# annotations exist. Attributes derived from `Fact` or `Theory` and bare capital `Tests/` folders are not recognised: add `index.tests`. Run a full `ctxo index` after upgrading `@ctxo/lang-csharp`.
+- **`csharp_tier` doctor check** - warns when the Roslyn helper cannot restore its NuGet packages (ScriptDom); the C# plugin then falls back to tree-sitter. The helper declares `RollForward` `Major`, so it can run on a newer .NET runtime when no .NET 8 runtime is installed. `ctxo watch` restarts an idle or crashed Roslyn keep-alive once and falls back to tree-sitter if that fails, instead of writing a C# file with zero symbols.
+
+### Co-change engine, incremental indexing, one snapshot per commit (#157)
+
+- Co-change is built from one `git log` pass with its own window, independent of `--max-history` (which controls per-file intent depth only). Config: `cochange:` in `.ctxo/config.yaml` (maxCommits 2000 or "all", since, maxFilesPerCommit 30, minShared 2, include, exclude). Overrides: `ctxo index --cochange-commits <n|all>`, `--cochange-since <duration>`. Merge commits are excluded; commits above `maxFilesPerCommit` are skipped and counted (`massSkipped`); renames are followed.
+- Every blast-radius path uses co-change: get_blast_radius, get_pr_impact, get_context_for_task, `ctxo blast-radius`, the safe-edit gate hook and `ctxo gate --preview`. `likely` includes co-change-upgraded dependents, `coChangeFrequency` is filled, and get_blast_radius adds `coChangedFiles` (up to 10 files, informational). The gate may fire somewhat more often.
+- Incremental indexing: `ctxo index --files <path...>` (alias `--file`) and `ctxo index --commit <rev>` re-index part of the index and recompute everything global from the merged index. The v2 post-commit hook runs `ctxo index --commit HEAD` once per commit, guarded by `[ -d .ctxo ]`. `ctxo init` and `ctxo doctor --fix` upgrade old hook blocks in place and refuse to write into a global or system `core.hooksPath`. New `git_hooks` doctor check.
+- One community snapshot per commit. Drift and boundary confidence count `distinctCommits` (low below 3, medium 3-6, high 7+). `ctxo index --check` records no snapshot.
+- `ctxo <command> --help` prints help and runs nothing.
 
 ## New in v0.8
 
@@ -70,7 +111,9 @@ Language adapters ship as separate npm packages and are discovered by scanning t
 
 ## Key Concepts
 
-- Symbol ID format: "file::name::kind" (e.g., "src/foo.ts::myFn::function")
+- Symbol ID format: "file::name::kind" (e.g., "src/foo.ts::myFn::function", "db/lending.sql::dbo.loans::table")
+- Symbol kinds: function, class, interface, method, variable, type, table, view, procedure
+- Edge kinds: imports, calls, extends, implements, uses, reads, writes, executes (data edges point at 2-part names such as "dbo.loans::table")
 - All responses include _meta: { totalItems, returnedItems, truncated, totalBytes }
 - 4 tools support intent filtering: get_blast_radius, get_logic_slice, find_importers, find_dead_code
 - Large responses auto-truncated at 8KB (configurable via CTXO_RESPONSE_LIMIT)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxo/cli",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "description": "MCP server delivering dependency-aware, history-enriched context for codebases",
   "type": "module",
   "engines": {
@@ -40,22 +40,24 @@
     "sql.js": "^1.14.1",
     "yaml": "^2.6.1",
     "zod": "^4.6.7",
-    "@ctxo/plugin-api": "0.7.3"
+    "@ctxo/plugin-api": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.1",
     "@types/picomatch": "^4.0.3",
     "@vitest/coverage-v8": "^5.0.1",
     "eslint": "^10.6.0",
+    "prettier": "2.8.8",
     "tsup": "^8.4.0",
     "tsx": "^4.19.4",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.71.1",
     "vitest": "^5.0.1",
-    "@ctxo/lang-csharp": "0.7.5",
-    "@ctxo/lang-go": "0.8.2",
-    "@ctxo/lang-java": "0.9.1",
-    "@ctxo/lang-typescript": "0.7.2"
+    "@ctxo/lang-csharp": "0.9.0",
+    "@ctxo/lang-go": "0.9.1",
+    "@ctxo/lang-java": "0.10.1",
+    "@ctxo/lang-sql": "0.1.0",
+    "@ctxo/lang-typescript": "0.8.1"
   },
   "repository": {
     "type": "git",

package/pages/visualize-template.html

@@ -288,7 +288,10 @@ var EDGE_COLORS = {
   calls:      { color: '#59A14F', opacity: 0.7 },
   extends:    { color: '#B07AA1', opacity: 0.8 },
   implements: { color: '#F28E2B', opacity: 0.8 },
-  uses:       { color: '#BAB0AC', opacity: 0.35 }
+  uses:       { color: '#BAB0AC', opacity: 0.35 },
+  reads:      { color: '#76B7B2', opacity: 0.6 },
+  writes:     { color: '#9C755F', opacity: 0.7 },
+  executes:   { color: '#EDC948', opacity: 0.7 }
 };
 
 // Boundary violations override edge styling. Red for "this edge crosses
@@ -953,7 +956,10 @@ function buildEdgeLegend() {
     { name: 'calls', dashed: false },
     { name: 'extends', dashed: false },
     { name: 'implements', dashed: false },
-    { name: 'uses', dashed: true }
+    { name: 'uses', dashed: true },
+    { name: 'reads', dashed: false },
+    { name: 'writes', dashed: false },
+    { name: 'executes', dashed: false }
   ];
   edgeKinds.forEach(function(ek) {
     var ec = EDGE_COLORS[ek.name];

package/skills/ctxo-review-pr/SKILL.md

@@ -8,3 +8,5 @@ description: Use when reviewing a PR, a diff, or recent changes, to get a full r
 1. `get_pr_impact` - single call: changed symbols + blast radius + co-change risk.
 2. For any high-risk symbol it surfaces, follow up with `get_why_context`.
 3. Summarize risk for the human: what breaks, what needs extra review, what has a bad history.
+
+<!-- ctxo-skill v0.13 -->

package/skills/ctxo-safe-edit/SKILL.md

@@ -13,3 +13,5 @@ Before changing a symbol, in order - do NOT skip:
 4. After editing, re-check the dependents from step 1.
 
 A deterministic guard may block the first edit of a high-impact symbol until you have run get_blast_radius. That is expected - run it, then re-issue the edit.
+
+<!-- ctxo-skill v0.13 -->