How the Tropo Vault Works

Where governed work artifacts live in a Tropo vault — and how humans and agents use them together.

The Short Version

The vault is the single place in a Tropo vault where governed work artifacts live. Tasks, design specs, decisions, briefs, documents, collection references — they all go in the Vault. Each entry has a unique ID, a type, a state, and a line in a flat index. A human can read the Vault in any editor. An agent reads the same files and follows the same rules. The Vault is the chain of truth for the vault's work.

Why the Vault?

Before the Vault, governed work lived in folders — one folder for tasks, one for design specs, one for decisions. This worked until two things happened: folders grew past the point where humans could browse them, and agents needed a single index to query. The Vault replaces the folder-per-type model with a single flat store and a single index. One place to look, one place to check work in, one place to audit what exists.

The principle: rules travel with the artifact, not with its folder. Each entry carries its own governance through its type: field (which points at a capsule definition) and its status: field (which names where it sits in the type's lifecycle). Move the file, rename the folder — the governance stays with the entry because the governance is the entry.

What Goes in the Vault

Not everything in a Tropo vault lives in the Vault. The Vault is for governed work artifacts — things with a type, an owner, a lifecycle, and a reason to be audited. Everything else lives elsewhere:

| Folder | What lives there | |---|---| | vault/ | Governed work artifacts (tasks, specs, decisions, briefs, documents, collection-refs) | | collections/ | Human-organized views of vault entries. Hierarchical. Uses [[uid]] wikilinks to reference vault entries. | | agents/ | Agent identity files (charters, briefings, memory, transfers). Not governed as work. | | channels/ | Inter-agent communication. Ephemeral. Not a vault concern. | | .tropo/ | OS infrastructure — capsule definitions, playbooks, schemas, actions, templates. | | .tropo-studio/ | Vault-level configuration — registries, memory, settings. |

If you're not sure whether something belongs in the Vault, ask: does it have a type, an owner, a lifecycle, and a reason to be audited? If yes, vault. If no, probably elsewhere.

How to Use It — As a Human

You don't write to the Vault directly. You tell an agent what you want, and the agent uses the check-in protocol to create, update, or retire entries.

To create something:

"Create a task for rewriting the landing page copy."

The agent picks the right type (task), generates a unique ID, writes the entry to vault/files/<uid>.md, adds a line to vault/00-index.jsonl, and confirms back to you with the ID and where it lives.

To find something:

"What's active in the Vault right now?" "Show me all design specs." "What's blocking the release?"

The agent reads the index, filters by status or type, and reports back. In Phase 1 this is a grep-and-read operation. In Phase 2, when the brain (a local reasoning model) runs continuously, it becomes a natural-language query handled in milliseconds.

To organize what's already there:

Collections live outside the Vault in the collections/ folder. A collection is a markdown file that references vault entries by UID using [[uid]] wikilinks. You can create any hierarchy of collections that helps you find what you need — master/, projects/, releases/, whatever shape fits your work.

"Create a collection of all the tasks for the v1 launch."

The agent writes a collection file under collections/, registers it in the Vault (every collection also has a matching collection-ref entry in the Vault so it's discoverable), and you can open the collection file in your editor to see the list. Collections are the human organization layer; the Vault is the machine-first store.

To retire something:

"Archive that old task — it's been superseded." "Delete this test entry."

Archive (soft delete) keeps the file and updates its status; delete (hard delete) removes the file and cleans up incoming references. The agent uses the delete-entry action to handle the full cleanup in one operation.

How to Use It — As an Agent

Read vault/AGENTS.md before writing anything. That file is the operating manual for the Vault — it declares who can write, what belongs, the five-step check-in protocol, and how to handle cross-type references. Every write to the Vault passes through that protocol.

The five-step check-in (abbreviated — the AGENTS.md has the full version):

1. Resolve the type. Pick a capsule definition from .tropo/capsules/. The capsule tells you the required frontmatter, the state machine, and the validation checks.
2. Generate a UID — 8-character hex, unique in the Vault. Check the index first to avoid collision.
3. Write the entry file at vault/files/<uid>.md with complete frontmatter matching the capsule definition and a body that fits the type's shape.
4. Append the index row in vault/00-index.jsonl — one JSON object per line, with the schema-required fields. Atomic with the file write.
5. Verify that the file exists, the index row is valid JSON, the UID is registered once, and (if applicable) any referenced UIDs in the frontmatter resolve.

Actions in .tropo/actions/ wrap this protocol for each type (create-task, create-project, create-design-spec, create-design-brief, create-decision, create-collection, delete-entry). Prefer the action over raw protocol-following when one exists — it ensures consistency across agents.

The Capsule Types

The Phase 1 vault ships with core capsule definitions for these types. Each type has its own rules, state machine, and lifecycle:

⚠️ Capsules are authoritative. The table below summarizes for navigation. Each type's capsule definition at .tropo/capsules/<type>.capsule.md carries the binding rules, required frontmatter, and full validation checks. If this article and the capsule disagree, the capsule wins. Lifecycle table audited + aligned 2026-05-01 (v1.4.2 cycle Stream 2 task 7c2a5e9f); subsequent capsule amendments may drift this table — re-audit at each cycle close.

| Type | What it represents | Lifecycle (status: values) | |---|---|---| | task | A unit of work with an owner and a verifier | requested → accepted → active → verify → done (+ blocked, rejected, cancelled) — per task.capsule v3.0 | | project | A container for related tasks with a goal and a status | ideate → build → done (uses stage: field — see capsule for transitions) — per project.capsule v2.3 | | design-spec | A formal specification (architectural, product, operational) | specify → done (+ state: archived on supersession) — per design-spec.capsule | | design-brief | A design proposal or framework, lighter than a full spec | design → specify → done — per design-brief.capsule v3.0 | | decision | An architectural decision record (ADR) | design → done (vault principal accepts; sets accepted_by: + accepted_at: per v3.1 amendment) — per decision.capsule v3.1 | | document | General-purpose markdown content (KB articles, notes, captures, references) | draft → published → archived — per document.capsule v3.0 | | note | Lightweight observation or finding tied to a project or entity | state: active \| archived only (no status: field per v3 Decision 4) — per note.capsule v3.1 | | release | A versioned shipment record | active → archived (on revocation, supersession, or retirement; immutable body post-ship) — per release.capsule v3.1 | | build | A per-build artifact recording ship-zip SHA + file count + version stamps | draft → building → tested → locked → archived — per build.capsule v1.1 | | collection-ref | The Vault-side registration for a collection file that lives in collections/ | build → done (uses status: field per v3 amendment) — per collection-ref.capsule | | activation-log | The per-spawn record file for a sa.* commission (live IPC channel + permanent historical record) | per activation-log.capsule v1.0 — Argus Sprint 1b 2026-05-01 | | playbook | An operational protocol with declared steps, rules, outcomes, and verification | draft → active → superseded \| archived — per playbook.capsule v2.4 (test-harness subtype: see §Subtypes §Test-Harness) |

New types can be added by writing a new capsule definition to .tropo/capsules/ and registering it. Subtypes (engineering-task extending task, kb-article extending document) inherit from parents and can add rules but can never remove them.

Collections — The Human Organization Layer

If you've used a Spotify playlist or a web bookmark folder, you already have the shape: a curated list that points at things living somewhere else. The difference in Tropo is that you own the underlying entries — the Vault is the authoritative store, and a collection is just a view you curate on top of it. Remove an entry from a collection, the entry stays in the Vault. Remove an entry from the Vault, every collection that referenced it breaks visibly (no silent greyed-out lines). The Vault is the truth; collections are how you see it.

The Vault is flat and machine-first. Collections are hierarchical and human-first. Together they give you both views of the same work:

• Vault — flat, UID-named, queryable, one source of truth
• Collections — folders of .collection.md files you organize however you like, each referencing vault entries by [[uid]]

A single vault entry can appear in many collections. Adding or removing a reference from a collection does not move, copy, or modify the underlying entry. The Vault is the artifact store; collections are the views.

Open any .collection.md file in Obsidian, VS Code, or any markdown editor. The [[uid]] wikilinks are clickable in editors that support them (Obsidian resolves them directly; VS Code with markdown extensions can too). The outline view shows the collection's section headers as a navigable tree.

What Phase 2 Will Add — The Brain

Phase 1 is the governed folder and the governance files a reasoning agent reads. Phase 2 adds a local reasoning kernel — a 7-14 billion parameter model running continuously on your machine — that reads the same governance files but operates as a service. The brain doesn't replace the Vault; it accelerates it:

• Natural language queries ("what's blocking the launch?") become first-class
• Validation becomes real-time at check-in rather than periodic at boot sweep
• The categorization tax drops — the brain reads your content and suggests the right type
• Drift detection becomes continuous rather than scheduled

The key property: the same governance files run under both phases. A vault you build in Phase 1 continues to work when you add the brain in Phase 2. No migration. No rewrites. The governance contract is unchanged. The system improves with the model, not with engineering effort.

A user who only ever runs Phase 1 — a reasoning agent reading markdown files on a filesystem — has a complete, functional Tropo vault. The brain is an acceleration layer, not a dependency.

Where to Learn More

• Tropo Vault Phase 1 Specification — the full design document
• Vault Index Schema — the JSONL index format reference
• Capsule Definitions — the complete list of Phase 1 types and their rules
• Actions — the create-* and delete-entry action specs
• vault/AGENTS.md in any vault — the check-in protocol that agents read before writing

Agent Operating Protocol

This section is for agents. It contains the exact steps for operating against the Vault.

Before You Write

1. Read vault/AGENTS.md — the full check-in protocol lives there. This KB article summarizes; the AGENTS.md is authoritative.
2. Read vault/CAPSULE.md — the folder's governance metadata (owner, write scope, capability level).
3. Confirm the capsule type you need. If you are not sure, ask the user. Do not invent types.
4. Confirm the target location. For single-file types, the file goes in vault/files/<uid>.md. For collection-ref types, the collection file goes in collections/<path>/<name>.collection.md AND a companion vault entry goes in vault/files/<uid>.md with the same UID.

The Check-In Protocol

1. Resolve the capsule definition at .tropo/capsules/<type>.capsule.md. Read its required frontmatter, state machine, and validation checks. A subtype inherits from its parent — resolve the full chain before validating.
2. Generate a UID using openssl rand -hex 4. Check vault/00-index.jsonl for collisions. Regenerate if collision found.
3. Write the entry file to vault/files/<uid>.md with complete frontmatter. All required fields for the type's capsule chain must be present. Body content follows the capsule's body convention.
4. Append the index row to vault/00-index.jsonl. One JSON object per line. The row must include the schema-required fields (uid, type, status, title, description, owner, created, modified, tags, file_ext, schema_version). No pretty-printing — each record on a single line.
5. Index regeneration happens via .tropo/scripts/rebuild-vault.py — projects frontmatter from every vault/files/<uid>.md into vault/00-index.jsonl. No manual registry edit required for vault entries.
6. Verify: the file exists, the index row parses as valid JSON, any referenced UIDs in the frontmatter resolve to existing entries, and the vault steward (when it runs) does not flag the entry.
7. Report to the caller with the UID, the file path, and a one-line summary.

Using Actions Instead of Raw Protocol

When an action file exists for the type (e.g., .tropo/actions/create-task.action.md), prefer the action. Actions wrap the check-in protocol with type-specific input gathering, template application, and verification. They are the steady-state interface for creating vault entries. Raw protocol-following is the fallback for one-off cases or for types without action wrappers.

When Referencing Other Entries

Use [[uid]] wikilinks in markdown body content. In frontmatter, use structured fields like refs: [<uid>, <uid>] or depends_on: [<uid>] depending on the capsule definition. Never hardcode a file path as a reference — the UID is the stable identifier; the path is an implementation detail that can change during migration.

State Transitions

Transitions are governed by the capsule definition's state machine. The general rule: to change an entry's state, edit its frontmatter's status: field, update modified: to today, update the matching index row's status: and modified: fields atomically with the file write, and append to any lifecycle log the capsule requires (e.g., task activity log, design spec change log).

Never skip states unless the capsule definition explicitly allows it.

Retiring an Entry

Use the delete-entry action (.tropo/actions/delete-entry.action.md). Soft mode archives (preserves file, sets status: archived). Hard mode removes the file and the index row and handles incoming references per the specified policy. Do not delete entries by direct filesystem operation — the multi-touchpoint cleanup is error-prone and bypasses the steward notification.

Dual-Indexing Tolerance

Some early-vault entries may be referenced in vault/00-index.jsonl but still live at their original paths (not yet migrated into vault/files/). This is a transitional state during Phase 1.A migration. Until the migration completes, an agent looking up an entry by UID should check vault/files/<uid>.md first; if the file is not there, the index record's path: field gives the source location. The transitional case is rare in practice; new entries always live at vault/files/<uid>.md.

Tropo Vault KB Article | How the Tropo Vault Works Author: Metis G39 | April 11, 2026 | Part of the Tropo Vault Phase 1 Build (project 40b8794a), Phase 1.G (task 1c8a0b9e) "The Vault is the chain of truth. The collections are the views. The brain is the librarian. The primitives are markdown."