Documentation map¶

How the ModelVault docs are organized by audience and goal. Use this when editing or reviewing pages for consistent positioning (master plan).

Audience levels¶

Level	Who	What they need
Beginner	Evaluating or first insert	Why, comparisons, quickstart, Pydantic, examples
Intermediate	Shipping an app	Python guide, FastAPI, storage modes, operations, reference APIs
Advanced	Engine / format / ops at scale	Specifications, compatibility matrix, security, CLI, debugging

Every major guide should open with outcomes (problem → solution), not implementation trivia.

By goal¶

Evaluate ModelVault (beginner)¶

Page	Level
Home	Beginner
Why ModelVault	Beginner
Comparisons	Beginner
Quickstart	Beginner
Choose your path	Beginner

Build an application (beginner → intermediate)¶

Page	Level
Pydantic	Beginner
FastAPI (`AsyncDatabase`, async routes)	Intermediate
Python guide	Intermediate
Models & collections	Intermediate
Core concepts	Beginner
Storage modes	Intermediate
Examples	Beginner

Operate in production (intermediate)¶

Page	Level
Operations runbook	Intermediate
Debugging	Advanced
CLI	Intermediate
Compatibility	Intermediate
Security	Intermediate
Types matrix	Intermediate

API reference (intermediate)¶

Page	Level
Python API	Intermediate
Rust API	Intermediate
Async policy (concurrent reads, exclusive writes)	Advanced

Engine & format (advanced)¶

Page	Level
Specifications overview	Advanced
On-disk format	Advanced
Catalog / index / record encodings	Advanced
Query planner	Advanced
Architecture	Advanced

Runnable examples (repo)¶

Example	Level	Path
Todo app	Beginner	`examples/todo_app/`
CLI notes	Beginner	`examples/cli_notes/`
FastAPI (async)	Intermediate	`examples/fastapi_app/`
Desktop data dir	Intermediate	`examples/desktop_app/`

CI: make examples-smoke (todo + CLI + desktop with isolated MODELVAULT_EXAMPLE_DATA_DIR).

Launch material¶

Asset	Path
Copy bank	launch_messaging.md
Blog post	blog/modelvault-for-application-models.md

Editorial checklist (new or updated pages)¶

Headline — outcome or question, not “SegmentType catalog”
Problem — who is stuck and why
Solution — what ModelVault provides
Code + result — runnable or verified output where possible
Links — Why ModelVault, comparisons, or quickstart for newcomers
Level — place advanced detail behind intermediate summaries

Maintainers¶

Verified stdout: make verify-doc-examples
Example CLIs: make examples-smoke
Full gate: make check-full (includes examples-smoke)