@open-press/cli 0.3.0

package/template/skills/editorial-monograph/starter/document/theme/tokens.css

@@ -0,0 +1,80 @@
+:root {
+  /* 深色 chrome（navbar / sidebar / app background） */
+  --openpress-color-app-bg: #161616;
+  --openpress-color-border-subtle: #393939;
+  --openpress-color-border-strong: #6f6f6f;
+  --openpress-color-text-on-dark: #f4f4f4;
+  --openpress-color-text-secondary: #c6c6c6;
+  --openpress-color-text-placeholder: #8d8d8d;
+  --openpress-color-focus: #0f62fe;
+
+  /* 文件本身（白底文件、墨色內文） */
+  --openpress-color-document: #ffffff;
+  --openpress-color-ink: #161616;
+  --openpress-color-muted: #6f6f6f;
+  --openpress-color-line: #e0e0e0;
+  --openpress-color-soft-line: #f4f4f4;
+
+  /* 表格狀態符號 */
+  --openpress-color-green: #24a148;
+
+  /* 圖表 palette(柔和暖色系)
+   * 用於 data-foundation、milestone-roadmap、cost-donut、revenue-line-chart 等元件。
+   * 排序由淺到深,可以對應 phase / tier 的進階感:
+   *   gold (起始 / current) → coral (中期) → coral-deep (後期) → dark (anchor / 成熟)
+   */
+  --openpress-chart-gold: #FFB000;
+  --openpress-chart-coral: #FF6A4D;
+  --openpress-chart-coral-deep: #C9522B;
+  --openpress-chart-dark: #1F2328;
+  --openpress-chart-cream: #FFF3DB;
+  --openpress-chart-warm-gray: #B0A89A;
+
+  /* 對應的背景 tint(較飽和、用於 phase / tier 卡片) */
+  --openpress-chart-gold-bg: rgba(255, 176, 0, 0.20);
+  --openpress-chart-coral-bg: rgba(255, 106, 77, 0.16);
+  --openpress-chart-coral-deep-bg: rgba(201, 82, 43, 0.14);
+  --openpress-chart-dark-bg: rgba(31, 35, 40, 0.09);
+
+  /* 對應的中等飽和邊框色(配合 background tint) */
+  --openpress-chart-gold-border: rgba(255, 176, 0, 0.55);
+  --openpress-chart-coral-border: rgba(255, 106, 77, 0.5);
+  --openpress-chart-coral-deep-border: rgba(201, 82, 43, 0.42);
+  --openpress-chart-dark-border: rgba(31, 35, 40, 0.28);
+
+  /* Status — 文件內行內語意強調色（warn / success / info），
+   * 用於 <span class="status-warn|status-success|status-info">。
+   * 避免按色相命名（accent-gold 之類）以強制走語意。 */
+  --openpress-status-warn: #C9522B;
+  --openpress-status-success: #5C8C4F;
+  --openpress-status-info: #4A6B8A;
+
+  /* 字型 */
+  --openpress-font-body: "IBM Plex Sans", "PingFang TC", "Noto Sans TC", "Hiragino Sans", "Microsoft JhengHei", sans-serif;
+  --openpress-font-serif: "Noto Serif TC", "Songti TC", "Source Han Serif TC", "PMingLiU", serif;
+  --openpress-font-mono: "SFMono-Regular", "Menlo", "Consolas", monospace;
+
+  /* 字級（固定 pt 用於小元素；標題改用 container queries 算） */
+  --openpress-text-sm: 9.5pt;
+  --openpress-text-md: 10.5pt;
+
+  /* 行距 */
+  --openpress-leading-body: 1.72;
+  --openpress-leading-table: 1.45;
+
+  /* 間距系統（mm 為主、適合 print 與 A4 視覺節奏） */
+  --openpress-space-1: 2mm;
+  --openpress-space-2: 4mm;
+  --openpress-space-3: 6mm;
+  --openpress-space-4: 9mm;
+  --openpress-space-5: 13mm;
+
+  /* Page geometry — A4 預設。
+   * 換成 B5 / Letter / 16:9 投影片時改這三條，其他 CSS 與 page-contract `@page`
+   * 都會跟著走。注意：@page size 改用 length pair 時，PDF 與瀏覽器 print 都會吃。 */
+  --openpress-page-width: 210mm;
+  --openpress-page-height: 297mm;
+  --openpress-page-aspect-ratio: 210 / 297;
+  --openpress-page-height-ratio: calc(297 / 210);
+  --openpress-page-margin: 18mm;
+}

package/template/skills/editorial-monograph/starter/openpress.config.mjs

@@ -0,0 +1,5 @@
+// editorial-monograph starter — root marker for a nested React/MDX open-press workspace.
+export default {
+  documentDir: "document",
+  config: "document/openpress.config.mjs",
+};

package/template/skills/openpress/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openpress
+description: Use when operating a open-press workspace or framework checkout through CLI commands, discovering project status, validating/exporting/rendering/PDF output, inspecting structure/issues, searching or safely replacing source text, managing pending @openpress-comment markers, or deciding which open-press skill owns a task.
+---
+
+# open-press Core
+
+open-press owns the tool surface and delivery boundaries. **Use this skill first** when the task involves the CLI, workspace status, generated output, or deciding which specialist skill should take over.
+
+This skill is also the **single source of truth** for the source vs generated boundary. Other skills reference this section instead of re-listing paths.
+
+## Responsibilities
+
+- Choose safe open-press CLI commands.
+- Define the canonical source vs framework vs generated path boundary (see below).
+- Inspect workspace state before broad edits.
+- Open and manage the local workbench review loop.
+- Manage `@openpress-comment` markers (list, apply, resolve, clear).
+- Route domain work to the owning skill.
+- Require verification before declaring output ready.
+
+## Skill Routing
+
+open-press skills fall into three categories:
+
+1. **System operation skills**: how to operate open-press itself. `openpress` is the main entry point; lifecycle helpers cover init, update, and deploy.
+2. **Writing skills**: content strategy, suggested skeletons, language, tone, genre rules. They do not own CLI commands or validation depth.
+3. **Style pack skills**: reusable visual starters under `skills/<pack>/starter/`. They do not own workspace operation.
+
+| Skill | Owns |
+| --- | --- |
+| `openpress` | CLI, inspect/search/replace, source/generated boundary, validation/export/render/PDF command choice, `@openpress-comment` operations, skill routing |
+| `openpress-init` | First-time intake conversation, style-pack recommendation, metadata gathering, running `init`, handing off to writing/design |
+| `openpress-update` | Release upgrade flow: pulling new framework, CHANGELOG-driven migrations, post-upgrade verification |
+| `openpress-writing` | Reader-facing content, narrative, captions, factual boundaries, portable writing skill loading |
+| `openpress-document-hierarchy` | H1/H2/H3/H4 model, TOC depth, reader outline, appendix placement |
+| `openpress-design` | Workspace visual system: `document/theme/`, `document/components/`, PDF-safe layout |
+| `openpress-diagram-drawing` | Diagram semantics: nodes, arrows, labels, states, figure text |
+| `openpress-deploy` | Deploy config, preflight, dry run, public publish confirmation |
+| `openpress-style-pack-contributor` | Bundled packs under `skills/<pack>/starter/` (the upstream design, not workspace consumption) |
+| Portable writing skills (`chinese-ai-writing-polish`, `teaching-notes-writing`, …) | Language, tone, genre, learner-facing rules. Loaded via `openpress-writing` |
+
+## Source Boundary (canonical)
+
+Edit source, not generated output. **This list is the single authoritative version**; other skills link here.
+
+| Layer | Paths | Edit? |
+| --- | --- | --- |
+| Workspace source | `openpress.config.mjs`, `document/index.tsx`, `document/chapters/`, `document/design.md`, `document/theme/`, `document/components/`, `document/media/` | yes — domain skills |
+| Skill / pack source | `skills/<pack>/SKILL.md`, `skills/<pack>/starter/**`, other skill files under `skills/` | yes — `openpress-style-pack-contributor` for packs; skill maintainers for own skill |
+| Framework | `engine/`, `src/`, `tests/`, `docs/superpowers/`, `vite.config.ts`, `tsconfig.json`, `index.html` | yes — framework agents only |
+| Generated | `public/openpress/`, `dist-react/`, `.deploy/`, `.openpress/` | **never hand-edit** |
+
+If a workspace lacks `document/index.tsx`, run `node engine/cli.mjs migrate-to-react` before broad structural rewrites.
+
+If `memory/AGENTS.md` exists, read it before framework-level `AGENTS.md`; it usually marks a downstream document workspace where `document/` is git-ignored project content, not source you commit upstream.
+
+## Workflow
+
+1. Orient: read `AGENTS.md`, `memory/AGENTS.md` if present, and the relevant specialist skill.
+2. Inspect before broad edits with `inspect --json`, `search --json`, or `rg`.
+3. Route domain work to the owning skill instead of duplicating its rules.
+4. Edit only source paths in the owning area (see boundary table).
+5. Verify with the narrowest command that proves the claim.
+
+## Starting A New Workspace
+
+Route to `openpress-init` for the intake conversation. The CLI itself is:
+
+```bash
+node engine/cli.mjs init <target> --skill <pack-name>
+```
+
+Style packs are auto-discovered from `skills/<pack>/SKILL.md` where `starter/` exists.
+
+## Updating An Existing Workspace
+
+Route to `openpress-update` for release-driven upgrades.
+
+## @openpress-comment Operations
+
+Pending `@openpress-comment` markers are source markers, not UI-only notes. Apply them as small source edits close to the marker, then remove the marker only after the comment is resolved or explicitly cleared.
+
+Scope:
+
+- List, apply, resolve, clear markers.
+- Edit only the source file containing the marker (paths follow the Source Boundary table above).
+- Route domain-heavy rewrites to the owning skill (writing / hierarchy / design / diagram).
+- Do not rewrite unrelated sections while resolving one comment.
+
+Operations:
+
+| Need | Action |
+| --- | --- |
+| See pending comments | `rg "@openpress-comment" document -n` |
+| Apply one comment | Edit nearby source, then delete that marker line |
+| Clear one without applying | Delete that marker line only after the user asks |
+| Clear all comments | Use the comments tab or delete all marker lines only after explicit confirmation |
+| Comment is ambiguous | Ask for clarification and leave the marker in place |
+
+After applying, run `npm run openpress:validate`; also run `npm run openpress:render` when layout, visual output, or React/MDX structure changed.
+
+Common mistakes: do not clear a marker just because it was read; do not batch unrelated rewrites under one comment.
+
+## When To Read References
+
+- Read `references/cli-commands.md` when choosing commands, using search/replace, or explaining verification depth.
+- Read `references/local-review.md` when opening the workbench, using Document/Design System/Project views, or coordinating visual review before export/deploy.
+
+## Safety Rules
+
+- Preview broad replacements before applying them.
+- Do not publish without explicit user confirmation naming the target (handled by `openpress-deploy`).
+- Do not claim render, PDF, or deploy readiness without fresh command output.

package/template/skills/openpress/references/cli-commands.md

@@ -0,0 +1,31 @@
+# open-press CLI Commands
+
+Prefer package scripts in the framework checkout. Use direct `node engine/cli.mjs ...` when a downstream workspace lacks scripts or when a command has no script wrapper.
+
+| Need | Command |
+| --- | --- |
+| Top-level usage | `node engine/cli.mjs --help` |
+| Migrate legacy Markdown workspace to React/MDX | `node engine/cli.mjs migrate-to-react . --dry-run` |
+| Validate structure and delivery gates | `npm run openpress:validate` |
+| Export source to open-press JSON | `npm run openpress:export` |
+| Build React reader | `npm run openpress:render` |
+| Open local workbench | `npm run dev` |
+| Preview production build | `npm run openpress:preview` |
+| Generate PDF | `npm run openpress:pdf` |
+| Inspect structure/issues as JSON | `node engine/cli.mjs inspect . --json` |
+| Search public source text | `node engine/cli.mjs search . "<query>" --json` |
+| Search all workspace source classes | `node engine/cli.mjs search . "<query>" --json --scope all` |
+| List pending inspector comments | `rg "@openpress-comment" document -n` |
+| Preview replacement without writing | `node engine/cli.mjs replace . "<from>" "<to>" --json` |
+| Apply replacement after preview | `node engine/cli.mjs replace . "<from>" "<to>" --apply` |
+| Dry-run deploy workflow | `npm run openpress:deploy:dry-run` |
+| Publish after confirmation | use `openpress-deploy` |
+
+Command notes:
+
+- `search` and `replace` default to `--scope content`.
+- Add `--scope all` to also include `document/design.md`, component, media, and theme source.
+- Add `--case-sensitive` only when casing matters.
+- `replace` previews by default and writes only with `--apply`.
+- `replace` does not touch code blocks unless `--include-code` is provided.
+- Per-command `--help` is not implemented yet; use top-level usage and command error messages.

package/template/skills/openpress/references/local-review.md

@@ -0,0 +1,43 @@
+# Local Review
+
+open-press local review is the human feedback loop before PDF or public deploy.
+
+## Workflow
+
+```bash
+npm run openpress:export
+npm run dev
+```
+
+Use the URL printed by Vite. It is usually:
+
+```txt
+http://127.0.0.1:5173/?dev=1
+```
+
+If `5173` is occupied, use the fallback port reported by the dev server.
+
+## Workbench Views
+
+- **Document**: reader-facing document.
+- **Design System**: visual rules and specimens.
+- **Project**: source inventory, components, media, and status.
+
+After source edits:
+
+```bash
+npm run openpress:export
+npm run openpress:validate
+```
+
+For renderer-sensitive visual, bookmark, or layout changes, also run:
+
+```bash
+npm run openpress:render
+```
+
+## Safety Rules
+
+- A local preview is not deploy approval.
+- Do not hand-edit generated output to fix preview issues.
+- If preview is blank or stale, inspect export status, dev server output, and browser console before changing source content.

package/template/skills/openpress-deploy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: openpress-deploy
+description: Use when preparing, configuring, checking, staging, or publishing a open-press document to public hosting, especially Cloudflare Pages, deploy setup, deploy buttons, deploy status, public release checks, or safe deployment workflow.
+---
+
+# open-press Deploy
+
+open-press deploy owns the public-release gate. Use it only when the user asks to configure, inspect, dry-run, or publish a open-press document.
+
+## Responsibilities
+
+- Inspect deploy config in `openpress.config.mjs`.
+- Check target adapter, staging source, project name, and confirmation settings.
+- Run deploy preflight and dry runs.
+- Keep secrets out of source files.
+- Require explicit confirmation before publishing.
+- Report public URL and PDF URL after successful deploy.
+
+## Boundaries
+
+- `openpress` owns generic CLI usage, non-deploy validation, local review, and the source/generated boundary.
+- `openpress-writing` and `openpress-design` own document content and visual readiness.
+- This skill owns public target confirmation and deploy execution.
+
+## Public Deploy Rule
+
+Never publish without a clear confirmation that names the target project.
+
+Good confirmation shape:
+
+```txt
+This will publish the current open-press build to Cloudflare Pages project `<projectName>` from `<deploy.source>`.
+Do you want me to deploy now?
+```
+
+## Preflight
+
+Before real deploy, run the commands that prove the output is ready:
+
+```bash
+npm run openpress:export
+npm run openpress:validate
+npm run openpress:render
+npm run openpress:pdf
+```
+
+Also scan public-facing source for unfinished markers:
+
+```bash
+rg "\\[TODO:|\\[FIX:|\\[DRAFT:" document/chapters document/design.md
+```
+
+## Deploy Commands
+
+Dry run:
+
+```bash
+npm run openpress:deploy:dry-run
+```
+
+Publish after explicit confirmation:
+
+```bash
+npm run openpress:deploy -- --confirm
+```
+
+## When To Read References
+
+- Read `references/cloudflare-pages.md` when creating or repairing Cloudflare Pages config, project setup, Wrangler auth expectations, or UI deploy-button behavior.

package/template/skills/openpress-deploy/references/cloudflare-pages.md

@@ -0,0 +1,51 @@
+# Cloudflare Pages Deploy
+
+## Config Shape
+
+Write confirmed deploy settings into `openpress.config.mjs`:
+
+```js
+deploy: {
+  adapter: "cloudflare-pages",
+  source: ".deploy/<name>",
+  projectName: "<cloudflare-pages-project>",
+  commitDirty: false,
+  requiresConfirmation: true,
+}
+```
+
+Prefer an explicit `deploy.projectName`. If it is missing, ask the user to confirm the project name before writing config or creating a Cloudflare Pages project.
+
+## Setup Workflow
+
+1. Discover the workspace and load open-press config.
+2. Confirm the document is intended for public hosting.
+3. Inspect deploy config and derive the target:
+   - use explicit `deploy.projectName`;
+   - otherwise use a user-confirmed slug;
+   - do not invent and write a public target silently.
+4. Ask whether to create a new Cloudflare Pages project or use an existing one.
+5. Verify Wrangler auth outside source control.
+6. Run dry run before real deploy.
+
+If creating a new project, ask before running:
+
+```bash
+npx wrangler pages project create <projectName> --production-branch main
+```
+
+## Secrets
+
+Do not write API tokens or secrets into open-press config, Markdown, `design.md`, or skill files.
+
+## UI Deploy Button Contract
+
+A UI deploy button is a review surface over the CLI workflow. It should:
+
+- show target, source, and status before publishing;
+- block when `deploy.projectName` is missing;
+- require confirmation before posting to the deploy endpoint;
+- call the same CLI-backed deploy path;
+- show success URL, PDF URL, failure output, and dirty status.
+
+It must not create a second hidden deployment behavior.

package/template/skills/openpress-design/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: openpress-design
+description: Use when designing or revising open-press visual systems, page rhythm, print/PDF-safe CSS, figure/table/chart presentation, covers, style packs, or document component recipes.
+---
+
+# open-press Design
+
+open-press design owns the **workspace visual system** — the CSS and components that live in a user's `document/` after a pack has been initialized. It decides how the document looks while keeping fixed-layout, mobile, and PDF output stable.
+
+## Responsibilities
+
+- Choose typography, color, spacing, page rhythm, covers, figures, tables, and chart treatment.
+- Edit `document/theme/`, `document/design.md`, and `document/components/` in a workspace.
+- Decide when dense prose should become a reusable visual component.
+- Keep `document/design.md` public-readable so users and agents can review the same rules.
+- Preserve React reader output as the public reading surface; PDF is an export artifact.
+
+## Boundaries (by path, not by topic)
+
+| Path | Owner |
+| --- | --- |
+| `document/theme/`, `document/components/`, `document/design.md` (workspace) | **this skill** |
+| `skills/<pack>/starter/document/theme/`, `…/components/`, `…/design.md` (upstream pack) | `openpress-style-pack-contributor` |
+| `engine/`, `src/` (framework rendering) | framework agents only |
+
+Other domain skills:
+
+- `openpress-writing` owns claims, prose, audience, and captions as language.
+- `openpress-diagram-drawing` owns diagram semantics; this skill owns visual skin.
+- `openpress-deploy` owns public release.
+
+Source paths follow `openpress` > Source Boundary.
+
+## Hard Rules
+
+- Avoid uncontrolled overflow into headers, footers, or fixed pages.
+- Do not depend on local-only fonts when public, iPad, or PDF-stable output matters.
+- Keep page-surface CSS, generic patterns, and component CSS in their owning layers.
+
+## Workflow
+
+1. Read `document/design.md` before changing theme or components.
+2. Edit source CSS/components only (see `openpress` > Source Boundary).
+3. Use `openpress` to choose validation depth.
+4. For renderer-sensitive changes, ask `openpress` which render/inspect/local-review verification is needed before declaring the design ready.
+
+## When To Read References
+
+- Read `references/theme-and-components.md` before moving CSS layers, extracting components, changing `document/design.md`, or localizing page-surface defaults.
+- Read `references/pdf-safe-css.md` before changing fixed page geometry, print behavior, or overflow-sensitive CSS.
+- Read `references/responsive-fixed-layout.md` before changing mobile, tablet, zoom, spread, or responsive behavior.

package/template/skills/openpress-design/references/pdf-safe-css.md

@@ -0,0 +1,29 @@
+# PDF-Safe CSS Notes
+
+Use this reference when editing open-press CSS that affects fixed pages, PDF output, or renderer stability.
+
+## Prefer
+
+- fixed page geometry;
+- container-relative type scales;
+- explicit image dimensions or max dimensions;
+- `break-inside: avoid` only for blocks that must stay together;
+- table and figure captions outside the media object;
+- CSS variables for theme values.
+
+## Avoid
+
+- viewport-width type for fixed-format content;
+- uncontrolled `position: absolute` near footer/header;
+- large nested cards;
+- transform-based layout where measurement matters;
+- SVG text for document copy unless the visual must be one fixed asset;
+- mobile RWD changes that alter canonical PDF layout.
+
+## PDF Export
+
+PDF output is an export artifact. Do not embed the browser's built-in PDF viewer as the primary open-press reading surface; it introduces a second toolbar, second page model, and inconsistent navigation. The deployed reader should remain open-press-owned DOM.
+
+## Design Skill Boundary
+
+PDF-safe does not mean visually conservative. It means the chosen design must survive measurement, pagination, and rendering.

package/template/skills/openpress-design/references/responsive-fixed-layout.md

@@ -0,0 +1,48 @@
+# Responsive Fixed-Layout Notes
+
+Use this reference when editing open-press styles that affect mobile, tablet, zoom, spread mode, or responsive behavior.
+
+## Core Principle
+
+open-press pages have canonical page geometry. Responsive behavior should scale the page and surrounding workspace, not re-author the document for every viewport.
+
+A deployed open-press reader should stay DOM-rendered and open-press-owned. Do not embed the browser PDF viewer to solve responsive problems; that adds a second reader UI and breaks the intended workspace model.
+
+## Page Rules
+
+- Keep one canonical width/height ratio for each page.
+- Use CSS variables for page dimensions and derive scale from the available stage size.
+- On narrow viewports, show one page at a time and scale the page down.
+- On wide viewports, spread mode may show two pages if both fit without clipping.
+- Preserve page order, anchors, bookmarks, figure indexes, and page numbers across breakpoints.
+- do not reflow document copy into a different editorial structure on mobile.
+
+## SVG Rules
+
+- Inline SVG charts must keep a stable `viewBox` and use CSS `aspect-ratio` that matches that viewBox.
+- SVG figures should use `display: block`, `max-width: 100%`, `height: auto`, and `overflow: visible`.
+- Scale the SVG as one fixed graphic within the canonical page; do not reflow labels, legends, or axes per breakpoint.
+- External SVG assets used through `<img>` should be constrained like other images: fixed frame, `object-fit: contain`, and explicit max dimensions.
+
+## Workspace Rules
+
+- The React open-press workbench shell may be responsive: side panels can collapse, navigation can become denser, and controls may hide secondary metadata.
+- The document page itself should not change its typography hierarchy, captions, table structure, or figure composition just because the viewport changed.
+- If text becomes too small on mobile, prefer pinch/zoom or horizontal-safe page scaling over rewriting the document layout.
+- Keep a single scroll owner per viewport mode. Avoid nested vertical scrollbars between body, stage, and page.
+
+## Avoid
+
+- viewport-width font sizing inside fixed pages;
+- mobile-specific page content order;
+- breakpoints that alter canonical page pagination;
+- iframe-based PDF readers as the central stage;
+- CSS transforms that leave hit targets, bookmarks, or scroll sync using stale geometry.
+
+## Acceptance Checklist
+
+- Desktop, tablet, and mobile all show the same page count.
+- Bookmark clicks land on the same logical page across breakpoints.
+- Figures and tables retain captions and do not overflow.
+- The page is scaled or positioned by the workspace, not redesigned by the viewport.
+- There is no embedded browser PDF toolbar inside the open-press reader.

package/template/skills/openpress-design/references/theme-and-components.md

@@ -0,0 +1,77 @@
+# Theme And Component Boundaries
+
+## Theme Layers
+
+Use theme layers by responsibility:
+
+| Layer | Owns |
+| --- | --- |
+| `document/theme/tokens.css` | variables only: colors, fonts, type scale, spacing, chart colors, shared numeric tokens |
+| `document/theme/fonts.css` and `fonts/` | font-face sources copied to `/openpress/fonts.css` and `/openpress/fonts/` |
+| `document/theme/base/` | global page contract, typography, figures, tables, captions, TOC, print safeguards |
+| `document/theme/page-surfaces/` | whole-page layouts such as cover, TOC, optional chapter openers, back cover, divider pages |
+| `document/theme/patterns/` | reusable document-wide class patterns |
+| `document/theme/shell/` | exported reader controls around the document |
+| `document/components/<name>/style.css` | instance-scoped component CSS |
+
+Do not put page-surface or component-specific CSS in `base/typography.css`.
+
+## Component Extraction
+
+Prefer React components when a visual block has structured sub-elements, repeats with different props, or would otherwise become a large inline HTML island.
+
+Component shape:
+
+```txt
+document/components/ComponentName.tsx
+document/components/ComponentName/
+  index.tsx       # default-exported React component
+  style.css       # optional component-scoped CSS
+```
+
+Use PascalCase component names so MDX can call them directly:
+
+```mdx
+<ProcessDiagram title="Deploy flow" steps={["Validate", "Render", "Deploy"]} />
+```
+
+Props live in TypeScript types or interfaces next to the component. Do not add sidecar renderer, schema, data, or custom element bridge files.
+
+Keep image grids inline when pagination owns their page-break behavior. Do not extract foundational page surfaces such as cover/back-cover/chapter-opener unless the design system does it as a coordinated React page-surface change.
+
+## Page Surface Chrome
+
+The renderer owns page chrome policy. Theme CSS should style the contract, not invent per-document footer hacks:
+
+| Page kind | Theme surface | Footer |
+| --- | --- | --- |
+| `cover` | `page-surfaces/cover.css` | off |
+| `toc` | `page-surfaces/toc.css` | off |
+| `chapter-opener` | `page-surfaces/chapter-opener.css` when the pack supports book-like dividers | off |
+| `content` | `base/typography.css` and patterns/components | on |
+| `back-cover` | `page-surfaces/back-cover.css` | off |
+
+Use `.reader-page.no-footer .page-frame` for layout rows when a surface has no footer. Do not leave empty footer text or hide meaningful generated page numbers with one-off selectors.
+
+## Design Document Source
+
+`document/design.md` is a single public-readable design brief. It should describe the same theme the document actually uses:
+
+- typography hierarchy and scale;
+- cover, TOC, optional chapter-opener, chapter, and back-cover direction;
+- paragraphs, lists, quotes, callouts;
+- image, image-grid, chart, table, caption, and dense-content stress cases.
+
+Caption wording and numbering belong to `openpress-writing` and the renderer. Design may style `figcaption`, `caption`, and `[data-openpress-caption]`, but should not require authors to maintain figure/table numbers or duplicate caption text inside visuals.
+
+Do not create a second hidden design brief unless the user explicitly asks for a sandbox.
+
+## Localization Defaults
+
+open-press engine does not embed a complete language system. Audit these per document:
+
+- frontmatter `title:` on cover, TOC, and back cover;
+- `theme/tokens.css` font stacks;
+- `theme/base/typography.css` chapter and section numbering rules.
+
+Workbench UI strings in `src/openpress/` are application UI and belong to framework work, not document styling.

package/template/skills/openpress-diagram-drawing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: openpress-diagram-drawing
+description: Use when drawing or revising open-press document diagrams, especially concept diagrams, comparison figures, process states, data-structure nodes, pointers, arrows, before/after states, linked lists, stacks, queues, trees, or memory relationship figures.
+---
+
+# open-press Diagram Drawing
+
+This skill owns diagram semantics, not visual skin. It decides what the diagram should show and what text belongs inside the figure.
+
+## Core Rule
+
+Draw the relationship, not the explanation.
+
+Figure bodies may contain only spatially meaningful information: object labels, pointer names, field names, axes, legends, short state labels, node values, `NULL`, and operation-order labels.
+
+Move reasons, warnings, edge cases, teaching commentary, and interpretation into surrounding prose or captions.
+
+## Responsibilities
+
+- Choose whether a concept needs a diagram, table, code block, or prose.
+- Define nodes, links, arrows, states, labels, and before/after relationships.
+- Keep figure text lean and connected to position or direction.
+- Prevent diagrams from containing answers, production notes, or caption-like sentences.
+
+## Boundaries
+
+- `openpress` owns validation/render command choice and the source/generated boundary.
+- `openpress-design` owns visual skin, typography, CSS, and component implementation.
+- `openpress-writing` owns the surrounding explanation and caption wording.
+- `teaching-notes-writing` (loaded via `openpress-writing`) owns learner-facing practice flow.
+
+## Workflow
+
+1. Identify the diagram job: comparison, process state, relationship snapshot, before/after, operation sequence, traversal trace, or data representation.
+2. Choose the surface:
+   - diagram for links, ownership, direction, state changes;
+   - table for dense comparisons or many trace rows;
+   - code block for exact syntax.
+3. Draw from semantics first; let style follow.
+4. Check whether the diagram can be understood without explanatory sentences inside the visual.
+
+## When To Read References
+
+- Read `references/diagram-patterns.md` for linked-list, circular-list, doubly-list, stack, queue, polynomial, sparse-structure, and tree drawing patterns.