@agent-native/core 0.127.3 → 0.128.1

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1739
+- core files: 1625
 - toolkit files: 160
-- template files: 6816
+- template files: 6837

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,106 @@
 # @agent-native/core
 
+## 0.128.1
+
+### Patch Changes
+
+- 9140268: Update Builder design-system indexing to call the current `/design-systems/v1/index`
+  endpoint with a structured `sources` array (uploaded files, public repos, connected
+  projects) instead of the retired `generate` endpoint and its flat `uploads` payload.
+  File selections are now attached per source, and the incomplete-response guard only
+  requires a `designSystemId`. "Open in Builder" now links into the actual
+  project/branch (`branchUrl`) when the service returns one, falling back to the
+  design-system-intelligence docs URL. When `/index` returns only a `jobId`, the
+  Fusion branch URL is read from `GET /design-systems/v1/decode-jobs/:jobId`
+  (exposed as `fetchBuilderDesignSystemDecodeJobStatus`) so "Open in Builder" lands
+  on the branch. Large files (notably `.fig`) now stream to
+  storage in 16 MiB resumable chunks with retry and offset recovery instead of a
+  single unbounded request body. Indexing is split into `startBuilderDesignSystemUpload`
+  (opens signed resumable-upload slots) and `indexBuilderDesignSystem` (finalizes from
+  resolved sources) so browsers can stream `.fig` bytes straight to storage and never
+  hit the serverless request-body cap; `startBuilderDesignSystemIndex` still handles
+  small in-memory server-side payloads. Also exports `builderProjectBranchUrl`.
+
+## 0.128.0
+
+### Minor Changes
+
+- ce559da: Add per-app member roles: `defineAppRoles`, an `authorize` gate on `defineAction`, and an `appRoles` column on `TeamPage`.
+
+  Apps that need permissions of their own no longer have to hand-roll a members table or collapse a rich vocabulary into the org's three roles. `defineAppRoles({ appId, roles })` declares an app's role set; `authorize: myApp.requireAny("admin")` gates an action for every caller (agent tool, HTTP, frontend, MCP, A2A, CLI) because it wraps `run` rather than hanging off a flag the dispatchers each have to remember; `<TeamPage appRoles={descriptor} />` adds the assignment column to the existing roster instead of forcing a second members view.
+
+  Org membership stays canonical — an app role only narrows what an existing member may do inside one app. Roles are an unordered set, not a ladder: authorization always names the accepted roles explicitly. `defaultRole` is a display value and never satisfies a guard, membership and assignment resolve in one statement so a stale row cannot authorize, and a failed lookup throws rather than resolving to a deny-shaped status.
+
+### Patch Changes
+
+- ce559da: Keep serverless startup bounded by moving legacy chat-thread repair, global stale-run cleanup, and remote MCP connection setup out of route initialization, and batch additive Postgres schema introspection into one query.
+- ce559da: Keep the hidden-mode agent sidebar on chat when restoring persisted panel state.
+- ce559da: Fix browser live transcription silently freezing mid-recording. `useLiveTranscription` now restarts recognition off the event loop instead of synchronously inside `onend` (Chrome throws `InvalidStateError` there), retries a failed restart with backoff instead of giving up after one throw, and exposes `getIncompleteReason()` so callers can tell a partial capture from a finished one.
+- ce559da: Make two first-run failures explain themselves instead of looking like a broken app.
+
+  The full-screen loading shell now reveals an explanatory line after 10 seconds
+  ("a first run compiles dependencies…, otherwise check the terminal"). The reveal
+  is a pure-CSS `animation-delay`, not a timer, because the states that strand a
+  user on this screen — hydration never running, a route module 404ing, a cold dev
+  compile — are exactly the states where none of our JS executes. A featureless
+  spinner is indistinguishable from a blank page and reads as "the app is broken"
+  rather than "look at the terminal".
+
+  Missing-table database errors now name the likely cause. The driver reports
+  `no such table: x` from whichever query touched it first, so the stack lands in
+  an action and reads as a bug there; the real cause is almost always that no
+  migration created it, which is what a template with no `server/plugins/db.ts`
+  does. The hint is appended to the driver's original message, so existing error
+  classifiers that match its substrings are unaffected.
+
+- ce559da: Stop refusing real deck URLs in A2A responses. The artifact guard only accepted
+  decks from `create-deck`, `duplicate-deck`, `get-deck`, `list-decks`, and
+  `add-slide`, and rejected a `create-deck` that saved an empty deck — so the
+  documented "create empty, then fill" flow, `patch-deck`, `save-deck`,
+  `update-slide`, `import-pptx`, and `restore-deck-version` all produced "I could
+  not verify the deck URL" for decks that were genuinely saved. Any successful
+  result that names a deck (an explicit `deckId`, or a canonical `/deck/<id>` URL
+  the action itself returned) now verifies it.
+- ce559da: Fix the cold-start failure mode that turns a serverless page load into a burst of 502/504s, and stop the chat spinner from hanging forever when the run-status probe is unreachable.
+
+  **Container-killing 502.** `createCoreRoutesPlugin` rethrew after `rejectInit(error)`.
+  Nitro invokes plugins as `try { plugin(app) } catch`, which cannot catch an async
+  rejection, so that rethrow surfaced as an `unhandledRejection`: Node exits, the
+  serverless container dies, and every in-flight request on it returns a bare 502.
+  `rejectInit` already routes the failure to the readiness gate's retryable 503, so
+  the rethrow only destroyed the container.
+
+  **Unbounded readiness gate.** Requests to `/_agent-native/*` waited on plugin
+  bootstrap with no deadline, so a slow cold boot parked them until the platform
+  killed the invocation — the client got nothing it could act on. The gate now
+  releases after `AGENT_NATIVE_ROUTE_READY_TIMEOUT_MS` (default 25s, deliberately
+  below the shortest deployment target's request wall) and answers with a retryable
+  503 instead.
+
+  **155MB function bundles.** Serverless builds copied every platform variant of
+  `@libsql` and `@resvg` into the output — darwin, win32, android and 32-bit arm
+  binaries a Lambda can never execute, ~66MB of dead weight, paid again for each
+  additional emitted function. Cold start scales with bundle size, and a page that
+  opens several requests at once scales out to that many cold containers, which is
+  why this surfaced as 502/504 on a page's first burst rather than as a slow deploy.
+
+  **Eternal "Thinking…".** `AssistantChat` treated a failed `/runs/active` probe as
+  "no active run" and returned early. That probe is the only path that clears the
+  stored active run and no caller reschedules it, so a transient 5xx left the
+  spinner up permanently — surviving reloads, because the stored run lives in
+  `sessionStorage`. It now retries, then clears the stored run and raises a
+  recoverable `run_status_unavailable` error. `activeRunLooksStale` also falls back
+  to the heartbeat when a run was killed before recording any progress, so those
+  runs no longer read as perpetually fresh.
+
+  **Dead tools advertised in production.** `source-search` was registered for the
+  production agent even where its corpus is not deployed, so its only possible
+  answer was "not found". It is now registered only when the corpus exists, and
+  `docs-search` says when framework doc pages are absent from the deployment
+  instead of letting a miss read as "that page does not exist".
+
+- ce559da: Teach visual-edit to open Design in supported inline browser panes and document multi-page, flow, state, and responsive canvas reviews.
+
 ## 0.127.3
 
 ### Patch Changes

package/corpus/core/README.md

@@ -2,7 +2,7 @@
 
 ## The framework for agentic apps
 
-Agent-Native is an open-source framework for rapidly building robust applications with agents at their core.
+Don't pick between apps or agents. Agent-Native apps are both.
 
 ```ts
 // One action powers every app surface: UI, agent, HTTP, MCP, A2A, and CLI.
@@ -22,20 +22,11 @@ export default defineAction({
 - **[Backend agnostic](https://agent-native.com/docs/database)**: Plug in any Drizzle-supported SQL database and Nitro-compatible host.
 - **[Toolkits](https://agent-native.com/docs/agent-native-toolkit)**: Reusable building blocks for collaboration, sharing, settings, teams, and observability.
 
-## Don't pick between apps or agents.
-
-Agent-native apps are both
-
-|                   | SaaS Tools         | Raw AI Agents           | Internal Tools             | Agent-Native App        |
-| ----------------- | ------------------ | ----------------------- | -------------------------- | ----------------------- |
-| **UI**            | Polished but rigid | None                    | Mixed quality              | Full UI, fork & go      |
-| **AI**            | Bolted on          | Powerful                | Shallowly connected        | Agent-first, integrated |
-| **Customization** | Can't              | Instructions and skills | Full, but high maintenance | Agent modifies the app  |
-| **Ownership**     | Rented             | Somewhat yours          | You own the code           | You own the code        |
+https://github.com/user-attachments/assets/ef51644b-6506-46d8-8083-0af7b7e5b65c
 
 ## Try an Agent-Native app
 
-Fork a working app and let the agent evolve it. **You can customize everything.**
+Start from a working app and let the agent evolve it. **You can customize everything.**
 
 <table>
 <tr>
@@ -47,8 +38,6 @@ Fork a working app and let the agent evolve it. **You can customize everything.*
 
 **Agent-Native Loom**
 
-Record your screen with auto-transcripts and captured browser debug logs, share a link, and let an agent read the transcript, see timestamped frames, and fix the bug.
-
 </td>
 <td width="33%" align="center" valign="top">
 
@@ -58,8 +47,6 @@ Record your screen with auto-transcripts and captured browser debug logs, share
 
 **Visual plan mode for coding agents**
 
-Install `/visual-plan` and `/visual-recap` so your coding agent can plan before it builds and recap changes after they land. High-level code reviews with diagrams, wireframes, annotations, and review links.
-
 </td>
 <td width="33%" align="center" valign="top">
 
@@ -69,8 +56,6 @@ Install `/visual-plan` and `/visual-recap` so your coding agent can plan before
 
 **Agent-Native Figma**
 
-Generate interactive HTML prototypes, compare variants, refine controls, and export the result.
-
 </td>
 </tr>
 <tr>
@@ -82,8 +67,6 @@ Generate interactive HTML prototypes, compare variants, refine controls, and exp
 
 **Agent-Native Notion/Obsidian**
 
-Edit local Markdown/MDX files, generate rich interactive custom blocks, and draft, rewrite, or publish with an agent.
-
 </td>
 <td width="33%" align="center" valign="top">
 
@@ -93,8 +76,6 @@ Edit local Markdown/MDX files, generate rich interactive custom blocks, and draf
 
 **Open-Source Alternative to Amplitude and FullStory**
 
-Connect analytics data sources, prompt for real charts, and build reusable dashboards.
-
 </td>
 <td width="33%" align="center" valign="top">
 
@@ -104,13 +85,11 @@ Connect analytics data sources, prompt for real charts, and build reusable dashb
 
 **A minimal ChatGPT-style app for your own agent**
 
-Chat-first app scaffold with durable threads, actions, auth, live sync, and a clean path to add screens or plug in your own agent backend.
-
 </td>
 </tr>
 </table>
 
-View the full app gallery at **[agent-native.com/apps](https://agent-native.com/apps)**, or build from scratch with the **[framework guide](https://agent-native.com/docs/getting-started)**.
+View the [full gallery](https://agent-native.com/apps), or build from scratch with the **[framework guide](https://agent-native.com/docs/getting-started)**.
 
 ## Quick Start
 
@@ -123,7 +102,7 @@ pnpm install
 pnpm dev
 ```
 
-Prefer flags? `create my-app --template mail`, `--headless`, or `--standalone` skip the prompt.
+Prefer flags? `create my-app --template chat`, `--headless`, or `--standalone` skip the prompt.
 
 See the full [getting started docs](https://agent-native.com/docs).
 

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.127.3",
+  "version": "0.128.1",
   "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": {
@@ -338,6 +338,7 @@
     "@assistant-ui/react-markdown": "^0.12.6",
     "@assistant-ui/store": ">=0.2.9 <0.2.14",
     "@assistant-ui/tap": "^0.5.14",
+    "@builder.io/ai-utils": "^0.84.0",
     "@clack/prompts": "^1.4.0",
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/theme-one-dark": "^6.1.3",