Navegador

docs: full documentation rewrite — two-layer KG, agent hooks, planopticon, all guide pages

lmata 2026-03-22 21:53 trunk

Commit ce0374a2be6edb56c1746a6f6f6cd0384b958766f65e2bf5a206b325851b5b8e

Parent 9c8fd06c4519a01…

16 files changed +261 -2 +269 -2 +250 -2 +121 -2 +135 -2 +104 -2 +75 -2 +139 -2 +215 +149 -2 +140 -2 +149 -2 +151 -2 +175 +88 -25 +3 -1

~ docs/api/graph.md ~ docs/api/ingestion.md ~ docs/api/mcp.md ~ docs/architecture/graph-schema.md ~ docs/architecture/overview.md ~ docs/getting-started/configuration.md ~ docs/getting-started/installation.md ~ docs/getting-started/quickstart.md + docs/guide/agent-hooks.md ~ docs/guide/context-loading.md ~ docs/guide/graph-queries.md ~ docs/guide/ingestion.md ~ docs/guide/mcp-integration.md + docs/guide/planopticon.md ~ docs/index.md ~ mkdocs.yml

M docs/api/graph.md

+261 -2

		--- docs/api/graph.md
		+++ docs/api/graph.md
		@@ -1,3 +1,262 @@
1		-# graph
	1	+# Graph API
	2	+
	3	+```python
	4	+from navegador.graph import GraphStore
	5	+from navegador.context import ContextLoader, ContextBundle, ContextNode
	6	+```
	7	+
	8	+---
	9	+
	10	+## GraphStore
	11	+
	12	+The database abstraction layer. Both SQLite and Redis backends implement this interface.
	13	+
	14	+```python
	15	+class GraphStore:
	16	+ @classmethod
	17	+ def sqlite(cls, path: str \| Path = "navegador.db") -> "GraphStore": ...
	18	+
	19	+ @classmethod
	20	+ def redis(cls, url: str = "redis://localhost:6379") -> "GraphStore": ...
	21	+
	22	+ def query(
	23	+ self,
	24	+ cypher: str,
	25	+ params: dict \| None = None,
	26	+ ) -> list[dict]: ...
	27	+
	28	+ def create_node(
	29	+ self,
	30	+ label: str,
	31	+ properties: dict,
	32	+ ) -> str: ... # returns node ID
	33	+
	34	+ def merge_node(
	35	+ self,
	36	+ label: str,
	37	+ match_properties: dict,
	38	+ set_properties: dict \| None = None,
	39	+ ) -> str: ... # upsert by match_properties, returns node ID
	40	+
	41	+ def create_edge(
	42	+ self,
	43	+ from_id: str,
	44	+ to_id: str,
	45	+ edge_type: str,
	46	+ properties: dict \| None = None,
	47	+ ) -> None: ...
	48	+
	49	+ def merge_edge(
	50	+ self,
	51	+ from_label: str,
	52	+ from_match: dict,
	53	+ to_label: str,
	54	+ to_match: dict,
	55	+ edge_type: str,
	56	+ properties: dict \| None = None,
	57	+ ) -> None: ...
	58	+
	59	+ def clear(self) -> None: ...
	60	+
	61	+ def close(self) -> None: ...
	62	+```
	63	+
	64	+### Usage
	65	+
	66	+```python
	67	+# SQLite (local dev)
	68	+store = GraphStore.sqlite(".navegador/navegador.db")
	69	+
	70	+# Redis (production)
	71	+store = GraphStore.redis("redis://localhost:6379")
	72	+
	73	+# raw Cypher query
	74	+results = store.query(
	75	+ "MATCH (f:Function {name: $name}) RETURN f",
	76	+ params={"name": "validate_token"}
	77	+)
	78	+
	79	+# create a node
	80	+node_id = store.create_node("Concept", {
	81	+ "name": "Idempotency",
	82	+ "description": "Operations safe to retry"
	83	+})
	84	+
	85	+# upsert a node (match by name, update description)
	86	+node_id = store.merge_node(
	87	+ "Concept",
	88	+ match_properties={"name": "Idempotency"},
	89	+ set_properties={"description": "Updated description"}
	90	+)
	91	+
	92	+# create an edge
	93	+store.create_edge(from_id, to_id, "ANNOTATES")
	94	+
	95	+# wipe the graph
	96	+store.clear()
	97	+```
	98	+
	99	+### Context manager
	100	+
	101	+`GraphStore` implements the context manager protocol:
	102	+
	103	+```python
	104	+with GraphStore.sqlite(".navegador/navegador.db") as store:
	105	+ results = store.query("MATCH (n) RETURN count(n) AS total")
	106	+```
	107	+
	108	+---
	109	+
	110	+## ContextLoader
	111	+
	112	+Builds structured context bundles from graph queries. Each method corresponds to a CLI command.
	113	+
	114	+```python
	115	+class ContextLoader:
	116	+ def __init__(self, store: GraphStore) -> None: ...
	117	+
	118	+ def load_file(self, path: str) -> ContextBundle: ...
	119	+
	120	+ def load_function(
	121	+ self,
	122	+ name: str,
	123	+ *,
	124	+ file: str = "",
	125	+ depth: int = 1,
	126	+ ) -> ContextBundle: ...
	127	+
	128	+ def load_class(
	129	+ self,
	130	+ name: str,
	131	+ *,
	132	+ file: str = "",
	133	+ ) -> ContextBundle: ...
	134	+
	135	+ def explain(
	136	+ self,
	137	+ name: str,
	138	+ *,
	139	+ file: str = "",
	140	+ ) -> ContextBundle: ...
	141	+
	142	+ def load_concept(self, name: str) -> ContextBundle: ...
	143	+
	144	+ def load_domain(self, name: str) -> ContextBundle: ...
	145	+
	146	+ def search(
	147	+ self,
	148	+ query: str,
	149	+ *,
	150	+ all_layers: bool = False,
	151	+ docs_only: bool = False,
	152	+ limit: int = 20,
	153	+ ) -> list[ContextNode]: ...
	154	+
	155	+ def search_by_docstring(
	156	+ self,
	157	+ query: str,
	158	+ *,
	159	+ limit: int = 20,
	160	+ ) -> list[ContextNode]: ...
	161	+
	162	+ def decorated_by(
	163	+ self,
	164	+ decorator: str,
	165	+ ) -> list[ContextNode]: ...
	166	+```
	167	+
	168	+### Usage
	169	+
	170	+```python
	171	+store = GraphStore.sqlite(".navegador/navegador.db")
	172	+loader = ContextLoader(store)
	173	+
	174	+# file context
	175	+bundle = loader.load_file("src/auth/service.py")
	176	+
	177	+# function with 2-hop call graph
	178	+bundle = loader.load_function("validate_token", depth=2)
	179	+
	180	+# class hierarchy
	181	+bundle = loader.load_class("PaymentProcessor", file="src/payments/processor.py")
	182	+
	183	+# universal explain
	184	+bundle = loader.explain("AuthService")
	185	+
	186	+# concept with annotated code
	187	+bundle = loader.load_concept("Idempotency")
	188	+
	189	+# domain overview
	190	+bundle = loader.load_domain("Payments")
	191	+
	192	+# search
	193	+nodes = loader.search("rate limit", all_layers=True, limit=10)
	194	+
	195	+# all @login_required functions
	196	+nodes = loader.decorated_by("login_required")
	197	+```
	198	+
	199	+---
	200	+
	201	+## ContextBundle
	202	+
	203	+The structured result type returned by `ContextLoader` methods.
	204	+
	205	+```python
	206	+@dataclass
	207	+class ContextBundle:
	208	+ root: ContextNode
	209	+ nodes: list[ContextNode]
	210	+ edges: list[ContextEdge]
	211	+ metadata: dict
	212	+
	213	+ def to_json(self) -> str: ...
	214	+ def to_markdown(self) -> str: ...
	215	+ def to_dict(self) -> dict: ...
	216	+```
	217	+
	218	+---
	219	+
	220	+## ContextNode
	221	+
	222	+A single node in a context bundle.
	223	+
	224	+```python
	225	+@dataclass
	226	+class ContextNode:
	227	+ id: str
	228	+ label: str # e.g. "Function", "Concept"
	229	+ name: str
	230	+ properties: dict # all node properties
	231	+ layer: str # "code" or "knowledge"
	232	+```
	233	+
	234	+---
	235	+
	236	+## ContextEdge
	237	+
	238	+```python
	239	+@dataclass
	240	+class ContextEdge:
	241	+ from_id: str
	242	+ to_id: str
	243	+ edge_type: str # e.g. "CALLS", "ANNOTATES"
	244	+ properties: dict
	245	+```
	246	+
	247	+---
	248	+
	249	+## Formatting output
	250	+
	251	+```python
	252	+bundle = loader.load_function("validate_token")
	253	+
	254	+# JSON string
	255	+print(bundle.to_json())
	256	+
	257	+# Markdown string (for agent consumption)
	258	+print(bundle.to_markdown())
2	259
3		-Documentation coming soon.
	260	+# Python dict (for further processing)
	261	+data = bundle.to_dict()
	262	+```
4	263

	--- docs/api/graph.md
	+++ docs/api/graph.md
	@@ -1,3 +1,262 @@
1	# graph

































































































































































































































































2
3	Documentation coming soon.


4

	--- docs/api/graph.md
	+++ docs/api/graph.md
	@@ -1,3 +1,262 @@
1	# Graph API
2
3	```python
4	from navegador.graph import GraphStore
5	from navegador.context import ContextLoader, ContextBundle, ContextNode
6	```
7
8	---
9
10	## GraphStore
11
12	The database abstraction layer. Both SQLite and Redis backends implement this interface.
13
14	```python
15	class GraphStore:
16	@classmethod
17	def sqlite(cls, path: str \| Path = "navegador.db") -> "GraphStore": ...
18
19	@classmethod
20	def redis(cls, url: str = "redis://localhost:6379") -> "GraphStore": ...
21
22	def query(
23	self,
24	cypher: str,
25	params: dict \| None = None,
26	) -> list[dict]: ...
27
28	def create_node(
29	self,
30	label: str,
31	properties: dict,
32	) -> str: ... # returns node ID
33
34	def merge_node(
35	self,
36	label: str,
37	match_properties: dict,
38	set_properties: dict \| None = None,
39	) -> str: ... # upsert by match_properties, returns node ID
40
41	def create_edge(
42	self,
43	from_id: str,
44	to_id: str,
45	edge_type: str,
46	properties: dict \| None = None,
47	) -> None: ...
48
49	def merge_edge(
50	self,
51	from_label: str,
52	from_match: dict,
53	to_label: str,
54	to_match: dict,
55	edge_type: str,
56	properties: dict \| None = None,
57	) -> None: ...
58
59	def clear(self) -> None: ...
60
61	def close(self) -> None: ...
62	```
63
64	### Usage
65
66	```python
67	# SQLite (local dev)
68	store = GraphStore.sqlite(".navegador/navegador.db")
69
70	# Redis (production)
71	store = GraphStore.redis("redis://localhost:6379")
72
73	# raw Cypher query
74	results = store.query(
75	"MATCH (f:Function {name: $name}) RETURN f",
76	params={"name": "validate_token"}
77	)
78
79	# create a node
80	node_id = store.create_node("Concept", {
81	"name": "Idempotency",
82	"description": "Operations safe to retry"
83	})
84
85	# upsert a node (match by name, update description)
86	node_id = store.merge_node(
87	"Concept",
88	match_properties={"name": "Idempotency"},
89	set_properties={"description": "Updated description"}
90	)
91
92	# create an edge
93	store.create_edge(from_id, to_id, "ANNOTATES")
94
95	# wipe the graph
96	store.clear()
97	```
98
99	### Context manager
100
101	`GraphStore` implements the context manager protocol:
102
103	```python
104	with GraphStore.sqlite(".navegador/navegador.db") as store:
105	results = store.query("MATCH (n) RETURN count(n) AS total")
106	```
107
108	---
109
110	## ContextLoader
111
112	Builds structured context bundles from graph queries. Each method corresponds to a CLI command.
113
114	```python
115	class ContextLoader:
116	def __init__(self, store: GraphStore) -> None: ...
117
118	def load_file(self, path: str) -> ContextBundle: ...
119
120	def load_function(
121	self,
122	name: str,
123	*,
124	file: str = "",
125	depth: int = 1,
126	) -> ContextBundle: ...
127
128	def load_class(
129	self,
130	name: str,
131	*,
132	file: str = "",
133	) -> ContextBundle: ...
134
135	def explain(
136	self,
137	name: str,
138	*,
139	file: str = "",
140	) -> ContextBundle: ...
141
142	def load_concept(self, name: str) -> ContextBundle: ...
143
144	def load_domain(self, name: str) -> ContextBundle: ...
145
146	def search(
147	self,
148	query: str,
149	*,
150	all_layers: bool = False,
151	docs_only: bool = False,
152	limit: int = 20,
153	) -> list[ContextNode]: ...
154
155	def search_by_docstring(
156	self,
157	query: str,
158	*,
159	limit: int = 20,
160	) -> list[ContextNode]: ...
161
162	def decorated_by(
163	self,
164	decorator: str,
165	) -> list[ContextNode]: ...
166	```
167
168	### Usage
169
170	```python
171	store = GraphStore.sqlite(".navegador/navegador.db")
172	loader = ContextLoader(store)
173
174	# file context
175	bundle = loader.load_file("src/auth/service.py")
176
177	# function with 2-hop call graph
178	bundle = loader.load_function("validate_token", depth=2)
179
180	# class hierarchy
181	bundle = loader.load_class("PaymentProcessor", file="src/payments/processor.py")
182
183	# universal explain
184	bundle = loader.explain("AuthService")
185
186	# concept with annotated code
187	bundle = loader.load_concept("Idempotency")
188
189	# domain overview
190	bundle = loader.load_domain("Payments")
191
192	# search
193	nodes = loader.search("rate limit", all_layers=True, limit=10)
194
195	# all @login_required functions
196	nodes = loader.decorated_by("login_required")
197	```
198
199	---
200
201	## ContextBundle
202
203	The structured result type returned by `ContextLoader` methods.
204
205	```python
206	@dataclass
207	class ContextBundle:
208	root: ContextNode
209	nodes: list[ContextNode]
210	edges: list[ContextEdge]
211	metadata: dict
212
213	def to_json(self) -> str: ...
214	def to_markdown(self) -> str: ...
215	def to_dict(self) -> dict: ...
216	```
217
218	---
219
220	## ContextNode
221
222	A single node in a context bundle.
223
224	```python
225	@dataclass
226	class ContextNode:
227	id: str
228	label: str # e.g. "Function", "Concept"
229	name: str
230	properties: dict # all node properties
231	layer: str # "code" or "knowledge"
232	```
233
234	---
235
236	## ContextEdge
237
238	```python
239	@dataclass
240	class ContextEdge:
241	from_id: str
242	to_id: str
243	edge_type: str # e.g. "CALLS", "ANNOTATES"
244	properties: dict
245	```
246
247	---
248
249	## Formatting output
250
251	```python
252	bundle = loader.load_function("validate_token")
253
254	# JSON string
255	print(bundle.to_json())
256
257	# Markdown string (for agent consumption)
258	print(bundle.to_markdown())
259
260	# Python dict (for further processing)
261	data = bundle.to_dict()
262	```
263

M docs/api/ingestion.md

+269 -2

		--- docs/api/ingestion.md
		+++ docs/api/ingestion.md
		@@ -1,3 +1,270 @@
1		-# ingestion
	1	+# Ingestion API
	2	+
	3	+All ingesters accept a `GraphStore` instance and return an `IngestionResult` dataclass.
	4	+
	5	+```python
	6	+from navegador.graph import GraphStore
	7	+from navegador.ingest import RepoIngester, KnowledgeIngester, WikiIngester, PlanopticonIngester
	8	+```
	9	+
	10	+---
	11	+
	12	+## IngestionResult
	13	+
	14	+```python
	15	+@dataclass
	16	+class IngestionResult:
	17	+ nodes_created: int
	18	+ nodes_updated: int
	19	+ edges_created: int
	20	+ files_processed: int
	21	+ errors: list[str]
	22	+ duration_seconds: float
	23	+```
	24	+
	25	+---
	26	+
	27	+## RepoIngester
	28	+
	29	+Parses a source tree and writes code layer nodes and edges.
	30	+
	31	+```python
	32	+class RepoIngester:
	33	+ def __init__(self, store: GraphStore) -> None: ...
	34	+
	35	+ def ingest(
	36	+ self,
	37	+ path: str \| Path,
	38	+ *,
	39	+ clear: bool = False,
	40	+ ) -> IngestionResult: ...
	41	+
	42	+ def ingest_file(
	43	+ self,
	44	+ path: str \| Path,
	45	+ ) -> IngestionResult: ...
	46	+```
	47	+
	48	+### Usage
	49	+
	50	+```python
	51	+store = GraphStore.sqlite(".navegador/navegador.db")
	52	+ingester = RepoIngester(store)
	53	+
	54	+# full repo ingest
	55	+result = ingester.ingest("./src")
	56	+print(f"{result.nodes_created} nodes, {result.edges_created} edges")
	57	+
	58	+# incremental: single file
	59	+result = ingester.ingest_file("./src/auth/service.py")
	60	+
	61	+# wipe + rebuild
	62	+result = ingester.ingest("./src", clear=True)
	63	+```
	64	+
	65	+### Supported languages
	66	+
	67	+\| Language \| File extensions \| Parser \|
	68	+\|---\|---\|---\|
	69	+\| Python \| `.py` \| tree-sitter-python \|
	70	+\| TypeScript \| `.ts`, `.tsx` \| tree-sitter-typescript \|
	71	+\| JavaScript \| `.js`, `.jsx` \| tree-sitter-javascript \|
	72	+
	73	+### Adding a new language parser
	74	+
	75	+1. Install the tree-sitter grammar: `pip install tree-sitter-<lang>`
	76	+2. Subclass `navegador.ingest.base.LanguageParser`:
	77	+
	78	+```python
	79	+from navegador.ingest.base import LanguageParser, ParseResult
	80	+
	81	+class RubyParser(LanguageParser):
	82	+ language = "ruby"
	83	+ extensions = [".rb"]
	84	+
	85	+ def parse(self, source: str, file_path: str) -> ParseResult:
	86	+ # use self.tree_sitter_language to build the tree
	87	+ # return ParseResult with nodes and edges
	88	+ ...
	89	+```
	90	+
	91	+3. Register in `navegador/ingest/registry.py`:
	92	+
	93	+```python
	94	+from .ruby import RubyParser
	95	+PARSERS["ruby"] = RubyParser
	96	+```
	97	+
	98	+`RepoIngester` dispatches to registered parsers by file extension.
	99	+
	100	+---
	101	+
	102	+## KnowledgeIngester
	103	+
	104	+Writes knowledge layer nodes. Wraps the `navegador add` commands programmatically.
	105	+
	106	+```python
	107	+class KnowledgeIngester:
	108	+ def __init__(self, store: GraphStore) -> None: ...
	109	+
	110	+ def add_concept(
	111	+ self,
	112	+ name: str,
	113	+ *,
	114	+ description: str = "",
	115	+ domain: str = "",
	116	+ status: str = "",
	117	+ ) -> str: ... # returns node ID
	118	+
	119	+ def add_rule(
	120	+ self,
	121	+ name: str,
	122	+ *,
	123	+ description: str = "",
	124	+ domain: str = "",
	125	+ severity: str = "info",
	126	+ rationale: str = "",
	127	+ ) -> str: ...
	128	+
	129	+ def add_decision(
	130	+ self,
	131	+ name: str,
	132	+ *,
	133	+ description: str = "",
	134	+ domain: str = "",
	135	+ rationale: str = "",
	136	+ alternatives: str = "",
	137	+ date: str = "",
	138	+ status: str = "proposed",
	139	+ ) -> str: ...
	140	+
	141	+ def add_person(
	142	+ self,
	143	+ name: str,
	144	+ *,
	145	+ email: str = "",
	146	+ role: str = "",
	147	+ team: str = "",
	148	+ ) -> str: ...
	149	+
	150	+ def add_domain(
	151	+ self,
	152	+ name: str,
	153	+ *,
	154	+ description: str = "",
	155	+ ) -> str: ...
	156	+
	157	+ def annotate(
	158	+ self,
	159	+ code_name: str,
	160	+ *,
	161	+ node_type: str = "Function",
	162	+ concept: str = "",
	163	+ rule: str = "",
	164	+ ) -> None: ...
	165	+```
	166	+
	167	+### Usage
	168	+
	169	+```python
	170	+store = GraphStore.sqlite(".navegador/navegador.db")
	171	+ingester = KnowledgeIngester(store)
	172	+
	173	+ingester.add_domain("Payments", description="Payment processing and billing")
	174	+ingester.add_concept("Idempotency", domain="Payments",
	175	+ description="Operations safe to retry without side effects")
	176	+ingester.add_rule("RequireIdempotencyKey",
	177	+ domain="Payments", severity="critical",
	178	+ rationale="Card networks retry on timeout")
	179	+ingester.annotate("process_payment", node_type="Function",
	180	+ concept="Idempotency", rule="RequireIdempotencyKey")
	181	+```
	182	+
	183	+---
	184	+
	185	+## WikiIngester
	186	+
	187	+Fetches GitHub wiki pages and writes `WikiPage` nodes.
	188	+
	189	+```python
	190	+class WikiIngester:
	191	+ def __init__(self, store: GraphStore) -> None: ...
	192	+
	193	+ def ingest_repo(
	194	+ self,
	195	+ repo: str,
	196	+ *,
	197	+ token: str = "",
	198	+ use_api: bool = False,
	199	+ ) -> IngestionResult: ...
	200	+
	201	+ def ingest_dir(
	202	+ self,
	203	+ path: str \| Path,
	204	+ ) -> IngestionResult: ...
	205	+```
	206	+
	207	+### Usage
	208	+
	209	+```python
	210	+import os
	211	+store = GraphStore.sqlite(".navegador/navegador.db")
	212	+ingester = WikiIngester(store)
	213	+
	214	+# from GitHub API
	215	+result = ingester.ingest_repo("myorg/myrepo", token=os.environ["GITHUB_TOKEN"])
	216	+
	217	+# from local clone
	218	+result = ingester.ingest_dir("./myrepo.wiki")
	219	+```
	220	+
	221	+---
	222	+
	223	+## PlanopticonIngester
	224	+
	225	+Ingests Planopticon knowledge graph output into the knowledge layer.
	226	+
	227	+```python
	228	+class PlanopticonIngester:
	229	+ def __init__(self, store: GraphStore) -> None: ...
	230	+
	231	+ def ingest(
	232	+ self,
	233	+ path: str \| Path,
	234	+ *,
	235	+ input_type: str = "auto",
	236	+ source: str = "",
	237	+ ) -> IngestionResult: ...
	238	+
	239	+ def ingest_manifest(
	240	+ self,
	241	+ path: str \| Path,
	242	+ *,
	243	+ source: str = "",
	244	+ ) -> IngestionResult: ...
	245	+
	246	+ def ingest_kg(
	247	+ self,
	248	+ path: str \| Path,
	249	+ *,
	250	+ source: str = "",
	251	+ ) -> IngestionResult: ...
	252	+
	253	+ def ingest_interchange(
	254	+ self,
	255	+ path: str \| Path,
	256	+ *,
	257	+ source: str = "",
	258	+ ) -> IngestionResult: ...
	259	+
	260	+ def ingest_batch(
	261	+ self,
	262	+ path: str \| Path,
	263	+ *,
	264	+ source: str = "",
	265	+ ) -> IngestionResult: ...
	266	+```
	267	+
	268	+`input_type` values: `"auto"`, `"manifest"`, `"kg"`, `"interchange"`, `"batch"`.
2	269
3		-Documentation coming soon.
	270	+See [Planopticon guide](../guide/planopticon.md) for format details and entity mapping.
4	271

	--- docs/api/ingestion.md
	+++ docs/api/ingestion.md
	@@ -1,3 +1,270 @@
1	# ingestion











































































































































































































































































2
3	Documentation coming soon.
4

	--- docs/api/ingestion.md
	+++ docs/api/ingestion.md
	@@ -1,3 +1,270 @@
1	# Ingestion API
2
3	All ingesters accept a `GraphStore` instance and return an `IngestionResult` dataclass.
4
5	```python
6	from navegador.graph import GraphStore
7	from navegador.ingest import RepoIngester, KnowledgeIngester, WikiIngester, PlanopticonIngester
8	```
9
10	---
11
12	## IngestionResult
13
14	```python
15	@dataclass
16	class IngestionResult:
17	nodes_created: int
18	nodes_updated: int
19	edges_created: int
20	files_processed: int
21	errors: list[str]
22	duration_seconds: float
23	```
24
25	---
26
27	## RepoIngester
28
29	Parses a source tree and writes code layer nodes and edges.
30
31	```python
32	class RepoIngester:
33	def __init__(self, store: GraphStore) -> None: ...
34
35	def ingest(
36	self,
37	path: str \| Path,
38	*,
39	clear: bool = False,
40	) -> IngestionResult: ...
41
42	def ingest_file(
43	self,
44	path: str \| Path,
45	) -> IngestionResult: ...
46	```
47
48	### Usage
49
50	```python
51	store = GraphStore.sqlite(".navegador/navegador.db")
52	ingester = RepoIngester(store)
53
54	# full repo ingest
55	result = ingester.ingest("./src")
56	print(f"{result.nodes_created} nodes, {result.edges_created} edges")
57
58	# incremental: single file
59	result = ingester.ingest_file("./src/auth/service.py")
60
61	# wipe + rebuild
62	result = ingester.ingest("./src", clear=True)
63	```
64
65	### Supported languages
66
67	\| Language \| File extensions \| Parser \|
68	\|---\|---\|---\|
69	\| Python \| `.py` \| tree-sitter-python \|
70	\| TypeScript \| `.ts`, `.tsx` \| tree-sitter-typescript \|
71	\| JavaScript \| `.js`, `.jsx` \| tree-sitter-javascript \|
72
73	### Adding a new language parser
74
75	1. Install the tree-sitter grammar: `pip install tree-sitter-<lang>`
76	2. Subclass `navegador.ingest.base.LanguageParser`:
77
78	```python
79	from navegador.ingest.base import LanguageParser, ParseResult
80
81	class RubyParser(LanguageParser):
82	language = "ruby"
83	extensions = [".rb"]
84
85	def parse(self, source: str, file_path: str) -> ParseResult:
86	# use self.tree_sitter_language to build the tree
87	# return ParseResult with nodes and edges
88	...
89	```
90
91	3. Register in `navegador/ingest/registry.py`:
92
93	```python
94	from .ruby import RubyParser
95	PARSERS["ruby"] = RubyParser
96	```
97
98	`RepoIngester` dispatches to registered parsers by file extension.
99
100	---
101
102	## KnowledgeIngester
103
104	Writes knowledge layer nodes. Wraps the `navegador add` commands programmatically.
105
106	```python
107	class KnowledgeIngester:
108	def __init__(self, store: GraphStore) -> None: ...
109
110	def add_concept(
111	self,
112	name: str,
113	*,
114	description: str = "",
115	domain: str = "",
116	status: str = "",
117	) -> str: ... # returns node ID
118
119	def add_rule(
120	self,
121	name: str,
122	*,
123	description: str = "",
124	domain: str = "",
125	severity: str = "info",
126	rationale: str = "",
127	) -> str: ...
128
129	def add_decision(
130	self,
131	name: str,
132	*,
133	description: str = "",
134	domain: str = "",
135	rationale: str = "",
136	alternatives: str = "",
137	date: str = "",
138	status: str = "proposed",
139	) -> str: ...
140
141	def add_person(
142	self,
143	name: str,
144	*,
145	email: str = "",
146	role: str = "",
147	team: str = "",
148	) -> str: ...
149
150	def add_domain(
151	self,
152	name: str,
153	*,
154	description: str = "",
155	) -> str: ...
156
157	def annotate(
158	self,
159	code_name: str,
160	*,
161	node_type: str = "Function",
162	concept: str = "",
163	rule: str = "",
164	) -> None: ...
165	```
166
167	### Usage
168
169	```python
170	store = GraphStore.sqlite(".navegador/navegador.db")
171	ingester = KnowledgeIngester(store)
172
173	ingester.add_domain("Payments", description="Payment processing and billing")
174	ingester.add_concept("Idempotency", domain="Payments",
175	description="Operations safe to retry without side effects")
176	ingester.add_rule("RequireIdempotencyKey",
177	domain="Payments", severity="critical",
178	rationale="Card networks retry on timeout")
179	ingester.annotate("process_payment", node_type="Function",
180	concept="Idempotency", rule="RequireIdempotencyKey")
181	```
182
183	---
184
185	## WikiIngester
186
187	Fetches GitHub wiki pages and writes `WikiPage` nodes.
188
189	```python
190	class WikiIngester:
191	def __init__(self, store: GraphStore) -> None: ...
192
193	def ingest_repo(
194	self,
195	repo: str,
196	*,
197	token: str = "",
198	use_api: bool = False,
199	) -> IngestionResult: ...
200
201	def ingest_dir(
202	self,
203	path: str \| Path,
204	) -> IngestionResult: ...
205	```
206
207	### Usage
208
209	```python
210	import os
211	store = GraphStore.sqlite(".navegador/navegador.db")
212	ingester = WikiIngester(store)
213
214	# from GitHub API
215	result = ingester.ingest_repo("myorg/myrepo", token=os.environ["GITHUB_TOKEN"])
216
217	# from local clone
218	result = ingester.ingest_dir("./myrepo.wiki")
219	```
220
221	---
222
223	## PlanopticonIngester
224
225	Ingests Planopticon knowledge graph output into the knowledge layer.
226
227	```python
228	class PlanopticonIngester:
229	def __init__(self, store: GraphStore) -> None: ...
230
231	def ingest(
232	self,
233	path: str \| Path,
234	*,
235	input_type: str = "auto",
236	source: str = "",
237	) -> IngestionResult: ...
238
239	def ingest_manifest(
240	self,
241	path: str \| Path,
242	*,
243	source: str = "",
244	) -> IngestionResult: ...
245
246	def ingest_kg(
247	self,
248	path: str \| Path,
249	*,
250	source: str = "",
251	) -> IngestionResult: ...
252
253	def ingest_interchange(
254	self,
255	path: str \| Path,
256	*,
257	source: str = "",
258	) -> IngestionResult: ...
259
260	def ingest_batch(
261	self,
262	path: str \| Path,
263	*,
264	source: str = "",
265	) -> IngestionResult: ...
266	```
267
268	`input_type` values: `"auto"`, `"manifest"`, `"kg"`, `"interchange"`, `"batch"`.
269
270	See [Planopticon guide](../guide/planopticon.md) for format details and entity mapping.
271

M docs/api/mcp.md

+250 -2

		--- docs/api/mcp.md
		+++ docs/api/mcp.md
		@@ -1,3 +1,251 @@
1		-# mcp
	1	+# MCP Server API
	2	+
	3	+Navegador exposes all context-loading commands as an MCP server. The server is created with `create_mcp_server()` and speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio.
	4	+
	5	+```python
	6	+from navegador.mcp import create_mcp_server
	7	+```
	8	+
	9	+---
	10	+
	11	+## create_mcp_server
	12	+
	13	+```python
	14	+def create_mcp_server(
	15	+ store: GraphStore \| None = None,
	16	+ db_path: str = "",
	17	+) -> MCPServer: ...
	18	+```
	19	+
	20	+Creates and returns an MCP server instance. If `store` is not provided, opens a `GraphStore.sqlite()` at `db_path` (or `NAVEGADOR_DB` env var, or `./navegador.db`).
	21	+
	22	+The CLI command `navegador mcp [--db path]` calls this function and runs the server loop.
	23	+
	24	+### Usage
	25	+
	26	+```python
	27	+from navegador.graph import GraphStore
	28	+from navegador.mcp import create_mcp_server
	29	+
	30	+store = GraphStore.sqlite(".navegador/navegador.db")
	31	+server = create_mcp_server(store=store)
	32	+server.run() # blocks; serves over stdio
	33	+```
	34	+
	35	+To embed in a larger MCP server:
	36	+
	37	+```python
	38	+server = create_mcp_server(db_path=".navegador/navegador.db")
	39	+# register additional tools on server before running
	40	+server.run()
	41	+```
	42	+
	43	+---
	44	+
	45	+## Available MCP tools
	46	+
	47	+All tools accept JSON input and return JSON output.
	48	+
	49	+---
	50	+
	51	+### `ingest`
	52	+
	53	+Ingest a repository or file into the graph.
	54	+
	55	+Input schema:
	56	+```json
	57	+{
	58	+ "type": "object",
	59	+ "properties": {
	60	+ "path": {
	61	+ "type": "string",
	62	+ "description": "Path to the repo or file to ingest"
	63	+ },
	64	+ "clear": {
	65	+ "type": "boolean",
	66	+ "description": "Wipe the graph before ingesting",
	67	+ "default": false
	68	+ }
	69	+ },
	70	+ "required": ["path"]
	71	+}
	72	+```
	73	+
	74	+Output: `IngestionResult` serialized to JSON.
	75	+
	76	+---
	77	+
	78	+### `context`
	79	+
	80	+Return the full context bundle for a source file.
	81	+
	82	+Input schema:
	83	+```json
	84	+{
	85	+ "type": "object",
	86	+ "properties": {
	87	+ "file": {
	88	+ "type": "string",
	89	+ "description": "Path to the source file"
	90	+ },
	91	+ "format": {
	92	+ "type": "string",
	93	+ "enum": ["json", "markdown"],
	94	+ "default": "json"
	95	+ }
	96	+ },
	97	+ "required": ["file"]
	98	+}
	99	+```
	100	+
	101	+Output: `ContextBundle` as JSON or markdown string.
	102	+
	103	+---
	104	+
	105	+### `function`
	106	+
	107	+Return a function's context bundle including callers, callees, and decorators.
	108	+
	109	+Input schema:
	110	+```json
	111	+{
	112	+ "type": "object",
	113	+ "properties": {
	114	+ "name": {
	115	+ "type": "string",
	116	+ "description": "Function name"
	117	+ },
	118	+ "file": {
	119	+ "type": "string",
	120	+ "description": "Optional file path to disambiguate"
	121	+ },
	122	+ "depth": {
	123	+ "type": "integer",
	124	+ "description": "Call graph traversal depth",
	125	+ "default": 1
	126	+ }
	127	+ },
	128	+ "required": ["name"]
	129	+}
	130	+```
	131	+
	132	+Output: `ContextBundle` as JSON.
	133	+
	134	+---
	135	+
	136	+### `class`
	137	+
	138	+Return a class context bundle including hierarchy, methods, and references.
	139	+
	140	+Input schema:
	141	+```json
	142	+{
	143	+ "type": "object",
	144	+ "properties": {
	145	+ "name": {
	146	+ "type": "string",
	147	+ "description": "Class name"
	148	+ },
	149	+ "file": {
	150	+ "type": "string",
	151	+ "description": "Optional file path to disambiguate"
	152	+ }
	153	+ },
	154	+ "required": ["name"]
	155	+}
	156	+```
	157	+
	158	+Output: `ContextBundle` as JSON.
	159	+
	160	+---
	161	+
	162	+### `explain`
	163	+
	164	+Universal lookup: explain any node (function, class, file, concept, rule, decision) by name.
	165	+
	166	+Input schema:
	167	+```json
	168	+{
	169	+ "type": "object",
	170	+ "properties": {
	171	+ "name": {
	172	+ "type": "string",
	173	+ "description": "Node name to explain"
	174	+ },
	175	+ "file": {
	176	+ "type": "string",
	177	+ "description": "Optional file path to disambiguate code nodes"
	178	+ }
	179	+ },
	180	+ "required": ["name"]
	181	+}
	182	+```
	183	+
	184	+Output: `ContextBundle` as JSON.
	185	+
	186	+---
	187	+
	188	+### `search`
	189	+
	190	+Search the graph by text query.
	191	+
	192	+Input schema:
	193	+```json
	194	+{
	195	+ "type": "object",
	196	+ "properties": {
	197	+ "query": {
	198	+ "type": "string",
	199	+ "description": "Search query"
	200	+ },
	201	+ "all": {
	202	+ "type": "boolean",
	203	+ "description": "Search all layers including knowledge layer",
	204	+ "default": false
	205	+ },
	206	+ "docs": {
	207	+ "type": "boolean",
	208	+ "description": "Search docstrings and wiki content only",
	209	+ "default": false
	210	+ },
	211	+ "limit": {
	212	+ "type": "integer",
	213	+ "description": "Maximum results to return",
	214	+ "default": 20
	215	+ }
	216	+ },
	217	+ "required": ["query"]
	218	+}
	219	+```
	220	+
	221	+Output: Array of `ContextNode` objects as JSON.
	222	+
	223	+---
	224	+
	225	+### `query`
	226	+
	227	+Execute a raw Cypher query against the graph.
	228	+
	229	+Input schema:
	230	+```json
	231	+{
	232	+ "type": "object",
	233	+ "properties": {
	234	+ "cypher": {
	235	+ "type": "string",
	236	+ "description": "Cypher query string"
	237	+ },
	238	+ "params": {
	239	+ "type": "object",
	240	+ "description": "Optional query parameters",
	241	+ "default": {}
	242	+ }
	243	+ },
	244	+ "required": ["cypher"]
	245	+}
	246	+```
	247	+
	248	+Output: Array of result rows as JSON.
2	249
3		-Documentation coming soon.
	250	+!!! warning
	251	+ This tool executes writes as well as reads. Agents should use read-only queries (`MATCH` / `RETURN`) unless explicitly performing graph updates.
4	252

	--- docs/api/mcp.md
	+++ docs/api/mcp.md
	@@ -1,3 +1,251 @@
1	# mcp























































































































































































































































2
3	Documentation coming soon.

4

	--- docs/api/mcp.md
	+++ docs/api/mcp.md
	@@ -1,3 +1,251 @@
1	# MCP Server API
2
3	Navegador exposes all context-loading commands as an MCP server. The server is created with `create_mcp_server()` and speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio.
4
5	```python
6	from navegador.mcp import create_mcp_server
7	```
8
9	---
10
11	## create_mcp_server
12
13	```python
14	def create_mcp_server(
15	store: GraphStore \| None = None,
16	db_path: str = "",
17	) -> MCPServer: ...
18	```
19
20	Creates and returns an MCP server instance. If `store` is not provided, opens a `GraphStore.sqlite()` at `db_path` (or `NAVEGADOR_DB` env var, or `./navegador.db`).
21
22	The CLI command `navegador mcp [--db path]` calls this function and runs the server loop.
23
24	### Usage
25
26	```python
27	from navegador.graph import GraphStore
28	from navegador.mcp import create_mcp_server
29
30	store = GraphStore.sqlite(".navegador/navegador.db")
31	server = create_mcp_server(store=store)
32	server.run() # blocks; serves over stdio
33	```
34
35	To embed in a larger MCP server:
36
37	```python
38	server = create_mcp_server(db_path=".navegador/navegador.db")
39	# register additional tools on server before running
40	server.run()
41	```
42
43	---
44
45	## Available MCP tools
46
47	All tools accept JSON input and return JSON output.
48
49	---
50
51	### `ingest`
52
53	Ingest a repository or file into the graph.
54
55	Input schema:
56	```json
57	{
58	"type": "object",
59	"properties": {
60	"path": {
61	"type": "string",
62	"description": "Path to the repo or file to ingest"
63	},
64	"clear": {
65	"type": "boolean",
66	"description": "Wipe the graph before ingesting",
67	"default": false
68	}
69	},
70	"required": ["path"]
71	}
72	```
73
74	Output: `IngestionResult` serialized to JSON.
75
76	---
77
78	### `context`
79
80	Return the full context bundle for a source file.
81
82	Input schema:
83	```json
84	{
85	"type": "object",
86	"properties": {
87	"file": {
88	"type": "string",
89	"description": "Path to the source file"
90	},
91	"format": {
92	"type": "string",
93	"enum": ["json", "markdown"],
94	"default": "json"
95	}
96	},
97	"required": ["file"]
98	}
99	```
100
101	Output: `ContextBundle` as JSON or markdown string.
102
103	---
104
105	### `function`
106
107	Return a function's context bundle including callers, callees, and decorators.
108
109	Input schema:
110	```json
111	{
112	"type": "object",
113	"properties": {
114	"name": {
115	"type": "string",
116	"description": "Function name"
117	},
118	"file": {
119	"type": "string",
120	"description": "Optional file path to disambiguate"
121	},
122	"depth": {
123	"type": "integer",
124	"description": "Call graph traversal depth",
125	"default": 1
126	}
127	},
128	"required": ["name"]
129	}
130	```
131
132	Output: `ContextBundle` as JSON.
133
134	---
135
136	### `class`
137
138	Return a class context bundle including hierarchy, methods, and references.
139
140	Input schema:
141	```json
142	{
143	"type": "object",
144	"properties": {
145	"name": {
146	"type": "string",
147	"description": "Class name"
148	},
149	"file": {
150	"type": "string",
151	"description": "Optional file path to disambiguate"
152	}
153	},
154	"required": ["name"]
155	}
156	```
157
158	Output: `ContextBundle` as JSON.
159
160	---
161
162	### `explain`
163
164	Universal lookup: explain any node (function, class, file, concept, rule, decision) by name.
165
166	Input schema:
167	```json
168	{
169	"type": "object",
170	"properties": {
171	"name": {
172	"type": "string",
173	"description": "Node name to explain"
174	},
175	"file": {
176	"type": "string",
177	"description": "Optional file path to disambiguate code nodes"
178	}
179	},
180	"required": ["name"]
181	}
182	```
183
184	Output: `ContextBundle` as JSON.
185
186	---
187
188	### `search`
189
190	Search the graph by text query.
191
192	Input schema:
193	```json
194	{
195	"type": "object",
196	"properties": {
197	"query": {
198	"type": "string",
199	"description": "Search query"
200	},
201	"all": {
202	"type": "boolean",
203	"description": "Search all layers including knowledge layer",
204	"default": false
205	},
206	"docs": {
207	"type": "boolean",
208	"description": "Search docstrings and wiki content only",
209	"default": false
210	},
211	"limit": {
212	"type": "integer",
213	"description": "Maximum results to return",
214	"default": 20
215	}
216	},
217	"required": ["query"]
218	}
219	```
220
221	Output: Array of `ContextNode` objects as JSON.
222
223	---
224
225	### `query`
226
227	Execute a raw Cypher query against the graph.
228
229	Input schema:
230	```json
231	{
232	"type": "object",
233	"properties": {
234	"cypher": {
235	"type": "string",
236	"description": "Cypher query string"
237	},
238	"params": {
239	"type": "object",
240	"description": "Optional query parameters",
241	"default": {}
242	}
243	},
244	"required": ["cypher"]
245	}
246	```
247
248	Output: Array of result rows as JSON.
249
250	!!! warning
251	This tool executes writes as well as reads. Agents should use read-only queries (`MATCH` / `RETURN`) unless explicitly performing graph updates.
252

M docs/architecture/graph-schema.md

+121 -2

		--- docs/architecture/graph-schema.md
		+++ docs/architecture/graph-schema.md
		@@ -1,3 +1,122 @@
1		-# graph-schema
	1	+# Graph Schema
	2	+
	3	+## Node labels
	4	+
	5	+### Code layer
	6	+
	7	+\| Label \| Properties \| Description \|
	8	+\|---\|---\|---\|
	9	+\| `Repository` \| `name`, `path`, `url`, `ingested_at` \| Top-level repo node \|
	10	+\| `File` \| `path`, `language`, `lines`, `size` \| Source file \|
	11	+\| `Module` \| `name`, `file`, `path` \| Python module or TS namespace \|
	12	+\| `Class` \| `name`, `file`, `line`, `end_line`, `docstring`, `is_abstract` \| Class definition \|
	13	+\| `Function` \| `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async` \| Top-level function \|
	14	+\| `Method` \| `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async`, `is_classmethod`, `is_staticmethod` \| Class method \|
	15	+\| `Variable` \| `name`, `file`, `line`, `type_annotation` \| Module-level variable \|
	16	+\| `Import` \| `name`, `alias`, `file`, `line`, `from_module` \| Import statement \|
	17	+\| `Decorator` \| `name`, `expression`, `file`, `line` \| Decorator applied to function/class \|
	18	+
	19	+### Knowledge layer
	20	+
	21	+\| Label \| Properties \| Description \|
	22	+\|---\|---\|---\|
	23	+\| `Domain` \| `name`, `description`, `created_at` \| Top-level grouping for concepts, rules, decisions \|
	24	+\| `Concept` \| `name`, `description`, `domain`, `status`, `created_at` \| Named domain concept or design pattern \|
	25	+\| `Rule` \| `name`, `description`, `domain`, `severity`, `rationale`, `created_at` \| Enforceable constraint; severity: `info`, `warning`, `critical` \|
	26	+\| `Decision` \| `name`, `description`, `domain`, `rationale`, `alternatives`, `date`, `status`, `created_at` \| Architectural decision record; status: `proposed`, `accepted`, `deprecated`, `superseded` \|
	27	+\| `WikiPage` \| `title`, `content`, `url`, `source`, `updated_at` \| Wiki page or document \|
	28	+\| `Person` \| `name`, `email`, `role`, `team`, `created_at` \| Team member or contributor \|
	29	+
	30	+---
	31	+
	32	+## Edge types
	33	+
	34	+\| Edge \| From \| To \| Meaning \|
	35	+\|---\|---\|---\|---\|
	36	+\| `CONTAINS` \| Repository, File, Module, Class \| File, Class, Function, Method, Variable, Import \| Structural containment \|
	37	+\| `DEFINES` \| File, Class \| Class, Function, Method \| Definition site \|
	38	+\| `IMPORTS` \| File \| Import \| File imports a module or symbol \|
	39	+\| `DEPENDS_ON` \| File, Module \| File, Module \| Module-level dependency \|
	40	+\| `CALLS` \| Function, Method \| Function, Method \| Direct function call (static analysis) \|
	41	+\| `REFERENCES` \| Function, Method, File \| Variable, Class, Function \| Name reference (not a call) \|
	42	+\| `INHERITS` \| Class \| Class \| Class inherits from parent \|
	43	+\| `IMPLEMENTS` \| Class, Function \| Concept \| Code implements a concept or interface \|
	44	+\| `DECORATES` \| Decorator \| Function, Method, Class \| Decorator applied to target \|
	45	+\| `BELONGS_TO` \| Concept, Rule, Decision, Person \| Domain \| Membership in a domain \|
	46	+\| `RELATED_TO` \| Any \| Any \| General semantic relationship \|
	47	+\| `GOVERNS` \| Rule \| Function, Method, Class, File \| Rule applies to code node \|
	48	+\| `DOCUMENTS` \| WikiPage \| Concept, Function, Class, File \| Documentation relationship \|
	49	+\| `ANNOTATES` \| Concept, Rule \| Function, Method, Class, File, Module \| Knowledge node annotates code node \|
	50	+\| `ASSIGNED_TO` \| Rule, Decision \| Person \| Work item or decision assigned to person \|
	51	+\| `DECIDED_BY` \| Decision \| Person \| Decision was made by person \|
	52	+
	53	+---
	54	+
	55	+## Schema diagram
	56	+
	57	+```mermaid
	58	+graph LR
	59	+ subgraph Knowledge["Knowledge Layer"]
	60	+ Domain
	61	+ Concept
	62	+ Rule
	63	+ Decision
	64	+ WikiPage
	65	+ Person
	66	+ end
	67	+
	68	+ subgraph Code["Code Layer"]
	69	+ Repository
	70	+ File
	71	+ Module
	72	+ Class
	73	+ Function
	74	+ Method
	75	+ Decorator
	76	+ Import
	77	+ Variable
	78	+ end
	79	+
	80	+ Repository -->\|CONTAINS\| File
	81	+ File -->\|CONTAINS\| Class
	82	+ File -->\|CONTAINS\| Function
	83	+ File -->\|IMPORTS\| Import
	84	+ Class -->\|DEFINES\| Method
	85	+ Function -->\|CALLS\| Function
	86	+ Method -->\|CALLS\| Function
	87	+ Method -->\|CALLS\| Method
	88	+ Class -->\|INHERITS\| Class
	89	+ Decorator -->\|DECORATES\| Function
	90	+ Decorator -->\|DECORATES\| Class
	91	+ Decorator -->\|DECORATES\| Method
	92	+
	93	+ Domain -->\|"(inverse) BELONGS_TO"\| Concept
	94	+ Domain -->\|"(inverse) BELONGS_TO"\| Rule
	95	+ Domain -->\|"(inverse) BELONGS_TO"\| Decision
	96	+ WikiPage -->\|DOCUMENTS\| Concept
	97	+ WikiPage -->\|DOCUMENTS\| Function
	98	+
	99	+ Rule -->\|GOVERNS\| Function
	100	+ Rule -->\|GOVERNS\| Class
	101	+ Concept -->\|ANNOTATES\| Function
	102	+ Concept -->\|ANNOTATES\| Class
	103	+ Class -->\|IMPLEMENTS\| Concept
	104	+ Decision -->\|DECIDED_BY\| Person
	105	+ Rule -->\|ASSIGNED_TO\| Person
	106	+```
	107	+
	108	+---
	109	+
	110	+## Code vs knowledge layer distinction
	111	+
	112	+The two layers have different lifecycle and provenance:
	113	+
	114	+\| Dimension \| Code layer \| Knowledge layer \|
	115	+\|---\|---\|---\|
	116	+\| Source \| tree-sitter AST parsing \| Manual curation, wiki, Planopticon \|
	117	+\| Refresh \| On every `navegador ingest` \| On demand (`navegador add`, `wiki ingest`, `planopticon ingest`) \|
	118	+\| Change rate \| Fast (changes with every commit) \| Slow (changes with design decisions) \|
	119	+\| Authorship \| Derived from code \| Human or meeting-authored \|
	120	+\| Queryability \| Names, signatures, call graphs \| Domain semantics, rationale, history \|
2	121
3		-Documentation coming soon.
	122	+Cross-layer edges (`ANNOTATES`, `GOVERNS`, `IMPLEMENTS`, `DOCUMENTS`) are the join points between the two layers. They are created explicitly by humans via `navegador annotate` or inferred during wiki/Planopticon ingestion.
4	123

	--- docs/architecture/graph-schema.md
	+++ docs/architecture/graph-schema.md
	@@ -1,3 +1,122 @@
1	# graph-schema























































































































2
3	Documentation coming soon.
4

	--- docs/architecture/graph-schema.md
	+++ docs/architecture/graph-schema.md
	@@ -1,3 +1,122 @@
1	# Graph Schema
2
3	## Node labels
4
5	### Code layer
6
7	\| Label \| Properties \| Description \|
8	\|---\|---\|---\|
9	\| `Repository` \| `name`, `path`, `url`, `ingested_at` \| Top-level repo node \|
10	\| `File` \| `path`, `language`, `lines`, `size` \| Source file \|
11	\| `Module` \| `name`, `file`, `path` \| Python module or TS namespace \|
12	\| `Class` \| `name`, `file`, `line`, `end_line`, `docstring`, `is_abstract` \| Class definition \|
13	\| `Function` \| `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async` \| Top-level function \|
14	\| `Method` \| `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async`, `is_classmethod`, `is_staticmethod` \| Class method \|
15	\| `Variable` \| `name`, `file`, `line`, `type_annotation` \| Module-level variable \|
16	\| `Import` \| `name`, `alias`, `file`, `line`, `from_module` \| Import statement \|
17	\| `Decorator` \| `name`, `expression`, `file`, `line` \| Decorator applied to function/class \|
18
19	### Knowledge layer
20
21	\| Label \| Properties \| Description \|
22	\|---\|---\|---\|
23	\| `Domain` \| `name`, `description`, `created_at` \| Top-level grouping for concepts, rules, decisions \|
24	\| `Concept` \| `name`, `description`, `domain`, `status`, `created_at` \| Named domain concept or design pattern \|
25	\| `Rule` \| `name`, `description`, `domain`, `severity`, `rationale`, `created_at` \| Enforceable constraint; severity: `info`, `warning`, `critical` \|
26	\| `Decision` \| `name`, `description`, `domain`, `rationale`, `alternatives`, `date`, `status`, `created_at` \| Architectural decision record; status: `proposed`, `accepted`, `deprecated`, `superseded` \|
27	\| `WikiPage` \| `title`, `content`, `url`, `source`, `updated_at` \| Wiki page or document \|
28	\| `Person` \| `name`, `email`, `role`, `team`, `created_at` \| Team member or contributor \|
29
30	---
31
32	## Edge types
33
34	\| Edge \| From \| To \| Meaning \|
35	\|---\|---\|---\|---\|
36	\| `CONTAINS` \| Repository, File, Module, Class \| File, Class, Function, Method, Variable, Import \| Structural containment \|
37	\| `DEFINES` \| File, Class \| Class, Function, Method \| Definition site \|
38	\| `IMPORTS` \| File \| Import \| File imports a module or symbol \|
39	\| `DEPENDS_ON` \| File, Module \| File, Module \| Module-level dependency \|
40	\| `CALLS` \| Function, Method \| Function, Method \| Direct function call (static analysis) \|
41	\| `REFERENCES` \| Function, Method, File \| Variable, Class, Function \| Name reference (not a call) \|
42	\| `INHERITS` \| Class \| Class \| Class inherits from parent \|
43	\| `IMPLEMENTS` \| Class, Function \| Concept \| Code implements a concept or interface \|
44	\| `DECORATES` \| Decorator \| Function, Method, Class \| Decorator applied to target \|
45	\| `BELONGS_TO` \| Concept, Rule, Decision, Person \| Domain \| Membership in a domain \|
46	\| `RELATED_TO` \| Any \| Any \| General semantic relationship \|
47	\| `GOVERNS` \| Rule \| Function, Method, Class, File \| Rule applies to code node \|
48	\| `DOCUMENTS` \| WikiPage \| Concept, Function, Class, File \| Documentation relationship \|
49	\| `ANNOTATES` \| Concept, Rule \| Function, Method, Class, File, Module \| Knowledge node annotates code node \|
50	\| `ASSIGNED_TO` \| Rule, Decision \| Person \| Work item or decision assigned to person \|
51	\| `DECIDED_BY` \| Decision \| Person \| Decision was made by person \|
52
53	---
54
55	## Schema diagram
56
57	```mermaid
58	graph LR
59	subgraph Knowledge["Knowledge Layer"]
60	Domain
61	Concept
62	Rule
63	Decision
64	WikiPage
65	Person
66	end
67
68	subgraph Code["Code Layer"]
69	Repository
70	File
71	Module
72	Class
73	Function
74	Method
75	Decorator
76	Import
77	Variable
78	end
79
80	Repository -->\|CONTAINS\| File
81	File -->\|CONTAINS\| Class
82	File -->\|CONTAINS\| Function
83	File -->\|IMPORTS\| Import
84	Class -->\|DEFINES\| Method
85	Function -->\|CALLS\| Function
86	Method -->\|CALLS\| Function
87	Method -->\|CALLS\| Method
88	Class -->\|INHERITS\| Class
89	Decorator -->\|DECORATES\| Function
90	Decorator -->\|DECORATES\| Class
91	Decorator -->\|DECORATES\| Method
92
93	Domain -->\|"(inverse) BELONGS_TO"\| Concept
94	Domain -->\|"(inverse) BELONGS_TO"\| Rule
95	Domain -->\|"(inverse) BELONGS_TO"\| Decision
96	WikiPage -->\|DOCUMENTS\| Concept
97	WikiPage -->\|DOCUMENTS\| Function
98
99	Rule -->\|GOVERNS\| Function
100	Rule -->\|GOVERNS\| Class
101	Concept -->\|ANNOTATES\| Function
102	Concept -->\|ANNOTATES\| Class
103	Class -->\|IMPLEMENTS\| Concept
104	Decision -->\|DECIDED_BY\| Person
105	Rule -->\|ASSIGNED_TO\| Person
106	```
107
108	---
109
110	## Code vs knowledge layer distinction
111
112	The two layers have different lifecycle and provenance:
113
114	\| Dimension \| Code layer \| Knowledge layer \|
115	\|---\|---\|---\|
116	\| Source \| tree-sitter AST parsing \| Manual curation, wiki, Planopticon \|
117	\| Refresh \| On every `navegador ingest` \| On demand (`navegador add`, `wiki ingest`, `planopticon ingest`) \|
118	\| Change rate \| Fast (changes with every commit) \| Slow (changes with design decisions) \|
119	\| Authorship \| Derived from code \| Human or meeting-authored \|
120	\| Queryability \| Names, signatures, call graphs \| Domain semantics, rationale, history \|
121
122	Cross-layer edges (`ANNOTATES`, `GOVERNS`, `IMPLEMENTS`, `DOCUMENTS`) are the join points between the two layers. They are created explicitly by humans via `navegador annotate` or inferred during wiki/Planopticon ingestion.
123

M docs/architecture/overview.md

+135 -2

		--- docs/architecture/overview.md
		+++ docs/architecture/overview.md
		@@ -1,3 +1,136 @@
1		-# overview
	1	+# Architecture Overview
	2	+
	3	+## Design philosophy
	4	+
	5	+Navegador is built around a single observation: code structure and business knowledge are both graph-shaped, and they belong in the same graph.
	6	+
	7	+Most context tools for AI agents handle one or the other — either they parse code (AST tools, code search) or they surface docs (RAG over wikis, ADR files). Navegador stores both in the same property graph and connects them with typed edges. An agent asking "what does `process_payment` do?" gets back not just the function signature and call graph, but the business rules that govern it and the architectural decision that shaped its design — in a single structured query.
	8	+
	9	+---
	10	+
	11	+## Two-layer design
	12	+
	13	+```
	14	+┌──────────────────────────────────────────────────────────────────┐
	15	+│ KNOWLEDGE LAYER │
	16	+│ │
	17	+│ Domain ──BELONGS_TO── Concept ──RELATED_TO── Rule │
	18	+│ │ │ │ │
	19	+│ └──BELONGS_TO── Decision GOVERNS │ │
	20	+│ │ ↓ │
	21	+│ DECIDED_BY── Person (code nodes) │
	22	+│ │
	23	+│ WikiPage ──DOCUMENTS── Concept │
	24	+│ │
	25	+├──────────────── ANNOTATES / GOVERNS / IMPLEMENTS ────────────────┤
	26	+│ │
	27	+│ CODE LAYER │
	28	+│ │
	29	+│ Repository ──CONTAINS── File ──CONTAINS── Class │
	30	+│ │ │ │
	31	+│ CONTAINS DEFINES │
	32	+│ ↓ ↓ │
	33	+│ Function ──CALLS── Function │
	34	+│ │ │
	35	+│ DECORATES── Decorator │
	36	+│ │ │
	37	+│ IMPORTS── Import │
	38	+└──────────────────────────────────────────────────────────────────┘
	39	+```
	40	+
	41	+### Code layer
	42	+
	43	+Populated automatically by `navegador ingest`. Contains the structural facts extracted from source code: which functions exist, what they call, which classes inherit from which, what decorators are applied. This layer changes whenever code changes; re-ingest is the refresh mechanism.
	44	+
	45	+### Knowledge layer
	46	+
	47	+Populated by humans (via `navegador add`) or semi-automatically (via wiki and Planopticon ingestion). Contains the why: business concepts, architectural rules, recorded decisions, domain ownership, and documentation. This layer changes slowly and deliberately.
	48	+
	49	+### Cross-layer edges
	50	+
	51	+\| Edge \| Meaning \| Direction \|
	52	+\|---\|---\|---\|
	53	+\| `ANNOTATES` \| A knowledge node describes a code node \| Concept/Rule → Function/Class/File \|
	54	+\| `GOVERNS` \| A rule applies to a code node \| Rule → Function/Class \|
	55	+\| `IMPLEMENTS` \| A code node implements a concept or interface \| Function/Class → Concept/Interface \|
	56	+\| `DOCUMENTS` \| A wiki page documents a concept or code node \| WikiPage → Concept/Function/Class \|
	57	+
	58	+These edges are created explicitly via `navegador annotate` or inferred during wiki/Planopticon ingestion when names match.
	59	+
	60	+---
	61	+
	62	+## FalkorDB as the store
	63	+
	64	+Navegador uses [FalkorDB](https://www.falkordb.com/) — a property graph database with a Cypher query interface.
	65	+
	66	+\| Environment \| Backend \| Install \|
	67	+\|---\|---\|---\|
	68	+\| Local dev \| `falkordblite` (SQLite) \| Included in `pip install navegador` \|
	69	+\| Production / team \| FalkorDB on Redis \| `pip install "navegador[redis]"` \|
	70	+
	71	+Both backends implement the same `GraphStore` interface. The query path is identical; only the connection setup differs. The SQLite backend uses an embedded engine — no daemon, no port, just a `.db` file.
	72	+
	73	+---
	74	+
	75	+## Ingestion pipeline
	76	+
	77	+```
	78	+Source code (Python, TypeScript)
	79	+ │
	80	+ ▼
	81	+ tree-sitter parser
	82	+ │
	83	+ ▼
	84	+ AST visitor (extract nodes + relationships)
	85	+ │
	86	+ ▼
	87	+ GraphStore.merge_node / create_edge
	88	+ │
	89	+ ▼
	90	+ FalkorDB (SQLite or Redis)
	91	+```
	92	+
	93	+```
	94	+Human curation (navegador add)
	95	+Wiki pages (navegador wiki ingest)
	96	+Planopticon output (navegador planopticon ingest)
	97	+ │
	98	+ ▼
	99	+ KnowledgeIngester / WikiIngester / PlanopticonIngester
	100	+ │
	101	+ ▼
	102	+ GraphStore.merge_node / create_edge
	103	+ │
	104	+ ▼
	105	+ FalkorDB (same database)
	106	+```
	107	+
	108	+All ingesters write to the same graph. There is no separate code database and knowledge database.
	109	+
	110	+---
	111	+
	112	+## Query path
	113	+
	114	+```
	115	+User / agent
	116	+ │
	117	+ ▼ CLI command or MCP tool call
	118	+navegador context / function / explain / search / ...
	119	+ │
	120	+ ▼
	121	+ContextLoader (builds Cypher query)
	122	+ │
	123	+ ▼
	124	+GraphStore.query(cypher)
	125	+ │
	126	+ ▼
	127	+FalkorDB (SQLite or Redis)
	128	+ │
	129	+ ▼
	130	+ContextBundle (structured result)
	131	+ │
	132	+ ▼
	133	+JSON / Markdown / rich terminal output
	134	+```
2	135
3		-Documentation coming soon.
	136	+`ContextLoader` is the query abstraction layer. Each command (`function`, `class`, `explain`, etc.) corresponds to a `ContextLoader` method that constructs the appropriate Cypher query, fetches results, and assembles a `ContextBundle`. The CLI formats the bundle for output; the MCP server returns it as JSON.
4	137

	--- docs/architecture/overview.md
	+++ docs/architecture/overview.md
	@@ -1,3 +1,136 @@
1	# overview





































































































































2
3	Documentation coming soon.
4

	--- docs/architecture/overview.md
	+++ docs/architecture/overview.md
	@@ -1,3 +1,136 @@
1	# Architecture Overview
2
3	## Design philosophy
4
5	Navegador is built around a single observation: code structure and business knowledge are both graph-shaped, and they belong in the same graph.
6
7	Most context tools for AI agents handle one or the other — either they parse code (AST tools, code search) or they surface docs (RAG over wikis, ADR files). Navegador stores both in the same property graph and connects them with typed edges. An agent asking "what does `process_payment` do?" gets back not just the function signature and call graph, but the business rules that govern it and the architectural decision that shaped its design — in a single structured query.
8
9	---
10
11	## Two-layer design
12
13	```
14	┌──────────────────────────────────────────────────────────────────┐
15	│ KNOWLEDGE LAYER │
16	│ │
17	│ Domain ──BELONGS_TO── Concept ──RELATED_TO── Rule │
18	│ │ │ │ │
19	│ └──BELONGS_TO── Decision GOVERNS │ │
20	│ │ ↓ │
21	│ DECIDED_BY── Person (code nodes) │
22	│ │
23	│ WikiPage ──DOCUMENTS── Concept │
24	│ │
25	├──────────────── ANNOTATES / GOVERNS / IMPLEMENTS ────────────────┤
26	│ │
27	│ CODE LAYER │
28	│ │
29	│ Repository ──CONTAINS── File ──CONTAINS── Class │
30	│ │ │ │
31	│ CONTAINS DEFINES │
32	│ ↓ ↓ │
33	│ Function ──CALLS── Function │
34	│ │ │
35	│ DECORATES── Decorator │
36	│ │ │
37	│ IMPORTS── Import │
38	└──────────────────────────────────────────────────────────────────┘
39	```
40
41	### Code layer
42
43	Populated automatically by `navegador ingest`. Contains the structural facts extracted from source code: which functions exist, what they call, which classes inherit from which, what decorators are applied. This layer changes whenever code changes; re-ingest is the refresh mechanism.
44
45	### Knowledge layer
46
47	Populated by humans (via `navegador add`) or semi-automatically (via wiki and Planopticon ingestion). Contains the why: business concepts, architectural rules, recorded decisions, domain ownership, and documentation. This layer changes slowly and deliberately.
48
49	### Cross-layer edges
50
51	\| Edge \| Meaning \| Direction \|
52	\|---\|---\|---\|
53	\| `ANNOTATES` \| A knowledge node describes a code node \| Concept/Rule → Function/Class/File \|
54	\| `GOVERNS` \| A rule applies to a code node \| Rule → Function/Class \|
55	\| `IMPLEMENTS` \| A code node implements a concept or interface \| Function/Class → Concept/Interface \|
56	\| `DOCUMENTS` \| A wiki page documents a concept or code node \| WikiPage → Concept/Function/Class \|
57
58	These edges are created explicitly via `navegador annotate` or inferred during wiki/Planopticon ingestion when names match.
59
60	---
61
62	## FalkorDB as the store
63
64	Navegador uses [FalkorDB](https://www.falkordb.com/) — a property graph database with a Cypher query interface.
65
66	\| Environment \| Backend \| Install \|
67	\|---\|---\|---\|
68	\| Local dev \| `falkordblite` (SQLite) \| Included in `pip install navegador` \|
69	\| Production / team \| FalkorDB on Redis \| `pip install "navegador[redis]"` \|
70
71	Both backends implement the same `GraphStore` interface. The query path is identical; only the connection setup differs. The SQLite backend uses an embedded engine — no daemon, no port, just a `.db` file.
72
73	---
74
75	## Ingestion pipeline
76
77	```
78	Source code (Python, TypeScript)
79	│
80	▼
81	tree-sitter parser
82	│
83	▼
84	AST visitor (extract nodes + relationships)
85	│
86	▼
87	GraphStore.merge_node / create_edge
88	│
89	▼
90	FalkorDB (SQLite or Redis)
91	```
92
93	```
94	Human curation (navegador add)
95	Wiki pages (navegador wiki ingest)
96	Planopticon output (navegador planopticon ingest)
97	│
98	▼
99	KnowledgeIngester / WikiIngester / PlanopticonIngester
100	│
101	▼
102	GraphStore.merge_node / create_edge
103	│
104	▼
105	FalkorDB (same database)
106	```
107
108	All ingesters write to the same graph. There is no separate code database and knowledge database.
109
110	---
111
112	## Query path
113
114	```
115	User / agent
116	│
117	▼ CLI command or MCP tool call
118	navegador context / function / explain / search / ...
119	│
120	▼
121	ContextLoader (builds Cypher query)
122	│
123	▼
124	GraphStore.query(cypher)
125	│
126	▼
127	FalkorDB (SQLite or Redis)
128	│
129	▼
130	ContextBundle (structured result)
131	│
132	▼
133	JSON / Markdown / rich terminal output
134	```
135
136	`ContextLoader` is the query abstraction layer. Each command (`function`, `class`, `explain`, etc.) corresponds to a `ContextLoader` method that constructs the appropriate Cypher query, fetches results, and assembles a `ContextBundle`. The CLI formats the bundle for output; the MCP server returns it as JSON.
137

M docs/getting-started/configuration.md

+104 -2

		--- docs/getting-started/configuration.md
		+++ docs/getting-started/configuration.md
		@@ -1,3 +1,105 @@
1		-# configuration
	1	+# Configuration
	2	+
	3	+Navegador has minimal required configuration. The only thing you typically need to set is where the graph database lives.
	4	+
	5	+---
	6	+
	7	+## Database path
	8	+
	9	+### SQLite (default)
	10	+
	11	+By default navegador writes a `navegador.db` file in the current working directory. Override with the `--db` flag or the `NAVEGADOR_DB` environment variable:
	12	+
	13	+```bash
	14	+# flag (takes precedence)
	15	+navegador ingest ./repo --db ~/.navegador/myproject.db
	16	+
	17	+# environment variable
	18	+export NAVEGADOR_DB=~/.navegador/myproject.db
	19	+navegador ingest ./repo
	20	+```
	21	+
	22	+The `.navegador/` directory convention keeps the database alongside your project:
	23	+
	24	+```
	25	+my-project/
	26	+ .navegador/
	27	+ navegador.db ← graph database
	28	+ src/
	29	+ ...
	30	+```
	31	+
	32	+Add `.navegador/` to `.gitignore` — the database is a build artifact, not source.
	33	+
	34	+### Redis (production)
	35	+
	36	+For team or CI environments, point `NAVEGADOR_DB` at a Redis instance running FalkorDB:
	37	+
	38	+```bash
	39	+export NAVEGADOR_DB=redis://localhost:6379
	40	+```
	41	+
	42	+With authentication:
	43	+
	44	+```bash
	45	+export NAVEGADOR_DB=redis://:[email protected]:6379
	46	+```
	47	+
	48	+Install the Redis extra if you haven't already:
	49	+
	50	+```bash
	51	+pip install "navegador[redis]"
	52	+```
	53	+
	54	+---
	55	+
	56	+## SQLite vs Redis: when to use which
	57	+
	58	+\| \| SQLite (falkordblite) \| Redis (FalkorDB) \|
	59	+\|---\|---\|---\|
	60	+\| Setup \| Zero config \| Requires a Redis server \|
	61	+\| Use case \| Local dev, single developer \| Team, CI, shared context \|
	62	+\| Persistence \| Local file \| Redis persistence config \|
	63	+\| Performance \| Fast for single-user workloads \| Scales to large codebases \|
	64	+\| Extra required \| None (included) \| `navegador[redis]` \|
	65	+
	66	+Both backends implement the same `GraphStore` interface. You can migrate by re-ingesting against the new backend.
	67	+
	68	+---
	69	+
	70	+## GitHub token
	71	+
	72	+Required for `navegador wiki ingest --repo owner/repo` to access private wikis or to avoid rate limits on public repos.
	73	+
	74	+```bash
	75	+export GITHUB_TOKEN=ghp_...
	76	+navegador wiki ingest --repo myorg/myrepo
	77	+```
	78	+
	79	+For public repos, wiki ingestion works without a token but will hit GitHub's unauthenticated rate limit (60 req/hr).
	80	+
	81	+---
	82	+
	83	+## Environment variable reference
	84	+
	85	+\| Variable \| Default \| Description \|
	86	+\|---\|---\|---\|
	87	+\| `NAVEGADOR_DB` \| `./navegador.db` \| Path to SQLite file or `redis://` URL \|
	88	+\| `GITHUB_TOKEN` \| — \| GitHub personal access token for wiki ingestion \|
	89	+
	90	+---
	91	+
	92	+## Project-local config
	93	+
	94	+Drop a `.navegador/config.toml` in your project root for project-specific defaults (optional):
	95	+
	96	+```toml
	97	+[database]
	98	+path = ".navegador/navegador.db"
	99	+
	100	+[ingest]
	101	+exclude = ["node_modules", "dist", ".venv", "migrations"]
	102	+```
2	103
3		-Documentation coming soon.
	104	+!!! note
	105	+ `.navegador/config.toml` support is planned. Check `navegador --version` to confirm it is available in your installed version.
4	106

	--- docs/getting-started/configuration.md
	+++ docs/getting-started/configuration.md
	@@ -1,3 +1,105 @@
1	# configuration





































































































2
3	Documentation coming soon.

4

	--- docs/getting-started/configuration.md
	+++ docs/getting-started/configuration.md
	@@ -1,3 +1,105 @@
1	# Configuration
2
3	Navegador has minimal required configuration. The only thing you typically need to set is where the graph database lives.
4
5	---
6
7	## Database path
8
9	### SQLite (default)
10
11	By default navegador writes a `navegador.db` file in the current working directory. Override with the `--db` flag or the `NAVEGADOR_DB` environment variable:
12
13	```bash
14	# flag (takes precedence)
15	navegador ingest ./repo --db ~/.navegador/myproject.db
16
17	# environment variable
18	export NAVEGADOR_DB=~/.navegador/myproject.db
19	navegador ingest ./repo
20	```
21
22	The `.navegador/` directory convention keeps the database alongside your project:
23
24	```
25	my-project/
26	.navegador/
27	navegador.db ← graph database
28	src/
29	...
30	```
31
32	Add `.navegador/` to `.gitignore` — the database is a build artifact, not source.
33
34	### Redis (production)
35
36	For team or CI environments, point `NAVEGADOR_DB` at a Redis instance running FalkorDB:
37
38	```bash
39	export NAVEGADOR_DB=redis://localhost:6379
40	```
41
42	With authentication:
43
44	```bash
45	export NAVEGADOR_DB=redis://:[email protected]:6379
46	```
47
48	Install the Redis extra if you haven't already:
49
50	```bash
51	pip install "navegador[redis]"
52	```
53
54	---
55
56	## SQLite vs Redis: when to use which
57
58	\| \| SQLite (falkordblite) \| Redis (FalkorDB) \|
59	\|---\|---\|---\|
60	\| Setup \| Zero config \| Requires a Redis server \|
61	\| Use case \| Local dev, single developer \| Team, CI, shared context \|
62	\| Persistence \| Local file \| Redis persistence config \|
63	\| Performance \| Fast for single-user workloads \| Scales to large codebases \|
64	\| Extra required \| None (included) \| `navegador[redis]` \|
65
66	Both backends implement the same `GraphStore` interface. You can migrate by re-ingesting against the new backend.
67
68	---
69
70	## GitHub token
71
72	Required for `navegador wiki ingest --repo owner/repo` to access private wikis or to avoid rate limits on public repos.
73
74	```bash
75	export GITHUB_TOKEN=ghp_...
76	navegador wiki ingest --repo myorg/myrepo
77	```
78
79	For public repos, wiki ingestion works without a token but will hit GitHub's unauthenticated rate limit (60 req/hr).
80
81	---
82
83	## Environment variable reference
84
85	\| Variable \| Default \| Description \|
86	\|---\|---\|---\|
87	\| `NAVEGADOR_DB` \| `./navegador.db` \| Path to SQLite file or `redis://` URL \|
88	\| `GITHUB_TOKEN` \| — \| GitHub personal access token for wiki ingestion \|
89
90	---
91
92	## Project-local config
93
94	Drop a `.navegador/config.toml` in your project root for project-specific defaults (optional):
95
96	```toml
97	[database]
98	path = ".navegador/navegador.db"
99
100	[ingest]
101	exclude = ["node_modules", "dist", ".venv", "migrations"]
102	```
103
104	!!! note
105	`.navegador/config.toml` support is planned. Check `navegador --version` to confirm it is available in your installed version.
106

M docs/getting-started/installation.md

+75 -2

		--- docs/getting-started/installation.md
		+++ docs/getting-started/installation.md
		@@ -1,3 +1,76 @@
1		-# installation
	1	+# Installation
	2	+
	3	+## Requirements
	4	+
	5	+- Python 3.12 or later — required by `falkordblite`, the embedded SQLite backend
	6	+- pip 23+
	7	+
	8	+## Install
	9	+
	10	+```bash
	11	+pip install navegador
	12	+```
	13	+
	14	+This installs the core package with the SQLite backend (`falkordblite`) included. No external services are required for local use.
	15	+
	16	+## Optional extras
	17	+
	18	+=== "[sqlite]"
	19	+
	20	+ The default. `falkordblite` is bundled and requires no configuration. This is what `pip install navegador` already gives you.
	21	+
	22	+ ```bash
	23	+ pip install "navegador[sqlite]" # explicit, same as above
	24	+ ```
	25	+
	26	+ !!! note
	27	+ `falkordblite` requires Python 3.12+. Its embedded SQLite graph engine uses features not available in earlier Python versions.
	28	+
	29	+=== "[redis]"
	30	+
	31	+ For production deployments backed by a Redis instance running FalkorDB.
	32	+
	33	+ ```bash
	34	+ pip install "navegador[redis]"
	35	+ ```
	36	+
	37	+ Then point navegador at your Redis instance:
	38	+
	39	+ ```bash
	40	+ export NAVEGADOR_DB=redis://localhost:6379
	41	+ navegador ingest ./repo
	42	+ ```
	43	+
	44	+ See [Configuration](configuration.md) for full Redis setup details.
	45	+
	46	+## Verify
	47	+
	48	+```bash
	49	+navegador --version
	50	+```
	51	+
	52	+Expected output:
	53	+
	54	+```
	55	+navegador, version 0.x.y
	56	+```
	57	+
	58	+## Development install
	59	+
	60	+```bash
	61	+git clone https://github.com/ConflictHQ/navegador
	62	+cd navegador
	63	+pip install -e ".[sqlite,redis]"
	64	+```
	65	+
	66	+## Upgrading
	67	+
	68	+```bash
	69	+pip install --upgrade navegador
	70	+```
	71	+
	72	+After upgrading, re-ingest any existing repos to pick up new parser features or schema changes:
2	73
3		-Documentation coming soon.
	74	+```bash
	75	+navegador ingest ./repo --clear
	76	+```
4	77

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -1,3 +1,76 @@
1	# installation







































































2
3	Documentation coming soon.


4

	--- docs/getting-started/installation.md
	+++ docs/getting-started/installation.md
	@@ -1,3 +1,76 @@
1	# Installation
2
3	## Requirements
4
5	- Python 3.12 or later — required by `falkordblite`, the embedded SQLite backend
6	- pip 23+
7
8	## Install
9
10	```bash
11	pip install navegador
12	```
13
14	This installs the core package with the SQLite backend (`falkordblite`) included. No external services are required for local use.
15
16	## Optional extras
17
18	=== "[sqlite]"
19
20	The default. `falkordblite` is bundled and requires no configuration. This is what `pip install navegador` already gives you.
21
22	```bash
23	pip install "navegador[sqlite]" # explicit, same as above
24	```
25
26	!!! note
27	`falkordblite` requires Python 3.12+. Its embedded SQLite graph engine uses features not available in earlier Python versions.
28
29	=== "[redis]"
30
31	For production deployments backed by a Redis instance running FalkorDB.
32
33	```bash
34	pip install "navegador[redis]"
35	```
36
37	Then point navegador at your Redis instance:
38
39	```bash
40	export NAVEGADOR_DB=redis://localhost:6379
41	navegador ingest ./repo
42	```
43
44	See [Configuration](configuration.md) for full Redis setup details.
45
46	## Verify
47
48	```bash
49	navegador --version
50	```
51
52	Expected output:
53
54	```
55	navegador, version 0.x.y
56	```
57
58	## Development install
59
60	```bash
61	git clone https://github.com/ConflictHQ/navegador
62	cd navegador
63	pip install -e ".[sqlite,redis]"
64	```
65
66	## Upgrading
67
68	```bash
69	pip install --upgrade navegador
70	```
71
72	After upgrading, re-ingest any existing repos to pick up new parser features or schema changes:
73
74	```bash
75	navegador ingest ./repo --clear
76	```
77

M docs/getting-started/quickstart.md

+139 -2

		--- docs/getting-started/quickstart.md
		+++ docs/getting-started/quickstart.md
		@@ -1,3 +1,140 @@
1		-# quickstart
	1	+# Quick Start
	2	+
	3	+This guide walks from a fresh install to a fully wired agent integration in five steps.
	4	+
	5	+---
	6	+
	7	+## Step 1: Install
	8	+
	9	+```bash
	10	+pip install navegador
	11	+navegador --version
	12	+```
	13	+
	14	+Python 3.12+ is required. See [Installation](installation.md) for extras and Redis setup.
	15	+
	16	+---
	17	+
	18	+## Step 2: Ingest a repo
	19	+
	20	+Point navegador at any local source tree:
	21	+
	22	+```bash
	23	+navegador ingest ./my-repo
	24	+```
	25	+
	26	+On first run this builds the graph from scratch. Re-run anytime to pick up changes. Use `--clear` to wipe and rebuild:
	27	+
	28	+```bash
	29	+navegador ingest ./my-repo --clear
	30	+```
	31	+
	32	+Use `--json` to get a machine-readable summary of what was indexed:
	33	+
	34	+```bash
	35	+navegador ingest ./my-repo --json
	36	+```
	37	+
	38	+Navegador walks the tree, parses every `.py` and `.ts`/`.tsx` file with tree-sitter, and writes nodes and edges for: files, modules, classes, functions, methods, imports, decorators, and call relationships.
	39	+
	40	+---
	41	+
	42	+## Step 3: Query the graph
	43	+
	44	+Explain anything by name — works for functions, classes, files, concepts, rules, and decisions:
	45	+
	46	+```bash
	47	+navegador explain AuthService
	48	+navegador explain validate_token
	49	+navegador explain src/payments/processor.py
	50	+```
	51	+
	52	+Search across code and knowledge together:
	53	+
	54	+```bash
	55	+navegador search "rate limit" --all
	56	+navegador search "authentication" --docs --limit 10
	57	+```
	58	+
	59	+Inspect a function (callers, callees, decorators, source):
	60	+
	61	+```bash
	62	+navegador function validate_token
	63	+navegador function validate_token --depth 2 --format json
	64	+```
	65	+
	66	+Inspect a class (hierarchy, methods, references):
	67	+
	68	+```bash
	69	+navegador class PaymentProcessor
	70	+navegador class PaymentProcessor --format json
	71	+```
	72	+
	73	+---
	74	+
	75	+## Step 4: Add business knowledge
	76	+
	77	+Code alone doesn't capture why. Add concepts, rules, and decisions and link them to code.
	78	+
	79	+Add a concept:
	80	+
	81	+```bash
	82	+navegador add concept "Idempotency" \
	83	+ --desc "Operations that can be retried safely without side effects" \
	84	+ --domain Payments
	85	+```
	86	+
	87	+Add a rule:
	88	+
	89	+```bash
	90	+navegador add rule "PaymentsMustBeIdempotent" \
	91	+ --desc "All payment endpoints must handle duplicate submissions" \
	92	+ --domain Payments \
	93	+ --severity critical \
	94	+ --rationale "Card networks retry on timeout; double-charging causes chargebacks"
	95	+```
	96	+
	97	+Annotate code with a concept or rule:
	98	+
	99	+```bash
	100	+navegador annotate process_payment \
	101	+ --type Function \
	102	+ --concept Idempotency \
	103	+ --rule PaymentsMustBeIdempotent
	104	+```
	105	+
	106	+Add a decision:
	107	+
	108	+```bash
	109	+navegador add decision "UseStripeForPayments" \
	110	+ --desc "Stripe is the primary payment processor" \
	111	+ --domain Payments \
	112	+ --rationale "Best fraud tooling for SaaS" \
	113	+ --alternatives "Braintree, Adyen" \
	114	+ --date 2025-01-15 \
	115	+ --status accepted
	116	+```
	117	+
	118	+Now `navegador explain process_payment` returns code structure and the rules that govern it.
	119	+
	120	+---
	121	+
	122	+## Step 5: Wire an agent hook
	123	+
	124	+Use the bootstrap script to ingest your repo and install the hook for your AI coding assistant in one command:
	125	+
	126	+```bash
	127	+./bootstrap.sh --repo owner/repo --wiki --agent claude
	128	+```
	129	+
	130	+Options:
	131	+
	132	+\| Flag \| Effect \|
	133	+\|---\|---\|
	134	+\| `--repo owner/repo` \| GitHub repo to clone + ingest \|
	135	+\| `--wiki` \| Also ingest the GitHub wiki \|
	136	+\| `--agent claude` \| Install `.claude/hooks/claude-hook.py` \|
	137	+\| `--agent gemini` \| Install `.gemini/hooks/gemini-hook.py` \|
	138	+\| `--agent openai` \| Install `openai-hook.py` + `openai-tools.json` \|
2	139
3		-Documentation coming soon.
	140	+After bootstrap, every file the agent edits triggers a re-ingest so the graph stays in sync. See [Agent Hooks](../guide/agent-hooks.md) for manual setup and the `NAVEGADOR.md` template.
4	141
5	142	ADDED docs/guide/agent-hooks.md

	--- docs/getting-started/quickstart.md
	+++ docs/getting-started/quickstart.md
	@@ -1,3 +1,140 @@
1	# quickstart









































































































































2
3	Documentation coming soon.
4
5	DDED docs/guide/agent-hooks.md

	--- docs/getting-started/quickstart.md
	+++ docs/getting-started/quickstart.md
	@@ -1,3 +1,140 @@
1	# Quick Start
2
3	This guide walks from a fresh install to a fully wired agent integration in five steps.
4
5	---
6
7	## Step 1: Install
8
9	```bash
10	pip install navegador
11	navegador --version
12	```
13
14	Python 3.12+ is required. See [Installation](installation.md) for extras and Redis setup.
15
16	---
17
18	## Step 2: Ingest a repo
19
20	Point navegador at any local source tree:
21
22	```bash
23	navegador ingest ./my-repo
24	```
25
26	On first run this builds the graph from scratch. Re-run anytime to pick up changes. Use `--clear` to wipe and rebuild:
27
28	```bash
29	navegador ingest ./my-repo --clear
30	```
31
32	Use `--json` to get a machine-readable summary of what was indexed:
33
34	```bash
35	navegador ingest ./my-repo --json
36	```
37
38	Navegador walks the tree, parses every `.py` and `.ts`/`.tsx` file with tree-sitter, and writes nodes and edges for: files, modules, classes, functions, methods, imports, decorators, and call relationships.
39
40	---
41
42	## Step 3: Query the graph
43
44	Explain anything by name — works for functions, classes, files, concepts, rules, and decisions:
45
46	```bash
47	navegador explain AuthService
48	navegador explain validate_token
49	navegador explain src/payments/processor.py
50	```
51
52	Search across code and knowledge together:
53
54	```bash
55	navegador search "rate limit" --all
56	navegador search "authentication" --docs --limit 10
57	```
58
59	Inspect a function (callers, callees, decorators, source):
60
61	```bash
62	navegador function validate_token
63	navegador function validate_token --depth 2 --format json
64	```
65
66	Inspect a class (hierarchy, methods, references):
67
68	```bash
69	navegador class PaymentProcessor
70	navegador class PaymentProcessor --format json
71	```
72
73	---
74
75	## Step 4: Add business knowledge
76
77	Code alone doesn't capture why. Add concepts, rules, and decisions and link them to code.
78
79	Add a concept:
80
81	```bash
82	navegador add concept "Idempotency" \
83	--desc "Operations that can be retried safely without side effects" \
84	--domain Payments
85	```
86
87	Add a rule:
88
89	```bash
90	navegador add rule "PaymentsMustBeIdempotent" \
91	--desc "All payment endpoints must handle duplicate submissions" \
92	--domain Payments \
93	--severity critical \
94	--rationale "Card networks retry on timeout; double-charging causes chargebacks"
95	```
96
97	Annotate code with a concept or rule:
98
99	```bash
100	navegador annotate process_payment \
101	--type Function \
102	--concept Idempotency \
103	--rule PaymentsMustBeIdempotent
104	```
105
106	Add a decision:
107
108	```bash
109	navegador add decision "UseStripeForPayments" \
110	--desc "Stripe is the primary payment processor" \
111	--domain Payments \
112	--rationale "Best fraud tooling for SaaS" \
113	--alternatives "Braintree, Adyen" \
114	--date 2025-01-15 \
115	--status accepted
116	```
117
118	Now `navegador explain process_payment` returns code structure and the rules that govern it.
119
120	---
121
122	## Step 5: Wire an agent hook
123
124	Use the bootstrap script to ingest your repo and install the hook for your AI coding assistant in one command:
125
126	```bash
127	./bootstrap.sh --repo owner/repo --wiki --agent claude
128	```
129
130	Options:
131
132	\| Flag \| Effect \|
133	\|---\|---\|
134	\| `--repo owner/repo` \| GitHub repo to clone + ingest \|
135	\| `--wiki` \| Also ingest the GitHub wiki \|
136	\| `--agent claude` \| Install `.claude/hooks/claude-hook.py` \|
137	\| `--agent gemini` \| Install `.gemini/hooks/gemini-hook.py` \|
138	\| `--agent openai` \| Install `openai-hook.py` + `openai-tools.json` \|
139
140	After bootstrap, every file the agent edits triggers a re-ingest so the graph stays in sync. See [Agent Hooks](../guide/agent-hooks.md) for manual setup and the `NAVEGADOR.md` template.
141
142	DDED docs/guide/agent-hooks.md

A docs/guide/agent-hooks.md

+215

		--- a/docs/guide/agent-hooks.md
		+++ b/docs/guide/agent-hooks.md
		@@ -0,0 +1,215 @@
	1	+# Agent Hooks
	2	+
	3	+Agent hooks keep the navegador graph in sync as AI coding agents work. Without hooks, the graph goes stale the moment an agent edits a file. With hooks, the graph is re-ingested automatically after every file write, and architectural decisions in `DECISIONS.md` are synced into the knowledge layer.
	4	+
	5	+---
	6	+
	7	+## Why hooks
	8	+
	9	+A stale graph gives wrong answers. If an agent adds a new function and then asks `navegador function` about a caller, the graph needs to reflect the edit. Hooks solve this by triggering `navegador ingest` on the modified files immediately after the agent writes them.
	10	+
	11	+Hooks also enforce the habit: every agent session starts with the graph as ground truth, not a stale snapshot.
	12	+
	13	+---
	14	+
	15	+## Claude Code
	16	+
	17	+### Install
	18	+
	19	+The hook file lives at `.claude/hooks/claude-hook.py`. Bootstrap installs it automatically:
	20	+
	21	+```bash
	22	+./bootstrap.sh --repo owner/repo --agent claude
	23	+```
	24	+
	25	+To install manually, copy `hooks/claude-hook.py` from the navegador repo into your project's `.claude/hooks/` directory.
	26	+
	27	+### settings.json config
	28	+
	29	+In your project's `.claude/settings.json`, register the hook:
	30	+
	31	+```json
	32	+{
	33	+ "hooks": {
	34	+ "PostToolUse": [
	35	+ {
	36	+ "matcher": "Write\|Edit\|MultiEdit",
	37	+ "hooks": [
	38	+ {
	39	+ "type": "command",
	40	+ "command": "python .claude/hooks/claude-hook.py"
	41	+ }
	42	+ ]
	43	+ }
	44	+ ]
	45	+ }
	46	+}
	47	+```
	48	+
	49	+### What the hook does
	50	+
	51	+On every `Write`, `Edit`, or `MultiEdit` tool call:
	52	+
	53	+1. Reads the list of modified file paths from the tool result
	54	+2. Runs `navegador ingest` scoped to those files (fast incremental update)
	55	+3. Checks for changes to `DECISIONS.md` — if found, syncs any new ADR entries into the graph as `Decision` nodes
	56	+4. Logs a one-line summary to stderr (visible in Claude's tool output)
	57	+
	58	+---
	59	+
	60	+## Gemini CLI
	61	+
	62	+### Install
	63	+
	64	+The hook file lives at `.gemini/hooks/gemini-hook.py`. Bootstrap installs it automatically:
	65	+
	66	+```bash
	67	+./bootstrap.sh --repo owner/repo --agent gemini
	68	+```
	69	+
	70	+To install manually, copy `hooks/gemini-hook.py` from the navegador repo into your project's `.gemini/hooks/` directory.
	71	+
	72	+### GEMINI.md config
	73	+
	74	+Add to your project's `GEMINI.md`:
	75	+
	76	+```markdown
	77	+## Tool Hooks
	78	+
	79	+After writing or editing any source file, run:
	80	+```
	81	+python .gemini/hooks/gemini-hook.py <file_path>
	82	+```
	83	+
	84	+This keeps the navegador knowledge graph in sync. The graph is your source of truth for code structure and project decisions.
	85	+```
	86	+
	87	+The Gemini CLI does not have a declarative hook registry like Claude. The `GEMINI.md` instruction tells the model to call the hook script explicitly as a tool after file writes.
	88	+
	89	+---
	90	+
	91	+## OpenAI
	92	+
	93	+OpenAI agents use a dispatcher script and a tool definition JSON file.
	94	+
	95	+### Install
	96	+
	97	+```bash
	98	+./bootstrap.sh --repo owner/repo --agent openai
	99	+```
	100	+
	101	+This places:
	102	+- `openai-hook.py` — dispatcher script
	103	+- `openai-tools.json` — tool schema for the OpenAI function-calling API
	104	+
	105	+### openai-tools.json
	106	+
	107	+The tool schema exposes navegador commands as callable functions:
	108	+
	109	+```json
	110	+[
	111	+ {
	112	+ "type": "function",
	113	+ "function": {
	114	+ "name": "navegador_explain",
	115	+ "description": "Look up any code or knowledge node by name",
	116	+ "parameters": {
	117	+ "type": "object",
	118	+ "properties": {
	119	+ "name": { "type": "string", "description": "Node name to explain" },
	120	+ "file": { "type": "string", "description": "Optional file path to disambiguate" }
	121	+ },
	122	+ "required": ["name"]
	123	+ }
	124	+ }
	125	+ },
	126	+ {
	127	+ "type": "function",
	128	+ "function": {
	129	+ "name": "navegador_ingest",
	130	+ "description": "Re-ingest a file or directory into the knowledge graph",
	131	+ "parameters": {
	132	+ "type": "object",
	133	+ "properties": {
	134	+ "path": { "type": "string", "description": "File or directory path to ingest" }
	135	+ },
	136	+ "required": ["path"]
	137	+ }
	138	+ }
	139	+ }
	140	+]
	141	+```
	142	+
	143	+### Dispatcher script
	144	+
	145	+`openai-hook.py` receives function call JSON on stdin and dispatches to `navegador` CLI commands:
	146	+
	147	+```python
	148	+# openai-hook.py dispatches tool calls to the navegador CLI
	149	+# usage: echo '{"name": "navegador_explain", "arguments": {"name": "AuthService"}}' \| python openai-hook.py
	150	+```
	151	+
	152	+Register `openai-tools.json` in your OpenAI assistant configuration and point function call handling at `openai-hook.py`.
	153	+
	154	+---
	155	+
	156	+## NAVEGADOR.md template
	157	+
	158	+Drop a `NAVEGADOR.md` in your project root so agents know the graph exists and how to use it. Example template:
	159	+
	160	+```markdown
	161	+# Navegador Knowledge Graph
	162	+
	163	+This project has a navegador knowledge graph at `.navegador/navegador.db`.
	164	+
	165	+## Before editing code
	166	+
	167	+Run the relevant context command first:
	168	+
	169	+```bash
	170	+navegador context <file> # full file context
	171	+navegador function <name> # function + call graph
	172	+navegador class <name> # class + hierarchy
	173	+navegador explain <name> # anything by name
	174	+```
	175	+
	176	+## Before adding new patterns
	177	+
	178	+Check if a concept or rule already exists:
	179	+
	180	+```bash
	181	+navegador search "<topic>" --all
	182	+navegador domain <domain-name>
	183	+```
	184	+
	185	+## After editing code
	186	+
	187	+The agent hook re-ingests automatically. If you disabled hooks, run:
	188	+
	189	+```bash
	190	+navegador ingest ./src --clear
	191	+```
	192	+
	193	+## Key domains
	194	+
	195	+- Payments — payment processing, billing, idempotency rules
	196	+- Auth — authentication, session management, permissions
	197	+- Infrastructure — deployment, database, caching decisions
	198	+```
	199	+
	200	+---
	201	+
	202	+## Bootstrap reference
	203	+
	204	+```bash
	205	+./bootstrap.sh [options]
	206	+```
	207	+
	208	+\| Option \| Description \|
	209	+\|---\|---\|
	210	+\| `--repo owner/repo` \| GitHub repo to clone and ingest \|
	211	+\| `--wiki` \| Also ingest the GitHub wiki \|
	212	+\| `--agent claude` \| Install Claude Code hook + settings.json config \|
	213	+\| `--agent gemini` \| Install Gemini CLI hook + GEMINI.md instruction \|
	214	+\| `--agent openai` \| Install openai-hook.py + openai-tools.json \|
	215	+\| `--db <path>` \| Custom database path (default: `.navegador/navegador.db`) \|

	--- a/docs/guide/agent-hooks.md
	+++ b/docs/guide/agent-hooks.md
	@@ -0,0 +1,215 @@

	--- a/docs/guide/agent-hooks.md
	+++ b/docs/guide/agent-hooks.md
	@@ -0,0 +1,215 @@
1	# Agent Hooks
2
3	Agent hooks keep the navegador graph in sync as AI coding agents work. Without hooks, the graph goes stale the moment an agent edits a file. With hooks, the graph is re-ingested automatically after every file write, and architectural decisions in `DECISIONS.md` are synced into the knowledge layer.
4
5	---
6
7	## Why hooks
8
9	A stale graph gives wrong answers. If an agent adds a new function and then asks `navegador function` about a caller, the graph needs to reflect the edit. Hooks solve this by triggering `navegador ingest` on the modified files immediately after the agent writes them.
10
11	Hooks also enforce the habit: every agent session starts with the graph as ground truth, not a stale snapshot.
12
13	---
14
15	## Claude Code
16
17	### Install
18
19	The hook file lives at `.claude/hooks/claude-hook.py`. Bootstrap installs it automatically:
20
21	```bash
22	./bootstrap.sh --repo owner/repo --agent claude
23	```
24
25	To install manually, copy `hooks/claude-hook.py` from the navegador repo into your project's `.claude/hooks/` directory.
26
27	### settings.json config
28
29	In your project's `.claude/settings.json`, register the hook:
30
31	```json
32	{
33	"hooks": {
34	"PostToolUse": [
35	{
36	"matcher": "Write\|Edit\|MultiEdit",
37	"hooks": [
38	{
39	"type": "command",
40	"command": "python .claude/hooks/claude-hook.py"
41	}
42	]
43	}
44	]
45	}
46	}
47	```
48
49	### What the hook does
50
51	On every `Write`, `Edit`, or `MultiEdit` tool call:
52
53	1. Reads the list of modified file paths from the tool result
54	2. Runs `navegador ingest` scoped to those files (fast incremental update)
55	3. Checks for changes to `DECISIONS.md` — if found, syncs any new ADR entries into the graph as `Decision` nodes
56	4. Logs a one-line summary to stderr (visible in Claude's tool output)
57
58	---
59
60	## Gemini CLI
61
62	### Install
63
64	The hook file lives at `.gemini/hooks/gemini-hook.py`. Bootstrap installs it automatically:
65
66	```bash
67	./bootstrap.sh --repo owner/repo --agent gemini
68	```
69
70	To install manually, copy `hooks/gemini-hook.py` from the navegador repo into your project's `.gemini/hooks/` directory.
71
72	### GEMINI.md config
73
74	Add to your project's `GEMINI.md`:
75
76	```markdown
77	## Tool Hooks
78
79	After writing or editing any source file, run:
80	```
81	python .gemini/hooks/gemini-hook.py <file_path>
82	```
83
84	This keeps the navegador knowledge graph in sync. The graph is your source of truth for code structure and project decisions.
85	```
86
87	The Gemini CLI does not have a declarative hook registry like Claude. The `GEMINI.md` instruction tells the model to call the hook script explicitly as a tool after file writes.
88
89	---
90
91	## OpenAI
92
93	OpenAI agents use a dispatcher script and a tool definition JSON file.
94
95	### Install
96
97	```bash
98	./bootstrap.sh --repo owner/repo --agent openai
99	```
100
101	This places:
102	- `openai-hook.py` — dispatcher script
103	- `openai-tools.json` — tool schema for the OpenAI function-calling API
104
105	### openai-tools.json
106
107	The tool schema exposes navegador commands as callable functions:
108
109	```json
110	[
111	{
112	"type": "function",
113	"function": {
114	"name": "navegador_explain",
115	"description": "Look up any code or knowledge node by name",
116	"parameters": {
117	"type": "object",
118	"properties": {
119	"name": { "type": "string", "description": "Node name to explain" },
120	"file": { "type": "string", "description": "Optional file path to disambiguate" }
121	},
122	"required": ["name"]
123	}
124	}
125	},
126	{
127	"type": "function",
128	"function": {
129	"name": "navegador_ingest",
130	"description": "Re-ingest a file or directory into the knowledge graph",
131	"parameters": {
132	"type": "object",
133	"properties": {
134	"path": { "type": "string", "description": "File or directory path to ingest" }
135	},
136	"required": ["path"]
137	}
138	}
139	}
140	]
141	```
142
143	### Dispatcher script
144
145	`openai-hook.py` receives function call JSON on stdin and dispatches to `navegador` CLI commands:
146
147	```python
148	# openai-hook.py dispatches tool calls to the navegador CLI
149	# usage: echo '{"name": "navegador_explain", "arguments": {"name": "AuthService"}}' \| python openai-hook.py
150	```
151
152	Register `openai-tools.json` in your OpenAI assistant configuration and point function call handling at `openai-hook.py`.
153
154	---
155
156	## NAVEGADOR.md template
157
158	Drop a `NAVEGADOR.md` in your project root so agents know the graph exists and how to use it. Example template:
159
160	```markdown
161	# Navegador Knowledge Graph
162
163	This project has a navegador knowledge graph at `.navegador/navegador.db`.
164
165	## Before editing code
166
167	Run the relevant context command first:
168
169	```bash
170	navegador context <file> # full file context
171	navegador function <name> # function + call graph
172	navegador class <name> # class + hierarchy
173	navegador explain <name> # anything by name
174	```
175
176	## Before adding new patterns
177
178	Check if a concept or rule already exists:
179
180	```bash
181	navegador search "<topic>" --all
182	navegador domain <domain-name>
183	```
184
185	## After editing code
186
187	The agent hook re-ingests automatically. If you disabled hooks, run:
188
189	```bash
190	navegador ingest ./src --clear
191	```
192
193	## Key domains
194
195	- Payments — payment processing, billing, idempotency rules
196	- Auth — authentication, session management, permissions
197	- Infrastructure — deployment, database, caching decisions
198	```
199
200	---
201
202	## Bootstrap reference
203
204	```bash
205	./bootstrap.sh [options]
206	```
207
208	\| Option \| Description \|
209	\|---\|---\|
210	\| `--repo owner/repo` \| GitHub repo to clone and ingest \|
211	\| `--wiki` \| Also ingest the GitHub wiki \|
212	\| `--agent claude` \| Install Claude Code hook + settings.json config \|
213	\| `--agent gemini` \| Install Gemini CLI hook + GEMINI.md instruction \|
214	\| `--agent openai` \| Install openai-hook.py + openai-tools.json \|
215	\| `--db <path>` \| Custom database path (default: `.navegador/navegador.db`) \|

M docs/guide/context-loading.md

+149 -2

		--- docs/guide/context-loading.md
		+++ docs/guide/context-loading.md
		@@ -1,3 +1,150 @@
1		-# context-loading
	1	+# Loading Context
	2	+
	3	+These commands retrieve structured context from the graph. All commands support `--format json` for machine-readable output (useful in agent tool definitions) and default to rich terminal output.
	4	+
	5	+---
	6	+
	7	+## explain — universal lookup
	8	+
	9	+`explain` is the single command for "what is this thing?" It works for any node type: functions, classes, files, concepts, rules, decisions, and domains.
	10	+
	11	+```bash
	12	+navegador explain AuthService
	13	+navegador explain validate_token
	14	+navegador explain src/auth/service.py
	15	+navegador explain PaymentsMustBeIdempotent
	16	+```
	17	+
	18	+Output includes:
	19	+- Node type, name, and properties
	20	+- Source location and docstring (for code nodes)
	21	+- Related knowledge (concepts, rules, decisions) via ANNOTATES edges
	22	+- Related code (for knowledge nodes) that implements or is governed by the node
	23	+
	24	+```bash
	25	+navegador explain AuthService --format json
	26	+navegador explain AuthService --file src/auth/service.py # disambiguate by file
	27	+```
	28	+
	29	+---
	30	+
	31	+## context — file contents
	32	+
	33	+Returns everything navegador knows about a file: the file node, its modules, classes, functions, imports, and their relationships.
	34	+
	35	+```bash
	36	+navegador context src/auth/service.py
	37	+navegador context src/auth/service.py --format json
	38	+navegador context src/auth/service.py --format markdown
	39	+```
	40	+
	41	+Useful as a pre-edit context load: give the agent the full graph context for a file before it starts editing.
	42	+
	43	+---
	44	+
	45	+## function — call graph view
	46	+
	47	+Returns a function node with its callers, callees, decorators, containing class, and source.
	48	+
	49	+```bash
	50	+navegador function validate_token
	51	+navegador function validate_token --file src/auth/service.py
	52	+navegador function validate_token --depth 2
	53	+navegador function validate_token --format json
	54	+```
	55	+
	56	+`--depth` controls how many hops of the call graph to traverse (default: 1). At depth 2, you get callers-of-callers and callees-of-callees.
	57	+
	58	+---
	59	+
	60	+## class — hierarchy and references
	61	+
	62	+Returns a class node with its methods, base classes, subclasses, and references from other files.
	63	+
	64	+```bash
	65	+navegador class PaymentProcessor
	66	+navegador class PaymentProcessor --file src/payments/processor.py
	67	+navegador class PaymentProcessor --format json
	68	+```
	69	+
	70	+Output includes:
	71	+- Class properties (file, line, docstring)
	72	+- Methods with signatures
	73	+- INHERITS chain (parents and children)
	74	+- IMPLEMENTS edges (for abstract base classes / interfaces)
	75	+- Files that import or reference this class
	76	+
	77	+---
	78	+
	79	+## concept — knowledge + implementing code
	80	+
	81	+Returns a concept node with its rules, linked wiki pages, and annotated code nodes.
	82	+
	83	+```bash
	84	+navegador concept Idempotency
	85	+navegador concept Idempotency --format json
	86	+```
	87	+
	88	+Output includes:
	89	+- Concept description and domain
	90	+- Rules in the same domain that reference this concept
	91	+- WikiPage nodes linked via DOCUMENTS
	92	+- All code nodes (functions, classes, files) annotated with this concept via ANNOTATES edges
	93	+
	94	+---
	95	+
	96	+## domain — everything in a domain
	97	+
	98	+Returns a domain and all nodes belonging to it: concepts, rules, decisions, people, and code annotated via those knowledge nodes.
	99	+
	100	+```bash
	101	+navegador domain Payments
	102	+navegador domain Payments --format json
	103	+```
	104	+
	105	+Useful for onboarding: a new contributor can run `navegador domain Payments` to get the full business context before reading any code.
	106	+
	107	+---
	108	+
	109	+## search — text search across the graph
	110	+
	111	+```bash
	112	+navegador search "rate limit"
	113	+```
	114	+
	115	+By default, searches function and class names. Flags expand the scope:
	116	+
	117	+\| Flag \| What it searches \|
	118	+\|---\|---\|
	119	+\| (default) \| Function, class, method names \|
	120	+\| `--all` \| Names + docstrings + knowledge layer (concepts, rules, decisions, wiki) \|
	121	+\| `--docs` \| Docstrings and wiki page content only \|
	122	+\| `--limit N` \| Max results (default: 20) \|
	123	+\| `--format json` \| JSON output \|
	124	+
	125	+Examples:
	126	+
	127	+```bash
	128	+# find anything about rate limiting, anywhere
	129	+navegador search "rate limit" --all
	130	+
	131	+# find code with docstrings mentioning retry logic
	132	+navegador search "retry" --docs
	133	+
	134	+# search with a higher limit
	135	+navegador search "auth" --all --limit 50 --format json
	136	+```
	137	+
	138	+---
	139	+
	140	+## decorated — find by decorator
	141	+
	142	+Find all functions and classes that use a specific decorator:
	143	+
	144	+```bash
	145	+navegador decorated login_required
	146	+navegador decorated pytest.mark.parametrize
	147	+navegador decorated --format json login_required
	148	+```
2	149
3		-Documentation coming soon.
	150	+Returns function/class nodes with their file paths, line numbers, and the full decorator expression.
4	151

	--- docs/guide/context-loading.md
	+++ docs/guide/context-loading.md
	@@ -1,3 +1,150 @@
1	# context-loading



















































































































































2
3	Documentation coming soon.
4

	--- docs/guide/context-loading.md
	+++ docs/guide/context-loading.md
	@@ -1,3 +1,150 @@
1	# Loading Context
2
3	These commands retrieve structured context from the graph. All commands support `--format json` for machine-readable output (useful in agent tool definitions) and default to rich terminal output.
4
5	---
6
7	## explain — universal lookup
8
9	`explain` is the single command for "what is this thing?" It works for any node type: functions, classes, files, concepts, rules, decisions, and domains.
10
11	```bash
12	navegador explain AuthService
13	navegador explain validate_token
14	navegador explain src/auth/service.py
15	navegador explain PaymentsMustBeIdempotent
16	```
17
18	Output includes:
19	- Node type, name, and properties
20	- Source location and docstring (for code nodes)
21	- Related knowledge (concepts, rules, decisions) via ANNOTATES edges
22	- Related code (for knowledge nodes) that implements or is governed by the node
23
24	```bash
25	navegador explain AuthService --format json
26	navegador explain AuthService --file src/auth/service.py # disambiguate by file
27	```
28
29	---
30
31	## context — file contents
32
33	Returns everything navegador knows about a file: the file node, its modules, classes, functions, imports, and their relationships.
34
35	```bash
36	navegador context src/auth/service.py
37	navegador context src/auth/service.py --format json
38	navegador context src/auth/service.py --format markdown
39	```
40
41	Useful as a pre-edit context load: give the agent the full graph context for a file before it starts editing.
42
43	---
44
45	## function — call graph view
46
47	Returns a function node with its callers, callees, decorators, containing class, and source.
48
49	```bash
50	navegador function validate_token
51	navegador function validate_token --file src/auth/service.py
52	navegador function validate_token --depth 2
53	navegador function validate_token --format json
54	```
55
56	`--depth` controls how many hops of the call graph to traverse (default: 1). At depth 2, you get callers-of-callers and callees-of-callees.
57
58	---
59
60	## class — hierarchy and references
61
62	Returns a class node with its methods, base classes, subclasses, and references from other files.
63
64	```bash
65	navegador class PaymentProcessor
66	navegador class PaymentProcessor --file src/payments/processor.py
67	navegador class PaymentProcessor --format json
68	```
69
70	Output includes:
71	- Class properties (file, line, docstring)
72	- Methods with signatures
73	- INHERITS chain (parents and children)
74	- IMPLEMENTS edges (for abstract base classes / interfaces)
75	- Files that import or reference this class
76
77	---
78
79	## concept — knowledge + implementing code
80
81	Returns a concept node with its rules, linked wiki pages, and annotated code nodes.
82
83	```bash
84	navegador concept Idempotency
85	navegador concept Idempotency --format json
86	```
87
88	Output includes:
89	- Concept description and domain
90	- Rules in the same domain that reference this concept
91	- WikiPage nodes linked via DOCUMENTS
92	- All code nodes (functions, classes, files) annotated with this concept via ANNOTATES edges
93
94	---
95
96	## domain — everything in a domain
97
98	Returns a domain and all nodes belonging to it: concepts, rules, decisions, people, and code annotated via those knowledge nodes.
99
100	```bash
101	navegador domain Payments
102	navegador domain Payments --format json
103	```
104
105	Useful for onboarding: a new contributor can run `navegador domain Payments` to get the full business context before reading any code.
106
107	---
108
109	## search — text search across the graph
110
111	```bash
112	navegador search "rate limit"
113	```
114
115	By default, searches function and class names. Flags expand the scope:
116
117	\| Flag \| What it searches \|
118	\|---\|---\|
119	\| (default) \| Function, class, method names \|
120	\| `--all` \| Names + docstrings + knowledge layer (concepts, rules, decisions, wiki) \|
121	\| `--docs` \| Docstrings and wiki page content only \|
122	\| `--limit N` \| Max results (default: 20) \|
123	\| `--format json` \| JSON output \|
124
125	Examples:
126
127	```bash
128	# find anything about rate limiting, anywhere
129	navegador search "rate limit" --all
130
131	# find code with docstrings mentioning retry logic
132	navegador search "retry" --docs
133
134	# search with a higher limit
135	navegador search "auth" --all --limit 50 --format json
136	```
137
138	---
139
140	## decorated — find by decorator
141
142	Find all functions and classes that use a specific decorator:
143
144	```bash
145	navegador decorated login_required
146	navegador decorated pytest.mark.parametrize
147	navegador decorated --format json login_required
148	```
149
150	Returns function/class nodes with their file paths, line numbers, and the full decorator expression.
151

M docs/guide/graph-queries.md

+140 -2

		--- docs/guide/graph-queries.md
		+++ docs/guide/graph-queries.md
		@@ -1,3 +1,141 @@
1		-# graph-queries
	1	+# Graph Queries
	2	+
	3	+## Raw Cypher passthrough
	4	+
	5	+Every high-level command is built on Cypher queries against FalkorDB. You can drop to raw Cypher for anything the built-in commands don't cover:
	6	+
	7	+```bash
	8	+navegador query "MATCH (f:Function) RETURN f.name, f.file LIMIT 10"
	9	+```
	10	+
	11	+Results are printed as a table to stdout. Pipe with `--format json` if you need machine-readable output:
	12	+
	13	+```bash
	14	+navegador query "MATCH (f:Function) RETURN f.name, f.file" --format json
	15	+```
	16	+
	17	+!!! warning
	18	+ `navegador query` executes writes as well as reads. Use `MATCH` / `RETURN` for inspection. Use `CREATE` / `MERGE` / `DELETE` only if you know what you're doing — there is no undo.
	19	+
	20	+---
	21	+
	22	+## Useful example queries
	23	+
	24	+### Find all functions decorated with `@login_required`
	25	+
	26	+```cypher
	27	+MATCH (d:Decorator {name: "login_required"})-[:DECORATES]->(f:Function)
	28	+RETURN f.name, f.file, f.line
	29	+ORDER BY f.file
	30	+```
	31	+
	32	+### Find all functions in a specific file
	33	+
	34	+```cypher
	35	+MATCH (file:File {path: "src/auth/service.py"})-[:CONTAINS]->(f:Function)
	36	+RETURN f.name, f.line, f.signature
	37	+```
	38	+
	39	+### Find everything a function calls (two hops)
	40	+
	41	+```cypher
	42	+MATCH (f:Function {name: "process_payment"})-[:CALLS*1..2]->(callee:Function)
	43	+RETURN DISTINCT callee.name, callee.file
	44	+```
	45	+
	46	+### Find all callers of a function
	47	+
	48	+```cypher
	49	+MATCH (caller:Function)-[:CALLS]->(f:Function {name: "validate_token"})
	50	+RETURN caller.name, caller.file
	51	+```
	52	+
	53	+### Find all rules in a domain
	54	+
	55	+```cypher
	56	+MATCH (d:Domain {name: "Payments"})<-[:BELONGS_TO]-(r:Rule)
	57	+RETURN r.name, r.severity, r.description
	58	+ORDER BY r.severity
	59	+```
	60	+
	61	+### Find all concepts implemented by code in a file
	62	+
	63	+```cypher
	64	+MATCH (file:File {path: "src/payments/processor.py"})-[:CONTAINS]->(f)
	65	+ -[:ANNOTATES]-(c:Concept)
	66	+RETURN DISTINCT c.name, c.description
	67	+```
	68	+
	69	+### Find all decisions that relate to a domain
	70	+
	71	+```cypher
	72	+MATCH (d:Domain {name: "Infrastructure"})<-[:BELONGS_TO]-(dec:Decision)
	73	+RETURN dec.name, dec.status, dec.date, dec.rationale
	74	+ORDER BY dec.date DESC
	75	+```
	76	+
	77	+### Find classes that inherit from a base class
	78	+
	79	+```cypher
	80	+MATCH (child:Class)-[:INHERITS]->(parent:Class {name: "BaseProcessor"})
	81	+RETURN child.name, child.file
	82	+```
	83	+
	84	+### Find the full inheritance chain for a class
	85	+
	86	+```cypher
	87	+MATCH path = (c:Class {name: "StripeProcessor"})-[:INHERITS*]->(ancestor)
	88	+RETURN [node IN nodes(path) \| node.name] AS hierarchy
	89	+```
	90	+
	91	+### Find wiki pages that document a concept
	92	+
	93	+```cypher
	94	+MATCH (wp:WikiPage)-[:DOCUMENTS]->(c:Concept {name: "Idempotency"})
	95	+RETURN wp.title, wp.url
	96	+```
	97	+
	98	+### Find all functions annotated with a specific rule
	99	+
	100	+```cypher
	101	+MATCH (r:Rule {name: "RequireIdempotencyKey"})-[:GOVERNS]->(f:Function)
	102	+RETURN f.name, f.file, f.line
	103	+```
	104	+
	105	+### Find what a person is assigned to
	106	+
	107	+```cypher
	108	+MATCH (p:Person {name: "Alice Chen"})<-[:ASSIGNED_TO]-(item)
	109	+RETURN labels(item)[0] AS type, item.name
	110	+```
	111	+
	112	+---
	113	+
	114	+## navegador stats
	115	+
	116	+Get a high-level count of everything in the graph:
	117	+
	118	+```bash
	119	+navegador stats
	120	+navegador stats --json
	121	+```
	122	+
	123	+Output breakdown:
	124	+
	125	+\| Metric \| What it counts \|
	126	+\|---\|---\|
	127	+\| Repositories \| `Repository` nodes \|
	128	+\| Files \| `File` nodes \|
	129	+\| Classes \| `Class` nodes \|
	130	+\| Functions + Methods \| `Function` + `Method` nodes combined \|
	131	+\| Decorators \| `Decorator` nodes \|
	132	+\| Imports \| `Import` nodes \|
	133	+\| Domains \| `Domain` nodes \|
	134	+\| Concepts \| `Concept` nodes \|
	135	+\| Rules \| `Rule` nodes \|
	136	+\| Decisions \| `Decision` nodes \|
	137	+\| People \| `Person` nodes \|
	138	+\| WikiPages \| `WikiPage` nodes \|
	139	+\| Total edges \| All relationship edges \|
2	140
3		-Documentation coming soon.
	141	+Use `--json` to feed stats into CI dashboards or coverage checks.
4	142

	--- docs/guide/graph-queries.md
	+++ docs/guide/graph-queries.md
	@@ -1,3 +1,141 @@
1	# graph-queries










































































































































2
3	Documentation coming soon.
4

	--- docs/guide/graph-queries.md
	+++ docs/guide/graph-queries.md
	@@ -1,3 +1,141 @@
1	# Graph Queries
2
3	## Raw Cypher passthrough
4
5	Every high-level command is built on Cypher queries against FalkorDB. You can drop to raw Cypher for anything the built-in commands don't cover:
6
7	```bash
8	navegador query "MATCH (f:Function) RETURN f.name, f.file LIMIT 10"
9	```
10
11	Results are printed as a table to stdout. Pipe with `--format json` if you need machine-readable output:
12
13	```bash
14	navegador query "MATCH (f:Function) RETURN f.name, f.file" --format json
15	```
16
17	!!! warning
18	`navegador query` executes writes as well as reads. Use `MATCH` / `RETURN` for inspection. Use `CREATE` / `MERGE` / `DELETE` only if you know what you're doing — there is no undo.
19
20	---
21
22	## Useful example queries
23
24	### Find all functions decorated with `@login_required`
25
26	```cypher
27	MATCH (d:Decorator {name: "login_required"})-[:DECORATES]->(f:Function)
28	RETURN f.name, f.file, f.line
29	ORDER BY f.file
30	```
31
32	### Find all functions in a specific file
33
34	```cypher
35	MATCH (file:File {path: "src/auth/service.py"})-[:CONTAINS]->(f:Function)
36	RETURN f.name, f.line, f.signature
37	```
38
39	### Find everything a function calls (two hops)
40
41	```cypher
42	MATCH (f:Function {name: "process_payment"})-[:CALLS*1..2]->(callee:Function)
43	RETURN DISTINCT callee.name, callee.file
44	```
45
46	### Find all callers of a function
47
48	```cypher
49	MATCH (caller:Function)-[:CALLS]->(f:Function {name: "validate_token"})
50	RETURN caller.name, caller.file
51	```
52
53	### Find all rules in a domain
54
55	```cypher
56	MATCH (d:Domain {name: "Payments"})<-[:BELONGS_TO]-(r:Rule)
57	RETURN r.name, r.severity, r.description
58	ORDER BY r.severity
59	```
60
61	### Find all concepts implemented by code in a file
62
63	```cypher
64	MATCH (file:File {path: "src/payments/processor.py"})-[:CONTAINS]->(f)
65	-[:ANNOTATES]-(c:Concept)
66	RETURN DISTINCT c.name, c.description
67	```
68
69	### Find all decisions that relate to a domain
70
71	```cypher
72	MATCH (d:Domain {name: "Infrastructure"})<-[:BELONGS_TO]-(dec:Decision)
73	RETURN dec.name, dec.status, dec.date, dec.rationale
74	ORDER BY dec.date DESC
75	```
76
77	### Find classes that inherit from a base class
78
79	```cypher
80	MATCH (child:Class)-[:INHERITS]->(parent:Class {name: "BaseProcessor"})
81	RETURN child.name, child.file
82	```
83
84	### Find the full inheritance chain for a class
85
86	```cypher
87	MATCH path = (c:Class {name: "StripeProcessor"})-[:INHERITS*]->(ancestor)
88	RETURN [node IN nodes(path) \| node.name] AS hierarchy
89	```
90
91	### Find wiki pages that document a concept
92
93	```cypher
94	MATCH (wp:WikiPage)-[:DOCUMENTS]->(c:Concept {name: "Idempotency"})
95	RETURN wp.title, wp.url
96	```
97
98	### Find all functions annotated with a specific rule
99
100	```cypher
101	MATCH (r:Rule {name: "RequireIdempotencyKey"})-[:GOVERNS]->(f:Function)
102	RETURN f.name, f.file, f.line
103	```
104
105	### Find what a person is assigned to
106
107	```cypher
108	MATCH (p:Person {name: "Alice Chen"})<-[:ASSIGNED_TO]-(item)
109	RETURN labels(item)[0] AS type, item.name
110	```
111
112	---
113
114	## navegador stats
115
116	Get a high-level count of everything in the graph:
117
118	```bash
119	navegador stats
120	navegador stats --json
121	```
122
123	Output breakdown:
124
125	\| Metric \| What it counts \|
126	\|---\|---\|
127	\| Repositories \| `Repository` nodes \|
128	\| Files \| `File` nodes \|
129	\| Classes \| `Class` nodes \|
130	\| Functions + Methods \| `Function` + `Method` nodes combined \|
131	\| Decorators \| `Decorator` nodes \|
132	\| Imports \| `Import` nodes \|
133	\| Domains \| `Domain` nodes \|
134	\| Concepts \| `Concept` nodes \|
135	\| Rules \| `Rule` nodes \|
136	\| Decisions \| `Decision` nodes \|
137	\| People \| `Person` nodes \|
138	\| WikiPages \| `WikiPage` nodes \|
139	\| Total edges \| All relationship edges \|
140
141	Use `--json` to feed stats into CI dashboards or coverage checks.
142

M docs/guide/ingestion.md

+149 -2

		--- docs/guide/ingestion.md
		+++ docs/guide/ingestion.md
		@@ -1,3 +1,150 @@
1		-# ingestion
	1	+# Ingesting a Repo
	2	+
	3	+Navegador builds the graph from four sources: code, manual knowledge curation, GitHub wikis, and Planopticon knowledge graph output.
	4	+
	5	+---
	6	+
	7	+## Code ingestion
	8	+
	9	+```bash
	10	+navegador ingest ./repo
	11	+```
	12	+
	13	+### What gets extracted
	14	+
	15	+Navegador walks every `.py` and `.ts` / `.tsx` file and uses tree-sitter to extract:
	16	+
	17	+\| What \| Graph nodes / edges created \|
	18	+\|---\|---\|
	19	+\| Files and modules \| `File`, `Module` nodes; `CONTAINS` edges from `Repository` \|
	20	+\| Classes \| `Class` node with `name`, `file`, `line`, `docstring` \|
	21	+\| Functions and methods \| `Function` / `Method` nodes with `name`, `signature`, `docstring`, `line` \|
	22	+\| Decorators \| `Decorator` node; `DECORATES` edge to the decorated function/class \|
	23	+\| Imports \| `Import` node; `IMPORTS` edge from the importing file \|
	24	+\| Call relationships \| `CALLS` edges between functions based on static call analysis \|
	25	+\| Inheritance \| `INHERITS` edges from subclass to parent; `IMPLEMENTS` for interfaces \|
	26	+\| Variables (module-level) \| `Variable` nodes \|
	27	+
	28	+### Options
	29	+
	30	+\| Flag \| Effect \|
	31	+\|---\|---\|
	32	+\| `--clear` \| Wipe the graph before ingesting (full rebuild) \|
	33	+\| `--json` \| Output a JSON summary of nodes and edges created \|
	34	+\| `--db <path>` \| Use a specific database file \|
	35	+
	36	+### Re-ingesting
	37	+
	38	+Re-run `navegador ingest` anytime to pick up changes. Nodes are upserted by identity (file path + name), so repeated ingestion is idempotent for unchanged nodes. Use `--clear` when you need a clean slate (e.g., after a large rename refactor).
	39	+
	40	+---
	41	+
	42	+## Knowledge curation
	43	+
	44	+Manual knowledge is added with `navegador add` commands and linked to code with `navegador annotate`.
	45	+
	46	+### Concepts
	47	+
	48	+A concept is a named idea or design pattern relevant to the codebase.
	49	+
	50	+```bash
	51	+navegador add concept "Idempotency" \
	52	+ --desc "Operations safe to retry without side effects" \
	53	+ --domain Payments
	54	+```
	55	+
	56	+### Rules
	57	+
	58	+A rule is an enforceable constraint on code behaviour.
	59	+
	60	+```bash
	61	+navegador add rule "RequireIdempotencyKey" \
	62	+ --desc "All write endpoints must accept an idempotency key header" \
	63	+ --domain Payments \
	64	+ --severity critical \
	65	+ --rationale "Prevents double-processing on client retries"
	66	+```
	67	+
	68	+Severity values: `info`, `warning`, `critical`.
	69	+
	70	+### Decisions
	71	+
	72	+An architectural decision record (ADR) stored in the graph.
	73	+
	74	+```bash
	75	+navegador add decision "UsePostgresForTransactions" \
	76	+ --desc "PostgreSQL is the primary datastore for transactional data" \
	77	+ --domain Infrastructure \
	78	+ --rationale "ACID guarantees required for financial data" \
	79	+ --alternatives "MySQL, CockroachDB" \
	80	+ --date 2025-03-01 \
	81	+ --status accepted
	82	+```
	83	+
	84	+Status values: `proposed`, `accepted`, `deprecated`, `superseded`.
	85	+
	86	+### People
	87	+
	88	+```bash
	89	+navegador add person "Alice Chen" \
	90	+ --email [email protected] \
	91	+ --role "Lead Engineer" \
	92	+ --team Payments
	93	+```
	94	+
	95	+### Domains
	96	+
	97	+Domains are top-level groupings for concepts, rules, and decisions.
	98	+
	99	+```bash
	100	+navegador add domain "Payments" \
	101	+ --desc "Everything related to payment processing and billing"
	102	+```
	103	+
	104	+### Annotating code
	105	+
	106	+Link a code node to a concept or rule:
	107	+
	108	+```bash
	109	+navegador annotate process_payment \
	110	+ --type Function \
	111	+ --concept Idempotency \
	112	+ --rule RequireIdempotencyKey
	113	+```
	114	+
	115	+`--type` accepts: `Function`, `Class`, `Method`, `File`, `Module`.
	116	+
	117	+This creates `ANNOTATES` edges between the knowledge nodes and the code node. The code node then appears in results for `navegador concept Idempotency` and `navegador explain process_payment`.
	118	+
	119	+---
	120	+
	121	+## Wiki ingestion
	122	+
	123	+Pull a GitHub wiki into the graph as `WikiPage` nodes.
	124	+
	125	+```bash
	126	+# ingest from GitHub API
	127	+navegador wiki ingest --repo myorg/myrepo --token $GITHUB_TOKEN
	128	+
	129	+# ingest from a locally cloned wiki directory
	130	+navegador wiki ingest --dir ./myrepo.wiki
	131	+
	132	+# force API mode (bypass auto-detection)
	133	+navegador wiki ingest --repo myorg/myrepo --api
	134	+```
	135	+
	136	+Each wiki page becomes a `WikiPage` node with `title`, `content`, `url`, and `updated_at` properties. Pages are linked to relevant `Concept`, `Domain`, or `Function` nodes with `DOCUMENTS` edges where names match.
	137	+
	138	+Set `GITHUB_TOKEN` in your environment to avoid rate limits and to access private wikis.
	139	+
	140	+---
	141	+
	142	+## Planopticon ingestion
	143	+
	144	+[Planopticon](planopticon.md) is a video/meeting knowledge extraction tool. It produces structured knowledge graph output that navegador can ingest directly.
	145	+
	146	+```bash
	147	+navegador planopticon ingest ./meeting-output/ --type auto
	148	+```
2	149
3		-Documentation coming soon.
	150	+See the [Planopticon guide](planopticon.md) for the full input format reference and entity mapping details.
4	151

	--- docs/guide/ingestion.md
	+++ docs/guide/ingestion.md
	@@ -1,3 +1,150 @@
1	# ingestion



















































































































































2
3	Documentation coming soon.
4

	--- docs/guide/ingestion.md
	+++ docs/guide/ingestion.md
	@@ -1,3 +1,150 @@
1	# Ingesting a Repo
2
3	Navegador builds the graph from four sources: code, manual knowledge curation, GitHub wikis, and Planopticon knowledge graph output.
4
5	---
6
7	## Code ingestion
8
9	```bash
10	navegador ingest ./repo
11	```
12
13	### What gets extracted
14
15	Navegador walks every `.py` and `.ts` / `.tsx` file and uses tree-sitter to extract:
16
17	\| What \| Graph nodes / edges created \|
18	\|---\|---\|
19	\| Files and modules \| `File`, `Module` nodes; `CONTAINS` edges from `Repository` \|
20	\| Classes \| `Class` node with `name`, `file`, `line`, `docstring` \|
21	\| Functions and methods \| `Function` / `Method` nodes with `name`, `signature`, `docstring`, `line` \|
22	\| Decorators \| `Decorator` node; `DECORATES` edge to the decorated function/class \|
23	\| Imports \| `Import` node; `IMPORTS` edge from the importing file \|
24	\| Call relationships \| `CALLS` edges between functions based on static call analysis \|
25	\| Inheritance \| `INHERITS` edges from subclass to parent; `IMPLEMENTS` for interfaces \|
26	\| Variables (module-level) \| `Variable` nodes \|
27
28	### Options
29
30	\| Flag \| Effect \|
31	\|---\|---\|
32	\| `--clear` \| Wipe the graph before ingesting (full rebuild) \|
33	\| `--json` \| Output a JSON summary of nodes and edges created \|
34	\| `--db <path>` \| Use a specific database file \|
35
36	### Re-ingesting
37
38	Re-run `navegador ingest` anytime to pick up changes. Nodes are upserted by identity (file path + name), so repeated ingestion is idempotent for unchanged nodes. Use `--clear` when you need a clean slate (e.g., after a large rename refactor).
39
40	---
41
42	## Knowledge curation
43
44	Manual knowledge is added with `navegador add` commands and linked to code with `navegador annotate`.
45
46	### Concepts
47
48	A concept is a named idea or design pattern relevant to the codebase.
49
50	```bash
51	navegador add concept "Idempotency" \
52	--desc "Operations safe to retry without side effects" \
53	--domain Payments
54	```
55
56	### Rules
57
58	A rule is an enforceable constraint on code behaviour.
59
60	```bash
61	navegador add rule "RequireIdempotencyKey" \
62	--desc "All write endpoints must accept an idempotency key header" \
63	--domain Payments \
64	--severity critical \
65	--rationale "Prevents double-processing on client retries"
66	```
67
68	Severity values: `info`, `warning`, `critical`.
69
70	### Decisions
71
72	An architectural decision record (ADR) stored in the graph.
73
74	```bash
75	navegador add decision "UsePostgresForTransactions" \
76	--desc "PostgreSQL is the primary datastore for transactional data" \
77	--domain Infrastructure \
78	--rationale "ACID guarantees required for financial data" \
79	--alternatives "MySQL, CockroachDB" \
80	--date 2025-03-01 \
81	--status accepted
82	```
83
84	Status values: `proposed`, `accepted`, `deprecated`, `superseded`.
85
86	### People
87
88	```bash
89	navegador add person "Alice Chen" \
90	--email [email protected] \
91	--role "Lead Engineer" \
92	--team Payments
93	```
94
95	### Domains
96
97	Domains are top-level groupings for concepts, rules, and decisions.
98
99	```bash
100	navegador add domain "Payments" \
101	--desc "Everything related to payment processing and billing"
102	```
103
104	### Annotating code
105
106	Link a code node to a concept or rule:
107
108	```bash
109	navegador annotate process_payment \
110	--type Function \
111	--concept Idempotency \
112	--rule RequireIdempotencyKey
113	```
114
115	`--type` accepts: `Function`, `Class`, `Method`, `File`, `Module`.
116
117	This creates `ANNOTATES` edges between the knowledge nodes and the code node. The code node then appears in results for `navegador concept Idempotency` and `navegador explain process_payment`.
118
119	---
120
121	## Wiki ingestion
122
123	Pull a GitHub wiki into the graph as `WikiPage` nodes.
124
125	```bash
126	# ingest from GitHub API
127	navegador wiki ingest --repo myorg/myrepo --token $GITHUB_TOKEN
128
129	# ingest from a locally cloned wiki directory
130	navegador wiki ingest --dir ./myrepo.wiki
131
132	# force API mode (bypass auto-detection)
133	navegador wiki ingest --repo myorg/myrepo --api
134	```
135
136	Each wiki page becomes a `WikiPage` node with `title`, `content`, `url`, and `updated_at` properties. Pages are linked to relevant `Concept`, `Domain`, or `Function` nodes with `DOCUMENTS` edges where names match.
137
138	Set `GITHUB_TOKEN` in your environment to avoid rate limits and to access private wikis.
139
140	---
141
142	## Planopticon ingestion
143
144	[Planopticon](planopticon.md) is a video/meeting knowledge extraction tool. It produces structured knowledge graph output that navegador can ingest directly.
145
146	```bash
147	navegador planopticon ingest ./meeting-output/ --type auto
148	```
149
150	See the [Planopticon guide](planopticon.md) for the full input format reference and entity mapping details.
151

M docs/guide/mcp-integration.md

+151 -2

		--- docs/guide/mcp-integration.md
		+++ docs/guide/mcp-integration.md
		@@ -1,3 +1,152 @@
1		-# mcp-integration
	1	+# MCP Integration
	2	+
	3	+Navegador ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server. When running in MCP mode, all navegador commands become callable tools that agents can invoke with structured input and receive structured output.
	4	+
	5	+---
	6	+
	7	+## CLI vs MCP: when to use which
	8	+
	9	+The primary interface for agents is the CLI, not MCP. Here's why:
	10	+
	11	+\| \| CLI \| MCP \|
	12	+\|---\|---\|---\|
	13	+\| Token cost \| Low — agent calls a shell tool, gets back only what it asked for \| Higher — MCP tool calls involve protocol overhead \|
	14	+\| Setup \| None beyond installing navegador \| Requires MCP config in agent settings \|
	15	+\| Best for \| Agent hooks, shell scripts, CI \| Interactive sessions in Claude / Cursor \|
	16	+\| Output formats \| JSON, markdown, rich terminal \| Structured JSON always \|
	17	+
	18	+Use MCP when you want navegador tools available as first-class tool calls in an interactive Claude or Cursor session. Use the CLI (via agent hooks) for automated background sync and pre-edit context loading.
	19	+
	20	+---
	21	+
	22	+## Starting the MCP server
	23	+
	24	+```bash
	25	+navegador mcp
	26	+```
	27	+
	28	+With a custom database path:
	29	+
	30	+```bash
	31	+navegador mcp --db .navegador/navegador.db
	32	+```
	33	+
	34	+The server speaks MCP over stdio. It does not bind a port.
	35	+
	36	+---
	37	+
	38	+## Agent configuration
	39	+
	40	+=== "Claude Code"
	41	+
	42	+ Add to your project's `.claude/settings.json`:
	43	+
	44	+ ```json
	45	+ {
	46	+ "mcpServers": {
	47	+ "navegador": {
	48	+ "command": "navegador",
	49	+ "args": ["mcp"],
	50	+ "env": {
	51	+ "NAVEGADOR_DB": ".navegador/navegador.db"
	52	+ }
	53	+ }
	54	+ }
	55	+ }
	56	+ ```
	57	+
	58	+=== "Claude Desktop"
	59	+
	60	+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
	61	+
	62	+ ```json
	63	+ {
	64	+ "mcpServers": {
	65	+ "navegador": {
	66	+ "command": "navegador",
	67	+ "args": ["mcp", "--db", "/path/to/project/.navegador/navegador.db"]
	68	+ }
	69	+ }
	70	+ }
	71	+ ```
	72	+
	73	+=== "Cursor"
	74	+
	75	+ Add to `.cursor/mcp.json` in your project root:
	76	+
	77	+ ```json
	78	+ {
	79	+ "mcpServers": {
	80	+ "navegador": {
	81	+ "command": "navegador",
	82	+ "args": ["mcp"],
	83	+ "env": {
	84	+ "NAVEGADOR_DB": ".navegador/navegador.db"
	85	+ }
	86	+ }
	87	+ }
	88	+ }
	89	+ ```
	90	+
	91	+---
	92	+
	93	+## Available MCP tools
	94	+
	95	+All tools accept and return JSON.
	96	+
	97	+\| Tool \| Equivalent CLI \| Description \|
	98	+\|---\|---\|---\|
	99	+\| `ingest` \| `navegador ingest` \| Ingest a repo into the graph \|
	100	+\| `context` \| `navegador context` \| File-level context bundle \|
	101	+\| `function` \| `navegador function` \| Function with call graph \|
	102	+\| `class` \| `navegador class` \| Class with hierarchy \|
	103	+\| `explain` \| `navegador explain` \| Universal node lookup \|
	104	+\| `search` \| `navegador search` \| Text search across graph \|
	105	+\| `query` \| `navegador query` \| Raw Cypher passthrough \|
	106	+
	107	+### Tool input schemas
	108	+
	109	+ingest
	110	+```json
	111	+{ "path": "./repo", "clear": false }
	112	+```
	113	+
	114	+context
	115	+```json
	116	+{ "file": "src/auth/service.py", "format": "json" }
	117	+```
	118	+
	119	+function
	120	+```json
	121	+{ "name": "validate_token", "file": "src/auth/service.py", "depth": 2 }
	122	+```
	123	+
	124	+class
	125	+```json
	126	+{ "name": "PaymentProcessor", "file": "src/payments/processor.py" }
	127	+```
	128	+
	129	+explain
	130	+```json
	131	+{ "name": "AuthService", "file": "src/auth/service.py" }
	132	+```
	133	+
	134	+search
	135	+```json
	136	+{ "query": "rate limit", "all": true, "docs": false, "limit": 20 }
	137	+```
	138	+
	139	+query
	140	+```json
	141	+{ "cypher": "MATCH (f:Function) RETURN f.name LIMIT 10" }
	142	+```
	143	+
	144	+---
	145	+
	146	+## When MCP makes sense
	147	+
	148	+- You are in an interactive Claude or Cursor session and want to call `explain`, `search`, or `function` without dropping to a terminal
	149	+- You want navegador tools auto-discovered by the agent without writing custom tool definitions
	150	+- You are building an agent workflow that dynamically queries the graph mid-task
2	151
3		-Documentation coming soon.
	152	+For automated background tasks (re-ingest on file save, sync on pull), use the CLI via [agent hooks](agent-hooks.md) instead.
4	153
5	154	ADDED docs/guide/planopticon.md

	--- docs/guide/mcp-integration.md
	+++ docs/guide/mcp-integration.md
	@@ -1,3 +1,152 @@
1	# mcp-integration





















































































































































2
3	Documentation coming soon.
4
5	DDED docs/guide/planopticon.md

	--- docs/guide/mcp-integration.md
	+++ docs/guide/mcp-integration.md
	@@ -1,3 +1,152 @@
1	# MCP Integration
2
3	Navegador ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server. When running in MCP mode, all navegador commands become callable tools that agents can invoke with structured input and receive structured output.
4
5	---
6
7	## CLI vs MCP: when to use which
8
9	The primary interface for agents is the CLI, not MCP. Here's why:
10
11	\| \| CLI \| MCP \|
12	\|---\|---\|---\|
13	\| Token cost \| Low — agent calls a shell tool, gets back only what it asked for \| Higher — MCP tool calls involve protocol overhead \|
14	\| Setup \| None beyond installing navegador \| Requires MCP config in agent settings \|
15	\| Best for \| Agent hooks, shell scripts, CI \| Interactive sessions in Claude / Cursor \|
16	\| Output formats \| JSON, markdown, rich terminal \| Structured JSON always \|
17
18	Use MCP when you want navegador tools available as first-class tool calls in an interactive Claude or Cursor session. Use the CLI (via agent hooks) for automated background sync and pre-edit context loading.
19
20	---
21
22	## Starting the MCP server
23
24	```bash
25	navegador mcp
26	```
27
28	With a custom database path:
29
30	```bash
31	navegador mcp --db .navegador/navegador.db
32	```
33
34	The server speaks MCP over stdio. It does not bind a port.
35
36	---
37
38	## Agent configuration
39
40	=== "Claude Code"
41
42	Add to your project's `.claude/settings.json`:
43
44	```json
45	{
46	"mcpServers": {
47	"navegador": {
48	"command": "navegador",
49	"args": ["mcp"],
50	"env": {
51	"NAVEGADOR_DB": ".navegador/navegador.db"
52	}
53	}
54	}
55	}
56	```
57
58	=== "Claude Desktop"
59
60	Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
61
62	```json
63	{
64	"mcpServers": {
65	"navegador": {
66	"command": "navegador",
67	"args": ["mcp", "--db", "/path/to/project/.navegador/navegador.db"]
68	}
69	}
70	}
71	```
72
73	=== "Cursor"
74
75	Add to `.cursor/mcp.json` in your project root:
76
77	```json
78	{
79	"mcpServers": {
80	"navegador": {
81	"command": "navegador",
82	"args": ["mcp"],
83	"env": {
84	"NAVEGADOR_DB": ".navegador/navegador.db"
85	}
86	}
87	}
88	}
89	```
90
91	---
92
93	## Available MCP tools
94
95	All tools accept and return JSON.
96
97	\| Tool \| Equivalent CLI \| Description \|
98	\|---\|---\|---\|
99	\| `ingest` \| `navegador ingest` \| Ingest a repo into the graph \|
100	\| `context` \| `navegador context` \| File-level context bundle \|
101	\| `function` \| `navegador function` \| Function with call graph \|
102	\| `class` \| `navegador class` \| Class with hierarchy \|
103	\| `explain` \| `navegador explain` \| Universal node lookup \|
104	\| `search` \| `navegador search` \| Text search across graph \|
105	\| `query` \| `navegador query` \| Raw Cypher passthrough \|
106
107	### Tool input schemas
108
109	ingest
110	```json
111	{ "path": "./repo", "clear": false }
112	```
113
114	context
115	```json
116	{ "file": "src/auth/service.py", "format": "json" }
117	```
118
119	function
120	```json
121	{ "name": "validate_token", "file": "src/auth/service.py", "depth": 2 }
122	```
123
124	class
125	```json
126	{ "name": "PaymentProcessor", "file": "src/payments/processor.py" }
127	```
128
129	explain
130	```json
131	{ "name": "AuthService", "file": "src/auth/service.py" }
132	```
133
134	search
135	```json
136	{ "query": "rate limit", "all": true, "docs": false, "limit": 20 }
137	```
138
139	query
140	```json
141	{ "cypher": "MATCH (f:Function) RETURN f.name LIMIT 10" }
142	```
143
144	---
145
146	## When MCP makes sense
147
148	- You are in an interactive Claude or Cursor session and want to call `explain`, `search`, or `function` without dropping to a terminal
149	- You want navegador tools auto-discovered by the agent without writing custom tool definitions
150	- You are building an agent workflow that dynamically queries the graph mid-task
151
152	For automated background tasks (re-ingest on file save, sync on pull), use the CLI via [agent hooks](agent-hooks.md) instead.
153
154	DDED docs/guide/planopticon.md

A docs/guide/planopticon.md

+175

		--- a/docs/guide/planopticon.md
		+++ b/docs/guide/planopticon.md
		@@ -0,0 +1,175 @@
	1	+# Planopticon Integration
	2	+
	3	+## What is Planopticon
	4	+
	5	+Planopticon is a video and meeting knowledge extraction tool. It ingests recordings, transcripts, and meeting notes and produces structured knowledge graphs: entities (people, concepts, decisions), relationships, action items, and diagrams extracted from the meeting content.
	6	+
	7	+Navegador treats Planopticon output as a first-class knowledge source. Where `navegador add concept` requires manual entry, Planopticon extracts concepts, rules, and decisions from meeting recordings automatically and navegador stores them alongside your code graph.
	8	+
	9	+---
	10	+
	11	+## How they connect
	12	+
	13	+```
	14	+Video / transcript
	15	+ ↓
	16	+ Planopticon
	17	+ ↓ produces
	18	+ knowledge_graph.json / interchange.json / manifest.json
	19	+ ↓
	20	+ navegador planopticon ingest
	21	+ ↓ creates
	22	+ Concept / Rule / Decision / Person / WikiPage nodes
	23	+ in the same FalkorDB graph as your code
	24	+```
	25	+
	26	+The result: "the team decided to use Redis for session storage in the March architecture review" becomes a `Decision` node linked to the `Infrastructure` domain and, via `GOVERNS`, to the `SessionManager` class in your code.
	27	+
	28	+---
	29	+
	30	+## Input formats
	31	+
	32	+Planopticon produces several output formats. Navegador accepts all of them and auto-detects by default.
	33	+
	34	+### manifest.json
	35	+
	36	+Top-level manifest for a multi-file Planopticon output package. Points to the knowledge graph, interchange, and supporting files.
	37	+
	38	+```json
	39	+{
	40	+ "version": "1.0",
	41	+ "source": "zoom-meeting-2026-03-15",
	42	+ "knowledge_graph": "knowledge_graph.json",
	43	+ "interchange": "interchange.json",
	44	+ "diagrams": ["arch-diagram.png"]
	45	+}
	46	+```
	47	+
	48	+### knowledge_graph.json
	49	+
	50	+Planopticon's native graph format. Contains typed entities and relationships:
	51	+
	52	+```json
	53	+{
	54	+ "entities": [
	55	+ { "id": "e1", "type": "Decision", "name": "UseRedisForSessions", "description": "...", "rationale": "..." },
	56	+ { "id": "e2", "type": "Person", "name": "Alice Chen", "role": "Lead Engineer" },
	57	+ { "id": "e3", "type": "Concept", "name": "SessionAffinity", "description": "..." }
	58	+ ],
	59	+ "relationships": [
	60	+ { "from": "e2", "to": "e1", "type": "DECIDED_BY" },
	61	+ { "from": "e1", "to": "e3", "type": "RELATED_TO" }
	62	+ ]
	63	+}
	64	+```
	65	+
	66	+### interchange.json
	67	+
	68	+A normalized interchange format, flatter than the native graph. Used when exporting from Planopticon for consumption by downstream tools.
	69	+
	70	+```json
	71	+{
	72	+ "concepts": [...],
	73	+ "rules": [...],
	74	+ "decisions": [...],
	75	+ "people": [...],
	76	+ "action_items": [...],
	77	+ "diagrams": [...]
	78	+}
	79	+```
	80	+
	81	+### Batch manifest
	82	+
	83	+A JSON file listing multiple Planopticon output directories or archive paths for bulk ingestion:
	84	+
	85	+```json
	86	+{
	87	+ "batch": [
	88	+ { "path": "./meetings/2026-03-15/", "source": "arch-review" },
	89	+ { "path": "./meetings/2026-02-20/", "source": "sprint-planning" }
	90	+ ]
	91	+}
	92	+```
	93	+
	94	+---
	95	+
	96	+## What maps to what
	97	+
	98	+\| Planopticon entity \| Navegador node \| Notes \|
	99	+\|---\|---\|---\|
	100	+\| `Concept` \| `Concept` \| Direct mapping; domain preserved if present \|
	101	+\| `Rule` \| `Rule` \| Severity set to `info` if not specified \|
	102	+\| `Decision` \| `Decision` \| `rationale`, `alternatives`, `date`, `status` preserved \|
	103	+\| `Person` \| `Person` \| `name`, `email`, `role`, `team` preserved \|
	104	+\| Action item \| `Rule` + `ASSIGNED_TO` \| Creates a `Rule` with severity `info`; creates `ASSIGNED_TO` edge to the `Person` \|
	105	+\| Diagram / image \| `WikiPage` \| Title from filename; content set to alt-text or caption \|
	106	+\| `Relationship: DECIDED_BY` \| `DECIDED_BY` edge \| Person → Decision \|
	107	+\| `Relationship: RELATED_TO` \| `RELATED_TO` edge \| Between any two knowledge nodes \|
	108	+\| Entity domain field \| `BELONGS_TO` edge \| Links node to named `Domain` (created if not exists) \|
	109	+
	110	+---
	111	+
	112	+## CLI examples
	113	+
	114	+### Auto-detect format (recommended)
	115	+
	116	+```bash
	117	+navegador planopticon ingest ./meeting-output/ --type auto
	118	+```
	119	+
	120	+### Explicit format
	121	+
	122	+```bash
	123	+navegador planopticon ingest ./meeting-output/knowledge_graph.json --type kg
	124	+navegador planopticon ingest ./meeting-output/interchange.json --type interchange
	125	+navegador planopticon ingest ./manifest.json --type manifest
	126	+navegador planopticon ingest ./batch.json --type batch
	127	+```
	128	+
	129	+### Label the source
	130	+
	131	+Use `--source` to tag all nodes from this ingestion with a source label (useful for auditing where knowledge came from):
	132	+
	133	+```bash
	134	+navegador planopticon ingest ./meeting-output/ \
	135	+ --type auto \
	136	+ --source "arch-review-2026-03-15"
	137	+```
	138	+
	139	+### JSON output
	140	+
	141	+```bash
	142	+navegador planopticon ingest ./meeting-output/ --json
	143	+```
	144	+
	145	+Returns a summary of nodes and edges created.
	146	+
	147	+---
	148	+
	149	+## Python API
	150	+
	151	+```python
	152	+from navegador.ingest import PlanopticonIngester
	153	+from navegador.graph import GraphStore
	154	+
	155	+store = GraphStore.sqlite(".navegador/navegador.db")
	156	+ingester = PlanopticonIngester(store)
	157	+
	158	+# auto-detect format
	159	+result = ingester.ingest("./meeting-output/", input_type="auto", source="arch-review")
	160	+
	161	+print(f"Created {result.nodes_created} nodes, {result.edges_created} edges")
	162	+
	163	+# ingest a specific interchange file
	164	+result = ingester.ingest_interchange("./interchange.json", source="sprint-planning")
	165	+```
	166	+
	167	+### PlanopticonIngester methods
	168	+
	169	+\| Method \| Description \|
	170	+\|---\|---\|
	171	+\| `ingest(path, input_type, source)` \| Auto or explicit ingest from path \|
	172	+\| `ingest_manifest(path, source)` \| Ingest a manifest.json package \|
	173	+\| `ingest_kg(path, source)` \| Ingest a knowledge_graph.json file \|
	174	+\| `ingest_interchange(path, source)` \| Ingest an interchange.json file \|
	175	+\| `ingest_batch(path, source)` \| Ingest a batch manifest \|

	--- a/docs/guide/planopticon.md
	+++ b/docs/guide/planopticon.md
	@@ -0,0 +1,175 @@

	--- a/docs/guide/planopticon.md
	+++ b/docs/guide/planopticon.md
	@@ -0,0 +1,175 @@
1	# Planopticon Integration
2
3	## What is Planopticon
4
5	Planopticon is a video and meeting knowledge extraction tool. It ingests recordings, transcripts, and meeting notes and produces structured knowledge graphs: entities (people, concepts, decisions), relationships, action items, and diagrams extracted from the meeting content.
6
7	Navegador treats Planopticon output as a first-class knowledge source. Where `navegador add concept` requires manual entry, Planopticon extracts concepts, rules, and decisions from meeting recordings automatically and navegador stores them alongside your code graph.
8
9	---
10
11	## How they connect
12
13	```
14	Video / transcript
15	↓
16	Planopticon
17	↓ produces
18	knowledge_graph.json / interchange.json / manifest.json
19	↓
20	navegador planopticon ingest
21	↓ creates
22	Concept / Rule / Decision / Person / WikiPage nodes
23	in the same FalkorDB graph as your code
24	```
25
26	The result: "the team decided to use Redis for session storage in the March architecture review" becomes a `Decision` node linked to the `Infrastructure` domain and, via `GOVERNS`, to the `SessionManager` class in your code.
27
28	---
29
30	## Input formats
31
32	Planopticon produces several output formats. Navegador accepts all of them and auto-detects by default.
33
34	### manifest.json
35
36	Top-level manifest for a multi-file Planopticon output package. Points to the knowledge graph, interchange, and supporting files.
37
38	```json
39	{
40	"version": "1.0",
41	"source": "zoom-meeting-2026-03-15",
42	"knowledge_graph": "knowledge_graph.json",
43	"interchange": "interchange.json",
44	"diagrams": ["arch-diagram.png"]
45	}
46	```
47
48	### knowledge_graph.json
49
50	Planopticon's native graph format. Contains typed entities and relationships:
51
52	```json
53	{
54	"entities": [
55	{ "id": "e1", "type": "Decision", "name": "UseRedisForSessions", "description": "...", "rationale": "..." },
56	{ "id": "e2", "type": "Person", "name": "Alice Chen", "role": "Lead Engineer" },
57	{ "id": "e3", "type": "Concept", "name": "SessionAffinity", "description": "..." }
58	],
59	"relationships": [
60	{ "from": "e2", "to": "e1", "type": "DECIDED_BY" },
61	{ "from": "e1", "to": "e3", "type": "RELATED_TO" }
62	]
63	}
64	```
65
66	### interchange.json
67
68	A normalized interchange format, flatter than the native graph. Used when exporting from Planopticon for consumption by downstream tools.
69
70	```json
71	{
72	"concepts": [...],
73	"rules": [...],
74	"decisions": [...],
75	"people": [...],
76	"action_items": [...],
77	"diagrams": [...]
78	}
79	```
80
81	### Batch manifest
82
83	A JSON file listing multiple Planopticon output directories or archive paths for bulk ingestion:
84
85	```json
86	{
87	"batch": [
88	{ "path": "./meetings/2026-03-15/", "source": "arch-review" },
89	{ "path": "./meetings/2026-02-20/", "source": "sprint-planning" }
90	]
91	}
92	```
93
94	---
95
96	## What maps to what
97
98	\| Planopticon entity \| Navegador node \| Notes \|
99	\|---\|---\|---\|
100	\| `Concept` \| `Concept` \| Direct mapping; domain preserved if present \|
101	\| `Rule` \| `Rule` \| Severity set to `info` if not specified \|
102	\| `Decision` \| `Decision` \| `rationale`, `alternatives`, `date`, `status` preserved \|
103	\| `Person` \| `Person` \| `name`, `email`, `role`, `team` preserved \|
104	\| Action item \| `Rule` + `ASSIGNED_TO` \| Creates a `Rule` with severity `info`; creates `ASSIGNED_TO` edge to the `Person` \|
105	\| Diagram / image \| `WikiPage` \| Title from filename; content set to alt-text or caption \|
106	\| `Relationship: DECIDED_BY` \| `DECIDED_BY` edge \| Person → Decision \|
107	\| `Relationship: RELATED_TO` \| `RELATED_TO` edge \| Between any two knowledge nodes \|
108	\| Entity domain field \| `BELONGS_TO` edge \| Links node to named `Domain` (created if not exists) \|
109
110	---
111
112	## CLI examples
113
114	### Auto-detect format (recommended)
115
116	```bash
117	navegador planopticon ingest ./meeting-output/ --type auto
118	```
119
120	### Explicit format
121
122	```bash
123	navegador planopticon ingest ./meeting-output/knowledge_graph.json --type kg
124	navegador planopticon ingest ./meeting-output/interchange.json --type interchange
125	navegador planopticon ingest ./manifest.json --type manifest
126	navegador planopticon ingest ./batch.json --type batch
127	```
128
129	### Label the source
130
131	Use `--source` to tag all nodes from this ingestion with a source label (useful for auditing where knowledge came from):
132
133	```bash
134	navegador planopticon ingest ./meeting-output/ \
135	--type auto \
136	--source "arch-review-2026-03-15"
137	```
138
139	### JSON output
140
141	```bash
142	navegador planopticon ingest ./meeting-output/ --json
143	```
144
145	Returns a summary of nodes and edges created.
146
147	---
148
149	## Python API
150
151	```python
152	from navegador.ingest import PlanopticonIngester
153	from navegador.graph import GraphStore
154
155	store = GraphStore.sqlite(".navegador/navegador.db")
156	ingester = PlanopticonIngester(store)
157
158	# auto-detect format
159	result = ingester.ingest("./meeting-output/", input_type="auto", source="arch-review")
160
161	print(f"Created {result.nodes_created} nodes, {result.edges_created} edges")
162
163	# ingest a specific interchange file
164	result = ingester.ingest_interchange("./interchange.json", source="sprint-planning")
165	```
166
167	### PlanopticonIngester methods
168
169	\| Method \| Description \|
170	\|---\|---\|
171	\| `ingest(path, input_type, source)` \| Auto or explicit ingest from path \|
172	\| `ingest_manifest(path, source)` \| Ingest a manifest.json package \|
173	\| `ingest_kg(path, source)` \| Ingest a knowledge_graph.json file \|
174	\| `ingest_interchange(path, source)` \| Ingest an interchange.json file \|
175	\| `ingest_batch(path, source)` \| Ingest a batch manifest \|

M docs/index.md

+88 -25

		--- docs/index.md
		+++ docs/index.md
		@@ -1,46 +1,108 @@
1	1	# Navegador
2	2
3		-AST + knowledge graph context engine for AI coding agents.
	3	+The project knowledge graph for AI coding agents.
4	4
5		-Navegador parses your codebase into a property graph — functions, classes, files, imports, call relationships — and makes that structure queryable by AI coding agents via MCP or a Python API.
	5	+Navegador builds and maintains a queryable graph of your software project — combining static code analysis with human-curated business knowledge — so that AI coding agents always have precise, structured context instead of raw file dumps.
6	6
7	7	> navegador — Spanish for navigator / sailor. It helps agents navigate your code.
8	8
9	9	---
10	10
11		-## Why
12		-
13		-AI coding agents (Claude, Cursor, Copilot) load context by reading raw files. They don't know what calls what, what depends on what, or how to find the relevant 5 functions out of 500. Navegador gives agents a structured map.
14		-
15		-```
16		-agent: "find everything that depends on auth1/sessions.py"
17		-
18		-→ MATCH (f:File {path: "auth1/sessions.py"})<-[:IMPORTS\|CALLS*1..3]-(n)
19		-→ returns: 4 files, 12 functions, full source + docstrings
20		-```
21		-
		----
22		-
23		-## Features
24		-
25		-- Multi-language AST parsing — Python and TypeScript/JavaScript via tree-sitter
26		-- Property graph storage — FalkorDB-lite (SQLite, zero infra) or Redis FalkorDB for production
27		-- MCP server — native integration with Claude, Cursor, and any MCP-compatible agent
28		-- Context bundles — structured JSON or markdown export of a file/function/class and its relationships
29		-- CLI — `navegador ingest ./myrepo`, `navegador context src/auth.py`
	11	+## Two layers, one graph
	12	+
	13	+```
	14	+┌─────────────────────────────────────────────────────────────────┐
	15	+│ KNOWLEDGE LAYER │
	16	+│ Concepts · Rules · Decisions · WikiPages · People · Domains │
	17	+│ │
	18	+│ ↕ GOVERNS / IMPLEMENTS / DOCUMENTS / ANNOTATES │
	19	+│ │
	20	+│ CODE LAYER │
	21	+│ Repository · File · Module · Class · Function · Method │
	22	+│ Variable · Import · Decorator · (call graphs, hierarchies) │
	23	+└─────────────────────────────────────────────────────────────────┘
	24	+ stored in FalkorDB (SQLite local / Redis prod)
	25	+```
	26	+
	27	+The code layer is populated automatically by ingesting source trees. Python and TypeScript are supported out of the box via tree-sitter. The knowledge layer is populated by manual curation (`navegador add`), GitHub wiki ingestion, and [Planopticon](guide/planopticon.md) output (meeting and video knowledge graphs).
30	28
31	29	---
32	30
33	31	## Quick start
34	32
35	33	```bash
36		-pip install navegador
37		-navegador ingest ./myrepo
38		-navegador context src/auth.py
	34	+pip install navegador # Python 3.12+ required
	35	+navegador ingest ./my-repo # parse + index the codebase
	36	+navegador explain AuthService # what is this thing?
	37	+navegador search "rate limit" --all # search code + knowledge together
39	38	```
40	39
	40	+---
	41	+
	42	+## What goes in the graph
	43	+
	44	+\| Layer \| Node type \| Populated by \|
	45	+\|---\|---\|---\|
	46	+\| Code \| Repository, File, Module \| `navegador ingest` \|
	47	+\| Code \| Class, Function, Method \| `navegador ingest` (tree-sitter AST) \|
	48	+\| Code \| Decorator, Import, Variable \| `navegador ingest` \|
	49	+\| Code \| CALLS / INHERITS edges \| `navegador ingest` (call graph analysis) \|
	50	+\| Knowledge \| Concept, Domain \| `navegador add concept` / `add domain` \|
	51	+\| Knowledge \| Rule \| `navegador add rule` \|
	52	+\| Knowledge \| Decision \| `navegador add decision` \|
	53	+\| Knowledge \| Person \| `navegador add person` \|
	54	+\| Knowledge \| WikiPage \| `navegador wiki ingest` \|
	55	+\| Knowledge \| (any) \| `navegador planopticon ingest` \|
	56	+\| Cross-layer \| ANNOTATES, GOVERNS, IMPLEMENTS \| `navegador annotate` \|
	57	+
	58	+---
	59	+
	60	+## Agent integration
	61	+
	62	+=== "CLI"
	63	+
	64	+ The simplest integration: call `navegador explain` or `navegador context` from any shell script or agent tool definition.
	65	+
	66	+ ```bash
	67	+ # get context for the file the agent just edited
	68	+ navegador context src/auth/service.py --format json
	69	+
	70	+ # look up a function before editing it
	71	+ navegador function validate_token --depth 2 --format json
	72	+
	73	+ # find everything annotated with a business concept
	74	+ navegador concept PaymentProcessing --format json
	75	+ ```
	76	+
	77	+=== "MCP"
	78	+
	79	+ Run navegador as a Model Context Protocol server. Configure it once in your agent settings and all navegador commands become callable tools with structured input/output.
	80	+
	81	+ ```json
	82	+ {
	83	+ "mcpServers": {
	84	+ "navegador": {
	85	+ "command": "navegador",
	86	+ "args": ["mcp"]
	87	+ }
	88	+ }
	89	+ }
	90	+ ```
	91	+
	92	+ See [MCP Integration](guide/mcp-integration.md) for the full tool list and per-agent config snippets.
	93	+
	94	+=== "Bootstrap"
	95	+
	96	+ One command to install navegador, ingest a repo, and wire the agent hook for your preferred AI coding assistant.
	97	+
	98	+ ```bash
	99	+ ./bootstrap.sh --repo owner/repo --wiki --agent claude
	100	+ ```
	101	+
	102	+ Supports `--agent claude`, `--agent gemini`, and `--agent openai`. See [Agent Hooks](guide/agent-hooks.md) for what the hook does and how to configure it manually.
	103	+
41	104	---
42	105
43	106	## License
44	107
45		-MIT — [CONFLICT LLC](https://github.com/ConflictHQ)
	108	+Navegador is open source under the [MIT License](https://github.com/ConflictHQ/navegador/blob/main/LICENSE). Copyright 2026 CONFLICT LLC.
46	109

	--- docs/index.md
	+++ docs/index.md
	@@ -1,46 +1,108 @@
1	# Navegador
2
3	AST + knowledge graph context engine for AI coding agents.
4
5	Navegador parses your codebase into a property graph — functions, classes, files, imports, call relationships — and makes that structure queryable by AI coding agents via MCP or a Python API.
6
7	> navegador — Spanish for navigator / sailor. It helps agents navigate your code.
8
9	---
10
11	## Why
12
13	AI coding agents (Claude, Cursor, Copilot) load context by reading raw files. They don't know what calls what, what depends on what, or how to find the relevant 5 functions out of 500. Navegador gives agents a structured map.
14
15	```
16	agent: "find everything that depends on auth1/sessions.py"
17
18	→ MATCH (f:File {path: "auth1/sessions.py"})<-[:IMPORTS\|CALLS*1..3]-(n)
19	→ returns: 4 files, 12 functions, full source + docstrings
20	```
21
	----
22
23	## Features
24
25	- Multi-language AST parsing — Python and TypeScript/JavaScript via tree-sitter
26	- Property graph storage — FalkorDB-lite (SQLite, zero infra) or Redis FalkorDB for production
27	- MCP server — native integration with Claude, Cursor, and any MCP-compatible agent
28	- Context bundles — structured JSON or markdown export of a file/function/class and its relationships
29	- CLI — `navegador ingest ./myrepo`, `navegador context src/auth.py`









30
31	---
32
33	## Quick start
34
35	```bash
36	pip install navegador
37	navegador ingest ./myrepo
38	navegador context src/auth.py

39	```
40
































































41	---
42
43	## License
44
45	MIT — [CONFLICT LLC](https://github.com/ConflictHQ)
46

	--- docs/index.md
	+++ docs/index.md
	@@ -1,46 +1,108 @@
1	# Navegador
2
3	The project knowledge graph for AI coding agents.
4
5	Navegador builds and maintains a queryable graph of your software project — combining static code analysis with human-curated business knowledge — so that AI coding agents always have precise, structured context instead of raw file dumps.
6
7	> navegador — Spanish for navigator / sailor. It helps agents navigate your code.
8
9	---
10











	----
11	## Two layers, one graph
12
13	```
14	┌─────────────────────────────────────────────────────────────────┐
15	│ KNOWLEDGE LAYER │
16	│ Concepts · Rules · Decisions · WikiPages · People · Domains │
17	│ │
18	│ ↕ GOVERNS / IMPLEMENTS / DOCUMENTS / ANNOTATES │
19	│ │
20	│ CODE LAYER │
21	│ Repository · File · Module · Class · Function · Method │
22	│ Variable · Import · Decorator · (call graphs, hierarchies) │
23	└─────────────────────────────────────────────────────────────────┘
24	stored in FalkorDB (SQLite local / Redis prod)
25	```
26
27	The code layer is populated automatically by ingesting source trees. Python and TypeScript are supported out of the box via tree-sitter. The knowledge layer is populated by manual curation (`navegador add`), GitHub wiki ingestion, and [Planopticon](guide/planopticon.md) output (meeting and video knowledge graphs).
28
29	---
30
31	## Quick start
32
33	```bash
34	pip install navegador # Python 3.12+ required
35	navegador ingest ./my-repo # parse + index the codebase
36	navegador explain AuthService # what is this thing?
37	navegador search "rate limit" --all # search code + knowledge together
38	```
39
40	---
41
42	## What goes in the graph
43
44	\| Layer \| Node type \| Populated by \|
45	\|---\|---\|---\|
46	\| Code \| Repository, File, Module \| `navegador ingest` \|
47	\| Code \| Class, Function, Method \| `navegador ingest` (tree-sitter AST) \|
48	\| Code \| Decorator, Import, Variable \| `navegador ingest` \|
49	\| Code \| CALLS / INHERITS edges \| `navegador ingest` (call graph analysis) \|
50	\| Knowledge \| Concept, Domain \| `navegador add concept` / `add domain` \|
51	\| Knowledge \| Rule \| `navegador add rule` \|
52	\| Knowledge \| Decision \| `navegador add decision` \|
53	\| Knowledge \| Person \| `navegador add person` \|
54	\| Knowledge \| WikiPage \| `navegador wiki ingest` \|
55	\| Knowledge \| (any) \| `navegador planopticon ingest` \|
56	\| Cross-layer \| ANNOTATES, GOVERNS, IMPLEMENTS \| `navegador annotate` \|
57
58	---
59
60	## Agent integration
61
62	=== "CLI"
63
64	The simplest integration: call `navegador explain` or `navegador context` from any shell script or agent tool definition.
65
66	```bash
67	# get context for the file the agent just edited
68	navegador context src/auth/service.py --format json
69
70	# look up a function before editing it
71	navegador function validate_token --depth 2 --format json
72
73	# find everything annotated with a business concept
74	navegador concept PaymentProcessing --format json
75	```
76
77	=== "MCP"
78
79	Run navegador as a Model Context Protocol server. Configure it once in your agent settings and all navegador commands become callable tools with structured input/output.
80
81	```json
82	{
83	"mcpServers": {
84	"navegador": {
85	"command": "navegador",
86	"args": ["mcp"]
87	}
88	}
89	}
90	```
91
92	See [MCP Integration](guide/mcp-integration.md) for the full tool list and per-agent config snippets.
93
94	=== "Bootstrap"
95
96	One command to install navegador, ingest a repo, and wire the agent hook for your preferred AI coding assistant.
97
98	```bash
99	./bootstrap.sh --repo owner/repo --wiki --agent claude
100	```
101
102	Supports `--agent claude`, `--agent gemini`, and `--agent openai`. See [Agent Hooks](guide/agent-hooks.md) for what the hook does and how to configure it manually.
103
104	---
105
106	## License
107
108	Navegador is open source under the [MIT License](https://github.com/ConflictHQ/navegador/blob/main/LICENSE). Copyright 2026 CONFLICT LLC.
109

M mkdocs.yml

+3 -1

		--- mkdocs.yml
		+++ mkdocs.yml
		@@ -1,8 +1,8 @@
1	1	site_name: Navegador
2	2	site_url: https://navegador.dev
3		-site_description: AST + knowledge graph context engine for AI coding agents
	3	+site_description: Project knowledge graph for AI coding agents — code structure, business rules, and architectural decisions in one queryable graph
4	4	site_author: CONFLICT LLC
5	5	repo_url: https://github.com/ConflictHQ/navegador
6	6	repo_name: ConflictHQ/navegador
7	7
8	8	theme:
		@@ -81,10 +81,12 @@
81	81	- Guide:
82	82	- Ingesting a Repo: guide/ingestion.md
83	83	- Loading Context: guide/context-loading.md
84	84	- Graph Queries: guide/graph-queries.md
85	85	- MCP Integration: guide/mcp-integration.md
	86	+ - Agent Hooks: guide/agent-hooks.md
	87	+ - Planopticon: guide/planopticon.md
86	88	- Architecture:
87	89	- Overview: architecture/overview.md
88	90	- Graph Schema: architecture/graph-schema.md
89	91	- API Reference:
90	92	- Ingestion: api/ingestion.md
91	93

	--- mkdocs.yml
	+++ mkdocs.yml
	@@ -1,8 +1,8 @@
1	site_name: Navegador
2	site_url: https://navegador.dev
3	site_description: AST + knowledge graph context engine for AI coding agents
4	site_author: CONFLICT LLC
5	repo_url: https://github.com/ConflictHQ/navegador
6	repo_name: ConflictHQ/navegador
7
8	theme:
	@@ -81,10 +81,12 @@
81	- Guide:
82	- Ingesting a Repo: guide/ingestion.md
83	- Loading Context: guide/context-loading.md
84	- Graph Queries: guide/graph-queries.md
85	- MCP Integration: guide/mcp-integration.md


86	- Architecture:
87	- Overview: architecture/overview.md
88	- Graph Schema: architecture/graph-schema.md
89	- API Reference:
90	- Ingestion: api/ingestion.md
91

	--- mkdocs.yml
	+++ mkdocs.yml
	@@ -1,8 +1,8 @@
1	site_name: Navegador
2	site_url: https://navegador.dev
3	site_description: Project knowledge graph for AI coding agents — code structure, business rules, and architectural decisions in one queryable graph
4	site_author: CONFLICT LLC
5	repo_url: https://github.com/ConflictHQ/navegador
6	repo_name: ConflictHQ/navegador
7
8	theme:
	@@ -81,10 +81,12 @@
81	- Guide:
82	- Ingesting a Repo: guide/ingestion.md
83	- Loading Context: guide/context-loading.md
84	- Graph Queries: guide/graph-queries.md
85	- MCP Integration: guide/mcp-integration.md
86	- Agent Hooks: guide/agent-hooks.md
87	- Planopticon: guide/planopticon.md
88	- Architecture:
89	- Overview: architecture/overview.md
90	- Graph Schema: architecture/graph-schema.md
91	- API Reference:
92	- Ingestion: api/ingestion.md
93

Navegador

Keyboard Shortcuts