davidf9999 · davidf9999 · Jul 22, 2026 · Jul 22, 2026
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -5,5 +5,5 @@ include README.md
 include SECURITY.md
 include STATUS.md
 recursive-include .agents *.md *.yaml
-recursive-include docs *.md *.svg
+recursive-include docs *.html *.md *.png *.svg
 recursive-include examples *.json *.md *.svg *.yaml
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ auditable layout proposals and agent-generated designs.
 > may change incompatibly while downstream use cases establish the right public
 > abstractions.
 
-![Validated synthetic irregular kitchen](docs/demo/irregular_kitchen.svg)
+![A validated kitchen plan beside a refused invalid render](docs/social-preview.png)
 
 ## Why This Exists
 
@@ -30,6 +30,22 @@ blockage. The downstream adapter exposed the defect, and the core now makes
 operation-blocker checks height-aware. This feedback loop is why the package is
 kept separate from domain policy while still being exercised by a real project.
 
+## Failure Is a First-Class Output
+
+The validator does not produce a design drawing after a hard failure:
+
+```console
+$ geometry-validated-layout render examples/failing_cooktop/project.yaml \
+    --output /tmp/failing.svg
+Errors:
+- cooktop_01: footprint is not contained by parent counter_01
+Rendering refused because validation failed.
+```
+
+This refusal is part of the public contract: rendering and validation use the
+same structured coordinates, so a plausible image cannot hide rejected
+geometry.
+
 ## Quick Start
 
 ```bash
@@ -44,14 +60,15 @@ geometry-validated-layout render examples/irregular_kitchen/project.yaml --outpu
 pytest
 ```
 
-The failing example demonstrates the main value:
+Try the deliberate failure:
 
 ```bash
-geometry-validated-layout validate examples/failing_cooktop/project.yaml
+geometry-validated-layout render examples/failing_cooktop/project.yaml \
+  --output /tmp/failing.svg
 ```
 
-Expected result: validation fails because the cooktop is not contained by its
-parent countertop and supporting base.
+Expected result: validation identifies the containment error and rendering is
+refused.
 
 Generate the demo SVG:
 

diff --git a/docs/social-preview.html b/docs/social-preview.html
@@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>geometry-validated-layout social preview</title>
+  <style>
+    * { box-sizing: border-box; }
+    html, body { margin: 0; width: 1280px; height: 640px; overflow: hidden; }
+    body {
+      background: #f3f5f6;
+      color: #172126;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      letter-spacing: 0;
+    }
+    main {
+      width: 1280px;
+      height: 640px;
+      padding: 42px 52px 34px;
+      display: grid;
+      grid-template-rows: 112px 1fr 34px;
+      gap: 18px;
+      border-top: 12px solid #1f8a70;
+    }
+    header { display: flex; align-items: flex-start; justify-content: space-between; gap: 30px; }
+    .brand { font-size: 21px; font-weight: 750; color: #31505c; }
+    h1 { margin: 8px 0 0; font-size: 48px; line-height: 1; font-weight: 780; }
+    .version { margin-top: 4px; font-size: 18px; color: #50646d; white-space: nowrap; }
+    .comparison { min-height: 0; display: grid; grid-template-columns: 1.05fr 0.95fr; gap: 26px; }
+    section { min-width: 0; min-height: 0; border: 1px solid #c8d1d5; background: #ffffff; }
+    .valid { display: grid; grid-template-rows: 46px 1fr; }
+    .valid .heading, .invalid .heading {
+      padding: 12px 18px;
+      border-bottom: 1px solid #d9e0e3;
+      font-size: 18px;
+      font-weight: 750;
+    }
+    .valid .heading { color: #14664f; border-left: 8px solid #1f8a70; }
+    .plan-wrap { min-height: 0; padding: 10px 16px 14px; display: flex; align-items: center; justify-content: center; }
+    .plan-wrap img { width: 100%; height: 100%; object-fit: contain; }
+    .invalid { display: grid; grid-template-rows: 46px 1fr; background: #20292e; border-color: #20292e; color: #f5f7f8; }
+    .invalid .heading { color: #ffb4ab; border-color: #46545b; border-left: 8px solid #d74343; }
+    .terminal { padding: 24px 26px; font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace; }
+    .command { color: #b9c8ce; font-size: 16px; line-height: 1.45; }
+    .error-label { margin-top: 26px; color: #ffb4ab; font-size: 17px; font-weight: 700; }
+    .error { margin-top: 8px; font-size: 18px; line-height: 1.42; color: #ffffff; }
+    .refused { margin-top: 28px; padding-top: 18px; border-top: 2px solid #d74343; font-size: 31px; font-weight: 800; color: #ffb4ab; }
+    footer { display: flex; align-items: center; justify-content: space-between; font-size: 17px; color: #48606a; }
+    footer strong { color: #172126; }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div>
+        <div class="brand">geometry-validated-layout</div>
+        <h1>Validate before render.</h1>
+      </div>
+      <div class="version">Python · CLI · v0.1.0 developer preview</div>
+    </header>
+
+    <div class="comparison">
+      <section class="valid">
+        <div class="heading">PASS · Deterministic SVG rendered</div>
+        <div class="plan-wrap">
+          <img src="../examples/complete_kitchen/plan.svg" alt="Validated synthetic kitchen plan">
+        </div>
+      </section>
+
+      <section class="invalid">
+        <div class="heading">FAIL · Invalid geometry rejected</div>
+        <div class="terminal">
+          <div class="command">$ geometry-validated-layout render<br>examples/failing_cooktop/project.yaml</div>
+          <div class="error-label">ERROR</div>
+          <div class="error">cooktop_01: footprint is not contained by parent counter_01</div>
+          <div class="refused">RENDERING REFUSED</div>
+        </div>
+      </section>
+    </div>
+
+    <footer>
+      <span>Auditable spatial-layout validation for humans and AI agents</span>
+      <strong>github.com/davidf9999/geometry-validated-layout</strong>
+    </footer>
+  </main>
+</body>
+</html>
diff --git a/docs/social-preview.png b/docs/social-preview.png