@open-press/cli 0.8.0 → 1.0.0

package/README.md

@@ -9,13 +9,15 @@ Node.js 20 or newer with `npm` / `npx`.
 ## Quick start
 
 ```bash
-npx @open-press/cli init my-doc --pack editorial-monograph
+npx @open-press/cli init my-doc
 cd my-doc
 npm run dev
 ```
 
 Then open the local URL printed by Vite (typically `http://127.0.0.1:5173/?dev=1`).
 
+The CLI creates the OpenPress runtime workspace only. Starters and examples live in skills, installed separately with `npx skills add <owner/repo>`. The starter-bearing skills in the framework repo are just skills; agents can read and use them directly.
+
 ## Usage
 
 ```
@@ -24,40 +26,49 @@ npx @open-press/cli init <target> [flags]
 
 | Flag                 | Description                                                                 |
 | -------------------- | --------------------------------------------------------------------------- |
-| `--pack <name>`      | Style pack starter: `editorial-monograph`, `claude-document`, or `academic-paper` |
-| `--title <s>`        | Document title (written to `openpress.config.mjs`)                          |
+| `--title <s>`        | Document title (written to workspace config)                                |
 | `--subtitle <s>`     | Document subtitle                                                           |
 | `--organization <s>` | Organization name                                                           |
 | `--author <s>`       | Author name                                                                 |
-| `--no-git`           | Skip `git init`                                                             |
-| `--no-install`       | Skip `npm install`                                                          |
-| `--force`            | Allow scaffolding into a non-empty target                                   |
+| `--no-git`           | Skip `git init` + initial commit (use when scaffolding inside an existing repo) |
+| `--no-install`       | Skip `npm install` (offline, or you'll run pnpm/bun yourself)              |
 | `--help`             | Print help                                                                  |
 
+> The target must be empty. A `.git/` directory or other harmless dotfiles (`.gitignore`, `.gitkeep`, `.DS_Store`) are ignored — common when scaffolding into a fresh repo.
+
+To use an opinionated starter, install a skill and let the agent read that skill's files:
+
+```bash
+npx -y skills@latest add quan0715/openpress-social-card-skill
+```
+
 ## What it creates
 
 A self-contained workspace with:
 
 - `engine/`, `src/`, `vite.config.ts` — the open-press framework (snapshot of `@open-press/core`)
-- `document/` — your content (populated from the chosen style pack)
 - `.claude/skills/` and `.agents/skills/` — agent skill files for Claude Code, Codex, Cursor, Copilot, etc.
 - `openpress.config.mjs` — workspace metadata (title, subtitle, organization, author)
 - `AGENTS.md` — agent contract
 
+The `press/` or transitional `document/` source tree is added by a skill, user-authored code, or a project-specific workflow after init.
+
 ## After init
 
 Workspace commands (run via `npm run` or `node engine/cli.mjs`):
 
 ```
-npm run dev         # start workbench
-npm run openpress:export   # refresh public/openpress/document.json
-npm run build       # render production output (dist-react/)
-npm run preview     # preview production build
-npm run openpress:validate   # structural checks
-npm run openpress:pdf        # render PDF
-npm run openpress:deploy:dry-run
+npm run dev                       # start workbench
+npm run build                     # validate + render dist-react/
+npm run preview                   # preview production build
+npm run typecheck                 # tsc --noEmit
+npm run openpress:image           # render one PNG per page
+npm run openpress:pdf             # render PDF
+npm run openpress:deploy:dry-run  # preview deploy without publishing
 ```
 
+Full reference: <https://open-press.dev/docs/cli>
+
 ## License
 
 MIT — see [LICENSE](https://github.com/quan0715/open-press/blob/main/LICENSE).

package/dist/cli.js

@@ -6,61 +6,21 @@ import process2 from "process";
 // src/init.ts
 import { spawn } from "child_process";
 import { existsSync } from "fs";
-import { cp, mkdir as mkdir2, rm as rm2 } from "fs/promises";
-import path2 from "path";
+import { cp, mkdir } from "fs/promises";
+import path from "path";
 import process from "process";
 import { fileURLToPath } from "url";
 
-// src/degit.ts
-import { createWriteStream } from "fs";
-import { mkdir, rm, stat } from "fs/promises";
-import { tmpdir } from "os";
-import path from "path";
-import { Readable } from "stream";
-import { pipeline } from "stream/promises";
-import { x as extract } from "tar";
-async function degit({ owner, repo, ref = "main", dest, subdir }) {
-  const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/${ref}`;
-  const tmpDir = await mkdir(path.join(tmpdir(), `open-press-degit-${Date.now()}`), { recursive: true });
-  const tarballPath = path.join(tmpDir, "repo.tar.gz");
-  try {
-    await fetchTo(url, tarballPath);
-    await mkdir(dest, { recursive: true });
-    const subdirSegments = subdir ? subdir.split("/").filter(Boolean).length : 0;
-    const totalStrip = 1 + subdirSegments;
-    const filterPrefix = subdir ? subdir.replace(/\/$/, "") + "/" : null;
-    await extract({
-      file: tarballPath,
-      cwd: dest,
-      strip: totalStrip,
-      filter: (filePath) => {
-        const segments = filePath.split("/");
-        const inside = segments.slice(1).join("/");
-        if (filterPrefix) {
-          return inside.startsWith(filterPrefix);
-        }
-        return true;
-      }
-    });
-  } finally {
-    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
-    });
-  }
-}
-async function fetchTo(url, destFile) {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok || !res.body) {
-    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
-  }
-  await pipeline(Readable.fromWeb(res.body), createWriteStream(destFile));
-}
-async function pathIsEmpty(target) {
+// src/path-is-empty.ts
+import { readdir, stat } from "fs/promises";
+var HARMLESS_TARGET_ENTRIES = /* @__PURE__ */ new Set([".git", ".gitignore", ".gitkeep", ".DS_Store"]);
+async function pathIsEmpty(target, options = {}) {
   try {
     const s = await stat(target);
     if (!s.isDirectory()) return false;
-    const { readdir } = await import("fs/promises");
     const entries = await readdir(target);
-    return entries.length === 0;
+    if (!options.ignoreHarmless) return entries.length === 0;
+    return entries.every((entry) => HARMLESS_TARGET_ENTRIES.has(entry));
   } catch {
     return true;
   }
@@ -68,20 +28,17 @@ async function pathIsEmpty(target) {
 
 // src/metadata.ts
 import { readFile, writeFile } from "fs/promises";
-async function patchOpenpressConfig(configPath, patch) {
-  let source = await readFile(configPath, "utf8");
-  for (const [key, value] of Object.entries(patch)) {
-    if (value === void 0 || value === null || value === "") continue;
-    const escaped = escapeStringForJs(value);
-    const re = new RegExp(`(${key}\\s*:\\s*)("[^"]*"|'[^']*'|\`[^\`]*\`)`, "m");
-    if (re.test(source)) {
-      source = source.replace(re, `$1"${escaped}"`);
-    } else {
-      source = source.replace(/(export\s+default\s*\{)/, `$1
-  ${key}: "${escaped}",`);
-    }
+async function patchPressTitle(entryPath, title) {
+  const source = await readFile(entryPath, "utf8");
+  const escaped = escapeStringForJs(title);
+  const existing = /(<Press\b[^>]*\btitle\s*=\s*)("[^"]*"|'[^']*'|\{`[^`]*`\})/;
+  let next;
+  if (existing.test(source)) {
+    next = source.replace(existing, `$1"${escaped}"`);
+  } else {
+    next = source.replace(/<Press\b/, `<Press title="${escaped}"`);
   }
-  await writeFile(configPath, source);
+  await writeFile(entryPath, next);
 }
 function escapeStringForJs(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -115,69 +72,27 @@ async function patchPackageJsonName(packagePath, newName) {
 }
 
 // src/init.ts
-var BUNDLED_PACKS = ["editorial-monograph", "claude-document", "academic-paper"];
 var FRAMEWORK_SKILLS_SOURCE = "quan0715/open-press";
-var __dirname = path2.dirname(fileURLToPath(import.meta.url));
-var TEMPLATE_ROOT = path2.resolve(__dirname, "..", "template");
-var TEMPLATE_CORE = path2.join(TEMPLATE_ROOT, "core");
-var TEMPLATE_PACKS = path2.join(TEMPLATE_ROOT, "packs");
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var TEMPLATE_ROOT = path.resolve(__dirname, "..", "template");
+var TEMPLATE_CORE = path.join(TEMPLATE_ROOT, "core");
 async function init(options) {
-  const packSpec = options.pack ? parsePackSpec(options.pack) : null;
   ensureTemplateBundled();
-  const target = path2.resolve(process.cwd(), options.target);
-  await ensureTarget(target, options.force);
+  const target = path.resolve(process.cwd(), options.target);
+  await ensureTarget(target);
   log(`Creating open-press workspace at ${target}`);
   log("Copying framework (engine + runtime + config)\u2026");
   await cp(TEMPLATE_CORE, target, { recursive: true });
-  const docDest = path2.join(target, "document");
-  await rm2(docDest, { recursive: true, force: true });
-  await mkdir2(docDest, { recursive: true });
-  if (packSpec?.kind === "bundled") {
-    log(`Applying bundled style pack: ${packSpec.name}`);
-    const packStarter = path2.join(TEMPLATE_PACKS, packSpec.name, "document");
-    if (!existsSync(packStarter)) {
-      throw new Error(`Bundled style pack starter not found: ${packStarter}`);
-    }
-    await cp(packStarter, docDest, { recursive: true });
-  } else if (packSpec?.kind === "github") {
-    log(`Fetching style pack from github:${packSpec.owner}/${packSpec.repo}${packSpec.ref ? `#${packSpec.ref}` : ""}\u2026`);
-    try {
-      await degit({
-        owner: packSpec.owner,
-        repo: packSpec.repo,
-        ref: packSpec.ref,
-        dest: docDest,
-        subdir: "starter/document"
-      });
-    } catch (err) {
-      throw new Error(
-        `Failed to fetch pack from github:${packSpec.owner}/${packSpec.repo}: ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-    if (await pathIsEmpty(docDest)) {
-      throw new Error(
-        `github:${packSpec.owner}/${packSpec.repo} doesn't contain starter/document/ at the repo root.
-Third-party pack repos should follow this layout:
-  <repo>/
-  \u251C\u2500\u2500 starter/
-  \u2502   \u2514\u2500\u2500 document/   \u2190 cli copies this into your workspace's document/
-  \u2514\u2500\u2500 skills/<pack>/SKILL.md   \u2190 npx skills add picks this up`
-      );
-    }
-  }
-  const pkgPath = path2.join(target, "package.json");
+  const pkgPath = path.join(target, "package.json");
   if (existsSync(pkgPath)) {
-    await patchPackageJsonName(pkgPath, path2.basename(target));
+    await patchPackageJsonName(pkgPath, path.basename(target));
   }
-  const configPath = path2.join(target, "openpress.config.mjs");
-  if (existsSync(configPath) && hasMetadata(options)) {
-    log("Writing metadata into openpress.config.mjs");
-    await patchOpenpressConfig(configPath, {
-      title: options.title,
-      subtitle: options.subtitle,
-      organization: options.organization,
-      author: options.author
-    });
+  if (options.title) {
+    const pressEntry = path.join(target, "press", "index.tsx");
+    if (existsSync(pressEntry)) {
+      log("Writing title into <Press> in press/index.tsx");
+      await patchPressTitle(pressEntry, options.title);
+    }
   }
   log(`Installing framework skills via \`npx skills add ${FRAMEWORK_SKILLS_SOURCE}\`\u2026`);
   try {
@@ -186,16 +101,6 @@ Third-party pack repos should follow this layout:
     log(`(framework skills install failed; retry: npx skills add ${FRAMEWORK_SKILLS_SOURCE})`);
     log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
   }
-  if (packSpec?.kind === "github") {
-    const packSource = `${packSpec.owner}/${packSpec.repo}`;
-    log(`Installing pack skills via \`npx skills add ${packSource}\`\u2026`);
-    try {
-      await runInTarget(target, "npx", ["-y", "skills@latest", "add", packSource]);
-    } catch (err) {
-      log(`(pack skills install failed; retry: npx skills add ${packSource})`);
-      log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
   if (options.install) {
     log("Installing dependencies (npm install)\u2026");
     await runInTarget(target, "npm", ["install"]);
@@ -216,46 +121,24 @@ Third-party pack repos should follow this layout:
   }
   printNextSteps(target, options);
 }
-function parsePackSpec(spec) {
-  if (spec.startsWith("github:")) {
-    const rest = spec.slice("github:".length);
-    const [pathPart, ref] = rest.split("#");
-    const segments = pathPart.split("/").filter(Boolean);
-    if (segments.length !== 2) {
-      throw new Error(
-        `Invalid --pack spec: "${spec}". Use github:owner/repo or github:owner/repo#ref.`
-      );
-    }
-    const [owner, repo] = segments;
-    return { kind: "github", owner, repo, ref: ref?.trim() || void 0 };
-  }
-  if (!BUNDLED_PACKS.includes(spec)) {
-    throw new Error(
-      `Unknown style pack: "${spec}". Bundled packs: ${BUNDLED_PACKS.join(", ")}. For third-party packs use github:owner/repo (e.g. github:quan0715/openpress-pack-nycu-thesis).`
-    );
-  }
-  return { kind: "bundled", name: spec };
-}
 function ensureTemplateBundled() {
-  if (!existsSync(TEMPLATE_CORE) || !existsSync(TEMPLATE_PACKS)) {
+  if (!existsSync(TEMPLATE_CORE)) {
     throw new Error(
       `Template not bundled at ${TEMPLATE_ROOT}. If running from source, run \`pnpm sync:template\` in packages/cli first.`
     );
   }
 }
-async function ensureTarget(target, force) {
+async function ensureTarget(target) {
   if (existsSync(target)) {
-    if (force) return;
-    const empty = await pathIsEmpty(target);
+    const empty = await pathIsEmpty(target, { ignoreHarmless: true });
     if (!empty) {
-      throw new Error(`Target ${target} is not empty. Pass --force to scaffold into it anyway.`);
+      throw new Error(
+        `Target ${target} is not empty. Remove existing files first, or scaffold into a different directory.`
+      );
     }
     return;
   }
-  await mkdir2(target, { recursive: true });
-}
-function hasMetadata(options) {
-  return Boolean(options.title || options.subtitle || options.organization || options.author);
+  await mkdir(target, { recursive: true });
 }
 async function runInTarget(cwd, command, args, opts = {}) {
   return new Promise((resolve, reject) => {
@@ -276,7 +159,7 @@ function log(message) {
 `);
 }
 function printNextSteps(target, options) {
-  const rel = path2.relative(process.cwd(), target) || ".";
+  const rel = path.relative(process.cwd(), target) || ".";
   const lines = [
     "",
     "\u2713 Done. Your open-press workspace is ready.",
@@ -297,7 +180,7 @@ function printNextSteps(target, options) {
     "Agent skills installed under .agents/skills/ (universal \u2014 read by Claude Code,",
     `Cursor, Codex, Gemini CLI, etc.). Update later with: npx skills upgrade`,
     "",
-    "Edit content under document/chapters/, or ask your AI agent to help.",
+    "Use an OpenPress-ready skill to add or adapt the press/document source tree.",
     ""
   );
   process.stdout.write(lines.join("\n"));
@@ -310,28 +193,14 @@ Usage:
   npx @open-press/cli init <target> [flags]
 
 Flags:
-  --pack <spec>            Style pack source. Either:
-                             \u2022 a bundled name \u2014 editorial-monograph | claude-document | academic-paper
-                             \u2022 github:owner/repo (third-party pack)
-                             \u2022 github:owner/repo#branch-or-tag
-  --title <s>              Document title (written to openpress.config.mjs)
-  --subtitle <s>           Document subtitle
-  --organization <s>       Organization name
-  --author <s>             Author name
+  --title <s>              Document title (written into <Press title="..."> in press/index.tsx)
   --no-git                 Skip git init
   --no-install             Skip npm install
-  --force                  Allow non-empty target
   --help                   Show this help
 
 Examples:
-  # Bundled
-  npx @open-press/cli init my-doc --pack editorial-monograph
-  npx @open-press/cli init my-brief --pack claude-document --title "Q2 Brief" --author Quan
-  npx @open-press/cli init my-paper --pack academic-paper --title "Paper Title" --author "First Author"
-
-  # Third-party (any GitHub repo with starter/document/ at the root)
-  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
-  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
+  npx @open-press/cli init my-doc
+  npx @open-press/cli init my-brief --title "Q2 Brief"
 `;
 async function main(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
@@ -368,33 +237,16 @@ function parseInitArgs(args) {
   }
   const options = {
     target: "",
-    pack: void 0,
     title: void 0,
-    subtitle: void 0,
-    organization: void 0,
-    author: void 0,
     git: true,
-    install: true,
-    force: false
+    install: true
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     switch (arg) {
-      case "--pack":
-        options.pack = args[++i];
-        break;
       case "--title":
         options.title = args[++i];
         break;
-      case "--subtitle":
-        options.subtitle = args[++i];
-        break;
-      case "--organization":
-        options.organization = args[++i];
-        break;
-      case "--author":
-        options.author = args[++i];
-        break;
       case "--no-git":
         options.git = false;
         break;
@@ -407,9 +259,6 @@ function parseInitArgs(args) {
       case "--install":
         options.install = true;
         break;
-      case "--force":
-        options.force = true;
-        break;
       default:
         if (arg.startsWith("--")) {
           process2.stderr.write(`Unknown flag: ${arg}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Scaffolder for open-press — AI-first fixed-layout document workspaces.",
   "license": "MIT",
@@ -40,9 +40,7 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "tar": "^7.5.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^25.8.0",
     "tsup": "^8.5.0",
@@ -52,6 +50,7 @@
     "sync:template": "node scripts/sync-template.mjs",
     "build": "pnpm sync:template && tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && node --test tests/*.test.mjs"
   }
 }

package/template/core/AGENTS.md

@@ -16,15 +16,19 @@ will rewrite it.
 
 ```bash
 npm run dev                  # workbench at http://127.0.0.1:5173/?dev=1
-npm run openpress:validate   # structural checks
-npm run openpress:render     # full render through chromium
+npm run build                # validate + render dist-react/
+npm run openpress:image      # write dist-react/images/page-*.png
 npm run openpress:pdf        # write document.pdf
-npm run openpress:export     # write public/openpress/document.json
 npm run openpress:deploy     # deploy via the configured adapter
 npx open-press doctor        # current vs latest version + pending migrations
 npx open-press upgrade       # apply the upgrade flow (see below)
 ```
 
+The intermediate engine steps live behind `node engine/cli.mjs` if you
+need them directly (rarely): `validate` (source-level checks only,
+fast), `export` (write `public/openpress/document.json` without
+bundling), `inspect` (post-render geometry + comment markers).
+
 ## When the user asks to upgrade
 
 Triggers: "升級 / 套件更新 / upgrade open-press / apply latest design /
@@ -44,8 +48,7 @@ update to vX.Y.Z" etc.
    Apply to `document/` with user confirmation.
 5. Verify:
    ```bash
-   npm run openpress:validate
-   npm run openpress:render
+   npm run build
    ```
    Fix anything broken using the migration notes.
 6. Report to the user: starting version → ending version, what was
@@ -73,32 +76,33 @@ regenerate `document.json`. So edits to:
 the change:
 
 ```bash
-npm run openpress:export   # regenerate public/openpress/document.json
+npm run build              # validate + render (includes the export step)
 # then refresh the browser
+# — or, for the inner export only, without the full Vite bundle step:
+node engine/cli.mjs export .
 ```
 
 Quick rules of thumb:
 
 - Pure CSS edits under `document/theme/` that don't move blocks → HMR
   is enough (CSS is hot-replaced).
-- Anything that affects content, pagination, or metadata → re-export.
-- `npm run openpress:render` is `export` + extra asset sync; either
-  works to refresh the JSON.
+- Anything that affects content, pagination, or metadata → re-build (or
+  call `node engine/cli.mjs export .` for just the JSON refresh).
 
 **Agent SOP**: after applying any non-CSS edit to `document/`, run
-`npm run openpress:export` before telling the user "done". If they ask
-"why didn't my change show up?", check whether `document.json` was
+`npm run build` before telling the user "done". If they ask "why
+didn't my change show up?", check whether `document.json` was
 regenerated since the edit.
 
 ## When the user reports a render / paginate issue
 
 Press Tree paginates at build time. Common things to check:
 
-1. `npm run openpress:export` then inspect
+1. `npm run build` then inspect
    `public/openpress/document.json` for `source.warnings` (chain
    overflow, missing chains, etc.).
-2. `npm run openpress:validate` for structural issues
-   (missing entries, broken anchors).
+2. `node engine/cli.mjs validate .` for structural issues
+   (missing entries, broken anchors) — faster than a full build.
 3. `npm run dev` and use the workbench inspector to find which MDX
    block / Frame element is misbehaving — comments and inline
    annotations work directly from there.

package/template/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
@@ -50,7 +62,6 @@
 ### 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.
@@ -72,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.
@@ -107,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.
@@ -119,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
@@ -168,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.
@@ -178,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).
 
@@ -195,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).