Platform work in Neru

Platform code carries Neru's strictest guardrails, and this is where agents most often guess. A change that lands cleanly sits in an existing file slot, crosses the boundary through a port, returns CodeNotSupported wherever it is unimplemented, and reports itself honestly in the capability matrix.

Before writing code

1. Read internal/adapter/platform/AGENTS.md, the single home for the rules this skill obeys: the One Rule, file slots, the factory and Linux's runtime compositor axis, loud stubs, capability honesty, coordinates, generated Wayland bindings. Add the darwin/ or linux/ guide for the native boundary you touch.
2. Read internal/adapter/platform/profile.go. It is the source of truth for each subsystem's backend family, primary-modifier expectations, and whether a backend needs CGO. CGO is a per-backend decision, not a per-OS one.
3. Read the port you're implementing in internal/ports/. If the capability doesn't have a port yet, define the interface there first and add a mock in internal/ports/mocks.

Tests

• Unit tests with port mocks stay platform-neutral.
• Real-OS behavior goes in *_integration_<os>_test.go tagged //go:build integration && <os>.
• Contract tests pin CodeNotSupported per subsystem, not per stub. Update the subsystem's existing one if it has one, and write a new one when a caller could read the stub's nil as success, so a later "implementation" that silently no-ops fails a test. internal/adapter/platform/AGENTS.md names the ones that exist.

Docs (same change, not a follow-up)

docs/contributing/porting.md has the ownership table ("Documentation Checklist"), and each fact has exactly one home. Capability status goes in docs/reference/platform-support.md, the API or protocol behind it in docs/contributing/platform-internals.md, and never either in docs/contributing/architecture.md (shape only). Linux setup specifics go in docs/guide/linux.md / docs/guide/linux-desktops.md.

Verify

just lint                      # depguard enforces the One Rule
go test ./internal/architecture/
just test-foundation

Cross-compile the platforms you touched (just build-linux, just build-windows) even when you can't run them, because build tags hide breakage from a darwin-only just build. Then the standard pre-commit gate, and ask a maintainer to run integration tests on the target OS if you can't.