@legionworks/facet 1.9.0 → 1.10.0

package/README.md

@@ -41,10 +41,10 @@ Current gallery captures use the Mermaid fixture in resolved dark and the chart
 
 ## Install
 
-Facet is distributed as `@legionworks/facet`. **Bun is the required runtime**:
-the CLI runs on Bun `1.4.0` or newer. npm and pnpm are distribution channels,
-not Node runtime support; a machine without Bun cannot run the installed CLI and
-will receive a runtime failure.
+Facet is distributed as `@legionworks/facet`. Bun is the required runtime
+(version `1.4.0` or newer); install it first using the [official Bun
+installation instructions](https://bun.sh/docs/installation). npm and pnpm
+distribute Facet, but do not provide Bun. npm alone is not enough.
 
 Recommended:
 
@@ -65,27 +65,56 @@ For a zero-install invocation:
 bunx @legionworks/facet <verb>
 ```
 
-The pinned browser used for visual read-back downloads on the first visual
-read-back. See the [CLI reference](docs/reference/cli.md) for the command
-contract and [MCP reference](docs/reference/mcp.md) for structured-tool-only
-hosts.
+The first visual read-back requires the pinned browser. If it is missing,
+`facet doctor` prints the install command. See the [CLI reference](docs/reference/cli.md) for
+the command contract and [MCP reference](docs/reference/mcp.md) for
+structured-tool-only hosts.
+
+## Quickstart from an installed binary
+
+This walkthrough uses the globally installed `facet` command, not a source
+checkout. It creates disposable runtime and export directories.
+
+```sh
+export FACET_HOME="$(mktemp -d)"
+facet status --start
+facet doctor
+bunx --bun puppeteer browsers install chrome-headless-shell@151.0.7922.77
+SOURCE='<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 80"><rect width="240" height="80" rx="8" fill="#202638"/><text x="20" y="48" fill="white">Facet quickstart</text></svg>'
+SOURCE_FILE="$(mktemp)"
+printf '%s' "$SOURCE" > "$SOURCE_FILE"
+ARTIFACT_ID="$(facet create --project-id demo --slug quickstart --title 'Quickstart' | bun -e 'const x=JSON.parse(await Bun.stdin.text()); if(!x.ok) throw new Error(x.error.code); console.log(x.data.artifact.id)')"
+PUBLISH="$(facet publish --artifact-id "$ARTIFACT_ID" --type svg --file "$SOURCE_FILE")"
+printf '%s\n' "$PUBLISH" | bun -e 'const x=JSON.parse(await Bun.stdin.text()); if(!x.ok || !x.data.verdict) throw new Error("publish failed"); console.log(JSON.stringify(x.data.verdict))'
+REVISION_SHA="$(printf '%s\n' "$PUBLISH" | bun -e 'const x=JSON.parse(await Bun.stdin.text()); console.log(x.data.revision.sha256)')"
+facet read-back --artifact-id "$ARTIFACT_ID" --revision-sha "$REVISION_SHA" --tier visual
+EXPORT_DIR="$(mktemp -d)"
+facet export "$ARTIFACT_ID" --format source --out "$EXPORT_DIR/artifact.svg"
+```
+
+`doctor` checks the local runtime and browser setup and prints the browser
+install command if the pinned shell is missing. Install it before visual
+read-back. Inspect `data.verdict` in the publish envelope: an `ok` command
+envelope only confirms transport, and the stored verdict can still have
+`status: "error"`.
 
 ## Verdict language
 
 The gallery and CLI use the same wire enum, glyph, hue, and treatment.
 
-| enum (wire, verbatim)        | glyph | hue       | treatment                        |
-| ---------------------------- | ----- | --------- | -------------------------------- |
-| `ok`                         | `✓`   | `#c3e88d` | outline — proof, not celebration |
-| `error`                      | `✗`   | `#ff757f` | outline                          |
-| `partial:layout_unverified`  | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:opaque_content`     | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:external_resources` | `◐`   | `#ffc777` | outline; screenshot required     |
-| `partial:unstable`           | `◐`   | `#ffc777` | outline; screenshot required     |
-| `tampered`                   | `⊘`   | `#ff757f` | filled alarm badge               |
-| `timeout`                    | `◌`   | `#737aa2` | dim outline                      |
-| `shim_only`                  | `◇`   | `#737aa2` | dim outline                      |
-| `probe_only`                 | `◈`   | `#737aa2` | dim outline                      |
+| enum (wire, verbatim)        | glyph | hue       | treatment                           |
+| ---------------------------- | ----- | --------- | ----------------------------------- |
+| `ok`                         | `✓`   | `#c3e88d` | outline — proof, not celebration    |
+| `error`                      | `✗`   | `#ff757f` | outline                             |
+| `partial:layout_unverified`  | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:opaque_content`     | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:external_resources` | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:unstable`           | `◐`   | `#ffc777` | outline; screenshot required        |
+| `partial:empty_render`       | `◐`   | `#ffc777` | empty TSX root; screenshot required |
+| `tampered`                   | `⊘`   | `#ff757f` | filled alarm badge                  |
+| `timeout`                    | `◌`   | `#737aa2` | dim outline                         |
+| `shim_only`                  | `◇`   | `#737aa2` | dim outline                         |
+| `probe_only`                 | `◈`   | `#737aa2` | dim outline                         |
 
 `partial:external_resources` means an artifact references external HTTPS images the no-egress verifier could not load. An `ok` verdict can still carry `Verdict.screenshotError.code: "screenshot_unavailable"` when whole-artifact capture cannot be produced; it records the limit without changing the validation result. `insecure:unvalidated` means level 3 intentionally skipped validation. A missing verdict is `UNVERIFIED` with no tier.
 
@@ -133,7 +162,7 @@ Facet's insecure mode is an explicit, boot-only opt-in (`FACET_INSECURE=1|2|3`)
 
 ## MCP
 
-On harnesses with shell access, the CLI is the integration; the MCP adapter is for structured-tool-only environments. The npm package includes a stdio MCP adapter with five CLI-backed tools: publish, read-back, status, export, and a no-launch frame URL lookup. It requires Bun `1.4.0`. See the [MCP reference](docs/reference/mcp.md) for OpenCode, Claude Code, and Codex registration.
+On harnesses with shell access, the CLI is the integration; the MCP adapter is for structured-tool-only environments. The npm package includes six CLI-backed tools: `facet_create`, `facet_publish`, `facet_read_back`, `facet_status`, `facet_export`, and `facet_open_url`. It requires Bun `1.4.0`. Register it with `bun add -g @legionworks/facet` followed by the bare `facet-mcp` command; `npx -p @legionworks/facet facet-mcp` is the no-install alternative. See the [MCP reference](docs/reference/mcp.md) for OpenCode, Claude Code, and Codex registration.
 
 ## Documentation
 

package/dist/gallery/{chunk-4g8rem85.css → chunk-2dge4gwb.css}

@@ -136,6 +136,17 @@
   content: "✓";
 }
 
+.facet-verdict[data-interaction-error="true"] {
+  border-color: var(--facet-fail);
+  box-shadow: var(--facet-glow-danger);
+}
+
+.facet-verdict[data-interaction-error="true"]:after {
+  content: "✗ runtime";
+  color: var(--facet-fail);
+  font-weight: 700;
+}
+
 .facet-verdict[data-status="error"] {
   border-color: var(--facet-fail-border);
   background: var(--facet-fail-fill);
@@ -186,6 +197,16 @@
   content: "◐";
 }
 
+.facet-verdict[data-status="partial:empty_render"] {
+  border-color: var(--facet-partial-border);
+  background: var(--facet-partial-fill);
+  color: var(--facet-partial);
+}
+
+.facet-verdict[data-status="partial:empty_render"]:before {
+  content: "◐";
+}
+
 .facet-verdict[data-status="tampered"], .facet-verdict[data-status="insecure:unvalidated"] {
   border-color: var(--facet-fail);
   background: var(--facet-fail);
@@ -194,7 +215,7 @@
   font-weight: 700;
 }
 
-.facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="insecure:unvalidated"]:before {
+.facet-verdict[data-status="tampered"]:before, .facet-verdict[data-status="insecure:unvalidated"]:before {
   content: "⊘";
 }
 

package/dist/gallery/{chunk-c6s9k9ty.js → chunk-48emrxg6.js}

@@ -4349,7 +4349,8 @@ var TemplateSchema = exports_external.object({
   name: exports_external.string().min(1),
   description: exports_external.string().nullable(),
   promotedBy: exports_external.string().min(1),
-  promotedAt: IsoTimestampSchema
+  promotedAt: IsoTimestampSchema,
+  promotionOverride: exports_external.string().nullable()
 });
 
 // src/shared/contracts/observed-counts.ts
@@ -4380,6 +4381,7 @@ var RenderStatusSchema = exports_external.enum([
   "partial:opaque_content",
   "partial:external_resources",
   "partial:unstable",
+  "partial:empty_render",
   "tampered",
   "timeout",
   "shim_only",
@@ -4417,8 +4419,12 @@ var LexicalCountersSchema = exports_external.object({
   html: HtmlStructureCountsSchema.optional()
 });
 var ObservedCountShape = Object.fromEntries(OBSERVED_COUNT_KEYS.map((key) => [key, exports_external.number().int().nonnegative()]));
+var RenderedContentShape = {
+  emptyRendererRoot: exports_external.boolean().optional()
+};
 var VerdictObservedSchema = exports_external.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: exports_external.array(exports_external.string()).optional(),
   errorCount: exports_external.number().int().nonnegative(),
@@ -4472,6 +4478,7 @@ var Tier1ResultSchema = Tier0ResultSchema.extend({
 });
 var ProtocolObservationSchema = exports_external.object({
   ...ObservedCountShape,
+  ...RenderedContentShape,
   html: HtmlStructureCountsSchema.optional(),
   viewBoxes: exports_external.array(exports_external.string()),
   errorCount: exports_external.number().int().nonnegative(),
@@ -4486,6 +4493,7 @@ var FAVICON_TINT_BY_STATUS = {
   "partial:opaque_content": "amber",
   "partial:external_resources": "amber",
   "partial:unstable": "amber",
+  "partial:empty_render": "amber",
   tampered: "red",
   timeout: "red",
   shim_only: "grey",
@@ -4599,6 +4607,10 @@ var ListRequestSchema = BaseRequestSchema.extend({
   slugPrefix: exports_external.string().optional(),
   limit: exports_external.number().int().positive().max(MAX_LIST_LIMIT).optional()
 });
+var TemplatesRequestSchema = BaseRequestSchema.extend({
+  command: exports_external.literal("templates"),
+  limit: exports_external.number().int().positive().max(MAX_LIST_LIMIT).optional()
+});
 var ReadBackRequestSchema = BaseRequestSchema.extend({
   command: exports_external.literal("readBack"),
   artifactId: exports_external.string().min(1),
@@ -4620,7 +4632,8 @@ var PromoteRequestSchema = BaseRequestSchema.extend({
   revisionId: exports_external.string().min(1),
   name: exports_external.string().min(1),
   description: exports_external.string().nullable().optional(),
-  promotedBy: exports_external.string().min(1)
+  promotedBy: exports_external.string().min(1),
+  allowUnverified: exports_external.boolean().optional()
 });
 var InstantiateRequestSchema = BaseRequestSchema.extend({
   command: exports_external.literal("instantiate"),
@@ -4678,6 +4691,19 @@ var ListResultSchema = BaseResultSchema.extend({
   artifacts: exports_external.array(ArtifactEnvelopeSchema),
   nextCursor: exports_external.string().nullable().optional()
 });
+var TemplatesResultSchema = BaseResultSchema.extend({
+  command: exports_external.literal("templates"),
+  templates: exports_external.array(exports_external.object({
+    name: exports_external.string().min(1),
+    artifactId: exports_external.string().min(1),
+    revisionId: exports_external.string().min(1),
+    revisionSha: exports_external.string().regex(/^[a-f0-9]{64}$/),
+    promotedBy: exports_external.string().min(1),
+    promotedAt: exports_external.string().datetime({ offset: true }),
+    promotionOverride: exports_external.string().nullable(),
+    sourceVerdict: exports_external.object({ status: RenderStatusSchema, tier: exports_external.union([exports_external.literal(0), exports_external.literal(1)]) }).nullable()
+  }))
+});
 var ReadBackResultSchema = BaseResultSchema.extend({
   command: exports_external.literal("readBack"),
   renderer: RendererSchema,
@@ -5402,7 +5428,7 @@ function setGalleryVerdict(document2, verdict) {
   badge.dataset.status = verdict.status;
   badge.childNodes[0].textContent = verdict.status.split(":")[0] ?? verdict.status;
   if (tier !== null) {
-    const detail = verdict.status === "partial:opaque_content" ? "opaque" : verdict.status === "partial:layout_unverified" ? "layout" : verdict.status === "partial:external_resources" ? "external" : verdict.status === "partial:unstable" ? "unstable" : null;
+    const detail = verdict.status === "partial:opaque_content" ? "opaque" : verdict.status === "partial:layout_unverified" ? "layout" : verdict.status === "partial:external_resources" ? "external" : verdict.status === "partial:unstable" ? "unstable" : verdict.status === "partial:empty_render" ? "empty" : null;
     const insecure = verdict.insecure === undefined ? null : `INSECURE L${verdict.insecure.level}`;
     const suffix = insecure === null ? `T${verdict.tier}` : `${insecure} · T${verdict.tier}`;
     tier.textContent = detail === null ? `· ${suffix}` : `· ${detail} · ${suffix}`;
@@ -5546,6 +5572,42 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   let removeThemePreferenceListener = noOp;
   let generation = 0;
   let activeFrame = null;
+  let removeInteractionListener = noOp;
+  const endInteractionSignal = () => {
+    removeInteractionListener();
+    const badge = document2.getElementById("facet-verdict");
+    if (badge !== null)
+      delete badge.dataset.interactionError;
+  };
+  const activateInteractionSignal = (frame) => {
+    endInteractionSignal();
+    const badge = document2.getElementById("facet-verdict");
+    updateGalleryStatus("displayed");
+    const frameWindow = frame.element.raw.contentWindow;
+    if (frameWindow === null || typeof frameWindow.addEventListener !== "function")
+      return;
+    const markFailure = () => {
+      if (expired || activeFrame !== frame || frame.renderResult === null)
+        return;
+      if (badge !== null)
+        badge.dataset.interactionError = "true";
+      updateGalleryStatus("displayed · runtime error during interaction");
+    };
+    frameWindow.addEventListener("error", markFailure, true);
+    frameWindow.addEventListener("unhandledrejection", markFailure, true);
+    const frameDocument = frame.element.raw.contentDocument;
+    const observer = frameDocument == null || typeof MutationObserver !== "function" ? null : new MutationObserver(() => {
+      if (frameDocument.querySelector("[data-facet-error]"))
+        markFailure();
+    });
+    if (frameDocument !== null)
+      observer?.observe(frameDocument, { childList: true, subtree: true });
+    removeInteractionListener = () => {
+      frameWindow.removeEventListener("error", markFailure, true);
+      frameWindow.removeEventListener("unhandledrejection", markFailure, true);
+      observer?.disconnect();
+    };
+  };
   const expireSession = () => {
     if (expired)
       return;
@@ -5556,6 +5618,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
     exportMenu?.sync();
     activeFrame?.renderResult?.setGestureMode("native");
     swaps?.close();
+    endInteractionSignal();
     removeThemePreferenceListener();
     clearSession(window2.sessionStorage);
     renderSessionExpired(document2, (message) => setGalleryError(document2, message), (status) => setGalleryStatus(document2, status));
@@ -5687,6 +5750,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   updateGalleryFavicon(source.verdict?.status ?? "unverified");
   updateGalleryVerdict(source.verdict ?? null);
   updateGalleryStatus("displayed");
+  activateInteractionSignal(current);
   updateLiveState("live");
   const themeToggle = document2.getElementById("facet-theme-toggle");
   const updateThemeToggle = (mode) => {
@@ -5745,6 +5809,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       return;
     current = next;
     activeFrame = next;
+    activateInteractionSignal(next);
     commitTheme(nextMode, nextResolvedTheme);
     syncPanZoomToggle();
     syncZoomButtons();
@@ -5815,6 +5880,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       if (!result.failedNewFrameReady) {
         current = frame;
         activeFrame = frame;
+        activateInteractionSignal(frame);
         source = revision;
         commitTheme(revisionThemeMode, revisionTheme);
         syncPanZoomToggle();
@@ -5870,6 +5936,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
       updateSwapBar("start");
       updateGalleryFavicon("unverified");
       updateGalleryVerdict(null);
+      endInteractionSignal();
       swaps?.enqueue({ kind: "revision", ...event });
     },
     onClose: (event) => {
@@ -5885,6 +5952,7 @@ async function startGallery(runtime = browserGalleryRuntime()) {
   let zoomButtonPoll;
   const shutdown = () => {
     stream.close();
+    removeInteractionListener();
     removeThemePreferenceListener();
     if (zoomButtonPoll !== undefined)
       clearInterval(zoomButtonPoll);

package/dist/gallery/frame/frame.css

@@ -98,12 +98,19 @@ body {
  * wider than the stage (it start-aligns and stays reachable by
  * scroll instead).
  */
+#artifact[data-facet-artifact-type="html"],
+#artifact[data-facet-artifact-type="tsx"] {
+  display: flex;
+  flex-direction: column;
+}
+
 #artifact[data-facet-artifact-type="html"] > [data-facet-renderer-root],
 #artifact[data-facet-artifact-type="tsx"] > [data-facet-renderer-root] {
   display: flex;
   justify-content: safe center;
   align-items: flex-start;
-  min-height: 100%;
+  /* A full-height root plus a sibling runtime error makes capture bounds grow on every viewport resize. */
+  flex: 1 0 auto;
 }
 
 #artifact > svg {

package/dist/gallery/frame/runtime/chart.js

@@ -42693,6 +42693,28 @@ function withFacetChartTheme(spec, theme) {
     }
   };
 }
+function withFacetChartDimensions(spec) {
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+    return spec;
+  const source4 = spec;
+  const config = source4.config;
+  if ("autosize" in source4 || typeof config === "object" && config !== null && !Array.isArray(config) && "view" in config)
+    return spec;
+  if ("width" in source4 && "height" in source4)
+    return spec;
+  const authoredConfig = typeof config === "object" && config !== null && !Array.isArray(config) ? config : {};
+  const viewDefaults = {
+    ...!("width" in source4) ? { continuousWidth: 640, discreteWidth: 640 } : {},
+    ...!("height" in source4) ? { continuousHeight: 360, discreteHeight: 360 } : {}
+  };
+  return {
+    ...source4,
+    config: {
+      ...authoredConfig,
+      view: viewDefaults
+    }
+  };
+}
 async function renderChart(ctx, bytes, renderer = "svg") {
   const text3 = decodeArtifactBytes(bytes);
   let spec;
@@ -42704,7 +42726,7 @@ async function renderChart(ctx, bytes, renderer = "svg") {
   }
   let compiled;
   try {
-    compiled = compile(withFacetChartTheme(spec, ctx.theme));
+    compiled = compile(withFacetChartTheme(withFacetChartDimensions(spec), ctx.theme));
   } catch (error3) {
     const message = error3 instanceof Error ? error3.message : String(error3);
     throw new FacetRenderError(`vega-lite compile failed: ${message}`, "chart_compile_error");

package/dist/gallery/index.html

@@ -8,7 +8,7 @@
     
     
     
-  <link rel="stylesheet" crossorigin href="./chunk-4g8rem85.css"><script type="module" crossorigin src="./chunk-c6s9k9ty.js"></script></head>
+  <link rel="stylesheet" crossorigin href="./chunk-2dge4gwb.css"><script type="module" crossorigin src="./chunk-48emrxg6.js"></script></head>
   <body>
     <div id="facet-shell">
       <header id="facet-status">
@@ -17,7 +17,9 @@
         <span class="sep" aria-hidden="true"></span>
         <span id="facet-artifact-title"></span>
         <span class="revision" id="facet-revision">—</span>
-        <span class="status-line" id="facet-status-line">idle</span>
+        <span class="status-line" id="facet-status-line" role="status" aria-live="polite"
+          >idle</span
+        >
         <!--
           Verdict badge. JS wiring: set data-status to the FULL wire
           enum, text to status.split(":")[0], and the tier span to

package/docs/reference/cli.md

@@ -28,7 +28,8 @@ Errors use the same top level with `ok: false` and
 | `read-back`   | `--artifact-id`, optional `--revision-sha` (latest when omitted), `--tier` (one of: `0` \| `1` \| `visual`)                       |
 | `status`      | `--artifact-id`, `--start` (valueless start-then-inspect switch)                                                                  |
 | `open`        | `--artifact-id`, optional `--revision-sha` (latest when omitted), `--no-launch`                                                   |
-| `promote`     | `--artifact-id`, `--revision-id`, `--name`, `--description`, `--promoted-by`                                                      |
+| `promote`     | `--artifact-id`, `--revision-id`, `--name`, `--description`, `--promoted-by`, `--allow-unverified`                                |
+| `templates`   | optional `--limit`                                                                                                                |
 | `instantiate` | `--name`, `--new-slug`, `--project-id`                                                                                            |
 | `pin`         | `--revision-id`, `--pinned` (`true` or `false`)                                                                                   |
 | `export`      | `<artifactId>`, `--revision`, `--format source\|render`, `--out`, `--force`, `--include-bytes`                                    |
@@ -96,6 +97,12 @@ available without invoking the desktop launcher, and a launcher failure reports
 defaults to `svg`; `canvas` is valid only for chart artifacts. An invalid
 renderer value is a usage error and exits 64.
 
+For charts, Facet defaults unspecified views to 640×360 through
+`config.view`. These defaults apply only when the spec has no `autosize`, no
+`config.view`, and does not set both top-level `width` and `height`. An authored
+dimension is preserved; composite facet, concat, and repeat views receive the
+defaults through their child view config.
+
 `publish --type html` publishes a static, script-free HTML artifact.
 See [HTML reference](html.md) for the static / script-free contract,
 the denied element and attribute set, the vendored class vocabulary,
@@ -134,6 +141,27 @@ mode does not assert that its visuals always change.
 `FACET_HOME/secrets/promote.token`. Neither source is accepted as an argv flag
 or emitted in a CLI envelope.
 
+Before promotion, request visual read-back for the exact revision. Promotion
+requires Tier 1 visual verification. A refusal returns `promotion_refused`
+(HTTP 409) with `error.details.reason`: `no_visual_verification` when no visual
+run exists, `error` when Tier 0 failed, or the refused Tier 1 status. The gate refuses `error`,
+`partial:empty_render`, `tampered`, `timeout`, `shim_only`, `probe_only`, and
+`insecure:unvalidated`. Other Tier 1 statuses are allowed when Tier 0 is not an
+error. `--allow-unverified` permits a refused promotion but stores the refusal
+reason in the template's `promotionOverride`; this is an audit record, not
+verification or a passing verdict. A duplicate template name returns
+`template_name_taken` (HTTP 409).
+
+`facet templates [--limit N]` lists promoted templates. It uses the install
+token. Each row includes the source verdict, read from the stored revision when
+the list is requested, and any `promotionOverride` reason.
+
+A Tier 1 verdict whose `insecure.level === 3` marker is present is refused as
+`insecure:unvalidated` even when the verdict's status would otherwise be
+allow-listed (level 3 skips validation); `--allow-unverified` records the same
+reason on `promotionOverride`. Levels 1 and 2 keep their status-based
+treatment — they are real validator results under relaxed sandboxing.
+
 ## Insecure mode
 
 `FACET_INSECURE=1|2|3` sets a boot-only forced floor. `FACET_INSECURE_AUTO=1`

package/docs/reference/export.md

@@ -84,6 +84,10 @@ its sidecar is not a valid export.
 The sidecar describes the stored verdict. Export does not approve, promote,
 revalidate, or otherwise change the artifact.
 
+Evidence consumers must inspect `verdict.insecure` before treating a result as
+validated. In particular, an explicit Tier 1 run under insecure level 3 carries
+the insecure marker even when its status is not `insecure:unvalidated`.
+
 ## `evidence_unavailable`
 
 Render export returns typed `evidence_unavailable` when the selected revision

package/docs/reference/mcp.md

@@ -4,12 +4,17 @@ On harnesses with shell access, the CLI is the integration; the MCP adapter is f
 
 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:
+Install globally, then run the bin with Bun `1.4.0` or newer:
 
 ```sh
-bunx -p @legionworks/facet facet-mcp
+bun add -g @legionworks/facet
+facet-mcp
 ```
 
+Releases through `1.9.0` ship a `facet-mcp` bin that cannot launch directly. Use the next release or newer. A local package built with this fix answered JSON-RPC `initialize` after a global install. The `npx -p @legionworks/facet facet-mcp` path still needs verification against that published release before it is recommended.
+
+Do not use `bunx -p @legionworks/facet facet-mcp` as the registration command without verifying the local Bun release. It exited immediately with status 1 on Bun `1.3.14` on the measured host; the same form also exited with status 1 under the available scratch Bun `1.4.0` runtime. These observations are environment-specific, so this caveat is not a universal claim about every Bun release or installation.
+
 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
@@ -21,7 +26,7 @@ OpenCode config:
   "mcp": {
     "facet": {
       "type": "local",
-      "command": ["bunx", "-p", "@legionworks/facet", "facet-mcp"],
+      "command": ["facet-mcp"],
       "enabled": true
     }
   }
@@ -34,8 +39,7 @@ Claude Code project config (`.mcp.json`):
 {
   "mcpServers": {
     "facet": {
-      "command": "bunx",
-      "args": ["-p", "@legionworks/facet", "facet-mcp"]
+      "command": "facet-mcp"
     }
   }
 }
@@ -45,8 +49,7 @@ Codex config (`~/.codex/config.toml`):
 
 ```toml
 [mcp_servers.facet]
-command = "bunx"
-args = ["-p", "@legionworks/facet", "facet-mcp"]
+command = "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.
@@ -55,6 +58,7 @@ Set `FACET_HOME` in the host configuration when the adapter must use a non-defau
 
 | Tool              | Inputs                                                                                                                    | Effect                                                                       |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `facet_create`    | `projectId`, `slug`, `title`                                                                                              | Creates an artifact; pass its returned `data.artifact.id` to publish.        |
 | `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.                  |
@@ -65,7 +69,7 @@ Set `FACET_HOME` in the host configuration when the adapter must use a non-defau
 
 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.
+The MCP surface has six artifact tools. Start a cold-home flow with `facet_create`, then call `facet_publish`, `facet_read_back`, and `facet_export`. Each tool advertises its input schema in `tools/list`; run `facet doctor` through the CLI.
 
 ## Result and error handling
 
@@ -73,6 +77,10 @@ Every tool returns one text content item containing the complete versioned Facet
 
 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.
 
+For `output_unwritable`, `error.details.out` is the absolute path whose write
+failed. A malformed Mermaid fence is a verdict result, not a tool failure: the
+call returns `isError: false` with `data.verdict.status: "error"`.
+
 ## 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

@@ -107,6 +107,13 @@ service.
 |   `2` | Removes Tier 0 and Tier 1 network-namespace isolation. Real validators still run.             |
 |   `3` | Performs no validation and records `insecure:unvalidated`.                                    |
 
+Level 3 skips publish-time validation, not an explicit visual read-back.
+`facet read-back --tier visual` still runs Tier 1, and that verdict carries the
+insecure marker. Evidence consumers must check the marker, not infer trust from
+`status` alone. A level-3 visual verdict does not count toward `facet promote`
+either — the gate refuses it as `insecure:unvalidated` unless the operator
+passes `--allow-unverified`.
+
 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

package/docs/reference/storage.md

@@ -23,7 +23,7 @@ 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:
+additive fragments in order. The current schema is v10:
 
 | version | change                                                                                                                                                                 |
 | ------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -36,6 +36,7 @@ additive fragments in order. The current schema is v9:
 |      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.                                                                               |
+|     v10 | Adds nullable `templates.promotion_override`; null for pre-v10 templates and for promotions that passed the verification gate.                                         |
 
 Migrations are additive and transactional. Existing revisions are not rewritten
 when a later schema version is applied.
@@ -81,6 +82,10 @@ 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.
 
+Facet targets one operator on a local machine. The evidence bound is the last
+`EVIDENCE_LAST_N_PER_ARTIFACT` Tier 1 runs per artifact, plus any retained runs.
+There is no quota; retained evidence can grow without a fixed limit.
+
 ## Templates
 
 A template records one immutable revision ID. Later publication to the source

package/docs/reference/tsx.md

@@ -29,6 +29,15 @@ and must not call `createRoot` or self-mount.
 
 ## Imports and styling
 
+Artifacts cannot fetch data (`connect-src 'none'`). Generate source with the
+data embedded, then publish it. For repeated updates, regenerate the file and
+use `facet publish --watch` to publish each changed version:
+
+```sh
+node -e 'const data = [{label:"A", value:3}]; require("node:fs").writeFileSync("report.tsx", `export default function Report(){ return <pre>{JSON.stringify(${JSON.stringify(data)})}</pre> }`)'
+facet publish --artifact-id <id> --type tsx --file report.tsx
+```
+
 The compiler accepts only vendored modules: `react`, `react-dom`,
 `react-dom/client`, `react/jsx-runtime`, and `react/jsx-dev-runtime`.
 Pinned versions are React and React DOM `19.2.8`, TypeScript `5.7.3`.
@@ -62,6 +71,11 @@ has no host port or service capability.
 
 ## Storage and export
 
+The TSX verifier loads the vendored `artifact.css` used by the gallery frame.
+A runtime error after initial render, such as one thrown by a click handler,
+appears as a gallery signal in an `aria-live="polite"` status region. It does
+not rewrite the immutable verdict and clears on revision swap or theme change.
+
 Revision source remains immutable. Compilation creates derived bytes recorded at
 the run's `compiled_path`; TSX source export writes the original `.tsx` bytes.
 Render export remains the retained Tier 1 screenshot. Evidence retains the last