@open-press/cli 0.7.1 → 1.0.0

package/template/core/CHANGELOG.md

@@ -1,11 +1,67 @@
 # @open-press/core
 
+## 1.0.0
+
+### Major Changes
+
+- 8c528ad: 1.0 contract release. Breaking changes:
+  - `<Workspace>` is now required at the root of `press/index.tsx`; `<Press>` lives as a child, and multi-Press workspaces are first-class (each `<Press>` exports to `/openpress/<slug>/document.json`).
+  - Document metadata (`title` / `subtitle` / `organization` / `page` / `sources` / `captionNumbering`) moves onto `<Press>` JSX props. `export const config` and `export const sources` are removed.
+  - `openpress.config.mjs` is removed. Operational settings (deploy / pdf) live in the workspace `package.json` under the `"openpress"` field; paths are convention (`press/`, `press/<slug>/chapters/`, `press/theme/`, `public/openpress/`, `dist-react/`).
+  - Workspace folder renamed from `document/` → `press/`. The dogfood and starter skills are migrated.
+  - Reader gains a workspace gallery for multi-Press projects, per-page PNG export, page thumbnails for canvas-style Press, and a back-to-workspace button.
+  - New built-in page presets `a4`, `social-square`, `slide-16-9` and improved init metadata propagation.
+
+## 0.8.0
+
+### Minor Changes
+
+- **Workbench architecture**: the monolithic `workbench.tsx` is split into a modular structure under `workbench/{shell,panels,actions,inspector,mentions,project,document}/`. New panels: `DeploymentControl`, `SearchControl`, `PendingCommentsPanel`, `DocumentPanel`, `ProjectEntryPanel`, plus `WorkbenchShell` and `InlineInspectorLayer`.
+- **Module reorganization**: source tree split into typed subdirectories:
+  - `app/`: `OpenPressApp`, `OpenPressRuntime` (replaces the old `App.tsx` + `renderer.tsx`)
+  - `document-model/`: `anchorMap`, `documentIndexes`, `documentTypes`, `objectEntityModel`, `projectIdentity`, `reactDocumentMetadata`
+  - `reader/`: `PublicReaderPage`, `ReaderNavigationPanel`, `useReaderRuntime`, registry/route/scroll/state helpers
+  - `shared/`: `frameScheduler`, `runtimeMode`, `Panel`, `numberUtils`
+- **Object-entity model**: `Frame` and `MdxArea` now expose `data-openpress-object-id`. New `document-model/objectEntityModel` defines the id format.
+- **`MediaFigure` / `ImageFigure`**: new core primitives that accept `src/alt/caption` and resolve relative paths to `/openpress/media/...` automatically.
+- **`<Sections>` default page**: `page` prop becomes optional; when omitted the built-in `DefaultSectionPage` renders the standard manuscript frame.
+- **Engine helpers**: new `engine/react/{http-json,object-entities,source-edit-endpoint}.mjs` and `engine/runtime/{file-walk,path-utils}.mjs` runtime helpers. `engine/runtime/source-text-tools` exports TypeScript definitions.
+- **Dev endpoints**: vite plugin wires `/__openpress/search` and `/__openpress/source-edit` middlewares for the new workbench search + inline editing flows.
+- **Inline source editor**: ships the `InlineSourceEditorLayer` UI on top of `useInlineDocumentEditor` + `/__openpress/source-edit`. The hook now uses a `MutationObserver` so newly inserted blocks become editable, and routes mouse clicks through `focus()` to preserve selection on `contenteditable` boundaries. Workbench wires `sourceEditorTarget` state into the layer.
+- **Table editing in the source pipeline**: table captions are emitted as standalone source blocks (`kind=element`, `name=caption`, `layout="attached"`) with `data-openpress-block-id`/`data-openpress-object-id` markers and preserved source positions; the allocator treats `layout="attached"` blocks as non-paginable. `applySourceBlockTableCellEditToText` (in `engine/runtime/source-text-tools`) accepts a `cellIndex` so the inline source editor can target a single `<td>`.
+- **Reader pagination**: arrow-key pagination now defers to the user's active text selection. Shift-arrow / mouse-drag selections no longer get swallowed by the page-turn shortcut.
+- **Page zoom + spread layout**: new `reader/pageViewportScaleModel` + `usePageViewportScale` hook drive a `--openpress-page-viewport-scale` CSS variable on the page container; the workbench toolbar exposes a `PageZoomControl` dropdown with fit-width / fit-page / fixed percentages plus a one-page / two-page spread toggle.
+- **Inspector cell-precision comments**: `CommentDraft` gains an optional `targetObjectId` so a comment can point at a sub-block (e.g. a single table cell) while still attributing the source position to its enclosing block. `formatInspectorHint` carries the value through to the wire hint.
+- **Shared `WorkbenchDialog` shell**: portal + backdrop + header (eyebrow / title / title-meta / close) + optional footer. `DeploymentControl`, `SearchControl`, and `ProjectPreviewDialog` all render through this shell now, replacing the prior per-dialog scaffolding under `openpress-deploy-dialog-*` / `openpress-search-dialog-*` / `openpress-project-preview-dialog__*`.
+- **`WorkbenchControlPanel` registry**: `HtmlWorkbench` now accepts an `extraControlPanels?: WorkbenchPanel[]` prop and renders the right-side panel from a `{ id, render }` registry. Built-in panels (pending comments, project entry) ship as the first entries.
+- **Workbench state hooks**: extract `useDeploymentWorkbench` and `useInspectorComments` from `HtmlWorkbench`; `useReaderRuntime` is split into focused sub-hooks (`usePanelState`, `useReaderScrollAnchor`, `useReaderHashSync`, `useReaderKeyboardNav`).
+- **`InlineInspectorLayer` memoization**: now wrapped in `React.memo` with a stable `geometryVersion` prop so the geometry / event listeners no longer rebuild on every parent render.
+- **Panels open lazily**: `usePanelState` now defaults both panels closed, so the reader opens with a clean stage; resize never auto-opens them.
+
+### Patch Changes
+
+- Inspector: fix comment-marker count and multi-target marker rendering.
+- Inspector: object-entity id helpers consolidate in `document-model/objectEntityModel` instead of being duplicated inside `Frame`, `MdxArea`, manuscript `TocArea`, and `PublicReaderPage`.
+- Inline editor: `useInlineDocumentEditor` exposes `onDocumentEdited`; `OpenPressApp` re-loads `/openpress/document.json` after a successful inline edit so derived indexes stay in sync.
+- Dev: reset Vite optimizer cache so workspace-side dependencies are picked up.
+- Workbench dialog: viewport-aware width + max-height so a big media preview doesn't blow up the dialog to full screen.
+- Project composer: add `/apply-comments` to the skill mention list so pending comment resolution can be invoked from the workbench.
+- Carries forward the 0.7.1 measurement + pagination fixes (font/image readiness, relative media src inlining, list-per-item paging, `OPENPRESS_DEBUG_ALLOC`, academic-paper starter body overflow).
+
+### Breaking Changes
+
+- `FrameContext.consumeArea(chainId)` return type changes from `ReactNode | null` to `{ indexInFrame: number; blocks: ReactNode | null }`. Custom `Frame` consumers must read `.blocks`.
+- `App` export is renamed to `OpenPressApp` and now lives under `@open-press/core/app`. The old `renderer.tsx` is replaced by `OpenPressRuntime`.
+- `data-openpress-mdx-area-empty` is now always emitted (`"true"` / `"false"`). Selectors that relied on the attribute being absent need updating.
+- Reader `ViewMode` collapses to `"paged"` only — the legacy `"reading"` flow mode is removed. Use `usePageViewportScale` for free-scaling instead.
+- Several internal module paths moved into subdirectories (`document-model/`, `reader/`, `shared/`, `workbench/...`). Consumers that deep-imported from the openpress source must switch to the new barrels.
+- Shared dialog scaffolding (backdrop, container, header, close button) moved from per-dialog class families (`openpress-deploy-dialog-backdrop`, `__panel`, `__panel header`, `__close`, etc.) to the shared `openpress-workbench-dialog*` family. Per-dialog modifier classes (`openpress-deploy-dialog`, `openpress-search-dialog`, `openpress-project-preview-dialog`) are still applied for dialog-specific styling. Selectors that targeted the old scaffolding names (notably `*-backdrop` and `__panel`) need updating; selectors that combine the modifier class with new `__heading` / `__footer` / `__close` modifiers continue to work.
+
 ## 0.7.1
 
 ### Patch Changes
 
 - Measurement pipeline + pagination fixes:
-
   - **Measurement**: wait on `document.fonts.ready`, image `load`/`error` + `decode()`,
     and two `requestAnimationFrame` ticks before sampling block heights so figures
     no longer under-measure on cold loads.
@@ -27,7 +83,6 @@
 - 718d2d1: **Press Tree render architecture** — full refresh of the React export pipeline (clean break, no v0.5 compatibility).
 
   The render kernel no longer knows about `cover`, `toc`, `chapter`, or `back-cover` as built-in concepts. Workspaces describe their document as a React tree using three primitives:
-
   - `Press` — root composition boundary.
   - `Frame` — a single fixed-layout surface (replaces `BasePage` and friends).
   - `MdxArea` — a measurable slot consuming a content chain, with `overflow="extend|truncate|error"` control.
@@ -62,7 +117,6 @@
   MDX source resolution now derives manuscript TOC entries from actual `##` / `###` headings, not folder slugs. Heading numbering is written during export as `data-chapter="01"` / `data-section="1.1"` attributes so themes can render numbering with CSS without reader-side mutation.
 
   **Removed (no compatibility layer):**
-
   - `BasePage`, `BaseCoverPage`, `BaseTocPage`, `BaseContentPage`, `BaseBackCoverPage`.
   - Legacy named exports (`cover`, `toc`, `backCover`) from `document/index.tsx`.
   - The `migrate-to-react` CLI command.
@@ -74,15 +128,12 @@
   All `<Frame>` instances require a stable `frameKey`; source roots and file-list entries must stay inside `document/`.
 
   **Workspace data attributes:**
-
   - `data-frame-role` (new, opaque role like `"manuscript.content"`).
   - `data-page-kind` (derived from role's last segment — reader CSS keeps using this).
   - `data-section-id` replaces `data-chapter-slug` for section-scoped CSS.
 
   **Migration:** Workspaces written for v0.5.x must rewrite `document/index.tsx` to default-export a Press component. Pre-1.0 minor bump is acceptable per repo policy; no production deployments exist to break.
 
-  See `docs/superpowers/specs/2026-05-23-press-tree-render-architecture-design.md` for full design rationale.
-
 ## 0.6.0
 
 ### Minor Changes
@@ -123,7 +174,6 @@
 - 0169cba: Agent-driven upgrade flow.
 
   **New commands:**
-
   - `npx open-press doctor` — diagnose workspace against latest framework state. Reports `@open-press/core` version vs npm latest, installed skill count, and any pending `docs/migrations/<version>.md` notes between current and latest. `--json` for machine-readable output, `--no-cache` to bypass the 24h cache. Always exits 0 (informational only).
 
   - `npx open-press upgrade` — orchestrate the upgrade. Runs `npm update @open-press/core` (when the workspace declares the dep) and `npx skills upgrade`, then surfaces the list of migration notes for the agent to read. **Does not auto-edit `document/` content** — the agent reads the surfaced `docs/migrations/<version>.md` notes and proposes edits to the user with confirmation. Use `--dry-run` to preview, `--no-deps` / `--no-skills` to target one layer.
@@ -133,7 +183,6 @@
   `open-press dev` now runs `doctor` before starting Vite. When the workspace is behind, a single line prints: `○ open-press: @open-press/core 0.4.0 → 0.5.0 · 1 migration note(s) — run npx open-press doctor for details.` Cached for 24h, network failure is silent, never blocks dev.
 
   **Migration docs:**
-
   - New `docs/migrations/_template.md` — each release with breaking changes ships a `docs/migrations/<version>.md` file with sections the agent reads.
   - New `docs/migrations/0.4.0.md` — backfilled. Documents the SKILL fold (no document or CLI changes).
 
@@ -150,7 +199,6 @@
 ### Minor Changes
 
 - 3cb4939: Consolidate internal skills (13 → 11).
-
   - `openpress-update` folded into `openpress` as an "Updating An Existing Workspace" section. The release-upgrade flow, pre-flight checks, breaking-change reference, and do-not list are now part of the system-operation skill where they naturally belong.
   - `openpress-document-hierarchy` folded into `openpress-writing` as a "Hierarchy" section. Hierarchy decisions (H2/H3/H4 model, TOC depth, appendix placement, H4 granularity) and prose decisions happen in the same workflow; one skill, one routing decision.
   - `references/data-structures-outline.md` moved from the hierarchy skill into `openpress-writing/references/`.

package/template/core/README.md

@@ -5,10 +5,10 @@ Framework runtime, CLI engine, and Press Tree primitives for [open-press](https:
 Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
 
 ```bash
-npx @open-press/cli init my-doc --pack editorial-monograph
+npx @open-press/cli init my-doc
 ```
 
-The scaffolded workspace contains a snapshot of this package.
+The scaffolded workspace contains a snapshot of this package. Starter files are supplied by skills, not by `@open-press/core`.
 
 ## Direct use
 
@@ -31,7 +31,10 @@ import { mdxSource } from "@open-press/core/mdx";
 import { Sections, Toc } from "@open-press/core/manuscript";
 ```
 
-`document/index.tsx` default-exports a `<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+`press/index.tsx` or transitional `document/index.tsx` default-exports a `<Workspace>/<Press>` tree. `Frame` marks fixed-layout pages, `MdxArea` receives measured MDX blocks, and `mdxSource()` declares which MDX files participate in the render pipeline.
+
+For the maintenance contract around Press Tree, page geometry presets, and the
+allocation pipeline, see [`docs/press-tree.md`](https://github.com/quan0715/open-press/blob/main/docs/press-tree.md).
 
 The CLI bin (`open-press`) supports dev / build / preview / validate / pdf / deploy / export commands. It requires a workspace with `openpress.config.mjs` and the surrounding framework files (which the scaffolder installs).
 

package/template/core/engine/cli.mjs

@@ -4,25 +4,25 @@ import * as deployCmd from "./commands/deploy.mjs";
 import * as devCmd from "./commands/dev.mjs";
 import * as doctorCmd from "./commands/doctor.mjs";
 import * as exportCmd from "./commands/export.mjs";
-import * as initCmd from "./commands/init.mjs";
 import * as inspectCmd from "./commands/inspect.mjs";
+import * as imageCmd from "./commands/image.mjs";
 import * as pdfCmd from "./commands/pdf.mjs";
 import * as previewCmd from "./commands/preview.mjs";
 import * as replaceCmd from "./commands/replace.mjs";
 import * as renderCmd from "./commands/render.mjs";
 import * as searchCmd from "./commands/search.mjs";
+import * as skillsSyncCmd from "./commands/skills-sync.mjs";
 import * as typecheckCmd from "./commands/typecheck.mjs";
 import * as upgradeCmd from "./commands/upgrade.mjs";
 import * as validateCmd from "./commands/validate.mjs";
 import { parseOptions } from "./commands/_shared.mjs";
 import { loadConfig } from "./runtime/config.mjs";
-import { listStylePackSkills } from "./init.mjs";
 import { discoverWorkspace } from "./runtime/validation.mjs";
 
 const COMMANDS = {
-  init: initCmd,
   validate: validateCmd,
   inspect: inspectCmd,
+  image: imageCmd,
   search: searchCmd,
   replace: replaceCmd,
   export: exportCmd,
@@ -34,6 +34,8 @@ const COMMANDS = {
   deploy: deployCmd,
   doctor: doctorCmd,
   upgrade: upgradeCmd,
+  migrate: upgradeCmd,
+  "skills:sync": skillsSyncCmd,
 };
 
 const args = process.argv.slice(2);
@@ -71,12 +73,9 @@ async function main(commandName, argv) {
 }
 
 async function printHelp() {
-  const packs = await listStylePackSkills();
-  const skillList = packs.length ? packs.join(" | ") : "(none installed)";
   console.log(`Usage: node engine/cli.mjs <command> [path] [options]
 
 Commands:
-  init <target> [--skill <name>] [--force]
   validate
   inspect [--json] [--no-build] [--dry-run]
   search [path] <query> [--json] [--scope content|all]
@@ -86,11 +85,12 @@ Commands:
   preview --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   dev --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   typecheck
+  image [--output <outputDir>] [--no-build] [--dry-run]
   pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
   doctor [--json] [--no-cache]                          # version + skill staleness check
   upgrade [--dry-run] [--no-deps] [--no-skills] [--json] # apply updates; agent-driven
-
-Style packs available for \`init --skill\`: ${skillList}
+  migrate [--dry-run] [--no-deps] [--no-skills] [--json] # alias for upgrade; reads migration notes
+  skills:sync [--source <owner/repo>] [--dry-run]        # refresh installed agent skills
 `);
 }

package/template/core/engine/commands/_shared.mjs

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
+import { captureUrlPagesToPng, printUrlToPdf, stopChildProcess, waitForPrintReady } from "../output/chrome-pdf.mjs";
 import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
 import { exportDocument } from "../document-export.mjs";
 import { optimizePdfMediaForStaticRoot } from "../output/pdf-media.mjs";
@@ -23,6 +23,9 @@ export function parseOptions(argv) {
     else if (value === "--force") options.force = true;
     else if (value === "--confirm") options.confirm = true;
     else if (value === "--json") options.json = true;
+    else if (value === "--no-cache") options.noCache = true;
+    else if (value === "--no-deps") options.noDeps = true;
+    else if (value === "--no-skills") options.noSkills = true;
     else if (value === "--no-build") options.noBuild = true;
     else if (value === "--apply") options.apply = true;
     else if (value === "--include-code") options.includeCode = true;
@@ -38,20 +41,6 @@ export function parseOptions(argv) {
   return options;
 }
 
-export function parseInitOptions(argv) {
-  const options = { force: false };
-  const positional = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const value = argv[i];
-    if (value === "--skill") options.skill = argv[++i];
-    else if (value === "--force") options.force = true;
-    else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
-    else positional.push(value);
-  }
-  options.target = positional[0];
-  return options;
-}
-
 export function formatDisplayPath(absolutePath) {
   const relative = path.relative(process.cwd(), absolutePath);
   if (!relative || relative.startsWith("..")) return absolutePath;
@@ -118,6 +107,39 @@ export async function buildReactPdf({
   return { pdfPath: outPath };
 }
 
+export async function buildReactImages({
+  root,
+  config,
+  outDir,
+  host = "127.0.0.1",
+  port = "5186",
+  noBuild = false,
+  recurse,
+}) {
+  config ??= await loadConfig(root);
+  outDir ??= path.join(config.paths.outputDir, "images");
+  const renderCode = await buildReactStatic({ root, noBuild, recurse });
+  if (renderCode !== 0) throw new Error(`React render failed with exit code ${renderCode}`);
+  await fs.mkdir(outDir, { recursive: true });
+
+  const server = await startStaticServer(root, config, host, port);
+  try {
+    const result = await captureUrlPagesToPng({
+      root,
+      url: `http://${host}:${port}/?print=1`,
+      outDir,
+      waitForReady: waitForPrintReady,
+      debuggingPortBase: 9700,
+      debuggingPortRange: 600,
+      profilePrefix: "chrome-image",
+    });
+    console.log(`${result.files.length} OpenPress pages exported to PNG`);
+    return { outDir, files: result.files, pageCount: result.pageCount };
+  } finally {
+    await stopChildProcess(server);
+  }
+}
+
 export function startStaticServer(root, config, host, port) {
   return new Promise((resolve, reject) => {
     const child = spawn("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], {

package/template/core/engine/commands/dev.mjs

@@ -16,7 +16,7 @@ export async function run({ root, options }) {
     if (!options.noBuild) {
       console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} export .`);
     }
-    console.log(`Command: npx vite --config vite.config.ts --host ${host} --port ${port}`);
+    console.log(`Command: npx vite --force --config vite.config.ts --host ${host} --port ${port}`);
     return 0;
   }
   if (!options.noBuild) {
@@ -27,7 +27,7 @@ export async function run({ root, options }) {
   await printDoctorNoticeIfStale(root);
 
   console.log(`OpenPress dev: ${url}`);
-  return runCommand("npx", ["vite", "--config", "vite.config.ts", "--host", host, "--port", port], root);
+  return runCommand("npx", ["vite", "--force", "--config", "vite.config.ts", "--host", host, "--port", port], root);
 }
 
 async function printDoctorNoticeIfStale(root) {

package/template/core/engine/commands/image.mjs

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { CLI_ENTRY, STATIC_SERVER, buildReactImages, formatNodeScriptCommand } from "./_shared.mjs";
+
+export async function run({ root, config, options, recurse }) {
+  const outputDir = options.output ? path.resolve(root, options.output) : path.join(config.paths.outputDir, "images");
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? "5186";
+
+  if (options.dryRun) {
+    console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} render . --renderer react`);
+    console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
+    console.log(`Chrome image export URL: http://${host}:${port}/?print=1`);
+    console.log(`Output: ${path.relative(root, path.join(outputDir, "page-001.png"))}`);
+    return 0;
+  }
+
+  const result = await buildReactImages({
+    root,
+    config,
+    outDir: outputDir,
+    host,
+    port,
+    noBuild: options.noBuild,
+    recurse,
+  });
+
+  console.log(`OpenPress images: ${path.relative(root, result.outDir)} (${result.files.length} pages)`);
+  return 0;
+}

package/template/core/engine/commands/skills-sync.mjs

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { runCommand } from "./_shared.mjs";
+
+const DEFAULT_SOURCE = "quan0715/open-press";
+
+// Refresh installed agent skills against the workspace's lock file.
+// Behavior:
+//   - If skills-lock.json exists, run `npx skills upgrade` (refreshes all
+//     currently-installed sources to their latest published versions).
+//   - If skills-lock.json is missing, install the OpenPress framework
+//     skill bundle (and any user-supplied --source) as a first-time setup.
+//   - If a --source flag is passed, also add that source on top of any
+//     existing installations.
+//
+// Always exits 0 unless the underlying `skills` tool fails.
+export async function run({ root, options }) {
+  const lockPath = path.join(root, "skills-lock.json");
+  const lockExists = existsSync(lockPath);
+  const extraSource = options?.source;
+
+  if (options?.dryRun) {
+    if (lockExists) {
+      console.log("Command: npx -y skills@latest upgrade");
+    } else {
+      console.log(`Command: npx -y skills@latest add ${DEFAULT_SOURCE}`);
+    }
+    if (extraSource) {
+      console.log(`Command: npx -y skills@latest add ${extraSource}`);
+    }
+    return 0;
+  }
+
+  if (lockExists) {
+    const sources = await readLockSources(lockPath);
+    if (sources.length === 0) {
+      console.log("skills-lock.json has no sources; installing framework default…");
+      const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+      if (code !== 0) return code;
+    } else {
+      console.log(`Refreshing ${sources.length} installed source(s)…`);
+      for (const src of sources) console.log(`  ${src}`);
+      const code = await runCommand("npx", ["-y", "skills@latest", "upgrade"], root);
+      if (code !== 0) return code;
+    }
+  } else {
+    console.log(`No skills-lock.json; installing framework default: ${DEFAULT_SOURCE}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", DEFAULT_SOURCE], root);
+    if (code !== 0) return code;
+  }
+
+  if (extraSource) {
+    console.log(`Adding extra source: ${extraSource}`);
+    const code = await runCommand("npx", ["-y", "skills@latest", "add", extraSource], root);
+    if (code !== 0) return code;
+  }
+
+  console.log("✓ Skills synced");
+  return 0;
+}
+
+async function readLockSources(lockPath) {
+  try {
+    const lock = JSON.parse(await readFile(lockPath, "utf8"));
+    const sources = Array.isArray(lock?.sources) ? lock.sources : [];
+    return sources.map((s) => s?.source).filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}

package/template/core/engine/commands/typecheck.mjs

@@ -1,5 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
 import { runCommand } from "./_shared.mjs";
 
+// Run typecheck via the locally installed typescript. The previous
+// implementation used `npx tsc`; npm 11 + Node 24 (our CI / release
+// pin) changed npx's bin lookup so it no longer walks pnpm's nested
+// `.bin/` symlink farm and falls back to fetching the legacy
+// `tsc@2.0.4` shim, which crashes.
+//
+// Resolution order:
+//   1. `node <resolved tsc>` via require.resolve(typescript/package.json)
+//      — works with npm-hoisted layouts and most pnpm installs.
+//   2. Walk up node_modules/.bin/tsc — covers downstream npm/yarn.
+//   3. Fall back to `pnpm exec tsc` — pnpm knows its own symlink farm
+//      even when bare require.resolve doesn't, which is what CI hits.
 export async function run({ root }) {
-  return runCommand("npx", ["tsc", "--noEmit", "-p", "tsconfig.json"], root);
+  const absoluteRoot = path.resolve(root);
+
+  const tscBin = resolveTscBin(absoluteRoot);
+  if (tscBin) {
+    return runCommand("node", [tscBin, "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  if (hasCommand("pnpm")) {
+    return runCommand("pnpm", ["exec", "tsc", "--noEmit", "-p", "tsconfig.json"], absoluteRoot);
+  }
+
+  console.error("[openpress] typescript is not installed in this workspace.");
+  console.error("Add it with: npm install --save-dev typescript");
+  return 1;
+}
+
+function resolveTscBin(absoluteRoot) {
+  try {
+    const require = createRequire(path.join(absoluteRoot, "package.json"));
+    const pkgPath = require.resolve("typescript/package.json");
+    return path.join(path.dirname(pkgPath), "bin", "tsc");
+  } catch {
+    // fall through to .bin probe
+  }
+
+  let dir = absoluteRoot;
+  while (true) {
+    const candidate = path.join(dir, "node_modules", ".bin", "tsc");
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function hasCommand(name) {
+  const PATH = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
+    : [""];
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      if (fs.existsSync(path.join(dir, name + ext))) return true;
+    }
+  }
+  return false;
 }

package/template/core/engine/commands/upgrade.mjs

@@ -46,7 +46,7 @@ export async function run({ root, options }) {
     if (!json) {
       process.stdout.write("dry run — nothing changed. The agent should:\n");
       process.stdout.write("  1. read each docs/migrations/<version>.md for document-level changes\n");
-      process.stdout.write("  2. apply edits to document/ where needed\n");
+      process.stdout.write("  2. apply edits to press/ where needed\n");
       process.stdout.write("  3. re-run: npx open-press upgrade   (without --dry-run)\n");
     } else {
       process.stdout.write(JSON.stringify({ status: "dry-run", before }, null, 2) + "\n");
@@ -98,11 +98,11 @@ export async function run({ root, options }) {
       }
     }
     process.stdout.write(
-      "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
+      "\nAgent: open each file, identify document-level changes, grep press/ for affected patterns, propose edits before applying.\n",
     );
   }
 
-  process.stdout.write("\nVerify with:\n  npm run openpress:validate\n  npm run openpress:render\n\n");
+  process.stdout.write("\nVerify with:\n  npm run build\n\n");
   return 0;
 }
 

package/template/core/engine/document-export.mjs

@@ -10,6 +10,6 @@ export async function exportDocument(root = ROOT) {
   if (reactResult) return reactResult;
 
   throw new Error(
-    "React/MDX document entry not found. Expected document/index.tsx with a Press default export before exporting.",
+    "React/MDX document entry not found. Expected press/index.tsx with a Press default export before exporting.",
   );
 }