codebeacon 0.3.0__tar.gz → 0.3.2__tar.gz

{codebeacon-0.3.0 → codebeacon-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebeacon
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -96,6 +96,7 @@ Existing tools solve this partially. Route analyzers map your controllers but mi
 - **gitignore-style `.codebeaconignore`** — last-match-wins with `!` negation, dir patterns (`build/`), anchored patterns (`/secrets.txt`), trailing-whitespace rules
 - **Zero configuration** — auto-detects frameworks and languages; generates `codebeacon.yaml` for repeat runs
 - **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
 
 ---
 
@@ -183,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
@@ -242,11 +249,20 @@ 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
 ```
 
+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.
+
 ### MCP Server
 
 Run codebeacon as a persistent MCP server so any MCP-compatible client can query your knowledge graph directly.
@@ -318,14 +334,25 @@ 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
 
 # Config-driven mode
 codebeacon init [path]                    # auto-generate codebeacon.yaml
-codebeacon sync                           # run from codebeacon.yaml
+codebeacon sync                           # run from codebeacon.yaml (auto-appends new workspace projects)
 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
@@ -342,6 +369,51 @@ codebeacon install                        # install Claude Code skill
 
 ---
 
+## 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`:
@@ -423,7 +495,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
 ```
@@ -485,13 +559,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.0 → codebeacon-0.3.2}/README.de.md

@@ -55,6 +55,7 @@ Bestehende Tools lösen dieses Problem nur teilweise. Route-Analyzer erfassen Ih
 - **`.codebeaconignore` im gitignore-Stil** — last-match-wins mit `!`-Negation, Verzeichnis-Patterns (`build/`), verankerte Patterns (`/secrets.txt`), Trailing-Whitespace-Regeln
 - **Keine Konfiguration notwendig** — erkennt Frameworks und Sprachen automatisch; generiert `codebeacon.yaml` für Folgeläufe
 - **Deep-Dive-Modus** — `--deep-dive` erzeugt für jedes Sub-Projekt eigene `.codebeacon/` + `CLAUDE.md`; ein Update-Aufruf aus **beliebigem** Sub-Projekt-Ordner synchronisiert automatisch alle Projekte im Workspace
+- **Automatische Workspace-Wiedererkennung** — bei jedem `scan`/`sync` scannt codebeacon den Workspace erneut und hängt vor der Extraktion automatisch neue Projekte an die `codebeacon.yaml` an, sodass frisch hinzugefügte Sub-Projekte nicht unbemerkt übersprungen werden; `--no-rediscover` deaktiviert dies für handgepflegte Konfigurationen
 
 ---
 
@@ -240,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
 ```
@@ -358,12 +362,13 @@ 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
 
 codebeacon init [pfad]                    # codebeacon.yaml generieren
-codebeacon sync                           # von codebeacon.yaml ausführen
+codebeacon sync                           # von codebeacon.yaml ausführen (hängt neue Workspace-Projekte automatisch an)
+codebeacon sync --no-rediscover           # neue Projekte nicht automatisch anhängen (handgepflegter yaml-Modus)
 
 codebeacon query <Begriff> [--dir .codebeacon] [--limit N]   # Knoten per Label-Substring suchen
 codebeacon path <Quelle> <Ziel> [--dir .codebeacon]          # kürzester Abhängigkeitspfad
@@ -372,12 +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
 ```
 
 ---
 
+## 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
 
 | | codesight | graphify | **codebeacon** |
@@ -406,11 +468,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.0 → codebeacon-0.3.2}/README.es.md

@@ -55,6 +55,7 @@ Las herramientas existentes resuelven esto de forma parcial. Los analizadores de
 - **`.codebeaconignore` estilo gitignore** — last-match-wins con negación `!`, patrones de directorio (`build/`), patrones anclados (`/secrets.txt`), reglas de espacio final
 - **Cero configuración** — detecta frameworks y lenguajes automáticamente; genera `codebeacon.yaml` para ejecuciones posteriores
 - **Modo Deep Dive** — `--deep-dive` genera `.codebeacon/` + `CLAUDE.md` propios para cada sub-proyecto; ejecutar el comando de actualización desde **cualquier** sub-proyecto sincroniza automáticamente todos los proyectos del workspace
+- **Auto-redescubrimiento del workspace** — en cada `scan`/`sync`, codebeacon re-escanea el workspace y añade automáticamente al `codebeacon.yaml` los nuevos proyectos antes de extraer, de modo que los sub-proyectos recién añadidos nunca se omitan silenciosamente; usa `--no-rediscover` para optar por el modo de configuración curada manualmente
 
 ---
 
@@ -239,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
 ```
@@ -357,12 +360,13 @@ 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
 
 codebeacon init [ruta]                    # generar codebeacon.yaml
-codebeacon sync                           # ejecutar desde codebeacon.yaml
+codebeacon sync                           # ejecutar desde codebeacon.yaml (añade nuevos proyectos del workspace automáticamente)
+codebeacon sync --no-rediscover           # no añadir automáticamente nuevos proyectos (modo yaml curado a mano)
 
 codebeacon query <término> [--dir .codebeacon] [--limit N]   # buscar nodos por substring de etiqueta
 codebeacon path <origen> <destino> [--dir .codebeacon]       # ruta más corta de dependencias
@@ -371,12 +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
 ```
 
 ---
 
+## 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
 
 | | codesight | graphify | **codebeacon** |
@@ -405,11 +466,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.0 → codebeacon-0.3.2}/README.fr.md

@@ -55,6 +55,7 @@ Les outils existants ne résolvent ce problème qu'en partie. Les analyseurs de
 - **`.codebeaconignore` style gitignore** — last-match-wins avec négation `!`, patterns de répertoire (`build/`), patterns ancrés (`/secrets.txt`), règles sur espaces de fin
 - **Zéro configuration** — détecte automatiquement les frameworks et langages ; génère `codebeacon.yaml` pour les exécutions suivantes
 - **Mode Deep Dive** — `--deep-dive` génère un `.codebeacon/` + `CLAUDE.md` propre à chaque sous-projet ; une commande de mise à jour depuis **n'importe quel** sous-projet synchronise automatiquement tous les projets du workspace
+- **Redécouverte automatique du workspace** — à chaque `scan`/`sync`, codebeacon réanalyse le workspace et ajoute automatiquement les nouveaux projets au `codebeacon.yaml` avant l'extraction, de sorte que les sous-projets fraîchement ajoutés ne soient jamais oubliés en silence ; utilisez `--no-rediscover` pour conserver une configuration yaml gérée manuellement
 
 ---
 
@@ -239,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
 ```
@@ -357,12 +361,13 @@ 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é
 
 codebeacon init [chemin]                  # générer codebeacon.yaml
-codebeacon sync                           # exécuter depuis codebeacon.yaml
+codebeacon sync                           # exécuter depuis codebeacon.yaml (ajoute automatiquement les nouveaux projets du workspace)
+codebeacon sync --no-rediscover           # ne pas ajouter automatiquement les nouveaux projets (mode yaml géré manuellement)
 
 codebeacon query <terme> [--dir .codebeacon] [--limit N]   # rechercher des nœuds par sous-chaîne de label
 codebeacon path <source> <cible> [--dir .codebeacon]       # chemin de dépendances le plus court
@@ -371,12 +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
 ```
 
 ---
 
+## 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
 
 | | codesight | graphify | **codebeacon** |
@@ -405,11 +467,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.
 
 ---