feat: robust docs

docs/guide/recipes.md

@@ -0,0 +1,119 @@
+# Recipes
+
+Short answers, for when you know the shape of the tool and want the invocation.
+
+## Assembly
+
+**Draw only from material I have taught.**
+`--lectures l09,l10,l11`.
+Combine with `--topics` and `--banks` to narrow further; the filters intersect.
+
+**See the draw before committing to it.**
+`--dry-run`.
+Prints the selection and any notes about constraints that had to bend, and writes nothing.
+
+**Reproduce a draw exactly.**
+`--seed N`.
+The same seed against the same pool gives the same items in the same order.
+Recorded in the assessment file, so a draw stays reproducible after the fact.
+
+**Two forms that differ only in option order.**
+`--forms 2`.
+Each form gets its own seed; item order is shared unless the form sets `shuffle_items`.
+
+**A blueprint I cannot satisfy.**
+The error names the level, how many items were asked for, and how many were available after filtering.
+Usually the fix is a shorter cooldown or a wider lecture range, not more items.
+
+## Reuse
+
+```console
+$ coursebank usage history q-align-recall-001
+$ coursebank usage unused
+```
+
+`unused` lists approved items never placed on an assessment, which is the queue of work you already did and forgot about.
+
+## Exports
+
+**A printable exam.**
+`coursebank export typst exam-2 --form all`.
+Add `--variant key` to write only the key.
+
+**A Canvas quiz.**
+`coursebank export qti exam-2 --form A`.
+Add `--no-feedback` to leave per-option feedback out of the package.
+
+**A Markdown copy for a colleague to read.**
+`coursebank export md exam-2`.
+Add `--with-key` for the answers and rationales.
+
+**Restyle the printed output.**
+`coursebank template dump`, then edit `templates/exam.typ`.
+See [`typst_export`](crate::guide::typst_export).
+
+## Ingest
+
+**Gradescope.**
+`coursebank ingest gradescope grading/exam-2/ --assessment exam-2`.
+Point it at the directory holding the per-question CSVs.
+
+**Canvas.**
+`coursebank ingest canvas export.csv --assessment exam-2`.
+The Student Analysis export, not the gradebook.
+
+**Keep student identities out of the repository.**
+`--pseudonymize --salt-file ~/.coursebank-salt`.
+Keep the salt outside the repository; the point of the salt is that hashed ids cannot be brute-forced over a class roster, which fails if the salt sits next to them.
+
+**Check a parse before writing.** `--dry-run`.
+
+## Analysis
+
+| Question | Command |
+|:--|:--|
+| Which items misbehaved? | `analyze items --assessment exam-2` |
+| How hard is each item, on a common scale? | `analyze irt --assessment exam-2 --model 2pl` |
+| Which students are struggling, and with what? | `analyze students --assessment exam-2` |
+| What is in the store? | `data` |
+
+Pool across terms by passing the assessment id rather than one administration id.
+Twenty-four students supports very little; ninety-six across four terms supports something.
+
+## Reports
+
+```console
+$ coursebank report students --assessment exam-2
+$ coursebank report cohort --assessment exam-2
+```
+
+The student report omits correct answers, other students' data, and any rank.
+Hand it out without a second pass.
+
+## After grading
+
+**An option turned out to be defensible.**
+Add `credit_overrides: {C: 0.5}` to the placement in the assessment record.
+Do not edit scores by hand, or item analysis sees different numbers than the students did.
+
+**An item was broken.**
+Add `dropped: true` to the placement.
+It leaves the scored matrix and is not printed on re-export, but the record of having asked it stays.
+
+**Statistics onto the items.**
+`coursebank calibrate --assessment exam-2`, read the diff, then `--apply`.
+
+## Housekeeping
+
+**Editor validation stopped working.**
+`coursebank schema` rewrites the JSON Schemas.
+They ship with the binary, so an upgrade can leave them stale.
+
+**A pre-commit hook.**
+`coursebank validate && coursebank lint`.
+Exit code `2` means findings, `1` means the command failed, so a hook can treat them differently.
+
+**Build without Parquet.**
+`pixi run build-lean`.
+The response store falls back to CSV.
+Useful if you want a binary with a shorter dependency list; the tradeoff is slower reads on large stores.