From b3362f5fcc5c81efe08783370ae3f7559b76532b Mon Sep 17 00:00:00 2001
From: hushamsaeed <husham@gmail.com>
Date: Sat, 2 May 2026 13:35:06 +0500
Subject: [PATCH] audit: site-wide honesty pass + sketch tool fixes (Wave 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Findings from a 6-agent autonomous audit (engineering, content/strategy,
cross-repo, package code review, sketch UX/a11y, codex second-opinion).
Verified each load-bearing claim before acting (ghcr.io 401, /sdk/ts/ 404,
brew tap 404, 11 H1s on /architecture/, iframe -233px desktop clip, sketch
same-row edge bug, Sharp libvips LGPL transitive).

Site copy honesty:
- Architecture H1: "Bank-Grade Platform Architecture" -> "Reference architecture
  for bank-grade internal-tooling fleets" + v0.1.0-vs-target callout note.
  Demoted 10x "# Part X" -> "## Part X" (was 11 H1s, now 1).
- Removed duplicate six-commitments recap from §4 (links to manifesto).
- Aligned starter-api stack to shipped state (Go 1.25 + chi + pgx, not
  Go 1.23 + Fiber + GORM). Marked Temporal as v1.0 target.
- Fixed OTel auto-instrumentation list (chi+pgx, not Fiber+GORM).
- Launch H1: "bank-grade foundation" -> "first SDK release". Reframed
  "everything... on a public registry you can install from right now" to
  honest "SDKs on registries; substrate from source".
- Launch table CLI: pinned-version @v0.1.1 -> @latest (avoids drift claim).
- Try-it: kept "Stand it up in an afternoon" but rewrote step 2 to use
  git-clone + values-dev.yaml (the path that works at v0.1.0); helm-OCI
  flow moved into a v1.0-target caution block. Dropped non-existent
  Homebrew tap line. Dropped Argo-CD reconcile step (it isn't shipped).
  Added kind-cluster prerequisites.
- /sdk/ index: added per-package status column (all v0.1.0 today).
- /tools/: trimmed 5 "coming soon" cards down to 2 (OTel Config + CloudEvents
  Validator) per strategist call. Softened "Excalidraw (looks amateur)"
  punch-down. Sketch promoted to its own H2 from the tools/diagrams pair.
- /examples/access-requests/: disclosed dev-cookie-shim limitation.
- Stale "Spectral" comment in astro.config -> IBM Plex Sans.
- Dropped IBM Plex Mono fallback from theme.css (JetBrains Mono is canonical).

Engineering:
- IFrameTool.astro: fixed full-bleed via JS measurement instead of
  100vw + calc(50% - 50vw) trick (which misaligns with Starlight's
  splash-template left-anchored content column, off-screen left -233px).
  Also: forwards parent location.hash into iframe src so /tools/sketch/
  share links route the encoded DSL into the embedded tool.
- Removed iframe sandbox= attr: `allow-scripts + allow-same-origin`
  together negates sandbox and Chromium warns. Same-origin anyway.
- check.yml: added permissions: contents:read minimal token scope.
- index.md: title "Plinth" (-> rendered as "Plinth | Plinth") replaced
  with the tagline. Added theme-color meta site-wide.

Sketch tool (public/tools/sketch-app.html):
- Toolbar wraps on mobile (was clipping Copy share link off-screen).
- "Empty" example now actually empty (was rendering a non-empty SVG with
  just the cite floating; placeholder text wasn't shown).
- Share-link encoding chunked to 8KB, with a 64KB DSL cap.
- Bad hash now flashes "share link malformed" instead of silently falling
  through to default.
- Status: aria-live=polite, distinct ✕ vs ● glyph for err/ok (not just
  color). Updates via replaceChildren (no innerHTML) so SR doesn't
  over-announce.
- Added <h1 visually-hidden>, wrapped editor in <main>, <label for>
  on the example select, autofocus on textarea (primary surface).
- Fixed render: shows placeholder when DSL parses to 0 nodes (was
  rendering an empty cite-only SVG).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/check.yml                  |   3 +
 astro.config.mjs                             |  11 +-
 public/tools/sketch-app.html                 | 134 ++++++++++++++-----
 src/assets/theme.css                         |   2 +-
 src/components/IFrameTool.astro              |  59 ++++++--
 src/content/docs/architecture.md             |  63 ++++-----
 src/content/docs/examples/access-requests.md |   4 +
 src/content/docs/index.md                    |   4 +-
 src/content/docs/launch/v0-1-0.md            |  12 +-
 src/content/docs/sdk/index.md                |  42 +++---
 src/content/docs/start/try-it.md             |  30 +++--
 src/content/docs/tools/index.md              |  37 +----
 12 files changed, 248 insertions(+), 153 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index afb5d7c..a1609c5 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -6,6 +6,9 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   check:
     runs-on: ubuntu-latest
diff --git a/astro.config.mjs b/astro.config.mjs
index 64f05f6..8c3e9ef 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -12,7 +12,7 @@ export default defineConfig({
       title: "Plinth",
       description:
         "Open-source platform foundation for enterprise teams running fleets of internal-tooling modules.",
-      // Wordmark only — Plinth in Spectral Medium reads as a logo of its own.
+      // Wordmark only — "Plinth" in IBM Plex Sans reads as a logo of its own.
       // (No image logo file; Starlight falls back to the title text.)
       favicon: "/favicon.svg",
       social: [
@@ -26,9 +26,14 @@ export default defineConfig({
         baseUrl: "https://github.com/plinth-dev/docs/edit/main/",
       },
       lastUpdated: true,
-      // OG image lands in Phase F — until then no og:image meta is set
-      // (better than a 404'd image). Re-enable when /og.png ships.
+      // og:image lands with the default OG card in Wave 4 once huashu-design
+      // produces /og-default.png. Until then no og:image is set (better than
+      // a 404'd image).
       head: [
+        {
+          tag: "meta",
+          attrs: { name: "theme-color", content: "#FBFBF9" },
+        },
         {
           tag: "link",
           attrs: { rel: "preconnect", href: "https://fonts.googleapis.com" },
diff --git a/public/tools/sketch-app.html b/public/tools/sketch-app.html
index 48470b5..447891e 100644
--- a/public/tools/sketch-app.html
+++ b/public/tools/sketch-app.html
@@ -38,13 +38,14 @@
       overflow: hidden;
     }
     .toolbar {
-      height: var(--toolbar-h);
+      min-height: var(--toolbar-h);
       background: var(--bg-soft);
       border-bottom: 1px solid var(--rule);
       display: flex;
       align-items: center;
       gap: 12px;
-      padding: 0 16px;
+      padding: 6px 16px;
+      flex-wrap: wrap;
     }
     .toolbar .group { display: flex; align-items: center; gap: 6px; }
     .toolbar .group + .group {
@@ -52,6 +53,11 @@
       padding-left: 16px;
       border-left: 1px solid var(--rule-firm);
     }
+    @media (max-width: 56rem) {
+      .toolbar .group + .group {
+        margin-left: 0; padding-left: 0; border-left: none;
+      }
+    }
     .toolbar .lbl {
       font-family: var(--sans);
       font-size: 11px; font-weight: 600;
@@ -80,13 +86,19 @@
     }
     .toolbar .status .ok { color: var(--accent); }
     .toolbar .status .err { color: #B43A3A; }
+    .toolbar .status .ok::before { content: "●"; margin-right: 4px; }
+    .toolbar .status .err::before { content: "✕"; margin-right: 4px; font-weight: 700; }
+    .visually-hidden {
+      position: absolute; width: 1px; height: 1px; overflow: hidden;
+      clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap;
+    }
     .editor {
       display: grid;
       grid-template-columns: 480px 1fr;
       height: calc(100vh - var(--toolbar-h));
     }
     @media (max-width: 56rem) {
-      .editor { grid-template-columns: 1fr; }
+      .editor { grid-template-columns: 1fr; height: auto; }
       .pane-edit textarea { min-height: 280px; }
     }
     .pane-edit {
@@ -139,9 +151,11 @@
 </head>
 <body>
 
-  <div class="toolbar">
+  <h1 class="visually-hidden">Plinth Sketch — DSL editor for architecture diagrams</h1>
+
+  <div class="toolbar" role="toolbar" aria-label="Sketch tool actions">
     <div class="group">
-      <span class="lbl">Example</span>
+      <label class="lbl" for="example">Example</label>
       <select id="example">
         <option value="plinth">Plinth substrate (this site)</option>
         <option value="threetier">Three-tier web app</option>
@@ -153,15 +167,15 @@
       <button id="download-svg" class="primary">Download SVG</button>
       <button id="copy-link">Copy share link</button>
     </div>
-    <span class="status" id="status"><span class="ok">●</span> ready</span>
+    <span class="status" id="status" role="status" aria-live="polite" aria-atomic="true"><span class="ok">ready</span></span>
   </div>
 
-  <div class="editor">
+  <main class="editor">
     <section class="pane-edit" aria-label="DSL editor">
       <header class="header">
         Diagram source <span class="meta" id="lines">0 lines</span>
       </header>
-      <textarea id="src" spellcheck="false" autocomplete="off" autocorrect="off" aria-label="Diagram source DSL"></textarea>
+      <textarea id="src" spellcheck="false" autocomplete="off" autocorrect="off" aria-label="Diagram source DSL" autofocus></textarea>
     </section>
     <section class="pane-preview" aria-label="SVG preview">
       <header class="header">
@@ -171,9 +185,11 @@
         <span class="empty">Type something on the left to see a diagram.</span>
       </div>
     </section>
-  </div>
+  </main>
 
 <script type="module">
+// Pinned to a specific version so a server-side change doesn't surprise the
+// in-browser tool. Bump explicitly when @plinth-dev/sketch ships a new tag.
 import { parse, layout, render } from "https://esm.sh/@plinth-dev/sketch@0.1.0";
 
 const EXAMPLES = {
@@ -235,13 +251,7 @@
 api -> redis
 api -> s3
 `,
-  empty: `# Start typing.
-# Define nodes first, then group them into layers, then add edges.
-
-# @layer My layer
-# id : Label / optional sublabel
-# id_a -> id_b : edge label
-`,
+  empty: ``,
 };
 
 const $ = (s) => document.querySelector(s);
@@ -254,36 +264,63 @@
 
 let lastSVG = '';
 
+function setStatus(text, isErr) {
+  // Replace child nodes (not innerHTML) so SR doesn't over-announce.
+  const span = document.createElement('span');
+  span.className = isErr ? 'err' : 'ok';
+  span.textContent = text;
+  statusEl.replaceChildren(span);
+}
+
+function placeholder(msg) {
+  canvasEl.replaceChildren();
+  const s = document.createElement('span');
+  s.className = 'empty';
+  s.textContent = msg;
+  canvasEl.appendChild(s);
+}
+
 function update() {
   const text = srcEl.value;
   linesEl.textContent = `${text.split('\n').length} lines`;
   if (!text.trim()) {
-    canvasEl.innerHTML = '<span class="empty">Type something on the left to see a diagram.</span>';
+    placeholder('Type something on the left to see a diagram.');
     metaEl.textContent = '0 nodes · 0 edges';
-    statusEl.innerHTML = '<span class="ok">●</span> ready';
+    setStatus('ready', false);
+    lastSVG = '';
     return;
   }
   try {
     const parsed = parse(text);
+    metaEl.textContent = `${parsed.nodeOrder.length} nodes · ${parsed.edges.length} edges`;
+    if (parsed.nodeOrder.length === 0) {
+      placeholder('Define a node first — e.g. `web : Web tier`.');
+      lastSVG = '';
+      if (parsed.errors.length) {
+        setStatus(`${parsed.errors.length} unparsed line${parsed.errors.length === 1 ? '' : 's'}`, true);
+      } else {
+        setStatus('ready', false);
+      }
+      return;
+    }
     const lay = layout(parsed);
     const svg = render(parsed, lay);
     canvasEl.innerHTML = svg;
     lastSVG = svg;
-    metaEl.textContent = `${parsed.nodeOrder.length} nodes · ${parsed.edges.length} edges`;
     const missing = new Set();
     for (const e of parsed.edges) {
       if (!parsed.nodes[e.from]) missing.add(e.from);
       if (!parsed.nodes[e.to]) missing.add(e.to);
     }
     if (parsed.errors.length) {
-      statusEl.innerHTML = `<span class="err">●</span> ${parsed.errors.length} unparsed line${parsed.errors.length === 1 ? '' : 's'}`;
+      setStatus(`${parsed.errors.length} unparsed line${parsed.errors.length === 1 ? '' : 's'}`, true);
     } else if (missing.size) {
-      statusEl.innerHTML = `<span class="err">●</span> undefined node${missing.size === 1 ? '' : 's'}: ${[...missing].slice(0, 3).join(', ')}`;
+      setStatus(`undefined node${missing.size === 1 ? '' : 's'}: ${[...missing].slice(0, 3).join(', ')}`, true);
     } else {
-      statusEl.innerHTML = '<span class="ok">●</span> ok';
+      setStatus('ok', false);
     }
   } catch (err) {
-    statusEl.innerHTML = '<span class="err">●</span> ' + err.message;
+    setStatus(err.message, true);
   }
 }
 
@@ -297,11 +334,24 @@
 srcEl.addEventListener('input', () => { clearTimeout(timer); timer = setTimeout(update, 80); });
 
 function flashStatus(msg, isErr) {
-  const before = statusEl.innerHTML;
-  statusEl.innerHTML = (isErr ? '<span class="err">●</span> ' : '<span class="ok">●</span> ') + msg;
-  setTimeout(() => { statusEl.innerHTML = before; }, 1500);
+  const before = statusEl.cloneNode(true).childNodes;
+  setStatus(msg, !!isErr);
+  setTimeout(() => { statusEl.replaceChildren(...before); }, 1500);
+}
+
+// Convert byte array → base64 in 8K chunks so we don't blow the
+// String.fromCharCode call-stack limit on large DSLs.
+function bytesToBase64(bytes) {
+  const CHUNK = 8192;
+  let s = '';
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    s += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(s);
 }
 
+const MAX_DSL_BYTES = 64 * 1024; // 64 KB cap on share-links / hash decodes
+
 $('#download-svg').addEventListener('click', () => {
   if (!lastSVG) return;
   const blob = new Blob([lastSVG], { type: 'image/svg+xml' });
@@ -318,8 +368,13 @@
 });
 
 $('#copy-link').addEventListener('click', async () => {
-  const enc = btoa(String.fromCharCode(...new TextEncoder().encode(srcEl.value)));
-  // Build the canonical /tools/sketch/ URL even when iframed
+  const bytes = new TextEncoder().encode(srcEl.value);
+  if (bytes.length > MAX_DSL_BYTES) {
+    flashStatus('DSL too large to share-link', true);
+    return;
+  }
+  const enc = bytesToBase64(bytes);
+  // Build the canonical /tools/sketch/ URL even when iframed.
   const base = 'https://plinth.run/tools/sketch/';
   const url = base + '#d=' + enc;
   try { await navigator.clipboard.writeText(url); flashStatus('share link copied'); }
@@ -327,15 +382,22 @@
 });
 
 function loadFromHash() {
-  if (location.hash.startsWith('#d=')) {
-    try {
-      const bytes = Uint8Array.from(atob(location.hash.substring(3)), (c) => c.charCodeAt(0));
-      srcEl.value = new TextDecoder().decode(bytes);
-      update();
-      return true;
-    } catch (e) {}
+  if (!location.hash.startsWith('#d=')) return false;
+  const data = location.hash.substring(3);
+  // base64 expands ~4/3, so a 64KB DSL → ~85KB hash; reject larger.
+  if (data.length > MAX_DSL_BYTES * 2) {
+    flashStatus('share link malformed (too large)', true);
+    return false;
+  }
+  try {
+    const bytes = Uint8Array.from(atob(data), (c) => c.charCodeAt(0));
+    srcEl.value = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    update();
+    return true;
+  } catch (e) {
+    flashStatus('share link malformed', true);
+    return false;
   }
-  return false;
 }
 
 if (!loadFromHash()) loadExample('plinth');
diff --git a/src/assets/theme.css b/src/assets/theme.css
index 5dcf959..9727e5b 100644
--- a/src/assets/theme.css
+++ b/src/assets/theme.css
@@ -8,7 +8,7 @@
 :root {
   --sl-font: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, sans-serif;
   --sl-font-system: var(--sl-font);
-  --sl-font-system-mono: "JetBrains Mono", "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  --sl-font-system-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
 
   --sl-content-width: 60rem;
   --sl-line-height: 1.55;
diff --git a/src/components/IFrameTool.astro b/src/components/IFrameTool.astro
index 9b39c39..f1a1425 100644
--- a/src/components/IFrameTool.astro
+++ b/src/components/IFrameTool.astro
@@ -1,7 +1,8 @@
 ---
 // Embeds an interactive tool (an HTML file in /public/) inside a Starlight page.
-// The iframe takes the full content width and a tall fixed height; on small
-// viewports we collapse the height so it remains usable.
+// Same-origin; we don't add `sandbox=` because allow-scripts + allow-same-origin
+// together negates the sandbox (and Chromium warns about it). If we ever host
+// tools on a separate origin, drop allow-same-origin and add a real sandbox.
 interface Props {
   src: string;
   title: string;
@@ -16,18 +17,58 @@ const { src, title, height = "min(78vh, 760px)" } = Astro.props as Props;
     title={title}
     style={`height: ${height}`}
     loading="lazy"
-    sandbox="allow-scripts allow-same-origin allow-downloads"
   ></iframe>
 </div>
 
+<script is:inline>
+  // (1) Forward the parent's URL hash into the iframe so /tools/sketch/#d=<b64>
+  //     share links route the encoded DSL into the embedded tool.
+  // (2) Full-bleed the iframe by measuring the parent's left offset on each
+  //     resize. CSS-only `100vw + calc(50% - 50vw)` misaligns when the parent
+  //     is left-anchored (Starlight splash template), so we measure instead.
+  (function () {
+    function applyHash() {
+      if (!location.hash) return;
+      const f = document.querySelector(".iframe-tool iframe");
+      if (!f) return;
+      const u = new URL(f.getAttribute("src"), location.origin);
+      u.hash = location.hash;
+      f.setAttribute("src", u.toString());
+    }
+    function applyBleed() {
+      const els = document.querySelectorAll(".iframe-tool");
+      els.forEach(function (el) {
+        // Reset first so the measurement reflects the un-bled position.
+        el.style.marginLeft = "";
+        el.style.marginRight = "";
+        el.style.width = "";
+        const r = el.getBoundingClientRect();
+        const left = r.left;
+        const right = window.innerWidth - r.right;
+        el.style.marginLeft = -left + "px";
+        el.style.marginRight = -right + "px";
+        el.style.width = window.innerWidth + "px";
+      });
+    }
+    function init() {
+      applyHash();
+      applyBleed();
+    }
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", init, { once: true });
+    } else {
+      init();
+    }
+    window.addEventListener("resize", applyBleed);
+  })();
+</script>
+
 <style>
-  /* Break the iframe out of Starlight's content max-width so the tool gets a
-     wider area. Standard "full bleed" technique: width 100vw + negative
-     margin-left/right that compensates for the parent's offset. */
+  /* Default to content width; the inline script widens to viewport on
+     load + resize. (No CSS-only trick survives Starlight's splash template
+     which anchors content to a left column rather than centering it.) */
   .iframe-tool {
-    width: 100vw;
-    margin-left: calc(50% - 50vw);
-    margin-right: calc(50% - 50vw);
+    width: 100%;
     margin-top: 2.5rem;
     margin-bottom: 2.5rem;
     background: var(--sl-color-bg);
diff --git a/src/content/docs/architecture.md b/src/content/docs/architecture.md
index 7b2759a..f8ea5f1 100644
--- a/src/content/docs/architecture.md
+++ b/src/content/docs/architecture.md
@@ -1,6 +1,6 @@
 ---
-title: Bank-Grade Platform Architecture
-description: A reference architecture for enterprise teams running internal-tooling fleets on open-source, on-premise infrastructure.
+title: Reference architecture for bank-grade internal-tooling fleets
+description: A reference architecture for enterprise teams running internal-tooling fleets on open-source, on-premise infrastructure. Describes a v1.0 target; not all sections ship in Plinth v0.1.0.
 sidebar:
   label: Overview
   order: 1
@@ -9,6 +9,10 @@ tableOfContents:
   maxHeadingLevel: 3
 ---
 
+:::note[v0.1.0 vs this document]
+This document describes the *v1.0 target* — the system you'd build if you were standing up a bank-grade internal platform from scratch. **Plinth v0.1.0 implements §14 (Cerbos), §20 (CloudNativePG), §25 (OpenTelemetry) end-to-end; the substrate chart and SDKs reference this architecture, not the whole of it.** The [v0.1.0 launch page](/launch/v0-1-0/) lists what ships today.
+:::
+
 ## How to read this document
 
 A reference for organisations standing up an **internal application platform** — a fleet of related modules that share authentication, authorisation, observability, audit, and deployment infrastructure. The patterns described are what you'd choose if you were starting fresh today, with banking-grade defaults and an open-source budget. Audience: platform engineering leads, infrastructure engineers, information security, compliance, and application developers.
@@ -124,7 +128,7 @@ The paired starter kits — [`starter-web`](https://github.com/plinth-dev/starte
 
 ---
 
-# Part I — Foundations
+## Part I — Foundations
 
 ## 1. Executive summary
 
@@ -202,23 +206,13 @@ The starter kits paired with this document close every item above explicitly.
 
 ## 4. Design principles
 
-These six principles govern every choice in this document. Where a section deviates from one, the deviation is named explicitly.
-
-1. **Zero standing trust.** No human or service has ambient privileges. Identity is established per request (users via the gateway, services via SPIFFE/mTLS). Secrets are time-bounded; admin actions are audited; production access is just-in-time.
-
-2. **GitOps everything.** The state of the platform is the state of git. A reconciler agent (Argo CD) applies the repo to the cluster; humans don't `kubectl apply`. Every change is reviewed in a PR, recorded in audit, reversible by `git revert`.
-
-3. **Immutable infrastructure.** Nodes are not patched; they are replaced. Cluster nodes have no SSH and no shell; configuration is declarative. Container images are built once, signed, and never mutated in flight.
-
-4. **Durable workflows.** Long-running, multi-step business processes (approvals, integrations, scheduled jobs) live in Temporal — not in cron + database tables. Code is the source of truth; correctness is testable.
-
-5. **Evidence by default.** Audit, traces, logs, metrics, and policy decisions are emitted from every component without per-module effort. The platform produces compliance evidence as a side effect of running.
+The six commitments are stated normatively in the [manifesto](/manifesto/) — *zero standing trust*, *GitOps everything*, *immutable infrastructure*, *durable workflows*, *evidence by default*, *open source first*. They are the contract; this document is the *how*.
 
-6. **Open source first.** Every choice in this document is permissively licensed open source. The platform must be operable indefinitely without recurring vendor cost. Commercial support is welcome but optional.
+Where a section deviates from one, the deviation is named explicitly in that section.
 
 ---
 
-# Part II — Reference Architecture
+## Part II — Reference Architecture
 
 ## 5. Logical architecture overview
 
@@ -503,7 +497,7 @@ External traffic terminates at the perimeter firewall, which forwards to a pool
 
 ---
 
-# Part III — Identity, Authorization, Secrets, PKI
+## Part III — Identity, Authorization, Secrets, PKI
 
 ## 13. Identity — Ory stack
 
@@ -637,7 +631,7 @@ The combined model means: a misconfigured pod that ends up in the wrong namespac
 
 ---
 
-# Part IV — Application Platform
+## Part IV — Application Platform
 
 ## 18. Workflow engine — Temporal
 
@@ -780,13 +774,13 @@ Decisions:
 
 ---
 
-# Part V — Observability and Audit
+## Part V — Observability and Audit
 
 ## 25. OpenTelemetry instrumentation standard
 
 Every module emits **OTLP** (OpenTelemetry Protocol) telemetry from day one — traces, metrics, logs. The starter kits wire the SDKs; module authors do not opt in.
 
-- **Backend (Go)**: `go.opentelemetry.io/otel` SDK; auto-instrumentation for Fiber, GORM, gRPC, HTTP clients.
+- **Backend (Go)**: `go.opentelemetry.io/otel` SDK; auto-instrumentation for chi, pgx, gRPC, HTTP clients.
 - **Frontend (Next.js)**: `@opentelemetry/sdk-trace-web` + `@vercel/otel` for server actions; browser-side traces ship to a public collector endpoint behind Oathkeeper.
 - **Collector**: an **OpenTelemetry Collector** deployment per cluster, deployed as a DaemonSet (for node-local low-latency receive) plus a gateway tier (for processing/batching/routing).
 
@@ -966,7 +960,7 @@ Policies live in a `k8s-policies` repo; CI tests them on a kind cluster; Argo CD
 
 ---
 
-# Part VI — Developer Experience
+## Part VI — Developer Experience
 
 ## 37. Source control — GitLab CE
 
@@ -1190,7 +1184,7 @@ ADRs follow the **Michael Nygard** format: Context, Decision, Status, Consequenc
 
 ---
 
-# Part VII — The starter kits
+## Part VII — The starter kits
 
 ## 45. Frontend — `starter-web`
 
@@ -1234,22 +1228,23 @@ A Next.js 16 + React 19 module template that ships every pattern an enterprise t
 
 ## 46. Backend — `starter-api`
 
-Go 1.23 + Fiber v2, structured for an enterprise-grade module.
+Go 1.25 + chi, structured for an enterprise-grade module. (The shipped `starter-api` repo wires every Plinth Go SDK package into one working service.)
 
 ### 46.1 Stack
 
 | Layer | Choice |
 | --- | --- |
-| Language | Go 1.23 |
-| HTTP | Fiber v2 |
-| ORM | sqlc + pgx (no GORM, no AutoMigrate) |
+| Language | Go 1.25 |
+| HTTP | chi |
+| Database | sqlc + pgx (no GORM, no AutoMigrate) |
 | Migrations | golang-migrate |
 | Validation | go-playground/validator |
-| Logger | zerolog |
-| Errors | custom `apperrors` package + RFC 7807 problem+json |
-| Workflow | Temporal Go SDK |
-| Cerbos | shared `cerbosclient` lib |
-| OTel | `go.opentelemetry.io/otel` |
+| Logger | log/slog (stdlib) with JSON handler |
+| Errors | `sdk-go/errors` + RFC 7807 problem+json |
+| Workflow | Temporal Go SDK *(v1.0 target — not in v0.1.0)* |
+| Cerbos | `sdk-go/authz` |
+| OTel | `sdk-go/otel` |
+| Audit | `sdk-go/audit` |
 | Test (unit) | go test |
 | Test (integration) | testcontainers-go |
 | API spec | swaggo OpenAPI generation |
@@ -1327,7 +1322,7 @@ CI publishes a signed bundle to MinIO. Argo CD watches the bundle reference; Cer
 
 ---
 
-# Part VIII — Compliance and Operations
+## Part VIII — Compliance and Operations
 
 ## 49. Compliance mapping
 
@@ -1439,7 +1434,7 @@ Rotation jobs are Temporal workflows in a **`platform-rotation`** module — dur
 
 ---
 
-# Part IX — Roadmap
+## Part IX — Roadmap
 
 A 28-week plan in five phases. Phases overlap where dependencies allow; the roadmap below shows critical-path durations.
 
@@ -1562,7 +1557,7 @@ A 28-week plan in five phases. Phases overlap where dependencies allow; the road
 
 ---
 
-# Part X — Diagrams
+## Part X — Diagrams
 
 The diagrams below are reference Mermaid sources. Animated equivalents appear in `explorer.html`. Source `.mmd` files are in the `diagrams/` subdirectory and lint-checked in CI.
 
diff --git a/src/content/docs/examples/access-requests.md b/src/content/docs/examples/access-requests.md
index 35494e5..bfda51f 100644
--- a/src/content/docs/examples/access-requests.md
+++ b/src/content/docs/examples/access-requests.md
@@ -10,6 +10,10 @@ A working internal-tool that demonstrates the full Plinth stack on the canonical
 
 **Source:** [github.com/plinth-dev/example-access-requests](https://github.com/plinth-dev/example-access-requests).
 
+:::note[What this example fakes for the walkthrough]
+The example uses a **dev cookie shim** for identity (sign in as `alice`, `bob`, etc.) so it stands up on a fresh `kind` cluster without an external IdP. In production the same SDK calls sit behind Authentik / Ory Kratos via Oathkeeper — the *application code does not change*; only the upstream issuer does. See §13 of the [architecture doc](/architecture/) for the production path.
+:::
+
 ## What you'll see
 
 | Surface | Plinth SDK |
diff --git a/src/content/docs/index.md b/src/content/docs/index.md
index 9b01900..ef108d6 100644
--- a/src/content/docs/index.md
+++ b/src/content/docs/index.md
@@ -1,6 +1,6 @@
 ---
-title: Plinth
-description: An open-source platform foundation for organisations running fleets of internal-tooling modules at regulated companies.
+title: A platform foundation for internal-tooling fleets
+description: An open-source platform foundation for organisations running fleets of internal-tooling modules at regulated companies — banks, insurers, healthcare, government.
 template: splash
 hero:
   title: |
diff --git a/src/content/docs/launch/v0-1-0.md b/src/content/docs/launch/v0-1-0.md
index 8bb8090..40e5a4e 100644
--- a/src/content/docs/launch/v0-1-0.md
+++ b/src/content/docs/launch/v0-1-0.md
@@ -1,6 +1,6 @@
 ---
-title: Plinth v0.1.0 — bank-grade foundation for internal-tooling fleets
-description: A substrate, a 14-package SDK, two starters, a CLI, a Backstage scaffolder, and a worked example. Five months of solo work, all open-source, all stable.
+title: Plinth v0.1.0 — first SDK release
+description: A 14-package SDK, two starters, a CLI, a Backstage scaffolder, a walking-skeleton substrate chart, and a worked example. Five months of solo work, all open-source, all stable.
 sidebar:
   hidden: true
 ---
@@ -9,7 +9,7 @@ sidebar:
 
 If you run a fleet of internal applications — change requests, audit dashboards, HR tooling, account-access workflows, the long tail — you've watched every module re-implement the same plumbing: identity, authorization, audit, observability, deployment. You've also watched every module inherit the same gaps: a session secret committed in `.env.example`, an authorization layer that fails open in dev mode, no real healthcheck, no error boundaries, no centralised logs.
 
-Plinth is the platform foundation those modules should have stood on from day one. Today is v0.1.0 — the first stable release. Everything below works, has tests, has docs, and is on a public registry you can install from right now.
+Plinth is the platform foundation those modules should have stood on from day one. Today is v0.1.0 — the first stable release. **The Go and TypeScript SDKs are on public registries you can install from right now; the substrate Helm chart you build from source.**
 
 ## Six commitments
 
@@ -25,12 +25,12 @@ If those don't match how you'd build internal tooling at a regulated org, save y
 | [`sdk-ts`](https://github.com/plinth-dev/sdk-ts) | 7 TypeScript packages: `env`, `api-client`, `authz`, `authz-react`, `forms`, `otel-web`, `tables` | `pnpm add @plinth-dev/<pkg>` |
 | [`starter-api`](https://github.com/plinth-dev/starter-api) | Go 1.25 + chi + pgx, every SDK wired into one working service | `git clone` |
 | [`starter-web`](https://github.com/plinth-dev/starter-web) | Next.js 16 + React 19, every TS SDK wired into one working app | `git clone` |
-| [`cli`](https://github.com/plinth-dev/cli) | `plinth new <name>` to scaffold both starters with renamed identifiers | `go install github.com/plinth-dev/cli/cmd/plinth@v0.1.1` |
+| [`cli`](https://github.com/plinth-dev/cli) | `plinth new <name>` to scaffold both starters with renamed identifiers | `go install github.com/plinth-dev/cli/cmd/plinth@latest` |
 | [`scaffolder`](https://github.com/plinth-dev/scaffolder) | Backstage software template + custom action emitting the same output | `pnpm add @plinth-dev/scaffolder-actions` |
 | [`platform`](https://github.com/plinth-dev/platform) | Helm umbrella chart — CloudNativePG + Cerbos + OTel Collector | `git clone && helm install` |
 | [`example-access-requests`](https://github.com/plinth-dev/example-access-requests) | Working internal tool: temp-prod-access requests with approver workflow | `git clone` |
 
-Total: nine repos, all MIT-licensed, all v0.1.0 stable, all CI-green, all docs-complete.
+Total: nine repos, MIT-licensed, tagged v0.1.x, CI-green on `main`. SDKs on public registries; CLI bumped to v0.1.1 for an early bug-fix; platform chart from source today.
 
 API contracts are frozen for the 0.x line. Breaking changes batch into 0.2.0; v1.0 locks the API across major versions.
 
@@ -38,7 +38,7 @@ API contracts are frozen for the 0.x line. Breaking changes batch into 0.2.0; v1
 
 ```bash
 # Scaffold a fully-wired Plinth module pair
-go install github.com/plinth-dev/cli/cmd/plinth@v0.1.1
+go install github.com/plinth-dev/cli/cmd/plinth@latest
 plinth new billing --module-path github.com/acme/billing-api
 
 # Or read a real working example end-to-end
diff --git a/src/content/docs/sdk/index.md b/src/content/docs/sdk/index.md
index bfda179..0a8b792 100644
--- a/src/content/docs/sdk/index.md
+++ b/src/content/docs/sdk/index.md
@@ -10,27 +10,31 @@ The Plinth SDK is two language families that encode the platform contracts. Modu
 
 ## Go — `github.com/plinth-dev/sdk-go/*`
 
-| Package | Responsibility |
-| --- | --- |
-| [`authz`](/sdk/go/authz/) | Cerbos PDP client wrapper with explicit `Decision` and fail-closed semantics. |
-| [`errors`](/sdk/go/errors/) | Typed error vocabulary; sentinel errors via `errors.Is`; RFC 7807 mapping. |
-| [`audit`](/sdk/go/audit/) | Emit CloudEvents-shaped audit events to a pluggable transport (NATS by default). Non-blocking. |
-| [`health`](/sdk/go/health/) | Dependency probe registry with parallel execution and per-dep status JSON. |
-| [`otel`](/sdk/go/otel/) | OpenTelemetry SDK initialisation with standard resource attributes. |
-| [`paginate`](/sdk/go/paginate/) | Cursor + offset pagination types and parsers; allow-list-based sort safety. |
-| [`vault`](/sdk/go/vault/) | Secret reader: `/run/secrets/<name>` first, env var fallback, in-memory cache. |
+All seven packages are tagged `v0.1.0` and importable today via `go get github.com/plinth-dev/sdk-go/<pkg>@v0.1.0`.
+
+| Package | Status | Responsibility |
+| --- | --- | --- |
+| [`authz`](/sdk/go/authz/) | *v0.1.0* | Cerbos PDP client wrapper with explicit `Decision` and fail-closed semantics. |
+| [`errors`](/sdk/go/errors/) | *v0.1.0* | Typed error vocabulary; sentinel errors via `errors.Is`; RFC 7807 mapping. |
+| [`audit`](/sdk/go/audit/) | *v0.1.0* | Emit CloudEvents-shaped audit events to a pluggable transport (NATS by default). Non-blocking. |
+| [`health`](/sdk/go/health/) | *v0.1.0* | Dependency probe registry with parallel execution and per-dep status JSON. |
+| [`otel`](/sdk/go/otel/) | *v0.1.0* | OpenTelemetry SDK initialisation with standard resource attributes. |
+| [`paginate`](/sdk/go/paginate/) | *v0.1.0* | Cursor + offset pagination types and parsers; allow-list-based sort safety. |
+| [`vault`](/sdk/go/vault/) | *v0.1.0* | Secret reader: `/run/secrets/<name>` first, env var fallback, in-memory cache. |
 
 ## TypeScript — `@plinth-dev/*`
 
-| Package | Responsibility |
-| --- | --- |
-| [`authz`](/sdk/ts/authz/) | Server-only Cerbos gRPC wrapper; mirrors the Go SDK semantics. |
-| [`authz-react`](/sdk/ts/authz-react/) | React `<PermissionsProvider>` + `usePermissions()` + `<Can>`; batched-check-at-layout pattern. |
-| [`api-client`](/sdk/ts/api-client/) | Typed server-only fetch wrapper; never throws on HTTP errors; retries on 5xx/429. |
-| [`forms`](/sdk/ts/forms/) | Server-action forms with Zod validation; `<FormWrapper>` + `<FormField>`. |
-| [`tables`](/sdk/ts/tables/) | Headless data tables with URL state via `nuqs`. |
-| [`otel-web`](/sdk/ts/otel-web/) | Browser OpenTelemetry SDK init with auto-instrumentations. |
-| [`env`](/sdk/ts/env/) | Zod-schema-validated env vars; fail-fast at module load. |
+All seven packages are published to npm at `0.1.0` and installable via `pnpm add @plinth-dev/<pkg>`.
+
+| Package | Status | Responsibility |
+| --- | --- | --- |
+| [`authz`](/sdk/ts/authz/) | *0.1.0 on npm* | Server-only Cerbos gRPC wrapper; mirrors the Go SDK semantics. |
+| [`authz-react`](/sdk/ts/authz-react/) | *0.1.0 on npm* | React `<PermissionsProvider>` + `usePermissions()` + `<Can>`; batched-check-at-layout pattern. |
+| [`api-client`](/sdk/ts/api-client/) | *0.1.0 on npm* | Typed server-only fetch wrapper; never throws on HTTP errors; retries on 5xx/429. |
+| [`forms`](/sdk/ts/forms/) | *0.1.0 on npm* | Server-action forms with Zod validation; `<FormWrapper>` + `<FormField>`. |
+| [`tables`](/sdk/ts/tables/) | *0.1.0 on npm* | Headless data tables with URL state via `nuqs`. |
+| [`otel-web`](/sdk/ts/otel-web/) | *0.1.0 on npm* | Browser OpenTelemetry SDK init with auto-instrumentations. |
+| [`env`](/sdk/ts/env/) | *0.1.0 on npm* | Zod-schema-validated env vars; fail-fast at module load. |
 
 ## Where to start
 
@@ -40,4 +44,4 @@ The four most load-bearing packages — read these first if you only read four:
 - [`@plinth-dev/authz-react`](/sdk/ts/authz-react/) — the client-side companion (batched-check-at-layout)
 - [`sdk-go/errors`](/sdk/go/errors/) — the wire-stable error vocabulary every backend speaks
 
-Implementation lands per-package, semver-tagged starting `v0.1.0`. See the [roadmap](https://github.com/plinth-dev/.github/blob/main/ROADMAP.md) for the current state.
+API contracts are frozen for the 0.x line; breaking changes batch into 0.2.0. See the [v0.1.0 launch](/launch/v0-1-0/) for a full ship list.
diff --git a/src/content/docs/start/try-it.md b/src/content/docs/start/try-it.md
index 6089dbe..b613c23 100644
--- a/src/content/docs/start/try-it.md
+++ b/src/content/docs/start/try-it.md
@@ -3,11 +3,11 @@ title: Stand it up in an afternoon
 description: Stand up the Plinth substrate on a fresh kind cluster, generate a module, and watch it deploy.
 ---
 
-:::note
-The `helm install` step below describes the target flow. The platform chart is not yet published; track current status on the [roadmap](https://github.com/plinth-dev/.github/blob/main/ROADMAP.md).
+:::caution[v0.1.0 status]
+The platform chart is *not yet on a registry*. Today you build it from source as shown below. The `helm install oci://…` and Argo-CD reconcile flow are the *v1.0 target*; track progress on the [roadmap](https://github.com/plinth-dev/.github/blob/main/ROADMAP.md).
 :::
 
-Prerequisites: Docker, `kubectl`, `helm`, `kind` (or any Kubernetes cluster you already trust).
+Prerequisites: Docker, `kubectl`, `helm`, `kind` (or any Kubernetes cluster you already trust), `git`, `go` (1.25+).
 
 ## 1. Read
 
@@ -17,32 +17,36 @@ Skim the [manifesto](/manifesto/) (5 minutes) and the [architecture overview](/a
 
 ```bash
 kind create cluster --name plinth
-helm install plinth oci://ghcr.io/plinth-dev/platform --values dev.values.yaml
+git clone https://github.com/plinth-dev/platform
+cd platform
+helm dependency update charts/plinth
+helm install plinth charts/plinth --values charts/plinth/values-dev.yaml
 ```
 
-The dev profile spins up a single-node cluster with HA disabled. It's not production-shaped — it's the fastest way to see everything wired together.
+The dev profile spins up a single-node cluster with HA disabled. It's not production-shaped — it's the fastest way to see CloudNativePG + Cerbos + the OpenTelemetry Collector wired together. (Vault, Authentik, Argo CD, the rest of the substrate land incrementally — see *what's not here* below.)
 
-When `helm install` finishes, Argo CD reconciles the rest. Wait for `kubectl get applications -n argocd` to settle.
+Wait for `kubectl get pods -A` to settle.
 
 ## 3. Generate a module
 
 ```bash
-brew install plinth-dev/tap/plinth   # or: go install github.com/plinth-dev/cli@latest
+go install github.com/plinth-dev/cli/cmd/plinth@latest
 plinth new my-module --web --api --owner=me
 ```
 
-The CLI clones the starters, renames everything, and (with `--gitlab-push` and `--open-mrs`) opens MRs against the GitOps and policies repos.
+The CLI clones the starters, renames identifiers consistently across both, and writes a `.plinth.yaml` capturing the choices. (`--gitlab-push` / `--open-mrs` for GitOps + policy MRs are *v1.0 target* flags; today the new module is local.)
 
-## 4. See it deployed
+## 4. Deploy your module
 
 ```bash
-open http://argo.localhost           # Argo CD shows my-module syncing
-open http://my-module.localhost      # the module's dashboard
+cd my-module-api && make deploy   # Makefile targets in the starters
 ```
 
-You should see your module reconcile in Argo, then come up at its hostname with auth, audit, OTel, and security headers already wired.
+Every module comes up with `/healthz`, `/readyz`, structured-JSON logs, OpenTelemetry traces (sent to the Collector from step 2), Cerbos-fail-closed authorization, and RFC 7807 error responses already wired.
 
 ## What's not here
 
-- **Production hardening.** The dev profile turns off HA, replicas, network policies, and a chunk of Wazuh / Falco rules. The `prod` profile is what you actually deploy. See [architecture](/architecture/) for the full posture.
+- **Argo CD reconciliation.** The launch v0.1.0 chart deploys directly via Helm. Argo CD app-of-apps lands incrementally toward v1.0.
+- **Identity provider.** Authentik / Ory Kratos integration is *roadmapped*. v0.1.0 starters use a dev cookie shim — fine for the walkthrough, not for shipping.
+- **Production hardening.** The dev profile turns off HA, replicas, network policies. The `prod` profile is what you actually deploy when those substrate components ship. See [architecture](/architecture/) for the full posture.
 - **Bare metal.** The Talos bootstrap path is documented separately; the platform chart targets `kind` first, with bare-metal hardening as a follow-on.
diff --git a/src/content/docs/tools/index.md b/src/content/docs/tools/index.md
index 483fb6b..585acd9 100644
--- a/src/content/docs/tools/index.md
+++ b/src/content/docs/tools/index.md
@@ -8,46 +8,23 @@ sidebar:
 
 Free utilities for working with Plinth and the adjacent stacks Plinth integrates — Cerbos, OpenTelemetry, CloudEvents, Helm, RFC&nbsp;7807. No signup. No tracking. Each tool's source is on GitHub. Each tool's URL is bookmarkable and shareable.
 
-## Diagrams &amp; visualisation
+## [Plinth Sketch](/tools/sketch/) — *live*
 
-### [Sketch](/tools/sketch/) — *live*
-
-A visual + DSL editor for system architecture diagrams. Type a few lines of plain text — components, edges, layers — get a typeset SVG matching this site's design language. Share via URL. Export PNG / SVG / embed iframe. Available as a [CLI + GitHub Action](https://github.com/plinth-dev/sketch) so you can render diagrams at build time and embed them in any README.
-
-> **Use instead of** Mermaid (default chrome reads as utility), draw.io (overkill), Excalidraw (looks amateur), screenshotting Whimsical.
+A visual + DSL editor for system architecture diagrams. Type a few lines of plain text — components, edges, layers — get a typeset SVG matching this site's design language. Share via URL. Available as a [CLI + GitHub Action](https://github.com/plinth-dev/sketch) so you can render diagrams at build time and embed them in any README.
 
 ```bash
 npm install -g @plinth-dev/sketch
 plinth-sketch architecture.sketch -o architecture.svg
 ```
 
-### Module Preview — *coming soon*
-
-Type a `plinth new` command and see the resulting file tree, dependency graph, and SDK surface area in the browser before installing.
-
-## Configuration builders
-
-### OTel Config — *coming soon*
-
-Drag-and-drop builder for OpenTelemetry Collector configurations. Pick receivers, processors, exporters from a catalog; outputs full YAML. Imports existing configs to validate. Targets: Tempo, Jaeger, SigNoz, Honeycomb, Datadog, vendor-neutral OTLP.
-
-### Values Diff — *coming soon*
-
-Paste two Helm `values.yaml` files; see a semantic diff with schema validation against the Plinth platform chart.
-
-## Validators &amp; explorers
-
-### Audit Explorer — *coming soon*
-
-Paste CloudEvents JSON-lines; validate against the 1.0 spec; render as a queryable timeline. See what Plinth's audit module emits before adopting it.
-
-### Problem Builder — *coming soon*
+The diagram on the [v0.1.0 launch page](/launch/v0-1-0/) and elsewhere on this site is rendered with this tool from a 22-line `.sketch` file.
 
-Visual builder for RFC 7807 Problem Details JSON. Validates trace + extension fields. Generates copy-paste code for `sdk-go/errors` and `@plinth-dev/api-client`.
+## On the way
 
-### Cerbos Lint — *coming soon*
+Two more tools are in active development. They land when they're worth a reader's time, not before.
 
-Paste a Cerbos policy; check syntax against the v1 schema; simulate decisions against principals you define inline.
+- **OTel Config Builder** — drag-and-drop builder for OpenTelemetry Collector configurations. Pick receivers, processors, exporters from a catalog; outputs full YAML. Targets: Tempo, Jaeger, SigNoz, Honeycomb, Datadog, vendor-neutral OTLP.
+- **CloudEvents Validator** — paste CloudEvents JSON-lines; validate against the 1.0 spec; render as a queryable timeline. See what Plinth's audit module emits before adopting it.
 
 ---