@quillmark/quiver 0.16.0 → 0.18.1

package/LICENSE

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

@@ -0,0 +1,2 @@
+Quillmark
+Copyright 2026 Nibs

package/README.md

@@ -8,319 +8,158 @@ Load and build collections of quills for rendering with `@quillmark/wasm`.
 npm install @quillmark/quiver @quillmark/wasm
 ```
 
-## Distribution model
+## Loading a quiver
 
-A Quiver has one authored shape: the **source layout** (`Quiver.yaml` at the
-package root, quills under `quills/<name>/<x.y.z>/`). Authors publish it as
-an npm package. Consumers decide how to consume it:
+A quiver has one authored shape, the **source layout** (`Quiver.yaml` at the package root, quills under `quills/<name>/<x.y.z>/`), published as an npm package. Browsers cannot read that layout, so `build(src, out)` packs it at deploy time and the output is served as static assets. Each loader names exactly what it reads; there is no auto-detection.
 
-- **Node consumers** load the source layout directly with `Quiver.fromPackage`,
-  or load a packed (build-output) artifact from disk with
-  `Quiver.fromBuiltDir`.
-- **Browser consumers** run `Quiver.build(...)` as a build step and serve the
-  output as static assets, loading it with `Quiver.fromBuiltUrl`.
+| Loader                     | Reads                   | Import                   |
+| -------------------------- | ----------------------- | ------------------------ |
+| `fromDir(path)`            | the source layout       | `@quillmark/quiver/node` |
+| `fromBuiltDir(path)`       | build output, off disk  | `@quillmark/quiver/node` |
+| `Quiver.fromBuiltUrl(url)` | build output, over HTTP | `@quillmark/quiver`      |
 
-Each loader names exactly what it loads. Source: `fromPackage(specifier)`,
-`fromDir(path)`. Build output: `fromBuiltUrl(url)` (HTTP/HTTPS, browser-safe),
-`fromBuiltDir(path)` (filesystem, Node-only). No auto-detection, no branching
-on artifact shape.
-
-This keeps the author flow to a single command (`npm publish` or `git tag`)
-and puts the deployment-topology decision where it belongs: with the
-consumer.
-
-## The render model
-
-`@quillmark/quiver` produces quills; `@quillmark/wasm` renders them.
-
-- `quiver.getQuill(ref)` returns a core `Quill` — engine-free, portable data,
-  good for schema inspection, validation, blueprint access, and seeding. It is
-  the **only** way to obtain a quill from a quiver.
-- `const engine = new Engine()` (from the `@quillmark/wasm` root) renders it:
-  `await engine.render(quill, doc, opts?)`. The Engine routes on
-  `quill.backendId`, lazily loads that backend, clones the quill and document
-  into the backend's WASM memory, renders, and frees the clones — so a core
-  `Quill` passes straight to `engine.render` with no boundary-crossing step.
-
-`Engine.render`, `open`, `supportedFormats`, and `supportsCanvas` are all
-**async** — always `await` them. The canonical `Quill`/`Document`/`Engine`
-types are not re-exported from `@quillmark/quiver`; import them straight from
-the `@quillmark/wasm` peer dependency, which is the single source of truth.
-
-## Authoring a quiver
-
-Lay out the source per the spec, then publish to npm (or push a git tag):
-
-```
-my-quiver/
-  Quiver.yaml
-  quills/
-    <name>/<x.y.z>/
-      Quill.yaml
-      ...
-  package.json
-```
-
-Recommended CI: use the bundled `@quillmark/quiver/testing` harness — it
-loads with `Quiver.fromDir`, compiles every quill, and renders each quill's
-example document so validation errors surface on publish, not on the
-consumer's build. The harness uses `node:test` (built into Node 18+); no extra
-test-runner dependency required. If you prefer vitest/jest/mocha, write a
-12-line loop against the main API instead.
-
-```ts
-// quiver.test.ts — run with: node --test
-import { Engine } from "@quillmark/wasm";
-import { runQuiverTests } from "@quillmark/quiver/testing";
-
-runQuiverTests(import.meta.url, new Engine());
-```
-
-## Manual validation (rendering samples)
-
-The CI harness proves every quill _compiles_; it does not produce output a
-human can look at. To eyeball real renders, run the
-`@quillmark/quiver/preview` helper:
-
-```ts
-// scripts/preview.ts — run with: node --experimental-strip-types scripts/preview.ts
-import { Engine } from "@quillmark/wasm";
-import { renderQuiverSamples } from "@quillmark/quiver/preview";
-
-await renderQuiverSamples(import.meta.url, {
-  engine: new Engine(),
-});
-// → writes ./preview/<name>@<version>.<fmt> + index.html
-```
-
-It renders every quill's illustrative example document (seeded via
-`quill.seedDocument()` — a fully filled-out, always-renderable sample; the
-blueprint itself carries `<must-fill>` sentinels and is not directly
-renderable), writes the artifacts
-to `outDir` (default `preview/`), and emits an `index.html`
-gallery. A `.gitignore` is written into `outDir` so the generated artifacts
-are never accidentally committed. A quill that throws is recorded as failed —
-with every diagnostic, not just the first — without aborting the run, so one
-broken quill never hides the rest.
-
-To iterate on a subset, pass `include` / `exclude` (each entry matches a
-quill name or canonical ref):
-
-```ts
-await renderQuiverSamples(import.meta.url, {
-  engine: new Engine(),
-  exclude: ["broken-quill"], // or: include: ["memo@1.0.0"]
-});
-```
-
-> **Linking the source repo?** `@quillmark/quiver/preview` resolves to
-> `./dist/preview.js`, which only exists after `npm install && npm run build`
-> in the `@quillmark/quiver` checkout. If you `npm link` it and see
-> `Cannot find module './dist/preview.js'`, build the linked package first.
+The filesystem factories are free functions from `/node`; the one that reaches across HTTP is a static on `Quiver`. Importing `/node` adds nothing to the class, so a bundler drops the verbs you do not call.
 
 ## Consuming a quiver (Node)
 
+A quiver installed from npm is a directory like any other. Resolve its root from your own module: your dependencies are reachable from your module, not from this package's install location.
+
 ```ts
-import { Engine, Document } from "@quillmark/wasm";
-import { Quiver } from "@quillmark/quiver/node";
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { Engine, Document } from '@quillmark/wasm';
+import { fromDir } from '@quillmark/quiver/node';
 
-const quiver = await Quiver.fromPackage("@org/my-quiver");
+const root = dirname(createRequire(import.meta.url).resolve('@org/my-quiver/Quiver.yaml'));
+const quiver = await fromDir(root);
 const engine = new Engine();
 
 const doc = Document.fromMarkdown(markdownString);
 const quill = await quiver.getQuill(doc.quillRef);
-const result = await engine.render(quill, doc, { format: "pdf" });
+const result = await engine.render(quill, doc, { format: 'pdf' });
 ```
 
-`getQuill` accepts both selector refs (`"memo"`, `"memo@1"`) and canonical
-refs (`"memo@1.0.0"`). It resolves the selector, materializes the quill via
-`Quill.fromTree(tree)` (engine-free), and caches one instance per canonical
-ref for the lifetime of the `Quiver`. Concurrent calls for the same ref
-coalesce into a single load.
+`getQuill(ref)` is the only way to obtain a quill from a quiver, and the only entry point most consumers need. It accepts selector refs (`"memo"`, `"memo@1"`) and canonical ones (`"memo@1.0.0"`), resolves the selector, materializes the quill via `Quill.fromTree`, and caches one instance per canonical ref for the quiver's lifetime; concurrent calls for the same ref coalesce into a single load.
 
-The returned quill lives in the core build's WASM memory and is suitable for
-schema inspection, validation, blueprint access, and seeding. To render it,
-hand it straight to `engine.render(quill, doc)` — the Engine clones both
-handles into the backend on demand, so no separate boundary-crossing step is
-needed:
+That quill is **borrowed, not owned**: every caller asking for that ref gets the same instance, so `free()` on it hands the next caller a freed handle. Code that owns its quill mints one from `(await quiver.getQuill(ref)).toTree()` and frees that.
 
-```ts
-// Editor path — core only, ~0.66 MB gzip
-const coreQuill = await quiver.getQuill(ref);
-coreQuill.schema; // ✓ schema, validate, blueprint, seed — all fine
-const doc = coreQuill.seedDocument(); // a fully-filled example document
-
-// Render path — the same core handles render directly.
-const result = await engine.render(coreQuill, doc, { format: "pdf" });
-```
+This package produces quills; `@quillmark/wasm` renders them. A quill from `getQuill` is engine-free portable data — schema inspection, validation, blueprint access, `seedDocument()` — and passes straight to `engine.render(quill, doc)`, which routes on `quill.backendId`, loads that backend, clones both handles into its memory, renders, and frees the clones. There is no boundary-crossing step to perform. `Engine.render`, `open`, `supportedFormats` and `supportsCanvas` are **async**. The canonical `Quill` / `Document` / `Engine` types are not re-exported here; import them from the `@quillmark/wasm` peer, their single source of truth.
 
-If you only need the canonical ref (without materializing), use `resolve`:
+One narrower verb sits beside `getQuill`: `resolve(ref)` returns the canonical ref without materializing anything, and is **sync** (the catalog is in memory from the moment the quiver is built).
 
 ```ts
-const canonicalRef = await quiver.resolve("memo"); // "memo@1.1.0"
+const canonicalRef = quiver.resolve('memo'); // "memo@1.1.0"
 ```
 
-If you need the raw file tree (e.g. to drive a backend binary directly), call
-`(await quiver.getQuill(ref)).toTree()` on the core `Quill` — it is I/O-free
-once the quill is materialized.
-
 ## Consuming a quiver (browser)
 
-Browsers cannot read the source layout directly, so build at deploy time and
-serve the output as static files:
+Build at deploy time, serve the output as static files:
 
 ```ts
 // build script (Node) — typically wired into your existing build pipeline
-import { Quiver } from "@quillmark/quiver/node";
+import { build } from '@quillmark/quiver/node';
 
-await Quiver.build(
-  "./node_modules/@org/my-quiver",
-  "./public/quivers/my-quiver",
-);
+await build('./node_modules/@org/my-quiver', './public/quivers/my-quiver');
 ```
 
+`build` clears its output directory before writing, so it owns that path outright. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
+
 ```ts
 // browser runtime
-import { Engine, Document } from "@quillmark/wasm";
-import { Quiver } from "@quillmark/quiver";
+import { Engine, Document } from '@quillmark/wasm';
+import { Quiver } from '@quillmark/quiver';
 
-const quiver = await Quiver.fromBuiltUrl("/quivers/my-quiver/");
+const quiver = await Quiver.fromBuiltUrl('/quivers/my-quiver/');
 const engine = new Engine();
 
 const doc = Document.fromMarkdown(markdownString);
 const quill = await quiver.getQuill(doc.quillRef);
-const result = await engine.render(quill, doc, { format: "pdf" });
+const result = await engine.render(quill, doc, { format: 'pdf' });
 ```
 
-## SSR seeding (skip the `latest.json` pointer)
-
-`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json` — a stable-named,
-non-content-addressed pointer to the current manifest — before fetching the
-manifest itself. Because that one filename is stable, a CDN edge or browser
-cache can serve a **stale pointer** after a release and silently pin the
-client to the old catalog, with no error. Per-host cache headers only fix this
-one serving layer at a time.
+A CDN URL works the same way, for consumers who cannot run a Node build step of their own.
 
-If you already hold the manifest bytes at build time — a common case for SSR
-consumers, which read the built artifact during their own build — seed the
-catalog from them directly with `Quiver.fromManifest`. It never requests
-`latest.json`; bundles and fonts are still fetched lazily and
-content-addressed, relative to `baseUrl`, exactly as with `fromBuiltUrl`:
+## Server-side runtime (Node, packed artifact on disk)
 
-```ts
-// Server build step — read the manifest the build wrote.
-// build-output/latest.json → { "manifest": "manifest.<hash>.json" }
-import { readFile } from "node:fs/promises";
-
-const { manifest } = JSON.parse(
-  await readFile("./public/quivers/my-quiver/latest.json", "utf8"),
-);
-const manifestBytes = new Uint8Array(
-  await readFile(`./public/quivers/my-quiver/${manifest}`),
-);
-// Inline manifestBytes into the page payload (e.g. base64) for the client.
-```
+Where the packed artifact ships in the deployment image, `fromBuiltDir` reads it from disk, avoiding the self-fetch round-trip `fromBuiltUrl` would force on a self-hosted deployment and letting the source quiver stay a `devDependency`:
 
 ```ts
-// Browser / SSR runtime — seed from the bytes you shipped, no pointer fetch.
-import { Engine, Document } from "@quillmark/wasm";
-import { Quiver } from "@quillmark/quiver";
+import { fromBuiltDir } from '@quillmark/quiver/node';
 
-const quiver = await Quiver.fromManifest("/quivers/my-quiver/", manifestBytes);
-const engine = new Engine();
-
-const doc = Document.fromMarkdown(markdownString);
-const quill = await quiver.getQuill(doc.quillRef);
-const result = await engine.render(quill, doc, { format: "pdf" });
+// Packed at build time, e.g. into ./static/quills/my-quiver
+const quiver = await fromBuiltDir('./static/quills/my-quiver');
 ```
 
-`fromManifest` is browser-safe (no `node:*` imports) and shares
-`fromBuiltUrl`'s error semantics: `quiver_invalid` for malformed manifest
-bytes, `transport_error` for a `file://` `baseUrl` or a later bundle-fetch
-failure.
+## The `latest.json` pointer
 
-## Server-side runtime (Node, packed artifact on disk)
+`Quiver.fromBuiltUrl(url)` first fetches `<url>/latest.json`, a stable-named pointer to the current manifest. Everything behind that pointer is content-addressed and checked against the digest in its name; the pointer itself is not, so a cache layer can serve a stale one and silently pin the client to the old catalog. It is therefore the one request fetched `no-cache` (revalidate with the origin; a 304 still serves from disk), which closes the browser-cache layer. A stale CDN edge is answered by that host's cache headers.
+
+## Error handling
 
-For server-side rendering where the packed artifact ships in the deployment
-image, use `Quiver.fromBuiltDir` to read it from disk. This avoids the
-self-fetch / load-balancer round-trip that `fromBuiltUrl` would force on a
-self-hosted deployment, and lets the source quiver stay in
-`devDependencies`:
+Every error is a `QuiverError` carrying a `code` from a closed set — `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error` — a human-readable `message`, and the offending `ref` where there is one.
 
 ```ts
-import { Quiver } from "@quillmark/quiver/node";
+import { QuiverError } from '@quillmark/quiver';
 
-// Packed at build time, e.g. into ./static/quills/my-quiver
-const quiver = await Quiver.fromBuiltDir("./static/quills/my-quiver");
+try {
+	quiver.resolve('unknown_quill');
+} catch (err) {
+	if (err instanceof QuiverError) console.error(err.code, err.message, err.ref);
+}
 ```
 
-## Advanced: pre-built distribution to a CDN
-
-If you need to ship the runtime artifact directly (e.g. consumers cannot run
-a Node build step), publish `Quiver.build` output to a CDN and have
-consumers point `fromBuiltUrl` at the CDN URL:
+## Authoring a quiver
 
-```ts
-import { Quiver } from "@quillmark/quiver/node";
+Lay out the source per the spec, then publish to npm (or push a git tag):
 
-await Quiver.build("./my-quiver", "./dist/my-quiver");
-// upload ./dist/my-quiver to https://cdn.example.com/quivers/my-quiver/
-const quiver = await Quiver.fromBuiltUrl("https://cdn.example.com/quivers/my-quiver/");
+```
+my-quiver/
+  Quiver.yaml
+  quills/
+    <name>/<x.y.z>/
+      Quill.yaml
+      ...
+  package.json
 ```
 
-## Warm (prefetch all quill trees)
+A consumer reaches an installed quiver by resolving `<specifier>/Quiver.yaml`, which goes through your `exports` map. A package that declares one must expose that subpath, or the quiver is unreachable however correct its layout; a package with no `exports` map needs nothing.
 
-```ts
-await quiver.warm();
+```jsonc
+// package.json
+{
+	"files": ["Quiver.yaml", "quills"],
+	"exports": {
+		"./Quiver.yaml": "./Quiver.yaml"
+	}
+}
 ```
 
-`warm()` is I/O-only: it loads every quill's tree (over the network for
-`fromBuiltUrl`, off the filesystem for `fromPackage` / `fromDir` /
-`fromBuiltDir`) and caches them. It does not require an engine and does
-not materialize Quill instances — that happens lazily on the first
-`getQuill` call, which is microseconds. A subsequent `getQuill` reuses
-the cached tree, skipping the load.
-
-## Error handling
+Gate the quiver in CI so a validation failure surfaces on publish rather than on a consumer's build. `quillmark-quiver test` loads with `fromDir`, compiles every quill, and renders each quill's example document. One door, so what you run locally is what CI runs.
 
-All errors are instances of `QuiverError` with a `code` field.
+The CLI needs no file. Installing the package links `quillmark-quiver` into `node_modules/.bin`, which npm puts on PATH for every script:
 
-```ts
-import { QuiverError } from "@quillmark/quiver";
+```sh
+npm install --save-dev @quillmark/quiver @quillmark/wasm
+```
 
-try {
-  await quiver.resolve("unknown_quill");
-} catch (err) {
-  if (err instanceof QuiverError) {
-    console.error(err.code);    // e.g. "quill_not_found"
-    console.error(err.message); // human-readable description
-    console.error(err.ref);     // offending ref, when available
-  }
+```jsonc
+// package.json
+{
+	"scripts": { "test": "quillmark-quiver test" }
 }
 ```
 
-Error codes: `invalid_ref`, `quill_not_found`, `quiver_invalid`, `transport_error`.
-
-## Using `getQuill` vs calling `Quill.fromTree` directly
+It finds the engine itself: a named `engine` export from `quiver.config.js` at the collection root, else `@quillmark/wasm` from your own `node_modules`. `quillmark-quiver build [--out <dir>]` packs the same source into a servable artifact.
 
-`getQuill(ref)` is the correct entry point for any code that loads a quill
-through a `Quiver`. It handles ref resolution, tree fetching, `Quill.fromTree`
-construction, and per-ref caching in one call. Do **not** reach for
-`Quill.fromTree` directly inside a Quiver consumer:
+On vitest, jest or `node:test`, spawn the bin from a test rather than rebuilding the loop against the main API. The gate stays one implementation, and the case gates what CI gates:
 
 ```ts
-import { Quill } from "@quillmark/wasm";
+// quiver.test.ts
+import { execFileSync } from 'node:child_process';
 
-// wrong — bypasses Quiver's cache; duplicates work getQuill already does
-const tree = new Map<string, Uint8Array>();
-tree.set("Quill.yaml", new TextEncoder().encode("name: memo\n..."));
-// ...assemble the rest of the file tree by hand...
-const quill = Quill.fromTree(tree);
-
-// right
-const quill = await quiver.getQuill(ref);
+it('gates the quiver', () => {
+	execFileSync('quillmark-quiver', ['test'], { stdio: 'inherit' });
+});
 ```
 
-`Quill.fromTree` is for code that builds quills **outside** of a Quiver (e.g.
-a server route that receives a raw file tree over the network, or a test
-fixture that constructs a quill from a hand-rolled in-memory tree).
+It answers _does it work_, and that is the whole of what this package offers a quill author: _what is it like to use_ is answered by working a real document through the quill live, which is an app rather than a subpath.