@agent-native/core 0.26.9 → 0.28.0

package/docs/content/template-design.md

@@ -66,6 +66,33 @@ The rest of this doc is for anyone forking the Design template or extending it.
 pnpm dlx @agent-native/core create my-design --template design --standalone
 ```
 
+### Data Model
+
+All data lives in SQL via Drizzle ORM. Schema: `templates/design/server/db/schema.ts`. Designs and design systems carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+| Table                                    | What it holds                                                                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `designs`                                | A design project — `title`, `description`, `project_type` (`prototype` / `other`), the `data` JSON blob, and an optional `design_system_id` link |
+| `design_files`                           | Individual files belonging to a design (`filename`, `content`, `file_type` defaulting to `html`)                                                 |
+| `design_versions`                        | Point-in-time `snapshot`s of a design with an optional `label`, for history and rollback                                                         |
+| `design_systems`                         | Reusable brand tokens — `data` (colors/typography/spacing), `assets`, `custom_instructions`, and an `is_default` flag                            |
+| `design_shares` / `design_system_shares` | Framework shares tables mapping principals (users or orgs) to roles (viewer, editor, admin)                                                      |
+
+A design project is a shell until it has content: `create-design` makes an empty row (`data: "{}"`), then `generate-design` writes the actual standalone HTML/JSX files. The generated artifact, the editable source, and every export all come from the same HTML, so there is no separate "AI mockup" format to translate. A linked design system supplies tokens and `custom_instructions` that the agent honors on every generation pass.
+
+Routes in the UI live under `templates/design/app/routes/`: `_index.tsx` (list), `design.$id.tsx` (editor), `present.$id.tsx` (presentation), `design-systems.tsx` and `design-systems_.setup.tsx`, `templates.tsx`, `examples.tsx`, plus `settings.tsx` and `team.tsx`.
+
+### Key Actions
+
+Every agent-callable operation is a TypeScript file in `templates/design/actions/`, auto-mounted at `POST /_agent-native/actions/:name` and runnable from the CLI as `pnpm action <name>`. The groupings:
+
+- **Designs** — `create-design` (empty shell), `generate-design` (write generated HTML/JSX content), `update-design`, `get-design`, `list-designs`, `duplicate-design`, `delete-design`, and `apply-tweaks` for persisting live tweak-knob values (accent color, density, etc.).
+- **Files** — `create-file`, `update-file`, `list-files`, `delete-file` for the files inside a design project.
+- **Design systems** — `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `delete-design-system`, `set-default-design-system`, and `analyze-brand-assets` for gathering brand data ahead of analysis.
+- **Import** — `import-code`, `import-figma`, `import-github`, `import-from-url`, `import-document` (DOCX/PPTX/PDF/XLSX), and `import-design-project` to lift a design system out of an existing project.
+- **Export & handoff** — `export-html`, `export-pdf`, `export-svg`, `export-zip`, and `export-coding-handoff` to turn a design into a coding-tool handoff.
+- **Context & navigation** — `view-screen` (current design, open file, view, pending question or variant grid), `get-design-snapshot` (current state for an external agent to continue from), and `navigate`.
+
 ### Customize It
 
 Design is a complete, cloneable template. Some practical extension ideas:

package/docs/content/template-dispatch.md

@@ -1,5 +1,5 @@
 ---
-title: "Dispatch Template"
+title: "Dispatch"
 description: "Dispatch is the workspace control plane — central inbox, cross-app orchestration, secrets vault, Slack/Telegram integration, and scheduled jobs."
 ---
 
@@ -73,7 +73,7 @@ Day-to-day, Dispatch is the place admins and ops folks open to keep the workspac
 _How it works under the hood (for developers)._
 
 - **Orchestrator agent.** The chat is set up as a router: it reads `AGENTS.md`, `LEARNINGS.md`, and routes to specialist sub-agents or remote A2A agents.
-- **Remote agent registry.** A2A manifests live in `remote-agents/*.json` — one per app. Dispatch calls them using the `call-agent` action. In a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers — no manual registration needed.
+- **Remote agent registry.** A2A agent manifests are workspace-runtime entries (not a checked-in template source folder): in a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers — no manual registration needed. Dispatch calls them using the `call-agent` action.
 - **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. See `server/db/schema.ts` in the template.
 - **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
 - **Workspace MCP resources.** Add HTTP MCP server definitions under `mcp-servers/*.json` in Resources, then scope them to All apps or selected app grants just like skills and context.
@@ -89,7 +89,7 @@ When Dispatch approval policy is enabled, applying a shared or team-wide dream p
 
 Use Dreams when you want to answer questions like "what did agents keep getting wrong this week?", "what should we remember?", or "which repeated lesson deserves a skill?" Inbound Slack, email, Telegram, WhatsApp, and web-derived evidence is treated as untrusted input, so proposals from those sources require review and provenance before they affect shared memory. Workspace-instruction proposals require durable evidence spanning at least two threads or two source apps; eval-only noise, account setup issues, quota limits, and single-app UI wording corrections stay out of global instructions.
 
-### Dream Input Validation Boundaries
+### Dream input validation boundaries
 
 Because evidence is collected from external, untrusted sources (such as chat transcripts, webhooks, and third-party integrations), the Dream processor enforces strict input validation boundaries to prevent prompt injection and payload-size attacks:
 

package/docs/content/template-forms.md

@@ -1,5 +1,5 @@
 ---
-title: "Forms Template"
+title: "Forms"
 description: "Agent-native form builder — create, edit, publish, and route form submissions through natural language plus a visual editor."
 ---
 
@@ -28,7 +28,7 @@ When you open the app, you see your forms, the current editor, and a live previe
 - **Route submissions.** Send submission payloads to webhooks, Slack, Discord, or Google Sheets using the built-in integrations.
 - **Publish public forms.** Share a public form URL and show a thank-you message after submission.
 
-## Start Here
+## Getting started
 
 1. **Create a form from a prompt.** Ask for the form you want, including the
    audience and what should happen after submission.
@@ -39,7 +39,7 @@ When you open the app, you see your forms, the current editor, and a live previe
 4. **Connect destinations.** Route new submissions to Slack, Discord, Google
    Sheets, webhooks, or your own extension point.
 
-## Useful Prompts
+## Useful prompts
 
 - "Create a beta signup form with role, team size, and priority use case."
 - "Add a required NPS question and a free-text follow-up."
@@ -53,7 +53,7 @@ The useful part of an agent-native form builder is that setup and iteration happ
 
 See [What is agent-native?](/docs/what-is-agent-native) for the broader framework model.
 
-## For Developers
+## For developers
 
 ### Scaffolding
 
@@ -69,7 +69,7 @@ pnpm dlx @agent-native/core create my-platform
 
 Pick Forms and any other templates you want during the workspace setup.
 
-### Customize It
+### Customizing it
 
 Ask the agent for shipped behavior first:
 
@@ -81,7 +81,7 @@ Ask the agent for shipped behavior first:
 
 If you need new capabilities such as file uploads, signatures, or custom field widgets, treat them as template extensions: add the SQL shape, actions, UI editor controls, public renderer support, and agent instructions together. See [Creating Templates](/docs/creating-templates) for the current build pattern.
 
-## What's Next
+## What's next
 
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model
 - [**Actions**](/docs/actions) — the action system powering the builder

package/docs/content/template-starter.md

@@ -1,5 +1,5 @@
 ---
-title: "Starter Template"
+title: "Starter"
 description: "The minimal agent-native scaffold — agent chat, actions, application state, live sync, auth — wired up, with no domain code. Build from scratch."
 ---
 
@@ -24,7 +24,7 @@ Pick Starter when you're not sure which domain template fits, or when you want t
 - **Agent sidebar** (`<AgentSidebar>`) wired into `app/root.tsx`. Chat, CLI, workspace tabs all present.
 - **Agent chat plugin** pre-configured so the chat actually talks to Claude (once `ANTHROPIC_API_KEY` is set).
 - **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped so signup is just an email + password.
-- **Actions directory** with one example (`actions/hello-world.ts`) and the `view-screen` / `navigate` standard actions wired up.
+- **Actions directory** with one example (`actions/hello.ts`) and the `view-screen` / `navigate` standard actions wired up.
 - **Drizzle schema** with the framework's core tables (application_state, settings, oauth_tokens, sessions, resources).
 - **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
 - **AGENTS.md** with the framework-wide rules the agent reads on every turn.

package/docs/content/using-your-agent.md

@@ -0,0 +1,56 @@
+---
+title: "Using Your Agent"
+description: "The day-to-day loop of working with the agent: it sees what you're looking at, you direct it, embed it, go UI-light, and co-edit alongside it."
+---
+
+# Using Your Agent
+
+The defining idea behind agent-native is that the agent and the UI are **equal partners** — see [What Is Agent-Native?](/docs/what-is-agent-native) for the why. This section is about the other half of that promise: what it feels like to actually work with the agent once it's docked next to your app.
+
+There's a simple through-line. The agent **sees** what you're looking at, you **direct** it toward what you want, you can **embed** it anywhere, you can go fully **UI-light** when that's the better fit, and you can **co-edit** the same documents at the same time. Each of those is a page in this section.
+
+## It sees what you're looking at {#it-sees}
+
+The agent isn't blind to your screen. Open an email and it knows which thread. Select a chart and it knows which chart. Highlight a paragraph and it can act on just that range. That shared awareness is what lets you say "reply to this" or "summarize the selection" without spelling out the context every time.
+
+This works because the current navigation and selection live in `application_state` SQL, which the agent reads as part of its context. The agent can also drive that same state back — opening a view, selecting a row — so you watch it work in the real UI rather than in a transcript.
+
+→ [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, navigate commands, and how the agent stays in sync with your screen.
+
+## You direct it {#you-direct-it}
+
+Most of the time you steer the agent by typing into the chat. Two things make that faster.
+
+**Mentions.** Tag a custom agent, a connected agent, or a file with `@` to pull it into the conversation — "let `@analytics` pull last week's numbers, then draft the summary." Mentions are how you reach the right specialist or attach the right context without leaving the composer.
+
+**Voice.** The composer has a microphone. Dictate a request instead of typing it, with provider options ranging from Builder's hosted transcription to bring-your-own-key to a browser fallback.
+
+→ [**Agent Mentions**](/docs/agent-mentions) — `@`-mention custom agents, connected agents, and files in chat.
+→ [**Voice Input**](/docs/voice-input) — dictation in the chat composer and how transcription is routed.
+
+## You embed it {#you-embed-it}
+
+The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
+
+→ [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>`, `<AgentSidebar>`, and `sendToAgentChat()` into any React app.
+
+## You can go UI-light {#ui-light}
+
+Not every app needs a full dashboard. When the agent _is_ the product, you can skip most of the custom UI: open the app, ask for what you want, and let the agent do the rest. The agent still has its management surface — history, workspace, settings — but the primary interaction is conversation rather than clicks.
+
+→ [**Pure-Agent Apps**](/docs/pure-agent-apps) — apps where the agent is the whole product.
+
+## You co-edit with it {#you-co-edit}
+
+When you and the agent are working on the same document, you don't take turns. With real-time collaboration, the agent's edits stream in alongside yours — live cursors, no overwrites — the same way a teammate's would. You can keep typing while it works, and it sees your changes as they happen.
+
+→ [**Real-Time Collaboration**](/docs/real-time-collaboration) — multi-user collaborative editing with live cursors and agent edits in the same document.
+
+## What's next {#whats-next}
+
+- [**Context Awareness**](/docs/context-awareness) — the agent knows what you're looking at
+- [**Agent Mentions**](/docs/agent-mentions) — direct it with `@`-mentions
+- [**Voice Input**](/docs/voice-input) — direct it by speaking
+- [**Drop-in Agent**](/docs/drop-in-agent) — embed it in any React app
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) — go UI-light when the agent is the product
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — co-edit the same document together

package/docs/content/workspace-management.md

@@ -25,7 +25,7 @@ main                         ← production
 
 **Naming conventions:**
 
-- **Single-app changes:** `feat/<app>-<description>` or `fix/<app>-<description>` — e.g. `feat/mail-thread-search`, `fix/recruiting-resume-parse`
+- **Single-app changes:** `feat/<app>-<description>` or `fix/<app>-<description>` — e.g. `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
 - **Framework changes:** `feat/core-<description>` or `fix/core-<description>` — e.g. `feat/core-polling-v2`
 - **Dispatch changes:** `feat/dispatch-<description>` — e.g. `feat/dispatch-vault-policies`
 - **Cross-app changes:** if a framework change requires template updates, do both in one branch so they ship atomically
@@ -69,9 +69,9 @@ templates/mail/                    @your-org/mail-team
 templates/analytics/               @your-org/analytics-team
 templates/calendar/                @your-org/calendar-team
 templates/content/                 @your-org/content-team
-templates/recruiting/              @your-org/recruiting-team
+templates/design/                  @your-org/design-team
 templates/forms/                   @your-org/forms-team
-templates/issues/                  @your-org/issues-team
+templates/clips/                   @your-org/clips-team
 templates/slides/                  @your-org/slides-team
 templates/videos/                  @your-org/videos-team
 
@@ -119,9 +119,9 @@ app:calendar:
   - changed-files:
       - any-glob-to-any-file: templates/calendar/**
 
-app:recruiting:
+app:design:
   - changed-files:
-      - any-glob-to-any-file: templates/recruiting/**
+      - any-glob-to-any-file: templates/design/**
 
 dispatch:
   - changed-files:
@@ -260,7 +260,7 @@ For a new workspace, after running `agent-native create`:
 - [ ] Register reusable workspace connections for shared provider accounts, then
       grant apps such as Brain, Analytics, Mail, or Dispatch only when they need
       that account
-- [ ] Add workspace-wide skills, guardrail instructions, and brand/company reference resources via the Resources page: `context/company.md`, `context/brand.md`, `context/messaging.md`, `instructions/guardrails.md`, and `skills/company-voice/SKILL.md`
+- [ ] Add workspace-wide skills, guardrail instructions, and brand/company reference resources via the Resources page. See [Workspace](/docs/workspace#global-resources) for the full resource-model table and the recommended starter pack.
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
 - [ ] Connect Slack or Telegram for workspace messaging

package/docs/content/workspace.md

@@ -63,6 +63,25 @@ Resources have three runtime scopes:
 
 The in-app Workspace panel shows all three scopes. Personal and shared/organization resources are editable there. Workspace-scope resources are read-only in app panels and edited centrally from Dispatch, so every app sees the same canonical files without a sync step.
 
+### Global resources and canonical paths {#global-resources}
+
+Workspace-scope resources are managed from Dispatch's **Resources** page and inherited by apps at runtime — no copy or sync step. Dispatch supports two grant scopes:
+
+- **All apps** — global resources every app in the workspace inherits. Most company, brand, persona, positioning, messaging, and guardrail context should be **All apps**.
+- **Selected apps** — resources granted to specific apps for app-specific context or tools. Use these sparingly.
+
+The path determines how the agent uses a resource. These canonical paths apply across all three scopes (workspace, organization/app, personal):
+
+| Runtime resource        | Path                                    | How agents use it                               |
+| ----------------------- | --------------------------------------- | ----------------------------------------------- |
+| Guardrail instructions  | `AGENTS.md` or `instructions/<slug>.md` | Loaded every turn in every app that receives it |
+| Global skills           | `skills/<slug>/SKILL.md`                | Listed as workspace skills and read on demand   |
+| Brand/company resources | `context/<slug>.md`                     | Indexed every turn, read when relevant          |
+| Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
+| Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |
+
+This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
+
 ## Workspace Panel {#workspace-panel}
 
 The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse workspace resources, create/edit/delete personal or organization resources, and view inherited workspace defaults. It displays a tree view of all resources organized by folder path.
@@ -120,7 +139,7 @@ Change how the agent behaves, in 60 seconds.
 
 ## How the Agent Uses Resources {#how-the-agent-uses-resources}
 
-The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-effective`, `resource-write`, and `resource-delete`. These are available in both dev and production modes.
+The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-effective`, `resource-write`, and `resource-delete`. These are available in both Code mode and App mode.
 
 At the start of every conversation, the agent automatically reads:
 
@@ -318,8 +337,8 @@ When the agent encounters a task that matches a skill, it reads the skill file a
 
 There are two ways to add skills:
 
-1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill/SKILL.md`. This works in both dev and production.
-2. **Via code (dev only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in dev mode.
+1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill/SKILL.md`. This works in both Code mode and App mode.
+2. **Via code (Code mode only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in Code mode.
 
 ## Custom Agents {#custom-agents}
 
@@ -416,8 +435,8 @@ When you send a message:
 
 What shows up depends on the mode:
 
-- **Dev mode** — Codebase files, workspace resources, custom agents, and connected agents
-- **Production mode** — Workspace resources, custom agents, and connected agents
+- **Code mode** — Codebase files, workspace resources, custom agents, and connected agents
+- **App mode** — Workspace resources, custom agents, and connected agents
 
 ## / Slash Commands {#slash-commands}
 
@@ -425,16 +444,16 @@ Type `/` at the start of a line to invoke a skill. A dropdown shows available sk
 
 What shows up depends on the mode:
 
-- **Dev mode** — Skills from `.agents/skills/` (codebase) and skills from resources
-- **Production mode** — Skills from resources only
+- **Code mode** — Skills from `.agents/skills/` (codebase) and skills from resources
+- **App mode** — Skills from resources only
 
 If no skills are configured, the dropdown shows a hint with a link to these docs.
 
-## Dev vs Production Mode {#dev-vs-prod}
+## Code vs App Mode {#dev-vs-prod}
 
 The resource system works identically in both modes. The difference is what additional sources are available for `@` tagging and `/` commands:
 
-| Feature            | Dev Mode                                                                | Production                                             |
+| Feature            | Code Mode                                                               | App Mode                                               |
 | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
 | @ tagging          | Codebase files + workspace resources + custom agents + connected agents | Workspace resources + custom agents + connected agents |
 | / slash commands   | .agents/skills/ + resource skills                                       | Resource skills only                                   |

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@agent-native/core",
-  "version": "0.26.9",
+  "version": "0.28.0",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
   "repository": {
@@ -57,6 +60,7 @@
     "./secrets": "./dist/secrets/index.js",
     "./org": "./dist/org/index.js",
     "./client/org": "./dist/client/org/index.js",
+    "./client/db-admin": "./dist/client/db-admin/index.js",
     "./sharing": "./dist/sharing/index.js",
     "./sharing/actions/share-resource": "./dist/sharing/actions/share-resource.js",
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",
@@ -104,8 +108,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest --run src",
     "prepack": "npm run build && cp ../../README.md ./README.md",
-    "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish --access public"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@amplitude/analytics-browser": "^2.41.1",
@@ -113,6 +116,8 @@
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
     "@clack/prompts": "^1.4.0",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/theme-one-dark": "^6.1.3",
     "@libsql/client": "^0.15.0",
     "@modelcontextprotocol/ext-apps": "1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -129,12 +134,14 @@
     "@standard-schema/spec": "^1.1.0",
     "@tabler/icons-react": "^3",
     "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/react-table": "^8.21.3",
     "@tiptap/core": "^3.22.2",
     "@tiptap/extension-link": "^3.22.2",
     "@tiptap/extension-placeholder": "^3.22.2",
     "@tiptap/pm": "^3.22.2",
     "@tiptap/react": "^3.22.2",
     "@tiptap/starter-kit": "^3.22.2",
+    "@uiw/react-codemirror": "^4.25.10",
     "better-auth": "1.6.0",
     "better-sqlite3": "^12.8.0",
     "clsx": "^2.1.1",

package/src/templates/default/AGENTS.md

@@ -21,12 +21,12 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 
 ### Authentication
 
-Auth is automatic and environment-driven:
+Auth is real Better Auth in every environment — there is **no dev bypass**:
 
-- **Dev mode**: Auth is bypassed. `getSession()` returns `{ email: "local@localhost" }`.
-- **Production** (`ACCESS_TOKEN` set): Auth middleware auto-mounts.
+- **Development**: the same Better Auth flow as production. On first run the framework auto-creates a throwaway dev account and signs you in (so you are not stuck at a login wall). `getSession()` returns the signed-in user or `null` — it never returns a `local@localhost` sentinel.
+- **Production**: Better Auth with email/password + social providers; organizations built in.
 
-Use `getSession(event)` server-side and `useSession()` client-side.
+Use `getSession(event)` server-side and `useSession()` client-side. When there is no session, **throw or return 401** — never fall back to `local@localhost` (that pools every unauthenticated request into one shared tenant).
 
 ## Resources
 

package/src/templates/default/app/routes/database.tsx

@@ -0,0 +1,13 @@
+import { DbAdminPage } from "@agent-native/core/client/db-admin";
+
+export function meta() {
+  return [{ title: "Database" }];
+}
+
+export default function DatabasePage() {
+  return (
+    <div className="p-6">
+      <DbAdminPage />
+    </div>
+  );
+}

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

@@ -16,14 +16,21 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 
 | Mode                      | Behavior                                                                                                                                 |
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| **Development (default)** | Auth is automatically bypassed. `getSession()` falls back to `{ email: "local@localhost" }` when nothing else succeeds. No config.      |
+| **Development (default)** | Real Better Auth — same flow as production. There is **no auth bypass**. On first run the framework auto-creates a throwaway dev account and signs you in (credentials printed once to the console; disable with `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1`), so you are not stuck at a login wall. `getSession()` returns the signed-in user or `null` — it never falls back to a sentinel identity. |
 | **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_MODE=local`**     | **Not** a browser auth bypass, and never returns `local@localhost`. It only affects CLI/agent identity: it lets `pnpm action` / the local agent loop auto-bind to the single real signed-in dev user from the `sessions` table (see `scripts/dev-session.ts`). Browser login is unchanged. |
 | **`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 })`.                                                                     |
 
+> **Never** use `local@localhost` as a fallback identity in app code
+> (`getRequestUserEmail() ?? "local@localhost"`, `session?.email ?? "local@localhost"`,
+> etc.). There is no dev auth shim. That pattern pools every unauthenticated
+> request into one shared tenant and caused the 2026-04-29 credentials leak.
+> When there is no session, **throw or return 401** — never substitute a
+> sentinel. Enforced by `scripts/guard-no-localhost-fallback.mjs`.
+
 ## 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`.

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

@@ -144,11 +144,17 @@ import {
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
 
+const ownerEmail = getRequestUserEmail();
+// Never fall back to a sentinel like "local@localhost" — that pools every
+// unauthenticated write into one shared tenant (see the 2026-04-29 leak and
+// guard-no-localhost-fallback). Throw / 401 when there is no session instead.
+if (!ownerEmail) throw new Error("Not authenticated");
+
 await db.insert(schema.decks).values({
   id: nanoid(),
   title,
   data,
-  ownerEmail: getRequestUserEmail() ?? "local@localhost",
+  ownerEmail,
   orgId: getRequestOrgId(),
   // visibility defaults to 'private'
   // ...