Design a Vault Humans Can Read
Create a file and schema system that stays understandable before any automation exists.
By the end
You will have a folder map, page schema, naming rules, link conventions, and change policy that both humans and agents can follow.
The filesystem is your first interface
Before building a dashboard, make the folder tree predictable. A person should know where originals, maintained knowledge, temporary capture, and system records belong. Prefer a shallow lifecycle map such as Sources, Wiki, Inbox, System, and Archive. Relationships belong in metadata and links; folders communicate broad purpose and custody.
Frontmatter is a database contract you can read
YAML frontmatter gives a Markdown page typed fields without hiding its contents. Begin with stable ID, schema version, title, type, status, source IDs, created and updated times, tags, and review date. Every field needs allowed values and an owner. If two agents interpret status differently, the field is decoration rather than a contract.
Center each page on one durable subject
An atomic page is not necessarily short; it changes as one unit. A decision page can include context, alternatives, consequences, and follow-up while remaining one decision. Atomic pages improve citation, reuse, and updates. When two ideas have different owners or change on different schedules, they usually deserve separate canonical pages.
- Put the current summary first and chronology in a history section.
- Separate observations from conclusions.
- Prefer one canonical page plus aliases over duplicate pages.
- Use nouns and explicit decisions as titles, not vague dates alone.
Links create navigation; indexes create orientation
Wikilinks let a project point to its people, decisions, tools, and evidence while backlinks reveal where a concept is used. Links alone do not tell a newcomer where to begin. Maintain a small Home page and an index that surfaces canonical pages, recent changes, unresolved links, and orphans. Search answers a query; orientation teaches the shape of the system.
Teach every agent the same operating rules
A root instruction file should explain the map, schemas, retrieval order, write boundaries, approval rules, and verification steps. Test it with a fresh agent. If the agent guesses a path, overwrites a source, or invents metadata, improve the instruction and keep that mistake as a regression case. Instructions are operating policy, not welcome text.
Working reference
Commands and patterns
[Starter repo] Recreate the minimal vault
mkdir -p vault/{Sources,Wiki,Inbox,System,Archive}Run from llm-wiki-starter. It recreates the portable lifecycle-oriented content roots without touching src or receipts.
[Starter repo] Inventory Markdown pages
find vault -type f -name '*.md' | sort
A plain file inventory quickly reveals misplaced and duplicate material.
When the happy path breaks
Failure modes
Symptom
Nobody knows whether a note belongs in Memory, Wiki, Projects, or Sources.
Likely cause
Folders were named after implementation concepts rather than lifecycle rules.
Recovery
Define each folder in one sentence with three examples and merge categories that remain ambiguous.
Symptom
Automation succeeds on recent pages and fails on older pages.
Likely cause
Frontmatter drifted without a schema version.
Recovery
Add schemaVersion, validate required fields, and migrate with a dry-run report.
Symptom
Two pages describe the same person under different names.
Likely cause
There is no stable identity or alias policy.
Recovery
Choose one canonical page, preserve alternate names as aliases, redirect links, and record the merge.
Hands-on lab
Build the vault before the agent
Create a structure a new reader can navigate without AI help.
- 01Create the five-folder minimal vault and a root README.
- 02Write System/SCHEMA.md defining source, concept, and decision pages.
- 03Create five pages with stable IDs and valid frontmatter.
- 04Add Home and Index pages that orient a new reader.
- 05Ask someone new to find a current decision, its source, and a related concept.
- 06Revise the map where that reader hesitated.
Deliverable: A navigable vault with README, schema, Home, index, and five valid pages.
Reusable artifact
Canonical page schema
A starting contract for a durable knowledge page.
--- id: wiki-<stable-id> schemaVersion: 1 title: <human-readable title> type: concept | entity | decision | playbook status: active | superseded | archived sourceIds: - source-<id> tags: - <controlled-tag> createdAt: <ISO-8601 UTC> updatedAt: <ISO-8601 UTC> reviewAfter: <ISO-8601 UTC or null> --- # Title ## Current summary ## Evidence ## Relationships ## Change history
Before you move on
Receipt checklist
- Folder tree captured as text.
- Versioned schema with required fields and allowed values.
- Five pages that pass a schema check.
- Navigation test by someone who did not design the vault.
Primary sources
