From 70634c01781e73a1650d1e2ec76b7ca75aae92ed Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Wed, 1 Jul 2026 10:09:30 +0200
Subject: [PATCH 1/7] refactor(stream-react): migrate to live-docs orchestrator
 + custom-ui contract

Complete stream-react's transition from bundled blueprints to the PR #24
live-docs pattern, add the bespoke-UI completion contract, and remove the
Task A.2 frontend-skill install gate.

- docs-map.md (was DOCS.md): teach the .md-twin convention + per-product live
  CLI index + URL-grounding rule so the router self-heals instead of rotting;
  fix a stale Feeds quick-start path.
- custom-ui.md (new): prebuilt-vs-bespoke rubric, headless Chat/Video path,
  route-to-live table, and a REQUIRED completion contract (reproduce /
  N/A-with-design-reason / GAP) that stops custom rows from silently dropping
  attachments, reactions, quoted replies, receipts, threads.
- Router fix: writing your own component for a prebuilt region now loads
  custom-ui.md first (RULES/docs-map/SKILL), even via Message=/WithComponents.
- Surgical blueprint trim: CHAT -688, VIDEO -473 (drop doc-mirror; keep the
  canonical provider trees + prebuilt happy path). Light trims to CHAT/VIDEO.
- Remove Task A.2: stream-react no longer installs third-party frontend skills
  or prompts for consent; uses them only if already present. stream-builder
  retains A.2 (divergence documented in RULES.md).

Validated RED->GREEN with subagent pressure tests (custom-row completeness,
routing reachability, N/A-loophole). ASCII-clean.
---
 skills/stream-react/RULES.md                  |  19 +-
 skills/stream-react/SKILL.md                  |  41 +-
 skills/stream-react/builder-ui.md             |   8 +-
 skills/stream-react/enhance.md                |   4 +-
 skills/stream-react/migrate.md                |   4 +-
 .../references/CHAT-blueprints.md             | 688 +-----------------
 skills/stream-react/references/CHAT.md        |  13 +-
 .../references/FEEDS-blueprints.md            |   2 +-
 .../references/VIDEO-blueprints.md            | 473 +-----------
 skills/stream-react/references/VIDEO.md       |  13 +-
 skills/stream-react/references/custom-ui.md   | 158 ++++
 .../references/{DOCS.md => docs-map.md}       |  50 +-
 12 files changed, 244 insertions(+), 1229 deletions(-)
 create mode 100644 skills/stream-react/references/custom-ui.md
 rename skills/stream-react/references/{DOCS.md => docs-map.md} (81%)

diff --git a/skills/stream-react/RULES.md b/skills/stream-react/RULES.md
index 6581e7f..634707d 100644
--- a/skills/stream-react/RULES.md
+++ b/skills/stream-react/RULES.md
@@ -70,9 +70,14 @@ docs/cookbooks are built around customizing them. Default to that path:
 
 **Customize via the documented hooks/props** (e.g. `<MessageList Message={Custom} />`,
 `useChannelStateContext()`, `useMessageContext()`, `useCallStateHooks()`, `<Channel>` theming) -
-fetch the matching docs page first (see Docs-first below). **Hand-build raw markup ONLY when the
-user explicitly asks for fully bespoke UI**; in that case use the `references/*-blueprints.md`
-"Fully custom UI" fallback section (raw element structure + wiring tables) - still docs-first.
+fetch the matching docs page first (see Docs-first below).
+
+**Writing your OWN component for a prebuilt region triggers [`references/custom-ui.md`](references/custom-ui.md) - load it BEFORE you build.** This is the predicate, and it is easy to get wrong:
+
+- **Passing props / theme** to a prebuilt component (a cookbook recipe's prop, `<Channel>` theme tokens) -> just fetch the page.
+- **Writing your own component/markup for a region** - a custom message row / `MessageUI`, a custom composer, a custom channel preview or header, a custom call layout - **load `custom-ui.md` first, then fetch the page.** This holds **even when you wire it via the documented `Message=` / `WithComponents` prop**, and it is **not** limited to a "fully bespoke app".
+
+Why: replacing a prebuilt region means you inherit every sub-feature it rendered. `custom-ui.md` carries the **completion contract** (reproduce-or-mark-`N/A`: attachments, reactions, quoted replies, receipts, threads, edited/deleted, grouping) that stops a custom row from silently dropping them. Still docs-first either way.
 
 **Reference files are the source of truth for the components they document** - which prebuilt
 component to use, its props, SDK wiring, and property paths. Do not generate Stream SDK code from
@@ -86,11 +91,11 @@ and memory - fetch it.
 
 ## Docs-first for cookbook / advanced features
 
-**Before implementing any feature that matches a UI component, UI Cookbook, or Advanced Guide topic, fetch the matching Stream docs page first.** [`references/DOCS.md`](references/DOCS.md) holds the keyword -> page map and the protocol. The bundled `references/*-blueprints.md` cover the common path; component-reference and cookbook/advanced topics - the prebuilt component props, typing indicator, custom message UI, message actions, reactions, message composer / input UI, channel header, emoji picker, autocomplete, link previews, AI integrations, advanced search, multiple lists, infinite scroll, channel read state, online status, location sharing, blocking users, message reminders, notifications, attachment previews, audio playback, date/time formatting, SDK state management, dialog management, TypeScript custom data types, chat + video integration, call layouts, PiP, network quality, livestream watching, recording, broadcasting - change often and **must** be built from the current page, not memory.
+**Before implementing any feature that matches a UI component, UI Cookbook, or Advanced Guide topic, fetch the matching Stream docs page first.** [`references/docs-map.md`](references/docs-map.md) holds the keyword -> page map and the protocol. The bundled `references/*-blueprints.md` cover the common path; component-reference and cookbook/advanced topics - the prebuilt component props, typing indicator, custom message UI, message actions, reactions, message composer / input UI, channel header, emoji picker, autocomplete, link previews, AI integrations, advanced search, multiple lists, infinite scroll, channel read state, online status, location sharing, blocking users, message reminders, notifications, attachment previews, audio playback, date/time formatting, SDK state management, dialog management, TypeScript custom data types, chat + video integration, call layouts, PiP, network quality, livestream watching, recording, broadcasting - change often and **must** be built from the current page, not memory.
 
-**This rule also governs migration (Track M).** Never apply an SDK upgrade from memory - fetch the matching release / upgrade guide from the index in [`references/DOCS.md`](references/DOCS.md) (or [`migrate.md`](migrate.md)) and apply *that*.
+**This rule also governs migration (Track M).** Never apply an SDK upgrade from memory - fetch the matching release / upgrade guide from the index in [`references/docs-map.md`](references/docs-map.md) (or [`migrate.md`](migrate.md)) and apply *that*.
 
-**Flow:** match a trigger -> `WebFetch` the `.md` URL from [`references/DOCS.md`](references/DOCS.md) -> read it this turn -> implement to match.
+**Flow:** match a trigger -> `WebFetch` the `.md` URL from [`references/docs-map.md`](references/docs-map.md) -> read it this turn -> implement to match.
 
 **Hard gate on fetch failure.** If the page does not load, hand the lookup to the `stream-docs` skill. If **neither** the page nor `stream-docs` resolves the API, **stop and tell the user** - report that you could not confirm the current API and ask how to proceed. **Do not implement the feature from memory.** A guess that happens to compile is still a guess.
 
@@ -126,7 +131,7 @@ The generic onboarding + phase-order discipline lives in [`../stream/RULES.md`](
 
 - Do not load `references/*.md` until the user names the product(s).
 - Do not load [`builder-ui.md`](builder-ui.md) before Step 4.
-- Shadcn/ui is always installed during Step 3 - never skip. Third-party **frontend skills** (`vercel-labs/*`, `anthropics/*`) require one explicit user confirmation per session before install - see [`SKILL.md`](SKILL.md) Task A.2.
+- Shadcn/ui is always installed during Step 3 - never skip. **stream-react does not install third-party frontend skills** (no install step). If such packs (`frontend-design`, `vercel-react-best-practices`, `web-design-guidelines`) are already present in the session, use them for generic UI polish only - Stream references stay authoritative for SDK wiring. (The consent-to-install rule in [`../stream/RULES.md`](../stream/RULES.md) > Builder phase order is for `stream-builder`, which retains that step; this file wins for React.)
 
 ## Moderation is Dashboard-only
 
diff --git a/skills/stream-react/SKILL.md b/skills/stream-react/SKILL.md
index b822c98..60fd5c1 100644
--- a/skills/stream-react/SKILL.md
+++ b/skills/stream-react/SKILL.md
@@ -31,7 +31,7 @@ This skill builds, enhances, audits, and migrates Stream Chat, Video, and Feeds
 
 - **Track A - Scaffold a new app:** Steps 0-7 below. Use when the cwd is empty / new and the user said "build me a ... app".
 - **Track E - Enhance an existing app:** see [`enhance.md`](enhance.md). Skips scaffold + theme; reuses the same SDK wiring and component blueprints.
-- **Track F - Audit an existing integration (read-only):** for "audit/review my video integration", "check my app against best practices", "is my video app production-ready?", "what am I missing before launch?". **Video only:** load the **Integration best-practices audit** section in [`references/VIDEO.md`](references/VIDEO.md) and follow its protocol - it has a Video-specific checklist + output contract. **If the user asks to audit Chat or Feeds**, say up front there is no dedicated best-practices checklist for those yet, then do a general docs-based review (fetch the relevant pages from [`references/DOCS.md`](references/DOCS.md) and check the app against them) rather than applying the Video checklist. **Skip onboarding, auth, the CLI, and all build steps** - this track only reads the app and reports findings. Fix issues only if the user then asks.
+- **Track F - Audit an existing integration (read-only):** for "audit/review my video integration", "check my app against best practices", "is my video app production-ready?", "what am I missing before launch?". **Video only:** load the **Integration best-practices audit** section in [`references/VIDEO.md`](references/VIDEO.md) and follow its protocol - it has a Video-specific checklist + output contract. **If the user asks to audit Chat or Feeds**, say up front there is no dedicated best-practices checklist for those yet, then do a general docs-based review (fetch the relevant pages from [`references/docs-map.md`](references/docs-map.md) and check the app against them) rather than applying the Video checklist. **Skip onboarding, auth, the CLI, and all build steps** - this track only reads the app and reports findings. Fix issues only if the user then asks.
 - **Track M - Migrate / upgrade an SDK version:** see [`migrate.md`](migrate.md). For "upgrade stream-chat-react to v14", "migrate to the new SDK", "bump my Stream version". Docs-driven: detect the installed version, fetch the matching release guide, apply it. Never migrate from memory.
 
 ### Flow dispatch - choose exactly one
@@ -45,14 +45,14 @@ This skill builds, enhances, audits, and migrates Stream Chat, Video, and Feeds
 
 ## Docs-first triggers (consult docs before building)
 
-**For any feature that matches a UI component, cookbook, or advanced-guide topic, fetch the matching Stream docs page BEFORE writing code.** The live docs are the source of truth for the current API and the recommended pattern; the bundled `references/*-blueprints.md` cover the common path only. Full keyword -> page map with exact URLs: [`references/DOCS.md`](references/DOCS.md). Enforced by [`RULES.md`](RULES.md) > Docs-first for cookbook / advanced features.
+**For any feature that matches a UI component, cookbook, or advanced-guide topic, fetch the matching Stream docs page BEFORE writing code.** The live docs are the source of truth for the current API and the recommended pattern; the bundled `references/*-blueprints.md` cover the prebuilt common path only. Full keyword -> page map with exact URLs: [`references/docs-map.md`](references/docs-map.md) - it opens with the **docs convention** (the `.md`-twin rule + per-product live index) so any unmapped page is still reachable: never guess a path, fetch the index. Enforced by [`RULES.md`](RULES.md) > Docs-first for cookbook / advanced features.
 
 This skill is **prebuilt-component-first**: build the common path with the SDK's prebuilt React components and customize via the documented hooks/props - see [`RULES.md`](RULES.md) > Reference authority. The docs-first protocol covers both the **component reference pages** and the **cookbook / advanced** recipes:
 
 - **UI Cookbook (customization / theming):** typing indicator, custom message UI, message actions, reactions customization, message composer / input UI, channel header, channel list preview, emoji picker, autocomplete / suggestion list, link previews, pin indicator, thread header, search, collapsible sidebar, system message / banner, mentions actions, attachment actions, hide channel history, localization / i18n; Video: replacing call controls, custom layouts, lobby preview, PiP, network quality, livestream watching, ringing.
 - **Advanced Guides:** AI integrations (LangChain, AI SDK), advanced search, multiple lists, infinite scroll, read state, online status, location sharing, blocking, message reminders, notifications / web push, attachment previews, audio playback, date formatting, SDK state management, dialog management, TypeScript custom data, chat + video integration, recording, broadcasting, video filters.
 
-When a request hits one of these: **match -> `WebFetch` the page's `.md` URL from [`references/DOCS.md`](references/DOCS.md) -> implement to match.** On fetch failure, hand to the `stream-docs` skill; if neither resolves the API, **stop and ask the user** - never build from memory.
+When a request hits one of these: **match -> `WebFetch` the page's `.md` URL from [`references/docs-map.md`](references/docs-map.md) -> implement to match.** On fetch failure, hand to the `stream-docs` skill; if neither resolves the API, **stop and ask the user** - never build from memory.
 
 ---
 
@@ -60,7 +60,7 @@ When a request hits one of these: **match -> `WebFetch` the page's `.md` URL fro
 
 > **Track A only.** Tracks E, F, and M branch in **Flow dispatch** above and never enter this section.
 
-Once `getstream init` has onboarded (authenticated + selected/created org + app + written credentials), announce the network plan once, then **immediately start executing Steps 0-7** - do not ask permission to begin (the user has authorized the build by asking for it). The only pauses for input are the theme + app pick (Step 1b) and the skill-pack consent (Task A.2).
+Once `getstream init` has onboarded (authenticated + selected/created org + app + written credentials), announce the network plan once, then **immediately start executing Steps 0-7** - do not ask permission to begin (the user has authorized the build by asking for it). The only pause for input is the theme + app pick (Step 1b).
 
 ### Trust readout (announce, then continue on the same turn - do not wait)
 
@@ -71,11 +71,11 @@ Before the first network command, print this verbatim to the user, then proceed
 > - `npm install <stream-packages> --legacy-peer-deps` - Stream SDKs from npm (`stream-chat-react`, `@stream-io/video-react-sdk`, etc.).
 > - `getstream env` - local CLI, no network; writes `.env.local` (gitignored by the Next.js scaffold's default; Task B verifies).
 >
-> Interrupt me at any point if something looks wrong. I'll pause twice for your input: the theme + Stream-app pick (Step 1b) and the optional third-party skill packs (Task A.2).
+> Interrupt me at any point if something looks wrong. I'll pause once for your input: the theme + Stream-app pick (Step 1b).
 
 Full per-command audit (publisher, why unpinned, what each writes): section Install trust & integrity below. The user's continued silence after the readout is implicit consent for this scaffold; an objection or stop instruction aborts the run.
 
-Shadcn/ui is always installed during Step 3. Third-party **frontend skills** (`vercel-react-best-practices`, `web-design-guidelines`, `frontend-design`) are installed **only with explicit user consent** - see Task A.2 for the disclosure script. If the user declines, Step 4 proceeds using Stream references only. **Precedence (when the skills are present):** Stream references win for SDK wiring; frontend skills guide generic React / UI polish.
+Shadcn/ui is always installed during Step 3. **stream-react does not install third-party frontend skills** - the build uses Stream references + Shadcn. **If** frontend skill packs (`frontend-design`, `vercel-react-best-practices`, `web-design-guidelines`) are already available in the session, use them for generic React / UI polish only; Stream references remain authoritative for SDK wiring.
 
 ---
 
@@ -88,13 +88,11 @@ This builder runs three classes of network-touching commands. Each is listed her
 | `npx shadcn@latest init ...` (Task A) | Vercel - [`shadcn-ui/ui`](https://github.com/shadcn-ui/ui) | Scaffolder; `@latest` is the maintainer's documented usage. Pinning ships outdated scaffolds. | Project files in cwd. Next.js scaffold's `.gitignore` ignores `.env*` by default. |
 | `npx shadcn@latest add ...` (Task A.1) | Vercel - same source as above | Same scaffolder; component sync depends on registry parity. | Component files under `components/ui/`. |
 | `npm install <stream-packages> --legacy-peer-deps` (Task C) | GetStream (npm) for `@stream-io/*` and `stream-chat-react`; transitive deps via standard npm trust | Latest published versions of GetStream's own SDKs - same trust model as the CLI itself. | Modules under `node_modules/`. Runtime SDKs + transitive deps. |
-| `npx skills add <github>` (Task A.2) | `vercel-labs/agent-skills` and `anthropics/skills` | Optional. Markdown-only skill packs; `npx skills add` is the published install path. | Markdown files in the user's skills directory. **Gated by explicit user consent in Task A.2** - never runs without an affirmative answer. |
 | `getstream env` (Task B) | GetStream - install instructions in the root skill's "Stream CLI" section in [`../stream/SKILL.md`](../stream/SKILL.md) | n/a (local CLI, no network at this step) | `.env.local` in the project root with `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET`. Task B verifies `.gitignore` covers `.env*` before writing (Next.js scaffold's default already does). The agent never reads `.env.local` (RULES.md > Secrets). |
 
 **Reviewer checklist:**
 
 - All `npx` invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
-- `npx skills add` runs **only after** the disclosure prompt in Task A.2 and an explicit user "yes."
 - `.env.local` is written by the Stream CLI directly, not by the agent, and is not transmitted into the conversation.
 - If the user wants to pin a specific shadcn version, replace `@latest` with `@<version>` in Tasks A and A.1.
 
@@ -139,8 +137,7 @@ Order:
 2. **Step 2:** Apply the org/app choice (select existing or create).
 3. **Task A:** Scaffold with Shadcn + Next.js using the chosen preset.
 4. **Task A.1:** Add base Shadcn components.
-5. **Task A.2:** Disclose + ask about third-party frontend skill installs; install only with user consent.
-6. Continue with Task B (.env), Task C (SDKs), Task D (CLI config).
+5. Continue with Task B (.env), Task C (SDKs), Task D (CLI config).
 
 **Task A: Scaffold** - scaffolds Next.js + Tailwind + Shadcn/ui (Base UI) into the current directory. Use the theme preset chosen in **Step 1b**.
 
@@ -158,24 +155,6 @@ npx shadcn@latest add button input textarea card avatar badge separator
 
 Add more components as the use case requires (e.g. `dialog`, `dropdown-menu`, `tabs`, `popover`).
 
-**Task A.2: Frontend skills** - third-party skill packs. **You must disclose and ask before installing.** Do NOT construct your own command variant.
-
-Print this disclosure verbatim, then stop and wait for the user's answer:
-
-> I'd like to install three third-party skill packs that improve generic UI quality:
-> - `vercel-react-best-practices` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)
-> - `web-design-guidelines` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills)
-> - `frontend-design` - from [`anthropics/skills`](https://github.com/anthropics/skills)
->
-> The packs are markdown only - no scripts execute. If you say yes, I'll run `npx skills add ... -y` once per pack from those GitHub repos at their current `main` branch (`-y` skips the installer's own confirmation since you've consented here). These aren't required - Stream reference files cover SDK wiring either way. Install them?
-
-- **User agrees** -> run:
-  ```bash
-  npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -y && npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines -y && npx skills add https://github.com/anthropics/skills --skill frontend-design -y
-  ```
-- **User declines** -> skip silently and continue to Task B. Do not retry, do not bring it up again this session.
-- **Install fails** -> continue with Stream reference files only; mention the failure briefly.
-
 Do **not** modify `layout.tsx` or `globals.css` after scaffold - use Shadcn's defaults as-is (RULES.md > Theme).
 
 **Task B: .env** - run AFTER scaffold so the `.env` lands inside the project directory.
@@ -218,11 +197,11 @@ If `NO_ICONS`, install `lucide-react`: `npm install lucide-react --legacy-peer-d
 
 ### Step 4: Generate code and UI
 
-**Prebuilt-component-first.** Build the common path with the SDK's prebuilt React components and customize via the documented hooks/props ([`RULES.md`](RULES.md) > Reference authority). Hand-build markup only when the user explicitly wants fully bespoke UI.
+**Prebuilt-component-first.** Build the common path with the SDK's prebuilt React components and customize via the documented hooks/props ([`RULES.md`](RULES.md) > Reference authority). Writing your own component for a region (custom message row, composer, channel preview/header, call layout) - not just passing props - loads [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) first; see [`RULES.md`](RULES.md) > Reference authority.
 
-**Docs-first:** before implementing any component, cookbook, or advanced feature (typing indicator, custom message UI, reactions, AI integrations, read state, notifications, call layouts, ...), follow the **Docs-first triggers** section above - `WebFetch` the matching [`references/DOCS.md`](references/DOCS.md) page first, then build to match.
+**Docs-first:** before implementing any component, cookbook, or advanced feature (typing indicator, custom message UI, reactions, AI integrations, read state, notifications, call layouts, ...), follow the **Docs-first triggers** section above - `WebFetch` the matching [`references/docs-map.md`](references/docs-map.md) page first, then build to match.
 
-**Load [`builder-ui.md`](builder-ui.md) and [`sdk.md`](sdk.md)** (cross-cutting SDK wiring: token route, instantiation, CSS imports), plus **only** the relevant [`references/<Product>.md`](references/) header + `references/<Product>-blueprints.md` for the sections you are implementing - not every reference file. Pull **Use Case Matching** and **Page Flow** from [`builder.md`](builder.md) to choose products and navigation structure. **For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) before writing AppShell** - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table.
+**Load [`builder-ui.md`](builder-ui.md) and [`sdk.md`](sdk.md)** (cross-cutting SDK wiring: token route, instantiation, CSS imports), plus **only** the relevant [`references/<Product>.md`](references/) header + `references/<Product>-blueprints.md` (the prebuilt provider tree + props) for the product(s) you are implementing - not every reference file. For any customization, fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) first; **writing your own component for a region (custom message row/composer/preview/header/call layout) -> load [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) before building**, then fetch the page. Pull **Use Case Matching** and **Page Flow** from [`builder.md`](builder.md) to choose products and navigation structure. **For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) before writing AppShell** - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table.
 
 ### Step 5: Verify
 
diff --git a/skills/stream-react/builder-ui.md b/skills/stream-react/builder-ui.md
index c1d8743..010bdd7 100644
--- a/skills/stream-react/builder-ui.md
+++ b/skills/stream-react/builder-ui.md
@@ -3,7 +3,7 @@
 Load when executing **Step 4** (after scaffold). Rules: [`RULES.md`](RULES.md) (login screen first, theme, reference authority).
 
 ### Step 4: Generate ALL code files
-Write every file sequentially. Follow the UI Guidelines below for all visual styling. See **RULES.md > Reference authority** - reference files are the only source of truth for SDK wiring. Before writing each component, load the relevant `references/<Product>-blueprints.md` section.
+Write every file sequentially. Follow the UI Guidelines below for all visual styling. See **RULES.md > Reference authority** - reference files are the only source of truth for SDK wiring. Before writing each component, load the prebuilt path in the relevant `references/<Product>-blueprints.md`; fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and see [`references/custom-ui.md`](references/custom-ui.md) for fully bespoke UI.
 
 #### Login Screen (required for every app - RULES.md > Login Screen first)
 
@@ -52,7 +52,7 @@ Use whatever `globals.css` Shadcn generates. Do not add custom variables, custom
 
 ### Design
 
-Use Shadcn components, Tailwind utilities, and - if the user approved them in Step 3 Task A.2 - the frontend skills to build a polished UI. No further opinions; use your best judgement. Stream references provide structure and wiring; frontend skills (when present) provide generic design guidance.
+Use Shadcn components, Tailwind utilities, and - if frontend skill packs are already available in the session - the frontend skills to build a polished UI. No further opinions; use your best judgement. Stream references provide structure and wiring; frontend skills (when present) provide generic design guidance.
 
 ### Button labels
 
@@ -72,6 +72,6 @@ Use Shadcn components, Tailwind utilities, and - if the user approved them in St
 
 ### Reference Blueprints
 
-See RULES.md > Reference authority. Load `references/<Product>.md` (header) for setup + gotchas, and `references/<Product>-blueprints.md` for structure and wiring of each component. Load only the product(s) relevant to the current use case.
+See RULES.md > Reference authority. Load `references/<Product>.md` (header) for setup + gotchas, and `references/<Product>-blueprints.md` for the prebuilt provider tree + props. For fully bespoke UI on the low-level client, see [`references/custom-ui.md`](references/custom-ui.md). Load only the product(s) relevant to the current use case.
 
-**Prebuilt-first default (Chat + Video).** Build the common path with the SDK's prebuilt React components - Chat: `<Chat>` / `<ChannelList>` / `<Channel>` / `<Window>` / `<MessageList>` / `<MessageComposer>` / `<Thread>` (v14 uses `MessageComposer`, not `MessageInput`); Video: `<StreamVideo>` / `<StreamCall>` / `SpeakerLayout` / `PaginatedGridLayout` / `ParticipantView` / `CallControls`. Customize via the documented hooks/props - register custom UI through `<WithComponents overrides={{...}}>` or pass a per-list `<MessageList Message={Custom} />`; read state with `useChannelStateContext()` / `useCallStateHooks()`) - fetch the matching cookbook page first (RULES.md > Docs-first). Drop to fully hand-built markup **only** when the user explicitly wants bespoke UI; the `*-blueprints.md` "Fully custom UI" fallback section has the raw element + wiring tables for that case. Feeds is headless (no prebuilt UI) - always build from its hooks.
+**Prebuilt-first default (Chat + Video).** Build the common path with the SDK's prebuilt React components - Chat: `<Chat>` / `<ChannelList>` / `<Channel>` / `<Window>` / `<MessageList>` / `<MessageComposer>` / `<Thread>` (v14 uses `MessageComposer`, not `MessageInput`); Video: `<StreamVideo>` / `<StreamCall>` / `SpeakerLayout` / `PaginatedGridLayout` / `ParticipantView` / `CallControls`. Customize via the documented hooks/props - register custom UI through `<WithComponents overrides={{...}}>` or pass a per-list `<MessageList Message={Custom} />`; read state with `useChannelStateContext()` / `useCallStateHooks()`) - fetch the matching cookbook page first (RULES.md > Docs-first). Drop to fully hand-built markup **only** when the user explicitly wants bespoke UI; [`references/custom-ui.md`](references/custom-ui.md) carries the prebuilt-vs-bespoke decision + the headless context-hook map for that case. Feeds is headless (no prebuilt UI) - always build from its hooks.
diff --git a/skills/stream-react/enhance.md b/skills/stream-react/enhance.md
index 0ce37d4..a321065 100644
--- a/skills/stream-react/enhance.md
+++ b/skills/stream-react/enhance.md
@@ -31,7 +31,7 @@ Before writing any code, understand what's already in place:
 
 1. **Token endpoint:** extend the existing token endpoint to return the new product's token alongside existing ones. On **Next.js** this is the `/api/token` route handler; on **other React stacks** it is the project's own server endpoint (Express/Fastify route, Remix loader/action, Vite server fn, etc.) - the server-side instantiation in [`sdk.md`](sdk.md) is identical, only the host differs. Tokens are always minted server-side ([`RULES.md`](RULES.md) > Env vars are server-side only).
 2. **API routes:** add the product-specific server routes from `references/<Product>.md` (App Integration -> API Routes) - as Next.js route handlers on Next.js, or equivalent endpoints in the app's backend otherwise. Feeds needs several (`/api/feed/get`, `/api/feed/post`, etc.); Chat and Video typically only need the token endpoint.
-3. **Components:** load the relevant `references/<Product>-blueprints.md` sections and build components using the existing project's patterns and styling conventions - not the [`builder-ui.md`](builder-ui.md) defaults.
+3. **Components:** load the prebuilt path in `references/<Product>-blueprints.md` (and [`references/custom-ui.md`](references/custom-ui.md) for fully bespoke UI), fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and build using the existing project's patterns and styling conventions - not the [`builder-ui.md`](builder-ui.md) defaults.
 4. **State:** if the app already manages user state (auth context, session), wire Stream tokens into that - don't add a separate Login Screen unless the app has no auth.
 
 ## E4: Verify
@@ -49,7 +49,7 @@ Fix any errors. Use the project's existing package manager and `build` script -
 
 ## Key constraints
 
-- Do **not** re-scaffold, re-initialize Shadcn, install frontend skills, or modify `globals.css` / `layout.tsx`.
+- Do **not** re-scaffold, re-initialize Shadcn, or modify `globals.css` / `layout.tsx`.
 - Do **not** overwrite or restructure existing files - add new files alongside them.
 - Do **not** change the existing auth flow. Adapt Stream's token generation to fit the app's existing auth, not the other way around.
 - If the project uses a different package manager (yarn, pnpm), match what it already uses - the npm-only rule applies to new scaffolds, not existing projects.
diff --git a/skills/stream-react/migrate.md b/skills/stream-react/migrate.md
index 545e398..36ed0c4 100644
--- a/skills/stream-react/migrate.md
+++ b/skills/stream-react/migrate.md
@@ -28,9 +28,9 @@ Establish **from version -> to version** for each package the user wants to move
 
 **Match the upgrade to its guide and `WebFetch` it this turn.** Known entry point:
 
-- **Chat React v13 -> v14:** https://getstream.io/chat/docs/sdk/react/release-guides/upgrade-to-v14.md (also in [`references/DOCS.md`](references/DOCS.md) > Chat Advanced Guides).
+- **Chat React v13 -> v14:** https://getstream.io/chat/docs/sdk/react/release-guides/upgrade-to-v14.md (also in [`references/docs-map.md`](references/docs-map.md) > Chat Advanced Guides).
 
-For any other package/version, discover the guide from the product `llms.txt` index ([`references/DOCS.md`](references/DOCS.md) > Source indexes) - look for a `release-guides/` or `upgrade-*` page that matches the from/to versions. Read the guide in full before touching code; note every breaking change, rename, removed export, and codemod it lists.
+For any other package/version, discover the guide from the product index ([`references/docs-map.md`](references/docs-map.md) > The docs convention) - look for a `release-guides/` or `upgrade-*` page that matches the from/to versions. Read the guide in full before touching code; note every breaking change, rename, removed export, and codemod it lists.
 
 **Hard gate ([`RULES.md`](RULES.md)):** if no guide loads, hand the lookup to the `stream-docs` skill. If neither the guide nor `stream-docs` confirms the migration steps, **stop and tell the user** - report that you could not confirm the upgrade path and ask how to proceed. Do not migrate from memory; a guess that happens to compile is still a guess.
 
diff --git a/skills/stream-react/references/CHAT-blueprints.md b/skills/stream-react/references/CHAT-blueprints.md
index 02c1977..e8a04ed 100644
--- a/skills/stream-react/references/CHAT-blueprints.md
+++ b/skills/stream-react/references/CHAT-blueprints.md
@@ -2,7 +2,7 @@
 
 Setup, routes, and gotchas: [CHAT.md](CHAT.md). Rules: [`../RULES.md`](../RULES.md) (reference authority, strict mode protection) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
-**Build the common path with `stream-chat-react`'s prebuilt components and customize via the documented hooks/props.** Only drop to the hand-built markup in **Fully custom UI (fallback)** below when the user explicitly wants fully bespoke UI - and even then, fetch the matching docs page first ([`DOCS.md`](DOCS.md)).
+**Build the common path with `stream-chat-react`'s prebuilt components and customize via the documented hooks/props.** For fully hand-built, bespoke UI on the low-level client, see [`custom-ui.md`](custom-ui.md) - and even then, fetch the matching docs page first ([`docs-map.md`](docs-map.md)).
 
 ---
 
@@ -65,7 +65,7 @@ import { WithComponents } from 'stream-chat-react';
 
 **Bonus:** `ChatView` (+ `ChatView.Selector` / `.Channels` / `.Threads`) and `ThreadList` / `ThreadListItem` for a channel/thread switcher.
 
-**Beyond the common path (docs-first expansion points)** - features the blueprints above don't cover; fetch the matching [`DOCS.md`](DOCS.md) row before building:
+**Beyond the common path (docs-first expansion points)** - features the blueprints above don't cover; fetch the matching [`docs-map.md`](docs-map.md) row before building:
 - **Polls** - prebuilt `Poll` component; create / vote (needs `polls` enabled on the channel type)
 - **AI assistant / streaming responses** - typewriter effect + `AIStateIndicator` (AI Integrations, LangChain, Vercel AI SDK)
 - **Voice messages** - record in the composer (`audioRecordingEnabled`) and play back the voice-recording attachment
@@ -75,690 +75,10 @@ import { WithComponents } from 'stream-chat-react';
 - **Threads manager** - `ChatView` channel/thread switcher + `ThreadList` (unread-threads inbox)
 - **Moderation bounce** - let a user review / edit / retry their own message bounced by moderation (`MessageBounce`)
 
-**Docs-first:** for any customization (custom message UI, theming, reactions, composer UI, channel header, search, AI, ...) fetch the matching page from [`DOCS.md`](DOCS.md) before writing - the prebuilt props and customization API evolve. Component reference pages live at `https://getstream.io/chat/docs/sdk/react/components/{category}/{component}.md`.
+**Docs-first:** for any customization (custom message UI, theming, reactions, composer UI, channel header, search, AI, ...) fetch the matching page from [`docs-map.md`](docs-map.md) before writing - the prebuilt props and customization API evolve. Component reference pages live at `https://getstream.io/chat/docs/sdk/react/components/{category}/{component}.md`.
 
 ---
 
 ## Fully custom UI (fallback)
 
-> **Use these only when the user explicitly wants bespoke, fully hand-built UI** (not the prebuilt components above). Each section gives the raw element structure + a wiring table mapping DOM to SDK calls. Still fetch the matching [`DOCS.md`](DOCS.md) page first. The BEM class names are a structural spec (elements + conditional states) - implement with Shadcn components and Tailwind utilities; do not ship the BEM classes or hand-written CSS.
-
-## Channel List
-
-Sidebar listing channels the user belongs to. Shows last message preview, unread count, and online presence.
-
-### Blueprint
-
-```html
-<div class="channel-list">
-
-  <div class="channel-list__header">
-    <img class="channel-list__user-avatar" src="" alt="" />
-    <h2 class="channel-list__title">Messages</h2>
-    <button class="channel-list__compose" aria-label="New message"></button>
-  </div>
-
-  <!-- OPTIONAL: search -->
-  <div class="channel-list__search">
-    <input class="channel-list__search-input" type="search" placeholder="Search" />
-  </div>
-
-  <div class="channel-list__items" role="listbox">
-
-    <button class="channel-list__item channel-list__item--active" role="option" aria-selected="true">
-      <!-- Modifiers: --active (selected), --unread (has unread), --muted -->
-      <div class="channel-list__item-avatar">
-        <img src="" alt="" />
-        <!-- CONDITIONAL: 1:1 channel -> other user's avatar; group -> channel image or stacked avatars -->
-        <!-- CONDITIONAL: other user is online -->
-        <span class="channel-list__item-presence channel-list__item-presence--online"></span>
-      </div>
-      <div class="channel-list__item-content">
-        <div class="channel-list__item-top">
-          <span class="channel-list__item-name"></span>
-          <time class="channel-list__item-time"></time>
-        </div>
-        <div class="channel-list__item-bottom">
-          <p class="channel-list__item-preview"></p>
-          <!-- CONDITIONAL: channel has unread messages -->
-          <span class="channel-list__item-unread">3</span>
-        </div>
-      </div>
-    </button>
-
-  </div>
-
-  <!-- States: channel-list__loading (skeleton), channel-list__empty, channel-list__error -->
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `channel-list__items` | `client.queryChannels(filter, sort, { watch: true, state: true })` | - | Returns array of `channel` objects |
-| `channel-list__item-avatar` (1:1) | Channel members | - | Other member's `user.image` |
-| `channel-list__item-avatar` (group) | `channel.data.image` | `channel.update({ image })` | `channel.data.image` |
-| `channel-list__item-name` (1:1) | Channel members | - | Other member's `user.name` |
-| `channel-list__item-name` (group) | `channel.data.name` | `channel.update({ name })` | `channel.data.name` |
-| `channel-list__item-preview` | Channel state | - | `channel.state.messages[last].text` - truncated |
-| `channel-list__item-time` | Channel state | - | `channel.state.messages[last].created_at` |
-| `channel-list__item-unread` | `channel.countUnread()` | `channel.markRead()` | Returns integer |
-| `channel-list__item-presence` | User presence events | - | `user.online` (boolean) |
-| `--active` modifier | Client-side selection state | - | Set when user clicks channel |
-| New channel | - | `client.channel(type, id, { name, members })` then `channel.watch()` | - |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Channel queries | `client.queryChannels(filter, sort, options)` | Available |
-| Real-time updates | `{ watch: true }` in query options | On by default - both `watch` and `state` default to `true` in `queryChannels` |
-| Presence | Dashboard -> Channel Type -> "Connect Events" enabled | Off per channel type |
-| Unread counts | `channel.countUnread()` | Available - relies on `channel.markRead()` being called |
-| Search | `client.search(filter, query)` or `client.queryChannels` with name filter | Available |
-
----
-
-## Channel Header
-
-Top bar of an active channel. Shows channel identity, members, and actions.
-
-### Blueprint
-
-```html
-<header class="channel-header">
-
-  <div class="channel-header__info">
-    <img class="channel-header__avatar" src="" alt="" />
-    <!-- CONDITIONAL: 1:1 -> presence dot on avatar -->
-    <span class="channel-header__presence channel-header__presence--online"></span>
-    <div class="channel-header__meta">
-      <h3 class="channel-header__name"></h3>
-      <!-- CONDITIONAL: 1:1 channel -> "Online" / "Last seen 2h ago" -->
-      <!-- CONDITIONAL: group channel -> "3 members, 2 online" -->
-      <span class="channel-header__status"></span>
-    </div>
-  </div>
-
-  <div class="channel-header__actions">
-    <button class="channel-header__action channel-header__action--search" aria-label="Search"></button>
-    <button class="channel-header__action channel-header__action--members" aria-label="Members"></button>
-    <!-- OPTIONAL: video/audio call -->
-    <button class="channel-header__action channel-header__action--call" aria-label="Call"></button>
-    <button class="channel-header__action channel-header__action--menu" aria-label="More"></button>
-  </div>
-
-</header>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `channel-header__avatar` | `channel.data` or member data | - | `channel.data.image` (group) or other member's `user.image` (1:1) |
-| `channel-header__name` | `channel.data` or member data | - | `channel.data.name` (group) or other member's `user.name` (1:1) |
-| `channel-header__status` (1:1) | Presence events | - | `user.online` -> "Online"; `user.last_active` -> "Last seen X ago" |
-| `channel-header__status` (group) | `channel.state.members`, `channel.state.watcher_count` | - | Count members + online watchers |
-| `channel-header__action--call` | - | Initiates Stream Video call (see VIDEO.md) | Cross-product integration |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Presence / last active | "Connect Events" enabled on channel type | Off |
-| Watcher count | `{ watch: true, presence: true }` on `channel.watch()` | Must pass explicitly |
-| Video/audio calls | Stream Video product enabled | Separate product |
-
----
-
-## Message List
-
-Scrollable container for messages. Handles date separators, scroll-to-bottom, and real-time message injection.
-
-### Blueprint
-
-```html
-<div class="message-list" role="log" aria-live="polite">
-
-  <!-- CONDITIONAL: older messages available -->
-  <div class="message-list__load-older">
-    <button class="message-list__load-older-btn">Load older messages</button>
-    <!-- Or: IntersectionObserver sentinel at top for infinite scroll -->
-  </div>
-
-  <!-- Date separator -->
-  <div class="message-list__date-separator">
-    <span class="message-list__date-label">March 17, 2026</span>
-  </div>
-
-  <!-- System/event message -->
-  <div class="message-list__event">
-    <span class="message-list__event-text">Jane added Alex to the channel</span>
-  </div>
-
-  <!-- Messages grouped by sender (consecutive messages from same user) -->
-  <div class="message-list__group message-list__group--other">
-    <!-- Modifiers: --own (current user) | --other -->
-    <!-- First message in group shows avatar + name, rest are compact -->
-    <div class="message-list__item message-list__item--first">
-      <!-- Insert Message component -->
-    </div>
-    <div class="message-list__item message-list__item--continuation">
-      <!-- Insert Message component (no avatar/name, compact spacing) -->
-    </div>
-  </div>
-
-  <!-- CONDITIONAL: typing indicator -->
-  <div class="message-list__typing">
-    <!-- See Typing Indicator component -->
-  </div>
-
-  <!-- CONDITIONAL: user has scrolled up, new messages below -->
-  <button class="message-list__scroll-to-bottom">
-    <!-- CONDITIONAL: unread count badge -->
-    <span class="message-list__new-count">5</span>
-  </button>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| Messages (initial) | `channel.watch()` or `channel.query({ messages: { limit: 25 } })` | - | `channel.state.messages` |
-| Messages (older) | `channel.query({ messages: { limit: 25, id_lt: oldestMessageId } })` | - | Prepend to message list |
-| Messages (real-time) | `channel.on('message.new', callback)` | - | Append new message to list |
-| Message groups | Client-side grouping | - | Group consecutive messages by `message.user.id` within a time window |
-| Date separators | Client-side | - | Insert when `message.created_at` crosses a day boundary |
-| System events | `channel.on('member.added', ...)`, `channel.on('member.removed', ...)` | - | Render as `message-list__event` |
-| Typing indicator | `channel.on('typing.start', ...)`, `channel.on('typing.stop', ...)` | - | `channel.state.typing` - map of userId -> event |
-| Scroll to bottom | Client-side scroll position tracking | - | Show when `scrollTop < threshold` |
-| `message-list__new-count` | Track messages received while scrolled up | - | Client-side counter |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Message history | `channel.watch()` or `channel.query()` | Available |
-| Real-time | `channel.watch()` establishes websocket | Automatic when channel is watched |
-| Typing events | "Typing Events" enabled on channel type in Dashboard | On for most types |
-| Read events | "Read Events" enabled on channel type | On for most types |
-| System events | Automatic on member add/remove | Available |
-
----
-
-## Message
-
-The core content unit in chat. A single message with author info, text, attachments, reactions, and thread.
-
-### Blueprint
-
-```html
-<div class="message">
-  <!-- Modifiers: message--own | message--other | message--deleted | message--pinned | message--highlighted | message--system -->
-  <!-- message--first (first in group, shows avatar/name) -->
-  <!-- message--continuation (same sender, compact) -->
-
-  <!-- CONDITIONAL: message--first in group only -->
-  <a class="message__actor" href="/user/{user.id}">
-    <img class="message__avatar" src="" alt="" />
-  </a>
-
-  <div class="message__content">
-    <!-- CONDITIONAL: message--first in group only -->
-    <div class="message__header">
-      <span class="message__author"></span>
-      <time class="message__time" datetime=""></time>
-    </div>
-
-    <!-- CONDITIONAL: message.pinned === true -->
-    <div class="message__pinned-badge">
-      Pinned by <span class="message__pinned-by"></span>
-    </div>
-
-    <div class="message__bubble">
-      <!-- CONDITIONAL: message.quoted_message exists (reply/quote) -->
-      <div class="message__quoted">
-        <span class="message__quoted-author"></span>
-        <p class="message__quoted-text"></p>
-      </div>
-
-      <!-- Parse @mentions -> <a class="message__mention">, URLs -> <a class="message__link"> -->
-      <p class="message__text"></p>
-
-      <!-- CONDITIONAL: message.attachments has type "image" -->
-      <div class="message__images">
-        <!-- Modifiers: message__images--single | --grid -->
-        <figure class="message__image-item">
-          <img src="" alt="" />
-        </figure>
-      </div>
-
-      <!-- CONDITIONAL: message.attachments has type "video" -->
-      <div class="message__video">
-        <video class="message__video-player" src="" controls></video>
-      </div>
-
-      <!-- CONDITIONAL: message.attachments has type "file" -->
-      <div class="message__files">
-        <a class="message__file" href="" download>
-          <span class="message__file-icon"></span>
-          <span class="message__file-name"></span>
-          <span class="message__file-size"></span>
-        </a>
-      </div>
-
-      <!-- CONDITIONAL: message.attachments has og_scrape_url (link preview) -->
-      <a class="message__og" href="" target="_blank" rel="noopener">
-        <img class="message__og-image" src="" alt="" />
-        <div class="message__og-content">
-          <span class="message__og-title"></span>
-          <span class="message__og-description"></span>
-          <span class="message__og-domain"></span>
-        </div>
-      </a>
-    </div>
-
-    <!-- CONDITIONAL: message.deleted_at exists -->
-    <div class="message__deleted">This message was deleted.</div>
-
-    <!-- Reactions row (inline, beneath bubble) -->
-    <!-- CONDITIONAL: message has any reactions -->
-    <div class="message__reactions">
-      <!-- One pill per reaction type -->
-      <button class="message__reaction">
-        <!-- Modifier: message__reaction--own when user has reacted with this type -->
-        <span class="message__reaction-emoji"></span>
-        <span class="message__reaction-count"></span>
-      </button>
-      <!-- Add reaction button -->
-      <button class="message__reaction message__reaction--add" aria-label="Add reaction"></button>
-    </div>
-
-    <!-- CONDITIONAL: message.reply_count > 0 -->
-    <button class="message__thread-reply">
-      <div class="message__thread-avatars">
-        <!-- Stacked avatars of thread participants -->
-        <img class="message__thread-avatar" src="" alt="" />
-      </div>
-      <span class="message__thread-count"></span>
-      <time class="message__thread-last" datetime=""></time>
-    </button>
-
-    <!-- Message status (own messages only) -->
-    <!-- CONDITIONAL: message--own -->
-    <div class="message__status">
-      <!-- Modifiers: message__status--sending | --sent | --delivered | --read -->
-      <!-- Read: show stacked read receipt avatars -->
-    </div>
-
-    <!-- Hover/long-press action bar -->
-    <div class="message__actions">
-      <button class="message__action message__action--react" aria-label="React"></button>
-      <button class="message__action message__action--reply" aria-label="Reply in thread"></button>
-      <button class="message__action message__action--quote" aria-label="Quote"></button>
-      <!-- CONDITIONAL: message.user.id === currentUserId -->
-      <button class="message__action message__action--edit" aria-label="Edit"></button>
-      <button class="message__action message__action--delete" aria-label="Delete"></button>
-      <!-- Always visible -->
-      <button class="message__action message__action--pin" aria-label="Pin"></button>
-      <button class="message__action message__action--flag" aria-label="Flag"></button>
-    </div>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `message__avatar` | In message payload | - | `message.user.image` |
-| `message__author` | In message payload | - | `message.user.name` |
-| `message__time` | In message payload | - | `message.created_at` |
-| `message__text` | In message payload | - | `message.text` |
-| `message__pinned-badge` | In message payload | - | `message.pinned`, `message.pinned_by.name` |
-| `message__quoted` | In message payload | - | `message.quoted_message.user.name`, `message.quoted_message.text` |
-| `message__image-item` | In message payload | - | `message.attachments[].image_url` where `type === 'image'` |
-| `message__video-player` | In message payload | - | `message.attachments[].asset_url` where `type === 'video'` |
-| `message__file` | In message payload | - | `message.attachments[].asset_url`, `.title`, `.file_size` where `type === 'file'` |
-| `message__og-*` | In message payload | - | `message.attachments[].og_scrape_url`, `.title`, `.text`, `.image_url` |
-| `message__deleted` | In message payload | - | `message.deleted_at` (truthy = deleted) |
-| `message__reaction` | In message payload | - | `message.reaction_groups` (keyed by type; each has `count`, `sum_scores`, `first_reaction_at`, `last_reaction_at`) - preferred. `message.reaction_counts` still works. Also `message.own_reactions[]` |
-| Reaction - add | - | `channel.sendReaction(message.id, { type: 'like' })` | Supports `{ enforce_unique: true }` option as third arg to replace all user's existing reactions |
-| Reaction - remove | - | `channel.deleteReaction(message.id, 'like')` | Removes current user's reaction of that type |
-| `message__thread-count` | In message payload | - | `message.reply_count` |
-| `message__thread-avatars` | In message payload | - | `message.thread_participants[].image` |
-| `message__thread-last` | Thread replies | - | Most recent reply's `created_at` (from `channel.getReplies()` or thread state) |
-| `message__status` (read) | `channel.state.read` | - | Map of `userId -> { last_read, user }` - compare with `message.created_at` |
-| Edit | - | `client.updateMessage({ id: message.id, text: newText })` | - |
-| Delete | - | `client.deleteMessage(message.id)` | Sets `message.deleted_at`. Pass `{ hardDelete: true }` for permanent deletion |
-| Pin | - | `client.pinMessage(message, timeoutOrExpiration)` | Accepts a message object or message id. Second arg is optional: timeout in seconds, expiration date, or null for no expiry |
-| Unpin | - | `client.unpinMessage(message)` | Accepts a message object or message id |
-| `message__mentioned-users` | In message payload | - | `message.mentioned_users` - enriched user objects for @mentions in the message |
-| Flag | - | `client.flagMessage(message.id)` | See MODERATION.md |
-| Mute user | - | `client.muteUser(userId, null, { timeout: 60 })` | Three args: userId, null, options object. `timeout` is in minutes |
-| Quote | - | Send new message with `quoted_message_id: message.id` | - |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Attachments | "Uploads" enabled on channel type | On |
-| Reactions | "Reactions" enabled on channel type in Dashboard | On |
-| Replies/threads | "Replies" enabled on channel type | On |
-| Read receipts | "Read Events" enabled on channel type | On for most types |
-| URL enrichment | "URL Enrichment" enabled on channel type | On - auto-scrapes OG data server-side |
-| Pinning | "Pinning" enabled on channel type | Off |
-| Quoting | `quoted_message_id` on `sendMessage` | Available - no config needed |
-| Message editing | - | Available - own messages by default, admin can edit any |
-| Message deletion | - | Available - own messages by default, admin can delete any |
-
----
-
-## Message Input
-
-Text input for composing and sending messages. Handles attachments, mentions, slash commands, and edit mode.
-
-### Blueprint
-
-```html
-<div class="message-input">
-  <!-- Modifier: message-input--editing (when editing an existing message) -->
-  <!-- Modifier: message-input--disabled (when user lacks send permission) -->
-  <!-- Modifier: message-input--thread (when in thread view) -->
-
-  <!-- CONDITIONAL: editing a message -->
-  <div class="message-input__edit-banner">
-    Editing message
-    <button class="message-input__edit-cancel" aria-label="Cancel edit"></button>
-  </div>
-
-  <!-- CONDITIONAL: replying with quote -->
-  <div class="message-input__quote-preview">
-    <span class="message-input__quote-author"></span>
-    <p class="message-input__quote-text"></p>
-    <button class="message-input__quote-remove" aria-label="Remove quote"></button>
-  </div>
-
-  <!-- CONDITIONAL: user has selected files to upload -->
-  <div class="message-input__attachments">
-    <div class="message-input__attachment">
-      <!-- Modifiers: --image | --file | --uploading | --error -->
-      <img class="message-input__attachment-preview" src="" alt="" />
-      <button class="message-input__attachment-remove" aria-label="Remove"></button>
-      <div class="message-input__attachment-progress">
-        <div class="message-input__attachment-progress-bar" style="width: 0%"></div>
-      </div>
-    </div>
-  </div>
-
-  <div class="message-input__composer">
-    <div class="message-input__tools-left">
-      <button class="message-input__tool message-input__tool--attach" aria-label="Attach file"></button>
-    </div>
-
-    <div class="message-input__text-area">
-      <div class="message-input__text" contenteditable="true" role="textbox" aria-multiline="true" data-placeholder="Send a message"></div>
-
-      <!-- CONDITIONAL: user types "@" + characters -->
-      <div class="message-input__mention-dropdown">
-        <button class="message-input__mention-option">
-          <img class="message-input__mention-avatar" src="" alt="" />
-          <span class="message-input__mention-name"></span>
-        </button>
-      </div>
-
-      <!-- CONDITIONAL: user types "/" (slash commands) -->
-      <div class="message-input__command-dropdown">
-        <button class="message-input__command-option">
-          <span class="message-input__command-name">/giphy</span>
-          <span class="message-input__command-desc">Post a random GIF</span>
-        </button>
-      </div>
-    </div>
-
-    <div class="message-input__tools-right">
-      <button class="message-input__tool message-input__tool--emoji" aria-label="Emoji"></button>
-      <button class="message-input__send" aria-label="Send" disabled></button>
-    </div>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `message-input__text` | - (user input) | Becomes `message.text` | - |
-| `message-input__mention-dropdown` | `channel.queryMembers({ name: { $autocomplete: query } })` | - | Match typed query against channel members |
-| `message-input__command-dropdown` | `channel.getConfig()` | - | `channel.config.commands[]` - name + description |
-| `message-input__attachment` (image) | Local blob preview | `channel.sendImage(file)` -> CDN URL | Collect into `message.attachments[]` with `type: 'image'` |
-| `message-input__attachment` (file) | Local blob preview | `channel.sendFile(file)` -> CDN URL | Collect into `message.attachments[]` with `type: 'file'` |
-| Attachment remove (image) | - | `channel.deleteImage(url)` | Deletes uploaded image from CDN when user removes before sending |
-| Attachment remove (file) | - | `channel.deleteFile(url)` | Deletes uploaded file from CDN when user removes before sending |
-| Send (new) | - | `channel.sendMessage({ text, attachments, quoted_message_id?, mentioned_users? })` | `mentioned_users` is an array of user IDs referenced via @mentions in the text |
-| Send (edit) | - | `client.updateMessage({ id, text, attachments })` | - |
-| Send (thread) | - | `channel.sendMessage({ text, parent_id: parentMessage.id })` | - |
-| Typing events | - | `channel.keystroke()` on input, `channel.stopTyping()` on pause | Debounced - SDK handles interval |
-| `--disabled` | `channel.data.own_capabilities` | - | Check if `'send-message'` is in capabilities array |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| File uploads | "Uploads" enabled on channel type | On |
-| Slash commands | Commands configured on channel type in Dashboard | `/giphy` available by default |
-| @Mentions | Channel members queryable | Available - searches channel members |
-| Typing indicators | "Typing Events" enabled on channel type | On for most |
-| Message length | `channel.config.max_message_length` | 5000 chars (server-side default) |
-| Slow mode | `channel.data.cooldown` (seconds) | Off - set per channel |
-
----
-
-## Thread
-
-Reply thread on a specific message. Opens as a side panel or overlay.
-
-### Blueprint
-
-```html
-<div class="thread">
-
-  <header class="thread__header">
-    <h3 class="thread__title">Thread</h3>
-    <span class="thread__count"></span>
-    <button class="thread__close" aria-label="Close thread"></button>
-  </header>
-
-  <!-- Parent message (the message being replied to) -->
-  <div class="thread__parent">
-    <!-- Insert Message component (with thread-reply button hidden) -->
-  </div>
-
-  <div class="thread__separator">
-    <span class="thread__reply-count"></span>
-  </div>
-
-  <!-- Reply list (same structure as Message List, but for thread replies) -->
-  <div class="thread__replies" role="log">
-    <div class="thread__reply">
-      <!-- Insert Message component -->
-    </div>
-  </div>
-
-  <!-- Thread-specific message input -->
-  <div class="thread__input">
-    <!-- Insert Message Input component with message-input--thread modifier -->
-    <!-- OPTIONAL: "Also send to channel" checkbox -->
-    <label class="thread__send-to-channel">
-      <input type="checkbox" />
-      Also send to #channel-name
-    </label>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `thread__parent` | Already in message list | - | The message with `reply_count > 0` |
-| `thread__replies` | `channel.getReplies(parentMessage.id, { limit: 25 })` | - | Returns `{ messages: [...] }` |
-| `thread__replies` (older) | `channel.getReplies(parentId, { limit: 25, id_lt: oldestReplyId })` | - | Cursor pagination |
-| `thread__replies` (real-time) | `channel.on('message.new', cb)` - filter where `message.parent_id === parentId` | - | Append to reply list |
-| `thread__reply-count` | Parent message | - | `parentMessage.reply_count` |
-| Reply - send | - | `channel.sendMessage({ text, parent_id: parentMessage.id })` | - |
-| Reply - send to channel | - | `channel.sendMessage({ text, parent_id: parentMessage.id, show_in_channel: true })` | Shows reply in main channel too |
-| All threads | `client.queryThreads()` | - | Lists all threads the current user participates in - supports pagination and filtering |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Replies/threads | "Replies" enabled on channel type in Dashboard | On |
-| Thread participants | Automatic | Tracked in `message.thread_participants` |
-
----
-
-## Typing Indicator
-
-Shows who is currently typing in the channel.
-
-### Blueprint
-
-```html
-<!-- CONDITIONAL: channel.state.typing has entries (excluding current user) -->
-<div class="typing-indicator">
-  <div class="typing-indicator__avatars">
-    <img class="typing-indicator__avatar" src="" alt="" />
-    <!-- Max 2-3 avatars -->
-  </div>
-  <div class="typing-indicator__dots">
-    <span class="typing-indicator__dot"></span>
-    <span class="typing-indicator__dot"></span>
-    <span class="typing-indicator__dot"></span>
-  </div>
-  <span class="typing-indicator__text">
-    <!-- 1 user: "Jane is typing" -->
-    <!-- 2 users: "Jane and Alex are typing" -->
-    <!-- 3+: "3 people are typing" -->
-  </span>
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| Typing users | `channel.on('typing.start', cb)`, `channel.on('typing.stop', cb)` | `channel.keystroke()` / `channel.stopTyping()` | `channel.state.typing` - map of userId -> `{ user }`, excludes current user. For threads: `channel.keystroke(threadId)` sends thread-specific typing events |
-| `typing-indicator__avatar` | In typing event | - | `event.user.image` |
-| Auto-expiry | Client-side | - | Remove user from typing state after ~7s with no new `typing.start` event |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Typing events | "Typing Events" enabled on channel type | On for most types |
-
----
-
-## Emoji Reaction Picker
-
-Overlay for selecting a reaction to add to a message. Typically triggered from message action bar or existing reaction row.
-
-### Blueprint
-
-```html
-<div class="reaction-picker">
-  <!-- Quick reactions row (most common) -->
-  <div class="reaction-picker__quick">
-    <button class="reaction-picker__emoji" data-type="like">&#x1F44D;</button>
-    <button class="reaction-picker__emoji" data-type="love">&#x2764;</button>
-    <button class="reaction-picker__emoji" data-type="haha">&#x1F602;</button>
-    <button class="reaction-picker__emoji" data-type="wow">&#x1F632;</button>
-    <button class="reaction-picker__emoji" data-type="sad">&#x1F622;</button>
-    <button class="reaction-picker__emoji" data-type="angry">&#x1F621;</button>
-  </div>
-  <!-- OPTIONAL: full emoji picker with categories and search -->
-  <button class="reaction-picker__more" aria-label="More reactions"></button>
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| Emoji click | - | `channel.sendReaction(message.id, { type: 'like' })` | Type is the `data-type` attribute. Pass `{ enforce_unique: true }` as third arg to replace user's existing reactions |
-| Toggle off | Check `message.own_reactions` for existing reaction of same type | `channel.deleteReaction(message.id, 'like')` | - |
-| Available types | - | Any string works as reaction type | No configuration needed for custom types |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Reactions | "Reactions" enabled on channel type | On |
-
----
-
-## Search
-
-Search messages across channels or within a specific channel.
-
-### Blueprint
-
-```html
-<div class="search">
-
-  <div class="search__input-area">
-    <span class="search__icon"></span>
-    <input class="search__input" type="search" placeholder="Search messages" />
-    <!-- CONDITIONAL: query is non-empty -->
-    <button class="search__clear" aria-label="Clear search"></button>
-  </div>
-
-  <!-- CONDITIONAL: search has results -->
-  <div class="search__results">
-    <button class="search__result">
-      <img class="search__result-avatar" src="" alt="" />
-      <div class="search__result-content">
-        <div class="search__result-top">
-          <span class="search__result-author"></span>
-          <span class="search__result-channel">#general</span>
-          <time class="search__result-time"></time>
-        </div>
-        <p class="search__result-text">
-          <!-- Highlight matching text with <mark class="search__highlight"> -->
-        </p>
-      </div>
-    </button>
-  </div>
-
-  <!-- States: search__loading, search__empty ("No results for ...") -->
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `search__results` | `client.search({ members: { $in: [userId] } }, query, { limit: 20 })` | - | Returns `{ results: [{ message }] }` |
-| `search__results` (in-channel) | `client.search({ cid: channel.cid }, query, { limit: 20 })` | - | Filter by specific channel |
-| `search__result-avatar` | In result | - | `result.message.user.image` |
-| `search__result-author` | In result | - | `result.message.user.name` |
-| `search__result-channel` | In result | - | `result.message.channel.name` or `result.message.channel.id` |
-| `search__result-text` | In result | - | `result.message.text` - add highlights client-side |
-| Result click | - | Navigate to message in channel | `result.message.channel` + `result.message.id` |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Search | "Search" enabled on channel type | On |
-| Cross-channel | `client.search()` with filter across channels | Available |
+For fully hand-built, bespoke UI on the low-level client - when the prebuilt components above can't be customized into the target - see [`custom-ui.md`](custom-ui.md): the prebuilt-vs-bespoke decision, the headless context-hook map, and per-region routing to the live docs. Don't hand-build a messenger you could have themed; default to the prebuilt path above.
diff --git a/skills/stream-react/references/CHAT.md b/skills/stream-react/references/CHAT.md
index 2eb7cfb..0679bbb 100644
--- a/skills/stream-react/references/CHAT.md
+++ b/skills/stream-react/references/CHAT.md
@@ -1,21 +1,20 @@
 # Chat - Setup & Integration
 
-Stream Chat provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For full component structure and wiring, see [CHAT-blueprints.md](CHAT-blueprints.md).
+Stream Chat provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + props), see [CHAT-blueprints.md](CHAT-blueprints.md); for fully bespoke UI on the low-level client, see [custom-ui.md](custom-ui.md).
 
 Rules: [../RULES.md](../RULES.md) (login screen first, strict mode protection, reference authority) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
-- **Blueprint** - HTML with BEM classes defining structure and conditional rendering
-- **Wiring** - API calls to read/write each element, exact property paths
-- **Requirements** - Dashboard settings, API params, and prerequisites. The **Default** column in each Requirements table reflects server-side channel-type defaults (set in the Dashboard / via the API), not values enforced by the SDK.
+- **Prebuilt path** ([CHAT-blueprints.md](CHAT-blueprints.md)) - the canonical provider tree, the prebuilt component prop table, and the `WithComponents` customization mechanism. The common path for every messenger.
+- **Bespoke path** ([custom-ui.md](custom-ui.md)) - the prebuilt-vs-bespoke decision + the headless context-hook map for fully hand-built UI.
+- **Live docs** ([docs-map.md](docs-map.md)) - fetch the matching component / cookbook / advanced page before building any customization. Server-side channel-type **defaults** (permissions, features) are set in the Dashboard / via the API, not enforced by the SDK.
 
 ## Quick ref
 
 - **Packages:** `stream-chat`, `stream-chat-react`; import `stream-chat-react/css/index.css` (v14+ preferred alias; v13 used `dist/css/v2/index.css`).
 - **First:** **App Integration** -> **Setup** (CLI / channel types) before UI.
-- **Per feature:** Jump to section (Channel List, Message List, ...) when implementing that screen.
-- **Below the next rule:** full blueprints - **do not load past it** until you implement that component.
+- **Per feature:** fetch the matching live page from [docs-map.md](docs-map.md) before implementing that screen; for fully hand-built UI on the low-level client, see [custom-ui.md](custom-ui.md).
 
-Full component blueprints: [CHAT-blueprints.md](CHAT-blueprints.md) - load only the section you are implementing.
+Prebuilt component path: [CHAT-blueprints.md](CHAT-blueprints.md) - the canonical provider tree + props. Bespoke UI on the low-level client: [custom-ui.md](custom-ui.md).
 
 ---
 
diff --git a/skills/stream-react/references/FEEDS-blueprints.md b/skills/stream-react/references/FEEDS-blueprints.md
index c818860..78b06a6 100644
--- a/skills/stream-react/references/FEEDS-blueprints.md
+++ b/skills/stream-react/references/FEEDS-blueprints.md
@@ -76,7 +76,7 @@ Individual activity card showing author, content, reactions, comments, and actio
 
   <!-- CONDITIONAL: has poll -->
   <div class="post-card__poll">
-    <!-- No bundled Poll blueprint - fetch the Polls page (DOCS.md > Feeds) before building -->
+    <!-- No bundled Poll blueprint - fetch the Polls page (docs-map.md > Feeds) before building -->
   </div>
 
   <div class="post-card__actions">
diff --git a/skills/stream-react/references/VIDEO-blueprints.md b/skills/stream-react/references/VIDEO-blueprints.md
index cce2d29..1c09237 100644
--- a/skills/stream-react/references/VIDEO-blueprints.md
+++ b/skills/stream-react/references/VIDEO-blueprints.md
@@ -2,7 +2,7 @@
 
 Setup, routes, and gotchas: [VIDEO.md](VIDEO.md). Rules: [`../RULES.md`](../RULES.md) (reference authority, strict mode protection) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
-**Build the common path with `@stream-io/video-react-sdk`'s prebuilt components and customize via `useCallStateHooks()` + `ParticipantView`.** Only drop to the hand-built markup in **Fully custom UI (fallback)** below when the user explicitly wants fully bespoke UI - and even then, fetch the matching docs page first ([`DOCS.md`](DOCS.md)).
+**Build the common path with `@stream-io/video-react-sdk`'s prebuilt components and customize via `useCallStateHooks()` + `ParticipantView`.** For fully hand-built, bespoke UI on the low-level client, see [`custom-ui.md`](custom-ui.md) - and even then, fetch the matching docs page first ([`docs-map.md`](docs-map.md)).
 
 ---
 
@@ -54,477 +54,10 @@ const [spotlight, ...others] = useParticipants();
 
 **Customization hooks:** the umbrella is `useCallStateHooks()`, which returns sub-hooks you destructure: `useParticipants`, `useLocalParticipant`, `useRemoteParticipants`, `useCallCallingState`, `useCameraState`, `useMicrophoneState`, `useScreenShareState`, `useDominantSpeaker`, `useParticipantCount`, `useOwnCapabilities`, `useIsCallRecordingInProgress`, ... Plus `useCall()` and `useStreamVideoClient()`. Usage: `const { useCameraState } = useCallStateHooks(); const { camera, isMute } = useCameraState(); camera.toggle();`
 
-**Docs-first:** for any customization (replacing call controls, custom layouts, lobby preview, PiP, network quality, livestream watching, ringing, ...) fetch the matching page from [`DOCS.md`](DOCS.md) first. Component reference pages live at `https://getstream.io/video/docs/react/ui-components/...`.
+**Docs-first:** for any customization (replacing call controls, custom layouts, lobby preview, PiP, network quality, livestream watching, ringing, ...) fetch the matching page from [`docs-map.md`](docs-map.md) first. Component reference pages live at `https://getstream.io/video/docs/react/ui-components/...`.
 
 ---
 
 ## Fully custom UI (fallback)
 
-> **Use these only when the user explicitly wants bespoke, fully hand-built UI** (not the prebuilt components above). Each section gives the raw element structure + a wiring table mapping DOM to SDK calls. Still fetch the matching [`DOCS.md`](DOCS.md) page first. The BEM class names are a structural spec (elements + conditional states) - implement with Shadcn components and Tailwind utilities; do not ship the BEM classes or hand-written CSS.
-
-## Lobby
-
-Pre-join screen where users preview their camera/mic and set preferences before entering a call.
-
-### Blueprint
-
-```html
-<div class="lobby">
-
-  <div class="lobby__preview">
-    <!-- Local camera preview -->
-    <video class="lobby__video" autoplay muted playsinline></video>
-    <!-- CONDITIONAL: camera is off -->
-    <div class="lobby__video-off">
-      <img class="lobby__avatar" src="" alt="" />
-      <span class="lobby__name"></span>
-    </div>
-    <!-- CONDITIONAL: mic is on - show audio level visualization -->
-    <div class="lobby__audio-level">
-      <div class="lobby__audio-level-bar"></div>
-    </div>
-  </div>
-
-  <div class="lobby__controls">
-    <button class="lobby__toggle lobby__toggle--camera" aria-pressed="true" aria-label="Toggle camera">
-      <!-- aria-pressed="false" + modifier --off when camera disabled -->
-    </button>
-    <button class="lobby__toggle lobby__toggle--mic" aria-pressed="true" aria-label="Toggle microphone">
-      <!-- aria-pressed="false" + modifier --off when mic disabled -->
-    </button>
-  </div>
-
-  <!-- Device selectors -->
-  <div class="lobby__devices">
-    <select class="lobby__device-select lobby__device-select--camera" aria-label="Camera"></select>
-    <select class="lobby__device-select lobby__device-select--mic" aria-label="Microphone"></select>
-    <select class="lobby__device-select lobby__device-select--speaker" aria-label="Speaker"></select>
-    <!-- Populated from call.{device}.listDevices() -->
-  </div>
-
-  <div class="lobby__info">
-    <h2 class="lobby__call-title"></h2>
-    <!-- CONDITIONAL: other participants already in call -->
-    <div class="lobby__participants-preview">
-      <img class="lobby__participant-avatar" src="" alt="" />
-      <span class="lobby__participants-text">3 others already in this call</span>
-    </div>
-  </div>
-
-  <div class="lobby__actions">
-    <button class="lobby__join">Join call</button>
-    <button class="lobby__cancel">Cancel</button>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `lobby__video` | `call.camera.state.mediaStream` | Assign stream to video element's `srcObject` | Local media stream |
-| `lobby__toggle--camera` | `call.camera.state.status` | `call.camera.enable()` / `call.camera.disable()` | `'enabled'` or `'disabled'` |
-| `lobby__toggle--mic` | `call.microphone.state.status` | `call.microphone.enable()` / `call.microphone.disable()` | `'enabled'` or `'disabled'` |
-| `lobby__device-select--camera` | `call.camera.listDevices()` | `call.camera.select(deviceId)` | RxJS Observable of `MediaDeviceInfo[]` |
-| `lobby__device-select--mic` | `call.microphone.listDevices()` | `call.microphone.select(deviceId)` | RxJS Observable of `MediaDeviceInfo[]` |
-| `lobby__device-select--speaker` | `call.speaker.listDevices()` | `call.speaker.select(deviceId)` | RxJS Observable of `MediaDeviceInfo[]` |
-| `lobby__call-title` | `call.state.custom.title` or `call.id` | - | Set during `call.getOrCreate({ data: { custom: { title } } })` |
-| `lobby__participants-preview` | `call.state.participants` | - | Participants already joined |
-| `lobby__join` | - | `call.join()` | Transitions to call layout |
-| `lobby__cancel` | - | `call.leave()` | Navigates away |
-| `lobby__audio-level` | `call.microphone.state.mediaStream` | - | Use `AudioContext` + `AnalyserNode` on the stream |
-
-> `call.{camera,microphone,speaker}.listDevices()` returns an **RxJS Observable** of `MediaDeviceInfo[]` - you must `.subscribe()` to it (it is not an array). Inside a `<StreamCall>` context, prefer `useCameraState().devices` / `useMicrophoneState().devices` / `useSpeakerState().devices`, which are already-resolved arrays.
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Camera/mic access | Browser `getUserMedia` permission | Prompted on first access |
-| Call reference | `call = client.call(callType, callId)` then `call.getOrCreate()` | Must create before lobby |
-| Device enumeration | `navigator.mediaDevices.enumerateDevices()` | Available after permission grant |
-| Participants preview | `call.getOrCreate()` returns current participants | Available |
-
----
-
-## Call Layout
-
-Container for the active call. Manages participant arrangement in different layout modes.
-
-### Blueprint
-
-```html
-<div class="call-layout">
-  <!-- Modifiers: call-layout--grid | --speaker | --spotlight | --pip -->
-
-  <!-- GRID: all participants equal size -->
-  <div class="call-layout__grid">
-    <!-- Insert Participant Tile components -->
-    <!-- Grid adapts: 1 = full, 2 = side-by-side, 3-4 = 2x2, 5-9 = 3x3, etc. -->
-  </div>
-
-  <!-- SPEAKER: active speaker large, others in strip -->
-  <div class="call-layout__speaker">
-    <div class="call-layout__speaker-main">
-      <!-- Insert Participant Tile for dominant speaker (large) -->
-    </div>
-    <div class="call-layout__speaker-strip">
-      <!-- Insert Participant Tile components (small) for remaining participants -->
-    </div>
-  </div>
-
-  <!-- SPOTLIGHT: screen share or pinned participant fills main area -->
-  <div class="call-layout__spotlight">
-    <div class="call-layout__spotlight-main">
-      <!-- Screen share surface OR pinned participant -->
-    </div>
-    <div class="call-layout__spotlight-strip">
-      <!-- All other participants in strip -->
-    </div>
-  </div>
-
-  <!-- CONDITIONAL: screen share active - auto-switch to spotlight layout -->
-  <div class="call-layout__screen-share">
-    <video class="call-layout__screen-share-video" autoplay playsinline></video>
-    <div class="call-layout__screen-share-label">
-      <img class="call-layout__screen-share-avatar" src="" alt="" />
-      <span class="call-layout__screen-share-name"></span> is sharing their screen
-    </div>
-  </div>
-
-  <!-- Self-view (Picture-in-Picture overlay) -->
-  <div class="call-layout__self-view" draggable="true">
-    <!-- Insert Participant Tile for local participant (compact) -->
-  </div>
-
-  <!-- CONDITIONAL: someone is requesting to join (for calls requiring permission) -->
-  <div class="call-layout__join-request">
-    <img class="call-layout__join-request-avatar" src="" alt="" />
-    <span class="call-layout__join-request-name"></span> wants to join
-    <button class="call-layout__join-request-accept">Accept</button>
-    <button class="call-layout__join-request-reject">Reject</button>
-  </div>
-
-  <!-- Call controls (always visible at bottom) -->
-  <div class="call-layout__controls">
-    <!-- Insert Call Controls component -->
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| Participant list | `call.state.participants` | - | Array of `StreamVideoParticipant` objects |
-| Dominant speaker | `call.state.dominantSpeaker` | - | Updates in real-time |
-| Screen share track | `participant.screenShareStream` | - | Non-null when participant is screen sharing |
-| `call-layout__screen-share-video` | Screen share participant's video track | Assign to `srcObject` | `participant.screenShareStream` |
-| Layout mode | Client-side state | - | Auto-switch to spotlight when screen share starts |
-| Self-view | `call.state.localParticipant` | - | Current user's participant object |
-| Join request | `call.on('call.permission_request', cb)` | `call.grantPermissions(userId, ['send-audio','send-video'])` / `call.revokePermissions(userId, [...])` | `permissions` (string[]) is **required** - the second arg lists the capabilities to grant/revoke |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Call joined | `call.join()` completed | - |
-| Dominant speaker | Automatic | Available - determined server-side from audio levels |
-| Screen sharing | `call.screenShare.enable()` | Available - browser `getDisplayMedia` |
-| Layout modes | Client-side | No config - implement layout logic based on participant count and screen share state |
-| Join requests | Call type configured with `join_ahead_time_seconds` or backstage mode | Off |
-
----
-
-## Participant Tile
-
-Individual participant's video/audio in the call. Used inside call layouts.
-
-### Blueprint
-
-```html
-<div class="participant-tile">
-  <!-- Modifiers: --speaking | --muted | --video-off | --pinned | --local | --dominant -->
-
-  <!-- Video layer -->
-  <video class="participant-tile__video" autoplay playsinline></video>
-  <!-- CONDITIONAL: video track is off -->
-  <div class="participant-tile__video-off">
-    <img class="participant-tile__avatar" src="" alt="" />
-  </div>
-
-  <!-- Overlays -->
-  <div class="participant-tile__overlay">
-    <div class="participant-tile__info">
-      <span class="participant-tile__name"></span>
-      <!-- CONDITIONAL: participant is muted -->
-      <span class="participant-tile__muted-icon" aria-label="Muted"></span>
-    </div>
-
-    <!-- CONDITIONAL: speaking - audio level border/ring -->
-    <div class="participant-tile__speaking-border"></div>
-
-    <!-- CONDITIONAL: network quality degraded -->
-    <div class="participant-tile__network">
-      <!-- Modifiers: --good | --ok | --poor -->
-      <span class="participant-tile__network-icon"></span>
-    </div>
-
-    <!-- Action menu (on hover/long press) -->
-    <div class="participant-tile__actions">
-      <button class="participant-tile__action participant-tile__action--pin" aria-label="Pin"></button>
-      <button class="participant-tile__action participant-tile__action--fullscreen" aria-label="Fullscreen"></button>
-      <!-- CONDITIONAL: current user is host/admin -->
-      <button class="participant-tile__action participant-tile__action--mute" aria-label="Mute participant"></button>
-      <button class="participant-tile__action participant-tile__action--remove" aria-label="Remove from call"></button>
-    </div>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `participant-tile__video` | Participant's video track | Assign to `srcObject` | `participant.videoStream` |
-| `participant-tile__avatar` | Participant data | - | `participant.image` |
-| `participant-tile__name` | Participant data | - | `participant.name` or `participant.userId` |
-| `--speaking` modifier | Participant audio state | - | `participant.isSpeaking` (boolean) |
-| `--muted` modifier | Participant audio state | - | `participant.audioStream` is null or `!hasAudio(participant)` (import `hasAudio` from `@stream-io/video-client`) |
-| `--video-off` modifier | Participant video state | - | `participant.videoStream` is null or `!hasVideo(participant)` (import `hasVideo` from `@stream-io/video-client`) |
-| `--dominant` modifier | `call.state.dominantSpeaker` | - | `participant.isDominantSpeaker` |
-| Network quality | Participant stats | - | `participant.connectionQuality` - `ConnectionQuality.EXCELLENT`, `.GOOD`, `.POOR`, `.UNSPECIFIED` |
-| Pin | - | Client-side state | Layout prioritizes pinned participant |
-| Mute participant | - | `call.muteUser(userId, 'audio')` | Host/admin only |
-| Remove participant | - | `call.kickUser({ user_id: userId })` | Host/admin only. Removes from the call; add `block: true` to also ban from rejoining. `call.blockUser(userId)` *bans* without removing - not the same as "remove" |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Video rendering | Participant has granted camera permission and is publishing | - |
-| Audio rendering | Attach `participant.audioStream` to an `<audio>` element (not in tile HTML - managed globally) | - |
-| Network quality | Automatic | Available - tracked by SDK |
-| Host controls (mute/remove) | User has `call.state.ownCapabilities` including `'mute-users'`, `'remove-call-member'` (remove/kick), `'block-users'` (ban) | Depends on call type role |
-
----
-
-## Call Controls
-
-Bottom bar with call action buttons: mic, camera, screen share, participants, reactions, leave/end.
-
-### Blueprint
-
-```html
-<div class="call-controls">
-
-  <div class="call-controls__group call-controls__group--media">
-    <button class="call-controls__btn call-controls__btn--mic" aria-pressed="true" aria-label="Toggle microphone">
-      <!-- aria-pressed="false" + modifier --off when muted -->
-      <span class="call-controls__icon call-controls__icon--mic"></span>
-      <!-- OPTIONAL: device selector dropdown arrow -->
-      <button class="call-controls__device-toggle call-controls__device-toggle--mic" aria-label="Select microphone"></button>
-    </button>
-
-    <button class="call-controls__btn call-controls__btn--camera" aria-pressed="true" aria-label="Toggle camera">
-      <span class="call-controls__icon call-controls__icon--camera"></span>
-      <button class="call-controls__device-toggle call-controls__device-toggle--camera" aria-label="Select camera"></button>
-    </button>
-
-    <button class="call-controls__btn call-controls__btn--screen-share" aria-pressed="false" aria-label="Share screen">
-      <span class="call-controls__icon call-controls__icon--screen-share"></span>
-    </button>
-  </div>
-
-  <div class="call-controls__group call-controls__group--actions">
-    <!-- OPTIONAL: in-call reactions (raise hand, emoji) -->
-    <button class="call-controls__btn call-controls__btn--reactions" aria-label="Reactions">
-      <span class="call-controls__icon call-controls__icon--reactions"></span>
-    </button>
-
-    <button class="call-controls__btn call-controls__btn--participants" aria-label="Participants">
-      <span class="call-controls__icon call-controls__icon--participants"></span>
-      <!-- Badge with participant count -->
-      <span class="call-controls__badge"></span>
-    </button>
-
-    <!-- OPTIONAL: chat alongside video -->
-    <button class="call-controls__btn call-controls__btn--chat" aria-label="Chat">
-      <span class="call-controls__icon call-controls__icon--chat"></span>
-      <!-- CONDITIONAL: unread messages -->
-      <span class="call-controls__badge"></span>
-    </button>
-
-    <!-- OPTIONAL: recording (host/admin only) -->
-    <button class="call-controls__btn call-controls__btn--record" aria-pressed="false" aria-label="Record">
-      <!-- Modifier: --recording when active -->
-      <span class="call-controls__icon call-controls__icon--record"></span>
-    </button>
-  </div>
-
-  <div class="call-controls__group call-controls__group--leave">
-    <button class="call-controls__btn call-controls__btn--leave call-controls__btn--danger" aria-label="Leave call">
-      <span class="call-controls__icon call-controls__icon--leave"></span>
-      Leave
-    </button>
-    <!-- CONDITIONAL: current user is host -->
-    <!-- Show dropdown: "Leave call" vs "End call for everyone" -->
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `--mic` | `call.microphone.state.status` | `call.microphone.toggle()` | `'enabled'` or `'disabled'` |
-| `--camera` | `call.camera.state.status` | `call.camera.toggle()` | `'enabled'` or `'disabled'` |
-| `--screen-share` | `call.screenShare.state.status` | `call.screenShare.toggle()` | `'enabled'` or `'disabled'` |
-| Mic device select | `call.microphone.listDevices()` | `call.microphone.select(deviceId)` | - |
-| Camera device select | `call.camera.listDevices()` | `call.camera.select(deviceId)` | - |
-| `--participants` badge | `call.state.participants` | - | `call.state.participants.length` |
-| `--record` | `call.state.recording` | `call.startRecording()` / `call.stopRecording()` | Boolean |
-| `--reactions` | - | `call.sendReaction({ type: 'raised-hand' })` | Custom reaction types |
-| `--leave` | - | `call.leave()` | Leaves call, keeps it running for others |
-| End call | - | `call.endCall()` | Ends for all participants - host only |
-| `--chat` badge | Unread count in associated chat channel | - | Cross-product: Stream Chat channel linked to call |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Screen sharing | Browser `getDisplayMedia` support | Available in desktop browsers |
-| Recording | Dashboard -> Call Types -> Recording enabled | Off - requires plan support |
-| In-call reactions | - | Available - `call.sendReaction()` |
-| End call (for all) | User must have `'end-call'` capability | Host/admin role only |
-| In-call chat | Chat product integrated, channel linked to call | Separate setup |
-
----
-
-## Incoming Call
-
-Ringing UI when another user initiates a call. Shown as overlay or notification.
-
-### Blueprint
-
-```html
-<div class="incoming-call">
-
-  <div class="incoming-call__info">
-    <img class="incoming-call__avatar" src="" alt="" />
-    <!-- CONDITIONAL: group call - show multiple avatars or group name -->
-    <span class="incoming-call__caller-name"></span>
-    <span class="incoming-call__type">
-      <!-- "Video call" or "Audio call" based on call type -->
-    </span>
-  </div>
-
-  <div class="incoming-call__actions">
-    <button class="incoming-call__btn incoming-call__btn--reject" aria-label="Decline">
-      <span class="incoming-call__icon incoming-call__icon--reject"></span>
-      Decline
-    </button>
-    <button class="incoming-call__btn incoming-call__btn--accept" aria-label="Accept">
-      <span class="incoming-call__icon incoming-call__icon--accept"></span>
-      Accept
-    </button>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `incoming-call__avatar` | Ring event | - | `call.state.createdBy.image` or caller's user image |
-| `incoming-call__caller-name` | Ring event | - | `call.state.createdBy.name` |
-| `incoming-call__type` | Call metadata | - | `call.type` - `'default'`, `'audio_room'`, `'livestream'` etc. |
-| `--accept` | - | `call.join()` | Transitions to call layout |
-| `--reject` | - | `call.leave({ reject: true })` | Dismisses the ring |
-| Ring event | `useCalls()` from the SDK - filter by `call.state.callingState === CallingState.RINGING` | - | The React hook for ringing calls; fetch the Ringing cookbook page ([`DOCS.md`](DOCS.md)) before building |
-| Auto-dismiss | Client-side timeout | - | Dismiss after ~30s if no action |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Ringing | Call type supports ringing | Available on `'default'` call type |
-| Ring initiation | Caller uses `call.getOrCreate({ ring: true, data: { members: [...] } })` for initial ring, or `call.ring({ members_ids: [...] })` to ring specific members | - |
-| Push notifications | Mobile SDKs + push provider configured | Optional - for ringing when app is backgrounded |
-
----
-
-## Participant List
-
-Side panel showing all participants in the current call with their status.
-
-### Blueprint
-
-```html
-<div class="participant-list">
-
-  <header class="participant-list__header">
-    <h3 class="participant-list__title">Participants</h3>
-    <span class="participant-list__count"></span>
-    <button class="participant-list__close" aria-label="Close"></button>
-  </header>
-
-  <!-- OPTIONAL: invite more participants -->
-  <div class="participant-list__invite">
-    <input class="participant-list__invite-input" placeholder="Invite people" />
-  </div>
-
-  <div class="participant-list__items">
-    <div class="participant-list__item">
-      <!-- Modifiers: --speaking | --muted | --video-off | --host -->
-      <img class="participant-list__item-avatar" src="" alt="" />
-      <!-- CONDITIONAL: online presence dot -->
-      <div class="participant-list__item-info">
-        <span class="participant-list__item-name"></span>
-        <!-- CONDITIONAL: user is host -->
-        <span class="participant-list__item-role">Host</span>
-      </div>
-      <div class="participant-list__item-status">
-        <!-- Mic status icon -->
-        <span class="participant-list__item-mic"></span>
-        <!-- Camera status icon -->
-        <span class="participant-list__item-camera"></span>
-      </div>
-      <!-- CONDITIONAL: current user is host/admin -->
-      <div class="participant-list__item-actions">
-        <button class="participant-list__item-mute" aria-label="Mute"></button>
-        <button class="participant-list__item-remove" aria-label="Remove"></button>
-      </div>
-    </div>
-  </div>
-
-</div>
-```
-
-### Wiring
-
-| Element | Read | Write | Property Path |
-|---|---|---|---|
-| `participant-list__items` | `call.state.participants` | - | Array of participants |
-| `participant-list__count` | `call.state.participants` | - | `.length` |
-| `participant-list__item-avatar` | Participant data | - | `participant.image` |
-| `participant-list__item-name` | Participant data | - | `participant.name` |
-| `participant-list__item-role` | Participant data | - | `participant.roles` - check for `'host'`, `'admin'` |
-| Mic status | Participant state | - | `hasAudio(participant)` (import from `@stream-io/video-client`) |
-| Camera status | Participant state | - | `hasVideo(participant)` (import from `@stream-io/video-client`) |
-| Mute participant | - | `call.muteUser(userId, 'audio')` | Host/admin only |
-| Remove participant | - | `call.kickUser({ user_id: userId })` | Host/admin only. Removes from the call; add `block: true` to also ban from rejoining. `call.blockUser(userId)` *bans* without removing - not the same as "remove" |
-| Invite | - | `call.updateCallMembers({ update_members: [{ user_id: id }] })` then ring or notify | The key is `update_members` (not `members`); `remove_members: [userId]` removes |
-
-### Requirements
-
-| Feature | Requirement | Default |
-|---|---|---|
-| Participant list | `call.join()` completed | Available |
-| Host controls | User has host/admin role on call type | Depends on call type config |
-| Invite | - | Available - add members to call |
+For fully hand-built, bespoke UI on the low-level client - when the prebuilt layouts/controls can't be customized into the target - see [`custom-ui.md`](custom-ui.md): the prebuilt-vs-bespoke decision, the headless `useCallStateHooks()` map, and per-region routing to the live docs. Keep `ParticipantView` for track binding even in a bespoke layout; default to the prebuilt path above.
diff --git a/skills/stream-react/references/VIDEO.md b/skills/stream-react/references/VIDEO.md
index 6c17d8a..51535d9 100644
--- a/skills/stream-react/references/VIDEO.md
+++ b/skills/stream-react/references/VIDEO.md
@@ -1,21 +1,20 @@
 # Video - Setup & Integration
 
-Stream Video provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For full component structure and wiring, see [VIDEO-blueprints.md](VIDEO-blueprints.md).
+Stream Video provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + layouts/controls), see [VIDEO-blueprints.md](VIDEO-blueprints.md); for fully bespoke UI on the low-level client, see [custom-ui.md](custom-ui.md).
 
 Rules: [../RULES.md](../RULES.md) (login screen first, strict mode protection, reference authority) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
-- **Blueprint** - HTML with BEM classes defining structure and conditional rendering
-- **Wiring** - API calls to read/write each element, exact property paths
-- **Requirements** - Dashboard settings, API params, and prerequisites
+- **Prebuilt path** ([VIDEO-blueprints.md](VIDEO-blueprints.md)) - the canonical provider tree, prebuilt layouts/controls, and the `useCallStateHooks()` customization surface. The common path for calls and livestreams.
+- **Bespoke path** ([custom-ui.md](custom-ui.md)) - custom layouts/controls on the low-level client; keep `ParticipantView` for track binding.
+- **Live docs** ([docs-map.md](docs-map.md)) - fetch the matching component / cookbook / advanced page before building any customization.
 
 ## Quick ref
 
 - **Packages:** `@stream-io/video-react-sdk`; import SDK CSS from package `dist/css/styles.css`.
 - **First:** **App Integration** -> **Setup** for call types / credentials.
-- **Per feature:** Lobby, Call Layout, Controls, ... - one section at a time.
-- **Below the next rule:** full blueprints - **do not load past it** until you implement that component.
+- **Per feature:** fetch the matching live page from [docs-map.md](docs-map.md) before implementing that screen; for fully hand-built UI on the low-level client, see [custom-ui.md](custom-ui.md).
 
-Full component blueprints: [VIDEO-blueprints.md](VIDEO-blueprints.md) - load only the section you are implementing.
+Prebuilt component path: [VIDEO-blueprints.md](VIDEO-blueprints.md) - the canonical provider tree + layouts/controls. Bespoke UI on the low-level client: [custom-ui.md](custom-ui.md).
 
 ---
 
diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
new file mode 100644
index 0000000..1f6c0e5
--- /dev/null
+++ b/skills/stream-react/references/custom-ui.md
@@ -0,0 +1,158 @@
+# Stream React (web) - custom / bespoke UI on the low-level client
+
+Read this **only** when the user explicitly wants fully hand-built UI - a bespoke surface that the
+prebuilt components can't be customized into. The default is the opposite: **prebuilt-component-first**
+([`../RULES.md`](../RULES.md) > Reference authority). This file is the *decision* (prebuilt vs bespoke)
+plus the *headless path* (how to build on the low-level client + the SDK's context hooks). It does
+**not** mirror element markup - for every region you build, fetch the matching live page from
+[`docs-map.md`](docs-map.md) first.
+
+---
+
+## Step 0: prebuilt vs bespoke - lean hard toward prebuilt
+
+Stream's React SDKs ship rich prebuilt components built to be *customized*. Choosing to hand-build
+instead is an architecture decision that usually costs a day and throws away typing indicators, read
+receipts, reactions, threads, attachments, uploads, presence, optimistic send, and i18n - all of
+which the prebuilt path gives you for free. So decide deliberately, and **default to prebuilt.**
+
+There are **three levels of customization** - exhaust the cheaper ones before going bespoke:
+
+| Level | Mechanism | Changes |
+|---|---|---|
+| **Theming** | CSS variables + the theme class (`str-chat__theme-light/dark`), `<Channel>` theming, Tailwind around the components | Colors, fonts, spacing, radius - *within the existing layout* |
+| **Component injection** | `<WithComponents overrides={{ MessageUI, MessageComposerUI, Avatar, ... }}>` (writes `ComponentContext`), or a per-list `<MessageList Message={Custom} />` | Swap *one* region's UI while the SDK still drives data, events, and the rest of the tree |
+| **Bespoke (this file)** | Your own React tree consuming the SDK's context hooks (or the raw `stream-chat` client) | Everything - but you own every dropped sub-feature |
+
+**Litmus test:** if theming + a few `WithComponents` overrides + hooks could reach the design, it's a
+**prebuilt** job - even a strong reskin (WhatsApp/Slack/Linear). Pick **bespoke only** when you'd be
+replacing the message row, composer, channel list, **and** header all at once - i.e. using the SDK
+purely as a data source for a non-messenger surface (a flat ticker, an overlay, a livestream chat
+rail). Over-choosing bespoke is the common, expensive mistake. **When unsure, build the prebuilt
+version first** - it's faster to confirm-or-reject than to rebuild a worse messenger by hand.
+
+If it's genuinely unclear, ask one question:
+
+> Is this a standard messenger (channel list + message list + composer) we can customize, or a
+> bespoke surface where you want fully hand-built UI on the Stream client?
+
+---
+
+## The headless path - Chat
+
+**Stay inside the providers.** The cheap, correct way to go bespoke is to keep `<Chat>` / `<Channel>`
+mounted (so client lifecycle, the WebSocket, pagination, read state, and optimistic updates keep
+working) and render **your own children that consume the SDK's context hooks**. Only drive the raw
+`stream-chat` client directly (no providers) for a surface that isn't a channel view at all.
+
+Entry-point hooks (confirm the current surface on the page before using - the API evolves):
+
+| Hook | Gives you |
+|---|---|
+| `useChatContext()` | `client`, active `channel`, `setActiveChannel` |
+| `useChannelStateContext()` | `messages`, `members`, `read`, `watcher_count`, `loadingMore`, `hasMore`, `thread` |
+| `useChannelActionContext()` | `sendMessage`, `editMessage`, `removeMessage`, `loadMore`, `openThread`, `jumpToMessage` |
+| `useMessageContext()` | `message`, `isMyMessage()`, `handleReaction`, `handleDelete`, `handleOpenThread`, ... |
+| `useComponentContext()`, `useTypingContext()` | injected components; who is typing |
+
+Provider-less fallback (non-channel surfaces only): drive the client directly - `client.queryChannels(filter, sort, { watch: true, state: true })`, `channel.watch()`, `channel.on(event => ...)` (keep the returned `unsubscribe` for cleanup), `channel.sendMessage(...)`, `channel.countUnread()` / `channel.markRead()`. Read the **low-level client / API reference** index in [`docs-map.md`](docs-map.md) for the current surface.
+
+**Strict mode:** still create the client with `useCreateChatClient()` ([`../RULES.md`](../RULES.md) >
+Strict mode protection) - never `getInstance()` on the client. Any `channel.on(...)` subscription in
+an effect must be torn down in cleanup.
+
+## The headless path - Video
+
+Build custom layouts from `useCallStateHooks()` (`useParticipants`, `useCameraState`,
+`useMicrophoneState`, `useCallCallingState`, `useParticipantViewContext`, ... - confirm on the page).
+**Keep `ParticipantView` even in a bespoke layout** - it binds the media track for you; only hand-bind
+`participant.videoStream` / `audioStream` when you must. Keep `<StreamVideo>` / `<StreamCall>` mounted.
+
+---
+
+## Route each region to its live page (do not mirror)
+
+For every region you hand-build, **fetch the matching page from [`docs-map.md`](docs-map.md) first** -
+it carries the current props, hook names, and the canonical customization pattern. The bespoke build
+is then "consume the hook above + render your own markup to match the target."
+
+| Bespoke region | Fetch first (row in `docs-map.md`) |
+|---|---|
+| Custom message row | Chat cookbook -> **Message UI** |
+| Custom composer / input | Chat cookbook -> **Message Composer UI** |
+| Reactions set / selector | Chat cookbook -> **Reactions Customization** |
+| Channel list item / preview | Chat cookbook -> **Channel List UI** |
+| Channel header | Chat cookbook -> **Channel Header** |
+| Message actions / context menu | Chat cookbook -> **Message Actions** |
+| Search | Chat cookbook -> **Search Customization** |
+| Custom call controls | Video cookbook -> **Replacing Call Controls** |
+| Custom call layout | Video index -> `ui-cookbook/<slug>.md` (fetch the index) |
+
+---
+
+## Completion contract - fill before you ship (do NOT skip rows)
+
+Replacing a prebuilt region means you inherit **every** sub-feature it rendered. This is not a
+reminder, it's a checklist: for the region you're building, **every row below is REQUIRED**. For each
+row, do exactly one of:
+
+- **Reproduce it** - reuse the named SDK piece; don't hand-roll.
+- **`N/A - <why the design genuinely doesn't need it>`** - a real *design* reason (e.g. read receipts
+  in anonymous livestream chat, threads in a flat ticker). **"Deferred", "later", "moving fast", and
+  "out of scope for now" are NOT design reasons and are NOT valid `N/A`.**
+- **`GAP - not implemented`** - if you are skipping a genuinely-needed capability for time, label it in
+  exactly those words so it stays visible. Never relabel a time-skip as `N/A`.
+
+A blank row - or an `N/A` whose real reason is "deferred" - = incomplete. Confirm the exact current
+component/prop names on the live page first ([`docs-map.md`](docs-map.md)) - the *capability list* here
+is the durable part, the *names* come from the fetch.
+
+**Custom message row (`MessageUI`):**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Text: markdown, links, mentions, emoji | `<MessageText/>` - never raw `{message.text}` | [ ] |
+| Attachments: image / file / video / voice / giphy | `<Attachment attachments={message.attachments}/>` | [ ] |
+| Reactions: display + add | `<MessageReactions/>` + `handleReaction` | [ ] |
+| Quoted / replied-to parent | render `message.quoted_message` preview | [ ] |
+| Thread reply indicator | `<MessageRepliesCountButton/>` + `handleOpenThread` | [ ] |
+| Read / delivery receipts (own messages) | `<MessageStatus/>` | [ ] |
+| Edited / deleted state | `message.message_text_updated_at` / `message.deleted_at` | [ ] |
+| Actions menu: reply / edit / delete / pin / flag | `<MessageActions/>` - not a dead `...` button | [ ] |
+| Same-author grouping | `firstOfGroup` / `groupedByUser` from `useMessageContext()` | [ ] |
+| Error / optimistic-send state | `message.status` / `message.error` | [ ] |
+
+**Custom composer:** text input; attachments + upload (and removal); mentions / slash-commands
+autocomplete; send (+ enter-to-send); voice recording (if enabled); edit-message mode.
+
+**Custom call layout / controls:** each participant via `<ParticipantView/>` (don't hand-bind tracks);
+screenshare track; dominant-speaker / active state; camera + mic toggle (`useCameraState` /
+`useMicrophoneState`); join / leave; device selectors (if shown).
+
+Then **verify on seeded data** that triggers every ticked row (see Verify below) - a near-empty channel
+hides every gap. Baseline testing showed that without this contract, agents drop attachments, quoted
+replies, threads, and receipts almost every time, and each run drops a *different* set - so fill the
+rows; don't trust recall.
+
+---
+
+## Implementation discipline (the curated gotchas)
+
+- **Any BEM/class names in a docs example are a structural spec, not shippable CSS.** They tell you
+  the elements + conditional states (`--active`, `--unread`, online presence, sent/delivered/read).
+  Implement them with **Shadcn components + Tailwind utilities**; do not ship the BEM classes or
+  hand-written CSS.
+- **Reuse SDK pieces inside bespoke UI** (`Attachment`, `Avatar`, `ParticipantView`) instead of
+  rebuilding them.
+- **Keep the providers** (`<Chat>`/`<Channel>`, `<StreamVideo>`/`<StreamCall>`) unless the surface is
+  genuinely not a channel/call view - that's what keeps the WebSocket, pagination, read state, and
+  client lifecycle working.
+- **Still docs-first, still no guessing.** Fetch the page this turn; never wire a hook/prop from
+  memory ([`docs-map.md`](docs-map.md) > URL grounding).
+
+## Verify
+
+A bespoke surface isn't done until you run it and check it against the target. Seed data that triggers
+**every** region (incoming + outgoing, a run of same-author messages so grouping shows, an attachment,
+a reaction, a reply/thread, long text, a typing event), open the real screen on its actual navigation
+path, compare region-by-region, and iterate. Match the target, don't approximate it.
diff --git a/skills/stream-react/references/DOCS.md b/skills/stream-react/references/docs-map.md
similarity index 81%
rename from skills/stream-react/references/DOCS.md
rename to skills/stream-react/references/docs-map.md
index 68152cf..c2f1c6e 100644
--- a/skills/stream-react/references/DOCS.md
+++ b/skills/stream-react/references/docs-map.md
@@ -1,27 +1,45 @@
-# Stream React (web) - docs-first manifest
+# Stream React (web) - docs routing map
 
-**Best practices live in the live docs, not in training data.** Before implementing any feature that matches a trigger row below, **fetch the matching docs page first**, read its current guidance, then build to match. Stream's React SDKs evolve quickly; the component reference, cookbook, and advanced-guide pages are the authority for the current API and the recommended pattern.
+Map a request to the exact React docs page, then fetch its `.md`. **Best practices live in the live docs, not in training data** - Stream's React SDKs evolve quickly, so the component-reference, cookbook, and advanced-guide pages are the authority for the current API and recommended pattern. The trigger tables below are the curated 80% (the high-frequency intents); **for anything not listed, fetch the live index and pick from it - never guess a path.**
 
-This skill is **prebuilt-component-first** ([`../RULES.md`](../RULES.md) > Reference authority): build the common path with the SDK's prebuilt components and customize via the documented hooks/props on the pages below.
+This skill is **prebuilt-component-first** ([`../RULES.md`](../RULES.md) > Reference authority): build the common path with the SDK's prebuilt components and customize via the documented hooks/props on the pages below. For fully bespoke UI on the low-level client, see [`custom-ui.md`](custom-ui.md).
+
+---
+
+## The docs convention (the core mechanism)
+
+Every Stream docs page has a Markdown twin a coding agent can read directly: **take the page URL, drop the trailing `/`, add `.md`.**
+
+```
+https://getstream.io/chat/docs/sdk/react/components/core-components/channel/   ->   https://getstream.io/chat/docs/sdk/react/components/core-components/channel.md
+```
+
+Always fetch the `.md` variant - it is clean Markdown with verbatim code, no page chrome.
+
+Each product has a **live index** that lists every page with its `.md` URL. Fetch the index to discover or confirm a page whenever a request does not match a trigger row below:
+
+| Product | Live index (always current) | Page URL shape |
+|---|---|---|
+| Chat React (SDK: UI components + hooks) | `https://getstream.io/cli/docs/chat-sdk-react.md` | `https://getstream.io/chat/docs/sdk/react/...md` |
+| Chat React (low-level client / API reference) | `https://getstream.io/cli/docs/chat-react.md` | `https://getstream.io/chat/docs/react/...md` |
+| Video React | `https://getstream.io/cli/docs/video-react.md` | `https://getstream.io/video/docs/react/...md` |
+| Feeds React | `https://getstream.io/cli/docs/activity-feeds-react.md` | `https://getstream.io/activity-feeds/docs/react/...md` |
+
+(The same manifests are also published as `llms.txt` in list form: Chat SDK `.../chat/docs/sdk/react/llms.txt`, Chat API `.../chat/docs/react/llms.txt`, Video `.../video/docs/react/llms.txt`, Feeds `.../activity-feeds/docs/react/llms.txt`.)
+
+**URL grounding (non-negotiable).** Only fetch a page URL you got from a trigger row below or from a live index fetch *in this conversation*. **Do not construct a doc path from memory or from a pattern** - many look guessable but are wrong (e.g. the Feeds React quick start is `https://getstream.io/activity-feeds/docs/react.md`, **not** `.../docs/react/quick-start.md`, which 404s). If a page is not in a table below, fetch the product index and pick the real URL from it; on fetch failure, escalate to the `stream-docs` skill, then stop and ask - never build from memory.
+
+**Version note.** The Chat React index is versioned (v14 latest, then v13, ...). When a project pins a specific major (check `package.json`), route to that version's pages - this matters most for Track M migrations ([`../migrate.md`](../migrate.md)).
 
 ## Docs-first protocol
 
 1. **Match** the user's request against a trigger row below (Chat / Video / Feeds; component, cookbook, or advanced guide), or against the relevant index when it does not match a row.
 2. **Fetch before coding** - `WebFetch` the page's `.md` URL (every row links the raw markdown). Read it this turn.
-3. **Implement to match** the fetched guidance - do not write the feature from memory or from the bundled blueprints alone. The blueprints in `*-blueprints.md` cover the common path; these pages cover the customization/advanced path and override memory.
+3. **Implement to match** the fetched guidance - do not write the feature from memory or from the bundled blueprints alone. The blueprints in `*-blueprints.md` cover the prebuilt common path; these pages cover the customization/advanced path and override memory.
 4. **On fetch failure** - hand the lookup to the `stream-docs` skill (live docs with citations) before coding. If neither the page nor `stream-docs` resolves it, **stop and ask the user** - do not implement from memory. Never guess the API.
 
 This protocol is a non-negotiable rule - see [`../RULES.md`](../RULES.md) > Docs-first for cookbook / advanced features. It also governs **migration** (Track M) - fetch the release/upgrade guide before applying an upgrade ([`../migrate.md`](../migrate.md)).
 
-## Source indexes (llms.txt)
-
-The full per-product page list lives in these manifests. Fetch the index when a request does not match a row below, or to discover newer pages:
-
-- **Chat React (SDK):** https://getstream.io/chat/docs/sdk/react/llms.txt
-- **Chat React (API):** https://getstream.io/chat/docs/react/llms.txt
-- **Video React:** https://getstream.io/video/docs/react/llms.txt
-- **Feeds React:** https://getstream.io/activity-feeds/docs/react/llms.txt
-
 ---
 
 ## Chat React - prebuilt components (build the common path with these)
@@ -55,6 +73,8 @@ First-class prebuilt features the common-path blueprints don't cover. Most need
 
 ## Chat React - UI Cookbook (customization + theming recipes)
 
+> **Writing your OWN component for one of these regions** (custom message row, composer, channel preview/header) instead of passing props/theme? **Load [`custom-ui.md`](custom-ui.md) first** - its completion contract lists every sub-feature you must reproduce or mark `N/A` (attachments, reactions, quoted replies, receipts, threads, edited/deleted, grouping) - **then** fetch the page below for the current API. Just passing props/theme to the prebuilt component? Fetch the page and skip the contract.
+
 | Trigger keywords (in the user's request) | Topic | Fetch first |
 |---|---|---|
 | typing indicator, "user is typing", typing dots | Typing Indicator | https://getstream.io/chat/docs/sdk/react/guides/customization/typing-indicator.md |
@@ -120,6 +140,8 @@ First-class prebuilt features the common-path blueprints don't cover. Most need
 
 ## Video React - UI Cookbook (customization recipes)
 
+> **Writing your OWN call layout/controls component** instead of passing props? **Load [`custom-ui.md`](custom-ui.md) first** (completion contract: each participant via `ParticipantView`, screenshare, dominant-speaker, join/leave, device state), **then** fetch the page below. Passing props to a prebuilt component? Fetch the page.
+
 | Trigger keywords (in the user's request) | Topic | Fetch first |
 |---|---|---|
 | replace call controls, custom control bar, custom buttons | Replacing Call Controls | https://getstream.io/video/docs/react/ui-cookbook/replacing-call-controls.md |
@@ -149,7 +171,7 @@ Feeds has **no prebuilt UI components** - always build from its hooks (`useFeedA
 
 | Trigger keywords (in the user's request) | Topic | Fetch first |
 |---|---|---|
-| feeds setup, install, client, useCreateFeedsClient, quick start | Quick Start | https://getstream.io/activity-feeds/docs/react/react.md |
+| feeds setup, install, client, useCreateFeedsClient, quick start | Quick Start | https://getstream.io/activity-feeds/docs/react.md |
 | installation, packages | Installation | https://getstream.io/activity-feeds/docs/react/installation.md |
 | post, activity, addActivity, create post | Activities | https://getstream.io/activity-feeds/docs/react/activities.md |
 | read a feed, timeline, useFeedActivities, getOrCreate, pagination | Feeds | https://getstream.io/activity-feeds/docs/react/feeds.md |

From 82e74d211fdfd9788e31cf8dc231cc77f997eec4 Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Mon, 6 Jul 2026 10:49:26 +0200
Subject: [PATCH 2/7] fix(stream-react): close custom-ui contract escape + add
 version-pinning gate

Address xhigh code-review findings on the live-docs migration.

- custom-ui.md: the entry gate contradicted the router - it opened "read this
  only when the user wants fully hand-built UI" and Step 0 scoped bespoke to
  "replace message row + composer + list + header at once", so an agent routed
  in for a single WithComponents/Message= override could read the opening and
  bail past the completion contract. Rewrite the opening + Step 0 so the gate is
  "are you writing your own component for a region? yes -> contract applies";
  fully-headless vs injection is now framed as an architecture choice, not a
  contract escape. (GREEN: 3/3 subagents apply the contract, none bail.)
- enhance.md / SKILL.md: add a version-detect step - read the installed Stream
  major before applying blueprint API names (blueprints assume Chat React v14:
  MessageComposer, css/index.css), so a v13 project routes to its own docs
  instead of shipping v14-only imports.
- Collapse the "custom component for a region" predicate to one wording across
  RULES.md (canonical), SKILL.md, enhance.md, CHAT.md, VIDEO.md, builder-ui.md
  (they had drifted; enhance + product files still said "fully bespoke UI").
---
 skills/stream-react/SKILL.md                |  6 +-
 skills/stream-react/builder-ui.md           |  2 +-
 skills/stream-react/enhance.md              |  4 +-
 skills/stream-react/references/CHAT.md      |  2 +-
 skills/stream-react/references/VIDEO.md     |  2 +-
 skills/stream-react/references/custom-ui.md | 69 ++++++++++++---------
 6 files changed, 48 insertions(+), 37 deletions(-)

diff --git a/skills/stream-react/SKILL.md b/skills/stream-react/SKILL.md
index 60fd5c1..9398580 100644
--- a/skills/stream-react/SKILL.md
+++ b/skills/stream-react/SKILL.md
@@ -185,7 +185,9 @@ getstream env
 npm install <packages> --legacy-peer-deps
 ```
 
-After installing SDKs, verify an icon package is available. Some Shadcn presets bundle one, others don't:
+After installing SDKs, note the resolved **Stream Chat React major**: the bundled blueprints assume **v14** (`MessageComposer`, `stream-chat-react/css/index.css`). `@latest` is v14 today; if a future install resolves a **newer major**, fetch that major's component reference from [`references/docs-map.md`](references/docs-map.md) (Version note) before writing the provider tree - don't apply v14 names from memory.
+
+Also verify an icon package is available. Some Shadcn presets bundle one, others don't:
 
 ```bash
 node -e "const p=['lucide-react','@phosphor-icons/react','@hugeicons/react'];console.log(p.some(m=>{try{require.resolve(m);return true}catch{return false}})?'ICONS_OK':'NO_ICONS')"
@@ -201,7 +203,7 @@ If `NO_ICONS`, install `lucide-react`: `npm install lucide-react --legacy-peer-d
 
 **Docs-first:** before implementing any component, cookbook, or advanced feature (typing indicator, custom message UI, reactions, AI integrations, read state, notifications, call layouts, ...), follow the **Docs-first triggers** section above - `WebFetch` the matching [`references/docs-map.md`](references/docs-map.md) page first, then build to match.
 
-**Load [`builder-ui.md`](builder-ui.md) and [`sdk.md`](sdk.md)** (cross-cutting SDK wiring: token route, instantiation, CSS imports), plus **only** the relevant [`references/<Product>.md`](references/) header + `references/<Product>-blueprints.md` (the prebuilt provider tree + props) for the product(s) you are implementing - not every reference file. For any customization, fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) first; **writing your own component for a region (custom message row/composer/preview/header/call layout) -> load [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) before building**, then fetch the page. Pull **Use Case Matching** and **Page Flow** from [`builder.md`](builder.md) to choose products and navigation structure. **For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) before writing AppShell** - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table.
+**Load [`builder-ui.md`](builder-ui.md) and [`sdk.md`](sdk.md)** (cross-cutting SDK wiring: token route, instantiation, CSS imports), plus **only** the relevant [`references/<Product>.md`](references/) header + `references/<Product>-blueprints.md` (the prebuilt provider tree + props) for the product(s) you are implementing - not every reference file. For any customization, fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) first (and if you are writing your own component for a region, load [`references/custom-ui.md`](references/custom-ui.md) first per Step 4's rule above / [`RULES.md`](RULES.md) > Reference authority). Pull **Use Case Matching** and **Page Flow** from [`builder.md`](builder.md) to choose products and navigation structure. **For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) before writing AppShell** - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table.
 
 ### Step 5: Verify
 
diff --git a/skills/stream-react/builder-ui.md b/skills/stream-react/builder-ui.md
index 010bdd7..2f6d4e6 100644
--- a/skills/stream-react/builder-ui.md
+++ b/skills/stream-react/builder-ui.md
@@ -3,7 +3,7 @@
 Load when executing **Step 4** (after scaffold). Rules: [`RULES.md`](RULES.md) (login screen first, theme, reference authority).
 
 ### Step 4: Generate ALL code files
-Write every file sequentially. Follow the UI Guidelines below for all visual styling. See **RULES.md > Reference authority** - reference files are the only source of truth for SDK wiring. Before writing each component, load the prebuilt path in the relevant `references/<Product>-blueprints.md`; fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and see [`references/custom-ui.md`](references/custom-ui.md) for fully bespoke UI.
+Write every file sequentially. Follow the UI Guidelines below for all visual styling. See **RULES.md > Reference authority** - reference files are the only source of truth for SDK wiring. Before writing each component, load the prebuilt path in the relevant `references/<Product>-blueprints.md`; fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and load [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) first when you write your own component for a region - even one, even via `Message=` / `WithComponents`.
 
 #### Login Screen (required for every app - RULES.md > Login Screen first)
 
diff --git a/skills/stream-react/enhance.md b/skills/stream-react/enhance.md
index a321065..4b03625 100644
--- a/skills/stream-react/enhance.md
+++ b/skills/stream-react/enhance.md
@@ -14,7 +14,7 @@ For adding Stream products to an **existing React project** - Next.js or any oth
 
 Before writing any code, understand what's already in place:
 
-1. **Packages:** check `package.json` for `stream-chat`, `stream-chat-react`, `@stream-io/video-react-sdk`, `@stream-io/node-sdk`.
+1. **Packages + installed version:** check `package.json` for `stream-chat`, `stream-chat-react`, `@stream-io/video-react-sdk`, `@stream-io/node-sdk` - and read the **installed major** of each (from the `package.json` range and the lockfile). The bundled blueprints assume **Chat React v14** (`MessageComposer`, `stream-chat-react/css/index.css`); if the project pins an **older major** (v13: `MessageInput`, `dist/css/v2/index.css`), do **not** apply v14 blueprint names from memory - fetch that major's docs index from [`references/docs-map.md`](references/docs-map.md) (Version note) and match the installed version. Never bump the SDK as a side effect of adding a feature.
 2. **Framework:** detect from `package.json` - **Next.js** (has `next`; route handlers under `app/` or `pages/api`; build = `next build`) vs **another React stack** (Vite/CRA/Remix/etc.; no Next.js `/api` routes; build = the project's own `build` script). This drives where the token endpoint lives (E3) and the verify command (E4).
 3. **Auth:** does the app already have a server token endpoint (Next.js `/api/token` route, or an equivalent endpoint in the app's own backend)? If so, **extend** it with the new product's token - don't create a second token endpoint.
 4. **Credentials:** check for `.env` with `STREAM_API_KEY` / `STREAM_API_SECRET`. If missing, run `getstream init` (if the dir isn't a Stream project yet) then `getstream env` to write them - never read or print the secret.
@@ -31,7 +31,7 @@ Before writing any code, understand what's already in place:
 
 1. **Token endpoint:** extend the existing token endpoint to return the new product's token alongside existing ones. On **Next.js** this is the `/api/token` route handler; on **other React stacks** it is the project's own server endpoint (Express/Fastify route, Remix loader/action, Vite server fn, etc.) - the server-side instantiation in [`sdk.md`](sdk.md) is identical, only the host differs. Tokens are always minted server-side ([`RULES.md`](RULES.md) > Env vars are server-side only).
 2. **API routes:** add the product-specific server routes from `references/<Product>.md` (App Integration -> API Routes) - as Next.js route handlers on Next.js, or equivalent endpoints in the app's backend otherwise. Feeds needs several (`/api/feed/get`, `/api/feed/post`, etc.); Chat and Video typically only need the token endpoint.
-3. **Components:** load the prebuilt path in `references/<Product>-blueprints.md` (and [`references/custom-ui.md`](references/custom-ui.md) for fully bespoke UI), fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and build using the existing project's patterns and styling conventions - not the [`builder-ui.md`](builder-ui.md) defaults.
+3. **Components:** load the prebuilt path in `references/<Product>-blueprints.md`; fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization. **Writing your own component for a region - even one, even via `Message=` / `WithComponents` - loads [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) first** ([`RULES.md`](RULES.md) > Reference authority). Build using the existing project's patterns and styling conventions - not the [`builder-ui.md`](builder-ui.md) defaults.
 4. **State:** if the app already manages user state (auth context, session), wire Stream tokens into that - don't add a separate Login Screen unless the app has no auth.
 
 ## E4: Verify
diff --git a/skills/stream-react/references/CHAT.md b/skills/stream-react/references/CHAT.md
index 0679bbb..5acab6e 100644
--- a/skills/stream-react/references/CHAT.md
+++ b/skills/stream-react/references/CHAT.md
@@ -1,6 +1,6 @@
 # Chat - Setup & Integration
 
-Stream Chat provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + props), see [CHAT-blueprints.md](CHAT-blueprints.md); for fully bespoke UI on the low-level client, see [custom-ui.md](custom-ui.md).
+Stream Chat provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + props), see [CHAT-blueprints.md](CHAT-blueprints.md); when you write your own component for a region (even one, even via `Message=` / `WithComponents`) or go fully hand-built, see [custom-ui.md](custom-ui.md) (the completion contract).
 
 Rules: [../RULES.md](../RULES.md) (login screen first, strict mode protection, reference authority) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
diff --git a/skills/stream-react/references/VIDEO.md b/skills/stream-react/references/VIDEO.md
index 51535d9..e475b8d 100644
--- a/skills/stream-react/references/VIDEO.md
+++ b/skills/stream-react/references/VIDEO.md
@@ -1,6 +1,6 @@
 # Video - Setup & Integration
 
-Stream Video provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + layouts/controls), see [VIDEO-blueprints.md](VIDEO-blueprints.md); for fully bespoke UI on the low-level client, see [custom-ui.md](custom-ui.md).
+Stream Video provides pre-built UI components via React, React Native, Flutter, Swift, and Kotlin SDKs. This file covers setup, server routes, client patterns, and gotchas. For the prebuilt component path (provider tree + layouts/controls), see [VIDEO-blueprints.md](VIDEO-blueprints.md); when you write your own component for a region (custom call layout, participant tile, controls, lobby) or go fully hand-built, see [custom-ui.md](custom-ui.md) (the completion contract).
 
 Rules: [../RULES.md](../RULES.md) (login screen first, strict mode protection, reference authority) and the cross-cutting [../../stream/RULES.md](../../stream/RULES.md) (secrets, no auto-seeding).
 
diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
index 1f6c0e5..4b9e4c8 100644
--- a/skills/stream-react/references/custom-ui.md
+++ b/skills/stream-react/references/custom-ui.md
@@ -1,40 +1,49 @@
-# Stream React (web) - custom / bespoke UI on the low-level client
+# Stream React (web) - custom components + bespoke UI on the Stream client
 
-Read this **only** when the user explicitly wants fully hand-built UI - a bespoke surface that the
-prebuilt components can't be customized into. The default is the opposite: **prebuilt-component-first**
-([`../RULES.md`](../RULES.md) > Reference authority). This file is the *decision* (prebuilt vs bespoke)
-plus the *headless path* (how to build on the low-level client + the SDK's context hooks). It does
-**not** mirror element markup - for every region you build, fetch the matching live page from
-[`docs-map.md`](docs-map.md) first.
+**Read this whenever you write your OWN component or markup for a region a prebuilt component
+normally renders - even a single region, and even when you wire it via the documented `Message=` /
+`<WithComponents overrides={...}>` prop - OR when you go fully hand-built (the low-level client for a
+non-messenger surface).** Passing props or theme tokens to a prebuilt component is NOT this file; just
+fetch the page. (Exact predicate: [`../RULES.md`](../RULES.md) > Reference authority.)
 
----
+The default is still **prebuilt-component-first**. This file carries two things: the *decision* (is
+going custom even warranted? - Step 0) and, once you are writing a custom component, the **completion
+contract** below (the sub-features you must reproduce so a custom region doesn't silently drop
+attachments, reactions, receipts, threads). It does **not** mirror element markup - for every region
+you build, fetch the matching live page from [`docs-map.md`](docs-map.md) first.
 
-## Step 0: prebuilt vs bespoke - lean hard toward prebuilt
+---
 
-Stream's React SDKs ship rich prebuilt components built to be *customized*. Choosing to hand-build
-instead is an architecture decision that usually costs a day and throws away typing indicators, read
-receipts, reactions, threads, attachments, uploads, presence, optimistic send, and i18n - all of
-which the prebuilt path gives you for free. So decide deliberately, and **default to prebuilt.**
+## Step 0: which level - and does the completion contract apply?
 
-There are **three levels of customization** - exhaust the cheaper ones before going bespoke:
+Stream's React SDKs ship rich prebuilt components built to be *customized*. There are **three
+levels** - use the cheapest that reaches the design:
 
-| Level | Mechanism | Changes |
+| Level | Mechanism | Completion contract? |
 |---|---|---|
-| **Theming** | CSS variables + the theme class (`str-chat__theme-light/dark`), `<Channel>` theming, Tailwind around the components | Colors, fonts, spacing, radius - *within the existing layout* |
-| **Component injection** | `<WithComponents overrides={{ MessageUI, MessageComposerUI, Avatar, ... }}>` (writes `ComponentContext`), or a per-list `<MessageList Message={Custom} />` | Swap *one* region's UI while the SDK still drives data, events, and the rest of the tree |
-| **Bespoke (this file)** | Your own React tree consuming the SDK's context hooks (or the raw `stream-chat` client) | Everything - but you own every dropped sub-feature |
-
-**Litmus test:** if theming + a few `WithComponents` overrides + hooks could reach the design, it's a
-**prebuilt** job - even a strong reskin (WhatsApp/Slack/Linear). Pick **bespoke only** when you'd be
-replacing the message row, composer, channel list, **and** header all at once - i.e. using the SDK
-purely as a data source for a non-messenger surface (a flat ticker, an overlay, a livestream chat
-rail). Over-choosing bespoke is the common, expensive mistake. **When unsure, build the prebuilt
-version first** - it's faster to confirm-or-reject than to rebuild a worse messenger by hand.
-
-If it's genuinely unclear, ask one question:
-
-> Is this a standard messenger (channel list + message list + composer) we can customize, or a
-> bespoke surface where you want fully hand-built UI on the Stream client?
+| **Theming** | CSS variables + the theme class (`str-chat__theme-light/dark`), `<Channel>` theming, Tailwind around the components | **No** - you replace no region. Fetch the page, pass props/tokens, done. |
+| **Component injection** | Your OWN component for one region via `<WithComponents overrides={{ MessageUI, MessageComposerUI, Avatar, ... }}>` or `<MessageList Message={Custom} />` | **YES** - you render the region yourself, so you inherit its sub-features. Fill the contract below. |
+| **Bespoke (headless)** | Your own React tree consuming the SDK's context hooks (or the raw `stream-chat` client) | **YES** - you own every region and every dropped sub-feature. |
+
+**The gate is one question: are you writing your own component/markup for a region?** If **no**
+(props + theme only) -> Theming row; you can stop reading here. If **yes** -> the **completion
+contract** applies, whether it is one region via `WithComponents` or a whole bespoke tree. Do **not**
+talk yourself out of it because "it's only one component" or "it's still basically the prebuilt app":
+a single custom `MessageUI` is exactly the case that silently drops attachments / receipts / threads.
+
+**Injection vs. fully-headless is an architecture choice, NOT a contract escape.** Prefer **component
+injection** - keep the prebuilt tree, swap only the regions you must - over a fully-headless rebuild.
+Go **fully headless** only when you'd be replacing the message row, composer, channel list, **and**
+header at once, i.e. using the SDK purely as a data source for a non-messenger surface (a flat
+ticker, an overlay, a livestream chat rail). Over-choosing headless is the common, expensive mistake
+(you throw away typing indicators, receipts, reactions, threads, uploads, presence, optimistic send,
+i18n). **When unsure, injection first** - and the contract still applies.
+
+If it is genuinely unclear whether the user wants a custom component at all (vs. just a restyle), ask
+one question:
+
+> Do you want your own custom component(s) for specific regions, or just to restyle the prebuilt UI
+> (colors / fonts / spacing) via theming?
 
 ---
 

From 9040f1d7c3410edf7b18e77fd6a1b220ac5bb85e Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Mon, 6 Jul 2026 11:00:19 +0200
Subject: [PATCH 3/7] feat(stream-react): add design-matching runbook for
 screenshot one-shot builds

New references/design-matching.md + hooks so a screenshot / Figma / "make it look
like X" request reproduces the design region by region instead of falling through
to a generic scaffold. Ports the stream-swift design-matching pattern to React
(shadcn + str-chat theming + Preview-MCP verify).

- design-matching.md (new): work-in-batches; decompose the image into a written
  region/color/type/dimension spec (measure + sample, don't eyeball); route each
  region to a Stream component + mechanism (theming / WithComponents injection ->
  the custom-ui completion contract / bespoke); match the palette via the shadcn
  preset + str-chat theming (not globals.css); ground names on the live page +
  installed major; build batched; verify with a throwaway seed + render-and-compare
  (Preview MCP), then delete the seed.
- SKILL.md: a styling-depth flag in dispatch routes screenshot/Figma/"look like X"
  requests through design-matching.md before building (Track A + E); Step 1b skips
  the theme question when a reference design already dictates it.
- RULES.md: a design-matching exception to the "don't edit globals.css" rule (match
  via preset + documented str-chat variables).
- custom-ui.md: back-pointer to design-matching.md.

Dry-run GREEN (2/2, Track A + Track E): both route through design-matching, skip the
redundant theme question, decompose a spec, bind custom regions to the completion
contract, and plan the render-and-compare verify loop.
---
 skills/stream-react/RULES.md                  |   2 +
 skills/stream-react/SKILL.md                  |   5 +-
 skills/stream-react/references/custom-ui.md   |   2 +
 .../references/design-matching.md             | 114 ++++++++++++++++++
 4 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100644 skills/stream-react/references/design-matching.md

diff --git a/skills/stream-react/RULES.md b/skills/stream-react/RULES.md
index 634707d..e98239f 100644
--- a/skills/stream-react/RULES.md
+++ b/skills/stream-react/RULES.md
@@ -59,6 +59,8 @@ Shadcn components use `@base-ui/react`, NOT `@radix-ui`. Key differences:
 
 Use whatever theme Shadcn generates. Do not modify `globals.css` after init - no dark mode overrides, no custom variable blocks. The scaffold includes `next-themes` with a `ThemeProvider` (system default, class-based toggle) - use it as-is.
 
+**Design-matching exception:** when a screenshot / Figma dictates the palette, match it through the sanctioned channels - the shadcn `--preset` and Stream's documented `str-chat` theming variables / `<Channel>` theming - not ad-hoc `globals.css` edits. See [`references/design-matching.md`](references/design-matching.md) > Step 3.
+
 ## Reference authority
 
 **Prebuilt-component-first.** Stream's React SDKs ship rich prebuilt components, and the React
diff --git a/skills/stream-react/SKILL.md b/skills/stream-react/SKILL.md
index 9398580..978da22 100644
--- a/skills/stream-react/SKILL.md
+++ b/skills/stream-react/SKILL.md
@@ -41,6 +41,8 @@ This skill builds, enhances, audits, and migrates Stream Chat, Video, and Feeds
 - **Track F:** skip onboarding and go directly to the audit in [`references/VIDEO.md`](references/VIDEO.md). **Do not enter Start or any build step.**
 - **Track M:** skip onboarding and Read [`migrate.md`](migrate.md) first; it fetches the live release guide before any edit. **Do not enter Start or any scaffold task.**
 
+**Styling-depth flag (orthogonal to the track).** If the request carries a **target appearance** - an attached screenshot, a Figma frame, or "make it look like WhatsApp / Slack / <app>" - route through [`references/design-matching.md`](references/design-matching.md): a reference design is a **checklist of regions, not a color tweak**. It decomposes the image into a written spec, routes each region to a component + mechanism (theming / injection -> the [`references/custom-ui.md`](references/custom-ui.md) completion contract / bespoke), and closes with a render-and-compare verify loop. This composes with the track: **Track A** scaffolds first, then matches before Step 4's build; **Track E** matches within E3. Load it **before** writing UI.
+
 ---
 
 ## Docs-first triggers (consult docs before building)
@@ -115,12 +117,13 @@ Run the **Provisioning > Step 1: Auth** flow in [`builder.md`](builder.md) (auth
 Ask both setup questions in **one message** before doing anything else - a single pause, the same "ask exactly once, then act" pattern the other platform packs use for credentials. Build the app options from what is already in context: the configured org/app from `getstream init` and the org list from Step 1's `OrganizationRead` output.
 
 > **Quick setup - two questions:**
-> 1. **Theme:** I can use a random shadcn theme, or you can design your own at [ui.shadcn.com/create](https://ui.shadcn.com/create) and share the `--preset` value (e.g. `--preset b1Gdi7z7r`). Random, or do you have a preset?
+> 1. **Theme:** I can use a random shadcn theme, or you can design your own at [ui.shadcn.com/create](https://ui.shadcn.com/create) and share the `--preset` value (e.g. `--preset b1Gdi7z7r`). Random, or do you have a preset? *(If you already shared a screenshot or Figma, I'll match that instead - skip this.)*
 > 2. **Stream app:** *(an app is configured)* Use the currently configured app **`<name>`** (default), pick another existing org/app, or create a fresh one? / *(no app configured)* You have these orgs: `<list>`. Pick one to use - I'll list its apps - or create a fresh org + app?
 
 **STOP here and wait for the user's answer.** Do not continue with any other step until the user responds. Asking a question and continuing to work in parallel is confusing - the user misses the question as output scrolls past.
 
 - **Theme - preset provided** -> store it for Task A scaffold command. **Random / doesn't care** -> pick a random preset from `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`.
+- **Theme - a reference design (screenshot / Figma) was provided** -> the design dictates the theme: **skip question 1**, pick the shadcn preset closest to the sampled palette, ask only question 2 (the Stream app), and match the design via [`references/design-matching.md`](references/design-matching.md).
 - **App - named choice, "default", or "don't care"** -> Step 2 applies it (the configured app wins whenever one exists). **Create new** -> Step 2 runs the create flow.
 - **Account has no orgs at all** -> drop question 2, announce that a fresh org + app will be created, and ask only the theme.
 
diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
index 4b9e4c8..655d6f4 100644
--- a/skills/stream-react/references/custom-ui.md
+++ b/skills/stream-react/references/custom-ui.md
@@ -12,6 +12,8 @@ contract** below (the sub-features you must reproduce so a custom region doesn't
 attachments, reactions, receipts, threads). It does **not** mirror element markup - for every region
 you build, fetch the matching live page from [`docs-map.md`](docs-map.md) first.
 
+**Matching a reference design (screenshot / Figma)?** Run [`design-matching.md`](design-matching.md) for the region-by-region decompose -> map -> verify procedure; it routes back here for the completion contract on each custom region.
+
 ---
 
 ## Step 0: which level - and does the completion contract apply?
diff --git a/skills/stream-react/references/design-matching.md b/skills/stream-react/references/design-matching.md
new file mode 100644
index 0000000..21ba6c6
--- /dev/null
+++ b/skills/stream-react/references/design-matching.md
@@ -0,0 +1,114 @@
+# Stream React (web) - matching a reference design (screenshot / Figma / "make it look like X")
+
+Run this whenever the request carries a **target appearance** - an attached screenshot, a Figma
+frame, or "make it look like WhatsApp / Slack / Linear / <app>". A reference design is a **checklist
+of regions**, not a color tweak: the rail width, the message-row layout, where the timestamp and
+receipts sit, the composer's button placement, the header - most differ from Stream's defaults
+*structurally*, not just by color. Stopping at "wallpaper + bubble color" is the known failure mode.
+
+This file is the *procedure*. The *decision* (customize prebuilt vs go bespoke) and the per-region
+**completion contract** live in [`custom-ui.md`](custom-ui.md); every region's current props/hooks
+come from the live page in [`docs-map.md`](docs-map.md). Still **prebuilt-component-first** and
+**docs-first** ([`../RULES.md`](../RULES.md) > Reference authority, Docs-first) - matching a design
+never licenses building from memory.
+
+## Work in batches - decompose all, build all, verify once
+
+A full match is many regions; do **not** build-and-screenshot after every tweak. Decompose every
+region into a written spec first, ground the names once, implement all regions in one pass, then run
+the app once and verify region-by-region. Iterate on the whole surface, not one control at a time.
+
+## Step 1: Decompose the reference into a written spec (before any code)
+
+**Read the image.** Then write the spec down - do not hold it in your head, and do not start coding
+from an impression:
+
+- **Regions / layout:** the columns and bars - conversation-list rail (and its width), main message
+  list, composer, header, thread panel, any secondary rail or pinned banner. Name every region you
+  can see; a region you don't name is a region you'll silently drop.
+- **Component inventory:** per region, the sub-elements present - avatar, author, timestamp,
+  reactions, reply/thread summary, receipts, attachment tiles, composer buttons. This inventory is
+  what the completion contract holds you to.
+- **Color - sample, don't guess:** sample the actual hex of each sub-part (app chrome, list
+  background, incoming vs outgoing bubble, text, muted text, accent, unread badge, online dot). A
+  "weird line" between two regions is usually a **color seam** (two backgrounds meeting), not a
+  divider element. A background may be a **texture / gradient / image**, not a flat color.
+- **Type:** family, weight, size, line-height per text role (author, body, timestamp, unread).
+  **Weight is its own axis** - match it separately from size.
+- **Dimensions - measure, don't eyeball:** rail width, avatar size, bubble radius + padding, row
+  gap, header height. Read pixels off the image; do not invent round numbers (16 / 24 / 32).
+- **State + population:** is the screenshot populated (messages, reactions, attachments, threads,
+  typing) or empty? Note every visible state - you must reproduce it to verify (Step 6).
+
+## Step 2: Route each region to a component + mechanism
+
+Map every region to its Stream component, then to the cheapest mechanism that reaches the design.
+**Three axes** (from [`custom-ui.md`](custom-ui.md) Step 0):
+
+| Region in the screenshot | Stream component | Typical mechanism |
+|---|---|---|
+| Conversation-list rail | `<ChannelList>` + channel preview | Preview differs structurally -> **injection** (`ChannelPreviewUI`) -> completion contract |
+| Message row / bubble | `<MessageList>` + message row | Almost always structural -> **injection** (`MessageUI` via `Message={...}` / `WithComponents`) -> completion contract |
+| Composer / input bar | `<MessageComposer>` | Button placement differs -> **injection** (`MessageComposerUI`) -> completion contract |
+| Top bar / channel header | `<Channel>` header slot | Injection (custom header) or props |
+| Colors / fonts / spacing only | any | **Theming** (shadcn preset + `str-chat` CSS variables) - no contract |
+| Call layout / participant tile / controls | `<StreamCall>` + layout | Injection -> completion contract (Video rows) |
+
+**Rule:** any region where you render your **own** component inherits every sub-feature the prebuilt
+rendered - fill that region's row in the [`custom-ui.md`](custom-ui.md) completion contract
+(attachments, reactions, quoted replies, receipts, threads, ...). A region matched by **theming
+only** (props + CSS vars, no custom component) skips the contract. Prefer **injection** (keep the
+prebuilt tree, swap the regions you must) over a fully-headless rebuild.
+
+## Step 3: Match the palette through the sanctioned channels (not hand-CSS)
+
+You can match a screenshot's colors **without** hand-editing `globals.css` (which
+[`../RULES.md`](../RULES.md) > Theme forbids):
+
+- **App chrome** (your shell, buttons, sidebar): the **shadcn preset** - pick or generate the
+  `--preset` closest to the sampled palette in Step 1b; don't accept a random preset when a
+  screenshot dictates the colors. *(Track E / existing app: the preset is already set - match chrome
+  via the app's existing theme system; if the chrome itself must change color and there is no theme
+  lever, surface that to the user. The Stream chat surface below is matched regardless.)*
+- **Stream chat surface** (bubbles, list, composer): Stream's **`str-chat` theming** - the
+  `str-chat__theme-light/dark` class plus the SDK's CSS custom properties, and `<Channel>` theming.
+  **Confirm the current variable names** on the Theming page ([`docs-map.md`](docs-map.md) Chat
+  cookbook -> theming) - do not hard-code variable names from memory.
+
+This is the design-matching carve-out to "don't touch `globals.css`": theme via presets + documented
+Stream variables, not ad-hoc CSS overrides.
+
+## Step 4: Ground the names (don't guess)
+
+Before writing markup, `WebFetch` each region's live page from [`docs-map.md`](docs-map.md) to
+confirm the current component / prop / hook names, and confirm they match the **installed SDK major**
+(Chat React v14 vs v13 differ - see [`enhance.md`](enhance.md) E1, or the scaffold's resolved
+version). The capability list is durable; the names come from the fetch.
+
+## Step 5: Build (batched)
+
+Implement every region from the spec in one pass, **reusing** SDK pieces inside your components
+(`<MessageText/>`, `<Attachment/>`, `<Avatar/>`, `<ParticipantView/>`) rather than rebuilding them.
+Any BEM / class names on a docs page are a **structural spec, not shippable CSS** - implement with
+Shadcn + Tailwind. Keep the providers mounted (injection over headless).
+
+## Step 6: Verify against the reference (mandatory - render and compare)
+
+A match is not done until you run it and compare, region by region, against the target:
+
+1. **Seed the states the screenshot shows.** If it shows a populated conversation, create a
+   **throwaway** seed (messages incoming + outgoing, a same-author run for grouping, an attachment,
+   a reaction, a reply/thread, long text, a typing event) so every region is visible. This is a
+   **verification-only** carve-out to the no-auto-seeding rule
+   ([`../stream/RULES.md`](../stream/RULES.md)): seed to verify, then **delete it before delivery** -
+   never ship demo data the user did not ask for.
+2. **Render and inspect.** If browser-preview tooling is available (e.g. the Preview MCP:
+   `preview_start` / `preview_screenshot` / `preview_inspect` / `preview_resize`), start the dev
+   server, screenshot the real screen on its actual navigation path, and **inspect computed `color`
+   / `font` / `padding` / `border-radius`** against the sampled spec from Step 1; `preview_resize`
+   to the breakpoints the screenshot implies. Computed-style inspection is exact - trust it over
+   eyeballing. If no preview tooling is present, run the dev server and compare in a browser
+   manually.
+3. **Compare region-by-region and iterate.** Fix drift until each region matches. **Implement every
+   region, the composer included** - a region left at the SDK default is a FAIL, not a "known
+   cosmetic gap".

From efce6be14061b136f000d0e65dfa923d73ebda4b Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Mon, 6 Jul 2026 11:33:14 +0200
Subject: [PATCH 4/7] fix(stream-react): harden design-matching verify + add
 preview/header contracts

Address the Codex adversarial review of design-matching.md.

- Verification no longer seeds the configured Stream app. design-matching.md
  Step 6 and custom-ui.md's Verify now default to LOCAL fixtures (render custom
  components against hand-authored message/channel objects, zero backend writes);
  backend seeding is gated behind explicit user confirmation + a disposable/dev
  app with tracked, verified teardown. Defers to the no-auto-seeding invariant
  instead of carving it out. (GREEN 2/2: agents use fixtures, refuse to seed the
  configured app under time pressure.)
- custom-ui.md now defines completion-contract tables for the two regions the
  design-matching router sends to injection but that previously had no checklist:
  Channel preview (display name, last message, timestamp, unread badge, active
  state, avatar/presence, muted/pinned) and Channel header. (GREEN 1/1: agent
  reproduces the unread badge + active state instead of dropping them.)
- Upgrade the composer + call-layout contracts from prose to checkbox tables so
  every router-governed region has an executable checklist (closes the earlier
  review's finding #3); folds back dropped gotchas (keystroke/stopTyping,
  hasAudio/hasVideo, listDevices-returns-an-Observable).
---
 skills/stream-react/references/custom-ui.md   | 63 ++++++++++++++++---
 .../references/design-matching.md             | 26 +++++---
 2 files changed, 70 insertions(+), 19 deletions(-)

diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
index 655d6f4..2b8e93d 100644
--- a/skills/stream-react/references/custom-ui.md
+++ b/skills/stream-react/references/custom-ui.md
@@ -133,14 +133,53 @@ is the durable part, the *names* come from the fetch.
 | Same-author grouping | `firstOfGroup` / `groupedByUser` from `useMessageContext()` | [ ] |
 | Error / optimistic-send state | `message.status` / `message.error` | [ ] |
 
-**Custom composer:** text input; attachments + upload (and removal); mentions / slash-commands
-autocomplete; send (+ enter-to-send); voice recording (if enabled); edit-message mode.
+**Custom composer (`MessageComposerUI`):**
 
-**Custom call layout / controls:** each participant via `<ParticipantView/>` (don't hand-bind tracks);
-screenshare track; dominant-speaker / active state; camera + mic toggle (`useCameraState` /
-`useMicrophoneState`); join / leave; device selectors (if shown).
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Text input + send (+ enter-to-send) | composer input + submit handler | [ ] |
+| Attachments: attach + upload + remove | upload handler + attachment previews | [ ] |
+| Mentions / slash-command autocomplete | the SDK suggestion list | [ ] |
+| Voice recording (if enabled) | the SDK voice-recording control | [ ] |
+| Edit-message mode | composer edit state | [ ] |
+| Typing events | `channel.keystroke()` / `channel.stopTyping()` | [ ] |
+
+**Custom channel preview (`ChannelPreviewUI`):**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Display name | channel display-name helper | [ ] |
+| Last message: text + sender (attachment / deleted fallbacks) | latest of `channel.state.messages` / `lastMessage` | [ ] |
+| Last-message timestamp | latest message `created_at` | [ ] |
+| Unread count / badge | `unread` preview prop / `channel.countUnread()` | [ ] |
+| Active / selected state | compare to `channel` from `useChatContext()`; `setActiveChannel` | [ ] |
+| Avatar + online presence (DMs) | `<Avatar/>` + member `user.online` | [ ] |
+| Muted / pinned / archived indicator | `channel.muteStatus()` / channel state | [ ] |
+
+**Custom channel header:**
 
-Then **verify on seeded data** that triggers every ticked row (see Verify below) - a near-empty channel
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Channel name / title | channel display name | [ ] |
+| Member / online count or subtitle | `channel.state.members` / watcher count | [ ] |
+| Typing indicator | `useTypingContext()` | [ ] |
+| Avatar | `<Avatar/>` | [ ] |
+| Back / close nav (mobile) | your router + `setActiveChannel(undefined)` | [ ] |
+| Header actions (info / search / call) | as the design shows | [ ] |
+
+**Custom call layout / controls:**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Each participant | `<ParticipantView/>` - don't hand-bind tracks | [ ] |
+| Screenshare track | the screen-share participant / track type | [ ] |
+| Dominant-speaker / active state | participant state from `useCallStateHooks()` | [ ] |
+| Mute / camera-off indicator (per participant) | `hasAudio(p)` / `hasVideo(p)` from `@stream-io/video-react-sdk` | [ ] |
+| Camera + mic toggle | `useCameraState` / `useMicrophoneState` | [ ] |
+| Join / leave | `call.join()` / `call.leave()` | [ ] |
+| Device selectors (if shown) | `useCameraState().devices` (Observable-backed - subscribe, don't `.map` an array) | [ ] |
+
+Then **verify against local fixtures** that trigger every ticked row (see Verify below) - a near-empty channel
 hides every gap. Baseline testing showed that without this contract, agents drop attachments, quoted
 replies, threads, and receipts almost every time, and each run drops a *different* set - so fill the
 rows; don't trust recall.
@@ -163,7 +202,11 @@ rows; don't trust recall.
 
 ## Verify
 
-A bespoke surface isn't done until you run it and check it against the target. Seed data that triggers
-**every** region (incoming + outgoing, a run of same-author messages so grouping shows, an attachment,
-a reaction, a reply/thread, long text, a typing event), open the real screen on its actual navigation
-path, compare region-by-region, and iterate. Match the target, don't approximate it.
+A bespoke surface isn't done until you run it and check it against the target. **Populate every region
+with local mock / fixture data** (incoming + outgoing, a run of same-author messages so grouping shows,
+an attachment, a reaction, a reply/thread, long text, a typing event) - render your components against
+hand-authored message / channel objects, **not** by seeding the configured Stream app. The
+no-auto-seeding rule ([`../stream/RULES.md`](../stream/RULES.md)) still holds: backend seeding to verify
+needs the user's explicit confirmation **and** a disposable / dev app (see [`design-matching.md`](design-matching.md)
+Step 6). Open the real screen on its actual navigation path, compare region-by-region, and iterate.
+Match the target, don't approximate it.
diff --git a/skills/stream-react/references/design-matching.md b/skills/stream-react/references/design-matching.md
index 21ba6c6..5d7e9ee 100644
--- a/skills/stream-react/references/design-matching.md
+++ b/skills/stream-react/references/design-matching.md
@@ -50,7 +50,7 @@ Map every region to its Stream component, then to the cheapest mechanism that re
 | Conversation-list rail | `<ChannelList>` + channel preview | Preview differs structurally -> **injection** (`ChannelPreviewUI`) -> completion contract |
 | Message row / bubble | `<MessageList>` + message row | Almost always structural -> **injection** (`MessageUI` via `Message={...}` / `WithComponents`) -> completion contract |
 | Composer / input bar | `<MessageComposer>` | Button placement differs -> **injection** (`MessageComposerUI`) -> completion contract |
-| Top bar / channel header | `<Channel>` header slot | Injection (custom header) or props |
+| Top bar / channel header | `<Channel>` header slot | Injection (custom header) -> completion contract; or props (no contract) |
 | Colors / fonts / spacing only | any | **Theming** (shadcn preset + `str-chat` CSS variables) - no contract |
 | Call layout / participant tile / controls | `<StreamCall>` + layout | Injection -> completion contract (Video rows) |
 
@@ -94,14 +94,22 @@ Shadcn + Tailwind. Keep the providers mounted (injection over headless).
 
 ## Step 6: Verify against the reference (mandatory - render and compare)
 
-A match is not done until you run it and compare, region by region, against the target:
-
-1. **Seed the states the screenshot shows.** If it shows a populated conversation, create a
-   **throwaway** seed (messages incoming + outgoing, a same-author run for grouping, an attachment,
-   a reaction, a reply/thread, long text, a typing event) so every region is visible. This is a
-   **verification-only** carve-out to the no-auto-seeding rule
-   ([`../stream/RULES.md`](../stream/RULES.md)): seed to verify, then **delete it before delivery** -
-   never ship demo data the user did not ask for.
+A match is not done until you run it and compare, region by region, against the target. **Populate
+the regions with LOCAL fixtures, not backend writes** - the no-auto-seeding rule
+([`../stream/RULES.md`](../stream/RULES.md)) is **not** carved out here:
+
+1. **Populate with local mock data (default).** Render each custom component against hand-authored
+   message / channel objects that trigger every state the screenshot shows - incoming + outgoing, a
+   same-author run (grouping), an attachment, a reaction, a reply/thread, long text, a typing event,
+   read receipts. Mount the component in the SDK's context providers with mocked context values (a
+   dev-only preview route), or feed the fixtures as props. This writes **nothing** to the Stream
+   backend, triggers every state deterministically, and is the most precise way to check a component
+   covers its completion-contract rows. Data already in the app may also be used as-is.
+   - **Do NOT seed the configured Stream app to verify.** Backend seeding is allowed **only** if the
+     user explicitly asks to verify against their live app **and** confirms a **disposable / dev**
+     app (never a shared or production app). Even then: track every resource you create, tear it down
+     in a finally-style flow, verify the deletion, and warn that side effects (webhooks, push,
+     moderation events, unread state) may not be reversible. When in doubt, use fixtures.
 2. **Render and inspect.** If browser-preview tooling is available (e.g. the Preview MCP:
    `preview_start` / `preview_screenshot` / `preview_inspect` / `preview_resize`), start the dev
    server, screenshot the real screen on its actual navigation path, and **inspect computed `color`

From 69b0296fb09dcf1b3e4049f7c5441f1e80ca940c Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Mon, 6 Jul 2026 11:44:53 +0200
Subject: [PATCH 5/7] refactor(stream-react): consolidate CSS-import fact + add
 grounding step + fix citation

Address review findings #8 (CSS dedup), #11 (grounding), #12 (citation).

- #8c CSS imports: sdk.md > CSS imports is now the single canonical home (v14
  alias, v13 path, dist/css/index.css also resolves, and the separate
  EmojiPicker stylesheet). CHAT.md, builder-ui.md, enhance.md point there instead
  of each restating the variants - fixes the inconsistency where the
  emoji-picker note existed in only some copies.
- #11 grounding: custom-ui.md gains a runnable "ground the symbol before wiring"
  step (node -e require(...) / grep the installed .d.ts) so a version-wrong
  export name is caught against the installed package, not just prose "confirm on
  the page".
- #12 citation: CROSS-PRODUCT.md cited a non-fetchable numbered content-repo path
  (video/react/10-advanced/06-chat-with-video.md); replaced with the grounded
  docs-map URL (Video React > Advanced Guides > Chat Integration).

Not changed (deliberate, to avoid over-dedup): #8a the strict-mode client snippet
stays inline in CROSS-PRODUCT.md's AppShell (a complete runnable example) with
VIDEO.md the canonical it mirrors; #8b the composer-rename one-liners are
consistent and low-drift, CHAT.md > Gotchas canonical.
---
 skills/stream-react/builder-ui.md               |  2 +-
 skills/stream-react/enhance.md                  |  2 +-
 skills/stream-react/references/CHAT.md          |  4 ++--
 skills/stream-react/references/CROSS-PRODUCT.md |  2 +-
 skills/stream-react/references/custom-ui.md     | 11 +++++++++++
 skills/stream-react/sdk.md                      |  6 +++++-
 6 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/skills/stream-react/builder-ui.md b/skills/stream-react/builder-ui.md
index 2f6d4e6..0c9b04b 100644
--- a/skills/stream-react/builder-ui.md
+++ b/skills/stream-react/builder-ui.md
@@ -60,7 +60,7 @@ Use Shadcn components, Tailwind utilities, and - if frontend skill packs are alr
 
 ### Stream SDK CSS & Providers
 
-- **Chat:** Import `stream-chat-react/css/index.css` (v14+ preferred alias; v13 used `dist/css/v2/index.css`). Use `useCreateChatClient` from `stream-chat-react` to instantiate. Match theme: `useTheme()` -> `str-chat__theme-dark` or `str-chat__theme-light` to `<Chat>`.
+- **Chat:** Import the Chat CSS ([`sdk.md`](sdk.md) > CSS imports for the path + version variants). Use `useCreateChatClient` from `stream-chat-react` to instantiate. Match theme: `useTheme()` -> `str-chat__theme-dark` or `str-chat__theme-light` to `<Chat>`.
 - **Video:** Import `@stream-io/video-react-sdk/dist/css/styles.css`. Instantiate `StreamVideoClient` with the canonical `useState` + `useEffect` pattern (NOT `useMemo` - see `references/VIDEO.md`).
 - **Feeds:** No CSS import - headless SDK. Wrap app in `<StreamFeeds client={client}>`, then per-feed in `<StreamFeed feed={feed}>`. Use `useCreateFeedsClient()` for client creation - **gate rendering on `client !== null`** (returns `null` until connected). Call `feed.getOrCreate({ watch: true })` inside `setTimeout(50ms)` + `mounted` guard (strict mode protection) before passing to `<StreamFeed>`. See `references/FEEDS.md` for complete patterns.
 
diff --git a/skills/stream-react/enhance.md b/skills/stream-react/enhance.md
index 4b03625..0ae64c6 100644
--- a/skills/stream-react/enhance.md
+++ b/skills/stream-react/enhance.md
@@ -25,7 +25,7 @@ Before writing any code, understand what's already in place:
 
 1. **Install** only the new SDKs **with the project's detected package manager** (from E1) - never introduce a second lockfile: npm -> `npm install <new-packages> --legacy-peer-deps`; yarn -> `yarn add <new-packages>`; pnpm -> `pnpm add <new-packages>`. `--legacy-peer-deps` is **npm-only** (yarn/pnpm resolve Stream peers without it). (the `stream` skill's [`RULES.md`](../stream/RULES.md) > Package manager.)
 2. **Configure via CLI:** run setup commands from the relevant `references/<Product>.md` (App Integration -> Setup). Feeds needs feed groups created; Moderation needs blocklist + config.
-3. **Import CSS** if the product needs it (Chat: `stream-chat-react/css/index.css` (v14+ preferred alias; v13 used `dist/css/v2/index.css`), Video: `@stream-io/video-react-sdk/dist/css/styles.css`).
+3. **Import CSS** if the product needs it - paths + version variants live in [`sdk.md`](sdk.md) > CSS imports (Chat `stream-chat-react/css/index.css`, Video `@stream-io/video-react-sdk/dist/css/styles.css`).
 
 ## E3: Integrate
 
diff --git a/skills/stream-react/references/CHAT.md b/skills/stream-react/references/CHAT.md
index 5acab6e..c5e838e 100644
--- a/skills/stream-react/references/CHAT.md
+++ b/skills/stream-react/references/CHAT.md
@@ -10,7 +10,7 @@ Rules: [../RULES.md](../RULES.md) (login screen first, strict mode protection, r
 
 ## Quick ref
 
-- **Packages:** `stream-chat`, `stream-chat-react`; import `stream-chat-react/css/index.css` (v14+ preferred alias; v13 used `dist/css/v2/index.css`).
+- **Packages:** `stream-chat`, `stream-chat-react`; import `stream-chat-react/css/index.css` (paths + version variants + the `EmojiPicker` stylesheet: [`../sdk.md`](../sdk.md) > CSS imports).
 - **First:** **App Integration** -> **Setup** (CLI / channel types) before UI.
 - **Per feature:** fetch the matching live page from [docs-map.md](docs-map.md) before implementing that screen; for fully hand-built UI on the low-level client, see [custom-ui.md](custom-ui.md).
 
@@ -81,7 +81,7 @@ const client = StreamChat.getInstance(process.env.STREAM_API_KEY!, process.env.S
   }
   ```
 - Listen for `user.banned` event to show banned state in UI
-- Import `stream-chat-react/css/index.css` for default styles - the preferred aliased path (`dist/css/index.css` also resolves; v14+, the `/v2/` subpath was removed). If you use `EmojiPicker`, also import `stream-chat-react/css/emoji-picker.css`
+- Import the Chat CSS once - the path, version variants, and the separate `EmojiPicker` stylesheet all live in [`../sdk.md`](../sdk.md) > CSS imports (the canonical home).
 - `MessageInput` was renamed/removed in v14 - use `MessageComposer` from `stream-chat-react` instead. Note: the React `<MessageComposer />` UI component is distinct from the `MessageComposer` *state class* in `stream-chat` (same name, different thing)
 - Token endpoint as `GET /api/token?user_id=xxx`
 - `upsertUsers` takes an **array** of user objects: `client.upsertUsers([{ id, name, role }])` - NOT an object keyed by ID
diff --git a/skills/stream-react/references/CROSS-PRODUCT.md b/skills/stream-react/references/CROSS-PRODUCT.md
index 212a6a8..94b3d80 100644
--- a/skills/stream-react/references/CROSS-PRODUCT.md
+++ b/skills/stream-react/references/CROSS-PRODUCT.md
@@ -2,7 +2,7 @@
 
 When using two or more of Chat / Video / Feeds in the same app, mount all clients **once** at AppShell and provide them at the root. Per-screen components only render `<Channel>`, `<StreamCall>`, or `<StreamFeed>` from the existing providers - never re-instantiate the clients.
 
-Source of truth: `video/react/10-advanced/06-chat-with-video.md` from the Stream docs (the messenger-clone reference app).
+Source of truth: the **Chat Integration** guide (Video React > Advanced Guides in [`docs-map.md`](docs-map.md)) - `https://getstream.io/video/docs/react/advanced/chat-with-video.md`, the messenger-clone reference app. Fetch it via the map, don't guess a doc path ([`docs-map.md`](docs-map.md) > URL grounding).
 
 ## AppShell skeleton
 
diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
index 2b8e93d..44b5f38 100644
--- a/skills/stream-react/references/custom-ui.md
+++ b/skills/stream-react/references/custom-ui.md
@@ -199,6 +199,17 @@ rows; don't trust recall.
   client lifecycle working.
 - **Still docs-first, still no guessing.** Fetch the page this turn; never wire a hook/prop from
   memory ([`docs-map.md`](docs-map.md) > URL grounding).
+- **Ground the symbol before wiring it (runnable check).** Export names move between majors, so
+  confirm the component / hook / prop actually exists in the *installed* package - not just in memory
+  or a docs page for another version:
+  ```bash
+  # does the export exist in the installed SDK? (v14 vs v13 differ)
+  node -e "console.log(Object.keys(require('stream-chat-react')).filter(k => /MessageComposer|MessageStatus|WithComponents/.test(k)))"
+  # or grep the shipped type defs:
+  grep -rl 'MessageComposer' node_modules/stream-chat-react/dist/*.d.ts
+  ```
+  If the name isn't there, you're on a different major - re-fetch the docs for the installed version
+  ([`docs-map.md`](docs-map.md) Version note) before wiring.
 
 ## Verify
 
diff --git a/skills/stream-react/sdk.md b/skills/stream-react/sdk.md
index 01df347..d1e78b7 100644
--- a/skills/stream-react/sdk.md
+++ b/skills/stream-react/sdk.md
@@ -34,9 +34,13 @@ Product-specific SDK wiring, gotchas, and client patterns: see [`references/*.md
 
 ## CSS imports
 
+**Canonical home for Stream CSS import paths** - other files point here instead of restating the variants.
+
 ```ts
-// Chat (v14+ preferred alias; v13 used dist/css/v2/index.css)
+// Chat: the v14+ preferred alias. (v13 used 'dist/css/v2/index.css'; 'dist/css/index.css' also resolves.)
 import 'stream-chat-react/css/index.css';
+// Chat: ONLY if you render <EmojiPicker /> - its stylesheet is separate:
+import 'stream-chat-react/css/emoji-picker.css';
 // Video
 import '@stream-io/video-react-sdk/dist/css/styles.css';
 ```

From 37e7b85953090aaf8b3492a86cdb8837a0c12286 Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Tue, 7 Jul 2026 11:23:30 +0200
Subject: [PATCH 6/7] feat(stream-react): rewrite design-matching runbook +
 feeds contracts + fill-parent layout

Fresh references/design-matching.md (Classify -> Spec -> Route -> Ground -> Build
-> verify loop): per-product signal->concept taxonomy (chat/video/feeds), fidelity
tiers + viewport derivation, and an empirical verify loop - isolated .design-verify
Playwright harness, capture recipe + probe spec, per-region discrepancy table, loop
cap, GAP-not-matched vocabulary, anti-rationalization table. Includes ChannelList /
MessageList empty + loading states.

references/custom-ui.md: feeds completion contracts (activity card / comment row /
feed composer) + headless-Feeds path + routing rows; empty/loading regions; fix a
stale ../../stream/RULES.md relative link.

builder-ui.md: Stream regions must grow to fill their parent (flex + min-w-0 +
height chain; override the SDK default channel-list width via the documented
str-chat variable).

RULES.md + SKILL.md: repoint design-matching citations to section names; add the
Playwright verify-loop install-trust row + a narrow Bash(node .design-verify/*)
permission; reword the styling-depth flag to the new pipeline.
---
 skills/stream-react/RULES.md                  |   2 +-
 skills/stream-react/SKILL.md                  |   6 +-
 skills/stream-react/builder-ui.md             |   6 +
 skills/stream-react/references/custom-ui.md   |  85 ++-
 .../references/design-matching.md             | 537 ++++++++++++++----
 5 files changed, 510 insertions(+), 126 deletions(-)

diff --git a/skills/stream-react/RULES.md b/skills/stream-react/RULES.md
index e98239f..5c00a1a 100644
--- a/skills/stream-react/RULES.md
+++ b/skills/stream-react/RULES.md
@@ -59,7 +59,7 @@ Shadcn components use `@base-ui/react`, NOT `@radix-ui`. Key differences:
 
 Use whatever theme Shadcn generates. Do not modify `globals.css` after init - no dark mode overrides, no custom variable blocks. The scaffold includes `next-themes` with a `ThemeProvider` (system default, class-based toggle) - use it as-is.
 
-**Design-matching exception:** when a screenshot / Figma dictates the palette, match it through the sanctioned channels - the shadcn `--preset` and Stream's documented `str-chat` theming variables / `<Channel>` theming - not ad-hoc `globals.css` edits. See [`references/design-matching.md`](references/design-matching.md) > Step 3.
+**Design-matching exception:** when a screenshot / Figma dictates the palette, match it through the sanctioned channels - the shadcn `--preset` and Stream's documented `str-chat` theming variables / `<Channel>` theming - not ad-hoc `globals.css` edits. See [`references/design-matching.md`](references/design-matching.md) > Palette through the sanctioned channels.
 
 ## Reference authority
 
diff --git a/skills/stream-react/SKILL.md b/skills/stream-react/SKILL.md
index 978da22..adbcb29 100644
--- a/skills/stream-react/SKILL.md
+++ b/skills/stream-react/SKILL.md
@@ -11,7 +11,7 @@ allowed-tools: >-
   Bash(getstream *),
   Bash(npx *), Bash(npm install *), Bash(npm run *),
   Bash(yarn *), Bash(pnpm *),
-  Bash(node -e *), Bash(node --version), Bash(openssl rand *),
+  Bash(node -e *), Bash(node --version), Bash(node .design-verify/*), Bash(openssl rand *),
   Bash(mv .scaffold*), Bash(rm -rf .scaffold),
   Bash(ls *), Bash(test *),
   Bash(grep *),
@@ -41,7 +41,7 @@ This skill builds, enhances, audits, and migrates Stream Chat, Video, and Feeds
 - **Track F:** skip onboarding and go directly to the audit in [`references/VIDEO.md`](references/VIDEO.md). **Do not enter Start or any build step.**
 - **Track M:** skip onboarding and Read [`migrate.md`](migrate.md) first; it fetches the live release guide before any edit. **Do not enter Start or any scaffold task.**
 
-**Styling-depth flag (orthogonal to the track).** If the request carries a **target appearance** - an attached screenshot, a Figma frame, or "make it look like WhatsApp / Slack / <app>" - route through [`references/design-matching.md`](references/design-matching.md): a reference design is a **checklist of regions, not a color tweak**. It decomposes the image into a written spec, routes each region to a component + mechanism (theming / injection -> the [`references/custom-ui.md`](references/custom-ui.md) completion contract / bespoke), and closes with a render-and-compare verify loop. This composes with the track: **Track A** scaffolds first, then matches before Step 4's build; **Track E** matches within E3. Load it **before** writing UI.
+**Styling-depth flag (orthogonal to the track).** If the request carries a **target appearance** - an attached screenshot, a Figma frame, or "make it look like WhatsApp / Slack / <app>" - route through [`references/design-matching.md`](references/design-matching.md): a reference design is a **checklist of regions, not a color tweak**. Its pipeline is **Classify -> Spec -> Route -> Ground -> Build -> Verify**: classify the fidelity tier + viewport, write a per-screen spec that **names the Stream concept behind every visual signal** via per-product identification checklists (chat / video / feeds), route each region to a component + mechanism (theming / injection -> the [`references/custom-ui.md`](references/custom-ui.md) completion contract / bespoke), ground the names against the live docs, build batched, and close with **an empirical verify loop - screenshot + computed-style checks via session browser tooling or a Playwright fallback - iterated until the spec table passes**. This composes with the track: **Track A** scaffolds first, then matches before Step 4's build; **Track E** matches within E3. Load it **before** writing UI.
 
 ---
 
@@ -91,12 +91,14 @@ This builder runs three classes of network-touching commands. Each is listed her
 | `npx shadcn@latest add ...` (Task A.1) | Vercel - same source as above | Same scaffolder; component sync depends on registry parity. | Component files under `components/ui/`. |
 | `npm install <stream-packages> --legacy-peer-deps` (Task C) | GetStream (npm) for `@stream-io/*` and `stream-chat-react`; transitive deps via standard npm trust | Latest published versions of GetStream's own SDKs - same trust model as the CLI itself. | Modules under `node_modules/`. Runtime SDKs + transitive deps. |
 | `getstream env` (Task B) | GetStream - install instructions in the root skill's "Stream CLI" section in [`../stream/SKILL.md`](../stream/SKILL.md) | n/a (local CLI, no network at this step) | `.env.local` in the project root with `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET`. Task B verifies `.gitignore` covers `.env*` before writing (Next.js scaffold's default already does). The agent never reads `.env.local` (RULES.md > Secrets). |
+| Playwright into a self-contained `.design-verify/` harness (`npm install --prefix .design-verify -D playwright` + browser install) - design-matching verify-loop fallback only | Microsoft - [`microsoft/playwright`](https://github.com/microsoft/playwright) | Latest published; runs **only** when a design match needs a capture and no in-session browser tooling exists (may never run), announced inline at point of use. | Everything under `.design-verify/` (its own `package.json` + `node_modules`, gitignored) - **the app's `package.json` / lockfile are untouched** - plus ~120MB Chromium in the shared Playwright cache. Deleted wholesale at loop exit; nothing lands in the app manifest. |
 
 **Reviewer checklist:**
 
 - All `npx` invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
 - `.env.local` is written by the Stream CLI directly, not by the agent, and is not transmitted into the conversation.
 - If the user wants to pin a specific shadcn version, replace `@latest` with `@<version>` in Tasks A and A.1.
+- The Playwright row is a **design-matching verify-loop fallback**, not part of the scaffold: it is announced inline if and when it runs (it may never run), installs only into a self-contained `.design-verify/` harness (never the app root), and does **not** appear in the Start trust readout above.
 
 ---
 
diff --git a/skills/stream-react/builder-ui.md b/skills/stream-react/builder-ui.md
index 0c9b04b..5fc7bd8 100644
--- a/skills/stream-react/builder-ui.md
+++ b/skills/stream-react/builder-ui.md
@@ -66,6 +66,12 @@ Use Shadcn components, Tailwind utilities, and - if frontend skill packs are alr
 
 **Provider hierarchy:** mount **all** Stream providers - `<Chat>`, `<StreamVideo>`, `<StreamFeeds>` - once at AppShell, in any order. Per-screen components render `<Channel>`, `<StreamCall>`, or `<StreamFeed>` from the existing root providers. **Never re-instantiate Stream clients per screen** - the cleanup of one screen's effect will disconnect a client another screen is still using. For multi-product apps, see [`references/CROSS-PRODUCT.md`](references/CROSS-PRODUCT.md) for the full skeleton.
 
+**Layout / sizing (Stream regions fill their parent).** The prebuilt regions must **grow to fill the container you put them in** - the SDK's default `str-chat` CSS can otherwise cap the **channel list at a fixed width** (you may see ~30% / ~288px) and leave the message list or header not filling. Own the sizing with your wrapper:
+- A **flex row**: the channel-list column gets the width you want (a fixed sidebar width, or `flex-1` to fill); the `<Channel>` / `<Window>` column is `flex-1 min-w-0` (the `min-w-0` defeats flexbox `min-width: auto`, which otherwise blocks `<MessageList>` from growing/shrinking to its column).
+- A **height chain**: root the height at the AppShell (`h-dvh` / `h-full`) so `<ChannelList>` and `<MessageList>` fill vertically instead of collapsing.
+- Each region `w-full h-full` inside its column - the **wrapper decides the width**, not the component's own default; `<ChannelHeader>` (or a custom header) spans the full width of the main pane.
+- If the SDK default still caps the channel-list width, override it through the documented `str-chat` sizing variable (confirm the current name on the Theming page - do not guess it) or a wrapper width utility. Do not ship the ~288px default when full width is wanted.
+
 ### Moderation
 
 **Never build moderation review UI in the app** (RULES.md > Moderation is Dashboard-only). All review happens in the [Stream Dashboard](https://beta.dashboard.getstream.io). The app's role is **CLI setup only** (blocklists, automod config in Step 3).
diff --git a/skills/stream-react/references/custom-ui.md b/skills/stream-react/references/custom-ui.md
index 44b5f38..5c8daab 100644
--- a/skills/stream-react/references/custom-ui.md
+++ b/skills/stream-react/references/custom-ui.md
@@ -79,6 +79,26 @@ Build custom layouts from `useCallStateHooks()` (`useParticipants`, `useCameraSt
 **Keep `ParticipantView` even in a bespoke layout** - it binds the media track for you; only hand-bind
 `participant.videoStream` / `audioStream` when you must. Keep `<StreamVideo>` / `<StreamCall>` mounted.
 
+## The headless path - Feeds
+
+Feeds is **always** headless - there are no prebuilt UI components, so **every** feeds region is a
+custom component and the completion contract **always** applies (there is no theming-only escape). Build
+from the SDK hooks; keep `<StreamFeeds>` / `<StreamFeed>` mounted and create the client with
+`useCreateFeedsClient()` ([`../RULES.md`](../RULES.md) > Strict mode protection). Entry-point hooks
+(confirm the current surface on the page before using - the API evolves):
+
+| Hook | Gives you |
+|---|---|
+| `useFeedActivities(feed)` | `activities`, `is_loading`, `has_next_page`, `loadNextPage` |
+| `useActivityComments({ feed, activity })` | `comments`, `has_next_page`, `is_loading_next_page`, `loadNextPage` |
+| `useAggregatedActivities(feed)` / `useNotificationStatus(feed)` | grouped notifications; `unread` / `unseen` counts |
+| `useOwnFollows(feed)` / `useFeedMetadata(feed)` | follow state; `follower_count` / `following_count` |
+
+Writes go through the feed / client instance - `feed.addActivity(...)`, `client.addComment(...)`,
+`client.addActivityReaction(...)`, `client.addBookmark(...)`, `feed.follow(...)`; confirm each on its
+[`docs-map.md`](docs-map.md) Feeds row before wiring. The initial `useActivityComments` fetch needs a
+one-shot `loadNextPage()` on mount (ref-guard carve-out - [`../RULES.md`](../RULES.md) > Strict mode).
+
 ---
 
 ## Route each region to its live page (do not mirror)
@@ -93,11 +113,17 @@ is then "consume the hook above + render your own markup to match the target."
 | Custom composer / input | Chat cookbook -> **Message Composer UI** |
 | Reactions set / selector | Chat cookbook -> **Reactions Customization** |
 | Channel list item / preview | Chat cookbook -> **Channel List UI** |
+| Empty / loading state (channel list, message list) | Chat cookbook -> **Channel List UI**; also the **MessageList** / **Channel** pages (`EmptyStateIndicator` / `LoadingIndicator`) |
 | Channel header | Chat cookbook -> **Channel Header** |
 | Message actions / context menu | Chat cookbook -> **Message Actions** |
 | Search | Chat cookbook -> **Search Customization** |
 | Custom call controls | Video cookbook -> **Replacing Call Controls** |
 | Custom call layout | Video index -> `ui-cookbook/<slug>.md` (fetch the index) |
+| Feed activity card | Feeds -> **Feeds**, **Activities** |
+| Comment row / list | Feeds -> **Comments** |
+| Feed composer / post box | Feeds -> **Activities** |
+| Reaction / bookmark controls | Feeds -> **Reactions**, **Bookmarks** |
+| Notification list | Feeds -> **Notification Feeds** |
 
 ---
 
@@ -179,6 +205,47 @@ is the durable part, the *names* come from the fetch.
 | Join / leave | `call.join()` / `call.leave()` | [ ] |
 | Device selectors (if shown) | `useCameraState().devices` (Observable-backed - subscribe, don't `.map` an array) | [ ] |
 
+**Feeds contracts** (Feeds is headless, so one of these applies to **every** feeds surface you build -
+same reproduce / `N/A` / `GAP` semantics; names come from the [`docs-map.md`](docs-map.md) Feeds rows):
+
+**Custom feed activity card:**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Author + avatar | `activity.user` (`.name ?? .id`, `.image`) | [ ] |
+| Relative timestamp | `activity.created_at` | [ ] |
+| Text + mentions / links | `activity.text` (docs User Mentions / URL Previews) | [ ] |
+| Attachments | `activity.attachments` (`.type`, `.image_url`, `.asset_url`) | [ ] |
+| Reaction count + own-state toggle | `activity.reaction_groups`, `activity.own_reactions`; `client.addActivityReaction` / `deleteActivityReaction` | [ ] |
+| Comment count + open comments | `activity.comment_count`; `useActivityComments` | [ ] |
+| Bookmark toggle | `activity.own_bookmarks`; `client.addBookmark` / `deleteBookmark` | [ ] |
+| Repost (if shown) | per docs Activities - confirm the API before wiring | [ ] |
+| Poll (if shown) | fetch docs Polls before building (no bundled blueprint) | [ ] |
+| Pagination | `has_next_page` + `loadNextPage()` (wrap for onClick) | [ ] |
+| Loading / empty state | `is_loading`; guard optional fields (`activities?`) | [ ] |
+
+**Custom comment row:**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Author / avatar / timestamp | `comment.user`, `comment.created_at` | [ ] |
+| Text | `comment.text` | [ ] |
+| Nested replies | `client.addComment({ parent_id })` (inherits `object_id` / `object_type`) | [ ] |
+| Comment reactions (if shown) | per docs Reactions - confirm the API | [ ] |
+| Initial fetch | `loadNextPage()` once on mount (ref-guard carve-out - [`../RULES.md`](../RULES.md) > Strict mode) | [ ] |
+| Post a comment | `client.addComment({ object_id: activity.id, object_type: 'activity', comment })` - field is `comment`, NOT `text` | [ ] |
+
+**Custom feed composer:**
+
+| Sub-feature | Reuse (don't hand-roll) | Status |
+|---|---|---|
+| Text input + submit | `feed.addActivity({ type: 'post', text })` - note `feed.`, not `client.` | [ ] |
+| Attachment upload / preview (if shown) | `client.uploadImage()` / `uploadFile()` -> URL in `attachments` | [ ] |
+| Mentions (if shown) | per docs User Mentions | [ ] |
+| Poll creation (if shown) | per docs Polls | [ ] |
+| Post appears without reload | watched feed (`getOrCreate({ watch: true })`) | [ ] |
+| Error / disabled state | `useFeedsClient` null-guard; disable submit when text empty | [ ] |
+
 Then **verify against local fixtures** that trigger every ticked row (see Verify below) - a near-empty channel
 hides every gap. Baseline testing showed that without this contract, agents drop attachments, quoted
 replies, threads, and receipts almost every time, and each run drops a *different* set - so fill the
@@ -197,6 +264,10 @@ rows; don't trust recall.
 - **Keep the providers** (`<Chat>`/`<Channel>`, `<StreamVideo>`/`<StreamCall>`) unless the surface is
   genuinely not a channel/call view - that's what keeps the WebSocket, pagination, read state, and
   client lifecycle working.
+- **Empty + loading states are their own regions.** `<ChannelList>` and `<MessageList>` / `<Channel>`
+  render an `EmptyStateIndicator` (no channels / no messages) and a `LoadingIndicator` (while fetching);
+  if the design shows a specific empty or loading screen, pass custom ones and reproduce them - a seeded
+  or near-full channel hides both, so trigger them with fixtures (Verify below).
 - **Still docs-first, still no guessing.** Fetch the page this turn; never wire a hook/prop from
   memory ([`docs-map.md`](docs-map.md) > URL grounding).
 - **Ground the symbol before wiring it (runnable check).** Export names move between majors, so
@@ -214,10 +285,12 @@ rows; don't trust recall.
 ## Verify
 
 A bespoke surface isn't done until you run it and check it against the target. **Populate every region
-with local mock / fixture data** (incoming + outgoing, a run of same-author messages so grouping shows,
-an attachment, a reaction, a reply/thread, long text, a typing event) - render your components against
-hand-authored message / channel objects, **not** by seeding the configured Stream app. The
-no-auto-seeding rule ([`../stream/RULES.md`](../stream/RULES.md)) still holds: backend seeding to verify
+with local mock / fixture data** (chat: incoming + outgoing, a run of same-author messages so grouping
+shows, an attachment, a reaction, a reply/thread, long text, a typing event, an empty channel list, an empty message list, a
+loading state; feeds: a card with
+reactions + comments + an image, long text, a notification entry) - render your components against
+hand-authored message / channel / activity objects, **not** by seeding the configured Stream app. The
+no-auto-seeding rule ([`../../stream/RULES.md`](../../stream/RULES.md)) still holds: backend seeding to verify
 needs the user's explicit confirmation **and** a disposable / dev app (see [`design-matching.md`](design-matching.md)
-Step 6). Open the real screen on its actual navigation path, compare region-by-region, and iterate.
-Match the target, don't approximate it.
+> The verify loop). Open the real screen on its actual navigation path, compare region-by-region, and
+iterate. Match the target, don't approximate it.
diff --git a/skills/stream-react/references/design-matching.md b/skills/stream-react/references/design-matching.md
index 5d7e9ee..d75e033 100644
--- a/skills/stream-react/references/design-matching.md
+++ b/skills/stream-react/references/design-matching.md
@@ -1,122 +1,425 @@
 # Stream React (web) - matching a reference design (screenshot / Figma / "make it look like X")
 
 Run this whenever the request carries a **target appearance** - an attached screenshot, a Figma
-frame, or "make it look like WhatsApp / Slack / Linear / <app>". A reference design is a **checklist
-of regions**, not a color tweak: the rail width, the message-row layout, where the timestamp and
-receipts sit, the composer's button placement, the header - most differ from Stream's defaults
-*structurally*, not just by color. Stopping at "wallpaper + bubble color" is the known failure mode.
-
-This file is the *procedure*. The *decision* (customize prebuilt vs go bespoke) and the per-region
-**completion contract** live in [`custom-ui.md`](custom-ui.md); every region's current props/hooks
-come from the live page in [`docs-map.md`](docs-map.md). Still **prebuilt-component-first** and
-**docs-first** ([`../RULES.md`](../RULES.md) > Reference authority, Docs-first) - matching a design
-never licenses building from memory.
-
-## Work in batches - decompose all, build all, verify once
-
-A full match is many regions; do **not** build-and-screenshot after every tweak. Decompose every
-region into a written spec first, ground the names once, implement all regions in one pass, then run
-the app once and verify region-by-region. Iterate on the whole surface, not one control at a time.
-
-## Step 1: Decompose the reference into a written spec (before any code)
-
-**Read the image.** Then write the spec down - do not hold it in your head, and do not start coding
-from an impression:
-
-- **Regions / layout:** the columns and bars - conversation-list rail (and its width), main message
-  list, composer, header, thread panel, any secondary rail or pinned banner. Name every region you
-  can see; a region you don't name is a region you'll silently drop.
-- **Component inventory:** per region, the sub-elements present - avatar, author, timestamp,
-  reactions, reply/thread summary, receipts, attachment tiles, composer buttons. This inventory is
-  what the completion contract holds you to.
-- **Color - sample, don't guess:** sample the actual hex of each sub-part (app chrome, list
-  background, incoming vs outgoing bubble, text, muted text, accent, unread badge, online dot). A
-  "weird line" between two regions is usually a **color seam** (two backgrounds meeting), not a
-  divider element. A background may be a **texture / gradient / image**, not a flat color.
-- **Type:** family, weight, size, line-height per text role (author, body, timestamp, unread).
-  **Weight is its own axis** - match it separately from size.
-- **Dimensions - measure, don't eyeball:** rail width, avatar size, bubble radius + padding, row
-  gap, header height. Read pixels off the image; do not invent round numbers (16 / 24 / 32).
-- **State + population:** is the screenshot populated (messages, reactions, attachments, threads,
-  typing) or empty? Note every visible state - you must reproduce it to verify (Step 6).
-
-## Step 2: Route each region to a component + mechanism
-
-Map every region to its Stream component, then to the cheapest mechanism that reaches the design.
-**Three axes** (from [`custom-ui.md`](custom-ui.md) Step 0):
-
-| Region in the screenshot | Stream component | Typical mechanism |
+frame, a whiteboard sketch, or "make it look like WhatsApp / Slack / Linear / <app>". A reference
+design is a **checklist of regions, not a color tweak**: every rail, bar, row, tile, and card is a
+thing to reproduce, and most differ from Stream's defaults *structurally*, not just by color.
+
+**The thesis of this whole file:** a match is **claimed only from a rendered screenshot captured
+this round and compared against the reference** - never from the code you wrote, never from your
+classes, never from eyeballing the running app (however late or careful). "I implemented every region"
+is a plan, not a match.
+
+**Implement EVERY region - the composer is first-class.** Do not deliver a partial match with the
+rest labelled "known cosmetic gap": a region left at the SDK default is a FAIL, not a footnote. Only
+genuine impossibility is a reason to skip, and then you say exactly what and why (see The verify loop
+> Exit honestly).
+
+Division of labor - this file owns the *procedure*; it does not restate what it references:
+- **Customize-vs-bespoke decision + the per-region completion contract:** [`custom-ui.md`](custom-ui.md).
+- **Every URL / page name:** [`docs-map.md`](docs-map.md) - cite row names here, never raw URLs.
+- **Non-negotiables** (no backend seeding, docs-first, palette channels, prebuilt-first, work in
+  batches): [`../RULES.md`](../RULES.md) and [`../../stream/RULES.md`](../../stream/RULES.md).
+
+**Work in batches** (the loop economics): decompose ALL regions -> ground ALL names -> build ALL
+regions -> then **one capture per verify round, never one per tweak**. A full match is many regions;
+batching the fixes and capturing once per round is what keeps it fast.
+
+The pipeline is six steps: **Classify -> Spec -> Route -> Ground -> Build -> Verify loop.**
+
+---
+
+## Step 1: Classify the reference
+
+Before decomposing, classify what you were handed - it sets the match standard and the verify
+standard.
+
+| Tier | Input looks like | Match standard | Verify standard |
+|---|---|---|---|
+| **Pixel** | An app screenshot or a Figma PNG export | Measured: sampled hex values, measured dimensions, exact type | Full verify loop (every spec row measured against a this-round capture) |
+| **Lo-fi** | A sketch, wireframe, or whiteboard photo | Structural: the right regions, present, in the right hierarchy | Verify loop checks presence + layout rows only; palette comes from the sanctioned theme channels, never sampled from pencil |
+| **Figma link, no exports** | A `figma.com/...` URL with no attached images | **Stop and ask for PNG exports, one per frame** | n/a until you have images |
+
+**Figma links: stop and ask.** You cannot authenticate to Figma and you must never guess a design
+from a URL, a file name, or an app's name. Ask for a PNG export per frame, then classify as Pixel.
+
+**The capture requirement is identical for Pixel and Lo-fi** - Step 6 (a browser screenshot taken this
+round) is mandatory for both; only *what you measure* differs (Lo-fi drops color / type sampling, never
+the capture). Presence and layout are confirmed from the this-round capture and the probe `missing`
+flags, never from reading your own markup. **When unsure which tier, treat it as Pixel.**
+
+**Multiple screenshots** = one spec per screen, but **one shared token table**: sample the palette
+and type roles once and reuse them across screens (they are one app). The verify loop then captures
+and diffs each screen separately.
+
+**Derive the viewport** (it is a spec field - the loop captures at exactly this size):
+
+| Reference shows | Viewport (CSS px) |
+|---|---|
+| Portrait ~9:19.5, a status bar / notch | Mobile `390 x 844` |
+| ~3:4, no phone chrome | Tablet `820 x 1180` |
+| Window chrome, multi-column rails | Desktop `1440 x 900` |
+| A known Figma frame | That frame's exact declared size |
+
+**Scale rule:** `scale = reference-image-px-width / viewport-CSS-width`. Divide every dimension you
+measure off the image by `scale` before it enters the spec (a 132px avatar on a 3x mobile shot is
+44 CSS px). Do not enter raw image pixels as CSS pixels.
+
+---
+
+## Step 2: Write the spec
+
+Write the spec down, per screen - do not hold it in your head and do not code from an impression. The
+spec has two halves: the **attributes** (what to measure) and the **taxonomy** (naming the Stream
+concept behind every visual signal). The taxonomy is where regions get silently dropped, so it is the
+centerpiece.
+
+### Attributes to record per region
+
+- **Regions / layout:** name every column, bar, rail, tile, and card. A region you do not name is a
+  region you will silently drop.
+- **Colors - sample, do not guess:** the hex of each sub-part (chrome, list bg, incoming vs outgoing
+  bubble, text, muted text, accent, unread badge, presence dot). A "weird line" between two regions is
+  usually a **color seam** (two backgrounds meeting), not a divider element. A background may be a
+  **texture / gradient / image**, not a flat fill.
+- **Type - per text role:** family, size, **weight** (its own axis - match it separately), line
+  height, for author / body / timestamp / unread each.
+- **Dimensions - measure, do not eyeball:** rail width, avatar size, bubble radius + padding, row
+  gap, header height. Read pixels off the image and divide by `scale`; never invent round numbers
+  (16 / 24 / 32).
+- **State + population:** every visible state (incoming + outgoing, reactions, attachments, threads,
+  typing, receipts, empty). You must be able to reproduce each with a local fixture (Step 6).
+- **Viewport + scale:** carried from Step 1.
+
+**Measuring the two sides (the web's edge over native).** The *rendered* side never needs pixel
+sampling: `getComputedStyle` returns the exact `color` / `font` / `padding` / `border-radius` - trust
+it over any eyeball. Only the *reference* side needs sampling. Sample it with `magick` or Python+PIL
+if present; if neither is available, load the reference image into the capture browser (`file://`) and
+read pixels with a canvas `getImageData` (the `--sample` mode of the capture script in Step 6). Lo-fi
+tier: skip sampling entirely, palette comes from the preset / brand.
+
+### Name the Stream concept behind every signal
+
+For every glyph, badge, pill, and label in the image, name the Stream concept it implies and where it
+routes. A signal you cannot name is a region you will silently drop; if it truly matches nothing here,
+fetch the product index ([`docs-map.md`](docs-map.md)) before declaring it custom chrome. "Routes to"
+cites [`custom-ui.md`](custom-ui.md) contract rows and [`docs-map.md`](docs-map.md) page names - no URLs.
+
+**Chat signals:**
+
+| Visual signal in the image | Stream concept | Routes to |
+|---|---|---|
+| Single / double tick, "seen" | Read + delivery receipts | contract: message row (receipts); docs Channel Read State |
+| Emoji pill with a count | Reactions | contract: message row (reactions); docs Reactions Customization |
+| "N replies" under a message | Thread reply summary | contract: message row (thread indicator); docs Thread |
+| Mini-quote block above a message | Quoted / replied-to parent | contract: message row (quoted parent); docs Message UI |
+| Image grid / file card / audio waveform | Attachments | contract: message row (attachments); docs Voice Recording Attachment |
+| Stacked same-author bubbles, one avatar | Message grouping | contract: message row (grouping); docs Message UI |
+| "(edited)" / "This message was deleted" | Edited / deleted state | contract: message row (edited/deleted); docs Message UI |
+| Floating "Today" / date pill | Date separator | docs Message List |
+| Bold row + badge in the sidebar | Unread state | contract: channel preview (unread); docs Channel List UI |
+| Dot on an avatar | Online presence | contract: channel preview / header (presence); docs Online Status |
+| "X is typing..." | Typing indicator | contract: header (typing); docs Typing Indicator |
+| Plus / smiley / mic inside the input | Composer attach / emoji / voice | contract: composer; docs Message Composer UI, Audio Recorder |
+| Metadata inside vs below the bubble | Structural message row | contract: message row (injection - `MessageUI`); docs Message UI |
+| Hover "..." on a message | Message actions menu | contract: message row (actions); docs Message Actions |
+| "No chats yet" / "No messages yet" screen, or a loading skeleton | Empty / loading state | custom `EmptyStateIndicator` / `LoadingIndicator`; docs Channel List UI, MessageList |
+
+**Video signals:**
+
+| Visual signal in the image | Stream concept | Routes to |
+|---|---|---|
+| Equal grid of tiles | `PaginatedGridLayout` | docs Call layout |
+| One large tile + a filmstrip | `SpeakerLayout` | docs Call layout |
+| Name label on a tile | Participant label | contract: call layout (each participant); docs ParticipantView |
+| Mic-slash on a tile | Mute indicator (`hasAudio`) | contract: call layout (mute indicator); docs ParticipantView |
+| Colored ring around a tile | Dominant speaker | contract: call layout (dominant speaker); docs Call layout |
+| A desktop / window inside a tile | Screenshare | contract: call layout (screenshare); docs ParticipantView |
+| Circular buttons along the bottom | Call controls | contract: call controls; docs Call Control Actions |
+| Small self-view thumbnail | Local participant | contract: call layout (each participant); docs ParticipantView |
+| Signal / reception bars on a tile | Network quality | docs Network Quality Indicator |
+| "LIVE" badge + viewer count | Livestream surface | docs Watching a livestream |
+
+**Feeds signals** (Feeds is headless - every feeds region is bespoke, so the contract always applies):
+
+| Visual signal in the image | Stream concept | Routes to |
+|---|---|---|
+| Avatar + name + time + text card | Activity card | contract: activity card; docs Feeds, Activities |
+| Heart + count | Activity reaction + own-state | contract: activity card (reaction); docs Reactions |
+| Speech-bubble + count | Comments | contract: activity card (comments) + comment row; docs Comments |
+| Two circular arrows + count | Repost | contract: activity card (repost); docs Activities |
+| Bookmark flag | Bookmark | contract: activity card (bookmark); docs Bookmarks |
+| "Follow" button | Follow graph | docs Follow and Unfollow |
+| "What's on your mind" box | Feed composer | contract: feed composer; docs Activities |
+| "X and 2 others..." + a bell | Notification feed | contract: activity card (base) + docs Notification Feeds |
+| A tab switcher over the feed | Multiple / For You feeds | docs For You Feed |
+| Horizontal bars in a post | Poll activity | docs Polls |
+
+---
+
+## Step 3: Route every region
+
+For each region, name the Stream component, then the cheapest mechanism that reaches the design. The
+three axes: **theming** (props + CSS vars, no custom component), **injection** (your own component for
+one region -> completion contract), **bespoke** (a headless tree -> completion contract). This table
+maps screenshot region -> component + mechanism; [`custom-ui.md`](custom-ui.md)'s table maps a bespoke
+region -> its docs page (no duplication).
+
+| Region in the screenshot | Stream component | Cheapest mechanism |
 |---|---|---|
-| Conversation-list rail | `<ChannelList>` + channel preview | Preview differs structurally -> **injection** (`ChannelPreviewUI`) -> completion contract |
-| Message row / bubble | `<MessageList>` + message row | Almost always structural -> **injection** (`MessageUI` via `Message={...}` / `WithComponents`) -> completion contract |
-| Composer / input bar | `<MessageComposer>` | Button placement differs -> **injection** (`MessageComposerUI`) -> completion contract |
-| Top bar / channel header | `<Channel>` header slot | Injection (custom header) -> completion contract; or props (no contract) |
-| Colors / fonts / spacing only | any | **Theming** (shadcn preset + `str-chat` CSS variables) - no contract |
-| Call layout / participant tile / controls | `<StreamCall>` + layout | Injection -> completion contract (Video rows) |
-
-**Rule:** any region where you render your **own** component inherits every sub-feature the prebuilt
-rendered - fill that region's row in the [`custom-ui.md`](custom-ui.md) completion contract
-(attachments, reactions, quoted replies, receipts, threads, ...). A region matched by **theming
-only** (props + CSS vars, no custom component) skips the contract. Prefer **injection** (keep the
-prebuilt tree, swap the regions you must) over a fully-headless rebuild.
-
-## Step 3: Match the palette through the sanctioned channels (not hand-CSS)
-
-You can match a screenshot's colors **without** hand-editing `globals.css` (which
-[`../RULES.md`](../RULES.md) > Theme forbids):
-
-- **App chrome** (your shell, buttons, sidebar): the **shadcn preset** - pick or generate the
-  `--preset` closest to the sampled palette in Step 1b; don't accept a random preset when a
-  screenshot dictates the colors. *(Track E / existing app: the preset is already set - match chrome
-  via the app's existing theme system; if the chrome itself must change color and there is no theme
-  lever, surface that to the user. The Stream chat surface below is matched regardless.)*
+| Channel-list rail | `<ChannelList>` + preview | Structural preview -> injection (`ChannelPreviewUI`) -> contract |
+| Message row / bubble | `<MessageList>` + row | Almost always structural -> injection (`MessageUI` via `Message=` / `WithComponents`) -> contract |
+| Composer / input bar | `<MessageComposer>` | Button placement differs -> injection (`MessageComposerUI`) -> contract |
+| Channel header | `<Channel>` header slot | Injection -> contract; or props only (no contract) |
+| Participant tile / call layout | `<StreamCall>` + layout | Prebuilt layout, or injection -> contract |
+| Call-controls bar | `CallControls` | Prebuilt, or injection (custom controls) -> contract |
+| Feed of cards | `useFeedActivities` + your card | Bespoke -> contract (always) |
+| Comment list | `useActivityComments` + your row | Bespoke -> contract (always) |
+| Post box | `feed.addActivity` + your form | Bespoke -> contract (always) |
+| Colors / fonts / spacing only | any | Theming (preset + `str-chat` vars) - no contract |
+
+Rules:
+- **Any region where you render your own component fills its [`custom-ui.md`](custom-ui.md) contract**
+  (it inherits every sub-feature the prebuilt drew). A theming-only region skips the contract.
+- **Injection over headless.** Keep the prebuilt tree; swap only the regions you must.
+- **Feeds has no prebuilt UI: every feeds region is bespoke by definition, so the contract always
+  applies** - there is no theming-only escape for any feeds region (card, composer, comment row, or
+  notification list).
+
+---
+
+## Step 4: Ground the names
+
+Batch-collect every [`docs-map.md`](docs-map.md) row named in Step 3, then `WebFetch` them **in one
+pass before building** - confirm the current component / prop / hook names, and confirm they match the
+**installed SDK major** (Chat React v14 vs v13 differ). Use the runnable installed-export check in
+[`custom-ui.md`](custom-ui.md) (do not restate it here). The capability list is durable; the names come
+from the fetch. On fetch failure, hand to the `stream-docs` skill; if neither resolves it, **stop and
+ask** ([`../RULES.md`](../RULES.md) > Docs-first). Never build from memory.
+
+---
+
+## Step 5: Build, batched
+
+Implement every region from the spec in one pass:
+- **Reuse SDK pieces inside your components** (`<MessageText/>`, `<Attachment/>`, `<Avatar/>`,
+  `<ParticipantView/>`) rather than rebuilding them.
+- **BEM / class names on a docs page are a structural spec, not shippable CSS** - implement with
+  Shadcn + Tailwind.
+- **Keep the providers mounted** (`<Chat>` / `<Channel>`, `<StreamVideo>` / `<StreamCall>`,
+  `<StreamFeeds>` / `<StreamFeed>`) - injection over headless.
+
+### Palette through the sanctioned channels
+
+Match the reference's colors **without** hand-editing `globals.css` (which [`../RULES.md`](../RULES.md)
+> Theme forbids):
+- **App chrome** (your shell, buttons, sidebar): the **shadcn preset** closest to the sampled palette
+  - do not accept a random preset when a screenshot dictates the colors. *(Track E / existing app: the
+  preset is already set; match chrome via the app's existing theme system, and if the chrome must
+  change color with no theme lever, surface that to the user. The Stream surface is matched
+  regardless.)*
 - **Stream chat surface** (bubbles, list, composer): Stream's **`str-chat` theming** - the
-  `str-chat__theme-light/dark` class plus the SDK's CSS custom properties, and `<Channel>` theming.
-  **Confirm the current variable names** on the Theming page ([`docs-map.md`](docs-map.md) Chat
-  cookbook -> theming) - do not hard-code variable names from memory.
-
-This is the design-matching carve-out to "don't touch `globals.css`": theme via presets + documented
-Stream variables, not ad-hoc CSS overrides.
-
-## Step 4: Ground the names (don't guess)
-
-Before writing markup, `WebFetch` each region's live page from [`docs-map.md`](docs-map.md) to
-confirm the current component / prop / hook names, and confirm they match the **installed SDK major**
-(Chat React v14 vs v13 differ - see [`enhance.md`](enhance.md) E1, or the scaffold's resolved
-version). The capability list is durable; the names come from the fetch.
-
-## Step 5: Build (batched)
-
-Implement every region from the spec in one pass, **reusing** SDK pieces inside your components
-(`<MessageText/>`, `<Attachment/>`, `<Avatar/>`, `<ParticipantView/>`) rather than rebuilding them.
-Any BEM / class names on a docs page are a **structural spec, not shippable CSS** - implement with
-Shadcn + Tailwind. Keep the providers mounted (injection over headless).
-
-## Step 6: Verify against the reference (mandatory - render and compare)
-
-A match is not done until you run it and compare, region by region, against the target. **Populate
-the regions with LOCAL fixtures, not backend writes** - the no-auto-seeding rule
-([`../stream/RULES.md`](../stream/RULES.md)) is **not** carved out here:
-
-1. **Populate with local mock data (default).** Render each custom component against hand-authored
-   message / channel objects that trigger every state the screenshot shows - incoming + outgoing, a
-   same-author run (grouping), an attachment, a reaction, a reply/thread, long text, a typing event,
-   read receipts. Mount the component in the SDK's context providers with mocked context values (a
-   dev-only preview route), or feed the fixtures as props. This writes **nothing** to the Stream
-   backend, triggers every state deterministically, and is the most precise way to check a component
-   covers its completion-contract rows. Data already in the app may also be used as-is.
-   - **Do NOT seed the configured Stream app to verify.** Backend seeding is allowed **only** if the
-     user explicitly asks to verify against their live app **and** confirms a **disposable / dev**
-     app (never a shared or production app). Even then: track every resource you create, tear it down
-     in a finally-style flow, verify the deletion, and warn that side effects (webhooks, push,
-     moderation events, unread state) may not be reversible. When in doubt, use fixtures.
-2. **Render and inspect.** If browser-preview tooling is available (e.g. the Preview MCP:
-   `preview_start` / `preview_screenshot` / `preview_inspect` / `preview_resize`), start the dev
-   server, screenshot the real screen on its actual navigation path, and **inspect computed `color`
-   / `font` / `padding` / `border-radius`** against the sampled spec from Step 1; `preview_resize`
-   to the breakpoints the screenshot implies. Computed-style inspection is exact - trust it over
-   eyeballing. If no preview tooling is present, run the dev server and compare in a browser
-   manually.
-3. **Compare region-by-region and iterate.** Fix drift until each region matches. **Implement every
-   region, the composer included** - a region left at the SDK default is a FAIL, not a "known
-   cosmetic gap".
+  `str-chat__theme-light/dark` class, the SDK's documented CSS custom properties, and `<Channel>`
+  theming. **Confirm the current variable names on the Theming page** ([`docs-map.md`](docs-map.md)) -
+  do not hard-code variable names from memory.
+- **Lo-fi tier:** palette from the preset / brand, never sampled from a pencil sketch.
+
+### The reference frame wins over the generic shell
+
+Apply [`builder-ui.md`](builder-ui.md) > Reference-design override: **drop chrome the reference does
+not show** (a bare phone-chat reference has no app top-bar and no channel-list sidebar) and **fill the
+viewport** (no fixed-width chat strip beside empty background). The reference is the shell, not a
+widget inside the generic shell. The Stream regions themselves must **grow to fill their container** -
+the SDK default can cap the channel list at a fixed ~288px and leave the message list / header not
+filling; size via the wrapper (flex + `min-w-0`, a height chain) per [`builder-ui.md`](builder-ui.md) >
+Layout / sizing.
+
+---
+
+## Step 6: The verify loop
+
+**"Verified" = a screenshot of the rendered app, captured THIS round, compared region-by-region
+against the reference, with every spec row measured.** Reading the code, trusting your class names, or
+eyeballing the running app (however late or careful) does not count. A match claimed any other way is
+not a match; it is a guess that happened to compile.
+
+### 6a. Populate every state - fixtures by default
+
+Every state the reference shows must be **visibly present in the capture**. Default to **local
+fixtures** (no backend writes - the no-seeding invariant, [`../../stream/RULES.md`](../../stream/RULES.md)
+> No auto-seeding, holds). Enumerate them by product:
+- **Chat:** incoming + outgoing, a same-author run (grouping), an attachment, a reaction, a
+  reply/thread, long text, a typing event, read receipts, **an empty channel list, an empty message
+  list, and (if the design shows one) a loading skeleton**.
+- **Video:** multiple tiles, a muted participant, a screenshare, a dominant speaker.
+- **Feeds:** a card with reactions + comments + an image, long text, a notification entry.
+
+**Render fixtures through the standard flow - never a login-bypassing route.** Mount the real
+components against your fixtures in a **dev-only view reached AFTER the normal username login and
+sitting inside the real AppShell / providers**, so the real layout, providers, and authenticated state
+are exercised. **Guard it with an env flag that is code-checked absent in production** (the view
+early-returns / 404s when the flag is unset), so a missed cleanup can never ship a live test surface. A
+bare route that skips login renders components in a fake context and passes while production differs -
+do not use one.
+
+**Opt-in real-data check.** If the user prefers a real-backend pass over fixtures, seed the states into
+a **throwaway app provisioned solely for this check and deleted after** - **not** the app the project
+connects to (its `.env.local` key), and **not** any app holding other users' data - with explicit
+confirmation + tracked teardown, then capture the actual screen. "Dev" is not "disposable": if the only
+app available is the project's own, you may **not** seed it; fall back to fixtures. Fixtures stay the
+default; when in doubt, use fixtures.
+
+This step is **required**: a claim that a region "would render" / "is wired so it will look right" -
+without a this-round capture that actually shows it populated - is not verification, and an unpopulated
+fixture is `GAP - not matched`, not an inference.
+
+### 6b. Tool ladder (use the first rung that works; never skip to a lower rung while a higher one works)
+
+A render comes from a browser, not from markup: `curl`-ing the page HTML or reading the served CSS
+is **not** a capture (no layout, no computed styles, no fonts resolved). Use the first rung that works
+and do not substitute a static read for it.
+
+1. **In-session browser tooling, if present.** Anything that loads a URL at a set viewport,
+   screenshots it, and reads computed styles / the DOM. Examples: a Preview MCP
+   (`preview_start` / `preview_screenshot` / `preview_inspect` / `preview_resize`) or a connected
+   Chrome - *examples of a capability*, use whatever the session exposes. Before concluding it is
+   absent, **state which capture tools you checked for**; an unstated "no tooling here" is not a reason
+   to descend.
+2. **Playwright fallback - mandatory whenever `node` / `npm` are available.** Announce first (published
+   by Microsoft, `microsoft/playwright`; ~120MB of Chromium to the shared Playwright cache), then
+   **actually run** it - installed into a **self-contained `.design-verify/` harness with its own
+   `package.json`, so the app's `package.json` / lockfile are never touched** (Track E may be a
+   yarn / pnpm project - **never add playwright to the app root with any manager** - no `npm install`, `pnpm add`, or `yarn add` there; the harness install below is npm-only whatever the app uses):
+   ```bash
+   mkdir -p .design-verify && printf '{"private":true}\n' > .design-verify/package.json
+   npm install --prefix .design-verify -D playwright
+   .design-verify/node_modules/.bin/playwright install chromium   # add --with-deps on Linux CI
+   ```
+   Descend to rung 3 **only if that command actually errors** - paste the failure. Predicting "this
+   looks sandboxed / offline, it would fail" and skipping the install is **not** permitted; run it and
+   observe. Never fake a capture and never claim rung 2 ran when it did not. *(If the project has **no runnable app at all** - nothing to serve -
+   that is a prerequisite failure: report UNVERIFIED per 6e and do not install a browser to screenshot
+   nothing. Not having **built the fixtures view yet** is not this case - build it, then capture; in a
+   design-matching task the app exists by definition, so this rarely applies.)*
+3. **Last resort - manual with the user.** Only after rung 1 was checked and rung 2 was *run and
+   errored* (show both). Give the user the dev-server URL, the viewport, and the spec table, and ask
+   them to compare. Until the user confirms, **every region is implemented but UNVERIFIED** - say
+   exactly that, and never imply a match you did not see.
+
+### 6c. Capture recipe
+
+1. Start the dev server in the background (SKILL.md port convention: a random 5-digit port).
+2. Log in through the standard Login Screen and open the env-guarded fixtures view (or, on the opt-in
+   real-data path, navigate to the seeded screen).
+3. Set the **Step 1 viewport** and `deviceScaleFactor: 2`.
+4. Wait for network-idle, then ~500ms for images / animations to settle.
+5. Produce, per screen: **(a)** a full-screen screenshot; **(b)** **element crops** of the high-detail
+   regions (the composer, one message row, one tile / card) - detail is lost in a full-page shot;
+   **(c)** a **probe pass** that, for each selector in your probe list, returns its
+   `getBoundingClientRect` + the `getComputedStyle` values you need and a `missing: true` flag when the
+   selector matches nothing (that flag IS the structural-presence check in 6d); **(d)** optionally,
+   sample the reference image for the color rows (`magick` / PIL, or a canvas `getImageData` over a
+   `file://` load).
+
+With in-session tooling, use its screenshot + computed-style calls directly. With the Playwright
+harness, write your own small runner **in `.design-verify/`** (its own `package.json` means CommonJS
+`require` and ESM both work; use a `.cjs` extension to force CommonJS if you prefer) - the
+`npx playwright screenshot` CLI cannot run probes, so a script is needed. **Write it AND run it**
+(`node .design-verify/<runner>`); the probe's actual stdout is the artifact you cite in 6d - a runner
+authored but not executed produces no Rendered values. Probe shape:
+
+```
+// probe list: [{ selector: '.str-chat__message-text', props: ['color','font-size','font-weight'] }, ...]
+// each probe -> { selector, rect, styles: { ... } }   OR   { selector, missing: true }
+```
+
+### 6d. Compare protocol (three checks per round, in order)
+
+1. **Read both images side by side.** Numbers can pass while the screen reads wrong (font fallback,
+   seams, weight). Name the specific things you checked (seams, font shape, weight, alignment, overall
+   balance) - a bare "reads the same" with nothing named is not a completed check. **Loop until the
+   side-by-side reads as the same screen, not just until the numbers match.**
+2. **Computed-style diff**, mapping each spec field explicitly:
+   - color -> `color` / `background-color`
+   - type -> `font-family` / `font-size` / `font-weight` / `line-height`
+   - dimensions -> the rect + `border-radius` / `padding` / `gap`
+
+   Tolerances: dimensions within `+/-2` CSS px; colors within a small band of the sampled value (about
+   `+/-3` per 8-bit channel, to absorb anti-aliasing - a visible hue / shade change is a FAIL), stating
+   both hex values on every color row; **`font-family` must resolve to the intended family - a fallback
+   to serif/sans is a FAIL, not a rounding error.**
+3. **Structural presence** via the probe `missing` flags: every Step 2 taxonomy signal must exist in
+   the DOM. A `missing:true` is a dropped region.
+
+Output a per-region discrepancy table. Every "Rendered" value is copied from this round's probe output
+/ capture, and the Source cell names the file - a row with no Source is UNVERIFIED, not PASS:
+
+| Region | Spec | Rendered (this round) | Source (capture file + probe) | Verdict | Fix |
+|---|---|---|---|---|---|
+| ... | ... | ... | ... | PASS / FAIL | ... |
+
+**Completeness gate.** Every signal named in Step 2's taxonomy and every row of the applicable
+[`custom-ui.md`](custom-ui.md) contract must have a probe selector and a table row. Before exit, diff
+the probe list against the taxonomy - any taxonomy entry with no probe is an unverified region (treat
+as FAIL), never a silent omission. Each high-detail region (composer, one message row, one tile / card)
+must also have an element crop cited in its Source cell - a full-page shot alone does not satisfy a
+high-detail row. A short table is an incomplete spec, not an early finish.
+
+### 6e. Iterate and exit honestly
+
+Fix **all** failing rows, **then** recapture **once** (work in batches - not one recapture per row).
+**Loop cap: 5 rounds.**
+
+Exit only when every spec row is **PASS with this-round evidence**: the final claim cites the last
+capture. "This round" = the capture taken after your most recent edit to any file affecting the
+previewed regions (components, CSS / theme, fixtures, preset). *Any* such edit - however small -
+invalidates the prior capture; if `git status` shows changes to those paths since the cited capture, it
+is stale and you re-capture before claiming PASS.
+
+**If no capture happened this round on any rung** (tooling absent, install failed, app unreachable),
+the deliverable says **UNVERIFIED** and lists which regions are implemented-but-unseen. Do not describe
+any region as "matched" or "verified" in the delivery when you never rendered it - a note-to-self that
+it is unverified does not license a customer-facing "it matches." UNVERIFIED still requires the fixtures
+view to be **built** and its states populated - "unseen" means the capture tooling failed, not that you
+skipped the fixtures work; an UNVERIFIED deliverable with no fixtures view built is an unfinished task,
+not an honest exit.
+
+At the cap, report each unresolved row as **`GAP - not matched`** (the [`custom-ui.md`](custom-ui.md)
+vocabulary), with **both measured values** (spec vs rendered) and the honest reason. "Deferred",
+"minor", "close enough", and "cosmetic" are banned relabels of a GAP.
+
+**"Genuine impossibility"** (the only pre-cap reason to skip a region) means the SDK or platform cannot
+express it at all - cite the specific limitation, not "hard to fixture", "fiddly", or "low on time". A
+region you skip for *any* reason is still a row in the discrepancy table marked `GAP - not matched` with
+the reason (impossible regions included), never a prose footnote. Time pressure is never impossibility.
+
+**Cleanup at exit (finally-style - run it even on failure or interruption):** delete the entire
+`.design-verify/` harness (its `package.json` / `node_modules` included - nothing landed in the app
+manifest, so there is no app devDependency to disclose); remove the dev-only fixtures view + its env
+flag and confirm it is gone (it is also code-guarded out of production, so a missed cleanup cannot ship
+a live surface). If you used the opt-in disposable-app seed, tear down every seeded resource and verify
+the deletion.
+
+### 6f. Anti-rationalization
+
+Matching a design under time pressure breeds excuses. The discrepancy table decides, not adjectives.
+
+| Excuse | Reality |
+|---|---|
+| "It's close enough / basically there" | The table decides with measured values, not an adjective. |
+| "I verified it by reading the code" | Code is not a render. Capture this round or it is UNVERIFIED. |
+| "There's no browser tooling here" | The ladder has three rungs. Rung 2 (Playwright) installs; rung 3 is labeled UNVERIFIED. |
+| "Screenshots are too slow to loop" | The loop is batched: decompose/build all, ~5 captures total, not one per tweak. |
+| "The computed styles all match" | The side-by-side Read is mandatory every round - numbers miss font fallback, seams, weight. |
+| "`next build` passed" | Compiling is not matching. A green build says nothing about the pixels. |
+| "The user can just check it" | That is rung 3 only, and only after rungs 1-2 fail - and it ships labeled UNVERIFIED. |
+| "I'll curl the HTML / read the served CSS instead" | Static markup is not a render - no layout, no computed styles, no resolved fonts. Use a browser rung (1 or 2). |
+| "The font won't install, so I'll note it as minor" | An unresolved row is `GAP - not matched` with both measured values, never "minor". |
+| "I'll `pnpm add` / `yarn add` playwright instead" | Any add in the app root corrupts its lockfile. Install only into the `.design-verify/` harness (`npm install --prefix`), whatever the app uses. |
+| "I wrote the probe / capture script" | Writing it is not running it. Run it this round; its real stdout is the evidence - an authored-but-unrun script proves nothing. |
+
+**Red flags - stop:**
+- Claiming "matches" without a capture taken **this round**.
+- Ending with failing rows left unlabeled, or a GAP relabeled "deferred" / "minor" / "cosmetic".
+- Skipping the composer or the receipts rows because they are fiddly.
+- Downgrading a measured FAIL to a soft word to close the task.

From f2b149511f462ce192893e1fa4f81d90e91672fe Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Tue, 7 Jul 2026 11:26:57 +0200
Subject: [PATCH 7/7] feat(stream-react): reference-design shell override +
 getstream init auth flow

builder-ui.md: add the Reference-design override (the reference's frame wins over
the generic shell) and make the App Header a default-shell element that is omitted
when the reference design shows no top-bar.

SKILL.md: move Step 1 auth to `getstream init` (opens the browser as its own
invocation when unsigned); drop the removed pre-1.0 `OrganizationRead` probe and
note `getstream api` is now product-namespaced; reword the Step 1b app pick around
the configured-app default.
---
 skills/stream-react/SKILL.md      | 8 ++++----
 skills/stream-react/builder-ui.md | 6 ++++--
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/skills/stream-react/SKILL.md b/skills/stream-react/SKILL.md
index adbcb29..cadbb60 100644
--- a/skills/stream-react/SKILL.md
+++ b/skills/stream-react/SKILL.md
@@ -106,21 +106,21 @@ This builder runs three classes of network-touching commands. Each is listed her
 
 Execute phases **in order** (later steps depend on earlier ones). Do **not** run independent phases in parallel. Shell discipline (one `bash -c` per phase, no `bash -ce`, `getstream login` standalone) lives in [`../stream/RULES.md`](../stream/RULES.md) > Shell discipline.
 
-**Two-call exception:** If you must Read JSON (e.g. `OrganizationRead`) and then choose IDs, use one call for the read, one batched call for all creates.
+**Two-call exception:** If you must Read JSON from a `getstream api` call and then choose IDs, use one call for the read, one batched call for all creates.
 
 ### Step 0: Package manager
 Always use `npm`. Never use bun. ([`RULES.md`](RULES.md) > Package manager.)
 
 ### Step 1: Auth
-Run the **Provisioning > Step 1: Auth** flow in [`builder.md`](builder.md) (auth probe via `getstream api OrganizationRead`; `getstream login` as its own invocation on exit 2; hang recovery). On **exit 0**, continue to Step 1b.
+Authentication is handled by `getstream init` (Step 2) - it opens the browser as its **own invocation** if you're not signed in ([`builder.md`](builder.md) > Provisioning; [`../stream/RULES.md`](../stream/RULES.md) > Shell discipline). There is **no separate `getstream api` auth probe** - CLI v1.0.0 removed the pre-1.0 `OrganizationRead` probe, and `getstream api` subcommands are now product-namespaced (e.g. `getstream api chat ...`). Continue to Step 1b.
 
 ### Step 1b: Theme + app pick
 
-Ask both setup questions in **one message** before doing anything else - a single pause, the same "ask exactly once, then act" pattern the other platform packs use for credentials. Build the app options from what is already in context: the configured org/app from `getstream init` and the org list from Step 1's `OrganizationRead` output.
+Ask both setup questions in **one message** before doing anything else - a single pause, the same "ask exactly once, then act" pattern the other platform packs use for credentials. Build the app options from what is already in context: the org/app already configured in this project by a prior `getstream init`, if any. If none is configured yet, `getstream init` lists your orgs/apps interactively when it runs (Step 2) - don't try to enumerate them with a raw `getstream api` call.
 
 > **Quick setup - two questions:**
 > 1. **Theme:** I can use a random shadcn theme, or you can design your own at [ui.shadcn.com/create](https://ui.shadcn.com/create) and share the `--preset` value (e.g. `--preset b1Gdi7z7r`). Random, or do you have a preset? *(If you already shared a screenshot or Figma, I'll match that instead - skip this.)*
-> 2. **Stream app:** *(an app is configured)* Use the currently configured app **`<name>`** (default), pick another existing org/app, or create a fresh one? / *(no app configured)* You have these orgs: `<list>`. Pick one to use - I'll list its apps - or create a fresh org + app?
+> 2. **Stream app:** *(an app is already configured)* Use the currently configured app **`<name>`** (default), or pick/create a different one? / *(no app configured yet)* `getstream init` will list your orgs and apps when it runs - use an existing one, or create a fresh org + app?
 
 **STOP here and wait for the user's answer.** Do not continue with any other step until the user responds. Asking a question and continuing to work in parallel is confusing - the user misses the question as output scrolls past.
 
diff --git a/skills/stream-react/builder-ui.md b/skills/stream-react/builder-ui.md
index 5fc7bd8..aa953f7 100644
--- a/skills/stream-react/builder-ui.md
+++ b/skills/stream-react/builder-ui.md
@@ -2,6 +2,8 @@
 
 Load when executing **Step 4** (after scaffold). Rules: [`RULES.md`](RULES.md) (login screen first, theme, reference authority).
 
+> **Reference-design override.** If the request carries a screenshot / Figma / "make it look like X", the **reference's frame wins over the generic shell defined here** (App Header, sidebar, shell geometry). Reproduce the reference's frame per [`references/design-matching.md`](references/design-matching.md) - **remove in-app chrome the reference doesn't show** (a bare phone-chat reference has no app top-bar and no chat-list sidebar) and **fill the viewport** (no fixed-width chat strip beside empty background) - then apply the region + theming guidance here within it. The Login Screen stays as the auth gate unless the reference itself is the full app.
+
 ### Step 4: Generate ALL code files
 Write every file sequentially. Follow the UI Guidelines below for all visual styling. See **RULES.md > Reference authority** - reference files are the only source of truth for SDK wiring. Before writing each component, load the prebuilt path in the relevant `references/<Product>-blueprints.md`; fetch the matching live page from [`references/docs-map.md`](references/docs-map.md) for any customization, and load [`references/custom-ui.md`](references/custom-ui.md) (the completion contract) first when you write your own component for a region - even one, even via `Message=` / `WithComponents`.
 
@@ -22,9 +24,9 @@ Centered card on a neutral background. No sidebar, no nav - just the login form.
 - After successful token fetch, render the main app UI (state gate, not redirect)
 - App name / use-case label above the input
 
-#### App Header (required for every app)
+#### App Header (default shell - omit when a reference design doesn't show it)
 
-Once logged in, every app MUST show a persistent header bar:
+Once logged in, the default shell shows a persistent header bar (but see the **Reference-design override** above - a screenshot that has no app top-bar means you drop this):
 
 - **Left:** App name (derived from use case)
 - **Right:** Avatar circle (initial letter) + username + "Switch User" button