@agent-native/core 0.66.0 → 0.66.2

package/docs/content/getting-started.md

@@ -1,12 +1,13 @@
 ---
 title: "Getting Started"
-description: "Create an agent app — with a chat UI or headless — add an action, and watch the agent call it."
+description: "Create an agent app, understand instructions, skills, and actions, then watch the agent call its first action."
 ---
 
 # Getting Started
 
 Agent-Native apps give an AI agent and your UI the same actions, data, and
-state. The smallest useful app is a single action.
+state. A basic agent is made from instructions that guide it, skills that teach
+repeatable behavior, and actions that let it do real work.
 
 **Want a complete app to start from?** Clone one of our rich templates —
 [Chat](/docs/template-chat), [Mail](/docs/template-mail),
@@ -15,15 +16,23 @@ state. The smallest useful app is a single action.
 each a full-featured app you customize.
 
 Building from scratch? The only choice up front is whether you want a UI —
-everything after (defining actions, running the agent) is the same either way.
+everything after (writing instructions, adding skills, defining actions, running
+the agent) is the same either way.
 
-```an-diagram title="The three-step on-ramp" summary="Create an app, add one action, run it. The action is then reachable from every surface."
+```an-file-tree title="A basic Agent-Native agent"
 {
-  "html": "<div class=\"diagram-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">1</span><strong>Create</strong><small class=\"diagram-muted\">chat template or headless</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2</span><strong>Add an action</strong><small class=\"diagram-muted\">one defineAction file</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">3</span><strong>Run it</strong><small class=\"diagram-muted\">CLI, agent, or browser</small></div></div>",
-  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:140px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
 }
 ```
 
+This is true whether you start with a chat UI, a headless agent, or a full app.
+The UI changes the surface; instructions, skills, and actions give the agent its
+guidance and behavior.
+
 ## 1. Create your app
 
 You'll need [Node.js 22+](https://nodejs.org) and [pnpm](https://pnpm.io).
@@ -51,10 +60,10 @@ loop, no UI shell:
 npx @agent-native/core@latest create my-agent --headless
 ```
 
-Then install:
+Then install from the folder you created:
 
 ```bash
-cd my-app
+cd my-agent # or my-app if you chose the Chat template
 pnpm install
 ```
 
@@ -80,8 +89,13 @@ ship with this example:
 }
 ```
 
-Replace `hello` with the smallest real operation in your domain. You define it
-once; every surface picks it up.
+Replace `hello` with the first real operation in your domain. You define it once;
+every surface picks it up.
+
+Use `AGENTS.md` for guidance that should apply every turn. Use a skill when the
+agent needs a reusable workflow or domain procedure. Use an action when the
+agent needs a typed, testable way to read data, write data, call an API, or
+perform an approval.
 
 ## 3. Run it
 
@@ -182,7 +196,8 @@ my-app/
   actions/         # Agent-callable actions
   app/             # React frontend (UI templates only; omitted when headless)
   server/          # Nitro API server (routes, plugins)
-  .agents/         # Agent instructions and skills
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
   data/app.db      # Local SQLite state when DATABASE_URL is unset
 ```
 

package/docs/content/key-concepts.md

@@ -26,6 +26,33 @@ Every agent-native app is three things working together:
 
 Headless apps can run the same production app-agent loop from the folder with `pnpm agent`, while UI apps mount the embedded agent panel and run locally with `pnpm dev`. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams.
 
+## Agent building blocks {#agent-building-blocks}
+
+Every agent-native app has the same agent building blocks, regardless of whether
+the product surface is headless, chat-first, or a full UI:
+
+```an-file-tree title="Guidance and behavior"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, core rules, state keys, action index, skills index" },
+    { "path": ".agents/skills/<name>/SKILL.md", "note": "reusable behavior: workflow steps, policies, examples, references, and do/don't lists" },
+    { "path": "actions/<name>.ts", "note": "executable capability: typed operation exposed to the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks" }
+  ]
+}
+```
+
+| Building block   | Use it for                                                                                          | Loaded when                                           |
+| ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Instructions** | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes  | Every turn                                            |
+| **Skills**       | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output  | On demand when the skill description matches the task |
+| **Actions**      | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called |
+
+Skills and actions work together. A skill teaches the agent how to do a class of
+work; an action is the code path it can call while doing that work. For example,
+a `customer-research` skill might tell the agent which sources to inspect and
+how to summarize evidence, while `search-crm` and `create-brief` actions fetch
+and write the actual data.
+
 Six rules govern the architecture:
 
 1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM

package/docs/content/writing-agent-instructions.md

@@ -114,6 +114,26 @@ defineAction({
 });
 ```
 
+## Skills vs actions {#skills-vs-actions}
+
+Skills and actions are complementary. A skill is guidance the agent reads; an
+action is code the agent can run.
+
+| Need                                                                   | Use                                |
+| ---------------------------------------------------------------------- | ---------------------------------- |
+| The agent needs to follow a workflow, policy, checklist, or rubric     | **Skill**                          |
+| The agent needs examples, reference material, or domain-specific rules | **Skill**                          |
+| The agent needs to read or write app data                              | **Action**                         |
+| The agent needs to call an external API or perform an approval         | **Action**                         |
+| The agent calls the right operation but in the wrong way               | Improve the **skill**              |
+| The agent cannot reliably invoke the operation                         | Improve the **action**             |
+| The agent chooses the wrong tool                                       | Improve the **action description** |
+
+Most real features use both: the skill explains how to approach the task, and
+the action provides the typed operation. For example, an `invoice-review` skill
+can explain the review policy and escalation rules, while `list-invoices`,
+`flag-invoice`, and `approve-invoice` actions do the actual reads and writes.
+
 ## Bake in anti-fabrication and verify-before-done {#anti-fabrication}
 
 App instructions should make honesty and verification the default behavior:

package/package.json

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

package/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -61,9 +61,20 @@ Organizations are **framework-managed**, not handled by Better Auth's organizati
 
 The active org flows automatically: `session.orgId` — resolved by `getOrgContext` from `org_members` plus the user's `active-org-id` setting (_not_ from a Better Auth session field) — → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
 
-**If your template requires an org to function** (data is scoped by `organization_id`, core features can't run without one), set `AUTO_CREATE_DEFAULT_ORG=1` in your `.env`. The framework will auto-create a default org (named after the user) on first login when no memberships exist. This happens inside `getOrgContext` — no template integration needed.
-
-As a safety net, also wrap your app shell in `<RequireActiveOrg>` from `@agent-native/core/client/org`. It blocks the wrapped area with a "Create your organization" pane (and accept-invite CTAs for pending invitations) if auto-create failed or the account predates it. Place it **inside** the agent sidebar so the setup checklist, chat, and CLI stay usable during setup.
+If your template requires an org to function because data is scoped by
+`organization_id`, set `AUTO_CREATE_DEFAULT_ORG=1` in that template's runtime
+environment. The framework will auto-create a default org (named after the
+user) on first login when no memberships exist. The auto-create path skips users
+with pending invites or a matching `allowed_domain` org so they can join the
+intended team instead. Leave the flag unset for deployments that intentionally
+support solo `orgId === null` data.
+
+As a safety net, wrap org-scoped app shells or org-scoped routes in
+`<RequireActiveOrg>` from `@agent-native/core/client/org`. It blocks the wrapped
+area with a "Create your organization" pane plus accept-invite/domain-join CTAs
+when no active org exists, preventing org-scoped queries or mutations from
+failing later in the workflow. Place it inside the agent sidebar so the setup
+checklist, chat, and CLI stay usable during setup.
 
 ## A2A Identity