tests: wire check, pty and sanitizer targets and document them

4 files changed, 47 insertions, 10 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 0d04f7f..55408ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,9 +48,14 @@ Never rewrite ledger rows in a migration.
 
 1. Handler in `commands.c` (or the domain file it belongs to), using the
    `fail()/failf()` helpers and stable error codes from `PROTOCOL.md` §5.3.
-2. Entry in `g_commands[]` with permission, `need_org`, `mutating`, `dry_run`.
+2. Entry in `g_commands[]` with permission, `need_org`, `mutating`, `dry_run`
+   and a `CMD_ARGS(args_x)` name/type/required/default schema; the dispatcher
+   validates present arguments before the handler runs and `describe` emits
+   the schema.
 3. Audit (`audit_append`) for mutations, after success.
-4. Update `docs/PROTOCOL.md`; add tests in `tests/test_core.c`.
+4. Update `docs/PROTOCOL.md`; add tests in `tests/test_core.c`. `make check`
+   (part of `make test`) fails when a command or error code is missing from
+   PROTOCOL.md.
 5. `agent.instructions` in `commands.c` if agents need to know about it.
 
 ## Server code style
@@ -74,8 +79,12 @@ first (spec in `TUI-GUIDELINES.md` + tests in `tests/test_tui.c`).
 
 ## Verifying
 
-- Server changes: `make test`. UI changes: also drive `bokftui` over a pty
-  (`script -qec`) or against the demo daemon and check the real behaviour.
+- Server changes: `make test` (runs `make check`, the server suite and the TUI
+  unit tests). UI changes: also run `make test-pty`, which drives the real TUI
+  over a pty against a throwaway `/tmp` daemon and asserts on screen text.
+- Sanitizers: `make test-asan` (ASan) and `make test-ubsan` (UBSan) build
+  `test_core` in `build-asan`/`build-ubsan`. Run them after touching
+  allocation or arithmetic paths.
 - Never run `bokftui` for tests without `scripts/tui-sandbox.sh`: it
   isolates `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` so a run cannot overwrite the
   human's `~/.config/bokf/tui.conf`, `~/.cache/bokf/tui.log` or bw session.
diff --git a/Makefile b/Makefile
index d67e92e..86a5ffe 100644
--- a/Makefile
+++ b/Makefile
@@ -52,13 +52,27 @@ $(BUILD)/test_tui: $(BUILD)/tests/test_tui.o $(BUILD)/clients/tui.o \
                    $(BUILD)/vendor/sha256.o
 	$(CC) $(CFLAGS) -o $@ $^ -lm -lncursesw
 
-test: $(BUILD)/test_core $(BUILD)/test_tui
+test: check $(BUILD)/test_core $(BUILD)/test_tui
 	$(BUILD)/test_core
 	$(BUILD)/test_tui
 
 test-core: $(BUILD)/test_core
 	$(BUILD)/test_core
 
+check:
+	sh scripts/check-consistency.sh
+
+test-pty: all
+	python3 scripts/tui-golden.py
+
+SAN_CFLAGS = -O1 -g -fno-omit-frame-pointer
+
+test-asan:
+	$(MAKE) BUILD=build-asan CFLAGS="$(SAN_CFLAGS) -fsanitize=address" test-core
+
+test-ubsan:
+	$(MAKE) BUILD=build-ubsan CFLAGS="$(SAN_CFLAGS) -fsanitize=undefined" test-core
+
 $(BUILD)/vendor/%.o: vendor/%.c
 	@mkdir -p $(dir $@)
 	$(CC) $(CFLAGS) $(DEPFLAGS) $(CPPFLAGS) $(DEFS) -w -c $< -o $@
@@ -87,6 +101,7 @@ install: all
 	install -m 0644 data/bas_k2.csv data/bas_k3.csv $(DESTDIR)/usr/local/share/bokf/
 
 clean:
-	rm -rf $(BUILD)
+	rm -rf $(BUILD) build-asan build-ubsan
 
-.PHONY: all backend test test-core install clean
+.PHONY: all backend test test-core test-pty check test-asan test-ubsan \
+        install clean
diff --git a/README.md b/README.md
index f13f5ed..8559ca2 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,11 @@ make -j$(nproc)
 make test
 ```
 
+`make test` runs the server/protocol suite, the TUI unit tests and a docs/code
+consistency check. Extra targets: `make test-asan` / `make test-ubsan`
+(sanitizers) and `make test-pty` (drives the real TUI over a pty against a
+throwaway `/tmp` daemon and asserts on screen text).
+
 Produces `build/bokfd` (daemon), `build/bokfctl` (CLI) and `build/bokftui`
 (ncurses UI). Builds on x86_64 and arm64 (Armbian, Raspberry Pi, …).
 
diff --git a/docs/STATE.md b/docs/STATE.md
index 9f2f29f..aae9906 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -6,9 +6,10 @@ and `docs/TUI-GUIDELINES.md` (UI conventions). Dated 2026-09-19.
 ## Status
 
 Working self-hosted bookkeeping system, not production-proven. Backend ledger
-core is complete; filing/year-end/payroll are not. TUI is usable and
-exercised via pty smoke tests; the test suite (`make test`) covers the
-server/protocol/ledger only.
+core is complete; filing/year-end/payroll are not. TUI is usable and exercised
+by `make test-pty` (golden screen-text scenarios); `make test` covers the
+server/protocol/ledger, the TUI widget unit tests and the docs consistency
+check.
 
 ## Locked decisions
 
@@ -229,6 +230,13 @@ server/protocol/ledger only.
 
 ## Known caveats
 
+- Developer tooling (2026-09-20): `g_commands[]` carries declarative argument
+  schemas (`CMD_ARGS`); `describe` emits them and the dispatcher validates
+  before the handler runs. `make check` (part of `make test`) fails when a
+  command or error code is missing from `PROTOCOL.md`
+  (`scripts/check-consistency.sh`). `make test-asan`/`test-ubsan` build
+  `test_core` with sanitizers; `make test-pty` runs `scripts/tui-golden.py`
+  (dashboard, audit, vouchers) against a throwaway `/tmp` daemon.
 - Never commit unless the human asks.
 - SQLite files must not be backed up live with restic; use
   `backup.snapshot` (`VACUUM INTO`) and point restic at the snapshots.