bmad-module-skill-forge 0.7.4 → 0.8.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "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.
 
@@ -102,7 +102,7 @@ For remote repository sources (GitHub URLs), CCC cannot operate during step-02b
 
 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 `ccc init {temp_path}` + `ccc index` on the ephemeral clone (extended timeout or background mode, verified via `ccc status`)
+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.

package/src/knowledge/tool-resolution.md

@@ -7,12 +7,13 @@ 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             |
+| `qmd_bridge` | `version()`                      | `qmd --version` → parse `"qmd X.Y.Z"` → `"X.Y.Z"`              | qmd MCP server | `qmd --version`                                    | `"unknown"`                      |
 | `gh_bridge`  | `list_tree(owner, repo, branch)` | `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1`     | gh CLI         | `gh api ...`                                       | Direct file listing if local     |
 | `gh_bridge`  | `read_file(owner, repo, path)`   | `gh api repos/{owner}/{repo}/contents/{path}`                    | gh CLI         | `gh api ...`                                       | Direct file read if local        |
 

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-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:

package/src/workflows/create-skill/data/skill-sections.md

@@ -59,6 +59,82 @@ SKILL.md uses a two-tier structure to ensure actionable content survives `split-
 - **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge/Forge+ tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
 - **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
 
+### Component Library Section Overrides
+
+When `scope.type: "component-library"`, these section formats replace their standard counterparts. All other sections (Overview, Common Workflows, Architecture, CLI, Manual Sections, etc.) use the standard format.
+
+#### Section 4 — Component Catalog (replaces Key API Summary)
+
+```markdown
+## Component Catalog
+
+| Category | Count | Key Components |
+|----------|-------|---------------|
+| {category} | {count} | {ComponentA}, {ComponentB}, {ComponentC}, ... |
+
+**Design system variants:** {primary} (primary), {variant2}, {variant3}
+**Total components:** {unique_count} | **With {variant1}:** {count1} | **With {variant2}:** {count2}
+```
+
+- Source: `component_catalog[]` from step-03d extraction
+- Group by `category` field from registry
+- Show top 3-5 component names per category
+- Cite registry file: `[SRC:{registry_file}:L1]`
+- Budget: ~20 lines (same as standard Section 4)
+
+#### Section 5 — Key Props (replaces Key Types)
+
+```markdown
+## Key Types
+
+### {ComponentName}Props
+
+| Prop | Type | Default | Required |
+|------|------|---------|----------|
+| {propName} | {type} | {default or —} | {yes/no} |
+
+{Repeat for top 5 Props interfaces}
+```
+
+- Show only the 5 most-used Props interfaces (by component count or documentation prominence)
+- Full Props details for all components go in Tier 2 reference
+- Budget: ~20 lines (same as standard Section 5)
+
+#### Tier 2 — Props Reference (replaces Full API Reference)
+
+```markdown
+## Full API Reference
+
+### {ComponentName}
+
+**Install:** `npx {cli} add {component-id}`
+**Available in:** {variant list}
+**Props:** `{ComponentName}Props`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| {prop} | {type} | {default} | {description from JSDoc or —} |
+
+**Provenance:** `[AST:{file}:L{line}]`
+```
+
+- Organize by component, not by function
+- Each component shows: install command, variant availability, full props table
+- Include JSDoc descriptions for props when available
+- Standard provenance citations apply
+
+#### 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}
+```
+
 ### Provenance Citation Format
 
 | Tier | Format | Example |

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -68,8 +68,8 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    When `exclude_patterns` exist, use `--no-cone` mode to pass both include and exclude patterns directly as gitignore-style rules:
 
-   1. Convert `include_patterns` to gitignore-style patterns. If a pattern contains no glob characters (`*`, `?`, `[`) and does not end with `/`, append `/**` to match directory contents recursively (e.g., `cognee` → `cognee/**`; `cognee/**` → kept as-is).
-   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same anchoring rule (e.g., `cognee/tests` → `!cognee/tests/**`; `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
+   1. Convert `include_patterns` to gitignore-style patterns. For patterns without glob characters (`*`, `?`, `[`) that do not end with `/`, apply the **file-detection heuristic**: if the last path segment contains a `.` (file extension), it is an **individual file** — prepend `/` and keep as-is (e.g., `packages/registry/registry.json` → `/packages/registry/registry.json`). If the last path segment has no extension, it is a **bare directory name** — append `/**` (e.g., `cognee` → `cognee/**`). Patterns that already contain glob characters are kept as-is (e.g., `cognee/**` → kept as-is).
+   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same file-detection heuristic: individual files (last segment has `.` extension) get `!/` prefix only (e.g., `src/internal/config.json` → `!/src/internal/config.json`); bare directory names get `/**` appended (e.g., `cognee/tests` → `!cognee/tests/**`). Patterns with globs are kept as-is with `!` prefix (e.g., `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
    3. **CRITICAL:** List all include patterns BEFORE negated exclude patterns — git processes patterns in order and a negation can only suppress a prior inclusion.
    4. Pass to sparse-checkout — include patterns first, then negated exclude patterns:
 
@@ -79,15 +79,17 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    Example transformation:
    ```
-   Brief include_patterns:        Brief exclude_patterns:
-   cognee/**                      cognee/tests/**
-                                  cognee/alembic/**
-                                  **/test_*
+   Brief include_patterns:          Brief exclude_patterns:
+   cognee/**                        cognee/tests/**
+   packages/registry/registry.json  cognee/alembic/**
+                                    **/test_*
 
    sparse-checkout args (--no-cone):
-   'cognee/**' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
+   'cognee/**' '/packages/registry/registry.json' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
    ```
 
+   Note: `registry.json` is an individual file (has `.json` extension), so it gets `/` prefix instead of `/**` suffix.
+
    **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
 
    **Always-included root files:**
@@ -112,7 +114,13 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
 
-**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
+**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`:
+
+1. **Reset working directory first:** Before deleting the clone, ensure the shell working directory is not inside the temp path. Run `cd {project-root}` using the **absolute path** captured at workflow start (not a relative path). This prevents `getcwd` errors when the temp directory is deleted while it is the shell's cwd — which happens if `cd {temp_path}` was used during CCC init or extraction operations.
+2. **Delete the clone:** `rm -rf {temp_path}`
+3. **Log:** "Ephemeral source clone cleaned up."
+
+This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing. **If any error halts the extraction step before Gate 2 is reached**, cleanup must still occur: reset cwd to `{project-root}` and attempt to delete `{temp_path}` before halting. Log the cleanup attempt regardless of success.
 
 ---
 
@@ -137,7 +145,11 @@ Store the result as `source_commit` in context. If capture fails (not a git repo
 After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
 
 - Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
-- JavaScript/TypeScript: `package.json` (`"version"`)
+- JavaScript/TypeScript: `package.json` (`"version"`). **Monorepo resolution:** When multiple `package.json` files exist (workspace root + packages), resolve version using this priority:
+  1. Package whose `name` field matches `brief.name` (e.g., the skill's target library name)
+  2. Package with a `bin` field (CLI entry point — represents the published version)
+  3. Root workspace `package.json` version (if present)
+  4. Fall back to `brief.version` if no version found. For monorepos using workspace protocols (pnpm, yarn, npm workspaces), the root `package.json` often has no `version` field — this is expected, not an error.
 - Rust: `Cargo.toml` (`[package] version`)
 - Go: `go.mod` (module version if tagged)
 

package/src/workflows/create-skill/steps-c/step-02b-ccc-discover.md

@@ -79,7 +79,7 @@ Read `ccc_index` from forge-tier.yaml:
 - If `ccc_index.status` is `"stale"`: display brief note — "CCC index is stale — discovery results may miss recent changes." Continue to section 3.
 - If `ccc_index.status` is `"none"` or `"failed"`: attempt lazy indexing via `ccc_bridge.ensure_index(source_root)`. If indexing succeeds, continue to section 3. If indexing fails, set `{ccc_discovery: []}` and auto-proceed to section 5.
 
-**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `ccc init` + `ccc index {source_root}` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc init` + `ccc index` (CLI). Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 ### 3. Construct Semantic Query
 
@@ -97,7 +97,7 @@ Where:
 
 Run `ccc_bridge.search(query, source_root, top_k=20)`:
 
-**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {source_root} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory — there is no flag to specify a project directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 **If search succeeds:**
 

package/src/workflows/create-skill/steps-c/step-03-extract.md

@@ -2,6 +2,7 @@
 name: 'step-03-extract'
 description: 'Tier-dependent source code extraction — AST or source reading for exports, signatures, and types'
 nextStepFile: './step-03b-fetch-temporal.md'
+componentExtractionStepFile: './step-03d-component-extraction.md'
 extractionPatternsData: '../data/extraction-patterns.md'
 extractionPatternsTracingData: '../data/extraction-patterns-tracing.md'
 tierDegradationRulesData: '../data/tier-degradation-rules.md'
@@ -49,7 +50,7 @@ To extract all public exports, function signatures, type definitions, and co-imp
 - Available: brief_data, tier, source_root, file_tree from step-01; ecosystem check outcome from step-02 (proceed/halt decision — no named variable stored)
 - Focus: Source code extraction and inventory building
 - Limits: Do NOT compile, assemble, or write any output
-- Dependencies: Source code must be accessible (resolved in step-01)
+- Dependencies: Source code must be accessible (local repos resolved in step-01; remote repos cloned in section 2a)
 
 ## MANDATORY SEQUENCE
 
@@ -69,32 +70,9 @@ From the brief, apply scope and pattern filters:
 
 Build the filtered file list from the source tree resolved in step-01. Record the result: "**Filtered file count: {N} files in scope**" — this count is the input to the AST Extraction Protocol decision tree in the extraction patterns data file.
 
-### 3. Check for Docs-Only Mode
-
-**If `source_type: "docs-only"` in the brief data:**
-
-"**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step-03c."
-
-Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
-
-**If `source_type: "source"` (default):** Continue with extraction below.
-
-### 4. Execute Tier-Dependent Extraction
-
-Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution** protocol for Forge/Deep tiers (ephemeral clone, sparse-checkout, cleanup) and the **Version Reconciliation** protocol for all tiers. Apply the protocols before proceeding with the tier-specific extraction strategy below.
-
-**Quick Tier (No AST tools):**
+### 2a. Resolve Source Access
 
-1. Use `gh_bridge.list_tree(owner, repo, branch)` to map source structure (if remote)
-2. Identify entry points: index files, main exports, public modules
-3. Use `gh_bridge.read_file(owner, repo, path)` to read each entry point
-4. Extract from source text: exported function names, parameter lists, return types
-5. Infer types from JSDoc, docstrings, type annotations
-6. Confidence: All results T1-low — `[SRC:{file}:L{line}]`
-
-**Tool resolution for gh_bridge:** Use `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` for list_tree, `gh api repos/{owner}/{repo}/contents/{path}` for read_file. If source is local, use direct file listing/reading instead. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
-
-**Forge/Forge+/Deep Tier (AST available):**
+Load `{sourceResolutionData}` completely. Follow the **Remote Source Resolution** protocol for Forge/Deep tiers (ephemeral clone, sparse-checkout, cleanup), the **Source Commit Capture** protocol for all tiers, and the **Version Reconciliation** protocol for all tiers. This ensures source code is accessible regardless of which extraction path is taken below (standard, component-library, or docs-only).
 
 **Deferred CCC Discovery (Forge+ and Deep — remote sources only):**
 
@@ -106,12 +84,12 @@ If ALL of these conditions are true:
 
 Then run CCC indexing and discovery on the ephemeral clone:
 
-1. **Index the clone:** Run `ccc init {temp_path}` then `ccc index` with an extended timeout or in background mode — indexing can take several minutes on large codebases (1000+ files). Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero. If init fails or indexing fails, set `{ccc_discovery: []}` and continue — this is not an error.
+1. **Index the clone:** Run `cd {temp_path} && ccc init` then `ccc index` with an extended timeout or in background mode — `ccc init` takes no positional arguments and initializes the index for the current working directory. Indexing can take several minutes on large codebases (1000+ files). Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero. If init fails or indexing fails, set `{ccc_discovery: []}` and continue — this is not an error.
 
 2. **Construct semantic query:** Build from brief data: `"{brief.name} {brief.scope}"`. Truncate to 80 characters — keep the full skill name and trim `brief.scope` from the end. If `brief.scope` is very short (< 10 chars), append terms from `brief.description` to fill the remaining space.
 
 3. **Execute search:** Run `ccc_bridge.search(query, temp_path, top_k=20)`:
-   - **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{query}" --path {temp_path} --top 20` (CLI). See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+   - **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {temp_path} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
 
 4. **Store results:** If search succeeds, store as `{ccc_discovery: [{file, score, snippet}]}`. Display: "**CCC semantic discovery (post-clone): {N} relevant regions identified across {M} unique files.**"
 
@@ -126,7 +104,44 @@ If `{ccc_discovery}` is in context and non-empty (populated by step-02b or defer
 
 If `{ccc_discovery}` is empty or not in context: proceed with existing file ordering (no change to current behavior).
 
-⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step-01's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases.
+### 2b. Component Library Delegation
+
+**If `scope.type: "component-library"` in the brief:**
+
+"**Component library detected.** Delegating to specialized extraction strategy for registry-first, props-focused extraction."
+
+Load and execute `{componentExtractionStepFile}` completely. When that step completes, it returns control here. Resume at section 5 (Build Extraction Inventory) with the enriched extraction data and `component_catalog[]` from the component extraction step.
+
+**Otherwise:** Continue with standard extraction below.
+
+### 3. Check for Docs-Only Mode
+
+**If `source_type: "docs-only"` in the brief data:**
+
+"**Docs-only mode:** No source code to extract. Documentation content will be fetched from `doc_urls` in step-03c."
+
+Build an empty extraction inventory with zero exports. Set `extraction_mode: "docs-only"` in context. Auto-proceed through Gate 2 (section 6) — display the empty inventory and note that T3 content will be produced by the doc-fetcher step.
+
+**If `source_type: "source"` (default):** Continue with extraction below.
+
+### 4. Execute Tier-Dependent Extraction
+
+Source resolution, version reconciliation, and CCC discovery were completed in section 2a. Proceed with the tier-specific extraction strategy below.
+
+**Quick Tier (No AST tools):**
+
+1. Use `gh_bridge.list_tree(owner, repo, branch)` to map source structure (if remote)
+2. Identify entry points: index files, main exports, public modules
+3. Use `gh_bridge.read_file(owner, repo, path)` to read each entry point
+4. Extract from source text: exported function names, parameter lists, return types
+5. Infer types from JSDoc, docstrings, type annotations
+6. Confidence: All results T1-low — `[SRC:{file}:L{line}]`
+
+**Tool resolution for gh_bridge:** Use `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` for list_tree, `gh api repos/{owner}/{repo}/contents/{path}` for read_file. If source is local, use direct file listing/reading instead. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+
+**Forge/Forge+/Deep Tier (AST available):**
+
+⚠️ **CRITICAL:** Before executing AST extraction, load the **AST Extraction Protocol** section from `{extractionPatternsData}`. Follow the decision tree based on the file count from step-01's file tree. This determines whether to use the MCP tool, scoped YAML rules, or CLI streaming. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases. Always use the explicit `run` subcommand with streaming: `ast-grep run -p '{pattern}' --json=stream`.
 
 1. Detect language from brief or file extensions
 2. Follow the AST Extraction Protocol decision tree from `{extractionPatternsData}`:

package/src/workflows/create-skill/steps-c/step-03d-component-extraction.md

@@ -0,0 +1,292 @@
+---
+name: 'step-03d-component-extraction'
+description: 'Component-library extraction strategy — registry detection, props-first extraction, variant consolidation, demo exclusion'
+returnToStep: './step-03-extract.md'
+extractionPatternsData: '../data/extraction-patterns.md'
+---
+
+# Step 3d: Component Library Extraction
+
+## STEP GOAL:
+
+When `scope.type: "component-library"`, perform specialized extraction that treats the component registry as the primary API surface and props interfaces as API contracts. This step replaces the standard AST extraction flow (step-03 sections 4-4c) and returns control to step-03 section 5 (Build Extraction Inventory).
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🎯 ALWAYS follow the exact instructions in the step file
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a skill compilation engine performing component-library-specialized extraction
+- ✅ Zero hallucination tolerance — every extracted item must trace to source code
+- ✅ Component registry is the source of truth for the API surface
+- ✅ Props interfaces are the API contracts, not function signatures
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on extracting component catalog, props interfaces, and shared types
+- 🚫 FORBIDDEN to compile SKILL.md content — that is step-05
+- 🚫 FORBIDDEN to write any output files — extraction stays in context
+- 🚫 FORBIDDEN to include content that cannot be cited to a source location
+- ⚒️ Every extracted item MUST have a provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
+
+## CONTEXT BOUNDARIES:
+
+- Available: brief_data (including `scope.registry_path`, `scope.ui_variants`, `scope.demo_patterns` if present), tier, source_root (may be `temp_path` from ephemeral clone for remote repos — use the working source path resolved in step-03 section 2a), filtered file list from step-03 section 2, CCC discovery results (if available from step-03 section 2a)
+- Focus: Component-specific extraction and inventory building
+- Limits: Do NOT compile, assemble, or write output
+- Dependencies: Source code accessible (resolved in step-03 section 2a — ephemeral clone for remote repos), scope filters already applied
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### Phase 1: Demo/Example Exclusion
+
+Before extraction, identify and exclude demo/example files to avoid inflating export counts.
+
+**If `scope.demo_patterns` is specified in the brief:** Use those patterns directly.
+
+**Otherwise, auto-detect:**
+
+1. Scan the filtered file list for directories matching: `demo/`, `demos/`, `stories/`, `examples/`, `__stories__/`, `storybook/`
+2. Scan for file patterns matching: `*.stories.*`, `*.story.*`, `*.example.*`, `*.demo.*`
+3. Count matches per pattern category
+
+**User confirmation required:**
+
+"**Auto-detected {N} demo/example files** in {M} directories matching these patterns:
+{list detected patterns with counts}
+
+Confirm exclusion? [Y/n] Or adjust patterns:"
+
+Wait for user response. Apply confirmed patterns to the exclude list. Record `demo_files_excluded: {count}` in context.
+
+Update the filtered file list by removing excluded demo files before proceeding.
+
+### Phase 2: Registry Detection
+
+The component registry is the primary API surface for component libraries.
+
+**If `scope.registry_path` is specified in the brief:**
+
+Read the specified file directly. Parse it as described below.
+
+**Otherwise, auto-detect:**
+
+1. Search the filtered file list for files matching these patterns (in priority order):
+   - Files named `registry.ts`, `registry.tsx`, `registry.js` in any directory
+   - Files named `components.ts`, `components.tsx` in `registry/`, `catalog/`, or `components/` directories
+   - Files named `index.ts`, `index.tsx` in `registry/` or `catalog/` directories
+
+2. For each candidate, read the file and look for:
+   - Arrays of objects with fields like `id`, `name`, `component`, `category`
+   - Type annotations containing `Component[]` or similar array types
+   - 10+ entries to qualify as a registry (reject small arrays)
+
+3. **Confidence scoring** for each candidate:
+   - +3 points: Contains `id` field per entry
+   - +2 points: Contains `name` or `component` field per entry
+   - +2 points: Contains `category` or `tags` field per entry
+   - +1 point: Located in a `registry/` or `catalog/` directory
+   - +1 point: Has 20+ entries
+   - Minimum threshold: 5 points to qualify
+
+4. **User confirmation required:**
+
+"**Registry candidate detected** at `{path}` (confidence: {score}/9, {count} entries).
+
+Sample entries:
+{show 3-5 sample entries with id, name, category}
+
+Is this the component registry? [Y/n] Or provide the correct path:"
+
+Wait for user response.
+
+**If no registry found and no `registry_path` in brief:**
+
+"**No component registry detected.** Component-library extraction works best with a registry file. Options:
+- **[P]** Provide the registry file path
+- **[S]** Skip registry — proceed with standard props-first extraction only"
+
+Wait for user response.
+
+### Phase 3: Parse Registry
+
+If a registry was confirmed, parse it into `component_catalog[]`:
+
+**Per-component entry:**
+
+- `id` — registry key (used for CLI `add` command)
+- `name` — display name (PascalCase)
+- `description` — from registry or empty
+- `category` — from registry field or directory structure
+- `available_in[]` — which design system variants include this component
+- `code_paths[]` — source file path for each variant
+- `tags[]` — from registry or empty
+- Provenance citation: `[SRC:{registry_file}:L{line}]`
+
+Display: "**Parsed component catalog: {N} components across {M} categories.**"
+
+**If no registry:** Set `component_catalog: []` and proceed to Phase 4.
+
+### Phase 4: Props-First Extraction
+
+Extract props interfaces as the primary API contracts, then link to components.
+
+**Step 1 — Extract Props interfaces:**
+
+Load `{extractionPatternsData}` and use the component-library-specific patterns.
+
+Using AST tools (Forge/Deep) or source reading (Quick):
+
+```yaml
+# React/TypeScript props interfaces
+id: react-props-interfaces
+language: typescript
+rule:
+  pattern: 'export interface $NAME { $$$ }'
+constraints:
+  NAME:
+    regex: '.*Props$'
+```
+
+For each `*Props` interface found:
+- Extract all fields with types, optionality, and default values
+- Extract JSDoc descriptions per field (if present)
+- Record: interface name, fields[], source file, line number
+- Provenance: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
+
+**Step 2 — Extract component exports:**
+
+```yaml
+# React component exports (PascalCase)
+id: react-component-exports
+language: tsx  # Use 'tsx' for .tsx files, 'typescript' for .ts files
+rule:
+  pattern: 'export function $NAME($$$PARAMS)'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+Also run `export const $NAME` patterns for arrow function components.
+
+For each component export: record name, source file, line number. Do NOT document the function signature in detail (it's always `(props: XProps) => JSX.Element`).
+
+**Step 3 — Link Props to Components:**
+
+Use a 3-level fallback chain:
+
+1. **Naming convention (primary):** Match `FooProps` → `Foo` component by stripping the `Props` suffix
+2. **File co-location (fallback):** If naming doesn't match, check if a Props interface and a component are defined in the same file
+3. **Generic parameter (deep fallback):** Look for `ComponentProps<typeof Foo>` or similar generic patterns that reference the component
+
+For each linked pair, record the association. For unlinked Props interfaces, include them as standalone type exports.
+
+**Step 4 — Extract shared types:**
+
+Extract non-Props type exports using standard AST patterns (same as Forge tier):
+- `export type $NAME = $VALUE`
+- `export enum $NAME { $$$ }`
+- `export interface $NAME { $$$ }` (excluding `*Props` already captured)
+
+### Phase 5: Variant Consolidation
+
+**Skip this phase if `scope.ui_variants` is not specified and no variant directories detected.**
+
+When multiple design system variants exist:
+
+1. **Group components by registry `id`** (NOT by filename — registry is source of truth):
+   - For each `id` in `component_catalog[]`, collect all variant paths from `available_in[]` and `code_paths[]`
+
+2. **Select canonical props definition:**
+   - Use the primary variant (first in `scope.ui_variants` list) as canonical
+   - If primary variant's props are unavailable, use the first available variant
+
+3. **Detect props differences between variants:**
+   - For components available in 2+ variants, compare Props interfaces
+   - Record any variant-specific props as notes (e.g., "Base UI variant adds `slots` prop")
+
+4. **Deduplicate export counts:**
+   - Count unique components (by registry `id`), not total files across variants
+   - Record: `components_unique: {N}`, `components_total_with_variants: {M}`
+
+Display: "**Variant consolidation: {unique} unique components across {variant_count} variants** ({total} total including variants). Primary variant: {primary_name}."
+
+### Phase 6: Build Component Extraction Results
+
+Compile all extracted data into the format expected by step-03 section 5:
+
+**Per-export entry (for Props interfaces — primary API):**
+
+- Interface name (e.g., `NativeLiquidButtonProps`)
+- Full interface with all fields and types
+- Parameters: each field as name, type, required/optional, default
+- Linked component name (e.g., `NativeLiquidButton`)
+- Source file and line number
+- Provenance citation
+- Confidence tier (T1 or T1-low)
+
+**Per-export entry (for component functions):**
+
+- Component name
+- Linked Props interface (if found)
+- Source file and line number
+- Provenance citation
+- Confidence tier
+
+**Per-export entry (for shared types):**
+
+- Same as standard extraction format
+
+**Component library aggregate counts:**
+
+- `components_registered`: count from registry (or 0)
+- `components_documented`: count of components with linked Props
+- `props_interfaces_extracted`: count of `*Props` interfaces
+- `components_unique`: deduplicated count (after variant consolidation)
+- `demo_files_excluded`: count from Phase 1
+- `design_variants`: map of variant name → component count (if variants exist)
+
+**Store `component_catalog[]` in context** — this is consumed by step-05 for the Component Catalog section.
+
+Display: "**Component extraction complete.** Returning to main extraction flow."
+
+## RETURN PROTOCOL
+
+After Phase 6 completes, return control to step-03 section 5 (Build Extraction Inventory). The extraction results from this step are merged into the standard extraction inventory format. Step-03 continues with its normal Gate 2 summary and menu.
+
+Do NOT load `{returnToStep}` — the calling step (step-03) will continue from where it delegated.
+
+---
+
+## SYSTEM SUCCESS/FAILURE METRICS
+
+### SUCCESS:
+
+- Demo/example files detected and excluded with user confirmation
+- Registry detected (or user provided path) and parsed into component_catalog
+- Props interfaces extracted as primary API contracts
+- Components linked to Props via 3-level fallback chain
+- Variant consolidation produced deduplicated counts (if applicable)
+- All extracted items have provenance citations
+- Results compatible with step-03 section 5 inventory format
+- component_catalog stored in context for step-05
+
+### FAILURE:
+
+- Excluding demo files without user confirmation
+- Accepting a registry candidate without user confirmation
+- Not extracting Props interfaces as primary API surface
+- Documenting component function signatures instead of Props
+- Including hallucinated component data not in source
+- Variant deduplication based on filenames instead of registry IDs
+- Not returning control to step-03 after completion
+
+**Master Rule:** Zero hallucination — every extraction must trace to source code. The component registry is the source of truth for the API surface.

package/src/workflows/create-skill/steps-c/step-05-compile.md

@@ -117,6 +117,15 @@ Following the structure from the skill-sections data file:
   3. `{project-root}/_bmad/skf/VERSION` → read plain text file (single line containing version string, written by the SKF installer)
   4. `"unknown"` (final fallback — add a warning to the evidence report)
   Never hardcode the version.
+- Resolve `{ast_grep_version}` using this resolution chain (try each in order, use the first that succeeds):
+  1. `ast-grep --version` → parse version string from output (e.g., `ast-grep 0.41.1` → `"0.41.1"`)
+  2. `mcp__ast-grep__find_code` tool metadata (if version is exposed by the MCP server)
+  3. `"unknown"` (final fallback — add a warning to the evidence report)
+- Resolve `{qmd_version}` using this resolution chain (try each in order, use the first that succeeds):
+  1. `qmd --version` → parse version string from output (e.g., `qmd 2.0.1` → `"2.0.1"`)
+  2. `mcp__plugin_qmd-plugin_qmd__status` → parse version if exposed in status output
+  3. `"unknown"` (final fallback — add a warning to the evidence report)
+  Note: QMD is a Bun/Node package (`@tobilu/qmd`). Install via `bun install -g @tobilu/qmd`.
 - Store `commit_short` = first 8 characters of `source_commit` (or `"unknown"` if unavailable) for use in step-08 report.
 - If `scripts_inventory` is non-empty, populate `scripts[]` array and set `stats.scripts_count`. If `assets_inventory` is non-empty, populate `assets[]` array and set `stats.assets_count`. Omit these fields entirely when inventories are empty.
 

package/src/workflows/test-skill/data/scoring-rules.md

@@ -54,6 +54,18 @@ When `docs_only_mode: true` is set by step-03 (indicating a Quick tier skill whe
 
 This is functionally identical to Quick tier weight redistribution but with a different coverage denominator (self-consistency instead of source comparison).
 
+### State 2 Source Access (Any Tier, Provenance-Map Only)
+
+When source is not locally available and analysis resolves to State 2 (provenance-map baseline per source-access-protocol.md):
+
+- **Signature Accuracy:** N/A — provenance-map stores parameters as flat string arrays; verification is string comparison only, not semantic AST verification. Type aliases (`str` vs `String`, `list` vs `List[Any]`) cannot be resolved without live source.
+- **Type Coverage:** N/A — cannot verify type completeness without local source access for AST re-parsing.
+- **Weight redistribution:** Same as Quick tier — Signature Accuracy (22%) and Type Coverage (14%) weights redistributed proportionally to remaining active categories (Export Coverage, Coherence, External Validation).
+- **Applies regardless of detected tier** (including Forge, Forge+, Deep) whenever `analysis_confidence` is `provenance-map` and local source is unavailable.
+- **Export Coverage denominator:** Uses the union of provenance-map entry names and metadata.json `exports[]` names (per source-access-protocol.md State 2 rules).
+
+Note: When provenance-map entries are predominantly T1 (AST-verified at compilation time), the coverage and name-matching data is already at highest confidence. The N/A categories reflect the inability to re-verify at test time, not low-quality extraction data.
+
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison
 - Signature Accuracy: AST-verified signature matching

package/src/workflows/test-skill/steps-c/step-04b-external-validators.md

@@ -60,13 +60,20 @@ Read {outputFile} frontmatter to get the skill directory path (`skillDir`).
 
 Before running external validators, check if `{forge_data_folder}/{skill_name}/evidence-report.md` contains validation results (a `## Validation Results` section with quality scores).
 
-**Staleness check:** Determine whether SKILL.md has changed since the evidence report was generated.
+**Staleness check:** Determine whether SKILL.md has changed since the evidence report was generated. Walk through these checks in order:
 
-**Primary (git-tracked):** Run `git log -1 --format=%cI -- {skillDir}/SKILL.md` to get the last commit date of SKILL.md. Compare against the evidence report's generation date (from its frontmatter or the `## Validation Results` timestamp). If SKILL.md's last commit is newer, results are stale.
+**Pre-check (untracked or staged-only file):** Run `git ls-files --error-unmatch {skillDir}/SKILL.md 2>/dev/null`.
+- If the command fails (exit code non-zero) or git is not available, the file is either **untracked** (new, never committed) or we're in a **non-git environment**:
+  - Check if `{skillDir}/metadata.json` exists and has a `generation_date` field
+  - Compare `metadata.json` `generation_date` against the evidence report's generation date (from its frontmatter or `## Validation Results` timestamp)
+  - If timestamps match within the same minute (same workflow session): auto-reuse is safe — the evidence report was generated from the same SKILL.md content
+  - If timestamps differ or metadata.json is missing: treat as stale, proceed to section 2 for a fresh run
+  - Note: "Staleness check: SKILL.md is untracked/non-git — using metadata.json timestamp comparison."
+- If the command succeeds (file is tracked by git), continue to Primary check below.
 
-**Secondary (uncommitted changes):** Run `git diff --name-only -- {skillDir}/SKILL.md`. If output is non-empty, SKILL.md has uncommitted changes — treat results as stale regardless of commit dates.
+**Primary (git-tracked):** Run `git log -1 --format=%cI -- {skillDir}/SKILL.md` to get the last commit date of SKILL.md. Compare against the evidence report's generation date (from its frontmatter or the `## Validation Results` timestamp). If SKILL.md's last commit is newer, results are stale.
 
-**Fallback (non-git environments):** If git commands fail (not a git repository), fall back to `metadata.json` `generation_date` comparison with a warning: "Staleness check using metadata.json — may be identical to evidence report timestamp. Consider a git-tracked directory for reliable staleness detection."
+**Secondary (uncommitted changes):** Run `git diff --name-only -- {skillDir}/SKILL.md`. If output is non-empty, SKILL.md has uncommitted changes — treat results as stale regardless of commit dates. Also check `git diff --cached --name-only -- {skillDir}/SKILL.md` for staged-but-uncommitted changes — if non-empty, SKILL.md has been staged since last commit, treat results as stale.
 
 If SKILL.md was modified after the evidence report was generated (e.g., after update-skill), the cached results are stale — skip auto-reuse and proceed to section 2 for a fresh run.
 

package/src/workflows/update-skill/steps-c/step-03-re-extract.md

@@ -76,9 +76,25 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 
 **Remote Source Resolution (Forge/Deep only):**
 
-**MCP source access check (before ephemeral clone):** If MCP source-reading tools are available (zread, deepwiki, gh API, or similar) and `source_repo` is set in metadata.json, use MCP tools to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. MCP provides full source file content equivalent to a local read. If the fetched content is written to a temp file and analyzed with ast-grep, label confidence as T1. If AST is unavailable (the common case for MCP-fetched content), use pattern-based extraction and label confidence as T1-low.
+**MCP source access (ordered fallback):** When `source_repo` is set in metadata.json, try each MCP tool in order to fetch only the changed files from the change manifest. This avoids ephemeral clone overhead entirely. Tools are ordered by data freshness — gh API returns live GitHub content and is preferred for update-skill where current file versions are required. zread and deepwiki depend on manual indexing and may return stale data if indexes haven't been refreshed since the changes being extracted.
 
-**If MCP unavailable:** Load and follow `{remoteSourceResolutionData}` for ephemeral clone setup, version reconciliation, and AST tool unavailability handling.
+1. **gh API** — `gh api repos/{owner}/{repo}/contents/{path}` for raw file content
+   - If accessible: fetch file content (base64-decoded), always current
+   - If rate-limited, 404, or inaccessible: log tool and reason, continue to next tool
+2. **zread** — `get_repo_structure` + `read_file` for targeted file access
+   - If repo found: fetch changed files, proceed with extraction
+   - If "repo not found" or error: log tool and reason, continue to next tool
+   - Caveat: indexed data — may be stale if index wasn't refreshed after the target changes
+3. **deepwiki** — `ask_question` for targeted export/signature queries
+   - If repo indexed and returns usable source data: extract from response
+   - If no results or repo not indexed: log tool and reason, continue to next tool
+   - Caveat: returns synthesized content, not raw source — extraction quality varies; index may be stale
+
+**Confidence labeling:** MCP-fetched content written to a temp file and analyzed with ast-grep → T1. MCP-fetched content analyzed with pattern matching (AST unavailable) → T1-low.
+
+**If all MCP tools fail for this repo:** Fall back to ephemeral clone — load and follow `{remoteSourceResolutionData}` for clone setup, version reconciliation, and AST tool unavailability handling.
+
+**If all approaches fail (MCP + ephemeral clone):** Degrade to provenance-map-only analysis (State 2, T1 confidence from compilation-time data). Warn user: "Source access failed for {source_repo}. Analysis limited to provenance-map baseline."
 
 **Quick tier (text pattern matching):**
 - Extract function/class/type names via regex patterns