docs: test ownership rules for app, desktop and gui extensions

Rules drawn from the test audit: one contract per test at the strongest boundary, keeper suites instead of a spec per bug, the shared e2e harness instead of per-spec setup, no test-only production seams, tests that can fail, tables instead of per-theme or per-channel repeats, and no e2e copies of component tests. gui-extensions gets its own AGENTS.md with the structure, host boundary, performance and localization rules.
Hona · Oct 1, 2026 · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026 · Sep 30, 2026
commit ed33675c38c199dd55f229ea85ece336af91e45b
@@ -43,6 +43,18 @@
 - In translation review notes, name the corpora used and call out uncertain or region-specific terminology so native speakers can focus review where it matters.
 - Also use the relevant language authority or official dictionary for the locale (for example RAE/Fundéu, FranceTerme, Duden, TDK, Kotus/Kielitoimiston sanakirja, Språkrådet/Bokmålsordboka, Rada Języka Polskiego/PWN, the Russian and Arabic language academies, the Ukrainian Orthography, Taiwan MOE dictionaries, or the Royal Society of Thailand). Treat the English dictionary as the semantic source of truth and preserve placeholders, code identifiers, product names, and keyboard labels.
 
+## Tests
+
+A test must pay for its upkeep. Before adding one, answer three questions: which observable contract does it protect, which credible regression makes it fail, and why does no existing test already catch that regression. If any answer is missing, do not add the test.
+
+- One contract, one owner. Test each behavior once, at the strongest boundary that observes it: the area's e2e keeper suite, or the owning module's unit test. Extend an existing table or keeper case before creating a file.
+- Do not unit-test what an e2e keeper already proves, what a dependency does (for example `@pierre/trees`), config that passes values through, or source text (import or string greps). Source text is fair game only when that text is the contract, such as a persisted key.
+- Never add production seams for tests: no test-only exports, parameters such as `now`, `delay` or `budget`, flags, globals, or `data-*` attributes. Control time with `setSystemTime` from `bun:test` and drive the real entry point.
+- A test must be able to fail. Do not assert values the code under test produced, mock the behavior you assert, use soft assertions for the order the test guards, or leave `rejects`/`resolves` un-awaited. A regression test must fail on the code before the fix.
+- Do not repeat a case per theme, text direction, viewport or channel. Use one table, and only when the behavior differs.
+- When you delete or move coverage, name the test that still proves the contract. When you move a contract, mutate its owner once and confirm the new test fails.
+- A contract proven by a `packages/session-ui/component-tests` test does not also get an app e2e copy.
+
 ## Tool Calling
 
 - ALWAYS USE PARALLEL TOOLS WHEN APPLICABLE.

@@ -14,3 +14,11 @@
 - Do not retry state-changing actions. Retry idempotent readiness checks, then perform the action once and assert its outcome.
 - Keep action and assertion timeouts adaptive. Do not use short timeouts as readiness probes or rely on retries to hide flakes.
 - Assert exact outcomes and identities so stale state, duplicate rendering, and interactions with the wrong element cannot pass.
+
+## Test Ownership
+
+- Each product area has one keeper suite in `regression/` (for example tabs, settings, review, terminal, timeline history). A new regression is a new case in that suite, not a new spec file.
+- Build pages with the shared harness in `utils/` (`app.ts`, `workspace.ts`, `mock-server.ts` with `mockServers` and the mock PTY). Do not hand-write routing, storage seeding, or fixtures inside a spec. If the harness lacks something, add it to `utils/` once rather than copying setup.
+- Files in `utils/` must not end in `.spec.ts` or `.test.ts`, or Playwright runs them as tests.
+- Assert what the user sees and can do. Assert exact pixels or CSS values only when that measurement is the contract, and then only once, in the owning keeper.
+- `performance/` holds benchmarks that CI does not run. Never prove correctness with a benchmark, and never copy benchmark code into a regression spec; import it from `utils/`.
@@ -1,5 +1,17 @@
 # Desktop package notes
 
+## Tests
+
+- Follow the Tests section of `packages/app/AGENTS.md`: every test protects a named contract with a credible regression, has one owner, and can fail.
+- Packaging, installer, IPC validation, credential, and SQLite migration and storage tests are contracts. Write them as tables: one table across channels, not one test per channel.
+- Never add test-only parameters or exports to production modules (`now`, `delay`, `budget`). Use `setSystemTime` from `bun:test`.
+- Test IPC through the raw message format the renderer sends, not through a mock client.
+- No source-grep or tombstone tests that assert a file, export or feature is gone.
+- Main-process code that belongs to a GUI extension is tested in `packages/gui-extensions`, not here.
+- `bun typecheck` does not cover test files. Run `bun test <file>` for every test file you touch.
+
+## Code
+
 - Follow Solid best practices, leave a comment when violating this: https://www.brenelz.com/posts/solid-js-best-practices/
 - Renderer process should only reach the main process through `window.electron` (exposed by `src/preload`) and the MessagePort RPC client in `src/renderer/api.ts`.
 - Main process should define IPC handlers in `src/main/ipc-handlers/*` and compose them in `src/main/ipc.ts`.

diff --git a/packages/gui-extensions/AGENTS.md b/packages/gui-extensions/AGENTS.md
@@ -0,0 +1,33 @@
+# GUI extensions
+
+Built-in features of the desktop and web app, each behind the SDK in `src/sdk/`. The renderer host lives in `packages/app/src/runtime/extension/`, the main-process host in `packages/desktop/src/main/extension/`.
+
+## Structure
+
+- One folder per extension: `index.ts` (`Extension.define({ id, os?, i18n })`), `contract.ts`, `renderer.tsx`, optional `main.ts`, and `i18n/<locale>.ts`.
+- `src/renderer.ts` and `src/main.ts` are the only files that list the built-ins. Main never imports renderer code.
+- Another extension may import only your `contract.ts` (tokens and schemas, no runtime code). Every consumer must still work when the provider is disabled: `ctx.use(Service)` is an accessor that can return `undefined`.
+- Never import `@opencode/app`, `@opencode/desktop`, or `@/` paths. Import CSS with `?inline` and contribute it through `ctx.add(Style, css)`. No module-level state: keep state inside `setup`. `bun run lint` enforces these rules.
+
+## Host boundary
+
+- Host code must not name an extension or know its internals: no extension ids, command ids, DOM selectors, or stored key formats. When the host needs something from extensions, add a generic, documented field to the SDK (for example `PanelTab.file`, `Command.featured`, `Command.section`).
+- Accepted exceptions: the built-in lists, the keybind rename map in `packages/app/src/settings/keybinds/migration.ts`, and the crash page's use of the updater contract.
+
+## Performance
+
+- Keep `renderer.tsx` small and put heavy UI behind `lazy()`. Load chunks with `preload(sessions, …)` or `onIdle(…)`, never at startup.
+- Return stable objects from `Panel.list` and reactive contributions, so the host never remounts a trigger or a panel.
+- Never add work to timeline rows. The session header slot is the only timeline surface.
+
+## Localization
+
+- Each extension owns its copy in `i18n/en.ts` with short keys. `ctx.t` falls back to the app's keys only for shared vocabulary such as `common.*`; feature copy belongs to the extension.
+- When moving copy, keep the English byte-for-byte and carry every locale's translation. The localization rules in `packages/app/AGENTS.md` apply.
+
+## Tests
+
+- Follow the Tests section of `packages/app/AGENTS.md`.
+- Unit-test pure logic that carries a contract: path and security checks, storage migration, protocol parsing, archive validation.
+- UI behavior is proven by the app e2e keeper suites. Do not add unit tests that repeat them.
+- Test a main-process entry through its `Remote` contract with real inputs, not through Electron mocks.