Implement reactions and image sync

LLM_CODING_STANDARDS.md

@@ -0,0 +1,102 @@
+# LLM Coding Standards (GIA)
+
+This document defines implementation standards for coding LLM agents working in this repository.
+
+## 1) Repository Context
+
+GIA is a multi-transport communication workspace with these major domains:
+
+- Transport runtime and relay (`core/modules/router.py`, `core/clients/*`)
+- Shared transport abstraction (`core/clients/transport.py`)
+- Manual compose UX and APIs (`core/views/compose.py` + templates)
+- AI workspace and mitigation operations (`core/views/workspace.py`)
+- OSINT/search UX (`core/views/osint.py`)
+- Core identity/history models (`core/models.py`)
+
+The stack is containerized and commonly managed via `make` commands in `Makefile`.
+
+## 2) Core Design Principles
+
+- Fix root causes first; avoid papering over with UI-only patches.
+- Keep behavior symmetric across `signal`, `whatsapp`, `xmpp`, `instagram` where protocol permits.
+- Centralize shared logic in one place; avoid copy/paste service forks.
+- Prefer small reusable helpers over monolithic in-function branching.
+- Preserve existing UX unless a task explicitly changes interaction behavior.
+
+## 3) Runtime / Restart Policy
+
+- If runtime code changes (`core/clients/*`, router, relay, transport), restart runtime before validating.
+- Preferred full stack recycle: `make stop && make run`.
+- Single-service restart is acceptable, but if dependency state is improper, use full recycle.
+
+## 4) Media Pipeline Rules
+
+- Use one shared attachment prep pipeline (`transport` layer) for outbound service sends.
+- Service adapters should only execute provider-specific API calls after shared prep.
+- Preserve MIME type and filename semantics; infer when source metadata is missing.
+- Never inject internal `/compose/media/blob/...` links as relay body text for attachment-only messages.
+- Blob links are fallback for web/history continuity, not preferred transport payloads.
+
+## 5) XMPP Upload/Share Rules
+
+- Preferred config: `XMPP_UPLOAD_SERVICE` or `XMPP_UPLOAD_JID`.
+- If config absent, use XEP-0363 discovery and normalize discovery to a valid JID.
+- Do not pass raw stanza XML where JID is expected.
+- Keep one place for upload slot and upload error handling semantics.
+
+## 6) Transport Symmetry & Performance
+
+- Improvements for one service’s media path should be mirrored for others when applicable.
+- Keep performance tuning entry points centralized in shared transport helpers.
+- One TODO location per shared bottleneck (e.g. stream-as-completed optimization), not repeated per service.
+
+## 7) Logging and Diagnostics
+
+- Keep production logs high signal:
+  - lifecycle at info
+  - warnings/errors for operational failures
+  - high-volume traces at debug
+- Temporary deep diagnostics must be gated (e.g. `WHATSAPP_DEBUG`) and removable in one patch.
+- Avoid ad-hoc/unprofessional debug strings.
+
+## 8) Large File Refactoring Policy
+
+When touching large files (especially ~2000+ lines):
+
+- Extract minimal reusable helpers in-place or to shared modules.
+- Add short docstrings for shared utility functions.
+- Avoid introducing new repeated service-specific branches.
+
+## 9) Documentation Maintenance Standards
+
+Maintain docs as follows:
+
+- `INSTALL.md` owns setup/config/restart/troubleshooting.
+- `README.md` owns capability map, operation modes, architecture, and interface workflows.
+- Keep README setup instructions short and point to INSTALL first.
+- Update both docs when operational commands/env requirements change.
+- Reflect significant behavior changes (relay semantics, media fallback rules, runtime handoff) in docs immediately.
+
+## 10) Validation Workflow
+
+- Run targeted checks for changed files.
+- Validate runtime behavior with real channel tests after restart.
+- For media/relay changes, validate both directions:
+  - XMPP -> service
+  - service -> XMPP
+- Confirm no regression in web compose display semantics.
+
+## 11) Security & TLS Operational Baseline
+
+- Keep upload endpoints compatible and modern (`TLSv1.2` + `TLSv1.3`).
+- Maintain valid certificate chain/stapling where configured.
+- Treat TLS/protocol mismatch as infra blocker before application-layer debugging.
+
+## 12) Current Operational Priorities (Living Guidance)
+
+As of current project state:
+
+- Stabilize live WhatsApp<->XMPP sync behavior.
+- Complete media relay parity and offline/backfill consistency.
+- Continue reducing transport-specific duplication through shared abstractions.
+- Keep compose and workspace indicators clear and non-ambiguous.