Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/.system/RULES.md

Raw
Rendered preview

RULES

Commands

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

  • just lint (zero-warning static/format/shader checks, full JS/MJS and Rust tests, every feature load target)
  • just test (accepts a stem, e.g. just test audio; vault-native runs the Rust suite)
  • just load-test (accepts a feature; runs features/<feature>/fixtures/load.qml offscreen with every feature's doubles from features/*/fixtures/services/)
  • just ui-test (accepts a named fixture, including every feature suite, and an optional WIDTHxHEIGHT; shell runs production shell.qml against private service stand-ins and opens every popup and overlay)
  • just stress <test> [runs] (runs one JS test concurrently, 16 times by default; any failure means the test is flaky)
  • just worktree <name> (creates an agent worktree and prints its directory)
  • just reload (owner only: restarts the live desktop shell, waiting for the old instance to exit; agents never run it)
  • just fmt
  • just build (shares Cargo artifacts in $XDG_CACHE_HOME/nuguland/cargo, default $HOME/.cache/nuguland/cargo; installs only the release vault executable into the current checkout for runtime and nested fixtures)
  • just deps (every recipe above runs it first; the package list there is the single source of host requirements)

just deps lists only what gates and builds need on every host. Hardware-dependent runtime tools stay out: the owning feature installs them on demand through its setup flow (e.g. ddcutil via brightness "setup ddc") or reports an unavailable state (e.g. no ColorHug sensor).

  • Never edit the main checkout: ~/.config/quickshell/nuguland points at it and the live desktop shell hot-reloads every change, broken or not. Create a worktree with just worktree <name>, edit and run every gate there, and merge back only verified commits.
  • Live verification is the owner's: never probe the running desktop shell, its log, or its IPC to prove a change. Prove behavior through the gates and nested fixtures; where they cannot reach, build the missing test tool and report the gap.
  • Run commands from quickshell/nuguland of your worktree.
  • 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/lifecycle.qml or niri-integration.qml directly; their sandbox service substitutions are mandatory.
  • Host tests never reach the desktop session: every process a test file or runner starts goes through test-fixtures/isolation.js (allowlisted environment, private HOME and XDG directories, no display, no bus or a private bus that activates nothing, process-group cleanup); test-fixtures/isolation.test.js enforces it.

Feature files

Feature onboarding follows NL-SPEC-A7K4QX2M; ownership follows SYSTEM. FeatureEntry.qml owns entry field, host-kind, geometry, bar presentation, retention, initial-focus and lifecycle documentation; do not duplicate its property list here. Registry.qml creates services and entries; explicit typed IPC stays in shell.qml.

  • Feature-local *.test.js or *.test.mjs, fixtures/load.qml, fixtures/suite.mjs; optional fixtures/production.mjs. Load imports root as import "../../.." as N; directory conventions discover suites and loads.
  • Every native/system integration service needs a fixtures/services/<Type>.qml double mirroring consumed properties/methods and exposing fixtureState(). Pure production services such as OSD stay. Doubles must pass assertPureService in ui-test.mjs, including its import, object-type and token restrictions; no parallel forbidden-token list. All load and Bar fixtures apply all feature doubles. Native integration keeps the nativeFeatures in test-fixtures/ui/niri-integration.mjs with fixture-bound inputs; per-feature production hooks separately restore production sources after the double-based suite.
  • External inputs are nullable typed Registry properties bound by startup composition and forwarded to services. Doubles declare those inputs as property var <name>: null.
  • Internal readers bind readonly service properties, typed scalars and var only for row lists/records. stateJson()/stateObject() serve IPC/diagnostics only; no in-process caller parses service returns. Registry bar bindings read properties, never service functions (typed-state.test.mjs).
  • Config discovers optional typed entry configuration sections; declarations remain shell-lifetime objects, never runtime JSON or serialized service snapshots. Generic rows render choices, fields, actions and status; feature services retain validation, drafts, persistence and execution. Secrets never enter declaration serialization, retained state, diagnostics or snapshot text; editable fixtures expose only filled/masked predicates. No generic persistence or universal Apply engine; Config invokes only the selected section's declared entry/exit policy, never blanket cancellation or save/discard. Vault section exit stops connection testing; speech/DDC installation remains domain-owned until native exit. Feature-local *Config.qml components contain typed section/row declarations and service intents only; Registry instantiates them and the renderer remains feature-agnostic. Section scroll/focus coordinates may outlive the renderer; editable content remains service-owned and is never serialized by Config. Migrate setup/preferences, not operational controls or internal constants.
  • Panels never receive SurfaceManager. A feature's configureRequested signal is wired within its registry declaration to Config navigation; hosts stay feature-agnostic. Opening Light configuration does not activate its operational sensor-demand panelOpen gate. Entry opening/dismissed handlers own open/close service work, never Bar/IPC or disposable panel lifecycle. opening happens before activation, potentially before panel creation, on open/switch/repeated open, never close. Previous dismissal precedes switching. Keep literal entry layout compatible with registryEntries() in sources.js.

Suite API and snapshots: bar.mjs, bar.qml; production-hook API: ui-test.mjs. open(name, ready) clicks the chip/control (closing an already-open popup), waits for ready(snapshot) to return the primary control rect and asserts it on-output. Assert content-fit using popup card and declared panel height within entry budget; inspect orientation, retained state, usage/chip state, external updates, focus entry/return and dismissal. call invokes a double service method; fixture selects checked-in fixture state, never arbitrary commands. Controls/items expose safe state; editable inputs never expose text, only filled and password masked. Snapshot userTexts identifies visible person/app-authored text.

Screenshot names must not contain error, failed, or warn: the log gate reads evidence paths. Send keys to a popup only after popup.windowActive.

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.
  • A flaky test is worse than none: fix its cause or delete it in the same change, proven with just stress. Never retry, rerun until green, quarantine, or loosen an assertion to hide timing.
  • All UI labels are lowercase.
  • No rendered label shows a machine identifier (zen rule 4): every external string that becomes a label passes through human.js (label for names and titles, pick for name precedence, text for lines that carry data); bodies the user wrote stay as they are. Every Bar suite snapshot fails on one (assertHumanLabels in ui-test.mjs), and a double whose feature shows external strings carries adversarial ones that its suite proves human.
  • No rendered label narrates the interface (zen): a control the current source can never perform is absent, never disabled and explained. Every Bar suite snapshot fails on capability or explanation phrasing in texts, tooltips and accessible names (assertPlainLabels in ui-test.mjs); text a person or an app wrote carries userText: true (NuguText.qml, PopupButton.qml) and is never read as narration.

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.
  • Every surface follows the Zen of Nugu, NL-SPEC-VQXGUHYK.
  • Reuse Theme.qml and shared Popup*.qml; read their callers before changing shared behavior.
  • Popup work follows NL-SPEC-38AED50A.

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, normally just load-test <feature>; 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 the agent; they are agent evidence, not approval.
  • Owner review: the owner judges the change on the live desktop after merge; never ask the owner to review screenshots.

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

just ui-test evidence is scratch in $TMPDIR/nuguland-ui-test-*: each run prunes to the newest 3 runs per fixture and spares runs written in the last 15 minutes. Evidence that must outlive that is copied deliberately into the relevant spec's evidence/ directory; never cite scratch run paths in docs.

Debugging

  • Owner only, live read-only snapshot: qs ipc -c nuguland call nuguland diagnostics; it needs a shell that already loaded the endpoint, never a restarted parent desktop.
  • Reproduce with just ui-test <suite>; suites replay checked-in synthetic state, never arbitrary commands or live desktop actions, and invalid selections fail before any compositor starts.
  • Read a failed run in order: failure.json (original error, phase, latest safe snapshot, capture errors), replay.json (suite, rerun command), failure.png, diagnostics.jsonl with the fixture-specific log (bar.log, lifecycle.log, niri-integration.log, etc.), then commands.log (timestamped, with durations), fixture and compositor logs, versions.txt, outputs.json.
  • Popup transition log records have kind: popup-transition and events opening, opened, switched, closed; opening and its deferred opened share an operation ID, switching and closing allocate new ones; IDs belong to one shell instance and wrap after 2147483647.
  • Diagnostics contract: one read-only, versioned nuguland diagnostics IPC endpoint projecting popup lifecycle and geometry, display geometry, and coarse service availability. It never includes clipboard text, vault records, secrets, accounts, URLs, notification bodies, window titles, authentication prompts, editable text, or raw service JSON; logs carry only selected fields, never caller-provided free text.
  • Failure capture never replaces the original error or skips cleanup; screenshots refuse revealed nonempty authentication input; a missing screenshot is explicit in captureErrors, never a pass.
  • just test vault-native runs every Rust test; child-process and barrier waits stay bounded so a regression fails instead of stalling.

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;

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.

FileView write failure, owner-approved 2026-11-15, config-orientation.test.mjs failure case only:

  • Quickshell 0.3.2 reports a failed FileView write at WARN even with printErrors: false.
  • The case that points the preference at a directory accepts exactly one such record, the full Write of … failed: Unknown error when opening file. line for features/config/Config.qml; every other case and any second diagnostic still fail.

QTBUG-146211 workaround, owner-approved 2026-11-13, Qt fixture logs only:

  • Qt 6.12.0 QWaylandInputContext::setFocusObject leaves text-input enable and disable calls unpaired when focus moves between windows; fixed upstream by qtbase e26d5a8eee and b4dd527686.
  • qtTextInputWorkaround in ui-test.mjs accepts exactly the observed qt.qpa.wayland.textinput warning shapes, disableSurface … but <surface> is focused and enableSurface … but <surface> has focus, and counts every occurrence in runtime-diagnostics.json.
  • Any other text-input shape, such as is enabled or is already enabled, still fails until traced and approved.
  • just test fails as soon as the installed Qt differs from brokenQt; then remove every QTBUG-146211 site and rerun just ui-test.

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/.
# RULES

## Commands

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

- `just lint` (zero-warning static/format/shader checks, full JS/MJS and Rust tests, every feature load target)
- `just test` (accepts a stem, e.g. `just test audio`; `vault-native` runs the Rust suite)
- `just load-test` (accepts a feature; runs `features/<feature>/fixtures/load.qml` offscreen with every feature's doubles from `features/*/fixtures/services/`)
- `just ui-test` (accepts a named fixture, including every feature suite, and an optional `WIDTHxHEIGHT`; `shell` runs production `shell.qml` against private service stand-ins and opens every popup and overlay)
- `just stress <test> [runs]` (runs one JS test concurrently, 16 times by default; any failure means the test is flaky)
- `just worktree <name>` (creates an agent worktree and prints its directory)
- `just reload` (owner only: restarts the live desktop shell, waiting for the old instance to exit; agents never run it)
- `just fmt`
- `just build` (shares Cargo artifacts in `$XDG_CACHE_HOME/nuguland/cargo`, default `$HOME/.cache/nuguland/cargo`; installs only the release vault executable into the current checkout for runtime and nested fixtures)
- `just deps` (every recipe above runs it first; the package list there is the single source of host requirements)

`just deps` lists only what gates and builds need on every host.
Hardware-dependent runtime tools stay out: the owning feature installs them on demand through its setup flow (e.g. `ddcutil` via brightness "setup ddc") or reports an unavailable state (e.g. no ColorHug sensor).

- Never edit the main checkout: `~/.config/quickshell/nuguland` points at it and the live desktop shell hot-reloads every change, broken or not. Create a worktree with `just worktree <name>`, edit and run every gate there, and merge back only verified commits.
- Live verification is the owner's: never probe the running desktop shell, its log, or its IPC to prove a change. Prove behavior through the gates and nested fixtures; where they cannot reach, build the missing test tool and report the gap.
- Run commands from `quickshell/nuguland` of your worktree.
- 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/lifecycle.qml` or `niri-integration.qml` directly; their sandbox service substitutions are mandatory.
- Host tests never reach the desktop session: every process a test file or runner starts goes through `test-fixtures/isolation.js` (allowlisted environment, private HOME and XDG directories, no display, no bus or a private bus that activates nothing, process-group cleanup); `test-fixtures/isolation.test.js` enforces it.

## Feature files

Feature onboarding follows [NL-SPEC-A7K4QX2M](specs/NL-SPEC-A7K4QX2M-nuguland-agent-onboarding/index.md); ownership follows [SYSTEM](SYSTEM.md).
[FeatureEntry.qml](../FeatureEntry.qml) owns entry field, host-kind, geometry, bar presentation, retention, initial-focus and lifecycle documentation; do not duplicate its property list here.
[Registry.qml](../Registry.qml) creates services and entries; explicit typed IPC stays in `shell.qml`.

- Feature-local `*.test.js` or `*.test.mjs`, `fixtures/load.qml`, `fixtures/suite.mjs`; optional `fixtures/production.mjs`.
  Load imports root as `import "../../.." as N`; directory conventions discover suites and loads.
- Every native/system integration service needs a `fixtures/services/<Type>.qml` double mirroring consumed properties/methods and exposing `fixtureState()`.
  Pure production services such as OSD stay.
  Doubles must pass `assertPureService` in [ui-test.mjs](../ui-test.mjs), including its import, object-type and token restrictions; no parallel forbidden-token list.
  All load and Bar fixtures apply all feature doubles.
  Native integration keeps the `nativeFeatures` in `test-fixtures/ui/niri-integration.mjs` with fixture-bound inputs; per-feature production hooks separately restore production sources after the double-based suite.
- External inputs are nullable typed Registry properties bound by startup composition and forwarded to services.
  Doubles declare those inputs as `property var <name>: null`.
- Internal readers bind readonly service properties, typed scalars and `var` only for row lists/records.
  `stateJson()`/`stateObject()` serve IPC/diagnostics only; no in-process caller parses service returns.
  Registry bar bindings read properties, never service functions (`typed-state.test.mjs`).
- Config discovers optional typed entry `configuration` sections; declarations remain shell-lifetime objects, never runtime JSON or serialized service snapshots.
  Generic rows render choices, fields, actions and status; feature services retain validation, drafts, persistence and execution.
  Secrets never enter declaration serialization, retained state, diagnostics or snapshot text; editable fixtures expose only filled/masked predicates.
  No generic persistence or universal Apply engine; Config invokes only the selected section's declared entry/exit policy, never blanket cancellation or save/discard.
  Vault section exit stops connection testing; speech/DDC installation remains domain-owned until native exit.
  Feature-local `*Config.qml` components contain typed section/row declarations and service intents only; Registry instantiates them and the renderer remains feature-agnostic.
  Section scroll/focus coordinates may outlive the renderer; editable content remains service-owned and is never serialized by Config.
  Migrate setup/preferences, not operational controls or internal constants.
- Panels never receive SurfaceManager.
  A feature's `configureRequested` signal is wired within its registry declaration to Config navigation; hosts stay feature-agnostic.
  Opening Light configuration does not activate its operational sensor-demand `panelOpen` gate.
  Entry `opening`/`dismissed` handlers own open/close service work, never Bar/IPC or disposable panel lifecycle.
  `opening` happens before activation, potentially before panel creation, on open/switch/repeated open, never close.
  Previous dismissal precedes switching.
  Keep literal entry layout compatible with `registryEntries()` in [sources.js](../test-fixtures/sources.js).

Suite API and snapshots: [bar.mjs](../test-fixtures/ui/bar.mjs), [bar.qml](../test-fixtures/ui/bar.qml); production-hook API: [ui-test.mjs](../ui-test.mjs).
`open(name, ready)` clicks the chip/control (closing an already-open popup), waits for `ready(snapshot)` to return the primary control rect and asserts it on-output.
Assert content-fit using popup card and declared panel height within entry budget; inspect orientation, retained state, usage/chip state, external updates, focus entry/return and dismissal.
`call` invokes a double service method; `fixture` selects checked-in fixture state, never arbitrary commands.
Controls/items expose safe state; editable inputs never expose text, only `filled` and password `masked`.
Snapshot `userTexts` identifies visible person/app-authored text.

Screenshot names must not contain `error`, `failed`, or `warn`: the log gate reads evidence paths.
Send keys to a popup only after `popup.windowActive`.

## 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.
- A flaky test is worse than none: fix its cause or delete it in the same change, proven with `just stress`. Never retry, rerun until green, quarantine, or loosen an assertion to hide timing.
- All UI labels are lowercase.
- No rendered label shows a machine identifier (zen rule 4): every external string that becomes a label passes through `human.js` (`label` for names and titles, `pick` for name precedence, `text` for lines that carry data); bodies the user wrote stay as they are. Every Bar suite snapshot fails on one (`assertHumanLabels` in `ui-test.mjs`), and a double whose feature shows external strings carries adversarial ones that its suite proves human.
- No rendered label narrates the interface (zen): a control the current source can never perform is absent, never disabled and explained. Every Bar suite snapshot fails on capability or explanation phrasing in texts, tooltips and accessible names (`assertPlainLabels` in `ui-test.mjs`); text a person or an app wrote carries `userText: true` (`NuguText.qml`, `PopupButton.qml`) and is never read as narration.

## 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.
- Every surface follows the Zen of Nugu, `NL-SPEC-VQXGUHYK`.
- Reuse `Theme.qml` and shared `Popup*.qml`; read their callers before changing shared behavior.
- Popup work follows `NL-SPEC-38AED50A`.

## 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, normally `just load-test <feature>`; 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 the agent; they are agent evidence, not approval.
- Owner review: the owner judges the change on the live desktop after merge; never ask the owner to review screenshots.

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

`just ui-test` evidence is scratch in `$TMPDIR/nuguland-ui-test-*`: each run prunes to the newest 3 runs per fixture and spares runs written in the last 15 minutes.
Evidence that must outlive that is copied deliberately into the relevant spec's `evidence/` directory; never cite scratch run paths in docs.

## Debugging

- Owner only, live read-only snapshot: `qs ipc -c nuguland call nuguland diagnostics`; it needs a shell that already loaded the endpoint, never a restarted parent desktop.
- Reproduce with `just ui-test <suite>`; suites replay checked-in synthetic state, never arbitrary commands or live desktop actions, and invalid selections fail before any compositor starts.
- Read a failed run in order: `failure.json` (original error, phase, latest safe snapshot, capture errors), `replay.json` (suite, rerun command), `failure.png`, `diagnostics.jsonl` with the fixture-specific log (`bar.log`, `lifecycle.log`, `niri-integration.log`, etc.), then `commands.log` (timestamped, with durations), fixture and compositor logs, `versions.txt`, `outputs.json`.
- Popup transition log records have `kind: popup-transition` and events `opening`, `opened`, `switched`, `closed`; `opening` and its deferred `opened` share an operation ID, switching and closing allocate new ones; IDs belong to one shell instance and wrap after 2147483647.
- Diagnostics contract: one read-only, versioned `nuguland diagnostics` IPC endpoint projecting popup lifecycle and geometry, display geometry, and coarse service availability. It never includes clipboard text, vault records, secrets, accounts, URLs, notification bodies, window titles, authentication prompts, editable text, or raw service JSON; logs carry only selected fields, never caller-provided free text.
- Failure capture never replaces the original error or skips cleanup; screenshots refuse revealed nonempty authentication input; a missing screenshot is explicit in `captureErrors`, never a pass.
- `just test vault-native` runs every Rust test; child-process and barrier waits stay bounded so a regression fails instead of stalling.

## 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;

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.

FileView write failure, owner-approved 2026-11-15, `config-orientation.test.mjs` failure case only:

- Quickshell 0.3.2 reports a failed `FileView` write at WARN even with `printErrors: false`.
- The case that points the preference at a directory accepts exactly one such record, the full `Write of … failed: Unknown error when opening file.` line for `features/config/Config.qml`; every other case and any second diagnostic still fail.

QTBUG-146211 workaround, owner-approved 2026-11-13, Qt fixture logs only:

- Qt 6.12.0 `QWaylandInputContext::setFocusObject` leaves text-input enable and disable calls unpaired when focus moves between windows; fixed upstream by qtbase `e26d5a8eee` and `b4dd527686`.
- `qtTextInputWorkaround` in `ui-test.mjs` accepts exactly the observed `qt.qpa.wayland.textinput` warning shapes, `disableSurface … but <surface> is focused` and `enableSurface … but <surface> has focus`, and counts every occurrence in `runtime-diagnostics.json`.
- Any other text-input shape, such as `is enabled` or `is already enabled`, still fails until traced and approved.
- `just test` fails as soon as the installed Qt differs from `brokenQt`; then remove every `QTBUG-146211` site and rerun `just ui-test`.

## 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/`.