casebench

commit f9d7e68b50430f4781fa2ce316ae73d54ed85b6a
parent 3354c6713e1f15c2050de2cd98b861c460056019
author Owen Rusk <owen@papermothgames.com>
date   2026-09-22 16:08:31 -0500

readme: commands, configuration, the case folder

diff --git a/README.md b/README.md
index 9f1771a..458c297 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,54 @@
 
 Test cases go straight to the board. The runtime never sees them. Reaches the board and nothing else.
 
-    casebench put path/to/case --player owen
-    casebench note CASE "text" [--item ITEM] --player owen
-    casebench lock CASE --answer A [--answer B] [--rest 3/60] --player owen
-    casebench unlock CASE --player owen
-    casebench list [--player owen]
-    casebench pull CASE --player owen
+## commands
 
-needs CASEBENCH_DSN, pointing at the hub's postgres.
+    casebench put FOLDER --player HANDLE
+    casebench note CASE "text" [--item ITEM] --player HANDLE
+    casebench note CASE -f note.md [--item ITEM] --player HANDLE
+    casebench lock CASE [--answer A ...] [--rest 3/60] [--text locked.] --player HANDLE
+    casebench unlock CASE --player HANDLE
+    casebench list [--player HANDLE]
+    casebench pull CASE --player HANDLE
 
-tests: `python -m unittest`
+every command that writes takes `--player` (more than once is fine) or `--all`, for every board. `list` without `--player` lists every board.
+
+- `put` puts the case on the board, or replaces its title and items if it's there already. notes and a lock stay. it won't put a case over one the runtime put there.
+- `note` writes under the case's title, or on an item with `--item`. `-f -` reads stdin.
+- `lock` takes one `--answer` per line of the lock, or asks for them if there's none. `a|b` takes either. lines are checked together, so a wrong try never says which line was right. only salted hashes are stored.
+- `--rest 3/60`: after 3 wrong tries in a row the lock takes nothing for 60 minutes.
+- `pull` only pulls what the bench put there.
+
+## configuration
+
+- `CASEBENCH_DSN`: the hub's postgres.
+- `CASEBENCH_REST`: the default for `--rest`. 3/60 if unset.
+
+`schema.sql` has the board tables as the bench expects them, for a local database.
+
+## a case folder
+
+    case.yaml
+    items/ticket.md
+    items/umbrella.svg
+
+```yaml
+id: test-lost-umbrella
+title: The lost umbrella
+items:
+  - id: ticket
+    title: Cloakroom ticket
+    text: items/ticket.md
+  - id: umbrella
+    title: The umbrella
+    text: items/umbrella.md
+    images: [items/umbrella.svg]
+```
+
+ids are lowercase, digits and dashes. images: png, jpg, webp, svg. `examples/lost-umbrella` is a whole one.
+
+## tests
+
+    python -m unittest
+
+against the memstore. no database needed.