.gitea/workflows/ci.yaml

@@ -1,15 +1,21 @@
-# Flake CI: full `nix flake check` (formatting + deadnix + statix + pre-commit)
+# Flake CI. Formatting (treefmt) runs on *every* PR; the heavier Nix work
-# plus an explicit per-host evaluation pass for granular output.
+# (deadnix/statix/pre-commit lints + per-host evaluation) runs only when the
+# change can affect it.
 name: CI
 
 # Deliberately no `paths:` filter. This job is a required status check on main,
 # and a path-filtered workflow is *skipped* (never runs) for PRs that touch no
 # matching file -- which leaves the required check pending forever and blocks the
 # merge (e.g. a .renovaterc.json-only change). So the workflow always runs and
-# always reports. To avoid burning a full Nix evaluation on changes that can't
+# always reports.
-# affect it, the "detect" step below diffs the PR and the heavy steps run only
+#
-# when a .nix file, flake.lock, or this workflow changed; otherwise they skip and
+# Two tiers of checks:
-# the job still passes. The required check is therefore always green-reportable.
+#   * Formatting always runs. treefmt covers Markdown, YAML, and JSON as well as
+#     Nix and shell, so a docs- or config-only PR must be format-checked too. It
+#     is cheap (no host evaluation).
+#   * The heavy steps (full `nix flake check` + host evals) run only when a .nix
+#     file, flake.lock, or this workflow changed; otherwise they skip and the job
+#     still passes, keeping the required check green-reportable.
 on:
   push:
     branches: [main]
@@ -25,11 +31,10 @@ jobs:
           # Full history so the detect step can diff the PR against its base.
           fetch-depth: 0
 
-      # Decide whether the Nix steps need to run. On a pull_request, diff the PR
+      # Decide whether the *heavy* Nix steps need to run. On a pull_request, diff
-      # against its base and look for files that can affect the flake: any .nix,
+      # against the base for files that can affect them: any .nix, the lockfile,
-      # the lockfile, or this workflow. On any other event (push to main) always
+      # or this workflow. On any other event (push to main) always run. The
-      # run. The job itself always succeeds, so the required status check is
+      # formatting step below is unaffected -- it always runs.
-      # reported even when the heavy steps are skipped.
       - name: Detect Nix-relevant changes
         id: detect
         run: |
@@ -45,15 +50,15 @@ jobs:
           echo "Changed files:"
           echo "$changed"
           if echo "$changed" | grep -Eq '(\.nix$|^flake\.lock$|^\.gitea/workflows/ci\.yaml$)'; then
-            echo "Nix-relevant changes found: running checks."
+            echo "Nix-relevant changes found: running heavy checks."
             echo "run=true" >> "$GITHUB_OUTPUT"
           else
-            echo "No Nix-relevant changes: skipping checks (job still passes)."
+            echo "No Nix-relevant changes: heavy checks skip (formatting still runs)."
             echo "run=false" >> "$GITHUB_OUTPUT"
           fi
 
+      # Nix drives the formatting check, so install it unconditionally.
       - name: Install Nix
-        if: steps.detect.outputs.run == 'true'
         uses: cachix/install-nix-action@a49548c11d9846ad46ecc0115273879b045f001c # v31
         with:
           extra_nix_config: |
@@ -62,6 +67,13 @@ jobs:
             substituters = https://cache.nixos.org https://nix-community.cachix.org
             trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=
 
+      # Always run: treefmt formats Markdown/YAML/JSON (docs + config) as well as
+      # Nix and shell, so documentation-only PRs are format-checked too. This is
+      # the cheap gate (no host evaluation) and pre-builds the `formatting`
+      # derivation that the flake check below reuses from cache.
+      - name: Formatting check
+        run: nix build --print-build-logs '.#checks.x86_64-linux.formatting'
+
       # Runs every flake check: treefmt formatting, deadnix, statix, and the
       # pre-commit hooks (so a --no-verify commit can't ship unlinted).
       - name: Flake check

CLAUDE.md

@@ -36,18 +36,18 @@ Excluded from formatting: `*/hardware-configuration.nix` (generated by
 newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which
 encodes hard line breaks.
 
-## Docs are checked too — the common trap
+## Docs are checked too
 
 prettier formats `*.md`, so **documentation edits must be run through `nix fmt`**
 exactly like code. prettier re-aligns Markdown tables in particular; hand-editing
 a table almost always leaves it non-conformant and fails the `formatting` check.
 
-Beware a false green: the CI `detect` step skips the heavy checks on a pull
+The CI `formatting` step runs on **every** PR — including docs- and config-only
-request that touches **no** `.nix`, `flake.lock`, or the workflow file — so a
+changes — so a Markdown/YAML/JSON edit is format-checked before merge, not just
-docs-only PR reports success without ever running prettier. The failure then
+after it lands on `main`. (The heavier `deadnix`/`statix`/`pre-commit` lints and
-surfaces on the push-to-`main` run (which always runs the full check) or on the
+the per-host evaluation still run only when a `.nix` file, `flake.lock`, or the
-next unrelated PR that does touch Nix. Run `nix flake check` locally before
+workflow changed; see `.gitea/workflows/ci.yaml`.) Run `nix fmt` before you
-merging a docs change, regardless of what the PR check shows.
+commit and the formatting check stays green.
 
 ## Host evaluation
 

home/claude/memory/sibo_workabout_mx_scanner.md

@@ -10,6 +10,7 @@ metadata:
 Long-running project (July 2026) reverse-engineering the **Psion Workabout MX** (SIBO OS, NEC V30MX, TopSpeed C) to build a barcode **inventory demo** (scan UPC → DBF database file; add stock, consume by a quantity unit) and, alongside, **complete device programming documentation**. Repo: Gitea **lyrathorpe/sibo-playground**, working branch **`feat/inventory-phase1-scan`** (unmerged). Gitea needs hand-off / the contents API for pushes — see [[git-network-ops]]; [[git-conventions]] for branch/PR rules.
 
 **Committed on the branch (durable, survive reboot):**
+
 - `docs/reference/00-08` + index — the SIBO/MX programming reference (building apps, system/OS, I/O devices, PLIB core, file system & DBF, UI, hardware, and RE'd boot/OS-call internals).
 - `code/inventory/` — app scaffold: `upc.c/.h` (UPC-A check-digit validation, correct), `bcode.c/.h`, `scan.c` (Phase-1 diagnostics), `README.md`, **`SCANNER-API.md`** (all scanner findings), **`CONTINUATION.md`** (the on-device debugging procedure to finish).
 - `docs/mx-re/toolchain-and-plan.md` — the RE toolchain.