From 7572e715433a2ecad1f40a352632628259111d5a Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Thu, 12 Mar 2026 22:59:42 +0300
Subject: [PATCH 01/14] Promote product planning docs

---
 .../active/local-sqlite-materialization.md    | 173 ++++++++++++++
 .../active/product-reset-and-shipping.md      | 223 ++++++++++++++++++
 2 files changed, 396 insertions(+)
 create mode 100644 docs/exec-plans/active/local-sqlite-materialization.md
 create mode 100644 docs/exec-plans/active/product-reset-and-shipping.md

diff --git a/docs/exec-plans/active/local-sqlite-materialization.md b/docs/exec-plans/active/local-sqlite-materialization.md
new file mode 100644
index 0000000..7708063
--- /dev/null
+++ b/docs/exec-plans/active/local-sqlite-materialization.md
@@ -0,0 +1,173 @@
+# Execution Plan: Local SQLite Materialization and App Data Layer
+
+<!-- Verified: 2026-03-12 -->
+
+**Status:** Active  
+**Created:** 2026-03-12  
+**Goal:** Use SQLite as a local indexed/materialized view layer on top of selftune’s raw JSONL source-of-truth logs so the local app can be fast, credible, and simple to reason about.
+
+---
+
+## Executive Summary
+
+selftune’s raw JSONL logs remain the right source of truth for:
+
+- telemetry capture
+- transcript/source replay
+- repair overlays
+- append-only local durability
+
+They are not the right structure for serving a good local product experience directly.
+
+SQLite via `bun:sqlite` is the right local materialization layer because it gives us:
+
+- fast indexed reads
+- a simple single-file local store
+- WAL-backed write safety
+- zero extra network services
+- a much cleaner foundation for overview/report queries
+
+The architecture is now:
+
+- **JSONL = truth**
+- **SQLite = local indexed/materialized view**
+- **SPA = local user experience**
+
+---
+
+## Why SQLite Is Now Justified
+
+The old dashboard path showed the limits of raw-log-first serving:
+
+- repeated large file scans and joins
+- poor cold-start performance
+- heavy live payloads
+- fragile drilldown UX
+
+SQLite solves the UX/product problem without replacing the telemetry model.
+
+This is not a move to “database-first telemetry.” It is a local query/materialization layer on top of append-only source logs.
+
+---
+
+## What Has Already Landed
+
+`#42` introduced the first SQLite local materialization layer.
+
+That means the work now is not “decide whether to use SQLite.”  
+The work now is:
+
+1. stabilize the local DB schema and materialization flow
+2. make overview/report queries first-class
+3. move the local app to those queries
+4. retire the old heavy dashboard path as the primary UX
+
+---
+
+## Data Model Role
+
+SQLite should hold the structured local data needed for:
+
+- overview page
+- per-skill report page
+- evolution evidence and version history
+- summary/report payloads consumed by the local app
+
+Likely source domains:
+
+- sessions
+- prompts
+- skill invocations
+- execution facts
+- evidence
+- optional materialized aggregates for overview/report
+
+The exact schema can evolve, but its role should stay narrow:
+
+- indexed cache/materialized view
+- local query surface
+- not the authority for telemetry capture
+
+---
+
+## Architectural Rules
+
+### 1. JSONL remains authoritative
+
+If a conflict exists between raw logs and SQLite materialization, the raw logs win.
+
+### 2. Materialization must be rebuildable
+
+It should always be possible to rebuild the local DB from source-truth logs.
+
+### 3. Local app queries should be explicit
+
+Do not let the app depend on giant generic payloads. Prefer query helpers and routes that match the UX:
+
+- `OverviewPayload`
+- `SkillReportPayload`
+
+### 4. SQLite should stay local-only for now
+
+Do not make the local DB the cloud contract. Cloud stays based on canonical telemetry + DB projections.
+
+---
+
+## Immediate Work
+
+### 1. Stabilize overview/report query helpers
+
+The local data layer should explicitly support:
+
+- overview KPI/status/skill-card payload
+- single-skill report payload
+
+### 2. Move the SPA onto SQLite-backed data
+
+The React local app should stop depending primarily on the old dashboard server’s heavy data path.
+
+### 3. Keep the old dashboard path only as compatibility
+
+Do not optimize it indefinitely. Keep it as fallback until the new path is trustworthy.
+
+### 4. Keep source-truth sync first
+
+Any materialization flow must still start from fresh source-truth sync/repair data.
+
+---
+
+## Open Questions
+
+### How incremental should local materialization be?
+
+Short term:
+
+- correctness and simplicity matter more than perfect incrementalism
+
+Later:
+
+- add incremental rebuilds/checkpoints where safe and justified
+
+### How much of the old dashboard server should remain?
+
+Short term:
+
+- enough to support the new app and compatibility mode
+
+Long term:
+
+- the new local app should be the default experience
+
+---
+
+## What This Enables
+
+If this path is completed, selftune gains:
+
+- fast local overview loads
+- fast skill drilldowns
+- simpler local UX architecture
+- cleaner alignment between local and cloud payload semantics
+- a better demo path on real machine data
+
+That is why this work is now core to shipping, not optional polish.
diff --git a/docs/exec-plans/active/product-reset-and-shipping.md b/docs/exec-plans/active/product-reset-and-shipping.md
new file mode 100644
index 0000000..4bef897
--- /dev/null
+++ b/docs/exec-plans/active/product-reset-and-shipping.md
@@ -0,0 +1,223 @@
+# Execution Plan: Product Reset and Shipping Priorities
+
+<!-- Verified: 2026-03-12 -->
+
+**Status:** Active  
+**Created:** 2026-03-12  
+**Goal:** Align selftune around the actual post-merge architecture and the shortest credible path to a fast, trustworthy, shippable product.
+
+---
+
+## Executive Summary
+
+selftune is no longer blocked by telemetry architecture. It is now blocked by **product shape and UX**.
+
+Recent merged work changed the baseline:
+
+- `#38` hardened source-truth telemetry and repair paths
+- `#40` added the first orchestrator core loop
+- `#41` made generic scheduling the primary posture and OpenClaw cron optional
+- `#42` added a local SQLite materialization layer
+- `#43` improved sync progress and tightened noisy query filtering
+
+That means the next phase should optimize for:
+
+1. **Trustworthy source-truth sync**
+2. **A fast, demoable local app on top of materialized local data**
+3. **A clear orchestrated loop that evolves, validates, and watches skills**
+
+The architecture does not need a rewrite. It needs a narrower product story and a better local user experience.
+
+---
+
+## What Changed Since The Earlier Audit
+
+The earlier architecture audit was directionally right about pruning, orchestration, and avoiding over-scoping. It is now outdated in two areas:
+
+### 1. SQLite is now justified
+
+Earlier guidance argued against SQLite. That was reasonable when the local UX still looked like a lightweight HTML dashboard.
+
+It is no longer reasonable after real-machine proof showed:
+
+- slow cold dashboard loads
+- heavy client-side data flow
+- poor drilldown UX on realistic datasets
+
+The right model is now:
+
+- JSONL stays source of truth
+- SQLite becomes the indexed local view store
+- the local app should consume SQLite/materialized queries
+
+### 2. Cloud/export work is now part of the product path
+
+Canonical export and cloud ingest are no longer speculative. We already proved:
+
+- local canonical export works on real source-truth data
+- a real `PushPayloadV2` can be generated
+- cloud ingest accepts that payload end to end
+
+So cloud/local alignment now belongs in the main product path.
+
+---
+
+## Current First Principles
+
+selftune still does one thing:
+
+**make agent skills improve from real usage data**
+
+The core loop remains:
+
+1. **Observe** — ingest source-truth logs/transcripts
+2. **Detect** — identify missed triggers, failures, regressions
+3. **Fix** — propose and validate improvements
+4. **Ship** — deploy and monitor safely
+
+The most important architectural clarification is:
+
+- **hooks are hints**
+- **transcripts/logs are truth**
+
+That should govern future product work.
+
+---
+
+## Updated Priority Stack
+
+## Priority 1: Trustworthy Local Data Model
+
+Keep making source-truth sync the authority.
+
+Includes:
+
+- transcript/rollout replay correctness
+- repaired usage overlays
+- provenance and scope classification
+- polluted query cleanup
+- sync transparency and safe incrementalism
+
+## Priority 2: Demoable Local Product
+
+Make the local app fast and believable.
+
+Includes:
+
+- SQLite materialization
+- SPA overview and skill report UX
+- clear loading/empty/error states
+- making the new local app the default path
+
+## Priority 3: Orchestrated Skill Improvement
+
+Make the closed loop obvious and usable.
+
+Includes:
+
+- orchestrator refinement
+- generic scheduling
+- evolve/watch safety and explainability
+
+## Priority 4: Release And Ship
+
+Includes:
+
+- published package proof
+- install and upgrade path
+- quickstart/demo path
+- stable docs/help
+
+## Priority 5: Paperclip And Multi-Repo Iteration
+
+Paperclip should accelerate iteration, not become the product priority.
+
+---
+
+## Current Recommendations
+
+### 1. Make the SPA the real default dashboard path
+
+Once the SQLite-backed local app is credible, stop treating it as sidecar UI.
+
+### 2. Stabilize payload contracts for local/cloud dashboards
+
+Define and align:
+
+- `OverviewPayload`
+- `SkillReportPayload`
+
+Local should produce them from JSONL + SQLite/materialized queries.  
+Cloud should produce them from canonical ingest + DB projections.
+
+### 3. Keep reducing remaining unknown provenance
+
+Unknown provenance is much lower than before, but not zero. Continue tightening:
+
+- Claude repair path recovery
+- scope/project/global/admin detection
+
+### 4. Make orchestrator output explainable
+
+If the system evolves or refuses to evolve a skill, the user should see why immediately.
+
+### 5. Reduce the shipping surface in docs/help
+
+Not by deleting code, but by making the main story smaller and easier to follow:
+
+- `sync`
+- `status`
+- local app
+- `evolve`
+- `watch`
+- orchestrator
+- `doctor`
+
+---
+
+## Things We Should Not Do Right Now
+
+1. **Do not return to hooks as the primary truth source**
+2. **Do not spend another cycle optimizing the old static dashboard path**
+3. **Do not make OpenClaw-specific automation the main story again**
+4. **Do not do broad CLI regrouping before the local app and orchestrator feel good**
+5. **Do not overinvest in Paperclip/platform setup at the expense of product proof**
+
+---
+
+## Updated 1.0 Path
+
+### Phase 1
+
+- source-truth sync remains correct and explainable
+- query/provenance cleanup lands
+- local SQLite/materialization path is stable
+
+### Phase 2
+
+- SPA overview and skill report become the default local UX
+- the local app is fast on real-machine datasets
+
+### Phase 3
+
+- orchestrator becomes the main autonomous loop entry point
+- generic scheduling path is documented and stable
+
+### Phase 4
+
+- package release / install proof
+- cloud/local payload alignment
+- GTM/demo narrative based on the actual product loop
+
+---
+
+## Final Assessment
+
+The key shift is simple:
+
+- telemetry correctness is good enough to build on
+- the local app is now the highest-leverage product bottleneck
+- orchestration is the next core integration layer
+- shipping selftune means making the product feel fast, obvious, and trustworthy on a real machine
+
+That is the current architecture priority.

From ba89071c32633f43e3a99aea2edc06aca6b58ef3 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 13:17:52 +0300
Subject: [PATCH 02/14] Add execution plans for product gaps and evals

---
 docs/exec-plans/active/grader-prompt-evals.md | 110 +++++++++++++++++
 .../active/mcp-tool-descriptions.md           | 112 ++++++++++++++++++
 .../active/product-reset-and-shipping.md      |  36 ++++++
 3 files changed, 258 insertions(+)
 create mode 100644 docs/exec-plans/active/grader-prompt-evals.md
 create mode 100644 docs/exec-plans/active/mcp-tool-descriptions.md

diff --git a/docs/exec-plans/active/grader-prompt-evals.md b/docs/exec-plans/active/grader-prompt-evals.md
new file mode 100644
index 0000000..9abfdb6
--- /dev/null
+++ b/docs/exec-plans/active/grader-prompt-evals.md
@@ -0,0 +1,110 @@
+# Execution Plan: Grader Prompt and Agent Evals
+
+<!-- Verified: 2026-03-14 -->
+
+**Status:** Active  
+**Created:** 2026-03-14  
+**Goal:** Evaluate and improve the grader prompts and grading agents so selftune’s session/skill judgments are trustworthy, stable, and measurable.
+
+---
+
+## Problem Statement
+
+selftune relies on grading to decide:
+
+- whether a session succeeded
+- whether a skill was valuable
+- whether evolution helped
+- whether monitoring signals are believable
+
+That makes grader quality a core product dependency.
+
+Current risks:
+
+- grader prompts may be too brittle or too noisy
+- agent/runtime choice may affect grading consistency
+- we do not yet have a tight eval loop for the graders themselves
+- users can lose trust quickly if the grader feels arbitrary
+
+---
+
+## Goals
+
+1. Build a real eval loop for selftune’s grading prompts/agents.
+2. Measure grader consistency and failure modes explicitly.
+3. Improve prompt quality where graders are too noisy, too weak, or too inconsistent.
+4. Separate “grading infrastructure exists” from “grading is trustworthy.”
+
+---
+
+## Scope
+
+In scope:
+
+- session grading prompts
+- skill-level grading prompts/agents
+- eval sets and fixtures for grader behavior
+- comparison of grader outputs across representative examples
+
+Out of scope:
+
+- broad telemetry architecture changes
+- cloud analytics work
+- unrelated UI work
+
+---
+
+## Recommended Work
+
+### 1. Define grader eval corpora
+
+Build or curate examples for:
+
+- clear passes
+- clear failures
+- ambiguous sessions
+- noisy wrapper/system-polluted sessions
+- skills that should obviously count vs should not count
+
+### 2. Measure prompt behavior
+
+Evaluate:
+
+- consistency
+- false positives
+- false negatives
+- susceptibility to polluted context
+
+### 3. Compare prompt/agent variants
+
+Where useful, compare:
+
+- revised prompt variants
+- different calling styles
+- stricter vs broader grading criteria
+
+### 4. Feed results back into product trust
+
+Use the findings to improve:
+
+- grading prompts
+- grading docs
+- orchestrator confidence
+- monitoring credibility
+
+---
+
+## Deliverables
+
+1. A grader-focused eval suite
+2. Prompt revisions where justified
+3. A short report on grader failure modes
+4. Recommendations for how much trust product features should place in current grading
+
+---
+
+## Success Criteria
+
+- Grader behavior becomes more measurable and explainable
+- Prompt changes are backed by eval evidence, not intuition
+- selftune’s “it works” claim becomes more credible because the grading layer is being tested directly
diff --git a/docs/exec-plans/active/mcp-tool-descriptions.md b/docs/exec-plans/active/mcp-tool-descriptions.md
new file mode 100644
index 0000000..242dab5
--- /dev/null
+++ b/docs/exec-plans/active/mcp-tool-descriptions.md
@@ -0,0 +1,112 @@
+# Execution Plan: MCP Tool Descriptions and Surface Quality
+
+<!-- Verified: 2026-03-14 -->
+
+**Status:** Active  
+**Created:** 2026-03-14  
+**Goal:** Improve selftune’s MCP/tool descriptions so agent runtimes can understand and select the right tools more reliably, with less ambiguity and less prompt burden.
+
+---
+
+## Problem Statement
+
+selftune increasingly depends on agents selecting the right commands and flows without human hand-holding. That makes tool surface quality part of the product.
+
+Current risk areas:
+
+- command descriptions are uneven across workflows
+- some commands are over-broad or under-specified
+- agent runtimes need clearer “when to use this” guidance
+- local app/orchestrator/scheduler capabilities have changed faster than the descriptive layer around them
+
+This is especially important for:
+
+- MCP-style tool exposure
+- Paperclip / Claude Code / other autonomous agent runtimes
+- future cloud/local parity in product semantics
+
+---
+
+## Goals
+
+1. Define clean, unambiguous descriptions for the most important selftune tools and commands.
+2. Reduce ambiguity in when an agent should use:
+   - `sync`
+   - `status`
+   - `doctor`
+   - `evolve`
+   - `watch`
+   - orchestrator
+   - local app/dashboard flows
+3. Make the tool surface reflect the current source-truth-first architecture.
+4. Improve the ability of external runtimes to use selftune without long custom prompts.
+
+---
+
+## Scope
+
+In scope:
+
+- CLI command descriptions and help text
+- MCP/tool descriptions for externally exposed workflows
+- workflow routing docs in `skill/Workflows/`
+- any thin metadata or schema layer needed to describe the tool surface clearly
+
+Out of scope:
+
+- large command regrouping refactors
+- product semantics changes
+- cloud implementation details
+
+---
+
+## Recommended Work
+
+### 1. Inventory the current tool surface
+
+Create a current map of:
+
+- core user-facing commands
+- advanced commands
+- commands that should be de-emphasized
+
+### 2. Standardize description format
+
+Each command/tool description should answer:
+
+- what it does
+- when to use it
+- what preconditions it assumes
+- what it outputs
+- whether it changes state
+
+### 3. Align with the current architecture
+
+Descriptions should clearly reflect:
+
+- source-truth sync first
+- local app as the intended UX path
+- OpenClaw cron as optional, not primary
+- orchestrator as the autonomous loop entry
+
+### 4. Define agent-friendly descriptions
+
+Produce descriptions that are short enough for tool selection, but specific enough to reduce misuse.
+
+---
+
+## Deliverables
+
+1. A canonical inventory of the selftune tool surface
+2. Updated command/workflow descriptions
+3. MCP/tool-facing description text for core commands
+4. Guidance on which tools should be exposed by default vs advanced
+
+---
+
+## Success Criteria
+
+- Agents choose the right selftune tools with less prompt scaffolding
+- Fewer ambiguous tool-selection failures
+- The tool surface matches the current product story
+- Help/docs/workflow descriptions stop lagging behind the implementation
diff --git a/docs/exec-plans/active/product-reset-and-shipping.md b/docs/exec-plans/active/product-reset-and-shipping.md
index 4bef897..00dd125 100644
--- a/docs/exec-plans/active/product-reset-and-shipping.md
+++ b/docs/exec-plans/active/product-reset-and-shipping.md
@@ -136,6 +136,42 @@ Paperclip should accelerate iteration, not become the product priority.
 
 ## Current Recommendations
 
+## Remaining Product Gaps
+
+These are the highest-confidence gaps still blocking adoption and confident shipping:
+
+### 1. The local UX is still not good enough
+
+The old dashboard path remains too slow and awkward, and the SQLite + SPA path is not yet the obvious default experience.
+
+### 2. The autonomous loop is not yet obvious and trustworthy
+
+The orchestrator exists, but the product does not yet feel like a safe, comprehensible “turn this on and it improves my skills” system.
+
+### 3. Evolution is still under-triggering in practice
+
+We can prove skill usage and at least one real successful evolution, but the system still does not yet feel like it consistently turns real usage into useful proposed improvements across many skills.
+
+### 4. Query and environment pollution still distort the signal
+
+Polluted host environments still make status and unmatched-query outputs harder to trust than they should be.
+
+### 5. Local/cloud product contracts are not fully stabilized
+
+We proved OSS export -> cloud ingest, but the actual user-facing payload contracts for overview/report views still need to be made explicit and aligned.
+
+### 6. The default story is still too broad
+
+The product still presents too much surface area for a first-time user instead of one tight loop.
+
+### 7. The release path still needs one clean published-package proof
+
+Branch code has been proven on a real machine; the final “published install behaves the same way” proof still needs to happen.
+
+---
+
+## Current Recommendations
+
 ### 1. Make the SPA the real default dashboard path
 
 Once the SQLite-backed local app is credible, stop treating it as sidecar UI.

From 94c8f67b0cef53bf12f338bd9403b5da1a2e3b33 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 16:40:57 +0300
Subject: [PATCH 03/14] Prepare SPA dashboard release path

---
 apps/local-dashboard/HANDOFF.md          |   6 +
 apps/local-dashboard/src/types.ts        | 180 ++-------------
 cli/selftune/dashboard-contract.ts       | 161 ++++++++++++++
 cli/selftune/localdb/queries.ts          | 116 +---------
 cli/selftune/orchestrate.ts              |  52 +++--
 package.json                             |   2 +
 skill/Workflows/Dashboard.md             |   6 +
 tests/dashboard/dashboard-server.test.ts | 270 +++++++++++++----------
 tests/orchestrate.test.ts                |  37 +++-
 9 files changed, 425 insertions(+), 405 deletions(-)
 create mode 100644 cli/selftune/dashboard-contract.ts

diff --git a/apps/local-dashboard/HANDOFF.md b/apps/local-dashboard/HANDOFF.md
index 251a32f..6312396 100644
--- a/apps/local-dashboard/HANDOFF.md
+++ b/apps/local-dashboard/HANDOFF.md
@@ -28,6 +28,12 @@ JSONL logs → materializeIncremental() → SQLite → getOverviewPayload() / ge
 ## How to run
 
 ```bash
+# From repo root
+bun run dev
+# → if 7888 is free, starts dashboard server on 7888 and SPA dev server on http://localhost:5199
+# → if 7888 is already in use, reuses that dashboard server and starts only the SPA dev server
+
+# Or run manually:
 # Terminal 1: Start the dashboard server
 selftune dashboard --port 7888
 
diff --git a/apps/local-dashboard/src/types.ts b/apps/local-dashboard/src/types.ts
index ef9aae6..3f6fb9a 100644
--- a/apps/local-dashboard/src/types.ts
+++ b/apps/local-dashboard/src/types.ts
@@ -1,168 +1,22 @@
 /** Data contracts for the v2 SQLite-backed dashboard API */
 
-// -- Shared primitives --------------------------------------------------------
-
-export interface TelemetryRecord {
-  timestamp: string;
-  session_id: string;
-  skills_triggered: string[];
-  errors_encountered: number;
-  total_tool_calls: number;
-}
-
-export interface SkillUsageRecord {
-  timestamp: string;
-  session_id: string;
-  skill_name: string;
-  skill_path: string;
-  query: string;
-  triggered: boolean;
-  source: string | null;
-}
-
-export interface EvalSnapshot {
-  before_pass_rate?: number;
-  after_pass_rate?: number;
-  net_change?: number;
-  improved?: boolean;
-  regressions?: Array<Record<string, unknown>>;
-  new_passes?: Array<Record<string, unknown>>;
-}
-
-export interface EvolutionEntry {
-  timestamp: string;
-  proposal_id: string;
-  action: string;
-  details: string;
-  eval_snapshot?: EvalSnapshot | null;
-}
-
-export interface UnmatchedQuery {
-  timestamp: string;
-  session_id: string;
-  query: string;
-}
-
-export interface PendingProposal {
-  proposal_id: string;
-  action: string;
-  timestamp: string;
-  details: string;
-  skill_name?: string;
-}
-
-// -- /api/v2/overview response ------------------------------------------------
-
-export interface SkillSummary {
-  skill_name: string;
-  skill_scope: string | null;
-  total_checks: number;
-  triggered_count: number;
-  pass_rate: number;
-  unique_sessions: number;
-  last_seen: string | null;
-  has_evidence: boolean;
-}
-
-export interface OverviewResponse {
-  overview: {
-    telemetry: TelemetryRecord[];
-    skills: SkillUsageRecord[];
-    evolution: EvolutionEntry[];
-    counts: {
-      telemetry: number;
-      skills: number;
-      evolution: number;
-      evidence: number;
-      sessions: number;
-      prompts: number;
-    };
-    unmatched_queries: UnmatchedQuery[];
-    pending_proposals: PendingProposal[];
-  };
-  skills: SkillSummary[];
-  version?: string;
-}
-
-// -- /api/v2/skills/:name response --------------------------------------------
-
-export interface EvidenceEntry {
-  proposal_id: string;
-  target: string;
-  stage: string;
-  timestamp: string;
-  rationale: string | null;
-  confidence: number | null;
-  original_text: string | null;
-  proposed_text: string | null;
-  validation: Record<string, unknown> | null;
-  details: string | null;
-  eval_set: Array<Record<string, unknown>>;
-}
-
-export interface CanonicalInvocation {
-  timestamp: string;
-  session_id: string;
-  skill_name: string;
-  invocation_mode: string | null;
-  triggered: boolean;
-  confidence: number | null;
-  tool_name: string | null;
-}
-
-export interface PromptSample {
-  prompt_text: string;
-  prompt_kind: string | null;
-  is_actionable: boolean;
-  occurred_at: string;
-  session_id: string;
-}
-
-export interface SessionMeta {
-  session_id: string;
-  platform: string | null;
-  model: string | null;
-  agent_cli: string | null;
-  branch: string | null;
-  workspace_path: string | null;
-  started_at: string | null;
-  ended_at: string | null;
-  completion_status: string | null;
-}
-
-export interface SkillReportResponse {
-  skill_name: string;
-  usage: {
-    total_checks: number;
-    triggered_count: number;
-    pass_rate: number;
-  };
-  recent_invocations: Array<{
-    timestamp: string;
-    session_id: string;
-    query: string;
-    triggered: boolean;
-    source: string | null;
-  }>;
-  evidence: EvidenceEntry[];
-  sessions_with_skill: number;
-  evolution: EvolutionEntry[];
-  pending_proposals: PendingProposal[];
-  // Extended data
-  token_usage: {
-    total_input_tokens: number;
-    total_output_tokens: number;
-  };
-  canonical_invocations: CanonicalInvocation[];
-  duration_stats: {
-    avg_duration_ms: number;
-    total_duration_ms: number;
-    execution_count: number;
-    total_errors: number;
-  };
-  prompt_samples: PromptSample[];
-  session_metadata: SessionMeta[];
-}
+export type {
+  CanonicalInvocation,
+  EvalSnapshot,
+  EvidenceEntry,
+  EvolutionEntry,
+  OverviewPayload,
+  OverviewResponse,
+  PendingProposal,
+  PromptSample,
+  SessionMeta,
+  SkillReportPayload,
+  SkillReportResponse,
+  SkillSummary,
+  SkillUsageRecord,
+  TelemetryRecord,
+  UnmatchedQuery,
+} from "../../../cli/selftune/dashboard-contract";
 
 // -- UI types -----------------------------------------------------------------
 
diff --git a/cli/selftune/dashboard-contract.ts b/cli/selftune/dashboard-contract.ts
new file mode 100644
index 0000000..6c235b3
--- /dev/null
+++ b/cli/selftune/dashboard-contract.ts
@@ -0,0 +1,161 @@
+export interface TelemetryRecord {
+  timestamp: string;
+  session_id: string;
+  skills_triggered: string[];
+  errors_encountered: number;
+  total_tool_calls: number;
+}
+
+export interface SkillUsageRecord {
+  timestamp: string;
+  session_id: string;
+  skill_name: string;
+  skill_path: string;
+  query: string;
+  triggered: boolean;
+  source: string | null;
+}
+
+export interface EvalSnapshot {
+  before_pass_rate?: number;
+  after_pass_rate?: number;
+  net_change?: number;
+  improved?: boolean;
+  regressions?: Array<Record<string, unknown>>;
+  new_passes?: Array<Record<string, unknown>>;
+}
+
+export interface EvolutionEntry {
+  timestamp: string;
+  proposal_id: string;
+  action: string;
+  details: string;
+  eval_snapshot?: EvalSnapshot | null;
+}
+
+export interface UnmatchedQuery {
+  timestamp: string;
+  session_id: string;
+  query: string;
+}
+
+export interface PendingProposal {
+  proposal_id: string;
+  action: string;
+  timestamp: string;
+  details: string;
+  skill_name?: string;
+}
+
+export interface SkillSummary {
+  skill_name: string;
+  skill_scope: string | null;
+  total_checks: number;
+  triggered_count: number;
+  pass_rate: number;
+  unique_sessions: number;
+  last_seen: string | null;
+  has_evidence: boolean;
+}
+
+export interface OverviewPayload {
+  telemetry: TelemetryRecord[];
+  skills: SkillUsageRecord[];
+  evolution: EvolutionEntry[];
+  counts: {
+    telemetry: number;
+    skills: number;
+    evolution: number;
+    evidence: number;
+    sessions: number;
+    prompts: number;
+  };
+  unmatched_queries: UnmatchedQuery[];
+  pending_proposals: PendingProposal[];
+}
+
+export interface OverviewResponse {
+  overview: OverviewPayload;
+  skills: SkillSummary[];
+  version?: string;
+}
+
+export interface EvidenceEntry {
+  proposal_id: string;
+  target: string;
+  stage: string;
+  timestamp: string;
+  rationale: string | null;
+  confidence: number | null;
+  original_text: string | null;
+  proposed_text: string | null;
+  validation: Record<string, unknown> | null;
+  details: string | null;
+  eval_set: Array<Record<string, unknown>>;
+}
+
+export interface CanonicalInvocation {
+  timestamp: string;
+  session_id: string;
+  skill_name: string;
+  invocation_mode: string | null;
+  triggered: boolean;
+  confidence: number | null;
+  tool_name: string | null;
+}
+
+export interface PromptSample {
+  prompt_text: string;
+  prompt_kind: string | null;
+  is_actionable: boolean;
+  occurred_at: string;
+  session_id: string;
+}
+
+export interface SessionMeta {
+  session_id: string;
+  platform: string | null;
+  model: string | null;
+  agent_cli: string | null;
+  branch: string | null;
+  workspace_path: string | null;
+  started_at: string | null;
+  ended_at: string | null;
+  completion_status: string | null;
+}
+
+export interface SkillReportPayload {
+  skill_name: string;
+  usage: {
+    total_checks: number;
+    triggered_count: number;
+    pass_rate: number;
+  };
+  recent_invocations: Array<{
+    timestamp: string;
+    session_id: string;
+    query: string;
+    triggered: boolean;
+    source: string | null;
+  }>;
+  evidence: EvidenceEntry[];
+  sessions_with_skill: number;
+}
+
+export interface SkillReportResponse extends SkillReportPayload {
+  evolution: EvolutionEntry[];
+  pending_proposals: PendingProposal[];
+  token_usage: {
+    total_input_tokens: number;
+    total_output_tokens: number;
+  };
+  canonical_invocations: CanonicalInvocation[];
+  duration_stats: {
+    avg_duration_ms: number;
+    total_duration_ms: number;
+    execution_count: number;
+    total_errors: number;
+  };
+  prompt_samples: PromptSample[];
+  session_metadata: SessionMeta[];
+}
diff --git a/cli/selftune/localdb/queries.ts b/cli/selftune/localdb/queries.ts
index 51f93ca..82a7b99 100644
--- a/cli/selftune/localdb/queries.ts
+++ b/cli/selftune/localdb/queries.ts
@@ -6,53 +6,12 @@
  */
 
 import type { Database } from "bun:sqlite";
-
-// -- Overview payload ---------------------------------------------------------
-
-export interface OverviewPayload {
-  telemetry: Array<{
-    timestamp: string;
-    session_id: string;
-    skills_triggered: string[];
-    errors_encountered: number;
-    total_tool_calls: number;
-  }>;
-  skills: Array<{
-    timestamp: string;
-    session_id: string;
-    skill_name: string;
-    skill_path: string;
-    query: string;
-    triggered: boolean;
-    source: string | null;
-  }>;
-  evolution: Array<{
-    timestamp: string;
-    proposal_id: string;
-    action: string;
-    details: string;
-  }>;
-  counts: {
-    telemetry: number;
-    skills: number;
-    evolution: number;
-    evidence: number;
-    sessions: number;
-    prompts: number;
-  };
-  unmatched_queries: Array<{
-    timestamp: string;
-    session_id: string;
-    query: string;
-  }>;
-  pending_proposals: Array<{
-    proposal_id: string;
-    action: string;
-    timestamp: string;
-    details: string;
-    skill_name: string;
-  }>;
-}
+import type {
+  OverviewPayload,
+  PendingProposal,
+  SkillReportPayload,
+  SkillSummary,
+} from "../dashboard-contract.js";
 
 /**
  * Build the overview payload from SQLite, suitable for the dashboard main page.
@@ -77,7 +36,7 @@ export function getOverviewPayload(db: Database): OverviewPayload {
   const telemetry = telemetryRows.map((row) => ({
     timestamp: row.timestamp,
     session_id: row.session_id,
-    skills_triggered: safeParseJsonArray(row.skills_triggered_json),
+    skills_triggered: safeParseJsonArray<string>(row.skills_triggered_json),
     errors_encountered: row.errors_encountered,
     total_tool_calls: row.total_tool_calls,
   }));
@@ -174,38 +133,6 @@ export function getOverviewPayload(db: Database): OverviewPayload {
   };
 }
 
-// -- Skill report payload -----------------------------------------------------
-
-export interface SkillReportPayload {
-  skill_name: string;
-  usage: {
-    total_checks: number;
-    triggered_count: number;
-    pass_rate: number;
-  };
-  recent_invocations: Array<{
-    timestamp: string;
-    session_id: string;
-    query: string;
-    triggered: boolean;
-    source: string | null;
-  }>;
-  evidence: Array<{
-    proposal_id: string;
-    target: string;
-    stage: string;
-    timestamp: string;
-    rationale: string | null;
-    confidence: number | null;
-    original_text: string | null;
-    proposed_text: string | null;
-    validation: Record<string, unknown> | null;
-    details: string | null;
-    eval_set: string[];
-  }>;
-  sessions_with_skill: number;
-}
-
 /**
  * Build the skill report payload for a specific skill.
  */
@@ -285,7 +212,7 @@ export function getSkillReportPayload(db: Database, skillName: string): SkillRep
     proposed_text: row.proposed_text,
     validation: safeParseJson(row.validation_json),
     details: row.details,
-    eval_set: safeParseJsonArray(row.eval_set_json),
+    eval_set: safeParseJsonArray<Record<string, unknown>>(row.eval_set_json),
   }));
 
   // Unique sessions count
@@ -306,19 +233,6 @@ export function getSkillReportPayload(db: Database, skillName: string): SkillRep
   };
 }
 
-// -- Skills list payload ------------------------------------------------------
-
-export interface SkillSummary {
-  skill_name: string;
-  skill_scope: string | null;
-  total_checks: number;
-  triggered_count: number;
-  pass_rate: number;
-  unique_sessions: number;
-  last_seen: string | null;
-  has_evidence: boolean;
-}
-
 /**
  * Get a summary list of all skills with aggregated stats.
  */
@@ -368,16 +282,6 @@ export function getSkillsList(db: Database): SkillSummary[] {
   }));
 }
 
-// -- Shared query helpers -----------------------------------------------------
-
-export interface PendingProposal {
-  proposal_id: string;
-  action: string;
-  timestamp: string;
-  details: string;
-  skill_name: string;
-}
-
 /**
  * Get pending proposals (created/validated with no terminal action).
  * Optionally filtered by skill_name.
@@ -407,11 +311,11 @@ export function getPendingProposals(db: Database, skillName?: string): PendingPr
 
 // -- Helpers ------------------------------------------------------------------
 
-function safeParseJsonArray(json: string | null): string[] {
+function safeParseJsonArray<T = string>(json: string | null): T[] {
   if (!json) return [];
   try {
     const parsed = JSON.parse(json);
-    return Array.isArray(parsed) ? parsed : [];
+    return Array.isArray(parsed) ? (parsed as T[]) : [];
   } catch {
     return [];
   }
diff --git a/cli/selftune/orchestrate.ts b/cli/selftune/orchestrate.ts
index ae2f61d..092156d 100644
--- a/cli/selftune/orchestrate.ts
+++ b/cli/selftune/orchestrate.ts
@@ -5,7 +5,8 @@
  * It chains existing modules (sync, status, evolve, watch) into one
  * coordinated run with explicit candidate selection and safety controls.
  *
- * Default behavior is safe: dry-run mode, no deployments without --auto-approve.
+ * Default behavior is autonomous for low-risk description evolution, with
+ * explicit dry-run and review-required modes for human-in-the-loop operation.
  */
 
 import { homedir } from "node:os";
@@ -38,8 +39,8 @@ import { readEffectiveSkillUsageRecords } from "./utils/skill-log.js";
 export interface OrchestrateOptions {
   /** Run sync → status → evolve → watch without writing changes. */
   dryRun: boolean;
-  /** Allow evolve to deploy changes (without this, evolve always uses dry-run). */
-  autoApprove: boolean;
+  /** Approval policy for low-risk description evolution. */
+  approvalMode: "auto" | "review";
   /** Scope to a single skill by name. */
   skillFilter?: string;
   /** Cap the number of skills processed per run. */
@@ -70,7 +71,7 @@ export interface OrchestrateResult {
     watched: number;
     skipped: number;
     dryRun: boolean;
-    autoApprove: boolean;
+    approvalMode: "auto" | "review";
     elapsedMs: number;
   };
 }
@@ -302,7 +303,7 @@ export async function orchestrate(
       continue;
     }
 
-    const effectiveDryRun = options.dryRun || !options.autoApprove;
+    const effectiveDryRun = options.dryRun || options.approvalMode === "review";
     console.error(
       `[orchestrate] Evolving "${candidate.skill}"${effectiveDryRun ? " (dry-run)" : ""}...`,
     );
@@ -405,7 +406,7 @@ export async function orchestrate(
       watched: watchedCount,
       skipped: candidates.filter((c) => c.action === "skip").length,
       dryRun: options.dryRun,
-      autoApprove: options.autoApprove,
+      approvalMode: options.approvalMode,
       elapsedMs: Date.now() - startTime,
     },
   };
@@ -420,7 +421,8 @@ export async function orchestrate(
 export async function cliMain(): Promise<void> {
   const { values } = parseArgs({
     options: {
-      "dry-run": { type: "boolean", default: true },
+      "dry-run": { type: "boolean", default: false },
+      "review-required": { type: "boolean", default: false },
       "auto-approve": { type: "boolean", default: false },
       skill: { type: "string" },
       "max-skills": { type: "string", default: "5" },
@@ -440,8 +442,9 @@ Usage:
   selftune orchestrate [options]
 
 Options:
-  --dry-run             Preview actions without mutations (default: true)
-  --auto-approve        Allow evolve to deploy changes
+  --dry-run             Preview actions without mutations
+  --review-required     Validate candidates but require human review before deploy
+  --auto-approve        Deprecated alias; autonomous mode is now the default
   --skill <name>        Scope to a single skill
   --max-skills <n>      Cap skills processed per run (default: 5)
   --recent-window <hrs> Hours to look back for watch targets (default: 48)
@@ -449,13 +452,15 @@ Options:
   -h, --help            Show this help message
 
 Safety:
-  By default, orchestrate runs in dry-run mode. Evolve proposals are
-  validated but not deployed. Pass --auto-approve to enable deployment.
-  Even with --auto-approve, each skill must pass validation gates.
+  By default, low-risk description evolution runs autonomously after
+  validation. Use --review-required to keep a human in the loop, or
+  --dry-run to preview the whole loop without mutations. Every deploy
+  still passes validation gates first.
 
 Examples:
-  selftune orchestrate                          # dry-run preview
-  selftune orchestrate --auto-approve           # deploy validated changes
+  selftune orchestrate                          # autonomous description evolution
+  selftune orchestrate --review-required        # validate but do not deploy
+  selftune orchestrate --dry-run                # preview only
   selftune orchestrate --skill Research         # single skill
   selftune orchestrate --max-skills 3           # limit scope`);
     process.exit(0);
@@ -473,13 +478,20 @@ Examples:
     process.exit(1);
   }
 
-  // --auto-approve implies --no-dry-run
   const autoApprove = values["auto-approve"] ?? false;
-  const dryRun = autoApprove ? false : (values["dry-run"] ?? true);
+  if (autoApprove) {
+    console.error(
+      "[orchestrate] --auto-approve is deprecated; autonomous mode is now the default.",
+    );
+  }
+
+  const reviewRequired = values["review-required"] ?? false;
+  const dryRun = values["dry-run"] ?? false;
+  const approvalMode: "auto" | "review" = reviewRequired ? "review" : "auto";
 
   const result = await orchestrate({
     dryRun,
-    autoApprove,
+    approvalMode,
     skillFilter: values.skill,
     maxSkills,
     recentWindowHours: recentWindow,
@@ -499,11 +511,13 @@ Examples:
   console.error(`  Watched:        ${result.summary.watched}`);
   console.error(`  Skipped:        ${result.summary.skipped}`);
   console.error(`  Dry run:        ${result.summary.dryRun}`);
-  console.error(`  Auto-approve:   ${result.summary.autoApprove}`);
+  console.error(`  Approval mode:  ${result.summary.approvalMode}`);
   console.error(`  Elapsed:        ${(result.summary.elapsedMs / 1000).toFixed(1)}s`);
 
   if (result.summary.dryRun && result.summary.evaluated > 0) {
-    console.error("\n  Pass --auto-approve to deploy validated changes.");
+    console.error("\n  Rerun without --dry-run to allow validated deployments.");
+  } else if (result.summary.approvalMode === "review" && result.summary.evaluated > 0) {
+    console.error("\n  Rerun without --review-required to allow validated deployments.");
   }
 
   process.exit(0);
diff --git a/package.json b/package.json
index c085f8a..949820c 100644
--- a/package.json
+++ b/package.json
@@ -50,6 +50,8 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "dev": "sh -c 'if lsof -iTCP:7888 -sTCP:LISTEN >/dev/null 2>&1; then echo \"Using existing dashboard server on 7888\"; cd apps/local-dashboard && bun install && bunx vite --strictPort; else cd apps/local-dashboard && bun install && bun run dev; fi'",
+    "dev:dashboard": "bun run dev",
     "lint": "bunx @biomejs/biome check .",
     "lint:fix": "bunx @biomejs/biome check --write .",
     "lint:arch": "bun run lint-architecture.ts",
diff --git a/skill/Workflows/Dashboard.md b/skill/Workflows/Dashboard.md
index bb9aa8b..2b86070 100644
--- a/skill/Workflows/Dashboard.md
+++ b/skill/Workflows/Dashboard.md
@@ -208,6 +208,12 @@ selftune dashboard --port 8080
 To develop the React SPA locally:
 
 ```bash
+# From repo root
+bun run dev
+# → if 7888 is free, starts both the dashboard server and the SPA dev server
+# → if 7888 is already in use, reuses that dashboard server and starts only the SPA dev server on http://localhost:5199
+
+# Or run manually:
 # Terminal 1: Start the dashboard server
 selftune dashboard --port 7888
 
diff --git a/tests/dashboard/dashboard-server.test.ts b/tests/dashboard/dashboard-server.test.ts
index 2e05998..5f09344 100644
--- a/tests/dashboard/dashboard-server.test.ts
+++ b/tests/dashboard/dashboard-server.test.ts
@@ -47,63 +47,98 @@ beforeAll(async () => {
 });
 
 describe("dashboard-server", () => {
-  let server: { server: unknown; stop: () => void; port: number };
-
-  beforeAll(async () => {
-    server = await startDashboardServer({
-      port: 0, // random port
-      host: "localhost",
-      openBrowser: false,
-      dataLoader: () => fakeData,
-      statusLoader: () => ({
-        skills: [
-          {
-            name: "test-skill",
-            passRate: 1,
-            trend: "stable",
-            missedQueries: 0,
-            status: "HEALTHY",
-            snapshot: null,
+  let serverPromise:
+    | Promise<{ server: unknown; stop: () => void; port: number }>
+    | null = null;
+
+  async function getServer(): Promise<{ server: unknown; stop: () => void; port: number }> {
+    if (!serverPromise) {
+      serverPromise = startDashboardServer({
+        port: 0, // random port
+        host: "127.0.0.1",
+        openBrowser: false,
+        dataLoader: () => fakeData,
+        statusLoader: () => ({
+          skills: [
+            {
+              name: "test-skill",
+              passRate: 1,
+              trend: "stable",
+              missedQueries: 0,
+              status: "HEALTHY",
+              snapshot: null,
+            },
+          ],
+          unmatchedQueries: 0,
+          pendingProposals: 0,
+          lastSession: "2026-03-12T10:00:00Z",
+          system: {
+            healthy: true,
+            pass: 1,
+            fail: 0,
+            warn: 0,
           },
-        ],
-        unmatchedQueries: 0,
-        pendingProposals: 0,
-        lastSession: "2026-03-12T10:00:00Z",
-        system: {
-          healthy: true,
-          pass: 1,
-          fail: 0,
-          warn: 0,
-        },
-      }),
-      actionRunner: async (command) => ({
-        success: command !== "rollback",
-        output: `${command} ok`,
-        error: command === "rollback" ? "rollback blocked in test" : null,
-      }),
-    });
-  });
-
-  afterAll(() => {
-    server?.stop();
+        }),
+        actionRunner: async (command) => ({
+          success: command !== "rollback",
+          output: `${command} ok`,
+          error: command === "rollback" ? "rollback blocked in test" : null,
+        }),
+      });
+    }
+
+    return serverPromise;
+  }
+
+  async function readRootHtml(): Promise<string> {
+    const server = await getServer();
+    const res = await fetch(`http://127.0.0.1:${server.port}/`);
+    return res.text();
+  }
+
+  async function servesSpaShell(): Promise<boolean> {
+    const html = await readRootHtml();
+    return html.includes("<div id=\"root\"></div>") && html.includes("/assets/");
+  }
+
+  afterAll(async () => {
+    if (serverPromise) {
+      const server = await serverPromise;
+      server.stop();
+    }
   });
 
   // ---- GET / ----
   describe("GET /", () => {
     it("returns 200 with HTML content", async () => {
-      const res = await fetch(`http://localhost:${server.port}/`);
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/`);
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toContain("text/html");
-    });
+    }, 15000);
 
     it("contains the selftune title", async () => {
-      const res = await fetch(`http://localhost:${server.port}/`);
-      const html = await res.text();
+      const html = await readRootHtml();
       expect(html).toContain("selftune");
     });
 
-    it("sets the live mode flag", async () => {
-      const res = await fetch(`http://localhost:${server.port}/`);
+    it("serves either the SPA shell or the legacy live shell", async () => {
+      const html = await readRootHtml();
+      const isSpa = await servesSpaShell();
+      if (isSpa) {
+        expect(html).toContain("<div id=\"root\"></div>");
+        expect(html).toContain("/assets/");
+      } else {
+        expect(html).toContain("__SELFTUNE_LIVE__");
+      }
+    });
+
+    it("keeps the legacy dashboard available at /legacy/ when SPA is active", async () => {
+      if (!(await servesSpaShell())) return;
+
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/legacy/`);
+      expect(res.status).toBe(200);
       const html = await res.text();
       expect(html).toContain("__SELFTUNE_LIVE__");
     });
@@ -112,13 +147,15 @@ describe("dashboard-server", () => {
   // ---- GET /api/data ----
   describe("GET /api/data", () => {
     it("returns 200 with JSON", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/data`);
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toContain("application/json");
     });
 
     it("returns expected data shape", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/data`);
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
       const data = await res.json();
       expect(data).toHaveProperty("telemetry");
       expect(data).toHaveProperty("skills");
@@ -134,7 +171,8 @@ describe("dashboard-server", () => {
     });
 
     it("includes decisions in the data", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/data`);
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
       const data = await res.json();
       expect(data).toHaveProperty("decisions");
       expect(Array.isArray(data.decisions)).toBe(true);
@@ -144,8 +182,9 @@ describe("dashboard-server", () => {
   // ---- GET /api/events (SSE) ----
   describe("GET /api/events", () => {
     it("returns SSE content type", async () => {
+      const server = await getServer();
       const controller = new AbortController();
-      const res = await fetch(`http://localhost:${server.port}/api/events`, {
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/events`, {
         signal: controller.signal,
       });
       expect(res.status).toBe(200);
@@ -154,10 +193,11 @@ describe("dashboard-server", () => {
     });
 
     it("sends initial data event", async () => {
+      const server = await getServer();
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), 3000);
 
-      const res = await fetch(`http://localhost:${server.port}/api/events`, {
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/events`, {
         signal: controller.signal,
       });
 
@@ -196,7 +236,8 @@ describe("dashboard-server", () => {
   // ---- POST /api/actions/watch ----
   describe("POST /api/actions/watch", () => {
     it("returns JSON response", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/actions/watch`, {
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/watch`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ skill: "test-skill", skillPath: "/tmp/test-skill" }),
@@ -214,7 +255,8 @@ describe("dashboard-server", () => {
   // ---- POST /api/actions/evolve ----
   describe("POST /api/actions/evolve", () => {
     it("returns JSON response", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/actions/evolve`, {
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/evolve`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ skill: "test-skill", skillPath: "/tmp/test-skill" }),
@@ -229,7 +271,8 @@ describe("dashboard-server", () => {
   // ---- POST /api/actions/rollback ----
   describe("POST /api/actions/rollback", () => {
     it("returns JSON response with proposalId validation", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/actions/rollback`, {
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/rollback`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -248,8 +291,9 @@ describe("dashboard-server", () => {
   // ---- GET /api/evaluations/:skillName ----
   describe("GET /api/evaluations/:skillName", () => {
     it("returns 200 with JSON array", async () => {
+      const server = await getServer();
       const res = await fetch(
-        `http://localhost:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
+        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
       );
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toContain("application/json");
@@ -258,8 +302,9 @@ describe("dashboard-server", () => {
     });
 
     it("returns entries with expected shape when data exists", async () => {
+      const server = await getServer();
       const res = await fetch(
-        `http://localhost:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
+        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
       );
       const data = await res.json();
       // May be empty if no skill_usage_log.jsonl entries match, but shape is still an array
@@ -274,8 +319,9 @@ describe("dashboard-server", () => {
     });
 
     it("returns empty array for unknown skill", async () => {
+      const server = await getServer();
       const res = await fetch(
-        `http://localhost:${server.port}/api/evaluations/${encodeURIComponent("nonexistent-skill-xyz")}`,
+        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("nonexistent-skill-xyz")}`,
       );
       expect(res.status).toBe(200);
       const data = await res.json();
@@ -283,8 +329,9 @@ describe("dashboard-server", () => {
     });
 
     it("includes CORS headers", async () => {
+      const server = await getServer();
       const res = await fetch(
-        `http://localhost:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
+        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
       );
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
     });
@@ -292,16 +339,24 @@ describe("dashboard-server", () => {
 
   // ---- 404 for unknown routes ----
   describe("unknown routes", () => {
-    it("returns 404 for unknown paths", async () => {
-      const res = await fetch(`http://localhost:${server.port}/nonexistent`);
-      expect(res.status).toBe(404);
+    it("returns SPA fallback or 404 depending on served mode", async () => {
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/nonexistent`);
+      if (await servesSpaShell()) {
+        expect(res.status).toBe(200);
+        const html = await res.text();
+        expect(html).toContain("<div id=\"root\"></div>");
+      } else {
+        expect(res.status).toBe(404);
+      }
     });
   });
 
   // ---- CORS headers ----
   describe("CORS", () => {
     it("includes CORS headers on API responses", async () => {
-      const res = await fetch(`http://localhost:${server.port}/api/data`);
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
     });
   });
@@ -312,7 +367,7 @@ describe("server lifecycle", () => {
   it("can start and stop cleanly", async () => {
     const s = await startDashboardServer({
       port: 0,
-      host: "localhost",
+      host: "127.0.0.1",
       openBrowser: false,
       dataLoader: () => fakeData,
       statusLoader: () => ({
@@ -328,12 +383,12 @@ describe("server lifecycle", () => {
     expect(typeof s.port).toBe("number");
     expect(s.port).toBeGreaterThan(0);
     s.stop();
-  });
+  }, 30000);
 
   it("exposes port after binding", async () => {
     const s = await startDashboardServer({
       port: 0,
-      host: "localhost",
+      host: "127.0.0.1",
       openBrowser: false,
       dataLoader: () => fakeData,
       statusLoader: () => ({
@@ -345,21 +400,18 @@ describe("server lifecycle", () => {
       }),
     });
     // Verify the server is actually responding
-    const res = await fetch(`http://localhost:${s.port}/api/data`);
+    const res = await fetch(`http://127.0.0.1:${s.port}/api/data`);
     expect(res.status).toBe(200);
     s.stop();
-  });
+  }, 15000);
 });
 
 describe("live shell loading", () => {
-  let server: { server: unknown; stop: () => void; port: number };
-  let dataLoaderCalls = 0;
-
-  beforeAll(async () => {
-    dataLoaderCalls = 0;
-    server = await startDashboardServer({
+  it("serves / without eagerly loading dashboard data", async () => {
+    let dataLoaderCalls = 0;
+    const server = await startDashboardServer({
       port: 0,
-      host: "localhost",
+      host: "127.0.0.1",
       openBrowser: false,
       dataLoader: () => {
         dataLoaderCalls++;
@@ -390,40 +442,38 @@ describe("live shell loading", () => {
         },
       }),
     });
-  });
-
-  afterAll(() => {
-    server?.stop();
-  });
 
-  it("serves / without eagerly loading dashboard data", async () => {
     const callsBefore = dataLoaderCalls;
-    const res = await fetch(`http://localhost:${server.port}/`);
-    const html = await res.text();
-    expect(res.status).toBe(200);
-    expect(html).toContain("__SELFTUNE_LIVE__");
-    expect(html).not.toContain('id="embedded-data"');
-    expect(dataLoaderCalls).toBe(callsBefore);
-  });
-
-  it("loads dashboard data only through /api/data", async () => {
-    const res = await fetch(`http://localhost:${server.port}/api/data`);
-    expect(res.status).toBe(200);
-    expect(dataLoaderCalls).toBe(1);
-  });
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/`);
+      const html = await res.text();
+      expect(res.status).toBe(200);
+      const isSpa = html.includes("<div id=\"root\"></div>") && html.includes("/assets/");
+      if (isSpa) {
+        expect(html).toContain("<div id=\"root\"></div>");
+      } else {
+        expect(html).toContain("__SELFTUNE_LIVE__");
+        expect(html).not.toContain('id="embedded-data"');
+      }
+      expect(dataLoaderCalls).toBe(callsBefore);
+
+      const dataRes = await fetch(`http://127.0.0.1:${server.port}/api/data`);
+      expect(dataRes.status).toBe(200);
+      expect(dataLoaderCalls).toBe(1);
+    } finally {
+      server.stop();
+    }
+  }, 15000);
 });
 
 describe("report loading", () => {
-  let server: { server: unknown; stop: () => void; port: number };
-  let dataLoaderCalls = 0;
-  let evidenceLoaderCalls = 0;
-
-  beforeAll(async () => {
-    dataLoaderCalls = 0;
-    evidenceLoaderCalls = 0;
-    server = await startDashboardServer({
+  it("loads report data without touching the full dashboard loader", async () => {
+    let dataLoaderCalls = 0;
+    let evidenceLoaderCalls = 0;
+
+    const server = await startDashboardServer({
       port: 0,
-      host: "localhost",
+      host: "127.0.0.1",
       openBrowser: false,
       dataLoader: () => {
         dataLoaderCalls++;
@@ -467,16 +517,14 @@ describe("report loading", () => {
         return [];
       },
     });
-  });
-
-  afterAll(() => {
-    server?.stop();
-  });
 
-  it("loads report data without touching the full dashboard loader", async () => {
-    const res = await fetch(`http://localhost:${server.port}/report/test-skill`);
-    expect(res.status).toBe(200);
-    expect(dataLoaderCalls).toBe(0);
-    expect(evidenceLoaderCalls).toBe(1);
-  });
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/report/test-skill`);
+      expect(res.status).toBe(200);
+      expect(dataLoaderCalls).toBe(0);
+      expect(evidenceLoaderCalls).toBe(1);
+    } finally {
+      server.stop();
+    }
+  }, 15000);
 });
diff --git a/tests/orchestrate.test.ts b/tests/orchestrate.test.ts
index fd7a165..ca242da 100644
--- a/tests/orchestrate.test.ts
+++ b/tests/orchestrate.test.ts
@@ -56,8 +56,8 @@ function makeStatusResult(skills: SkillStatus[]): StatusResult {
 }
 
 const baseOptions: OrchestrateOptions = {
-  dryRun: true,
-  autoApprove: false,
+  dryRun: false,
+  approvalMode: "auto",
   maxSkills: 5,
   recentWindowHours: 48,
   syncForce: false,
@@ -204,8 +204,8 @@ describe("orchestrate", () => {
     expect(result.summary.totalSkills).toBe(0);
     expect(result.summary.evaluated).toBe(0);
     expect(result.summary.skipped).toBe(0);
-    expect(result.summary.dryRun).toBe(true);
-    expect(result.summary.autoApprove).toBe(false);
+    expect(result.summary.dryRun).toBe(false);
+    expect(result.summary.approvalMode).toBe("auto");
   });
 
   test("dry-run prevents deployment even when evolve would succeed", async () => {
@@ -233,7 +233,7 @@ describe("orchestrate", () => {
     expect(evolveDryRun).toBe(true);
   });
 
-  test("auto-approve passes dryRun=false to evolve", async () => {
+  test("autonomous mode passes dryRun=false to evolve", async () => {
     let evolveDryRun: boolean | undefined;
     const deps = makeDeps({
       computeStatus: () =>
@@ -254,10 +254,35 @@ describe("orchestrate", () => {
       },
     });
 
-    await orchestrate({ ...baseOptions, dryRun: false, autoApprove: true }, deps);
+    await orchestrate({ ...baseOptions, dryRun: false, approvalMode: "auto" }, deps);
     expect(evolveDryRun).toBe(false);
   });
 
+  test("review-required mode keeps evolve in dry-run", async () => {
+    let evolveDryRun: boolean | undefined;
+    const deps = makeDeps({
+      computeStatus: () =>
+        makeStatusResult([
+          makeSkill({ name: "Skill1", status: "CRITICAL", passRate: 0.2, missedQueries: 5 }),
+        ]),
+      evolve: async (opts) => {
+        evolveDryRun = opts.dryRun;
+        return {
+          proposal: null,
+          validation: null,
+          deployed: false,
+          auditEntries: [],
+          reason: "review required",
+          llmCallCount: 0,
+          elapsedMs: 50,
+        };
+      },
+    });
+
+    await orchestrate({ ...baseOptions, approvalMode: "review" }, deps);
+    expect(evolveDryRun).toBe(true);
+  });
+
   test("skips evolve when skill path cannot be resolved", async () => {
     const deps = makeDeps({
       computeStatus: () =>

From 273bd390a91487648696ee485dabf980948059bc Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:03:56 +0300
Subject: [PATCH 04/14] Remove legacy dashboard runtime

---
 ARCHITECTURE.md                          |    7 +-
 CHANGELOG.md                             |    2 +-
 README.md                                |    2 +-
 ROADMAP.md                               |    2 +-
 apps/local-dashboard/HANDOFF.md          |    9 +-
 apps/local-dashboard/package.json        |    2 +-
 cli/selftune/dashboard-server.ts         |  374 +---
 cli/selftune/dashboard.ts                |  240 +--
 dashboard/index.html                     | 2113 ----------------------
 docs/design-docs/sandbox-claude-code.md  |    2 +-
 docs/design-docs/sandbox-test-harness.md |    2 +-
 docs/escalation-policy.md                |    4 +-
 docs/exec-plans/tech-debt-tracker.md     |    2 +-
 package.json                             |    3 +-
 skill/SKILL.md                           |    6 +-
 skill/Workflows/Dashboard.md             |  202 +--
 tests/dashboard/dashboard-server.test.ts |  458 ++---
 tests/dashboard/dashboard.test.ts        |  112 +-
 tests/sandbox/run-sandbox.ts             |   87 +-
 19 files changed, 391 insertions(+), 3238 deletions(-)
 delete mode 100644 dashboard/index.html

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c080752..af694bc 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -44,8 +44,8 @@ cli/selftune/
 ├── observability.ts      Health checks (doctor command)
 ├── status.ts             Skill health summary (status command)
 ├── last.ts               Last session insight (last command)
-├── dashboard.ts          HTML dashboard builder (dashboard command)
-├── dashboard-server.ts   Live Bun.serve server with SSE (dashboard --serve)
+├── dashboard.ts          Dashboard command entry point (SPA server launcher)
+├── dashboard-server.ts   Bun.serve SPA + v2 API server
 ├── types.ts              Shared interfaces (incl. SelftuneConfig)
 ├── constants.ts          Log paths, config paths, known tools
 ├── utils/                Shared utilities (jsonl, transcript, logging, llm-call, schema-validator, trigger-check)
@@ -100,9 +100,6 @@ apps/local-dashboard/     React SPA dashboard (Vite + TypeScript + shadcn/ui)
 ├── vite.config.ts        Dev proxy → dashboard-server, build to dist/
 └── package.json          React 19, Tailwind v4, shadcn/ui, recharts
 
-dashboard/                Legacy HTML dashboard (served at /legacy/)
-└── index.html            Original embedded-JSON dashboard (v1 endpoints)
-
 templates/                Settings and config templates
 ├── single-skill-settings.json
 ├── multi-skill-settings.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a821bd7..e3215e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   - Onboarding flow: full empty-state guide for first-time users (3-step setup), dismissible welcome banner for returning users (localStorage-persisted)
 - **SQLite v2 API endpoints** — `GET /api/v2/overview` and `GET /api/v2/skills/:name` backed by materialized SQLite queries (`getOverviewPayload()`, `getSkillReportPayload()`, `getSkillsList()`)
 - **SQL query optimizations** — Replaced `NOT IN` subqueries with `LEFT JOIN + IS NULL`, moved JS-side dedup to SQL `GROUP BY`, added `LIMIT 200` to unbounded evidence queries
-- **SPA serving from dashboard server** — Built SPA served at `/`, legacy HTML dashboard moved to `/legacy/`
+- **SPA serving from dashboard server** — Built SPA served at `/` as the supported local dashboard experience
 - **Source-truth-driven pipeline** — Transcripts and rollouts are now the authoritative source; `sync` rebuilds repaired overlays from source data rather than relying solely on hook-time capture
 - **Telemetry contract package** — `@selftune/telemetry-contract` workspace package with canonical schema types, validators, versioning, metadata, and golden fixture tests
 - **Test split** — `make test-fast` / `make test-slow` and `bun run test:fast` / `bun run test:slow` for faster development feedback loop
diff --git a/README.md b/README.md
index 56de090..ab25e5c 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ A continuous feedback loop that makes your skills learn and adapt. Automatically
 - **Per-stage model control** — `--validation-model`, `--proposal-model`, and `--gate-model` flags give fine-grained control over which model runs each evolution stage.
 - **Auto-activation system** — Hooks detect when selftune should run and suggest actions
 - **Enforcement guardrails** — Blocks SKILL.md edits on monitored skills unless `selftune watch` has been run
-- **React SPA dashboard** — `selftune dashboard` serves a React SPA with skill health grid, per-skill drilldown, evidence viewer, evolution timeline, dark/light theming, and SQLite-backed v2 API (legacy dashboard at `/legacy/`)
+- **React SPA dashboard** — `selftune dashboard` serves a React SPA with skill health grid, per-skill drilldown, evidence viewer, evolution timeline, dark/light theming, and SQLite-backed v2 API
 - **Evolution memory** — Persists context, plans, and decisions across context resets
 - **4 specialized agents** — Diagnosis analyst, pattern analyst, evolution reviewer, integration guide
 - **Sandbox test harness** — Comprehensive automated test coverage, including devcontainer-based LLM testing
diff --git a/ROADMAP.md b/ROADMAP.md
index 40abd7c..d4cf915 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -16,7 +16,7 @@
   - Per-skill drilldown with evidence viewer, evolution timeline
   - SQLite v2 API endpoints (`/api/v2/overview`, `/api/v2/skills/:name`)
   - Dark/light theme toggle with selftune branding
-  - SPA served at `/`, legacy HTML dashboard at `/legacy/`
+  - SPA served at `/` as the supported local dashboard
 
 ## In Progress
 - Multi-agent sandbox expansion
diff --git a/apps/local-dashboard/HANDOFF.md b/apps/local-dashboard/HANDOFF.md
index 6312396..e5f6ae8 100644
--- a/apps/local-dashboard/HANDOFF.md
+++ b/apps/local-dashboard/HANDOFF.md
@@ -35,7 +35,7 @@ bun run dev
 
 # Or run manually:
 # Terminal 1: Start the dashboard server
-selftune dashboard --port 7888
+selftune dashboard --port 7888 --no-open
 
 # Terminal 2: Start the SPA dev server (proxies /api to port 7888)
 cd apps/local-dashboard
@@ -47,7 +47,7 @@ bunx vite
 ## What was rebased / changed
 
 - **SPA types**: Rewritten to match `queries.ts` payload shapes (`OverviewResponse`, `SkillReportResponse`, `SkillSummary`, `EvidenceEntry`)
-- **API layer**: Now calls `/api/v2/overview` and `/api/v2/skills/:name` instead of `/api/data` + `/api/evaluations/:name`
+- **API layer**: Calls `/api/v2/overview` and `/api/v2/skills/:name`
 - **SSE removed**: Replaced with 15s polling (SQLite reads are cheap, SSE was complex)
 - **Overview page**: Uses `SkillSummary[]` from `getSkillsList()` for skill cards (pre-aggregated pass rate, check count, sessions)
 - **Skill report page**: Single fetch to v2 endpoint instead of parallel overview + evaluations fetch. Shows evidence entries, evolution audit history per skill
@@ -67,13 +67,12 @@ bunx vite
 
 ## What still depends on old dashboard code
 
-- The old v1 endpoints (`/api/data`, `/api/events`, `/api/evaluations/:name`) still work and are used by the legacy `dashboard/index.html`
-- Badge endpoints (`/badge/:name`) and report HTML endpoints (`/report/:name`) use the old `computeStatus` + JSONL reader path
+- Badge endpoints (`/badge/:name`) and report HTML endpoints (`/report/:name`) still use the status/evidence JSONL path rather than SQLite-backed view models
 - Action endpoints (`/api/actions/*`) are unchanged
 
 ## What remains before this can become default
 
-1. ~~**Serve built SPA from dashboard-server**~~: Done — `/` serves SPA, old dashboard at `/legacy/`
+1. ~~**Serve built SPA from dashboard-server**~~: Done — `/` serves the SPA
 2. ~~**Production build**~~: Done — `bun run build:dashboard` in root package.json
 3. **Regression detection**: The SQLite layer doesn't compute regression detection yet — `deriveStatus()` currently only uses pass rate + check count. Add a `regression_detected` column to skill summaries when the monitoring snapshot computation moves to SQLite.
 4. **Monitoring snapshot migration**: Move `computeMonitoringSnapshot()` logic into the SQLite materializer or a query helper (window sessions, false negative rate, baseline comparison)
diff --git a/apps/local-dashboard/package.json b/apps/local-dashboard/package.json
index 06931d8..a6520ec 100644
--- a/apps/local-dashboard/package.json
+++ b/apps/local-dashboard/package.json
@@ -4,7 +4,7 @@
   "version": "0.1.0",
   "type": "module",
   "scripts": {
-    "dev": "concurrently \"cd ../.. && bun run cli/selftune/index.ts dashboard --serve --port 7888\" \"vite\"",
+    "dev": "concurrently \"cd ../.. && bun run cli/selftune/index.ts dashboard --port 7888 --no-open\" \"vite\"",
     "build": "vite build",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit"
diff --git a/cli/selftune/dashboard-server.ts b/cli/selftune/dashboard-server.ts
index bcbc97c..fef2c4f 100644
--- a/cli/selftune/dashboard-server.ts
+++ b/cli/selftune/dashboard-server.ts
@@ -1,16 +1,16 @@
 /**
- * selftune dashboard server — Live Bun.serve HTTP server with SSE, data API,
- * and action endpoints for the interactive dashboard.
+ * selftune dashboard server — Bun.serve HTTP server for the SPA dashboard,
+ * skill report HTML, badges, and action endpoints.
  *
  * Endpoints:
- *   GET  /              — Serve dashboard HTML shell + live mode flag
- *   GET  /api/data      — JSON endpoint returning current telemetry data
- *   GET  /api/events    — SSE stream sending data updates every 5 seconds
+ *   GET  /                     — Serve dashboard SPA shell
+ *   GET  /api/v2/overview      — SQLite-backed overview payload
+ *   GET  /api/v2/skills/:name  — SQLite-backed per-skill report
  *   POST /api/actions/watch    — Trigger `selftune watch` for a skill
  *   POST /api/actions/evolve   — Trigger `selftune evolve` for a skill
  *   POST /api/actions/rollback — Trigger `selftune rollback` for a skill
- *   GET  /api/v2/overview     — SQLite-backed overview payload
- *   GET  /api/v2/skills/:name — SQLite-backed per-skill report
+ *   GET  /badge/:name          — Skill health badge
+ *   GET  /report/:name         — Skill health report HTML
  */
 
 import type { Database } from "bun:sqlite";
@@ -21,7 +21,7 @@ import { findSkillBadgeData } from "./badge/badge-data.js";
 import type { BadgeFormat } from "./badge/badge-svg.js";
 import { formatBadgeOutput, renderBadgeSvg } from "./badge/badge-svg.js";
 import { EVOLUTION_AUDIT_LOG, QUERY_LOG, TELEMETRY_LOG } from "./constants.js";
-import { getLastDeployedProposal } from "./evolution/audit.js";
+import type { OverviewResponse, SkillReportResponse } from "./dashboard-contract.js";
 import { readEvidenceTrail } from "./evolution/evidence.js";
 import { openDb } from "./localdb/db.js";
 import { materializeIncremental } from "./localdb/materialize.js";
@@ -31,37 +31,29 @@ import {
   getSkillReportPayload,
   getSkillsList,
 } from "./localdb/queries.js";
-import { readDecisions } from "./memory/writer.js";
-import { computeMonitoringSnapshot } from "./monitoring/watch.js";
 import { doctor } from "./observability.js";
 import type { StatusResult } from "./status.js";
-import { computeStatus, DEFAULT_WINDOW_SESSIONS } from "./status.js";
+import { computeStatus } from "./status.js";
 import type {
   EvolutionAuditEntry,
   EvolutionEvidenceEntry,
   QueryLogRecord,
   SessionTelemetryRecord,
-  SkillUsageRecord,
 } from "./types.js";
 import { readJsonl } from "./utils/jsonl.js";
-import {
-  filterActionableQueryRecords,
-  filterActionableSkillUsageRecords,
-} from "./utils/query-filter.js";
 import { readEffectiveSkillUsageRecords } from "./utils/skill-log.js";
 
 export interface DashboardServerOptions {
   port?: number;
   host?: string;
   openBrowser?: boolean;
-  dataLoader?: () => DashboardData;
   statusLoader?: () => StatusResult;
   evidenceLoader?: () => EvolutionEvidenceEntry[];
+  overviewLoader?: () => OverviewResponse;
+  skillReportLoader?: (skillName: string) => SkillReportResponse | null;
   actionRunner?: typeof runAction;
 }
 
-const LIVE_CACHE_TTL_MS = 30_000;
-
 /** Read selftune version from package.json once at startup */
 let selftuneVersion = "unknown";
 try {
@@ -71,60 +63,6 @@ try {
   // fallback already set
 }
 
-interface DashboardData {
-  telemetry: SessionTelemetryRecord[];
-  skills: SkillUsageRecord[];
-  queries: QueryLogRecord[];
-  evolution: EvolutionAuditEntry[];
-  evidence: EvolutionEvidenceEntry[];
-  decisions: import("./types.js").DecisionRecord[];
-  computed: {
-    snapshots: Record<string, ReturnType<typeof computeMonitoringSnapshot>>;
-    unmatched: Array<{ timestamp: string; session_id: string; query: string }>;
-    pendingProposals: EvolutionAuditEntry[];
-  };
-}
-
-interface LiveDashboardPayload {
-  telemetry: Array<
-    Pick<
-      SessionTelemetryRecord,
-      "timestamp" | "session_id" | "skills_triggered" | "errors_encountered" | "total_tool_calls"
-    >
-  >;
-  skills: Array<
-    Pick<
-      SkillUsageRecord,
-      "timestamp" | "session_id" | "skill_name" | "skill_path" | "query" | "triggered" | "source"
-    >
-  >;
-  queries: Array<Pick<QueryLogRecord, never>>;
-  evolution: Array<Pick<EvolutionAuditEntry, "timestamp" | "proposal_id" | "action" | "details">>;
-  evidence: Array<Pick<EvolutionEvidenceEntry, never>>;
-  decisions: DashboardData["decisions"];
-  computed: DashboardData["computed"] & { unmatched_count: number };
-  counts: {
-    telemetry: number;
-    skills: number;
-    queries: number;
-    evolution: number;
-    evidence: number;
-    decisions: number;
-  };
-}
-
-function findViewerHTML(): string {
-  const candidates = [
-    join(dirname(import.meta.dir), "..", "dashboard", "index.html"),
-    join(dirname(import.meta.dir), "dashboard", "index.html"),
-    resolve("dashboard", "index.html"),
-  ];
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
-  }
-  throw new Error("Could not find dashboard/index.html. Ensure it exists in the selftune repo.");
-}
-
 function findSpaDir(): string | null {
   const candidates = [
     join(dirname(import.meta.dir), "..", "apps", "local-dashboard", "dist"),
@@ -150,73 +88,6 @@ const MIME_TYPES: Record<string, string> = {
   ".ico": "image/x-icon",
 };
 
-function collectData(): DashboardData {
-  const telemetry = readJsonl<SessionTelemetryRecord>(TELEMETRY_LOG);
-  const skills = filterActionableSkillUsageRecords(readEffectiveSkillUsageRecords());
-  const queries = readJsonl<QueryLogRecord>(QUERY_LOG);
-  const actionableQueries = filterActionableQueryRecords(queries);
-  const evolution = readJsonl<EvolutionAuditEntry>(EVOLUTION_AUDIT_LOG);
-  const evidence = readEvidenceTrail();
-  const decisions = readDecisions();
-
-  // Compute per-skill monitoring snapshots
-  const skillNames = [...new Set(skills.map((r) => r.skill_name))];
-  const snapshots: Record<string, ReturnType<typeof computeMonitoringSnapshot>> = {};
-  for (const name of skillNames) {
-    const lastDeployed = getLastDeployedProposal(name);
-    const baselinePassRate = lastDeployed?.eval_snapshot?.pass_rate ?? 0.5;
-    snapshots[name] = computeMonitoringSnapshot(
-      name,
-      telemetry,
-      skills,
-      actionableQueries,
-      DEFAULT_WINDOW_SESSIONS,
-      baselinePassRate,
-    );
-  }
-
-  // Compute unmatched queries
-  const triggeredQueries = new Set(
-    skills
-      .filter((r) => r.triggered && typeof r.query === "string")
-      .map((r) => r.query.toLowerCase().trim()),
-  );
-  const unmatched = actionableQueries
-    .filter((q) => !triggeredQueries.has(q.query.toLowerCase().trim()))
-    .map((q) => ({
-      timestamp: q.timestamp,
-      session_id: q.session_id,
-      query: q.query,
-    }));
-
-  // Compute pending proposals (reuse already-loaded evolution entries)
-  const proposalStatus: Record<string, string[]> = {};
-  for (const e of evolution) {
-    if (!proposalStatus[e.proposal_id]) proposalStatus[e.proposal_id] = [];
-    proposalStatus[e.proposal_id].push(e.action);
-  }
-  const terminalActions = new Set(["deployed", "rejected", "rolled_back"]);
-  const seenProposals = new Set<string>();
-  const pendingProposals = evolution.filter((e) => {
-    if (e.action !== "created" && e.action !== "validated") return false;
-    if (seenProposals.has(e.proposal_id)) return false;
-    const actions = proposalStatus[e.proposal_id] || [];
-    const isPending = !actions.some((a: string) => terminalActions.has(a));
-    if (isPending) seenProposals.add(e.proposal_id);
-    return isPending;
-  });
-
-  return {
-    telemetry,
-    skills,
-    queries: actionableQueries,
-    evolution,
-    evidence,
-    decisions,
-    computed: { snapshots, unmatched, pendingProposals },
-  };
-}
-
 function computeStatusFromLogs(): StatusResult {
   const telemetry = readJsonl<SessionTelemetryRecord>(TELEMETRY_LOG);
   const skillRecords = readEffectiveSkillUsageRecords();
@@ -226,56 +97,6 @@ function computeStatusFromLogs(): StatusResult {
   return computeStatus(telemetry, skillRecords, queryRecords, auditEntries, doctorResult);
 }
 
-function buildLivePayload(data: DashboardData): LiveDashboardPayload {
-  return {
-    telemetry: data.telemetry.map((record) => ({
-      timestamp: record.timestamp,
-      session_id: record.session_id,
-      skills_triggered: record.skills_triggered,
-      errors_encountered: record.errors_encountered,
-      total_tool_calls: record.total_tool_calls,
-    })),
-    skills: data.skills.map((record) => ({
-      timestamp: record.timestamp,
-      session_id: record.session_id,
-      skill_name: record.skill_name,
-      skill_path: record.skill_path,
-      query: record.query,
-      triggered: record.triggered,
-      source: record.source,
-    })),
-    queries: [],
-    evolution: data.evolution.map((record) => ({
-      timestamp: record.timestamp,
-      proposal_id: record.proposal_id,
-      action: record.action,
-      details: record.details,
-    })),
-    evidence: [],
-    decisions: data.decisions,
-    computed: {
-      ...data.computed,
-      unmatched: data.computed.unmatched.slice(0, 500),
-      unmatched_count: data.computed.unmatched.length,
-    },
-    counts: {
-      telemetry: data.telemetry.length,
-      skills: data.skills.length,
-      queries: data.queries.length,
-      evolution: data.evolution.length,
-      evidence: data.evidence.length,
-      decisions: data.decisions.length,
-    },
-  };
-}
-
-function buildLiveHTML(): string {
-  const template = readFileSync(findViewerHTML(), "utf-8");
-  const liveFlag = "<script>window.__SELFTUNE_LIVE__ = true;</script>";
-
-  return template.replace("</body>", `${liveFlag}\n</body>`);
-}
-
 interface MergedEvidenceEntry {
   proposal_id: string;
   target: string;
@@ -584,9 +405,10 @@ export async function startDashboardServer(
   const port = options?.port ?? 3141;
   const hostname = options?.host ?? "localhost";
   const openBrowser = options?.openBrowser ?? true;
-  const getDashboardData = options?.dataLoader ?? collectData;
   const getStatusResult = options?.statusLoader ?? computeStatusFromLogs;
   const getEvidenceEntries = options?.evidenceLoader ?? readEvidenceTrail;
+  const getOverviewResponse = options?.overviewLoader;
+  const getSkillReportResponse = options?.skillReportLoader;
   const executeAction = options?.actionRunner ?? runAction;
 
   // -- SPA serving -------------------------------------------------------------
@@ -594,21 +416,26 @@ export async function startDashboardServer(
   if (spaDir) {
     console.log(`SPA found at ${spaDir}, serving as default dashboard`);
   } else {
-    console.log("SPA build not found, serving legacy dashboard at /");
+    console.warn(
+      "SPA build not found. Run `bun run build:dashboard` before using `selftune dashboard`.",
+    );
   }
 
   // -- SQLite v2 data layer ---------------------------------------------------
   let db: Database | null = null;
   let lastV2MaterializedAt = 0;
   let lastV2RefreshAttemptAt = 0;
-  try {
-    db = openDb();
-    materializeIncremental(db);
-    lastV2MaterializedAt = Date.now();
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`V2 dashboard data unavailable: ${message}`);
-    // Continue serving; refreshV2Data will retry on demand.
+  const needsDb = !getOverviewResponse || !getSkillReportResponse;
+  if (needsDb) {
+    try {
+      db = openDb();
+      materializeIncremental(db);
+      lastV2MaterializedAt = Date.now();
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`V2 dashboard data unavailable: ${message}`);
+      // Continue serving; refreshV2Data will retry on demand.
+    }
   }
   const V2_MATERIALIZE_TTL_MS = 15_000;
 
@@ -628,38 +455,15 @@ export async function startDashboardServer(
     }
   }
 
-  const sseClients = new Set<ReadableStreamDefaultController>();
-  let cachedDashboardData: DashboardData | null = null;
-  let cachedLivePayload: LiveDashboardPayload | null = null;
   let cachedStatusResult: StatusResult | null = null;
-  let lastDataCacheRefreshAt = 0;
   let lastStatusCacheRefreshAt = 0;
-  let dataRefreshPromise: Promise<void> | null = null;
   let statusRefreshPromise: Promise<void> | null = null;
 
-  async function refreshLiveCache(force = false): Promise<void> {
-    const cacheIsFresh =
-      cachedDashboardData !== null && Date.now() - lastDataCacheRefreshAt < LIVE_CACHE_TTL_MS;
-    if (!force && cacheIsFresh) return;
-    if (dataRefreshPromise) return dataRefreshPromise;
-
-    dataRefreshPromise = (async () => {
-      const data = getDashboardData();
-      cachedDashboardData = data;
-      cachedLivePayload = buildLivePayload(data);
-      lastDataCacheRefreshAt = Date.now();
-    })();
-
-    try {
-      await dataRefreshPromise;
-    } finally {
-      dataRefreshPromise = null;
-    }
-  }
+  const STATUS_CACHE_TTL_MS = 30_000;
 
   async function refreshStatusCache(force = false): Promise<void> {
     const cacheIsFresh =
-      cachedStatusResult !== null && Date.now() - lastStatusCacheRefreshAt < LIVE_CACHE_TTL_MS;
+      cachedStatusResult !== null && Date.now() - lastStatusCacheRefreshAt < STATUS_CACHE_TTL_MS;
     if (!force && cacheIsFresh) return;
     if (statusRefreshPromise) return statusRefreshPromise;
 
@@ -675,15 +479,6 @@ export async function startDashboardServer(
     }
   }
 
-  async function getCachedLivePayload(): Promise<LiveDashboardPayload> {
-    if (!cachedLivePayload) {
-      await refreshLiveCache(true);
-    } else {
-      void refreshLiveCache(false);
-    }
-    return cachedLivePayload as LiveDashboardPayload;
-  }
-
   async function getCachedStatusResult(): Promise<StatusResult> {
     if (!cachedStatusResult) {
       await refreshStatusCache(true);
@@ -726,7 +521,7 @@ export async function startDashboardServer(
         return new Response("Not Found", { status: 404, headers: corsHeaders() });
       }
 
-      // ---- GET / ---- Serve SPA (or legacy fallback)
+      // ---- GET / ---- Serve SPA shell
       if (url.pathname === "/" && req.method === "GET") {
         if (spaDir) {
           const html = await Bun.file(join(spaDir, "index.html")).text();
@@ -734,72 +529,9 @@ export async function startDashboardServer(
             headers: { "Content-Type": "text/html; charset=utf-8", ...corsHeaders() },
           });
         }
-        const html = buildLiveHTML();
-        return new Response(html, {
-          headers: { "Content-Type": "text/html; charset=utf-8", ...corsHeaders() },
-        });
-      }
-
-      // ---- GET /legacy/ ---- Serve old dashboard HTML
-      if (url.pathname === "/legacy/" && req.method === "GET") {
-        const html = buildLiveHTML();
-        return new Response(html, {
-          headers: { "Content-Type": "text/html; charset=utf-8", ...corsHeaders() },
-        });
-      }
-
-      // ---- GET /api/data ---- JSON data endpoint
-      if (url.pathname === "/api/data" && req.method === "GET") {
-        const payload = await getCachedLivePayload();
-        return Response.json(payload, { headers: corsHeaders() });
-      }
-
-      // ---- GET /api/events ---- SSE stream
-      if (url.pathname === "/api/events" && req.method === "GET") {
-        const stream = new ReadableStream({
-          async start(controller) {
-            sseClients.add(controller);
-
-            // Send initial data immediately
-            const initialPayload = await getCachedLivePayload();
-            const payload = `event: data\ndata: ${JSON.stringify(initialPayload)}\n\n`;
-            controller.enqueue(new TextEncoder().encode(payload));
-
-            // Set up periodic updates every 5 seconds
-            const interval = setInterval(async () => {
-              try {
-                const freshPayload = await getCachedLivePayload();
-                const msg = `event: data\ndata: ${JSON.stringify(freshPayload)}\n\n`;
-                controller.enqueue(new TextEncoder().encode(msg));
-              } catch {
-                clearInterval(interval);
-                sseClients.delete(controller);
-              }
-            }, 5000);
-
-            // Clean up when client disconnects
-            req.signal.addEventListener("abort", () => {
-              clearInterval(interval);
-              sseClients.delete(controller);
-              try {
-                controller.close();
-              } catch {
-                // already closed
-              }
-            });
-          },
-          cancel() {
-            // Stream cancelled by client
-          },
-        });
-
-        return new Response(stream, {
-          headers: {
-            "Content-Type": "text/event-stream",
-            "Cache-Control": "no-cache",
-            Connection: "keep-alive",
-            ...corsHeaders(),
-          },
+        return new Response("Dashboard build not found. Run `bun run build:dashboard` first.", {
+          status: 503,
+          headers: { "Content-Type": "text/plain; charset=utf-8", ...corsHeaders() },
         });
       }
 
@@ -946,25 +678,11 @@ export async function startDashboardServer(
         });
       }
 
-      // ---- GET /api/evaluations/:skillName ----
-      if (url.pathname.startsWith("/api/evaluations/") && req.method === "GET") {
-        const skillName = decodeURIComponent(url.pathname.slice("/api/evaluations/".length));
-        const skills = readEffectiveSkillUsageRecords();
-        const filtered = skills
-          .filter((r) => r.skill_name === skillName)
-          .map((r) => ({
-            timestamp: r.timestamp,
-            session_id: r.session_id,
-            query: r.query,
-            skill_name: r.skill_name,
-            triggered: r.triggered,
-            source: r.source ?? null,
-          }));
-        return Response.json(filtered, { headers: corsHeaders() });
-      }
-
       // ---- GET /api/v2/overview ---- SQLite-backed overview
       if (url.pathname === "/api/v2/overview" && req.method === "GET") {
+        if (getOverviewResponse) {
+          return Response.json(getOverviewResponse(), { headers: corsHeaders() });
+        }
         if (!db) {
           return Response.json(
             { error: "V2 data unavailable" },
@@ -982,13 +700,23 @@ export async function startDashboardServer(
 
       // ---- GET /api/v2/skills/:name ---- SQLite-backed skill report
       if (url.pathname.startsWith("/api/v2/skills/") && req.method === "GET") {
+        const skillName = decodeURIComponent(url.pathname.slice("/api/v2/skills/".length));
+        if (getSkillReportResponse) {
+          const report = getSkillReportResponse(skillName);
+          if (!report) {
+            return Response.json(
+              { error: "Skill not found" },
+              { status: 404, headers: corsHeaders() },
+            );
+          }
+          return Response.json(report, { headers: corsHeaders() });
+        }
         if (!db) {
           return Response.json(
             { error: "V2 data unavailable" },
             { status: 503, headers: corsHeaders() },
           );
         }
-        const skillName = decodeURIComponent(url.pathname.slice("/api/v2/skills/".length));
         refreshV2Data();
         const report = getSkillReportPayload(db, skillName);
 
@@ -1187,14 +915,6 @@ export async function startDashboardServer(
 
   // Graceful shutdown
   const shutdownHandler = () => {
-    for (const client of sseClients) {
-      try {
-        client.close();
-      } catch {
-        // already closed
-      }
-    }
-    sseClients.clear();
     db?.close();
     server.stop();
   };
diff --git a/cli/selftune/dashboard.ts b/cli/selftune/dashboard.ts
index aedc5c1..80ac299 100644
--- a/cli/selftune/dashboard.ts
+++ b/cli/selftune/dashboard.ts
@@ -1,136 +1,12 @@
 /**
- * selftune dashboard — Exports JSONL data into a standalone HTML viewer.
+ * selftune dashboard — Start the local React SPA dashboard server.
  *
  * Usage:
- *   selftune dashboard              — Open dashboard in default browser
- *   selftune dashboard --export     — Export data-embedded HTML to stdout
- *   selftune dashboard --out FILE   — Write data-embedded HTML to FILE
- *   selftune dashboard --serve      — Start live dashboard server (default port 3141)
- *   selftune dashboard --serve --port 8080 — Start on custom port
+ *   selftune dashboard              — Start server on port 3141 and open browser
+ *   selftune dashboard --port 8080  — Start on custom port
+ *   selftune dashboard --serve      — Deprecated alias for the default behavior
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { EVOLUTION_AUDIT_LOG, QUERY_LOG, SKILL_LOG, TELEMETRY_LOG } from "./constants.js";
-import { getLastDeployedProposal, readAuditTrail } from "./evolution/audit.js";
-import { readEvidenceTrail } from "./evolution/evidence.js";
-import { computeMonitoringSnapshot } from "./monitoring/watch.js";
-import { DEFAULT_WINDOW_SESSIONS } from "./status.js";
-import type { EvolutionAuditEntry, QueryLogRecord, SessionTelemetryRecord } from "./types.js";
-import { escapeJsonForHtmlScript } from "./utils/html.js";
-import { readJsonl } from "./utils/jsonl.js";
-import {
-  filterActionableQueryRecords,
-  filterActionableSkillUsageRecords,
-} from "./utils/query-filter.js";
-import { readEffectiveSkillUsageRecords } from "./utils/skill-log.js";
-
-function findViewerHTML(): string {
-  // Try relative to this module first (works for both dev and installed)
-  const candidates = [
-    join(dirname(import.meta.dir), "..", "dashboard", "index.html"),
-    join(dirname(import.meta.dir), "dashboard", "index.html"),
-    resolve("dashboard", "index.html"),
-  ];
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
-  }
-  throw new Error("Could not find dashboard/index.html. Ensure it exists in the selftune repo.");
-}
-
-function buildEmbeddedHTML(): string {
-  const template = readFileSync(findViewerHTML(), "utf-8");
-
-  const telemetry = readJsonl<SessionTelemetryRecord>(TELEMETRY_LOG);
-  const skills = filterActionableSkillUsageRecords(readEffectiveSkillUsageRecords());
-  const queries = readJsonl<QueryLogRecord>(QUERY_LOG);
-  const actionableQueries = filterActionableQueryRecords(queries);
-  const evolution = readJsonl<EvolutionAuditEntry>(EVOLUTION_AUDIT_LOG);
-  const evidence = readEvidenceTrail();
-
-  const totalRecords =
-    telemetry.length + skills.length + actionableQueries.length + evolution.length;
-
-  if (totalRecords === 0) {
-    console.error("No log data found. Run some sessions first.");
-    console.error(`  Checked: ${TELEMETRY_LOG}`);
-    console.error(`           ${SKILL_LOG}`);
-    console.error(`           ${QUERY_LOG}`);
-    console.error(`           ${EVOLUTION_AUDIT_LOG}`);
-    process.exit(1);
-  }
-
-  // Compute per-skill monitoring snapshots
-  const skillNames = [...new Set(skills.map((r) => r.skill_name))];
-  const snapshots: Record<string, ReturnType<typeof computeMonitoringSnapshot>> = {};
-  for (const name of skillNames) {
-    const lastDeployed = getLastDeployedProposal(name);
-    const baselinePassRate = lastDeployed?.eval_snapshot?.pass_rate ?? 0.5;
-    snapshots[name] = computeMonitoringSnapshot(
-      name,
-      telemetry,
-      skills,
-      actionableQueries,
-      DEFAULT_WINDOW_SESSIONS,
-      baselinePassRate,
-    );
-  }
-
-  // Compute unmatched queries
-  const triggeredQueries = new Set(
-    skills
-      .filter((r) => r.triggered && typeof r.query === "string")
-      .map((r) => r.query.toLowerCase().trim()),
-  );
-  const unmatched = actionableQueries
-    .filter((q) => !triggeredQueries.has(q.query.toLowerCase().trim()))
-    .map((q) => ({
-      timestamp: q.timestamp,
-      session_id: q.session_id,
-      query: q.query,
-    }));
-
-  // Compute pending proposals
-  const auditTrail = readAuditTrail();
-  const proposalStatus: Record<string, string[]> = {};
-  for (const e of auditTrail) {
-    if (!proposalStatus[e.proposal_id]) proposalStatus[e.proposal_id] = [];
-    proposalStatus[e.proposal_id].push(e.action);
-  }
-  // Deduplicate by proposal_id: one entry per pending proposal
-  const terminalActions = new Set(["deployed", "rejected", "rolled_back"]);
-  const seenProposals = new Set<string>();
-  const pendingProposals = auditTrail.filter((e) => {
-    if (e.action !== "created" && e.action !== "validated") return false;
-    if (seenProposals.has(e.proposal_id)) return false;
-    const actions = proposalStatus[e.proposal_id] || [];
-    const isPending = !actions.some((a: string) => terminalActions.has(a));
-    if (isPending) seenProposals.add(e.proposal_id);
-    return isPending;
-  });
-
-  const data = {
-    telemetry,
-    skills,
-    queries: actionableQueries,
-    evolution,
-    evidence,
-    computed: {
-      snapshots,
-      unmatched,
-      pendingProposals,
-    },
-  };
-
-  // Inject embedded data right before </body>
-  // Escape the full JSON payload for safe embedding inside a script tag.
-  const safeJson = escapeJsonForHtmlScript(data);
-  const encodedJson = Buffer.from(safeJson, "utf8").toString("base64");
-  const dataScript = `<script id="embedded-data" type="application/json" data-encoding="base64">${encodedJson}</script>`;
-  return template.replace("</body>", `${dataScript}\n</body>`);
-}
-
 export async function cliMain(): Promise<void> {
   const args = process.argv.slice(2);
 
@@ -138,84 +14,50 @@ export async function cliMain(): Promise<void> {
     console.log(`selftune dashboard — Visual data dashboard
 
 Usage:
-  selftune dashboard                        Open dashboard in default browser
-  selftune dashboard --export               Export data-embedded HTML to stdout
-  selftune dashboard --out FILE             Write data-embedded HTML to FILE
-  selftune dashboard --serve                Start live dashboard server (port 3141)
-  selftune dashboard --serve --port 8080    Start on custom port`);
+  selftune dashboard                      Start dashboard server (port 3141)
+  selftune dashboard --port 8080          Start on custom port
+  selftune dashboard --serve              Deprecated alias for default behavior
+  selftune dashboard --no-open            Start server without opening browser`);
     process.exit(0);
   }
 
-  if (args.includes("--serve")) {
-    const portIdx = args.indexOf("--port");
-    let port: number | undefined;
-    if (portIdx !== -1) {
-      const parsed = Number.parseInt(args[portIdx + 1], 10);
-      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
-        console.error(
-          `Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`,
-        );
-        process.exit(1);
-      }
-      port = parsed;
-    }
-    const { startDashboardServer } = await import("./dashboard-server.js");
-    const { stop } = await startDashboardServer({ port, openBrowser: true });
-    await new Promise<void>((resolve) => {
-      let closed = false;
-      const keepAlive = setInterval(() => {}, 1 << 30);
-      const shutdown = () => {
-        if (closed) return;
-        closed = true;
-        clearInterval(keepAlive);
-        stop();
-        resolve();
-      };
-      process.on("SIGINT", shutdown);
-      process.on("SIGTERM", shutdown);
-    });
-    return;
-  }
-
-  if (args.includes("--export")) {
-    process.stdout.write(buildEmbeddedHTML());
-    return;
+  if (args.includes("--export") || args.includes("--out")) {
+    console.error("Legacy dashboard export was removed.");
+    console.error(
+      "Use `selftune dashboard` to run the SPA locally, then share a route or screenshot instead.",
+    );
+    process.exit(1);
   }
 
-  const outIdx = args.indexOf("--out");
-  if (outIdx !== -1) {
-    const outPath = args[outIdx + 1];
-    if (!outPath) {
-      console.error("--out requires a file path argument");
+  const portIdx = args.indexOf("--port");
+  let port: number | undefined;
+  if (portIdx !== -1) {
+    const parsed = Number.parseInt(args[portIdx + 1], 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      console.error(`Invalid port "${args[portIdx + 1]}": must be an integer between 1 and 65535.`);
       process.exit(1);
     }
-    const html = buildEmbeddedHTML();
-    writeFileSync(outPath, html, "utf-8");
-    console.log(`Dashboard written to ${outPath}`);
-    return;
-  }
-
-  // Default: write to temp file and open in browser
-  const tmpDir = join(homedir(), ".selftune");
-  if (!existsSync(tmpDir)) {
-    mkdirSync(tmpDir, { recursive: true });
+    port = parsed;
   }
-  const tmpPath = join(tmpDir, "dashboard.html");
-  const html = buildEmbeddedHTML();
-  writeFileSync(tmpPath, html, "utf-8");
 
-  console.log(`Dashboard saved to ${tmpPath}`);
-  console.log("Opening in browser...");
-
-  try {
-    const platform = process.platform;
-    const cmd = platform === "darwin" ? "open" : platform === "linux" ? "xdg-open" : null;
-    if (!cmd) throw new Error("Unsupported platform");
-    const proc = Bun.spawn([cmd, tmpPath], { stdio: ["ignore", "ignore", "ignore"] });
-    await proc.exited;
-    if (proc.exitCode !== 0) throw new Error(`Failed to launch ${cmd}`);
-  } catch {
-    console.log(`Open manually: file://${tmpPath}`);
-  }
-  process.exit(0);
+  if (args.includes("--serve")) {
+    console.warn("`selftune dashboard --serve` is deprecated; use `selftune dashboard` instead.");
+  }
+
+  const openBrowser = !args.includes("--no-open");
+  const { startDashboardServer } = await import("./dashboard-server.js");
+  const { stop } = await startDashboardServer({ port, openBrowser });
+  await new Promise<void>((resolve) => {
+    let closed = false;
+    const keepAlive = setInterval(() => {}, 1 << 30);
+    const shutdown = () => {
+      if (closed) return;
+      closed = true;
+      clearInterval(keepAlive);
+      stop();
+      resolve();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
 }
diff --git a/dashboard/index.html b/dashboard/index.html
deleted file mode 100644
index 15af075..0000000
--- a/dashboard/index.html
+++ /dev/null
@@ -1,2113 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>selftune — Dashboard</title>
-  <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.7/dist/chart.umd.min.js"></script>
-  <style>
-    :root {
-      --bg: #f8fafc;
-      --surface: #ffffff;
-      --surface-muted: #f8fafc;
-      --border: #e2e8f0;
-      --text: #0f172a;
-      --text-muted: #64748b;
-      --text-soft: #94a3b8;
-      --blue: #2563eb;
-      --blue-bg: #dbeafe;
-      --green: #059669;
-      --green-bg: #d1fae5;
-      --amber: #d97706;
-      --amber-bg: #fef3c7;
-      --red: #dc2626;
-      --red-bg: #fee2e2;
-      --slate-bg: #e2e8f0;
-      --radius: 16px;
-      --radius-sm: 12px;
-      --shadow: 0 1px 2px rgba(15, 23, 42, 0.05);
-      --mono: "SF Mono", SFMono-Regular, Consolas, "Liberation Mono", Menlo, monospace;
-      --font-sans: "Avenir Next", "Segoe UI", "Helvetica Neue", sans-serif;
-    }
-
-    * { box-sizing: border-box; margin: 0; padding: 0; }
-
-    html { scroll-behavior: smooth; }
-
-    body {
-      min-height: 100vh;
-      background: var(--bg);
-      color: var(--text);
-      font-family: var(--font-sans);
-      display: flex;
-      flex-direction: column;
-    }
-
-    .header {
-      position: sticky;
-      top: 0;
-      z-index: 10;
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      gap: 1rem;
-      padding: 1rem 1.5rem;
-      background: rgba(248, 250, 252, 0.94);
-      backdrop-filter: blur(12px);
-      border-bottom: 1px solid var(--border);
-    }
-    .header-left { display: flex; align-items: center; gap: 0.9rem; }
-    .header h1 {
-      font-size: 1.2rem;
-      font-weight: 700;
-      letter-spacing: -0.03em;
-    }
-    .header h1 span { color: var(--blue); }
-    .header .version {
-      padding: 0.18rem 0.55rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--surface);
-      color: var(--text-muted);
-      font-family: var(--mono);
-      font-size: 0.68rem;
-    }
-    .header .status {
-      text-align: right;
-      font-size: 0.82rem;
-      color: var(--text-muted);
-    }
-    .header .status .count {
-      color: var(--text);
-      font-weight: 700;
-    }
-
-    .main {
-      width: min(1280px, 100%);
-      margin: 0 auto;
-      padding: 2rem 1.5rem 3rem;
-      display: flex;
-      flex-direction: column;
-      gap: 1.5rem;
-    }
-
-    .page-intro {
-      display: flex;
-      justify-content: space-between;
-      gap: 1.5rem;
-      align-items: flex-end;
-    }
-    .page-intro h2 {
-      font-size: 2rem;
-      font-weight: 700;
-      letter-spacing: -0.04em;
-    }
-    .page-intro p {
-      margin-top: 0.4rem;
-      color: var(--text-muted);
-      font-size: 0.95rem;
-    }
-    .intro-chip {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      padding: 0.55rem 0.85rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--surface);
-      color: var(--text-muted);
-      font-size: 0.8rem;
-      white-space: nowrap;
-    }
-    .intro-chip strong {
-      color: var(--text);
-      font-weight: 700;
-    }
-
-    .drop-zone {
-      display: none;
-      border: 1px dashed #94a3b8;
-      border-radius: var(--radius);
-      padding: 2rem;
-      text-align: center;
-      cursor: pointer;
-      background: var(--surface);
-      box-shadow: var(--shadow);
-    }
-    .drop-zone.visible { display: block; }
-    .drop-zone:hover, .drop-zone.drag-over {
-      border-color: var(--blue);
-      background: #eff6ff;
-    }
-    .drop-zone h2 {
-      font-size: 1.05rem;
-      font-weight: 700;
-      margin-bottom: 0.5rem;
-    }
-    .drop-zone p {
-      color: var(--text-muted);
-      font-size: 0.9rem;
-      margin-bottom: 1rem;
-      line-height: 1.5;
-    }
-    .drop-zone .file-types {
-      display: flex;
-      justify-content: center;
-      gap: 0.5rem;
-      flex-wrap: wrap;
-    }
-    .file-tag {
-      display: inline-block;
-      padding: 0.25rem 0.65rem;
-      border-radius: 9999px;
-      border: 1px solid var(--border);
-      background: var(--surface-muted);
-      color: var(--text-muted);
-      font-family: var(--mono);
-      font-size: 0.68rem;
-    }
-    .file-tag.loaded {
-      background: var(--green-bg);
-      border-color: #a7f3d0;
-      color: var(--green);
-    }
-    .drop-zone input[type="file"] { display: none; }
-
-    .kpi-row {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
-      gap: 1rem;
-    }
-    .kpi-card,
-    .section {
-      border: 1px solid var(--border);
-      border-radius: var(--radius);
-      background: var(--surface);
-      box-shadow: var(--shadow);
-    }
-    .kpi-card {
-      padding: 1.25rem;
-    }
-    .kpi-label {
-      font-size: 0.75rem;
-      font-weight: 600;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      color: var(--text-muted);
-    }
-    .kpi-value {
-      margin-top: 0.6rem;
-      font-size: 2rem;
-      font-weight: 700;
-      letter-spacing: -0.05em;
-    }
-    .kpi-sub {
-      margin-top: 0.45rem;
-      font-size: 0.82rem;
-      line-height: 1.45;
-      color: var(--text-muted);
-    }
-
-    .status-row {
-      display: grid;
-      grid-template-columns: repeat(4, minmax(0, 1fr));
-      gap: 1rem;
-    }
-    .status-pill {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 0.75rem;
-      padding: 0.95rem 1rem;
-      border-radius: var(--radius);
-      border: 1px solid var(--border);
-      background: var(--surface);
-      box-shadow: var(--shadow);
-      font-size: 0.92rem;
-      font-weight: 600;
-    }
-    .status-pill-label {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.55rem;
-    }
-    .status-pill-count {
-      color: var(--text);
-      font-weight: 700;
-    }
-    .status-dot {
-      width: 0.6rem;
-      height: 0.6rem;
-      border-radius: 999px;
-      display: inline-block;
-    }
-    .status-dot.healthy, .skill-status-dot.healthy { background: var(--green); }
-    .status-dot.warning, .skill-status-dot.warning { background: var(--amber); }
-    .status-dot.critical, .skill-status-dot.critical { background: var(--red); }
-    .status-dot.unknown, .skill-status-dot.unknown { background: var(--text-soft); }
-
-    .section-header {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      gap: 1rem;
-      padding: 1rem 1.15rem;
-      border-bottom: 1px solid var(--border);
-      font-size: 0.78rem;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      color: var(--text-muted);
-    }
-    .section-body { padding: 1.15rem; }
-
-    .toolbar {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      gap: 1rem;
-      flex-wrap: wrap;
-    }
-    .search-filter {
-      width: min(420px, 100%);
-      padding: 0.75rem 0.95rem;
-      border: 1px solid var(--border);
-      border-radius: 12px;
-      background: var(--surface);
-      color: var(--text);
-      font-size: 0.92rem;
-      outline: none;
-    }
-    .search-filter:focus {
-      border-color: var(--blue);
-      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.12);
-    }
-    .search-filter::placeholder { color: var(--text-soft); }
-
-    .export-btn,
-    .drill-down-close,
-    .action-btn,
-    .time-period-selector .period-btn {
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      background: var(--surface);
-      color: var(--text-muted);
-      font-family: inherit;
-      font-size: 0.82rem;
-      font-weight: 600;
-      cursor: pointer;
-      transition: background 0.15s, border-color 0.15s, color 0.15s;
-    }
-    .export-btn,
-    .drill-down-close,
-    .action-btn { padding: 0.55rem 0.85rem; }
-    .export-btn:hover,
-    .drill-down-close:hover,
-    .action-btn:hover:not(:disabled) {
-      border-color: #cbd5e1;
-      background: var(--surface-muted);
-      color: var(--text);
-    }
-
-    .skill-health-header { display: none; }
-    .skill-health-grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
-      gap: 1rem;
-    }
-    .skill-health-card {
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      background: var(--surface);
-      padding: 1rem;
-      cursor: pointer;
-      transition: border-color 0.15s, box-shadow 0.15s, transform 0.15s;
-    }
-    .skill-health-card:hover {
-      transform: translateY(-1px);
-      border-color: #cbd5e1;
-      box-shadow: 0 8px 24px rgba(15, 23, 42, 0.08);
-    }
-    .skill-health-card.selected {
-      border-color: #93c5fd;
-      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.12);
-    }
-    .skill-card-top {
-      display: flex;
-      justify-content: space-between;
-      align-items: flex-start;
-      gap: 0.75rem;
-    }
-    .skill-name {
-      font-size: 0.92rem;
-      font-weight: 700;
-      color: var(--text);
-      line-height: 1.4;
-      word-break: break-word;
-    }
-    .skill-status-dot {
-      width: 0.7rem;
-      height: 0.7rem;
-      border-radius: 999px;
-      flex-shrink: 0;
-      margin-top: 0.15rem;
-    }
-    .skill-pass-rate {
-      margin-top: 0.9rem;
-      font-size: 2rem;
-      font-weight: 700;
-      letter-spacing: -0.05em;
-    }
-    .skill-pass-rate.healthy { color: var(--green); }
-    .skill-pass-rate.warning { color: var(--amber); }
-    .skill-pass-rate.critical { color: var(--red); }
-    .skill-pass-rate.unknown { color: var(--text-soft); }
-    .skill-trend {
-      margin-top: 0.25rem;
-      font-size: 0.86rem;
-      font-weight: 600;
-    }
-    .trend-up { color: var(--green); }
-    .trend-down { color: var(--red); }
-    .trend-flat { color: var(--text-muted); }
-    .skill-card-meta {
-      margin-top: 1rem;
-      display: flex;
-      justify-content: space-between;
-      gap: 0.75rem;
-      align-items: center;
-      font-size: 0.82rem;
-      color: var(--text-muted);
-    }
-
-    .badge {
-      display: inline-flex;
-      align-items: center;
-      border-radius: 999px;
-      padding: 0.22rem 0.58rem;
-      font-size: 0.72rem;
-      font-weight: 700;
-      text-transform: capitalize;
-    }
-    .badge-green, .badge-healthy { background: var(--green-bg); color: var(--green); }
-    .badge-red, .badge-critical { background: var(--red-bg); color: var(--red); }
-    .badge-blue { background: var(--blue-bg); color: var(--blue); }
-    .badge-amber, .badge-warning { background: var(--amber-bg); color: var(--amber); }
-    .badge-unknown { background: var(--slate-bg); color: var(--text-muted); }
-
-    .drill-down-panel {
-      display: none;
-      border: 1px solid var(--border);
-      border-radius: var(--radius);
-      background: var(--surface);
-      box-shadow: var(--shadow);
-    }
-    .drill-down-panel.visible { display: block; }
-    .drill-down-header {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      gap: 1rem;
-      padding: 1rem 1.15rem;
-      border-bottom: 1px solid var(--border);
-    }
-    .drill-down-title-wrap {
-      display: flex;
-      flex-direction: column;
-      gap: 0.25rem;
-    }
-    .drill-down-title-wrap span:first-child {
-      font-size: 1rem;
-      font-weight: 700;
-      color: var(--text);
-    }
-    .drill-down-title-wrap span:last-child {
-      font-size: 0.82rem;
-      color: var(--text-muted);
-    }
-    .drill-down-content {
-      display: grid;
-      grid-template-columns: repeat(2, minmax(0, 1fr));
-      gap: 1rem;
-      padding: 1.15rem;
-    }
-    .drill-down-section {
-      min-height: 220px;
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      padding: 1rem;
-      background: var(--surface);
-    }
-    .drill-down-section h4 {
-      margin-bottom: 0.75rem;
-      font-size: 0.78rem;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      color: var(--text-muted);
-    }
-
-    .chart-container {
-      position: relative;
-      width: 100%;
-      height: 280px;
-    }
-
-    .time-period-selector {
-      display: inline-flex;
-      overflow: hidden;
-      border-radius: 10px;
-    }
-    .time-period-selector .period-btn {
-      padding: 0.45rem 0.75rem;
-      border-radius: 0;
-      border-right: none;
-    }
-    .time-period-selector .period-btn:last-child { border-right: 1px solid var(--border); }
-    .time-period-selector .period-btn.active {
-      background: var(--blue);
-      border-color: var(--blue);
-      color: #fff;
-    }
-
-    .secondary-grid {
-      display: grid;
-      grid-template-columns: repeat(2, minmax(0, 1fr));
-      gap: 1rem;
-      align-items: start;
-    }
-
-    .table-scroll {
-      max-height: 360px;
-      overflow-y: auto;
-    }
-    .table-scroll::-webkit-scrollbar {
-      width: 8px;
-      height: 8px;
-    }
-    .table-scroll::-webkit-scrollbar-thumb {
-      background: #cbd5e1;
-      border-radius: 999px;
-    }
-
-    .data-table,
-    .eval-feed {
-      width: 100%;
-      border-collapse: collapse;
-      font-size: 0.86rem;
-    }
-    .data-table th,
-    .data-table td,
-    .eval-feed th,
-    .eval-feed td {
-      padding: 0.75rem;
-      text-align: left;
-      border-bottom: 1px solid var(--border);
-    }
-    .data-table th,
-    .eval-feed th {
-      position: sticky;
-      top: 0;
-      z-index: 1;
-      background: var(--surface);
-      color: var(--text-muted);
-      font-size: 0.72rem;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-    }
-    .data-table tr:hover,
-    .eval-feed tr:hover {
-      background: var(--surface-muted);
-    }
-    .data-table td.mono,
-    .eval-feed td.mono,
-    .timeline-date,
-    .action-result,
-    .live-indicator {
-      font-family: var(--mono);
-    }
-
-    .timeline-item {
-      display: flex;
-      gap: 0.9rem;
-      padding: 0.9rem 0;
-      border-bottom: 1px solid var(--border);
-      font-size: 0.86rem;
-    }
-    .timeline-item:last-child { border-bottom: none; }
-    .timeline-date {
-      min-width: 132px;
-      color: var(--text-muted);
-      font-size: 0.72rem;
-      flex-shrink: 0;
-    }
-    .timeline-action {
-      font-weight: 700;
-      color: var(--text);
-    }
-
-    .empty-state {
-      padding: 2rem 1rem;
-      text-align: center;
-      color: var(--text-muted);
-      font-size: 0.9rem;
-      border: 1px dashed var(--border);
-      border-radius: var(--radius-sm);
-      background: var(--surface-muted);
-    }
-
-    .live-indicator {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      font-size: 0.72rem;
-      color: var(--green);
-    }
-    .live-dot {
-      width: 0.45rem;
-      height: 0.45rem;
-      border-radius: 999px;
-      background: var(--green);
-    }
-    .action-btn:disabled {
-      opacity: 0.5;
-      cursor: not-allowed;
-    }
-    .action-btn.loading {
-      color: transparent;
-      position: relative;
-    }
-    .action-btn.loading::after {
-      content: "...";
-      position: absolute;
-      inset: 0;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      color: var(--blue);
-    }
-    .action-btn-group {
-      display: flex;
-      flex-wrap: wrap;
-      gap: 0.5rem;
-    }
-    .action-result {
-      display: none;
-      margin-top: 0.75rem;
-      padding: 0.75rem;
-      border-radius: var(--radius-sm);
-      font-size: 0.75rem;
-      max-height: 140px;
-      overflow-y: auto;
-    }
-    .action-result.visible { display: block; }
-    .action-result.success { background: var(--green-bg); color: var(--green); }
-    .action-result.error { background: var(--red-bg); color: var(--red); }
-
-    .evo-timeline {
-      position: relative;
-      padding-left: 1.5rem;
-    }
-    .evo-timeline::before {
-      content: "";
-      position: absolute;
-      left: 0.35rem;
-      top: 0;
-      bottom: 0;
-      width: 1px;
-      background: var(--border);
-    }
-    .evo-timeline-item {
-      position: relative;
-      padding: 0 0 1rem 0.8rem;
-    }
-    .evo-timeline-item::before {
-      content: "";
-      position: absolute;
-      left: -1.2rem;
-      top: 0.35rem;
-      width: 0.6rem;
-      height: 0.6rem;
-      border-radius: 999px;
-      background: var(--slate-bg);
-    }
-    .evo-timeline-item.action-evolved::before { background: var(--green); }
-    .evo-timeline-item.action-rolled-back::before { background: var(--red); }
-    .evo-timeline-item.action-watched::before { background: var(--blue); }
-    .evo-timeline-meta {
-      color: var(--text-muted);
-      font-size: 0.74rem;
-    }
-    .evo-timeline-body {
-      margin-top: 0.3rem;
-      font-size: 0.86rem;
-      color: var(--text);
-    }
-    .evo-timeline-rationale {
-      margin-top: 0.3rem;
-      color: var(--text-muted);
-      font-size: 0.82rem;
-      line-height: 1.45;
-    }
-    .evidence-list {
-      display: flex;
-      flex-direction: column;
-      gap: 0.9rem;
-    }
-    .evidence-card {
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      background: var(--surface-muted);
-      padding: 0.9rem;
-    }
-    .evidence-card summary {
-      cursor: pointer;
-      list-style: none;
-    }
-    .evidence-card summary::-webkit-details-marker { display: none; }
-    .evidence-meta {
-      display: flex;
-      flex-wrap: wrap;
-      gap: 0.5rem 0.75rem;
-      margin-top: 0.35rem;
-      color: var(--text-muted);
-      font-size: 0.76rem;
-    }
-    .evidence-diff {
-      display: grid;
-      grid-template-columns: repeat(2, minmax(0, 1fr));
-      gap: 0.75rem;
-      margin-top: 0.8rem;
-    }
-    .evidence-block {
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      background: var(--surface);
-      padding: 0.75rem;
-    }
-    .evidence-block h5 {
-      margin-bottom: 0.45rem;
-      font-size: 0.74rem;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      color: var(--text-muted);
-    }
-    .evidence-block pre {
-      white-space: pre-wrap;
-      word-break: break-word;
-      font-family: var(--mono);
-      font-size: 0.77rem;
-      line-height: 1.5;
-      color: var(--text);
-    }
-    .evidence-summary {
-      margin-top: 0.75rem;
-      display: flex;
-      flex-wrap: wrap;
-      gap: 0.5rem;
-    }
-    .evidence-chip {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      padding: 0.32rem 0.55rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--surface);
-      color: var(--text-muted);
-      font-size: 0.74rem;
-    }
-
-    @media (max-width: 960px) {
-      .status-row,
-      .secondary-grid,
-      .drill-down-content {
-        grid-template-columns: 1fr;
-      }
-      .evidence-diff {
-        grid-template-columns: 1fr;
-      }
-      .page-intro {
-        flex-direction: column;
-        align-items: flex-start;
-      }
-    }
-
-    @media (max-width: 720px) {
-      .header {
-        flex-direction: column;
-        align-items: flex-start;
-      }
-      .header .status {
-        text-align: left;
-      }
-      .main {
-        padding-left: 1rem;
-        padding-right: 1rem;
-      }
-      .kpi-row,
-      .skill-health-grid {
-        grid-template-columns: 1fr;
-      }
-    }
-  </style>
-</head>
-<body>
-
-<!-- ===== Header ===== -->
-<div class="header">
-  <div class="header-left">
-    <svg xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 250 250" fill="none" style="flex-shrink:0" aria-hidden="true">
-      <path d="M 190.16,31.49 C 187.91,29.88 184.51,32.19 185.88,35.16 C 186.31,36.11 187.08,36.54 187.71,37.01 C 218.75,59.86 237.63,92.71 237.63,128.82 C 237.63,175.99 205.12,218.56 153.82,234.69 C 149.89,235.93 150.91,241.71 154.91,240.66 C 205.98,226.96 243.01,181.94 243,128.45 C 242.99,90.87 223.47,56.18 190.16,31.49 Z" fill="currentColor"/>
-      <path d="M 125.19,243.91 C 138.08,243.91 147.18,236.44 151.21,225.01 C 193.72,217.79 226.98,184.02 226.98,140.81 C 226.98,121.17 219.82,103.78 209.93,87.04 C 191.42,55.45 165.15,34.72 117.71,28.65 C 112.91,28.04 113.77,34.35 117.19,34.82 C 161.67,39.33 185.84,56.71 203.76,86.42 C 213.87,103.68 220.68,119.61 220.68,140.81 C 220.68,179.96 190.81,211.95 148.71,219.16 C 147.11,219.47 146.27,220.32 145.92,221.8 C 142.95,231.11 135.72,238.02 125.19,237.66 C 64.48,237.66 11.67,191.61 11.67,127.51 C 11.67,79.61 44.82,36.38 93.89,27.77 L 94.11,27.73 L 94.38,26.64 C 97.04,16.61 104.57,11.82 114.19,11.82 C 134.12,13.36 152.91,18.15 170.48,26.08 C 171.92,26.78 173.81,27.09 174.76,25.59 C 176.05,23.72 175.31,21.07 173.01,20.34 C 154.78,11.96 137.21,7.17 114.47,6 H 113.52 C 101.91,6 93.46,12.16 89.49,21.78 C 42.36,31.26 6.17,74.76 6.17,128.08 C 6.17,190.05 57.92,243.91 125.19,243.91 Z" fill="currentColor"/>
-      <path d="M 93.67,40.64 C 100.51,52.07 109.54,51.33 114.05,52.17 C 128.72,53.91 141.48,55.78 157.38,62.16 C 162.72,64.47 162.29,58.19 159.18,57.01 C 145.11,51.33 132.48,49.79 111.31,47.48 C 101.83,46.29 95.45,41.18 93.75,32.81 C 55.21,39.46 22.06,72.17 22.06,112.48 C 22.06,131.98 30.36,149.82 43.26,164.49 C 46.23,167.59 50.19,164.13 48.32,161.02 C 36.21,145.54 28.42,129.78 28.42,112.4 C 28.42,79.11 54.91,48.36 89.91,40.36 C 90.76,40.15 91.04,39.87 91.62,40.01 C 92.62,40.01 93.04,39.65 93.67,40.64 Z" fill="currentColor"/>
-      <path d="M 152.72,82.77 C 126.61,82.77 113.07,99.44 103.01,119.33 C 100.56,123.36 103.74,125.03 105.61,123.92 C 107.15,123.22 107.89,121.05 108.73,119.61 C 118.22,102.16 130.33,88.56 152.72,88.56 C 181.62,88.56 201.91,116.01 201.91,147.31 C 201.91,175.12 183.47,199.96 152.51,205.75 C 151.84,205.96 151.63,206.03 151.56,205.54 C 147.74,195.37 139.36,188.15 128.07,186.48 C 113.2,184.24 101.23,182.36 83.8,176.81 C 79.3,175.48 77.91,182.36 82.41,183.09 C 97.21,187.46 108.09,189.47 126.25,192.65 C 136.78,194.31 145.41,201.71 147.11,210.95 C 147.74,213.05 149.13,213.41 150.15,213.26 C 183.75,208.61 208.26,180.93 208.26,147.24 C 208.26,115.06 186.94,82.77 152.72,82.77 Z" fill="currentColor"/>
-      <path d="M 129.77,105.21 C 122.93,112.05 118.97,122.73 113.77,130.41 C 111.31,133.45 114.56,136.63 117.46,134.46 C 123.75,126.23 127.43,115.62 135.15,108.71 C 138.22,105.81 134.73,101.09 129.77,105.21 Z" fill="currentColor"/>
-      <path d="M 136.78,120.31 C 127.71,136.71 120.12,154.91 93.74,154.91 C 66.07,154.91 47.76,128.53 47.76,104.78 C 47.76,84.47 58.57,66.08 77.66,56.25 C 82.23,54.21 79.85,47.76 75.34,49.93 C 54.77,59.72 42.01,80.11 42.01,104.71 C 42.01,131.77 61.86,161.31 93.67,161.31 C 114.77,161.31 128.91,147.24 139.86,124.06 C 142.76,120.45 139.15,117.73 136.78,120.31 Z" fill="currentColor"/>
-      <path d="M 30.73,154.7 C 27.76,152.97 23.87,155.93 25.41,158.76 C 41.73,188.36 68.94,199.79 105.75,206.41 C 112.25,207.66 122.07,208.75 123.46,209.03 C 128.07,209.95 128.07,220.18 121.78,220.18 C 107.64,218.94 92.06,215.98 76.23,211.33 C 72.13,210.24 71.04,216.69 75.27,217.64 C 90.41,222.22 103.95,224.74 120.47,226.54 C 133.73,226.54 136.56,209.03 126.03,203.38 C 123.75,202.13 122.73,202.56 112.04,200.76 C 78.09,195.04 54.06,188.98 32.12,155.65 C 31.77,155.23 31.28,154.91 30.73,154.7 Z" fill="currentColor"/>
-    </svg>
-    <h1>self<span>tune</span></h1>
-    <span class="version">v0.1.4</span>
-  </div>
-  <div class="status" id="headerStatus">Drop log files to get started</div>
-</div>
-
-<!-- ===== Content ===== -->
-<div class="main" id="mainContent">
-
-  <div class="page-intro">
-    <div>
-      <h2>Overview</h2>
-      <p>Local snapshot of skill health, regressions, unmatched queries, and recent evolution activity.</p>
-    </div>
-    <div class="intro-chip"><strong id="overviewMode">Static export</strong><span id="overviewContext">Open a built dashboard or run live mode for updates.</span></div>
-  </div>
-
-  <!-- Drop zone (shown when no data) -->
-  <div class="drop-zone" id="dropZone" role="button" tabindex="0" aria-label="Load log files by clicking or dragging">
-    <h2>No embedded dashboard data found</h2>
-    <p>Drag &amp; drop JSONL log files here, or click to browse.<br>
-       This fallback stays local to your machine and lets you inspect raw exports.</p>
-    <div class="file-types">
-      <span class="file-tag" id="tag-telemetry">session_telemetry_log.jsonl</span>
-      <span class="file-tag" id="tag-skill">skill_usage_log.jsonl</span>
-      <span class="file-tag" id="tag-query">all_queries_log.jsonl</span>
-      <span class="file-tag" id="tag-evolution">evolution_audit_log.jsonl</span>
-      <span class="file-tag" id="tag-evidence">evolution_evidence_log.jsonl</span>
-    </div>
-    <input type="file" id="fileInput" multiple accept=".jsonl,.json">
-  </div>
-
-  <!-- ===== SYSTEM HEALTH SUMMARY ===== -->
-  <div id="healthSummary" style="display:none;">
-    <div class="kpi-row" id="kpiRow">
-      <div class="kpi-card">
-        <div class="kpi-label">Skills Monitored</div>
-        <div class="kpi-value" id="kpi-skills-monitored">0</div>
-        <div class="kpi-sub" id="kpi-skills-sub"></div>
-      </div>
-      <div class="kpi-card">
-        <div class="kpi-label">Avg Pass Rate</div>
-        <div class="kpi-value" id="kpi-avg-pass-rate">--</div>
-        <div class="kpi-sub" id="kpi-pass-rate-sub"></div>
-      </div>
-      <div class="kpi-card">
-        <div class="kpi-label">Regressions</div>
-        <div class="kpi-value" id="kpi-regressions">0</div>
-        <div class="kpi-sub" id="kpi-regressions-sub"></div>
-      </div>
-      <div class="kpi-card">
-        <div class="kpi-label">Unmatched Queries</div>
-        <div class="kpi-value" id="kpi-unmatched">0</div>
-        <div class="kpi-sub" id="kpi-unmatched-sub"></div>
-      </div>
-      <div class="kpi-card">
-        <div class="kpi-label">Sessions</div>
-        <div class="kpi-value" id="kpi-sessions">0</div>
-        <div class="kpi-sub" id="kpi-sessions-sub"></div>
-      </div>
-      <div class="kpi-card">
-        <div class="kpi-label">Pending Proposals</div>
-        <div class="kpi-value" id="kpi-pending">0</div>
-        <div class="kpi-sub" id="kpi-pending-sub"></div>
-      </div>
-    </div>
-  </div>
-
-  <div class="status-row" id="statusRow" style="display:none;">
-    <div class="status-pill">
-      <span class="status-pill-label"><span class="status-dot healthy"></span>Healthy</span>
-      <span class="status-pill-count" id="statusHealthy">0</span>
-    </div>
-    <div class="status-pill">
-      <span class="status-pill-label"><span class="status-dot warning"></span>Warning</span>
-      <span class="status-pill-count" id="statusWarning">0</span>
-    </div>
-    <div class="status-pill">
-      <span class="status-pill-label"><span class="status-dot critical"></span>Critical</span>
-      <span class="status-pill-count" id="statusCritical">0</span>
-    </div>
-    <div class="status-pill">
-      <span class="status-pill-label"><span class="status-dot unknown"></span>Unknown</span>
-      <span class="status-pill-count" id="statusUnknown">0</span>
-    </div>
-  </div>
-
-  <!-- ===== SKILL HEALTH GRID ===== -->
-  <div class="section" id="skillHealthSection" style="display:none;">
-    <div class="section-header">
-      <span>Skill Health</span>
-      <div class="toolbar">
-        <input id="skillSearchInput" placeholder="Search skills..." class="search-filter" aria-label="Filter skills by name" style="display:none;">
-        <button class="export-btn" id="exportCsvBtn">Export CSV</button>
-      </div>
-    </div>
-    <div class="skill-health-header"></div>
-    <div class="section-body skill-health-grid" id="skillHealthGrid">
-      <div class="empty-state">Load data to see skill health</div>
-    </div>
-  </div>
-
-  <!-- ===== DRILL-DOWN PANEL ===== -->
-  <div class="drill-down-panel" id="drillDownPanel">
-    <div class="drill-down-header">
-      <div class="drill-down-title-wrap">
-        <span id="drillDownTitle">Skill Details</span>
-        <span id="drillDownSubtitle">Select a skill to inspect pass rate, missed prompts, and evolution history.</span>
-      </div>
-      <button class="drill-down-close" id="drillDownClose">Close</button>
-    </div>
-    <div class="drill-down-content">
-      <div class="drill-down-section">
-        <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:0.75rem;">
-          <h4>Pass Rate Over Time</h4>
-          <div class="time-period-selector" id="timePeriodSelector">
-            <button class="period-btn" data-days="7">7d</button>
-            <button class="period-btn" data-days="30">30d</button>
-            <button class="period-btn" data-days="90">90d</button>
-            <button class="period-btn active" data-days="0">All</button>
-          </div>
-        </div>
-        <div class="chart-container"><canvas id="chartDrillPassRate"></canvas></div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Missed Queries</h4>
-        <div class="table-scroll" style="max-height:260px;">
-          <table class="data-table" id="drillMissedTable">
-            <thead><tr><th>Timestamp</th><th>Session</th><th>Query</th></tr></thead>
-            <tbody></tbody>
-          </table>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Evolution History</h4>
-        <div id="drillEvoTimeline" class="table-scroll" style="max-height:260px;">
-          <div class="empty-state">No evolution history</div>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Description Versions</h4>
-        <div id="drillVersionHistory" class="evidence-list">
-          <div class="empty-state">No proposal artifacts recorded</div>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Validation Evidence</h4>
-        <div class="table-scroll" style="max-height:320px;">
-          <table class="eval-feed" id="drillEvidenceTable">
-            <thead><tr><th>Query</th><th>Expected</th><th>Before</th><th>After</th><th>Delta</th></tr></thead>
-            <tbody></tbody>
-          </table>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Sessions</h4>
-        <div class="table-scroll" style="max-height:260px;">
-          <table class="data-table" id="drillSessionsTable">
-            <thead><tr><th>Timestamp</th><th>Tools</th><th>Skills</th><th>Errors</th></tr></thead>
-            <tbody></tbody>
-          </table>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Evaluation Feed</h4>
-        <div class="table-scroll" style="max-height:260px;">
-          <table class="eval-feed" id="drillEvalFeed">
-            <thead><tr><th>Time</th><th>Query</th><th>Triggered</th><th>Type</th></tr></thead>
-            <tbody></tbody>
-          </table>
-        </div>
-      </div>
-      <div class="drill-down-section">
-        <h4>Invocation Breakdown</h4>
-        <div class="chart-container"><canvas id="chartInvocationBreakdown"></canvas></div>
-      </div>
-    </div>
-  </div>
-
-  <div class="secondary-grid">
-    <!-- ===== UNMATCHED QUERIES ===== -->
-    <div class="section" id="unmatchedSection" style="display:none;">
-      <div class="section-header">Unmatched Queries</div>
-      <div class="section-body">
-        <div class="table-scroll">
-          <table class="data-table" id="unmatchedTable">
-            <thead><tr><th>Timestamp</th><th>Session</th><th>Query</th></tr></thead>
-            <tbody></tbody>
-          </table>
-        </div>
-      </div>
-    </div>
-
-    <!-- ===== RECENT EVOLUTION ===== -->
-    <div class="section" id="evolutionFeedSection" style="display:none;">
-      <div class="section-header">Recent Evolution</div>
-      <div class="section-body" id="evolutionFeed">
-        <div class="empty-state">No evolution activity recorded</div>
-      </div>
-    </div>
-
-    <!-- ===== SKILL ACTIONS (live mode only) ===== -->
-    <div class="section" id="actionsSection" style="display:none;">
-      <div class="section-header">
-        <span>Skill Actions</span>
-        <span class="live-indicator" id="liveIndicator"><span class="live-dot"></span> LIVE</span>
-      </div>
-      <div class="section-body" id="actionsBody">
-        <div class="empty-state">Select a skill from the health grid to see actions</div>
-      </div>
-    </div>
-
-    <!-- ===== EVOLUTION TIMELINE (live mode only) ===== -->
-    <div class="section" id="evoTimelineSection" style="display:none;">
-      <div class="section-header">Evolution Timeline</div>
-      <div class="section-body">
-        <div class="evo-timeline" id="evoTimeline">
-          <div class="empty-state">No evolution decisions recorded</div>
-        </div>
-      </div>
-    </div>
-  </div>
-
-</div>
-
-<script>
-// ========================================================================
-// State
-// ========================================================================
-const state = {
-  telemetry: [],   // SessionTelemetryRecord[]
-  skills: [],      // SkillUsageRecord[]
-  queries: [],     // QueryLogRecord[]
-  evolution: [],   // EvolutionAuditEntry[]
-  evidence: [],    // EvolutionEvidenceEntry[]
-  counts: null,    // Optional aggregated counts for live mode payloads
-  computed: null,  // Pre-computed monitoring data (from CLI)
-  liveLoading: false,
-};
-
-const charts = {};
-let selectedSkill = null;
-let selectedPeriodDays = 0; // 0 = All
-
-// ========================================================================
-// File identification
-// ========================================================================
-function identifyFile(name, firstLine) {
-  if (name.includes('session_telemetry')) return 'telemetry';
-  if (name.includes('skill_usage')) return 'skills';
-  if (name.includes('all_queries')) return 'queries';
-  if (name.includes('evolution_audit')) return 'evolution';
-  if (name.includes('evolution_evidence')) return 'evidence';
-  if (firstLine) {
-    try {
-      const obj = JSON.parse(firstLine);
-      if ('total_tool_calls' in obj || 'transcript_path' in obj) return 'telemetry';
-      if ('skill_name' in obj && 'triggered' in obj) return 'skills';
-      if ('query' in obj && !('skill_name' in obj)) return 'queries';
-      if ('proposal_id' in obj && 'action' in obj) return 'evolution';
-      if ('proposal_id' in obj && 'stage' in obj && 'target' in obj) return 'evidence';
-    } catch {}
-  }
-  return null;
-}
-
-function parseJSONL(text) {
-  return text.trim().split('\n').filter(Boolean).map(line => {
-    try { return JSON.parse(line); }
-    catch { return null; }
-  }).filter(Boolean);
-}
-
-// ========================================================================
-// Client-side computed data generation (for drag-drop mode)
-// ========================================================================
-const REGRESSION_THRESHOLD = 0.4;
-const DEFAULT_BASELINE_PASS_RATE = 0.5;
-const MIN_MONITORING_SKILL_CHECKS = 3;
-const NON_USER_QUERY_PREFIXES = [
-  '<system_instruction>',
-  '<system-instruction>',
-  '<local-command-caveat>',
-  '<local-command-stdout>',
-  '<local-command-stderr>',
-  '[Request interrupted by user for tool use]',
-  'Base directory for this skill:',
-];
-
-function isActionableQueryText(query) {
-  const trimmed = (query || '').trim();
-  if (!trimmed) return false;
-  return !NON_USER_QUERY_PREFIXES.some(prefix => trimmed.startsWith(prefix));
-}
-
-function computeClientSide() {
-  const actionableQueries = state.queries.filter(q => isActionableQueryText(q.query));
-  const skillNames = [...new Set(state.skills.map(r => r.skill_name))];
-  const triggeredQueries = new Set(
-    state.skills.filter(r => r.triggered).map(r => r.query.toLowerCase().trim())
-  );
-
-  // Per-skill snapshots
-  const snapshots = {};
-  for (const name of skillNames) {
-    const skillRecords = state.skills.filter(r => r.skill_name === name);
-    const triggered = skillRecords.filter(r => r.triggered).length;
-    const skillChecks = skillRecords.length;
-    const passRate = skillChecks === 0 ? 0 : triggered / skillChecks;
-    const falseNegatives = skillRecords.filter(r => !r.triggered).length;
-    const fnRate = skillChecks === 0 ? 0 : falseNegatives / skillChecks;
-    snapshots[name] = {
-      timestamp: new Date().toISOString(),
-      skill_name: name,
-      window_sessions: state.telemetry.length,
-      skill_checks: skillChecks,
-      pass_rate: passRate,
-      false_negative_rate: fnRate,
-      regression_detected: skillChecks >= MIN_MONITORING_SKILL_CHECKS && passRate < REGRESSION_THRESHOLD,
-      baseline_pass_rate: DEFAULT_BASELINE_PASS_RATE,
-    };
-  }
-
-  // Unmatched queries
-  const unmatched = actionableQueries.filter(q =>
-    !triggeredQueries.has(q.query.toLowerCase().trim())
-  ).map(q => ({ timestamp: q.timestamp, session_id: q.session_id, query: q.query }));
-
-  // Pending proposals
-  const proposalStatus = {};
-  for (const e of state.evolution) {
-    if (!proposalStatus[e.proposal_id]) proposalStatus[e.proposal_id] = [];
-    proposalStatus[e.proposal_id].push(e.action);
-  }
-  const seenProposals = new Set();
-  const pendingProposals = state.evolution.filter(e => {
-    if (e.action !== 'created' && e.action !== 'validated') return false;
-    const actions = proposalStatus[e.proposal_id] || [];
-    if (actions.includes('deployed') || actions.includes('rejected') || actions.includes('rolled_back')) return false;
-    if (seenProposals.has(e.proposal_id)) return false;
-    seenProposals.add(e.proposal_id);
-    return true;
-  });
-
-  return { snapshots, unmatched, pendingProposals };
-}
-
-// ========================================================================
-// File loading
-// ========================================================================
-async function handleFiles(files) {
-  for (const file of files) {
-    const text = await file.text();
-    const lines = text.trim().split('\n').filter(Boolean);
-    if (!lines.length) continue;
-    const type = identifyFile(file.name, lines[0]);
-    if (!type) { console.warn('Unknown file type:', file.name); continue; }
-    state[type] = parseJSONL(text);
-    const tag = document.getElementById(`tag-${type === 'skills' ? 'skill' : type}`);
-    if (tag) tag.classList.add('loaded');
-  }
-  state.computed = computeClientSide();
-  refreshAll();
-}
-
-// ========================================================================
-// Drag & drop + click
-// ========================================================================
-const dropZone = document.getElementById('dropZone');
-const fileInput = document.getElementById('fileInput');
-
-dropZone.addEventListener('click', () => fileInput.click());
-dropZone.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); fileInput.click(); } });
-fileInput.addEventListener('change', e => handleFiles(e.target.files));
-
-dropZone.addEventListener('dragover', e => {
-  e.preventDefault();
-  dropZone.classList.add('drag-over');
-});
-dropZone.addEventListener('dragleave', () => dropZone.classList.remove('drag-over'));
-dropZone.addEventListener('drop', e => {
-  e.preventDefault();
-  dropZone.classList.remove('drag-over');
-  handleFiles(e.dataTransfer.files);
-});
-
-// ========================================================================
-// Data loading from embedded JSON (when served by CLI)
-// ========================================================================
-function loadEmbeddedData() {
-  const el = document.getElementById('embedded-data');
-  if (!el) return false;
-  try {
-    const rawText = (el.textContent || '').trim();
-    const payload = el.dataset.encoding === 'base64'
-      ? new TextDecoder().decode(Uint8Array.from(atob(rawText), c => c.charCodeAt(0)))
-      : rawText;
-    const data = JSON.parse(payload);
-    if (data.telemetry) state.telemetry = data.telemetry;
-    if (data.skills) state.skills = data.skills;
-    if (data.queries) state.queries = data.queries;
-    if (data.evolution) state.evolution = data.evolution;
-    if (data.evidence) state.evidence = data.evidence;
-    if (data.counts) state.counts = data.counts;
-    if (data.computed) {
-      state.computed = data.computed;
-    } else {
-      state.computed = computeClientSide();
-    }
-    return state.telemetry.length || state.skills.length || state.queries.length || state.evolution.length;
-  } catch { return false; }
-}
-
-function getCount(key, records) {
-  return state.counts && Number.isFinite(Number(state.counts[key]))
-    ? Number(state.counts[key])
-    : records.length;
-}
-
-// ========================================================================
-// Helpers
-// ========================================================================
-function toDate(ts) { return new Date(ts); }
-
-function formatDate(ts) {
-  const d = toDate(ts);
-  return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
-}
-
-function toDayKey(ts) { return new Date(ts).toISOString().slice(0, 10); }
-
-function formatTimestamp(ts) {
-  const d = toDate(ts);
-  return d.toLocaleString('en-US', {
-    month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit'
-  });
-}
-
-function truncate(s, max = 60) {
-  if (!s) return '\u2014';
-  return s.length > max ? s.slice(0, max) + '...' : s;
-}
-
-function escapeHtml(s) {
-  if (!s) return '';
-  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-function groupByDay(records) {
-  const map = {};
-  for (const r of records) {
-    const day = toDayKey(r.timestamp);
-    map[day] = (map[day] || 0) + 1;
-  }
-  return map;
-}
-
-function getSkillStatus(passRate, regressionDetected, skillChecks = MIN_MONITORING_SKILL_CHECKS) {
-  if (skillChecks < MIN_MONITORING_SKILL_CHECKS) return 'unknown';
-  if (passRate === null || passRate === undefined) return 'unknown';
-  if (regressionDetected || passRate < 0.4) return 'critical';
-  if (passRate < 0.7) return 'warning';
-  return 'healthy';
-}
-
-function getStatusBadge(status) {
-  const map = {
-    healthy: '<span class="badge badge-healthy">Healthy</span>',
-    warning: '<span class="badge badge-warning">Warning</span>',
-    critical: '<span class="badge badge-critical">Critical</span>',
-    unknown: '<span class="badge badge-unknown">Unknown</span>',
-  };
-  return map[status] || '';
-}
-
-const CHART_COLORS = [
-  '#2563eb', '#059669', '#d97706', '#dc2626', '#7c3aed',
-  '#0891b2', '#ea580c', '#475569', '#65a30d', '#db2777'
-];
-
-// ========================================================================
-// Refresh all views
-// ========================================================================
-function refreshAll() {
-  const hasData = state.telemetry.length || state.skills.length ||
-                  state.queries.length || state.evolution.length;
-  const isLoading = isLiveMode() && state.liveLoading && !hasData;
-
-  if (hasData || isLoading) {
-    dropZone.classList.remove('visible');
-    document.getElementById('healthSummary').style.display = 'block';
-    document.getElementById('statusRow').style.display = 'grid';
-    document.getElementById('skillHealthSection').style.display = 'block';
-    document.getElementById('skillSearchInput').style.display = 'block';
-  } else {
-    dropZone.classList.add('visible');
-    document.getElementById('healthSummary').style.display = 'none';
-    document.getElementById('statusRow').style.display = 'none';
-    document.getElementById('skillHealthSection').style.display = 'none';
-    document.getElementById('skillSearchInput').style.display = 'none';
-  }
-
-  updateHeader();
-  updateHealthSummary();
-  updateStatusSummary();
-  updateSkillHealthGrid();
-  updateUnmatched();
-  updateEvolutionFeed();
-}
-
-// ========================================================================
-// Header
-// ========================================================================
-function updateHeader() {
-  const isLoading = isLiveMode() && state.liveLoading;
-  const parts = [];
-  const telemetryCount = getCount('telemetry', state.telemetry);
-  const skillCount = getCount('skills', state.skills);
-  const queryCount = getCount('queries', state.queries);
-  const evolutionCount = getCount('evolution', state.evolution);
-  if (telemetryCount) parts.push(`<span class="count">${telemetryCount}</span> sessions`);
-  if (skillCount) parts.push(`<span class="count">${skillCount}</span> skill events`);
-  if (queryCount) parts.push(`<span class="count">${queryCount}</span> queries`);
-  if (evolutionCount) parts.push(`<span class="count">${evolutionCount}</span> evolution actions`);
-  document.getElementById('headerStatus').innerHTML = isLoading
-    ? 'Loading live dashboard data&hellip;'
-    : parts.length
-      ? parts.join(' &middot; ')
-      : 'No embedded data found. Load log files to explore a local snapshot.';
-  document.getElementById('overviewMode').textContent = isLiveMode() ? 'Live dashboard' : 'Static export';
-  document.getElementById('overviewContext').textContent = isLoading
-    ? 'Waiting for the first live payload from your local server.'
-    : parts.length
-      ? `${skillCount || 0} tracked skill events across your local logs`
-      : 'Open a built dashboard or run live mode for updates.';
-}
-
-// ========================================================================
-// Health Summary KPIs
-// ========================================================================
-function updateHealthSummary() {
-  const computed = state.computed;
-  if (!computed) {
-    if (isLiveMode() && state.liveLoading) {
-      document.getElementById('kpi-skills-monitored').textContent = '—';
-      document.getElementById('kpi-skills-sub').textContent = 'loading live metrics';
-      document.getElementById('kpi-avg-pass-rate').textContent = '—';
-      document.getElementById('kpi-pass-rate-sub').textContent = 'waiting for summary';
-      document.getElementById('kpi-regressions').textContent = '—';
-      document.getElementById('kpi-regressions-sub').textContent = 'waiting for summary';
-      document.getElementById('kpi-unmatched').textContent = '—';
-      document.getElementById('kpi-unmatched-sub').textContent = 'waiting for summary';
-      document.getElementById('kpi-sessions').textContent = '—';
-      document.getElementById('kpi-sessions-sub').textContent = 'waiting for summary';
-      document.getElementById('kpi-pending').textContent = '—';
-      document.getElementById('kpi-pending-sub').textContent = 'waiting for summary';
-    }
-    return;
-  }
-
-  const snapshots = computed.snapshots || {};
-  const skillNames = Object.keys(snapshots);
-  const regressions = skillNames.filter(n => snapshots[n].regression_detected);
-
-  document.getElementById('kpi-skills-monitored').textContent = skillNames.length;
-  document.getElementById('kpi-skills-sub').textContent =
-    regressions.length ? `${regressions.length} need attention` : 'all stable';
-
-  if (skillNames.length > 0) {
-    const avgPR = skillNames.reduce((sum, n) => sum + snapshots[n].pass_rate, 0) / skillNames.length;
-    document.getElementById('kpi-avg-pass-rate').textContent = (avgPR * 100).toFixed(0) + '%';
-    const totalChecks = skillNames.reduce((sum, n) => sum + (snapshots[n].skill_checks || 0), 0);
-    const status = getSkillStatus(avgPR, false, totalChecks);
-    document.getElementById('kpi-pass-rate-sub').textContent =
-      status === 'healthy' ? 'system healthy' : status === 'warning' ? 'needs monitoring' : status === 'critical' ? 'action required' : 'no data';
-  }
-
-  document.getElementById('kpi-regressions').textContent = regressions.length;
-  document.getElementById('kpi-regressions-sub').textContent =
-    regressions.length ? regressions.join(', ') : 'none detected';
-
-  const unmatched = computed.unmatched || [];
-  const unmatchedCount = Number.isFinite(Number(computed.unmatched_count))
-    ? Number(computed.unmatched_count)
-    : unmatched.length;
-  document.getElementById('kpi-unmatched').textContent = unmatchedCount;
-  document.getElementById('kpi-unmatched-sub').textContent =
-    unmatchedCount ? 'queries not matched to any skill' : 'all queries matched';
-
-  document.getElementById('kpi-sessions').textContent = getCount('telemetry', state.telemetry);
-  if (state.telemetry.length) {
-    const sorted = [...state.telemetry].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
-    const first = formatDate(sorted[0].timestamp);
-    const last = formatDate(sorted[sorted.length - 1].timestamp);
-    document.getElementById('kpi-sessions-sub').textContent = first + ' \u2014 ' + last;
-  }
-
-  const pending = computed.pendingProposals || [];
-  document.getElementById('kpi-pending').textContent = pending.length;
-  document.getElementById('kpi-pending-sub').textContent =
-    pending.length ? 'awaiting deployment' : 'none pending';
-}
-
-function updateStatusSummary() {
-  const computed = state.computed;
-  if (!computed) return;
-
-  const snapshots = computed.snapshots || {};
-  const counts = { healthy: 0, warning: 0, critical: 0, unknown: 0 };
-
-  Object.values(snapshots).forEach((snap) => {
-    const status = getSkillStatus(snap.pass_rate, snap.regression_detected, snap.skill_checks);
-    counts[status] = (counts[status] || 0) + 1;
-  });
-
-  document.getElementById('statusHealthy').textContent = counts.healthy;
-  document.getElementById('statusWarning').textContent = counts.warning;
-  document.getElementById('statusCritical').textContent = counts.critical;
-  document.getElementById('statusUnknown').textContent = counts.unknown;
-}
-
-// ========================================================================
-// Skill Health Grid
-// ========================================================================
-function updateSkillHealthGrid() {
-  const computed = state.computed;
-  const grid = document.getElementById('skillHealthGrid');
-  if (!computed) {
-    if (isLiveMode() && state.liveLoading) {
-      grid.innerHTML = '<div class="empty-state">Loading live skill health…</div>';
-    }
-    return;
-  }
-
-  const snapshots = computed.snapshots || {};
-  const skillNames = Object.keys(snapshots);
-
-  if (!skillNames.length) {
-    grid.innerHTML = '<div class="empty-state">No skill health data yet</div>';
-    return;
-  }
-
-  // Sort worst-first
-  const sorted = skillNames.sort((a, b) => {
-    const sa = snapshots[a];
-    const sb = snapshots[b];
-    if (sa.regression_detected && !sb.regression_detected) return -1;
-    if (!sa.regression_detected && sb.regression_detected) return 1;
-    return sa.pass_rate - sb.pass_rate;
-  });
-
-  grid.innerHTML = sorted.map(name => {
-    const snap = snapshots[name];
-    const status = getSkillStatus(snap.pass_rate, snap.regression_detected, snap.skill_checks);
-    const pct = (snap.pass_rate * 100).toFixed(0);
-    const evalCount = snap.skill_checks ?? state.skills.filter(r => r.skill_name === name).length;
-    const delta = typeof snap.baseline_pass_rate === 'number'
-      ? (snap.pass_rate - snap.baseline_pass_rate) * 100
-      : null;
-    const trendSymbol = delta === null ? '\u2192' : delta > 0.1 ? '\u2191' : delta < -0.1 ? '\u2193' : '\u2192';
-    const trendClass = delta === null ? 'trend-flat' : delta > 0.1 ? 'trend-up' : delta < -0.1 ? 'trend-down' : 'trend-flat';
-    const selectedClass = selectedSkill === name ? 'selected' : '';
-
-    const safeName = escapeHtml(name);
-    return `<div class="skill-health-card ${selectedClass}" data-skill="${safeName}" role="button" tabindex="0" aria-label="View details for skill ${safeName}">
-      <div class="skill-card-top">
-        <div class="skill-name" title="${safeName}">${safeName}</div>
-        <span class="skill-status-dot ${status}"></span>
-      </div>
-      <div class="skill-pass-rate ${status}">${pct}%</div>
-      <div class="skill-trend ${trendClass}">${trendSymbol} ${delta === null ? 'No baseline' : `${Math.abs(delta).toFixed(1)}pp vs baseline`}</div>
-      <div class="skill-card-meta">
-        <span>${evalCount.toLocaleString()} evaluations</span>
-        ${getStatusBadge(status)}
-      </div>
-    </div>`;
-  }).join('');
-
-  // Click + keyboard handlers for drill-down
-  grid.querySelectorAll('.skill-health-card').forEach(row => {
-    const handler = () => {
-      const skillName = row.dataset.skill;
-      if (isLiveMode()) {
-        window.location.href = `/report/${encodeURIComponent(skillName)}`;
-        return;
-      }
-      grid.querySelectorAll('.skill-health-card').forEach(r => r.classList.remove('selected'));
-      row.classList.add('selected');
-      openDrillDown(skillName);
-    };
-    row.addEventListener('click', handler);
-    row.addEventListener('keydown', e => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); handler(); } });
-  });
-
-  // Reapply search filter after grid rebuild
-  const searchInput = document.getElementById('skillSearchInput');
-  if (searchInput && searchInput.value) {
-    const query = searchInput.value.toLowerCase();
-    grid.querySelectorAll('.skill-health-card').forEach(row => {
-      const name = (row.dataset.skill || '').toLowerCase();
-      row.style.display = name.includes(query) ? '' : 'none';
-    });
-  }
-
-  if (!selectedSkill && sorted.length) {
-    const first = sorted[0];
-    const firstCard = grid.querySelector('.skill-health-card');
-    if (firstCard) firstCard.classList.add('selected');
-    openDrillDown(first);
-  }
-}
-
-// ========================================================================
-// Drill-down panel
-// ========================================================================
-function openDrillDown(skillName) {
-  selectedSkill = skillName;
-  const panel = document.getElementById('drillDownPanel');
-  panel.classList.add('visible');
-  document.getElementById('drillDownTitle').textContent = skillName;
-  document.getElementById('drillDownSubtitle').textContent = 'Pass rate trend, missed prompts, session evidence, and invocation breakdown.';
-
-  // Pass rate over time chart
-  updateDrillPassRateChart(skillName);
-  updateDrillMissedQueries(skillName);
-  updateDrillEvolution(skillName);
-  updateDrillVersionHistory(skillName);
-  updateDrillValidationEvidence(skillName);
-  updateDrillSessions(skillName);
-  updateDrillEvalFeed(skillName);
-  updateDrillInvocationBreakdown(skillName);
-}
-
-document.getElementById('drillDownClose').addEventListener('click', () => {
-  document.getElementById('drillDownPanel').classList.remove('visible');
-  document.getElementById('skillHealthGrid').querySelectorAll('.skill-health-card').forEach(r => r.classList.remove('selected'));
-  selectedSkill = null;
-});
-
-function updateDrillPassRateChart(skillName) {
-  // Group skill records by day and compute daily pass rate
-  const allRecords = state.skills.filter(r => r.skill_name === skillName);
-  const records = filterByPeriod(allRecords, selectedPeriodDays);
-  const byDay = {};
-  for (const r of records) {
-    const day = toDayKey(r.timestamp);
-    if (!byDay[day]) byDay[day] = { triggered: 0, total: 0 };
-    byDay[day].total++;
-    if (r.triggered) byDay[day].triggered++;
-  }
-
-  const dayKeys = Object.keys(byDay).sort();
-  const labels = dayKeys.map(d => formatDate(d + "T00:00:00Z"));
-  const data = dayKeys.map(d => ((byDay[d].triggered / byDay[d].total) * 100).toFixed(1));
-
-  // Deploy events as annotations
-  const deployDays = new Set(
-    state.evolution
-      .filter(e => e.action === 'deployed' && (e.details || '').toLowerCase().includes(skillName.toLowerCase()))
-      .map(e => toDayKey(e.timestamp))
-  );
-
-  const pointColors = dayKeys.map(d => deployDays.has(d) ? '#d97757' : '#788c5d');
-  const pointSizes = dayKeys.map(d => deployDays.has(d) ? 8 : 3);
-
-  if (charts.drillPassRate) charts.drillPassRate.destroy();
-  charts.drillPassRate = new Chart(document.getElementById('chartDrillPassRate'), {
-    type: 'line',
-    data: {
-      labels,
-      datasets: [{
-        label: 'Pass Rate %',
-        data,
-        borderColor: '#788c5d',
-        backgroundColor: 'rgba(120, 140, 93, 0.1)',
-        fill: true,
-        tension: 0.3,
-        pointRadius: pointSizes,
-        pointBackgroundColor: pointColors,
-      }]
-    },
-    options: {
-      responsive: true,
-      maintainAspectRatio: false,
-      plugins: { legend: { display: false } },
-      scales: {
-        y: { min: 0, max: 100, ticks: { callback: v => v + '%' } },
-        x: { grid: { display: false } }
-      }
-    }
-  });
-}
-
-function updateDrillMissedQueries(skillName) {
-  const missed = state.skills.filter(r => r.skill_name === skillName && !r.triggered);
-  const tbody = document.querySelector('#drillMissedTable tbody');
-  tbody.innerHTML = missed.slice(0, 50).map(r => `<tr>
-    <td class="mono">${escapeHtml(formatTimestamp(r.timestamp))}</td>
-    <td class="mono">${escapeHtml((r.session_id || '').slice(0, 8))}</td>
-    <td>${escapeHtml(truncate(r.query, 50))}</td>
-  </tr>`).join('') || '<tr><td colspan="3" class="empty-state">No missed queries</td></tr>';
-}
-
-function updateDrillEvolution(skillName) {
-  const needle = skillName.toLowerCase();
-  const entries = state.evolution.filter(e => (e.details || '').toLowerCase().includes(needle));
-  const container = document.getElementById('drillEvoTimeline');
-  const actionBadge = {
-    created: 'badge-blue', validated: 'badge-amber', deployed: 'badge-green',
-    rolled_back: 'badge-red', rejected: 'badge-red',
-  };
-  if (entries.length) {
-    const sorted = [...entries].sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
-    container.innerHTML = sorted.map(r => `<div class="timeline-item">
-      <div class="timeline-date">${escapeHtml(formatTimestamp(r.timestamp))}</div>
-      <div><span class="badge ${actionBadge[r.action] || 'badge-blue'}">${escapeHtml(r.action)}</span>
-        <span class="timeline-action" style="margin-left:0.5rem">${escapeHtml(r.proposal_id.slice(0, 8))}</span>
-      </div>
-      <div style="flex:1;color:var(--text-secondary);font-size:0.8125rem;">${escapeHtml(truncate(r.details, 60))}</div>
-    </div>`).join('');
-  } else {
-    container.innerHTML = '<div class="empty-state">No evolution history for this skill</div>';
-  }
-}
-
-function getMergedEvidenceForSkill(skillName) {
-  const merged = new Map();
-  const entries = state.evidence
-    .filter(r => r.skill_name === skillName)
-    .sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
-
-  for (const entry of entries) {
-    if (!merged.has(entry.proposal_id)) {
-      merged.set(entry.proposal_id, {
-        proposal_id: entry.proposal_id,
-        target: entry.target,
-        rationale: entry.rationale || '',
-        confidence: entry.confidence,
-        original_text: entry.original_text || '',
-        proposed_text: entry.proposed_text || '',
-        eval_set: entry.eval_set || [],
-        validation: entry.validation || null,
-        stages: [],
-        latest_timestamp: entry.timestamp,
-      });
-    }
-
-    const current = merged.get(entry.proposal_id);
-    current.stages.push({
-      stage: entry.stage,
-      timestamp: entry.timestamp,
-      details: entry.details || '',
-    });
-    if (!current.rationale && entry.rationale) current.rationale = entry.rationale;
-    if (current.confidence === undefined && entry.confidence !== undefined) current.confidence = entry.confidence;
-    if (!current.original_text && entry.original_text) current.original_text = entry.original_text;
-    if (!current.proposed_text && entry.proposed_text) current.proposed_text = entry.proposed_text;
-    if ((!current.eval_set || !current.eval_set.length) && entry.eval_set) current.eval_set = entry.eval_set;
-    if (!current.validation && entry.validation) current.validation = entry.validation;
-  }
-
-  return [...merged.values()].sort((a, b) => new Date(b.latest_timestamp) - new Date(a.latest_timestamp));
-}
-
-function updateDrillVersionHistory(skillName) {
-  const container = document.getElementById('drillVersionHistory');
-  const proposals = getMergedEvidenceForSkill(skillName);
-
-  if (!proposals.length) {
-    container.innerHTML = '<div class="empty-state">No proposal artifacts recorded</div>';
-    return;
-  }
-
-  container.innerHTML = proposals.slice(0, 8).map((proposal, index) => {
-    const validation = proposal.validation || {};
-    const before = typeof validation.before_pass_rate === 'number' ? `${(validation.before_pass_rate * 100).toFixed(1)}%` : '—';
-    const after = typeof validation.after_pass_rate === 'number' ? `${(validation.after_pass_rate * 100).toFixed(1)}%` : '—';
-    const net = typeof validation.net_change === 'number' ? `${validation.net_change >= 0 ? '+' : ''}${(validation.net_change * 100).toFixed(1)}pp` : '—';
-    const stages = proposal.stages
-      .sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp))
-      .map(s => `${s.stage} ${formatTimestamp(s.timestamp)}`)
-      .join(' · ');
-    return `<details class="evidence-card" ${index === 0 ? 'open' : ''}>
-      <summary>
-        <div style="display:flex;justify-content:space-between;gap:1rem;align-items:flex-start;">
-          <div>
-            <div style="font-weight:700;color:var(--text);">${escapeHtml(proposal.proposal_id)}</div>
-            <div class="evidence-meta">
-              <span>${escapeHtml(proposal.target || 'description')}</span>
-              <span>${proposal.confidence !== undefined ? `conf ${proposal.confidence.toFixed(2)}` : 'no confidence'}</span>
-              <span>${escapeHtml(stages || 'no stages')}</span>
-            </div>
-          </div>
-          <div class="evidence-summary">
-            <span class="evidence-chip">Before ${before}</span>
-            <span class="evidence-chip">After ${after}</span>
-            <span class="evidence-chip">Net ${net}</span>
-          </div>
-        </div>
-      </summary>
-      <div class="evidence-meta" style="margin-top:0.75rem;">${escapeHtml(proposal.rationale || 'No rationale recorded')}</div>
-      <div class="evidence-diff">
-        <div class="evidence-block">
-          <h5>Original</h5>
-          <pre>${escapeHtml(proposal.original_text || 'No original text recorded')}</pre>
-        </div>
-        <div class="evidence-block">
-          <h5>Proposed</h5>
-          <pre>${escapeHtml(proposal.proposed_text || 'No proposed text recorded')}</pre>
-        </div>
-      </div>
-    </details>`;
-  }).join('');
-}
-
-function updateDrillValidationEvidence(skillName) {
-  const tbody = document.querySelector('#drillEvidenceTable tbody');
-  const proposals = getMergedEvidenceForSkill(skillName);
-  const latest = proposals.find(p => p.validation && p.validation.per_entry_results && p.validation.per_entry_results.length);
-
-  if (!latest || !latest.validation || !latest.validation.per_entry_results) {
-    tbody.innerHTML = '<tr><td colspan="5" class="empty-state">No per-eval validation evidence recorded</td></tr>';
-    return;
-  }
-
-  tbody.innerHTML = latest.validation.per_entry_results.slice(0, 100).map(result => {
-    const expected = result.entry.should_trigger ? 'Yes' : 'No';
-    const before = result.before_pass ? 'Yes' : 'No';
-    const after = result.after_pass ? 'Yes' : 'No';
-    const delta = result.before_pass === result.after_pass
-      ? 'Unchanged'
-      : result.after_pass
-        ? 'New pass'
-        : 'Regression';
-    const deltaBadge = delta === 'New pass'
-      ? '<span class="badge badge-healthy">New pass</span>'
-      : delta === 'Regression'
-        ? '<span class="badge badge-critical">Regression</span>'
-        : '<span class="badge badge-unknown">Unchanged</span>';
-    return `<tr>
-      <td>${escapeHtml(truncate(result.entry.query, 80))}</td>
-      <td>${escapeHtml(expected)}</td>
-      <td>${escapeHtml(before)}</td>
-      <td>${escapeHtml(after)}</td>
-      <td>${deltaBadge}</td>
-    </tr>`;
-  }).join('');
-}
-
-function updateDrillSessions(skillName) {
-  const sessionIds = new Set(
-    state.skills.filter(r => r.skill_name === skillName).map(r => r.session_id)
-  );
-  const sessions = state.telemetry.filter(r => sessionIds.has(r.session_id));
-  const tbody = document.querySelector('#drillSessionsTable tbody');
-  const sorted = [...sessions].sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
-  tbody.innerHTML = sorted.slice(0, 30).map(r => {
-    const skills = (r.skills_triggered || []).join(', ') || '\u2014';
-    const errorCount = Number.isFinite(Number(r.errors_encountered)) ? Number(r.errors_encountered) : 0;
-    const totalToolCalls = Number.isFinite(Number(r.total_tool_calls)) ? Number(r.total_tool_calls) : 0;
-    const errorBadge = errorCount > 0
-      ? `<span class="badge badge-red">${errorCount}</span>`
-      : '<span class="badge badge-green">0</span>';
-    return `<tr>
-      <td class="mono">${escapeHtml(formatTimestamp(r.timestamp))}</td>
-      <td>${totalToolCalls}</td>
-      <td>${escapeHtml(truncate(skills, 30))}</td>
-      <td>${errorBadge}</td>
-    </tr>`;
-  }).join('') || '<tr><td colspan="4" class="empty-state">No sessions</td></tr>';
-}
-
-// ========================================================================
-// Unmatched queries section
-// ========================================================================
-function updateUnmatched() {
-  const computed = state.computed;
-  if (!computed) return;
-  const unmatched = computed.unmatched || [];
-  const section = document.getElementById('unmatchedSection');
-  if (!unmatched.length) {
-    section.style.display = 'none';
-    return;
-  }
-
-  section.style.display = 'block';
-  const tbody = document.querySelector('#unmatchedTable tbody');
-  tbody.innerHTML = unmatched.slice(0, 100).map(q => `<tr>
-    <td class="mono">${escapeHtml(formatTimestamp(q.timestamp))}</td>
-    <td class="mono">${escapeHtml((q.session_id || '').slice(0, 8))}</td>
-    <td>${escapeHtml(truncate(q.query, 60))}</td>
-  </tr>`).join('');
-}
-
-// ========================================================================
-// Recent evolution section
-// ========================================================================
-function updateEvolutionFeed() {
-  const entries = [...state.evolution].sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
-  const section = document.getElementById('evolutionFeedSection');
-  const container = document.getElementById('evolutionFeed');
-  if (!entries.length) {
-    section.style.display = 'none';
-    return;
-  }
-
-  section.style.display = 'block';
-  const actionBadge = {
-    created: 'badge-blue',
-    validated: 'badge-amber',
-    deployed: 'badge-green',
-    rolled_back: 'badge-red',
-    rejected: 'badge-red',
-  };
-  container.innerHTML = entries.slice(0, 12).map(r => `<div class="timeline-item">
-    <div class="timeline-date">${escapeHtml(formatTimestamp(r.timestamp))}</div>
-    <div><span class="badge ${actionBadge[r.action] || 'badge-blue'}">${escapeHtml(r.action)}</span>
-      <span class="timeline-action" style="margin-left:0.5rem">${escapeHtml(r.proposal_id.slice(0, 8))}</span>
-    </div>
-    <div style="flex:1;color:var(--text-secondary);font-size:0.8125rem;">${escapeHtml(truncate(r.details, 80))}</div>
-  </div>`).join('');
-}
-
-// ========================================================================
-// CSV export
-// ========================================================================
-document.getElementById('exportCsvBtn').addEventListener('click', () => {
-  if (!state.computed || !state.computed.snapshots) return;
-  const snapshots = state.computed.snapshots;
-  const headers = ['skill_name','skill_checks','pass_rate','regression_detected','baseline_pass_rate','window_sessions','false_negative_rate'];
-  const rows = Object.keys(snapshots).map(name => {
-    const s = snapshots[name];
-    return headers.map(h => {
-      const v = s[h];
-      if (typeof v === 'boolean') return v ? 'true' : 'false';
-      if (typeof v === 'number') return v.toFixed(4);
-      if (typeof v === 'string' && (v.includes(',') || v.includes('"')))
-        return '"' + v.replace(/"/g, '""') + '"';
-      return v ?? '';
-    }).join(',');
-  });
-  const csv = [headers.join(','), ...rows].join('\n');
-  const blob = new Blob([csv], { type: 'text/csv' });
-  const a = document.createElement('a');
-  a.href = URL.createObjectURL(blob);
-  a.download = 'selftune-skill-health.csv';
-  a.click();
-});
-
-// ========================================================================
-// Live mode: SSE client + action buttons + evolution timeline
-// ========================================================================
-let sseSource = null;
-
-function isLiveMode() {
-  return window.__SELFTUNE_LIVE__ === true;
-}
-
-function startSSE() {
-  if (!isLiveMode()) return;
-  if (sseSource) { sseSource.close(); sseSource = null; }
-
-  sseSource = new EventSource('/api/events');
-  sseSource.addEventListener('data', (e) => {
-    try {
-      const data = JSON.parse(e.data);
-      state.liveLoading = false;
-      if (data.telemetry) state.telemetry = data.telemetry;
-      if (data.skills) state.skills = data.skills;
-      if (data.queries) state.queries = data.queries;
-      if (data.evolution) state.evolution = data.evolution;
-      if (data.evidence) state.evidence = data.evidence;
-      if (data.decisions) state.decisions = data.decisions;
-      if (data.counts) state.counts = data.counts;
-      if (data.computed) {
-        state.computed = data.computed;
-      } else {
-        state.computed = computeClientSide();
-      }
-      refreshAll();
-      updateEvolutionTimeline();
-    } catch (err) { console.warn('[selftune] SSE parse error:', err); }
-  });
-  sseSource.onerror = () => {
-    // Reconnect after 3 seconds on error
-    setTimeout(() => { if (isLiveMode()) startSSE(); }, 3000);
-  };
-}
-
-// Decisions state (populated from server in live mode)
-if (!state.decisions) state.decisions = [];
-
-function updateEvolutionTimeline() {
-  if (!isLiveMode()) return;
-  const decisions = state.decisions || [];
-  const section = document.getElementById('evoTimelineSection');
-  if (!section) return;
-
-  section.style.display = 'block';
-  const container = document.getElementById('evoTimeline');
-  if (!decisions.length) {
-    container.innerHTML = '<div class="empty-state">No evolution decisions recorded</div>';
-    return;
-  }
-
-  // Show most recent first
-  const sorted = [...decisions].reverse();
-  container.innerHTML = sorted.slice(0, 50).map(d => {
-    const actionClass = 'action-' + escapeHtml(d.action || '');
-    return `<div class="evo-timeline-item ${actionClass}">
-      <div class="evo-timeline-meta">${escapeHtml(formatTimestamp(d.timestamp))} &middot; ${escapeHtml(d.skillName)}</div>
-      <div class="evo-timeline-body">
-        <span class="badge ${d.action === 'evolved' ? 'badge-green' : d.action === 'rolled-back' ? 'badge-red' : 'badge-blue'}">${escapeHtml(d.action)}</span>
-        <span style="margin-left:0.375rem;">${escapeHtml(d.actionType)}</span>
-      </div>
-      <div class="evo-timeline-rationale">${escapeHtml(truncate(d.rationale, 100))}</div>
-    </div>`;
-  }).join('');
-}
-
-function showActionButtons(skillName) {
-  if (!isLiveMode()) return;
-  const section = document.getElementById('actionsSection');
-  const body = document.getElementById('actionsBody');
-  if (!section || !body) return;
-
-  section.style.display = 'block';
-
-  // Find skill path from skill records
-  const skillRecord = state.skills.find(r => r.skill_name === skillName);
-  const skillPath = skillRecord ? skillRecord.skill_path : '';
-  const safeSkill = escapeHtml(skillName);
-  const safeSkillPath = escapeHtml(skillPath);
-
-  body.innerHTML = `
-    <div style="margin-bottom:0.5rem;font-family:var(--font-sans);font-size:0.8125rem;font-weight:600;">${safeSkill}</div>
-    <div class="action-btn-group">
-      <button class="action-btn" id="btn-watch" data-skill="${safeSkill}" data-path="${safeSkillPath}">Watch</button>
-      <button class="action-btn" id="btn-evolve" data-skill="${safeSkill}" data-path="${safeSkillPath}">Evolve</button>
-      <button class="action-btn" id="btn-rollback" data-skill="${safeSkill}" data-path="${safeSkillPath}">Rollback</button>
-    </div>
-    <div class="action-result" id="action-result"></div>
-  `;
-
-  // Bind action handlers
-  document.getElementById('btn-watch').addEventListener('click', () => runSkillAction('watch', skillName, skillPath));
-  document.getElementById('btn-evolve').addEventListener('click', () => runSkillAction('evolve', skillName, skillPath));
-  document.getElementById('btn-rollback').addEventListener('click', () => runSkillAction('rollback', skillName, skillPath));
-}
-
-async function runSkillAction(action, skill, skillPath) {
-  const btn = document.getElementById('btn-' + action);
-  const resultEl = document.getElementById('action-result');
-  if (!btn || !resultEl) return;
-
-  // Set loading state
-  btn.classList.add('loading');
-  btn.disabled = true;
-  btn.textContent = '...';
-  resultEl.className = 'action-result';
-  resultEl.style.display = 'none';
-
-  try {
-    const payload = { skill, skillPath };
-    if (action === 'rollback') {
-      // For rollback, find the latest pending proposal
-      const pending = (state.computed && state.computed.pendingProposals) || [];
-      const needle = skill.toLowerCase();
-      const match = pending.find(p => (p.details || '').toLowerCase().includes(needle));
-      if (match) payload.proposalId = match.proposal_id;
-    }
-
-    const res = await fetch('/api/actions/' + action, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
-    });
-    const data = await res.json();
-
-    resultEl.style.display = 'block';
-    if (data.success) {
-      resultEl.className = 'action-result visible success';
-      resultEl.textContent = data.output || 'Action completed successfully';
-    } else {
-      resultEl.className = 'action-result visible error';
-      resultEl.textContent = data.error || data.output || 'Action failed';
-    }
-  } catch (err) {
-    resultEl.style.display = 'block';
-    resultEl.className = 'action-result visible error';
-    resultEl.textContent = 'Network error: ' + (err.message || err);
-  } finally {
-    btn.classList.remove('loading');
-    btn.disabled = false;
-    btn.textContent = action.charAt(0).toUpperCase() + action.slice(1);
-  }
-}
-
-// ========================================================================
-// Search filter
-// ========================================================================
-document.getElementById('skillSearchInput').addEventListener('input', function() {
-  const query = this.value.toLowerCase();
-  document.querySelectorAll('.skill-health-card').forEach(row => {
-    const name = (row.dataset.skill || '').toLowerCase();
-    row.style.display = name.includes(query) ? '' : 'none';
-  });
-});
-
-// ========================================================================
-// Evaluation Feed
-// ========================================================================
-function updateDrillEvalFeed(skillName) {
-  const records = state.skills.filter(r => r.skill_name === skillName);
-  const sorted = [...records].sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
-  const tbody = document.querySelector('#drillEvalFeed tbody');
-  tbody.innerHTML = sorted.slice(0, 50).map(r => {
-    const triggeredBadge = r.triggered
-      ? '<span class="badge badge-healthy">Yes</span>'
-      : '<span class="badge badge-critical">No</span>';
-    const sourceType = escapeHtml(r.source || r.type || 'implicit');
-    return `<tr>
-      <td class="mono">${escapeHtml(formatTimestamp(r.timestamp))}</td>
-      <td>${escapeHtml(truncate(r.query, 50))}</td>
-      <td>${triggeredBadge}</td>
-      <td class="mono">${sourceType}</td>
-    </tr>`;
-  }).join('') || '<tr><td colspan="4" class="empty-state">No evaluations</td></tr>';
-}
-
-// ========================================================================
-// Invocation Breakdown
-// ========================================================================
-function updateDrillInvocationBreakdown(skillName) {
-  const computed = state.computed;
-  const snapshot = computed && computed.snapshots ? computed.snapshots[skillName] : null;
-  const byType = (snapshot && snapshot.by_invocation_type) || {};
-
-  // If no invocation type data, compute from skill records
-  let labels, values;
-  if (Object.keys(byType).length > 0) {
-    labels = Object.keys(byType);
-    values = Object.values(byType);
-  } else {
-    // Fallback: count source/type fields from skill records
-    const records = state.skills.filter(r => r.skill_name === skillName);
-    const counts = {};
-    for (const r of records) {
-      const t = r.source || r.type || 'implicit';
-      counts[t] = (counts[t] || 0) + 1;
-    }
-    labels = Object.keys(counts);
-    values = Object.values(counts);
-  }
-
-  if (charts.invocationBreakdown) charts.invocationBreakdown.destroy();
-
-  if (!labels.length) return;
-
-  charts.invocationBreakdown = new Chart(document.getElementById('chartInvocationBreakdown'), {
-    type: 'doughnut',
-    data: {
-      labels,
-      datasets: [{
-        data: values,
-        backgroundColor: CHART_COLORS.slice(0, labels.length),
-        borderWidth: 1,
-        borderColor: '#fff',
-      }]
-    },
-    options: {
-      responsive: true,
-      maintainAspectRatio: false,
-      plugins: {
-        legend: {
-          position: 'right',
-          labels: {
-            font: { family: '"Avenir Next", "Segoe UI", "Helvetica Neue", sans-serif', size: 11 },
-            padding: 12,
-          }
-        }
-      }
-    }
-  });
-}
-
-// ========================================================================
-// Time period filtering
-// ========================================================================
-function filterByPeriod(records, days) {
-  if (!days || days === 0) return records;
-  // Anchor cutoff to latest timestamp in dataset, not viewer's clock,
-  // so archived/historical datasets filter correctly.
-  const latest = records.reduce((max, r) => {
-    const t = new Date(r.timestamp).getTime();
-    return t > max ? t : max;
-  }, 0);
-  if (!latest) return records;
-  const cutoff = new Date(latest);
-  cutoff.setDate(cutoff.getDate() - days);
-  return records.filter(r => new Date(r.timestamp) >= cutoff);
-}
-
-document.getElementById('timePeriodSelector').addEventListener('click', function(e) {
-  const btn = e.target.closest('.period-btn');
-  if (!btn) return;
-  this.querySelectorAll('.period-btn').forEach(b => b.classList.remove('active'));
-  btn.classList.add('active');
-  selectedPeriodDays = parseInt(btn.dataset.days, 10);
-  if (selectedSkill) {
-    updateDrillPassRateChart(selectedSkill);
-  }
-});
-
-// Hook into drill-down to show action buttons in live mode
-const origOpenDrillDown = typeof openDrillDown === 'function' ? openDrillDown : null;
-openDrillDown = function(skillName) {
-  if (origOpenDrillDown) origOpenDrillDown(skillName);
-  showActionButtons(skillName);
-};
-
-function initLiveMode() {
-  if (!isLiveMode()) return;
-  // Show live sections
-  document.getElementById('actionsSection').style.display = 'block';
-  state.liveLoading = true;
-  refreshAll();
-
-  startSSE();
-  updateEvolutionTimeline();
-}
-
-// ========================================================================
-// Init: try loading embedded data
-// ========================================================================
-window.addEventListener('DOMContentLoaded', () => {
-  loadEmbeddedData();
-  refreshAll();
-  initLiveMode();
-});
-</script>
-
-</body>
-</html>
diff --git a/docs/design-docs/sandbox-claude-code.md b/docs/design-docs/sandbox-claude-code.md
index f9f7145..21afaa8 100644
--- a/docs/design-docs/sandbox-claude-code.md
+++ b/docs/design-docs/sandbox-claude-code.md
@@ -23,7 +23,7 @@ Claude Code-specific sandbox configuration, tests, and Docker container. See [sa
 | `evals --skill frontend-design` | 0 positives (correctly identifies undertriggering) |
 | `status` | Colored table with per-skill health |
 | `last` | Latest session insight with unmatched queries |
-| `dashboard --export` | Standalone HTML with embedded data |
+| `dashboard --port <port> --no-open` | Starts the SPA dashboard server and responds on HTTP |
 | `contribute --preview` | Sanitized contribution bundle |
 | Hook: prompt-log | Record appended to all_queries_log.jsonl |
 | Hook: skill-eval | Record appended to skill_usage_log.jsonl |
diff --git a/docs/design-docs/sandbox-test-harness.md b/docs/design-docs/sandbox-test-harness.md
index 7aba544..f021fb7 100644
--- a/docs/design-docs/sandbox-test-harness.md
+++ b/docs/design-docs/sandbox-test-harness.md
@@ -30,7 +30,7 @@ selftune had 499 unit tests covering individual functions, but zero integration
 | `evals --skill frontend-design` | 0 positives (correctly identifies undertriggering) |
 | `status` | Colored table with per-skill health |
 | `last` | Latest session insight with unmatched queries |
-| `dashboard --export` | Standalone HTML with embedded data |
+| `dashboard --port <port> --no-open` | Starts the SPA dashboard server and responds on HTTP |
 | `contribute --preview` | Sanitized contribution bundle |
 | Hook: prompt-log | Record appended to all_queries_log.jsonl |
 | Hook: skill-eval | Record appended to skill_usage_log.jsonl |
diff --git a/docs/escalation-policy.md b/docs/escalation-policy.md
index ce20be0..30930cc 100644
--- a/docs/escalation-policy.md
+++ b/docs/escalation-policy.md
@@ -52,8 +52,8 @@ Clear criteria for when agents proceed autonomously vs. when to involve a human.
 - Modifying the SKILL.md routing table (affects which workflow agents load)
 - Changing `computeStatus` logic in `status.ts` (affects skill health reporting)
 - Changing `computeLastInsight` logic in `last.ts` (affects session insight accuracy)
-- Modifying dashboard data schema in `dashboard.ts` (breaks `dashboard/index.html` rendering)
-- Changing the `dashboard/index.html` embedded data contract (must match `dashboard.ts` output)
+- Modifying the dashboard response contract in `dashboard-contract.ts`
+- Changing SQLite-backed dashboard query shapes in `cli/selftune/localdb/queries.ts`
 - Modifying activation rules configuration
 - Changing agent assignment logic
 - Updating dashboard server endpoints or action handlers
diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.md
index 4badcf7..790fa3c 100644
--- a/docs/exec-plans/tech-debt-tracker.md
+++ b/docs/exec-plans/tech-debt-tracker.md
@@ -17,7 +17,7 @@ Track known technical debt with priority and ownership.
 | TD-009 | Add evolution/monitoring to lint-architecture.ts import rules | Infra | Medium | — | Closed | 2026-02-28 | 2026-02-28 |
 | TD-010 | `cli/selftune/utils/logging.ts` has no test file — violates golden-principles testing rule | Testing | Medium | — | Open | 2026-03-01 | 2026-03-01 |
 | TD-011 | `cli/selftune/utils/seeded-random.ts` has no test file — violates golden-principles testing rule | Testing | Medium | — | Open | 2026-03-01 | 2026-03-01 |
-| TD-012 | Dashboard server test (`tests/dashboard/dashboard-server.test.ts`) is flaky — `GET /api/events` sends initial data event fails intermittently with `null` response | Testing | Medium | — | Open | 2026-03-03 | 2026-03-03 |
+| TD-012 | Dashboard server test (`tests/dashboard/dashboard-server.test.ts`) was flaky around legacy SSE `/api/events` behavior | Testing | Medium | — | Closed | 2026-03-03 | 2026-03-14 |
 
 ## Priority Definitions
 
diff --git a/package.json b/package.json
index 949820c..2a47a74 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,6 @@
     "bin/",
     "cli/selftune/",
     "apps/local-dashboard/dist/",
-    "dashboard/",
     "packages/telemetry-contract/",
     "templates/",
     ".claude/agents/",
@@ -51,7 +50,7 @@
   ],
   "scripts": {
     "dev": "sh -c 'if lsof -iTCP:7888 -sTCP:LISTEN >/dev/null 2>&1; then echo \"Using existing dashboard server on 7888\"; cd apps/local-dashboard && bun install && bunx vite --strictPort; else cd apps/local-dashboard && bun install && bun run dev; fi'",
-    "dev:dashboard": "bun run dev",
+    "dev:dashboard": "bun run cli/selftune/index.ts dashboard --port 7888 --no-open",
     "lint": "bunx @biomejs/biome check .",
     "lint:fix": "bunx @biomejs/biome check --write .",
     "lint:arch": "bun run lint-architecture.ts",
diff --git a/skill/SKILL.md b/skill/SKILL.md
index ac76605..18e6ae9 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -32,7 +32,7 @@ selftune <command> [options]
 ```
 
 Most commands output deterministic JSON. Parse JSON output for machine-readable commands.
-`selftune dashboard` is an exception: it generates an HTML artifact and may print
+`selftune dashboard` is an exception: it starts a local SPA server and may print
 informational progress lines.
 
 ## Quick Reference
@@ -46,7 +46,7 @@ selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
 selftune status
 selftune last
 selftune doctor
-selftune dashboard [--export] [--out FILE] [--serve]
+selftune dashboard [--port <port>] [--no-open]
 selftune ingest-codex
 selftune ingest-opencode
 selftune ingest-openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]
@@ -57,7 +57,7 @@ selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
 selftune cron setup [--dry-run] [--tz <timezone>]
 selftune cron list
 selftune cron remove [--dry-run]
-selftune dashboard --serve [--port <port>]
+selftune dashboard [--port <port>] [--no-open]
 selftune evolve-body --skill <name> --skill-path <path> --target <routing_table|full_body> [--dry-run]
 selftune baseline   --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]
 selftune badge      --skill <name> [--format svg|markdown|url] [--output <path>]
diff --git a/skill/Workflows/Dashboard.md b/skill/Workflows/Dashboard.md
index 2b86070..8ecd252 100644
--- a/skill/Workflows/Dashboard.md
+++ b/skill/Workflows/Dashboard.md
@@ -1,9 +1,7 @@
 # selftune Dashboard Workflow
 
-Visual dashboard for selftune telemetry, skill performance, evolution
-audit, and monitoring data. The default dashboard is a React SPA backed
-by SQLite materialized queries (v2 API). Also supports static HTML
-export, file output, and a legacy HTML dashboard.
+Open and operate the local selftune dashboard. The supported dashboard is the
+React SPA backed by SQLite materialized queries.
 
 ## Default Command
 
@@ -11,40 +9,15 @@ export, file output, and a legacy HTML dashboard.
 selftune dashboard
 ```
 
-Starts the dashboard server and opens the React SPA in the browser.
-The SPA polls SQLite-backed v2 API endpoints every 15 seconds.
+Starts the dashboard server on `localhost:3141` and opens the SPA in your browser.
 
 ## Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--export` | Export data-embedded HTML to stdout (legacy) | Off |
-| `--out FILE` | Write data-embedded HTML to FILE (legacy) | None |
-| `--serve` | Start live dashboard server (implied by default) | Off |
-| `--port <port>` | Custom port for the server | 3141 |
-
-## Modes
-
-### Live Server (Default)
-
-Starts a Bun HTTP server. The React SPA serves at `/` and polls the
-v2 API endpoints backed by SQLite. Data auto-refreshes every 15 seconds.
-
-```bash
-selftune dashboard
-selftune dashboard --port 8080
-```
-
-### Legacy Static
-
-Builds an HTML file with all telemetry data embedded as JSON, saves it
-to `~/.selftune/dashboard.html`, and opens it in the default browser.
-The legacy dashboard is still accessible at `/legacy/` on the live server.
-
-```bash
-selftune dashboard --export > dashboard.html
-selftune dashboard --out /tmp/report.html
-```
+| `--port <port>` | Custom port for the dashboard server | `3141` |
+| `--no-open` | Start the server without opening a browser window | Off |
+| `--serve` | Deprecated alias for the default behavior | Off |
 
 ## Server Architecture
 
@@ -54,176 +27,55 @@ selftune dashboard --out /tmp/report.html
 JSONL logs → materializeIncremental() → SQLite (~/.selftune/selftune.db)
   → getOverviewPayload() / getSkillReportPayload()
     → /api/v2/* endpoints
-      → React SPA (polling every 15s)
+      → React SPA
 ```
 
-### Default Port
-
-The server binds to `localhost:3141` by default. Use `--port` to override.
-
 ### Endpoints
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/` | Serve React SPA (production build) |
-| `GET` | `/legacy/` | Serve legacy HTML dashboard |
-| `GET` | `/api/v2/overview` | Combined overview payload + skill list (SQLite) |
-| `GET` | `/api/v2/skills/:name` | Per-skill report payload (SQLite) |
-| `GET` | `/api/data` | Legacy JSON endpoint (v1, JSONL-based) |
-| `GET` | `/api/events` | Legacy SSE stream (v1) |
+| `GET` | `/` | Serve React SPA |
+| `GET` | `/api/v2/overview` | Overview payload + skill list |
+| `GET` | `/api/v2/skills/:name` | Per-skill report payload |
 | `GET` | `/badge/:name` | Skill health badge SVG |
-| `GET` | `/report/:name` | Per-skill HTML report |
+| `GET` | `/report/:name` | Server-rendered per-skill HTML report |
 | `POST` | `/api/actions/watch` | Trigger `selftune watch` for a skill |
 | `POST` | `/api/actions/evolve` | Trigger `selftune evolve` for a skill |
 | `POST` | `/api/actions/rollback` | Trigger `selftune rollback` for a skill |
 
-### Action Endpoints
-
-Action buttons in the dashboard trigger selftune commands via POST
-requests. Each endpoint spawns a `bun run` subprocess.
-
-**Watch and Evolve** request body:
-
-```json
-{
-  "skill": "skill-name",
-  "skillPath": "/path/to/SKILL.md"
-}
-```
-
-**Rollback** request body:
-
-```json
-{
-  "skill": "skill-name",
-  "skillPath": "/path/to/SKILL.md",
-  "proposalId": "proposal-uuid"
-}
-```
-
-All action endpoints return:
-
-```json
-{
-  "success": true,
-  "output": "command stdout",
-  "error": null
-}
-```
-
-On failure, `success` is `false` and `error` contains the error message.
-
-### Browser and Shutdown
-
-The live server auto-opens the dashboard URL in the default browser on
-macOS (`open`) and Linux (`xdg-open`).
-
-Graceful shutdown on `SIGINT` (Ctrl+C) and `SIGTERM`: closes all SSE
-client connections and stops the server.
-
-## Data Contents
-
-The SPA dashboard displays data materialized into SQLite from these sources:
-
-| Data | Source | SQLite Table | Description |
-|------|--------|-------------|-------------|
-| Telemetry | `session_telemetry_log.jsonl` | `sessions` | Session-level telemetry records |
-| Skills | `skill_usage_log.jsonl` | `skill_usages` | Skill activation and usage events |
-| Queries | `all_queries_log.jsonl` | `queries` | All user queries across sessions |
-| Evolution | `evolution_audit_log.jsonl` | `evolution_entries` | Evolution audit trail (create, deploy, rollback) |
-| Evidence | Computed from evals | `evidence_entries` | Per-skill evaluation evidence |
-| Snapshots | Computed | `eval_snapshots` | Per-skill monitoring snapshots (pass rate, check count) |
-| Unmatched | Computed | Via query | Queries that did not trigger any skill |
-| Pending | Computed | Via query | Evolution proposals not yet deployed, rejected, or rolled back |
-
-If no log data is found, the static modes exit with an error message
-listing the checked file paths.
-
-## Steps
-
-### 1. Choose Mode
-
-| Goal | Command |
-|------|---------|
-| Interactive dashboard | `selftune dashboard` |
-| Interactive on custom port | `selftune dashboard --port 8080` |
-| Save legacy report to file | `selftune dashboard --out report.html` |
-| Pipe legacy report | `selftune dashboard --export` |
-
-### 2. Run Command
-
-```bash
-# Start server and open React SPA (default)
-selftune dashboard
-
-# Custom port
-selftune dashboard --port 8080
-```
-
-### 3. Interact with Dashboard
-
-- **Overview page** (`/`): KPI cards with info tooltips (total skills,
-  sessions, pass rate, unmatched queries, pending proposals, evidence),
-  skill health grid with status filters, evolution feed, unmatched queries.
-  First-time users see an onboarding banner with a 3-step setup guide;
-  returning users see a dismissible welcome banner.
-- **Skill report** (`/skills/:name`): Per-skill drilldown with 8 KPI cards
-  (each with info tooltip), tabbed content (Evidence, Invocations, Prompts,
-  Sessions, Pending — each tab has a hover description), evolution timeline
-  sidebar with collapsible lifecycle legend, evidence viewer with context
-  banner explaining the evidence trail
-- **Sidebar**: Collapsible navigation listing all skills by health status
-- **Theme**: Dark/light toggle with selftune branding
-- **Tooltips**: Hover over the info icon next to any metric label to see
-  what it measures. Hover over tab names for brief descriptions.
-
 ## Common Patterns
 
 **"Show me the dashboard"**
-> Run `selftune dashboard`. Opens the React SPA in your browser.
+> Run `selftune dashboard`.
 
-**"I want to drill into a specific skill"**
-> Click any skill in the sidebar or skill health grid. The skill report
-> page shows usage stats, evidence viewer, evolution timeline, and
-> pending proposals.
+**"Use a different port"**
+> Run `selftune dashboard --port 8080`.
 
-**"Export a report"**
-> Use `selftune dashboard --out report.html` to save a self-contained
-> legacy HTML file. Share it -- no server needed, all data is embedded.
+**"Start the dashboard without launching a browser"**
+> Run `selftune dashboard --no-open`.
 
-**"The dashboard shows no data"**
-> No log files found. Run some sessions first so hooks generate
-> telemetry. Check `selftune doctor` to verify hooks are installed.
+**"The dashboard won’t load"**
+> Ensure the SPA build exists with `bun run build:dashboard` in the repo, then retry.
+> If using the published package, verify the install completed correctly and run `selftune doctor`.
 
-**"Use a different port"**
-> `selftune dashboard --port 8080`. Port must be 1-65535.
-
-**"Trigger actions from the dashboard"**
-> The dashboard provides buttons to trigger watch, evolve, and rollback
-> for each skill. These call the action endpoints which spawn selftune
-> subprocesses.
+**"I want a per-skill deep link"**
+> Open `/skills/<name>` in the SPA, or `/report/<name>` for the HTML report view.
 
 ## SPA Development
 
-To develop the React SPA locally:
-
 ```bash
 # From repo root
 bun run dev
-# → if 7888 is free, starts both the dashboard server and the SPA dev server
-# → if 7888 is already in use, reuses that dashboard server and starts only the SPA dev server on http://localhost:5199
 
-# Or run manually:
-# Terminal 1: Start the dashboard server
-selftune dashboard --port 7888
+# Server only
+bun run dev:dashboard
 
-# Terminal 2: Start the Vite dev server (proxies /api to port 7888)
+# Or manually:
+selftune dashboard --port 7888 --no-open
 cd apps/local-dashboard
 bun install
 bunx vite
-# → opens at http://localhost:5199
 ```
 
-Production builds are created with `bun run build:dashboard` from the
-repo root and output to `apps/local-dashboard/dist/`. The dashboard
-server serves these static files at `/`.
+The Vite dev server runs at `http://localhost:5199` and proxies API traffic to
+the dashboard server on `http://localhost:7888`.
diff --git a/tests/dashboard/dashboard-server.test.ts b/tests/dashboard/dashboard-server.test.ts
index 5f09344..b345f99 100644
--- a/tests/dashboard/dashboard-server.test.ts
+++ b/tests/dashboard/dashboard-server.test.ts
@@ -1,44 +1,93 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import type {
+  OverviewResponse,
+  SkillReportResponse,
+} from "../../cli/selftune/dashboard-contract.js";
 
-/**
- * Dashboard server tests — validates HTTP endpoints, SSE streaming,
- * action handlers, and server lifecycle.
- *
- * Strategy: spawn actual server on port 0 (random), test with fetch, clean up.
- */
-
-// Dynamic import to avoid module-level failures when file doesn't exist yet
 let startDashboardServer: typeof import("../../cli/selftune/dashboard-server.js").startDashboardServer;
-const fakeData = {
-  telemetry: [{ timestamp: "2026-03-12T10:00:00Z", session_id: "sess-1" }],
+
+const overviewFixture: OverviewResponse = {
+  overview: {
+    telemetry: [
+      {
+        timestamp: "2026-03-12T10:00:00Z",
+        session_id: "sess-1",
+        skills_triggered: ["test-skill"],
+        errors_encountered: 0,
+        total_tool_calls: 3,
+      },
+    ],
+    skills: [
+      {
+        timestamp: "2026-03-12T10:00:00Z",
+        session_id: "sess-1",
+        skill_name: "test-skill",
+        skill_path: "/tmp/test-skill/SKILL.md",
+        query: "test prompt",
+        triggered: true,
+        source: "claude_code_repair",
+      },
+    ],
+    evolution: [],
+    counts: {
+      telemetry: 1,
+      skills: 1,
+      evolution: 0,
+      evidence: 1,
+      sessions: 1,
+      prompts: 1,
+    },
+    unmatched_queries: [],
+    pending_proposals: [],
+  },
   skills: [
+    {
+      skill_name: "test-skill",
+      skill_scope: "global",
+      total_checks: 1,
+      triggered_count: 1,
+      pass_rate: 1,
+      unique_sessions: 1,
+      last_seen: "2026-03-12T10:00:00Z",
+      has_evidence: true,
+    },
+  ],
+  version: "0.2.1-test",
+};
+
+const skillReportFixture: SkillReportResponse = {
+  skill_name: "test-skill",
+  usage: {
+    total_checks: 1,
+    triggered_count: 1,
+    pass_rate: 1,
+  },
+  recent_invocations: [
     {
       timestamp: "2026-03-12T10:00:00Z",
       session_id: "sess-1",
-      skill_name: "test-skill",
-      skill_path: "/tmp/test-skill/SKILL.md",
       query: "test prompt",
       triggered: true,
+      source: "claude_code_repair",
     },
   ],
-  queries: [{ timestamp: "2026-03-12T10:00:00Z", session_id: "sess-1", query: "test prompt" }],
-  evolution: [],
   evidence: [],
-  decisions: [],
-  computed: {
-    snapshots: {
-      "test-skill": {
-        window_sessions: 1,
-        pass_rate: 1,
-        false_negative_rate: 0,
-        regression_detected: false,
-        baseline_pass_rate: 0.5,
-        skill_checks: 1,
-      },
-    },
-    unmatched: [],
-    pendingProposals: [],
+  sessions_with_skill: 1,
+  evolution: [],
+  pending_proposals: [],
+  token_usage: {
+    total_input_tokens: 10,
+    total_output_tokens: 20,
   },
+  canonical_invocations: [],
+  duration_stats: {
+    avg_duration_ms: 50,
+    total_duration_ms: 50,
+    execution_count: 1,
+    total_errors: 0,
+  },
+  prompt_samples: [],
+  session_metadata: [],
 };
 
 beforeAll(async () => {
@@ -47,17 +96,16 @@ beforeAll(async () => {
 });
 
 describe("dashboard-server", () => {
-  let serverPromise:
-    | Promise<{ server: unknown; stop: () => void; port: number }>
-    | null = null;
+  let serverPromise: Promise<{ server: unknown; stop: () => void; port: number }> | null = null;
 
   async function getServer(): Promise<{ server: unknown; stop: () => void; port: number }> {
     if (!serverPromise) {
       serverPromise = startDashboardServer({
-        port: 0, // random port
+        port: 0,
         host: "127.0.0.1",
         openBrowser: false,
-        dataLoader: () => fakeData,
+        overviewLoader: () => overviewFixture,
+        skillReportLoader: (skillName) => (skillName === "test-skill" ? skillReportFixture : null),
         statusLoader: () => ({
           skills: [
             {
@@ -79,6 +127,7 @@ describe("dashboard-server", () => {
             warn: 0,
           },
         }),
+        evidenceLoader: () => [],
         actionRunner: async (command) => ({
           success: command !== "rollback",
           output: `${command} ok`,
@@ -96,11 +145,6 @@ describe("dashboard-server", () => {
     return res.text();
   }
 
-  async function servesSpaShell(): Promise<boolean> {
-    const html = await readRootHtml();
-    return html.includes("<div id=\"root\"></div>") && html.includes("/assets/");
-  }
-
   afterAll(async () => {
     if (serverPromise) {
       const server = await serverPromise;
@@ -108,134 +152,82 @@ describe("dashboard-server", () => {
     }
   });
 
-  // ---- GET / ----
   describe("GET /", () => {
     it("returns 200 with HTML content", async () => {
       const server = await getServer();
       const res = await fetch(`http://127.0.0.1:${server.port}/`);
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toContain("text/html");
-    }, 15000);
-
-    it("contains the selftune title", async () => {
-      const html = await readRootHtml();
-      expect(html).toContain("selftune");
     });
 
-    it("serves either the SPA shell or the legacy live shell", async () => {
+    it("serves the SPA shell", async () => {
       const html = await readRootHtml();
-      const isSpa = await servesSpaShell();
-      if (isSpa) {
-        expect(html).toContain("<div id=\"root\"></div>");
-        expect(html).toContain("/assets/");
-      } else {
-        expect(html).toContain("__SELFTUNE_LIVE__");
-      }
-    });
-
-    it("keeps the legacy dashboard available at /legacy/ when SPA is active", async () => {
-      if (!(await servesSpaShell())) return;
-
-      const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/legacy/`);
-      expect(res.status).toBe(200);
-      const html = await res.text();
-      expect(html).toContain("__SELFTUNE_LIVE__");
+      expect(html).toContain('<div id="root"></div>');
+      expect(html).toContain("/assets/");
     });
   });
 
-  // ---- GET /api/data ----
-  describe("GET /api/data", () => {
+  describe("GET /api/v2/overview", () => {
     it("returns 200 with JSON", async () => {
       const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/v2/overview`);
       expect(res.status).toBe(200);
       expect(res.headers.get("content-type")).toContain("application/json");
     });
 
-    it("returns expected data shape", async () => {
+    it("returns the overview payload contract", async () => {
       const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/v2/overview`);
       const data = await res.json();
-      expect(data).toHaveProperty("telemetry");
+      expect(data).toHaveProperty("overview");
       expect(data).toHaveProperty("skills");
-      expect(data).toHaveProperty("queries");
-      expect(data).toHaveProperty("evolution");
-      expect(data).toHaveProperty("evidence");
-      expect(data).toHaveProperty("computed");
-      expect(Array.isArray(data.telemetry)).toBe(true);
+      expect(data).toHaveProperty("version");
+      expect(Array.isArray(data.overview.telemetry)).toBe(true);
       expect(Array.isArray(data.skills)).toBe(true);
-      expect(Array.isArray(data.queries)).toBe(true);
-      expect(Array.isArray(data.evolution)).toBe(true);
-      expect(Array.isArray(data.evidence)).toBe(true);
+      expect(data.skills[0]?.skill_name).toBe("test-skill");
     });
 
-    it("includes decisions in the data", async () => {
+    it("includes CORS headers", async () => {
       const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
-      const data = await res.json();
-      expect(data).toHaveProperty("decisions");
-      expect(Array.isArray(data.decisions)).toBe(true);
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/v2/overview`);
+      expect(res.headers.get("access-control-allow-origin")).toBe("*");
     });
   });
 
-  // ---- GET /api/events (SSE) ----
-  describe("GET /api/events", () => {
-    it("returns SSE content type", async () => {
+  describe("GET /api/v2/skills/:name", () => {
+    it("returns 200 with JSON", async () => {
       const server = await getServer();
-      const controller = new AbortController();
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/events`, {
-        signal: controller.signal,
-      });
+      const res = await fetch(
+        `http://127.0.0.1:${server.port}/api/v2/skills/${encodeURIComponent("test-skill")}`,
+      );
       expect(res.status).toBe(200);
-      expect(res.headers.get("content-type")).toContain("text/event-stream");
-      controller.abort();
+      expect(res.headers.get("content-type")).toContain("application/json");
     });
 
-    it("sends initial data event", async () => {
+    it("returns the skill report payload contract", async () => {
       const server = await getServer();
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), 3000);
-
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/events`, {
-        signal: controller.signal,
-      });
-
-      const reader = res.body?.getReader();
-      expect(reader).toBeDefined();
-      if (!reader) throw new Error("Response body reader is null");
-      const decoder = new TextDecoder();
-      let accumulated = "";
-
-      try {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          accumulated += decoder.decode(value, { stream: true });
-          // Wait for a complete SSE event (double newline terminates an event)
-          if (accumulated.includes("\n\n")) break;
-        }
-      } catch {
-        // abort expected
-      } finally {
-        clearTimeout(timeout);
-        controller.abort();
-      }
+      const res = await fetch(
+        `http://127.0.0.1:${server.port}/api/v2/skills/${encodeURIComponent("test-skill")}`,
+      );
+      const data = await res.json();
+      expect(data.skill_name).toBe("test-skill");
+      expect(data.usage.pass_rate).toBe(1);
+      expect(Array.isArray(data.recent_invocations)).toBe(true);
+      expect(Array.isArray(data.evolution)).toBe(true);
+      expect(Array.isArray(data.pending_proposals)).toBe(true);
+    });
 
-      expect(accumulated).toContain("event: data");
-      // The data line should be parseable JSON
-      const dataMatch = accumulated.match(/data: (.+)/);
-      expect(dataMatch).not.toBeNull();
-      if (dataMatch) {
-        const parsed = JSON.parse(dataMatch[1]);
-        expect(parsed).toHaveProperty("telemetry");
-      }
+    it("returns 404 for an unknown skill", async () => {
+      const server = await getServer();
+      const res = await fetch(
+        `http://127.0.0.1:${server.port}/api/v2/skills/${encodeURIComponent("missing")}`,
+      );
+      expect(res.status).toBe(404);
     });
   });
 
-  // ---- POST /api/actions/watch ----
-  describe("POST /api/actions/watch", () => {
-    it("returns JSON response", async () => {
+  describe("POST /api/actions/*", () => {
+    it("watch returns JSON response", async () => {
       const server = await getServer();
       const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/watch`, {
         method: "POST",
@@ -244,17 +236,10 @@ describe("dashboard-server", () => {
       });
       expect(res.status).toBe(200);
       const data = await res.json();
-      expect(data).toHaveProperty("success");
-      // May fail since skill doesn't exist, but shape should be correct
-      expect(typeof data.success).toBe("boolean");
-      expect(data).toHaveProperty("output");
-      expect(data).toHaveProperty("error");
+      expect(data.success).toBe(true);
     });
-  });
 
-  // ---- POST /api/actions/evolve ----
-  describe("POST /api/actions/evolve", () => {
-    it("returns JSON response", async () => {
+    it("evolve returns JSON response", async () => {
       const server = await getServer();
       const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/evolve`, {
         method: "POST",
@@ -263,14 +248,10 @@ describe("dashboard-server", () => {
       });
       expect(res.status).toBe(200);
       const data = await res.json();
-      expect(data).toHaveProperty("success");
-      expect(typeof data.success).toBe("boolean");
+      expect(data.success).toBe(true);
     });
-  });
 
-  // ---- POST /api/actions/rollback ----
-  describe("POST /api/actions/rollback", () => {
-    it("returns JSON response with proposalId validation", async () => {
+    it("rollback validates proposalId", async () => {
       const server = await getServer();
       const res = await fetch(`http://127.0.0.1:${server.port}/api/actions/rollback`, {
         method: "POST",
@@ -278,157 +259,76 @@ describe("dashboard-server", () => {
         body: JSON.stringify({
           skill: "test-skill",
           skillPath: "/tmp/test-skill",
-          proposalId: "test-proposal-123",
+          proposalId: "proposal-123",
         }),
       });
       expect(res.status).toBe(200);
       const data = await res.json();
-      expect(data).toHaveProperty("success");
-      expect(typeof data.success).toBe("boolean");
-    });
-  });
-
-  // ---- GET /api/evaluations/:skillName ----
-  describe("GET /api/evaluations/:skillName", () => {
-    it("returns 200 with JSON array", async () => {
-      const server = await getServer();
-      const res = await fetch(
-        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
-      );
-      expect(res.status).toBe(200);
-      expect(res.headers.get("content-type")).toContain("application/json");
-      const data = await res.json();
-      expect(Array.isArray(data)).toBe(true);
-    });
-
-    it("returns entries with expected shape when data exists", async () => {
-      const server = await getServer();
-      const res = await fetch(
-        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
-      );
-      const data = await res.json();
-      // May be empty if no skill_usage_log.jsonl entries match, but shape is still an array
-      expect(Array.isArray(data)).toBe(true);
-      if (data.length > 0) {
-        expect(data[0]).toHaveProperty("timestamp");
-        expect(data[0]).toHaveProperty("session_id");
-        expect(data[0]).toHaveProperty("query");
-        expect(data[0]).toHaveProperty("skill_name");
-        expect(data[0]).toHaveProperty("triggered");
-      }
-    });
-
-    it("returns empty array for unknown skill", async () => {
-      const server = await getServer();
-      const res = await fetch(
-        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("nonexistent-skill-xyz")}`,
-      );
-      expect(res.status).toBe(200);
-      const data = await res.json();
-      expect(data).toEqual([]);
-    });
-
-    it("includes CORS headers", async () => {
-      const server = await getServer();
-      const res = await fetch(
-        `http://127.0.0.1:${server.port}/api/evaluations/${encodeURIComponent("test-skill")}`,
-      );
-      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      expect(data.success).toBe(false);
     });
   });
 
-  // ---- 404 for unknown routes ----
   describe("unknown routes", () => {
-    it("returns SPA fallback or 404 depending on served mode", async () => {
+    it("returns SPA fallback for client-side routes", async () => {
       const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/nonexistent`);
-      if (await servesSpaShell()) {
-        expect(res.status).toBe(200);
-        const html = await res.text();
-        expect(html).toContain("<div id=\"root\"></div>");
-      } else {
-        expect(res.status).toBe(404);
-      }
-    });
-  });
-
-  // ---- CORS headers ----
-  describe("CORS", () => {
-    it("includes CORS headers on API responses", async () => {
-      const server = await getServer();
-      const res = await fetch(`http://127.0.0.1:${server.port}/api/data`);
-      expect(res.headers.get("access-control-allow-origin")).toBe("*");
+      const res = await fetch(`http://127.0.0.1:${server.port}/skills/test-skill`);
+      expect(res.status).toBe(200);
+      const html = await res.text();
+      expect(html).toContain('<div id="root"></div>');
     });
   });
 });
 
-// ---- Server lifecycle ----
 describe("server lifecycle", () => {
+  const statusLoader = () => ({
+    skills: [],
+    unmatchedQueries: 0,
+    pendingProposals: 0,
+    lastSession: null,
+    system: { healthy: true, pass: 0, fail: 0, warn: 0 },
+  });
+
   it("can start and stop cleanly", async () => {
     const s = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
       openBrowser: false,
-      dataLoader: () => fakeData,
-      statusLoader: () => ({
-        skills: [],
-        unmatchedQueries: 0,
-        pendingProposals: 0,
-        lastSession: null,
-        system: { healthy: true, pass: 0, fail: 0, warn: 0 },
-      }),
+      overviewLoader: () => overviewFixture,
+      skillReportLoader: () => null,
+      statusLoader,
     });
-    expect(s).toHaveProperty("stop");
-    expect(s).toHaveProperty("port");
     expect(typeof s.port).toBe("number");
     expect(s.port).toBeGreaterThan(0);
     s.stop();
-  }, 30000);
+  });
 
-  it("exposes port after binding", async () => {
+  it("exposes v2 overview after binding", async () => {
     const s = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
       openBrowser: false,
-      dataLoader: () => fakeData,
-      statusLoader: () => ({
-        skills: [],
-        unmatchedQueries: 0,
-        pendingProposals: 0,
-        lastSession: null,
-        system: { healthy: true, pass: 0, fail: 0, warn: 0 },
-      }),
+      overviewLoader: () => overviewFixture,
+      skillReportLoader: () => null,
+      statusLoader,
     });
-    // Verify the server is actually responding
-    const res = await fetch(`http://127.0.0.1:${s.port}/api/data`);
+    const res = await fetch(`http://127.0.0.1:${s.port}/api/v2/overview`);
     expect(res.status).toBe(200);
     s.stop();
-  }, 15000);
+  });
 });
 
-describe("live shell loading", () => {
-  it("serves / without eagerly loading dashboard data", async () => {
-    let dataLoaderCalls = 0;
+describe("SPA shell loading", () => {
+  it("serves / without eagerly loading the overview payload", async () => {
+    let overviewLoaderCalls = 0;
     const server = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
       openBrowser: false,
-      dataLoader: () => {
-        dataLoaderCalls++;
-        return {
-          telemetry: [],
-          skills: [],
-          queries: [],
-          evolution: [],
-          evidence: [],
-          decisions: [],
-          computed: {
-            snapshots: {},
-            unmatched: [],
-            pendingProposals: [],
-          },
-        };
+      overviewLoader: () => {
+        overviewLoaderCalls++;
+        return overviewFixture;
       },
+      skillReportLoader: () => skillReportFixture,
       statusLoader: () => ({
         skills: [],
         unmatchedQueries: 0,
@@ -443,53 +343,35 @@ describe("live shell loading", () => {
       }),
     });
 
-    const callsBefore = dataLoaderCalls;
     try {
       const res = await fetch(`http://127.0.0.1:${server.port}/`);
       const html = await res.text();
       expect(res.status).toBe(200);
-      const isSpa = html.includes("<div id=\"root\"></div>") && html.includes("/assets/");
-      if (isSpa) {
-        expect(html).toContain("<div id=\"root\"></div>");
-      } else {
-        expect(html).toContain("__SELFTUNE_LIVE__");
-        expect(html).not.toContain('id="embedded-data"');
-      }
-      expect(dataLoaderCalls).toBe(callsBefore);
+      expect(html).toContain('<div id="root"></div>');
+      expect(overviewLoaderCalls).toBe(0);
 
-      const dataRes = await fetch(`http://127.0.0.1:${server.port}/api/data`);
+      const dataRes = await fetch(`http://127.0.0.1:${server.port}/api/v2/overview`);
       expect(dataRes.status).toBe(200);
-      expect(dataLoaderCalls).toBe(1);
+      expect(overviewLoaderCalls).toBe(1);
     } finally {
       server.stop();
     }
-  }, 15000);
+  });
 });
 
 describe("report loading", () => {
-  it("loads report data without touching the full dashboard loader", async () => {
-    let dataLoaderCalls = 0;
+  it("loads report data without touching the v2 skill-report loader", async () => {
+    let skillReportLoaderCalls = 0;
     let evidenceLoaderCalls = 0;
 
     const server = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
       openBrowser: false,
-      dataLoader: () => {
-        dataLoaderCalls++;
-        return {
-          telemetry: [],
-          skills: [],
-          queries: [],
-          evolution: [],
-          evidence: [],
-          decisions: [],
-          computed: {
-            snapshots: {},
-            unmatched: [],
-            pendingProposals: [],
-          },
-        };
+      overviewLoader: () => overviewFixture,
+      skillReportLoader: () => {
+        skillReportLoaderCalls++;
+        return skillReportFixture;
       },
       statusLoader: () => ({
         skills: [
@@ -521,10 +403,10 @@ describe("report loading", () => {
     try {
       const res = await fetch(`http://127.0.0.1:${server.port}/report/test-skill`);
       expect(res.status).toBe(200);
-      expect(dataLoaderCalls).toBe(0);
+      expect(skillReportLoaderCalls).toBe(0);
       expect(evidenceLoaderCalls).toBe(1);
     } finally {
       server.stop();
     }
-  }, 15000);
+  });
 });
diff --git a/tests/dashboard/dashboard.test.ts b/tests/dashboard/dashboard.test.ts
index 271f9a4..a643b07 100644
--- a/tests/dashboard/dashboard.test.ts
+++ b/tests/dashboard/dashboard.test.ts
@@ -2,113 +2,23 @@ import { describe, expect, it } from "bun:test";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-const DASHBOARD_PATH = join(import.meta.dir, "..", "..", "dashboard", "index.html");
-
-describe("dashboard/index.html", () => {
-  it("exists", () => {
-    expect(existsSync(DASHBOARD_PATH)).toBe(true);
-  });
-
-  it("contains required elements", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("selftune");
-    expect(html).toContain("dropZone");
-    expect(html).toContain("session_telemetry_log.jsonl");
-    expect(html).toContain("skill_usage_log.jsonl");
-    expect(html).toContain("all_queries_log.jsonl");
-    expect(html).toContain("evolution_audit_log.jsonl");
-    expect(html).toContain("evolution_evidence_log.jsonl");
-  });
-
-  it("loads Chart.js from CDN", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("chart.js");
-  });
-
-  it("supports embedded data loading", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("embedded-data");
-    expect(html).toContain("loadEmbeddedData");
-  });
-
-  it("waits for DOM content before trying to load embedded data", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("window.addEventListener('DOMContentLoaded'");
-  });
-
-  it("has skill health grid element", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("skill-health-grid");
-  });
-
-  it("handles computed data field", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("computed");
-  });
-
-  it("has drill-down panel element", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html.includes("drill-down") || html.includes("drillDown")).toBe(true);
-  });
-
-  it("has skill search input", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("skillSearchInput");
-  });
-
-  it("has evaluation feed table", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("drillEvalFeed");
-  });
-
-  it("has evidence drill-down sections", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("drillVersionHistory");
-    expect(html).toContain("drillEvidenceTable");
-  });
-
-  it("has invocation breakdown chart", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("chartInvocationBreakdown");
-  });
-
-  it("has time period selector buttons", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("period-btn");
-  });
-
-  it("has 4-state badge classes", () => {
-    const html = readFileSync(DASHBOARD_PATH, "utf-8");
-    expect(html).toContain("badge-warning");
-    expect(html).toContain("badge-critical");
-    expect(html).toContain("badge-healthy");
-    expect(html).toContain("badge-unknown");
-  });
-});
+const DASHBOARD_CLI_PATH = join(import.meta.dir, "..", "..", "cli", "selftune", "dashboard.ts");
 
 describe("cli/selftune/dashboard.ts", () => {
   it("module exists", () => {
-    const modPath = join(import.meta.dir, "..", "..", "cli", "selftune", "dashboard.ts");
-    expect(existsSync(modPath)).toBe(true);
-  });
-
-  it("imports from constants (shared layer)", () => {
-    const modPath = join(import.meta.dir, "..", "..", "cli", "selftune", "dashboard.ts");
-    const src = readFileSync(modPath, "utf-8");
-    expect(src).toContain("./constants");
+    expect(existsSync(DASHBOARD_CLI_PATH)).toBe(true);
   });
 
-  it("imports from monitoring for snapshot computation", () => {
-    const modPath = join(import.meta.dir, "..", "..", "cli", "selftune", "dashboard.ts");
-    const src = readFileSync(modPath, "utf-8");
-    expect(src).toContain("computeMonitoringSnapshot");
+  it("documents the SPA server workflow", () => {
+    const src = readFileSync(DASHBOARD_CLI_PATH, "utf-8");
+    expect(src).toContain("Start the local React SPA dashboard server");
+    expect(src).toContain("--no-open");
+    expect(src).not.toContain("buildEmbeddedHTML");
+    expect(src).not.toContain("dashboard/index.html");
   });
 
-  it("imports from evolution for audit trail", () => {
-    const modPath = join(import.meta.dir, "..", "..", "cli", "selftune", "dashboard.ts");
-    const src = readFileSync(modPath, "utf-8");
-    expect(src).toContain("getLastDeployedProposal");
-    expect(src).toContain("readAuditTrail");
-    expect(src).toContain("readEvidenceTrail");
+  it("rejects the removed legacy export mode explicitly", () => {
+    const src = readFileSync(DASHBOARD_CLI_PATH, "utf-8");
+    expect(src).toContain("Legacy dashboard export was removed.");
   });
 });
diff --git a/tests/sandbox/run-sandbox.ts b/tests/sandbox/run-sandbox.ts
index 5702a08..6cb9311 100644
--- a/tests/sandbox/run-sandbox.ts
+++ b/tests/sandbox/run-sandbox.ts
@@ -189,6 +189,80 @@ async function runCliCommand(name: string, args: string[]): Promise<RawTestResul
   }
 }
 
+async function runDashboardSmokeTest(port: number): Promise<RawTestResult> {
+  const name = "dashboard";
+  const command = `bun run ${CLI_PATH} dashboard --port ${port} --no-open`;
+  const start = performance.now();
+  const baseUrl = `http://localhost:${port}`;
+  const proc = Bun.spawn(
+    ["bun", "run", CLI_PATH, "dashboard", "--port", String(port), "--no-open"],
+    {
+      env: sandboxEnv,
+      stdout: "pipe",
+      stderr: "pipe",
+      cwd: PROJECT_ROOT,
+    },
+  );
+
+  let ready = false;
+  let failureReason = "Dashboard server did not become ready";
+
+  try {
+    for (let attempt = 0; attempt < 40; attempt++) {
+      await Bun.sleep(250);
+      try {
+        const rootRes = await fetch(`${baseUrl}/`);
+        if (rootRes.status !== 200) {
+          failureReason = `Expected 200 from dashboard root, got ${rootRes.status}`;
+          continue;
+        }
+        const html = await rootRes.text();
+        if (!html.includes('<div id="root"></div>')) {
+          failureReason = "Expected SPA shell from dashboard root";
+          continue;
+        }
+
+        const overviewRes = await fetch(`${baseUrl}/api/v2/overview`);
+        if (overviewRes.status !== 200) {
+          failureReason = `Expected 200 from /api/v2/overview, got ${overviewRes.status}`;
+          continue;
+        }
+        const overview = await overviewRes.json();
+        if (!overview?.overview || !Array.isArray(overview?.skills)) {
+          failureReason = "Expected overview payload from /api/v2/overview";
+          continue;
+        }
+
+        ready = true;
+        break;
+      } catch (error) {
+        failureReason = error instanceof Error ? error.message : String(error);
+      }
+    }
+  } finally {
+    proc.kill("SIGTERM");
+  }
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  const durationMs = Math.round(performance.now() - start);
+
+  return {
+    name,
+    command,
+    exitCode,
+    passed: ready,
+    durationMs,
+    stdout: stdout.slice(0, 2000),
+    stderr: stderr.slice(0, 2000),
+    fullStdout: stdout,
+    error: ready ? undefined : failureReason,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Hook runner
 // ---------------------------------------------------------------------------
@@ -324,17 +398,8 @@ async function main(): Promise<void> {
     const lastResult = await runCliCommand("last", ["last"]);
     results.push(lastResult);
 
-    // f. dashboard --export
-    const dashboardResult = await runCliCommand("dashboard --export", ["dashboard", "--export"]);
-    // Dashboard --export writes HTML to stdout; verify it contains HTML
-    if (
-      dashboardResult.passed &&
-      !dashboardResult.fullStdout.includes("<!DOCTYPE html") &&
-      !dashboardResult.fullStdout.includes("<html")
-    ) {
-      dashboardResult.passed = false;
-      dashboardResult.error = "Expected HTML output from dashboard --export";
-    }
+    // f. dashboard server smoke test
+    const dashboardResult = await runDashboardSmokeTest(43141);
     results.push(dashboardResult);
 
     // g. contribute --skill find-skills --preview

From 9fa76c19daad4c4bf9a2288ebdf274bf26795988 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:07:36 +0300
Subject: [PATCH 05/14] Refresh execution plans after dashboard cutover

---
 docs/exec-plans/active/grader-prompt-evals.md | 10 +++-
 .../active/local-sqlite-materialization.md    | 24 ++++++--
 .../active/mcp-tool-descriptions.md           | 10 +++-
 docs/exec-plans/active/multi-agent-sandbox.md |  8 ++-
 .../active/product-reset-and-shipping.md      |  8 ++-
 docs/exec-plans/active/telemetry-field-map.md |  2 +-
 .../completed/dashboard-spa-cutover.md        | 58 +++++++++++++++++++
 7 files changed, 106 insertions(+), 14 deletions(-)
 create mode 100644 docs/exec-plans/completed/dashboard-spa-cutover.md

diff --git a/docs/exec-plans/active/grader-prompt-evals.md b/docs/exec-plans/active/grader-prompt-evals.md
index 9abfdb6..aab5eb4 100644
--- a/docs/exec-plans/active/grader-prompt-evals.md
+++ b/docs/exec-plans/active/grader-prompt-evals.md
@@ -2,7 +2,7 @@
 
 <!-- Verified: 2026-03-14 -->
 
-**Status:** Active  
+**Status:** Deferred  
 **Created:** 2026-03-14  
 **Goal:** Evaluate and improve the grader prompts and grading agents so selftune’s session/skill judgments are trustworthy, stable, and measurable.
 
@@ -26,6 +26,14 @@ Current risks:
 - we do not yet have a tight eval loop for the graders themselves
 - users can lose trust quickly if the grader feels arbitrary
 
+## Priority Note
+
+This remains important, but it is not the shortest path to the next release. It should resume once:
+
+- the local app/dashboard path is stable
+- the orchestrated improvement loop is demoable end to end
+- the published package proof is done
+
 ---
 
 ## Goals
diff --git a/docs/exec-plans/active/local-sqlite-materialization.md b/docs/exec-plans/active/local-sqlite-materialization.md
index 7708063..c4d4535 100644
--- a/docs/exec-plans/active/local-sqlite-materialization.md
+++ b/docs/exec-plans/active/local-sqlite-materialization.md
@@ -1,6 +1,6 @@
 # Execution Plan: Local SQLite Materialization and App Data Layer
 
-<!-- Verified: 2026-03-12 -->
+<!-- Verified: 2026-03-14 -->
 
 **Status:** Active  
 **Created:** 2026-03-12  
@@ -54,13 +54,19 @@ This is not a move to “database-first telemetry.” It is a local query/materi
 
 `#42` introduced the first SQLite local materialization layer.
 
+Since then:
+
+- `#39` made the SPA the real local dashboard UI
+- `#44` removed the legacy embedded-HTML runtime and v1 dashboard routes
+- the shared dashboard payload contract now lives in `cli/selftune/dashboard-contract.ts`
+
 That means the work now is not “decide whether to use SQLite.”  
 The work now is:
 
 1. stabilize the local DB schema and materialization flow
 2. make overview/report queries first-class
 3. move the local app to those queries
-4. retire the old heavy dashboard path as the primary UX
+4. finish migrating the remaining dashboard-adjacent surfaces onto the same v2 contracts
 
 ---
 
@@ -126,9 +132,15 @@ The local data layer should explicitly support:
 
 The React local app should stop depending primarily on the old dashboard server’s heavy data path.
 
-### 3. Keep the old dashboard path only as compatibility
+### 3. Remove remaining non-v2 dashboard paths
+
+The legacy HTML runtime is gone. The remaining follow-through is to keep migrating:
+
+- report HTML
+- badge/status projections
+- any leftover JSONL-only dashboard helpers
 
-Do not optimize it indefinitely. Keep it as fallback until the new path is trustworthy.
+onto the same SQLite-backed payload semantics where appropriate.
 
 ### 4. Keep source-truth sync first
 
@@ -152,11 +164,11 @@ Later:
 
 Short term:
 
-- enough to support the new app and compatibility mode
+- enough to serve the SPA, report HTML, badges, and action endpoints
 
 Long term:
 
-- the new local app should be the default experience
+- only the SPA/v2 contract, plus explicitly supported adjunct routes like badges and reports
 
 ---
 
diff --git a/docs/exec-plans/active/mcp-tool-descriptions.md b/docs/exec-plans/active/mcp-tool-descriptions.md
index 242dab5..ba71397 100644
--- a/docs/exec-plans/active/mcp-tool-descriptions.md
+++ b/docs/exec-plans/active/mcp-tool-descriptions.md
@@ -2,7 +2,7 @@
 
 <!-- Verified: 2026-03-14 -->
 
-**Status:** Active  
+**Status:** Deferred  
 **Created:** 2026-03-14  
 **Goal:** Improve selftune’s MCP/tool descriptions so agent runtimes can understand and select the right tools more reliably, with less ambiguity and less prompt burden.
 
@@ -25,6 +25,14 @@ This is especially important for:
 - Paperclip / Claude Code / other autonomous agent runtimes
 - future cloud/local parity in product semantics
 
+## Priority Note
+
+This is intentionally not in the current release-critical path. It should stay deferred until:
+
+- the SPA/local app path is fully credible
+- the autonomous loop is clearer
+- the published install proof is complete
+
 ---
 
 ## Goals
diff --git a/docs/exec-plans/active/multi-agent-sandbox.md b/docs/exec-plans/active/multi-agent-sandbox.md
index 5c9d8cd..c5004df 100644
--- a/docs/exec-plans/active/multi-agent-sandbox.md
+++ b/docs/exec-plans/active/multi-agent-sandbox.md
@@ -1,11 +1,15 @@
 # Execution Plan: Multi-Agent Sandbox Expansion
 
-<!-- Verified: 2026-03-02 -->
+<!-- Verified: 2026-03-14 -->
 
-**Status:** Active
+**Status:** Deferred
 **Created:** 2026-03-02
 **Goal:** Expand the sandbox test harness from Claude Code-only to cover all three agents (Claude Code, Codex, OpenCode) with shared fixtures, per-agent Layer 1 tests, and per-agent Layer 2 Docker containers.
 
+## Priority Note
+
+This is no longer on the immediate shipping path. Keep the current Claude/sandbox coverage working, but defer the broader multi-agent expansion until after the next release candidate is shipped and validated.
+
 ---
 
 ## Problem Statement
diff --git a/docs/exec-plans/active/product-reset-and-shipping.md b/docs/exec-plans/active/product-reset-and-shipping.md
index 00dd125..05d1fb3 100644
--- a/docs/exec-plans/active/product-reset-and-shipping.md
+++ b/docs/exec-plans/active/product-reset-and-shipping.md
@@ -1,6 +1,6 @@
 # Execution Plan: Product Reset and Shipping Priorities
 
-<!-- Verified: 2026-03-12 -->
+<!-- Verified: 2026-03-14 -->
 
 **Status:** Active  
 **Created:** 2026-03-12  
@@ -15,10 +15,12 @@ selftune is no longer blocked by telemetry architecture. It is now blocked by **
 Recent merged work changed the baseline:
 
 - `#38` hardened source-truth telemetry and repair paths
+- `#39` merged the local dashboard SPA
 - `#40` added the first orchestrator core loop
 - `#41` made generic scheduling the primary posture and OpenClaw cron optional
 - `#42` added a local SQLite materialization layer
 - `#43` improved sync progress and tightened noisy query filtering
+- `#44` removed the legacy dashboard runtime and made the SPA/server path authoritative
 
 That means the next phase should optimize for:
 
@@ -140,9 +142,9 @@ Paperclip should accelerate iteration, not become the product priority.
 
 These are the highest-confidence gaps still blocking adoption and confident shipping:
 
-### 1. The local UX is still not good enough
+### 1. The local UX still needs product polish
 
-The old dashboard path remains too slow and awkward, and the SQLite + SPA path is not yet the obvious default experience.
+The SPA + SQLite path is now the supported default, but the experience still needs latency work, drilldown polish, and stronger route/report coherence before it feels fully ready for broader adoption.
 
 ### 2. The autonomous loop is not yet obvious and trustworthy
 
diff --git a/docs/exec-plans/active/telemetry-field-map.md b/docs/exec-plans/active/telemetry-field-map.md
index 68d1218..83b4ac2 100644
--- a/docs/exec-plans/active/telemetry-field-map.md
+++ b/docs/exec-plans/active/telemetry-field-map.md
@@ -2,7 +2,7 @@
 
 <!-- Verified: 2026-03-10 -->
 
-**Status:** Active
+**Status:** Reference
 **Purpose:** Define the canonical telemetry contract that all platform adapters must emit before any downstream projection or analytics.
 **Audience:** Adapter implementers, reviewers, and anyone building the shared local/cloud telemetry pipeline.
 
diff --git a/docs/exec-plans/completed/dashboard-spa-cutover.md b/docs/exec-plans/completed/dashboard-spa-cutover.md
new file mode 100644
index 0000000..f65029a
--- /dev/null
+++ b/docs/exec-plans/completed/dashboard-spa-cutover.md
@@ -0,0 +1,58 @@
+# Execution Plan: Dashboard SPA Cutover
+
+<!-- Verified: 2026-03-14 -->
+
+**Status:** Completed  
+**Completed:** 2026-03-14  
+**Goal:** Retire the legacy embedded-HTML dashboard runtime and make the SPA + v2 dashboard server path the supported local experience.
+
+---
+
+## What Landed
+
+- The React SPA became the supported local dashboard UI.
+- `selftune dashboard` now starts the SPA-backed dashboard server directly.
+- The legacy `dashboard/index.html` runtime was removed.
+- Legacy v1 dashboard routes were removed from `cli/selftune/dashboard-server.ts`:
+  - `/legacy/`
+  - `/api/data`
+  - `/api/events`
+  - `/api/evaluations/:name`
+- The shared dashboard payload contract was centralized in `cli/selftune/dashboard-contract.ts`.
+- Dashboard docs and sandbox coverage were updated to the SPA/server model.
+
+## Resulting Product Shape
+
+The supported dashboard path is now:
+
+```text
+selftune dashboard
+  -> dashboard server
+    -> /api/v2/overview
+    -> /api/v2/skills/:name
+    -> SPA at /
+```
+
+Supporting routes that still remain on the server:
+
+- `/badge/:name`
+- `/report/:name`
+- `/api/actions/*`
+
+## Follow-Through That Is Still Separate
+
+This cutover did not complete every dashboard-adjacent migration. Remaining follow-up belongs to other active plans:
+
+- move more report/badge/status semantics onto the same v2 data model
+- continue improving SPA latency and UX polish
+- finish the release/install proof against the published package
+
+## Verification
+
+The cutover was validated with:
+
+- focused dashboard server tests
+- badge/report route tests
+- sandbox dashboard HTTP smoke coverage
+
+The only remaining sandbox failure at completion time was the unrelated pre-existing `hook: skill-eval` issue.

From bee281c1332b396fe97bbcebeed8ed0c0cc189a0 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:28:45 +0300
Subject: [PATCH 06/14] Build dashboard SPA in CI and publish

---
 .github/workflows/ci.yml      | 10 ++++++++++
 .github/workflows/publish.yml |  3 +++
 2 files changed, 13 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5084e7b..4a7ed14 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -20,6 +20,16 @@ jobs:
       - run: bunx @biomejs/biome check .
       - run: bun run lint-architecture.ts
 
+  build-dashboard:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2
+      - run: bun install
+      - run: bun run build:dashboard
+
   test:
     runs-on: ubuntu-latest
     permissions:
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 2d06499..f4f7139 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -60,6 +60,9 @@ jobs:
       - name: Install dependencies
         run: bun install
 
+      - name: Build dashboard SPA
+        run: bun run build:dashboard
+
       - name: Verify npm version for trusted publishing
         run: npm --version
 

From 23e53801ae749b83c689e23acf3b896daee46413 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:33:27 +0300
Subject: [PATCH 07/14] Refresh README for SPA release path

---
 README.md | 67 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index ab25e5c..0028a5e 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/selftune?activeTab=dependencies)
 [![Bun](https://img.shields.io/badge/runtime-bun%20%7C%20node-black)](https://bun.sh)
 
-Your agent skills learn how you work. Detect what's broken. Fix it automatically.
+Your agent skills learn how you work. Detect what's broken. Improve low-risk skill behavior automatically.
 
 **[Install](#install)** · **[Use Cases](#built-for-how-you-actually-work)** · **[How It Works](#how-it-works)** · **[Commands](#commands)** · **[Platforms](#platforms)** · **[Docs](docs/integration-guide.md)**
 
@@ -23,7 +23,7 @@ Your agent skills learn how you work. Detect what's broken. Fix it automatically
 
 ---
 
-Your skills don't understand how you talk. You say "make me a slide deck" and nothing happens — no error, no log, no signal. selftune watches your real sessions, learns how you actually speak, and rewrites skill descriptions to match. Automatically.
+Your skills do not understand how you talk. You say "make me a slide deck" and nothing happens: no error, no signal, no clue why the right skill never fired. selftune reads the transcripts and telemetry your agent already saves, learns how you actually speak, and improves skill descriptions to match. It validates changes before deployment, watches for regressions after, and rolls back when needed.
 
 Built for **Claude Code**. Also works with Codex, OpenCode, and OpenClaw. Zero runtime dependencies.
 
@@ -35,9 +35,18 @@ npx skills add selftune-dev/selftune
 
 Then tell your agent: **"initialize selftune"**
 
-Two minutes. No API keys. No external services. No configuration ceremony. Uses your existing agent subscription. Within minutes you'll see which skills are undertriggering.
+Two minutes. No API keys. No external services. No configuration ceremony. Uses your existing agent subscription.
 
-**CLI only** (no skill, just the CLI):
+Quick proof path:
+
+```bash
+npx selftune@latest doctor
+npx selftune@latest sync --force
+npx selftune@latest status
+npx selftune@latest dashboard
+```
+
+**CLI only** (no installed skill):
 
 ```bash
 npx selftune@latest doctor
@@ -68,51 +77,49 @@ combinations repeat, which ones help, and where the friction is.
   <img src="./assets/FeedbackLoop.gif" alt="Observe → Detect → Evolve → Watch" width="800">
 </p>
 
-A continuous feedback loop that makes your skills learn and adapt. Automatically.
+A continuous feedback loop that makes your skills learn and adapt from real work.
 
-**Observe** — Hooks capture every user query and which skills fired. On Claude Code, hooks install automatically. Use `selftune replay` to backfill existing transcripts. This is how your skills start learning.
+**Observe** — selftune reads the transcripts and telemetry your agents already save. On Claude Code, hooks can add low-latency hints, but transcripts and logs are the source of truth. Use `selftune sync` to ingest current activity and `selftune replay` to backfill older Claude Code sessions.
 
-**Detect** — selftune finds the gap between how you talk and how your skills are described. You say "make me a slide deck" and your pptx skill stays silent — selftune catches that mismatch.
+**Detect** — selftune finds the gap between how you talk and how your skills are described. It spots missed triggers, underperforming descriptions, noisy environments, and regressions in real usage.
 
-**Evolve** — Rewrites skill descriptions — and full skill bodies — to match how you actually work. Batched validation with per-stage model control (`--cheap-loop` uses haiku for the loop, sonnet for the gate). Teacher-student body evolution with 3-gate validation. Baseline comparison gates on measurable lift. Automatic backup.
+**Evolve** — For low-risk changes, selftune can autonomously rewrite skill descriptions to match how you actually work. Every proposal is validated before deploy. Full skill-body or routing changes stay available for higher-touch workflows.
 
-**Watch** — After deploying changes, selftune monitors skill trigger rates. If anything regresses, it rolls back automatically. Your skills keep improving without you touching them.
+**Watch** — After deploying changes, selftune monitors trigger quality and post-deploy evidence. If something regresses, it can roll back automatically. The goal is autonomous improvement with safeguards, not blind self-editing.
 
-## What's New in v0.2.0
+## What's New in v0.2.x
 
-- **Full skill body evolution** — Beyond descriptions: evolve routing tables and entire skill bodies using teacher-student model with structural, trigger, and quality gates
-- **Synthetic eval generation** — `selftune evals --synthetic` generates eval sets from SKILL.md via LLM, no session logs needed. Solves cold-start: new skills get evals immediately.
-- **Cheap-loop evolution** — `selftune evolve --cheap-loop` uses haiku for proposal generation and validation, sonnet only for the final deployment gate. ~80% cost reduction.
-- **Batch trigger validation** — Validation now batches 10 queries per LLM call instead of one-per-query. ~10x faster evolution loops.
-- **Per-stage model control** — `--validation-model`, `--proposal-model`, and `--gate-model` flags give fine-grained control over which model runs each evolution stage.
-- **Auto-activation system** — Hooks detect when selftune should run and suggest actions
-- **Enforcement guardrails** — Blocks SKILL.md edits on monitored skills unless `selftune watch` has been run
-- **React SPA dashboard** — `selftune dashboard` serves a React SPA with skill health grid, per-skill drilldown, evidence viewer, evolution timeline, dark/light theming, and SQLite-backed v2 API
-- **Evolution memory** — Persists context, plans, and decisions across context resets
-- **4 specialized agents** — Diagnosis analyst, pattern analyst, evolution reviewer, integration guide
-- **Sandbox test harness** — Comprehensive automated test coverage, including devcontainer-based LLM testing
-- **Workflow discovery + codification** — `selftune workflows` finds repeated
-  multi-skill sequences from telemetry, and `selftune workflows save
-  <workflow-id|index>` appends them to `## Workflows` in SKILL.md
+- **Source-truth sync** — `selftune sync` now leads the product loop, using transcripts/logs as truth and hooks as hints
+- **SQLite-backed local app** — `selftune dashboard` now serves the React SPA by default with faster overview/report routes on top of materialized local data
+- **Autonomous low-risk evolution** — description evolution is autonomous by default, with explicit review-required mode for stricter policies
+- **Full skill body evolution** — evolve routing tables and entire skill bodies using teacher-student model with structural, trigger, and quality gates
+- **Synthetic eval generation** — `selftune evals --synthetic` generates eval sets from `SKILL.md` for cold-start skills
+- **Cheap-loop evolution** — `selftune evolve --cheap-loop` uses haiku for proposal generation and validation, sonnet only for the final deployment gate
+- **Per-stage model control** — `--validation-model`, `--proposal-model`, and `--gate-model` give fine-grained control over each evolution stage
+- **Sandbox test harness** — automated coverage, including devcontainer-based LLM testing
+- **Workflow discovery + codification** — `selftune workflows` finds repeated multi-skill sequences from telemetry and can append them to `## Workflows` in `SKILL.md`
 
 ## Commands
 
 | Command | What it does |
 |---|---|
+| `selftune doctor` | Health check: logs, config, permissions, dashboard build/runtime expectations |
+| `selftune sync` | Ingest source-truth activity from supported agents and rebuild local state |
 | `selftune status` | See which skills are undertriggering and why |
+| `selftune dashboard` | Open the React SPA dashboard (SQLite-backed) |
+| `selftune orchestrate` | Run the core loop: sync, inspect candidates, evolve, and watch |
 | `selftune evals --skill <name>` | Generate eval sets from real session data (`--synthetic` for cold-start) |
 | `selftune evolve --skill <name>` | Propose, validate, and deploy improved descriptions (`--cheap-loop`, `--with-baseline`) |
 | `selftune evolve-body --skill <name>` | Evolve full skill body or routing table (teacher-student, 3-gate validation) |
+| `selftune watch --skill <name>` | Monitor after deploy. Auto-rollback on regression. |
+| `selftune replay` | Backfill data from existing Claude Code transcripts |
 | `selftune baseline --skill <name>` | Measure skill value vs no-skill baseline |
 | `selftune unit-test --skill <name>` | Run or generate skill-level unit tests |
 | `selftune composability --skill <name>` | Measure synergy and conflicts between co-occurring skills, with workflow-candidate hints |
 | `selftune workflows` | Discover repeated multi-skill workflows and save a discovered workflow into `SKILL.md` |
 | `selftune import-skillsbench` | Import external eval corpus from [SkillsBench](https://github.com/benchflow-ai/skillsbench) |
 | `selftune badge --skill <name>` | Generate skill health badge SVG |
-| `selftune watch --skill <name>` | Monitor after deploy. Auto-rollback on regression. |
-| `selftune dashboard` | Open the React SPA dashboard (SQLite-backed) |
-| `selftune replay` | Backfill data from existing Claude Code transcripts |
-| `selftune doctor` | Health check: logs, hooks, config, permissions |
+| `selftune cron setup` | Optional scheduler helper for OpenClaw-oriented automation |
 
 Full command reference: `selftune --help`
 
@@ -141,13 +148,13 @@ Observability tools trace LLM calls. Skill authoring tools help you write skills
 
 ## Platforms
 
-**Claude Code** (primary) — Hooks install automatically. `selftune replay` backfills existing transcripts. Full feature support.
+**Claude Code** (primary) — Reads saved transcripts and telemetry directly. Hooks install automatically and add low-latency hints. `selftune replay` backfills older Claude Code sessions. Full feature support.
 
 **Codex** — `selftune wrap-codex -- <args>` or `selftune ingest-codex`
 
 **OpenCode** — `selftune ingest-opencode`
 
-**OpenClaw** — `selftune ingest-openclaw` + `selftune cron setup` for autonomous evolution
+**OpenClaw** — `selftune ingest-openclaw`. `selftune cron setup` remains available as an optional OpenClaw-oriented scheduler helper, but the main product loop is agent-agnostic.
 
 Requires [Bun](https://bun.sh) or Node.js 18+. No extra API keys.
 

From 68f99579a26d39dcc7ed370814432bdecab53483 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:39:58 +0300
Subject: [PATCH 08/14] Address dashboard release review comments

---
 cli/selftune/dashboard-server.ts              |  49 ++++-
 docs/escalation-policy.md                     |   2 +-
 .../active/product-reset-and-shipping.md      |   2 -
 .../active/telemetry-normalization.md         |   2 +-
 .../telemetry-field-map.md                    |   2 +-
 package.json                                  |   2 +-
 tests/dashboard/badge-routes.test.ts          | 196 ++++++++++++------
 tests/dashboard/dashboard-server.test.ts      |  30 ++-
 8 files changed, 207 insertions(+), 78 deletions(-)
 rename docs/exec-plans/{active => reference}/telemetry-field-map.md (99%)

diff --git a/cli/selftune/dashboard-server.ts b/cli/selftune/dashboard-server.ts
index fef2c4f..8ee671a 100644
--- a/cli/selftune/dashboard-server.ts
+++ b/cli/selftune/dashboard-server.ts
@@ -4,6 +4,7 @@
  *
  * Endpoints:
  *   GET  /                     — Serve dashboard SPA shell
+ *   GET  /api/health           — Dashboard server health probe
  *   GET  /api/v2/overview      — SQLite-backed overview payload
  *   GET  /api/v2/skills/:name  — SQLite-backed per-skill report
  *   POST /api/actions/watch    — Trigger `selftune watch` for a skill
@@ -46,6 +47,7 @@ import { readEffectiveSkillUsageRecords } from "./utils/skill-log.js";
 export interface DashboardServerOptions {
   port?: number;
   host?: string;
+  spaDir?: string;
   openBrowser?: boolean;
   statusLoader?: () => StatusResult;
   evidenceLoader?: () => EvolutionEvidenceEntry[];
@@ -75,6 +77,14 @@ function findSpaDir(): string | null {
   return null;
 }
 
+function decodePathSegment(segment: string): string | null {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
+
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html; charset=utf-8",
   ".js": "application/javascript; charset=utf-8",
@@ -412,7 +422,7 @@ export async function startDashboardServer(
   const executeAction = options?.actionRunner ?? runAction;
 
   // -- SPA serving -------------------------------------------------------------
-  const spaDir = findSpaDir();
+  const spaDir = options?.spaDir ?? findSpaDir();
   if (spaDir) {
     console.log(`SPA found at ${spaDir}, serving as default dashboard`);
   } else {
@@ -499,6 +509,19 @@ export async function startDashboardServer(
         return new Response(null, { status: 204, headers: corsHeaders() });
       }
 
+      if (url.pathname === "/api/health" && req.method === "GET") {
+        return Response.json(
+          {
+            ok: true,
+            service: "selftune-dashboard",
+            version: selftuneVersion,
+            spa: Boolean(spaDir),
+            v2_data_available: Boolean(getOverviewResponse || db),
+          },
+          { headers: corsHeaders() },
+        );
+      }
+
       // ---- SPA static assets ---- Serve from dist/assets/
       if (spaDir && req.method === "GET" && url.pathname.startsWith("/assets/")) {
         const filePath = resolve(spaDir, `.${url.pathname}`);
@@ -590,7 +613,13 @@ export async function startDashboardServer(
 
       // ---- GET /badge/:skillName ---- Badge SVG
       if (url.pathname.startsWith("/badge/") && req.method === "GET") {
-        const skillName = decodeURIComponent(url.pathname.slice("/badge/".length));
+        const skillName = decodePathSegment(url.pathname.slice("/badge/".length));
+        if (skillName === null) {
+          return Response.json(
+            { error: "Malformed skill name" },
+            { status: 400, headers: corsHeaders() },
+          );
+        }
         const formatParam = url.searchParams.get("format");
         const validFormats = new Set(["svg", "markdown", "url"]);
         const format: BadgeFormat =
@@ -654,7 +683,13 @@ export async function startDashboardServer(
 
       // ---- GET /report/:skillName ---- Skill health report
       if (url.pathname.startsWith("/report/") && req.method === "GET") {
-        const skillName = decodeURIComponent(url.pathname.slice("/report/".length));
+        const skillName = decodePathSegment(url.pathname.slice("/report/".length));
+        if (skillName === null) {
+          return Response.json(
+            { error: "Malformed skill name" },
+            { status: 400, headers: corsHeaders() },
+          );
+        }
         const statusResult = await getCachedStatusResult();
         const skill = statusResult.skills.find((s) => s.name === skillName);
         const evidenceEntries = getEvidenceEntries().filter(
@@ -700,7 +735,13 @@ export async function startDashboardServer(
 
       // ---- GET /api/v2/skills/:name ---- SQLite-backed skill report
       if (url.pathname.startsWith("/api/v2/skills/") && req.method === "GET") {
-        const skillName = decodeURIComponent(url.pathname.slice("/api/v2/skills/".length));
+        const skillName = decodePathSegment(url.pathname.slice("/api/v2/skills/".length));
+        if (skillName === null) {
+          return Response.json(
+            { error: "Malformed skill name" },
+            { status: 400, headers: corsHeaders() },
+          );
+        }
         if (getSkillReportResponse) {
           const report = getSkillReportResponse(skillName);
           if (!report) {
diff --git a/docs/escalation-policy.md b/docs/escalation-policy.md
index 30930cc..25f4e2c 100644
--- a/docs/escalation-policy.md
+++ b/docs/escalation-policy.md
@@ -52,7 +52,7 @@ Clear criteria for when agents proceed autonomously vs. when to involve a human.
 - Modifying the SKILL.md routing table (affects which workflow agents load)
 - Changing `computeStatus` logic in `status.ts` (affects skill health reporting)
 - Changing `computeLastInsight` logic in `last.ts` (affects session insight accuracy)
-- Modifying the dashboard response contract in `dashboard-contract.ts`
+- Modifying the dashboard response contract in `cli/selftune/dashboard-contract.ts`
 - Changing SQLite-backed dashboard query shapes in `cli/selftune/localdb/queries.ts`
 - Modifying activation rules configuration
 - Changing agent assignment logic
diff --git a/docs/exec-plans/active/product-reset-and-shipping.md b/docs/exec-plans/active/product-reset-and-shipping.md
index 05d1fb3..1b54ce3 100644
--- a/docs/exec-plans/active/product-reset-and-shipping.md
+++ b/docs/exec-plans/active/product-reset-and-shipping.md
@@ -136,8 +136,6 @@ Paperclip should accelerate iteration, not become the product priority.
 
 ---
 
-## Current Recommendations
-
 ## Remaining Product Gaps
 
 These are the highest-confidence gaps still blocking adoption and confident shipping:
diff --git a/docs/exec-plans/active/telemetry-normalization.md b/docs/exec-plans/active/telemetry-normalization.md
index 1ae2d3a..61b9c56 100644
--- a/docs/exec-plans/active/telemetry-normalization.md
+++ b/docs/exec-plans/active/telemetry-normalization.md
@@ -201,7 +201,7 @@ That means the normalization layer should be grounded in verified platform contr
 ### Track 0 Verification Snapshot (2026-03-10)
 
 The implementation contract derived from this snapshot lives in
-[`telemetry-field-map.md`](./telemetry-field-map.md).
+[`telemetry-field-map.md`](../reference/telemetry-field-map.md).
 
 **Official source references**
 
diff --git a/docs/exec-plans/active/telemetry-field-map.md b/docs/exec-plans/reference/telemetry-field-map.md
similarity index 99%
rename from docs/exec-plans/active/telemetry-field-map.md
rename to docs/exec-plans/reference/telemetry-field-map.md
index 83b4ac2..154a286 100644
--- a/docs/exec-plans/active/telemetry-field-map.md
+++ b/docs/exec-plans/reference/telemetry-field-map.md
@@ -1,6 +1,6 @@
 # Telemetry Source-to-Canonical Field Map
 
-<!-- Verified: 2026-03-10 -->
+<!-- Verified: 2026-03-14 -->
 
 **Status:** Reference
 **Purpose:** Define the canonical telemetry contract that all platform adapters must emit before any downstream projection or analytics.
diff --git a/package.json b/package.json
index 2a47a74..792dff0 100644
--- a/package.json
+++ b/package.json
@@ -49,7 +49,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "dev": "sh -c 'if lsof -iTCP:7888 -sTCP:LISTEN >/dev/null 2>&1; then echo \"Using existing dashboard server on 7888\"; cd apps/local-dashboard && bun install && bunx vite --strictPort; else cd apps/local-dashboard && bun install && bun run dev; fi'",
+    "dev": "sh -c 'if lsof -iTCP:7888 -sTCP:LISTEN >/dev/null 2>&1; then if curl -fsS http://127.0.0.1:7888/api/health | grep -q selftune-dashboard; then echo \"Using existing dashboard server on 7888\"; cd apps/local-dashboard && bun install && bunx vite --strictPort; else echo \"Port 7888 is occupied by a non-selftune service\"; exit 1; fi; else cd apps/local-dashboard && bun install && bun run dev; fi'",
     "dev:dashboard": "bun run cli/selftune/index.ts dashboard --port 7888 --no-open",
     "lint": "bunx @biomejs/biome check .",
     "lint:fix": "bunx @biomejs/biome check --write .",
diff --git a/tests/dashboard/badge-routes.test.ts b/tests/dashboard/badge-routes.test.ts
index 4a45e58..e2e8306 100644
--- a/tests/dashboard/badge-routes.test.ts
+++ b/tests/dashboard/badge-routes.test.ts
@@ -1,10 +1,14 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type {
+  OverviewResponse,
+  SkillReportResponse,
+} from "../../cli/selftune/dashboard-contract.js";
 import type { StatusResult } from "../../cli/selftune/status.js";
 import type {
-  EvolutionAuditEntry,
   EvolutionEvidenceEntry,
-  QueryLogRecord,
-  SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../../cli/selftune/types.js";
 
@@ -16,69 +20,116 @@ import type {
  */
 
 let startDashboardServer: typeof import("../../cli/selftune/dashboard-server.js").startDashboardServer;
+let testSpaDir: string;
 
 const reportSkillName = "test-skill";
-const dashboardFixture = {
-  telemetry: [] as SessionTelemetryRecord[],
+const overviewFixture: OverviewResponse = {
+  overview: {
+    telemetry: [],
+    skills: [
+      {
+        timestamp: "2026-03-10T10:00:00.000Z",
+        session_id: "sess-report-1",
+        skill_name: reportSkillName,
+        skill_path: "/tmp/test-skill/SKILL.md",
+        query: "Use the test skill",
+        triggered: true,
+      },
+    ] as SkillUsageRecord[],
+    evolution: [],
+    counts: {
+      telemetry: 0,
+      skills: 1,
+      evolution: 0,
+      evidence: 1,
+      sessions: 1,
+      prompts: 1,
+    },
+    unmatched_queries: [],
+    pending_proposals: [],
+  },
   skills: [
     {
-      timestamp: "2026-03-10T10:00:00.000Z",
-      session_id: "sess-report-1",
       skill_name: reportSkillName,
-      skill_path: "/tmp/test-skill/SKILL.md",
-      query: "Use the test skill",
-      triggered: true,
+      skill_scope: "global",
+      total_checks: 1,
+      triggered_count: 1,
+      pass_rate: 1,
+      unique_sessions: 1,
+      last_seen: "2026-03-10T10:00:00.000Z",
+      has_evidence: true,
     },
-  ] as SkillUsageRecord[],
-  queries: [
+  ],
+  version: "0.2.1-test",
+};
+const evidenceFixture: EvolutionEvidenceEntry[] = [
+  {
+    timestamp: "2026-03-10T10:00:00.000Z",
+    proposal_id: "proposal-test-skill-1",
+    skill_name: reportSkillName,
+    skill_path: "/tmp/test-skill/SKILL.md",
+    stage: "validated",
+    target: "description",
+    original_text: "Original description",
+    proposed_text: "Proposed description",
+    details: "Validation completed",
+    validation: {
+      before_pass_rate: 0.5,
+      after_pass_rate: 1,
+      improved: true,
+      regressions: [],
+      new_passes: [
+        {
+          query: "Use the test skill",
+          should_trigger: true,
+        },
+      ],
+      per_entry_results: [
+        {
+          entry: {
+            query: "Use the test skill",
+            should_trigger: true,
+          },
+          before_pass: false,
+          after_pass: true,
+        },
+      ],
+    },
+  },
+] as EvolutionEvidenceEntry[];
+const skillReportFixture: SkillReportResponse = {
+  skill_name: reportSkillName,
+  usage: {
+    total_checks: 1,
+    triggered_count: 1,
+    pass_rate: 1,
+  },
+  recent_invocations: [
     {
       timestamp: "2026-03-10T10:00:00.000Z",
       session_id: "sess-report-1",
       query: "Use the test skill",
+      triggered: true,
+      source: "claude_code_repair",
     },
-  ] as QueryLogRecord[],
-  evolution: [] as EvolutionAuditEntry[],
-  evidence: [
-    {
-      timestamp: "2026-03-10T10:00:00.000Z",
-      proposal_id: "proposal-test-skill-1",
-      skill_name: reportSkillName,
-      skill_path: "/tmp/test-skill/SKILL.md",
-      stage: "validated",
-      target: "description",
-      original_text: "Original description",
-      proposed_text: "Proposed description",
-      details: "Validation completed",
-      validation: {
-        before_pass_rate: 0.5,
-        after_pass_rate: 1,
-        improved: true,
-        regressions: [],
-        new_passes: [
-          {
-            query: "Use the test skill",
-            should_trigger: true,
-          },
-        ],
-        per_entry_results: [
-          {
-            entry: {
-              query: "Use the test skill",
-              should_trigger: true,
-            },
-            before_pass: false,
-            after_pass: true,
-          },
-        ],
-      },
-    },
-  ] as EvolutionEvidenceEntry[],
-  decisions: [],
-  computed: {
-    snapshots: {},
-    unmatched: [],
-    pendingProposals: [],
+  ],
+  evidence: [],
+  sessions_with_skill: 1,
+  evolution: [],
+  pending_proposals: [],
+  token_usage: {
+    total_input_tokens: 0,
+    total_output_tokens: 0,
   },
+  canonical_invocations: [],
+  duration_stats: {
+    avg_duration_ms: 0,
+    total_duration_ms: 0,
+    execution_count: 0,
+    total_errors: 0,
+  },
+  prompt_samples: [],
+  session_metadata: [],
 };
 const statusFixture: StatusResult = {
   skills: [
@@ -105,6 +156,13 @@ const statusFixture: StatusResult = {
 beforeAll(async () => {
   const mod = await import("../../cli/selftune/dashboard-server.js");
   startDashboardServer = mod.startDashboardServer;
+  testSpaDir = mkdtempSync(join(tmpdir(), "selftune-badge-test-"));
+  mkdirSync(join(testSpaDir, "assets"), { recursive: true });
+  writeFileSync(
+    join(testSpaDir, "index.html"),
+    `<!DOCTYPE html><html lang="en"><body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`,
+  );
+  writeFileSync(join(testSpaDir, "assets", "app.js"), "console.log('selftune badge test spa');\n");
 });
 
 describe("badge routes", () => {
@@ -113,11 +171,13 @@ describe("badge routes", () => {
   beforeAll(async () => {
     server = await startDashboardServer({
       port: 0,
-      host: "localhost",
+      host: "127.0.0.1",
+      spaDir: testSpaDir,
       openBrowser: false,
-      dataLoader: () => dashboardFixture,
+      overviewLoader: () => overviewFixture,
+      skillReportLoader: (skillName) => (skillName === reportSkillName ? skillReportFixture : null),
       statusLoader: () => statusFixture,
-      evidenceLoader: () => dashboardFixture.evidence,
+      evidenceLoader: () => evidenceFixture,
     });
   });
 
@@ -127,7 +187,7 @@ describe("badge routes", () => {
 
   describe("GET /badge/:skillName", () => {
     it("returns SVG content type for unknown skill", async () => {
-      const res = await fetch(`http://localhost:${server.port}/badge/nonexistent-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/badge/nonexistent-skill`);
       expect(res.status).toBe(404);
       expect(res.headers.get("content-type")).toContain("image/svg+xml");
       const body = await res.text();
@@ -136,24 +196,24 @@ describe("badge routes", () => {
     });
 
     it("returns valid SVG badge (not JSON error)", async () => {
-      const res = await fetch(`http://localhost:${server.port}/badge/nonexistent-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/badge/nonexistent-skill`);
       const body = await res.text();
       // Should be valid SVG, not a JSON error
       expect(body.startsWith("<svg")).toBe(true);
     });
 
     it("includes Cache-Control no-cache header", async () => {
-      const res = await fetch(`http://localhost:${server.port}/badge/test-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/badge/test-skill`);
       expect(res.headers.get("cache-control")).toBe("no-cache, no-store");
     });
 
     it("includes CORS headers", async () => {
-      const res = await fetch(`http://localhost:${server.port}/badge/test-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/badge/test-skill`);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
     });
 
     it("returns text/plain for ?format=markdown", async () => {
-      const res = await fetch(`http://localhost:${server.port}/badge/nonexistent?format=markdown`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/badge/nonexistent?format=markdown`);
       // For unknown skills, still returns SVG 404 (badge not found)
       // But for known skills would return text/plain
       expect(res.status).toBe(404);
@@ -162,18 +222,18 @@ describe("badge routes", () => {
 
   describe("GET /report/:skillName", () => {
     it("returns 404 for unknown skill", async () => {
-      const res = await fetch(`http://localhost:${server.port}/report/nonexistent-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/report/nonexistent-skill`);
       expect(res.status).toBe(404);
     });
 
     it("includes CORS headers", async () => {
-      const res = await fetch(`http://localhost:${server.port}/report/test-skill`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/report/test-skill`);
       expect(res.headers.get("access-control-allow-origin")).toBe("*");
     });
 
     it("renders evidence sections for a real skill report", async () => {
       const res = await fetch(
-        `http://localhost:${server.port}/report/${encodeURIComponent(reportSkillName)}`,
+        `http://127.0.0.1:${server.port}/report/${encodeURIComponent(reportSkillName)}`,
       );
       expect(res.status).toBe(200);
       const html = await res.text();
@@ -182,8 +242,12 @@ describe("badge routes", () => {
     });
 
     it("returns text/plain for missing skill", async () => {
-      const res = await fetch(`http://localhost:${server.port}/report/nonexistent`);
+      const res = await fetch(`http://127.0.0.1:${server.port}/report/nonexistent`);
       expect(res.headers.get("content-type")).toContain("text/plain");
     });
   });
 });
+
+afterAll(() => {
+  rmSync(testSpaDir, { recursive: true, force: true });
+});
diff --git a/tests/dashboard/dashboard-server.test.ts b/tests/dashboard/dashboard-server.test.ts
index b345f99..698394a 100644
--- a/tests/dashboard/dashboard-server.test.ts
+++ b/tests/dashboard/dashboard-server.test.ts
@@ -1,10 +1,14 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type {
   OverviewResponse,
   SkillReportResponse,
 } from "../../cli/selftune/dashboard-contract.js";
 
 let startDashboardServer: typeof import("../../cli/selftune/dashboard-server.js").startDashboardServer;
+let testSpaDir: string;
 
 const overviewFixture: OverviewResponse = {
   overview: {
@@ -93,16 +97,24 @@ const skillReportFixture: SkillReportResponse = {
 beforeAll(async () => {
   const mod = await import("../../cli/selftune/dashboard-server.js");
   startDashboardServer = mod.startDashboardServer;
+  testSpaDir = mkdtempSync(join(tmpdir(), "selftune-dashboard-test-"));
+  mkdirSync(join(testSpaDir, "assets"), { recursive: true });
+  writeFileSync(
+    join(testSpaDir, "index.html"),
+    `<!DOCTYPE html><html lang="en"><body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`,
+  );
+  writeFileSync(join(testSpaDir, "assets", "app.js"), "console.log('selftune test spa');\n");
 });
 
 describe("dashboard-server", () => {
-  let serverPromise: Promise<{ server: unknown; stop: () => void; port: number }> | null = null;
+  let serverPromise: ReturnType<typeof startDashboardServer> | null = null;
 
-  async function getServer(): Promise<{ server: unknown; stop: () => void; port: number }> {
+  async function getServer(): Promise<Awaited<ReturnType<typeof startDashboardServer>>> {
     if (!serverPromise) {
       serverPromise = startDashboardServer({
         port: 0,
         host: "127.0.0.1",
+        spaDir: testSpaDir,
         openBrowser: false,
         overviewLoader: () => overviewFixture,
         skillReportLoader: (skillName) => (skillName === "test-skill" ? skillReportFixture : null),
@@ -224,6 +236,12 @@ describe("dashboard-server", () => {
       );
       expect(res.status).toBe(404);
     });
+
+    it("returns 400 for malformed skill-name encoding", async () => {
+      const server = await getServer();
+      const res = await fetch(`http://127.0.0.1:${server.port}/api/v2/skills/%E0%A4%A`);
+      expect(res.status).toBe(400);
+    });
   });
 
   describe("POST /api/actions/*", () => {
@@ -292,6 +310,7 @@ describe("server lifecycle", () => {
     const s = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
+      spaDir: testSpaDir,
       openBrowser: false,
       overviewLoader: () => overviewFixture,
       skillReportLoader: () => null,
@@ -306,6 +325,7 @@ describe("server lifecycle", () => {
     const s = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
+      spaDir: testSpaDir,
       openBrowser: false,
       overviewLoader: () => overviewFixture,
       skillReportLoader: () => null,
@@ -323,6 +343,7 @@ describe("SPA shell loading", () => {
     const server = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
+      spaDir: testSpaDir,
       openBrowser: false,
       overviewLoader: () => {
         overviewLoaderCalls++;
@@ -367,6 +388,7 @@ describe("report loading", () => {
     const server = await startDashboardServer({
       port: 0,
       host: "127.0.0.1",
+      spaDir: testSpaDir,
       openBrowser: false,
       overviewLoader: () => overviewFixture,
       skillReportLoader: () => {
@@ -410,3 +432,7 @@ describe("report loading", () => {
     }
   });
 });
+
+afterAll(() => {
+  rmSync(testSpaDir, { recursive: true, force: true });
+});

From 789ebef95c744bc3efe563e8294809f1cf50e89e Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:46:52 +0300
Subject: [PATCH 09/14] Fix biome lint errors in dashboard tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 tests/dashboard/badge-routes.test.ts     | 7 ++-----
 tests/dashboard/dashboard-server.test.ts | 2 +-
 2 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/tests/dashboard/badge-routes.test.ts b/tests/dashboard/badge-routes.test.ts
index e2e8306..3915117 100644
--- a/tests/dashboard/badge-routes.test.ts
+++ b/tests/dashboard/badge-routes.test.ts
@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type {
@@ -7,10 +7,7 @@ import type {
   SkillReportResponse,
 } from "../../cli/selftune/dashboard-contract.js";
 import type { StatusResult } from "../../cli/selftune/status.js";
-import type {
-  EvolutionEvidenceEntry,
-  SkillUsageRecord,
-} from "../../cli/selftune/types.js";
+import type { EvolutionEvidenceEntry, SkillUsageRecord } from "../../cli/selftune/types.js";
 
 /**
  * Badge route tests — validates /badge/:skillName and /report/:skillName
diff --git a/tests/dashboard/dashboard-server.test.ts b/tests/dashboard/dashboard-server.test.ts
index 698394a..ebc1fda 100644
--- a/tests/dashboard/dashboard-server.test.ts
+++ b/tests/dashboard/dashboard-server.test.ts
@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type {

From 61c7deca68475ceb9a53657ad6d171e8b1e1b91c Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 17:58:28 +0300
Subject: [PATCH 10/14] Make autonomous loop the default scheduler path

---
 cli/selftune/cron/setup.ts      |  15 +-
 cli/selftune/init.ts            |  19 +++
 cli/selftune/orchestrate.ts     |  13 +-
 cli/selftune/schedule.ts        | 245 +++++++++++++++++++++++++++-----
 docs/integration-guide.md       |  49 +++----
 skill/Workflows/Cron.md         |  18 ++-
 skill/Workflows/Initialize.md   |   7 +-
 skill/Workflows/Schedule.md     |  22 +--
 tests/cron/setup.test.ts        |   7 +-
 tests/orchestrate.test.ts       |   5 +-
 tests/schedule/schedule.test.ts |  65 ++++++---
 11 files changed, 340 insertions(+), 125 deletions(-)

diff --git a/cli/selftune/cron/setup.ts b/cli/selftune/cron/setup.ts
index ef9a4fb..0c91080 100644
--- a/cli/selftune/cron/setup.ts
+++ b/cli/selftune/cron/setup.ts
@@ -45,18 +45,11 @@ export const DEFAULT_CRON_JOBS: CronJobConfig[] = [
     description: "Daily health check after source sync",
   },
   {
-    name: "selftune-evolve",
-    cron: "0 3 * * 0",
-    message:
-      "Run selftune sync, review source-truth status, and run selftune evolve --sync-first for any skills with enough negative evidence or clear undertriggering patterns. Report proposed changes and validation results.",
-    description: "Weekly evolution at 3am Sunday",
-  },
-  {
-    name: "selftune-watch",
+    name: "selftune-orchestrate",
     cron: "0 */6 * * *",
     message:
-      "Run selftune sync first, then run selftune watch --sync-first on all recently evolved skills to detect regressions against the latest source-truth telemetry.",
-    description: "Monitor regressions every 6 hours after source sync",
+      "Run selftune orchestrate --max-skills 3. This performs source-truth sync, selects candidate skills, evolves validated low-risk descriptions autonomously, and watches recent deployments for regressions.",
+    description: "Autonomous improvement loop every 6 hours",
   },
 ];
 
@@ -123,7 +116,7 @@ export function loadCronJobs(jobsPath: string): CronJobConfig[] {
 /** Register default cron jobs with OpenClaw. */
 export async function setupCronJobs(tz: string, dryRun: boolean): Promise<void> {
   const openclawPath = Bun.which("openclaw");
-  if (!openclawPath) {
+  if (!dryRun && !openclawPath) {
     console.error("Error: openclaw is not installed or not in PATH.");
     console.error("");
     console.error("Install OpenClaw:");
diff --git a/cli/selftune/init.ts b/cli/selftune/init.ts
index e4e4f07..a1b2735 100644
--- a/cli/selftune/init.ts
+++ b/cli/selftune/init.ts
@@ -8,6 +8,7 @@
  *
  * Usage:
  *   selftune init [--agent <type>] [--cli-path <path>] [--force]
+ *   selftune init --enable-autonomy [--schedule-format cron|launchd|systemd]
  */
 
 import {
@@ -407,6 +408,8 @@ export async function cliMain(): Promise<void> {
       agent: { type: "string" },
       "cli-path": { type: "string" },
       force: { type: "boolean", default: false },
+      "enable-autonomy": { type: "boolean", default: false },
+      "schedule-format": { type: "string" },
     },
     strict: true,
   });
@@ -466,6 +469,22 @@ export async function cliMain(): Promise<void> {
       total: doctorResult.summary.total,
     }),
   );
+
+  if (values["enable-autonomy"]) {
+    const { installSchedule } = await import("./schedule.js");
+    const scheduleResult = installSchedule({
+      format: values["schedule-format"],
+    });
+    console.log(
+      JSON.stringify({
+        level: "info",
+        code: "autonomy_enabled",
+        format: scheduleResult.format,
+        activated: scheduleResult.activated,
+        files: scheduleResult.artifacts.map((artifact) => artifact.path),
+      }),
+    );
+  }
 }
 
 // Guard: only run when invoked directly
diff --git a/cli/selftune/orchestrate.ts b/cli/selftune/orchestrate.ts
index 092156d..131d10a 100644
--- a/cli/selftune/orchestrate.ts
+++ b/cli/selftune/orchestrate.ts
@@ -79,6 +79,14 @@ export interface OrchestrateResult {
 /** Candidate selection criteria. */
 const CANDIDATE_STATUSES = new Set(["CRITICAL", "WARNING", "UNGRADED"]);
 
+function candidatePriority(skill: SkillStatus): number {
+  const statusWeight =
+    skill.status === "CRITICAL" ? 300 : skill.status === "WARNING" ? 200 : 100;
+  const missedWeight = Math.min(skill.missedQueries, 50);
+  const passPenalty = skill.passRate === null ? 0 : Math.round((1 - skill.passRate) * 100);
+  return statusWeight + missedWeight + passPenalty;
+}
+
 /**
  * Injectable dependencies for orchestrate(). Pass overrides in tests.
  */
@@ -126,8 +134,9 @@ export function selectCandidates(
   options: Pick<OrchestrateOptions, "skillFilter" | "maxSkills">,
 ): SkillAction[] {
   const actions: SkillAction[] = [];
+  const orderedSkills = [...skills].sort((a, b) => candidatePriority(b) - candidatePriority(a));
 
-  for (const skill of skills) {
+  for (const skill of orderedSkills) {
     // Apply skill filter
     if (options.skillFilter && skill.name !== options.skillFilter) {
       actions.push({
@@ -370,7 +379,7 @@ export async function orchestrate(
         skillPath,
         windowSessions: 20,
         regressionThreshold: 0.1,
-        autoRollback: false,
+        autoRollback: true,
         syncFirst: false,
       });
 
diff --git a/cli/selftune/schedule.ts b/cli/selftune/schedule.ts
index 74d401e..820958e 100644
--- a/cli/selftune/schedule.ts
+++ b/cli/selftune/schedule.ts
@@ -8,9 +8,13 @@
  * For OpenClaw-specific scheduling, see `selftune cron`.
  *
  * Usage:
- *   selftune schedule [--format cron|launchd|systemd]
+ *   selftune schedule [--format cron|launchd|systemd] [--install] [--dry-run]
  */
 
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 
 import { DEFAULT_CRON_JOBS } from "./cron/setup.js";
@@ -33,10 +37,8 @@ function commandForJob(jobName: string): string {
       return "selftune sync";
     case "selftune-status":
       return "selftune sync && selftune status";
-    case "selftune-evolve":
-      return "selftune evolve --sync-first --skill <name> --skill-path <path>";
-    case "selftune-watch":
-      return "selftune watch --sync-first --skill <name> --skill-path <path>";
+    case "selftune-orchestrate":
+      return "selftune orchestrate --max-skills 3";
     default:
       return `selftune ${jobName.replace("selftune-", "")}`;
   }
@@ -49,6 +51,19 @@ export const SCHEDULE_ENTRIES: ScheduleEntry[] = DEFAULT_CRON_JOBS.map((job) =>
   description: job.description,
 }));
 
+export interface ScheduleInstallArtifact {
+  path: string;
+  content: string;
+}
+
+export interface ScheduleInstallResult {
+  format: ScheduleFormat;
+  artifacts: ScheduleInstallArtifact[];
+  activationCommands: string[];
+  activated: boolean;
+  dryRun: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers for launchd/systemd generation
 // ---------------------------------------------------------------------------
@@ -91,7 +106,6 @@ function cronToLaunchdSchedule(cron: string): string {
 function cronToOnCalendar(cron: string): string {
   if (cron === "*/30 * * * *") return "*:0/30";
   if (cron === "0 8 * * *") return "*-*-* 08:00:00";
-  if (cron === "0 3 * * 0") return "Sun *-*-* 03:00:00";
   if (cron === "0 */6 * * *") return "*-*-* 0/6:00:00";
   return cron;
 }
@@ -123,8 +137,9 @@ export function generateCrontab(): string {
   const lines = [
     "# selftune automation — add to your crontab with: crontab -e",
     "#",
-    "# The core loop: sync → status → evolve → watch",
-    "# Adjust paths and skill names for your setup.",
+    "# The core loop: sync → orchestrate",
+    "# status remains a reporting job; orchestrate handles sync, candidate",
+    "# selection, low-risk description evolution, and watch/rollback follow-up.",
     "#",
   ];
   for (const entry of SCHEDULE_ENTRIES) {
@@ -135,15 +150,14 @@ export function generateCrontab(): string {
   return lines.join("\n");
 }
 
-export function generateLaunchd(): string {
-  const plists: string[] = [];
-
-  for (const entry of SCHEDULE_ENTRIES) {
-    const label = `com.selftune.${entry.name.replace("selftune-", "")}`;
-    const args = toLaunchdArgs(entry.command);
-    const schedule = cronToLaunchdSchedule(entry.schedule);
+function buildLaunchdDefinition(entry: ScheduleEntry): { label: string; content: string } {
+  const label = `com.selftune.${entry.name.replace("selftune-", "")}`;
+  const args = toLaunchdArgs(entry.command);
+  const schedule = cronToLaunchdSchedule(entry.schedule);
 
-    plists.push(`<?xml version="1.0" encoding="UTF-8"?>
+  return {
+    label,
+    content: `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <!--
@@ -167,48 +181,176 @@ ${schedule}
   <key>StandardErrorPath</key>
   <string>/tmp/${entry.name}.err</string>
 </dict>
-</plist>`);
+</plist>`,
+  };
+}
+
+export function generateLaunchd(): string {
+  const plists: string[] = [];
+
+  for (const entry of SCHEDULE_ENTRIES) {
+    plists.push(buildLaunchdDefinition(entry).content);
   }
 
   return plists.join("\n\n");
 }
 
+function buildSystemdDefinition(
+  entry: ScheduleEntry,
+): { baseName: string; timerContent: string; serviceContent: string } {
+  const unitName = entry.name;
+  const calendar = cronToOnCalendar(entry.schedule);
+  const execStart = toSystemdExecStart(entry.command);
+
+  return {
+    baseName: unitName,
+    timerContent: `[Unit]
+Description=${entry.description}
+
+[Timer]
+OnCalendar=${calendar}
+Persistent=true
+
+[Install]
+WantedBy=timers.target`,
+    serviceContent: `[Unit]
+Description=${entry.description}
+
+[Service]
+Type=oneshot
+ExecStart=${execStart}`,
+  };
+}
+
 export function generateSystemd(): string {
   const units: string[] = [];
 
   for (const entry of SCHEDULE_ENTRIES) {
-    const unitName = entry.name;
-    const calendar = cronToOnCalendar(entry.schedule);
-    const execStart = toSystemdExecStart(entry.command);
+    const definition = buildSystemdDefinition(entry);
 
-    units.push(`# --- ${unitName}.timer ---
+    units.push(`# --- ${definition.baseName}.timer ---
 # ${entry.description}
 #
 # Install:
-#   cp ${unitName}.service ${unitName}.timer ~/.config/systemd/user/
+#   cp ${definition.baseName}.service ${definition.baseName}.timer ~/.config/systemd/user/
 #   systemctl --user daemon-reload
-#   systemctl --user enable --now ${unitName}.timer
+#   systemctl --user enable --now ${definition.baseName}.timer
 
-[Unit]
-Description=${entry.description}
+${definition.timerContent}
 
-[Timer]
-OnCalendar=${calendar}
-Persistent=true
+# --- ${definition.baseName}.service ---
+${definition.serviceContent}`);
+  }
 
-[Install]
-WantedBy=timers.target
+  return units.join("\n\n");
+}
 
-# --- ${unitName}.service ---
-[Unit]
-Description=${entry.description}
+export function selectInstallFormat(
+  requested?: string,
+  platform: NodeJS.Platform = process.platform,
+): { ok: true; format: ScheduleFormat } | { ok: false; error: string } {
+  if (requested) {
+    if (!isValidFormat(requested)) {
+      return {
+        ok: false,
+        error: `Unknown format "${requested}". Valid formats: ${VALID_FORMATS.join(", ")}`,
+      };
+    }
+    return { ok: true, format: requested };
+  }
 
-[Service]
-Type=oneshot
-ExecStart=${execStart}`);
+  if (platform === "darwin") return { ok: true, format: "launchd" };
+  if (platform === "linux") return { ok: true, format: "systemd" };
+  return { ok: true, format: "cron" };
+}
+
+export function buildInstallPlan(
+  format: ScheduleFormat,
+  homeDir = homedir(),
+): { artifacts: ScheduleInstallArtifact[]; activationCommands: string[] } {
+  if (format === "cron") {
+    const path = join(homeDir, ".selftune", "schedule", "selftune.crontab");
+    return {
+      artifacts: [{ path, content: generateCrontab() }],
+      activationCommands: [`crontab ${path}`],
+    };
   }
 
-  return units.join("\n\n");
+  if (format === "launchd") {
+    const launchAgentsDir = join(homeDir, "Library", "LaunchAgents");
+    const artifacts = SCHEDULE_ENTRIES.map((entry) => {
+      const definition = buildLaunchdDefinition(entry);
+      return {
+        path: join(launchAgentsDir, `${definition.label}.plist`),
+        content: definition.content,
+      };
+    });
+
+    return {
+      artifacts,
+      activationCommands: artifacts.flatMap((artifact) => [
+        `launchctl unload ${artifact.path} >/dev/null 2>&1 || true`,
+        `launchctl load ${artifact.path}`,
+      ]),
+    };
+  }
+
+  const systemdDir = join(homeDir, ".config", "systemd", "user");
+  const definitions = SCHEDULE_ENTRIES.map(buildSystemdDefinition);
+  return {
+    artifacts: definitions.flatMap((definition) => [
+      { path: join(systemdDir, `${definition.baseName}.timer`), content: definition.timerContent },
+      {
+        path: join(systemdDir, `${definition.baseName}.service`),
+        content: definition.serviceContent,
+      },
+    ]),
+    activationCommands: [
+      "systemctl --user daemon-reload",
+      ...definitions.map((definition) => `systemctl --user enable --now ${definition.baseName}.timer`),
+    ],
+  };
+}
+
+function runShellCommand(command: string): number {
+  const result = spawnSync("/bin/sh", ["-c", command], { stdio: "inherit" });
+  return result.status ?? 1;
+}
+
+export function installSchedule(options: {
+  format?: string;
+  dryRun?: boolean;
+  homeDir?: string;
+  platform?: NodeJS.Platform;
+  runCommand?: (command: string) => number;
+} = {}): ScheduleInstallResult {
+  const formatResult = selectInstallFormat(options.format, options.platform);
+  if (!formatResult.ok) {
+    throw new Error(formatResult.error);
+  }
+
+  const plan = buildInstallPlan(formatResult.format, options.homeDir);
+  const dryRun = options.dryRun ?? false;
+
+  for (const artifact of plan.artifacts) {
+    if (dryRun) continue;
+    mkdirSync(dirname(artifact.path), { recursive: true });
+    writeFileSync(artifact.path, artifact.content, "utf-8");
+  }
+
+  let activated = false;
+  if (!dryRun) {
+    const runCommand = options.runCommand ?? runShellCommand;
+    activated = plan.activationCommands.every((command) => runCommand(command) === 0);
+  }
+
+  return {
+    format: formatResult.format,
+    artifacts: plan.artifacts,
+    activationCommands: plan.activationCommands,
+    activated,
+    dryRun,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -256,6 +398,8 @@ export function cliMain(): void {
   const { values } = parseArgs({
     options: {
       format: { type: "string", short: "f" },
+      install: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
       help: { type: "boolean", default: false },
     },
     strict: false,
@@ -266,14 +410,16 @@ export function cliMain(): void {
     console.log(`selftune schedule — Generate scheduling examples for automation
 
 Usage:
-  selftune schedule [--format cron|launchd|systemd]
+  selftune schedule [--format cron|launchd|systemd] [--install] [--dry-run]
 
 Flags:
   --format, -f    Output only one format (cron, launchd, or systemd)
+  --install       Write and activate schedule artifacts for the selected platform
+  --dry-run       Preview installed files and activation commands without writing
   --help          Show this help message
 
 The selftune automation loop is:
-  sync → status → evolve --sync-first → watch --sync-first
+  sync → orchestrate
 
 This command generates ready-to-use snippets for running that loop
 with standard system scheduling tools. No agent runtime required.
@@ -282,6 +428,27 @@ For OpenClaw-specific scheduling, see: selftune cron`);
     process.exit(0);
   }
 
+  if (values.install) {
+    const result = installSchedule({
+      format: values.format,
+      dryRun: values["dry-run"] ?? false,
+    });
+    console.log(
+      JSON.stringify(
+        {
+          format: result.format,
+          installed: !result.dryRun,
+          activated: result.activated,
+          files: result.artifacts.map((artifact) => artifact.path),
+          activationCommands: result.activationCommands,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
   const result = formatOutput(values.format);
   if (!result.ok) {
     console.error(result.error);
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
index 4a2a2f9..3ecf595 100644
--- a/docs/integration-guide.md
+++ b/docs/integration-guide.md
@@ -388,69 +388,60 @@ in your hook configuration, which resolves the correct script path at runtime.
 ## Automation
 
 selftune is designed to run unattended on any machine. The core automation
-loop is four commands:
+loop is centered on one command:
 
 ```text
-sync → status → evolve --sync-first → watch --sync-first
+orchestrate
 ```
 
-Run `selftune schedule` to generate ready-to-use snippets for your platform.
+`selftune orchestrate` runs source-truth sync first, selects candidate skills,
+deploys validated low-risk description changes autonomously, and watches recent
+deployments with auto-rollback enabled.
 
-### System cron (Linux/macOS — recommended default)
+Fastest path:
 
-The simplest path. Add to your crontab with `crontab -e`:
+```bash
+selftune init --enable-autonomy
+```
 
-```cron
-# Sync source-truth telemetry every 30 minutes
-*/30 * * * *  selftune sync
+Run `selftune schedule` to generate or install ready-to-use snippets for your platform.
 
-# Daily health check at 8am (syncs first)
-0 8 * * *     selftune sync && selftune status
+### System cron (Linux/macOS — recommended default)
 
-# Weekly evolution at 3am Sunday
-0 3 * * 0     selftune evolve --sync-first --skill <name> --skill-path <path>
+The simplest path. Install it directly:
 
-# Monitor regressions every 6 hours
-0 */6 * * *   selftune watch --sync-first --skill <name> --skill-path <path>
+```bash
+selftune schedule --install --format cron
 ```
 
-Replace `<name>` and `<path>` with your skill name and SKILL.md path.
+Or inspect the raw crontab first with `selftune schedule --format cron`.
 
 ### macOS launchd
 
 For macOS machines that need scheduling to survive reboots and sleep/wake:
 
 ```bash
-selftune schedule --format launchd > ~/Library/LaunchAgents/com.selftune.sync.plist
-launchctl load ~/Library/LaunchAgents/com.selftune.sync.plist
+selftune schedule --install --format launchd
 ```
 
-Run `selftune schedule --format launchd` for a full example plist.
+Run `selftune schedule --format launchd` for raw plist output without installing it.
 
 ### Linux systemd timer
 
 For systemd-based servers:
 
 ```bash
-selftune schedule --format systemd
-```
-
-Save the output as `~/.config/systemd/user/selftune-sync.timer` and
-`selftune-sync.service`, then:
-
-```bash
-systemctl --user daemon-reload
-systemctl --user enable --now selftune-sync.timer
+selftune schedule --install --format systemd
 ```
 
 ### OpenClaw integration (optional)
 
 If you use OpenClaw, `selftune cron setup` registers jobs directly with
 OpenClaw's Gateway Scheduler. This provides isolated sessions per cron run
-and automatic hot-reloading of evolved skills.
+and an autonomous orchestrated loop without manual scheduler setup.
 
 ```bash
-selftune cron setup                    # register 4 default jobs
+selftune cron setup                    # register autonomous jobs
 selftune cron setup --dry-run          # preview first
 selftune cron list                     # check registered jobs
 ```
diff --git a/skill/Workflows/Cron.md b/skill/Workflows/Cron.md
index 8d74249..a71ab70 100644
--- a/skill/Workflows/Cron.md
+++ b/skill/Workflows/Cron.md
@@ -5,8 +5,8 @@ This is the **OpenClaw-specific** scheduling path. For generic scheduling
 with system cron, launchd, or systemd, see `Workflows/Schedule.md` or
 run `selftune schedule`.
 
-The scheduled architecture is **source-truth first**: every
-status/evolve/watch pass should sync raw agent data before making decisions.
+The scheduled architecture is **source-truth first**: the autonomous loop
+should sync raw agent data before making decisions.
 
 ## When to Use
 
@@ -57,14 +57,13 @@ Remove all selftune cron jobs from OpenClaw.
 
 ## Default Job Schedule
 
-Setup registers these four jobs:
+Setup registers these three jobs:
 
 | Name | Cron Expression | Schedule | Description |
 |------|----------------|----------|-------------|
 | `selftune-sync` | `*/30 * * * *` | Every 30 minutes | Sync source-truth telemetry and rebuild repaired overlay |
 | `selftune-status` | `0 8 * * *` | Daily at 8am | Sync first, then report skills with pass rate below 80% |
-| `selftune-evolve` | `0 3 * * 0` | Weekly at 3am Sunday | Full evolution pipeline for undertriggering skills |
-| `selftune-watch` | `0 */6 * * *` | Every 6 hours | Sync first, then monitor recently evolved skills for regressions |
+| `selftune-orchestrate` | `0 */6 * * *` | Every 6 hours | Autonomous loop: sync, candidate selection, evolve, and watch |
 
 All jobs run in **isolated session** mode — each execution gets a clean
 session with no context accumulation from previous runs.
@@ -108,11 +107,10 @@ Skill snapshot version bumped — next agent turn uses updated description
 Better triggering in real-time, no restart needed
 ```
 
-The four jobs form a continuous loop:
+The three jobs form a continuous loop:
 - **sync** refreshes source-truth telemetry and rebuilds the repaired skill overlay every 30 minutes
 - **status** evaluates health only after that sync has completed
-- **evolve** runs `selftune evolve --sync-first` after reviewing synced status
-- **watch** runs `selftune watch --sync-first` before monitoring regressions and auto-rollback decisions
+- **orchestrate** runs `selftune orchestrate --max-skills 3`, which syncs, evolves validated low-risk descriptions autonomously, and watches recent deployments with auto-rollback
 
 Skills improve and take effect within seconds of the cron job completing.
 No deployment step, no restart, no manual intervention.
@@ -133,8 +131,8 @@ No deployment step, no restart, no manual intervention.
 ## Common Patterns
 
 **"Set up autonomous skill evolution"**
-> Run `selftune cron setup`. The four default jobs handle source sync,
-> health checks, evolution, and regression monitoring.
+> Run `selftune cron setup`. The default jobs handle source sync,
+> health checks, and the autonomous orchestrated loop.
 
 **"Preview before registering"**
 > Run `selftune cron setup --dry-run` to see exactly what commands
diff --git a/skill/Workflows/Initialize.md b/skill/Workflows/Initialize.md
index 3449850..24fe22b 100644
--- a/skill/Workflows/Initialize.md
+++ b/skill/Workflows/Initialize.md
@@ -11,7 +11,7 @@ Bootstrap selftune for first-time use or after changing environments.
 ## Default Command
 
 ```bash
-selftune init [--agent <type>] [--cli-path <path>] [--force]
+selftune init [--agent <type>] [--cli-path <path>] [--force] [--enable-autonomy] [--schedule-format <cron|launchd|systemd>]
 ```
 
 ## Options
@@ -21,6 +21,8 @@ selftune init [--agent <type>] [--cli-path <path>] [--force]
 | `--agent <type>` | Agent platform: `claude`, `codex`, `opencode` | Auto-detected |
 | `--cli-path <path>` | Override auto-detected CLI entry-point path | Auto-detected |
 | `--force` | Reinitialize even if config already exists | Off |
+| `--enable-autonomy` | Install and activate the autonomous scheduler for the current platform | Off |
+| `--schedule-format <type>` | Override the scheduler format used by `--enable-autonomy` | Platform default |
 
 ## Output Format
 
@@ -171,6 +173,9 @@ Bundled setup assets:
 > Install the CLI (`npm install -g selftune`), run `selftune init`,
 > install hooks, and verify with `selftune doctor`.
 
+**"Initialize and turn on the autonomous loop"**
+> Run `selftune init --enable-autonomy`. Use `--schedule-format` if you need to override the platform default scheduler.
+
 **"Hooks aren't capturing data"**
 > Run `selftune doctor` to check hook installation. Verify paths in
 > `~/.claude/settings.json` point to actual files.
diff --git a/skill/Workflows/Schedule.md b/skill/Workflows/Schedule.md
index 6ce93e0..17c6201 100644
--- a/skill/Workflows/Schedule.md
+++ b/skill/Workflows/Schedule.md
@@ -16,16 +16,15 @@ For OpenClaw-specific scheduling, see `Workflows/Cron.md`.
 
 ## The Automation Loop
 
-The core selftune automation loop is four commands:
+The core selftune automation loop is one command:
 
 ```
-sync → status → evolve --sync-first → watch --sync-first
+orchestrate
 ```
 
-1. **sync** refreshes source-truth telemetry from all agent sources
-2. **status** reports skill health (run after sync)
-3. **evolve --sync-first** improves underperforming skills (syncs before analyzing)
-4. **watch --sync-first** monitors recently evolved skills for regressions
+`selftune orchestrate` runs source-truth sync first, selects candidate skills,
+deploys validated low-risk description changes autonomously, and watches recent
+deployments with auto-rollback enabled.
 
 ## Default Command
 
@@ -40,25 +39,26 @@ Outputs examples for all three scheduling systems (cron, launchd, systemd).
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--format <type>` | Output only one format: `cron`, `launchd`, or `systemd` | All formats |
+| `--install` | Write and activate scheduler artifacts for the selected/default platform | Off |
+| `--dry-run` | Preview installed files and activation commands without writing | Off |
 | `--help` | Show help message | — |
 
 ## Steps
 
 1. Run `selftune schedule` to see all examples
 2. Pick the scheduling system for your platform
-3. Customize the snippets (skill names, paths, timezone)
-4. Install using the instructions in the output
+3. Install them directly with `--install`, or inspect/customize the raw snippets first
 
 ## Common Patterns
 
 **"Quick setup on a Linux server"**
-> Run `selftune schedule --format cron`, paste the output into `crontab -e`.
+> Run `selftune schedule --install --format cron`.
 
 **"Set up on macOS"**
-> Run `selftune schedule --format launchd`, save as a `.plist` file, load with `launchctl`.
+> Run `selftune schedule --install --format launchd`.
 
 **"Set up on a systemd-based server"**
-> Run `selftune schedule --format systemd`, save as `.timer` and `.service` files, enable with `systemctl`.
+> Run `selftune schedule --install --format systemd`.
 
 **"I use OpenClaw"**
 > Use `selftune cron setup` instead — it registers jobs directly with OpenClaw's scheduler.
diff --git a/tests/cron/setup.test.ts b/tests/cron/setup.test.ts
index ee917ed..0117e96 100644
--- a/tests/cron/setup.test.ts
+++ b/tests/cron/setup.test.ts
@@ -55,8 +55,8 @@ describe("buildCronAddArgs", () => {
 // 2. DEFAULT_CRON_JOBS has expected structure
 // ---------------------------------------------------------------------------
 describe("DEFAULT_CRON_JOBS", () => {
-  test("has exactly 4 jobs", () => {
-    expect(DEFAULT_CRON_JOBS).toHaveLength(4);
+  test("has exactly 3 jobs", () => {
+    expect(DEFAULT_CRON_JOBS).toHaveLength(3);
   });
 
   test("all jobs have required fields", () => {
@@ -82,8 +82,7 @@ describe("DEFAULT_CRON_JOBS", () => {
     const names = DEFAULT_CRON_JOBS.map((j) => j.name);
     expect(names).toContain("selftune-sync");
     expect(names).toContain("selftune-status");
-    expect(names).toContain("selftune-evolve");
-    expect(names).toContain("selftune-watch");
+    expect(names).toContain("selftune-orchestrate");
   });
 });
 
diff --git a/tests/orchestrate.test.ts b/tests/orchestrate.test.ts
index ca242da..d9f4f3f 100644
--- a/tests/orchestrate.test.ts
+++ b/tests/orchestrate.test.ts
@@ -300,6 +300,7 @@ describe("orchestrate", () => {
 
   test("watches recently evolved skills from audit log", async () => {
     let watchCalled = false;
+    let watchAutoRollback: boolean | undefined;
     const recentTimestamp = new Date().toISOString();
     const deps = makeDeps({
       readAuditEntries: () => [
@@ -311,8 +312,9 @@ describe("orchestrate", () => {
           skill_name: "RecentSkill",
         },
       ],
-      watch: async () => {
+      watch: async (opts) => {
         watchCalled = true;
+        watchAutoRollback = opts.autoRollback;
         return {
           snapshot: {
             timestamp: new Date().toISOString(),
@@ -339,6 +341,7 @@ describe("orchestrate", () => {
 
     const result = await orchestrate(baseOptions, deps);
     expect(watchCalled).toBe(true);
+    expect(watchAutoRollback).toBe(true);
     expect(result.summary.watched).toBe(1);
   });
 
diff --git a/tests/schedule/schedule.test.ts b/tests/schedule/schedule.test.ts
index c38ccd8..65b7589 100644
--- a/tests/schedule/schedule.test.ts
+++ b/tests/schedule/schedule.test.ts
@@ -1,19 +1,22 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  buildInstallPlan,
   formatOutput,
   generateCrontab,
   generateLaunchd,
   generateSystemd,
+  installSchedule,
   SCHEDULE_ENTRIES,
+  selectInstallFormat,
 } from "../../cli/selftune/schedule.js";
 
 // ---------------------------------------------------------------------------
 // 1. SCHEDULE_ENTRIES structure
 // ---------------------------------------------------------------------------
 describe("SCHEDULE_ENTRIES", () => {
-  test("has exactly 4 entries", () => {
-    expect(SCHEDULE_ENTRIES).toHaveLength(4);
+  test("has exactly 3 entries", () => {
+    expect(SCHEDULE_ENTRIES).toHaveLength(3);
   });
 
   test("all entries have required fields", () => {
@@ -29,22 +32,16 @@ describe("SCHEDULE_ENTRIES", () => {
     }
   });
 
-  test("contains sync, status, evolve, and watch entries", () => {
+  test("contains sync, status, and orchestrate entries", () => {
     const names = SCHEDULE_ENTRIES.map((e) => e.name);
     expect(names).toContain("selftune-sync");
     expect(names).toContain("selftune-status");
-    expect(names).toContain("selftune-evolve");
-    expect(names).toContain("selftune-watch");
+    expect(names).toContain("selftune-orchestrate");
   });
 
-  test("evolve entry uses --sync-first", () => {
-    const evolve = SCHEDULE_ENTRIES.find((e) => e.name === "selftune-evolve");
-    expect(evolve?.command).toContain("--sync-first");
-  });
-
-  test("watch entry uses --sync-first", () => {
-    const watch = SCHEDULE_ENTRIES.find((e) => e.name === "selftune-watch");
-    expect(watch?.command).toContain("--sync-first");
+  test("orchestrate entry runs the autonomous loop", () => {
+    const orchestrate = SCHEDULE_ENTRIES.find((e) => e.name === "selftune-orchestrate");
+    expect(orchestrate?.command).toContain("selftune orchestrate");
   });
 
   test("derives from DEFAULT_CRON_JOBS (shared source of truth)", () => {
@@ -53,6 +50,8 @@ describe("SCHEDULE_ENTRIES", () => {
     expect(sync?.schedule).toBe("*/30 * * * *");
     const status = SCHEDULE_ENTRIES.find((e) => e.name === "selftune-status");
     expect(status?.schedule).toBe("0 8 * * *");
+    const orchestrate = SCHEDULE_ENTRIES.find((e) => e.name === "selftune-orchestrate");
+    expect(orchestrate?.schedule).toBe("0 */6 * * *");
   });
 });
 
@@ -114,8 +113,7 @@ describe("generateLaunchd", () => {
     const output = generateLaunchd();
     expect(output).toContain("com.selftune.sync");
     expect(output).toContain("com.selftune.status");
-    expect(output).toContain("com.selftune.evolve");
-    expect(output).toContain("com.selftune.watch");
+    expect(output).toContain("com.selftune.orchestrate");
   });
 });
 
@@ -149,8 +147,41 @@ describe("generateSystemd", () => {
     const output = generateSystemd();
     expect(output).toContain("selftune-sync.timer");
     expect(output).toContain("selftune-status.timer");
-    expect(output).toContain("selftune-evolve.timer");
-    expect(output).toContain("selftune-watch.timer");
+    expect(output).toContain("selftune-orchestrate.timer");
+  });
+});
+
+describe("install helpers", () => {
+  test("selectInstallFormat defaults by platform", () => {
+    expect(selectInstallFormat(undefined, "darwin")).toEqual({ ok: true, format: "launchd" });
+    expect(selectInstallFormat(undefined, "linux")).toEqual({ ok: true, format: "systemd" });
+    expect(selectInstallFormat(undefined, "win32")).toEqual({ ok: true, format: "cron" });
+  });
+
+  test("buildInstallPlan returns launchd artifacts and activation commands", () => {
+    const plan = buildInstallPlan("launchd", "/tmp/test-home");
+    expect(plan.artifacts.some((artifact) => artifact.path.includes("LaunchAgents"))).toBe(true);
+    expect(plan.activationCommands.some((command) => command.includes("launchctl load"))).toBe(
+      true,
+    );
+  });
+
+  test("installSchedule dry-run does not activate commands", () => {
+    let commandsRun = 0;
+    const result = installSchedule({
+      format: "cron",
+      dryRun: true,
+      homeDir: "/tmp/test-home",
+      runCommand: () => {
+        commandsRun++;
+        return 0;
+      },
+    });
+
+    expect(result.dryRun).toBe(true);
+    expect(result.activated).toBe(false);
+    expect(commandsRun).toBe(0);
+    expect(result.artifacts[0]?.path).toContain(".selftune/schedule/selftune.crontab");
   });
 });
 

From 0c4a64e3b11ab5c528cc2649a09f5eb3d5d58eef Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 18:02:47 +0300
Subject: [PATCH 11/14] Document orchestrate as the autonomous loop

---
 skill/SKILL.md                     | 30 ++++++++-----
 skill/Workflows/Orchestrate.md     | 70 ++++++++++++++++++++++++++++++
 skill/references/setup-patterns.md |  3 +-
 3 files changed, 90 insertions(+), 13 deletions(-)
 create mode 100644 skill/Workflows/Orchestrate.md

diff --git a/skill/SKILL.md b/skill/SKILL.md
index 18e6ae9..c89fe21 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -11,7 +11,7 @@ compatibility: >
   optionally integrate with ~/.claude/settings.json.
 metadata:
   version: "0.2.2"
-  last_updated: "2026-03-09"
+  last_updated: "2026-03-14"
 ---
 
 # selftune
@@ -41,6 +41,7 @@ informational progress lines.
 selftune grade    --skill <name> [--expectations "..."] [--agent <name>]
 selftune evals    --skill <name> [--list-skills] [--stats] [--max N]
 selftune evolve   --skill <name> --skill-path <path> [--dry-run]
+selftune orchestrate [--dry-run] [--review-required] [--max-skills N] [--skill <name>]
 selftune rollback --skill <name> --skill-path <path> [--proposal-id <id>]
 selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
 selftune status
@@ -53,11 +54,11 @@ selftune ingest-openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force
 selftune wrap-codex -- <codex args>
 selftune replay     [--since DATE] [--dry-run] [--force] [--verbose]
 selftune sync       [--since DATE] [--dry-run] [--force]
+selftune schedule   [--format <cron|launchd|systemd>] [--install] [--dry-run]
 selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
 selftune cron setup [--dry-run] [--tz <timezone>]
 selftune cron list
 selftune cron remove [--dry-run]
-selftune dashboard [--port <port>] [--no-open]
 selftune evolve-body --skill <name> --skill-path <path> --target <routing_table|full_body> [--dry-run]
 selftune baseline   --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]
 selftune badge      --skill <name> [--format svg|markdown|url] [--output <path>]
@@ -75,6 +76,7 @@ selftune export-canonical [--out FILE] [--pretty] [--platform <name>] [--record-
 | grade, score, evaluate, assess session | Grade | Workflows/Grade.md |
 | evals, eval set, undertriggering, skill stats | Evals | Workflows/Evals.md |
 | evolve, improve, triggers, catch more queries | Evolve | Workflows/Evolve.md |
+| orchestrate, autonomous loop, run the loop, auto improve, self-improving | Orchestrate | Workflows/Orchestrate.md |
 | rollback, undo, restore, revert evolution | Rollback | Workflows/Rollback.md |
 | watch, monitor, regression, post-deploy, performing | Watch | Workflows/Watch.md |
 | doctor, health, hooks, broken, diagnose | Doctor | Workflows/Doctor.md |
@@ -83,7 +85,8 @@ selftune export-canonical [--out FILE] [--pretty] [--platform <name>] [--record-
 | sync, source truth, rebuild repaired overlay, rebuild telemetry, refresh logs | Sync | Workflows/Sync.md |
 | contribute, share, community, export data, anonymized | Contribute | Workflows/Contribute.md |
 | init, setup, bootstrap, first time | Initialize | Workflows/Initialize.md |
-| cron, schedule, autonomous, automate evolution | Cron | Workflows/Cron.md |
+| schedule, launchd, systemd, crontab, install scheduler | Schedule | Workflows/Schedule.md |
+| cron, openclaw scheduler, openclaw jobs | Cron | Workflows/Cron.md |
 | auto-activate, suggestions, activation rules, nag, why suggest | AutoActivation | Workflows/AutoActivation.md |
 | dashboard, visual, open dashboard, skill grid, serve dashboard, live dashboard | Dashboard | Workflows/Dashboard.md |
 | evolution memory, context memory, session continuity, what happened last | EvolutionMemory | Workflows/EvolutionMemory.md |
@@ -144,13 +147,13 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
    +--------------------------------------------------------------------+
 ```
 
-1. **Observe** -- Hooks capture every session (queries, triggers, metrics)
-2. **Detect** -- `evals` finds missed triggers across invocation types
+1. **Observe** -- source-truth transcripts and telemetry are replayed into the shared logs
+2. **Detect** -- `sync`, `status`, and `evals` surface missed triggers and weak routing
 3. **Diagnose** -- `grade` evaluates session quality with evidence
-4. **Propose** -- `evolve` generates description improvements
-5. **Validate** -- Evolution is tested against the eval set
-6. **Deploy** -- Updated description replaces the original (with backup)
-7. **Watch** -- `watch` monitors for regressions post-deploy
+4. **Propose** -- `evolve` generates low-risk description improvements
+5. **Validate** -- proposals are checked before deploy
+6. **Deploy** -- validated descriptions can ship autonomously
+7. **Watch** -- `watch` monitors recent changes and rolls back regressions
 
 ## Resource Index
 
@@ -170,6 +173,7 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
 | `Workflows/Grade.md` | Grade a session with expectations and evidence |
 | `Workflows/Evals.md` | Generate eval sets, list skills, show stats |
 | `Workflows/Evolve.md` | Evolve a skill description from failure patterns |
+| `Workflows/Orchestrate.md` | Run the autonomy-first sync → evolve → watch loop |
 | `Workflows/Rollback.md` | Undo an evolution, restore previous description |
 | `Workflows/Watch.md` | Post-deploy regression monitoring |
 | `Workflows/Doctor.md` | Health checks on logs, hooks, schema |
@@ -177,9 +181,10 @@ Observe --> Detect --> Diagnose --> Propose --> Validate --> Deploy --> Watch
 | `Workflows/Replay.md` | Backfill logs from Claude Code transcripts |
 | `Workflows/Sync.md` | Source-truth sync across supported agents + repaired overlay rebuild |
 | `Workflows/Contribute.md` | Export anonymized data for community contribution |
+| `Workflows/Schedule.md` | Install platform-native scheduling for the autonomous loop |
 | `Workflows/Cron.md` | Manage OpenClaw cron jobs for autonomous evolution |
 | `Workflows/AutoActivation.md` | Auto-activation hook behavior and rules |
-| `Workflows/Dashboard.md` | Dashboard modes: static, export, live server |
+| `Workflows/Dashboard.md` | Run the SPA dashboard and per-skill report views |
 | `Workflows/EvolutionMemory.md` | Evolution memory system for session continuity |
 | `Workflows/EvolveBody.md` | Full body and routing table evolution |
 | `Workflows/Baseline.md` | No-skill baseline comparison and lift measurement |
@@ -203,6 +208,7 @@ them.
 - "What skills are undertriggering?"
 - "Generate evals for the pptx skill"
 - "Evolve the pptx skill to catch more queries"
+- "Run the autonomous selftune loop"
 - "Rollback the last evolution"
 - "Is the skill performing well after the change?"
 - "Check selftune health"
@@ -221,8 +227,8 @@ them.
 - "Rebuild the repaired skill overlay"
 - "Contribute my selftune data to the community"
 - "Share anonymized skill data"
-- "Set up cron jobs for autonomous evolution"
-- "Schedule selftune to run automatically"
+- "Install autonomous scheduling for this machine"
+- "Set up OpenClaw cron jobs for selftune"
 - "Ingest my OpenClaw sessions"
 - "Why is selftune suggesting things?"
 - "Customize activation rules"
diff --git a/skill/Workflows/Orchestrate.md b/skill/Workflows/Orchestrate.md
new file mode 100644
index 0000000..8e66dbd
--- /dev/null
+++ b/skill/Workflows/Orchestrate.md
@@ -0,0 +1,70 @@
+# selftune Orchestrate Workflow
+
+Run the autonomy-first selftune loop in one command.
+
+`selftune orchestrate` is the primary closed-loop entrypoint. It runs
+source-truth sync, computes current skill health, selects candidates,
+deploys validated low-risk description changes autonomously, and watches
+recent changes with auto-rollback enabled.
+
+## When to Use
+
+- You want the full autonomous loop, not isolated subcommands
+- You want to improve skills without manually chaining `sync`, `status`, `evolve`, and `watch`
+- You want a dry-run of what selftune would change next
+- You want a stricter review policy for a single run
+
+## Default Command
+
+```bash
+selftune orchestrate
+```
+
+## Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry-run` | Plan and validate without deploying changes | Off |
+| `--review-required` | Keep validated changes in review mode instead of deploying | Off |
+| `--skill <name>` | Limit the loop to one skill | All skills |
+| `--max-skills <n>` | Cap how many candidates are processed in one run | `3` |
+| `--recent-window <hours>` | Window for post-deploy watch/rollback checks | `24` |
+| `--sync-force` | Force a full source replay before candidate selection | Off |
+
+## Default Behavior
+
+- Sync source-truth telemetry first
+- Prioritize critical/warning/ungraded skills with real missed-query signal
+- Deploy validated low-risk description changes automatically
+- Watch recent deployments and roll back regressions automatically
+
+Use `--review-required` only when you want a stricter policy for a specific run.
+
+## Common Patterns
+
+**"Run the full loop now"**
+> Run `selftune orchestrate`.
+
+**"Show me what would change first"**
+> Run `selftune orchestrate --dry-run`.
+
+**"Only work on one skill"**
+> Run `selftune orchestrate --skill selftune`.
+
+**"Keep review in the loop for this run"**
+> Run `selftune orchestrate --review-required`.
+
+**"Force a full replay before acting"**
+> Run `selftune orchestrate --sync-force`.
+
+## Output
+
+The command prints:
+
+- sync results
+- candidate-selection reasoning
+- evolve/watch actions taken
+- skipped skills and why
+- a final summary with counts and elapsed time
+
+This is the recommended runtime for recurring autonomous scheduling.
diff --git a/skill/references/setup-patterns.md b/skill/references/setup-patterns.md
index 8f26fc3..05757c3 100644
--- a/skill/references/setup-patterns.md
+++ b/skill/references/setup-patterns.md
@@ -45,7 +45,7 @@ the repo root so hook paths and telemetry cover the whole workspace.
 - Run `selftune init --agent openclaw`
 - Use `selftune ingest-openclaw` for ingestion
 - Use `selftune doctor` to verify the shared logs are healthy
-- Use `selftune cron setup` if the user wants autonomous recurring runs
+- Use `selftune cron setup` if the user specifically wants OpenClaw-managed recurring runs
 
 ## Mixed-Agent Setup
 
@@ -54,6 +54,7 @@ combined.
 
 - Initialize each platform against the same `~/.selftune/` data directory
 - Ingest platform-specific logs into the shared JSONL schema
+- Use `selftune schedule --install` for the default autonomous scheduler path
 - Use `selftune status`, `selftune dashboard`, and `selftune workflows` on the
   merged dataset
 

From 4ea63c3d188ae55366a8cf6f5b988dfd3ebe40d2 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 19:30:41 +0300
Subject: [PATCH 12/14] Document autonomy-first setup path

---
 README.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0028a5e..4b5d022 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,14 @@ npx selftune@latest status
 npx selftune@latest dashboard
 ```
 
+Autonomy quick start:
+
+```bash
+npx selftune@latest init --enable-autonomy
+npx selftune@latest orchestrate --dry-run
+npx selftune@latest schedule --install --dry-run
+```
+
 **CLI only** (no installed skill):
 
 ```bash
@@ -92,6 +100,7 @@ A continuous feedback loop that makes your skills learn and adapt from real work
 - **Source-truth sync** — `selftune sync` now leads the product loop, using transcripts/logs as truth and hooks as hints
 - **SQLite-backed local app** — `selftune dashboard` now serves the React SPA by default with faster overview/report routes on top of materialized local data
 - **Autonomous low-risk evolution** — description evolution is autonomous by default, with explicit review-required mode for stricter policies
+- **Autonomous scheduling** — `selftune init --enable-autonomy` and `selftune schedule --install` make the orchestrated loop the default recurring runtime
 - **Full skill body evolution** — evolve routing tables and entire skill bodies using teacher-student model with structural, trigger, and quality gates
 - **Synthetic eval generation** — `selftune evals --synthetic` generates eval sets from `SKILL.md` for cold-start skills
 - **Cheap-loop evolution** — `selftune evolve --cheap-loop` uses haiku for proposal generation and validation, sonnet only for the final deployment gate
@@ -108,6 +117,7 @@ A continuous feedback loop that makes your skills learn and adapt from real work
 | `selftune status` | See which skills are undertriggering and why |
 | `selftune dashboard` | Open the React SPA dashboard (SQLite-backed) |
 | `selftune orchestrate` | Run the core loop: sync, inspect candidates, evolve, and watch |
+| `selftune schedule --install` | Install platform-native scheduling for the autonomous loop |
 | `selftune evals --skill <name>` | Generate eval sets from real session data (`--synthetic` for cold-start) |
 | `selftune evolve --skill <name>` | Propose, validate, and deploy improved descriptions (`--cheap-loop`, `--with-baseline`) |
 | `selftune evolve-body --skill <name>` | Evolve full skill body or routing table (teacher-student, 3-gate validation) |
@@ -154,7 +164,7 @@ Observability tools trace LLM calls. Skill authoring tools help you write skills
 
 **OpenCode** — `selftune ingest-opencode`
 
-**OpenClaw** — `selftune ingest-openclaw`. `selftune cron setup` remains available as an optional OpenClaw-oriented scheduler helper, but the main product loop is agent-agnostic.
+**OpenClaw** — `selftune ingest-openclaw`. `selftune cron setup` remains available as an optional OpenClaw-oriented scheduler helper, but the main product loop is still `selftune orchestrate` plus generic scheduling.
 
 Requires [Bun](https://bun.sh) or Node.js 18+. No extra API keys.
 

From f0ed1527fd4f0b2f9be498bbc60355102697730b Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 19:38:41 +0300
Subject: [PATCH 13/14] Harden autonomous scheduler install paths

---
 cli/selftune/dashboard-server.ts         |   7 +-
 cli/selftune/init.ts                     |  46 ++++---
 cli/selftune/orchestrate.ts              |   3 +-
 cli/selftune/schedule.ts                 | 165 ++++++++++++++++++-----
 docs/integration-guide.md                |   2 +-
 skill/Workflows/Schedule.md              |   4 +-
 tests/dashboard/dashboard-server.test.ts |  34 +++++
 tests/schedule/schedule.test.ts          |  44 +++++-
 8 files changed, 250 insertions(+), 55 deletions(-)

diff --git a/cli/selftune/dashboard-server.ts b/cli/selftune/dashboard-server.ts
index 8ee671a..d47671c 100644
--- a/cli/selftune/dashboard-server.ts
+++ b/cli/selftune/dashboard-server.ts
@@ -422,10 +422,15 @@ export async function startDashboardServer(
   const executeAction = options?.actionRunner ?? runAction;
 
   // -- SPA serving -------------------------------------------------------------
-  const spaDir = options?.spaDir ?? findSpaDir();
+  const requestedSpaDir = options?.spaDir ?? findSpaDir();
+  const spaDir =
+    requestedSpaDir && existsSync(join(requestedSpaDir, "index.html")) ? requestedSpaDir : null;
   if (spaDir) {
     console.log(`SPA found at ${spaDir}, serving as default dashboard`);
   } else {
+    if (options?.spaDir) {
+      console.warn(`Configured spaDir is missing index.html: ${options.spaDir}`);
+    }
     console.warn(
       "SPA build not found. Run `bun run build:dashboard` before using `selftune dashboard`.",
     );
diff --git a/cli/selftune/init.ts b/cli/selftune/init.ts
index a1b2735..ee1d5be 100644
--- a/cli/selftune/init.ts
+++ b/cli/selftune/init.ts
@@ -417,9 +417,10 @@ export async function cliMain(): Promise<void> {
   const configDir = SELFTUNE_CONFIG_DIR;
   const configPath = SELFTUNE_CONFIG_PATH;
   const force = values.force ?? false;
+  const enableAutonomy = values["enable-autonomy"] ?? false;
 
   // Check for existing config without force
-  if (!force && existsSync(configPath)) {
+  if (!force && !enableAutonomy && existsSync(configPath)) {
     try {
       const raw = readFileSync(configPath, "utf-8");
       const existing = JSON.parse(raw) as SelftuneConfig;
@@ -470,20 +471,35 @@ export async function cliMain(): Promise<void> {
     }),
   );
 
-  if (values["enable-autonomy"]) {
-    const { installSchedule } = await import("./schedule.js");
-    const scheduleResult = installSchedule({
-      format: values["schedule-format"],
-    });
-    console.log(
-      JSON.stringify({
-        level: "info",
-        code: "autonomy_enabled",
-        format: scheduleResult.format,
-        activated: scheduleResult.activated,
-        files: scheduleResult.artifacts.map((artifact) => artifact.path),
-      }),
-    );
+  if (enableAutonomy) {
+    try {
+      const { installSchedule } = await import("./schedule.js");
+      const scheduleResult = installSchedule({
+        format: values["schedule-format"],
+      });
+
+      if (!scheduleResult.activated) {
+        console.error(
+          "Failed to activate the autonomous scheduler. Re-run with --schedule-format or use `selftune schedule --install --dry-run` to inspect the generated artifacts first.",
+        );
+        process.exit(1);
+      }
+
+      console.log(
+        JSON.stringify({
+          level: "info",
+          code: "autonomy_enabled",
+          format: scheduleResult.format,
+          activated: scheduleResult.activated,
+          files: scheduleResult.artifacts.map((artifact) => artifact.path),
+        }),
+      );
+    } catch (err) {
+      console.error(
+        `Failed to enable autonomy: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
   }
 }
 
diff --git a/cli/selftune/orchestrate.ts b/cli/selftune/orchestrate.ts
index 131d10a..cd8d69b 100644
--- a/cli/selftune/orchestrate.ts
+++ b/cli/selftune/orchestrate.ts
@@ -80,8 +80,7 @@ export interface OrchestrateResult {
 const CANDIDATE_STATUSES = new Set(["CRITICAL", "WARNING", "UNGRADED"]);
 
 function candidatePriority(skill: SkillStatus): number {
-  const statusWeight =
-    skill.status === "CRITICAL" ? 300 : skill.status === "WARNING" ? 200 : 100;
+  const statusWeight = skill.status === "CRITICAL" ? 300 : skill.status === "WARNING" ? 200 : 100;
   const missedWeight = Math.min(skill.missedQueries, 50);
   const passPenalty = skill.passRate === null ? 0 : Math.round((1 - skill.passRate) * 100);
   return statusWeight + missedWeight + passPenalty;
diff --git a/cli/selftune/schedule.ts b/cli/selftune/schedule.ts
index 820958e..49052c6 100644
--- a/cli/selftune/schedule.ts
+++ b/cli/selftune/schedule.ts
@@ -12,7 +12,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
@@ -64,6 +64,9 @@ export interface ScheduleInstallResult {
   dryRun: boolean;
 }
 
+const CRON_BEGIN_MARKER = "# BEGIN SELFTUNE";
+const CRON_END_MARKER = "# END SELFTUNE";
+
 // ---------------------------------------------------------------------------
 // Helpers for launchd/systemd generation
 // ---------------------------------------------------------------------------
@@ -150,6 +153,30 @@ export function generateCrontab(): string {
   return lines.join("\n");
 }
 
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function wrapManagedCrontabBlock(content: string): string {
+  return `${CRON_BEGIN_MARKER}\n${content.trim()}\n${CRON_END_MARKER}\n`;
+}
+
+export function mergeManagedCrontab(existing: string, managedContent: string): string {
+  const managedBlock = wrapManagedCrontabBlock(managedContent);
+  const normalizedExisting = existing.replace(/\r\n/g, "\n");
+  const markerPattern = new RegExp(
+    `${escapeRegex(CRON_BEGIN_MARKER)}[\\s\\S]*?${escapeRegex(CRON_END_MARKER)}\\n?`,
+    "g",
+  );
+  const withoutExistingBlock = normalizedExisting.replace(markerPattern, "").trimEnd();
+
+  if (!withoutExistingBlock) {
+    return managedBlock;
+  }
+
+  return `${withoutExistingBlock}\n\n${managedBlock}`;
+}
+
 function buildLaunchdDefinition(entry: ScheduleEntry): { label: string; content: string } {
   const label = `com.selftune.${entry.name.replace("selftune-", "")}`;
   const args = toLaunchdArgs(entry.command);
@@ -195,9 +222,11 @@ export function generateLaunchd(): string {
   return plists.join("\n\n");
 }
 
-function buildSystemdDefinition(
-  entry: ScheduleEntry,
-): { baseName: string; timerContent: string; serviceContent: string } {
+function buildSystemdDefinition(entry: ScheduleEntry): {
+  baseName: string;
+  timerContent: string;
+  serviceContent: string;
+} {
   const unitName = entry.name;
   const calendar = cronToOnCalendar(entry.schedule);
   const execStart = toSystemdExecStart(entry.command);
@@ -272,7 +301,7 @@ export function buildInstallPlan(
     const path = join(homeDir, ".selftune", "schedule", "selftune.crontab");
     return {
       artifacts: [{ path, content: generateCrontab() }],
-      activationCommands: [`crontab ${path}`],
+      activationCommands: [`selftune schedule --apply-cron-artifact ${path}`],
     };
   }
 
@@ -295,6 +324,10 @@ export function buildInstallPlan(
     };
   }
 
+  if (format !== "systemd") {
+    throw new Error(`Unknown format "${format}". Valid formats: ${VALID_FORMATS.join(", ")}`);
+  }
+
   const systemdDir = join(homeDir, ".config", "systemd", "user");
   const definitions = SCHEDULE_ENTRIES.map(buildSystemdDefinition);
   return {
@@ -307,7 +340,9 @@ export function buildInstallPlan(
     ]),
     activationCommands: [
       "systemctl --user daemon-reload",
-      ...definitions.map((definition) => `systemctl --user enable --now ${definition.baseName}.timer`),
+      ...definitions.map(
+        (definition) => `systemctl --user enable --now ${definition.baseName}.timer`,
+      ),
     ],
   };
 }
@@ -317,13 +352,44 @@ function runShellCommand(command: string): number {
   return result.status ?? 1;
 }
 
-export function installSchedule(options: {
-  format?: string;
-  dryRun?: boolean;
-  homeDir?: string;
-  platform?: NodeJS.Platform;
-  runCommand?: (command: string) => number;
-} = {}): ScheduleInstallResult {
+function readCurrentCrontab(): string {
+  const result = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+
+  if (result.status === 0) {
+    return result.stdout;
+  }
+
+  const stderr = (result.stderr ?? "").trim();
+  if (stderr.includes("no crontab for")) {
+    return "";
+  }
+
+  throw new Error(stderr || `crontab -l failed with exit code ${result.status ?? 1}`);
+}
+
+export function applyCronArtifact(artifactPath: string): void {
+  const artifactContent = readFileSync(artifactPath, "utf-8");
+  const mergedPath = artifactPath.replace(/\.crontab$/, ".merged.crontab");
+  const mergedContent = mergeManagedCrontab(readCurrentCrontab(), artifactContent);
+
+  mkdirSync(dirname(mergedPath), { recursive: true });
+  writeFileSync(mergedPath, mergedContent, "utf-8");
+
+  const result = spawnSync("crontab", [mergedPath], { stdio: "inherit" });
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(`Failed to install merged crontab from ${mergedPath}`);
+  }
+}
+
+export function installSchedule(
+  options: {
+    format?: string;
+    dryRun?: boolean;
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+    runCommand?: (command: string) => number;
+  } = {},
+): ScheduleInstallResult {
   const formatResult = selectInstallFormat(options.format, options.platform);
   if (!formatResult.ok) {
     throw new Error(formatResult.error);
@@ -340,8 +406,17 @@ export function installSchedule(options: {
 
   let activated = false;
   if (!dryRun) {
-    const runCommand = options.runCommand ?? runShellCommand;
-    activated = plan.activationCommands.every((command) => runCommand(command) === 0);
+    if (formatResult.format === "cron") {
+      const cronArtifact = plan.artifacts[0];
+      if (!cronArtifact) {
+        throw new Error("Cron install plan is missing the selftune crontab artifact.");
+      }
+      applyCronArtifact(cronArtifact.path);
+      activated = true;
+    } else {
+      const runCommand = options.runCommand ?? runShellCommand;
+      activated = plan.activationCommands.every((command) => runCommand(command) === 0);
+    }
   }
 
   return {
@@ -400,12 +475,25 @@ export function cliMain(): void {
       format: { type: "string", short: "f" },
       install: { type: "boolean", default: false },
       "dry-run": { type: "boolean", default: false },
+      "apply-cron-artifact": { type: "string" },
       help: { type: "boolean", default: false },
     },
     strict: false,
     allowPositionals: true,
   });
 
+  if (values["apply-cron-artifact"]) {
+    try {
+      applyCronArtifact(values["apply-cron-artifact"]);
+      return;
+    } catch (err) {
+      console.error(
+        `Failed to apply selftune cron artifact: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
+  }
+
   if (values.help) {
     console.log(`selftune schedule — Generate scheduling examples for automation
 
@@ -429,24 +517,35 @@ For OpenClaw-specific scheduling, see: selftune cron`);
   }
 
   if (values.install) {
-    const result = installSchedule({
-      format: values.format,
-      dryRun: values["dry-run"] ?? false,
-    });
-    console.log(
-      JSON.stringify(
-        {
-          format: result.format,
-          installed: !result.dryRun,
-          activated: result.activated,
-          files: result.artifacts.map((artifact) => artifact.path),
-          activationCommands: result.activationCommands,
-        },
-        null,
-        2,
-      ),
-    );
-    return;
+    try {
+      const result = installSchedule({
+        format: values.format,
+        dryRun: values["dry-run"] ?? false,
+      });
+      if (!result.dryRun && !result.activated) {
+        console.error("Failed to activate installed schedule artifacts.");
+        process.exit(1);
+      }
+      console.log(
+        JSON.stringify(
+          {
+            format: result.format,
+            installed: !result.dryRun,
+            activated: result.activated,
+            files: result.artifacts.map((artifact) => artifact.path),
+            activationCommands: result.activationCommands,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    } catch (err) {
+      console.error(
+        `Failed to install schedule artifacts: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
   }
 
   const result = formatOutput(values.format);
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
index 3ecf595..bf916b3 100644
--- a/docs/integration-guide.md
+++ b/docs/integration-guide.md
@@ -391,7 +391,7 @@ selftune is designed to run unattended on any machine. The core automation
 loop is centered on one command:
 
 ```text
-orchestrate
+selftune orchestrate
 ```
 
 `selftune orchestrate` runs source-truth sync first, selects candidate skills,
diff --git a/skill/Workflows/Schedule.md b/skill/Workflows/Schedule.md
index 17c6201..309a877 100644
--- a/skill/Workflows/Schedule.md
+++ b/skill/Workflows/Schedule.md
@@ -18,8 +18,8 @@ For OpenClaw-specific scheduling, see `Workflows/Cron.md`.
 
 The core selftune automation loop is one command:
 
-```
-orchestrate
+```bash
+selftune orchestrate
 ```
 
 `selftune orchestrate` runs source-truth sync first, selects candidate skills,
diff --git a/tests/dashboard/dashboard-server.test.ts b/tests/dashboard/dashboard-server.test.ts
index ebc1fda..33e433f 100644
--- a/tests/dashboard/dashboard-server.test.ts
+++ b/tests/dashboard/dashboard-server.test.ts
@@ -378,6 +378,40 @@ describe("SPA shell loading", () => {
       server.stop();
     }
   });
+
+  it("returns 503 when a configured spaDir is missing index.html", async () => {
+    const brokenSpaDir = mkdtempSync(join(tmpdir(), "selftune-dashboard-broken-"));
+    mkdirSync(join(brokenSpaDir, "assets"), { recursive: true });
+
+    const server = await startDashboardServer({
+      port: 0,
+      host: "127.0.0.1",
+      spaDir: brokenSpaDir,
+      openBrowser: false,
+      overviewLoader: () => overviewFixture,
+      skillReportLoader: () => skillReportFixture,
+      statusLoader: () => ({
+        skills: [],
+        unmatchedQueries: 0,
+        pendingProposals: 0,
+        lastSession: null,
+        system: {
+          healthy: true,
+          pass: 0,
+          fail: 0,
+          warn: 0,
+        },
+      }),
+    });
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/`);
+      expect(res.status).toBe(503);
+    } finally {
+      server.stop();
+      rmSync(brokenSpaDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("report loading", () => {
diff --git a/tests/schedule/schedule.test.ts b/tests/schedule/schedule.test.ts
index 65b7589..d5c5e96 100644
--- a/tests/schedule/schedule.test.ts
+++ b/tests/schedule/schedule.test.ts
@@ -1,14 +1,17 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  applyCronArtifact,
   buildInstallPlan,
   formatOutput,
   generateCrontab,
   generateLaunchd,
   generateSystemd,
   installSchedule,
+  mergeManagedCrontab,
   SCHEDULE_ENTRIES,
   selectInstallFormat,
+  wrapManagedCrontabBlock,
 } from "../../cli/selftune/schedule.js";
 
 // ---------------------------------------------------------------------------
@@ -152,12 +155,23 @@ describe("generateSystemd", () => {
 });
 
 describe("install helpers", () => {
+  test("selectInstallFormat rejects unknown format", () => {
+    expect(selectInstallFormat("docker")).toEqual({
+      ok: false,
+      error: 'Unknown format "docker". Valid formats: cron, launchd, systemd',
+    });
+  });
+
   test("selectInstallFormat defaults by platform", () => {
     expect(selectInstallFormat(undefined, "darwin")).toEqual({ ok: true, format: "launchd" });
     expect(selectInstallFormat(undefined, "linux")).toEqual({ ok: true, format: "systemd" });
     expect(selectInstallFormat(undefined, "win32")).toEqual({ ok: true, format: "cron" });
   });
 
+  test("buildInstallPlan rejects unknown format at runtime", () => {
+    expect(() => buildInstallPlan("docker" as never, "/tmp/test-home")).toThrow(/Unknown format/);
+  });
+
   test("buildInstallPlan returns launchd artifacts and activation commands", () => {
     const plan = buildInstallPlan("launchd", "/tmp/test-home");
     expect(plan.artifacts.some((artifact) => artifact.path.includes("LaunchAgents"))).toBe(true);
@@ -181,7 +195,35 @@ describe("install helpers", () => {
     expect(result.dryRun).toBe(true);
     expect(result.activated).toBe(false);
     expect(commandsRun).toBe(0);
-    expect(result.artifacts[0]?.path).toContain(".selftune/schedule/selftune.crontab");
+    expect(result.artifacts[0]?.path).toMatch(
+      /[\\/]\.selftune[\\/]schedule[\\/]selftune\.crontab$/,
+    );
+  });
+
+  test("installSchedule throws for unknown format", () => {
+    expect(() => installSchedule({ format: "docker" })).toThrow(/Unknown format/);
+  });
+
+  test("mergeManagedCrontab preserves unrelated jobs and replaces the selftune block", () => {
+    const existing = [
+      "MAILTO=user@example.com",
+      "0 1 * * * backup-job",
+      wrapManagedCrontabBlock("old-selftune-job"),
+      "15 3 * * * analytics-job",
+    ].join("\n");
+
+    const merged = mergeManagedCrontab(existing, "0 */6 * * * selftune orchestrate --max-skills 3");
+
+    expect(merged).toContain("MAILTO=user@example.com");
+    expect(merged).toContain("0 1 * * * backup-job");
+    expect(merged).toContain("15 3 * * * analytics-job");
+    expect(merged).toContain("# BEGIN SELFTUNE");
+    expect(merged).toContain("0 */6 * * * selftune orchestrate --max-skills 3");
+    expect(merged).not.toContain("old-selftune-job");
+  });
+
+  test("applyCronArtifact throws when the artifact is missing", () => {
+    expect(() => applyCronArtifact("/tmp/does-not-exist/selftune.crontab")).toThrow();
   });
 });
 

From 8c5db2e39683d2776c52a0d1a944ede6df1b4848 Mon Sep 17 00:00:00 2001
From: WellDunDun <45949032+WellDunDun@users.noreply.github.com>
Date: Sat, 14 Mar 2026 19:46:20 +0300
Subject: [PATCH 14/14] Clarify sync force usage in README

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4b5d022..86b84c4 100644
--- a/README.md
+++ b/README.md
@@ -41,11 +41,13 @@ Quick proof path:
 
 ```bash
 npx selftune@latest doctor
-npx selftune@latest sync --force
+npx selftune@latest sync
 npx selftune@latest status
 npx selftune@latest dashboard
 ```
 
+Use `--force` only when you explicitly need to rebuild local state from scratch.
+
 Autonomy quick start:
 
 ```bash