@autono/create-open-pages 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Yiwei Ho (open-slide)
+Copyright (c) 2026 Autono Holdings Inc. (open-pdf modifications)
+
+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,45 @@
+# @autono/create-open-pages
+
+Scaffold a workspace for [open-pages](https://openpages.sh) — the web page framework built for agents. Your coding agent writes pages as React components or plain HTML; you get a live browser preview, click-to-comment, and static export to any host.
+
+## Usage
+
+```bash
+npm create @autono/open-pages@latest my-pages
+cd my-pages
+npm run dev
+```
+
+This creates a workspace containing:
+
+- `pages/getting-started/` — a starter page you can edit or delete.
+- `package.json` — depends on `@autono/open-pages`, which provides the runtime (viewer, inspector, export) and the `open-pages` CLI.
+- `open-pages.config.ts` — optional typed config (pagesDir, port, base).
+- `.claude/skills/` and `.agents/skills/` — agent skills (`create-page`, `page-authoring`, `apply-comments`, `create-theme`, `current-page`).
+- `AGENTS.md` (linked as `CLAUDE.md`) — agent guide for authoring pages.
+
+You won't see any Vite, React, Tailwind, or tsconfig files in the workspace. They live inside `@autono/open-pages` and you never touch them.
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `init [dir]` | Scaffold into `dir` (defaults to the current directory). |
+| `-f, --force` | Scaffold into a non-empty directory. |
+| `-n, --name <name>` | Override the generated `package.json` name. |
+| `--use-npm` / `--use-pnpm` / `--use-yarn` / `--use-bun` | Pick the package manager for the install step. |
+| `--no-install` | Skip dependency installation. |
+| `--no-git` | Skip git init and the initial commit. |
+
+## The loop
+
+1. Ask your agent to "make a landing page for X" — the `create-page` skill writes the React.
+2. `npm run dev` shows the live preview at `http://localhost:5173/p/<id>`; every save hot-reloads.
+3. Press `i`, click anything, leave a note — it lands in the source as a marker.
+4. The agent runs `apply-comments`; `open-pages export <id>` writes a deployable static folder.
+
+Full documentation: [docs.openpages.sh](https://docs.openpages.sh)
+
+## License
+
+MIT

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-pages 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-pages";
+	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 `^0.1.0`;
+}
+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 @autono/create-open-pages 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?.["@autono/open-pages"]) pkg.dependencies["@autono/open-pages"] = coreVersionRange();
+		await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+	}
+	await writeFile(join(target, ".gitignore"), "node_modules\ndist\nexport\n.DS_Store\n");
+	const cdTarget = dir === "." ? basename(target) : dir;
+	process.stdout.write(`\n${chalk.green.bold("✔ Created open-pages 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("create-open-pages").description("Scaffold and manage open-pages workspaces.").version(version, "-v, --version", "print version").helpOption("-h, --help", "show help").showHelpAfterError(chalk.dim("(run `create-open-pages --help` for usage)"));
+	program.command("init", { isDefault: true }).description("Create a new open-pages 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,58 @@
+{
+  "name": "@autono/create-open-pages",
+  "version": "0.1.0",
+  "description": "Scaffold an open-pages workspace — agent skills preconfigured, live real-PDF preview out of the box.",
+  "type": "module",
+  "bin": {
+    "create-open-pages": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/sync-template-skills.mjs && tsdown",
+    "typecheck": "tsc --noEmit",
+    "sync:template-skills": "node scripts/sync-template-skills.mjs",
+    "prepack": "pnpm build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pdf",
+    "pages",
+    "claude-code",
+    "agents",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "autonoco",
+    "url": "https://github.com/autonoco"
+  },
+  "homepage": "https://openpages.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/autonoco/open-pages.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/autonoco/open-pages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^6.0.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"
+  }
+}

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

@@ -0,0 +1,86 @@
+---
+name: apply-comments
+description: Apply pending @page-comment markers written by the open-pages inspector tool. Use when the user asks to "apply comments", "process page comments", "apply the inspector comments", or references markers left inside `pages/<id>/index.tsx` (or its `components/*.tsx`).
+---
+
+# Apply page comments
+
+The open-pages viewer has an inspector that lets the user click any element on the live page and attach a textual comment (e.g. *"make this red"*, *"change to 'Open Pages Rocks'"*). Each comment is persisted as an in-source JSX marker inside the page's source — usually `pages/<pageId>/index.tsx`, occasionally a file under `pages/<pageId>/components/`.
+
+Your job: read those markers, perform the described edits, and delete the markers.
+
+> **Before making any page edit**, consult the **`page-authoring`** skill — it is the technical reference for how a page is structured (file contract, `className` styling, layout and responsive rules, type scale, interactivity). A comment like *"make this bigger"* or *"change the accent colour"* should be applied in a way that stays consistent with those rules and still works on mobile.
+
+## Marker format
+
+```
+{/* @page-comment id="c-<8hex>" ts="<ISO>" text="<base64url(JSON)>" */}
+```
+
+- Inserted as the **first child inside** the JSX element it refers to: a newline + indent + the marker, spliced immediately after the element's opening `>`. The marker is dropped *into* its target, not floated above it. **The marker does not necessarily end its line** — for an element that was written on one line (`<h1>Title</h1>`), the element's children and closing tag follow the marker on the same line.
+- `text` is base64url-encoded JSON: `{"note": "...", "hint"?: "..."}`.
+- Detection regex (authoritative — use exactly this):
+
+  ```
+  /\{\/\*\s*@page-comment\s+id="(c-[a-f0-9]+)"\s+ts="([^"]+)"\s+text="([A-Za-z0-9_\-]+={0,2})"\s*\*\/\}/g
+  ```
+
+## Procedure
+
+1. **Identify the target page(s).**
+   - If the user names one (`launch`, `pricing`, etc.), work on that single page's source files.
+   - If they say "all" or don't specify, scan every `pages/*/index.tsx` and `pages/*/components/*.tsx`. Process each page 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), 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, `className` strings, any state the element depends on) to apply the change faithfully. A comment inside a `<button>` with an `onClick` may be about behaviour, not looks.
+   - If the marker sits inside a `.map` body, the comment applies to the row template — every rendered row changes. If the user clearly meant one item ("make the *middle* one green"), change the data or add a per-item field rather than special-casing the JSX.
+   - 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 **only the marker text itself** — the `{/* @page-comment … */}` span matched by the detection regex — plus the newline and indentation immediately *before* it (the whitespace the inspector inserted). Never delete the whole line: children and the closing tag often share the marker's line, and removing the line destroys them.
+   - After removal, if the element is left split across two lines that were originally one (`<h1 …>\n  Title</h1>`), it is fine to rejoin them, but not required.
+   - Never leave a marker behind for an edit you applied — that signals a failure. Markers deliberately skipped per the edge cases below stay in place.
+
+6. **Verify.**
+   - After all edits, re-read the file and confirm the only remaining markers are ones you reported as skipped.
+   - Confirm the edited JSX is well-formed (balanced tags, no dangling attributes) and that changed `className` strings are literal Tailwind utilities. If the project's `package.json` has typecheck/lint scripts, run them with the project's package manager; scaffolded projects ship neither TypeScript nor a linter — there, rely on the running dev server (or the `build` script) to surface compile errors. Fix any errors you introduced.
+   - For layout changes, mentally check the Mobile viewport (390px): did the edit introduce a fixed width or a grid with no stacking fallback?
+
+7. **Report.**
+   - Summarise: `N applied, M skipped` plus a one-line description of each change (including the page 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. Read their notes in source order to understand the combined intent, then apply and delete them bottom-up per step 4.
+- **Comment asks for something outside the target element's scope** (e.g. "add a testimonials section"): do the closest-reasonable edit and mention the scope expansion in your summary.
+- **Comment on a plain HTML page** (`pages/<id>/index.html`): the inspector does not run there, so no markers exist. Apply the user's request directly to the HTML.
+- **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-pages.config.ts`, or files outside `pages/`.
+- 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-page/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: create-page
+description: Use this skill when the user wants to create, build, draft, or generate a new web page, site, or landing page in this open-pages repo. Triggers on phrases like "make a landing page for X", "build a pricing page", "create a portfolio site", "new page", "a dashboard UI", "an HTML page", or when the user asks to add content under `pages/`. Do NOT use for editing the framework itself — only for authoring content inside `pages/<id>/`.
+---
+
+# Create a page in open-pages
+
+This skill owns the **workflow** for building a new page. The technical reference — file contract, Tailwind via `className`, layout and responsive rules, type scale, interactivity, assets — lives in the **`page-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 `pages/<id>/`. Never modify `package.json`, `open-pages.config.ts`, or existing pages.
+
+## 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. (`AskUserQuestion` holds at most 4 options — with 4+ themes, offer the 3 most topic-relevant plus "no theme"; the auto-added "Other" lets the user name any omitted theme.)
+
+- If the user picks a theme: read `themes/<id>.md` end-to-end. The theme's palette, typography, and fixed components are now authoritative — copy them directly into the page. **Also set `theme: '<theme-id>'` on the `meta` export** so the page back-links to the theme. In Step 2, skip the **visual direction** question (the theme already commits to one); confirm the page's purpose itself before moving on. Sections and interactivity are independent of theme — ask those normally.
+- If the user picks "no theme", or `themes/` contains no theme markdown files: proceed to Step 2 unchanged.
+
+If you skip the visual-direction 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 key decisions below via `AskUserQuestion`.** They shape every downstream choice, so locking them in up front avoids rework. Only skip a question when it's already unambiguously answered — by the user's original message, or by a theme picked in Step 1 — and if you skip, restate your assumption so they can correct it.
+
+**Purpose comes first.** If the user's initial request is thin ("make me a page", "build a site"), make a *separate* `AskUserQuestion` call first to gather what the page is for, who lands on it, and what content they already have (copy, product names, prices, screenshots, links). Skip this only if already clear — then restate your reading so they can correct course.
+
+Then ask these four in a single `AskUserQuestion` call (multi-question form):
+
+1. **Page type** — offer the closest fits: landing / marketing page, product or pricing page, dashboard or app UI, docs or long-form content page, portfolio or personal site, form or signup flow, internal tool. Mark the best fit "(Recommended)". This drives structure and how much interactivity to expect.
+
+2. **Visual direction** — propose 3 directions tailored to *this* page and its audience. Do **not** pull from a fixed preset list. Each option must combine a vibe word + a concrete visual cue (palette, weight, surfaces) so the user can picture it; bare labels like "modern" are too vague. The three options should feel meaningfully different.
+
+   How options should shift with page type:
+   - *SaaS landing page* → **dark launch** (near-black, one neon accent, large display type) · **clean product** (white, slate text, one indigo accent, soft cards) · **editorial** (warm off-white, serif display, generous whitespace)
+   - *Dashboard* → **ops console** (dense, slate surfaces, status colors) · **calm workspace** (airy, rounded cards, one accent) · **data-forward** (tables and charts as the spine, mono numerals)
+   - *Portfolio* → **gallery** (big imagery, minimal chrome) · **typographic** (type does the work, one accent) · **playful** (color blocks, rounded shapes, motion)
+
+   Mark the best fit "(Recommended)". (`AskUserQuestion` auto-adds "Other" — don't add a catch-all yourself.)
+
+3. **Sections / content** — offer bundles that fit the type, e.g. for a landing page: hero + features + pricing + FAQ + footer (Recommended); hero + social proof + CTA (short); hero + long-form explainer + CTA. The auto-added "Other" covers custom lists.
+
+4. **Interactivity** — offer: static (links only), light (tabs, toggles, accordions, a pricing switch), form (a contact/signup form that mirrors state locally or posts to a URL they supply), app-like (filters, local state, multiple views). Note that no backend exists — anything that needs one requires a URL from the user.
+
+After those, ask follow-ups **only if still unclear**: brand colors, logo/screenshots, real copy (headlines, prices, names). Real pages live on real content — placeholder copy like "Acme, $10/mo" is a last resort; prefer asking for the real values. Responsive is not a question: every page must work at Desktop, Tablet (820px), and Mobile (390px).
+
+## Step 3 — Pick a page id
+
+Use **kebab-case**, short, descriptive. Examples: `launch`, `pricing`, `status-board`, `founder-portfolio`, `waitlist`. Check `pages/` to avoid collisions.
+
+## Step 4 — Plan the structure
+
+Sketch the page as an ordered list of sections before writing code. Common shapes:
+
+| Section | Purpose |
+| --- | --- |
+| Header / nav | Wordmark, 3–5 links, one CTA; collapses on mobile |
+| Hero | One headline, one lede, primary + secondary CTA, optional visual |
+| Social proof | Logos, a metric row, one quote |
+| Features | 3–6 cards or alternating rows, each one benefit |
+| Pricing | 2–3 tiers, a billing toggle, clear CTA per tier |
+| FAQ | Accordion or plain list |
+| CTA band | Restate the ask before the footer |
+| Footer | Links, legal line |
+| App shell | Sidebar/topbar + content area for dashboards and tools |
+
+**Rule of thumb:** one idea per section, one CTA per screen. If a section lists things, it wants a grid or a table, not a paragraph.
+
+Decide the data shape now: which sections render from a typed const array (`.map`), which are explicit component instances — `page-authoring` explains why this matters for the inspector.
+
+## Step 5 — Commit to a visual direction
+
+One palette, one type scale, held for the whole page. The constraints (web type scale, palette structure, contrast) live in `page-authoring` and its `references/typography-and-color.md` — apply them. Define the palette as repeated Tailwind utilities (or a small const map of class strings). Fonts: default to the system stack; load a Google Font or self-hosted file only when the user names one or a theme requires it (`references/assets-and-fonts.md`).
+
+## Step 6 — Write `pages/<id>/index.tsx`
+
+Read the **`page-authoring`** skill before writing — file contract, `className` styling, layout and responsive rules, interactivity constraints, assets. Its file-contract example is the starter template. Split large pages into `pages/<id>/components/*.tsx` when a section is more than ~80 lines.
+
+## Step 7 — Self-review
+
+Run the checklist in `page-authoring` ("Self-review before finishing"). Check all three viewports.
+
+## Step 8 — Hand off to the user
+
+Tell the user:
+
+- The page id and file path you created.
+- The preview URL — `http://localhost:5173/p/<id>` — hot-reloads on every edit, with Desktop / Tablet / Mobile toggles and **Open** to view the page by itself.
+- That they can hit **Inspect** (or `i`) in the preview, click any element, and leave comments — then ask you to run `apply-comments`.
+- That `open-pages export <id>` writes `export/<id>/` — a static folder (index.html + assets) they can deploy to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any static host.
+- If dev isn't running: run the project's `dev` script from the project root with its package manager (`npm run dev`, `pnpm dev`, … — match the lockfile).
+
+Don't run the dev server yourself unless asked.