second-brain-graph 0.1.0__tar.gz

second_brain_graph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lopax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

second_brain_graph-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# Ship the vendored 3D viewer assets in the source distribution (wheels already include them
+# via [tool.setuptools.package-data]). Without this, the sdist would omit ui/*.js and ui/*.html.
+include LICENSE
+include README.md
+include README.it.md
+include second_brain/py.typed
+recursive-include second_brain/ui *.html *.js

second_brain_graph-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: second-brain-graph
+Version: 0.1.0
+Summary: A living, always-fresh, low-token map of every project: files, links, areas and mechanics, with a navigable 3D view.
+Author-email: Lopax <lopax76@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lopax76/second-brain
+Project-URL: Repository, https://github.com/lopax76/second-brain
+Project-URL: Issues, https://github.com/lopax76/second-brain/issues
+Project-URL: Documentation, https://github.com/lopax76/second-brain#readme
+Keywords: knowledge-graph,memory,ai-agents,documentation,code-graph,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# Second Brain (SB)
+
+[![CI](https://github.com/lopax76/second-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/lopax76/second-brain/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-none-success.svg)](pyproject.toml)
+
+**A living, always-fresh, low-token map of every project** — files, links, areas and
+mechanics — that an AI assistant can **query** instead of re-reading everything, and that a
+human can explore in a navigable **3D graph**.
+
+🇮🇹 [Leggi in italiano →](README.it.md)
+
+> Not "another place to store stuff". It's the canonical, per-project picture that stays in
+> sync with your files so you never lose track: no forgotten pieces, no "we discussed that
+> three chats ago", no stale docs.
+
+![Second Brain 3D viewer — anonymized backbone of a real multi-project workspace](docs/assets/ui-suite.png)
+
+<sub>The offline 3D viewer on a real, multi-project workspace (names anonymized): nodes colored
+by type, grouped here by type, with a click-through detail panel.</sub>
+
+---
+
+## Why this exists
+
+A project gets more complex over time. Files drift, some go orphaned or quietly broken, the
+mental model of "what's where and how it connects" gets fuzzier, and an AI assistant **loses
+the thread between one chat and the next** — so every session starts by re-reading and
+re-searching files. That is slow, incomplete, and **burns tokens repeatedly** — and it only
+gets worse as the project grows.
+
+Second Brain builds the project's graph **once** and keeps it fresh incrementally (outside the
+model, at near-zero token cost). The assistant **queries** it and gets compact answers; a human
+opens the **3D view** and sees the whole project at a glance.
+
+It is **not a RAG system**: no embeddings, no vector store, no LLM needed to build the graph.
+It maps the *structural* relationships between files, which makes it complementary to RAG and
+purpose-built for one thing: **situational awareness at a very low token cost.**
+
+## What makes it different
+
+- **Read-only on your sources** — it indexes, it never modifies your files. Run it on anything
+  without risk.
+- **Files are the truth** — the graph is derived (in `.secondbrain/`) and always regenerable;
+  contents are never duplicated into it.
+- **Zero runtime dependencies** — the core runs on the Python standard library alone. No
+  conflicts, instant install, works in CI / containers / air-gapped boxes.
+- **Low token cost by design** — queries return ids, types, sizes and connections, never file
+  contents, so orienting an assistant costs a few hundred tokens, not tens of thousands.
+- **Anti-drift gate** — refuses to call the graph "fine" while something is stale, orphaned, or
+  broken.
+- **Offline 3D viewer** — the data is inlined and the 3D library is vendored next to the page;
+  the viewer works fully offline, no CDN, nothing for a script blocker to break.
+- **Optional MCP server** — exposes the same low-token queries to MCP-aware assistants, behind
+  an optional extra so the core stays dependency-free.
+
+## See it on a real project (anonymized)
+
+A **read-only** measurement on a mature, multi-repo project (identity withheld): ~1,684
+knowledge files across 17 top-level areas, indexed in **~1.3 s** (index `graph.json` = 0.91 MB).
+
+Three ways to answer the same four questions about the project — *what's here, list every
+recorded decision, which files are truncated/empty, the most-connected files* — in three
+separate clean chats:
+
+| Metric | NOTHING (manual) | TODAY (manual) | WITH Second Brain |
+|---|---|---|---|
+| Time | ~8.5 min | ~9 min | **~3–4 min** |
+| Working tokens | opaque | opaque | **~3–4k, self-measured** |
+| **Decisions found** | 112 (wrong) | 131 (wrong) | **117 (exact)** |
+| **Truncated files** | 3 | 0 (missed) | **2 (exact)** |
+| Files counted | 2,174 | 2,174 | **1,684 (exact)** |
+| Reproducible / verifiable | no | no | **yes** |
+
+Two things stand out. (1) The two manual runs **disagree with each other** — 112 vs 131
+decisions, 3 vs 0 truncated files (the second missed them entirely): the by-hand method is
+non-deterministic and unverifiable. (2) Second Brain returns the **exact, identical answer
+every run**, with far fewer tokens and in less than half the time.
+
+Just to *orient* an assistant on the whole project — something you pay for **every session** —
+reading the curated source-of-truth docs costs **~229,000 tokens**; the `second-brain map`
+digest costs **~270 tokens**: **~800× less**, and roughly constant as the project grows (the
+full index is queried, never loaded into context).
+
+<p align="center">
+  <img src="docs/assets/chart-tokens.png" width="90%" alt="Tokens to orient (log scale): ~26.7M to read everything, ~4.09M all docs, ~229,000 today's curated docs, ~270 the Second Brain digest">
+</p>
+
+<p align="center">
+  <img src="docs/assets/chart-accuracy.png" width="48%" alt="Accuracy: manual runs disagree (112 / 131), Second Brain is exact (117)">
+  <img src="docs/assets/chart-time.png" width="48%" alt="Time to answer: ~8.5 / ~9 min manual vs ~3–4 min with Second Brain; index build ~1.3 s once">
+</p>
+
+And it surfaces what even curated docs miss: genuinely **truncated/corrupted files** (with
+UTF-16/encoding false positives excluded), **~45 empty files**, **~1,390 orphan files (~80%)**,
+**117 decisions** and **~626 cross-references** now explicit and queryable, plus **13 files
+already stale within seconds** of indexing (a live system constantly writing) — which is
+exactly why the map has to update itself.
+
+<p align="center">
+  <img src="docs/assets/chart-memory.png" width="72%" alt="Illustrative: across many chats a hand-kept project map drifts while a queryable graph stays current">
+</p>
+
+<sub>Illustrative — the continuity problem SB removes: over many sessions a hand-kept map
+drifts as orphans and stale files pile up, while a queryable graph stays current.</sub>
+
+### The same structure, the code layer
+
+Second Brain's code-import layer renders the whole workspace as a graph you can actually read:
+
+![Graphify view of the workspace code graph](docs/assets/graphify-suite.png)
+
+## Install
+
+```bash
+pip install -e .            # from a clone
+# once published:
+# pip install second-brain-graph
+```
+
+Requires Python 3.10+. Runtime dependencies: **none** (standard library only).
+
+## Quickstart
+
+```bash
+second-brain build  .          # index a project -> .secondbrain/graph.json
+second-brain gate   .          # anti-drift check: broken refs, stale files, orphans
+second-brain view   .          # write the offline 3D viewer -> .secondbrain/view.html
+second-brain stats  .          # quick counts by node/edge type
+second-brain map    .          # compact digest: areas, sizes, most-connected files
+second-brain find   util .     # find nodes by name or path
+second-brain neighbors second_brain/model.py .   # a node and its connections
+second-brain assess .          # one-shot before/after report: problems + token savings
+```
+
+**Drill down** by pointing the tool at a subfolder — `second-brain view ./src/api` renders just
+that area in full detail, while the top-level view stays light via *backbone* mode (areas +
+the knowledge-connected core; isolated data files are summarized on their area node).
+
+Open `.secondbrain/view.html` in a browser (double-click — no server needed): the data is
+inlined and the 3D library is vendored next to the page, so **it works fully offline**.
+
+## Query layer (for AI assistants)
+
+`second-brain map`, `find`, and `neighbors` return compact, budgeted answers (ids, types, sizes,
+connections — never file contents). An optional **MCP server** exposes the same queries to
+MCP-aware assistants:
+
+```bash
+pip install "second-brain-graph[mcp]"
+second-brain-mcp .      # serves map / find / neighbors / subgraph / health over stdio
+```
+
+See [`docs/mcp.md`](docs/mcp.md) for the tools and their shapes.
+
+## How it works
+
+1. **Index** — walk the project, classify each file into a typed node, and extract edges:
+   Python imports (via `ast`), JS/TS imports, documentation references (markdown links,
+   `[[wikilinks]]`, and **plain path mentions in prose** — the part standard tools miss), and
+   area membership. Operational nodes (decisions found in the docs, sessions from git commits)
+   are added too.
+2. **Stay fresh** — content-hash diffing rebuilds only what changed (outside the model).
+3. **Query / view** — a human gets the 3D view; an assistant queries the low-token layer.
+
+**On false positives:** plain path mentions in prose are inherently noisy. Second Brain handles
+this asymmetrically — markdown links and wikilinks are intentional (an unresolved one is
+reported as *broken*), but a plain prose mention is used **only if it resolves** to a real file;
+otherwise it is dropped as noise and never creates a broken reference. Deep import parsing is
+Python and JS/TS today; other languages contribute via documentation links.
+
+The full node/edge taxonomy, the `graph.json` schema, and the classification rules are
+documented in [`docs/graph-format.md`](docs/graph-format.md).
+
+## Try the before/after yourself
+
+Run these in **separate clean chats** (read-only), then compare the answers and the token/time
+cost. Replace `/path/to/project` with a real project.
+
+**TODAY (your current method):**
+
+```
+READ-ONLY: do not modify, create, delete or move any file. On the project at
+/path/to/project, work with your NORMAL method (reference docs, memory, the tools you
+usually use). Give me a COMPLETE, ACCURATE picture answering these 4 questions:
+1) how many files (excluding images, venvs, caches, .git) and the breakdown by type;
+2) list ALL decisions recorded in the docs (D-XXX, ADR-N, RFC-N);
+3) which files are truncated/corrupted (null-byte) or empty (zero-byte);
+4) the 10 most-connected files. When done, tell me the time and tokens you used.
+```
+
+**WITH Second Brain** (index already built — query it, don't re-read files):
+
+```
+READ-ONLY. Second Brain's index is already built — only query it. Use ONLY:
+  python -m second_brain map   "/path/to/project"
+  python -m second_brain stats "/path/to/project"
+  python -m second_brain find <text> "/path/to/project"
+and read /path/to/project/.secondbrain/assessment.md. Answer the same 4 questions, then
+tell me the time and tokens you used.
+```
+
+## Status & roadmap
+
+Alpha (v0.1). Working today: the typed graph, the anti-drift gate, the offline 3D viewer, the
+low-token query layer (`map`/`find`/`neighbors`/`subgraph`), operational nodes
+(decisions/sessions), and the optional MCP server. Next: richer reference resolution and a PyPI
+release.
+
+## Development
+
+```bash
+pip install -e ".[dev,mcp]"
+ruff check second-brain tests
+pytest -q
+```
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[design principles](CONTRIBUTING.md#design-principles-please-keep-these-intact) (read-only,
+zero-deps, low-token, deterministic). Security reports: [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE).

second_brain_graph-0.1.0/README.it.md

@@ -0,0 +1,229 @@
+# Second Brain (SB)
+
+[![CI](https://github.com/lopax76/second-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/lopax76/second-brain/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+[![Runtime deps](https://img.shields.io/badge/dipendenze%20runtime-nessuna-success.svg)](pyproject.toml)
+
+**Una mappa viva, sempre fresca e a basso costo di token di ogni progetto** — file, collegamenti,
+aree e meccaniche — che un assistente AI può **interrogare** invece di rileggere tutto, e che una
+persona può esplorare in un **grafo 3D** navigabile.
+
+🇬🇧 [Read in English →](README.md)
+
+> Non "un altro posto dove mettere roba". È il quadro canonico, per-progetto, che resta in sync
+> con i tuoi file così non perdi mai il filo: niente pezzi dimenticati, niente "ne avevamo parlato
+> tre chat fa", niente documenti stantii.
+
+![Viewer 3D di Second Brain — backbone anonimizzato di un workspace multi-progetto reale](docs/assets/ui-suite.png)
+
+<sub>Il viewer 3D offline su un workspace multi-progetto reale (nomi anonimizzati): nodi colorati
+per tipo, qui raggruppati per tipo, con pannello di dettaglio cliccabile.</sub>
+
+---
+
+## Perché nasce
+
+Un progetto diventa più complesso col tempo. I file derivano, alcuni restano orfani o si rompono
+in silenzio, lo schema mentale di "cosa c'è e come si collega" si fa sempre più sfocato, e un
+assistente AI **perde il filo tra una chat e l'altra** — così ogni sessione riparte rileggendo e
+ri-cercando i file. È lento, incompleto e **brucia token ripetutamente** — e peggiora man mano che
+il progetto cresce.
+
+Second Brain costruisce il grafo del progetto **una volta sola** e lo mantiene fresco in modo
+incrementale (fuori dal modello, a costo di token quasi nullo). L'assistente lo **interroga** e
+ottiene risposte compatte; una persona apre la **vista 3D** e vede l'intero progetto a colpo
+d'occhio.
+
+**Non è un sistema RAG**: niente embedding, niente vector store, nessun LLM per costruire il grafo.
+Mappa le relazioni *strutturali* tra i file, il che lo rende complementare al RAG e mirato a una
+cosa sola: **consapevolezza del contesto a costo di token bassissimo.**
+
+## Cosa lo rende diverso
+
+- **Read-only sui sorgenti** — indicizza, non modifica mai i tuoi file. Lo esegui su qualsiasi cosa
+  senza rischio.
+- **I file sono la verità** — il grafo è derivato (in `.secondbrain/`) e sempre rigenerabile; i
+  contenuti non vengono mai duplicati dentro.
+- **Zero dipendenze runtime** — il core gira con la sola libreria standard di Python. Nessun
+  conflitto, installazione istantanea, funziona in CI / container / macchine air-gapped.
+- **Basso costo di token per design** — le query restituiscono id, tipi, dimensioni e collegamenti,
+  mai il contenuto dei file: orientare un assistente costa qualche centinaio di token, non decine di
+  migliaia.
+- **Gate anti-deriva** — rifiuta di dichiarare il grafo "a posto" finché c'è qualcosa di stantio,
+  orfano o rotto.
+- **Viewer 3D offline** — i dati sono inline e la libreria 3D è bundlata accanto alla pagina; il
+  viewer funziona completamente offline, niente CDN, niente che un blocco-script possa rompere.
+- **Server MCP opzionale** — espone le stesse query a basso costo agli assistenti MCP, dietro un
+  extra opzionale così il core resta senza dipendenze.
+
+## Visto su un progetto reale (anonimizzato)
+
+Misura **read-only** su un progetto maturo multi-repo (identità non rivelata): ~1.684 file di
+conoscenza in 17 aree di primo livello, indicizzato in **~1,3 s** (indice `graph.json` = 0,91 MB).
+
+Tre modi di rispondere alle stesse quattro domande sul progetto — *cosa c'è, elenca ogni decisione
+registrata, quali file sono troncati/vuoti, i file più collegati* — in tre chat pulite separate:
+
+| Metrica | NIENTE (manuale) | ADESSO (manuale) | CON Second Brain |
+|---|---|---|---|
+| Tempo | ~8,5 min | ~9 min | **~3–4 min** |
+| Token di lavoro | opachi | opachi | **~3–4k, auto-misurabili** |
+| **Decisioni trovate** | 112 (errato) | 131 (errato) | **117 (esatto)** |
+| **File troncati** | 3 | 0 (mancati) | **2 (esatto)** |
+| File contati | 2.174 | 2.174 | **1.684 (esatto)** |
+| Riproducibile / verificabile | no | no | **sì** |
+
+Due cose saltano all'occhio. (1) I due run manuali **non concordano tra loro** — 112 vs 131
+decisioni, 3 vs 0 troncati (il secondo li ha mancati del tutto): il metodo a mano è
+non-deterministico e non verificabile. (2) Second Brain dà la **risposta esatta e identica a ogni
+run**, con molti meno token e in meno della metà del tempo.
+
+Solo per *orientare* un assistente sull'intero progetto — cosa che paghi **ogni sessione** —
+rileggere i documenti curati sorgente-di-verità costa **~229.000 token**; il digest
+`second-brain map` costa **~270 token**: **~800× in meno**, e ~costante mentre il progetto cresce
+(l'indice completo si interroga, non entra mai nel contesto).
+
+<p align="center">
+  <img src="docs/assets/chart-tokens.png" width="90%" alt="Token per orientarsi (scala log): ~26,7M per leggere tutto, ~4,09M tutti i documenti, ~229.000 i documenti curati di oggi, ~270 il digest di Second Brain">
+</p>
+
+<p align="center">
+  <img src="docs/assets/chart-accuracy.png" width="48%" alt="Accuratezza: i run manuali non concordano (112 / 131), Second Brain è esatto (117)">
+  <img src="docs/assets/chart-time.png" width="48%" alt="Tempo per rispondere: ~8,5 / ~9 min manuale vs ~3–4 min con Second Brain; build indice ~1,3 s una-tantum">
+</p>
+
+E fa emergere ciò che persino i documenti curati non vedono: file **realmente
+troncati/corrotti** (esclusi i falsi positivi UTF-16/encoding), **~45 file vuoti**, **~1.390 file
+orfani (~80%)**, **117 decisioni** e **~626 riferimenti incrociati** ora espliciti e interrogabili,
+più **13 file già stantii a pochi secondi** dall'indicizzazione (un sistema vivo che riscrive di
+continuo) — ed è proprio per questo che la mappa deve aggiornarsi da sola.
+
+<p align="center">
+  <img src="docs/assets/chart-memory.png" width="72%" alt="Illustrativo: nel corso di molte chat una mappa tenuta a mano deriva, mentre un grafo interrogabile resta aggiornato">
+</p>
+
+<sub>Illustrativo — il problema di continuità che SB elimina: nel corso di molte sessioni una
+mappa tenuta a mano deriva (orfani e file stantii si accumulano), mentre un grafo interrogabile
+resta sempre aggiornato.</sub>
+
+### La stessa struttura, il layer di codice
+
+Il layer di import-codice di Second Brain rende l'intero workspace come un grafo davvero leggibile:
+
+![Vista Graphify del grafo di codice del workspace](docs/assets/graphify-suite.png)
+
+## Installazione
+
+```bash
+pip install -e .            # da un clone
+# una volta pubblicato:
+# pip install second-brain-graph
+```
+
+Richiede Python 3.10+. Dipendenze runtime: **nessuna** (solo libreria standard).
+
+## Avvio rapido
+
+```bash
+second-brain build  .          # indicizza un progetto -> .secondbrain/graph.json
+second-brain gate   .          # check anti-deriva: ref rotte, file stantii, orfani
+second-brain view   .          # scrive il viewer 3D offline -> .secondbrain/view.html
+second-brain stats  .          # conteggi rapidi per tipo nodo/arco
+second-brain map    .          # digest compatto: aree, dimensioni, file più connessi
+second-brain find   util .     # trova nodi per nome o path
+second-brain neighbors second_brain/model.py .   # un nodo e le sue connessioni
+second-brain assess .          # report prima/dopo: problemi + risparmio token
+```
+
+**Drill-down** puntando lo strumento su una sottocartella — `second-brain view ./src/api`
+renderizza solo quell'area in pieno dettaglio, mentre la vista d'insieme resta leggera grazie alla
+modalità *backbone* (aree + nucleo connesso per conoscenza; i file-dati isolati sono riassunti sul
+nodo-area).
+
+Apri `.secondbrain/view.html` in un browser (doppio clic — niente server): i dati sono inline e la
+libreria 3D è bundlata accanto alla pagina, quindi **funziona completamente offline**.
+
+## Layer di query (per gli assistenti AI)
+
+`second-brain map`, `find` e `neighbors` restituiscono risposte compatte e budgettate (id, tipi,
+dimensioni, connessioni — mai il contenuto dei file). Un **server MCP** opzionale espone le stesse
+query agli assistenti compatibili MCP:
+
+```bash
+pip install "second-brain-graph[mcp]"
+second-brain-mcp .      # serve map / find / neighbors / subgraph / health su stdio
+```
+
+Vedi [`docs/mcp.md`](docs/mcp.md) per i tool e le forme dei dati.
+
+## Come funziona
+
+1. **Index** — percorre il progetto, classifica ogni file in un nodo tipizzato ed estrae gli archi:
+   import Python (via `ast`), import JS/TS, riferimenti di documentazione (link markdown,
+   `[[wikilink]]` e **menzioni di path in prosa** — il pezzo che gli strumenti standard mancano) e
+   appartenenza ad area. Vengono aggiunti anche i nodi operativi (decisioni trovate nei documenti,
+   sessioni dai commit git).
+2. **Stay fresh** — il diffing per content-hash ricostruisce solo ciò che è cambiato (fuori dal
+   modello).
+3. **Query / view** — una persona ottiene la vista 3D; un assistente interroga il layer a basso
+   costo di token.
+
+**Sui falsi positivi:** le menzioni di path in prosa sono intrinsecamente rumorose. Second Brain
+le gestisce in modo asimmetrico — link markdown e wikilink sono intenzionali (uno non risolto è
+segnalato come *rotto*), ma una menzione in prosa è usata **solo se risolve** a un file reale;
+altrimenti viene scartata come rumore e non crea mai un riferimento rotto. Il parsing profondo degli
+import oggi è Python e JS/TS; gli altri linguaggi contribuiscono via link di documentazione.
+
+La tassonomia completa nodi/archi, lo schema di `graph.json` e le regole di classificazione sono
+documentati in [`docs/graph-format.md`](docs/graph-format.md).
+
+## Prova tu il prima/dopo
+
+Esegui questi in **chat pulite separate** (read-only), poi confronta le risposte e il costo
+token/tempo. Sostituisci `/path/al/progetto` con un progetto reale.
+
+**ADESSO (il tuo metodo attuale):**
+
+```
+SOLO LETTURA: non modificare, creare, cancellare o spostare alcun file. Sul progetto in
+/path/al/progetto, lavora col tuo METODO NORMALE (documenti di riferimento, memoria, gli
+strumenti che usi di solito). Dammi un quadro COMPLETO e ACCURATO rispondendo a 4 domande:
+1) quanti file (esclusi immagini, venv, cache, .git) e ripartizione per tipo;
+2) elenca TUTTE le decisioni registrate nei documenti (D-XXX, ADR-N, RFC-N);
+3) quali file sono troncati/corrotti (null-byte) o vuoti (zero-byte);
+4) i 10 file più collegati. Quando hai finito, dimmi tempo e token consumati.
+```
+
+**CON Second Brain** (indice già costruito — interrogalo, non rileggere i file):
+
+```
+SOLO LETTURA. L'indice di Second Brain è già costruito — va solo interrogato. Usa SOLO:
+  python -m second_brain map   "/path/al/progetto"
+  python -m second_brain stats "/path/al/progetto"
+  python -m second_brain find <testo> "/path/al/progetto"
+e leggi /path/al/progetto/.secondbrain/assessment.md. Rispondi alle stesse 4 domande, poi
+dimmi tempo e token consumati.
+```
+
+## Stato & roadmap
+
+Alpha (v0.1). Funzionante oggi: grafo tipizzato, gate anti-deriva, viewer 3D offline, layer di
+query a basso costo (`map`/`find`/`neighbors`/`subgraph`), nodi operativi (decisioni/sessioni) e
+server MCP opzionale. Prossimi passi: risoluzione dei riferimenti più ricca e una release su PyPI.
+
+## Sviluppo
+
+```bash
+pip install -e ".[dev,mcp]"
+ruff check second-brain tests
+pytest -q
+```
+
+I contributi sono benvenuti — vedi [CONTRIBUTING.md](CONTRIBUTING.md) e i
+[principi di design](CONTRIBUTING.md#design-principles-please-keep-these-intact) (read-only,
+zero-deps, basso costo di token, deterministico). Segnalazioni di sicurezza: [SECURITY.md](SECURITY.md).
+
+## Licenza
+
+[MIT](LICENSE).