# Concept graph, pathfinding e neighborhood

Usa questa reference per esplorare connessioni tra documenti e concetti senza trasformare una lettura del grafo in una mutazione implicita.

## Concept graph

`docs_mindmap extract_concepts` analizza heading Markdown e tag dello shelf. Esegui prima il dry-run; con `apply:true` crea o riusa concept node per `normalized_label` e crea il link `document -> concept` `mentions` mancante. La convergenza e non distruttiva: non fondere o cancellare concept esistenti.

Per un link intenzionale usa `manage_concept_links` con `operation:add`, documento, concept e relazione; `remove` applica un tombstone e `list` e read-only. Le mutazioni sono rifiutate su repliche e remote-server.

I concetti presenti in Manifest V3/replica iniziale sono `snapshot_only`: dopo sync incrementale non affermare che siano allineati al remoto senza uno snapshot aggiornato.

## Traversal locale

Usa `docs_mindmap map_path` con `source` e `target`, oppure `map_neighborhood` con `center`. I riferimenti hanno forma `{ "type": "document", "uuid": "..." }`.

Il traversal e bidirezionale su `document_links` e `concept_links`; l'output conserva direzione e relazione originarie. Di default include manual, curated e inferred, ma esclude ambiguous. Imposta `include_ambiguous:true` solo quando il rumore e accettabile e rendilo esplicito nel report.

Mantieni i limiti bounded: `max_depth` default 4/max 8 e `max_nodes` default 50/max 200. Usa `output_format:"mermaid"` o `"both"` solo per visualizzazione; il JSON rimane l'output strutturato di riferimento. Nessun percorso entro il limite e un esito valido (`found:false`), non un errore.

## Lettura remota

Per non creare una replica usa `docs_remote map_remote_path` o `map_remote_neighborhood`, con `remote`, `remote_shelf_uuid` e gli stessi riferimenti/filtri locali. Il risultato e limitato al contenuto nello snapshot V3 esportato dallo shelf, quindi non dichiarare copertura cross-shelf oltre gli edge disponibili. Queste operazioni non cambiano replica, cursor, change-log, push o conflitti e dichiarano `concept_sync_mode:"snapshot_only"`.