@adonis-agora/agent 0.25.1 → 0.25.3

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @adonis-agora/agent
 
+## 0.25.3
+
+### Patch Changes
+
+- [#82](https://github.com/DavideCarvalho/adonis-agora-agent/pull/82) [`59be4e9`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/59be4e9943b47d79ce5f006c1d24b9b39e052f84) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add TanStack Intent agent skills. Both packages now ship a `skills/` directory
+  (five skills under @adonis-agora/agent: setup, tools, governance, personas &
+  multi-agent delegation, offline testing; one under @adonis-agora/agent-dashboard:
+  the governance console client) that coding agents can load as structured,
+  verified documentation. The directories are included in each package's `files`
+  allowlist, and `@tanstack/intent` is added as a devDependency so CI can enforce
+  skill validity via `intent validate`.
+
+## 0.25.2
+
+### Patch Changes
+
+- [#79](https://github.com/DavideCarvalho/adonis-agora-agent/pull/79) [`88018eb`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/88018ebfeef32be65c464b075d692b62a369d3fd) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fix `node ace configure @adonis-agora/agent`, which was broken in every published version.
+
+  The configure codemod runs each stub through Tempura, which compiles the stub **body** into a JavaScript
+  template literal. A bare backtick in the body closes that literal; a bare `${` opens an interpolation.
+  All four published stubs were full of both, in ordinary JSDoc prose — `` `lucid` ``, `` `model` ``,
+  `` `${documentId}#<n>` `` — so every one of them threw at render time.
+
+  `configure` therefore aborted on the very first stub, _after_ `updateRcFile` had already succeeded. The
+  result was worse than nothing happening: `adonisrc.ts` came out referencing the agent and dashboard
+  providers while `config/agent.ts` was never written, leaving an app that could not boot.
+
+  Both constructs are now backslash-escaped in the stub bodies (`` \` ``, `\${`). This is a render-time
+  concern only — the generated files are **byte-identical** to what the stubs always intended, backticked
+  prose and all, which was verified against the pre-fix sources.
+
+  The reason no gate caught this: every stub harness here rendered by stripping the `{{{ }}}` header with a
+  regex and using the remainder, which is not what the generator does. A gate that renders differently from
+  the generator is not testing the generator. All of them now render through the real engine
+  (`app.stubs.create().build().prepare()`), and a new `stub-render.spec.ts` asserts that every stub
+  `configure.ts` publishes actually renders — including the two config stubs, which no test had touched.
+
+  Users on an earlier version who ran `configure` and saw it fail should re-run it after upgrading; if
+  `adonisrc.ts` already lists the providers, the codemod is idempotent and only the missing files are written.
+
 ## 0.25.1
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.25.1";
+export declare const VERSION = "0.25.3";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.25.1';
+export const VERSION = '0.25.3';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/stubs/config/agent.stub

@@ -7,17 +7,17 @@ import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
 // import { openai } from '@ai-sdk/openai'
 
 /**
- * Configuration for @adonis-agora/agent. Only `model` is required. Pick a `store` by name from the
- * `stores` map (each driver's peer is imported lazily, only when selected); omit `store` for the
- * in-memory store. The runner is in-process by default (`durable` is deferred). The actor resolver
+ * Configuration for @adonis-agora/agent. Only \`model\` is required. Pick a \`store\` by name from the
+ * \`stores\` map (each driver's peer is imported lazily, only when selected); omit \`store\` for the
+ * in-memory store. The runner is in-process by default (\`durable\` is deferred). The actor resolver
  * defaults to one that THROWS — the agent never fabricates a caller — so wire a real one.
  *
- * Publish the tables with `node ace migration:run` after configuring.
+ * Publish the tables with \`node ace migration:run\` after configuring.
  */
 export default defineConfig({
   /**
-   * The LLM provider. Wrap the Vercel AI SDK via `aiSdkModel(...)` (from `@adonis-agora/agent/ai-sdk`)
-   * or supply any `ModelProvider`. A lazy thunk keeps the provider SDK peer imported only at boot:
+   * The LLM provider. Wrap the Vercel AI SDK via \`aiSdkModel(...)\` (from \`@adonis-agora/agent/ai-sdk\`)
+   * or supply any \`ModelProvider\`. A lazy thunk keeps the provider SDK peer imported only at boot:
    *
    *   model: () => aiSdkModel({ model: openai('gpt-4o-mini') }),
    */
@@ -40,7 +40,7 @@ export default defineConfig({
   // maxSteps: 8,              // cap on model↔tool iterations per turn
 
   // Governance console — served automatically at <path>/dashboard (default /agent/dashboard), no
-  // separate install. It only mounts once `governanceAuthorize` is set (every panel but Quota reads
+  // separate install. It only mounts once \`governanceAuthorize\` is set (every panel but Quota reads
   // the cross-actor governance routes, which need that gate too — see the docs). Toggle it off,
   // relocate it, or add an extra gate on top of governanceAuthorize:
   // dashboard: { enabled: true, path: '/agent/dashboard', authorize: (actor) => actor.roles?.includes('ADMIN') ?? false },
@@ -48,7 +48,7 @@ export default defineConfig({
 
   // Multimodal uploads — mounts POST /agent/attachments, which stages a file into a model-fetchable
   // MessageAttachment the client sends back with its next chat message. Bind your own store (presign
-  // S3/GCS or wrap your media pipeline); `attachmentStores.memory()` inlines bytes as a data: URL.
+  // S3/GCS or wrap your media pipeline); \`attachmentStores.memory()\` inlines bytes as a data: URL.
   // attachmentStaging: attachmentStores.memory(),
   // attachmentMaxBytes: 20 * 1024 * 1024,
   // attachmentAllowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],

package/dist/stubs/config/mcp.stub

@@ -6,10 +6,10 @@ import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
 
 /**
  * Configuration for the MCP (Model Context Protocol) endpoint. The provider exposes the agent's tool
- * registry over Streamable HTTP: `tools/list` mirrors the tools the acting actor may call and
- * `tools/call` runs them through the same role-checked registry the agent loop uses.
+ * registry over Streamable HTTP: \`tools/list\` mirrors the tools the acting actor may call and
+ * \`tools/call\` runs them through the same role-checked registry the agent loop uses.
  *
- * Requires `@adonis-agora/agent`'s agent provider (which owns the ToolRegistry singleton) to be
+ * Requires \`@adonis-agora/agent\`'s agent provider (which owns the ToolRegistry singleton) to be
  * registered. Register the MCP provider in adonisrc.ts:
  *
  *   providers: [
@@ -17,8 +17,8 @@ import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
  *     () => import('@adonis-agora/agent/mcp_provider'),
  *   ]
  *
- * The endpoint mounts at `/mcp`. When `auth` exposes OAuth metadata (authKitAuth), MCP clients discover
- * the login flow at `/.well-known/oauth-protected-resource/mcp`.
+ * The endpoint mounts at \`/mcp\`. When \`auth\` exposes OAuth metadata (authKitAuth), MCP clients discover
+ * the login flow at \`/.well-known/oauth-protected-resource/mcp\`.
  */
 export default defineMcpConfig({
   name: 'Agent MCP Server',

package/dist/stubs/database/migrations/create_agent_rag_chunks.stub

@@ -6,22 +6,22 @@ import db from '@adonisjs/lucid/services/db'
 import { PgVectorStore } from '@adonis-agora/agent'
 
 /**
- * The pgvector chunk table for the @adonis-agora/agent `retrievers.pgvector({...})` store: one row per
- * embedded chunk (id `${documentId}#<n>`), the chunk text, an optional citation source, a `jsonb`
- * metadata column filtered with `@>`, and the `vector(N)` embedding ranked with the `<=>`/`<->`/`<#>`
+ * The pgvector chunk table for the @adonis-agora/agent \`retrievers.pgvector({...})\` store: one row per
+ * embedded chunk (id \`\${documentId}#<n>\`), the chunk text, an optional citation source, a \`jsonb\`
+ * metadata column filtered with \`@>\`, and the \`vector(N)\` embedding ranked with the \`<=>\`/\`<->\`/\`<#>\`
  * operators. Requires the pgvector extension — Postgres only. Delete this file if you do not use
  * pgvector RAG.
  *
- * Like the agent tables migration, this DELEGATES rather than copying DDL: `PgVectorStore` owns the
+ * Like the agent tables migration, this DELEGATES rather than copying DDL: \`PgVectorStore\` owns the
  * column names and the index operator class its own queries depend on, and it exposes the same
- * provisioning the store runs for itself under `ensureSchema: true`. Every statement is
- * `IF NOT EXISTS`, so this is safe against a database that already has the table.
+ * provisioning the store runs for itself under \`ensureSchema: true\`. Every statement is
+ * \`IF NOT EXISTS\`, so this is safe against a database that already has the table.
  *
- * SET THESE to match your retriever config in `config/agent.ts` — they must agree, or the store will
+ * SET THESE to match your retriever config in \`config/agent.ts\` — they must agree, or the store will
  * query a table shaped differently from the one this created:
- *   - `DIMENSION` — your embedding model's width (1536 for text-embedding-3-small).
- *   - `METRIC` — 'cosine' (default), 'l2', or 'inner'. Picks the index operator class.
- *   - `TABLE` — only if you overrode `table` on the retriever.
+ *   - \`DIMENSION\` — your embedding model's width (1536 for text-embedding-3-small).
+ *   - \`METRIC\` — 'cosine' (default), 'l2', or 'inner'. Picks the index operator class.
+ *   - \`TABLE\` — only if you overrode \`table\` on the retriever.
  */
 const TABLE = 'agent_rag_chunks'
 const DIMENSION = 1536

package/dist/stubs/database/migrations/create_agent_tables.stub

@@ -6,36 +6,36 @@ import db from '@adonisjs/lucid/services/db'
 import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
 
 /**
- * The six tables for the @adonis-agora/agent `lucid` store: threads, messages, tool calls, token
+ * The six tables for the @adonis-agora/agent \`lucid\` store: threads, messages, tool calls, token
  * usage, model pricing, and the run lifecycle — plus their indexes.
  *
  * This migration DELEGATES to the library instead of reproducing its DDL. The schema belongs to the
- * library: `LucidAgentStore`, the pricing store and the governance read-model all decide together what
+ * library: \`LucidAgentStore\`, the pricing store and the governance read-model all decide together what
  * columns they read and write, so a hand-copied snapshot here can only ever be right until the next
- * release. It was already wrong in two ways. It reproduced `createTable(...)` with no existence guard,
+ * release. It was already wrong in two ways. It reproduced \`createTable(...)\` with no existence guard,
  * which THROWS on a database where the tables are already there — and they usually are, because
- * `autoCreateTables` defaults to `true` and any of those three stores provisions the shared schema on
+ * \`autoCreateTables\` defaults to \`true\` and any of those three stores provisions the shared schema on
  * its first use. And it took two files to say what the library says in one: a second additive migration
- * existed purely to ALTER in the `run_id` columns this one had been written before.
+ * existed purely to ALTER in the \`run_id\` columns this one had been written before.
  *
- * `createAgentTables` is idempotent (`CREATE TABLE IF NOT EXISTS`) and additive-only: it creates what
- * is missing and ALTERs the `run_id` columns into a database that predates run tracking. So it is safe
+ * \`createAgentTables\` is idempotent (\`CREATE TABLE IF NOT EXISTS\`) and additive-only: it creates what
+ * is missing and ALTERs the \`run_id\` columns into a database that predates run tracking. So it is safe
  * against an empty database, against one the library already auto-created, and against one left over
  * from an older version — which is exactly the set of states a real app is in.
  *
- * `db` (the `Database` manager from `@adonisjs/lucid/services/db`) rather than `this.db`: the manager
+ * \`db\` (the \`Database\` manager from \`@adonisjs/lucid/services/db\`) rather than \`this.db\`: the manager
  * checks out its own connection from the pool, which is what keeps the DDL out of the migrator's
- * transaction (see `disableTransactions` below). `this.db` still supplies the connection NAME, so
- * `node ace migration:run --connection=x` provisions the tables on connection `x` and not on the default.
+ * transaction (see \`disableTransactions\` below). \`this.db\` still supplies the connection NAME, so
+ * \`node ace migration:run --connection=x\` provisions the tables on connection \`x\` and not on the default.
  */
 export default class extends BaseSchema {
   /**
-   * REQUIRED, not a preference. The DDL below runs on a connection the `Database` manager checks out
+   * REQUIRED, not a preference. The DDL below runs on a connection the \`Database\` manager checks out
    * itself — it is not part of the transaction the migrator would otherwise open for this migration.
-   * With `pool: { max: 1 }` (Adonis's own SQLite guidance) that transaction would hold the only
-   * connection while `createAgentTables` waited for a free one, and the migration would hang until the
+   * With \`pool: { max: 1 }\` (Adonis's own SQLite guidance) that transaction would hold the only
+   * connection while \`createAgentTables\` waited for a free one, and the migration would hang until the
    * acquire timeout. Nothing is lost by opting out: the statements were never inside that transaction
-   * anyway, and re-running an interrupted `createAgentTables` is a no-op.
+   * anyway, and re-running an interrupted \`createAgentTables\` is a no-op.
    */
   static disableTransactions = true
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -112,7 +112,8 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -184,6 +185,7 @@
     "@adonisjs/core": "7.4.0",
     "@adonisjs/lucid": "22.4.2",
     "@qdrant/js-client-rest": "1.19.0",
+    "@tanstack/intent": "^0.3.2",
     "@types/node": "22.20.1",
     "@types/react": "19.2.18",
     "ai": "7.0.59",
@@ -208,6 +210,7 @@
     "governance",
     "ai-sdk",
     "durable",
+    "tanstack-intent",
     "agora"
   ],
   "scripts": {

package/skills/agent-governance/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: agent-governance
+description: >-
+  Lock down @adonis-agora/agent: the ActorResolver identity seam (AuthActorResolver over
+  ctx.auth.user with toActor mapper, HeaderActorResolver x-actor-id/x-actor-role behind a
+  gateway, UnconfiguredActorResolver throwing default), DefaultToolAuthorizer role
+  intersection with the offered-tools + invoke-time double check, object-level ownership
+  via evaluateOwnership (404 for unknown ids), governanceAuthorize mounting semantics for
+  /agent/governance/* (404 without it) and the dashboard mount refusals,
+  evaluateGovernanceGate fail-closed behavior, and GET /agent/approvals/mine exemption.
+  Use for "tool forbidden", "governance routes 404", "dashboard won't mount", "IDOR /
+  cross-actor access", "swap roles for ability checks".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/governance/authorization.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/governance/dashboard.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/governance-gate.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/ownership.ts"
+---
+
+# Governance: identity, authorization, ownership
+
+Authorization in `@adonis-agora/agent` is fail-closed at three layers: **who is calling**
+(an `ActorResolver` that never fabricates an identity), **what they may do** (a
+`RolesPolicy` checked twice — before the model sees a tool and again at invoke time),
+and **which records they may address** (object-level ownership on every run/thread route).
+
+## Setup
+
+Wire identity once; everything downstream keys off it:
+
+```ts
+// config/agent.ts
+import { defineConfig, AuthActorResolver } from '@adonis-agora/agent'
+
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  // Reads ctx.auth.user (populated by @adonisjs/auth). Throws when unauthenticated —
+  // no identity is ever invented. Map non-standard user shapes with toActor.
+  actorResolver: new AuthActorResolver({
+    toActor: (user) => ({
+      id: String(user.id),
+      roles: user.roleNames,     // e.g. pulled from a relation
+      tenantRef: user.tenantId,
+    }),
+  }),
+  defaultRoles: ['STAFF'],       // roles a tool requires when it declares none
+})
+```
+
+## Core patterns
+
+### Pattern 1 — swap role checks for ability checks
+
+`roles` and `ability` share one seam. The default policy intersects roles; an
+ability-aware policy (the `@adonis-agora/authz` Bouncer adapter, `authzToolAuthorizer`)
+consults each tool's `ability` instead — tenant-scoped and fail-closed. Swap only the
+binding; tools keep both annotations:
+
+```ts
+// config/agent.ts
+import { defineConfig } from '@adonis-agora/agent'
+import { authzToolAuthorizer } from '@adonis-agora/agent/authz'
+
+export default defineConfig({
+  // ...
+  authorizer: authzToolAuthorizer, // alias: rolesPolicy — one seam, both filter layers follow
+})
+```
+
+Because the offered-tools filter AND the invoke-time re-check call the same
+`can(actor, tool)`, swapping the policy changes both layers together — they can never
+disagree about what an actor may reach.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Ability-aware
+authorization"), `packages/adonis/src/authorizer.ts`.
+
+### Pattern 2 — mount the governance read-model with `governanceAuthorize`
+
+The cross-actor `/agent/governance/*` read routes exist ONLY when a gate is configured.
+Omit it and every one of those paths answers 404 — by design, so an ungated read-model of
+every actor's spend/threads/approvals can never be served by accident:
+
+```ts
+// config/agent.ts — typically an ADMIN check; runs AFTER the actor resolves.
+export default defineConfig({
+  // ...
+  governanceAuthorize: (actor, _ctx) => actor.roles?.includes('ADMIN') ?? false,
+})
+```
+
+`evaluateGovernanceGate` applies it fail-closed: falsy → 403, thrown → 403 (message shown
+only outside production). The SAME predicate feeds object-level ownership's `privileged`
+flag, and the dashboard console refuses to mount without it.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Governance route
+authorization"), `packages/adonis/src/governance-gate.ts`.
+
+### Pattern 3 — unit-test your gates router-free
+
+Both decision cores are exported pure functions, so you can test them without booting an
+app:
+
+```ts
+import { evaluateOwnership, evaluateGovernanceGate } from '@adonis-agora/agent'
+
+evaluateOwnership('u_1', 'u_1', false) // → { ok: true,  status: 200 }  owner
+evaluateOwnership('u_2', 'u_1', false) // → { ok: false, status: 403 }  not owner
+evaluateOwnership('u_2', null, false)  // → { ok: false, status: 404 }  unknown id
+evaluateOwnership('u_2', 'u_1', true)  // → { ok: true,  status: 200 }  privileged
+
+const verdict = await evaluateGovernanceGate(actor, ctx, config.governanceAuthorize, !app.inProduction)
+if (!verdict.ok) return ctx.response.status(verdict.status).json({ error: verdict.error })
+```
+
+Unknown ids deliberately reply 404, never 403, so a response never confirms to a caller
+that an id they don't own exists.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Object-level ownership"),
+`packages/adonis/src/ownership.ts`.
+
+## Common mistakes
+
+### CRITICAL — assuming `HeaderActorResolver` is production-safe
+
+```ts
+// Wrong — anyone can send x-actor-id: u_admin and become admin unless a gateway strips these.
+actorResolver: new HeaderActorResolver()
+```
+
+```ts
+// Correct — read a VERIFIED principal in production; headers are for dev/gateway use only.
+actorResolver: new AuthActorResolver()
+```
+
+Mechanism: `HeaderActorResolver` trusts client-sent `x-actor-id` / `x-actor-role` /
+`x-tenant-ref`; it is safe only behind a gateway that strips and re-sets them from an
+authenticated principal. It does throw when `x-actor-id` is missing, but any caller who
+sets the header IS that actor.
+Source: `packages/adonis/src/actor-resolver.ts` (`HeaderActorResolver` security note),
+`packages/adonis/docs/governance/authorization.mdx`.
+
+### HIGH — expecting `/agent/governance/*` to exist after configuring only `governanceQueries`
+
+```ts
+// Wrong — read-model resolves, but no gate → the 11 governance routes are NEVER mounted (all 404).
+export default defineConfig({ store: 'lucid', stores: { lucid: stores.lucid() } })
+```
+
+```ts
+// Correct — set the gate to mount them (gated); or explicitly opt into open reads.
+export default defineConfig({
+  ...,
+  governanceAuthorize: (actor) => actor.roles?.includes('ADMIN') ?? false,
+  // governanceAuthorize: () => true, // deliberate legacy behaviour: ANY authenticated actor reads
+})
+```
+
+Mechanism: mounting is conditional on the gate because the data is cross-actor; a boot
+warning names both ways forward when the read-model resolved without a gate. Note
+`GET /agent/approvals/mine` is exempt — always mounted when the read-model resolves, and
+always scoped to the calling actor.
+Source: `packages/adonis/src/define_config.ts` (`AgentConfig.governanceAuthorize`),
+`packages/adonis/docs/streaming-and-http.mdx` ("Five optional surfaces").
+
+### HIGH — treating `dashboard.authorize` as the dashboard's data gate
+
+```ts
+// Wrong — authorize gates only the SPA shell; panels still 403/404 without governanceAuthorize.
+dashboard: { enabled: true, authorize: (actor) => actor.roles?.includes('ADMIN') ?? false }
+```
+
+```ts
+// Correct — one predicate shape on BOTH knobs: shell gate + data gate.
+governanceAuthorize: (actor) => actor.roles?.includes('ADMIN') ?? false,
+dashboard: { enabled: true, authorize: (actor) => actor.roles?.includes('ADMIN') ?? false },
+```
+
+Mechanism: the console is a pure consumer of `/agent/governance/*`; `authorize` decides
+who may load the shell while `governanceAuthorize` decides whether the console mounts at
+all and whether its data routes answer. With no gate the provider logs a boot warning and
+refuses to mount rather than serve seven dead panels.
+Source: `packages/adonis/src/dashboard/define_config.ts` (`decideDashboardMount`,
+`NO_GOVERNANCE_GATE_WARNING`).
+
+### MEDIUM — giving a per-agent resolver a different identity than the global one
+
+```ts
+// Wrong — webhook agents resolve actor 'body:svc-1'; the global resolver would say 'user_9'.
+agents: [{ name: 'webhook', actorResolver: new BodyActorResolver() }]
+```
+
+```ts
+// Correct — a per-agent resolver must yield an id the GLOBAL resolver could also produce.
+agents: [
+  {
+    name: 'webhook',
+    actorResolver: new AuthActorResolver({ toActor: mapServicePrincipal }), // same id space
+  },
+]
+```
+
+Mechanism: the override applies ONLY to `POST /agent/chat`; stream re-attach, cancel,
+approve/reject, threads, quota, and all governance routes resolve the GLOBAL resolver —
+a mismatched `actor.id` means the caller starts a run it cannot stream, cancel, or
+approve (ownership compares ids).
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("The override applies
+to POST /agent/chat only").
+
+### MEDIUM — designing a client around a thrown gate's message
+
+```ts
+// Wrong — reading error.message from a 403 to branch UI logic; prod never carries it.
+if (err.message.includes('missing tenant')) showTenantPicker()
+```
+
+```ts
+// Correct — treat 403 as opaque; debug details exist only outside production.
+if (err.status === 403) showForbidden() // body is exactly { "error": "forbidden" } in prod
+```
+
+Mechanism: `evaluateGovernanceGate` passes the thrown message through only when `debug`
+is true (the provider passes `!app.inProduction`); in production the body is the generic
+string, because authorization predicates routinely throw with sensitive detail.
+Source: `packages/adonis/src/governance-gate.ts`, `packages/adonis/docs/governance/authorization.mdx`
+("A thrown message never reaches production clients").
+
+See also: `agent-setup/SKILL.md` — wiring `AuthActorResolver` at setup time;
+`agent-console-client/SKILL.md` — how the console consumes these gated routes.