spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/reference/functions/ai-interactions.md

@@ -0,0 +1,156 @@
+---
+title: ai-interactions
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/ai-interactions.ts
+  - .framework/functions/ai-agents.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - public/_redirects
+---
+
+# ai-interactions
+
+## What it does
+
+`ai-interactions` (`.framework/functions/ai-interactions.ts`) writes the
+feedback and observability side of the AI loop as `items` rows. It is *not*
+the conversation engine:
+
+- Interactive turns run through `POST /api/ai-agents?action=run` — `runAgent`
+  in `.framework/functions/_shared/agent-runner.ts` drives a `threads` row,
+  persists `messages`, and manages the episode lease.
+- Stateless pipeline inference runs through the `agent_inference` stage
+  (`.framework/functions/_shared/pipeline-runner.ts`) — it POSTs `{ context,
+  model, temperature, max_tokens }` to `config.webhook_url` via
+  `integration-outbound` (`generic-http`), and returns a marked mock response
+  when `webhook_url` is unset.
+- `ai-interactions` records what happened around those paths: customer
+  thumbs feedback, per-interaction telemetry rows, and draft learning
+  proposals.
+
+Actions (dispatched on `?action=`):
+
+| Action | Method | Purpose |
+|---|---|---|
+| `submit_feedback` | POST | Record `helpful`/`not_helpful` on an AI message; escalate or resolve the ticket. |
+| `create_interaction` | POST | Insert a telemetry item (default type `ai_feedback_record`, overridable via `type_slug`). The pipeline `create_interaction` stage lazy-imports this handler. |
+| `update_interaction` | PATCH or POST | Merge allow-listed fields into an existing interaction item. |
+| `create_cil_proposal` | POST | Insert a `status: 'draft'` learning-proposal item (fixed `cil_*` type slug) from ticket context and source references. |
+| `list` | GET | List interaction items for the caller's account (default action). |
+
+## Route and methods
+
+- `/api/ai-interactions?action=<action>` — `public/_redirects` maps `/api/*`
+  to `/.netlify/functions/:splat`; the export `handler` is a
+  `createHandler`-wrapped dispatcher reading `ctx.query.action` and
+  `ctx.query.method` (populated from the HTTP method).
+- `GET` with no `action` (or an unrecognized one) falls through to `list`;
+  other invalid action/method pairs throw `Invalid action or method`.
+
+## Authentication
+
+`createHandler` resolves a principal and rejects anonymous requests with 401.
+There is no role gate — any authenticated human or machine principal may call
+the actions. `list` reads through `ctx.db` scoped to `ctx.accountId`;
+`create_interaction`/`create_cil_proposal`/`update_interaction` write through
+admin-data `create`/`update`, so the caller's permissions, audit, and
+triggers apply. `submit_feedback` writes `messages`/`items` via `adminDb`
+directly (service role) — it does not check that the caller owns the ticket.
+
+## Request contract
+
+`submit_feedback` (POST):
+
+| Field | Required | Notes |
+|---|---|---|
+| `message_id` | yes | `messages.id` of the AI reply. |
+| `ticket_id` | yes | `items.id` of the ticket under discussion. |
+| `feedback` | yes | `'helpful'` or `'not_helpful'`. |
+| `reason` | no | Free text, truncated to 2000 chars. |
+
+`create_interaction` (POST): `thread_id` *or* `ai_message_id` required.
+Optional: `type_slug` (default `ai_feedback_record`; skipped silently when
+the type isn't installed), `retrieved_sources`, `per_source_feedback`,
+`ai_confidence`, `retrieval_confidence`, `kb_candidate`, `answer_quality`,
+`assistance_outcome`, `eval_case_id`, the learning-proposal linkage id,
+`review_notes`, `reviewed_by`, `reviewed_at`. The record is titled
+`AI Interaction — <date>`, `status: 'active'`.
+
+`update_interaction` (PATCH/POST): `id` required plus ≥1 allow-listed field:
+`kb_article_id`, `human_message_id`, `human_edits_made`, `customer_feedback`,
+`kb_candidate`, `reuse_count`, `per_source_feedback`, `answer_quality`,
+`assistance_outcome`, `eval_case_id`, the learning-proposal linkage id,
+`review_notes`, `reviewed_by`, `reviewed_at`.
+
+`create_cil_proposal` (POST): `ticket_id` and `proposed_summary` required;
+optional `thread_id`, `ai_message_id`, `source_message_ids`,
+`source_chunk_ids`, `proposed_tags`. Returns `{ skipped: true }` when the
+proposal type isn't installed.
+
+`list` (GET): query params `feedback`, `kb_candidate`, `limit` (default 50),
+`offset` (default 0).
+
+## Response contract
+
+- `submit_feedback` → `{ message_id, ticket_id, feedback, escalated }` where
+  `escalated` is `feedback === 'not_helpful'`.
+- `create_interaction` / `create_cil_proposal` → the created `items` record,
+  or `{ skipped: true, reason: '<type> type not found' }` when the type slug
+  can't be resolved — **not** an error.
+- `update_interaction` → the admin-data `update` result.
+- `list` → an array of `items` rows (filtered to the `ai_feedback_record`
+  type when that type exists).
+
+## Side effects
+
+- `submit_feedback` stamps `messages.data.feedback` (+ `feedback_reason`,
+  and for `not_helpful` a `feedback_diagnosis` + `needs_review: true`).
+  Diagnosis is heuristic over the message's own evidence trail:
+  `missing_knowledge` (no retrieved sources), `retrieval_miss` (mean
+  similarity < 0.35), `reasoning_error` (sources retrieved but none cited),
+  else `wrong_answer`.
+- Ticket lifecycle side effects on the `items` row: `not_helpful` sets
+  `status: 'human_assigned'` from any state except `human_assigned`/
+  `in_progress`, reopening `resolved`/`closed` tickets (`reopened_at`,
+  `reopen_reason: 'thumbs_down'`, resolution stamps cleared). `helpful` on a
+  `pending_resolution` ticket resolves it with `resolved_via:
+  ai_confirmed|human_confirmed` (chosen from `pending_proposed_by`) and
+  `aim_resolved_by_ai`.
+- The first `items` row whose `data.ai_message_id` matches gets
+  `customer_feedback` (+reason/diagnosis) stamped.
+- `ai_interaction.feedback_submitted` audit event plus a `funnel_signal`
+  `feedback_submitted` journey signal (fire-and-forget).
+
+## Errors
+
+| Condition | Error |
+|---|---|
+| Missing inputs | `message_id is required` · `ticket_id is required` · `id is required` · `thread_id or ai_message_id is required` · `proposed_summary is required` |
+| Bad enum | `feedback must be "helpful" or "not_helpful"` |
+| Empty patch | `No updatable fields provided` |
+| Unknown interaction id | `Interaction record not found` |
+| Bad dispatch | `Invalid action or method` |
+
+## Agent notes
+
+- Use `type_slug` on `create_interaction` to record under an app-specific
+  item type; the `{ skipped: true }` return makes the call safe to fire even
+  when the type isn't installed — check for `skipped` instead of treating it
+  as failure.
+- `submit_feedback` is a lifecycle accelerator, not just a thumbs counter:
+  thumbs-up is the explicit customer confirmation that closes a
+  `pending_resolution` ticket, thumbs-down escalates and can reopen. Calling
+  it outside the support-ticket statuses is a no-op for the ticket fields.
+- The pipeline `create_interaction` stage resolves `ai_message_id`/
+  `thread_id` from trigger data and passes `config.type_slug` through.
+- `list` queries `ctx.db` — a machine principal sees account-scoped rows via
+  `adminDb`, a human sees RLS-filtered rows.
+- See [AI agents, prompt configs, and embeddings](../../concepts/ai-and-prompts.md)
+  for how the run path, inference, and these records fit together.

package/.framework/src/instructions/reference/functions/api-keys.md

@@ -0,0 +1,130 @@
+---
+title: api-keys
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/api-keys.ts
+  - .framework/functions/_shared/hash-api-key.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/public/_redirects
+---
+
+# api-keys
+
+## What it does
+
+Mints, validates, revokes, and lists API keys — the `sk_…` credentials
+that resolve to machine principals on every other endpoint. Also exposes
+per-key usage logs.
+
+## Route and methods
+
+`/.netlify/functions/api-keys`, reachable as `/api/api-keys` (`/api/*` →
+`/.netlify/functions/:splat`). Dispatch is by `?action=` plus method
+(`?method=` can override the HTTP method):
+
+| Call | Action |
+|---|---|
+| `GET /api/api-keys` | `list` |
+| `GET /api/api-keys?id=<uuid>` | `get` |
+| `POST /api/api-keys` | `create` |
+| `POST /api/api-keys?action=validate` | `validate` |
+| `POST /api/api-keys?action=revoke` | `revoke` |
+| `GET /api/api-keys?action=usage-logs` | `listUsageLogs` |
+
+Unrecognized `action` values fall through to the method-based default
+branch, so `GET`/`POST` still dispatch; only methods other than `GET`,
+`POST` (or a matched action with the wrong method) reach
+`Invalid action or method`.
+
+## Authentication
+
+Standard `createHandler`: `x-api-key`, internal secret, or
+`Bearer <jwt>`; anonymous → 401. `list`, `create`, and `usage-logs`
+additionally require `ctx.accountId` ("Account context required").
+
+- System admins read via `adminDb` (all accounts); other principals use
+  `ctx.db` — JWT-scoped (RLS) for humans, service role for machines.
+- There is **no machine-scope check** in this file. A machine principal
+  with an `account_id` can create/revoke/read keys within what its
+  service-role client reaches — treat key management as a trusted-surface
+  operation.
+
+## Request contract
+
+**list** (query): `integration_id`, `key_type`, `is_active` (`'true'`/
+`'false'`), `expires_before`, `expires_after`, `limit` (default 100),
+`offset` (default 0). Ordered `created_at` desc.
+
+**get** (query): `id`.
+
+**create** (body): `name` required. Optional: `slug` (defaults to a
+slugified `name`), `key_type` (default `'inbound'`), `permissions`,
+`scopes`, `rate_limit` (default `100`), `expires_at`, `metadata`,
+`integration_id`, `app_id` (resolved via `resolveAppUuid`, falling back
+to the `x-app-id` header's app), `machine_type` (default `'integration'`),
+`is_internal` (default `false`). `account_id` and `is_active: true` are
+stamped from context; `created_by` is the principal id.
+
+**validate** (body): `key_value` required; `required_permissions`
+optional array.
+
+**revoke** (body): `id` required.
+
+**usage-logs** (query): `api_key_id`, `response_status`, `success`,
+`date_from`, `date_to`, `limit` (default 100), `offset` (default 0).
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `create` → the inserted row (`id, name, key_type, rate_limit,
+  expires_at, is_active, created_at`) **plus `raw_key` — the only time
+  the secret is returned** — and `warning: 'Store this key now. It will
+  not be shown again.'` Raw key format: `sk_<32 hex chars>`.
+- `validate` → `{ is_valid: true, api_key_id, integration_id, app_id,
+  account_id, scopes, permissions }`, or `{ is_valid: false, error }`
+  (HTTP 200 in both cases; `Insufficient permissions` carries
+  `api_key_id`).
+- `list`/`get`/`revoke`/`usage-logs` → rows passed through
+  `sanitizeRecordData` + `omitSecretFields`, so `key_hash`/`key_value`-type
+  secret columns never leave the function. Only `key_prefix` (first 8
+  chars of the raw key) is stored in plaintext as the lookup index.
+
+## Side effects
+
+- `create` inserts an `api_keys` row storing `key_prefix` and a
+  PBKDF2-SHA256 `key_hash` (the raw key is never stored).
+- `revoke` sets `is_active = false` (keys are never hard-deleted here).
+- `emitLog` writes `api_key.created` / `api_key.revoked` audit entries.
+- Note: `api_key_usage_logs` rows are written by `resolvePrincipal` on
+  every authenticated request that uses a key, not by this endpoint.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing `name` / `id` / `key_value` | 500 | `name is required` / `API key ID is required` / `key_value is required` |
+| No account context | 500 | `Account context required` |
+| Unknown action/method | 500 | `Invalid action or method` |
+| DB failures | 500 | PostgREST message |
+
+`validate` failures are payload-level (`is_valid: false`), not HTTP
+errors.
+
+## Agent notes
+
+- `validate` checks permissions as **any-match**: a key passes if at least
+  one of its `permissions` entries appears in `required_permissions`.
+  Wildcard `*:*` in `scopes` is honored at principal resolution, not here.
+- Key verification happens on prefix-matched candidates (`key_prefix` =
+  first 8 chars), then PBKDF2 verify — `validate` mirrors exactly what
+  `resolvePrincipal` does on a live request.
+- To call `validate`/`revoke`/`get` a caller needs only to be
+  authenticated (no `ctx.accountId` check on those paths); `revoke` on a
+  machine principal runs with the service role — pin management calls to
+  humans or `*:*` keys in practice.
+- `expires_at` is nullable; expiry is enforced at resolution time
+  (`expires_at.is.null OR expires_at >= now`).

package/.framework/src/instructions/reference/functions/apps.md

@@ -0,0 +1,140 @@
+---
+title: apps
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/apps.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/013_get_account_apps_role_filter.sql
+  - .framework/public/_redirects
+---
+
+# apps
+
+## What it does
+
+CRUD over `public.apps` — the app registry that controls routing
+(`route_prefix`, `renderer`), visibility (`min_role`, `required_roles`),
+and install metadata (`version`, `app_type`, `source`,
+`integration_deps`). Also exposes schema, availability, and version-bump
+RPC pass-throughs.
+
+## Route and methods
+
+`/.netlify/functions/apps`, reachable as `/api/apps` (`/api/*` →
+`/.netlify/functions/:splat`, `.framework/public/_redirects`). Dispatch
+is by method plus `?action=`/`?id`/`?slug`:
+
+| Call | Handler |
+|---|---|
+| `GET /api/apps` | `list` (also `?action=list`) |
+| `GET /api/apps?id=<uuid>` or `?slug=<s>` or `?action=get` | `get` |
+| `GET /api/apps?action=schema&slug=<s>` | `getSchema` → RPC `get_app_schema` |
+| `GET /api/apps?action=available&slug=<s>` | `checkAvailability` → RPC `is_app_available` |
+| `POST /api/apps` | `create` |
+| `POST /api/apps?action=version` | `updateVersion` → RPC `update_app_version` |
+| `PATCH /api/apps?id=<uuid>` (or `id` in body) | `update` |
+| `DELETE /api/apps?id=<uuid>` (or `id` in body) | `remove` |
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list` requires an account context (`ctx.accountId` or an explicit
+  `account_id` query param).
+- `create` allows non-system-admins only when
+  `resolveFirstSurfacePermissions(principal.id, accountId, 'app',
+  'create')` grants `canCreate`.
+- `update`/`remove` have no role gate in this file — field-level control
+  comes from `validateUpdatePermissions` (update only) and RLS on
+  `ctx.db` for human callers. Machine principals run `ctx.db` as the
+  service role.
+
+## Request contract
+
+**list** (query): `account_id` (defaults to `ctx.accountId`),
+`include_system` (default true; `'false'` excludes), `include_inactive`
+(`'true'` to include). Backed by the `get_account_apps` RPC, which
+filters by ownership, active state, `required_roles`/`min_role` against
+the caller's role slugs unless the caller is a system admin
+(`.framework/migrations/013_get_account_apps_role_filter.sql`).
+
+**get** (query): `id` or `slug` (active rows only).
+
+**getSchema** / **checkAvailability** (query): `slug`.
+
+**create** (body): `slug`, `name` required. Optional with defaults:
+`version` `'1.0.0'`, `app_type` `'custom'`, `source` `'custom'`,
+`owner_account_id` → caller's account, `config` `{}`, `nav_items` `[]`,
+`min_role` `'member'`, `required_roles` `[]`, `integration_deps` `[]`, `metadata` `{}`,
+`route_prefix` `'/' + slug`, `renderer` `'generic'`; `is_active: true`,
+`is_system: false` are forced.
+
+**update** (`id` in body or query + body): **no field allowlist** —
+every body key except `id` is written verbatim plus `updated_at`, after
+`validateUpdatePermissions(ctx, updates, current, 'apps')` passes.
+
+**remove** (`id` in body or query): sets `is_active = false`.
+
+**updateVersion** (body): `id`, `version` required.
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- `list` → rows from `get_account_apps`, each passed through
+  `sanitizeRecordData`. Non-system-admins receive only the routing
+  whitelist (`id, slug, name, description, route_prefix, min_role,
+  required_roles, preview_domain, prod_domain, is_active, is_system,
+  renderer, created_at, updated_at`); admins get the full row.
+- `get` → sanitized row. `getSchema` → raw RPC result.
+  `checkAvailability` → `{ available: boolean }`. `updateVersion` →
+  `{ success: true }`.
+
+## Side effects
+
+- `create` inserts into `public.apps`; a duplicate `slug` is rejected by
+  a pre-check before insert (slug has a global `UNIQUE` constraint in
+  `.framework/migrations/001_core_schema.sql`).
+- `update`/`remove` write `updated_at`; remove is a soft delete.
+- `emitLog` writes `app.created`, `app.updated`, `app.deleted`, and
+  `app.version_updated` audit rows to `public.logs`.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No account context (list, available) | 500 | `Account context required` |
+| Missing slug/id | 500 | `App ID or slug is required` / `App slug is required` / `App ID is required` |
+| Missing create fields | 500 | `slug and name are required` |
+| Non-admin without create grant | 500 | `Insufficient permissions to create apps` |
+| Duplicate slug | 500 | `App slug already exists` |
+| Missing row (update/remove) | 500 | `App not found` |
+| Missing version args | 500 | `App ID and version are required` |
+| Unknown method | 500 | `Unsupported method: <METHOD>` |
+
+Validation failures surface as HTTP 500 — thrown `Error`s without a
+`statusCode` map to 500 in the shared error path.
+
+## Agent notes
+
+- The four RPCs called here — `get_app_schema`, `is_app_available`,
+  `update_app_version` (plus `get_type_schema` for types) — are provided
+  by `.framework/migrations/070_app_type_schema_rpcs.sql`;
+  `get_account_apps` exists via
+  `.framework/migrations/013_get_account_apps_role_filter.sql`. Installs
+  missing migration 070 will see `function does not exist` errors.
+- `update` will write **any** column present in the body (including
+  `slug`, `is_system`, `owner_account_id`) — the only guard is
+  `validateUpdatePermissions`, which is config-object (second-surface)
+  logic. Treat it as an admin-trusted endpoint.
+- `remove` does not check `is_system` or permissions at all beyond
+  authentication + RLS for human callers.
+- `renderer` defaults to `'generic'` on create — custom-renderer apps
+  must pass `renderer: 'custom'` explicitly (see
+  [Apps and renderers](../../concepts/apps-and-renderers.md)).

package/.framework/src/instructions/reference/functions/auth.md

@@ -0,0 +1,99 @@
+---
+title: auth
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/auth.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/public/_redirects
+---
+
+# auth
+
+## What it does
+
+Returns the caller's resolved user context: the `people` row bound to the
+JWT, its role and permissions, and the set of accounts the person can
+reach through the account hierarchy. This is the endpoint the frontend
+calls after login to learn "who am I".
+
+## Route and methods
+
+`/.netlify/functions/auth`, reachable as `/api/auth` (`/api/*` →
+`/.netlify/functions/:splat`). Dispatch is on `ctx.query.method`, which
+the middleware fills from the HTTP method but a `?method=` query
+parameter can override:
+
+| Call | Result |
+|---|---|
+| `GET /api/auth` | `context` — the user-context payload below |
+| `GET /api/auth?method=HEALTH` | `health` — `{ status: 'healthy', timestamp, service: 'auth' }` |
+| any other method | error `Unsupported method: <method>` |
+
+`HEALTH` is a query-param convention, not an HTTP method — there is no
+`?action=` dispatch.
+
+## Authentication
+
+Standard `createHandler`: `x-api-key`, internal secret, or
+`Bearer <jwt>`; anonymous is rejected with 401, and `context` re-checks
+`principal.id !== 'anonymous'`. All queries run on `ctx.db` — JWT-scoped
+for humans (RLS applies), service role for machines/system. In practice
+`context` is human-only: a machine principal's id is an API-key id, not a
+`people.id`, so the person lookup returns "User not found".
+
+## Request contract
+
+No parameters for `context` — identity comes entirely from the resolved
+principal. `?method=HEALTH` selects the health check.
+
+## Response contract
+
+`context` returns inside the standard `{ data, error, meta }` envelope:
+
+```json
+{
+  "id": "<people.id>",
+  "email": "...",
+  "full_name": "...",
+  "account_id": "<uuid>",
+  "account": { "id", "slug", "display_name", "parent_id" },
+  "roles": ["<role slug>"],
+  "permissions": ["read", "write", ...],
+  "is_system_admin": false,
+  "status": "active",
+  "accessible_accounts": [{ "id", "slug", "display_name", "parent_id" }]
+}
+```
+
+- `roles` is a single-element array of the person's role slug.
+- `permissions` is `['read', 'write', 'admin', 'system']` for
+  `system_admin`, else the role row's `permissions` array (possibly `[]`).
+- `accessible_accounts` comes from the `get_accessible_accounts` RPC,
+  raced against a 5-second timeout; on failure or timeout it degrades to
+  `[]` rather than erroring.
+
+## Side effects
+
+None — read-only (the middleware still emits request spans/logs).
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Anonymous | 401 | `Authentication required` |
+| `people` row missing/inactive | 500 | `User not found: <principal.id>` |
+| Unsupported method | 500 | `Unsupported method: <method>` |
+
+## Agent notes
+
+- `is_system_admin` and `permissions` are derived here, not authoritative
+  checks — server-side endpoints re-evaluate roles from the principal.
+- The 5-second `get_accessible_accounts` timeout means a slow hierarchy
+  query yields `accessible_accounts: []`, not an error; clients should not
+  treat an empty list as proof of a single-account deployment.
+- Role/account changes can lag up to ~60 seconds because human principals
+  are cached per warm function instance.

package/.framework/src/instructions/reference/functions/debug-auth.md

@@ -0,0 +1,91 @@
+---
+title: debug-auth
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/debug-auth.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/public/_redirects
+---
+
+# debug-auth
+
+## What it does
+
+Diagnostic endpoint for troubleshooting authentication. Reports whether a
+principal was resolved from the request credentials and whether the
+function's Supabase environment variables are configured. **This is a
+debug/diagnostic endpoint, not part of the product API.**
+
+## Route and methods
+
+`/.netlify/functions/debug-auth`, reachable as
+`/api/debug-auth` (`/api/*` → `/.netlify/functions/:splat`). There is no
+HTTP-method or `action` dispatch — the only selector is the `?method=`
+**query parameter**, read directly off the request:
+
+| Call | Result |
+|---|---|
+| `GET /api/debug-auth` (or `?method=debug`, the default) | env + principal summary |
+| `GET /api/debug-auth?method=testJwt` | principal echo for a Bearer token |
+| any other `?method=` value | falls through to `debug` |
+
+## Authentication
+
+Standard `createHandler` — so a valid `x-api-key`, internal secret, or
+`Bearer <jwt>` is required and anonymous gets 401. As of the S-006 fix the
+handler **requires a `system_admin` principal** — non-admin principals are
+rejected with `statusCode` 403. That is the
+point of a diagnostic — it answers "did my credentials resolve, and as
+what?".
+
+## Request contract
+
+`?method=debug|testJwt` only. No body.
+
+## Response contract
+
+Both branches return an object with a top-level `data` key, so the payload
+is nested one level deep inside the standard envelope —
+`{ "data": { "data": { ... } }, "error": null, "meta": {...} }`.
+
+`debug` returns:
+
+```json
+{
+  "message": "Debug auth endpoint",
+  "hasPrincipal": true,
+  "principalType": "human",
+  "requestId": "<uuid>",
+  "envVars": {
+    "supabaseUrl": "SET",
+    "supabaseAnonKey": "SET"
+  }
+}
+```
+
+`testJwt` returns `{ tokenValid: true, principal: { type, id, accountId } }`,
+or `{ data: null, error: 'No principal resolved from token' }` when the
+principal is missing.
+
+## Side effects
+
+None — read-only. Env-var values are never returned, only `SET`/`NOT_SET`
+flags for `SUPABASE_URL` and `SUPABASE_ANON_KEY`.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Anonymous | 401 | `Authentication required` |
+
+## Agent notes
+
+- Use `?method=testJwt` to verify a `Bearer` token resolves to the
+  expected person + account, and `debug` to sanity-check a deployment's
+  env wiring.
+- Because it is an admin-only diagnostic surface, do not build
+  product logic on it and expect it to behave like a hardened endpoint.
+- The double-nested `data.data` shape is real — unwrap twice.