exam-study-guide

name	exam-study-guide
description	将已经讲完但尚未完成阶段门禁的一个章节整理成强类型教材清单，并在视觉模式下编译为公式可读、图片可见、知识点与全部对应例题逐项精讲的自包含 HTML/PDF。结构化工作区准备阶段完成证据、用户说 Markdown 公式仍是 raw LaTeX、图片缺失、要含课件/作业/Quiz/模拟考试题及答案的零基础讲义，或要求打印版时使用。
license	MIT

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:

   python scripts/study_guide_author.py --workspace <ws> prepare --chapter <N> --json
   

   This fixed command atomically writes notebook/chNN.authoring-packet.json and the deliberately incomplete notebook/chNN.authoring-annotations.template.json; its JSON result reports both paths plus the template hash. Exit 10/status=blocked forbids authoring until every reported review, conflict, source, asset, and denominator blocker is resolved. The packet binds source/fact/asset revisions and contains the exact semantic units, formulas, items, prompt/answer assets, and source locations the agent may use.

Historical mode-less ingestion-v2 read-only seam

An already-existing canonical protocol-v2 notebook/chNN.guide.json that lacks answer_explanation_mode but has a complete, currently verifiable isolated contract may be inspected only with study_guide_content.py --workspace <ws> validate --chapter <N> --json, omitting --input. This narrow seam cannot import, render, run QA, satisfy completion, or accept another input; library validators and every new publication require an explicit canonical mode. Any revision requires rebuilding the full authoring chain under ordinary or isolated.

Legacy ingestion-v1 read-only compatibility

An explicit pipeline_version=ingestion-v1 workspace may inspect only an already existing canonical notebook/chNN.guide.json:

python scripts/study_guide_content.py --workspace <ws> validate --chapter <N> --json

The machine report identifies ingestion_pipeline_version=ingestion-v1, legacy_compatibility=read_only, and claim_verification.status=not_applicable with required=false. Do not pass another --input, import, relocalize, or render this manifest into a new visual Guide. Existing historical JSON/HTML/PDF files remain readable as historical artifacts, but they satisfy no new completion or QA claim. To revise content, language, crops, explanations, HTML, or PDF, migrate/re-ingest the workspace as ingestion-v2 and run the complete authoring chain. If a workspace says v2, missing claims or a failed author command is a blocker rather than permission to use this branch. 8. For visual, read docs/pdf-capability-adapters.md, probe docs/pdf-capability-adapters.json, and select exactly one backend:

• native: an already installed host PDF capability can print/convert the exact validated study_guide/chNN.html to study_guide/chNN.pdf and can render the result for QA;
• browser: use the repository fallback with a detected local Edge/Chrome;
• html: HTML-only request, so no PDF backend is required.

9. Run the content/backend-aware preflight after the typed manifest exists but before invoking the renderer:

   python scripts/check_deps.py --workspace <ws> --chapter <N> --artifact-mode visual --pdf-backend <native|browser|html>
   

   chapter_math_status=needs_recovery is a content blocker, not “no math.” Formula conversion becomes required when typed formulas/substitutions exist. Edge/Chrome is required only for the browser route. Explain only the exact missing dependency and obtain consent before installation.

10. Render the selected chapter. The default artifact type is the real typed Study Guide; backend/profile are explicit assertions:

python scripts/study_guide_render.py --workspace <ws> --chapter <N> --profile <full|abridged> --pdf-backend <html|browser|native>

11. For the browser PDF route, create the PDF only after HTML validation:

python scripts/study_guide_render.py --workspace <ws> --chapter <N> --profile <full|abridged> --pdf-backend browser --pdf

For native, the first render leaves a deliberately non-deliverable awaiting_native_pdf receipt. Before conversion, the host adapter must record that receipt's exact html_sha256 and conversion_start_gate_sha256, its declared registry adapter_id and exact loaded version, and a UTC start timestamp. It must consume those exact HTML bytes and write only the canonical study_guide/chNN.pdf; after it records the UTC completion timestamp, atomically bind the result:

python scripts/study_guide_render.py --workspace <ws> --chapter <N> --pdf-backend native --bind-native --native-pdf-path <ws>/study_guide/chNN.pdf --native-adapter-id <declared-id> --native-adapter-version <exact-version> --conversion-input-html-sha256 <receipt-html-sha256> --conversion-start-gate-sha256 <receipt-gate-sha256> --conversion-started-at <UTC-Z> --conversion-completed-at <UTC-Z> --json

The binding command invokes no adapter, network, installer, or renderer. It revalidates the current typed manifest, HTML, full-processing/runtime gate, allow-listed adapter identity, canonical PDF path/signature/hash, and timestamps under the workspace publication lock, then atomically changes the receipt to qa_pending. Any mismatch leaves the old receipt unbound, so merely dropping a PDF beside the HTML never makes it acceptable. --pdf is browser-only. The adapter/version fields are host declarations bound into the conversion hash, not an attestation that the host process was sandboxed. If the host cannot report the exact loaded adapter version, native binding is unavailable; explicitly fall back to browser or HTML rather than guessing latest. 12. Render and lint every PDF page, then inspect every PNG visually:

```text
python scripts/study_guide_qa.py --workspace <ws> --chapter <N> --json render
python scripts/study_guide_qa.py --workspace <ws> --chapter <N> accept --inspected-pages all --reviewer <name> --reviewer-kind agent --page-verdict 1=pass
```

Repeat `--page-verdict N=pass:<notes>` once for every rendered page; the one-page command above is only the minimal shape. Check formulas, glyphs, prompt/answer order, image clarity, clipping, tables, margins, page numbers, page breaks, orphan headings, and abnormal blank space. Any defect requires a source/renderer fix, regeneration, and a fresh inspection from page 1. `artifact_ready` remains false until the receipt has matching hashes, `visual_qa.status=ready`, every page is recorded, and unresolved defects are empty. Only after `artifact_ready=ready` return to `exam-tutor` to call `complete-phase`.

Output Contract

• Produce study_guide/chNN.html as an offline document with inline CSS, native MathML, and data-URI images. It must require no network, CDN, script, or browser extension.
• Dispatch every agent-authored heading, explanation, step, answer, and receipt from canonical zh|en|bilingual. Bilingual content is complete blockwise zh+en—not merely bilingual UI chrome. Source quotations/images stay original-language evidence and use the translation rule above.
• Hero source inventory uses only typed walkthroughs: localize counts; mark absent mock_exam/past_exam “not provided in the current workspace/material set.” Scoped zeroes change neither coverage nor global claims.
• Place prompt-side assets first and answer-side assets later. The printable Study Guide contains no hidden details, answer toggle, form control, or screen-only answer.
• Explain the provenance legend in full exactly once near the beginning. In later teaching content use only the legend emoji at the end of the relevant paragraph/run, and collapse consecutive paragraphs with the same provenance to one terminal marker. Keep the complete provenance sidecars and receipts machine-readable.
• Never render an unrelated full question/answer page merely because it has the right page number. Every newly rendered Study Guide requires authoring protocol v2; page-shaped assets require a current schema-v2, source-revision-bound crop receipt whose full single-region or explicit deterministic-composite variant passes the shared live verifier. New receipts use semantic-review schema v2: target-only has empty contexts plus isolation=target_item_only, while a dependent prompt contains only the target plus exact sorted required_context_ids and uses the distinct isolation=target_with_required_context; detected IDs, crop hash, every composite region/bbox, and output pixels must close exactly. Preserve those semantic schema/context/isolation controls into the author packet and isolated-explanation input. Historical receipt schema v1 and historical semantic-review v1 (including semantic v1 inside an otherwise readable receipt-v2 record) are read-only and cannot satisfy current Study Guide authoring; layout-only crops, stale/missing review evidence, unrelated content, undeclared detected IDs, or student-attempt output evidence also block authoring. A tainted parent page is not itself rendered and may supply a verified clean prompt region; answer-side evidence remains official-only.
• Retain source_file, the adapter's honest location anchors (for example PDF page, PPTX slide, XLSX worksheet, or DOCX logical segment), and the canonical provenance labels from the workspace.
• Produce study_guide/chNN.receipt.json with manifest/HTML/PDF hashes, exact coverage of the current chapter's de-duplicated teaching-example + all-bank-item + typed-question-unit ID denominator, selected backend/converter, and QA state. This does not prove semantic recall of every source claim. Never claim completion from file existence alone.

Boundaries

• Do not render the entire course to bypass chapter lazy-loading.
• Do not run because a host appears to have a low/high subscription. The only standing switch is canonical artifact_mode=chat|visual; missing and unknown values fail safe to chat.
• Do not silently machine-translate source evidence. Translation fields are explicitly AI-authored/localized teaching blocks and must be labeled by placement; do not pass them off as official wording.
• Non-PNG visual readiness conditionally requires an installed local Pillow decoder for full pixel verification. If missing, block the asset, explain the dependency, obtain consent, and never install silently.
• The raw-material preflight (check_deps.py --materials <dir> --artifact-mode visual) cannot know the final chapter content or host PDF backend and therefore must not trigger speculative MathML/browser installation. Before visual generation, rerun it with --workspace <ws> --chapter <N> --pdf-backend <native|browser|html>. If that chapter contains formula content without the audited latex2mathml==3.60.0, the preflight/renderer prints the exact pinned command. Explain the dependency and obtain consent before installation; never install silently. Never present an older chNN.html as the result of a failed render.
• Reject URL, absolute, parent-traversal, missing, unreadable, or symlinked assets and paths. The sole compatibility exception is ../assets/<safe-relative-tail> inside a selected references/wiki/*.md, because build_visual_index --apply-wiki emits that shape. Resolve it only to <ws>/references/assets/<safe-relative-tail>, reject every additional .. and every symlink component, and never extend this exception to teaching examples, quiz items, or notebook content.
• A missing local browser blocks only the selected browser backend. It does not block a successfully probed native adapter. Any failed PDF route is an HTML-only degradation, not a PDF success.
• Do not auto-download an untrusted third-party skill. Use only an adapter declared by the repository capability registry and confirmed by a successful probe.
• Do not treat location-derived source/unit IDs as content hashes. Bind exact revisions with the persisted source/unit digests, and never let a canonical-group display choice erase a source occurrence or adjudicate an unresolved conflict.