# Workflow codebase e documentazione

`docs_codebase` e una capability MCP esclusivamente locale, metadata-only. Non e disponibile sul remote-server e non entra in Manifest, replica, delta, push, change-log o conflitti. Non proporla per un remote o una replica read-only.

## Inventory esplicito

1. `attach_codebase` collega una root canonica a uno shelf locale; non esegue uno scan implicito. `exclude[]` aggiunge esclusioni alle policy robuste di default.
2. `scan_codebase` esegue l'inventory incrementale di una source per nome o UUID; riferisci nel report discovered, unchanged, updated, tombstoned, excluded, skipped_symlinks ed errori non bloccanti.
3. `list_code_files` restituisce esclusivamente path relativo, dimensione, mtime, hash, UUID/versione e tombstone. Non richiedere, salvare o restituire contenuto sorgente.

Gli hash sono aggiornati solo per file nuovi o modificati; symlink esterni alla root o non risolvibili sono ignorati. Un file scomparso diventa tombstone e puo essere riattivato se riappare.

## Simboli e link documento-file

`extract_code_symbols` e esplicito e attualmente best-effort per JS/TS/MJS/CJS; usa `list_code_symbols` per il risultato. Non inferire supporto AST, ColdFusion, PHP o C#: M15/M16 sono fuori scope fino a nuova decisione.

Per il workflow umano consigliato:

1. inventaria con attach/scan;
2. usa `propose_document_code_links` soltanto come dry-run di review;
3. crea il collegamento confermato con `manage_document_code_links` `add`, relation allowlisted e rationale;
4. usa `list` per la verifica o `remove` per tombstonare il link.

Le relazioni sono `implemented_by`, `tested_by`, `configures`, `references`. I link sono manuali con certainty `manual`, hash snapshot dei due endpoint e provenance. `apply:true` nelle proposal e rifiutato: non aggirare questa review con scritture automatiche.

## Stale documentation

`detect_stale_docs` e un report read-only che calcola live l'hash del file e confronta gli snapshot del link manuale. Un file modificato con documento immutato produce issue `high`; un documento aggiornato dopo il link sopprime lo stale per quel link. File mancanti, esterni alla root o metadata legacy non validi sono `unverifiable`/warning, non errori globali.

Per una lettura puntuale usa `docs_navigation read_document` con `include_stale_warning:true`. L'opzione e opt-in e non deve cambiare le letture legacy prive di warning.