exam-study-guide

# Exam Study Guide

## Purpose

After teaching the current chapter, build its validated typed Study Guide manifest; in visual mode, compile that manifest into a readable, self-contained HTML Study Guide and printable PDF before phase completion. A Study Guide is a teaching artifact, not a dump of the wiki and bank: it groups knowledge points with every mapped lecture, homework, Quiz, mock-exam, past-exam, or textbook example and explains each one through formula selection, variable mapping, substitution, solution, a beginner-first explanation of why the answer follows, and source trace. Keep Markdown/JSON as auditable sources and never overwrite them with a derived artifact.

## Activation

Require explicit `study_state.json.processing_mode=full`. Lightweight mode never
invokes this module, even for a one-shot handout request; explain that Study Guide
generation requires switching to full processing and reconfirming the start gate.

Use this module after the exam workspace/current chapter are confirmed and its substantive teaching is persisted, but before `complete-phase` in a structured workspace. Restore the current phase and effective `artifact_mode` from `study_state.json` before selecting `<N>`. `chat` still builds and imports the mandatory typed `profile=full` manifest, then stops without HTML/PDF; a recognized standing `visual` preference continues through rendering, receipt binding, and all-page QA. A direct one-shot handout request follows its explicit output scope without rewriting the stored preference. Never inspect or infer the student's subscription. Preserve the parent exam-coach language and provenance contracts in all chat summaries.

## Inputs

- Exactly one current-chapter `references/wiki/chNN*.md` file, used as source evidence rather than pasted wholesale.
- Optional `study_state.json`; its canonical language-neutral `language` code (`zh` / `en` / `bilingual`; legacy/display aliases `中文` / `English` / `双语` migrate on read) controls all agent-generated headings, notices, explanations, labels, and summaries. Missing state follows the session default (English unless the student opened in Chinese); the script's Chinese empty-value fallback exists only for legacy workspaces and is not a new-session language decision.
- The current-chapter slice of `references/teaching_examples.json`, every current-chapter entry in `references/quiz_bank.json`, and every typed current-chapter question unit, de-duplicated by item ID. A legacy `gradable=false` record remains a teaching example in the guide but is never served or graded as a quiz.
- A substantive `notebook/chNN.md` plus the validated typed teaching manifest `notebook/chNN.guide.json`.
- Workspace-local images under `references/assets/` referenced by the typed manifest.
- For ingestion-v2 workspaces, current validated `.ingest/canonical_groups.jsonl` and `.ingest/source_conflicts.jsonl` facts. These are revision-bound derived facts, not replacements for source occurrences or item/unit IDs. Do not preload unrelated chapters or hand-fold near matches.
- For ingestion-v2, `.ingest/claim_records.jsonl` and the matching `.ingest/claim_verification_receipts/chNN.json` are mandatory typed-guide inputs. The validator recomputes them against the current manifest and live source/content/group/conflict facts. The receipt's `fact_snapshot_sha256` also binds current build/parser/page-quality/review facts into its ID, so a parser identity revision requires re-verification even when content units are unchanged. Legacy/v1 compatibility is read-only for an existing canonical manifest and must not be described as having this v2 evidence. The receipt scope is `location_only`, never semantic proof.

Use only `$...$` and `$$...$$` as formula delimiters in source Markdown. Forms such as `(A\cup B)`, `[P=\frac{...}]`, `\(...\)`, and `\[...\]` are not valid framework input. Confirm and migrate the source explicitly; never guess-rewrite a formula.

## Workflow

1. Restore `study_state.json`, resolve output intent, and run `validate_workspace.py <ws> --json`. Read the explicit `.ingest/build_manifest.json.pipeline_version`; never infer or delete it. Only `ingestion-v2` follows the author/compiler/claim path in steps 2-6. An explicit `ingestion-v1` workspace may only read its existing canonical manifest through the legacy compatibility path below; it cannot import, relocalize, or render a new Study Guide and must never claim the v2 claim/receipt gate. A failed v2 command does not authorize downgrading to v1. `chat` stops after the canonical `profile=full` manifest import; `visual` continues through rendering and all-page QA. Persist a standing choice only through `update_progress.py set --artifact-mode chat|visual`. Separately resolve `answer_explanation_mode=ordinary|isolated`. Missing, legacy, or invalid state has stored-schema fallback `ordinary`, which still requires a detailed beginner-first explanation for every item without an isolation claim. Before authoring a full-v2 Guide, perform a native-child capability handshake: require one fresh independent child context per item plus enforceable restriction of that child's task input and tools to the exact request. When verified, default to `isolated` unless the user opted out, persist it, and disclose once that it consumes extra host quota/time; no separate API key or external-upload consent is needed. Any missing, inherited, or unverified boundary keeps `ordinary` and must be named. A separately billed external Provider is available only when the user explicitly requests it; before persisting that fallback, retain the two-stage no-upload exact plan and exact-plan pricing/privacy/upload consent. Never infer either capability or upload permission from a model family, subscription, API key, `full`, or `visual`.
2. For ingestion-v2, prepare the revision-bound current-chapter packet and annotation template; do not hand-copy source facts or reverse-engineer the compiler source:

   ```text
   python script