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