codebeacon 0.6.9__tar.gz → 0.7.0__tar.gz

{codebeacon-0.6.9 → codebeacon-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.6.9
+Version: 0.7.0
 Summary: Source code AST analysis tool for AI context generation — unified multi-framework knowledge graph
 Project-URL: Homepage, https://github.com/codebeacon/codebeacon
 Project-URL: Repository, https://github.com/codebeacon/codebeacon
@@ -49,6 +49,7 @@ Requires-Dist: tree-sitter-ruby<0.24,>=0.23; extra == 'dev'
 Requires-Dist: tree-sitter-rust<0.25,>=0.23; extra == 'dev'
 Requires-Dist: tree-sitter-svelte<1.1,>=0.23; extra == 'dev'
 Requires-Dist: tree-sitter-swift<0.8,>=0.0.1; extra == 'dev'
+Requires-Dist: watchdog<8,>=4; extra == 'dev'
 Provides-Extra: dotnet
 Requires-Dist: tree-sitter-c-sharp<0.24,>=0.23; extra == 'dotnet'
 Provides-Extra: full
@@ -62,6 +63,7 @@ Requires-Dist: tree-sitter-ruby<0.24,>=0.23; extra == 'full'
 Requires-Dist: tree-sitter-rust<0.25,>=0.23; extra == 'full'
 Requires-Dist: tree-sitter-svelte<1.1,>=0.23; extra == 'full'
 Requires-Dist: tree-sitter-swift<0.8,>=0.0.1; extra == 'full'
+Requires-Dist: watchdog<8,>=4; extra == 'full'
 Provides-Extra: go
 Requires-Dist: tree-sitter-go<0.26,>=0.23; extra == 'go'
 Provides-Extra: html
@@ -86,6 +88,8 @@ Provides-Extra: svelte
 Requires-Dist: tree-sitter-svelte<1.1,>=0.23; extra == 'svelte'
 Provides-Extra: swift
 Requires-Dist: tree-sitter-swift<0.8,>=0.0.1; extra == 'swift'
+Provides-Extra: watch
+Requires-Dist: watchdog<8,>=4; extra == 'watch'
 Provides-Extra: web
 Requires-Dist: tree-sitter-html<0.24,>=0.23; extra == 'web'
 Requires-Dist: tree-sitter-svelte<1.1,>=0.23; extra == 'web'
@@ -118,6 +122,21 @@ Description-Content-Type: text/markdown
 
 ---
 
+## What's new in 0.7.0
+
+A capability release rather than a bug sweep: codebeacon grows a live file-watcher, links your design notes into the code graph, ships two new front-ends (an npm launcher for the MCP server and a GitHub Action), and tightens what it indexes by default. Every feature stays local-first — the core scan still needs no network, no cloud, and no model.
+
+- **`codebeacon watch` keeps the index live** — a debounced file-watcher (`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`) re-syncs the graph whenever watched source files change. A burst of edits — a 500-file `git checkout`, a branch switch — coalesces into a single resync, and the watcher reuses the scanner's exact ignore rules so writing the index never wakes it into a loop over its own `.codebeacon/` output. Needs the new optional extra: `pip install 'codebeacon[watch]'` (watchdog).
+- **Design notes link into the code graph** — `codebeacon knowledge` now writes its notes (ADRs, meeting notes, retros, specs) *into* `beacon.json` when an index already exists: an explicit file-path reference becomes a trusted `references` edge, and a distinctive symbol mention (`PaymentService`, never a bare `User`) becomes an `AMBIGUOUS` `mentions` edge — so an agent reading the graph learns *why* a service is shaped the way it is. Because `codebeacon scan` rebuilds the code graph from source alone and drops this overlay, **re-run `codebeacon knowledge` after a scan** to restore the links.
+- **`beacon_knowledge` MCP tool** — a new tool searches notes by keyword and/or lists the notes linked to a given code node, exposing the decision trail behind the code directly over MCP.
+- **npm launcher for the MCP server** — `@codebeacon/mcp` lets MCP clients start the server the npx-first way they expect (`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). The zero-dependency Node shim resolves a working codebeacon via PATH → `uvx` → `pipx run` → `python3 -m codebeacon` and forwards stdio untouched. See [`npm/README.md`](npm/README.md). (Ships with 0.7.0; not yet published to npm.)
+- **GitHub Action for PR context** — a composite action comments on every pull request with the affected slice of your committed knowledge graph: the wiki articles the change touches, the upstream blast radius, and any high-impact hub files it edits — an architecture-drift check for AI-era review. Requires a committed `.codebeacon/` index, `fetch-depth: 0`, and `permissions: pull-requests: write`. See [`action/README.md`](action/README.md) and [`action/examples/pr-context.yml`](action/examples/pr-context.yml).
+- **Workspace CLAUDE.md stays under ~200 lines** — in a multi-project workspace the root `CLAUDE.md` now keeps only the shared overview and moves per-project detail into scoped `.claude/rules/codebeacon-<project>.md` files whose `paths:` frontmatter loads them only when that project's files are touched (following Anthropic's own guidance for context files). Single-project output is unchanged; set `output.context_map.rules_split: false` for the old monolithic file. Duplicate project rows are also collapsed.
+- **Test fixtures are ignored by default** — `tests/fixtures/`, `test/fixtures/`, and `__fixtures__/` at any depth are now default-ignored, so a project's synthetic test inputs stop injecting fake routes and services into the graph (codebeacon's own self-scan had reported a fixture `main.py` as five "routes"). It is the lowest-precedence rule, so a `.codebeaconignore` line `!tests/fixtures/` re-includes them, and pointing a scan *at* a fixture directory still collects it.
+- **Warp route extraction is real now** — Warp's filter-combinator routes are actually extracted: `warp::path!(...)` and `warp::path("x")` segments, method combinators (`warp::get()` / `post()` / …), and `.map` / `.and_then` handlers are correlated by their enclosing binding into whole routes. Honest limits (spelled out in the query header): filters joined by `.or(...)` inside one binding collapse into a single concatenated route, and `warp::path::param()` filter-call segments and closure handlers are left unresolved.
+
+---
+
 ## What's new in 0.6.9
 
 The largest audit release to date: a dual upstream-parity sweep (the first-ever full audit of codesight's tracker, plus graphify v0.9.4–v0.9.12 / issues through #1776) combined with an independent multi-agent bug hunt over codebeacon itself. Every candidate was reproduced before fixing, every fix was mutation-tested, and an adversarial second review then attacked the fixes themselves — catching 18 further holes before release. **48 real bugs fixed.**
@@ -282,7 +301,8 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 - **Deep-dive mode** — `--deep-dive` generates per-project `.codebeacon/` + `CLAUDE.md` for every sub-project; running `codebeacon scan . --update` from any sub-project folder automatically syncs all projects in the workspace
 - **Workspace auto-rediscovery** — on every `scan` / `sync`, codebeacon re-scans the workspace and appends any new project folders to `codebeacon.yaml` before extraction, so freshly added sub-projects are never silently skipped; pass `--no-rediscover` to opt out for hand-curated configs
 - **Graphify-style semantic enrichment** — after AST extraction, the skill dispatches one parallel subagent per chunk to emit `{nodes, edges, hyperedges}` with 8 relation types (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) and EXTRACTED/INFERRED/AMBIGUOUS confidence; on Claude Code the subagent runs one tier below the host model (Opus→Sonnet, Sonnet→Haiku) so spend stays proportional to corpus size. AST owns code nodes; LLM only contributes `concept`/`document`/`paper` nodes. Existing 0.3.x archives replay through the new schema unchanged.
-- **Knowledge mode (`codebeacon knowledge`)** — scan markdown notes (ADRs, meeting notes, retros, specs, research) and produce a single `KNOWLEDGE.md` next to `.codebeacon/`. Auto-classifies by filename and heading patterns, parses Obsidian YAML frontmatter and `[[backlinks]]`, surfaces a top-level "Key Decisions" + "Open Questions" rollup so an agent learns *why* the codebase looks the way it does. Pure heuristics — no LLM call.
+- **Knowledge mode (`codebeacon knowledge`)** — scan markdown notes (ADRs, meeting notes, retros, specs, research) and produce a single `KNOWLEDGE.md` next to `.codebeacon/`. Auto-classifies by filename and heading patterns, parses Obsidian YAML frontmatter and `[[backlinks]]`, surfaces a top-level "Key Decisions" + "Open Questions" rollup so an agent learns *why* the codebase looks the way it does. Pure heuristics — no LLM call. When a `beacon.json` already exists, the notes are also **linked into the graph**: explicit file-path references become trusted `references` edges and distinctive symbol mentions become `AMBIGUOUS` `mentions` edges. This overlay is dropped by the next `codebeacon scan` (which rebuilds the code graph from source alone), so re-run `codebeacon knowledge` after a scan to restore it.
+- **Watch mode (`codebeacon watch`)** — a debounced file-watcher re-syncs the index whenever watched source files change, coalescing a burst of edits (a 500-file `git checkout`) into a single resync and reusing the scanner's exact ignore rules so it never loops on its own `.codebeacon/` output. Optional extra: `pip install 'codebeacon[watch]'`.
 - **Bare-path shortcut** — `codebeacon ./src` is now equivalent to `codebeacon scan ./src`; when the first argument isn't a registered subcommand, `scan` is auto-injected, so muscle memory from `graphify <path>` / `codesight <path>` works here too.
 - **Hardened semantic pipeline** — `semantic-apply` guards against malformed agent JSONL (null/list/code-fence lines, missing fields), coerces broken `confidence_score` values (None/NaN/string/out-of-range) to a safe default, snapshots `beacon.json` → `beacon.json.bak` before merging so the AST baseline is always recoverable, and regenerates `beacon.html` + `callflow.html` so visual exports reflect the newly-inferred edges.
 - **Sensitive file/dir guard** — `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` directories are always skipped; filenames matching credential patterns (`api_token`, `oauth_token`, `private_key`, `client_secret`; underscore *and* hyphen variants) are excluded from the source-file collector before they reach extractors.
@@ -323,6 +343,18 @@ codebeacon sync                      # subsequent runs via config
 | Swift | Vapor |
 | ArkTS | `.ets` (HarmonyOS) collected — extractors framework-agnostic |
 
+> **How the "27 frameworks" count works.** Coverage is grounded in tree-sitter
+> queries, and frameworks in the same grammar family share query files — Rocket
+> reuses Actix-Web's attribute-macro pattern, the JS/TS web frameworks share the
+> class/decorator queries, and so on. That sharing is what makes broad coverage
+> tractable, but it also means depth varies per framework: some are exercised by
+> extensive fixtures, others by a single query pattern. Where a framework has
+> known limits, they're documented at the source — e.g. Warp's `.or(...)` and
+> `warp::path::param()` caveats live in the query header
+> ([`codebeacon/extract/queries/actix.scm`](codebeacon/extract/queries/actix.scm)).
+> If a specific framework matters to you, scan a representative repo and check
+> the routes/services it actually extracts before relying on the number.
+
 ---
 
 ## Architecture
@@ -513,6 +545,71 @@ codebeacon scan .
 | `beacon_blast_radius` | Upstream callers + downstream affected nodes |
 | `beacon_routes` | List all HTTP routes, filterable by project |
 | `beacon_services` | List all services/classes, filterable by project |
+| `beacon_knowledge` | Search knowledge notes (ADRs, meetings, retros, specs) or list the notes linked to a code node — the *why* behind the code |
+| `beacon_pr_context` | Given changed files (or a `base` ref), return the wiki articles in their blast radius — read the docs that matter before a PR review |
+
+### npm launcher (`@codebeacon/mcp`)
+
+MCP clients that prefer to launch servers with `npx` can use the thin Node
+wrapper instead of pointing at the `codebeacon` binary directly:
+
+```json
+{
+  "mcpServers": {
+    "codebeacon": {
+      "command": "npx",
+      "args": ["-y", "@codebeacon/mcp", "--dir", "/path/to/your/repo/.codebeacon"]
+    }
+  }
+}
+```
+
+The wrapper bundles no Python — it resolves an installed codebeacon on the host
+(PATH → `uvx` → `pipx run` → `python3 -m codebeacon`) and forwards stdio to
+`codebeacon serve` untouched. See [`npm/README.md`](npm/README.md) for the full
+per-client config snippets. (Shipping with 0.7.0; not yet published to npm.)
+
+---
+
+## GitHub Action — PR context
+
+Comment on every pull request with the affected slice of your committed
+knowledge graph — the wiki articles the change touches, the upstream blast
+radius, and any high-impact hub files it edits. It reframes review around
+**architecture drift**: instead of reading a diff in isolation, the comment
+points at the parts of the system that actually move.
+
+```yaml
+# .github/workflows/pr-context.yml
+name: codebeacon PR context
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write        # required to post/update the comment
+jobs:
+  pr-context:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0       # required — full history so the base is diffable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: codebeacon/codebeacon/action@v1
+        with:
+          base: ${{ github.base_ref }}
+```
+
+The Action does **not** scan on the runner — it reads the `.codebeacon/` index
+you commit to the repo (codebeacon's model is that the graph is a
+git-committable artifact). If the index is missing it posts one-time setup
+guidance instead of failing the build, and it updates a single marked comment in
+place rather than stacking duplicates. See [`action/README.md`](action/README.md)
+and [`action/examples/pr-context.yml`](action/examples/pr-context.yml) for inputs
+and edge-case behaviour.
 
 ---
 
@@ -521,6 +618,7 @@ codebeacon scan .
 ```bash
 pip install codebeacon              # all language grammars included
 pip install codebeacon[cluster]     # + Leiden community detection (graspologic)
+pip install codebeacon[watch]       # + live file-watcher for `codebeacon watch` (watchdog)
 pip install --upgrade codebeacon    # upgrade to latest version with all dependencies
 ```
 
@@ -552,6 +650,12 @@ codebeacon sync --config <file>           # use a specific config file
 codebeacon sync --no-rediscover           # don't auto-append newly added projects (hand-curated yaml mode)
 codebeacon sync --exclude PATTERN         # same flag, same semantics
 
+# Watch mode — keep the index live as you edit (needs the `watch` extra)
+codebeacon watch [path]                    # re-sync on file changes (default path: cwd)
+codebeacon watch . --debounce 2.0          # quiet-window before a resync fires; coalesces bursts
+codebeacon watch . --once                  # process one debounce cycle then exit
+codebeacon watch . --exclude 'docs/**'     # extra gitignore-style pattern (repeatable)
+
 # PR / CI: what does this diff actually break?
 codebeacon affected --base main           # walk upstream callers of every changed file
 codebeacon affected --base origin/main --head HEAD --depth 4 --limit 200
@@ -712,6 +816,11 @@ output:
   obsidian: true
   context_map:
     targets: [CLAUDE.md, .cursorrules, AGENTS.md]
+    rules_split: true          # multi-project workspaces: keep CLAUDE.md under
+                               # ~200 lines and move per-project detail into
+                               # scoped .claude/rules/codebeacon-<project>.md
+                               # files. Set false for the old monolithic CLAUDE.md.
+                               # No effect on single-project scans.
 
 wave:
   auto: true
@@ -751,6 +860,8 @@ fixtures/
 
 `!pattern` re-includes a previously-ignored path; later rules override earlier ones. The walker prunes directories whose name matches the rule set, but defers pruning when any negation rule could un-ignore a nested file.
 
+**Default fixture exclusion.** `tests/fixtures/`, `test/fixtures/`, and `__fixtures__/` are ignored by default at any depth — test-fixture trees are synthetic inputs for a project's *own* test suite, not product surface, and indexing them injects fake routes and services. This is the lowest-precedence rule, so a `.codebeaconignore` line `!tests/fixtures/` re-includes them, and pointing a scan directly *at* a fixture directory still collects it.
+
 ---
 
 ## How It Compares
@@ -793,6 +904,50 @@ All AST processing is local. Your source code never leaves your machine when you
 
 ---
 
+## Air-Gapped & Compliance-Friendly
+
+codebeacon's core pipeline — tree-sitter AST parsing → knowledge graph → wiki
+and context map — runs **entirely on your machine**. It requires:
+
+- **No network.** The scan makes no outbound calls; nothing about your source
+  code leaves the host.
+- **No cloud service.** There is no backend, no account, no telemetry.
+- **No LLM — not even a local one.** The graph, wiki, `beacon.json`, and
+  `CLAUDE.md` are all produced by deterministic AST analysis. (The optional
+  AI-semantic layer is a *separate*, opt-in step owned by the `/codebeacon`
+  agent — it never runs unless you invoke it; see
+  [Privacy & Security](#privacy--security) — and the CLI ships no API client,
+  key handling, or model name.)
+
+That architecture makes codebeacon suitable for **air-gapped and tightly
+regulated environments** — healthcare, defense, legal, finance — where source
+code cannot touch third-party services. To be precise about what that does and
+does not mean: codebeacon makes **no compliance certification claims** (no
+HIPAA, FedRAMP, CMMC, SOC 2, or similar). What it offers is an architecture that
+keeps code on-premises, so it can *fit* within environments governed by those
+policies. Verifying that codebeacon meets the specific controls of your
+environment remains your responsibility.
+
+**Offline install.** Because it is a normal Python package with vendored
+grammars, codebeacon installs without internet access on the target host:
+download the wheel and its dependencies on a connected machine, transfer them
+across the air gap, and install from the local files.
+
+```bash
+# On a connected machine (include the grammar extras you need — [full] grabs all):
+pip download 'codebeacon[full]' -d ./codebeacon-offline
+
+# Transfer ./codebeacon-offline across the air gap, then on the target host:
+pip install --no-index --find-links ./codebeacon-offline 'codebeacon[full]'
+```
+
+The base install bundles Python + JavaScript/TypeScript grammars; other
+languages are ordinary wheels pulled in by extras (`[jvm]`, `[backend]`,
+`[full]`, …), so include the extras you need in the download and nothing is
+fetched at runtime.
+
+---
+
 ## Contributing
 
 ```bash

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.de.md

@@ -27,6 +27,21 @@
 
 ---
 
+## Neu in 0.7.0
+
+Eine Fähigkeits-Release statt eines Bug-Sweeps: codebeacon bekommt einen Live-File-Watcher, verknüpft deine Design-Notizen mit dem Code-Graphen, liefert zwei neue Front-Ends (einen npm-Launcher für den MCP-Server und eine GitHub Action) und schärft, was es standardmäßig indexiert. Jede Funktion bleibt local-first — der Kern-Scan braucht weiterhin kein Netzwerk, keine Cloud und kein Modell.
+
+- **`codebeacon watch` hält den Index live** — ein entprellter File-Watcher (`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`) resynchronisiert den Graphen, sobald überwachte Quelldateien sich ändern. Ein Schwall von Edits — ein `git checkout` über 500 Dateien, ein Branch-Wechsel — verschmilzt zu einer einzigen Resynchronisierung, und der Watcher verwendet exakt dieselben Ignore-Regeln wie der Scanner wieder, sodass das Schreiben des Index ihn nie in eine Schleife über seine eigene `.codebeacon/`-Ausgabe weckt. Benötigt das neue optionale Extra: `pip install 'codebeacon[watch]'` (watchdog).
+- **Design-Notizen verknüpfen sich mit dem Code-Graphen** — `codebeacon knowledge` schreibt seine Notizen (ADRs, Meeting-Notizen, Retros, Specs) jetzt *in* `beacon.json`, wenn bereits ein Index existiert: eine explizite Dateipfad-Referenz wird zu einer vertrauenswürdigen `references`-Kante, und eine markante Symbol-Erwähnung (`PaymentService`, niemals ein bloßes `User`) wird zu einer `AMBIGUOUS`-`mentions`-Kante — sodass ein Agent, der den Graphen liest, erfährt, *warum* ein service so geformt ist, wie er ist. Da `codebeacon scan` den Code-Graphen allein aus dem Quellcode neu aufbaut und dieses Overlay verwirft, **führe `codebeacon knowledge` nach einem Scan erneut aus**, um die Verknüpfungen wiederherzustellen.
+- **MCP-Tool `beacon_knowledge`** — ein neues Tool durchsucht Notizen nach Schlüsselwort und/oder listet die mit einem gegebenen Code-Node verknüpften Notizen auf und legt so die Entscheidungsspur hinter dem Code direkt über MCP offen.
+- **npm-Launcher für den MCP-Server** — `@codebeacon/mcp` lässt MCP-Clients den Server auf die npx-first-Weise starten, die sie erwarten (`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). Der abhängigkeitsfreie Node-Shim löst ein funktionierendes codebeacon über PATH → `uvx` → `pipx run` → `python3 -m codebeacon` auf und leitet stdio unangetastet weiter. Siehe [`npm/README.md`](npm/README.md). (Wird mit 0.7.0 ausgeliefert; noch nicht auf npm veröffentlicht.)
+- **GitHub Action für PR-Kontext** — eine Composite-Action kommentiert jeden Pull Request mit dem betroffenen Ausschnitt deines committeten Wissensgraphen: die Wiki-Artikel, die die Änderung berührt, den stromaufwärts gelegenen Blast-Radius und alle High-Impact-Hub-Dateien, die sie bearbeitet — eine Architektur-Drift-Prüfung für Reviews im KI-Zeitalter. Erfordert einen committeten `.codebeacon/`-Index, `fetch-depth: 0` und `permissions: pull-requests: write`. Siehe [`action/README.md`](action/README.md) und [`action/examples/pr-context.yml`](action/examples/pr-context.yml).
+- **Die Workspace-CLAUDE.md bleibt unter ~200 Zeilen** — in einem Multi-Projekt-Workspace behält die Root-`CLAUDE.md` jetzt nur die gemeinsame Übersicht und verschiebt die projektspezifischen Details in gescopte `.claude/rules/codebeacon-<project>.md`-Dateien, deren `paths:`-Frontmatter sie nur lädt, wenn die Dateien dieses Projekts berührt werden (den eigenen Empfehlungen von Anthropic für Kontextdateien folgend). Die Einzelprojekt-Ausgabe ist unverändert; setze `output.context_map.rules_split: false` für die alte monolithische Datei. Doppelte Projektzeilen werden ebenfalls zusammengefasst.
+- **Test-Fixtures werden standardmäßig ignoriert** — `tests/fixtures/`, `test/fixtures/` und `__fixtures__/` in beliebiger Tiefe werden jetzt standardmäßig ignoriert, sodass die synthetischen Test-Eingaben eines Projekts aufhören, falsche Routen und services in den Graphen einzuschleusen (codebeacons eigener Self-Scan hatte eine Fixture-`main.py` als fünf „Routen" gemeldet). Es ist die Regel mit der niedrigsten Priorität, sodass eine Zeile `!tests/fixtures/` in `.codebeaconignore` sie wieder aufnimmt, und einen Scan *auf* ein Fixture-Verzeichnis zu richten, sammelt es weiterhin ein.
+- **Warps Routen-Extraktion ist jetzt echt** — Warps Filter-Kombinator-Routen werden tatsächlich extrahiert: `warp::path!(...)`- und `warp::path("x")`-Segmente, Methoden-Kombinatoren (`warp::get()` / `post()` / …) und `.map`- / `.and_then`-Handler werden über ihr umschließendes Binding zu ganzen Routen korreliert. Ehrliche Grenzen (im Query-Header ausbuchstabiert): Filter, die innerhalb eines Bindings mit `.or(...)` verbunden sind, kollabieren zu einer einzigen verketteten Route, und `warp::path::param()`-Filteraufruf-Segmente sowie Closure-Handler bleiben unaufgelöst.
+
+---
+
 ## Neu in 0.6.9
 
 Die bislang größte Audit-Release: ein doppelter Upstream-Parity-Sweep (das allererste vollständige Audit von codesights Tracker, plus graphify v0.9.4–v0.9.12 / Issues bis #1776), kombiniert mit einer unabhängigen Multi-Agent-Bug-Hunt über codebeacon selbst. Jeder Kandidat wurde vor der Behebung reproduziert, jede Behebung mutation-getestet, und eine adversariale Zweitprüfung griff anschließend die Fixes selbst an — und fing so vor der Auslieferung 18 weitere Lücken ab. **48 echte Bugs behoben.**

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.es.md

@@ -27,6 +27,21 @@
 
 ---
 
+## Novedades en 0.7.0
+
+Una release de capacidades más que un barrido de bugs: codebeacon estrena un file-watcher en vivo, enlaza tus notas de diseño en el grafo de código, incorpora dos nuevos front-ends (un lanzador npm para el servidor MCP y una GitHub Action) y ajusta lo que indexa por defecto. Cada funcionalidad sigue siendo local-first — el scan central sigue sin necesitar red, ni nube, ni modelo.
+
+- **`codebeacon watch` mantiene el índice en vivo** — un file-watcher con debounce (`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`) resincroniza el grafo cada vez que cambian los archivos fuente vigilados. Una ráfaga de ediciones — un `git checkout` de 500 archivos, un cambio de rama — se fusiona en una única resincronización, y el watcher reutiliza exactamente las mismas reglas de ignore del scanner, de modo que escribir el índice nunca lo despierta en un bucle sobre su propia salida `.codebeacon/`. Necesita el nuevo extra opcional: `pip install 'codebeacon[watch]'` (watchdog).
+- **Las notas de diseño se enlazan en el grafo de código** — `codebeacon knowledge` ahora escribe sus notas (ADRs, notas de reunión, retros, specs) *dentro* de `beacon.json` cuando ya existe un índice: una referencia explícita a una ruta de archivo se convierte en una arista `references` de confianza, y una mención de símbolo distintiva (`PaymentService`, nunca un `User` pelado) se convierte en una arista `mentions` `AMBIGUOUS` — de modo que un agente que lee el grafo aprende *por qué* un service tiene la forma que tiene. Como `codebeacon scan` reconstruye el grafo de código solo a partir del fuente y descarta esta capa, **vuelve a ejecutar `codebeacon knowledge` después de un scan** para restaurar los enlaces.
+- **Herramienta MCP `beacon_knowledge`** — una nueva herramienta busca notas por palabra clave y/o lista las notas enlazadas a un nodo de código dado, exponiendo el rastro de decisiones detrás del código directamente por MCP.
+- **Lanzador npm para el servidor MCP** — `@codebeacon/mcp` permite que los clientes MCP arranquen el servidor de la forma npx-first que esperan (`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). El shim de Node sin dependencias resuelve un codebeacon funcional vía PATH → `uvx` → `pipx run` → `python3 -m codebeacon` y reenvía stdio sin tocarlo. Ver [`npm/README.md`](npm/README.md). (Se distribuye con 0.7.0; aún no publicado en npm.)
+- **GitHub Action para contexto de PR** — una action compuesta comenta en cada pull request con la porción afectada de tu grafo de conocimiento commiteado: los artículos de wiki que toca el cambio, el radio de impacto aguas arriba, y cualquier archivo hub de alto impacto que edite — una comprobación de deriva de arquitectura para la revisión en la era de la IA. Requiere un índice `.codebeacon/` commiteado, `fetch-depth: 0` y `permissions: pull-requests: write`. Ver [`action/README.md`](action/README.md) y [`action/examples/pr-context.yml`](action/examples/pr-context.yml).
+- **El CLAUDE.md de workspace se mantiene por debajo de ~200 líneas** — en un workspace multi-proyecto, el `CLAUDE.md` raíz ahora conserva solo la visión general compartida y mueve el detalle por proyecto a archivos `.claude/rules/codebeacon-<project>.md` con alcance acotado, cuyo frontmatter `paths:` los carga solo cuando se tocan los archivos de ese proyecto (siguiendo la propia guía de Anthropic para archivos de contexto). La salida de un solo proyecto no cambia; pon `output.context_map.rules_split: false` para el antiguo archivo monolítico. Las filas de proyecto duplicadas también se colapsan.
+- **Los fixtures de test se ignoran por defecto** — `tests/fixtures/`, `test/fixtures/` y `__fixtures__/` a cualquier profundidad ahora se ignoran por defecto, de modo que las entradas de test sintéticas de un proyecto dejan de inyectar rutas y services falsos en el grafo (el propio self-scan de codebeacon había reportado un `main.py` de fixtures como cinco "rutas"). Es la regla de menor precedencia, así que una línea `!tests/fixtures/` en `.codebeaconignore` las vuelve a incluir, y apuntar un scan *a* un directorio de fixtures sigue recogiéndolo.
+- **La extracción de rutas de Warp ahora es real** — las rutas de combinadores de filtros de Warp se extraen de verdad: los segmentos `warp::path!(...)` y `warp::path("x")`, los combinadores de método (`warp::get()` / `post()` / …) y los handlers `.map` / `.and_then` se correlacionan por su binding contenedor en rutas completas. Límites honestos (detallados en la cabecera de la query): los filtros unidos por `.or(...)` dentro de un mismo binding colapsan en una única ruta concatenada, y los segmentos de llamada a filtro `warp::path::param()` y los handlers de closure quedan sin resolver.
+
+---
+
 ## Novedades en 0.6.9
 
 La release de auditoría más grande hasta la fecha: un doble barrido de paridad con el upstream (la primera auditoría completa del tracker de codesight, más graphify v0.9.4–v0.9.12 / issues hasta el #1776) combinado con una caza de bugs multiagente independiente sobre el propio codebeacon. Cada candidato se reprodujo antes de corregirlo, cada corrección se probó con mutation testing, y una segunda revisión adversarial atacó luego las propias correcciones — atrapando 18 agujeros más antes de la publicación. **48 bugs reales corregidos.**

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.fr.md

@@ -27,6 +27,21 @@
 
 ---
 
+## Nouveautés en 0.7.0
+
+Une release de capacités plutôt qu'un balayage de bugs : codebeacon se dote d'un file-watcher en direct, relie vos notes de conception au graphe de code, embarque deux nouveaux front-ends (un lanceur npm pour le serveur MCP et une GitHub Action) et resserre ce qu'il indexe par défaut. Chaque fonctionnalité reste local-first — le scan central n'a toujours besoin ni de réseau, ni de cloud, ni de modèle.
+
+- **`codebeacon watch` garde l'index en direct** — un file-watcher avec debounce (`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`) resynchronise le graphe chaque fois que les fichiers source surveillés changent. Une rafale d'éditions — un `git checkout` de 500 fichiers, un changement de branche — se fond en une unique resynchronisation, et le watcher réutilise exactement les mêmes règles d'ignore que le scanner, si bien qu'écrire l'index ne le réveille jamais dans une boucle sur sa propre sortie `.codebeacon/`. Nécessite le nouvel extra optionnel : `pip install 'codebeacon[watch]'` (watchdog).
+- **Les notes de conception se relient au graphe de code** — `codebeacon knowledge` écrit désormais ses notes (ADR, comptes rendus de réunion, rétros, specs) *dans* `beacon.json` lorsqu'un index existe déjà : une référence explicite à un chemin de fichier devient une arête `references` de confiance, et une mention de symbole distinctive (`PaymentService`, jamais un simple `User`) devient une arête `mentions` `AMBIGUOUS` — de sorte qu'un agent qui lit le graphe apprend *pourquoi* un service a la forme qu'il a. Comme `codebeacon scan` reconstruit le graphe de code à partir du seul source et abandonne cette surcouche, **relancez `codebeacon knowledge` après un scan** pour restaurer les liens.
+- **Outil MCP `beacon_knowledge`** — un nouvel outil recherche les notes par mot-clé et/ou liste les notes reliées à un nœud de code donné, exposant la trace des décisions derrière le code directement via MCP.
+- **Lanceur npm pour le serveur MCP** — `@codebeacon/mcp` permet aux clients MCP de démarrer le serveur de la manière npx-first qu'ils attendent (`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). Le shim Node sans dépendances résout un codebeacon fonctionnel via PATH → `uvx` → `pipx run` → `python3 -m codebeacon` et relaie stdio sans y toucher. Voir [`npm/README.md`](npm/README.md). (Livré avec 0.7.0 ; pas encore publié sur npm.)
+- **GitHub Action pour le contexte de PR** — une action composite commente chaque pull request avec la tranche affectée de votre graphe de connaissances commité : les articles de wiki que touche le changement, le rayon d'impact en amont, et tout fichier hub à fort impact qu'il modifie — un contrôle de dérive d'architecture pour la revue à l'ère de l'IA. Nécessite un index `.codebeacon/` commité, `fetch-depth: 0` et `permissions: pull-requests: write`. Voir [`action/README.md`](action/README.md) et [`action/examples/pr-context.yml`](action/examples/pr-context.yml).
+- **Le CLAUDE.md de workspace reste sous ~200 lignes** — dans un workspace multi-projets, le `CLAUDE.md` racine ne conserve désormais que la vue d'ensemble partagée et déplace le détail par projet dans des fichiers `.claude/rules/codebeacon-<project>.md` à portée restreinte, dont le frontmatter `paths:` ne les charge que lorsque les fichiers de ce projet sont touchés (suivant les propres recommandations d'Anthropic pour les fichiers de contexte). La sortie mono-projet est inchangée ; mettez `output.context_map.rules_split: false` pour retrouver l'ancien fichier monolithique. Les lignes de projet en double sont également fusionnées.
+- **Les fixtures de test sont ignorées par défaut** — `tests/fixtures/`, `test/fixtures/` et `__fixtures__/` à n'importe quelle profondeur sont désormais ignorées par défaut, si bien que les entrées de test synthétiques d'un projet cessent d'injecter de fausses routes et de faux services dans le graphe (le propre self-scan de codebeacon avait signalé un `main.py` de fixtures comme cinq « routes »). C'est la règle de plus faible priorité, donc une ligne `!tests/fixtures/` dans `.codebeaconignore` les réinclut, et pointer un scan *sur* un répertoire de fixtures le collecte toujours.
+- **L'extraction des routes de Warp est réelle maintenant** — les routes à combinateurs de filtres de Warp sont réellement extraites : les segments `warp::path!(...)` et `warp::path("x")`, les combinateurs de méthode (`warp::get()` / `post()` / …) et les handlers `.map` / `.and_then` sont corrélés par leur binding englobant en routes entières. Limites honnêtes (détaillées dans l'en-tête de la requête) : les filtres joints par `.or(...)` au sein d'un même binding se fondent en une unique route concaténée, et les segments d'appel de filtre `warp::path::param()` ainsi que les handlers de closure restent non résolus.
+
+---
+
 ## Nouveautés en 0.6.9
 
 La plus grande release d'audit à ce jour : un double balayage de parité amont (le tout premier audit complet du tracker de codesight, plus graphify v0.9.4–v0.9.12 / issues jusqu'au #1776) combiné à une chasse aux bugs multi-agent indépendante sur codebeacon lui-même. Chaque candidat a été reproduit avant correction, chaque correction a été testée par mutation, et une seconde revue adversariale a ensuite attaqué les correctifs eux-mêmes — attrapant 18 failles supplémentaires avant la publication. **48 bugs réels corrigés.**

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.ja.md

@@ -27,6 +27,21 @@
 
 ---
 
+## 0.7.0 の新機能
+
+バグ修正のスイープというより機能リリースです:codebeacon にライブのファイルウォッチャーが加わり、設計ノートをコードグラフに繋ぎ、2つの新しいフロントエンド(MCP サーバー用の npm ランチャーと GitHub Action)を提供し、デフォルトでインデックスする対象を絞り込みました。すべての機能はローカルファーストのままです — コアスキャンは相変わらずネットワークも、クラウドも、モデルも必要としません。
+
+- **`codebeacon watch` がインデックスをライブに保ちます** — デバウンスされたファイルウォッチャー(`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`)が、監視中のソースファイルが変わるたびにグラフを再同期します。編集の集中 — 500ファイルの `git checkout`、ブランチ切り替え — は単一の再同期にまとめられ、ウォッチャーはスキャナーとまったく同じ無視ルールを再利用するため、インデックスを書き込む動作が自身の `.codebeacon/` 出力を巡るループでウォッチャーを起こすことはありません。新しいオプションの extra が必要です:`pip install 'codebeacon[watch]'`(watchdog)。
+- **設計ノートがコードグラフに繋がります** — `codebeacon knowledge` は、インデックスが既に存在する場合、ノート(ADR、会議メモ、レトロ、仕様)を `beacon.json` の *中に* 書き込むようになりました:明示的なファイルパス参照は信頼された `references` エッジになり、特徴的なシンボルの言及(`PaymentService`、単なる `User` は決して対象外)は `AMBIGUOUS` な `mentions` エッジになります — こうしてグラフを読むエージェントは、ある service が *なぜ* その形をしているのかを学びます。`codebeacon scan` はコードグラフをソースだけから再構築してこのオーバーレイを捨てるため、リンクを復元するには **スキャンの後に `codebeacon knowledge` を再実行してください**。
+- **`beacon_knowledge` MCP ツール** — 新しいツールがキーワードでノートを検索し、あるいは指定したコードノードに繋がったノートを一覧して、コードの背後にある意思決定の軌跡を MCP 越しに直接公開します。
+- **MCP サーバー用の npm ランチャー** — `@codebeacon/mcp` により、MCP クライアントは期待どおりの npx ファーストの方法でサーバーを起動できます(`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`)。依存関係ゼロの Node シムが、動作する codebeacon を PATH → `uvx` → `pipx run` → `python3 -m codebeacon` の順に解決し、stdio を手を加えずそのまま転送します。[`npm/README.md`](npm/README.md) を参照。(0.7.0 に同梱、npm へはまだ公開されていません。)
+- **PR コンテキスト用の GitHub Action** — コンポジットアクションが、すべてのプルリクエストに、コミットされた知識グラフのうち影響を受けたスライスをコメントします:変更が触れる wiki 記事、上流のブラスト半径、そして編集された高影響のハブファイル — AI 時代のレビューのためのアーキテクチャドリフト検査です。コミットされた `.codebeacon/` インデックス、`fetch-depth: 0`、`permissions: pull-requests: write` が必要です。[`action/README.md`](action/README.md) と [`action/examples/pr-context.yml`](action/examples/pr-context.yml) を参照。
+- **ワークスペースの CLAUDE.md が約200行以下に収まります** — マルチプロジェクトのワークスペースでは、ルートの `CLAUDE.md` が共有の概要だけを保ち、プロジェクトごとの詳細を、`paths:` フロントマターがそのプロジェクトのファイルに触れたときだけ読み込むスコープ付きの `.claude/rules/codebeacon-<project>.md` ファイルに移すようになりました(コンテキストファイルに関する Anthropic 自身のガイダンスに従っています)。単一プロジェクトの出力は変わりません。従来の一枚岩ファイルが欲しい場合は `output.context_map.rules_split: false` を設定してください。重複するプロジェクト行もまとめられます。
+- **テストフィクスチャがデフォルトで無視されます** — どの深さの `tests/fixtures/`、`test/fixtures/`、`__fixtures__/` もデフォルトで無視されるようになり、プロジェクトの合成テスト入力が偽のルートや service をグラフに注入しなくなります(codebeacon 自身のセルフスキャンは、フィクスチャの `main.py` を5つの「ルート」として報告していました)。これは最も優先度の低いルールなので、`.codebeaconignore` に `!tests/fixtures/` の行を入れれば再び含められ、スキャンをフィクスチャディレクトリ *に* 向ければ依然として収集されます。
+- **Warp のルート抽出が本物になりました** — Warp のフィルタ・コンビネータのルートが実際に抽出されます:`warp::path!(...)` と `warp::path("x")` のセグメント、メソッドコンビネータ(`warp::get()` / `post()` / …)、そして `.map` / `.and_then` ハンドラが、それらを囲むバインディングを基準に相関づけられ、まるごとのルートになります。正直な限界(クエリヘッダーに明記):1つのバインディング内で `.or(...)` で繋がれたフィルタは単一の連結ルートに潰れ、`warp::path::param()` のフィルタ呼び出しセグメントとクロージャハンドラは未解決のまま残ります。
+
+---
+
 ## 0.6.9 の新機能
 
 これまでで最大規模の監査リリースです。二重のアップストリーム・パリティ・スイープ(codesight のトラッカーに対する史上初の完全監査に加え、graphify v0.9.4–v0.9.12 / issue は #1776 まで)と、codebeacon 自体に対する独立したマルチエージェント・バグハントを組み合わせました。各候補は修正前に再現し、各修正は mutation テストにかけ、さらに敵対的な2次レビューが修正自体を攻撃して、リリース前にさらに18個の穴を捕まえました。**実バグ48件を修正。**

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.ko.md

@@ -27,6 +27,21 @@
 
 ---
 
+## 0.7.0 새 소식
+
+버그 스윕이라기보다 기능 릴리스입니다: codebeacon에 실시간 파일 워처가 생기고, 설계 노트를 코드 그래프에 연결하며, 두 개의 새 프런트엔드(MCP 서버용 npm 런처와 GitHub Action)를 제공하고, 기본으로 인덱싱하는 대상을 좁혔습니다. 모든 기능은 로컬 우선을 유지합니다 — 코어 스캔은 여전히 네트워크도, 클라우드도, 모델도 필요로 하지 않습니다.
+
+- **`codebeacon watch`가 인덱스를 실시간으로 유지합니다** — 디바운스된 파일 워처(`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`)가 감시 중인 소스 파일이 바뀔 때마다 그래프를 다시 동기화합니다. 편집 폭주 — 500개 파일 `git checkout`, 브랜치 전환 — 는 단일 재동기화로 합쳐지고, 워처가 스캐너의 정확히 동일한 무시 규칙을 재사용하므로 인덱스를 쓰는 동작이 자신의 `.codebeacon/` 출력을 도는 루프로 워처를 깨우는 일이 없습니다. 새 선택적 extra가 필요합니다: `pip install 'codebeacon[watch]'`(watchdog).
+- **설계 노트가 코드 그래프에 연결됩니다** — `codebeacon knowledge`가 인덱스가 이미 존재할 때 이제 노트(ADR, 회의록, 회고, 스펙)를 `beacon.json` *안에* 기록합니다: 명시적 파일 경로 참조는 신뢰된 `references` 엣지가 되고, 특징적인 심볼 언급(`PaymentService`, 맨 `User`은 절대 아님)은 `AMBIGUOUS` `mentions` 엣지가 됩니다 — 그래서 그래프를 읽는 에이전트가 어떤 service가 *왜* 그런 형태인지를 배웁니다. `codebeacon scan`은 코드 그래프를 소스만으로 다시 만들며 이 오버레이를 버리므로, 링크를 복원하려면 **스캔 후 `codebeacon knowledge`를 다시 실행하세요**.
+- **`beacon_knowledge` MCP 도구** — 새 도구가 키워드로 노트를 검색하거나 주어진 코드 노드에 연결된 노트를 나열해, 코드 뒤에 있는 결정의 흔적을 MCP로 직접 노출합니다.
+- **MCP 서버용 npm 런처** — `@codebeacon/mcp`는 MCP 클라이언트가 기대하는 npx 우선 방식으로 서버를 시작하게 해줍니다(`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). 의존성 없는 Node 심(shim)이 PATH → `uvx` → `pipx run` → `python3 -m codebeacon` 순으로 동작하는 codebeacon을 찾아 stdio를 손대지 않고 그대로 전달합니다. [`npm/README.md`](npm/README.md) 참조. (0.7.0에 포함, 아직 npm에 게시되지 않음.)
+- **PR 컨텍스트용 GitHub Action** — 컴포지트 액션이 모든 풀 리퀘스트에, 커밋된 지식 그래프에서 영향받는 조각을 댓글로 남깁니다: 변경이 건드리는 wiki 문서, 업스트림 폭발 반경, 그리고 편집된 고영향 허브 파일 — AI 시대 리뷰를 위한 아키텍처 드리프트 점검입니다. 커밋된 `.codebeacon/` 인덱스, `fetch-depth: 0`, `permissions: pull-requests: write`가 필요합니다. [`action/README.md`](action/README.md)와 [`action/examples/pr-context.yml`](action/examples/pr-context.yml) 참조.
+- **워크스페이스 CLAUDE.md가 ~200줄 이하로 유지됩니다** — 다중 프로젝트 워크스페이스에서 루트 `CLAUDE.md`가 이제 공유 개요만 담고, 프로젝트별 세부는 `paths:` 프런트매터가 해당 프로젝트 파일을 건드릴 때만 로드하는 스코프된 `.claude/rules/codebeacon-<project>.md` 파일로 옮깁니다(컨텍스트 파일에 대한 Anthropic 자체 가이드를 따름). 단일 프로젝트 출력은 그대로입니다. 예전의 단일 파일을 원하면 `output.context_map.rules_split: false`로 설정하세요. 중복 프로젝트 행도 합쳐집니다.
+- **테스트 픽스처가 기본으로 무시됩니다** — 어느 깊이든 `tests/fixtures/`, `test/fixtures/`, `__fixtures__/`가 이제 기본 무시되어, 프로젝트의 합성 테스트 입력이 가짜 라우트와 service를 그래프에 주입하는 일이 멈춥니다(codebeacon 자체 셀프 스캔이 픽스처 `main.py`를 다섯 개의 "라우트"로 보고했었습니다). 이는 우선순위가 가장 낮은 규칙이므로, `.codebeaconignore`에 `!tests/fixtures/` 줄을 넣으면 다시 포함되고, 스캔을 픽스처 디렉토리*로* 향하게 하면 여전히 수집됩니다.
+- **Warp 라우트 추출이 이제 실제로 됩니다** — Warp의 필터-콤비네이터 라우트가 실제로 추출됩니다: `warp::path!(...)`와 `warp::path("x")` 세그먼트, 메서드 콤비네이터(`warp::get()` / `post()` / …), 그리고 `.map` / `.and_then` 핸들러가 그것들을 감싸는 바인딩을 기준으로 상관되어 온전한 라우트로 만들어집니다. 정직한 한계(쿼리 헤더에 명시됨): 한 바인딩 안에서 `.or(...)`로 이어진 필터는 하나의 연결된 라우트로 합쳐지고, `warp::path::param()` 필터-호출 세그먼트와 클로저 핸들러는 미해결로 남습니다.
+
+---
+
 ## 0.6.9 새 소식
 
 역대 최대 규모의 감사 릴리스입니다: 이중 업스트림 패리티 스윕(codesight 트래커 최초 전체 감사 + graphify v0.9.4–v0.9.12 / 이슈 #1776까지)에 codebeacon 자체에 대한 독립 멀티에이전트 버그 헌트를 결합했습니다. 모든 후보를 수정 전에 재현하고, 모든 수정을 mutation 테스트했으며, 적대적 2차 리뷰가 수정 자체를 공격해 출시 전에 추가 구멍 18개를 잡아냈습니다. **실제 버그 48건 수정.**

{codebeacon-0.6.9 → codebeacon-0.7.0}/README.md

@@ -25,6 +25,21 @@
 
 ---
 
+## What's new in 0.7.0
+
+A capability release rather than a bug sweep: codebeacon grows a live file-watcher, links your design notes into the code graph, ships two new front-ends (an npm launcher for the MCP server and a GitHub Action), and tightens what it indexes by default. Every feature stays local-first — the core scan still needs no network, no cloud, and no model.
+
+- **`codebeacon watch` keeps the index live** — a debounced file-watcher (`codebeacon watch [path] [--debounce 2.0] [--once] [--exclude PATTERN]`) re-syncs the graph whenever watched source files change. A burst of edits — a 500-file `git checkout`, a branch switch — coalesces into a single resync, and the watcher reuses the scanner's exact ignore rules so writing the index never wakes it into a loop over its own `.codebeacon/` output. Needs the new optional extra: `pip install 'codebeacon[watch]'` (watchdog).
+- **Design notes link into the code graph** — `codebeacon knowledge` now writes its notes (ADRs, meeting notes, retros, specs) *into* `beacon.json` when an index already exists: an explicit file-path reference becomes a trusted `references` edge, and a distinctive symbol mention (`PaymentService`, never a bare `User`) becomes an `AMBIGUOUS` `mentions` edge — so an agent reading the graph learns *why* a service is shaped the way it is. Because `codebeacon scan` rebuilds the code graph from source alone and drops this overlay, **re-run `codebeacon knowledge` after a scan** to restore the links.
+- **`beacon_knowledge` MCP tool** — a new tool searches notes by keyword and/or lists the notes linked to a given code node, exposing the decision trail behind the code directly over MCP.
+- **npm launcher for the MCP server** — `@codebeacon/mcp` lets MCP clients start the server the npx-first way they expect (`"command": "npx", "args": ["-y", "@codebeacon/mcp"]`). The zero-dependency Node shim resolves a working codebeacon via PATH → `uvx` → `pipx run` → `python3 -m codebeacon` and forwards stdio untouched. See [`npm/README.md`](npm/README.md). (Ships with 0.7.0; not yet published to npm.)
+- **GitHub Action for PR context** — a composite action comments on every pull request with the affected slice of your committed knowledge graph: the wiki articles the change touches, the upstream blast radius, and any high-impact hub files it edits — an architecture-drift check for AI-era review. Requires a committed `.codebeacon/` index, `fetch-depth: 0`, and `permissions: pull-requests: write`. See [`action/README.md`](action/README.md) and [`action/examples/pr-context.yml`](action/examples/pr-context.yml).
+- **Workspace CLAUDE.md stays under ~200 lines** — in a multi-project workspace the root `CLAUDE.md` now keeps only the shared overview and moves per-project detail into scoped `.claude/rules/codebeacon-<project>.md` files whose `paths:` frontmatter loads them only when that project's files are touched (following Anthropic's own guidance for context files). Single-project output is unchanged; set `output.context_map.rules_split: false` for the old monolithic file. Duplicate project rows are also collapsed.
+- **Test fixtures are ignored by default** — `tests/fixtures/`, `test/fixtures/`, and `__fixtures__/` at any depth are now default-ignored, so a project's synthetic test inputs stop injecting fake routes and services into the graph (codebeacon's own self-scan had reported a fixture `main.py` as five "routes"). It is the lowest-precedence rule, so a `.codebeaconignore` line `!tests/fixtures/` re-includes them, and pointing a scan *at* a fixture directory still collects it.
+- **Warp route extraction is real now** — Warp's filter-combinator routes are actually extracted: `warp::path!(...)` and `warp::path("x")` segments, method combinators (`warp::get()` / `post()` / …), and `.map` / `.and_then` handlers are correlated by their enclosing binding into whole routes. Honest limits (spelled out in the query header): filters joined by `.or(...)` inside one binding collapse into a single concatenated route, and `warp::path::param()` filter-call segments and closure handlers are left unresolved.
+
+---
+
 ## What's new in 0.6.9
 
 The largest audit release to date: a dual upstream-parity sweep (the first-ever full audit of codesight's tracker, plus graphify v0.9.4–v0.9.12 / issues through #1776) combined with an independent multi-agent bug hunt over codebeacon itself. Every candidate was reproduced before fixing, every fix was mutation-tested, and an adversarial second review then attacked the fixes themselves — catching 18 further holes before release. **48 real bugs fixed.**
@@ -189,7 +204,8 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 - **Deep-dive mode** — `--deep-dive` generates per-project `.codebeacon/` + `CLAUDE.md` for every sub-project; running `codebeacon scan . --update` from any sub-project folder automatically syncs all projects in the workspace
 - **Workspace auto-rediscovery** — on every `scan` / `sync`, codebeacon re-scans the workspace and appends any new project folders to `codebeacon.yaml` before extraction, so freshly added sub-projects are never silently skipped; pass `--no-rediscover` to opt out for hand-curated configs
 - **Graphify-style semantic enrichment** — after AST extraction, the skill dispatches one parallel subagent per chunk to emit `{nodes, edges, hyperedges}` with 8 relation types (`calls`/`implements`/`references`/`cites`/`conceptually_related_to`/`shares_data_with`/`semantically_similar_to`/`rationale_for`) and EXTRACTED/INFERRED/AMBIGUOUS confidence; on Claude Code the subagent runs one tier below the host model (Opus→Sonnet, Sonnet→Haiku) so spend stays proportional to corpus size. AST owns code nodes; LLM only contributes `concept`/`document`/`paper` nodes. Existing 0.3.x archives replay through the new schema unchanged.
-- **Knowledge mode (`codebeacon knowledge`)** — scan markdown notes (ADRs, meeting notes, retros, specs, research) and produce a single `KNOWLEDGE.md` next to `.codebeacon/`. Auto-classifies by filename and heading patterns, parses Obsidian YAML frontmatter and `[[backlinks]]`, surfaces a top-level "Key Decisions" + "Open Questions" rollup so an agent learns *why* the codebase looks the way it does. Pure heuristics — no LLM call.
+- **Knowledge mode (`codebeacon knowledge`)** — scan markdown notes (ADRs, meeting notes, retros, specs, research) and produce a single `KNOWLEDGE.md` next to `.codebeacon/`. Auto-classifies by filename and heading patterns, parses Obsidian YAML frontmatter and `[[backlinks]]`, surfaces a top-level "Key Decisions" + "Open Questions" rollup so an agent learns *why* the codebase looks the way it does. Pure heuristics — no LLM call. When a `beacon.json` already exists, the notes are also **linked into the graph**: explicit file-path references become trusted `references` edges and distinctive symbol mentions become `AMBIGUOUS` `mentions` edges. This overlay is dropped by the next `codebeacon scan` (which rebuilds the code graph from source alone), so re-run `codebeacon knowledge` after a scan to restore it.
+- **Watch mode (`codebeacon watch`)** — a debounced file-watcher re-syncs the index whenever watched source files change, coalescing a burst of edits (a 500-file `git checkout`) into a single resync and reusing the scanner's exact ignore rules so it never loops on its own `.codebeacon/` output. Optional extra: `pip install 'codebeacon[watch]'`.
 - **Bare-path shortcut** — `codebeacon ./src` is now equivalent to `codebeacon scan ./src`; when the first argument isn't a registered subcommand, `scan` is auto-injected, so muscle memory from `graphify <path>` / `codesight <path>` works here too.
 - **Hardened semantic pipeline** — `semantic-apply` guards against malformed agent JSONL (null/list/code-fence lines, missing fields), coerces broken `confidence_score` values (None/NaN/string/out-of-range) to a safe default, snapshots `beacon.json` → `beacon.json.bak` before merging so the AST baseline is always recoverable, and regenerates `beacon.html` + `callflow.html` so visual exports reflect the newly-inferred edges.
 - **Sensitive file/dir guard** — `secrets/`, `credentials/`, `.ssh/`, `.aws/`, `.gnupg/` directories are always skipped; filenames matching credential patterns (`api_token`, `oauth_token`, `private_key`, `client_secret`; underscore *and* hyphen variants) are excluded from the source-file collector before they reach extractors.
@@ -230,6 +246,18 @@ codebeacon sync                      # subsequent runs via config
 | Swift | Vapor |
 | ArkTS | `.ets` (HarmonyOS) collected — extractors framework-agnostic |
 
+> **How the "27 frameworks" count works.** Coverage is grounded in tree-sitter
+> queries, and frameworks in the same grammar family share query files — Rocket
+> reuses Actix-Web's attribute-macro pattern, the JS/TS web frameworks share the
+> class/decorator queries, and so on. That sharing is what makes broad coverage
+> tractable, but it also means depth varies per framework: some are exercised by
+> extensive fixtures, others by a single query pattern. Where a framework has
+> known limits, they're documented at the source — e.g. Warp's `.or(...)` and
+> `warp::path::param()` caveats live in the query header
+> ([`codebeacon/extract/queries/actix.scm`](codebeacon/extract/queries/actix.scm)).
+> If a specific framework matters to you, scan a representative repo and check
+> the routes/services it actually extracts before relying on the number.
+
 ---
 
 ## Architecture
@@ -420,6 +448,71 @@ codebeacon scan .
 | `beacon_blast_radius` | Upstream callers + downstream affected nodes |
 | `beacon_routes` | List all HTTP routes, filterable by project |
 | `beacon_services` | List all services/classes, filterable by project |
+| `beacon_knowledge` | Search knowledge notes (ADRs, meetings, retros, specs) or list the notes linked to a code node — the *why* behind the code |
+| `beacon_pr_context` | Given changed files (or a `base` ref), return the wiki articles in their blast radius — read the docs that matter before a PR review |
+
+### npm launcher (`@codebeacon/mcp`)
+
+MCP clients that prefer to launch servers with `npx` can use the thin Node
+wrapper instead of pointing at the `codebeacon` binary directly:
+
+```json
+{
+  "mcpServers": {
+    "codebeacon": {
+      "command": "npx",
+      "args": ["-y", "@codebeacon/mcp", "--dir", "/path/to/your/repo/.codebeacon"]
+    }
+  }
+}
+```
+
+The wrapper bundles no Python — it resolves an installed codebeacon on the host
+(PATH → `uvx` → `pipx run` → `python3 -m codebeacon`) and forwards stdio to
+`codebeacon serve` untouched. See [`npm/README.md`](npm/README.md) for the full
+per-client config snippets. (Shipping with 0.7.0; not yet published to npm.)
+
+---
+
+## GitHub Action — PR context
+
+Comment on every pull request with the affected slice of your committed
+knowledge graph — the wiki articles the change touches, the upstream blast
+radius, and any high-impact hub files it edits. It reframes review around
+**architecture drift**: instead of reading a diff in isolation, the comment
+points at the parts of the system that actually move.
+
+```yaml
+# .github/workflows/pr-context.yml
+name: codebeacon PR context
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+permissions:
+  contents: read
+  pull-requests: write        # required to post/update the comment
+jobs:
+  pr-context:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0       # required — full history so the base is diffable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: codebeacon/codebeacon/action@v1
+        with:
+          base: ${{ github.base_ref }}
+```
+
+The Action does **not** scan on the runner — it reads the `.codebeacon/` index
+you commit to the repo (codebeacon's model is that the graph is a
+git-committable artifact). If the index is missing it posts one-time setup
+guidance instead of failing the build, and it updates a single marked comment in
+place rather than stacking duplicates. See [`action/README.md`](action/README.md)
+and [`action/examples/pr-context.yml`](action/examples/pr-context.yml) for inputs
+and edge-case behaviour.
 
 ---
 
@@ -428,6 +521,7 @@ codebeacon scan .
 ```bash
 pip install codebeacon              # all language grammars included
 pip install codebeacon[cluster]     # + Leiden community detection (graspologic)
+pip install codebeacon[watch]       # + live file-watcher for `codebeacon watch` (watchdog)
 pip install --upgrade codebeacon    # upgrade to latest version with all dependencies
 ```
 
@@ -459,6 +553,12 @@ codebeacon sync --config <file>           # use a specific config file
 codebeacon sync --no-rediscover           # don't auto-append newly added projects (hand-curated yaml mode)
 codebeacon sync --exclude PATTERN         # same flag, same semantics
 
+# Watch mode — keep the index live as you edit (needs the `watch` extra)
+codebeacon watch [path]                    # re-sync on file changes (default path: cwd)
+codebeacon watch . --debounce 2.0          # quiet-window before a resync fires; coalesces bursts
+codebeacon watch . --once                  # process one debounce cycle then exit
+codebeacon watch . --exclude 'docs/**'     # extra gitignore-style pattern (repeatable)
+
 # PR / CI: what does this diff actually break?
 codebeacon affected --base main           # walk upstream callers of every changed file
 codebeacon affected --base origin/main --head HEAD --depth 4 --limit 200
@@ -619,6 +719,11 @@ output:
   obsidian: true
   context_map:
     targets: [CLAUDE.md, .cursorrules, AGENTS.md]
+    rules_split: true          # multi-project workspaces: keep CLAUDE.md under
+                               # ~200 lines and move per-project detail into
+                               # scoped .claude/rules/codebeacon-<project>.md
+                               # files. Set false for the old monolithic CLAUDE.md.
+                               # No effect on single-project scans.
 
 wave:
   auto: true
@@ -658,6 +763,8 @@ fixtures/
 
 `!pattern` re-includes a previously-ignored path; later rules override earlier ones. The walker prunes directories whose name matches the rule set, but defers pruning when any negation rule could un-ignore a nested file.
 
+**Default fixture exclusion.** `tests/fixtures/`, `test/fixtures/`, and `__fixtures__/` are ignored by default at any depth — test-fixture trees are synthetic inputs for a project's *own* test suite, not product surface, and indexing them injects fake routes and services. This is the lowest-precedence rule, so a `.codebeaconignore` line `!tests/fixtures/` re-includes them, and pointing a scan directly *at* a fixture directory still collects it.
+
 ---
 
 ## How It Compares
@@ -700,6 +807,50 @@ All AST processing is local. Your source code never leaves your machine when you
 
 ---
 
+## Air-Gapped & Compliance-Friendly
+
+codebeacon's core pipeline — tree-sitter AST parsing → knowledge graph → wiki
+and context map — runs **entirely on your machine**. It requires:
+
+- **No network.** The scan makes no outbound calls; nothing about your source
+  code leaves the host.
+- **No cloud service.** There is no backend, no account, no telemetry.
+- **No LLM — not even a local one.** The graph, wiki, `beacon.json`, and
+  `CLAUDE.md` are all produced by deterministic AST analysis. (The optional
+  AI-semantic layer is a *separate*, opt-in step owned by the `/codebeacon`
+  agent — it never runs unless you invoke it; see
+  [Privacy & Security](#privacy--security) — and the CLI ships no API client,
+  key handling, or model name.)
+
+That architecture makes codebeacon suitable for **air-gapped and tightly
+regulated environments** — healthcare, defense, legal, finance — where source
+code cannot touch third-party services. To be precise about what that does and
+does not mean: codebeacon makes **no compliance certification claims** (no
+HIPAA, FedRAMP, CMMC, SOC 2, or similar). What it offers is an architecture that
+keeps code on-premises, so it can *fit* within environments governed by those
+policies. Verifying that codebeacon meets the specific controls of your
+environment remains your responsibility.
+
+**Offline install.** Because it is a normal Python package with vendored
+grammars, codebeacon installs without internet access on the target host:
+download the wheel and its dependencies on a connected machine, transfer them
+across the air gap, and install from the local files.
+
+```bash
+# On a connected machine (include the grammar extras you need — [full] grabs all):
+pip download 'codebeacon[full]' -d ./codebeacon-offline
+
+# Transfer ./codebeacon-offline across the air gap, then on the target host:
+pip install --no-index --find-links ./codebeacon-offline 'codebeacon[full]'
+```
+
+The base install bundles Python + JavaScript/TypeScript grammars; other
+languages are ordinary wheels pulled in by extras (`[jvm]`, `[backend]`,
+`[full]`, …), so include the extras you need in the download and nothing is
+fetched at runtime.
+
+---
+
 ## Contributing
 
 ```bash