trace-mcp 0.1.0 → 1.0.10

package/README.md

@@ -1,6 +1,6 @@
 # trace-mcp
 
-**Framework-aware code intelligence MCP server for Laravel / Vue / Inertia / Nuxt stacks.**
+**Framework-aware code intelligence MCP server — 48+ framework integrations across 68 languages.**
 
 > Your AI agent reads `UserController.php` and sees a class.
 > trace-mcp reads it and sees a route → controller → FormRequest → Eloquent model → Inertia render → Vue page → child components — **in one graph.**
@@ -17,150 +17,210 @@ So they brute-read files, guess at relationships, and miss cross-language edges
 
 ## The solution
 
-trace-mcp builds a **cross-language dependency graph** from your source code — PHP, TypeScript, Vue SFCs, Blade templates — and exposes it through the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-compatible agent (Claude Code, Cursor, Windsurf, etc.) gets framework-level understanding out of the box.
+trace-mcp builds a **cross-language dependency graph** from your source code and exposes it through the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-compatible agent (Claude Code, Cursor, Windsurf, etc.) gets framework-level understanding out of the box.
 
 | Without trace-mcp | With trace-mcp |
 |---|---|
-| Agent reads 15 files to understand a feature | Agent calls `get_feature_context` — gets relevant code in one shot |
-| Agent doesn't know which Vue page a controller renders | Agent sees `routes_to → renders_component → uses_prop` edges |
-| "What breaks if I change this model?" — agent guesses | `get_change_impact` traverses reverse dependencies across PHP + Vue |
-| Schema? Agent needs a running database | Migrations are parsed — schema reconstructed from code |
+| Agent reads 15 files to understand a feature | `get_task_context` — optimal code subgraph in one shot |
+| Agent doesn't know which Vue page a controller renders | `routes_to → renders_component → uses_prop` edges |
+| "What breaks if I change this model?" — agent guesses | `get_change_impact` traverses reverse dependencies across languages |
+| Schema? Agent needs a running database | Migrations parsed — schema reconstructed from code |
 | Prop mismatch between PHP and Vue? Discovered in production | Detected at index time — PHP data vs. `defineProps` |
 
 ---
 
-## What you get
+## Key capabilities
 
-| Capability | How it works |
-|---|---|
-| **Request flow tracing** | URL → Route → Middleware → Controller → FormRequest → Model → Inertia → Vue Page → Props |
-| **Component trees** | Parent → Child render hierarchy with props / emits / slots |
-| **Schema from migrations** | Table structure reconstructed from migration files — no DB connection needed |
-| **Event chains** | Event → Listener → Job fan-out across async boundaries |
-| **Prop mismatch detection** | PHP `Inertia::render()` data vs. Vue `defineProps` — catch type drift before production |
-| **Change impact analysis** | "What breaks if I touch this?" — reverse dependency traversal across languages |
-| **Feature context assembly** | Describe a feature in plain English → get all relevant code within a token budget |
+- **Request flow tracing** — URL → Route → Middleware → Controller → Service, across 18 backend frameworks
+- **Component trees** — render hierarchy with props / emits / slots (Vue, React, Blade)
+- **Schema from migrations** — no DB connection needed
+- **Event chains** — Event → Listener → Job fan-out (Laravel, Django, NestJS, Celery, Socket.io)
+- **Change impact analysis** — reverse dependency traversal across languages
+- **Graph-aware task context** — describe a dev task → get the optimal code subgraph (execution paths, tests, types), adapted to bugfix/feature/refactor intent
+- **CI/PR change impact reports** — automated blast radius, risk scoring, test gap detection, architecture violation checks on every PR
+- **Call graph & DI tree** — bidirectional call graphs, NestJS dependency injection
+- **ORM model context** — relationships, schema, metadata for 7 ORMs
+- **Dead code & test gap detection** — find untested exports, dead code, coverage gaps
+- **Multi-repo federation** — link graphs across separate repos via API contracts; cross-repo impact analysis
+- **AI-powered analysis** — symbol explanation, test suggestions, change review, semantic search (optional)
 
----
+### Supported stack
+
+**Languages (68):** PHP, TypeScript/JavaScript, Python, Go, Java, Kotlin, Ruby, Rust, C, C++, C#, Swift, Objective-C, Dart, Scala, Groovy, Elixir, Erlang, Haskell, Gleam, Bash, Lua, Perl, GDScript, R, Julia, Nix, SQL, HCL/Terraform, Protocol Buffers, Vue SFC, HTML, CSS/SCSS/SASS/LESS, XML/XUL/XSD, YAML, JSON, TOML, Assembly, Fortran, AutoHotkey, Verse, AL, Blade, EJS, Zig, OCaml, Clojure, F#, Elm, CUDA, COBOL, Verilog/SystemVerilog, GLSL, Meson, Vim Script, Common Lisp, Emacs Lisp, Dockerfile, Makefile, CMake, INI, Svelte, Markdown, MATLAB, Lean 4, FORM, Magma, Wolfram/Mathematica
+
+**Frameworks:** Laravel (+ Livewire, Nova, Filament, Pennant), Django (+ DRF), FastAPI, Flask, Express, NestJS, Fastify, Hono, Next.js, Nuxt, Rails, Spring, tRPC
+
+**ORMs:** Eloquent, Prisma, TypeORM, Drizzle, Sequelize, Mongoose, SQLAlchemy
+
+**Frontend:** Vue, React, React Native, Blade, Inertia, shadcn/ui, Nuxt UI, MUI, Ant Design, Headless UI
 
-## Supported frameworks
+**Other:** GraphQL, Socket.io, Celery, Zustand, Pydantic, Zod, n8n, React Query/SWR, Playwright/Cypress/Jest/Vitest/Mocha
 
-| Layer | Frameworks | What's extracted |
-|---|---|---|
-| **Backend** | Laravel 6–13 | Routes, controllers, Eloquent relations, migrations, FormRequests, events/listeners, middleware |
-| **Templates** | Blade | `@extends`, `@include`, `@component`, `<x-*>` directives, template inheritance |
-| **Bridge** | Inertia.js | `Inertia::render()` calls, controller ↔ Vue page mapping, prop extraction & validation |
-| **Frontend** | Vue 2 (Options API), Vue 3 (Composition API) | `defineProps`, `defineEmits`, composables, component render trees |
-| **Meta-framework** | Nuxt 3 | File-based routing, auto-imports, `useFetch` / `useAsyncData`, server API routes |
-| **Languages** | PHP, TypeScript, JavaScript, Vue SFC | Full symbol extraction via tree-sitter |
+> Full details: [Supported frameworks](docs/supported-frameworks.md) · [All tools](docs/tools-reference.md)
 
 ---
 
-## MCP tools
+## Quick start
 
-### Project
+```bash
+npm install -g trace-mcp
+trace-mcp init        # one-time global setup (MCP clients, hooks, CLAUDE.md)
+trace-mcp add         # register current project for indexing
+```
 
-| Tool | What it does |
-|---|---|
-| `get_project_map` | Project overview — detected frameworks, directory structure, entry points |
-| `get_index_health` | Index stats — file count, symbol count, edge count, errors |
-| `reindex` | Trigger full or incremental re-indexing |
+**Step 1: `init`** — one-time global setup. Configures your MCP client (Claude Code, Cursor, Windsurf, or Claude Desktop), installs the guard hook, and adds a tool routing guide to `~/.claude/CLAUDE.md`.
 
-### Navigation
+**Step 2: `add`** — registers a project. Detects frameworks and languages, creates the index database, and adds the project to the global registry. Run this in each project you want trace-mcp to understand.
 
-| Tool | What it does |
-|---|---|
-| `search` | Full-text search (FTS5 + BM25) with kind / language / file pattern filters |
-| `get_symbol` | Look up a symbol by ID or FQN — returns source code |
-| `get_file_outline` | All symbols in a file — signatures only, no bodies |
+All state lives in `~/.trace-mcp/` — nothing is stored in your project directory.
 
-### Framework intelligence
+Start your MCP client and use:
+```
+> get_project_map to see what frameworks are detected
+> get_task_context("fix the login bug") to get full execution context for a task
+> get_change_impact on app/Models/User.php to see what depends on it
+```
 
-| Tool | What it does |
-|---|---|
-| `get_component_tree` | Build Vue/Blade component render tree from a root file |
-| `get_change_impact` | Reverse dependency graph — what depends on this file or symbol |
-| `get_feature_context` | NLP-driven context assembly — describe a feature, get relevant code within a token budget |
+### Adding more projects
 
-### Resources
+```bash
+cd /path/to/another/project
+trace-mcp add
+```
 
-| Resource | URI | Description |
-|---|---|---|
-| Project map | `project://map` | JSON project overview |
-| Index health | `project://health` | Index status |
+Or specify a path directly:
+```bash
+trace-mcp add /path/to/project
+```
 
----
+List all registered projects:
+```bash
+trace-mcp list
+```
 
-## When does it help?
+### Upgrading
 
-| Scenario | Without trace-mcp | With trace-mcp |
-|---|---|---|
-| "Add a new field to the User model" | Agent edits model, misses migration, FormRequest, and Vue form | `get_change_impact` shows all dependents — model, migration, request validation, Vue props |
-| "What components does this page use?" | Agent greps for import statements, misses dynamic components | `get_component_tree` returns full render tree with props/slots |
-| "Refactor the auth flow" | Agent reads files one by one, burns tokens | `get_feature_context("authentication")` assembles relevant code in one call |
-| "Does the Vue page match the controller response?" | Manual comparison, easy to miss fields | Prop mismatch detection flags drift automatically |
-| "What's the DB schema?" | Need a running database or read raw SQL | Migrations parsed — `get_schema` returns reconstructed tables |
+After updating trace-mcp (`npm update -g trace-mcp`), run:
 
----
+```bash
+trace-mcp upgrade
+```
 
-## Quick start
+This runs database migrations and reindexes **all registered projects** with the latest plugins. To upgrade a specific project:
+
+```bash
+trace-mcp upgrade /path/to/project
+```
+
+### Manual setup
 
-### 1. Install
+If you prefer manual control, see [Configuration](docs/configuration.md) for all options. You can skip specific init steps:
 
 ```bash
-npm install -g trace-mcp
+trace-mcp init --skip-hooks --skip-claude-md --skip-mcp-client
 ```
 
-### 2. Add to your MCP client
+### Indexing details
+
+**Automatic:** `trace-mcp serve` starts background indexing immediately and launches a file watcher. The server is ready for tool calls right away — results improve as indexing progresses. If the project isn't registered yet, `serve` auto-registers it.
 
-**Claude Code:**
+**Manual:** index a project without starting the server:
 ```bash
-claude mcp add trace-mcp -- trace-mcp serve
+trace-mcp index /path/to/project          # incremental (skips unchanged files)
+trace-mcp index /path/to/project --force   # full reindex
 ```
 
-**Claude Desktop / Cursor / Windsurf** (MCP config JSON):
-```json
-{
-  "mcpServers": {
-    "trace-mcp": {
-      "command": "trace-mcp",
-      "args": ["serve"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
+Files are content-hashed (MD5). On re-index, unchanged files are skipped. Both `serve` and `serve-http` start a file watcher that debounces rapid changes (300ms) and processes deletions immediately.
+
+### Global directory structure
+
+All trace-mcp state is centralized:
+
 ```
+~/.trace-mcp/
+  .config.json              # global config + per-project settings
+  registry.json             # registered projects
+  topology.db               # cross-service topology + federation graph
+  index/
+    my-app-a1b2c3d4e5f6.db  # per-project databases (named by project + hash)
+```
+
+---
+
+## Getting the most out of trace-mcp
+
+trace-mcp works on three levels to make AI agents use its tools instead of raw file reading:
 
-### 3. Start using it
+### Level 1: Automatic (works out of the box)
 
-The server auto-indexes on first tool call. No configuration needed for standard Laravel + Vue projects.
+The MCP server provides **instructions** and **tool descriptions** with routing hints that tell AI agents when to prefer trace-mcp over native Read/Grep/Glob. This works with any MCP-compatible client — no configuration needed.
 
+### Level 2: CLAUDE.md (recommended)
+
+Add this block to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md` for global use) to reinforce tool routing:
+
+```markdown
+## Code Navigation Policy
+
+Use trace-mcp tools for code intelligence — they understand framework relationships, not just text.
+
+| Task | trace-mcp tool | Instead of |
+|------|---------------|------------|
+| Find a function/class/method | `search` | Grep |
+| Understand a file before editing | `get_outline` | Read (full file) |
+| Read one symbol's source | `get_symbol` | Read (full file) |
+| What breaks if I change X | `get_change_impact` | guessing |
+| All usages of a symbol | `find_usages` | Grep |
+| Starting work on a task | `get_task_context` | reading 15 files |
+| Quick keyword context | `get_feature_context` | reading 15 files |
+| Tests for a symbol | `get_tests_for` | Glob + Grep |
+| HTTP request flow | `get_request_flow` | reading route files |
+| DB model relationships | `get_model_context` | reading model + migrations |
+
+Use Read/Grep/Glob for non-code files (.md, .json, .yaml, config).
+Start sessions with `get_project_map` (summary_only=true).
 ```
-> Use get_project_map to see what frameworks are detected
-> Use get_feature_context to find code related to "user registration"
-> Use get_change_impact on app/Models/User.php to see what depends on it
+
+### Level 3: Hook enforcement (Claude Code only)
+
+For hard enforcement, install the **PreToolUse guard hook** that blocks Read/Grep/Glob on source code files and redirects the agent to trace-mcp tools with specific suggestions. The hook is installed globally by `trace-mcp init`, or manually:
+
+```bash
+trace-mcp setup-hooks --global    # install
+trace-mcp setup-hooks --uninstall # remove
 ```
 
+This copies the guard script to `~/.claude/hooks/` and adds the hook to your Claude Code settings.
+
+**What the hook does:**
+- **Blocks** Read/Grep/Glob/Bash on source code files (`.ts`, `.py`, `.php`, `.go`, `.java`, `.rb`, etc.)
+- **Allows** non-code files (`.md`, `.json`, `.yaml`, `.env`, config)
+- **Allows** Read before Edit — first Read is blocked with a suggestion, retry on the same file is allowed (the agent needs full content for editing)
+- **Allows** safe Bash commands (git, npm, build, test, docker, etc.)
+- **Redirects** with specific trace-mcp tool suggestions in the denial message
+
 ---
 
 ## How it works
 
 ```
-Source files (PHP, TS, Vue, Blade)
+Source files (PHP, TS, Vue, Python, Go, Java, Kotlin, Ruby, HTML, CSS, Blade)
     │
     ▼
 ┌──────────────────────────────────────────┐
 │  Pass 1 — Per-file extraction            │
 │  tree-sitter → symbols                   │
-│  framework plugins → routes, components, │
-│    migrations, events, Eloquent models   │
+│  integration plugins → routes,           │
+│    components, migrations, events,       │
+│    models, schemas, variants, tests      │
 └────────────────────┬─────────────────────┘
                      │
                      ▼
 ┌──────────────────────────────────────────┐
 │  Pass 2 — Cross-file resolution          │
-│  PSR-4 · ES modules · Vue components    │
-│  Inertia bridge · Blade inheritance      │
+│  PSR-4 · ES modules · Python modules    │
+│  Vue components · Inertia bridge         │
+│  Blade inheritance · ORM relations       │
 │  → unified directed edge graph           │
 └────────────────────┬─────────────────────┘
                      │
@@ -168,130 +228,165 @@ Source files (PHP, TS, Vue, Blade)
 ┌──────────────────────────────────────────┐
 │  SQLite (WAL mode) + FTS5               │
 │  nodes · edges · symbols · routes       │
-│  components · migrations                 │
+│  + optional: embeddings · summaries     │
 └────────────────────┬─────────────────────┘
                      │
                      ▼
-              MCP stdio server
-              9 tools · 2 resources
+         MCP server (stdio or HTTP/SSE)
+         44+ tools · 2 resources
 ```
 
 **Incremental by default** — files are content-hashed; unchanged files are skipped on re-index.
 
-**Plugin architecture** — language plugins (symbol extraction) and framework plugins (semantic edges) are loaded based on project detection. Adding a new framework = implementing `FrameworkPlugin` with `detect()`, `extractNodes()`, and `resolveEdges()`.
+**Plugin architecture** — language plugins (symbol extraction) and integration plugins (semantic edges) are loaded based on project detection, organized into categories: framework, ORM, view, API, validation, state, realtime, testing, tooling.
+
+> Details: [Architecture & plugin system](docs/architecture.md)
 
 ---
 
-## Configuration
-
-Optional. Works out of the box for standard Laravel + Vue projects.
-
-Create `.trace-mcp.json` in your project root (or add a `"trace-mcp"` key to `package.json`):
-
-```jsonc
-{
-  "root": ".",
-  "include": [
-    "app/**/*.php",
-    "routes/**/*.php",
-    "resources/**/*.vue",
-    "resources/views/**/*.blade.php",
-    "src/**/*.{ts,js,vue}"
-  ],
-  "exclude": [
-    "vendor/**",
-    "node_modules/**",
-    "storage/**"
-  ],
-  "db": {
-    "path": ".trace-mcp/index.db"
-  },
-  "frameworks": {
-    "laravel": {
-      "artisan": { "enabled": true, "timeout": 10000 },
-      "graceful_degradation": true
-    }
-  },
-  "security": {
-    "max_file_size_bytes": 524288
-  }
-}
-```
+## Documentation
 
-Config is loaded via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) — supports `.trace-mcp.json`, `.trace-mcp.yaml`, `package.json`, and more. All values validated with [Zod](https://zod.dev). Environment variable overrides available.
+| Document | Description |
+|---|---|
+| [Supported frameworks](docs/supported-frameworks.md) | Complete list of languages, frameworks, ORMs, UI libraries, and what each extracts |
+| [Tools reference](docs/tools-reference.md) | All 38 MCP tools with descriptions and usage examples |
+| [Configuration](docs/configuration.md) | Config options, AI setup, environment variables, security settings |
+| [Architecture](docs/architecture.md) | How indexing works, plugin system, project structure, tech stack |
+| [Development](docs/development.md) | Building, testing, contributing, adding new plugins |
 
 ---
 
-## Tech stack
+## Multi-repo federation
 
-| Component | Technology |
-|---|---|
-| Parsing | [tree-sitter](https://tree-sitter.github.io/) (PHP, TypeScript), [@vue/compiler-sfc](https://github.com/vuejs/core) (Vue SFCs) |
-| Database | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) — WAL mode, FTS5 full-text search |
-| Module resolution | [oxc-resolver](https://github.com/nicolo-ribaudo/oxc-resolver) (ESM/CJS), PSR-4 (PHP autoloading) |
-| Validation | [Zod](https://zod.dev) — config + input validation |
-| Error handling | [neverthrow](https://github.com/supermacro/neverthrow) — Rust-style `Result<T, E>` types |
-| MCP | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) |
-| Build | tsup · vitest · TypeScript 5.7 |
+Real projects are not a single repository. trace-mcp can **link dependency graphs across separate repos** — if microservice A calls an API endpoint in microservice B, trace-mcp knows that changing that endpoint in B breaks clients in A.
 
----
+### How it works
 
-## Security
+Federation is **automatic by default**. Every time a project is indexed (`serve`, `serve-http`, or `index`), trace-mcp:
 
-- **Path traversal protection** — all file access validated against project root
-- **Symlink detection** — prevents escape from project boundary
-- **Secret pattern filtering** — configurable regex patterns
-- **File size limits** — per-file byte cap
-- **Artisan whitelist** — only safe artisan commands allowed (when Laravel integration is enabled)
+1. **Registers** the project in the global federation (`~/.trace-mcp/topology.db`)
+2. **Discovers** services (Docker Compose, workspace detection)
+3. **Parses** API contracts — OpenAPI/Swagger, GraphQL SDL, Protobuf/gRPC
+4. **Scans** code for HTTP client calls (fetch, axios, Http::, requests, http.Get, gRPC stubs, GraphQL operations)
+5. **Links** discovered calls to known endpoints from previously indexed repos
+6. **Creates** cross-repo dependency edges
 
----
+### Example
 
-## Development
+```bash
+# Index two separate repos
+cd ~/projects/user-service && trace-mcp add
+cd ~/projects/order-service && trace-mcp add
+
+# order-service has: axios.get('/api/users/{id}')
+# user-service has: openapi.yaml with GET /api/users/{id}
+# → trace-mcp automatically links them
+
+# Check cross-repo impact
+trace-mcp federation impact --endpoint=/api/users
+# → "GET /api/users/{id} is called by 2 client(s) in 1 repo(s)"
+#   [order-service] src/services/user-client.ts:42 (axios, confidence: 85%)
+```
+
+### Federation CLI
 
 ```bash
-git clone https://github.com/nickvysotskyi/trace-mcp.git
-cd trace-mcp
-npm install
-npm run build
-npm test            # 286 tests
-npm run dev         # watch mode (tsup)
-npm run serve       # start MCP server (dev)
+trace-mcp federation add --repo=../service-b [--contract=openapi.yaml]
+trace-mcp federation remove <name-or-path>
+trace-mcp federation list [--json]
+trace-mcp federation sync           # re-scan all repos
+trace-mcp federation impact --endpoint=/api/users [--method=GET] [--service=user-svc]
 ```
 
-### Project structure
+### MCP tools
 
+| Tool | What it does |
+|---|---|
+| `get_federation_graph` | All federated repos, their connections, and stats |
+| `get_federation_impact` | Cross-repo impact: what breaks if endpoint X changes (resolves to symbol level) |
+| `get_federation_clients` | Find all client calls across repos that call a specific endpoint |
+| `federation_add_repo` | Add a repo to the federation via MCP |
+| `federation_sync` | Re-scan all federated repos |
+
+> Federation builds on top of the topology system. See [Configuration](docs/configuration.md#topology--federation) for options.
+
+---
+
+## CI/PR change impact reports
+
+trace-mcp can generate automated change impact reports for pull requests — blast radius, risk scoring, test coverage gaps, architecture violations, and dead code detection.
+
+### CLI usage
+
+```bash
+# Generate a markdown report for changes between main and HEAD
+trace-mcp ci-report --base main --head HEAD
+
+# Output to file
+trace-mcp ci-report --base main --head HEAD --format markdown --output report.md
+
+# JSON output
+trace-mcp ci-report --base main --head HEAD --format json
+
+# Fail CI if risk level >= high
+trace-mcp ci-report --base main --head HEAD --fail-on high
+
+# Index before generating (for CI environments without pre-built index)
+trace-mcp ci-report --base main --head HEAD --index
 ```
-src/
-├── db/                     # SQLite schema, store, FTS5
-├── indexer/
-│   ├── plugins/
-│   │   ├── language/       # PHP, TypeScript, Vue parsers
-│   │   └── framework/      # Laravel, Vue, Inertia, Nuxt, Blade
-│   ├── resolvers/          # PSR-4, ES module resolution
-│   └── pipeline.ts         # Two-pass indexing engine
-├── tools/                  # MCP tool implementations
-├── scoring/                # PageRank, BM25, hybrid scoring
-├── plugin-api/             # Plugin registry + executor
-├── server.ts               # MCP server setup
-├── config.ts               # Cosmiconfig + Zod
-└── cli.ts                  # Commander CLI
+
+### GitHub Action
+
+Add this workflow to get automatic impact reports on every PR:
+
+```yaml
+# .github/workflows/ci.yml (impact-report job runs after build-and-test)
+- name: Index project
+  run: node dist/cli.js index . --force
+
+- name: Generate impact report
+  run: |
+    node dist/cli.js ci-report \
+      --base ${{ github.event.pull_request.base.sha }} \
+      --head ${{ github.event.pull_request.head.sha }} \
+      --format markdown \
+      --output report.md
+
+- name: Post PR comment
+  uses: marocchino/sticky-pull-request-comment@v2
+  with:
+    path: report.md
 ```
 
+The full workflow is in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — it runs `build → test → impact-report` on every PR.
+
+### Report sections
+
+| Section | What it shows |
+|---|---|
+| **Summary** | Changed files, affected files count, risk level, gap counts |
+| **Blast Radius** | Files transitively affected by changes (depth-2 reverse dependency traversal) |
+| **Test Coverage Gaps** | Affected symbols with no matching test file |
+| **Risk Analysis** | Per-file composite score: 30% complexity + 25% churn + 25% coupling + 20% blast radius |
+| **Architecture Violations** | Layer rule violations involving changed files (auto-detects clean architecture / hexagonal presets) |
+| **Dead Code** | New exports in changed files that nothing imports |
+
 ---
 
 ## Best for
 
-- Laravel + Vue / Inertia / Nuxt full-stack projects
+- **Full-stack projects** in any supported framework combination
 - Teams using AI agents (Claude, Cursor, Windsurf) for day-to-day development
-- Projects where PHP ↔ JavaScript boundaries create blind spots
-- CI/CD environments where a running database isn't available
+- **Multi-language codebases** where PHP ↔ JavaScript ↔ Python boundaries create blind spots
+- **Monorepos** with multiple services and shared libraries
+- **Microservice architectures** where API changes ripple across repos
 - Large codebases where agents waste tokens re-reading files
 
 ---
 
 ## License
 
-[Elastic License 2.0](LICENSE) — free for personal and internal use. See LICENSE for full terms.
+[Elastic License 2.0 + Ethical Use Addendum](LICENSE) — free for personal and internal use. See LICENSE for full terms.
 
 ---