@uniweb/unipress 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+## 0.2.0
+
+The credibility-shifting release. Two production-shaped foundations
+(`@uniweb/book`, `@uniweb/data`), five templates (`book`, `monograph`,
+`report`, `data-report`, `directory`), and a vocabulary cleanup that
+separates create-time templates from runtime foundations.
+
+### Added
+
+- **`@uniweb/book`** foundation. Long-form prose with chapters; outputs
+  Typst/PDF, Paged.js HTML, EPUB. Default section type `Chapter` plus
+  `Cover`, `BackCover`, `BackMatter`, `Contents`. Inlines parameterised
+  Typst defaults (trim, typography, structure, localized labels) and a
+  CSS Paged Media stylesheet.
+- **`@uniweb/data`** foundation. Aggregates structured records and
+  emits Excel workbooks + Word reports. Eight section types
+  (`Cover`, `Members`, `Publications*` ×4, `Funding`, `Supervisions`)
+  with Loom-driven aggregate stats and a queryable filter surface.
+- **Five templates** under `documents/`:
+  - `book` — trade-6x9 prose (3 chapters).
+  - `monograph` — royal-octavo, EB Garamond, `tocDepth: 3`.
+  - `report` — trade-7x10, block paragraphs, code-margin relief.
+  - `data-report` — migrated from the v0.1 `academic-metrics`
+    placeholder; aggregate metrics across sample naturalists.
+  - `directory` — flat records listing with filterable surface.
+- **Per-template docs** at `docs/templates/<name>.md` covering the
+  `document.yml` fields that matter, common customizations, and
+  links to the foundation README.
+- **Registry-ref resolver** in `foundation-loader.js`. The fifth ref
+  form `@<namespace>/<name>@<version>` constructs a URL from
+  `UNIWEB_REGISTRY_URL` (or the production default at
+  `site-router.uniweb-edge.workers.dev`) and fetches via the existing
+  cache. Catalog entries pin registry refs; scaffolded `document.yml`
+  files inherit them.
+
+### Changed
+
+- **Vocabulary**: `unipress create` now takes `--template <id>`
+  instead of `--foundation <id>`, and `list-foundations` is renamed
+  to `list-templates`. Catalog ids are templates — starter content
+  pinning a foundation. Runtime concepts keep the foundation name
+  (`compile --foundation`, `document.yml`'s `foundation:`).
+- **Catalog entry shape**: `{ source: { url } }` →
+  `{ foundation: { ref, source: { url } } }`. The new `foundation.ref`
+  is the registry ref scaffolded `document.yml` files pin; the
+  `foundation.source.url` is the human-readable "where this lives"
+  pointer shown in `list-templates` output.
+- **Repo layout**: `framework/unipress/` is now a nested pnpm
+  workspace. Foundations developed for unipress live under
+  `foundations/<name>/`; documents (foundation-dev test harnesses
+  AND bundled template starter content) live under `documents/<name>/`.
+  The `scripts/generate-templates-data.js` generator reads from
+  `documents/` and rewrites path-ref `foundation:` values to registry
+  refs at bundle time so the on-disk file stays dev-friendly while
+  the bundled file is end-user-friendly.
+
+### Removed
+
+- `--foundation` flag on `create`. Errors with a pointer to
+  `--template` (no deprecation alias — pre-1.0).
+- `list-foundations` command. Errors with a pointer to `list-templates`.
+- `templates/` directory; `package.json`'s `files:` array now ships
+  `documents/`.
+
+### Caveat
+
+Catalog entries currently point at the **local registry**
+(`http://localhost:4001/registry/packages/<ns>/<name>/<ver>/foundation.js`).
+Scaffolded documents will fail to fetch the foundation unless the
+foundations are published locally via `uniweb publish --local` against
+a running unicloud, OR the user passes `--foundation <path>` explicitly.
+A follow-up release switches the catalog URLs to the production
+registry once `@uniweb/book` and `@uniweb/data` publish there.
+
+## 0.1.0 (unreleased)
+
+First working release, published as `@uniweb/unipress` after the
+unscoped `unipress` name was abandoned (npm Levenshtein-policy
+conflict with `unirest`). The CLI binary is still `unipress`; only the
+package specifier is scoped. All functionality below is in the working
+tree and exercised end-to-end against the v0.1 reference foundation
+(198-page PDF via Typst 0.14.2).
+
+### Added
+
+- `unipress compile <dir>` — compile a content directory into a
+  document. Calls `foundation.compileDocument(website, { format,
+  foundation, ...hostHints })` and sinks the resulting Blob.
+- Format support: whatever the foundation declares in its `outputs:`
+  map. Today that's PDF / Typst source zip / Paged.js HTML / EPUB via
+  `@proximify/press-book`; other formats land when their foundations do.
+- Typst binary manager: pinned to `0.14.2`, SHA-256-verified, cached
+  under `$UNIPRESS_CACHE_DIR` or the platform default (XDG /
+  `~/Library/Caches/unipress` / `~/.cache/unipress`). Override with
+  `--typst-binary <path>`.
+- `unipress.config.js` + `--config <path>`. Precedence: CLI > config >
+  `document.yml` > defaults. Fields: `format`, `foundation`, `out`,
+  `typst.binary`, `typst.version`. Relative paths resolve against the
+  config file's directory.
+- `unipress inspect <dir>` — JSON dump of the resolved Website graph,
+  with filtering knobs (`--full`, `--summary`, `--page <route>`,
+  `--depth <n>`, `--foundation <ref>`, `--no-orchestrate`).
+- Foundation resolver: npm package name (walks `node_modules/`, picks
+  `exports['./dist']`) or local path. URL-based resolution is planned.
+- Named error catalog (`ContentDirectoryError`, `DocumentYmlError`,
+  `ConfigValidationError`, `FoundationResolutionError`, `CompileError`,
+  `OutputWriteError`, `TypstBinaryError`, plus three reserved for
+  later milestones). `UnipressError.format()` produces structured
+  multi-line output. Top-level handler splits exit codes: `1` for
+  user-addressable errors, `2` for internal bugs.
+- `--verbose` flag — step-by-step progress to stderr + stack traces on
+  errors.
+- `--keep-temp` flag — preserves the typst temp directory on compile
+  failure so the generated source bundle can be inspected.
+
+### Framework-side changes that shipped alongside
+
+- [`@uniweb/press`] `compileDocument(websiteOrTree, options)` — the
+  high-level compile entry point. Tree mode passes through to
+  `compileSubtree`; website mode reads `foundation.outputs[format]`,
+  assembles adapter options, gathers blocks, dispatches.
+- [`@uniweb/build`] Host-shareable re-export extended — the generated
+  entry now re-exports both `compileSubtree` and `compileDocument`
+  when the foundation depends on `@uniweb/press`.
+- [docs] New "Document Outputs" section in `foundation-config.md`
+  covering the `outputs: { <format>: { getOptions, via?, extension? } }`
+  contract.
+
+(0.1.0 was never tagged; its content shipped under the 0.0.1 working
+tree and was superseded by 0.2.0 directly.)
+
+## 0.0.1
+
+- Name-reservation release. CLI prints help and version; no commands
+  are implemented yet.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,213 @@
+# unipress
+
+**Compile a directory of markdown into a document — typeset PDF, EPUB, Word, Excel, Paged.js HTML, Typst source — using a foundation that knows the conventions of the kind of document you're writing.**
+
+```bash
+unipress create my-book
+unipress compile my-book
+```
+
+Two commands. The first scaffolds a starter project; the second produces the file.
+
+## What it makes
+
+| Format | What it's for |
+|---|---|
+| **PDF** | The finished, typeset document. Real typography, real pagination, ready to print or share. Built on [Typst](https://typst.app), the modern typesetting system. |
+| **EPUB** | The format Kindles and other ebook readers use. |
+| **Word (`.docx`)** | When a journal, committee, or collaborator needs a Word file. |
+| **Excel (`.xlsx`)** | When the document is structured data — a directory, a dataset, a registry — rather than prose. |
+| **Paged.js HTML** | Browser-paginated HTML you can print to PDF or post on the web. |
+| **Typst source** | The `.typ` files unipress feeds the compiler. Useful if you want to take the typesetting further yourself, or hand off to a designer. |
+
+Equations work in the standard LaTeX style — `$E = mc^2$` for inline, `$$...$$` for displayed. Tables, lists, footnotes, code blocks, and images all behave the way you'd expect from markdown.
+
+## Two ways to use it
+
+**For authors.** unipress is a tool. Pick a template, write markdown, compile. The template knows the conventions for its kind of document — typography, structure, the bits that make a book look like a book and a directory look like a directory. You handle the content; the template handles everything else.
+
+**For developers.** unipress is an engine. A *foundation* is a component system that declares what section types exist (`type: Chapter`, `type: Bibliography`), where data comes from (`data:` declarations), and what output formats it can emit (`outputs: { docx, xlsx, pdf, custom-format }`). Authors write markdown against your vocabulary; unipress runs your foundation against their content. Same content directory, multiple outputs your foundation chooses to support — typeset book, accessible EPUB, regulatory report, structured data feed. The same foundation can also drive a [Uniweb](https://uniweb.io) website, so the work is never single-purpose.
+
+Foundations consume [`@uniweb/press`](https://github.com/uniweb/press) for the bytes-emitting work. Press is the output layer (Word, Excel, Typst today; more formats shipping); the foundation is your vocabulary.
+
+## Install
+
+**Standalone binary (recommended for most users).** No Node, no npm. Download the asset for your platform from [the releases page](https://github.com/uniweb/unipress/releases), make it executable, and put it somewhere on your `PATH` — `/usr/local/bin/unipress` is a common choice on macOS and Linux. Then you can run `unipress` from any directory.
+
+**npm.** If you already have Node:
+
+```bash
+npm i -g @uniweb/unipress
+```
+
+## Pick a template
+
+Five built-in templates ship with the binary. Run `unipress list-templates` for the picker.
+
+| Template | Foundation | Outputs | Use case |
+|---|---|---|---|
+| `book` | `@uniweb/book` | pdf, typst, pagedjs, epub | Trade book, long-form prose |
+| `monograph` | `@uniweb/book` | pdf, typst, pagedjs, epub | Scholarly monograph (royal-octavo, classical typography) |
+| `report` | `@uniweb/book` | pdf, typst, pagedjs, epub | Technical report (trade-7x10, block paragraphs) |
+| `data-report` | `@uniweb/data` | xlsx, docx | Aggregate metrics across structured records |
+| `directory` | `@uniweb/data` | xlsx, docx | Flat records listing with a filterable surface |
+
+Per-template guides: [`docs/templates/`](./docs/templates/).
+
+More templates land as more foundations ship — `cv`, `resume`, `paper`, `thesis` are on the roadmap for upcoming releases.
+
+## Write your first document
+
+```bash
+unipress create my-book --template book --title "My Book" --author "Your Name"
+cd my-book
+```
+
+The result is a content-only directory — markdown pages, a `document.yml`, optional `theme.yml` and `assets/`. **No `package.json`, no `node_modules`.** Edit the markdown — that's your content. Numbered filenames (`01-intro.md`, `02-chapter-one.md`) keep chapter order predictable.
+
+When you're ready to produce the document:
+
+```bash
+unipress compile . --format pdf
+```
+
+Or any of the formats the foundation declares (`--format epub`, `--format pagedjs`). Write, compile, look at the result, revise, compile again — that's the loop.
+
+The first PDF run downloads Typst 0.14.2 to `~/Library/Caches/unipress/typst/0.14.2/` (or the XDG cache dir on Linux). Subsequent runs reuse the cached binary.
+
+## Custom foundations
+
+Any foundation that declares an `outputs: { … }` map on its default export can drive unipress. Point `document.yml`'s `foundation:` at:
+
+- a registry ref: `@<namespace>/<name>@<version>` — fetched from the Uniweb registry, cached locally,
+- a URL: `https://…/foundation.js`,
+- a local filesystem path: `./foundation`, `/abs/path`, etc.
+
+The local-path form is the everyday dev loop — point unipress at a foundation directory you're iterating on, no publish step needed:
+
+```bash
+unipress compile my-doc --foundation ../my-foundation
+```
+
+For the foundation contract — the `outputs:` map, the `getOptions(website, hostHints)` function, what bytes a foundation can emit — see the [foundation authors' guide](https://github.com/uniweb/docs/blob/main/reference/foundation-config.md#document-outputs). Foundations are distributed via the [Uniweb registry](https://uniweb.io), not npm.
+
+---
+
+Below this point is reference material — useful when you want to do something beyond the basics, or when something doesn't behave as expected.
+
+## CLI reference
+
+```text
+unipress compile <dir> [options]
+  --format <fmt>      Output format (pdf | typst | docx | xlsx | pagedjs | epub).
+                      Overrides the format: field in document.yml.
+  --foundation <ref>  Override document.yml's foundation. Accepts:
+                        - registry ref:  @<namespace>/<name>@<version>
+                        - URL:           https://…/foundation.js
+                        - path:          ./foundation, /abs/path, …
+  --out <path>        Output file (default: ./<dir-basename>.<ext>).
+  --config <path>     Explicit config file (default: <dir>/unipress.config.js).
+  --typst-binary <p>  Path to a typst binary (skips the managed download).
+  --keep-temp         On typst-compile failure, keep the temp dir for inspection.
+  --verbose           Per-step progress to stderr + stack traces on errors.
+
+unipress create <dir> [options]
+  --template <id>     Template to scaffold (interactive picker if omitted).
+                      Run `unipress list-templates` to see available ids.
+  --title <str>       Document title (prompts if omitted).
+  --author <str>      Document author (prompts if omitted).
+  --force             Overwrite non-empty <dir>.
+  --yes               Skip prompts (requires --template).
+
+unipress list-templates
+  List the templates available, one per line, with description, outputs,
+  the foundation each pins, and the source URL where the foundation lives.
+
+unipress inspect <dir> [options]
+  Dump the parsed content as JSON (debugging aid).
+  --full              Include web-only fields (assets, icons, etc.).
+  --summary           Replace pages[] with route strings only.
+  --page <route>      Keep only the page matching <route>.
+  --depth <n>         Truncate nested values beyond depth n.
+  --foundation <ref>  Override document.yml's foundation.
+  --no-orchestrate    Skip running the foundation; show only the parsed content.
+
+unipress --help
+unipress --version
+```
+
+Exit codes: `0` success, `1` user-addressable error, `2` internal error (re-run with `--verbose` for a stack trace).
+
+## Configuration
+
+### `document.yml`
+
+The content-directory-level config. Fields unipress reads:
+
+| Field | Purpose |
+|---|---|
+| `name` | Document name (used as a title fallback). |
+| `foundation` | Registry ref (`@ns/name@ver`), URL, or local path to the foundation. |
+| `format` | Default output format. Overridable by CLI `--format` or `unipress.config.js`. |
+| `pages:` | Reading order (same semantics as a Uniweb site's `site.yml`). |
+| `book:`, `report:`, `collections:` … | Foundation-specific config blocks. The foundation's `getOptions` reads these. |
+
+`site.yml` is also accepted as a fallback for compatibility with existing Uniweb site directories.
+
+### `unipress.config.js`
+
+Optional ESM file for things awkward in YAML — imports, computed values, format-specific overrides. Auto-discovered at `<dir>/unipress.config.js` or explicit via `--config <path>`.
+
+```js
+import { defineUnipressConfig } from '@uniweb/unipress'
+
+export default defineUnipressConfig({
+  out: './dist/my-book.pdf',           // overrides --out default
+  format: 'pdf',                        // overrides document.yml format
+
+  typst: {
+    version: '0.14.2',                  // override the pinned Typst version
+    binary: '/usr/local/bin/typst',     // skip the managed download
+  },
+})
+```
+
+Plain `export default { … }` works equally well; `defineUnipressConfig` is an identity wrapper for editor autocomplete.
+
+Relative paths in the config (`out`, `foundation`, `typst.binary`) resolve against the **config file's directory** — matching Vite / Astro convention.
+
+### Precedence chain
+
+```
+CLI flags > unipress.config.js > document.yml > defaults
+```
+
+Applied per-field.
+
+## Typst binary
+
+`--format pdf` requires a Typst binary. unipress pins `0.14.2` and manages the download:
+
+- **Cache location:** `$UNIPRESS_CACHE_DIR` > `$XDG_CACHE_HOME/unipress` > `~/Library/Caches/unipress` (macOS) > `~/.cache/unipress` (fallback). Binary path: `<cache>/typst/<version>/typst`.
+- **Override:** pass `--typst-binary <path>` or set `typst.binary` in `unipress.config.js`.
+- **Checksum verified:** each download is SHA-256-checked against the digest pinned in `src/typst/versions.js`.
+
+## Where things stand
+
+unipress is **pre-1.0**. The CLI is stable enough to write real documents with — the `book` template, in particular, is well-tested. Future versions may change small things, but `document.yml` files and project folders from today should keep working: scaffolded projects pin a specific foundation version, and registry artifacts are immutable.
+
+**Heads-up for v0.2:** the bundled catalog points at a local registry (`http://localhost:4001/...`) until the foundations publish to the production Uniweb registry. To compile against a bundled template today, either pass `--foundation <path>` pointing at a built foundation directory, or run a local foundation registry (publish a built foundation with `uniweb publish --local` and serve `.unicloud/registry/` on port 4001). A follow-up release switches the catalog to production URLs once `@uniweb/book` and `@uniweb/data` ship there.
+
+## Troubleshooting
+
+See [`docs/troubleshooting.md`](./docs/troubleshooting.md) for common errors and fixes — every named error class maps to a cause and a concrete next step.
+
+## See also
+
+- [`@uniweb/press`](https://github.com/uniweb/press) — the output layer foundations consume to produce Word/Excel/Typst/EPUB. Foundation authors interact with it directly.
+- [`@uniweb/build`](https://github.com/uniweb/build) — the framework's content-collection pipeline. unipress consumes the sharp-free `/content` entry.
+- [Uniweb](https://uniweb.io) — the larger framework. Foundations originate here; unipress brings them to the command line.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/RELEASING.md

@@ -0,0 +1,101 @@
+# Releasing unipress
+
+Notes for cutting a release tag (`unipress@<version>`). The release workflow at `.github/workflows/release.yml` watches for tag pushes matching that pattern, builds three binaries (darwin-arm64, linux-x64, windows-x64), and creates a GitHub Release with the binaries and SHA-256 sidecars attached.
+
+This file mostly exists to flag one thing the release workflow currently can't handle on its own.
+
+---
+
+## The CI install tension
+
+unipress's runtime depends on five `@uniweb/*` framework packages (`@uniweb/build`, `@uniweb/content-reader`, `@uniweb/core`, `@uniweb/runtime`, `@uniweb/semantic-parser`). The CLI is developed inside a larger monorepo where these are sibling packages and resolve via `workspace:*`. That works for local dev — pnpm symlinks the local sources directly — but the release workflow checks out only this repo, with no monorepo around it.
+
+Two strategies have been tried, and each has a failure mode:
+
+- **`^X.Y.Z` (npm version specs).** Lets CI install standalone from npm. Failure mode: when framework changes ship in unpublished workspace versions, dev machines pnpm-resolve to the npm-published copy instead of the local sibling — meaning `pnpm install` from inside the monorepo silently picks up an older framework. This bit us once; the developer-side breakage is silent and hard to spot.
+
+- **`workspace:*` (current).** Dev machines always get the local siblings. Failure mode: CI's `pnpm install --ignore-workspace --no-frozen-lockfile` has no way to resolve `workspace:*` outside a workspace — it will error.
+
+Both strategies are correct for one audience and broken for the other. The current state is `workspace:*`, which means **the next release tag will fail at the CI install step until one of the two fixes below lands.**
+
+## Two ways out
+
+### (a) Publish all `@uniweb/*` framework packages to npm at the release version, then flip the specs back to npm ranges at release time
+
+The `pnpm framework:publish:*` shortcuts in the outer monorepo handle the framework publish. Workflow:
+
+1. From the outer monorepo, bump + publish all framework packages: `pnpm framework:publish:patch` (or `:minor`).
+2. Wait for the publish to settle on npm.
+3. In the unipress repo, change the five `@uniweb/*` deps in `package.json` from `workspace:*` back to `^<published-version>` matching what just shipped.
+4. Commit, tag `unipress@<version>`, push.
+5. After the release CI succeeds and the binary is out, switch the deps back to `workspace:*` so dev resolution stays correct.
+
+Pros: keeps the CI workflow simple — `pnpm install --ignore-workspace --no-frozen-lockfile` continues to work standalone. The release artifact is reproducible from npm with no monorepo context.
+
+Cons: requires a framework publish before every unipress release. Adds a step. The flip-back-to-`workspace:*` after release is easy to forget; if you skip it, the next dev `pnpm install` quietly downgrades the framework deps to the npm-published versions. Worth automating the flip with a script if this becomes the standard path.
+
+### (b) Build the unipress binary inside the outer monorepo's CI
+
+Add a release workflow at the **outer monorepo** that:
+
+1. Watches for tag pushes matching `unipress@*`.
+2. Checks out the outer monorepo (which has the workspace + all `@uniweb/*` siblings cloned via `pnpm clone`).
+3. Runs `pnpm install` at the outer root (resolves `workspace:*` correctly).
+4. Runs `node scripts/build-binaries.js` from inside `framework/unipress/`.
+5. Uploads the resulting binaries to a GitHub Release in the **unipress** repo (cross-repo release via `gh release` with a PAT).
+
+Pros: matches the dev environment exactly — workspace:* always resolves the same way locally and in CI. No extra publish step. No flip-back dance.
+
+Cons: more workflow complexity. Cross-repo release upload requires a PAT (the workflow's default `GITHUB_TOKEN` is scoped to its own repo). The outer monorepo is private, so the workflow runs there and can't be inspected by anyone outside the org — fine for our purposes but worth noting if unipress ever gets external contributors who want to understand how releases are produced.
+
+## Recommendation
+
+**Go with (a) for v0.x releases. Move to (b) once unipress's release cadence outpaces the framework's**, or once the outer monorepo's CI matures enough that adding a cross-repo build step is cheap.
+
+Why (a) first:
+
+- The framework already publishes to npm on its own cadence. Tagging unipress *after* a framework publish settles is a normal sequencing — every framework feature unipress depends on is on npm anyway by the time a release ships.
+- The flip-back-to-`workspace:*` step is the only friction, and it's a one-line change. Easy to script.
+- (b) is strictly more invasive and ties the unipress release pipeline to the outer monorepo's existence — a coupling worth deferring.
+
+When (b) starts to make sense:
+
+- If unipress needs to release patches against unpublished framework changes (rare, but possible).
+- If the framework publish cadence becomes the bottleneck on shipping unipress fixes.
+- If cross-repo release infrastructure is already in place for other reasons (e.g., other tools in `framework/` shipping binaries).
+
+## Concrete checklist for the next release
+
+Until (b) lands, every release goes through this:
+
+```bash
+# 1. From the outer monorepo: bump + publish framework
+pnpm framework:publish:patch    # or :minor
+
+# 2. Note the new versions: check `framework/<pkg>/package.json` for each.
+
+# 3. In framework/unipress/, edit package.json:
+#    - "@uniweb/build": "workspace:*"      → "^<new-version>"
+#    - (repeat for content-reader, core, runtime, semantic-parser)
+
+# 4. Bump unipress version + update CHANGELOG (this file's git history
+#    should make the pattern obvious).
+
+# 5. Commit + tag + push:
+git add package.json CHANGELOG.md
+git commit -m "release: <version>"
+git tag -a unipress@<version> -m "..."
+git push origin main
+git push origin unipress@<version>
+
+# 6. Wait for the release workflow. Confirm artifacts uploaded.
+#    The release is created as a draft — review and publish it via
+#    `gh release edit unipress@<version> --draft=false`.
+
+# 7. Flip framework deps back to workspace:* so dev resolution stays
+#    correct against unpublished framework changes:
+git revert <step-3-commit>     # or hand-edit + commit
+git push origin main
+```
+
+Step 7 is the easy-to-forget one. If a dev pulls and runs `pnpm install` while the package.json still has the npm specs from step 3, they'll silently get the npm-published framework copies — which means any unpublished framework features won't be available locally. Don't skip step 7.