docs: cut the living docs for concision

docs/decisions/README.md

@@ -83,48 +83,46 @@ not access logs, so it is not proof of non-access.
 **Decision.** The PostgREST Data API is not part of Helpthread's architecture. The
 application reaches Postgres directly over the pooler (`DATABASE_URL`) and uses Supabase
 Storage with the `service_role` key; no anon-key client exists anywhere in the codebase.
-Migration 027 therefore enables RLS on every table and revokes the `anon`/`authenticated`
-grants, including via `ALTER DEFAULT PRIVILEGES` so future tables created by the migrating
-role do not arrive pre-granted. Neither half hardcodes `public`, because `PostgresDb`
-supports a `schema` option; the revokes derive the schema from `'conversations'::regclass`
-— deliberately *not* `current_schema()`, which resolves to search_path's first entry rather
+Migration 027 enables RLS on every table and revokes the `anon`/`authenticated` grants,
+including via `ALTER DEFAULT PRIVILEGES` so future tables created by the migrating role do
+not arrive pre-granted. Neither half hardcodes `public`, because `PostgresDb` supports a
+`schema` option; the revokes derive the schema from `'conversations'::regclass` —
+deliberately *not* `current_schema()`, which resolves to search_path's first entry rather
 than to the schema actually holding the tables, and so can diverge from the unqualified
-`ALTER TABLE`s. (An earlier revision of this change used `current_schema()` and was caught
-in review; the divergence fails silently, leaving the grants in place while the migration
-reports success.) The same lockdown was applied directly to the production project ahead of
-the migration landing, to close live exposure rather than wait on review.
-
-Be precise about the limits of the `ALTER DEFAULT PRIVILEGES` layer, which is easy to
-overrate: it *deletes a default-ACL entry* rather than installing a standing deny, and
-without `FOR ROLE` it binds only to the role that ran the migration. It does not survive
-Supabase re-running its stock bootstrap, and it does not touch defaults defined for other
-roles such as `supabase_admin`. The durable protection is the standing rule below.
-
-**Alternatives considered.** Enabling RLS alone was rejected: the grants would remain, so
-a single future permissive policy would reopen everything. Revoking grants alone was
-rejected for the mirror-image reason — anything that re-grants, including Supabase
-re-running its stock bootstrap, restores them, and as noted above the default-privileges
-layer does not prevent that. Writing real per-tenant RLS policies was rejected as solving a problem Helpthread
-does not have: policies exist to make anon access safe, and there is no anon access to
-make safe. Deny-by-default with no policies is the honest expression of that.
-
-**Consequences.** The Supabase security advisor now reports `rls_enabled_no_policy` at
-INFO level for every table. That is the intended end state, not an outstanding item.
-Tables are owned by `postgres`, which bypasses RLS unless `FORCE ROW LEVEL SECURITY` is
-set — deliberately not set — so the application is unaffected. A standing rule follows:
-any migration adding a table must also enable RLS on it.
-
-**This promotes an implicit deployment detail into an invariant: `DATABASE_URL` must
-connect as the role that owns the tables.** It does today — the runbook has the operator
-use the Supabase pooler string (role `postgres`) for both the app and `scripts/migrate.ts`,
-so connecting role and owning role coincide by construction. But pointing `DATABASE_URL` at
-a dedicated least-privilege role — a supported Supabase pattern — now breaks the engine, and
-the two halves break differently: reads go quiet (RLS with no policies returns zero rows
-instead of raising, so the symptom is an empty inbox rather than a database error) while
-every write hard-errors with `new row violates row-level security policy`. The loud signal
-arrives first, via inbound ingest. No test can catch the misconfiguration, because PGlite
-also runs as the owner. Separately,
-`splitStatements` in `src/db/migrate.ts` had to learn about dollar quoting, since
+`ALTER TABLE`s, silently leaving the grants in place while the migration reports success.
+The same lockdown was applied directly to the production project ahead of the migration
+landing, to close live exposure rather than wait on review.
+
+The `ALTER DEFAULT PRIVILEGES` layer is easy to overrate: it *deletes a default-ACL entry*
+rather than installing a standing deny, and without `FOR ROLE` it binds only to the role
+that ran the migration. It does not survive Supabase re-running its stock bootstrap, and it
+does not touch defaults defined for other roles such as `supabase_admin`. The durable
+protection is the standing rule below.
+
+**Alternatives considered.** Enabling RLS alone was rejected: the grants would remain, so a
+single future permissive policy would reopen everything. Revoking grants alone was rejected
+for the mirror-image reason — anything that re-grants, including Supabase's stock bootstrap,
+restores them. Writing real per-tenant RLS policies was rejected as solving a problem
+Helpthread does not have: policies exist to make anon access safe, and there is no anon
+access to make safe. Deny-by-default with no policies is the honest expression of that.
+
+**Consequences.** The Supabase security advisor now reports `rls_enabled_no_policy` at INFO
+level for every table — the intended end state, not an outstanding item. Tables are owned by
+`postgres`, which bypasses RLS unless `FORCE ROW LEVEL SECURITY` is set (deliberately not
+set), so the application is unaffected. **Standing rule: any migration adding a table must
+also enable RLS on it.**
+
+**This promotes an implicit deployment detail into an invariant: `DATABASE_URL` must connect
+as the role that owns the tables.** It does today — the runbook has the operator use the
+Supabase pooler string (role `postgres`) for both the app and `scripts/migrate.ts`. But
+pointing `DATABASE_URL` at a dedicated least-privilege role — a supported Supabase pattern —
+now breaks the engine, and the two halves break differently: reads go quiet (RLS with no
+policies returns zero rows rather than raising, so the symptom is an empty inbox, not a
+database error) while every write hard-errors with `new row violates row-level security
+policy`. The loud signal arrives first, via inbound ingest. No test can catch the
+misconfiguration, because PGlite also runs as the owner.
+
+Separately, `splitStatements` in `src/db/migrate.ts` had to learn about dollar quoting, since
 migration 027's role guard is a `DO $$ ... $$` block whose body contains semicolons.
 
 **Supersedes.** Nothing.

docs/modules/assistants-and-drafts.md

@@ -156,12 +156,11 @@ looked at anything.
 
 ## The Agent approval flow
 
-Everything past this point is an **Agent** action — the core Helpthread
-inbox UI does this for a human clicking "approve" or "discard," and it
-consumes exactly the same API, so these are also the calls a module author
-would use to build their own review tooling or to understand what the UI is
-doing. All three require `Authorization: Bearer $HELPTHREAD_API_TOKEN` +
-`X-Helpthread-Agent-Id: <acting Agent's uuid>` — missing either is `401`.
+Everything past this point is an **Agent** action. The core inbox UI does this for a
+human clicking "approve" or "discard" and consumes exactly the same API, so these are
+also the calls to build your own review tooling against. All three require
+`Authorization: Bearer $HELPTHREAD_API_TOKEN` + `X-Helpthread-Agent-Id: <acting Agent's
+uuid>` — missing either is `401`.
 
 **List the review queue** (every conversation's drafts, across the whole
 deployment, newest first):
@@ -193,19 +192,16 @@ curl -X POST "$BASE_URL/api/v1/drafts/$THREAD_ID/approve" \
   -d '{"bodyText": "Edited reply text..."}'
 ```
 
-Approval is a state transition, not a resend: it mints the reply's
-threading token and Message-ID, derives the envelope (recipient, subject,
-`In-Reply-To`/`References`) exactly the way a normal Agent reply does, and
-hands off to the same delivery worker — the mail that goes out is
-equivalent to what a human typing the same body and hitting reply would
-send. Fires `draft.resolved` immediately (`{ threadId, resolution:
-'approved', edited }`), and `conversation.reply_sent` once delivery actually
-confirms `sent` (not at accept-for-send time — modules reacting to "we
-replied" get truth, not intent).
-
-Refused `404` (indistinguishable-from-nonexistent) if the conversation is
-missing/soft-deleted or `$THREAD_ID` doesn't name a draft currently
-`awaiting_review`; refused `409 conflict` if the conversation is `spam`.
+Approval is a state transition, not a resend: it mints the reply's threading token and
+Message-ID, derives the envelope (recipient, subject, `In-Reply-To`/`References`) exactly
+as a normal Agent reply does, and hands off to the same delivery worker. Fires
+`draft.resolved` immediately (`{ threadId, resolution: 'approved', edited }`), and
+`conversation.reply_sent` only once delivery confirms `sent` — not at accept-for-send time,
+so modules reacting to "we replied" get truth, not intent.
+
+Refused `404` (indistinguishable-from-nonexistent) if the conversation is missing or
+soft-deleted, or `$THREAD_ID` doesn't name a draft currently `awaiting_review`; refused
+`409 conflict` if the conversation is `spam`.
 
 **Discard** (no send, row kept for audit):
 

docs/modules/webhooks.md

@@ -245,22 +245,8 @@ if (!result.valid) {
 const event = JSON.parse(rawBody)
 ```
 
-Reject a stale `t` (the 5-minute default above matches the spec's
-recommendation) to close a replay window — an attacker who captures one
-valid delivery cannot resend it indefinitely.
-
-> **Verified, not just written.** This exact function was checked before
-> landing in this doc, and re-checked after the hex-validation fix above:
-> (1) signed with the engine's own `signWebhookPayload`
-> (`src/webhooks/delivery.ts`) and verified successfully by this function,
-> byte-for-byte, with a real HMAC computed both ways; (2) cross-checked
-> against the independent verifier in `module-draft-assistant/src/verify.ts`
-> (the reference module referenced throughout this guide) — both verifiers
-> agree on the same signed payload; (3) correctly rejects a wrong secret, a
-> tampered body, a stale timestamp, and a signature with trailing non-hex
-> garbage appended after a valid-length prefix (`Buffer.from(str, 'hex')`
-> otherwise silently truncates instead of rejecting it). The throwaway
-> script that ran these checks exited `0`.
+Reject a stale `t` — the 5-minute default above — to close a replay window: an
+attacker who captures one valid delivery cannot resend it indefinitely.
 
 ## Delivery guarantees