RN chat skill improvement - design matching

skills/stream-react-native/RULES.md

@@ -53,6 +53,8 @@ Before installing Stream Chat, Video, or Feeds RN packages:
 
 Before changing an existing Chat, Video, or Feeds UI, fetch the manifest-selected markdown page that matches the requested change. Choose the implementation path from the docs and the existing app: theme for style-only changes (Chat / Video; Feeds is headless and changes are made directly in the components you wrote), component overrides for UI slots (Chat / Video only), documented props/hooks for behavior, and optional native packages only for requested native capabilities.
 
+**Matching a provided design is a decompose-and-plan-first task, not a theming afterthought.** When a Chat request carries a target appearance (screenshot, Figma, "look like \<app\>"), run [`references/CHAT-REACT-NATIVE-design-matching.md`](references/CHAT-REACT-NATIVE-design-matching.md) **before** writing UI code: decompose the reference region by region and plan every difference as theming / layout / functional, then verify region-by-region against the reference. Implement **every** region, the composer included; a region left at the SDK default is a FAIL, not a "known cosmetic gap." Report a region as unmatched only when it is genuinely impossible (say what + why), never because it is risky or more effort.
+
 ---
 
 ## Required peer setup

skills/stream-react-native/SKILL.md

@@ -8,7 +8,7 @@ metadata:
 allowed-tools: >-
   Read, Write, Edit, Glob, Grep,
   WebFetch(domain:getstream.io),
-  Bash(ls *), Bash(find . *), Bash(grep *),
+  Bash(ls *), Bash(find . *), Bash(grep *), Bash(sips *),
   Bash(cat package.json), Bash(cat app.json), Bash(cat app.config.js), Bash(cat app.config.ts),
   Bash(cat babel.config.js), Bash(cat metro.config.js),
   Bash(command -v getstream), Bash(getstream *),
@@ -154,11 +154,50 @@ Product-specific setup, docs lookup, gotchas, and UI blueprints live under **`re
 - **Video screen/component blueprints:** [`references/VIDEO-REACT-NATIVE-blueprints.md`](references/VIDEO-REACT-NATIVE-blueprints.md)
 - **Feeds setup/reference:** [`references/FEEDS-REACT-NATIVE.md`](references/FEEDS-REACT-NATIVE.md)
 - **Feeds screen/component blueprints:** [`references/FEEDS-REACT-NATIVE-blueprints.md`](references/FEEDS-REACT-NATIVE-blueprints.md)
+- **iOS simulator verification (fast run/screenshot loop):** [`references/SIMULATOR-VERIFICATION.md`](references/SIMULATOR-VERIFICATION.md)
 
 If the requested product file is not bundled yet, say so plainly and only switch to live docs if the user asks.
 
 ---
 
+## Docs-first triggers (consult docs before building)
+
+The bundled blueprints cover the **common scaffold path only** - root providers, auth gate, fresh-app scaffold, channel list, channel/message screen, threads (and the Video/Feeds equivalents). For anything that **customizes or extends** that path, the live `llms.txt`-selected page is the source of truth for the current API and recommended pattern. Fetch it **before** writing code.
+
+Docs-first applies when the request hits any of these:
+
+- **UI customization / theming / component overrides** - themes, design tokens, replacing a slot (message bubble, composer, call controls, participant tile, activity row), custom render props.
+- **Cookbook recipes** - typing indicators, message actions, reactions UI, attachment handling, mentions, search, link previews, etc.
+- **Advanced guides** - push notifications, offline support, PiP, ringing, screenshare, broadcasting, video filters, Chat+Video interop, notification/For-You feeds, polls, moderation.
+- **Migration / version upgrades.**
+- **Any exact API, prop, hook, or component detail** not already in the bundled blueprints.
+
+Mechanism (mirrors the `stream-react` skill):
+
+**match -> run the [`references/DOCS.md`](references/DOCS.md) manifest lookup -> `WebFetch` (or `curl -Ls`) the selected `.md` page -> implement to match.** On fetch failure, hand to the `stream-docs` skill; if neither resolves the API, **stop and ask the user - never build customization, cookbook, or advanced features from memory.**
+
+Enforced by [`RULES.md`](RULES.md) > Package version and docs discipline.
+
+---
+
+## Styling-depth flag: matching a provided design (Chat)
+
+Orthogonal to the track above: if a **Chat** request carries a **target appearance** - an attached
+screenshot, a Figma frame, or "make it look like WhatsApp / iMessage / Slack / \<app\>" - do not
+treat it as a set-a-few-colors task. **Before** writing UI code, run
+[`references/CHAT-REACT-NATIVE-design-matching.md`](references/CHAT-REACT-NATIVE-design-matching.md):
+it decomposes the reference region by region and plans **every** difference as one of three axes -
+**theming** (the `Theme` object), **layout** (`WithComponents` slot overrides + props), or
+**functional** (props / config / SDK hooks) - then verifies region-by-region against the reference.
+Implement every region, the composer included; a region left at the SDK default is a FAIL, not a
+"known cosmetic gap."
+
+This runs in addition to (not instead of) the `DOCS.md` lookup: fetch the manifest-selected
+theming/customization pages to confirm exact theme paths and component names. A plain Chat request
+with **no** target appearance does not trip this flag - build from the blueprints as usual.
+
+---
+
 ## Track A - New app
 
 **Full detail:** [`builder.md`](builder.md) - use the new-app path.

skills/stream-react-native/builder.md

@@ -377,6 +377,8 @@ How to add one:
 
 After adding native optional packages, follow their platform permission steps. For Expo, keep the app in the dev-client/native-build lane and run `npx expo prebuild` when native config changes need to be regenerated.
 
+**Batch capability packages before the first native build.** Each native capability package forces a prebuild + native rebuild (minutes). Decide the *complete* set the app needs up front and install them together **before** the first `expo run:ios` / `pod install`, so you build once — adding one later (e.g. discovering the composer mic needs `expo-audio` only after the app runs) costs a second full rebuild, the most common avoidable simulator time sink. See [references/SIMULATOR-VERIFICATION.md](references/SIMULATOR-VERIFICATION.md).
+
 ---
 
 ## 5. Configure native/runtime requirements
@@ -573,3 +575,11 @@ npx expo start
 ```
 
 Run only commands that exist in the project.
+
+**Running on the iOS simulator (Expo dev-client).** When you actually boot the app to screenshot and
+verify it (especially for a design match), follow the fast loop in
+[references/SIMULATOR-VERIFICATION.md](references/SIMULATOR-VERIFICATION.md): batch all capability
+packages before the first native build, start Metro **not** in CI mode (`npx expo start --dev-client
+--clear`) so edits aren't served stale, start Metro separately from `expo run:ios` (which exits and
+can take the bundler down), reach non-initial screens with temporary in-code navigation (`simctl`
+can't tap), and wait for the client to reconnect before trusting a screenshot.

skills/stream-react-native/credentials.md

@@ -113,7 +113,7 @@ getstream api UpdateUsers --request '{"users":{"<token_user_id>":{"id":"<token_u
 Use `GetOrCreateChannel`. Prefix every channel id with `<demo_prefix>` and tag the channel with a `seeded_by_skill: true` marker in `data.custom` so later runs can detect this skill's own seeded data:
 
 ```bash
-getstream api GetOrCreateChannel --type messaging --id <demo_prefix>general --request '{"data":{"name":"General (demo)","created_by_id":"<token_user_id>","members":[{"user_id":"<token_user_id>"},{"user_id":"<demo_prefix>alice"},{"user_id":"<demo_prefix>bob"}],"custom":{"seeded_by_skill":true,"demo_prefix":"<demo_prefix>"}}}'
+getstream api GetOrCreateChannel --type messaging --id <demo_prefix>general --request '{"data":{"created_by_id":"<token_user_id>","members":[{"user_id":"<token_user_id>"},{"user_id":"<demo_prefix>alice"},{"user_id":"<demo_prefix>bob"}],"custom":{"name":"General (demo)","seeded_by_skill":true,"demo_prefix":"<demo_prefix>"}}}
 ```
 
 Use namespaced channel ids such as `<demo_prefix>general`, `<demo_prefix>random`, `<demo_prefix>team-alpha`. Make sure the token user appears in `data.members`. `GetOrCreateChannel` is idempotent on the `(type, id)` pair - re-running with the same prefix returns the existing channel rather than duplicating it.
@@ -206,6 +206,20 @@ After C6 + C7, summarize without printing tokens:
 
 Do not run C4 through C7 when Feeds is not in scope, or when the user only asked for credentials. If only C4 + C5 ran (timeline-only demo, no Explore tab), `foryou` stays empty and that is fine - the Home tab still works.
 
+### Channel-type configuration - disable threads (optional) [Chat]
+
+<a id="disable-threads"></a>Some feature toggles live on the **channel type**, not on the client. Thread replies are one: whether the SDK surfaces a reply-in-thread affordance is governed by the `replies` setting on the `messaging` channel type (enabled by default). If a design has no threads (see the thread scope gate in [`references/CHAT-REACT-NATIVE-design-matching.md`](references/CHAT-REACT-NATIVE-design-matching.md)), turn them off at the source so the UI never offers a thread action the design lacks:
+
+```bash
+# Confirm the body shape first, then disable thread replies on the messaging type.
+getstream api UpdateChannelType -h
+getstream api UpdateChannelType --name messaging --request '{"replies":false}'
+```
+
+- This is a **mutating, app-wide** setting - it affects **every** channel of the `messaging` type, not just demo channels. Only run it on a fresh / scaffold app, or after the same non-empty-app confirmation gate as Step C0. Do not silently reconfigure a channel type in an app that already has real data.
+- Follow the CLI-safety rule (confirm the endpoint and body with `getstream api UpdateChannelType -h` before running; only mutate after the user confirms no threads).
+- Reversible and symmetric: re-enable with `--request '{"replies":true}'`.
+
 ### Step D - Proceed automatically
 
 After credentials and requested demo data succeed, return to [`SKILL.md`](SKILL.md) and continue into [`builder.md`](builder.md). No additional prompt is needed.

skills/stream-react-native/references/CHAT-REACT-NATIVE-blueprints.md

@@ -18,10 +18,13 @@ Expo lane: change imports from `"stream-chat-react-native"` to `"stream-chat-exp
 | thread navigation, replies, thread list | Thread Screen or Thread List Screen |
 | React Navigation or Expo Router shell | Navigation Shell |
 | theme, dark mode, colors, design tokens | Theming Blueprint |
+| screenshot / Figma / "match this design" / "make it look like \<app\>" | [CHAT-REACT-NATIVE-design-matching.md](CHAT-REACT-NATIVE-design-matching.md) first (decompose + plan every region), then Theming + Component Override Blueprints |
 | UI slot, component, behavior, or composer customization | DOCS.md -> primary manifest lookup, then Component Override Blueprint |
-| offline support or sign-out cleanup | Offline and Sign-out Blueprint |
+| cookbook / advanced feature (push, mentions, search, reactions UI, link previews, etc.) | DOCS.md -> primary manifest lookup, then implement to match |
+| offline support | Offline and Sign-out Blueprint |
+| sign-out cleanup | Offline and Sign-out Blueprint |
 
-If no row matches, read [DOCS.md](DOCS.md) and [CHAT-REACT-NATIVE.md](CHAT-REACT-NATIVE.md) first, then verify symbols in manifest-selected docs or the installed package before coding.
+If no row matches, run the [DOCS.md](DOCS.md) manifest lookup and `WebFetch` (or `curl -Ls`) the selected `.md` page before coding; also read [CHAT-REACT-NATIVE.md](CHAT-REACT-NATIVE.md) for setup/gotchas. Verify symbols in the manifest-selected docs or the installed package - never build customization or advanced features from memory.
 
 ---
 
@@ -408,6 +411,8 @@ Wiring:
 
 ---
 
+For custom header consult [DOCS.md](./DOCS.md)
+
 ## Thread Screen
 
 Use explicit thread state. The main channel should receive the active `thread` while the thread screen is open; the thread screen renders `Channel` with `threadList`.
@@ -571,7 +576,7 @@ Wiring:
 
 ## Component Override Blueprint
 
-Use `WithComponents` for custom subcomponents. Keep custom message rows memoized and use SDK context hooks.
+Always consult [DOCS.md](./DOCS.md) to find a relevant guide/cookbook, if there is no match, read SDK context and hooks to reuse business logic. Aim for using SDK provided hooks and contexts, only use low-level client if there are no hooks. Use `WithComponents` for custom subcomponents. Keep custom message rows memoized and use SDK context hooks.
 
 ```tsx
 import React, { memo } from "react";
@@ -606,6 +611,7 @@ Wiring:
 - Prefer the smallest documented override that satisfies the requested customization.
 - Avoid replacing core message components unless required.
 - If replacing message row structure and still using the long-press overlay, preserve overlay anchor behavior by reading the manifest-selected context docs.
+- Consult the theme object to adjust spacing as necessary
 
 ---