Merge pull request 'fix(nixfiles): fix formatting stuff' (#63) from ci/format-check-all-prs into main

Reviewed-on: #63

.gitea/workflows/ci.yaml

@@ -1,15 +1,21 @@
-# Flake CI: full `nix flake check` (formatting + deadnix + statix + pre-commit)
-# plus an explicit per-host evaluation pass for granular output.
+# Flake CI. Formatting (treefmt) runs on *every* PR; the heavier Nix work
+# (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
-# 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
-# the job still passes. The required check is therefore always green-reportable.
+# always reports.
+#
+# Two tiers of checks:
+#   * 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
-      # against its base and look for files that can affect the flake: any .nix,
-      # the lockfile, or this workflow. On any other event (push to main) always
-      # run. The job itself always succeeds, so the required status check is
-      # reported even when the heavy steps are skipped.
+      # Decide whether the *heavy* Nix steps need to run. On a pull_request, diff
+      # against the base for files that can affect them: any .nix, the lockfile,
+      # or this workflow. On any other event (push to main) always run. The
+      # formatting step below is unaffected -- it always runs.
       - name: Detect Nix-relevant changes
         id: detect
         run: |
@@ -45,16 +50,16 @@ 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@8aa03977d8d733052d78f4e008a241fd1dbf36b3 # v31
+        uses: cachix/install-nix-action@a49548c11d9846ad46ecc0115273879b045f001c # v31
         with:
           extra_nix_config: |
             experimental-features = nix-command flakes
@@ -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

@@ -0,0 +1,63 @@
+# Working on this flake
+
+Project notes for changes to this repository. Persona and memory rules live in
+the user-global config; this file is about the flake's checks and conventions.
+
+## Before you commit: run the formatter
+
+Formatting and linting are driven by the flake. CI (`.gitea/workflows/ci.yaml`)
+runs `nix flake check`, which fails the build if any file is unformatted or trips
+a lint. From the repo root:
+
+- `nix fmt` — format the whole tree (writes changes).
+- `nix flake check` — run every check read-only (what CI runs).
+- `nix develop` — dev shell; its `shellHook` installs the git pre-commit hooks so
+  the same gates run on `git commit`.
+
+Never commit with `--no-verify`. A bypassed commit ships unformatted content and
+turns CI red on the next push to `main` (see "Docs are checked too").
+
+## What gets checked
+
+Defined in `flake.nix` (the `treefmt`, `pre-commit`, and `checks` blocks) and
+`statix.toml`:
+
+| Check        | Tool                              | Covers                                                  |
+| ------------ | --------------------------------- | ------------------------------------------------------- |
+| `formatting` | treefmt → `nixfmt`                | all `*.nix`                                             |
+| `formatting` | treefmt → `shfmt`                 | shell scripts                                           |
+| `formatting` | treefmt → `prettier`              | **Markdown, YAML, JSON** (incl. `README.md`, this file) |
+| `deadnix`    | deadnix                           | dead Nix bindings (`--no-lambda-pattern-names`)         |
+| `statix`     | statix                            | Nix antipatterns (config in `statix.toml`)              |
+| pre-commit   | nixfmt-rfc-style, deadnix, statix | the same gates, run on commit                           |
+
+Excluded from formatting: `*/hardware-configuration.nix` (generated by
+`nixos-generate-config`) and `flake.lock`. Editor defaults (indent, EOL, final
+newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which
+encodes hard line breaks.
+
+## 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.
+
+The CI `formatting` step runs on **every** PR — including docs- and config-only
+changes — so a Markdown/YAML/JSON edit is format-checked before merge, not just
+after it lands on `main`. (The heavier `deadnix`/`statix`/`pre-commit` lints and
+the per-host evaluation still run only when a `.nix` file, `flake.lock`, or the
+workflow changed; see `.gitea/workflows/ci.yaml`.) Run `nix fmt` before you
+commit and the formatting check stays green.
+
+## Host evaluation
+
+CI also evaluates every `nixosConfigurations` / `darwinConfigurations` host's
+toplevel (eval only, no build) on an x86_64 runner, so eval errors fail cheaply.
+Reproduce locally:
+
+```sh
+nix eval --raw ".#nixosConfigurations.<host>.config.system.build.toplevel.drvPath"
+```
+
+Host lists are discovered from the flake, so adding or removing a host needs no
+change to the workflow.

home/claude/memory/MEMORY.md

@@ -5,7 +5,9 @@
 - [Git commit signing](git_commit_signing.md) — signs in-sandbox via ssh-agent (allowAllUnixSockets + inlined pubkey)
 - [Git check state first](git_check_state.md) — always check branch/status/divergence before git work; Lyra edits repos between sessions
 - [Keep docs updated](docs_keep_updated.md) — update docs in the same pass as code/config changes; stale docs are a defect
+- [SIBO Workabout MX project](sibo_workabout_mx_scanner.md) — RE + barcode-inventory project state; scanner is an OO DYL object (oscanner), blocked on on-device ordinal capture; resume via code/inventory/CONTINUATION.md
 - [Jira tooling](jira_tooling.md) — comments are Markdown not wiki; transitions may need assignee; link direction; WSP transition IDs
 - [Review and comments workflow](workflow_review_and_comments.md) — show PR body and non-trivial Jira comments before posting; terse IaC code comments; PR body content rules
 - [Sandbox prompts](feedback_sandbox_prompts.md) — don't prompt for sandbox-disable or routine read-only shell ops; broaden permissions instead
 - [Dev clusters disposable](dev_clusters_disposable.md) — Lyra's dev clusters are recreatable; mutate/break freely, no confirmation needed
+- [Nix shell tooling](nix_shell_tooling.md) — any nixpkgs tool runs ad hoc via `nix run`/`nix shell nixpkgs#<pkg>`; a missing command is never a dead end

home/claude/memory/nix_shell_tooling.md

@@ -0,0 +1,23 @@
+---
+name: nix-shell-tooling
+description: "Any nixpkgs tool can be run ad hoc via nix run / nix shell — a missing command is never a dead end during development"
+metadata:
+  node_type: memory
+  type: feedback
+  originSessionId: dfb56b58-518b-4daf-b531-7119bb4a9534
+---
+
+Any tool in nixpkgs can be run without installing it into the environment. If a
+command is missing during development, pull it from nixpkgs on the fly instead
+of working around its absence or reporting the tool as unavailable.
+
+**Why:** Lyra runs NixOS; the ambient PATH is deliberately minimal, but the full
+nixpkgs set is always one command away. "command not found" is not a blocker.
+
+**How to apply:**
+
+- One-off run: `nix run nixpkgs#<pkg> -- <args>` (e.g. `nix run nixpkgs#jq -- .`).
+- Tools on PATH for a session: `nix shell nixpkgs#<pkg> [nixpkgs#<pkg2> ...]`,
+  then run commands normally.
+- Legacy form also works: `nix-shell -p <pkg> --run '<cmd>'`.
+- Prefer this over hand-rolling a substitute for a tool that exists in nixpkgs.

home/claude/memory/sibo_workabout_mx_scanner.md

@@ -0,0 +1,25 @@
+---
+name: sibo-workabout-mx-scanner
+description: State of the Psion Workabout MX reverse-engineering / barcode-inventory project and how to resume it
+metadata:
+  node_type: memory
+  type: project
+  originSessionId: 74de014e-9cf4-47f6-92f4-c34197ac1858
+---
+
+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.
+- The **ROM `w2mx_v7.20f_eng.bin`** and the full **SDK + HDK** (manuals as `docs/*.txt`; headers/libs/`bar*.ldd` under `code/SIBOSDK/`; HDK under `code/HDK/`) are on the branch. `/tmp/claude/sibo/` working files (ROM slices, MAME rom dir, Ghidra/decomp output) are transient and reproducible from the toolchain doc.
+
+**Scanner — key result:** the integral laser is driven as an **OO library object** in `SCANNER.DYL` (category token **`oscanner`**) via `p_getlibh` → `p_newsend`/`f_newsend` → `p_send`, over **LIBMANAGER (INT 0x84)** / **MESSMANAGER (INT 0x83)** — NOT raw device I/O. Confirmed on the physical device: `p_open("WL2:D")` + control ops **6** then **7** (`p_iow(chan,6); p_iow(chan,7)`) fire the laser to a good decode (green LED). Default Symbol2 11-byte param block: `04 3f 01 15 06 04 1e 80 0d 0a 06` (decoded output is CR/LF-terminated). Dead ends (do not retry): raw `TTY:D` reads, and the wand `BAR:` / `bar*.ldd` decoders (probe expansion slots → `-41`).
+
+**Blocked on / next step:** the OO **message ordinals + parameter structs** for init / set-params / trigger / read. OLIB assigns ordinals dynamically across the class hierarchy (base classes in `olib`/`hwim`), so they resolve only at runtime — capture them with the **SIBO Debugger on the physical device** (remote debug over serial; it supports breakpoints inside DYLs). MAME cannot inject a barcode, so the last mile must be on hardware. Full step-by-step is in `code/inventory/CONTINUATION.md`.
+
+**RE toolchain (reproducible):** the ROM is MAME machine **`psionwamx`**; run its debugger headless via `xvfb-run -a mame psionwamx -rompath roms -debug -debugscript CMDS -sound none -seconds_to_run N` (MAME lua input injection into the keyboard matrix does NOT work headless — a known limitation). Static: **radare2** (16-bit x86). Decompile: **Ghidra headless** (processor `x86:LE:16:Real Mode`, a Java GhidraScript — Ghidra 12 has no bundled Python). Get MAME/radare2/Ghidra via `nix-shell -p ...`. Details in `docs/mx-re/toolchain-and-plan.md`.
+
+**Fallback to deliver value now:** Phase 2 (the DBF inventory: add stock, consume by quantity) can be built with keyboard UPC entry against `docs/reference/05-filesystem-dbf.md`, dropping the scanner in behind the same interface once retrieval is finished. [[docs-keep-updated]]