@open-press/cli 0.3.0 → 0.5.0

package/template/skills/openpress-style-pack-contributor/SKILL.md

@@ -1,62 +0,0 @@
----
-name: openpress-style-pack-contributor
-description: Use when contributing, designing, creating, reviewing, or improving a open-press style pack, especially the visual philosophy, starter workspace, design doc, theme tokens, page surfaces, components, and validation for skills/<pack>/starter.
----
-
-# open-press Style Pack Contributor
-
-This skill owns **bundled style packs at the source** — everything under `skills/<pack>/`. A style pack is an opinionated document design system plus a runnable starter workspace. Use `openpress` for the exact init, validate, export, render, and scratch-workspace commands.
-
-The split with `openpress-design` is by path, not by topic:
-
-- `skills/<pack>/starter/document/…` → this skill (upstream, ships to every new workspace).
-- `document/…` in an end-user workspace → `openpress-design` (downstream, one project's local edits).
-
-## Responsibilities
-
-- Define one clear visual philosophy for the pack.
-- Edit only `skills/<pack>/` unless the framework lacks a generic capability.
-- Provide a runnable `starter/` that the system-level `openpress` skill can initialize into a fresh target.
-- Keep starter `design.md` public-readable.
-- Preserve portable typography contracts: `theme/tokens.css` names `--openpress-font-*` tokens, `theme/fonts.css` loads faces, and `local(...)` alone is not enough for stable public output.
-- Validate the pack through a scratch workspace (do not overwrite the user's current `document/`).
-
-## Boundaries
-
-- `openpress` owns CLI command choice and the source/generated boundary table.
-- `openpress-design` owns the same visual concerns but in workspace `document/`, not pack `starter/`.
-- `openpress-writing` owns starter content prose and factual boundaries.
-
-## Pack Layout
-
-```txt
-skills/<pack>/
-  SKILL.md            # visual signature, suitable-for, do/don't
-  starter/
-    openpress.config.mjs
-    document/
-      index.tsx
-      chapters/
-      design.md
-      theme/
-      components/
-      media/
-```
-
-Do not put generated output, private content, customer data, secrets, or deployment artifacts in a style pack.
-
-## Workflow
-
-1. Define intended document types, readers, and visual philosophy.
-2. Keep the pack narrow; one pack should not serve every tone or industry.
-3. Build or update `starter/`.
-4. Ask `openpress` to choose and run the scratch-workspace validation workflow.
-5. Ask `openpress` for broader framework checks only when shared code changes.
-
-## Cross-Pack Discovery
-
-When adding a new pack, also update sibling pack SKILLs that overlap in audience so users can choose between them. Each pack SKILL should at minimum list its **suitable / not suitable** scope.
-
-## When To Read References
-
-- Read `references/starter-contract.md` for starter file responsibilities, typography portability, validation expectations, and review checklist.

package/template/skills/openpress-style-pack-contributor/references/starter-contract.md

@@ -1,49 +0,0 @@
-# Style Pack Starter Contract
-
-## Starter Responsibilities
-
-| Path | Responsibility |
-| --- | --- |
-| `starter/openpress.config.mjs` | root marker that points at `document/openpress.config.mjs` |
-| `starter/document/index.tsx` | React document entry: config plus cover, TOC, and back-cover shell JSX |
-| `starter/document/chapters/` | minimal coherent MDX chapters; optional chapter opener files |
-| `starter/document/design.md` | single public-readable design brief (style positioning, tokens, components, CSS responsibilities) |
-| `starter/document/theme/` | CSS tokens, fonts, base typography, page surfaces, patterns, shell rules, print safeguards |
-| `starter/document/theme/fonts.css` | font-face imports or self-hosted font rules |
-| `starter/document/theme/fonts/` | optional self-hosted `.woff2` files |
-| `starter/document/components/` | reusable structured visual units |
-| `starter/document/media/` | assets safe to ship with the pack |
-
-The engine discovers a style pack by the presence of `starter/`.
-
-Page surfaces are optional by document type. A report-focused pack can ship only cover, TOC, chapter, and back cover styling. A book/manual/teaching pack may also include `starter/document/theme/page-surfaces/chapter-opener.css` plus optional `chapter.tsx` opener exports. Chapter openers must be optional starter content, not a required page in every new workspace.
-
-## Typography Portability
-
-Style packs own typography:
-
-- `theme/tokens.css` names font tokens and fallback stacks.
-- `theme/fonts.css` loads actual font faces.
-- `theme/fonts/` stores self-hosted files when the pack must work without a CDN.
-
-Do not rely on `local(...)` alone for public, mobile, iPad, or PDF-stable output. If a pack uses system fonts, document that output is not pixel-identical across devices.
-
-## Validation Expectations
-
-Validate through a scratch workspace, but do not define the command sequence in this style-pack reference. Use `openpress` for init, validate, export, render, PDF, and broader framework check commands.
-
-Run PDF only when `openpress` determines the scratch workspace has the required app/runtime files. Run broader framework checks only when shared code changes.
-
-## Review Checklist
-
-Before calling the pack ready, confirm:
-
-- one narrow, describable visual philosophy;
-- portable typography policy;
-- starter renders without missing assets or fonts;
-- `openpress` can initialize and validate the pack through the current system-level workflow;
-- dense paragraphs, tables, figures, captions, and long headings remain readable;
-- starter Markdown tables demonstrate `<TableCaption>...</TableCaption>` instead of legacy prose markers or hand-written table numbers;
-- PDF output does not overflow fixed pages when PDF validation is available;
-- `design.md` teaches users and agents how to review the pack;
-- no private content, customer data, tokens, or deploy secrets are included.

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

@@ -1,88 +0,0 @@
----
-name: openpress-update
-description: Use when updating or upgrading an existing open-press workspace to a newer framework release, pulling new engine/runtime changes, applying release migration notes, or handling breaking changes between versions.
----
-
-# open-press Update
-
-This skill owns the **release update flow** for an existing workspace: pulling new framework code, applying migration notes, handling breaking changes, and verifying nothing broke.
-
-It does not own first-time setup (that is `openpress-init`) and does not own content/design changes (those are domain skills).
-
-## When To Enter
-
-Activate when the user says any of:
-
-- "升級 open-press / 更新到最新版"
-- "update open-press / upgrade to latest"
-- "拉新版的 engine"
-- "看一下這版有什麼破壞性改動"
-- After the user pulls a new git tag and asks to verify the workspace still works.
-
-## Pre-Flight Check
-
-Before touching anything, confirm:
-
-1. **Workspace state is clean**: `git status` shows no uncommitted document changes that an upgrade might overwrite.
-2. **Current version is known**: read `package.json` `version` field; compare to target version.
-3. **CHANGELOG has been read**: locate the project's CHANGELOG (currently in `docs/superpowers/specs/` migration notes; future: top-level `CHANGELOG.md`). Identify every breaking change between current and target version.
-
-If any of these are missing, surface to the user before proceeding.
-
-## Current Update Surface (pre-`core/`)
-
-Until the `core/` folder restructure ships (tracked in `docs/superpowers/specs/2026-05-21-open-press-template-and-skill-init.md`), framework code lives intermixed with workspace code in this repo. Update means:
-
-1. `git pull` (or merge / rebase the new framework tag).
-2. `npm install` to refresh dependencies.
-3. `npm run typecheck` — first signal of API-shape breakage.
-4. `npm test` — second signal of behavior breakage.
-5. `npm run openpress:validate && npm run openpress:render` against current `document/`.
-6. For each failure, check the CHANGELOG entry for the breaking change and apply the documented migration.
-
-## Future Update Surface (post-`core/`)
-
-When `core/` exists (planned, see spec):
-
-1. Backup user-edited escape-hatch files under `src/` (workspace overrides via vite alias).
-2. Overwrite `core/` wholesale from the new release.
-3. Re-apply codemods listed in the release migration notes.
-4. Verify with `typecheck` + `test` + `validate` + `render`.
-
-This skill will own the codemod runner once it exists.
-
-## Breaking Change Handling
-
-For each breaking change in the CHANGELOG:
-
-| Change type | Action |
-| --- | --- |
-| Renamed identifier (e.g. `BaseReportPage` → `BaseContentPage`) | grep workspace for old name; rewrite at every callsite |
-| Removed export | grep workspace; ask user if replacement is acceptable |
-| Changed function signature | typecheck will surface; fix per release notes |
-| CSS class rename | grep `document/theme/` and `document/components/`; rewrite |
-| Config schema change | edit `openpress.config.mjs` per release notes |
-| Markdown / MDX directive change | grep `document/chapters/`; rewrite per release notes |
-
-If a breaking change has no documented migration in the CHANGELOG, **stop and ask the user** — do not improvise.
-
-## Workflow
-
-1. Pre-flight (clean tree, version delta, CHANGELOG read).
-2. Pull the new code.
-3. Run `typecheck` / `test` / `validate` / `render` in that order; stop at the first failure.
-4. For each failure: find the CHANGELOG entry, apply the migration, re-run the failing command.
-5. After all gates pass, run `npm run openpress:pdf` to sanity-check PDF output.
-6. Report to the user: starting version, ending version, list of migrations applied, anything that needed manual intervention.
-
-## Boundaries
-
-- `openpress` owns the CLI and the source/generated boundary. This skill uses those commands.
-- `openpress-deploy` is **not** part of update; do not auto-deploy after a successful update.
-- Domain skills (`openpress-writing` / `openpress-design`) handle non-mechanical content rewrites that the user wants to do alongside the upgrade.
-
-## Do Not
-
-- Do not skip CHANGELOG reading. An undocumented breaking change is a sign to stop, not a sign to guess.
-- Do not bundle new feature work with an update. Land the update first, commit, then start new work.
-- Do not run `--force` overwrites on workspace files. If a file conflicts, surface it.

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

@@ -1,68 +0,0 @@
----
-name: openpress-writing
-description: "Use when planning, restructuring, drafting, rewriting, or editing open-press document content at the document level: audience, narrative, section order, table/figure captions, factual boundaries, and coordination with independent writing skills."
----
-
-# open-press Writing
-
-open-press writing owns the **reader-facing document argument**. It decides what the document should say, in what order, and what facts need confirmation. It is also the **entry point for portable writing skills** (tone, language, genre, teaching).
-
-## Responsibilities
-
-- Define audience, purpose, narrative flow, and section order.
-- Rewrite prose, tables, captions, and content transitions.
-- Own the `<TableCaption>...</TableCaption>` placement rule (single authoritative definition; style packs link to this skill, not redefine it).
-- Decide when prose should become a table, figure, chart, or callout.
-- Preserve confirmed facts and mark missing facts explicitly.
-- Load portable writing skills based on content type (see triggers below).
-- Reference `openpress` for system operations, source/generated boundaries, and verification commands instead of defining them here.
-
-## Boundaries
-
-| Owns | Boundary |
-| --- | --- |
-| `openpress` | CLI, inspect/search/replace, source/generated boundary |
-| `openpress-document-hierarchy` | H1/H2/H3/H4 structure, TOC depth, appendix placement |
-| `openpress-design` | theme CSS, visual systems, component styling |
-| `openpress-diagram-drawing` | what diagrams show |
-| Portable writing skills | language, tone, genre, teaching-specific rules |
-
-Source paths follow `openpress` > Source Boundary. Do not redefine them here.
-
-## Coordination With Hierarchy
-
-When work might change `##` chapter splits, TOC depth, or H4 outline density, **route to `openpress-document-hierarchy` first**, then return here to write the prose. When writing reveals a need to split or merge headings, hand the structural change back to hierarchy.
-
-## Portable Writing Skill Triggers
-
-Load a portable skill when content matches these conditions:
-
-| Content type | Load |
-| --- | --- |
-| Any Traditional Chinese professional content | `chinese-ai-writing-polish` |
-| Learner-facing teaching notes, worksheets, study guides, tutorial chapters | `teaching-notes-writing` |
-| (future) Business proposal / pitch / investor memo | dedicated portable skill |
-| (future) Academic report / paper | dedicated portable skill |
-
-Multiple portable skills may apply (e.g. 繁體中文 teaching notes load both). When two rules disagree, resolve in this order:
-
-1. Explicit user instruction in the current conversation.
-2. Workspace memory and preferences (e.g. `memory/AGENTS.md`, `document/design.md`).
-3. Document brief or stated purpose.
-4. `openpress-writing` structural decisions (audience, narrative, section order).
-5. Portable skill rules.
-
-If the conflict changes meaning or claims, ask the user.
-
-## Workflow
-
-1. Identify audience, goal, fixed facts, and missing facts.
-2. Check if hierarchy is affected; if so, coordinate with `openpress-document-hierarchy` first.
-3. Load portable writing skills per the trigger table.
-4. Rewrite source content without adding unsupported claims.
-5. Mark unresolved facts as `[TODO: ...]`, `[FIX: ...]`, or `[DRAFT: ...]`.
-6. Ask `openpress` which validation depth and commands are needed after content edits.
-
-## When To Read References
-
-- Read `references/source-and-writing-rules.md` for frontmatter, metadata, unfinished markers, public-content boundaries, heading hygiene, formulas, captions, and starter document rules.

package/template/skills/openpress-writing/references/source-and-writing-rules.md

@@ -1,120 +0,0 @@
-# Source And Writing Rules
-
-## Content Shape
-
-open-press scans React/MDX chapter content in chapter directory order:
-
-```txt
-document/index.tsx
-document/chapters/
-  01-example/
-    chapter.tsx       optional meta/opener for book-like docs
-    content/
-      01-start.mdx
-```
-
-Document shell exports in `document/index.tsx`:
-
-- `config`: document identity and open-press paths.
-- `cover`: opening identity page.
-- `toc`: generated table of contents shell.
-- `backCover`: closing page.
-
-Chapter exports in `chapter.tsx`:
-
-- `meta`: optional `slug`, `title`, and tone/style metadata.
-- `opener`: optional chapter divider JSX for books, teaching notes, manuals, or loose chapter collections.
-
-Document-level identity belongs in `document/index.tsx` `config` and, for nested workspaces, matching `document/openpress.config.mjs` delivery settings:
-
-- `title`
-- `subtitle`
-- `organization`
-- `workspaceLabel`
-
-Do not move document identity into MDX frontmatter.
-
-## Page Kind Boundaries
-
-Use source location to describe a page's role, not its topic:
-
-| Source | Use For | Footer |
-| --- | --- | --- |
-| `document/index.tsx` `cover` | document opening identity | no |
-| `document/index.tsx` `toc` | generated table of contents shell | no |
-| `chapter.tsx` `opener` | optional chapter divider / mini cover | no |
-| `content/*.mdx` | normal reader-facing sections split/paginated by blocks | yes |
-| `document/index.tsx` `backCover` | closing page | no |
-
-`opener` is not a substitute for `##` chapter content. It should introduce the next chapter with a title, short summary, or learning map, then the real chapter still starts in MDX. Do not add chapter openers to thesis/report-style documents unless the user asks for a book-like reading rhythm.
-
-## Public Content Boundary
-
-Rendered open-press pages are for the intended reader. Avoid internal production notes in `document/chapters/` unless the document topic is explicitly open-press, agent workflows, style packs, or design documentation.
-
-Avoid accidental internal language such as `agent`, `skill`, `style pack`, `內部規則`, `給老師看`, `設計理由`, or `production note` in normal reader-facing chapters. Use `openpress` when source scanning is needed.
-
-## Unfinished Content
-
-Use recognizable markers:
-
-```txt
-[TODO: ...]
-[FIX: ...]
-[DRAFT: ...]
-```
-
-Avoid bare `TODO`, `TBD`, or `[必填]`; they are harder to distinguish from normal prose.
-
-## Heading Hygiene
-
-Headings are navigation labels. Keep `##` and `###` plain-text and semantic:
-
-- no backtick code spans;
-- no raw HTML tags;
-- no bold/italic Markdown;
-- no formulas as heading text.
-
-Move identifiers, formulas, commands, and API names into the paragraph after the heading. Before finishing a writing pass, ask `openpress` to scan headings for code spans, raw HTML, bold/italic Markdown, or formula-like labels when that risk is present.
-
-## Formula Writing
-
-open-press renders LaTeX math. Use plain Markdown delimiters:
-
-- Inline: `$x^2$` or `\(x^2\)`.
-- Display: `$$ ... $$` or `\[ ... \]` on their own lines.
-
-If a formula string should remain literal, use code spans or code fences.
-
-## Caption Contract
-
-open-press owns figure and table numbering. Components and Markdown content provide only semantic caption text; the renderer adds numbering such as `圖 N：` or `表 N：`.
-
-- Use at most one `<figcaption>` per `<figure>`.
-- Put visible captions after the visual body.
-- Put `<TableCaption>` immediately before any Markdown table that should be captioned:
-  ```mdx
-  <TableCaption>Pointer syntax</TableCaption>
-
-  | 寫法 | 意義 |
-  | --- | --- |
-  | `p` | 節點位址 |
-  ```
-- Do not use the legacy `表：...` marker, and do not write `表 1：`, `圖 2：`, `Figure 1`, or `Table 1` in source content. The visible number is generated from DOM order.
-- Empty `<TableCaption>` components, misplaced `<TableCaption>` components, and legacy `表：...` markers are compile errors.
-- Keep captions title-level; put long explanation in surrounding prose.
-- Do not draw figure/table numbers or explanatory prose inside chart panels.
-
-## Starter Document Writing
-
-Use the active style pack starter and `document/design.md` when drafting a new or thin open-press workspace.
-
-A small starter document usually includes:
-
-- cover: title, subtitle, promise, summary;
-- TOC: placeholder only, because open-press injects entries;
-- chapter 1: purpose, audience, workflow;
-- chapter 2: validation, output, example table or list;
-- back cover: concise closing statement.
-
-Prefer user-provided facts. If facts are missing, write neutral operational content or explicit placeholders instead of inventing organizations, metrics, testimonials, dates, or commitments.

package/template/skills/teaching-notes-writing/SKILL.md

@@ -1,54 +0,0 @@
----
-name: teaching-notes-writing
-description: Use when drafting or revising learner-facing teaching notes, course handouts, worksheets, study guides, or tutorial chapters that need comparisons, step-by-step explanation, quick practice, worked examples, or answer appendices.
----
-
-# Teaching Notes Writing
-
-This is a **portable writing skill**: usable standalone, and loaded by `openpress-writing` when content is learner-facing teaching material (handouts, worksheets, study guides, tutorial chapters). `openpress-writing` owns the trigger and conflict-resolution rules.
-
-Teaching notes are for learners who are still building the mental model. This skill provides **suggested content skeletons**, explanation strategies, examples, practice ideas, and answer-flow guidance. It does not mandate one rigid chapter template.
-
-## Responsibilities
-
-- Start from the learner's likely mental model.
-- Compare nearby ideas before introducing formal rules.
-- Show procedures step by step with visible state changes.
-- Put reasons, warnings, and interpretation in prose rather than overloading figures.
-- Suggest practice surfaces that match the chapter content.
-- Put answers after the learner has had a chance to try.
-- Suggest when a structure, relationship, or state change should become a diagram; use `openpress-diagram-drawing` for the actual diagram semantics.
-
-## Boundaries
-
-- `openpress-writing` owns open-press source boundaries and public-content hygiene.
-- `openpress-document-hierarchy` owns H1/H2/H3/H4 structure for long-form open-press notes.
-- `openpress-diagram-drawing` owns diagram semantics.
-- `openpress-design` owns visual style and component implementation.
-- `openpress` owns CLI, validation/export/render commands, and source/generated boundaries.
-- This skill owns learner-facing explanation suggestions and exercise-design patterns only.
-
-## Suggested Skeleton
-
-Use this as a starting skeleton, not a required template:
-
-1. Start from the learner's concrete problem or confusion.
-2. Compare nearby concepts, states, or representations.
-3. Show the operation or idea step by step.
-4. Add one small check, trace, or practice task when it helps.
-5. Put full answers after the learner has had a chance to attempt.
-
-If the concept depends on spatial structure, ownership, arrows, state transitions, or before/after relationships, hand the visual semantics to `openpress-diagram-drawing`.
-
-## Learner Boundary
-
-Rendered teaching pages should speak to the learner, not the teacher or agent.
-
-- Do not include teacher-only reminders, production notes, internal rationale, or style-pack commentary.
-- Keep internal rules in skills, design docs, or source references.
-- Use consistent terms and variable names across prose, diagrams, tables, and code.
-
-## When To Read References
-
-- Read `references/teaching-patterns.md` for comparison writing, explanation order, practice question types, and answer placement.
-- Read `references/programming.md` when teaching code, pseudocode, data structures, pointer diagrams, memory state, or program traces.

package/template/skills/teaching-notes-writing/references/programming.md

@@ -1,65 +0,0 @@
-# Programming Teaching Reference
-
-Use this reference with `teaching-notes-writing` when the learning material teaches programming, algorithms, data structures, memory state, or code tracing.
-
-## Long Code Teaching Flow
-
-When a section introduces a long program, avoid dropping the full code block first. Use this order:
-
-1. State the problem the code solves.
-2. Show the data shape first, usually a `struct`, record, class, type definition, or table of variables.
-3. Explain helper functions one at a time.
-4. Present the core algorithm or function after students know the supporting pieces.
-5. Add a complete version at the end, including `main` or an equivalent entry point when the language uses one.
-6. Show a small expected output or state trace so students know how to verify the program.
-
-## Heading Hierarchy For Course Notes
-
-- Use `#` only for the whole document title, usually on the cover or in metadata.
-- Use `##` for formal chapters such as `CH5 Tree`, `CH6 Graph`, or `CH7 Sorting`.
-- Use `###` for major topic groups that should appear in the formal table of contents, such as `Traversal`, `BST`, `MST`, or `Sorting Algorithms`.
-- Use `####` for concrete algorithms, operations, theorem items, or implementation variants, such as `BST delete`, `left rotate`, `quick sort (non-recursive)`, or `Theorem 1`.
-- Do not promote every algorithm to `##`; a long course note needs stable hierarchy more than large titles.
-
-## Code Block Rules
-
-- A code block should have a clear local purpose before it appears.
-- Prefer several short code blocks for teaching, then one complete code block for integration.
-- Keep identifiers consistent across prose, tables, diagrams, and code.
-- Use comments only when they explain a non-obvious step. Do not comment every assignment.
-- When dynamic memory or external resources are involved, include cleanup in the complete version if the language requires it.
-- If a simplified example omits error handling or cleanup, state the omission explicitly. Prefer not omitting them in final code.
-
-## Pseudocode Rules
-
-- Pseudocode should look like an algorithm, not a compressed prose note.
-- Include `Algorithm`, `Input`, and `Output` when the block represents a complete procedure.
-- Use indentation to show loops and branches.
-- Name operations by intent, such as `append_term`, `poly_add`, `clear`, or `return`, instead of vague verbs.
-- Keep pseudocode close enough to implementation that students can map it back to the final program.
-
-## Programming Diagram And Table Pairing
-
-- Use markdown tables for dense comparisons, coefficient tables, state traces, and step-by-step logs.
-- Suggest custom open-press components for visual relationships: node links, pointer movement, memory layout, before/after states, and flow diagrams.
-- Use `openpress-diagram-drawing` to decide what belongs inside those visuals.
-- Do not combine a large table and a large diagram into one oversized image. Split them so each surface has one reading job.
-- Full-width figures are acceptable when a diagram contains multiple linked nodes or state rows.
-
-## Technical Term Usage
-
-- Do not force every programming term into Chinese.
-- Use common English terms when students will also see them in code, exams, online judges, IDEs, or English documentation.
-- For major concepts, use English first with a local-language bridge on first mention: `Linked List（鏈結串列）`, `Singly Linked List（單向鏈結串列）`, `Doubly Linked List（雙向鏈結串列）`, `Circular Linked List（環狀串列）`, `Header Node（開頭空白節點）`.
-- After a concept is established, keep the English term in headings, tables, diagrams, and code-adjacent prose when that is what students will see elsewhere.
-- Use the local language when explaining reasoning, constraints, and student-facing guidance.
-
-## Completion Check
-
-Before finishing a programming teaching pass:
-
-- verify long code sections have both breakdown and complete integration;
-- check that pseudocode, code, diagrams, and tables use the same identifiers;
-- confirm examples include an expected output, final state, or trace when useful;
-- check that simplified code does not silently omit cleanup or safety checks students need to learn;
-- use `openpress` for any workspace validation, export, render, or source/generated boundary questions.

package/template/skills/teaching-notes-writing/references/teaching-patterns.md

@@ -1,60 +0,0 @@
-# Teaching Patterns
-
-## Comparison Writing
-
-Use comparison when a concept is abstract, easily confused, or representation-dependent.
-
-| Surface | Best For |
-| --- | --- |
-| paragraph | one conceptual difference |
-| table | several aligned dimensions |
-| figure | spatial or directional relationship |
-| state trace | repeated algorithm steps |
-| code block | exact syntax or implementation |
-
-Avoid comparing too many things at once. If a table grows past one reading job, split it.
-
-## Suggested Explanation Skeletons
-
-These are reusable starting points, not mandatory page templates. Adjust the order when the learner's prior knowledge or the source material demands it.
-
-For a concept:
-
-1. why it appears;
-2. small concrete example;
-3. representation or vocabulary;
-4. diagram or table;
-5. formal rule, formula, or code;
-6. common mistake;
-7. quick practice.
-
-For a procedure:
-
-1. initial state;
-2. state-changing steps;
-3. final state;
-4. why order matters;
-5. matching code or formula;
-6. practice trace with another input.
-
-## Visual And Text Roles
-
-- Use diagrams for relationships, directions, and state changes.
-- Use `openpress-diagram-drawing` when a structural visual, state diagram, pointer diagram, process diagram, or before/after figure is needed.
-- Use tables for dense comparisons and traces.
-- Use prose for reasons, warnings, edge cases, and interpretation.
-- Use code/math blocks for exact syntax, formulas, or runnable fragments.
-- Keep captions short; they name what to observe.
-
-## Practice Design
-
-Useful question types:
-
-- quick recall;
-- comparison;
-- state trace;
-- bug finding;
-- implementation;
-- explanation of why a step must happen before another.
-
-Answers can be inline only for tiny checks. For chapter-level exercises, prefer an answer appendix before the back cover.