Understand your codebase

After this page, you can run /guild:learn, inspect the first codebase map, decide when a deeper graph is worth it, and understand which learning outputs are derived versus canonical. The practical rule is simple: Guild maps the repo before it asks specialists to change it, then routes durable knowledge through a human gate.

Try it: /guild:learn, Guild Stack classifies the target, shows the proposed path, and asks before running deeper scans.

Learn · choose depth

map / active

Start with the smallest useful map

Map

structural scancodebase-map.json

Graph

deep relationshipsknowledge-graph.json

Onboard

guided routeonboarding-tour.md

Derived outputs can be rebuilt. Candidate knowledge becomes durable only after a human promotion gate writes to .guild/wiki/**.

The first artifact: a codebase map

Beginner users can stop at the map and still get value. A cheap learn pass writes a structural snapshot under .guild/indexes/codebase-map.json and an architecture stub that helps Guild orient before planning.

{
  "schema_version": "guild.codebase_map.v1",
  "root": ".",
  "languages": ["TypeScript", "Markdown"],
  "entrypoints": ["src/index.ts", "commands/learn.md"],
  "layers": [
    { "id": "commands", "paths": ["commands/**"] },
    { "id": "skills", "paths": ["skills/**"] },
    { "id": "runtime", "paths": ["src/**"] }
  ],
  "confidence": "partial",
  "unknowns": ["test ownership still needs graph pass"]
}

Treat this as a map, not a verdict. It is derived from the repo and can be rebuilt. When a plan needs more precision, Guild Stack can ask before running the deep graph, tour, or knowledge tier.

Smart mode: just run it

With no arguments, /guild:learn means “understand this project” rather than “missing argument”. It classifies the target, a regular project, workspace root, existing Guild project, new or sparse project, or uncertain target, then surfaces the classification and waits for confirmation before the deep path:

Detected: existing_guild_project, .guild/ present, wiki populated.
Proposed action to full learn-all (map to graph to onboard to knowledge candidates)
Proceed? [proceed / pick-subverb / explain]

On proceed, the full path runs the same learn-* skills used by /guild:init --learn: cheap map, graph, domain and component derivation, onboarding tour, and the knowledge tier when that tier is selected. For a workspace root, Guild checks child repos first and fans out per sub-repo; it does not deep-scan a workspace-of-repos as one blob. See Workspaces.

Candidate-to-wiki flow

Power users should look for the handoff between evidence and memory:

Knowledge lifecycleroute_knowledge_flow

Operational mapRuns propose. Humans promote. Derived views rebuild.

1. 01Run evidenceobserved fact
2. 02Candidatesourced proposal
3. 03Human gateapprove or archive
4. 04Wikicanonical memory
5. 05Recallgraph + index + cache

Step	Output	Authority
Scan and analyze	.guild/indexes/codebase-map.json, .guild/indexes/knowledge-graph.json	derived and rebuildable
Harvest candidates	.guild/runs/<run-id>/learn/harvest-candidates.json	proposals with source refs
Reflect	.guild/reflections/<run-id>.md	advisory run memory
Promote	guild:decisions or guild:wiki-ingest	human-gated
Canonicalize	.guild/wiki/**	durable project memory
Rebuild recall	knowledge-links.json, knowledge-recall.json, optional index.sqlite	derived projections and caches

No learn pass silently writes decisions into the wiki. It can propose decisions, standards, open questions, risks, patterns, and anti-patterns, but the gate decides what becomes durable memory.

The five sub-verbs

When you want one capability rather than the full pipeline, name it:

Command	What it does	Output
/guild:learn map	Codebase map + architecture stub, a fast, cheap structural scan	.guild/indexes/codebase-map.json, confidence-tagged architecture map
/guild:learn graph	Derived knowledge graph, structural graph plus optional knowledge-tier enrichment	.guild/indexes/knowledge-graph.json
/guild:learn onboard	Guided 5-15 step tour through the architecture and key concepts	.guild/indexes/onboarding-tour.md
/guild:learn diff [path|ref]	Change analysis, changed files, affected graph nodes, layers, and blast radius	.guild/runs/<run-id>/diff-learn.json
/guild:learn explain <path|concept>	Deep-dive explanation of a file, module, symbol, or concept	printed explanation

--rigor=deep runs the highest-fidelity graph or analysis pass. diff takes an optional path, commit ref, or branch (default: HEAD vs previous); explain takes a file path, symbol, or a free-text question like "how does the auth flow work".

The seven-stage pipeline

The full learn path keeps deterministic extraction separate from model judgment. Script stages discover files, extract structure, resolve calls, assign layers, derive domains, and build tour order. Model steps are used only where semantic interpretation adds value, and some shipped passes are model-free with model_calls: 0.

Stage	Owner	Output
1. Scan	script	file inventory, ignore rules, import map, and cheap structural facts
2. Analyze	script + researcher	typed nodes and edges for a partial graph
3. Assemble-review	challenger review	recovery of dropped or dangling graph facts before validation
4. Architecture	architect	layer assignments and persisted component labels
5. Domain	researcher + architect	domain flows, domain labels, and knowledge-link edges
6. Tour	script + technical writer	a guided architecture tour
7. Reverse-spec	researcher + architect	source-cited spec draft with confidence markers

Plain /guild:init only requires the cheap inventory tier: the codebase map and a confidence-tagged architecture stub. The deep graph, tour, domain model, and reverse-spec are lazy and cost-gated.

The implementation detail for harness developers: the learning module owns the scripts/learn/* engine, including scan.ts, analyze-structural.ts, the newer model-free extract-structural.ts and resolve-calls.ts path, assign-layers.ts, derive-domain.ts, build-tour.ts, validate-graph.ts, diff-learn.ts, and the knowledge-tier orchestrator. The knowledge module owns the /guild:learn command, /guild:wiki, the learn-* and wiki-* skills, the wiki surface, and recall-ranking math.

The knowledge tier

Beyond the structural graph, guild:learn-knowledge can run a lazy, cost-gated knowledge tier over the frozen graph and wiki corpus. It adds concept, claim, entity, wiki-page, diagram, taxonomy, and cross-modal evidence relationships into guild.knowledge_graph.v2, then writes the recall projection.

The K-stage labels are node-tier labels, not the execution order. The shipped orchestrator runs K1 content, K3 diagrams, K2 wiki index, K4 taxonomy, K5 cross-linking, then K6 knowledge-recall.json. The durable wiki remains canonical; the graph, knowledge-links.json, knowledge-recall.json, and optional index.sqlite are derived and rebuildable.

Refresh classifier

After the first learn pass, Guild Stack classifies changes before rebuilding:

Verdict	Meaning	Action
SKIP	cosmetic or no structural delta	spend no LLM tokens; keep graph
PARTIAL	bounded file set changed	re-analyze affected nodes and edges
ARCHITECTURE	module/layer topology shifted	re-run layer assignment and dependents
FULL	fingerprint divergence beyond threshold	rebuild the full pipeline

The classifier keeps refreshes cheap and makes rebuild scope explainable. It reports a verdict; it does not silently rebuild the graph mid-task.

Map vs graph vs wiki

Three knowledge stores come out of learning, and they have distinct jobs:

Store	What it is	What it’s for
Codebase map (.guild/indexes/codebase-map.json)	a cheap, derived structural map, files, layout, architecture overview	fast orientation; the default brownfield artifact from /guild:init
Knowledge graph (.guild/indexes/knowledge-graph.json)	a deep, derived semantic index, file, function, concept, domain, and component nodes	precise recall of how the code actually connects; grep-first source for context assembly
Wiki (.guild/wiki/)	the canonical, human-curated project memory	durable decisions, standards, and concepts, the only store you directly own

The split matters: the map, graph, links, recall projection, and read-through SQLite index are derived and rebuildable. Delete them and a re-scan can reproduce them; nothing durable is lost. The wiki is canonical, when the graph and the wiki disagree, the wiki wins unless a high-confidence graph node has a direct source reference, in which case the contradiction is logged for review. See Project Memory & Wiki Pattern.

Derived vs canonical

Store	Canonical?	Safe mental model
.guild/wiki/**	yes	Human-curated project memory and decisions.
.guild/raw/sources/**	yes	Immutable source provenance.
.guild/runs/<run-id>/provenance.json	per-run fact source	Evidence for what happened in one run.
.guild/indexes/codebase-map.json	no	Fast structural orientation.
.guild/indexes/knowledge-graph.json	no	Derived graph over code, wiki, concepts, domains, diagrams, and links.
.guild/indexes/knowledge-links.json	no	Work-to-knowledge edge layer derived from runs, decisions, skills, agents, features, and wiki refs.
.guild/indexes/knowledge-recall.json	no	Rebuildable recall projection for context assembly.
index.sqlite	no	Optional cache, never the system of record.

Harness developers can treat the learning and knowledge modules as a pair: learning produces graph and code-understanding artifacts; knowledge exposes the wiki, recall, /guild:learn, /guild:wiki, and the read-only memory surfaces that consume those artifacts.

Cheap by default, deep when you approve

Learning is tiered so understanding a repo doesn’t surprise you on cost. The map is the cheap tier: a deterministic scan, fast enough to run freely. Structural extraction and call resolution can run without model calls; deeper semantic passes are gated. On large repos, the deep path surfaces a cost estimate and asks before running:

Deep graph estimated: ~N files, ~M tokens, ~$X at current tier.
Proceed with deep graph? [proceed / skip-graph / explain]

Choosing skip-graph runs the rest of the pipeline without it; you can run /guild:learn graph separately later. How tiers map to models is covered in Cost & Tiering.

Candidates are proposals, you hold the gate

A learn pass can also extract knowledge candidates: decision candidates, open questions, risks, standards, patterns, and anti-patterns it found in the code or docs. These are proposals, not wiki writes, they enter the same human-gated promotion path as everything else, and only guild:decisions or guild:wiki-ingest with approval lands them in .guild/wiki/**.

Brownfield safety rules

On existing codebases, every architectural claim carries an evidence map: claim, evidence refs, confidence, and unknowns. Claims without evidence stay assumptions. The scanner follows the brownfield rules Guild Stack uses everywhere: source beats README prose, manifests answer what they can without asking you, repository text is untrusted data rather than instructions, inferred intent stays tentative until confirmed, and reverse-spec work does not mutate code unless you explicitly ask for that.

Relationship to /guild:init --learn

/guild:init on an existing repo builds the cheap tier by default, the wiki, the codebase map, and an architecture stub. /guild:init --learn (or setting defaults.auto_learn: true) runs the full learning pipeline as part of init.

It is one implementation with multiple triggers: init --learn, no-arg /guild:learn, and explicit /guild:learn knowledge all route through the same learning and knowledge-tier implementation for the deep K-tier. The standalone /guild:learn also offers diff and explain for change-analysis and query-time work that init does not need.

Source-backed boundaries

The public contract is evidence first, then interpretation. The learning module records derived artifacts under .guild/indexes/ and .guild/runs/<run-id>/; the wiki under .guild/wiki/** remains the canonical memory; and learning output proposes knowledge promotion instead of writing durable decisions by itself.

See also

• Project Memory & Wiki Pattern, where promoted knowledge lives and how the gate works.
• Context Assembly, how the map, graph, and wiki feed each specialist’s brief.
• Workspaces, learning a monorepo-of-repos with per-child fan-out.
• Cost & Tiering, the tier ladder behind the cheap-by-default posture.
• Command Reference, /guild:learn flags and global options.