From 9031281cd4d126ab165206551986ca310aed1f07 Mon Sep 17 00:00:00 2001
From: Keysat <licensing@keysat.xyz>
Date: Tue, 16 Jun 2026 23:14:22 -0500
Subject: [PATCH] design guide: add Case-B extract field notes from first live
 run

First extract->reconcile run (recap) surfaced generalizable process
learnings: harvest the inventory with grep frequency tables in the main
thread (counts are the reconcile evidence), disambiguate near-duplicates
with frequency plus an external anchor, present conflicts as
recommended-first A/B/C forks with value previews, and treat the code
itself as the inspiration for a document-as-is extract (skip BRIEF and
_imports, write provenance). Also refine the Extract phase to enumerate
every styling surface and read the brand mark before the CSS.
---
 guides/design.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/guides/design.md b/guides/design.md
index cd6eceb..99185ae 100644
--- a/guides/design.md
+++ b/guides/design.md
@@ -113,7 +113,11 @@ canvas. Work it out *with* the user, inspiration-first:
    component treatments, depth/elevation — **including the inconsistencies** (the three
    almost-the-same blues, the four heading sizes). A read-only `design-checker` cannot do this
    (it needs a contract to check against), so inventory here in the main thread, optionally
-   delegating a read-only reader to gather the raw values.
+   delegating a read-only reader to gather the raw values. First **enumerate every styling
+   surface** — there is often more than one (a second stylesheet, a separate auth/landing
+   page, *CSS embedded in a string literal* that ships a self-contained export); a grep over
+   one `<style>` block silently misses the others. And **read the brand mark / icon before the
+   CSS** — it frequently encodes the intended color story the code only partly realized.
 2. **Reconcile with the user.** Surface the conflicts and let them make the **canonical calls**
    — which blue is *the* blue, which scale is *the* scale. Organically-arrived-at does not mean
    correct; their taste decides. This is the high-value human step; don't auto-resolve it.
@@ -276,6 +280,28 @@ us things. Brand facts never go here; only generalizable process/distillation kn
   drift risk — name a canonical `brand/palette.css`, point `DESIGN.md` §Agent-guide at it, and log
   the consolidation as backlog. Before relocating an existing design dir into `_imports/`, grep
   that **nothing imports it** (in keysat, nothing did — safe to move).
+- *(first Case-B extract run, 2026-06-16, recap)* **Harvest the inventory with grep frequency
+  tables in the main thread, not a delegated reader.** For a ~13k-line single file with ~450
+  inline styles, `grep -oE '<pattern>' | sort | uniq -c | sort -rn` per dimension (hex, rgba,
+  font-size, weight, radius, shadow, breakpoint) produced a complete *ranked* census that stayed
+  in context for the reconcile conversation — a sub-agent would have returned excerpts. The
+  **use-counts themselves are the reconcile evidence**: "which dark is THE background" is answered
+  by "132 uses + it's the PWA `manifest.json theme_color`," turning a taste call into a confirmation.
+- *(first Case-B extract run, 2026-06-16)* **Disambiguate near-duplicates with frequency + an
+  external anchor**, not the eye. Ranking each value by use-count and cross-referencing a fixed
+  reference (the PWA `theme_color`, the icon's gradient endpoints) reliably separated "one
+  canonical + N strays" from "N intentional values," which is exactly the call to hand the user.
+- *(first Case-B extract run, 2026-06-16)* **Present the reconcile conflicts as A/B/C forks,
+  recommended-option-first, with the candidate values in each option's preview.** Surfacing four
+  conflicts (the background, the accent, the surface ladder, the type scale) as one batch of
+  multiple-choice questions — each preview a monospace block showing the rival hexes in context —
+  let the owner make every canonical call in a single turn instead of a long volley. This is the
+  high-value human step; make it cheap to answer.
+- *(first Case-B extract run, 2026-06-16)* **For a document-as-is extract, the "inspiration" is the
+  code itself.** There is no external reference set and no export bundle, so `BRIEF.md` and
+  `_imports/` are correctly skipped; instead write `inspiration/README.md` pointing at the
+  harvested source files + the brand icon as the de-facto reference, and copy the icon into
+  `brand/`. That preserves the *why/where* record the folder convention exists for.
 
 ## Final report