codebeacon 0.3.1__tar.gz → 0.3.3__tar.gz

{codebeacon-0.3.1 → codebeacon-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -184,6 +184,12 @@ project-root/
         entities/<Name>.md
         components/<Name>.md
     obsidian/            ← Obsidian vault (one note per graph node)
+    semantic/
+      original.jsonl     ← durable archive of every applied AI-semantic result
+                           (skipped on rescans, never re-emitted as a task)
+    semantic-tasks.jsonl     ← pending AI-semantic batch (present only between
+                               `semantic-prepare` and `semantic-apply`)
+    semantic-results.jsonl   ← agent-written results (same lifecycle as above)
 ```
 
 ### Deep Dive Mode
@@ -243,11 +249,31 @@ codebeacon install
 This copies `SKILL.md` to `~/.claude/skills/codebeacon/` and registers the `/codebeacon` trigger in `~/.claude/CLAUDE.md`. Restart your Claude Code session, then type `/codebeacon` to scan the current directory.
 
 ```
-/codebeacon                  # scan current directory
-/codebeacon /path/to/project # scan a specific path
-/codebeacon sync             # re-scan from codebeacon.yaml
+/codebeacon                       # scan current directory + auto AI-semantic
+/codebeacon /path/to/project      # scan a specific path  + auto AI-semantic
+/codebeacon sync                  # re-scan from codebeacon.yaml + auto AI-semantic
+/codebeacon <path> --no-semantic  # scan only, skip the AI-semantic step
+/codebeacon <path> --wiki-only    # regenerate wiki from existing beacon.json
+/codebeacon semantic-prepare      # emit a fresh tasks file only
+/codebeacon semantic-apply        # merge a results file the agent already wrote
+/codebeacon serve <path>          # start MCP server pointing at .codebeacon/
+/codebeacon query <term>          # search the graph
+/codebeacon path <src> <tgt>      # shortest path
+/codebeacon upgrade               # pip upgrade + refresh this skill (then restart Claude Code)
 ```
 
+By default `scan` and `sync` invocations automatically run the **AI-semantic** pipeline at the end (see the [AI-Semantic Enrichment](#ai-semantic-enrichment-via-the-codebeacon-skill) section). The agent uses whatever model your Claude Code session is currently running on — Opus, Sonnet, Haiku — codebeacon never hardcodes a model and never needs an API key.
+
+### Updating to a new version
+
+Run **one** command from anywhere:
+
+```bash
+codebeacon upgrade
+```
+
+This pip-upgrades the package, then re-runs `codebeacon install` so `~/.claude/skills/codebeacon/SKILL.md` is overwritten with the new release's copy. Restart your Claude Code session for the new SKILL.md to load. If codebeacon is installed in editable mode (`pip install -e .`), the pip step is skipped — pass `--force` to upgrade anyway.
+
 ### MCP Server
 
 Run codebeacon as a persistent MCP server so any MCP-compatible client can query your knowledge graph directly.
@@ -319,7 +345,7 @@ codebeacon scan /workspace                # workspace root (multi-project)
 codebeacon scan . --update                # incremental: mtime/size fast path + content-hash fallback
 codebeacon scan . --wiki-only             # skip re-extraction, regenerate wiki/obsidian/context map from existing beacon.json
 codebeacon scan . --obsidian-dir <path>   # write Obsidian vault to custom location
-codebeacon scan . --semantic              # enable LLM semantic extraction
+codebeacon scan . --semantic              # enable structured-comment semantic extraction (Javadoc/JSDoc/docstring refs)
 codebeacon scan . --list-only             # detect frameworks only, don't extract
 codebeacon scan /workspace --deep-dive    # per-project + combined workspace outputs
 
@@ -329,6 +355,16 @@ codebeacon sync                           # run from codebeacon.yaml (auto-appen
 codebeacon sync --config <file>           # use a specific config file
 codebeacon sync --no-rediscover           # don't auto-append newly added projects (hand-curated yaml mode)
 
+# AI-semantic enrichment (the agent does the LLM work, codebeacon does the bookkeeping)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
+                                          # rehydrate semantic archive onto beacon.json, emit fresh tasks
+                                          # for NEW candidates only (god-node folders + unresolved targets);
+                                          # writes .codebeacon/semantic-tasks.jsonl
+codebeacon semantic-apply   [--dir .codebeacon]
+                                          # read .codebeacon/semantic-results.jsonl, merge as INFERRED
+                                          # references edges, append to .codebeacon/semantic/original.jsonl
+                                          # archive, clear pending files, regenerate wiki/obsidian/context map
+
 # Query the knowledge graph
 codebeacon query <term> [--dir .codebeacon] [--limit N]   # search nodes by label substring
 codebeacon path <source> <target> [--dir .codebeacon]     # shortest dependency path
@@ -340,10 +376,57 @@ codebeacon merge-driver <base> <cur> <other>  # invoked by git after `hook insta
 # Integrations
 codebeacon serve [--dir .codebeacon]      # start MCP server (stdio)
 codebeacon install                        # install Claude Code skill
+codebeacon upgrade                        # pip install --upgrade + refresh ~/.claude/skills/codebeacon/SKILL.md
+                                          # (`--force` to upgrade even when installed in editable mode)
 ```
 
 ---
 
+## AI-Semantic Enrichment (via the `/codebeacon` skill)
+
+Tree-sitter parsing finds what's in the AST. **AI-semantic** finds what's only in the *comments* — the `@see UserService` in a Javadoc, the `:class:`OrderRepository`` in a Python docstring, the contractual references documented next to a route handler. codebeacon ships two layers for this:
+
+| Layer | Flag | Cost | What it catches |
+|---|---|---|---|
+| Structured-comment parsing | `--semantic` | free, local, no LLM | Javadoc `@see` / `{@link}`, JSDoc `@see` / `@param` types, Python `:class:` / `:func:` / `See Also` |
+| **AI-semantic** | auto in `/codebeacon` skill | uses the agent's existing model — **no extra API key** | unresolved class/type/service references that regex can't catch (free-form prose, indirect mentions, type-only hints) |
+
+The CLI itself never makes an LLM API call. The AI-semantic layer is intentionally **owned by the running agent** inside the `/codebeacon` Claude Code skill — that way the user's model choice (Opus / Sonnet / Haiku / anything) is honored, and codebeacon never needs `ANTHROPIC_API_KEY` or any cloud configuration.
+
+### How it runs
+
+When you invoke `/codebeacon` in Claude Code:
+
+1. `scan` / `sync` builds `beacon.json` from the AST (no LLM).
+2. `codebeacon semantic-prepare` re-applies the prior archive to the fresh graph, then writes `.codebeacon/semantic-tasks.jsonl` containing **only new candidates** — files that score high (unresolved-target edges + god-node folders) and have never been processed before.
+3. The skill loops over the tasks file. For each line, the agent (using its current model) reads the `excerpt` field and returns inferred references inline. Results are written to `.codebeacon/semantic-results.jsonl`.
+4. `codebeacon semantic-apply` merges the results as `INFERRED references` edges into `beacon.json`, **appends them to `.codebeacon/semantic/original.jsonl`** (the durable archive), clears the pending tasks/results files, and regenerates wiki + obsidian + context map.
+5. Next scan: `semantic-prepare` rehydrates the archive onto the freshly built graph (so historical inferences don't disappear) and emits a tasks file with **only newly discovered candidates** since the last archive. Already-processed files are skipped via `task_id` (SHA1 of `file_path|node_id`).
+
+This gives you incremental, idempotent enrichment: the agent never re-analyzes the same file twice, and accumulated AI signal survives every rescan.
+
+### Direct CLI usage
+
+If you're not running through the skill (e.g. CI), you can drive the same two commands manually and supply your own `semantic-results.jsonl`:
+
+```bash
+codebeacon scan .
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+
+# now write .codebeacon/semantic-results.jsonl yourself; each line is:
+#   {"task_id":"...", "source_node_id":"...", "edges":[
+#     {"target_name":"UserService","relation":"references","confidence_score":0.7}
+#   ]}
+
+codebeacon semantic-apply --dir .codebeacon
+```
+
+### Opt out
+
+Pass `--no-semantic` (or `--wiki-only`, or `--list-only`) when invoking the skill to skip the AI step entirely. The structured-comment layer still runs when you pass `--semantic` to `scan` / `sync`.
+
+---
+
 ## Visual Exploration
 
 Every scan writes two self-contained HTML files alongside `beacon.json`:
@@ -425,7 +508,9 @@ wave:
   max_parallel: 5              # parallel threads
 
 semantic:
-  enabled: false               # override with --semantic flag
+  enabled: false               # structured-comment extraction; override with --semantic.
+                               # AI-semantic does NOT live here — it is invoked by the
+                               # /codebeacon skill, see "AI-Semantic Enrichment" above.
 
 deep_dive: false               # set to true to generate per-project outputs
 ```
@@ -487,13 +572,13 @@ codebeacon is not a replacement for either tool — it's the union of what both
 
 ## Privacy & Security
 
-All processing is local. Your source code never leaves your machine.
+All AST processing is local. Your source code never leaves your machine when you run codebeacon directly.
 
 - Tree-sitter AST parsing runs entirely in-process
 - No telemetry, no analytics, no network calls during normal operation
-- The `--semantic` flag (disabled by default) activates two extraction modes:
-  1. **Structured comment parsing** (no LLM required) — infers cross-references from Javadoc (`@see`, `{@link}`), Python docstrings (`:class:`, `:func:`), and JSDoc (`@see`, `@param` types)
-  2. **LLM inference** (optional) — when `ANTHROPIC_API_KEY` is set, sends code excerpts to the Claude API for deeper relationship inference; only enable it explicitly
+- The CLI **never calls an LLM provider on its own** — codebeacon ships no API client, no key handling, no model name
+- `--semantic` activates **structured-comment parsing only** (Javadoc `@see` / `{@link}`, JSDoc `@see` / `@param` types, Python `:class:` / `:func:` / `See Also`). Fully local.
+- **AI-semantic** (the deeper LLM-driven layer) is invoked by the `/codebeacon` Claude Code skill. The agent reads `semantic-tasks.jsonl`, runs the analysis under whatever model the user already picked, and writes `semantic-results.jsonl`. The Python CLI only prepares the task batch and merges the results — it has no idea which model was used. Pass `--no-semantic` in the skill to skip the LLM step entirely.
 
 ---
 

{codebeacon-0.3.1 → codebeacon-0.3.3}/README.de.md

@@ -241,7 +241,10 @@ wave:
   max_parallel: 5              # parallele Threads
 
 semantic:
-  enabled: false               # mit --semantic überschreiben
+  enabled: false               # nur strukturierte Kommentaranalyse;
+                               # mit --semantic überschreiben. AI-semantik lebt NICHT
+                               # hier — sie wird vom /codebeacon-Skill
+                               # (= laufender Agent) ausgelöst.
 
 deep_dive: false               # auf true setzen für Pro-Projekt-Ausgabe
 ```
@@ -359,7 +362,7 @@ Java, Kotlin, Python, JavaScript, TypeScript, Go, Ruby, PHP, C#, Rust, Swift, HT
 codebeacon scan .                         # aktuelles Verzeichnis
 codebeacon scan . --update                # inkrementell: nur geänderte Dateien
 codebeacon scan . --wiki-only             # Extraktion überspringen, Wiki/Obsidian/Kontext aus vorhandenem beacon.json regenerieren
-codebeacon scan . --semantic              # LLM-semantische Extraktion
+codebeacon scan . --semantic              # Extraktion strukturierter Kommentar-Referenzen (Javadoc/JSDoc/docstring)
 codebeacon scan . --list-only             # nur Frameworks erkennen
 codebeacon scan /workspace --deep-dive    # Pro-Projekt- + kombinierte Workspace-Ausgabe
 
@@ -374,10 +377,69 @@ codebeacon path <Quelle> <Ziel> [--dir .codebeacon]          # kürzester Abhän
 codebeacon hook install [path]            # Merge-Driver + Post-Commit-Inkrement-Rebuild installieren
 codebeacon merge-driver <base> <cur> <other>  # von git nach `hook install` aufgerufen; Union-Merge von beacon.json
 
+# AI-semantische Anreicherung (LLM macht der Agent, codebeacon nur die Buchführung)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
+                                          # spielt vorhandenes Archiv wieder auf das frische
+                                          # beacon.json an und gibt Aufgaben nur für NEUE
+                                          # Kandidaten aus (god-node-Ordner + unaufgelöste Ziele)
+codebeacon semantic-apply   [--dir .codebeacon]
+                                          # mergt .codebeacon/semantic-results.jsonl als
+                                          # INFERRED references-Kanten in beacon.json,
+                                          # hängt an .codebeacon/semantic/original.jsonl an,
+                                          # räumt Pending-Dateien auf und regeneriert
+                                          # wiki/obsidian/Kontextkarte
+
 codebeacon serve [--dir .codebeacon]      # MCP-Server starten (stdio)
 codebeacon install                        # Claude-Code-Skill installieren
+codebeacon upgrade                        # pip-Upgrade + ~/.claude/skills/codebeacon/SKILL.md aktualisieren
+                                          # (`--force` falls editable-Installation)
+```
+
+---
+
+## AI-semantische Anreicherung (via `/codebeacon`-Skill)
+
+Tree-sitter-Parsing findet, was im AST steht. **AI-semantik** findet, was nur in den *Kommentaren* lebt — das `@see UserService` in einer Javadoc, das `:class:`OrderRepository`` in einer Python-Docstring, die vertraglichen Referenzen neben einem Route-Handler. codebeacon liefert dafür zwei Schichten:
+
+| Schicht | Flag | Kosten | Was sie erfasst |
+|---|---|---|---|
+| Strukturierte Kommentaranalyse | `--semantic` | kostenlos, lokal, kein LLM | Javadoc `@see` / `{@link}`, JSDoc `@see` / `@param`-Typen, Python `:class:` / `:func:` / `See Also` |
+| **AI-semantik** | automatisch im `/codebeacon`-Skill | nutzt das aktuelle Modell des Agenten — **kein extra API-Schlüssel** | nicht aufgelöste Klassen-/Typ-/Service-Referenzen, die Regex nicht findet (freier Prosa, indirekte Erwähnungen, reine Typ-Hinweise) |
+
+Das CLI selbst **ruft niemals einen LLM-Anbieter auf**. Die AI-semantik-Schicht gehört bewusst dem **laufenden Agenten** innerhalb des `/codebeacon` Claude-Code-Skills — so wird die Modellwahl des Nutzers (Opus / Sonnet / Haiku / etc.) respektiert, und codebeacon braucht weder `ANTHROPIC_API_KEY` noch irgendeine Cloud-Konfiguration.
+
+### Wie es läuft
+
+Wenn Sie `/codebeacon` in Claude Code aufrufen:
+
+1. `scan` / `sync` baut `beacon.json` aus dem AST (kein LLM-Aufruf).
+2. `codebeacon semantic-prepare` spielt das frühere Archiv wieder auf den frischen Graphen ein und schreibt dann `.codebeacon/semantic-tasks.jsonl` mit **nur neuen Kandidaten** — hochbewertete Dateien (Kanten zu nicht aufgelösten Zielen + god-node-Ordner), die noch nie verarbeitet wurden.
+3. Der Skill iteriert die Tasks-Datei. Für jede Zeile liest der Agent (mit dem Modell der aktuellen Sitzung) das `excerpt`-Feld und liefert inline gefolgerte References. Ergebnisse werden in `.codebeacon/semantic-results.jsonl` geschrieben.
+4. `codebeacon semantic-apply` mergt die Ergebnisse als `INFERRED references`-Kanten in `beacon.json`, **hängt sie an `.codebeacon/semantic/original.jsonl`** (das dauerhafte Archiv) an, räumt die Pending-Dateien auf und regeneriert Wiki + Obsidian + Kontextkarte.
+5. Beim nächsten Scan: `semantic-prepare` rehydriert das Archiv auf den frisch gebauten Graphen (damit historische Inferenzen nicht durch ein erneutes Scannen verschwinden) und gibt eine Tasks-Datei mit **nur den seit dem letzten Archiv neu entdeckten Kandidaten** aus. Bereits verarbeitete Dateien werden per `task_id` (SHA1 von `file_path|node_id`) übersprungen.
+
+Das ergibt inkrementelle, idempotente Anreicherung: der Agent analysiert dieselbe Datei nie zweimal, und das angesammelte AI-Signal überlebt jeden Rescan.
+
+### Direkte CLI-Nutzung
+
+Wenn Sie nicht über den Skill gehen (z. B. CI), können Sie dieselben zwei Befehle manuell ausführen und Ihr eigenes `semantic-results.jsonl` liefern:
+
+```bash
+codebeacon scan .
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+
+# jetzt selbst .codebeacon/semantic-results.jsonl schreiben; jede Zeile:
+#   {"task_id":"...", "source_node_id":"...", "edges":[
+#     {"target_name":"UserService","relation":"references","confidence_score":0.7}
+#   ]}
+
+codebeacon semantic-apply --dir .codebeacon
 ```
 
+### Deaktivieren
+
+Übergeben Sie `--no-semantic` (oder `--wiki-only`, oder `--list-only`) beim Aufruf des Skills, um den AI-Schritt komplett zu überspringen. Die strukturierte Kommentaranalyse läuft weiterhin, wenn Sie `--semantic` an `scan` / `sync` übergeben.
+
 ---
 
 ## Vergleich
@@ -408,11 +470,11 @@ codebeacon install                        # Claude-Code-Skill installieren
 
 ## Datenschutz und Sicherheit
 
-Alle Verarbeitung erfolgt lokal. Ihr Quellcode verlässt niemals Ihren Rechner. Keine Telemetrie, keine Netzwerkaufrufe im normalen Betrieb.
+Die gesamte AST-Verarbeitung läuft lokal. Wenn Sie codebeacon direkt aufrufen, verlässt Ihr Quellcode niemals Ihren Rechner. Keine Telemetrie, keine Netzwerkaufrufe im normalen Betrieb.
 
-- Das Flag `--semantic` (standardmäßig deaktiviert) aktiviert zwei Extraktionsmodi:
-  1. **Strukturierte Kommentaranalyse** (kein LLM erforderlich) — leitet Kreuzreferenzen aus Javadoc (`@see`, `{@link}`), Python-Docstrings (`:class:`, `:func:`) und JSDoc (`@see`, `@param`-Typen) ab
-  2. **LLM-Inferenz** (optional) — bei gesetztem `ANTHROPIC_API_KEY` werden Code-Ausschnitte an die Claude-API gesendet; nur bei expliziter Aktivierung verwenden
+- Die CLI selbst **ruft niemals einen LLM-Anbieter auf** — das codebeacon-Paket enthält weder API-Client, noch Schlüsselverwaltung, noch Modellnamen.
+- `--semantic` aktiviert **ausschließlich die strukturierte Kommentaranalyse** (Javadoc `@see` / `{@link}`, JSDoc `@see` / `@param`-Typen, Python `:class:` / `:func:` / `See Also`). Vollständig lokal.
+- **AI-semantik** (die tiefere LLM-Schicht) wird vom `/codebeacon` Claude-Code-Skill ausgelöst. Der Agent liest `semantic-tasks.jsonl`, führt die Analyse mit dem **Modell der laufenden Sitzung** aus und schreibt `semantic-results.jsonl`. Die Python-CLI bereitet nur das Aufgaben-Batch vor und mergt die Ergebnisse — sie weiß nicht einmal, welches Modell verwendet wurde. Übergeben Sie `--no-semantic` an den Skill, um den LLM-Schritt vollständig zu überspringen.
 
 ---
 

{codebeacon-0.3.1 → codebeacon-0.3.3}/README.es.md

@@ -240,7 +240,9 @@ wave:
   max_parallel: 5              # hilos paralelos
 
 semantic:
-  enabled: false               # sobrescribir con --semantic
+  enabled: false               # solo extracción de comentarios estructurados;
+                               # --semantic lo activa. El AI-semántico NO vive aquí:
+                               # lo dispara el skill /codebeacon (= el agente en ejecución).
 
 deep_dive: false               # establecer true para salida por proyecto
 ```
@@ -358,7 +360,7 @@ Los parsers de Java, Kotlin, Python, JavaScript, TypeScript, Go, Ruby, PHP, C#,
 codebeacon scan .                         # directorio actual
 codebeacon scan . --update                # incremental: solo archivos modificados
 codebeacon scan . --wiki-only             # saltar extracción, regenerar wiki/obsidian/contexto desde beacon.json existente
-codebeacon scan . --semantic              # extracción semántica con LLM
+codebeacon scan . --semantic              # extracción de referencias de comentarios estructurados (Javadoc/JSDoc/docstring)
 codebeacon scan . --list-only             # solo detectar frameworks
 codebeacon scan /workspace --deep-dive    # salida por proyecto + workspace combinado
 
@@ -373,10 +375,69 @@ codebeacon path <origen> <destino> [--dir .codebeacon]       # ruta más corta d
 codebeacon hook install [path]            # instala merge driver + hook post-commit incremental
 codebeacon merge-driver <base> <cur> <other>  # invocado por git tras `hook install`; union-merge de beacon.json
 
+# Enriquecimiento AI-semántico (el LLM lo ejecuta el agente, codebeacon lleva la contabilidad)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
+                                          # rehidrata el archivo histórico sobre el nuevo beacon.json
+                                          # y emite tareas solo para candidatos NUEVOS
+                                          # (carpetas god-node + objetivos no resueltos)
+codebeacon semantic-apply   [--dir .codebeacon]
+                                          # fusiona .codebeacon/semantic-results.jsonl como
+                                          # aristas INFERRED references en beacon.json,
+                                          # añade al archivo .codebeacon/semantic/original.jsonl,
+                                          # limpia los archivos pendientes y regenera
+                                          # wiki/obsidian/mapa de contexto
+
 codebeacon serve [--dir .codebeacon]      # servidor MCP (stdio)
 codebeacon install                        # instalar skill de Claude Code
+codebeacon upgrade                        # pip upgrade + refrescar ~/.claude/skills/codebeacon/SKILL.md
+                                          # (use `--force` si está instalado en modo editable)
+```
+
+---
+
+## Enriquecimiento AI-semántico (mediante el skill `/codebeacon`)
+
+El análisis con tree-sitter encuentra lo que está en el AST. **AI-semántico** encuentra lo que vive sólo en los *comentarios* — el `@see UserService` en un Javadoc, el `:class:`OrderRepository`` en una docstring de Python, las referencias contractuales documentadas junto a un handler de ruta. codebeacon ofrece dos capas para esto:
+
+| Capa | Flag | Coste | Qué captura |
+|---|---|---|---|
+| Análisis de comentarios estructurados | `--semantic` | gratis, local, sin LLM | Javadoc `@see` / `{@link}`, JSDoc `@see` / tipos de `@param`, Python `:class:` / `:func:` / `See Also` |
+| **AI-semántico** | automático en el skill `/codebeacon` | usa el modelo actual del agente — **sin API key adicional** | referencias de clase/tipo/servicio que el regex no atrapa (texto libre, menciones indirectas, sólo hints de tipo) |
+
+El CLI por sí mismo **nunca llama a un LLM**. La capa AI-semántica es propiedad intencional del **agente en ejecución** dentro del skill `/codebeacon` de Claude Code — así se respeta el modelo elegido por el usuario (Opus / Sonnet / Haiku / lo que sea) y codebeacon nunca necesita `ANTHROPIC_API_KEY` ni configuración en la nube.
+
+### Cómo funciona
+
+Cuando invocas `/codebeacon` en Claude Code:
+
+1. `scan` / `sync` construye `beacon.json` desde el AST (sin LLM).
+2. `codebeacon semantic-prepare` reaplica el archivo histórico sobre el grafo nuevo y luego escribe `.codebeacon/semantic-tasks.jsonl` con **sólo los candidatos nuevos** — archivos con puntuación alta (aristas a objetivos no resueltos + carpetas god-node) que nunca se han procesado.
+3. El skill itera sobre el archivo de tareas. Por cada línea, el agente (usando el modelo de su sesión actual) lee el campo `excerpt` y devuelve referencias inferidas en línea. Los resultados se escriben en `.codebeacon/semantic-results.jsonl`.
+4. `codebeacon semantic-apply` mezcla los resultados como aristas `INFERRED references` en `beacon.json`, **los anexa a `.codebeacon/semantic/original.jsonl`** (el archivo durable), limpia los ficheros pendientes y regenera wiki + obsidian + mapa de contexto.
+5. En la próxima ejecución: `semantic-prepare` rehidrata el archivo sobre el grafo recién construido (para que las inferencias históricas no desaparezcan en una nueva exploración) y emite un fichero de tareas con **sólo candidatos nuevos** desde la última actualización del archivo. Los archivos ya procesados se omiten vía `task_id` (SHA1 de `file_path|node_id`).
+
+Esto da enriquecimiento incremental e idempotente: el agente nunca reanaliza el mismo archivo dos veces, y la señal AI acumulada sobrevive a cada re-escaneo.
+
+### Uso directo del CLI
+
+Si no usas el skill (p. ej. en CI), puedes ejecutar las mismas dos órdenes manualmente y suministrar tu propio `semantic-results.jsonl`:
+
+```bash
+codebeacon scan .
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+
+# ahora escribe tú mismo .codebeacon/semantic-results.jsonl; cada línea:
+#   {"task_id":"...", "source_node_id":"...", "edges":[
+#     {"target_name":"UserService","relation":"references","confidence_score":0.7}
+#   ]}
+
+codebeacon semantic-apply --dir .codebeacon
 ```
 
+### Desactivar
+
+Pasa `--no-semantic` (o `--wiki-only`, o `--list-only`) al invocar el skill para saltarte por completo el paso AI. La capa de comentarios estructurados sigue funcionando cuando pasas `--semantic` a `scan` / `sync`.
+
 ---
 
 ## Comparativa
@@ -407,11 +468,11 @@ codebeacon install                        # instalar skill de Claude Code
 
 ## Privacidad y seguridad
 
-Todo el procesamiento es local. El código fuente nunca sale de su máquina. Sin telemetría ni llamadas de red durante el uso normal.
+Todo el procesamiento AST es local. Al ejecutar codebeacon directamente, su código fuente nunca sale de su máquina. Sin telemetría ni llamadas de red durante el uso normal.
 
-- La bandera `--semantic` (deshabilitada por defecto) activa dos modos de extracción:
-  1. **Análisis de comentarios estructurados** (sin LLM) — infiere referencias cruzadas de Javadoc (`@see`, `{@link}`), docstrings de Python (`:class:`, `:func:`) y JSDoc (`@see`, tipos de `@param`)
-  2. **Inferencia LLM** (opcional) — si `ANTHROPIC_API_KEY` está configurado, envía fragmentos de código a la API de Claude para inferencia de relaciones más profunda; úselo solo si lo habilita explícitamente
+- El propio CLI **nunca llama a un proveedor LLM** — el paquete codebeacon no incluye cliente API, ni manejo de claves, ni nombre de modelo.
+- `--semantic` activa **solo el análisis de comentarios estructurados** (Javadoc `@see` / `{@link}`, JSDoc `@see` / tipos de `@param`, Python `:class:` / `:func:` / `See Also`). 100 % local.
+- **AI-semántico** (la capa LLM más profunda) lo dispara el skill `/codebeacon` de Claude Code. El agente lee `semantic-tasks.jsonl`, ejecuta el análisis con el **modelo de su sesión actual** y escribe `semantic-results.jsonl`. El CLI Python solo prepara el lote de tareas y fusiona los resultados; ni siquiera sabe qué modelo se utilizó. Pase `--no-semantic` al skill para omitir por completo el paso LLM.
 
 ---
 

{codebeacon-0.3.1 → codebeacon-0.3.3}/README.fr.md

@@ -240,7 +240,10 @@ wave:
   max_parallel: 5              # threads parallèles
 
 semantic:
-  enabled: false               # écraser avec --semantic
+  enabled: false               # uniquement l'extraction de commentaires structurés ;
+                               # activée par --semantic. L'AI-sémantique N'EST PAS ici :
+                               # elle est déclenchée par le skill /codebeacon
+                               # (= l'agent en cours d'exécution).
 
 deep_dive: false               # mettre à true pour une sortie par projet
 ```
@@ -358,7 +361,7 @@ Les parsers Java, Kotlin, Python, JavaScript, TypeScript, Go, Ruby, PHP, C#, Rus
 codebeacon scan .                         # répertoire courant
 codebeacon scan . --update                # incrémental : fichiers modifiés seulement
 codebeacon scan . --wiki-only             # ignorer la ré-extraction, régénérer wiki/obsidian/contexte depuis beacon.json existant
-codebeacon scan . --semantic              # extraction sémantique LLM
+codebeacon scan . --semantic              # extraction des références dans commentaires structurés (Javadoc/JSDoc/docstring)
 codebeacon scan . --list-only             # détecter les frameworks uniquement
 codebeacon scan /workspace --deep-dive    # sortie par projet + workspace combiné
 
@@ -373,10 +376,69 @@ codebeacon path <source> <cible> [--dir .codebeacon]       # chemin de dépendan
 codebeacon hook install [path]            # installer merge driver + hook post-commit incrémental
 codebeacon merge-driver <base> <cur> <other>  # invoqué par git après `hook install` ; union-merge de beacon.json
 
+# Enrichissement AI-sémantique (le LLM est exécuté par l'agent, codebeacon tient la comptabilité)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
+                                          # réapplique l'archive existante au beacon.json frais
+                                          # puis n'émet de tâches que pour les candidats NEUFS
+                                          # (dossiers god-node + cibles non résolues)
+codebeacon semantic-apply   [--dir .codebeacon]
+                                          # fusionne .codebeacon/semantic-results.jsonl comme
+                                          # arêtes INFERRED references dans beacon.json,
+                                          # ajoute à l'archive .codebeacon/semantic/original.jsonl,
+                                          # nettoie les fichiers en attente et régénère
+                                          # wiki/obsidian/carte de contexte
+
 codebeacon serve [--dir .codebeacon]      # serveur MCP (stdio)
 codebeacon install                        # installer le skill Claude Code
+codebeacon upgrade                        # pip upgrade + rafraîchir ~/.claude/skills/codebeacon/SKILL.md
+                                          # (`--force` si installé en mode éditable)
+```
+
+---
+
+## Enrichissement AI-sémantique (via le skill `/codebeacon`)
+
+L'analyse tree-sitter trouve ce qui est dans l'AST. **AI-sémantique** trouve ce qui ne vit que dans les *commentaires* — le `@see UserService` dans une Javadoc, le `:class:`OrderRepository`` dans une docstring Python, les références contractuelles documentées à côté d'un handler de route. codebeacon propose deux couches pour cela :
+
+| Couche | Flag | Coût | Ce qu'elle capture |
+|---|---|---|---|
+| Analyse de commentaires structurés | `--semantic` | gratuit, local, sans LLM | Javadoc `@see` / `{@link}`, JSDoc `@see` / types `@param`, Python `:class:` / `:func:` / `See Also` |
+| **AI-sémantique** | auto dans le skill `/codebeacon` | utilise le modèle courant de l'agent — **aucune clé API supplémentaire** | références de classe/type/service que la regex ne peut pas attraper (prose libre, mentions indirectes, hints de type uniquement) |
+
+Le CLI lui-même **n'appelle jamais un LLM**. La couche AI-sémantique est intentionnellement **propriété de l'agent en cours d'exécution** à l'intérieur du skill Claude Code `/codebeacon` — ainsi le modèle choisi par l'utilisateur (Opus / Sonnet / Haiku / autre) est respecté et codebeacon n'a jamais besoin de `ANTHROPIC_API_KEY` ni d'aucune configuration cloud.
+
+### Comment ça tourne
+
+Quand vous invoquez `/codebeacon` dans Claude Code :
+
+1. `scan` / `sync` construit `beacon.json` à partir de l'AST (aucun appel LLM).
+2. `codebeacon semantic-prepare` réapplique l'archive précédente au graphe frais puis écrit `.codebeacon/semantic-tasks.jsonl` contenant **uniquement les nouveaux candidats** — fichiers à score élevé (arêtes vers cibles non résolues + dossiers god-node) qui n'ont jamais été traités.
+3. Le skill itère sur le fichier de tâches. Pour chaque ligne, l'agent (en utilisant le modèle de sa session courante) lit le champ `excerpt` et renvoie inline les références inférées. Les résultats sont écrits dans `.codebeacon/semantic-results.jsonl`.
+4. `codebeacon semantic-apply` fusionne les résultats en arêtes `INFERRED references` dans `beacon.json`, **les ajoute à `.codebeacon/semantic/original.jsonl`** (l'archive durable), nettoie les fichiers en attente et régénère wiki + obsidian + carte de contexte.
+5. Au prochain scan : `semantic-prepare` réhydrate l'archive sur le graphe fraîchement construit (pour que les inférences historiques ne disparaissent pas lors d'un re-scan) et n'émet dans le fichier de tâches que **les candidats nouvellement découverts** depuis la dernière mise à jour de l'archive. Les fichiers déjà traités sont sautés via `task_id` (SHA1 de `file_path|node_id`).
+
+Vous obtenez ainsi un enrichissement incrémental et idempotent : l'agent ne réanalyse jamais deux fois le même fichier et le signal AI accumulé survit à chaque re-scan.
+
+### Utilisation directe du CLI
+
+Si vous n'utilisez pas le skill (par ex. en CI), vous pouvez piloter les deux mêmes commandes manuellement et fournir votre propre `semantic-results.jsonl` :
+
+```bash
+codebeacon scan .
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+
+# écrivez vous-même .codebeacon/semantic-results.jsonl ; chaque ligne :
+#   {"task_id":"...", "source_node_id":"...", "edges":[
+#     {"target_name":"UserService","relation":"references","confidence_score":0.7}
+#   ]}
+
+codebeacon semantic-apply --dir .codebeacon
 ```
 
+### Désactivation
+
+Passez `--no-semantic` (ou `--wiki-only`, ou `--list-only`) lors de l'invocation du skill pour sauter complètement l'étape AI. La couche de commentaires structurés fonctionne toujours quand vous passez `--semantic` à `scan` / `sync`.
+
 ---
 
 ## Comparaison
@@ -407,11 +469,11 @@ codebeacon install                        # installer le skill Claude Code
 
 ## Confidentialité et sécurité
 
-Tout le traitement est local. Le code source ne quitte jamais votre machine. Aucune télémétrie ni appel réseau pendant le fonctionnement normal.
+Tout le traitement AST est local. Lorsque vous lancez codebeacon directement, le code source ne quitte jamais votre machine. Aucune télémétrie ni appel réseau pendant le fonctionnement normal.
 
-- L'option `--semantic` (désactivée par défaut) active deux modes d'extraction :
-  1. **Analyse des commentaires structurés** (sans LLM) — déduit des références croisées depuis Javadoc (`@see`, `{@link}`), les docstrings Python (`:class:`, `:func:`) et JSDoc (`@see`, types de `@param`)
-  2. **Inférence LLM** (optionnel) — si `ANTHROPIC_API_KEY` est défini, envoie des extraits de code à l'API Claude pour une inférence de relations plus approfondie ; à n'activer qu'explicitement
+- Le CLI lui-même **n'appelle jamais un fournisseur LLM** — le paquet codebeacon ne contient aucun client API, ni gestion de clé, ni nom de modèle.
+- `--semantic` n'active que **l'analyse des commentaires structurés** (Javadoc `@see` / `{@link}`, JSDoc `@see` / types `@param`, Python `:class:` / `:func:` / `See Also`). 100 % local.
+- **AI-sémantique** (la couche LLM plus profonde) est déclenchée par le skill `/codebeacon` de Claude Code. L'agent lit `semantic-tasks.jsonl`, exécute l'analyse avec **le modèle de sa session courante** et écrit `semantic-results.jsonl`. Le CLI Python prépare uniquement le lot de tâches et fusionne les résultats — il ne sait même pas quel modèle a été utilisé. Passez `--no-semantic` au skill pour ignorer entièrement l'étape LLM.
 
 ---
 

{codebeacon-0.3.1 → codebeacon-0.3.3}/README.ja.md

@@ -266,7 +266,7 @@ codebeacon scan /workspace                # ワークスペースルート (マ
 codebeacon scan . --update                # インクリメンタル：変更ファイルのみ再抽出
 codebeacon scan . --wiki-only             # 再抽出をスキップし、既存の beacon.json からウィキ/obsidian/コンテキストマップを再生成
 codebeacon scan . --obsidian-dir <path>   # Obsidian Vault をカスタム場所に書き込み
-codebeacon scan . --semantic              # LLM セマンティック抽出を有効化
+codebeacon scan . --semantic              # 構造化コメント参照（Javadoc/JSDoc/docstring）の抽出を有効化
 codebeacon scan . --list-only             # フレームワーク検出のみ、抽出なし
 codebeacon scan /workspace --deep-dive    # プロジェクト別 + 統合ワークスペース出力
 
@@ -284,11 +284,71 @@ codebeacon path <source> <target> [--dir .codebeacon]     # 最短依存関係
 codebeacon hook install [path]            # merge driver + post-commit インクリメンタル再ビルドのインストール
 codebeacon merge-driver <base> <cur> <other>  # `hook install` 後 git が呼び出す；beacon.json を union マージ
 
+# AI-セマンティック補強 (LLM はエージェント、整合性管理は codebeacon)
+codebeacon semantic-prepare [--dir .codebeacon] [--max-tasks N]
+                                          # 過去のアーカイブを fresh beacon.json に再適用後、
+                                          # 未処理の NEW 候補 (god-node フォルダ + unresolved
+                                          # ターゲット) のみを .codebeacon/semantic-tasks.jsonl
+                                          # に書き出す
+codebeacon semantic-apply   [--dir .codebeacon]
+                                          # .codebeacon/semantic-results.jsonl を INFERRED
+                                          # references エッジとして beacon.json に統合し、
+                                          # .codebeacon/semantic/original.jsonl アーカイブに
+                                          # 追記、pending ファイルを掃除し、
+                                          # wiki/obsidian/コンテキストマップを再生成
+
 # インテグレーション
 codebeacon serve [--dir .codebeacon]      # MCP サーバー起動 (stdio)
 codebeacon install                        # Claude Code スキルをインストール
+codebeacon upgrade                        # pip で更新 + ~/.claude/skills/codebeacon/SKILL.md を再生成
+                                          # (`--force` で editable インストール時も強制実行)
+```
+
+---
+
+## AI-セマンティック補強（`/codebeacon` スキル経由）
+
+tree-sitter パースは AST に**ある**ものを見つけます。**AI-セマンティック**は**コメントのみにある**ものを見つけます — Javadoc 中の `@see UserService`、Python docstring 中の `:class:`OrderRepository``、ルートハンドラの横に書かれた契約上の参照など。codebeacon はこのために 2 層を提供します：
+
+| レイヤー | フラグ | コスト | 捕捉対象 |
+|---|---|---|---|
+| 構造化コメントパース | `--semantic` | 無料、ローカル、LLM 不要 | Javadoc `@see` / `{@link}`、JSDoc `@see` / `@param` 型、Python `:class:` / `:func:` / `See Also` |
+| **AI-セマンティック** | `/codebeacon` スキルで自動 | エージェントの**現在のモデル**を使用 — **API キー不要** | 正規表現が捕えられないクラス／型／サービス参照（自由文、間接的言及、型ヒントのみ等） |
+
+CLI 自体は LLM API 呼び出しを **行いません**。AI-セマンティック層は意図的に `/codebeacon` Claude Code スキル内で**実行中のエージェントが所有**します — そうすることでユーザーが選んだモデル（Opus / Sonnet / Haiku など）がそのまま使われ、codebeacon 自体は `ANTHROPIC_API_KEY` もクラウド設定も必要としません。
+
+### 実行フロー
+
+Claude Code で `/codebeacon` を呼び出すと：
+
+1. `scan` / `sync` が AST から `beacon.json` を構築（LLM 呼び出しなし）。
+2. `codebeacon semantic-prepare` が過去のアーカイブを新しいグラフに再適用後、**新しい候補のみ**を含む `.codebeacon/semantic-tasks.jsonl` を書き出します — スコアが高い（unresolved ターゲットエッジ + god-node フォルダ）かつ一度も処理されたことのないファイル。
+3. スキルが tasks ファイルを順次処理。各行についてエージェント（現在セッションのモデル）が `excerpt` フィールドを読み、推論された references をインラインで返します。結果は `.codebeacon/semantic-results.jsonl` に書き込まれます。
+4. `codebeacon semantic-apply` が結果を `INFERRED references` エッジとして `beacon.json` にマージし、**`.codebeacon/semantic/original.jsonl`**（永続アーカイブ）に追記、pending ファイルを掃除、wiki + obsidian + コンテキストマップを再生成します。
+5. 次回スキャン時：`semantic-prepare` がアーカイブを新グラフに再適用（再スキャンで過去の推論が失われないように）し、最後のアーカイブ以降の**新しく発見された候補のみ**を tasks ファイルに含めます。処理済みファイルは `task_id`（SHA1 of `file_path|node_id`）でスキップ。
+
+→ 増分かつ冪等の補強。同じファイルを二度分析せず、蓄積された AI シグナルは毎回の再スキャンを生き延びます。
+
+### 直接 CLI 使用
+
+スキルを介さず（例：CI）に同じ 2 コマンドで手動運用し、`semantic-results.jsonl` を自分で書くこともできます：
+
+```bash
+codebeacon scan .
+codebeacon semantic-prepare --dir .codebeacon --max-tasks 50
+
+# 次に .codebeacon/semantic-results.jsonl を自分で書く；各行：
+#   {"task_id":"...", "source_node_id":"...", "edges":[
+#     {"target_name":"UserService","relation":"references","confidence_score":0.7}
+#   ]}
+
+codebeacon semantic-apply --dir .codebeacon
 ```
 
+### オプトアウト
+
+スキル呼び出し時に `--no-semantic`（または `--wiki-only`、`--list-only`）を渡せば AI ステップは完全にスキップされます。`--semantic` を `scan` / `sync` に渡すと構造化コメント層は引き続き動作します。
+
 ---
 
 ## ビジュアル探索
@@ -364,7 +424,10 @@ wave:
   max_parallel: 5              # 並列スレッド数
 
 semantic:
-  enabled: false               # --semantic フラグでオーバーライド
+  enabled: false               # 構造化コメント抽出のみ。--semantic で上書き。
+                               # AI-セマンティックはこのキーに無い ―
+                               # /codebeacon スキル (= 実行中のエージェント)
+                               # が trigger する。
 
 deep_dive: false               # true にすると各プロジェクト別出力を生成
 ```
@@ -426,13 +489,13 @@ codebeacon は両ツールの代替ではなく統合です — 共有の抽出
 
 ## プライバシーとセキュリティ
 
-すべての処理はローカルで行われます。ソースコードは外部に送信されません。
+AST 処理はすべてローカルで実行されます。codebeacon を直接呼び出す限り、ソースコードはマシンの外に出ません。
 
 - tree-sitter AST パースはプロセス内でのみ実行
 - テレメトリ、分析、通常操作中のネットワーク呼び出しなし
-- `--semantic` フラグ（デフォルト無効）は 2 つの抽出モードを有効化します：
-  1. **構造化コメント解析**（LLM 不要） — Javadoc（`@see`、`{@link}`）、Python ドキュメント文字列（`:class:`、`:func:`）、JSDoc（`@see`、`@param` 型）からクロスリファレンスを推論
-  2. **LLM 推論**（オプション） — `ANTHROPIC_API_KEY` が設定されている場合、Claude API にコードの抜粋を送信して深い関係推論を実行；明示的に有効化した場合のみ使用
+- CLI 自体は **LLM プロバイダーを一切呼び出しません** — codebeacon パッケージには API クライアントもキー処理もモデル名もありません
+- `--semantic` は **構造化コメントパースのみ** を有効化します（Javadoc `@see` / `{@link}`、JSDoc `@see` / `@param` 型、Python `:class:` / `:func:` / `See Also`）。完全ローカル。
+- **AI-セマンティック**（LLM ベースの深い推論層）は `/codebeacon` Claude Code スキルが起動します。エージェントが `semantic-tasks.jsonl` を読み、**現在セッションのモデル** で解析を実行して `semantic-results.jsonl` を書き戻します。Python CLI はタスクバッチの準備と結果の統合のみを担当し、どのモデルが使われたかすら知りません。スキル呼び出しに `--no-semantic` を渡せば LLM ステップは完全にスキップされます。
 
 ---