@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: actions
+description: >-
+  How to create and run agent actions. Actions are the single source of truth
+  for app operations — the agent calls them as tools, the frontend calls them
+  as HTTP endpoints. Use when creating a new action, adding an API integration,
+  or wiring up frontend data fetching.
+---
+
+# Agent Actions
+
+## Rule
+
+Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the framework auto-exposes them as HTTP endpoints at `/_agent-native/actions/:name`. The frontend calls those endpoints using React Query hooks. No duplicate `/api/` routes needed.
+
+## Why
+
+Actions give the agent callable tools with structured input/output, AND they give the frontend type-safe HTTP endpoints automatically. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
+
+## How to Create an Action
+
+Use `defineAction` with a Zod schema (required for new actions):
+
+```ts
+// actions/list-meals.ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+import { getDb } from "../server/db/index.js";
+import { meals } from "../server/db/schema.js";
+
+export default defineAction({
+  description: "List all meals",
+  schema: z.object({
+    date: z.string().describe("Filter by date (YYYY-MM-DD)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    // args is fully typed: { date: string }
+    const db = getDb();
+    const rows = await db.select().from(meals);
+    return rows; // Return objects/arrays, NOT JSON.stringify()
+  },
+});
+```
+
+The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages (400 for HTTP, error result for agent), full TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
+
+Tips:
+- Use `.describe()` for parameter descriptions
+- Use `.optional()` for optional params
+- Use `z.coerce.number()` / `z.coerce.boolean()` for params that arrive as strings from HTTP
+- Use `z.enum(["draft", "published"])` for constrained values
+
+The legacy `parameters` field (plain JSON Schema object) still works as a fallback but does not provide runtime validation or type inference.
+
+### The `http` Option
+
+Controls how the action is exposed as an HTTP endpoint:
+
+| Value                     | Behavior                                                    | Use for                          |
+| ------------------------- | ----------------------------------------------------------- | -------------------------------- |
+| _(omitted)_               | Auto-exposed as `POST /_agent-native/actions/:name`         | Write operations (default)       |
+| `{ method: "GET" }`       | Auto-exposed as `GET /_agent-native/actions/:name`          | Read-only queries                |
+| `{ method: "PUT" }`       | Auto-exposed as `PUT /_agent-native/actions/:name`          | Update operations                |
+| `{ method: "DELETE" }`    | Auto-exposed as `DELETE /_agent-native/actions/:name`       | Delete operations                |
+| `{ method: "GET", path: "custom" }` | Auto-exposed as `GET /_agent-native/actions/custom` | Custom route path                |
+| `false`                   | Agent-only, never exposed as HTTP                           | `navigate`, `view-screen`, internal actions |
+
+### Screen Refresh (automatic)
+
+The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the server emits a poll event that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload.
+
+Rules:
+
+- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
+- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
+- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
+- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
+
+Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
+
+### Return Values
+
+Actions should return **structured data** (objects, arrays) — not `JSON.stringify()`. The framework serializes the response automatically. If you return a string, the framework tries to parse it as JSON for a clean response.
+
+```ts
+// Good — return structured data
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return events;
+}
+
+// Bad — don't stringify
+run: async (args) => {
+  const events = await fetchEvents(args.from, args.to);
+  return JSON.stringify(events, null, 2);
+}
+```
+
+## Frontend Hooks
+
+The frontend calls action endpoints using React Query hooks from `@agent-native/core/client`:
+
+### `useActionQuery` — for GET actions
+
+```ts
+import { useActionQuery } from "@agent-native/core/client";
+
+function MealList() {
+  // Types are auto-inferred from the action's schema + return type — no manual generic needed
+  const { data: meals } = useActionQuery("list-meals", {
+    date: "2025-01-01",
+  });
+  return <ul>{meals?.map((m) => <li key={m.id}>{m.name}</li>)}</ul>;
+}
+```
+
+### `useActionMutation` — for POST/PUT/DELETE actions
+
+```ts
+import { useActionMutation } from "@agent-native/core/client";
+
+function AddMealButton() {
+  // Types are auto-inferred — no manual generic needed
+  const { mutate } = useActionMutation("log-meal");
+  return (
+    <button onClick={() => mutate({ name: "Salad", calories: 350 })}>
+      Log Meal
+    </button>
+  );
+}
+```
+
+**Do NOT use manual type generics** like `useActionQuery<Meal[]>(...)`. Types are inferred automatically from `.generated/action-types.d.ts`, which is auto-generated by a Vite plugin.
+
+Mutations automatically invalidate all `["action"]` query keys on success, so GET queries refetch.
+
+## How to Run (Agent)
+
+```bash
+pnpm action my-action --input data/source.json --output data/result.json
+```
+
+## Action Dispatcher
+
+The default template uses core's `runScript()` in `actions/run.ts`:
+
+```ts
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
+
+## When You Still Need Custom `/api/` Routes
+
+Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+
+- **File uploads** — actions receive JSON params, not multipart form data
+- **Streaming responses** — SSE or chunked responses that need direct H3 control
+- **Webhooks** — external services POST to a specific URL
+- **OAuth callbacks** — redirect-based flows that need specific URL patterns
+
+If it's a standard CRUD operation or data query, use an action instead.
+
+## Legacy Pattern (bare export)
+
+Older actions use a bare async function export with `parseArgs`:
+
+```ts
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  // ...
+}
+```
+
+This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
+
+## Guidelines
+
+- **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
+- **Return structured data.** Return objects/arrays, not `JSON.stringify()`.
+- **Use `http: { method: "GET" }`** for read-only actions. Default is POST.
+- **Use `http: false`** for agent-only actions (`navigate`, `view-screen`).
+- **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
+- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
+- **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
+
+## Common Patterns
+
+**Read action (GET):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "List calendar events",
+  schema: z.object({
+    from: z.string().describe("Start date"),
+    to: z.string().describe("End date"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return await fetchEvents(args.from, args.to);
+  },
+});
+```
+
+**Write action (POST, default):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Log a meal",
+  schema: z.object({
+    name: z.string().describe("Meal name"),
+    calories: z.coerce.number().describe("Calorie count"),
+  }),
+  run: async (args) => {
+    // args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
+    const meal = await insertMeal(args);
+    return meal;
+  },
+});
+```
+
+**Agent-only action:**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Navigate the UI to a view",
+  schema: z.object({
+    view: z.string().describe("Target view"),
+  }),
+  http: false,
+  run: async (args) => {
+    await writeAppState("navigate", { command: "go", view: args.view });
+    return "Navigated";
+  },
+});
+```
+
+## Troubleshooting
+
+- **Action not found** — Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
+- **Args not parsing** — Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
+- **Frontend getting 405** — The action's `http.method` doesn't match the hook. Use `useActionQuery` for GET actions, `useActionMutation` for POST/PUT/DELETE.
+- **Frontend getting undefined** — Make sure the action returns structured data, not `JSON.stringify()`.
+
+## Related Skills
+
+- **storing-data** — Actions read/write data in SQL
+- **delegate-to-agent** — The agent invokes actions via `pnpm action <name>`
+- **real-time-sync** — Database writes from actions trigger poll events to update the UI
+- **adding-a-feature** — Actions are area 2 of the four-area checklist

package/dist/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature must complete. Use when adding any
+  feature, integration, or capability to ensure the agent and UI stay in parity.
+---
+
+# Adding a Feature — The Four-Area Checklist
+
+## Rule
+
+Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
+
+## Why
+
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
+
+## The Checklist
+
+When you add a new feature, work through these four areas in order:
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations — you rarely need custom `/api/` routes.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
+
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client";
+  import { useQuery } from "@tanstack/react-query";
+
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // no flicker on refetch
+  });
+  ```
+
+  See the `real-time-sync` skill for the full pattern and source catalog.
+
+### 2. Action
+
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
+
+### 4. Application State Sync
+
+Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
+
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
+## Anti-Patterns
+
+- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
+- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
+- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle. Actions are auto-exposed as HTTP endpoints — use `useActionQuery`/`useActionMutation` instead.
+- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
+- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
+
+## Verification
+
+After completing all four areas, verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the same operation via actions?
+3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
+4. Can the agent navigate to the feature view via the `navigate` action?
+5. Is the feature documented in AGENTS.md with action names and args?
+
+## One more area — sharing
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## Related Skills
+
+- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
+- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
+- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **create-skill** — How to create skills for new patterns (area 3 in detail)
+- **storing-data** — Where to store the feature's data
+- **real-time-sync** — How the UI stays in sync when the agent writes data

package/dist/templates/workspace-core/.agents/skills/address-feedback/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: address-feedback
+description: >-
+  Triage feedback docs or pasted feedback into bugs to fix, UX suggestions to
+  propose, unclear questions, and skipped noise; verify bugs, check Sentry when
+  relevant, and keep UI changes minimal.
+---
+
+# Address Feedback
+
+Use this skill when the user shares a feedback document, issue, thread, or pasted notes and asks you to address the feedback.
+
+The default posture is judgment plus action: fix clear, verified bugs you agree with; propose UX changes with rationale; skip or flag low-signal, unclear, or out-of-scope items.
+
+## Prerequisites
+
+- If no link or feedback text is provided, ask for it.
+- Read the repo `AGENTS.md` before touching code.
+- Use the relevant connector/plugin/skill for the source when available, instead of scraping authenticated pages.
+
+## Steps
+
+1. Read the feedback source.
+
+   | Source | Reader |
+   | --- | --- |
+   | Notion link | Notion connector or Notion skill |
+   | Google Docs/Drive link | Google Drive connector or Google Docs skill |
+   | Linear link | Linear connector if installed; otherwise ask for pasted content |
+   | GitHub issue or PR | GitHub connector or `gh issue view` / `gh pr view` |
+   | Slack thread | Slack connector |
+   | Public URL | Web browsing |
+   | Pasted text | Read directly |
+
+   Use web browsing only for public URLs. Auth-gated docs usually need their matching connector.
+
+2. Categorize every actionable item.
+
+   - **Bug**: Broken behavior, crash, wrong data, dead link, package/API mismatch, or captured exception. Verify and fix when you agree.
+   - **UX suggestion**: Design, discoverability, workflow, or feature feedback. Propose the cleanest version first unless the user explicitly asked you to implement UX changes.
+   - **Question or unclear**: Missing detail, contradictory feedback, or behavior you cannot inspect. Ask or flag it.
+   - **Out of scope**: Outside this repo, already shipped, intentionally unsupported, or too low-signal. Note briefly and skip.
+
+3. Check Sentry when the feedback smells like an error.
+
+   - Use the Sentry skill/plugin if available, or the repo's Sentry scripts if documented.
+   - Search by route, stack symbol, error text, and symptom keywords.
+   - Default org is `builder-io` unless the user specifies another.
+   - Cite issue IDs or links when you find a match.
+   - If nothing matches, say that plainly.
+
+4. Fix only the clear bugs you agree with.
+
+   - Verify before fixing: reproduce locally, read the relevant code, inspect logs, or confirm with a stack trace.
+   - Keep each fix narrow and mapped to a feedback item.
+   - Follow existing project conventions and nearby patterns.
+   - Do not switch branches, stash, reset, force-push, or open a PR unless the user asks.
+   - Add or update focused tests when the bug risk warrants it.
+
+5. Treat UX feedback with restraint.
+
+   Do not solve UX problems by adding more visible controls, helper text, banners, top-level nav, or always-open panels by default. Prefer cleaner interaction models:
+
+   - Make the existing primary action more discoverable.
+   - Remove competing elements so the right action stands out.
+   - Move secondary actions into `DropdownMenu`, `Popover`, `Sheet`, `Collapsible`, or tabs.
+   - Improve empty states around one clear action.
+   - Use progressive disclosure for optional or advanced controls.
+
+   When proposing a UX change, write it as: what to change, why it helps, and the tradeoff. Keep each proposal short.
+
+6. Verify changed behavior.
+
+   - Run the smallest relevant test or typecheck command.
+   - For UI fixes, verify in a browser when feasible and inspect the actual screen.
+   - If you cannot run a useful verification, say why.
+
+## Report Format
+
+Keep the final report short:
+
+```md
+## Bugs Fixed
+- [feedback item] - [what changed, file:line]
+
+## Bugs Flagged But Not Fixed
+- [feedback item] - [why]
+
+## UX Suggestions
+- [feedback item] -> [proposed change]
+
+## Skipped
+- [feedback item] - [reason]
+```
+
+Only include sections that have content. The user can read the diff; do not write a second feedback document.
+
+## Avoid
+
+- Do not agree with every suggestion by default.
+- Do not bundle unrelated cleanups.
+- Do not implement UX changes that make an important screen busier without explicit user approval.
+- Do not claim a UI change is done without browser verification when a local app can be run.
+- Do not invent Sentry matches, affected users, or reproduction steps.
+
+## Related Skills
+
+- `github:gh-address-comments` for GitHub PR review threads.
+- `github:gh-fix-ci` for failing GitHub checks.
+- `sentry:sentry` for production error investigation.
+- `frontend-design` for approved UI implementation work.
+- `qa` for broader browser verification.

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

@@ -0,0 +1,88 @@
+---
+name: authentication
+description: >-
+  How auth works in agent-native apps. Use when wiring login/signup,
+  configuring auth modes, setting up organizations, protecting routes, or
+  debugging session issues.
+---
+
+# Authentication
+
+## Rule
+
+Auth is powered by **Better Auth** with account-first design. Every new user creates an account on first visit. Use `getSession(event)` to authenticate custom routes; actions are auto-protected.
+
+## Auth Modes
+
+| Mode                      | Behavior                                                                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Development (default)** | Auth is automatically bypassed. `getSession()` falls back to `{ email: "local@localhost" }` when nothing else succeeds. No config.      |
+| **Production (default)**  | Better Auth with email/password + social providers (Google, GitHub). Organizations built in.                                             |
+| **`AUTH_MODE=local`**     | Explicit escape hatch. `getSession()` always returns `{ email: "local@localhost" }`. Set via `.env` or the onboarding page's "Use locally" button. |
+| **`AUTH_SKIP_EMAIL_VERIFICATION=1`** | QA/preview escape hatch for real email/password accounts. Signup skips email verification and does not send the signup verification email. Local dev/test skips verification by default; set `AUTH_SKIP_EMAIL_VERIFICATION=0` only when testing verification itself. Use `+qa` emails for test accounts. |
+| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Simple token-based auth for production deployments.                                                                           |
+| **`AUTH_DISABLED=true`**  | Skip auth entirely (for apps behind infrastructure-level auth like Cloudflare Access).                                                   |
+| **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |
+
+## Local → Real Account Migration
+
+Upgrading from `local@localhost` to a real account preserves SQL-backed workspace data. The built-in migration moves `application_state`, user-scoped `settings`, `oauth_tokens`, and any template table that uses `owner_email`.
+
+Templates with legacy global settings can provide `POST /api/local-migration` for one-time re-homing during the upgrade flow.
+
+## Organizations
+
+Better Auth's organization plugin is built in. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
+
+The active org flows automatically: `session.orgId` → `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.
+
+## A2A Identity
+
+Set `A2A_SECRET` (same value) on all apps that must verify each other's identity.
+
+- Outbound A2A calls are signed with JWTs
+- Inbound calls are verified cryptographically
+- Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev)
+
+## Builder Browser Access
+
+Apps can connect to Builder via the `cli-auth` flow and persist shared browser credentials in `.env`. Agents then use the built-in `get-browser-connection` tool to provision a real browser session via AI Services.
+
+## Protecting Custom Routes
+
+Actions are auto-protected. For custom `/api/` routes:
+
+```ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session) throw createError({ statusCode: 401 });
+  // ...
+});
+```
+
+Never create unprotected routes that modify data.
+
+## Sign-In from a Public Page
+
+For public pages (share links, embeds, marketing pages) that need anonymous viewers to sign in and return to where they were, navigate them through the framework's sign-in entry point — never roll your own:
+
+```ts
+const ret = window.location.pathname + window.location.search;
+window.location.href =
+  "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+```
+
+After successful sign-in (token / email-password / Google OAuth), the framework 302s to `return`. The path is validated as same-origin via the URL parser — open-redirect / header-injection inputs fall back to `/`.
+
+Bookmarked private paths already work without any plumbing — the framework's login page is served at the requested URL, and post-login reload returns the user there.
+
+## Related Skills
+
+- `security` — Data scoping, SQL injection, secrets
+- `actions` — Auto-protected by the auth guard