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

• Keep NgOptimizedImage off runtime blob and data URLs — [angular] [images]
• Read the exact Obsidian bug note before diagnosing a named ticket — [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]
• Canonicalize direct conversation ids across cross-signal actor aliases — [direct-message] [identity]
• 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]
• 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]
• 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 HANDOFF.md and ask the user for a new chat — agents cannot open chats — [workflow] [tokens] [handoff]