@agent-native/core 0.59.1 → 0.60.0

package/dist/triggers/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/triggers/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,IAAI,CAAC;AAkBZ,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,yBAAyB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AA2HD,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAahC;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAkD9B;AAWD,wBAAgB,wBAAwB;;;;IA8DvC"}

package/dist/triggers/routes.js

@@ -0,0 +1,202 @@
+import { defineEventHandler, getMethod, setResponseStatus, } from "h3";
+import { readBody } from "../server/h3-helpers.js";
+import { getSession } from "../server/auth.js";
+import { getDbExec } from "../db/client.js";
+import { nextOccurrence, describeCron, isValidCron } from "../jobs/cron.js";
+import { getOrgContext } from "../org/context.js";
+import { resourceGetByPath, resourceListAllOwners, resourcePut, SHARED_OWNER, } from "../resources/store.js";
+import { buildTriggerContent, parseTriggerFrontmatter, refreshEventSubscriptions, } from "./dispatcher.js";
+function automationName(path) {
+    return path.replace(/^jobs\//, "").replace(/\.md$/, "");
+}
+function normalizeAutomationPath(input) {
+    const rawPath = input.path ?? (input.name ? `jobs/${input.name}.md` : "");
+    const path = rawPath.replace(/^\/+/, "");
+    if (!path.startsWith("jobs/") ||
+        !path.endsWith(".md") ||
+        path.endsWith(".keep") ||
+        path.includes("..")) {
+        throw Object.assign(new Error("A valid jobs/*.md automation path is required"), {
+            statusCode: 400,
+        });
+    }
+    return path;
+}
+function scheduleDescription(schedule) {
+    if (!schedule)
+        return undefined;
+    try {
+        return describeCron(schedule);
+    }
+    catch {
+        return schedule;
+    }
+}
+function nextRunForMeta(meta) {
+    if (meta.nextRun)
+        return meta.nextRun;
+    if (meta.enabled &&
+        meta.triggerType !== "event" &&
+        meta.schedule &&
+        isValidCron(meta.schedule)) {
+        try {
+            return nextOccurrence(meta.schedule).toISOString();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+async function currentUserCanUpdateAutomation(event, userEmail, resourceOwner, meta) {
+    if (resourceOwner === userEmail)
+        return true;
+    if (resourceOwner !== SHARED_OWNER)
+        return false;
+    if (meta.createdBy &&
+        meta.createdBy.toLowerCase() === userEmail.toLowerCase()) {
+        return true;
+    }
+    let orgId = meta.orgId;
+    if (!orgId) {
+        try {
+            orgId = (await getOrgContext(event)).orgId ?? undefined;
+        }
+        catch {
+            orgId = undefined;
+        }
+    }
+    if (!orgId)
+        return false;
+    try {
+        const { rows } = await getDbExec().execute({
+            sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+            args: [orgId, userEmail.toLowerCase()],
+        });
+        const role = String(rows[0]?.role ?? "").toLowerCase();
+        return role === "owner" || role === "admin";
+    }
+    catch {
+        return false;
+    }
+}
+async function resourceToAutomationItem(event, userEmail, resource) {
+    const { meta, body } = parseTriggerFrontmatter(resource.content);
+    return {
+        id: resource.id,
+        name: automationName(resource.path),
+        path: resource.path,
+        owner: resource.owner,
+        canUpdate: await currentUserCanUpdateAutomation(event, userEmail, resource.owner, meta),
+        triggerType: meta.triggerType,
+        event: meta.event,
+        schedule: meta.schedule || undefined,
+        scheduleDescription: scheduleDescription(meta.schedule),
+        condition: meta.condition,
+        mode: meta.mode,
+        domain: meta.domain,
+        enabled: meta.enabled,
+        lastStatus: meta.lastStatus,
+        lastRun: meta.lastRun,
+        lastError: meta.lastError,
+        nextRun: nextRunForMeta(meta),
+        createdBy: meta.createdBy,
+        body,
+    };
+}
+export async function listAutomationsForOwner(event, userEmail) {
+    const allResources = await resourceListAllOwners("jobs/");
+    const resources = allResources.filter((resource) => (resource.owner === userEmail || resource.owner === SHARED_OWNER) &&
+        resource.path.endsWith(".md") &&
+        !resource.path.endsWith(".keep"));
+    return Promise.all(resources.map((resource) => resourceToAutomationItem(event, userEmail, resource)));
+}
+export async function setAutomationEnabledForOwner(event, userEmail, input) {
+    if (typeof input.enabled !== "boolean") {
+        throw Object.assign(new Error("enabled must be a boolean"), {
+            statusCode: 400,
+        });
+    }
+    const path = normalizeAutomationPath(input);
+    const requestedOwner = input.owner === SHARED_OWNER ? SHARED_OWNER : userEmail;
+    const resource = await resourceGetByPath(requestedOwner, path);
+    if (!resource) {
+        throw Object.assign(new Error("Automation not found"), { statusCode: 404 });
+    }
+    const { meta, body } = parseTriggerFrontmatter(resource.content);
+    const allowed = await currentUserCanUpdateAutomation(event, userEmail, resource.owner, meta);
+    if (!allowed) {
+        throw Object.assign(new Error("Only the automation creator or an org admin can update it."), { statusCode: 403 });
+    }
+    meta.enabled = input.enabled;
+    if (meta.enabled &&
+        meta.triggerType !== "event" &&
+        meta.schedule &&
+        isValidCron(meta.schedule)) {
+        meta.nextRun = nextOccurrence(meta.schedule).toISOString();
+    }
+    await resourcePut(resource.owner, resource.path, buildTriggerContent(meta, body));
+    await refreshEventSubscriptions();
+    return resourceToAutomationItem(event, userEmail, {
+        ...resource,
+        content: buildTriggerContent(meta, body),
+    });
+}
+function routeError(event, err, fallback) {
+    const statusCode = typeof err?.statusCode === "number"
+        ? err.statusCode
+        : 500;
+    setResponseStatus(event, statusCode);
+    return { error: err?.message ?? fallback };
+}
+export function createAutomationsHandler() {
+    return defineEventHandler(async (event) => {
+        const method = getMethod(event);
+        const pathname = (event.path || event.url?.pathname || "")
+            .split("?")[0]
+            .replace(/^\/+/, "")
+            .replace(/\/+$/, "");
+        const session = await getSession(event).catch(() => null);
+        if (!session?.email) {
+            setResponseStatus(event, 401);
+            return { error: "Unauthenticated" };
+        }
+        if ((pathname === "fire-test" || pathname.endsWith("/fire-test")) &&
+            method === "POST") {
+            try {
+                const { emit } = await import("../event-bus/index.js");
+                const body = (await readBody(event).catch(() => ({})));
+                emit("test.event.fired", { data: body.data ?? {} }, { owner: session.email });
+                return { ok: true };
+            }
+            catch (err) {
+                return routeError(event, err, "Failed to emit test event");
+            }
+        }
+        if (method === "GET") {
+            try {
+                return await listAutomationsForOwner(event, session.email);
+            }
+            catch (err) {
+                return routeError(event, err, "Failed to list automations");
+            }
+        }
+        if (method === "PATCH" || method === "PUT") {
+            try {
+                const body = (await readBody(event).catch(() => ({})));
+                return await setAutomationEnabledForOwner(event, session.email, {
+                    owner: body?.owner,
+                    path: body?.path,
+                    name: body?.name,
+                    enabled: body?.enabled,
+                });
+            }
+            catch (err) {
+                return routeError(event, err, "Failed to update automation");
+            }
+        }
+        setResponseStatus(event, 405);
+        return { error: "Method not allowed" };
+    });
+}
+//# sourceMappingURL=routes.js.map

package/dist/triggers/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/triggers/routes.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  defineEventHandler,\n  getMethod,\n  setResponseStatus,\n  type H3Event,\n} from \"h3\";\nimport { readBody } from \"../server/h3-helpers.js\";\nimport { getSession } from \"../server/auth.js\";\nimport { getDbExec } from \"../db/client.js\";\nimport { nextOccurrence, describeCron, isValidCron } from \"../jobs/cron.js\";\nimport { getOrgContext } from \"../org/context.js\";\nimport {\n  resourceGetByPath,\n  resourceListAllOwners,\n  resourcePut,\n  SHARED_OWNER,\n  type Resource,\n} from \"../resources/store.js\";\nimport {\n  buildTriggerContent,\n  parseTriggerFrontmatter,\n  refreshEventSubscriptions,\n} from \"./dispatcher.js\";\nimport type { TriggerFrontmatter } from \"./types.js\";\n\nexport interface AutomationRouteItem {\n  id: string;\n  name: string;\n  path: string;\n  owner: string;\n  canUpdate: boolean;\n  triggerType: TriggerFrontmatter[\"triggerType\"];\n  event?: string;\n  schedule?: string;\n  scheduleDescription?: string;\n  condition?: string;\n  mode: TriggerFrontmatter[\"mode\"];\n  domain?: string;\n  enabled: boolean;\n  lastStatus?: TriggerFrontmatter[\"lastStatus\"];\n  lastRun?: string;\n  lastError?: string;\n  nextRun?: string;\n  createdBy?: string;\n  body: string;\n}\n\ninterface SetAutomationEnabledInput {\n  owner?: string;\n  path?: string;\n  name?: string;\n  enabled: boolean;\n}\n\nfunction automationName(path: string): string {\n  return path.replace(/^jobs\\//, \"\").replace(/\\.md$/, \"\");\n}\n\nfunction normalizeAutomationPath(input: SetAutomationEnabledInput): string {\n  const rawPath = input.path ?? (input.name ? `jobs/${input.name}.md` : \"\");\n  const path = rawPath.replace(/^\\/+/, \"\");\n  if (\n    !path.startsWith(\"jobs/\") ||\n    !path.endsWith(\".md\") ||\n    path.endsWith(\".keep\") ||\n    path.includes(\"..\")\n  ) {\n    throw Object.assign(\n      new Error(\"A valid jobs/*.md automation path is required\"),\n      {\n        statusCode: 400,\n      },\n    );\n  }\n  return path;\n}\n\nfunction scheduleDescription(schedule: string | undefined): string | undefined {\n  if (!schedule) return undefined;\n  try {\n    return describeCron(schedule);\n  } catch {\n    return schedule;\n  }\n}\n\nfunction nextRunForMeta(meta: TriggerFrontmatter): string | undefined {\n  if (meta.nextRun) return meta.nextRun;\n  if (\n    meta.enabled &&\n    meta.triggerType !== \"event\" &&\n    meta.schedule &&\n    isValidCron(meta.schedule)\n  ) {\n    try {\n      return nextOccurrence(meta.schedule).toISOString();\n    } catch {\n      return undefined;\n    }\n  }\n  return undefined;\n}\n\nasync function currentUserCanUpdateAutomation(\n  event: H3Event,\n  userEmail: string,\n  resourceOwner: string,\n  meta: TriggerFrontmatter,\n): Promise<boolean> {\n  if (resourceOwner === userEmail) return true;\n  if (resourceOwner !== SHARED_OWNER) return false;\n\n  if (\n    meta.createdBy &&\n    meta.createdBy.toLowerCase() === userEmail.toLowerCase()\n  ) {\n    return true;\n  }\n\n  let orgId = meta.orgId;\n  if (!orgId) {\n    try {\n      orgId = (await getOrgContext(event)).orgId ?? undefined;\n    } catch {\n      orgId = undefined;\n    }\n  }\n  if (!orgId) return false;\n\n  try {\n    const { rows } = await getDbExec().execute({\n      sql: `SELECT role FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,\n      args: [orgId, userEmail.toLowerCase()],\n    });\n    const role = String((rows[0] as any)?.role ?? \"\").toLowerCase();\n    return role === \"owner\" || role === \"admin\";\n  } catch {\n    return false;\n  }\n}\n\nasync function resourceToAutomationItem(\n  event: H3Event,\n  userEmail: string,\n  resource: Resource,\n): Promise<AutomationRouteItem> {\n  const { meta, body } = parseTriggerFrontmatter(resource.content);\n  return {\n    id: resource.id,\n    name: automationName(resource.path),\n    path: resource.path,\n    owner: resource.owner,\n    canUpdate: await currentUserCanUpdateAutomation(\n      event,\n      userEmail,\n      resource.owner,\n      meta,\n    ),\n    triggerType: meta.triggerType,\n    event: meta.event,\n    schedule: meta.schedule || undefined,\n    scheduleDescription: scheduleDescription(meta.schedule),\n    condition: meta.condition,\n    mode: meta.mode,\n    domain: meta.domain,\n    enabled: meta.enabled,\n    lastStatus: meta.lastStatus,\n    lastRun: meta.lastRun,\n    lastError: meta.lastError,\n    nextRun: nextRunForMeta(meta),\n    createdBy: meta.createdBy,\n    body,\n  };\n}\n\nexport async function listAutomationsForOwner(\n  event: H3Event,\n  userEmail: string,\n): Promise<AutomationRouteItem[]> {\n  const allResources = await resourceListAllOwners(\"jobs/\");\n  const resources = allResources.filter(\n    (resource) =>\n      (resource.owner === userEmail || resource.owner === SHARED_OWNER) &&\n      resource.path.endsWith(\".md\") &&\n      !resource.path.endsWith(\".keep\"),\n  );\n  return Promise.all(\n    resources.map((resource) =>\n      resourceToAutomationItem(event, userEmail, resource),\n    ),\n  );\n}\n\nexport async function setAutomationEnabledForOwner(\n  event: H3Event,\n  userEmail: string,\n  input: SetAutomationEnabledInput,\n): Promise<AutomationRouteItem> {\n  if (typeof input.enabled !== \"boolean\") {\n    throw Object.assign(new Error(\"enabled must be a boolean\"), {\n      statusCode: 400,\n    });\n  }\n\n  const path = normalizeAutomationPath(input);\n  const requestedOwner =\n    input.owner === SHARED_OWNER ? SHARED_OWNER : userEmail;\n  const resource = await resourceGetByPath(requestedOwner, path);\n  if (!resource) {\n    throw Object.assign(new Error(\"Automation not found\"), { statusCode: 404 });\n  }\n\n  const { meta, body } = parseTriggerFrontmatter(resource.content);\n  const allowed = await currentUserCanUpdateAutomation(\n    event,\n    userEmail,\n    resource.owner,\n    meta,\n  );\n  if (!allowed) {\n    throw Object.assign(\n      new Error(\"Only the automation creator or an org admin can update it.\"),\n      { statusCode: 403 },\n    );\n  }\n\n  meta.enabled = input.enabled;\n  if (\n    meta.enabled &&\n    meta.triggerType !== \"event\" &&\n    meta.schedule &&\n    isValidCron(meta.schedule)\n  ) {\n    meta.nextRun = nextOccurrence(meta.schedule).toISOString();\n  }\n\n  await resourcePut(\n    resource.owner,\n    resource.path,\n    buildTriggerContent(meta, body),\n  );\n  await refreshEventSubscriptions();\n\n  return resourceToAutomationItem(event, userEmail, {\n    ...resource,\n    content: buildTriggerContent(meta, body),\n  });\n}\n\nfunction routeError(event: H3Event, err: unknown, fallback: string) {\n  const statusCode =\n    typeof (err as any)?.statusCode === \"number\"\n      ? (err as any).statusCode\n      : 500;\n  setResponseStatus(event, statusCode);\n  return { error: (err as any)?.message ?? fallback };\n}\n\nexport function createAutomationsHandler() {\n  return defineEventHandler(async (event: H3Event) => {\n    const method = getMethod(event);\n    const pathname = (event.path || event.url?.pathname || \"\")\n      .split(\"?\")[0]\n      .replace(/^\\/+/, \"\")\n      .replace(/\\/+$/, \"\");\n\n    const session = await getSession(event).catch(() => null);\n    if (!session?.email) {\n      setResponseStatus(event, 401);\n      return { error: \"Unauthenticated\" };\n    }\n\n    if (\n      (pathname === \"fire-test\" || pathname.endsWith(\"/fire-test\")) &&\n      method === \"POST\"\n    ) {\n      try {\n        const { emit } = await import(\"../event-bus/index.js\");\n        const body = (await readBody(event).catch(() => ({}))) as Record<\n          string,\n          unknown\n        >;\n        emit(\n          \"test.event.fired\",\n          { data: body.data ?? {} },\n          { owner: session.email },\n        );\n        return { ok: true };\n      } catch (err) {\n        return routeError(event, err, \"Failed to emit test event\");\n      }\n    }\n\n    if (method === \"GET\") {\n      try {\n        return await listAutomationsForOwner(event, session.email);\n      } catch (err) {\n        return routeError(event, err, \"Failed to list automations\");\n      }\n    }\n\n    if (method === \"PATCH\" || method === \"PUT\") {\n      try {\n        const body = (await readBody(event).catch(\n          () => ({}),\n        )) as SetAutomationEnabledInput | null;\n        return await setAutomationEnabledForOwner(event, session.email, {\n          owner: body?.owner,\n          path: body?.path,\n          name: body?.name,\n          enabled: (body as any)?.enabled,\n        } as SetAutomationEnabledInput);\n      } catch (err) {\n        return routeError(event, err, \"Failed to update automation\");\n      }\n    }\n\n    setResponseStatus(event, 405);\n    return { error: \"Method not allowed\" };\n  });\n}\n"]}

package/docs/AGENTS.md

@@ -0,0 +1,57 @@
+# Agent Native Docs For Agents
+
+These docs are bundled with `@agent-native/core` and installed at:
+
+```txt
+node_modules/@agent-native/core/docs
+```
+
+Use these version-matched markdown docs before coding against Agent Native
+framework APIs or advanced features. Public docs are useful for browsing, but
+the package docs match the exact framework version installed in the app.
+
+## Fast Lookup
+
+From a generated app root:
+
+```bash
+pnpm action docs-search --list
+pnpm action docs-search --query "actions"
+pnpm action docs-search --slug actions
+```
+
+The built-in app agent also has a read-only `docs-search` tool with the same
+`list`, `query`, and `slug` options.
+
+If the action runner is unavailable, search the markdown files directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read the matching files under `node_modules/@agent-native/core/docs/content/`.
+
+## What To Read First
+
+| Task                                  | Start with                                                                                               |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Define or call app operations         | `content/actions.md`, `content/client.md`                                                                |
+| Add SQL data, schema, or access rules | `content/database.md`, `content/security.md`, `content/sharing.md`                                       |
+| Keep the UI and agent in sync         | `content/context-awareness.md`, `content/client.md`                                                      |
+| Build headless or chat-first apps     | `content/pure-agent-apps.md`, `content/agent-surfaces.md`, `content/using-your-agent.md`                 |
+| Add automations or scheduled work     | `content/automations.md`, `content/recurring-jobs.md`                                                    |
+| Compose apps or call sibling agents   | `content/a2a-protocol.md`, `content/multi-app-workspace.md`, `content/workspace.md`                      |
+| Expose tools to external agents       | `content/external-agents.md`, `content/mcp-protocol.md`, `content/mcp-apps.md`, `content/mcp-clients.md` |
+| Add integrations, setup, or secrets   | `content/onboarding.md`, `content/workspace-connections.md`, `content/security.md`                       |
+| Build extensions or custom widgets    | `content/extensions.md`, `content/agent-web-surfaces.md`                                                 |
+| Deploy or configure hosting           | `content/deployment.md`, `content/server.md`                                                             |
+| Write agent instructions or skills    | `content/skills-guide.md`, `content/writing-agent-instructions.md`                                       |
+
+## Rules
+
+- Prefer the app's own `AGENTS.md` and `.agents/skills/` for app-specific
+  behavior. Use this package docs tree for framework APIs and patterns.
+- If local instructions and package docs conflict, local app instructions win
+  for that app, but verify the framework API shape in package docs or types.
+- Do not invent Agent Native APIs. Search these docs and installed type
+  definitions before adding imports, routes, actions, or framework config.

package/docs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: agent-native-docs
+description: "How to look up version-matched Agent Native framework docs in node_modules. Use before coding against @agent-native/core APIs or advanced features."
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing non-trivial Agent Native functionality, read the
+version-matched docs installed with `@agent-native/core`.
+
+## How
+
+1. Start from the generated app root.
+2. Search with `pnpm action docs-search --query "<feature>"`.
+3. Read a specific page with `pnpm action docs-search --slug <slug>`.
+4. If the action runner is unavailable, search
+   `node_modules/@agent-native/core/docs` directly with `rg`.
+5. For app-specific rules, also read the app's own `AGENTS.md` and any relevant
+   `.agents/skills/<name>/SKILL.md`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when local package docs are present.
+- Do not add custom REST wrappers for normal app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/docs/content/a2a-protocol.md

@@ -305,7 +305,7 @@ A mail agent needs analytics data. The analytics agent exposes a "run-query" ski
 
 ```ts
 // In the mail agent's actions/get-analytics.ts
-import { defineAction } from "@agent-native/core/server";
+import { defineAction } from "@agent-native/core/action";
 import { callAgent } from "@agent-native/core/a2a";
 import { z } from "zod";
 

package/docs/content/actions.md

@@ -19,11 +19,51 @@ One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-ag
 If you are deciding whether to expose an operation headlessly, in chat, in an
 embedded sidecar, or as a full app screen, see [Agent Surfaces](/docs/agent-surfaces).
 
+## Start with one action {#hello-action}
+
+The primitive-first on-ramp is one action, not a template. In a headless
+scaffold such as `agent-native create my-agent --headless`, this can be the
+whole first app:
+
+```ts
+// actions/hello.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Say hello from the local agent.",
+  schema: z.object({
+    name: z.string().default("world"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});
+```
+
+Run it from the same folder:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Then run the app-agent loop against the folder:
+
+```bash
+pnpm agent "Call hello for Steve and explain the result"
+```
+
+That is the same app-agent loop your scheduled jobs, chat UI, external MCP
+tools, and future screens will use. Chat and domain templates are for adding UI
+around actions, not a required prerequisite for the action itself.
+
 ## Defining an action {#defining}
 
 ```ts
 // actions/reply-to-email.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({
@@ -229,7 +269,7 @@ User-owned tables must scope reads through `accessFilter` and writes through `as
 
 ```ts
 // actions/create-lead.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 import { getDb } from "../server/db/index.js";
 import * as schema from "../server/db/schema.js";
@@ -315,12 +355,12 @@ summaries, and insight cards; use [MCP Apps](/docs/mcp-apps) for inline UI in
 external MCP hosts.
 
 ```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
 import {
-  ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+  createDataInsightsWidgetResult,
   dataInsightsWidgetResultSchema,
-  defineAction,
-} from "@agent-native/core";
-import { createDataInsightsWidgetResult } from "@agent-native/core/data-widgets";
+} from "@agent-native/core/data-widgets";
 
 export default defineAction({
   description: "Summarize response trends.",
@@ -411,7 +451,7 @@ Reads the current navigation state, fetches contextual data, and returns a snaps
 
 ```ts
 // actions/view-screen.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 
@@ -438,7 +478,7 @@ Writes a one-shot navigation command to application state. The UI reads it, navi
 
 ```ts
 // actions/navigate.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 

package/docs/content/agent-surfaces.md

@@ -13,13 +13,13 @@ application.
 The useful way to choose is not by protocol first. Choose the product surface
 you want, then use the matching primitive.
 
-| Surface                       | Use it when                                                                                                 | Start with                                                         |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `defineAction`, HTTP, CLI, MCP, A2A                                |
-| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | `<AgentChatSurface>`, `<AssistantChat>`, `createAgentChatPlugin()` |
-| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`            |
-| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`         |
-| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                   |
+| Surface                       | Use it when                                                                                                 | Start with                                                                                  |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| **Headless agent/actions**    | Code, jobs, scripts, another app, or another agent should call the work directly.                           | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A |
+| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop.                                   | [Chat template](/docs/template-chat), `<AgentChatSurface>`, `<AssistantChat>`               |
+| **Rich chat on your agent**   | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `<AssistantChat runtime={runtime}>`                                     |
+| **Embedded sidecar**          | You already have a SaaS app and want an agent beside it with page context and host commands.                | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded`                                  |
+| **Full application**          | Humans and agents should share durable screens, data, navigation, and collaboration.                        | Templates, actions, SQL state, context awareness                                            |
 
 Those are stages, not separate products. A workflow can start as a headless
 action, appear in chat as a table or chart, and later become a full screen in an
@@ -31,11 +31,19 @@ Use the headless path when no one needs to stare at a custom app screen while
 the work runs: scheduled jobs, integrations, backend workflows, CLI loops,
 another agent, or an existing product calling into Agent-Native.
 
-Most headless integrations should start with actions:
+The smallest local path is a headless scaffold plus one action:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
+pnpm install
+```
+
+Then define the durable operation:
 
 ```ts
 // actions/summarize-week.ts
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({
@@ -52,14 +60,26 @@ One action is then callable as:
 
 - **HTTP** — `POST /_agent-native/actions/summarize-week`
 - **CLI** — `pnpm action summarize-week --formId form_123`
+- **App-agent CLI** — `pnpm agent "Summarize form_123"`
 - **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts
 - **A2A** — from another agent-native app or agent peer
 - **UI** — through `useActionQuery`, `useActionMutation`, or `callAction`
 - **Agent tool** — from the built-in chat loop
 
-If you need the whole agent loop headlessly, use the server API from a worker,
-job, integration webhook, or custom host. This is lower-level than actions: you
-provide the engine, model, messages, actions, and event sink yourself.
+This is not a no-database or stateless mode. The app-agent loop stores sessions,
+threads, runs, settings, credentials, application state, and share records in
+SQL. Local development defaults to SQLite; hosted headless apps should use a
+persistent SQL database.
+
+If you need the whole agent loop headlessly from the project folder, use:
+
+```bash
+pnpm agent "Summarize this week's forms."
+```
+
+Workers, jobs, integration webhooks, and custom hosts can use the server API
+directly. This is lower-level than actions: you provide the engine, model,
+messages, actions, and event sink yourself.
 
 ```ts
 import {
@@ -97,11 +117,49 @@ For most apps, scheduled prompts and integration webhooks already call this loop
 for you. Reach for direct `runAgentLoop()` when you are building a custom
 headless host, eval runner, or server-side orchestration surface.
 
+### Running against a folder {#folder-loop}
+
+If your goal is "run an agent against this folder," start with the app-agent
+loop in that folder: scaffold the headless app, add actions/instructions, run
+`pnpm agent "..."`. That keeps the work inside the same action/runtime/state
+contract the app will use in production.
+
+External coding harnesses are a separate product surface for embedding Claude
+Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app.
+Use them when you are building a coding-agent product, not as the default way to
+start a local agent-native workflow.
+
+### Cloud repo access {#cloud-repo-access}
+
+For cloud headless apps that need repository access, the planned model is a
+GitHub connector plus token CRUD: list repositories, search files, read files,
+create or edit files, delete files, and revoke access through provider-scoped
+credentials.
+
+Do not treat a VM clone or long-lived sandbox checkout as the primary cloud
+repo-access model. Sandboxes still matter for isolated code execution, but
+repository access should be explicit, permissioned, auditable, and revocable
+through the connector layer.
+
+### Sharing sessions and runs {#sharing-runs}
+
+Headless sessions and runs are durable objects. Shareability should be phased:
+read/share links first, so teammates can inspect sanitized prompts, outputs,
+and run status; permissioned writable collaboration later, so continuing a run,
+approving actions, editing schedules, or changing configuration goes through
+explicit access checks.
+
 ## Rich chat on Agent-Native {#rich-chat}
 
 Use the built-in chat when the user should talk to the agent, see tool calls,
 approve work, inspect native results, and keep a durable thread history.
 
+For a full app starting point, use the [Chat template](/docs/template-chat):
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+```
+
 The simplest full-page chat:
 
 ```tsx
@@ -131,6 +189,9 @@ components in the chat, without iframes. See [Native Chat UI](/docs/native-chat-
 Use this path when your agent is already built with another framework or
 runtime and you want Agent-Native's chat UI around it.
 
+The [Chat template](/docs/template-chat) is still useful here: keep its app
+shell and thread UI, then swap the runtime behind the chat plugin or route.
+
 `AgentChatRuntime` is the boundary. Your runtime streams normalized events;
 Agent-Native renders the composer, transcript, tool calls, approvals, native
 widgets, and app layout.
@@ -245,8 +306,9 @@ Full apps add product UI around the same action and agent contract:
 - **Deep links** — action results can open the right app view.
 - **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline.
 
-Start from a [template](/docs/cloneable-saas) when you want a complete app, or
-from [Starter](/docs/template-starter) when you want only the framework wiring.
+Start from the [Chat template](/docs/template-chat) when you want a minimal app
+around your actions, or from a domain [template](/docs/cloneable-saas) when you
+want a complete product shape.
 
 ## How to choose {#how-to-choose}
 

package/docs/content/cli-adapters.md

@@ -228,7 +228,7 @@ Actions can use CLI adapters directly for structured access:
 
 ```ts
 // actions/list-prs.ts
-import { defineAction } from "@agent-native/core/server";
+import { defineAction } from "@agent-native/core/action";
 import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
 import { z } from "zod";
 

package/docs/content/cloneable-saas.md

@@ -15,6 +15,7 @@ Each one is a real app you could use today, and the launching pad for your own v
 
 | Template                                  | What it is                                                                                                     |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| [**Chat**](/docs/template-chat)           | Minimal chat-first app with durable threads, actions, auth, and a clean path to custom UI or your own backend. |
 | [**Mail**](/docs/template-mail)           | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent.      |
 | [**Calendar**](/docs/template-calendar)   | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                  |
 | [**Content**](/docs/template-content)     | Open-source Obsidian for MDX. Local Markdown/MDX, Tiptap editor, Notion sync, real-time multi-user collab.     |
@@ -29,7 +30,7 @@ Each one is a real app you could use today, and the launching pad for your own v
 | [**Plan**](/docs/template-plan)           | Visual plans and PR recaps with diagrams, wireframes, and annotations.                                         |
 | [**Dispatch**](/docs/template-dispatch)   | The workspace control plane: shared secrets, reusable integrations, Slack/Telegram, scheduled jobs.            |
 
-Don't want a domain template? See [Pure-Agent Apps / Starter](/docs/pure-agent-apps) for the minimal scaffold.
+Don't want a domain template? Use [Chat](/docs/template-chat) when you want a basic app users can talk to immediately, or start action-first with [Pure-Agent Apps](/docs/pure-agent-apps).
 
 See the full catalog under [Templates](/templates), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
 
@@ -72,11 +73,11 @@ You don't have to. Every template is also available as a hosted app on `agent-na
 
 ## Try it with a skill {#try-with-a-skill}
 
-Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See [Try it with a skill](/docs/getting-started#try-with-a-skill) in Getting Started.
+Not ready to scaffold? You can add agent-native superpowers to a coding agent you already use with a single command — no app needed. See the [Skills Guide](/docs/skills-guide#app-backed-skills).
 
 ## Building on this
 
-- [**Getting Started**](/docs/getting-started) — clone your first template and run it locally
+- [**Getting Started**](/docs/getting-started) — create a minimal chat app or headless action
 - [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each template
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several templates into one workspace that shares auth, brand, and agent
 - [**Dispatch**](/docs/template-dispatch) — the workspace control plane template
@@ -90,7 +91,7 @@ If you're scaffolding now, the CLI command is:
 npx @agent-native/core@latest create my-platform
 ```
 
-You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need.
+You'll get a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need. For an action-only app instead of a template UI, use `npx @agent-native/core@latest create my-agent --headless`.
 
 Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.