bmad-module-skill-forge 0.7.3 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/agents/forger.agent.yaml

@@ -8,7 +8,7 @@ agent:
     module: skf
     hasSidecar: true
     sidecar-folder: forger-sidecar
-    sidecar-path: "{project-root}/_bmad/_memory/forger-sidecar/"
+    sidecar-path: "{project-root}/_bmad/_memory/forger-sidecar"
 
   persona:
     role: |

package/src/knowledge/ccc-bridge.md

@@ -33,7 +33,7 @@ When either condition is false, calling steps skip ccc discovery silently and pr
 
 ### `ccc_bridge.search(query, path?, top_k?)`
 
-**Resolves to:** `ccc search "{query}" --path {path} --top {top_k}` (CLI) or the `ccc` MCP search tool (preferred)
+**Resolves to:** `cd {path} && ccc search --limit {top_k} "{query}"` (CLI) or the `ccc` MCP search tool (preferred). Note: `ccc search` operates on the index in the current working directory — there is no flag to specify a project directory. The `--path` flag is a file path glob filter within the index, not a project selector.
 
 Returns: list of `{file, score, snippet}` entries ranked by semantic relevance to the query. These are **candidates** for ast-grep extraction — not verified exports.
 
@@ -41,7 +41,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 
 ### `ccc_bridge.ensure_index(path)`
 
-**Resolves to:** Check `ccc_index.status` in forge-tier.yaml. If `"none"` or the indexed_path does not match, run `ccc init {path}` then `ccc index` and update forge-tier.yaml.
+**Resolves to:** Check `ccc_index.status` in forge-tier.yaml. If `"none"` or the indexed_path does not match, run `cd {path} && ccc init` then `ccc index` and update forge-tier.yaml. Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory.
 
 **Usage context:** Called by setup-forge step-01b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
 
@@ -77,6 +77,36 @@ The ccc search is invisible in the output artifact. A Forge+ skill's citations a
 - A stale index still produces useful results — the workflow proceeds with the stale index and notes the staleness
 - setup-forge is the designated refresh authority
 
+### Exclusion Patterns
+
+CCC stores its configuration at `{project-root}/.cocoindex_code/settings.yml`. This file contains `exclude_patterns` and `include_patterns` arrays in glob format. `ccc init` creates the file with sensible defaults (excludes `node_modules`, `__pycache__`, hidden dirs, etc.).
+
+**SKF infrastructure exclusions:** setup-forge step-01b appends SKF-specific exclusion patterns after `ccc init` creates the default config. These patterns prevent indexing of framework and output directories that have zero value for source extraction:
+
+| Pattern | Purpose |
+|---------|---------|
+| `**/_bmad` | SKF framework module (workflow instructions, agents, knowledge) |
+| `**/_bmad-output` | Build output artifacts (TODO files, reports) |
+| `**/.claude` | Claude Code configuration |
+| `**/_skf-learn` | SKF learning materials |
+| `**/{skills_output_folder}` | Generated skill files (from manifest, default: `skills`) |
+| `**/{forge_data_folder}` | Compilation workspace (from manifest, default: `forge-data`) |
+
+The `skills_output_folder` and `forge_data_folder` values are read from `_bmad/_config/skf-manifest.yaml` when available, falling back to the defaults `skills` and `forge-data`. Patterns are appended only if not already present — user customizations to `settings.yml` are preserved.
+
+The configured exclusion patterns are stored in `ccc_index.exclude_patterns` in forge-tier.yaml for reference.
+
+### Deferred Discovery (Remote Sources)
+
+For remote repository sources (GitHub URLs), CCC cannot operate during step-02b because no local code exists yet. The ephemeral clone happens in step-03. To provide CCC pre-ranking for remote sources:
+
+1. **step-02b:** Detects remote source, sets `{ccc_discovery: []}`, displays deferred message
+2. **step-03:** After ephemeral clone succeeds, detects the deferred scenario (`tools.ccc == true AND {ccc_discovery} is empty AND ephemeral_clone_active == true AND tier is Forge+/Deep`)
+3. **step-03:** Runs `cd {temp_path} && ccc init` + `ccc index` on the ephemeral clone (extended timeout or background mode, verified via `ccc status`)
+4. **step-03:** Executes CCC search and populates `{ccc_discovery}` before AST extraction begins
+
+The ephemeral clone index is not registered in `ccc_index_registry` — the clone is deleted after extraction and the CCC daemon's own GC handles orphaned indexes.
+
 ### Relationship to QMD Registry
 
 ccc_index and qmd_collections are **orthogonal**:
@@ -100,6 +130,8 @@ To prevent excessive daemon calls, workflow steps cap ccc queries:
 - Running ccc_bridge.ensure_index() without checking ccc_index.status first — unnecessary re-indexing
 - Passing ccc results directly to the extraction inventory — they are candidates, not extractions
 - Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
+- Indexing without configuring SKF exclusions — framework and output directories pollute search results
+- Skipping CCC discovery for remote sources without deferring to step-03 — remote repos deserve the same pre-ranking as local sources
 
 ## Related Fragments
 

package/src/knowledge/tool-resolution.md

@@ -7,9 +7,9 @@ Bridge names (`ast_bridge`, `ccc_bridge`, `qmd_bridge`, `gh_bridge`) and subproc
 | Bridge       | Operation                        | Claude Code                                                      | Cursor         | CLI                                                | Fallback                         |
 |--------------|----------------------------------|------------------------------------------------------------------|----------------|----------------------------------------------------|----------------------------------|
 | `ast_bridge` | `scan_definitions()`             | `mcp__ast-grep__find_code` or `mcp__ast-grep__find_code_by_rule` | ast-grep MCP   | `sg run` / `ast-grep -p`                           | Source reading (T1-low)          |
-| `ast_bridge` | `detect_co_imports()`            | `mcp__ast-grep__find_code_by_rule` with co-import YAML rule      | ast-grep MCP   | `ast-grep -p 'import $$$' --json=stream`           | grep-based co-import count       |
-| `ccc_bridge` | `search(query, root, top_k)`     | `/ccc` skill search                                              | ccc MCP server | `ccc search "{query}" --path {root} --top {top_k}` | Skip silently                    |
-| `ccc_bridge` | `ensure_index(root)`             | `/ccc` skill indexing                                            | ccc MCP server | `ccc init` + `ccc index {root}`                    | Skip silently                    |
+| `ast_bridge` | `detect_co_imports()`            | `mcp__ast-grep__find_code_by_rule` with co-import YAML rule      | ast-grep MCP   | `ast-grep run -p 'import $$$' --json=stream`       | grep-based co-import count       |
+| `ccc_bridge` | `search(query, root, top_k)`     | `/ccc` skill search                                              | ccc MCP server | `cd {root} && ccc search --limit {top_k} "{query}"` | Skip silently                    |
+| `ccc_bridge` | `ensure_index(root)`             | `/ccc` skill indexing                                            | ccc MCP server | `cd {root} && ccc init` + `ccc index`               | Skip silently                    |
 | `ccc_bridge` | `status()`                       | `/ccc` skill status                                              | ccc MCP server | `ccc --help` + `ccc doctor`                        | Unavailable = `tools.ccc: false` |
 | `qmd_bridge` | `search(query)`                  | `mcp__plugin_qmd-plugin_qmd__search`                             | qmd MCP server | `qmd search "{query}"`                             | Skip enrichment                  |
 | `qmd_bridge` | `vector_search(query)`           | `mcp__plugin_qmd-plugin_qmd__vector_search`                      | qmd MCP server | `qmd vector_search "{query}"`                      | Use BM25 search only             |

package/src/module.yaml

@@ -15,11 +15,13 @@ forge_data_folder:
   default: "forge-data"
   result: "{project-root}/{value}"
 
+sidecar_path:
+  prompt: false
+  default: "_bmad/_memory/forger-sidecar"
+  result: "{project-root}/{value}"
+
 # Variables from Core Config inserted:
 ## user_name
 ## communication_language
 ## document_output_language
 ## output_folder
-
-# Variables from Agent Sidecar Config:
-## sidecar_path  (from forger.agent.yaml metadata.sidecar-path)

package/src/workflows/analyze-source/data/skill-brief-schema.md

@@ -55,12 +55,20 @@ The create-skill workflow (step-03-extract) also performs version reconciliation
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api | docs-only
+  type: full-library | specific-modules | public-api | component-library | docs-only
   include:
     - 'src/**/*.ts'          # At least one required
   exclude:
     - 'src/**/*.test.ts'     # Optional
   notes: 'Optional rationale for scope decision'
+  # Additional fields when scope.type is "component-library":
+  # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
+  # ui_variants:                           # Optional — design system variants
+  #   - name: "shadcnui"
+  #     package: "packages/components/react-shadcn"
+  # demo_patterns:                         # Optional — auto-detected if omitted
+  #   - "**/demo/**"
+  #   - "**/*.stories.*"
 ```
 
 ### Scope Types
@@ -70,6 +78,7 @@ scope:
 | full-library | Entire codebase of a unit |
 | specific-modules | Selected components or packages |
 | public-api | Only exported interfaces |
+| component-library | UI component libraries with registries, props-based APIs, and design system variants |
 | docs-only | When source_type is docs-only — no source code available, all content from doc_urls |
 
 ## YAML Template
@@ -98,7 +107,7 @@ created_by: '{user_name}'
 1. **Name uniqueness**: No duplicate names within forge_data_folder
 2. **Source accessibility**: source_repo path must exist or be reachable
 3. **Language recognized**: Must be a known programming language
-4. **Scope type valid**: Must match one of the four defined types (full-library, specific-modules, public-api, docs-only)
+4. **Scope type valid**: Must match one of the five defined types (full-library, specific-modules, public-api, component-library, docs-only)
 5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
 6. **Forge tier match**: Must match value in forge-tier.yaml
 7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional

package/src/workflows/analyze-source/data/unit-detection-heuristics.md

@@ -59,6 +59,15 @@ Rules for identifying discrete skillable units within a project. A "skillable un
 - Custom wrappers, configurations, or integration code
 - Scope type: `public-api`
 
+### Component Library Boundary
+- Contains a component registry or catalog file (array of component definitions with IDs, names, categories)
+- Has `components/`, `packages/components/`, or similar multi-component directory structure
+- Multiple design system variant directories (e.g., `react-shadcn/`, `react-baseui/`, `react-carbon/`)
+- Significant demo/story/example file ratio (>30% of total files)
+- CLI-based installation pattern (e.g., `npx <tool> add <component-id>`)
+- Props interfaces outnumber function signatures as primary API surface
+- Scope type: `component-library`
+
 ## Disqualification Rules
 
 Do NOT recommend as a skillable unit if:

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -90,7 +90,7 @@ For EACH qualifying unit, prepare a recommendation card:
 
 **Proposed Brief Fields:**
 - name: {suggested kebab-case name}
-- scope.type: {full-library / specific-modules / public-api}
+- scope.type: {full-library / specific-modules / public-api / component-library}
 - scope.include: {suggested glob patterns}
 - description: {suggested 1-3 sentence description}
 ```

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -97,7 +97,7 @@ For each generated brief, check against {schemaFile} validation rules:
 1. **Name uniqueness** — no duplicate names within the batch or existing skills
 2. **Source accessible** — project_path exists
 3. **Language recognized** — valid programming language identifier
-4. **Scope type valid** — matches `full-library`, `specific-modules`, or `public-api`
+4. **Scope type valid** — matches `full-library`, `specific-modules`, `public-api`, or `component-library`
 5. **Include patterns** — at least one glob pattern present
 6. **Forge tier match** — matches forge_tier from config
 
@@ -152,6 +152,7 @@ For each generated brief, recommend the appropriate next workflow:
 | Condition | Recommendation |
 |-----------|---------------|
 | Brief has `scope.type: full-library` and unit is well-bounded | create-skill — brief is sufficient for direct skill creation |
+| Brief has `scope.type: component-library` and registry defines boundaries | create-skill — component boundaries defined by registry |
 | Brief has `scope.type: specific-modules` or scope needs refinement | brief-skill — refine scope before creating skill |
 | Brief has `scope.type: public-api` or complex interface | brief-skill — detailed scoping needed |
 | Unit flagged as stack skill candidate | create-stack-skill — after individual skills exist |

package/src/workflows/brief-skill/data/scope-templates.md

@@ -16,6 +16,12 @@ Present these options to the user for selection:
 - Entry points and exported interfaces only
 - Internal implementation excluded
 
+**[C] Component Library** — Optimized for UI component libraries with registries, props-based APIs, and design system variants.
+- Component registry as primary API surface (not individual exports)
+- Props interfaces as API contracts (not function signatures)
+- Auto-exclude demo/example/story files (with user confirmation)
+- Variant consolidation across design systems
+
 ## Boundary Definitions by Scope Type
 
 ### Full Library Boundaries
@@ -69,6 +75,41 @@ Prompt: "Any additional items you'd like to include or exclude?"
 
 Prompt: "Any additional documentation URLs to include? Or URLs to exclude from the ones collected?"
 
+### Component Library Boundaries
+
+**Phase 1 — Registry Detection:**
+
+Auto-detect or accept explicit `registry_path` from user. Scan source tree for files matching common registry patterns:
+- Files named `registry.ts`, `components.ts`, `index.ts` in `registry/`, `catalog/`, or `components/` directories
+- Arrays of objects with `{ id, name, component }` structure and 10+ entries
+- Files with `Component[]` type annotations
+
+Present detected registry candidate(s) to user for confirmation.
+Prompt: "I found what looks like a component registry at {path} ({count} entries). Is this correct? Or provide the registry path:"
+
+**Phase 2 — Demo/Example Exclusion:**
+
+Auto-detect demo directories and file patterns:
+- Directories: `demo/`, `demos/`, `stories/`, `examples/`, `__stories__/`, `storybook/`
+- Files: `*.stories.*`, `*.story.*`, `*.example.*`, `*.demo.*`
+
+Present detected patterns to user before applying (do NOT exclude silently).
+Prompt: "**Auto-detected {N} demo/example files** in {M} directories. Confirm exclusion? [Y/n] Or adjust patterns:"
+
+**Phase 3 — Variant Selection (if applicable):**
+
+If multiple design system variant directories detected (e.g., `react-shadcn/`, `react-baseui/`, `react-carbon/`):
+- Present detected variants with component counts per variant
+- User selects primary variant and which variants to include
+- Record as `ui_variants` in brief
+
+Prompt: "I detected {count} design system variants: {list with counts}. Which is the primary variant? Include all? [Y/n]"
+
+**Phase 4 — Scope Confirmation:**
+
+Summary showing: component count, excluded demo count, variant summary, include/exclude patterns.
+Prompt: "Does this component library scope look right? Adjust before continuing."
+
 ## Scripts & Assets Detection (Optional Refinement)
 
 When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

package/src/workflows/brief-skill/data/skill-brief-schema.md

@@ -51,13 +51,21 @@ The create-skill workflow (step-03-extract) also performs version reconciliation
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api | docs-only
+  type: full-library | specific-modules | public-api | component-library | docs-only
   include:
     - "src/**/*.ts"           # Glob patterns for included files/directories
   exclude:
     - "**/*.test.*"           # Glob patterns for excluded files
     - "**/node_modules/**"
   notes: "Optional notes about scope decisions"
+  # Additional fields when scope.type is "component-library":
+  # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
+  # ui_variants:                           # Optional — design system variants
+  #   - name: "shadcnui"
+  #     package: "packages/components/react-shadcn"
+  # demo_patterns:                         # Optional — auto-detected if omitted
+  #   - "**/demo/**"
+  #   - "**/*.stories.*"
 ```
 
 ## YAML Template
@@ -74,7 +82,7 @@ forge_tier: "{Quick|Forge|Forge+|Deep}"
 created: "{date}"
 created_by: "{user_name}"
 scope:
-  type: "{full-library|specific-modules|public-api|docs-only}"
+  type: "{full-library|specific-modules|public-api|component-library|docs-only}"
   include:
     - "{pattern}"
   exclude:
@@ -133,7 +141,7 @@ Created by: {created_by}
 1. `name` must be unique within {forge_data_folder}
 2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
 3. `language` must be a recognized programming language
-4. `scope.type` must be one of the four defined types
+4. `scope.type` must be one of the five defined types
 5. `scope.include` must have at least one pattern (exception: `docs-only` scope, where include patterns are optional since no source code is available)
 6. `forge_tier` must be one of: Quick, Forge, Forge+, Deep (Title Case, must match the tier from forge-tier.yaml, or default to Quick)
 7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional

package/src/workflows/brief-skill/steps-c/step-02-analyze-target.md

@@ -139,7 +139,7 @@ Based on detected language, identify public API surface:
 
 **Semantic Signals (Forge+ and Deep with ccc only):**
 
-**Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC will be available during create-skill if the source is cloned locally."
+**Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC discovery will run automatically during create-skill after the source is cloned."
 
 If `tools.ccc` is true in forge-tier.yaml, supplement the module listing with a semantic discovery pass:
 

package/src/workflows/brief-skill/steps-c/step-03-scope-definition.md

@@ -106,9 +106,9 @@ Wait for confirmation. Record any changes to `doc_urls`.
 
 ### 2c. Offer Scope Templates
 
-Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P]) and their descriptions.
+Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P], [C]) and their descriptions.
 
-Present: "**How broadly should this skill cover the library?**" followed by the three scope type options from the loaded reference.
+Present: "**How broadly should this skill cover the library?**" followed by the scope type options from the loaded reference.
 
 Ask: "Which scope type fits your needs?"
 
@@ -116,7 +116,7 @@ Wait for user selection.
 
 ### 3. Define Boundaries Based on Selection
 
-Using the boundary definitions from `{scopeTemplatesFile}`, present the appropriate flow for the user's selected scope type ([F], [M], or [P]). Follow each type's prompts and wait for user input at each phase before proceeding.
+Using the boundary definitions from `{scopeTemplatesFile}`, present the appropriate flow for the user's selected scope type ([F], [M], [P], or [C]). Follow each type's prompts and wait for user input at each phase before proceeding.
 
 ### 4. Handle Language Override
 
@@ -132,7 +132,7 @@ Wait for confirmation or override.
 
 "**Scope Summary:**
 
-**Type:** {Full Library / Specific Modules / Public API}
+**Type:** {Full Library / Specific Modules / Public API / Component Library}
 
 **Include:**
 {bulleted list of include patterns}
@@ -151,7 +151,7 @@ Wait for confirmation. Make adjustments if requested.
 
 ### 5b. Scripts & Assets Intent (Optional)
 
-**Only ask when `scope.type` is `full-library` or `specific-modules` (skip for `public-api` and `docs-only`).**
+**Only ask when `scope.type` is `full-library`, `specific-modules`, or `component-library` (skip for `public-api` and `docs-only`).**
 
 "Does this library include executable scripts (CLI tools, validation scripts, setup helpers) or static assets (config templates, JSON schemas, example configs) that should be packaged with the skill?"
 
@@ -189,7 +189,7 @@ ONLY WHEN C is selected and scope boundaries are confirmed will you load and rea
 
 ### ✅ SUCCESS:
 
-- Scope type selected by user (Full Library, Specific Modules, or Public API)
+- Scope type selected by user (Full Library, Specific Modules, Public API, or Component Library)
 - Include patterns defined and confirmed
 - Exclude patterns defined and confirmed
 - Language confirmed (or overridden if detection was low confidence)

package/src/workflows/create-skill/data/compile-assembly-rules.md

@@ -108,6 +108,114 @@ Assemble Sections 9-11 (Full API Reference, Full Type Definitions, Full Integrat
 
 Do NOT repeat Tier 1's name/purpose/key-params table format in Tier 2. Tier 2 is a deep reference, not a reformatted summary. This distinction prevents conciseness scorers from flagging the two-tier design as redundancy.
 
+### Component Library Assembly Overrides
+
+When `scope.type: "component-library"` in the brief AND `component_catalog[]` is available in context, apply these overrides to the standard assembly. All other sections remain unchanged.
+
+**Section 2 (Quick Start) — CLI-first override:**
+
+Replace the standard function-based Quick Start with CLI installation:
+
+```markdown
+## Quick Start
+
+Install a component:
+`npx {cli-name} add {top-component-id}`
+
+{If provider wrapping detected in source:}
+Set up providers:
+\`\`\`tsx
+import { ThemeProvider, UILibraryProvider } from "{primary-package}";
+
+<ThemeProvider>
+  <UILibraryProvider>
+    <YourApp />
+  </UILibraryProvider>
+</ThemeProvider>
+\`\`\`
+```
+
+Detect CLI name from: `package.json` `bin` field, README usage examples, or `registry_path` context. If no CLI detected, fall back to standard import-based Quick Start.
+
+**Section 4 (Key API Summary) — Component Catalog override:**
+
+Replace the function table with a Component Catalog organized by category:
+
+```markdown
+## Component Catalog
+
+| Category | Count | Key Components |
+|----------|-------|---------------|
+| {category} | {count} | {top 3-5 component names, comma-separated} |
+
+**Design system variants:** {variant list with primary marked}
+**Total components:** {unique count} | {Per variant: **With {name}:** {count}}
+```
+
+Source: `component_catalog[]` from step-03d. Group by `category` field. Provenance: cite the registry file.
+
+**Section 5 (Key Types) — Props-focused override:**
+
+Replace generic types with the top 5 most-used Props interfaces (by component count or prominence):
+
+```markdown
+## Key Types
+
+### {ComponentName}Props
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| {prop} | {type} | {default or —} | {yes/no} |
+```
+
+Show only the 5 most important Props interfaces inline. Full Props details go in Tier 2.
+
+**Tier 2 (Full API Reference) — Props Reference override:**
+
+Organize by component (not by function). Per component:
+
+```markdown
+### {ComponentName}
+
+**Install:** `npx {cli} add {component-id}`
+**Available in:** {variant list}
+**Props:** `{ComponentName}Props`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| {prop} | {type} | {default} | {JSDoc description or —} |
+```
+
+**context-snippet.md — Component Library format:**
+
+```markdown
+[{name} v{version}]|root: skills/{name}/
+|IMPORTANT: {name} v{version} — read SKILL.md before writing {name} code. Do NOT rely on training data.
+|install: npx {cli} add <component-id>
+|catalog:{SKILL.md#component-catalog} — {N} components: {category(count), ...}
+|variants: {variant list} — {provider wrapping note if applicable}
+|key-props:{SKILL.md#key-types} — {top props interfaces with key fields}
+|gotchas: {detected gotchas}
+```
+
+**metadata.json — Component Library stats:**
+
+When `scope.type: "component-library"`, add these fields to `stats`:
+
+```json
+{
+  "stats": {
+    "components_registered": 0,
+    "components_documented": 0,
+    "props_interfaces_extracted": 0,
+    "components_unique": 0,
+    "demo_files_excluded": 0,
+    "design_variants": {}
+  }
+}
+```
+
+These are in addition to the standard stats fields (exports_documented, etc.).
+
 ### Assembly Rules
 
 1. Assemble all Tier 1 sections first — these form the essential standalone body

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -130,7 +130,7 @@ Files in scope 101–500
   → Parse compact text output into extraction inventory
 
 Files in scope > 500
-  → CLI streaming fallback: ast-grep --json=stream + line-by-line Python processing
+  → CLI streaming fallback: ast-grep run --json=stream + line-by-line Python processing
   → Process in directory batches, cap per-batch output
   → Merge batch results into extraction inventory
 ```
@@ -171,6 +171,7 @@ When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--js
 **Head cap selection:** The `| head -N` cap at the end of the pipeline controls how many exports are captured. Select `N` based on scope and tier:
 - **Default (Quick/Forge, any scope):** `N = 200`
 - **Forge+/Deep with `scope.type: "full-library"`:** `N = 500`
+- **Forge+/Deep with `scope.type: "component-library"`:** `N = 300` (components have fewer but richer exports; props interfaces are the primary API surface)
 
 For full-library skills at higher tiers, the larger cap prevents silently dropping internal module exports that maintainers need. The cap is applied AFTER exclude-pattern filtering, so useful results are not wasted on excluded files.
 
@@ -181,7 +182,8 @@ For full-library skills at higher tiers, the larger cap prevents silently droppi
 # Patterns are matched against the full file path as emitted by ast-grep.
 # Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
 # {HEAD_CAP} = 200 (default) or 500 (Forge+/Deep full-library) — see head cap selection above.
-ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
+# IMPORTANT: The explicit 'run' subcommand is required for --json=stream to work.
+ast-grep run -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
 import sys, json, fnmatch, signal
 signal.signal(signal.SIGPIPE, signal.SIG_DFL)
 
@@ -244,9 +246,11 @@ constraints:
 
 **JavaScript/TypeScript — exported functions:**
 
+> **Language selection:** Use `language: typescript` for `.ts` files and `language: tsx` for `.tsx` files. Patterns that work with `typescript` may return zero results with `tsx` and vice versa — they use different tree-sitter parsers. For mixed codebases, run each pattern twice (once per language) and merge results. Note: `export function` patterns may fail with `tsx` on ast-grep 0.41.x (see Known Limitations #5) — use source reading as fallback for those.
+
 ```yaml
 id: js-exported-functions
-language: typescript
+language: typescript  # Use 'tsx' for .tsx files — see language selection note above
 rule:
   pattern: 'export function $NAME($$$PARAMS)'
 ```
@@ -311,6 +315,67 @@ constraints:
     regex: '^[A-Z]'
 ```
 
+### Component Library YAML Rule Recipes
+
+These patterns are used by `step-03d-component-extraction.md` when `scope.type: "component-library"`. They prioritize Props interfaces and PascalCase component exports.
+
+**React/TypeScript — Props interfaces (primary API contracts):**
+
+```yaml
+id: react-props-interfaces
+language: typescript  # Use 'tsx' for .tsx files
+rule:
+  pattern: 'export interface $NAME { $$$ }'
+constraints:
+  NAME:
+    regex: '.*Props$'
+```
+
+**React/TypeScript — Component function exports (PascalCase):**
+
+> **Language note:** Use `language: tsx` for `.tsx` files. The `export function` pattern may fail with tsx on ast-grep 0.41.x (see Known Limitations #5). Use `export const` patterns as primary and fall back to source reading for `export function` in tsx files.
+
+```yaml
+id: react-component-functions
+language: tsx
+rule:
+  pattern: 'export function $NAME($$$PARAMS)'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+**React/TypeScript — Component arrow function exports:**
+
+```yaml
+id: react-component-arrow-functions
+language: typescript
+rule:
+  pattern: 'export const $NAME = ($$$PARAMS) => $BODY'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+**Vue — defineProps extraction:**
+
+```yaml
+id: vue-define-props
+language: typescript
+rule:
+  pattern: 'defineProps<$TYPE>()'
+```
+
+**Props-to-Component linking strategy:**
+
+After extracting Props interfaces and component exports, link them using this 3-level fallback chain:
+
+1. **Naming convention (primary):** Strip `Props` suffix from interface name → match to component export (e.g., `NativeLiquidButtonProps` → `NativeLiquidButton`)
+2. **File co-location (fallback):** If naming doesn't match, check if a Props interface and a PascalCase export function are defined in the same file — link them
+3. **Generic parameter (deep fallback):** Search for `ComponentProps<typeof $NAME>` or `React.ComponentProps<typeof $NAME>` patterns that reference the component by name
+
+Unlinked Props interfaces are included as standalone type exports. Unlinked component exports are included with a note that no Props interface was found (signature-only, T1-low confidence for API contract).
+
 ### Known ast-grep Limitations
 
 When using ast-grep for extraction, be aware of these documented limitations:
@@ -326,6 +391,32 @@ When using ast-grep for extraction, be aware of these documented limitations:
    - Second: if `find_code()` also fails, fall back to source reading for that pattern category (T1-low confidence)
    - Never silently accept zero results for a pattern category that the source language commonly uses
 
+5. **TSX `export function` pattern failure:** The `export function $NAME($$$PARAMS)` pattern may return zero results in TSX files with ast-grep 0.41.x. This affects both MCP tools and CLI. `export const` and `export type` patterns are unaffected. **Workaround:** For TSX files, use `export const` patterns first (which work), then fall back to source reading (grep/file read) for `export function` declarations. When a TSX codebase shows zero `export function` matches but source files clearly contain them, this is a known ast-grep tree-sitter tsx parser limitation — not an extraction error. Log it in the evidence report and proceed with T1-low confidence for those exports.
+
+6. **CLI `--json=stream` may produce no output:** On ast-grep 0.41.x, `--json=stream` may produce empty output for certain patterns. The `--json=stream` flag requires the explicit `run` subcommand: use `ast-grep run -p '{pattern}' --json=stream` (not `ast-grep -p '{pattern}' --json=stream`). If streaming still produces no output, fall back to the MCP tool or source reading.
+
+### Component Library Demo/Example Auto-Exclusion
+
+When `scope.type: "component-library"`, auto-detect and propose demo/example exclusions before extraction begins. **User confirmation is required before applying** — some `examples/` directories contain API-level code.
+
+**Auto-detect directory patterns:**
+- `**/demo/**`, `**/demos/**`
+- `**/stories/**`, `**/__stories__/**`, `**/storybook/**`
+- `**/examples/**`, `**/example/**`
+
+**Auto-detect file patterns:**
+- `**/*.stories.*`, `**/*.story.*`
+- `**/*.example.*`, `**/*.demo.*`
+
+If `demo_patterns` is specified in the brief, use those instead of auto-detection.
+
+**Procedure:**
+1. Scan the scoped file tree for matching directories and files
+2. Count matches per pattern category
+3. Present to user: "**Auto-detected {N} demo/example files** in {M} directories matching these patterns: {list}. Confirm exclusion? [Y/n] Or adjust patterns:"
+4. Apply confirmed patterns to the exclude list before AST extraction
+5. Record in extraction inventory: `demo_files_excluded: {count}`
+
 ### Re-Export Tracing and Script/Asset Extraction
 
 See `extraction-patterns-tracing.md` for: