claude-turing 4.0.0 → 4.2.0

package/templates/scripts/generate_onboarding.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""Project onboarding generator for new collaborators.
+
+Reads config, experiments, annotations, and hypotheses to produce a
+structured walkthrough: task description, what's been tried (grouped
+by family), key decisions, where heading, how to start.
+
+Usage:
+    python scripts/generate_onboarding.py --audience researcher --depth full
+    python scripts/generate_onboarding.py --audience stakeholder --depth brief --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+from scripts.turing_io import load_config, load_experiments, load_hypotheses
+
+VALID_AUDIENCES = ["researcher", "engineer", "stakeholder"]
+VALID_DEPTHS = ["brief", "full"]
+DEFAULT_LOG = "experiments/log.jsonl"
+DEFAULT_ANNOTATIONS = "experiments/annotations.yaml"
+DEFAULT_HYPOTHESES = "hypotheses.yaml"
+
+
+def _load_yaml_list(path: str) -> list[dict]:
+    p = Path(path)
+    if not p.exists() or p.stat().st_size == 0:
+        return []
+    with open(p) as f:
+        data = yaml.safe_load(f)
+    return data if isinstance(data, list) else []
+
+
+def _load_yaml_dir(directory: str, glob: str) -> list[dict]:
+    path = Path(directory)
+    if not path.exists():
+        return []
+    items = []
+    for f in sorted(path.glob(glob)):
+        try:
+            with open(f) as fh:
+                d = yaml.safe_load(fh)
+                if d and isinstance(d, dict):
+                    items.append(d)
+        except (yaml.YAMLError, OSError):
+            continue
+    return items
+
+
+def _family_summary(exps: list[dict], metric: str, lower_is_better: bool) -> dict:
+    total = len(exps)
+    kept = [e for e in exps if e.get("status") == "kept"]
+    best_val, best_id = None, None
+    for e in kept:
+        val = e.get("metrics", {}).get(metric)
+        if val is None:
+            continue
+        if best_val is None or (lower_is_better and val < best_val) or (not lower_is_better and val > best_val):
+            best_val, best_id = val, e.get("experiment_id")
+    return {"total": total, "kept": len(kept), "keep_rate": round(len(kept) / total, 2) if total else 0,
+            "best_metric": best_val, "best_experiment": best_id}
+
+
+def _find_best(experiments: list[dict], metric: str, lower_is_better: bool) -> dict | None:
+    best, best_val = None, float("inf") if lower_is_better else float("-inf")
+    for e in experiments:
+        if e.get("status") != "kept":
+            continue
+        val = e.get("metrics", {}).get(metric)
+        if val is not None and ((lower_is_better and val < best_val) or (not lower_is_better and val > best_val)):
+            best_val, best = val, e
+    return best
+
+
+def _extract_decisions(packets: list[dict], annotations: list[dict]) -> list[dict]:
+    decisions = []
+    for pkt in packets:
+        if pkt.get("action") in ("promote", "abandon", "replicate"):
+            decisions.append({"type": "decision", "experiment": pkt.get("experiment_id", "?"),
+                              "action": pkt["action"], "reason": pkt.get("reason", ""),
+                              "date": pkt.get("timestamp", "")[:10]})
+    key_tags = {"decision", "key", "important", "milestone"}
+    for ann in annotations:
+        if set(t.lower() for t in ann.get("tags", [])) & key_tags:
+            decisions.append({"type": "annotation", "experiment": ann.get("experiment_id", "?"),
+                              "text": ann.get("text", ""), "date": ann.get("date", "")[:10]})
+    decisions.sort(key=lambda d: d.get("date", ""), reverse=True)
+    return decisions
+
+
+def _project_direction(hypotheses: list[dict], experiments: list[dict]) -> dict:
+    queued = [h for h in hypotheses if h.get("status") == "queued"]
+    promising = [h for h in hypotheses if h.get("status") == "promising"]
+    recent = experiments[-5:] if len(experiments) >= 5 else experiments
+    recent_kept = sum(1 for e in recent if e.get("status") == "kept")
+    if not experiments:
+        phase = "not_started"
+    elif not queued and not promising:
+        phase = "exhausted"
+    elif recent_kept == 0 and len(recent) >= 3:
+        phase = "plateaued"
+    elif promising:
+        phase = "promising_leads"
+    else:
+        phase = "active_exploration"
+    return {"phase": phase, "queued": queued[:5], "promising": promising[:3],
+            "n_queued": len(queued), "n_promising": len(promising)}
+
+
+def format_onboarding_report(config, experiments, families, best, decisions,
+                             direction, annotations, seeds, audience, depth,
+                             metric, lower_is_better) -> str:
+    d = "lower" if lower_is_better else "higher"
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    L = ["# Project Onboarding", "", f"*Generated {now} for audience: {audience}*", "", "---", "",
+         "## 1. What This Project Does", ""]
+    data_cfg, eval_cfg = config.get("data", {}), config.get("evaluation", {})
+    L.append(f"**Task:** {config.get('task_description', 'N/A')}")
+    L.append(f"**Dataset:** {data_cfg.get('source', 'unknown')}")
+    L.append(f"**Primary metric:** `{metric}` ({d} is better)")
+    extra = [m for m in eval_cfg.get("metrics", []) if m != metric]
+    if extra:
+        L.append(f"**Additional metrics:** {', '.join(f'`{m}`' for m in extra)}")
+    if depth == "full" and audience != "stakeholder":
+        sr = data_cfg.get("split_ratios", {})
+        if sr:
+            L.append(f"**Data splits:** {' / '.join(f'{k}: {int(v*100)}%' for k, v in sr.items())}")
+        if data_cfg.get("target_column"):
+            L.append(f"**Target column:** `{data_cfg['target_column']}`")
+    L.extend(["", "## 2. What's Been Tried", ""])
+    total, kept_n = len(experiments), sum(1 for e in experiments if e.get("status") == "kept")
+    if total == 0:
+        L.append("No experiments yet. Start with `/turing:train`.")
+    else:
+        L.append(f"**{total} experiments**, **{kept_n} kept** ({round(kept_n/total*100)}% keep rate).")
+        L.append("")
+        if best:
+            ms = ", ".join(f"{k}={v:.4f}" if isinstance(v, float) else f"{k}={v}"
+                           for k, v in best.get("metrics", {}).items())
+            L.extend([f"**Champion:** `{best.get('experiment_id','?')}` "
+                       f"({best.get('config',{}).get('model_type','?')}) — {ms}", ""])
+        L.extend(["### By Family", "", "| Family | Exps | Kept | Best | Status |",
+                   "|--------|------|------|------|--------|"])
+        for name, s in sorted(families.items()):
+            bv = f"{s['best_metric']:.4f}" if s["best_metric"] is not None else "---"
+            st = "Exhausted" if s["keep_rate"] == 0 and s["total"] >= 3 else (
+                 "Productive" if s["keep_rate"] >= 0.5 else "Mixed")
+            L.append(f"| {name} | {s['total']} | {s['kept']} | {bv} | {st} |")
+        L.append("")
+        if depth == "full" and audience in ("researcher", "engineer"):
+            for name, s in sorted(families.items()):
+                if not s["total"]:
+                    continue
+                L.append(f"#### {name}")
+                if s["best_experiment"]:
+                    L.append(f"- Best: `{s['best_experiment']}` ({metric}={s['best_metric']:.4f})")
+                L.append(f"- {s['kept']}/{s['total']} kept ({s['keep_rate']:.0%})")
+                fam_ids = {e.get("experiment_id") for e in experiments if (e.get("family") or "untagged") == name}
+                notes = [a for a in annotations if a.get("experiment_id") in fam_ids]
+                for n in notes[:3]:
+                    L.append(f"  - {n.get('text','')[:80]}")
+                L.append("")
+    L.extend(["## 3. Key Decisions", ""])
+    if not decisions:
+        L.append("No major decisions recorded yet.")
+    else:
+        lim = 5 if depth == "brief" else 15
+        for dec in decisions[:lim]:
+            if dec["type"] == "decision":
+                L.append(f"- **{dec['date']}** `{dec['experiment']}`: **{dec['action']}** — {dec['reason']}")
+            else:
+                L.append(f"- **{dec['date']}** `{dec['experiment']}`: {dec['text'][:100]}")
+        if len(decisions) > lim:
+            L.append(f"  *...and {len(decisions)-lim} more*")
+    L.extend(["", "## 4. Where We're Heading", ""])
+    phases = {"not_started": "Project has not started experiments yet.",
+              "exhausted": "All hypotheses tested. Need fresh ideas.",
+              "plateaued": "Recent experiments not improving. Consider pivoting.",
+              "promising_leads": "Promising directions identified and being pursued.",
+              "active_exploration": "Actively exploring hypothesis space."}
+    L.extend([phases.get(direction["phase"], "Unknown phase."), ""])
+    if direction["n_queued"]:
+        L.append(f"**{direction['n_queued']} hypotheses queued:**")
+        for h in direction["queued"]:
+            p = " (HIGH)" if h.get("priority") == "high" else ""
+            L.append(f"- {h.get('id','?')}: {h.get('description','?')}{p}")
+        L.append("")
+    if direction["n_promising"]:
+        L.append(f"**{direction['n_promising']} promising lead(s):**")
+        for h in direction["promising"]:
+            L.append(f"- {h.get('id','?')}: {h.get('description','?')}")
+        L.append("")
+    sensitive = [s for s in seeds if s.get("seed_sensitive")]
+    if sensitive and audience != "stakeholder":
+        L.append("**Seed sensitivity warnings:**")
+        for s in sensitive:
+            L.append(f"- `{s.get('experiment_id','?')}`: CV={s.get('cv_percent',0):.1f}%")
+        L.append("")
+    L.extend(["## 5. How to Get Started", ""])
+    cmds = {"researcher": [
+        "1. Read `config.yaml` for task and evaluation setup",
+        "2. `/turing:status` — current experiment state",
+        "3. `/turing:brief` — full research intelligence report",
+        "4. Review `hypotheses.yaml` for queued ideas",
+        "5. `/turing:try \"your hypothesis\"` — inject ideas",
+        "6. `/turing:train` — run next experiment",
+    ], "engineer": [
+        "1. `pip install -r requirements.txt`",
+        "2. Review `config.yaml` for data paths",
+        "3. `/turing:status` — where things stand",
+        "4. Check `train.py` for current model",
+        "5. `/turing:train` — execute experiments",
+    ], "stakeholder": [
+        "1. `/turing:brief` — high-level summary",
+        "2. Check champion performance above",
+        "3. Review 'Where We're Heading' for next steps",
+    ]}
+    L.extend(cmds.get(audience, []))
+    L.extend(["", "---", f"*Generated by `/turing:onboard` — {audience}, {depth}*"])
+    return "\n".join(L)
+
+
+def save_onboarding_report(content: str, path: str = "ONBOARDING.md") -> Path:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content)
+    return p
+
+
+def generate_onboarding(config_path="config.yaml", log_path=DEFAULT_LOG,
+                         hypotheses_path=DEFAULT_HYPOTHESES,
+                         annotations_path=DEFAULT_ANNOTATIONS,
+                         audience="researcher", depth="full") -> dict:
+    """Generate full onboarding report. Returns dict with report and metadata."""
+    config = load_config(config_path)
+    metric = config.get("evaluation", {}).get("primary_metric", "accuracy")
+    lower = config.get("evaluation", {}).get("lower_is_better", False)
+    experiments = load_experiments(log_path)
+    hypotheses = load_hypotheses(hypotheses_path)
+    annotations = _load_yaml_list(annotations_path)
+    packets = _load_yaml_dir("experiments/decisions", "*.yaml")
+    seeds = _load_yaml_dir("experiments/seed_studies", "*-seeds.yaml")
+    fam_groups = {}
+    for e in experiments:
+        fam_groups.setdefault(e.get("family") or "untagged", []).append(e)
+    families = {n: _family_summary(exps, metric, lower) for n, exps in fam_groups.items()}
+    best = _find_best(experiments, metric, lower)
+    decisions = _extract_decisions(packets, annotations)
+    direction = _project_direction(hypotheses, experiments)
+    report = format_onboarding_report(config, experiments, families, best, decisions,
+                                       direction, annotations, seeds, audience, depth, metric, lower)
+    return {"timestamp": datetime.now(timezone.utc).isoformat(), "audience": audience,
+            "depth": depth, "total_experiments": len(experiments),
+            "project_phase": direction["phase"], "report": report}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate project onboarding for new collaborators")
+    parser.add_argument("--config", default="config.yaml")
+    parser.add_argument("--log", default=DEFAULT_LOG)
+    parser.add_argument("--hypotheses", default=DEFAULT_HYPOTHESES)
+    parser.add_argument("--annotations", default=DEFAULT_ANNOTATIONS)
+    parser.add_argument("--audience", default="researcher", choices=VALID_AUDIENCES)
+    parser.add_argument("--depth", default="full", choices=VALID_DEPTHS)
+    parser.add_argument("--output", default="ONBOARDING.md")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    args = parser.parse_args()
+    result = generate_onboarding(args.config, args.log, args.hypotheses,
+                                  args.annotations, args.audience, args.depth)
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        saved = save_onboarding_report(result["report"], args.output)
+        print(result["report"])
+        print(f"\nSaved to {saved}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/templates/scripts/package_experiments.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""Package experiments into portable archive for sharing.
+
+Collects config, metrics, seed studies, annotations, decision packets
+per experiment. Generates manifest.yaml and README.md inside the
+package directory. Does NOT create tar.gz -- just organizes files.
+
+Usage:
+    python scripts/package_experiments.py
+    python scripts/package_experiments.py --experiments exp-042,exp-043
+    python scripts/package_experiments.py --include model,data-hash,figures,code
+    python scripts/package_experiments.py --json
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+from scripts.turing_io import load_config, load_experiments
+
+DEFAULT_LOG = "experiments/log.jsonl"
+DEFAULT_OUTPUT = "exports/packages"
+VALID_INCLUDES = ["model", "data-hash", "figures", "code"]
+
+
+def _load_yaml_list(path: str) -> list[dict]:
+    p = Path(path)
+    if not p.exists() or p.stat().st_size == 0:
+        return []
+    with open(p) as f:
+        data = yaml.safe_load(f)
+    return data if isinstance(data, list) else []
+
+
+def _load_yaml_file(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            d = yaml.safe_load(f)
+        return d if isinstance(d, dict) else None
+    except (yaml.YAMLError, OSError):
+        return None
+
+
+def _file_hash(filepath: str) -> str | None:
+    p = Path(filepath)
+    if not p.exists():
+        return None
+    h = hashlib.sha256()
+    with open(p, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def collect_experiment_artifacts(exp: dict, includes: list[str]) -> dict:
+    """Collect all artifacts for a single experiment."""
+    eid = exp.get("experiment_id", "unknown")
+    art: dict = {"experiment_id": eid, "status": exp.get("status", "unknown"),
+                 "metrics": exp.get("metrics", {}), "config": exp.get("config", {}),
+                 "description": exp.get("description", ""), "timestamp": exp.get("timestamp", ""),
+                 "family": exp.get("family")}
+    # Seed study
+    seed = _load_yaml_file(Path(f"experiments/seed_studies/{eid}-seeds.yaml"))
+    if seed:
+        art["seed_study"] = {"mean": seed.get("mean"), "std": seed.get("std"),
+                              "cv_percent": seed.get("cv_percent"),
+                              "seed_sensitive": seed.get("seed_sensitive", False)}
+    # Decision packet
+    dec = _load_yaml_file(Path(f"experiments/decisions/{eid}-decision.yaml"))
+    if dec:
+        art["decision"] = {"action": dec.get("action"), "reason": dec.get("reason", "")}
+    # Ablation
+    abl = _load_yaml_file(Path(f"experiments/ablations/{eid}-ablation.yaml"))
+    if abl:
+        art["ablation"] = {"metric": abl.get("metric"),
+                            "n_ablations": len(abl.get("results", []))}
+    # Reproduction
+    repro = _load_yaml_file(Path(f"experiments/reproductions/{eid}-repro.yaml"))
+    if repro:
+        art["reproduction"] = {"verdict": repro.get("verdict"), "reason": repro.get("reason", "")}
+    # Optional includes
+    if "model" in includes:
+        for pat in [f"models/{eid}", f"models/{eid}.*", f"checkpoints/{eid}/*"]:
+            matches = list(Path(".").glob(pat))
+            if matches:
+                art["model_path"] = str(matches[0])
+                break
+    if "data-hash" in includes:
+        dp = exp.get("config", {}).get("data", {}).get("path")
+        if dp:
+            h = _file_hash(dp)
+            if h:
+                art["data_hash"] = h
+    if "figures" in includes:
+        fig_dir = Path(f"experiments/figures/{eid}")
+        art["figures"] = [str(f) for f in fig_dir.glob("*") if f.is_file()] if fig_dir.exists() else []
+    if "code" in includes:
+        art["train_py_hash"] = _file_hash("train.py")
+        snap = Path(f"experiments/code/{eid}")
+        if snap.exists():
+            art["code_snapshot_path"] = str(snap)
+    return art
+
+
+def build_manifest(name: str, config: dict, artifacts: list[dict], includes: list[str]) -> dict:
+    eval_cfg = config.get("evaluation", {})
+    return {
+        "package": {"name": name, "created": datetime.now(timezone.utc).isoformat(),
+                     "generator": "turing:share", "version": "1.0"},
+        "project": {"task": config.get("task_description", ""),
+                     "primary_metric": eval_cfg.get("primary_metric", "accuracy"),
+                     "lower_is_better": eval_cfg.get("lower_is_better", False)},
+        "contents": {"experiments": len(artifacts), "includes": includes,
+                      "has_seed_studies": any(a.get("seed_study") for a in artifacts),
+                      "has_decisions": any(a.get("decision") for a in artifacts)},
+        "experiments": [{"id": a["experiment_id"], "status": a["status"],
+                          "family": a.get("family"), "metrics": a["metrics"]} for a in artifacts],
+    }
+
+
+def build_package_readme(config: dict, artifacts: list[dict], manifest: dict) -> str:
+    metric = manifest["project"]["primary_metric"]
+    d = "lower" if manifest["project"]["lower_is_better"] else "higher"
+    L = [f"# Experiment Package: {manifest['package']['name']}", "",
+         f"*Packaged {manifest['package']['created'][:19]} UTC*", "",
+         "## Project", "", f"- **Task:** {config.get('task_description', 'N/A')}",
+         f"- **Primary metric:** `{metric}` ({d} is better)", "", "## Experiments", "",
+         f"| ID | Status | Family | {metric} |",
+         f"|----|--------|--------|{'---'*max(len(metric)//3,1)}--|"]
+    for a in artifacts:
+        v = a.get("metrics", {}).get(metric)
+        vs = f"{v:.4f}" if isinstance(v, (int, float)) else "---"
+        L.append(f"| {a['experiment_id']} | {a['status']} | {a.get('family','---')} | {vs} |")
+    seeds = [a for a in artifacts if a.get("seed_study")]
+    if seeds:
+        L.extend(["", "## Seed Studies", ""])
+        for a in seeds:
+            s = a["seed_study"]
+            tag = "SEED-SENSITIVE" if s["seed_sensitive"] else "stable"
+            L.append(f"- `{a['experiment_id']}`: mean={s['mean']:.4f} +/- {s['std']:.4f} [{tag}]")
+    decs = [a for a in artifacts if a.get("decision")]
+    if decs:
+        L.extend(["", "## Decisions", ""])
+        for a in decs:
+            L.append(f"- `{a['experiment_id']}`: **{a['decision']['action']}** — {a['decision']['reason']}")
+    L.extend(["", "## Files", "", "- `manifest.yaml` — Machine-readable manifest",
+              "- `README.md` — This file", "- `experiments/` — Per-experiment artifacts",
+              "- `config.yaml` — Project config snapshot", "", "---",
+              "*Generated by `/turing:share`*"])
+    return "\n".join(L)
+
+
+def write_package(pkg_dir: Path, config: dict, artifacts: list[dict],
+                   manifest: dict, readme: str, includes: list[str]) -> None:
+    """Write all package files to the directory."""
+    pkg_dir.mkdir(parents=True, exist_ok=True)
+    with open(pkg_dir / "manifest.yaml", "w") as f:
+        yaml.dump(manifest, f, default_flow_style=False, sort_keys=False)
+    (pkg_dir / "README.md").write_text(readme)
+    with open(pkg_dir / "config.yaml", "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+    exp_dir = pkg_dir / "experiments"
+    exp_dir.mkdir(exist_ok=True)
+    for art in artifacts:
+        sub = exp_dir / art["experiment_id"]
+        sub.mkdir(exist_ok=True)
+        with open(sub / "artifact.yaml", "w") as f:
+            yaml.dump(art, f, default_flow_style=False, sort_keys=False)
+        if "figures" in includes and art.get("figures"):
+            fd = sub / "figures"
+            fd.mkdir(exist_ok=True)
+            for fp in art["figures"]:
+                src = Path(fp)
+                if src.exists():
+                    shutil.copy2(src, fd / src.name)
+        if "code" in includes and art.get("code_snapshot_path"):
+            cs = Path(art["code_snapshot_path"])
+            if cs.exists() and cs.is_dir():
+                shutil.copytree(cs, sub / "code", dirs_exist_ok=True)
+        if "model" in includes and art.get("model_path"):
+            ms = Path(art["model_path"])
+            if ms.exists():
+                md = sub / "model"
+                md.mkdir(exist_ok=True)
+                if ms.is_dir():
+                    shutil.copytree(ms, md, dirs_exist_ok=True)
+                else:
+                    shutil.copy2(ms, md / ms.name)
+
+
+def save_package_report(result: dict, pkg_dir: Path) -> Path:
+    rp = pkg_dir / "package-report.yaml"
+    with open(rp, "w") as f:
+        yaml.dump({"timestamp": result["timestamp"], "package_name": result["package_name"],
+                    "package_dir": str(result["package_dir"]),
+                    "experiments_packaged": result["experiments_packaged"],
+                    "includes": result["includes"]}, f, default_flow_style=False, sort_keys=False)
+    return rp
+
+
+def format_package_report(result: dict) -> str:
+    L = ["# Package Summary", "",
+         f"- **Package:** {result['package_name']}",
+         f"- **Location:** `{result['package_dir']}`",
+         f"- **Experiments:** {result['experiments_packaged']}",
+         f"- **Includes:** {', '.join(result['includes']) or 'metrics only'}", "", "## Contents", ""]
+    for a in result.get("artifacts", []):
+        extras = [k for k in ("seed_study", "decision", "ablation", "reproduction") if a.get(k)]
+        es = f" [{', '.join(extras)}]" if extras else ""
+        L.append(f"- `{a['experiment_id']}` ({a['status']}){es}")
+    return "\n".join(L)
+
+
+def package_experiments(experiment_ids=None, includes=None, config_path="config.yaml",
+                         log_path=DEFAULT_LOG, output_dir=DEFAULT_OUTPUT) -> dict:
+    """Package experiments into a portable directory."""
+    includes = includes or []
+    config = load_config(config_path)
+    experiments = load_experiments(log_path)
+    annotations = _load_yaml_list("experiments/annotations.yaml")
+    if experiment_ids:
+        selected = [e for e in experiments if e.get("experiment_id") in experiment_ids]
+        if not selected:
+            return {"error": f"No matching experiments for: {experiment_ids}"}
+    else:
+        selected = [e for e in experiments if e.get("status") == "kept"]
+        if not selected:
+            return {"error": "No kept experiments to package."}
+    artifacts = [collect_experiment_artifacts(e, includes) for e in selected]
+    for art in artifacts:
+        eid = art["experiment_id"]
+        anns = [a for a in annotations if a.get("experiment_id") == eid]
+        if anns:
+            art["annotations"] = anns
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    pkg_name = f"package-{len(artifacts)}exp-{ts}"
+    pkg_dir = Path(output_dir) / pkg_name
+    manifest = build_manifest(pkg_name, config, artifacts, includes)
+    readme = build_package_readme(config, artifacts, manifest)
+    write_package(pkg_dir, config, artifacts, manifest, readme, includes)
+    result = {"timestamp": datetime.now(timezone.utc).isoformat(), "package_name": pkg_name,
+              "package_dir": str(pkg_dir), "experiments_packaged": len(artifacts),
+              "includes": includes, "artifacts": artifacts}
+    save_package_report(result, pkg_dir)
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Package experiments into portable archive")
+    parser.add_argument("--experiments", default=None, help="Comma-separated experiment IDs")
+    parser.add_argument("--include", default=None, help="Extras: model,data-hash,figures,code")
+    parser.add_argument("--config", default="config.yaml")
+    parser.add_argument("--log", default=DEFAULT_LOG)
+    parser.add_argument("--output", default=DEFAULT_OUTPUT)
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    args = parser.parse_args()
+    exp_ids = [e.strip() for e in args.experiments.split(",")] if args.experiments else None
+    includes = []
+    if args.include:
+        includes = [i.strip() for i in args.include.split(",")]
+        bad = [i for i in includes if i not in VALID_INCLUDES]
+        if bad:
+            print(f"ERROR: Invalid include(s): {bad}. Valid: {VALID_INCLUDES}", file=sys.stderr)
+            sys.exit(1)
+    result = package_experiments(exp_ids, includes, args.config, args.log, args.output)
+    if "error" in result:
+        print(f"ERROR: {result['error']}", file=sys.stderr)
+        sys.exit(1)
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(format_package_report(result))
+        print(f"\nPackage saved to: {result['package_dir']}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/templates/scripts/scaffold.py

@@ -140,6 +140,12 @@ TEMPLATE_DIRS = {
         "citation_manager.py",
         "generate_figures.py",
         "generate_changelog.py",
+        "generate_onboarding.py",
+        "package_experiments.py",
+        "simulate_review.py",
+        "whatif_engine.py",
+        "counterfactual_explanation.py",
+        "experiment_simulator.py",
     ],
     "tests": ["__init__.py", "conftest.py"],
 }
@@ -189,6 +195,11 @@ DIRECTORIES_TO_CREATE = [
     "experiments/replays",
     "experiments/citations",
     "paper/figures",
+    "exports/packages",
+    "experiments/reviews",
+    "experiments/whatif",
+    "experiments/counterfactuals",
+    "experiments/simulations",
     "experiments/logs",
     "models/best",
     "models/archive",