Openpress

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.
• Route @openpress-comment marker work to openpress-apply-comments.
• Route package upgrade and migration work to openpress-upgrade.
• Point framework release work to docs/release-and-deploy.md; release maintenance is documentation, not an installed workspace skill.
• Route domain work to the owning skill.
• Require verification before declaring output ready.

Skill Routing

Source Boundary (canonical)

Edit source, not generated output. This list is the single authoritative version; other skills link here.

If a workspace lacks press/*/press.tsx, it has runtime files but no Press Tree source yet. Route to openpress-create-pages for page-based artifacts or openpress-create-slide for slide decks. Do not use the removed scaffolding command as a user-facing skill route.

If memory/AGENTS.md exists, read it before framework-level AGENTS.md; it usually marks a downstream workspace where press/ is git-ignored project content, not source you commit upstream.

Press Tree Render Boundary

• press/<slug>/press.tsx owns one rendered Press tree: <Press>, manuscript helpers such as <Toc> / <Sections>, and any custom frame components.
• <Press sources> owns MDX registration. The helper reads the registered source, not a hard-coded folder.
• <Press componentsDir> and <Press mediaDir> may be a path or path array. Prefer folder-local ./components / ./media; use press/shared/* only for intentionally shared source.
• <Frame> is the only core page primitive. Cover, TOC, openers, content pages, and back cover are all frame instances from the engine's perspective.
• <MdxArea> and helper wrappers such as <TocArea> are measurable content slots. TOC is implemented as a generated toc:<sourceId> chain, not as a reader/runtime special case.
• Page chrome belongs to workspace components. Headers, footers, running titles, page numbers, and TOC page layout must be implemented in the workspace Press tree or source-tree components; the reader runtime displays final HTML and must not paginate or patch page shell after export.

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.

Hot reload boundary

Vite Hot Reload covers React UI chrome (workbench panels, navigation, inspector) and framework CSS (packages/core/src/styles/ in this repo, or node_modules/@open-press/core/dist/ in downstream workspaces). It does not regenerate public/openpress/<slug>/document.json. So edits to MDX content, press/*/press.tsx, press/<slug>/components/**/*.tsx, package.json's "openpress" metadata, or any press/<slug>/theme/** rule that changes pagination capacity require a re-export before the workbench / public viewer shows the change:

npm run build              # validate + render (includes the export step)
# — or, for the inner export only, without the full Vite bundle step:
node engine/cli.mjs export .
# then refresh the browser

Pure CSS edits that don't move blocks are picked up by HMR — re-export is only required when content, pagination, or document.json metadata changes. After applying a non-CSS edit to press/, run npm run build before reporting "done"; if the user asks "why didn't my change show up?", check whether document.json was regenerated since the edit.

Starting A New Workspace

Starting a new artifact is owned by openpress-create-pages or openpress-create-slide.

The global create package is the low-level workspace bootstrapper:

npm create @open-press <target> -- --type slides

Creation skills call that command when they need a fresh package-based workspace shell. Slide skills keep and extend the generated slides Press; page skills replace it with the appropriate pages Press Tree, theme, source folders, and components. Inside an existing workspace, slide decks are added with open-press create <slug> --type slides. openpress does not own intake for new artifacts.

Before a framework release, verify the create surfaces still match core and the slide skill: @open-press/create and open-press create must both scaffold marker-only slide Presses, slide-style/manifest.json, registered slide-style/templates/*/slide.tsx, an active theme/default.css copied from slide-style/theme/default.css, slides/<id>/slide.tsx, and theme/ (not themes/). Run the create and CLI package tests after any template or core slides-folder contract change.

Use openpress for system lifecycle work on existing workspaces: doctor, validation, render, PDF/image export, deploy dry-runs, and source search/replace. Use openpress-upgrade for package upgrades and workspace migrations.

Updating An Existing Workspace

Use openpress-upgrade when the user explicitly asks to upgrade, check for a new version, respond to an update notice, prepare before migration, apply migration notes, or verify migration QA. Do not run upgrade commands during ordinary writing/design/deploy work.

@openpress-comment Routing

Use openpress-apply-comments when the user asks to list, apply, resolve, clear, or inspect pending @openpress-comment markers. Keep this skill focused on the source boundary and command surface; the comment workflow lives in the dedicated workflow skill.

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 the inspector / page zoom / inline source editor, 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.

open-press CLI Commands

Prefer package scripts. For commands without a script wrapper, use the open-press binary:

open-press <command> [path] [options]

In the framework repo (monorepo), use node packages/core/engine/cli.mjs instead — the binary is not built locally.

Command notes:

• search and replace default to --scope content.
• Add --scope all to also include press/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 may be sparse; use top-level usage and command error messages.
• Applying pending comment markers is an agent workflow, not a deterministic CLI replacement; use the openpress-apply-comments skill.

Local Review

open-press local review is the human feedback loop before PDF or public deploy.

Workflow

npm run build
npm run dev

Use the URL printed by Vite. It is usually:

http://127.0.0.1:5173/workspace

If 5173 is occupied, use the port reported by the dev server.

Workbench Layout

The workbench is a three-column shell — left navigation, center rendered document, right control panel. Both side panels default to closed and toggle from the toolbar.

• Left panel — document identity, bookmarks (chapter outline), current page indicator.
• Center stage — the rendered document. Use the toolbar zoom control for fit-width / fit-page / fixed % / one-page ↔ two-page spread.
• Right panel — control panel with two stacked sections:
• Pending comments — every unresolved @openpress-comment marker. Click an entry to jump to its block.
• Project entry — referenced media (click to preview) and registered components (click to preview rendered HTML). Project preview dialogs are view-only — comment via the inspector toggle.

Below 1184px width the panels become floating drawers; above that they sit in grid columns.

Toolbar

• PDF export — opens the most recent PDF (local dev or deployed).
• Page geometry — current page dimensions.
• Page zoom — fit-width / fit-page / 25–200% / single ↔ spread.
• Search (dev) — full-text across registered MDX sources.
• Inline edit status (dev) — pill that shows 編輯中 / 儲存中 / 已儲存 / 儲存失敗.
• Inspector toggle (dev) — turn on to leave comments on rendered blocks.
• Deploy (dev) — open the deploy dialog.

Comments

• Toggle the inspector, click a block (or the insertion bar between blocks), pick Add / Edit / Remove, type in the inline composer, submit with Cmd/Ctrl + Enter.
• Saved comments leave numbered markers; click a marker to edit or delete its comment.
• Use the right-panel Pending comments list for cross-page navigation.
• Route resolution work to openpress-apply-comments.

Inline Source Editing (dev)

Text blocks rendered from MDX are contenteditable in dev mode. Click into one to edit, blur or Cmd/Ctrl + Enter to save. The save endpoint refreshes the document so derived indexes (blockMap, anchorPageMap) stay in sync. Table cells edit independently — each <td> is its own block with a cellIndex round-trip.

After Source Edits

npm run build              # validates + renders the full pipeline

For fast inner-loop iteration (no Vite bundle):

node engine/cli.mjs export .     # rewrite document.json
node engine/cli.mjs validate .   # source structure only

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.