@agent-native/core 0.63.4 → 0.64.0

package/README.md

@@ -1,33 +1,8 @@
 # Agent-Native
 
-### Open-source framework for agentic applications you own.
-
-Don't choose between rich user interfaces and autonomous agents. Every Agent-Native app is both.
-
-## Agents and UIs — Fully Connected
-
-The agent and the UI are equal citizens of the same system. Every action works both ways — click it or ask for it.
-
-![Agents and UIs fully connected](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fadc1e9e9368e4a8cb1b4dbb5aae5aaa2)
-
-- **Everything syncs** — Agent and UI share one database and one state. Changes from either side show up instantly on the other.
-- **Real-time multiplayer** — Humans and agents collaborate in the same document simultaneously: CRDT merging, live presence (cursors, selection rings, who's on which slide), and the agent as a first-class peer editor. Works on any SQL database and any host, including serverless.
-- **Context-aware** — The agent knows what you're looking at. Select text, hit Cmd+I, and tell it what to do.
-- **Per-user workspace** — Skills, memory, instructions, sub-agents, and MCP servers — SQL-backed, customizable per user. Claude-Code-level flexibility, SaaS-grade economics.
-- **Agents call agents** — Tag another agent from any app. They discover each other over A2A and take action across your stack.
-- **Reusable integrations** — Connect a provider once in Dispatch, keep secret values in the vault, then grant apps like Brain, Analytics, Mail, and Dispatch access to the shared account metadata and credential refs.
-- **Three shapes** — Build the same agent as a headless API, a rich chat experience, or a full application where agent and UI stay in sync.
-- **Apps that improve themselves** — Your apps get better on their own. The agent can add features, fix bugs, and refine the UI over time.
-- **Any database, any host** — Any SQL database Drizzle supports. Any hosting target Nitro supports. No lock-in.
-- **Bring the agent surface you need** — MCP-compatible hosts can call your apps, coding agents can install skills, native chat renders reusable app outputs, and BYO agent runtimes can stream into the Agent-Native chat shell.
-
 ## The framework for agent-native apps
 
-Agent-Native is an open-source framework for building robust agents that can act inside real apps, not just chat next to them.
-
-It gives you primitives for product-grade agentic software: shared actions, SQL-backed state, identity, tools, skills, jobs, observability, and UI surfaces that all work together.
-
-Backend agnostic: bring your own database, hosting provider, model stack, and app code.
+Agent-Native is an open-source framework for building robust agents that act inside real apps, not just chat next to them. It gives you primitives for product-grade agentic software: shared actions, SQL-backed state, identity, tools, skills, jobs, observability, and UI surfaces that all work together. Bring your own database, hosting provider, model stack, and app code.
 
 ```ts
 // One action powers UI, agent, HTTP, MCP, A2A, and CLI.
@@ -42,44 +17,25 @@ export default defineAction({
 });
 ```
 
-- **Actions** — Define work once. Use it from UI, agent, API, MCP, A2A, and CLI.
-- **Agent runtime** — Chat, tools, skills, memory, jobs, observability, and handoffs ship together.
-- **Backend agnostic** — Plug in any Drizzle-supported SQL database and Nitro-compatible host.
-
-## One agent, three product shapes
+- **Actions**: Define work once. Use it from UI, agent, API, MCP, A2A, and CLI.
+- **Agent runtime**: Chat, tools, skills, memory, jobs, observability, and handoffs ship together.
+- **Backend agnostic**: Plug in any Drizzle-supported SQL database and Nitro-compatible host.
 
-Agent-Native primitives let you choose how much UI to put around an agent without rebuilding the agent contract:
-
-| Shape         | What you ship                                                                                             | Same primitives underneath                                                  |
-| ------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| **Headless**  | Call the agent and actions from code, CLI, HTTP, MCP, or A2A.                                             | `defineAction`, auth, skills, memory, jobs, observability                   |
-| **Rich chat** | A standalone or embedded chat with native tables, charts, approvals, setup flows, and tool results.       | Shared chat runtime, BYO runtime adapters, action-declared native renderers |
-| **Whole app** | A full SaaS/product UI where chat can start central, move to the sidebar, and stay synced with app state. | SQL state, actions, context awareness, deep links, live sync                |
-
-Protocols come with the framework instead of becoming separate integrations per feature. Today that means A2A, MCP, MCP Apps, standard remote MCP OAuth, MCP clients, HTTP/CLI action calls, native chat widgets, `AgentChatRuntime` adapters, standard OpenAI, AG-UI, Claude Agent SDK, and Vercel AI SDK chat runtime connectors, and deep links all hang off the same action surface. ACP is best understood as the coding-agent/editor interoperability protocol, not the general BYO app-chat runtime.
-
-For the full decision guide — headless, rich chat on the built-in agent, rich chat on your own agent, embedded sidecar, or full app — see [Agent Surfaces](https://agent-native.com/docs/agent-surfaces).
-
-To connect Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP host to your hosted app, see the [External Agents guide](https://agent-native.com/docs/external-agents).
-
-## Try it with a skill
-
-Don't want to scaffold a whole app yet? Add visual planning and PR recaps to Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, and similar agents with one command:
-
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
+## Agents and UIs, Fully Connected
 
-You get two slash commands that upgrade how your agent plans and reports its work:
+The agent and the UI are equal citizens of one system. Every action works both ways: click it or ask for it.
 
-- **`/visual-plan`** — before the agent writes code, it opens a structured, reviewable plan document instead of a wall of text: inline diagrams, UI wireframes and prototypes, file-by-file implementation maps, and annotations you can comment on and approve.
-- **`/visual-recap`** — after changes land, it turns a PR or git diff into a high-altitude visual recap: schema, API, and file changes rendered as grounded before/after blocks with a shareable review link, instead of scrolling a raw diff.
+![Agents and UIs fully connected](https://cdn.builder.io/api/v1/file/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fadc1e9e9368e4a8cb1b4dbb5aae5aaa2)
 
-See the **[Skills Guide](https://agent-native.com/docs/skills-guide#app-backed-skills)** for more skills and local installs.
+- **Everything syncs**: One database, one state. Changes from either side show up instantly on the other.
+- **Real-time multiplayer**: Humans and agents edit the same document together, with the agent as a first-class peer.
+- **Context-aware**: The agent knows what you're looking at. Select text, hit Cmd+I, and tell it what to do.
+- **Agents call agents**: Tag another agent from any app and they coordinate over A2A.
+- **Self-improving**: The agent can add features, fix bugs, and refine the UI over time.
 
 ## Templates
 
-Start with a full featured template. Each one is a complete, 100% free and open-source SaaS app — cloneable, not scaffolded — except you own the code and can customize everything.
+Start with a full featured template. Each one is a complete, 100% free and open-source SaaS app: cloneable, not scaffolded, except you own the code and can customize everything.
 
 <table>
 <tr>
@@ -113,7 +69,7 @@ Edit local Markdown/MDX files, generate rich interactive custom blocks, and draf
 
 **Visual plan mode for coding agents**
 
-Install `/visual-plan` and `/visual-recap` so your coding agent can plan before it builds and recap changes after they land — high-level code reviews with diagrams, wireframes, annotations, and review links.
+Install `/visual-plan` and `/visual-recap` so your coding agent can plan before it builds and recap changes after they land. High-level code reviews with diagrams, wireframes, annotations, and review links.
 
 </td>
 </tr>
@@ -137,7 +93,7 @@ Generate and edit React-based presentations via prompt or point-and-click.
 
 **Agent-Native Amplitude, Mixpanel**
 
-Connect analytics data sources, prompt for real charts, and build reusable dashboards. Shared workspace connections can provide provider credentials, while Analytics still owns metrics, source-of-truth choices, and saved analyses.
+Connect analytics data sources, prompt for real charts, and build reusable dashboards.
 
 </td>
 <td width="33%" align="center" valign="top">
@@ -154,62 +110,43 @@ Record your screen with auto-transcripts, shareable links, and an agent that sum
 </tr>
 </table>
 
-Every template is a complete cloneable SaaS — fork it, customize it with the agent, own it. Try them with example data before connecting your own sources.
-
 View the full template gallery at **[agent-native.com/templates](https://agent-native.com/templates)**.
 
-## Quick Start
+## Try it with a skill
 
-One command to fork a template and start building locally.
+Don't want to scaffold a whole app yet? Add visual planning and PR recaps to Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, and similar agents with one command:
 
 ```bash
-npx @agent-native/core@latest create my-platform
-cd my-platform
-pnpm install
-pnpm dev
+npx @agent-native/core@latest skills add visual-plan
 ```
 
-The CLI shows a multi-select picker so you can include as many templates as you want in one workspace. Pick Mail + Calendar + Forms and you get all three apps wired up and sharing auth in one go. Or browse the **[template gallery](https://agent-native.com/templates)** for live demos.
+![Visual plan and recap in action](https://raw.githubusercontent.com/builderio/skills/main/media/visual-recap.gif)
 
-Want a single app, no monorepo? Use `--standalone`:
+You get two slash commands:
 
-```bash
-npx @agent-native/core@latest create my-app --standalone --template mail
-```
-
-## Workspaces (Monorepo)
+- **`/visual-plan`**: before the agent writes code, it opens a structured, reviewable plan with inline diagrams, UI wireframes, file-by-file implementation maps, and annotations you can comment on and approve.
+- **`/visual-recap`**: after changes land, it turns a PR or git diff into a high-altitude visual recap with a shareable review link instead of a raw diff.
 
-A workspace is the default shape of an agent-native project. Every app sits under `apps/`, and `packages/shared/` is available for the small amount of code, instructions, skills, or branding that should truly apply to every app.
+See the **[Skills Guide](https://agent-native.com/docs/skills-guide#app-backed-skills)** for more.
 
-```
-my-platform/
-├── package.json                   # declares `agent-native.workspaceCore`
-├── pnpm-workspace.yaml
-├── .env                           # shared secrets: ANTHROPIC_API_KEY, BUILDER_PRIVATE_KEY, A2A_SECRET, ...
-├── packages/
-│   └── shared/                    # optional shared custom code
-└── apps/
-    ├── mail/
-    ├── calendar/
-    └── forms/
-```
+## Quick Start
 
-Add another app later:
+One command to start a new project locally.
 
 ```bash
-npx @agent-native/core@latest add-app notes --template content
+npx @agent-native/core@latest create my-app
+cd my-app
+pnpm install
+pnpm dev
 ```
 
-Deploy every app behind one origin:
+`create` first asks how you want to start:
 
-```bash
-npx @agent-native/core@latest deploy
-# https://your-agents.com/mail/*       → mail
-# https://your-agents.com/calendar/*   → calendar
-# https://your-agents.com/forms/*      → forms
-```
+- **Full template(s)**: clone one or more complete apps into a workspace. Pick Mail + Calendar + Forms and you get all three wired up and sharing auth.
+- **Chat**: a single app with a minimal chat UI and the browser shell already wired, the simplest way to get a UI.
+- **Headless**: a single action-first app with no UI shell. The CLI walks you through calling your first action and agent, and you can add a UI later.
 
-Same-origin deploy means a **shared login session** across every app and **zero-config cross-app A2A** — tag `@mail` from the calendar's agent chat and it just works (no JWT signing, no CORS). Full details at **[agent-native.com/docs/multi-app-workspace](https://agent-native.com/docs/multi-app-workspace)**.
+Prefer flags? `create my-app --template mail`, `--headless`, or `--standalone` skip the prompt.
 
 ## The Best of Both Worlds
 

package/dist/cli/create-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-workspace.d.ts","sourceRoot":"","sources":["../../src/cli/create-workspace.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CACnC,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"create-workspace.d.ts","sourceRoot":"","sources":["../../src/cli/create-workspace.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,eAAe,CACnC,IAAI,GAAE,sBAA2B,GAChC,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/cli/create-workspace.js

@@ -12,6 +12,9 @@ export async function createWorkspace(opts = {}) {
     const passthrough = {
         template: opts.template,
         noInstall: opts.noInstall,
+        // Preserve the alias's contract: always scaffold a workspace, never the
+        // new start-shape prompt that could route to a standalone app.
+        forceWorkspace: true,
     };
     await createApp(opts.name, passthrough);
 }

package/dist/cli/create-workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-workspace.js","sourceRoot":"","sources":["../../src/cli/create-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAyB,MAAM,aAAa,CAAC;AAS/D,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B,EAAE;IAEjC,MAAM,WAAW,GAAqB;QACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["/**\n * @deprecated `create-workspace` is now an alias for `create`. In current\n * versions, `agent-native create <name>` defaults to scaffolding a workspace\n * with a multi-select template picker. Use `--standalone` for a single-app\n * standalone scaffold.\n *\n * This module is kept for backwards compatibility with older docs and\n * scripts that still invoke `agent-native create-workspace`.\n */\nimport { createApp, type CreateAppOptions } from \"./create.js\";\n\nexport interface CreateWorkspaceOptions {\n  name?: string;\n  /** Pre-select these templates in the picker. */\n  template?: string;\n  noInstall?: boolean;\n}\n\nexport async function createWorkspace(\n  opts: CreateWorkspaceOptions = {},\n): Promise<void> {\n  const passthrough: CreateAppOptions = {\n    template: opts.template,\n    noInstall: opts.noInstall,\n  };\n  await createApp(opts.name, passthrough);\n}\n"]}
+{"version":3,"file":"create-workspace.js","sourceRoot":"","sources":["../../src/cli/create-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAyB,MAAM,aAAa,CAAC;AAS/D,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAA+B,EAAE;IAEjC,MAAM,WAAW,GAAqB;QACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,wEAAwE;QACxE,+DAA+D;QAC/D,cAAc,EAAE,IAAI;KACrB,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1C,CAAC","sourcesContent":["/**\n * @deprecated `create-workspace` is now an alias for `create`. In current\n * versions, `agent-native create <name>` defaults to scaffolding a workspace\n * with a multi-select template picker. Use `--standalone` for a single-app\n * standalone scaffold.\n *\n * This module is kept for backwards compatibility with older docs and\n * scripts that still invoke `agent-native create-workspace`.\n */\nimport { createApp, type CreateAppOptions } from \"./create.js\";\n\nexport interface CreateWorkspaceOptions {\n  name?: string;\n  /** Pre-select these templates in the picker. */\n  template?: string;\n  noInstall?: boolean;\n}\n\nexport async function createWorkspace(\n  opts: CreateWorkspaceOptions = {},\n): Promise<void> {\n  const passthrough: CreateAppOptions = {\n    template: opts.template,\n    noInstall: opts.noInstall,\n    // Preserve the alias's contract: always scaffold a workspace, never the\n    // new start-shape prompt that could route to a standalone app.\n    forceWorkspace: true,\n  };\n  await createApp(opts.name, passthrough);\n}\n"]}

package/dist/cli/create.d.ts

@@ -15,6 +15,12 @@ export interface CreateAppOptions {
     standalone?: boolean;
     /** Internal: skip pnpm install at the end (for tests). */
     noInstall?: boolean;
+    /**
+     * Internal: always scaffold a workspace and skip the start-shape prompt.
+     * Used by the deprecated `create-workspace` alias, whose contract is an
+     * unconditional workspace scaffold.
+     */
+    forceWorkspace?: boolean;
 }
 /**
  * Main entry for `agent-native create [name]`.

package/dist/cli/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AA4BvE;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AA6BD,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAmCf;AAgLD,iBAAS,oCAAoC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAa1E;AAiBD,iBAAe,qBAAqB,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAiDD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAmLD;;;;;GAKG;AACH,iBAAe,mBAAmB,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAoDD;;;;GAIG;AACH,iBAAe,wBAAwB,CACrC,aAAa,EAAE,MAAM,EAAE,EACvB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC,CA2Ef;AAED;;;GAGG;AACH,iBAAS,qBAAqB,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAoGN;AA2HD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GACf;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkB7D;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B,yCAAyC;AACzC,OAAO,EACL,qBAAqB,IAAI,sBAAsB,EAC/C,mBAAmB,IAAI,oBAAoB,EAC3C,wBAAwB,IAAI,yBAAyB,EACrD,qBAAqB,IAAI,sBAAsB,EAC/C,WAAW,IAAI,YAAY,EAC3B,kBAAkB,IAAI,mBAAmB,EACzC,eAAe,IAAI,gBAAgB,EACnC,kBAAkB,IAAI,mBAAmB,EACzC,wBAAwB,IAAI,yBAAyB,EACrD,4BAA4B,IAAI,6BAA6B,EAC7D,oBAAoB,IAAI,qBAAqB,EAC7C,8BAA8B,IAAI,+BAA+B,EACjE,oCAAoC,IAAI,qCAAqC,EAC7E,uBAAuB,IAAI,wBAAwB,EACnD,cAAc,IAAI,eAAe,GAClC,CAAC;AAcF,iBAAS,cAAc,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,MAAM,EAAE,CAQV;AA8GD;;;;;GAKG;AACH,iBAAS,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+B7C;AAiCD,iBAAS,kBAAkB,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAsBN;AAyBD,iBAAS,wBAAwB,IAAI,MAAM,CAW1C;AAED,iBAAS,4BAA4B,IAAI,MAAM,CAO9C;AAcD;;;;;;;;;;;GAWG;AACH,iBAAS,8BAA8B,IAAI,MAAM,EAAE,CASlD;AAED;;qDAEqD;AACrD,iBAAS,oBAAoB,IAAI,MAAM,CAEtC;AAoID,iBAAS,kBAAkB,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,GAAG,WAAW,GAC/B,IAAI,CA8CN;AAoFD,iBAAS,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAyED,iBAAS,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CA+BxE"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/cli/create.ts"],"names":[],"mappings":"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"}

package/dist/cli/create.js

@@ -65,6 +65,11 @@ const HEADLESS_OPTION = {
  */
 export async function createApp(name, opts) {
     const clack = await import("@clack/prompts");
+    // Reject an invalid provided name before any interactive prompt so bad input
+    // fails fast instead of blocking on the start-shape picker below.
+    if (name !== undefined) {
+        assertValidProjectName(name, clack);
+    }
     // If we're already inside a workspace, the meaning of `create <name>` is
     // "add a new app to this workspace". Delegate to add-app.
     const workspace = detectWorkspace(process.cwd());
@@ -82,17 +87,94 @@ export async function createApp(name, opts) {
     // Use `--template a,b` or pass no --template to opt into the workspace
     // flow with the multi-select picker.
     const parsed = parseTemplateList(opts?.template);
-    if (parsed.includes("headless") && parsed.length > 1) {
+    // Headless can't live in a workspace, so reject it when more than one
+    // template is requested or when workspace semantics are forced.
+    if (parsed.includes("headless") &&
+        (parsed.length > 1 || opts?.forceWorkspace)) {
         clack.cancel("The headless scaffold is standalone-only. Use `agent-native create my-app --headless`, or use the Chat template when adding a UI app to a workspace.");
         process.exit(1);
     }
-    if (parsed.length === 1) {
+    // A single explicit template scaffolds a standalone app, unless the caller
+    // forces workspace semantics (the deprecated `create-workspace` alias), in
+    // which case the template is preselected in the workspace picker below.
+    if (parsed.length === 1 && !opts?.forceWorkspace) {
         await createStandaloneApp(name, opts, clack);
         return;
     }
-    // Default: create a workspace.
+    // No template specified: ask what shape to start from before diving into
+    // "which templates?". The on-ramp choice implies the project structure, so
+    // we don't ask a separate "workspace or standalone?" question — Chat and
+    // Headless scaffold a single standalone app (the lightest starts; headless
+    // cannot live in a workspace), while Template continues into the workspace
+    // multi-select.
+    if (parsed.length === 0) {
+        // The deprecated `create-workspace` alias forces workspace semantics, so
+        // it must skip the start-shape prompt and scaffold a workspace directly.
+        if (opts?.forceWorkspace) {
+            await createWorkspaceInteractive(name, opts, clack);
+            return;
+        }
+        const shape = await promptStartShape(clack);
+        if (shape === "headless" || shape === "chat") {
+            await createStandaloneApp(name, { ...opts, template: shape }, clack);
+            return;
+        }
+        // shape === "template" → full app(s) in a workspace.
+        await createWorkspaceInteractive(name, opts, clack);
+        return;
+    }
+    // Multiple explicit templates: create a workspace with them.
     await createWorkspaceInteractive(name, opts, clack);
 }
+/**
+ * Top-level on-ramp shown by the bare `create <name>` command (no flags). The
+ * choice made here implies the project structure, so we deliberately avoid a
+ * separate "workspace or standalone?" question:
+ *   - "template" → full app(s) in a workspace (the multi-select picker)
+ *   - "chat"     → a single standalone chat UI app
+ *   - "headless" → a single standalone action-first app with no UI shell
+ * Chat and headless are standalone on purpose: a monorepo is unnecessary
+ * ceremony for the lightest on-ramps, and headless cannot be a workspace
+ * member. Either can grow into a workspace later via `add-app`.
+ */
+async function promptStartShape(clack) {
+    const choice = await clack.select({
+        message: "How do you want to start?",
+        options: [
+            {
+                value: "template",
+                label: "Full template(s)",
+                hint: "Clone complete apps (Mail, Calendar, Slides, ...) into a workspace",
+            },
+            {
+                value: "chat",
+                label: "Chat",
+                hint: "A single app with a minimal chat UI and the browser shell wired up",
+            },
+            {
+                value: "headless",
+                label: "Headless",
+                hint: "A single action-first app with one primitive and no UI shell",
+            },
+        ],
+    });
+    if (clack.isCancel(choice)) {
+        clack.cancel("Cancelled.");
+        process.exit(0);
+    }
+    return choice;
+}
+/**
+ * Validate a project name supplied on the command line. Mirrors the rule in
+ * `promptNameIfMissing` so an invalid name is rejected before any interactive
+ * prompt runs (the sub-flows re-validate, which is a harmless no-op).
+ */
+function assertValidProjectName(name, clack) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        clack.cancel(`Invalid name "${name}". Use lowercase letters, numbers, and hyphens (must start with a letter).`);
+        process.exit(1);
+    }
+}
 /* ─────────────────────────────────────────────────────────────────────────
  * Workspace creation (new default)
  * ───────────────────────────────────────────────────────────────────────── */