@legionworks/facet 1.9.0

package/docs/reference/html.md

@@ -0,0 +1,215 @@
+# HTML reference
+
+Static, script-free HTML artifacts. The verifier predicts structural counts
+from the source bytes with a no-egress WHATWG parser, observes the rendered
+DOM through Chromium, and binds the verdict to the revision SHA.
+
+## Publish
+
+```sh
+facet publish --artifact-id <id> --type html --file templates/html-status-report.html
+facet read-back --artifact-id <id> --revision-sha <sha> --tier 1
+```
+
+`--type html` is a first-class type on `publish`; `--renderer` stays chart-only.
+
+## Static, script-free contract
+
+The artifact has no script, no event handler, no `<style>` block, no `style=`
+attribute, and no Facet marker bytes. The frame wraps the parsed body in a
+single element carrying `data-facet-renderer-root` so protocol probes can
+scope their observations — the marker is frame-owned, never artifact-owned.
+
+Source export returns the published bytes byte-for-byte; the wrapper is
+frame-only and never reaches storage or export. `export <artifactId>
+--format source` against an HTML revision produces the exact source the
+operator published.
+
+## Accepted semantic HTML
+
+Every element and attribute an HTML report or dashboard reasonably uses is
+permitted:
+
+- text, headings, lists, tables, sectioning (`<section>`, `<article>`,
+  `<nav>`, `<header>`, `<footer>`, `<main>`, `<aside>`)
+- figures, `<details>`, `<summary>`, `<mark>`, `<time>`, `<abbr>`, `<cite>`,
+  `<q>`, `<dfn>`
+- inline semantics (`<span>`, `<em>`, `<strong>`, `<code>`, `<kbd>`,
+  `<samp>`, `<var>`, `<br>`, `<wbr>`)
+- images (`<img>`), source (`<source>`), anchors (`<a>`)
+- canvases (`<canvas>`)
+
+## Denied elements and attributes
+
+| kind            | refused                                                               |
+| --------------- | --------------------------------------------------------------------- |
+| script-tagged   | `script`, `iframe`, `object`, `embed`, `form`, `link`, `meta`, `base` |
+| styling surface | `style`, `style=` (no CSS-injection surface anywhere)                 |
+| event handlers  | every `on*=` attribute                                                |
+| bad URL schemes | `http:`, protocol-relative (`//host/...`), `javascript:`              |
+
+`cleartext http:`, protocol-relative, and `javascript:` URLs fail closed
+with `html_denied_url_scheme`. Image anchors accept `https:` and `data:`;
+regular anchors accept `https:` and `mailto:`.
+
+## Verdict claim
+
+`ok` on an HTML artifact means: counts agree across the Tier 0 parse5
+prediction and the Tier 1 Chromium observation, every count group is
+exercised, no discriminative error fired, and the layout pass is
+observable. The observable is a structural count vector:
+
+| key                  | what it counts                                                     |
+| -------------------- | ------------------------------------------------------------------ |
+| `rendererRootCount`  | frame-owned `data-facet-renderer-root` wrappers in the document    |
+| `headingCount`       | `<h1>`–`<h6>`                                                      |
+| `tableCount`         | `<table>`                                                          |
+| `listCount`          | `<ul>`, `<ol>`                                                     |
+| `imageCount`         | `<img>`                                                            |
+| `canvasCount`        | `<canvas>`                                                         |
+| `externalImageCount` | `<img>` and `<source>` whose `src` / `srcset` resolves to `https:` |
+
+The marker-anchored structure is the smallest claim that catches blank
+renders, truncated trees, or structure the source never declared — and
+the largest claim that survives legitimate parse5-versus-Chromium
+recovery differences (see [unsupported recovery families](#unsupported-recovery-families)).
+
+## Verdict precedence
+
+Status is decided in exactly one place (`src/validation/tier1/verdict.ts`).
+For HTML specifically:
+
+1. `tampered` — predicted counts disagree with the Tier 1 observation.
+2. `error` — discriminative error fired (`html_denied_element`,
+   `html_denied_attribute`, `html_denied_url_scheme`,
+   `html_encoding_unsupported`, `html_nesting_depth_exceeded`,
+   `html_recovery_unsupported`).
+3. `partial:opaque_content` — a `<canvas>` exists; structure beneath it
+   is unobservable. MUST carry a screenshot or typed `screenshotError`.
+4. `partial:external_resources` — an HTTPS image was referenced; the
+   no-egress verifier never loaded it. MUST carry a screenshot or typed
+   `screenshotError`.
+5. `ok` — counts agree, no discriminative error, no opaque region, no
+   external image.
+
+`partial:` is not a degraded `ok`. The screenshot is mandatory evidence
+so a human or re-verifier can see what the verifier saw.
+
+## HTTPS image and the no-connect rule
+
+The frozen CSP widened from `img-src data:` to `img-src data: https:` to
+let reports link real screenshots without inflating the source cap. The
+no-connect and no-script rules are unchanged:
+
+| directive     | value                       | verdict or display?  |
+| ------------- | --------------------------- | -------------------- |
+| `script-src`  | `'nonce-<BOOTSTRAP_NONCE>'` | verdict              |
+| `connect-src` | `'none'`                    | verdict              |
+| `frame-src`   | `'none'`                    | verdict              |
+| `object-src`  | `'none'`                    | verdict              |
+| `base-uri`    | `'none'`                    | verdict              |
+| `form-action` | `'none'`                    | verdict              |
+| `worker-src`  | `'none'`                    | verdict              |
+| `img-src`     | `data: https:`              | display-time privacy |
+| `font-src`    | `data:`                     | display-time privacy |
+
+The first six protect the VERDICT — a page that can run attacker code
+or open a network socket can forge a verdict or exfiltrate, so they stay
+closed. `img-src` and `font-src` protect PRIVACY at display time only;
+the verifier never follows the URLs, so widening `img-src` to `https:`
+cannot weaken the verdict.
+
+→ [Security reference](security.md) for the full frozen-CSP contract.
+
+## Vendored styling
+
+Styling comes exclusively from the frame's offline-vendored stylesheet.
+Gallery frames map resolved light/dark themes to daisyUI's `winter` and
+`night` themes. The gallery preference defaults to `system` and resolves from
+the user's light/dark preference; Tier 1 deliberately fixes dark/night parity
+for deterministic structural comparison. Artifact-authored HTML still cannot
+supply `<style>` or `style=`; gallery theming does not widen that policy.
+Tailwind utilities come from a deterministic corpus that
+covers the templates, this reference, and common layout, spacing, typography,
+and color classes.
+
+`HTML_TAILWIND_CLASSES` and `HTML_DAISY_COMPONENTS` in
+`src/shared/html/style-vocabulary.ts` are recommendations, not a styling
+ceiling. Use them for predictable artifact output. A valid daisyUI class or
+an included Tailwind utility outside this list can still render.
+
+<!-- VOCABULARY:START -->
+
+### Recommended Tailwind utilities
+
+`block`, `flex`, `grid`, `inline-flex`, `flex-col`, `flex-wrap`, `items-center`, `justify-between`, `justify-center`, `grid-cols-1`, `grid-cols-2`, `grid-cols-3`, `gap-2`, `gap-3`, `gap-4`, `gap-6`, `p-2`, `p-3`, `p-4`, `p-6`, `px-3`, `px-4`, `py-2`, `py-3`, `m-0`, `mt-2`, `mt-4`, `mb-2`, `mb-4`, `w-full`, `max-w-prose`, `max-w-2xl`, `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `font-medium`, `font-semibold`, `font-bold`, `leading-relaxed`, `text-left`, `text-center`, `text-right`, `text-legion-ink`, `text-legion-muted`, `text-legion-cyan`, `bg-legion-paper`, `bg-legion-ink`, `bg-legion-cyan`, `border`, `border-2`, `border-legion-line`, `rounded`, `rounded-box`, `overflow-x-auto`, `table`, `table-zebra`.
+
+59 recommended utilities.
+
+### Recommended daisyUI components
+
+`alert`, `badge`, `btn`, `card`, `stat`, `table`.
+
+6 recommended components · 64 documented recommendations.
+
+<!-- VOCABULARY:END -->
+
+### Unknown classes
+
+No error, no `partial:`, no trust downgrade. A class that is neither a real
+daisyUI class nor present in the Tailwind corpus has no styling effect.
+
+## Pinned styling packages
+
+| package            | version | loaded under `script-src 'nonce-…'`? |
+| ------------------ | ------- | ------------------------------------ |
+| `@tailwindcss/cli` | 4.3.3   | no (build-time only)                 |
+| `tailwindcss`      | 4.x     | no (vendored stylesheet, no runtime) |
+| `daisyui`          | 5.7.16  | no (vendored CSS, no runtime JS)     |
+
+Tailwind is bundled at build time (`bun scripts/build-html-styles.ts`)
+against the deterministic build corpus in `src/shared/html/style-vocabulary.ts`;
+no Tailwind runtime runs in the frame. `daisyui` 5.7.16 ships CSS-var themes
+and components only — the vendored bundle contains zero `<script>` and zero
+`javascript:` URLs. The `img-src` and `font-src` widenings do not load any
+runtime JS because the packages carry none.
+
+## Starter template
+
+A neutral status / report page that uses only the shipped vocabulary:
+
+```sh
+facet publish --artifact-id <id> --type html --file templates/html-status-report.html
+```
+
+→ [`templates/html-status-report.html`](../../templates/html-status-report.html) ·
+[`templates/README.md`](../../templates/README.md) for the starter index.
+
+## Unsupported recovery families
+
+The differential corpus (parse5 prediction vs Chromium observation over real
+documents) discovered three recovery shapes where the WHATWG parser and
+Chromium disagree. Static HTML reports do not need these, so the accepted
+input set shrinks instead of weakening the comparison:
+
+| family                                                                                                                                                                                                                                                                  | rejected as                 |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| UTF-8 encoding ambiguity (`0xFF` mid-stream)                                                                                                                                                                                                                            | `html_encoding_unsupported` |
+| `<select>` containing `<table>` / `<tr>` / `<td>` / `<th>` / `<tbody>` / `<thead>` / `<tfoot>` / `<caption>` / `<colgroup>` / `<col>` (including the two-`<select>` variant where the second `<select>` carries the table markup, and any `<noscript>`-nested instance) | `html_recovery_unsupported` |
+
+A fourth bound — `html_nesting_depth_exceeded` — fires when source nesting
+exceeds the cap in `MAX_HTML_NESTING_DEPTH`. The cap protects Tier 0 and
+Tier 1 from pathological inputs.
+
+These error codes are stable wire values; downstream tooling can match on
+them without parsing message text.
+
+## Tier 0 prediction source
+
+Tier 0 parses the source bytes with `parse5@8.0.1` (`scriptingEnabled:
+false`, matching Chromium's `DOMParser`) inside the existing netns worker.
+No CSS sanitizer, no DOM mutation, no event-loop. The structural counts
+that come out of Tier 0 are bound to the revision SHA and never mutate.
+
+→ [Validation reference](validation.md) for tier evidence and the
+revision-binding guarantee.

package/docs/reference/http.md

@@ -0,0 +1,85 @@
+# HTTP surface
+
+Facet binds loopback only. The CLI is the supported client; these routes are the
+service and gallery contract.
+
+## Routes
+
+| method | route                                                      | purpose                                                                                      | success |
+| ------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------: |
+| `POST` | `/api/v1/commands`                                         | Parse and dispatch a versioned command envelope.                                             |   `200` |
+| `GET`  | `/api/v1/stream`                                           | Stream committed revisions for one leased artifact as SSE.                                   |   `200` |
+| `POST` | `/api/v1/gallery/bootstrap`                                | Consume the one-shot `open` capability and return the artifact, revision, bearer, and lease. |   `200` |
+| `POST` | `/api/v1/gallery/release`                                  | Release a gallery lease.                                                                     |   `204` |
+| `GET`  | `/api/v1/gallery/source?revisionSha=<sha>`                 | Read source bytes and the latest stored verdict for the leased revision.                     |   `200` |
+| `GET`  | `/api/v1/gallery/evidence?revisionSha=<sha>`               | Read retained Tier 1 screenshot bytes for the leased revision without rerendering.           |   `200` |
+| `GET`  | `/gallery` and `/gallery/*`                                | Serve the built gallery shell and static assets.                                             |   `200` |
+| `GET`  | `/gallery/frame?nonce=<32 hex>&type=<type>&theme=<theme>`  | Return a frame document for `markdown`, `mermaid`, `svg`, `chart`, `html`, or `tsx`.         |   `200` |
+| `GET`  | `/gallery/frame/bootstrap/*` and `/gallery/frame/chunks/*` | Serve bundled frame scripts.                                                                 |   `200` |
+
+The gallery source route requires a non-empty `revisionSha`. It returns
+`artifactId`, the bound SHA, `artifactType`, `renderer`, UTF-8 `source`, and
+`verdict` (or `null`); TSX source responses also carry `execution`.
+The source and stream routes match both the lease ID and the artifact ID,
+preventing a valid lease for one artifact from reading another.
+
+The evidence route requires the same lease and artifact headers as the source
+route. It serves retained screenshot bytes with a content type sniffed from
+the bytes: `image/webp` or `image/png`. `screenshot_format` metadata does not
+override the file signature, and the route never rerenders the artifact.
+
+`theme` is validated as `dark` or `light` when supplied. It selects resolved
+frame display state; it is not an authorization or validation control.
+
+## Authentication
+
+`/api/v1/commands` accepts the install bearer or operator bearer. `promote`
+requires the operator bearer. Mutations require
+`Content-Type: application/json`.
+
+The stream requires:
+
+```text
+Authorization: Bearer <install-token>
+X-Gallery-Lease: <lease-id>
+X-Gallery-Artifact: <artifact-id>
+```
+
+The release and source routes use the same bearer plus the two gallery headers.
+The bootstrap route uses the one-shot capability returned by `open`; it does
+not accept a reusable query-string lease. `X-Gallery-Lease` is deliberately a
+header because URL tokens leak through logs, referrers, and browser history.
+
+## Host and CSRF
+
+Requests must use the loopback `Host` value issued by the service. Missing or
+foreign hosts are rejected. Missing `Host` is `421`; a foreign host is `400`.
+State-changing routes require an authenticated loopback request with `Origin`
+absent or equal to the service origin and `Sec-Fetch-Site` absent,
+`same-origin`, or `none`. Cross-site mutations return `403`. Browser origins
+are not trusted as authorization.
+
+## Status codes
+
+| status | meaning                                                                                                                |
+| -----: | ---------------------------------------------------------------------------------------------------------------------- |
+|  `200` | Successful envelope, JSON response, SSE stream, gallery file, or frame.                                                |
+|  `204` | Gallery lease released.                                                                                                |
+|  `400` | Invalid JSON/envelope/request, unsupported frame input, invalid `revisionSha`, invalid content type, or host mismatch. |
+|  `401` | Missing or invalid bearer, lease, artifact header, or one-shot bootstrap capability.                                   |
+|  `403` | Cross-site mutation or operator-only command attempted with the install bearer.                                        |
+|  `404` | Unknown route, missing gallery file, artifact, revision, or template.                                                  |
+|  `405` | `GET` sent to the command endpoint.                                                                                    |
+|  `409` | Store constraint, duplicate or immutable revision, unsupported artifact type, or pinned revision capacity.             |
+|  `413` | Raw request body exceeds the 16 MiB HTTP cap.                                                                          |
+|  `422` | Tier 0 worker timeout, protocol error, death, or output cap.                                                           |
+|  `503` | Tier 0 sandbox is unavailable.                                                                                         |
+|  `500` | Unhandled internal error or gallery build failure.                                                                     |
+
+## Status shape
+
+Status reports artifact-scoped `latestRevisionSha`, `revisionCount`,
+`pinnedCount`, and `templateCount` alongside `state` (`dormant` or `active`), `process` (`pid`, `uptimeMs`,
+`rssBytes`, `pssBytes`), `dbBytes`, `evidenceBytes`, `activeLeases`,
+`activeJobs`, `browserJobs`, `idleDeadline`, `version`, and `contractVersion`.
+Unavailable memory values are `null`; RSS from multiple processes is not summed.

package/docs/reference/mcp.md

@@ -0,0 +1,78 @@
+# MCP adapter
+
+On harnesses with shell access, the CLI is the integration; the MCP adapter is for structured-tool-only environments. If an agent can run a shell, use the CLI and the Facet skill — this adapter buys no capability there.
+
+Facet's npm package includes the `facet-mcp` bin. It needs Bun `1.4.0`; npm and pnpm install the package, but Bun remains the runtime.
+
+Run the adapter without a checkout:
+
+```sh
+bunx -p @legionworks/facet facet-mcp
+```
+
+The adapter resolves the CLI in this order: `FACET_CLI`, then `bun <adapter-relative-repository>/src/cli/main.ts`, then `facet` on `PATH`. Set `FACET_CLI` to an absolute CLI executable when the adapter should use another installation.
+
+## Register the server
+
+OpenCode config:
+
+```json
+{
+  "mcp": {
+    "facet": {
+      "type": "local",
+      "command": ["bunx", "-p", "@legionworks/facet", "facet-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Claude Code project config (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "facet": {
+      "command": "bunx",
+      "args": ["-p", "@legionworks/facet", "facet-mcp"]
+    }
+  }
+}
+```
+
+Codex config (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.facet]
+command = "bunx"
+args = ["-p", "@legionworks/facet", "facet-mcp"]
+```
+
+Set `FACET_HOME` in the host configuration when the adapter must use a non-default Facet runtime directory. Set `FACET_CLI` only for an alternate CLI executable.
+
+## Tools
+
+| Tool              | Inputs                                                                                                                    | Effect                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `facet_publish`   | `artifactId`, `type`, exactly one of `sourceText` or `file`; optional `execution`, `renderer`, `note`, `parentRevisionId` | Publishes inline source through CLI stdin or reads the named local file.     |
+| `facet_read_back` | `artifactId`; optional `revisionSha`, `tier` (`0` \| `1` \| `visual`)                                                     | Reads the latest or named revision. Tier 1 and visual need browser evidence. |
+| `facet_status`    | optional `artifactId`, `start`                                                                                            | Reads status. Set `start` only when activation is intended.                  |
+| `facet_export`    | `artifactId`, `format` (`source` \| `render`), `outDir`; optional `revisionSha`, `force`, `includeBytes`                  | Writes the CLI's normal export and sidecar beneath `outDir`.                 |
+| `facet_open_url`  | `artifactId`; optional `revisionSha`                                                                                      | Returns a gallery `frameUrl` without launching a browser.                    |
+
+`facet_open_url` always adds `--no-launch`. It is the MCP-safe form of `facet open`; it never invokes `xdg-open` or another desktop launcher.
+
+Exactly one of `sourceText` or `file` is required. The adapter returns `invalid_request` when both or neither are supplied.
+
+The MCP surface is the five artifact tools; run `facet doctor` through the CLI.
+
+## Result and error handling
+
+Every tool returns one text content item containing the complete versioned Facet envelope. `ok: true` means the CLI command completed at the transport boundary. For publish and read-back, inspect `data.verdict.status` separately: a stored verdict can be `error` even when the envelope is successful.
+
+Typed Facet failures return that same envelope with `isError: true`. The JSON body preserves `error.code`, `error.message`, `error.retryable`, and `error.details`. The adapter converts malformed CLI stdout and subprocess failures into typed `invalid_envelope` errors instead of throwing raw process text through MCP.
+
+## Boundary
+
+The adapter only shells out to `facet` and parses the shared wire envelope. It does not import service, validation, or gallery code. The boundary checker permits only the MCP SDK, Zod, Node builtins, adapter-local modules, shared contracts, and the shared product version in `src/harness-adapters/mcp/`.

package/docs/reference/security.md

@@ -0,0 +1,119 @@
+# Security reference
+
+Facet uses two bearer capabilities:
+
+• The install token authorizes ordinary agent/service commands.
+• The distinct operator promote capability authorizes `promote`.
+
+The operator token is supplied first by `FACET_PROMOTE_TOKEN`, otherwise by
+`FACET_HOME/secrets/promote.token` (or the configured runtime token path).
+Promotion requires that token and records the operator identity and timestamp.
+Token values never appear in argv, envelopes, logs, URLs, artifacts, notes, or
+fixtures. Structured logs contain request, artifact, revision, and timestamp
+identifiers only; source bytes and bearer tokens are redacted and never logged.
+
+TTY presence is not authorization. An agent can allocate a PTY; only the distinct operator token can promote. Promotion changes retention and audit state, not validation tier or sandbox trust.
+
+Gallery theme choice is display state, not a validation or security control.
+
+## Static HTML artifact policy
+
+HTML artifacts are static, script-free, and carry no `<style>` block or
+`style=` attribute. The verifier rejects:
+
+- the short known-dangerous element set: `script`, `iframe`, `object`,
+  `embed`, `form`, `link`, `meta`, `base`, `style`
+- every `on*=` event handler attribute
+- non-https, protocol-relative, and `javascript:` URLs on `<a>`, `<img>`,
+  and `<source>` (`<a>` allows `mailto:`; `<img>` and `<source>` allow
+  `data:` and `https:`)
+
+This is not the same surface the other artifact types police. Static
+HTML is the only type that can carry text-format risk inside its body,
+so the policy applies at parse time in Tier 0 and again in the Tier 1
+renderer. The verdict is bound to the bytes the operator published; the
+frame never injects script or styles into the artifact, only wraps the
+sanitized body in a marker-bearing wrapper that never reaches storage
+or export.
+
+### The two CSP jobs
+
+The frozen CSP at `src/shared/security/frozen-csp.ts` does two unrelated
+jobs, and the HTML widening widens only one of them:
+
+| job                  | directives                                                                                                                                                                                |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Verdict protection   | `script-src 'nonce-<BOOTSTRAP_NONCE>'`, `connect-src 'none'`, `frame-src 'none'`, `object-src 'none'`, `base-uri 'none'`, `form-action 'none'`, `worker-src 'none'`, `default-src 'none'` |
+| Display-time privacy | `img-src`, `font-src`                                                                                                                                                                     |
+
+A page that can run attacker code or open a network socket can forge a
+verdict or exfiltrate, so the verdict-protection directives stay closed
+on every artifact type. `img-src` and `font-src` protect PRIVACY at
+display time only — the verifier never follows these URLs, so widening
+`img-src` to `https:` (from `data:`) cannot weaken the verdict. The
+widening was an over-restriction being corrected: artifacts are authored
+by the operator's own agents, which hold bash and unrestricted network,
+so the artifact channel is strictly weaker than its author.
+
+The full frozen CSP, verbatim:
+
+```
+default-src 'none';
+script-src 'nonce-<BOOTSTRAP_NONCE>';
+style-src 'unsafe-inline';
+img-src data: https:;
+font-src data:;
+worker-src 'none';
+connect-src 'none';
+object-src 'none';
+base-uri 'none';
+form-action 'none';
+frame-src 'none';
+media-src 'none'
+```
+
+`style-src 'unsafe-inline'` exists for the vendored Tailwind/daisyUI
+stylesheet, which is loaded into the frame by `src/gallery-web/frame/styles/html-source.css`
+under the per-frame nonce. A custom `data:` font ships in the bundle as
+`font-src data:` allows; no remote font ever loads.
+
+→ [HTML reference](html.md) for the full HTML contract.
+
+## TSX execution policy
+
+TSX is executable artifact code, so interactive bundles run only inside the
+artifact's gallery frame, under that frame's own restrictive CSP (`self`, plus `blob:` for the
+compiled module import, plus inline styles for renderer-injected theme
+blocks) — a display-time policy,
+separate from the frozen nonce-only CSP the Tier 1 verifier enforces during
+validation. Tier 0 rejects direct capability use for typed author feedback,
+but the compilation-time runtime boundary is authoritative: netns blocks
+egress during `Bun.build` compilation. The AST policy is intentionally not
+complete under aliasing; the vendored-module allowlist (`src/shared/tsx/import-policy.ts`)
+is what makes indirect import forms unreachable at compile time.
+
+Facet mounts the default export. Artifact source must not self-mount.
+
+## Insecure mode
+
+Insecure mode is never enabled by default. It is boot-only: set `FACET_INSECURE=1`,
+`2`, or `3`, then restart the service. Environment changes do not alter a live
+service.
+
+| level | contract                                                                                      |
+| ----: | --------------------------------------------------------------------------------------------- |
+|   `0` | Secure defaults. Tier 0 and Tier 1 use their normal isolation.                                |
+|   `1` | Removes Tier 1 network-namespace isolation only. Real Tier 0 and Tier 1 validators still run. |
+|   `2` | Removes Tier 0 and Tier 1 network-namespace isolation. Real validators still run.             |
+|   `3` | Performs no validation and records `insecure:unvalidated`.                                    |
+
+Levels compose as a forced floor: the effective level is never below the
+operator's `FACET_INSECURE` value. `FACET_INSECURE_AUTO=1` may raise a level when
+startup probes fail, but it never selects level 3. With auto mode off, hard
+`tier*_unavailable` errors remain hard errors.
+
+Every insecure-level verdict carries its `Verdict.insecure` marker. L1 and L2
+statuses are real validator results — do not call them unvalidated. L3 also
+carries the marker and owns `insecure:unvalidated`. Startup, the service-ready
+envelope, CLI output, and gallery badge are intentionally loud. The CLI emits
+an `INSECURE` line.

package/docs/reference/storage.md

@@ -0,0 +1,93 @@
+# Storage reference
+
+Facet stores source bytes in SQLite and keeps render evidence on disk. The
+service does not parse or render source while writing it.
+
+## Runtime paths and permissions
+
+`computeFacetPaths` (`src/shared/config/paths.ts`) uses `FACET_HOME` when set:
+
+| path          | location under `FACET_HOME` | XDG default                                  |
+| ------------- | --------------------------- | -------------------------------------------- |
+| database      | `db/facet.sqlite`           | `$XDG_DATA_HOME/facet/db/facet.sqlite`       |
+| evidence      | `evidence/`                 | `$XDG_STATE_HOME/facet/evidence/`            |
+| promote token | `secrets/promote.token`     | `$XDG_DATA_HOME/facet/secrets/promote.token` |
+| lock          | `run/facet.lock`            | `$XDG_STATE_HOME/facet/run/facet.lock`       |
+| metadata      | `metadata.json`             | `$XDG_CONFIG_HOME/facet/metadata.json`       |
+
+`openDatabase` enables SQLite WAL mode, a 1,000 ms default busy timeout, and
+foreign keys. `hardenDatabaseFiles` applies mode `0600` to the database and its
+`-wal` and `-shm` sidecars. Owner-only directories use mode `0700`, including
+the evidence root and every per-run evidence directory.
+
+## Schema migrations
+
+`runMigrations` records applied versions in `schema_migrations` and applies
+additive fragments in order. The current schema is v9:
+
+| version | change                                                                                                                                                                 |
+| ------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|      v1 | Creates `projects`, `artifacts`, `revisions`, `render_runs`, and `templates`. Revision source is a BLOB; artifact types are `markdown`, `mermaid`, `svg`, and `chart`. |
+|      v2 | Adds `render_runs.retained`, exempting selected evidence from cleanup.                                                                                                 |
+|      v3 | Adds `revisions.renderer`, constrained to `svg` or `canvas`. `canvas` is a chart renderer, not an artifact type.                                                       |
+|      v4 | Adds `render_runs.screenshot_error_json` for typed transient screenshot-capture failures.                                                                              |
+|      v5 | Adds `render_runs.insecure_json` for the effective insecure execution marker and reason.                                                                               |
+|      v6 | Adds static `html` revisions and HTML observations.                                                                                                                    |
+|      v7 | Backfills HTML observation defaults.                                                                                                                                   |
+|      v8 | Adds `tsx`, declared revision execution, and nullable `render_runs.compiled_path`.                                                                                     |
+|      v9 | Adds `render_runs.screenshot_format`, recorded as `png` or `webp` for retained evidence.                                                                               |
+
+Migrations are additive and transactional. Existing revisions are not rewritten
+when a later schema version is applied.
+
+## Revisions
+
+Each artifact keeps a ring of at most 50 revisions. Publication evicts the
+oldest revision that is neither pinned nor bound to a template. If every
+retained revision is pinned or template-bound, publication fails with
+`revision_capacity_pinned`; protected history is never deleted.
+
+`pin` changes retention metadata only. It does not copy or rewrite source bytes.
+Unpinning makes a revision eligible for future ring eviction.
+
+Each revision has an immutable source BLOB, SHA-256, revision number, optional
+parent revision, note, artifact type, renderer, and timestamps. A revision SHA
+is unique per artifact. Read-back looks up `(artifactId, revisionSha)` before
+reading verdict rows, so verdicts cannot cross revisions.
+
+## Render evidence
+
+Tier 0 stores its row and, for successful TSX compilation, derived compiled
+bytes at `compiled_path`. Tier 1 stores the row plus a deterministic per-run directory:
+
+```text
+<evidence>/tier1/<revisionSha>/<runId>/
+├── screenshot.webp
+├── console.txt
+└── protocol-observation.json
+```
+
+New captures use `screenshot.webp`; legacy retained rows may keep
+`screenshot.png`. The v9 `render_runs.screenshot_format` value is `webp` or
+`png`, but bytes are authoritative on read and export: the service sniffs PNG
+and WebP signatures and treats unknown signatures as unavailable rather than
+trusting stale metadata. The service stores and serves bytes; it does not
+encode screenshots.
+
+The row also points to `protocol-observation.json` when present. The evidence
+root and each run directory are mode `0700`. `EVIDENCE_LAST_N_PER_ARTIFACT`
+defaults to `10`: the write path keeps the ten newest non-retained runs for an
+artifact and unlinks older screenshot and console files. Rows marked
+`retained = 1` are exempt. Cleanup is best-effort; the database row remains the
+authority and the orphan sweep can recover from stale files.
+
+## Templates
+
+A template records one immutable revision ID. Later publication to the source
+artifact cannot change that revision's SHA or bytes. Promotion records
+`promoted_by` and `promoted_at`. Promotion and instantiation require the
+operator capability.
+
+Instantiation creates a new artifact and publishes a byte-for-byte copy of the
+template revision with the same artifact type. The new revision is independent
+of the source artifact.