get-fsa-training-done 1.0.0__tar.gz

get_fsa_training_done-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+node_modules/
+.DS_Store
+

get_fsa_training_done-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phuong Bui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

get_fsa_training_done-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: get-fsa-training-done
+Version: 1.0.0
+Summary: One agent skill, and the CLI behind it, for getting FSA training done: programmes, teaching material and assessments. Installs into Claude Code and Codex.
+Project-URL: Homepage, https://github.com/phuongbv00/get-fsa-training-done
+Project-URL: Issues, https://github.com/phuongbv00/get-fsa-training-done/issues
+Author: Phuong Bui
+License: MIT
+License-File: LICENSE
+Keywords: agent-skill,assessment,claude-code,codex,curriculum,grading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# get-fsa-training-done
+
+One agent skill, and the CLI behind it, for getting FSA training done:
+designing a programme, writing its teaching material, and designing and grading
+its assessments. It installs into [Claude Code](https://claude.com/claude-code)
+and the [Codex CLI](https://developers.openai.com/codex/cli).
+
+The skill has three features, each with its own CLI namespace:
+
+| Namespace | What it does | Docs |
+| --- | --- | --- |
+| `program` | design a training programme and export its workbooks | [README](src/get_fsa_training_done/features/program/README.md) |
+| `material` | write lecture notes, handbooks, lab guides and worksheets | [README](src/get_fsa_training_done/features/material/README.md) |
+| `assessment` | design and grade quizzes, assignments, exams and capstones | [README](src/get_fsa_training_done/features/assessment/README.md) |
+
+They divide one job. A programme's session plan names, in its
+`Training Materials` column, the file that serves each session — so `program`
+declares that a slot exists and what it weighs, `material` writes the lecture
+note or lab guide, and `assessment` writes the quiz, brief or exam. No feature
+authors another's artifact, and each checks its own half of that manifest.
+
+The skill is built from **tasks** — one step each, such as writing a rubric,
+rendering a brief, or merging a retake — composed into **workflows**. Ask for a
+whole job and the agent follows the workflow; ask for one step and it runs that
+task on its own.
+
+The skill is **stateless**. It assumes nothing about the directory layout it
+was installed into and never scans a project on a hunch — it asks for its
+inputs first, echoes back the resolved paths, and waits for a go-ahead.
+
+## Install
+
+```bash
+pip install get-fsa-training-done
+```
+
+This gives you the `get-fsa-training-done` command and its short alias `gftd`.
+It needs Python 3.12+.
+
+Then install the skill into your agent:
+
+```bash
+get-fsa-training-done install --platform all
+```
+
+| Command | Effect |
+| --- | --- |
+| `get-fsa-training-done install --platform claude --scope user` | `~/.claude/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform claude --scope project` | `./.claude/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform codex --scope user` | `~/.codex/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform codex --scope project` | `./.codex/skills/get-fsa-training-done` |
+| `get-fsa-training-done update` | upgrade in place, preserving files you edited |
+| `get-fsa-training-done uninstall --platform all` | remove exactly what was installed |
+| `get-fsa-training-done status` | what is installed where, and whether it drifted |
+| `get-fsa-training-done doctor` | check this machine for the skill's prerequisites |
+
+Add `--dry-run` to any of `install`, `update`, or `uninstall` to see the exact
+file-by-file plan without touching anything.
+
+## Dependencies
+
+Installing the package pulls nothing: `dependencies = []` is deliberate, so the
+lifecycle commands run on a bare interpreter. The libraries the worker commands
+need live in the **managed virtualenv** instead — declared once in
+`src/get_fsa_training_done/lifecycle/envmgr/requirements/core.txt`:
+
+| Library | Used by |
+| --- | --- |
+| `xhtml2pdf` | `assessment render`, for the brief PDF |
+| `py7zr` | `assessment grade preprocess`, for `.7z` submissions |
+
+`get-fsa-training-done install` builds that environment, so the first install
+needs a network and everything after it does not — which is the property that
+matters on an exam machine.
+
+Two external tools are optional, and `doctor` reports each without failing for
+its absence:
+
+- **A `.rar` extractor** (`unar`, `7z` or `bsdtar`). `.rar` is proprietary and
+  has no pure-Python reader; every other archive format is read in-process.
+- **Docker**, for `assessment sandbox`: running a seed script, a JUnit suite or
+  a pytest run that is not ours — an exam's supplied files, or a submission —
+  in a disposable container with no network.
+
+Rendering embeds its own fonts (see
+[`core/fonts/`](src/get_fsa_training_done/features/assessment/core/fonts)), so a
+Vietnamese brief comes out identical on every machine.
+
+## Layout
+
+```
+src/get_fsa_training_done/
+  cli.py  skill.py          the CLI, and the one skill it installs
+  lifecycle/                install, update, uninstall, status, doctor, env
+  features/                 program, material, assessment (+ common)
+  payload/get-fsa-training-done/
+    SKILL.md                the router: workflows and tasks per feature
+    references/<feature>/   overview, tasks/, workflows/, generated references
+    references/common/      writing style, Vietnamese conventions, shared tasks
+```
+
+## Development
+
+```bash
+pip install -e .
+pytest
+ruff check . && ruff format --check .
+python scripts/sync_version.py --check
+for generator in scripts/*/gen_*.py; do python "$generator" --check; done
+```
+
+`src/get_fsa_training_done/__about__.py` holds the canonical version;
+`sync_version.py` propagates it to the payload's `VERSION`.
+
+## Licence
+
+MIT

get_fsa_training_done-1.0.0/README.md

@@ -0,0 +1,117 @@
+# get-fsa-training-done
+
+One agent skill, and the CLI behind it, for getting FSA training done:
+designing a programme, writing its teaching material, and designing and grading
+its assessments. It installs into [Claude Code](https://claude.com/claude-code)
+and the [Codex CLI](https://developers.openai.com/codex/cli).
+
+The skill has three features, each with its own CLI namespace:
+
+| Namespace | What it does | Docs |
+| --- | --- | --- |
+| `program` | design a training programme and export its workbooks | [README](src/get_fsa_training_done/features/program/README.md) |
+| `material` | write lecture notes, handbooks, lab guides and worksheets | [README](src/get_fsa_training_done/features/material/README.md) |
+| `assessment` | design and grade quizzes, assignments, exams and capstones | [README](src/get_fsa_training_done/features/assessment/README.md) |
+
+They divide one job. A programme's session plan names, in its
+`Training Materials` column, the file that serves each session — so `program`
+declares that a slot exists and what it weighs, `material` writes the lecture
+note or lab guide, and `assessment` writes the quiz, brief or exam. No feature
+authors another's artifact, and each checks its own half of that manifest.
+
+The skill is built from **tasks** — one step each, such as writing a rubric,
+rendering a brief, or merging a retake — composed into **workflows**. Ask for a
+whole job and the agent follows the workflow; ask for one step and it runs that
+task on its own.
+
+The skill is **stateless**. It assumes nothing about the directory layout it
+was installed into and never scans a project on a hunch — it asks for its
+inputs first, echoes back the resolved paths, and waits for a go-ahead.
+
+## Install
+
+```bash
+pip install get-fsa-training-done
+```
+
+This gives you the `get-fsa-training-done` command and its short alias `gftd`.
+It needs Python 3.12+.
+
+Then install the skill into your agent:
+
+```bash
+get-fsa-training-done install --platform all
+```
+
+| Command | Effect |
+| --- | --- |
+| `get-fsa-training-done install --platform claude --scope user` | `~/.claude/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform claude --scope project` | `./.claude/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform codex --scope user` | `~/.codex/skills/get-fsa-training-done` |
+| `get-fsa-training-done install --platform codex --scope project` | `./.codex/skills/get-fsa-training-done` |
+| `get-fsa-training-done update` | upgrade in place, preserving files you edited |
+| `get-fsa-training-done uninstall --platform all` | remove exactly what was installed |
+| `get-fsa-training-done status` | what is installed where, and whether it drifted |
+| `get-fsa-training-done doctor` | check this machine for the skill's prerequisites |
+
+Add `--dry-run` to any of `install`, `update`, or `uninstall` to see the exact
+file-by-file plan without touching anything.
+
+## Dependencies
+
+Installing the package pulls nothing: `dependencies = []` is deliberate, so the
+lifecycle commands run on a bare interpreter. The libraries the worker commands
+need live in the **managed virtualenv** instead — declared once in
+`src/get_fsa_training_done/lifecycle/envmgr/requirements/core.txt`:
+
+| Library | Used by |
+| --- | --- |
+| `xhtml2pdf` | `assessment render`, for the brief PDF |
+| `py7zr` | `assessment grade preprocess`, for `.7z` submissions |
+
+`get-fsa-training-done install` builds that environment, so the first install
+needs a network and everything after it does not — which is the property that
+matters on an exam machine.
+
+Two external tools are optional, and `doctor` reports each without failing for
+its absence:
+
+- **A `.rar` extractor** (`unar`, `7z` or `bsdtar`). `.rar` is proprietary and
+  has no pure-Python reader; every other archive format is read in-process.
+- **Docker**, for `assessment sandbox`: running a seed script, a JUnit suite or
+  a pytest run that is not ours — an exam's supplied files, or a submission —
+  in a disposable container with no network.
+
+Rendering embeds its own fonts (see
+[`core/fonts/`](src/get_fsa_training_done/features/assessment/core/fonts)), so a
+Vietnamese brief comes out identical on every machine.
+
+## Layout
+
+```
+src/get_fsa_training_done/
+  cli.py  skill.py          the CLI, and the one skill it installs
+  lifecycle/                install, update, uninstall, status, doctor, env
+  features/                 program, material, assessment (+ common)
+  payload/get-fsa-training-done/
+    SKILL.md                the router: workflows and tasks per feature
+    references/<feature>/   overview, tasks/, workflows/, generated references
+    references/common/      writing style, Vietnamese conventions, shared tasks
+```
+
+## Development
+
+```bash
+pip install -e .
+pytest
+ruff check . && ruff format --check .
+python scripts/sync_version.py --check
+for generator in scripts/*/gen_*.py; do python "$generator" --check; done
+```
+
+`src/get_fsa_training_done/__about__.py` holds the canonical version;
+`sync_version.py` propagates it to the payload's `VERSION`.
+
+## Licence
+
+MIT

get_fsa_training_done-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "get-fsa-training-done"
+dynamic = ["version"]
+description = "One agent skill, and the CLI behind it, for getting FSA training done: programmes, teaching material and assessments. Installs into Claude Code and Codex."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Phuong Bui" }]
+keywords = ["assessment", "curriculum", "grading", "claude-code", "codex", "agent-skill"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Intended Audience :: Education",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Education :: Testing",
+]
+
+# The package itself declares nothing, deliberately: `pip install
+# get-fsa-training-done` pulls no transitive tree, and every lifecycle command
+# (install, update, status, doctor) runs on a bare interpreter.
+#
+# The libraries the *workers* need live in the managed venv instead, listed in
+# `envmgr/requirements/core.txt` and pre-warmed by `install`. So the offline
+# guarantee still holds — after the first install, which needs a network.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/phuongbv00/get-fsa-training-done"
+Issues = "https://github.com/phuongbv00/get-fsa-training-done/issues"
+
+[project.scripts]
+get-fsa-training-done = "get_fsa_training_done.cli:run"
+gftd = "get_fsa_training_done.cli:run"
+
+[tool.hatch.version]
+path = "src/get_fsa_training_done/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+# The skill's payload is data inside this one package, so the default
+# packages declaration already covers everything — no force-include needed.
+packages = ["src/get_fsa_training_done"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/scripts",
+  "/README.md",
+  "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+ignore = ["B008"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

get_fsa_training_done-1.0.0/scripts/assessment/gen_levels_md.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Generate the assessment skill's `references/levels.md` from the shared level table.
+
+The model reads the Markdown; `verify` and the CLI read the Python. Writing the
+Markdown by hand would guarantee they drift, and drift here is invisible — the
+workflow would quietly calibrate to numbers the verifier does not check against.
+So the table is generated, and `--check` fails CI when it is stale.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "src"))
+
+from get_fsa_training_done.features.common import levels as L  # noqa: E402
+
+TARGET = (
+    ROOT
+    / "src"
+    / "get_fsa_training_done"
+    / "payload"
+    / "get-fsa-training-done"
+    / "references"
+    / "assessment"
+    / "levels.md"
+)
+
+HEADER = """# Levels
+
+Every assessment is calibrated for exactly one level. It is a required input
+when planning, and it changes the Bloom mix, the difficulty mix, the duration,
+how much of the specification is handed over, and how strict the rubric is.
+
+Two axes, because they answer different questions:
+
+- **UP_SKILL** — same technology stack, greater depth. The candidate already
+  works in this stack; the assessment probes how far.
+- **RE_SKILL** — an experienced engineer arriving from a *different* stack.
+  Transferable reasoning is high but stack-specific recall is not assumed, so
+  these assessments use migration, integration, and modernisation framing and
+  never reward knowing an idiom by heart.
+
+`CPL` and `FR` have no bands. `UP_SKILL` and `RE_SKILL` each split into
+`junior` / `mid` / `senior`.
+
+The level goes in the display code and a `Level:` banner line — **never in the
+filename stem**, which would break rubric discovery and the submission archive
+naming the grading pipeline depends on.
+
+> These are defaults. Confirm them with the user when planning and adjust when
+> the subject warrants it; state any deviation in the plan echo.
+> `get-fsa-training-done assessment verify` reports drift from the level default
+> as a warning, not an error.
+
+<!-- Generated by scripts/assessment/gen_levels_md.py from
+     src/get_fsa_training_done/features/common/levels.py.
+     Do not edit by hand; edit the Python and regenerate. -->
+
+## At a glance
+
+"""
+
+
+def render() -> str:
+    lines = [HEADER.rstrip("\n"), ""]
+
+    bloom_cols = " | ".join(name[:2] for name in L.BLOOM_ORDER)
+    difficulty_cols = " | ".join(L.DIFFICULTY_ORDER)
+    lines.append(f"| Level | Audience | {bloom_cols} | {difficulty_cols} | Tasks | Duration |")
+    numeric = len(L.BLOOM_ORDER) + len(L.DIFFICULTY_ORDER)
+    lines.append("|---|---|" + "---:|" * numeric + "---:|---:|")
+    for level in L.LEVELS:
+        bloom = " | ".join(str(level.bloom.get(name, 0)) for name in L.BLOOM_ORDER)
+        difficulty = " | ".join(str(level.difficulty.get(name, 0)) for name in L.DIFFICULTY_ORDER)
+        tasks = f"{level.task_range[0]}-{level.task_range[1]}"
+        lines.append(
+            f"| **{level.display}** | {level.audience} | {bloom} | {difficulty} | "
+            f"{tasks} | {level.duration_factor}x |"
+        )
+
+    lines.append("")
+    lines.append(
+        f"Bloom columns are {', '.join(L.BLOOM_ORDER)}, as percentages of the question set. "
+        "Duration is a multiplier on the baseline you would set for a fresher."
+    )
+    lines.append("")
+    lines.append("## Per level")
+    lines.append("")
+
+    for level in L.LEVELS:
+        lines.append(f"### {level.display}")
+        lines.append("")
+        lines.append(f"- **Audience** — {level.audience}")
+        lines.append(f"- **Scope** — {level.scope}")
+        lines.append(f"- **Rubric posture** — {level.rubric_posture}")
+        lines.append(
+            "- **Mechanisms** — "
+            + (
+                "may be named directly in the brief"
+                if level.may_name_mechanism
+                else "state the outcome and let the candidate choose the mechanism; "
+                "the rubric still names it so criteria stay observable"
+            )
+        )
+        seconds = ", ".join(
+            f"{name} {level.time_map[name]}s"
+            for name in L.DIFFICULTY_ORDER
+            if name in level.time_map
+        )
+        lines.append(f"- **Seconds per question** — {seconds} (quiz always uses 5/10/20)")
+        if level.notes:
+            lines.append(f"- **Note** — {level.notes}")
+        lines.append("")
+
+    lines.append("## Question counts")
+    lines.append("")
+    lines.append(
+        "Percentages become whole questions by largest remainder, so the counts always "
+        "sum to the requested total. Ask the CLI rather than doing the arithmetic:"
+    )
+    lines.append("")
+    lines.append("```bash")
+    lines.append(
+        "get-fsa-training-done assessment levels show --level UP_SKILL --band mid --count 40"
+    )
+    lines.append("```")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail if the file is stale")
+    args = parser.parse_args()
+
+    content = render()
+    current = TARGET.read_text(encoding="utf-8") if TARGET.is_file() else ""
+
+    if args.check:
+        if current != content:
+            print(f"ERROR: {TARGET.relative_to(ROOT)} is out of date", file=sys.stderr)
+            print("run `python scripts/assessment/gen_levels_md.py` to regenerate", file=sys.stderr)
+            return 1
+        print("levels.md is up to date")
+        return 0
+
+    TARGET.parent.mkdir(parents=True, exist_ok=True)
+    TARGET.write_text(content, encoding="utf-8")
+    print(f"wrote {TARGET.relative_to(ROOT)} ({len(L.LEVELS)} levels)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

get_fsa_training_done-1.0.0/scripts/material/gen_structure_md.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Generate the material skill's `references/structure.md` from `core/grammar.py`.
+
+The model writes documents from this file; `verify` checks them against the
+Python. Prose describing a required section the checker does not enforce would
+calibrate the model to a constraint nothing holds it to — and prose omitting one
+it does enforce produces documents that fail a check the docs never mentioned.
+So the templates and the rulebook are both generated, and `--check` fails CI
+when either is stale.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "src"))
+
+from get_fsa_training_done.features.material.core import grammar as G  # noqa: E402
+from get_fsa_training_done.features.material.core import rules as R  # noqa: E402
+
+TARGET = (
+    ROOT
+    / "src"
+    / "get_fsa_training_done"
+    / "payload"
+    / "get-fsa-training-done"
+    / "references"
+    / "material"
+    / "structure.md"
+)
+
+HEADER = """# Document structure
+
+What each kind of teaching document is shaped like, and every rule
+`FSA material verify` applies. Both come from the same definitions the checker
+executes, so nothing here is a constraint the tool does not enforce.
+
+**Write new lecture notes as a unit.** The chapter form is older, still used by
+two modules, and is recognised so those files can be checked rather than
+rewritten — not because it is a choice for new work.
+
+Universal, whatever the kind:
+
+- Exactly one `#` heading, on line 1. No YAML front matter.
+- Every fenced block declares a language. `text` is the right tag for the blocks
+  that are not code — diagrams, console output, directory trees.
+- Relative links resolve, and so do their `#anchors`.
+- English, unless the filename ends `_vn` to mark a translation.
+
+<!-- Generated by scripts/material/gen_structure_md.py from
+     src/get_fsa_training_done/features/material/core/{grammar,rules}.py.
+     Do not edit by hand; edit the Python and regenerate. -->
+"""
+
+
+def render() -> str:
+    lines = [HEADER, "\n## Naming\n"]
+    lines.append(f"- Lecture notes, handbooks and appendices: `{G.NOTE_FILENAME.pattern}`")
+    lines.append(f"- Lab guides: `{G.LAB_FILENAME.pattern}`")
+    lines.append(f"- Index `{G.HANDBOOK_INDEX}` is the module handbook.")
+    lines.append(f"- Index `{G.APPENDIX_INDEX}` is the module appendix.")
+    lines.append(
+        "- A trailing letter marks an aside outside the syllabus (`02b_...`).\n"
+        f"- A translation appends `{G.TRANSLATION_SUFFIX}` to the stem.\n"
+    )
+
+    for template in G.TEMPLATES:
+        lines.append(f"\n## {template.title}\n")
+        lines.append(f"{template.summary}\n")
+        if template.numbered_sections:
+            lines.append(
+                "Sections between the opening and the closing ones are numbered "
+                "`1..n`, contiguously, and named by the author.\n"
+            )
+        if template.slots:
+            lines.append("| Section | Required | Holds |")
+            lines.append("|---|---|---|")
+            for slot in template.slots:
+                required = "yes" if slot.required else "optional"
+                lines.append(f"| `## {slot.label}` | {required} | {slot.description} |")
+            lines.append("")
+            for slot in template.slots:
+                if slot.opening is not None:
+                    lines.append(
+                        f"`## {slot.label}` must open with `{slot.opening.pattern.lstrip('^')}`.\n"
+                    )
+        if template.footer_description:
+            lines.append(f"Ends with {template.footer_description}\n")
+
+    lines.append("\n## Fence languages\n")
+    lines.append(
+        "Anything outside this set is reported as a warning rather than an "
+        "error — a module may legitimately introduce a language.\n"
+    )
+    lines.append(", ".join(f"`{name}`" for name in G.FENCE_LANGUAGES) + "\n")
+
+    for scope, title, blurb in (
+        ("document", "Rules — one document", "Applied to every file `verify` reads."),
+        (
+            "coverage",
+            "Rules — material against the session plan",
+            "Applied by `coverage`, comparing a folder with the plan that asks for it.",
+        ),
+    ):
+        in_scope = [rule for rule in R.RULES if rule.scope == scope]
+        lines.append(f"\n## {title}\n")
+        lines.append(f"{blurb}\n")
+        lines.append("| Rule | Severity | Checks |")
+        lines.append("|---|---|---|")
+        for rule in in_scope:
+            lines.append(f"| `{rule.id}` | {rule.severity} | {rule.title} |")
+        lines.append("")
+        for rule in in_scope:
+            lines.append(f"### `{rule.id}` — {rule.title}\n")
+            lines.append(f"{rule.rationale}\n")
+
+    counts = {
+        severity: sum(1 for rule in R.RULES if rule.severity == severity)
+        for severity in ("error", "warning")
+    }
+    lines.append(
+        f"---\n\n{len(R.RULES)} rules: {counts['error']} errors, {counts['warning']} warnings.\n"
+    )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail if the file is stale")
+    args = parser.parse_args()
+
+    content = render()
+    current = TARGET.read_text(encoding="utf-8") if TARGET.is_file() else ""
+
+    if args.check:
+        if current != content:
+            print(f"ERROR: {TARGET.relative_to(ROOT)} is out of date", file=sys.stderr)
+            print(
+                "run `python scripts/material/gen_structure_md.py` to regenerate", file=sys.stderr
+            )
+            return 1
+        print("structure.md is up to date")
+        return 0
+
+    TARGET.parent.mkdir(parents=True, exist_ok=True)
+    TARGET.write_text(content, encoding="utf-8")
+    print(f"wrote {TARGET.relative_to(ROOT)} ({len(G.TEMPLATES)} templates, {len(R.RULES)} rules)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())