# KORA Studio v0.3 Live Harness Plan

## Status

KORA Studio v0.2 is complete as a local preview/demo readiness milestone. v0.2 provides a coherent first-run local setup experience, grouped `/status` fields, fixture/mock Execution Viewer data, fixture/mock Standard Mode vs KORA Boost comparison data, a report viewer placeholder, a local smoke-check helper, and public readiness and goal reports.

KORA Studio v0.3 should move the preview from static fixture-only display toward a safe local deterministic harness milestone. The goal is to generate local deterministic execution events and comparison metrics from approved sample requests, while keeping all provider, cloud, model download, and model execution paths disabled.

## Positioning

KORA Studio is a local-first AI Task Execution Router workspace.

LM Studio runs local models. KORA Studio routes local AI workflows. The model remains one execution path, not the default path.

KORA Studio v0.3 should make KORA Boost visible as an execution path difference: deterministic route checks, structured lookup, validation, fallback boundaries, and counters should be generated by a local harness instead of being presented only as static fixture text.

## v0.2 Complete State

The v0.2 local preview already provides:

- `python3 -m kora studio` localhost launch
- browser auto-open by default
- `python3 -m kora studio --no-browser`
- `python3 -m kora studio --status`
- `/health`
- `/status`
- `/`
- first-run UI section order
- system profile scaffold
- model capability estimate scaffold
- static curated model catalog scaffold
- runtime status scaffold
- installed model detection scaffold, disabled by default
- setup guidance scaffold
- disabled download/run action metadata
- fixture/mock Execution Viewer events
- fixture/mock Standard Mode vs KORA Boost comparison
- report viewer/export placeholder
- local smoke-check helper
- visual QA checklist
- readiness and goal reports

## v0.3 Objective

KORA Studio v0.3 should provide a live local harness milestone that demonstrates the execution-router concept through local deterministic requests, generated event stages, generated counters, and local harness comparison output.

The user should see, or `/status` should expose:

1. Local harness status
2. Available local deterministic sample requests
3. Live/simulated run trigger boundary
4. Event stream source status
5. Execution Viewer stages from a local harness event source
6. Standard Mode vs KORA Boost comparison from local deterministic harness output
7. Metrics snapshot from harness output
8. Report viewer placeholder connected to harness summary metadata
9. Clear local-only/no-provider/no-model-execution boundary
10. v0.3 readiness report

## Local Deterministic Harness Scope

The v0.3 harness should use only local deterministic inputs and code paths:

- synthetic sample requests committed to the repository
- deterministic route classification
- structured lookup against committed sample data only
- validation against expected local values
- model-needed boundary events without model execution
- generated event lists for the Execution Viewer
- generated counters for local harness summaries
- generated Standard Mode vs KORA Boost comparison counters
- local report placeholder metadata sourced from harness summary data

Approved sample request families:

- JSON formatting and required-field validation
- policy-like rule classification
- known FAQ lookup
- structured record normalization
- ambiguous prompt routed to a model-needed boundary

## Event Source Boundary

v0.3 may expose local harness events through `/status` first. A POST run endpoint or SSE stream should be added only if the status sample is insufficient and the implementation remains local-only, deterministic, mockable, and test-covered.

The event source must clearly distinguish:

- local deterministic harness data
- fixture/mock data retained for backward compatibility
- model-needed boundaries where execution is not connected
- provider-disabled state
- cloud-disabled state
- download/run-disabled state

## Comparison Fixture-to-Harness Migration Path

v0.2 comparison data is fixture/mock data. v0.3 should introduce local harness-generated comparison data while preserving backward-compatible fields where useful.

Migration path:

1. Add deterministic sample requests.
2. Convert sample requests into harness events and counters.
3. Expose one local harness sample run through `/status`.
4. Add local harness comparison output for Standard Mode vs KORA Boost.
5. Update the preview UI to show harness-generated stages and counters.
6. Connect the report placeholder to local harness summary metadata.
7. Keep fixture/mock fields until consumers no longer need them.

## Non-Scope

v0.3 does not add:

- real model download
- real model execution
- provider calls
- cloud sync
- remote catalog fetching
- Hugging Face or Ollama registry calls
- private model directory scans
- runtime model list commands
- active report file picker/export
- production monitoring
- billing dashboard
- cost-reduction dashboard
- energy dashboard
- LM Studio replacement behavior

## Claim Boundaries

KORA Studio v0.3 must keep these boundaries visible:

- KORA Studio v0.3 is a local preview/demo readiness milestone, not a production release.
- Execution data is local deterministic harness data or fixture/mock data until live runtime wiring is implemented.
- Model-needed boundaries do not execute models in this milestone.
- Provider calls are disabled by default.
- Cloud sync is disabled by default.
- Download and run actions remain disabled until explicitly connected.
- KORA does not remove model memory requirements.
- Larger-model workflows may become more practical when deterministic work avoids the model path.
- No production cost reduction is claimed.
- No energy reduction is claimed.
- No unsupported larger-model execution is claimed.

## v0.3 Milestone Plan

### Task 424 - v0.3 Live Harness Plan

Add this v0.3 plan and link it from the Studio docs index.

### Task 425 - Local Deterministic Harness Request Set

Add a small claim-safe sample request set and helper module for local deterministic harness inputs.

### Task 426 - Local Harness Event Builder

Build a local deterministic event builder that turns sample requests into claim-safe execution events and counters.

### Task 427 - Status API Live Harness Surface

Expose local harness status, request set, sample run, counters, and claim boundary through `/status`.

### Task 428 - Preview UI Live Harness Panel

Update the static preview UI to show the local harness request set and one sample harness run.

### Task 429 - Standard vs KORA Boost Harness Comparison

Generate comparison output from the local deterministic harness while keeping model execution disconnected.

### Task 430 - Report Placeholder Connected to Harness Summary

Connect the report viewer placeholder to local harness summary metadata, not arbitrary local files.

### Task 431 - v0.3 Local Harness Smoke Check

Extend the smoke check to verify local harness surfaces, comparison output, report source, and disabled model/provider/cloud boundaries.

### Task 432 - v0.3 Readiness and Goal Reports

Add v0.3 readiness and consolidated goal reports after full validation.

## Validation Expectations

Each milestone should run:

- `git diff --check`
- `python3 -m pytest tests/test_kora_studio_cli.py`
- `python3 -m pytest tests/test_kora_studio_server.py`
- `python3 -m pytest tests/test_kora_studio_system_profile.py`
- `python3 -m pytest tests/test_kora_studio_model_catalog.py`
- `python3 -m pytest tests/test_kora_studio_runtime_status.py`
- `python3 -m pytest tests/test_kora_studio_execution_fixture.py` if present
- `python3 -m pytest tests/test_kora_studio_comparison_fixture.py` if present
- `python3 -m pytest tests -k "studio or sse or execution or harness"`

Final v0.3 readiness should also run:

- `python3 -m pytest`
- `python3 scripts/check_kora_studio_preview.py` against a live local preview when feasible

Forbidden wording scans should be reviewed after each milestone. Matches in explicit forbidden-wording or negative-test contexts are acceptable; product claims are not.

## v0.3 Readiness Criteria

v0.3 is ready when:

- local deterministic harness requests exist
- local harness event generation exists
- `/status` exposes local harness status, sample run, counters, and claim boundary
- the static preview shows local harness events and counters
- Standard Mode vs KORA Boost comparison is generated from local harness output
- report viewer placeholder references local harness summary metadata
- the smoke check verifies v0.3 harness surfaces
- provider calls remain disabled
- cloud sync remains disabled
- model download remains disconnected
- model execution remains disconnected
- private model directory scanning remains disconnected
- runtime model list commands remain disconnected
- public docs and UI copy remain claim-safe
- full validation passes
