@ryanyahya/opendoc-headless 0.4.0

package/docs/AUTHORING.md

@@ -0,0 +1,178 @@
+# Authoring documents
+
+Run these commands from your OpenDoc workspace, such as `~/Documents/My OpenDoc`. The installed guides live in `node_modules/opendoc/docs`; paths such as `documents/`, `themes/`, `templates/`, and `output/` below refer to the workspace root. Use `npx opendoc --help` for commands, `--workspace <path>` to choose a workspace explicitly, and `--json` for machine-readable output. From a workspace subfolder, OpenDoc discovers the containing workspace automatically.
+
+The authoring API, full starter library, and commands below are shared by normal OpenDoc and OpenDoc Headless. Headless uses the `opendoc` package alias to preserve imports and guide paths; it needs no browser service. See [Headless](HEADLESS.md) for complete remote production and artifact delivery.
+
+Every document needs a project. Create its initial source and assignment with `npx opendoc create <id> --project <project-id> --title "Title"`, then develop the generated source. Add `--template <template-id>` when using a catalog layout; an ordinary document needs neither a template nor a starter. For imported document folders, use `npx opendoc projects assign <document-id> <project-id>`. See [Projects](PROJECTS.md) for defaults and membership.
+
+Use English, local assets, and a pure TSX component. OpenDoc owns a small set of document primitives; Forme provides the underlying page layout. Arbitrary HTML, browser CSS, React hooks, and asynchronous component effects do not belong inside document source.
+
+## A complete small document
+
+```tsx
+import {
+  Document, Pages, TitleBlock, Section, Paragraph, Cite, References,
+  type DocumentMeta,
+} from 'opendoc';
+import { theme } from './theme';
+
+export const meta: DocumentMeta = {
+  title: 'A useful technical brief',
+  description: 'The decision, its reasoning, and how to check it.',
+  kind: 'technical',
+  theme: theme.id,
+};
+
+export default function Brief() {
+  return <Document title={meta.title} theme={theme}
+    references={{ forme: { title: 'Forme documentation', url: 'https://docs.formepdf.com/' } }}>
+    <Pages title={meta.title} footer="Design notes">
+      <TitleBlock id="opening" title={meta.title}
+        subtitle="Begin with the decision this document supports." />
+      <Section id="context" title="Context" lead="Explain the problem in a short opening.">
+        <Paragraph id="reasoning">Develop the reasoning with evidence. <Cite source="forme" /></Paragraph>
+      </Section>
+      <References />
+    </Pages>
+  </Document>;
+}
+```
+
+Use this inside a document created with the command above; retain the generated `theme.tsx` and `assets.json`. This example demonstrates citation mechanics; replace its source and prose with material relevant to the user's brief.
+
+Import document primitives from `opendoc`, asset adapters from `opendoc/assets`, template contracts from `opendoc/template`, and theme types and helpers from `opendoc/themes`. Keep imports of your own documents, templates, themes, and data relative to those workspace files. Do not import OpenDoc's internal `src/` files.
+
+`meta.kind` is an optional nonempty descriptive label, such as `quotation`. Omit it when a category adds nothing. Metadata describes the document; it does not choose its layout or constrain its structure. Themes are discovered from `themes/<id>/`. Use `npx opendoc themes list` and read only the selected theme’s `design.md`, then the needed component source. New documents import the adapted `theme` from `./theme`, preserving the saved asset choices; `meta.theme` must match the `Document` theme ID. Pass this same theme to any template factory before rendering. Civic Spectrum, Field Manual, McKinsey Consulting, and OpenDoc Neutral supply distinct print systems and reusable compositions. Neutral offers a simpler foundation and is the document fallback. See [Themes](THEMES.md).
+
+## Page structure and reading rhythm
+
+### Presentations
+
+Create a presentation with `npx opendoc create <id> --project <project-id> --title "Title" --format presentation`. It uses the same document folder, theme adapter, assets, media, selection, comments, and text corrections. The format is recorded in `projects.json` before source publication; older entries remain documents. Use the matching root rather than changing the format by swapping components alone.
+
+```tsx
+import { Presentation, Slide, Heading, Paragraph } from 'opendoc';
+import { theme } from './theme';
+
+export const meta = { title: 'A clear idea', description: '', theme: theme.id };
+export default function Deck() {
+  return <Presentation title={meta.title} theme={theme}>
+    <Slide id="opening">
+      <Heading id="opening-title" level={1} style={{ fontSize: 44, lineHeight: 1.1 }}>A clear idea</Heading>
+      <Paragraph id="opening-lead" style={{ fontSize: 24 }}>One thought with room to breathe.</Paragraph>
+    </Slide>
+  </Presentation>;
+}
+```
+
+Each `Slide` is exactly 960 × 540 points (16:9), with 40-point padding by default. Optional `padding` changes the inset; `style` controls the content composition while canvas dimensions remain fixed. `backgroundMedia`, `backgroundImage`, `backgroundOpacity`, `backgroundSize`, and `backgroundPosition` use the same managed background support as `Page`. Place ordinary native content, `MediaFrame`, and `Logo` inside slides. Use current theme fonts and colors, adapting sizes locally for reading at presentation distance; document typography is not automatically scaled.
+
+Every slide needs a unique stable ID, and component IDs remain unique across the whole deck. Preserve both when reordering. Slides cannot nest or contain `Page`, `Pages`, `PageBreak`, or running header/footer primitives. Put all content inside explicit slides. References and source notes also need room on explicit slides.
+
+Overflow is an error: OpenDoc rejects extra pages, content crossing slide boundaries, off-page visuals/text, and clipped content. It does not silently shrink or discard content. Shorten the material, adjust the composition, or explicitly add another slide. Review the updated PDF after text corrections; a failed revision may leave older successful artifacts or the browser preview available, which do not represent that revision. Discover reusable deck skeletons through `npx opendoc templates list` or the browser's **Templates → Presentations**; `--template <id>` infers their presentation format. See [Templates](TEMPLATES.md#presentation-templates). Current themes supply fonts and colors; compose typography for slides locally.
+
+#### PowerPoint delivery
+
+Presentations are delivered as **PDF and editable PowerPoint by default**, unless the user asks for a single format. The PDF is also the reviewed layout used for PowerPoint export. From the same final source revision, run:
+
+```sh
+npx opendoc export <id>
+npx opendoc export <id> --format pptx
+```
+
+Deliver `output/<id>.pdf` and `output/<id>.pptx`. After a source, media, or font change, regenerate and review the affected output in both formats. Do not mix an updated PDF with an earlier deck. See [the review skill](../.agents/skills/opendoc-review-document/SKILL.md).
+
+Compose for the editable export from the beginning:
+
+- Native text, rectangular shapes, solid borders, and images are supported. Text becomes editable boxes with the reviewed line breaks. Images and chart artwork remain images; tables assembled from blocks remain separate objects.
+- Embedded fonts must have TrueType outlines and permit editable embedding. PowerPoint has regular, bold, italic, and bold-italic slots; different faces competing for the same family/style slot cannot be preserved together. Use the exact selected asset faces and verify an early export when introducing custom fonts. Do not silently replace an explicitly chosen font.
+- Unsupported effects, including transforms, shadows, gradients, rounded shape corners, group opacity, justified text, and custom word spacing, fail with a specific error. Use compatible compositions within the brief; ask if resolving an error would materially change the user's chosen design or editability. Do not flatten the whole slide to work around an editable-export failure.
+- Significant edits in PowerPoint can require resizing or reflowing a text box; PowerPoint does not rerun Forme. Inspect native rendering when available, and state verification limits accurately. A successful export or embedded-font record alone is not proof of identical appearance across platforms.
+
+#### Document primitives
+
+| Primitive | Use |
+| --- | --- |
+| `Document` | One root; title, author, theme, reference records, and citation mode |
+| `Pages` | Flowing pages; optional size, margins, running header/footer text, and page numbers |
+| `Page` | Custom native page composition, including reliable full-page background colors |
+| `Cover` | A deliberate opening page with title, subtitle, footer, and optional stable `idPrefix` |
+| `TitleBlock` | A compact title, optional subtitle/byline, and restrained dividing rule |
+| `Section` | A heading plus a short lead held together; subsequent children flow naturally |
+| `Heading` | Levels 1–3 with automatic PDF bookmarks; `bookmark={false}` suppresses one |
+| `Paragraph` | Readable prose with widow/orphan controls and optional whole-block `href` |
+| `Block` | A stable feedback target around a custom Forme visual or composition |
+
+Use `Section` for ordinary prose sections. Its lead is deliberately limited to 700 characters; put longer content in normal paragraphs inside the section. Do not place an entire long section, table, or variable data report in an unbreakable container.
+
+`Pages` defaults to the theme's A4 portrait layout. It also accepts Forme page sizes or a custom `{ width, height }` in points, `margin`, `header`, `footer`, and `pageNumbers`. Set header/footer to `false` to suppress them. For custom page compositions import `Page` from OpenDoc, with native Forme primitives inside; it handles the current engine's page-background limitation. Columns are appropriate for short independent material; they are not a promise of sequential magazine text flow. Use a composed opening followed by flowing pages for long publications.
+
+## Tables, figures, lists, and code
+
+`DataTable` takes `columns` and `rows`. Columns have `label`, optional positive `width` weights, and optional `align: 'left' | 'center' | 'right'`. Numeric columns align right automatically. Cells are strings, finite numbers, or transparent text bindings; every row must match the columns. Optional `rowIds` preserve cell targets when records reorder. Optional `caption` and `sourceNote` explain the table. The caption and column headings repeat on continued pages. An empty table displays `emptyMessage` instead of pretending to contain observations.
+
+```tsx
+<DataTable id="measurements" caption="Illustrative measurements"
+  columns={[{ label: 'Condition', width: 2 }, { label: 'Time (ms)' }]}
+  rows={[["Baseline", 24], ["Revised", 19]]}
+  sourceNote="Synthetic values for demonstrating table layout." />
+```
+
+`Figure` keeps its visual, caption, and optional source note together. Size the visual to fit the available page area. Use managed `Media`, or supported local `Svg` or `Image` content, with useful alternative text. Do not treat a diagram or chart as evidence without identifying its basis. Very long labels and oversized figures require visual review.
+
+OpenDoc rejects native Forme chart components on the current engine: their label encoding is incompatible with OpenDoc's embedded fonts, and changing the chart's font style does not correct it. Generate a local chart asset and place it in `Figure`; review every label, unit, scale, and legend in the exported PDF. Keep the underlying data with the document.
+
+Prefer managed `<Media item="id" width={460} />` inside `Figure` for photos, charts, and diagrams. Each item has its own folder, metadata, and optional prepared data. Leave supplied inputs in the project’s existing organization. Optional source notes identify provenance; OpenDoc does not manage those originals. Read the [media guide](MEDIA.md) before adding or regenerating media.
+
+For exact image rectangles use `<MediaFrame item="id" width={460} height={240} fit="cover" />`; use `fit="contain"` to preserve the whole image, `position={{x:0.5,y:0.5}}` to align the crop, or `radius` for rounded/circular frames. Use `<Page backgroundMedia="id" backgroundSize="cover">` for managed full bleed with native text on top. These follow the same freshness and usage contract as `Media`. See [image placement](MEDIA.md#image-frames-and-full-page-artwork) and the Image story guide at workspace-root `templates/image-story/AGENTS.md` for reviewed starting compositions and renderer limitations.
+
+Direct local image paths resolve relative to the document folder; managed `Media` adds browser discovery and provenance checks. For `documents/cooling-review/chart.png`, use:
+
+```tsx
+<Figure id="cooling-chart" caption="Illustrative cooling curves."
+  sourceNote="Synthetic measurements; see the accompanying data file.">
+  <Image src="./chart.png" alt="Two illustrative temperature curves over 30 minutes."
+    style={{ width: 460, height: 260 }} />
+</Figure>
+```
+
+`List` takes `items: { id, children }[]`, with optional `ordered` and `start`. Record IDs survive reordering. Omit empty lists. Items remain together and the list flows between items; a single item must fit on a page.
+
+For continuous essay text with first-line indentation, use `Prose` as described in [Continuous prose](PROSE.md). It preserves ordinary paragraph IDs and source bindings.
+
+Lists use ordinary text rows because the current engine mismeasures native wrapped list items. Their text and numbering remain selectable, but the PDF does not carry native list structure tags.
+
+`Callout` accepts inline or block children and an optional title. Use it when the reader needs to notice a limitation, decision, or instruction, not as a container for every paragraph.
+
+`CodeBlock` accepts a literal string, optional `language`/`caption`, and `tabSize` (2, 4, or 8). It uses the bundled monospace face and preserves indentation. Long source lines can wrap; inspect code where wrapping could change how a reader interprets it. Keep executable examples accurate. `Strong` and `Em` use real weight and italic faces from the selected family. Explicitly unavailable styles fail instead of being synthesized.
+
+## Evidence and references
+
+`Document` accepts a `references` object keyed by stable source IDs. Each record needs a `title`. Include an HTTP(S) `url` when one exists; print sources do not need a fabricated link. `author` and `year` are optional for numeric citations and required for author-date citations.
+
+- `<Cite source="key" />` reuses its number on repeated citations. An optional `locator="p. 12"` identifies a page or section of the source.
+- `<Document citationStyle="author-date">` uses author/year labels and disambiguates matching author/year pairs.
+- `<References />` includes all cited sources, even when the list is placed before a citation in source. Prefer placing it at the end for readers. Omitting the list when citations exist is an error.
+- `<CrossReference target="measurements" />` resolves a figure/table number or heading/section title, including forward references. Unknown targets fail instead of showing a fabricated label. Referenced tables need visible captions; inconsistent manually numbered captions fail clearly.
+- `<Note id="method-detail">Additional explanation.</Note>` creates an inline marker; `<Notes />` prints the endnotes. The notes section is required when notes exist.
+
+These are simple numeric and author-date formats, not a complete citation-style processor. Cross-references identify labels rather than page numbers. Reference-list entries carry working PDF links; Forme 0.20.1 does not emit working annotations for inline link runs. Use `Paragraph href` for a whole-block link.
+
+OpenDoc validates reference records and relationships. It does not verify whether a source supports a claim, whether a calculation is correct, or whether a study design is sound. Keep synthetic examples, measured observations, and inference distinct.
+
+## Durable feedback
+
+Every commentable block needs a unique, stable `id`. Preserve it when rewriting or moving the same idea; assign a new ID to a different idea. Avoid IDs derived from page numbers or array positions.
+
+Selections can identify individual phrases within those blocks. Literal document-owned text supports quick corrections; reusable props and instance data use transparent `TextSlot` bindings. Preserve slot and record IDs alongside block IDs. See [Selection and quick corrections](SELECTION.md) for the binding and agent-context contract.
+
+Composite primitives reserve their child IDs. `TitleBlock id="opening"` creates `opening-title`, `opening-subtitle`, and `opening-byline` when present. `Section id="method"` creates `method-heading` and `method-lead`. `List id="steps"` combines its ID with each item ID. `Cover` defaults to the `cover-` prefix; choose another prefix for a second cover. References reserve `reference-<source-id>` and notes reserve `note-<note-id>`.
+
+Data-driven reports should export provenance identifying their shared template and their own data file. See the monthly report contract at workspace-root `templates/monthly-report/README.md` and the [opendoc-create-template skill](../.agents/skills/opendoc-create-template/SKILL.md). A content correction belongs in the instance data; a layout change may affect every instance.
+
+## Finish at the PDF
+
+Run `npx opendoc check`. `npx opendoc review <id> --json` prepares a fresh PDF, page images, extracted text, and structured review evidence without a browser; save intended browser corrections first when using it in normal OpenDoc. Inspect every page at readable size, read render issues, and check representative text, including symbols, code, and the final rows of long tables. Verify references and links that matter to the document. Revise as needed, then use `npx opendoc export <id>` to deliver the final unchanged revision. Presentations also need the requested PowerPoint export described above. Remote agents deliver accessible files through their existing channel; the recipient needs no OpenDoc installation.
+
+The geometry checks reject concrete off-page content, clipping, and header/footer overlap. They allow deliberate page backgrounds and do not enforce an aesthetic template. Warnings point to possible stranded headings or empty pages. They are aids to review, not a guarantee of perfect formatting or accessibility conformance.

package/docs/HEADLESS.md

@@ -0,0 +1,120 @@
+# OpenDoc Headless
+
+OpenDoc Headless is the complete document-production workflow for agents running remotely. Ask the agent for a report, presentation, theme, or template; it authors, renders, reviews, and revises the work, then returns the finished files. The recipient opens the PDF or PowerPoint on any device and does not need OpenDoc installed.
+
+Both editions come from the same open-source repository, use the same version and rendering implementation, and include the full starter library: editable templates, themes, fonts, and welcome examples. Headless omits the browser interface and its service dependencies. It has no embedded AI, hosted service, or messaging connector. The host agent supplies the model, task context, filesystem access, and delivery channel.
+
+## Install in the agent's environment
+
+Requires Node.js 24 or newer and npm on macOS or Linux. Run:
+
+```sh
+npx --yes @ryanyahya/opendoc-headless init ./workspace --json
+cd ./workspace
+npx opendoc --help
+```
+
+Supply a new or empty destination. Headless initialization is noninteractive and never opens a browser or starts a service. It installs an exact version, copies the full editable starter library, and writes the workspace's project records and versioned agent-guide pointers. Installation and updates need network access; rendering local content does not.
+
+Run subsequent commands from the initialized workspace or one of its subfolders. Use `--workspace /absolute/path/to/workspace` to target it from elsewhere. The `.opendoc/workspace.json` marker records `edition: "headless"`. Its package dependency uses an npm alias, for example:
+
+```json
+{
+  "dependencies": {
+    "opendoc": "npm:@ryanyahya/opendoc-headless@0.4.0"
+  }
+}
+```
+
+Normal OpenDoc similarly aliases `opendoc` to `npm:@ryanyahya/opendoc@<version>`. These aliases keep `npx opendoc`, `node_modules/opendoc/`, and authoring imports such as `opendoc/assets` identical in both editions. Do not add the normal package to obtain document components. Edit the workspace's `documents/`, `themes/`, `templates/`, and `assets/`; installed package files are application code and versioned guidance.
+
+The agent may retain this workspace for later requests or create a disposable one for a single job. A command exits after its work; no persistent OpenDoc process is required. Retain the source and resources before discarding a workspace when future revisions or reusable designs are part of the request.
+
+## Author, inspect, revise, deliver
+
+Follow [AGENTS.md](../AGENTS.md) and its matching skills. All shared writing, design, provenance, stable-identity, media, font, and export rules apply. Resolve document and project IDs from the request and workspace catalogs; an old `.opendoc/current.json` is not current remote task context. Do not start the browser to resolve a target.
+
+For example, discover the available designs and create a project and document:
+
+```sh
+npx opendoc themes list --json
+npx opendoc templates list --json
+npx opendoc projects create client-work --name "Client work" --theme neutral --json
+npx opendoc create my-report --project client-work --title "Project report" --json
+```
+
+Honor the user's design choices; when choosing is delegated, use judgment. An existing project can be reused. Creation makes a scaffold, project membership, `theme.tsx`, and exact `assets.json` bindings. The agent then writes the actual report in `documents/my-report/index.tsx` using the [authoring API](AUTHORING.md). A scaffold is not a finished deliverable.
+
+After authoring:
+
+```sh
+npx opendoc check --json
+npx opendoc review my-report --json
+```
+
+`check` typechecks workspace source. `review` renders fresh saved source and produces the PDF, readable page PNGs, extracted page text, and a `review.json` manifest. For documents and presentations these live under `output/reviews/documents/<id>/`; theme and template specimens use `output/reviews/themes/<id>/` and `output/reviews/templates/<id>/`. Use the returned paths instead of guessing filenames. The same command works in normal OpenDoc; save intended browser text corrections before reviewing saved source there.
+
+The result identifies the exact PDF hash, output paths, page count and dimensions, page images/text, render issues, and stable block/source information. `status: "ready"` and exit code 0 mean the review artifacts were prepared and technical render/layout checks passed. **They do not mean visual or factual review is complete.** The manifest keeps `visualReview` and `factualReview` as `"required"`.
+
+The agent must inspect every page image at a readable scale, examine representative extracted text, and check the content against the brief and sources. Fix clipping, missing glyphs, awkward breaks, bad crops, incorrect claims, and other material defects. After changing source, regenerate the review artifacts and inspect affected pages and adjacent breaks. The [review skill](../.agents/skills/opendoc-review-document/SKILL.md) defines the full pass. If the agent cannot inspect images, report that concrete limitation; generating PNGs is not visual inspection.
+
+Render and source-freshness failures return a nonzero exit status and structured diagnostics when available. They leave the previous successful review files intact, so those files must not be represented as the failed revision's output. Inspect the current command result before using an existing path.
+
+When the final revision is ready:
+
+```sh
+npx opendoc export my-report --json
+```
+
+This writes `output/my-report.pdf`. Export renders fresh in Headless, independently of any browser session or stale server state. Keep source unchanged between final review and export, and use the exported file for delivery.
+
+## Presentations
+
+Create a slide scaffold with `--format presentation`, or use a presentation template whose format is inferred:
+
+```sh
+npx opendoc create project-deck --project client-work --title "Project update" --format presentation --json
+```
+
+Author `Presentation` and explicit `Slide` components, preserving one 960 × 540 PDF page per slide. Complete the same check/review/revise cycle, then export both formats from the same final source:
+
+```sh
+npx opendoc export project-deck --json
+npx opendoc export project-deck --format pptx --json
+```
+
+Deliver both `output/project-deck.pdf` and `output/project-deck.pptx` unless the user requests a single format. Review the PDF even for a PowerPoint-only request because it supplies the layout used for export. Follow [PowerPoint delivery](AUTHORING.md#powerpoint-delivery) for supported effects, editable objects, font embedding, package/content checks, and native inspection when available.
+
+A remote environment need not have Microsoft PowerPoint installed. Complete available PDF and PPTX package/content checks and state when native PowerPoint appearance was not verified; that limitation alone does not prevent delivery of a valid requested file. A failed PPTX export is a separate incomplete format and must be reported and corrected within scope.
+
+## Create themes and templates remotely
+
+Use [opendoc-create-theme](../.agents/skills/opendoc-create-theme/SKILL.md) or [opendoc-create-template](../.agents/skills/opendoc-create-template/SKILL.md). Author the reusable bundle in its workspace catalog, then inspect its real specimen without a browser:
+
+```sh
+npx opendoc review --theme my-theme --json
+npx opendoc review --template my-template --json
+```
+
+Each produces the same page-image, text, PDF, and manifest evidence as a document review. Specimens stay outside the document library and need no project membership. The lighter `themes check <id>` and `templates check <id>` commands validate and render without exporting a specimen. `themes preview <id>` writes `output/themes/<id>.pdf`; `templates preview <id>` writes `output/templates/<id>.pdf`.
+
+Verify catalog discovery with `themes inspect <id>` or `templates inspect <id>`, inspect every specimen page, and exercise representative content and affected instances as required by the skill. Keep the completed theme or template in the remote workspace for reuse. Return its reviewed specimen PDF to show the design. If the user requests a portable bundle, include its source, guide, specimen source, and required local dependencies/assets with their licenses; a specimen PDF alone is not a reusable theme or template.
+
+## Deliver through the host agent
+
+OpenDoc produces files and machine-readable results. The agent sends the requested artifacts through its existing attachment, download, or storage capabilities, within the user's requested destination and scope. For example, a messaging agent may attach the PDF to its current conversation; another agent may expose a downloadable file.
+
+Return accessible artifacts, not a remote-only filesystem path the recipient cannot open. Do not send internal review manifests, source material, or unrelated workspace files unless requested. Keep the final response focused on the deliverables and any concrete unresolved limits. The recipient should never need to install OpenDoc, start its GUI, or repeat the agent's review to complete the requested production workflow.
+
+## Update
+
+From the workspace:
+
+```sh
+npx opendoc update --check --json
+npx opendoc update --json
+```
+
+Updates stay on `@ryanyahya/opendoc-headless` and pin the selected exact version while preserving authored documents, templates, themes, assets, feedback, and project records. They update the installed application and its guidance together; they do not overwrite local catalogs with newly shipped examples. See the [update rules](../README.md#update-an-existing-workspace) for compatible versions and explicit version selection.
+
+The workspace runs trusted TSX code. Render workers contain crashes and timeouts, not hostile code. The host agent's environment owns its own isolation and access controls; see [Security](../SECURITY.md).

package/docs/MEDIA.md

@@ -0,0 +1,112 @@
+# Document media
+
+Each document owns its prepared media. OpenDoc embeds and previews those visuals; the project and coding agent manage original reference material. There is no source library or required source-folder layout. Reusable logos and fonts belong in the shared **Logos** and **Fonts** tabs of **Media & Assets**; see [Assets](ASSETS.md). Do not copy those families into each document's media folder.
+
+Run commands from the workspace root. The paths below refer to that workspace, not the installed package containing this guide.
+
+```text
+documents/cooling-curves/
+  index.tsx
+  media/
+    cooling-curves/
+      meta.json                 title, description, file and relationships
+      image.png                 the embedding image
+      data.json                 rows prepared for this chart
+      recipe.py                 optional reproducible preparation
+      generation.json           recorded image and input hashes
+    temperature-drop/
+      ...                       another view of the same source
+```
+
+Original datasets, supplied PDFs, previous drafts, and reference documents stay wherever the surrounding project manages them. Do not copy or move originals just to satisfy OpenDoc. Several documents may use the same original. Prepared selections, calculations, chart specifications, and editable diagram files belong beside the image that uses them. The coding agent interprets the originals, prepares visuals, and checks evidence and attribution.
+
+## Describe a visual
+
+Every `media/<id>/meta.json` requires `title`, `description`, `file`, and `kind`. IDs use lowercase words separated by single hyphens. `kind` is `photo`, `illustration`, `chart`, `diagram`, or `image`.
+
+```json
+{
+  "title": "Temperature over time",
+  "description": "Two illustrative cooling curves from one synthetic dataset.",
+  "file": "image.png",
+  "kind": "chart",
+  "alt": "Cup A falls from 80 to 53 degrees Celsius; Cup B falls to 62.",
+  "sources": ["Project teaching dataset; synthetic, not measured"],
+  "data": "data.json",
+  "recipe": "recipe.py",
+  "attribution": "Synthetic teaching example; no experiment was conducted."
+}
+```
+
+`alt`, `sources`, `data`, `recipe`, and `attribution` are optional. `sources` contains descriptive provenance notes or locations for the author: OpenDoc displays the text but never resolves, downloads, hashes, or requires those files. Existing source-path notes remain valid. `file`, `data`, and `recipe` identify owned files relative to the media item; parent traversal, hidden paths, and symlinks are rejected for these files. Unknown fields are rejected. Titles are limited to 200 characters; descriptions and each source note to 4,000.
+
+PNG and JPEG are the supported media embedding formats, up to 50 MB and 100 megapixels. Preserve an SVG or other editable original alongside a PNG export; arbitrary SVG text rendering is not reliable in the current PDF engine. Shared logos have their own SVG/PNG import path with automatic PNG preparation; use [Assets](ASSETS.md) for those. Use an image large enough for its printed size—about 300 pixels per inch for charts—and inspect labels at actual reading size. Keep important chart values in a selectable table as well: raster chart labels are image pixels in the PDF.
+
+## Add, generate, and review
+
+Use the existing image tool or a suitable chart/diagram tool to produce the visual. The media contract does not choose a generator, run recipes automatically, or install their dependencies. Choose tools already available for the task. Keep any recipe reproducible and resolve its files from its own location. Sample documents are not a required dependency.
+
+```sh
+npx opendoc media import my-report overview --file /path/to/image.png --title "Overview" --description "The main stages." --kind diagram
+```
+
+Media imports copy an image and refuse to overwrite an existing media folder. Media is added by the agent from chat attachments, generated visuals, or downloaded images. The app browses these document-owned folders and edits their details; it has no media upload form. An ordinary photograph can consist of only an image and metadata. For generated work, add the prepared data and recipe before recording it. Add provenance notes when useful. Editing a title, description, or other metadata in the app never records a generated visual as reviewed.
+
+After generating, review the actual image for values, labels, scales, units, and provenance. Then record the reviewed inputs:
+
+```sh
+npx opendoc media record my-report overview
+npx opendoc media check my-report overview
+```
+
+`record` snapshots file hashes; it does not generate or validate a chart. Never use it just to silence a stale warning. Changing prepared data, a recipe, or a recorded image marks the item as needing regeneration. Regenerate and review the affected images, then record their new versions. Original-source changes are the author’s responsibility; OpenDoc does not infer whether they require a new chart or a revised argument. Images with inputs but no generation record also require review and recording.
+
+## Place it in the PDF
+
+```tsx
+<Figure id="overview-figure" caption="The main stages." sourceNote="Based on the supplied reference.">
+  <Media item="overview" width={460} />
+</Figure>
+```
+
+Import `Media` from `opendoc` with the other document primitives. Width is a positive value in PDF points. An optional positive `height` sets a maximum bound; the image keeps its aspect ratio. Alternative text defaults to metadata, or can be supplied as `alt`. Preserve the enclosing Figure ID when replacing an image so feedback stays attached.
+
+The document cannot export a stale or unrecorded derived image. Its previous successful preview remains visible, with the current error. After recording, export and review the actual PDF, including caption placement and adjacent page breaks. Raw `Image` and vector `Svg` primitives remain available, but only managed media items appear in the Media browser and receive these provenance checks. For pictures inside SVG layouts, use the frame support below.
+
+## Image frames and full-page artwork
+
+Use `Media` when an image should keep its natural proportions inside a maximum bound. Use `MediaFrame` when the layout needs an **exact rectangle**. It supports `cover` (default: proportional crop) or `contain` (whole image, transparent unused space), normalized `position` (`0` left/top, `0.5` center, `1` right/bottom), and an optional `radius` in PDF points. Width and height are required. Dimensions in `style` do not override them.
+
+```tsx
+import { Block, Figure, MediaFrame, Page, Heading, Paragraph } from 'opendoc';
+
+<Figure id="opening-scene" caption="A supplied photograph of the site.">
+  <MediaFrame item="site" width={490} height={240}
+    fit="cover" position={{x:0.65,y:0.5}} />
+</Figure>
+
+// A circular crop. Use containment for diagrams and images whose labels must stay visible.
+<Block id="portrait"><MediaFrame item="portrait" width={160} height={160} radius={80}/></Block>
+
+// Artwork reaches the page edges; the margin only reserves room for the native text.
+<Page size="A4" margin={48} backgroundMedia="cover-art" backgroundSize="cover">
+  <Heading id="cover-title" level={1} style={{color:'#ffffff',fontSize:54}}>A short title</Heading>
+  <Paragraph id="cover-subtitle" style={{color:'#ffffff'}}>Choose quiet image space for the words.</Paragraph>
+</Page>
+```
+
+Frames and `backgroundMedia` use the same document-owned media IDs, freshness checks, and usage records as `Media`. Frames inherit their enclosing `Block` or `Figure` for feedback; a page background records page-level usage without a block selection. Missing named images fail rendering. You cannot combine `backgroundMedia` and `backgroundImage` on one page. For an unmanaged local PNG/JPEG, `backgroundImage="./image.png"` resolves relative to the authored document; it does not add managed provenance. Managed backgrounds default to centered `cover`; `backgroundSize="contain"` preserves the whole picture, and `backgroundPosition` accepts `center` or a corner such as `top-left`. OpenDoc prepares these proportional local-image backgrounds before sending them to the native page layer, which otherwise stretches images. Explicit `fill` retains stretching; remote URLs retain the native renderer's behavior.
+
+The installed renderer prepares cropped/rounded frames as bounded PNGs, leaving the originals intact and surrounding text selectable. It uses up to 216 dpi with a 4096-pixel edge limit; this does not add detail to a low-resolution source. You do not need to read files, encode base64, import a native addon, or clip an oversized `Image` yourself. Native SVG `<image>` content can disappear without an export error, so use `MediaFrame` for image composition instead. Do not rasterize an entire text page to work around image placement.
+
+For starting compositions, read workspace-root `templates/image-story/AGENTS.md` and view its real PDF in **Templates**. It demonstrates full bleed, vertical/horizontal halves, panoramas with insets, diptychs, collage, and floating text panels. You can use the primitives without using that template. Generate or choose images for their intended aspect ratio and quiet text areas; never crop away a face, important object, label, or evidence merely to match a frame. Always inspect the rendered PDF for image visibility, crop, contrast, caption placement, and text extraction. A successful export is not a visual review.
+
+## Browse and continue with Codex
+
+The **Media** tab in **Media & Assets** lists visuals across documents, searchable by title, description, kind, and document. Existing Media links keep working. Byte-identical images share one browser card; ownership, metadata, and source relationships stay separate. A filename match alone never merges images. The detail view shows their document, current PDF usage, prepared files, and optional source notes.
+
+File downloads are limited to document-owned media files. Original references are shown only as source notes. Selecting a media item updates `.opendoc/current.json` with its folder, metadata, and input status so Codex can work on the right item. Selection remains observed context, never an instruction to change the document. Metadata is editable in the app or through ordinary local files and the coding agent; prepared data, recipes, and regeneration remain agent work.
+
+## Existing projects
+
+Existing original files and media folders remain in place. Older generation records may contain original-source hashes; those remain historical information and no longer participate in media checks. Current checks cover only the image and its own prepared data and recipe. Normal document imports still participate in dependency tracking and rerendering. Citations, references, and source notes in PDFs continue to work independently of file organization.

package/docs/PROJECTS.md

@@ -0,0 +1,55 @@
+# Projects
+
+A workspace contains projects, and every newly created document must have a project. A new workspace starts with **Getting started** and the **Welcome to OpenDoc** document and welcome presentation. Paths in this guide refer to the workspace root; the installed guide itself lives in `node_modules/opendoc/docs`.
+
+## In the app
+
+Use the **+ beside Projects in the sidebar** to create a project. A name is required; a default theme is optional. Choose a project in the sidebar to create and find its documents. **Documents** shows all documents across the workspace, with project links beneath their previews. There is no separate projects overview page. On narrow screens, **Open sidebar** reveals the full project list and creation button. **Project settings** changes its name or default theme. **Move to project** changes an existing document’s membership. A project can be deleted only when it has no documents.
+
+**Create document** and **Create presentation** provide agent prompts carrying the current project, without a title, purpose, or theme form. **Use this template** and theme-based creation carry the selected layout or theme in the prompt. The agent follows [opendoc-create](../.agents/skills/opendoc-create/SKILL.md), resolves any missing project from the brief or current context, and asks when a meaningful design preference is unclear. Naming the skill is optional. Creation requires project membership; the CLI uses an explicit theme override, then the project default, then Neutral. Those fallbacks apply after the agent resolves the user's direction. Explicitly requested starter examples retain their own fallback themes. Changing a project default applies to future work. Moving a document or presentation keeps its existing theme.
+
+Switch between **Gallery** and **List** beside the document count in Documents or any project. List shows a compact first-page PDF thumbnail, name, document details, and a project link in Documents. The browser remembers one shared view preference. Switching views preserves the current search.
+
+The **…** menu on every card or list row offers **Rename**, **Duplicate**, **Move to project…**, and **Delete**. These actions also appear in the reader’s **Document options** menu. Rename changes the library name; the PDF title stays authored in source. Duplicate copies saved source, local media, and feedback into the same project, rebinding supplied template instance IDs and local data paths. It does not include unsaved browser drafts. Delete asks for confirmation and shows an **Undo** notification. Its saved folder and receipt remain recoverable in `.opendoc/trash/<restore-id>/`; existing PDF exports remain in `output/`. Restore refuses to overwrite a reused ID and requires the original project to exist.
+
+Opening a document hides the workspace sidebar and gives the reader the full window. The header’s back arrow returns to the project, Documents, or other workspace view you opened from and restores navigation. A directly opened document returns to its project, or Documents if it has no project. The same pattern applies on mobile.
+
+If files from an older workspace have no assignment, **Documents** keeps them accessible and offers **Choose a project** beneath each unassigned document. OpenDoc does not invent a replacement project or silently discard these files.
+
+## Local files
+
+`projects.json` owns project names, optional default themes, document assignments, and optional library names:
+
+```json
+{
+  "version": 1,
+  "projects": [
+    { "id": "getting-started", "name": "Getting started", "defaultTheme": "neutral" }
+  ],
+  "assignments": { "welcome": "getting-started" },
+  "names": { "welcome": "Workspace guide" }
+}
+```
+
+Documents remain at `documents/<id>/index.tsx`. Grouping is separate from physical folders. Renaming projects or documents and moving documents do not move files or rewrite imports, media, comments, or PDF contents. Document IDs are unique across the workspace. Templates and themes remain shared resources.
+
+The creation service records membership before exposing a new document entry. Browser and command-line changes serialize through a local lock and atomically replace the manifest. Invalid registries are reported without being overwritten. If a process terminates while holding the project lock, the next operation recovers it only after confirming the owner is no longer running. An active or unrecognized lock remains protected; retry after the other operation finishes rather than deleting its lock blindly.
+
+The optional `names` map is keyed by stable document ID. Without an override, the app uses the PDF metadata title. The generated `.opendoc/current.json` distinguishes the library `name` from the authored `title` and includes the active project and its default theme alongside the document or selection. Do not edit this generated context by hand.
+
+## Commands
+
+Run from the workspace root, or add `--workspace <path>`. Use `npx opendoc --help` for the command list and `--json` for machine-readable output.
+
+```sh
+npx opendoc projects list
+npx opendoc projects create client-work --name "Client work" --theme neutral
+npx opendoc projects update client-work --name "Client publications" --theme civic-spectrum
+npx opendoc projects update client-work --theme none
+npx opendoc create proposal --project client-work --title "A proposal"
+npx opendoc create brief --project client-work --title "A technical brief" --theme field-manual
+npx opendoc projects assign proposal client-work
+npx opendoc projects delete empty-project
+```
+
+A missing or unknown project prevents creation before any document folder is written. Use the normal creation command for bespoke documents too, then replace its editable source. If importing existing document folders, assign each one using the project command. Preserve unrelated assignments and stable document IDs.

package/docs/PROSE.md

@@ -0,0 +1,15 @@
+# Continuous prose
+
+`Prose` is an optional OpenDoc region for continuous reading text. The Editorial essay template uses it for its body. Existing documents retain their paragraph behavior unless they explicitly use this region.
+
+It leaves the first paragraph flush left and indents subsequent paragraphs by 1½ em. Paragraph gaps default to zero; set `paragraphGap` to a non-negative number of points for extra spacing. Editorial essay uses `<Prose paragraphGap={6}>`. Headings, section starts, figures, tables, callouts, lists, and explicit breaks restart the reading sequence. Section lead paragraphs stay flush; their following paragraphs indent. Captions, tables, and reference entries do not receive body formatting. Pure author components and fragments expand before formatting, so their paragraph IDs and source locations remain available for comments.
+
+## Forme compatibility
+
+Forme 0.20.1 has no native first-line-indent style. OpenDoc uses an isolated inline U+2003 em-space run, sized to the requested indent. Its measured advance is fixed; an ordinary leading whitespace string is stretchable glue in this engine and does not reliably preserve its width. This is a compatibility shim, not a native Forme feature. No word joiner, tabs, manual line splitting, dependency patch, or full-paragraph padding is involved.
+
+The body uses greedy line breaking by default to keep measured text within the column in this renderer. An explicit paragraph `lineBreaking` choice takes precedence. The spacer appears only at the paragraph's beginning; Forme handles all subsequent lines and page fragments. It leaves the body line height unchanged. Searchable and copied text retain the authored words; layout-oriented extraction may include normal indentation spaces.
+
+This helper deliberately supports one measured 1½-em indent. Do not generalize it to arbitrary spacing without new PDF coordinate checks: Forme can merge a spacer run that has the same font size as the body and treat it as stretchable whitespace. Do not nest `Prose` regions; sibling regions start separate paragraph sequences. Keep regions within a single document's body. Use a separate region or a structural break to begin a new passage, not blank paragraphs.
+
+Regression checks read actual PDF coordinates with the bundled Sans and Serif fonts, check continuation lines across pages, verify heading/figure/section resets, and preserve mixed inline formatting, citations, source locations, and existing non-Prose paragraphs. Recheck the spacer advance and extraction before using a new font or upgrading Forme. Replace this shim with native first-line indentation when the engine supports it and those checks pass.

package/docs/SELECTION.md

@@ -0,0 +1,59 @@
+# Selection and quick corrections
+
+OpenDoc uses stable component selection for text editing and feedback. A fixed-width bottom bar offers Edit and Comment for the selection; both use the same panel above it. Saved comments have their own bottom-right dock. Hover outlines identify components before clicking. Text selection and copying stay inside the editor; the PDF itself supports component selection, links, navigation, and reading.
+
+## Correcting text
+
+Click a component to select it without opening a panel. Choose the Edit icon to edit its full text value, or the Comment icon to write feedback. The bar keeps the same dimensions when either panel opens or closes. Valid changes enter a browser draft and update a separately rendered PDF preview. Moving to another component, clicking outside, **Done**, Cmd/Ctrl+Enter, and Escape keep those changes without writing source. A change that crosses source values or generated content must be corrected or reset before leaving the editor. Formatting and structural changes remain agent work.
+
+The floating bar keeps the pending count, Undo, Redo, Discard, and Save all together. Consecutive typing in one source value coalesces into history steps; native textarea undo remains available, while Cmd/Ctrl+Z and Shift+Cmd/Ctrl+Z operate on draft history outside text fields. Save all or Cmd/Ctrl+S validates the combined candidate and writes the group. Save errors retain the draft. A successful source save then updates the canonical PDF; only a ready result displays the saved confirmation. Export stays paused while text changes remain unsaved.
+
+Drafts and their bounded history survive document navigation and reloads in the same browser tab. If source changes elsewhere, Refresh draft carries forward only edits whose original values and identities still match. Conflicts keep the draft for review. Storage failures retain the in-memory draft and warn before a reload can lose it. The latest saved group has one guarded, server-session-local Undo; later source changes invalidate it instead of overwriting newer work.
+
+Open editors remember the source version they came from. Untouched text follows source updates; modified text from an older or unknown version stays available for review without silently becoming a new draft change.
+
+A correction replaces text within one proven writable source value and preserves surrounding structure and formatting. Shared local constants update every occurrence, and the draft count counts that shared value once. Mixed formatting stays intact: individual changes must stay inside one existing source value. Imported, computed, and unsupported expressions are available for feedback rather than guessed from their displayed wording.
+
+The renderer issues writable targets. Requests do not choose arbitrary files or source spans. The server checks the baseline document revision, PDF hash, source digests, and source ownership; validates all candidate files; and renders a real draft PDF through isolated source overrides. Previewing never changes document source or canonical artifacts. Save stages the validated replacements and uses guarded rollback on a write failure, preserving intervening external changes. These safeguards do not imply a filesystem-wide atomic rename across independent files.
+
+## Binding reusable content
+
+Native OpenDoc blocks provide content slots. Shared components can declare a caller-owned prop with the transparent `TextSlot` helper:
+
+```tsx
+import { Paragraph, TextSlot } from 'opendoc';
+
+export function Byline({ author }: { author: string }) {
+  return <Paragraph id="byline">
+    <TextSlot slot="author" from="author">{author}</TextSlot>
+  </Paragraph>;
+}
+```
+
+For a validated data template, bind a string in the instance's `provenance.dataFile`:
+
+```tsx
+<TextSlot slot="client-name" field={['client', 'name']}>
+  {data.client.name}
+</TextSlot>
+
+{data.terms.map(term => <Paragraph id={`term-${term.id}`} key={term.id}>
+  <TextSlot slot="text" field={['terms', { id: term.id }, 'text']}>
+    {term.text}
+  </TextSlot>
+</Paragraph>)}
+```
+
+Slots and record IDs must remain stable through edits and reordering. TextSlot adds no PDF node, style, or text. Bind the original string, not a formatted or computed representation. Data corrections run the existing template parser before saving; import `bindTemplate` from `opendoc/template` for template instances, or `validateTemplateInput` from the same module to wrap an existing parser for optional data components.
+
+DataTable accepts transparent TextSlot content within cells. Supply `rowIds` for stable row identities when data can reorder. Cell values without a proven binding remain readable and commentable. Never bind a calculated total to an unrelated raw field merely to enable editing.
+
+## Comments and agent context
+
+Select any component and choose the Comment icon in the bottom bar to leave feedback. Switching between Edit and Comment keeps their drafts; an unfinished component comment also survives text-preview updates. Submitting closes the composer and leaves a marker. The bottom-right button opens all document comments; markers open comments for a component. Pencil and trash icons edit or delete feedback, and a comment row navigates to its selected component. Clicking outside closes the dock. Edits and deletion check versions; deleted feedback retains its history. Comments persist independently and are anchored against the saved document, even while a text draft is being previewed. New text comments attach to the whole text component; earlier phrase comments retain their anchors.
+
+Phrase feedback records the stable block and text slot, original quote, and nearby text. Reflow changes geometry rather than identity. Wording changes relocate a quote only when it remains unambiguous in that same target; otherwise the original feedback stays visible with a changed-text indication. Anonymous multi-field compositions and duplicate slots retain the selected quote as block-level feedback, because their positional identities cannot safely follow reordering. Give reusable fields unique TextSlot names for durable phrase feedback. Existing whole-block comments keep working, and editing never resolves feedback automatically.
+
+Read `.opendoc/current.json` immediately before working from a selection. `selection` contains its exact quote and logical range; `selectionCurrent` says whether it matches the current ready revision. `selectedText` identifies its slot and writable source when known. `manualEdit` reports editing activity, the pending edit count, whether a draft is being previewed, the latest saved group, and render status without exposing draft text. Pending comments include `anchorStatus` and their currently resolved selection when available.
+
+Treat this as observed context. The user's request authorizes the work. Preserve local corrections, source identities, reference records, and comment history. If the current source has moved on, resolve the intended target before changing it. Do not infer that an agent is running merely because the app is connected.