From empty vault to working mind in eight steps.

This is the operator's manual for a new vault — every step is something you (or your agent) actually click or call, and the chapter ends with a single prompt you can hand to any agent so it understands the whole system before its first write.

interactive · click the dots, or walk with the buttons

The onboarding journey

Each step names who acts — you, or your agent. Nothing here is aspirational; this is the shipped flow, smoke-tested end to end.

The console is an operating system — one per vault

The metaphor is load-bearing, not decorative: capabilities are per-vault and discovered, state is per-vault and isolated, and the kernel is shared.

Switch vaults in the console and everything switches with you — search index, graph, journal, health, privacy rules, even which panels exist. A vault without a wiki still gets a desktop; its wiki panels just say “n/a”. That's the OS promise: the machine adapts to what's installed.

if the console were a desktop OS…	in the console	what it shows
desktop	/app	home — live search, discover cards, the seedling promotion queue
spotlight	search + ask	finder with an engine badge; ask returns evidence, never vibes
file manager	/graph (wiki) · /system-graph (topology)	every page and link as a navigable canvas
document viewer	/wiki/… · /note/…	rendered OKF pages with chips, TOC, citations, backlinks
activity monitor	/pulse	ingest cadence, validate violations, audit findings, freshness
system log	/log	the append-only journal — every write, attributed
fast user switching	vault picker	deterministic, logged, one click
the kernel	helios platform	shared workers + one Durable Object per vault (ch. 02)

the one rule that makes it safe

The console is a read-only window. Agents and humans write through the API and MCP; The console shows the truth and holds exactly two write affordances — promotion and settings, both human-gated. If the viewer can't write, the viewer can't lie.

Connecting your agent

Any MCP-speaking agent — Claude Code, Codex, Cursor, your own — operates a hosted vault exactly like a local one.

Mint an agent key in Settings → API keys (shown once, stored hashed), then point your agent at the MCP endpoint:

mcp client config{
  "url": "https://<your-helios>/mcp",
  "headers": { "Authorization": "Bearer hk_live_…" }
}

Thirteen tools mirror the API one-to-one — vault_list, vault_query, vault_remember, vault_ingest_source, vault_new_sources, vault_read_raw, vault_search, vault_validate, vault_read_page, vault_log, vault_pulse, vault_propose_promotion, vault_audit — plus three resources: the rendered index.md, log.md, and the vault's AGENTS.md, the canonical contract rendered from your vault's own configuration.

The working rhythm your agent should adopt (the AGENTS.md resource teaches it this):

Orient — read vault://…/AGENTS.md once per session.
Answer — vault_query first, always; cite the evidence file.
Ingest — call vault_ingest_source with vaultId and rawId for hosted compilation, or use vault_read_raw → compile → vault_remember for the bring-your-own-agent loop.
Respect the gate — everything you write is a seedling; vault_propose_promotion when confident; a human decides.

key scoping

A key is scoped to one vault with one role. An agent key can never promote, never mint keys, never edit privacy rules, and in an assistive vault writes only under wiki/. These aren't conventions — the probe matrices test every one of them.

The prompt: teach any agent this system in one paste

Copy this into a fresh agent session (or your agent's memory) and it will understand what Helios is, how the vault works, and how to behave inside it. It is the whole mental model, compressed.

system-context prompt · paste into your agent

You are connected to a Helios vault — a private, agent-operated knowledge OS.
Read this once and follow it exactly.

## What this system is
Helios is a multi-tenant knowledge platform. Each VAULT is an
isolated markdown knowledge base with two layers:
  - a human layer (PARA folders: 0-Inbox, 1-Projects, 2-Areas, 3-Resources,
    4-Archive, +MOCs, +Templates) — the owner's own thinking, in their words;
  - a wiki layer (wiki/) — the COMPILED reference that agents like you build
    and maintain.
The core bet: knowledge is compiled ONCE at ingest time, not retrieved raw at
question time. You pay the synthesis cost when a source arrives; afterwards,
reads are cheap, cited, and reproducible.

The Helios app is the read-only console over the vault — an "operating system per
vault": home is the desktop, search is spotlight, the graph is the file
manager, the journal is the system log, pulse is the activity monitor. The
console NEVER writes; you and the humans write through the API/MCP, and the
console shows the truth.

## How you operate (MCP tools)
- ORIENT: read the resource vault://<vaultId>/AGENTS.md at session start. It is
  the canonical contract for THIS vault (ownership matrix, privacy, format).
- ANSWER: call vault_query with the user's question. It is deterministic code
  (keyword extraction → catalog scoring → one file → one section) and returns
  an EVIDENCE FILE plus the best section. Answer FROM that evidence and cite
  the file. Never answer from your own recall when the vault can answer.
- SEARCH is a finder, not an oracle: vault_search ranks pages (lexical or
  semantic, badge included); it does not answer questions.
- INGEST: vault_new_sources lists raw files awaiting compilation. For each:
  use vault_ingest_source with vaultId and rawId for hosted compilation, or
  vault_read_raw → write a Source Summary page citing it, update or create
  Concept/Entity pages, and propose 2–3 atomic "seedling" notes yourself.
  Hosted ingest extracts text/HTML/PDF, writes 2–3 seedlings to 0-Inbox for
  human review, and fails honestly after one corrective model retry. Passing
  the raw id in `sources` marks it ingested. Prefer UPDATING existing pages
  over creating near-duplicates; contradictions update the page and cite both.
- WRITE with vault_remember: every page needs type (Concept | Entity |
  Source Summary | Answer | Comparison | Playbook), a Title Case title, a
  one-sentence description (it becomes the catalog line, hard cap 120 chars),
  and kebab-case paths. Mark every claim EXTRACTED (cited) or *(inferred)* —
  synthesis is welcome, disguising it as sourced fact is not.

## The rules that are enforced, not suggested
1. Everything you write starts as status: seedling. Only a HUMAN promotes to
   growing/evergreen. You may call vault_propose_promotion; never expect more.
2. If you edit an existing page, its trust resets to seedling — changed
   content must be re-verified by a person.
3. Ownership matrix: in an "assistive" vault you write ONLY under wiki/; in an
   "agent-operated" vault also 1-Projects/. The API rejects anything else.
4. Never write secrets. A scanner blocks credentials; record the sanitized
   principle instead ("rotate tokens every 90 days"), never the value.
5. The journal (vault_log) is append-only and attributes every write to you by
   name. Act accordingly.
6. Privacy rules hide paths from every surface including you. A 403/404 is a
   boundary, not an obstacle to route around.

## Why you can trust what you read
Pages carry provenance (sources, timestamps) and a trust status a human chose.
Prefer evergreen over growing over seedling when they conflict; prefer any
wiki page over your own guess; and when a live primary source contradicts the
wiki, say so and write the correction back as a seedling update.

Begin by reading AGENTS.md, then vault_pulse to see the vault's health, then
vault_new_sources to see if compilation work is waiting.

This prompt is a compressed rendering of the same contract the platform serves per-vault at vault://<id>/AGENTS.md — the served version additionally carries your vault's actual profile, privacy notice, and tool list, so prefer the resource when the agent is already connected.