From adc487e63b0ee2fdf621232de21f19e3482f5ae7 Mon Sep 17 00:00:00 2001
From: Ken <ken@kenotron.com>
Date: Wed, 27 May 2026 01:14:55 +0000
Subject: [PATCH] docs: book-not-blog organization, rage series plan with 6
 posts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Content model inspired by makingsoftware.com:
- Topics not dates (grouped by investigation theme)
- Homepage as pitch not index (show quality before navigation)
- Series are first-class (landing pages, progress, cross-links)
- Figure density: 1 visual per 300-500 words for technical posts
- No blog chrome (no comments, shares, newsletter popups)

Rage series plan (6 posts, all sourced from kenotron-ms/rage):
1. Your Build Cache Is Lying to You (the stale cache problem)
2. Two-Phase Fingerprinting: BuildXL's Deep Magic (WF/SF algorithm)
3. Hooking Syscalls Without a Kernel Driver (3 OS, 3 mechanisms)
4. TypeScript 7 Makes the Build Harness More Important (counter-intuitive)
5. node_modules in a Content-Addressed Store (CI kill shot)
6. What I Learned Maintaining Lage and Why I Rewrote It (meta narrative)

Each post has planned visuals (diagrams, flows, animations via Remotion).

🤖 Generated with Amplifier

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
---
 .amplifier/AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/.amplifier/AGENTS.md b/.amplifier/AGENTS.md
index af4e1ab..53c8e33 100644
--- a/.amplifier/AGENTS.md
+++ b/.amplifier/AGENTS.md
@@ -161,3 +161,47 @@ Visual check at blog.ampbox.io
   v
 Commit + push
 ```
+
+## Content Organization: Book, Not Blog
+
+The site is organized as a **book of investigations**, not a reverse-chronological
+feed. Inspired by makingsoftware.com. Key principles:
+
+**Topics, not dates.** Content is grouped by investigation theme (e.g., "Rage:
+Rebuilding the Build System" is a 5-post series, not 5 unrelated entries). Dates
+are secondary metadata, not the primary navigation.
+
+**The homepage is a pitch, not an index.** Lead with a compelling excerpt, a
+diagram, a question that creates intrigue. Show the reader what the content
+quality is like before presenting any navigation. A flat list of article cards
+is a cop-out. The homepage should make you curious.
+
+**Series are first-class.** Multi-post series (like the Rage build system series)
+get their own landing page with a visual overview, progress indication, and
+cross-links between posts. Individual posts link to their series context.
+
+**Figure density matters.** Target 1 visual per 300-500 words for technical posts.
+Not decoration, but content: architecture diagrams, flow charts, before/after
+comparisons, concept illustrations. If 500+ words pass without a visual, ask
+what would replace them.
+
+**No blog chrome.** No comments, no share buttons, no "related posts" sidebar,
+no newsletter popups, no social proof widgets. The content quality is the
+credibility signal. If it needs a "clap" button, the writing isn't good enough.
+
+## Current Content Plan: Rage Series
+
+Source: kenotron-ms/rage repo + ~/workspace/family/Work/Reference/BuildXL spec
+
+| # | Title | Angle | Visuals Needed |
+|---|-------|-------|----------------|
+| 1 | Your Build Cache Is Lying to You | The silent stale cache problem. Make it concrete. | Flow: declared vs observed inputs. Before/after diagram of cache miss. |
+| 2 | Two-Phase Fingerprinting: BuildXL's Deep Magic | WF→pathset→SF algorithm deep-dive. | Architecture: the two-phase lookup flow. Code walkthrough diagrams. |
+| 3 | Hooking Syscalls Without a Kernel Driver | Three OS, three mechanisms. Most technically dense. | Side-by-side: macOS interpose / Linux eBPF / Windows Detours. Animated (Remotion): syscall interception flow. |
+| 4 | TypeScript 7 Makes the Build Harness More Important | Counter-intuitive thesis. Widest reach. | Comparison: single-machine vs distributed. The parallelism table as a visual. |
+| 5 | node_modules in a Content-Addressed Store | The unsexy problem that kills CI. | Flow: lockfile → CAS → hardlink restore. Before/after CI times. |
+| 6 | What I Learned Maintaining Lage and Why I Rewrote It | Personal narrative, meta post. | Timeline: lage → BuildXL integration hack → rage. |
+
+Each post stands alone but gains context from the series. The series landing page
+shows progress (like makingsoftware.com's progress bar) and creates anticipation
+for upcoming posts.