@ctxo/cli 0.12.0 → 0.13.0

package/README.md

@@ -20,7 +20,7 @@ ctxo index
   <img src="https://img.shields.io/badge/Get%20Started-%E2%86%92-06b6d4?style=for-the-badge&labelColor=0f172a" alt="Get Started →">
 </a>
 
-<sub>Detects your languages, installs the right plugins, wires Ctxo into your AI client, installs git hooks, and builds the first index  one command.</sub>
+<sub>Detects your languages, installs the right plugins, wires Ctxo into your AI client, installs git hooks, and builds the first index, all in one command.</sub>
 
 </div>
 
@@ -28,7 +28,7 @@ ctxo index
 
 ## The Problem: agents code blind
 
-Drop a modern coding agent into a real repo. It ripgreps a symbol, gets 47 hits, reads five files to find the definition, five more for callers  **misses the subclass entirely** (inheritance doesn't show up in text search), **never checks git history** (and confidently reintroduces a bug that was reverted three weeks ago), then runs out of context and starts hallucinating.
+Drop a modern coding agent into a real repo. It ripgreps a symbol, gets 47 hits, reads five files to find the definition, five more for callers, **misses the subclass entirely** (inheritance doesn't show up in text search), **never checks git history** (and confidently reintroduces a bug that was reverted three weeks ago), then runs out of context and starts hallucinating.
 
 It's not a skill gap. It's a **sensory gap**. The agent is navigating your codebase with its eyes closed and a phone book.
 
@@ -36,11 +36,11 @@ It's not a skill gap. It's a **sensory gap**. The agent is navigating your codeb
 
 The core shift: your agent stops reacting to files it stumbles into and starts planning from a complete map. **Blast radius before the edit. Git intent before the bug fix. Importer list before the rename.**
 
-Ctxo indexes your repo once kept fresh by file watchers and git hooks into a deterministic graph: every symbol, every edge (imports, calls, extends, implements), every relevant git commit with intent classified, every anti-pattern. All exposed through 14 semantic MCP tools.
+Ctxo indexes your repo once, kept fresh by file watchers and git hooks, into a deterministic graph: every symbol, every edge (imports, calls, extends, implements, uses, and the data edges reads, writes and executes), every relevant git commit with intent classified, every anti-pattern. All exposed through 14 semantic MCP tools.
 
 One `get_blast_radius` call replaces an entire ripgrep/read spiral. One `get_pr_impact` replaces a full review session of "wait, what calls this?"
 
-The agent still writes the code. It just stops writing it **blind** so the bug never has to be caught by the compiler, the tests, CI, or a user.
+The agent still writes the code. It just stops writing it **blind**, so the bug never has to be caught by the compiler, the tests, CI, or a user.
 
 ## Codebase Dashboard
 
@@ -71,6 +71,26 @@ The safe-edit guard closes this loop deterministically. When you run `ctxo init`
 
 If an agent tries to edit a high-impact symbol without first calling `get_blast_radius`, the hook blocks the edit and tells the agent what to check. Once the agent runs the tool, the edit goes through normally. Fires once per symbol per session, fail-open on any uncertainty.
 
+With the hook and the skills doing the work, the always-loaded `CLAUDE.md` block shrinks to four lines:
+
+```markdown
+## ctxo
+
+This repo has a ctxo index: dependency graph, git intent, change health. For structural questions (who depends on X, what breaks if X changes, why X looks like this), use the ctxo MCP tools before grepping.
+A pre-edit guard blocks the first edit to a high-impact symbol until `get_blast_radius` has been called for it.
+Skills: `ctxo-understand` (orient at task start), `ctxo-safe-edit` (before changing a symbol), `ctxo-review-pr` (before reviewing a diff).
+```
+
+Every other client, Claude Code without the guard, and a `CLAUDE.md` that another client reads too (an `AGENTS.md` linked to it) get the full tool guide. Re-running `ctxo init` replaces the block in place and keeps the rest of your file. The blocks and skills are written in Prettier's layout and compared with formatting ignored, so a markdown formatter and ctxo never rewrite each other. `ctxo doctor` warns when the block, the skills or the hook drift, and `ctxo doctor --fix` repairs them.
+
+**Pick the parts:**
+
+```shell
+ctxo init --only rules,skills,guard   # add the guard and the skills; the rules block follows
+ctxo init --skip git-hooks            # everything except the git hooks
+ctxo init --no-guard                  # does not install the guard (CLAUDE.md gets the full block unless a guard is already registered)
+```
+
 **Tune it:**
 
 ```shell
@@ -97,6 +117,30 @@ gate:
 | Cursor | no (no blocking pre-edit hook) | yes | yes |
 | Other | no | where supported | yes |
 
+## Fresh on every commit
+
+A stale index is worse than none: the agent trusts a map that no longer matches the code. `ctxo init` installs a post-commit hook that runs `ctxo index --commit HEAD` once per commit. It re-indexes only the files that commit changed, refreshes the co-change matrix from git history, and records one snapshot per commit for the drift and boundary signals.
+
+```shell
+ctxo index --commit HEAD                                 # what the hook runs
+ctxo index --files src/a.ts src/b.ts                     # re-index a few files
+ctxo index --cochange-commits 500 --cochange-since 12m   # co-change window (or `cochange:` in config.yaml)
+ctxo doctor --fix                                        # upgrades an old hook block in place
+```
+
+The file you forget to touch is usually the one no import points at. Files that keep changing together are coupled anyway: `get_blast_radius` promotes a dependent that co-changes with your target from `potential` to `likely`, and lists the files with no dependency path at all as `coChangedFiles`. `ctxo index --max-history` only controls how many commits each file keeps for `get_why_context`; the co-change window has its own settings.
+
+## Where the boundaries really are
+
+Folder names say one thing; imports and commit history often say another. `ctxo index` also writes candidate bounded contexts: files clustered by dependency and co-change edges, with hub files damped, each with a suggested label, a cohesion score, top terms and the edges that cross into other candidates. With `@ctxo/lang-sql` installed, tables, views and procedures join the graph: a table's readers and writers show up in its blast radius, and each candidate lists the tables it shares with other candidates.
+
+```shell
+ctxo contexts          # candidates as a table
+ctxo contexts --json   # the full contexts-view.json
+```
+
+Agents get the same view from `get_architectural_overlay(mode: "contexts")`, and one candidate in full with `candidate: <id>`.
+
 ## Supported Languages
 
 | Language | Plugin | Tier | Notes |
@@ -105,11 +149,13 @@ gate:
 | Go | `@ctxo/lang-go` | syntax | tree-sitter; exported-symbol analysis |
 | C# | `@ctxo/lang-csharp` | full | Roslyn; .NET SDK 8+ for full tier, tree-sitter fallback |
 | Java | `@ctxo/lang-java` | syntax / full | tree-sitter syntax tier built-in; full tier via `@ctxo/lang-java-analyzer` companion (JRE 11+ required, covers Java 8-21); detected by `pom.xml` / `build.gradle` |
+| SQL (T-SQL) | `@ctxo/lang-sql` | syntax | `.sql` tables, views, procedures and functions with `reads` / `writes` / `executes` edges; no database or .NET needed. With it installed, the C# plugin's Roslyn tier also links constant SQL at ADO.NET, Dapper, `SqlBulkCopy` and EF Core call sites to the same tables |
 
 Install via the CLI shortcut:
 
 ```bash
 ctxo install typescript go csharp   # syntax or full tier auto-detected
+ctxo install sql                    # T-SQL plugin (alias tsql)
 ctxo install java                   # installs syntax tier; adds full-tier analyzer when JRE 11+ detected
 ctxo install java --full-tier       # force full-tier analyzer install
 ctxo install java --syntax-only     # skip analyzer, syntax tier only
@@ -117,7 +163,7 @@ ctxo install java --syntax-only     # skip analyzer, syntax tier only
 
 ## Links
 
-* [Docs](https://alperhankendi.github.io/Ctxo/docs/)  quick start, MCP tools, CLI reference, integrations
+* [Docs](https://alperhankendi.github.io/Ctxo/docs/): quick start, MCP tools, CLI reference, integrations
 * [npm](https://www.npmjs.com/package/@ctxo/cli)
 * [Changelog](CHANGELOG.md)
 * [LLM Reference](llms-full.txt)