eduevidence 5.2.0 → 6.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to EduEvidence
+
+EduEvidence 是一个**证据驱动的决策引擎**：它的产出要能被第三方复核。因此本仓库的贡献规则有一条主线——**契约先行**。每个科学概念都在多处声明（协议、能力、角色、简报、子技能、分包），任何一处漂移都会让结论失去可追溯性。
+
+## 1. 环境准备
+
+```bash
+git clone https://github.com/37chengshan/eduevidence.git
+cd eduevidence
+bash install.sh            # venv + 依赖 + 自检 + 测试
+# 或最小安装
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+```
+
+要求 Python ≥ 3.10；内核（`engine/`、`retrieval/`）零第三方依赖，测试需要 `pytest`。Node 只在构建 Research Studio 前端时需要。
+
+## 2. 提交前必须跑的门
+
+```bash
+python scripts/check_version_consistency.py   # 版本口径单一权威
+python scripts/generate_metrics.py --check    # 文档数字与仓库一致
+python scripts/skill_lint.py                  # Skill 结构完整
+python scripts/check_protocol_alignment.py    # 协议五方对齐
+ruff check --select E9,F63,F7,F82 .
+python -m pytest -q
+```
+
+CI（`.github/workflows/ci.yml`）会重复执行上述门，外加 wheel 隔离安装冒烟、schema-smoke 与提交包构建。本地全绿是提交的最低门槛。
+
+## 3. 科学不变量（不可协商）
+
+- **任务表现 ≠ 学习效果**：任何把任务完成度当作学习收益的写法都会被门拒绝。
+- **snippet ≠ 证据**：检索片段与摘要只是发现线索，只有抓取并通过校验门的正文可以抽取。
+- **缺证据 ≠ 零效应**：证据不足时输出 `INSUFFICIENT EVIDENCE`，不得换算成"无效"。
+- **无证据奠基不得设计新研究**：研究设计必须引用显式的 KnowledgeGap ID。
+- **证据 append-only**：修订产生新 revision 与新 decision snapshot，绝不覆盖历史。
+- **写入者唯一**：图修订只能由规范写入者提交，worker 不得直接写图。
+
+详见 `references/scientific-invariants.md`，由 `scripts/check_autoresearch_invariants.py` 强制。
+
+## 4. 如何新增一项能力（capability）
+
+能力是"协议能做什么"的最小单元，它与模型、CLI、Agent 数量无关。新增一项能力需要同时落地四处，缺一不可：
+
+1. `engine/capabilities.py`：用 `_register(...)` 注册 `capability_id`、输入/输出契约、是否可确定性本地执行，以及（如有）科学门。
+2. `skill/roles/registry.yaml`：把能力分配给承担它的角色（`capabilities:` 列表）。
+3. `skill/agents/<role>.md`：在 frontmatter 的 `capabilities` 中同步，并在正文写清产出契约。
+4. `skill/sub-skills/<name>/SKILL.md`：frontmatter 写 `capability:`，正文按 recipe 模板给出 Inputs / Process / Output Contract / Quality Gates / Anti-Patterns。
+
+跑 `python scripts/check_protocol_alignment.py` 验证五方一致。
+
+## 5. 如何新增一个子技能（sub-skill）
+
+子技能是内部能力配方，不是新的用户入口。模板：
+
+```markdown
+---
+name: <dir-name>            # 必须与目录名一致
+description: "..."
+capability: <capability_id>  # 映射到 engine/capabilities.py
+---
+
+# <Title>
+## When to Use
+## Inputs
+## Process
+## Output Contract
+## Quality Gates
+## Anti-Patterns
+## Worked Example
+## References
+```
+
+## 6. 如何新增一个角色（role）
+
+角色是责任单元，不是运行时 Agent。新增角色需要：`skill/roles/registry.yaml`（stage / capability / critical_path）、`skill/agents/<role>.md`（frontmatter 用 `role_id` / `capabilities` / `output_contracts` / `recommended_reasoning`，**不得写死模型或 CLI 名**）、`integrations/agent_mcp.py` 的 `ROLE_REQUIREMENTS`（只写能力等级）。
+
+需要独立性的角色显式声明：`independence_required: different-model-family`（如 skeptic）或 `role-separation`（如 method-reviewer）。
+
+## 7. 如何新增一个检索通道
+
+1. 在 `retrieval/` 下实现 provider（stdlib-only、超时、定型错误，不抛异常到管道）。
+2. 零配置通道进 `zero_config_academic` / `zero_config_web`；需 key 的学术通道进 `academic_key_providers`，并实现 `is_available()`。
+3. 命中结果统一为 `SearchHit`；沿用 `doc_id` / `chunk_id` / `offset` 表达定位（如适用）。
+4. 在 `docs/` 记录端点契约，在 `references/retrieval-compliance.md` 补齐配额与限制，在 `tests/` 用 mock HTTP 覆盖成功与各类失败。
+
+## 8. 证据纪律与文档
+
+- 示例与演示必须如实标注 `data_origin`（manual_curated / synthetic / hybrid）；不得把手工整理文献说成模型运行结果。
+- 数字口径以 `docs/metrics.json` 为准，文档中不硬编码会漂移的计数。
+- 内部文档用中文，`SKILL.md` 保持英文；协议语义（九步、四态、Projection 边界）不因文档改写而改变。
+
+## 9. PR 检查表
+
+- [ ] 五个门本地全绿（版本 / 指标 / skill_lint / 协议对齐 / 测试）。
+- [ ] 新增或改动的契约在五方（协议 / 能力 / 角色 / 简报 / 子技能）一致。
+- [ ] 未引入硬编码的模型名、CLI 名或密钥。
+- [ ] 科学不变量未被弱化；如有例外，在 PR 说明中显式论证。
+- [ ] 文档、CHANGELOG、`docs/plans/STATUS.md` 同步更新。
+- [ ] 未提交本地运行状态、私有数据或凭据。
+
+## 10. 行为准则
+
+讨论以证据为准：提出结论时给出可核验来源；被反驳时更新结论而不是更新措辞。对他人贡献的评审聚焦"证据是否支撑结论"，不针对作者。
+

package/README.md

@@ -1,18 +1,35 @@
+<p align="center">
+  <img src="assets/readme/logo.png" width="88" height="88" alt="EduEvidence logo" />
+</p>
+
 # EduEvidence
 
 > **🌐 English | [中文](README.zh-CN.md)**
 
-## EduEvidence Research Engine — Evidence-Based Education Decision Skill
+## EduEvidence Research Engine — Evidence Research & Decision Skill
+
+> **From Research Questions to Evidence-Based Decisions.** · Current release **6.2.0**
 
-> **From Education Questions to Evidence-Based Decisions.**
+> **▶ Live demo:** [Landing](https://37chengshan.github.io/eduevidence/) · [Research Studio](https://37chengshan.github.io/eduevidence/studio/) · [Deep Research comparison](https://37chengshan.github.io/eduevidence/comparison.html)
 
 EduEvidence is delivered as an **AI Agent Skill**; inside the Skill operates
 the **EduEvidence Research Engine** — a persistent, auditable engine that
-turns education questions into evidence-grounded decisions.
-
-- **Two Research Modes** — **Evidence Review** (secondary-evidence research)
-  and **Full Research Cycle** (Evidence Review → Knowledge Gap → study design
-  → your data → analysis → updated decision).
+turns a decision question into an evidence-grounded answer. It is **multi-domain**:
+the domain registry (`domains/manifest.json`) ships **education** and **policy**
+today, each declaring its own frame schema, outcome taxonomy and methodology
+checklist, so one nine-stage protocol serves education and applied social science
+work without forking the engine.
+
+- **Three public workflows** — **Evidence Review**, **Decision & Pilot**, and
+  **Evaluate & Update**. A full research cycle connects existing evidence,
+  grounded knowledge gaps, a study design, new data and a revised decision.
+- **Multi-domain by contract** — `education` and `policy` are registered domains;
+  a run validates against its own domain's frame schema and outcome taxonomy
+  (`engine/taxonomy.py` is the single authority; unknown tokens fail closed).
+- **Retrieval that stays traceable** — zero-config channels (OpenAlex / Semantic
+  Scholar / CrossRef / AIHot / AgentSearch / DuckDuckGo) plus key-based channels:
+  **Sciverse** (citation-grade academic retrieval with full-text locators),
+  Tavily and Brave. A lookup snippet is a locator, never evidence.
 - **Project Workspace + Evidence Graph** — long-lived Projects with versioned,
   immutable graph revisions; `result.json`/HTML/Markdown are projections, not
   fact stores.
@@ -21,18 +38,38 @@ turns education questions into evidence-grounded decisions.
 - **Frozen scientific rule** — *No new study design without evidence
   grounding*: designs must reference explicit, evidence-grounded Knowledge
   Gap IDs.
-- ⚖️ It does not generate answers for teachers — it shows what the evidence supports, what it cannot support, who it applies to, and how to pilot and verify it.
+- ⚖️ Inspect what the evidence supports, what it cannot support, who it applies to, and how to pilot and verify it.
 - 🧪 Built on real research (examples include CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 empirical evidence); no claims without sources.
-- 🚦 The output is not a binary "allow/forbid" answer but a four-state decision — **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** — plus an actionable teaching intervention and evaluation plan.
+- 🚦 The output is not a binary "allow/forbid" answer but a four-state decision — **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** — plus an actionable intervention and evaluation plan.
 - 🧩 The engine is an internal capability architecture — not a standalone
   server/app; Native Core runs on Python stdlib only and never requires
   Agent MCP or a daemon.
 
-![EduEvidence overview banner](assets/top-banner.jpg)
+![Research Studio walkthrough: overview, report library, and the five report identities](assets/readme/studio-tour.gif)
+
+*Recorded from the actual local Studio — no mockups: overview → report library → five report identities. Below, the introduction page walkthrough:*
+
+![Introduction page walkthrough: hero, nine-step protocol, five report systems](assets/readme/landing-tour.gif)
 
 ---
 
-## Quick Install
+## Quick Start
+
+**Fastest path — read a finished report (no install):**
+
+```bash
+open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
+open examples/spaced-retrieval-practice/EduEvidence_Report.html   # real Sciverse run
+```
+
+**Look at the console (Python 3.10+, Node not required):**
+
+```bash
+python3 scripts/dashboard_server.py --host 127.0.0.1 --port 8765
+# browser: http://127.0.0.1:8765/studio/   (read-only research console)
+```
+
+**Install it:**
 
 **npm (recommended for Skill install)**
 
@@ -54,7 +91,7 @@ bash install.sh              # one-click: venv + deps + self-check + tests
 Open the example report right away:
 
 ```bash
-open examples/ai-coding-assistant/EduEvidence_Report.html
+open examples/ai-coding-assistant-evidence/EduEvidence_Report.html
 ```
 
 > Requires Python 3.10+; the core has zero third-party dependencies. `pip install matplotlib` is optional for academic-figure PNG/PDF export.
@@ -129,7 +166,7 @@ runnable + sample report renderable).
 
 ## What Problem We Solve
 
-A typical AI answers an education question like this:
+A typical AI answers a decision question like this:
 
 ```text
 Question → Search a few sources → Summarize opinions → Give advice
@@ -138,15 +175,15 @@ Question → Search a few sources → Summarize opinions → Give advice
 EduEvidence does this instead:
 
 ```text
-Education question
-  → Education Research Framing (learner / intervention / comparison / outcomes / context)
+Decision question (education or applied social science)
+  → Domain Research Framing (learner or decision object / intervention / comparison / outcomes / context)
   → Literature & evidence retrieval (supporting evidence + independent counter-evidence)
   → Claim-Level Evidence Extraction
   → Skeptic challenge protocol + Method Reviewer audit
   → Evidence Tribunal
   → Applicability Analysis
   → Decision: ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE
-  → Teaching Intervention (minimum viable pilot)
+  → Intervention (minimum viable pilot)
   → Evaluation Plan
 ```
 
@@ -155,43 +192,44 @@ It answers six questions:
 1. What does the current evidence actually support?
 2. What can the current evidence not support?
 3. Why do different studies reach different results?
-4. Which students, which courses, under which conditions does it apply to?
-5. If an institution adopts it, how to roll it out with low risk?
+4. Which population, in which setting, under which conditions does it apply to?
+5. If an institution adopts it, how should it be rolled out with low risk?
 6. How to verify whether it actually works after implementation?
 
-## 30-second Demo
+## 30-second tour
 
-> Main demo: **Should first-year C programming students be allowed to use generative AI coding assistants?**
+> Flagship question: **Should first-year C programming students be allowed to use generative AI coding assistants?**
 
 | Time | Stage |
 |---|---|
-| 0–20s | Ask the education question |
-| 20–45s | Education Research Frame |
+| 0–20s | Ask the decision question |
+| 20–45s | Research Frame (domain-specific schema) |
 | 45–75s | Evidence Retrieval |
 | 75–110s | Evidence Matrix |
 | 110–135s | Methodology + Skeptic |
 | 135–155s | Evidence Tribunal |
-| 155–170s | Teaching Intervention + Evaluation |
+| 155–170s | Intervention + Evaluation |
 | 170–180s | Benchmark |
 
-Full example pack: [`examples/ai-coding-assistant/`](examples/ai-coding-assistant/).
+Full example pack: [`examples/ai-coding-assistant-evidence/`](examples/ai-coding-assistant-evidence/).
 
-## Why Education Evidence Is Hard
+## Why Evidence Decisions Are Hard
 
-Education evidence has natural pitfalls. EduEvidence's core contribution is standardizing the countermeasures:
+Evidence across education and applied social science shares the same natural pitfalls. EduEvidence's core contribution is standardizing the countermeasures:
 
 - **Outcome Separation**: `faster task completion ≠ actually learning to program`; `short-term score gains ≠ long-term retention`; `completing tasks with AI ≠ transferring skills without AI`.
 - **Counter-Evidence Search**: it does not just verify the user's initial assumption — it independently searches for null / negative / contradictory evidence, AI dependency, novelty effects, self-selection bias, and more.
 - **Evidence Tribunal**: instead of listing pros and cons, it judges which studies are more credible, whether conflicts come from samples / measurement / course / tool / design, and what can be concluded so far.
-- **Evidence-to-Action Bridge**: it does not stop at "research shows…" — it connects to applicability, the teaching decision, pilot intervention, and evaluation design.
+- **Evidence-to-Action Bridge**: it does not stop at "research shows…" — it connects to applicability, the decision, pilot intervention, and evaluation design.
 
 ## How EduEvidence Works
 
 ```text
 ┌─────────────────────────────────────┐
 │            EduEvidence              │
-│  education knowledge + decision +   │
-│  intervention + evaluation          │
+│  domain contracts (education /       │
+│  policy) + decision + intervention   │
+│  + evaluation                        │
 └────────────────┬────────────────────┘
                  │
 ┌────────────────▼────────────────────┐
@@ -209,22 +247,24 @@ Education evidence has natural pitfalls. EduEvidence's core contribution is stan
 The 9-step workflow:
 
 ```text
-1. Frame          Build the EducationResearchFrame
+1. Frame          Build the domain frame (education frame / policy frame)
 2. Retrieve       Retrieve literature & evidence (support + independent counter-evidence)
 3. Extract        Extract claim-level evidence (bound to outcomes)
 4. Challenge      Skeptic protocol (fixed 9 checks)
 5. Audit          Method Reviewer audit (15-item checklist)
 6. Adjudicate     Evidence Tribunal (Evidence Matrix + Verdict)
 7. Applicability  Applicability analysis
-8. Intervene      Teaching Intervention design (minimum viable pilot)
+8. Intervene      Intervention design (minimum viable pilot)
 9. Evaluate       Evaluation Plan design
 ```
 
-Every step is validated against JSON Schemas (`schemas/`), deterministic logic lives in `scripts/`, and the education methodology is documented independently in `references/`.
+Every step is validated against JSON Schemas (`schemas/`), deterministic logic lives in `scripts/`, and the methodology is documented independently in `references/` (21 documents: evidence quality, skeptic protocol, tribunal policy, WWC/GRADE standards, social-science pitfalls, retrieval protocol, report copy style …; counts in `docs/metrics.json`).
 
 ## Outcome Separation
 
-EduEvidence enforces 20 outcome types (`references/outcome-taxonomy.md`):
+Outcome tokens are domain-owned. The education taxonomy declares **20 tokens** in four categories (`domains/education/outcome_taxonomy.json`); the policy domain declares its own categories and tokens (`domains/policy/outcome_taxonomy.json`). `engine/taxonomy.py` is the only reader: an unknown token or unregistered domain **fails closed** instead of being silently classified as a learning outcome.
+
+The education set (`references/outcome-taxonomy.md`):
 
 ```text
 Learning:    Knowledge Gain / Concept Understanding / Retention / Transfer / Independent Problem Solving
@@ -233,25 +273,25 @@ Process:     Engagement / Motivation / Cognitive Load / Help-Seeking / Metacogni
 Risk:        AI Dependency / Over-reliance / Reduced Effort / Reduced Transfer / Academic Integrity Risk / False Confidence
 ```
 
-The demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant raised task completion by 1.15× and correctness by 1.8×, but the one-week retention test showed no significant difference — **task performance ≠ learning**.
+The flagship demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant raised task completion by 1.15× and correctness by 1.8×, but the one-week retention test showed no significant difference — **task performance ≠ learning**.
 
 ## Evidence Tribunal
 
-`references/tribunal-policy.md` defines the adjudication rules: input = Frame + Evidence Matrix + Skeptic Findings + Method Reviews; output = EducationVerdict (`schemas/verdict.schema.json`), including:
+`references/tribunal-policy.md` defines the adjudication rules: input = Frame + Evidence Matrix + Skeptic Findings + Method Reviews; output = the domain Verdict (`schemas/verdict.schema.json`), including:
 
 - supported / uncertain / contradicted claims
 - conflict-source analysis (sample / measurement / course / tool / design)
 - Can Claim / Cannot Claim boundaries
 - four-state decision + Confidence (rule-based, not model-generated freely)
 
-![Evidence Tribunal Workflow](assets/tribunal-workflow.jpg)
+![Evidence Tribunal Workflow](assets/readme/research-workflow.svg)
 
 ## From Evidence to Action
 
-Evidence must connect to the real classroom (`references/applicability-policy.md`, `intervention-design.md`, `evaluation-design.md`):
+Evidence must connect to the real setting — a classroom, a support team, a policy roll-out (`references/applicability-policy.md`, `intervention-design.md`, `evaluation-design.md`):
 
-- **Applicability**: For whom? For which course? For which outcome? Under what conditions? With what AI usage policy?
-- **Intervention**: always a "minimum viable pilot", never direct full deployment; includes AI usage rules, teacher/student roles, reflection requirements, and stop conditions.
+- **Applicability**: For whom? In which setting? For which outcome? Under what conditions? With what AI usage policy?
+- **Intervention**: always a "minimum viable pilot", never direct full deployment; includes AI usage rules, staff/user roles, reflection requirements, and stop conditions.
 - **Evaluation**: every PILOT/ADOPT recommendation must come with an evaluation plan; distinguishes baseline / post-test / retention / transfer, and task-performance vs learning metrics.
 
 ## Benchmark
@@ -276,47 +316,51 @@ Key metrics: Citation Support Precision / Unsupported Claim Rate / Contradiction
 
 > **Should first-year C programming students be allowed to use generative AI coding assistants?**
 
-`examples/ai-coding-assistant/` shows the full path from question to decision:
+`examples/ai-coding-assistant-evidence/` shows the full path from question to decision:
 
-- **Evidence** (7 items, all bound to real sources): task-performance gains (Kazemitabaar 2023), unguarded access harming independent exam performance by −17% (Bastani 2025, PNAS), guardrails eliminating the negative effect (Bastani 2025), formative-feedback writing evidence (Marzuki 2024).
+- **Evidence** (12 findings from 8 sources): task-performance gains (Kazemitabaar 2023), unguarded access harming independent exam performance by −17% (Bastani 2025, PNAS), guardrails eliminating the negative effect (Bastani 2025), formative-feedback writing evidence (Marzuki 2024).
 - **Decision**: **PILOT** — task-performance evidence is strong, but direct learning-effect evidence for university programming courses is missing, and the unguarded-access risk is documented.
 - **Intervention**: 4-phase pilot (Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check).
 - **Evaluation**: no-AI baseline / post-test / final-exam retention / no-AI transfer task + AI-dependency risk metrics.
 
-Two more examples — AI writing assistant (`examples/ai-writing-assistant/`) and a calculus AI tutor (`examples/ai-tutor/`) — show the skill is not hard-coded to one question.
+A second public example, `examples/workplace-ai-assistant/`, evaluates AI assistance in enterprise customer support using the policy domain: 4 findings from 3 studies, with direct and indirect evidence distinguished. Its proposed supervised pilot has not been executed.
+
+The third public example, `examples/spaced-retrieval-practice/`, asks whether spaced repetition and retrieval practice should replace massed review in an introductory programming course. It is the first pack whose sources were located through the **Sciverse** channel (`discovery_provider=sciverse`, `fetch_provider=sciverse_content`) and whose `meta.data_origin` is `real_run_sciverse`: 6 findings from 7 tier-1 DOI sources, decision **ADOPT** (High confidence). It is the worked example that the ADOPT path is reachable: retention and transfer - the two primary outcomes - carry direct, consistent evidence at directness 2, while the coding and workplace cases stay bounded at PILOT because their primary learning evidence is missing.
 
-**Example provenance (read before citing)**: every example pack carries a `data_origin`
-badge in its report header and in `result.json.meta`:
+Each pack ships `result.json` + `result.zh.json` (bilingual parallel data), a packaged-`EduEvidence_Report.html` root report, and `reports-5themes/` with the five standalone theme HTML files.
 
-- `examples/ai-coding-assistant-evidence/` — **flagship, real literature**: 8 sources with
-  registry-verified DOIs (Crossref/DataCite audit: `benchmarks/doi-audit/report.md`),
-  engine-computed confidence; data_origin=`manual_curated`.
-- `examples/ai-coding-assistant/`, `ai-tutor/`, `ai-writing-assistant/` — real-source
-  walkthrough packs.
-- `examples/esl-academic-writing-ai/`, `highschool-math-ai-tutor/` — **synthetic
-  demonstrations** (data_origin=`synthetic`). Their numbers and citations are illustrative,
-  not real studies; reports carry a loud SYNTHETIC badge. Do not cite them as evidence.
+All three public examples are literature demonstrations, and their `data_origin` says exactly what produced them. The coding and workplace cases are **manually curated** (`manual_curated`); the spaced-retrieval case is a recorded **Sciverse-backed run** (`real_run_sciverse`). A rendered report never establishes that an agent completed the whole nine-stage research workflow. See [the workplace evidence notes](docs/demo-workplace-ai.md) for source versions and limitations, and [`docs/reproducibility.md`](docs/reproducibility.md) for how `data_origin` is declared.
 
 ### Start your own research in ~30 minutes
 
 ```bash
-python3 scripts/quickstart.py "你的教育研究问题"          # creates runs/<id> + NEXT_STEPS.md
+python3 scripts/quickstart.py "你的研究问题"             # creates runs/<id> + NEXT_STEPS.md
 # hand the LLM stages to your AI agent per NEXT_STEPS.md, then finish with:
 python3 scripts/orchestrator.py adjudicate --project runs/<id>
 bash scripts/bake_pack.sh <pack_dir>                     # 5-theme bilingual report
 python3 scripts/citation_check.py --pack <pack_dir> --write-back   # DOI ✓ badges
 ```
 
+## Studio in use
+
+Select a graph node to trace source → finding → claim. The flow is a visual aid; it does not signal an active research run.
+
+![Actual provenance graph](assets/readme/studio-graph.png)
+
+Read the same evidence through five independent report themes, with bilingual and brief/full views.
+
+![Actual report reading room](assets/readme/studio-reports.png)
+
 ## Visualization: Bilingual HTML Report + Infographics + Academic Figures
 
-After research completes, `result.json` is rendered into three visualization outputs by deterministic Python adapters. The adapters themselves use the standard library; the optional Web Studio chart enhancement has a separate browser dependency.
+After research completes, `result.json` is rendered into three visualization outputs by deterministic Python adapters. The adapters themselves use the standard library; legacy ECharts enhancement is optional and is not required by the new Research Studio.
 
 ```text
 result.json + result.zh.json (Chinese parallel data)
-  ├─ build_charts.py        → chart_specs.json (ECharts option data; no ECharts runtime bundled)
-  ├─ build_infographics.py  → infographics.json (hand-authored SVGs)
-  ├─ build_figures.py       → figures/ (publication figures: figure_data.json + SVG/PNG/PDF)
-  └─ build_report.py        → EduEvidence_Report.html (single-file bilingual report + report_spec.json)
+  ├─ visualization/eduevidence-report/scripts/build_charts.py        → chart_specs.json (ECharts option data; no ECharts runtime bundled)
+  ├─ visualization/eduevidence-report/scripts/build_infographics.py  → infographics.json (hand-authored SVGs)
+  ├─ visualization/eduevidence-report/scripts/build_figures.py       → figures/ (publication figures: figure_data.json + SVG/PNG/PDF)
+  └─ visualization/eduevidence-report/scripts/build_report.py        → EduEvidence_Report.html (single-file bilingual report + report_spec.json)
 ```
 
 **EduEvidence_Report.html (main deliverable)**:
@@ -328,14 +372,33 @@ result.json + result.zh.json (Chinese parallel data)
 - **Static-first**: decision, matrix, tribunal, intervention and sources remain readable without JavaScript; ECharts is an optional enhancement.
 - **Integrity gate**: chart numbers are checked against result.json item by item; publishing is blocked with `REPORT_INVALID` on mismatch.
 
-**Local Web Studio** (`python3 scripts/dashboard_server.py --port 8765`) has exactly three read-only views: Dashboard, Report Browser and Data Visualization. It loads ECharts 5.4.3 from jsDelivr for interactive charts; the submission package does not bundle that runtime, so Web interactivity requires network access. The baked report's static HTML/SVG remains the offline artifact.
+**Research Studio** is a read-only research workspace. Start `python3 scripts/dashboard_server.py --port 8765` and open `/studio/` to inspect projects, evidence, sources, recorded runs, committed revisions and five report identities. Skill Autoevolve has a separate observation view; the console cannot start research, mutate evidence or dispatch agents.
+
+The React + TypeScript frontend ships as static assets: Node is needed only for development, not for running the packaged Skill. Its charts do not depend on a remote ECharts CDN and never compute a pooled effect in the browser. Local research remains local; GitHub Pages exports public example packs only. Report themes are generated from complete bilingual inputs with explicit missing-data states, not fabricated fallback claims.
+
+See [Research Studio workflow and delivery guide](docs/research-studio-guide.zh-CN.md).
+
+> Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
 
-> Open the example directly: `examples/ai-coding-assistant/EduEvidence_Report.html`
+
+### Optional key-based retrieval channels
+
+Zero-config retrieval (OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch) works out of the box. These channels activate once a key is present and stay silently inactive otherwise — the scientific gates never depend on them:
+
+```bash
+export SCIVERSE_API_TOKEN=sv-...   # citation-grade academic retrieval + full-text location
+export TAVILY_API_KEY=...          # general web search
+export BRAVE_API_KEY=...           # general web search
+```
+
+The Sciverse channel treats an `/agentic-search` chunk as a **locator**: it must be expanded through `/content` and pass the validation gate before it may enter evidence extraction (RULE 2, machine-enforced). Contract: `docs/sciverse-api.md`; compliance: `references/retrieval-compliance.md`.
 
 ## Architecture
 
 The repository is a complete **Skill package**: `SKILL.md` is the entry point; everything else is layered as *skill core → quality assurance → demos*. See [`docs/architecture.md`](docs/architecture.md):
 
+Read the illustrated single-file walkthrough of the same architecture (nine-step protocol, roles and independence, artifact/state map, execution and approval loop) at [`web/architecture.html`](web/architecture.html).
+
 ```text
 EduEvidence/  (= one Skill package)
 │
@@ -360,14 +423,14 @@ EduEvidence/  (= one Skill package)
 │                            bilingual HTML composer + V2 project surfaces)
 │
 ├─ Quality assurance
-│  ├─ tests/                 pytest test matrix (V1–V4, 752 test functions / 73 files — docs/metrics.json)
+│  ├─ tests/                 pytest test matrix (V1–V4, current counts in docs/metrics.json)
 │  └─ benchmarks/            V1 questions + benchmarks/v2/ (graph/contract metrics)
 │
 └─ Demos & distribution
    ├─ examples/              Research & Decision Packs + full-research-cycle-fixture (synthetic)
    ├─ docs/                  architecture / methodology / benchmark / demo / reproducibility
    ├─ install.sh             one-click install (local / multi-agent Skill) + self-check
-   ├─ pyproject.toml         packaging metadata (wheel ships CLI + engine; stdlib-only core)
+   ├─ pyproject.toml         packaging metadata (wheel ships CLI, engine and installed runtime resources; stdlib-only core)
    └─ README(.en).md         bilingual docs
 ```
 
@@ -419,7 +482,7 @@ Agent MCP is a **performance & reliability enhancement layer, not a prerequisite
 
 > 🔒 Agent MCP principle: **Scan first. Recommend second. Ask the user. Execute only after explicit confirmation.** No spawn without user approval; reject → fall back to Native.
 
-![Controlled Multi-Agent Research](assets/multi-agent-research.jpg)
+![Controlled Multi-Agent Research](assets/readme/controlled-execution.svg)
 
 
 ## Usage
@@ -427,33 +490,37 @@ Agent MCP is a **performance & reliability enhancement layer, not a prerequisite
 ```bash
 # 1. Validate data against the schema contracts
 python3 scripts/validate_schema.py --schema schemas/evidence.schema.json \
-    --data examples/ai-coding-assistant/evidence.jsonl
+    --data examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 2. Compute evidence quality scores and Confidence
-python3 scripts/evidence_score.py examples/ai-coding-assistant/evidence.jsonl
+python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 3. Generate the Evidence Matrix (one of the core views)
-python3 scripts/evidence_matrix.py examples/ai-coding-assistant/evidence.jsonl
+python3 scripts/evidence_matrix.py examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 4. Run the Citation Audit (claim-evidence traceability)
-python3 scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
+python3 scripts/claim_audit.py \
+  --claims examples/ai-coding-assistant-evidence/claims.jsonl \
+  --evidence examples/ai-coding-assistant-evidence/evidence.jsonl
 
 # 5. Render the Research & Decision Pack (Markdown)
 python3 scripts/render_report.py \
-    --frame examples/ai-coding-assistant/frame.json \
-    --evidence examples/ai-coding-assistant/evidence.jsonl \
-    --methodology examples/ai-coding-assistant/methodology.json \
-    --verdict examples/ai-coding-assistant/verdict.json \
-    --intervention examples/ai-coding-assistant/intervention.json \
-    --evaluation examples/ai-coding-assistant/evaluation.json \
+    --frame examples/ai-coding-assistant-evidence/frame.json \
+    --evidence examples/ai-coding-assistant-evidence/evidence.jsonl \
+    --methodology examples/ai-coding-assistant-evidence/methodology.json \
+    --verdict examples/ai-coding-assistant-evidence/verdict.json \
+    --intervention examples/ai-coding-assistant-evidence/intervention.json \
+    --evaluation examples/ai-coding-assistant-evidence/evaluation.json \
     --out REPORT.md
 
 # 6. Render the single-file bilingual HTML report (main deliverable)
 python3 visualization/eduevidence-report/scripts/build_report.py \
-    --result examples/ai-coding-assistant/result.json \
-    --out examples/ai-coding-assistant/EduEvidence_Report.html
+    --result examples/ai-coding-assistant-evidence/result.json \
+    --out examples/ai-coding-assistant-evidence/EduEvidence_Report.html
 
 # 7. Validate the benchmark question set
+# Source checkout only: benchmarks/questions.jsonl is not part of the
+# shipped Skill package (see packaging/upload-layout.md).
 python3 scripts/benchmark.py --questions benchmarks/questions.jsonl
 
 # 8. Run the tests