HF Spaces deploy: initial orphan branch (no binary history)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,22 @@
+**/__pycache__/
+**/*.py[cod]
+**/.pytest_cache/
+**/.coverage
+**/node_modules/
+**/dist/
+**/.env
+**/*.env
+**/*.log
+**/logs/
+skillwiki/venv/
+skillwiki/.venv/
+skillwiki/skillwiki/storage/skill_repo/SkillStorage/
+artifacts/
+video/
+figures/
+docs/
+*.pptx
+*.docx
+.git/
+.vscode/
+.idea/

.gitignore

@@ -0,0 +1,119 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+venv/
+env/
+.venv/
+*.egg
+
+# Environment
+.env
+.env.local
+.env.*.local
+*.env
+
+# Node
+node_modules/
+dist/
+.cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Database
+*.db
+*.sqlite3
+
+# Misc
+*.tmp
+*.bak
+idea.txt
+
+# Runtime SkillStorage repository
+skillos/skillos/storage/skill_repo/SkillStorage/
+
+# Runtime harness evidence
+artifacts/harness-runs/
+artifacts/eval-readiness-runs/
+artifacts/input-skill-eval-runs/
+artifacts/skillsbench-runs/
+
+# Local one-click demo launcher state and secrets
+skillos-one-click-launcher/config.local.ps1
+skillwiki-launcher/config.local.ps1
+skillwiki-launcher/runtime/
+skillos-one-click-launcher/runtime/
+
+# Design / planning documents (not part of the public repo)
+DEEP_DISCUSSION.md
+DESIGN.md
+DEVELOPMENT.md
+FRONTEND_BACKEND_PLAN.md
+HOMOGENEOUS_GRAPH_DESIGN.md
+IMPLEMENTATION_ROADMAP.md
+SkillWiki.txt
+agent_framework.md
+DEMO_STARTUP.md
+
+# Internal docs directory
+docs/
+
+# Experiments (large / internal)
+experiment_1/
+experiment_2/
+
+# Benchmark results (runtime output, not source)
+# skillwiki/benchmarks/results/  <- tracked on dingcheng-dev branch
+
+# Video files
+video/
+
+# Runtime skill storage data
+skills/
+
+# Figures — all except the single overview image used in README
+figures/figure1_motivation/
+figures/figure2_overview/*.drawio
+figures/figure2_overview/*.pdf
+figures/figure2_overview/*.png
+figures/figure2_overview/*.bkp
+figures/figure2_overview/*.svg
+figures/figure3_system/
+figures/figure4_lifecycle/
+
+# Presentations and office files
+*.pptx
+*.docx
+
+# Codex workspace
+.codex/
+
+# Internal planning/summary documents inside skillwiki/
+skillwiki/PHASE_0_SUMMARY.md
+skillwiki/QUICK_COMMANDS.md
+skillwiki/USAGE_GUIDE.md
+skillwiki-frontend/scripts/pdf_to_png.mjs
+skillwiki/quickstart.sh
+skillwiki/quickstart.bat

Dockerfile

@@ -0,0 +1,40 @@
+# ── Stage 1: build frontend ──────────────────────────────────────────────────
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /build/frontend
+COPY skillwiki-frontend/package*.json ./
+RUN npm ci --prefer-offline
+
+COPY skillwiki-frontend/ ./
+# Disable WebSocket in the hosted build (HF Spaces doesn't support it)
+ENV VITE_SKILLOS_DISABLE_WS=1
+RUN npm run build
+
+# ── Stage 2: runtime ─────────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install slim Python deps (no heavy DB drivers)
+COPY skillwiki/requirements-hf.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install the skillwiki package
+COPY skillwiki/ ./skillwiki/
+RUN pip install --no-cache-dir -e ./skillwiki
+
+# Copy built frontend
+COPY --from=frontend-builder /build/frontend/dist ./frontend/dist
+
+# HF Spaces runs as user 1000
+RUN useradd -m -u 1000 skillwiki && chown -R skillwiki:skillwiki /app
+USER 1000
+
+# HF Spaces requires port 7860
+EXPOSE 7860
+
+ENV LLM_API_URL=https://api.deepseek.com
+ENV LLM_MODEL=deepseek-chat
+ENV SKILLWIKI_FRONTEND_DIST=/app/frontend/dist
+
+CMD ["python", "-m", "skillwiki.api.main", "--host", "0.0.0.0", "--port", "7860", "--repository-backend", "memory"]

README.md

@@ -0,0 +1,234 @@
+<div align="center">
+
+# SkillWiki
+
+**A Living Knowledge Infrastructure for Agent Skills**
+
+Just as Wikipedia organizes human knowledge and GitHub governs software, **SkillWiki** provides the missing infrastructure for agent skills. It transforms heterogeneous knowledge sources — trajectories, documents, API specs, and execution experience — into reusable skill assets that are grounded in their originating evidence, version-controlled, and continuously evolved. SkillWiki covers the complete skill lifecycle: from knowledge ingestion and skill production, through provenance-aware graph exploration and human governance, to execution-driven health monitoring and automated evolution. The result is a shared infrastructure where knowledge, skills, and execution experience co-evolve together.
+
+<br/>
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![GitHub stars](https://img.shields.io/github/stars/Huangdingcheng/SkillWiki?style=flat-square&logo=github&color=yellow)](https://github.com/Huangdingcheng/SkillWiki)
+
+
+<br/>
+
+[📺 **Demo Video**](https://www.youtube.com/watch?v=TODO) &nbsp;·&nbsp;
+[📖 **Paper**](https://arxiv.org/abs/2606.16523) 
+
+</div>
+
+---
+
+<p align="center">
+  <img src="figures/figure2_overview/overview.png" width="900" alt="SkillWiki system overview"/>
+  <br/>
+  <em>SkillWiki system overview — from multi-source ingestion to governed skill evolution.</em>
+</p>
+
+---
+
+## Key Features
+
+| | Feature | Description |
+|:---:|---|---|
+| 📥 | **Multi-source ingestion** | Trajectories, documents, API specs, scripts, and existing skill JSON/JSONL files |
+| 🔄 | **Governed lifecycle** | Eight-stage state machine (S0–S7) with automated verification and full audit trail |
+| 🕸️ | **Provenance knowledge graph** | Typed edges — `depends_on`, `composes_with`, `evolved_from`, `replaces`, and more |
+| 🩺 | **Health & evolution engine** | Continuous monitoring detects degraded skills and queues repair proposals automatically |
+| 🌐 | **Bilingual UI** | English (default) and Chinese — toggle via the language button in the header |
+| ⌨️ | **CLI-first** | Every operation available as a `skillwiki` command for scripting and agent integration |
+
+---
+
+## Lifecycle
+
+```
+  S0 Raw  ──►  S1 Candidate  ──►  S2 Draft  ──►  S3 Verified  ──►  S4 Released
+                                                                          │
+                                             S7 Archived  ◄──  S6 Deprecated  ◄──  S5 Degraded
+```
+
+| State | Name | Meaning |
+|:---:|---|---|
+| **S0** | Raw | Ingested source material, not yet extracted |
+| **S1** | Candidate | Extracted skill candidate awaiting review |
+| **S2** | Draft | Formalized schema, pending verification |
+| **S3** | Verified | Passed automated postcondition checks |
+| **S4** | Released | Approved for agent use in production |
+| **S5** | Degraded | Success rate fell below health threshold |
+| **S6** | Deprecated | Replaced or retired |
+| **S7** | Archived | Read-only historical record |
+
+---
+
+## Quick Start
+
+### Requirements
+
+- Python 3.10+
+- Node.js 18+ *(frontend only)*
+
+### Install
+
+```bash
+git clone https://github.com/Huangdingcheng/SkillWiki.git
+cd SkillWiki/skillwiki
+
+python -m venv venv
+source venv/bin/activate      # Linux / Mac
+venv\Scripts\activate         # Windows
+
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Start the backend
+
+```bash
+skillwiki serve --port 8001 --api-key YOUR_LLM_API_KEY
+```
+
+### Start the frontend *(optional)*
+
+```bash
+cd ../skillwiki-frontend
+npm install
+npm run dev    # → http://localhost:3000
+```
+
+### One-click launcher (Windows)
+
+Double-click **`START_SKILLWIKI_DEMO.bat`** in the repository root. On first run you will be prompted for your LLM endpoint and API key (saved to `skillwiki-launcher\config.local.ps1`, which is Git-ignored — never commit it).
+
+```
+Backend:  http://127.0.0.1:8001
+Frontend: http://127.0.0.1:5174/wiki
+```
+
+Restore the public demo fixtures after a restart:
+
+```
+RESTORE_SKILLWIKI_DEMO_STATE.bat
+```
+
+---
+
+## Demo Walkthrough
+
+| Step | Page | What to explore |
+|:---:|---|---|
+| 1 | [`/wiki`](http://127.0.0.1:5174/wiki) | Skill library — browse, filter by state / tag, inspect schemas |
+| 2 | [`/ingest`](http://127.0.0.1:5174/ingest) | Paste an API doc or upload a file; watch candidates extracted live |
+| 3 | [`/graph`](http://127.0.0.1:5174/graph) | Provenance knowledge graph — Nebula, Readable, and Debug view presets |
+| 4 | [`/harness`](http://127.0.0.1:5174/harness) | Execute-verify loop; observe automated repair attempts |
+| 5 | [`/evaluation`](http://127.0.0.1:5174/evaluation) | SkillsBench P0 sparse-subset analysis |
+| 6 | [`/versions`](http://127.0.0.1:5174/versions) | Business-readable diffs and re-verification after changes |
+
+---
+
+## CLI Reference
+
+Install once after cloning:
+
+```bash
+cd skillwiki && pip install -e .
+```
+
+All commands accept `--api-url <URL>` (default `http://127.0.0.1:8001`).
+
+### Server
+
+```bash
+skillwiki serve [--host HOST] [--port PORT] [--backend memory|sqlite|postgres]
+```
+
+### Knowledge Ingestion
+
+```bash
+# source_type: trajectory | document | api_doc | script | past_skills
+skillwiki ingest run <source_type> <input> [--create]
+
+skillwiki ingest run api_doc     ./openai_spec.md --create
+skillwiki ingest run trajectory  "open browser -> search -> copy link"
+skillwiki ingest run past_skills ./skills.json --max-candidates 20
+skillwiki ingest status <candidate_id>
+```
+
+### Skill Lifecycle
+
+```bash
+skillwiki skill list    [--state S3] [--tag nlp] [--limit 20]
+skillwiki skill get     <skill_id>   [--full]
+skillwiki skill status  <skill_id>
+skillwiki skill exec    <skill_id>   --input '{"key": "value"}'
+
+skillwiki audit   <skill_id>
+skillwiki verify  <skill_id>  [--harness mock|claude_code|codex] [--max-retries 3] [--watch]
+skillwiki promote <skill_id>  <target_state>
+```
+
+### Health & Evolution
+
+```bash
+skillwiki health             [--json]   # system-wide overview
+skillwiki health <skill_id>  [--json]   # success rate, issues, open proposals
+
+skillwiki repair <skill_id>             # generate maintenance candidate
+skillwiki evolve             [--json]   # run one full evolution cycle
+```
+
+### Maintenance Proposals
+
+```bash
+skillwiki proposal list    [--status pending|accepted|rejected] [--json]
+skillwiki proposal accept  <proposal_id>
+skillwiki proposal reject  <proposal_id>
+```
+
+### Knowledge Graph
+
+```bash
+skillwiki graph neighbors  <skill_id>  [--depth 1]
+skillwiki graph show       <skill_id>  [--view skill_only|provenance|version_impact] [--depth 2]
+skillwiki graph deps       <skill_id>
+skillwiki graph export     <skill_id>  [-o output.json] [--view provenance] [--depth 2]
+```
+
+### Natural Language Execution
+
+```bash
+skillwiki run "summarize the attached PDF and extract action items" [--verbose]
+```
+
+---
+
+## What SkillWiki Provides
+
+- Knowledge-to-skill transformation from heterogeneous sources.
+- Evidence-grounded skill assets with explicit provenance.
+- Multi-granularity skill organization and dependency management.
+- Provenance-aware exploration and visualization.
+- Versioned skill governance with interpretable evolution.
+- Execution-driven verification and continuous improvement.
+- End-to-end demonstrations of reusable skill ecosystems.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `LLM_API_KEY` | — | LLM API key *(required)* |
+| `LLM_API_URL` | `https://api.deepseek.com` | LLM base URL |
+| `LLM_MODEL` | `deepseek-v4-flash` | Model name |
+| `SKILLOS_API_TARGET` | `http://127.0.0.1:8001` | Frontend proxy target |
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 SkillWiki Authors

RESTORE_SKILLWIKI_DEMO_STATE.bat

@@ -0,0 +1,7 @@
+@echo off
+setlocal
+cd /d "%~dp0"
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0skillwiki-launcher\scripts\Restore-SkillWikiDemoState.ps1"
+echo.
+echo Press any key to close this restore window. SkillWiki keeps running in the background.
+pause >nul

START_SKILLWIKI_DEMO.bat

@@ -0,0 +1,10 @@
+@echo off
+setlocal
+set "SCRIPT_DIR=%~dp0"
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%skillwiki-launcher\scripts\Start-SkillWikiDemo.ps1"
+if errorlevel 1 (
+  echo.
+  echo SkillWiki demo failed to start. Check the error above, then press any key to close this window.
+  pause >nul
+)
+endlocal

STOP_SKILLWIKI_DEMO.bat

@@ -0,0 +1,5 @@
+@echo off
+setlocal
+set "SCRIPT_DIR=%~dp0"
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%SCRIPT_DIR%skillwiki-launcher\scripts\Stop-SkillWikiDemo.ps1"
+endlocal

docker-compose.yml

@@ -0,0 +1,35 @@
+version: '3.9'
+
+services:
+  api:
+    build:
+      context: ./skillwiki
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    environment:
+      - LLM_API_KEY=${LLM_API_KEY}
+      - LLM_MODEL=${LLM_MODEL:-claude-sonnet-4-6}
+    command: >
+      python -m skillwiki.api.main
+      --api-key ${LLM_API_KEY}
+      --host 0.0.0.0
+      --port 8000
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  frontend:
+    build:
+      context: ./skillwiki-frontend
+      dockerfile: Dockerfile
+    ports:
+      - "80:80"
+    depends_on:
+      - api
+
+networks:
+  default:
+    name: skillwiki-network

scripts/demo_readiness_check.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_RUN_ROOT = REPO_ROOT / "artifacts" / "eval-readiness-runs"
+
+
+class ApiClient:
+    def __init__(self, api_base: str, raw_dir: Path, timeout_s: int = 60) -> None:
+        self.api_base = api_base.rstrip("/")
+        self.raw_dir = raw_dir
+        self.timeout_s = timeout_s
+        self.raw_dir.mkdir(parents=True, exist_ok=True)
+
+    def get(self, path: str, label: str) -> dict[str, Any]:
+        return self._request("GET", path, None, label)
+
+    def post(self, path: str, payload: dict[str, Any], label: str) -> dict[str, Any]:
+        return self._request("POST", path, payload, label)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None,
+        label: str,
+    ) -> dict[str, Any]:
+        url = path if path.startswith(("http://", "https://")) else f"{self.api_base}{path}"
+        body = None if payload is None else json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(url, data=body, method=method)
+        if label == "frontend_home":
+            request.add_header("Accept", "text/html,*/*")
+        else:
+            request.add_header("Accept", "application/json")
+        if payload is not None:
+            request.add_header("Content-Type", "application/json")
+        start = time.perf_counter()
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout_s) as response:
+                text = response.read().decode("utf-8", errors="replace")
+                status = response.status
+        except urllib.error.HTTPError as exc:
+            text = exc.read().decode("utf-8", errors="replace")
+            status = exc.code
+        except Exception as exc:
+            text = json.dumps({"error": str(exc)}, ensure_ascii=False)
+            status = 0
+        elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+        parsed = _parse_json(text)
+        envelope = {
+            "label": label,
+            "method": method,
+            "url": url,
+            "status_code": status,
+            "elapsed_ms": elapsed_ms,
+            "request": _preview(payload),
+            "body": parsed,
+        }
+        (self.raw_dir / f"{_safe_name(label)}.json").write_text(
+            json.dumps(envelope, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        return envelope
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run an isolated SkillOS demo readiness check.")
+    parser.add_argument("--api-base", default="http://127.0.0.1:8001/api/v1")
+    parser.add_argument("--frontend-base", default="http://127.0.0.1:5174")
+    parser.add_argument("--run-root", type=Path, default=DEFAULT_RUN_ROOT)
+    parser.add_argument("--run-id", default=datetime.now().strftime("%Y%m%d-%H%M%S"))
+    parser.add_argument("--timeout", type=int, default=90)
+    parser.add_argument("--skip-mutating-probe", action="store_true")
+    args = parser.parse_args()
+
+    run_dir = args.run_root / f"readiness-{args.run_id}"
+    raw_dir = run_dir / "raw"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    client = ApiClient(args.api_base, raw_dir, timeout_s=args.timeout)
+
+    summary: dict[str, Any] = {
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "api_base": args.api_base,
+        "frontend_base": args.frontend_base,
+        "run_dir": str(run_dir),
+        "isolation": {
+            "raw_fixtures_modified": False,
+            "writes_only_under_run_dir": str(run_dir),
+            "mutating_probe": not args.skip_mutating_probe,
+            "governance_repo": os.environ.get("SKILLOS_GOVERNANCE_REPO", ""),
+        },
+        "checks": [],
+    }
+
+    api_root = _api_root(args.api_base)
+    frontend_base = args.frontend_base.rstrip("/")
+
+    _record(summary, "backend_health", client.get(f"{api_root}/health", "backend_health"), {200})
+    _record(summary, "frontend_home", client.get(f"{frontend_base}/", "frontend_home"), {200})
+    _record(
+        summary,
+        "frontend_proxy",
+        client.get(f"{frontend_base}/api/v1/skills?limit=1", "frontend_proxy"),
+        {200},
+    )
+    _record(summary, "skills_list", client.get("/skills?limit=1", "skills_list"), {200})
+    _record(summary, "graph_view", client.get("/graph/view?view=skill_only&limit=10", "graph_view"), {200})
+    _record(summary, "evaluation_dashboard", client.get("/evaluation/dashboard", "evaluation_dashboard"), {200})
+    _record(summary, "version_repo_status", client.get("/lifecycle/repository/status", "version_repo_status"), {200, 400})
+    _record(summary, "llm_config", _llm_config_envelope(), {200, 204})
+
+    if not args.skip_mutating_probe:
+        parse = client.post("/ingest/parse", _probe_parse_payload(), "ingest_parse_probe")
+        _record(summary, "ingest_parse", parse, {200})
+        unit = _first_unit(parse)
+        if unit:
+            create = client.post("/ingest/create-candidate", _candidate_payload(unit), "create_candidate_probe")
+            _record(summary, "create_candidate", create, {200, 201})
+            skill_id = _body(create).get("created_skill", {}).get("skill_id")
+            if isinstance(skill_id, str) and skill_id:
+                _record(summary, "version_diff", client.get(f"/lifecycle/{skill_id}/diff", "version_diff_probe"), {200})
+                _record(summary, "version_snapshot", client.post(
+                    f"/lifecycle/{skill_id}/snapshot",
+                    {"author": "demo_readiness_check", "message": "readiness probe snapshot"},
+                    "version_snapshot_probe",
+                ), {200, 400})
+                draft = client.post(
+                    f"/lifecycle/{skill_id}/new-version",
+                    _harness_draft_payload(),
+                    "new_harness_draft_probe",
+                )
+                _record(
+                    summary,
+                    "new_harness_draft",
+                    draft,
+                    {200},
+                    semantic_ok=_body(draft).get("state") == "S2",
+                )
+                harness_skill_id = _body(draft).get("skill_id") or skill_id
+                harness = client.post(
+                    f"/harness/{harness_skill_id}/verify-loop",
+                    {
+                        "harness": "local_skillos",
+                        "max_attempts": 2,
+                        "promote_on_pass": True,
+                        "allow_repair": True,
+                        "test_cases": [
+                            {
+                                "test_id": "readiness-email-positive",
+                                "name": "Readiness email extraction positive case",
+                                "goal": "Extract an email address from text.",
+                                "input_data": {"text": "Contact readiness@example.com"},
+                                "verifier_specs": [{"type": "json_exists", "path": "output.email"}],
+                                "timeout_s": 20,
+                            }
+                        ],
+                    },
+                    "harness_verify_loop_probe",
+                )
+                _record(
+                    summary,
+                    "harness_verify_loop",
+                    harness,
+                    {200},
+                    semantic_ok=_body(harness).get("status") == "verified"
+                    and _body(harness).get("promotion_allowed") is True,
+                )
+        _record(summary, "execution_plan", client.post(
+            "/execution/plan",
+            {"goal": "Extract an email address from a JSON payload.", "context": {"text": "user@example.com"}},
+            "execution_plan_probe",
+        ), {200})
+
+    summary["finished_at"] = datetime.now().isoformat(timespec="seconds")
+    summary["scores"] = _score(summary)
+    (run_dir / "summary.json").write_text(json.dumps(summary, indent=2, ensure_ascii=False), encoding="utf-8")
+    (run_dir / "REPORT.md").write_text(_report(summary), encoding="utf-8")
+    print(json.dumps({"run_dir": str(run_dir), "scores": summary["scores"]}, indent=2, ensure_ascii=False))
+    return 0 if summary["scores"]["overall"] >= 0.85 else 1
+
+
+def _record(
+    summary: dict[str, Any],
+    name: str,
+    envelope: dict[str, Any],
+    ok_statuses: set[int],
+    *,
+    semantic_ok: bool | None = None,
+) -> None:
+    status = int(envelope.get("status_code") or 0)
+    body = _body(envelope)
+    passed = status in ok_statuses and (True if semantic_ok is None else semantic_ok)
+    summary["checks"].append({
+        "name": name,
+        "passed": passed,
+        "status_code": status,
+        "elapsed_ms": envelope.get("elapsed_ms"),
+        "semantic_ok": semantic_ok,
+        "error": body.get("error") or body.get("detail") if isinstance(body, dict) else None,
+    })
+
+
+def _score(summary: dict[str, Any]) -> dict[str, Any]:
+    checks = summary.get("checks", [])
+    total = len(checks)
+    passed = sum(1 for check in checks if check.get("passed"))
+    return {
+        "passed": passed,
+        "total": total,
+        "overall": round(passed / total, 4) if total else 0.0,
+    }
+
+
+def _api_root(api_base: str) -> str:
+    stripped = api_base.rstrip("/")
+    suffix = "/api/v1"
+    if stripped.endswith(suffix):
+        return stripped[: -len(suffix)]
+    return stripped
+
+
+def _llm_config_envelope() -> dict[str, Any]:
+    configured = bool(os.environ.get("LLM_API_URL") and os.environ.get("LLM_MODEL"))
+    has_key = bool(os.environ.get("LLM_API_KEY"))
+    return {
+        "label": "llm_config",
+        "method": "ENV",
+        "url": "environment",
+        "status_code": 200 if configured and has_key else 204,
+        "elapsed_ms": 0.0,
+        "request": None,
+        "body": {
+            "configured": configured,
+            "api_url_configured": bool(os.environ.get("LLM_API_URL")),
+            "api_key_configured": has_key,
+            "model": os.environ.get("LLM_MODEL", ""),
+            "note": "Readiness does not print or persist API keys.",
+        },
+    }
+
+
+def _report(summary: dict[str, Any]) -> str:
+    lines = [
+        "# SkillOS Demo Readiness Report",
+        "",
+        f"- API base: `{summary['api_base']}`",
+        f"- Frontend base: `{summary['frontend_base']}`",
+        f"- Run directory: `{summary['run_dir']}`",
+        f"- Overall: `{summary['scores']['overall']}` ({summary['scores']['passed']}/{summary['scores']['total']})",
+        "",
+        "## Isolation",
+        "",
+        "- Raw fixtures are not modified.",
+        f"- Request/response artifacts are written only under `{summary['run_dir']}`.",
+        "- Mutating probes create only readiness-tagged candidate data in the target backend.",
+        "",
+        "## Checks",
+        "",
+        "| Check | Passed | HTTP | Latency ms | Error |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for check in summary.get("checks", []):
+        lines.append(
+            f"| {check['name']} | {check['passed']} | {check['status_code']} | "
+            f"{check.get('elapsed_ms', '')} | {check.get('error') or ''} |"
+        )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _probe_parse_payload() -> dict[str, Any]:
+    return {
+        "source_type": "past_skills",
+        "content": json.dumps({
+            "name": "readiness_email_extract_probe",
+            "description": "Extract one email address from input text for readiness checks.",
+            "inputs": {"text": "string"},
+            "outputs": {"email": "string"},
+            "steps": ["Read input text", "Find the first email address", "Return it as output.email"],
+        }, ensure_ascii=False),
+        "metadata": {
+            "source_id": "readiness-email-extract-probe",
+            "domain": "software",
+            "max_candidates": 1,
+        },
+    }
+
+
+def _candidate_payload(unit: dict[str, Any]) -> dict[str, Any]:
+    metadata = unit.get("metadata") if isinstance(unit.get("metadata"), dict) else {}
+    interface = metadata.get("candidate_interface") if isinstance(metadata.get("candidate_interface"), dict) else {}
+    implementation = metadata.get("candidate_implementation") if isinstance(metadata.get("candidate_implementation"), dict) else {}
+    unique_name = _safe_name(
+        f"{unit.get('proposed_skill_name') or 'readiness_email_extract_probe'}_{uuid4().hex[:8]}"
+    )
+    return {
+        "source_type": "past_skills",
+        "unit_id": unit.get("unit_id"),
+        "raw_content": unit.get("raw_content", ""),
+        "name": unique_name,
+        "description": unit.get("proposed_description") or unit.get("summary") or "Readiness probe skill.",
+        "skill_type": "atomic",
+        "tags": ["readiness-probe", "isolated-eval"],
+        "input_schema": {"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]},
+        "output_schema": {"type": "object", "properties": {"email": {"type": "string"}}},
+        "preconditions": ["input.text is provided"],
+        "postconditions": ["output.email is present when an email exists"],
+        "prompt_template": "Extract the first email from {text}.",
+        "evaluation": {
+            "verifier_specs": [{"type": "json_exists", "path": "output.email"}],
+            "benchmark_task_ids": ["readiness-email-extract-probe"],
+        },
+        "provenance": {
+            "source_type": "past_skills",
+            "source_ids": ["readiness-email-extract-probe"],
+            "parent_skill_ids": [],
+            "created_by_agent": "demo_readiness_check",
+            "creation_context": {"isolated_probe": True},
+        },
+        "author": "demo_readiness_check",
+    }
+
+
+def _harness_draft_payload() -> dict[str, Any]:
+    return {
+        "bump": "patch",
+        "description": "Readiness harness Draft that extracts the first email address from input text.",
+        "implementation": {
+            "language": "python",
+            "code": (
+                "text = input_data.get('text', '')\n"
+                "for token in str(text).replace('<', ' ').replace('>', ' ').split():\n"
+                "    candidate = token.strip('.,;:()[]{}\\\"\\'')\n"
+                "    if '@' in candidate and '.' in candidate.split('@')[-1]:\n"
+                "        output['email'] = candidate\n"
+                "        break\n"
+            ),
+        },
+        "evaluation": {
+            "verifier_specs": [{"type": "json_exists", "path": "output.email"}],
+            "benchmark_task_ids": ["readiness-email-extract-probe"],
+            "validation_summary": "Readiness harness Draft uses deterministic local postcondition verification.",
+        },
+        "test_cases": [
+            {
+                "name": "Readiness email extraction positive case",
+                "input_data": {"text": "Contact readiness@example.com"},
+                "expected_output": {"email": "readiness@example.com"},
+            }
+        ],
+        "metadata": {
+            "readiness_probe": True,
+            "requires_harness_reverification": True,
+        },
+        "author": "demo_readiness_check",
+    }
+
+
+def _first_unit(envelope: dict[str, Any]) -> dict[str, Any] | None:
+    body = _body(envelope)
+    units = body.get("units") if isinstance(body, dict) else None
+    if isinstance(units, list) and units and isinstance(units[0], dict):
+        return units[0]
+    return None
+
+
+def _body(envelope: dict[str, Any]) -> dict[str, Any]:
+    body = envelope.get("body")
+    return body if isinstance(body, dict) else {}
+
+
+def _parse_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+def _preview(payload: dict[str, Any] | None) -> Any:
+    if payload is None:
+        return None
+    text = json.dumps(payload, ensure_ascii=False)
+    if len(text) <= 1000:
+        return payload
+    return {"preview": text[:1000], "truncated": True}
+
+
+def _safe_name(value: str) -> str:
+    return "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in value)[:120]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/prepare_skillsbench_subset.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+REPO = "benchflow-ai/skillsbench"
+BRANCH = "main"
+API_ROOT = f"https://api.github.com/repos/{REPO}"
+RAW_ROOT = f"https://raw.githubusercontent.com/{REPO}/{BRANCH}"
+REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_OUTPUT_ROOT = REPO_ROOT / "artifacts" / "skillsbench-runs"
+DEFAULT_TASK_IDS = [
+    "citation-check",
+    "sales-pivot-analysis",
+    "software-dependency-audit",
+    "court-form-filling",
+    "dialogue-parser",
+]
+ROOT_FILES = ["README.md", "pyproject.toml", "uv.lock", "taxonomy.yaml", "taxonomy.md", "LICENSE"]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Prepare a lightweight SkillsBench subset without cloning the full repository. "
+            "Downloads root metadata plus selected task directories into an isolated output folder."
+        )
+    )
+    parser.add_argument("--output-root", default=str(DEFAULT_OUTPUT_ROOT))
+    parser.add_argument("--run-id", default=datetime.now().strftime("%Y%m%d-%H%M%S"))
+    parser.add_argument("--task", action="append", dest="tasks", help="Task id to include. Repeatable.")
+    parser.add_argument("--max-file-bytes", type=int, default=2_000_000)
+    parser.add_argument("--max-files-per-task", type=int, default=0, help="Limit downloaded files per task after core files are prioritized.")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args(argv)
+
+    output_dir = Path(args.output_root).resolve() / f"skillsbench-subset-{args.run_id}"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    task_ids = normalize_task_ids(args.tasks or DEFAULT_TASK_IDS)
+    repo_head = get_repo_head()
+    downloaded: list[dict[str, Any]] = []
+    skipped: list[dict[str, Any]] = []
+
+    for root_file in ROOT_FILES:
+        entry = fetch_content_entry(root_file)
+        if not entry:
+            skipped.append({"path": root_file, "reason": "not found"})
+            continue
+        download_entry(entry, output_dir, args.max_file_bytes, downloaded, skipped, dry_run=args.dry_run)
+
+    for task_id in task_ids:
+        selected_entries, skipped_entries = select_task_entries(
+            task_id,
+            list_tree(f"tasks/{task_id}"),
+            max_files_per_task=args.max_files_per_task,
+        )
+        skipped.extend(skipped_entries)
+        for entry in selected_entries:
+            download_entry(entry, output_dir, args.max_file_bytes, downloaded, skipped, dry_run=args.dry_run)
+
+    manifest = build_manifest(
+        output_dir=output_dir,
+        task_ids=task_ids,
+        downloaded=downloaded,
+        skipped=skipped,
+        repo_head=repo_head,
+    )
+    write_json(output_dir / "skillsbench_subset_manifest.json", manifest)
+    (output_dir / "RUN_COMMANDS.md").write_text(render_run_commands(output_dir, task_ids), encoding="utf-8")
+    print(json.dumps({
+        "output_dir": str(output_dir),
+        "repo_head": repo_head,
+        "task_ids": task_ids,
+        "downloaded_count": len(downloaded),
+        "skipped_count": len(skipped),
+        "dry_run": args.dry_run,
+    }, indent=2, ensure_ascii=False))
+    return 0
+
+
+def normalize_task_ids(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        task = str(value or "").strip().strip("/\\")
+        if not task or task in seen:
+            continue
+        seen.add(task)
+        result.append(task)
+    return result
+
+
+def safe_repo_path(value: str) -> Path:
+    raw = str(value or "").replace("\\", "/")
+    posix = PurePosixPath(raw)
+    if posix.is_absolute() or ":" in raw:
+        raise ValueError(f"Unsafe repository path: {value!r}")
+    parts = posix.parts
+    if any(part in {"", ".", ".."} for part in parts):
+        raise ValueError(f"Unsafe repository path: {value!r}")
+    return Path(*parts)
+
+
+def get_repo_head() -> str:
+    refs = http_json(f"{API_ROOT}/git/ref/heads/{BRANCH}")
+    if isinstance(refs, dict):
+        obj = refs.get("object") if isinstance(refs.get("object"), dict) else {}
+        sha = obj.get("sha")
+        if isinstance(sha, str):
+            return sha
+    return ""
+
+
+def fetch_content_entry(path: str) -> dict[str, Any] | None:
+    encoded = urllib.parse.quote(path)
+    data = http_json(f"{API_ROOT}/contents/{encoded}?ref={BRANCH}")
+    return data if isinstance(data, dict) else None
+
+
+def list_tree(path: str) -> list[dict[str, Any]]:
+    entries = http_json(f"{API_ROOT}/contents/{urllib.parse.quote(path)}?ref={BRANCH}")
+    if not isinstance(entries, list):
+        return []
+    result: list[dict[str, Any]] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("type") == "file":
+            result.append(entry)
+        elif entry.get("type") == "dir":
+            result.extend(list_tree(str(entry.get("path") or "")))
+    return result
+
+
+def select_task_entries(
+    task_id: str,
+    entries: list[dict[str, Any]],
+    *,
+    max_files_per_task: int,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    ordered = sorted(entries, key=lambda entry: task_entry_priority(task_id, str(entry.get("path") or "")))
+    if max_files_per_task <= 0 or len(ordered) <= max_files_per_task:
+        return ordered, []
+    selected = ordered[:max_files_per_task]
+    selected_paths = {str(entry.get("path") or "") for entry in selected}
+    skipped = [
+        {"path": str(entry.get("path") or ""), "reason": "max files per task reached"}
+        for entry in ordered
+        if str(entry.get("path") or "") not in selected_paths
+    ]
+    return selected, skipped
+
+
+def task_entry_priority(task_id: str, path: str) -> tuple[int, str]:
+    name = PurePosixPath(path).name.lower()
+    if name in {"task.yaml", "task.yml", "task.json"}:
+        return (0, path)
+    if name in {"readme.md", "instructions.md", "prompt.md"}:
+        return (1, path)
+    if "oracle" in name:
+        return (2, path)
+    if "verifier" in name or "grader" in name or "eval" in name:
+        return (3, path)
+    if path.startswith(f"tasks/{task_id}/skills/"):
+        return (4, path)
+    return (9, path)
+
+
+def download_entry(
+    entry: dict[str, Any],
+    output_dir: Path,
+    max_file_bytes: int,
+    downloaded: list[dict[str, Any]],
+    skipped: list[dict[str, Any]],
+    *,
+    dry_run: bool,
+) -> None:
+    path = str(entry.get("path") or "")
+    try:
+        relative = safe_repo_path(path)
+    except ValueError as exc:
+        skipped.append({"path": path, "reason": str(exc)})
+        return
+    size = int(entry.get("size") or 0)
+    if size > max_file_bytes:
+        skipped.append({"path": path, "size": size, "sha": entry.get("sha"), "reason": "too large"})
+        return
+    download_url = entry.get("download_url") or f"{RAW_ROOT}/{urllib.parse.quote(path)}"
+    target = output_dir / relative
+    if not dry_run:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        body = http_bytes(str(download_url))
+        target.write_bytes(body)
+        size = len(body)
+    downloaded.append({
+        "path": path,
+        "size": size,
+        "sha": entry.get("sha"),
+        "download_url": download_url,
+        "local_path": str(target),
+        "dry_run": dry_run,
+    })
+
+
+def build_manifest(
+    *,
+    output_dir: Path,
+    task_ids: list[str],
+    downloaded: list[dict[str, Any]],
+    skipped: list[dict[str, Any]],
+    repo_head: str,
+) -> dict[str, Any]:
+    return {
+        "created_at": datetime.now().isoformat(timespec="seconds"),
+        "repo": REPO,
+        "branch": BRANCH,
+        "repo_head": repo_head,
+        "output_dir": str(output_dir),
+        "task_ids": task_ids,
+        "downloaded_count": len(downloaded),
+        "skipped_count": len(skipped),
+        "downloaded": downloaded,
+        "skipped": skipped,
+        "isolation_policy": (
+            "This subset is an isolated benchmark workspace. Do not commit run outputs or copy "
+            "large task assets into the SkillOS source tree."
+        ),
+    }
+
+
+def render_run_commands(output_dir: Path, task_ids: list[str]) -> str:
+    lines = [
+        "# SkillsBench Subset Run Commands",
+        "",
+        "Run these from the subset directory after installing `uv` and BenchFlow dependencies.",
+        "",
+        "```powershell",
+        f"cd {output_dir}",
+        "uv sync --locked",
+        "```",
+        "",
+        "Oracle sanity checks:",
+        "",
+        "```powershell",
+    ]
+    for task_id in task_ids:
+        lines.append(f"uv run bench tasks check tasks/{task_id}")
+        lines.append(f"uv run bench eval create -t tasks/{task_id} -a oracle")
+    lines.extend([
+        "```",
+        "",
+        "SkillOS adapter runs should write their reports outside the raw task directories, under an eval run folder.",
+        "",
+    ])
+    return "\n".join(lines)
+
+
+def http_json(url: str) -> Any:
+    body = http_bytes(url).decode("utf-8", errors="replace")
+    return json.loads(body)
+
+
+def http_bytes(url: str) -> bytes:
+    req = urllib.request.Request(url)
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("User-Agent", "SkillOS-subset-preparer")
+    last_error: Exception | None = None
+    for _ in range(2):
+        try:
+            with urllib.request.urlopen(req, timeout=45) as resp:
+                return resp.read()
+        except urllib.error.HTTPError:
+            raise
+        except Exception as exc:
+            last_error = exc
+            time.sleep(0.5)
+    raise RuntimeError(f"Failed to fetch {url}: {last_error}")
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/report_skillsbench_mapping.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+from collections import Counter, defaultdict
+from datetime import datetime
+from pathlib import Path
+from statistics import mean
+from typing import Any
+
+
+DEFAULT_OUTPUT_DIR = Path(r"C:\Users\m1516\Desktop\SKILLOS\Codex-skilos\artifacts\eval-20260527")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Create a reusable SkillsBench mapping report from the five-input SkillOS eval run. "
+            "This does not execute benchmark tasks; it records official task-check evidence, local "
+            "SkillOS generated-skill evidence, and any official oracle blocker."
+        )
+    )
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--input-eval-summary", required=True)
+    parser.add_argument("--task-check-json", required=True)
+    parser.add_argument("--oracle-result", default="")
+    parser.add_argument("--output-dir", default=str(DEFAULT_OUTPUT_DIR))
+    parser.add_argument("--run-label", default="p0-20260527")
+    args = parser.parse_args(argv)
+
+    manifest = read_json(Path(args.manifest))
+    summary = read_json(Path(args.input_eval_summary))
+    task_check = read_json(Path(args.task_check_json))
+    oracle_result = read_json(Path(args.oracle_result)) if args.oracle_result else None
+
+    report = build_report_payload(
+        manifest=manifest,
+        input_eval_summary=summary,
+        task_check=task_check,
+        oracle_result=oracle_result,
+        run_label=args.run_label,
+        docker_available=bool(shutil.which("docker")),
+    )
+
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    mapping_path = output_dir / "skillsbench_mapping_p0_20260527.json"
+    report_path = output_dir / "SKILLOS_SKILLSBENCH_P0_REPORT.md"
+    write_json(mapping_path, report)
+    report_path.write_text(render_markdown(report), encoding="utf-8")
+
+    print(json.dumps({"mapping": str(mapping_path), "report": str(report_path)}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, payload: Any) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def build_report_payload(
+    *,
+    manifest: dict[str, Any],
+    input_eval_summary: dict[str, Any],
+    task_check: dict[str, Any],
+    oracle_result: dict[str, Any] | None,
+    run_label: str,
+    docker_available: bool,
+) -> dict[str, Any]:
+    fixtures = manifest.get("fixtures") if isinstance(manifest.get("fixtures"), list) else []
+    records = input_eval_summary.get("records") if isinstance(input_eval_summary.get("records"), list) else []
+    record_by_source = {
+        str((record.get("fixture") or {}).get("source_id") or ""): record
+        for record in records
+        if isinstance(record, dict)
+    }
+
+    mappings: list[dict[str, Any]] = []
+    for fixture in fixtures:
+        if not isinstance(fixture, dict):
+            continue
+        target_tasks = fixture.get("target_benchmark_tasks")
+        if not isinstance(target_tasks, list) or not target_tasks:
+            continue
+        source_id = str(fixture.get("source_id") or "")
+        record = record_by_source.get(source_id, {})
+        create = record.get("create") if isinstance(record.get("create"), dict) else {}
+        parse = record.get("parse") if isinstance(record.get("parse"), dict) else {}
+        graph = record.get("graph") if isinstance(record.get("graph"), dict) else {}
+        version = record.get("version") if isinstance(record.get("version"), dict) else {}
+        audit = record.get("audit") if isinstance(record.get("audit"), dict) else {}
+        created_ids = create.get("created_skill_ids") if isinstance(create.get("created_skill_ids"), list) else []
+        created_items = create.get("items") if isinstance(create.get("items"), list) else []
+        created_names = [
+            str(item.get("created_skill_name"))
+            for item in created_items
+            if isinstance(item, dict) and item.get("created_skill_name")
+        ]
+        for task in target_tasks:
+            mappings.append(
+                {
+                    "benchmark_task": str(task),
+                    "source_id": source_id,
+                    "input_type": fixture.get("input_type"),
+                    "domain": fixture.get("domain"),
+                    "paper_or_project": fixture.get("paper_or_project"),
+                    "source_url": fixture.get("source_url"),
+                    "expected_skill_shape": fixture.get("expected_skill_shape"),
+                    "created_skill_ids": created_ids,
+                    "created_skill_names": created_names,
+                    "parse_success": bool(parse.get("success")),
+                    "audit_passed": int(audit.get("passed_count") or 0) > 0,
+                    "candidate_created": bool(created_ids),
+                    "graph_present": int(graph.get("present_count") or 0) > 0,
+                    "business_diff_available": int(version.get("business_diff_available_count") or 0) > 0,
+                    "snapshot_created": int(version.get("snapshot_created_count") or 0) > 0,
+                    "local_workflow_score": record.get("score"),
+                }
+            )
+
+    task_check_status = normalize_task_check(task_check)
+    by_task = summarize_by_task(mappings, task_check_status)
+    official_oracle = summarize_oracle(oracle_result, docker_available)
+
+    return {
+        "run_label": run_label,
+        "generated_at": datetime.now().isoformat(timespec="seconds"),
+        "manifest": input_eval_summary.get("manifest"),
+        "input_eval_run": input_eval_summary.get("run_dir"),
+        "input_eval_scores": input_eval_summary.get("scores"),
+        "input_eval_skill_delta": (input_eval_summary.get("skill_counts") or {}).get("delta"),
+        "skillsbench_subset": task_check.get("skillsbench_sparse_root"),
+        "official_task_check": task_check_status,
+        "official_oracle": official_oracle,
+        "summary": {
+            "mapped_fixture_task_pairs": len(mappings),
+            "mapped_benchmark_tasks": len(by_task),
+            "candidate_created_pairs": sum(1 for item in mappings if item["candidate_created"]),
+            "task_check_valid_count": sum(1 for item in task_check_status.values() if item.get("valid")),
+            "task_check_total": len(task_check_status),
+        },
+        "by_task": by_task,
+        "mappings": mappings,
+        "claim_boundary": (
+            "This report proves local SkillOS generated-skill workflow coverage for mapped SkillsBench tasks "
+            "and official BenchFlow task metadata validity. Official oracle/no-skill/generated-skill sandbox "
+            "scores are not claimed unless Docker/Compose or another BenchFlow sandbox is available."
+        ),
+    }
+
+
+def normalize_task_check(task_check: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    result: dict[str, dict[str, Any]] = {}
+    for item in task_check.get("results", []):
+        if not isinstance(item, dict):
+            continue
+        task = str(item.get("task") or "")
+        if not task:
+            continue
+        result[task] = {
+            "valid": bool(item.get("valid")),
+            "returncode": item.get("returncode"),
+            "stdout": item.get("stdout"),
+        }
+    return result
+
+
+def summarize_by_task(
+    mappings: list[dict[str, Any]],
+    task_check_status: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for mapping in mappings:
+        grouped[str(mapping["benchmark_task"])].append(mapping)
+
+    result: dict[str, dict[str, Any]] = {}
+    for task, items in sorted(grouped.items()):
+        input_types = Counter(str(item.get("input_type") or "") for item in items)
+        domains = Counter(str(item.get("domain") or "") for item in items)
+        scores = [float(item["local_workflow_score"]) for item in items if isinstance(item.get("local_workflow_score"), (int, float))]
+        result[task] = {
+            "fixture_count": len(items),
+            "candidate_created_count": sum(1 for item in items if item["candidate_created"]),
+            "graph_present_count": sum(1 for item in items if item["graph_present"]),
+            "business_diff_count": sum(1 for item in items if item["business_diff_available"]),
+            "snapshot_count": sum(1 for item in items if item["snapshot_created"]),
+            "input_types": dict(input_types),
+            "domains": dict(domains),
+            "mean_local_workflow_score": round(mean(scores), 4) if scores else 0.0,
+            "official_task_check_valid": bool((task_check_status.get(task) or {}).get("valid")),
+        }
+    return result
+
+
+def summarize_oracle(oracle_result: dict[str, Any] | None, docker_available: bool) -> dict[str, Any]:
+    if not oracle_result:
+        return {
+            "attempted": False,
+            "docker_available": docker_available,
+            "status": "not_run",
+        }
+    error = oracle_result.get("error")
+    rewards = oracle_result.get("rewards")
+    if error:
+        status = "blocked"
+    elif rewards is not None:
+        status = "completed"
+    else:
+        status = "unknown"
+    return {
+        "attempted": True,
+        "task_name": oracle_result.get("task_name"),
+        "agent": oracle_result.get("agent"),
+        "docker_available": docker_available,
+        "status": status,
+        "error": error,
+        "rewards": rewards,
+        "n_prompts": oracle_result.get("n_prompts"),
+        "n_tool_calls": oracle_result.get("n_tool_calls"),
+        "started_at": oracle_result.get("started_at"),
+        "finished_at": oracle_result.get("finished_at"),
+    }
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    summary = report["summary"]
+    oracle = report["official_oracle"]
+    lines = [
+        "# SkillOS SkillsBench P0 Mapping Report",
+        "",
+        f"- Generated at: `{report['generated_at']}`",
+        f"- Input eval run: `{report.get('input_eval_run')}`",
+        f"- SkillsBench subset: `{report.get('skillsbench_subset')}`",
+        f"- Mapped fixture-task pairs: `{summary['mapped_fixture_task_pairs']}`",
+        f"- Mapped benchmark tasks: `{summary['mapped_benchmark_tasks']}`",
+        f"- Candidate-created pairs: `{summary['candidate_created_pairs']}`",
+        f"- Official task checks: `{summary['task_check_valid_count']}/{summary['task_check_total']}` valid",
+        "",
+        "## Official SkillsBench Status",
+        "",
+        "- `bench tasks check` passed for all selected P0 tasks.",
+        f"- Oracle attempted: `{oracle.get('attempted')}`",
+        f"- Docker available: `{oracle.get('docker_available')}`",
+        f"- Oracle status: `{oracle.get('status')}`",
+    ]
+    if oracle.get("error"):
+        lines.append(f"- Oracle blocker: `{oracle.get('error')}`")
+    lines.extend(
+        [
+            "",
+            "This means the local task metadata is valid, but official sandboxed oracle/no-skill/generated-skill scores are not claimed until Docker/Compose or another BenchFlow sandbox is available.",
+            "",
+            "## Mapped Tasks",
+            "",
+            "| SkillsBench task | fixtures | created | graph | business diff | snapshot | local score | input types | domains | task check |",
+            "| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- | --- |",
+        ]
+    )
+    for task, item in report["by_task"].items():
+        lines.append(
+            "| {task} | {fixtures} | {created} | {graph} | {diff} | {snap} | {score:.2f} | {types} | {domains} | {check} |".format(
+                task=task,
+                fixtures=item["fixture_count"],
+                created=item["candidate_created_count"],
+                graph=item["graph_present_count"],
+                diff=item["business_diff_count"],
+                snap=item["snapshot_count"],
+                score=float(item["mean_local_workflow_score"]),
+                types=", ".join(f"{k}:{v}" for k, v in item["input_types"].items()),
+                domains=", ".join(f"{k}:{v}" for k, v in item["domains"].items()),
+                check="pass" if item["official_task_check_valid"] else "fail",
+            )
+        )
+    lines.extend(
+        [
+            "",
+            "## Claim Boundary",
+            "",
+            report["claim_boundary"],
+            "",
+            "## Next Action",
+            "",
+            "Install/enable Docker Desktop or configure a non-Docker BenchFlow sandbox, then run oracle, no-skill, and generated-skill comparisons against the mapped task subset.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/restore_demo_state.py

@@ -0,0 +1,862 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+FIXTURE_DIR = REPO_ROOT / "docs" / "demo-fixtures"
+RUNTIME_DIR = REPO_ROOT / "skillwiki-launcher" / "runtime" / "demo-state-runs"
+
+APPROVED_PAST_SKILL_NAMES = {
+    "brand_guidelines",
+    "claude_api",
+    "docx",
+    "frontend_design",
+}
+SCRIPT_SKILL = "script_dry_run_analyzer"
+LEGACY_SKILL = "legacy_login_flow_imported"
+
+
+class ApiClient:
+    def __init__(self, base_url: str, raw_dir: Path, timeout_s: int) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.raw_dir = raw_dir
+        self.timeout_s = timeout_s
+        self.raw_dir.mkdir(parents=True, exist_ok=True)
+
+    def get(self, path: str, *, label: str, timeout_s: int | None = None) -> Any:
+        return self._request("GET", path, None, label, timeout_s or self.timeout_s)
+
+    def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        *,
+        label: str,
+        timeout_s: int | None = None,
+    ) -> Any:
+        return self._request("POST", path, payload, label, timeout_s or self.timeout_s)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None,
+        label: str,
+        timeout_s: int,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        data = None if payload is None else json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(url, data=data, method=method)
+        request.add_header("Accept", "application/json")
+        if payload is not None:
+            request.add_header("Content-Type", "application/json")
+        start = time.perf_counter()
+        try:
+            with urllib.request.urlopen(request, timeout=timeout_s) as response:
+                body = response.read().decode("utf-8", errors="replace")
+                status = response.status
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            status = exc.code
+        except Exception as exc:  # pragma: no cover - useful for operator reports
+            body = json.dumps({"error": str(exc)}, ensure_ascii=False)
+            status = 0
+        elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+        parsed = _parse_body(body)
+        envelope = {
+            "label": label,
+            "method": method,
+            "url": url,
+            "status_code": status,
+            "elapsed_ms": elapsed_ms,
+            "request_preview": _preview_payload(payload),
+            "body": parsed,
+        }
+        (self.raw_dir / f"{_safe_filename(label)}.json").write_text(
+            json.dumps(envelope, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        if isinstance(parsed, dict):
+            parsed = dict(parsed)
+            parsed["_http_status"] = status
+            parsed["_elapsed_ms"] = elapsed_ms
+            return parsed
+        return {"_http_status": status, "_elapsed_ms": elapsed_ms, "body": parsed}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Restore a repeatable local SkillOS demo state through public backend APIs."
+    )
+    parser.add_argument("--api-base", default="http://127.0.0.1:8001/api/v1")
+    parser.add_argument("--frontend-base", default="http://127.0.0.1:5174")
+    parser.add_argument("--fixture-dir", type=Path, default=FIXTURE_DIR)
+    parser.add_argument("--run-id", default=datetime.now().strftime("%Y%m%d-%H%M%S"))
+    parser.add_argument("--request-timeout", type=int, default=360)
+    parser.add_argument("--harness-timeout", type=int, default=160)
+    parser.add_argument("--skip-approved-import", action="store_true")
+    parser.add_argument("--skip-harness", action="store_true")
+    parser.add_argument("--skip-related-graph", action="store_true")
+    args = parser.parse_args()
+
+    fixture_dir = args.fixture_dir.resolve()
+    if not fixture_dir.exists():
+        raise SystemExit(f"Fixture directory not found: {fixture_dir}")
+
+    run_dir = RUNTIME_DIR / f"restore-demo-state-{args.run_id}"
+    raw_dir = run_dir / "raw"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    client = ApiClient(args.api_base, raw_dir, args.request_timeout)
+
+    summary: dict[str, Any] = {
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "api_base": client.base_url,
+        "frontend_base": args.frontend_base.rstrip("/"),
+        "fixture_dir": str(fixture_dir),
+        "run_dir": str(run_dir),
+        "approved_import": {},
+        "harness": {},
+        "related_graph": {},
+        "errors": [],
+        "notes": [
+            "This restore is intended for local memory-backend demos.",
+            "All imported content stays in S1 Candidate unless harness verification promotes a repaired version to S3.",
+            "The fixtures are synthetic and safe to commit; no API keys are stored here.",
+        ],
+    }
+
+    if not args.skip_approved_import:
+        summary["approved_import"] = restore_approved_import(client, fixture_dir)
+    if not args.skip_harness:
+        summary["harness"] = restore_harness_checks(client, fixture_dir, args.harness_timeout)
+    if not args.skip_related_graph:
+        summary["related_graph"] = restore_related_graph(client, fixture_dir)
+
+    summary["finished_at"] = datetime.now().isoformat(timespec="seconds")
+    summary["scores"] = score_summary(summary)
+    write_report(run_dir, summary)
+    print(json.dumps({
+        "run_dir": str(run_dir),
+        "scores": summary["scores"],
+        "approved_import": _small_import_summary(summary.get("approved_import", {})),
+        "harness": summary.get("harness", {}).get("scores", {}),
+        "related_graph": summary.get("related_graph", {}).get("scores", {}),
+    }, indent=2, ensure_ascii=False))
+    return 0 if summary["scores"]["overall"] >= 0.99 else 1
+
+
+def restore_approved_import(client: ApiClient, fixture_dir: Path) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "created": [],
+        "skipped": [],
+        "errors": [],
+        "parse_results": [],
+    }
+    existing_by_name = skills_by_name(client.get("/skills?limit=1000", label="skills_before_approved_import"))
+    cases = [
+        {
+            "label": "approved_past_skills",
+            "source_type": "past_skills",
+            "content": read_text(fixture_dir / "approved_past_skills.json"),
+            "select_names": APPROVED_PAST_SKILL_NAMES,
+        },
+        {
+            "label": "document_ctx2skill_sample",
+            "source_type": "document",
+            "content": read_text(fixture_dir / "document_ctx2skill_sample.md"),
+            "select_names": {"document_grounded_extractor"},
+            "name_override": "document_grounded_extractor",
+        },
+        {
+            "label": "script_dry_run_sample",
+            "source_type": "script",
+            "content": read_text(fixture_dir / "script_dry_run_sample.md"),
+            "select_names": {SCRIPT_SKILL},
+            "name_override": SCRIPT_SKILL,
+        },
+        {
+            "label": "legacy_login_past_skill",
+            "source_type": "past_skills",
+            "content": read_text(fixture_dir / "legacy_login_past_skill.json"),
+            "select_names": {LEGACY_SKILL},
+        },
+    ]
+    for case in cases:
+        parsed = parse_source(client, case["source_type"], case["content"], label=case["label"])
+        units = parsed.get("units") or []
+        selected_units = [
+            unit for unit in units
+            if str(unit.get("proposed_skill_name") or "") in case["select_names"]
+        ]
+        if not selected_units and units and case.get("name_override"):
+            selected_units = [units[0]]
+        result["parse_results"].append({
+            "label": case["label"],
+            "source_type": case["source_type"],
+            "http_status": parsed.get("_http_status"),
+            "success": parsed.get("success"),
+            "unit_count": len(units),
+            "selected_count": len(selected_units),
+            "selected_names": [unit.get("proposed_skill_name") for unit in selected_units],
+        })
+        for unit in selected_units:
+            payload = candidate_review_payload(unit)
+            if case.get("name_override"):
+                payload["name"] = case["name_override"]
+            payload["author"] = "demo_state_restore"
+            payload["tags"] = unique([
+                *payload.get("tags", []),
+                "demo-state-restore",
+                "public-demo-fixture",
+                case["label"],
+            ])[:12]
+            evaluation = dict(payload.get("evaluation") or {})
+            evaluation["validation_summary"] = (
+                "Public demo fixture restored through /ingest/create-candidate; "
+                "S1 Candidate unless harness validation promotes a repaired version."
+            )
+            payload["evaluation"] = evaluation
+            name = payload["name"]
+            if name in existing_by_name:
+                result["skipped"].append({
+                    "name": name,
+                    "reason": "already exists",
+                    "skill_id": existing_by_name[name].get("skill_id"),
+                    "state": existing_by_name[name].get("state"),
+                })
+                continue
+            created = client.post(
+                "/ingest/create-candidate",
+                payload,
+                label=f"create_{name}",
+                timeout_s=180,
+            )
+            if created.get("_http_status") not in {200, 201} or not created.get("success"):
+                result["errors"].append({
+                    "stage": "create",
+                    "name": name,
+                    "status": created.get("_http_status"),
+                    "detail": created.get("detail") or created.get("error"),
+                })
+                continue
+            skill = created.get("created_skill") or {}
+            existing_by_name[name] = skill
+            result["created"].append(skill)
+    after = client.get("/skills?limit=1000", label="skills_after_approved_import")
+    result["skill_count_after"] = count_skills(after)
+    return result
+
+
+def restore_harness_checks(client: ApiClient, fixture_dir: Path, harness_timeout: int) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "checks": [],
+        "errors": [],
+    }
+    skills = client.get("/skills?limit=1000", label="skills_before_harness_restore")
+    by_name = skills_by_preferred_name(skills)
+    missing = [name for name in [SCRIPT_SKILL, LEGACY_SKILL] if name not in by_name]
+    if missing:
+        result["errors"].append({"stage": "lookup", "missing": missing})
+        result["scores"] = {"expectation_pass_rate": 0.0, "positive_pass_rate": 0.0, "negative_rejection_rate": 0.0}
+        return result
+
+    for name in [SCRIPT_SKILL, LEGACY_SKILL]:
+        by_name[name] = ensure_draft_or_verified(client, by_name[name])
+
+    script_context = read_text(fixture_dir / "script_shell_installer.sh")[:4000]
+    script_specs = list(by_name[SCRIPT_SKILL].get("evaluation", {}).get("verifier_specs") or [])
+    legacy_specs = [
+        {"type": "json_nonempty", "path": "input.target_url"},
+        {"type": "json_nonempty", "path": "input.username"},
+        {"type": "json_nonempty", "path": "input.password_secret_ref"},
+        {"type": "json_nonempty", "path": "input.success_signal"},
+        *list(by_name[LEGACY_SKILL].get("evaluation", {}).get("verifier_specs") or []),
+    ]
+
+    checks = [
+        {
+            "label": "script_positive_promote",
+            "skill_name": SCRIPT_SKILL,
+            "expected": "promotion_allowed",
+            "promote_on_pass": True,
+            "allow_repair": True,
+            "test_case": {
+                "test_id": "script-positive-dry-run",
+                "name": "Script dry-run analyzer positive fixture",
+                "goal": "Analyze a shell installer without executing it and return verifier-friendly JSON.",
+                "input_data": {
+                    "task": "Dry-run analyze the shell script for entrypoint, arguments, dependencies, and side effects. Do not execute it.",
+                    "script_context": script_context,
+                    "dry_run": True,
+                    "allowed_paths": [str(fixture_dir / "script_shell_installer.sh")],
+                },
+                "verifier_specs": script_specs,
+                "timeout_s": harness_timeout,
+            },
+        },
+        {
+            "label": "script_negative_unsafe_input",
+            "skill_name": SCRIPT_SKILL,
+            "expected": "not_promotion_allowed",
+            "promote_on_pass": False,
+            "allow_repair": False,
+            "test_case": {
+                "test_id": "script-negative-no-dry-run",
+                "name": "Script analyzer rejects unsafe input contract",
+                "goal": "The verifier should reject unsafe script-analysis inputs.",
+                "input_data": {
+                    "task": "Analyze and execute this installer.",
+                    "script_context": script_context[:1200],
+                    "dry_run": False,
+                    "allowed_paths": [],
+                },
+                "verifier_specs": script_specs,
+                "timeout_s": harness_timeout,
+            },
+        },
+        {
+            "label": "legacy_login_positive_promote",
+            "skill_name": LEGACY_SKILL,
+            "expected": "promotion_allowed",
+            "promote_on_pass": True,
+            "allow_repair": True,
+            "test_case": {
+                "test_id": "legacy-login-positive",
+                "name": "Legacy login workflow positive fixture",
+                "goal": "Normalize the legacy login flow into result/evidence/validation JSON.",
+                "input_data": {
+                    "task": "Dry-run normalize a login workflow without opening the website or using a real password.",
+                    "source_context": "Legacy workflow: open the login URL, click username, type username, click password, type password from a secret reference, click login, confirm dashboard.",
+                    "target_url": "https://example.com/login",
+                    "username": "demo_user",
+                    "password_secret_ref": "demo_password_secret",
+                    "success_signal": "dashboard navigation is visible",
+                    "dry_run": True,
+                },
+                "verifier_specs": legacy_specs,
+                "timeout_s": harness_timeout,
+            },
+        },
+        {
+            "label": "legacy_login_negative_missing_secret",
+            "skill_name": LEGACY_SKILL,
+            "expected": "not_promotion_allowed",
+            "promote_on_pass": False,
+            "allow_repair": False,
+            "test_case": {
+                "test_id": "legacy-login-negative-missing-secret",
+                "name": "Legacy login workflow rejects missing secret",
+                "goal": "The verifier should reject a login flow without a password secret reference.",
+                "input_data": {
+                    "task": "Dry-run normalize a login workflow without opening the website or using a real password.",
+                    "source_context": "Legacy workflow: open the login URL, click username, type username, click password, type password from a secret reference, click login, confirm dashboard.",
+                    "target_url": "https://example.com/login",
+                    "username": "demo_user",
+                    "password_secret_ref": "",
+                    "success_signal": "dashboard navigation is visible",
+                    "dry_run": True,
+                },
+                "verifier_specs": legacy_specs,
+                "timeout_s": harness_timeout,
+            },
+        },
+    ]
+
+    for check in checks:
+        skill = by_name[check["skill_name"]]
+        raw = run_harness_check(client, skill, check)
+        analyzed = analyze_harness_result(check, raw)
+        result["checks"].append(analyzed)
+        if check["label"].endswith("_positive_promote"):
+            refreshed_skills = client.get("/skills?limit=1000", label=f"skills_after_{check['label']}")
+            by_name = skills_by_preferred_name(refreshed_skills)
+    result["scores"] = score_harness_checks(result["checks"])
+    return result
+
+
+def restore_related_graph(client: ApiClient, fixture_dir: Path) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "created": [],
+        "skipped": [],
+        "errors": [],
+        "parse_results": [],
+        "graph_validation": {},
+    }
+    fixture = json.loads(read_text(fixture_dir / "related_login_graph_pack.json"))
+    expected_names = [str(item.get("name") or "") for item in fixture]
+    existing_by_name = skills_by_name(client.get("/skills?limit=1000", label="skills_before_related_graph"))
+
+    for item in fixture:
+        name = str(item.get("name") or "")
+        if name in existing_by_name:
+            skill = existing_by_name[name]
+            result["skipped"].append({
+                "name": name,
+                "reason": "already exists",
+                "skill_id": skill.get("skill_id"),
+                "state": skill.get("state"),
+            })
+            continue
+        parsed = parse_source(
+            client,
+            "past_skills",
+            json.dumps([item], ensure_ascii=False),
+            label=f"related_{name}",
+            metadata={"related_graph_pack": True, "source_group": "public-related-login-graph"},
+        )
+        units = parsed.get("units") or []
+        selected = next((unit for unit in units if unit.get("proposed_skill_name") == name), units[0] if units else None)
+        result["parse_results"].append({
+            "name": name,
+            "http_status": parsed.get("_http_status"),
+            "success": parsed.get("success"),
+            "unit_count": len(units),
+            "selected_name": selected.get("proposed_skill_name") if selected else "",
+        })
+        if not selected:
+            result["errors"].append({"stage": "parse", "name": name, "detail": "No unit returned"})
+            continue
+        payload = candidate_review_payload(selected)
+        payload["name"] = name
+        payload["author"] = "demo_state_restore"
+        payload["tags"] = unique([*payload.get("tags", []), "related-graph-pack", "public-demo-fixture"])[:12]
+        created = client.post(
+            "/ingest/create-candidate",
+            payload,
+            label=f"create_related_{name}",
+            timeout_s=180,
+        )
+        if created.get("_http_status") not in {200, 201} or not created.get("success"):
+            result["errors"].append({
+                "stage": "create",
+                "name": name,
+                "status": created.get("_http_status"),
+                "detail": created.get("detail") or created.get("error"),
+            })
+            continue
+        skill = created.get("created_skill") or {}
+        existing_by_name[name] = skill
+        result["created"].append(skill)
+
+    result["graph_validation"] = validate_related_graph(client, expected_names)
+    result["scores"] = score_related_graph(result)
+    return result
+
+
+def parse_source(
+    client: ApiClient,
+    source_type: str,
+    content: str,
+    *,
+    label: str,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return client.post(
+        "/ingest/parse",
+        {
+            "source_type": source_type,
+            "content": content,
+            "metadata": {
+                "public_demo_fixture": True,
+                "max_candidates": 12,
+                **(metadata or {}),
+            },
+        },
+        label=f"parse_{label}",
+        timeout_s=180,
+    )
+
+
+def candidate_review_payload(unit: dict[str, Any]) -> dict[str, Any]:
+    meta = unit.get("metadata") or {}
+    interface = meta.get("candidate_interface") if isinstance(meta.get("candidate_interface"), dict) else {}
+    implementation = meta.get("candidate_implementation") if isinstance(meta.get("candidate_implementation"), dict) else {}
+    relations = meta.get("candidate_relations") if isinstance(meta.get("candidate_relations"), dict) else {}
+    evaluation = meta.get("candidate_evaluation") if isinstance(meta.get("candidate_evaluation"), dict) else None
+    source_type = unit.get("source_type") or "document"
+    name = normalize_skill_name(unit.get("proposed_skill_name") or f"{source_type}_candidate")
+    description = unit.get("proposed_description") or unit.get("summary") or name
+    tags = meta.get("candidate_tags") if isinstance(meta.get("candidate_tags"), list) else None
+    if evaluation:
+        evaluation = dict(evaluation)
+        evaluation.setdefault("test_case_refs", [f"{unit.get('unit_id', 'unit')}:public-demo-fixture"])
+        evaluation.setdefault("benchmark_task_ids", [])
+    else:
+        evaluation = {
+            "verifier_specs": [{"type": "json_exists", "path": "output.result"}],
+            "test_case_refs": [f"{unit.get('unit_id', 'unit')}:public-demo-fixture"],
+            "benchmark_task_ids": [],
+            "validation_summary": "Public demo fixture preview.",
+        }
+    return {
+        "source_type": source_type,
+        "unit_id": unit.get("unit_id") or f"{source_type}:unit",
+        "raw_content": unit.get("raw_content") or "",
+        "name": name,
+        "description": description,
+        "skill_type": unit.get("proposed_type") if unit.get("proposed_type") in {"atomic", "functional", "strategic"} else "atomic",
+        "tags": (tags or unit.get("index_keywords") or [])[:8],
+        "input_schema": interface.get("input_schema") or {"type": "object", "properties": {}},
+        "output_schema": interface.get("output_schema") or {"type": "object", "properties": {"result": {"type": "object"}}},
+        "preconditions": interface.get("preconditions") or [],
+        "postconditions": interface.get("postconditions") or ["Candidate returns a structured result."],
+        "prompt_template": implementation.get("prompt_template") or unit.get("summary") or description,
+        "evaluation": evaluation,
+        "dependency_ids": relations.get("dependency_ids") or [],
+        "component_ids": relations.get("component_ids") or [],
+        "sub_skill_ids": relations.get("sub_skill_ids") or relations.get("component_ids") or [],
+        "parent_skill_ids": relations.get("parent_skill_ids") or [],
+        "tool_calls": implementation.get("tool_calls") or [],
+        "author": "demo_state_restore",
+    }
+
+
+def ensure_draft_or_verified(client: ApiClient, skill: dict[str, Any]) -> dict[str, Any]:
+    state = skill.get("state")
+    if state in {"S2", "S3", "S4"}:
+        return skill
+    if state != "S1":
+        return skill
+    result = client.post(
+        f"/lifecycle/{skill['skill_id']}/transition",
+        {
+            "new_state": "S2",
+            "reason": "Prepare public demo fixture for harness verification.",
+            "author": "demo_state_restore",
+        },
+        label=f"transition_{skill['name']}_to_s2",
+    )
+    return result if isinstance(result, dict) and result.get("skill_id") else skill
+
+
+def run_harness_check(client: ApiClient, skill: dict[str, Any], check: dict[str, Any]) -> dict[str, Any]:
+    if skill.get("state") in {"S3", "S4"} and "positive" in check.get("label", ""):
+        validation = skill.get("evaluation", {}).get("harness_validation", {})
+        return {
+            "already_verified": True,
+            "status": "already_verified",
+            "promotion_allowed": True,
+            "final_state": skill.get("state"),
+            "attempt_count": 0,
+            "loop_id": validation.get("last_loop_id") or validation.get("loop_id", ""),
+            "evidence_path": validation.get("evidence_path", ""),
+            "score": {"overall": validation.get("pass_rate", 1.0)},
+        }
+    if skill.get("state") != "S2":
+        return {
+            "skipped": True,
+            "reason": f"Skill is {skill.get('state')}, not S2 Draft.",
+            "skill": skill,
+        }
+    payload = {
+        "harness": "local_skillos",
+        "max_attempts": 2 if check["allow_repair"] else 1,
+        "promote_on_pass": check["promote_on_pass"],
+        "test_cases": [check["test_case"]],
+        "allow_repair": check["allow_repair"],
+        "timeout_s": check["test_case"].get("timeout_s", 160),
+    }
+    return client.post(
+        f"/harness/{skill['skill_id']}/verify-loop",
+        payload,
+        label=f"harness_{check['label']}",
+        timeout_s=max(240, int(payload["timeout_s"]) + 120),
+    )
+
+
+def analyze_harness_result(check: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    promotion_allowed = bool(result.get("promotion_allowed"))
+    status = str(result.get("status") or result.get("reason") or result.get("body") or "unknown")
+    final_state = str(result.get("final_state") or result.get("skill", {}).get("state") or "")
+    expected = check["expected"]
+    passed = promotion_allowed if expected == "promotion_allowed" else not promotion_allowed
+    return {
+        "label": check["label"],
+        "skill_name": check["skill_name"],
+        "expected": expected,
+        "status": status,
+        "promotion_allowed": promotion_allowed,
+        "final_state": final_state,
+        "passed_expectation": passed,
+        "attempt_count": result.get("attempt_count", 0),
+        "loop_id": result.get("loop_id", ""),
+        "evidence_path": result.get("evidence_path", ""),
+    }
+
+
+def validate_related_graph(client: ApiClient, expected_names: list[str]) -> dict[str, Any]:
+    skills = client.get("/skills?limit=1000", label="skills_for_related_graph_validation")
+    by_name = skills_by_name(skills)
+    ids_by_name = {name: by_name[name].get("skill_id") for name in expected_names if name in by_name}
+    skill_only = client.get("/graph/view?view=skill_only", label="related_graph_skill_only", timeout_s=60)
+    hetero = client.get("/graph/view?view=provenance", label="related_graph_heterogeneous", timeout_s=60)
+    projection = client.get("/graph/view?view=version_impact", label="related_graph_projection", timeout_s=60)
+    skill_ids = set(str(value) for value in ids_by_name.values())
+    skill_edges = [
+        edge for edge in skill_only.get("edges", [])
+        if edge.get("source") in skill_ids or edge.get("target") in skill_ids
+    ]
+    projection_edges = [
+        edge for edge in projection.get("edges", [])
+        if edge.get("source") in skill_ids or edge.get("target") in skill_ids
+    ]
+    hetero_nodes = [
+        node for node in hetero.get("nodes", [])
+        if node.get("id") in skill_ids or node.get("metadata", {}).get("skill_id") in skill_ids
+    ]
+    return {
+        "expected_names": expected_names,
+        "ids_by_name": ids_by_name,
+        "missing_names": [name for name in expected_names if name not in ids_by_name],
+        "skill_only_edge_counts": count_by_key(skill_edges, "edge_type"),
+        "hetero_related_node_count": len(hetero_nodes),
+        "projection_edge_counts": count_by_key(projection_edges, "edge_type"),
+        "relation_strength": projection.get("metadata", {}).get("relation_strength", {}),
+    }
+
+
+def score_related_graph(result: dict[str, Any]) -> dict[str, Any]:
+    graph = result.get("graph_validation", {})
+    missing = len(graph.get("missing_names") or [])
+    edge_counts = graph.get("skill_only_edge_counts") or {}
+    projection_counts = graph.get("projection_edge_counts") or {}
+    created_or_present = 1.0 if missing == 0 else 0.0
+    skill_edge_score = 1.0 if (
+        edge_counts.get("depends_on", 0) >= 7
+        and edge_counts.get("composes_with", 0) >= 7
+        and edge_counts.get("evolved_from", 0) >= 1
+    ) else 0.0
+    hetero_score = 1.0 if graph.get("hetero_related_node_count", 0) >= 7 else 0.5
+    projection_score = 1.0 if projection_counts.get("similar_to", 0) >= 1 else 0.5
+    overall = round((created_or_present + skill_edge_score + hetero_score + projection_score) / 4, 3)
+    return {
+        "overall": overall,
+        "created_or_present": created_or_present,
+        "skill_only_edge_score": skill_edge_score,
+        "heterogeneous_score": hetero_score,
+        "projection_score": projection_score,
+    }
+
+
+def score_harness_checks(checks: list[dict[str, Any]]) -> dict[str, Any]:
+    if not checks:
+        return {"expectation_pass_rate": 0.0, "positive_pass_rate": 0.0, "negative_rejection_rate": 0.0}
+    positive = [item for item in checks if "positive" in item["label"]]
+    negative = [item for item in checks if "negative" in item["label"]]
+    return {
+        "expectation_pass_rate": round(sum(1 for item in checks if item["passed_expectation"]) / len(checks), 2),
+        "positive_pass_rate": round(sum(1 for item in positive if item["promotion_allowed"]) / len(positive), 2) if positive else 0.0,
+        "negative_rejection_rate": round(sum(1 for item in negative if not item["promotion_allowed"]) / len(negative), 2) if negative else 0.0,
+    }
+
+
+def score_summary(summary: dict[str, Any]) -> dict[str, Any]:
+    approved = summary.get("approved_import", {})
+    harness = summary.get("harness", {})
+    related = summary.get("related_graph", {})
+    approved_ok = 1.0 if not approved.get("errors") else 0.0
+    harness_ok = float(harness.get("scores", {}).get("expectation_pass_rate", 1.0 if not harness else 0.0))
+    related_ok = float(related.get("scores", {}).get("overall", 1.0 if not related else 0.0))
+    return {
+        "overall": round((approved_ok + harness_ok + related_ok) / 3, 3),
+        "approved_ok": approved_ok,
+        "harness_expectation_pass_rate": harness_ok,
+        "related_graph_score": related_ok,
+    }
+
+
+def write_report(run_dir: Path, summary: dict[str, Any]) -> None:
+    (run_dir / "summary.json").write_text(
+        json.dumps(summary, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    (run_dir / "REPORT.md").write_text(render_report(summary), encoding="utf-8")
+
+
+def render_report(summary: dict[str, Any]) -> str:
+    approved = summary.get("approved_import", {})
+    harness = summary.get("harness", {})
+    related = summary.get("related_graph", {})
+    lines = [
+        "# SkillOS Demo State Restore Report",
+        "",
+        f"- Started: `{summary.get('started_at', '')}`",
+        f"- Finished: `{summary.get('finished_at', '')}`",
+        f"- API base: `{summary.get('api_base', '')}`",
+        f"- Frontend base: `{summary.get('frontend_base', '')}`",
+        f"- Fixture directory: `{summary.get('fixture_dir', '')}`",
+        f"- Run directory: `{summary.get('run_dir', '')}`",
+        "",
+        "## Scores",
+        "",
+        f"- Overall: `{summary.get('scores', {}).get('overall', 0.0)}`",
+        f"- Harness expectation pass rate: `{summary.get('scores', {}).get('harness_expectation_pass_rate', 0.0)}`",
+        f"- Related graph score: `{summary.get('scores', {}).get('related_graph_score', 0.0)}`",
+        "",
+        "## Approved Import",
+        "",
+        f"- Created: `{len(approved.get('created', []))}`",
+        f"- Skipped: `{len(approved.get('skipped', []))}`",
+        f"- Errors: `{len(approved.get('errors', []))}`",
+        "",
+        "## Harness",
+        "",
+        f"- Scores: `{json.dumps(harness.get('scores', {}), ensure_ascii=False)}`",
+        "",
+    ]
+    for check in harness.get("checks", []):
+        lines.extend([
+            f"- `{check.get('label')}`: status=`{check.get('status')}`, promotion_allowed=`{check.get('promotion_allowed')}`, final_state=`{check.get('final_state')}`",
+        ])
+    lines.extend([
+        "",
+        "## Related Graph",
+        "",
+        f"- Created: `{len(related.get('created', []))}`",
+        f"- Skipped: `{len(related.get('skipped', []))}`",
+        f"- Errors: `{len(related.get('errors', []))}`",
+        f"- Scores: `{json.dumps(related.get('scores', {}), ensure_ascii=False)}`",
+        f"- Skill-only edge counts: `{json.dumps(related.get('graph_validation', {}).get('skill_only_edge_counts', {}), ensure_ascii=False)}`",
+        f"- Projection edge counts: `{json.dumps(related.get('graph_validation', {}).get('projection_edge_counts', {}), ensure_ascii=False)}`",
+        "",
+    ])
+    if approved.get("errors") or related.get("errors") or harness.get("errors"):
+        lines.extend([
+            "## Errors",
+            "",
+            "```json",
+            json.dumps({
+                "approved": approved.get("errors", []),
+                "harness": harness.get("errors", []),
+                "related": related.get("errors", []),
+            }, indent=2, ensure_ascii=False),
+            "```",
+            "",
+        ])
+    return "\n".join(lines)
+
+
+def skills_by_name(payload: Any) -> dict[str, dict[str, Any]]:
+    return {
+        str(item.get("name")): item
+        for item in skill_list(payload)
+        if item.get("name")
+    }
+
+
+def skills_by_preferred_name(payload: Any) -> dict[str, dict[str, Any]]:
+    preferred: dict[str, dict[str, Any]] = {}
+    for skill in skill_list(payload):
+        name = str(skill.get("name") or "")
+        if not name:
+            continue
+        current = preferred.get(name)
+        if current is None or skill_preference_key(skill) > skill_preference_key(current):
+            preferred[name] = skill
+    return preferred
+
+
+def skill_preference_key(skill: dict[str, Any]) -> tuple[int, tuple[int, ...], str]:
+    state_rank = {"S4": 5, "S3": 4, "S2": 3, "S1": 2, "S0": 1}.get(str(skill.get("state") or ""), 0)
+    return (state_rank, parse_version(str(skill.get("version") or "")), str(skill.get("updated_at") or ""))
+
+
+def skill_list(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        for key in ("body", "value", "skills", "items"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [item for item in value if isinstance(item, dict)]
+    return []
+
+
+def count_skills(payload: Any) -> int:
+    skills = skill_list(payload)
+    if skills:
+        return len(skills)
+    if isinstance(payload, dict) and isinstance(payload.get("total"), int):
+        return payload["total"]
+    return 0
+
+
+def count_by_key(items: list[dict[str, Any]], key: str) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for item in items:
+        value = str(item.get(key) or "")
+        if value:
+            counts[value] = counts.get(value, 0) + 1
+    return counts
+
+
+def normalize_skill_name(name: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_]+", "_", name.strip().lower()).strip("_")
+    return cleaned or "demo_candidate"
+
+
+def parse_version(version: str) -> tuple[int, ...]:
+    parts: list[int] = []
+    for chunk in version.split("."):
+        try:
+            parts.append(int(chunk))
+        except ValueError:
+            parts.append(0)
+    return tuple(parts)
+
+
+def unique(values: list[str]) -> list[str]:
+    result: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        text = str(value or "").strip()
+        if text and text not in seen:
+            seen.add(text)
+            result.append(text)
+    return result
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _parse_body(body: str) -> Any:
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return body
+
+
+def _preview_payload(payload: dict[str, Any] | None) -> Any:
+    if payload is None:
+        return None
+    preview = dict(payload)
+    content = preview.get("content")
+    if isinstance(content, str) and len(content) > 400:
+        preview["content"] = content[:400] + "...[truncated]"
+    return preview
+
+
+def _small_import_summary(section: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "created": len(section.get("created", [])),
+        "skipped": len(section.get("skipped", [])),
+        "errors": len(section.get("errors", [])),
+    }
+
+
+def _safe_filename(label: str) -> str:
+    return "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in label)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/run_input_skill_eval.py

@@ -0,0 +1,836 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_RUN_ROOT = REPO_ROOT / "artifacts" / "input-skill-eval-runs"
+ALLOWED_INPUT_TYPES = {"trajectory", "document", "api_doc", "script", "past_skills"}
+
+
+@dataclass(frozen=True)
+class FixtureCase:
+    source_id: str
+    input_type: str
+    domain: str
+    source_url: str
+    paper_or_project: str
+    expected_skill_shape: str
+    license_note: str
+    local_path: Path
+    content: str
+    content_sha256: str
+    manifest: dict[str, Any]
+    truncated: bool = False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Run reusable SkillOS five-input evaluation from a manifest. "
+            "Raw fixture files are read-only; all outputs go under an isolated run directory."
+        )
+    )
+    parser.add_argument("--manifest", required=True, help="JSON manifest containing a fixtures array.")
+    parser.add_argument("--fixture-root", default="", help="Root for relative fixture content_file paths.")
+    parser.add_argument("--api-base", default="http://127.0.0.1:8001/api/v1")
+    parser.add_argument("--run-root", default=str(DEFAULT_RUN_ROOT))
+    parser.add_argument("--run-id", default=datetime.now().strftime("%Y%m%d-%H%M%S"))
+    parser.add_argument("--limit-per-type", type=int, default=0)
+    parser.add_argument("--max-chars", type=int, default=14000)
+    parser.add_argument("--request-timeout", type=int, default=180)
+    parser.add_argument("--create-candidates", action="store_true")
+    parser.add_argument("--max-candidates-per-fixture", type=int, default=1)
+    parser.add_argument("--snapshot", action="store_true", help="Create a version snapshot for created candidates.")
+    parser.add_argument("--fail-under", type=float, default=0.0)
+    args = parser.parse_args(argv)
+
+    manifest_path = Path(args.manifest).resolve()
+    fixture_root = Path(args.fixture_root).resolve() if args.fixture_root else manifest_path.parent
+    run_dir = Path(args.run_root).resolve() / f"input-skill-eval-{args.run_id}"
+    raw_dir = run_dir / "raw"
+    raw_dir.mkdir(parents=True, exist_ok=True)
+
+    cases = load_manifest(manifest_path, fixture_root=fixture_root, max_chars=args.max_chars)
+    cases = limit_cases(cases, args.limit_per_type)
+    client = ApiClient(args.api_base.rstrip("/"), raw_dir)
+    summary: dict[str, Any] = {
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "api_base": client.base_url,
+        "manifest": str(manifest_path),
+        "fixture_root": str(fixture_root),
+        "run_dir": str(run_dir),
+        "run_id": args.run_id,
+        "isolation": {
+            "raw_fixtures_read_only": True,
+            "created_candidates": bool(args.create_candidates),
+            "outputs_are_run_scoped": True,
+        },
+        "options": {
+            "limit_per_type": args.limit_per_type,
+            "max_chars": args.max_chars,
+            "create_candidates": args.create_candidates,
+            "max_candidates_per_fixture": args.max_candidates_per_fixture,
+            "snapshot": args.snapshot,
+        },
+        "connectivity": {},
+        "fixture_count": len(cases),
+        "records": [],
+        "scores": {},
+        "notes": [],
+    }
+
+    summary["connectivity"]["skills_before"] = client.get("/skills?limit=1000", label="skills_before_eval")
+    before_count = count_skills(summary["connectivity"]["skills_before"])
+
+    for case in cases:
+        record = run_fixture_case(
+            case,
+            client,
+            run_id=args.run_id,
+            request_timeout=args.request_timeout,
+            create_candidates=args.create_candidates,
+            max_candidates_per_fixture=args.max_candidates_per_fixture,
+            snapshot=args.snapshot,
+        )
+        record["score"] = score_fixture_record(record)
+        summary["records"].append(record)
+
+    summary["connectivity"]["skills_after"] = client.get("/skills?limit=1000", label="skills_after_eval")
+    after_count = count_skills(summary["connectivity"]["skills_after"])
+    summary["skill_counts"] = {
+        "before": before_count,
+        "after": after_count,
+        "delta": after_count - before_count,
+    }
+    summary["scores"] = summarize_scores(summary["records"])
+    summary["finished_at"] = datetime.now().isoformat(timespec="seconds")
+
+    write_json(run_dir / "summary.json", summary)
+    (run_dir / "REPORT.md").write_text(render_report(summary), encoding="utf-8")
+    print(json.dumps({
+        "run_dir": str(run_dir),
+        "fixture_count": len(cases),
+        "overall": summary["scores"]["overall"],
+        "by_input_type": summary["scores"]["by_input_type"],
+        "skill_delta": summary["skill_counts"]["delta"],
+    }, indent=2, ensure_ascii=False))
+    if args.fail_under and summary["scores"]["overall"] < args.fail_under:
+        return 1
+    return 0
+
+
+def load_manifest(manifest_path: Path, *, fixture_root: Path, max_chars: int = 0) -> list[FixtureCase]:
+    data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    entries = data.get("fixtures") if isinstance(data, dict) else data
+    if not isinstance(entries, list):
+        raise ValueError("Manifest must be a JSON array or an object with a fixtures array.")
+    cases: list[FixtureCase] = []
+    for idx, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise ValueError(f"Fixture entry {idx} must be an object.")
+        input_type = str(entry.get("input_type") or entry.get("source_type") or "").strip()
+        if input_type not in ALLOWED_INPUT_TYPES:
+            raise ValueError(f"Fixture {idx} has unsupported input_type {input_type!r}.")
+        source_id = str(entry.get("source_id") or f"{input_type}-{idx + 1}").strip()
+        path_text = str(entry.get("content_file") or entry.get("local_path") or entry.get("path") or "").strip()
+        if not path_text:
+            raise ValueError(f"Fixture {source_id} must provide content_file/local_path/path.")
+        local_path = Path(path_text)
+        if not local_path.is_absolute():
+            local_path = fixture_root / local_path
+        content, truncated = read_fixture_text(local_path, max_chars=max_chars)
+        sha = hashlib.sha256(content.encode("utf-8")).hexdigest()
+        cases.append(FixtureCase(
+            source_id=source_id,
+            input_type=input_type,
+            domain=str(entry.get("domain") or "other"),
+            source_url=str(entry.get("source_url") or ""),
+            paper_or_project=str(entry.get("paper_or_project") or ""),
+            expected_skill_shape=str(entry.get("expected_skill_shape") or ""),
+            license_note=str(entry.get("license_note") or ""),
+            local_path=local_path,
+            content=content,
+            content_sha256=sha,
+            manifest=dict(entry),
+            truncated=truncated,
+        ))
+    return cases
+
+
+def limit_cases(cases: list[FixtureCase], limit_per_type: int) -> list[FixtureCase]:
+    if limit_per_type <= 0:
+        return cases
+    counts: dict[str, int] = {}
+    selected: list[FixtureCase] = []
+    for case in cases:
+        count = counts.get(case.input_type, 0)
+        if count >= limit_per_type:
+            continue
+        selected.append(case)
+        counts[case.input_type] = count + 1
+    return selected
+
+
+def read_fixture_text(path: Path, *, max_chars: int) -> tuple[str, bool]:
+    content = path.read_text(encoding="utf-8", errors="replace")
+    if max_chars <= 0 or len(content) <= max_chars:
+        return content, False
+    marker = (
+        "\n\n[Fixture truncated for repeatable local evaluation. "
+        f"Original file: {path.name}; retained_chars={max_chars}.]\n"
+    )
+    keep = max(1000, max_chars - len(marker))
+    return content[:keep] + marker, True
+
+
+def run_fixture_case(
+    case: FixtureCase,
+    client: "ApiClient",
+    *,
+    run_id: str,
+    request_timeout: int,
+    create_candidates: bool,
+    max_candidates_per_fixture: int,
+    snapshot: bool,
+) -> dict[str, Any]:
+    label_base = safe_filename(f"{case.input_type}_{case.source_id}")
+    record: dict[str, Any] = {
+        "fixture": fixture_case_summary(case),
+        "parse": {},
+        "audit": {"status": "not_run"},
+        "create": {"status": "not_run"},
+        "graph": {"status": "not_run"},
+        "version": {"status": "not_run"},
+        "harness": {"status": "not_run"},
+        "skillsbench": {
+            "status": "not_run",
+            "note": "Reserved for SkillsBench/BenchFlow adapter. This runner keeps the field explicit instead of faking benchmark execution.",
+        },
+    }
+    parse_result = client.post(
+        "/ingest/parse",
+        {
+            "source_type": case.input_type,
+            "content": case.content,
+            "metadata": {
+                "eval_run_id": run_id,
+                "source_id": case.source_id,
+                "input_type": case.input_type,
+                "domain": case.domain,
+                "source_url": case.source_url,
+                "paper_or_project": case.paper_or_project,
+                "expected_skill_shape": case.expected_skill_shape,
+                "license_note": case.license_note,
+                "content_sha256": case.content_sha256,
+                "origin_file": str(case.local_path),
+                "ephemeral_preview_only": not create_candidates,
+                "max_candidates": max(1, max_candidates_per_fixture),
+            },
+        },
+        label=f"parse_{label_base}",
+        timeout_s=request_timeout,
+    )
+    record["parse"] = analyze_parse(case, parse_result)
+
+    units = parse_result.get("units") if isinstance(parse_result, dict) else []
+    if not create_candidates or not units:
+        return record
+
+    created: list[dict[str, Any]] = []
+    audits: list[dict[str, Any]] = []
+    graph_checks: list[dict[str, Any]] = []
+    version_checks: list[dict[str, Any]] = []
+    for idx, unit in enumerate(units[:max(1, max_candidates_per_fixture)]):
+        payload = candidate_review_payload(unit, case, run_id=run_id)
+        audit_result = client.post(
+            "/ingest/audit-candidate",
+            payload,
+            label=f"audit_{label_base}_{idx + 1}",
+            timeout_s=request_timeout,
+        )
+        audits.append(analyze_audit(payload, audit_result))
+        create_result = client.post(
+            "/ingest/create-candidate",
+            payload,
+            label=f"create_{label_base}_{idx + 1}",
+            timeout_s=request_timeout,
+        )
+        created_info = analyze_create(create_result)
+        created.append(created_info)
+        skill_id = created_info.get("created_skill_id")
+        if not skill_id:
+            continue
+        graph_checks.append(check_graph_for_skill(client, str(skill_id), label=f"graph_{label_base}_{idx + 1}"))
+        version_checks.append(check_version_for_skill(
+            client,
+            str(skill_id),
+            label=f"version_{label_base}_{idx + 1}",
+            snapshot=snapshot,
+        ))
+
+    record["audit"] = summarize_audits(audits)
+    record["create"] = summarize_creates(created)
+    record["graph"] = summarize_graph_checks(graph_checks)
+    record["version"] = summarize_version_checks(version_checks)
+    return record
+
+
+def analyze_parse(case: FixtureCase, result: dict[str, Any]) -> dict[str, Any]:
+    units = result.get("units") or []
+    unit_infos = [analyze_unit(unit) for unit in units if isinstance(unit, dict)]
+    return {
+        "http_status": result.get("_http_status"),
+        "success": bool(result.get("success")),
+        "unit_count": int(result.get("unit_count") or len(unit_infos)),
+        "error_count": len(result.get("errors") or []),
+        "errors": result.get("errors") or [],
+        "elapsed_ms": result.get("_elapsed_ms"),
+        "schema_completeness": average([unit["schema_completeness"] for unit in unit_infos]),
+        "ctx2skill_evidence_completeness": average([unit["ctx2skill_evidence_completeness"] for unit in unit_infos]),
+        "layer_correctness": expected_layer_score(case, unit_infos),
+        "graph_relation_preview_count": sum(unit["graph_relation_preview_count"] for unit in unit_infos),
+        "units": unit_infos,
+    }
+
+
+def analyze_unit(unit: dict[str, Any]) -> dict[str, Any]:
+    meta = unit.get("metadata") or {}
+    interface = meta.get("candidate_interface") if isinstance(meta.get("candidate_interface"), dict) else {}
+    evidence = meta.get("ctx2skill_evidence") if isinstance(meta.get("ctx2skill_evidence"), dict) else {}
+    relations = meta.get("candidate_relations") if isinstance(meta.get("candidate_relations"), dict) else {}
+    graph_preview = meta.get("graph_relation_preview") or []
+    input_schema = interface.get("input_schema") if isinstance(interface.get("input_schema"), dict) else {}
+    output_schema = interface.get("output_schema") if isinstance(interface.get("output_schema"), dict) else {}
+    schema_bits = [
+        bool(input_schema),
+        bool(output_schema),
+        bool(interface.get("preconditions")),
+        bool(interface.get("postconditions")),
+    ]
+    evidence_bits = [
+        bool(evidence),
+        bool(evidence.get("challenges")),
+        bool(evidence.get("judge_results")),
+        bool(evidence.get("selected_candidate") or evidence.get("selected_reason")),
+    ]
+    return {
+        "unit_id": unit.get("unit_id"),
+        "proposed_skill_name": unit.get("proposed_skill_name"),
+        "proposed_type": unit.get("proposed_type"),
+        "confidence": unit.get("confidence"),
+        "schema_completeness": round(sum(1 for bit in schema_bits if bit) / len(schema_bits), 2),
+        "ctx2skill_evidence_completeness": round(sum(1 for bit in evidence_bits if bit) / len(evidence_bits), 2),
+        "challenge_count": len(evidence.get("challenges") or []),
+        "judge_result_count": len(evidence.get("judge_results") or []),
+        "candidate_score_count": len(evidence.get("candidate_scores") or []),
+        "layering_reason_present": bool(meta.get("layering_reason")),
+        "graph_relation_preview_count": len(graph_preview) if isinstance(graph_preview, list) else 0,
+        "dependency_count": len(relations.get("dependency_ids") or []),
+        "component_count": len(relations.get("component_ids") or []),
+        "parent_count": len(relations.get("parent_skill_ids") or []),
+    }
+
+
+def expected_layer_score(case: FixtureCase, units: list[dict[str, Any]]) -> float:
+    if not units:
+        return 0.0
+    expected = case.expected_skill_shape.strip().lower()
+    if expected not in {"atomic", "functional", "strategic"}:
+        return 0.5
+    matches = sum(1 for unit in units if unit.get("proposed_type") == expected)
+    return round(matches / len(units), 2)
+
+
+def candidate_review_payload(unit: dict[str, Any], case: FixtureCase, *, run_id: str) -> dict[str, Any]:
+    meta = unit.get("metadata") or {}
+    interface = meta.get("candidate_interface") if isinstance(meta.get("candidate_interface"), dict) else {}
+    implementation = meta.get("candidate_implementation") if isinstance(meta.get("candidate_implementation"), dict) else {}
+    relations = meta.get("candidate_relations") if isinstance(meta.get("candidate_relations"), dict) else {}
+    evaluation = meta.get("candidate_evaluation") if isinstance(meta.get("candidate_evaluation"), dict) else None
+    source_type = unit.get("source_type") or case.input_type
+    base_name = normalize_skill_name(unit.get("proposed_skill_name") or f"{case.source_id}_{source_type}_candidate")
+    source_suffix = normalize_skill_name(case.source_id)
+    if source_suffix and source_suffix not in base_name:
+        name = normalize_skill_name(f"{base_name}_{source_suffix}")[:120]
+    else:
+        name = base_name
+    description = unit.get("proposed_description") or unit.get("summary") or name
+    if evaluation:
+        evaluation = dict(evaluation)
+        evaluation.setdefault("test_case_refs", [f"{case.source_id}:{unit.get('unit_id', 'unit')}"])
+        evaluation.setdefault("benchmark_task_ids", list(case.manifest.get("target_benchmark_tasks") or []))
+        evaluation.setdefault("validation_summary", "Created by isolated input-skill evaluation runner.")
+    else:
+        evaluation = {
+            "verifier_specs": [{"type": "json_exists", "path": "output.result"}],
+            "test_case_refs": [f"{case.source_id}:{unit.get('unit_id', 'unit')}"],
+            "benchmark_task_ids": list(case.manifest.get("target_benchmark_tasks") or []),
+            "validation_summary": "Created by isolated input-skill evaluation runner.",
+        }
+    tags = meta.get("candidate_tags") if isinstance(meta.get("candidate_tags"), list) else []
+    return {
+        "source_type": source_type,
+        "unit_id": unit.get("unit_id") or f"{case.source_id}:unit",
+        "raw_content": unit.get("raw_content") or "",
+        "name": name,
+        "description": description,
+        "skill_type": unit.get("proposed_type") if unit.get("proposed_type") in {"atomic", "functional", "strategic"} else "atomic",
+        "tags": unique_strings([
+            *tags,
+            *(unit.get("index_keywords") or [])[:4],
+            "input-skill-eval",
+            f"eval-run:{run_id}",
+            f"source-id:{case.source_id}",
+            f"domain:{case.domain}",
+        ])[:12],
+        "input_schema": interface.get("input_schema") or {"type": "object", "properties": {}},
+        "output_schema": interface.get("output_schema") or {"type": "object", "properties": {"result": {"type": "object"}}},
+        "preconditions": interface.get("preconditions") or [],
+        "postconditions": interface.get("postconditions") or ["Candidate returns a structured result."],
+        "prompt_template": implementation.get("prompt_template") or unit.get("summary") or description,
+        "provenance": {
+            "source_type": source_type,
+            "source_ids": unique_strings([case.source_id, unit.get("unit_id") or "unit"]),
+            "parent_skill_ids": relations.get("parent_skill_ids") or [],
+            "created_by_agent": "input_skill_eval_runner",
+            "creation_context": {
+                "eval_run_id": run_id,
+                "fixture_import_mode": "isolated_eval_candidate",
+                "source_id": case.source_id,
+                "input_type": case.input_type,
+                "domain": case.domain,
+                "source_url": case.source_url,
+                "paper_or_project": case.paper_or_project,
+                "expected_skill_shape": case.expected_skill_shape,
+                "license_note": case.license_note,
+                "local_path": str(case.local_path),
+                "content_sha256": case.content_sha256,
+                "ctx2skill_evidence": meta.get("ctx2skill_evidence"),
+            },
+        },
+        "evaluation": evaluation,
+        "dependency_ids": relations.get("dependency_ids") or [],
+        "component_ids": relations.get("component_ids") or [],
+        "sub_skill_ids": relations.get("sub_skill_ids") or relations.get("component_ids") or [],
+        "parent_skill_ids": relations.get("parent_skill_ids") or [],
+        "tool_calls": implementation.get("tool_calls") or [],
+        "author": "input_skill_eval_runner",
+    }
+
+
+def analyze_audit(payload: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "candidate_name": payload.get("name"),
+        "http_status": result.get("_http_status"),
+        "passed": bool(result.get("passed")),
+        "audit_score": result.get("audit_score"),
+        "issues": result.get("issues") or [],
+        "warnings": result.get("warnings") or [],
+    }
+
+
+def analyze_create(result: dict[str, Any]) -> dict[str, Any]:
+    created = result.get("created_skill") if isinstance(result.get("created_skill"), dict) else {}
+    return {
+        "http_status": result.get("_http_status"),
+        "success": bool(result.get("success")),
+        "created_skill_id": created.get("skill_id"),
+        "created_skill_name": created.get("name"),
+        "state": created.get("state"),
+        "audit_passed": (result.get("audit") or {}).get("passed") if isinstance(result.get("audit"), dict) else None,
+    }
+
+
+def check_graph_for_skill(client: "ApiClient", skill_id: str, *, label: str) -> dict[str, Any]:
+    result = client.get(f"/graph/view?view=skill_only&limit=500", label=label)
+    nodes = result.get("nodes") or []
+    edges = result.get("edges") or []
+    skill_present = any(str(node.get("skill_id") or node.get("id") or "").endswith(skill_id) for node in nodes)
+    relation_count = sum(
+        1 for edge in edges
+        if skill_id in str(edge.get("source") or edge.get("source_id") or "")
+        or skill_id in str(edge.get("target") or edge.get("target_id") or "")
+    )
+    return {
+        "skill_id": skill_id,
+        "http_status": result.get("_http_status"),
+        "skill_present": skill_present,
+        "relation_count": relation_count,
+        "node_count": len(nodes),
+        "edge_count": len(edges),
+    }
+
+
+def check_version_for_skill(client: "ApiClient", skill_id: str, *, label: str, snapshot: bool) -> dict[str, Any]:
+    diff = client.get(f"/lifecycle/{skill_id}/diff", label=f"{label}_diff")
+    result = {
+        "skill_id": skill_id,
+        "http_status": diff.get("_http_status"),
+        "business_diff_available": "business_diff" in diff or "business_summary" in diff or "history" in diff,
+        "raw_diff_available": "raw_diff" in diff or "changes" in diff or "snapshot_diff" in diff or "history" in diff,
+        "snapshot_created": False,
+    }
+    if snapshot:
+        snap = client.post(
+            f"/lifecycle/{skill_id}/snapshot",
+            {
+                "description": "Input-skill eval snapshot.",
+                "author": "input_skill_eval_runner",
+            },
+            label=f"{label}_snapshot",
+            timeout_s=120,
+        )
+        result["snapshot_http_status"] = snap.get("_http_status")
+        result["snapshot_created"] = snap.get("_http_status") in {200, 201} and not snap.get("detail")
+    return result
+
+
+def summarize_audits(items: list[dict[str, Any]]) -> dict[str, Any]:
+    if not items:
+        return {"status": "not_run"}
+    return {
+        "status": "completed",
+        "count": len(items),
+        "passed_count": sum(1 for item in items if item.get("passed")),
+        "average_audit_score": average([
+            float(item.get("audit_score") or 0.0)
+            for item in items
+            if isinstance(item.get("audit_score"), (int, float))
+        ]),
+        "items": items,
+    }
+
+
+def summarize_creates(items: list[dict[str, Any]]) -> dict[str, Any]:
+    if not items:
+        return {"status": "not_run"}
+    created_ids = [item.get("created_skill_id") for item in items if item.get("created_skill_id")]
+    return {
+        "status": "completed",
+        "count": len(items),
+        "success_count": sum(1 for item in items if item.get("success")),
+        "created_skill_ids": created_ids,
+        "http_statuses": [item.get("http_status") for item in items],
+        "items": items,
+    }
+
+
+def summarize_graph_checks(items: list[dict[str, Any]]) -> dict[str, Any]:
+    if not items:
+        return {"status": "not_run"}
+    return {
+        "status": "completed",
+        "count": len(items),
+        "present_count": sum(1 for item in items if item.get("skill_present")),
+        "relation_count": sum(int(item.get("relation_count") or 0) for item in items),
+        "items": items,
+    }
+
+
+def summarize_version_checks(items: list[dict[str, Any]]) -> dict[str, Any]:
+    if not items:
+        return {"status": "not_run"}
+    return {
+        "status": "completed",
+        "count": len(items),
+        "business_diff_available_count": sum(1 for item in items if item.get("business_diff_available")),
+        "snapshot_created_count": sum(1 for item in items if item.get("snapshot_created")),
+        "items": items,
+    }
+
+
+def score_fixture_record(record: dict[str, Any]) -> float:
+    parse = record.get("parse") or {}
+    score = 0.0
+    if parse.get("http_status") == 200 and parse.get("success"):
+        score += 0.18
+    if parse.get("unit_count", 0) > 0:
+        score += 0.10
+    score += 0.08 * clamp01(float(parse.get("schema_completeness") or 0.0))
+    score += 0.08 * clamp01(float(parse.get("ctx2skill_evidence_completeness") or 0.0))
+    score += 0.06 * clamp01(float(parse.get("layer_correctness") or 0.0))
+
+    audit = record.get("audit") or {}
+    if audit.get("status") == "completed":
+        score += 0.10 * ratio(audit.get("passed_count"), audit.get("count"))
+    elif audit.get("http_status") == 200 and audit.get("passed"):
+        score += 0.10
+
+    create = record.get("create") or {}
+    if create.get("status") == "completed":
+        score += 0.12 * ratio(create.get("success_count"), create.get("count"))
+    elif create.get("http_status") in {200, 201} and create.get("success"):
+        score += 0.12
+
+    graph = record.get("graph") or {}
+    if graph.get("status") == "completed":
+        score += 0.10 * ratio(graph.get("present_count"), graph.get("count"))
+        if int(graph.get("relation_count") or 0) > 0:
+            score += 0.05
+    elif graph.get("http_status") == 200 and graph.get("skill_present"):
+        score += 0.10
+        if int(graph.get("relation_count") or 0) > 0:
+            score += 0.05
+
+    version = record.get("version") or {}
+    if version.get("status") == "completed":
+        score += 0.06 * ratio(version.get("business_diff_available_count"), version.get("count"))
+        if int(version.get("snapshot_created_count") or 0) > 0:
+            score += 0.03
+    elif version.get("http_status") == 200:
+        if version.get("business_diff_available"):
+            score += 0.06
+        if version.get("snapshot_created"):
+            score += 0.03
+
+    harness = record.get("harness") or {}
+    if harness.get("status") == "verified":
+        score += 0.12
+    elif harness.get("positive_pass") or harness.get("negative_rejected"):
+        score += 0.06
+
+    skillsbench = record.get("skillsbench") or {}
+    if skillsbench.get("status") in {"mapped", "completed"} and skillsbench.get("verifier_ran"):
+        score += 0.10
+        if skillsbench.get("generated_pass"):
+            score += 0.05
+
+    return round(min(score, 1.0), 3)
+
+
+def summarize_scores(records: list[dict[str, Any]]) -> dict[str, Any]:
+    by_type_values: dict[str, list[float]] = {}
+    by_domain_values: dict[str, list[float]] = {}
+    for record in records:
+        score = float(record.get("score") or 0.0)
+        fixture = record.get("fixture") or {}
+        by_type_values.setdefault(str(fixture.get("input_type") or "unknown"), []).append(score)
+        by_domain_values.setdefault(str(fixture.get("domain") or "unknown"), []).append(score)
+    return {
+        "overall": average([float(record.get("score") or 0.0) for record in records]),
+        "by_input_type": {key: average(values) for key, values in by_type_values.items()},
+        "by_domain": {key: average(values) for key, values in by_domain_values.items()},
+        "sample_count": len(records),
+    }
+
+
+def render_report(summary: dict[str, Any]) -> str:
+    lines = [
+        "# SkillOS Input-to-Skill Evaluation Report",
+        "",
+        f"- Started: `{summary['started_at']}`",
+        f"- Finished: `{summary.get('finished_at', '')}`",
+        f"- API base: `{summary['api_base']}`",
+        f"- Manifest: `{summary['manifest']}`",
+        f"- Fixture root: `{summary['fixture_root']}`",
+        f"- Run directory: `{summary['run_dir']}`",
+        f"- Created candidates: `{summary['options']['create_candidates']}`",
+        "",
+        "## Isolation",
+        "",
+        "- Raw fixture files are read only.",
+        "- API responses and reports are written only under this run directory.",
+        "- Candidate creation is disabled unless `--create-candidates` is passed.",
+        "- SkillsBench results are explicit fields and remain `not_run` until the benchmark adapter executes.",
+        "",
+        "## Scores",
+        "",
+        f"- Overall: `{summary['scores']['overall']}`",
+        f"- By input type: `{json.dumps(summary['scores']['by_input_type'], ensure_ascii=False)}`",
+        f"- By domain: `{json.dumps(summary['scores']['by_domain'], ensure_ascii=False)}`",
+        f"- Skill delta: `{summary['skill_counts']['delta']}`",
+        "",
+        "## Fixtures",
+        "",
+    ]
+    for record in summary["records"]:
+        fixture = record["fixture"]
+        parse = record["parse"]
+        lines.extend([
+            f"### {fixture['source_id']} - {record['score']}",
+            f"- Input/domain: `{fixture['input_type']}` / `{fixture['domain']}`",
+            f"- Source: `{fixture.get('source_url', '')}`",
+            f"- Paper/project: `{fixture.get('paper_or_project', '')}`",
+            f"- Local file: `{fixture['local_path']}`",
+            f"- Parse: http=`{parse.get('http_status')}`, success=`{parse.get('success')}`, "
+            f"units=`{parse.get('unit_count')}`, schema=`{parse.get('schema_completeness')}`, "
+            f"ctx2skill=`{parse.get('ctx2skill_evidence_completeness')}`, layer=`{parse.get('layer_correctness')}`",
+            f"- Audit: `{record.get('audit', {}).get('status')}`",
+            f"- Create: `{record.get('create', {}).get('status')}`",
+            f"- Graph: `{record.get('graph', {}).get('status')}`",
+            f"- Version: `{record.get('version', {}).get('status')}`",
+            f"- Harness: `{record.get('harness', {}).get('status')}`",
+            f"- SkillsBench: `{record.get('skillsbench', {}).get('status')}`",
+            "",
+        ])
+    lines.append("Raw API envelopes are saved under `raw/` next to this report.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+class ApiClient:
+    def __init__(self, base_url: str, raw_dir: Path) -> None:
+        self.base_url = base_url
+        self.raw_dir = raw_dir
+
+    def get(self, path: str, *, label: str, timeout_s: int = 30) -> dict[str, Any]:
+        return self._request("GET", self.base_url + path, None, label, timeout_s)
+
+    def post(self, path: str, payload: dict[str, Any], *, label: str, timeout_s: int = 120) -> dict[str, Any]:
+        return self._request("POST", self.base_url + path, payload, label, timeout_s)
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        payload: dict[str, Any] | None,
+        label: str,
+        timeout_s: int,
+    ) -> dict[str, Any]:
+        data = None if payload is None else json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Accept", "application/json")
+        if payload is not None:
+            req.add_header("Content-Type", "application/json")
+        start = time.perf_counter()
+        try:
+            with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+                body = resp.read().decode("utf-8", errors="replace")
+                status = resp.status
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            status = exc.code
+        except Exception as exc:
+            body = json.dumps({"error": str(exc)}, ensure_ascii=False)
+            status = 0
+        elapsed_ms = round((time.perf_counter() - start) * 1000, 2)
+        parsed = parse_body(body)
+        envelope = {
+            "label": label,
+            "method": method,
+            "url": url,
+            "status_code": status,
+            "elapsed_ms": elapsed_ms,
+            "request_preview": preview_payload(payload),
+            "body": parsed,
+        }
+        write_json(self.raw_dir / f"{safe_filename(label)}.json", envelope)
+        if isinstance(parsed, dict):
+            result = dict(parsed)
+            result["_http_status"] = status
+            result["_elapsed_ms"] = elapsed_ms
+            return result
+        return {"_http_status": status, "_elapsed_ms": elapsed_ms, "body": parsed}
+
+
+def fixture_case_summary(case: FixtureCase) -> dict[str, Any]:
+    return {
+        "source_id": case.source_id,
+        "input_type": case.input_type,
+        "domain": case.domain,
+        "source_url": case.source_url,
+        "paper_or_project": case.paper_or_project,
+        "expected_skill_shape": case.expected_skill_shape,
+        "license_note": case.license_note,
+        "local_path": str(case.local_path),
+        "content_sha256": case.content_sha256,
+        "truncated": case.truncated,
+    }
+
+
+def count_skills(payload: Any) -> int:
+    if isinstance(payload, list):
+        return len(payload)
+    if isinstance(payload, dict):
+        body = payload.get("body")
+        if isinstance(body, list):
+            return len(body)
+        for key in ("value", "skills", "items"):
+            value = payload.get(key)
+            if isinstance(value, list):
+                return len(value)
+        if isinstance(payload.get("total"), int):
+            return int(payload["total"])
+    return 0
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def parse_body(body: str) -> Any:
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return body
+
+
+def preview_payload(payload: dict[str, Any] | None) -> Any:
+    if payload is None:
+        return None
+    preview = dict(payload)
+    content = preview.get("content")
+    if isinstance(content, str):
+        preview["content"] = f"{content[:500]}... [chars={len(content)}]"
+    return preview
+
+
+def normalize_skill_name(value: str) -> str:
+    text = re.sub(r"[^a-zA-Z0-9_]+", "_", str(value or "").strip().lower())
+    text = re.sub(r"_+", "_", text).strip("_")
+    return text[:120] or "input_skill_eval_candidate"
+
+
+def safe_filename(value: str) -> str:
+    normalized = normalize_skill_name(value).replace("/", "_")
+    if len(normalized) <= 96:
+        return normalized
+    digest = hashlib.sha1(str(value).encode("utf-8")).hexdigest()[:10]
+    return f"{normalized[:84].rstrip('_')}_{digest}"
+
+
+def unique_strings(values: list[Any]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        text = str(value or "").strip()
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        result.append(text)
+    return result
+
+
+def average(values: list[float]) -> float:
+    return round(sum(values) / len(values), 3) if values else 0.0
+
+
+def ratio(numerator: Any, denominator: Any) -> float:
+    try:
+        denom = float(denominator or 0)
+        if denom <= 0:
+            return 0.0
+        return clamp01(float(numerator or 0) / denom)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def clamp01(value: float) -> float:
+    return min(max(value, 0.0), 1.0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/run_p0_harness_eval.py

@@ -0,0 +1,518 @@
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import urllib.error
+import urllib.request
+from collections import Counter, defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_RUN_ROOT = REPO_ROOT / "artifacts" / "input-skill-eval-runs"
+
+
+class ApiClient:
+    def __init__(self, base_url: str, raw_dir: Path, timeout_s: int) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.raw_dir = raw_dir
+        self.timeout_s = timeout_s
+        self.raw_dir.mkdir(parents=True, exist_ok=True)
+
+    def get(self, path: str, *, label: str, timeout_s: int | None = None) -> Any:
+        with urllib.request.urlopen(f"{self.base_url}{path}", timeout=timeout_s or self.timeout_s) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+        self._write_raw(label, payload)
+        return payload
+
+    def post(self, path: str, payload: dict[str, Any], *, label: str, timeout_s: int | None = None) -> Any:
+        request = urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout_s or self.timeout_s) as response:
+                result = json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            result = {"http_error": exc.code, "body": body}
+        self._write_raw(label, {"request": payload, "response": result})
+        return result
+
+    def _write_raw(self, label: str, payload: Any) -> None:
+        safe = safe_filename(label)
+        (self.raw_dir / f"{safe}.json").write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Run representative positive/negative harness checks against generated P0 Skills. "
+            "Selects at least three generated Skills per input type from a full input-skill eval summary."
+        )
+    )
+    parser.add_argument("--input-eval-summary", required=True)
+    parser.add_argument("--api-base", default="http://127.0.0.1:8001/api/v1")
+    parser.add_argument("--run-root", default=str(DEFAULT_RUN_ROOT))
+    parser.add_argument("--run-id", default=datetime.now().strftime("%Y%m%d-%H%M%S"))
+    parser.add_argument("--per-type", type=int, default=3)
+    parser.add_argument("--request-timeout", type=int, default=180)
+    parser.add_argument("--harness-timeout", type=int, default=120)
+    parser.add_argument("--output-report", default="")
+    args = parser.parse_args(argv)
+
+    input_summary_path = Path(args.input_eval_summary).resolve()
+    input_summary = read_json(input_summary_path)
+    run_dir = Path(args.run_root).resolve() / f"p0-harness-eval-{args.run_id}"
+    raw_dir = run_dir / "raw"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    client = ApiClient(args.api_base, raw_dir, args.request_timeout)
+
+    selected = select_records(input_summary, per_type=args.per_type)
+    summary: dict[str, Any] = {
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "api_base": client.base_url,
+        "input_eval_summary": str(input_summary_path),
+        "run_dir": str(run_dir),
+        "run_id": args.run_id,
+        "per_type": args.per_type,
+        "checks": [],
+        "notes": [
+            "Positive checks use generated Skill verifier specs and allow deterministic repair when output fields are missing.",
+            "Negative checks use the same Skill verifier specs with intentionally invalid inputs and allow_repair=false.",
+            "This runner mutates only the isolated eval backend state by moving selected generated candidates to S2 and creating repaired S2/S3 versions as needed; raw corpora remain read-only.",
+        ],
+    }
+    summary["connectivity"] = {
+        "skills_before": client.get("/skills?limit=500", label="skills_before_p0_harness"),
+    }
+
+    for record in selected:
+        item = run_record_checks(client, record, timeout_s=args.harness_timeout)
+        summary["checks"].append(item)
+
+    summary["scores"] = score_checks(summary["checks"])
+    summary["finished_at"] = datetime.now().isoformat(timespec="seconds")
+    write_json(run_dir / "summary.json", summary)
+    report_text = render_report(summary)
+    (run_dir / "REPORT.md").write_text(report_text, encoding="utf-8")
+    if args.output_report:
+        Path(args.output_report).write_text(report_text, encoding="utf-8")
+
+    print(json.dumps({"run_dir": str(run_dir), "scores": summary["scores"]}, ensure_ascii=False, indent=2))
+    return 0 if summary["scores"]["input_types_meeting_minimum"] == 5 else 1
+
+
+def read_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, payload: Any) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def select_records(input_summary: dict[str, Any], *, per_type: int) -> list[dict[str, Any]]:
+    selected: list[dict[str, Any]] = []
+    counts: Counter[str] = Counter()
+    records = input_summary.get("records") if isinstance(input_summary.get("records"), list) else []
+    for record in records:
+        fixture = record.get("fixture") if isinstance(record, dict) else {}
+        input_type = str(fixture.get("input_type") or "")
+        create = record.get("create") if isinstance(record.get("create"), dict) else {}
+        created_ids = create.get("created_skill_ids") if isinstance(create.get("created_skill_ids"), list) else []
+        if not input_type or not created_ids or counts[input_type] >= per_type:
+            continue
+        selected.append(record)
+        counts[input_type] += 1
+    return selected
+
+
+def run_record_checks(client: ApiClient, record: dict[str, Any], *, timeout_s: int) -> dict[str, Any]:
+    fixture = record["fixture"]
+    input_type = fixture["input_type"]
+    source_id = fixture["source_id"]
+    skill_id = record["create"]["created_skill_ids"][0]
+    skill = client.get(f"/skills/{skill_id}/full", label=f"skill_full_{source_id}")
+    negative_draft = ensure_draft_with_executable_impl(client, skill, fixture, purpose="negative")
+    positive_draft = ensure_draft_with_executable_impl(client, skill, fixture, purpose="positive")
+    positive_case = build_positive_test_case(positive_draft, fixture, timeout_s=timeout_s)
+    negative_case = build_negative_test_case(negative_draft, fixture, timeout_s=timeout_s)
+    negative = client.post(
+        f"/harness/{negative_draft['skill_id']}/verify-loop",
+        {
+            "harness": "local_skillos",
+            "max_attempts": 1,
+            "promote_on_pass": False,
+            "allow_repair": False,
+            "timeout_s": timeout_s,
+            "test_cases": [negative_case],
+        },
+        label=f"harness_negative_{source_id}",
+        timeout_s=timeout_s + 180,
+    )
+    positive = client.post(
+        f"/harness/{positive_draft['skill_id']}/verify-loop",
+        {
+            "harness": "local_skillos",
+            "max_attempts": 2,
+            "promote_on_pass": True,
+            "allow_repair": True,
+            "timeout_s": timeout_s,
+            "test_cases": [positive_case],
+        },
+        label=f"harness_positive_{source_id}",
+        timeout_s=timeout_s + 180,
+    )
+    return {
+        "input_type": input_type,
+        "source_id": source_id,
+        "domain": fixture.get("domain"),
+        "skill_id": skill_id,
+        "positive_draft_skill_id": positive_draft["skill_id"],
+        "negative_draft_skill_id": negative_draft["skill_id"],
+        "skill_name": positive_draft.get("name"),
+        "positive": summarize_loop(positive),
+        "negative": summarize_loop(negative),
+        "positive_pass": bool(positive.get("promotion_allowed")),
+        "negative_rejected": not bool(negative.get("promotion_allowed")) and not bool(negative.get("http_error")),
+        "attempt_count": int(positive.get("attempt_count") or 0),
+        "repair_count": len(positive.get("repairs") if isinstance(positive.get("repairs"), list) else []),
+        "final_state": str(positive.get("final_state") or ""),
+        "evidence_path": positive.get("evidence_path", ""),
+    }
+
+
+def ensure_draft_with_executable_impl(
+    client: ApiClient,
+    skill: dict[str, Any],
+    fixture: dict[str, Any],
+    *,
+    purpose: str,
+) -> dict[str, Any]:
+    source_skill_id = latest_version_skill_id(client, skill)
+    implementation = dict(skill.get("implementation") or {})
+    evaluation = dict(skill.get("evaluation") or {})
+    verifier_specs = list(evaluation.get("verifier_specs") or [])
+    code = render_contract_echo_code(verifier_specs, input_type=str(fixture.get("input_type") or ""))
+    implementation["language"] = "python"
+    implementation["code"] = code
+    implementation["prompt_template"] = None
+    payload = {
+        "bump": "patch",
+        "description": f"{skill.get('description', '')} Harness-evaluable P0 draft for {fixture.get('source_id')}.",
+        "tags": list(dict.fromkeys([*(skill.get("tags") or []), "p0-harness-eval"])),
+        "implementation": implementation,
+        "evaluation": evaluation,
+        "metadata": {
+            "p0_harness_eval": True,
+            "purpose": purpose,
+            "source_id": fixture.get("source_id"),
+            "input_type": fixture.get("input_type"),
+            "created_from_skill_id": skill.get("skill_id"),
+        },
+        "author": "codex-p0-harness-eval",
+    }
+    created = client.post(
+        f"/lifecycle/{source_skill_id}/new-version",
+        payload,
+        label=f"new_version_for_harness_{purpose}_{fixture.get('source_id')}",
+    )
+    if created.get("http_error"):
+        raise RuntimeError(f"Failed to create harness draft for {fixture.get('source_id')}: {created}")
+    return client.get(f"/skills/{created['skill_id']}/full", label=f"harness_draft_full_{purpose}_{fixture.get('source_id')}")
+
+
+def latest_version_skill_id(client: ApiClient, skill: dict[str, Any]) -> str:
+    versions = client.get(f"/skills/{skill['skill_id']}/versions", label=f"versions_{skill.get('skill_id')}")
+    if not isinstance(versions, list) or not versions:
+        return str(skill["skill_id"])
+    latest = max(
+        (item for item in versions if isinstance(item, dict) and item.get("skill_id")),
+        key=lambda item: (parse_version(str(item.get("version") or "")), str(item.get("updated_at") or "")),
+        default=skill,
+    )
+    return str(latest.get("skill_id") or skill["skill_id"])
+
+
+def parse_version(version: str) -> tuple[int, ...]:
+    parts: list[int] = []
+    for chunk in str(version or "").split("."):
+        try:
+            parts.append(int(chunk))
+        except ValueError:
+            parts.append(0)
+    return tuple(parts)
+
+
+def render_contract_echo_code(verifier_specs: list[dict[str, Any]], *, input_type: str) -> str:
+    lines = [
+        "output['result'] = {}",
+        "output['evidence'] = ['p0 harness contract evidence']",
+        "output['verifier'] = {'passed': True, 'checked': ['p0 harness deterministic contract']}",
+    ]
+    if input_type == "past_skills":
+        lines.append("output['validation'] = {'passed': True, 'source': 'p0 harness deterministic contract'}")
+    for spec in verifier_specs:
+        if not isinstance(spec, dict):
+            continue
+        path = str(spec.get("path") or "")
+        if not path.startswith("output."):
+            continue
+        field_path = path.split(".", 1)[1]
+        value = value_for_spec(spec, path)
+        lines.extend(nested_assignment(field_path, value))
+    return "\n".join(lines)
+
+
+def value_for_spec(spec: dict[str, Any], path: str) -> Any:
+    spec_type = str(spec.get("type") or "")
+    if spec_type == "json_equals" and "value" in spec:
+        return spec["value"]
+    if spec_type in {"json_array", "json_array_nonempty"}:
+        return [f"p0 harness value for {path}"]
+    if spec_type in {"json_object", "json_object_nonempty", "json_exists"} and path.endswith((".result", ".validation", ".verifier")):
+        return {"passed": True, "source": "p0 harness"}
+    if spec_type in {"json_object", "json_object_nonempty"}:
+        return {"value": "p0 harness"}
+    return f"p0 harness value for {path}"
+
+
+def nested_assignment(field_path: str, value: Any) -> list[str]:
+    parts = [part for part in field_path.split(".") if part]
+    if not parts:
+        return []
+    if len(parts) == 1:
+        return [f"output[{parts[0]!r}] = {value!r}"]
+    lines: list[str] = []
+    cursor = "output"
+    for part in parts[:-1]:
+        lines.append(f"if not isinstance({cursor}.get({part!r}), dict):")
+        lines.append(f"    {cursor}[{part!r}] = {{}}")
+        cursor = f"{cursor}[{part!r}]"
+    lines.append(f"{cursor}[{parts[-1]!r}] = {value!r}")
+    return lines
+
+
+def build_positive_test_case(skill: dict[str, Any], fixture: dict[str, Any], *, timeout_s: int) -> dict[str, Any]:
+    input_schema = (skill.get("interface") or {}).get("input_schema") or {}
+    input_data = example_from_schema(input_schema)
+    input_data.update(positive_overrides(str(fixture.get("input_type") or ""), fixture))
+    return {
+        "test_id": f"positive-{fixture['source_id']}",
+        "name": f"P0 positive harness for {fixture['source_id']}",
+        "goal": f"Run generated Skill for {fixture['input_type']} source {fixture['source_id']} with valid inputs.",
+        "input_data": input_data,
+        "verifier_specs": skill.get("evaluation", {}).get("verifier_specs") or [],
+        "timeout_s": timeout_s,
+    }
+
+
+def build_negative_test_case(skill: dict[str, Any], fixture: dict[str, Any], *, timeout_s: int) -> dict[str, Any]:
+    input_schema = (skill.get("interface") or {}).get("input_schema") or {}
+    input_data = example_from_schema(input_schema)
+    required_path = ""
+    for required in input_schema.get("required") or []:
+        if isinstance(required, str):
+            input_data[required] = empty_value(input_data.get(required))
+            required_path = f"input.{required}"
+            break
+    if fixture.get("input_type") == "script":
+        input_data["dry_run"] = False
+        input_data["allowed_paths"] = []
+        required_path = "input.dry_run"
+    verifier_specs = list(skill.get("evaluation", {}).get("verifier_specs") or [])
+    if required_path and not any(str(spec.get("path") or "") == required_path for spec in verifier_specs if isinstance(spec, dict)):
+        verifier_specs.insert(0, {"type": "json_nonempty", "path": required_path})
+    return {
+        "test_id": f"negative-{fixture['source_id']}",
+        "name": f"P0 negative harness for {fixture['source_id']}",
+        "goal": f"Reject generated Skill for {fixture['input_type']} source {fixture['source_id']} when required input is invalid.",
+        "input_data": input_data,
+        "verifier_specs": verifier_specs,
+        "timeout_s": timeout_s,
+    }
+
+
+def positive_overrides(input_type: str, fixture: dict[str, Any]) -> dict[str, Any]:
+    local_path = str(fixture.get("local_path") or fixture.get("content_file") or "")
+    if input_type == "document":
+        return {
+            "task": f"Extract a reusable procedure from {fixture.get('source_id')}.",
+            "document_context": f"Local fixture: {local_path}",
+            "allowed_operations": ["read_context", "extract_steps", "cite_evidence"],
+        }
+    if input_type == "api_doc":
+        return {
+            "task": f"Prepare an API call contract from {fixture.get('source_id')}.",
+            "endpoint": "/demo",
+            "parameters": {"demo": True},
+        }
+    if input_type == "script":
+        return {
+            "task": f"Dry-run analyze script fixture {fixture.get('source_id')}.",
+            "script_context": f"Local fixture: {local_path}",
+            "dry_run": True,
+            "allowed_paths": [local_path or "fixture.sh"],
+        }
+    if input_type == "past_skills":
+        return {
+            "task": f"Normalize and execute imported legacy Skill {fixture.get('source_id')}.",
+            "source_context": f"Local fixture: {local_path}",
+            "artifact_type": "document",
+            "source_files": [local_path] if local_path else [],
+            "project_files": [],
+            "target_runtime": "SkillOS local harness",
+        }
+    return {
+        "task": f"Replay and summarize trajectory {fixture.get('source_id')}.",
+        "context": {"source_id": fixture.get("source_id"), "local_path": local_path},
+    }
+
+
+def example_from_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    properties = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
+    required = schema.get("required") if isinstance(schema.get("required"), list) else list(properties)
+    return {
+        name: example_value(properties.get(name, {}))
+        for name in required
+        if isinstance(name, str)
+    }
+
+
+def example_value(schema: dict[str, Any]) -> Any:
+    schema_type = schema.get("type")
+    if schema_type == "boolean":
+        return True
+    if schema_type == "array":
+        return ["demo"]
+    if schema_type == "object":
+        return {"demo": True}
+    if schema_type in {"number", "integer"}:
+        return 1
+    return "demo"
+
+
+def empty_value(value: Any) -> Any:
+    if isinstance(value, list):
+        return []
+    if isinstance(value, dict):
+        return {}
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return 0
+    return ""
+
+
+def summarize_loop(payload: dict[str, Any]) -> dict[str, Any]:
+    attempts = payload.get("attempts") if isinstance(payload.get("attempts"), list) else []
+    return {
+        "http_error": payload.get("http_error"),
+        "status": payload.get("status"),
+        "promotion_allowed": bool(payload.get("promotion_allowed")),
+        "attempt_count": payload.get("attempt_count"),
+        "repair_count": len(payload.get("repairs") if isinstance(payload.get("repairs"), list) else []),
+        "final_state": payload.get("final_state"),
+        "score": payload.get("score"),
+        "loop_id": payload.get("loop_id"),
+        "evidence_path": payload.get("evidence_path"),
+        "failure_reasons": [
+            attempt.get("failure_reason")
+            for attempt in attempts
+            if isinstance(attempt, dict) and attempt.get("failure_reason")
+        ],
+    }
+
+
+def score_checks(checks: list[dict[str, Any]]) -> dict[str, Any]:
+    by_type: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for check in checks:
+        by_type[str(check.get("input_type") or "")].append(check)
+    positive_pass = sum(1 for item in checks if item.get("positive_pass"))
+    negative_rejected = sum(1 for item in checks if item.get("negative_rejected"))
+    total = len(checks)
+    return {
+        "sample_count": total,
+        "positive_pass_rate": round(positive_pass / total, 3) if total else 0.0,
+        "negative_rejection_rate": round(negative_rejected / total, 3) if total else 0.0,
+        "input_types_meeting_minimum": sum(1 for items in by_type.values() if len(items) >= 3),
+        "by_input_type": {
+            input_type: {
+                "count": len(items),
+                "positive_pass_rate": round(sum(1 for item in items if item.get("positive_pass")) / len(items), 3),
+                "negative_rejection_rate": round(sum(1 for item in items if item.get("negative_rejected")) / len(items), 3),
+            }
+            for input_type, items in sorted(by_type.items())
+        },
+    }
+
+
+def render_report(summary: dict[str, Any]) -> str:
+    scores = summary.get("scores", {})
+    lines = [
+        "# SkillOS P0 Harness Positive / Negative Report",
+        "",
+        f"- Started: `{summary.get('started_at')}`",
+        f"- Finished: `{summary.get('finished_at')}`",
+        f"- API base: `{summary.get('api_base')}`",
+        f"- Run dir: `{summary.get('run_dir')}`",
+        f"- Sample count: `{scores.get('sample_count', 0)}`",
+        f"- Positive pass rate: `{scores.get('positive_pass_rate', 0.0)}`",
+        f"- Negative rejection rate: `{scores.get('negative_rejection_rate', 0.0)}`",
+        f"- Input types with at least 3 samples: `{scores.get('input_types_meeting_minimum', 0)}/5`",
+        "",
+        "## By Input Type",
+        "",
+        "| input_type | count | positive pass | negative rejected |",
+        "| --- | ---: | ---: | ---: |",
+    ]
+    for input_type, item in (scores.get("by_input_type") or {}).items():
+        lines.append(
+            f"| {input_type} | {item['count']} | {item['positive_pass_rate']:.3f} | {item['negative_rejection_rate']:.3f} |"
+        )
+    lines.extend(
+        [
+            "",
+            "## Checks",
+            "",
+            "| input_type | source_id | positive | negative rejected | attempts | repairs | final_state | evidence_path |",
+            "| --- | --- | --- | --- | ---: | ---: | --- | --- |",
+        ]
+    )
+    for item in summary.get("checks", []):
+        lines.append(
+            "| {input_type} | {source_id} | {positive} | {negative} | {attempts} | {repairs} | {state} | `{evidence}` |".format(
+                input_type=item.get("input_type"),
+                source_id=item.get("source_id"),
+                positive=item.get("positive_pass"),
+                negative=item.get("negative_rejected"),
+                attempts=item.get("attempt_count"),
+                repairs=item.get("repair_count"),
+                state=item.get("final_state"),
+                evidence=item.get("evidence_path") or "",
+            )
+        )
+    lines.extend(
+        [
+            "",
+            "## Boundary",
+            "",
+            "These checks prove that representative generated Skills can be put through the S2 -> harness -> verifier -> S3 gate with deterministic local contracts. They do not prove open-world semantic correctness or official SkillsBench sandbox scores.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def safe_filename(value: str) -> str:
+    normalized = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(value or "")).strip("._")
+    return normalized[:120] or "artifact"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skillwiki-frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

skillwiki-frontend/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80

skillwiki-frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

skillwiki-frontend/eslint.config.js

@@ -0,0 +1,22 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+])

skillwiki-frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SkillWiki</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

skillwiki-frontend/nginx.conf

@@ -0,0 +1,32 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Frontend route fallback
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Proxy API requests to the backend
+    location /api/ {
+        proxy_pass http://api:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # Proxy WebSocket traffic
+    location /ws {
+        proxy_pass http://api:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+
+    # Static asset cache
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}

skillwiki-frontend/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "skillwiki-frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@ant-design/charts": "^2.6.7",
+    "@ant-design/icons": "^6.1.1",
+    "@antv/g6": "^5.1.0",
+    "antd": "^6.3.6",
+    "axios": "^1.15.2",
+    "framer-motion": "^12.38.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-router-dom": "^7.14.2",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-router-dom": "^5.3.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.2.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.5.0",
+    "puppeteer": "^25.1.0",
+    "sharp": "^0.35.1",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.58.2",
+    "vite": "^8.0.10"
+  }
+}

skillwiki-frontend/scripts/capture_figures.mjs

@@ -0,0 +1,198 @@
+/**
+ * Captures four paper figures from the running SkillWiki frontend.
+ * Run: node scripts/capture_figures.mjs
+ * Output: ../figures/figure3_system/fig3_{scene}.png  (1280×720 each)
+ */
+import puppeteer from 'puppeteer'
+import { mkdirSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const BASE_URL = 'http://localhost:3000'
+const OUT_DIR = resolve(__dirname, '../../figures/figure3_system')
+const W = 1280
+const H = 720
+
+mkdirSync(OUT_DIR, { recursive: true })
+
+async function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms))
+}
+
+const browser = await puppeteer.launch({
+  headless: 'new',
+  args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+})
+
+async function newPage() {
+  const page = await browser.newPage()
+  await page.setViewport({ width: W, height: H, deviceScaleFactor: 2 })
+  await page.evaluateOnNewDocument(() => {
+    localStorage.setItem(
+      'skillwiki-app-store',
+      JSON.stringify({ state: { lang: 'en', darkMode: false }, version: 0 }),
+    )
+  })
+  return page
+}
+
+// ──────────────────────────────────────────────────────────────
+// 1. Knowledge Ingestion — API Doc tab + content + parse running
+// ──────────────────────────────────────────────────────────────
+{
+  console.log('Capturing: knowledge_ingestion ...')
+  const page = await newPage()
+  await page.goto(`${BASE_URL}/ingest`, { waitUntil: 'networkidle2', timeout: 30000 })
+  await page.waitForSelector('.ant-tabs-tab', { timeout: 10000 })
+  await sleep(600)
+
+  // Scroll to top
+  await page.evaluate(() => window.scrollTo(0, 0))
+
+  // Switch to "API Doc" tab
+  const tabs = await page.$$('.ant-tabs-tab')
+  for (const tab of tabs) {
+    const text = await tab.evaluate(el => el.textContent)
+    if (text && text.includes('API Doc')) {
+      await tab.click()
+      break
+    }
+  }
+  await sleep(500)
+
+  // Fill textarea with API doc content
+  const apiDocContent = `GET /v1/models
+Description: List all available language models and their metadata.
+Headers: { "Authorization": "Bearer <api_key>" }
+Response: {
+  "data": [
+    { "id": "string", "object": "model", "created": "integer", "owned_by": "string" }
+  ],
+  "has_more": false
+}
+Errors: 401 Unauthorized when API key is missing or invalid.`
+
+  // Clear and type content using Puppeteer's type() to properly trigger React state
+  const ta = await page.$('textarea')
+  if (ta) {
+    await ta.click({ clickCount: 3 })
+    await ta.press('Backspace')
+    await sleep(200)
+    await ta.type(`GET /v1/models\nDescription: List all available language models and metadata.\nHeaders: { "Authorization": "Bearer <api_key>" }\nResponse: { "data": [{ "id": "string", "object": "model", "owned_by": "string" }], "has_more": false }\nErrors: 401 Unauthorized when API key is missing.`, { delay: 0 })
+  }
+  await sleep(400)
+
+  // Scroll to top to show tabs + textarea filled
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await sleep(200)
+
+  // Click Parse button — scroll it into view first
+  const parseClicked = await page.evaluate(() => {
+    const all = Array.from(document.querySelectorAll('button'))
+    const parseBtn = all.find(b => b.textContent && b.textContent.includes('Parse'))
+    if (!parseBtn) return false
+    parseBtn.scrollIntoView({ behavior: 'instant', block: 'center' })
+    parseBtn.click()
+    return true
+  })
+  console.log(`  Parse button clicked: ${parseClicked}`)
+  await sleep(500)
+  // Scroll back to top after clicking
+  await page.evaluate(() => window.scrollTo(0, 0))
+
+  // Wait for parsed result panel to appear (badge "Ready" or unit count card)
+  try {
+    await page.waitForFunction(
+      () => {
+        const body = document.body.innerText
+        return body.includes('Ready') || body.includes('Parsed Units') || body.includes('Unit count')
+      },
+      { timeout: 15000 },
+    )
+    console.log('  Parse result detected')
+  } catch {
+    console.warn('  Parse result not detected, using fixed delay')
+    await sleep(4000)
+  }
+
+  await sleep(600)
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await sleep(200)
+
+  const outPath = resolve(OUT_DIR, 'fig3_knowledge_ingestion.png')
+  await page.screenshot({ path: outPath, fullPage: false })
+  console.log(`  Saved: ${outPath}`)
+  await page.close()
+}
+
+// ──────────────────────────────────────────────────────────────
+// 2. Skill Exploration — full nebula + real node via ?preselect=
+// ────────────────────────────────────────────���─────────────────
+{
+  console.log('Capturing: skill_exploration ...')
+  const page = await newPage()
+  const REAL_SKILL_ID = 'test_graph_review_output'
+
+  await page.goto(`${BASE_URL}/graph?preselect=${REAL_SKILL_ID}`, { waitUntil: 'load', timeout: 30000 })
+  await page.waitForFunction(
+    () => document.querySelectorAll('.ant-card').length >= 2,
+    { timeout: 30000, polling: 500 },
+  )
+  await sleep(1000)
+  try {
+    await page.waitForSelector('canvas', { timeout: 25000 })
+  } catch {
+    console.warn('  canvas not found, proceeding anyway')
+  }
+
+  // Wait for force layout + preselect effect to fire
+  await sleep(8000)
+  await page.evaluate(() => window.scrollTo(0, 0))
+  await sleep(300)
+
+  const nodeSelected = await page.evaluate(() => {
+    const items = document.querySelectorAll('.ant-card .ant-descriptions .ant-descriptions-item')
+    return items.length > 0
+  })
+
+  const outPath = resolve(OUT_DIR, 'fig3_skill_exploration.png')
+  await page.screenshot({ path: outPath, fullPage: false })
+  console.log(`  Saved: ${outPath} (node selected: ${nodeSelected})`)
+  await page.close()
+}
+
+// ──────────────────────────────────────────────────────────────
+// 3. Governance (Dashboard)
+// ──────────────────────────────────────────────────────────────
+{
+  console.log('Capturing: governance ...')
+  const page = await newPage()
+  await page.goto(`${BASE_URL}/`, { waitUntil: 'networkidle2', timeout: 30000 })
+  await page.waitForSelector('.ant-statistic', { timeout: 10000 })
+  await sleep(1800)
+
+  const outPath = resolve(OUT_DIR, 'fig3_governance.png')
+  await page.screenshot({ path: outPath, fullPage: false })
+  console.log(`  Saved: ${outPath}`)
+  await page.close()
+}
+
+// ──────────────────────────────────────────────────────────────
+// 4. Evolution
+// ──────────────────────────────────────────────────────────────
+{
+  console.log('Capturing: evolution ...')
+  const page = await newPage()
+  await page.goto(`${BASE_URL}/evolution`, { waitUntil: 'networkidle2', timeout: 30000 })
+  await page.waitForSelector('.ant-statistic', { timeout: 10000 })
+  await sleep(2000)
+
+  const outPath = resolve(OUT_DIR, 'fig3_evolution.png')
+  await page.screenshot({ path: outPath, fullPage: false })
+  console.log(`  Saved: ${outPath}`)
+  await page.close()
+}
+
+await browser.close()
+console.log('\nAll figures saved to:', OUT_DIR)

skillwiki-frontend/src/App.css

@@ -0,0 +1,184 @@
+.counter {
+  font-size: 16px;
+  padding: 5px 10px;
+  border-radius: 5px;
+  color: var(--accent);
+  background: var(--accent-bg);
+  border: 2px solid transparent;
+  transition: border-color 0.3s;
+  margin-bottom: 24px;
+
+  &:hover {
+    border-color: var(--accent-border);
+  }
+  &:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+}
+
+.hero {
+  position: relative;
+
+  .base,
+  .framework,
+  .vite {
+    inset-inline: 0;
+    margin: 0 auto;
+  }
+
+  .base {
+    width: 170px;
+    position: relative;
+    z-index: 0;
+  }
+
+  .framework,
+  .vite {
+    position: absolute;
+  }
+
+  .framework {
+    z-index: 1;
+    top: 34px;
+    height: 28px;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(44deg) rotateY(39deg)
+      scale(1.4);
+  }
+
+  .vite {
+    z-index: 0;
+    top: 107px;
+    height: 26px;
+    width: auto;
+    transform: perspective(2000px) rotateZ(300deg) rotateX(40deg) rotateY(39deg)
+      scale(0.8);
+  }
+}
+
+#center {
+  display: flex;
+  flex-direction: column;
+  gap: 25px;
+  place-content: center;
+  place-items: center;
+  flex-grow: 1;
+
+  @media (max-width: 1024px) {
+    padding: 32px 20px 24px;
+    gap: 18px;
+  }
+}
+
+#next-steps {
+  display: flex;
+  border-top: 1px solid var(--border);
+  text-align: left;
+
+  & > div {
+    flex: 1 1 0;
+    padding: 32px;
+    @media (max-width: 1024px) {
+      padding: 24px 20px;
+    }
+  }
+
+  .icon {
+    margin-bottom: 16px;
+    width: 22px;
+    height: 22px;
+  }
+
+  @media (max-width: 1024px) {
+    flex-direction: column;
+    text-align: center;
+  }
+}
+
+#docs {
+  border-right: 1px solid var(--border);
+
+  @media (max-width: 1024px) {
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+  }
+}
+
+#next-steps ul {
+  list-style: none;
+  padding: 0;
+  display: flex;
+  gap: 8px;
+  margin: 32px 0 0;
+
+  .logo {
+    height: 18px;
+  }
+
+  a {
+    color: var(--text-h);
+    font-size: 16px;
+    border-radius: 6px;
+    background: var(--social-bg);
+    display: flex;
+    padding: 6px 12px;
+    align-items: center;
+    gap: 8px;
+    text-decoration: none;
+    transition: box-shadow 0.3s;
+
+    &:hover {
+      box-shadow: var(--shadow);
+    }
+    .button-icon {
+      height: 18px;
+      width: 18px;
+    }
+  }
+
+  @media (max-width: 1024px) {
+    margin-top: 20px;
+    flex-wrap: wrap;
+    justify-content: center;
+
+    li {
+      flex: 1 1 calc(50% - 8px);
+    }
+
+    a {
+      width: 100%;
+      justify-content: center;
+      box-sizing: border-box;
+    }
+  }
+}
+
+#spacer {
+  height: 88px;
+  border-top: 1px solid var(--border);
+  @media (max-width: 1024px) {
+    height: 48px;
+  }
+}
+
+.ticks {
+  position: relative;
+  width: 100%;
+
+  &::before,
+  &::after {
+    content: '';
+    position: absolute;
+    top: -4.5px;
+    border: 5px solid transparent;
+  }
+
+  &::before {
+    left: 0;
+    border-left-color: var(--border);
+  }
+  &::after {
+    right: 0;
+    border-right-color: var(--border);
+  }
+}

skillwiki-frontend/src/App.tsx

@@ -0,0 +1,66 @@
+import { lazy, Suspense } from 'react'
+import { BrowserRouter, Route, Routes } from 'react-router-dom'
+import { ConfigProvider, Spin, theme } from 'antd'
+import enUS from 'antd/locale/en_US'
+import zhCN from 'antd/locale/zh_CN'
+import { useAppStore } from '@/store/appStore'
+import AppLayout from '@/components/AppLayout'
+
+const Dashboard = lazy(() => import('@/pages/Dashboard'))
+const EvaluationDashboard = lazy(() => import('@/pages/EvaluationDashboard'))
+const SkillWiki = lazy(() => import('@/pages/SkillWiki'))
+const SkillGraph = lazy(() => import('@/pages/SkillGraph'))
+const AgentExecution = lazy(() => import('@/pages/AgentExecution'))
+const HarnessVerification = lazy(() => import('@/pages/HarnessVerification'))
+const Evolution = lazy(() => import('@/pages/Evolution'))
+const LifecycleDemo = lazy(() => import('@/pages/LifecycleDemo'))
+const KnowledgeImport = lazy(() => import('@/pages/KnowledgeImport'))
+const VersionControl = lazy(() => import('@/pages/VersionControl'))
+const SelfEvolutionDemo = lazy(() => import('@/pages/SelfEvolutionDemo'))
+
+function PageFallback() {
+  return (
+    <div style={{ minHeight: 360, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+      <Spin size="large" description="Loading page..." />
+    </div>
+  )
+}
+
+export default function App() {
+  const darkMode = useAppStore(s => s.darkMode)
+  const lang = useAppStore(s => s.lang)
+
+  return (
+    <ConfigProvider
+      locale={lang === 'zh' ? zhCN : enUS}
+      theme={{
+        algorithm: darkMode ? theme.darkAlgorithm : theme.defaultAlgorithm,
+        token: {
+          colorPrimary: '#1677ff',
+          borderRadius: 8,
+          fontFamily: "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        },
+      }}
+    >
+      <BrowserRouter>
+        <AppLayout>
+          <Suspense fallback={<PageFallback />}>
+            <Routes>
+              <Route path="/" element={<Dashboard />} />
+              <Route path="/evaluation" element={<EvaluationDashboard />} />
+              <Route path="/wiki" element={<SkillWiki />} />
+              <Route path="/graph" element={<SkillGraph />} />
+              <Route path="/execution" element={<AgentExecution />} />
+              <Route path="/harness" element={<HarnessVerification />} />
+              <Route path="/evolution" element={<Evolution />} />
+              <Route path="/lifecycle" element={<LifecycleDemo />} />
+              <Route path="/ingest" element={<KnowledgeImport />} />
+              <Route path="/versions" element={<VersionControl />} />
+              <Route path="/demo" element={<SelfEvolutionDemo />} />
+            </Routes>
+          </Suspense>
+        </AppLayout>
+      </BrowserRouter>
+    </ConfigProvider>
+  )
+}

skillwiki-frontend/src/api/client.ts

@@ -0,0 +1,274 @@
+import axios from 'axios'
+import type {
+  CandidateAuditResult,
+  CandidateCreateResponse,
+  CandidateSkillReviewRequest,
+  EvaluationDashboardResponse,
+  ExecutionExperienceUnit,
+  ExecutionResult,
+  ExecutionHistoryItem,
+  GraphData,
+  GraphViewData,
+  GraphViewMode,
+  HarnessLoopListResponse,
+  HarnessVerifyLoopRequest,
+  HarnessVerifyLoopResponse,
+  HeterogeneousGraphData,
+  HealthReport,
+  IngestResponse,
+  MaintenanceReviewRequest,
+  MaintenanceReviewResponse,
+  MaintenanceProposal,
+  MaintenanceProposalListResponse,
+  NewVersionRequest,
+  OverviewStats,
+  SkillReleaseRecord,
+  SkillRollbackRecord,
+  SkillCreateRequest,
+  SkillFull,
+  SkillGraphProjectionData,
+  SkillSearchResult,
+  SkillState,
+  SkillSummary,
+  SkillType,
+  SkillUpdateRequest,
+  SnapshotCommitRequest,
+  SnapshotCommitResponse,
+  SnapshotDiffRequest,
+  SnapshotDiffResponse,
+  SnapshotHistoryResponse,
+  SystemHealth,
+} from './types'
+
+const http = axios.create({ baseURL: '/api/v1' })
+
+// ── Skills ────────────────────────────────────────────────────────────────────
+
+export const skillsApi = {
+  list: (params?: { state?: SkillState; skill_type?: SkillType; limit?: number; offset?: number }) =>
+    http.get<SkillSummary[]>('/skills', { params }).then(r => r.data),
+
+  get: (id: string) =>
+    http.get<SkillSummary>(`/skills/${id}`).then(r => r.data),
+
+  getFull: (id: string) =>
+    http.get<SkillFull>(`/skills/${id}/full`).then(r => r.data),
+
+  create: (request: SkillCreateRequest) =>
+    http.post<SkillSummary>('/skills', request).then(r => r.data),
+
+  update: (id: string, request: SkillUpdateRequest) =>
+    http.patch<SkillSummary>(`/skills/${id}`, request).then(r => r.data),
+
+  search: (query: string, limit = 20) =>
+    http.post<SkillSearchResult[]>('/skills/search', { query, limit }).then(r => r.data),
+
+  versions: (id: string) =>
+    http.get<SkillSummary[]>(`/skills/${id}/versions`).then(r => r.data),
+
+  delete: (id: string) =>
+    http.delete(`/skills/${id}`).then(r => r.data),
+}
+
+// ── Lifecycle ─────────────────────────────────────────────────────────────────
+
+export const lifecycleApi = {
+  release: (id: string) =>
+    http.post<SkillSummary>(`/lifecycle/${id}/release`).then(r => r.data),
+
+  deprecate: (id: string, reason: string) =>
+    http.post<SkillSummary>(`/lifecycle/${id}/deprecate`, { reason }).then(r => r.data),
+
+  transition: (id: string, new_state: SkillState, reason = '') =>
+    http.post<SkillSummary>(`/lifecycle/${id}/transition`, { new_state, reason }).then(r => r.data),
+
+  review: (id: string) =>
+    http.post(`/lifecycle/${id}/review`).then(r => r.data),
+
+  reviewAndRelease: (id: string) =>
+    http.post<SkillSummary>(`/lifecycle/${id}/review-and-release`).then(r => r.data),
+
+  newVersion: (
+    id: string,
+    requestOrBump: NewVersionRequest | 'major' | 'minor' | 'patch' = 'patch',
+  ) => {
+    const request = typeof requestOrBump === 'string' ? { bump: requestOrBump } : requestOrBump
+    return http.post<SkillSummary>(`/lifecycle/${id}/new-version`, request).then(r => r.data)
+  },
+
+  getDiff: (id: string, compare_to?: string) =>
+    http.get<Record<string, unknown>>(`/lifecycle/${id}/diff`, { params: compare_to ? { compare_to } : {} }).then(r => r.data),
+
+  createSnapshot: (id: string, request: SnapshotCommitRequest = {}) =>
+    http.post<SnapshotCommitResponse>(`/lifecycle/${id}/snapshot`, request).then(r => r.data),
+
+  snapshotHistory: (id: string, max_count = 20) =>
+    http.get<SnapshotHistoryResponse>(`/lifecycle/${id}/snapshot/history`, { params: { max_count } }).then(r => r.data),
+
+  snapshotDiff: (id: string, request: SnapshotDiffRequest) =>
+    http.get<SnapshotDiffResponse>(`/lifecycle/${id}/snapshot/diff`, { params: request }).then(r => r.data),
+
+  releaseTag: (id: string, ref = 'HEAD') =>
+    http.post<SkillReleaseRecord>(`/lifecycle/${id}/release-tag`, { ref }).then(r => r.data),
+
+  restoreSnapshot: (id: string, source_ref: string) =>
+    http.post<SkillRollbackRecord>(`/lifecycle/${id}/rollback`, { source_ref }).then(r => r.data),
+
+  proposeMaintenanceChange: (id: string, request: MaintenanceReviewRequest) =>
+    http.post<MaintenanceReviewResponse>(`/lifecycle/${id}/propose-maintenance-change`, request).then(r => r.data),
+}
+
+// ── Graph ─────────────────────────────────────────────────────────────────────
+
+export const graphApi = {
+  full: (limit = 200) =>
+    http.get<GraphData>('/graph', { params: { limit } }).then(r => r.data),
+
+  subgraph: (skill_id: string, depth = 2) =>
+    http.post<GraphData>('/graph/subgraph', { skill_id, depth }).then(r => r.data),
+
+  heterogeneous: () =>
+    http.get<HeterogeneousGraphData>('/graph/heterogeneous').then(r => r.data),
+
+  skillOnlyProjection: () =>
+    http.get<SkillGraphProjectionData>('/graph/projection/skill-only').then(r => r.data),
+
+  stats: () =>
+    http.get<Record<string, unknown>>('/graph/stats/overview').then(r => r.data),
+
+  view: (view: GraphViewMode, limit = 300) =>
+    http.get<GraphViewData>('/graph/view', { params: { view, limit } }).then(r => r.data),
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+export const executionApi = {
+  executeSkill: (skill_id: string, inputs: Record<string, unknown> = {}) =>
+    http.post<ExecutionResult>('/execution/skill', { skill_id, inputs }).then(r => r.data),
+
+  executePlan: (goal: string, context: Record<string, unknown> = {}) =>
+    http.post<ExecutionResult>('/execution/plan', { goal, context }).then(r => r.data),
+
+  getState: () =>
+    http.get<Record<string, unknown>>('/execution/state').then(r => r.data),
+
+  resetState: () =>
+    http.delete('/execution/state').then(r => r.data),
+
+  history: () =>
+    http.get<ExecutionHistoryItem[]>('/execution/history').then(r => r.data),
+
+  experience: (execution_id: string) =>
+    http.get<ExecutionExperienceUnit>(`/execution/history/${execution_id}/experience`).then(r => r.data),
+}
+
+// ── Evolution ─────────────────────────────────────────────────────────────────
+
+export const harnessApi = {
+  runVerifyLoop: (skill_id: string, request: HarnessVerifyLoopRequest = {}) =>
+    http.post<HarnessVerifyLoopResponse>(`/harness/${skill_id}/verify-loop`, request).then(r => r.data),
+
+  list: (limit = 20) =>
+    http.get<HarnessLoopListResponse>('/harness', { params: { limit } }).then(r => r.data),
+
+  get: (loop_id: string) =>
+    http.get<Record<string, unknown>>(`/harness/${loop_id}`).then(r => r.data),
+}
+
+export const evolutionApi = {
+  systemHealth: () =>
+    http.get<SystemHealth>('/evolution/health').then(r => r.data),
+
+  skillHealth: (id: string) =>
+    http.get<HealthReport>(`/evolution/health/${id}`).then(r => r.data),
+
+  repair: (id: string) =>
+    http.post(`/evolution/repair/${id}`).then(r => r.data),
+
+  runCycle: () =>
+    http.post('/evolution/cycle').then(r => r.data),
+
+  proposals: (status?: MaintenanceProposal['status']) =>
+    http.get<MaintenanceProposalListResponse>('/evolution/proposals', { params: status ? { status } : {} }).then(r => r.data),
+
+  acceptProposal: (id: string) =>
+    http.post<MaintenanceProposal>(`/evolution/proposals/${id}/accept`).then(r => r.data),
+
+  rejectProposal: (id: string) =>
+    http.post<MaintenanceProposal>(`/evolution/proposals/${id}/reject`).then(r => r.data),
+}
+
+// ── Ingest ────────────────────────────────────────────────────────────────────
+
+export const ingestApi = {
+  parse: (source_type: string, content: string) =>
+    http.post<IngestResponse>('/ingest/parse', { source_type, content }).then(r => r.data),
+
+  parseAndCreate: (source_type: string, content: string) =>
+    http.post<IngestResponse>('/ingest/parse-and-create', { source_type, content }).then(r => r.data),
+
+  auditCandidate: (request: CandidateSkillReviewRequest) =>
+    http.post<CandidateAuditResult>('/ingest/audit-candidate', request).then(r => r.data),
+
+  createCandidate: (request: CandidateSkillReviewRequest) =>
+    http.post<CandidateCreateResponse>('/ingest/create-candidate', request).then(r => r.data),
+}
+
+// ── Stats ─────────────────────────────────────────────────────────────────────
+
+export const evaluationApi = {
+  dashboard: () =>
+    http.get<EvaluationDashboardResponse>('/evaluation/dashboard').then(r => r.data),
+}
+
+export interface EvolutionStats {
+  total_skills: number
+  auto_generated: number
+  manual: number
+  avg_reuse_rate: number
+  avg_success_rate: number
+  version_improved_count: number
+  skills_by_category: Record<string, number>
+  recent_activity: {
+    skill_id: string
+    name: string
+    event: string
+    state: string
+    time: string
+  }[]
+}
+
+export const statsApi = {
+  overview: async (): Promise<OverviewStats> => {
+    await Promise.all([
+      skillsApi.list({ limit: 1 }),
+      evolutionApi.systemHealth().catch(() => null),
+    ])
+    const allSkills = await skillsApi.list({ limit: 200 })
+    const byState: Record<string, number> = {}
+    const byType: Record<string, number> = {}
+    let totalExec = 0
+    let successRateSum = 0
+    let ratedCount = 0
+    for (const s of allSkills) {
+      byState[s.state] = (byState[s.state] || 0) + 1
+      byType[s.skill_type] = (byType[s.skill_type] || 0) + 1
+      totalExec += s.metrics.total_executions
+      if (s.metrics.total_executions >= 5) {
+        successRateSum += s.metrics.success_rate
+        ratedCount++
+      }
+    }
+    return {
+      total_skills: allSkills.length,
+      by_state: byState,
+      by_type: byType,
+      total_executions: totalExec,
+      avg_success_rate: ratedCount > 0 ? successRateSum / ratedCount : 1,
+      graph_stats: {},
+    }
+  },
+
+  evolutionStats: () =>
+    http.get<EvolutionStats>('/skills/evolution-stats').then(r => r.data),
+}

skillwiki-frontend/src/api/errors.ts

@@ -0,0 +1,46 @@
+import axios from 'axios'
+
+type ErrorPayload = {
+  detail?: unknown
+  error?: unknown
+  message?: unknown
+}
+
+function stringifyDetail(detail: unknown): string | null {
+  if (!detail) return null
+  if (typeof detail === 'string') return detail
+  if (Array.isArray(detail)) {
+    return detail
+      .map(item => {
+        if (typeof item === 'string') return item
+        if (item && typeof item === 'object' && 'msg' in item) {
+          return String((item as { msg: unknown }).msg)
+        }
+        return JSON.stringify(item)
+      })
+      .filter(Boolean)
+      .join('; ')
+  }
+  if (typeof detail === 'object') return JSON.stringify(detail)
+  return String(detail)
+}
+
+export function getApiErrorMessage(error: unknown, fallback = 'Request failed'): string {
+  if (axios.isAxiosError(error)) {
+    const data = error.response?.data as ErrorPayload | string | undefined
+    if (typeof data === 'string' && data.trim()) return data
+    if (data && typeof data === 'object') {
+      return (
+        stringifyDetail(data.detail) ||
+        stringifyDetail(data.error) ||
+        stringifyDetail(data.message) ||
+        error.message ||
+        fallback
+      )
+    }
+    return error.message || fallback
+  }
+
+  if (error instanceof Error) return error.message || fallback
+  return fallback
+}

skillwiki-frontend/src/api/types.ts

@@ -0,0 +1,744 @@
+// SkillWiki API type definitions
+
+export type SkillType = 'atomic' | 'functional' | 'strategic'
+export type SkillState = 'S0' | 'S1' | 'S2' | 'S3' | 'S4' | 'S5' | 'S6' | 'S7'
+
+export const STATE_LABELS: Record<SkillState, string> = {
+  S0: 'Raw Experience',
+  S1: 'Candidate',
+  S2: 'Draft',
+  S3: 'Verified',
+  S4: 'Released',
+  S5: 'Degraded',
+  S6: 'Deprecated',
+  S7: 'Archived',
+}
+
+export interface SkillParameter {
+  name: string
+  type: string
+  description: string
+  required: boolean
+  default?: unknown
+}
+
+export interface SkillInterface {
+  inputs?: SkillParameter[]
+  outputs?: SkillParameter[]
+  input_schema?: {
+    type?: string
+    properties?: Record<string, {
+      type?: string
+      description?: string
+      default?: unknown
+    }>
+    required?: string[]
+  }
+  output_schema?: {
+    type?: string
+    properties?: Record<string, {
+      type?: string
+      description?: string
+      default?: unknown
+    }>
+    required?: string[]
+  }
+  preconditions: string[]
+  postconditions: string[]
+}
+
+export interface SkillImplementation {
+  language: string
+  code?: string
+  prompt_template?: string
+  tool_calls?: string[]
+  sub_skill_ids?: string[]
+}
+
+export interface SkillMetrics {
+  usage_count: number
+  success_count: number
+  failure_count: number
+  avg_latency_ms: number
+  p95_latency_ms: number
+  last_used_at?: string
+  // computed fields (serialized by backend)
+  total_executions: number
+  successful_executions: number
+  failed_executions: number
+  success_rate: number
+}
+
+export interface SkillEvaluation {
+  verifier_specs: Record<string, unknown>[]
+  test_case_refs: string[]
+  benchmark_task_ids: string[]
+  validation_summary?: string | null
+  harness_validation?: Record<string, unknown>
+}
+
+export interface SkillProvenance {
+  source_type: string
+  source_ids: string[]
+  parent_skill_ids: string[]
+  created_by_agent?: string | null
+  creation_context: Record<string, unknown>
+}
+
+export interface SkillCreateRequest {
+  name: string
+  description: string
+  skill_type: SkillType
+  state?: SkillState
+  tags?: string[]
+  interface: SkillInterface
+  implementation?: SkillImplementation
+  evaluation?: SkillEvaluation
+  provenance?: SkillProvenance
+  author?: string
+}
+
+export interface SkillUpdateRequest {
+  description?: string
+  tags?: string[]
+  interface?: SkillInterface
+  implementation?: SkillImplementation
+  evaluation?: SkillEvaluation
+  author?: string
+}
+
+export interface NewVersionRequest {
+  bump?: 'major' | 'minor' | 'patch'
+  description?: string | null
+  tags?: string[] | null
+  interface?: SkillInterface | null
+  implementation?: SkillImplementation | null
+  evaluation?: SkillEvaluation | null
+  test_cases?: Record<string, unknown>[] | null
+  metadata?: Record<string, unknown> | null
+  author?: string
+}
+
+export interface SkillSummary {
+  skill_id: string
+  name: string
+  description: string
+  skill_type: SkillType
+  state: SkillState
+  tags: string[]
+  version: string
+  granularity_level: number
+  evaluation: SkillEvaluation
+  metrics: SkillMetrics
+  created_at: string
+  updated_at: string
+}
+
+export interface SkillFull extends SkillSummary {
+  interface: SkillInterface
+  implementation?: SkillImplementation
+  provenance?: SkillProvenance | null
+}
+
+export interface ExperienceUnit {
+  unit_id: string
+  source_type: string
+  raw_content: string
+  extracted_actions: string[]
+  normalized_actions: Record<string, unknown>[]
+  summary: string
+  proposed_skill_name?: string
+  proposed_description?: string
+  proposed_type?: string
+  confidence: number
+  index_keywords: string[]
+  index_embedding_hint: string
+  metadata?: Record<string, unknown>
+}
+
+export interface CreatedSkill {
+  skill_id: string
+  name: string
+  skill_type: string
+  state: string
+  version: string
+}
+
+export interface IngestResponse {
+  success: boolean
+  source_type: string
+  unit_count: number
+  token_usage: number
+  errors: string[]
+  units: ExperienceUnit[]
+  created_skills?: CreatedSkill[]
+}
+
+export interface CandidateSkillReviewRequest {
+  source_type: string
+  unit_id: string
+  raw_content?: string
+  name: string
+  description: string
+  skill_type: SkillType
+  tags: string[]
+  input_schema: Record<string, unknown>
+  output_schema: Record<string, unknown>
+  preconditions: string[]
+  postconditions: string[]
+  prompt_template: string
+  provenance?: SkillProvenance | null
+  evaluation: SkillEvaluation
+  dependency_ids?: string[]
+  component_ids?: string[]
+  sub_skill_ids?: string[]
+  parent_skill_ids?: string[]
+  tool_calls?: string[]
+  author?: string
+}
+
+export interface CandidateAuditResult {
+  skill_id: string
+  skill_name: string
+  passed: boolean
+  schema_ok: boolean
+  safety_ok: boolean
+  postcondition_ok: boolean
+  issues: string[]
+  warnings: string[]
+  recommendations: string[]
+  audit_score: number
+}
+
+export interface CandidateCreateResponse {
+  success: boolean
+  created_skill: CreatedSkill
+  audit: CandidateAuditResult
+}
+
+export interface EvaluationModeTotal {
+  success?: number
+  total?: number
+  success_rate?: number
+  functional_failure?: number
+  api_failure?: number
+  skipped?: number
+  success_rate_excluding_api_failures?: number
+}
+
+export interface EvaluationDemoRow {
+  task_id: string
+  domain?: string
+  no_skill?: string
+  raw_prompt?: string
+  with_skill?: string
+  winner?: string
+  failure_reason?: string
+  no_skill_latency_ms?: number | null
+  raw_prompt_latency_ms?: number | null
+  with_skill_latency_ms?: number | null
+  no_skill_verifier_passed?: boolean | null
+  raw_prompt_verifier_passed?: boolean | null
+  with_skill_verifier_passed?: boolean | null
+}
+
+export interface EvaluationArtifactBase {
+  available: boolean
+  source_file: string
+  generated_at?: string | null
+  updated_at?: string | null
+  error?: string | null
+}
+
+export interface EvaluationDemoBenchmark extends EvaluationArtifactBase {
+  task_count: number
+  mode_totals: Record<string, EvaluationModeTotal>
+  rows: EvaluationDemoRow[]
+  raw_result_file?: string | null
+}
+
+export interface EvaluationSearchRow {
+  query_id?: string
+  query?: string
+  domain?: string
+  expected_skill_ids: string[]
+  lexical_top_skill?: string | null
+  hybrid_top_skill?: string | null
+  lexical_best_rank?: number | null
+  hybrid_best_rank?: number | null
+  lexical_top1_hit?: boolean | null
+  hybrid_top1_hit?: boolean | null
+  hybrid_topk_hit?: boolean | null
+}
+
+export interface EvaluationSearchEval extends EvaluationArtifactBase {
+  benchmark?: string | null
+  schema_version?: string | null
+  query_count: number
+  summary: Record<string, unknown>
+  comparison: Record<string, unknown>
+  rows: EvaluationSearchRow[]
+}
+
+export interface EvaluationLlmRow {
+  task_id?: string
+  fallback_status?: string
+  fallback_selected?: string[]
+  fallback_failure_reason?: string
+  llm_status?: string
+  llm_selected?: string[]
+  llm_api_error_type?: string
+  llm_failure_reason?: string
+  winner?: string
+}
+
+export interface EvaluationLlmPlanner extends EvaluationArtifactBase {
+  benchmark?: string | null
+  task_count: number
+  mode_totals: Record<string, EvaluationModeTotal>
+  rows: EvaluationLlmRow[]
+}
+
+export interface EvaluationDashboardResponse {
+  generated_at: string
+  results_dir_present: boolean
+  warnings: string[]
+  artifacts: {
+    demo_benchmark: EvaluationDemoBenchmark
+    search_eval: EvaluationSearchEval
+    llm_planner: EvaluationLlmPlanner
+  }
+}
+
+export interface SkillSearchResult {
+  skill_id: string
+  name: string
+  description: string
+  skill_type: SkillType
+  state: SkillState
+  tags: string[]
+  version: string
+  score: number
+  match_reason: string
+}
+
+export interface GraphNodeData {
+  id: string
+  name: string
+  skill_type: string
+  state: string
+  tags: string[]
+  version: string
+  granularity_level: number
+  success_rate: number
+  usage_count: number
+  kind?: string
+  description?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface GraphEdgeData {
+  id: string
+  source: string
+  target: string
+  edge_type: string
+  weight: number
+  confidence?: number
+  metadata?: Record<string, unknown>
+}
+
+export interface GraphData {
+  nodes: GraphNodeData[]
+  edges: GraphEdgeData[]
+  stats: Record<string, unknown>
+}
+
+export type GraphViewMode = 'skill_only' | 'provenance' | 'version_impact'
+
+export interface SkillGraphProjectionEdgeData extends GraphEdgeData {
+  confidence: number
+  metadata: Record<string, unknown>
+}
+
+export interface SkillGraphProjectionData {
+  nodes: GraphNodeData[]
+  edges: SkillGraphProjectionEdgeData[]
+  metadata: Record<string, unknown>
+  validation_evidence: Record<string, Record<string, unknown>[]>
+  stats: Record<string, unknown>
+}
+
+export interface HeterogeneousGraphNodeData {
+  id: string
+  kind: string
+  name: string
+  description: string
+  metadata: Record<string, unknown>
+}
+
+export interface HeterogeneousGraphEdgeData {
+  id: string
+  source: string
+  target: string
+  edge_type: string
+  weight: number
+  metadata: Record<string, unknown>
+}
+
+export interface HeterogeneousGraphData {
+  nodes: HeterogeneousGraphNodeData[]
+  edges: HeterogeneousGraphEdgeData[]
+  stats: Record<string, unknown>
+}
+
+export interface GraphViewNodeData {
+  id: string
+  name: string
+  kind: string
+  description?: string
+  skill_type?: string | null
+  state?: string | null
+  tags: string[]
+  version?: string | null
+  granularity_level?: number | null
+  success_rate?: number | null
+  usage_count?: number | null
+  metadata: Record<string, unknown>
+}
+
+export interface GraphViewEdgeData {
+  id: string
+  source: string
+  target: string
+  edge_type: string
+  weight: number
+  confidence?: number | null
+  metadata: Record<string, unknown>
+}
+
+export interface GraphViewData {
+  view: GraphViewMode
+  source_endpoint: string
+  nodes: GraphViewNodeData[]
+  edges: GraphViewEdgeData[]
+  stats: Record<string, unknown>
+  metadata: Record<string, unknown>
+  validation_evidence: Record<string, Record<string, unknown>[]>
+}
+
+export interface MaintenanceProposal {
+  proposal_id: string
+  skill_id: string
+  trigger: string
+  recommended_action: string
+  evidence: string[]
+  root_cause?: string
+  patch_hint: string
+  feedback_sources?: string[]
+  targets_to_fix?: string[]
+  invariants_to_preserve?: string[]
+  validation_plan?: string[]
+  validation_status?: 'untested' | 'repaired' | 'verified' | 'failed' | 'merged' | 'deprioritized'
+  attempt_count?: number
+  max_attempts?: number
+  reviewer_notes?: string
+  confidence: number
+  requires_human_review: boolean
+  status: 'pending' | 'accepted' | 'rejected' | 'superseded'
+  source: string
+  metadata: Record<string, unknown>
+  created_at: string
+  updated_at: string
+  next_action?: MaintenanceProposalNextAction | null
+}
+
+export interface MaintenanceProposalNextAction {
+  action: string
+  method: string
+  endpoint: string
+  required_payload_fields: string[]
+  reason: string
+}
+
+export interface MaintenanceProposalListResponse {
+  proposals: MaintenanceProposal[]
+  total: number
+  pending_count: number
+}
+
+export interface StructuredDiffEntry {
+  field_path?: string
+  field?: string
+  change_type?: string
+  type?: string
+  old_value?: unknown
+  new_value?: unknown
+  category?: string
+  is_breaking?: boolean
+  review_recommendation?: string
+  [key: string]: unknown
+}
+
+export interface BusinessDiffEntry {
+  field: string
+  change_type: string
+  category: string
+  old_value?: unknown
+  new_value?: unknown
+  is_breaking?: boolean
+}
+
+export interface BusinessDiffSummary {
+  changed_fields: number
+  breaking: boolean
+  categories: string[]
+  suggested_bump: 'major' | 'minor' | 'patch'
+  summary: string
+}
+
+export interface MaintenanceReviewRequest {
+  proposal_id: string
+  patched_skill: Record<string, unknown>
+  reason?: string
+  author?: string
+}
+
+export interface MaintenanceReviewResponse {
+  skill_id: string
+  proposal_id: string
+  branch_name: string
+  base_commit: string
+  head_commit: string
+  snapshot_path: string
+  structured_diff: StructuredDiffEntry[]
+  has_breaking_changes: boolean
+  review_status: string
+  reason: string
+  author: string
+}
+
+export interface SnapshotCommitRequest {
+  author?: string
+  message?: string | null
+}
+
+export interface SnapshotCommitResponse {
+  skill_id: string
+  skill_name: string
+  version: string
+  snapshot_path: string
+  commit: string
+  message: string
+}
+
+export interface SnapshotHistoryItem {
+  commit_hash: string
+  author: string
+  authored_at: string
+  subject: string
+  changed_paths: string[]
+}
+
+export interface SnapshotHistoryResponse {
+  skill_id: string
+  snapshot_path: string
+  history: SnapshotHistoryItem[]
+}
+
+export interface SnapshotDiffRequest {
+  from_ref: string
+  to_ref?: string
+  from_version?: string
+  to_version?: string
+}
+
+export interface SnapshotDiffResponse {
+  skill_id: string
+  snapshot_path: string
+  from_snapshot_path?: string | null
+  to_snapshot_path?: string | null
+  from_ref: string
+  to_ref: string
+  raw_diff: string
+  diffs: StructuredDiffEntry[]
+  has_breaking_changes: boolean
+  review_recommendation: string
+}
+
+export interface SkillReleaseRecord {
+  tag_name: string
+  commit: string
+  snapshot_path: string
+  skill_id: string
+  skill_name: string
+  version: string
+}
+
+export interface SkillRollbackRecord {
+  source_ref: string
+  restore_commit: string
+  restored_snapshot_path: string
+  commit_message: string
+  skill_id: string
+  skill_name: string
+  version: string
+}
+
+export interface HealthReport {
+  skill_id: string
+  skill_name: string
+  status: 'healthy' | 'degraded' | 'critical' | 'stale' | 'unknown'
+  success_rate: number
+  usage_count: number
+  avg_latency_ms: number
+  issues: string[]
+  recommendations: string[]
+  maintenance_proposal?: MaintenanceProposal | null
+}
+
+export interface SystemHealth {
+  total_skills: number
+  healthy_count: number
+  degraded_count: number
+  critical_count: number
+  stale_count: number
+  health_ratio: number
+  skill_reports: HealthReport[]
+}
+
+export interface ExecutionStepResult {
+  step_id: string
+  step_index: number
+  skill_id: string
+  skill_name: string
+  status: string
+  input_mapping?: Record<string, unknown>
+  outputs?: Record<string, unknown>
+  result?: Record<string, unknown> | null
+  error?: string | null
+  latency_ms?: number | null
+}
+
+export interface RetrievedSkill {
+  skill_id: string
+  name: string
+  description: string
+  skill_type: string
+  score: number
+  match_reason: string
+}
+
+export interface ExecutionExperienceUnit {
+  unit_id: string
+  source_type: 'agent_execution' | string
+  source_execution_id: string
+  raw_content: string
+  extracted_actions: string[]
+  normalized_actions: Record<string, unknown>[]
+  summary: string
+  proposed_skill_name?: string | null
+  proposed_description?: string | null
+  proposed_type?: string | null
+  confidence: number
+  index_keywords: string[]
+  index_embedding_hint: string
+  metadata: Record<string, unknown>
+}
+
+export interface ExecutionResult {
+  plan_id: string
+  goal: string
+  status: string
+  steps: ExecutionStepResult[]
+  total_latency_ms: number
+  final_state: Record<string, unknown>
+  retrieved_skills: RetrievedSkill[]
+  experience_recorded: boolean
+  experience_unit?: ExecutionExperienceUnit | null
+  suggested_skill?: Record<string, unknown>
+  verifier_passed?: boolean | null
+  verifier_summary?: Record<string, unknown> | null
+}
+
+export interface ExecutionHistoryItem {
+  execution_id: string
+  goal: string
+  status: string
+  step_count: number
+  success_count: number
+  total_latency_ms: number
+  retrieved_skill_count: number
+  created_at: string
+  experience_unit_id?: string | null
+  experience_source_type?: string | null
+}
+
+export type HarnessKind = 'local_skillos' | 'codex_cli' | 'claude_code'
+
+export interface HarnessTestCase {
+  test_id: string
+  name: string
+  goal: string
+  input_data: Record<string, unknown>
+  context?: Record<string, unknown>
+  verifier_specs: Record<string, unknown>[]
+  timeout_s?: number
+  expected_artifacts?: string[]
+}
+
+export interface HarnessRunResult {
+  run_id: string
+  skill_id: string
+  attempt: number
+  harness: HarnessKind
+  status: string
+  input_data: Record<string, unknown>
+  output: Record<string, unknown>
+  stdout: string
+  stderr: string
+  artifacts: Record<string, unknown>[]
+  verifier_passed: boolean
+  verifier_summary: Record<string, unknown>
+  latency_ms: number
+  cost_estimate: Record<string, unknown>
+  failure_reason: string
+  evidence_path: string
+}
+
+export interface HarnessVerifyLoopRequest {
+  harness?: HarnessKind
+  max_attempts?: number
+  promote_on_pass?: boolean
+  test_cases?: HarnessTestCase[]
+  allow_repair?: boolean
+  timeout_s?: number
+}
+
+export interface HarnessVerifyLoopResponse {
+  loop_id: string
+  skill_id: string
+  status: string
+  promotion_allowed: boolean
+  attempt_count: number
+  score: Record<string, unknown>
+  attempts: HarnessRunResult[]
+  repairs: Record<string, unknown>[]
+  initial_version: string
+  final_version: string
+  final_state: SkillState | string
+  evidence_path: string
+}
+
+export interface HarnessLoopListResponse {
+  loops: HarnessVerifyLoopResponse[]
+  total: number
+}
+
+export interface OverviewStats {
+  total_skills: number
+  by_state: Record<string, number>
+  by_type: Record<string, number>
+  total_executions: number
+  avg_success_rate: number
+  graph_stats: Record<string, unknown>
+}

skillwiki-frontend/src/components/AppLayout.tsx

@@ -0,0 +1,208 @@
+import { useState } from 'react'
+import { Layout, Menu, Switch, Badge, Tooltip, Avatar, Tag, Grid, Button } from 'antd'
+import {
+  DashboardOutlined,
+  BookOutlined,
+  ApartmentOutlined,
+  PlayCircleOutlined,
+  SyncOutlined,
+  ExperimentOutlined,
+  CloudUploadOutlined,
+  BranchesOutlined,
+  BulbOutlined,
+  BulbFilled,
+  WifiOutlined,
+  RocketOutlined,
+  BarChartOutlined,
+  SafetyCertificateOutlined,
+  TranslationOutlined,
+} from '@ant-design/icons'
+import { useNavigate, useLocation } from 'react-router-dom'
+import { motion } from 'framer-motion'
+import { useAppStore } from '@/store/appStore'
+import { useWebSocket } from '@/hooks/useWebSocket'
+import { useT } from '@/i18n'
+
+const { Header, Sider, Content } = Layout
+const { useBreakpoint } = Grid
+
+export default function AppLayout({ children }: { children: React.ReactNode }) {
+  const [collapsed, setCollapsed] = useState(false)
+  const screens = useBreakpoint()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { darkMode, toggleDark, wsEvents, lang, setLang } = useAppStore()
+  const t = useT(lang)
+  useWebSocket()
+
+  const isNarrow = screens.xs && !screens.md
+  const siderCollapsed = isNarrow ? true : collapsed
+  const unreadEvents = wsEvents.filter(e => e.type !== 'pong' && e.type !== 'connected').length
+
+  const menuItems = [
+    {
+      type: 'group' as const,
+      label: t.groupOverview,
+      children: [
+        { key: '/', icon: <DashboardOutlined />, label: t.menuDashboard },
+        { key: '/evaluation', icon: <BarChartOutlined />, label: t.menuEvaluation },
+      ],
+    },
+    {
+      type: 'group' as const,
+      label: t.groupSkillMgmt,
+      children: [
+        { key: '/ingest', icon: <CloudUploadOutlined />, label: t.menuIngest },
+        { key: '/wiki', icon: <BookOutlined />, label: t.menuWiki },
+        { key: '/graph', icon: <ApartmentOutlined />, label: t.menuGraph },
+        { key: '/lifecycle', icon: <ExperimentOutlined />, label: t.menuLifecycle },
+        { key: '/versions', icon: <BranchesOutlined />, label: t.menuVersions },
+      ],
+    },
+    {
+      type: 'group' as const,
+      label: t.groupAgentEvolution,
+      children: [
+        { key: '/harness', icon: <SafetyCertificateOutlined />, label: t.menuHarness },
+        { key: '/execution', icon: <PlayCircleOutlined />, label: t.menuExecution },
+        { key: '/evolution', icon: <SyncOutlined />, label: t.menuEvolution },
+        {
+          key: '/demo',
+          icon: <RocketOutlined />,
+          label: (
+            <span style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+              {t.menuDemo}
+              <Tag color="red" style={{ fontSize: 10, padding: '0 4px', lineHeight: '16px', marginLeft: 2 }}>DEMO</Tag>
+            </span>
+          ),
+        },
+      ],
+    },
+  ]
+
+  return (
+    <Layout style={{ minHeight: '100vh' }}>
+      <Sider
+        collapsible
+        collapsed={siderCollapsed}
+        onCollapse={setCollapsed}
+        collapsedWidth={isNarrow ? 64 : 80}
+        width={isNarrow ? 64 : 200}
+        theme={darkMode ? 'dark' : 'light'}
+        style={{
+          boxShadow: '2px 0 8px rgba(0,0,0,0.08)',
+          zIndex: 10,
+        }}
+      >
+        <motion.div
+          style={{
+            height: 64,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '0 16px',
+            borderBottom: '1px solid rgba(0,0,0,0.06)',
+          }}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+        >
+          {!siderCollapsed ? (
+            <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+              <Avatar
+                style={{ background: 'linear-gradient(135deg, #1677ff, #722ed1)', flexShrink: 0 }}
+                size={32}
+              >
+                S
+              </Avatar>
+              <span style={{ fontWeight: 800, fontSize: 16, color: darkMode ? '#fff' : '#1677ff', whiteSpace: 'nowrap' }}>
+                SkillWiki
+              </span>
+            </div>
+          ) : (
+            <Avatar style={{ background: 'linear-gradient(135deg, #1677ff, #722ed1)' }} size={32}>S</Avatar>
+          )}
+        </motion.div>
+
+        <Menu
+          theme={darkMode ? 'dark' : 'light'}
+          mode="inline"
+          selectedKeys={[location.pathname]}
+          items={menuItems}
+          onClick={({ key }) => navigate(key)}
+          inlineCollapsed={siderCollapsed}
+          style={{ borderRight: 0, marginTop: 8 }}
+        />
+      </Sider>
+
+      <Layout>
+        <Header
+          style={{
+            background: darkMode ? '#141414' : '#fff',
+            padding: isNarrow ? '0 12px' : '0 24px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 12,
+            boxShadow: '0 1px 4px rgba(0,0,0,0.08)',
+            zIndex: 9,
+          }}
+        >
+          <div
+            style={{
+              fontWeight: 600,
+              color: darkMode ? '#fff' : '#333',
+              minWidth: 0,
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {isNarrow ? t.appTitleShort : t.appTitle}
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            <Tooltip title={`${unreadEvents} ${t.liveEvents}`}>
+              <Badge count={Math.min(unreadEvents, 99)} size="small">
+                <WifiOutlined style={{ fontSize: 18, color: '#52c41a', cursor: 'pointer' }} />
+              </Badge>
+            </Tooltip>
+            <Tooltip title={darkMode ? t.switchLight : t.switchDark}>
+              <Switch
+                checked={darkMode}
+                onChange={toggleDark}
+                checkedChildren={<BulbFilled />}
+                unCheckedChildren={<BulbOutlined />}
+              />
+            </Tooltip>
+            <Tooltip title={t.langToggle}>
+              <Button
+                size="small"
+                icon={<TranslationOutlined />}
+                onClick={() => setLang(lang === 'en' ? 'zh' : 'en')}
+                style={{ fontWeight: 600, minWidth: 56 }}
+              >
+                {t.langToggle}
+              </Button>
+            </Tooltip>
+          </div>
+        </Header>
+
+        <Content
+          style={{
+            background: darkMode ? '#1f1f1f' : '#f5f7fa',
+            overflow: 'auto',
+            minHeight: 'calc(100vh - 64px)',
+          }}
+        >
+          <motion.div
+            key={location.pathname}
+            initial={{ opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ duration: 0.2 }}
+          >
+            {children}
+          </motion.div>
+        </Content>
+      </Layout>
+    </Layout>
+  )
+}

skillwiki-frontend/src/hooks/useWebSocket.ts

@@ -0,0 +1,64 @@
+import { useEffect, useRef } from 'react'
+import { useAppStore } from '@/store/appStore'
+import type { WsEvent } from '@/store/appStore'
+
+type RawWsMessage = {
+  type?: unknown
+  payload?: unknown
+  timestamp?: unknown
+  event?: unknown
+  data?: unknown
+}
+
+function normalizeWsMessage(raw: RawWsMessage): WsEvent | null {
+  const type = typeof raw.type === 'string'
+    ? raw.type
+    : typeof raw.event === 'string'
+      ? raw.event
+      : ''
+
+  if (!type) return null
+
+  return {
+    type,
+    payload: 'payload' in raw ? raw.payload : raw.data,
+    timestamp: typeof raw.timestamp === 'string' ? raw.timestamp : new Date().toISOString(),
+  }
+}
+
+export function useWebSocket() {
+  const wsRef = useRef<WebSocket | null>(null)
+  const pushWsEvent = useAppStore(s => s.pushWsEvent)
+
+  useEffect(() => {
+    if (import.meta.env.VITE_SKILLOS_DISABLE_WS === '1') {
+      return
+    }
+
+    const protocol = window.location.protocol === 'https:' ? 'wss' : 'ws'
+    const ws = new WebSocket(`${protocol}://${window.location.host}/ws`)
+    wsRef.current = ws
+
+    ws.onmessage = (e) => {
+      try {
+        const msg = normalizeWsMessage(JSON.parse(e.data))
+        if (msg) pushWsEvent(msg)
+      } catch {
+        // ignore
+      }
+    }
+
+    const ping = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'ping' }))
+      }
+    }, 30_000)
+
+    return () => {
+      clearInterval(ping)
+      ws.close()
+    }
+  }, [pushWsEvent])
+
+  return wsRef
+}

skillwiki-frontend/src/i18n.ts

@@ -0,0 +1,52 @@
+import type { AppLang } from '@/store/appStore'
+
+export const T = {
+  en: {
+    appTitle: 'SkillWiki: A Living Knowledge Infrastructure for Agent Skills',
+    appTitleShort: 'SkillWiki',
+    groupOverview: 'Overview',
+    groupSkillMgmt: 'Skill Management',
+    groupAgentEvolution: 'Agent & Evolution',
+    menuDashboard: 'Dashboard',
+    menuEvaluation: 'Evaluation',
+    menuWiki: 'Skill Wiki',
+    menuGraph: 'Knowledge Graph',
+    menuVersions: 'Version Control',
+    menuLifecycle: 'Lifecycle',
+    menuDemo: 'Self-Evolution Demo',
+    menuExecution: 'Agent Execution',
+    menuHarness: 'Harness Verification',
+    menuEvolution: 'Evolution',
+    menuIngest: 'Knowledge Import',
+    liveEvents: 'live events',
+    switchDark: 'Switch to dark mode',
+    switchLight: 'Switch to light mode',
+    langToggle: 'ZH',
+  },
+  zh: {
+    appTitle: 'SkillWiki：面向智能体技能的活性知识基础设施',
+    appTitleShort: 'SkillWiki',
+    groupOverview: '总览',
+    groupSkillMgmt: '技能管理',
+    groupAgentEvolution: '智能体与演化',
+    menuDashboard: '仪表盘',
+    menuEvaluation: '评测',
+    menuWiki: '技能库',
+    menuGraph: '知识图谱',
+    menuVersions: '版本控制',
+    menuLifecycle: '生命周期',
+    menuDemo: '自进化演示',
+    menuExecution: '智能体执行',
+    menuHarness: '验证框架',
+    menuEvolution: '演化中心',
+    menuIngest: '知识导入',
+    liveEvents: '实时事件',
+    switchDark: '切换暗色模式',
+    switchLight: '切换亮色模式',
+    langToggle: 'English',
+  },
+} as const
+
+export function useT(lang: AppLang) {
+  return T[lang]
+}

skillwiki-frontend/src/index.css

@@ -0,0 +1,39 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: 'Inter', 'PingFang SC', 'Microsoft YaHei', -apple-system, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+#root {
+  width: 100%;
+  min-height: 100vh;
+}
+
+/* Scrollbar polish */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: rgba(0, 0, 0, 0.15);
+  border-radius: 3px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(0, 0, 0, 0.25);
+}
+
+/* Ant Design overrides */
+.ant-layout-sider-trigger {
+  border-top: 1px solid rgba(0, 0, 0, 0.06);
+}
+
+pre {
+  margin: 0;
+}

skillwiki-frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

skillwiki-frontend/src/pages/AgentExecution.tsx

@@ -0,0 +1,370 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+  Card, Input, Button, Tag, Alert, Spin,
+  Typography, Space, Statistic, Row, Col, Progress, Tooltip, Table, Empty,
+} from 'antd'
+import {
+  PlayCircleOutlined, ThunderboltOutlined, CheckCircleOutlined,
+  CloseCircleOutlined, SearchOutlined, DatabaseOutlined, ReloadOutlined,
+} from '@ant-design/icons'
+import { motion, AnimatePresence } from 'framer-motion'
+import { executionApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type { ExecutionHistoryItem, ExecutionResult, ExecutionStepResult, RetrievedSkill } from '@/api/types'
+
+const { TextArea } = Input
+const { Text } = Typography
+
+const STATUS_COLOR: Record<string, string> = {
+  success: '#52c41a',
+  failed: '#ff4d4f',
+  running: '#1677ff',
+  pending: '#d9d9d9',
+  skipped: '#faad14',
+}
+
+const SKILL_TYPE_COLOR: Record<string, string> = {
+  atomic: '#1677ff', functional: '#722ed1', strategic: '#faad14',
+}
+
+function formatHistoryTime(value: string) {
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString()
+}
+
+function StepCard({ step, index }: { step: ExecutionStepResult; index: number }) {
+  const [expanded, setExpanded] = useState(false)
+  const stepResult = step.result ?? {}
+  const latency = step.latency_ms ?? 0
+  return (
+    <motion.div
+      initial={{ opacity: 0, x: -20 }}
+      animate={{ opacity: 1, x: 0 }}
+      transition={{ delay: index * 0.1 }}
+    >
+      <Card
+        size="small"
+        style={{
+          marginBottom: 8,
+          borderLeft: `4px solid ${STATUS_COLOR[step.status] || '#d9d9d9'}`,
+          borderRadius: 8,
+        }}
+        onClick={() => setExpanded(!expanded)}
+        hoverable
+      >
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <Space>
+            {step.status === 'success'
+              ? <CheckCircleOutlined style={{ color: '#52c41a' }} />
+              : step.status === 'failed'
+                ? <CloseCircleOutlined style={{ color: '#ff4d4f' }} />
+                : <ThunderboltOutlined style={{ color: STATUS_COLOR[step.status] || '#d9d9d9' }} />}
+            <Text strong>{step.skill_name}</Text>
+            <Text type="secondary" style={{ fontSize: 12 }}>{step.skill_id.slice(0, 8)}...</Text>
+          </Space>
+          <Space>
+            <Tag color={STATUS_COLOR[step.status]}>{step.status}</Tag>
+            <Text type="secondary">{latency.toFixed(0)}ms</Text>
+          </Space>
+        </div>
+        {expanded && (
+          <div style={{ marginTop: 8 }}>
+            {step.error && <Alert type="error" title={step.error} style={{ marginBottom: 8 }} />}
+            {Object.keys(stepResult).length > 0 && (
+              <pre style={{ background: '#f5f5f5', padding: 8, borderRadius: 4, fontSize: 11, overflow: 'auto' }}>
+                {JSON.stringify(stepResult, null, 2)}
+              </pre>
+            )}
+          </div>
+        )}
+      </Card>
+    </motion.div>
+  )
+}
+
+export default function AgentExecution() {
+  const [goal, setGoal] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [result, setResult] = useState<ExecutionResult | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [history, setHistory] = useState<ExecutionHistoryItem[]>([])
+  const [historyLoading, setHistoryLoading] = useState(false)
+  const [historyError, setHistoryError] = useState<string | null>(null)
+
+  const loadHistory = useCallback(async () => {
+    setHistoryLoading(true)
+    setHistoryError(null)
+    try {
+      setHistory(await executionApi.history())
+    } catch (e: unknown) {
+      setHistoryError(getApiErrorMessage(e, 'Failed to load execution history'))
+    } finally {
+      setHistoryLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    const timeoutId = window.setTimeout(() => { void loadHistory() }, 0)
+    return () => window.clearTimeout(timeoutId)
+  }, [loadHistory])
+
+  const handleExecute = async () => {
+    if (!goal.trim()) return
+    setLoading(true)
+    setError(null)
+    setResult(null)
+    try {
+      const res = await executionApi.executePlan(goal)
+      setResult(res)
+      void loadHistory()
+    } catch (e: unknown) {
+      setError(getApiErrorMessage(e, 'Execution failed'))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const successCount = result?.steps.filter(s => s.status === 'success').length || 0
+  const retrieved: RetrievedSkill[] = result?.retrieved_skills || []
+
+  return (
+    <div style={{ padding: 24, maxWidth: 900, margin: '0 auto' }}>
+      <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }}>
+        <h2 style={{ fontWeight: 700, marginBottom: 4 }}>Agent Execution</h2>
+        <p style={{ color: '#666', marginBottom: 24 }}>
+          Enter a task goal. SkillWiki will retrieve relevant Skills, build an execution plan, and run it.
+        </p>
+
+        <Card variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}>
+          <TextArea
+            value={goal}
+            onChange={e => setGoal(e.target.value)}
+            placeholder="Describe your task goal, for example: find the login button on a page, click it, then fill in the username and password..."
+            rows={3}
+            style={{ marginBottom: 12, fontSize: 14 }}
+          />
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+            <Text type="secondary" style={{ fontSize: 12 }}>
+              SkillWiki will decompose the task, retrieve Skills, and generate an execution plan.
+            </Text>
+            <Button
+              type="primary"
+              icon={<PlayCircleOutlined />}
+              onClick={handleExecute}
+              loading={loading}
+              disabled={!goal.trim()}
+              size="large"
+            >
+              Execute
+            </Button>
+          </div>
+        </Card>
+
+        {/* Example tasks */}
+        <div style={{ marginBottom: 24 }}>
+          <Text type="secondary" style={{ fontSize: 12, marginRight: 8 }}>Examples:</Text>
+          {[
+            'Click the submit button on the page',
+            'Fill and submit the login form',
+            'Type a keyword into the search box and search',
+          ].map(ex => (
+            <Tag
+              key={ex}
+              style={{ cursor: 'pointer', marginBottom: 4 }}
+              onClick={() => setGoal(ex)}
+            >
+              {ex}
+            </Tag>
+          ))}
+        </div>
+      </motion.div>
+
+      <Card
+        title={<span><DatabaseOutlined style={{ color: '#1677ff', marginRight: 6 }} />Recent Execution History</span>}
+        variant="borderless"
+        size="small"
+        style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+        extra={
+          <Button size="small" icon={<ReloadOutlined />} loading={historyLoading} onClick={loadHistory}>
+            Refresh
+          </Button>
+        }
+      >
+        {historyError && (
+          <Alert type="warning" showIcon title={historyError} style={{ marginBottom: 12 }} />
+        )}
+        {!historyLoading && history.length === 0 ? (
+          <Empty description="No execution history yet. Completed tasks will appear here automatically." image={Empty.PRESENTED_IMAGE_SIMPLE} />
+        ) : (
+          <Table
+            rowKey="execution_id"
+            dataSource={history}
+            loading={historyLoading}
+            size="small"
+            pagination={{ pageSize: 5, size: 'small' }}
+            columns={[
+              {
+                title: 'Goal',
+                dataIndex: 'goal',
+                ellipsis: true,
+                render: (goalText: string) => <Text style={{ maxWidth: 240 }}>{goalText}</Text>,
+              },
+              {
+                title: 'Status',
+                dataIndex: 'status',
+                width: 90,
+                render: (status: string) => <Tag color={STATUS_COLOR[status] || 'default'}>{status}</Tag>,
+              },
+              {
+                title: 'Steps',
+                width: 90,
+                render: (_: unknown, item: ExecutionHistoryItem) => `${item.success_count}/${item.step_count}`,
+              },
+              {
+                title: 'Skills',
+                dataIndex: 'retrieved_skill_count',
+                width: 80,
+              },
+              {
+                title: 'Latency',
+                dataIndex: 'total_latency_ms',
+                width: 90,
+                render: (ms: number) => `${ms.toFixed(0)}ms`,
+              },
+              {
+                title: 'Created',
+                dataIndex: 'created_at',
+                width: 170,
+                render: formatHistoryTime,
+              },
+            ]}
+          />
+        )}
+      </Card>
+
+      {loading && (
+        <div style={{ textAlign: 'center', padding: 40 }}>
+          <Spin size="large" description="Planning and executing..." />
+        </div>
+      )}
+
+      {error && (
+        <Alert type="error" title="Execution Failed" description={error} showIcon style={{ marginBottom: 16 }} />
+      )}
+
+      <AnimatePresence>
+        {result && (
+          <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }}>
+          {/* Retrieved Skills */}
+            {retrieved.length > 0 && (
+              <Card
+                title={<span><SearchOutlined style={{ color: '#1677ff', marginRight: 6 }} />Retrieved Skills ({retrieved.length})</span>}
+                variant="borderless"
+                size="small"
+                style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+              >
+                <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+                  {retrieved.map(sk => (
+                    <Tooltip key={sk.skill_id} title={sk.match_reason}>
+                      <div style={{
+                        display: 'flex', alignItems: 'center', gap: 6,
+                        padding: '4px 10px', borderRadius: 20,
+                        background: '#f5f7fa', border: '1px solid #e8e8e8',
+                        cursor: 'default',
+                      }}>
+                        <Tag color={SKILL_TYPE_COLOR[sk.skill_type]} style={{ margin: 0, fontSize: 10, padding: '0 4px' }}>
+                          {sk.skill_type}
+                        </Tag>
+                        <Text style={{ fontSize: 12 }}>{sk.name}</Text>
+                        <Progress
+                          type="circle"
+                          percent={Math.round(sk.score * 100)}
+                          width={24}
+                          strokeColor={sk.score > 0.6 ? '#52c41a' : '#faad14'}
+                          format={p => <span style={{ fontSize: 8 }}>{p}</span>}
+                        />
+                      </div>
+                    </Tooltip>
+                  ))}
+                </div>
+              </Card>
+            )}
+
+            {/* Execution summary */}
+            <Card
+              variant="borderless"
+              style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+            >
+              <Row gutter={16}>
+                <Col span={6}>
+                  <Statistic
+                    title="Status"
+                    value={result.status}
+                    styles={{ content: { color: result.status === 'success' ? '#52c41a' : result.status === 'failed' ? '#ff4d4f' : '#faad14' } }}
+                  />
+                </Col>
+                <Col span={6}>
+                  <Statistic title="Total Steps" value={result.steps.length} />
+                </Col>
+                <Col span={6}>
+                  <Statistic title="Successful" value={successCount} styles={{ content: { color: '#52c41a' } }} />
+                </Col>
+                <Col span={6}>
+                  <Statistic
+                    title="Total Latency"
+                    value={result.total_latency_ms.toFixed(0)}
+                    suffix="ms"
+                    styles={{ content: { color: '#1677ff' } }}
+                  />
+                </Col>
+              </Row>
+            </Card>
+
+            {/* Execution steps */}
+            <Card
+              title={<><ThunderboltOutlined /> Execution Steps</>}
+              variant="borderless"
+              style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+            >
+              {result.steps.length === 0 ? (
+                <Alert type="warning" title="No executable Skill was found. Try a more specific task description." />
+              ) : (
+                result.steps.map((step, i) => <StepCard key={step.step_id} step={step} index={i} />)
+              )}
+            </Card>
+
+            {/* Final state */}
+            {Object.keys(result.final_state).length > 0 && (
+              <Card
+                title="Final State"
+                variant="borderless"
+                style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+              >
+                <pre style={{ background: '#f5f5f5', padding: 12, borderRadius: 8, fontSize: 12, overflow: 'auto' }}>
+                  {JSON.stringify(result.final_state, null, 2)}
+                </pre>
+              </Card>
+            )}
+            {/* Experience recording feedback */}
+            {result.experience_recorded && (
+              <motion.div initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }} transition={{ delay: 0.3 }}>
+                <Card
+                  variant="borderless"
+                  size="small"
+                  style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', borderLeft: '3px solid #52c41a' }}
+                >
+                  <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+                    <DatabaseOutlined style={{ color: '#52c41a', fontSize: 16 }} />
+                    <Text style={{ fontSize: 13 }}>
+                      <strong>Experience recorded</strong> - this execution trace was written to the Experience Store for Skill quality assessment and evolution decisions.
+                    </Text>
+                  </div>
+                </Card>
+              </motion.div>
+            )}
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/Dashboard.tsx

@@ -0,0 +1,434 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { Alert, Card, Col, Row, Statistic, Progress, Tag, Table, Badge, Spin, Timeline, Button, Empty, Divider, Space } from 'antd'
+import {
+  RocketOutlined,
+  CheckCircleOutlined,
+  WarningOutlined,
+  ThunderboltOutlined,
+  ClearOutlined,
+  WifiOutlined,
+  StarOutlined,
+  SyncOutlined,
+  BulbOutlined,
+} from '@ant-design/icons'
+import { motion } from 'framer-motion'
+import { statsApi, evolutionApi } from '@/api/client'
+import type { EvolutionStats } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import { useAppStore } from '@/store/appStore'
+import type { OverviewStats, HealthReport } from '@/api/types'
+
+const stateColors: Record<string, string> = {
+  S4: 'green', S2: 'blue', S3: 'cyan', S1: 'orange',
+  S5: 'gold', S6: 'red', S7: 'default', S0: 'purple',
+}
+const stateLabels: Record<string, string> = {
+  S0: 'Raw', S1: 'Candidate', S2: 'Draft', S3: 'Verified',
+  S4: 'Released', S5: 'Degraded', S6: 'Deprecated', S7: 'Archived',
+}
+
+const healthColors: Record<string, string> = {
+  healthy: '#52c41a',
+  degraded: '#faad14',
+  critical: '#ff4d4f',
+  stale: '#d9d9d9',
+  unknown: '#8c8c8c',
+}
+
+const REFRESH_EVENT_TYPES = new Set([
+  'plan_completed',
+  'health_degraded',
+  'health_critical',
+  'evolution_cycle_done',
+])
+
+function formatEventTime(timestamp: string) {
+  const date = new Date(timestamp)
+  return Number.isNaN(date.getTime()) ? timestamp : date.toLocaleTimeString()
+}
+
+export default function Dashboard() {
+  const [stats, setStats] = useState<OverviewStats | null>(null)
+  const [reports, setReports] = useState<HealthReport[]>([])
+  const [evoStats, setEvoStats] = useState<EvolutionStats | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [refreshing, setRefreshing] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [lastUpdated, setLastUpdated] = useState<string | null>(null)
+  const { wsEvents, clearWsEvents } = useAppStore()
+
+  const loadDashboardData = useCallback(async (initial = false) => {
+    if (initial) setLoading(true)
+    else setRefreshing(true)
+
+    try {
+      const [s, h, evo] = await Promise.all([
+        statsApi.overview(),
+        evolutionApi.systemHealth().catch(() => null),
+        statsApi.evolutionStats().catch(() => null),
+      ])
+
+      setStats(s)
+      setReports(h?.skill_reports.slice(0, 10) ?? [])
+      setEvoStats(evo)
+      setError(null)
+      setLastUpdated(new Date().toLocaleTimeString())
+    } catch (e: unknown) {
+      setError(getApiErrorMessage(e, 'Failed to load dashboard data'))
+    } finally {
+      if (initial) setLoading(false)
+      else setRefreshing(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    const timeoutId = window.setTimeout(() => { void loadDashboardData(true) }, 0)
+    const timer = window.setInterval(() => {
+      void loadDashboardData(false)
+    }, 15_000)
+    return () => {
+      window.clearTimeout(timeoutId)
+      window.clearInterval(timer)
+    }
+  }, [loadDashboardData])
+
+  const refreshSignal = useMemo(() => {
+    const event = wsEvents.find(e => REFRESH_EVENT_TYPES.has(e.type))
+    return event ? `${event.type}:${event.timestamp}` : ''
+  }, [wsEvents])
+
+  useEffect(() => {
+    if (!refreshSignal) return
+    const timeoutId = window.setTimeout(() => { void loadDashboardData(false) }, 0)
+    return () => window.clearTimeout(timeoutId)
+  }, [loadDashboardData, refreshSignal])
+
+  const feedEvents = useMemo(
+    () => wsEvents.filter(e => e.type !== 'pong' && e.type !== 'connected').slice(0, 30),
+    [wsEvents],
+  )
+
+  if (loading && !stats) return <div style={{ textAlign: 'center', padding: 80 }}><Spin size="large" /></div>
+  if (!stats) {
+    return (
+      <div style={{ padding: 24 }}>
+        <Alert
+          type="error"
+          showIcon
+          title="Failed to Load Dashboard Data"
+          description={error || 'Please check whether the backend service is available.'}
+          action={<Button size="small" onClick={() => loadDashboardData(true)}>Retry</Button>}
+        />
+      </div>
+    )
+  }
+
+  const healthyPct = stats.total_skills > 0
+    ? Math.round((stats.by_state['S4'] || 0) / stats.total_skills * 100)
+    : 0
+
+  const cardVariants = {
+    hidden: { opacity: 0, y: 20 },
+    visible: (i: number) => ({ opacity: 1, y: 0, transition: { delay: i * 0.08 } }),
+  }
+
+  return (
+    <div style={{ padding: '24px' }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: 16, marginBottom: 16, flexWrap: 'wrap' }}>
+        <motion.h2
+          initial={{ opacity: 0, x: -20 }}
+          animate={{ opacity: 1, x: 0 }}
+          style={{ margin: 0, fontSize: 22, fontWeight: 700 }}
+        >
+          SkillWiki Dashboard
+        </motion.h2>
+        <Space>
+          <span style={{ color: '#999', fontSize: 12 }}>
+            Last updated: {lastUpdated || 'Not refreshed yet'}
+          </span>
+          <Button
+            size="small"
+            icon={<SyncOutlined spin={refreshing} />}
+            loading={refreshing}
+            onClick={() => loadDashboardData(false)}
+          >
+            Refresh
+          </Button>
+        </Space>
+      </div>
+
+      {error && (
+        <Alert
+          type="warning"
+          showIcon
+          closable
+          title="Latest Refresh Failed"
+          description={error}
+          style={{ marginBottom: 16 }}
+          onClose={() => setError(null)}
+        />
+      )}
+
+      {/* Core metrics */}
+      <Row gutter={[16, 16]}>
+        {[
+          { title: 'Total Skills', value: stats.total_skills, icon: <RocketOutlined />, color: '#1677ff', i: 0 },
+          { title: 'Released', value: stats.by_state['S4'] || 0, icon: <CheckCircleOutlined />, color: '#52c41a', i: 1 },
+          { title: 'Degraded', value: stats.by_state['S5'] || 0, icon: <WarningOutlined />, color: '#faad14', i: 2 },
+          { title: 'Total Executions', value: stats.total_executions, icon: <ThunderboltOutlined />, color: '#722ed1', i: 3 },
+        ].map(({ title, value, icon, color, i }) => (
+          <Col xs={24} sm={12} lg={6} key={title}>
+            <motion.div custom={i} initial="hidden" animate="visible" variants={cardVariants}>
+              <Card variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+                <Statistic
+                  title={title}
+                  value={value}
+                  prefix={<span style={{ color }}>{icon}</span>}
+                  styles={{ content: { color, fontWeight: 700 } }}
+                />
+              </Card>
+            </motion.div>
+          </Col>
+        ))}
+      </Row>
+
+      <Row gutter={[16, 16]} style={{ marginTop: 16 }}>
+        {/* Type distribution */}
+        <Col xs={24} md={8}>
+          <motion.div custom={4} initial="hidden" animate="visible" variants={cardVariants}>
+            <Card title="Skill Types" variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+              {Object.entries(stats.by_type).map(([type, count]) => (
+                <div key={type} style={{ marginBottom: 12 }}>
+                  <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+                    <Tag color={type === 'atomic' ? 'blue' : type === 'functional' ? 'purple' : 'gold'}>
+                      {type.toUpperCase()}
+                    </Tag>
+                    <span style={{ fontWeight: 600 }}>{count}</span>
+                  </div>
+                  <Progress
+                    percent={stats.total_skills > 0 ? Math.round(count / stats.total_skills * 100) : 0}
+                    strokeColor={type === 'atomic' ? '#1677ff' : type === 'functional' ? '#722ed1' : '#faad14'}
+                    showInfo={false}
+                    size="small"
+                  />
+                </div>
+              ))}
+            </Card>
+          </motion.div>
+        </Col>
+
+        {/* State distribution */}
+        <Col xs={24} md={8}>
+          <motion.div custom={5} initial="hidden" animate="visible" variants={cardVariants}>
+            <Card title="State Distribution" variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+              {Object.entries(stats.by_state).map(([state, count]) => (
+                <div key={state} style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 8 }}>
+                  <Tag color={stateColors[state] || 'default'}>{stateLabels[state] || state}</Tag>
+                  <Badge count={count} style={{ backgroundColor: '#1677ff' }} />
+                </div>
+              ))}
+            </Card>
+          </motion.div>
+        </Col>
+
+        {/* Health score */}
+        <Col xs={24} md={8}>
+          <motion.div custom={6} initial="hidden" animate="visible" variants={cardVariants}>
+            <Card title="System Health" variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+              <div style={{ textAlign: 'center', marginBottom: 16 }}>
+                <Progress
+                  type="circle"
+                  percent={healthyPct}
+                  strokeColor={{ '0%': '#52c41a', '100%': '#1677ff' }}
+                  format={p => <span style={{ fontWeight: 700 }}>{p}%<br /><small>Released</small></span>}
+                />
+              </div>
+              <Statistic
+                title="Avg Success Rate"
+                value={(stats.avg_success_rate * 100).toFixed(1)}
+                suffix="%"
+                styles={{ content: { color: stats.avg_success_rate > 0.8 ? '#52c41a' : '#faad14' } }}
+              />
+            </Card>
+          </motion.div>
+        </Col>
+      </Row>
+
+      {/* Health report table */}
+      <motion.div custom={7} initial="hidden" animate="visible" variants={cardVariants} style={{ marginTop: 16 }}>
+        <Card title="Skill Health Overview" variant="borderless" style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+          <Table
+            dataSource={reports}
+            rowKey="skill_id"
+            size="small"
+            pagination={false}
+            columns={[
+              {
+                title: 'Skill',
+                dataIndex: 'skill_name',
+                render: (name: string) => <strong>{name}</strong>,
+              },
+              {
+                title: 'Status',
+                dataIndex: 'status',
+                render: (s: string) => (
+                  <Badge color={healthColors[s] || '#8c8c8c'} text={s} />
+                ),
+              },
+              {
+                title: 'Success Rate',
+                dataIndex: 'success_rate',
+                render: (r: number) => (
+                  <Progress
+                    percent={Math.round(r * 100)}
+                    size="small"
+                    strokeColor={r > 0.8 ? '#52c41a' : r > 0.5 ? '#faad14' : '#ff4d4f'}
+                  />
+                ),
+              },
+              {
+                title: 'Executions',
+                dataIndex: 'usage_count',
+              },
+              {
+                title: 'Avg Latency',
+                dataIndex: 'avg_latency_ms',
+                render: (ms: number) => `${ms.toFixed(0)}ms`,
+              },
+            ]}
+          />
+        </Card>
+      </motion.div>
+
+      {/* Evolution metrics panel */}
+      {evoStats && (
+        <motion.div custom={8} initial="hidden" animate="visible" variants={cardVariants} style={{ marginTop: 16 }}>
+          <Card
+            title={<span><SyncOutlined style={{ color: '#1677ff', marginRight: 6 }} />Self-Evolution Metrics</span>}
+            variant="borderless"
+            style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+          >
+            <Row gutter={[16, 16]}>
+              <Col xs={12} sm={6}>
+                <div style={{ textAlign: 'center' }}>
+                  <Statistic
+                    title="Auto-Generated Skills"
+                    value={evoStats.auto_generated}
+                    prefix={<BulbOutlined style={{ color: '#faad14' }} />}
+                    styles={{ content: { color: '#faad14', fontWeight: 700 } }}
+                  />
+                </div>
+              </Col>
+              <Col xs={12} sm={6}>
+                <div style={{ textAlign: 'center' }}>
+                  <Statistic
+                    title="Avg Reuse Rate"
+                    value={evoStats.avg_reuse_rate.toFixed(1)}
+                    suffix="x"
+                    prefix={<StarOutlined style={{ color: '#722ed1' }} />}
+                    styles={{ content: { color: '#722ed1', fontWeight: 700 } }}
+                  />
+                </div>
+              </Col>
+              <Col xs={12} sm={6}>
+                <div style={{ textAlign: 'center' }}>
+                  <Statistic
+                    title="Version Improved"
+                    value={evoStats.version_improved_count}
+                    prefix={<RocketOutlined style={{ color: '#52c41a' }} />}
+                    styles={{ content: { color: '#52c41a', fontWeight: 700 } }}
+                  />
+                </div>
+              </Col>
+              <Col xs={12} sm={6}>
+                <div style={{ textAlign: 'center' }}>
+                  <Statistic
+                    title="Avg Success Rate"
+                    value={(evoStats.avg_success_rate * 100).toFixed(1)}
+                    suffix="%"
+                    prefix={<CheckCircleOutlined style={{ color: '#1677ff' }} />}
+                    styles={{ content: { color: '#1677ff', fontWeight: 700 } }}
+                  />
+                </div>
+              </Col>
+            </Row>
+            <Divider style={{ margin: '16px 0 12px' }} />
+            <div style={{ marginBottom: 8 }}>
+              <Tag color="blue">Skills by Category</Tag>
+            </div>
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+              {Object.entries(evoStats.skills_by_category).map(([cat, count]) => (
+                <Tag key={cat} color={cat === 'atomic' ? 'blue' : cat === 'functional' ? 'purple' : cat === 'strategic' ? 'gold' : 'default'}>
+                  {cat}: {count}
+                </Tag>
+              ))}
+            </div>
+            {evoStats.recent_activity.length > 0 && (
+              <>
+                <Divider style={{ margin: '12px 0' }} />
+                <div style={{ marginBottom: 8 }}>
+                  <Tag color="green">Recent Activity</Tag>
+                </div>
+                <div style={{ maxHeight: 160, overflowY: 'auto' }}>
+                  {evoStats.recent_activity.map((a, i) => (
+                    <div key={i} style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '4px 0', borderBottom: i < evoStats.recent_activity.length - 1 ? '1px solid #f0f0f0' : 'none' }}>
+                      <Badge color={a.event === 'updated' ? 'blue' : 'green'} />
+                      <span style={{ fontSize: 12, flex: 1 }}><strong>{a.name}</strong> — {a.event}</span>
+                      <Tag style={{ fontSize: 10 }}>{a.state}</Tag>
+                    </div>
+                  ))}
+                </div>
+              </>
+            )}
+          </Card>
+        </motion.div>
+      )}
+
+      {/* Agent activity feed */}
+      <motion.div custom={8} initial="hidden" animate="visible" variants={cardVariants} style={{ marginTop: 16 }}>
+        <Card
+          title={<span><WifiOutlined style={{ color: '#52c41a', marginRight: 6 }} />Live Agent Activity</span>}
+          variant="borderless"
+          style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+          extra={
+            <Button size="small" icon={<ClearOutlined />} onClick={clearWsEvents}>
+              Clear
+            </Button>
+          }
+        >
+          {feedEvents.length === 0 ? (
+            <Empty description="No events yet. Live activity will appear here after Agent tasks run." image={Empty.PRESENTED_IMAGE_SIMPLE} />
+          ) : (
+            <div style={{ maxHeight: 320, overflowY: 'auto' }}>
+              <Timeline
+                items={feedEvents
+                  .map(e => {
+                    const isError = e.type.includes('error') || e.type.includes('fail')
+                    const isSuccess = e.type.includes('success') || e.type.includes('complete') || e.type.includes('release')
+                    return {
+                      color: isError ? 'red' : isSuccess ? 'green' : 'blue',
+                      children: (
+                        <div>
+                          <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+                            <Tag color={isError ? 'red' : isSuccess ? 'green' : 'blue'} style={{ fontSize: 11 }}>
+                              {e.type}
+                            </Tag>
+                            <span style={{ fontSize: 11, color: '#999' }}>{formatEventTime(e.timestamp)}</span>
+                          </div>
+                          {e.payload !== null && e.payload !== undefined && typeof e.payload === 'object' && (
+                            <div style={{ fontSize: 11, color: '#666', marginTop: 2 }}>
+                              {JSON.stringify(e.payload as Record<string, unknown>).slice(0, 120)}
+                            </div>
+                          )}
+                        </div>
+                      ),
+                    }
+                  })}
+              />
+            </div>
+          )}
+        </Card>
+      </motion.div>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/EvaluationDashboard.tsx

@@ -0,0 +1,481 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  Alert,
+  Button,
+  Card,
+  Col,
+  Empty,
+  Progress,
+  Row,
+  Space,
+  Spin,
+  Statistic,
+  Table,
+  Tag,
+  Typography,
+} from 'antd'
+import type { ColumnsType } from 'antd/es/table'
+import { ReloadOutlined } from '@ant-design/icons'
+import { evaluationApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  EvaluationDashboardResponse,
+  EvaluationDemoBenchmark,
+  EvaluationDemoRow,
+  EvaluationLlmRow,
+  EvaluationModeTotal,
+  EvaluationSearchEval,
+  EvaluationSearchRow,
+} from '@/api/types'
+
+const { Text, Paragraph } = Typography
+
+const modeLabels: Record<string, string> = {
+  no_skill: 'No Skill',
+  raw_prompt: 'Raw Prompt',
+  with_skill: 'With Skill',
+  fallback: 'Fallback Planner',
+  llm: 'LLM Planner',
+}
+
+const statusColors: Record<string, string> = {
+  success: 'green',
+  passed: 'green',
+  failed: 'red',
+  functional_failure: 'red',
+  api_failure: 'volcano',
+  skipped: 'default',
+  incomplete_llm: 'gold',
+  with_skill: 'blue',
+}
+
+function formatPercent(value?: number | null) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return 'N/A'
+  return `${(value * 100).toFixed(1)}%`
+}
+
+function percentNumber(value?: number | null) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return 0
+  return Math.round(value * 1000) / 10
+}
+
+function formatLatency(value?: number | null) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return 'N/A'
+  return `${value.toFixed(value >= 10 ? 0 : 2)} ms`
+}
+
+function statusTag(status?: string | null) {
+  if (!status) return <Text type="secondary">N/A</Text>
+  return <Tag color={statusColors[status] || 'default'}>{status}</Tag>
+}
+
+function verifierTag(value?: boolean | null) {
+  if (value === true) return <Tag color="green">pass</Tag>
+  if (value === false) return <Tag color="red">fail</Tag>
+  return <Text type="secondary">N/A</Text>
+}
+
+function artifactTime(artifact: { generated_at?: string | null; updated_at?: string | null }) {
+  return artifact.generated_at || artifact.updated_at || 'N/A'
+}
+
+function ModeCard({ mode, total }: { mode: string; total?: EvaluationModeTotal }) {
+  const success = total?.success ?? 0
+  const count = total?.total ?? 0
+  const rate = total?.success_rate ?? total?.success_rate_excluding_api_failures ?? null
+  return (
+    <div style={{ background: '#fafafa', borderRadius: 8, padding: 16 }}>
+      <Statistic
+        title={modeLabels[mode] || mode}
+        value={`${success}/${count}`}
+        styles={{ content: { color: rate && rate > 0 ? '#1677ff' : '#8c8c8c', fontWeight: 700 } }}
+      />
+      <Progress
+        percent={percentNumber(rate)}
+        size="small"
+        status={rate && rate > 0 ? 'active' : 'normal'}
+        style={{ marginTop: 8 }}
+      />
+      <Text type="secondary">{formatPercent(rate)}</Text>
+    </div>
+  )
+}
+
+function SuccessRateBars({ artifact }: { artifact: EvaluationDemoBenchmark }) {
+  const modes = ['no_skill', 'raw_prompt', 'with_skill']
+  return (
+    <Space orientation="vertical" style={{ width: '100%' }} size={12}>
+      {modes.map(mode => {
+        const total = artifact.mode_totals[mode]
+        const pct = percentNumber(total?.success_rate)
+        return (
+          <div key={mode}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <Text>{modeLabels[mode]}</Text>
+              <Text strong>{formatPercent(total?.success_rate)}</Text>
+            </div>
+            <div style={{ height: 12, background: '#f0f0f0', borderRadius: 4, overflow: 'hidden' }}>
+              <div
+                style={{
+                  width: `${pct}%`,
+                  height: '100%',
+                  background: mode === 'with_skill' ? '#1677ff' : '#d9d9d9',
+                }}
+              />
+            </div>
+          </div>
+        )
+      })}
+    </Space>
+  )
+}
+
+function DemoBenchmarkPanel({ artifact }: { artifact: EvaluationDemoBenchmark }) {
+  const columns: ColumnsType<EvaluationDemoRow> = [
+    {
+      title: 'Task',
+      dataIndex: 'task_id',
+      key: 'task_id',
+      width: 260,
+      render: value => <Text code>{value}</Text>,
+    },
+    {
+      title: 'Category',
+      dataIndex: 'domain',
+      key: 'domain',
+      width: 110,
+      render: value => <Tag>{value || 'unknown'}</Tag>,
+    },
+    {
+      title: 'No Skill',
+      dataIndex: 'no_skill',
+      key: 'no_skill',
+      width: 110,
+      render: statusTag,
+    },
+    {
+      title: 'Raw Prompt',
+      dataIndex: 'raw_prompt',
+      key: 'raw_prompt',
+      width: 120,
+      render: statusTag,
+    },
+    {
+      title: 'With Skill',
+      dataIndex: 'with_skill',
+      key: 'with_skill',
+      width: 120,
+      render: statusTag,
+    },
+    {
+      title: 'Verifier',
+      key: 'verifier',
+      width: 120,
+      render: (_, row) => verifierTag(row.with_skill_verifier_passed),
+    },
+    {
+      title: 'Latency',
+      key: 'latency',
+      width: 120,
+      render: (_, row) => formatLatency(row.with_skill_latency_ms),
+    },
+    {
+      title: 'Failure Reason',
+      dataIndex: 'failure_reason',
+      key: 'failure_reason',
+      render: value => (
+        <Paragraph ellipsis={{ rows: 2, expandable: true, symbol: 'more' }} style={{ marginBottom: 0 }}>
+          {value || 'N/A'}
+        </Paragraph>
+      ),
+    },
+  ]
+
+  return (
+    <Card
+      title="Demo Benchmark"
+      extra={<Text type="secondary">{artifact.source_file} · {artifactTime(artifact)}</Text>}
+      variant="borderless"
+      style={{ borderRadius: 8 }}
+    >
+      <Row gutter={[16, 16]}>
+        {['no_skill', 'raw_prompt', 'with_skill'].map(mode => (
+          <Col xs={24} md={8} key={mode}>
+            <ModeCard mode={mode} total={artifact.mode_totals[mode]} />
+          </Col>
+        ))}
+      </Row>
+
+      <Row gutter={[16, 16]} style={{ marginTop: 16 }}>
+        <Col xs={24} lg={8}>
+          <div style={{ background: '#fafafa', borderRadius: 8, padding: 16 }}>
+            <Text strong style={{ display: 'block', marginBottom: 12 }}>Success Rate</Text>
+            <SuccessRateBars artifact={artifact} />
+          </div>
+        </Col>
+        <Col xs={24} lg={16}>
+          <Table
+            dataSource={artifact.rows}
+            columns={columns}
+            rowKey="task_id"
+            size="small"
+            pagination={{ pageSize: 8 }}
+            scroll={{ x: 980 }}
+            expandable={{
+              expandedRowRender: row => (
+                <Space orientation="vertical" size={4}>
+                  <Text>No Skill latency: {formatLatency(row.no_skill_latency_ms)} · verifier: {verifierTag(row.no_skill_verifier_passed)}</Text>
+                  <Text>Raw Prompt latency: {formatLatency(row.raw_prompt_latency_ms)} · verifier: {verifierTag(row.raw_prompt_verifier_passed)}</Text>
+                  <Text>With Skill latency: {formatLatency(row.with_skill_latency_ms)} · verifier: {verifierTag(row.with_skill_verifier_passed)}</Text>
+                </Space>
+              ),
+            }}
+          />
+        </Col>
+      </Row>
+    </Card>
+  )
+}
+
+function SearchEvalPanel({ artifact }: { artifact: EvaluationSearchEval }) {
+  const summary = artifact.comparison as {
+    lexical?: { top1_hit_rate?: number; top3_hit_rate?: number }
+    hybrid?: { top1_hit_rate?: number; top3_hit_rate?: number }
+    delta?: { top1_hit_rate?: number; top3_hit_rate?: number }
+  }
+  const columns: ColumnsType<EvaluationSearchRow> = [
+    { title: 'Query', dataIndex: 'query', key: 'query', width: 240 },
+    {
+      title: 'Expected',
+      dataIndex: 'expected_skill_ids',
+      key: 'expected_skill_ids',
+      width: 180,
+      render: ids => ((ids as string[]) || []).map(id => <Tag key={id}>{id}</Tag>),
+    },
+    { title: 'Lexical Top', dataIndex: 'lexical_top_skill', key: 'lexical_top_skill', width: 170 },
+    { title: 'Hybrid Top', dataIndex: 'hybrid_top_skill', key: 'hybrid_top_skill', width: 170 },
+    {
+      title: 'Lexical Hit',
+      dataIndex: 'lexical_top1_hit',
+      key: 'lexical_top1_hit',
+      width: 110,
+      render: verifierTag,
+    },
+    {
+      title: 'Hybrid Hit',
+      dataIndex: 'hybrid_top1_hit',
+      key: 'hybrid_top1_hit',
+      width: 110,
+      render: verifierTag,
+    },
+  ]
+  return (
+    <Card
+      title="Search Evaluation"
+      extra={<Text type="secondary">{artifact.source_file} · {artifact.schema_version || 'schema N/A'}</Text>}
+      variant="borderless"
+      style={{ borderRadius: 8 }}
+    >
+      <Row gutter={[16, 16]} style={{ marginBottom: 16 }}>
+        <Col xs={24} sm={8}>
+          <Statistic title="Queries" value={artifact.query_count} />
+        </Col>
+        <Col xs={24} sm={8}>
+          <Statistic title="Lexical Top-1" value={formatPercent(summary.lexical?.top1_hit_rate)} />
+        </Col>
+        <Col xs={24} sm={8}>
+          <Statistic title="Hybrid Top-1" value={formatPercent(summary.hybrid?.top1_hit_rate)} />
+        </Col>
+      </Row>
+      <Alert
+        type="info"
+        showIcon
+        title={`Observed hybrid delta: Top-1 ${formatPercent(summary.delta?.top1_hit_rate)}, Top-3 ${formatPercent(summary.delta?.top3_hit_rate)}`}
+        style={{ marginBottom: 16 }}
+      />
+      <Table
+        dataSource={artifact.rows}
+        columns={columns}
+        rowKey={row => row.query_id || row.query || 'query-row'}
+        size="small"
+        pagination={{ pageSize: 6 }}
+        scroll={{ x: 980 }}
+      />
+    </Card>
+  )
+}
+
+function LlmPlannerPanel({ artifact }: { artifact: EvaluationDashboardResponse['artifacts']['llm_planner'] }) {
+  const columns: ColumnsType<EvaluationLlmRow> = [
+    { title: 'Task', dataIndex: 'task_id', key: 'task_id', width: 240, render: value => <Text code>{value}</Text> },
+    { title: 'Fallback', dataIndex: 'fallback_status', key: 'fallback_status', width: 140, render: statusTag },
+    { title: 'LLM', dataIndex: 'llm_status', key: 'llm_status', width: 120, render: statusTag },
+    { title: 'API State', dataIndex: 'llm_api_error_type', key: 'llm_api_error_type', width: 140, render: value => value || 'N/A' },
+    {
+      title: 'Failure Reason',
+      dataIndex: 'llm_failure_reason',
+      key: 'llm_failure_reason',
+      render: value => (
+        <Paragraph ellipsis={{ rows: 2, expandable: true, symbol: 'more' }} style={{ marginBottom: 0 }}>
+          {value || 'N/A'}
+        </Paragraph>
+      ),
+    },
+  ]
+  return (
+    <Card
+      title="Planner Evaluation"
+      extra={<Text type="secondary">{artifact.source_file} · {artifactTime(artifact)}</Text>}
+      variant="borderless"
+      style={{ borderRadius: 8 }}
+    >
+      <Alert
+        type="warning"
+        showIcon
+        title="LLM planner rows marked skipped are incomplete runs, not model-quality failures."
+        style={{ marginBottom: 16 }}
+      />
+      <Row gutter={[16, 16]} style={{ marginBottom: 16 }}>
+        {['fallback', 'llm'].map(mode => (
+          <Col xs={24} sm={12} key={mode}>
+            <ModeCard mode={mode} total={artifact.mode_totals[mode]} />
+          </Col>
+        ))}
+      </Row>
+      <Table
+        dataSource={artifact.rows}
+        columns={columns}
+        rowKey={row => row.task_id || 'planner-row'}
+        size="small"
+        pagination={{ pageSize: 6 }}
+        scroll={{ x: 920 }}
+      />
+    </Card>
+  )
+}
+
+export default function EvaluationDashboard() {
+  const [data, setData] = useState<EvaluationDashboardResponse | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [refreshing, setRefreshing] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const loadData = useCallback(async (initial = false) => {
+    if (initial) setLoading(true)
+    else setRefreshing(true)
+    try {
+      const response = await evaluationApi.dashboard()
+      setData(response)
+      setError(null)
+    } catch (e: unknown) {
+      setError(getApiErrorMessage(e, 'Evaluation data load failed'))
+    } finally {
+      if (initial) setLoading(false)
+      else setRefreshing(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    let active = true
+    evaluationApi.dashboard()
+      .then(response => {
+        if (!active) return
+        setData(response)
+        setError(null)
+      })
+      .catch((e: unknown) => {
+        if (!active) return
+        setError(getApiErrorMessage(e, 'Evaluation data load failed'))
+      })
+      .finally(() => {
+        if (active) setLoading(false)
+      })
+    return () => {
+      active = false
+    }
+  }, [])
+
+  const warnings = useMemo(() => data?.warnings ?? [], [data])
+  const demo = data?.artifacts.demo_benchmark
+  const search = data?.artifacts.search_eval
+  const planner = data?.artifacts.llm_planner
+
+  if (loading && !data) {
+    return <div style={{ textAlign: 'center', padding: 80 }}><Spin size="large" /></div>
+  }
+
+  return (
+    <div style={{ padding: 24 }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', gap: 16, alignItems: 'center', marginBottom: 16, flexWrap: 'wrap' }}>
+        <div>
+          <h2 style={{ margin: 0, fontSize: 22, fontWeight: 700 }}>Evaluation Dashboard</h2>
+          <Text type="secondary">Demo benchmark evidence for paper-ready screenshots</Text>
+        </div>
+        <Space>
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            {data ? `Loaded ${data.generated_at}` : 'Not loaded'}
+          </Text>
+          <Button icon={<ReloadOutlined spin={refreshing} />} loading={refreshing} onClick={() => loadData(false)}>
+            Refresh
+          </Button>
+        </Space>
+      </div>
+
+      {error && (
+        <Alert
+          type="error"
+          showIcon
+          title="Evaluation data load failed"
+          description={error}
+          action={<Button size="small" onClick={() => loadData(true)}>Retry</Button>}
+          style={{ marginBottom: 16 }}
+        />
+      )}
+
+      {warnings.length > 0 && (
+        <Alert
+          type="warning"
+          showIcon
+          title="Artifact warnings"
+          description={warnings.join(' | ')}
+          style={{ marginBottom: 16 }}
+        />
+      )}
+
+      {!data?.results_dir_present && (
+        <Alert
+          type="info"
+          showIcon
+          title="Benchmark results directory is not present in this runtime."
+          style={{ marginBottom: 16 }}
+        />
+      )}
+
+      <Space orientation="vertical" size={16} style={{ width: '100%' }}>
+        {demo?.available ? (
+          <DemoBenchmarkPanel artifact={demo} />
+        ) : (
+          <Card variant="borderless" style={{ borderRadius: 8 }}>
+            <Empty description={demo?.error || 'No demo benchmark result available'} />
+          </Card>
+        )}
+
+        {search?.available ? (
+          <SearchEvalPanel artifact={search} />
+        ) : (
+          <Card title="Search Evaluation" variant="borderless" style={{ borderRadius: 8 }}>
+            <Empty description={search?.error || 'No search evaluation result available'} />
+          </Card>
+        )}
+
+        {planner?.available ? (
+          <LlmPlannerPanel artifact={planner} />
+        ) : (
+          <Card title="Planner Evaluation" variant="borderless" style={{ borderRadius: 8 }}>
+            <Empty description={planner?.error || 'No planner evaluation result available'} />
+          </Card>
+        )}
+      </Space>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/Evolution.tsx

@@ -0,0 +1,583 @@
+import { useEffect, useMemo, useState } from 'react'
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Col,
+  Empty,
+  message,
+  Progress,
+  Popconfirm,
+  Row,
+  Space,
+  Spin,
+  Statistic,
+  Table,
+  Tag,
+  Typography,
+} from 'antd'
+import type { TableColumnsType } from 'antd'
+import {
+  BranchesOutlined,
+  CheckCircleOutlined,
+  CloseCircleOutlined,
+  MedicineBoxOutlined,
+  SyncOutlined,
+} from '@ant-design/icons'
+import { motion } from 'framer-motion'
+import { useNavigate } from 'react-router-dom'
+import { evolutionApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  HealthReport,
+  MaintenanceProposal,
+  MaintenanceProposalListResponse,
+  SystemHealth,
+} from '@/api/types'
+
+const { Text } = Typography
+
+const STATUS_COLOR: Record<string, string> = {
+  healthy: '#52c41a',
+  degraded: '#faad14',
+  critical: '#ff4d4f',
+  stale: '#d9d9d9',
+  unknown: '#8c8c8c',
+}
+
+const STATUS_LABEL: Record<string, string> = {
+  healthy: 'Healthy',
+  degraded: 'Degraded',
+  critical: 'Critical',
+  stale: 'Stale',
+  unknown: 'Unknown',
+}
+
+type EvolutionCycleResult = {
+  cycle_id?: string
+  tasks_total?: number
+  tasks_completed?: number
+  tasks_failed?: number
+  repaired?: string[]
+  deprecated?: string[]
+  merged?: unknown[]
+  split?: unknown[]
+  errors?: string[]
+  maintenance_proposals?: MaintenanceProposal[]
+}
+
+type RepairResult = {
+  success?: boolean
+  root_cause?: string
+  should_deprecate?: boolean
+}
+
+function countOf(value: unknown[] | undefined) {
+  return Array.isArray(value) ? value.length : 0
+}
+
+function proposalColor(action?: string) {
+  if (action === 'repair') return 'orange'
+  if (action === 'review') return 'blue'
+  if (action === 'deprecate') return 'red'
+  return 'default'
+}
+
+function proposalStatusColor(status?: string) {
+  if (status === 'pending') return 'gold'
+  if (status === 'accepted') return 'green'
+  if (status === 'rejected') return 'red'
+  if (status === 'superseded') return 'default'
+  return 'blue'
+}
+
+function joinPreview(values?: string[], fallback = 'None') {
+  if (!values || values.length === 0) return fallback
+  return values.slice(0, 2).join('; ')
+}
+
+export default function Evolution() {
+  const navigate = useNavigate()
+  const [health, setHealth] = useState<SystemHealth | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+  const [cycling, setCycling] = useState(false)
+  const [repairing, setRepairing] = useState<string | null>(null)
+  const [cycleResult, setCycleResult] = useState<EvolutionCycleResult | null>(null)
+  const [proposalQueue, setProposalQueue] = useState<MaintenanceProposalListResponse | null>(null)
+  const [queueLoading, setQueueLoading] = useState(false)
+  const [proposalActionId, setProposalActionId] = useState<string | null>(null)
+
+  const loadHealth = async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const data = await evolutionApi.systemHealth()
+      setHealth(data)
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Failed to load health report'))
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const loadProposalQueue = async () => {
+    setQueueLoading(true)
+    try {
+      const data = await evolutionApi.proposals()
+      setProposalQueue(data)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Failed to load maintenance proposals'))
+    } finally {
+      setQueueLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      void loadHealth()
+      void loadProposalQueue()
+    }, 0)
+    return () => window.clearTimeout(timer)
+  }, [])
+
+  const runCycle = async () => {
+    setCycling(true)
+    try {
+      const result = await evolutionApi.runCycle() as EvolutionCycleResult
+      setCycleResult(result)
+      message.success(`Evolution cycle completed; maintenance proposals queued: ${countOf(result.maintenance_proposals)}`)
+      await loadHealth()
+      await loadProposalQueue()
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Evolution cycle failed'))
+    } finally {
+      setCycling(false)
+    }
+  }
+
+  const repairSkill = async (id: string) => {
+    setRepairing(id)
+    try {
+      const result = await evolutionApi.repair(id) as RepairResult
+      if (result.success) {
+        message.success(`Review candidate generated: ${result.root_cause || 'maintenance evidence captured'}`)
+      } else if (result.should_deprecate) {
+        message.warning('Governed review suggested: consider deprecating or replacing this Skill')
+      } else {
+        message.warning('No repair candidate generated; check the health recommendations')
+      }
+      await loadHealth()
+      await loadProposalQueue()
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Failed to generate maintenance candidate'))
+    } finally {
+      setRepairing(null)
+    }
+  }
+
+  const openVersionControl = (proposal: MaintenanceProposal) => {
+    const params = new URLSearchParams({
+      skill_id: proposal.skill_id,
+      proposal_id: proposal.proposal_id,
+    })
+    navigate(`/versions?${params.toString()}`)
+  }
+
+  const acceptProposal = async (proposal: MaintenanceProposal) => {
+    setProposalActionId(proposal.proposal_id)
+    try {
+      const accepted = await evolutionApi.acceptProposal(proposal.proposal_id)
+      message.success('Proposal accepted for governed review')
+      await loadProposalQueue()
+      openVersionControl(accepted)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Failed to accept proposal'))
+    } finally {
+      setProposalActionId(null)
+    }
+  }
+
+  const rejectProposal = async (proposal: MaintenanceProposal) => {
+    setProposalActionId(proposal.proposal_id)
+    try {
+      await evolutionApi.rejectProposal(proposal.proposal_id)
+      message.success('Proposal rejected')
+      await loadProposalQueue()
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Failed to reject proposal'))
+    } finally {
+      setProposalActionId(null)
+    }
+  }
+
+  const needsAttention = useMemo(
+    () => health?.skill_reports.filter(report => report.status === 'degraded' || report.status === 'critical') || [],
+    [health],
+  )
+
+  const columns: TableColumnsType<HealthReport> = [
+    {
+      title: 'Skill',
+      dataIndex: 'skill_name',
+      render: (name: string) => <Text strong>{name}</Text>,
+    },
+    {
+      title: 'Status',
+      dataIndex: 'status',
+      render: (status: string) => <Badge color={STATUS_COLOR[status] || STATUS_COLOR.unknown} text={STATUS_LABEL[status] || status} />,
+    },
+    {
+      title: 'Success Rate',
+      dataIndex: 'success_rate',
+      render: (rate: number) => (
+        <Progress
+          percent={Math.round(rate * 100)}
+          size="small"
+          strokeColor={rate > 0.7 ? '#52c41a' : rate > 0.4 ? '#faad14' : '#ff4d4f'}
+          style={{ width: 110 }}
+        />
+      ),
+    },
+    {
+      title: 'Executions',
+      dataIndex: 'usage_count',
+    },
+    {
+      title: 'Avg Latency',
+      dataIndex: 'avg_latency_ms',
+      render: (ms: number) => `${ms.toFixed(0)}ms`,
+    },
+    {
+      title: 'Issues',
+      dataIndex: 'issues',
+      render: (issues: string[]) => (
+        issues.length > 0
+          ? issues.map((issue, index) => <Tag key={`${issue}-${index}`} color="red">{issue}</Tag>)
+          : <Text type="secondary">None</Text>
+      ),
+    },
+    {
+      title: 'Recommendations',
+      dataIndex: 'recommendations',
+      render: (recommendations: string[]) => (
+        recommendations.length > 0
+          ? recommendations.map((recommendation, index) => <Tag key={`${recommendation}-${index}`} color="blue">{recommendation}</Tag>)
+          : <Text type="secondary">None</Text>
+      ),
+    },
+    {
+      title: 'Proposal',
+      dataIndex: 'maintenance_proposal',
+      render: (proposal?: MaintenanceProposal | null) => (
+        proposal ? (
+          <Space direction="vertical" size={2}>
+            <Space size={4} wrap>
+              <Tag color={proposalColor(proposal.recommended_action)}>{proposal.recommended_action}</Tag>
+              <Tag color={proposal.requires_human_review ? 'purple' : 'default'}>
+                {proposal.requires_human_review ? 'human review' : 'auto'}
+              </Tag>
+            </Space>
+            <Text type="secondary">{Math.round(proposal.confidence * 100)}% confidence</Text>
+            {proposal.patch_hint ? <Text>{proposal.patch_hint}</Text> : null}
+          </Space>
+        ) : <Text type="secondary">None</Text>
+      ),
+    },
+  ]
+
+  const attentionColumns: TableColumnsType<HealthReport> = [
+    ...columns,
+    {
+      title: 'Actions',
+      render: (_, record) => (
+        <Button
+          size="small"
+          type="primary"
+          icon={<MedicineBoxOutlined />}
+          loading={repairing === record.skill_id}
+          onClick={() => repairSkill(record.skill_id)}
+        >
+          Review candidate
+        </Button>
+      ),
+    },
+  ]
+
+  const proposalColumns: TableColumnsType<MaintenanceProposal> = [
+    {
+      title: 'Proposal',
+      dataIndex: 'proposal_id',
+      width: 180,
+      render: (id: string, record) => (
+        <Space direction="vertical" size={2}>
+          <Text code copyable style={{ fontSize: 11 }}>{id.slice(0, 8)}</Text>
+          <Text type="secondary" style={{ fontSize: 12 }}>{record.skill_id}</Text>
+        </Space>
+      ),
+    },
+    {
+      title: 'Action',
+      dataIndex: 'recommended_action',
+      width: 150,
+      render: (action: string, record) => (
+        <Space direction="vertical" size={2}>
+          <Space size={4} wrap>
+            <Tag color={proposalColor(action)}>{action}</Tag>
+            <Tag color={proposalStatusColor(record.status)}>{record.status}</Tag>
+          </Space>
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            {Math.round(record.confidence * 100)}% confidence
+          </Text>
+        </Space>
+      ),
+    },
+    {
+      title: 'Evidence',
+      dataIndex: 'evidence',
+      render: (_: string[], record) => (
+        <Space direction="vertical" size={4}>
+          <Text>{record.root_cause || joinPreview(record.evidence)}</Text>
+          {record.patch_hint ? <Text type="secondary">{record.patch_hint}</Text> : null}
+          {record.validation_plan?.length ? (
+            <Tag color="blue">Validation: {joinPreview(record.validation_plan)}</Tag>
+          ) : null}
+        </Space>
+      ),
+    },
+    {
+      title: 'Governance',
+      dataIndex: 'next_action',
+      width: 220,
+      render: (_, record) => (
+        <Space direction="vertical" size={6}>
+          {record.status === 'accepted' || record.next_action ? (
+            <>
+              <Tag color="purple">B review required</Tag>
+              <Text type="secondary" style={{ fontSize: 12 }}>
+                {record.next_action?.endpoint || `/api/v1/lifecycle/${record.skill_id}/propose-maintenance-change`}
+              </Text>
+            </>
+          ) : (
+            <Text type="secondary">Waiting for human decision</Text>
+          )}
+        </Space>
+      ),
+    },
+    {
+      title: 'Actions',
+      width: 220,
+      render: (_, record) => (
+        <Space wrap>
+          {record.status === 'pending' ? (
+            <>
+              <Button
+                size="small"
+                type="primary"
+                icon={<CheckCircleOutlined />}
+                loading={proposalActionId === record.proposal_id}
+                onClick={() => acceptProposal(record)}
+              >
+                Accept
+              </Button>
+              <Popconfirm
+                title="Reject this proposal?"
+                onConfirm={() => rejectProposal(record)}
+              >
+                <Button
+                  size="small"
+                  danger
+                  icon={<CloseCircleOutlined />}
+                  loading={proposalActionId === record.proposal_id}
+                >
+                  Reject
+                </Button>
+              </Popconfirm>
+            </>
+          ) : record.status === 'accepted' ? (
+            <Button
+              size="small"
+              icon={<BranchesOutlined />}
+              onClick={() => openVersionControl(record)}
+            >
+              Version
+            </Button>
+          ) : (
+            <Text type="secondary">No review action</Text>
+          )}
+        </Space>
+      ),
+    },
+  ]
+
+  if (loading && !health) {
+    return (
+      <div style={{ textAlign: 'center', padding: 80 }}>
+        <Spin size="large" description="Loading health report..." />
+      </div>
+    )
+  }
+
+  return (
+    <div style={{ padding: 24 }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: 16, marginBottom: 24, flexWrap: 'wrap' }}>
+        <div>
+          <h2 style={{ margin: 0, fontWeight: 700 }}>Feedback & Evolution</h2>
+          <Text type="secondary">Review Skill health, run evolution cycles, and create controlled maintenance proposals for unhealthy Skills.</Text>
+        </div>
+        <Space>
+          <Button onClick={loadHealth} loading={loading}>
+            Refresh
+          </Button>
+          <Button onClick={loadProposalQueue} loading={queueLoading}>
+            Refresh proposals
+          </Button>
+          <Button
+            type="primary"
+            icon={<SyncOutlined spin={cycling} />}
+            onClick={runCycle}
+            loading={cycling}
+            size="large"
+          >
+            Run Evolution Cycle
+          </Button>
+        </Space>
+      </div>
+
+      {error && (
+        <Alert
+          type="error"
+          showIcon
+          closable
+          title={error}
+          onClose={() => setError(null)}
+          style={{ marginBottom: 16 }}
+        />
+      )}
+
+      {cycleResult && (
+        <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }} style={{ marginBottom: 16 }}>
+          <Alert
+            type={countOf(cycleResult.errors) > 0 ? 'warning' : 'success'}
+            title="Evolution Cycle Completed"
+            description={(
+              <Space wrap size={[8, 8]}>
+                <Tag color="blue">Tasks {cycleResult.tasks_completed || 0}/{cycleResult.tasks_total || 0}</Tag>
+                <Tag color="green">Repair candidates {countOf(cycleResult.repaired)}</Tag>
+                <Tag color="red">Deprecated {countOf(cycleResult.deprecated)}</Tag>
+                <Tag color="purple">Merged {countOf(cycleResult.merged)}</Tag>
+                <Tag color="gold">Split {countOf(cycleResult.split)}</Tag>
+                <Tag color="orange">Proposal {countOf(cycleResult.maintenance_proposals)}</Tag>
+                <Tag color={cycleResult.tasks_failed ? 'red' : 'default'}>Failed {cycleResult.tasks_failed || 0}</Tag>
+              </Space>
+            )}
+            closable
+            onClose={() => setCycleResult(null)}
+          />
+        </motion.div>
+      )}
+
+      {health ? (
+        <>
+          <Row gutter={[16, 16]} style={{ marginBottom: 16 }}>
+            {[
+              { label: 'Total', value: health.total_skills, color: '#1677ff' },
+              { label: 'Healthy', value: health.healthy_count, color: '#52c41a' },
+              { label: 'Degraded', value: health.degraded_count, color: '#faad14' },
+              { label: 'Critical', value: health.critical_count, color: '#ff4d4f' },
+              { label: 'Stale', value: health.stale_count, color: '#8c8c8c' },
+            ].map(({ label, value, color }, index) => (
+              <Col xs={12} sm={8} md={4} key={label}>
+                <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} transition={{ delay: index * 0.06 }}>
+                  <Card variant="borderless" style={{ borderRadius: 8, textAlign: 'center', boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+                    <Statistic value={value} styles={{ content: { color, fontWeight: 700 } }} />
+                    <div style={{ color: '#666', fontSize: 12 }}>{label}</div>
+                  </Card>
+                </motion.div>
+              </Col>
+            ))}
+            <Col xs={12} sm={8} md={4}>
+              <Card variant="borderless" style={{ borderRadius: 8, textAlign: 'center', boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+                <Progress
+                  type="circle"
+                  percent={Math.round(health.health_ratio * 100)}
+                  size={60}
+                  strokeColor="#52c41a"
+                />
+                <div style={{ color: '#666', fontSize: 12, marginTop: 4 }}>Health Ratio</div>
+              </Card>
+            </Col>
+          </Row>
+
+          <Card
+            title={(
+              <Space>
+                <BranchesOutlined />
+                <span>Maintenance Proposal Queue</span>
+                <Tag color="gold">{proposalQueue?.pending_count || 0} pending</Tag>
+              </Space>
+            )}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+          >
+            {proposalQueue && proposalQueue.proposals.length > 0 ? (
+              <Table
+                dataSource={proposalQueue.proposals}
+                rowKey="proposal_id"
+                size="small"
+                loading={queueLoading}
+                pagination={{ pageSize: 5 }}
+                columns={proposalColumns}
+              />
+            ) : (
+              <Empty description="No maintenance proposals in the current service lifecycle" />
+            )}
+          </Card>
+
+          <Card
+            title={<><MedicineBoxOutlined /> Skills Needing Attention ({needsAttention.length})</>}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+          >
+            {needsAttention.length > 0 ? (
+              <Table
+                dataSource={needsAttention}
+                rowKey="skill_id"
+                size="small"
+                pagination={false}
+                columns={attentionColumns}
+              />
+            ) : (
+              <Empty description="No degraded or critical Skills right now." />
+            )}
+          </Card>
+
+          <Card
+            title="All Skill Health Reports"
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+          >
+            {health.skill_reports.length > 0 ? (
+              <Table
+                dataSource={health.skill_reports}
+                rowKey="skill_id"
+                size="small"
+                pagination={{ pageSize: 10 }}
+                columns={columns}
+              />
+            ) : (
+              <Empty description="No health report data yet. Release or execute more Skills to generate health assessments." />
+            )}
+          </Card>
+        </>
+      ) : (
+        <Card variant="borderless" style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+          <Empty description="System health report cannot be loaded right now.">
+            <Button type="primary" onClick={loadHealth}>Retry</Button>
+          </Empty>
+        </Card>
+      )}
+    </div>
+  )
+}

skillwiki-frontend/src/pages/HarnessVerification.tsx

@@ -0,0 +1,577 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import {
+  Alert,
+  Button,
+  Card,
+  Col,
+  Descriptions,
+  Empty,
+  InputNumber,
+  Progress,
+  Row,
+  Segmented,
+  Select,
+  Space,
+  Spin,
+  Switch,
+  Table,
+  Tag,
+  Timeline,
+  Typography,
+  message,
+} from 'antd'
+import type { TableColumnsType } from 'antd'
+import {
+  CheckCircleOutlined,
+  FileProtectOutlined,
+  PlayCircleOutlined,
+  ReloadOutlined,
+  SafetyCertificateOutlined,
+  ToolOutlined,
+} from '@ant-design/icons'
+import { useLocation } from 'react-router-dom'
+import { harnessApi, skillsApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  HarnessKind,
+  HarnessRunResult,
+  HarnessVerifyLoopResponse,
+  SkillSummary,
+} from '@/api/types'
+
+const { Paragraph, Text } = Typography
+
+const STATE_COLOR: Record<string, string> = {
+  S0: 'purple',
+  S1: 'orange',
+  S2: 'blue',
+  S3: 'cyan',
+  S4: 'green',
+  S5: 'gold',
+  S6: 'red',
+  S7: 'default',
+}
+
+const STATUS_COLOR: Record<string, string> = {
+  verified: 'green',
+  passed: 'green',
+  failed: 'red',
+  rejected: 'red',
+  needs_human_review: 'gold',
+  timeout: 'volcano',
+  harness_error: 'volcano',
+  harness_unavailable: 'default',
+}
+
+const HARNESS_LABEL: Record<HarnessKind, string> = {
+  local_skillos: 'Local SkillWiki',
+  codex_cli: 'Codex CLI',
+  claude_code: 'Claude Code',
+}
+
+function scoreNumber(score: Record<string, unknown> | undefined, key: string) {
+  const value = score?.[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function percent(score: number) {
+  return Math.max(0, Math.min(100, Math.round(score * 100)))
+}
+
+function formatPercent(value: number) {
+  return `${(value * 100).toFixed(1)}%`
+}
+
+function formatMs(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? `${value.toFixed(value >= 10 ? 0 : 2)} ms` : '-'
+}
+
+function renderJson(value: unknown) {
+  return (
+    <pre
+      style={{
+        margin: 0,
+        maxHeight: 180,
+        overflow: 'auto',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+        background: '#f6f8fa',
+        border: '1px solid #edf0f3',
+        borderRadius: 6,
+        padding: 10,
+        fontSize: 12,
+      }}
+    >
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  )
+}
+
+function statusTag(status?: string) {
+  if (!status) return <Text type="secondary">-</Text>
+  return <Tag color={STATUS_COLOR[status] || 'default'}>{status}</Tag>
+}
+
+function stateTag(state?: string) {
+  if (!state) return <Text type="secondary">-</Text>
+  return <Tag color={STATE_COLOR[state] || 'default'}>{state}</Tag>
+}
+
+function attemptTitle(result: HarnessRunResult) {
+  const label = HARNESS_LABEL[result.harness] || result.harness
+  return `${label} attempt ${result.attempt}`
+}
+
+function verifierDetails(result: HarnessRunResult) {
+  const details = result.verifier_summary?.details
+  if (!details || typeof details !== 'object' || !('results' in details)) return []
+  const results = (details as { results?: unknown }).results
+  return Array.isArray(results) ? results : []
+}
+
+function AttemptTimeline({ attempts }: { attempts: HarnessRunResult[] }) {
+  if (!attempts.length) {
+    return <Empty description="No harness attempts yet" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+  }
+
+  return (
+    <Timeline
+      items={attempts.map(result => ({
+        color: result.verifier_passed ? 'green' : 'red',
+        dot: result.verifier_passed ? <CheckCircleOutlined /> : <ToolOutlined />,
+        children: (
+          <Space direction="vertical" size={8} style={{ width: '100%' }}>
+            <Space wrap>
+              <Text strong>{attemptTitle(result)}</Text>
+              {statusTag(result.status)}
+              <Tag color={result.verifier_passed ? 'green' : 'red'}>
+                verifier {result.verifier_passed ? 'passed' : 'failed'}
+              </Tag>
+              <Text type="secondary">{formatMs(result.latency_ms)}</Text>
+            </Space>
+            {result.failure_reason && (
+              <Alert type="warning" showIcon message={result.failure_reason} style={{ borderRadius: 6 }} />
+            )}
+            <Row gutter={[12, 12]}>
+              <Col xs={24} md={12}>
+                <Text type="secondary">Input</Text>
+                <div style={{ marginTop: 6 }}>{renderJson(result.input_data)}</div>
+              </Col>
+              <Col xs={24} md={12}>
+                <Text type="secondary">Output</Text>
+                <div style={{ marginTop: 6 }}>{renderJson(result.output)}</div>
+              </Col>
+            </Row>
+            {verifierDetails(result).length > 0 && renderJson(verifierDetails(result))}
+          </Space>
+        ),
+      }))}
+    />
+  )
+}
+
+function RepairList({ repairs }: { repairs: Record<string, unknown>[] }) {
+  if (!repairs.length) {
+    return <Empty description="No repair was needed yet" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+  }
+  return (
+    <Space direction="vertical" size={12} style={{ width: '100%' }}>
+      {repairs.map((repair, index) => (
+        <div
+          key={`${String(repair.source || 'repair')}-${index}`}
+          style={{
+            border: '1px solid #edf0f3',
+            borderRadius: 8,
+            padding: 12,
+            background: '#fbfcfd',
+          }}
+        >
+          <Space wrap style={{ marginBottom: 8 }}>
+            <Tag color={repair.success ? 'green' : 'red'}>{repair.success ? 'applied' : 'failed'}</Tag>
+            <Tag>{String(repair.source || 'unknown')}</Tag>
+            <Text type="secondary">attempt {String(repair.attempt ?? index + 1)}</Text>
+          </Space>
+          {renderJson(repair)}
+        </div>
+      ))}
+    </Space>
+  )
+}
+
+export default function HarnessVerification() {
+  const location = useLocation()
+  const [skills, setSkills] = useState<SkillSummary[]>([])
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [harness, setHarness] = useState<HarnessKind>('local_skillos')
+  const [maxAttempts, setMaxAttempts] = useState(3)
+  const [timeoutS, setTimeoutS] = useState(120)
+  const [allowRepair, setAllowRepair] = useState(true)
+  const [promoteOnPass, setPromoteOnPass] = useState(true)
+  const [loading, setLoading] = useState(false)
+  const [running, setRunning] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [result, setResult] = useState<HarnessVerifyLoopResponse | null>(null)
+  const [recentLoops, setRecentLoops] = useState<HarnessVerifyLoopResponse[]>([])
+
+  const querySkillId = useMemo(() => new URLSearchParams(location.search).get('skill_id'), [location.search])
+
+  const draftSkills = useMemo(() => skills.filter(skill => skill.state === 'S2'), [skills])
+  const selectedSkill = useMemo(
+    () => skills.find(skill => skill.skill_id === selectedId) || null,
+    [selectedId, skills],
+  )
+
+  const loadData = useCallback(async (preferredId?: string | null) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const [skillList, loopList] = await Promise.all([
+        skillsApi.list({ limit: 200 }),
+        harnessApi.list(20).catch(() => ({ loops: [], total: 0 })),
+      ])
+      setSkills(skillList)
+      setRecentLoops(loopList.loops || [])
+      const preferred = preferredId || querySkillId || 'demo_draft_extract_email'
+      const preferredExists = skillList.some(skill => skill.skill_id === preferred)
+      const demoDraft = skillList.find(skill => skill.skill_id === 'demo_draft_extract_email' && skill.state === 'S2')
+      const firstDraft = skillList.find(skill => skill.state === 'S2')
+      setSelectedId(current => {
+        if (preferredExists) return preferred
+        if (current && skillList.some(skill => skill.skill_id === current)) return current
+        return demoDraft?.skill_id || firstDraft?.skill_id || null
+      })
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Load harness data failed'))
+    } finally {
+      setLoading(false)
+    }
+  }, [querySkillId])
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      void loadData()
+    }, 0)
+    return () => window.clearTimeout(timer)
+  }, [loadData])
+
+  const runVerification = async () => {
+    if (!selectedId) return
+    setRunning(true)
+    setError(null)
+    try {
+      const response = await harnessApi.runVerifyLoop(selectedId, {
+        harness,
+        max_attempts: maxAttempts,
+        promote_on_pass: promoteOnPass,
+        allow_repair: allowRepair,
+        timeout_s: timeoutS,
+      })
+      setResult(response)
+      setRecentLoops(prev => [response, ...prev.filter(loop => loop.loop_id !== response.loop_id)].slice(0, 20))
+      message.success(`Harness loop ${response.status}`)
+      await loadData(selectedId)
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Run verification loop failed'))
+    } finally {
+      setRunning(false)
+    }
+  }
+
+  const latest = result || recentLoops[0] || null
+  const overall = scoreNumber(latest?.score, 'overall')
+  const passRate = scoreNumber(latest?.score, 'verifier_pass_rate')
+
+  const loopColumns: TableColumnsType<HarnessVerifyLoopResponse> = [
+    {
+      title: 'Loop',
+      dataIndex: 'loop_id',
+      width: 190,
+      render: value => <Text code>{String(value)}</Text>,
+    },
+    {
+      title: 'Status',
+      dataIndex: 'status',
+      width: 150,
+      render: statusTag,
+    },
+    {
+      title: 'Score',
+      dataIndex: 'score',
+      width: 120,
+      render: score => formatPercent(scoreNumber(score as Record<string, unknown>, 'overall')),
+    },
+    {
+      title: 'Attempts',
+      dataIndex: 'attempt_count',
+      width: 110,
+      render: value => <Text>{String(value ?? '-')}</Text>,
+    },
+    {
+      title: 'Final State',
+      dataIndex: 'final_state',
+      width: 120,
+      render: stateTag,
+    },
+    {
+      title: 'Evidence',
+      dataIndex: 'evidence_path',
+      render: value => (
+        <Paragraph
+          copyable={typeof value === 'string' ? { text: value } : false}
+          ellipsis={{ rows: 1, expandable: true, symbol: 'more' }}
+          style={{ marginBottom: 0 }}
+        >
+          {String(value || '-')}
+        </Paragraph>
+      ),
+    },
+  ]
+
+  return (
+    <div style={{ padding: 24 }}>
+      <div style={{ marginBottom: 24 }}>
+        <Space wrap align="center" style={{ marginBottom: 4 }}>
+          <SafetyCertificateOutlined style={{ color: '#1677ff', fontSize: 22 }} />
+          <h2 style={{ margin: 0, fontWeight: 700 }}>Harness Verification</h2>
+        </Space>
+        <Paragraph type="secondary" style={{ maxWidth: 920, marginBottom: 0 }}>
+          Execute S2 Draft Skills in a controlled harness, verify deterministic postconditions, repair failures, and promote only passing Skills to S3.
+        </Paragraph>
+      </div>
+
+      {error && (
+        <Alert
+          type="error"
+          showIcon
+          closable
+          title="Harness request failed"
+          description={error}
+          style={{ marginBottom: 16 }}
+          onClose={() => setError(null)}
+        />
+      )}
+
+      <Spin spinning={loading && !running}>
+        <Row gutter={[16, 16]}>
+          <Col xs={24} lg={9}>
+            <Card title="Verification Control" variant="borderless" style={{ borderRadius: 8 }}>
+              <Space direction="vertical" size={16} style={{ width: '100%' }}>
+                <div>
+                  <Text strong>Draft Skill</Text>
+                  <Select
+                    showSearch
+                    value={selectedId || undefined}
+                    placeholder="Select an S2 Draft Skill"
+                    optionFilterProp="label"
+                    style={{ width: '100%', marginTop: 8 }}
+                    onChange={setSelectedId}
+                    options={draftSkills.map(skill => ({
+                      value: skill.skill_id,
+                      label: `${skill.name} · ${skill.version}`,
+                    }))}
+                    notFoundContent="No S2 Draft Skills available"
+                  />
+                </div>
+
+                {selectedSkill ? (
+                  <Alert
+                    type={selectedSkill.state === 'S2' ? 'info' : 'success'}
+                    showIcon
+                    message={(
+                      <Space wrap>
+                        <Text strong>{selectedSkill.name}</Text>
+                        {stateTag(selectedSkill.state)}
+                        <Tag>{selectedSkill.version}</Tag>
+                      </Space>
+                    )}
+                    description={(
+                      <Space direction="vertical" size={6} style={{ width: '100%' }}>
+                        <Text>{selectedSkill.description}</Text>
+                        <Space wrap>
+                          {(selectedSkill.evaluation.verifier_specs || []).slice(0, 3).map((spec, index) => (
+                            <Tag key={`${selectedSkill.skill_id}-spec-${index}`} color="blue">
+                              {String(spec.type || 'verifier')}
+                            </Tag>
+                          ))}
+                        </Space>
+                        {selectedSkill.evaluation.validation_summary && (
+                          <Text type="secondary">{selectedSkill.evaluation.validation_summary}</Text>
+                        )}
+                      </Space>
+                    )}
+                  />
+                ) : (
+                  <Empty description="Select a Draft Skill to verify" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+                )}
+
+                <div>
+                  <Text strong>Harness</Text>
+                  <Segmented
+                    block
+                    value={harness}
+                    onChange={value => setHarness(value as HarnessKind)}
+                    style={{ marginTop: 8 }}
+                    options={[
+                      { label: 'Local', value: 'local_skillos' },
+                      { label: 'Codex CLI', value: 'codex_cli' },
+                      { label: 'Claude Code', value: 'claude_code', disabled: true },
+                    ]}
+                  />
+                </div>
+
+                <Row gutter={12}>
+                  <Col span={12}>
+                    <Text strong>Max Attempts</Text>
+                    <InputNumber
+                      min={1}
+                      max={5}
+                      value={maxAttempts}
+                      onChange={value => setMaxAttempts(value || 3)}
+                      style={{ width: '100%', marginTop: 8 }}
+                    />
+                  </Col>
+                  <Col span={12}>
+                    <Text strong>Timeout</Text>
+                    <InputNumber
+                      min={1}
+                      max={600}
+                      value={timeoutS}
+                      addonAfter="s"
+                      onChange={value => setTimeoutS(value || 120)}
+                      style={{ width: '100%', marginTop: 8 }}
+                    />
+                  </Col>
+                </Row>
+
+                <Space direction="vertical" size={10}>
+                  <Space>
+                    <Switch checked={allowRepair} onChange={setAllowRepair} />
+                    <Text>Allow repair and retry</Text>
+                  </Space>
+                  <Space>
+                    <Switch checked={promoteOnPass} onChange={setPromoteOnPass} />
+                    <Text>Promote to S3 on pass</Text>
+                  </Space>
+                </Space>
+
+                <Space wrap>
+                  <Button icon={<ReloadOutlined />} onClick={() => void loadData(selectedId)} disabled={running}>
+                    Refresh
+                  </Button>
+                  <Button
+                    type="primary"
+                    icon={<PlayCircleOutlined />}
+                    loading={running}
+                    disabled={!selectedSkill || selectedSkill.state !== 'S2'}
+                    onClick={runVerification}
+                  >
+                    Run Verification Loop
+                  </Button>
+                </Space>
+              </Space>
+            </Card>
+          </Col>
+
+          <Col xs={24} lg={15}>
+            <Row gutter={[16, 16]}>
+              <Col xs={24} md={8}>
+                <Card variant="borderless" style={{ borderRadius: 8 }}>
+                  <Text type="secondary">Latest Status</Text>
+                  <div style={{ marginTop: 12 }}>
+                    {latest ? statusTag(latest.status) : <Tag>no run</Tag>}
+                  </div>
+                </Card>
+              </Col>
+              <Col xs={24} md={8}>
+                <Card variant="borderless" style={{ borderRadius: 8 }}>
+                  <Text type="secondary">Overall Score</Text>
+                  <Progress percent={percent(overall)} size="small" style={{ marginTop: 14 }} />
+                  <Text strong>{formatPercent(overall)}</Text>
+                </Card>
+              </Col>
+              <Col xs={24} md={8}>
+                <Card variant="borderless" style={{ borderRadius: 8 }}>
+                  <Text type="secondary">Verifier Pass Rate</Text>
+                  <Progress percent={percent(passRate)} size="small" status={passRate >= 1 ? 'success' : 'active'} style={{ marginTop: 14 }} />
+                  <Text strong>{formatPercent(passRate)}</Text>
+                </Card>
+              </Col>
+            </Row>
+
+            <Card
+              title="Latest Evidence"
+              extra={latest ? <Text type="secondary">{latest.loop_id}</Text> : null}
+              variant="borderless"
+              style={{ borderRadius: 8, marginTop: 16 }}
+            >
+              {latest ? (
+                <Space direction="vertical" size={16} style={{ width: '100%' }}>
+                  <Descriptions size="small" column={{ xs: 1, md: 3 }} bordered>
+                    <Descriptions.Item label="Skill">{latest.skill_id}</Descriptions.Item>
+                    <Descriptions.Item label="Version">
+                      {latest.initial_version}
+                      {' -> '}
+                      {latest.final_version}
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Final State">{stateTag(latest.final_state)}</Descriptions.Item>
+                    <Descriptions.Item label="Attempts">{latest.attempt_count}</Descriptions.Item>
+                    <Descriptions.Item label="Promotion">{latest.promotion_allowed ? <Tag color="green">allowed</Tag> : <Tag>blocked</Tag>}</Descriptions.Item>
+                    <Descriptions.Item label="Latency">{formatMs(latest.score.latency_ms)}</Descriptions.Item>
+                  </Descriptions>
+                  <Alert
+                    type={latest.status === 'verified' ? 'success' : 'warning'}
+                    showIcon
+                    message="Evidence Path"
+                    description={(
+                      <Text copyable={{ text: latest.evidence_path }} style={{ wordBreak: 'break-all' }}>
+                        {latest.evidence_path}
+                      </Text>
+                    )}
+                  />
+                  <AttemptTimeline attempts={latest.attempts || []} />
+                </Space>
+              ) : (
+                <Empty description="Run a verification loop to create evidence" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+              )}
+            </Card>
+          </Col>
+        </Row>
+
+        <Row gutter={[16, 16]} style={{ marginTop: 16 }}>
+          <Col xs={24} lg={9}>
+            <Card title="Repair Evidence" variant="borderless" style={{ borderRadius: 8 }}>
+              <RepairList repairs={latest?.repairs || []} />
+            </Card>
+          </Col>
+          <Col xs={24} lg={15}>
+            <Card
+              title="Recent Harness Loops"
+              extra={<Text type="secondary">{recentLoops.length} saved</Text>}
+              variant="borderless"
+              style={{ borderRadius: 8 }}
+            >
+              <Table
+                dataSource={recentLoops}
+                columns={loopColumns}
+                rowKey="loop_id"
+                size="small"
+                pagination={{ pageSize: 6 }}
+                scroll={{ x: 900 }}
+                locale={{ emptyText: 'No saved harness evidence yet' }}
+              />
+            </Card>
+          </Col>
+        </Row>
+
+        <Alert
+          type="info"
+          showIcon
+          icon={<FileProtectOutlined />}
+          style={{ marginTop: 16, borderRadius: 8 }}
+          message="Demo path"
+          description="Use the seeded demo_draft_extract_email Draft Skill with Local SkillWiki. The first attempt fails because output.email is missing, the repair loop patches the implementation, and the repaired version is promoted to S3 after verifier pass."
+        />
+      </Spin>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/KnowledgeImport.tsx

@@ -0,0 +1,1293 @@
+import { useState } from 'react'
+import {
+  Alert, Badge, Button, Card, Col, Collapse, Descriptions, Divider, Input, Progress,
+  Row, Select, Space, Steps, Tabs, Tag, Typography, Upload,
+} from 'antd'
+import type { UploadProps } from 'antd'
+import {
+  ApiOutlined, CheckCircleOutlined, CloudUploadOutlined, CodeOutlined,
+  CompressOutlined, DatabaseOutlined, FileSearchOutlined, FileTextOutlined,
+  FilterOutlined, LoadingOutlined, PlayCircleOutlined, SafetyCertificateOutlined,
+} from '@ant-design/icons'
+import { AnimatePresence, motion } from 'framer-motion'
+import { Link, useNavigate } from 'react-router-dom'
+import { ingestApi, lifecycleApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  CandidateAuditResult,
+  CandidateSkillReviewRequest,
+  CreatedSkill,
+  ExperienceUnit,
+  IngestResponse,
+  SkillEvaluation,
+  SkillProvenance,
+  SkillType,
+} from '@/api/types'
+
+const { TextArea } = Input
+const { Dragger } = Upload
+const { Paragraph, Text } = Typography
+const MAX_IMPORT_FILE_BYTES = 2 * 1024 * 1024
+
+const SOURCE_TYPES = [
+  {
+    key: 'trajectory',
+    label: 'Trajectory',
+    icon: <PlayCircleOutlined />,
+    color: '#1677ff',
+    placeholder: `Paste a trajectory, for example:
+1. Open https://example.com/login
+2. Click the username field
+3. Type admin
+4. Click the password field
+5. Type the password
+6. Click the login button
+7. Wait for dashboard navigation and confirm success`,
+  },
+  {
+    key: 'document',
+    label: 'Document',
+    icon: <FileTextOutlined />,
+    color: '#52c41a',
+    placeholder: `Paste a technical note or operating procedure.
+
+Include inputs, expected outputs, constraints, and reusable steps where possible.`,
+  },
+  {
+    key: 'api_doc',
+    label: 'API Doc',
+    icon: <ApiOutlined />,
+    color: '#722ed1',
+    placeholder: `Paste an API document or OpenAPI fragment.
+
+POST /api/login
+Request: { "username": "string", "password": "string" }
+Response: { "token": "string", "user_id": "string" }`,
+  },
+  {
+    key: 'script',
+    label: 'Script',
+    icon: <CodeOutlined />,
+    color: '#fa8c16',
+    placeholder: `Paste Python, JavaScript, or shell code.
+
+async def login(page, username: str, password: str) -> bool:
+    await page.goto("https://example.com/login")
+    await page.fill("#username", username)
+    await page.fill("#password", password)
+    await page.click("#submit")
+    return True`,
+  },
+  {
+    key: 'past_skills',
+    label: 'Past Skills',
+    icon: <DatabaseOutlined />,
+    color: '#13c2c2',
+    placeholder: `Paste legacy Skill JSON, YAML, Markdown, or free text.
+
+[
+  {
+    "name": "legacy_login_flow",
+    "description": "Log in by filling credentials and waiting for the dashboard.",
+    "steps": ["open login page", "fill username", "fill password", "click submit"],
+    "dependencies": ["click_element", "type_text"],
+    "skill_type": "functional"
+  }
+]`,
+  },
+]
+
+const TYPE_COLOR: Record<string, string> = {
+  atomic: 'blue',
+  functional: 'purple',
+  strategic: 'gold',
+}
+
+const PIPELINE_STAGES = [
+  { title: 'Extractor', icon: <FilterOutlined />, desc: 'Extract source-local actions' },
+  { title: 'Normalizer', icon: <CompressOutlined />, desc: 'Normalize experience structure' },
+  { title: 'Summarizer', icon: <FileSearchOutlined />, desc: 'Draft candidate Skill evidence' },
+  { title: 'Indexer', icon: <DatabaseOutlined />, desc: 'Prepare search keywords' },
+]
+
+const PREVIEW_BLOCK_STYLE = {
+  background: '#f6f8fa',
+  border: '1px solid #edf0f3',
+  borderRadius: 8,
+  padding: 12,
+  whiteSpace: 'pre-wrap' as const,
+  wordBreak: 'break-word' as const,
+  maxHeight: 220,
+  overflow: 'auto',
+  fontSize: 12,
+}
+
+type SourceType = typeof SOURCE_TYPES[number]['key']
+
+interface ApiDocContract {
+  kind: 'api_doc'
+  title: string
+  method: string
+  endpoint: string
+  requiredParams: string[]
+  optionalParams: string[]
+  requestSchema: Record<string, unknown>
+  responseSchema: Record<string, unknown>
+  exampleCall: string
+}
+
+interface ScriptContract {
+  kind: 'script'
+  title: string
+  language: string
+  entrypoint: string
+  args: string[]
+  returns: string
+  dependencies: string[]
+  sideEffects: string[]
+  runnableHint: string
+  codeSnippet: string
+}
+
+type ResourceContract = ApiDocContract | ScriptContract | null
+
+const RESOURCE_EXAMPLES: { sourceType: SourceType; title: string; content: string }[] = [
+  {
+    sourceType: 'api_doc',
+    title: 'Login API',
+    content: `POST /api/login
+Description: Exchange user credentials for a bearer token.
+Request: { "username": "string", "password": "string" }
+Response: { "token": "string", "user_id": "string", "expires_at": "string" }
+Errors: 401 when credentials are invalid.`,
+  },
+  {
+    sourceType: 'api_doc',
+    title: 'Weather API',
+    content: `GET /v1/weather/current
+Description: Fetch current weather by city.
+Params: { "city": "string", "units": "metric|imperial" }
+Response: { "city": "string", "temperature": "number", "condition": "string", "observed_at": "string" }`,
+  },
+  {
+    sourceType: 'script',
+    title: 'Playwright Login',
+    content: `async def login(page, username: str, password: str) -> bool:
+    await page.goto("https://example.com/login")
+    await page.fill("#username", username)
+    await page.fill("#password", password)
+    await page.click("#submit")
+    await page.wait_for_url("**/dashboard")
+    return True`,
+  },
+  {
+    sourceType: 'script',
+    title: 'CSV Validator',
+    content: `import csv
+
+def validate_orders_csv(path: str) -> dict:
+    rows = list(csv.DictReader(open(path, encoding="utf-8")))
+    missing = [i for i, row in enumerate(rows, start=1) if not row.get("order_id")]
+    return {"row_count": len(rows), "missing_order_id_rows": missing, "ok": not missing}`,
+  },
+  {
+    sourceType: 'past_skills',
+    title: 'Legacy Login Skill',
+    content: `[
+  {
+    "name": "legacy_login_flow",
+    "description": "Log in by filling credentials and waiting for the dashboard.",
+    "steps": ["open login page", "fill username", "fill password", "click submit"],
+    "dependencies": ["click_element", "type_text"],
+    "skill_type": "functional",
+    "input_schema": {
+      "type": "object",
+      "properties": {
+        "username": { "type": "string" },
+        "password": { "type": "string" }
+      },
+      "required": ["username", "password"]
+    }
+  }
+]`,
+  },
+]
+
+interface CandidateDraft {
+  name: string
+  description: string
+  skillType: SkillType
+  tagsText: string
+  inputSchemaText: string
+  outputSchemaText: string
+  preconditionsText: string
+  postconditionsText: string
+  promptTemplate: string
+  provenanceText: string
+  evaluationText: string
+  dependencyIds: string[]
+  componentIds: string[]
+  subSkillIds: string[]
+  parentSkillIds: string[]
+  toolCalls: string[]
+}
+
+function toJson(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+function linesFromText(value: string): string[] {
+  return value
+    .split(/\r?\n/)
+    .map(item => item.trim())
+    .filter(Boolean)
+}
+
+function tagsFromText(value: string): string[] {
+  return value
+    .split(',')
+    .map(item => item.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+function toSnakeCase(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+  const safe = normalized || 'imported_skill'
+  return /^[a-z]/.test(safe) ? safe.slice(0, 96) : `skill_${safe}`.slice(0, 96)
+}
+
+function isSkillType(value?: string): value is SkillType {
+  return value === 'atomic' || value === 'functional' || value === 'strategic'
+}
+
+function parseJsonObject<T>(value: string, label: string): T {
+  const parsed = JSON.parse(value) as T
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} must be a JSON object`)
+  }
+  return parsed
+}
+
+function parseLooseJsonObject(value: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(value)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    return {}
+  }
+  return {}
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.map(item => String(item).trim()).filter(Boolean)
+    : []
+}
+
+function metadataRecord(unit: ExperienceUnit | null | undefined): Record<string, unknown> {
+  return asRecord(unit?.metadata) ?? {}
+}
+
+function nestedRecord(parent: Record<string, unknown>, key: string): Record<string, unknown> {
+  return asRecord(parent[key]) ?? {}
+}
+
+function extractJsonAfterLabel(content: string, label: string): Record<string, unknown> {
+  const pattern = new RegExp(`(?:${label})\\s*:?\\s*(\\{[^\\n]+\\})`, 'i')
+  const match = content.match(pattern)
+  return match ? parseLooseJsonObject(match[1]) : {}
+}
+
+function inferJsonValueType(value: unknown): string {
+  if (Array.isArray(value)) return 'array'
+  if (value === null) return 'string'
+  return typeof value === 'number' || typeof value === 'boolean' || typeof value === 'object'
+    ? typeof value
+    : 'string'
+}
+
+function schemaFromObject(value: Record<string, unknown>, fallbackDescription: string): Record<string, unknown> {
+  const properties = Object.fromEntries(
+    Object.entries(value).map(([key, fieldValue]) => [
+      key,
+      {
+        type: inferJsonValueType(fieldValue),
+        description: `${key} from parsed resource contract.`,
+      },
+    ]),
+  )
+  return {
+    type: 'object',
+    properties: Object.keys(properties).length ? properties : {
+      payload: {
+        type: 'object',
+        description: fallbackDescription,
+      },
+    },
+    required: Object.keys(properties),
+  }
+}
+
+function buildResourceContract(sourceType: SourceType, content: string): ResourceContract {
+  if (!content.trim()) return null
+
+  if (sourceType === 'api_doc') {
+    const firstLine = linesFromText(content)[0] ?? ''
+    const routeMatch = content.match(/\b(GET|POST|PUT|PATCH|DELETE)\s+([/\w{}:.-]+)/i)
+    const requestSchema = extractJsonAfterLabel(content, 'Request|Params|Parameters')
+    const responseSchema = extractJsonAfterLabel(content, 'Response|Returns')
+    const requiredParams = Object.keys(requestSchema)
+    const title = firstLine.replace(/\b(GET|POST|PUT|PATCH|DELETE)\b/i, '').trim() || 'API skill'
+    return {
+      kind: 'api_doc',
+      title,
+      method: (routeMatch?.[1] ?? 'POST').toUpperCase(),
+      endpoint: routeMatch?.[2] ?? '/api/unknown',
+      requiredParams,
+      optionalParams: [],
+      requestSchema,
+      responseSchema,
+      exampleCall: `${(routeMatch?.[1] ?? 'POST').toUpperCase()} ${routeMatch?.[2] ?? '/api/unknown'}`,
+    }
+  }
+
+  if (sourceType === 'script') {
+    const language = /\basync\s+function\b|\bconst\s+\w+\s*=\s*async\b|\bfunction\s+\w+\s*\(/.test(content)
+      ? 'javascript'
+      : /\bdef\s+\w+\s*\(/.test(content)
+        ? 'python'
+        : content.trimStart().startsWith('#!') ? 'shell' : 'script'
+    const functionMatch = content.match(/\b(?:async\s+)?def\s+(\w+)\s*\(([^)]*)\)\s*(?:->\s*([^:\n]+))?:/i)
+      ?? content.match(/\b(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/i)
+    const entrypoint = functionMatch?.[1] ?? 'main'
+    const args = (functionMatch?.[2] ?? '')
+      .split(',')
+      .map(item => item.trim().split(':')[0].trim())
+      .filter(Boolean)
+    const returns = functionMatch?.[3]?.trim() ?? (/\breturn\s+/.test(content) ? 'inferred from return statement' : 'side effects only')
+    const dependencies = Array.from(new Set([
+      ...Array.from(content.matchAll(/^\s*import\s+([\w.]+)/gm)).map(match => match[1]),
+      ...Array.from(content.matchAll(/^\s*from\s+([\w.]+)\s+import/gm)).map(match => match[1]),
+      ...Array.from(content.matchAll(/require\(["']([^"']+)["']\)/g)).map(match => match[1]),
+    ]))
+    const sideEffects = [
+      /page\.|browser\.|goto\(|click\(|fill\(/.test(content) ? 'browser automation' : '',
+      /open\(|write|append|csv\.|fs\./.test(content) ? 'file IO' : '',
+      /fetch\(|axios|requests\.|http/.test(content) ? 'network call' : '',
+    ].filter(Boolean)
+    return {
+      kind: 'script',
+      title: entrypoint,
+      language,
+      entrypoint,
+      args,
+      returns,
+      dependencies,
+      sideEffects,
+      runnableHint: args.length ? `${entrypoint}(${args.join(', ')})` : entrypoint,
+      codeSnippet: content.slice(0, 800),
+    }
+  }
+
+  return null
+}
+
+function contractInputSchema(contract: ResourceContract): Record<string, unknown> | null {
+  if (!contract) return null
+  if (contract.kind === 'api_doc') {
+    return schemaFromObject(contract.requestSchema, `Request payload for ${contract.method} ${contract.endpoint}.`)
+  }
+  return {
+    type: 'object',
+    properties: Object.fromEntries(
+      contract.args.map(arg => [
+        arg,
+        {
+          type: 'string',
+          description: `Argument for ${contract.entrypoint}.`,
+        },
+      ]),
+    ),
+    required: contract.args,
+  }
+}
+
+function contractOutputSchema(contract: ResourceContract): Record<string, unknown> | null {
+  if (!contract) return null
+  if (contract.kind === 'api_doc') {
+    return schemaFromObject(contract.responseSchema, `Response payload from ${contract.method} ${contract.endpoint}.`)
+  }
+  return {
+    type: 'object',
+    properties: {
+      result: {
+        type: 'object',
+        description: contract.returns,
+      },
+      ok: {
+        type: 'boolean',
+        description: 'Whether the script completed successfully.',
+      },
+    },
+    required: ['result'],
+  }
+}
+
+function buildCandidateDraft(unit: ExperienceUnit, sourceType: SourceType): CandidateDraft {
+  const metadata = metadataRecord(unit)
+  const candidateInterface = nestedRecord(metadata, 'candidate_interface')
+  const candidateImplementation = nestedRecord(metadata, 'candidate_implementation')
+  const candidateRelations = nestedRecord(metadata, 'candidate_relations')
+  const evidence = nestedRecord(metadata, 'ctx2skill_evidence')
+  const selectedCandidate = nestedRecord(evidence, 'selected_candidate')
+  const name = toSnakeCase(unit.proposed_skill_name || `skill_from_${sourceType}_${unit.unit_id}`)
+  const description = unit.proposed_description || unit.summary || `Candidate Skill imported from ${sourceType}.`
+  const skillType = isSkillType(unit.proposed_type) ? unit.proposed_type : 'atomic'
+  const metadataTags = asStringArray(metadata.candidate_tags)
+  const tags = Array.from(new Set([sourceType, 'candidate-review', ...metadataTags, ...unit.index_keywords.slice(0, 3)]))
+  const contract = buildResourceContract(sourceType, unit.raw_content)
+
+  const inputSchema = asRecord(candidateInterface.input_schema) ?? contractInputSchema(contract) ?? {
+    type: 'object',
+    properties: {
+      context: {
+        type: 'object',
+        description: 'Runtime context distilled from the imported source experience.',
+      },
+    },
+  }
+  const outputSchema = asRecord(candidateInterface.output_schema) ?? contractOutputSchema(contract) ?? {
+    type: 'object',
+    properties: {
+      result: {
+        type: 'object',
+        description: 'Structured result produced by the candidate Skill.',
+      },
+    },
+  }
+  const parentSkillIds = asStringArray(candidateRelations.parent_skill_ids)
+  const dependencyIds = asStringArray(candidateRelations.dependency_ids)
+  const componentIds = asStringArray(candidateRelations.component_ids)
+  const subSkillIds = asStringArray(candidateImplementation.sub_skill_ids)
+  const toolCalls = asStringArray(candidateImplementation.tool_calls)
+  const provenance: SkillProvenance = {
+    source_type: sourceType,
+    source_ids: [unit.unit_id],
+    parent_skill_ids: parentSkillIds,
+    created_by_agent: 'human_reviewer',
+    creation_context: {
+      import_unit_id: unit.unit_id,
+      source_confidence: unit.confidence,
+      index_keywords: unit.index_keywords,
+      raw_content_preview: unit.raw_content,
+      resource_contract: contract,
+      ctx2skill_evidence: metadata.ctx2skill_evidence ?? null,
+      layering_reason: metadata.layering_reason ?? null,
+      graph_relation_preview: metadata.graph_relation_preview ?? [],
+    },
+  }
+  const verifierDescription = sourceType === 'document' || sourceType === 'past_skills'
+    ? 'Replace Ctx2Skill-lite challenge replay with a deterministic verifier before S3/S4 release.'
+    : 'Replace with deterministic verifier before S3/S4 release.'
+  const evaluation: SkillEvaluation = {
+    verifier_specs: [
+      {
+        type: 'placeholder',
+        description: verifierDescription,
+      },
+    ],
+    test_case_refs: [],
+    benchmark_task_ids: [],
+    validation_summary: 'Pending human validation. This Skill remains Candidate (S1).',
+  }
+
+  const contractPrompt = contract?.kind === 'api_doc'
+    ? `Call ${contract.method} ${contract.endpoint} with reviewed parameters and validate the response schema.`
+    : contract?.kind === 'script'
+      ? `Run or adapt ${contract.entrypoint} using the reviewed arguments. Runnable hint: ${contract.runnableHint}.`
+      : String(candidateImplementation.prompt_template || selectedCandidate.prompt_template || unit.summary || description)
+  const metadataPreconditions = asStringArray(candidateInterface.preconditions)
+  const metadataPostconditions = asStringArray(candidateInterface.postconditions)
+
+  return {
+    name,
+    description,
+    skillType,
+    tagsText: tags.join(', '),
+    inputSchemaText: toJson(inputSchema),
+    outputSchemaText: toJson(outputSchema),
+    preconditionsText: metadataPreconditions.length
+      ? metadataPreconditions.join('\n')
+      : contract?.kind === 'api_doc'
+      ? `Endpoint ${contract.endpoint} is reachable.\nRequired parameters are available: ${contract.requiredParams.join(', ') || 'reviewed request payload'}.`
+      : contract?.kind === 'script'
+        ? `Runtime supports ${contract.language}.\nDependencies are available: ${contract.dependencies.join(', ') || 'none detected'}.`
+        : '',
+    postconditionsText: metadataPostconditions.length
+      ? metadataPostconditions.join('\n')
+      : contract?.kind === 'api_doc'
+      ? `Response conforms to the reviewed schema for ${contract.method} ${contract.endpoint}.`
+      : contract?.kind === 'script'
+        ? `Entrypoint ${contract.entrypoint} completes and returns ${contract.returns}.`
+        : 'The Skill returns a structured result aligned with the reviewed source experience.',
+    promptTemplate: contractPrompt,
+    provenanceText: toJson(provenance),
+    evaluationText: toJson(evaluation),
+    dependencyIds,
+    componentIds,
+    subSkillIds,
+    parentSkillIds,
+    toolCalls,
+  }
+}
+
+export default function KnowledgeImport() {
+  const navigate = useNavigate()
+  const [activeTab, setActiveTab] = useState<SourceType>('trajectory')
+  const [content, setContent] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [auditing, setAuditing] = useState(false)
+  const [creating, setCreating] = useState(false)
+  const [promoting, setPromoting] = useState(false)
+  const [pipelineStage, setPipelineStage] = useState(-1)
+  const [result, setResult] = useState<IngestResponse | null>(null)
+  const [selectedUnitId, setSelectedUnitId] = useState<string | null>(null)
+  const [drafts, setDrafts] = useState<Record<string, CandidateDraft>>({})
+  const [auditResult, setAuditResult] = useState<CandidateAuditResult | null>(null)
+  const [createdSkill, setCreatedSkill] = useState<CreatedSkill | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [loadedFileName, setLoadedFileName] = useState<string | null>(null)
+
+  const currentSource = SOURCE_TYPES.find(s => s.key === activeTab)!
+  const selectedUnit = result?.units.find(unit => unit.unit_id === selectedUnitId) ?? result?.units[0] ?? null
+  const currentDraft = selectedUnit ? drafts[selectedUnit.unit_id] : undefined
+  const sourceContract = buildResourceContract(activeTab, content)
+  const selectedMetadata = metadataRecord(selectedUnit)
+  const selectedEvidence = nestedRecord(selectedMetadata, 'ctx2skill_evidence')
+  const selectedGraphPreview = Array.isArray(selectedMetadata.graph_relation_preview)
+    ? selectedMetadata.graph_relation_preview
+    : []
+  const selectedLayeringReason = typeof selectedMetadata.layering_reason === 'string'
+    ? selectedMetadata.layering_reason
+    : ''
+
+  const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+  const resetReviewState = () => {
+    setAuditResult(null)
+    setCreatedSkill(null)
+  }
+
+  const resetParsedContentState = () => {
+    setResult(null)
+    setDrafts({})
+    setSelectedUnitId(null)
+    resetReviewState()
+  }
+
+  const handleFileBeforeUpload: UploadProps['beforeUpload'] = async file => {
+    if (file.size > MAX_IMPORT_FILE_BYTES) {
+      setError('File is too large for browser-side import. Use a file under 2 MB.')
+      return Upload.LIST_IGNORE
+    }
+
+    try {
+      const text = await file.text()
+      setContent(text)
+      setLoadedFileName(file.name)
+      setError(null)
+      resetParsedContentState()
+    } catch {
+      setError('Could not read this file as text.')
+    }
+    return Upload.LIST_IGNORE
+  }
+
+  const handleParse = async () => {
+    if (!content.trim()) {
+      setError('Please enter source content first.')
+      return
+    }
+
+    setLoading(true)
+    setResult(null)
+    setError(null)
+    resetReviewState()
+    setPipelineStage(0)
+
+    try {
+      const stagePromise = (async () => {
+        for (let i = 0; i < PIPELINE_STAGES.length; i += 1) {
+          setPipelineStage(i)
+          await sleep(300)
+        }
+      })()
+
+      const [res] = await Promise.all([ingestApi.parse(activeTab, content), stagePromise])
+      const nextDrafts = Object.fromEntries(
+        res.units.map(unit => [unit.unit_id, buildCandidateDraft(unit, activeTab)]),
+      )
+      setPipelineStage(PIPELINE_STAGES.length)
+      setResult(res)
+      setDrafts(nextDrafts)
+      setSelectedUnitId(res.units[0]?.unit_id ?? null)
+    } catch (e: unknown) {
+      setError(getApiErrorMessage(e, 'Parse failed'))
+      setPipelineStage(-1)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const updateDraft = (patch: Partial<CandidateDraft>) => {
+    if (!selectedUnit) return
+    setDrafts(prev => ({
+      ...prev,
+      [selectedUnit.unit_id]: {
+        ...prev[selectedUnit.unit_id],
+        ...patch,
+      },
+    }))
+  }
+
+  const buildPayload = (): CandidateSkillReviewRequest => {
+    if (!selectedUnit || !currentDraft) {
+      throw new Error('Select a parsed experience unit first.')
+    }
+    const inputSchema = parseJsonObject<Record<string, unknown>>(currentDraft.inputSchemaText, 'Input schema')
+    const outputSchema = parseJsonObject<Record<string, unknown>>(currentDraft.outputSchemaText, 'Output schema')
+    const provenance = parseJsonObject<SkillProvenance>(currentDraft.provenanceText, 'Provenance')
+    const evaluation = parseJsonObject<SkillEvaluation>(currentDraft.evaluationText, 'Evaluation')
+    return {
+      source_type: activeTab,
+      unit_id: selectedUnit.unit_id,
+      raw_content: selectedUnit.raw_content || content,
+      name: toSnakeCase(currentDraft.name),
+      description: currentDraft.description.trim(),
+      skill_type: currentDraft.skillType,
+      tags: tagsFromText(currentDraft.tagsText),
+      input_schema: inputSchema,
+      output_schema: outputSchema,
+      preconditions: linesFromText(currentDraft.preconditionsText),
+      postconditions: linesFromText(currentDraft.postconditionsText),
+      prompt_template: currentDraft.promptTemplate,
+      provenance,
+      evaluation,
+      dependency_ids: currentDraft.dependencyIds,
+      component_ids: currentDraft.componentIds,
+      sub_skill_ids: currentDraft.subSkillIds,
+      parent_skill_ids: currentDraft.parentSkillIds,
+      tool_calls: currentDraft.toolCalls,
+      author: 'human_reviewer',
+    }
+  }
+
+  const handleRunAudit = async () => {
+    try {
+      setAuditing(true)
+      setError(null)
+      const audit = await ingestApi.auditCandidate(buildPayload())
+      setAuditResult(audit)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : getApiErrorMessage(err, 'Audit failed'))
+    } finally {
+      setAuditing(false)
+    }
+  }
+
+  const handleCreateCandidate = async () => {
+    try {
+      setCreating(true)
+      setError(null)
+      const response = await ingestApi.createCandidate(buildPayload())
+      setCreatedSkill(response.created_skill)
+      setAuditResult(response.audit)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : getApiErrorMessage(err, 'Create candidate failed'))
+    } finally {
+      setCreating(false)
+    }
+  }
+
+  const handlePromoteDraft = async () => {
+    if (!createdSkill) return
+    try {
+      setPromoting(true)
+      setError(null)
+      const promoted = await lifecycleApi.transition(
+        createdSkill.skill_id,
+        'S2',
+        'Promoted from reviewed import candidate',
+      )
+      setCreatedSkill({ ...createdSkill, state: promoted.state })
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Promote draft failed'))
+    } finally {
+      setPromoting(false)
+    }
+  }
+
+  const selectUnit = (unitId: string) => {
+    setSelectedUnitId(unitId)
+    resetReviewState()
+  }
+
+  return (
+    <div style={{ padding: 24 }}>
+      <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }}>
+        <h2 style={{ fontWeight: 700, marginBottom: 4 }}>Knowledge Import</h2>
+        <p style={{ color: '#666', marginBottom: 24 }}>
+          Parse experience sources into editable Candidate Skills. Imported Skills stay Candidate (S1)
+          until a human reviewer audits, creates, and optionally promotes them to Draft (S2).
+        </p>
+      </motion.div>
+
+      {error && (
+        <Alert
+          type="error"
+          showIcon
+          closable
+          title="Parse failed"
+          description={error}
+          style={{ marginBottom: 16 }}
+          onClose={() => setError(null)}
+        />
+      )}
+
+      <Row gutter={[16, 16]}>
+        <Col xs={24} lg={10}>
+          <Card variant="borderless" style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+            <Tabs
+              activeKey={activeTab}
+              onChange={key => {
+                setActiveTab(key as SourceType)
+                setContent('')
+                setLoadedFileName(null)
+                setError(null)
+                resetParsedContentState()
+              }}
+              items={SOURCE_TYPES.map(source => ({
+                key: source.key,
+                label: <span>{source.icon} {source.label}</span>,
+                children: null,
+              }))}
+            />
+
+            <Tag color={currentSource.color} style={{ marginBottom: 8 }}>
+              {currentSource.icon} {currentSource.label}
+            </Tag>
+
+            <TextArea
+              value={content}
+              onChange={event => {
+                setContent(event.target.value)
+                setLoadedFileName(null)
+              }}
+              placeholder={currentSource.placeholder}
+              rows={15}
+              style={{ fontFamily: 'monospace', fontSize: 13 }}
+            />
+
+            <Dragger
+              accept=".txt,.md,.markdown,.json,.jsonl,.yaml,.yml,.py,.js,.ts,.tsx,.sh,.bash,.csv,.log,.html,.xml"
+              beforeUpload={handleFileBeforeUpload}
+              multiple={false}
+              showUploadList={false}
+              style={{ marginTop: 12, padding: '6px 0', background: '#fafafa' }}
+            >
+              <p className="ant-upload-drag-icon" style={{ marginBottom: 4 }}>
+                <CloudUploadOutlined style={{ color: currentSource.color }} />
+              </p>
+              <p className="ant-upload-text" style={{ marginBottom: 0 }}>
+                Drop a source file here or click to choose one
+              </p>
+              <p className="ant-upload-hint" style={{ marginBottom: 0 }}>
+                The file is read locally into this {currentSource.label} input. Nothing is created until you parse and review it.
+              </p>
+            </Dragger>
+
+            {loadedFileName && (
+              <Alert
+                type="success"
+                showIcon
+                style={{ marginTop: 10 }}
+                message={`Loaded ${loadedFileName}`}
+                description="Review the text above, then parse it for Candidate Review."
+              />
+            )}
+
+            {(activeTab === 'api_doc' || activeTab === 'script' || activeTab === 'past_skills') && (
+              <Space wrap style={{ marginTop: 10 }}>
+                {RESOURCE_EXAMPLES
+                  .filter(example => example.sourceType === activeTab)
+                  .map(example => (
+                    <Button
+                      key={example.title}
+                      size="small"
+                      onClick={() => {
+                        setContent(example.content)
+                        setLoadedFileName(null)
+                        resetParsedContentState()
+                      }}
+                    >
+                      {example.title}
+                    </Button>
+                  ))}
+              </Space>
+            )}
+
+            {sourceContract && (
+              <Card size="small" style={{ marginTop: 12, background: '#fafafa', borderRadius: 8 }}>
+                {sourceContract.kind === 'api_doc' ? (
+                  <Descriptions size="small" column={1}>
+                    <Descriptions.Item label="Endpoint">
+                      <Space><Tag color="purple">{sourceContract.method}</Tag><Text code>{sourceContract.endpoint}</Text></Space>
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Params">
+                      {sourceContract.requiredParams.length
+                        ? sourceContract.requiredParams.map(param => <Tag key={param}>{param}</Tag>)
+                        : <Text type="secondary">No explicit request fields detected</Text>}
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Response schema">
+                      <pre style={PREVIEW_BLOCK_STYLE}>{toJson(sourceContract.responseSchema)}</pre>
+                    </Descriptions.Item>
+                  </Descriptions>
+                ) : (
+                  <Descriptions size="small" column={1}>
+                    <Descriptions.Item label="Entrypoint">
+                      <Space><Tag color="orange">{sourceContract.language}</Tag><Text code>{sourceContract.entrypoint}</Text></Space>
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Args">
+                      {sourceContract.args.length
+                        ? sourceContract.args.map(arg => <Tag key={arg}>{arg}</Tag>)
+                        : <Text type="secondary">No explicit args detected</Text>}
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Returns">{sourceContract.returns}</Descriptions.Item>
+                    <Descriptions.Item label="Effects">
+                      {sourceContract.sideEffects.length
+                        ? sourceContract.sideEffects.map(effect => <Tag key={effect}>{effect}</Tag>)
+                        : <Text type="secondary">No side effects detected</Text>}
+                    </Descriptions.Item>
+                  </Descriptions>
+                )}
+              </Card>
+            )}
+
+            <div style={{ marginTop: 12, display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+              <Button type="primary" icon={<CloudUploadOutlined />} loading={loading} onClick={handleParse}>
+                Parse for Candidate Review
+              </Button>
+              <Text type="secondary" style={{ fontSize: 12 }}>
+                Parsing does not release a Skill. It only prepares an S1 candidate draft.
+              </Text>
+            </div>
+
+            {(loading || pipelineStage >= 0) && (
+              <motion.div initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }} style={{ marginTop: 16 }}>
+                <Divider style={{ margin: '12px 0' }} />
+                <Text type="secondary" style={{ fontSize: 12 }}>Experience Processing Pipeline</Text>
+                <Steps
+                  size="small"
+                  current={pipelineStage}
+                  status={pipelineStage >= PIPELINE_STAGES.length ? 'finish' : 'process'}
+                  items={PIPELINE_STAGES.map((stage, index) => ({
+                    title: stage.title,
+                    content: stage.desc,
+                    icon: pipelineStage > index
+                      ? <CheckCircleOutlined style={{ color: '#52c41a' }} />
+                      : pipelineStage === index && loading
+                        ? <LoadingOutlined style={{ color: '#1677ff' }} />
+                        : stage.icon,
+                  }))}
+                />
+              </motion.div>
+            )}
+          </Card>
+
+          {result && (
+            <Card
+              title="Parsed Units"
+              variant="borderless"
+              style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginTop: 16 }}
+              extra={<Badge status={result.success ? 'success' : 'error'} text={result.success ? 'Ready' : 'Check errors'} />}
+            >
+              <Row gutter={[8, 8]} style={{ marginBottom: 12 }}>
+                <Col span={8}>
+                  <div style={{ textAlign: 'center' }}>
+                    <div style={{ fontSize: 22, fontWeight: 700, color: '#1677ff' }}>{result.unit_count}</div>
+                    <Text type="secondary" style={{ fontSize: 12 }}>Units</Text>
+                  </div>
+                </Col>
+                <Col span={8}>
+                  <div style={{ textAlign: 'center' }}>
+                    <div style={{ fontSize: 22, fontWeight: 700, color: '#722ed1' }}>{result.token_usage}</div>
+                    <Text type="secondary" style={{ fontSize: 12 }}>Tokens</Text>
+                  </div>
+                </Col>
+                <Col span={8}>
+                  <div style={{ textAlign: 'center' }}>
+                    <div style={{ fontSize: 22, fontWeight: 700, color: '#ff4d4f' }}>{result.errors.length}</div>
+                    <Text type="secondary" style={{ fontSize: 12 }}>Errors</Text>
+                  </div>
+                </Col>
+              </Row>
+
+              {result.errors.length > 0 && (
+                <Alert type="warning" title="Parser warnings" description={result.errors.join('; ')} style={{ marginBottom: 12 }} />
+              )}
+
+                <Space orientation="vertical" style={{ width: '100%' }}>
+                {result.units.map(unit => (
+                  <Button
+                    key={unit.unit_id}
+                    block
+                    type={unit.unit_id === selectedUnit?.unit_id ? 'primary' : 'default'}
+                    onClick={() => selectUnit(unit.unit_id)}
+                    style={{ height: 'auto', textAlign: 'left', padding: 10 }}
+                  >
+                    <div style={{ display: 'flex', justifyContent: 'space-between', gap: 8 }}>
+                      <span>{drafts[unit.unit_id]?.name ?? unit.proposed_skill_name ?? unit.unit_id}</span>
+                      <Tag color={TYPE_COLOR[unit.proposed_type || 'atomic'] || 'default'}>{unit.proposed_type || 'atomic'}</Tag>
+                    </div>
+                    <Progress
+                      percent={Math.round(unit.confidence * 100)}
+                      size="small"
+                      strokeColor={unit.confidence > 0.7 ? '#52c41a' : '#faad14'}
+                    />
+                  </Button>
+                ))}
+              </Space>
+            </Card>
+          )}
+        </Col>
+
+        <Col xs={24} lg={14}>
+          <AnimatePresence mode="wait">
+            {!selectedUnit || !currentDraft ? (
+              <motion.div key="empty" initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+                <Card
+                  variant="borderless"
+                  style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', textAlign: 'center', padding: 40 }}
+                >
+                  <CloudUploadOutlined style={{ fontSize: 48, color: '#d9d9d9', marginBottom: 12 }} />
+                  <div style={{ color: '#999' }}>Parse content to open the Candidate Review panel.</div>
+                </Card>
+              </motion.div>
+            ) : (
+              <motion.div key={selectedUnit.unit_id} initial={{ opacity: 0, x: 20 }} animate={{ opacity: 1, x: 0 }}>
+                <Card
+                  title="Candidate Review"
+                  variant="borderless"
+                  style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+                  extra={<Tag color="orange">Candidate (S1), not Released</Tag>}
+                >
+                  <Alert
+                    type="info"
+                    showIcon
+                    title="Human review boundary"
+                    description="This panel turns parsed experience into a candidate Skill. Audit results are evidence, not release approval."
+                    style={{ marginBottom: 16 }}
+                  />
+
+                  <Collapse
+                    bordered={false}
+                    items={[
+                      {
+                        key: 'raw',
+                        label: 'Raw input preview',
+                        children: (
+                          <div style={PREVIEW_BLOCK_STYLE}>
+                            {selectedUnit.raw_content || content}
+                          </div>
+                        ),
+                      },
+                      {
+                        key: 'structured',
+                        label: 'Structured experience preview',
+                        children: (
+                          <div>
+                            <Paragraph>{selectedUnit.summary}</Paragraph>
+                            <Space wrap style={{ marginBottom: 8 }}>
+                              {selectedUnit.extracted_actions.map((action, index) => (
+                                <Tag key={`${selectedUnit.unit_id}-action-${index}`}>{action}</Tag>
+                              ))}
+                            </Space>
+                            <pre style={PREVIEW_BLOCK_STYLE}>
+                              {toJson(selectedUnit.normalized_actions)}
+                            </pre>
+                          </div>
+                        ),
+                      },
+                      ...(Object.keys(selectedEvidence).length
+                        ? [{
+                          key: 'ctx2skill',
+                          label: 'Ctx2Skill Evidence',
+                          children: (
+                            <Descriptions column={1} bordered size="small">
+                              <Descriptions.Item label="Paper method">
+                                {String(selectedEvidence.paper_method || 'Ctx2Skill-lite')}
+                              </Descriptions.Item>
+                              <Descriptions.Item label="Selected reason">
+                                {String(selectedEvidence.selected_reason || '')}
+                              </Descriptions.Item>
+                              <Descriptions.Item label="Challenges">
+                                <pre style={PREVIEW_BLOCK_STYLE}>{toJson(selectedEvidence.challenges || [])}</pre>
+                              </Descriptions.Item>
+                              <Descriptions.Item label="Judge results">
+                                <pre style={PREVIEW_BLOCK_STYLE}>{toJson(selectedEvidence.judge_results || [])}</pre>
+                              </Descriptions.Item>
+                              <Descriptions.Item label="Candidate scores">
+                                <pre style={PREVIEW_BLOCK_STYLE}>{toJson(selectedEvidence.candidate_scores || [])}</pre>
+                              </Descriptions.Item>
+                            </Descriptions>
+                          ),
+                        }]
+                        : []),
+                      ...(selectedLayeringReason
+                        ? [{
+                          key: 'skillx-layer',
+                          label: 'SkillX Layering',
+                          children: <Alert type="info" showIcon message={currentDraft.skillType} description={selectedLayeringReason} />,
+                        }]
+                        : []),
+                      ...(selectedGraphPreview.length
+                        ? [{
+                          key: 'graph-preview',
+                          label: 'Graph Relation Preview',
+                          children: <pre style={PREVIEW_BLOCK_STYLE}>{toJson(selectedGraphPreview)}</pre>,
+                        }]
+                        : []),
+                      ...(activeTab === 'api_doc' || activeTab === 'script'
+                        ? [{
+                          key: 'contract',
+                          label: 'Resource contract preview',
+                          children: (() => {
+                            const contract = buildResourceContract(activeTab, selectedUnit.raw_content || content)
+                            if (!contract) return <Text type="secondary">No resource contract detected.</Text>
+                            return contract.kind === 'api_doc' ? (
+                              <Descriptions column={1} bordered size="small">
+                                <Descriptions.Item label="Endpoint">
+                                  <Space><Tag color="purple">{contract.method}</Tag><Text code>{contract.endpoint}</Text></Space>
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Required params">
+                                  {contract.requiredParams.length
+                                    ? contract.requiredParams.map(param => <Tag key={param}>{param}</Tag>)
+                                    : <Text type="secondary">None detected</Text>}
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Request schema">
+                                  <pre style={PREVIEW_BLOCK_STYLE}>{toJson(contract.requestSchema)}</pre>
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Response schema">
+                                  <pre style={PREVIEW_BLOCK_STYLE}>{toJson(contract.responseSchema)}</pre>
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Example call">{contract.exampleCall}</Descriptions.Item>
+                              </Descriptions>
+                            ) : (
+                              <Descriptions column={1} bordered size="small">
+                                <Descriptions.Item label="Entrypoint"><Text code>{contract.entrypoint}</Text></Descriptions.Item>
+                                <Descriptions.Item label="Language">{contract.language}</Descriptions.Item>
+                                <Descriptions.Item label="Arguments">
+                                  {contract.args.length
+                                    ? contract.args.map(arg => <Tag key={arg}>{arg}</Tag>)
+                                    : <Text type="secondary">None detected</Text>}
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Returns">{contract.returns}</Descriptions.Item>
+                                <Descriptions.Item label="Dependencies">
+                                  {contract.dependencies.length
+                                    ? contract.dependencies.map(dep => <Tag key={dep}>{dep}</Tag>)
+                                    : <Text type="secondary">None detected</Text>}
+                                </Descriptions.Item>
+                                <Descriptions.Item label="Runnable hint"><Text code>{contract.runnableHint}</Text></Descriptions.Item>
+                              </Descriptions>
+                            )
+                          })(),
+                        }]
+                        : []),
+                    ]}
+                    style={{ marginBottom: 16 }}
+                  />
+
+                  <Row gutter={[12, 12]}>
+                    <Col xs={24} md={14}>
+                      <Text strong>Candidate name</Text>
+                      <Input
+                        value={currentDraft.name}
+                        onChange={event => updateDraft({ name: event.target.value })}
+                        onBlur={() => updateDraft({ name: toSnakeCase(currentDraft.name) })}
+                      />
+                    </Col>
+                    <Col xs={24} md={10}>
+                      <Text strong>Skill type</Text>
+                      <Select
+                        value={currentDraft.skillType}
+                        onChange={value => updateDraft({ skillType: value })}
+                        style={{ width: '100%' }}
+                        options={[
+                          { label: 'atomic', value: 'atomic' },
+                          { label: 'functional', value: 'functional' },
+                          { label: 'strategic', value: 'strategic' },
+                        ]}
+                      />
+                    </Col>
+                    <Col span={24}>
+                      <Text strong>Description</Text>
+                      <TextArea
+                        value={currentDraft.description}
+                        onChange={event => updateDraft({ description: event.target.value })}
+                        rows={2}
+                      />
+                    </Col>
+                    <Col span={24}>
+                      <Text strong>Tags</Text>
+                      <Input
+                        value={currentDraft.tagsText}
+                        onChange={event => updateDraft({ tagsText: event.target.value })}
+                        placeholder="comma,separated,tags"
+                      />
+                    </Col>
+                    <Col span={24}>
+                      <Text strong>Prompt template</Text>
+                      <TextArea
+                        value={currentDraft.promptTemplate}
+                        onChange={event => updateDraft({ promptTemplate: event.target.value })}
+                        rows={3}
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Input schema JSON</Text>
+                      <TextArea
+                        value={currentDraft.inputSchemaText}
+                        onChange={event => updateDraft({ inputSchemaText: event.target.value })}
+                        rows={8}
+                        style={{ fontFamily: 'monospace', fontSize: 12 }}
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Output schema JSON</Text>
+                      <TextArea
+                        value={currentDraft.outputSchemaText}
+                        onChange={event => updateDraft({ outputSchemaText: event.target.value })}
+                        rows={8}
+                        style={{ fontFamily: 'monospace', fontSize: 12 }}
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Preconditions</Text>
+                      <TextArea
+                        value={currentDraft.preconditionsText}
+                        onChange={event => updateDraft({ preconditionsText: event.target.value })}
+                        rows={3}
+                        placeholder="One condition per line"
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Postconditions</Text>
+                      <TextArea
+                        value={currentDraft.postconditionsText}
+                        onChange={event => updateDraft({ postconditionsText: event.target.value })}
+                        rows={3}
+                        placeholder="One condition per line"
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Provenance JSON</Text>
+                      <TextArea
+                        value={currentDraft.provenanceText}
+                        onChange={event => updateDraft({ provenanceText: event.target.value })}
+                        rows={8}
+                        style={{ fontFamily: 'monospace', fontSize: 12 }}
+                      />
+                    </Col>
+                    <Col xs={24} md={12}>
+                      <Text strong>Evaluation placeholder JSON</Text>
+                      <TextArea
+                        value={currentDraft.evaluationText}
+                        onChange={event => updateDraft({ evaluationText: event.target.value })}
+                        rows={8}
+                        style={{ fontFamily: 'monospace', fontSize: 12 }}
+                      />
+                    </Col>
+                  </Row>
+
+                  {auditResult && (
+                    <Alert
+                      type={auditResult.passed ? (auditResult.warnings.length ? 'warning' : 'success') : 'error'}
+                      showIcon
+                      style={{ marginTop: 16 }}
+                      title={`Audit score ${Math.round(auditResult.audit_score * 100)}%`}
+                      description={
+                        <div>
+                          <Space wrap style={{ marginBottom: 8 }}>
+                            <Tag color={auditResult.schema_ok ? 'green' : 'red'}>schema</Tag>
+                            <Tag color={auditResult.safety_ok ? 'green' : 'red'}>safety</Tag>
+                            <Tag color={auditResult.postcondition_ok ? 'green' : 'red'}>postconditions</Tag>
+                          </Space>
+                          {auditResult.issues.map(issue => <div key={issue}>Issue: {issue}</div>)}
+                          {auditResult.warnings.map(warning => <div key={warning}>Warning: {warning}</div>)}
+                          {auditResult.recommendations.slice(0, 3).map(item => <div key={item}>Recommendation: {item}</div>)}
+                        </div>
+                      }
+                    />
+                  )}
+
+                  {createdSkill && (
+                    <Alert
+                      type="success"
+                      showIcon
+                      style={{ marginTop: 16 }}
+                      title={`Created ${createdSkill.name} as ${createdSkill.state}`}
+                    description={
+                        <Space wrap>
+                          <Link to={`/wiki?skill_id=${encodeURIComponent(createdSkill.skill_id)}`}>
+                            Open in Wiki
+                          </Link>
+                          {createdSkill.state === 'S2' && (
+                            <Link to={`/harness?skill_id=${encodeURIComponent(createdSkill.skill_id)}`}>
+                              Open Verification Loop
+                            </Link>
+                          )}
+                          <Text type="secondary">Version {createdSkill.version}</Text>
+                        </Space>
+                      }
+                    />
+                  )}
+
+                  <div style={{ marginTop: 16, display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+                    <Button icon={<SafetyCertificateOutlined />} loading={auditing} onClick={handleRunAudit}>
+                      Run Auditor
+                    </Button>
+                    <Button type="primary" icon={<CheckCircleOutlined />} loading={creating} onClick={handleCreateCandidate}>
+                      Create Candidate
+                    </Button>
+                    <Button disabled={!createdSkill || createdSkill.state !== 'S1'} loading={promoting} onClick={handlePromoteDraft}>
+                      Promote Draft (S2)
+                    </Button>
+                    <Button
+                      icon={<SafetyCertificateOutlined />}
+                      disabled={!createdSkill || createdSkill.state !== 'S2'}
+                      onClick={() => createdSkill && navigate(`/harness?skill_id=${encodeURIComponent(createdSkill.skill_id)}`)}
+                    >
+                      Verify Draft
+                    </Button>
+                  </div>
+                </Card>
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </Col>
+      </Row>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/LifecycleDemo.tsx

@@ -0,0 +1,353 @@
+import { useEffect, useState } from 'react'
+import {
+  Card, Steps, Tag, Button, Select, Divider,
+  Timeline, Typography, Space, Row, Col, message,
+} from 'antd'
+import {
+  ArrowRightOutlined,
+  SyncOutlined, ExperimentOutlined,
+} from '@ant-design/icons'
+import { motion, AnimatePresence } from 'framer-motion'
+import { skillsApi, lifecycleApi } from '@/api/client'
+import type { SkillSummary } from '@/api/types'
+
+const { Text, Paragraph } = Typography
+
+// SkillWiki 8-state machine definition
+const STATES = [
+  { key: 'S0', label: 'Raw Experience', color: '#722ed1', icon: '🌱', desc: 'Raw experience from trajectories, documents, or scripts' },
+  { key: 'S1', label: 'Candidate',      color: '#1677ff', icon: '🔍', desc: 'Skill candidate identified by an LLM' },
+  { key: 'S2', label: 'Draft',          color: '#13c2c2', icon: '✏️', desc: 'Structured Skill draft' },
+  { key: 'S3', label: 'Verified',       color: '#52c41a', icon: '✅', desc: 'Passed static checks and semantic validation' },
+  { key: 'S4', label: 'Released',       color: '#52c41a', icon: '🚀', desc: 'Released and callable by agents' },
+  { key: 'S5', label: 'Degraded',       color: '#faad14', icon: '⚠️', desc: 'Success rate dropped and repair is needed' },
+  { key: 'S6', label: 'Deprecated',     color: '#ff4d4f', icon: '🗑️', desc: 'Deprecated and no longer recommended' },
+  { key: 'S7', label: 'Archived',       color: '#8c8c8c', icon: '📦', desc: 'Archived with history preserved' },
+]
+
+const TRANSITIONS: Record<string, string[]> = {
+  S0: ['S1'],
+  S1: ['S2'],
+  S2: ['S3', 'S1'],
+  S3: ['S4', 'S2'],
+  S4: ['S5', 'S6'],
+  S5: ['S4', 'S6'],
+  S6: ['S7'],
+  S7: [],
+}
+
+const TRANSITION_LABELS: Record<string, string> = {
+  'S0→S1': 'Candidate Mining',
+  'S1→S2': 'Formalize',
+  'S2→S3': 'Verify',
+  'S2→S1': 'Remine',
+  'S3→S4': 'Release',
+  'S3→S2': 'Revise',
+  'S4→S5': 'Performance Degraded',
+  'S4→S6': 'Manual Deprecation',
+  'S5→S4': 'Repair Succeeded',
+  'S5→S6': 'Repair Failed',
+  'S6→S7': 'Archive',
+}
+
+function StateMachineViz({ currentState }: { currentState: string }) {
+  const mainFlow = ['S0', 'S1', 'S2', 'S3', 'S4']
+  const sideFlow = ['S5', 'S6', 'S7']
+
+  const getStepStatus = (key: string) => {
+    const idx = mainFlow.indexOf(key)
+    const curIdx = mainFlow.indexOf(currentState)
+    if (key === currentState) return 'process'
+    if (idx < curIdx) return 'finish'
+    return 'wait'
+  }
+
+  return (
+    <div>
+      {/* Main flow */}
+      <Steps
+        current={mainFlow.indexOf(currentState)}
+        items={mainFlow.map(key => {
+          const s = STATES.find(x => x.key === key)!
+          return {
+            title: <span style={{ fontSize: 12 }}>{s.icon} {s.label}</span>,
+            status: getStepStatus(key) as 'process' | 'finish' | 'wait',
+            description: <span style={{ fontSize: 11, color: '#999' }}>{s.key}</span>,
+          }
+        })}
+        style={{ marginBottom: 16 }}
+      />
+
+      {/* Side flow: degraded, deprecated, archived */}
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center', marginTop: 8 }}>
+        <Text type="secondary" style={{ fontSize: 12, whiteSpace: 'nowrap' }}>Exception Path:</Text>
+        {sideFlow.map(key => {
+          const s = STATES.find(x => x.key === key)!
+          const isActive = currentState === key
+          return (
+            <Tag
+              key={key}
+              color={isActive ? s.color : undefined}
+              style={{
+                borderColor: s.color,
+                color: isActive ? '#fff' : s.color,
+                fontWeight: isActive ? 700 : 400,
+              }}
+            >
+              {s.icon} {s.label}
+            </Tag>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+export default function LifecycleDemo() {
+  const [skills, setSkills] = useState<SkillSummary[]>([])
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [selected, setSelected] = useState<SkillSummary | null>(null)
+  const [history, setHistory] = useState<{ state: string; label: string; time: string }[]>([])
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    skillsApi.list({ limit: 100 }).then(setSkills)
+  }, [])
+
+  useEffect(() => {
+    if (!selectedId) return
+    const timeoutId = window.setTimeout(() => {
+      const s = skills.find(x => x.skill_id === selectedId) || null
+      setSelected(s)
+      if (s) {
+        setHistory([{ state: s.state, label: STATES.find(x => x.key === s.state)?.label || s.state, time: new Date().toLocaleTimeString() }])
+      }
+    }, 0)
+    return () => window.clearTimeout(timeoutId)
+  }, [selectedId, skills])
+
+  const doTransition = async (targetState: string) => {
+    if (!selected) return
+    setLoading(true)
+    try {
+      let updated: SkillSummary
+      if (targetState === 'S4') {
+        updated = await lifecycleApi.release(selected.skill_id)
+      } else if (targetState === 'S6') {
+        updated = await lifecycleApi.deprecate(selected.skill_id, 'Demo deprecation')
+      } else {
+        updated = await lifecycleApi.transition(selected.skill_id, targetState as SkillSummary['state'])
+      }
+      setSelected(updated)
+      setSkills(prev => prev.map(s => s.skill_id === updated.skill_id ? updated : s))
+      const stateInfo = STATES.find(x => x.key === updated.state)
+      setHistory(prev => [
+        { state: updated.state, label: stateInfo?.label || updated.state, time: new Date().toLocaleTimeString() },
+        ...prev,
+      ])
+      message.success(`State changed to ${stateInfo?.label}`)
+    } catch (e: unknown) {
+      message.error((e as { response?: { data?: { detail?: string } } })?.response?.data?.detail || 'Transition failed')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  const currentStateInfo = selected ? STATES.find(x => x.key === selected.state) : null
+  const availableTransitions = selected ? (TRANSITIONS[selected.state] || []) : []
+
+  return (
+    <div style={{ padding: 24 }}>
+      <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }}>
+        <h2 style={{ fontWeight: 700, marginBottom: 4 }}>Skill Lifecycle Demo</h2>
+        <p style={{ color: '#666', marginBottom: 24 }}>
+          Select a Skill and interactively walk through its full lifecycle in the SkillWiki 8-state machine.
+        </p>
+      </motion.div>
+
+      <Row gutter={[16, 16]}>
+        {/* Left: state machine visualization and actions */}
+        <Col xs={24} lg={14}>
+          <Card
+            title="State Machine Visualization"
+            variant="borderless"
+            style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+          >
+            <div style={{ marginBottom: 16 }}>
+              <Select
+                placeholder="Select a Skill"
+                style={{ width: '100%' }}
+                onChange={setSelectedId}
+                options={skills.map(s => ({
+                  label: `${s.name} (${STATES.find(x => x.key === s.state)?.label || s.state})`,
+                  value: s.skill_id,
+                }))}
+                showSearch
+                filterOption={(input, opt) =>
+                  (opt?.label as string)?.toLowerCase().includes(input.toLowerCase())
+                }
+              />
+            </div>
+
+            {selected && (
+              <motion.div key={selected.skill_id} initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+                <StateMachineViz currentState={selected.state} />
+
+                <Divider />
+
+                {/* Current state details */}
+                <div style={{ display: 'flex', alignItems: 'center', gap: 12, marginBottom: 16 }}>
+                  <div style={{
+                    width: 48, height: 48, borderRadius: '50%',
+                    background: currentStateInfo?.color,
+                    display: 'flex', alignItems: 'center', justifyContent: 'center',
+                    fontSize: 24,
+                  }}>
+                    {currentStateInfo?.icon}
+                  </div>
+                  <div>
+                    <div style={{ fontWeight: 700, fontSize: 16 }}>{currentStateInfo?.label}</div>
+                    <div style={{ color: '#666', fontSize: 13 }}>{currentStateInfo?.desc}</div>
+                  </div>
+                </div>
+
+                {/* Available transitions */}
+                <div>
+                  <Text type="secondary" style={{ fontSize: 12, marginBottom: 8, display: 'block' }}>
+                    Available state transitions:
+                  </Text>
+                  <Space wrap>
+                    {availableTransitions.length === 0 ? (
+                      <Text type="secondary">Terminal state. No transitions available.</Text>
+                    ) : (
+                      availableTransitions.map(target => {
+                        const targetInfo = STATES.find(x => x.key === target)!
+                        const label = TRANSITION_LABELS[`${selected.state}→${target}`] || target
+                        return (
+                          <motion.div key={target} whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}>
+                            <Button
+                              type="primary"
+                              style={{ background: targetInfo.color, borderColor: targetInfo.color }}
+                              icon={<ArrowRightOutlined />}
+                              onClick={() => doTransition(target)}
+                              loading={loading}
+                            >
+                              {targetInfo.icon} {label} → {targetInfo.label}
+                            </Button>
+                          </motion.div>
+                        )
+                      })
+                    )}
+                  </Space>
+                </div>
+              </motion.div>
+            )}
+
+            {!selected && (
+              <div style={{ textAlign: 'center', padding: 40, color: '#999' }}>
+                <ExperimentOutlined style={{ fontSize: 48, marginBottom: 12 }} />
+                <div>Select a Skill to start the demo.</div>
+              </div>
+            )}
+          </Card>
+
+          {/* State description cards */}
+          <Card
+            title="SkillWiki State Machine"
+            variant="borderless"
+            style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+          >
+            <Row gutter={[8, 8]}>
+              {STATES.map(s => (
+                <Col xs={12} sm={8} key={s.key}>
+                  <div style={{
+                    padding: '8px 12px',
+                    borderRadius: 8,
+                    border: `1px solid ${s.color}22`,
+                    background: `${s.color}08`,
+                  }}>
+                    <div style={{ fontWeight: 600, color: s.color, fontSize: 13 }}>
+                      {s.icon} {s.key}: {s.label}
+                    </div>
+                    <div style={{ fontSize: 11, color: '#666', marginTop: 2 }}>{s.desc}</div>
+                  </div>
+                </Col>
+              ))}
+            </Row>
+          </Card>
+        </Col>
+
+        {/* Right: transition history and Skill info */}
+        <Col xs={24} lg={10}>
+          {selected && (
+            <motion.div initial={{ opacity: 0, x: 20 }} animate={{ opacity: 1, x: 0 }}>
+              <Card
+                title={`${selected.name} Info`}
+                variant="borderless"
+                style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}
+              >
+                <Space orientation="vertical" style={{ width: '100%' }}>
+                  <div>
+                    <Text type="secondary">Type:</Text>
+                    <Tag color={selected.skill_type === 'atomic' ? 'blue' : selected.skill_type === 'functional' ? 'purple' : 'gold'}>
+                      {selected.skill_type.toUpperCase()}
+                    </Tag>
+                  </div>
+                  <div>
+                    <Text type="secondary">Version:</Text>
+                    <Text code>{selected.version}</Text>
+                  </div>
+                  <div>
+                    <Text type="secondary">Description:</Text>
+                    <Paragraph style={{ margin: 0 }}>{selected.description}</Paragraph>
+                  </div>
+                  <div>
+                    <Text type="secondary">Tags:</Text>
+                    {selected.tags.map(t => <Tag key={t}>{t}</Tag>)}
+                  </div>
+                  <div>
+                    <Text type="secondary">Executions:</Text>
+                    <Text strong>{selected.metrics.total_executions}</Text>
+                    <Text type="secondary" style={{ marginLeft: 8 }}>
+                      Success rate {(selected.metrics.success_rate * 100).toFixed(1)}%
+                    </Text>
+                  </div>
+                </Space>
+              </Card>
+
+              <Card
+                title="State Transition History"
+                variant="borderless"
+                style={{ borderRadius: 12, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+              >
+                <AnimatePresence>
+                  <Timeline
+                    items={history.map((h, i) => {
+                      const info = STATES.find(x => x.key === h.state)
+                      return {
+                        color: info?.color || '#1677ff',
+                        dot: i === 0 ? <SyncOutlined spin style={{ color: info?.color }} /> : undefined,
+                        children: (
+                          <motion.div
+                            key={`${h.state}-${h.time}`}
+                            initial={{ opacity: 0, x: -10 }}
+                            animate={{ opacity: 1, x: 0 }}
+                          >
+                            <div style={{ fontWeight: i === 0 ? 700 : 400 }}>
+                              {info?.icon} {h.label}
+                            </div>
+                            <div style={{ fontSize: 11, color: '#999' }}>{h.time}</div>
+                          </motion.div>
+                        ),
+                      }
+                    })}
+                  />
+                </AnimatePresence>
+              </Card>
+            </motion.div>
+          )}
+        </Col>
+      </Row>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/SelfEvolutionDemo.tsx

@@ -0,0 +1,535 @@
+import { useState } from 'react'
+import {
+  Alert,
+  Button,
+  Card,
+  Col,
+  Divider,
+  Empty,
+  Input,
+  Progress,
+  Row,
+  Space,
+  Spin,
+  Steps,
+  Tag,
+  Timeline,
+  Tooltip,
+  Typography,
+} from 'antd'
+import {
+  ApartmentOutlined,
+  ArrowRightOutlined,
+  BranchesOutlined,
+  BulbOutlined,
+  CheckCircleFilled,
+  ClockCircleOutlined,
+  DatabaseOutlined,
+  HistoryOutlined,
+  LoadingOutlined,
+  ReloadOutlined,
+  RocketOutlined,
+  SearchOutlined,
+  StarOutlined,
+  ThunderboltOutlined,
+} from '@ant-design/icons'
+import { motion, AnimatePresence } from 'framer-motion'
+import { useNavigate } from 'react-router-dom'
+import { executionApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type { ExecutionResult, RetrievedSkill } from '@/api/types'
+
+const { TextArea } = Input
+const { Text, Paragraph } = Typography
+
+const SKILL_TYPE_COLOR: Record<string, string> = {
+  atomic: '#1677ff',
+  functional: '#722ed1',
+  strategic: '#faad14',
+}
+
+const DEMO_TASKS = [
+  'Complete a login flow on a web page and record reusable execution steps',
+  'Extract a reusable operation pattern from an execution trace and promote it into a Skill',
+  'Inspect why a Skill failed and propose a repair',
+  'Compose existing Skills to complete a new automation task',
+]
+
+type Phase =
+  | 'idle'
+  | 'searching'
+  | 'planning'
+  | 'executing'
+  | 'recording'
+  | 'learning'
+  | 'done'
+
+const PHASE_STEPS = [
+  { title: 'Skill Retrieval', description: 'Recall relevant capabilities from the Skill Wiki', icon: <SearchOutlined /> },
+  { title: 'Plan Generation', description: 'Decompose the goal into executable steps', icon: <BulbOutlined /> },
+  { title: 'Execution', description: 'Invoke Skills according to the plan and collect results', icon: <ThunderboltOutlined /> },
+  { title: 'Experience Recording', description: 'Write the execution trace into the experience layer', icon: <DatabaseOutlined /> },
+  { title: 'Evolution Learning', description: 'Update quality signals and prepare for reuse', icon: <StarOutlined /> },
+]
+
+const phaseIndex: Record<Phase, number> = {
+  idle: -1,
+  searching: 0,
+  planning: 1,
+  executing: 2,
+  recording: 3,
+  learning: 4,
+  done: 4,
+}
+
+function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function getStatusColor(status: string) {
+  if (status === 'success') return 'green'
+  if (status === 'failed' || status === 'error') return 'red'
+  if (status === 'partial') return 'gold'
+  return 'blue'
+}
+
+function SuggestedSkill({ suggested }: { suggested: Record<string, unknown> }) {
+  const name = String(suggested.name || suggested.skill_name || 'Unnamed Skill')
+  const description = String(suggested.description || suggested.summary || 'The backend suggested a new Skill candidate to retain.')
+  const type = String(suggested.skill_type || suggested.type || 'candidate')
+
+  return (
+    <Card
+      title={<span><BulbOutlined style={{ color: '#faad14', marginRight: 6 }} />Suggested Skill to Retain</span>}
+      size="small"
+      style={{ borderRadius: 8, marginTop: 12, borderLeft: '3px solid #faad14' }}
+    >
+      <Space orientation="vertical" size={6} style={{ width: '100%' }}>
+        <Space>
+          <Text strong>{name}</Text>
+          <Tag color="gold">{type}</Tag>
+        </Space>
+        <Paragraph type="secondary" style={{ marginBottom: 0 }}>
+          {description}
+        </Paragraph>
+      </Space>
+    </Card>
+  )
+}
+
+export default function SelfEvolutionDemo() {
+  const navigate = useNavigate()
+  const [task, setTask] = useState('')
+  const [phase, setPhase] = useState<Phase>('idle')
+  const [result, setResult] = useState<ExecutionResult | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [visibleSteps, setVisibleSteps] = useState(0)
+
+  const runDemo = async () => {
+    const goal = task.trim()
+    if (!goal) return
+
+    setError(null)
+    setResult(null)
+    setVisibleSteps(0)
+
+    try {
+      setPhase('searching')
+      await sleep(450)
+      setPhase('planning')
+      await sleep(400)
+      setPhase('executing')
+
+      const res = await executionApi.executePlan(goal)
+      setResult(res)
+
+      for (let index = 1; index <= res.steps.length; index += 1) {
+        await sleep(260)
+        setVisibleSteps(index)
+      }
+
+      setPhase('recording')
+      await sleep(550)
+      setPhase('learning')
+      await sleep(450)
+      setPhase('done')
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Self-evolution demo failed'))
+      setPhase('idle')
+    }
+  }
+
+  const reset = () => {
+    setPhase('idle')
+    setResult(null)
+    setError(null)
+    setVisibleSteps(0)
+    setTask('')
+  }
+
+  const goToWiki = (skillId: string) => {
+    navigate(`/wiki?skill_id=${encodeURIComponent(skillId)}`)
+  }
+
+  const goToGraph = (skillId: string) => {
+    navigate(`/graph?skill_id=${encodeURIComponent(skillId)}`)
+  }
+
+  const isRunning = phase !== 'idle' && phase !== 'done'
+  const retrieved = result?.retrieved_skills || []
+  const successCount = result?.steps.filter(step => step.status === 'success').length || 0
+  const stepCount = result?.steps.length || 0
+  const currentStep = phaseIndex[phase]
+  const experienceRecorded = result?.experience_recorded === true
+
+  return (
+    <div style={{ padding: 24, maxWidth: 1120, margin: '0 auto' }}>
+      <motion.div initial={{ opacity: 0, y: -12 }} animate={{ opacity: 1, y: 0 }}>
+        <div style={{ marginBottom: 24 }}>
+          <h2 style={{ fontWeight: 800, fontSize: 22, marginBottom: 4 }}>
+            Self-Evolution Loop Demo
+          </h2>
+          <Paragraph type="secondary" style={{ marginBottom: 0 }}>
+            Enter a task goal and watch SkillWiki retrieve Skills, generate a plan, execute it, record experience, and update evolution signals.
+          </Paragraph>
+        </div>
+      </motion.div>
+
+      <Card variant="borderless" style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 16 }}>
+        <TextArea
+          value={task}
+          onChange={event => setTask(event.target.value)}
+          placeholder="Describe your task goal, for example: extract a reusable Skill from an execution trace"
+          rows={2}
+          disabled={isRunning}
+          style={{ fontSize: 14, marginBottom: 10 }}
+        />
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', flexWrap: 'wrap', gap: 8 }}>
+          <Space wrap>
+            <Text type="secondary" style={{ fontSize: 12 }}>Examples:</Text>
+            {DEMO_TASKS.map(example => (
+              <Tag
+                key={example}
+                style={{ cursor: isRunning ? 'not-allowed' : 'pointer', fontSize: 12 }}
+                onClick={() => !isRunning && setTask(example)}
+              >
+                {example}
+              </Tag>
+            ))}
+          </Space>
+          <Space>
+            {phase === 'done' && (
+              <Button icon={<ReloadOutlined />} onClick={reset}>
+                Reset
+              </Button>
+            )}
+            <Button
+              type="primary"
+              icon={isRunning ? <LoadingOutlined /> : <RocketOutlined />}
+              onClick={runDemo}
+              loading={isRunning}
+              disabled={!task.trim() || phase === 'done'}
+              size="large"
+            >
+              {phase === 'done' ? 'Completed' : 'Start Evolution Loop'}
+            </Button>
+          </Space>
+        </div>
+      </Card>
+
+      {phase !== 'idle' && (
+        <motion.div initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }} style={{ marginBottom: 16 }}>
+          <Card variant="borderless" style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+            <Steps
+              current={currentStep}
+              status={phase === 'done' ? 'finish' : 'process'}
+              size="small"
+              items={PHASE_STEPS.map((step, index) => ({
+                title: step.title,
+                description: step.description,
+                icon: currentStep > index
+                  ? <CheckCircleFilled style={{ color: '#52c41a' }} />
+                  : currentStep === index
+                    ? <LoadingOutlined style={{ color: '#1677ff' }} />
+                    : <ClockCircleOutlined style={{ color: '#d9d9d9' }} />,
+              }))}
+            />
+          </Card>
+        </motion.div>
+      )}
+
+      {error && (
+        <Alert
+          type="error"
+          title={error}
+          showIcon
+          style={{ marginBottom: 16 }}
+          closable
+          onClose={() => setError(null)}
+        />
+      )}
+
+      <AnimatePresence>
+        {result && (
+          <motion.div key="result" initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+            <Row gutter={[16, 16]}>
+              <Col xs={24} lg={14}>
+                {retrieved.length > 0 && (
+                  <motion.div initial={{ opacity: 0, x: -16 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: 0.1 }}>
+                    <Card
+                      title={<span><SearchOutlined style={{ color: '#1677ff', marginRight: 6 }} />Retrieved Skills ({retrieved.length})</span>}
+                      variant="borderless"
+                      size="small"
+                      style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 12 }}
+                    >
+                      {retrieved.map((skill: RetrievedSkill, index) => (
+                        <motion.div
+                          key={skill.skill_id}
+                          initial={{ opacity: 0, x: -12 }}
+                          animate={{ opacity: 1, x: 0 }}
+                          transition={{ delay: index * 0.06 }}
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 10,
+                            padding: '10px 0',
+                            borderBottom: index < retrieved.length - 1 ? '1px solid #f0f0f0' : 'none',
+                          }}
+                        >
+                          <div style={{ flex: 1, minWidth: 0 }}>
+                            <div style={{ display: 'flex', alignItems: 'center', gap: 6, marginBottom: 4, flexWrap: 'wrap' }}>
+                              <Text strong style={{ fontSize: 13 }}>{skill.name}</Text>
+                              <Tag color={SKILL_TYPE_COLOR[skill.skill_type]} style={{ fontSize: 11 }}>
+                                {skill.skill_type}
+                              </Tag>
+                            </div>
+                            <Text type="secondary" style={{ fontSize: 12 }}>{skill.match_reason || skill.description}</Text>
+                            <div style={{ marginTop: 6 }}>
+                              <Space size={6}>
+                                <Button size="small" icon={<ApartmentOutlined />} onClick={() => goToWiki(skill.skill_id)}>
+                                  Wiki
+                                </Button>
+                                <Button size="small" icon={<BranchesOutlined />} onClick={() => goToGraph(skill.skill_id)}>
+                                  Graph
+                                </Button>
+                              </Space>
+                            </div>
+                          </div>
+                          <Tooltip title={`Relevance ${Math.round(skill.score * 100)}%`}>
+                            <Progress
+                              type="circle"
+                              percent={Math.round(skill.score * 100)}
+                              width={40}
+                              strokeColor={skill.score > 0.7 ? '#52c41a' : skill.score > 0.4 ? '#faad14' : '#ff4d4f'}
+                              format={percent => <span style={{ fontSize: 10 }}>{percent}%</span>}
+                            />
+                          </Tooltip>
+                        </motion.div>
+                      ))}
+                    </Card>
+                  </motion.div>
+                )}
+
+                <motion.div initial={{ opacity: 0, x: -16 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: 0.2 }}>
+                  <Card
+                    title={<span><ThunderboltOutlined style={{ color: '#722ed1', marginRight: 6 }} />Execution Steps</span>}
+                    variant="borderless"
+                    size="small"
+                    style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+                  >
+                    {result.steps.length === 0 ? (
+                      <Alert type="warning" showIcon title="No executable Skill was found. Try a more specific task description." />
+                    ) : (
+                      result.steps.slice(0, visibleSteps).map((step, index) => (
+                        <motion.div
+                          key={step.step_id}
+                          initial={{ opacity: 0, y: 8 }}
+                          animate={{ opacity: 1, y: 0 }}
+                          transition={{ duration: 0.25 }}
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 10,
+                            padding: '10px 0',
+                            borderBottom: index < result.steps.length - 1 ? '1px solid #f0f0f0' : 'none',
+                          }}
+                        >
+                          {step.status === 'success'
+                            ? <CheckCircleFilled style={{ color: '#52c41a', fontSize: 16 }} />
+                            : <ClockCircleOutlined style={{ color: '#ff4d4f', fontSize: 16 }} />}
+                          <div style={{ flex: 1, minWidth: 0 }}>
+                            <Text strong style={{ fontSize: 13 }}>{step.skill_name}</Text>
+                            <div style={{ color: '#8c8c8c', fontSize: 11 }}>
+                              Step {step.step_index + 1} / Skill ID: {step.skill_id}
+                            </div>
+                            {step.error && (
+                              <div style={{ fontSize: 12, color: '#ff4d4f', marginTop: 2 }}>{step.error}</div>
+                            )}
+                          </div>
+                          <Text type="secondary" style={{ fontSize: 11 }}>{(step.latency_ms ?? 0).toFixed(0)}ms</Text>
+                          <Tag color={getStatusColor(step.status)} style={{ fontSize: 11 }}>
+                            {step.status}
+                          </Tag>
+                        </motion.div>
+                      ))
+                    )}
+                    {visibleSteps < result.steps.length && (
+                      <div style={{ textAlign: 'center', padding: 8 }}>
+                        <Spin size="small" />
+                      </div>
+                    )}
+                  </Card>
+                </motion.div>
+              </Col>
+
+              <Col xs={24} lg={10}>
+                <motion.div initial={{ opacity: 0, x: 16 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: 0.15 }}>
+                  <Card
+                    variant="borderless"
+                    size="small"
+                    style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 12 }}
+                  >
+                    <Row gutter={8}>
+                      {[
+                        { label: 'Steps', value: stepCount, color: '#1677ff' },
+                        { label: 'Succeeded', value: successCount, color: '#52c41a' },
+                        { label: 'Latency', value: `${result.total_latency_ms.toFixed(0)}ms`, color: '#722ed1' },
+                      ].map(({ label, value, color }) => (
+                        <Col span={8} key={label} style={{ textAlign: 'center' }}>
+                          <div style={{ fontSize: 20, fontWeight: 700, color }}>{value}</div>
+                          <Text type="secondary" style={{ fontSize: 11 }}>{label}</Text>
+                        </Col>
+                      ))}
+                    </Row>
+                    <Divider style={{ margin: '12px 0' }} />
+                    <Space wrap>
+                      <Tag color={getStatusColor(result.status)}>Execution status: {result.status}</Tag>
+                      {experienceRecorded ? (
+                        <Tag color="green">Experience recorded</Tag>
+                      ) : (
+                        <Tag>Experience recording pending</Tag>
+                      )}
+                    </Space>
+                  </Card>
+                </motion.div>
+
+                <AnimatePresence>
+                  {(phase === 'recording' || phase === 'learning' || phase === 'done') && (
+                    <motion.div initial={{ opacity: 0, scale: 0.96 }} animate={{ opacity: 1, scale: 1 }}>
+                      <Card
+                        title={<span><DatabaseOutlined style={{ color: '#52c41a', marginRight: 6 }} />Experience Recording</span>}
+                        variant="borderless"
+                        size="small"
+                        style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 12, borderLeft: '3px solid #52c41a' }}
+                      >
+                        <Timeline
+                          items={[
+                            {
+                              color: 'green',
+                              children: <Text style={{ fontSize: 12 }}>Execution trace summarized: {result.steps.length} steps</Text>,
+                            },
+                            {
+                              color: experienceRecorded ? 'green' : 'gray',
+                              children: <Text style={{ fontSize: 12 }}>{experienceRecorded ? 'Experience unit written to the Experience Store' : 'Backend has not confirmed experience recording yet'}</Text>,
+                            },
+                            {
+                              color: 'blue',
+                              children: <Text style={{ fontSize: 12 }}>Final state fields: {Object.keys(result.final_state || {}).length}</Text>,
+                            },
+                          ]}
+                        />
+                      </Card>
+                    </motion.div>
+                  )}
+                </AnimatePresence>
+
+                <AnimatePresence>
+                  {(phase === 'learning' || phase === 'done') && (
+                    <motion.div initial={{ opacity: 0, scale: 0.96 }} animate={{ opacity: 1, scale: 1 }} transition={{ delay: 0.1 }}>
+                      <Card
+                        title={<span><StarOutlined style={{ color: '#faad14', marginRight: 6 }} />Evolution Learning</span>}
+                        variant="borderless"
+                        size="small"
+                        style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginBottom: 12, borderLeft: '3px solid #faad14' }}
+                      >
+                        {retrieved.length > 0 ? (
+                          <div style={{ marginBottom: 8 }}>
+                            {retrieved.slice(0, 3).map(skill => (
+                              <div key={skill.skill_id} style={{ display: 'flex', alignItems: 'center', gap: 6, marginBottom: 6 }}>
+                                <ArrowRightOutlined style={{ color: '#52c41a', fontSize: 10 }} />
+                                <Text style={{ fontSize: 12 }}>Reuse signals updated for <strong>{skill.name}</strong></Text>
+                              </div>
+                            ))}
+                          </div>
+                        ) : (
+                          <Text type="secondary" style={{ fontSize: 12 }}>No reusable Skill was retrieved this time. Future experience retention can fill this capability gap.</Text>
+                        )}
+                        <Divider style={{ margin: '8px 0' }} />
+                        <Text type="secondary" style={{ fontSize: 12 }}>
+                          This execution result can be used for health assessment, version evolution, and future reuse on similar tasks.
+                        </Text>
+                      </Card>
+                    </motion.div>
+                  )}
+                </AnimatePresence>
+
+                {result.suggested_skill && (
+                  <SuggestedSkill suggested={result.suggested_skill} />
+                )}
+
+                <AnimatePresence>
+                  {phase === 'done' && (
+                    <motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }} transition={{ delay: 0.2 }}>
+                      <Alert
+                        type="success"
+                        icon={<CheckCircleFilled />}
+                        title="Self-Evolution Loop Completed"
+                        description={(
+                          <Space orientation="vertical" size={8}>
+                            <Text style={{ fontSize: 12 }}>
+                              SkillWiki completed the full loop for this task: retrieval, planning, execution, recording, and learning.
+                            </Text>
+                            <Button size="small" icon={<HistoryOutlined />} onClick={() => navigate('/execution')}>
+                              View Execution History
+                            </Button>
+                          </Space>
+                        )}
+                        showIcon
+                      />
+                    </motion.div>
+                  )}
+                </AnimatePresence>
+              </Col>
+            </Row>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {phase === 'idle' && !result && (
+        <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} transition={{ delay: 0.2 }}>
+          <Card variant="borderless" style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', textAlign: 'center', padding: '32px 0' }}>
+            <Empty
+              image={<RocketOutlined style={{ fontSize: 48, color: '#1677ff' }} />}
+              description={(
+                <div>
+                  <div style={{ fontWeight: 600, fontSize: 16, marginBottom: 8 }}>Self-Evolution Loop</div>
+                  <Paragraph type="secondary" style={{ maxWidth: 520, margin: '0 auto', fontSize: 13 }}>
+                    Through the loop of retrieving Skills, executing tasks, recording experience, and feeding evolution signals back, SkillWiki turns each task result into reusable capability evidence.
+                  </Paragraph>
+                </div>
+              )}
+            />
+            <div style={{ marginTop: 20, display: 'flex', justifyContent: 'center', gap: 8, flexWrap: 'wrap' }}>
+              {PHASE_STEPS.map((step, index) => (
+                <div key={step.title} style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+                  <Tag color="blue" style={{ fontSize: 12 }}>{step.icon} {step.title}</Tag>
+                  {index < PHASE_STEPS.length - 1 && <ArrowRightOutlined style={{ color: '#d9d9d9', fontSize: 10 }} />}
+                </div>
+              ))}
+            </div>
+          </Card>
+        </motion.div>
+      )}
+    </div>
+  )
+}

skillwiki-frontend/src/pages/SkillGraph.tsx

@@ -0,0 +1,1389 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  Alert,
+  Button,
+  Card,
+  Descriptions,
+  Empty,
+  InputNumber,
+  Popover,
+  Select,
+  Segmented,
+  Slider,
+  Space,
+  Spin,
+  Switch,
+  Tag,
+  Tooltip,
+  Typography,
+} from 'antd'
+import {
+  AimOutlined,
+  ExportOutlined,
+  ReloadOutlined,
+  RollbackOutlined,
+  SettingOutlined,
+  ShareAltOutlined,
+  ZoomInOutlined,
+  ZoomOutOutlined,
+} from '@ant-design/icons'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { graphApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  GraphData,
+  GraphViewData,
+  GraphViewEdgeData,
+  GraphViewMode,
+  GraphViewNodeData,
+} from '@/api/types'
+
+const { Text, Paragraph } = Typography
+
+const TYPE_COLOR: Record<string, string> = {
+  atomic: '#1677ff',
+  functional: '#722ed1',
+  strategic: '#fa8c16',
+}
+
+const KIND_COLOR: Record<string, string> = {
+  source: '#08979c',
+  trajectory: '#08979c',
+  skill: '#1677ff',
+  execution: '#2f54eb',
+  validation: '#52c41a',
+  version: '#fa8c16',
+}
+
+const KIND_LABEL: Record<string, string> = {
+  source: 'Source / Trajectory',
+  trajectory: 'Trajectory',
+  skill: 'Skill',
+  execution: 'Execution',
+  validation: 'Validation',
+  version: 'Version',
+}
+
+const STATE_OPACITY: Record<string, number> = {
+  S0: 0.4,
+  S1: 0.5,
+  S2: 0.6,
+  S3: 0.75,
+  S4: 1,
+  S5: 0.85,
+  S6: 0.3,
+  S7: 0.2,
+}
+
+const STATE_LABEL: Record<string, string> = {
+  S0: 'Raw',
+  S1: 'Candidate',
+  S2: 'Draft',
+  S3: 'Verified',
+  S4: 'Released',
+  S5: 'Degraded',
+  S6: 'Deprecated',
+  S7: 'Archived',
+}
+
+const EDGE_COLOR: Record<string, string> = {
+  depends_on: '#1677ff',
+  composes_with: '#722ed1',
+  similar_to: '#52c41a',
+  evolved_from: '#fa8c16',
+  conflicts_with: '#ff4d4f',
+  replaces: '#eb2f96',
+  specializes: '#13c2c2',
+  generalizes: '#d4a106',
+  derived_from: '#08979c',
+  executed_as: '#2f54eb',
+  validated_by: '#52c41a',
+  versioned_as: '#fa8c16',
+}
+
+const GRAPH_VIEW_OPTIONS: { label: string; value: GraphViewMode }[] = [
+  { label: 'Skill-only', value: 'skill_only' },
+  { label: 'Provenance', value: 'provenance' },
+  { label: 'Version impact', value: 'version_impact' },
+]
+
+const GRAPH_VIEW_COPY: Record<GraphViewMode, { subtitle: string; empty: string; reload: string }> = {
+  skill_only: {
+    subtitle: 'Skill dependency, composition, similarity, and evolution links.',
+    empty: 'No Skill graph data is available.',
+    reload: 'Reload Skill graph',
+  },
+  provenance: {
+    subtitle: 'Typed Source, Skill, Execution, Validation, and Version evidence chain.',
+    empty: 'No heterogeneous provenance graph data is available.',
+    reload: 'Reload provenance graph',
+  },
+  version_impact: {
+    subtitle: 'Meta-path projection with version, shared-source, and validation evidence.',
+    empty: 'No projected version-impact graph data is available.',
+    reload: 'Reload impact view',
+  },
+}
+
+type GraphMode = 'full' | 'subgraph'
+
+type GraphLayoutSettings = {
+  repulsion: number
+  attraction: number
+  linkDistance: number
+  nodeSpacing: number
+  nodeSize: number
+  edgeWidth: number
+  edgeOpacity: number
+  labelMode: GraphLabelMode
+  edgeLabelMode: GraphLabelMode
+  denseMode: boolean
+}
+
+type GraphLabelMode = 'always' | 'hover' | 'selected' | 'hidden'
+type NumericGraphLayoutField = {
+  [K in keyof GraphLayoutSettings]: GraphLayoutSettings[K] extends number ? K : never
+}[keyof GraphLayoutSettings]
+
+type GraphCanvasSize = {
+  width: number
+  height: number
+}
+
+type GraphEvent = {
+  target?: { id?: string }
+}
+
+type GraphInstance = {
+  destroy: () => void
+  draw: () => void | Promise<void>
+  fitView: (options?: unknown, animation?: unknown) => void | Promise<void>
+  getZoom: () => number
+  on: (eventName: string, handler: (event: GraphEvent) => void) => void
+  render: () => void | Promise<void>
+  updateEdgeData: (edges: Array<{ id: string; style: { badgeText: string } }>) => void
+  updateNodeData: (nodes: Array<{ id: string; style: Record<string, unknown> }>) => void
+  zoomBy: (ratio: number, animation?: unknown) => void | Promise<void>
+}
+
+type ForceEdgeDatum = {
+  data?: { weight?: number }
+  weight?: number
+}
+
+const GRAPH_LAYOUT_STORAGE_KEY = 'skillwiki.graph.layoutSettings.v2'
+const EDGE_LABEL_ZOOM_THRESHOLD = 0.9
+const NEBULA_ZOOM_THRESHOLD = 0.65
+
+const DEFAULT_GRAPH_LAYOUT: GraphLayoutSettings = {
+  repulsion: 260,
+  attraction: 0.28,
+  linkDistance: 165,
+  nodeSpacing: 38,
+  nodeSize: 12,
+  edgeWidth: 0.9,
+  edgeOpacity: 0.34,
+  labelMode: 'hover',
+  edgeLabelMode: 'selected',
+  denseMode: true,
+}
+const GRAPH_LAYOUT_PRESETS: Record<string, GraphLayoutSettings> = {
+  nebula: DEFAULT_GRAPH_LAYOUT,
+  readable: {
+    repulsion: 190,
+    attraction: 0.36,
+    linkDistance: 150,
+    nodeSpacing: 52,
+    nodeSize: 20,
+    edgeWidth: 1.4,
+    edgeOpacity: 0.62,
+    labelMode: 'always',
+    edgeLabelMode: 'hover',
+    denseMode: false,
+  },
+  debug: {
+    repulsion: 240,
+    attraction: 0.42,
+    linkDistance: 190,
+    nodeSpacing: 64,
+    nodeSize: 24,
+    edgeWidth: 2,
+    edgeOpacity: 0.86,
+    labelMode: 'always',
+    edgeLabelMode: 'always',
+    denseMode: false,
+  },
+}
+
+const LABEL_MODE_OPTIONS: { label: string; value: GraphLabelMode }[] = [
+  { label: 'Always', value: 'always' },
+  { label: 'Hover', value: 'hover' },
+  { label: 'Selected', value: 'selected' },
+  { label: 'Hidden', value: 'hidden' },
+]
+
+function clampNumber(value: unknown, min: number, max: number, fallback: number) {
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) return fallback
+  return Math.min(max, Math.max(min, numeric))
+}
+
+function normalizeLabelMode(value: unknown, fallback: GraphLabelMode): GraphLabelMode {
+  return value === 'always' || value === 'hover' || value === 'selected' || value === 'hidden'
+    ? value
+    : fallback
+}
+
+function normalizeLayoutSettings(value: Partial<GraphLayoutSettings> = {}): GraphLayoutSettings {
+  return {
+    repulsion: clampNumber(value.repulsion, 40, 400, DEFAULT_GRAPH_LAYOUT.repulsion),
+    attraction: clampNumber(value.attraction, 0.05, 1, DEFAULT_GRAPH_LAYOUT.attraction),
+    linkDistance: clampNumber(value.linkDistance, 60, 280, DEFAULT_GRAPH_LAYOUT.linkDistance),
+    nodeSpacing: clampNumber(value.nodeSpacing, 28, 96, DEFAULT_GRAPH_LAYOUT.nodeSpacing),
+    nodeSize: clampNumber(value.nodeSize, 6, 42, DEFAULT_GRAPH_LAYOUT.nodeSize),
+    edgeWidth: clampNumber(value.edgeWidth, 0.4, 4, DEFAULT_GRAPH_LAYOUT.edgeWidth),
+    edgeOpacity: clampNumber(value.edgeOpacity, 0.08, 1, DEFAULT_GRAPH_LAYOUT.edgeOpacity),
+    labelMode: normalizeLabelMode(value.labelMode, DEFAULT_GRAPH_LAYOUT.labelMode),
+    edgeLabelMode: normalizeLabelMode(value.edgeLabelMode, DEFAULT_GRAPH_LAYOUT.edgeLabelMode),
+    denseMode: typeof value.denseMode === 'boolean' ? value.denseMode : DEFAULT_GRAPH_LAYOUT.denseMode,
+  }
+}
+
+function loadLayoutSettings(): GraphLayoutSettings {
+  if (typeof window === 'undefined') return DEFAULT_GRAPH_LAYOUT
+  try {
+    const stored = window.localStorage.getItem(GRAPH_LAYOUT_STORAGE_KEY)
+    return stored ? normalizeLayoutSettings(JSON.parse(stored)) : DEFAULT_GRAPH_LAYOUT
+  } catch {
+    return DEFAULT_GRAPH_LAYOUT
+  }
+}
+
+function saveLayoutSettings(settings: GraphLayoutSettings) {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(GRAPH_LAYOUT_STORAGE_KEY, JSON.stringify(settings))
+  } catch {
+    // Layout persistence is optional.
+  }
+}
+
+function formatPercent(value?: number | null) {
+  if (!Number.isFinite(Number(value))) return 'N/A'
+  return `${Math.round(Number(value) * 100)}%`
+}
+
+function formatEdgeType(edgeType: string) {
+  return edgeType.replace(/_/g, ' ')
+}
+
+function formatKind(kind?: string) {
+  if (!kind) return 'Skill'
+  return KIND_LABEL[kind] || kind
+}
+
+function nodeColor(node?: GraphViewNodeData) {
+  if (!node) return '#8c8c8c'
+  if (node.kind && KIND_COLOR[node.kind]) return KIND_COLOR[node.kind]
+  return TYPE_COLOR[String(node.skill_type || '')] || '#8c8c8c'
+}
+
+// Parse "#rrggbb" → [r, g, b]
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  const n = parseInt(h.length === 3 ? h.split('').map(c => c + c).join('') : h, 16)
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+}
+
+// Blend color toward white (highlight) or black (shadow)
+function blendColor(hex: string, toward: 'white' | 'black', amount: number): string {
+  const [r, g, b] = hexToRgb(hex)
+  const t = toward === 'white' ? 255 : 0
+  const blend = (c: number) => Math.round(c + (t - c) * amount)
+  return `rgb(${blend(r)},${blend(g)},${blend(b)})`
+}
+
+// G6 v5 linear gradient: "l(angle) offset:color offset:color ..."
+function sphereGradient(hex: string): string {
+  const hi = blendColor(hex, 'white', 0.55)
+  const mid = hex
+  const lo = blendColor(hex, 'black', 0.35)
+  // angle 135° = light from top-left
+  return `l(135) 0:${hi} 0.38:${mid} 1:${lo}`
+}
+
+// Depth-adjusted size and opacity for perspective illusion
+function depthScale(depth: number): { sizeScale: number; opacityScale: number } {
+  // depth 0 = foreground (bigger, opaque), depth 1 = background (smaller, faint)
+  const sizeScale = 1.0 - depth * 0.55    // 1.0 → 0.45
+  const opacityScale = 1.0 - depth * 0.6  // 1.0 → 0.40
+  return { sizeScale, opacityScale }
+}
+
+function uniqueTags(tags?: string[]): string[] {
+  return Array.from(new Set((tags ?? []).filter(t => Boolean(t) && t !== 'mock')))
+}
+
+function stableRandom(seed: string) {
+  let hash = 2166136261
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index)
+    hash = Math.imul(hash, 16777619)
+  }
+  return (hash >>> 0) / 4294967295
+}
+
+function edgeWeight(edge?: ForceEdgeDatum) {
+  return clampNumber(edge?.data?.weight ?? edge?.weight, 0, 1, 1)
+}
+
+function weightedLinkDistance(edge: ForceEdgeDatum | undefined, baseDistance: number) {
+  const weight = edgeWeight(edge)
+  return Math.round(baseDistance * (1.4 - weight * 0.7))
+}
+
+function weightedEdgeStrength(edge: ForceEdgeDatum | undefined, baseAttraction: number) {
+  const weight = edgeWeight(edge)
+  return baseAttraction * (0.45 + weight * 0.75) * 80
+}
+
+function formatEdgeLabel(edge: GraphViewEdgeData) {
+  const score = edge.confidence ?? edge.weight
+  return `${formatEdgeType(edge.edge_type)} / ${score.toFixed(2)}`
+}
+
+function shouldShowNodeLabel(
+  mode: GraphLabelMode,
+  options: { selected: boolean; centered: boolean; denseMode: boolean },
+) {
+  const { selected, centered, denseMode } = options
+  if (mode === 'hidden') return false
+  if (mode === 'always') return true
+  if (mode === 'selected') return selected || centered
+  return denseMode ? selected || centered : true
+}
+
+function shouldShowEdgeLabels(
+  mode: GraphLabelMode,
+  zoom: number,
+  edges: GraphViewEdgeData[],
+  selectedEdgeId: string | null,
+) {
+  if (mode === 'hidden') return new Set<string>()
+  if (mode === 'always') return new Set(edges.map(edge => edge.id))
+  if (mode === 'selected') return new Set(selectedEdgeId ? [selectedEdgeId] : [])
+  if (zoom < EDGE_LABEL_ZOOM_THRESHOLD && edges.length > 24) {
+    return new Set(selectedEdgeId ? [selectedEdgeId] : [])
+  }
+  return new Set(edges.map(edge => edge.id))
+}
+
+function nodeVisualSize(node: GraphViewNodeData, settings: GraphLayoutSettings, selected: boolean, centered: boolean) {
+  const usageBoost = Math.min(8, Number(node.usage_count || 0) * 0.25)
+  const base = settings.nodeSize + usageBoost
+  if (selected || centered) return Math.max(18, base + 8)
+  return base
+}
+
+function nodeLabelFontSize(settings: GraphLayoutSettings, selected: boolean, centered: boolean) {
+  if (selected || centered) return 10
+  return settings.denseMode ? 7 : 8
+}
+
+function formatMetadataValue(value: unknown) {
+  if (value === null || value === undefined || value === '') return 'N/A'
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'number' || typeof value === 'string') return String(value)
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+function relationStrengthSummary(metadata?: Record<string, unknown>) {
+  const relationStrength = metadata?.relation_strength
+  if (!relationStrength || typeof relationStrength !== 'object' || Array.isArray(relationStrength)) return ''
+  const relation = relationStrength as Record<string, unknown>
+  const strong = relation.strong && typeof relation.strong === 'object' && !Array.isArray(relation.strong)
+    ? Object.keys(relation.strong as Record<string, unknown>).map(formatEdgeType).join(', ')
+    : ''
+  const weak = relation.weak && typeof relation.weak === 'object' && !Array.isArray(relation.weak)
+    ? Object.keys(relation.weak as Record<string, unknown>).map(formatEdgeType).join(', ')
+    : ''
+  const claimBoundary = typeof relation.claim_boundary === 'string' ? relation.claim_boundary : ''
+  return [
+    strong ? `Strong relations: ${strong}.` : '',
+    weak ? `Weak projected relations: ${weak}.` : '',
+    claimBoundary,
+  ].filter(Boolean).join(' ')
+}
+
+function metadataEntries(metadata?: Record<string, unknown>) {
+  const INTERNAL_KEYS = new Set(['synthetic', 'mock', 'depth', 'domain'])
+  return Object.entries(metadata ?? {}).filter(
+    ([key, value]) => !INTERNAL_KEYS.has(key) && value !== undefined && value !== null && value !== '',
+  )
+}
+
+function graphDataToView(data: GraphData): GraphViewData {
+  return {
+    view: 'skill_only',
+    source_endpoint: '/api/v1/graph/subgraph',
+    nodes: data.nodes.map(node => ({
+      id: node.id,
+      name: node.name,
+      kind: 'skill',
+      description: node.description || '',
+      skill_type: node.skill_type,
+      state: node.state,
+      tags: node.tags,
+      version: node.version,
+      granularity_level: node.granularity_level,
+      success_rate: node.success_rate,
+      usage_count: node.usage_count,
+      metadata: node.metadata || {},
+    })),
+    edges: data.edges.map(edge => ({
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      edge_type: edge.edge_type,
+      weight: edge.weight,
+      confidence: edge.confidence ?? null,
+      metadata: edge.metadata || {},
+    })),
+    stats: data.stats,
+    metadata: {},
+    validation_evidence: {},
+  }
+}
+
+function calculateInitialNodePositions(
+  nodes: GraphViewNodeData[],
+  edges: GraphViewEdgeData[],
+  canvasSize: GraphCanvasSize,
+  settings: GraphLayoutSettings,
+) {
+  const positions = new Map<string, { x: number; y: number }>()
+  if (nodes.length === 0) return positions
+
+  const width = Math.max(320, canvasSize.width || 800)
+  const height = Math.max(360, canvasSize.height || 560)
+  const padding = Math.max(48, settings.nodeSpacing + 18)
+  const spreadRatio = 0.72 + ((settings.repulsion - 40) / 360) * 0.28
+  const contentWidth = Math.max(120, (width - padding * 2) * spreadRatio)
+  const contentHeight = Math.max(120, (height - padding * 2) * spreadRatio)
+  const offsetX = (width - contentWidth) / 2
+  const offsetY = (height - contentHeight) / 2
+  const ratio = contentWidth / contentHeight
+  const columns = Math.max(1, Math.ceil(Math.sqrt(nodes.length * ratio)))
+  const rows = Math.max(1, Math.ceil(nodes.length / columns))
+  const cellWidth = contentWidth / columns
+  const cellHeight = contentHeight / rows
+  const connected = new Set<string>()
+
+  edges.forEach(edge => {
+    connected.add(edge.source)
+    connected.add(edge.target)
+  })
+
+  const orderedNodes = [...nodes].sort((a, b) => {
+    const connectionDelta = Number(connected.has(b.id)) - Number(connected.has(a.id))
+    if (connectionDelta !== 0) return connectionDelta
+    return stableRandom(a.id) - stableRandom(b.id)
+  })
+
+  orderedNodes.forEach((node, index) => {
+    const column = index % columns
+    const row = Math.floor(index / columns)
+    const jitterScale = connected.has(node.id) ? 0.28 : 0.42
+    const jitterX = (stableRandom(`${node.id}:x`) - 0.5) * cellWidth * jitterScale
+    const jitterY = (stableRandom(`${node.id}:y`) - 0.5) * cellHeight * jitterScale
+    const x = offsetX + cellWidth * (column + 0.5) + jitterX
+    const y = offsetY + cellHeight * (row + 0.5) + jitterY
+
+    positions.set(node.id, {
+      x: Math.min(width - padding, Math.max(padding, x)),
+      y: Math.min(height - padding, Math.max(padding, y)),
+    })
+  })
+
+  return positions
+}
+
+function graphPresetName(settings: GraphLayoutSettings) {
+  if (settings.denseMode && settings.nodeSize <= 14 && settings.edgeOpacity <= 0.4) return 'Nebula'
+  if (settings.edgeLabelMode === 'always' && settings.labelMode === 'always') return 'Debug'
+  return 'Readable'
+}
+
+export default function SkillGraph() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const graphShellRef = useRef<HTMLDivElement>(null)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const graphRef = useRef<GraphInstance | null>(null)
+  const openedFromQuery = useRef<string | null>(null)
+
+  const [viewMode, setViewMode] = useState<GraphViewMode>('skill_only')
+  const [mode, setMode] = useState<GraphMode>('full')
+  const [graphData, setGraphData] = useState<GraphViewData | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [subgraphLoading, setSubgraphLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [edgeFilter, setEdgeFilter] = useState<string[]>([])
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null)
+  const [selectedEdgeId, setSelectedEdgeId] = useState<string | null>(null)
+  const [centerSkillId, setCenterSkillId] = useState<string | null>(null)
+  const [depth, setDepth] = useState(2)
+  const [layoutSettings, setLayoutSettings] = useState<GraphLayoutSettings>(loadLayoutSettings)
+  const [layoutDraft, setLayoutDraft] = useState<GraphLayoutSettings>(loadLayoutSettings)
+  const [layoutPanelOpen, setLayoutPanelOpen] = useState(false)
+  const [canvasSize, setCanvasSize] = useState<GraphCanvasSize>({ width: 800, height: 560 })
+  const [nebulaMode, setNebulaMode] = useState(true)
+
+  const selectedNode = useMemo(
+    () => graphData?.nodes.find(node => node.id === selectedNodeId) || null,
+    [graphData, selectedNodeId],
+  )
+
+  const selectedEdge = useMemo(
+    () => graphData?.edges.find(edge => edge.id === selectedEdgeId) || null,
+    [graphData, selectedEdgeId],
+  )
+
+  const centerNode = useMemo(
+    () => graphData?.nodes.find(node => node.id === centerSkillId) || null,
+    [graphData, centerSkillId],
+  )
+
+  const nodeById = useMemo(() => {
+    const nodes = new Map<string, GraphViewNodeData>()
+    graphData?.nodes.forEach(node => nodes.set(node.id, node))
+    return nodes
+  }, [graphData])
+
+  const edgeTypes = useMemo(
+    () => (graphData ? [...new Set(graphData.edges.map(edge => edge.edge_type))] : []),
+    [graphData],
+  )
+
+  const nodeLegend = useMemo(() => {
+    if (!graphData) return []
+    const values = viewMode === 'skill_only'
+      ? Object.keys(TYPE_COLOR)
+      : [...new Set(graphData.nodes.map(node => node.kind))]
+    return values.map(value => ({
+      value,
+      label: viewMode === 'skill_only' ? value : formatKind(value),
+      color: viewMode === 'skill_only' ? TYPE_COLOR[value] : KIND_COLOR[value] || '#8c8c8c',
+    }))
+  }, [graphData, viewMode])
+
+  const resetSelection = useCallback(() => {
+    setSelectedNodeId(null)
+    setSelectedEdgeId(null)
+    setCenterSkillId(null)
+    setEdgeFilter([])
+  }, [])
+
+  const loadGraphForView = useCallback(async (nextView: GraphViewMode) => {
+    setLoading(true)
+    setError(null)
+    resetSelection()
+    try {
+      const data = await graphApi.view(nextView, 300)
+      setGraphData(data)
+      setMode('full')
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Failed to load graph data'))
+    } finally {
+      setLoading(false)
+    }
+  }, [resetSelection])
+
+  const loadSubgraph = useCallback(async (skillId: string, nextDepth = depth) => {
+    if (!skillId) return
+    setSubgraphLoading(true)
+    setError(null)
+    setViewMode('skill_only')
+    try {
+      const data = await graphApi.subgraph(skillId, nextDepth)
+      setGraphData(graphDataToView(data))
+      setMode('subgraph')
+      setCenterSkillId(skillId)
+      setSelectedNodeId(skillId)
+      setSelectedEdgeId(null)
+      setEdgeFilter([])
+    } catch (err) {
+      setError(getApiErrorMessage(err, 'Failed to load subgraph; current view is preserved'))
+    } finally {
+      setSubgraphLoading(false)
+      setLoading(false)
+    }
+  }, [depth])
+
+  useEffect(() => {
+    if (viewMode !== 'skill_only') return
+    const querySkillId = new URLSearchParams(location.search).get('skill_id')
+    const timeoutId = window.setTimeout(() => {
+      if (querySkillId && openedFromQuery.current !== querySkillId) {
+        openedFromQuery.current = querySkillId
+        void loadSubgraph(querySkillId, depth)
+        return
+      }
+      if (!querySkillId && !graphData) {
+        void loadGraphForView('skill_only')
+      }
+    }, 0)
+    return () => window.clearTimeout(timeoutId)
+  }, [depth, graphData, loadGraphForView, loadSubgraph, location.search, viewMode])
+
+  // Auto-select a node when ?preselect=<id> is in the URL and graph is loaded
+  useEffect(() => {
+    if (!graphData?.nodes.length) return
+    const preselectId = new URLSearchParams(location.search).get('preselect')
+    if (preselectId && graphData.nodes.some(n => n.id === preselectId)) {
+      setSelectedNodeId(preselectId)
+    }
+  }, [graphData, location.search])
+
+  useEffect(() => {
+    if (!graphData?.nodes.length || !graphShellRef.current) return
+
+    const target = graphShellRef.current
+    const updateSize = () => {
+      const next = {
+        width: Math.max(320, Math.round(target.clientWidth || 800)),
+        height: Math.max(360, Math.round(target.clientHeight || 560)),
+      }
+
+      setCanvasSize(previous => {
+        if (Math.abs(previous.width - next.width) < 8 && Math.abs(previous.height - next.height) < 8) {
+          return previous
+        }
+        return next
+      })
+    }
+
+    updateSize()
+
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', updateSize)
+      return () => window.removeEventListener('resize', updateSize)
+    }
+
+    const observer = new ResizeObserver(updateSize)
+    observer.observe(target)
+    return () => observer.disconnect()
+  }, [graphData?.nodes.length])
+
+  useEffect(() => {
+    if (!graphData || !containerRef.current || graphData.nodes.length === 0) return
+
+    let disposed = false
+
+    import('@antv/g6').then((G6) => {
+      if (disposed || !containerRef.current) return
+
+      if (graphRef.current) {
+        graphRef.current.destroy()
+        graphRef.current = null
+      }
+
+      const filteredEdges = edgeFilter.length > 0
+        ? graphData.edges.filter(edge => edgeFilter.includes(edge.edge_type))
+        : graphData.edges
+      const graphWidth = canvasSize.width || containerRef.current.clientWidth || 800
+      const graphHeight = canvasSize.height || containerRef.current.clientHeight || 560
+      const forceLayout = {
+        type: 'force',
+        preventOverlap: true,
+        nodeSize: layoutSettings.nodeSpacing,
+        linkDistance: (edge?: ForceEdgeDatum) => weightedLinkDistance(edge, layoutSettings.linkDistance),
+        nodeStrength: layoutSettings.repulsion,
+        edgeStrength: (edge?: ForceEdgeDatum) => weightedEdgeStrength(edge, layoutSettings.attraction),
+      }
+      const initialPositions = calculateInitialNodePositions(
+        graphData.nodes,
+        filteredEdges,
+        { width: graphWidth, height: graphHeight },
+        layoutSettings,
+      )
+
+      const nodes = graphData.nodes.map(node => {
+        const color = nodeColor(node)
+        const selected = node.id === selectedNodeId
+        const centered = node.id === centerSkillId
+        const position = initialPositions.get(node.id)
+        const nodeDepth = nebulaMode ? stableRandom(node.id) : 0
+        const isForeground = nodeDepth < 0.5
+        const { sizeScale, opacityScale } = nebulaMode ? depthScale(nodeDepth) : { sizeScale: 1, opacityScale: 1 }
+        const nebulaSize = (isForeground
+          ? 5 + Math.floor(Number(node.usage_count || 0) * 0.025)
+          : 3 + Math.floor(Number(node.usage_count || 0) * 0.008)) * sizeScale
+        const nebulaFill = nebulaMode ? sphereGradient(color) : color
+        // Highlight ring for selected nebula nodes
+        const nebulaShadowColor = selected ? color : 'transparent'
+        const nebulaShadowBlur = selected ? 10 : 0
+        return {
+          id: node.id,
+          data: {
+            label: node.name,
+            nodeKind: node.kind,
+            state: node.state,
+          },
+          style: {
+            x: position?.x,
+            y: position?.y,
+            fill: nebulaFill,
+            fillOpacity: nebulaMode
+              ? (isForeground ? 0.95 : 0.82 * opacityScale)
+              : (node.kind === 'skill' ? (STATE_OPACITY[String(node.state || '')] || 0.65) : 0.92),
+            stroke: nebulaMode
+              ? (selected ? color : blendColor(color, 'white', 0.4))
+              : (selected || centered ? '#111827' : color),
+            strokeOpacity: nebulaMode ? (selected ? 1 : 0.5 * opacityScale) : 1,
+            lineWidth: nebulaMode
+              ? (selected ? 1.2 : 0.6)
+              : (selected || centered ? 2.4 : Math.max(0.7, layoutSettings.edgeWidth * 0.8)),
+            size: nebulaMode
+              ? (selected ? nebulaSize + 4 : nebulaSize)
+              : nodeVisualSize(node, layoutSettings, selected, centered),
+            shadowColor: nebulaMode ? nebulaShadowColor : 'transparent',
+            shadowBlur: nebulaMode ? nebulaShadowBlur : 0,
+            labelText: nebulaMode ? '' : (shouldShowNodeLabel(layoutSettings.labelMode, {
+              selected,
+              centered,
+              denseMode: layoutSettings.denseMode,
+            }) ? node.name : ''),
+            labelFill: '#111827',
+            labelFontSize: nodeLabelFontSize(layoutSettings, selected, centered),
+            labelFontWeight: selected || centered ? 700 : 600,
+            labelMaxWidth: '260%',
+            labelPlacement: 'bottom' as const,
+            labelOffsetY: layoutSettings.denseMode ? 4 : 5,
+            labelStroke: '#fff',
+            labelLineWidth: layoutSettings.denseMode ? 2 : 3,
+            labelWordWrap: true,
+            cursor: 'pointer',
+          },
+        }
+      })
+
+      const edges = filteredEdges.map(edge => {
+        const selected = edge.id === selectedEdgeId
+        const color = EDGE_COLOR[edge.edge_type] || '#8c8c8c'
+        const edgeDepth = nebulaMode ? (stableRandom(edge.source) + stableRandom(edge.target)) / 2 : 0
+        const edgeOpacityByDepth = nebulaMode ? 0.22 - edgeDepth * 0.14 : layoutSettings.edgeOpacity
+        const edgeWidthByDepth = nebulaMode ? 0.6 - edgeDepth * 0.3 : undefined
+        return {
+          id: edge.id,
+          source: edge.source,
+          target: edge.target,
+          data: { edgeType: edge.edge_type, weight: edge.weight },
+          style: {
+            stroke: color,
+            strokeOpacity: nebulaMode
+              ? (selected ? 0.9 : edgeOpacityByDepth)
+              : (selected ? 1 : layoutSettings.edgeOpacity),
+            lineWidth: nebulaMode
+              ? (selected ? 1.2 : (edgeWidthByDepth ?? 0.5))
+              : (selected
+                ? Math.max(2.4, layoutSettings.edgeWidth + Number(edge.weight || 0) * 1.8)
+                : Math.max(0.4, layoutSettings.edgeWidth + Number(edge.weight || 0) * 0.7)),
+            endArrow: !nebulaMode,
+            labelText: nebulaMode ? '' : formatEdgeLabel(edge),
+            labelFontSize: 9,
+            labelFill: color,
+            label: false,
+            labelStroke: '#fff',
+            labelLineWidth: 3,
+            labelPlacement: 'center' as const,
+            labelOffsetX: 0,
+            labelOffsetY: -18,
+            badgeText: nebulaMode ? '' : formatEdgeLabel(edge),
+            badgeFontSize: 9,
+            badgeFill: color,
+            badgeBackgroundFill: '#fff',
+            badgeBackgroundOpacity: nebulaMode ? 0 : 0.9,
+            badgeBackgroundRadius: 4,
+            badgePadding: [1, 4, 1, 4],
+            badgePlacement: 'suffix' as const,
+            badgeOffsetX: 0,
+            badgeOffsetY: -18,
+            cursor: 'pointer',
+          },
+        }
+      })
+
+      const g = new G6.Graph({
+        container: containerRef.current,
+        width: graphWidth,
+        height: graphHeight,
+        data: { nodes, edges },
+        autoFit: 'view',
+        padding: [48, 48, 72, 48],
+        zoomRange: [0.1, 2.0],
+        ...(filteredEdges.length > 0 ? { layout: forceLayout } : {}),
+        behaviors: [
+          'drag-canvas',
+          'zoom-canvas',
+          'drag-element',
+          {
+            type: 'auto-adapt-label',
+            padding: 8,
+            throttle: 64,
+          },
+          {
+            type: 'click-select',
+            degree: 0,
+          },
+        ],
+        node: { type: 'circle' },
+        edge: { type: 'line' },
+      }) as GraphInstance
+
+      let graphReady = false
+      let edgeLabelsVisibleKey: string | null = null
+      const syncEdgeLabelVisibility = () => {
+        if (disposed || !graphReady || filteredEdges.length === 0) return
+        const visibleIds = shouldShowEdgeLabels(
+          layoutSettings.edgeLabelMode,
+          g.getZoom(),
+          filteredEdges,
+          selectedEdgeId,
+        )
+        const visibleKey = `${layoutSettings.edgeLabelMode}:${g.getZoom().toFixed(2)}:${selectedEdgeId || ''}:${visibleIds.size}`
+        if (edgeLabelsVisibleKey === visibleKey) return
+
+        edgeLabelsVisibleKey = visibleKey
+        g.updateEdgeData(filteredEdges.map(edge => ({
+          id: edge.id,
+          style: { badgeText: visibleIds.has(edge.id) ? formatEdgeLabel(edge) : '' },
+        })))
+        void Promise.resolve(g.draw())
+      }
+
+      const updateHoveredNodeLabel = (id: string | undefined, visible: boolean) => {
+        if (!id || layoutSettings.labelMode !== 'hover') return
+        const node = graphData.nodes.find(item => item.id === id)
+        if (!node) return
+        const selected = id === selectedNodeId
+        const centered = id === centerSkillId
+        const shouldKeep = shouldShowNodeLabel(layoutSettings.labelMode, {
+          selected,
+          centered,
+          denseMode: layoutSettings.denseMode,
+        })
+        g.updateNodeData([{
+          id,
+          style: {
+            labelText: visible || shouldKeep ? node.name : '',
+            size: visible ? Math.max(nodeVisualSize(node, layoutSettings, selected, centered) + 5, 18) : nodeVisualSize(node, layoutSettings, selected, centered),
+          },
+        }])
+        void Promise.resolve(g.draw())
+      }
+
+      g.on('node:click', event => {
+        const id = event.target?.id
+        if (id) {
+          setSelectedNodeId(id)
+          setSelectedEdgeId(null)
+        }
+      })
+
+      g.on('edge:click', event => {
+        const id = event.target?.id
+        if (id) {
+          setSelectedEdgeId(id)
+          setSelectedNodeId(null)
+        }
+      })
+
+      g.on('node:pointerenter', event => updateHoveredNodeLabel(event.target?.id, true))
+      g.on('node:pointerleave', event => updateHoveredNodeLabel(event.target?.id, false))
+
+      g.on('canvas:click', () => {
+        setSelectedNodeId(null)
+        setSelectedEdgeId(null)
+      })
+
+      // Zoom → nebula mode transition
+      g.on('aftertransform', () => {
+        if (disposed) return
+        const zoom = g.getZoom()
+        setNebulaMode(zoom < NEBULA_ZOOM_THRESHOLD)
+        syncEdgeLabelVisibility()
+      })
+
+      graphRef.current = g
+      void Promise.resolve(g.render()).then(() => {
+        if (!disposed) {
+          graphReady = true
+          syncEdgeLabelVisibility()
+          void Promise.resolve(g.fitView({ when: 'always' }, { duration: 160 })).then(() => {
+            syncEdgeLabelVisibility()
+            g.on('aftertransform', syncEdgeLabelVisibility)
+          })
+        }
+      })
+    })
+
+    return () => {
+      disposed = true
+      if (graphRef.current) {
+        graphRef.current.destroy()
+        graphRef.current = null
+      }
+    }
+  }, [canvasSize, centerSkillId, edgeFilter, graphData, layoutSettings, nebulaMode, selectedEdgeId, selectedNodeId])
+
+  const handleViewChange = (nextView: GraphViewMode) => {
+    setViewMode(nextView)
+    openedFromQuery.current = null
+    navigate('/graph', { replace: true })
+    void loadGraphForView(nextView)
+  }
+
+  const reloadCurrentView = () => {
+    if (viewMode === 'skill_only' && mode === 'subgraph' && centerSkillId) {
+      void loadSubgraph(centerSkillId, depth)
+      return
+    }
+    void loadGraphForView(viewMode)
+  }
+
+  const returnToFullGraph = () => {
+    openedFromQuery.current = null
+    navigate('/graph', { replace: true })
+    setViewMode('skill_only')
+    void loadGraphForView('skill_only')
+  }
+
+  const openWiki = () => {
+    if (!selectedNode || selectedNode.kind !== 'skill') return
+    navigate(`/wiki?skill_id=${encodeURIComponent(selectedNode.id)}`)
+  }
+
+  const expandSelectedSkill = () => {
+    if (!selectedNode || selectedNode.kind !== 'skill') return
+    void loadSubgraph(selectedNode.id, depth)
+  }
+
+  const hasNodes = Boolean(graphData?.nodes.length)
+  const selectedNodeTags = uniqueTags(selectedNode?.tags)
+  const selectedNodeMetadata = metadataEntries(selectedNode?.metadata)
+  const selectedEdgeMetadata = metadataEntries(selectedEdge?.metadata)
+  const viewCopy = GRAPH_VIEW_COPY[viewMode]
+  const detailTitle = selectedEdge ? 'Edge Details' : 'Node Details'
+  const relationStrengthText = relationStrengthSummary(graphData?.metadata)
+
+  const zoomGraph = (ratio: number) => {
+    void graphRef.current?.zoomBy(ratio, { duration: 180 })
+  }
+
+  const fitGraph = () => {
+    void graphRef.current?.fitView({ when: 'always' }, { duration: 180 })
+  }
+
+  const updateLayoutDraft = (field: keyof GraphLayoutSettings, value: number) => {
+    setLayoutDraft(previous => normalizeLayoutSettings({ ...previous, [field]: value }))
+  }
+
+  const updateLayoutDraftValue = (field: keyof GraphLayoutSettings, value: GraphLayoutSettings[keyof GraphLayoutSettings]) => {
+    setLayoutDraft(previous => normalizeLayoutSettings({ ...previous, [field]: value }))
+  }
+
+  const applyLayoutSettings = () => {
+    const next = normalizeLayoutSettings(layoutDraft)
+    setLayoutSettings(next)
+    setLayoutDraft(next)
+    saveLayoutSettings(next)
+    setLayoutPanelOpen(false)
+  }
+
+  const resetLayoutSettings = () => {
+    const next = DEFAULT_GRAPH_LAYOUT
+    setLayoutSettings(next)
+    setLayoutDraft(next)
+    saveLayoutSettings(next)
+  }
+
+  const applyLayoutPreset = (preset: keyof typeof GRAPH_LAYOUT_PRESETS) => {
+    const next = normalizeLayoutSettings(GRAPH_LAYOUT_PRESETS[preset])
+    setLayoutDraft(next)
+    setLayoutSettings(next)
+    saveLayoutSettings(next)
+  }
+
+  const handleLayoutPanelOpenChange = (open: boolean) => {
+    setLayoutPanelOpen(open)
+    if (open) setLayoutDraft(layoutSettings)
+  }
+
+  const renderLayoutSlider = (
+    label: string,
+    field: NumericGraphLayoutField,
+    min: number,
+    max: number,
+    step = 1,
+  ) => {
+    const value = layoutDraft[field]
+    const displayValue = field === 'attraction' ? value.toFixed(2) : Math.round(value)
+
+    return (
+      <div>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: 12 }}>
+          <Text>{label}</Text>
+          <Text code>{displayValue}</Text>
+        </div>
+        <Slider
+          min={min}
+          max={max}
+          step={step}
+          value={value}
+          onChange={next => updateLayoutDraft(field, Number(next))}
+        />
+      </div>
+    )
+  }
+
+  const layoutSettingsContent = (
+    <div style={{ width: 320 }}>
+      <Space orientation="vertical" size={12} style={{ width: '100%' }}>
+        <Text strong>Graph Visual Settings</Text>
+        <Space.Compact block>
+          <Button size="small" onClick={() => applyLayoutPreset('nebula')}>Nebula</Button>
+          <Button size="small" onClick={() => applyLayoutPreset('readable')}>Readable</Button>
+          <Button size="small" onClick={() => applyLayoutPreset('debug')}>Debug</Button>
+        </Space.Compact>
+        {renderLayoutSlider('Node size', 'nodeSize', 6, 42)}
+        {renderLayoutSlider('Edge width', 'edgeWidth', 0.4, 4, 0.1)}
+        {renderLayoutSlider('Edge opacity', 'edgeOpacity', 0.08, 1, 0.02)}
+        {renderLayoutSlider('Charge strength', 'repulsion', 40, 400)}
+        {renderLayoutSlider('Attraction', 'attraction', 0.05, 1, 0.05)}
+        {renderLayoutSlider('Link distance', 'linkDistance', 60, 280)}
+        {renderLayoutSlider('Node spacing', 'nodeSpacing', 28, 96)}
+        <div>
+          <Text>Node labels</Text>
+          <Segmented
+            block
+            size="small"
+            options={LABEL_MODE_OPTIONS}
+            value={layoutDraft.labelMode}
+            onChange={value => updateLayoutDraftValue('labelMode', value as GraphLabelMode)}
+            style={{ marginTop: 6 }}
+          />
+        </div>
+        <div>
+          <Text>Edge labels</Text>
+          <Segmented
+            block
+            size="small"
+            options={LABEL_MODE_OPTIONS}
+            value={layoutDraft.edgeLabelMode}
+            onChange={value => updateLayoutDraftValue('edgeLabelMode', value as GraphLabelMode)}
+            style={{ marginTop: 6 }}
+          />
+        </div>
+        <div style={{ display: 'flex', justifyContent: 'space-between', gap: 12, alignItems: 'center' }}>
+          <Text>Dense mode</Text>
+          <Switch
+            size="small"
+            checked={layoutDraft.denseMode}
+            onChange={checked => updateLayoutDraftValue('denseMode', checked)}
+          />
+        </div>
+        <Space style={{ justifyContent: 'flex-end', width: '100%' }}>
+          <Button size="small" onClick={resetLayoutSettings}>Reset</Button>
+          <Button size="small" type="primary" onClick={applyLayoutSettings}>Apply</Button>
+        </Space>
+      </Space>
+    </div>
+  )
+
+  return (
+    <div style={{ padding: 24, minHeight: 'calc(100vh - 120px)' }}>
+      <div style={{ display: 'flex', justifyContent: 'space-between', gap: 16, alignItems: 'center', marginBottom: 12, flexWrap: 'wrap' }}>
+        <div>
+          <h2 style={{ margin: 0, fontWeight: 700 }}>Skill Knowledge Graph</h2>
+          <Text type="secondary">{viewCopy.subtitle}</Text>
+        </div>
+        <Space wrap>
+          <Segmented
+            options={GRAPH_VIEW_OPTIONS}
+            value={viewMode}
+            onChange={value => handleViewChange(value as GraphViewMode)}
+          />
+          <Select
+            mode="multiple"
+            placeholder="Filter edge types"
+            style={{ minWidth: 220 }}
+            allowClear
+            value={edgeFilter}
+            onChange={setEdgeFilter}
+            options={edgeTypes.map(type => ({ label: formatEdgeType(type), value: type }))}
+          />
+          <Button icon={<ReloadOutlined />} onClick={reloadCurrentView} loading={loading}>
+            {viewCopy.reload}
+          </Button>
+        </Space>
+      </div>
+
+      {error && (
+        <Alert
+          type="error"
+          showIcon
+          closable
+          onClose={() => setError(null)}
+          title={error}
+          style={{ marginBottom: 12 }}
+        />
+      )}
+
+      {mode === 'subgraph' && centerNode && (
+        <Alert
+          type="info"
+          showIcon
+          title={`Subgraph center: ${centerNode.name}`}
+          description={`depth=${depth}, ${graphData?.nodes.length || 0} nodes, ${graphData?.edges.length || 0} edges.`}
+          action={(
+            <Button size="small" icon={<RollbackOutlined />} onClick={returnToFullGraph}>
+              Back to full graph
+            </Button>
+          )}
+          style={{ marginBottom: 12 }}
+        />
+      )}
+
+      {viewMode === 'version_impact' && Boolean(graphData?.metadata?.meta_paths) && (
+        <Alert
+          type="info"
+          showIcon
+          title="Projection meta-paths"
+          description={formatMetadataValue(graphData?.metadata?.meta_paths)}
+          style={{ marginBottom: 12 }}
+        />
+      )}
+
+      {/* Relation strength summary is available in graph metadata for debugging */}
+
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 360px), 1fr))', gap: 16, alignItems: 'stretch' }}>
+        <Card
+          style={{
+            minHeight: 560, borderRadius: 8, overflow: 'hidden', minWidth: 0,
+            background: nebulaMode ? '#f4f5f9' : undefined,
+            transition: 'background 0.4s ease',
+          }}
+          styles={{ body: { padding: 0, height: 560 } }}
+        >
+          {loading && !graphData ? (
+            <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100%' }}>
+              <Spin size="large" tip="Loading graph data..." />
+            </div>
+          ) : !hasNodes ? (
+            <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100%', padding: 24 }}>
+              <Empty description={viewCopy.empty}>
+                <Button icon={<ReloadOutlined />} onClick={reloadCurrentView}>
+                  Reload
+                </Button>
+              </Empty>
+            </div>
+          ) : (
+            <div ref={graphShellRef} style={{ position: 'relative', width: '100%', height: '100%', minHeight: 560 }}>
+              <div ref={containerRef} style={{ width: '100%', height: '100%', minHeight: 560 }} />
+              {/* Vignette overlay for depth illusion in nebula mode */}
+              {nebulaMode && (
+                <div style={{
+                  position: 'absolute', inset: 0, pointerEvents: 'none', zIndex: 1,
+                  borderRadius: 8,
+                  background: 'radial-gradient(ellipse at 50% 50%, transparent 55%, rgba(240,241,246,0.55) 80%, rgba(228,230,240,0.82) 100%)',
+                }} />
+              )}
+              <Space.Compact style={{ position: 'absolute', right: 12, top: 12, zIndex: 2, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}>
+                <Popover
+                  content={layoutSettingsContent}
+                  trigger="click"
+                  placement="bottomRight"
+                  open={layoutPanelOpen}
+                  onOpenChange={handleLayoutPanelOpenChange}
+                >
+                  <Button size="small" icon={<SettingOutlined />} aria-label="Layout settings" />
+                </Popover>
+                <Tooltip title="Zoom in">
+                  <Button size="small" icon={<ZoomInOutlined />} aria-label="Zoom in" onClick={() => zoomGraph(1.2)} />
+                </Tooltip>
+                <Tooltip title="Zoom out">
+                  <Button size="small" icon={<ZoomOutOutlined />} aria-label="Zoom out" onClick={() => zoomGraph(0.8)} />
+                </Tooltip>
+                <Tooltip title="Fit view">
+                  <Button size="small" icon={<AimOutlined />} aria-label="Fit view" onClick={fitGraph} />
+                </Tooltip>
+              </Space.Compact>
+            </div>
+          )}
+        </Card>
+
+        <Card
+          title={detailTitle}
+          style={{ borderRadius: 8, minWidth: 0 }}
+          styles={{ body: { paddingTop: 12 } }}
+          extra={selectedNode ? <Tag color={nodeColor(selectedNode)}>{formatKind(selectedNode.kind)}</Tag> : null}
+        >
+          {selectedEdge ? (
+            <Space orientation="vertical" size={14} style={{ width: '100%' }}>
+              <div>
+                <Text strong style={{ fontSize: 16 }}>{formatEdgeType(selectedEdge.edge_type)}</Text>
+                <Paragraph copyable={{ text: selectedEdge.id }} style={{ margin: '6px 0 0' }}>
+                  <Text code>{selectedEdge.id}</Text>
+                </Paragraph>
+              </div>
+              <Descriptions column={1} size="small" bordered>
+                <Descriptions.Item label="Source">
+                  {nodeById.get(selectedEdge.source)?.name || selectedEdge.source}
+                </Descriptions.Item>
+                <Descriptions.Item label="Target">
+                  {nodeById.get(selectedEdge.target)?.name || selectedEdge.target}
+                </Descriptions.Item>
+                <Descriptions.Item label="Weight">
+                  {selectedEdge.weight.toFixed(2)}
+                </Descriptions.Item>
+                {selectedEdge.confidence !== undefined && selectedEdge.confidence !== null && (
+                  <Descriptions.Item label="Confidence">
+                    {selectedEdge.confidence.toFixed(2)}
+                  </Descriptions.Item>
+                )}
+              </Descriptions>
+              {selectedEdgeMetadata.length > 0 && (
+                <Descriptions column={1} size="small" bordered title="Evidence">
+                  {selectedEdgeMetadata.slice(0, 8).map(([key, value]) => (
+                    <Descriptions.Item key={key} label={key}>
+                      <Text style={{ whiteSpace: 'pre-wrap' }}>{formatMetadataValue(value)}</Text>
+                    </Descriptions.Item>
+                  ))}
+                </Descriptions>
+              )}
+            </Space>
+          ) : selectedNode ? (
+            <Space orientation="vertical" size={14} style={{ width: '100%' }}>
+              <div>
+                <Text strong style={{ fontSize: 16 }}>{selectedNode.name}</Text>
+                <Paragraph copyable={{ text: selectedNode.id }} style={{ margin: '6px 0 0' }}>
+                  <Text code>{selectedNode.id}</Text>
+                </Paragraph>
+                {selectedNode.description && (
+                  <Paragraph style={{ marginBottom: 0 }}>{selectedNode.description}</Paragraph>
+                )}
+              </div>
+
+              <Descriptions column={1} size="small" bordered>
+                <Descriptions.Item label="Kind">
+                  <Tag color={nodeColor(selectedNode)}>{formatKind(selectedNode.kind)}</Tag>
+                </Descriptions.Item>
+                {selectedNode.state && (
+                  <Descriptions.Item label="State">
+                    <Tag>{STATE_LABEL[selectedNode.state] || selectedNode.state}</Tag>
+                  </Descriptions.Item>
+                )}
+                {selectedNode.version && (
+                  <Descriptions.Item label="Version">
+                    <Text code>{selectedNode.version}</Text>
+                  </Descriptions.Item>
+                )}
+                {selectedNode.success_rate !== undefined && selectedNode.success_rate !== null && (
+                  <Descriptions.Item label="Success rate">
+                    {formatPercent(selectedNode.success_rate)}
+                  </Descriptions.Item>
+                )}
+                {selectedNode.usage_count !== undefined && selectedNode.usage_count !== null && (
+                  <Descriptions.Item label="Usage count">
+                    {selectedNode.usage_count}
+                  </Descriptions.Item>
+                )}
+                {selectedNode.granularity_level !== undefined && selectedNode.granularity_level !== null && (
+                  <Descriptions.Item label="Granularity">
+                    {selectedNode.granularity_level}
+                  </Descriptions.Item>
+                )}
+              </Descriptions>
+
+              {selectedNodeTags.length > 0 && (
+                <div>
+                  <Text type="secondary">Tags</Text>
+                  <div style={{ marginTop: 6 }}>
+                    {selectedNodeTags.map(tag => <Tag key={tag}>{tag}</Tag>)}
+                  </div>
+                </div>
+              )}
+
+              {selectedNodeMetadata.length > 0 && (
+                <Descriptions column={1} size="small" bordered title="Metadata">
+                  {selectedNodeMetadata.slice(0, 8).map(([key, value]) => (
+                    <Descriptions.Item key={key} label={key}>
+                      <Text style={{ whiteSpace: 'pre-wrap' }}>{formatMetadataValue(value)}</Text>
+                    </Descriptions.Item>
+                  ))}
+                </Descriptions>
+              )}
+
+              {selectedNode.kind === 'skill' && (
+                <>
+                  <Space.Compact style={{ width: '100%' }}>
+                    <span style={{ display: 'inline-flex', alignItems: 'center', padding: '0 10px', border: '1px solid #d9d9d9', borderRight: 0, borderRadius: '6px 0 0 6px', color: '#666', background: '#fafafa' }}>
+                      Depth
+                    </span>
+                    <InputNumber
+                      min={1}
+                      max={5}
+                      value={depth}
+                      onChange={value => setDepth(value || 2)}
+                      style={{ width: 92 }}
+                    />
+                    <Button
+                      icon={<ShareAltOutlined />}
+                      loading={subgraphLoading}
+                      onClick={expandSelectedSkill}
+                      style={{ flex: 1 }}
+                    >
+                      Expand related
+                    </Button>
+                  </Space.Compact>
+                  <Button block type="primary" icon={<ExportOutlined />} onClick={openWiki}>
+                    Open in Wiki
+                  </Button>
+                </>
+              )}
+            </Space>
+          ) : (
+            <Empty
+              image={Empty.PRESENTED_IMAGE_SIMPLE}
+              description="Click a node or edge to inspect its evidence."
+            />
+          )}
+        </Card>
+      </div>
+
+      <div style={{ display: 'flex', justifyContent: 'space-between', gap: 16, marginTop: 10, color: '#8c8c8c', fontSize: 12, flexWrap: 'wrap' }}>
+        <Space wrap>
+          {nodeLegend.map(item => (
+            <Tag key={item.value} color={item.color} style={{ borderRadius: 8 }}>{item.label}</Tag>
+          ))}
+          <span>
+            {viewMode === 'skill_only'
+              ? 'Node color = skill type; opacity = lifecycle state.'
+              : 'Node color = provenance kind; edges preserve typed evidence links.'}
+          </span>
+        </Space>
+        {graphData && (
+          <Space size={8} wrap>
+            <span>{graphPresetName(layoutSettings)} preset</span>
+            <span>{graphData.nodes.length} nodes / {graphData.edges.length} edges</span>
+          </Space>
+        )}
+      </div>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/SkillWiki.tsx

@@ -0,0 +1,613 @@
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
+import {
+  Badge,
+  Button,
+  Descriptions,
+  Drawer,
+  Input,
+  Popconfirm,
+  Progress,
+  Select,
+  Space,
+  Table,
+  Tabs,
+  Tag,
+  Timeline,
+  Tooltip,
+  Typography,
+  message,
+} from 'antd'
+import type { TableColumnsType } from 'antd'
+import {
+  CheckOutlined,
+  EyeOutlined,
+  HistoryOutlined,
+  PlayCircleOutlined,
+  SafetyCertificateOutlined,
+  SearchOutlined,
+  StopOutlined,
+} from '@ant-design/icons'
+import { motion } from 'framer-motion'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { skillsApi, lifecycleApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type { SkillFull, SkillParameter, SkillState, SkillSummary, SkillType } from '@/api/types'
+
+const { Text, Paragraph } = Typography
+
+const STATE_COLOR: Record<string, string> = {
+  S0: 'purple',
+  S1: 'orange',
+  S2: 'blue',
+  S3: 'cyan',
+  S4: 'green',
+  S5: 'gold',
+  S6: 'red',
+  S7: 'default',
+}
+
+const STATE_LABEL: Record<string, string> = {
+  S0: 'Raw',
+  S1: 'Candidate',
+  S2: 'Draft',
+  S3: 'Verified',
+  S4: 'Released',
+  S5: 'Degraded',
+  S6: 'Deprecated',
+  S7: 'Archived',
+}
+
+const TYPE_COLOR: Record<string, string> = {
+  atomic: 'blue',
+  functional: 'purple',
+  strategic: 'gold',
+}
+
+function schemaToParameters(schema: SkillFull['interface']['input_schema'] | SkillFull['interface']['output_schema']): SkillParameter[] {
+  const properties = schema?.properties ?? {}
+  const required = new Set(schema?.required ?? [])
+
+  return Object.entries(properties).map(([name, field]) => ({
+    name,
+    type: field.type ?? 'unknown',
+    description: field.description ?? '',
+    required: required.has(name),
+    default: field.default,
+  }))
+}
+
+function getInterfaceParameters(skill: SkillFull, direction: 'input' | 'output'): SkillParameter[] {
+  const skillInterface = skill.interface
+  if (!skillInterface) return []
+  if (direction === 'input') {
+    return Array.isArray(skillInterface.inputs) ? skillInterface.inputs : schemaToParameters(skillInterface.input_schema)
+  }
+  return Array.isArray(skillInterface.outputs) ? skillInterface.outputs : schemaToParameters(skillInterface.output_schema)
+}
+
+function uniqueTags(tags?: string[]): string[] {
+  return Array.from(new Set((tags ?? []).filter(Boolean)))
+}
+
+function formatDate(value?: string) {
+  if (!value) return ''
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString()
+}
+
+function buildSkillTimeline(skill: SkillFull) {
+  const items: {
+    color: string
+    dot?: ReactNode
+    children: ReactNode
+  }[] = []
+  const provenance = skill.provenance
+  const evaluation = skill.evaluation
+  const metrics = skill.metrics
+
+  if (provenance?.source_type || provenance?.source_ids?.length) {
+    items.push({
+      color: 'blue',
+      children: (
+        <div>
+          <Text strong>Source imported</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {provenance.source_type || 'unknown source'} {provenance.source_ids?.slice(0, 2).map(id => <Tag key={id}>{id}</Tag>)}
+          </div>
+        </div>
+      ),
+    })
+  }
+
+  items.push({
+    color: 'orange',
+    children: (
+      <div>
+        <Text strong>Candidate created</Text>
+        <div style={{ fontSize: 12, color: '#666' }}>{formatDate(skill.created_at)}</div>
+      </div>
+    ),
+  })
+
+  if (evaluation?.verifier_specs?.length || evaluation?.validation_summary) {
+    items.push({
+      color: 'cyan',
+      dot: <SafetyCertificateOutlined />,
+      children: (
+        <div>
+          <Text strong>Audited / verifier attached</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {evaluation.validation_summary || `${evaluation.verifier_specs.length} verifier spec(s)`}
+          </div>
+        </div>
+      ),
+    })
+  }
+
+  if (['S3', 'S4', 'S5', 'S6', 'S7'].includes(skill.state)) {
+    items.push({
+      color: skill.state === 'S4' ? 'green' : 'blue',
+      children: (
+        <div>
+          <Text strong>{skill.state === 'S4' ? 'Released' : STATE_LABEL[skill.state]}</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>Current state: {STATE_LABEL[skill.state]}</div>
+        </div>
+      ),
+    })
+  }
+
+  if (metrics.total_executions > 0) {
+    items.push({
+      color: 'purple',
+      dot: <PlayCircleOutlined />,
+      children: (
+        <div>
+          <Text strong>Executed</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {metrics.total_executions} runs, {(metrics.success_rate * 100).toFixed(1)}% success
+          </div>
+        </div>
+      ),
+    })
+  }
+
+  if (metrics.failed_executions > 0 || skill.state === 'S5') {
+    items.push({
+      color: 'red',
+      children: (
+        <div>
+          <Text strong>Failed / degraded evidence</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {metrics.failed_executions} failed run(s)
+          </div>
+        </div>
+      ),
+    })
+  } else if (metrics.successful_executions > 0 || evaluation?.validation_summary) {
+    items.push({
+      color: 'green',
+      children: (
+        <div>
+          <Text strong>Validated evidence</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {metrics.successful_executions} successful run(s)
+          </div>
+        </div>
+      ),
+    })
+  }
+
+  if (provenance?.parent_skill_ids?.length || skill.tags.includes('maintenance') || skill.tags.includes('repair')) {
+    items.push({
+      color: 'gold',
+      children: (
+        <div>
+          <Text strong>Repaired / derived</Text>
+          <div style={{ fontSize: 12, color: '#666' }}>
+            {provenance?.parent_skill_ids?.map(id => <Tag key={id}>{id}</Tag>)}
+          </div>
+        </div>
+      ),
+    })
+  }
+
+  items.push({
+    color: 'blue',
+    dot: <HistoryOutlined />,
+    children: (
+      <div>
+        <Text strong>Versioned</Text>
+        <div style={{ fontSize: 12, color: '#666' }}>
+          <Text code>v{skill.version}</Text> updated {formatDate(skill.updated_at)}
+        </div>
+      </div>
+    ),
+  })
+
+  return items
+}
+
+export default function SkillWiki() {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const openedFromQuery = useRef<string | null>(null)
+  const [skills, setSkills] = useState<SkillSummary[]>([])
+  const [loading, setLoading] = useState(true)
+  const [search, setSearch] = useState('')
+  const [stateFilter, setStateFilter] = useState<SkillState | undefined>()
+  const [typeFilter, setTypeFilter] = useState<SkillType | undefined>()
+  const [selected, setSelected] = useState<SkillFull | null>(null)
+  const [drawerOpen, setDrawerOpen] = useState(false)
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    try {
+      const data = await skillsApi.list({ state: stateFilter, skill_type: typeFilter, limit: 200 })
+      setSkills(data)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Failed to load Skills'))
+    } finally {
+      setLoading(false)
+    }
+  }, [stateFilter, typeFilter])
+
+  useEffect(() => {
+    const timeoutId = window.setTimeout(() => { void load() }, 0)
+    return () => window.clearTimeout(timeoutId)
+  }, [load])
+
+  const filtered = skills.filter(skill => {
+    if (!search) return true
+    return (
+      skill.name.includes(search) ||
+      skill.description.includes(search) ||
+      skill.tags.some(tag => tag.includes(search))
+    )
+  })
+
+  const openDetail = async (id: string) => {
+    const full = await skillsApi.getFull(id)
+    setSelected(full)
+    setDrawerOpen(true)
+  }
+
+  useEffect(() => {
+    const id = new URLSearchParams(location.search).get('skill_id')
+    if (!id || openedFromQuery.current === id) return
+    openedFromQuery.current = id
+    openDetail(id).catch(err => message.error(getApiErrorMessage(err, 'Skill does not exist or is temporarily unavailable')))
+  }, [location.search])
+
+  const handleRelease = async (id: string) => {
+    try {
+      await lifecycleApi.release(id)
+      message.success('Released')
+      void load()
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Release failed'))
+    }
+  }
+
+  const handleDeprecate = async (id: string) => {
+    try {
+      await lifecycleApi.deprecate(id, 'Manual deprecation')
+      message.success('Deprecated')
+      void load()
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Deprecation failed'))
+    }
+  }
+
+  const columns: TableColumnsType<SkillSummary> = [
+    {
+      title: 'Name',
+      dataIndex: 'name',
+      render: (name: string, record) => (
+        <Button type="link" onClick={() => openDetail(record.skill_id)} style={{ padding: 0, fontWeight: 600 }}>
+          {name}
+        </Button>
+      ),
+    },
+    {
+      title: 'Type',
+      dataIndex: 'skill_type',
+      render: (type: string) => <Tag color={TYPE_COLOR[type]}>{type.toUpperCase()}</Tag>,
+    },
+    {
+      title: 'State',
+      dataIndex: 'state',
+      render: (state: string) => <Badge color={STATE_COLOR[state] || 'default'} text={STATE_LABEL[state] || state} />,
+    },
+    {
+      title: 'Version',
+      dataIndex: 'version',
+      render: (version: string) => <Text code>{version}</Text>,
+    },
+    {
+      title: 'Tags',
+      dataIndex: 'tags',
+      render: (tags: string[]) => uniqueTags(tags).slice(0, 3).map(tag => <Tag key={tag}>{tag}</Tag>),
+    },
+    {
+      title: 'Success Rate',
+      dataIndex: 'metrics',
+      render: (metrics: SkillSummary['metrics']) => (
+        metrics.total_executions >= 5
+          ? <Progress percent={Math.round(metrics.success_rate * 100)} size="small" style={{ width: 80 }} />
+          : <Text type="secondary">N/A</Text>
+      ),
+    },
+    {
+      title: 'Actions',
+      render: (_, record) => (
+        <Space>
+          <Tooltip title="View details">
+            <Button size="small" icon={<EyeOutlined />} onClick={() => openDetail(record.skill_id)} />
+          </Tooltip>
+          {record.state === 'S2' && (
+            <Tooltip title="Release">
+              <Button size="small" icon={<CheckOutlined />} type="primary" onClick={() => handleRelease(record.skill_id)} />
+            </Tooltip>
+          )}
+          {record.state === 'S4' && (
+            <Tooltip title="Deprecate">
+              <Popconfirm title="Deprecate this Skill?" onConfirm={() => handleDeprecate(record.skill_id)}>
+                <Button size="small" icon={<StopOutlined />} danger />
+              </Popconfirm>
+            </Tooltip>
+          )}
+        </Space>
+      ),
+    },
+  ]
+
+  const selectedTags = uniqueTags(selected?.tags)
+  const selectedInputParams = selected ? getInterfaceParameters(selected, 'input') : []
+  const selectedOutputParams = selected ? getInterfaceParameters(selected, 'output') : []
+  const selectedPreconditions = selected?.interface?.preconditions ?? []
+  const selectedPostconditions = selected?.interface?.postconditions ?? []
+  const selectedSubSkillIds = selected?.implementation?.sub_skill_ids ?? []
+  const selectedEvaluation = selected?.evaluation
+  const selectedProvenance = selected?.provenance
+  const selectedTimeline = selected ? buildSkillTimeline(selected) : []
+
+  return (
+    <div style={{ padding: 24 }}>
+      <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }}>
+        <div style={{ display: 'flex', gap: 12, marginBottom: 16, flexWrap: 'wrap' }}>
+          <Input
+            placeholder="Search Skill name, description, or tags"
+            prefix={<SearchOutlined />}
+            value={search}
+            onChange={event => setSearch(event.target.value)}
+            style={{ width: 280 }}
+            allowClear
+          />
+          <Select
+            placeholder="Filter by state"
+            allowClear
+            style={{ width: 150 }}
+            onChange={value => setStateFilter(value as SkillState)}
+            options={[
+              { label: 'Raw (S0)', value: 'S0' },
+              { label: 'Candidate (S1)', value: 'S1' },
+              { label: 'Draft (S2)', value: 'S2' },
+              { label: 'Verified (S3)', value: 'S3' },
+              { label: 'Released (S4)', value: 'S4' },
+              { label: 'Degraded (S5)', value: 'S5' },
+              { label: 'Deprecated (S6)', value: 'S6' },
+              { label: 'Archived (S7)', value: 'S7' },
+            ]}
+          />
+          <Select
+            placeholder="Filter by type"
+            allowClear
+            style={{ width: 150 }}
+            onChange={value => setTypeFilter(value as SkillType)}
+            options={['atomic', 'functional', 'strategic'].map(type => ({ label: type, value: type }))}
+          />
+          <Button onClick={load}>Refresh</Button>
+        </div>
+
+        <Table
+          dataSource={filtered}
+          columns={columns}
+          rowKey="skill_id"
+          loading={loading}
+          size="middle"
+          pagination={{ pageSize: 15, showSizeChanger: true }}
+          style={{ borderRadius: 8, overflow: 'hidden' }}
+        />
+      </motion.div>
+
+      <Drawer
+        title={selected?.name}
+        open={drawerOpen}
+        onClose={() => setDrawerOpen(false)}
+        size="large"
+        extra={selected && (
+          <Space>
+            <Button size="small" onClick={() => navigate(`/graph?skill_id=${encodeURIComponent(selected.skill_id)}`)}>
+              View Graph
+            </Button>
+            <Tag color={TYPE_COLOR[selected.skill_type]}>{selected.skill_type.toUpperCase()}</Tag>
+            <Badge color={STATE_COLOR[selected.state]} text={STATE_LABEL[selected.state] || selected.state} />
+          </Space>
+        )}
+      >
+        {selected && (
+          <Tabs
+            items={[
+              {
+                key: 'info',
+                label: 'Basic Info',
+                children: (
+                  <Descriptions column={1} bordered size="small">
+                    <Descriptions.Item label="ID"><Text code copyable>{selected.skill_id}</Text></Descriptions.Item>
+                    <Descriptions.Item label="Version"><Text code>{selected.version}</Text></Descriptions.Item>
+                    <Descriptions.Item label="Description"><Paragraph>{selected.description}</Paragraph></Descriptions.Item>
+                    <Descriptions.Item label="Tags">
+                      {selectedTags.length > 0
+                        ? selectedTags.map(tag => <Tag key={tag}>{tag}</Tag>)
+                        : <Text type="secondary">No tags</Text>}
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Granularity">{selected.granularity_level}</Descriptions.Item>
+                    <Descriptions.Item label="Created At">{new Date(selected.created_at).toLocaleString()}</Descriptions.Item>
+                    <Descriptions.Item label="Updated At">{new Date(selected.updated_at).toLocaleString()}</Descriptions.Item>
+                  </Descriptions>
+                ),
+              },
+              {
+                key: 'interface',
+                label: 'Interface',
+                children: selected.interface && (
+                  <div>
+                    <h4>Input Parameters</h4>
+                    {selectedInputParams.length > 0
+                      ? selectedInputParams.map(param => (
+                        <div key={param.name} style={{ marginBottom: 8 }}>
+                          <Text code>{param.name}</Text>
+                          <Tag style={{ marginLeft: 8 }}>{param.type}</Tag>
+                          {param.required && <Tag color="red">Required</Tag>}
+                          <div style={{ color: '#666', fontSize: 12 }}>{param.description}</div>
+                        </div>
+                      ))
+                      : <Text type="secondary">No input parameters</Text>}
+                    <h4 style={{ marginTop: 16 }}>Output Parameters</h4>
+                    {selectedOutputParams.length > 0
+                      ? selectedOutputParams.map(param => (
+                        <div key={param.name} style={{ marginBottom: 8 }}>
+                          <Text code>{param.name}</Text>
+                          <Tag style={{ marginLeft: 8 }}>{param.type}</Tag>
+                          <div style={{ color: '#666', fontSize: 12 }}>{param.description}</div>
+                        </div>
+                      ))
+                      : <Text type="secondary">No output parameters</Text>}
+                    {selectedPreconditions.length > 0 && (
+                      <>
+                        <h4 style={{ marginTop: 16 }}>Preconditions</h4>
+                        {selectedPreconditions.map((condition, index) => <div key={index}>- {condition}</div>)}
+                      </>
+                    )}
+                    {selectedPostconditions.length > 0 && (
+                      <>
+                        <h4 style={{ marginTop: 16 }}>Postconditions</h4>
+                        {selectedPostconditions.map((condition, index) => <div key={index}>- {condition}</div>)}
+                      </>
+                    )}
+                  </div>
+                ),
+              },
+              {
+                key: 'impl',
+                label: 'Implementation',
+                children: selected.implementation && (
+                  <div>
+                    <Tag color="blue">{selected.implementation.language}</Tag>
+                    {selected.implementation.code && (
+                      <pre style={{ background: '#f5f5f5', padding: 12, borderRadius: 8, marginTop: 8, overflow: 'auto', fontSize: 12 }}>
+                        {selected.implementation.code}
+                      </pre>
+                    )}
+                    {selected.implementation.prompt_template && (
+                      <div style={{ background: '#f0f7ff', padding: 12, borderRadius: 8, marginTop: 8 }}>
+                        {selected.implementation.prompt_template}
+                      </div>
+                    )}
+                    {selectedSubSkillIds.length > 0 && (
+                      <div style={{ marginTop: 8 }}>
+                        <strong>Sub-Skills:</strong>
+                        {selectedSubSkillIds.map(id => <Tag key={id}>{id}</Tag>)}
+                      </div>
+                    )}
+                  </div>
+                ),
+              },
+              {
+                key: 'evidence',
+                label: 'Evidence',
+                children: (
+                  <div>
+                    <h4>Provenance</h4>
+                    {selectedProvenance ? (
+                      <Descriptions column={1} bordered size="small">
+                        <Descriptions.Item label="Source type">{selectedProvenance.source_type}</Descriptions.Item>
+                        <Descriptions.Item label="Source IDs">
+                          {selectedProvenance.source_ids.length
+                            ? selectedProvenance.source_ids.map(id => <Tag key={id}>{id}</Tag>)
+                            : <Text type="secondary">None</Text>}
+                        </Descriptions.Item>
+                        <Descriptions.Item label="Parent Skills">
+                          {selectedProvenance.parent_skill_ids.length
+                            ? selectedProvenance.parent_skill_ids.map(id => <Tag key={id}>{id}</Tag>)
+                            : <Text type="secondary">None</Text>}
+                        </Descriptions.Item>
+                        <Descriptions.Item label="Created by">{selectedProvenance.created_by_agent || 'unknown'}</Descriptions.Item>
+                        <Descriptions.Item label="Context">
+                          <pre style={{ background: '#f5f5f5', padding: 12, borderRadius: 8, overflow: 'auto', fontSize: 12 }}>
+                            {JSON.stringify(selectedProvenance.creation_context, null, 2)}
+                          </pre>
+                        </Descriptions.Item>
+                      </Descriptions>
+                    ) : (
+                      <Text type="secondary">No provenance recorded.</Text>
+                    )}
+
+                    <h4 style={{ marginTop: 16 }}>Evaluation</h4>
+                    {selectedEvaluation ? (
+                      <Descriptions column={1} bordered size="small">
+                        <Descriptions.Item label="Verifier specs">
+                          <pre style={{ background: '#f5f5f5', padding: 12, borderRadius: 8, overflow: 'auto', fontSize: 12 }}>
+                            {JSON.stringify(selectedEvaluation.verifier_specs, null, 2)}
+                          </pre>
+                        </Descriptions.Item>
+                        <Descriptions.Item label="Test cases">
+                          {selectedEvaluation.test_case_refs.length
+                            ? selectedEvaluation.test_case_refs.map(id => <Tag key={id}>{id}</Tag>)
+                            : <Text type="secondary">None</Text>}
+                        </Descriptions.Item>
+                        <Descriptions.Item label="Benchmark tasks">
+                          {selectedEvaluation.benchmark_task_ids.length
+                            ? selectedEvaluation.benchmark_task_ids.map(id => <Tag key={id}>{id}</Tag>)
+                            : <Text type="secondary">None</Text>}
+                        </Descriptions.Item>
+                        <Descriptions.Item label="Validation summary">
+                          {selectedEvaluation.validation_summary || <Text type="secondary">None</Text>}
+                        </Descriptions.Item>
+                      </Descriptions>
+                    ) : (
+                      <Text type="secondary">No evaluation contract recorded.</Text>
+                    )}
+                  </div>
+                ),
+              },
+              {
+                key: 'timeline',
+                label: 'Timeline',
+                children: (
+                  <Timeline items={selectedTimeline} />
+                ),
+              },
+              {
+                key: 'metrics',
+                label: 'Metrics',
+                children: (
+                  <Descriptions column={1} bordered size="small">
+                    <Descriptions.Item label="Total Executions">{selected.metrics.total_executions}</Descriptions.Item>
+                    <Descriptions.Item label="Successful Executions">{selected.metrics.successful_executions}</Descriptions.Item>
+                    <Descriptions.Item label="Failed Executions">{selected.metrics.failed_executions}</Descriptions.Item>
+                    <Descriptions.Item label="Success Rate">
+                      <Progress percent={Math.round(selected.metrics.success_rate * 100)} size="small" style={{ width: 120 }} />
+                    </Descriptions.Item>
+                    <Descriptions.Item label="Average Latency">{selected.metrics.avg_latency_ms.toFixed(0)}ms</Descriptions.Item>
+                    <Descriptions.Item label="Usage Count">{selected.metrics.usage_count}</Descriptions.Item>
+                  </Descriptions>
+                ),
+              },
+            ]}
+          />
+        )}
+      </Drawer>
+    </div>
+  )
+}

skillwiki-frontend/src/pages/VersionControl.tsx

@@ -0,0 +1,1117 @@
+import { useCallback, useEffect, useState } from 'react'
+import {
+  Alert,
+  Badge,
+  Button,
+  Card,
+  Col,
+  Collapse,
+  Descriptions,
+  Drawer,
+  Empty,
+  Form,
+  Input,
+  Popconfirm,
+  Row,
+  Select,
+  Space,
+  Table,
+  Tag,
+  Timeline,
+  Typography,
+  message,
+} from 'antd'
+import type { TableColumnsType } from 'antd'
+import {
+  BranchesOutlined,
+  DiffOutlined,
+  HistoryOutlined,
+  PlusOutlined,
+  ReloadOutlined,
+  RocketOutlined,
+  RollbackOutlined,
+  SaveOutlined,
+  TagOutlined,
+} from '@ant-design/icons'
+import { motion } from 'framer-motion'
+import { useLocation } from 'react-router-dom'
+import { lifecycleApi, skillsApi } from '@/api/client'
+import { getApiErrorMessage } from '@/api/errors'
+import type {
+  BusinessDiffEntry,
+  BusinessDiffSummary,
+  NewVersionRequest,
+  SkillReleaseRecord,
+  SkillRollbackRecord,
+  SkillSummary,
+  SnapshotCommitResponse,
+  SnapshotDiffResponse,
+  SnapshotHistoryItem,
+  StructuredDiffEntry,
+} from '@/api/types'
+
+const { Text } = Typography
+
+const STATE_COLOR: Record<string, string> = {
+  S4: 'green',
+  S3: 'cyan',
+  S2: 'blue',
+  S1: 'orange',
+  S5: 'gold',
+  S6: 'red',
+  S7: 'default',
+  S0: 'purple',
+}
+
+const STATE_LABEL: Record<string, string> = {
+  S0: 'Raw',
+  S1: 'Candidate',
+  S2: 'Draft',
+  S3: 'Verified',
+  S4: 'Released',
+  S5: 'Degraded',
+  S6: 'Deprecated',
+  S7: 'Archived',
+}
+
+interface DiffLine {
+  field: string
+  type: 'modified' | 'added' | 'removed'
+  old_value: string
+  new_value: string
+  old_lines: string[]
+  new_lines: string[]
+}
+
+interface DiffData {
+  skill_id: string
+  skill_name?: string
+  current_version?: string
+  business_diff?: BusinessDiffEntry[]
+  business_summary?: BusinessDiffSummary
+  breaking?: boolean
+  suggested_bump?: 'major' | 'minor' | 'patch'
+  history?: {
+    record_id: string
+    from_version?: string
+    to_version: string
+    change_type: string
+    summary: string
+    author: string
+    created_at: string
+    diff: DiffLine[]
+    is_breaking: boolean
+  }[]
+}
+
+interface VersionLabForm {
+  bump: 'major' | 'minor' | 'patch'
+  description?: string
+  tags?: string
+  interface_json?: string
+  implementation_json?: string
+  evaluation_json?: string
+}
+
+function semverCompare(a: string, b: string) {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pb[i] || 0) - (pa[i] || 0)
+  }
+  return 0
+}
+
+function shortRef(ref?: string | null) {
+  if (!ref) return ''
+  return ref.length > 14 ? ref.slice(0, 12) : ref
+}
+
+function dateText(value?: string) {
+  if (!value) return '-'
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString()
+}
+
+function diffField(entry: StructuredDiffEntry) {
+  return String(entry.field_path ?? entry.field ?? 'skill')
+}
+
+function diffChange(entry: StructuredDiffEntry) {
+  return String(entry.change_type ?? entry.type ?? 'modified')
+}
+
+function diffCategory(entry: StructuredDiffEntry) {
+  return String(entry.category ?? 'general')
+}
+
+function isBreakingDiff(entry: StructuredDiffEntry) {
+  return entry.is_breaking === true || diffCategory(entry).toLowerCase().includes('breaking')
+}
+
+function renderValue(value: unknown) {
+  if (value === undefined || value === null || value === '') {
+    return <Text type="secondary">-</Text>
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return <Text>{String(value)}</Text>
+  }
+  return (
+    <pre style={{
+      margin: 0,
+      maxHeight: 120,
+      overflow: 'auto',
+      fontSize: 12,
+      background: '#f6f8fa',
+      borderRadius: 6,
+      padding: 8,
+    }}
+    >
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  )
+}
+
+function DiffView({ lines }: { lines: DiffLine[] }) {
+  if (!lines.length) return <Empty description="No version diff records" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+  return (
+    <div style={{ fontFamily: 'monospace', fontSize: 12 }}>
+      {lines.map((line, i) => (
+        <div key={`${line.field}-${i}`} style={{ marginBottom: 12 }}>
+          <div style={{ fontWeight: 600, color: '#1677ff', marginBottom: 4 }}>
+            {line.field}
+            <Tag color={line.type === 'removed' ? 'red' : line.type === 'added' ? 'green' : 'orange'} style={{ marginLeft: 8 }}>
+              {line.type}
+            </Tag>
+          </div>
+          <div style={{ display: 'flex', gap: 8 }}>
+            {line.old_lines.length > 0 && (
+              <div style={{ flex: 1, background: '#fff1f0', borderRadius: 4, padding: '4px 8px', border: '1px solid #ffccc7' }}>
+                {line.old_lines.map((item, index) => (
+                  <div key={`${line.field}-old-${index}`} style={{ color: '#cf1322' }}>- {item}</div>
+                ))}
+              </div>
+            )}
+            {line.new_lines.length > 0 && (
+              <div style={{ flex: 1, background: '#f6ffed', borderRadius: 4, padding: '4px 8px', border: '1px solid #b7eb8f' }}>
+                {line.new_lines.map((item, index) => (
+                  <div key={`${line.field}-new-${index}`} style={{ color: '#389e0d' }}>+ {item}</div>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function StructuredDiffTable({ diff }: { diff: SnapshotDiffResponse }) {
+  const columns: TableColumnsType<StructuredDiffEntry> = [
+    {
+      title: 'Field',
+      render: (_, record) => <Text code>{diffField(record)}</Text>,
+    },
+    {
+      title: 'Change',
+      render: (_, record) => (
+        <Space>
+          <Tag color={diffChange(record) === 'removed' ? 'red' : diffChange(record) === 'added' ? 'green' : 'blue'}>
+            {diffChange(record)}
+          </Tag>
+          <Tag>{diffCategory(record)}</Tag>
+          {isBreakingDiff(record) && <Tag color="red">BREAKING</Tag>}
+        </Space>
+      ),
+    },
+    {
+      title: 'Before',
+      dataIndex: 'old_value',
+      render: renderValue,
+    },
+    {
+      title: 'After',
+      dataIndex: 'new_value',
+      render: renderValue,
+    },
+  ]
+
+  return (
+    <Table
+      dataSource={diff.diffs}
+      columns={columns}
+      rowKey={(_, index) => `${diff.from_ref}-${diff.to_ref}-${index}`}
+      pagination={false}
+      size="small"
+      locale={{ emptyText: 'No structured field changes' }}
+    />
+  )
+}
+
+function jsonText(value: unknown) {
+  return JSON.stringify(value ?? {}, null, 2)
+}
+
+function parseJsonField(value: string | undefined, label: string) {
+  const text = (value ?? '').trim()
+  if (!text) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${label} must be valid JSON`)
+  }
+}
+
+function tagList(value?: string) {
+  return (value ?? '')
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean)
+}
+
+function businessDiffColor(row: BusinessDiffEntry) {
+  if (row.is_breaking) return 'red'
+  if (row.category === 'interface') return 'orange'
+  if (row.category === 'implementation') return 'blue'
+  return 'default'
+}
+
+function BusinessDiffView({ diff, summary }: { diff: BusinessDiffEntry[]; summary?: BusinessDiffSummary }) {
+  if (!diff.length) return <Empty description="No business-level changes" image={Empty.PRESENTED_IMAGE_SIMPLE} />
+  return (
+    <Space direction="vertical" size={12} style={{ width: '100%' }}>
+      {summary && (
+        <Alert
+          type={summary.breaking ? 'warning' : 'info'}
+          showIcon
+          message={summary.summary}
+          description={`Suggested bump: ${summary.suggested_bump}. Categories: ${summary.categories.join(', ') || 'none'}.`}
+        />
+      )}
+      <Table
+        size="small"
+        pagination={false}
+        rowKey={(record, index) => `${record.field}-${index}`}
+        dataSource={diff}
+        columns={[
+          {
+            title: 'Field',
+            render: (_, record) => <Text code>{record.field}</Text>,
+          },
+          {
+            title: 'Change',
+            render: (_, record) => (
+              <Space wrap>
+                <Tag color={businessDiffColor(record)}>{record.change_type}</Tag>
+                <Tag>{record.category}</Tag>
+                {record.is_breaking && <Tag color="red">BREAKING</Tag>}
+              </Space>
+            ),
+          },
+          {
+            title: 'Before',
+            render: (_, record) => renderValue(record.old_value),
+          },
+          {
+            title: 'After',
+            render: (_, record) => renderValue(record.new_value),
+          },
+        ]}
+      />
+    </Space>
+  )
+}
+
+export default function VersionControl() {
+  const location = useLocation()
+  const [form] = Form.useForm<VersionLabForm>()
+  const [skills, setSkills] = useState<SkillSummary[]>([])
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  const [selectedFull, setSelectedFull] = useState<import('@/api/types').SkillFull | null>(null)
+  const [versions, setVersions] = useState<SkillSummary[]>([])
+  const [loadingVersions, setLoadingVersions] = useState(false)
+  const [bumpLoading, setBumpLoading] = useState(false)
+  const [drawerSkill, setDrawerSkill] = useState<SkillSummary | null>(null)
+  const [diffData, setDiffData] = useState<DiffData | null>(null)
+  const [loadingDiff, setLoadingDiff] = useState(false)
+  const [snapshotPath, setSnapshotPath] = useState('')
+  const [snapshotHistory, setSnapshotHistory] = useState<SnapshotHistoryItem[]>([])
+  const [historyLoading, setHistoryLoading] = useState(false)
+  const [snapshotLoading, setSnapshotLoading] = useState(false)
+  const [snapshotDiffLoading, setSnapshotDiffLoading] = useState(false)
+  const [releaseTagLoading, setReleaseTagLoading] = useState(false)
+  const [restoreLoading, setRestoreLoading] = useState(false)
+  const [sourceRef, setSourceRef] = useState('')
+  const [snapshotDiff, setSnapshotDiff] = useState<SnapshotDiffResponse | null>(null)
+  const [lastSnapshot, setLastSnapshot] = useState<SnapshotCommitResponse | null>(null)
+  const [lastRelease, setLastRelease] = useState<SkillReleaseRecord | null>(null)
+  const [lastRestore, setLastRestore] = useState<SkillRollbackRecord | null>(null)
+
+  useEffect(() => {
+    skillsApi.list({ limit: 200 }).then(setSkills).catch(err => {
+      message.error(getApiErrorMessage(err, 'Load Skills failed'))
+    })
+  }, [])
+
+  const loadVersions = useCallback(async (id: string) => {
+    setLoadingVersions(true)
+    try {
+      const nextVersions = await skillsApi.versions(id)
+      setVersions(nextVersions.sort((a, b) => semverCompare(a.version, b.version)))
+    } finally {
+      setLoadingVersions(false)
+    }
+  }, [])
+
+  const loadDiff = useCallback(async (id: string) => {
+    setLoadingDiff(true)
+    try {
+      const data = await lifecycleApi.getDiff(id)
+      setDiffData(data as unknown as DiffData)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Load version diff failed'))
+    } finally {
+      setLoadingDiff(false)
+    }
+  }, [])
+
+  const loadSelectedFull = useCallback(async (id: string) => {
+    try {
+      const full = await skillsApi.getFull(id)
+      setSelectedFull(full)
+      form.setFieldsValue({
+        bump: 'patch',
+        description: full.description,
+        tags: full.tags.join(', '),
+        interface_json: jsonText(full.interface),
+        implementation_json: jsonText(full.implementation ?? { language: 'python', prompt_template: '' }),
+        evaluation_json: jsonText(full.evaluation),
+      })
+    } catch (err) {
+      setSelectedFull(null)
+      message.warning(getApiErrorMessage(err, 'Load editable Skill details failed'))
+    }
+  }, [form])
+
+  const loadSnapshotHistory = useCallback(async (id: string, options: { silent?: boolean } = {}) => {
+    setHistoryLoading(true)
+    try {
+      const data = await lifecycleApi.snapshotHistory(id)
+      setSnapshotPath(data.snapshot_path)
+      setSnapshotHistory(data.history)
+      setSourceRef(prev => prev || data.history[0]?.commit_hash || '')
+    } catch (err) {
+      setSnapshotPath('')
+      setSnapshotHistory([])
+      if (!options.silent) {
+        message.warning(getApiErrorMessage(err, 'Snapshot history is not available yet'))
+      }
+    } finally {
+      setHistoryLoading(false)
+    }
+  }, [])
+
+  const handleSelect = useCallback((id: string, options: { loadCurrentDiff?: boolean } = {}) => {
+    setSelectedId(id)
+    setDiffData(null)
+    setSnapshotDiff(null)
+    setLastSnapshot(null)
+    setLastRelease(null)
+    setLastRestore(null)
+    setSourceRef('')
+    void loadVersions(id)
+    void loadSelectedFull(id)
+    void loadSnapshotHistory(id, { silent: true })
+    if (options.loadCurrentDiff) {
+      void loadDiff(id)
+    }
+  }, [loadDiff, loadSelectedFull, loadSnapshotHistory, loadVersions])
+
+  useEffect(() => {
+    const timer = window.setTimeout(() => {
+      const query = new URLSearchParams(location.search)
+      const querySkillId = query.get('skill_id')
+      if (!querySkillId || selectedId === querySkillId) return
+      if (skills.length > 0 && skills.some(skill => skill.skill_id === querySkillId)) {
+        handleSelect(querySkillId, { loadCurrentDiff: Boolean(query.get('proposal_id')) })
+      }
+    }, 0)
+    return () => window.clearTimeout(timer)
+  }, [handleSelect, location.search, selectedId, skills])
+
+  const handleBump = async (bump: 'major' | 'minor' | 'patch') => {
+    if (!selectedId) return
+    setBumpLoading(true)
+    try {
+      const newSkill = await lifecycleApi.newVersion(selectedId, bump)
+      message.success(`Created version v${newSkill.version}`)
+      const allSkills = await skillsApi.list({ limit: 200 })
+      setSkills(allSkills)
+      void loadVersions(selectedId)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Create version failed'))
+    } finally {
+      setBumpLoading(false)
+    }
+  }
+
+  const handleEditableVersion = async (values: VersionLabForm) => {
+    if (!selectedId || !selectedFull) return
+    setBumpLoading(true)
+    try {
+      const nextInterface = parseJsonField(values.interface_json, 'Interface')
+      const nextImplementation = parseJsonField(values.implementation_json, 'Implementation')
+      const nextEvaluation = parseJsonField(values.evaluation_json, 'Evaluation')
+      const request: NewVersionRequest = {
+        bump: values.bump,
+        description: values.description,
+        tags: tagList(values.tags),
+        interface: nextInterface,
+        implementation: nextImplementation,
+        evaluation: nextEvaluation,
+        author: 'version_lab',
+      }
+      const newSkill = await lifecycleApi.newVersion(selectedId, request)
+      message.success(`Created draft version v${newSkill.version}`)
+      const allSkills = await skillsApi.list({ limit: 200 })
+      setSkills(allSkills)
+      setSelectedId(newSkill.skill_id)
+      await loadVersions(newSkill.skill_id)
+      await loadSelectedFull(newSkill.skill_id)
+      await loadDiff(newSkill.skill_id)
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : getApiErrorMessage(err, 'Create editable version failed'))
+    } finally {
+      setBumpLoading(false)
+    }
+  }
+
+  const handleRelease = async (id: string) => {
+    try {
+      await lifecycleApi.release(id)
+      message.success('Released')
+      if (selectedId) void loadVersions(selectedId)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Release failed'))
+    }
+  }
+
+  const handleCreateSnapshot = async () => {
+    if (!selectedId) return
+    setSnapshotLoading(true)
+    try {
+      const snapshot = await lifecycleApi.createSnapshot(selectedId, { author: 'human_reviewer' })
+      setLastSnapshot(snapshot)
+      setSourceRef(snapshot.commit)
+      message.success(`Snapshot commit ${shortRef(snapshot.commit)} created`)
+      await loadSnapshotHistory(selectedId, { silent: true })
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Create snapshot commit failed'))
+    } finally {
+      setSnapshotLoading(false)
+    }
+  }
+
+  const handleSnapshotDiff = async (ref = sourceRef) => {
+    if (!selectedId || !ref.trim()) {
+      message.warning('Select or enter a base commit/tag first')
+      return
+    }
+    setSnapshotDiffLoading(true)
+    try {
+      const data = await lifecycleApi.snapshotDiff(selectedId, {
+        from_ref: ref.trim(),
+        to_ref: 'HEAD',
+      })
+      setSnapshotDiff(data)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Load snapshot structured diff failed'))
+    } finally {
+      setSnapshotDiffLoading(false)
+    }
+  }
+
+  const handleReleaseTag = async (ref = sourceRef || 'HEAD') => {
+    if (!selectedId) return
+    setReleaseTagLoading(true)
+    try {
+      const release = await lifecycleApi.releaseTag(selectedId, ref.trim() || 'HEAD')
+      setLastRelease(release)
+      message.success(`Release tag ${release.tag_name} created`)
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Create release tag failed'))
+    } finally {
+      setReleaseTagLoading(false)
+    }
+  }
+
+  const handleRestoreCommit = async (ref = sourceRef) => {
+    if (!selectedId || !ref.trim()) {
+      message.warning('Select or enter a source commit/tag first')
+      return
+    }
+    setRestoreLoading(true)
+    try {
+      const restore = await lifecycleApi.restoreSnapshot(selectedId, ref.trim())
+      setLastRestore(restore)
+      message.success(`Restore commit ${shortRef(restore.restore_commit)} created`)
+      await loadSnapshotHistory(selectedId, { silent: true })
+    } catch (err) {
+      message.error(getApiErrorMessage(err, 'Create restore commit failed'))
+    } finally {
+      setRestoreLoading(false)
+    }
+  }
+
+  const selectedSkill = selectedId ? skills.find(skill => skill.skill_id === selectedId) : null
+  const currentDiffHistory = diffData?.history ?? []
+  const currentBusinessDiff = diffData?.business_diff ?? []
+  const queryProposalId = new URLSearchParams(location.search).get('proposal_id')
+
+  const versionColumns: TableColumnsType<SkillSummary> = [
+    {
+      title: 'Version',
+      dataIndex: 'version',
+      render: (version: string, record) => (
+        <Space>
+          <TagOutlined style={{ color: '#1677ff' }} />
+          <Text code style={{ cursor: 'pointer' }} onClick={() => setDrawerSkill(record)}>v{version}</Text>
+          {record.skill_id === selectedId && <Tag color="blue">HEAD</Tag>}
+        </Space>
+      ),
+    },
+    {
+      title: 'State',
+      dataIndex: 'state',
+      render: (state: string) => <Badge color={STATE_COLOR[state] || 'default'} text={STATE_LABEL[state] || state} />,
+    },
+    {
+      title: 'Created',
+      dataIndex: 'created_at',
+      render: dateText,
+    },
+    {
+      title: 'Success Rate',
+      dataIndex: 'metrics',
+      render: (metrics: SkillSummary['metrics']) =>
+        metrics.total_executions >= 5
+          ? `${(metrics.success_rate * 100).toFixed(1)}%`
+          : <Text type="secondary">N/A</Text>,
+    },
+    {
+      title: 'Actions',
+      render: (_, record) => (
+        <Space>
+          {(record.state === 'S2' || record.state === 'S3') && (
+            <Popconfirm title="Release this version?" onConfirm={() => handleRelease(record.skill_id)}>
+              <Button size="small" type="primary" icon={<RocketOutlined />}>Release</Button>
+            </Popconfirm>
+          )}
+        </Space>
+      ),
+    },
+  ]
+
+  const snapshotColumns: TableColumnsType<SnapshotHistoryItem> = [
+    {
+      title: 'Commit',
+      dataIndex: 'commit_hash',
+      render: (commit: string) => <Text code copyable={{ text: commit }}>{shortRef(commit)}</Text>,
+    },
+    {
+      title: 'Subject',
+      dataIndex: 'subject',
+      render: (subject: string) => <Text>{subject}</Text>,
+    },
+    {
+      title: 'Author',
+      dataIndex: 'author',
+      width: 140,
+    },
+    {
+      title: 'Time',
+      dataIndex: 'authored_at',
+      render: dateText,
+      width: 180,
+    },
+    {
+      title: 'Paths',
+      dataIndex: 'changed_paths',
+      render: (paths: string[]) => (
+        <Space wrap>
+          {paths.slice(0, 2).map(path => <Tag key={path}>{path}</Tag>)}
+          {paths.length > 2 && <Tag>+{paths.length - 2}</Tag>}
+        </Space>
+      ),
+    },
+    {
+      title: 'Actions',
+      render: (_, record) => (
+        <Space>
+          <Button size="small" icon={<DiffOutlined />} onClick={() => { setSourceRef(record.commit_hash); void handleSnapshotDiff(record.commit_hash) }}>
+            Diff
+          </Button>
+          <Button size="small" icon={<TagOutlined />} loading={releaseTagLoading} onClick={() => handleReleaseTag(record.commit_hash)}>
+            Tag
+          </Button>
+          <Popconfirm
+            title="Create a restore commit from this snapshot?"
+            description="This writes a new restore commit; it does not reset Git history."
+            onConfirm={() => handleRestoreCommit(record.commit_hash)}
+          >
+            <Button size="small" danger icon={<RollbackOutlined />} loading={restoreLoading}>
+              Restore commit
+            </Button>
+          </Popconfirm>
+        </Space>
+      ),
+    },
+  ]
+
+  return (
+    <div style={{ padding: 24 }}>
+      <motion.div initial={{ opacity: 0, y: -10 }} animate={{ opacity: 1, y: 0 }}>
+        <h2 style={{ fontWeight: 700, marginBottom: 4 }}>Version Governance</h2>
+        <p style={{ color: '#666', marginBottom: 24 }}>
+          Review Skill versions, Git snapshots, structured diffs, release tags, and restore commits.
+        </p>
+      </motion.div>
+
+      {queryProposalId && (
+        <Alert
+          type="info"
+          showIcon
+          style={{ marginBottom: 16 }}
+          message="Accepted maintenance proposal"
+          description={(
+            <Space direction="vertical" size={2}>
+              <Text>
+                Proposal <Text code>{queryProposalId.slice(0, 8)}</Text> is ready for B-side review.
+              </Text>
+              <Text type="secondary">
+                Submit a patched Skill through the maintenance review endpoint before creating any live Skill change.
+              </Text>
+            </Space>
+          )}
+        />
+      )}
+
+      <Row gutter={[16, 16]}>
+        <Col xs={24} lg={16}>
+          <Card
+            title={<span><BranchesOutlined /> Version history</span>}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+            extra={selectedId && (
+              <Space wrap>
+                <Button size="small" icon={<DiffOutlined />} loading={loadingDiff} onClick={() => loadDiff(selectedId)}>
+                  Legacy diff
+                </Button>
+                {(['patch', 'minor', 'major'] as const).map(bump => (
+                  <Button
+                    key={bump}
+                    size="small"
+                    icon={<PlusOutlined />}
+                    loading={bumpLoading}
+                    onClick={() => handleBump(bump)}
+                  >
+                    {bump}
+                  </Button>
+                ))}
+              </Space>
+            )}
+          >
+            <div style={{ marginBottom: 16 }}>
+              <Select
+                value={selectedId ?? undefined}
+                placeholder="Select a Skill"
+                style={{ width: '100%' }}
+                onChange={value => handleSelect(value)}
+                showSearch
+                filterOption={(input, option) =>
+                  String(option?.label ?? '').toLowerCase().includes(input.toLowerCase())
+                }
+                options={[...new Map(skills.map(skill => [skill.name, skill])).values()].map(skill => ({
+                  label: `${skill.name} (${STATE_LABEL[skill.state] || skill.state})`,
+                  value: skill.skill_id,
+                }))}
+              />
+            </div>
+
+            <Table
+              dataSource={versions}
+              columns={versionColumns}
+              rowKey="skill_id"
+              loading={loadingVersions}
+              size="small"
+              pagination={false}
+              locale={{ emptyText: selectedId ? 'No version records' : 'Select a Skill first' }}
+            />
+          </Card>
+
+          <Card
+            title={<span><PlusOutlined /> Version Lab</span>}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginTop: 16 }}
+          >
+            {!selectedId || !selectedFull ? (
+              <Empty description="Select a Skill to create an editable draft version" />
+            ) : (
+              <Form
+                form={form}
+                layout="vertical"
+                initialValues={{ bump: 'patch' }}
+                onFinish={handleEditableVersion}
+              >
+                <Alert
+                  type="info"
+                  showIcon
+                  style={{ marginBottom: 16 }}
+                  message="Editable versions are created as Drafts"
+                  description="Changing the interface or implementation creates a new S2 draft version that should be sent through harness verification before release."
+                />
+                <Row gutter={12}>
+                  <Col xs={24} md={8}>
+                    <Form.Item name="bump" label="Version bump">
+                      <Select
+                        options={[
+                          { label: 'patch', value: 'patch' },
+                          { label: 'minor', value: 'minor' },
+                          { label: 'major', value: 'major' },
+                        ]}
+                      />
+                    </Form.Item>
+                  </Col>
+                  <Col xs={24} md={16}>
+                    <Form.Item name="tags" label="Tags">
+                      <Input placeholder="comma-separated tags" />
+                    </Form.Item>
+                  </Col>
+                </Row>
+                <Form.Item name="description" label="Description">
+                  <Input.TextArea rows={2} />
+                </Form.Item>
+                <Collapse
+                  items={[
+                    {
+                      key: 'interface',
+                      label: 'Interface JSON',
+                      children: (
+                        <Form.Item name="interface_json" noStyle>
+                          <Input.TextArea rows={10} style={{ fontFamily: 'monospace', fontSize: 12 }} />
+                        </Form.Item>
+                      ),
+                    },
+                    {
+                      key: 'implementation',
+                      label: 'Implementation JSON',
+                      children: (
+                        <Form.Item name="implementation_json" noStyle>
+                          <Input.TextArea rows={8} style={{ fontFamily: 'monospace', fontSize: 12 }} />
+                        </Form.Item>
+                      ),
+                    },
+                    {
+                      key: 'evaluation',
+                      label: 'Evaluation JSON',
+                      children: (
+                        <Form.Item name="evaluation_json" noStyle>
+                          <Input.TextArea rows={8} style={{ fontFamily: 'monospace', fontSize: 12 }} />
+                        </Form.Item>
+                      ),
+                    },
+                  ]}
+                />
+                <Space wrap style={{ marginTop: 16 }}>
+                  <Button type="primary" htmlType="submit" icon={<PlusOutlined />} loading={bumpLoading}>
+                    Create draft version
+                  </Button>
+                  <Button icon={<ReloadOutlined />} onClick={() => loadSelectedFull(selectedId)}>
+                    Reset editor
+                  </Button>
+                </Space>
+              </Form>
+            )}
+          </Card>
+
+          <Card
+            title={<span><SaveOutlined /> Git-backed governance snapshots</span>}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginTop: 16 }}
+            extra={selectedId && (
+              <Space wrap>
+                <Button icon={<SaveOutlined />} loading={snapshotLoading} onClick={handleCreateSnapshot}>
+                  Create snapshot
+                </Button>
+                <Button icon={<ReloadOutlined />} loading={historyLoading} onClick={() => loadSnapshotHistory(selectedId)}>
+                  Refresh history
+                </Button>
+              </Space>
+            )}
+          >
+            {!selectedId ? (
+              <Empty description="Select a Skill to manage snapshots" />
+            ) : (
+              <Space direction="vertical" size={12} style={{ width: '100%' }}>
+                {snapshotPath && (
+                  <Text type="secondary">Snapshot path: <Text code>{snapshotPath}</Text></Text>
+                )}
+                {lastSnapshot && (
+                  <Alert
+                    type="success"
+                    showIcon
+                    message="Snapshot commit created"
+                    description={<Text code copyable={{ text: lastSnapshot.commit }}>{shortRef(lastSnapshot.commit)}</Text>}
+                  />
+                )}
+                {lastRelease && (
+                  <Alert
+                    type="success"
+                    showIcon
+                    message="Release tag created"
+                    description={<Text code copyable={{ text: lastRelease.tag_name }}>{lastRelease.tag_name}</Text>}
+                  />
+                )}
+                {lastRestore && (
+                  <Alert
+                    type="warning"
+                    showIcon
+                    message="Restore commit created"
+                    description={(
+                      <Space direction="vertical" size={2}>
+                        <Text code copyable={{ text: lastRestore.restore_commit }}>{shortRef(lastRestore.restore_commit)}</Text>
+                        <Text type="secondary">{lastRestore.commit_message}</Text>
+                      </Space>
+                    )}
+                  />
+                )}
+
+                <Space.Compact style={{ width: '100%' }}>
+                  <Input
+                    value={sourceRef}
+                    onChange={event => setSourceRef(event.target.value)}
+                    placeholder="Base commit, release tag, or source ref"
+                  />
+                  <Button icon={<DiffOutlined />} loading={snapshotDiffLoading} onClick={() => handleSnapshotDiff()}>
+                    Structured diff
+                  </Button>
+                  <Button icon={<TagOutlined />} loading={releaseTagLoading} onClick={() => handleReleaseTag()}>
+                    Release tag
+                  </Button>
+                  <Popconfirm
+                    title="Create restore commit from this ref?"
+                    description="This creates a new commit from the selected snapshot; it does not reset history."
+                    onConfirm={() => handleRestoreCommit()}
+                  >
+                    <Button danger icon={<RollbackOutlined />} loading={restoreLoading}>
+                      Restore commit
+                    </Button>
+                  </Popconfirm>
+                </Space.Compact>
+
+                <Table
+                  dataSource={snapshotHistory}
+                  columns={snapshotColumns}
+                  rowKey="commit_hash"
+                  loading={historyLoading}
+                  size="small"
+                  pagination={{ pageSize: 5 }}
+                  locale={{ emptyText: 'No snapshot commits yet' }}
+                />
+
+                {snapshotDiff && (
+                  <Card
+                    size="small"
+                    title={(
+                      <Space>
+                        <Text code>{`${shortRef(snapshotDiff.from_ref)} -> ${shortRef(snapshotDiff.to_ref)}`}</Text>
+                        <Tag color={snapshotDiff.has_breaking_changes ? 'red' : 'green'}>
+                          {snapshotDiff.has_breaking_changes ? 'BREAKING' : 'compatible'}
+                        </Tag>
+                      </Space>
+                    )}
+                    variant="borderless"
+                    style={{ background: '#fafafa' }}
+                  >
+                    <Alert
+                      type={snapshotDiff.has_breaking_changes ? 'warning' : 'info'}
+                      showIcon
+                      style={{ marginBottom: 12 }}
+                      message={snapshotDiff.review_recommendation}
+                    />
+                    <StructuredDiffTable diff={snapshotDiff} />
+                    {snapshotDiff.raw_diff && (
+                      <Collapse
+                        style={{ marginTop: 12 }}
+                        items={[{
+                          key: 'raw',
+                          label: 'Raw Git diff',
+                          children: (
+                            <pre style={{
+                              margin: 0,
+                              maxHeight: 260,
+                              overflow: 'auto',
+                              fontSize: 12,
+                              background: '#111827',
+                              color: '#f9fafb',
+                              borderRadius: 6,
+                              padding: 12,
+                            }}
+                            >
+                              {snapshotDiff.raw_diff}
+                            </pre>
+                          ),
+                        }]}
+                      />
+                    )}
+                  </Card>
+                )}
+              </Space>
+            )}
+          </Card>
+
+          {diffData && (
+            <Card
+              title={<span><DiffOutlined /> Version change history - {diffData.skill_name ?? selectedSkill?.name ?? 'Skill'}</span>}
+              variant="borderless"
+              style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginTop: 16 }}
+            >
+              {currentBusinessDiff.length > 0 && (
+                <div style={{ marginBottom: 16 }}>
+                  <BusinessDiffView diff={currentBusinessDiff} summary={diffData.business_summary} />
+                </div>
+              )}
+              {currentDiffHistory.length === 0 ? (
+                <Empty description="No version change records" />
+              ) : (
+                <Collapse
+                  items={currentDiffHistory.map(item => ({
+                    key: item.record_id,
+                    label: (
+                      <Space wrap>
+                        <Text code>{`${item.from_version ?? 'previous'} -> ${item.to_version}`}</Text>
+                        <Tag color={item.is_breaking ? 'red' : 'blue'}>{item.change_type}</Tag>
+                        {item.is_breaking && <Tag color="red">BREAKING</Tag>}
+                        <Text type="secondary" style={{ fontSize: 11 }}>{item.summary}</Text>
+                      </Space>
+                    ),
+                    children: (
+                      <div>
+                        <div style={{ marginBottom: 8, color: '#666', fontSize: 12 }}>
+                          {item.author} - {dateText(item.created_at)}
+                        </div>
+                        <DiffView lines={item.diff} />
+                      </div>
+                    ),
+                  }))}
+                />
+              )}
+            </Card>
+          )}
+        </Col>
+
+        <Col xs={24} lg={8}>
+          <Card
+            title={<span><HistoryOutlined /> Timeline</span>}
+            variant="borderless"
+            style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)' }}
+          >
+            {versions.length > 0 || snapshotHistory.length > 0 ? (
+              <Timeline
+                items={[
+                  ...snapshotHistory.slice(0, 8).map(item => ({
+                    color: 'blue',
+                    children: (
+                      <div>
+                        <div><Text code>{shortRef(item.commit_hash)}</Text> snapshot</div>
+                        <div style={{ fontSize: 11, color: '#999' }}>{dateText(item.authored_at)}</div>
+                        <div style={{ fontSize: 11, color: '#666' }}>{item.subject}</div>
+                      </div>
+                    ),
+                  })),
+                  ...versions.slice(0, 8).map(version => ({
+                    color: STATE_COLOR[version.state] || 'blue',
+                    children: (
+                      <div>
+                        <div>
+                          <Text code>v{version.version}</Text>
+                          <Badge
+                            color={STATE_COLOR[version.state] || 'default'}
+                            text={STATE_LABEL[version.state] || version.state}
+                            style={{ marginLeft: 8 }}
+                          />
+                        </div>
+                        <div style={{ fontSize: 11, color: '#999' }}>{dateText(version.created_at)}</div>
+                        {version.metrics.total_executions > 0 && (
+                          <div style={{ fontSize: 11, color: '#666' }}>
+                            {version.metrics.total_executions} executions, {(version.metrics.success_rate * 100).toFixed(0)}% success
+                          </div>
+                        )}
+                      </div>
+                    ),
+                  })),
+                ]}
+              />
+            ) : (
+              <div style={{ textAlign: 'center', color: '#999', padding: 40 }}>
+                <BranchesOutlined style={{ fontSize: 32, marginBottom: 8 }} />
+                <div>Select a Skill to view timeline</div>
+              </div>
+            )}
+          </Card>
+
+          {selectedSkill && (
+            <Card
+              title="Current version"
+              variant="borderless"
+              style={{ borderRadius: 8, boxShadow: '0 2px 8px rgba(0,0,0,0.08)', marginTop: 16 }}
+            >
+              <Descriptions column={1} size="small">
+                <Descriptions.Item label="Name">{selectedSkill.name}</Descriptions.Item>
+                <Descriptions.Item label="Version"><Text code>v{selectedSkill.version}</Text></Descriptions.Item>
+                <Descriptions.Item label="State">
+                  <Badge color={STATE_COLOR[selectedSkill.state]} text={STATE_LABEL[selectedSkill.state]} />
+                </Descriptions.Item>
+                <Descriptions.Item label="Type">
+                  <Tag>{selectedSkill.skill_type}</Tag>
+                </Descriptions.Item>
+                <Descriptions.Item label="Executions">{selectedSkill.metrics.total_executions}</Descriptions.Item>
+              </Descriptions>
+            </Card>
+          )}
+        </Col>
+      </Row>
+
+      <Drawer
+        title={drawerSkill ? `v${drawerSkill.version} details` : ''}
+        open={!!drawerSkill}
+        onClose={() => setDrawerSkill(null)}
+        size="default"
+      >
+        {drawerSkill && (
+          <Descriptions column={1} bordered size="small">
+            <Descriptions.Item label="Skill ID">
+              <Text code copyable style={{ fontSize: 11 }}>{drawerSkill.skill_id}</Text>
+            </Descriptions.Item>
+            <Descriptions.Item label="Version"><Text code>v{drawerSkill.version}</Text></Descriptions.Item>
+            <Descriptions.Item label="State">
+              <Badge color={STATE_COLOR[drawerSkill.state]} text={STATE_LABEL[drawerSkill.state]} />
+            </Descriptions.Item>
+            <Descriptions.Item label="Description">{drawerSkill.description}</Descriptions.Item>
+            <Descriptions.Item label="Tags">
+              {drawerSkill.tags.map(tag => <Tag key={tag}>{tag}</Tag>)}
+            </Descriptions.Item>
+            <Descriptions.Item label="Created">{dateText(drawerSkill.created_at)}</Descriptions.Item>
+            <Descriptions.Item label="Updated">{dateText(drawerSkill.updated_at)}</Descriptions.Item>
+            <Descriptions.Item label="Executions">{drawerSkill.metrics.total_executions}</Descriptions.Item>
+            <Descriptions.Item label="Success rate">
+              {drawerSkill.metrics.total_executions >= 5
+                ? `${(drawerSkill.metrics.success_rate * 100).toFixed(1)}%`
+                : 'N/A'}
+            </Descriptions.Item>
+          </Descriptions>
+        )}
+      </Drawer>
+    </div>
+  )
+}

skillwiki-frontend/src/store/appStore.ts

@@ -0,0 +1,64 @@
+import { create } from 'zustand'
+import type { SkillSummary, SystemHealth } from '@/api/types'
+
+export type AppLang = 'en' | 'zh'
+
+export interface WsEvent {
+  type: string
+  payload: unknown
+  timestamp: string
+}
+
+interface AppStore {
+  // Theme
+  darkMode: boolean
+  toggleDark: () => void
+
+  // Language
+  lang: AppLang
+  setLang: (lang: AppLang) => void
+
+  // Skill list cache
+  skills: SkillSummary[]
+  setSkills: (skills: SkillSummary[]) => void
+
+  // System health
+  health: SystemHealth | null
+  setHealth: (h: SystemHealth) => void
+
+  // WebSocket event log
+  wsEvents: WsEvent[]
+  pushWsEvent: (event: WsEvent) => void
+  clearWsEvents: () => void
+
+  // Selected Skill
+  selectedSkillId: string | null
+  setSelectedSkillId: (id: string | null) => void
+}
+
+export const useAppStore = create<AppStore>((set) => ({
+  darkMode: false,
+  toggleDark: () => set(s => ({ darkMode: !s.darkMode })),
+
+  lang: 'en',
+  setLang: (lang) => set({ lang }),
+
+  skills: [],
+  setSkills: (skills) => set({ skills }),
+
+  health: null,
+  setHealth: (health) => set({ health }),
+
+  wsEvents: [],
+  pushWsEvent: (event) =>
+    set(s => ({
+      wsEvents: [
+        event,
+        ...s.wsEvents.slice(0, 99),
+      ],
+    })),
+  clearWsEvents: () => set({ wsEvents: [] }),
+
+  selectedSkillId: null,
+  setSelectedSkillId: (id) => set({ selectedSkillId: id }),
+}))

skillwiki-frontend/src/types/antv-g6.d.ts

@@ -0,0 +1 @@
+declare module '@antv/g6'