eduevidence 6.0.0 → 6.3.0

package/scripts/lint_file_layers.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""scripts/lint_file_layers.py — file-layer hard gate.
+
+Scans engine/ scripts/ integrations/ skill/ visualization/eduevidence-report/scripts/
+for *.py *.js *.ts and enforces:
+
+  * single file > 300 lines → ERROR (monument / legacy → WARNING only)
+  * new / moved files must be ≤ 300 lines (not eligible for whitelists)
+  * new / moved files must be ≤ 300 lines (not eligible for the whitelist)
+
+Monument whitelist = build_report.py, orchestrator.py, agent_mcp.py,
+pre_verdict_gate.py, living.py, evidence_graph.py. Anything else over the
+budget is an ERROR unless monument/legacy WARNING. Exit 1 on any ERROR.
+
+Usage:
+    python3 scripts/lint_file_layers.py
+Exit code 1 when any ERROR.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+MAX_LINES = 300
+
+SCAN_ROOTS = (
+    "engine",
+    "scripts",
+    "integrations",
+    "skill",
+    "visualization/eduevidence-report/scripts",
+)
+
+# Historical monument whitelist — WARNING only (not ERROR).
+# ONLY these six pre-split giants are grandfathered. New or moved files
+# MUST NOT be added here — keep them ≤ MAX_LINES instead.
+MONUMENT_BASENAMES = {
+    "build_report.py",
+    "orchestrator.py",
+    "agent_mcp.py",
+    "pre_verdict_gate.py",
+    "living.py",
+    "evidence_graph.py",
+}
+
+# Pre-existing large files (before the layering gate). WARNING only.
+# New/moved files must never be added here — keep them ≤ MAX_LINES.
+LEGACY_LARGE_BASENAMES = {
+    "analysis.py", "core.py", "runner.py", "graph_store.py", "library_builtin.py",
+    "meta_analysis.py", "migration.py", "orchestration.py", "pilot.py",
+    "studio_read_model.py", "tribunal.py", "benchmark_evaluator.py",
+    "benchmark_judge.py", "benchmark_v2.py", "benchmark_v3.py",
+    "build_esl_artifacts.py", "build_evidence_library.py", "build_result.py",
+    "check_protocol_alignment.py", "dashboard_server.py",
+    "enrich_projects_human_and_lieflat.py", "generate_new_projects.py",
+    "render_report_html.py", "research_auto_cli.py", "run_workspace.py",
+    "test_adversarial_empirical.py", "build_figures.py", "charts_data.py",
+    "lieflat_engine.py", "zh_labels.py", "library.py",
+}
+
+EXTS = {".py", ".js", ".ts"}
+SKIP_DIRS = {"__pycache__", "node_modules", ".git", ".venv", "venv"}
+
+
+def _iter_sources() -> list[Path]:
+    found: list[Path] = []
+    for root_name in SCAN_ROOTS:
+        root = ROOT / root_name
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*")):
+            if not path.is_file() or path.suffix not in EXTS:
+                continue
+            if any(part in SKIP_DIRS for part in path.parts):
+                continue
+            found.append(path)
+    return found
+
+
+def check_file_layers() -> tuple[list[str], list[str]]:
+    """Return (errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    for path in _iter_sources():
+        rel = path.relative_to(ROOT).as_posix()
+        try:
+            n = sum(1 for _ in path.open(encoding="utf-8", errors="replace"))
+        except OSError as exc:
+            errors.append(f"{rel}: unreadable ({exc})")
+            continue
+        if n <= MAX_LINES:
+            continue
+        msg = f"{rel}: {n} lines > {MAX_LINES}"
+        if path.name in MONUMENT_BASENAMES:
+            warnings.append(
+                f"{msg} (monument whitelist — WARNING only; split when touched)")
+        elif path.name in LEGACY_LARGE_BASENAMES:
+            warnings.append(
+                f"{msg} (legacy large file — WARNING only; split when touched)")
+        else:
+            errors.append(
+                f"{msg} (not on monument whitelist; new/moved must be ≤ {MAX_LINES})")
+    return errors, warnings
+
+
+def main() -> int:
+    print("[*] Running file-layer hard gate "
+          f"(max {MAX_LINES} lines; monuments+legacy WARNING only: "
+          f"{', '.join(sorted(MONUMENT_BASENAMES))})...")
+    errors, warnings = check_file_layers()
+    for w in warnings:
+        print(f"    ! {w}")
+    if errors:
+        print(f"[-] File-layer lint FAILED with {len(errors)} error(s):",
+              file=sys.stderr)
+        for e in errors:
+            print(f"    • {e}", file=sys.stderr)
+        return 1
+    print(f"[+] File-layer lint PASSED: {len(warnings)} monument warning(s), 0 error(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/orchestrator.py

@@ -60,6 +60,13 @@ from pre_verdict_gate import apply_enforcement, evaluate_workspace  # noqa: E402
 from engine.versions import ENGINE_VERSION  # noqa: E402
 from engine.log import enable_console_logging, get_log  # noqa: E402
 
+# One-shot two-round intake + prefs (scripts/intake/). Soft-import so the
+# orchestrator still starts if intake is stripped from a minimal package.
+try:
+    from intake import hooks as _intake_hooks  # noqa: E402
+except Exception:  # pragma: no cover - optional adapter
+    _intake_hooks = None
+
 log = get_log("orchestrator")
 
 DEPTH_ALIASES = {"quick": "S", "standard": "M", "deep": "L"}
@@ -67,13 +74,17 @@ DEPTHS = ("S", "M", "L")
 
 #: Stage -> primary artifact + schema gate + whether it is locally executable.
 STAGE_SPEC: dict[str, dict[str, Any]] = {
-    "frame":     {"artifact": "frame.json",       "schema": "education-frame.schema.json", "jsonl": False, "local": False},
+    # The frame contract belongs to the run's domain; the placeholder is
+    # resolved by frame_schema_for() below (education-frame.schema.json
+    # for education, domains/policy/frame.schema.json for policy, and so
+    # on for any domain registered under domains/).
+    "frame":     {"artifact": "frame.json",       "schema": "@domain_frame", "jsonl": False, "local": False},
     "retrieve":  {"artifact": "sources.jsonl",    "schema": "source.schema.json",          "jsonl": True,  "local": False},
     "extract":   {"artifact": "evidence.jsonl",   "schema": "evidence.schema.json",        "jsonl": True,  "local": False},
-    "challenge": {"artifact": "skeptic.json",     "schema": None,                          "jsonl": False, "local": False},
+    "challenge": {"artifact": "skeptic.json",     "schema": "skeptic.schema.json",       "jsonl": False, "local": False},
     "audit":     {"artifact": "methodology.json", "schema": "methodology.schema.json",     "jsonl": False, "local": False},
     "adjudicate": {"artifact": "final_verdict.json", "schema": "verdict.schema.json",      "jsonl": False, "local": True},
-    "applicability": {"artifact": "applicability.json", "schema": None, "jsonl": False, "local": False},
+    "applicability": {"artifact": "applicability.json", "schema": "applicability.schema.json", "jsonl": False, "local": False},
     "intervene": {"artifact": "intervention.json", "schema": "intervention.schema.json",   "jsonl": False, "local": False},
     "evaluate":  {"artifact": "evaluation.json",  "schema": "evaluation.schema.json",      "jsonl": False, "local": False},
     "projection": {"artifact": "result.json",      "schema": "report-result.schema.json",   "jsonl": False, "local": True},
@@ -187,11 +198,15 @@ def init_run(
     approve_agent_mcp: bool = False,
     scp_available: bool | None = None,
     approval_record: dict | None = None,
+    domain: str = "education",
 ) -> RunWorkspace:
     """Create the run workspace + manifest + planning artifacts (Phase 11-13)."""
     depth = DEPTH_ALIASES.get(depth, depth)
     if depth not in DEPTHS:
         raise ValueError(f"unknown depth {depth!r}; use quick/standard/deep or S/M/L")
+    # Validate the domain up front: every later stage gate reads it from the
+    # manifest, so an unknown id must fail here rather than mid-run.
+    domain_frame_schema(domain)
 
     try:
         from integrations.agent_mcp import detect_agent_mcp
@@ -214,6 +229,7 @@ def init_run(
         agent_mcp_available=agent_available,
         agent_mcp_approved=approve_agent_mcp,
         root=ROOT,
+        domain=domain,
     )
     ws.save_manifest(manifest)
 
@@ -264,7 +280,7 @@ def init_run(
         "run_id": run_id,
         "execution_mode": agent_mode,
         "routing": {
-            "education-planner": "strong/reasoning",
+            "research-planner": "strong/reasoning",
             "evidence-retriever": "fast/low-cost",
             "evidence-analyst": "strong/structured",
             "skeptic": "independent/reasoning",
@@ -319,11 +335,45 @@ def _load_artifact(ws: RunWorkspace, artifact: str) -> list[dict[str, Any]]:
     return [data] if data else []
 
 
+
+#: Placeholder replaced by the run's registered frame schema.
+DOMAIN_FRAME_SENTINEL = "@domain_frame"
+
+
+def domain_frame_schema(domain: str) -> str:
+    """Registered frame schema for a domain, relative to the repository root.
+
+    Raises ValueError for an unknown domain so a typo fails loudly instead of
+    silently validating against the education contract.
+    """
+    try:
+        from engine.evidencecore import load_domain
+
+        entry = load_domain(domain)
+    except KeyError as exc:
+        raise ValueError(str(exc)) from exc
+    return str(entry["frame_schema"])  # type: ignore[return-value]
+
+
+def frame_schema_for(ws: "RunWorkspace") -> str:
+    """The frame schema this run must satisfy (from its manifest domain)."""
+    domain = str(ws.load_manifest().get("domain") or "education")
+    return domain_frame_schema(domain)
+
+
 def schema_gate(ws: RunWorkspace, stage: str) -> dict[str, Any]:
     """Validate a stage's primary artifact against its schema. Never raises."""
     spec = STAGE_SPEC[stage]
     artifact = spec["artifact"]
     schema_name = spec["schema"]
+    if schema_name == DOMAIN_FRAME_SENTINEL:
+        # The frame contract is per-domain; resolve it from the run manifest.
+        try:
+            schema_name = frame_schema_for(ws)
+        except ValueError as exc:
+            return {"passed": False, "stage": stage, "artifact": artifact,
+                    "schema": DOMAIN_FRAME_SENTINEL,
+                    "issues": [f"unknown run domain: {exc}"]}
     if schema_name is None:  # lightweight parseability contract
         data = load_json(ws.path / artifact)
         ok = bool(data) and isinstance(data, dict)
@@ -333,13 +383,19 @@ def schema_gate(ws: RunWorkspace, stage: str) -> dict[str, Any]:
     from validate_schema import SchemaError, Validator
 
     schemas_dir = ROOT / "schemas"
-    if not (schemas_dir / schema_name).is_file():
-        share_dir = Path(sys.prefix) / "share" / "eduevidence" / "schemas"
-        if (share_dir / schema_name).is_file():
-            schemas_dir = share_dir
+    schema_path = schemas_dir / schema_name
+    if not schema_path.is_file():
+        # A domain may own its frame schema outside schemas/ (policy does).
+        candidate = ROOT / schema_name
+        if candidate.is_file():
+            schema_path = candidate
+        else:
+            share_candidates = (Path(sys.prefix) / "share" / "eduevidence" / schema_name,
+                                Path(sys.prefix) / "share" / "eduevidence" / "schemas" / schema_name)
+            schema_path = next((c for c in share_candidates if c.is_file()), schema_path)
 
     try:
-        schema = json.loads((schemas_dir / schema_name).read_text(encoding="utf-8"))
+        schema = json.loads(schema_path.read_text(encoding="utf-8"))
     except OSError:
         return {"passed": False, "stage": stage, "artifact": artifact,
                 "schema": schema_name, "issues": [f"schema file {schema_name} not found"]}
@@ -398,22 +454,52 @@ def derive_sources_from_evidence(evidence: list[dict[str, Any]]) -> list[dict[st
     return list(seen.values())
 
 
+#: The nine checks the skeptic contract requires (skill/task-briefs/challenge.md).
+SKEPTIC_CHECKS = (
+    "1_null_result", "2_negative_result", "3_contradictory_evidence",
+    "4_alternative_explanation", "5_measurement_mismatch", "6_sampling_bias",
+    "7_novelty_effect", "8_ai_dependency", "9_scope_overreach",
+)
+
+
 def derive_skeptic_from_evidence(evidence: list[dict[str, Any]]) -> dict[str, Any]:
     """Deterministic skeptic summary derived from evidence directions (demo/test mode).
 
     Records what the corpus itself contains (contradictions / null results /
-    confounders); it never invents counter-evidence.
+    confounders); it never invents counter-evidence. Field names follow the
+    challenge brief and the skeptic role prompt so the Pre-Verdict Gate reads
+    the same keys this writes.
     """
-    contradictions = [e.get("evidence_id") for e in evidence if e.get("direction") == "contradict"]
-    null_results = [e.get("evidence_id") for e in evidence if e.get("direction") == "neutral"]
+    contradictions = [e.get("evidence_id") for e in evidence
+                      if (e.get("relation_to_claim") or e.get("direction")) == "contradict"]
+    null_results = [e.get("evidence_id") for e in evidence
+                    if e.get("effect_direction") == "null"]
     confounders = sorted({c for e in evidence for c in (e.get("confounders", []) or [])})
+
+    status_for = {
+        "1_null_result": "found" if null_results else "not_found",
+        "2_negative_result": "found" if any(
+            e.get("effect_direction") == "negative" for e in evidence) else "not_found",
+        "3_contradictory_evidence": "found" if contradictions else "not_found",
+        "4_alternative_explanation": "found" if confounders else "not_found",
+    }
+    findings = []
+    for check in SKEPTIC_CHECKS:
+        findings.append({
+            "check": check,
+            "status": status_for.get(check, "not_found"),
+            "detail": "derived from the evidence corpus in demo/test mode",
+            "related_evidence_ids": (contradictions if "contradict" in check
+                                     else null_results if "null" in check else []),
+        })
     return {
         "search_performed": True,
         "method": "derived from evidence corpus directions (demo/test mode)",
-        "contradictions": contradictions,
-        "null_results": null_results,
-        "confounders": confounders,
-        "no_contradictory_evidence_found": not contradictions,
+        "skeptic_findings": findings,
+        "contradictory_evidence_found": bool(contradictions),
+        "no_contradictory_evidence_statement": (
+            "" if contradictions else "NO CONTRADICTORY EVIDENCE FOUND"),
+        "threats_to_validity": confounders,
     }
 
 
@@ -422,7 +508,13 @@ def _cap_verdict(gate: dict[str, Any], raw_verdict: dict[str, Any],
     """Build final_verdict.json: deterministic confidence + gate enforcement."""
     final = copy.deepcopy(raw_verdict)
     final["raw_model_confidence"] = raw_verdict.get("confidence")
-    final["raw_model_confidence_breakdown"] = raw_verdict.get("confidence_breakdown")
+    # The schema types this as an object; a model verdict without the field
+    # produced None here, which made the written file schema-invalid and the
+    # gate fail on data the pipeline had just produced.
+    final["raw_model_confidence_breakdown"] = (
+        raw_verdict.get("confidence_breakdown")
+        if isinstance(raw_verdict.get("confidence_breakdown"), dict)
+        else {})
     final["confidence"] = computed["confidence"]
     final["confidence_score"] = computed["confidence_breakdown"].get("score")
     final["confidence_policy_version"] = computed["confidence_policy_version"]
@@ -461,6 +553,10 @@ def _run_adjudicate(ws: RunWorkspace, question: str,
         json.dumps(final, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
 
     post = evaluate_workspace(ws.path, require_final=True)
+    if not post.get("passed") or post.get("critical_failures"):
+        final = apply_enforcement(final, post)
+        (ws.path / "final_verdict.json").write_text(
+            json.dumps(final, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
     gate_report = {"run_id": ws.run_id, "stage": "adjudicate",
                    "pre": {"passed": pre["passed"], "max_confidence": pre["max_confidence"],
                            "critical_failures": pre["critical_failures"]},
@@ -486,8 +582,7 @@ def _run_adjudicate(ws: RunWorkspace, question: str,
 
 def _assemble_result(ws: RunWorkspace, manifest: dict[str, Any]) -> dict[str, Any]:
     """Assemble result.json from workspace artifacts (decision=final_verdict.json)."""
-    from build_result import (NOT_CAPTURED_USAGE, OUTCOME_ORDER,
-                              aggregate_outcomes, build_claims,
+    from build_result import (NOT_CAPTURED_USAGE, aggregate_outcomes, build_claims,
                               build_outcome_mapping, derive_provenance)
 
     frame = load_json(ws.path / "frame.json")
@@ -530,7 +625,8 @@ def _assemble_result(ws: RunWorkspace, manifest: dict[str, Any]) -> dict[str, An
         "methodology_reviews": methodology_list,
         "conflicts": [{"reason_for_disagreement": verdict.get("reason_for_disagreement", "")}]
         if verdict.get("reason_for_disagreement") else [],
-        "applicability": verdict.get("applicability", {}),
+        "applicability": (load_json(ws.path / "applicability.json")
+                          or verdict.get("applicability", {})),
         "intervention": intervention,
         "evaluation": evaluation,
         "benchmark": {},
@@ -696,10 +792,16 @@ def _seed_from_demo(ws: RunWorkspace, stage: str, demo_pack: Path) -> dict[str,
             value = verdict.get("applicability") if isinstance(verdict, dict) else None
             # A demo can only carry the decision's existing applicability
             # boundary; absence remains explicit rather than inferred.
-            payload = value if isinstance(value, dict) and value else {
-                "status": "NOT_CAPTURED",
-                "reason": "demo pack does not provide an applicability assessment",
-            }
+            # The derived boundary is tagged ASSESSED so it satisfies the
+            # applicability contract instead of being an unlabelled dict.
+            if isinstance(value, dict) and value:
+                payload = {"status": "ASSESSED"}
+                payload.update(value)
+            else:
+                payload = {
+                    "status": "NOT_CAPTURED",
+                    "reason": "demo pack does not provide an applicability assessment",
+                }
             (ws.path / "applicability.json").write_text(
                 json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
         return {"seeded": True, "detail": "applicability.json seeded from decision boundary (demo)"}
@@ -884,12 +986,45 @@ def load_global_approval() -> dict | None:
 
 
 def _cmd_run(args: argparse.Namespace) -> int:
-    approve = args.approve_agent_mcp or interactive_agent_mcp_setup(args.approve_agent_mcp)
-    approval_record = None
-    if approve:
-        approval_record = load_global_approval()
-    ws = init_run(Path(args.runs_dir), args.question, depth=args.depth, run_id=args.run_id,
-                  approve_agent_mcp=approve, approval_record=approval_record)
+    """Create a run workspace. Delegates intake/open to scripts/intake/hooks.py."""
+    assume_yes = bool(getattr(args, "yes", False))
+    domain = getattr(args, "domain", "education")
+    enhancements = list(getattr(args, "enhancement", None) or []) or None
+    intake_record: dict[str, Any] | None = None
+
+    if _intake_hooks is not None:
+        ctx = _intake_hooks.prepare_run(
+            question=args.question,
+            depth=getattr(args, "depth", None),
+            enhancements=enhancements,
+            domain=domain,
+            assume_yes=assume_yes,
+        )
+        if ctx.get("error"):
+            print(f"ERROR: intake failed: {ctx['error']}", file=sys.stderr)
+            return 2
+        question, depth_arg = ctx["question"], ctx["depth"]
+        enhancements, intake_record = ctx["enhancements"], ctx["intake_record"]
+        wants_mcp = ctx["wants_mcp"]
+    else:
+        question = args.question
+        depth_arg = DEPTH_ALIASES.get(getattr(args, "depth", None) or "M",
+                                     getattr(args, "depth", None) or "M")
+        if depth_arg not in DEPTHS:
+            depth_arg = "M"
+        wants_mcp = bool(enhancements and "agent_mcp" in enhancements
+                         and "none" not in enhancements)
+
+    approve = bool(args.approve_agent_mcp)
+    if wants_mcp and not assume_yes and sys.stdin.isatty():
+        approve = approve or interactive_agent_mcp_setup(approve)
+    approval_record = load_global_approval() if approve else None
+
+    ws = init_run(Path(args.runs_dir), question, depth=depth_arg, run_id=args.run_id,
+                  approve_agent_mcp=approve, approval_record=approval_record,
+                  domain=domain)
+    if _intake_hooks is not None:
+        _intake_hooks.write_intake_artifact(ws.path, intake_record)
     print(f"workspace created: {ws.path}")
     print(f"manifest: {json.dumps(ws.load_manifest(), ensure_ascii=False, indent=2)}")
     if args.dry_run:
@@ -897,9 +1032,9 @@ def _cmd_run(args: argparse.Namespace) -> int:
         return 0
     summary = advance(ws, demo_pack=args.demo_pack)
     print(json.dumps(summary, ensure_ascii=False, indent=2))
-    if summary["failures"]:
-        return 1
-    return 0
+    if _intake_hooks is not None:
+        _intake_hooks.after_run(ws.path, intake_record=intake_record, summary=summary)
+    return 1 if summary["failures"] else 0
 
 
 def _print_status(ws) -> None:
@@ -994,7 +1129,7 @@ def _cmd_domain(args) -> int:
 
 def _cmd_living(args) -> int:
     from engine.project import ProjectWorkspace
-    from engine.living import create_subscription, refresh, set_subscription_status
+    from engine.living import create_subscription, refresh
     home = _home(args)
     ws = ProjectWorkspace.open(home, args.project)
     if args.action == "subscribe":
@@ -1014,7 +1149,6 @@ def _cmd_living(args) -> int:
         print(drift.get("summary", ""))
         return 0
     if args.action == "status":
-        from pathlib import Path as _P
         import json as _json
         p = ws.path / "living" / "subscriptions" / f"{args.subscription}.json"
         if not p.is_file():
@@ -1226,7 +1360,7 @@ def _cmd_study(args) -> int:
             print(e, file=sys.stderr)
         return 1
     from engine.study_design import save_study_design
-    path = save_study_design(ws, design)
+    save_study_design(ws, design)   # persists study-designs/<id>.json
     print(design["design_id"])
     return 0
 
@@ -1304,7 +1438,8 @@ def _cmd_migrate(args) -> int:
 
 def _cmd_dashboard(args) -> int:
     from dashboard_server import run_dashboard_server
-    run_dashboard_server(host=args.host, port=args.port)
+    run_dashboard_server(host=args.host, port=args.port,
+                         open_browser=bool(getattr(args, "open", False)))
     return 0
 
 
@@ -1358,14 +1493,24 @@ def main(argv: list[str] | None = None) -> int:
     sub = parser.add_subparsers(dest="command", required=True)
 
     p_run = sub.add_parser("run", help="create a run workspace and advance stages")
-    p_run.add_argument("--question", required=True, help="education question to research")
-    p_run.add_argument("--depth", default="M", choices=["quick", "standard", "deep", "S", "M", "L"],
-                       help="complexity depth (default: standard/M)")
+    p_run.add_argument("--question", required=True, help="research question to investigate")
+    p_run.add_argument("--domain", default="education", metavar="ID",
+                       help="registered research domain (default: education; "
+                            "see `domain list`)")
+    p_run.add_argument("--depth", default=None,
+                       choices=["quick", "standard", "deep", "S", "M", "L", "auto"],
+                       help="complexity depth (S/M/L/auto or quick/standard/deep; "
+                            "default: intake/prefs auto guideline)")
     p_run.add_argument("--run-id", default=None, help="explicit run id (default: timestamp)")
     p_run.add_argument("--demo-pack", default=None, type=Path,
                        help="seed external stages from an example pack (demo/test mode)")
     p_run.add_argument("--approve-agent-mcp", action="store_true",
                        help="record agent-mcp approval in the manifest")
+    p_run.add_argument("--yes", action="store_true",
+                       help="skip the two-round intake prompts; use prefs + flags unattended")
+    p_run.add_argument("--enhancement", action="append", default=None,
+                       choices=["agent_mcp", "jev", "semdecide", "none"],
+                       help="execution enhancement (repeatable; used by intake)")
     p_run.add_argument("--dry-run", action="store_true", help="initialize only, do not advance")
     p_run.add_argument("--runs-dir", default=os.environ.get("EDUEVIDENCE_RUNS_DIR", str(ROOT / "runs")),
                        help="directory holding run workspaces (default: <repo>/runs)")
@@ -1549,6 +1694,8 @@ def main(argv: list[str] | None = None) -> int:
     p_dash = sub.add_parser("dashboard", help="start local research & token dashboard")
     p_dash.add_argument("--host", default="127.0.0.1")
     p_dash.add_argument("--port", type=int, default=8765)
+    p_dash.add_argument("--open", action="store_true",
+                        help="open the Studio URL in the system browser once the server is up")
     p_dash.set_defaults(func=_cmd_dashboard)
 
     p_srch = sub.add_parser("search", help="multi-channel hybrid search")