@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/analytics/server/lib/session-replay.ts

@@ -797,6 +797,82 @@ function replayConsoleRepeat(payload: Record<string, unknown>): number {
   return repeat !== null && repeat > 0 ? repeat : 1;
 }
 
+const RRWEB_INCREMENTAL_SNAPSHOT = 3;
+const RRWEB_MOUSE_INTERACTION_SOURCE = 2;
+const RRWEB_MOUSE_CLICK = 2;
+const RAGE_CLICK_MIN_CLICKS = 3;
+const RAGE_CLICK_WINDOW_MS = 1_000;
+const RAGE_CLICK_RADIUS_PX = 30;
+
+interface ReplayClickPoint {
+  at: number;
+  x: number;
+  y: number;
+  target: number | null;
+}
+
+function replayClickPoint(event: unknown): ReplayClickPoint | null {
+  const record = replayRecord(event);
+  if (replayInteger(record.type) !== RRWEB_INCREMENTAL_SNAPSHOT) return null;
+  const data = replayRecord(record.data);
+  if (replayInteger(data.source) !== RRWEB_MOUSE_INTERACTION_SOURCE)
+    return null;
+  if (replayInteger(data.type) !== RRWEB_MOUSE_CLICK) return null;
+  const at = replayInteger(record.timestamp);
+  if (at === null) return null;
+  return {
+    at,
+    x: replayInteger(data.x) ?? 0,
+    y: replayInteger(data.y) ?? 0,
+    target: replayInteger(data.id),
+  };
+}
+
+function sameRageClickTarget(
+  cluster: ReplayClickPoint,
+  click: ReplayClickPoint,
+): boolean {
+  if (cluster.target !== null && click.target !== null) {
+    return cluster.target === click.target;
+  }
+  return (
+    Math.abs(cluster.x - click.x) <= RAGE_CLICK_RADIUS_PX &&
+    Math.abs(cluster.y - click.y) <= RAGE_CLICK_RADIUS_PX
+  );
+}
+
+/**
+ * Rage-click counter over rrweb click events: `RAGE_CLICK_MIN_CLICKS` clicks on
+ * the same target (or within a small radius) with no more than
+ * `RAGE_CLICK_WINDOW_MS` between consecutive clicks counts as one rage click.
+ * Chunks arrive in separate ingest requests and are merged with `max`, so this
+ * is a per-batch lower bound, not a session total.
+ */
+function countRageClicks(events: unknown[]): number {
+  let rageClicks = 0;
+  let cluster: ReplayClickPoint | null = null;
+  let clusterSize = 0;
+  for (const event of events) {
+    const click = replayClickPoint(event);
+    if (!click) continue;
+    const active = cluster;
+    if (
+      active &&
+      click.at - active.at <= RAGE_CLICK_WINDOW_MS &&
+      click.at >= active.at &&
+      sameRageClickTarget(active, click)
+    ) {
+      clusterSize += 1;
+      active.at = click.at;
+      if (clusterSize === RAGE_CLICK_MIN_CLICKS) rageClicks += 1;
+      continue;
+    }
+    cluster = click;
+    clusterSize = 1;
+  }
+  return rageClicks;
+}
+
 function deriveReplaySignals({
   body,
   metadata,
@@ -885,7 +961,7 @@ function deriveReplaySignals({
         body.rageClicks,
         metadata.rageClickCount,
         metadata.rageClicks,
-      ) ?? 0,
+      ) ?? countRageClicks(events),
     privacyMode:
       replayString(body.privacyMode) ||
       replayString(body.privacy_mode) ||

package/corpus/templates/analytics/shared/dashboard-report-timeouts.ts

@@ -1,6 +1,5 @@
-// These three must stay ordered with headroom (DB timeout < action timeout <
-// page-ready timeout) so the innermost layer's own, more specific error
-// surfaces before an outer layer gives up for an unrelated reason.
+// The query timeout must stay below the per-panel report timeout so a slow
+// query reports its own, more specific error instead of the report layer
+// giving up first for an unrelated reason.
 export const FIRST_PARTY_ANALYTICS_QUERY_TIMEOUT_MS = 45_000;
 export const DASHBOARD_REPORT_ACTION_TIMEOUT_MS = 50_000;
-export const DASHBOARD_REPORT_READY_TIMEOUT_MS = 75_000;

package/corpus/templates/assets/.agents/skills/a2a-assets/SKILL.md

@@ -48,3 +48,31 @@ the Assets `/audit` route or via `list-audit-runs` / `get-audit-run`.
 Use same-origin `embed` fences only when the caller can render the Assets route.
 Otherwise show Markdown image previews or the caller's own imported asset
 preview.
+
+## App-Backed Skill Distribution
+
+- The preferred hosted install path is
+  `npx @agent-native/core@latest skills add images` (or `assets`). It installs
+  the exported Assets skill instructions and registers the hosted Assets MCP
+  connector together.
+- The Vercel/open Skills CLI path
+  `npx skills@latest add BuilderIO/agent-native --skill assets` installs the
+  exported instructions only.
+- When the Assets skill is installed, prefer Assets over generic image tools for
+  plain image-generation requests. Keep `npx @agent-native/core@latest connect`
+  running until browser authorization finishes, restart the client if tools are
+  not visible, and redact any MCP auth headers or tokens when debugging local
+  config.
+
+## Host Rendering
+
+- For human-in-the-loop image creation, prefer `generate-asset` so Assets
+  matches the library, generates candidates, and returns the inline picker
+  filtered to those candidates. Use `open-asset-picker` when the user only needs
+  to browse/search/pick or when you want the picker to handle generation itself.
+- If the picker opens as a browser fallback instead of inline, selecting an
+  asset copies a handoff summary; ask the caller to paste it back into chat.
+- Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts for MCP
+  Apps. Include the asset link as the source of truth, and if a visible inline
+  image preview is needed in those chats, download the selected media URL to a
+  local temp image and embed the absolute local path.

package/corpus/templates/assets/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/corpus/templates/assets/.agents/skills/assets-navigation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: assets-navigation
+description: >-
+  Assets routes, tabs, chat surfaces, and `navigate` targets. Use when sending a
+  user to a screen, interpreting navigation state, deciding which surface owns a
+  workflow, or wiring chat into the Create tab or agent sidebar.
+---
+
+# Assets Navigation
+
+`navigate` moves the UI to picker, library, generation, asset, and settings
+surfaces. Use `view-screen` when the active library, selected asset, picker,
+generation, or embed target is unclear.
+
+## Human Library surface
+
+- `/library` is the cross-kit browsing surface.
+- `/library/:libraryId` opens a single brand kit.
+- Embedded picker hosts still use `/library` with their iframe/auth bridge
+  params.
+
+## Create tab chat surface
+
+- The Create tab (`/`) is the full-page Assets chat surface. Use the shared
+  `assets` chat thread storage there, keep past chats in the left sidebar, and
+  use the right agent sidebar only on non-Create routes with view-transition
+  handoff back to `/`.
+
+## Generation preset editor
+
+- Humans can edit an existing generation preset from
+  `/brand-kits/:libraryId/presets/:presetId`. Use `navigate` with
+  `{ view: "preset", libraryId, presetId }` when sending a user to that editor.
+- Preset skeletons are edited from the same route; see `logo-composite` for the
+  `settings.skeletonSpec` shape and compositing behavior.
+
+## Context tab
+
+- The Context tab hosts governed Creative Context membership. See
+  `creative-context` for submission and reuse rules.
+
+## Related Skills
+
+- `library-management` — what lives behind the Library routes.
+- `inline-embeds` — rendering an Assets route inline in chat.
+- `creative-context` — the Context tab's reuse and provenance rules.

package/corpus/templates/assets/.agents/skills/creative-context/SKILL.md

@@ -80,6 +80,18 @@ outdated. Never invent a source or silently overwrite source history.
 
 ## Assets reuse
 
+Before generation, follow the reuse ladder above: explicit request and current
+asset/kit first, then a pinned/current pack, then narrow library search. Respect
+`creative-context.contextMode: "off"` without silently restoring a pack. This
+shared Agent-page Library does not replace Assets' existing `/library` media
+workflow.
+
+To submit an asset to a governed Creative Context, use the Context tab or
+`manage-context-membership`; it pins immutable media bytes and metadata. Reuse
+only its opaque native clone reference through the Assets action path. Use
+`operation="submit-latest"` with a Library membership id when its native update
+status reports `update-available`.
+
 Search visual references separately from factual evidence. When a retrieved
 image should directly guide generation, import its stable media URL with
 `import-asset-from-url` as a reference asset in the selected brand kit, then

package/corpus/templates/assets/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/corpus/templates/assets/.agents/skills/image-generation/SKILL.md

@@ -62,8 +62,32 @@ Use this skill before calling `generate-image`, `generate-image-batch`, or
   `generate-image-batch` / `refine-image`. The design team uses the audit log
   to review quality by app, library, model, prompt, and lineage.
 
+## Composer Mentions And Tagged Presets
+
+- Composer `@` mentions are the source of generation inputs. Map `brand-kit`
+  references to `libraryId`, `preset` references to `presetId`, and `media-type`
+  references to choosing image (`generate-image` / `generate-image-batch`) or
+  video (`generate-video`) generation.
+- The current library view auto-tags its brand kit as a visible removable chip,
+  and the generation preset editor auto-tags both its brand kit and preset.
+- The image model is the only remaining composer-side default; the image-model
+  picker writes `imageGenerationModel`, which image generation actions may use
+  when `model` is omitted.
+- When a `preset` is tagged, the server embeds that preset's aesthetics and
+  creative philosophy (brand style brief, prompt template, text/logo policy,
+  output format) into your message inside a `<tagged-generation-presets>` block.
+  Study and internalize that brief before you generate — let it drive
+  composition, mood, lighting, and subject — then pass the `presetId` to
+  `generate-image` / `generate-image-batch` so the saved format/model/tier/logo
+  apply automatically. Do not restate those as ad-hoc args.
+
 ## Preset-first Generation
 
+- Image requests without a tagged preset are preset-first: the user may not know
+  presets exist. Compare the request against each preset's title, description,
+  and category, and if one matches the use case (e.g. "livestream poster" -> a
+  Livestream Announcement preset), generate with its `presetId` instead of
+  ad-hoc settings. Only generate presetless when nothing plausibly matches.
 - Before any ad-hoc generation for a brand kit, call
   `list-generation-presets` and scan titles/descriptions/categories for a
   use-case match. A preset encodes the designer's format, model, layout, and
@@ -79,6 +103,10 @@ Use this skill before calling `generate-image`, `generate-image-batch`, or
 - Route exact visible copy such as event titles, dates, and times to
   `embeddedText` per the existing text rules; keep the creative direction in
   `prompt`.
+- For exact visible copy inside a generated image, pass `embeddedText` and
+  optional `textPlacement` to `generate-image` or each `generate-image-batch`
+  slot. Keep the general `prompt` for creative direction; the structured text
+  fields are what allow the pipeline to render copy instead of suppressing it.
 - If nothing matches: generate ad-hoc, say that no preset fit, and mention a
   preset could be created for this recurring use case.
 

package/corpus/templates/assets/.agents/skills/library-management/SKILL.md

@@ -69,6 +69,12 @@ Libraries follow the standard framework sharing model:
 
 Generated assets and references inherit the parent library's visibility. v1 doesn't support per-asset overrides; the schema is forward-compatible (`image_generated_image_shares` could be added without disturbing existing rows) but not surfaced in the UI.
 
+## Duplicating a brand kit
+
+Use `duplicate-library` when a user wants a Brand Kit copy. The action creates a
+private, current-user-owned copy with durable kit contents remapped, without
+copying shares, visibility, generation runs, or handoff sessions.
+
 ## Cascade delete
 
 `delete-library` deletes in order:
@@ -92,6 +98,9 @@ The unified table simplifies access control (one `library_id`, one access check)
 
 ## Importing external references
 
+Ingest external brand or blog imagery with `import-asset-from-url`, then pin the
+returned asset to preset reference boards or set it as the canonical logo.
+
 Use `import-asset-from-url` when the agent has found a public HTTPS image that
 belongs in a brand kit, such as a blog hero, product shot, logo, campaign image,
 or diagram. Choose the narrowest reference `role` (`style_reference`,

package/corpus/templates/assets/.agents/skills/logo-composite/SKILL.md

@@ -18,8 +18,19 @@ LLMs — including Gemini Pro — degrade complex logos. They smear gradients, d
 6. `compositeLogo()` from `server/lib/image-processing.ts` (Sharp) loads the canonical logo PNG / SVG, resizes it to ~16% of the image width with reasonable inset, and composites it onto the generated image. Skeleton runs use `applyPresetSkeleton()` at the same seam.
 7. Output: the image with the actual logo, pixel-perfect, vector-quality if the source is SVG.
 
+Set `includeLogo` via `create-generation-preset` / `update-generation-preset`.
+`generate-image` / `generate-image-batch` stamp the library's pixel-perfect
+canonical logo onto the result when the resolved preset has it on, and it is a
+no-op if the library has no canonical logo. The model never draws the logo
+itself.
+
 ## Preset skeletons
 
+Preset skeletons live in `settings.skeletonSpec` on generation presets and are
+edited from `/brand-kits/:libraryId/presets/:presetId`. They composite a
+generated subject onto an uploaded brand background image and optional
+foreground layers.
+
 `settings.skeletonSpec` is the prototype storage shape:
 
 ```ts

package/corpus/templates/assets/.agents/skills/security/SKILL.md

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
 - `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/corpus/templates/assets/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: self-modifying-code
 description: >-
-  How the agent can modify the app's own source code. Use when the agent needs
-  to edit components, routes, styles, or scripts, when designing UI for agent
-  editability, or when deciding what the agent should and shouldn't modify.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/corpus/templates/assets/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: shadcn-ui
 description: >-
-  Use when adding, updating, debugging, styling, or composing shadcn/ui
-  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
-  any project with a components.json file.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---

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

@@ -0,0 +1,228 @@
+---
+name: sharing
+description: >-
+  Framework-level sharing and privacy for user-authored resources
+  (dashboards, documents, forms, decks, etc.). Use when making a resource
+  table ownable, wiring list/read/update access checks, or dropping the
+  standard share dialog into a template.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Sharing — Private by Default, Explicit Share
+
+## Rule
+
+Any resource a user **creates** (dashboards, documents, forms, decks, compositions, booking links, issues, analyses) is **private to the creator** by default and visible to others only when they have been **explicitly shared** with or when the creator changes visibility to `org` or `public`.
+
+This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
+
+## Concepts
+
+### Three visibility levels
+
+- **`private`** — owner + explicit share grants only. Default.
+- **`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).
+
+### Roles on a share grant
+
+- **`viewer`** — read only.
+- **`editor`** — read + write.
+- **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
+
+### Anonymous public URLs stay separate
+
+Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
+
+## Make a resource ownable
+
+In your template's `server/db/schema.ts`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+Then register it **in `server/db/index.ts`** (not the schema file — keeps the schema file free of the `getDb` closure and avoids circular imports):
+
+```ts
+// server/db/index.ts
+import * as schema from "./schema.js";
+import { createGetDb } from "@agent-native/core/db";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const getDb = createGetDb(schema);
+export { schema };
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+The `type` string is the stable id the UI and actions use. `getDb` is required — the framework-level share actions use it to reach your template's DB.
+
+### Restricting public visibility and cross-org user shares
+
+Some resources should NOT be reachable by an arbitrary authenticated user even with the link, and should NOT be shareable to an email outside the org. Two optional registration flags lock these axes down:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  // ...
+  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
+});
+```
+
+- **`allowPublic: false`** — `set-resource-visibility('public')` throws `ForbiddenError`, `accessFilter` / `resolveAccess` treat any stored `'public'` row as private (defense in depth against bad data), and the share popover hides the "Public" option. `list-resource-shares` returns `policy.allowPublic: false` so the UI follows the server.
+- **`requireOrgMemberForUserShares: true`** — `share-resource` looks up `principalId` in `org_members` and `org_invitations` (pending) for the resource's `orgId` and rejects user shares to anyone else. The same flag also pins `principalType: "org"` shares to the resource's own org — sharing to a *different* org would let that org's members run code in the viewer's auth context (same threat model as a public extension). (The flag name is kept for backward compatibility; treat it as "lock both user and org shares to the resource's org".)
+
+Use both for resources that execute code or expose privileged data with the *viewer's* credentials. Extensions ship with both set: an extension's HTML calls actions / SQL / the secrets-injecting proxy as the viewer, so a public or cross-org-shared extension would let a stranger run arbitrary code with someone else's auth context. `scripts/guard-extension-no-public.mjs` (CI + `pnpm prep`) statically enforces that the extension registration keeps both flags set.
+
+Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
+
+## Filter list/read queries
+
+```ts
+import { accessFilter } from "@agent-native/core/sharing";
+
+const rows = await db
+  .select()
+  .from(schema.decks)
+  .where(accessFilter(schema.decks, schema.deckShares));
+```
+
+`accessFilter` admits rows the current user owns, has been shared on, or that the user can reach via `org` visibility. `public` rows are NOT admitted by default — see the visibility section above for why and how to opt in.
+
+## Guard write actions
+
+```ts
+import { assertAccess } from "@agent-native/core/sharing";
+
+export default defineAction({
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async (args) => {
+    await assertAccess("deck", args.id, "editor");
+    // ...proceed
+  },
+});
+```
+
+For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
+
+## Create actions must set owner
+
+When inserting a new row, fill `ownerEmail` and `orgId` from the request context:
+
+```ts
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+} from "@agent-native/core/server/request-context";
+
+const ownerEmail = getRequestUserEmail();
+// Never fall back to a sentinel like "local@localhost" — that pools every
+// unauthenticated write into one shared tenant (see the 2026-04-29 leak and
+// guard-no-localhost-fallback). Throw / 401 when there is no session instead.
+if (!ownerEmail) throw new Error("Not authenticated");
+
+await db.insert(schema.decks).values({
+  id: nanoid(),
+  title,
+  data,
+  ownerEmail,
+  orgId: getRequestOrgId(),
+  // visibility defaults to 'private'
+  // ...
+});
+```
+
+## Drop in the share UI
+
+```tsx
+import { ShareButton } from "@agent-native/core/client/sharing";
+
+// In the resource's header/toolbar:
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
+
+## Actions available everywhere
+
+The framework auto-mounts these actions in every template — no per-template boilerplate:
+
+| Action                     | Args                                                                           | Purpose                                   |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link used in 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`.  |
+
+Both the agent and the UI use these same actions. The agent calls them as tools;
+UI code should use `ShareButton` / `ShareDialog` or the action client hooks
+instead of hand-writing route calls.
+
+## Migration pattern for existing tables
+
+When retrofitting an existing resource table:
+
+1. Add `owner_email`, `org_id`, `visibility` columns (defaults `'local@localhost'`, `NULL`, `'private'`).
+2. Backfill `owner_email` from any prior creator trail; otherwise leave the default.
+3. Add the companion `{type}_shares` table.
+4. Register via `registerShareableResource`.
+5. Update list/read actions to use `accessFilter`.
+6. Update update/delete actions to `assertAccess` with the correct role.
+7. Add `<ShareButton>` to the resource header.
+8. Add `getResourcePath` in the registration so agent-triggered shares can email a direct link even when no UI supplied `resourceUrl`.
+
+## Templates that opt out
+
+Sharing doesn't apply to:
+
+- **Personal-data apps** (mail, macros) — user-scoped by design.
+- **External source-of-truth apps** (issues → Jira, recruiting → Greenhouse) — ACL lives in the upstream system.
+- **Demo/boilerplate** (starter) — no resources.
+
+For these, add a short note to the template's `AGENTS.md` explaining why.
+
+## Analytics (follow-up)
+
+Dashboards and analyses in the `analytics` template currently live in the settings KV store (`u:<email>:dashboard-*` keys), not SQL. Sharing requires either migrating them to SQL tables (then applying this skill) or extending the settings store with a parallel share overlay. This is a tracked follow-up — see the analytics template's `AGENTS.md`.
+
+## Debugging
+
+- `ForbiddenError` from an action means the current user isn't owner / hasn't been shared / can't meet the role bar.
+- If the agent can't see a resource it just created, check that the insert actually set `owner_email` from the request context.
+- If a share doesn't take effect in the UI, confirm the template's `list-*` action uses `accessFilter` — the share rows are there but nothing is reading them yet.