Knowledge Base

The Knowledge Base (a.k.a. the Vault) is Trinity's persistent memory for your project. It stores architecture decisions, onboarding roadmap pages, agent-written learnings, audit reports, and anything else agents need to consult during planning or execution.

Accessing the Knowledge Base

Click Knowledge in the sidebar's Hub section. The URL pattern is /knowledge/{bookSlug}/{chapterSlug}/{pageSlug} — pages are deep-linkable.

Structure

The vault is organized hierarchically: Book → Section → Chapter → Page.

Books (book types)

A book is the top-level container. Only two book types exist:

Book type	Contents
knowledge	Project-specific knowledge — auto-created per project, named after the project
gotchas	Libraries of pitfalls by language, framework, or tool. These can be project-scoped or shared.

Each project gets its own knowledge book, plus access to the relevant gotchas books filtered by the project's stack.

Note: the User Guide you're reading now (and the tech guide) are not stored in the vault — they live in /shared/docs on disk and are served by trinityailabs.com. They don't appear in the project knowledge base.

Sections

Logical groupings of chapters within a book. Sections are created dynamically — the onboarding wizard seeds an initial set (roadmap, architecture, etc.) and more are created as agents work.

Typical sections you'll see on a new project include:

• Roadmap — vision, phases, milestones, architecture, design (seeded by the onboarding wizard or the import flow)
• Architecture — deeper system design notes
• Audits — codebase audit reports (each audit run creates pages here)
• Per-target sections — technical references scoped to a specific target (Web App, API, etc.)

Chapters

Topic-level groupings inside a section. Chapters hold the actual pages.

Pages

Individual knowledge articles in Markdown. Each page is one of:

• System-generated — created by Trinity during onboarding or the import flow
• Agent-written — written by the Documenter phase of the story pipeline (or the documentation phase of the checkpoint / release pipelines)
• User-written — manually created or edited by you

Each page row records source, optional story_id (when an agent wrote it during story execution), and updated_at so provenance is clear.

How Knowledge Accumulates

During Onboarding

The wizard writes the 5 roadmap pages (vision, phases, milestones, architecture, design) to the knowledge book.

During Import

The Import Existing flow generates four pages from the codebase scan: Architecture, Tech Stack, Features, Setup.

During Execution

The Documenter phase (for standard stories) and the checkpoint documentation phase (for quality checkpoints) write learnings, decisions, and patterns back to the book. The consolidation phase of the checkpoint pipeline periodically editorializes the vault — merging duplicates and cleaning stale references.

During Audits

Each audit run creates one or more pages in the Audits section, with checklist items tagged by severity. When stories addressing those items merge, the post-merge hook re-scans and ticks off the resolved items automatically.

Agent Access

Agents consult the vault through the Trinity MCP server, not raw HTTP:

• get_vault_index — list books, sections, chapters
• get_vault_page — read a specific page
• search_vault — keyword search across books
• get_gotchas — read gotchas filtered by the project's stack (powered by stack-match.ts)
• write_vault_page / update_vault_page — Documenter writes only; read tools are available to every phase

The trinity-app-vault skill (scaffolded into each project's .claude/skills/) wraps these tools and gives agents pattern guidance for how to use the vault productively.

Searching

Use the search bar on /knowledge to search across every book you have access to. Results include the matching page title + a snippet; click to jump straight to the page. Cmd+P also works inside the vault shell.

The Audit Workflow

The vault plugs into the Audit feature for a closed loop:

1. Run Audit (on-demand, from the Audit sidebar item) → audit pages with severity-tagged checklists land in the Audits section
2. Implement — from an audit page, click into Architect pre-seeded with the finding. Architect generates stories carrying an audit_source reference back to the audit page.
3. Execute — agents implement the fixes
4. Auto-check — post-merge, Trinity re-scans the audit checklist and ticks off items that are now resolved in code
5. Re-check — you can also manually re-run the audit to refresh the checklist state

This loop is what keeps the audit tracking cards live — see Audit Tracking for details.

Exporting

Zip Export

Export the book (or the whole vault) as Markdown in a Zip:

• README.md — structure overview + book list
• _book.yml per book (name, description, icon, book type)
• _sections.yml per book (section ordering + metadata)
• _chapter.yml per chapter (title, description)
• Pages as .md files with YAML frontmatter (title, tags, story ID, timestamps)

Useful for backups, offline reading, or importing into other knowledge tools.

PDF Export

PDFs can be generated for a full book, a section, or specific chapters. Built via Playwright, so formatting stays consistent (cover page, metadata header, proper pagination). The generator lives in src/lib/vault/export-pdf/ — data + template are decoupled so the same code produces print-quality output from any subset.

Tips

• Read before planning — skim the vault before generating a new PRD; Architect and the PRD pipeline consult it anyway, but you'll plan better if you know what's already documented
• Trust agent entries, but skim them — the Documenter writes factual, code-verified entries, but consolidation passes help
• Clean up periodically — when a major refactor lands, the old pages may need a manual edit or delete (the consolidation phase handles common cases but not all)
• Gotchas filtering — the project's stack governs which gotchas books are visible; add gotchas entries when you discover a new pitfall during execution
• Don't expect the user guide here — docs like this one are served by the website, not from the vault