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