# CORE Workbench v1

CORE Workbench is the first dedicated operator/auditor UI for CORE.

It is intentionally designed as:

- a cognition observatory,
- replay debugger,
- proposal review workstation,
- deterministic eval console,
- and audit surface.

It is NOT intended to be a generic chatbot shell.

---

# Document Index

## Doctrine

- `../decisions/ADR-0160-core-workbench-v1.md`

Defines:

- product doctrine
- trust boundaries
- architecture direction
- module scope
- acceptance criteria

---

## UX Blueprint

- `core-workbench-v1-blueprint.md`

Defines:

- visual philosophy
- interaction model
- module behavior
- navigation
- replay/proposal/eval UX

---

## Implementation Plan

- `implementation-plan.md`

Defines:

- W-026 through W-031
- phase sequencing
- backend/frontend constraints
- release criteria

---

## API Contract

- `api-contract-v1.md`

Defines:

- read-only endpoint surface
- request/response envelopes
- mutation boundaries
- runtime/trace/proposal/eval/replay routes

---

## Data Shapes

- `data-shapes-v1.md`

Defines:

- typed UI-facing shapes
- proposal structures
- replay structures
- artifact references
- trust badges

---

## Proposal Artifact Substrate

- `proposal-artifact-substrate-v1.md`

Defines:

- the universal proposal artifact envelope
- subject-specific proposal adapters
- proposal-only vs ratification-enabled capability levels
- safety, validation, affected-artifact, and checksum-impact report shapes
- the migration path for math, cognition, CORE-Logos, packs, and future modalities

---

## Wave M Consolidation / B3.5

- `wave-m-consolidation-b3.5.md`

Defines:

- the route-registry unification plan
- calibration as a first-class evidence subject
- the B4 leeway-feasibility gate
- the UI/UX guide requirement
- the Phase A residue ledger before further complexity

Supporting B3.5 deliverables:

- `UI-UX-GUIDE.md` — operator/evaluator route map, evidence grammar, route
  proofs, boundaries, and absences.
- `b4-leeway-feasibility-gate.md` — B4 source-tuple audit and B4a nullable
  read model (gate CLEARED 2026-06-13; the producer now exists).
- `b4-leeway-producer-scope-2026-06-13.md` — the engine-side leeway producer
  scope: the serving-path seam, the `LicenseDecision`→`LeewayEvidence` mapping,
  and the two honest layers (STRICT / earned-`APPROXIMATE`).
- `phase-a-residue-ledger.md` — implemented/deferred/blocked residue.

---

## Mastery & Worthiness Waves (1 / R / M)

The plans that took the surface from read-only spine to "worthy of the
deterministic engine":

- `wave-1-evidence-spine.md` — the evidence-address model (URL = subject),
  Evidence Chain Rail, and RightInspector.
- `wave-R-mastery-revamp.md` — the 11 real routes, the Replay Moment, trace
  integrity, and the DAG/Demo/wrong=0 surfaces.
- `wave-M-worthiness.md` — the governing plan for the worthiness arc:
  Phase B (calibrated-learning / serving discipline), Phase C (cognition
  legibility), Phase D (guided tour + shareable evidence bundles), Phase E
  (robustness). Per-deliverable implementation notes live inline.

---

## Design System

- `design-system.md` — semantic token roles, density, primitives, and the
  motion / calm-honesty discipline.

---

## CORE-Logos Studio

- `core-logos-studio-plan.md`

Defines:

- the `/logos` Studio route concept
- pack identity, lexicon, glosses, morphology, alignment, holonomy, safety, and patch-forge tabs
- CORE-Logos evidence subjects
- read-only readers and proposal-only draft endpoint direction
- the handler-family admission sequence for future ratification

---

## UI Component Map

- `ui-component-map.md`

Defines:

- page layout
- navigation structure
- shared components
- trace drawer structure
- proposal/eval/replay modules

---

## Acceptance Gates

- `acceptance-gates.md`

Defines:

- implementation gates
- red flags
- release conditions
- mutation restrictions

---

## Visual Evidence / Handoff

- `../handoff/workbench-truncated-cell-visual-evidence-2026-06-14.md` — captured
  screenshots confirming the `TruncatedCell` full-content reveal (popover +
  copy + modal) across the proposal queue, the trace propagation edges, and the
  single-column selection rails.

---

# Core Principles

## Replay before persuasion

The UI should make replay evidence more important than aesthetic persuasion.

## Calm by default

The interface should remain quiet and precise.

## Progressive disclosure

The system should become more transparent the deeper an operator inspects.

## Proposal is not ratification

The UI must preserve ADR-0057 review doctrine.

## Read-only first

The first workbench phases prioritize visibility and auditability before any
mutation capability.

---

# Current Status (2026-06-14)

The Workbench is shipped and well past the W-026…W-031 planning era. The
read-only local API + React UI are real; W-026 (read-only API) through W-031
(replay theater) all landed, followed by the Wave 1 evidence spine, the Wave R
mastery revamp (11 routes + the Replay Moment), and the Wave M worthiness arc.

**Wave M is complete** — Phase B (calibrated-learning surfaces), Phase C
(cognition legibility, incl. the trace Field reader), Phase D (guided tour +
evidence bundles), and the B4 leeway producer all merged. Since then the
always-on heartbeat has added a continuous **Lived Life** surface and a
read-only **CORE-Logos** reader (identity / lexicon / glosses / morphology /
alignment / safety). Phase E (robustness; continuous) and the parallel tracks
(the CORE-Logos *Studio* mutation/patch-forge path, the universal proposal
envelope) remain.

The **Vault** evidence surface is likewise complete end to end: **P0** honest
empty/unavailable framing (every state framed as the Vault; absence vs
persisted-empty split; #760), **P1** entry-inspector depth + status/facet/text
filters + an honest evidence-rail progression (#762/#763/#764), and **P2**
read-only exact-CGA recall evidence (`GET /vault/entries/{index}/recall`; #766).
It stays a read-only evidence surface — no runtime controls, no persistence
toggle, no approximate recall.

Doctrine is unchanged: read-only first, allowlisted execution only
(`/evals/run`, ratify, `/demos/{id}/run`), every surface a real backend reader
(no theater), determinism over persuasion.

## Shipped surfaces

16 registry-driven routes (`src/app/routes.ts`), grouped by section:

| Section | Routes |
|---|---|
| Converse | **Chat** |
| Cognition | **Trace** (Pipeline / Field / Bundle / Surfaces / Grounding / Verdicts / Metadata / Raw tabs), **Contemplation** (staged learning loop) |
| Determinism | **Tour** (guided determinism narrative), **Replay** (hash-to-hash), **Demos** (Demo Theater) |
| Evidence | **Proposals** (+ HITL ratification), **Runs** (+ identity continuity), **Lived Life** (always-on heartbeat), **Vault** (honest empty/unavailable framing · inspector depth + status/facet/text filters · evidence-rail progression · exact-CGA recall), **Audit** |
| Discipline | **Evals** (wrong=0 ledger), **Calibration** (gold-tether arena, Wilson floor vs θ) |
| Substrate | **Packs**, **CORE-Logos** (read-only pack reader) |
| Settings | **Settings** (landing / density / inspector prefs) |

Cross-cutting: Evidence Address (URL = subject, `?inspect=`), Evidence Chain
Rail, command palette + registry-driven keyboard help, per-turn pipeline /
field / leeway / bundle evidence, full-content reveal for truncated table cells
(`TruncatedCell` — hover/focus popover + copy + modal), doctrine gates (hexScan,
schemaDrift, enumCoverage, route conformance, golden-file DAG layout).

---

# W-026 Local Runbook

Start the read-only local API:

```bash
core workbench api
```

Verify liveness:

```bash
curl http://127.0.0.1:8765/health
```

Inspect each W-026 endpoint family:

```bash
curl http://127.0.0.1:8765/runtime/status
curl http://127.0.0.1:8765/artifacts
curl http://127.0.0.1:8765/artifacts/evals/contemplation_quality/contract.md
curl http://127.0.0.1:8765/proposals
curl http://127.0.0.1:8765/evals
curl http://127.0.0.1:8765/evals/contemplation_quality
curl -X POST http://127.0.0.1:8765/evals/run \
  -H 'Content-Type: application/json' \
  -d '{"lane":"contemplation_quality","version":"v1","split":"public"}'
```

Bind to a different local port:

```bash
core workbench api --port 9000
```

Non-local binds require an explicit operator flag:

```bash
core workbench api --host 0.0.0.0 --allow-nonlocal-bind
```

---

# Initial Work Queue (delivered)

The original W-026…W-031 queue is complete; it is kept here as provenance.
Current work is tracked in the Wave M worthiness plan and the residue ledger.

| Work Item | Goal | Status |
|---|---|---|
| W-026 | Read-only API | done |
| W-027 | Frontend shell | done |
| W-028 | Chat + trace drawer | done |
| W-029 | Proposal queue | done |
| W-030 | Eval center | done |
| W-031 | Replay theater | done |

---

# Guiding Question

The correct operator reaction to the workbench should be:

> “Wait… I can actually inspect and replay the cognition.”

not:

> “Cool chatbot.”