eduevidence 6.0.0 → 6.3.0

package/README.md

@@ -8,15 +8,28 @@
 
 ## EduEvidence Research Engine — Evidence Research & Decision Skill
 
-> **From Research Questions to Evidence-Based Decisions.**
+> **From Research Questions to Evidence-Based Decisions.** · Current release **6.3.0**
+
+> **▶ 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 research questions into evidence-grounded decisions across education and organizational policy.
+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.
@@ -32,13 +45,31 @@ turns research questions into evidence-grounded decisions across education and o
   server/app; Native Core runs on Python stdlib only and never requires
   Agent MCP or a daemon.
 
-![Actual Research Studio overview: workplace AI evidence](assets/readme/studio-overview.png)
+![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:*
 
-*Actual local Studio screenshot. This case is manually curated literature, with no attached research execution history.*
+![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)**
 
@@ -135,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
@@ -144,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
 ```
 
@@ -161,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-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                        │
 └────────────────┬────────────────────┘
                  │
 ┌────────────────▼────────────────────┐
@@ -215,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
@@ -239,11 +273,11 @@ 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)
@@ -254,15 +288,15 @@ The demo's highlight: in Kazemitabaar et al. (CHI 2023), the AI code assistant r
 
 ## 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
 
-30 education research questions in v1 (`benchmarks/questions.jsonl`), S×10 / M×10 / L×10; 15 in the core domain "AI-assisted university teaching", 10 with human gold annotations (`benchmarks/annotations/`).
+30 education research questions in v1 (`benchmarks/questions.jsonl`), S×10 / M×10 / L×10; 15 in the core domain "AI-assisted university teaching", all 30 with human gold annotations (`benchmarks/annotations/gold-Q01..Q30`).
 
 Baseline design:
 
@@ -285,20 +319,22 @@ Key metrics: Citation Support Precision / Unsupported Claim Rate / Contradiction
 `examples/ai-coding-assistant-evidence/` shows the full path from question to decision:
 
 - **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.
+- **Decision**: recorded `PILOT` (Moderate, 0.586); matrix landing (`engine.decision_policy.decision_outcome`) is `INSUFFICIENT_EVIDENCE` (`unresolved_conflict`) — the decisive relations contain both `support_adoption` and `oppose_adoption`, which fails the conflict check before any `ADOPT`/`PILOT` claim; 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.
 
-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.
+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 recorded action is `PILOT` (Moderate, 0.578); the matrix landing is `INSUFFICIENT_EVIDENCE` with `downgrade_reason=None`: all four decisive relations are `conditional`, and `conditional` is not a conflict relation (`engine.decision_policy.CONFLICT_RELATIONS` = `{conflict, mixed}`), so no downgrade reason is recorded and — with no decisive `support_adoption` relation — Moderate confidence cannot reach `PILOT`. Its proposed supervised pilot has not been executed.
 
-Both public examples are **manually curated literature demonstrations** (`manual_curated`). A generated report does not establish that an agent completed the nine-stage research workflow. The coding case contains 12 findings from 8 sources; the workplace case contains 4 findings from 3 sources. See [the workplace evidence notes](docs/demo-workplace-ai.md) for source versions and limitations.
+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, 0.893) — the only public case where the recorded action and the matrix landing agree. 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. The coding and workplace cases are bounded below ADOPT: the coding case's decisive relations mix `support_adoption` with `oppose_adoption` (`unresolved_conflict`), and the workplace case carries no decisive `support_adoption` relation at all (all four are `conditional`), so both land at `INSUFFICIENT_EVIDENCE`.
 
-Four older teaching demos have moved to `tests/fixtures/legacy-examples/` for compatibility tests. They are excluded from public catalogs and distribution; their unverified or synthetic findings must not be cited as research evidence. The old `ai-coding-assistant` path remains a compatibility alias.
+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.
+
+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
@@ -321,10 +357,10 @@ After research completes, `result.json` is rendered into three visualization out
 
 ```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)**:
@@ -344,23 +380,39 @@ See [Research Studio workflow and delivery guide](docs/research-studio-guide.zh-
 
 > Open the example directly: `examples/ai-coding-assistant-evidence/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)
 │
-├─ SKILL.md                  ← Skill entry: When to Use / Inputs / Workflow / Output Contract
+├─ SKILL.md                  ← Skill entry: mission → workflow routing → scientific gates → 9-step protocol → output requirements
 │
 ├─ Skill core (required to run)
 │  ├─ engine/                V2 Research Engine (Project Workspace / immutable Evidence
 │  │                         Graph / Library / synthesis / tribunal / study design /
 │  │                         datasets / analysis / projections / migration)
 │  ├─ skill/agents/          role protocols (capability execution profiles)
-│  ├─ references/            11 education methodology documents (evidence quality / skeptic /
-│  │                         tribunal policy / intervention design…)
-│  ├─ schemas/               V1 + v2/v3 contracts (13 top-level + 17 v2 + v3 pilot/synthesis/run-manifest)
+│  ├─ references/            21 methodology documents (evidence quality / skeptic /
+│  │                         tribunal policy / intervention design…; counted in docs/metrics.json)
+│  ├─ schemas/               50 versioned JSON Schema contracts (15 top-level + 18 v2 +
+│  │                         3 v3 + 4 v4 + 10 vNext; counted by `scripts/generate_metrics.py`)
 │  ├─ domains/               v4 domain registry (manifest.json) + per-domain packages
 │  │                         (education: registration-only; policy: frame schema /
 │  │                         outcome taxonomy / methodology checklist / references)
@@ -380,11 +432,18 @@ EduEvidence/  (= one Skill package)
    ├─ 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 and installed runtime resources; stdlib-only core)
-   └─ README(.en).md         bilingual docs
+   └─ README.md / README.zh-CN.md   bilingual docs
 ```
 
 > Skill-package principle: the **minimal runtime set is `SKILL.md + engine/ + skill/ + references/ + schemas/ + scripts/`**; `retrieval/`, `integrations/`, `visualization/` are the execution/presentation layers that make the Skill actually runnable; `tests/`, `benchmarks/`, `examples/`, `docs/` provide credibility and onboarding — none of them affect the Skill body itself.
 
+### Distribution
+
+Two release channels, built from one runtime allowlist (`scripts/skill_payload.py`, shared with the host installer):
+
+- **Submission folder** — `bash packaging/make_upload.sh` rebuilds `dist/eduevidence-submission/` (flat Skill package + `submission-manifest.json` + `UPLOAD-README.md`); it regenerates the report variants first and aborts without a prebuilt `web/studio/index.html`. The older `upload/` tree is a **frozen deprecated snapshot** that must not be shipped — see [`upload/DEPRECATED.md`](upload/DEPRECATED.md).
+- **npm package** — `npm install -g eduevidence`, then `eduevidence skill --list-hosts` (every supported agent and its install path) or `eduevidence skill --dry-run` (preview; writes nothing). From a checkout the same flags run as `node bin/eduevidence.js skill --list-hosts` / `--dry-run`.
+
 ### v4 Domain Registry (EvidenceCore)
 
 The first step of the **EvidenceCore** abstraction: a `domains/` registry
@@ -394,8 +453,9 @@ The first step of the **EvidenceCore** abstraction: a `domains/` registry
 
 - **education** is a **registration-only domain**: it points at the existing
   contracts — `schemas/education-frame.schema.json` (frame),
-  the 20-token outcome taxonomy from `schemas/evidence.schema.json` (four
-  categories per `engine/pilot.py` `_OUTCOME_CATEGORY`), the 15-item
+  the 20-token education outcome taxonomy from
+  `domains/education/outcome_taxonomy.json` (`engine/taxonomy.py` is its sole
+  reader; 25 tokens across education + policy), the 15-item
   methodology checklist from `skill/agents/method-reviewer.md`,
   `benchmarks/annotations` (golds) and `references/`. It **adds no new logic
   path** — no new schema, no new validator, no new methodology.
@@ -448,7 +508,9 @@ python3 scripts/evidence_score.py examples/ai-coding-assistant-evidence/evidence
 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 \
@@ -466,6 +528,8 @@ python3 visualization/eduevidence-report/scripts/build_report.py \
     --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
@@ -495,7 +559,7 @@ pytest
   simulation that proves the evaluation framework runs; it is **not** real model
   performance (see the ⚠️ note in [Benchmark](#benchmark)).
 - [x] Skill core & pipeline: 9-step protocol (Research Core 6 + Decision Extension 3),
-  13 top-level JSON Schemas, deterministic scripts, 8-role protocols (original Phases 0–6).
+  50 versioned JSON Schemas (`schemas/**`, counted by `scripts/generate_metrics.py`), deterministic scripts, 8-role protocols (original Phases 0–6).
 - [x] Evidence-to-action: applicability / four-state decision / intervention / evaluation.
 - [x] Product UI: single-file bilingual HTML report + infographics + academic figures
   (original Phase 8).

package/README.zh-CN.md

@@ -11,6 +11,8 @@
 > **From Research Questions to Evidence-Based Decisions.**
 > **从研究问题，到有证据支撑的决策。**
 
+> **▶ 在线演示：** [介绍页](https://37chengshan.github.io/eduevidence/) · [Research Studio](https://37chengshan.github.io/eduevidence/studio/) · [深度调研对比页](https://37chengshan.github.io/eduevidence/comparison.html)
+
 EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI 工具采用等问题转化为**可追溯、可质疑、可验证的证据决策流程**。当前公开案例涵盖编程学习和企业客服，分别使用教育与组织政策领域契约。
 
 - **三条公开工作流**：Evidence Review（证据综述）、Decision & Pilot（决策与试点）、Evaluate & Update（评估与更新）。完整研究周期将文献证据、有依据的知识缺口、研究设计、新数据和决策修订连接起来。
@@ -18,9 +20,11 @@ EduEvidence 面向研究者与实践决策者，将教育、组织政策和 AI
 - 🧪 基于真实研究（示例包含 CHI 2023 / PNAS 2025 / ACL 2025 / Springer 2024 的实证证据），不做无来源断言。
 - 🚦 最终输出不是"允许/禁止"的二元结论，而是 **ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE** 四态决策 + 可落地的干预与评价方案。
 
-![实际研究概览：企业客服 AI 证据案例](assets/readme/studio-overview.png)
+![Research Studio 操作实录：总览 → 报告阅读室 → 五种报告形态](assets/readme/studio-tour.gif)
+
+*本地 Studio 真实录屏（非示意）：总览 → 报告阅读室 → 五种报告形态。下方为介绍页滚动实录：*
 
-*本地 Studio 实际截图。案例为人工整理文献，未附研究执行历史。*
+![介绍页实录：首屏 → 九步协议 → 五套报告体系](assets/readme/landing-tour.gif)
 
 ---
 
@@ -280,13 +284,15 @@ B4 EduEvidence + Agent MCP      ← 证明多 Agent 增强价值（B3 vs B4）
 `examples/ai-coding-assistant-evidence/` 完整展示了从问题到决策的全过程：
 
 - **证据**（12 条发现、8 个来源）：任务表现提升（Kazemitabaar 2023）、无护栏访问损害独立考试表现 -17%（Bastani 2025, PNAS）、护栏设计消除负效应（Bastani 2025）、形成性反馈写作证据（Marzuki 2024）。
-- **决策**：**PILOT** —— 任务表现证据强，但大学编程课程的直接学习效应证据缺失，无护栏风险已被证实。
+- **决策**：落档动作 `PILOT`（Moderate，0.586）；矩阵落点（`engine.decision_policy.decision_outcome`）为 `INSUFFICIENT_EVIDENCE`（`unresolved_conflict`）—— decisive relations 中同时存在 `support_adoption` 与 `oppose_adoption`，冲突检查在 `ADOPT`/`PILOT` 判定前即短路；任务表现证据强，但大学编程课程的直接学习效应证据缺失，且无护栏风险已被证实。
 - **干预**：4 阶段试点（Independent Foundation → Explain Don't Solve → Structured Collaboration → Transfer Check）。
 - **评价**：无 AI 基线/后测/期末考试保持/无 AI 迁移任务 + AI 依赖风险指标。
 
-另一公开案例 `examples/workplace-ai-assistant/` 使用组织政策领域，讨论企业客服是否引入 AI 助手：3 项研究、4 条发现，区分直接客服证据与间接写作/咨询证据，建议有监督试点。详见 [来源核验与边界](docs/demo-workplace-ai.md)。
+另一公开案例 `examples/workplace-ai-assistant/` 使用组织政策领域，讨论企业客服是否引入 AI 助手：3 项研究、4 条发现，区分直接客服证据与间接写作/咨询证据，落档动作 `PILOT`（Moderate，0.578），矩阵落点为 `INSUFFICIENT_EVIDENCE` 且 `downgrade_reason=None`：4 条 decisive relation 全为 `conditional`，而 `conditional` 不属于冲突关系（`engine.decision_policy.CONFLICT_RELATIONS` = `{conflict, mixed}`），因此引擎不记录降级理由；又因没有任何 decisive 的 `support_adoption`，Moderate 置信度无法升到 `PILOT`。详见 [来源核验与边界](docs/demo-workplace-ai.md)。
 
-两个公开案例均为人工整理文献（`manual_curated`），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
+第三个公开案例 `examples/spaced-retrieval-practice/`（来源经 Sciverse 通道逐条读回原文）讨论间隔重复与检索练习能否替代集中式复习：6 条证据、7 篇 tier-1 DOI 来源，判定 **ADOPT**（High，引擎复算 0.893）—— 唯一一个落档动作与矩阵落点一致的公开案例。它是“ADOPT 出口真实可达”的实证：延迟保持与迁移两个主要结果上都有 directness=2 的直接且一致证据；另两例低于 ADOPT：编程案中 decisive relations 同时含 `support_adoption` 与 `oppose_adoption`（`unresolved_conflict`），企业客服案中没有任何 decisive 的 `support_adoption`（4 条全为 `conditional`），因此矩阵落点均为 `INSUFFICIENT_EVIDENCE`，不得表述为已落在 PILOT。
+
+三个公开案例的数据来源各自如实标注：编程与企业客服两例为人工整理文献（`manual_curated`），间隔重复一例为真实 Sciverse 检索运行记录（`real_run_sciverse`），报告生成不等于九阶段模型研究已运行，也不代表试点已经执行。四个旧教学示例迁入 `tests/fixtures/legacy-examples/`，仅供软件兼容测试，排除于公共目录和分发包；未核验或合成数据不能引用为研究证据。旧 `ai-coding-assistant` 路径保留兼容别名。
 
 ## Studio 实际界面
 
@@ -327,27 +333,41 @@ result.json + result.zh.json
 
 > Open the example directly: `examples/ai-coding-assistant-evidence/EduEvidence_Report.html`
 
+### 可选检索通道（key-based）
+
+零配置检索（OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch）开箱可用。配置以下 key 后通道自动启用，未配置时静默失活、不影响科学门：
+
+```bash
+export SCIVERSE_API_TOKEN=sv-...   # 引用级学术检索 + 全文定位（meta-search / agentic-search / content / paper-relations）
+export TAVILY_API_KEY=...          # 通用网页检索
+export BRAVE_API_KEY=...           # 通用网页检索
+```
+
+Sciverse 通道把 `/agentic-search` 的 chunk 当作**定位子**：必须经 `/content` 读原文并通过校验门后，才允许进入证据抽取（RULE 2 的机器化执行）。契约见 `docs/sciverse-api.md`，合规见 `references/retrieval-compliance.md`。
+
 ## Architecture
 
 仓库是一个完整的 **Skill 包**：`SKILL.md` 是入口，其余目录按"Skill 运行必需 → 质量保障 → 演示"分层。详见 [`docs/architecture.md`](docs/architecture.md)：
 
+同一套架构的图解单页（九步协议 / 角色与独立性 / 产物状态地图 / 执行与审批闭环）见 [`web/architecture.html`](web/architecture.html)。
+
 ```text
 EduEvidence/  （= 一个 Skill 包）
 │
-├─ SKILL.md                  ← Skill 入口：When to Use / Inputs / 9 步 Workflow / 输出契约
+├─ SKILL.md                  ← Skill 入口：使命 → 工作流路由 → 科学门禁 → 9 步协议 → 输出要求
 │
 ├─ Skill 本体（运行必需）
 │  ├─ skill/agents/          8 个角色协议（Planner / Retriever / Analyst / Skeptic /
 │  │                         Method Reviewer / Judge / Intervention Designer / Evaluation Designer）
-│  ├─ references/            11 个教育方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计…）
-│  ├─ schemas/               33 个 JSON Schema 数据契约（13 顶层 + 17 v2 + 3 v3，每步输出的校验门）
-│  ├─ scripts/               17 个确定性逻辑脚本（评分 / 矩阵 / 审计 / 置信度 / Orchestrator / 启动探测）
+│  ├─ references/            方法论文档（证据质量 / 反证协议 / 裁决规则 / 干预设计 / 检索合规 / 文案规范…；数量见 docs/metrics.json）
+│  ├─ schemas/               50 个 JSON Schema 数据契约（15 顶层 + 18 v2 + 3 v3 + 4 v4 + 10 vNext，每步输出的校验门；递归计数见 `scripts/generate_metrics.py`）
+│  ├─ scripts/               确定性逻辑脚本（评分 / 矩阵 / 审计 / 置信度 / Orchestrator / 启动探测）
 │  ├─ retrieval/             检索与抓取层（fetch / validate / dedupe / failures）
 │  ├─ integrations/          Agent MCP 增强层 + Smart Web Fetch 集成
 │  └─ visualization/         结果呈现层（ECharts / 信息图 / 学术图 / 双语 HTML Composer）
 │
 ├─ 质量保障
-│  ├─ tests/                 pytest 测试矩阵（752 个测试函数，73 个文件，见 docs/metrics.json）
+│  ├─ tests/                 pytest 测试矩阵（测试函数与文件数见源码仓库的 docs/metrics.json）
 │  └─ benchmarks/            30 题 + 30 份金标注 + B0–B4 评测框架
 │
 └─ 演示与分发
@@ -355,11 +375,18 @@ EduEvidence/  （= 一个 Skill 包）
    ├─ docs/                  架构 / 方法论 / Benchmark / Demo / 复现指南
    ├─ install.sh             一键安装（本地 / 多 Agent Skill）+ 自检
    ├─ pyproject.toml         打包元数据（核心零第三方依赖）
-   └─ README(.en).md         双语说明
+   └─ README.md / README.zh-CN.md  双语说明
 ```
 
 > Skill 包设计原则：**运行所需的最小集是 `SKILL.md + skill/ + references/ + schemas/ + scripts/`**；`retrieval/`、`integrations/`、`visualization/` 是让 Skill 真正"可运行、可呈现"的执行层；`tests/`、`benchmarks/`、`examples/`、`docs/` 是可信度与上手保障，不影响 Skill 本体。
 
+### 分发
+
+两条发布通道共用同一份运行时 allowlist（`scripts/skill_payload.py`，宿主安装脚本也用这一份）：
+
+- **提交包** —— `bash packaging/make_upload.sh` 重建 `dist/eduevidence-submission/`（扁平 Skill 包 + `submission-manifest.json` + `UPLOAD-README.md`）；它会先重建五种风格的报告变体，缺少已构建的 `web/studio/index.html` 时直接中止。旧 `upload/` 目录是**冻结的废弃快照**，不得随包分发 —— 见 [`upload/DEPRECATED.md`](upload/DEPRECATED.md)。
+- **npm 包** —— `npm install -g eduevidence`，然后用 `eduevidence skill --list-hosts`（列出全部宿主与落点）或 `eduevidence skill --dry-run`（只预览，不写入）。在仓库目录中等价写法是 `node bin/eduevidence.js skill --list-hosts` / `--dry-run`。
+
 ### SCP / Platform Native Mode
 
 EduEvidence 可完全脱离 Agent MCP 独立运行（无需任何外部服务）：
@@ -442,7 +469,7 @@ pytest
 **已完成（仅 harness / 仿真，标注 SIMULATED，非实证）：**
 
 - [x] Benchmark v2 harness / simulation —— `benchmarks/results/` 是确定性仿真，证明评测框架可运行，**不是**真实模型性能（见上方 [Benchmark](#benchmark) 的 ⚠️ 说明）。
-- [x] Skill 核心与管线：9 步协议（Research Core 6 + Decision Extension 3）、13 个顶层 JSON Schema、确定性脚本、8 角色协议（原计划 Phase 0–6）。
+- [x] Skill 核心与管线：9 步协议（Research Core 6 + Decision Extension 3）、50 个版本化 JSON Schema（`schemas/**`，计数见 `scripts/generate_metrics.py`）、确定性脚本、8 角色协议（原计划 Phase 0–6）。
 - [x] Evidence-to-Action：适用性 / 四态决策 / 干预 / 评价设计。
 - [x] 产品 UI：单文件双语 HTML 报告 + 信息图 + 学术图（原计划 Phase 8）。
 

package/SKILL.md

@@ -2,7 +2,7 @@
 name: eduevidence
 description: "Decision-grade evidence synthesis for education and applied social science intervention decisions. Use when a user needs to determine whether, when, for whom, or how to adopt, pilot, evaluate, or revise a teaching method, curriculum change, AI tool, program, or policy intervention. Run an auditable evidence-to-decision workflow spanning systematic retrieval, counter-evidence challenge, methodological quality and evidence-certainty appraisal, provenance-traceable evidence graphs, applicability boundaries, evidence-grounded gap detection, preregistration-ready study or pilot design, empirical evidence re-injection, and decision revision."
 ---
-# EduEvidence 6.0 — Decision-Grade Evidence Engine
+# EduEvidence 6.3 — Decision-Grade Evidence Engine
 > **AI4SS Track | Art–Science Integration · General Intelligence**  
 > **From empirical questions to decision-grade evidence and evidence-to-action loops.**
 
@@ -28,6 +28,7 @@ Treat roles, models, Agent MCP, retrievers, scripts, and HTML reports as **execu
 ---
 
 ## 2. Route the Request to a Workflow
+Before selecting a primary workflow, run the one-shot two-round intake in `skill/workflows/intake.md` (research question → execution enhancements → depth; then enhancement mappings + Frame boundary confirmation). Persist non-question preferences via `scripts/intake/` to `~/.eduevidence/prefs.json`. After the wrap-up summary is confirmed once, continue unattended.
 Load exactly one primary workflow for the current task:
 - `skill/workflows/evidence-review.md` — use for evidence synthesis and decision appraisal from existing research.
 - `skill/workflows/decision-and-pilot.md` — use when the evidence must be converted into an actionable pilot or intervention plan.
@@ -109,7 +110,7 @@ Applicability → Intervene → Evaluate
 | 3 | **Extract** | `evidence.schema.json` | Extract findings, effect sizes, confidence intervals, sample sizes, outcomes, population characteristics, and study design information when available. |
 | 4 | **Challenge** | `evidence.schema.json` | Search explicitly for null findings, negative findings, contradictory evidence, alternative explanations, and confounders. |
 | 5 | **Audit** | `methodology.schema.json` | Appraise study quality and evidence certainty. Apply WWC 5.0 criteria where relevant to education-study design; use GRADE-informed certainty assessment at the body-of-evidence level where appropriate. |
-| 6 | **Adjudicate** | `verdict.schema.json` | Integrate evidence and emit a bounded decision: `ADOPT`, `PILOT`, `DO_NOT_ADOPT`, or `INSUFFICIENT`. Pass the Pre-Verdict Gate before finalizing. |
+| 6 | **Adjudicate** | `verdict.schema.json` | Integrate evidence and emit a bounded decision: `ADOPT`, `PILOT`, `REJECT`, or `INSUFFICIENT_EVIDENCE`. Pass the Pre-Verdict Gate before finalizing. |
 | 7 | **Applicability** | `references/applicability-policy.md` | State who the evidence applies to, in which contexts, for which outcomes, and under what conditions. |
 | 8 | **Intervene** | `intervention.schema.json` | Design the minimum viable intervention or pilot and define explicit success, failure, and stop conditions. |
 | 9 | **Evaluate** | `evaluation.schema.json` | Define baseline, post-intervention, retention/maintenance, transfer, and decision-update logic. |
@@ -138,7 +139,7 @@ Include, where relevant:
 ### Gate C — No Direct Learning Evidence, No ADOPT
 For education interventions, do not issue `ADOPT` based only on task speed, task completion, productivity, usability, preference, or subjective experience.
 Require direct evidence on learning, retention, independent transfer, or another explicitly decision-relevant outcome before `ADOPT` can be considered.
-If direct evidence is missing, bound the decision to `PILOT`, `INSUFFICIENT`, or `DO_NOT_ADOPT` as justified by the evidence.
+If direct evidence is missing, bound the decision to `PILOT`, `INSUFFICIENT_EVIDENCE`, or `REJECT` as justified by the evidence.
 ### Gate D — No False Precision
 Never invent missing uncertainty statistics.
 - If a confidence interval is not reported, do not fabricate one.
@@ -303,6 +304,14 @@ The example demonstrates:
 - Empirical evidence re-injection followed by decision revision.
 Do not generalize the flagship verdict to unrelated populations, courses, tools, or policy contexts.
 
+The four-state matrix (`engine.decision_policy.decision_outcome`) is the gate-enforced landing; each public case also records the adjudicator's own `recommended_action`. Recomputed from the pack's own `evidence.jsonl` + confidence label:
+
+- `examples/ai-coding-assistant-evidence/` - matrix `INSUFFICIENT_EVIDENCE` (`unresolved_conflict`: the decisive relations contain both `support_adoption` and `oppose_adoption`, so the conflict check fires first) / Moderate / 0.586. The pack records `PILOT`; primary evidence stops at task performance (no directness-2 learning outcome), so the decision is bounded — but the matrix does not let a conflicted relation set claim `PILOT`.
+- `examples/spaced-retrieval-practice/` - matrix `ADOPT` / High / 0.893. Retention and transfer, the primary outcomes, carry direct evidence at directness 2. The pack records `ADOPT`; this is the only public case where stated and matrix landings agree.
+- `examples/workplace-ai-assistant/` - matrix `INSUFFICIENT_EVIDENCE` with `downgrade_reason=None` / Moderate / 0.578, using the policy domain contract: all four decisive relations are `conditional`, and `conditional` is not a conflict relation (`CONFLICT_RELATIONS` = `{conflict, mixed}`), so no downgrade reason is recorded and, with no decisive `support_adoption`, Moderate confidence cannot reach `PILOT`. The pack records `PILOT`.
+
+A verdict never awards itself an action: the Pre-Verdict Gate re-derives primary-outcome directness from the evidence corpus and caps an unsupported `ADOPT` to `PILOT`. Never present a case as ADOPT without that derivation passing. Where the matrix landing is `INSUFFICIENT_EVIDENCE`, do not describe the case as having landed at `PILOT` — report both the recorded action and the matrix bound, and do not invent evidence to force a stronger landing.
+
 ---
 
 ## 16. Keep Presentation as a Projection Layer
@@ -391,7 +400,8 @@ python3 scripts/dashboard_server.py --port 8765
 # Search academic and current evidence
 python3 -m retrieval.search "AI coding assistants learning transfer"
 # Run the DID fixture / empirical analysis path
-python3 scripts/did_regression.py examples/full-research-cycle-fixture/data.csv
+python3 scripts/did_regression.py <your.csv>   # needs treat / post / outcome columns
+# column names are matched case-insensitively; see scripts/did_regression.py
 # Compute an effect size
 python3 scripts/effect_calculator.py \
   --mean1 78.5 --sd1 10.2 --n1 90 \
@@ -442,7 +452,7 @@ This appendix keeps the deterministic repository gates (skill lint / version / m
 - **EduEvidence Research Engine** — the runnable engine delivered as a Skill package (`engine/`, `retrieval/`, `scripts/`, `schemas/`).
 - **Shared Research Library** — verified external facts (`Source` / `Study` / `Finding` / `Audit`) may be reused across project snapshots; interpretive objects (`Claim` / `EvidenceLink` / `Applicability` / `Decision`) stay project-local.
 - **No new study design without evidence grounding** — every study or pilot must cite an explicit, evidence-supported `KnowledgeGap` identifier.
-- **Schema 版本口径**：schemas/ 顶层 13 个 = V1 契约（evidence.schema.json 当前修订 1.1、education-frame / verdict 等）；schemas/v2/ 17 个 = V2 契约（evidence-link / research-intent / study / graph-revision / project 等）。文档与代理配置一律以此口径命名。
+- **Schema 版本口径**：schemas/ 顶层 15 个 = V1 契约（evidence.schema.json 当前修订 1.1、education-frame / verdict / report-spec 等）；schemas/v2/ 18 个 = V2 契约（evidence-link / research-intent / intake / study / graph-revision / project 等）；另有 v3 3 个、v4 4 个、vNext 10 个，递归合计 50 个（计数以 `scripts/generate_metrics.py` 为准）。文档与代理配置一律以此口径命名。
 - Five baked report themes (presentation systems, not science):
 
     ├─ Claude Research      [Light]