@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: storing-data
+description: >-
+  How and where to store application data. Use when adding new data models,
+  deciding between settings vs Drizzle tables, reading/writing app config,
+  or working with application state.
+---
+
+# Storing Data
+
+## Where Data Goes
+
+All data lives in one SQLite database (`data/app.db`). In production, set `DATABASE_URL` to point to Turso, Neon, Supabase, or D1 — same code, no changes needed.
+
+There are three storage layers, each for a different kind of data:
+
+### 1. Settings — app configuration
+
+Key-value store for persistent config that the user or agent can change. Theme, preferences, integration API keys, availability schedules.
+
+```ts
+import { getSetting, putSetting } from "@agent-native/core/settings";
+
+// Read (returns null if not set)
+const prefs = await getSetting("user-preferences");
+
+// Write (creates or replaces)
+await putSetting("user-preferences", { theme: "dark", density: "comfortable" });
+```
+
+From scripts:
+```ts
+import { readSetting, writeSetting } from "@agent-native/core/settings";
+const prefs = await readSetting("user-preferences");
+```
+
+SSE: writes automatically notify the UI via `{ source: "settings", type: "change", key }`.
+
+### 2. Application State — ephemeral UI state
+
+For state the agent and UI share in real-time: what the user is looking at, compose drafts, navigation commands. Scoped by session — cleared between sessions.
+
+```ts
+import { readAppState, writeAppState, deleteAppState, listAppState } from "@agent-native/core/application-state";
+
+// Write state (UI updates instantly via SSE)
+await writeAppState("navigate", { view: "inbox", threadId: "t-123" });
+
+// Read state
+const nav = await readAppState("navigation");
+
+// List by prefix (e.g., all compose drafts)
+const drafts = await listAppState("compose-");
+
+// Delete (one-shot commands: UI reads, then agent or UI deletes)
+await deleteAppState("navigate");
+```
+
+SSE: writes automatically notify the UI via `{ source: "app-state", type: "change", key }`.
+
+### 3. Drizzle Tables — structured domain data
+
+For data with schemas, relationships, and queries: forms, bookings, emails, compositions. Define tables in `server/db/schema.ts` using Drizzle ORM.
+
+```ts
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const bookings = table("bookings", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull(),
+  startTime: integer("start_time").notNull(),
+  endTime: integer("end_time").notNull(),
+});
+```
+
+Query via `getDb()` singleton from `server/db/index.ts`.
+
+### 4. OAuth Tokens — credentials
+
+For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated store.
+
+```ts
+import { saveOAuthTokens, getOAuthTokens, listOAuthAccounts } from "@agent-native/core/oauth-tokens";
+
+await saveOAuthTokens("google", "user@gmail.com", { access_token: "...", refresh_token: "..." });
+const tokens = await getOAuthTokens("google", "user@gmail.com");
+const accounts = await listOAuthAccounts("google");
+```
+
+## Which Layer to Use
+
+| Data | Layer | Why |
+|------|-------|-----|
+| User preferences, theme, config | Settings | Persistent KV, SSE notifications, simple read/write |
+| What the user sees on screen | Application State | Ephemeral, real-time sync, agent ↔ UI bridge |
+| Compose drafts, wizard steps | Application State | Temporary, deleted when done |
+| Domain records (forms, bookings) | Drizzle table | Needs schema, queries, relationships |
+| OAuth refresh tokens | OAuth Tokens | Secure, per-provider, per-account |
+
+## Environment Variables
+
+Infrastructure config stays in `.env` — these differ per deployment:
+
+- `DATABASE_URL` — database connection (default: `file:./data/app.db`)
+- `DATABASE_AUTH_TOKEN` — for remote databases
+- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` — OAuth app credentials
+- `ACCESS_TOKEN` — production auth token
+
+Everything else (user settings, tokens, app state) goes in SQL.
+
+## Security Rules
+
+- **Never store API keys or secrets in Settings or Application State** — use `.env` for API keys (gitignored) and the `oauth_tokens` store for OAuth credentials. Settings and application state are readable by the client.
+- **Every Drizzle table with user data must have `owner_email`** — the framework auto-scopes queries in production so users only see their own data. Run `pnpm action db-check-scoping` to verify. See the `security` skill for the full model.
+- **Never return secrets in action responses** — action responses may be visible in the agent chat or sent to the client. Keep credentials server-side only.

package/src/templates/default/.claude/settings.json

@@ -1,4 +1,17 @@
 {
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pnpm action view-screen 2>/dev/null || echo '{\"view\": \"unknown\"}'",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
       "Read",

package/src/templates/default/AGENTS.md

@@ -52,18 +52,33 @@ The `navigation` key is written by the UI whenever the route changes. The `navig
 
 ## Agent Operations
 
-**Always run `pnpm action view-screen` first** before taking any action. This tells you what the user is looking at.
+**Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
+
+### If you are the built-in agent-chat agent
+
+A `<current-screen>` block is auto-injected into every user message with the current view, IDs, and selected item. You can trust it for the first action of a turn without calling `view-screen`. If the user says "this" or "now do X" after several tool calls, the user may have navigated — call `view-screen` again for a fresh snapshot.
+
+### If you are an external CLI agent (Claude Code, Codex, Cursor, etc.)
+
+You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at the start of every task and before any edit** so you're acting on the IDs the user currently sees, not what was open earlier. Do not rely on cached context from previous turns.
 
 ### Actions
 
-| Action        | Args                              | Purpose                         |
-| ------------- | --------------------------------- | ------------------------------- |
-| `view-screen` |                                   | See current UI state            |
-| `navigate`    | `--view <name>` or `--path <url>` | Navigate the UI                 |
-| `hello`       | `[--name <name>]`                 | Example script                  |
-| `db-schema`   |                                   | Show all tables, columns, types |
-| `db-query`    | `--sql "SELECT ..."`              | Run a SELECT query              |
-| `db-exec`     | `--sql "INSERT ..."`              | Run INSERT/UPDATE/DELETE        |
+| Action        | Args                                                                           | Purpose                                                                                 |
+| ------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `view-screen` |                                                                                | See current UI state                                                                    |
+| `navigate`    | `--view <name>` or `--path <url>`                                              | Navigate the UI                                                                         |
+| `hello`       | `[--name <name>]`                                                              | Example script                                                                          |
+| `db-schema`   |                                                                                | Show all tables, columns, types                                                         |
+| `db-query`    | `--sql "SELECT ..."`                                                           | Run a SELECT query                                                                      |
+| `db-exec`     | `--sql "INSERT ..."`                                                           | Run INSERT/UPDATE/DELETE (use for short/multi-column writes)                            |
+| `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
+
+**Pick the right SQL tool:**
+
+- Use `db-exec UPDATE` for short columns, multi-column writes, or computed updates.
+- Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
+- If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
 
 ## Skills
 
@@ -78,6 +93,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | `self-modifying-code` | Before editing source, components, or styles                   |
 | `capture-learnings`   | Before recording user preferences or corrections               |
 | `frontend-design`     | Before building or restyling any UI component, page, or layout |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine  |
 
 ## When Adding Features
 

package/src/templates/default/_gitignore

@@ -1,5 +1,6 @@
 # React Router generated types
 .react-router/
+.agent-native/
 
 # Logs
 logs

package/src/templates/default/actions/view-screen.ts

@@ -13,7 +13,7 @@ import type { ScriptTool } from "@agent-native/core";
 
 export const tool: ScriptTool = {
   description:
-    "See what the user is currently looking at on screen. Returns the current navigation state. Always call this first before taking any action.",
+    "See what the user is currently looking at on screen. Returns the current navigation state. Note: basic screen context is auto-included with each message — use this tool only when you need a detailed or refreshed snapshot.",
   parameters: {
     type: "object",
     properties: {},

package/src/templates/default/app/root.tsx

@@ -23,7 +23,10 @@ export function Layout({ children }: { children: React.ReactNode }) {
     <html lang="en" suppressHydrationWarning>
       <head>
         <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta
+          name="viewport"
+          content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
+        />
         <link rel="manifest" href="/manifest.json" />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />

package/src/templates/default/package.json

@@ -11,11 +11,11 @@
     "script": "agent-native script"
   },
   "dependencies": {
-    "@agent-native/core": "^0.4.1",
+    "@agent-native/core": "^0.6.0",
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
     "@tabler/icons-react": "^3.40.0",
-    "h3": "^1.13.0",
+    "h3": "^2.0.1-rc.20",
     "isbot": "^5"
   },
   "devDependencies": {

package/src/templates/default/server/middleware/auth.ts

@@ -0,0 +1,15 @@
+/**
+ * Global auth middleware — runs for ALL requests (page routes, API routes,
+ * framework routes). The auth plugin configures the guard; this middleware
+ * enforces it on every request.
+ *
+ * Without this, auth only runs for /_agent-native/* routes because the
+ * framework handler's middleware registry is scoped to that catch-all.
+ * Page routes (/, /settings) and API routes (/api/*) would bypass auth.
+ */
+import { defineEventHandler } from "h3";
+import { runAuthGuard } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  return runAuthGuard(event);
+});

package/src/templates/default/server/routes/[...page].get.ts

@@ -1,12 +1,5 @@
-import { createRequestHandler } from "react-router";
-import { defineEventHandler, toWebRequest } from "h3";
+import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
 
-const handler = createRequestHandler(
-  // virtual module provided by React Router Vite plugin
+export default createH3SSRHandler(
   () => import("virtual:react-router/server-build"),
 );
-
-export default defineEventHandler(async (event) => {
-  const webReq = toWebRequest(event);
-  return handler(webReq);
-});

package/src/templates/default/ssr-entry.ts

@@ -0,0 +1,20 @@
+/**
+ * SSR entry point for Nitro.
+ *
+ * This wraps React Router's request handler so Nitro can use it as an
+ * SSR service. The file must be a real file (not a virtual module) so
+ * Nitro can resolve it during build.
+ *
+ * Similar to how TanStack Start provides a server.ts entry for Nitro.
+ */
+import { createRequestHandler } from "react-router";
+
+const handler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+);
+
+export default {
+  async fetch(request: Request) {
+    return handler(request);
+  },
+};

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

@@ -0,0 +1,62 @@
+# {{APP_TITLE}} — Enterprise Agent Instructions
+
+These instructions apply to **every app** in the {{APP_TITLE}} workspace. The
+framework auto-injects this file into each app's agent system prompt as a
+`<resource name="AGENTS.md" scope="workspace">` block. Individual apps can
+add their own template-specific AGENTS.md on top.
+
+## Company context
+
+Write a short paragraph here describing your company and what you do. The
+agent reads this first so every response can be grounded in the same
+business context without you having to repeat it per app.
+
+## Shared conventions
+
+- **All cross-app state lives in the shared database.** Apps in this
+  workspace share `DATABASE_URL` by default, so a record created by one
+  app can be read by another as long as it respects the `owner_email` and
+  `org_id` scoping conventions.
+- **All API secrets come from the central credential store.** Never
+  hardcode a token. Call `resolveCompanyCredential("KEY")` from
+  `@{{APP_NAME}}/core-module/credentials` — it pulls from env first and
+  falls back to the shared settings table so one rotation updates every
+  app.
+- **UI chrome comes from the workspace core.** Wrap every screen in
+  `<AuthenticatedLayout>` from `@{{APP_NAME}}/core-module/client`. Don't
+  re-implement the brand header, sidebar, or org switcher per app.
+- **Design system.** If the app needs a button, dialog, or form control,
+  import from our internal design system package (if you have one) or
+  from the shared UI re-exports in `@{{APP_NAME}}/core-module/client`.
+
+## Compliance and policy
+
+List any enterprise-wide rules the agent must follow — data handling, PII
+guidelines, approval flows, deployment constraints. The agent will apply
+these to every decision it makes in every app.
+
+Example rules:
+
+- Never expose raw customer email addresses in logs.
+- Any action that modifies data must first be shown to the user with a
+  preview and wait for confirmation.
+- Never make network calls to anything outside `*.{{APP_NAME}}.com` or
+  the approved third-party allowlist.
+
+## How to add a new app
+
+```bash
+cd apps
+pnpm exec agent-native create <app-name>
+```
+
+The new app will automatically inherit:
+
+1. The workspace auth plugin (Better Auth + company SSO)
+2. The agent chat plugin with this AGENTS.md pre-loaded
+3. Every skill in `packages/core-module/skills/`
+4. Every action in `packages/core-module/actions/`
+5. The shared Tailwind preset and React components
+
+The only files the new app needs to own are its own routes/screens and any
+template-specific actions.

package/src/templates/workspace-core/actions/company-directory.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared action: look up an employee in the company directory.
+ *
+ * Every app in the workspace inherits this action automatically — no
+ * wiring required. From the agent's perspective it behaves exactly like
+ * a template action: the tool shows up in every app's agent, and calling
+ * it from the UI via `useActionQuery("company-directory", { ... })` Just
+ * Works.
+ *
+ * Replace the stub implementation with a real call to your company
+ * directory (SCIM, Okta Users API, internal /people endpoint, etc.).
+ */
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description:
+    "Look up a person in the {{APP_TITLE}} company directory by name or email. Returns role, team, and manager.",
+  schema: z.object({
+    query: z.string().describe("Name, email, or partial match to search for"),
+  }),
+  run: async (args) => {
+    // TODO: replace with a real lookup. This stub just echoes the query
+    // so the agent has a reasonable no-op while you wire up the real
+    // directory integration.
+    return {
+      results: [
+        {
+          query: args.query,
+          name: "(stub) " + args.query,
+          role: "Unknown",
+          team: "Unknown",
+          manager: null,
+        },
+      ],
+    };
+  },
+});

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

@@ -0,0 +1,39 @@
+{
+  "name": "@{{APP_NAME}}/core-module",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "default": "./src/server/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./src/client/index.ts"
+    },
+    "./credentials": {
+      "types": "./src/credentials.ts",
+      "default": "./src/credentials.ts"
+    },
+    "./tailwind": {
+      "types": "./tailwind.preset.ts",
+      "default": "./tailwind.preset.ts"
+    }
+  },
+  "dependencies": {
+    "@agent-native/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.23",
+    "react": "^18.3.1",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  }
+}

package/src/templates/workspace-core/skills/company-policies/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: company-policies
+description: {{APP_TITLE}}-wide policies the agent must enforce for every app — data handling, PII, approval flows, compliance rules.
+---
+
+# {{APP_TITLE}} Company Policies
+
+Every app in the workspace shares these policies. Read this skill before
+taking any action that touches customer data, external services, or
+deployed state.
+
+## Data handling
+
+- **PII minimization.** Only load the fields you actually need. Never
+  `SELECT *` on a table that contains customer records.
+- **No raw customer email in logs.** Hash or redact before logging.
+- **Retention.** Deleted records are soft-deleted first and purged by a
+  scheduled job. Do not write actions that hard-delete customer data.
+
+## Third-party calls
+
+- **Allowlist only.** Only call domains on the approved allowlist
+  (documented in the root `README.md`). If an integration needs a new
+  domain, surface a warning and wait for human approval before making
+  the call.
+- **Secrets come from `resolveCompanyCredential`.** Never hardcode.
+  Never check secrets into git. Rotating a key in the central store
+  updates every app on the next request.
+
+## Approval flows
+
+- **Destructive operations need a confirmation preview.** Any action
+  that modifies production data must first return a preview of the
+  change (what will be created / updated / deleted) and wait for
+  explicit user confirmation before executing.
+
+## Apply across apps
+
+This skill is loaded automatically in every workspace app. If an
+individual app needs different behavior, it can add a same-named skill
+under its own `.agents/skills/company-policies/SKILL.md` and that copy
+will win for that app only.

package/src/templates/workspace-core/src/client/AuthenticatedLayout.tsx

@@ -0,0 +1,37 @@
+/**
+ * Shared authenticated layout for every app in the @{{APP_NAME}} workspace.
+ *
+ * Provides the common chrome (brand header, user menu, agent chat sidebar)
+ * so individual apps only have to render their own content. Replace this
+ * with a real component that pulls in your design system. Every app
+ * imports it the same way:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ *   export default function Home() {
+ *     return (
+ *       <AuthenticatedLayout>
+ *         <h1>My app's screen</h1>
+ *       </AuthenticatedLayout>
+ *     );
+ *   }
+ */
+import type { ReactNode } from "react";
+
+export interface AuthenticatedLayoutProps {
+  children: ReactNode;
+}
+
+// Workspace title — replaced at scaffold time by the create-workspace CLI.
+const WORKSPACE_TITLE = "{{APP_TITLE}}";
+
+export function AuthenticatedLayout({ children }: AuthenticatedLayoutProps) {
+  return (
+    <div className="min-h-screen flex flex-col">
+      <header className="border-b px-6 py-3">
+        <strong>{WORKSPACE_TITLE}</strong>
+      </header>
+      <main className="flex-1 p-6">{children}</main>
+    </div>
+  );
+}

package/src/templates/workspace-core/src/client/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side entry for @{{APP_NAME}}/core-module.
+ *
+ * This is where shared React components, hooks, and providers that EVERY
+ * app in your workspace needs live. Think of it as the "app shell" layer
+ * between the framework's primitives (@agent-native/core/client) and the
+ * individual app's screens:
+ *
+ *   - Authenticated layouts (header / sidebar / footer with brand)
+ *   - Org switchers wired to your company's org plugin
+ *   - Common chrome: loading states, error boundaries, empty states
+ *   - Wrappers around @agent-native/core components that apply your
+ *     enterprise design tokens
+ *
+ * Apps import from here instead of re-implementing or copy-pasting:
+ *
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *
+ * NOTE: This package does not ship shadcn/ui or a generic design system
+ * by default. If you already have an internal `@{{APP_NAME}}/design-system`
+ * package, add it as a dep here and re-export from this file. Otherwise
+ * you can drop any shadcn components the apps share into `./ui/` and
+ * export them from this index.
+ */
+
+export { AuthenticatedLayout } from "./AuthenticatedLayout.js";

package/src/templates/workspace-core/src/credentials.ts

@@ -0,0 +1,29 @@
+/**
+ * Centralized credential helpers for the @{{APP_NAME}} workspace.
+ *
+ * Every enterprise has a few API keys that multiple apps need to share:
+ * a Slack bot token, a Sentry DSN, an OpenAI key, internal service
+ * credentials. Instead of each app reading them separately, we namespace
+ * them here so there's a single place to update when a key rotates.
+ *
+ * Under the hood this is a thin wrapper over @agent-native/core's
+ * `resolveCredential()`, which reads `process.env.<KEY>` first and
+ * falls back to `credential:<KEY>` in the shared settings table.
+ * Apps inside the workspace share the same DATABASE_URL by default,
+ * so storing a credential once makes it available everywhere.
+ */
+import { resolveCredential } from "@agent-native/core/credentials";
+
+/**
+ * Resolve a company-wide credential. Prefer this over `resolveCredential()`
+ * directly — it keeps your keys organized under a workspace namespace and
+ * makes "where does this secret come from" greppable.
+ *
+ * Example:
+ *   const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN");
+ */
+export async function resolveCompanyCredential(
+  key: string,
+): Promise<string | undefined> {
+  return await resolveCredential(key);
+}

package/src/templates/workspace-core/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @{{APP_NAME}}/core-module — enterprise-wide workspace core.
+ *
+ * Every agent-native app in this workspace inherits from this package:
+ *   - Server plugins (auth, org, agent-chat) — see src/server
+ *   - Shared React components and hooks — see src/client
+ *   - Shared agent actions — see actions/
+ *   - Shared agent skills — see skills/
+ *   - Enterprise-wide agent instructions — see AGENTS.md
+ *   - Shared Tailwind preset — see tailwind.preset.ts
+ *
+ * Apps don't import from this root entry directly — they import from
+ * the specific sub-path they need:
+ *
+ *   import { authPlugin } from "@{{APP_NAME}}/core-module/server";
+ *   import { AuthenticatedLayout } from "@{{APP_NAME}}/core-module/client";
+ *   import { resolveCompanyCredential } from "@{{APP_NAME}}/core-module/credentials";
+ *
+ * This root file is for package metadata only.
+ */
+export const WORKSPACE_CORE_NAME = "@{{APP_NAME}}/core-module";

package/src/templates/workspace-core/src/server/agent-chat-plugin.ts

@@ -0,0 +1,30 @@
+/**
+ * Workspace-wide agent-chat plugin for @{{APP_NAME}}/core-module.
+ *
+ * This mounts the framework's default agent-chat plugin so every app in
+ * the workspace gets the same chat endpoint, mention providers, and
+ * built-in tools. The ENTERPRISE-WIDE system prompt additions — things
+ * the agent should know across every app — live in the workspace's
+ * AGENTS.md file, which is loaded automatically into the prompt as a
+ * `<resource scope="workspace">` block.
+ *
+ * Customize this wrapper when you need agent behavior that can't be
+ * expressed in AGENTS.md — e.g. injecting enterprise-specific mention
+ * providers, pre-loading a custom set of MCP servers, or rewriting
+ * model choice based on your company's allowlist.
+ */
+import { defaultAgentChatPlugin } from "@agent-native/core/server";
+
+export const agentChatPlugin = async (nitroApp: any): Promise<void> => {
+  await defaultAgentChatPlugin(nitroApp);
+
+  // Hook for enterprise customization:
+  //
+  //   const chat = createAgentChatPlugin({
+  //     systemPrompt: (base) => `${base}\n\nCompany policy: …`,
+  //     mentionProviders: {
+  //       people: async (query) => searchCompanyDirectory(query),
+  //     },
+  //   });
+  //   await chat(nitroApp);
+};

package/src/templates/workspace-core/src/server/auth-plugin.ts

@@ -0,0 +1,35 @@
+/**
+ * Workspace-wide auth plugin for @{{APP_NAME}}/core-module.
+ *
+ * Today this just re-uses the framework default, which already does the
+ * right thing for most enterprises (Better Auth with Google SSO when
+ * GOOGLE_CLIENT_ID/SECRET are set, email/password otherwise, local dev
+ * bypass via AUTH_MODE=local). Customize it here when your enterprise
+ * needs specific behavior — e.g.:
+ *
+ *   - Wrap the default to force a specific SSO provider
+ *   - Add a callback that provisions users into your directory
+ *   - Pre-register organizations / role mappings from Okta groups
+ *   - Fail closed on unauthenticated requests outside dev
+ *
+ * Every app in the workspace inherits this automatically (as long as the
+ * root package.json has `"agent-native": { "workspaceCore": "@{{APP_NAME}}/core-module" }`).
+ */
+import { defaultAuthPlugin } from "@agent-native/core/server";
+
+export const authPlugin = async (nitroApp: any): Promise<void> => {
+  // Run the framework default first so Better Auth, org tables, and session
+  // middleware are all set up.
+  await defaultAuthPlugin(nitroApp);
+
+  // Add enterprise-specific post-auth behavior here. Examples:
+  //
+  //   const h3 = getH3App(nitroApp);
+  //   h3.use(defineEventHandler(async (event) => {
+  //     const session = await getSession(event);
+  //     if (session?.email && !session.email.endsWith("@{{APP_NAME}}.com")) {
+  //       setResponseStatus(event, 403);
+  //       return { error: "Only @{{APP_NAME}}.com accounts allowed" };
+  //     }
+  //   }));
+};