Toju/agents-docs/LESSONS-INDEX.md

# Agent Lessons — Index

**Session start:** read this file only. Match tags to the task. Open the matching lesson body in `agents-docs/LESSONS.md` — do **not** load every lesson.

When adding a lesson: append the full entry near the top of `LESSONS.md` (under `## Lessons`) **and** add one bullet here.

Tags help grepping: `rg '\\[attachments\\]' agents-docs/LESSONS-INDEX.md`

## Index

- A hold-on-unknown rule needs every attach site behind it — `[voice] [webrtc] [realtime]`
- Swap a live device with `replaceTrack`; an empty device list is missing evidence — `[voice] [webrtc] [devices]`
- One owner for a toggle the UI mirrors — `[voice] [state] [ui]`
- A timed-out sync round is not a clean one — `[messages] [realtime] [verification]`
- Derive a conversation id from canonical humans, never from the ids on the wire — `[direct-message] [identity]`
- Report whether a call event was delivered before showing a live call — `[direct-call] [verification]`
- Never spend a retry budget on attempts the transport cannot deliver — `[realtime] [recovery]`
- Repair a dead data channel on the live connection before rebuilding the peer — `[realtime] [webrtc] [recovery]`
- Compare peer ids only within one signal server's identity space — `[realtime] [identity] [webrtc]`
- Reproduce initiator/glare bugs with a simultaneous reconnect, not staggered joins — `[testing] [realtime] [webrtc]`
- Keep `NgOptimizedImage` off runtime blob and data URLs — `[angular] [images]`
- Read the exact Obsidian bug note for `fix bug "…"` (one note only) — `[workflow] [bugs]`
- Run `npm run i18n:sync` after editing any `public/i18n/catalog/*.json` file — `[i18n] [testing]`
- Match direct-call recipients against every local identity alias, exactly like DMs already do — `[direct-call] [identity]`
- Resolve outbound direct-call recipient ids to the peer's connected signal identity — `[direct-call] [identity] [signaling]`
- Decide attachment receive admission once at request time; never re-gate size in the chunk handler — `[attachments]`
- Re-queue attachment auto-downloads on every message/room binding event; never trust one transport's ordering — `[attachments] [realtime]`
- Scope per-user UI state by user id, not by the client database — `[persistence] [multi-user] [custom-emoji]`
- Don't strand signed-out mobile users on a logged-out dashboard — `[auth] [mobile] [routing]`
- "Shared from your device" must gate on local bytes, not uploader user id — `[attachments] [multi-device]`
- Generate Android brand icons from the source mark; guard against stock Capacitor placeholders — `[mobile] [android] [assets]`
- Bind chat attachments to a pre-allocated message id, never by matching content — `[attachments] [chat] [mobile]`
- Attachment file persistence must be platform-agnostic, not Electron-only — `[attachments] [persistence] [mobile]`
- Never count duplicate chunks toward transfer progress, and never finalize on byte counters — `[attachments] [webrtc]`
- Don't bump E2E timeouts for sync flakes - gate on presence and read server logs — `[testing] [realtime]`
- When renaming an Angular route, sweep every navigate/url-match/doc reference — `[routing]`
- Server discovery must fan out across all endpoints and self-heal on 404 — never hardcode a host capability blocklist — `[server-directory]`
- Server registration needs `ownerPublicKey: oderId || id`, and must not be fire-and-forget — `[server-directory] [rooms]`
- Identify must fall back to the legacy session token, not only the new credential store — `[realtime] [authentication]`
- Keep the per-signal-URL identify credential resolvable from the store — `[realtime] [authentication]`
- Store clientInstanceId in sessionStorage not localStorage — `[realtime] [multi-device]`
- Revalidate IndexedDB scope without reinitializing on every read — `[persistence] [performance]`
- Restore local user scope before protected writes — `[authentication] [persistence]`
- Persisted local user state still requires a session token — `[authentication] [signaling]`
- Declare MODIFY_AUDIO_SETTINGS for Android WebRTC mic capture — `[mobile] [android]`
- Do not override Tailwind with box-sizing inherit — `[mobile] [css]`
- Use the app-shell servers rail for mobile discovery pages — `[mobile] [layout]`
- Defer attachment blob hydration on Electron startup — `[attachments] [electron]`
- Lazy-load Capacitor modules on Electron/desktop — `[mobile] [electron]`
- Use the upgrade transaction during IndexedDB schema migrations — `[persistence] [browser]`
- Wait for authenticateUser storage prep before post-login navigation — `[authentication] [browser]`
- Use dense arrays for chunked transfer buffers — `[custom-emoji] [webrtc]`
- Route custom emoji right-click through the native context menu — `[custom-emoji] [ux]`
- Separate known emoji assets from saved library — `[custom-emoji] [ux]`
- Chunk custom emoji assets over data channels — `[custom-emoji] [webrtc]`
- Re-clear visible notification channels after recompute — `[notifications] [startup]`
- Disambiguate nested chat cards — `[chat] [ui]`
- Use terminal Vitest when the test tool hangs — `[testing]`
- Do not add fake chrome around screenshots — `[website] [design]`
- Verify lint exits 0 before claiming done — `[verification]`
- Prefer `npm run lint:fix` over hand-fixing lint/format — `[verification] [lint] [tokens]`
- Use blob URLs for inline attachment previews — `[attachments] [electron]`
- Resolve Electron drag-and-drop file paths with webUtils — `[attachments] [electron]`
- Preserve uploader local attachment paths across sync — `[attachments] [persistence]`
- Interview before coding; don’t guess the fix — `[workflow] [bugs] [tokens]`
- Prove the asked behavior; unit-green is not done — `[verification] [testing] [workflow]`
- Default to `toju-app/` + targeted `electron/` + CI; do not crawl the monorepo — `[workflow] [tokens] [scope]`
- Write/overwrite HANDOFF.md for new chats; clear it when the task finishes — `[workflow] [tokens] [handoff]`
- An outage test that only re-checks the end state is not a guard — `[testing] [verification] [webrtc]`
- coturn hands out a relay candidate but refuses loopback peers by default — `[testing] [webrtc] [turn]`
- Pin a chosen media device with `deviceId: { exact }`, never a bare string — `[webrtc] [media] [electron]`
- A second dev Electron window needs its own `--user-data-dir` — `[electron] [dev-shell]`
- Never answer `second-instance` by relaunching the app — `[electron] [dev-shell]`
- `ERR_FAILED (-2)` on a dev `loadURL` usually means aborted, not unreachable — `[electron] [dev-shell]`
- Never gate a presence indicator on the observer's own participation — `[ui] [voice] [webrtc]`
- Never test suspend/resume against a live-reloading dev server — `[testing] [dev-shell] [verification]`
- Keep diagnostic history outside the page you are diagnosing — `[testing] [verification]`
- Record whether the user is in a call before calling zero RTP a failure — `[testing] [voice] [verification]`
- Assert continuity when the state you broke repairs itself — `[testing] [voice] [verification]`
- Missing gossip about a peer is not evidence it left voice — `[voice] [webrtc] [realtime]`
- `app.commandLine.appendSwitch` cannot disable the Chromium sandbox — `[electron] [packaging] [linux]`