add evidence-grounded ai assistance

apps/api/README.md

@@ -179,3 +179,15 @@ Every CRM mutation and report/export operation emits an audit record with tenant
 ## Remaining limitations and production migration work
 
 SQLite is a pilot store with an MVP job/event schema but no production migration runner, durable queue, scheduler, worker lease/recovery, durable backup command, or tested restore workflow. Authentication currently uses a development password fallback and does not by itself provide production Argon2id, MFA, CSRF protection, rate limiting, or a complete retention-grade audit system. Website scanning remains subject to pilot limits: no production egress proxy/isolation, distributed crawl coordinator, hardened resolver, or compliance-grade scan-history retention. Production work must add SSRF/DNS-rebinding/redirect-chain tests, egress policy, authenticated history/cache isolation, budget/abuse enforcement, durable result retention/deletion, observability, reviewed content/robots/terms policy, and the Phase 7 PSL/DNS/availability controls. Redis/Celery/Postgres remain future options, not implemented dependencies.
+
+## Phase 13 optional AI assistance API contract
+
+AI assistance is an optional, authenticated, tenant-scoped drafting capability. It may summarize or classify already-held evidence and propose review text; it must not discover facts, verify identity/ownership/deliverability, calculate authoritative score/eligibility, mutate CRM state, merge records, acquire domains, send messages, create campaigns, schedule follow-ups, or perform any autonomous CRM/outreach action. The current Compose runtime does not configure an AI provider or expose a production AI worker; any future route must be explicitly enabled and documented rather than inferred from a provider setting.
+
+Provider selection is server-side and deny-by-default. A primary provider and optional fallback may be configured only from an allowlist of approved provider IDs. Each provider registration must include capability/purpose, model/version, tenant/data-class scope, processing region and retention terms, timeout/token/request budgets, rate and cost limits, approval owner/expiry, health/circuit state, and operational enablement. Fallback may run only for the same approved purpose and input data class; it must preserve the same tenant scope, redaction policy, evidence set, citation contract, and authority level. Provider credentials are secrets and must never appear in request payloads, prompts, responses, logs, Compose, or committed environment files. Provider outage, timeout, quota, policy rejection, or expired approval returns an explicit `unavailable`/`unknown` result and does not silently invent facts or present invented facts as supported claims.
+
+Before a request leaves the tenant boundary, minimize and redact data: include only the bounded evidence fields required for the task; remove credentials, tokens, session data, secrets, unnecessary contact values, raw page bodies, and unrelated personal data; and enforce input/output size limits. Store a redacted request/policy fingerprint, not a sensitive prompt. Every suggestion must carry tenant-scoped evidence IDs/citations, a hash of the exact evidence snapshot used, observed/captured times, uncertainty/conflict reasons, provider/model/version, and policy version. Hashes and citations provide reproducible lineage, not truth or independent verification. If evidence is absent, suppressed, stale, conflicting, blocked, or uncertain, preserve that state and return no unsupported claim.
+
+AI output is untrusted until an authorized human approves it. Approval/rejection must be an explicit tenant-scoped operation with actor, time, reason, output/version, evidence hash/citation set, and before/after value in the audit trail. At approval time re-check authorization, suppression, evidence freshness, provider/policy approval, and hash equality; changed evidence requires a new review. A rejected or expired suggestion must not be applied by retry, fallback, cache, or background work. Approval never converts a citation into proof, consent, deliverability, or outreach permission.
+
+AI records, prompts/fingerprints, outputs, citations, evidence snapshots, approvals, and audit events require explicit retention classes, deletion/legal-hold behavior, tenant-keyed access, and redacted operational logs. Preserve enough hashed lineage to explain an approved result without retaining unnecessary source content. Cross-tenant business, evidence, suggestion, approval, provider, job, cache, and audit IDs behave as not found. Production requires provider contracts/DPA review, secret isolation, immutable/tamper-evident audit, deletion verification, cost/rate monitoring, prompt-injection and hallucination tests, human-review SLAs, kill-switch procedures, and durable worker/retry semantics; none are implied by the current MVP.