From 05bfbc0cd8660d086782a19c73bbd30091307b28 Mon Sep 17 00:00:00 2001
From: dirtydishes <dishes@dpdrm.com>
Date: Tue, 26 May 2026 01:11:52 -0400
Subject: [PATCH] add turn doc template guidance

---
 AGENTS.md                |  15 +-
 CLAUDE.md                |   8 +-
 docs/turns/template.html | 319 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 337 insertions(+), 5 deletions(-)
 create mode 100644 docs/turns/template.html

diff --git a/AGENTS.md b/AGENTS.md
index cd1e980..334aa68 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -133,6 +133,8 @@ If a change does not cleanly fit either exempt or substantive buckets, ask the u
 
 Use the `impeccable` skill to structure and style the document as clean, readable HTML. For this repository, `impeccable` is the styling and layout authority for turn documents when available. Do not apply global non-repo computer-task house styling to repository turn documents.
 
+Future turn documents must start from `docs/turns/template.html`. The template is the canonical appearance baseline for this repository: dark polished layout, lavender and pink accent colors, compact header metadata, clear section rhythm, and contained diff shells modeled after `/Users/kell/dev/islandflow/docs/turns/2026-05-20-fix-alert-flow-packet-history.html`.
+
 If `impeccable` is unavailable or blocked by an actual tool/file error, still create a well-structured standalone HTML file.
 
 Each turn document must include these sections:
@@ -157,7 +159,7 @@ For a minor update to a previous substantive change, add this section to the exi
 
 ### Rendered Diff Documentation
 
-When turn documentation needs rendered code diffs, use `@pierre/diffs` through its ESM server-side renderer.
+When turn documentation needs rendered code diffs, use Clean SSR with `@pierre/diffs` through its ESM server-side renderer. The final HTML must be readable as a static file and must not depend on client-side package loading.
 
 Use `@pierre/diffs/ssr` with Node ESM imports. Do not test, load, or diagnose this package with CommonJS `require()`, because `@pierre/diffs` is ESM and `require('@pierre/diffs/ssr')` can falsely look like an export or package failure.
 
@@ -188,7 +190,16 @@ NODE
 
 Do not run `npx @pierre/diffs`; the package is a rendering library and does not expose a CLI executable.
 
-Only use a clearly labeled plain diff or code-block fallback when the ESM import-and-render pattern above fails because of a real tool, install, or runtime error. Document the failure briefly in the turn document.
+Diff output must follow these readability rules:
+
+- Use curated, relevant snippets rather than dumping an entire commit or full-file diff when a focused snippet explains the change.
+- Render one file diff per `.diff-shell`, with a clear `.diff-title` naming the file and purpose.
+- Insert generated SSR HTML only inside the matching `.diff-view` element from `docs/turns/template.html`.
+- Never paste generated SSR output as a freestanding section body or outside the diff shell.
+- Keep normal prose sections around the generated markup so the source and rendered page remain navigable.
+- Mark a shell with `class="diff-shell rendered"` when SSR output is present so the fallback is hidden.
+
+Only use a clearly labeled plain diff or code-block fallback in the template's `<pre class="diff-fallback">` block when the ESM import-and-render pattern above fails because of a real tool, install, or runtime error. Document the failure briefly in the turn document.
 
 ## Plan Mode Documentation
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 633878c..69c2703 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,7 +112,7 @@ Use this decision order before creating a turn document:
 
 The minor/trivial exemptions override the general mandatory turn-document rule.
 
-For diff content in turn documentation (including "Code diffs" and "Relevant Diff Snippets"), use `@pierre/diffs` output by default. Do not run `npx @pierre/diffs`; the package is a rendering library and does not expose a CLI executable. Generate rendered diff HTML with `@pierre/diffs/ssr`, usually `preloadPatchDiff`, and insert that rendered output into the turn document. `preloadPatchDiff` expects exactly one file diff per call, so split multi-file diffs into one patch per file and concatenate the rendered HTML. If `@pierre/diffs/ssr` is unavailable because of a real tool or blocking error, use a clearly labeled plain diff/code block fallback and note why.
+For diff content in turn documentation (including "Code diffs" and "Relevant Diff Snippets"), use Clean SSR with `@pierre/diffs` output by default. Do not run `npx @pierre/diffs`; the package is a rendering library and does not expose a CLI executable. Generate rendered diff HTML with `@pierre/diffs/ssr`, usually `preloadPatchDiff`, and insert that rendered output only inside a `.diff-view` element within a `.diff-shell` from `docs/turns/template.html`. `preloadPatchDiff` expects exactly one file diff per call, so split multi-file diffs into one patch per file and render one shell per file. Use curated, relevant snippets rather than dumping an entire commit or full-file diff when a focused snippet explains the change. If `@pierre/diffs/ssr` is unavailable because of a real tool or blocking error, use the template's clearly labeled plain fallback diff block and note why.
 
 ### No turn document for minor/trivial checklist matches
 
@@ -132,7 +132,7 @@ If a change does not cleanly fit either exempt or substantive buckets, ask the u
 **"New Changes as of {time and date at which the change was made}"**
 - **Summary of changes**
 - **Why this change was made**
-- **Code diffs** (use rendered `@pierre/diffs/ssr` output by default; do not use `npx @pierre/diffs`; if unavailable, include a clearly labeled plain diff/code block and note why)
+- **Code diffs** (use Clean SSR `@pierre/diffs/ssr` output inside the template's `.diff-view` by default; do not use `npx @pierre/diffs`; if unavailable, include a clearly labeled plain fallback diff block and note why)
 - **Related issues or PRs**
 
 Additionally, add a note to each section explaining why the changes were made.
@@ -163,6 +163,8 @@ Use the `impeccable` skill to structure and style the document as clean, readabl
 
 For this repository, `impeccable` is the styling and layout authority for turn documents when available. Do not apply global non-repo computer-task house styling to repository turn documents.
 
+Future turn documents must start from `docs/turns/template.html`. The template is the canonical appearance baseline for this repository: dark polished layout, lavender and pink accent colors, compact header metadata, clear section rhythm, and contained diff shells modeled after `/Users/kell/dev/islandflow/docs/turns/2026-05-20-fix-alert-flow-packet-history.html`.
+
 If the `impeccable` skill is unavailable or blocked by an actual tool/file error, still create a well-structured standalone HTML file with:
 
 - A concise summary at the top
@@ -181,7 +183,7 @@ Each turn document must include these sections:
 2. **Changes Made**
 3. **Context**
 4. **Important Implementation Details**
-5. **Relevant Diff Snippets** (render with `@pierre/diffs/ssr` output by default; do not use `npx @pierre/diffs`; if unavailable, include a clearly labeled plain diff/code block and note why)
+5. **Relevant Diff Snippets** (render with Clean SSR `@pierre/diffs/ssr` output inside the template's `.diff-view` by default; do not use `npx @pierre/diffs`; if unavailable, include a clearly labeled plain fallback diff block and note why)
 6. **Expected Impact for End-Users**
 7. **Validation**
 8. **Issues, Limitations, and Mitigations**
diff --git a/docs/turns/template.html b/docs/turns/template.html
new file mode 100644
index 0000000..18aa8c9
--- /dev/null
+++ b/docs/turns/template.html
@@ -0,0 +1,319 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><!-- TITLE --></title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@500;600&family=IBM+Plex+Sans:wght@400;500;600&family=Quantico:wght@400;700&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #06080b;
+      --bg-2: #0b1016;
+      --panel: rgba(17, 24, 32, 0.92);
+      --panel-2: rgba(13, 20, 27, 0.94);
+      --line: rgba(255, 255, 255, 0.1);
+      --text: #e6edf4;
+      --muted: #90a0b2;
+      --faint: #6e7b8c;
+      --lavender: #bda7ff;
+      --lavender-soft: rgba(189, 167, 255, 0.16);
+      --pink: #ff9bd2;
+      --blue: #8bc1ff;
+      --code: #0a0f14;
+      --shadow: 0 24px 70px rgba(0, 0, 0, 0.45);
+      --radius: 14px;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      min-height: 100vh;
+      background:
+        radial-gradient(circle at top left, rgba(189, 167, 255, 0.18), transparent 32rem),
+        radial-gradient(circle at top right, rgba(255, 155, 210, 0.12), transparent 26rem),
+        linear-gradient(180deg, var(--bg) 0%, #081017 42%, #05080c 100%);
+      color: var(--text);
+      font-family: "IBM Plex Sans", system-ui, sans-serif;
+      line-height: 1.6;
+    }
+
+    main {
+      width: min(1080px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 40px 0 64px;
+    }
+
+    header,
+    section {
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      background: linear-gradient(180deg, var(--panel), var(--panel-2));
+    }
+
+    header {
+      padding: 28px;
+      border-radius: calc(var(--radius) + 2px);
+      background: linear-gradient(180deg, rgba(17, 24, 32, 0.96), rgba(11, 16, 22, 0.94));
+      box-shadow: var(--shadow);
+    }
+
+    .eyebrow,
+    h2,
+    .meta-chip,
+    .diff-title {
+      font-family: "IBM Plex Mono", monospace;
+    }
+
+    .eyebrow {
+      margin: 0 0 12px;
+      color: var(--lavender);
+      font-size: 0.76rem;
+      letter-spacing: 0.14em;
+      text-transform: uppercase;
+    }
+
+    h1 {
+      margin: 0;
+      max-width: 16ch;
+      font-family: "Quantico", sans-serif;
+      font-size: clamp(2.1rem, 4vw, 4.2rem);
+      line-height: 1.04;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+    }
+
+    .summary {
+      max-width: 72ch;
+      margin: 18px 0 0;
+      color: var(--muted);
+      font-size: 1.02rem;
+    }
+
+    .meta-row {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      margin-top: 18px;
+    }
+
+    .meta-chip {
+      padding: 6px 10px;
+      border: 1px solid rgba(189, 167, 255, 0.28);
+      border-radius: 999px;
+      background: rgba(189, 167, 255, 0.11);
+      color: var(--text);
+      font-size: 0.74rem;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    .grid {
+      display: grid;
+      gap: 18px;
+      margin-top: 20px;
+    }
+
+    section {
+      padding: 22px;
+    }
+
+    h2 {
+      margin: 0 0 12px;
+      color: var(--lavender);
+      font-size: 0.84rem;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+    }
+
+    p,
+    li {
+      max-width: 76ch;
+    }
+
+    ul {
+      margin: 0;
+      padding-left: 1.15rem;
+    }
+
+    li + li {
+      margin-top: 8px;
+    }
+
+    code,
+    pre {
+      font-family: "IBM Plex Mono", monospace;
+    }
+
+    code {
+      color: #decfff;
+    }
+
+    .callout {
+      padding: 14px 16px;
+      border: 1px solid rgba(189, 167, 255, 0.2);
+      border-radius: 12px;
+      background: var(--lavender-soft);
+      color: var(--text);
+    }
+
+    .diff-grid {
+      display: grid;
+      gap: 18px;
+    }
+
+    .diff-shell {
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      overflow: hidden;
+      background: rgba(8, 12, 17, 0.92);
+    }
+
+    .diff-title {
+      margin: 0;
+      padding: 12px 14px;
+      border-bottom: 1px solid var(--line);
+      color: var(--text);
+      font-size: 0.76rem;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    .diff-view {
+      min-height: 84px;
+      overflow-x: auto;
+    }
+
+    .diff-view:empty {
+      display: none;
+    }
+
+    .diff-fallback {
+      margin: 0;
+      padding: 16px;
+      overflow-x: auto;
+      background: var(--code);
+      color: var(--text);
+      font-size: 0.86rem;
+      line-height: 1.5;
+    }
+
+    .diff-shell.rendered .diff-fallback {
+      display: none;
+    }
+
+    .note {
+      margin-top: 12px;
+      color: var(--faint);
+      font-size: 0.9rem;
+    }
+
+    a {
+      color: #8bc1ff;
+    }
+
+    @media (max-width: 720px) {
+      main {
+        width: min(100%, calc(100% - 20px));
+        padding: 18px 0 28px;
+      }
+
+      header,
+      section {
+        padding: 18px;
+      }
+
+      h1 {
+        max-width: none;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <p class="eyebrow">Dreamio turn document</p>
+      <h1><!-- TITLE --></h1>
+      <p class="summary"><!-- SUMMARY --></p>
+      <div class="meta-row">
+        <!-- META_CHIPS -->
+        <span class="meta-chip">YYYY-MM-DD</span>
+        <span class="meta-chip">Beads issue dreamio-xxx</span>
+      </div>
+    </header>
+
+    <div class="grid">
+      <section>
+        <h2>Summary</h2>
+        <p><!-- SUMMARY --></p>
+      </section>
+
+      <section>
+        <h2>Changes Made</h2>
+        <ul>
+          <li><!-- CHANGE ITEM --></li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Context</h2>
+        <p><!-- CONTEXT --></p>
+      </section>
+
+      <section>
+        <h2>Important Implementation Details</h2>
+        <ul>
+          <li><!-- IMPLEMENTATION DETAIL --></li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Relevant Diff Snippets</h2>
+        <div class="diff-grid">
+          <!-- DIFF_SHELLS -->
+          <div class="diff-shell rendered">
+            <p class="diff-title">path/to/file.ext · short description</p>
+            <div class="diff-view">
+              <!-- Insert exactly one @pierre/diffs/ssr prerendered file diff here. -->
+            </div>
+            <pre class="diff-fallback"><code><!-- Plain fallback diff only if SSR rendering fails. --></code></pre>
+          </div>
+        </div>
+        <p class="note">Diffs are generated with <code>@pierre/diffs/ssr</code> at documentation time. Each file diff stays inside its own shell so the page remains readable as a static HTML artifact.</p>
+      </section>
+
+      <section>
+        <h2>Expected Impact for End-Users</h2>
+        <p><!-- EXPECTED IMPACT --></p>
+      </section>
+
+      <section>
+        <h2>Validation</h2>
+        <!-- VALIDATION -->
+        <ul>
+          <li><!-- VALIDATION ITEM --></li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Issues, Limitations, and Mitigations</h2>
+        <ul>
+          <li><!-- LIMITATION OR MITIGATION --></li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Follow-up Work</h2>
+        <ul>
+          <li><!-- FOLLOW-UP ITEM --></li>
+        </ul>
+      </section>
+    </div>
+  </main>
+</body>
+</html>