chore: cut agent token burn with scoped bootstrap and handoffs

Slim always-on agent docs, default to toju-app plus targeted electron, and add HANDOFF.md plus a Cursor rule so long chats reset cleanly without agents opening new chats.

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -1,103 +1,98 @@
 # AGENTS.md
 
-Read these files at the start of every session before doing any work:
+Keep this file small. Detail lives in linked docs — load those **only when the task needs them**.
 
-1. `agents-docs/AGENT_WORKFLOW.md` — workflow and operating rules
-2. `agents-docs/LESSONS.md` — durable rules learned from past corrections; apply any that match this session's work
-3. `agents-docs/AGENTS_FEATURES.md` — when and how to update feature docs
-4. `agents-docs/FEATURES.md` — feature index
-5. `agents-docs/ENGINEERING.md` — engineering standards
-6. `agents-docs/CONTEXT-MAP.md` — index of bounded contexts in this repo
+## Session handoff (new chats)
 
-Reference on-demand (when the workflow triggers them — see `agents-docs/AGENT_WORKFLOW.md` §§ 4–5):
+Agents **cannot** open a new Cursor chat. To reset context:
 
-- `agents-docs/AGENTS_CONTEXT.md` — contract for updating `CONTEXT.md` / `CONTEXT-MAP.md`
-- `agents-docs/AGENTS_ADRS.md` — contract for writing architecture decision records
-- `agents-docs/BUG_TRACKER.md` — Obsidian bug inbox location, allowed vault edits, and triage workflow
+1. Write/update `agents-docs/HANDOFF.md` (`Status: active`) — see `.cursor/rules/handoff.mdc`.
+2. Ask the user to start a **new chat** and attach `@agents-docs/HANDOFF.md`.
 
-When working in a subdomain, also read its `CONTEXT.md` first:
+**At session start:** if `agents-docs/HANDOFF.md` has `Status: active`, read it first and continue Next steps. Do not redo Completed work.
 
-- Product client (Angular 21): `toju-app/CONTEXT.md`
-- Desktop shell (Electron main + preload): `electron/CONTEXT.md`
-- Signaling server (Express + WebSocket): `server/CONTEXT.md`
-- End-to-end tests (Playwright): `e2e/CONTEXT.md`
-- Marketing site (Angular 19): `website/CONTEXT.md`
-- Application documentation (Docusaurus): `docs-site/CONTEXT.md`
+## Default work scope (token fence)
+
+Unless the user **explicitly** expands scope, stay inside:
+
+- `toju-app/` (primary)
+- `electron/` — **targeted only** (desktop shell is coupled to the client; see below)
+- CI: `.gitea/workflows/`
+- Agent/docs as needed: this file, `agents-docs/` (index-first / handoff), `toju-app/CONTEXT.md`; `electron/CONTEXT.md` only when touching Electron
+
+### Electron — relevant files only
+
+`electron/` is in default scope because the renderer talks to it via preload/IPC/local DB. Do **not** browse the whole tree.
+
+When a `toju-app` change needs the desktop bridge:
+
+1. Start from the renderer call site (`window.api` / Electron bridge usage).
+2. Open only the matching surface: usually `electron/preload.ts`, then the specific handler under `electron/ipc/`, `electron/cqrs*`, or the one module/entity/migration involved.
+3. Prefer ripgrep with path `electron/` + a concrete symbol over listing directories.
+4. Skip unrelated areas (`electron/api/` docs server, `game-detection/`, `update/`, other migrations, etc.) unless the bug points there.
+
+**Still out of scope by default** (do not search/read/edit unless the user names them):
+
+- `server/`, `e2e/`, `website/`, `docs-site/`
+- Root noise: `dist*/`, `node_modules/`, `images/`, `project-files/`, `test-results/`
+
+If the root cause looks like `server/` or e2e-only, **ask once** instead of exploring those trees.
+
+Search with path filters. Prefer `toju-app/src/app/domains/<name>/` over repo-wide greps.
+
+## Session start (cheap bootstrap)
+
+1. Skim this file.
+2. If handoff `Status: active` → read `agents-docs/HANDOFF.md`.
+3. Open `agents-docs/LESSONS-INDEX.md` only — match tags; open matching bodies in `LESSONS.md`.
+4. Read `toju-app/CONTEXT.md` for client work; `electron/CONTEXT.md` only if this task touches Electron.
+5. Other docs **on demand** only.
+
+**Models:** use the latest problem-solving model the user selected. Save tokens with **scope, handoffs, and short chats** — not by silently downgrading model quality.
+
+**Do not auto-read:** `ENGINEERING.md`, `AGENTS_FEATURES.md`, `FEATURES.md`, `CONTEXT-MAP.md`, full `AGENT_WORKFLOW.md`, feature docs, ADRs — unless needed.
+
+On-demand: `agents-docs/AGENT_WORKFLOW.md`, `AGENTS_FEATURES.md`, `FEATURES.md`, `ENGINEERING.md`, `AGENTS_CONTEXT.md`, `AGENTS_ADRS.md`, `BUG_TRACKER.md`.
 
 ---
 
-MetoYou (also called Toju) is a desktop-first, P2P Discord-style chat application managed as an npm-workspaces monorepo. It bundles an Angular 21 product client, an Electron 39 desktop shell with TypeORM + sql.js for local persistence, a small Node/TypeScript Express signaling server with WebSocket-based realtime, a Playwright end-to-end suite, an Angular 19 marketing site, and a Docusaurus app/plugin documentation site that ships inside the Electron build. Voice and screen-share are WebRTC, with RNNoise denoising via a WASM audio worklet.
+MetoYou / Toju: desktop-first P2P chat. Default surface: Angular client (`toju-app/`) + targeted Electron bridge + CI.
 
-## CRITICAL — Non-negotiable rules for all agents
+## CRITICAL — Done means the asked behavior works
 
-### Test-Driven Development (MANDATORY)
-**Write tests before implementation code.**
+**Unit/spec green is support, not done.**
 
-When creating or changing anything:
-1. STOP — do not write implementation first
-2. Write failing tests (RED)
-3. Run tests and confirm failure (`npm run test` for the product client; `npm run test:e2e` for end-to-end; place spec files colocated with source, suffix `.spec.ts`)
-4. Write minimal code to pass tests (GREEN)
-5. Refactor while keeping tests green
+1. Restate acceptance in one sentence.
+2. Prove the behavior (user-visible path, focused test at the right level, or explicit manual check).
+3. Prefer a regression that fails if the asked behavior regresses.
 
-This applies to all code — Angular components and services, NgRx effects/reducers, Electron IPC handlers, server CQRS handlers, websocket message handlers, plugin runtime, and domain logic. If the code lives in a package without a configured test runner (server, website, docs-site), surface that gap before adding logic there.
+### Test-backed development (balanced)
 
-### Lint correctness (MANDATORY)
-Before completing any task:
-1. Run `npm run lint` from the repo root (ESLint 9 flat config in `eslint.config.js` covers every package)
-2. Fix all errors
-3. Do not consider work complete until it exits with code 0
+For domain/logic: failing behavior-level test → minimal fix → green.  
+Skip full red-green for docs/copy/agent text, formatting, trivial wiring already covered higher up.
 
-### Type / build correctness (MANDATORY)
-Type checks live in build scripts:
+**Do not:** ship implementation-shaped mocks as the feature; stop at unit-green for product asks; run full monorepo / full e2e on every tiny change — targeted specs first.
 
-- Product client (`toju-app/`): `npm run build` (Angular CLI runs `tsc` with strict settings)
-- Electron (`electron/`): `npm run build:electron` (invokes `tsc -p tsconfig.electron.json`)
-- Server (`server/`): `cd server && npm run build` (invokes `tsc`)
+### Lint / type correctness (scoped)
 
-If your change touches one of these packages, run the corresponding build and ensure it exits 0 before marking work complete.
+1. Targeted Vitest under `toju-app/` (and colocated Electron specs only if you changed those files).
+2. `npm run lint` — fix errors; do not paste entire lint logs into the chat.
+3. `npm run build` when client types/templates could break; `npm run build:electron` only if you changed Electron sources.
 
-## Most important rule
+Do **not** run `cd server && npm run build` or `npm run test:e2e` unless scope expanded or the bug is proven there.
 
-After any change that affects API contracts, schemas, invariants, workflows, or major behavior: update the relevant `agents-docs/features/<slug>.md` as part of the same task — not as a follow-up. New feature area → create `agents-docs/features/<slug>.md` and add an entry to `agents-docs/FEATURES.md` (alphabetical).
+### Feature docs
 
-The product client already maintains per-domain READMEs under `toju-app/src/app/domains/<name>/README.md`. When the change is fully internal to one of those bounded contexts and its surface stays the same, the domain README is the right place to update; cross-context contracts (websocket envelopes, IPC channels, server routes, plugin manifests) belong in `agents-docs/features/`.
-
-## Structure of further instructions
-
-- **Agent workflow & operating rules:** `agents-docs/AGENT_WORKFLOW.md`
-- **Agent lessons (durable cross-session rules):** `agents-docs/LESSONS.md`
-- **Engineering standards:** `agents-docs/ENGINEERING.md`
-- **Feature documentation contract:** `agents-docs/AGENTS_FEATURES.md`
-- **CONTEXT documentation contract:** `agents-docs/AGENTS_CONTEXT.md`
-- **ADR contract:** `agents-docs/AGENTS_ADRS.md`
-- **Feature index:** `agents-docs/FEATURES.md`
-- **Feature docs:** `agents-docs/features/`
-- **Architecture decisions:** `agents-docs/adr/`
-- **Context map:** `agents-docs/CONTEXT-MAP.md`
-- **Obsidian bug tracker:** `agents-docs/BUG_TRACKER.md`
-- **Product-client domain:** `toju-app/CONTEXT.md`
-- **Desktop-shell domain:** `electron/CONTEXT.md`
-- **Server domain:** `server/CONTEXT.md`
-- **E2E suite domain:** `e2e/CONTEXT.md`
-- **Marketing-site domain:** `website/CONTEXT.md`
-- **App-docs domain:** `docs-site/CONTEXT.md`
-
-Keep this file minimal. Do not duplicate detailed rules here.
+Internal domain changes → `toju-app/src/app/domains/<name>/README.md`.  
+IPC/preload/WS contract changes → `agents-docs/features/<slug>.md` when that contract actually changed.
 
 ## Completion checklist
 
-Before marking work complete:
-
-- [ ] Tests written before implementation
-- [ ] All tests passing (`npm run test`, plus `npm run test:e2e` if behavior is user-visible)
-- [ ] `npm run lint` passes
-- [ ] Affected package builds: `npm run build` / `npm run build:electron` / `cd server && npm run build`
-- [ ] Naming conventions followed (kebab-case files; domain `*.rules.ts` / `*.model.ts` / `*.component.ts` suffixes)
-- [ ] Errors handled
-- [ ] Feature docs updated if contract/schema/invariant changed (see `agents-docs/AGENTS_FEATURES.md`)
-- [ ] `CONTEXT.md` updated if a domain term was resolved or introduced (see `agents-docs/AGENTS_CONTEXT.md`)
-- [ ] ADR written if a hard-to-reverse decision was made (see `agents-docs/AGENTS_ADRS.md`)
-- [ ] Lesson recorded in `agents-docs/LESSONS.md` if this session produced a correction, revert, or hidden constraint (see triggers in `agents-docs/AGENT_WORKFLOW.md`)
-- [ ] PR opened with summary and linked issues (`Fixes #<n>` / `Relates to #<n>`)
-- [ ] Gitea Workflows checks passing
+- [ ] Asked behavior proven (not only unit tests green)
+- [ ] Stayed in scope (`toju-app` + targeted `electron` + CI) unless user expanded it
+- [ ] Appropriate targeted tests for logic changes
+- [ ] Lint/build only for touched packages
+- [ ] Docs only if contracts changed
+- [ ] Lesson + index entry if corrected this session
+- [ ] If the thread is long and work remains: write `HANDOFF.md` and ask user for a new chat
+- [ ] PR when requesting merge (`Fixes #<n>` / `Relates to #<n>`)