feat(react-native): port MCP subcomponent-resolution fix and doc tooling from hearth-react

Ports the hearth-react fix where a compound component's sub-component only
gets a resolvable MCP entry if it has its own Storybook story:

- Add dedicated `.stories.tsx` for 10 sub-components (ModalImage, Pill,
  CardPressHandler, TableHeader, TableHeaderCell, HighlightBannerImage,
  ProgressStep, TimelineItem, BannerImage, BannerIllustration)
- Wire up storybook-addon-oversight/oversight-lint and a path-filtered CI
  workflow, mirroring packages/react's setup
- Document every component's own props and add component-level JSDoc
  descriptions across the package, clearing all oversight findings
- Default packages/react-native/SKILL.md to the MCP server over local
  markdown, matching packages/react's SKILL.md
- Update react-native-component-addition/react-native-component-docs
  skills to require sub-component stories going forward

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: robphoenix

.changeset/react-native-oversight-jsdoc.md

@@ -0,0 +1,13 @@
+---
+'@utilitywarehouse/hearth-react-native': patch
+---
+
+🧹 [HOUSEKEEPING]: Add Storybook Oversight lint and document missing component/prop JSDoc
+
+Adds `storybook-addon-oversight` / `oversight-lint` to this package, mirroring the setup already in place for `hearth-react`, plus a `react-native-storybook-oversight` CI workflow that lints the Storybook manifest on every PR touching `packages/react-native`. This catches components or props with no JSDoc description before they reach the `hearth-react-native` MCP server, where an undocumented prop is invisible to AI coding agents.
+
+Running this lint for the first time surfaced JSDoc gaps across almost every component in the package (unlike `hearth-react`, which already had partial coverage). Component-level descriptions and each component's own props have been documented across the library. Props inherited from React Native's own `ViewProps`/`PressableProps`/`TextProps` (e.g. `onTouchStart`, `onPointerEnter`, `style`, `ref`) are excluded from the `prop-descriptions-missing` rule via `oversight.config.json`, since documenting them would mean duplicating the same JSDoc across dozens of unrelated components.
+
+**Developer changes**:
+
+No action required — this only adds documentation and CI tooling, not runtime behaviour.

.changeset/react-native-subcomponent-mcp-props.md

@@ -0,0 +1,22 @@
+---
+'@utilitywarehouse/hearth-react-native': patch
+---
+
+💅 [ENHANCEMENT]: Subcomponents now have their own Storybook entries, so the `hearth-react-native` MCP server can resolve their props
+
+`ModalImage`, `Pill`, `CardPressHandler`, `TableHeader`, `TableHeaderCell`, `HighlightBannerImage`, `ProgressStep`, `TimelineItem`, `BannerImage`, and `BannerIllustration` each now have their own Storybook story. Previously these subcomponents only appeared nested inside their parent's docs page, so the `hearth-react-native` MCP server (used by AI coding agents) couldn't resolve their props — it could only resolve props for a component with its own Storybook entry. `packages/react-native/SKILL.md` has been updated to default to the MCP server for component lookups, reflecting this.
+
+**Components affected**:
+
+- `Modal` (`ModalImage`)
+- `PillGroup` (`Pill`)
+- `Card` (`CardPressHandler`)
+- `Table` (`TableHeader`, `TableHeaderCell`)
+- `HighlightBanner` (`HighlightBannerImage`)
+- `ProgressStepper` (`ProgressStep`)
+- `Timeline` (`TimelineItem`)
+- `Banner` (`BannerImage`, `BannerIllustration`)
+
+**Developer changes**:
+
+No action required — this only affects Storybook navigation and the guidance given to AI coding agents using this library, not the runtime API.

.claude/skills/react-native-component-addition/SKILL.md

@@ -27,10 +27,30 @@ packages/react-native/src/components/<Component>/
   <Component>.docs.mdx
   <Component>.figma.tsx
   index.ts
+  <SubComponent>.tsx        # Sub-components (compound patterns)
+  <SubComponent>.stories.tsx  # Required — see "Sub-component stories" below
 ```
 
 Add additional files as needed (subcomponents, helpers, platform-specific variants).
 
+### Sub-component stories
+
+Every exported sub-component needs its **own** `<SubComponent>.stories.tsx` with its
+own `Meta` (`title: 'Stories / <SubComponent>'`, `component: <SubComponent>`) — even
+though it's already documented via a nested `### <SubComponent> Props` table in the
+parent's `.docs.mdx` (see the [react-native-component-docs](./../react-native-component-docs/SKILL.md)
+skill). The `hearth-react-native` MCP server only lists a component as its own
+resolvable entry in `list-all-documentation` when it has its own Storybook story — a
+sub-component documented only inside its parent's `.docs.mdx` doesn't get one. No
+separate `<SubComponent>.docs.mdx` is needed — mirror
+`src/components/Card/CardAction/CardAction.stories.tsx`: a `Meta` + at least one
+story, wrapped in whatever ancestor context the sub-component needs to render
+meaningfully.
+
+Note: `packages/react-native` has no `react-audit`-equivalent skill to catch this
+gap automatically (unlike `packages/react`) — treat this checklist item as the only
+guard against it regressing until one exists.
+
 ## Implementation Steps
 1. **Props**: Define public props in <Component>.props.ts. Keep types explicit and add JSDoc defaults.
 2. **Component**: Implement <Component>.tsx using tokens from theme (useTheme or StyleSheet variants).
@@ -49,6 +69,8 @@ Add storybook story tests for interaction behviour tests where necessary too.
 - Token usage aligns with components tokens (theme.components.<component>)
 - Stories include a Playground story and at least one variant example
 - Docs include Playground, Usage, Props table, and Figma links when available
+- Every sub-component (compound pattern) has its own `<SubComponent>.stories.tsx` — see [Sub-component stories](#sub-component-stories); required for the MCP server, not optional
+- Run `pnpm build:storybook && npx oversight --max-warnings 0 --expected-extractor react-docgen-typescript` (from `packages/react-native`) and fix any findings — confirms the MCP can actually resolve the new component's description and props, not just that JSDoc was added by eye
 - All Components list updated
 
 ## Notes

.claude/skills/react-native-component-docs/SKILL.md

@@ -68,7 +68,7 @@ Make sure to include code blocks for each example. This is likely needed for mos
 1. **Read the component's source of truth:** Open `<Component>.props.ts` and cross-check every prop against your drafted Props table. Include all public props with correct types and defaults. For compound components, verify each subcomponent's `.props.ts` file and include a nested props table under the subcomponent's heading.
 2. **Treat mismatches as blocking:** If a prop appears in `.props.ts` but not in your table (or vice versa), stop and fix it. This is not a nice-to-have — it's the ground truth check.
 3. **Match story names exactly:** Verify that `Stories.Playground` and any other story references exist in the component's `.stories.tsx` file.
-4. **Check compound-component structure:** If the component has subcomponents (e.g. `BadgeIcon`, `AccordionItem`), ensure each has its own `### Heading` with a `#### Props` table.
+4. **Check compound-component structure:** If the component has subcomponents (e.g. `BadgeIcon`, `AccordionItem`), ensure each has its own `### Heading` with a `#### Props` table. This nested table is **not** a substitute for the subcomponent's own `<SubComponent>.stories.tsx` — the `hearth-react-native` MCP server only resolves a component's real props when that component has its own Storybook entry. See [Sub-component stories](../react-native-component-addition/SKILL.md#sub-component-stories) in the `react-native-component-addition` skill.
 
 ## Checklist
 
@@ -77,6 +77,6 @@ Make sure to include code blocks for each example. This is likely needed for mos
 - `Playground` and `Controls` reference a real story
 - `Usage` section has both a live example and a code block
 - Props table verified against `.props.ts` (including subcomponents)
-- Compound component sub-props documented if applicable
+- Compound component sub-props documented if applicable, AND each subcomponent has its own `<SubComponent>.stories.tsx` (required for MCP resolution, not optional — see `react-native-component-addition`)
 - Optional sections are only added when helpful
 - Order of sections should be in the standard pattern (Playground, Usage, Props, then optional sections)

.github/workflows/react-native-storybook-oversight.yml

@@ -0,0 +1,38 @@
+name: React Native Storybook Oversight
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - 'packages/react-native/**'
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Storybook Oversight Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        with:
+          version: 11.8.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_GLOBAL_READ_TOKEN }}
+      - run: pnpm build:storybook:react-native
+        env:
+          NODE_OPTIONS: '--max_old_space_size=4096'
+      - uses: rachelslurs/oversight-lint-action@v1
+        working-directory: ./packages/react-native

packages/react-native/.storybook/main.ts

@@ -33,6 +33,7 @@ const config = {
     getAbsolutePath('@storybook/addon-a11y'),
     getAbsolutePath('@storybook/addon-vitest'),
     getAbsolutePath('@storybook/addon-mcp'),
+    getAbsolutePath('storybook-addon-oversight'),
   ],
   framework: {
     name: getAbsolutePath('@storybook/react-native-web-vite'),

packages/react-native/.storybook/manager.ts

@@ -8,4 +8,10 @@ const theme = create(config);
 
 addons.setConfig({
   theme,
+  'storybook-addon-oversight': {
+    expectedExtractor: 'react-component-meta',
+    rules: {
+      'prop-descriptions-missing': 'off',
+    },
+  },
 });

packages/react-native/SKILL.md

@@ -48,14 +48,22 @@ There are 2 options for discovering existing components and documentation:
 - MCP server: `hearth-react-native` MCP hosted on a remote URL
 - Raw markdown files: located in the `public` folder of the `hearth-react-native` package
 
-**Default to the raw markdown files.** They are local, always available, and
-version-matched to what the app actually has installed — so the API you read is
-the API you get.
-
-**Use the MCP server for richer exploration** — searching across components,
-fetching story code, or discovering what exists when you're not sure where to
-start. It's worth reaching for when the markdown files don't give you enough
-context, but it requires the server to be configured and reachable.
+**Default to the MCP server** for component lookups and general/cross-cutting
+guidance (design tokens, styling, layout, getting started, dark mode). For a
+component, fetch both its plain `stories-<component>` entry (props + story
+code) and its `components-<component>--docs` entry (narrative usage,
+accessibility, and examples) — together they cover what the local markdown
+file documents.
+
+Subcomponents (e.g. `ModalImage`, `CardAction`) are listed as their own
+`stories-<subcomponent>` entries in `list-all-documentation` — fetch them
+directly by their own id rather than relying on the parent's `--docs` page.
+They don't have a separate `--docs` entry of their own; their narrative usage
+stays documented inline in the parent's `components-<parent>--docs` entry.
+
+**Fall back to the raw markdown files** for a specific story's exact code
+beyond what's already surfaced by `get-documentation` or
+`get-documentation-for-story`.
 
 Whatever source you use, review what is available before writing any code.
 
@@ -68,6 +76,17 @@ prop the library added later (e.g. `List`'s own `heading`/`helperText` props
 vs. a sibling `SectionHeader` or `Heading`). Prefer the documented, current shorthand over
 an older local convention when they diverge.
 
+### MCP Server
+
+You can use the **`hearth-react-native`** MCP server if available (`https://main--68e3ad5c6e80b57678cad6c6.chromatic.com/mcp`):
+
+1. `list-all-documentation` — get an index of all Hearth React Native components and docs
+2. `get-documentation` — get props, API, and usage examples for a specific
+   component or docs entry. Pass the plain `stories-<component>` id (e.g.
+   `stories-modal`) for props and story code, or the `components-<component>--docs`
+   id (e.g. `components-modal--docs`) for narrative usage and accessibility docs
+3. `get-documentation-for-story` — get story code and docs for a specific story
+
 ### Raw markdown files
 
 Full component API reference is available in the installed package. First,
@@ -82,14 +101,6 @@ The docs are then at:
 - `<hearth-react-native-root>/public/llms/docs/` — design tokens, styling, layout, hooks, dark mode
 - `<hearth-react-native-root>/public/llms.txt` — index of all available docs
 
-### MCP Server
-
-You can use the **`hearth-react-native`** MCP server if available (`https://main--68e3ad5c6e80b57678cad6c6.chromatic.com/mcp`):
-
-1. `list-all-documentation` — get an index of all Hearth React Native components
-2. `get-documentation` — get props, API, and usage examples for a specific component
-3. `get-documentation-for-story` — get story code and docs for a specific story
-
 ## Plan before writing
 
 For anything beyond a trivial change — a new screen, a multi-component feature, an

packages/react-native/oversight.config.json

@@ -0,0 +1,8 @@
+{
+  "manifest": "storybook-static/manifests/components.json",
+  "expectedExtractor": "react-component-meta",
+  "maxWarnings": 0,
+  "rules": {
+    "prop-descriptions-missing": "off"
+  }
+}

packages/react-native/package.json

@@ -43,7 +43,8 @@
     "dev": "storybook dev -p 6006",
     "dev:docs": "storybook dev -p 6002 --no-open",
     "build:storybook": "storybook build",
-    "build:storybook:docs": "storybook build --docs"
+    "build:storybook:docs": "storybook build --docs",
+    "lint:oversight": "oversight"
   },
   "dependencies": {
     "@gluestack-ui/accordion": "1.0.14",
@@ -85,6 +86,7 @@
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
     "globals": "^15.15.0",
+    "oversight-lint": "^0.7.0",
     "playwright": "^1.59.1",
     "prismjs": "^1.30.0",
     "react": "19.2.3",
@@ -101,6 +103,7 @@
     "react-native-worklets": "0.10.1",
     "remark-gfm": "^4.0.1",
     "storybook": "^10.5.6",
+    "storybook-addon-oversight": "^0.7.0",
     "vite": "^7.1.3",
     "vite-plugin-svgr": "^4.5.0",
     "vitest": "^4.1.7"