@agent-native/core 0.162.0 → 0.163.1

package/dist/sharing/schema.d.ts

@@ -42,7 +42,7 @@ export declare function ownableColumns(): {
  * Columns:
  * - `id`              — share row id (generated by the share action)
  * - `resourceId`      — id of the parent resource
- * - `principalType`   — `'user' | 'org'`
+ * - `principalType`   — `'user' | 'group' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
  * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
@@ -100,14 +100,14 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "org" | "user";
+            data: "group" | "org" | "user";
             driverParam: string;
             notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["user", "org"];
+            enumValues: ["user", "group", "org"];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -195,7 +195,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
 }>;
 export type Visibility = "private" | "org" | "public";
 export type ShareRole = "viewer" | "commenter" | "editor" | "admin";
-export type PrincipalType = "user" | "org";
+export type PrincipalType = "user" | "group" | "org";
 /** Role precedence — higher number = stronger capability. */
 export declare const ROLE_RANK: Record<ShareRole | "owner", number>;
 export declare function roleSatisfies(actual: ShareRole | "owner", minimum: ShareRole | "owner"): boolean;

package/dist/sharing/schema.js

@@ -49,7 +49,7 @@ export function ownableColumns() {
  * Columns:
  * - `id`              — share row id (generated by the share action)
  * - `resourceId`      — id of the parent resource
- * - `principalType`   — `'user' | 'org'`
+ * - `principalType`   — `'user' | 'group' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
  * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
@@ -65,7 +65,7 @@ export function createSharesTable(tableName) {
         id: text("id").primaryKey(),
         resourceId: text("resource_id").notNull(),
         principalType: text("principal_type", {
-            enum: ["user", "org"],
+            enum: ["user", "group", "org"],
         }).notNull(),
         principalId: text("principal_id").notNull(),
         role: text("role", {

package/dist/templates/chat/.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/dist/templates/default/.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/dist/templates/workspace-core/.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/dist/tracking/registry.js

@@ -1,3 +1,4 @@
+import { resolveDeployEnvironment } from "../server/deploy-environment.js";
 import { getRequestContext } from "../server/request-context.js";
 import { ANALYTICS_CLIENT_PLATFORM_PROPERTY } from "../shared/analytics-platform.js";
 const REGISTRY_KEY = Symbol.for("@agent-native/core/tracking.registry");
@@ -46,12 +47,13 @@ function resolveTrackingSource(source) {
 export function track(name, properties, source) {
     const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
     const clientPlatform = getRequestContext()?.clientPlatform;
-    const trackedProperties = clientPlatform
-        ? {
-            ...(properties ?? {}),
-            [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform,
-        }
-        : properties;
+    const trackedProperties = {
+        ...(properties ?? {}),
+        deployment_environment: resolveDeployEnvironment(),
+        ...(clientPlatform
+            ? { [ANALYTICS_CLIENT_PLATFORM_PROPERTY]: clientPlatform }
+            : {}),
+    };
     const event = {
         name,
         properties: trackedProperties,

package/dist/vite/client.js

@@ -2913,6 +2913,11 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
             // netlify.toml environment is available to the build but not injected
             // into deployed Functions, so embed the decision in the server bundle.
             "process.env.AGENT_NATIVE_RELEASE_MIGRATIONS": JSON.stringify(process.env.AGENT_NATIVE_RELEASE_MIGRATIONS?.trim() || ""),
+            ...(resolvedAppConfig.deployment?.environment
+                ? {
+                    "process.env.AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT": JSON.stringify(resolvedAppConfig.deployment.environment),
+                }
+                : {}),
             __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(process.env.GTM_CONTAINER_ID?.trim() || ""),
             // Framework route warmup controls how SSR `.data` routes are fetched:

package/dist/workspace-connections/actions/list-workspace-user-groups.d.ts

@@ -1,2 +1,10 @@
-declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, import("../groups.js").WorkspaceUserGroup[]>;
+declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, {
+    id: string;
+    orgId: string;
+    name: string;
+    createdByEmail: string;
+    createdAt: string;
+    updatedAt: string;
+    memberEmails: any[];
+}[]>;
 export default _default;

package/dist/workspace-connections/actions/list-workspace-user-groups.js

@@ -1,13 +1,18 @@
 import { z } from "zod";
 import { defineAction } from "../../action.js";
-import { assertWorkspaceUserGroupManager, listWorkspaceUserGroupsForOrg, } from "../groups.js";
+import { listWorkspaceUserGroupsForOrg, workspaceUserGroupRole, } from "../groups.js";
 export default defineAction({
-    description: "List reusable workspace user groups. Group management is restricted to workspace owners and admins.",
+    description: "List reusable workspace user groups. Workspace members can see group names for sharing; only owners and admins receive member details and can manage groups.",
     schema: z.object({}),
     http: { method: "GET" },
     readOnly: true,
     run: async (_args, ctx) => {
-        await assertWorkspaceUserGroupManager(ctx?.orgId, ctx?.userEmail);
-        return listWorkspaceUserGroupsForOrg(ctx?.orgId ?? "");
+        const role = await workspaceUserGroupRole(ctx?.orgId, ctx?.userEmail);
+        if (!role)
+            throw new Error("Workspace membership is required.");
+        const groups = await listWorkspaceUserGroupsForOrg(ctx?.orgId ?? "");
+        if (role === "owner" || role === "admin")
+            return groups;
+        return groups.map((group) => ({ ...group, memberEmails: [] }));
     },
 });

package/dist/workspace-connections/groups.d.ts

@@ -20,12 +20,14 @@ export interface UpdateWorkspaceUserGroupMembersInput {
     operation: "add" | "remove";
     orgId?: string | null;
 }
+export declare function workspaceUserGroupsTable(): string;
 export declare function normalizeWorkspaceUserGroupIds(value: unknown): string[];
 export declare function ensureWorkspaceUserGroupsTable(): Promise<void>;
 export declare function listWorkspaceUserGroupsForOrg(orgId: string, groupIds?: string[]): Promise<WorkspaceUserGroup[]>;
 export declare function listWorkspaceUserGroups(): Promise<WorkspaceUserGroup[]>;
 export declare function assertWorkspaceUserGroupIds(groupIds: string[] | undefined, orgId: string | null | undefined): Promise<string[] | undefined>;
 export declare function assertWorkspaceUserGroupManager(orgId: string | null | undefined, userEmail: string | undefined): Promise<void>;
+export declare function workspaceUserGroupRole(orgId: string | null | undefined, userEmail: string | undefined): Promise<"owner" | "admin" | "member" | null>;
 export declare function upsertWorkspaceUserGroup(input: UpsertWorkspaceUserGroupInput): Promise<WorkspaceUserGroup>;
 export declare function updateWorkspaceUserGroupMembers(input: UpdateWorkspaceUserGroupMembersInput): Promise<WorkspaceUserGroup>;
 export declare function deleteWorkspaceUserGroup(id: string, orgId?: string | null): Promise<boolean>;

package/dist/workspace-connections/groups.js

@@ -3,7 +3,7 @@ import { getDbExec, intType, isPostgres, retryOnDdlRace, safeJsonParse, } from "
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { isOrgMember } from "../org/membership.js";
 import { getRequestOrgId, getRequestUserEmail, } from "../server/request-context.js";
-function workspaceUserGroupsTable() {
+export function workspaceUserGroupsTable() {
     return isPostgres()
         ? "public.workspace_user_groups"
         : "workspace_user_groups";
@@ -171,19 +171,25 @@ export async function assertWorkspaceUserGroupIds(groupIds, orgId) {
     return normalized;
 }
 export async function assertWorkspaceUserGroupManager(orgId, userEmail) {
+    const role = await workspaceUserGroupRole(orgId, userEmail);
+    if (role === "owner" || role === "admin")
+        return;
+    throw new Error("Only workspace admins can manage user groups.");
+}
+export async function workspaceUserGroupRole(orgId, userEmail) {
     const normalizedOrgId = orgId?.trim();
     const normalizedEmail = userEmail?.trim().toLowerCase();
     if (!normalizedOrgId || !normalizedEmail) {
-        throw new Error("Only workspace admins can manage user groups.");
+        return null;
     }
     const { rows } = await getDbExec().execute({
         sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
         args: [normalizedOrgId, normalizedEmail],
     });
     const role = String(rows[0]?.role ?? "");
-    if (role !== "owner" && role !== "admin") {
-        throw new Error("Only workspace admins can manage user groups.");
-    }
+    return role === "owner" || role === "admin" || role === "member"
+        ? role
+        : null;
 }
 export async function upsertWorkspaceUserGroup(input) {
     const requestScope = requireWorkspaceUserGroupScope();
@@ -283,6 +289,11 @@ export async function workspaceUserGroupsIncludeUser(orgId, groupIds, userEmail)
     if (!normalizedOrgId || !normalizedEmail || normalizedIds.length === 0) {
         return false;
     }
+    // Group rows can outlive roster membership. A stale email in the JSON
+    // member list must not keep granting access after that person leaves the
+    // organization.
+    if (!(await isOrgMember(normalizedOrgId, normalizedEmail)))
+        return false;
     const groups = await listWorkspaceUserGroupsForOrg(normalizedOrgId, normalizedIds);
     return groups.some((group) => group.memberEmails.includes(normalizedEmail));
 }

package/docs/content/deployment.mdx

@@ -26,11 +26,11 @@ pnpm install
 
 The install step creates the lockfile that the production Dockerfile below copies into its build stage.
 
-### 2. Add a local Compose file
+### 2. Add the local Docker files
 
-Create `docker-compose.yml` in the app root. It uses the [Dockerfile](#docker) in the next section and starts Postgres only on the private Compose network:
+Create `Dockerfile`, `.dockerignore`, and `docker-compose.yml` in the app root. `docker compose up --build` needs the Dockerfile, and `.dockerignore` keeps host-only files such as `node_modules` out of the Linux build context. Compose starts Postgres only on the private Compose network.
 
-You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture.
+You can also download the [Dockerfile](https://www.agent-native.com/examples/self-hosted-chat/Dockerfile), [.dockerignore](https://www.agent-native.com/examples/self-hosted-chat/.dockerignore), [Compose file](https://www.agent-native.com/examples/self-hosted-chat/docker-compose.yml), and [environment template](https://www.agent-native.com/examples/self-hosted-chat/env.example) as a starter fixture. The [Dockerfile](#docker) below matches the fixture.
 
 ```yaml filename="docker-compose.yml" maxLines=40
 services:
@@ -53,7 +53,7 @@ services:
       POSTGRES_USER: agent_native
       POSTGRES_HOST_AUTH_METHOD: trust
     volumes:
-      - postgres-data:/var/lib/postgresql
+      - postgres-data-v18:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U agent_native -d agent_native"]
       interval: 5s
@@ -61,9 +61,11 @@ services:
       retries: 10
 
 volumes:
-  postgres-data:
+  postgres-data-v18:
 ```
 
+PostgreSQL 18 uses `/var/lib/postgresql` as its volume mount path, unlike PostgreSQL 17 and earlier. The versioned volume name keeps this fresh fixture separate from older local stacks. If you are upgrading an existing PostgreSQL 17 or earlier stack, back up and migrate its data before changing the image or mount path. Do not point this fixture at the old volume without a migration.
+
 ### 3. Run it
 
 ```bash
@@ -322,6 +324,18 @@ EXPOSE 3000
 CMD ["node", ".output/server/index.mjs"]
 ```
 
+Create `.dockerignore` alongside the Dockerfile:
+
+```text filename=".dockerignore"
+node_modules
+.output
+data
+.env
+.env.*
+!.env.example
+.git
+```
+
 ### Self-hosted workspace with Docker Compose {#workspace-docker-compose}
 
 The Dockerfile above is for one standalone app. A workspace is not one Nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.162.0",
+  "version": "0.163.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": {

package/src/templates/chat/.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/src/templates/default/.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`.  |