--- name: preview description: Create an interactive HTML preview of any proposal, plan, idea, doc, brief, or spec and land it in the browsable local Preview Library by default (opens under file:// with a catalog sidebar and in-page comments); an explicitly temporary ask produces one self-contained HTML on the Desktop instead, and only an explicit request for Vercel, online deployment, cross-device access, or external sharing publishes the private Vercel Library or an isolated Share deployment. Use WHENEVER the user wants something visualized, made into a webpage, made interactive, shared for human review, or asks for charts / diagrams / calculators they can click through. ALWAYS use this skill for - make a preview / give me a preview / turn this into a webpage / visualize this / make it interactive / do a review / share for review / make a calculator page / make me a chart / make me a diagram / render this as HTML / make this reviewable / build a quick page / interactive proposal. Preferred over a markdown wall of text for human review. --- # preview ## Delivery mode gate This is the first action. Decide the delivery mode **before** reading Preview Library config, running Vercel preflight/setup, creating files, using the network, or making any other state change: - Choose `vercel` only when the user explicitly asks for **Vercel**, an **online deployment**, **cross-device access**, or **external sharing**. - Choose `ephemeral` only for explicitly temporary work — "quick look", "看完就丟", "just drop it on my Desktop" — or when the user names the output path themselves. - Choose `library` for everything else. `library` is the default; a request such as "give me a link" still means a clickable local `file://` link. Misrouting is asymmetric — a real deliverable sent to a throwaway file is lost after the look, while a throwaway in the Library is one extra catalog row — so ambiguity always lands in the Library. Run the side-effect-free resolver from this skill directory with no argument for `library`, or with exactly one flag for the explicit intents above: ```bash node scripts/resolve-delivery.mjs [--ephemeral | --vercel] ``` Follow only the workflow it prints. On a Codex host (`CODEX_THREAD_ID` set), `--vercel` fails closed before any network or state change. Stop immediately, repeat the resolver's Codex Phase 1 local-only limitation, and do not substitute a local artifact for the explicitly requested deployment. Claude Code may continue through the existing Vercel workflow. `library` and `ephemeral` are pure local file operations, available on Claude Code and Codex alike. Turn any proposal / plan / idea into interactive HTML and hand the user a link they can open. Library delivery writes into the content root and returns a `file://` link into the freshly rebuilt local library. Explicit remote delivery publishes the existing private Library; an external one-off link uses Share (same Vercel project, Preview environment only — never promotes Library production). ## Outcome the user is looking for A link they can open and try. Not a markdown wall and not a screenshot. Library delivery returns an absolute `file://` Markdown link to the item's built page (catalog sidebar included). Ephemeral delivery returns an absolute-path link to one standalone file. Explicit Vercel delivery returns the existing Library or Share URL. ## Library workflow (default) This workflow is available on Claude Code and Codex and is the default. Deep reference (schema, setup, deploy internals): `../../shared/config.md`, relative to this skill inside an installed package (canonical source: `src/solopreneur/shared/config.md`). ### 1. Resolve Library config Config is **path-scoped**, not git-remote-scoped. From the content path (or cwd when creating new work), walk up for the nearest **`.solopreneur.json`** that contains a `preview` block. Full resolution order and rules: `config-resolve.mjs` / `shared/config.md`. ```bash # Inspect what the tools will use (anchor at the content path or cwd) node scripts/config-resolve.mjs --from "$CONTENT_OR_CWD" # see script --help for flags ``` - Relative `root` is resolved against the **config file's directory**, not git root. - Nested `.solopreneur.json` fully replaces a parent `preview` block (no deep merge). - **Never hardcode** project names like personal fleet projects in this skill. Examples use placeholders only (`my-private-previews`). **No v2 config resolves** (mode `none` or `legacy`): library mode is unavailable here — say so in one line and deliver through the Ephemeral workflow instead. Creating a new content root stays an explicit setup action (`setup.mjs`, Vercel-oriented — **do not invent projects** or silently create roots). Legacy `solopreneur.json` cascades still work for the escape hatch; prefer migrating with `config-migrate.mjs` when the user is ready, and never silently rewrite their legacy file. ### 2. Decide content + create / update item **Self-assess ambiguity** before writing: only ask which deliverable if ≥2 separable topics, bare "preview" after a wide discussion, or multiple candidate artifacts. Otherwise state what you are previewing in one line and proceed. #### Layout (v2) ```text / # preview.root from resolved config ├── active// │ ├── index.html │ ├── preview.json │ └── …assets (relative only) ├── archive// │ └── … └── library/ # generated local library (gitignored, never edited) ``` - **New work** → `active//` with `index.html` + `preview.json`. - **Same work continues** → **same `id`**, same directory. When content or display metadata actually changes: `revision` += 1, refresh `updatedAt` and `provenance.lastUpdatedBy`. Unchanged re-publish and Share do **not** bump revision. - `id`: lowercase slug `[a-z0-9-]+`, unique across all included collections. - Collection is the **directory** (`active` vs `archive`); do not duplicate status in metadata. #### Update routing / duplicate guard Prefer, in order: preview id from URL / Share or archive request → caller-given id → `sourceRef` in metadata. Title similarity alone never auto-merges. Same id or same `sourceRef` → treat as update candidate. Fork only when the user says so. #### `preview.json` (required fields) Write a sidecar in the Library source tree only — **never deploy raw `preview.json`**; the builder projects an allowlist into `directory.json`: ```json { "schemaVersion": 1, "id": "2026-07-25-short-slug", "title": "Human title", "createdAt": "2026-07-25T10:00:00+08:00", "updatedAt": "2026-07-25T12:00:00+08:00", "revision": 1, "entry": "index.html", "provenance": { "createdBy": { "agent": "Builder Claude", "platform": "claude", "sessionTitle": "optional" }, "lastUpdatedBy": { "agent": "Builder Claude", "platform": "claude", "sessionTitle": "optional" } } } ``` - Required: `id`, `title`, `createdAt`, `updatedAt`, `revision`, and provenance parties' `agent` + `platform`. - `sessionTitle` only when known — **never invent**. - Optional: `project` (label only), `sourceRef` (workspace-relative stable ref, not absolute paths), `tags`. - `entry` v1 must be `index.html`. - Schema: `scripts/preview-schema.json`. ### 3. Write HTML Start from `assets/template.html` (placeholders `{{TITLE}}` / `{{DATE}}` / `{{LEAD_PARAGRAPH}}` / `{{AUTHOR_OR_CONTEXT}}`). **The builds inject** shared `comment-overlay.js` and `preview-shell.js` — the local library build and the Vercel publish alike. You may still reference `./comment-overlay.js` in the template for raw-source review; the builder rewrites it to the shared asset. Prefer not treating per-item overlay copies as the durable happy path. **Contract (v1 static):** single `index.html`, relative assets only. No root-relative `/assets/...`, no SPA history fallback, no entry outside the item dir. Read `references/libs.md` before Alpine / Chart.js / Mermaid. **Form follows content** (calculator, doc, charts, etc.) — same guidance as before. **Full-bleed slides:** wrap in `
`, set `body.cmt-full-bleed` when needed (see template comments). ### 4. Build the local library After content is ready (and preferably committed when the content root is git-backed): ```bash node scripts/build-library.mjs --local --from "$PATH_UNDER_ROOT" # machine-readable: node scripts/build-library.mjs --local --json --from "$PATH_UNDER_ROOT" ``` - Rebuilds the whole catalog in a temporary tree and swaps it into `/library/` — generated output, never edited, never committed. A failed build leaves the previous library untouched, and re-running is the recovery. Concurrent builds of one root are serialized by a lock; if a build was hard-killed, the next one refuses to start and names the stale lock file to delete. - First run on a root appends `/library/` + `/library.*` to the content root's `.gitignore` and reports it — commit those lines with the content. The glob covers the build's swap siblings (`library.tmp`, `library.bak`, `library.lock`); untracked build output would otherwise dirty the root and trip the deploy fetch-guard. - The built pages render under `file://` with the full Library UX: catalog sidebar, provenance footer, comment overlay. Comments persist per item in that browser's `localStorage` (this machine only — export markdown if they matter elsewhere). - Return a clickable Markdown link to the item's built page: `[Open preview](file:///…//library/p//index.html)` — and mention the library home `/library/index.html` when useful. Run `open` only when the user explicitly asks. - **Active-length hint:** if Active has **≥ 15** items (or many look clearly stale), mention once that the user can open the sidebar **Manage mode**, multi-select, and copy archive instructions — **never block** the build. ### 5. Archive / restore (from Manage mode) Sidebar **Manage mode** copies a structured block (agent contract): ```text ## library archive request library: