What we built, and how it thinks.
Helios turns a proven single-machine system — an agent-operated markdown knowledge OS — into a multi-tenant SaaS on Cloudflare without losing the properties that made it work: knowledge is compiled once, retrieval is deterministic code, trust is human-gated, and the viewer never writes.
The deterministic query engine
This is not a mock — it is the same scoring logic that runs inside every VaultDO, ported line-for-line. Ask a question; watch it never call a model.
1 · keyword extraction
2 · candidate scoring — no file opened yet
| page | line | name | dir | Σ |
|---|
+3 per keyword present in an index line · +2 in the filename · +1 per directory segment. Presence-based; ties break by path.
3 · open ONE file, return ONE section
The calling agent answers from this evidence, citing it. Reproducible, debuggable, ~0 cost — the model never free-associates over the corpus.
What shipped
Six original phases, each implemented by a coding agent against frozen tests, judged independently, committed with attribution — then extended by the hosted-ingest and editorial remediations recorded below.
The product is Flux, hosted: every vault gets a full operating-system view in the Flux idiom — the wiki home with its hero search, the knowledge and system graphs, the connected stack, the operational pulse, journal, and health — and LLM agents are the primary writers while humans review and promote. Eight Cloudflare Workers present one seamless application:
| path | worker | owns |
|---|---|---|
| / | helios-www | Astro 7 static paper-terminal marketing |
| /docs | helios-docs | Astro 7 + Starlight + Pagefind product documentation |
| /blog | helios-blog | Astro 7 field notes — three posts + RSS |
| /app | helios-app | Hono SSR console — auth, vault picker, every read surface |
| /api | helios-api | write plane + read JSON; exports VaultDO & OrgDO |
| /mcp | helios-mcp | MCP server — your agent's front door |
| — | helios-ingest | queue consumer + workflows (embeddings, hosted ingest) |
| * | helios-router | the VMFE router that stitches all of the above |
The build ledger
- P0Scaffold — monorepo, 3 shared packages, full VMFE routerrouter goldens 14/14
- P0.5OKF core — frontmatter round-trips, index lines, scorer, links, validatorfrozen contract 22/22
- P1Read path — control plane, VaultDO, /v1 API, console22-row isolation matrix
- P2Write plane — promote, keys, idempotency, MCP serveragent→MCP→log attribution e2e
- P3Multi-vault — grants, share links, real deletionzero-residue teardown
- P4Semantic — contextual-RAG pipeline, alarms, audit, exporthonest fallback + namespace zero
- P5Product — billing, quotas, importers, templates, www/docsstranger path unassisted
- R1Hosted ingest — Workers AI content channels, code-built trust structure, unpdf, inbox seedlingscorrect once, then fail honestly
- R2Editorial verticals — Astro 7 www/docs/blog, shared tokens, self-hosted Newsreader + GeistCSP + base-path assets live
- R3One-command dev — five supervised process groups, registry wiring, builds and health gatesone command · one Ctrl-C
- R4Production auth + lifecycle — OAuth, verification, Turnstile, reminder/expiration workflows, Polar webhooks, org rate limiter with first-party SSR exemptionfrozen reward tests
- R5Reference reskin + offline dev — auth-aware public chrome, Topology/Wiki graph workspaces with view-state persistence, qmd semantic bridge, tunnel-free dev configsfull UI drive · 211 tests
- R6Production cutover + transport hardening — usehelios.co custom domains with www→apex, deploy-production.sh secrets preflight, router retry/branded-502/redirect re-prefixing, legal pages + robots.txt, pricing→billing plan intent, Hobby naming, consolidated shell menus269 tests · dist checks pin the canonical domain
Every phase ended with an independent re-run of typecheck + tests + build, a code review of the diff, and — from P1 on — a live runtime drive through the router. The staging deploy then caught and fixed a real ship-blocker the local gates had missed (see the org-bootstrap incident).
The brain: compile once, read forever
The core bet, inherited from the local reference system: pay the synthesis cost at ingest time, so reads become cheap, cited, and trustworthy.
Instead of per-query RAG,
an agent compiles each raw source into the wiki once: a cited Source Summary, updated
Concept/Entity pages, and two or three seedling notes proposed for review. Every compiled claim is
marked EXTRACTED (cited) or *(inferred)* — synthesis is allowed but never
disguised as sourced fact.
Hosted ingest now runs that discipline for real. The Workers AI compile port asks the model only for
schema-constrained content channels; code constructs directories, EXTRACTED bullets,
citations, and *(inferred)* marks. Invalid output gets one corrective retry and then an
honest failure — never a silent heuristic. Text, HTML, and PDFs (through unpdf) produce a
Source Summary, concept/entity updates, and two or three seedlings in 0-Inbox/, written as
the narrowly scoped agent:helios-ingest principal. The human promotion gate does not move.
One transaction, zero drift
The reference system kept a hand-maintained catalog (index.md) and journal
(log.md) atomically consistent with pages via careful shell scripting. Hosted, the
guarantee became structural: a Durable Object is single-threaded, so
remember() is one transactionSync —
Retrieval is code, not vibes
The engine above is the entire hot path: extract keywords, score the
catalog (never the corpus), open exactly one page, return exactly one section, follow a
pointer link at most once. The response names its evidenceFile — the agent answering you
must cite it. Search elsewhere in the product is honestly positioned as a finder; the
ask affordance runs this evidence path.
Deterministic retrieval is reproducible and debuggable, costs ~nothing, and biases answers toward the curated, human-promoted layer. Interactive search is semantic-first: every query runs the semantic engine and falls back to lexical only when that pipeline cannot answer honestly — and the fallback is announced, never silent. The deterministic evidence path stays model-free.
Trust is a lifecycle, and humans hold the gate
Agents write freely; nothing they write is trusted until a person promotes it. This is the product's defense against confident nonsense compounding.
Every agent-written page enters as seedling and can only move to growing and evergreen by a human action. The gate is enforced twice — in the API route and inside the VaultDO — so no future refactor can accidentally hand it to a machine:
apps/api/src/routes/api.tsif (access.principal.type !== 'human')
return jsonError(403, 'human_gate', 'Only a human principal may promote pages.');
- Agents may propose promotion (
promotion_requestedflag) — the console surfaces the queue on the home screen. - An agent editing an existing page forces its status back to seedling — changed content means trust must be re-granted.
- A trusted page citing a seedling without an
(unverified)marker is avalidate()violation, visible on the pulse dashboard. - Every write is attributed: the append-only journal records which agent (by key) or which human (by session) did what. Verified live over MCP: the agent's remember and the human's promote carry different principals in the same log.
Proof, and what we won't claim
The reference system's testing culture — frozen-red-first, never weakened — survived the translation. So did its honesty properties.
Frozen-red-first: the reward tests were written and committed failing, before implementation, by a different mind than the one writing the code. The probe matrices are data files — every row names a principal, a route, and an expected status; positive-control rows make vacuous passes impossible (a lesson learned live, when a broken wildcard route made a traversal check pass for the wrong reason).
Verified on real infrastructure: real bge-m3 vectors in a real Vectorize index; a cross-namespace probe returning zero (with its positive control returning the vector — platform isolation, not just library discipline); the MCP loop driven end-to-end against staging.
Real Polar checkout/webhooks (staging runs fake billing) · the MCP gate was driven via raw
JSON-RPC, not a live editor session · the first production deploy has not run —
custom-domain routes are checked in and deploy-production.sh preflights the
secrets, but Email Routing, the production Polar webhook, live OAuth/Turnstile, and the
get-session 500 remain to be verified on usehelios.co.
The honesty properties are user-facing features: search is semantic-first and the results panel carries an engine indicator — “ENGINE · SEMANTIC” on the primary path, a loud “ENGINE · LEXICAL FALLBACK” when the semantic pipeline could not answer, wiki-less vaults degrade to “n/a” panels instead of errors, and export produces a byte-faithful tar of your markdown — leaving is always possible, which is exactly why staying is trustworthy.