# Four surfaces: the architecture of Eve inside the Presentation Center

Written by **EI.0.02**. The five decisions of §0.0 of
`EVE-V1-REDESIGN-TODOS.md`, what each one rejected, what the rejected road would
have cost — measured, not estimated — and, for each decision, **the file that
changes if it is reversed**.

Measured on 2026-09-19 at `cee74e22d75`. The facts the decisions rest on are
re-checked in `eve-integration-code-survey-2026-09-18.md`, which also records
the one claim that turned out to be false.

Decision 6 was added by **EI.8.00** later the same day, measured at
`c119736ec3a`, after the backlog audit found that decision 4 had been written
for one machine and the deployed stack is another.

Decision 7 was added by **EI.0.11**, measured at `062dd705114`, after EI.0.03
found that two of the four threat-model rows it was asked for could not be
written truthfully — one because the surface belongs to another application, and
one because the code it would describe does not exist yet.

Abbreviations: `PC` = `docs/presentations/presentation-center`, `AD` =
`apps/oshun/admin/src`, `B` = `apps/oshun/bff/src`, `BA` = `B/assistant`.

---

## The seven decisions

### 1. The admin console hosts the center

The center stays a generated static site; the **admin origin** serves its
published files read-only and shows them in a frame.

**Rejected: the BFF hosts it.** §12.3 of `TODOS.md` recommended the BFF because
"a same-origin page needs no cross-origin session plumbing". The BFF has no
session of its own to be same-origin with, and the admin origin already has the
operator cookie, the assistant proxy routes (`AD/app/api/assistant/**` through
`AD/lib/admin-bff-proxy.ts`) and the gate (`AD/middleware.ts`, which lets
through only `/unauthorized`, `/handoff`, `/_next`, `/api`, `/icons`, `/images`
and `/favicon`).

**Measured cost of the rejected road:**

| What it would need   | Measured                                                                                                                                                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A static-file plugin | `@fastify/static` **is not in the pnpm catalog**. The catalog holds exactly two `@fastify/*` entries — `@fastify/cors` and `@fastify/multipart` (`pnpm-workspace.yaml:150-151`) — so this is a new catalog entry plus a new BFF dependency                                                         |
| A cookie session     | The BFF sets no cookie anywhere. It _reads_ one (see the survey's Correction 1) but mints none, so a session means a new plugin or a hand-rolled store                                                                                                                                             |
| A CSRF regime        | The only one on the BFF is the double-submit pair in `B/routes/domain-stubs.ts` — `oshun-csrf` + `x-csrf-token`, 32 random bytes, an 8-hour cookie, its own `parseCookies`, an origin guard and a non-browser exemption: **19 CSRF references** in that one file                                   |
| Threat-model rows    | A browser session on the BFF is a new boundary, so a new plane. The model holds **12 planes, 11 classes and 75 cells**; `workbench-intent` alone carries **7 capability claims and 10 cells**. Each cell needs a disposition and named controls, and `threat-model.spec.ts` refuses an unowned one |

**Reverse it by changing:** `AD/app/…` (the wrapper route that frames the
center) and `AD/lib/presentation-center-files.ts` — the resolver EI.1.01 adds. A
reversal moves both to `B/routes/` and adds the four rows above.

### 2. Eve is the existing admin chat, not a bundled island

The wrapper page sits inside `AdminShell`, so the dock already mounted there is
the dock. The static pages gain a **message contract**, not a script tag; read
from `file://` they behave exactly as before.

**Rejected: a standalone esbuild island of the admin chat.** It is not
impossible — `tools/presentations/tests/eve-operator-chat-capture.mjs` bundles
`AdminAssistantChat` today with `bundlePinned` (esbuild, `bundle: true`,
`format: 'iife'`) and only **three mocked module boundaries**:
`next/navigation`, `next/link` and `@/lib/admin-voice`.

**Measured cost:** the island would be a **second copy of a 1,381-line
component** to keep in step with the first, plus those three substitutions
maintained as the component grows. The capture exists to photograph the chat,
not to ship it; making it a delivery path makes every future edit to
`AD/components/AdminAssistantChat.tsx` a two-place edit.

**Also rejected: the web dock.**
`apps/oshun/web/src/components/assistant/AssistantPanel.tsx` is **7,765 lines
with 53 imports**, and three of them are the member plane itself: `useAuth` from
`@/lib/auth-context` (line 140), the library store (line 148) and the profile
and preferences stores (line 174). It is the member dock; it is not a candidate.

**Reverse it by changing:** `tools/presentations/tests/pinned-bundle.mjs` would
become a build step rather than a test helper, and `PC/deck.js` / `PC/center.js`
would gain the script tag this decision keeps out of them.

### 3. The page sends identifiers; the server reads the slide

The browser is untrusted, so page context carries the guide id, the slide id and
a short visible excerpt, and Eve reads titles, notes, sources and excerpts
through a read tool over the canonical `PC/content/*.json` in the checkout.

**Rejected: the page sends the slide text.** The context path already drops what
it is not told to keep: `BA/page-context.ts` accepts exactly five fields —
`path`, `title`, `headings`, `anchors`, `selection` (`:55`, `:102`) — and
rebuilds its return object field by field, so an unlisted key cannot survive.
Sending slide bodies would mean widening that contract for the one surface that
is easiest to forge, and the model would be reading page-supplied prose as if it
were the repository's.

The identifiers are already there to send: a deck's guide id is
`meta.presentationId` in its `#deck-data` block, written by the builder at
`tools/presentations/build-eve-oshun.py:678`, and the current slide is the one
`.slide` without `hidden` (`PC/deck.js:4`, `:179`).

**Reverse it by changing:** `BA/page-context.ts` — a sixth field, and the
`coerceAssistantPageContext` contract that today refuses one.

### 4. Small edits are written directly; structural ones go to the work queue

Text, notes and takeaway edits to existing slides use the confirm-gated write
path with a draft preview first. Adding, removing or reordering slides, changing
a layout or a diagram goes through a work item.

The two enactment paths both exist already: the confirm-gated atomic write into
`OSHUN_WORKBENCH_REPO_DIR` (`B/workbench/workbench-agent-tools.ts:773`
`export_decision_adr` → `B/workbench/decision-adr-file.ts:54`), and a work item
leased by the delegated coding agent (`tools/eve-codex-agent.mjs`,
`B/routes/workbench.ts`). The draft preview exists too:
`build-eve-oshun.py --draft <id>` (`:717`) renders `PC/drafts/<id>.json` into
`PC/.qa-draft-<id>/` (`:651`) with every validator applied and without touching
the library. _Amended 2026-09-21 (EI.8.01, EI.8.02):_ that command renders a
manuscript at the library pin; a change is previewed by
`tools/presentations/eve_change.py preview`, which reads each replaced slide at
its own chapter's pin, and its draft format is `authoring/eve-change-drafts.md`.

**Rejected: everything through the work queue.** It would be safe and unusable —
a typo fix would wait for a lease. **Rejected: everything written directly.**
Nothing could then verify it: `B/workbench/artifact-verifier.ts` has exactly
four expectation kinds — `catalog-change` (`:213`), `e2e-suite-exists` (`:230`),
`doc-page-exists` (`:239`) and `nodes-exist` (`:251`) — and **none is about a
slide**, so structural work could never reach `verified`. That is why this
decision owes the verifier a `presentation-slides` kind.

**Reverse it by changing:** `B/workbench/artifact-verifier.ts` — the boundary
between the two paths is exactly the set of expectation kinds it can check.

### 5. Operators only

The center teaches engineering internals. Every route and tool in this phase
requires the `admin:` scope; the member corpus stays empty.

**Rejected: members see the center.** The member corpus is empty by decision and
by measurement: `./eve docs export --format bff-corpus --scope member` emits a
meta line and **zero chunks**, which is what makes `loadAssistantDocsSearch`
fail closed and never offer `search_docs` at all (ETB.8.10;
`BA/docs-search.ts`). `docs-search-member-audience.spec.ts` guards it against
the checked-in artifact, because the rule that once filled it admitted 317
engineering pages to members.

**Reverse it by changing:** `BA/skills/registry.ts` — the skill whose
`toolAllowlist` names these tools, and the `authScopes` on the eval deck cases
that hold its prose to measurement.

### 6. Authoring runs where the checkout is

Owner decision, 19 September 2026: proposing, previewing, applying and reverting
a change to the library is a **local-operator capability**. It works on a
machine that has the repository, the builder's Python and, for narration, the
Kokoro environment. The deployed stack has none of them, answers
`not_configured`, and the console says so. Nothing in 0.9–0.12 claims more.

Decision 4 writes into `OSHUN_WORKBENCH_REPO_DIR` and 0.9–0.10 run Python beside
the BFF. On a developer machine both exist. In the deployed stack:

- The BFF image is Node on Alpine (`docker/Dockerfile.node:28`) and adds exactly
  one package for the BFF, ffmpeg (`:136`). There is no Python in it.
- The BFF service sets neither `OSHUN_WORKBENCH_REPO_DIR` nor
  `OSHUN_PRESENTATIONS_PYTHON` (`infra/hetzner/docker-compose.yml:322-449`), its
  only volume is its run state (`:430-431`), and its memory limit is 512 MiB
  (`:334`).
- Admin mounts the published center **read-only** (`:576`), filled once per
  deploy by `infra/hetzner/scripts/deploy.sh:238` from a staging copy with
  EI.1.02's allowlist. A preview or an applied change written by the BFF is not
  a file admin can serve.

So the resolution the write path already uses is the whole mechanism:
`B/workbench/decision-adr-file.ts:54` and `BA/presentation-library.ts:92` read
`OSHUN_WORKBENCH_REPO_DIR` (or walk up to the workspace root) and throw a typed
`not_configured` when there is none, and EI.8.03's runner has no default for
`OSHUN_PRESENTATIONS_PYTHON`. Where those resolve, authoring works; where they
do not, it refuses in those words.

**What EI.8.05's preview handler reads from.** On an operator machine, the
`.qa-draft-eve-<changeId>/` directory under the same checkout, which admin
resolves from `OSHUN_PRESENTATION_CENTER_DIR` or by walking up to the workspace
root (`AD/lib/presentation-center-files.ts:82`). In the deployed stack there is
no draft to serve: no proposal can have been made, so the handler answers 404
like any unknown change, and never 503 for a preview that was claimed.

**The same fact reaches the read side, and it is cheaper to fix.** The read
loader of EI.5.01 needs the library's source too, so today a deployed Eve
answers `not_configured` to "what supports this slide's claim" as well. Reads
need no Python and no writable tree: the deploy already copies the center's
source to the host (`.github/workflows/deploy-hetzner.yml:417`), and a read-only
mount of it into the BFF is enough. That is EI.5.06. Source excerpts at a pinned
revision (EI.5.02) need `git`, and stay local.

**Rejected: a deployed authoring worker.** It is the right shape for several
operators and the wrong cost for one. Counted against the code: a second image
with Python and the builder, Chromium for the PDF step, and `kokoro`, `torch`,
`numpy`, `soundfile` and `huggingface_hub` for narration
(`tools/presentations/render-eve-oshun-narration.py:5`); a writable checkout the
worker owns, where the BFF has only a run-state volume; a publish step from that
checkout into the mount admin reads, which today only `deploy.sh` writes; a lock
that holds across processes, where EI.9.02's holds inside one; recovery after a
crash between the content write, the receipt row (EI.9.03) and the publish; and
a way for an applied change to get back into git, because EI.9.08 leaves the
commit to a person and a deployed checkout has nobody at it. The verification
supervisor refuses to start with less than 3 GiB available
(`tools/presentations/run-supervised.py:55`) on a stack budgeted at 6.5 GiB in
total (`docker-compose.yml:36`). The one operator there is already has a machine
where all of this exists.

**Reverse it by changing:** `infra/hetzner/docker-compose.yml` — a worker
service with a writable checkout volume and the two variables — and
`BA/presentation-builder-runner.ts` (EI.8.03), which would dispatch to that
worker instead of spawning a subprocess. The tools, the draft format, the
receipt and the confirm cards do not change: they talk to the runner, not to
Python.

### 7. The framed center is the admin app's surface, not a plane of Eve's model

`BA/security/threat-model.ts` is **not** widened to carry the framed
Presentation Center. What crosses from that frame INTO Eve is already modelled;
the page itself — same-origin static HTML with inline script inside the console
— is the admin app's surface, and is held by admin-app controls that already
exist.

The model is the **assistant's**, and its own contents say so. Measured
2026-09-19: every plane in it cites only `apps/oshun/bff` files — a grep for
`apps/oshun/admin` returns **zero** — and `ThreatPlane` requires each plane to
name the assistant `routes`, agent `tools` and model `legs` it owns, which
`threat-model-inventory.ts` cross-checks against what the BFF runtime actually
registers (`CoverageReport.routesClaimed` / `toolsClaimed` / `legsClaimed`). A
static-file route in another app owns none of the three.

**What already carries the parts that do reach Eve.** The slide text and source
excerpts are the `presentation-content` plane with its four cells, seam and
result label (EI.0.03). The identifiers the page posts ride in `page-context`,
which is declared untrusted and, since EI.4.03, framed on the wire; EI.4.04
drops them for anyone without admin scope.

**What holds the front-end surface, with the code that does it.** The published
files answer under a scoped policy — `script-src 'self' 'unsafe-inline'`,
`frame-src 'self'`, `frame-ancestors 'self'` and, the part worth having,
`connect-src 'none'`, so a deck that gained a `fetch` is refused by the browser
rather than by review (`AD/next.config.mjs`, `PRESENTATION_FILES_CSP`). Only an
allowlist of published paths is served at all
(`AD/lib/presentation-center-files.ts`, `PUBLISHED_FILES` / `PUBLISHED_TREES`).
Both ends of the postMessage contract check the origin and the sending window
(`PC/deck.js`, `PC/center.js`), and every message goes through a parser that
refuses rather than repairs (`SA/presentation-messages.ts`,
`parsePresentationMessage`).

**Rejected: widen the BFF model to cite admin files.** The evidence check would
pass — it reads any repository path — and everything else would stop being true.
The plane would declare no route, no tool and no model leg, so the inventory
would carry a plane it cannot verify against a runtime; `PLANE_SEAM`
(`BA/security/red-team-matrix.ts`) places every plane on the `prompt`, `tool` or
`runtime` seam of a TURN, and a static-file route sits on none of them; and the
model's opening sentence — a place where data or authority crosses a boundary of
the assistant — would stop describing its own contents. The cost is not the
edit; it is that the model stops meaning one thing.

**Deferred, not rejected: a threat model of the admin app's own.** That is the
right home, and it is a new artifact — its own classes, its own applicability
rule, its own cells and spec — for a surface already held by the four controls
above. It is named here so the next admin surface that needs one knows where it
goes, rather than being discovered again.

**Reverse it by changing:** `BA/security/threat-model.ts` (the plane and its
cells), `BA/security/red-team-matrix.ts` (`PLANE_SEAM`) and
`BA/security/trust-labels.ts` (`PLANE_RESULT_TRUST`) — or, for the deferred
answer, a new `apps/oshun/admin/src/security/threat-model.ts` with a spec of its
own. Nothing in 0.1–0.7 changes either way: no tool, route or prompt part
depends on where this surface is written down.

---

## What stays from §12 of `TODOS.md`

§12 opens with the owner's decision of 11 September 2026: the Presentation
Center and the Docs Center **stay generated static sites**, are not rewritten as
React applications and do not gain a CMS. Three properties are named there as
the ones to preserve, and this phase preserves all three:

- **Static generators.** `build-eve-oshun.py` still renders the whole library:
  69 single-file decks with `deck.css` and `deck.js` inlined (`:343-344`) and an
  `index.html` with `center.js` inlined (`:597`). Nothing in Phase 0 makes a
  deck depend on a server.
- **A deterministic `--check`.** `build-eve-oshun.py --check` (`:714`) still
  renders and compares rather than trusting the tree, and `--draft` keeps a
  preview out of the library entirely.
- **Offline reading.** Both bundles are closed IIFEs — `(() => { 'use strict';`
  at `PC/deck.js:1` and `PC/center.js:1`, with **zero** `window.<name> =`
  assignments in either — and the only cross-frame message is parent → deck
  `oshun-presentation:pause` (`PC/center.js:124` sends, `PC/deck.js:364`
  receives; `deck.js` sends none). A deck opened from `file://` behaves exactly
  as it does inside the console, because the contract it gains is a message it
  may never receive.

## The reversal table

| Decision                                 | Reverse it by changing                                                                                                       |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1. The admin console hosts the center    | `AD/lib/presentation-center-files.ts` and the `AD/app/…` wrapper route                                                       |
| 2. Eve is the existing admin chat        | `tools/presentations/tests/pinned-bundle.mjs` (test helper → build step) and `PC/deck.js` / `PC/center.js`                   |
| 3. The page sends identifiers            | `BA/page-context.ts`                                                                                                         |
| 4. Small edits direct, structural queued | `B/workbench/artifact-verifier.ts`                                                                                           |
| 5. Operators only                        | `BA/skills/registry.ts`                                                                                                      |
| 6. Authoring runs where the checkout is  | `infra/hetzner/docker-compose.yml` (a worker with a writable checkout) and `BA/presentation-builder-runner.ts`               |
| 7. The framed center is admin's surface  | `BA/security/threat-model.ts`, `BA/security/red-team-matrix.ts` and `BA/security/trust-labels.ts` — or a new admin-app model |
