@ryanyahya/opendoc 0.4.0

package/README.md

@@ -0,0 +1,179 @@
+# OpenDoc
+
+An open-source document-production workspace for making well-designed English documents and presentations with a coding agent, on your computer or in a remote agent environment.
+
+Open source under the [MIT license](LICENSE). Start with the included welcome document and presentation; no personal workspace, account, or API key is included or required.
+
+In normal OpenDoc, **Documents** and **Presentations** have separate library pages and share the same PDF reader, text corrections, comments, projects, media, and assets. Presentations use explicit 16:9 slides with strict overflow checks. Create one with `npx opendoc create my-deck --project client-work --title "My presentation" --format presentation`, then author it using `Presentation` and `Slide`; see [presentation authoring](docs/AUTHORING.md#presentations). **Templates → Presentations** offers researched Pitch deck, Brand guidelines, Company profile, and Proposal deck skeletons. Use `--template <id>` to start from one; its presentation format is inferred. Current themes supply fonts and colors.
+
+Bring a brief and your source material. An external coding agent authors and designs the work using native PDF components. Normal OpenDoc gives you a browser workspace for review, quick text corrections, and comments. OpenDoc Headless lets a remote agent complete the same authoring, review, and export workflow, then deliver the finished PDF or editable PowerPoint through its existing channel. The recipient needs no OpenDoc installation.
+
+Both editions share one repository, release version, engine, authoring API, and **full starter library** of editable templates, themes, fonts, and welcome examples. Your source and assets live in the workspace environment you choose. Headless removes the browser interface and its service dependencies; it does not remove the design library or introduce a hosted service, embedded AI, or messaging connector.
+
+## Start
+
+Requires **Node.js 24 or newer** and **npm** on macOS or Linux in the environment running OpenDoc. Windows has not yet been verified.
+
+### Normal OpenDoc
+
+For the browser workspace on your computer:
+
+```sh
+npx @ryanyahya/opendoc init
+```
+
+The default location is `~/Documents/My OpenDoc`. Choose another location by passing it as the destination, for example `npx @ryanyahya/opendoc init ~/Documents/ClientPublications`. The destination must be new or empty. Initialization installs a pinned OpenDoc version, copies the welcome documents and editable catalogs, starts the local service in the foreground, and opens your browser. Use `--no-start` to create the workspace without launching, or `--no-open` to start without opening a browser.
+
+Keep the terminal running while you use the app; press **Ctrl-C** to stop it. Open the localhost URL printed there if the browser does not open. The workspace starts with **Getting started → Welcome to OpenDoc**. Use the **+ beside Projects** in the sidebar to create a home for your work. **Create document** and **Create presentation** give you a prompt to paste into your coding agent; add your brief and material. The prompt carries any selected project, template, or theme. The resulting work appears automatically.
+
+To return later:
+
+```sh
+cd "$HOME/Documents/My OpenDoc"
+npx opendoc start
+```
+
+Document, template, theme, and asset edits refresh while the service runs. Commands find the workspace from your current directory or any parent; `--workspace /path/to/workspace` targets one explicitly. Run `npx opendoc --help` to discover commands, `<command> --help` for details, and add `--json` for structured output.
+
+Installation and updates need network access; the app runs locally afterward without an account or API key. An external coding agent may have its own requirements. The service listens on loopback; use the printed address instead of assuming a port. `OPENDOC_PORT` requests a fixed port.
+
+### OpenDoc Headless
+
+Install where your remote agent runs, with an explicit new or empty destination:
+
+```sh
+npx --yes @ryanyahya/opendoc-headless init ./workspace --json
+cd ./workspace
+npx opendoc check --json
+npx opendoc review welcome --json
+npx opendoc export welcome --json
+```
+
+Initialization is noninteractive and never opens a browser or starts a service. The welcome export is `output/welcome.pdf`; the review command supplies its page images, text, and technical issues for the agent to inspect. For actual work, the agent writes the requested content, checks and reviews it, revises it, then exports and delivers the requested files. A successful render alone is not a completed review.
+
+Inside either edition, commands remain `npx opendoc` and authoring imports remain `opendoc`. Both use the `opendoc` dependency key with an exact npm alias: `npm:@ryanyahya/opendoc@<version>` for normal OpenDoc or `npm:@ryanyahya/opendoc-headless@<version>` for Headless. The Headless alias resolves its authoring imports without installing the normal application. The workspace can persist for future revisions and reusable themes/templates, or be disposable for a single job. See [OpenDoc Headless](docs/HEADLESS.md) for the complete remote workflow, specimen creation, structured results, and file delivery.
+
+## Update an existing workspace
+
+In normal OpenDoc, first stop the foreground service with **Ctrl-C**. Then run this from either edition's workspace:
+
+```sh
+npx opendoc update
+```
+
+By default, the updater chooses the latest release within the installed version's compatible range and pins its exact version. `npx opendoc update --check` reports available versions without changing the installation. Use `npx opendoc update --version <exact-version>` to choose a published stable release explicitly, including an upgrade or downgrade outside that range; tags, ranges, and prereleases are not accepted.
+
+Updates preserve the chosen edition: normal OpenDoc updates from `@ryanyahya/opendoc`; Headless updates from `@ryanyahya/opendoc-headless`. They replace the application and its versioned guides while preserving your documents, templates, themes, assets, feedback, and project records. They do not merge new catalog examples into an existing workspace or migrate an old source checkout. Keep working in the initialized workspace; restart with `npx opendoc start` when using the normal browser edition.
+
+## Create and revise
+
+Both editions use the same [agent guide](AGENTS.md) and skills. In Headless, the agent works from explicit task context and catalog IDs and delivers files remotely; it does not require an active browser selection. The following browser interactions apply to normal OpenDoc.
+
+The book icon in the sidebar and PDF reader opens a quick index of the six `opendoc-` skills. Hover, focus, or tap it to see each skill's name and purpose. The root [AGENTS.md](AGENTS.md) routes ordinary requests to the matching workflow; naming a skill is optional. The app does not run the agent itself.
+
+Open your workspace folder in your coding agent and ask:
+
+> Create a presentation from these notes for our project kickoff. Use our project theme. Ask me if you need to clarify the audience or template.
+
+The workspace's `AGENTS.md` and `.agents/skills/` point to the guidance shipped with its installed OpenDoc version. The agent uses [opendoc-create](.agents/skills/opendoc-create/SKILL.md) for both documents and presentations. It follows explicit choices, asks when a meaningful theme or template preference is unclear, and exercises judgment when design is delegated. Documents are delivered as reviewed PDFs; presentations include both PDF and editable PowerPoint unless you request otherwise. You can also invoke `$opendoc-create` explicitly. Edit your content in the workspace; the app and complete guides live under `node_modules/opendoc/`.
+
+The agent resolves a project and design direction, then creates the source through the supported command. For a written brief:
+
+```sh
+npx opendoc projects create client-work --name "Client work" --theme neutral
+npx opendoc create my-brief --project client-work --title "A better handoff"
+```
+
+Creation makes a minimal draft, its project assignment, exact asset selections in `assets.json`, and a `theme.tsx` adapter. The agent develops `documents/my-brief/index.tsx` using native PDF components. A project theme is a default for future documents; moving a document or changing that default leaves existing choices intact.
+
+**Templates** offers reusable layouts with real PDF specimens and a readable **View AGENTS.md** guide. **Themes** offers design systems with their own components, palettes, typography, and design guides. Pick a template when its structure helps; the brief can also call for a bespoke document. [Authoring](docs/AUTHORING.md) describes the component API.
+
+In the reader, select a component and choose **Edit** or **Comment**. Text edits preview as a browser draft; **Save all** writes the group to local source. Drafts survive navigation and reload in the same tab. Formatting, calculations, and structural changes belong with your agent. Comments save independently, retain their history, and stay attached through reflow when block identities are preserved. [Selection and corrections](docs/SELECTION.md) explains supported edits and conflict recovery.
+
+Use the document **…** menu to rename, duplicate, move, or delete it. Rename changes the library name, while the PDF title remains authored content. Duplicate copies saved source, local data, media, and feedback. Delete offers Undo and keeps a recovery folder in `.opendoc/trash/`; existing exports remain in `output/`. [Projects](docs/PROJECTS.md) covers membership and recovery.
+
+## Use media, logos, and fonts
+
+**Media & Assets** separates document-owned visuals from reusable families:
+
+- **Media:** photographs, illustrations, charts, and diagrams, with each visual's metadata and optional prepared data and recipe beside it. Add or regenerate these with your agent. Original reference material stays in its existing project location. See [Media](docs/MEDIA.md).
+- **Logos:** import SVG or PNG, add named variations, and describe when to use each. A saved document binding pins the chosen version. Place it explicitly with `Logo`; the app's appearance does not select artwork.
+- **Fonts:** import original static TTF/OTF faces and inspect their real PDF specimens. Inter, Roboto, Open Sans, Lato, and Merriweather are bundled with six styles each; Geist includes regular, medium, and bold. Each family retains its license. Fonts must pass compatibility checks before becoming body or heading defaults.
+
+Theme details can choose assets for **new documents**. Updating a family or theme default does not silently change an existing document. Use the app or the same local CLI, described in [Assets](docs/ASSETS.md):
+
+```sh
+npx opendoc assets list
+npx opendoc assets inspect logo acme
+npx opendoc assets bind my-brief logo acme
+```
+
+## Review and export
+
+Both editions can prepare review evidence without a browser:
+
+```sh
+npx opendoc review my-brief --json
+npx opendoc review --theme neutral --json
+npx opendoc review --template editorial-essay --json
+```
+
+Each successful result supplies a PDF, page PNGs, extracted text, render issues, and a manifest identifying the exact PDF revision and its sources. The command renders saved workspace source directly; in normal OpenDoc, save intended browser text corrections first. The agent inspects these artifacts and refines the work before final export. The manifest's `visualReview` and `factualReview` stay `required`: preparing evidence does not perform those reviews. See [Headless review](docs/HEADLESS.md#author-inspect-revise-deliver).
+
+In normal OpenDoc, the reader shows the real PDF, including navigation, links, and current render warnings. An invalid revision keeps the last successful preview visible and blocks export until corrected. Review the current ready PDF, including every page, source notes, and representative copied text. The [opendoc-review-document skill](.agents/skills/opendoc-review-document/SKILL.md) supplies the final pass.
+
+In the browser, **Export → Save PDF** saves the reviewed bytes in `output/`, preserving existing files with numbered names. Save pending text corrections and review the updated PDF first. The result can reveal the file, download a copy, or open the PDF to print. For presentations, choose **PowerPoint (.pptx)** to save editable text and shapes with embedded fonts. Images and existing chart artwork remain images. On macOS it can also copy the exported file to the system clipboard. **Previous exports** lists saved files with open, reveal, and delete-with-Undo actions. If a save response is interrupted, **Check export** recovers the same request.
+
+Command-line export supports single documents and batches:
+
+```sh
+npx opendoc export my-brief
+npx opendoc export welcome-presentation --format pptx
+npx opendoc export welcome my-brief --json
+npx opendoc export --all --json
+```
+
+PowerPoint export uses the successful render’s content, media, and font bytes. It supports 16:9 slides with editable text, rectangular shapes, and images. Unsupported effects or fonts produce a specific error and preserve existing exports. Tables composed from individual blocks stay separate objects; chart images stay images. Embedded fonts must permit editing and have TrueType outlines. Representative slides were reviewed in PowerPoint on macOS; Windows compatibility has not yet been verified.
+
+CLI export writes `output/<id>.pdf` or `output/<id>.pptx`, replacing that document's previous CLI output only after successful rendering and freshness checks. In normal OpenDoc, a running local service supplies current preview bytes; without it, export renders fresh. Headless always renders directly and does not consult a browser session. Inspect each batch result. Saved exports are independent of later edits and retain their asset provenance when available.
+
+## Find the right guide
+
+For development and pull requests, read [Contributing](CONTRIBUTING.md). Review the local trust model in [Security](SECURITY.md) and the bundled notices in [Third-party notices](THIRD_PARTY.md).
+
+| Task | Read |
+| --- | --- |
+| First agent task or source conventions | [AGENTS.md](AGENTS.md) |
+| Produce finished files remotely without a GUI | [OpenDoc Headless](docs/HEADLESS.md) |
+| Write a document or use PDF primitives | [Authoring](docs/AUTHORING.md) |
+| Resolve the active document or feedback | [Current document skill](.agents/skills/opendoc-current-document/SKILL.md), [Selection](docs/SELECTION.md) |
+| Create or adapt a reusable layout | [Templates](docs/TEMPLATES.md) |
+| Create or apply a design system | [Themes](docs/THEMES.md) |
+| Manage projects and document ownership | [Projects](docs/PROJECTS.md) |
+| Prepare document visuals | [Media](docs/MEDIA.md) |
+| Import and bind shared logos or fonts | [Assets](docs/ASSETS.md) |
+| Change the app or prepare a release | [Validation](VALIDATION.md), [Appearance](docs/APPEARANCE.md) |
+| Understand licenses and the PDF engine repair | [Third-party notices](THIRD_PARTY.md), [Forme repair](vendor/formepdf/README.md) |
+
+## Develop the application
+
+Contributors work in a source checkout with Node.js 24 or newer and **pnpm 12.3.4**, pinned in `package.json`:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+For the built interface, run `pnpm build` followed by `pnpm start`. These contributor commands use the checkout's catalogs and local service. Ordinary writing in an installed workspace uses `npx opendoc` and does not require a source checkout or a frontend build.
+
+Before opening a pull request, run `pnpm verify` for typechecking, the full test suite, and the production build. The same checks run on Linux and macOS in CI. See [Validation](VALIDATION.md) for the local workflow and PDF acceptance checks. Package both releases with `pnpm package:pack`; it produces `output/packages/ryanyahya-opendoc-<version>.tgz` and `output/packages/ryanyahya-opendoc-headless-<version>.tgz`. Use both reviewed tarballs for clean-install acceptance and any explicitly authorized npm publication. Both include the same repaired PDF engine and full starter catalogs; normal OpenDoc additionally contains the built browser interface. Use `--edition normal` or `--edition headless` for a focused package build. Do not substitute a direct `npm pack` from the checkout.
+
+## Workspace boundaries
+
+`documents/` holds authored work; `templates/` holds reusable layouts and data contracts; `themes/` holds executable visual systems; `assets/` holds shared local resources. `projects.json` records document membership. `.opendoc/` holds generated context, previews, recovery records, and session state; `output/` holds exported PDFs and PowerPoint files. Generated state and exports are ignored by Git.
+
+Authoring uses the public imports `opendoc`, `opendoc/template`, `opendoc/assets`, and `opendoc/themes`. Keep references to your editable local catalogs relative to the workspace. The pinned application dependency lives in `node_modules/opendoc`; ordinary document work does not change it. The workspace's `package.json`, lockfile, and `.opendoc/workspace.json` identify its installation and format.
+
+In a source checkout, `src/document/` implements the authoring API, `src/template/` binds validated data, `src/assets/` owns shared asset contracts, `src/rendering/` supplies shared render utilities, `src/cli/` owns installation and command dispatch, and `src/server/` contains render/file operations alongside the normal edition's service entry. `src/shared/` holds shared contracts and `src/app/` is the browser review interface. Shared render and export operations are callable without the service; both packages use the same implementation.
+
+OpenDoc remains an English-only TSX authoring product that runs in the user's or agent's workspace. It has no embedded AI, Markdown document editor, visual theme editor, or cloud collaboration. Document code is trusted local code; render workers isolate crashes and timeouts, not hostile code. Keep the service local and never copy `.opendoc/server.json`'s session token into documents, logs, or messages.

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+OpenDoc runs a local Node service bound to loopback. It has no hosted account system or cloud collaboration service. Keep it local; exposing its port through a proxy or tunnel is outside the supported deployment model.
+
+Document, template, and theme TSX is trusted executable code. Render workers isolate crashes and timeouts, but they are not a security sandbox. Review unfamiliar repositories and TSX before opening or rendering them. An external coding agent has its own permissions and data-sharing behavior.
+
+The app stores documents, source media, feedback, and recovery data locally. `.opendoc/server.json` includes a local session token. Do not publish that file or attach personal work, tokens, or unredacted recovery records to an issue.
+
+For a vulnerability, use the hosting repository's private vulnerability reporting channel when available, or contact a maintainer privately. Include a minimal reproduction using synthetic data and the affected revision. Do not disclose exploitable details or private files in a public issue while coordinating a fix. Ordinary defects can use the issue tracker with the guidance in [CONTRIBUTING.md](CONTRIBUTING.md).

package/THIRD_PARTY.md

@@ -0,0 +1,49 @@
+# Third-party notices
+
+- **Forme 0.20.1**: shared React serializer, JavaScript definitions, and PDF rendering through repaired Node WASM. OpenDoc carries PDF text-writer and embedded font-subset metadata repairs in core 0.20.1-opendoc.3; both editions bundle the same repaired Node engine. Source patches, rebuild instructions, and MIT license are in `vendor/formepdf/`; the source repository also retains the rebuild archive, excluded from runtime packages. The attributed asset resolver in `src/rendering/resolve-sources.ts` is adapted from `@formepdf/renderer` 0.20.1 under that MIT license (Daniel Molitor, 2026); OpenDoc supplies its own TSX bundling and source-location capture. Original imported font files remain unchanged. https://github.com/formepdf/forme
+- **PDF.js**: PDF preview, review page rendering, and text extraction. Apache-2.0. https://github.com/mozilla/pdf.js
+- **@napi-rs/canvas 1.0.8**: Skia-backed Node canvas for PDF review page PNGs, without a browser. MIT; native dependencies retain their upstream notices. https://github.com/Brooooooklyn/canvas
+- **Base UI 1.8.0**: accessible interface controls. MIT. https://github.com/mui/base-ui
+- **React** and **Vite**: interface and development server. Their licenses are included in the installed packages.
+- **ts-pptx 3.7.0**: editable PowerPoint generation. MIT. https://github.com/shbernal/ts-pptx
+- **ttf2eot 3.1.0**: embedded TrueType font packaging for PowerPoint. MIT. https://github.com/fontello/ttf2eot
+- **fontkit 2.0.4**: font inspection and metadata. MIT. https://github.com/foliojs/fontkit
+- **resvg-js 2.6.2**: SVG rasterization. MPL-2.0; distributed through its installed package, with upstream source and notices at https://github.com/yisibl/resvg-js
+
+## Bundled fonts
+
+OpenDoc Sans, OpenDoc Serif, and OpenDoc Mono are renamed derivatives of Adobe Source Sans 3, Source Serif 4, and Source Code Pro, distributed under the SIL Open Font License 1.1. The original notices and licenses are retained beside the fonts in `assets/fonts/`. Sans and Serif include regular, semibold, italic, and semibold italic faces. Mono includes a regular face for code specimens.
+
+These historical derivatives removed GSUB, GPOS, and legacy kern tables to work around the original Forme 0.20.1 writer's ligature and spacing bugs. The engine now fixes those bugs directly; the existing derivatives are retained unchanged for document continuity. Outlines are unchanged; these variants intentionally use unkerned character spacing. Family and PostScript names are renamed to respect the reserved name “Source”. The derived font software remains under OFL 1.1.
+
+These checked-in derivatives retain their existing metrics for built-in themes. New font imports preserve the original files and shaping tables and are checked through the repaired PDF engine. The app needs no font conversion tools. Upstream sources:
+
+- https://github.com/adobe-fonts/source-sans/tree/release/TTF
+- https://github.com/adobe-fonts/source-serif/tree/release/TTF
+- https://github.com/adobe-fonts/source-code-pro/tree/release/TTF
+
+## Google Fonts asset families
+
+Inter, Roboto, Open Sans, Lato, and Merriweather are bundled as shared font assets under the SIL Open Font License 1.1. Each includes regular (400), semibold (600), bold (700), and the corresponding italic styles. These are Google-supplied static TTF files preserved byte for byte, not OpenDoc derivatives. The app makes no network request to use or inspect them.
+
+Each `assets/fonts/<family-id>/` folder retains `OFL.txt` with the original copyright notice and `source.json` with the exact download URLs, SHA-256 hashes, original filenames, and their managed asset paths. Lato comes from a pinned revision of the official `google/fonts` repository; the other four use the static TTF responses from the official Google Fonts CSS API, served by `fonts.gstatic.com`.
+
+- Inter: https://fonts.google.com/specimen/Inter
+- Roboto: https://fonts.google.com/specimen/Roboto
+- Open Sans: https://fonts.google.com/specimen/Open+Sans
+- Lato: https://fonts.google.com/specimen/Lato
+- Merriweather: https://fonts.google.com/specimen/Merriweather
+
+The bundled revisions include PDF compatibility results and specimens. The app uses those checks to determine eligibility for theme defaults; `tests/bundled-fonts.test.ts` and `tests/font-renderer.test.ts` cover the bundled files and text rendering, while `tests/font-subset.test.ts` checks metadata in the actual embedded font streams. Original font files, names, shaping tables, and hashes are preserved.
+
+## Geist and interface fonts
+
+Geist is distributed under SIL OFL 1.1. Its copyright and license are retained in `assets/ui-fonts/geist/OFL.txt` and `assets/fonts/geist/OFL.txt`. The interface uses variable WOFF2 files from `@fontsource-variable/geist` 5.3.0, with package provenance and exact hashes in `assets/ui-fonts/geist/source.json`. The shared document asset contains static regular, medium, and bold faces, with hashes and a PDF specimen recorded in its immutable revision. Upstream: https://github.com/vercel/geist-font
+
+The retained Inter UI TTF files carry their own OFL notice, original URLs, and hashes in `assets/fonts/InterUI-LICENSE.txt` and `assets/fonts/InterUI-source.json`.
+
+## OpenDoc examples and branding
+
+The welcome document and presentation contain OpenDoc demo artwork and synthetic chart data. Their media metadata identifies the AI-generated paper illustration and the chart's data and recipe. They contain no customer records. OpenDoc-authored source and example assets follow the repository's MIT license; bundled font software retains its separate OFL license. The OpenDoc wordmark is project artwork.
+
+The McKinsey Consulting theme is an independent interpretation of analytical publication conventions. It contains no McKinsey logo or proprietary font and does not imply affiliation or endorsement. Other theme and template specimens use illustrative content; their design guides retain relevant research references.

package/VALIDATION.md

@@ -0,0 +1,99 @@
+# Verification and release checks
+
+This guide describes repeatable checks, not a claim that an old run validates today's source. Run checks appropriate to the change; record the commands, results, and material limitations in the delivery or pull request. A successful build alone does not demonstrate the document workflow.
+
+## Automated checks
+
+From the repository root:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm verify
+```
+
+`pnpm verify` runs typechecking, the production build, and all tests. Building first makes the installed interface available to server integration tests; run `pnpm build` before invoking those tests directly from a fresh checkout. CI runs the same checks on Linux and macOS. The suite exercises real PDF rendering as well as data and service contracts. It covers document creation and project membership; references and pagination; template schemas, arithmetic, and theme integration; selection, comments, and guarded text edits; asset import, versioning, bindings, and fonts; export freshness, receipts, and recovery. Tests use disposable workspaces rather than adding sample documents to the shipped library.
+
+For a focused change, run the relevant existing test files with `pnpm exec tsx --test tests/<name>.test.ts`. Run the full checks before a release. Once successful checks cover the final source, repeat them only if new edits or evidence require it.
+
+Keep tests tied to a distinct failure or observable contract. When a template already renders in a test, check its text ownership and other related guarantees on that result rather than adding another rendering pass. Test shared creation and validation rules once; keep template-specific checks for layout, editable content, and calculations. Avoid locking tests to incidental copy, catalog counts, or source formatting. Small wording and styling changes normally need review of the existing output, not new tests.
+
+## Installed-package acceptance
+
+After `pnpm verify`, run `pnpm package:pack` and use both generated tarballs: `output/packages/ryanyahya-opendoc-<version>.tgz` and `output/packages/ryanyahya-opendoc-headless-<version>.tgz`. Both include the same repaired Node PDF engine, full starter catalogs, and shared versioned guides. Normal OpenDoc also includes the built browser interface; Headless excludes that interface and its service dependencies. Direct `npm pack` from the repository is not the release packaging route. `pnpm package:pack --edition normal` or `--edition headless` supports focused package checks; a release needs both.
+
+Exercise both tarballs outside the source checkout on macOS and Linux with Node.js 24 or newer and npm. For a release that is not published, set `OPENDOC_PACKAGE_TARBALL` to the selected tarball's absolute path so initialization installs the same reviewed artifact. For normal OpenDoc:
+
+```sh
+export OPENDOC_PACKAGE_TARBALL=/absolute/path/to/ryanyahya-opendoc-0.4.0.tgz
+npm exec --yes --package="$OPENDOC_PACKAGE_TARBALL" -- opendoc init /tmp/opendoc-acceptance --no-start --json
+cd /tmp/opendoc-acceptance
+npx opendoc check --json
+npx opendoc start --no-open
+```
+
+Use a new or empty destination. Confirm initialization refuses nonempty folders and leaves existing files intact. Also exercise the interactive default `~/Documents/My OpenDoc` using an isolated home or explicitly chosen disposable folder, then check the default browser launch and `--no-open`. A noninteractive invocation must supply its destination.
+
+Confirm the normal workspace pins `dependencies.opendoc` to the exact alias `npm:@ryanyahya/opendoc@<version>` and contains its own documents, themes, templates, assets, project records, and `.opendoc/workspace.json`. Verify its `AGENTS.md` and skill pointers reach the installed guidance, and that template/theme guides can open shared documentation without a checkout. From a nested folder, run a workspace command to check ancestor discovery; from elsewhere, use `--workspace`. Exercise `--help`, `--json`, and actionable failures.
+
+Create and revise a document and presentation through `npx opendoc create`, then run `npx opendoc check`, PDF export, and PPTX export against that installed workspace. Confirm edits to its local theme/template affect the intended documents. Complete the relevant reader checks below. Successful repository tests alone do not prove the installed workflow.
+
+Stop the foreground service with **Ctrl-C**, start it again, and stop it before update acceptance. Test update discovery with `npx opendoc update --check --json`; exercise a compatible update and an explicit exact-version request in a controlled fixture. Confirm the installed runtime and its package guidance change together while local documents, feedback, themes, templates, assets, and project files retain their bytes. Exercise invalid targets and a running-service rejection; keep legacy checkout migration and catalog merging outside the update path. Do not publish to test an update; use controlled registry fixtures or already authorized published versions.
+
+## Headless installed-package acceptance
+
+Use a separate disposable workspace and the Headless tarball:
+
+```sh
+export OPENDOC_PACKAGE_TARBALL=/absolute/path/to/ryanyahya-opendoc-headless-0.4.0.tgz
+npm exec --yes --package="$OPENDOC_PACKAGE_TARBALL" -- opendoc-headless init /tmp/opendoc-headless-acceptance --json
+cd /tmp/opendoc-headless-acceptance
+npx opendoc check --json
+npx opendoc review welcome --json
+npx opendoc review welcome-presentation --json
+npx opendoc export welcome --json
+npx opendoc export welcome-presentation --json
+npx opendoc export welcome-presentation --format pptx --json
+npx opendoc review --theme neutral --json
+npx opendoc review --template editorial-essay --json
+npx opendoc templates check editorial-essay --json
+npx opendoc templates preview editorial-essay --json
+```
+
+Confirm `init` requires an explicit destination even when a terminal is available, never prompts or starts a browser/service, and refuses nonempty folders without replacing their files. The workspace marker records the Headless edition. Its exact dependency is `opendoc: npm:@ryanyahya/opendoc-headless@<version>`; public imports, `node_modules/opendoc/` guide links, nested command discovery, and `npx opendoc` must work without the normal package or checkout. `start` should reject the unsupported GUI operation with actionable production commands.
+
+Compare the editable starter documents, templates, themes, fonts, and example media between clean installations. Both must retain the full library. Confirm the Headless package contains no built interface or GUI-only dependency tree; the native PDF/page-image dependencies remain available on each tested platform. Render the same unchanged workspace source and asset bytes in both editions and compare the PDFs and editable presentation content. Packaging reductions must not change document output.
+
+Inspect each successful review result's exact PDF hash, page count and dimensions, page images/text, render issues, stable block/source information, and output paths. Open every page image of representative documents, decks, and specimens at readable scale; inspect text extraction and the final exported files. `visualReview: "required"` and `factualReview: "required"` must not be converted into automated claims that these reviews passed.
+
+Exercise a failed/overflowing revision and source edits during rendering. Check nonzero exit status and structured issues when available, and confirm previous successful review files and exports remain intact without being labeled as the failed revision. Headless review/export must work without a live service, built interface, or browser context; stale or malformed `.opendoc/server.json` must not affect its direct production path. Include a bespoke document and a reusable theme/template change, then verify their specimens and dependent instance outside the checkout.
+
+Check PPTX slide count/order, editable text, media, and font parts against the reviewed PDF. Native PowerPoint inspection is useful when available; a remote environment without PowerPoint can finish package/content checks and report that native appearance was not verified. Do not substitute a PDF for a failed requested PPTX or require the recipient to install OpenDoc to complete acceptance.
+
+Exercise update discovery and an exact-version update in a controlled fixture. Confirm registry selection stays on `@ryanyahya/opendoc-headless`, the exact alias and workspace edition remain Headless, runtime/guidance update together, and all authored workspace content retains its bytes. Verify a remote delivery fixture exposes the actual PDF/PPTX through an accessible output mechanism; a host-only path is insufficient when the recipient cannot access it. No messaging service or publication is needed to demonstrate file production.
+
+## Reader and contributor-checkout acceptance
+
+Use a disposable copy of the workspace for destructive, conflict, and recovery exercises. Keep the shipped library at **Getting started → Welcome to OpenDoc**; template and theme specimens belong in their catalogs.
+
+1. In a source checkout, start with `pnpm start` after building; in an installed workspace, use `npx opendoc start`. Confirm the printed local URL opens, Welcome renders, and Templates, Themes, and Media & Assets load. Also check `pnpm dev` after changes to the development server integration.
+2. Create a project and a document using the documented command or template flow. Confirm assignment, the chosen theme, `theme.tsx`, and exact `assets.json` choices. Edit source and confirm the current PDF refreshes.
+3. Open the document, make a text draft, navigate away and back, then save it. Confirm source and PDF agree. Leave a comment, apply the intended revision, and resolve it through `pnpm comments` in the checkout or `npx opendoc comments` in the installed workspace. For editing changes, exercise a stale-source conflict and ensure pending text survives.
+4. Bind a shared font and logo; verify actual PDF usage, copied text, logo proportions, and the correct variation for the page background. For asset changes, check historical bindings remain readable and archive/Undo does not overwrite newer choices.
+5. Save a PDF through Export and open it. For presentations, also save PowerPoint and check editable text, embedded fonts, and slide content against the preview. Check previous exports and a CLI export. For export changes, exercise an interrupted response and recovery, plus an invalid render that preserves the previous valid output.
+6. Check the affected interface at desktop and narrow width, with keyboard navigation, light/dark appearance, and readable errors and empty states. Check every page of changed PDFs at a legible size; a thumbnail or contact sheet alone is insufficient.
+
+Document duplicate, move, delete, and Undo should preserve local data and asset selections. Exercise these after lifecycle changes. Test startup, shutdown, and a second launch after server changes; do not leave acceptance documents or temporary server sessions in the release workspace.
+
+## Review the actual output
+
+For documents, use the [opendoc-review-document skill](.agents/skills/opendoc-review-document/SKILL.md). Shared templates need representative sparse and long input plus a second theme. Shared themes need a reviewed specimen and representative affected layouts. Newly imported fonts need their real PDF specimen and review in the intended document. Check visual clipping and page breaks as well as extracted text, links, figures, calculations, and references relevant to the change.
+
+`pnpm themes -- preview <id>` in a source checkout, or `npx opendoc themes preview <id>` in either installed edition, exports a selected theme specimen for review. `npx opendoc templates preview <id>` exports a template specimen. `npx opendoc review --theme <id> --json` and `review --template <id> --json` also prepare page images/text for direct inspection without the app. Specimens do not become user documents. Use existing test fixtures for longer cases instead of keeping throwaway reports in `documents/`.
+
+## Current boundaries
+
+- The normal edition's built interface needs the local Node service and authoring dependencies. A static upload of `dist/` is not a working OpenDoc installation. Headless commands run directly without a service; they still require the document engine and native runtime dependencies.
+- Render workers execute trusted local TSX. Their process boundary handles crashes and timeouts; it is not a hostile-code sandbox.
+- Native Forme chart labels and inline link annotations have limitations. Use managed raster charts and whole-block links as described in [Authoring](docs/AUTHORING.md). Native list pagination uses OpenDoc's text-row workaround.
+- OpenDoc carries Forme text-writer and embedded font-subset metadata repairs. Font regressions check extracted text and geometry, plus subset table lengths, checksums, and hinting profiles. Preserve original imported fonts; do not strip shaping tables to hide engine failures. See [the patches and rebuild guide](vendor/formepdf/README.md).
+- Automated geometry and text checks do not establish factual accuracy, full accessibility conformance, legal compliance, or visual quality. State concrete unverified limits without presenting historical results as current proof.

package/bin/opendoc.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { register } from 'tsx/esm/api';
+
+register();
+const { main } = await import('../src/cli/main.ts');
+await main(process.argv.slice(2));