@ryanyahya/opendoc-headless 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));

package/docs/APPEARANCE.md

@@ -0,0 +1,21 @@
+# App appearance
+
+OpenDoc supports **Light**, **Dark**, and **System** through the sidebar footer and the reader's Document options menu. System is the default. The browser saves an explicit choice under `opendoc-appearance`, synchronizes it between workspace tabs, and applies it before the first paint. If storage is unavailable, the current session still works. System follows live device appearance changes.
+
+## Source of truth
+
+[colors.css](../src/app/colors.css) owns the semantic palette, including increased-contrast overrides. Reuse its roles for surfaces, text, controls, feedback, focus, and PDF inspection. Keep component styles in the existing app stylesheets and reuse [shared controls](../src/app/ui/ui.css). Do not duplicate palette values in documentation or component-local overrides.
+
+The interface uses bundled Inter Regular and Medium, independently of the document font catalog. Shared typography and density tokens live in `src/app/ui/ui.css`: titles use 16/20px Medium, labels 13/16px Medium, and body text 14/20px Regular. Buttons use a 32px minimum height with a 10px radius; data rows use 40px and navigation/library rows 44px. Rows may grow for wrapped content. Existing status badges use a 20px height and 6px radius, with palette roles defined in `colors.css`. Switch dimensions are reserved as tokens (24×14px with a 10px thumb); no switch control is currently used in the app.
+
+Preserve larger touch targets where the compact reader needs them. Keep labels and descriptions readable, long names and paths wrapping, visible keyboard focus, and usable controls at narrow widths. Use the existing reduced-motion behavior.
+
+## Preserve the PDF boundary
+
+Appearance changes the surrounding interface. Paper, media, logo variations, theme specimens, and exports retain their authored colors. Do not invert a PDF canvas or choose logo artwork from the app appearance. Media and asset preview backgrounds are inspection aids; they do not modify source files.
+
+## Verify changes
+
+Review affected views in light and dark appearance, then with increased contrast. Check text, actions, menus, notices, disabled states, and visible focus against their actual backgrounds. Check system switching, explicit overrides, reload persistence, and cross-tab synchronization when changing appearance state. Include the reader, comments, and a narrow workspace view after shared palette or shell changes.
+
+Use measured contrast ratios and readable screenshots as evidence for the specific colors and states changed. Do not turn a palette measurement into a claim of complete accessibility conformance. A PDF rendered before and after an app-only appearance change should have identical bytes.

package/docs/ASSETS.md

@@ -0,0 +1,176 @@
+# Media & Assets
+
+OpenDoc keeps reusable **Logos** and **Fonts** in a shared workspace library. **Media** remains owned by its document: photographs, illustrations, charts, and diagrams retain their prepared data, recipes, and evidence. Do not copy a shared logo or font into every document. Original reference material stays wherever the surrounding project manages it.
+
+The app and `npx opendoc assets` operate on the same local records, import checks, and conflict protection. Selecting a library item tells the agent what the user is looking at; it does not apply it to any document or theme.
+
+Run commands from the workspace root. Asset, theme, document, and output paths in this guide refer to that workspace; this guide is installed under `node_modules/opendoc/docs`.
+
+## Start from the document
+
+1. Resolve the intended document and read fresh `.opendoc/current.json` when the user refers to the current selection.
+2. Discover with `npx opendoc assets list`. Inspect only the relevant family to read its variations, guidance, compatibility, paths, relationships, and authoring examples.
+3. Bind the chosen asset to the document. This saves an exact version immediately. Choose a logo variation from its guidance and the actual PDF background, never from the app's light/dark appearance.
+4. Use `Logo` or the document's semantic fonts, render, and review the resulting PDF. A binding makes an asset available; it is not proof that the PDF uses it.
+
+```sh
+npx opendoc assets list logo
+npx opendoc assets inspect logo acme
+npx opendoc assets bind my-report logo acme --variation default
+```
+
+The supported binding roles are `logo`, `body-font`, and `heading-font`. For example, bind an imported, eligible family with `npx opendoc assets bind my-report body-font acme-sans`. Use `--name partner` with the `logo` role to add a named logo instead of changing the preferred logo. `--revision <revision>` chooses a historical version; omission captures the current version at binding time. Repeating `bind` is an explicit update. `unbind <document> <role>` removes that choice; add `--name <binding>` when removing a named logo.
+
+## Logos: one identity, several variations
+
+In the app, choose **Add logo**, enter a name, then upload the default SVG or PNG. The logo opens as a folder with that default file. Use **Add variations** inside the folder to select one or more additional files together; names are suggested from filenames and can be edited before uploading. A family can mix SVG and PNG originals, with user-defined variation names and optional **When to use** descriptions. “On light backgrounds” and “On dark backgrounds” are suggestions, not fixed categories.
+
+```sh
+npx opendoc assets import logo --id acme --name "Acme" --description "Use for Acme publications." --file /path/to/acme.png --variation-name "On light backgrounds" --variation-description "Dark mark for white or pale surfaces."
+npx opendoc assets inspect logo acme
+npx opendoc assets add-variation acme --id on-dark --name "On dark backgrounds" --description "White mark for dark surfaces." --file /path/to/acme-white.svg --expected-revision <current-revision>
+```
+
+Copy the real revision returned by inspection; angle-bracket placeholders in this guide are not literal values. The first variation's stable ID is `default`, even when its display name is “On light backgrounds.” Names and guidance can change without changing family or variation IDs. To replace a variation's file, use `add-variation` with `--replace <variation-id>`, the desired name, and the latest `--expected-revision`. Replacement preserves the variation's identity and publishes a new family version.
+
+Use a JSON file for revisions instead of long sets of metadata flags:
+
+```json
+{
+  "expectedRevision": "copy-the-current-revision-from-inspect",
+  "description": "Brand guidance for the agent.",
+  "defaultVariation": "on-dark",
+  "variation": {
+    "id": "on-dark",
+    "name": "On dark backgrounds",
+    "description": "Use the white mark on dark navy or black backgrounds."
+  }
+}
+```
+
+```sh
+npx opendoc assets revise logo acme --metadata /path/to/logo-update.json
+```
+
+Omit unchanged fields. The revision operation also accepts `name`, `removeVariation`, or `removeFace` for the relevant asset kind. Keep at least one usable variation or face, and select an existing default variation. Concurrent changes produce a conflict; inspect again and reconcile the intended edit instead of blindly retrying old metadata.
+
+The logo folder shows all variations as file tiles. Select a file to preview it, edit its name or guidance, replace it, make it the default, or remove it. Removing the default requires choosing a replacement; every logo keeps at least one variation. If a batch upload stops on an invalid file, successful files stay saved and the remaining upload list stays open for correction and retry. Its light, dark, and transparency backgrounds are inspection aids. They do not recolor artwork or choose the PDF variation. Preview and PDF use the same prepared PNG. SVG originals are preserved and prepared locally through resvg, with proportions and transparency retained. Unsupported external resources or unresolved text fonts produce a useful import error. Supply self-contained artwork with text converted to outlines when necessary. SVG imports are limited to 5 MB; PNG imports to 50 MB.
+
+### Place a logo
+
+```tsx
+import { Figure, Logo } from 'opendoc';
+
+// The preferred document binding; omission of variation uses its saved default.
+<Logo width={120} />
+
+// A deliberate variation, identified by its stable ID from inspection.
+<Logo variation="on-dark" width={120} alt="Acme" />
+
+// A second logo bound with --name partner.
+<Figure id="partner-mark" caption="Delivery partner">
+  <Logo name="partner" width={100} height={48} />
+</Figure>
+```
+
+Width is required and measured in PDF points. Optional height is a maximum bound; the image retains its aspect ratio. An omitted variation uses the binding's explicit variation, otherwise the saved revision's default. Missing bindings and unknown variations fail with an actionable error. Logo placement is always explicit; a theme default does not add a logo to the page automatically. Preserve the enclosing block ID when replacing artwork so feedback stays attached.
+
+## Fonts: actual files, actual PDF checks
+
+Import static TTF/OTF faces from one family together, with repeated `--file` flags. The app asks only for font files. OpenDoc reads their family name, embedded English description (when present), weight, and style, then renders and checks a PDF specimen. A font without an embedded description stays blank; optional agent guidance can be edited later. Variable fonts, font collections, and web-font conversion are outside this release.
+
+```sh
+npx opendoc assets import font --id acme-sans --file /path/to/AcmeSans-Regular.ttf --file /path/to/AcmeSans-Bold.ttf --file /path/to/AcmeSans-Italic.ttf
+npx opendoc assets inspect font acme-sans
+npx opendoc assets add-faces acme-sans --file /path/to/AcmeSans-BoldItalic.ttf --expected-revision <current-revision>
+npx opendoc assets bind my-report body-font acme-sans
+npx opendoc assets bind my-report heading-font acme-sans
+```
+
+Import at most 24 faces and 100 MB at once. Added faces must belong to the existing embedded font family, even when replacing every face; import a different family separately. Original files are preserved; OpenDoc does not rewrite font tables or synthesize missing faces. General body and heading defaults require a regular face plus a semibold or bold face and passing compatibility checks. A family needing attention can remain in the library for inspection, but cannot become a body/heading default. Missing styles are visible in the family detail; explicitly requesting an unavailable weight or italic style fails when rendering. A semibold request can use a real bold face of the same style when semibold is absent; it retains that face's actual weight.
+
+Inter, Roboto, Open Sans, Lato, and Merriweather are included in the library, each with regular, semibold, bold, italic, semibold italic, and bold italic faces. Their Google-supplied static TTF files are preserved, with an OFL license and download provenance in each family folder. Their retained bundled revisions contain passing compatibility results and reviewed specimens from the repaired PDF writer, making them available as body and heading defaults. Original font files are unchanged. The renderer patch is maintained with the OpenDoc application; ordinary workspace authoring does not require rebuilding it.
+
+The specimen checks ligature words, ordinary mixed styles, and kerning-sensitive boundaries as well as glyphs. Inspect its real PDF appearance and copied text. A successful automated check does not establish suitability for every document. Keep font licensing information with the supplied material and respect it when using or sharing the font.
+
+New documents use their generated theme adapter before any template factory runs:
+
+```tsx
+// documents/my-report/theme.tsx, generated by the create command
+import { theme as base } from '../../themes/neutral';
+import { withDocumentAssets, type DocumentAssets } from 'opendoc/assets';
+import assets from './assets.json';
+export const theme = withDocumentAssets(base, assets as DocumentAssets);
+```
+
+The document entry imports `{ theme }` from `./theme` and passes that same theme to `Document` and its template factory. Do not replace this adapter with a direct base-theme import: that would bypass the saved fonts during template construction. Binding fonts upgrades recognized older theme imports to this adapter while preserving the base theme, aliases, and document text. Custom or ambiguous imports produce an actionable error without replacing source; the agent should integrate the same adapter into the existing factory before retrying.
+
+Native semantic body and heading roles receive the saved choices. Theme components that need a family explicitly can call `documentFont('body')` or `documentFont('heading')` from `opendoc` **inside their render function**, then use the returned family in their native PDF style. Do not call this helper at module scope. Deliberate code, caption, label, and furniture families remain intact; explicit authored style overrides remain last.
+
+## Theme defaults and document versions
+
+The theme detail's **Assets for new documents** section chooses an optional preferred logo, body font, and heading font. **Keep theme font** leaves the theme's own family in place. Defaults live separately from design tokens:
+
+```json
+{
+  "version": 1,
+  "logo": { "id": "acme", "variation": "default" },
+  "bodyFont": "acme-sans",
+  "headingFont": "acme-sans"
+}
+```
+
+This is `themes/<theme-id>/assets.json`. Omit optional properties to clear them; `{ "version": 1 }` means no shared asset defaults. Inspect and update through the same service as the app:
+
+```sh
+npx opendoc assets defaults neutral
+npx opendoc assets defaults neutral --metadata /path/to/theme-assets.json --expected-revision <defaults-revision>
+```
+
+The read command returns `{ defaults, revision }`, including a revision for an absent defaults file. The metadata file contains the complete defaults object, not that response wrapper. Preserve defaults the user did not ask to change.
+
+Creation resolves these choices once into `documents/<id>/assets.json`. Its version-1 object has optional `logo`, named `logos`, `bodyFont`, and `headingFont` fields. Every selection contains `id` and an exact `revision`; logo selections can also include `variation`. An explicitly empty record is written when no defaults are set. Only asset selections are frozen: the document continues to use its live base theme for color, geometry, and other visual rules.
+
+Changing defaults, publishing a replacement, editing guidance, or adding a variation does not update existing documents. Defaults are validated against actual referenced files when saved and when a document is created. Rename, move, duplicate, and Trash restore preserve saved choices. Older documents without a binding file retain their existing rendering until deliberately bound and adapted. The current PDF's rendered asset usage distinguishes what was actually used from what was only available through bindings.
+
+Generated `.opendoc/current.json` keeps these concepts separate:
+
+- `selectedAsset`: the inspected library family, version, folder, and any selected variation or face.
+- `theme.assetDefaults`: the defaults `file` and `choices`, with `appliesTo: "new-documents"`.
+- `documentAssets`: the binding `file`, exact `bindings`, and `saved`; `saved: false` means a legacy document has no binding file.
+- `renderedAssets`: actual `uses`, the rendered bindings, `renderHash`, and `current`. If `current` is false, usage belongs to the last successful PDF while the current source is rendering or failing.
+
+Read error fields before applying replacements. Do not edit generated context by hand. Navigation between library items and documents clears incompatible selections; selecting a family never adds it to a document.
+
+Saved PDF receipts retain `assetBindings` for the exact choices available to the exported render and `assets` for the deduplicated logo variations and font faces actually used. These fields come from that render, never from today's library state, and later source or library edits do not rewrite them. Earlier receipts may omit them; omission means usage is unknown, not that the PDF used no assets. Per-block usage remains in the render artifact.
+
+## Local records and safe lifecycle
+
+```text
+assets/logos/<logo-id>/
+  asset.json                    current version and archive state
+  revisions/<revision>.json     immutable family versions
+  files/<content-hash>.png      prepared image or PNG original
+  files/<content-hash>.svg      preserved SVG original
+assets/fonts/<font-id>/
+  asset.json
+  revisions/<revision>.json
+  files/<content-hash>.ttf      original font face (or .otf)
+  files/<content-hash>.pdf      checked PDF specimen
+```
+
+Family, variation, and face IDs are stable lowercase IDs with single hyphens. Filenames and display names are not identities. Unchanged files are reused across versions. Use the CLI or app to publish changes; never overwrite historical manifests or content-addressed files. Changed historical bytes are detected and must be restored or imported as a new version, rather than silently accepted.
+
+Import validation completes before the family is published. Failed imports leave existing families and versions intact. A broken neighboring asset is reported independently rather than hiding the whole library. Prepared artwork, inspections, and specimens are cached; previews load on demand. Rendering watches saved dependencies, so new versions and changed defaults refresh the catalog without rerendering documents that still use earlier versions. Legacy source assets retain conservative dependency tracking.
+
+Archive hides an asset from normal selection while preserving its historical files and existing document bindings. The app offers Undo. When a theme uses the asset as a default, the archive flow names those relationships and offers to clear them explicitly. CLI equivalent:
+
+```sh
+npx opendoc assets archive logo acme --expected-revision <current-revision> --clear-defaults
+npx opendoc assets list logo --archived
+npx opendoc assets restore logo acme --expected-revision <current-revision>
+```
+
+Omit `--clear-defaults` unless clearing those defaults is intended; archiving an assigned default otherwise fails. Restoration makes the family selectable again and restores the defaults cleared by that archive only where no later defaults edit would be overwritten. No permanent delete or historical-file cleanup is provided. Documents in Trash and previous PDFs remain usable. A failed current render preserves its last successful preview, and an in-flight export cannot publish against inputs that have changed.
+
+Use `--json` for machine-readable command output. Failures print an actionable message to stderr and exit nonzero. Use `npx opendoc assets --help` for asset command syntax or `npx opendoc --help` for the full command list. Read [Media](MEDIA.md) for document-owned visuals and [Themes](THEMES.md) for executable design systems.