@agent-native/core 0.122.4 → 0.123.0

package/corpus/templates/plan/.agents/skills/plan-comments-and-feedback/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: plan-comments-and-feedback
+description: >-
+  Plan review threads end to end: what `get-plan-feedback` returns, how to read
+  anchors, resolver intent, replies, notification email, deletion, and abuse
+  reports. Use when reading, answering, resolving, or removing plan feedback.
+---
+
+# Plan Comments and Feedback
+
+- Plan comments include reviewer identity, @mentions, resolver intent
+  (`agent` or `human`), exact anchors, and design-review threads. When adding
+  human feedback through `update-visual-plan`, preserve `authorEmail` and
+  `authorName` when known; pass `parentCommentId` to reply inline to an
+  existing comment thread. Text feedback should anchor to the nearest prose
+  block, and visual/canvas feedback should include target coordinates plus
+  concise surrounding context.
+- Use `delete-plan-comment` only when the user explicitly asks to remove a
+  comment, undo an accidental comment, or clean up an obsolete thread. Deleting
+  is a soft delete: normal comment views hide the comment while the database row
+  remains for audit/debugging. Deleting a thread root also deletes its replies.
+  When feedback has merely been handled, prefer `resolve-plan-comment` and
+  `consume-plan-feedback` so review history remains visible.
+- Use `delete-visual-plan` only when the owner explicitly asks to delete or
+  restore their hosted plan/recap data. `mode=soft` moves the resource to the
+  Deleted tab and makes normal reads/direct links stop working; `mode=restore`
+  undeletes it; `mode=hard` permanently removes the plan row plus plan-scoped
+  comments, sections, events, versions, shares, reports, SQL asset records, and
+  collab snapshots. Hard delete requires the exact confirmation phrase
+  `DELETE <planId>`.
+- `get-plan-feedback` returns flat comments, grouped threads, anchor summaries,
+  detailed anchor lines, and recent review events that describe the edit/comment
+  delta. Use those fields before changing code or updating the plan, especially
+  to distinguish comments the agent should act on from comments intended for a
+  human reviewer.
+- **Anchor interpretation.** `targetX`/`targetY` are percentages within the
+  named element; bare `x`/`y` are percentages of the whole document;
+  `canvasX`/`canvasY` are board-world pixels. Wireframe anchors carry
+  `targetNodeId`/`targetNodePath` — prefer those over raw coordinates; fall back
+  to coordinates plus the focused screenshot only when no node id is present.
+  Resolve `textQuote` with `contextBefore`/`contextAfter`; if `ambiguous: true`,
+  ask the user. Threads in `detachedThreads` no longer match current prose —
+  reconcile, never drop. Act on `resolutionTarget=agent`; treat `human` as
+  context only; `@mentions` are notification signals, not routing. Mark ingested
+  comments consumed (`consumedCommentIds`); set `status=resolved` only on
+  agent-targeted comments you actually addressed. When a plan write addresses
+  feedback, do not resolve or consume it until a post-write `get-visual-plan`
+  confirms the requested change persisted. Then do both: call
+  `resolve-plan-comment` for the addressed thread and `consume-plan-feedback`
+  for its comments.
+- New human comments send best-effort transactional email when email is
+  configured: root comments and replies notify the plan owner, @mentioned
+  members, and replies also notify prior human participants in that thread.
+  Reuse the shared `renderEmail` template; do not invent a separate
+  plan-specific email style.
+- `report-visual-plan` records a bounded abuse report for a public plan or recap
+  without changing plan content. It requires the caller to be scoped to an
+  accessible public plan, accepts a fixed reason plus optional short details,
+  and updates an existing open report from the same reporter instead of creating
+  duplicate rows.
+
+## Related Skills
+
+- **plan-hosted-writes** — verify a write persisted before resolving or
+  consuming the feedback it addressed.
+- **plan-browser-editing** — the editing surfaces reviewers annotate.
+- **plan-source-sync** — `comments.json` sidecars for DB-free local plans.
+- **plan-events** — automating notifications on `plan.commented`.

package/corpus/templates/plan/.agents/skills/plan-events/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: plan-events
+description: >-
+  The four plan lifecycle events on the framework event bus and how to subscribe
+  with `manage-automations` instead of bespoke integration code. Use when a user
+  wants to be notified or trigger work on plan creation, comments, publishes, or
+  status changes.
+---
+
+# Plan Events
+
+The plan app emits four events on the framework event bus: `plan.created`,
+`plan.commented`, `plan.published`, and `plan.status.changed`. Automations can
+subscribe to any of them — if a user asks to "notify me when someone comments"
+or similar, call `manage-automations` with `action=define` (trigger `plan.commented`,
+optional condition on `resolutionTarget`) rather than writing bespoke integration
+code. See the `automations` skill and the [Visual Plans events docs](/docs/template-plan#events)
+for payload schemas and recipe examples.
+
+## Related Skills
+
+- **plan-comments-and-feedback** — the comment data an automation reacts to.

package/corpus/templates/plan/.agents/skills/plan-hosted-writes/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: plan-hosted-writes
+description: >-
+  Preconditions and protocol for writing hosted plans: real user session,
+  `expectedUpdatedAt` revision guard on destructive writes, post-write
+  verification, and when feedback may be resolved or consumed. Use when
+  performing any hosted plan write.
+---
+
+# Hosted Plan Writes
+
+## Session Requirement
+
+Current app actions require a real user session so plans stay scoped and
+shareable. Local development can use the framework's auto-created dev account;
+hosted persistence, private sharing, reviewer links, and cross-device/team
+workflows use account login, with Google sign-in shown when the standard
+Google OAuth env vars are configured.
+
+## Revision Guard Before Destructive Writes
+
+Before any destructive hosted-plan write (`replace-blocks`, a top-level
+`content` replacement, or a source `replace-file`), call `get-visual-plan`
+immediately before the write and pass its `plan.updatedAt` as
+`expectedUpdatedAt`. Never reuse a revision from an earlier read. Prefer
+targeted content or source patches whenever they can express the edit.
+
+## Verify After Every Write
+
+After every hosted-plan write, call `get-visual-plan` again and verify the
+persisted text, blocks, canvas, and prototype before claiming success. If the
+write addressed agent-targeted feedback, call `resolve-plan-comment` and
+`consume-plan-feedback` only after this verification; addressed feedback must
+be both resolved and consumed so it neither remains visibly open nor returns
+as pending work.
+
+## Related Skills
+
+- **plan-comments-and-feedback** — what `get-plan-feedback` returns and how to
+  interpret anchors before and after a write.
+- **plan-source-sync** — `replace-file` and other source-level writes.
+- **plan-version-history** — snapshots taken before meaningful writes.

package/corpus/templates/plan/.agents/skills/plan-local-codebase-chat/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: plan-local-codebase-chat
+description: >-
+  How Ask Plan links a browser-selected local codebase and how to answer
+  questions from its indexed snapshots instead of guessing from file names. Use
+  when the user asks about their linked local codebase or `localCodebase` is in
+  application state.
+---
+
+# Local Codebase Chat
+
+The `local-codebase` application-state key is written by the Ask Plan browser
+folder picker when a user links a local codebase. It includes the selected
+folder name plus personal resource paths for the latest code index, file tree,
+and captured source snapshots.
+
+- The Ask Plan page can link a browser-selected local codebase folder. The UI
+  indexes safe text files, skips generated/secret-looking paths, writes a small
+  personal instruction resource under `instructions/local-codebases/`, and
+  stores captured file snapshots under `codebases/<id>/snapshots/<timestamp>/`.
+- For live codebase questions, call `view-screen` when context is unclear and
+  inspect `localCodebase`. First read its `indexPath` with the `resources` tool
+  using `scope: "personal"`, then read relevant captured file `resourcePath`s
+  before making claims. Do not infer API contracts, schema shape, or UI behavior
+  from file names alone.
+- If the file needed to answer is absent or skipped, ask the user to sync again
+  or attach the file instead of guessing.
+- For API/schema/UI visualization from a local codebase, call
+  `get-plan-blocks` or `list-plan-components` before `visual-answer`, then
+  publish blocks such as `openapi-spec`, `api-endpoint`, `data-model`,
+  `diagram`, `file-tree`, `tabs`, and `annotated-code` grounded in the files
+  you read.
+
+## Related Skills
+
+- **visualize-repo** — durable repo-backed visual documentation from local plan
+  MDX files.
+- **plan-source-sync** — reading and writing local plan folders.

package/corpus/templates/plan/.agents/skills/plan-review-recaps/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plan-review-recaps
+description: >-
+  The `columns` before/after comparison primitive and the PR Visual Recap GitHub
+  Action (agent/model env vars, required tokens, sticky comment, informational
+  scope). Use when building a recap, configuring recap CI, or explaining a
+  Visual Recap check or comment.
+---
+
+# Review Recaps
+
+- `columns` is the generic before/after layout primitive for structured
+  comparisons. Use it for side-by-side schema, API, prose, and model blocks.
+- The PR Visual Recap GitHub Action runs the `visual-recap` skill on each PR via
+  an LLM coding agent (Claude Code or Codex, chosen with `VISUAL_RECAP_AGENT`;
+  model and reasoning depth via `VISUAL_RECAP_MODEL` / `VISUAL_RECAP_REASONING`)
+  when `PLAN_RECAP_TOKEN` and the backend's API key are configured, shows a
+  non-required `Visual Recap` check while it runs, then posts a sticky comment
+  with an inline screenshot. The recap is informational and must not imply the
+  diff has been reviewed.
+
+## Related Skills
+
+- **visual-recap** — how to generate the recap content itself.
+- **plan-authoring-flow** — when `/visual-recap` is the right command.

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

@@ -0,0 +1,68 @@
+---
+name: plan-source-sync
+description: >-
+  The MDX source surface for plans: export, import, patch by semantic ID, DB-free
+  local plan folders, `comments.json` sidecars, promotion into a repo, and the
+  Desktop folder bridge. Use when a plan must round-trip to or from repo files.
+---
+
+# Plan Source Sync
+
+## Source Surface
+
+Runtime plan content is normalized JSON in SQL. MDX is the source-control
+surface: `plan.mdx` for frontmatter plus markdown/document blocks,
+`prototype.mdx` for optional Prototype/PrototypeScreen/PrototypeTransition
+markup, `canvas.mdx` for optional DesignBoard/Section/Artboard/Screen/
+Annotation/Connector markup, optional `assets/`, and optional
+`.plan-state.json`.
+
+## Rules
+
+- Use `export-visual-plan` or `read-visual-plan-source` when a user or external
+  agent wants plan files to check into a repo.
+- Use `get-local-plan-folder` to read a DB-free local MDX folder from
+  `PLAN_LOCAL_DIR` or from a repo-relative `path`, and
+  `update-local-plan-folder` to apply structured `contentPatches` back to that
+  same folder. Pass `path` whenever the user is viewing a
+  `/local-plans/:slug?path=...` URL. These local-folder actions do not read or
+  write SQL.
+- Use `update-local-plan-comments` to add, reply to, resolve, or delete review
+  comments on a local plan. They persist to a `comments.json` sidecar beside
+  `plan.mdx` (committed with the plan, no SQL), are always addressed to the
+  agent (`resolutionTarget: "agent"`), and are surfaced by `get-local-plan-folder`.
+  Local comments are a one-way handoff to the coding agent — delivery is the
+  composer's "Send to agent" copy-to-clipboard, not notifications or sharing.
+  In bridge mode the read-only bridge serves no comments, so the colocated
+  folder's `comments.json` is merged in for display and persistence.
+- Use `promote-local-plan-folder` when a temporary local plan should be saved
+  into the repo. Its default target is `apps.plan.roots[0].path/<slug>` from
+  `agent-native.json`, falling back to `plans/<slug>`.
+- Commit `.plan-state.json` with repo-backed plan folders when present. It is
+  source metadata for stable bare-Markdown block IDs, not a disposable preview
+  cache.
+- Use `import-visual-plan-source` to create or replace a plan from an MDX folder.
+- Use `patch-visual-plan-source` for small source edits by stable semantic IDs.
+  It patches the MDX AST, runs formatting, parses back to normalized JSON, and
+  persists the runtime model. Prefer this over regenerating a whole plan when the
+  requested change is a few lines, one annotation, one artboard, or one
+  wireframe node.
+- `replace-file` is a destructive source operation. Use it only when targeted
+  source patches cannot express the edit, after a fresh `get-visual-plan`, and
+  pass that read's `plan.updatedAt` as `expectedUpdatedAt`. Re-read the plan
+  after the patch and verify that unrelated MDX files and visual surfaces were
+  preserved.
+- In Agent Native Desktop, the Plan menu can link a user-chosen local folder for
+  the current plan, write the exported MDX files to it, import local edits back
+  through `import-visual-plan-source`, and optionally auto-export whenever the
+  hosted plan changes. This is a native desktop bridge; it does not require a
+  cloned Plan app or CLI process.
+- Do not fork the vocabulary. MDX components must map to the same runtime terms:
+  `DesignBoard`, `Section`, `Artboard`, `Screen`, `Annotation`, `Connector`, and
+  the wireframe kit primitives from `shared/plan-content.ts`.
+
+## Related Skills
+
+- **plan-hosted-writes** — the revision guard `replace-file` depends on.
+- **plan-browser-editing** — how local folders autosave from the browser.
+- **visualize-repo** — repo-native visual docs built on local plan folders.

package/corpus/templates/plan/.agents/skills/plan-version-history/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plan-version-history
+description: >-
+  DB-backed plan snapshots: when they are taken, how to list and inspect them,
+  and what `restore-plan-version` preserves. Use when the user asks about plan
+  history, undo, rollback, or restoring an earlier version of a plan.
+---
+
+# Plan Version History
+
+- Plans keep DB-backed snapshots before meaningful authoring changes. Pure
+  comments, feedback replies, and comment status changes do not create history
+  snapshots.
+- Use `list-plan-versions` to see saved snapshots for a plan, and
+  `get-plan-version` to inspect one full snapshot before recommending a
+  rollback.
+- Use `restore-plan-version` only when the user asks to restore or roll back.
+  The current plan is snapshotted first with `Before restore`, so restore is
+  reversible. Restore preserves sharing, ownership, hosted publish metadata,
+  comments, and activity history; it restores the plan's authoring content and
+  legacy sections.
+
+## Related Skills
+
+- **plan-hosted-writes** — the write protocol that triggers snapshots.

package/corpus/templates/plan/.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/plan/.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/plan/.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/plan/.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.