@diottodev/runic 1.0.0 → 1.1.0

package/research/syllabus/skills/syllabus/references/audience_calibration.md

@@ -0,0 +1,167 @@
+# Audience Calibration — Undergrad vs Grad Summary Jargon + Question Complexity
+
+This reference answers exactly one decision: **how does the syllabus skill calibrate summary jargon and discussion question complexity to the course's audience (Q2)?**
+
+## The Core Rule
+
+The same paper needs **different summaries** for different audiences:
+
+- **Undergrad-intro**: define every technical term; assume zero prior knowledge
+- **Undergrad-advanced**: assume foundational vocabulary; explain field-specific terms
+- **Grad-Masters**: assume technical fluency; brief context for novel concepts
+- **Grad-doctoral**: assume technical + methodological fluency; brief mention only of established context
+
+Same paper, different summaries. Generic summaries miss the engagement target.
+
+## Audience Buckets (Q2)
+
+| Bucket | Vocabulary assumption | Method assumption | Discussion question complexity |
+|---|---|---|---|
+| Undergraduate (intro) | Zero specialized | Zero | Recall + comprehension + simple application |
+| Undergraduate (advanced) | Foundational vocab | Common methods | Application + analysis |
+| Graduate (Masters / early PhD) | Technical fluency | Common research methods | Analysis + evaluation |
+| Graduate (doctoral / advanced) | Technical + methodological fluency | Methods specifics | Evaluation + critique + synthesis |
+| Professional / continuing ed | Field-specific assumed | Methods context-dependent | Application to practice |
+| Mixed | Lowest bucket present | Same | Same |
+
+## Summary Calibration
+
+### Undergrad-intro
+
+Every technical term defined. Plain language. Connects to common experience.
+
+| ❌ Too jargon | ✅ Calibrated |
+|---|---|
+| "This RCT compared lipidomic profiles across dietary interventions to assess cardiometabolic risk modulation." | "This randomized study compared what happens to fat molecules in the blood when people eat different diets — Mediterranean, Nordic, vegetarian — and looked at how those changes might affect heart disease risk." |
+| "The phylogenetic analysis identified convergent evolution of toxin-resistant Na+ channels across reptilian lineages." | "Researchers compared sodium-channel genes across snake species and found that snakes from very different evolutionary branches independently developed similar resistance to toxic prey." |
+
+### Undergrad-advanced
+
+Foundational vocabulary assumed. Explain field-specific terms briefly.
+
+| ❌ Too dumbed-down | ✅ Calibrated |
+|---|---|
+| "This randomized study compared what happens to fat molecules in the blood..." | "This RCT (n=240) tracked lipidomic shifts across three dietary patterns — Mediterranean, Nordic, vegetarian — over 12 weeks. Cardiometabolic markers improved most in the Mediterranean arm." |
+| "Researchers compared sodium-channel genes..." | "Phylogenetic analysis across 47 reptilian lineages identifies convergent evolution of Na+ channel modifications conferring resistance to neurotoxic prey." |
+
+### Grad (Masters or doctoral)
+
+Technical fluency assumed. Brief context for novel concepts. Method specifics if relevant.
+
+| ❌ Too verbose | ✅ Calibrated |
+|---|---|
+| "This RCT (n=240) tracked lipidomic shifts across three dietary patterns over 12 weeks. Cardiometabolic markers improved most in Mediterranean." | "RCT (n=240, 12-week, parallel-arm) comparing Mediterranean / Nordic / vegetarian. Mediterranean → 14% lower LDL-particle count, 22% lower oxidized LDL; differences plausibly mediated by MUFA:SFA ratio." |
+| "Phylogenetic analysis across 47 reptilian lineages identifies convergent evolution..." | "Bayesian phylogenetic analysis (47 lineages, BEAST 2.7) supports independent emergence of Na+ channel S6-domain modifications in 6 lineages; convergence rate inconsistent with neutral drift (PP > 0.95)." |
+
+### Professional / continuing ed
+
+Field-specific terms assumed. Emphasize practice implications.
+
+| ❌ Too academic | ✅ Calibrated |
+|---|---|
+| "RCT (n=240, 12-week)... LDL-particle count down 14%..." | "12-week RCT shows Mediterranean diet improves LDL-particle metrics 14-22% vs comparators. Practice implication: nutritional counseling for cardiovascular-risk patients should emphasize MUFA-rich foods specifically, not just 'low-fat'." |
+
+## Discussion Question Calibration
+
+Use Bloom's revised taxonomy (Anderson & Krathwohl 2001):
+
+| Level | Action verbs | Question pattern |
+|---|---|---|
+| Remember | identify, list, recall | "What is X?" "Name the components" |
+| Understand | explain, summarize, classify | "Why does X happen?" "How would you describe Y?" |
+| Apply | use, apply, demonstrate | "How could this method be applied to...?" "What would happen if we used X for Y?" |
+| Analyze | compare, contrast, examine | "What patterns connect X and Y?" "Why do X and Y produce different results?" |
+| Evaluate | judge, critique, defend | "Is this study's conclusion warranted by its methods?" "Which approach better serves goal Z, and why?" |
+| Create | design, propose, construct | "Design a study that would test the limits of X." "Propose a novel application of Y to Z." |
+
+### Calibration by audience
+
+| Audience | Question levels | Avoid |
+|---|---|---|
+| Undergrad-intro | Remember + Understand + simple Apply | Pure recall ("what did authors find?") |
+| Undergrad-advanced | Understand + Apply + simple Analyze | Sophisticated Evaluate / Create |
+| Grad-Masters | Apply + Analyze + Evaluate | Pure recall (insulting) |
+| Grad-doctoral | Analyze + Evaluate + Create | Anything below Apply |
+
+### Examples per audience
+
+#### Undergrad-intro
+
+| ❌ Recall only | ✅ Calibrated |
+|---|---|
+| "What did the authors find?" | "If you wanted to lower your heart disease risk through diet, what does this study suggest you should change?" (Apply) |
+
+#### Grad-doctoral
+
+| ❌ Below level | ✅ Calibrated |
+|---|---|
+| "What did this RCT show?" | "How would you redesign this RCT to test whether MUFA:SFA ratio specifically (vs total fat composition) drives the lipidomic shift?" (Create) |
+
+## Discussion Question Validator
+
+`scripts/discussion_question_validator.py` flags:
+
+- **Recall-only questions** (any audience): "what did authors find?", "summarize", "describe"
+- **Below-audience questions**: undergrad-intro questions in grad course → flag
+- **Above-audience questions**: doctoral-level questions in undergrad-intro → flag
+
+Validator suggests upgrades by replacing verbs with audience-appropriate Bloom verbs.
+
+## Tying Discussion Questions to Learning Outcomes
+
+Beyond audience calibration, each question should **explicitly tie to a learning outcome**:
+
+| Without LO tie | With LO tie |
+|---|---|
+| "How could this approach be applied to...?" | "Course outcome 3 says students should be able to design enzymatic processes. How would the kinetics described in this paper inform a process design for cheese ripening?" |
+
+The LO tie:
+- Reinforces course goals
+- Shows students why the reading matters
+- Creates assessable discussion behaviors
+
+If learning outcomes were inferred (`[inferred]`), still tie discussion questions to them — flag both as inferred.
+
+## Anti-Patterns
+
+### "Same summary for all audiences"
+
+The biggest engagement killer. Undergrad summaries that read like graduate abstracts produce blank stares; graduate summaries that read like K-12 explainers feel patronizing.
+
+### "Add jargon to look academic in undergrad summaries"
+
+Engagement signal: students underline / highlight content. Jargon-heavy summaries get less highlighting in undergrad classes. Plain-language summaries get more.
+
+### "Generic discussion questions"
+
+"What did the authors find?" works for any audience — and serves none. The discussion question is the engagement hook; generic questions waste it.
+
+### "All discussion questions at the highest Bloom level"
+
+In a grad-doctoral course, even one Create-level question per paper is taxing. Mix Analyze, Evaluate, Create. Don't make every reading require students to design a follow-up study.
+
+## Operational Checklist
+
+- [ ] Q2 audience parsed → calibration bucket selected
+- [ ] All summaries calibrated to bucket
+- [ ] All discussion questions calibrated to bucket's Bloom range
+- [ ] Each discussion question tied to a learning outcome (explicit or inferred)
+- [ ] Validator (`discussion_question_validator.py`) run on all questions
+- [ ] Recall-only questions rejected
+- [ ] Below-audience or above-audience questions reworked
+
+## Citations (7 sources)
+
+1. **Bloom, B. S. (1956); Anderson, L. W. & Krathwohl, D. R. (2001), *A Taxonomy for Learning, Teaching, and Assessing*.** The revised Bloom's taxonomy. Source for the 6-level question hierarchy + action verb lexicon.
+
+2. **Marzano, R. J. & Kendall, J. S., *The New Taxonomy of Educational Objectives* (Corwin, 2007).** Modern alternative to Bloom; emphasizes meta-cognitive and self-system levels. Source for the validator's "below-level vs above-level" distinction.
+
+3. **Hattie, J., *Visible Learning* (Routledge, 2008/2023 update).** Meta-meta-analysis of educational interventions. Effect size 0.6+ for "teacher clarity" justifies the audience-calibrated summary discipline (clarity is audience-relative).
+
+4. **Bain, K., *What the Best College Teachers Do* (Harvard, 2004).** Source for the "tied to learning outcome" discipline. Bain's research found great teachers connect every reading explicitly to course-level goals; generic readings produce engagement drop.
+
+5. **Walvoord, B. E. & Anderson, V. J., *Effective Grading* (Jossey-Bass, 2nd ed. 2010).** Source for the "discussion question is assessable behavior" framing. Each discussion question = an opportunity to assess whether learning outcomes are being met.
+
+6. **Brookfield, S. D. & Preskill, S., *Discussion as a Way of Teaching* (Jossey-Bass, 2nd ed. 2005).** Source for the engagement-vs-jargon trade-off in summary writing. Brookfield's research: students engage with content they can paraphrase; jargon-heavy summaries reduce paraphrase capability.
+
+7. **Bjork, R. A. & Bjork, E. L., "Making Things Hard on Yourself, but in a Good Way" — *Psychology and the Real World* (FABBS Foundation, 2011).** Source for the "desirable difficulty" framing. Discussion questions should be challenging at the audience's edge, not below it (insulting) or above it (defeating).

package/research/syllabus/skills/syllabus/references/bundled_script_pattern.md

@@ -0,0 +1,150 @@
+# Bundled Script Pattern — Why JS for DOCX Generation, Not Inline
+
+This reference answers exactly one decision: **why does the syllabus skill ship a bundled `generate_reading_list.js` script rather than inlining the DOCX generation logic in SKILL.md?**
+
+## The Core Trade
+
+DOCX generation requires ~300 lines of `docx`-package boilerplate (table layouts, hyperlink patterns, list formatting, page setup, etc.). This logic is:
+
+1. **Reusable** across runs — every reading list uses the same DOCX layout
+2. **Mechanical** — no LLM judgment required; just JSON-in / DOCX-out
+3. **Long-lived** — the layout doesn't change between runs
+
+Inlining 300 lines of mechanical layout code in SKILL.md means:
+- The skill prompt is much longer (token cost on every invocation)
+- Layout changes require editing the skill prompt (high-risk)
+- The skill body has to re-derive the same logic each run
+
+Bundling the logic in `scripts/generate_reading_list.js` means:
+- The skill body is ~200 lines lighter (token-efficient)
+- Layout changes are isolated to one file
+- The skill orchestrates; the script executes mechanically
+
+## When to Bundle (vs Inline)
+
+### Bundle when:
+
+- ✅ The logic is mechanical (no LLM judgment)
+- ✅ The logic is reusable across runs (same layout / same algorithm)
+- ✅ The logic is non-trivial (>50 lines)
+- ✅ The logic is in a non-Python language (JS, Go, Rust, etc.)
+- ✅ The logic has external dependencies (`docx` package, `requests`, etc.)
+
+### Inline (in SKILL.md) when:
+
+- The logic requires LLM judgment per run (e.g., paper-summary writing)
+- The logic is short (<20 lines) and run-specific
+- The logic is in-context-only (uses session-specific tool calls)
+- The logic varies significantly per invocation
+
+## The Pattern Used Here
+
+`scripts/generate_reading_list.js`:
+
+1. **Accepts JSON input + output path as CLI args**
+   ```bash
+   node generate_reading_list.js --input data.json --output result.docx
+   ```
+
+2. **Has a documented JSON schema** (in SKILL.md so the orchestrator knows what to produce)
+
+3. **Handles `docx` require with multi-location fallback** (works whether `docx` is installed locally, globally, or in a parent dir)
+
+4. **Validates input** (missing fields → graceful error, not silent failure)
+
+5. **Produces a clean professional DOCX** with:
+   - Title page
+   - Introduction (with Consensus link)
+   - Learning outcomes box
+   - Numbered papers per section
+   - Footer with metadata
+
+6. **Uses canonical `docx` patterns**:
+   - `ExternalHyperlink` with full URLs
+   - `LevelFormat.BULLET` for lists
+   - Dual-width tables (`columnWidths` + cell `width`)
+
+## Skill Orchestrator's Role
+
+The skill body (SKILL.md):
+
+1. Walks Phase 0 intake
+2. Parses syllabus + extracts topics
+3. Walks group-and-confirm checkpoint
+4. Runs Consensus searches (LLM judgment per query)
+5. Writes summaries + discussion questions (LLM judgment per paper)
+6. **Constructs the JSON payload** matching the bundled script's schema
+7. **Invokes the script** with the JSON
+8. Validates output + delivers
+
+The skill body is responsible for **what goes in the document**. The script is responsible for **how it's laid out**.
+
+## Why Node.js Specifically
+
+The `docx` library is a JavaScript library (npm package). Could the skill use a Python `docx` library (`python-docx`)? Yes, but:
+
+- The repo's other research-pack DOCX-generating skills (litreview, grants, dossier) all use Node.js + `docx`
+- Consistency: one DOCX library across the research pack
+- The `docx` JS library is more actively maintained + has richer features
+- `python-docx` doesn't support all the features the skill needs (advanced hyperlinks, table styling)
+
+## File Structure
+
+```
+research/syllabus/skills/syllabus/scripts/
+├── citation_tracker.py            ← stdlib Python (orchestration helper)
+├── topic_grouper.py               ← stdlib Python (orchestration helper)
+├── discussion_question_validator.py ← stdlib Python (orchestration helper)
+└── generate_reading_list.js       ← BUNDLED Node.js (mechanical DOCX assembly)
+```
+
+The Python scripts are stateless helpers (per-run). The JS script is the bundled mechanical assembler (called once per run).
+
+## Anti-Patterns
+
+### "Inline the JS into a Python script via subprocess"
+
+Adds an unnecessary layer. The skill should call `node` directly.
+
+### "Convert JS logic to Python to keep all scripts in one language"
+
+Loses access to the better-maintained `docx` JS library. Worse: would diverge from sibling skills (litreview, grants, dossier all use `docx` JS).
+
+### "Keep the JS script but inline the JSON schema in the script"
+
+The JSON schema needs to be IN SKILL.md so the orchestrator knows what to construct. Documenting it in the script alone hides it from the orchestrator's prompt context.
+
+### "Inline 300 lines of docx code in SKILL.md"
+
+The original anti-pattern. Bloats the prompt, makes layout changes risky, makes the skill body harder to read.
+
+### "Import the script from another skill"
+
+Cross-skill dependencies break the per-skill self-contained discipline (per CLAUDE.md anti-patterns). Even though it would save duplication, the bundled script lives within syllabus's own folder.
+
+## Operational Checklist
+
+- [ ] `scripts/generate_reading_list.js` exists in syllabus's scripts/ folder
+- [ ] Script accepts `--input <json>` + `--output <docx>` CLI args
+- [ ] Script handles `docx` require with multi-location fallback
+- [ ] Script validates input (missing fields → graceful error)
+- [ ] JSON schema documented in SKILL.md (not just in the script)
+- [ ] Skill orchestrator constructs JSON matching the schema
+- [ ] Skill orchestrator invokes the script via `node` (not `python`)
+- [ ] DOCX output validated post-generation
+
+## Citations (7 sources)
+
+1. **Karpathy-coder discipline + write-a-skill conventions** (this repo's `engineering/write-a-skill/`). Source for the "stdlib-only Python tools, bundled non-Python scripts allowed for mechanical jobs" pattern.
+
+2. **CLAUDE.md anti-pattern: "Don't add features beyond what the task requires."** The bundled script honors this — it does ONE thing (DOCX layout) and does it mechanically.
+
+3. **`docx` Node.js package — github.com/dolanmiu/docx (MIT).** Authoritative source for the API patterns the bundled script uses. Active maintenance, comprehensive feature set.
+
+4. **CommonJS / Node.js module resolution algorithm.** Source for the "multi-location fallback" pattern in the require statement. Ensures the script works in development (local node_modules) and production (global install).
+
+5. **Twelve-Factor App principles — III. Config: store config in the environment.** Source for the CLI-args-not-config pattern. Script accepts input/output as args, not via env vars or config files.
+
+6. **Brian Kernighan & P. J. Plauger, *Software Tools* (1976).** Source for the "do one thing well + compose" pattern. The bundled script does exactly one thing (mechanical DOCX assembly); the skill body composes it with the rest of the pipeline.
+
+7. **Doug McIlroy / Unix philosophy.** Source for the broader pattern: "Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface." JSON-in / DOCX-out is the modern equivalent.

package/research/syllabus/skills/syllabus/scripts/citation_tracker.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""citation_tracker.py — Syllabus three-count audit + 1s sequential discipline.
+
+Stdlib-only. Mirrors litreview's citation_tracker (research-pack convention)
+adapted for syllabus's per-section search budget.
+
+Tracked counts:
+  - searches_total
+  - searches_per_section
+  - papers_received
+  - papers_cited
+
+Per-section detail recorded for DOCX audit log.
+Enforces 1s sequential gap.
+
+Usage:
+    python citation_tracker.py --action start --session syllabus-bio101-20260515 --course "Intro Biology"
+    python citation_tracker.py --action record_search --session ... --section "Cell Biology" --query "..."
+    python citation_tracker.py --action record_received --session ... --section "Cell Biology" --count 3
+    python citation_tracker.py --action record_cited --session ... --section "Cell Biology" --url "..."
+    python citation_tracker.py --action status --session ...
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+SESSIONS_DIR = Path.home() / ".syllabus_sessions"
+MIN_GAP_SECONDS = 1.0
+
+
+def session_path(name: str) -> Path:
+    return SESSIONS_DIR / f"{name}.json"
+
+
+def load_session(name: str) -> Dict[str, Any]:
+    p = session_path(name)
+    if not p.exists():
+        raise FileNotFoundError(f"Session not found: {name}")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def save_session(name: str, data: Dict[str, Any]) -> None:
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def now_ts() -> float:
+    return datetime.now(timezone.utc).timestamp()
+
+
+def action_start(name: str, course: Optional[str], audience: Optional[str], year_range: Optional[str]) -> Dict[str, Any]:
+    if session_path(name).exists():
+        raise FileExistsError(f"Session already exists: {name}")
+    data: Dict[str, Any] = {
+        "session": name,
+        "course": course or "",
+        "audience": audience or "",
+        "year_range": year_range or "",
+        "consensus_tier": None,
+        "started_at": now_iso(),
+        "ended_at": None,
+        "searches": [],
+        "received_log": [],
+        "cited": [],
+        "counts": {
+            "searches_total": 0,
+            "papers_received_total": 0,
+            "papers_cited_total": 0,
+        },
+        "by_section": {},
+    }
+    save_session(name, data)
+    return data
+
+
+def action_record_search(name: str, section: str, query: str, tier: Optional[str]) -> Dict[str, Any]:
+    data = load_session(name)
+    if data["searches"]:
+        last_ts = data["searches"][-1].get("ts", 0)
+        gap = now_ts() - last_ts
+        if gap < MIN_GAP_SECONDS:
+            raise RuntimeError(
+                f"Sequential discipline violated: {gap:.2f}s gap (need >= {MIN_GAP_SECONDS}s). "
+                f"Wait {MIN_GAP_SECONDS - gap:.2f}s more."
+            )
+    if tier and not data["consensus_tier"]:
+        data["consensus_tier"] = tier
+    data["searches"].append({"section": section, "query": query, "tier": tier, "at": now_iso(), "ts": now_ts()})
+    data["counts"]["searches_total"] += 1
+    if section not in data["by_section"]:
+        data["by_section"][section] = {"searches": 0, "received": 0, "cited": 0}
+    data["by_section"][section]["searches"] += 1
+    save_session(name, data)
+    return data
+
+
+def action_record_received(name: str, section: str, count: int) -> Dict[str, Any]:
+    data = load_session(name)
+    data["received_log"].append({"section": section, "count": count, "at": now_iso()})
+    data["counts"]["papers_received_total"] += count
+    if section not in data["by_section"]:
+        data["by_section"][section] = {"searches": 0, "received": 0, "cited": 0}
+    data["by_section"][section]["received"] += count
+    save_session(name, data)
+    return data
+
+
+def action_record_cited(name: str, section: str, url: str, title: Optional[str]) -> Dict[str, Any]:
+    data = load_session(name)
+    if any(c["url"] == url for c in data["cited"]):
+        return data
+    data["cited"].append({"section": section, "url": url, "title": title, "at": now_iso()})
+    data["counts"]["papers_cited_total"] += 1
+    if section not in data["by_section"]:
+        data["by_section"][section] = {"searches": 0, "received": 0, "cited": 0}
+    data["by_section"][section]["cited"] += 1
+    save_session(name, data)
+    return data
+
+
+def action_status(name: str) -> Dict[str, Any]:
+    return load_session(name)
+
+
+def action_close(name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if data.get("ended_at") is None:
+        data["ended_at"] = now_iso()
+        save_session(name, data)
+    return data
+
+
+def render_status_human(data: Dict[str, Any]) -> str:
+    out: List[str] = []
+    out.append(f"Session:           {data['session']}")
+    out.append(f"Course:            {data.get('course', '(unset)')}")
+    out.append(f"Audience:          {data.get('audience', '(unset)')}")
+    out.append(f"Year range:        {data.get('year_range', '(unset)')}")
+    out.append(f"Consensus tier:    {data.get('consensus_tier') or '(not detected)'}")
+    out.append(f"Started:           {data['started_at']}")
+    out.append(f"Ended:             {data.get('ended_at') or '(active)'}")
+    out.append("")
+    c = data["counts"]
+    out.append(f"Total searches:    {c['searches_total']}")
+    out.append(f"Total received:    {c['papers_received_total']}")
+    out.append(f"Total cited:       {c['papers_cited_total']}")
+    out.append("")
+    if data["by_section"]:
+        out.append("Per-section breakdown:")
+        for section, stats in data["by_section"].items():
+            out.append(f"  {section:<40s} {stats['searches']} searches → {stats['received']} received → {stats['cited']} cited")
+    out.append("")
+    out.append("Audit block (paste in DOCX audit-log section):")
+    out.append(
+        f"  Total queries: {c['searches_total']}. Papers received: {c['papers_received_total']}. "
+        f"Papers cited: {c['papers_cited_total']}. "
+        f"Plan tier: {data.get('consensus_tier') or 'undetected'}."
+    )
+    return "\n".join(out)
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--action", required=True, choices=["start", "record_search", "record_received", "record_cited", "status", "list", "close"])
+    parser.add_argument("--session")
+    parser.add_argument("--course")
+    parser.add_argument("--audience")
+    parser.add_argument("--year-range")
+    parser.add_argument("--section")
+    parser.add_argument("--query")
+    parser.add_argument("--tier")
+    parser.add_argument("--count", type=int)
+    parser.add_argument("--url")
+    parser.add_argument("--title")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.action == "start":
+            result = action_start(args.session, args.course, args.audience, args.year_range)
+        elif args.action == "record_search":
+            result = action_record_search(args.session, args.section, args.query, args.tier)
+        elif args.action == "record_received":
+            result = action_record_received(args.session, args.section, args.count)
+        elif args.action == "record_cited":
+            result = action_record_cited(args.session, args.section, args.url, args.title)
+        elif args.action == "status":
+            result = action_status(args.session)
+        elif args.action == "close":
+            result = action_close(args.session)
+        else:
+            SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+            result = [{"session": p.stem, "data": json.loads(p.read_text(encoding="utf-8"))} for p in sorted(SESSIONS_DIR.glob("*.json"))]
+    except (FileNotFoundError, FileExistsError, RuntimeError) as e:
+        print(f"error: {e}", file=sys.stderr); return 2
+
+    if args.output == "json":
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        if args.action == "list":
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            print(render_status_human(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))