@open-aippt/cli 1.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aibabelx
+
+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.

package/README.md

@@ -0,0 +1,38 @@
+# @open-aippt/cli
+
+Scaffold a workspace for [open-aippt](https://github.com/aibabelx/open-aippt) — a React-based slide framework with Claude Code skills preconfigured.
+
+## Usage
+
+```bash
+npx @open-aippt/cli init my-slide
+cd my-slide
+pnpm install
+pnpm dev
+```
+
+This creates a workspace containing:
+
+- `slides/getting-started/` — a starter slide you can edit or delete.
+- `package.json` — depends on `@open-aippt/core`, which provides the runtime (home page, slide viewer, fullscreen mode) and the `open-aippt` CLI.
+- `open-aippt.config.ts` — optional typed config (slidesDir, port).
+- `.claude/skills/` and `.agents/skills/` — Claude Code skills (`create-slide`, `apply-comments`, …).
+- `CLAUDE.md` — agent guide for authoring slides.
+
+You won't see any Vite, React, or tsconfig files in the workspace. They live inside `@open-aippt/core` and you never touch them.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `open-aippt init [dir]` | Scaffold a new workspace in `dir` (defaults to current dir). |
+| `open-aippt init --force` | Scaffold into a non-empty directory. |
+| `open-aippt init --name <name>` | Override the generated `package.json` name. |
+
+(Once installed in the workspace, `@open-aippt/core` provides `open-aippt dev`, `open-aippt build`, and `open-aippt preview` via its own bin.)
+
+## Authoring
+
+Inside the scaffolded workspace, slides live under `slides/<kebab-case-id>/index.tsx` and default-export an array of `Page` components. Each page renders into a fixed 1920×1080 canvas; the framework handles scaling.
+
+Ask Claude Code to "make slides about X" and the `create-slide` skill will take it from there.

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import chalk from "chalk";
+import { cp, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import prompts from "prompts";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+
+//#region src/git.ts
+const IS_WINDOWS$1 = process.platform === "win32";
+async function run$1(cmd, args, cwd) {
+	return new Promise((resolve$1, reject) => {
+		const child = spawn(cmd, args, {
+			cwd,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			shell: IS_WINDOWS$1
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (d) => {
+			stdout += d.toString();
+		});
+		child.stderr?.on("data", (d) => {
+			stderr += d.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolve$1({
+			code,
+			stdout,
+			stderr
+		}));
+	});
+}
+async function isGitAvailable() {
+	try {
+		const res = await run$1("git", ["--version"], process.cwd());
+		return res.code === 0;
+	} catch {
+		return false;
+	}
+}
+async function isInsideWorkTree(cwd) {
+	try {
+		const res = await run$1("git", ["rev-parse", "--is-inside-work-tree"], cwd);
+		return res.code === 0 && res.stdout.trim() === "true";
+	} catch {
+		return false;
+	}
+}
+async function gitInitAndCommit(target) {
+	if (!await isGitAvailable()) return {
+		status: "skipped-no-git",
+		message: "git binary not found on PATH"
+	};
+	if (await isInsideWorkTree(target)) return {
+		status: "skipped-nested",
+		message: "target is already inside a git work tree; leaving parent repo alone"
+	};
+	const init$1 = await run$1("git", ["init"], target);
+	if (init$1.code !== 0) return {
+		status: "failed",
+		message: `git init failed: ${init$1.stderr.trim() || init$1.stdout.trim()}`
+	};
+	const add = await run$1("git", ["add", "-A"], target);
+	if (add.code !== 0) return {
+		status: "failed",
+		message: `git add failed: ${add.stderr.trim() || add.stdout.trim()}`
+	};
+	const commit = await run$1("git", [
+		"commit",
+		"-m",
+		"chore: init open-aippt project"
+	], target);
+	if (commit.code !== 0) return {
+		status: "failed",
+		message: `git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`
+	};
+	return { status: "committed" };
+}
+
+//#endregion
+//#region src/init.ts
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(HERE, "..", "template");
+const IS_WINDOWS = process.platform === "win32";
+function sanitizeDirName(value) {
+	const trimmed = value.trim();
+	if (trimmed === "." || trimmed === "..") return trimmed;
+	const cleaned = trimmed.replace(/\s+/g, "-").replace(/[^\\\p{L}\p{N}_./-]/gu, "-").replace(/-+/g, "-").replace(/(^-|-$)/g, "").replace(/-*([/\\])-*/g, "$1");
+	if (cleaned === "" || /^[/\\]+$/.test(cleaned)) return "my-slides";
+	return cleaned;
+}
+async function isDirNonEmpty(target) {
+	if (!existsSync(target)) return false;
+	const entries = await readdir(target);
+	return entries.some((e) => !e.startsWith("."));
+}
+function coreVersionRange() {
+	return `^1.13.2`;
+}
+async function linkOrCopy(relSrc, dst) {
+	await rm(dst, {
+		recursive: true,
+		force: true
+	});
+	if (IS_WINDOWS) {
+		await cp(resolve(dirname(dst), relSrc), dst, { recursive: true });
+		return;
+	}
+	await symlink(relSrc, dst);
+}
+async function materializeTemplateLinks(target) {
+	const claudeMd = join(target, "CLAUDE.md");
+	if (!existsSync(claudeMd) && existsSync(join(target, "AGENTS.md"))) await linkOrCopy("AGENTS.md", claudeMd);
+	const agentsSkills = join(target, ".agents", "skills");
+	if (!existsSync(agentsSkills)) return;
+	const claudeSkills = join(target, ".claude", "skills");
+	await mkdir(claudeSkills, { recursive: true });
+	const entries = await readdir(agentsSkills, { withFileTypes: true });
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		await linkOrCopy(join("..", "..", ".agents", "skills", entry.name), join(claudeSkills, entry.name));
+	}
+}
+async function runInstall(pm, cwd) {
+	await new Promise((res, rej) => {
+		const child = spawn(pm, ["install"], {
+			cwd,
+			stdio: "inherit",
+			shell: IS_WINDOWS
+		});
+		child.on("error", rej);
+		child.on("close", (code) => code === 0 ? res() : rej(new Error(`${pm} install exited with code ${code}`)));
+	});
+}
+async function init(opts) {
+	const { dir, force, name, packageManager, install, git } = opts;
+	if (!existsSync(TEMPLATE_DIR)) throw new Error(`Template missing at ${TEMPLATE_DIR}. If you are running from source, run \`pnpm --filter @open-aippt/cli build\` first.`);
+	const target = resolve(process.cwd(), dir);
+	await mkdir(target, { recursive: true });
+	if (await isDirNonEmpty(target) && !force) throw new Error(`Target ${target} is not empty. Pass --force to scaffold into it anyway.`);
+	await cp(TEMPLATE_DIR, target, { recursive: true });
+	await materializeTemplateLinks(target);
+	const pkgPath = join(target, "package.json");
+	if (existsSync(pkgPath)) {
+		const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+		pkg.name = name ?? basename(target);
+		pkg.version = "0.0.0";
+		pkg.private = true;
+		if (pkg.dependencies?.["@open-aippt/core"]) pkg.dependencies["@open-aippt/core"] = coreVersionRange();
+		await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+	}
+	await writeFile(join(target, ".gitignore"), "node_modules\ndist\n.DS_Store\n");
+	const cdTarget = dir === "." ? basename(target) : dir;
+	process.stdout.write(`\n${chalk.green.bold("✔ Created open-aippt workspace")} ${chalk.dim(`in ${target}`)}\n`);
+	let installed = false;
+	if (install) {
+		process.stdout.write(`\n${chalk.bold(`Installing dependencies with ${packageManager}…`)}\n\n`);
+		try {
+			await runInstall(packageManager, target);
+			installed = true;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stdout.write(`\n${chalk.yellow("! Dependency install failed:")} ${chalk.dim(msg)}\n` + chalk.dim(`  You can retry manually with \`${packageManager} install\`.\n`));
+		}
+	}
+	if (git) {
+		const result = await gitInitAndCommit(target);
+		if (result.status === "committed") process.stdout.write(`${chalk.green("✔")} Initialized git repository with first commit.\n`);
+		else if (result.status === "skipped-nested") process.stdout.write(`${chalk.yellow("!")} Skipped ${chalk.bold("git init")}: ${chalk.dim(result.message ?? "")}\n`);
+		else if (result.status === "skipped-no-git") process.stdout.write(`${chalk.yellow("!")} Skipped git setup: ${chalk.dim(result.message ?? "")}\n`);
+		else process.stdout.write(`${chalk.yellow("!")} Git setup failed: ${chalk.dim(result.message ?? "")}\n` + chalk.dim("  You can initialize the repo manually.\n"));
+	}
+	process.stdout.write(`\n${chalk.bold("Next steps:")}\n`);
+	process.stdout.write(`  ${chalk.cyan(`cd ${cdTarget}`)}\n`);
+	if (!installed && install) process.stdout.write(`  ${chalk.cyan(`${packageManager} install`)}\n`);
+	else if (!install) process.stdout.write(`  ${chalk.cyan(`${packageManager} install`)}    ${chalk.dim("# install was skipped")}\n`);
+	const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
+	process.stdout.write(`  ${chalk.cyan(devCommand)}\n`);
+}
+
+//#endregion
+//#region src/package-manager.ts
+const PACKAGE_MANAGERS = [
+	"npm",
+	"pnpm",
+	"yarn",
+	"bun"
+];
+function detectPackageManager() {
+	const ua = process.env.npm_config_user_agent ?? "";
+	if (ua.startsWith("pnpm")) return "pnpm";
+	if (ua.startsWith("yarn")) return "yarn";
+	if (ua.startsWith("bun")) return "bun";
+	return "npm";
+}
+
+//#endregion
+//#region src/index.ts
+async function readVersion() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const pkg = JSON.parse(await readFile(join(here, "..", "package.json"), "utf8"));
+	return pkg.version;
+}
+function onCancel() {
+	process.stdout.write(chalk.dim("\nCancelled.\n"));
+	process.exit(130);
+}
+function packageManagerFromFlags(flags) {
+	const picks = [];
+	if (flags.useNpm) picks.push("npm");
+	if (flags.usePnpm) picks.push("pnpm");
+	if (flags.useYarn) picks.push("yarn");
+	if (flags.useBun) picks.push("bun");
+	if (picks.length > 1) throw new Error(`Only one of --use-npm / --use-pnpm / --use-yarn / --use-bun may be specified (got ${picks.map((p) => `--use-${p}`).join(", ")}).`);
+	return picks[0];
+}
+async function runInit(dirArg, flags) {
+	const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	let dir = dirArg;
+	const name = flags.name;
+	let force = flags.force ?? false;
+	let packageManager = packageManagerFromFlags(flags);
+	if (isTTY && dir === void 0) {
+		const answers = await prompts({
+			type: "text",
+			name: "dir",
+			message: "Target directory",
+			initial: "."
+		}, { onCancel });
+		dir = answers.dir;
+	}
+	if (dir !== void 0) {
+		const safe = sanitizeDirName(dir);
+		if (safe !== dir) {
+			if (!isTTY) throw new Error(`Target directory "${dir}" contains characters that break shell commands (spaces, quotes, etc.). Try "${safe}" instead.`);
+			process.stdout.write(`${chalk.yellow("!")} ${chalk.bold(`"${dir}"`)} has characters that confuse shells.\n  Suggested: ${chalk.cyan(`"${safe}"`)}\n`);
+			const answers = await prompts({
+				type: "text",
+				name: "dir",
+				message: "Directory name",
+				initial: safe
+			}, { onCancel });
+			dir = sanitizeDirName(answers.dir ?? safe);
+		}
+	}
+	if (isTTY && packageManager === void 0 && flags.install !== false) {
+		const detected = detectPackageManager();
+		const answers = await prompts({
+			type: "select",
+			name: "packageManager",
+			message: "Package manager",
+			choices: PACKAGE_MANAGERS.map((pm) => ({
+				title: pm,
+				value: pm
+			})),
+			initial: PACKAGE_MANAGERS.indexOf(detected)
+		}, { onCancel });
+		packageManager = answers.packageManager;
+	}
+	const resolvedDir = dir ?? ".";
+	const target = resolve(process.cwd(), resolvedDir);
+	if (!force && await isDirNonEmpty(target)) {
+		if (!isTTY) throw new Error(`Target ${target} is not empty. Pass --force to scaffold into it anyway.`);
+		const { overwrite } = await prompts({
+			type: "confirm",
+			name: "overwrite",
+			message: `${chalk.yellow(target)} is not empty. Scaffold into it anyway?`,
+			initial: false
+		}, { onCancel });
+		if (!overwrite) {
+			process.stdout.write(chalk.dim("Aborted.\n"));
+			return;
+		}
+		force = true;
+	}
+	const opts = {
+		dir: resolvedDir,
+		force,
+		name,
+		packageManager: packageManager ?? detectPackageManager(),
+		install: flags.install !== false,
+		git: flags.git !== false
+	};
+	await init(opts);
+}
+async function run(argv) {
+	const version = await readVersion();
+	const program = new Command();
+	program.name("open-aippt").description("Scaffold and manage open-aippt workspaces.").version(version, "-v, --version", "print version").helpOption("-h, --help", "show help").showHelpAfterError(chalk.dim("(run `open-aippt --help` for usage)"));
+	program.command("init").description("Create a new open-aippt workspace").argument("[dir]", "target directory", void 0).option("-f, --force", "overwrite non-empty target directory", false).option("-n, --name <name>", "override package name (defaults to folder name)").option("--use-npm", "use npm to install dependencies").option("--use-pnpm", "use pnpm to install dependencies").option("--use-yarn", "use yarn to install dependencies").option("--use-bun", "use bun to install dependencies").option("--no-install", "skip dependency installation").option("--no-git", "skip git init and initial commit").action(async (dir, flags) => {
+		await runInit(dir, flags);
+	});
+	await program.parseAsync(argv, { from: "user" });
+}
+
+//#endregion
+//#region src/cli.ts
+run(process.argv.slice(2)).catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`${chalk.red("error:")} ${message}\n`);
+	process.exit(1);
+});
+
+//#endregion

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@open-aippt/cli",
+  "version": "1.3.2",
+  "description": "Scaffold an open-aippt workspace with Claude Code skills preconfigured.",
+  "type": "module",
+  "bin": {
+    "open-aippt": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "slides",
+    "presentation",
+    "claude-code",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "aibabelx",
+    "url": "https://github.com/aibabelx"
+  },
+  "homepage": "https://open-aippt.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aibabelx/open-aippt.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/aibabelx/open-aippt/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^15.0.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "@types/prompts": "^2.4.9",
+    "tsdown": "^0.9.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "sync:template-skills": "node scripts/sync-template-skills.mjs"
+  }
+}

package/template/.agents/skills/apply-comments/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: apply-comments
+description: Apply pending @slide-comment markers written by the open-aippt inspector tool. Use when the user asks to "apply comments", "process slide comments", "apply the inspector comments", or references markers left inside `slides/<id>/index.tsx`.
+---
+
+# Apply slide comments
+
+The open-aippt editor has an inspector tool that lets the user click on a rendered page element and attach a textual comment (e.g. *"make this red"*, *"change to 'open-aippt Rocks'"*). Each comment is persisted as an in-source JSX marker inside `slides/<slideId>/index.tsx`.
+
+Your job: read those markers, perform the described edits, and delete the markers.
+
+> **Before making any page edit**, consult the **`slide-authoring`** skill — it is the technical reference for how `slides/<id>/index.tsx` is structured (canvas, type scale, palette, assets, file contract). A comment like *"make this bigger"* or *"change the accent colour"* should be applied in a way that stays consistent with those rules.
+
+## Marker format
+
+```
+{/* @slide-comment id="c-<8hex>" ts="<ISO>" text="<base64url(JSON)>" */}
+```
+
+- Always sits on its own line as the **first child inside** the JSX element it refers to (i.e. between that element's opening `>` and its other children). The marker is dropped *into* its target, not floated above it.
+- `text` is base64url-encoded JSON: `{"note": "...", "hint"?: "..."}`.
+- Detection regex (authoritative — use exactly this):
+
+  ```
+  /\{\/\*\s*@slide-comment\s+id="(c-[a-f0-9]+)"\s+ts="([^"]+)"\s+text="([A-Za-z0-9_\-]+={0,2})"\s*\*\/\}/g
+  ```
+
+## Procedure
+
+1. **Identify the target slide(s).**
+   - If the user names one (`example-slide`, `youbike-3-survey`, etc.), work on that single `slides/<slideId>/index.tsx`.
+   - If they say "all" or don't specify, scan every `slides/*/index.tsx`. Process each slide one at a time.
+
+2. **Read the file and find all markers.**
+   - Run the regex above against the whole file.
+   - For each match, base64url-decode `text` and `JSON.parse` it to get `{ note, hint? }`.
+   - Record each hit as `{ id, lineIndex (0-based), indent, note, hint }`.
+   - If there are no markers, tell the user and stop.
+
+3. **Understand each comment in context.**
+   - The targeted JSX element is the **enclosing** element of the marker — i.e. read upward from the marker line until you reach the unclosed JSX opening tag whose body the marker lives in. That element is the target. (For self-closing elements like `<img />`, the inspector hoists the marker to the nearest non-self-closing ancestor; in that case the comment usually refers to a child of the enclosing element rather than the enclosing element itself — use the `note` text to disambiguate.)
+   - Read enough surrounding code (parent element, sibling elements, inline styles) to apply the change faithfully. A comment inside a `<div>` with an inline `background` style usually refers to that element's styling, for example.
+   - If the `note` is ambiguous, do the smallest reasonable interpretation and mention the assumption in your summary.
+
+4. **Apply edits in reverse line order.**
+   - Sort markers by descending `lineIndex` and process one at a time, using the `Edit` tool.
+   - Processing top-down would invalidate line numbers for later markers as the file shrinks/grows.
+
+5. **Remove each marker after applying its edit.**
+   - Delete the entire marker line including its trailing `\n`.
+   - Never leave a marker behind. An un-removed marker signals a failure.
+
+6. **Verify.**
+   - After all edits, re-read the file and confirm zero remaining markers.
+   - Run `pnpm tsc --noEmit` and `pnpm biome check` (or `pnpm lint`). Fix any introduced errors.
+
+7. **Report.**
+   - Summarise: `N applied, 0 remaining` plus a one-line description of each change (including the slide id).
+
+## base64url decoding helper
+
+```js
+function decode(s) {
+  const pad = s.length % 4 === 0 ? '' : '='.repeat(4 - (s.length % 4));
+  return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64').toString('utf8');
+}
+```
+
+You can run this inline via `node -e '...'` if you need to inspect a payload; otherwise just reason about the decoded string.
+
+## Edge cases
+
+- **Marker with no enclosing JSX element** (shouldn't happen — the inspector won't write one — but if you find one): delete it and note as orphan.
+- **Multiple markers stacked on consecutive lines inside the same element**: they all refer to that enclosing element. Apply them in source order but still delete each line individually.
+- **`_debugSource` used SWC instead of Babel**: not your problem — the marker line is authoritative.
+- **Comment asks for something outside the target element's scope** (e.g. "add a new page"): do the closest-reasonable edit and mention the scope expansion in your summary.
+- **Can't resolve the comment** (e.g. truly ambiguous, or the file changed shape such that the target element doesn't exist): leave the marker in place and report it as skipped. Don't guess.
+
+## Do not
+
+- Do not touch `package.json`, `open-aippt.config.ts`, or files outside `slides/`.
+- Do not add dependencies.
+- Do not re-introduce markers or leave `TODO` breadcrumbs — the user already has a record in git.

package/template/.agents/skills/create-slide/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: create-slide
+description: Use this skill when the user wants to create, draft, author, or generate new slides / a presentation in this open-aippt repo. Triggers on phrases like "make slides about X", "create a presentation", "draft slides for", "new slide", or when the user asks to add content under `slides/`. Do NOT use for editing the framework itself — only for authoring content inside `slides/<id>/`.
+---
+
+# Create a slide in open-aippt
+
+This skill owns the **workflow** for drafting a new deck. The technical reference — file contract, 1920×1080 canvas, type scale, palette, layout, assets — lives in the **`slide-authoring`** skill. Read that skill whenever you need details on *how* a page is structured. This skill assumes you'll consult it before writing code.
+
+You only write files under `slides/<id>/`. Never modify `package.json`, `open-aippt.config.ts`, or existing slides.
+
+## Step 1 — Pick a theme
+
+List files under `themes/`. If any theme markdown files exist (anything other than `README.md`), call `AskUserQuestion` with each theme id as an option plus a final **"no theme — design from scratch"** option.
+
+- If the user picks a theme: read `themes/<id>.md` end-to-end. The theme's palette, typography, layout, and Title/Footer components are now authoritative — copy them directly into the slide. **Also set `theme: '<theme-id>'` on the `meta` export in `index.tsx`** (e.g. `export const meta: SlideMeta = { title: '…', theme: '<theme-id>' };`) so the slide back-links to the theme (chip on the slide card + listing on `/themes/<id>`). In Step 2, skip the **aesthetic direction** question (the theme already commits to one direction); you still need the topic itself, so confirm it before moving on. Page count, text density, and motion are independent of theme — ask those normally.
+- If the user picks "no theme", or `themes/` is empty (or contains only `README.md`): proceed to Step 2 unchanged.
+
+If you skip the aesthetic question because a theme was picked, restate the theme name in Step 2 so the user can correct course before you start writing.
+
+## Step 2 — Clarify requirements (MUST ask before writing code)
+
+**Before writing any code, lock in the four key style decisions below via `AskUserQuestion`.** They shape every downstream choice (layout, type scale, asset needs, motion code), so locking them in up front avoids rework. Only skip a question when the user's original message already gave an unambiguous answer for it — and if you skip, restate your assumption so they can correct it.
+
+**Topic comes first.** A meaningful aesthetic recommendation requires knowing what the deck is about. If the user's initial request is thin ("make me a deck", "draft some slides"), make a *separate* `AskUserQuestion` call first to gather topic, audience, and any draft outline. Skip this only if the topic is already clear from the user's message — in which case restate your reading of the topic in the next call so they can correct course.
+
+Then ask these four in a single `AskUserQuestion` call (multi-question form):
+
+1. **Aesthetic direction** — propose 3 visual directions tailored to *this* topic. Do **not** pull from a fixed preset list. Each option must combine a vibe word + a concrete visual cue (palette, typography, motif) so the user can picture it; bare labels like "minimal" or "corporate" alone are too vague. The three options should feel meaningfully different from each other — not three flavors of the same idea.
+
+   How options should shift with topic:
+   - *"Intro to Rust for backend engineers"* → **rust-orange technical editorial** (warm rust/charcoal, mono headings, code-grid layout) · **blueprint dev-doc** (cyan grid on near-black, monospace, schematic feel) · **brutalist terminal** (lime-on-black, ASCII rules, no-nonsense)
+   - *"Q2 product roadmap for stakeholders"* → **calm corporate clean** (off-white, single accent, generous whitespace) · **confident editorial** (large display serif, tight grid, one bold accent) · **data-forward dashboard** (charts as hero, muted neutrals + status colors)
+   - *"Kindergarten parent night"* → **playful crayon** (paper texture, hand-drawn accents, primary colors) · **soft pastel storybook** (peach/mint, rounded type, illustrated icons) · **warm photo-led** (full-bleed kid photos, simple captions)
+
+   Mark the option that best fits the topic and audience as "(Recommended)" so the user has a sensible default. (`AskUserQuestion` already auto-adds "Other" — don't add a generic catch-all yourself.)
+
+2. **Page count** — rough length. Offer brackets: 3–5 (short), 6–10 (standard), 11–20 (deep dive), custom.
+3. **Text density per page** — how much copy lives on each page? Offer: minimal (one line / big number), light (heading + 2–3 bullets), standard (heading + 4–5 bullets or short paragraph), dense (multi-column / detailed). This directly drives type scale and layout.
+4. **Motion** — does the user want CSS/React animations and transitions, or a fully static deck? Offer: static (no motion), subtle (fades / entrance only), rich (keyframes, staggered reveals, looping visuals). If animated, plan to use CSS `@keyframes` / inline `style` + `useEffect`; no extra libraries.
+
+After those four, ask follow-ups **only if still unclear**: brand colors, required assets. Don't pad the conversation with questions already answered.
+
+## Step 3 — Pick a slide id
+
+Use **kebab-case**, short, descriptive. Examples: `rust-intro`, `q2-roadmap`, `team-offsite-2026`. Check `slides/` to avoid collisions.
+
+## Step 4 — Plan the structure
+
+Sketch the slide as a list of page roles before writing code. Common page types:
+
+| Role             | Purpose                                       |
+| ---------------- | --------------------------------------------- |
+| Cover            | Title + subtitle, strong visual               |
+| Agenda           | What's coming (3–5 items)                     |
+| Section divider  | Big label between chapters                    |
+| Content          | Heading + 2–5 bullets OR heading + one visual |
+| Big number       | One statistic the size of the canvas          |
+| Quote            | Pull-quote with attribution                   |
+| Comparison       | Two-column before/after or A vs B             |
+| Closing          | CTA, thanks, contact                          |
+
+**Rule of thumb**: one idea per page. If you're tempted to put two, split them.
+
+If the deck topic naturally calls for specific real images the user must supply (product screenshots, team photos, customer dashboards), plan where those go and use `<ImagePlaceholder>` from `@open-aippt/core` — see the **Image placeholders** section in `slide-authoring`. Default is **no placeholders**: only insert one when a real image is genuinely required.
+
+## Step 5 — Commit to a visual direction
+
+Pick one coherent palette / type scale / aesthetic and hold it across every page. The full set of constraints (palette structure, type scale, padding, aesthetic options) lives in `slide-authoring` — apply it.
+
+**Default: declare a top-level `export const design: DesignSystem = { … }`** at the top of `index.tsx` (after imports) using the chosen palette / type scale, and reference the values via `var(--osd-X)` from inline styles. This keeps the slide tweakable from the Design panel after generation, which is what the user almost always wants. Only skip the `design` const for a one-off slide whose palette is intentionally locked and not meant to be re-themed — in that case, fall back to the local `palette` constants pattern. The "Design system" section of `slide-authoring` covers the format and available tokens.
+
+Consult the `frontend-design` skill for deeper aesthetic guidance if the user wants something bold.
+
+## Step 6 — Write `slides/<id>/index.tsx`
+
+Read the **`slide-authoring`** skill before writing — it covers the file contract, canvas rules, type scale, spacing, and asset imports, and it includes a starter template you can copy. Don't duplicate that knowledge here; use it.
+
+## Step 7 — Self-review
+
+Run the checklist in `slide-authoring` ("Self-review before finishing"). It covers structural correctness, layout discipline, and asset existence.
+
+## Step 8 — Hand off to the user
+
+Tell the user:
+
+- The slide id and file path you created.
+- That the dev server will hot-reload — they can open `http://localhost:5173/s/<id>` (or refresh the home page).
+- If dev isn't running: `pnpm dev` from the repo root.
+
+Don't run the dev server yourself unless asked.