# RULES

## Commands

The justfile is the source of truth. Public API only:

- `just lint`
- `just test` (accepts a stem, e.g. `just test audio`; `vault-native` runs the Rust suite)
- `just ui-test` (accepts a named fixture and an optional `WIDTHxHEIGHT`)
- `just fmt`
- `just build`

- Run commands from `quickshell/nuguland`.
- Never test by restarting or killing the parent niri session.
- Never execute `niri-session`; it ignores `--help` and can terminate the live desktop session. Inspect its source instead.
- Keep pointer, keyboard, `wdotool`, `wtype`, and screenshot proofs inside nested niri via `just ui-test`.
- Never launch `test-fixtures/ui/refactor.qml` or `niri-integration.qml` directly; their sandbox service substitutions are mandatory.

## Gates

Zero warnings, isolated evidence, reviewed pixels. Rigor over velocity claims.

- Zero warnings: `just lint` fails on any non-disabled `qmllint` warning (`MaxWarnings=0`) and on missing, stale, or orphan shader blobs.
- Never disable `qmllint`, `shellcheck`, `shfmt`, `qmlformat`, shader freshness, runtime shader fallback, `.qmltypes`, import paths, or any lint/test step, and never exclude files from them, without explicit human approval.
- No `|| true`, output filters, allowlists, or warning downgrades.
- All UI labels are lowercase.

## Shaders

- Research prior art online first (Shadertoy, Qt/QML examples, compositor shaders, demoscene); adapt it to Nugu semantics and budgets; document the inspiration in comments.
- Sources live in `shaders/*.frag`; `just build` compiles the checked-in `*.frag.qsb`; runtime never compiles shaders and degrades cleanly when a blob is missing.

## UI work

- Load `.pi/skills/nuguland-ui/` before creating, changing, or reviewing UI.
- Reuse `Theme.qml` and shared `Popup*.qml`; read their callers before changing shared behavior.
- Popup work follows `NL-SPEC-38AED50A`.
- Feature onboarding follows `NL-SPEC-A7K4QX2M`.

## Evidence levels

Static, load, interaction, and visual proof are separate; report them separately.

- Static: lint, unit tests, formatting, shader freshness. Proves nothing about loading or rendering.
- Load: run the entry point or fixture in isolation; inspect complete stdout and stderr.
- Interaction: real pointer and keyboard inside nested niri — activation, Tab and arrows, Escape, outside dismissal, focus entry and return, external updates, empty and unavailable states.
- Visual: rendered screenshots at target geometry, reviewed by a human. A screenshot is evidence, not approval.

An IPC ping proves reachability only. Source regexes prove source conventions only.

## Nested-fixture diagnostic exceptions

Owner-approved 2026-09-06, `niri.log` only:

- at most one exact `niri::backend::winit` DEBUG record for the software EGL render-node fallback, full multiline match including the `EGL_EXT_device_drm` cause;
- exactly one exact `niri::niri` WARN `ENOENT` for the deliberate `/evidence/missing-directory/native-failure.png` write, inside the measured action interval.

Duplicates, missing records, wrong source, severity, cause, out-of-interval timing, or occurrence in any other log fail the run. All other diagnostics stay strict; raw logs are never filtered or rewritten.

## Docs

- `.system/` cores and specs are agent authority; read RULES and the relevant spec before governed work.
- READMEs are human overview; agent-only knowledge belongs in `.system/`.