@agent-native/core 0.127.1 → 0.128.0

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.
 

package/docs/content/template-design-collaboration-and-full-apps.mdx

@@ -11,6 +11,21 @@ Once a prototype is in good shape, this page covers what happens next: pulling i
 
 Design isn't only for prototypes generated from a prompt — a coding agent can install `/visual-edit` to bring a real, already-running local app into Design as its own screens. Each requested path or URL becomes its own screen on the canvas, and a numbered flow (an onboarding step 1, 2, 3) stays as separate ordered screens instead of collapsing into one. The entry route renders before sign-in, and a shared design link works read-only without an account — but saving the layout, generating new screens, or sharing still requires signing in first.
 
+### Keep the canvas beside your chat
+
+When your coding app has an inline browser, ask `/visual-edit` to open the returned Design URL there. In Codex Desktop, that means the built-in Browser; in Claude Code Desktop's Code tab, it means the Browser pane. Both can keep the canvas inside the coding app beside the conversation. In VS Code, the Agent Native extension opens the same Design URL in its side-panel webview. Browser panes can be disabled or unavailable in CLI, remote, or restricted sessions, so `/visual-edit` falls back to an **Open design** link instead of claiming the canvas opened.
+
+Once Design is open, choose **Show/Hide UI** from the `Cmd+K` menu or press `Cmd+Shift+\` on Apple devices / `Ctrl+Shift+\` elsewhere to toggle all editing chrome so only the canvas remains. The same action is available by right-clicking empty canvas space.
+
+These are especially useful canvas sets:
+
+- **A multi-step flow:** `/visual-edit localhost:5173 — cart, shipping, payment, confirmation; open it beside this chat`
+- **Several pages:** `/visual-edit localhost:5173 — home, pricing, docs, and settings`
+- **One page at several sizes:** `/visual-edit localhost:5173/dashboard — desktop, tablet, and mobile side by side`
+- **Several states of one page:** `/visual-edit localhost:5173/inbox — empty, selected, and compose-open states`
+
+The agent keeps named steps in order and places responsive variants in aligned columns, so the canvas reads like a flow or comparison board rather than a pile of screenshots. Name the routes and sizes you care about; requesting every discovered route at every viewport can create a noisy canvas.
+
 <Diagram id="doc-block-design8" title="Three source modes" summary={"A design's source is inline, localhost, or fusion — the mode decides where an edit actually lands."}>
 
 ```html

package/docs/content/toolkit-org-team.mdx

@@ -21,17 +21,21 @@ connections, service tokens, and app switching.
 
 ## Pieces {#pieces}
 
-| Piece                 | Purpose                                                                                         |
-| --------------------- | ----------------------------------------------------------------------------------------------- |
-| `<TeamPage>`          | Standard team management page for members, invites, roles, and organization preferences.        |
-| `<OrgSwitcher>`       | Current organization picker for sidebars and headers.                                           |
-| `<InvitationBanner>`  | One-click invite and domain-match join prompts.                                                 |
-| `<RequireActiveOrg>`  | Guard for pages that need an active organization before rendering app data.                     |
-| `useOrgRole()`        | Shared role booleans for member, invite, settings, and domain controls.                         |
-| Organization handlers | Create, rename, switch, invite, accept, remove, and update roles/domains.                       |
-| Roles                 | Owner, admin, and member gates for sharing, settings, service tokens, and provider connections. |
-| Allowed domains       | Automatic join and domain-scoped access policy.                                                 |
-| App links             | Workspace app-link parsing and visible app-switcher helpers.                                    |
+| Piece                   | Purpose                                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `<TeamPage>`            | Standard team management page for members, invites, roles, and organization preferences.        |
+| `<OrgSwitcher>`         | Current organization picker for sidebars and headers.                                           |
+| `<InvitationBanner>`    | One-click invite and domain-match join prompts.                                                 |
+| `<RequireActiveOrg>`    | Guard for pages that need an active organization before rendering app data.                     |
+| `useOrgRole()`          | Shared role booleans for member, invite, settings, and domain controls.                         |
+| `appRoles` prop         | Adds a per-app role column and picker to `<TeamPage>` from a `defineAppRoles` descriptor.       |
+| `useAppRoles()`         | An app's role vocabulary, its assignments in the active org, and whether the viewer may edit.   |
+| `useAppRole()`          | The current user's role in one app, or `null` when unassigned.                                  |
+| `useSetAppMemberRole()` | Assign or clear one member's app role. Org owner/admin only, enforced server-side.              |
+| Organization handlers   | Create, rename, switch, invite, accept, remove, and update roles/domains.                       |
+| Roles                   | Owner, admin, and member gates for sharing, settings, service tokens, and provider connections. |
+| Allowed domains         | Automatic join and domain-scoped access policy.                                                 |
+| App links               | Workspace app-link parsing and visible app-switcher helpers.                                    |
 
 ## API {#api}
 
@@ -66,12 +70,68 @@ export function AdminOnlyControl() {
 
 Server code imports the same role helpers from `@agent-native/core/org-team`.
 The route plugin mounts `/_agent-native/org/*` for org creation, switching,
-invites, domains, member roles, and A2A secret sync.
+invites, domains, member roles, app roles, and A2A secret sync.
+
+### Per-app roles {#app-roles}
+
+When an app needs its own permission vocabulary on top of team membership,
+declare it with `defineAppRoles` and pass the descriptor to `TeamPage`. The
+descriptor is the serializable half of the declaration — no database imports —
+so the same object can be handed to `defineAppRoles` on the server and to the
+component in the browser bundle:
+
+```tsx
+import {
+  RequireActiveOrg,
+  TeamPage,
+  useAppRole,
+  useAppRoles,
+  useSetAppMemberRole,
+} from "@agent-native/core/client/org-team";
+import { coachRoles } from "../shared/coach-roles";
+
+export function SettingsTeamTab() {
+  return (
+    <RequireActiveOrg>
+      <TeamPage appRoles={coachRoles} />
+    </RequireActiveOrg>
+  );
+}
+
+export function CoachOnlyControl() {
+  const { role } = useAppRole("coach");
+  return role === "coach-admin" ? <button type="button">Archive</button> : null;
+}
+
+export function RoleAdmin() {
+  const { data } = useAppRoles("coach");
+  const setRole = useSetAppMemberRole("coach");
+  if (!data?.canManage) return null;
+  return (
+    <button
+      type="button"
+      onClick={() => setRole.mutate({ email: "dana@acme.com", role: null })}
+    >
+      Clear role
+    </button>
+  );
+}
+```
+
+`role`, `myRole`, and `canManage` are progressive disclosure only. The server
+re-resolves the caller's app role on every guarded operation, and assignment
+edits require the org `owner`/`admin` role regardless of what the client
+believes. See
+[Organizations, Teams & Permissions → App roles](/docs/organizations-teams-permissions#app-roles-per-app-rbac)
+for the role model and [Actions → Authorization](/docs/actions#authorize) for
+the server-side `authorize` guard.
 
 ## UX Standard {#ux-standard}
 
 - Users can see which organization they are in before creating or sharing data.
 - Invites and roles live in the team settings surface, not per-resource dialogs.
+- App-specific roles appear as another column on that same team surface, never
+  as a separate permissions page or a second organization.
 - Org domain changes are owner-only and explain who can auto-join.
 - App switching lists workspace/default app links. Active-org continuity comes
   from the target app sharing the same auth and organization state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.127.1",
+  "version": "0.128.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {