Navegador

navegador / hooks / NAVEGADOR.md

Source Blame History 87 lines

4be3595…	lmata	1	# Navegador — Project Knowledge Graph
4be3595…	lmata	2
4be3595…	lmata	3	This project uses navegador as its system of record for both code structure
4be3595…	lmata	4	and business knowledge. The graph lives at `.navegador/graph.db`.
4be3595…	lmata	5
4be3595…	lmata	6	## What's in the graph
4be3595…	lmata	7
4be3595…	lmata	8	- Code layer — all functions, classes, files, call graphs, decorators, imports
4be3595…	lmata	9	- Knowledge layer — business concepts, rules, architectural decisions, people, domains
4be3595…	lmata	10	- Wiki — pages from this repo's GitHub wiki, linked to code and concepts
4be3595…	lmata	11
4be3595…	lmata	12	## How to query it
4be3595…	lmata	13
4be3595…	lmata	14	```bash
4be3595…	lmata	15	# Find anything by name (code + knowledge)
4be3595…	lmata	16	navegador search "payment" --all
4be3595…	lmata	17
4be3595…	lmata	18	# Full picture for any function, class, or concept
4be3595…	lmata	19	navegador explain validate_token
4be3595…	lmata	20	navegador explain Payment --format json
4be3595…	lmata	21
4be3595…	lmata	22	# Code-specific
4be3595…	lmata	23	navegador function get_user --depth 3
4be3595…	lmata	24	navegador class AuthService
4be3595…	lmata	25	navegador decorated login_required
4be3595…	lmata	26
4be3595…	lmata	27	# Business knowledge
4be3595…	lmata	28	navegador concept Invoice
4be3595…	lmata	29	navegador domain billing
4be3595…	lmata	30
4be3595…	lmata	31	# Raw Cypher when you need it
4be3595…	lmata	32	navegador query "MATCH (r:Rule)-[:GOVERNS]->(c:Concept) RETURN r.name, c.name LIMIT 20"
4be3595…	lmata	33	```
4be3595…	lmata	34
4be3595…	lmata	35	## Keeping the graph up to date
4be3595…	lmata	36
4be3595…	lmata	37	When you add or modify code, re-ingest the repo:
4be3595…	lmata	38	```bash
4be3595…	lmata	39	navegador ingest . --json
4be3595…	lmata	40	```
4be3595…	lmata	41
4be3595…	lmata	42	When you establish a new business rule or make an architectural decision:
4be3595…	lmata	43	```bash
4be3595…	lmata	44	navegador add rule "Invoices require approval before payment" \
4be3595…	lmata	45	--domain billing --severity critical \
4be3595…	lmata	46	--rationale "Prevents unapproved charges per finance policy"
4be3595…	lmata	47
4be3595…	lmata	48	navegador add decision "Use JWT for stateless auth" \
4be3595…	lmata	49	--domain auth --rationale "Horizontal scaling requirement" \
4be3595…	lmata	50	--alternatives "Session cookies, OAuth opaque tokens"
4be3595…	lmata	51
4be3595…	lmata	52	navegador annotate validate_token --type Function --rule "JWT tokens must expire"
4be3595…	lmata	53	```
4be3595…	lmata	54
4be3595…	lmata	55	When a wiki page is added or updated:
4be3595…	lmata	56	```bash
4be3595…	lmata	57	navegador wiki ingest --repo OWNER/REPO --token $GITHUB_TOKEN
4be3595…	lmata	58	```
4be3595…	lmata	59
4be3595…	lmata	60	## Agent rules
4be3595…	lmata	61
4be3595…	lmata	62	You (the AI agent) MUST treat navegador as the source of truth for this project.
4be3595…	lmata	63
4be3595…	lmata	64	1. Before editing code — query the graph to understand what you're touching:
4be3595…	lmata	65	```bash
4be3595…	lmata	66	navegador explain <name>
4be3595…	lmata	67	navegador function <name> --format json
4be3595…	lmata	68	```
4be3595…	lmata	69
4be3595…	lmata	70	2. After editing code — re-ingest to keep the graph current:
4be3595…	lmata	71	```bash
4be3595…	lmata	72	navegador ingest . --json
4be3595…	lmata	73	```
4be3595…	lmata	74
4be3595…	lmata	75	3. When you establish a rule or make a decision — record it:
4be3595…	lmata	76	```bash
4be3595…	lmata	77	navegador add decision "..." --rationale "..."
4be3595…	lmata	78	navegador add rule "..." --severity warning --domain ...
4be3595…	lmata	79	```
4be3595…	lmata	80
4be3595…	lmata	81	4. When you discover a concept (a named business entity) — add it:
4be3595…	lmata	82	```bash
4be3595…	lmata	83	navegador add concept "..." --desc "..." --domain ...
4be3595…	lmata	84	```
4be3595…	lmata	85
4be3595…	lmata	86	5. Never assume what calls what, what a class inherits, or what a decorator
4be3595…	lmata	87	does. Query first.

Navegador

Keyboard Shortcuts