Ingesting a Repo

Navegador builds the graph from four sources: code, manual knowledge curation, GitHub wikis, and Planopticon knowledge graph output.

---

Code ingestion

navegador ingest ./repo

What gets extracted

Navegador walks all source files in the repo and uses tree-sitter to extract structure. Supported languages:

Extension(s)	Language
.py	Python
.ts, .tsx	TypeScript
.js, .jsx	JavaScript
.go	Go
.rs	Rust
.java	Java

The following directories are always skipped: .git, .venv, venv, node_modules, __pycache__, dist, build, .next, target (Rust/Java builds), vendor (Go modules), .gradle.

What gets extracted

What	Graph nodes / edges created
Files	File node; CONTAINS edge from Repository
Classes, structs, interfaces	Class node with name, file, line, docstring
Functions and methods	Function / Method nodes with name, docstring, line
Imports / use declarations	Import node; IMPORTS edge from the importing file
Call relationships	CALLS edges between functions based on static call analysis
Inheritance	INHERITS edges from subclass to parent

Doc comment formats supported per language: Python docstrings, JSDoc (/** */), Rust ///, Java Javadoc.

Options

Flag	Effect
--clear	Wipe the graph before ingesting (full rebuild)
--json	Output a JSON summary of nodes and edges created
--db <path>	Use a specific database file

Re-ingesting

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).

---

Knowledge curation

Manual knowledge is added with navegador add commands and linked to code with navegador annotate.

Concepts

A concept is a named idea or design pattern relevant to the codebase.

navegador add concept "Idempotency" \
  --desc "Operations safe to retry without side effects" \
  --domain Payments

Rules

A rule is an enforceable constraint on code behaviour.

navegador add rule "RequireIdempotencyKey" \
  --desc "All write endpoints must accept an idempotency key header" \
  --domain Payments \
  --severity critical \
  --rationale "Prevents double-processing on client retries"

Severity values: info, warning, critical.

Decisions

An architectural decision record (ADR) stored in the graph.

navegador add decision "UsePostgresForTransactions" \
  --desc "PostgreSQL is the primary datastore for transactional data" \
  --domain Infrastructure \
  --rationale "ACID guarantees required for financial data" \
  --alternatives "MySQL, CockroachDB" \
  --date 2025-03-01 \
  --status accepted

Status values: proposed, accepted, deprecated, superseded.

People

navegador add person "Alice Chen" \
  --email [email protected] \
  --role "Lead Engineer" \
  --team Payments

Domains

Domains are top-level groupings for concepts, rules, and decisions.

navegador add domain "Payments" \
  --desc "Everything related to payment processing and billing"

Annotating code

Link a code node to a concept or rule:

navegador annotate process_payment \
  --type Function \
  --concept Idempotency \
  --rule RequireIdempotencyKey

--type accepts: Function, Class, Method, File, Module.

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.

---

Wiki ingestion

Pull a GitHub wiki into the graph as WikiPage nodes.

# ingest from GitHub API
navegador wiki ingest --repo myorg/myrepo --token $GITHUB_TOKEN

# ingest from a locally cloned wiki directory
navegador wiki ingest --dir ./myrepo.wiki

# force API mode (bypass auto-detection)
navegador wiki ingest --repo myorg/myrepo --api

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.

Set GITHUB_TOKEN in your environment to avoid rate limits and to access private wikis.

---

Planopticon ingestion

Planopticon is a video/meeting knowledge extraction tool. It produces structured knowledge graph output that navegador can ingest directly.

navegador planopticon ingest ./meeting-output/ --type auto

See the Planopticon guide for the full input format reference and entity mapping details.