Learning Your Codebase

/xavier learn scans a repository and produces a set of interlinked Zettelkasten notes in your vault. It's the fastest way to onboard Xavier (and yourself) to a new codebase.

What it produces

Xavier generates atomic notes for each artifact it discovers:

• Architecture map — modules, their responsibilities, and how they connect
• Decision log — inferred architectural decisions and patterns in use
• Dependency graph — internal modules, external deps, and entry points
• Dependency-skills — best-practice summaries for packages you select

All notes are interlinked via wikilinks and tagged with structured frontmatter.

How it works

1. Stack detection — languages, frameworks, build tools, test runners
2. Architecture scan — modules, responsibilities, and connections (fan-out by directory for speed)
3. Decision inference — patterns in use, architectural choices
4. Dependency discovery — reads package.json, presents direct dependencies
5. User selection — you pick which dependencies get full skills (recommended cap: ~5)
6. Skill generation — selected packages get dependency-skills written to ~/.xavier/skills/
7. Team resolution — links to team-level convention notes via wikilinks
8. Vault commit — all notes committed per your configured git strategy

The scan uses Xavier's Shark concurrency model — directories are processed in parallel as remoras, so large codebases don't mean long waits.

Note format

Each generated note follows the Zettelkasten schema:

---
repo: my-app
team: platform
domain: auth
type: architecture
tags: [middleware, express, jwt]
related: [knowledge/repos/my-app-decisions, skills/jsonwebtoken]
created: 2026-04-08
updated: 2026-04-08
---

When to run it

• Joining a new codebase — get oriented fast
• After major refactors — update the architecture map
• Starting a new project — establish baseline knowledge

You can re-run /xavier learn on the same repo. Xavier updates existing notes rather than creating duplicates.

What it doesn't do

• It doesn't modify your code
• It doesn't install anything in your repo
• It only writes to your Xavier vault (~/.xavier/knowledge/repos/)

Ecosystem support

Currently supports Node.js projects. Other ecosystems are planned for future versions.