@open-aippt/cli 1.3.2

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

@@ -0,0 +1,250 @@
+---
+name: create-theme
+description: Use this skill when the user wants to create, draft, author, or extract a slide theme in this open-aippt repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <slide>", "build a theme from these images". Produces two paired files under `themes/` — `<id>.md` (palette, typography, layout, fixed Title/Footer components, motion) and `<id>.demo.tsx` (a runnable demo slide that the dev-UI Themes panel previews). Do NOT use for editing real slides — only for authoring the theme bundle.
+---
+
+# Create a slide theme
+
+This skill produces a **theme bundle** under `themes/`: two paired files that together describe a reusable visual identity.
+
+1. `themes/<id>.md` — agent-facing documentation: palette, typography, layout, fixed Title/Footer/Eyebrow components, motion. This is what `create-slide` reads when an author picks the theme.
+2. `themes/<id>.demo.tsx` — a runnable mini-slide (a normal slide module: `export default Page[]`) that demonstrates the theme on 2–3 pages. The dev UI's **Themes panel** loads this file and renders it as the theme's live preview.
+
+Both files share the same stem so the runtime can pair them automatically.
+
+A theme is **distinct from a slide's `design` const**. The theme markdown is authoring-time aesthetic direction (copied into a real slide's source by `create-slide`). The demo `.tsx` is a self-contained preview, not a real slide — it does not appear in the slides list. A per-slide `const design: DesignSystem = { … }` (declared at the top of `slides/<id>/index.tsx`) is the runtime tokens object the user can tweak from the Design panel. The markdown commits the *direction*; the per-slide `design` const makes the slide *tweakable*; the demo `.tsx` makes the theme *previewable*.
+
+You only write files under `themes/<id>.md` and `themes/<id>.demo.tsx`. Never modify real slides or other configuration. The canvas / type-scale defaults that themes can override live in the **`slide-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 slide screenshots, mood-board images, brand assets.
+- **Free-text description** — prose describing the desired palette, fonts, feel.
+- **An existing slide** — `slides/<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, slide 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/style, layout rhythm, decorative motifs, and any recurring chrome (header bar, footer line, page numbers).
+- **Text**: extract explicit tokens (hex codes, font names, motion verbs) and implicit tone words ("editorial", "playful", "brutalist"). Resolve vague language into concrete decisions before writing.
+- **Existing slide**: read `slides/<id>/index.tsx` and pull:
+  - The `palette` object → Palette section.
+  - Font constants and any `font-size` patterns → Typography section.
+  - Padding / alignment patterns → Layout section.
+  - Recurring components (TrafficLights, Eyebrow, Footer-style helpers, WindowShell, …) → Fixed components section.
+  - `@keyframes` blocks and the shared `styles` string → Motion section.
+  - The aesthetic feel implied by the design → 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: `editorial-noir`, `brutalist-mono`, `pastel-soft`, `dev-terminal`. 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. "Editorial Noir">
+description: <one-line elevator pitch>
+---
+
+# <Theme name>
+
+## Palette
+
+| Role   | Value     | Notes                          |
+| ------ | --------- | ------------------------------ |
+| bg     | `#0f172a` | page background                |
+| text   | `#f8fafc` | primary copy                   |
+| accent | `#fbbf24` | callouts, eyebrow, key numbers |
+| muted  | `#94a3b8` | secondary copy, dividers       |
+| ...    | ...       | extend as the theme requires   |
+
+## Typography
+
+- Display font: `<stack>` — weight 800–900 for headlines.
+- Body font: `<stack>` — weight 400–500.
+- Type-scale overrides (only list what differs from `slide-authoring` defaults):
+  - Hero title: 180 px (default 140–200 ✓)
+  - Body text: 36 px
+
+## Layout
+
+- Content padding: 120 px from canvas edges (1920 × 1080).
+- Alignment: left-aligned, single column.
+- Grid notes: optional 12-column overlay at 80 px gutter for content pages.
+
+## Fixed components
+
+These are paste-ready. Copy them verbatim into a slide that uses this theme.
+
+### Title
+
+```tsx
+const Title = ({ children }: { children: React.ReactNode }) => (
+  <h1
+    style={{
+      fontSize: 140,
+      fontWeight: 900,
+      lineHeight: 1.05,
+      letterSpacing: '-0.02em',
+      margin: 0,
+      color: '#f8fafc',
+    }}
+  >
+    {children}
+  </h1>
+);
+```
+
+### Footer
+
+Pull the page number from `useSlidePageNumber()` — never hardcode `pageNum` / `total` props.
+
+```tsx
+import { useSlidePageNumber } from '@open-aippt/core';
+
+const Footer = () => {
+  const { current, total } = useSlidePageNumber();
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 120,
+        right: 120,
+        bottom: 60,
+        display: 'flex',
+        justifyContent: 'space-between',
+        fontSize: 24,
+        color: '#94a3b8',
+      }}
+    >
+      <span>EDITORIAL NOIR · 2026</span>
+      <span>{current} / {total}</span>
+    </div>
+  );
+};
+```
+
+### Eyebrow / accents (optional)
+
+```tsx
+const Eyebrow = ({ children }: { children: React.ReactNode }) => (
+  <div style={{ fontSize: 26, letterSpacing: '0.2em', color: '#fbbf24' }}>
+    {children}
+  </div>
+);
+```
+
+## Motion
+
+- Philosophy: static / subtle / rich — pick one and explain in one sentence.
+- Reusable keyframes (paste-ready, only if the philosophy is subtle or rich):
+
+```css
+@keyframes fadeUp {
+  from { opacity: 0; transform: translateY(24px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+```
+
+## Aesthetic
+
+One paragraph. What it feels like, the references it draws on, what to avoid (e.g. "no rounded corners; no gradients; no decorative emoji"). Commit to a single direction — minimal, maximalist, editorial, retro, brutalist, soft/pastel, neon, paper/print.
+
+## Example usage
+
+```tsx
+const Cover: Page = () => (
+  <div style={{ width: '100%', height: '100%', background: '#0f172a', color: '#f8fafc', padding: 120, display: 'flex', flexDirection: 'column', justifyContent: 'center' }}>
+    <Eyebrow>CHAPTER 01</Eyebrow>
+    <Title>The Big Idea</Title>
+    <p style={{ fontSize: 36, color: '#94a3b8', maxWidth: 1200, marginTop: 32 }}>
+      A short subtitle that explains what this slide is about.
+    </p>
+    <Footer />
+  </div>
+);
+```
+````
+
+## Step 4b — Write `themes/<id>.demo.tsx`
+
+The demo is a normal slide module — same shape as `slides/<id>/index.tsx`, just sitting under `themes/` so the runtime knows it's preview-only. The dev-UI Themes panel imports it and renders it inside `SlideCanvas` (1920×1080).
+
+Contract:
+
+- `import { type Page, useSlidePageNumber } from '@open-aippt/core';`
+- Inline the **same** `Title`, `Footer`, `Eyebrow` components defined in the theme markdown — verbatim, no abstractions, no imports from elsewhere. The demo and the markdown must stay in lockstep so what the user sees in the panel matches what `create-slide` will paste into a real slide.
+- Export 2–3 `Page` components and a default array. Aim for: a Cover (Eyebrow + Title + subtitle), one Content page exercising body type + accent, and a Closer or "End" card. The "Example usage" block at the bottom of the markdown is a good starting point — extend it.
+- If the theme has runtime-tweakable tokens worth surfacing in the Design panel later, also `export const design: DesignSystem = {...}`.
+- No external assets, no `import` from `@/`, no slides-only helpers (e.g. `WindowShell` from a real slide). Demo files must be self-contained.
+
+Skeleton:
+
+```tsx
+import { type Page, useSlidePageNumber } from '@open-aippt/core';
+
+const Title = ({ children }: { children: React.ReactNode }) => (
+  // …same JSX as in themes/<id>.md
+);
+const Footer = () => {
+  const { current, total } = useSlidePageNumber();
+  // …
+};
+const Eyebrow = ({ children }: { children: React.ReactNode }) => (
+  // …
+);
+
+const Cover: Page = () => (
+  // …
+);
+const Content: Page = () => (
+  // …
+);
+const Closer: Page = () => (
+  // …
+);
+
+export default [Cover, Content, Closer];
+```
+
+## Step 5 — Self-review
+
+Run this checklist before finishing:
+
+- [ ] Palette covers `bg` / `text` / `accent` / `muted` at minimum, all as hex.
+- [ ] Type scale specifies hero, heading, body, caption sizes (or explicitly defers to `slide-authoring` defaults).
+- [ ] At least Title and Footer are defined as paste-ready React with concrete inline styles.
+- [ ] Motion section commits to one of static / subtle / rich.
+- [ ] Aesthetic paragraph names a single coherent direction.
+- [ ] Both files written: `themes/<id>.md` and `themes/<id>.demo.tsx`. No slide changes, no config changes.
+- [ ] Demo `.tsx` exports 2–3 pages and inlines the same Title/Footer/Eyebrow components defined in the markdown.
+- [ ] Demo opens cleanly in the **Themes** panel of the dev UI — re-checked by you only by reading the file (do not start a server).
+
+## Step 6 — Hand off
+
+Tell the user:
+
+- The theme id and the two file paths (`themes/<id>.md` + `themes/<id>.demo.tsx`).
+- That the demo will appear in the dev UI's **Themes** panel as a live card and detail view (HMR — no restart needed).
+- That `/create-slide` 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 slides — even to demonstrate the theme; 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.
+- ❌ Treating `themes/<id>.demo.tsx` as a real slide. It is preview-only and lives outside the slides list; never put it under `slides/`.
+- ❌ Importing from `@/` or any slide-specific helper inside the demo. The demo is self-contained.
+- ❌ Inventing palette / fonts when the user supplied images or an existing slide. Extract, don't fabricate.
+- ❌ Editing `slides/`, `packages/`, `package.json`, or `open-aippt.config.ts`.
+- ❌ Skipping the Fixed components section. Title and Footer are the most common reuse target — they must be paste-ready.

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

@@ -0,0 +1,110 @@
+---
+name: current-slide
+description: Resolve which slide, page, and (optionally) selected element the user is currently viewing in the open-aippt dev server. Consult this whenever the user references "this page", "this slide", "this element", "the slide I'm on", "the current page", or any deictic reference to slide content without naming it. Re-read `node_modules/.open-aippt/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 slide I'm looking at", they almost never name the slide id, page number, or element — they mean wherever they are in the dev viewer. Before asking "which slide?" 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 slides, 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 slide 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 slide or picked a different element. Trusting your last read here will silently edit the wrong file. Re-read, compare `slideId` / `pageIndex` / `selection` against what you used last time, and act on the new values.
+
+## How to read it
+
+```
+node_modules/.open-aippt/current.json
+```
+
+Path is relative to the project root (the user's `cwd`, the directory that contains `slides/` and `package.json`). Use the `Read` tool. The file is JSON.
+
+## What you get
+
+```json
+{
+  "slideId": "q2-roadmap",
+  "pageIndex": 2,
+  "pageNumber": 3,
+  "totalPages": 8,
+  "slideTitle": "Q2 Roadmap",
+  "view": "slides",
+  "pagePath": "slides/q2-roadmap/index.tsx",
+  "selection": {
+    "line": 42,
+    "column": 6,
+    "tagName": "h1",
+    "text": "Q2 Roadmap"
+  },
+  "updatedAt": "2026-05-09T14:32:11.123Z"
+}
+```
+
+- `slideId` — folder name under `slides/`. Use as-is for any `/__slides/<id>/...` API or as the URL segment.
+- `pageIndex` — 0-based, for use with the page array in `index.tsx` (`export default [Cover, Body, ...]`).
+- `pageNumber` — 1-based, for use in messages to the user ("page 3 of 8") and for the URL `?p=N`.
+- `pagePath` — relative path to the slide source. Hand straight to `Read` / `Edit`.
+- `view` — `"slides"` (canvas view) or `"assets"` (asset manager). If `"assets"`, the user is browsing files for that slide rather than viewing a page.
+- `selection` — `null` if nothing is selected. Otherwise, the JSX element the user picked in the inspector overlay:
+  - `line` (1-indexed) and `column` (0-indexed) point to the JSX opening tag inside `pagePath`. This is the canonical handle — match against the source line, not the rendered DOM.
+  - `tagName` is the rendered DOM tag, lowercased (`"h1"`, `"div"`, `"img"`).
+  - `text` is a trimmed text snippet (≤120 chars) from the element's `textContent`, useful as a sanity check that you're looking at the right node.
+  - Selection auto-clears whenever the user navigates to a different slide or page.
+- `updatedAt` — ISO timestamp of the last navigation or selection change. Use it to detect staleness.
+
+## When to use this
+
+- The user references the current slide/page deictically: "this", "here", "the page I'm on", "the slide 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 slide?" or "which element?" as a clarifying question — check this file first.
+- Before guessing from `git log`, recently-edited files, or the most recent slide folder.
+
+## When NOT to use this
+
+- The user names a slide explicitly ("edit `q2-roadmap`") — use that name directly.
+- The `apply-comments` workflow already finds the right file via `@slide-comment` markers; it doesn't need this skill.
+- For listing or discovering slides — read `slides/` 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, or older than your last interaction with the user**: 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 slide 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 `slideId` / `pageIndex` / `selection` without asking.
+
+## When the file is missing
+
+- The dev server hasn't been opened on a slide yet, or has never run.
+- Don't create the file or guess. Ask the user which slide they mean, or suggest they open the slide in the dev server first.
+
+## Example — page-level reference
+
+User: "tighten the spacing on this page"
+
+1. Read `node_modules/.open-aippt/current.json`.
+2. Check `updatedAt` is recent.
+3. Read `pagePath` (e.g. `slides/q2-roadmap/index.tsx`).
+4. Identify the page at `pageIndex` in the default-exported array.
+5. Consult the `slide-authoring` skill for spacing rules, then edit that page in place.
+
+If `current.json` is missing or stale, ask: "Which slide and 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-aippt/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 `slide-authoring` for type-scale and layout rules before editing.
+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.