Feat/ecrd

[KodeSage]

Description

Adds four operator and contributor reference docs under docs/. All four are built from the code as it is today rather than from intent. Where the code and existing docs disagree, the doc says so and names the file.

Docs only: no source, config or CI files change. Each doc passes the repo's pinned Prettier (3.9.1).

1. docs/environment-variables.md (#542)

One table of every environment variable across apps/backend, apps/web, apps/ai_agent and apps/tests. For each variable it gives the app that reads it, required or optional, the default, when it is loaded, and what breaks if it is wrong.

• Covers every variable in .env.example, plus about 30 read through process.env that .env.example leaves out, including all 15 RATE_LIMIT_<BUCKET> overrides.
• Marks which variables config.ts validates at boot (crash on start) and which are read later, where a bad value fails silently.
• Flags secrets 🔒 and says they must never be committed. Flags every NEXT_PUBLIC_* value 🌐 as compiled into the client bundle and therefore public.

2. docs/release-process.md (#547)

• Documents the contributor PR → dev → main promotion flow. Only the maintainer merges to main, matching the check in guard-main-branch.yml.
• Proposes a SemVer tagging convention. The repo has no tags or changelog today.
• Per-app deploy steps for the backend, Next.js app, AI agent and Soroban contracts, with a release order: contracts → migrations → backend → AI agent → web.
• Migrations run before the backend rollout. Destructive schema changes use a two-release expand/contract pattern, because old and new instances run at the same time.
• Contract deploys are a separate path with no rollback, cross-linked to contracts/docs/api-deployment-invocation.md.
• States the rollback story for each app honestly, including where one does not exist: DB migrations, Weaviate vectors, on-chain state.
• Post-deploy checks cross-link the relevant sections of docs/runbook.md.

3. docs/code-style.md (#551)

• For each language (Prettier, ESLint for TS/TSX, tsc, ruff + mypy, rustfmt + clippy): the tool, config file, command, and whether CI blocks on it.
• Documents .prettierignore and its rule: generated output (drizzle meta/, *.d.ts, Soroban test_snapshots/) is never formatted.
• Records the house comment convention: comments explain why and cite the motivating issue (#N — / (#N)). 56 of the 83 non-test backend source files follow it.
• Records measured warning counts: backend ESLint 58 (no-explicit-any), web ESLint 4 (no-unused-vars). These are non-blocking, but no PR may add to them.

4. docs/data-retention.md (#554)

• A table for every data category: store, content or metadata, retention window, and the job or action that removes it. Covers messages and envelopes, files (soft then hard delete), devices and prekeys, audit logs, Redis presence and resume streams, and push subscriptions.
• Documents the three GC jobs and their schedules: device GC hourly, envelope GC every 30 min, file cleanup every 5 min.
• States plainly what erasure cannot reach: audit rows are append-only and deliberately not FK-linked, and on-chain transaction data is permanent.
• Separates end-to-end-encrypted content from server-visible metadata, cross-linking docs/threat-model.md.

Problems found while writing these docs

These are recorded in the docs and left unfixed so this PR stays docs-only. Each is worth a follow-up issue.

Security

• The backend loads its .env file after all its imports have run. Values set only in .env are therefore missed by any module that reads its settings at import time. JWT_SECRET then falls back to 'test-secret', and the boot check still passes.
• deploy_group_treasury.sh does not pass the required threshold argument, so the initialize step fails. The contract is left deployed but uninitialised, and anyone can initialise it and become admin.
• The audit_logs_no_mutation append-only trigger is described in the docs and the schema, but no migration creates it. 0001_audit_logs.sql does not exist.

Data retention

• There is no account-deletion path.
• AI assistant replies are stored as server-readable plaintext, and no user can delete them.
• The AI agent's /index/message stores plaintext message content in Weaviate, with no retention window and no delete endpoint.
• When a group's last member leaves, the database deletes its files rows along with the conversation. The cleanup job never finds them, so their encrypted blobs stay in the object store forever.

Config drift

• .env.example lists RPC_URL, but the code reads STELLAR_RPC_URL.
• IDEMPOTENCY_TTL_SECONDS is validated at boot but never used.
• XMTP_ENV, PROPOSALS_CONTRACT_ID and all S3_* variables are never read.

Process and CI

• There is no dev branch on origin yet.
• Nothing enforces that only the maintainer merges to main. The guard workflow only checks who opened the PR, so a branch-protection rule is needed.
• CI does not run a Prettier check outside apps/backend/src, a cargo fmt check, or a backend tsc type check.

Issue numbers

Closes #542
Closes #547
Closes #551
Closes #554

Type of change

• Bug fix
• New feature
• Documentation update
• Other

Checklist

• I have read the contributing guidelines
• I have tested my changes locally: each doc passes prettier --check, internal links and anchors were checked against the target headings, and the lint and format counts in code-style.md were measured by running the tools
• My code follows the project's coding standards: formatted with the pinned Prettier 3.9.1 and the shared .prettierrc.json