_inbox/
Capture: unprocessed input awaiting classification
- written by
- /inbox, trillian, deep-thought, marvin
- read by
- /inbox, trillian, marvin
The contract
The vault, path by path
A folder structure is not a convention until something can check it. Every path here is declared, and every declaration names who may write it.
36 declared paths.
The names below are the contract's own. Several name tools that are not published — see the component pages for what can actually be obtained.
At the vault root 29
CONTEXT.md
Hand-written orientation at vault root: the frame the rest of the vault is read against — what is active, what is paused, which decisions are open, what governs the calendar. INDEX.md answers WHERE things live; CONTEXT.md answers WHAT APPLIES. Singleton (CR-036): there is one context, not one per folder
- written by
- user (manual)
- read by
- user, any session needing orientation
<folder>/.status/current.md
Generated situational view for one contact or org person: meeting cadence over months, insight counts by type with the most recent named, open items, and the last movement from CHANGELOG. Answers 'where does this relationship stand' without reading a year of files. Lives in a HIDDEN subfolder so scanning skills cannot reach it — structural isolation rather than a skip flag, because CR-033 showed skip-lists are missed when skills glob on the YYMMDD- prefix
- written by
- render_status.py (generated)
- read by
- user (read)
_inbox/_tasks.yaml
Personal working tasks — SOURCE OF TRUTH (CR-035, supersedes CR-022 in part). Standard v2 task schema plus triage_id (preserves the {id} token used by external sync). task: states what is to be done and nothing else; history, references and reasoning go in notes:
- written by
- user (manual), import from _inbox/_capture.md, a dashboard may append a captured task and mark one finished — those two fields only
- read by
- /ops, marvin, external sync (todoist-task-pipeline)
_inbox/_inbox.yaml
The inbox register: one entry per captured item, with its classification, routing and status. The markdown files in _inbox/ are the material; this is the index over them
- written by
- /inbox, a dashboard (capture and classification)
- read by
- /inbox, /analytics, a dashboard
_inbox/_capture.md
Free-form write path for tasks (CR-035). One line each; import moves them into _tasks.yaml and empties this file. Syntax: @tag or [Tag] -> context, !P0..!P3 -> priority, clock+YYMMDD -> due
- written by
- user (manual)
- read by
- import tooling
_inbox/_frame.md
Hand-written context (week anchor, frame, conventions) pasted verbatim into the generated view (CR-035), so the generator never owns prose
- written by
- user (manual)
- read by
- view generator
_inbox/<working-doc>.md
GENERATED VIEW of _inbox/_tasks.yaml (CR-035). Shows overdue, today, tomorrow, P0/P1 without a date, and the coming seven days. NEVER hand-edited; tools must not write to it. Was the system of record under CR-022 until 260907
- written by
- view generator only
- read by
- user (read), marvin
_inbox/.audio/
Raw audio captured by Trillian, paired by basename with _inbox/<id>.md
- written by
- trillian
- read by
- trillian, deep-thought, user (manual)
_inbox/.files/
File drops: input files with a vault destiny, paired by basename with _inbox/<id>.md (CR-024)
- written by
- user (manual drop), /inbox
- read by
- /inbox, downstream skills, marvin
.knowledge/wiki/
Knowledge wiki: topic articles synthesized from the insights corpus (CR-027)
- written by
- /insights synthesize
- read by
- any session answering knowledge questions (via INDEX.md), marvin (candidate)
.knowledge/INDEX.md
Master knowledge index — read FIRST when answering knowledge questions (no RAG)
- written by
- /insights synthesize
- read by
- any session, marvin (candidate)
.handoff/
Frozen handoff snapshots: one bounded subject each, self-contained, human-actioned only (CR-033)
- written by
- /handoff
- read by
- user (explicit request only), /handoff read
.transcripts/<stem>-raw.md
Raw source archive: the verbatim input behind each summary, one file per input (CR-085). A summary is a reading of what was said; this is what it was read from
- written by
- /ops, /transcript
- read by
- user (explicit request only)
.ephemeral/
Disposable working material with NO vault destiny (session scratch, snapshots, intermediates)
- written by
- any skill/session (scratch)
- read by
- the session that created it
_outbox/
Staging for outgoing material (CR-047). One folder per send event, or a loose .md for a single message. Each folder carries a _manifest.md declaring status, channel, contact and canonical source — that manifest is the contract any dispatcher reads. Those are the FIELD NAMES; the label each is written under follows the vault language (a Swedish vault writes Status, Kanal, Kontakt, Kanonisk källa) and belongs in a dispatcher's vocabulary file, not in its code
- written by
- /ops, user (manual), any tool that writes a manifest per this contract
- read by
- /outbox, a dispatching surface (see outbound_dispatch.tools), vaultpulse/trillian, the local mail client, user
_outbox/<item>/_manifest.md
The per-item contract every dispatcher reads: status, channel, contact, classification, canonical source. Declared in its own right because two different parties write it — the skill authors it, a dispatcher records only that it sent something
- written by
- /outbox and /ops (author it), a dispatching surface (status, status-note, channel and contact only; and creating one where a folder has none, per create_missing)
- read by
- /outbox, a dispatching surface, user
<venture>/.teamschats/
Chat archive from an external messaging platform (CR-047). Raw provider message objects, one JSON file per chat per day, plus a rendered .md per day and a _chat.json naming the meeting topic. A dot-folder so Obsidian ignores the raw data; the derived notes belong in the normal tree
- written by
- the chat-archive tool
- read by
- user, any tool reading the rendered .md
<venture>/.teamschats/_fetch.json
The fetch record for the archive: when it was last fetched, and whether that worked. Tells a quiet source (fetched, nothing new) from a stale one (not fetched) and a broken one (the fetch failed, often on an expired login) — three states a snapshot date alone prints identically
- written by
- the chat-archive tool
- read by
- any tool
_infrastructure/
The INTERNAL architecture: machines, topology, connectivity, who operates what from where. Named in prefix_conventions since CR-034 but never declared in its own right until CR-051
- written by
- user (manual), survey scripts (inventory snapshots)
- read by
- user, any session answering an operations question
_architecture/
The EXTERNAL architecture: the software system — which components exist, which repository holds each, what reads and writes the vault, and where each configuration lives. The counterpart to _infrastructure/, which answers the same questions about machines
- written by
- user (manual)
- read by
- user, any session answering how the parts fit together
<venture>/.githubmeta/
Repository metadata archive: issues with their state and dates, releases, commit subjects, a docs listing. One folder per repository, a manifest saying what it is, then a dated snapshot plus a rendered .md. Metadata only — never the code
- written by
- the repo metadata archiver
- read by
- user, any session asking what changed in a repository
<venture>/.githubmeta/_fetch.json
The fetch record for the archive: when it was last fetched, and whether that worked. Tells a quiet source (fetched, nothing new) from a stale one (not fetched) and a broken one (the fetch failed, often on an expired login) — three states a snapshot date alone prints identically
- written by
- the repo metadata archiver
- read by
- any tool
<venture>/.jirameta/
Issue-tracker metadata archive: issues with their status, assignee and dates, plus released versions. One folder per board, a manifest saying what it is, a dated snapshot, a rendered .md, and a status.md holding current state. Metadata only — never descriptions or comment threads
- written by
- the jira metadata archiver
- read by
- user, any session asking where a board stands
<venture>/.jirameta/_fetch.json
The fetch record for the archive: when it was last fetched, and whether that worked. Tells a quiet source (fetched, nothing new) from a stale one (not fetched) and a broken one (the fetch failed, often on an expired login) — three states a snapshot date alone prints identically
- written by
- the jira metadata archiver
- read by
- any tool
_config/
Vault-wide overrides for skill defaults (optional)
- written by
- user (manual)
- read by
- /ops, /insights, /tasks, /analytics
.analytics/
Dated snapshots of vault-level analytics. A DORMANT dot surface (CR-097): read on demand by name, never by a folder walk. Was _analytics/ before 1.83.0; readers fall back to it for one release
- written by
- /analytics
- read by
- marvin, user
_tasks.yaml
Vault-root task aggregation (legacy from v1 schema)
- written by
- /tasks
- read by
- /tasks, marvin
_INDEX-*.md
Generated registers at vault root: what runs where, and which project maps to which machine. Swept from a machine list held outside the vault, so the vault is the view and not the source
- written by
- an inventory scanner (generated)
- read by
- user, any session answering an operations question
Per folder 7
<folder>/_ops.yaml
Per-folder ops config (org config, team, language, terminology)
- written by
- user (manual), a dispatching surface may add an external_systems.chats entry, on explicit confirmation and nothing else
- read by
- /ops, /insights, /tasks, /analytics
<folder>/_tasks.yaml
Per-folder open tasks (v2 distributed)
- written by
- /tasks, /transcript, /ops
- read by
- /tasks, marvin
<folder>/_insights.yaml
Extracted decisions, learnings, patterns, evolution feedback
- written by
- /insights, /ops, /transcript, a dashboard — the promotion_review block only (CR-100)
- read by
- /insights, /analytics, marvin
<folder>/_meta.yaml
Folder metadata (esp. _contacts/<name>/ classification)
- written by
- user (manual), /ops
- read by
- /ops, /insights, /analytics
<folder>/_summary.yaml
Folder-level narrative summary (CR-008, generated by Ollama)
- written by
- scripts/generate_summaries.py (Marvin)
- read by
- marvin, user
<folder>/CHANGELOG.md
Per-folder changelog of structural changes
- written by
- /ops normalize, user, /ops
- read by
- user
<folder>/rolling-plan-<facilitator>-<partner>.md
Living per-axis planning doc for a recurring 1-on-1 (CR-014); registered in _ops.yaml workflows.rolling_plans
- written by
- /ops, user
- read by
- /ops, user
From ecosystem.yaml, contract 41 · core-skills 1.89.4 · read at build 2026-10-08