feat: add create-claudius project scaffolder

.github/workflows/ci.yml

@@ -75,3 +75,34 @@ jobs:
 
       - name: Test (Vitest)
         run: pnpm test
+
+  create-claudius:
+    name: Validate create-claudius
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: create-claudius
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: create-claudius/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: pnpm typecheck
+
+      - name: Test (Vitest)
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

.github/workflows/publish-npm.yml

@@ -1,20 +1,27 @@
 name: Publish to npm
 
-# Manual, on-demand publish of the widget to npm.
+# Manual, on-demand publish of a package to npm.
 #
 # The release-please workflow already publishes automatically when it cuts a
 # release. This workflow exists for the cases that one can't handle:
-#   - bootstrapping the very first publish (the release for the current version
-#     already exists, so re-running release-please is a no-op), and
-#   - recovering from a failed release publish without waiting for the next
-#     release.
+#   - bootstrapping the very first publish of a package (the release for the
+#     current version already exists, so re-running release-please is a no-op), and
+#   - recovering from a failed release publish without waiting for the next release.
 #
 # Requires the NPM_TOKEN secret to be an npm token that can publish the package
-# and bypasses 2FA (a classic Automation token, or a granular token with
-# "All packages" + read/write). Publishes with provenance (needs id-token).
+# (and create it on first publish) and bypasses 2FA — a granular token with
+# "All packages" + read/write, or an account-scoped token. Publishes with
+# provenance (needs id-token).
 on:
   workflow_dispatch:
     inputs:
+      package:
+        description: "Which package to publish"
+        type: choice
+        options:
+          - widget
+          - create-claudius
+        default: widget
       dist-tag:
         description: "npm dist-tag to publish under"
         required: false
@@ -25,16 +32,16 @@ permissions:
   id-token: write # for npm provenance
 
 concurrency:
-  group: publish-npm
+  group: publish-npm-${{ github.event.inputs.package }}
   cancel-in-progress: false
 
 jobs:
   publish:
-    name: Publish widget to npm
+    name: Publish ${{ inputs.package }} to npm
     runs-on: ubuntu-latest
     defaults:
       run:
-        working-directory: widget
+        working-directory: ${{ inputs.package }}
     steps:
       - uses: actions/checkout@v4
 
@@ -47,7 +54,7 @@ jobs:
           node-version: 20
           registry-url: https://registry.npmjs.org
           cache: pnpm
-          cache-dependency-path: widget/pnpm-lock.yaml
+          cache-dependency-path: ${{ inputs.package }}/pnpm-lock.yaml
 
       - name: Install
         run: pnpm install --frozen-lockfile

.github/workflows/release-please.yml

@@ -103,3 +103,13 @@ jobs:
           pnpm install --frozen-lockfile
           pnpm build
           npm publish --provenance --access public
+
+      - name: Build and publish create-claudius
+        if: ${{ steps.release.outputs.release_created }}
+        working-directory: create-claudius
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+          npm publish --provenance --access public

README.md

@@ -1,6 +1,7 @@
 # Claudius - Embeddable AI Chat Widget
 
 [![npm](https://img.shields.io/npm/v/claudius-chat-widget.svg)](https://www.npmjs.com/package/claudius-chat-widget)
+[![create-claudius](https://img.shields.io/npm/v/create-claudius.svg?label=create-claudius)](https://www.npmjs.com/package/create-claudius)
 [![license](https://img.shields.io/npm/l/claudius-chat-widget.svg)](LICENSE)
 
 An open-source, embeddable AI chat widget powered by Claude. Drop it into any
@@ -16,6 +17,19 @@ website with a single script tag, or install it as a React component.
 Claudius is two pieces: a Cloudflare Worker (keeps your Anthropic API key
 server-side) and a widget embed.
 
+### Fastest: scaffold a project
+
+```bash
+npm create claudius@latest
+```
+
+Answer a few prompts (framework — vanilla, React, or Next.js — theme, accent color,
+worker API URL, and optionally a Cloudflare Worker) and you get a ready-to-run
+project. See the
+[scaffolding guide](https://claudius-docs.pages.dev/getting-started/scaffolding/).
+
+Prefer to wire things up by hand? Continue below.
+
 ### 1. Deploy the worker
 
 ```bash

create-claudius/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PMDevSolutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

create-claudius/README.md

@@ -0,0 +1,68 @@
+# create-claudius
+
+[![npm](https://img.shields.io/npm/v/create-claudius.svg)](https://www.npmjs.com/package/create-claudius)
+
+Scaffold a [Claudius](https://claudius-docs.pages.dev) AI chat widget project in
+one command.
+
+```bash
+npm create claudius@latest
+# or
+pnpm create claudius
+# or
+yarn create claudius
+```
+
+You'll be prompted for:
+
+- **Project name** — the new directory / package name
+- **Framework** — `vanilla` (CDN script embed), `react` (Vite), or `next` (Next.js App Router)
+- **Theme** — `auto` / `light` / `dark`, or a built-in theme (`default`, `minimal`, `playful`, `corporate`)
+- **Accent color** — a hex color for the widget
+- **API URL** — your deployed Claudius worker endpoint
+- Optionally, a **Cloudflare Worker** scaffold (`wrangler.toml` + KV stub + deploy runbook)
+
+The generated project runs out of the box:
+
+```bash
+cd my-app
+pnpm install
+pnpm dev
+```
+
+## Non-interactive
+
+Pass flags to skip the prompts (handy for CI):
+
+```bash
+npm create claudius@latest my-app -- \
+  --template react \
+  --theme auto \
+  --accent "#4f46e5" \
+  --api-url https://my-worker.workers.dev \
+  --worker \
+  --yes
+```
+
+| Flag | Values | Description |
+| --- | --- | --- |
+| `--template` | `vanilla` \| `react` \| `next` | Framework template |
+| `--theme` | `auto` \| `light` \| `dark` \| `default` \| `minimal` \| `playful` \| `corporate` | Widget theme |
+| `--accent` | `#rrggbb` | Accent color |
+| `--api-url` | URL | Worker chat endpoint |
+| `--worker` | — | Also scaffold a Cloudflare Worker |
+| `--pm` | `npm` \| `pnpm` \| `yarn` \| `bun` | Package manager shown in next steps |
+| `--yes`, `-y` | — | Accept defaults for any unspecified prompt |
+
+## What you get
+
+- **vanilla** — a static Vite site that loads the widget from the jsDelivr CDN via a
+  single `<script>` tag and `window.ClaudiusConfig`.
+- **react** — a Vite + React + TypeScript app using the `claudius-chat-widget`
+  component and its stylesheet.
+- **next** — a Next.js (App Router) + TypeScript app with a client-side widget wrapper.
+
+See the [documentation](https://claudius-docs.pages.dev) for worker setup and
+configuration.
+
+MIT © PMDevSolutions

create-claudius/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "create-claudius",
+  "version": "1.6.0",
+  "description": "Scaffold a Claudius AI chat widget project in one command.",
+  "keywords": [
+    "claudius",
+    "create",
+    "create-claudius",
+    "scaffold",
+    "cli",
+    "chat-widget",
+    "claude",
+    "ai-chat"
+  ],
+  "author": "PAMulligan",
+  "license": "MIT",
+  "homepage": "https://claudius-docs.pages.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PMDevSolutions/Claudius.git",
+    "directory": "create-claudius"
+  },
+  "bugs": {
+    "url": "https://github.com/PMDevSolutions/Claudius/issues"
+  },
+  "type": "module",
+  "bin": {
+    "create-claudius": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.0"
+  }
+}