Read this entire file before doing anything. This is the architectural manual for the
Meridian project management and knowledge system. If you understand this file, you can
operate the system, modify it, and teach others how to use it.
Meridian is a 3-founder company building sovereign personal AI infrastructure.
| Founder | Role | Focus |
|---|---|---|
| **Q** | Lead architect, system builder | Architecture, PM, deployment, knowledge bank |
| **Will** | Technical co-founder | Schema design, scoring systems, build principles |
| **Rob** | Technical co-founder | Dream Engine, error handling, swarm architecture |
Your identity is set in .meridian.json → "author" field. Every change you make
is attributed to that name. Check it before starting work.
BACKEND (what AI reads) FRONTEND (what humans see) ───────────────────── ──────────────────────── YAML files in objects/ → Static HTML site (founder.mrd.works) Structured, queryable → Visual, navigable Source of truth → Generated output
YAML is the source of truth. The HTML site is a rendering. Never edit HTML directly.
All mutations go through meridian_core.py or the CLI. When you run python render_site.py,
it reads all YAML objects and regenerates every HTML page from scratch.
Everything in the system is a typed YAML object with relationships to other objects.
| Type | Prefix | What it is | Example |
|---|---|---|---|
| **vision** | vision_ | North star documents | Whitepaper, Manifesto, Constitution |
| **spec** | spec_ | Technical specification | Node schema, gravity scoring, embeddings |
| **dec** | dec_ | Decision with rationale | "Gravity replaces confidence" |
| **question** | question_ | Open question, assigned | "Decay function: time or usage?" |
| **task** | task_ | Work item | "Define base schema" |
| **call** | call_ | Meeting record | "Founders call Apr 4" |
| **blocker** | blocker_ | Blocks progress | "Schema alignment needed" |
| **milestone** | milestone_ | Weekly goal | "Ship PM system + align on schema" |
| **thread** | thread_ | Async discussion | Discussion on gravity weights |
| **session** | session_ | Work session | Build session log |
Objects reference each other by ID string: related: [spec_001], blocked_by: [blocker_001].
The context loader resolves these into a full graph.
MILESTONE: "Ship PM + schema" ├── TASK: "Build PM system" (Q) ├── TASK: "Define base schema" (Will) │ ├── SPEC: spec_001 (Unified Node Schema) │ │ ├── VISION REF: whitepaper section 05 │ │ ├── VISION REF: whitepaper section 15 │ │ ├── DECISION: dec_003 (gravity > confidence) │ │ └── QUESTION: question_002 (decay function?) │ └── BLOCKER: blocker_001 (alignment needed) └── CALL: call_001 (where these tasks were assigned)
When you load context for any object, the system traverses these connections
and shows you the full picture: what it references, what references it,
related questions, blockers, and recent activity.
| What you need | Where to find it |
|---|---|
| The product vision | `objects/vision/vision_001.yaml` — full whitepaper, structured by section |
| The manifesto | `objects/vision/vision_002.yaml` |
| The founding constitution | `objects/vision/vision_003.yaml` |
| Any spec's full details | `objects/specs/spec_XXX.yaml` |
| What was decided and why | `objects/decisions/dec_XXX.yaml` |
| What's unresolved | `meridian_cli.py status` or `objects/questions/` |
| What happened recently | `objects/activity.yaml` or `meridian_cli.py log` |
| Weekly goals | `objects/milestones/` or `meridian_cli.py week` |
| Meeting notes | `objects/calls/` |
The whitepaper (vision_001) is the most important file. It contains the full
product vision with 20 sections, each with structured content, status, and links
to the specs that implement them. Read it when you need business context for any
technical decision.
cd meridian # 1. Who am I? cat .meridian.json # 2. What needs my attention? python meridian_cli.py inbox # 3. What's the project state? python meridian_cli.py status # 4. What are this week's goals? python meridian_cli.py week # 5. Context for whatever I'm about to work on python meridian_cli.py context spec_001
Then ask the user: "Here's the current state. What do you want to work on?"
python meridian_cli.py task "Title" --assigned Q --priority P0 python meridian_cli.py task "Title" --assigned Will --priority P1 --related spec_001 python meridian_cli.py decide "Title" --proposed Q --agreed Q,Will --rationale "Why" python meridian_cli.py question "Title" --assigned Will --related spec_001 python meridian_cli.py blocker "Title" --blocks task_001,task_002 python meridian_cli.py spec "Title" --summary "What it defines" --owner Will python meridian_cli.py milestone "Title" --owners Q,Will --tasks task_001,task_002
from meridian_core import load, save
spec = load("spec_001")
spec["definition"]["new_field"] = "value"
save(spec, author="Will", summary="Added new_field to definition")
Every save() call automatically:
# From a file python meridian_cli.py capture "Call title" --file notes.txt # Inline (paste, then Ctrl+Z Enter to finish) python meridian_cli.py capture "Call title"
The system extracts lines prefixed with TODO:, DECISION:, QUESTION: and
creates the corresponding objects. For richer extraction, manually create the
objects after the call.
python meridian_cli.py summarize call_001 --text "Summary of what was discussed"
python meridian_cli.py resolve blocker_001 --resolution "Aligned on call" python meridian_cli.py resolve question_002 --resolution "Time-based, 90-day half-life"
python meridian_cli.py inbox # what's new/updated python meridian_cli.py inbox --as Will # check Will's perspective python meridian_cli.py read spec_001 # mark as read python meridian_cli.py read --all # clear inbox
python render_site.py
Generates a static HTML site in site/ from all YAML objects:
bash deploy.sh
This renders the site AND deploys to founder.mrd.works via Cloudflare Pages.
One command does everything: YAML → HTML → live site.
Cloudflare setup:
This account is completely separate from TOS/THUMOS infrastructure.
All three founders can deploy using the same deploy.sh.
meridian/
├── CLAUDE.md ← THIS FILE — the system manual
├── ONBOARDING.md ← give to new founders — sets up everything
├── .meridian.json ← config: author name only (gitignored)
│
├── meridian_core.py ← CORE: object CRUD, versioning, context, activity
├── meridian_cli.py ← CLI: all commands
├── render_site.py ← RENDER: generates full HTML site from YAML
├── render_activity.py ← RENDER: generates activity page
├── deploy.sh ← DEPLOY: render + push to founder.mrd.works
├── sync_repo.sh ← SYNC: syncs between main repo and standalone repo
│
├── objects/ ← SOURCE OF TRUTH
│ ├── .counters.yaml
│ ├── activity.yaml
│ ├── .readstate.yaml
│ ├── vision/ ← vision_001 (whitepaper), vision_002 (manifesto), vision_003 (constitution)
│ ├── specs/ ← spec_001 through spec_047
│ ├── decisions/
│ ├── questions/
│ ├── tasks/
│ ├── calls/
│ ├── blockers/
│ ├── milestones/
│ ├── threads/
│ └── sessions/
│
└── site/ ← GENERATED OUTPUT (HTML — deployed to founder.mrd.works)
├── index.html ← Management dashboard
├── whitepaper.html ← full whitepaper
├── activity.html ← activity log
├── manual.html ← AI Manual (this file, rendered)
├── style.css
└── specs/
├── index.html ← specs index grouped by layer
└── spec_XXX.html ← individual spec pages
All auto-generated from YAML. Never edit the HTML directly.
founder.mrd.works/ ├── index.html ← Management: milestones, tasks, blockers, questions ├── whitepaper.html ← full whitepaper with section status + linked specs ├── activity.html ← activity log ├── specs/ ← specs index grouped by layer, click into any for details └── manual.html ← AI Manual (this file, rendered as HTML)
Nav pages: Management (index.html), Whitepaper, Specs, Activity, AI Manual.
Deployed via Cloudflare Pages (isolated account: bqminlee@gmail.com).
bash deploy.sh renders + deploys in one command.
YAML is the source of truth. Never edit generated HTML. All mutations through meridian_core or CLI.
Every mutation logs automatically. `save()` appends to activity.yaml. Renders log too.
Never manually log activity — the system handles it.
IDs are sequential. `spec_001`, `task_042`. Use `generate_id()`, never hardcode.
Three founders: Q, Will, Rob. Attribution comes from `.meridian.json` author field.
Deploy renders everything. `bash deploy.sh` = render HTML + deploy to founder.mrd.works.
Run deploy after making changes so the live site reflects the current state.
Update this file when you change the system. If you add object types, commands,
or change the architecture — update this CLAUDE.md so the next AI session knows.
This file is the shared brain. If it's wrong, every AI is wrong.
If you add new object types, commands, render scripts, or change how objects connect:
`meridian_core.py` — add to TYPE_DIRS, REQUIRED_FIELDS, VALID_STATUSES
`meridian_cli.py` — add argparse subcommand + handler function
`render_site.py` — update if the new type should appear on the site
This CLAUDE.md — update the object table, file structure, and any changed behavior
The system is designed to be extended. New object types are just new YAML files in
a new subdirectory with a prefix in TYPE_DIRS. The rest (context loading, activity
logging, site rendering) works automatically for any registered type.
These are the key decisions that shaped the system. Read when you need to understand
WHY something works the way it does.
| Decision | Rationale |
|---|---|
| YAML over database | Human-readable, git-diffable, works offline, no server process |
| HTML site as view layer not source | AI works best with structured YAML files, HTML is generated output |
| Sequential IDs not UUIDs | Human-friendly at 3-person scale. `spec_001` > `a7f3b2c4-...` |
| Single activity.yaml | Append-only, simple, no database. Works at founder-team scale |
| Render scripts regenerate fully | No partial updates = no stale state. Clear + rewrite = always correct |
| Per-founder read state | Each founder has their own "last seen version" per object |
| Objects reference by ID string | Simple, grep-able. Context loader resolves at query time |
| No back-references stored | Computed by scanning all objects. Fine at <500 files |
*This file is the shared brain of the Meridian system. Keep it accurate.*
*Last updated: 2026-04-05 by Q.*