docs: align project scaffolding references

Author: Shaw

README.md

@@ -23,33 +23,42 @@ For complete guides and API references, visit our official **[documentation](htt
 
 > **Looking for plugins?** Browse the community plugin registry at **[elizaOS-plugins/registry](https://github.com/elizaOS-plugins/registry)** for a full list of available ElizaOS plugins.
 
-## Framework vs. application
+## Framework, Projects, And App Plugins
 
-elizaOS is two things stacked together. Knowing which one you're working with makes everything else easier.
+elizaOS is a framework plus packages built on top of it. Knowing which layer
+you're working with keeps projects, plugins, and app surfaces from getting
+mixed together.
 
 **The framework** is the runtime: `@elizaos/core`, the agent loop, the plugin model (actions, providers, services, evaluators), the message/memory/state primitives, and the model-agnostic LLM layer. If you depend on `@elizaos/core` from your own code, you are using the framework.
 
-**An application** is a product *built on* the framework. [`apps/app-companion`](apps/app-companion), [`apps/app-browser`](apps/app-browser), [`apps/app-knowledge`](apps/app-knowledge), [`apps/app-phone`](apps/app-phone), and the rest of [`apps/`](apps) are first-party examples. Each is a self-contained package with its own UI, runtime plugin, data model, and deployment story. They share the framework, not the implementation.
+**A project** is a deployable product workspace built on the framework. A
+generated project owns its branded app shell, usually under `apps/app` inside
+that project workspace.
+
+**An app plugin** is a runtime plugin that also contributes an app surface inside
+Eliza. First-party app plugins live under [`plugins/app-*`](plugins), keep npm
+names like `@elizaos/app-companion`, and are loaded by package name. They are
+plugins, not top-level repo applications.
 
 The same split shows up in the directory tree:
 
 ```
-packages/        ← FRAMEWORK
+packages/        ← framework and shared packages
   core/          # @elizaos/core — runtime, types, agent loop
   agent/         # @elizaos/agent — AgentRuntime + plugin loader
   app-core/      # API + dashboard host
   elizaos/       # the `elizaos` CLI
   prompts/       # shared prompt scaffolding
   ui/            # shared React component library
-  examples/      # 30+ standalone examples (chat, discord, mcp, …)
-  benchmarks/    # 30+ evaluation suites (gaia, swe_bench, tau-bench, …)
+  examples/      # standalone examples (chat, discord, mcp, ...)
+  benchmarks/    # evaluation suites (gaia, swe_bench, tau-bench, ...)
 
-apps/            ← APPLICATIONS
+plugins/         ← runtime plugins and app plugins
   app-companion/ app-browser/ app-knowledge/ app-phone/
   app-task-coordinator/ app-training/ app-form/ ...
+  plugin-discord/ plugin-openai/ plugin-sql/ ...
 
-plugins/         ← runtime plugins (connectors + capabilities)
-templates/       ← scaffolds used by `APP create` / `PLUGIN create` flows
+templates/       ← scaffolds used by project and plugin create flows
 ```
 
 A *plugin* sits between the two: framework-shaped (registers actions/providers/services with the runtime) but shipped and consumed like a product. Community plugins are listed at [elizaOS-plugins/registry](https://github.com/elizaOS-plugins/registry).
@@ -60,26 +69,26 @@ A *plugin* sits between the two: framework-shaped (registers actions/providers/s
 |---|---|
 | Try an agent in 5 minutes | [CLI quick start](#cli-quick-start) |
 | Use the runtime from your own TypeScript code (no CLI, no UI) | [Standalone usage](#standalone-usage) |
-| Build a new agent application | [Create a new app](#create-a-new-app) |
+| Build a new deployable product | [Create a new project](#create-a-new-project) |
 | Build a runtime plugin (action / provider / service) | [Create a new plugin](#create-a-new-plugin) |
 | See how others did it | [Examples](#examples) |
 | Evaluate or benchmark an agent | [Benchmarks](#benchmarks) |
 | Read the docs | [docs.elizaos.ai](https://docs.elizaos.ai/) |
 
 ## CLI quick start
 
-**Prerequisites:** [Node.js v23+](https://nodejs.org/), [bun](https://bun.sh/docs/installation). On Windows, use [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install-manual).
+**Prerequisites:** [Node.js v24+](https://nodejs.org/), [bun](https://bun.sh/docs/installation). On Windows, use [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install-manual).
 
 ```bash
-bun install -g elizaos@alpha
-elizaos create my-first-agent        # interactive — pick `fullstack-app` for the standard path
+bun add -g elizaos
+elizaos create my-first-agent --template project
 cd my-first-agent
 # add OPENAI_API_KEY=... to .env (or your provider's key)
 bun install
 bun run dev
 ```
 
-The scaffolded `fullstack-app` exposes the runtime scripts you'll use day-to-day: `bun run dev`, `bun run build`, `bun run test`, `bun run typecheck`, `bun run lint`, `bun run verify`. The `elizaos` CLI itself is intentionally minimal — its job is scaffolding (`elizaos create`) and template upgrades (`elizaos upgrade`). For a list of available templates, run `elizaos info`.
+The generated project exposes the runtime scripts you'll use day-to-day: `bun run dev`, `bun run build`, `bun run test`, `bun run typecheck`, `bun run lint`, `bun run verify`. The `elizaos` CLI itself is intentionally minimal — its job is scaffolding (`elizaos create`) and template upgrades (`elizaos upgrade`). For a list of available templates, run `elizaos info`.
 
 Full reference: `elizaos --help` or `elizaos <command> --help`.
 
@@ -100,32 +109,34 @@ Nearly every surface has a working example in [`packages/examples/`](packages/ex
 
 > **About the partial clone.** `--filter=blob:none` gives you the full history but fetches file contents on demand — about 10× smaller. `git log`, branches, and `git checkout` work normally; `git blame` and `git log -p` will fetch on first use. To upgrade later: `git config --unset remote.origin.partialclonefilter && git fetch --refetch`. For one-off CI, `--depth=1 --single-branch` is even smaller.
 
-## Create a new app
+## Create a new project
 
-An *application* is a self-contained product on top of the runtime: UI, runtime plugin, metadata. Two paths:
+A project is a self-contained product workspace on top of the runtime: branded
+app shell, local eliza checkout, app plugin selection, platform config, and
+deployment scripts. Two paths:
 
 **1. CLI scaffold (recommended).**
 
 ```bash
-elizaos create my-app -t fullstack-app
+elizaos create my-app --template project
 cd my-app
 bun install
 bun run dev
 ```
 
-`fullstack-app` lays out a full workspace with a local eliza checkout, default plugins (`plugin-sql`, `plugin-elizacloud`, `plugin-local-ai`, `plugin-ollama`), and a Vite + React UI you can edit immediately.
+The project template lays out a full workspace with a local eliza checkout, default plugins (`plugin-sql`, `plugin-elizacloud`, `plugin-local-ai`, `plugin-ollama`), and a Vite + React UI you can edit immediately.
 
 **2. Copy a template directly.** [`templates/min-app/`](templates/min-app) is the smallest possible app — Vite + React UI, a runtime `Plugin` with one action, the `elizaos.app` metadata block in `package.json`, and a vitest smoke test. Read [`templates/min-app/SCAFFOLD.md`](templates/min-app/SCAFFOLD.md) for the placeholders to replace and the verification contract.
 
-For real-world references, browse [`apps/`](apps). A few starting points by complexity:
+For first-party app plugin references, browse [`plugins/app-*`](plugins). A few starting points by complexity:
 
-- [`app-companion`](apps/app-companion) — chat-first companion with a custom React UI.
-- [`app-browser`](apps/app-browser) — agent-driven browser automation.
-- [`app-knowledge`](apps/app-knowledge) — RAG over user documents.
-- [`app-phone`](apps/app-phone) — voice + telephony surface.
-- [`app-form`](apps/app-form) — form-driven data collection.
-- [`app-task-coordinator`](apps/app-task-coordinator) — multi-agent orchestration.
-- [`app-training`](apps/app-training) — trajectory capture + native prompt optimization.
+- [`app-companion`](plugins/app-companion) — chat-first companion with a custom React UI.
+- [`app-browser`](plugins/app-browser) — agent-driven browser automation.
+- [`app-knowledge`](plugins/app-knowledge) — RAG over user documents.
+- [`app-phone`](plugins/app-phone) — voice + telephony surface.
+- [`app-form`](plugins/app-form) — form-driven data collection.
+- [`app-task-coordinator`](plugins/app-task-coordinator) — multi-agent orchestration.
+- [`app-training`](plugins/app-training) — trajectory capture + native prompt optimization.
 
 ## Create a new plugin
 

cloud/packages/content/agents.mdx

@@ -86,14 +86,16 @@ Response:
 ### Using the CLI
 
 ```bash
-# Install the CLI
-bun add -g @elizaos/cli
+# Install the scaffolding CLI
+bun add -g elizaos
 
-# Login to elizaOS Cloud
-elizaos login
+# Create a local project
+elizaos create research-assistant --template project
+cd research-assistant
 
-# Deploy from character file
-elizaos deploy --character ./character.json
+# Run the generated project scripts
+bun install
+bun run dev
 ```
 
   </Tabs.Tab>

cloud/packages/content/installation.mdx

@@ -1,6 +1,6 @@
 ---
 title: Installation
-description: Install the elizaOS SDK and CLI tools for local development.
+description: Install the elizaOS SDK and scaffolding CLI for local development.
 ---
 
 import { Tabs, Callout, Steps } from "@/docs/components";
@@ -29,10 +29,10 @@ Install the official elizaOS packages:
 
 ## CLI Installation
 
-Install the elizaOS CLI for deployment and management:
+Install the elizaOS CLI for project and plugin scaffolding:
 
 ```bash
-bun add -g @elizaos/cli
+bun add -g elizaos
 ```
 
 Verify the installation:
@@ -45,7 +45,7 @@ elizaos --version
 
 | Requirement | Version            |
 | ----------- | ------------------ |
-| Node.js     | 18.0+              |
+| Node.js     | 24.0+              |
 | Bun         | Latest             |
 | TypeScript  | 5.0+ (recommended) |
 
@@ -55,7 +55,7 @@ elizaos --version
 ### Initialize a New Project
 
 ```bash
-elizaos init my-agent
+elizaos create my-agent --template project
 cd my-agent
 ```
 

cloud/packages/content/quickstart.mdx

@@ -250,29 +250,31 @@ print(completion['choices'][0]['message']['content'])
 
 ## Using the CLI
 
-Deploy agents from your local elizaOS project.
+Create a local elizaOS project. Cloud deployment and hosted app registration use
+the dashboard, Cloud API, or SDK endpoints documented in the app and container
+sections.
 
 <Steps>
 ### Install the CLI
 
 ```bash
-bun add -g @elizaos/cli
+bun add -g elizaos
 ```
 
-### Login to elizaOS Cloud
+### Create a Project
 
 ```bash
-elizaos login
+elizaos create my-cloud-app --template project
+cd my-cloud-app
 ```
 
-### Deploy Your Agent
+### Run Locally
 
 ```bash
-elizaos deploy --character ./character.json
+bun install
+bun run dev
 ```
 
-This uploads your character configuration and deploys it to elizaOS Cloud.
-
 </Steps>
 
 ## Environment Variables

packages/app-core/test/regression-matrix.json

@@ -264,7 +264,7 @@
       "name": "e2e-test-harness",
       "globs": [
         "test/**",
-        "eliza/apps/**/test/**",
+        "eliza/plugins/app-*/test/**",
         "eliza/packages/app-core/test/**",
         "eliza/test/vitest/integration.config.ts",
         "eliza/test/vitest/e2e.config.ts"

packages/app-core/test/scripts/test-root-unit.mjs

@@ -63,14 +63,14 @@ function collectTestFiles(...relativeRoots) {
   return files.sort();
 }
 
-function collectAppTestFiles() {
-  const appsRoot = path.join(repoRoot, "eliza", "apps");
-  if (!fs.existsSync(appsRoot)) return [];
+function collectAppPluginTestFiles() {
+  const appPluginsRoot = path.join(repoRoot, "eliza", "plugins");
+  if (!fs.existsSync(appPluginsRoot)) return [];
 
   return fs
-    .readdirSync(appsRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .flatMap((entry) => collectTestFiles(`eliza/apps/${entry.name}/test`));
+    .readdirSync(appPluginsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("app-"))
+    .flatMap((entry) => collectTestFiles(`eliza/plugins/${entry.name}/test`));
 }
 
 function chunkFiles(label, files, chunkSize = 20) {
@@ -91,7 +91,7 @@ function chunkFiles(label, files, chunkSize = 20) {
   return chunks;
 }
 
-const appTestFiles = collectAppTestFiles();
+const appTestFiles = collectAppPluginTestFiles();
 const lifeOpsSourceTestFiles = collectTestFiles("eliza/plugins/app-lifeops/src");
 const appsAndPluginsSourceTestFiles = [
   ...collectTestFiles(

packages/app/vite.config.ts

@@ -37,6 +37,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const elizaRoot = path.resolve(here, "../..");
 const nativePluginsRoot = path.join(elizaRoot, "packages/native-plugins");
 const appCoreSrcRoot = path.join(elizaRoot, "packages/app-core/src");
+const pluginSqlSrcRoot = path.join(elizaRoot, "plugins/plugin-sql/typescript");
 const appCoreNativePluginEntrypoints = path.join(
   appCoreSrcRoot,
   "platform/native-plugin-entrypoints.ts",
@@ -110,8 +111,12 @@ function createWorkspacePackageAliases(packageRoots: string[]) {
   const aliases = [];
   for (const packageRoot of packageRoots) {
     if (!fs.existsSync(packageRoot)) continue;
+    const packageRootName = path.basename(packageRoot);
     for (const entry of fs.readdirSync(packageRoot, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
+      if (packageRootName === "plugins" && !entry.name.startsWith("app-")) {
+        continue;
+      }
       const pkgPath = path.join(packageRoot, entry.name, "package.json");
       if (!fs.existsSync(pkgPath)) continue;
       const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
@@ -1487,6 +1492,21 @@ export default defineConfig({
         find: /^@elizaos\/app-core\/platform\/native-plugin-entrypoints\.js$/,
         replacement: appCoreNativePluginEntrypoints,
       },
+      // Keep plugin-sql subpath imports on the repo-local source layout. Some
+      // cached package copies still describe the old src/ layout, which makes
+      // renderer builds fail before the server-only imports can be stubbed.
+      {
+        find: /^@elizaos\/plugin-sql\/drizzle$/,
+        replacement: path.join(pluginSqlSrcRoot, "drizzle/index.ts"),
+      },
+      {
+        find: /^@elizaos\/plugin-sql\/schema$/,
+        replacement: path.join(pluginSqlSrcRoot, "schema/index.ts"),
+      },
+      {
+        find: /^@elizaos\/plugin-sql\/types$/,
+        replacement: path.join(pluginSqlSrcRoot, "types.ts"),
+      },
       // Node built-in subpaths that browser polyfills don't provide.
       // Server-only code imports these but they're never executed in-browser.
       ...["util/types", "stream/promises", "stream/web"].flatMap((sub) => [
@@ -1556,12 +1576,8 @@ export default defineConfig({
         find: /^@elizaos\/ui\/lib\/(.*)$/,
         replacement: `${uiPkgRoot}/src/lib/$1.ts`,
       },
-      // Dynamic aliases for local app packages. Older checkouts used
-      // eliza/apps/*; current workspaces use plugins/app-*.
-      ...createWorkspacePackageAliases([
-        path.resolve(elizaRoot, "apps"),
-        path.resolve(elizaRoot, "plugins"),
-      ]),
+      // Dynamic aliases for local app plugin packages.
+      ...createWorkspacePackageAliases([path.resolve(elizaRoot, "plugins")]),
       ...(() => {
         const sharedPkgPath = path.resolve(
           elizaRoot,