@agent-native/core 0.127.3 → 0.128.1

package/dist/templates/chat/.agents/skills/adding-a-feature/SKILL.md

@@ -179,8 +179,15 @@ If the feature stores **user-authored resources** (documents, dashboards, forms,
 
 TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
 
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
 ## Related Skills
 
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)

package/dist/templates/chat/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/dist/templates/chat/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/dist/templates/default/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/dist/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -179,8 +179,15 @@ If the feature stores **user-authored resources** (documents, dashboards, forms,
 
 TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
 
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
 ## Related Skills
 
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)

package/dist/templates/default/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/dist/templates/headless/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -305,6 +305,38 @@ export default defineAction({
 
 On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
 
+### Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
 ### Human-in-the-Loop Approval (`needsApproval`)
 
 For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:

package/dist/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -179,8 +179,15 @@ If the feature stores **user-authored resources** (documents, dashboards, forms,
 
 TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
 
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
 ## Related Skills
 
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)

package/dist/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -71,6 +71,46 @@ The auto-create path skips users with pending invites or a matching
 `AUTO_CREATE_DEFAULT_ORG=0` only for deployments that intentionally want manual
 org creation.
 
+### App-Specific Roles
+
+When a request needs "only some teammates may do this **inside this app**", the
+answer is per-app roles — **not** a second organization. App roles are an
+overlay on the one org membership, never a second roster. Three role systems
+coexist and never imply one another: the org role (`org_members.role`) says what
+a person may do to the *team*, an app role says what they may do inside *one
+app*, and a share role (`sharing` skill) says what they may do to *one row*. An
+app `admin` is not an org admin, and org handlers never read app roles.
+
+Declare the vocabulary once on the server and guard actions with it:
+
+```ts
+import { defineAppRoles } from "@agent-native/core/org-team";
+
+export const coachAccess = defineAppRoles({
+  appId: "coach",
+  roles: ["member", "coach-admin"] as const,
+  defaultRole: "member",
+});
+
+// in an action
+authorize: coachAccess.requireAny("coach-admin"),
+```
+
+Roles are an unordered set, not a ladder — declaration order carries no meaning,
+and every guard names its accepted roles explicitly. `defaultRole` is **display
+only**: `requireAny` matches an explicit assignment row and nothing else, so
+"nobody assigned this person" never reads as "granted", and widening the default
+cannot silently widen a guard. Org membership is a precondition, resolved in the
+same statement as the assignment, so a leftover assignment for a removed member
+can never authorize. Only org owners/admins may assign app roles; render the
+picker with `<TeamPage appRoles={descriptor} />`.
+
+`requireAny` validates at definition time — no roles, or a role outside the
+declared vocabulary, throws when the module loads rather than surfacing as an
+unexplained 403 later. When calling `resolve`/`assertAny` directly, note that an
+explicit `userEmail: null` / `orgId: null` means "this run has no identity" and
+does **not** fall back to the ambient request context; only `undefined` does.
+
 ### Stop And Confirm Before Creating Or Switching Organizations
 
 Vault credentials are scoped per organization and are **not** shared between

package/dist/templates/workspace-core/.agents/skills/security/SKILL.md

@@ -159,6 +159,35 @@ whole site. Data scoping lives in actions and API routes; the client gates
 private UI after the shell loads. See the `authentication` skill and
 `guard:ssr-cache-shell` / `ssr-handler.spec.ts`.
 
+**Authorization beyond "is there a session" — `authorize`.** The auth guard only
+proves *someone* is signed in. To restrict an operation to some teammates, set
+`authorize` on the `defineAction`. It wraps `run`, so it applies at every
+dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
+`needsApproval`, which is honoured only in the agent loop.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. Guarded actions need
+a user identity — an unattended CLI/cron caller with no user email is denied.
+
+`authorize` is **not** a substitute for `accessFilter` / `assertAccess`. It
+decides whether this caller may perform the operation at all; `accessFilter` /
+`assertAccess` scope which rows a permitted caller may see or touch. A
+restricted write action needs both. See the `authentication` skill for
+`defineAppRoles` and the `actions` skill for the full surface.
+
 ## Human-in-the-Loop Approval for High-Consequence Actions
 
 For a small set of outward-facing, hard-to-undo operations — sending an email, charging a card, deleting an account, posting publicly — auth and access control are necessary but not sufficient: you also do not want the **agent** to perform them autonomously. Set `needsApproval` on the `defineAction` so the agent cannot run the action without a human approving the specific call.
@@ -274,6 +303,8 @@ Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org
 - [ ] New env vars in `.env` only, not committed
 - [ ] New user-data tables have `owner_email` column
 - [ ] Custom routes call `getSession` and reject unauthenticated requests
+- [ ] Actions only some teammates may run set `authorize` (in addition to any
+      `accessFilter` / `assertAccess` row scoping)
 
 ## Related Skills
 

package/dist/templates/workspace-core/.agents/skills/sharing/SKILL.md

@@ -34,6 +34,8 @@ Visibility is coarse. Explicit share grants are fine-grained (per user or per or
 - **`editor`** — read + write.
 - **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
 
+There are three role systems and they never imply one another. A share role answers "what may this person do to **one row**". An org role (`org_members.role`) answers "what may this person do to the **team**". An app role (`defineAppRoles`, see the `authentication` skill) answers "what may this person do inside **one app**". A share `admin` is not an app admin and neither is an org admin.
+
 ### Anonymous public URLs stay separate
 
 Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
@@ -137,6 +139,8 @@ export default defineAction({
 
 For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
 
+`authorize` is a different axis, not an alternative: it gates whether the caller may run the operation at all, while `assertAccess` scopes which row they may touch. A write action restricted to some teammates needs both — `authorize: appAccess.requireAny(...)` on the action, `assertAccess` inside `run`.
+
 ## Create actions must set owner
 
 When inserting a new row, fill `ownerEmail` and `orgId` from the request context:

package/docs/content/actions.mdx

@@ -94,7 +94,8 @@ For App Operations](/docs/server#actions-first).
 
 On this page: [Start with one action](#hello-action), [Defining an action](#defining),
 [Run context](#run-context), [Access control](#access-control),
-[Human-in-the-loop approval](#needs-approval), [Audit logging](#audit),
+[Authorization](#authorize), [Human-in-the-loop approval](#needs-approval),
+[Audit logging](#audit),
 [Calling from the UI](#ui), [Native chat UI](#native-chat-ui),
 [Calling from the CLI](#cli), [A2A](#a2a), [MCP](#mcp),
 [Standard actions](#standard-actions), and [Feature flags](#feature-flags).
@@ -258,7 +259,7 @@ POST by default; `http: { method: "GET" }` makes it a GET. The React hooks and `
 - **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — default `POST`. `GET` actions are auto-marked `readOnly` so successful calls don't trigger a UI poll-refresh.
 - **`http: { path: "..." }`** — override the mounted URL under `/_agent-native/actions/`. Defaults to the filename. **Path overrides change the URL only for direct HTTP callers** — `useActionQuery`, `useActionMutation`, and `callAction` always call `/_agent-native/actions/<name>` regardless of this override, so overriding the path makes those hooks 404. Use path overrides only for external HTTP callers. Note also that `:param` route segments in the override path are **not** parsed into `run()` args — only query-string params and JSON body fields are.
 - **`http: false`** — disable the HTTP endpoint entirely. Agent + CLI only.
-- **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate.
+- **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate. It is **not** access control: it does not restrict who may call the action, and it does not affect `useActionQuery`, `useActionMutation`, or any client hook. Its only effects are suppressing the post-call refresh event and opting the action out of write-auditing. To hide an action from the model use `agentTool: false`; to gate callers use the auth/access options above.
 - **`parallelSafe: true`** — allow a mutating action to run concurrently with other same-turn tool calls. Only set this when the action is internally concurrency-safe and order-independent; mutating actions serialize by default.
 
 ### Keep the action surface small {#small-surface}
@@ -274,7 +275,7 @@ A repo-level advisory helper, `node scripts/audit-template-actions.mjs [template
 
 ### Exposure flags {#exposure-flags}
 
-Four flags control _who_ can invoke an action. All default to the permissive value, so you only set one to tighten a specific surface. This table is the glanceable summary; the subsections add the one detail each needs.
+Five flags control _who_ can invoke an action. All default to the permissive value, so you only set one to tighten a specific surface. This table is the glanceable summary; the subsections add the one detail each needs.
 
 | Flag            | Default       | Restrictive value → who can still call                                      | Typical use                                                     |
 | --------------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
@@ -282,8 +283,9 @@ Four flags control _who_ can invoke an action. All default to the permissive val
 | `toolCallable`  | `true`        | `false` → everything **except** the sandboxed extension iframe bridge (403) | Auth-adjacent ops (delete account, change org membership/roles) |
 | `publicAgent`   | off (private) | `{ expose: true }` → adds the action to **public** MCP/A2A/OpenAPI surfaces | Safe read/ingest tools reachable without authentication         |
 | `needsApproval` | `false`       | `true` → the agent **pauses**; a human must approve the specific call       | Consequential side effects (send email, charge a card, delete)  |
+| `authorize`     | none          | a guard function → only callers it accepts, on **every** surface            | Operations restricted to a role (per-app RBAC, admin-only ops)  |
 
-These are independent: `agentTool` controls the model's view, `toolCallable` controls only the extension iframe, `publicAgent` adds an opt-in public surface (public web routes never imply public tool exposure), and `needsApproval` gates execution after the call is made — see [Human-in-the-loop approval](#needs-approval) below.
+These are independent: `agentTool` controls the model's view, `toolCallable` controls only the extension iframe, `publicAgent` adds an opt-in public surface (public web routes never imply public tool exposure), `needsApproval` gates execution after the call is made — see [Human-in-the-loop approval](#needs-approval) below — and `authorize` decides whether this caller may run the action at all, on every dispatch path, before `run` is entered — see [Authorization](#authorize).
 
 #### `agentTool` — hide from the model {#agent-tool}
 
@@ -403,6 +405,47 @@ export default defineAction({
 
 For list and read actions, use `accessFilter` to scope the query to the current user and org. For actions that update or delete a specific row, use `assertAccess` to confirm the caller is allowed before writing. See [Security](/docs/security#access-guards) and [Sharing](/docs/sharing) for the full helper API.
 
+### Authorization {#authorize}
+
+`accessFilter` / `assertAccess` scope _which rows_ a permitted caller may touch. `authorize` answers the question before that one: **may this caller run this operation at all?** Give it a guard function and it runs before `run()` on every caller — agent tool, HTTP, frontend, MCP, A2A, and CLI:
+
+```ts
+import { coachAccess } from "../server/lib/access.js";
+
+export default defineAction({
+  description: "Archive a training plan.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async ({ id }) => {
+    /* ... */
+  },
+});
+```
+
+The guard wraps `run` itself rather than hanging off the action entry, because `run` is the one thing all six dispatch sites go through — there is no caller that can reach the body without passing the check. A guard that throws denies with its own message; one that returns `false` denies with a generic 403; anything else, including `undefined`, allows. Because the gate needs a caller identity, an unattended CLI or cron invocation with no user email is denied rather than waved through.
+
+The wrappers compose in this order:
+
+```text
+validate input -> authorize -> run -> validate output -> audit
+```
+
+Authorization sits _inside_ input validation, so a guard that inspects `args` is handed the parsed, coerced value its type promises rather than whatever shape the caller sent. Auditing is outermost, so a denial is still recorded.
+
+`requireAny` fails at definition time, not at request time: calling it with no roles, or with a role outside the declared vocabulary, throws when the module loads. `authorize: coachAccess.requireAny()` is a dropped argument, and it should break where the mistake is rather than surface later as an unexplained 403.
+
+The three mechanisms are not interchangeable:
+
+| Mechanism                     | Question it answers                                | Applies to                  |
+| ----------------------------- | -------------------------------------------------- | --------------------------- |
+| `authorize`                   | May this caller perform the operation at all?      | All six dispatch sites      |
+| `needsApproval`               | Should a human bless this specific permitted call? | The agent loop only         |
+| `accessFilter`/`assertAccess` | Which rows may this permitted caller see or write? | Inside `run`, per query/row |
+
+A restricted write action typically needs both `authorize` and `assertAccess`: the first keeps non-coaches out of the operation, the second keeps a coach out of another org's plan. `needsApproval` is a separate axis again — it never restricts _who_ may call, only whether the agent may proceed unattended.
+
+`coachAccess` above comes from `defineAppRoles`, the per-app role overlay on org membership. See [Organizations, Teams & Permissions → App roles](/docs/organizations-teams-permissions#app-roles-per-app-rbac) for the role model and its guarantees.
+
 ### Human-in-the-loop approval {#needs-approval}
 
 A handful of actions are too consequential to let the agent run autonomously — sending an email, charging a card, deleting an account. Set `needsApproval: true` (or a predicate `(args, ctx) => boolean | Promise<boolean>`) on `defineAction` and the loop pauses before `run()`, requiring a human to approve that specific call. The default is **off**, and almost every action should stay that way.

package/docs/content/native-chat-ui.mdx

@@ -246,6 +246,13 @@ export default defineAction({
 Use this for first-party app UI. Keep cross-host iframe UI in `mcpApp`, and keep
 arbitrary query execution behind typed read actions rather than raw SQL in chat.
 
+Size renderers in absolute units, not percentages. The transcript grows to fit
+its messages, so a renderer's container has no definite height to resolve a
+percentage against — `height: 40%` on a chart bar collapses to zero rather than
+erroring, which reads as a renderer that failed to draw. Give charts and other
+height-driven visuals a pixel (or `rem`) basis; widths are fine as percentages
+because the transcript column does have a definite width.
+
 ## BYO agent runtimes {#byo-agent-runtimes}
 
 `AgentChatRuntime` is the bring-your-own-agent contract for the chat shell, and

package/docs/content/organizations-teams-permissions.mdx

@@ -41,8 +41,8 @@ server-side action or access guard must enforce the rule.
 ## Organizations and teams
 
 Every scaffold includes the framework's own `org/` module. It is backed by
-`organizations`, `org_members`, and `org_invitations`; it is not Better Auth's
-organization plugin. The built-in flow supports:
+`organizations`, `org_members`, `org_invitations`, and `app_member_roles`; it is
+not Better Auth's organization plugin. The built-in flow supports:
 
 - Creating an organization. The creator becomes the `owner`.
 - Inviting people as `member` or `admin` and accepting invitations.
@@ -64,6 +64,8 @@ routes are:
 | `GET /_agent-native/org/members`                 | List members in the active organization                         |
 | `DELETE /_agent-native/org/members/:email`       | Remove a member                                                 |
 | `PUT /_agent-native/org/members/:email/role`     | Change a member's role                                          |
+| `GET /_agent-native/org/app-roles?appId=X`       | An app's role vocabulary plus its assignments in the active org |
+| `PUT /_agent-native/org/app-roles/:email`        | Assign or clear one member's app role (owner/admin only)        |
 | `GET /_agent-native/org/invitations`             | List pending invites                                            |
 | `POST /_agent-native/org/invitations`            | Invite one or more people                                       |
 | `POST /_agent-native/org/invitations/:id/accept` | Accept an invitation                                            |
@@ -91,7 +93,8 @@ export function AppShell() {
 export function TeamSettings() {
   return (
     <RequireActiveOrg>
-      <TeamPage />
+      {/* `appRoles` is optional — see App roles below */}
+      <TeamPage appRoles={coachRoles} />
     </RequireActiveOrg>
   );
 }
@@ -162,11 +165,114 @@ The same helpers are available from
 client checks as progressive disclosure only; repeat the authorization check
 in the server action or route that changes org state.
 
+## App roles (per-app RBAC)
+
+App roles answer: **what may this person do inside _one app_?**
+
+An organization role is a statement about the team, and a resource role is a
+statement about a row. Neither can express "Dana runs the coaching program, but
+is an ordinary member everywhere else." App roles are that overlay: an
+app-defined vocabulary layered on the org roster, stored in `app_member_roles`
+and edited from the same team surface. They are not a second roster — do not
+create another organization to get app-specific permissions.
+
+Declare the vocabulary once in app source, then guard actions with an explicit
+list of accepted roles:
+
+```ts
+// server/lib/access.ts
+import { defineAppRoles } from "@agent-native/core/org-team";
+
+export const coachAccess = defineAppRoles({
+  appId: "coach",
+  roles: ["member", "coach-admin"] as const,
+  defaultRole: "member", // display only — never satisfies a guard
+  label: "Coach role", // column header in TeamPage
+  roleLabels: { "coach-admin": "Coach admin" },
+});
+```
+
+```ts
+// actions/archive-plan.ts
+export default defineAction({
+  description: "Archive a training plan.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async ({ id }) => {
+    /* ... */
+  },
+});
+```
+
+Against `requireAny("coach-admin")`, the caller resolves to exactly one of:
+
+| Caller                                     | `resolve()` status | Passes the guard              |
+| ------------------------------------------ | ------------------ | ----------------------------- |
+| Org member assigned `coach-admin`          | `assigned`         | Yes                           |
+| Org member assigned `member`               | `assigned`         | No — not in the accepted list |
+| Org member with no assignment row          | `unassigned`       | No, even with a `defaultRole` |
+| Signed-in user who is not in this org      | `not-a-member`     | No                            |
+| Request with no active organization        | `no-org`           | No                            |
+| Unattended caller with no user (CLI, cron) | `no-identity`      | No                            |
+
+The caveats that make this safe to build on:
+
+- **Roles are an unordered set, not a ladder.** Declaration order carries no
+  meaning; `["ae", "se", "csm"]` are classifications, and ranking them would
+  silently grant the last one everything the first one has. Authorization is
+  always an explicit accepted-role list, never "at least".
+- **`defaultRole` is display only.** `requireAny` matches an explicit
+  assignment row and nothing else. If the default satisfied a guard, "nobody
+  has assigned this person" and "this person was granted the role" would be the
+  same answer, and later widening the default would silently widen every guard
+  that names it.
+- **Org membership is a precondition.** Membership and assignment resolve in
+  one SQL statement, so an assignment left behind by a removed member can never
+  authorize.
+- **A failed lookup throws.** It is not one of the deny statuses above: a
+  database error is not an answer, and reporting it as a denial would look
+  exactly like a legitimate one.
+- **`requireAny` validates at definition time.** Calling it with no roles, or
+  with a role outside the declared vocabulary, throws when the module loads —
+  a dropped argument breaks where the mistake is instead of surfacing later as
+  an unexplained 403 in production.
+- **An explicit `null` caller is not "unspecified".** `resolve({ userEmail:
+null })` means "this run has no user" and does not fall back to the ambient
+  request context; only `undefined` does. Collapsing the two would let a system
+  or cron caller that deliberately declared no identity inherit whichever
+  request happens to be on the stack and authorize as that person.
+- **`appId` comes from trusted server config, never from the request.** The
+  REST layer resolves descriptors out of the `defineAppRoles` registry and 404s
+  an app id the server never declared.
+- **An app admin is not an org admin.** Only org owners and admins may change
+  app-role assignments, and nothing in the org handlers reads an app role. The
+  implication does not run in either direction.
+
+In the browser, `<TeamPage appRoles={coachRoles} />` adds a role column and
+picker next to the org role. The argument is the descriptor — the serializable
+half of the declaration, free of database imports — so hoist that object literal
+into a shared module as `coachRoles`, hand it to `defineAppRoles` on the server,
+and pass the same object to `TeamPage`. Passing `coachAccess` itself would drag
+the database into the browser bundle. To read the current user's own role:
+
+```tsx
+import { useAppRole } from "@agent-native/core/client/org-team";
+
+const { role } = useAppRole("coach");
+```
+
+`useAppRoles`, `useAppRole`, and `useSetAppMemberRole` are progressive
+disclosure only. Every guarded operation re-resolves the role on the server, so
+a client that shows the wrong affordance still cannot perform the operation.
+See [Actions → Authorization](/docs/actions#authorize) for how `authorize`
+differs from `needsApproval` and from row-level access guards.
+
 ## Resource permissions (sharing RBAC)
 
 Organization roles and resource roles are different systems:
 
 - **Organization role** controls team administration.
+- **App role** controls what a member may do inside one app.
 - **Resource role** controls access to one document, dashboard, or other
   shareable row.