docs(P00): complete pre-execution phase

---ci---
phase: 0
milestone: v0.1
status: complete
---/ci---

.ciagent/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Architecture
 
 ## Overview
-Three-tier local-first web application: Next.js frontend → FastAPI backend → custom async research engine, with all external capabilities (model, search, storage, memory, secrets) isolated behind hot-swappable adapter interfaces. The engine is a hand-rolled asyncio state machine; every run persists its resolved 12-dial configuration and full event trace for reproducibility and auditability.
+Two-milestone build (owner-directed 2026-09-27). Milestone v0.1 builds the UI/UX prototype as the production Next.js frontend with all data access behind a typed `ApiClient` interface backed by `MockApiClient` — no backend, zero throwaway work. Milestone v0.2 (gated on prototype approval) adds the FastAPI backend, the custom async research engine, and the adapter layer, then swaps `MockApiClient` for the OpenAPI-generated client. The engine is a hand-rolled asyncio state machine; every run persists its resolved 12-dial configuration and full event trace for reproducibility and auditability.
 
 ## Components
 
@@ -47,22 +47,27 @@ FastAPI routes: POST /api/runs, GET /api/methodologies, GET /api/runs/{id}, appr
 - **DependsOn:** engine, methodologies, config
 
 ### 7. Frontend (Next.js App Router, TypeScript strict)
-Screens: Ask (question + optional context), Choose (methodology cards with ETA/cost/why-recommended; dials behind "advanced"), Plan & Run (approve/edit plan, live SSE trace, pause/cancel), Reading Room v0 (rendered report, hover-a-citation → exact quoted passage, ledger panel, Markdown/JSON export).
+Screens: Ask (question + optional context), Choose (methodology cards with ETA/cost/why-recommended; dials behind "advanced"), Plan & Run (approve/edit plan, live SSE trace, pause/cancel), Reading Room v0 (rendered report, hover-a-citation → exact quoted passage, ledger panel, Markdown/JSON export), plus v2 surface mockups (project graph, task inbox) in the prototype.
 
-- **Boundaries:** consumes typed API client; no direct engine access.
-- **DependsOn:** API layer (via generated client)
+- **Boundaries:** consumes the typed `ApiClient` interface only — components never import the mock client directly. In v0.1 the interface is bound to `MockApiClient` (fixture data + scripted event replay); in v0.2 phase 3 the binding swaps to the OpenAPI-generated client with no component changes.
+- **DependsOn:** ApiClient contract (v0.1: mock; v0.2: API layer)
 
 ## Data Flow
-Ask (question + context) → Choose (methodology slug + dial overrides) → POST /api/runs → engine PLANNING (planner model via model adapter, dial bundle resolved) → AWAITING_APPROVAL (plan persisted; SSE events; user approves/edits) → SEARCHING (search adapter, routing per dials) → EXTRACTING (fetch pages → evidence store, stable passage IDs) → REFLECTING (planner model; depth loop per dials) → SYNTHESIZING (writer model; context = evidence passages only, per-claim citation markers) → VERIFYING (liveness pass, quote anchoring, confidence labels) → DONE (report + ledger + checklist persisted to storage; Reading Room renders; export).
+v0.1 (prototype): Ask (question + context) → Choose (methodology slug + dial overrides) → MockApiClient returns scripted plan → Plan & Run (scripted live trace replay, pause/cancel) → Reading Room (mock report with anchored citations, ledger, real file exports). All flows exercise the exact component paths the MVP will use.
+
+v0.2 (MVP): Ask (question + context) → Choose (methodology slug + dial overrides) → POST /api/runs → engine PLANNING (planner model via model adapter, dial bundle resolved) → AWAITING_APPROVAL (plan persisted; SSE events; user approves/edits) → SEARCHING (search adapter, routing per dials) → EXTRACTING (fetch pages → evidence store, stable passage IDs) → REFLECTING (planner model; depth loop per dials) → SYNTHESIZING (writer model; context = evidence passages only, per-claim citation markers) → VERIFYING (liveness pass, quote anchoring, confidence labels) → DONE (report + ledger + checklist persisted to storage; Reading Room renders; export).
 
 ## Build Order
+Milestone v0.1 (prototype): 1. Frontend scaffold + ApiClient/MockApiClient boundary → 2. Ask + Choose → 3. Plan & Run + Reading Room v0 → 4. v2 mockups + polish + 3-click validation → 5. review + owner approval gate + ship.
+
+Milestone v0.2 (MVP, gated on v0.1 approval):
 1. Methodology framework (dial schema + 2 seed methodologies + registry)
 2. Adapter layer (model/search/storage contracts + local implementations; fake adapters for tests)
 3. Evidence store (visited pages, passage extraction)
 4. Trust loop (liveness, anchoring, ledger)
 5. Engine (state machine, event bus, durable state, pause/resume)
 6. API layer (routes + SSE)
-7. Frontend (Ask → Choose → Plan & Run → Reading Room v0)
+7. Integration (swap MockApiClient → OpenAPI-generated client)
 8. Adversarial test suite (hallucinated-URL detection, quote-mismatch detection, pause/resume mid-depth-loop) + E2E happy path
 
-Build order is dependency-driven: trust verification requires evidence; engine requires adapters + trust; API requires engine; frontend requires API.
+Build order is dependency-driven: trust verification requires evidence; engine requires adapters + trust; API requires engine; integration requires API; frontend components carry over unchanged from v0.1.

.ciagent/CHECKPOINT.json

@@ -1,6 +1,8 @@
 {
   "phase": 0,
-  "stage": "specify",
-  "milestone": "v1.0",
-  "phase_role": "pre_execution"
+  "stage": "ship_pending",
+  "milestone": "v0.1",
+  "phase_role": "pre_execution",
+  "attempts": 0,
+  "updated_at": "2026-09-27T00:30:00Z"
 }

.ciagent/PERSONAS.md

@@ -0,0 +1,46 @@
+# Personas — Milestone v0.1 (Prototype)
+
+---
+active:
+  - name: frontend-engineer
+  - name: ci-lead-developer
+phase_specific: []
+reason: "v0.1 is a pure frontend prototype (Next.js, mock data). Only the frontend domain has work; backend/data personas activate in v0.2. Lead-developer coordinates decomposition and enforces the ApiClient boundary."
+---
+
+## Roster
+
+### frontend-engineer
+- **Domain**: frontend
+- **Active**: true
+- **Phase-specific**: false
+- **Frameworks**: next.js (App Router), react 19, typescript (strict), tailwind, vitest
+- **Constraints**: component-first; server components by default, client components only where interactivity demands; all data access through the ApiClient interface — components never import MockApiClient directly; no secrets or env keys in the frontend; typography care per vision §4
+- **Territory**: `frontend/**`
+
+### ci-lead-developer
+- **Domain**: coordination
+- **Active**: true
+- **Phase-specific**: false
+- **Frameworks**: ciagent workflows, git discipline
+- **Constraints**: enforce persona territories; ApiClient boundary review; commit discipline with ---ci--- blocks; phase-boundary file updates only (no .ciagent/ writes during task execution)
+- **Territory**: `.ciagent/**`, repo root config files
+
+### Deactivated (v0.1)
+
+#### backend-engineer
+- **Domain**: backend
+- **Active**: false
+- **Reason**: No backend in the prototype milestone; the FastAPI backend is milestone v0.2 (blocked until prototype approval)
+- **Frameworks**: fastapi, pydantic, uv (activates in v0.2)
+- **Territory**: `backend/**` (does not exist yet)
+
+#### data-engineer
+- **Domain**: data
+- **Active**: false
+- **Reason**: No database/schema work in v0.1; evidence store and citation ledger models arrive in v0.2; prototype uses typed fixtures
+- **Frameworks**: pydantic schemas (activates in v0.2)
+- **Territory**: `backend/src/researchx/evidence/**` (does not exist yet)
+
+### Custom personas
+None required for v0.1. The security-auditor persona activates in v0.2 phase 2 (trust loop: secrets handling, liveness verification). No CLI surface exists in this milestone, so no cli-engineer.

.ciagent/PLAN.md

@@ -0,0 +1,80 @@
+# PLAN — Milestone v0.1 Phase 1: Frontend Scaffold + Ask + Choose
+
+---
+phase: 1
+milestone: v0.1
+status: planned
+must_haves:
+  - "Next.js App Router scaffold with TypeScript strict, Tailwind, Vitest — typecheck/lint/test wired and green"
+  - "ApiClient interface + MockApiClient covering all 8 methodologies + scripted Deep Report run"
+  - "/ask and /choose routes rendering from mock data with zero API keys"
+personas:
+  - frontend-engineer
+requirements: [REQ-52, REQ-53, REQ-54, REQ-55, REQ-56]
+---
+
+## User-Facing Surface
+
+The visible deliverable of this phase is the first half of the prototype click-path:
+- **`/ask`** — the front door: a single question box + one optional context box, a "Research this" primary action, and nothing else competing for attention. Submitting stores question+context and routes to `/choose`.
+- **`/choose`** — the methodology chooser: all 8 locked methodology cards (Rapid Answer, Deep Report, SOTA Survey, Systematic Review, Fact-Check Dossier, Multi-Perspective Dossier, Competitive Landscape, Corpus Interrogation), each showing mock ETA, cost estimate, why-recommended, and a dial summary strip; a "Recommended" badge on Deep Report; an **Advanced dials drawer** per card (progressive disclosure) exposing the 12 dials with their defaults; "Start research" routes to `/run/[id]`.
+
+Later phases (2–3) deliver `/run/[id]` and `/library`; phase 4 is the owner approval gate. A README quickstart (`pnpm install && pnpm dev`) is part of this phase's surface so the owner can run it locally.
+
+## Happy Path
+
+End-to-end scenario, executable immediately after this phase:
+
+1. Owner runs `pnpm install && pnpm dev` (README quickstart, REQ-52)
+2. Opens `http://localhost:3000` → redirected to `/ask`
+3. Types "What are the latest advances in solid-state batteries?" into the question box; leaves context empty
+4. Clicks "Research this" → lands on `/choose`
+5. Sees 8 methodology cards; Deep Report is badged "Recommended" with ETA ~12 min, mock cost, why-recommended text
+6. Opens the Advanced drawer on any card → the 12 dials with defaults are visible (progressive disclosure, REQ-56)
+7. Clicks "Start research" on Deep Report → routes to `/run/[id]` (placeholder in this phase: "Plan & Run ships in phase 2")
+
+Three clicks from cold start to a chosen methodology with research initiated — the ≤3-click criterion (REQ-61) exercised on its first two legs.
+
+## UX Acceptance Criteria
+
+- **Ask screen**: exactly one question box + one optional context box; no other inputs; clear primary action. Question+context survive navigation to Choose (no loss on route change).
+- **Choose screen**: all 8 cards visible without scrolling failure states; each card shows ETA, cost, why-recommended, dial summary; "Recommended" badge on exactly one card; Advanced drawer opens/closes per card without layout shift (CLS-safe).
+- **Progressive disclosure**: dial details hidden by default; the surface shows only what a 3-click user needs (D-018 typography tokens applied to both screens).
+- **Trust affordance**: mock verification badges and confidence labels visible in card metadata where the methodology's dials demand them — the UI language of the trust loop appears from the first screen.
+- **Zero keys**: the app runs with no env vars, no network calls beyond static assets.
+- **Accessibility**: citation-bearing interactive elements are keyboard-reachable; focus states visible.
+- **Quality gates**: `pnpm typecheck`, `pnpm lint`, `pnpm test` all green; MockApiClient fixture data drives all rendered content.
+
+## Tasks (wave-ordered; persona: frontend-engineer unless noted)
+
+### Wave 1 — Foundation
+- **T-1.1**: Scaffold Next.js App Router app in `frontend/` (TS strict, ESLint, Tailwind v4, Vitest); package `@researchx/frontend`; scripts `dev/build/lint/typecheck/test` (REQ-52)
+- **T-1.2**: Design tokens: typography scale (size/leading/measure per vision §4), color, spacing as Tailwind theme extension (D-018)
+- **T-1.3**: Domain types: Methodology, DialValues, RunPlan, ResearchRun, TraceEvent, Citation, CitationLedger, Task — the vocabulary of the ApiClient contract (REQ-53)
+- **T-1.4**: ApiClient interface: `getMethodologies()`, `createRun()`, `getRun()`, `approvePlan()`, `getRunEvents()` (EventSource-shaped), `getReport()`, `getLedger()`, `exportReport()` (REQ-53)
+
+### Wave 2 — Mock data layer
+- **T-2.1**: MockApiClient: fixture data for all 8 methodologies (ETA/cost/why-recommended/dial defaults per ROADMAP) (REQ-53, REQ-56)
+- **T-2.2**: Scripted Deep Report run: plan → trace events → report with ~6 sources, page-anchored citations with exact quotes, verification statuses (live/stale), confidence labels (REQ-53, D-012)
+- **T-2.3**: Vitest coverage: fixtures typecheck; MockApiClient satisfies ApiClient (REQ-53)
+
+### Wave 3 — Screens
+- **T-3.1**: `/ask` — question + optional context, "Research this" → `/choose` with state carried (REQ-55)
+- **T-3.2**: `/choose` — 8 cards, Recommended badge, dial summary strips, Advanced drawer (12 dials, defaults), "Start research" (REQ-56)
+- **T-3.3**: Component tests: Ask state carry, Choose renders 8 cards from MockApiClient, drawer disclosure (REQ-55, REQ-56)
+- **T-3.4**: Root redirect → `/ask`; README quickstart section (REQ-52)
+
+### Wave 4 — Gate (persona: ci-lead-developer)
+- **T-4.1**: Boundary review: no component imports MockApiClient directly (REQ-54); typecheck/lint/test green; commit discipline verified
+
+## Verification
+
+- `pnpm typecheck && pnpm lint && pnpm test` green
+- Manual happy-path walk (above) passes its 7 steps
+- Requirement coverage: REQ-52 ✓, REQ-53 ✓, REQ-54 ✓ (boundary review), REQ-55 ✓, REQ-56 ✓
+
+## Delegation (execute workflow)
+
+Phase 1 executes via the frontend-engineer persona subagent (waves 1–3), ci-lead-developer for wave 4 boundary review. Task commits use `feat(P01-NN): …` with `---ci---` blocks carrying `phase: 1`, `milestone: v0.1`, `persona`, `task`, `requirements.covered`. Ship delegates to the ship workflow (tag v0.1.1, PR phase/01 → milestone/v0.1-prototype).
+
+**Scope guard**: this plan covers v0.1 P1 only. `/run/[id]`, `/library`, exports, v2 mockups are P2/P3 plans written at their phase boundaries (P0 of this checkpoint does not plan them in detail). No MVP (v0.2) work is planned or executed before v0.1.4 + owner approval.

.ciagent/PROJECT.md

@@ -6,14 +6,15 @@ ResearchX (working name; rename deferred — naming collision audit on file, see
 ## Core Value
 A deep-research studio where you bring your own model, storage, and memory; choose a research methodology before a single query fires; and every claim in the final report is anchored to a visited, verified, quotable source. Simple enough to run in three clicks, transparent enough to audit line by line.
 
-## Objective (MVP milestone v1.0)
-Build the 3-click happy path end-to-end: Ask → Choose (methodology cards) → Plan & Run (approved plan + live interruptible trace), with a custom async engine, a hot-swappable adapter layer, the trust loop (visited-only citations, URL liveness verification, quote anchoring, citation ledger), and the two seed methodologies (Rapid Answer, Deep Report).
+## Objective (two-milestone plan, owner-directed 2026-09-27)
+1. **Milestone v0.1 — Prototype**: UI/UX only, mock data, the production Next.js frontend with all data behind a typed `ApiClient` interface backed by `MockApiClient`. Surfaces: Ask, Choose (all 8 methodology cards), Plan & Run, Reading Room v0, v2 surface mockups (project graph, task inbox). **Ships only after owner approval — no MVP work begins until approved.**
+2. **Milestone v0.2 — MVP**: gated on prototype approval. FastAPI backend, custom async engine, adapter layer, trust loop, and integration (MockApiClient swapped for the OpenAPI-generated client).
 
 ## Requirements (validated)
 1. Five pluggable adapter slots: model (OpenAI-compatible, planner/writer split), storage (local FS), search (Tavily default, DuckDuckGo keyless fallback), memory (off — stubbed), secrets (env — OpenBao later)
 2. Hardware-aware defaults: probe backend, cap requests conservatively (8192 context default, embedding batch 8), surface overrides in UI, degrade gracefully
 3. 12-dial methodology framework (typed schema, every run persists resolved dial values for reproducibility/auditability)
-4. Methodology registry shipping Rapid Answer (depth 1/breadth 1/memo/per-claim citations) and Deep Report (depth 3/breadth 2/executive report/full verification); 8-methodology catalog locked for v1, phased rollout
+4. Methodology registry shipping Rapid Answer (depth 1/breadth 1/memo/per-claim citations) and Deep Report (depth 3/breadth 2/executive report/full verification); 8-methodology catalog locked, phased rollout
 5. Custom async engine: state machine PLANNING → AWAITING_APPROVAL → SEARCHING → EXTRACTING → REFLECTING → SYNTHESIZING → VERIFYING → DONE; durable JSON state; pause/cancel/resume; typed event bus → SSE live trace
 6. Trust loop in every methodology: visited-only constraint at generation time; URL liveness pass with live/stale/dead classification; claim-to-passage quote anchoring; citation ledger JSON per run; exportable verification checklist
 7. API surface: POST /api/runs, GET /api/methodologies, run lifecycle (approve/pause/cancel/resume), SSE events, config status; OpenAPI-generated typed frontend client
@@ -21,12 +22,14 @@ Build the 3-click happy path end-to-end: Ask → Choose (methodology cards) →
 9. Testing: fake model/search adapters enabling zero-API-key engine tests; adversarial hallucinated-URL and quote-mismatch detection tests targeting ≥99% citation liveness
 10. Tech stack: FastAPI (Python 3.12, uv, pydantic) + Next.js App Router (TypeScript strict)
 
-## Requirements (active, later phases)
+## Requirements (active, later milestones)
 - Remaining 6 methodologies: SOTA Survey, Systematic Review (PRISMA-like), Fact-Check Dossier, Multi-Perspective Dossier, Competitive Landscape, Corpus Interrogation
 - Reading Room full: project graph, global search, task inbox, confidence labels, BibTeX/PDF export
 - Memory scopes (semantic caching), S3/git storage adapters, Exa/Perplexity/Google search, OpenBao secrets, Docker packaging
 
 ## Constraints
+- Prototype must be approved before MVP work begins (owner directive)
+- Versioning starts at v0.1; MAJOR remains 0 until an owner-approved v1 release; all pre-v1 ships are MINOR/PATCH only (owner directive)
 - Not a general-purpose chatbot; not a model host; not a closed content index (v1)
 - Paywalled academic access out of scope v1 — open APIs (ArXiv/PubMed) only
 - Single-user, local-first tool — no auth/multi-tenancy in MVP
@@ -37,7 +40,7 @@ Build the 3-click happy path end-to-end: Ask → Choose (methodology cards) →
 - Paywalled academic sources; model hosting; multi-tenant/auth; native Ollama API adapter; domain registration/rename decision
 
 ## Context
-Vision finalized and locked 2026-09-26: v1 methodology composition LOCKED (8 core), product named ResearchX, OpenBao retained as architectural secrets component, criticism matrix and evidence base [E1]–[E15] on file. MVP plan approved this session: phased slices — slice 0 scaffolding, slice 1 core loop (this milestone), slices 2–4 extend catalog/adapters/infrastructure.
+Vision finalized and locked 2026-09-26: v1 methodology composition LOCKED (8 core), product named ResearchX, OpenBao retained as architectural secrets component, criticism matrix and evidence base [E1]–[E15] on file. Owner revisions 2026-09-27: (1) prototype-first — UI/UX prototype with mock data must be approved before MVP work begins; (2) version starts at v0.1, MAJOR remains 0 until MVP released; (3) the prototype is its own milestone. Milestone plan: v0.1 prototype (this milestone) → v0.2 MVP (gated).
 
 ## Key Decisions
 - Methodology-first selection is the core differentiator, not raw model quality — converts ad-hoc prompt-crafting into structured, reproducible selection
@@ -45,4 +48,8 @@ Vision finalized and locked 2026-09-26: v1 methodology composition LOCKED (8 cor
 - Progressive disclosure resolves granular-vs-simple tension — defaults on the surface, dials on demand
 - Custom async engine (hand-rolled asyncio state machine) over LangGraph — full control over pause/resume, durable state, trace streaming; framework lock-in avoided
 - NotebookLM-style source grounding kept; source-blindness removed via quality annotation
-- Model adapter default: Ollama cloud-first (ollama.com/v1) with keyless localhost:11434/v1 fallback on auth/connection failure
+- Model adapter default: Ollama cloud-first (ollama.com/v1) with keyless localhost:11434/v1 fallback on auth/connection failure
+- Prototype-first gate (owner): UI/UX prototype with mock data, approved before MVP work; prototype is its own milestone (v0.1)
+- Versioning (owner): starts at v0.1; MAJOR locked at 0 until owner-approved v1 release; MVP may span multiple 0.x minor milestones
+- Prototype = production Next.js frontend with typed ApiClient/MockApiClient split — zero throwaway work; phase 4 of v0.2 swaps the mock for the OpenAPI client
+- Tag-line mapping: 0.x milestones run patches on their own minor line (v0.1.x); supersedes the greenfield deviation noted at init

.ciagent/REQUIREMENTS.md

@@ -1,6 +1,25 @@
 # Requirements
 
-## V1 (Milestone v1.0 — Core Loop)
+## Prototype (Milestone v0.1 — UI/UX with mock data)
+
+### Scaffold & Mock Boundary
+- **REQ-52**: Next.js App Router scaffold, TypeScript strict, Tailwind, Vitest; typecheck/lint/test wired from phase 1
+- **REQ-53**: Typed `ApiClient` interface (all frontend data access behind it) + `MockApiClient` implementation with fixture data and scripted event replay; no backend, no API keys, runs standalone
+- **REQ-54**: Prototype = production frontend, zero throwaway: v0.2 phase 3 swaps `MockApiClient` for the OpenAPI-generated client with no component rewrites
+
+### Core Surfaces
+- **REQ-55**: Ask screen: one question box + one optional context box
+- **REQ-56**: Choose screen: all 8 locked methodology cards (Rapid Answer, Deep Report, SOTA Survey, Systematic Review, Fact-Check Dossier, Multi-Perspective Dossier, Competitive Landscape, Corpus Interrogation) with mock ETA, cost estimate, why-recommended; advanced dials drawer behind "advanced" (progressive disclosure)
+- **REQ-57**: Plan & Run screen: plan approval UI (sub-questions, source universe, outline), live scripted trace stream, pause/cancel controls
+- **REQ-58**: Reading Room v0: report reader with page-anchored citations (hover shows the exact quoted passage), citation ledger panel
+- **REQ-59**: Functional exports: real downloadable Markdown/JSON files generated from mock data; citations survive as real links
+
+### Vision Validation & Gate
+- **REQ-60**: v2 surface mockups: project graph and task inbox panels rendered from mock data
+- **REQ-61**: ≤3-click happy path on defaults (Ask → Choose → Run); typography care pass per vision §4
+- **REQ-62**: Owner approval gate: prototype ships only after recorded owner approval (prototype_approval escalation hook); MVP milestone v0.2 begins only after v0.1.4 is tagged
+
+## MVP (Milestone v0.2 — core loop, gated on prototype approval)
 
 ### Methodology Framework
 - **REQ-01**: Typed pydantic schema for the 12 methodology dials (source universe, search routing, query strategy, breadth, depth, quality gates, citation rigor, verification passes, synthesis style, output structure, memory scope, checkpoints), each with a safe default value
@@ -23,7 +42,7 @@
 - **REQ-14**: Plan = sub-questions + source universe + outline; run halts at AWAITING_APPROVAL until approved or edited
 - **REQ-15**: Durable run state persisted as JSON after each state transition; pause/cancel/resume works across process restarts
 - **REQ-16**: Typed event bus → SSE live trace (query fired, source visited, passage extracted); every run records a trace file
-- **REQ-17**: New user → research running in ≤3 clicks using defaults only
+- **REQ-17**: New user → research running in ≤3 clicks using defaults only (validated on the real stack in v0.2 after prototype REQ-61)
 
 ### Trust Loop
 - **REQ-18**: Generation-time visited-only constraint: writer context contains only stored evidence passages with stable IDs [E1]
@@ -34,13 +53,9 @@
 - **REQ-23**: ≥99% of citations in shipped reports pass the liveness check
 - **REQ-24**: Confidence labels: single-source vs corroborated claims
 
-### API & Frontend
+### API & Integration
 - **REQ-25**: API: POST /api/runs; GET /api/methodologies (cards with ETA, cost estimate, why-recommended); GET /api/runs/{id}; approve/pause/cancel/resume; GET /api/runs/{id}/events (SSE); GET /api/config (adapter status + probe results)
-- **REQ-26**: OpenAPI schema generates a typed frontend client
-- **REQ-27**: Ask screen: one question box + one optional context box
-- **REQ-28**: Choose screen: 3–5 ranked methodology cards with ETA/cost/why; dials behind "advanced" (progressive disclosure)
-- **REQ-29**: Plan & Run screen: approved plan display, live interruptible trace, pause/cancel controls
-- **REQ-30**: Reading Room v0: page-anchored citations (hover shows exact quoted passage), ledger panel, Markdown/JSON export with citations surviving as real links
+- **REQ-26**: OpenAPI schema generates a typed frontend client; v0.2 P3 swaps MockApiClient for it behind the unchanged ApiClient interface
 
 ### Testing & Infrastructure
 - **REQ-31**: Fake model + fake search adapters (canned planner/writer, fixture corpus) → full engine tests with zero API keys
@@ -48,7 +63,7 @@
 - **REQ-33**: Monorepo: uv-managed backend (ruff, mypy, pytest) + Next.js frontend (ESLint, strict TS, Vitest); one-command install/dev
 - **REQ-34**: Full export round-trip: report + ledger + citations survive as real links
 
-## V2 (Post-v1.0)
+## V2 (Post-MVP backlog)
 
 ### Methodology Catalog Extension
 - **REQ-35**: SOTA Survey (academic+web routing, outline-first encyclopedic synthesis)
@@ -83,20 +98,21 @@
 | Auth / multi-tenancy | Single-user local-first MVP |
 | Native Ollama API adapter | Ollama supported via OpenAI-compatible endpoint only |
 | Domain registration / product rename | Deferred by owner (vision §11) |
+| v1.0.0 release | Owner-approved release only; not created autonomously by the pipeline |
 
 ## Traceability
-| Requirement | Phase | Status |
-|---|---|---|
-| REQ-01..06, REQ-08..11 (framework, adapters) | P1 | pending |
-| REQ-31 (fake adapters) | P1 | pending |
-| REQ-07, REQ-12 (probing, warnings) | P2 | pending |
-| REQ-13..17 (engine) | P2 | pending |
-| REQ-18..24 (trust loop) | P2 | pending |
-| REQ-25 (API) | P3 | pending |
-| REQ-26 (typed client) | P3 | pending |
-| REQ-33 (monorepo tooling) | P3 | pending |
-| REQ-27..30 (frontend) | P4 | pending |
-| REQ-17 (≤3 clicks) | P4 | pending |
-| REQ-32, REQ-34 (adversarial, round-trip) | P5 | pending |
-| All REQ-01..34 (milestone gate) | P6 | pending |
-| REQ-35..51 | v2 backlog (next milestone) | pending |
+| Requirement | Milestone | Phase | Status |
+|---|---|---|---|
+| REQ-52 (scaffold) | v0.1 | P1 | pending |
+| REQ-53, REQ-54 (mock boundary) | v0.1 | P1 | pending |
+| REQ-55, REQ-56 (Ask, Choose) | v0.1 | P1 | pending |
+| REQ-57 (Plan & Run) | v0.1 | P2 | pending |
+| REQ-58, REQ-59 (Reading Room, exports) | v0.1 | P2 | pending |
+| REQ-60, REQ-61 (v2 mockups, 3-click) | v0.1 | P3 | pending |
+| REQ-62 (approval gate) | v0.1 | P4 | pending |
+| REQ-01..06, REQ-08..11, REQ-31 (framework, adapters) | v0.2 | P1 | blocked |
+| REQ-07, REQ-12, REQ-13..24 (probing, engine, trust) | v0.2 | P2 | blocked |
+| REQ-25, REQ-26, REQ-33 (API, client, tooling) | v0.2 | P3 | blocked |
+| REQ-17, REQ-32, REQ-34 (adversarial, E2E, round-trip) | v0.2 | P4 | blocked |
+| All REQ-01..34 (milestone gate) | v0.2 | P5 | blocked |
+| REQ-35..51 | v2 backlog (post-MVP milestones) | — | pending |

.ciagent/ROADMAP.md

@@ -1,58 +1,79 @@
-# Roadmap — Milestone v1.0 (MVP Core Loop)
+# Roadmap — Milestone v0.1 (Prototype) and v0.2 (MVP)
 
 ## Overview
-Milestone v1.0 delivers the ResearchX 3-click happy path: Ask → Choose methodology → Plan & Run, powered by a custom async engine, hot-swappable adapters, the trust loop, and the two seed methodologies (Rapid Answer, Deep Report). Five execution phases follow phase 0. Per branch-strategy tag rules, phase tags run on the previous minor's patch line: phase 0 ships as v0.9.0, execution phases as v0.9.1–v0.9.5, and the final phase's patch tag (v0.9.6) IS the milestone release — no separate minor tag is created. Post-v1.0 methodology catalog and infrastructure extensions (REQ-35..51) are tracked as v2 backlog.
+Two milestones, owner-directed 2026-09-27. **Milestone v0.1 — Prototype**: the UI/UX with mock data, built as the production Next.js frontend behind a typed `ApiClient`/`MockApiClient` boundary. It ships only after owner approval (prototype_approval escalation hook — the HITL gate that overrides full autonomy for this one checkpoint). **Milestone v0.2 — MVP**: the FastAPI backend, custom async engine, adapter layer, and trust loop, gated on prototype approval. Versioning: tags run on each 0.x milestone's own minor line (v0.1.x for milestone v0.1 — greenfield deviation from the "previous minor's patch line" rule, which has no previous line to run on; the convention applies unmodified from milestone v0.3 onward). MAJOR remains 0 until an owner-approved v1 release; the MVP may span multiple 0.x minors if scope requires. Feature milestone: each phase ships a patch; the final phase's patch IS the milestone release; no separate minor tag.
 
-## Phases
+## Milestone v0.1 — Prototype (feature)
 
 ### Phase 0 — Pre-Execution (in progress)
-- **Description**: Specification parsing, clarification, .ciagent/ reference files (PROJECT, ARCHITECTURE, REQUIREMENTS, ROADMAP), initial commit. Vision locked: 8-methodology catalog (composition frozen), MVP plan approved (custom async engine, FastAPI + Next.js).
+- **Description**: Specification parsing, clarification, research, planning. Bootstrap revision correcting v1.0 bookkeeping to the owner-directed two-milestone v0.1/v0.2 structure. Vision locked: 8-methodology catalog (composition frozen); prototype-first gate; v0.1 versioning.
 - **Requirements covered**: none (planning artifacts)
-- **Success criteria**: .ciagent/ files committed on phase/00-pre-execution; milestone v1.0 established in config.json and PROJECT.md; decisions logged in init commit
+- **Success criteria**: .ciagent/ files reflect the two-milestone structure; prototype requirements (REQ-52..61) defined and traceable; milestone v0.1 established in config.json and PROJECT.md; PLAN.md + PERSONAS.md committed; phases tagged v0.1.0
 - **Depends on**: —
 - **Status**: in_progress
 
-### Phase 1 — Methodology Framework + Adapter Layer
-- **Description**: Dial schema (12 dials, typed, safe defaults), methodology registry with Rapid Answer + Deep Report, adapter contracts (model/search/storage/memory/secrets) with local implementations, capability probing with conservative caps (8192 context, embedding batch 8, Ollama cloud-first + local fallback), fake model/search adapters for tests.
-- **Requirements covered**: REQ-01..06, REQ-08..11, REQ-31
-- **Success criteria**: registry resolves both methodologies from dial bundles; fake adapters drive contract tests; model probe caps requests and surfaces overrides; zero-API-key test suite green
+### Phase 1 — Frontend Scaffold + Ask + Choose
+- **Description**: Next.js App Router scaffold (TypeScript strict, Tailwind, Vitest); typed `ApiClient` interface + `MockApiClient` (fixture data, scripted event replay); Ask screen (question + optional context); Choose screen with all 8 locked methodology cards (mock ETA/cost/why-recommended, dial summary) and the advanced dials drawer (progressive disclosure).
+- **Requirements covered**: REQ-52, REQ-53, REQ-54, REQ-55, REQ-56
+- **Success criteria**: `pnpm dev` renders Ask → Choose with 8 cards from mock data; dials drawer opens/closes; typecheck + lint + tests green
 - **Depends on**: 0
 - **Status**: not_started
 
+### Phase 2 — Plan & Run + Reading Room v0
+- **Description**: Plan & Run screen (plan approval UI, scripted live trace stream, pause/cancel controls); Reading Room v0 (report reader, page-anchored citations with hover-to-quote, citation ledger panel, functional Markdown/JSON exports from mock data).
+- **Requirements covered**: REQ-57, REQ-58, REQ-59
+- **Success criteria**: scripted run replays end-to-end with live trace; hover shows exact quoted passage; exports download real files with citations as links
+- **Depends on**: 1
+- **Status**: not_started
+
+### Phase 3 — v2 Surface Mockups + Polish + 3-Click Validation
+- **Description**: Project graph and task inbox panels as visual mockups (v2 vision validation); typography care pass (reader experience per vision §4); ≤3-click happy-path validation on defaults.
+- **Requirements covered**: REQ-60, REQ-61
+- **Success criteria**: graph + inbox render from mock data; 3-click path verified; typography pass done
+- **Depends on**: 2
+- **Status**: not_started
+
+### Phase 4 — Review + Owner Approval Gate + Ship (FINAL)
+- **Description**: Review + audit, then the **owner approval gate**: prototype presented for owner review; approval recorded as a binding decision commit. Only after approval: milestone merge to main, tag v0.1.4 — the prototype release. (v0.2 P1 branches only after this tag.)
+- **Requirements covered**: milestone gate (REQ-52..61 approved)
+- **Success criteria**: owner approval recorded; v0.1.4 tagged; milestone branches deleted per ship workflow
+- **Depends on**: 3
+- **Status**: not_started
+
+## Milestone v0.2 — MVP (feature) — BLOCKED until prototype approval
+
+Phases renumbered from the original v1.0 plan (1-based within the milestone):
+
+### Phase 0 — Pre-Execution (v0.2)
+- **Description**: Milestone pre-execution re-run: PLAN.md refresh against approved prototype decisions (layout learnings, API shape implied by the ApiClient interface), research on any gaps surfaced by approval feedback.
+- **Status**: blocked (gate: v0.1.4)
+
+### Phase 1 — Methodology Framework + Adapter Layer
+- **Description**: Dial schema (12 dials, typed, safe defaults), methodology registry with Rapid Answer + Deep Report, adapter contracts (model/search/storage/memory/secrets) with local implementations, capability probing with conservative caps (8192 context, embedding batch 8, Ollama cloud-first + local fallback), fake model/search adapters.
+- **Requirements covered**: REQ-01..06, REQ-08..11, REQ-31
+- **Status**: blocked
+
 ### Phase 2 — Research Engine + Trust Loop
 - **Description**: Asyncio state machine with durable JSON state and pause/cancel/resume; plan approval gate; typed event bus → SSE; evidence store with stable passage IDs; trust loop (visited-only constraint, URL liveness pass, quote anchoring, citation ledger, verification checklist, confidence labels).
 - **Requirements covered**: REQ-07, REQ-12, REQ-13..24
-- **Success criteria**: engine completes depth-loop runs on fake adapters; run state survives process restart mid-run; hallucinated-URL and quote-mismatch adversarial tests pass; ≥99% citation liveness on fixture corpus
-- **Depends on**: 1
-- **Status**: not_started
+- **Status**: blocked
 
-### Phase 3 — API Layer + Typed Client
-- **Description**: FastAPI routes (runs, methodologies, lifecycle, SSE events, config status); OpenAPI-generated typed frontend client; ETA/cost estimation heuristics for methodology cards.
+### Phase 3 — API Layer + Integration
+- **Description**: FastAPI routes (runs, methodologies, lifecycle, SSE events, config status); OpenAPI-generated typed client; **swap MockApiClient → generated client** (the ApiClient interface absorbs any prototype-era API drift); ETA/cost heuristics for methodology cards.
 - **Requirements covered**: REQ-25, REQ-26
-- **Success criteria**: full run lifecycle drivable over HTTP; SSE trace streams live; generated client typechecks strict
-- **Depends on**: 2
-- **Status**: not_started
+- **Status**: blocked
 
-### Phase 4 — Frontend (Ask / Choose / Plan & Run / Reading Room v0)
-- **Description**: Next.js App Router screens: Ask, Choose (progressive disclosure dials), Plan & Run (live trace, pause/cancel), Reading Room v0 (page-anchored citations, ledger panel, Markdown/JSON export). ≤3-click happy path with defaults.
-- **Requirements covered**: REQ-27..30, REQ-17
-- **Success criteria**: new user reaches a running research session in ≤3 clicks on defaults; citations hover to exact quoted passages; export round-trips (REQ-34)
-- **Depends on**: 3
-- **Status**: not_started
-
-### Phase 5 — Hardening + Adversarial Suite + E2E
+### Phase 4 — Hardening + Adversarial Suite + E2E
 - **Description**: Adversarial test suite (hallucinated-URL writer, quote-anchor mismatch, pause/resume mid-depth-loop), E2E happy-path (Playwright), monorepo tooling polish (one-command install/dev, lint/typecheck/test green).
-- **Requirements covered**: REQ-32, REQ-33, REQ-34
-- **Success criteria**: adversarial suite green; E2E green; README quickstart works from clean clone
-- **Depends on**: 4
-- **Status**: not_started
+- **Requirements covered**: REQ-17, REQ-32, REQ-33, REQ-34
+- **Status**: blocked
 
-### Phase 6 — Final Review + Ship
-- **Description**: REVIEW + SHIP + AUDIT of milestone v1.0: requirements traceability verification, milestone merge to main, release. (Final phase is numeric: 6 execution phases → this is the 6th; merge/tag per branch-strategy.)
-- **Requirements covered**: milestone gate (all REQ-01..34 verified)
-- **Success criteria**: all v1 requirements complete or explicitly deferred with rationale; milestone tag created; release notes summarize milestone
-- **Depends on**: 5
-- **Status**: not_started
+### Phase 5 — Final Review + Ship (FINAL)
+- **Description**: Review + audit + milestone ship; final patch tag IS the MVP release. MAJOR stays 0 — the MVP ships as a 0.x release. v1.0.0 comes only after an owner-approved release decision.
+- **Status**: blocked
 
-## Milestone Release
-Feature milestone (contains feat phases) → next minor tag on milestone completion, per branch-strategy tag rules. v2 backlog (REQ-35..51) starts the next milestone cycle.
+## Milestone Releases
+- **v0.1.4 = approved prototype release** (feature milestone; final phase patch)
+- **v0.2.x = MVP release** (MAJOR still 0; ship only if all v0.2 phases complete)
+- If MVP scope extends: additional 0.x minor milestones (v0.3, …), each a full milestone cycle
+- **v1.0.0**: owner-approved release only — not created by the pipeline autonomously

.ciagent/config.json

@@ -2,11 +2,18 @@
   "ci_version": "0.7.0",
   "projects": [],
   "active_project": "researchx",
-  "milestone": "v1.0",
+  "milestone": "v0.1",
+  "milestone_name": "prototype",
   "milestone_type": "feature",
+  "versioning": {
+    "major_locked": true,
+    "major_lock_note": "MAJOR remains 0 until an owner-approved v1 release; the MVP may span multiple 0.x minor milestones; all pre-v1 ships are MINOR/PATCH only",
+    "tag_line": "v0.1.x",
+    "next_milestone": "v0.2-mvp (blocked until prototype approval)"
+  },
   "autonomy": {
     "level": "full",
-    "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
+    "escalation_hooks": ["deploy", "delete_data", "merge_to_main", "prototype_approval"],
     "decision_confidence_threshold": 0.6,
     "max_revision_iterations": 3,
     "clarify_budget": 10
@@ -17,6 +24,16 @@
     "owner": "coreci",
     "repo": "researchx"
   },
+  "ship": {
+    "per_phase": true,
+    "allow_skip": false,
+    "max_release_retries": 3,
+    "release_blocking": false
+  },
+  "personas": {
+    "enabled": true,
+    "territory_enforcement": "warn"
+  },
   "secrets": {
     "env_file": ".ciagent/.env.secrets",
     "scopes": {