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.

Scoped mode

By default, /xavier learn analyzes from the git root. You can pass an optional [path] argument to scope the scan to a single subdirectory. This is useful in large monorepos where you only care about one package.

/xavier learn [path]

Output location

When scoped, notes go to ~/.xavier/knowledge/repos/<monorepo-name>/<app-name>/ — one folder per package, nested under the monorepo name. <app-name> is derived from the package manifest's name field (stripping @org/ prefix, kebab-case), falling back to the leaf directory name if no manifest exists.

When no path is provided, behavior is unchanged: notes go to ~/.xavier/knowledge/repos/<repo-name>/.

Root-peek

Scoped remoras may read root-level shared config (tsconfig, eslint, root package.json) for inherited context, but they do not explore sibling packages outside the scope. This keeps architecture notes grounded when packages depend on shared tooling.

Skipped steps

When scoped, two steps of the default flow are skipped because you've already made the decision:

• Monorepo detection (no need — you already scoped)
• Per-workspace agent spawning (no need — you already picked the workspace)

Invalid path

If the path doesn't exist, Xavier errors with Directory `<path>` not found relative to repo root `<root>`. and stops. No fuzzy matching, no guessing.

Example

/xavier learn apps/checkout

Xavier scans apps/checkout/, derives the app name from its package.json, and writes ~/.xavier/knowledge/repos/<monorepo>/checkout/architecture.md (plus decisions.md and dependencies.md).

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.