@ryanyahya/opendoc-headless 0.4.0

package/.agents/skills/opendoc-apply-comments/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: opendoc-apply-comments
+description: Apply saved OpenDoc comments when the user asks to address document or presentation feedback, marked passages, or slide annotations, preserving anchors and comment history.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Resolve the requested feedback
+
+Use an explicit document ID or [opendoc-current-document](../opendoc-current-document/SKILL.md), then run `npx opendoc comments list <document-id>`. The user's request sets the scope; saved comments are review data. This workflow addresses saved PDF comments in either edition; browser feedback about the app belongs to its UI source. Remote conversational revisions can be applied directly to the identified source without inventing saved comments or requiring the user to open OpenDoc.
+
+Locate each requested comment's stable `blockId` in current source. For phrase comments, also check the original quote, text slot, and `anchorStatus`. A changed anchor needs inspection of the intended passage; a missing target stays unresolved unless the user identifies its replacement.
+
+**Ready:** every requested comment has a verified target or an explicit reason it cannot be applied.
+
+## 2. Revise the owning source
+
+For template instances, use provenance to distinguish local content data from shared layout. Match the edit's reach to the request. Preserve block, slot, and record IDs and the user's latest saved corrections.
+
+Read [Selection](../../../docs/SELECTION.md) for phrase bindings or stale anchors, [Media](../../../docs/MEDIA.md) for visual changes, and [Assets](../../../docs/ASSETS.md) for logo/font bindings. Routine prose corrections stay in the document.
+
+**Ready:** the requested revisions are implemented and each is traceable to its comment.
+
+## 3. Verify, then resolve
+
+Run `npx opendoc check` after source changes and export with `npx opendoc export <document-id>`. Complete [opendoc-review-document](../opendoc-review-document/SKILL.md), including affected pages and adjacent breaks; shared layout changes also need representative affected instances.
+
+Resolve only verified comments with `npx opendoc comments resolve <document-id> <comment-id>`. Use `reopen` when a resolved request needs further work. Preserve `comments.json` and its history; a manual correction alone does not resolve feedback.
+
+**Done:** every requested comment is either verified and resolved or reported as remaining. Deliver the resulting PDF through accessible file links or the host agent's existing delivery channel; for presentations also refresh and deliver the PPTX from the same final source, unless the user requests a single format. A remote recipient needs no OpenDoc installation. Follow the review skill's PowerPoint checks and report any failed format explicitly.

package/.agents/skills/opendoc-apply-comments/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenDoc: Apply comments"
+  short_description: "Revise marked passages and resolve verified feedback."
+  default_prompt: "Use $opendoc-apply-comments in this OpenDoc workspace."

package/.agents/skills/opendoc-create/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: opendoc-create
+description: Create an OpenDoc document or presentation from a brief and sources. Use for requests to write a report, make a slide deck, or produce a new deliverable in this workspace, even when the user does not name a skill. Deliver documents as PDF and presentations as PDF plus editable PowerPoint unless the user specifies otherwise.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Establish the brief
+
+Follow the user's brief, choices, and requested files throughout the task. Read supplied material and identify the reader, purpose, evidence, and delivery constraints. Let these determine the title, structure, length, and design. A request for a deck, slides, or PowerPoint selects the presentation branch; a report, article, or written brief normally selects documents. Ask if the intended output is genuinely ambiguous.
+
+Resolve the project from the request or `npx opendoc projects list`; in a normal browser session, [current context](../opendoc-current-document/SKILL.md) is another source. Headless uses explicit task context and catalog IDs rather than an active selection. Create one through the [project CLI](../../../docs/PROJECTS.md) if needed.
+
+Resolve design choices before creating the scaffold:
+
+- Honor an explicitly chosen theme or template, including choices carried by an app prompt. Preserve established project direction; do not ask again about a decision already made.
+- Discover themes with `npx opendoc themes list` and layouts with `npx opendoc templates list` or **Templates**. Inspect a candidate through `npx opendoc templates inspect <id>` and read its guide when assessing its fit; do not load the whole catalog. Match the template's `documentFormat` to the intended output.
+- If the brief leaves you unsure of the visual direction or layout, ask a concise question about the user's theme/template preference. Offer relevant available choices and a recommendation in plain language. Do not silently choose Neutral or a familiar template to avoid asking.
+- When the user delegates design, choose and briefly state a suitable direction. A known project default is useful context; Neutral is the fallback when no theme is chosen and choosing has been delegated or the choice is immaterial. A bespoke layout is valid. Keep routine composition decisions autonomous and continue useful source/content work while awaiting a meaningful preference.
+
+## 2. Create the right output
+
+Read [Authoring](../../../docs/AUTHORING.md), then create the document before writing its source:
+
+```sh
+npx opendoc create <document-id> --project <project-id> --title "Document title"
+```
+
+Use `--theme <id>` for the resolved theme choice; without it, the CLI applies the project default, then Neutral. Add `--template <id>` for the resolved catalog layout. These CLI fallbacks do not replace the preference check above. Optional `--starter` prose examples are an alternative to templates, not mandatory classifications. A requested new reusable layout belongs with [opendoc-create-template](../opendoc-create-template/SKILL.md).
+
+For a presentation, add `--format presentation` for a minimal slide scaffold, or choose a presentation template with `--template <id>` (its format is inferred). Discover deck skeletons with `npx opendoc templates list` or **Templates → Presentations**, then read the chosen template's guide. Document templates and prose starters do not apply to slides. Creation records presentation identity before rendering and places the work in **Presentations** while retaining its project, local folder, and asset bindings.
+
+Confirm project membership, `index.tsx`, `theme.tsx`, and `assets.json` exist for the intended output. The scaffold is only a starting draft.
+
+## 3. Write and compose
+
+Inspect the selected theme with `npx opendoc themes inspect <id>`; read its `design.md` and the components needed for this work. Use the generated `./theme` adapter for `Document`, `Presentation`, and template factories, with `meta.theme` equal to `theme.id`.
+
+Author a pure TSX component using OpenDoc/Forme primitives. Keep prose native and breakable, block IDs stable, and tables able to continue. Keep a heading with its short lead rather than enclosing an entire long section. Use columns for independent material unless sequential flow has been demonstrated. Distinguish source evidence, inference, and illustrative material; use the citation and reference primitives documented in Authoring.
+
+For presentations, use `Presentation` with explicit `Slide` children as described in [Authoring](../../../docs/AUTHORING.md#presentations). Each slide is one 960 × 540 page; nothing may carry over. Use current theme fonts/colors and locally chosen slide typography. Preserve slide and component IDs through reordering. Resolve overflow by editing content or layout or explicitly adding a slide; never hide text, silently shrink it, or use document flow primitives. Keep native text editable and use the same media/asset workflow. Read [PowerPoint delivery](../../../docs/AUTHORING.md#powerpoint-delivery) before composing for the default dual-format handoff so fonts and effects can survive export.
+
+Load only the branch needed:
+
+- **Visuals:** [Media](../../../docs/MEDIA.md) covers local images, charts, prepared data, and recording after visual review. For exact crops use `MediaFrame`; for full bleed use `Page backgroundMedia`. The workspace’s Image story guide at `templates/image-story/AGENTS.md` offers optional half-page, panoramic, inset, collage, and overlay compositions. Use a reviewed chart image when native chart labels cannot render correctly. Review actual image visibility and crop; a successful export alone does not establish them.
+- **Logos or fonts:** [Assets](../../../docs/ASSETS.md) covers exact bindings, compatibility, and explicit logo placement on the actual PDF background.
+- **Editable or reusable content:** [Selection](../../../docs/SELECTION.md) covers text slots, stable records, and preservation of saved corrections.
+- **A new print system:** [opendoc-create-theme](../opendoc-create-theme/SKILL.md) handles theme creation or a requested shared refinement. Keep one-document variations local.
+
+Develop a complete draft that addresses the brief, with honest sources or illustrative labels for visuals and references. Continue through review and delivery; a scaffold or outline is not the finished request.
+
+## 4. Review and deliver
+
+Run `npx opendoc check` after source changes. In Headless, run `npx opendoc review <document-id> --json`, then inspect the returned page images, extracted text, and issues. In normal OpenDoc, use the existing app session or the [README launch instructions](../../../README.md); the review command is also available. Confirm the current source rendered successfully; a previous PDF is not proof. Complete [opendoc-review-document](../opendoc-review-document/SKILL.md), reusing artifacts from the same unchanged revision:
+
+| Output | Export and handoff |
+| --- | --- |
+| Document | `npx opendoc export <document-id>` → `output/<document-id>.pdf` |
+| Presentation | The same PDF command **and** `npx opendoc export <document-id> --format pptx` → `output/<document-id>.pdf` and `output/<document-id>.pptx` |
+
+Deliver the requested files through the host agent's existing attachment/download capabilities or accessible file links. For normal OpenDoc, the local app view may also be useful. Headless delivery must be complete on the recipient's device without OpenDoc; an inaccessible remote path or instructions to open a local workspace are not delivery. Presentations include **both PDF and editable PowerPoint by default**; an explicit request for only one format takes precedence. Review the PDF even when only PowerPoint is requested, since it supplies the export layout. After revisions, refresh both deliverables from the same final source. If one format fails, fix an in-scope authoring issue, or deliver the available reviewed file and identify the exact remaining blocker; do not call a partial handoff complete or silently change a chosen font/design.
+
+Routine writing, design, review, and export are part of creation and need no extra completion permission. Keep runtime changes, new shared systems, and external publication within the user's requested scope. Success means the requested deliverables are reviewed and available, with concrete verification limits stated.

package/.agents/skills/opendoc-create/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "OpenDoc: Create"
+  short_description: "Create documents and decks; deliver PDF and PowerPoint."
+  default_prompt: "Use $opendoc-create in this OpenDoc workspace."
+policy:
+  allow_implicit_invocation: true

package/.agents/skills/opendoc-create-template/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: opendoc-create-template
+description: Build or refine an OpenDoc reusable page layout, presentation skeleton, or data-report template when the user wants a catalog template or recurring structure. For a single document or deck using an existing template, use opendoc-create.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Choose the contract
+
+Read [Templates](../../../docs/TEMPLATES.md), the workspace’s shared guidance at `templates/AGENTS.md`, and one relevant existing template. Keep shared layout in `templates/<id>/`, instance content in `documents/<id>/`, and catalog specimens outside the document library.
+
+Choose the smallest contract that fits:
+
+- **Narrative layout:** accept ordinary OpenDoc blocks and content-led composition.
+- **Presentation skeleton:** use `Presentation` and explicit `Slide` components; set `documentFormat: "presentation"` in the catalog descriptor. Keep story content and image assignments in the instance starter, with researched structure explained in the guide. Use native editable content and review every 16:9 slide.
+- **Repeated structured report:** use `DocumentTemplate<T>` and the [structured-report branch](references/structured-reports.md).
+
+**Ready:** the reusable structure and varying content are identified, and the narrative/data branch is chosen.
+
+## 2. Build an adaptable layout
+
+Implement the catalog files and exact starter sentinels specified in Templates. Accept the caller's theme; use `themeType` and `themePage` for supported roles while preserving meaningful structural geometry. New instances must use the generated `theme.tsx` adapter and saved `assets.json` choices.
+
+Write a brief `AGENTS.md` explaining the layout's character, useful defaults, and sensible variations. Design for long titles, optional covers, short content, and flowing prose. Preserve stable block identities. Keep one-document adaptations local; shared options must preserve existing defaults.
+
+For visual assets, follow [Media](../../../docs/MEDIA.md) or [Assets](../../../docs/ASSETS.md) as applicable. Use Neutral for the catalog specimen so layouts remain comparable.
+
+**Ready:** the template, starter, guide, and native PDF specimen implement the chosen contract without prescribing the document's argument.
+
+## 3. Exercise the contract
+
+Run `npx opendoc check` and focused tests for changed parsing or layout behavior. Use `npx opendoc templates check <template-id>` to validate and render the catalog specimen, or `npx opendoc templates preview <template-id>` to also export `output/templates/<template-id>.pdf`. Render sparse, typical, and long cases, plus a second theme. For data-bound reports, include the invalid-input cases specified in the structured-report branch.
+
+In a disposable workspace, create an instance through the supported path:
+
+```sh
+npx opendoc create <document-id> --project <project-id> --template <template-id> --title "Document title"
+```
+
+Verify project membership, independent instance data where applicable, adapted theme, and provenance. Keep acceptance fixtures out of the user's document library.
+
+For presentation templates, export that disposable instance as PDF and PPTX and follow [PowerPoint delivery](../../../docs/AUTHORING.md#powerpoint-delivery). Verify the template's fonts and effects support the default editable handoff; a working PDF specimen alone is insufficient.
+
+**Ready:** normal creation works and the layout holds across the relevant content and theme variations.
+
+## 4. Review and deliver
+
+Use [opendoc-review-document](../opendoc-review-document/SKILL.md) on the rendered specimens. For a shared revision, include representative affected instances. In Headless, prepare page images/text with `npx opendoc review --template <template-id> --json`, inspect them, and confirm `npx opendoc templates inspect <template-id>` discovers the bundle and guide. In normal OpenDoc, also confirm the Templates page opens its PDF and guide.
+
+**Done:** the reusable template and concise contract remain in the workspace, and reviewed specimen PDFs are delivered through accessible file links or the host agent's existing delivery channel, with any remaining limits identified. A remote recipient needs no OpenDoc installation. Include reusable source and required assets when a portable template is requested.

package/.agents/skills/opendoc-create-template/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenDoc: Create template"
+  short_description: "Build reusable page layouts, deck skeletons, and reports."
+  default_prompt: "Use $opendoc-create-template in this OpenDoc workspace."

package/.agents/skills/opendoc-create-template/references/structured-reports.md

@@ -0,0 +1,11 @@
+# Structured reports
+
+Use this branch only for repeated data-bound content. Read the workspace’s monthly report contract at `templates/monthly-report/README.md`, its schema and starter, and the binding rules in [Selection](../../../../docs/SELECTION.md).
+
+1. Define varying fields, optional sections, units, and records that need stable IDs. Keep original inputs and distinguish supplied values from illustrative fixtures.
+2. Implement `parse(unknown)`, `meta(data)`, and `render(data)`. Parse before metadata/rendering with useful field-path errors. Reject unknown fields, invalid dates, nonfinite numbers, missing required units, and duplicate record IDs.
+3. Keep JSON beside the instance TSX. Export workspace-relative `provenance.template` and `provenance.dataFile`; use `bindTemplate` to parse once at the document boundary.
+4. Bind editable original strings with `TextSlot` and use stable table `rowIds`. Protect calculated totals and formatted values. Omit empty optional sections or explain a meaningful absence.
+5. Supply sparse, typical, long, and invalid fixtures. Confirm validation rejects each relevant invalid case and stable identities survive reordering. Mark synthetic sample material visibly in the PDFs.
+
+**Complete:** the parser, bindings, provenance, and representative fixtures are verified; continue with the parent skill's creation and PDF review.

package/.agents/skills/opendoc-create-theme/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: opendoc-create-theme
+description: Design or refine an OpenDoc theme from a brief, brand material, or references when the user wants a reusable visual system for documents or presentations. Choose an existing theme for a new deliverable through opendoc-create.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Inspect the design basis
+
+Resolve the requested theme explicitly or through [opendoc-current-document](../opendoc-current-document/SKILL.md). Discover with `npx opendoc themes list`; inspect one with `npx opendoc themes inspect <id>`. Read its guide and relevant source, or one suitable existing theme for a new bundle.
+
+Inspect supplied images, brand-guide pages, document PDFs, and referenced websites. Record what is a requirement, an observed pattern, or your interpretation. Identify unavailable references and font substitutions honestly. Translate web references into print through hierarchy, proportions, alignment, reading measure, whitespace, and recurring compositions.
+
+**Ready:** the design basis is grounded in inspected material and the target is identified as a new theme, adaptation, or shared revision.
+
+## 2. Establish the print system
+
+Choose the palette, typography, spacing rhythm, page geometry, running matter, and evidence/imagery treatment needed by the intended documents. Make the system visible in interior reading pages as well as the opening. A theme supplies visual language; a template supplies adaptable document architecture. Keep subject-specific prose in documents and variable content able to flow.
+
+**Ready:** one coherent direction explains both ordinary reading and the distinctive compositions needed by the brief.
+
+## 3. Implement the bundle
+
+Follow the [Themes contract](../../../docs/THEMES.md) and supported roles exported by `opendoc/themes`. Create or refine `themes/<id>/` with a discoverable pure-data `index.ts`, actionable `design.md`, and a real `preview.tsx`. Add native PDF components only where standard roles cannot express the system.
+
+Keep exact guide values synchronized with executable tokens. Describe component inputs and link their source rather than duplicating implementations. Build the specimen with the actual theme/components and a plausible application; two to four pages is a starting point, not a quota. A theme specimen imports `./index`; an authored document imports its generated `./theme` adapter.
+
+For logos or custom fonts, read [Assets](../../../docs/ASSETS.md) and the font section of Themes before implementing them. Verify local faces and licenses, preserve original artwork, and use semantic document font bindings inside reusable components. For generated visuals, follow [Media](../../../docs/MEDIA.md). Keep reference originals in their existing project location.
+
+**Ready:** the bundle is discoverable, its guide matches its tokens, and the specimen demonstrates the implemented print system.
+
+## 4. Review its real use
+
+Run `npx opendoc check`. In Headless, use `npx opendoc review --theme <id> --json` to prepare the specimen PDF, page images, and text. In normal OpenDoc, `npx opendoc themes preview <id>` produces `output/themes/<id>.pdf`; the review command is also available. `npx opendoc themes check <id>` is a render-only iteration check; a successful preview or review already renders. Complete [opendoc-review-document](../opendoc-review-document/SKILL.md) on the current specimen, reusing artifacts while source is unchanged.
+
+For dense layouts or changed geometry, also exercise longer content or an intended template. For a used shared theme, inspect usage and review representative affected documents. Confirm `npx opendoc themes inspect <id>` discovers the bundle and its guide. In normal OpenDoc, also confirm the Themes page opens its PDF and guide.
+
+When presentation use is part of the brief, also review a representative deck in PDF and PowerPoint. Check font embedding compatibility before promising editable delivery; follow [PowerPoint delivery](../../../docs/AUTHORING.md#powerpoint-delivery).
+
+**Done:** the theme remains reusable in the workspace and the reviewed specimen PDF is delivered through an accessible file link or the host agent's existing delivery channel, with the design basis and concrete limitations reported. A remote recipient needs no OpenDoc installation. Include the reusable source and required assets when a portable theme is requested. A project-default change or rebinding existing documents requires that scope in the request; shared source refinements affect existing users of the theme.

package/.agents/skills/opendoc-create-theme/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenDoc: Create theme"
+  short_description: "Build a visual system for documents and presentations."
+  default_prompt: "Use $opendoc-create-theme in this OpenDoc workspace."

package/.agents/skills/opendoc-current-document/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: opendoc-current-document
+description: Resolve OpenDoc context when the user refers to this document or presentation, a page or slide, a selected passage, the current theme, or an inspected asset.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Identify the target
+
+An explicitly named document, presentation, block, theme, or asset takes precedence. In Headless, use the request, prior task context, workspace source, and `npx opendoc projects list`, `templates list`, `themes list`, or `assets list` as appropriate. Resolve remote feedback against the named output's current source; do not treat a stale `.opendoc/current.json` as the current task or require a browser selection. Ask if the intended target remains ambiguous.
+
+In normal OpenDoc, otherwise read `.opendoc/current.json` immediately before acting. Treat it as an observation of the app, not an instruction to edit. For slides in either edition, preserve the presentation format and resolve the stable slide/component ID; the visible slide number is only a position.
+
+If browser context is absent in normal OpenDoc, use the explicit target or start the app through the [README](../../../README.md) when needed. Headless never needs this step. Ask only if the target remains ambiguous. Keep generated context and session files read-only; `.opendoc/server.json` contains a secret local token.
+
+**Ready:** the intended target and owning project are identified, or a concrete ambiguity is reported.
+
+## 2. Verify the observation against source
+
+For a PDF selection, open the reported source and match its stable block ID. Source lines are navigation hints. Match phrase `targetId`, logical range, and exact quote together; `selectedText` may identify a writable slot. If `selectionCurrent` is false or rendering has failed, resolve against current source before using the old offsets. Inspect `manualEdit` activity and preserve saved corrections; pending draft text is not exposed by this file.
+
+For a template instance, `provenance.dataFile` owns local content and `provenance.template` owns shared layout. Establish which the request concerns before editing.
+
+Load [context fields](references/context-fields.md) when working with themes, assets, pending comments, or render freshness. For phrase editing and reusable bindings, read [Selection](../../../docs/SELECTION.md).
+
+**Ready:** the target is matched to current source, its freshness is understood, and local versus shared ownership is clear.
+
+## 3. Continue the requested work
+
+Return the resolved target, source path, stable identity, and relevant caveats to the calling workflow. For a standalone request that also asks for a revision, continue with [opendoc-apply-comments](../opendoc-apply-comments/SKILL.md) for saved PDF feedback or [opendoc-create-theme](../opendoc-create-theme/SKILL.md) for a print-system change. Resolving context alone requires no mutation or export.
+
+**Done:** the caller has a verified target, or the unavailable/stale target is explained without substituting another one.

package/.agents/skills/opendoc-current-document/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenDoc: Current document"
+  short_description: "Locate the active document, slide, selection, or asset."
+  default_prompt: "Use $opendoc-current-document in this OpenDoc workspace."

package/.agents/skills/opendoc-current-document/references/context-fields.md

@@ -0,0 +1,20 @@
+# Conditional context fields
+
+Read only the section relevant to the selected object. Field paths describe observed state, not authorization.
+
+## Theme or asset selection
+
+- `themeId` / `theme`: the selected theme, document theme, or project default. Definition, guide, specimen, and component paths are pointers; read the chosen `design.md` and needed source. `available: false` requires inspecting the missing definition before choosing a replacement.
+- `selectedAsset`: the inspected logo/font family, saved revision, library head, and selected variation or face. Read its guidance. Navigation does not bind the asset to a document.
+- `theme.assetDefaults`: choices captured for new documents. `documentAssets`: the current document's exact binding file and choices; `saved: false` denotes legacy behavior. Preserve existing bindings and `theme.tsx`; updating defaults does not rebind documents.
+- `renderedAssets`: actual uses, rendered bindings, and `renderHash`. `current: false` means these belong to the last successful PDF. A binding proves availability; rendered usage proves what the PDF used. Inspect asset errors before making substitutions.
+
+Use [Assets](../../../../docs/ASSETS.md) for binding, logo placement, and font compatibility; use [Media](../../../../docs/MEDIA.md) for document-owned visuals, their data, and regeneration.
+
+## Feedback or failed rendering
+
+- `rendering` / `error` status can leave an older successful PDF visible. Read the error and current source before making a claim about the displayed revision.
+- `manualEdit` describes editing activity, pending count, draft-preview status, and the latest committed correction, without exposing draft text. An open editor is not a request to act.
+- Pending phrase comments retain the original quote. `anchorStatus: changed` requires inspecting the intended passage; `missing` or `targetAvailable: false` means the owning block is unavailable. Retain its feedback rather than choosing another occurrence.
+
+For a requested project move, preserve membership through `npx opendoc projects assign <document-id> <project-id>`; context files are generated observations.

package/.agents/skills/opendoc-review-document/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: opendoc-review-document
+description: Review OpenDoc documents and presentations before delivery or when the user requests an audit, including PDF pages, editable PowerPoint exports, and theme or template specimens.
+---
+
+Use the user's OpenDoc workspace as the working directory. `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/` are workspace paths; guide links are relative to this installed skill. Use `npx opendoc` for commands and keep authoring changes out of `node_modules/opendoc`. In Headless, follow [the remote workflow](../../../docs/HEADLESS.md); these commands and imports stay the same, and no browser or recipient-side installation is needed.
+
+## 1. Establish the artifact
+
+Resolve the requested document or specimen and verify it represents the current successful source revision. For active selections in normal OpenDoc, use [opendoc-current-document](../opendoc-current-document/SKILL.md). Headless resolves an explicit ID from task context and workspace source.
+
+In Headless, use the matching review command; it also works in normal OpenDoc. It renders saved workspace source directly, so save pending browser text corrections first when those are intended for delivery. Reuse a just-produced review when its source is unchanged:
+
+```sh
+npx opendoc review <document-id> --json
+npx opendoc review --theme <theme-id> --json
+npx opendoc review --template <template-id> --json
+```
+
+Use the successful result's returned PDF, page images, extracted text, issues, and manifest paths. The manifest identifies the exact PDF hash, page count/dimensions, stable blocks, and source locations. Exit code 0 and `status: "ready"` establish artifact preparation and technical render/layout checks only; `visualReview` and `factualReview` remain `"required"`. The agent must perform the review below. Failed commands preserve previous files, which must not be presented as the failed revision's output.
+
+- **Document:** export with `npx opendoc export <document-id>`.
+- **Presentation:** export the PDF through the same command. When PowerPoint is included, also run `npx opendoc export <document-id> --format pptx`. Default delivery includes both; honor an explicit single-format request. Confirm one 960 × 540 PDF page per authored slide, in the intended order. Review every slide at a readable scale, including source/reference slides; text, images, and captions must fit without clipping or unintended continuation. Check comments and corrections against stable component identity after slide reordering.
+- **Theme:** use `npx opendoc themes preview <theme-id>` and its `output/themes/<theme-id>.pdf`.
+- **Template:** use `npx opendoc templates preview <template-id>` and `output/templates/<template-id>.pdf`, or the specimen review command above. A specimen is not an authored document and needs no library entry.
+- **Supplied PDF:** inspect the caller's file directly with available PDF tools; it does not need importing into OpenDoc.
+
+Read render warnings and relevant feedback. Reuse a just-produced export when its source is unchanged. Rendering/error states may leave an older PDF visible.
+
+**Ready:** the exact current files, page/slide count, brief, and review scope are known.
+
+## 2. Inspect every page
+
+Inspect the review command's page images at legible scale, render pages with an available PDF tool, or use the normal OpenDoc reader. A contact sheet helps assess rhythm; review each page legibly as well. Check hierarchy, reading measure, spacing, page furniture, stranded headings, awkward endings, clipped figures, table continuation, and captions against the document's purpose. Generating page images is not inspection. If the agent cannot view images, state that visual review remains unverified; do not claim the manifest proves visual quality.
+
+**Ready:** every page is accounted for and each material layout issue has a page and description.
+
+## 3. Check content and extraction
+
+Read the review command's extracted text or extract representative text with available PDF tools, including ligatures, symbols, mixed bold/italic boundaries, code, final table rows, and references where present. Verify link/bookmark destinations. Confirm the document addresses its brief and distinguishes evidence, inference, and illustrative material. When claim verification is in scope, compare citations with the underlying sources; a valid reference record alone does not establish support.
+
+Load [Media](../../../docs/MEDIA.md) for managed images/charts: inspect labels, values, provenance, and the actual image. Load [Assets](../../../docs/ASSETS.md) for logos/fonts: compare saved choices with rendered use, inspect the chosen artwork on its page background, and verify copied text. Recorded hashes and isolated specimens are not substitutes for checking the delivered PDF.
+
+**Ready:** relevant content, extraction, navigation, and asset checks have results or an explicit verification limit.
+
+## 4. Check the PowerPoint handoff when included
+
+Follow [PowerPoint delivery](../../../docs/AUTHORING.md#powerpoint-delivery). Confirm the PPTX opens as a valid presentation package, has the intended slide count/order, preserves text and images, and contains native text objects and embedded fonts. Compare slide text with the reviewed PDF or its captured layout; account for whitespace and ligature normalization. A ZIP containing font parts proves packaging, not correct rendering by PowerPoint.
+
+When PowerPoint is available, open the export and inspect slides for font substitution, clipping, missing visuals, and unexpected line wrapping. Verify text remains editable without changing the delivered file; use a disposable copy if testing an edit/save. When native inspection is unavailable, finish available package/content checks and state that native appearance was not verified. This limitation alone does not prevent delivering a valid requested PPTX. Do not require the recipient to install OpenDoc, install fonts or software, rasterize the deck, or change the chosen design just to make a check pass.
+
+If export rejects an unsupported effect or font, resolve it within the user's design direction. Ask when the remedy would change an explicit visual choice or reduce editability. Keep a successful PDF available and clearly identify an outstanding PPTX failure.
+
+## 5. Close the review
+
+For review-only requests, report findings without editing. When revision is in scope, fix material defects, re-export every requested format from the same final source, and inspect changed pages/slides and adjacent breaks. Repeat broader checks only when the change affects them. Shared themes/templates need representative short and long cases and affected-instance checks.
+
+Return verified changes to the calling workflow, which owns feedback resolution. Preserve IDs and comment history during revisions.
+
+**Done:** export the final unchanged revision and deliver the requested files (PDF for documents; PDF and PPTX for presentations by default) through accessible file links or the host agent's existing delivery channel, with the review result and concrete unresolved issues. The recipient needs no OpenDoc installation. A blocking defect means the affected format is not ready to share; identify it rather than claiming completion from a passing render alone.

package/.agents/skills/opendoc-review-document/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenDoc: Review document"
+  short_description: "Review PDFs and decks, content, fonts, and editable exports."
+  default_prompt: "Use $opendoc-review-document in this OpenDoc workspace."

package/AGENTS.md

@@ -0,0 +1,69 @@
+# OpenDoc agent guide
+
+OpenDoc is an English-only workspace for documents and presentations, with two editions from one shared engine and starter library. Normal OpenDoc adds a browser interface for preview, corrections, and comments. OpenDoc Headless runs in an agent's environment and produces finished files without a browser or server. The user directs the work; an external coding agent authors TSX. Deliver reviewed documents as PDF and presentations as both PDF and editable PowerPoint unless the user requests otherwise.
+
+Keep this product scope: no embedded AI, Markdown document authoring, visual theme editor, or cloud collaboration unless explicitly requested. Ordinary document work does not require changing the app or dependencies.
+
+## Work in the user's workspace
+
+Run commands and edit content in the initialized workspace, which contains `.opendoc/workspace.json`. Paths such as `documents/`, `templates/`, `themes/`, `assets/`, and `.opendoc/current.json` refer to that workspace. Installed guides and skill implementations live in `node_modules/opendoc/`; do not treat the package directory as the content workspace or edit its files for document work. Relative guide links below stay within this package.
+
+Use `npx opendoc <command>` in either edition from the workspace or one of its subfolders. Commands discover the workspace through parent directories; use `--workspace /path/to/workspace` when targeting another one. Use `npx opendoc --help` or `<command> --help` for syntax and `--json` for structured output. Both editions install under the `opendoc` dependency alias: `npm:@ryanyahya/opendoc@<version>` for normal OpenDoc and `npm:@ryanyahya/opendoc-headless@<version>` for Headless. This preserves these commands, authoring imports, and guide paths.
+
+In normal OpenDoc, `npx opendoc start` runs in the foreground and opens the browser; use its printed launch URL. Stop the service with Ctrl-C before an authorized `npx opendoc update`. Headless has no browser service. Updates preserve the workspace's edition and authored content.
+
+## Complete remote work with Headless
+
+Read [Headless](docs/HEADLESS.md) when working in the Headless edition or producing files remotely. Initialize it in the agent's environment with `npx --yes @ryanyahya/opendoc-headless init /path/to/workspace`; supply a new or empty destination. The full themes, templates, fonts, examples, and authoring API are available in both editions.
+
+Resolve targets and projects from the request, the agent's task context, and workspace catalogs. Headless does not have an active browser selection: do not require `.opendoc/current.json`, launch a GUI to identify a target, or treat old browser state as the current request. Ask only when the intended work remains materially ambiguous.
+
+Complete the work remotely: author, run `npx opendoc check`, run `npx opendoc review <id> --json`, inspect its page images and extracted text, revise, and export the requested PDF/PPTX. For reusable designs, use `review --theme <id>` or `review --template <id>` and inspect their specimens. Automated checks and generated page images are review evidence; the agent must actually inspect them before claiming visual review.
+
+Deliver files through the host agent's existing attachment, download, or storage capabilities, within the user's requested scope. A filesystem path is useful only when the recipient can access it. The recipient does not need OpenDoc or a local workspace. Keep reusable themes/templates and revision source in the remote workspace for later requests; provide their source and required assets when portability is requested. Do not defer completion to opening the work in normal OpenDoc.
+
+## Find the right starting point
+
+Select and use the relevant OpenDoc skills based on the user's intended outcome, even when the user has not named a skill. Read the matching `SKILL.md` before doing that work, and follow its workflow. Use additional skills as needed during the task, including context resolution, feedback, and PDF review; load only those that apply. Explicit skill invocation is a convenience, not a prerequisite.
+
+For example, “create a presentation from these notes” starts `opendoc-create` directly. Infer the output type from the request, resolve meaningful preferences, then continue through authoring, review, and file delivery. Do not stop at an outline, scaffold, or advice to invoke a skill. User instructions override skill defaults. Ask when uncertainty about audience, theme, template, or output would materially change the result; offer useful choices rather than silently assuming. When the user delegates a choice, exercise judgment and proceed.
+
+| Request | Read |
+| --- | --- |
+| Create a document, report, presentation, slide deck, or PowerPoint | [opendoc-create](.agents/skills/opendoc-create/SKILL.md) |
+| Work on “this document”, presentation, page, slide, or selection | [opendoc-current-document](.agents/skills/opendoc-current-document/SKILL.md) |
+| Apply saved comments or marked feedback to documents or slides | [opendoc-apply-comments](.agents/skills/opendoc-apply-comments/SKILL.md) |
+| Create or refine a theme | [opendoc-create-theme](.agents/skills/opendoc-create-theme/SKILL.md) |
+| Create a reusable page layout, deck skeleton, or data-report template | [opendoc-create-template](.agents/skills/opendoc-create-template/SKILL.md) |
+| Review PDF pages or slides and presentation exports before delivery | [opendoc-review-document](.agents/skills/opendoc-review-document/SKILL.md) |
+
+For application changes, read the relevant runtime and [verification guide](VALIDATION.md). [README.md](README.md) maps the folders and supported launch commands. Load only the specialized guidance needed for the task.
+
+## Create and preserve
+
+- Every document belongs to a project. Resolve it from the request or `npx opendoc projects list`; a normal browser session can also supply fresh `.opendoc/current.json`. Create through `npx opendoc create <id> --project <project-id> --title "Title"`; add `--template <id>` when using a catalog layout. This records membership and companion files before publishing source.
+- For presentations add `--format presentation`, or choose a presentation template with `--template <id>`; its format is inferred. Use `Presentation` with stable `Slide` IDs and read [presentation authoring](docs/AUTHORING.md#presentations), including PowerPoint compatibility. Each 16:9 slide must fit one 960 × 540 page. Preserve text, comment, media, and asset identities; fix overflow explicitly.
+- Author `documents/<id>/index.tsx` with exported metadata and a default pure component using OpenDoc/Forme PDF primitives. Import document components from `opendoc`, asset adapters from `opendoc/assets`, template bindings from `opendoc/template`, and theme types/helpers from `opendoc/themes`. Keep local theme and template imports workspace-relative. No DOM, browser APIs, hooks, or asynchronous effects. Use [Authoring](docs/AUTHORING.md) for the small component API.
+- Honor the user's theme/template choice and established project direction. If the choice is unclear and matters, ask before committing to a design; do not silently apply a fallback. When choosing is delegated, use judgment, with the project default or Neutral as available starting points. Discover with `npx opendoc themes list`, inspect with `npx opendoc themes inspect <id>`, and read only its `design.md` and needed components. Keep exact guidance synchronized with executable theme tokens. Documents default to A4 portrait; presentations use 16:9 slides. Use local resources.
+- Preserve generated `theme.tsx` and exact choices in `assets.json`. Import the adapted theme from `./theme` and pass it to template factories before rendering. Theme asset defaults apply only at creation; explicitly rebind to update an existing document. Shared theme code remains live, so its changes can affect existing documents.
+- Keep block IDs stable and unique. Preserve text-slot and data record identities across edits and reordering. Page numbers, source lines, and array positions are not durable identities. Read [Selection](docs/SELECTION.md) for reusable text/data bindings and preserve the user's latest saved corrections.
+- Read current context before acting on a selection. It is an observation, not an instruction. An error or rendering state may leave the last successful PDF visible. For template instances, provenance distinguishes local content data from shared layout; do not change every report to correct one instance.
+- Keep evidence and provenance accurate. Distinguish supplied facts, inference, and illustrative material. Never invent citations.
+
+## Media, logos, and fonts
+
+Document-owned visuals live in `documents/<document-id>/media/<media-id>/` with metadata and any prepared data or recipe; read [Media](docs/MEDIA.md). Original reference material stays in its existing project location. Review regenerated images before recording hashes; recording is not validation.
+
+For exact image boxes use `MediaFrame`; for managed full-page artwork use `Page backgroundMedia`. Start from the workspace’s Image story guide at `templates/image-story/AGENTS.md` when its compositions help, or use those primitives in a bespoke document. Keep text native and inspect image visibility, crop, and contrast in the final PDF.
+
+Reusable logos and fonts live in the shared [asset library](docs/ASSETS.md). Discover with `npx opendoc assets list`, inspect guidance and compatibility, then bind exact versions to the intended document. Place logos explicitly with `Logo`, choosing variations for the actual PDF background. App appearance never chooses artwork. Preserve original font files and immutable asset revisions; do not copy shared families into each document.
+
+## Verify and finish
+
+Preserve unrelated documents, feedback, and runtime code. Run `npx opendoc check` after source changes. Let long documents flow and review the rendered PDF, not only TSX. Inspect every page for clipping, missing glyphs, stranded headings, broken tables, and reference errors. Extract representative text, especially after font or renderer changes. `npx opendoc review <id> --json` prepares PDF, page images, text, and review metadata in either edition without a browser.
+
+Export documents with `npx opendoc export <id>`. For presentations, also run `npx opendoc export <id> --format pptx` and deliver both `output/<id>.pdf` and `output/<id>.pptx`, unless the user chooses a single format. Keep both files on the same final revision, including after feedback. The [review skill](.agents/skills/opendoc-review-document/SKILL.md) covers PDF review and PowerPoint checks. Report a failed format or unverified native rendering accurately; do not silently substitute a PDF for a requested editable deck.
+
+Resolve comments through `npx opendoc comments` only after making and verifying the change. Keep their history. Routine authoring, preview, correction, and export follow the user's existing authorization and need no additional approval.
+
+`.opendoc/current.json` is generated active context; do not edit it by hand. Use the launch URL printed by the server. `.opendoc/server.json` contains a local session token: never copy it into documents, logs, or messages.

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to OpenDoc
+
+OpenDoc produces agent-authored documents and presentations in two editions from one repository. Normal OpenDoc provides the browser workspace; OpenDoc Headless completes remote authoring, review, and artifact delivery through the host agent. Both share the rendering implementation, authoring API, release version, and full starter library. Contributions should improve those workflows while keeping writing, design choices, and file ownership with the user. Read [AGENTS.md](AGENTS.md) for the agent workflow and [README.md](README.md) for setup and product scope.
+
+## Run and verify
+
+Use a source checkout, the Node version in `.node-version`, and the pnpm version in `package.json`. Installed content workspaces use `npx opendoc`; they do not need the contributor toolchain.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+The service prints its local URL. For the production interface, run `pnpm build` followed by `pnpm start`. Keep the complete dependency installation; rendering uses the TypeScript tools at runtime.
+
+Run `pnpm verify` before opening a pull request. It checks TypeScript, runs the tests, and builds the interface. Follow [VALIDATION.md](VALIDATION.md) for the affected user flow. Rendering changes need inspected PDF output; presentation changes also need PowerPoint export checks. The vendored renderer's [rebuild guide](vendor/formepdf/README.md) explains its reproducible source patches.
+
+Use the disposable fixtures in `tests/helpers.ts` for test documents and mutations. A reusable layout belongs in `templates/`, a visual system in `themes/`, and shared controls in `src/app/ui/`. Keep the shipped library limited to the welcome document and welcome presentation in Getting started. Retain existing stable identities, font licenses, asset revisions, and user corrections.
+
+## Check both installed packages
+
+Build both installable artifacts with `pnpm package:pack`: `output/packages/ryanyahya-opendoc-<version>.tgz` and `output/packages/ryanyahya-opendoc-headless-<version>.tgz`. Both contain the same versioned guides, full editable starter catalogs, and repaired Node Forme engine; normal OpenDoc also contains the built interface. Headless excludes the browser interface and its service dependencies. Use this route instead of a direct `npm pack` from the checkout. `--edition normal` or `--edition headless` supports focused packaging during development.
+
+Exercise each tarball in a disposable location outside the source tree. Confirm normal `init` creates only a new or empty destination, installs an exact application version, and launches the built interface. Test `--no-start` and `--no-open`. Headless `init` always requires an explicit destination and never prompts, opens a browser, or starts a service. Both editions use exact aliases under the `opendoc` dependency key: `npm:@ryanyahya/opendoc@<version>` for normal OpenDoc and `npm:@ryanyahya/opendoc-headless@<version>` for Headless, preserving shared authoring imports and installed guide paths.
+
+In both editions, confirm the full default library, public authoring imports, `check`, review page images/text, PDF/PPTX export, and guidance work without checkout files. Exercise theme/template specimens, ancestor discovery, and `--workspace`. Identical source and resources must produce equivalent outputs; Headless must complete production without browser state or a local GUI handoff. Keep shared engine and catalog code shared rather than adding edition-specific rendering behavior.
+
+Stop any normal service with Ctrl-C before testing updates. Updates must preserve the selected package/edition, all workspace content, and local catalogs; legacy checkout migration and catalog merging are outside this updater. Test both editions through compatible and explicit-version requests.
+
+Use [VALIDATION.md](VALIDATION.md) for the acceptance details. Publishing is a separate, explicitly authorized action against the reviewed tarball; packaging and local installation do not publish it.
+
+## Keep personal work out of contributions
+
+Documents and their media are ordinary local source files. Newly authored work is not automatically private from Git: inspect every staged change before committing. Include only changes needed for the contribution. Do not add personal/client documents, transcripts, imported branding, credentials, browser state, or generated exports. `.opendoc/`, `output/`, and temporary/build directories are ignored; `.opendoc/server.json` contains a local session token and must never be shared.
+
+For a bug report, include the expected behavior, reproduction steps, operating system, Node and npm versions, installed OpenDoc version, and a minimal synthetic example when needed. Include pnpm's version for contributor-checkout failures. Redact paths and private text from logs and screenshots. For security-sensitive issues, follow [SECURITY.md](SECURITY.md).
+
+Explain the problem, resulting behavior, and relevant verification in a pull request. Keep unrelated refactors separate. Contributions follow the repository's MIT license, with third-party components retaining the licenses listed in [THIRD_PARTY.md](THIRD_PARTY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenDoc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.