@agent-native/core 0.72.4 → 0.74.0

package/dist/server/self-dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"self-dispatch.js","sourceRoot":"","sources":["../../src/server/self-dispatch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared self-dispatch helper for the framework's serverless background-work\n * pattern: enqueue a unit of work to SQL, then fire a fresh HTTP POST back to\n * this same deployment so the work runs in its own function invocation (with\n * its own full timeout budget) instead of riding on the request that created\n * it.\n *\n * This is the single mechanism that makes background work portable across every\n * host Nitro deploys to:\n *   - Netlify Lambda / Vercel Functions / AWS Lambda — the dispatched request\n *     hits a fresh function with its own budget; no `waitUntil` needed.\n *   - Cloudflare Workers — same (and `waitUntil` still works as a belt-and-\n *     suspenders fallback where the in-process path is used).\n *   - Self-hosted / long-lived Node — the dispatch comes back as another\n *     request to the same process; each handler still runs to completion.\n *\n * Originally inlined in both `a2a/handlers.ts` (`resolveSelfBaseUrl` +\n * `fireProcessTaskDispatch`) and `integrations/webhook-handler.ts`\n * (`resolveBaseUrl` + the dispatch in `enqueueAndDispatch`). Extracted here so\n * A2A, integration webhooks, and Agent Teams sub-agents share one tested\n * implementation.\n */\nimport { withConfiguredAppBasePath } from \"./app-base-path.js\";\nimport { isLocalDatabase } from \"../db/client.js\";\nimport { signInternalToken } from \"../integrations/internal-token.js\";\n\n/**\n * On serverless, returning from the dispatching handler before the outbound\n * TCP handshake starts can freeze the function with the dispatch request stuck\n * in the queue. Racing the fetch against a short timer gives the request a\n * chance to leave the box at the cost of a little added latency on the\n * dispatching call. Mirrors the 250ms used by the A2A/webhook paths.\n */\nexport const DEFAULT_DISPATCH_SETTLE_MS = 250;\n\nfunction readHeader(event: any, name: string): string | undefined {\n  try {\n    const headers = event?.node?.req?.headers ?? event?.headers;\n    if (!headers) return undefined;\n    if (typeof headers.get === \"function\") {\n      return headers.get(name) ?? undefined;\n    }\n    const map = headers as Record<string, string | undefined>;\n    return map[name] ?? map[String(name).toLowerCase()];\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve the base URL to fire a self-dispatch request at. Prefers explicit env\n * vars (most reliable on serverless, where inbound host headers can be the\n * platform's internal hostname), falling back to the inbound request headers\n * and finally localhost in dev.\n *\n * Throws in production / shared deployments when no env var is set — a silent\n * fallback to a bad host there would drop background work invisibly.\n */\nexport function resolveSelfDispatchBaseUrl(event?: any): string {\n  const fromEnv =\n    process.env.APP_URL ||\n    process.env.URL ||\n    process.env.DEPLOY_URL ||\n    process.env.BETTER_AUTH_URL;\n  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));\n\n  if (process.env.NODE_ENV === \"production\" || !isLocalDatabase()) {\n    throw new Error(\n      \"Self-dispatch requires APP_URL, URL, DEPLOY_URL, or BETTER_AUTH_URL in \" +\n        \"production/shared deployments so background work can reach this \" +\n        \"deployment's own URL.\",\n    );\n  }\n\n  const proto = readHeader(event, \"x-forwarded-proto\") || \"http\";\n  const host =\n    readHeader(event, \"host\") || `localhost:${process.env.PORT || 3000}`;\n  return withConfiguredAppBasePath(`${proto}://${host}`);\n}\n\nexport interface FireInternalDispatchOptions {\n  /** Base URL of this deployment. Defaults to `resolveSelfDispatchBaseUrl(event)`. */\n  baseUrl?: string;\n  /** Request event used to derive the base URL when `baseUrl` is omitted. */\n  event?: any;\n  /** Framework route path to POST to (e.g. \"/_agent-native/agent-teams/_process-run\"). */\n  path: string;\n  /** Task/run id the processor will claim. Used to sign the HMAC token and as the default body. */\n  taskId: string;\n  /** Extra fields merged into the JSON body alongside `{ taskId }`. */\n  body?: Record<string, unknown>;\n  /** Max ms to wait for the outbound request to leave the box. Default 250ms. */\n  settleMs?: number;\n}\n\nasync function dispatchResponseError(\n  path: string,\n  res: Response,\n): Promise<Error> {\n  let body = \"\";\n  try {\n    body = (await res.text()).trim();\n  } catch {\n    body = \"\";\n  }\n  const detail = body ? `: ${body.slice(0, 300)}` : \"\";\n  return new Error(\n    `Self-dispatch to ${path} returned HTTP ${res.status} ${res.statusText}${detail}`,\n  );\n}\n\n/**\n * Fire a fresh, HMAC-signed POST to a processor route on this same deployment.\n * Fire-and-forget: the dispatch is NOT awaited to completion (the processed run\n * may take minutes); it is only raced against a short settle timer so the\n * request reliably leaves a serverless box before it freezes.\n *\n * When `A2A_SECRET` is unset (local dev), the request is sent unsigned — the\n * processor accepts unsigned dispatches in dev and relies on the SQL atomic\n * claim for double-processing protection, mirroring the A2A/webhook flow.\n */\nexport async function fireInternalDispatch(\n  options: FireInternalDispatchOptions,\n): Promise<void> {\n  const baseUrl = options.baseUrl ?? resolveSelfDispatchBaseUrl(options.event);\n  const url = `${baseUrl}${options.path}`;\n  const headers: Record<string, string> = {\n    \"Content-Type\": \"application/json\",\n  };\n  try {\n    headers[\"Authorization\"] = `Bearer ${signInternalToken(options.taskId)}`;\n  } catch (err) {\n    // Distinguish the documented \"no A2A_SECRET in dev\" path from a real\n    // signing failure, so a malformed secret doesn't fail invisibly.\n    if (err instanceof Error && !/A2A_SECRET/i.test(err.message)) {\n      console.error(\n        `[self-dispatch] signInternalToken failed unexpectedly for ${options.taskId}:`,\n        err,\n      );\n    }\n  }\n\n  const dispatchPromise = fetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ taskId: options.taskId, ...(options.body ?? {}) }),\n  }).then(async (res) => {\n    if (!res.ok) {\n      throw await dispatchResponseError(options.path, res);\n    }\n  });\n  dispatchPromise.catch((err) => {\n    console.error(`[self-dispatch] dispatch to ${options.path} failed:`, err);\n  });\n\n  const settleMs = options.settleMs ?? DEFAULT_DISPATCH_SETTLE_MS;\n  await Promise.race([\n    dispatchPromise,\n    new Promise<void>((resolve) => setTimeout(resolve, settleMs)),\n  ]);\n}\n"]}
+{"version":3,"file":"self-dispatch.js","sourceRoot":"","sources":["../../src/server/self-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C,SAAS,UAAU,CAAC,KAAU,EAAE,IAAY;IAC1C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,IAAI,KAAK,EAAE,OAAO,CAAC;QAC5D,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAC/B,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;YACtC,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;QACxC,CAAC;QACD,MAAM,GAAG,GAAG,OAA6C,CAAC;QAC1D,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAW;IACpD,MAAM,OAAO,GACX,OAAO,CAAC,GAAG,CAAC,OAAO;QACnB,OAAO,CAAC,GAAG,CAAC,GAAG;QACf,OAAO,CAAC,GAAG,CAAC,UAAU;QACtB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9B,IAAI,OAAO;QAAE,OAAO,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAE/D,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,kEAAkE;YAClE,uBAAuB,CAC1B,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,mBAAmB,CAAC,IAAI,MAAM,CAAC;IAC/D,MAAM,IAAI,GACR,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,aAAa,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;IACvE,OAAO,yBAAyB,CAAC,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC;AAiBD,KAAK,UAAU,qBAAqB,CAClC,IAAY,EACZ,GAAa;IAEb,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrD,OAAO,IAAI,KAAK,CACd,oBAAoB,IAAI,kBAAkB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,GAAG,MAAM,EAAE,CAClF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAoC;IAEpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,0BAA0B,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;KACnC,CAAC;IACF,IAAI,CAAC;QACH,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAC3E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,iEAAiE;QACjE,IAAI,GAAG,YAAY,KAAK,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,KAAK,CACX,6DAA6D,OAAO,CAAC,MAAM,GAAG,EAC9E,GAAG,CACJ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,GAAG,EAAE;QACjC,MAAM,EAAE,MAAM;QACd,OAAO;QACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;KAC1E,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACpB,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,MAAM,qBAAqB,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC,CAAC;IACH,eAAe,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5B,0EAA0E;QAC1E,2EAA2E;QAC3E,0EAA0E;QAC1E,6DAA6D;QAC7D,OAAO,CAAC,KAAK,CACX,+BAA+B,OAAO,CAAC,IAAI,UAAU,OAAO,WAAW,EACvE,GAAG,CACJ,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,0BAA0B,CAAC;IAChE,MAAM,OAAO,CAAC,IAAI,CAAC;QACjB,eAAe;QACf,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;KAC9D,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Shared self-dispatch helper for the framework's serverless background-work\n * pattern: enqueue a unit of work to SQL, then fire a fresh HTTP POST back to\n * this same deployment so the work runs in its own function invocation (with\n * its own full timeout budget) instead of riding on the request that created\n * it.\n *\n * This is the single mechanism that makes background work portable across every\n * host Nitro deploys to:\n *   - Netlify Lambda / Vercel Functions / AWS Lambda — the dispatched request\n *     hits a fresh function with its own budget; no `waitUntil` needed.\n *   - Cloudflare Workers — same (and `waitUntil` still works as a belt-and-\n *     suspenders fallback where the in-process path is used).\n *   - Self-hosted / long-lived Node — the dispatch comes back as another\n *     request to the same process; each handler still runs to completion.\n *\n * Originally inlined in both `a2a/handlers.ts` (`resolveSelfBaseUrl` +\n * `fireProcessTaskDispatch`) and `integrations/webhook-handler.ts`\n * (`resolveBaseUrl` + the dispatch in `enqueueAndDispatch`). Extracted here so\n * A2A, integration webhooks, and Agent Teams sub-agents share one tested\n * implementation.\n */\nimport { withConfiguredAppBasePath } from \"./app-base-path.js\";\nimport { isLocalDatabase } from \"../db/client.js\";\nimport { signInternalToken } from \"../integrations/internal-token.js\";\n\n/**\n * On serverless, returning from the dispatching handler before the outbound\n * TCP handshake starts can freeze the function with the dispatch request stuck\n * in the queue. Racing the fetch against a short timer gives the request a\n * chance to leave the box at the cost of a little added latency on the\n * dispatching call. Mirrors the 250ms used by the A2A/webhook paths.\n */\nexport const DEFAULT_DISPATCH_SETTLE_MS = 250;\n\nfunction readHeader(event: any, name: string): string | undefined {\n  try {\n    const headers = event?.node?.req?.headers ?? event?.headers;\n    if (!headers) return undefined;\n    if (typeof headers.get === \"function\") {\n      return headers.get(name) ?? undefined;\n    }\n    const map = headers as Record<string, string | undefined>;\n    return map[name] ?? map[String(name).toLowerCase()];\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve the base URL to fire a self-dispatch request at. Prefers explicit env\n * vars (most reliable on serverless, where inbound host headers can be the\n * platform's internal hostname), falling back to the inbound request headers\n * and finally localhost in dev.\n *\n * Throws in production / shared deployments when no env var is set — a silent\n * fallback to a bad host there would drop background work invisibly.\n */\nexport function resolveSelfDispatchBaseUrl(event?: any): string {\n  const fromEnv =\n    process.env.APP_URL ||\n    process.env.URL ||\n    process.env.DEPLOY_URL ||\n    process.env.BETTER_AUTH_URL;\n  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));\n\n  if (process.env.NODE_ENV === \"production\" || !isLocalDatabase()) {\n    throw new Error(\n      \"Self-dispatch requires APP_URL, URL, DEPLOY_URL, or BETTER_AUTH_URL in \" +\n        \"production/shared deployments so background work can reach this \" +\n        \"deployment's own URL.\",\n    );\n  }\n\n  const proto = readHeader(event, \"x-forwarded-proto\") || \"http\";\n  const host =\n    readHeader(event, \"host\") || `localhost:${process.env.PORT || 3000}`;\n  return withConfiguredAppBasePath(`${proto}://${host}`);\n}\n\nexport interface FireInternalDispatchOptions {\n  /** Base URL of this deployment. Defaults to `resolveSelfDispatchBaseUrl(event)`. */\n  baseUrl?: string;\n  /** Request event used to derive the base URL when `baseUrl` is omitted. */\n  event?: any;\n  /** Framework route path to POST to (e.g. \"/_agent-native/agent-teams/_process-run\"). */\n  path: string;\n  /** Task/run id the processor will claim. Used to sign the HMAC token and as the default body. */\n  taskId: string;\n  /** Extra fields merged into the JSON body alongside `{ taskId }`. */\n  body?: Record<string, unknown>;\n  /** Max ms to wait for the outbound request to leave the box. Default 250ms. */\n  settleMs?: number;\n}\n\nasync function dispatchResponseError(\n  path: string,\n  res: Response,\n): Promise<Error> {\n  let body = \"\";\n  try {\n    body = (await res.text()).trim();\n  } catch {\n    body = \"\";\n  }\n  const detail = body ? `: ${body.slice(0, 300)}` : \"\";\n  return new Error(\n    `Self-dispatch to ${path} returned HTTP ${res.status} ${res.statusText}${detail}`,\n  );\n}\n\n/**\n * Fire a fresh, HMAC-signed POST to a processor route on this same deployment.\n * Fire-and-forget: the dispatch is NOT awaited to completion (the processed run\n * may take minutes); it is only raced against a short settle timer so the\n * request reliably leaves a serverless box before it freezes.\n *\n * When `A2A_SECRET` is unset (local dev), the request is sent unsigned — the\n * processor accepts unsigned dispatches in dev and relies on the SQL atomic\n * claim for double-processing protection, mirroring the A2A/webhook flow.\n */\nexport async function fireInternalDispatch(\n  options: FireInternalDispatchOptions,\n): Promise<void> {\n  const baseUrl = options.baseUrl ?? resolveSelfDispatchBaseUrl(options.event);\n  const url = `${baseUrl}${options.path}`;\n  const headers: Record<string, string> = {\n    \"Content-Type\": \"application/json\",\n  };\n  try {\n    headers[\"Authorization\"] = `Bearer ${signInternalToken(options.taskId)}`;\n  } catch (err) {\n    // Distinguish the documented \"no A2A_SECRET in dev\" path from a real\n    // signing failure, so a malformed secret doesn't fail invisibly.\n    if (err instanceof Error && !/A2A_SECRET/i.test(err.message)) {\n      console.error(\n        `[self-dispatch] signInternalToken failed unexpectedly for ${options.taskId}:`,\n        err,\n      );\n    }\n  }\n\n  const dispatchPromise = fetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify({ taskId: options.taskId, ...(options.body ?? {}) }),\n  }).then(async (res) => {\n    if (!res.ok) {\n      throw await dispatchResponseError(options.path, res);\n    }\n  });\n  dispatchPromise.catch((err) => {\n    // Include the resolved base URL: a self-dispatch failure is almost always\n    // about *which* host we POST to (custom domain behind an edge/auth wall vs\n    // the deploy URL), and that is invisible from the error alone. Keeps prod\n    // logs diagnostic without changing the URL resolution order.\n    console.error(\n      `[self-dispatch] dispatch to ${options.path} (base ${baseUrl}) failed:`,\n      err,\n    );\n  });\n\n  const settleMs = options.settleMs ?? DEFAULT_DISPATCH_SETTLE_MS;\n  await Promise.race([\n    dispatchPromise,\n    new Promise<void>((resolve) => setTimeout(resolve, settleMs)),\n  ]);\n}\n"]}

package/dist/templates/default/AGENTS.md

@@ -38,6 +38,10 @@ Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
 app-specific rules, then use the corpus for reusable framework/template
 patterns.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the app
+root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ### Database Code
 

package/dist/templates/default/package.json

@@ -8,7 +8,8 @@
     "start": "agent-native start",
     "typecheck": "agent-native typecheck",
     "action": "agent-native action",
-    "script": "agent-native script"
+    "script": "agent-native script",
+    "skills:update": "agent-native skills update scaffold --project"
   },
   "dependencies": {
     "@agent-native/core": "latest",

package/dist/templates/headless/AGENTS.md

@@ -38,6 +38,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` for app-specific rules, then use
 the corpus for reusable framework/template patterns.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the app
+root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ## Actions
 

package/dist/templates/headless/package.json

@@ -6,6 +6,7 @@
     "action": "agent-native action",
     "agent": "agent-native agent",
     "script": "agent-native script",
+    "skills:update": "agent-native skills update scaffold --project",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/dist/templates/workspace-root/AGENTS.md

@@ -27,6 +27,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus
 `packages/shared/.agents/skills/` for workspace-specific conventions.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the
+workspace root to refresh framework-provided shared skills and repair
+`CLAUDE.md` / `.claude/skills` compatibility links.
 
 ## Core Agent Rule
 

package/dist/templates/workspace-root/README.md

@@ -35,6 +35,10 @@ the shared package (`@{{APP_NAME}}/shared`).
 
 The workspace root also links `.agents/skills` to the shared package so coding
 agents launched from the root can discover the same workspace-wide skills.
+Run `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) after updating
+`@agent-native/core` to refresh framework-provided shared skills and repair
+Claude compatibility links.
 
 Runtime-editable global resources live in Dispatch, not in `packages/shared`.
 Use Dispatch **Resources** for company context and guardrails that admins should

package/dist/templates/workspace-root/package.json

@@ -7,6 +7,7 @@
     "build": "pnpm -r build",
     "typecheck": "pnpm -r typecheck",
     "repair:workspace-org": "tsx scripts/repair-workspace-org.ts",
+    "skills:update": "agent-native skills update scaffold --project",
     "fmt:check": "prettier --check .",
     "lint": "pnpm fmt:check"
   },

package/docs/content/skills-guide.md

@@ -264,3 +264,17 @@ npx @agent-native/core@latest skills update visual-plan
 the copied folder hash to the latest bundled skill, and rewrites stale folders in
 place. Newly copied Agent Native skills include an `agent-native-skill.json`
 marker so future status output can identify the source and hash.
+
+Generated Agent Native apps and workspaces also include framework-provided
+skills under `.agents/skills` (or `packages/shared/.agents/skills` in a
+workspace). Refresh those scaffolded skills from the current/latest CLI with:
+
+```bash
+npm run skills:update
+# or, without relying on the local package script:
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` and `.agents/skills` stay canonical. The update command also repairs
+Claude compatibility links (`CLAUDE.md` and `.claude/skills`) so Claude Code sees
+the same instructions without maintaining a second copy.

package/docs/content/template-clips.md

@@ -15,7 +15,7 @@ A capture-everything app: screen recordings, meeting notes from your calendar, a
 }
 ```
 
-Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's. Clips also makes shared recordings agent-readable: paste a normal Clips share link into an agent, and it can "hear" the transcript and "see" timestamped frames even when the underlying model cannot ingest raw video or audio.
+Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's. Clips also makes shared recordings agent-readable: paste a normal Clips share link into an agent and it can "hear" the transcript as text and "see" timestamped screen frames as images — no raw video needed. Frame-viewing works in any image-capable agent (ChatGPT, Claude Code, Cursor, Codex); text-only web chats still get the full transcript and can take a frame you upload.
 
 ```an-diagram title="Capture, transcribe, reuse" summary="Three capture types land in one library; the agent transcribes, titles, and summarizes, then every transcript is searchable and shareable."
 {
@@ -69,6 +69,12 @@ a compact agent context URL, and that context points to the transcript and frame
 APIs, so models that only accept text or still images can still understand what
 happened in the recording.
 
+Any agent that can fetch an image URL into its vision — ChatGPT, Claude Code,
+Cursor, Codex, and MCP-connected agents — reads the transcript and sees the
+frames. A few text-only web chats read the transcript but won't pull frame images
+in on their own; there, upload a key frame or open the clip in an image-capable
+agent.
+
 | Endpoint                                          | What agents get                                                                                                |
 | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript status, chapters, CTAs, recommended frames, and links to the transcript/frame APIs   |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.72.4",
+  "version": "0.74.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/default/AGENTS.md

@@ -38,6 +38,10 @@ Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
 app-specific rules, then use the corpus for reusable framework/template
 patterns.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the app
+root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ### Database Code
 

package/src/templates/default/package.json

@@ -8,7 +8,8 @@
     "start": "agent-native start",
     "typecheck": "agent-native typecheck",
     "action": "agent-native action",
-    "script": "agent-native script"
+    "script": "agent-native script",
+    "skills:update": "agent-native skills update scaffold --project"
   },
   "dependencies": {
     "@agent-native/core": "latest",

package/src/templates/headless/AGENTS.md

@@ -38,6 +38,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` for app-specific rules, then use
 the corpus for reusable framework/template patterns.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the app
+root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ## Actions
 

package/src/templates/headless/package.json

@@ -6,6 +6,7 @@
     "action": "agent-native action",
     "agent": "agent-native agent",
     "script": "agent-native script",
+    "skills:update": "agent-native skills update scaffold --project",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/src/templates/workspace-root/AGENTS.md

@@ -27,6 +27,10 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus
 `packages/shared/.agents/skills/` for workspace-specific conventions.
+After updating `@agent-native/core`, run `pnpm skills:update` or
+`npx @agent-native/core@latest skills update scaffold --project` from the
+workspace root to refresh framework-provided shared skills and repair
+`CLAUDE.md` / `.claude/skills` compatibility links.
 
 ## Core Agent Rule
 

package/src/templates/workspace-root/README.md

@@ -35,6 +35,10 @@ the shared package (`@{{APP_NAME}}/shared`).
 
 The workspace root also links `.agents/skills` to the shared package so coding
 agents launched from the root can discover the same workspace-wide skills.
+Run `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) after updating
+`@agent-native/core` to refresh framework-provided shared skills and repair
+Claude compatibility links.
 
 Runtime-editable global resources live in Dispatch, not in `packages/shared`.
 Use Dispatch **Resources** for company context and guardrails that admins should

package/src/templates/workspace-root/package.json

@@ -7,6 +7,7 @@
     "build": "pnpm -r build",
     "typecheck": "pnpm -r typecheck",
     "repair:workspace-org": "tsx scripts/repair-workspace-org.ts",
+    "skills:update": "agent-native skills update scaffold --project",
     "fmt:check": "prettier --check .",
     "lint": "pnpm fmt:check"
   },