@autono/create-open-pages 0.1.0

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

@@ -0,0 +1,223 @@
+---
+name: create-theme
+description: Use this skill when the user wants to create, draft, author, or extract a page theme in this open-pages repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <page>", "build a design system from these screenshots", "match our brand". Produces two paired files under `themes/` — `<id>.md` (palette, typography, layout, fixed components) and `<id>.demo.tsx` (a runnable demo page the workspace's Themes panel previews live). Do NOT use for editing real pages — only for authoring the theme bundle.
+---
+
+# Create a page theme
+
+This skill produces a **theme bundle** under `themes/`: two paired files that together describe a reusable visual identity for web pages.
+
+1. `themes/<id>.md` — agent-facing documentation: palette, typography, layout, fixed components (nav, hero, section wrapper, buttons, card, footer). This is what `create-page` reads when an author picks the theme.
+2. `themes/<id>.demo.tsx` — a runnable demo page (same module shape as `pages/<id>/index.tsx`: **one default-exported component**) that shows the theme on a single scrolling page. The workspace's Themes panel renders it live, exactly like a real page.
+
+Both files share the same stem so the runtime can pair them automatically.
+
+The theme markdown is authoring-time direction — `create-page` copies its palette, utilities, and components into a real page's source. The demo `.tsx` is a self-contained preview, not a real page — it does not appear in the pages list.
+
+You only write `themes/<id>.md` and `themes/<id>.demo.tsx`. Never modify real pages or configuration. The styling rules and web defaults that themes override live in the **`page-authoring`** skill — read it before writing the theme so your overrides are stated explicitly.
+
+## Step 1 — Identify the input source
+
+A theme can be derived from any combination of three input shapes:
+
+- **Image references** — paths or URLs to screenshots, mood-board images, brand assets.
+- **Free-text description** — prose describing the desired palette, weight, feel.
+- **An existing page** — `pages/<id>/index.tsx` whose visual identity should be lifted out into a reusable theme.
+
+If the user's original message already specifies the inputs unambiguously, skip the question and proceed. Otherwise call `AskUserQuestion` (multi-select) so they can pick one or more sources, and ask follow-ups (paths, page id, prose) only as needed.
+
+## Step 2 — Gather raw inputs
+
+- **Images**: read each path with the `Read` tool (it accepts images). Note dominant colors as hex, type weight and family feel, corner radius, surface treatment (flat vs. cards vs. borders), density, and recurring chrome (nav style, footer).
+- **Text**: extract explicit tokens (hex codes, font names, tone words) and resolve vague language into concrete decisions before writing.
+- **Existing page**: read `pages/<id>/index.tsx` (and `components/`) and pull:
+  - The Tailwind color utilities used consistently (`bg-…`, `text-…`, accent classes) → Palette section.
+  - Type sizes and any font loading (`<link>` to Google Fonts, `font-[…]`) → Typography section.
+  - Container widths, section padding, breakpoints used → Layout section.
+  - Recurring helper components (nav, hero, cards, buttons, footer) → Fixed components section.
+  - The aesthetic feel implied → Aesthetic paragraph.
+
+When inputs disagree (e.g. images use blue but the description says green), ask the user which to honor.
+
+## Step 3 — Pick a theme id
+
+Use **kebab-case**, short, descriptive. Examples: `dark-launch`, `clean-saas`, `editorial-warm`, `ops-console`. Check `themes/` to avoid collisions.
+
+## Step 4 — Write `themes/<id>.md`
+
+Produce a file with this exact section order. Section bodies adapt to the theme; the headings stay consistent across all themes.
+
+````markdown
+---
+name: <Human title, e.g. "Dark Launch">
+description: <one-line elevator pitch>
+---
+
+# <Theme name>
+
+## Palette
+
+| Role | Tailwind | Hex | Notes |
+| --- | --- | --- | --- |
+| background | `bg-[#0b0b10]` | #0b0b10 | page root |
+| surface | `bg-white/[0.04] border-white/10` | — | cards, panels |
+| text | `text-white` | #ffffff | headings, body |
+| muted | `text-white/60` | — | secondary copy, labels |
+| accent | `bg-emerald-400 text-black` / `text-emerald-400` | #34d399 | primary CTA, eyebrows |
+| border | `border-white/10` | — | dividers, card edges |
+
+## Typography
+
+- Font: system stack, or a named family with how to load it (Google Fonts `<link>` rendered in the page, or a self-hosted file the page must place under `assets/`).
+- Type-scale overrides (only list what differs from `page-authoring` defaults):
+  - Hero heading: `text-5xl sm:text-7xl font-bold leading-[1.02] tracking-tight`
+  - Section heading: `text-3xl font-bold tracking-tight`
+  - Body: `text-lg text-white/60`
+  - Eyebrow: `text-xs font-semibold uppercase tracking-[0.25em] text-emerald-400`
+
+## Layout
+
+- Container: `mx-auto max-w-6xl px-6`.
+- Section rhythm: `py-20`, sections separated by `border-t border-white/10`.
+- Breakpoints: single column by default; `sm:grid-cols-3` for feature and pricing grids; nav links `hidden sm:flex`.
+- Radius: `rounded-full` for buttons, `rounded-2xl` for cards.
+
+## Fixed components
+
+These are paste-ready React JSX with `className`. Copy them verbatim into a page that uses this theme.
+
+### Nav
+
+```tsx
+const Nav = ({ brand, links, cta }: { brand: string; links: { label: string; href: string }[]; cta: { label: string; href: string } }) => (
+  <header className="mx-auto flex max-w-6xl items-center justify-between px-6 py-6">
+    <span className="font-semibold tracking-tight">{brand}</span>
+    <nav className="hidden gap-8 text-sm text-white/70 sm:flex">
+      {links.map((l) => (
+        <a key={l.href} href={l.href} className="hover:text-white">{l.label}</a>
+      ))}
+    </nav>
+    <a href={cta.href} className="rounded-full bg-white px-4 py-2 text-sm font-medium text-black hover:bg-white/90">{cta.label}</a>
+  </header>
+);
+```
+
+### Hero
+
+```tsx
+const Hero = ({ eyebrow, title, lede, children }: { eyebrow: string; title: string; lede: string; children?: React.ReactNode }) => (
+  <section className="mx-auto max-w-6xl px-6 pt-20 pb-24 text-center">
+    <p className="text-xs font-semibold uppercase tracking-[0.25em] text-emerald-400">{eyebrow}</p>
+    <h1 className="mx-auto mt-6 max-w-3xl text-5xl font-bold leading-[1.02] tracking-tight sm:text-7xl">{title}</h1>
+    <p className="mx-auto mt-6 max-w-xl text-lg text-white/60">{lede}</p>
+    <div className="mt-10 flex flex-col justify-center gap-3 sm:flex-row">{children}</div>
+  </section>
+);
+```
+
+### Section
+
+```tsx
+const Section = ({ id, children }: { id?: string; children: React.ReactNode }) => (
+  <section id={id} className="border-t border-white/10">
+    <div className="mx-auto max-w-6xl px-6 py-20">{children}</div>
+  </section>
+);
+```
+
+### Buttons
+
+```tsx
+const PrimaryButton = ({ href, children }: { href: string; children: React.ReactNode }) => (
+  <a href={href} className="rounded-full bg-emerald-400 px-6 py-3 font-medium text-black hover:bg-emerald-300">{children}</a>
+);
+const SecondaryButton = ({ href, children }: { href: string; children: React.ReactNode }) => (
+  <a href={href} className="rounded-full border border-white/20 px-6 py-3 font-medium text-white/80 hover:border-white/40">{children}</a>
+);
+```
+
+### Card
+
+```tsx
+const Card = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <div className="rounded-2xl border border-white/10 bg-white/[0.03] p-6">
+    <h3 className="font-semibold">{title}</h3>
+    <div className="mt-2 text-white/60">{children}</div>
+  </div>
+);
+```
+
+### Footer
+
+```tsx
+const Footer = ({ left, right }: { left: string; right: string }) => (
+  <footer className="border-t border-white/10">
+    <div className="mx-auto flex max-w-6xl items-center justify-between px-6 py-8 text-sm text-white/40">
+      <span>{left}</span>
+      <span>{right}</span>
+    </div>
+  </footer>
+);
+```
+
+## Aesthetic
+
+One paragraph. What it feels like, the references it draws on, what to avoid (e.g. "no gradients; one accent only; borders over shadows; motion limited to hover color changes"). Commit to a single direction.
+
+## Example usage
+
+```tsx
+<main className="min-h-screen bg-[#0b0b10] text-white antialiased">
+  <Nav brand="Meridian" links={links} cta={{ label: 'Get started', href: '#pricing' }} />
+  <Hero eyebrow="Now in public beta" title="Your analytics, turned into decisions" lede="…">
+    <PrimaryButton href="#pricing">Start free</PrimaryButton>
+    <SecondaryButton href="#features">See how it works</SecondaryButton>
+  </Hero>
+  {/* … */}
+  <Footer left="© 2026 Meridian" right="Built with open-pages" />
+</main>
+```
+````
+
+## Step 4b — Write `themes/<id>.demo.tsx`
+
+The demo is a normal page module — same shape as `pages/<id>/index.tsx`, just sitting under `themes/` so the runtime knows it's preview-only.
+
+Contract:
+
+- `import type { PageMeta } from '@autono/open-pages';` and React hooks as needed.
+- **One default-exported component** — a single scrolling page that exercises the theme: nav, hero with both buttons, a section with a card grid, a footer.
+- Inline the **same** fixed components defined in the theme markdown — verbatim, no abstractions. Demo and markdown must stay in lockstep so what `create-page` pastes matches what the demo shows.
+- Root element sets `min-h-screen`, the theme background, and text color. Must look right at Mobile (390px) as well as Desktop.
+- Content should be plausible and realistic, not lorem ipsum. Self-contained: no `@/` imports, no page-local assets; if the theme names a Google Font, render the `<link>` tag in the demo too.
+
+## Step 5 — Self-review
+
+- [ ] Palette table covers background / surface / text / muted / accent / border as Tailwind utilities, with hex where fixed.
+- [ ] Frontmatter has `name` and `description` only (the runtime reads nothing else).
+- [ ] Typography names only fonts the theme explains how to load (or the system stack).
+- [ ] Layout specifies container width, section rhythm, and breakpoints.
+- [ ] Fixed components are paste-ready React JSX (`className`, typed props, no `@/` imports) and cover nav, hero, section, buttons, card, footer.
+- [ ] Aesthetic paragraph names a single coherent direction.
+- [ ] Both files written: `themes/<id>.md` and `themes/<id>.demo.tsx`. No page changes, no config changes.
+- [ ] Demo `.tsx` default-exports one component and inlines the same fixed components as the markdown; contrast holds; nothing overflows on mobile.
+
+## Step 6 — Hand off
+
+Tell the user:
+
+- The theme id and the two file paths.
+- That the Themes panel in the workspace (`http://localhost:5173/themes`) previews the demo live, and `/create-page` will list the theme as a picker option on its next run.
+- A one-line summary of the look (palette + aesthetic).
+
+Do not run the dev server. Do not modify real pages — the demo `.tsx` is the demonstration.
+
+## Anti-patterns
+
+- ❌ Writing executable code in `themes/<id>.md` outside the labeled component snippets — the markdown is documentation.
+- ❌ Producing only the markdown without the demo, or only the demo without the markdown. A theme is the **bundle** — both files, every time.
+- ❌ Desktop-only components: a nav with no mobile behaviour, grids with no stacking fallback.
+- ❌ Naming font families the theme never explains how to load.
+- ❌ Inventing palette / styling when the user supplied images or an existing page. Extract, don't fabricate.
+- ❌ Editing `pages/`, `packages/`, `package.json`, or `open-pages.config.ts`.
+- ❌ Skipping Fixed components. Nav, hero, buttons, and footer are the most common reuse targets — they must be paste-ready.

package/template/.agents/skills/current-page/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: current-page
+description: Resolve which page and (optionally) selected element the user is currently viewing in the open-pages dev server. Consult this whenever the user references "this page", "this site", "this element", "the page I'm on", "the button I clicked", or any deictic reference to page content without naming it. Re-read `node_modules/.open-pages/current.json` at the start of every such turn — the user navigates between turns, so a value you read earlier in the conversation is almost certainly stale.
+---
+
+# Where is the user right now?
+
+When the user says "fix this page", "tweak this heading", or "the page I'm looking at", they almost never name the page id or element — they mean wherever they are in the dev viewer. Before asking "which page?" or "which element?", check the file the dev server writes on every navigation and inspector pick.
+
+## Re-read on every deictic turn — never reuse a prior read
+
+`current.json` is a live cursor, not a fact about the conversation. The user moves between pages and elements freely between your turns — including while you were doing other work. **Read the file fresh at the start of every new turn that uses a deictic reference**, even if:
+
+- you already read it earlier in this same conversation,
+- you just finished editing the page it pointed to,
+- the user's new message sounds like a continuation ("now make it bigger", "also fix this one", "keep going").
+
+A "continue editing" follow-up is exactly the case where the user has likely just navigated to a different page or picked a different element. Trusting your last read here will silently edit the wrong file. Re-read, compare `pageId` / `selection` against what you used last time, and act on the new values.
+
+## How to read it
+
+```
+node_modules/.open-pages/current.json
+```
+
+Path is relative to the project root (the user's `cwd`, the directory that contains `pages/` and `package.json`). Use the `Read` tool. The file is JSON.
+
+## What you get
+
+```json
+{
+  "pageId": "launch",
+  "pageTitle": "Meridian — Launch",
+  "view": "pages",
+  "pagePath": "pages/launch/index.tsx",
+  "selection": {
+    "line": 52,
+    "column": 8,
+    "tagName": "h1",
+    "text": "Your analytics, turned into decisions"
+  },
+  "updatedAt": "2026-08-28T14:32:11.123Z"
+}
+```
+
+- `pageId` — folder name under `pages/`. Use as-is for any `/__pages/<id>/...` API or as the URL segment (`/p/<id>`).
+- `pageTitle` — the page's `meta.title` (or `<title>` for an HTML page), falling back to the id.
+- `pagePath` — page entry path **relative to the project root**: `pages/<id>/index.tsx`, or `pages/<id>/index.html` for a plain HTML page. Prefix it with the project root before handing it to `Read` / `Edit`. Note the selection may point into a file under `pages/<id>/components/` if the page is split — match the line against the file whose JSX contains that tag and text.
+- `view` — `"pages"` when the user is viewing the page, `"assets"` when they are browsing that page's files in the asset manager rather than the page itself.
+- `selection` — `null` if nothing is selected. Otherwise, the JSX element the user picked in the inspector:
+  - `line` (1-indexed) and `column` (0-indexed) point to the JSX opening tag in the page source. This is the canonical handle — match against the source line.
+  - `tagName` is the rendered HTML tag, lowercased (`"h1"`, `"div"`, `"button"`).
+  - `text` is a trimmed text snippet (≤120 chars) of the element's content — a sanity check that you're looking at the right node.
+  - Selection auto-clears whenever the user navigates to a different page or clears it in the viewer. HTML pages never produce a selection.
+- `updatedAt` — ISO timestamp of the last navigation or selection change. Use it to detect staleness.
+
+## When to use this
+
+- The user references the current page deictically: "this", "here", "the page I'm on", "the site I'm looking at", "what I'm working on".
+- The user references a specific element: "this heading", "this image", "the button I just clicked", "tighten this", "change the color of this". If `selection` is non-null, that's the element they mean.
+- Before asking "which page?" or "which element?" as a clarifying question — check this file first.
+- Before guessing from `git log`, recently-edited files, or the most recent page folder.
+
+## When NOT to use this
+
+- The user names a page explicitly ("edit `launch`") — use that name directly.
+- The `apply-comments` workflow already finds the right file via `@page-comment` markers; it doesn't need this skill.
+- For listing or discovering pages — read `pages/` directly.
+
+## Staleness — verify before acting
+
+`updatedAt` is the last time the user navigated. Treat it like a cache:
+
+- **Fresh (under ~5 minutes old)**: trust it. Open `pagePath`, do the work.
+- **Older than ~5 minutes**: confirm with the user before editing. The dev server may not be running; the user may have switched contexts.
+- **Hours/days old**: ignore it. Ask the user which page they mean.
+
+A *newer* `updatedAt` than the one you saw last turn is the normal signal that the user has moved — switch to the new `pageId` / `selection` without asking.
+
+## When the file is missing
+
+- The dev server hasn't been opened on a page yet, or has never run.
+- Don't create the file or guess. Ask the user which page they mean, or suggest they open the page in the dev server first.
+
+## Example — page-level reference
+
+User: "tighten the spacing on this page"
+
+1. Read `node_modules/.open-pages/current.json`.
+2. Check `updatedAt` is recent.
+3. Read `pagePath` (e.g. `pages/launch/index.tsx`).
+4. If `selection` is set, jump to that line; otherwise identify the relevant section from the user's words.
+5. Consult the `page-authoring` skill for spacing and layout rules, then edit in place.
+
+If `current.json` is missing or stale, ask: "Which page should I tighten? The dev server hasn't published a current page recently."
+
+## Example — element-level reference
+
+User: "make this bigger"
+
+1. Read `node_modules/.open-pages/current.json`.
+2. If `selection` is non-null, the user means that element. Read `pagePath`, jump to `selection.line`, and find the JSX opening tag near that line/column. Confirm with the snippet in `selection.text` and the `tagName`.
+3. Consult `page-authoring` for type-scale and responsive rules before editing (bigger on desktop usually means a `sm:`/`lg:` step, not a fixed size).
+4. Edit the JSX node in place.
+
+If `selection` is null, fall back to the page-level flow above — and consider asking "which element?" since the user used a deictic but hasn't picked one in the inspector.

package/template/.agents/skills/page-authoring/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: page-authoring
+description: Technical reference for writing or editing open-pages pages — file contract, Tailwind via `className`, layout and responsive breakpoints, web type scale, interactivity with hooks and state, assets and fonts, plain `index.html` pages, and the self-review checklist. Consult this whenever you are about to write or modify any file under `pages/<id>/`, including from inside the `create-page` or `apply-comments` workflows, or for any ad-hoc page edit. Triggers on phrases like "edit the page", "fix the layout", "change the palette", "add a section", "make it responsive", "add a form", "investigate the page framework", "how do pages work here".
+---
+
+# Authoring open-pages pages
+
+This skill is the **technical reference** for everything that happens inside `pages/<id>/`. It does not own a workflow:
+
+- `create-page` owns "build a new page" — it asks the user scoping questions, then delegates the *how* to this skill.
+- `apply-comments` owns "process inspector markers" — it finds markers and applies edits, but the edits themselves follow the rules here.
+- `current-page` resolves deictic references ("this page", "this element") to a concrete `pageId` + selection. Consult it **first** when the user references the current page without naming it, then come back here for how to edit it.
+- Any ad-hoc page edit (manual tweak, one-off fix) should also consult this skill before touching the file.
+
+A page here is a **real web page**: one React component rendered into a real browser document. The workspace previews it live in an iframe, the inspector maps clicks back to source lines, and `open-pages export` turns it into a static folder you can deploy anywhere. Your job is a good web page; the runtime's job is preview, comments, and export.
+
+## Topic references
+
+Details live under `references/` in this skill. **Read the relevant file before using the feature**:
+
+| Topic | Read before | File |
+| --- | --- | --- |
+| Layout + responsive | any multi-column layout, nav, hero, grid; anything that must work on mobile | `references/layout-and-responsive.md` |
+| Typography + color | picking a type scale or palette, dark backgrounds, contrast | `references/typography-and-color.md` |
+| Interactivity | state, forms, tabs, toggles, anything with an event handler | `references/interactivity.md` |
+| Assets + fonts | images, icons, custom fonts, Google Fonts | `references/assets-and-fonts.md` |
+| Plain HTML pages | a page authored as `index.html` instead of React | `references/html-pages.md` |
+
+## Hard rules
+
+- Put the page under `pages/<kebab-case-id>/`.
+- Entry is `pages/<id>/index.tsx` (or `pages/<id>/index.html` for a plain HTML page — see `references/html-pages.md`).
+- Do **not** touch `package.json`, `open-pages.config.ts`, or other pages.
+- Do not add dependencies. Only `react`, `react-dom`, and `@autono/open-pages` (types) are available, plus browser APIs.
+- A page is `index.tsx` plus, optionally, `components/*.tsx`, `styles.css`, and `assets/` for its images and fonts — all inside `pages/<id>/`. Shared assets live in the root `assets/` folder and import via `@assets/...`. No `README.md`, no config files.
+- Style with Tailwind utilities on `className`. Tailwind is preconfigured and scans `pages/` and `themes/`; there is nothing to set up.
+
+## File contract
+
+```tsx
+// pages/<id>/index.tsx
+import type { PageMeta } from '@autono/open-pages';
+import { useState } from 'react';
+
+export const meta: PageMeta = {
+  title: 'Meridian — Launch',
+  description: 'Meridian turns your analytics into weekly decisions.',
+  createdAt: '2026-08-28T12:00:00.000Z',
+};
+
+export default function Launch() {
+  const [open, setOpen] = useState(false);
+  return (
+    <main className="min-h-screen bg-white text-slate-900 antialiased">
+      {/* sections */}
+    </main>
+  );
+}
+```
+
+- `export default` is **one zero-prop React component** — the whole page. It owns the viewport: set the page background and text color on the root element (`min-h-screen bg-… text-…`).
+- `meta.title` (optional) becomes the browser tab title and the workspace card label. Default is the folder name.
+- `meta.description` (optional) becomes `<meta name="description">` in the exported HTML.
+- `meta.theme` (optional) marks the page as built from a theme under `themes/`. The id must match a `<id>.md` basename. Omit if not derived from a registered theme.
+- `meta.createdAt` is an **ISO 8601 string literal** set once when the page is scaffolded — **immediately before writing the file, run `node -e "console.log(new Date().toISOString())"` via Bash and paste the exact output**. Must stay a plain string literal (the framework reads it via regex, never by evaluating the module).
+- Hooks, state, event handlers, `fetch`, `window`, client-side routing: all allowed. This is a browser. See `references/interactivity.md` for the constraints that still apply (no `window` at module top level, StrictMode double-invokes effects).
+
+## Styling: Tailwind on `className`
+
+Write the HTML you already know — `main`, `header`, `nav`, `section`, `h1`–`h3`, `p`, `ul`/`li`, `button`, `a`, `form`, `table` — styled with **Tailwind v4 utilities via `className`**:
+
+```tsx
+<section className="mx-auto max-w-5xl px-6 py-20">
+  <h2 className="text-3xl font-bold tracking-tight">Pricing</h2>
+  <p className="mt-3 max-w-xl text-lg text-slate-600">Simple plans that grow with you.</p>
+</section>
+```
+
+- `className`, never a `tw` prop. Arbitrary values are fine (`text-[15px]`, `bg-[#0b0b10]`, `max-w-[72ch]`).
+- Responsive variants are the default tool: `grid sm:grid-cols-2 lg:grid-cols-3`. Mobile-first — unprefixed utilities are the mobile layout.
+- State variants for interactive elements: `hover:`, `focus-visible:`, `disabled:`, `aria-pressed:`.
+- Use inline `style={{ … }}` only for values Tailwind cannot express (computed positions, CSS variables from data).
+- A page may import its own stylesheet (`import './styles.css'`) for keyframes, complex selectors, or a font `@import`. Keep it small; utilities first.
+- Preflight (Tailwind's reset) is applied inside the page, so headings and buttons start unstyled — set sizes and weights explicitly.
+
+## Web type scale and color
+
+| Element | Size |
+| --- | --- |
+| Hero heading | 48–72px (`text-5xl`–`text-7xl`), tight leading + tracking |
+| Section heading | 24–36px (`text-2xl`–`text-4xl`) |
+| Body | 16–18px (`text-base`–`text-lg`), `leading-relaxed` |
+| Secondary / captions | 13–14px (`text-sm`), muted color |
+| Labels, eyebrows | 11–12px (`text-xs`), `uppercase tracking-widest` |
+
+- One page = one palette: a background, a text color, a muted text color, one accent, one border tint. Hold it for the whole page.
+- Contrast: body text must pass 4.5:1 against its background; muted text on dark backgrounds is `text-white/60`, not `text-white/30`.
+- Details in `references/typography-and-color.md`.
+
+## Data rows vs designed repeats
+
+- **Repeated data belongs in a `.map` over a data array** — pricing tiers, feature lists, testimonials pulled from a typed const at the top of the file; keep the row JSX in the map body. A comment on any row means "this row template".
+- **Designed repeats that differ (hero vs. secondary CTA, three distinct feature panels with custom art) are explicit instances** of a small helper component defined in the same file or under `components/`. The inspector targets source JSX; explicit instances give each block its own address, so "make the middle one green" is one edit, not three.
+
+## Editing an existing page
+
+Locate the section first instead of reading the whole file:
+
+```bash
+grep -n '<section\|<h[12]\|<header\|<footer' pages/<id>/index.tsx
+```
+
+Landmarks and headings anchor sections; read the target range with `offset` + `limit`. Read the whole file when auditing palette or restructuring.
+
+## Themes
+
+If `themes/<id>.md` exists and the page is meant to follow it, **the theme file overrides the defaults in this skill** — its palette, typography, and fixed components are authoritative. Read the theme before applying anything else here. Themes are produced by the `create-theme` skill.
+
+## Runtime behavior you get for free
+
+- Home lists every folder under `pages/`; cards show a live, scaled-down preview of the real page.
+- The page view at `http://localhost:5173/p/<id>` renders the page in an iframe with **Desktop / Tablet (820px) / Mobile (390px)** viewport toggles, a reload button, and **Open** (the page by itself in a new tab).
+- **Inspect mode** (toolbar button or `i`): the user clicks any element, sees its tag and source line, and can leave a comment that lands in your source as an `@page-comment` marker (see `apply-comments`). The current selection is always in `node_modules/.open-pages/current.json` (see `current-page`).
+- Hot reload: save any file under `pages/<id>/` and the preview updates in place.
+- `open-pages export <id>` builds `export/<id>/` — `index.html` plus hashed assets with relative URLs. Drop the folder on Netlify, Vercel, Cloudflare Pages, GitHub Pages, or S3.
+
+## Self-review before finishing
+
+- [ ] `pages/<id>/index.tsx` default-exports **one** component; `meta` has `title` + fresh `createdAt` literal.
+- [ ] Root element sets `min-h-screen`, background, and text color; the page has a `<main>` landmark.
+- [ ] Preview it at `http://localhost:5173/p/<id>` (or ask the user to). No error banner, no console errors.
+- [ ] Check the **Mobile** viewport: no horizontal overflow, nav collapses or wraps, grids stack, text sizes step down.
+- [ ] Every `className` is Tailwind v4 the scanner will see (literal strings, no runtime-concatenated utility names).
+- [ ] Interactive elements are real `<button>`/`<a>`/`<input>` elements with visible `focus-visible:` styles and labels; images have `alt`.
+- [ ] One coherent palette and type scale across the page; contrast holds on dark sections.
+- [ ] Designed repeats are explicit component instances; data lists are a `.map` over a typed const.
+- [ ] No `window`/`document` access at module top level; effects clean up.
+- [ ] Nothing outside `pages/<id>/` was edited.
+
+## Anti-patterns
+
+- ❌ `tw` props, `pageOptions`, fixed-size "page" `<div>`s, or any document/slide thinking. This is a scrolling web page.
+- ❌ Desktop-only layouts: absolute pixel positioning, fixed widths on the root, `grid-cols-3` with no `sm:` fallback.
+- ❌ Building class names at runtime (`` `text-${size}` ``) — Tailwind only generates utilities it can read literally. Map to full class strings instead.
+- ❌ `<div onClick>` where a `<button>` belongs; `<a>` without `href`; icon buttons without `aria-label`.
+- ❌ Tiny typography (11px body). Web body is 16px+.
+- ❌ Global CSS resets or `body {}` rules in `styles.css` that fight Preflight — style the root element instead.
+- ❌ Installing packages, editing `package.json`/config/other pages, adding a `README.md` to the page folder.

package/template/.agents/skills/page-authoring/references/assets-and-fonts.md

@@ -0,0 +1,85 @@
+# Assets and fonts
+
+Both images and fonts follow the same rule: put the file under
+`pages/<id>/assets/`, import it, and reference the imported value. Vite
+resolves the import to a URL in the preview and to a hashed file in the
+export.
+
+## Images
+
+```tsx
+import hero from './assets/hero.png';
+
+<img src={hero} alt="Dashboard showing the weekly brief" width={1200} height={720} className="w-full rounded-xl" />
+```
+
+- **Always give `width` and `height`** (intrinsic pixels) so the browser
+  reserves space and the layout does not shift while loading. Let CSS
+  (`w-full h-auto`) size it visually.
+- **Always give `alt`**: descriptive for content images, `alt=""` for purely
+  decorative ones.
+- Below-the-fold images: `loading="lazy"`. The hero image: eager, and keep it
+  reasonably sized (≤ 1600px wide, WebP or JPEG).
+- Page-local images live in `pages/<id>/assets/`; images shared across pages
+  live in the root `assets/` folder and import via `@assets/...`.
+- Inline `<svg>` for logos, icons, and simple illustrations — crisp at any
+  size and styleable with `fill-current`/`stroke-current`. Icon-only buttons
+  need `aria-label`.
+- Remote images (`https://…`) work but make the export depend on that host.
+  Prefer local files; ask the user for their assets rather than inventing
+  stock imagery.
+
+## Fonts
+
+The default is the system font stack — fast, no files, always correct.
+Register a font only when the user names one or supplies files.
+
+### Google Fonts
+
+Render the link tags at the top of the page component:
+
+```tsx
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
+/>
+```
+
+Then use it: `className="font-[Inter,ui-sans-serif,system-ui,sans-serif]"` on
+the root element, or in the page's `styles.css`:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&display=swap');
+```
+
+### Self-hosted
+
+```css
+/* pages/<id>/styles.css */
+@font-face {
+  font-family: 'Satoshi';
+  src: url('./assets/Satoshi-Variable.woff2') format('woff2');
+  font-weight: 300 900;
+  font-display: swap;
+}
+```
+
+`import './styles.css'` in `index.tsx`, then `font-[Satoshi,sans-serif]`.
+Always include a fallback family.
+
+## Favicons and `<head>`
+
+- `meta.title` and `meta.description` are written into the exported
+  `<head>`. Other head tags (favicon, Open Graph) are not supported yet; note
+  this to the user if they ask for them.
+
+## Anti-patterns
+
+- ❌ `<img>` without `alt`, or without `width`/`height`.
+- ❌ Multi-megapixel PNG screenshots as hero images.
+- ❌ `fontFamily` naming a font that was never loaded — it silently falls
+  back and the page looks nothing like the theme.
+- ❌ Loading four weights of two families for one heading.
+- ❌ Hotlinking images from someone else's site.

package/template/.agents/skills/page-authoring/references/html-pages.md

@@ -0,0 +1,65 @@
+# Plain HTML pages
+
+A page folder may hold an `index.html` instead of a React module. The
+workspace serves it as-is (through Vite, so scripts and styles are
+processed), the home card previews it live, and `open-pages export <id>`
+builds it into a static folder like any other page.
+
+## When to use it
+
+- The user hands you existing HTML/CSS/JS to host or tweak.
+- A tiny page where React is overhead: a one-screen announcement, a redirect
+  page, an embed target.
+- Prototypes that intentionally avoid a framework.
+
+For anything with real layout, state, or reuse, prefer `index.tsx`.
+
+## Contract
+
+```
+pages/<id>/
+  index.html     entry — must contain <title>
+  style.css      optional, referenced with a relative href
+  main.js        optional, referenced with a relative src (type="module" recommended)
+  assets/        images, fonts
+```
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Launch week</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <main>…</main>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>
+```
+
+- Reference siblings with **relative** URLs (`./style.css`, `./assets/logo.svg`,
+  `main.js`). Absolute paths (`/style.css`) do not resolve in the preview or
+  the export.
+- `<title>` is the card label in the workspace. There is no `meta` export;
+  the folder name is the page id.
+- If both `index.tsx` and `index.html` exist, the React entry wins and the
+  HTML is treated as a plain asset.
+- Tailwind is **not** wired into HTML pages. Write CSS, or use the React
+  entry when you want utilities.
+
+## What you do not get
+
+- No inspector, no click-to-comment, no `@page-comment` markers. Feedback on
+  an HTML page comes as plain requests; apply them by editing the file.
+- No hot module replacement for the HTML itself — the preview reloads the
+  frame on save. CSS and JS changes still hot-update.
+
+## Anti-patterns
+
+- ❌ Absolute or root-relative asset paths.
+- ❌ Inline `<script>` blobs of application logic — put them in `main.js`.
+- ❌ Reaching for `index.html` when the request is "a landing page with a
+  pricing toggle". That is a React page.