add evidence-grounded ai assistance

README.md

@@ -191,4 +191,16 @@ git diff --check
 docker compose config --quiet
 ```
 
+## Phase 13 optional AI assistance boundary
+
+Phase 13 adds optional, human-reviewed AI assistance for summarization, classification, and evidence-oriented suggestions. AI is a drafting aid, not a source of truth, verifier, identity resolver, score/eligibility authority, or CRM actor. It is disabled unless an explicitly configured provider and tenant-scoped policy permit the requested operation. A provider failure, timeout, quota/rate limit, approval expiry, missing evidence, or ambiguous result fails closed to `unknown`/`unavailable`; it must never be represented as a successful empty result.
+
+Provider configuration is optional and deny-by-default. A deployment may configure a primary provider and an optional fallback, but each provider must have an approved purpose/capability, tenant scope, data-processing/retention terms, region/egress policy, model/version, timeout/token budget, rate limit, cost ceiling, and operational enablement. Fallback is permitted only to another pre-approved provider for the same purpose and data class; it must not broaden tenant scope, retention, prompt data, or authority. No provider credentials belong in source, Compose files, logs, or committed `.env` files. The current Compose stack does not provision an AI provider; production enablement remains gated configuration work.
+
+AI requests must minimize data before transmission: send only the fields and evidence excerpts needed for the approved task, redact secrets and unnecessary personal/contact data, avoid raw page bodies and credentials, and record a redacted request/policy fingerprint rather than a prompt containing sensitive data. Every generated suggestion must cite the tenant-scoped evidence IDs/source references and preserve evidence hash, citation, observed time, provider/model/version, policy version, and uncertainty. Hashes identify the exact evidence snapshot for reproducibility; they do not prove that the source is true. Missing, conflicting, stale, suppressed, or low-quality evidence must remain visible and must not be filled with invented facts.
+
+AI output is an untrusted draft. It requires an authorized human approval/rejection (and an explicit reason for material changes) before it can become a stored claim, score input, pipeline update, contact decision, export, or any other consequential record. Approval must re-check tenant scope, suppression, evidence freshness, policy/version, and the unchanged evidence hash; stale or changed inputs require re-review. AI cannot create or edit CRM interactions/outcomes as if communication occurred, send messages, create campaigns, schedule follow-ups, contact prospects, merge records, acquire domains, or perform autonomous outreach. Suppressed/do-not-contact records remain visible for safety review and are never made eligible by an AI result.
+
+Phase 13 is pilot-only. Before production, implement provider allowlisting and secret management, data-processing agreements, prompt/output redaction tests, evidence hash/citation verification, approval and rollback semantics, immutable audit coverage, tenant-isolation tests, retention/deletion/legal-hold jobs, cost/rate monitoring, incident disablement, and evaluation for hallucination, prompt injection, bias, and stale/conflicting evidence. See the API, web, security, and operations contracts for the authoritative limitations.
+
 See `apps/api/README.md`, `apps/web/README.md`, `docs/SECURITY.md`, and `docs/OPERATIONS.md` for details.

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.

apps/api/app/ai_assistance.py

@@ -0,0 +1,93 @@
+"""Evidence-bounded AI assistance primitives for Phase 13.
+
+This module deliberately has no network or model dependency.  The local provider is
+an auditable formatter over stored records; other providers are reported as
+not_configured rather than guessed at.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from typing import Any
+
+MAX_INPUT_ITEMS = 100
+MAX_FIELD_CHARS = 500
+MAX_OUTPUT_CHARS = 12_000
+SUPPORTED_KINDS = ("summary", "qualification_explanation", "missing_data_questions", "research_note")
+_SECRET_RE = re.compile(r"(?i)(password|passwd|secret|token|api[_-]?key|authorization|private[_-]?key|credential)\s*[:=]\s*[^\s,;]+")
+
+
+def _text(value: Any, limit: int = MAX_FIELD_CHARS) -> str:
+    value = "" if value is None else str(value)
+    value = _SECRET_RE.sub(r"\1: [REDACTED]", value)
+    return value[:limit]
+
+
+def redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(k)[:80]: ("[REDACTED]" if re.search(r"(?i)(password|passwd|secret|token|api[_-]?key|authorization|private[_-]?key|credential)", str(k)) else redact(v)) for k, v in list(value.items())[:100]}
+    if isinstance(value, list):
+        return [redact(v) for v in value[:MAX_INPUT_ITEMS]]
+    if isinstance(value, str):
+        return _text(value)
+    return value
+
+
+def evidence_hashes(evidence: list[dict[str, Any]]) -> list[str]:
+    return [hashlib.sha256(json.dumps(redact(item), sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest() for item in evidence]
+
+
+def _citation(item: dict[str, Any]) -> dict[str, Any]:
+    return {"evidence_id": int(item["id"]), "kind": _text(item.get("kind", "evidence"), 80), "url": _text(item.get("url", ""), 500)}
+
+
+def _claim(item: dict[str, Any]) -> str:
+    return _text(item.get("claim", ""), MAX_FIELD_CHARS).strip()
+
+
+def build_local_suggestions(business: dict[str, Any], scans: list[dict[str, Any]], contacts: list[dict[str, Any]], evidence: list[dict[str, Any]], score_history: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    """Create deterministic suggestions using only supplied stored data.
+
+    Every claim-bearing item cites one or more rows from ``evidence``.  No
+    contact details are emitted, and contacts are used only as aggregate counts.
+    """
+    evidence = [redact(x) for x in evidence[:MAX_INPUT_ITEMS] if _claim(x)]
+    citations = [_citation(x) for x in evidence]
+    claims = [_claim(x) for x in evidence]
+    suggestions: list[dict[str, Any]] = []
+    name = _text(business.get("name", "this business"), 200)
+    if claims:
+        joined = " ".join(f"{claim} [evidence:{item['id']}]" for claim, item in zip(claims[:5], evidence[:5]))
+        suggestions.append({"type": "summary", "text": f"Stored evidence for {name}: {joined}", "citations": citations[:5]})
+        score = business.get("score")
+        if score is not None:
+            suggestions.append({"type": "qualification_explanation", "text": f"The stored qualification score is {_text(score, 30)}; review the cited evidence before relying on it. [evidence:{evidence[0]['id']}]", "citations": citations[:1]})
+        missing = []
+        if not _text(business.get("website", "")).strip(): missing.append("official website")
+        if not contacts: missing.append("public contact evidence")
+        if missing:
+            suggestions.append({"type": "missing_data_questions", "text": "Confirm whether the following data is available: " + ", ".join(missing) + f". [evidence:{evidence[0]['id']}]", "citations": citations[:1]})
+        suggestions.append({"type": "research_note", "text": f"Draft note: independently verify the stored claims for {name}; do not infer facts beyond the cited records. [evidence:{evidence[0]['id']}]", "citations": citations[:1]})
+    else:
+        # No claim is fabricated.  A question is safe but has no citation, so
+        # return no suggestions and let the caller expose the missing-data state.
+        suggestions = []
+    output = {"provider": "local", "version": "deterministic-v1", "suggestions": suggestions, "grounded": True, "claim_policy": "stored_evidence_only"}
+    encoded = json.dumps(output, sort_keys=True, ensure_ascii=False)
+    return json.loads(encoded[:MAX_OUTPUT_CHARS]) if len(encoded) <= MAX_OUTPUT_CHARS else {"provider": "local", "version": "deterministic-v1", "suggestions": suggestions[:1], "grounded": True, "claim_policy": "stored_evidence_only"}
+
+
+def provider_name() -> str | None:
+    value = os.environ.get("AI_PROVIDER", "").strip().lower()
+    return value or None
+
+
+def generate(business: dict[str, Any], scans: list[dict[str, Any]], contacts: list[dict[str, Any]], evidence: list[dict[str, Any]], score_history: list[dict[str, Any]] | None = None) -> tuple[str, str, str, dict[str, Any]]:
+    provider = provider_name()
+    hashes = evidence_hashes(evidence)
+    metadata = {"input_counts": {"business": 1, "scans": min(len(scans), MAX_INPUT_ITEMS), "contacts": min(len(contacts), MAX_INPUT_ITEMS), "evidence": min(len(evidence), MAX_INPUT_ITEMS)}, "redacted": True, "max_input_items": MAX_INPUT_ITEMS, "max_field_chars": MAX_FIELD_CHARS, "evidence_hashes": hashes}
+    if provider not in {"local", "deterministic"}:
+        return "not_configured", provider or "", "", metadata
+    return "succeeded", "local", "deterministic-v1", {**metadata, "output": build_local_suggestions(business, scans, contacts, evidence, score_history)}

apps/api/app/main.py

@@ -13,6 +13,7 @@ if __package__ in (None, ""):
     from app.website_scanner import scan_website, validate_url
     from app.contact_extractor import extract_contacts, MAX_HTML_BYTES, MAX_RESULTS
     from app.scoring import DEFAULT_RULES, signals_for_business, evaluate_score, SCORE_VERSION
+    from app.ai_assistance import generate as generate_ai, MAX_INPUT_ITEMS, MAX_OUTPUT_CHARS
 else:
     from .domain import deduplication_key, deduplicate_businesses, is_suppressed, normalize_business, score_business, normalize_domain, normalize_phone, match_businesses
     from .sources import adapter_for, contains_secret
@@ -20,6 +21,7 @@ else:
     from .website_scanner import scan_website, validate_url
     from .contact_extractor import extract_contacts, MAX_HTML_BYTES, MAX_RESULTS
     from .scoring import DEFAULT_RULES, signals_for_business, evaluate_score, SCORE_VERSION
+    from .ai_assistance import generate as generate_ai, MAX_INPUT_ITEMS, MAX_OUTPUT_CHARS
 ORGANIZATION_ID = "demo-tenant"
 SCHEMA = Path(__file__).resolve().parents[1] / "schema.sql"
 SESSION_DAYS = 7
@@ -296,6 +298,66 @@ class ApiHandler(BaseHTTPRequestHandler):
             rows=db.execute(sql,params).fetchall(); return self.send_json(200,{"organization_id":org,"items":[dict(r) for r in rows]})
         except ValueError as exc: return self.send_json(400,{"error":str(exc)})
 
+    def _ai_run_json(self, row, suggestions=None):
+        item = row_json(row)
+        for key in ("input_evidence_hashes_json", "prompt_metadata_json", "data_minimization_json", "output_json"):
+            source = item.pop(key, "{}" if key != "input_evidence_hashes_json" else "[]")
+            try: item[key[:-5] if key.endswith("_json") else key] = json.loads(source or ("{}" if key != "input_evidence_hashes_json" else "[]"))
+            except (TypeError, ValueError): item[key[:-5] if key.endswith("_json") else key] = {} if key != "input_evidence_hashes_json" else []
+        if suggestions is not None: item["suggestions"] = suggestions
+        return item
+
+    def suggest_ai(self, bid, payload, db, user):
+        org = user["organization_id"]
+        business = self.business(db, bid, org)
+        if not business: return self.send_json(404, {"error": "not_found"})
+        business_dict = row_json(business)
+        suppressions = [dict(r) for r in db.execute("SELECT kind,value FROM suppressions WHERE organization_id=? AND active=1", (org,))]
+        contacts = [dict(r) for r in db.execute("SELECT * FROM contacts WHERE business_id=? AND organization_id=?", (bid, org))]
+        extracted = [dict(r) for r in db.execute("SELECT * FROM contact_extractions WHERE business_id=? AND organization_id=?", (bid, org))]
+        if is_suppressed(business_dict, suppressions) or any(bool(c.get("do_not_contact") or c.get("suppressed")) for c in contacts + extracted):
+            return self.send_json(409, {"error": "ai_blocked_suppressed_business", "business_id": bid})
+        try:
+            requested = int(payload.get("max_items", MAX_INPUT_ITEMS))
+            if requested < 1 or requested > MAX_INPUT_ITEMS: raise ValueError
+        except (ValueError, TypeError): return self.send_json(400, {"error": "invalid_limits"})
+        scans = [dict(r) for r in db.execute("SELECT id,input_url,classification,result_json,scanned_at FROM website_scans WHERE business_id=? AND organization_id=? ORDER BY id DESC LIMIT ?", (bid, org, requested)).fetchall()]
+        evidence = [dict(r) for r in db.execute("SELECT id,kind,url,claim,created_at FROM evidence WHERE business_id=? AND organization_id=? ORDER BY id DESC LIMIT ?", (bid, org, requested)).fetchall()]
+        history = [dict(r) for r in db.execute("SELECT score,eligible,priority_band,score_version,explanations_json,created_at FROM score_history WHERE business_id=? AND organization_id=? ORDER BY id DESC LIMIT ?", (bid, org, requested)).fetchall()]
+        status, provider, version, metadata = generate_ai(business_dict, scans[:requested], contacts[:requested], evidence[:requested], history[:requested])
+        output = metadata.pop("output", {}) if status == "succeeded" else {"suggestions": [], "grounded": True, "claim_policy": "stored_evidence_only"}
+        hashes = metadata.get("evidence_hashes", [])
+        cur = db.execute("INSERT INTO ai_runs(organization_id,business_id,input_evidence_hashes_json,model,provider,version,prompt_metadata_json,data_minimization_json,status,approval_state,output_json,actor_user_id) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)", (org, bid, json.dumps(hashes, sort_keys=True), "local-deterministic" if provider else "", provider, version, json.dumps({"request": {"max_items": requested}, "output_limit": MAX_OUTPUT_CHARS}, sort_keys=True), json.dumps(metadata, sort_keys=True), status, "pending", json.dumps(output, sort_keys=True), user["id"]))
+        run_id = cur.lastrowid
+        for suggestion in output.get("suggestions", []):
+            db.execute("INSERT INTO ai_suggestions(ai_run_id,organization_id,business_id,suggestion_type,citations_json,output_json) VALUES(?,?,?,?,?,?)", (run_id, org, bid, str(suggestion.get("type", ""))[:80], json.dumps(suggestion.get("citations", []), sort_keys=True), json.dumps(suggestion, sort_keys=True)))
+        self.audit(db, user, "ai.suggested", str(run_id)); db.commit()
+        row = db.execute("SELECT * FROM ai_runs WHERE id=? AND organization_id=?", (run_id, org)).fetchone()
+        return self.send_json(201, self._ai_run_json(row, output.get("suggestions", [])))
+
+    def list_ai_runs(self, db, user, query):
+        try:
+            limit = int((query.get("page_size") or [50])[0]); offset = max(0, int((query.get("offset") or [0])[0]))
+            if limit < 1 or limit > 100: raise ValueError
+        except (ValueError, TypeError): return self.send_json(400, {"error": "invalid_pagination"})
+        rows = db.execute("SELECT * FROM ai_runs WHERE organization_id=? ORDER BY id DESC LIMIT ? OFFSET ?", (user["organization_id"], limit + 1, offset)).fetchall()
+        items = []
+        for row in rows[:limit]:
+            suggestions = [json.loads(x[0]) for x in db.execute("SELECT output_json FROM ai_suggestions WHERE ai_run_id=? AND organization_id=? ORDER BY id", (row["id"], user["organization_id"]))]
+            items.append(self._ai_run_json(row, suggestions))
+        return self.send_json(200, {"organization_id": user["organization_id"], "items": items, "limit": limit, "offset": offset, "has_more": len(rows) > limit})
+
+    def decide_ai(self, run_id, decision, db, user):
+        row = db.execute("SELECT * FROM ai_runs WHERE id=? AND organization_id=?", (run_id, user["organization_id"])).fetchone()
+        if not row: return self.send_json(404, {"error": "not_found"})
+        if decision == "approve" and row["status"] != "succeeded": return self.send_json(409, {"error": "run_not_approvable"})
+        if row["approval_state"] != "pending": return self.send_json(409, {"error": "already_decided"})
+        now = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+        if decision == "approve": db.execute("UPDATE ai_runs SET approval_state='approved',approved_at=? WHERE id=? AND organization_id=?", (now, run_id, user["organization_id"]))
+        else: db.execute("UPDATE ai_runs SET approval_state='rejected',rejected_at=? WHERE id=? AND organization_id=?", (now, run_id, user["organization_id"]))
+        self.audit(db, user, "ai." + decision, str(run_id)); db.commit()
+        return self.send_json(200, self._ai_run_json(db.execute("SELECT * FROM ai_runs WHERE id=?", (run_id,)).fetchone()))
+
     def do_GET(self):
         parsed=urlparse(self.path); path=parsed.path.rstrip("/")
         if path=="/api/v1/health/live": return self.send_json(200,{"status":"ok","organization_id":ORGANIZATION_ID})
@@ -331,6 +393,7 @@ class ApiHandler(BaseHTTPRequestHandler):
             if path=="/api/v1/outcomes": return self.send_json(200,{"items":sorted(self.OUTCOMES)})
             if path=="/api/v1/interactions": return self.list_interactions(db,org,parse_qs(parsed.query))
             if path=="/api/v1/suppressions": return self.list_suppressions(db,org,parse_qs(parsed.query))
+            if path=="/api/v1/ai-runs": return self.list_ai_runs(db,user,parse_qs(parsed.query))
             if path in ("/api/v1/reports/pipeline","/api/v1/reports/outcomes","/api/v1/reports/activity"): return self.report(db,org,path.rsplit('/',1)[1],parse_qs(parsed.query))
             if path.startswith("/api/v1/jobs/"): return self.get_job_route(db,org,path,parse_qs(parsed.query))
             if path.startswith("/api/v1/businesses/"):
@@ -691,6 +754,9 @@ class ApiHandler(BaseHTTPRequestHandler):
             payload=self.read_json(); org=user["organization_id"]
             if path=="/api/v1/saved-filters": return self.save_filter(payload,db,user)
             if path=="/api/v1/businesses/bulk-review": return self.bulk_review(payload,db,user)
+            bits_ai=path.split("/")
+            if len(bits_ai)==7 and bits_ai[:4]==["","api","v1","businesses"] and bits_ai[5]=="ai" and bits_ai[6]=="suggest": return self.suggest_ai(int(bits_ai[4]) if bits_ai[4].isdigit() else -1,payload,db,user)
+            if len(bits_ai)==6 and bits_ai[:4]==["","api","v1","ai-runs"] and bits_ai[4].isdigit() and bits_ai[5] in {"approve","reject"}: return self.decide_ai(int(bits_ai[4]),bits_ai[5],db,user)
             if path=="/api/v1/score-rules": return self.create_score_rule(payload,db,user)
             if len(path.split("/"))==7 and path.split("/")[3:]==["businesses",path.split("/")[4],"score","recalculate"]: return self.recalculate_score(int(path.split("/")[4]) if path.split("/")[4].isdigit() else -1,payload,db,user)
             if path.startswith("/api/v1/jobs/"):

apps/api/schema.sql

@@ -254,3 +254,29 @@ CREATE TABLE IF NOT EXISTS saved_filters (
  UNIQUE(organization_id,user_id,name)
 );
 CREATE INDEX IF NOT EXISTS idx_saved_filters_org_user ON saved_filters(organization_id,user_id,updated_at DESC,id DESC);
+
+-- Phase 13 optional, evidence-bounded AI assistance.  Outputs are drafts only.
+CREATE TABLE IF NOT EXISTS ai_runs (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ organization_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+ business_id INTEGER REFERENCES businesses(id) ON DELETE SET NULL,
+ input_evidence_hashes_json TEXT NOT NULL DEFAULT '[]',
+ model TEXT NOT NULL DEFAULT '', provider TEXT NOT NULL DEFAULT '', version TEXT NOT NULL DEFAULT '',
+ prompt_metadata_json TEXT NOT NULL DEFAULT '{}', data_minimization_json TEXT NOT NULL DEFAULT '{}',
+ status TEXT NOT NULL CHECK(status IN ('not_configured','succeeded','failed','rejected')),
+ approval_state TEXT NOT NULL DEFAULT 'pending' CHECK(approval_state IN ('pending','approved','rejected')),
+ output_json TEXT NOT NULL DEFAULT '{}',
+ created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, approved_at TEXT, rejected_at TEXT,
+ actor_user_id INTEGER REFERENCES users(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ai_runs_org_created ON ai_runs(organization_id,created_at DESC,id DESC);
+CREATE INDEX IF NOT EXISTS idx_ai_runs_business ON ai_runs(organization_id,business_id,created_at DESC,id DESC);
+CREATE TABLE IF NOT EXISTS ai_suggestions (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ ai_run_id INTEGER NOT NULL REFERENCES ai_runs(id) ON DELETE CASCADE,
+ organization_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+ business_id INTEGER REFERENCES businesses(id) ON DELETE SET NULL,
+ suggestion_type TEXT NOT NULL, citations_json TEXT NOT NULL DEFAULT '[]', output_json TEXT NOT NULL DEFAULT '{}',
+ created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_ai_suggestions_run ON ai_suggestions(organization_id,ai_run_id,id);

apps/api/tests/test_phase13_api.py

@@ -0,0 +1,82 @@
+import json
+import os
+import sqlite3
+import threading
+import unittest
+from http.client import HTTPConnection
+from tempfile import TemporaryDirectory
+
+from app.ai_assistance import build_local_suggestions, generate
+from app.main import create_server
+from app.main import hash_password
+
+
+class Phase13ApiTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = TemporaryDirectory()
+        self.old = {key: os.environ.get(key) for key in ("AI_PROVIDER", "BOOTSTRAP_ADMIN_EMAIL", "BOOTSTRAP_ADMIN_PASSWORD")}
+        os.environ["BOOTSTRAP_ADMIN_EMAIL"] = "ai-owner@example.test"
+        os.environ["BOOTSTRAP_ADMIN_PASSWORD"] = "ai-password"
+        os.environ["AI_PROVIDER"] = "local"
+        self.server = create_server("127.0.0.1", 0, self.tmp.name + "/ai.db")
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True); self.thread.start()
+        self.conn = HTTPConnection("127.0.0.1", self.server.server_port, timeout=3); self.cookie = None
+        self.request("POST", "/api/v1/auth/login", {"email": "ai-owner@example.test", "password": "ai-password"})
+
+    def tearDown(self):
+        self.server.shutdown(); self.server.server_close(); self.thread.join(timeout=2); self.tmp.cleanup()
+        for key, value in self.old.items():
+            if value is None: os.environ.pop(key, None)
+            else: os.environ[key] = value
+
+    def request(self, method, path, payload=None):
+        body = json.dumps(payload).encode() if payload is not None else None; headers = {"Content-Type": "application/json"}
+        if self.cookie: headers["Cookie"] = self.cookie
+        self.conn.request(method, path, body, headers); response = self.conn.getresponse(); cookie = response.getheader("Set-Cookie")
+        if cookie: self.cookie = cookie.split(";", 1)[0]
+        return response.status, json.loads(response.read() or b"{}")
+
+    def test_local_fallback_is_deterministic_and_evidence_bounded(self):
+        args = ({"id": 4, "name": "Acme", "score": 10}, [], [], [{"id": 2, "kind": "source", "url": "https://source.test", "claim": "Makes widgets"}])
+        first = build_local_suggestions(*args); second = build_local_suggestions(*args)
+        self.assertEqual(first, second)
+        self.assertIn("[evidence:2]", first["suggestions"][0]["text"])
+        self.assertNotIn("customers", json.dumps(first).lower())
+
+    def test_no_provider_returns_not_configured_without_output(self):
+        os.environ.pop("AI_PROVIDER", None)
+        status, provider, version, metadata = generate({"name": "Acme"}, [], [], [])
+        self.assertEqual(status, "not_configured"); self.assertEqual(provider, ""); self.assertEqual(version, "")
+        self.assertNotIn("output", metadata)
+
+    def test_endpoint_persists_citations_and_approval_without_crm_write(self):
+        status, business = self.request("POST", "/api/v1/businesses", {"name": "Evidence Co", "website": "https://evidence.test"}); self.assertEqual(status, 201)
+        bid = business["id"]
+        self.request("POST", f"/api/v1/businesses/{bid}/evidence", {"kind": "source", "url": "https://source.test", "claim": "Serves Cape Town"})
+        status, run = self.request("POST", f"/api/v1/businesses/{bid}/ai/suggest", {}); self.assertEqual(status, 201)
+        self.assertTrue(all(s["citations"] for s in run["suggestions"]))
+        self.assertEqual(self.request("POST", f"/api/v1/ai-runs/{run['id']}/approve", {})[1]["approval_state"], "approved")
+        self.assertEqual(self.request("POST", f"/api/v1/ai-runs/{run['id']}/reject", {})[0], 409)
+        db = sqlite3.connect(self.tmp.name + "/ai.db")
+        self.assertEqual(db.execute("SELECT COUNT(*) FROM pipeline_entries").fetchone()[0], 0); self.assertEqual(db.execute("SELECT COUNT(*) FROM interactions").fetchone()[0], 0); db.close()
+
+    def test_limits_and_suppressed_business_are_safe(self):
+        status, business = self.request("POST", "/api/v1/businesses", {"name": "Safe Co"}); self.assertEqual(status, 201)
+        bid = business["id"]
+        self.assertEqual(self.request("POST", f"/api/v1/businesses/{bid}/ai/suggest", {"max_items": 101})[0], 400)
+        self.request("POST", "/api/v1/suppressions", {"kind": "domain", "value": "safe.test"})
+        # Directly mark the business with the suppressed domain to exercise the AI guard.
+        db = sqlite3.connect(self.tmp.name + "/ai.db"); db.execute("UPDATE businesses SET website_domain='safe.test' WHERE id=?", (bid,)); db.commit(); db.close()
+        self.assertEqual(self.request("POST", f"/api/v1/businesses/{bid}/ai/suggest", {})[0], 409)
+    def test_tenant_isolation_applies_to_ai_runs_and_business_suggestions(self):
+        status, business = self.request("POST", "/api/v1/businesses", {"name": "Tenant A"}); self.assertEqual(status, 201)
+        ph, salt = hash_password("other-password")
+        db = sqlite3.connect(self.tmp.name + "/ai.db")
+        db.execute("INSERT INTO organizations (id,name) VALUES (?,?)", ("other-tenant", "Other"))
+        db.execute("INSERT INTO users (organization_id,email,password_hash,password_salt,role) VALUES (?,?,?,?,?)", ("other-tenant", "other-ai@example.test", ph, salt, "owner")); db.commit(); db.close()
+        self.cookie = None; self.assertEqual(self.request("POST", "/api/v1/auth/login", {"email": "other-ai@example.test", "password": "other-password"})[0], 200)
+        self.assertEqual(self.request("POST", f"/api/v1/businesses/{business['id']}/ai/suggest", {})[0], 404)
+        self.assertEqual(self.request("GET", "/api/v1/ai-runs")[1]["items"], [])
+
+
+if __name__ == "__main__": unittest.main()

apps/web/README.md

@@ -111,3 +111,13 @@ There is no send button, message composer, SMTP probe, validation email, campaig
 ## Remaining limitations
 
 The static client has no client-side crawler, scanner, contact extractor, enrichment scheduler, outreach integration, availability provider, or SSE delivery. It can display server-provided Phase 9 observations, but production still requires server-side official-site scoping, SSRF/DNS-rebinding/redirect controls, hard extraction/page/byte/time/candidate budgets, durable history/cache isolation and retention/deletion, abuse/rate controls, suppression regression tests, and authenticated provenance/audit coverage. For domain intelligence, display registrable-domain/PSL version and unresolved reasons, DNS status and freshness/TTL (not “available”), independent MX/NS/TXT uncertainty, and association confidence with explainable evidence. Never auto-attach candidate domains or treat `nxdomain`/`no_data` as availability. CSV preview is capped for display and is not an import workflow.
+
+## Phase 13 optional AI assistance UI contract
+
+The UI may offer AI drafting only when the authenticated API reports an approved, enabled capability for the current tenant and task. Provider choice, fallback, prompt construction, redaction, budgets, tenant authorization, and suppression checks are server-side; the browser must never receive provider secrets or call an AI vendor directly. Show provider/model/version and `unknown`/`unavailable`, timeout, partial, stale, or policy-blocked states distinctly from an empty or successful result.
+
+Every suggestion must display its evidence citations, tenant-scoped evidence IDs, exact evidence hash/snapshot identifier, observed time, uncertainty/conflict reasons, and policy/provider/model versions. A citation points to the evidence used; it is not proof that the source is correct, and an AI explanation is not an independently verified fact. Do not render unsupported or invented facts about names, roles, contact details, dates, outcomes, consent, deliverability, ownership, or other claims as facts. Preserve missing and conflicting evidence instead of filling gaps. Suppressed/do-not-contact records remain visible with the safety state and never become actionable because an AI suggestion is confident.
+
+AI output must be visibly labeled **AI suggestion — human review required** and remain read-only until an authorized human explicitly approves it. Approval must show the proposed change, citations/hash, freshness, tenant scope, and safe reason; rejection and expiry must be available. The UI must require re-review when the evidence hash or policy version changes and must display partial/failed approval rather than implying persistence. Approval does not authorize contact or verification.
+
+No Phase 13 control may send email/SMS, probe SMTP, create a campaign, schedule follow-up, alter pipeline/interactions/outcomes as if communication occurred, merge records, acquire a domain, or perform autonomous CRM/outreach actions. The browser must not hide or export suppressed data as eligible, and exports/reports must retain safe AI provenance and redaction labels where applicable. Production remains limited until browser/API tests cover citations and hash mismatch, redaction, fallback boundaries, approval/rejection, stale/conflicting evidence, suppression precedence, tenant non-disclosure, and no-autonomy controls; the current Compose stack has no configured AI provider.

apps/web/app.js

@@ -122,7 +122,27 @@
     panel.innerHTML=`<div class="score-panel-heading"><div><p class="eyebrow">SCORING</p><h4>Score breakdown</h4></div><button class="button ghost compact" id="recalculateScoreBtn" type="button">↻ Recalculate</button></div><div class="score-breakdown-summary"><div><small>Total score</small><strong class="score-total ${scoreClass(score)}">${esc(score)}<small>/ 100</small></strong></div><div><small>Priority</small><b>${esc(priority)}</b></div><div><small>Eligibility</small><b>${esc(eligible)}</b></div></div><dl class="score-meta"><div><dt>Score version</dt><dd>${esc(version)}</dd></div><div><dt>Signals</dt><dd>${factors.length}</dd></div></dl><div class="score-rules-explanation"><h5>Rule explanations</h5>${factors.length?factors.map(raw=>{const item=scoreExplanation(raw);return `<div class="score-rule-row"><span>${esc(scoreValue(item,['label','name','rule','factor'],'Scoring signal'))}</span><strong>${esc(scoreValue(item,['points','value','weight'],0))} pts</strong><small>${esc(scoreValue(item,['explanation','reason','description'],'Observed evidence contributes to this score.'))}</small></div>`}).join(''):'<p class="muted">No scoring signals returned.</p>'}</div><p class="score-safety">Scores are review signals only. They do not override suppression or authorize outreach.</p><p id="scoreMessage" class="form-message" role="status" aria-live="polite"></p>`;
   }
   async function recalculateScore() { const button=$('recalculateScoreBtn'), messageEl=$('scoreMessage'); if(!button||!selectedId)return; button.disabled=true; if(messageEl)messageEl.textContent='Recalculation requested…'; try { const result=await jsonRequest(`/api/v1/businesses/${encodeURIComponent(selectedId)}/score/recalculate`,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({})}); if(messageEl)messageEl.textContent=result?.status==='queued'?'Recalculation queued. Refresh when the job completes.':'Score recalculation accepted. Refresh to see the API result.'; } catch(error) { if(error.message!=='unauthorized'&&messageEl){messageEl.textContent=error.message||'Unable to recalculate score.';messageEl.className='form-message error';} } finally {button.disabled=false;} }
-  function renderDetail(p){const s=scoreFor(p),st=statusOf(p),f=freshness(p),factors=p.score_factors||p.factors||[],blocked=st==='review'||st==='suppressed',stage=p.pipeline_stage||p.pipeline?.stage||(Array.isArray(p.pipeline)?p.pipeline.at(-1)?.stage:'')||'new',contacts=p.contacts||[],domains=p.domains||[],websites=p.websites||[],evidence=p.evidence||p.evidence_timeline||[],notes=p.notes||[],review=p.review_status||p.review|| (st==='review'?'Needs review':st[0].toUpperCase()+st.slice(1));$('detailPanel').innerHTML=`<div class="detail-head"><div><p class="eyebrow">PROSPECT DETAIL</p><h3>${esc(p.name)}</h3><p class="detail-domain">${esc(p.website_domain||'no detected website')}</p></div><span class="status ${st}">${esc(review)}</span></div><div class="detail-score"><div><small>Fit score</small><b>${s}<small>/ 100</small></b></div><span class="score ${scoreClass(s)}">${esc(p.confidence||(s>=80?'High':s>=60?'Medium':'Low'))} confidence</span></div><section class="detail-block score-breakdown-panel" id="scoreBreakdownPanel" data-smoke="score-breakdown"><div class="detail-loading">Loading score breakdown…</div></section><div class="detail-block"><h4>Pipeline stage</h4><form id="pipelineForm" class="inline-form"><select name="stage" aria-label="Pipeline stage"><option value="new" ${stage==='new'?'selected':''}>New</option><option value="qualified" ${stage==='qualified'?'selected':''}>Qualified</option><option value="review" ${stage==='review'?'selected':''}>Review</option><option value="suppressed" ${stage==='suppressed'?'selected':''}>Suppressed</option></select><button class="button ghost compact" type="submit">Save stage</button></form><p id="pipelineMessage" class="form-message" role="status"></p></div><div class="detail-block"><h4>Contacts <span class="count">${contacts.length}</span></h4>${listItems(contacts,'No contacts added.','email')}<form id="contactForm" class="compact-form"><input name="name" placeholder="Contact name" aria-label="Contact name"><input name="email" type="email" placeholder="Email" aria-label="Contact email" required><button class="button ghost compact" type="submit">Add contact</button></form><p id="contactMessage" class="form-message" role="status"></p></div><section class="detail-block contact-extraction-panel" id="contactExtractionPanel" data-smoke="contact-extraction"><div class="detail-loading">Loading public contacts…</div></section><section class="detail-block website-scan-panel" id="websiteScanPanel" data-smoke="website-scan"><div class="detail-loading">Loading website scan…</div></section><section class="detail-block domain-intelligence" id="domainIntelligencePanel" data-smoke="domain-intelligence"><div class="detail-loading">Loading domain intelligence…</div></section><div class="detail-block"><h4>Domains & websites</h4>${listItems(domains,'No domains recorded.','domain')}${listItems(websites,'No websites recorded.','url')}</div><div class="detail-block"><h4>Evidence timeline</h4>${listItems(evidence,'No evidence events recorded.','description')}${factors.length?factors.map(x=>`<p class="evidence-line"><span>✓ ${esc(labelFactor(x))}</span><span class="confidence">${esc(p.confidence||'Medium')}</span></p>`).join(''):''}</div><div class="detail-block"><h4>Notes <span class="count">${notes.length}</span></h4>${listItems(notes,'No notes added.','body')}<form id="noteForm" class="compact-form"><textarea name="body" rows="2" placeholder="Add a review note…" required></textarea><button class="button ghost compact" type="submit">Add note</button></form><p id="noteMessage" class="form-message" role="status"></p></div><div class="detail-block"><h4>Review status</h4><p class="review-status">${esc(review)}</p>${st!=='suppressed'?'<button class="button primary compact" id="verifyBtn" type="button">Mark verified</button>':''}<p id="verifyMessage" class="form-message" role="status"></p></div>${blocked?`<button class="button disabled-action" disabled aria-disabled="true">Outreach unavailable</button><p class="disabled-reason">${st==='suppressed'?'Suppressed records cannot be contacted.':'Review this prospect before outreach is available.'}</p>`:''}`;renderScoreBreakdown(p);renderContactExtractionPanel(p);loadContactExtraction(p.id);renderWebsiteScanPanel(p);renderDomainPanel(p);renderDedupPanel();}
+  const aiItems = payload => { const runs=payloadItems(payload, ['items','runs','ai_runs']); return runs.flatMap(run => (run.suggestions||[]).length ? run.suggestions.map(item => ({...item,id:run.id,status:run.approval_state||run.status,provider:run.provider||run.model||'Unknown'})) : [{...run,id:run.id,status:run.status||run.approval_state,provider:run.provider||run.model||'Unknown'}]); };
+  const aiStatus = item => String(item?.status || item?.state || item?.suggestion_status || 'unknown').toLowerCase().replaceAll('_','-');
+  const aiLabel = value => ({'not-configured':'Not configured',unknown:'Unknown',error:'Error',suppressed:'Suppressed',pending:'Pending approval',approved:'Approved',rejected:'Rejected',generated:'Generated',ready:'Ready'})[String(value).toLowerCase()] || String(value || 'Unknown').replaceAll('-',' ').replace(/\b\w/g,c=>c.toUpperCase());
+  const aiCitations = item => item?.citations || item?.sources || item?.evidence || [];
+  const aiCitationText = citation => typeof citation === 'string' ? citation : citation?.title || citation?.label || citation?.source_url || citation?.url || citation?.quote || citation?.text || JSON.stringify(citation);
+  function renderAiSuggestion(item) {
+    const status=aiStatus(item), citations=aiCitations(item), pending=['pending','generated','ready'].includes(status), id=item?.id || item?.suggestion_id;
+    const body=item?.suggestion || item?.text || item?.content || item?.recommendation || item?.message || 'No suggestion was returned.';
+    const provider=item?.provider || item?.provider_name || item?.model || 'Unknown';
+    return `<article class="ai-suggestion ${status}" data-ai-suggestion-id="${esc(id || '')}"><div class="ai-suggestion-head"><div><span class="ai-status ${esc(status)}">${esc(aiLabel(status))}</span><span class="ai-provider">Provider: ${esc(provider)}</span></div>${pending && id ? `<div class="ai-actions"><button class="button ghost compact" type="button" data-ai-action="reject" data-ai-id="${esc(id)}">Reject</button><button class="button primary compact" type="button" data-ai-action="approve" data-ai-id="${esc(id)}">Approve</button></div>` : ''}</div><p class="ai-copy">${esc(body)}</p>${citations.length?`<div class="ai-citations"><h5>Evidence citations <span class="count">${citations.length}</span></h5><ol>${citations.slice(0,10).map(c=>`<li>${esc(aiCitationText(c))}${c?.url||c?.source_url?` <a href="${esc(c.url||c.source_url)}" target="_blank" rel="noreferrer">Open source</a>`:''}</li>`).join('')}</ol></div>`:'<p class="muted">No citations were returned; treat this as unknown.</p>'}</article>`;
+  }
+  function renderAiState(state, detail='') { const el=$('aiAssistanceState'); if(!el)return; const normalized=String(state||'unknown').toLowerCase().replaceAll('_','-'); const copy={
+    'not-configured':['AI assistance is not configured','Ask an administrator to configure an approved provider before generating suggestions.'],
+    unknown:['AI assistance is unknown','The provider did not establish a result. No suggestion is available for approval.'],
+    error:['Unable to load AI assistance',detail||'The provider returned an error. Try again later.'],
+    suppressed:['AI assistance suppressed','This prospect is suppressed. Suggestions are unavailable and no contact action is permitted.']
+  }[normalized] || ['No suggestion yet','Generate an evidence-grounded suggestion when an approved provider is available.']; el.innerHTML=`<div class="ai-state ${esc(normalized)}" role="${normalized==='error'?'alert':'status'}"><strong>${esc(copy[0])}</strong><p>${esc(copy[1])}</p></div>`; }
+  async function loadAiAssistance(id) { const panel=$('aiAssistancePanel'); if(!panel)return; const prospect=selectedDetail||prospects.find(item=>Number(item.id)===Number(id))||{}; if(statusOf(prospect)==='suppressed'){renderAiState('suppressed');return;} panel.querySelector('#aiAssistanceState').innerHTML='<div class="detail-loading" aria-live="polite">Loading AI assistance…</div>'; try { const payload=await jsonRequest(`/api/v1/ai-runs?business_id=${encodeURIComponent(id)}`); const items=aiItems(payload); const status=String(payload?.status||payload?.state||'').toLowerCase().replaceAll('_','-'); if(['not-configured','unknown','error','suppressed'].includes(status)){renderAiState(status,payload?.reason||payload?.message);return;} panel.querySelector('#aiAssistanceState').innerHTML=items.length?items.map(renderAiSuggestion).join(''): '<div class="ai-state" role="status"><strong>No suggestion yet</strong><p>Generate an evidence-grounded suggestion when an approved provider is available.</p></div>'; } catch(error) { if(error.message!=='unauthorized')renderAiState('error',error.message); } }
+  async function generateAiSuggestion() { if(!selectedId)return; const button=$('generateAiSuggestionBtn');if(!button)return;button.disabled=true;const state=$('aiAssistanceState');state.innerHTML='<div class="detail-loading" aria-live="polite">Generating evidence-grounded suggestion…</div>';try{await jsonRequest(`/api/v1/businesses/${encodeURIComponent(selectedId)}/ai/suggest`,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({evidence_grounded:true,autonomous_action:false})});await loadAiAssistance(selectedId);}catch(error){if(error.message!=='unauthorized')renderAiState(error.message.toLowerCase().includes('config')?'not-configured':'error',error.message);}finally{button.disabled=false;}}
+  async function aiAction(action,id) { if(!id)return; const label=action==='approve'?'approve':'reject'; if(!window.confirm(`Confirm ${label} of this suggestion? This only records a human decision; no outreach will be sent.`))return; const path=action==='approve'?`/api/v1/ai-runs/${encodeURIComponent(id)}/approve`:`/api/v1/ai-runs/${encodeURIComponent(id)}/reject`; try{await jsonRequest(path,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({human_approval:true,autonomous_action:false})});await loadAiAssistance(selectedId);}catch(error){if(error.message!=='unauthorized')renderAiState('error',error.message);}}
+  function renderDetail(p){const s=scoreFor(p),st=statusOf(p),f=freshness(p),factors=p.score_factors||p.factors||[],blocked=st==='review'||st==='suppressed',stage=p.pipeline_stage||p.pipeline?.stage||(Array.isArray(p.pipeline)?p.pipeline.at(-1)?.stage:'')||'new',contacts=p.contacts||[],domains=p.domains||[],websites=p.websites||[],evidence=p.evidence||p.evidence_timeline||[],notes=p.notes||[],review=p.review_status||p.review|| (st==='review'?'Needs review':st[0].toUpperCase()+st.slice(1));$('detailPanel').innerHTML=`<div class="detail-head"><div><p class="eyebrow">PROSPECT DETAIL</p><h3>${esc(p.name)}</h3><p class="detail-domain">${esc(p.website_domain||'no detected website')}</p></div><span class="status ${st}">${esc(review)}</span></div><div class="detail-score"><div><small>Fit score</small><b>${s}<small>/ 100</small></b></div><span class="score ${scoreClass(s)}">${esc(p.confidence||(s>=80?'High':s>=60?'Medium':'Low'))} confidence</span></div><section class="detail-block score-breakdown-panel" id="scoreBreakdownPanel" data-smoke="score-breakdown"><div class="detail-loading">Loading score breakdown…</div></section><div class="detail-block"><h4>Pipeline stage</h4><form id="pipelineForm" class="inline-form"><select name="stage" aria-label="Pipeline stage"><option value="new" ${stage==='new'?'selected':''}>New</option><option value="qualified" ${stage==='qualified'?'selected':''}>Qualified</option><option value="review" ${stage==='review'?'selected':''}>Review</option><option value="suppressed" ${stage==='suppressed'?'selected':''}>Suppressed</option></select><button class="button ghost compact" type="submit">Save stage</button></form><p id="pipelineMessage" class="form-message" role="status"></p></div><div class="detail-block"><h4>Contacts <span class="count">${contacts.length}</span></h4>${listItems(contacts,'No contacts added.','email')}<form id="contactForm" class="compact-form"><input name="name" placeholder="Contact name" aria-label="Contact name"><input name="email" type="email" placeholder="Email" aria-label="Contact email" required><button class="button ghost compact" type="submit">Add contact</button></form><p id="contactMessage" class="form-message" role="status"></p></div><section class="detail-block contact-extraction-panel" id="contactExtractionPanel" data-smoke="contact-extraction"><div class="detail-loading">Loading public contacts…</div></section><section class="detail-block website-scan-panel" id="websiteScanPanel" data-smoke="website-scan"><div class="detail-loading">Loading website scan…</div></section><section class="detail-block domain-intelligence" id="domainIntelligencePanel" data-smoke="domain-intelligence"><div class="detail-loading">Loading domain intelligence…</div></section><section class="detail-block ai-assistance-panel" id="aiAssistancePanel" data-smoke="ai-assistance"><div class="ai-panel-heading"><div><p class="eyebrow">AI ASSISTANCE</p><h4>Evidence-grounded suggestion</h4></div><button class="button primary compact" id="generateAiSuggestionBtn" type="button">Generate suggestion</button></div><p class="ai-safety">AI suggestions summarize workspace evidence and citations only. Review and approve explicitly; No autonomous action or outreach is taken.</p><div id="aiAssistanceState" aria-live="polite"><div class="detail-loading">Loading AI assistance…</div></div></section><div class="detail-block"><h4>Domains & websites</h4>${listItems(domains,'No domains recorded.','domain')}${listItems(websites,'No websites recorded.','url')}</div><div class="detail-block"><h4>Evidence timeline</h4>${listItems(evidence,'No evidence events recorded.','description')}${factors.length?factors.map(x=>`<p class="evidence-line"><span>✓ ${esc(labelFactor(x))}</span><span class="confidence">${esc(p.confidence||'Medium')}</span></p>`).join(''):''}</div><div class="detail-block"><h4>Notes <span class="count">${notes.length}</span></h4>${listItems(notes,'No notes added.','body')}<form id="noteForm" class="compact-form"><textarea name="body" rows="2" placeholder="Add a review note…" required></textarea><button class="button ghost compact" type="submit">Add note</button></form><p id="noteMessage" class="form-message" role="status"></p></div><div class="detail-block"><h4>Review status</h4><p class="review-status">${esc(review)}</p>${st!=='suppressed'?'<button class="button primary compact" id="verifyBtn" type="button">Mark verified</button>':''}<p id="verifyMessage" class="form-message" role="status"></p></div>${blocked?`<button class="button disabled-action" disabled aria-disabled="true">Outreach unavailable</button><p class="disabled-reason">${st==='suppressed'?'Suppressed records cannot be contacted.':'Review this prospect before outreach is available.'}</p>`:''}`;renderScoreBreakdown(p);renderContactExtractionPanel(p);loadContactExtraction(p.id);renderWebsiteScanPanel(p);renderDomainPanel(p);loadAiAssistance(p.id);renderDedupPanel();}
   let mergeSource = null, mergeTarget = null, mergeBusy = false;
   const payloadItems = (payload, keys) => { for (const key of keys) if (Array.isArray(payload?.[key])) return payload[key]; return Array.isArray(payload) ? payload : []; };
   const suggestionId = item => item.target_id ?? item.business_id ?? item.prospect_id ?? item.id;
@@ -231,7 +251,7 @@
   async function logout(){try{await fetch(endpoint('/api/v1/auth/logout'),{method:'POST',credentials:'include'});}finally{showLogin('You have been signed out.');$('loginForm').reset();}}
   async function bootstrap(){try{const res=await fetch(endpoint('/api/v1/auth/me'),{credentials:'include'});if(res.status===401){showLogin();return;}if(!res.ok)throw new Error('Could not verify session.');const user=await res.json();showDashboard(user.user||user);await loadData();await loadJobs();await loadSources();await loadScorePanels();await loadSavedFilters();await loadReviewQueue();await loadCrmPipeline();await loadReports();await loadSuppressions();}catch(e){if(e.message!=='unauthorized')showLogin('Unable to connect to the workspace. Try again.');}}
   document.addEventListener('submit',e=>{if(e.target.id==='contactForm')saveContact(e.target);if(e.target.id==='noteForm')saveNote(e.target);if(e.target.id==='pipelineForm')saveStage(e.target);});
-  document.addEventListener('click',e=>{if(e.target.id==='verifyBtn')verify();if(e.target.id==='recalculateScoreBtn')recalculateScore();const scoreEdit=e.target.closest?.('[data-score-edit]');if(scoreEdit)updateScoreRule(scoreEdit.dataset.scoreEdit,scoreEdit.dataset.scorePoints);if(e.target.id==='extractContactsBtn'&&selectedId)loadContactExtraction(selectedId,{extract:true});if(e.target.id==='refreshContactExtractionBtn'&&selectedId)loadContactExtraction(selectedId,{extract:true});if(e.target.id==='retryContactExtractionBtn'&&selectedId)loadContactExtraction(selectedId);if(e.target.id==='scanWebsiteBtn'&&selectedId)loadWebsiteScan(selectedId,{scan:true});if(e.target.id==='refreshWebsiteScanBtn'&&selectedId)loadWebsiteScan(selectedId);if(e.target.id==='retryWebsiteScanBtn'&&selectedId)loadWebsiteScan(selectedId);if(e.target.id==='runDomainCheckBtn')runDomainCheck();if(e.target.id==='retryDomainBtn'&&selectedId)loadDomainIntelligence(selectedId);const availability=e.target.closest?.('[data-domain-availability]');if(availability)checkDomainAvailability(availability.dataset.domain,availability);if(e.target.id==='retryDetailBtn'&&selectedId)loadDetail(selectedId);if(e.target.id==='retryDedupBtn'&&selectedId)loadMatchSuggestions(selectedId);if(e.target.id==='retryHistoryBtn'&&selectedId)loadMergeHistory(selectedId);if(e.target.id==='cancelMergeBtn'||e.target.id==='cancelMergeBtnSecondary')closeMergeDialog();if(e.target.id==='confirmMergeBtn')confirmMerge();const mergeButton=e.target.closest?.('[data-merge-target]');if(mergeButton)openMergeDialog(mergeButton.dataset.mergeTarget,mergeButton.dataset.mergeTargetName);const reverseButton=e.target.closest?.('[data-reverse-merge]');if(reverseButton)reverseMerge(reverseButton.dataset.reverseMerge);if(e.target.id==='retryJobDetailBtn'&&selectedJobId)loadJobDetail(selectedJobId);if(e.target.id==='cancelJobBtn')jobAction('cancel');if(e.target.id==='retryJobBtn')jobAction('retry');const row=e.target.closest?.('[data-job-id]');if(row)loadJobDetail(row.dataset.jobId);});
+  document.addEventListener('click',e=>{if(e.target.id==='verifyBtn')verify();if(e.target.id==='recalculateScoreBtn')recalculateScore();if(e.target.id==='generateAiSuggestionBtn')generateAiSuggestion();const aiButton=e.target.closest?.('[data-ai-action]');if(aiButton)aiAction(aiButton.dataset.aiAction,aiButton.dataset.aiId);const scoreEdit=e.target.closest?.('[data-score-edit]');if(scoreEdit)updateScoreRule(scoreEdit.dataset.scoreEdit,scoreEdit.dataset.scorePoints);if(e.target.id==='extractContactsBtn'&&selectedId)loadContactExtraction(selectedId,{extract:true});if(e.target.id==='refreshContactExtractionBtn'&&selectedId)loadContactExtraction(selectedId,{extract:true});if(e.target.id==='retryContactExtractionBtn'&&selectedId)loadContactExtraction(selectedId);if(e.target.id==='scanWebsiteBtn'&&selectedId)loadWebsiteScan(selectedId,{scan:true});if(e.target.id==='refreshWebsiteScanBtn'&&selectedId)loadWebsiteScan(selectedId);if(e.target.id==='retryWebsiteScanBtn'&&selectedId)loadWebsiteScan(selectedId);if(e.target.id==='runDomainCheckBtn')runDomainCheck();if(e.target.id==='retryDomainBtn'&&selectedId)loadDomainIntelligence(selectedId);const availability=e.target.closest?.('[data-domain-availability]');if(availability)checkDomainAvailability(availability.dataset.domain,availability);if(e.target.id==='retryDetailBtn'&&selectedId)loadDetail(selectedId);if(e.target.id==='retryDedupBtn'&&selectedId)loadMatchSuggestions(selectedId);if(e.target.id==='retryHistoryBtn'&&selectedId)loadMergeHistory(selectedId);if(e.target.id==='cancelMergeBtn'||e.target.id==='cancelMergeBtnSecondary')closeMergeDialog();if(e.target.id==='confirmMergeBtn')confirmMerge();const mergeButton=e.target.closest?.('[data-merge-target]');if(mergeButton)openMergeDialog(mergeButton.dataset.mergeTarget,mergeButton.dataset.mergeTargetName);const reverseButton=e.target.closest?.('[data-reverse-merge]');if(reverseButton)reverseMerge(reverseButton.dataset.reverseMerge);if(e.target.id==='retryJobDetailBtn'&&selectedJobId)loadJobDetail(selectedJobId);if(e.target.id==='cancelJobBtn')jobAction('cancel');if(e.target.id==='retryJobBtn')jobAction('retry');const row=e.target.closest?.('[data-job-id]');if(row)loadJobDetail(row.dataset.jobId);});
   $('loginForm').addEventListener('submit',login);$('logoutBtn').addEventListener('click',logout);$('searchInput').addEventListener('input',()=>{page=1;renderRows();});['scoreFilter','statusFilter','websiteClassFilter','pipelineFilter'].forEach(id=>$(id).addEventListener('change',()=>{page=1;loadData();}));$('pageSize').addEventListener('change',e=>{pageSize=Number(e.target.value);page=1;loadData();});$('nextPageBtn').addEventListener('click',()=>{if(hasNextPage){page+=1;loadData();}});$('refreshBtn').addEventListener('click',loadData);$('jobsRefreshBtn').addEventListener('click',()=>loadJobs());$('startDemoJobBtn').addEventListener('click',startDemoJob);$('sourcesRefreshBtn').addEventListener('click',loadSources);$('sourceForm').addEventListener('submit',saveSource);$('sourceType').addEventListener('change',e=>{$('sourceCsvField').hidden=e.target.value!=='csv';});$('discoveryForm').addEventListener('submit',e=>{e.preventDefault();runDiscovery(true);});$('discoveryRunBtn').addEventListener('click',()=>runDiscovery(false));$('sourcesList').addEventListener('click',e=>{const button=e.target.closest?.('[data-source-action]');if(button)sourceAction(button.dataset.sourceId,button.dataset.sourceAction);});$('addForm').addEventListener('submit',addProspect);$('csvInput').addEventListener('change',e=>{const file=e.target.files[0];if(file){const reader=new FileReader();reader.onload=()=>renderCsv(parseCsv(reader.result));reader.readAsText(file);}});$('menuBtn').addEventListener('click',()=>document.querySelector('.sidebar').classList.toggle('open'));document.querySelectorAll('[data-scroll]').forEach(b=>b.addEventListener('click',()=>document.querySelector(b.dataset.scroll)?.scrollIntoView()));
   $('savedFilterForm').addEventListener('submit',saveCurrentFilters);$('savedFilterSelect').addEventListener('change',e=>{ $('deleteSavedFilterBtn').disabled=!e.target.value;if(e.target.value)loadSavedFilter(e.target.value);});$('deleteSavedFilterBtn').addEventListener('click',deleteSavedFilter);$('reviewQueueState').addEventListener('change',e=>{const input=e.target.closest?.('[data-review-id]');if(input){if(input.checked)selectedReviewIds.add(String(input.dataset.reviewId));else selectedReviewIds.delete(String(input.dataset.reviewId));updateBulkState();}});$('selectAllReview').addEventListener('change',e=>{reviewQueue.forEach(p=>e.target.checked?selectedReviewIds.add(String(p.id)):selectedReviewIds.delete(String(p.id)));renderReviewQueue({items:reviewQueue,count:$('reviewQueueCount').textContent});});$('bulkVerifyBtn').addEventListener('click',()=>bulkReview('verify'));$('bulkRejectBtn').addEventListener('click',()=>bulkReview('reject'));$('reviewQueueState').addEventListener('click',e=>{if(e.target.id==='retryReviewQueueBtn')loadReviewQueue();});document.querySelectorAll('[data-dashboard-filter]').forEach(card=>card.addEventListener('click',()=>{const kind=card.dataset.dashboardFilter;if(kind==='review'||kind==='suppressed')applyFilters({status:kind});else if(kind==='high')applyFilters({score:'high'});else if(kind==='fresh')applyFilters({});else applyFilters({status:'all',score:'all'});}));
   $('interactionForm').addEventListener('submit',saveInteraction);$('suppressionForm').addEventListener('submit',addSuppression);$('crmRefreshBtn').addEventListener('click',()=>{loadCrmPipeline();loadInteractions(selectedId);});$('reportsRefreshBtn').addEventListener('click',loadReports);$('suppressionRefreshBtn').addEventListener('click',loadSuppressions);$('pipelineViewToggle').addEventListener('click',()=>{crmListMode=!crmListMode;$('pipelineViewToggle').textContent=crmListMode?'▦ Board view':'☷ List view';$('pipelineViewToggle').setAttribute('aria-pressed',String(crmListMode));renderPipeline();});$('pipelineBoard').addEventListener('click',e=>{const selectButton=e.target.closest?.('[data-crm-select]');if(selectButton){selectedId=Number(selectButton.dataset.crmSelect);selectProspect(selectedId);loadInteractions(selectedId);$('crmActivity').scrollIntoView({behavior:'smooth',block:'start'});}const stageButton=e.target.closest?.('[data-crm-save-stage]');if(stageButton)saveCrmStage(stageButton.dataset.crmSaveStage);if(e.target.id==='retryCrmBtn')loadCrmPipeline();if(e.target.id==='retryInteractionsBtn'&&selectedId)loadInteractions(selectedId);});$('suppressionState').addEventListener('change',e=>{const input=e.target.closest?.('[data-suppression-id]');if(input){if(input.checked)selectedSuppressionIds.add(String(input.dataset.suppressionId));else selectedSuppressionIds.delete(String(input.dataset.suppressionId));updateSuppressionSelection();}});$('suppressionState').addEventListener('click',e=>{const button=e.target.closest?.('[data-remove-suppression]');if(button)removeSuppression(button.dataset.removeSuppression);if(e.target.id==='retrySuppressionsBtn')loadSuppressions();});$('selectAllSuppressions').addEventListener('change',e=>{suppressions.forEach(item=>e.target.checked?selectedSuppressionIds.add(String(item.id)):selectedSuppressionIds.delete(String(item.id)));renderSuppressions();});$('bulkReviewSuppressionsBtn').addEventListener('click',bulkReviewSuppressions);

apps/web/smoke-test.html

@@ -58,5 +58,8 @@ frame.onload=async()=>{const d=frame.contentDocument;const js=await fetch('app.j
  ,['Phase 12 reports panels and API states',()=>!!d.querySelector('[data-smoke="crm-reports"]')&&['pipelineReport','outcomesReport','activityReport'].every(id=>!!d.querySelector('#'+id))&&['/api/v1/reports/pipeline','/api/v1/reports/outcomes','/api/v1/reports/activity'].every(path=>js.includes(path))&&js.includes('No')&&js.includes('Unable to load')]
  ,['Phase 12 suppression center controls and safety',()=>!!d.querySelector('[data-smoke="suppression-center"]')&&!!d.querySelector('#suppressionForm')&&!!d.querySelector('#bulkReviewSuppressionsBtn')&&js.includes('/api/v1/suppressions')&&js.includes('data-remove-suppression')&&js.includes('Suppression always wins')&&js.includes('do-not-contact')]
  ,['Phase 12 CRM responsive styles and authenticated requests',()=>js.includes('credentials:\'include\'')&&js.includes('crm-two-col')&&js.includes('reports-grid')&&js.includes('pipeline-board')&&js.includes('@media')]
+ ,['Phase 13 AI assistance panel and safety contract',()=>!!d.querySelector('[data-smoke="ai-assistance"]')&&!!d.querySelector('#generateAiSuggestionBtn')&&js.includes('/api/v1/ai-runs')&&js.includes('/api/v1/businesses/${encodeURIComponent(selectedId)}/ai/suggest')&&js.includes('Evidence-grounded suggestion')&&js.includes('No autonomous action')&&js.includes('citations')]
+ ,['Phase 13 AI states, provider, and human decisions',()=>['not-configured','Unknown','Error','Suppressed','Provider:','Pending approval','Approve','Reject','human_approval','no outreach will be sent'].every(x=>js.includes(x))&&js.includes('Loading AI assistance')]
+ ,['Phase 13 AI authenticated requests and responsive styles',()=>js.includes('/api/v1/ai-runs')&&js.includes('/ai/suggest')&&js.includes('autonomous_action:false')&&js.includes('ai-assistance-panel')&&js.includes('@media')]
 ];let passed=0;document.querySelector('#checks').innerHTML=checks.map(([name,test])=>{const ok=test();if(ok)passed++;return `<li class="${ok?'pass':'fail'}">${ok?'PASS':'FAIL'} — ${name}</li>`}).join('');document.querySelector('#summary').textContent=`${passed}/${checks.length} checks passed`;};
 </script>

apps/web/styles.css

@@ -7,6 +7,8 @@
 .website-scan-actions .button{min-height:32px}.contact-extraction-heading{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.contact-extraction-heading h4{margin:.1rem 0}.contact-extraction-actions{display:flex;gap:7px;flex-wrap:wrap}.contact-extraction-safety{border:1px solid #dcd8ff;border-radius:8px;background:var(--violet-soft);color:#5145a7;padding:9px 11px;font-size:12px;margin:10px 0}.extracted-contact-list{display:grid;gap:9px}.extracted-contact{border:1px solid var(--line);border-radius:9px;padding:11px;background:#fff}.extracted-contact-head{display:flex;justify-content:space-between;gap:10px;align-items:start}.extracted-contact-head strong{overflow-wrap:anywhere}.contact-confidence{color:var(--violet);font-size:11px;font-weight:700;white-space:nowrap}.extracted-contact-facts{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:7px;margin:10px 0 0}.extracted-contact-facts div{border:1px solid var(--line);border-radius:7px;padding:7px}.extracted-contact-facts dt{font-size:10px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted)}.extracted-contact-facts dd{margin:3px 0 0;font-size:12px;overflow-wrap:anywhere}.extracted-contact-facts a{color:var(--violet)}.contact-source{grid-column:1 / -1}.suppression-status{color:var(--green)}.contact-extraction-empty{padding:18px 4px}.contact-extraction-empty strong{color:var(--muted)}@media(max-width:700px){.website-scan-heading{flex-direction:column}.website-scan-actions{width:100%}.website-scan-actions .button{flex:1}.website-scan-grid{grid-template-columns:1fr}.signal-list{grid-template-columns:repeat(2,minmax(0,1fr))}.contact-extraction-heading{flex-direction:column}.contact-extraction-actions{width:100%}.contact-extraction-actions .button{flex:1}.extracted-contact-facts{grid-template-columns:repeat(2,minmax(0,1fr))}.contact-source{grid-column:1 / -1}}
 .metric-link{color:inherit;text-decoration:none}.metric-link:hover{border-color:#c9c3ff;transform:translateY(-1px)}.saved-view-controls{display:grid;grid-template-columns:minmax(220px,1fr) 180px auto;gap:8px;align-items:center;padding:12px 0;border-top:1px solid var(--line)}.saved-view-controls .form-message{grid-column:1 / -1;margin:0}.saved-view-controls input,.saved-view-controls select{border:1px solid var(--line);border-radius:7px;padding:8px;font:inherit;min-width:0}.review-queue{margin:4px 0 14px;padding:14px;background:#fbfbff;border:1px solid var(--line);border-radius:10px}.queue-heading{display:flex;justify-content:space-between;gap:12px;align-items:flex-start}.queue-heading h3{margin:.1rem 0}.queue-state{margin-top:8px}.queue-list{display:grid;gap:6px;max-height:300px;overflow:auto}.queue-row{display:flex;align-items:center;gap:10px;padding:8px;border:1px solid var(--line);border-radius:7px;background:#fff;cursor:pointer}.queue-row input{flex:0 0 auto}.queue-row>span:nth-child(2){display:flex;flex-direction:column;min-width:0;flex:1}.queue-row small{color:var(--muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.queue-boundary{font-size:11px;color:var(--muted);margin:8px 0 0}.bulk-actions{display:flex;align-items:center;gap:8px;flex-wrap:wrap;margin-top:10px;padding-top:10px;border-top:1px solid var(--line)}.bulk-actions .checkbox-label{margin:0}.explorer-state{min-height:0;color:var(--green);font-size:12px;padding:4px 0}.explorer-state.error{color:var(--red)}
 .status.review{background:var(--amber-soft);color:var(--amber)}
+.ai-assistance-panel{background:#fbfbff;border:1px solid #ddd9ff;border-radius:10px;padding:15px}.ai-panel-heading{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.ai-panel-heading h4{margin:.1rem 0}.ai-safety{border:1px solid #dcd8ff;border-radius:8px;background:var(--violet-soft);color:#5145a7;padding:9px 11px;font-size:12px;margin:10px 0}.ai-suggestion{border:1px solid var(--line);border-radius:9px;background:#fff;padding:12px}.ai-suggestion-head{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.ai-suggestion-head>div:first-child{display:flex;align-items:center;gap:8px;flex-wrap:wrap}.ai-status{border-radius:999px;padding:4px 8px;background:var(--amber-soft);color:var(--amber);font-size:11px;font-weight:750}.ai-status.approved{background:var(--green-soft);color:var(--green)}.ai-status.rejected,.ai-status.error,.ai-status.suppressed{background:var(--red-soft);color:var(--red)}.ai-provider{color:var(--muted);font-size:11px}.ai-actions{display:flex;gap:7px;flex-wrap:wrap}.ai-copy{white-space:pre-wrap;margin:12px 0}.ai-citations{border-top:1px solid var(--line);padding-top:9px}.ai-citations h5{margin:0}.ai-citations ol{margin:7px 0 0;padding-left:1.25rem}.ai-citations li{margin:5px 0;font-size:12px}.ai-citations a{color:var(--violet);margin-left:4px}.ai-state{padding:14px 4px;color:var(--muted)}.ai-state strong{color:var(--ink)}.ai-state.error strong{color:var(--red)}.ai-state.suppressed strong{color:var(--red)}
+@media(max-width:700px){.ai-panel-heading,.ai-suggestion-head{flex-direction:column}.ai-panel-heading .button,.ai-actions{width:100%}.ai-actions .button{flex:1}}
 .crm-section{margin-top:28px;scroll-margin-top:24px}.crm-header{display:flex;align-items:flex-start;justify-content:space-between;gap:18px}.crm-header h2{margin:.15rem 0 .25rem}.crm-actions{display:flex;gap:8px;flex-wrap:wrap}.crm-safety,.suppression-warning{margin:14px 0;padding:12px 15px;border:1px solid #dcd8ff;border-radius:9px;background:var(--violet-soft);color:#5145a7}.suppression-warning{border-color:#f1d7a5;background:var(--amber-soft);color:#76500d}.crm-message{min-height:22px;color:var(--green);padding:6px 2px}.crm-message.error{color:var(--red)}.pipeline-board{display:grid;grid-template-columns:repeat(4,minmax(180px,1fr));gap:12px;overflow-x:auto;align-items:start}.pipeline-column{background:#f1f2f8;border:1px solid var(--line);border-radius:10px;padding:10px;min-height:180px}.pipeline-column-head{display:flex;justify-content:space-between;align-items:center;margin-bottom:8px}.pipeline-column-head h3{margin:0;font-size:13px}.pipeline-card{background:#fff;border:1px solid var(--line);border-radius:9px;padding:10px;margin:8px 0;box-shadow:var(--shadow)}.pipeline-card.is-suppressed{border-color:#e9b8bd;background:#fffafa}.pipeline-card-link{display:grid;gap:3px;width:100%;border:0;background:none;text-align:left;color:inherit;padding:0;cursor:pointer}.pipeline-card-link small,.pipeline-card-link .score{font-size:11px;color:var(--muted)}.pipeline-card-actions{display:flex;gap:6px;margin-top:9px}.pipeline-card-actions select{min-width:0;flex:1;border:1px solid var(--line);border-radius:6px;padding:6px;font:inherit;font-size:12px}.pipeline-list-view{display:block}.pipeline-list{display:grid;grid-template-columns:repeat(auto-fit,minmax(260px,1fr));gap:10px}.crm-column-empty,.crm-empty{color:var(--muted);font-size:12px;text-align:center;padding:20px 8px}.suppression-inline,.review-inline{font-size:11px;color:var(--red);margin:8px 0 0}.review-inline{color:var(--amber)}.crm-two-col{display:grid;grid-template-columns:minmax(0,1.1fr) minmax(300px,.9fr);gap:18px}.crm-form{display:grid;gap:10px}.crm-form label{display:grid;gap:5px;font-size:12px;font-weight:650}.crm-form input,.crm-form select,.crm-form textarea{border:1px solid var(--line);border-radius:7px;padding:9px;font:inherit;font-weight:400}.crm-form textarea{resize:vertical}.crm-timeline{list-style:none;padding:0;margin:12px 0}.crm-timeline li{display:flex;gap:10px;border-top:1px solid var(--line);padding:12px 0}.crm-timeline li>div{display:grid;gap:4px;min-width:0}.crm-timeline p{margin:0;color:var(--muted)}.crm-timeline small{color:var(--muted);font-size:11px}.timeline-dot{width:9px;height:9px;flex:0 0 9px;margin-top:6px;border-radius:50%;background:var(--violet);box-shadow:0 0 0 4px var(--violet-soft)}.outcome-chip{font-size:11px;color:var(--violet);background:var(--violet-soft);border-radius:999px;padding:2px 7px;width:max-content}.reports-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:18px}.report-rows{display:grid;gap:8px}.report-rows div{display:flex;justify-content:space-between;gap:10px;border-top:1px solid var(--line);padding:9px 0}.report-rows strong{color:var(--violet)}.report-note{font-size:11px;color:var(--muted)}.suppression-bulk-actions{display:flex;gap:8px;align-items:center;flex-wrap:wrap}.suppression-bulk-actions .checkbox-label{margin:0}.suppression-list{display:grid}.suppression-row{display:flex;justify-content:space-between;gap:10px;align-items:center;border-top:1px solid var(--line);padding:11px 0}.suppression-row .checkbox-label{margin:0;flex:1}.suppression-row .checkbox-label span{display:grid;gap:2px;min-width:0}.suppression-row small{color:var(--muted);overflow-wrap:anywhere}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}@media(max-width:1000px){.pipeline-board{grid-template-columns:repeat(4,minmax(220px,1fr))}.reports-grid{grid-template-columns:1fr 1fr}}@media(max-width:700px){.crm-header{flex-direction:column}.crm-actions,.crm-actions .button{width:100%}.crm-actions .button{flex:1}.crm-two-col,.reports-grid{grid-template-columns:1fr}.pipeline-board{grid-template-columns:repeat(4,minmax(235px,1fr))}.pipeline-list{grid-template-columns:1fr}.suppression-row{align-items:flex-start}.suppression-bulk-actions{width:100%}}
 @media(max-width:700px){.saved-view-controls{grid-template-columns:1fr}.saved-view-controls .inline-form{display:flex}.saved-view-controls .inline-form input{flex:1}.queue-row{align-items:flex-start}.bulk-actions .button{flex:1}.metric-link{min-width:0}}
 .score-overview{margin-top:18px}.score-distribution-panel{min-width:0}.score-rules-section{margin-top:18px;scroll-margin-top:24px}.score-breakdown-panel{background:#fbfbff;border-radius:10px;padding:15px}.score-panel-heading{display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.score-panel-heading h4{margin:.1rem 0}.score-breakdown-summary{display:grid;grid-template-columns:1.4fr 1fr 1fr;gap:8px;margin:12px 0}.score-breakdown-summary>div,.score-meta div{border:1px solid var(--line);border-radius:8px;background:#fff;padding:10px}.score-breakdown-summary small,.score-breakdown-summary b{display:block}.score-breakdown-summary small,.score-meta dt{color:var(--muted);font-size:10px;text-transform:uppercase;letter-spacing:.05em}.score-breakdown-summary b{margin-top:4px}.score-total{display:block;font-size:28px;line-height:1.1;margin-top:3px}.score-total small{display:inline;font-size:12px;margin-left:3px}.score-meta{display:grid;grid-template-columns:1fr 1fr;gap:8px;margin:0}.score-meta dd{margin:3px 0 0}.score-rules-explanation{margin-top:13px}.score-rules-explanation h5{margin:0 0 7px}.score-rule-row{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:2px 8px;border-top:1px solid var(--line);padding:9px 0}.score-rule-row span{font-weight:650}.score-rule-row strong{color:var(--violet);font-size:12px}.score-rule-row small{grid-column:1 / -1;color:var(--muted)}.score-safety,.score-config-note{border:1px solid #dcd8ff;border-radius:8px;background:var(--violet-soft);color:#5145a7;padding:9px 11px;font-size:12px;margin:12px 0 0}.score-rule-table{border-top:1px solid var(--line);margin-top:12px}.score-config-row{display:grid;grid-template-columns:minmax(140px,1.4fr) .8fr .7fr .7fr auto;gap:10px;align-items:center;padding:11px 0;border-bottom:1px solid var(--line)}.score-config-row span{font-size:12px}.score-config-row span:nth-child(2){color:var(--green);font-weight:700}.score-config-row small{color:var(--muted)}.score-config-row button:disabled{opacity:.7;cursor:not-allowed}.score-distribution-list{display:grid;gap:10px;margin-top:12px}.distribution-row{display:grid;grid-template-columns:minmax(100px,1fr) 42px minmax(100px,2fr);gap:10px;align-items:center}.distribution-row strong{text-align:right}.distribution-track{height:8px;border-radius:99px;background:var(--line);overflow:hidden}.distribution-track i{display:block;height:100%;background:var(--violet);border-radius:inherit}@media(max-width:700px){.score-breakdown-summary{grid-template-columns:1fr 1fr}.score-breakdown-summary>div:first-child{grid-column:1 / -1}.score-config-row{grid-template-columns:1fr 1fr}.score-config-row strong{grid-column:1 / -1}.score-config-row button{justify-self:start}.distribution-row{grid-template-columns:minmax(95px,1fr) 34px minmax(80px,1fr)}}

docs/OPERATIONS.md

@@ -172,6 +172,18 @@ Do not run `docker compose down -v` on a data-bearing environment: it removes th
 
 Before production, complete a migration from SQLite to a reviewed production database, add schema/indexes for jobs/idempotency/events, domain observations, and scan history/cache, implement transactional sequence assignment and tenant authorization, and prove cancellation/retry/lease recovery under concurrency. Add durable queue/worker and scanner-isolation operations, bounded DNS/PSL/website processing, TTL/freshness-aware cache invalidation, SSRF/DNS-rebinding/redirect-chain tests, hard size/time/crawl budgets, uncertainty and association-review workflows, and a separately approved availability provider. Add metrics and alerts for queue age, failures, retries, cancellation latency, event lag/gaps, DNS/scanner status/error rates, cache freshness, blocked destinations, crawl-budget exhaustion, provider rate limits/circuit state, and SSE connections; define backup/restore and event-retention drills. Redis, Celery, Postgres, schedulers, discovery adapters, and production scanners are possible future components—not implicit Compose dependencies. No automated discovery, domain acquisition, ownership assertion, or outreach may be inferred from the scaling path.
 
+## Phase 13 optional AI assistance operations
+
+Keep AI disabled unless the provider registry, tenant scope, purpose, data class, redaction policy, retention class, rate/token/cost budgets, approval expiry, and operational enablement have been reviewed and recorded. The current Compose stack has no configured provider; do not enable one by adding an arbitrary URL or secret. Store credentials only in the deployment secret manager. A fallback must be pre-approved for the same purpose and input class and must inherit the primary provider's tenant, citation, redaction, retention, and authority constraints.
+
+Before an AI request, verify the authenticated tenant and permission, active provider/policy version, suppression state, and bounded evidence selection. Minimize and redact inputs; exclude secrets, credentials, session data, raw page bodies, unrelated personal data, and unnecessary full contact values. Monitor request/response size, latency, provider health, fallback rate, quota/rate/cost usage, redaction failures, policy/approval denials, and `unknown`/`unavailable`/partial outcomes. Provider failure, stale or conflicting evidence, prompt-injection indicators, or hash/citation mismatch is a safe non-result—not a retry reason and never permission to present invented facts.
+
+Review every suggestion as **AI draft — human review required**. Confirm citations resolve within the same tenant, the evidence hash still matches the cited snapshot, observed times/freshness are acceptable, suppression remains clear, and the provider/policy approval is current. An approval must be explicit, reasoned, audited, and read back; changed evidence or policy invalidates the proposal. Rejection, expiry, failed approval, and fallback events must remain auditable. Never report generation or approval request acceptance as persistence or completion.
+
+The operational path must not alter pipeline/interactions/outcomes as if communication occurred, send outreach, probe SMTP, create campaigns, schedule follow-ups, merge records, acquire domains, or otherwise act autonomously in CRM. Suppressed/do-not-contact records remain visible for safety review and blocked from contact-related actions. Retain only the approved minimum AI lineage (redacted fingerprint, output, citations/hash, versions, approval and audit metadata); apply deletion/legal-hold rules to prompts, outputs, evidence snapshots, caches, and logs and verify deletion without removing required suppression/audit history.
+
+On suspected provider misuse, data leakage, hallucinated/invented facts, prompt injection, cross-tenant exposure, unexpected outbound traffic, cost runaway, or suppression bypass: disable the AI capability/kill switch, stop affected jobs, preserve redacted evidence and audit metadata, revoke/rotate provider credentials, determine affected tenants and retention obligations, and require security/product/legal review before re-enabling. Production remains blocked until provider contracts/DPA, tenant-isolation, redaction, citation/hash, approval/rollback, evaluation, retention/deletion, monitoring, and recovery tests pass.
+
 ## Incident checklist
 
 1. Record time, affected service, image/config revision, and observed health state.

docs/SECURITY.md

@@ -136,4 +136,16 @@ Treat manually supplied business information, notes, and source references as po
 
 Pin or review base-image and dependency updates, scan images before release, use least-privilege GitHub tokens, and avoid printing environment values. CI may validate Compose with empty optional bootstrap variables and call unauthenticated health checks; it is not a substitute for authorization/tenant-isolation tests, provenance policy review, Argon2id parameter review, MFA testing, or a security assessment.
 
+## Phase 13 optional AI assistance security controls
+
+- AI is an optional, deny-by-default review aid. It may summarize or classify tenant-held evidence, but it is not an authority for facts, identity, ownership, deliverability, score/eligibility, CRM state, or contact permission. No AI path may send messages, probe SMTP, create campaigns, schedule follow-ups, merge records, acquire domains, or take autonomous CRM/outreach actions.
+- Provider configuration must use a server-side allowlist. Each primary or fallback provider requires an approved purpose/capability, model/version, tenant and data-class scope, processing/retention terms, region/egress policy, timeout/token/rate/cost budgets, health/circuit state, approval owner/expiry, and explicit operational enablement. Fallback may only preserve the same purpose, scope, redaction policy, evidence set, and authority; it must not silently broaden processing. Missing/expired approval, outage, quota, timeout, or policy failure fails closed to `unknown`/`unavailable`.
+- Keep provider credentials in a secret manager; never expose them to the browser or store them in prompts, responses, Compose, source, committed `.env`, logs, audit details, or error messages. Disable provider access immediately on suspected misuse or data leakage.
+- Minimize before transmission: send only bounded fields/evidence needed for the approved task; redact credentials, tokens, session data, secrets, raw page bodies, unnecessary personal/contact data, and unrelated tenant data. Enforce input/output size limits and log only a redacted request/policy fingerprint. Treat retrieved evidence and model output as untrusted input, including prompt-injection instructions; never invent facts or present invented facts as supported claims.
+- Every suggestion must cite tenant-scoped evidence IDs/source references and bind to a cryptographic evidence hash of the exact evidence snapshot, with observed time, uncertainty/conflict state, provider/model/version, and policy version. Hashing proves lineage to a snapshot, not source truth. Verify citations and hash equality server-side; a changed, missing, suppressed, stale, blocked, or conflicting input invalidates approval and requires re-review.
+- Approval is an explicit authorized human action, never an AI or retry side effect. Re-check tenant scope, suppression, permissions, evidence freshness/hash, provider approval, and policy version at approval time. Record proposal, citations/hash, actor, reason, before/after value, version, timestamp, rejection/expiry, and correlation/idempotency data in an append-oriented audit trail. Approval cannot create a verified fact or outreach authorization.
+- AI prompts/fingerprints, outputs, evidence snapshots/citations, approvals, caches, and audit events need separate retention classes, redaction rules, deletion/legal-hold semantics, tenant-keyed access, and readback/deletion verification. Retain only the minimum lineage needed to explain an approved result; do not retain full prompts or source content when a hash/reference suffices.
+- Suppression/do-not-contact is evaluated before AI input, generation, persistence, response, export, cache, queueing, and approval. Suppressed records remain visible as safety state, are never silently deleted, and cannot be revived by confidence, fallback, human approval, or later pipeline/outcome data.
+- Production requires provider/DPA/legal review, tenant-isolation and citation/hash tests, redaction and prompt-injection/hallucination evaluations, human-review and rollback semantics, immutable/tamper-evident audit, cost/rate monitoring, incident kill switch, retention/deletion jobs, and durable worker/retry idempotency. The current Compose stack has no configured AI provider and is not production-ready for AI processing.
+
 Report vulnerabilities privately to the repository maintainers; do not include live credentials or personal data in an issue.