@agent-native/core 0.161.23 → 0.163.0

package/corpus/templates/forms/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/corpus/templates/macros/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It polls every 2 seconds only while an agent run is in flight; otherwise it idles at 60 seconds whether or not SSE is connected (`SSE_FALLBACK_INTERVAL_MS` and `IDLE_POLL_INTERVAL_MS`, both 60 s). A hidden tab polls no faster than every 10 seconds (`HIDDEN_POLL_INTERVAL_MS`). Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/macros/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It polls every 2 seconds only while an agent run is in flight; otherwise it idles at 60 seconds whether or not SSE is connected (`SSE_FALLBACK_INTERVAL_MS` and `IDLE_POLL_INTERVAL_MS`, both 60 s). A hidden tab polls no faster than every 10 seconds (`HIDDEN_POLL_INTERVAL_MS`). Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/mail/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/corpus/templates/mail/app/components/layout/AppLayout.tsx

@@ -11,7 +11,10 @@ import { openCommandMenu } from "@agent-native/core/client/navigation";
 import { InvitationBanner, OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
 import { SidebarFooterActions } from "@agent-native/toolkit/app-shell";
-import { normalizeMailLabel } from "@shared/gmail-labels";
+import {
+  isInboxScopedAppLabel,
+  normalizeMailLabel,
+} from "@shared/gmail-labels";
 import type { Label } from "@shared/types";
 import {
   IconMenu2,
@@ -171,6 +174,18 @@ function labelDepth(name: string): number {
   return Math.max(0, name.split("/").length - 1);
 }
 
+// Gmail's inbox-only categories (important, social, promotions, ...) only
+// ever exist inside the inbox, so their tab stays scoped there. Regular user
+// labels are filed/archived independently of the inbox — routing them
+// through /inbox forces `in:inbox` server-side and hides every message the
+// user has archived out of the inbox while keeping the label, which reads as
+// "label is empty" even though it has mail. Route those through /all so the
+// label search is unscoped.
+export function labelTabHref(labelId: string): string {
+  const view = isInboxScopedAppLabel(labelId) ? "inbox" : "all";
+  return `/${view}?label=${encodeURIComponent(labelId)}`;
+}
+
 interface AppLayoutProps {
   children: React.ReactNode;
 }
@@ -590,7 +605,7 @@ function AppLayoutInner({ children }: AppLayoutProps) {
           pinnedId: id,
           label: aliasedName,
           fullLabel: lbl.name,
-          href: `/inbox?label=${encodeURIComponent(lbl.id)}`,
+          href: labelTabHref(lbl.id),
           isActive: activeLabel === lbl.id,
           color: lbl.color,
           type: "label",
@@ -630,7 +645,7 @@ function AppLayoutInner({ children }: AppLayoutProps) {
           id: active.id,
           label: aliasedName,
           fullLabel: active.name,
-          href: `/inbox?label=${encodeURIComponent(active.id)}`,
+          href: labelTabHref(active.id),
           isActive: true,
           color: active.color,
           type: "label",

package/corpus/templates/mail/server/handlers/google-auth.ts

@@ -58,23 +58,16 @@ function googleOAuthErrorPayload(
   message: string;
   code?: string;
   accountId?: string;
-  existingOwner?: string;
-  attemptedOwner?: string;
 } {
   if (
     error instanceof OAuthAccountOwnedByOtherUserError ||
     error?.name === "OAuthAccountOwnedByOtherUserError"
   ) {
     const account = error.accountId || "This Google account";
-    const existingOwner = error.existingOwner || undefined;
-    const attemptedOwner = error.attemptedOwner || undefined;
-    const message = `${account} is connected to another login. Sign out, then sign in with ${account}.`;
     return {
-      message,
+      message: `${account} is already connected to another login. Sign out, then sign in with the login that originally connected it.`,
       code: "account_owner_mismatch",
       accountId: error.accountId,
-      existingOwner,
-      attemptedOwner,
     };
   }
 

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It polls every 2 seconds only while an agent run is in flight; otherwise it idles at 60 seconds whether or not SSE is connected (`SSE_FALLBACK_INTERVAL_MS` and `IDLE_POLL_INTERVAL_MS`, both 60 s). A hidden tab polls no faster than every 10 seconds (`HIDDEN_POLL_INTERVAL_MS`). Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/plan/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/corpus/templates/slides/.agents/skills/create-deck/SKILL.md

@@ -25,6 +25,10 @@ Context, reference deck, or source material that the app already provides.
 5. Navigate to the new deck.
 6. Call `add-slide` once per slide in slide order, waiting for each result.
 
+When speaker notes are requested, put presenter-only text in each slide's
+`notes` field on `create-deck` or `add-slide`; keep it out of the slide HTML.
+Preserve existing notes when editing or importing a source deck.
+
 When the UI has already created the empty deck, keep its id and rename it before
 adding the first slide. Call `patch-deck` with a `patch-deck-fields` operation
 whose `fields.title` is the generated title. Do not leave the pre-created deck's

package/corpus/templates/slides/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It polls every 2 seconds only while an agent run is in flight; otherwise it idles at 60 seconds whether or not SSE is connected (`SSE_FALLBACK_INTERVAL_MS` and `IDLE_POLL_INTERVAL_MS`, both 60 s). A hidden tab polls no faster than every 10 seconds (`HIDDEN_POLL_INTERVAL_MS`). Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/slides/.agents/skills/sharing/SKILL.md

@@ -18,6 +18,11 @@ Any resource a user **creates** (dashboards, documents, forms, decks, compositio
 
 This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
 
+Workspace apps are the intentional organization-scoped exception: their default
+visibility is `org`, configurable by an organization owner/admin. The creator is
+stored as the app owner, and the creator or an organization owner/admin can
+change the app's visibility or manage its share grants.
+
 ## Concepts
 
 ### Three visibility levels
@@ -26,7 +31,8 @@ This is the framework-level primitive. Every ownable resource gets it for free
 - **`org`** — owner + explicit grants + anyone in the same org (read-only).
 - **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
 
-Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+Visibility is coarse. Explicit share grants are fine-grained (per user, reusable
+organization group, or per org).
 
 ### Roles on a share grant
 
@@ -101,6 +107,7 @@ registerShareableResource({
   // ...
   allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
   requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+  supportsGroupShares: true, // enable reusable organization groups for this resource
 });
 ```
 
@@ -111,6 +118,21 @@ Use both for resources that execute code or expose privileged data with the *vie
 
 Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
 
+### Reusable organization groups
+
+The workspace organization model stores reusable groups in
+`workspace_user_groups`. Organization owners/admins manage the groups and their
+members through the existing group actions. Set `supportsGroupShares: true` on a
+resource registration to enable `principalType: "group"` in the generic share
+actions and the shared popover's autocomplete. Group ids are always checked
+against the resource's organization, and membership is evaluated at access time
+so group changes apply to existing shares.
+
+Workspace apps opt into this flag and use the organization default visibility
+setting. The app creator is the durable `owner_email`, while organization
+owners/admins receive admin access through the registration's
+`canManageAccess` callback.
+
 ## Filter list/read queries
 
 ```ts
@@ -197,6 +219,9 @@ All app share popovers should use the same compact surface contract:
 - Add `ShareAgentsSection` only when the resource has a real agent-readable
   link or prompt. Keep it collapsed by default and supply domain-specific
   content through the shared section shell.
+- When `supportsGroupShares` is enabled, keep the existing people input as the
+  only entry point and include organization groups in its autocomplete. Do not
+  add a separate group-management surface to each resource.
 - App-specific tabs or controls may remain when they represent a real domain
   action (for example, an embed-code editor), but they should retain the same
   trigger, copy-row, access, and spacing language.
@@ -211,7 +236,7 @@ The framework auto-mounts these actions in every template — no per-template bo
 
 | Action                     | Args                                                                           | Purpose                                   |
 | -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
-| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?, message?` | Grant a user, group, or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link and `message` an optional short note for the notification email. |
 | `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
 | `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
 | `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |

package/corpus/templates/slides/actions/_await-fit-check.ts

@@ -94,15 +94,40 @@ export function formatOverflowForTool(
   deckId: string,
   m: SlideFitMeasurement,
 ): string {
+  const hasHorizontal = (m.horizontalOverflow ?? 0) > 0;
+  const hasVertical = m.verticalOverflow > 0;
+
+  // A row of side-by-side cards/columns that's too wide is a *width formula*
+  // bug (fixed px flex-basis, a wrong container-width assumption, a missing
+  // `min-width: 0`), not a density bug. The old list was vertical-only —
+  // "tighten copy" / "fewer stacked cards" — which cannot shrink a fixed
+  // column width no matter how many times it's applied, so a horizontal
+  // overflow looped forever against fixes that could never touch the actual
+  // defect (see the Oliver Robertson Slack thread this regression test
+  // reproduces).
+  const fixes = [
+    ...(hasHorizontal
+      ? [
+          `Use percentage or flex-based column widths (e.g. \`flex: 1 1 0%\` with \`min-width: 0\`, or \`width: calc((100% - <gaps>) / <count>)\` measured against this slide's own content width) instead of a fixed pixel width per column.`,
+          `Reduce the number of side-by-side columns, or wrap to a second row, if the content cannot fit at the slide's actual content width.`,
+        ]
+      : []),
+    ...(hasVertical || !hasHorizontal
+      ? [
+          `Tighten copy — shorter headings/bullets, drop low-value lines.`,
+          `Reduce vertical density — fewer stacked cards, smaller gaps, body font no smaller than 16px.`,
+          `Reduce slide padding (e.g. 40px top/bottom instead of 60-80px).`,
+          `Split across two slides only if the content cannot be compressed.`,
+        ]
+      : []),
+  ];
+
   return [
     ``,
-    `⚠ Layout overflows the canvas${m.verticalOverflow > 0 ? ` vertically by ${m.verticalOverflow}px` : ""}${(m.horizontalOverflow ?? 0) > 0 ? ` and horizontally by ${m.horizontalOverflow}px` : ""} — natural content is ${m.contentWidth ?? "unknown"}x${m.contentHeight}px inside a ${m.viewportWidth ?? "unknown"}x${m.viewportHeight}px content area.`,
+    `⚠ Layout overflows the canvas${hasVertical ? ` vertically by ${m.verticalOverflow}px` : ""}${hasHorizontal ? ` and horizontally by ${m.horizontalOverflow}px` : ""} — natural content is ${m.contentWidth ?? "unknown"}x${m.contentHeight}px inside a ${m.viewportWidth ?? "unknown"}x${m.viewportHeight}px content area.`,
     ``,
     `Make one structural repair now with \`update-slide --deckId ${deckId} --slideId ${m.slideId}\`. Prefer small surgical patches (--find / --replace) over a full rewrite:`,
-    `1. Tighten copy — shorter headings/bullets, drop low-value lines.`,
-    `2. Reduce vertical density — fewer stacked cards, smaller gaps, body font no smaller than 16px.`,
-    `3. Reduce slide padding (e.g. 40px top/bottom instead of 60-80px).`,
-    `4. Split across two slides only if the content cannot be compressed.`,
+    ...fixes.map((fix, index) => `${index + 1}. ${fix}`),
     ``,
     `Do **not** use zoom, \`transform: scale\`, clipping, \`overflow: scroll\`, or a smaller-than-16px body font. Preserve existing absolute text boxes and fix the normal-flow HTML. Verify the action result and then use \`view-screen\`; do not spin through another repair loop.`,
   ].join("\n");

package/corpus/templates/slides/actions/add-slide.ts

@@ -97,6 +97,7 @@ export default defineAction({
     "call it once per slide in slide order and wait for each result before adding the next slide. " +
     "Avoid parallel add-slide calls for the same deck; sequential writes keep the editor and agent connection stable. " +
     "If the deck has a designSystemId, first use `get-design-system` and apply its `agentContext` tokens/docs; do not use generic slide styling from the id alone. " +
+    "Pass presenter-only speaker notes in `notes`; keep them out of the slide HTML. " +
     "Returns the new slide ID, 1-based slideNumber, and updated slide count.",
   schema: z.object({
     deckId: z.string().describe("Target deck ID"),
@@ -120,7 +121,10 @@ export default defineAction({
       ])
       .optional()
       .describe("Layout type hint"),
-    notes: z.string().optional().describe("Speaker notes for this slide"),
+    notes: z
+      .string()
+      .optional()
+      .describe("Optional presenter-only speaker notes; keep them out of HTML"),
     position: z
       .preprocess((value) => {
         if (typeof value !== "string") return value;
@@ -299,7 +303,7 @@ export default defineAction({
         creativeContextReuseLabels: slideReuseLabels,
       };
       if (layout) newSlide.layout = layout;
-      if (notes) newSlide.notes = notes;
+      if (notes !== undefined) newSlide.notes = notes;
 
       const insertIndex =
         typeof position === "number"

package/corpus/templates/slides/actions/create-deck.ts

@@ -96,12 +96,13 @@ export default defineAction({
     "Create a new deck, optionally already populated with slides, or atomically replace all slides in an existing deck. " +
     "For short AI-generated decks in MCP app hosts, pass all generated slides in this call so the real deck editor opens inline already populated. " +
     "For longer decks or live in-app generation, create the deck with slides: [] and then use add-slide sequentially so progress appears live. " +
+    "Pass presenter-only speaker notes in each slide's `notes` field; keep them out of slide HTML. " +
     "Pass deckId to replace an existing deck. " +
     "Returns the deck id, title, and slide count.",
   schema: z.object({
     title: z.string().describe("Deck title"),
     slides: SlidesSchema.describe(
-      "Array of slides with id, content (HTML), and optional layout",
+      "Array of slides with id, content (HTML), optional layout, and presenter-only notes",
     ),
     deckId: z
       .string()

package/corpus/templates/slides/app/components/editor/GoogleDriveConnectionCta.tsx

@@ -35,11 +35,11 @@ async function readJson<T>(response: Response): Promise<JsonReadResult<T>> {
   try {
     return { ok: true, data: (await response.json()) as T };
   } catch (caught) {
+    const error = new Error("The server returned an unreadable response.");
+    (error as Error & { cause?: unknown }).cause = caught;
     return {
       ok: false,
-      error: new Error("The server returned an unreadable response.", {
-        cause: caught,
-      }),
+      error,
     };
   }
 }

package/corpus/templates/slides/app/components/editor/GoogleSlidesReferenceImport.tsx

@@ -56,11 +56,11 @@ async function readJson<T>(response: Response): Promise<JsonReadResult<T>> {
   try {
     return { ok: true, data: (await response.json()) as T };
   } catch (caught) {
+    const error = new Error("The server returned an unreadable response.");
+    (error as Error & { cause?: unknown }).cause = caught;
     return {
       ok: false,
-      error: new Error("The server returned an unreadable response.", {
-        cause: caught,
-      }),
+      error,
     };
   }
 }

package/corpus/templates/slides/app/components/editor/PromptDialog.tsx

@@ -55,7 +55,9 @@ export async function uploadPromptFiles(
         message = data.error;
       }
     } catch (error) {
-      throw new Error(`Upload failed (${response.status})`, { cause: error });
+      const uploadError = new Error(`Upload failed (${response.status})`);
+      (uploadError as Error & { cause?: unknown }).cause = error;
+      throw uploadError;
     }
     throw new Error(message);
   }