Align repository guidance for coding agents

.gitattributes

@@ -6,7 +6,7 @@
 *.bat text eol=crlf
 *.cmd text eol=crlf
 
-# Freeze the stock Gradle wrapper exactly as committed (CLAUDE.md: do NOT alter gradlew*).
+# Freeze the stock Gradle wrapper exactly as committed (AGENTS.md: do NOT alter gradlew*).
 gradlew     -text
 gradlew.bat -text
 

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
           cache-read-only: false
       # lintDebug enforces the shrink-only baseline (R5a step 4: "CI fails on any new violation");
       # runner JDK is 17 so the JDK-21 UAST hazard doesn't apply here.
-      - run: ./gradlew :app:testDebugUnitTest :app:lintDebug :app:assembleDebug --no-daemon
+      - run: ./scripts/check.sh --gradle-only
   # R9 step 5 (docs/top-down-audit-roadmap.md §R9): memory-hygiene guardrail.
   # Scope = tracked public docs that are meant to exist in normal clones. Local-only planning/evidence
   # plus AI workflow artifacts (.planning/, docs/commands/, docs/superpowers/) are intentionally outside
@@ -33,45 +33,5 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Stale-phrase check (tracked maintainer/public docs)
-        run: |
-          mapfile -t sources < <(
-            git ls-files README.md ':(glob)docs/*.md' ':(glob)docs/maintainer/*.md' \
-              ':!:docs/top-down-audit-roadmap.md' \
-              ':!:docs/superpowers/**' \
-              ':!:docs/commands/**'
-          )
-          if ((${#sources[@]})) && grep -rn "compileSdk 35\|Architecture not yet mapped" "${sources[@]}"; then
-            echo "FAIL: stale phrases found in tracked maintainer/public docs"; exit 1
-          fi
-          echo "OK: no stale phrases"
-      - name: Dead internal-link check (tracked maintainer/public docs)
-        run: |
-          rm -f /tmp/dead-links
-          mapfile -t sources < <(
-            git ls-files README.md ':(glob)docs/*.md' ':(glob)docs/maintainer/*.md' \
-              ':!:docs/top-down-audit-roadmap.md' \
-              ':!:docs/superpowers/**' \
-              ':!:docs/commands/**'
-          )
-          for src in "${sources[@]}"; do
-            [ -f "$src" ] || continue
-            dir=$(dirname "$src")
-            # Extract relative .md link targets: [text](path.md) / [text](path.md#anchor)
-            # `|| true` guards pipefail: grep exits 1 on no-match, which would kill the
-            # step under Actions' default `bash -e -o pipefail` before the dead-links check.
-            { grep -oE '\]\([^)# ]+\.md(#[^)]*)?\)' "$src" 2>/dev/null || true; } \
-              | sed -E 's/^\]\(//; s/#[^)]*//; s/\)$//' \
-              | sort -u \
-              | while read -r target; do
-                  case "$target" in
-                    http://*|https://*|*://*|/*|[A-Za-z]:/*|*'\'*) continue ;;  # skip URLs, absolute and Windows paths
-                  esac
-                  # accept either file-relative or repo-root-relative targets
-                  if [ ! -e "$dir/$target" ] && [ ! -e "$target" ]; then
-                    echo "DEAD LINK in $src -> $target" | tee -a /tmp/dead-links
-                  fi
-                done
-          done
-          if [ -s /tmp/dead-links ]; then echo "FAIL: dead internal links"; exit 1; fi
-          echo "OK: no dead internal links"
+      - name: Authoritative documentation hygiene
+        run: ./scripts/check.sh --docs-only

.gitignore

@@ -38,7 +38,6 @@ tools/__pycache__/
 
 # Internal planning / AI dev artifacts (local only — not in clones)
 .planning/
-/CLAUDE.md
 .claude/skills/
 docs/superpowers/
 # docs/commands/ is local-only evidence, EXCEPT the tracked artifacts CI requires in every clone:

AGENTS.md

@@ -0,0 +1,91 @@
+# jiib Agent Guide
+
+## Project
+
+jiib is a native Android control surface for Klipper 3D printers. It connects directly to
+Moonraker over the local network and must keep the connect → monitor → control-a-print loop reliable
+on old hardware.
+
+## Trust And Context
+
+Use current sources in this order:
+
+1. Source code, build configuration, and tests define current behavior.
+2. This file defines repository-wide working rules.
+3. `docs/maintainer/` explains current architecture, testing, releases, and documentation ownership.
+4. Scoped references such as `docs/ui_design/`, `docs/manual/`, `docs/commands/`, and accepted ADRs
+   are authoritative only for their stated subject.
+
+Ignored or local-only paths—including `.planning/`, `.superpowers/`, `.claude/skills/`,
+`docs/superpowers/`, and untracked reports—are historical or workflow context. Never treat them as
+current implementation guidance. Use them only for archaeology. When documentation conflicts with
+the implementation, verify the implementation and update the authoritative document as part of the
+change.
+
+## Non-Negotiable Constraints
+
+- Android 6.0 / API 23 is the support floor. Do not raise `minSdk` or add dependencies that do.
+- The Nexus 7 2013 (Adreno 320, 2 GB RAM) is the performance floor. Profile release builds; debug
+  Compose performance is not representative.
+- Support both portrait and landscape and the dark, light, custom-color, and S/M/L text settings.
+- The app is GMS-free and distributed as sideloaded per-ABI APKs.
+- Do not change the application ID, release signing model, ABI split strategy, or version scheme
+  without an explicit project decision.
+- Dependency versions are pinned. Do not make opportunistic dependency or build-tool upgrades.
+- Do not edit the checked-in Gradle wrapper scripts or wrapper JAR unless the task explicitly changes
+  the Gradle wrapper.
+
+## Canonical Commands
+
+- Run the normal local/CI gate: `./scripts/check.sh`
+- Run documentation hygiene only: `./scripts/check.sh --docs-only`
+- Run the Gradle gate only: `./scripts/check.sh --gradle-only`
+- Run a targeted host test: `./gradlew :app:testDebugUnitTest --tests <fully.qualified.Test> --no-daemon`
+
+Under WSL, `scripts/check.sh` automatically uses the Windows-side `E:\Android\gw.bat` helper so adb
+and the installed Android SDK remain reachable. CI and native Linux use the checked-in wrapper.
+Read `docs/maintainer/testing.md` before device-, printer-, or release-specific verification.
+
+## Architecture Boundaries
+
+- `MoonrakerService` owns the live printer session and publishes one atomic `SpineHandle`.
+- UI consumes the session spine, store-derived flows, or feature holders. UI must not construct
+  sockets, sessions, or raw JSON-RPC clients.
+- `state/` is headless state and reducers; `net/` is transport/protocol; `command/` is command specs
+  and dispatch; `service/` owns the session; `di/` exposes process wiring.
+- Keep feature state toolkit-agnostic where practical. Compose is the default UI toolkit; classic
+  Views are reserved for measured high-churn or render-heavy surfaces.
+- Put new code in the package that owns the behavior. Avoid generic dumping grounds.
+
+Read `docs/maintainer/architecture.md` before changing session ownership, reconnect behavior,
+printer switching, navigation, state flow, or major package responsibilities.
+
+## UI Changes
+
+Before changing screen structure, components, icons, colors, typography, layout, or control intent,
+read `docs/ui_design/AGENTS.md` and follow its reading order. Never guess or auto-select a glyph; use
+an existing approved asset or ask the owner when no selection exists. Update `docs/manual/` when
+user-visible behavior changes.
+
+## Testing And Completion
+
+- Add or update tests for behavior changes; add a regression test for a bug when practical.
+- Run the narrowest useful test while iterating, then the canonical gate before completion.
+- Device-dependent work may require instrumented tests and manual hardware/printer verification.
+- Do not grow the lint baseline to hide new violations.
+- Command-registry and reference changes must keep their drift tests and tracked generated artifacts
+  synchronized.
+
+## Security And Release Safety
+
+- Never commit API keys, printer credentials, keystores, signing passwords, or credential-bearing
+  `local.properties` content.
+- Do not log credentials or sensitive Moonraker payloads.
+- A release build can succeed unsigned. Follow `docs/maintainer/release.md`; never publish an APK
+  without explicitly verifying its signature and ABI.
+
+## Documentation Rule
+
+Update the owning document whenever a change alters how someone builds, tests, releases, configures,
+extends, or reasons about the system. Prefer links over copied facts. Delete or correct stale guidance
+immediately; do not preserve it inside an authoritative document merely for history.

CLAUDE.md

@@ -0,0 +1,4 @@
+# Claude Code Instructions
+
+Read and follow [AGENTS.md](AGENTS.md). It is the single repository-wide source of coding-agent
+instructions. This file intentionally adds no duplicate project rules.

README.md

@@ -88,6 +88,13 @@ Kotlin · Jetpack Compose + classic Views hybrid · OkHttp (WebSocket) + Retrofi
 kotlinx.serialization · Coroutines/Flow · Coil. See `docs/adr/0001-ui-toolkit-decision.md`
 for the UI-toolkit rationale and `docs/ui_design/` for the design system.
 
+## Maintainer guide
+
+Coding agents and contributors should start with [`AGENTS.md`](AGENTS.md). Current architecture,
+testing, release, and documentation-ownership guidance lives in
+[`docs/maintainer/`](docs/maintainer/README.md). Run `./scripts/check.sh` for the normal verification
+gate.
+
 ## License
 
 [GPLv3](LICENSE).

docs/adr/0001-ui-toolkit-decision.md

@@ -13,7 +13,7 @@ touchscreen in **Jetpack Compose everywhere** or use **classic Views** for the h
 The constraint is an **Adreno 320 / 2 GB / 1920×1200** tablet — fill-rate-bound, high-resolution,
 old GPU. A janky printer screen is worse than none, so this is decided by measurement, not preference.
 
-**The CLAUDE.md research prior leaned Compose ("HIGH confidence")** for dev velocity and modern
+**The initial project research leaned Compose ("HIGH confidence")** for dev velocity and modern
 tooling, while explicitly naming a **hybrid-Views fallback** for high-churn surfaces (Files list,
 temperature graph, Console scrollback) if measurement demanded it. This ADR is that measurement.
 

docs/maintainer/README.md

@@ -6,12 +6,16 @@ Use these docs when changing the app, reviewing AI-generated patches, or re-orie
 from the project. Historical planning notes under `.planning/` are local-only project memory and may
 contain stale package names, old navigation concepts, or retired implementation details.
 
+Repository-wide working rules and the trust hierarchy live in [AGENTS.md](../../AGENTS.md). Read it
+first. These maintainer documents provide the detail that the short root instruction file routes to.
+
 ## Reading Order
 
-1. [Architecture](architecture.md) - current app structure, session spine, navigation, state flow, and UI boundaries.
-2. [Testing](testing.md) - CI, local verification commands, device tests, fixtures, and docs-only verification.
-3. [Release](release.md) - manual release runbook, versioning, signing, split APKs, and smoke checks.
-4. [Doc Maintenance](doc-maintenance.md) - rules for keeping current docs, manuals, design docs, and local evidence in sync.
+1. [Root agent guide](../../AGENTS.md) - repository-wide constraints, commands, boundaries, and trust rules.
+2. [Architecture](architecture.md) - current app structure, session spine, navigation, state flow, and UI boundaries.
+3. [Testing](testing.md) - CI, local verification commands, device tests, fixtures, and docs-only verification.
+4. [Release](release.md) - manual release runbook, versioning, signing, split APKs, and smoke checks.
+5. [Doc Maintenance](doc-maintenance.md) - rules for keeping current docs, manuals, design docs, and local evidence in sync.
 
 ## Existing Docs To Use
 
@@ -22,7 +26,9 @@ contain stale package names, old navigation concepts, or retired implementation
 
 ## Local-Only Context
 
-- `docs/commands/` - local-only Moonraker/Klipper/Spoolman command evidence; gitignored and absent from normal public clones, except the tracked `catalog.json` and `printer-matrix.json` fixtures that `CommandCatalogDriftTest` requires in every clone.
+- `docs/commands/` - mostly local-only Moonraker/Klipper/Spoolman evidence. Public clones contain the
+  tracked `catalog.json` and `printer-matrix.json` fixtures plus the generated `COMMANDS.md` reference;
+  other files in the directory may be absent.
 - `.planning/` - local-only historical planning/project memory; gitignored and absent from normal public clones.
 
 ## What To Read Before Changing
@@ -35,7 +41,7 @@ contain stale package names, old navigation concepts, or retired implementation
 | Testing strategy or CI expectations | [Testing](testing.md) |
 | Release packaging, signing, or version bumps | [Release](release.md) |
 | Durable architecture decisions | [Doc Maintenance](doc-maintenance.md) and existing [ADRs](../adr/) |
-| Command contracts | [Architecture](architecture.md), `docs/commands/` (tracked `catalog.json`/`printer-matrix.json` plus local-only evidence), [CommandRegistry.kt](../../app/src/main/java/works/mees/jiib/command/CommandRegistry.kt), and [CommandCatalogDriftTest.kt](../../app/src/test/java/works/mees/jiib/command/CommandCatalogDriftTest.kt) |
+| Command contracts | [Architecture](architecture.md), [generated command reference](../commands/COMMANDS.md), tracked `catalog.json`/`printer-matrix.json`, [CommandRegistry.kt](../../app/src/main/java/works/mees/jiib/command/CommandRegistry.kt), and the command drift tests |
 
 ## Current Source Of Truth
 

docs/maintainer/doc-maintenance.md

@@ -4,12 +4,16 @@ This file defines which docs own current facts and how to keep them from driftin
 
 ## Current And Historical Sources
 
-Current maintainer facts live in `docs/maintainer/`.
+Repository-wide agent rules live in `AGENTS.md`; current maintainer explanations live in
+`docs/maintainer/`. Source code, build configuration, and tests remain the final authority for current
+behavior. Tool-specific instruction files such as `CLAUDE.md` are short pointers and must not copy
+project rules.
 
 Local-only historical/project-memory material lives in ignored paths such as:
 
 - `.planning/`
-- `docs/commands/` (except the tracked `catalog.json` and `printer-matrix.json` test fixtures)
+- untracked material under `docs/commands/` (the tracked exceptions are `catalog.json`,
+  `printer-matrix.json`, and the generated `COMMANDS.md` reference)
 - `docs/superpowers/` plans and evidence
 
 `docs/superpowers/` is local-only by policy: specs and plans are written there but never committed.
@@ -55,8 +59,8 @@ Update `docs/ui_design/` when visual law, layout grammar, tokens, typography, ic
 semantics change.
 
 Update the tracked `docs/commands/catalog.json` and `docs/commands/printer-matrix.json` fixtures,
-local-only `docs/commands/` evidence, and `CommandCatalogDriftTest` when Moonraker/Klipper/Spoolman
-command contracts change.
+generated `docs/commands/COMMANDS.md`, local-only command evidence, and both command drift tests when
+Moonraker/Klipper/Spoolman command contracts change.
 
 Add or update an ADR under `docs/adr/` when a durable architecture decision is made and future maintainers
 need the rationale.
@@ -77,8 +81,9 @@ maintainer docs; that makes the docs fail their own check.
 Negative historical facts may name retired concepts when needed. If they do, the stale-term scan must
 either allowlist those exact lines or the docs should be reworded to avoid the exact tokens.
 
-Run the stale-phrase and dead-link dry-runs in [Testing](testing.md#docs-only-changes). The source of
-truth for CI hygiene remains `.github/workflows/ci.yml`.
+Run the documentation check in [Testing](testing.md#docs-only-changes). The executable source of truth
+for CI hygiene is `scripts/check.sh`; `.github/workflows/ci.yml` invokes it rather than duplicating its
+logic.
 
 ## Avoiding Duplicate Truth