← חזרה לכל השלבים

Orion Studio — Specification (P5, stage: SPEC)

Owner: specification agent. Autonomous stage (P6 — not a creative gate). Upstream:

vision/vision.md, brand/brand.md. Downstream: ARCHITECTURE. Executable (P3): if the

implementation differs from this spec, the implementation is wrong. Scope: v1 only

(Observe tier-1 + Terminal). Every requirement here is testable; acceptance criteria are

measurable; there are zero TBDs.

0 · Scope statement

In (v1): read-only Observe of Orion (runtime) + PRISM (factory) in one cockpit, plus an

embedded VPS terminal, secured by defense-in-depth, reading only existing stores.

Out (v1, trigger-gated fast-follows): approve/reject gates (Review, tier 2), replay

(tier 3), submit PrismTask (Create, tier 4). Out (forever): any file-editing IDE surface

— the terminal is the escape hatch (Vision Lock 1).

1 · Actors & trust

• Operator = Ben (v1). Single identity; auth seams left for future operators (Vision).
• Trust law: the Studio is a read lens + terminal. It never computes status and

never writes to Orion's stores in v1. Truth = Orion's DB + Directus, surfaced verbatim.

2 · Functional requirements

FR-1 — Observe Orion: runs list

• FR-1.1 Display all runs from Orion (tasks / agent_runs) with: run id (trace_id),

project, status, started-at, duration, total cost, total tokens.

• FR-1.2 Live runs (status=running) sort first and carry the amber live signal (breathe).
• FR-1.3 List refreshes on an interval (default 3s, configurable) or via push if the

Observe API exposes a stream; no manual reload required.

• FR-1.4 Empty/zero-runs and Observe-API-unreachable states render explicit, calm messages

(not blank, not spinner-forever): no runs yet / orion observe API unreachable.

FR-2 — Observe Orion: trace detail (waterfall)

• FR-2.1 Selecting a run opens its trace as a waterfall of steps from shadow_logs

(trace_id/parent_trace_id hierarchy), each step a tool-call card: agent/step name, status,

duration, cost, token delta, and expandable metadata (JSONB payload).

• FR-2.2 Klaus pipeline steps render with their step name and index (e.g. klaus.repair · 4/6).
• FR-2.3 Failed steps carry the --ember mark and surface the failure taxonomy

(classify_failure output: type/subtype/origin/confidence) when present.

• FR-2.4 Cost/token totals shown as rings that fill to the run's value (brand motion: tick).

FR-3 — Observe PRISM: factory state

• FR-3.1 List PRISM product instances with current pipeline stage

(Research→Vision→Brand→Spec→Architecture→Tasks→Implement→Review→Evaluate→Knowledge).

• FR-3.2 Show gates pending human approval (Vision/Brand/Positioning/Direction) as a

read-only "needs you" indicator. (Acting on them = tier 2, out of v1.)

• FR-3.3 Memory browser: browse memory/ (patterns / evaluations / playbooks /

decisions) read-only, rendered from the repo files.

• FR-3.4 PRISM runs submitted to Orion appear in FR-1 like any Orion run (they are

shadow_logs rows under the prism-studio project — orion-integration-map.md §5).

FR-4 — VPS terminal

• FR-4.1 Embed ttyd as a terminal panel in the workspace column (iframe/panel).
• FR-4.2 The terminal reaches the VPS over Tailscale (no public ports). ttyd runs behind

the same secured surface as the Studio.

• FR-4.3 Terminal is the only mutation path in v1 and the catch-all escape hatch; the

Studio UI itself exposes no file editor and no write to Orion's DB.

FR-5 — Data sources (read-only, no parallel store)

• FR-5.1 Orion runtime data is read exclusively via the Orion Observe API (which

wraps the same functions Sherlock uses). The Studio holds no Orion data store of its own.

(Dependency: §6.)

• FR-5.2 PRISM product docs / CRM data are read from the existing Directus instance and

the repo files. No second source of truth is created.

• FR-5.3 Any value the Studio cannot source from FR-5.1/5.2 is shown as unknown — it is

never computed or inferred locally.

FR-6 — Security (defense in depth)

• FR-6.1 Default mode = localhost (no exposure).
• FR-6.2 Remote mode = reachable only over Tailscale (zero open public ports), behind

Caddy auto-TLS.

• FR-6.3 Application auth = passkey / WebAuthn (hermes pattern) on the Studio.
• FR-6.4 The terminal additionally enforces ttyd's own auth. (Layers: Tailscale → Caddy

TLS → passkey → ttyd auth.)

• FR-6.5 No secrets in client code or repo; secrets via environment (ARCH defines mechanism).

FR-7 — Layout & brand conformance

• FR-7.1 Three-panel cockpit: `sidebar (Orion ⟂ PRISM nav) · center (instruments) ·

workspace (trace detail / terminal), per brand.md §3`.

• FR-7.2 All visual output conforms to brand.md tokens (graphite + single amber signal,

IBM Plex Sans/Mono, instrument motion gated on prefers-reduced-motion).

• FR-7.3 Mobile-responsive (reference: hermes-webui) — panels collapse to a single column;

no functionality lost on a phone-width viewport.

3 · Non-functional requirements

• NFR-1 (latency / time-to-truth): from cockpit load to first paint of all live-run states

≤ 5s on a warm Observe API, with zero terminal commands required (Vision metric).

• NFR-2 (single pane): 100% of v1 observe + terminal operations are doable without leaving

the Studio (no separate SSH / psql / browser tab).

• NFR-3 (zero-drift): every displayed Orion value equals the Observe API response for that

field; no transformation that changes meaning. Verified by a drift check (§5 AC-Trust).

• NFR-4 (calm): ≤ 1 amber accent / alert element per viewport unless an action is

genuinely required (brand-isolation; automatable check).

• NFR-5 (exposure): 0 open public ports in any mode (verified by port scan in AC).
• NFR-6 (a11y): WCAG AA contrast on all text (aa-on-brand-color); full keyboard reach;

reduced-motion honored.

• NFR-7 (resilience): every external dependency (Observe API, Directus, ttyd, Tailscale)

has an explicit calm failure state (FR-1.4 pattern); no infinite spinners, no blank panels.

4 · Data contracts (consumed, read-only)

4.1 Orion Observe API (Orion-owned — P10; PRISM consumes)

Full contract + drift-guard ask: architecture/observe-api-contract.md (grounded in the real

agent_runs/tasks/shadow_logs columns, read from orion-os source). Read-only surface:

• GET /observe/runs?status=&project=&limit= → Run[] where `Run = { trace_id, project, title,

agent_name, status, source_channel, cost_usd, started_at, completed_at }`.

• GET /observe/runs/{trace_id} → { run, steps }; Step (from shadow_logs) = `{ trace_id,

parent_trace_id, agent_name, task_type, tool_used, outcome, failure_category, error_message,

duration_seconds, cost_usd, model_used, latency_ms, tokens_in, tokens_out, retry_count,

fallback_used, metadata }, ordered by created_at, tree via parent_trace_id`.

• GET /observe/runs/stream (SSE) → live run created/updated events (FR-1.3 push path).
• GET /observe/health → liveness for FR-1.4.

All fields map 1:1 to existing Orion columns — no field is invented by PRISM. (Note: per-step

duration is duration_seconds; tokens are tokens_in+tokens_out.)

4.2 Directus (existing CRM — read-only)

• Product/doc records read via Directus REST/GraphQL with a read-only token. Collections and

field names are discovered from the live instance at ARCH time; the Studio adds no

collections and writes nothing in v1.

4.3 Repo files (read-only)

• memory/** and products/*/ rendered for the memory browser and factory state (FR-3).

5 · Acceptance criteria (measurable — EVALUATE gates on these)

• AC-Observe-1: Given ≥1 Orion run exists, the runs list shows every run with all FR-1.1

fields; a running run shows the amber live signal. (pass/fail)

• AC-Observe-2: Selecting a run renders its full step waterfall with per-step cost/tokens/

status matching the Observe API response byte-for-byte on those fields. (diff = 0)

• AC-Trust (zero-drift): An automated check fetches the Observe API directly and compares

every displayed field to the API value; 0 discrepancies. Studio holds no Orion store

(verified: no Orion-data persistence layer in the codebase). (pass/fail)

• AC-PRISM-1: Product-instances list reflects the actual pipeline stage of each product in

products//; memory browser lists every file under memory/. (pass/fail)*

• AC-Terminal-1: The terminal panel connects to the VPS over Tailscale and runs a command;

works in localhost and remote modes. (pass/fail)

• AC-Sec-1 (exposure): A port scan of the host in remote mode shows 0 open public ports;

the Studio is reachable only via the Tailscale address. (0 ports)

• AC-Sec-2 (auth): Unauthenticated access (no passkey) is rejected on every route incl. the

terminal. (401/redirect on 100% of routes)

• AC-Latency: Cockpit load → all live-run states painted ≤ 5s, 0 terminal commands. (≤5s)
• AC-Calm: Automated scan of each primary viewport finds ≤1 amber accent/alert element at

rest. (≤1)

• AC-A11y: AA contrast on all text; keyboard reaches every control; prefers-reduced-motion

disables breathe/tick. (pass/fail)

• AC-Resilience: With Observe API / Directus / ttyd each down in turn, the corresponding

panel shows its calm failure message; no spinner-forever, no blank. (pass/fail, 3 cases)

6 · Dependencies & sequencing (hard)

• D-1 (corrected 2026-06-13): First Light is already SEALED but delivered **no HTTP/Observe

API** (explicit non-goal); observability today is the Sherlock CLI over shadow_logs. The real

dependency is therefore **"Orion builds the Observe API (Observe tier) per

architecture/observe-api-contract.md"** — Orion-owned (P10), triggered by this product's

existence. Until it ships, the Observe panels run against a fixture/stub shaped to the real

Orion columns; live cutover = config flip OBSERVE_BACKEND=live (no code change — the seam).

PRISM also proposes Orion publish observe_api.v1.schema.json + a drift-guard (mirror

prism_task.v1) so the contract cannot silently rot.

• D-2: A reachable Directus instance with a read-only token (§4.2).
• D-3: Tailscale on both the operator's machine and the VPS; ttyd + Caddy

installed on the VPS (ARCH specifies versions/config).

• D-4: Brand fonts (IBM Plex Sans/Mono) self-hosted (ARCH).

7 · Open technical decisions handed to ARCHITECTURE (autonomous, document reasoning)

• Stack confirmation (brief leaning: vanilla JS no-build + small FastAPI server) and repo home

(in/beside orion-os vs standalone talking to the Observe API — Vision says both are valid;

ARCH picks v1's home with reasoning).

• Server's role: pure read-proxy to Observe API + Directus, or also static host; auth/session

mechanism for passkeys; ttyd embedding approach; fixture/stub design for D-1.

• JS-budget posture (looser for an app than a marketing site — brief), and CI gates to carry

forward (js-budget-gate, lighthouse/a11y where applicable).