Toju/AGENTS.md

# AGENTS.md

Keep this file small. Detail lives in linked docs — load those **only when the task needs them**.

## Session handoff (new chats)

Agents **cannot** open a new Cursor chat. To reset context:

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

**At session start:** if `agents-docs/HANDOFF.md` has `Status: active`, read it first and continue Next steps. Do not redo Completed work.

## 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 / Toju: desktop-first P2P chat. Default surface: Angular client (`toju-app/`) + targeted Electron bridge + CI.

## CRITICAL — Done means the asked behavior works

**Unit/spec green is support, not done.**

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.

### Test-backed development (balanced)

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.

**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.

### Lint / type correctness (scoped)

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.

Do **not** run `cd server && npm run build` or `npm run test:e2e` unless scope expanded or the bug is proven there.

### Feature docs

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

- [ ] 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>`)