LinuxDevil · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026 · Oct 1, 2026
diff --git a/.fallowrc.json b/.fallowrc.json
@@ -1,7 +1,7 @@
 {
   "$schema": "./node_modules/fallow/schema.json",
   "entry": [
-    "src/cli/{dev,build,studio,mcp,doctor}.ts",
+    "src/cli/{dev,build,studio,mcp,doctor,init}.ts",
     "src/data/index.ts",
     "**/*.test-d.ts",
     "**/*.{test,spec}.{ts,tsx}",

diff --git a/README.md b/README.md
@@ -105,6 +105,15 @@ const result = await resumeAfterApproval(
 
 ## Quickstart
 
+**Start a new project** with one command: it scaffolds an agent, an example tool and an offline test, installs dependencies and runs `git init`:
+
+```bash
+npx loushy init my-agent        # or: npm create loushy-agent my-agent
+cd my-agent && npm run dev      # set your API key in .env first; `npm test` runs offline
+```
+
+See [Quick Start](docs/quick-start.md#start-a-new-project) for the flags (`--provider`, `--template`, `--yes`, ...). Or add the SDK to an existing project by hand:
+
 **1. Install**
 
 ```bash
@@ -546,9 +555,9 @@ const result = renderTemplate(template, { name: 'Alice', count: 5 });
 ## CLI
 
 ```bash
-npx create-loushy-agent --name=my-agent --provider=openai --yes  # scaffold a project
-npx loushy dev agent.yaml                                        # local chat UI + hot reload
-npx loushy build --target=node-server --agent=agent.yaml         # or docker / cloudflare-worker
+npx loushy init my-agent                                  # scaffold a project (or: npm create loushy-agent my-agent)
+npx loushy dev agent.yaml                                 # local chat UI + hot reload
+npx loushy build --target=node-server --agent=agent.yaml  # or docker / cloudflare-worker
 ```
 
 See [Installation](docs/installation.md) and [Deployment](docs/deployment.md)

diff --git a/bin/loushy.js b/bin/loushy.js
@@ -5,6 +5,7 @@ const path = require('node:path');
 
 const USAGE = [
   'Usage:',
+  '  loushy init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]',
   '  loushy dev <config.yaml|config.json> [--port N] [--host H]',
   '  loushy build --target=<name> --agent=<path> [--out=<dir>]',
   '  loushy studio [--port N] [--host H] [--prod|--dev]',
@@ -79,6 +80,12 @@ async function runStudio(rest) {
   }
 }
 
+// Scaffolds a new project (LOU-D3); see src/cli/init.ts. Also what `npm create loushy-agent` runs.
+async function runInitCommand(rest) {
+  const { runInit } = require(path.join(__dirname, '..', 'dist', 'cli', 'init.js'));
+  process.exitCode = await runInit(rest);
+}
+
 async function runDoctorCommand(rest) {
   const { runDoctorCommand: run } = require(path.join(__dirname, '..', 'dist', 'cli', 'doctor.js'));
   process.exitCode = await run(rest);
@@ -92,6 +99,7 @@ async function runMcp(rest) {
 }
 
 const COMMANDS = new Map([
+  ['init', runInitCommand],
   ['dev', runDev],
   ['build', runBuildCommand],
   ['studio', runStudio],

diff --git a/docs/installation.md b/docs/installation.md
@@ -61,7 +61,7 @@ feature needs them: `undici` (the built-in `http` tool), `dockerode`
 
 To try an unreleased version, build and pack the SDK from a checkout of this
 repository, then install the tarball into your project - the same approach
-`create-loushy-agent` uses for the projects it generates:
+`loushy init --sdk-path` uses for the projects it generates:
 
 ```bash
 # in the SDK checkout
@@ -75,21 +75,36 @@ npm install ./loushy-build-ai-agent-<version>.tgz ai zod
 
 ## Scaffolding a new project
 
-`packages/create-loushy-agent` in this repository scaffolds a ready-to-build
-project (`package.json`, `tsconfig.json`, `src/agent.ts` calling
-`createAgent()`, and a `.env.example` naming your provider's credential
-variable):
+`loushy init` creates a ready-to-run project: `package.json` (ESM, depending
+on this SDK by version range), a strict `tsconfig.json`, `src/agent.ts` calling
+`createAgent({ model, instructions })` with an example `defineTool()` tool, an
+offline `src/agent.test.ts` using `mockModel`, a `.env.example` naming your
+provider's key variable, `.gitignore` and a README. It then installs the
+dependencies and runs `git init`.
 
 ```bash
-# from a checkout of this repository
-cd packages/create-loushy-agent && npm install && npm run build && cd ../..
-node packages/create-loushy-agent/bin/cli.js --name=my-agent --provider=openai --yes
+npx loushy init my-agent                 # or: npm create loushy-agent my-agent
+npx loushy init my-agent --yes --provider anthropic --template tools --no-install
 ```
 
+| Flag | Meaning |
+| ---- | ------- |
+| `--provider openai\|anthropic\|openrouter\|ollama` | Default: the provider whose API key variable is set, else `openai`. |
+| `--template minimal\|tools\|yaml` | `minimal` (one tool), `tools` (three tools) or `yaml` (an `agent.yaml` spec run by `loushy dev`). Default `minimal`. |
+| `--package-manager npm\|pnpm\|yarn\|bun` | Default: the one that launched the command (`npm_config_user_agent`), else `npm`. |
+| `--yes`, `-y` | Never prompt; use defaults for anything not given. Prompts only appear on a terminal. |
+| `--no-install`, `--no-git` | Skip installing dependencies / `git init`. |
+| `--force` | Write into a directory that is not empty (otherwise `init` refuses). |
+| `--sdk-path <dir\|tarball>` | For SDK development: depend on a checkout (it is `npm pack`ed) or a packed `.tgz` instead of the published version. Also read from `LOUSHY_SDK_PATH`. |
+
+`create-loushy-agent` (`packages/create-loushy-agent`) is a thin wrapper that
+runs `loushy init` with the same arguments.
+
 ## The `loushy` CLI
 
 Installing the package also installs the `loushy` command:
 
+- `loushy init [dir]` - scaffold a new project (see above).
 - `loushy dev <spec.yaml|spec.json>` - local dev server with a chat UI and hot
   reload (see [Configuration](./configuration.md)).
 - `loushy build --target=<target> --agent=<spec>` - build a deployable

diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -7,7 +7,32 @@ with the real API. All of them run as-is with the SDK's built-in mock
 provider - no API key needed - except the first, which talks to a real model
 and is therefore only type-checked.
 
-Install first (see [Installation](./installation.md)):
+## Start a new project
+
+The fastest way in is one command, which creates a runnable project (an
+agent, an example tool, an offline test, a `.env.example` for your provider),
+installs its dependencies and runs `git init`:
+
+```bash
+npx loushy init my-agent
+cd my-agent
+cp .env.example .env     # put your API key in .env
+npm run dev              # chat with your agent in the terminal
+npm test                 # offline tests: no API key needed
+```
+
+`npm create loushy-agent my-agent` is equivalent, and so is
+`npx @loushy/build-ai-agent init my-agent` when the SDK is not installed yet
+(a bare `npx loushy` only finds the `loushy` command once the SDK is in your
+`node_modules`). Without arguments, `init` asks for the directory, provider and
+template; for scripts pass `--yes` (defaults: the `minimal` template and the
+provider whose API key variable is set, else OpenAI). Useful flags:
+`--provider openai|anthropic|openrouter|ollama`, `--template minimal|tools|yaml`,
+`--package-manager npm|pnpm|yarn|bun`, `--no-install`, `--no-git`, `--force`
+(write into a non-empty directory). `loushy init --help` lists them all.
+
+Prefer to add the SDK to an existing project? Install it by hand (see
+[Installation](./installation.md)):
 
 ```bash
 npm install @loushy/build-ai-agent ai zod

diff --git a/llms-full.txt b/llms-full.txt
@@ -103,6 +103,15 @@ const result = await resumeAfterApproval(
 
 ## Quickstart
 
+**Start a new project** with one command: it scaffolds an agent, an example tool and an offline test, installs dependencies and runs `git init`:
+
+```bash
+npx loushy init my-agent        # or: npm create loushy-agent my-agent
+cd my-agent && npm run dev      # set your API key in .env first; `npm test` runs offline
+```
+
+See [Quick Start](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/quick-start.md#start-a-new-project) for the flags (`--provider`, `--template`, `--yes`, ...). Or add the SDK to an existing project by hand:
+
 **1. Install**
 
 ```bash
@@ -544,9 +553,9 @@ const result = renderTemplate(template, { name: 'Alice', count: 5 });
 ## CLI
 
 ```bash
-npx create-loushy-agent --name=my-agent --provider=openai --yes  # scaffold a project
-npx loushy dev agent.yaml                                        # local chat UI + hot reload
-npx loushy build --target=node-server --agent=agent.yaml         # or docker / cloudflare-worker
+npx loushy init my-agent                                  # scaffold a project (or: npm create loushy-agent my-agent)
+npx loushy dev agent.yaml                                 # local chat UI + hot reload
+npx loushy build --target=node-server --agent=agent.yaml  # or docker / cloudflare-worker
 ```
 
 See [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md) and [Deployment](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/deployment.md)
@@ -755,7 +764,7 @@ feature needs them: `undici` (the built-in `http` tool), `dockerode`
 
 To try an unreleased version, build and pack the SDK from a checkout of this
 repository, then install the tarball into your project - the same approach
-`create-loushy-agent` uses for the projects it generates:
+`loushy init --sdk-path` uses for the projects it generates:
 
 ```bash
 # in the SDK checkout
@@ -769,21 +778,36 @@ npm install ./loushy-build-ai-agent-<version>.tgz ai zod
 
 ## Scaffolding a new project
 
-`packages/create-loushy-agent` in this repository scaffolds a ready-to-build
-project (`package.json`, `tsconfig.json`, `src/agent.ts` calling
-`createAgent()`, and a `.env.example` naming your provider's credential
-variable):
+`loushy init` creates a ready-to-run project: `package.json` (ESM, depending
+on this SDK by version range), a strict `tsconfig.json`, `src/agent.ts` calling
+`createAgent({ model, instructions })` with an example `defineTool()` tool, an
+offline `src/agent.test.ts` using `mockModel`, a `.env.example` naming your
+provider's key variable, `.gitignore` and a README. It then installs the
+dependencies and runs `git init`.
 
 ```bash
-# from a checkout of this repository
-cd packages/create-loushy-agent && npm install && npm run build && cd ../..
-node packages/create-loushy-agent/bin/cli.js --name=my-agent --provider=openai --yes
+npx loushy init my-agent                 # or: npm create loushy-agent my-agent
+npx loushy init my-agent --yes --provider anthropic --template tools --no-install
 ```
 
+| Flag | Meaning |
+| ---- | ------- |
+| `--provider openai\|anthropic\|openrouter\|ollama` | Default: the provider whose API key variable is set, else `openai`. |
+| `--template minimal\|tools\|yaml` | `minimal` (one tool), `tools` (three tools) or `yaml` (an `agent.yaml` spec run by `loushy dev`). Default `minimal`. |
+| `--package-manager npm\|pnpm\|yarn\|bun` | Default: the one that launched the command (`npm_config_user_agent`), else `npm`. |
+| `--yes`, `-y` | Never prompt; use defaults for anything not given. Prompts only appear on a terminal. |
+| `--no-install`, `--no-git` | Skip installing dependencies / `git init`. |
+| `--force` | Write into a directory that is not empty (otherwise `init` refuses). |
+| `--sdk-path <dir\|tarball>` | For SDK development: depend on a checkout (it is `npm pack`ed) or a packed `.tgz` instead of the published version. Also read from `LOUSHY_SDK_PATH`. |
+
+`create-loushy-agent` (`packages/create-loushy-agent`) is a thin wrapper that
+runs `loushy init` with the same arguments.
+
 ## The `loushy` CLI
 
 Installing the package also installs the `loushy` command:
 
+- `loushy init [dir]` - scaffold a new project (see above).
 - `loushy dev <spec.yaml|spec.json>` - local dev server with a chat UI and hot
   reload (see [Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md)).
 - `loushy build --target=<target> --agent=<spec>` - build a deployable
@@ -851,7 +875,32 @@ with the real API. All of them run as-is with the SDK's built-in mock
 provider - no API key needed - except the first, which talks to a real model
 and is therefore only type-checked.
 
-Install first (see [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md)):
+## Start a new project
+
+The fastest way in is one command, which creates a runnable project (an
+agent, an example tool, an offline test, a `.env.example` for your provider),
+installs its dependencies and runs `git init`:
+
+```bash
+npx loushy init my-agent
+cd my-agent
+cp .env.example .env     # put your API key in .env
+npm run dev              # chat with your agent in the terminal
+npm test                 # offline tests: no API key needed
+```
+
+`npm create loushy-agent my-agent` is equivalent, and so is
+`npx @loushy/build-ai-agent init my-agent` when the SDK is not installed yet
+(a bare `npx loushy` only finds the `loushy` command once the SDK is in your
+`node_modules`). Without arguments, `init` asks for the directory, provider and
+template; for scripts pass `--yes` (defaults: the `minimal` template and the
+provider whose API key variable is set, else OpenAI). Useful flags:
+`--provider openai|anthropic|openrouter|ollama`, `--template minimal|tools|yaml`,
+`--package-manager npm|pnpm|yarn|bun`, `--no-install`, `--no-git`, `--force`
+(write into a non-empty directory). `loushy init --help` lists them all.
+
+Prefer to add the SDK to an existing project? Install it by hand (see
+[Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md)):
 
 ```bash
 npm install @loushy/build-ai-agent ai zod

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -173,6 +173,7 @@
     "@modelcontextprotocol/sdk": "^1.30.1",
     "dockerode": "^5.0.1",
     "nanoid": "^5.0.7",
+    "prompts": "^2.4.2",
     "undici": "^8.11.2",
     "yaml": "^2.9.1"
   },
@@ -183,6 +184,7 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/dockerode": "^4.0.1",
     "@types/node": "^20",
+    "@types/prompts": "^2.4.9",
     "@vitest/coverage-v8": "^1.0.0",
     "esbuild": "^0.25.12",
     "eslint": "^10.11.0",

diff --git a/packages/create-loushy-agent/package.json b/packages/create-loushy-agent/package.json
@@ -1,27 +1,25 @@
 {
   "name": "create-loushy-agent",
   "version": "0.1.0",
-  "description": "Scaffold a new @loushy/build-ai-agent project",
+  "description": "npm create loushy-agent: scaffold a new @loushy/build-ai-agent project (runs `loushy init`)",
   "type": "commonjs",
   "bin": {
     "create-loushy-agent": "bin/cli.js"
   },
   "files": [
     "dist",
-    "bin",
-    "templates"
+    "bin"
   ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "prompts": "^2.4.2"
+    "@loushy/build-ai-agent": "^1.0.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@types/prompts": "^2.4.9",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^1.6.1"

diff --git a/packages/create-loushy-agent/src/cli.integration.test.ts b/packages/create-loushy-agent/src/cli.integration.test.ts