docs: split README into docs/ and add AGENTS.md

Move the README's hardware notes, demo controls, environment setup, test
notes, file map, and references into docs/ and docs/hardware/. The README
is now an overview with a docs index. AGENTS.md gives coding agents a short
map of crates, commands, and where to read and write documentation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/development.md

@@ -0,0 +1,80 @@
+# Development environment
+
+**macOS (Darwin) is the first development and validation target.**
+Build and test new features on Apple Silicon macOS before expanding platform support.
+Future window, input, and audio libraries must support native macOS.
+
+Install Nix with `nix-command` and `flakes` enabled, plus direnv.
+The flake defines shells for Apple Silicon macOS, Intel macOS, ARM64 Linux, and x86-64 Linux.
+Only Apple Silicon macOS is verified. Intel macOS and Linux remain untested.
+
+Verified locally on macOS 15.7.3:
+
+- Nix system: `aarch64-darwin`.
+- Rust host: `aarch64-apple-darwin`.
+- Release executable: native Mach-O `arm64`, without Rosetta.
+- All tests pass in debug and release builds.
+- All ten native window smoke tests pass. The mosaic test submits 128 frames; the other nine submit 60 frames each.
+- The eight CPU-driven smoke tests check CPU state, every output pixel, and presentation at VBlank entry.
+- The terminal-only CPU and timer IRQ demos run successfully.
+
+These results cover the CPU core, memory, Mode 0–5 snapshots and row capture, input mapping, and desktop windows.
+They do not verify a complete GBA display controller or audio.
+Arrow-key movement in the original host display test was confirmed manually on this Mac.
+The new CPU graphics demo has automated input-mapping tests; its physical keyboard behavior still needs manual confirmation.
+
+Enable the direnv hook in your shell if it is not already configured.
+For zsh, add this line to `~/.zshrc`:
+
+```sh
+eval "$(direnv hook zsh)"
+```
+
+For bash, use `eval "$(direnv hook bash)"` in `~/.bashrc` instead.
+Restart your shell after changing its configuration.
+
+From this project directory:
+
+```sh
+direnv allow
+cargo run
+cargo test
+cargo fmt --all --check
+cargo clippy --all-targets -- -D warnings
+```
+
+To run commands without a shell hook:
+
+```sh
+direnv allow .
+direnv exec . cargo run --locked
+direnv exec . cargo test --locked
+```
+
+`.envrc` uses the Nix flake to load Rust, Cargo, rustfmt, and Clippy.
+`flake.lock` pins the Nix package source. Keep it in version control.
+The first run needs network access to download the development tools and Rust dependencies.
+
+The pinned Nix Darwin toolchain targets macOS 14.0 or newer.
+The flake sets Darwin-only `CFLAGS` to correct two minifb 0.28 native-build issues:
+
+- Override its macOS 10.10 deployment flag, which predates the Metal APIs it uses.
+- Use `-fcommon` for its shared tentative Objective-C global definition.
+
+Build through direnv or `nix develop` so these settings apply.
+The window runs on the main thread, as required by macOS AppKit.
+`crates/desktop/src/desktop.rs` also corrects the inverted macOS focus result in minifb 0.28.0.
+The dependency is pinned to that exact version. Review this workaround before upgrading minifb.
+Intel macOS and Linux desktop builds are not verified.
+
+Without direnv, use:
+
+```sh
+nix develop
+```
+
+For one command without entering a shell:
+
+```sh
+nix develop -c cargo test
+```