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. **Overwrite** `agents-docs/HANDOFF.md` entirely (`Status: active`) — never append. See `.cursor/rules/handoff.mdc`.
2. Ask the user to start a **new chat** and attach `@agents-docs/HANDOFF.md`.

**At session start:** if `Status: active`, read it first and continue Next steps. Do not redo Completed work.

**When the task is finished:** clear the handoff — set `Status: none` and empty all sections (same short template). Never leave a growing archive in `HANDOFF.md`.

## Named Obsidian bugs

When the user says `fix bug "…"`, follow `agents-docs/BUG_TRACKER.md` § Named fix: open **that one** vault note, **interview before implementing**, then fix in default scope and set `status: Resolved`. Do not scan the whole bug inbox.

## Interview before implement (user in control)

Before changing product code for a bug or feature:

1. Read the ask / named bug note (cheap orientation only — not a monorepo dig).
2. Post a **short interview**: your understanding, gaps, A/B/C choices with a recommended default, proposed scope, how you’ll prove done.
3. **Wait** for the user’s choices. Do not guess past ambiguity.
4. Implement only what they approved.

Skip only if they say “just fix it” / “no interview”, or an active handoff already has approved decisions and they said continue. See `.cursor/rules/interview-before-fix.mdc`.

## 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. Auto-fix style first: `npm run lint:fix` from repo root (`format` + `sort:props` + `eslint . --fix`). Do **not** hand-edit formatting/import-sort/eslint-fixable issues — re-run `lint:fix`. Then confirm clean with `npm run lint` only if you need a no-write check; prefer trusting `lint:fix` exit 0.
3. Do not paste entire lint logs into the chat — fix via `lint:fix` / minimal code changes for non-auto issues.
4. `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

- [ ] Interview completed (or user opted out); implemented only approved choices
- [ ] 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 via `npm run lint:fix` (not hand-fixed style); build only touched packages
- [ ] Docs only if contracts changed
- [ ] Lesson + index entry if corrected this session
- [ ] If the thread is long and work remains: overwrite `HANDOFF.md` and ask user for a new chat
- [ ] If work from an active handoff is finished: clear `HANDOFF.md` to `Status: none` (empty sections)
- [ ] PR when requesting merge (`Fixes #<n>` / `Relates to #<n>`)