chore: snapshot docs for v3.3.0-beta.3

.dockerignore

@@ -39,6 +39,8 @@ dist/docs/*
 !dist/docs/3.3.0-beta.2/**
 !dist/docs/3.1.31
 !dist/docs/3.1.31/**
+!dist/docs/3.3.0-beta.3
+!dist/docs/3.3.0-beta.3/**
 !dist/schemas
 dist/schemas/latest
 dist/schemas/v*

dist/docs/3.3.0-beta.3/aao/aao-admins.mdx

@@ -0,0 +1,84 @@
+---
+title: AAO for AAO Admins
+description: Internal reference — editorial moderation, escalation triage, system settings, and member directory operations for AAO staff.
+"og:title": "AdCP — AAO for AAO Admins"
+noindex: true
+---
+
+# AAO for AAO Admins
+
+This page is for AAO staff with the global admin role — people on the AgenticAdvertising.org team who run editorial review, escalation triage, member ops, and system administration. It is intentionally narrow and operational.
+
+This page is indexed by Addie's `search_docs` so she can answer admin questions correctly, but is `noindex: true` for search engines and is hidden from the public docs sidebar.
+
+For end-user docs see [AAO for Members](/dist/docs/3.3.0-beta.3/aao/users). For org-admin docs see [AAO for Org Admins](/dist/docs/3.3.0-beta.3/aao/org-admins). For the full list of Addie's tools see the [Addie Tool Reference](/dist/docs/3.3.0-beta.3/aao/addie-tools).
+
+## Becoming an AAO admin
+
+Site-admin access is granted through membership in the server-pinned `aao-admin` working group. Manage that membership from the existing people/working-group administration views; WorkOS organization roles never grant AgenticAdvertising.org platform administration.
+
+`ADMIN_EMAILS` is an environment-managed break-glass path. It is not shown or edited in the UI. Keep its list minimal, rotate it through the deployment-secret process, and remove emergency entries as soon as the incident is resolved. When removing an entry, deploy the changed environment to every application replica and verify that the former address can no longer use an admin route.
+
+Addie web and voice administrator checks use the WorkOS credential that actually signed in, including its own email for break-glass access. Linking identities does not transfer platform administration: an administrator signing in through a linked non-admin canonical profile retains access, while a non-admin credential linked to an administrator does not inherit it. Organization owners cannot list or resolve the platform-wide escalation queue.
+
+When the administrator lookup is unavailable, Addie web requests return a retryable `503` with `admin_authorization_unavailable`; an already-open Addie stream reports a recoverable error. This is separate from `403` for a confirmed denial. A separately configured break-glass email remains valid during a membership lookup outage. Voice calls require captured credential provenance; legacy calls must restart through sign-in.
+
+Voice callbacks also require a signed session capability bound to the server's conversation record. A thread ID supplied in conversation text grants no access. Ending a call revokes that capability before contacting the video provider; expired, revoked, or unverified calls require a new session. Rotate `TAVUS_LLM_SECRET` consistently across replicas; rotation invalidates existing call capabilities.
+
+Every site-admin grant or revoke requires a written reason and writes an append-only event with the actor, target, access mechanism, reason, and timestamp. The revoke and its audit event commit together, so deleting the active membership cannot delete its forensic record.
+
+Admin authorization results are not cached. A grant or revoke is visible to every replica on its next authorization check, without a positive-cache propagation window. Failed checks remain fail-closed and are reported as unavailable rather than reused as either a grant or denial.
+
+## Escalation triage
+
+Members and visitors can ask Addie to escalate when she can't help. Escalations land in the database and a Slack notification fires to the configured escalation channel.
+
+- **Review the queue.** Web UI at `/admin/addie` (Escalations tab), or ask Addie *"list open escalations"* (`list_escalations`).
+- **Auto-triage suggestions.** A scheduled job in `server/src/addie/jobs/escalation-triage.ts` proposes status transitions on open escalations with evidence (URL probes, related escalation IDs). Suggestions land in `escalation_triage_suggestions` and require admin accept/reject before applying — every close has an operator behind it.
+- **Resolve from any thread.** *"Resolve escalation 142, paid the invoice"* (`resolve_escalation`) — `wont_do` is the right status when a request is intentionally not actionable; `resolved` means the asked-for thing happened.
+- **Categories.** `capability_gap` (Addie's knowledge needs updating), `needs_human_action` (admin had to do something), `complex_request` (multi-step / judgment), `sensitive_topic` (legal/compliance/political), `other`.
+
+## Editorial moderation (perspectives)
+
+Addie's committee-leader review powers also belong to the authenticated credential. Linking to a committee leader's profile does not grant publishing, approval, rejection, revision, or pending-review access. Personal author attribution remains associated with the person's profile.
+
+- **Review queue.** Web UI at `/admin/perspectives` shows `pending_review`. Or ask Addie *"list pending content"* (`list_pending_content`).
+- **Approve / decline.** *"Approve perspective [slug]"* (`approve_content`), *"reject perspective [slug] with reason ..."* (`reject_content`).
+- **Test posts.** Test perspectives published bypassing review (incident #271) come from the older publish path; the canonical path is `propose_content` → review → approve. If you see test content live without review, file an incident — that's a real bug, not a workflow.
+
+## Member directory ops
+
+- **List / get members.** *"Show member directory for [filter]"* (`list_members`, `get_member`). Public lookups are anonymous-safe; full contact details require admin.
+- **Send a payment request to a prospect.** `send_payment_request` (admin-tools.ts) issues an invite that the recipient signs in to accept. Their email is bound to the resulting Stripe customer at acceptance time, never trusted from caller-supplied input.
+- **Comp / discount membership.** Use `send_payment_request` with a $0 product or a coupon. For unusual cases (chapter leads, contributors), escalate or coordinate with billing manually.
+- **Promote / demote within an org.** Today this is a database operation; CLI scripts under `scripts/` cover the common cases. We're working on a tool surface.
+
+## Portrait management
+
+Members can manage their own illustrated portrait from their profile page. Addie's member-scoped portrait tools (`check_portrait_status`, `offer_portrait_generation`) only operate on the caller's own member organization context.
+
+Admin moderation uses the admin portrait API:
+
+- **List portraits.** `GET /api/admin/portraits?status=generated` returns generated portraits for review. Use `status=approved` or omit `status` to inspect other queues.
+- **Map active portraits.** `GET /api/admin/portraits/map` returns the lightweight user-to-portrait mapping for directory checks.
+- **Remove a portrait.** `DELETE /api/admin/portraits/:id` rejects the portrait and clears it from the member if it is their active portrait.
+
+## System settings
+
+- **Escalation channel.** `system_settings.escalation_channel` controls where Addie posts escalation notifications. Update via the admin web UI.
+- **Working-group channels.** `system_settings.wg_channel_*` map each WG to its Slack channel.
+- **Audit log.** `system_settings_audit` records every change — review at `/admin/audit`.
+
+## Internal flags and gates
+
+- `ADMIN_EMAILS` — comma-separated, environment-managed break-glass access. Rotate and remove entries through deployment secrets; do not treat it as a UI-managed role.
+- `ALLOW_INSECURE_COOKIES` — dev only; do not set in prod.
+- `ANTHROPIC_API_KEY` — required for Addie chat to function at all.
+- `ANONYMOUS_DAILY_LIMIT_USD` — daily anonymous usage cap; gates `anonymousChat` model.
+
+## Things to escalate further (engineering, not ops)
+
+- Empty assistant messages on short follow-ups — investigation needed in `claude-client.ts`.
+- Duplicate-message bug (#124) — same response posted twice.
+- Stale `search_docs` index symptoms — run a probe via `npm run start` locally, call `searchDocs(query)` directly to confirm.
+- Anonymous-mode tool refusal — Addie sometimes deflects to sign-in even when the tool is in `ANONYMOUS_SAFE_KNOWLEDGE_TOOLS`. Behavior gap, not a bug in the registry.