@agent-native/core 0.87.0 → 0.90.1

package/dist/sharing/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,6BAA6B;IAC5C,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC;IACnB,qDAAqD;IACrD,WAAW,EAAE,GAAG,CAAC;IACjB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;IACxD;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EACb,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,CACC,QAAQ,EAAE,GAAG,EACb,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAEzC,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;OAUG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK;QACtE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAuCD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,6BAA6B,GACnC,IAAI,CAGN;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GACX,6BAA6B,GAAG,SAAS,CAE3C;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GACX,6BAA6B,CAS/B;AAED,wBAAgB,sBAAsB,IAAI,6BAA6B,EAAE,CAExE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,6BAA6B;IAC5C,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,aAAa,EAAE,GAAG,CAAC;IACnB,qDAAqD;IACrD,WAAW,EAAE,GAAG,CAAC;IACjB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;IACxD;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,gBAAgB,CAAC,EACb,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,CACC,QAAQ,EAAE,GAAG,EACb,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAEzC,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,OAAO,CAAC,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;OAUG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK;QACtE,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,aAAa,CAAC,EACV,KAAK,GACL;QACE,uEAAuE;QACvE,YAAY,EAAE,MAAM,CAAC;QACrB,qEAAqE;QACrE,cAAc,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;QACtD,uEAAuE;QACvE,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,GAAG,SAAS,CAAC;QACpD,iEAAiE;QACjE,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACP;AAuCD,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,6BAA6B,GACnC,IAAI,CAGN;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,GACX,6BAA6B,GAAG,SAAS,CAE3C;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GACX,6BAA6B,CAS/B;AAED,wBAAgB,sBAAsB,IAAI,6BAA6B,EAAE,CAExE"}

package/dist/sharing/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA4FH,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,MAAM,cAAc,GAClB,UAAiB,CAAC;AAEpB,SAAS,aAAa;IACpB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;QAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAC3B,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B;IACnC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACtC,OAAO,oEAAoE,CAAC,IAAI,CAC9E,KAAK,CACN,CAAC;AACJ,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,IAAI,GAAG,EAAyC,CAAC;QACrD,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAoC;IAEpC,IAAI,CAAC,aAAa,EAAE,IAAI,4BAA4B,EAAE;QAAE,OAAO;IAC/D,WAAW,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAY;IAEZ,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAY;IAEZ,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,gDAAgD,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * Registry of shareable resources.\n *\n * Each template registers its ownable resource(s) once on module load so the\n * framework-level share actions (`share-resource`, `list-resource-shares`,\n * etc.) can dispatch to the correct tables.\n *\n *   import { registerShareableResource } from \"@agent-native/core/sharing\";\n *   import * as schema from \"./schema.js\";\n *\n *   registerShareableResource({\n *     type: \"document\",\n *     resourceTable: schema.documents,\n *     sharesTable: schema.documentShares,\n *     displayName: \"Document\",\n *     titleColumn: \"title\",\n *   });\n */\n\nexport interface ShareableResourceRegistration {\n  /** Stable identifier used across actions, UI, and analytics. e.g. \"document\". */\n  type: string;\n  /** Drizzle table for the parent resource (must have ownableColumns()). */\n  resourceTable: any;\n  /** Drizzle table produced by createSharesTable(). */\n  sharesTable: any;\n  /** Human-readable singular label shown in the share dialog. */\n  displayName: string;\n  /**\n   * Column on the resource table that holds a human-readable title for\n   * display in the share UI. Default: \"title\".\n   */\n  titleColumn?: string;\n  /**\n   * Optional app-relative path to this resource. Used by share notifications\n   * when the caller does not pass a more specific resourceUrl.\n   */\n  getResourcePath?: (resource: any) => string | undefined;\n  /**\n   * Drizzle DB accessor from the template's server/db/index.ts. Required —\n   * the framework-level share actions and access helpers call this to reach\n   * the right DB instance (schema is template-specific).\n   */\n  getDb: () => any;\n  /**\n   * When `false`, `visibility: \"public\"` is rejected by `set-resource-visibility`,\n   * and `accessFilter` / `resolveAccess` treat any stored public row as private\n   * (defense in depth — only owner + explicit shares grant access).\n   *\n   * Use this for resources that execute code or expose privileged data and must\n   * never be reachable by a random authenticated user. Extensions set this:\n   * extension HTML runs inside an iframe that calls actions / DB / proxied APIs\n   * as the *viewer*, so a public extension would be arbitrary code with the\n   * viewer's credentials.\n   *\n   * Default: `true` (matches the historical behavior — most resources can be public).\n   */\n  allowPublic?: boolean;\n  /**\n   * Optional role granted by a public-by-link read. Most resources should omit\n   * this so public visibility remains viewer-only. Use narrowly for local or\n   * otherwise constrained resources where the resource owner intentionally wants\n   * unauthenticated link holders to do more than view.\n   */\n  publicAccessRole?:\n    | \"viewer\"\n    | \"editor\"\n    | \"admin\"\n    | ((\n        resource: any,\n        ctx: { userEmail?: string; orgId?: string },\n      ) =>\n        | \"viewer\"\n        | \"editor\"\n        | \"admin\"\n        | Promise<\"viewer\" | \"editor\" | \"admin\">);\n  /**\n   * When `true`, individual user shares (`principalType: \"user\"`) must target\n   * an email that is already a member of the same org as the resource, OR has\n   * a pending invitation to that org. Cross-org user shares are rejected.\n   *\n   * Pair with `allowPublic: false` for resources that need a hard \"this org\n   * only\" trust boundary. Extensions set this so a malicious caller can't\n   * widen reach by sharing a code-executing extension to an outsider email.\n   *\n   * Default: `false` (matches the historical behavior — any email can be granted).\n   */\n  requireOrgMemberForUserShares?: boolean;\n  /**\n   * Optional per-resource access-context adapter. Most resources should use the\n   * request user/org unchanged. Templates with an intentional alternate local\n   * identity can normalize here so the generic framework sharing actions and\n   * access helpers stay in sync with template-owned actions.\n   */\n  resolveAccessContext?: (ctx: { userEmail?: string; orgId?: string }) => {\n    userEmail?: string;\n    orgId?: string;\n  };\n  /**\n   * When true, direct ownership is recognized by owner_email regardless of the\n   * caller's active org. Use this only for resource types where the template's\n   * own actions already treat owner_email as the cross-org authority and list\n   * views add their own org filters.\n   *\n   * Default: `false`.\n   */\n  ownerAccessIgnoresOrg?: boolean;\n}\n\n// Stash the registry on globalThis so it survives SSR bundle duplication.\n// Vite SSR's `noExternal: /^(?!node:)/` policy means @agent-native/core gets\n// inlined into every server bundle that imports it — and each bundle gets its\n// own module-level state. A plain `new Map()` here would create one Map per\n// bundle, so the template's `registerShareableResource()` (called from the\n// Nitro plugin graph) wouldn't be visible to the framework's auto-mounted\n// share-resource action (loaded via `import(\"../sharing/actions/...js\")` in a\n// different module instance). Using globalThis collapses them back to one Map.\nconst REGISTRY_KEY = \"__agentNativeShareableResources__\";\ntype RegistryStore = Map<string, ShareableResourceRegistration>;\nconst globalRegistry: { [K in typeof REGISTRY_KEY]?: RegistryStore } =\n  globalThis as any;\n\nfunction isTestRuntime(): boolean {\n  return (\n    process.env.NODE_ENV === \"test\" ||\n    process.env.VITEST === \"true\" ||\n    process.env.VITEST === \"1\"\n  );\n}\n\nfunction registrationCameFromTestFile(): boolean {\n  const stack = new Error().stack ?? \"\";\n  return /[./\\\\](?:[^/\\\\]+[.-])(?:test|spec)\\.[cm]?[jt]sx?(?::\\d+)?(?::\\d+)?/.test(\n    stack,\n  );\n}\n\nfunction getRegistry(): RegistryStore {\n  let r = globalRegistry[REGISTRY_KEY];\n  if (!r) {\n    r = new Map<string, ShareableResourceRegistration>();\n    globalRegistry[REGISTRY_KEY] = r;\n  }\n  return r;\n}\n\nexport function registerShareableResource(\n  entry: ShareableResourceRegistration,\n): void {\n  if (!isTestRuntime() && registrationCameFromTestFile()) return;\n  getRegistry().set(entry.type, entry);\n}\n\nexport function getShareableResource(\n  type: string,\n): ShareableResourceRegistration | undefined {\n  return getRegistry().get(type);\n}\n\nexport function requireShareableResource(\n  type: string,\n): ShareableResourceRegistration {\n  const reg = getRegistry();\n  const entry = reg.get(type);\n  if (!entry) {\n    throw new Error(\n      `Unknown shareable resource type: \"${type}\". Did you forget registerShareableResource()?`,\n    );\n  }\n  return entry;\n}\n\nexport function listShareableResources(): ShareableResourceRegistration[] {\n  return Array.from(getRegistry().values());\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/sharing/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA+GH,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEzD,MAAM,cAAc,GAClB,UAAiB,CAAC;AAEpB,SAAS,aAAa;IACpB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;QAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAC3B,CAAC;AACJ,CAAC;AAED,SAAS,4BAA4B;IACnC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;IACtC,OAAO,oEAAoE,CAAC,IAAI,CAC9E,KAAK,CACN,CAAC;AACJ,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,IAAI,GAAG,EAAyC,CAAC;QACrD,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,KAAoC;IAEpC,IAAI,CAAC,aAAa,EAAE,IAAI,4BAA4B,EAAE;QAAE,OAAO;IAC/D,WAAW,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAY;IAEZ,OAAO,WAAW,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,IAAY;IAEZ,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,gDAAgD,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * Registry of shareable resources.\n *\n * Each template registers its ownable resource(s) once on module load so the\n * framework-level share actions (`share-resource`, `list-resource-shares`,\n * etc.) can dispatch to the correct tables.\n *\n *   import { registerShareableResource } from \"@agent-native/core/sharing\";\n *   import * as schema from \"./schema.js\";\n *\n *   registerShareableResource({\n *     type: \"document\",\n *     resourceTable: schema.documents,\n *     sharesTable: schema.documentShares,\n *     displayName: \"Document\",\n *     titleColumn: \"title\",\n *   });\n */\n\nexport interface ShareableResourceRegistration {\n  /** Stable identifier used across actions, UI, and analytics. e.g. \"document\". */\n  type: string;\n  /** Drizzle table for the parent resource (must have ownableColumns()). */\n  resourceTable: any;\n  /** Drizzle table produced by createSharesTable(). */\n  sharesTable: any;\n  /** Human-readable singular label shown in the share dialog. */\n  displayName: string;\n  /**\n   * Column on the resource table that holds a human-readable title for\n   * display in the share UI. Default: \"title\".\n   */\n  titleColumn?: string;\n  /**\n   * Optional app-relative path to this resource. Used by share notifications\n   * when the caller does not pass a more specific resourceUrl.\n   */\n  getResourcePath?: (resource: any) => string | undefined;\n  /**\n   * Drizzle DB accessor from the template's server/db/index.ts. Required —\n   * the framework-level share actions and access helpers call this to reach\n   * the right DB instance (schema is template-specific).\n   */\n  getDb: () => any;\n  /**\n   * When `false`, `visibility: \"public\"` is rejected by `set-resource-visibility`,\n   * and `accessFilter` / `resolveAccess` treat any stored public row as private\n   * (defense in depth — only owner + explicit shares grant access).\n   *\n   * Use this for resources that execute code or expose privileged data and must\n   * never be reachable by a random authenticated user. Extensions set this:\n   * extension HTML runs inside an iframe that calls actions / DB / proxied APIs\n   * as the *viewer*, so a public extension would be arbitrary code with the\n   * viewer's credentials.\n   *\n   * Default: `true` (matches the historical behavior — most resources can be public).\n   */\n  allowPublic?: boolean;\n  /**\n   * Optional role granted by a public-by-link read. Most resources should omit\n   * this so public visibility remains viewer-only. Use narrowly for local or\n   * otherwise constrained resources where the resource owner intentionally wants\n   * unauthenticated link holders to do more than view.\n   */\n  publicAccessRole?:\n    | \"viewer\"\n    | \"editor\"\n    | \"admin\"\n    | ((\n        resource: any,\n        ctx: { userEmail?: string; orgId?: string },\n      ) =>\n        | \"viewer\"\n        | \"editor\"\n        | \"admin\"\n        | Promise<\"viewer\" | \"editor\" | \"admin\">);\n  /**\n   * When `true`, individual user shares (`principalType: \"user\"`) must target\n   * an email that is already a member of the same org as the resource, OR has\n   * a pending invitation to that org. Cross-org user shares are rejected.\n   *\n   * Pair with `allowPublic: false` for resources that need a hard \"this org\n   * only\" trust boundary. Extensions set this so a malicious caller can't\n   * widen reach by sharing a code-executing extension to an outsider email.\n   *\n   * Default: `false` (matches the historical behavior — any email can be granted).\n   */\n  requireOrgMemberForUserShares?: boolean;\n  /**\n   * Optional per-resource access-context adapter. Most resources should use the\n   * request user/org unchanged. Templates with an intentional alternate local\n   * identity can normalize here so the generic framework sharing actions and\n   * access helpers stay in sync with template-owned actions.\n   */\n  resolveAccessContext?: (ctx: { userEmail?: string; orgId?: string }) => {\n    userEmail?: string;\n    orgId?: string;\n  };\n  /**\n   * When true, direct ownership is recognized by owner_email regardless of the\n   * caller's active org. Use this only for resource types where the template's\n   * own actions already treat owner_email as the cross-org authority and list\n   * views add their own org filters.\n   *\n   * Default: `false`.\n   */\n  ownerAccessIgnoresOrg?: boolean;\n  /**\n   * Optional external-agent read handoff. When set, the framework-level\n   * `create-agent-resource-link` action can mint a short-lived, read-only\n   * `agent_access` URL for this resource. The context endpoint is owned by the\n   * template so it can expose the same intentionally shareable shape as the\n   * public page, not a generic raw database row.\n   */\n  agentReadable?:\n    | false\n    | {\n        /** Token scope. Include the app name to avoid cross-app collisions. */\n        resourceKind: string;\n        /** App-relative JSON endpoint that accepts `id` + `agent_access`. */\n        getContextPath: (resource: any) => string | undefined;\n        /** Optional override for the page URL. Defaults to getResourcePath. */\n        getPagePath?: (resource: any) => string | undefined;\n        /** Optional override for the default two-hour token lifetime. */\n        ttlSeconds?: number;\n      };\n}\n\n// Stash the registry on globalThis so it survives SSR bundle duplication.\n// Vite SSR's `noExternal: /^(?!node:)/` policy means @agent-native/core gets\n// inlined into every server bundle that imports it — and each bundle gets its\n// own module-level state. A plain `new Map()` here would create one Map per\n// bundle, so the template's `registerShareableResource()` (called from the\n// Nitro plugin graph) wouldn't be visible to the framework's auto-mounted\n// share-resource action (loaded via `import(\"../sharing/actions/...js\")` in a\n// different module instance). Using globalThis collapses them back to one Map.\nconst REGISTRY_KEY = \"__agentNativeShareableResources__\";\ntype RegistryStore = Map<string, ShareableResourceRegistration>;\nconst globalRegistry: { [K in typeof REGISTRY_KEY]?: RegistryStore } =\n  globalThis as any;\n\nfunction isTestRuntime(): boolean {\n  return (\n    process.env.NODE_ENV === \"test\" ||\n    process.env.VITEST === \"true\" ||\n    process.env.VITEST === \"1\"\n  );\n}\n\nfunction registrationCameFromTestFile(): boolean {\n  const stack = new Error().stack ?? \"\";\n  return /[./\\\\](?:[^/\\\\]+[.-])(?:test|spec)\\.[cm]?[jt]sx?(?::\\d+)?(?::\\d+)?/.test(\n    stack,\n  );\n}\n\nfunction getRegistry(): RegistryStore {\n  let r = globalRegistry[REGISTRY_KEY];\n  if (!r) {\n    r = new Map<string, ShareableResourceRegistration>();\n    globalRegistry[REGISTRY_KEY] = r;\n  }\n  return r;\n}\n\nexport function registerShareableResource(\n  entry: ShareableResourceRegistration,\n): void {\n  if (!isTestRuntime() && registrationCameFromTestFile()) return;\n  getRegistry().set(entry.type, entry);\n}\n\nexport function getShareableResource(\n  type: string,\n): ShareableResourceRegistration | undefined {\n  return getRegistry().get(type);\n}\n\nexport function requireShareableResource(\n  type: string,\n): ShareableResourceRegistration {\n  const reg = getRegistry();\n  const entry = reg.get(type);\n  if (!entry) {\n    throw new Error(\n      `Unknown shareable resource type: \"${type}\". Did you forget registerShareableResource()?`,\n    );\n  }\n  return entry;\n}\n\nexport function listShareableResources(): ShareableResourceRegistration[] {\n  return Array.from(getRegistry().values());\n}\n"]}

package/dist/styles/agent-native.css

@@ -41,6 +41,16 @@
    zoom-in/out, slide-in-from-*, spin-in, etc.). */
 @import "tw-animate-css";
 
+:root {
+  --agent-native-viewport-height: 100vh;
+}
+
+@supports (height: 100dvh) {
+  :root {
+    --agent-native-viewport-height: 100dvh;
+  }
+}
+
 /* Shared shell depth.
    Use these classes on app layouts that have a persistent left nav:
 
@@ -63,6 +73,8 @@
     var(--agent-native-raised-border);
   --agent-native-raised-shadow-left: -1px 0 3px rgb(0 0 0 / 0.018);
   --agent-native-raised-shadow-right: 1px 0 3px rgb(0 0 0 / 0.018);
+  height: var(--agent-native-viewport-height);
+  min-height: 0;
   background: var(--agent-native-lower-surface);
 }
 
@@ -90,16 +102,6 @@
       hsl(var(--sidebar-background, var(--background))) 94%,
       black
     );
-    --agent-native-raised-surface: color-mix(
-      in srgb,
-      hsl(var(--background)) 78%,
-      hsl(var(--muted)) 22%
-    );
-    --agent-native-card-surface: color-mix(
-      in srgb,
-      var(--agent-native-raised-surface) 88%,
-      hsl(var(--muted)) 12%
-    );
   }
 }
 
@@ -167,43 +169,45 @@
   container: agent-native-main / inline-size;
 }
 
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :first-child
-  > :where(header, div).border-b,
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :where(header, div).border-b,
-.agent-layout-shell
-  .agent-layout-left-drawer
-  > :where(header, div).border-b:first-child,
-.agent-layout-shell
-  .agent-layout-left-drawer
-  > :first-child
-  > :where(header, div).border-b,
-.agent-layout-shell .agent-native-shell-topbar {
-  border-bottom-color: transparent !important;
-}
+@media (min-width: 768px) {
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :first-child
+    > :where(header, div).border-b,
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :where(header, div).border-b,
+  .agent-layout-shell
+    .agent-layout-left-drawer
+    > :where(header, div).border-b:first-child,
+  .agent-layout-shell
+    .agent-layout-left-drawer
+    > :first-child
+    > :where(header, div).border-b,
+  .agent-layout-shell .agent-native-shell-topbar {
+    border-bottom-color: transparent !important;
+  }
 
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :first-child
-  > :where(header, div).border-b,
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :where(header, div).border-b {
-  background-color: var(--agent-native-raised-surface) !important;
-}
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :first-child
+    > :where(header, div).border-b,
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :where(header, div).border-b {
+    background-color: var(--agent-native-raised-surface) !important;
+  }
 
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :first-child
-  > :where(header, div).border-b.h-12,
-.agent-layout-shell
-  :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
-  > :where(header, div).border-b.h-12 {
-  min-height: 4rem;
-  height: 4rem;
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :first-child
+    > :where(header, div).border-b.h-12,
+  .agent-layout-shell
+    :where(.agent-layout-main-surface, .agent-sidebar-main-surface)
+    > :where(header, div).border-b.h-12 {
+    min-height: 4rem;
+    height: 4rem;
+  }
 }
 
 .dark
@@ -699,6 +703,14 @@
   width: 100%;
 }
 
+/* Plan-mode callout pill: lives inside .agent-composer-stack directly above
+   the composer. Matching .agent-composer-area's own width keeps the pill
+   visually attached to (and right-aligned with) the composer instead of the
+   full pane, whether the pane is a narrow sidebar or a wide centered page. */
+.agent-plan-mode-callout {
+  width: 100%;
+}
+
 [data-agent-empty-state="centered"] {
   justify-content: center;
 }

package/dist/templates/default/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/dist/templates/default/AGENTS.md

@@ -121,22 +121,19 @@ capability is missing, add or extend a `defineAction` so both the agent and UI
 share the same operation. Do not create `/api/*` routes that only call,
 repackage, or proxy an action.
 
-| Action        | Args                                                                           | Purpose                                                                                 |
-| ------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `view-screen` |                                                                                | See current UI state                                                                    |
-| `navigate`    | `--view <name>` or `--path <url>`                                              | Navigate the UI                                                                         |
-| `hello`       | `[--name <name>]`                                                              | Example script                                                                          |
-| `db-schema`   |                                                                                | Show all tables, columns, types                                                         |
-| `db-query`    | `--sql "SELECT ..."`                                                           | Run a SELECT query                                                                      |
-| `db-exec`     | `--sql "UPDATE ..."`                                                           | Last-resort ad-hoc maintenance; prefer domain actions and Drizzle code for product work |
-| `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
-
-**For one-off maintenance, pick the right SQL tool:**
+| Action        | Args                              | Purpose                         |
+| ------------- | --------------------------------- | ------------------------------- |
+| `view-screen` |                                   | See current UI state            |
+| `navigate`    | `--view <name>` or `--path <url>` | Navigate the UI                 |
+| `hello`       | `[--name <name>]`                 | Example script                  |
+| `db-schema`   |                                   | Show all tables, columns, types |
+| `db-query`    | `--sql "SELECT ..."`              | Run a SELECT query              |
+
+**For data changes, pick the right surface:**
 
 - Use domain actions first. They validate input, enforce access, and refresh the UI.
-- Use `db-exec UPDATE` only when no domain action exists and you need a small ad-hoc change.
-- Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
-- If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
+- Use `db-query` / `db-schema` for read-only inspection.
+- Raw write SQL (`db-exec` / `db-patch`) is not part of the default agent surface. If this app explicitly opts into `databaseTools: "write"`, use those tools only for deliberate maintenance when no domain action exists.
 - **Database admin (dev only):** in development, `db-admin-query` / `db-admin-mutate` / `db-admin-rows` / `db-admin-tables` / `db-admin-schema` give **unscoped, full-database** access to ANY table — including framework tables and tables without `owner_email`/`org_id`. Prefer these over `db-exec`/`db-query` for database-admin work and for any non-owner-scoped table: `db-exec`/`db-query` auto-scope to the current user and return **0 rows** on unscoped tables. These mirror the in-app Database admin UI, so prompts and the UI do the same thing.
 
 ## Skills

package/dist/templates/default/actions/navigate.ts

@@ -12,7 +12,7 @@ export default defineAction({
   http: false,
   run: async (args) => {
     if (!args.view && !args.path) {
-      return "Error: At least --view or --path is required.";
+      throw new Error("At least --view or --path is required.");
     }
     const nav: Record<string, string> = {};
     if (args.view) nav.view = args.view;

package/dist/templates/default/app/i18n/ar-SA.ts

@@ -303,7 +303,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "ماذا يجب أن تفعل؟",
     createPlaceholder: "قائمة المهام، لوحة تحكم API، آلة حاسبة...",
-    backToApp: "العودة إلى التطبيق",
     title: "الإضافات",
     hiddenShown: "يظهر الإخفاء",
     showHidden: "إظهار المخفية",

package/dist/templates/default/app/i18n/de-DE.ts

@@ -295,7 +295,6 @@ const messages = {
     whatShouldItDo: "Was soll es tun?",
     createPlaceholder:
       "Eine Aufgabenliste, ein API-Dashboard, ein Taschenrechner ...",
-    backToApp: "Zurück zur App",
     title: "Erweiterungen",
     hiddenShown: "Versteckt angezeigt",
     showHidden: "Ausgeblendete anzeigen",

package/dist/templates/default/app/i18n/en-US.ts

@@ -288,7 +288,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "What should it do?",
     createPlaceholder: "A todo list, API dashboard, calculator...",
-    backToApp: "Back to app",
     title: "Extensions",
     hiddenShown: "Hiding shown",
     showHidden: "Show hidden",

package/dist/templates/default/app/i18n/es-ES.ts

@@ -300,7 +300,6 @@ const messages = {
     whatShouldItDo: "¿Qué debería hacer?",
     createPlaceholder:
       "Una lista de tareas pendientes, panel API, calculadora...",
-    backToApp: "Volver a la aplicación",
     title: "Extensiones",
     hiddenShown: "Ocultando mostrado",
     showHidden: "Mostrar ocultos",

package/dist/templates/default/app/i18n/fr-FR.ts

@@ -299,7 +299,6 @@ const messages = {
     whatShouldItDo: "Que devrait-il faire ?",
     createPlaceholder:
       "Une liste de tâches, un tableau de bord API, une calculatrice...",
-    backToApp: "Retour à l'application",
     title: "Rallonges",
     hiddenShown: "Masquer affiché",
     showHidden: "Afficher les éléments masqués",

package/dist/templates/default/app/i18n/hi-IN.ts

@@ -284,7 +284,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "इसे क्या करना चाहिए?",
     createPlaceholder: "एक कार्य सूची, एपीआई डैशबोर्ड, कैलकुलेटर...",
-    backToApp: "ऐप पर वापस जाएं",
     title: "एक्सटेंशन",
     hiddenShown: "छिपाव दिखाया गया",
     showHidden: "छिपे हुए दिखाएं",

package/dist/templates/default/app/i18n/ja-JP.ts

@@ -287,7 +287,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "それは何をすべきでしょうか？",
     createPlaceholder: "ToDo リスト、API ダッシュボード、電卓...",
-    backToApp: "アプリに戻る",
     title: "拡張機能",
     hiddenShown: "非表示を表示",
     showHidden: "非表示を表示",

package/dist/templates/default/app/i18n/ko-KR.ts

@@ -283,7 +283,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "무엇을 해야 합니까?",
     createPlaceholder: "할 일 목록, API 대시보드, 계산기...",
-    backToApp: "앱으로 돌아가기",
     title: "확장",
     hiddenShown: "숨김 표시됨",
     showHidden: "숨김 항목 표시",

package/dist/templates/default/app/i18n/pt-BR.ts

@@ -298,7 +298,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "O que deveria fazer?",
     createPlaceholder: "Uma lista de tarefas, painel de API, calculadora...",
-    backToApp: "Voltar ao aplicativo",
     title: "Extensões",
     hiddenShown: "Ocultando mostrado",
     showHidden: "Mostrar ocultos",

package/dist/templates/default/app/i18n/zh-CN.ts

@@ -276,7 +276,6 @@ const messages = {
       'Create a new widget that fits in slot "{{slotId}}". I\'ll describe what it should do next.',
     whatShouldItDo: "它应该做什么？",
     createPlaceholder: "待办事项列表、API 仪表板、计算器...",
-    backToApp: "返回应用程序",
     title: "扩展",
     hiddenShown: "显示隐藏",
     showHidden: "显示隐藏项",

package/dist/templates/default/app/i18n/zh-TW.ts

@@ -276,7 +276,6 @@ const messages = {
       "建立一個適合「{{slotId}}」插槽的新小工具。我接著會描述它應該做什麼。",
     whatShouldItDo: "它應該做什麼？",
     createPlaceholder: "待辦事項清單、API 儀表板、計算器...",
-    backToApp: "返回應用程式",
     title: "擴充功能",
     hiddenShown: "顯示隱藏",
     showHidden: "顯示隱藏項",

package/dist/templates/default/app/routes/settings.tsx

@@ -1,6 +1,7 @@
 import {
   LanguagePicker,
-  openAgentSettings,
+  SettingsTabsPage,
+  useAgentSettingsTabs,
   useT,
 } from "@agent-native/core/client";
 import { Link } from "react-router";
@@ -11,10 +12,11 @@ export function meta() {
 
 export default function SettingsPage() {
   const t = useT();
+  const agentSettingsTabs = useAgentSettingsTabs();
 
   return (
     <main className="min-h-screen bg-background px-6 py-10">
-      <div className="mx-auto w-full max-w-2xl space-y-6">
+      <div className="mx-auto w-full max-w-5xl space-y-6">
         <div className="space-y-2">
           <Link
             to="/"
@@ -30,37 +32,24 @@ export default function SettingsPage() {
           </p>
         </div>
 
-        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
-          <div className="space-y-1">
-            <h2 className="text-[15px] font-semibold text-foreground">
-              {t("settings.languageTitle")}
-            </h2>
-            <p className="text-[13px] leading-relaxed text-muted-foreground">
-              {t("settings.languageDescription")}
-            </p>
-          </div>
-          <div className="mt-4 max-w-xs">
-            <LanguagePicker label={t("settings.languageLabel")} />
-          </div>
-        </section>
-
-        <section className="rounded-lg border border-border/50 bg-card px-4 py-4">
-          <div className="space-y-1">
-            <h2 className="text-[15px] font-semibold text-foreground">
-              {t("settings.agentTitle")}
-            </h2>
-            <p className="text-[13px] leading-relaxed text-muted-foreground">
-              {t("settings.agentDescription")}
-            </p>
-          </div>
-          <button
-            type="button"
-            className="mt-4 rounded-md border border-border bg-background px-3 py-2 text-[13px] font-medium text-foreground transition-colors hover:bg-accent/50"
-            onClick={() => openAgentSettings()}
-          >
-            {t("settings.openAgentSettings")}
-          </button>
-        </section>
+        <SettingsTabsPage
+          extraTabs={agentSettingsTabs}
+          general={
+            <section className="mx-auto w-full max-w-2xl rounded-lg border border-border/50 bg-card px-4 py-4">
+              <div className="space-y-1">
+                <h2 className="text-[15px] font-semibold text-foreground">
+                  {t("settings.languageTitle")}
+                </h2>
+                <p className="text-[13px] leading-relaxed text-muted-foreground">
+                  {t("settings.languageDescription")}
+                </p>
+              </div>
+              <div className="mt-4 max-w-xs">
+                <LanguagePicker label={t("settings.languageLabel")} />
+              </div>
+            </section>
+          }
+        />
       </div>
     </main>
   );

package/dist/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: agent-native-docs
 description: >-
-  How to find version-matched Agent Native framework docs bundled in
+  How to find version-matched Agent Native framework docs and source bundled in
   node_modules. Use before implementing or answering questions about
-  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
 metadata:
   internal: true
 ---
@@ -13,13 +15,17 @@ metadata:
 ## Rule
 
 Before implementing or explaining non-trivial Agent Native behavior, read the
-version-matched docs installed with `@agent-native/core`.
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
 
 ## Why
 
 Generated apps and workspaces may be on a different framework version than the
 public docs or model memory. The installed package is the source that matches
-the app in front of you.
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
 
 ## How
 
@@ -29,19 +35,26 @@ From a generated app directory:
 pnpm action docs-search --query "<feature>"
 pnpm action docs-search --slug <slug>
 pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --list
 ```
 
 The headless `pnpm agent` loop and built-in app agent also expose a read-only
-`docs-search` tool with the same `query`, `slug`, and `list` options.
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
 
-If the action runner is unavailable, search the package docs directly:
+If the action runner is unavailable, search the package directly:
 
 ```bash
 rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ```
 
 Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
-under `node_modules/@agent-native/core/docs/content/`.
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
 
 ## Useful Slugs
 

package/dist/templates/headless/AGENTS.md

@@ -45,12 +45,15 @@ root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
 
 ## Actions
 
-| Action      | Args              | Purpose                 |
-| ----------- | ----------------- | ----------------------- |
-| `hello`     | `[--name <name>]` | Return a greeting       |
-| `db-schema` |                   | Show SQL schema         |
-| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT     |
-| `db-exec`   | `--sql "UPDATE"`  | Last-resort maintenance |
+| Action      | Args              | Purpose             |
+| ----------- | ----------------- | ------------------- |
+| `hello`     | `[--name <name>]` | Return a greeting   |
+| `db-schema` |                   | Show SQL schema     |
+| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT |
+
+Raw SQL writes are not exposed by default. Add or update a typed action for app
+data writes; opt into `databaseTools: "write"` only for deliberate maintenance
+surfaces.
 
 Run actions from this app root: