@agent-native/core 0.123.0 → 0.123.1

package/corpus/templates/crm/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: customizing-agent-native
+description: >-
+  How to configure, compose, or eject Agent Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent Native
+
+## Rule
+
+Start with the app's registered design system and local UI adapters, then use
+the public feature's props, semantic components, controller, product slots,
+and callbacks. If those seams are not enough, use the eject CLI to transfer
+the smallest supported feature into the app and make that copy app-owned.
+Never edit `node_modules`, deep-import a private source file at runtime, or
+patch an `@agent-native/*` package.
+
+Use this order:
+
+1. Set brand tokens with the build-time theme configuration when tokens are
+   enough.
+2. Register company components in `app/design-system.ts` with
+   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
+3. Configure a public feature through its semantic components, headless
+   controller, and product-level render slots.
+4. Compose app primitives behind the app's local UI adapter layer.
+5. Eject the smallest feature into app-owned source.
+6. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Ejection is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Use A Company Design System
+
+Keep the explicit, typed registration seam in `app/design-system.ts`:
+
+```tsx
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import {
+  AcmeActionButtonAdapter,
+  AcmeDialogAdapter,
+} from "./design-system/acme-adapter";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  components: {
+    ActionButton: AcmeActionButtonAdapter,
+    Dialog: AcmeDialogAdapter,
+  },
+});
+```
+
+Adapters translate the semantic Toolkit contract into company component props.
+They are ordinary React components and may use MUI-style providers, React Aria,
+CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
+optional interoperability hooks, not Tailwind or CVA requirements.
+
+The contract has nine leaf components (`ActionButton`, `IconButton`,
+`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
+and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
+`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
+behavior, not date picking. Behavior adapters own their portal, focus,
+keyboard, dismissal, and stacking implementation while honoring the semantic
+props and `portalContainer` interop contract.
+
+App product code imports standard controls from its local adapter path, usually
+`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
+pages, routes, or domain components. That bypasses the app seam and makes a
+future design-system replacement incomplete. Toolkit feature packages remain
+valid imports; configure their presentation through the registered semantic
+components, controller, and product slots.
+
+Run the published conformance kit against a complete adapter in its own CI:
+
+```tsx
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+
+await assertDesignSystemConformance({
+  adapterName: "Acme",
+  components,
+  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+});
+```
+
+New components and optional props are minor contract changes. Required props,
+removed APIs, or behavioral changes require a new contract major.
+
+## Customize A Shared Feature
+
+Prefer feature-level headless controllers over rebuilding individual widgets.
+One controller must power both the Toolkit default view and every custom render
+path so behavior, actions, analytics, accessibility state, and error handling
+cannot drift. Use a product-level render slot to replace the view while keeping
+that controller. Eject only when the controller and slots cannot express the
+required product behavior.
+
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+Every first-party public ejection unit must have a complete manifest. If one is
+missing, treat that as a framework coverage bug instead of inventing a copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied; follow the
+reported configuration, adapter, or extension seam instead.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- Core and first-party template source lives under
+  `node_modules/@agent-native/core/corpus/core/` and
+  `node_modules/@agent-native/core/corpus/templates/`.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
+
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+- Keep page, route, and domain code on local UI adapter imports. Never reach
+  around the registered design system with direct Toolkit UI primitive imports.
+
+## App Shapes
+
+- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
+  and domain UI. Use Toolkit features for repeated workspace behavior; eject
+  only the unit being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** put one-app overrides in that app. Promote a local component
+  to `packages/shared` only when multiple workspace apps use it.
+
+## After Ejecting
+
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
+- Keep visible text in the app's localization catalogs.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
+- Don't fork feature state into a custom view; consume the feature's controller.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs and source lookup
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `self-modifying-code` — safe app source edits
+- `upgrade-agent-native` — supported package upgrade path
+- `adding-a-feature` — UI/action/instructions/application-state parity

package/corpus/templates/crm/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

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