Document checked-in .claude/ agent tooling in AGENTS.md

AGENTS.md

@@ -40,7 +40,7 @@ Eventually, a C toolchain necessary. However, it is helpful much sooner:
 
 ## Project status
 
-Last updated 2026-07-21. The project just finished migrating its boot
+Last updated 2026-07-26. The project just finished migrating its boot
 process from Multiboot2/GRUB to a custom UEFI loader. The loader
 (`loader/`) now successfully parses the kernel ELF, maps its segments, sets
 up paging, and jumps into `kernel_entry` in [src/kmain.rs](src/kmain.rs).
@@ -55,7 +55,10 @@ inert the way it was right after the UEFI migration.
 A dedicated testing/verification strategy (beyond ad hoc debugcon-reading
 and manual QEMU boots) landed in `.github/workflows/ci.yml` (PR #25):
 three jobs — `cheap` (host unit tests + per-crate compile checks),
-`expensive` (Miri), and `smoke` (full image build + a headless QEMU boot,
+`expensive` (Miri — path-gated to `shared`/Miri inputs so unrelated PRs get
+a green no-op, plus a daily `schedule:` run that forces the full suite to
+catch dateless-`nightly` drift), and `smoke` (full image build + a headless
+QEMU boot,
 gated on a new `src/qemu.rs` isa-debug-exit pass/fail signal, see
 "Verifying changes" below). GDB-over-QEMU-stub debugging is still real but
 slow for interactive local work, so CI — not local runs — is what now
@@ -219,6 +222,12 @@ of running them all by hand every time. Locally, in order of preference:
 
 ### Booting headlessly and bounding the run
 
+This whole procedure is packaged as the **`qemu-boot` skill**
+(`.claude/skills/qemu-boot/SKILL.md`) — an agent verifying a change by
+booting should invoke that skill rather than re-deriving the watchdog by
+hand. The prose below is the source of truth the skill follows; keep the two
+in sync when boot behavior changes.
+
 Rebuild first (`./make-image.sh`), then run headless and capture output.
 QEMU never exits on its own after the kernel halts, and there's **no
 `timeout`/`gtimeout` on macOS**. A `perl -e 'alarm N; exec ...'` wrapper
@@ -260,6 +269,30 @@ triple fault (QEMU silently resets without `-no-reboot`). Add
 QEMU's own exception/reset trace instead of re-guessing from debugcon
 silence alone.
 
+## Claude Code tooling (`.claude/`)
+
+Some agent tooling is checked into the repo under `.claude/` (this is a
+learning project, and part of that is learning how to use Claude Code here).
+Tracked assets, and what each is for:
+
+* **`skills/qemu-boot/`** — a skill that rebuilds the image and boots it
+  headlessly in QEMU with the external watchdog, distinguishing a hang from
+  a triple-fault reset from a normal panic. Use it for any boot-based
+  verification instead of hand-rolling the procedure in "Verifying changes"
+  above; that section remains the source of truth the skill defers to.
+* **`agents/source-grounded-explorer.md`** — a read-only subagent for
+  open-ended architectural/strategic questions about this codebase (e.g.
+  "how should X be re-wired for the UEFI handoff"). It reads the actual
+  source before reasoning and returns a labeled option menu with a
+  recommendation. Not for concrete already-decided fixes — just do those
+  directly.
+* **`output-styles/terse.md`** + **`settings.json`** — a project-wide
+  "Terse" output style (enabled via the checked-in `settings.json`) that
+  trims response verbosity without touching reasoning depth.
+
+`.claude/settings.local.json` is gitignored (machine-local overrides) and
+won't exist in a fresh clone.
+
 ## Contribution conventions
 
 * Keep commit messages concise (short subject, at most a brief sentence or