From 4a52d8178167499444f9aee90ce6645b07c9decd Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:25:16 -0800
Subject: [PATCH 1/7] refactor: rename marketplace to agentic-marketplace

Rename the marketplace action to agentic-marketplace for better clarity:
- Rename marketplace/ directory to agentic-marketplace/
- Rename workflow file marketplace.yml to agentic-marketplace.yml
- Update all references in README, CLAUDE.md, and docs
- Update workflow and test references
---
 ...arketplace.yml => agentic-marketplace.yml} |  8 ++---
 .github/workflows/test.yml                    |  4 +--
 CLAUDE.md                                     | 10 +++---
 README.md                                     | 22 ++++++------
 .../README.md                                 | 34 +++++++++----------
 .../discover/action.yml                       |  0
 .../generate/action.yml                       |  0
 .../validate/action.yml                       |  0
 8 files changed, 39 insertions(+), 39 deletions(-)
 rename .github/workflows/{marketplace.yml => agentic-marketplace.yml} (86%)
 rename {marketplace => agentic-marketplace}/README.md (88%)
 rename {marketplace => agentic-marketplace}/discover/action.yml (100%)
 rename {marketplace => agentic-marketplace}/generate/action.yml (100%)
 rename {marketplace => agentic-marketplace}/validate/action.yml (100%)

diff --git a/.github/workflows/marketplace.yml b/.github/workflows/agentic-marketplace.yml
similarity index 86%
rename from .github/workflows/marketplace.yml
rename to .github/workflows/agentic-marketplace.yml
index 7e47761..a112e95 100644
--- a/.github/workflows/marketplace.yml
+++ b/.github/workflows/agentic-marketplace.yml
@@ -1,4 +1,4 @@
-name: Marketplace Pipeline
+name: Agentic Marketplace Pipeline
 on:
   workflow_call:
     inputs:
@@ -33,7 +33,7 @@ jobs:
 
       - name: Discover components
         id: discover
-        uses: bitcomplete/bc-github-actions/marketplace/discover@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/discover@v1
         with:
           config-path: ${{ inputs.config-path }}
 
@@ -47,7 +47,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Validate components
-        uses: bitcomplete/bc-github-actions/marketplace/validate@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
         with:
           config-path: ${{ inputs.config-path }}
 
@@ -63,7 +63,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Generate marketplace files
-        uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
         with:
           config-path: ${{ inputs.config-path }}
           github-token: ${{ secrets.token }}
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1ca1dfa..46e8f13 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -49,7 +49,7 @@ jobs:
 
       - name: Test discover action
         id: discover
-        uses: ./marketplace/discover
+        uses: ./agentic-marketplace/discover
         with:
           config-path: '.claude-plugin/generator.config.toml'
 
@@ -68,7 +68,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Test validate action
-        uses: ./marketplace/validate
+        uses: ./agentic-marketplace/validate
         with:
           config-path: '.claude-plugin/generator.config.toml'
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 6fdee0e..c2615b4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,8 +27,8 @@ bc-github-actions/
 │   └── workflows/
 │       ├── test.yml                       # Self-tests
 │       ├── release.yml                    # Version tagging automation
-│       └── marketplace.yml                # REUSABLE WORKFLOW
-├── marketplace/
+│       └── agentic-marketplace.yml        # REUSABLE WORKFLOW
+├── agentic-marketplace/
 │   ├── discover/
 │   │   └── action.yml                     # Composite action
 │   ├── validate/
@@ -62,12 +62,12 @@ bc-github-actions/
 
 ### 1. Hybrid Approach: Composite Actions + Reusable Workflow
 
-**Reusable workflow** (`.github/workflows/marketplace.yml`) for:
-- Full marketplace pipelines (orchestrating steps)
+**Reusable workflow** (`.github/workflows/agentic-marketplace.yml`) for:
+- Full agentic marketplace pipelines (orchestrating steps)
 - Operations requiring secrets (GitHub token for PRs)
 - Job-level parallelism
 
-**Composite actions** (`marketplace/*/action.yml`) for:
+**Composite actions** (`agentic-marketplace/*/action.yml`) for:
 - Single-purpose operations (discover, validate, generate)
 - Maximum composability
 - Can be used standalone or via workflow
diff --git a/README.md b/README.md
index dda440b..351c46b 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Reusable GitHub Actions workflows for Claude Code development and Platform Engin
 
 ## Actions
 
-### Marketplace Automation
+### Agentic Marketplace Automation
 
 Automates Claude Code plugin marketplace management through auto-discovery, validation, and synchronization.
 
@@ -14,11 +14,11 @@ Automates Claude Code plugin marketplace management through auto-discovery, vali
 - Automatic marketplace.json generation
 - PR-based workflow with optional auto-merge
 
-[View marketplace action documentation →](marketplace/README.md)
+[View agentic-marketplace action documentation →](agentic-marketplace/README.md)
 
-## Basic Marketplace Publish Workflow
+## Basic Agentic Marketplace Publish Workflow
 
-When you push changes to a marketplace repository, the workflow automatically discovers, validates, and updates your marketplace.json:
+When you push changes to an agentic marketplace repository, the workflow automatically discovers, validates, and updates your marketplace.json:
 
 ```mermaid
 graph LR
@@ -52,12 +52,12 @@ This happens automatically on every push to your main branch. No manual JSON edi
 
 ## Quick Start
 
-### Using Marketplace Automation
+### Using Agentic Marketplace Automation
 
-Add this to `.github/workflows/marketplace.yml` in your marketplace repository:
+Add this to `.github/workflows/agentic-marketplace.yml` in your marketplace repository:
 
 ```yaml
-name: Update Marketplace
+name: Update Agentic Marketplace
 
 on:
   push:
@@ -67,7 +67,7 @@ on:
 
 jobs:
   update:
-    uses: bitcomplete/bc-github-actions/.github/workflows/marketplace.yml@v1
+    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
     with:
       config-path: .claude-plugin/generator.config.toml
     secrets:
@@ -77,15 +77,15 @@ jobs:
 Or use individual actions in your own workflow:
 
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/discover@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/discover@v1
   with:
     config-path: .claude-plugin/generator.config.toml
 
-- uses: bitcomplete/bc-github-actions/marketplace/validate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
   with:
     config-path: .claude-plugin/generator.config.toml
 
-- uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
   with:
     config-path: .claude-plugin/generator.config.toml
     github-token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/marketplace/README.md b/agentic-marketplace/README.md
similarity index 88%
rename from marketplace/README.md
rename to agentic-marketplace/README.md
index 5ffccb6..2429837 100644
--- a/marketplace/README.md
+++ b/agentic-marketplace/README.md
@@ -1,10 +1,10 @@
-# Marketplace Automation
+# Agentic Marketplace Automation
 
 Automates Claude Code plugin marketplace management through auto-discovery, validation, and synchronization.
 
 ## Overview
 
-The marketplace action provides three composable actions that work together to manage your Claude Code plugin marketplace:
+The agentic-marketplace action provides three composable actions that work together to manage your Claude Code plugin marketplace:
 
 1. **discover** - Finds plugins, commands, agents, skills, hooks, and MCP servers
 2. **validate** - Validates component structure, naming, and metadata
@@ -14,10 +14,10 @@ The marketplace action provides three composable actions that work together to m
 
 ### Using the Reusable Workflow (Recommended)
 
-Add `.github/workflows/marketplace.yml` to your marketplace repository:
+Add `.github/workflows/agentic-marketplace.yml` to your marketplace repository:
 
 ```yaml
-name: Update Marketplace
+name: Update Agentic Marketplace
 
 on:
   push:
@@ -27,7 +27,7 @@ on:
 
 jobs:
   update:
-    uses: bitcomplete/bc-github-actions/.github/workflows/marketplace.yml@v1
+    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
     with:
       config-path: .claude-plugin/generator.config.toml
     secrets:
@@ -39,32 +39,32 @@ jobs:
 For custom workflows, use the actions individually:
 
 ```yaml
-name: Custom Marketplace Workflow
+name: Custom Agentic Marketplace Workflow
 
 on:
   push:
     branches: [main]
 
 jobs:
-  marketplace:
+  agentic-marketplace:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Discover components
         id: discover
-        uses: bitcomplete/bc-github-actions/marketplace/discover@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/discover@v1
         with:
           config-path: .claude-plugin/generator.config.toml
 
       - name: Validate components
-        uses: bitcomplete/bc-github-actions/marketplace/validate@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
         with:
           config-path: .claude-plugin/generator.config.toml
           fail-on-error: true
 
       - name: Generate marketplace files
-        uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+        uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
         with:
           config-path: .claude-plugin/generator.config.toml
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,7 +86,7 @@ Scans your repository for Claude Code components based on your configuration fil
 
 **Example:**
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/discover@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/discover@v1
   id: discover
   with:
     config-path: .claude-plugin/generator.config.toml
@@ -115,7 +115,7 @@ Validates discovered components against marketplace standards defined in your co
 
 **Example:**
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/validate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
   id: validate
   with:
     config-path: .claude-plugin/generator.config.toml
@@ -148,7 +148,7 @@ Generates marketplace.json and plugin.json files, then creates a pull request wi
 
 **Example:**
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
   id: generate
   with:
     config-path: .claude-plugin/generator.config.toml
@@ -204,7 +204,7 @@ your-marketplace/
 │   └── generator.config.toml     # Your configuration
 ├── .github/
 │   └── workflows/
-│       └── marketplace.yml        # Workflow file
+│       └── agentic-marketplace.yml        # Workflow file
 ├── code/                          # Category directory
 │   └── my-plugin/                 # Plugin directory
 │       ├── .claude-plugin/
@@ -297,7 +297,7 @@ Check that:
 Preview changes without creating a PR:
 
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
   with:
     config-path: .claude-plugin/generator.config.toml
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -309,7 +309,7 @@ Preview changes without creating a PR:
 Disable auto-merge to review changes before merging:
 
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/generate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/generate@v1
   with:
     config-path: .claude-plugin/generator.config.toml
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -321,7 +321,7 @@ Disable auto-merge to review changes before merging:
 Use validation output to implement custom logic:
 
 ```yaml
-- uses: bitcomplete/bc-github-actions/marketplace/validate@v1
+- uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
   id: validate
   with:
     fail-on-error: false
diff --git a/marketplace/discover/action.yml b/agentic-marketplace/discover/action.yml
similarity index 100%
rename from marketplace/discover/action.yml
rename to agentic-marketplace/discover/action.yml
diff --git a/marketplace/generate/action.yml b/agentic-marketplace/generate/action.yml
similarity index 100%
rename from marketplace/generate/action.yml
rename to agentic-marketplace/generate/action.yml
diff --git a/marketplace/validate/action.yml b/agentic-marketplace/validate/action.yml
similarity index 100%
rename from marketplace/validate/action.yml
rename to agentic-marketplace/validate/action.yml

From 8f7f0719a909e6d1da4b9702529e5971f7a8af21 Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:26:50 -0800
Subject: [PATCH 2/7] docs: add comprehensive getting started guide

Add GETTING_STARTED.md with step-by-step walkthrough:
- Repository structure setup
- Configuration examples
- First plugin creation
- Usage in Claude Code
- Troubleshooting common issues
- Links from main README and action docs
---
 GETTING_STARTED.md            | 428 ++++++++++++++++++++++++++++++++++
 README.md                     |   2 +
 agentic-marketplace/README.md |   2 +
 3 files changed, 432 insertions(+)
 create mode 100644 GETTING_STARTED.md

diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
new file mode 100644
index 0000000..b103849
--- /dev/null
+++ b/GETTING_STARTED.md
@@ -0,0 +1,428 @@
+# Getting Started with Agentic Marketplace
+
+This guide walks you through setting up and using the Agentic Marketplace automation for your Claude Code plugins.
+
+## What You'll Build
+
+By the end of this guide, you'll have:
+- A marketplace repository with automated discovery and validation
+- Plugin components organized in a standardized structure
+- A `marketplace.json` file that updates automatically when you add or modify plugins
+- CI/CD workflows that maintain your marketplace
+
+## Prerequisites
+
+- GitHub repository for your marketplace
+- Git and GitHub CLI (`gh`) installed
+- Basic familiarity with GitHub Actions
+
+## Step 1: Create Marketplace Repository Structure
+
+Create the following directory structure in your repository:
+
+```bash
+# Create the base structure
+mkdir -p .claude-plugin
+mkdir -p .github/workflows
+
+# Create category directories (customize these for your needs)
+mkdir -p code
+mkdir -p analysis
+mkdir -p communication
+```
+
+Your repository should look like:
+
+```
+your-marketplace/
+├── .claude-plugin/
+├── .github/
+│   └── workflows/
+├── code/              # Category for code-related plugins
+├── analysis/          # Category for analysis plugins
+└── communication/     # Category for communication plugins
+```
+
+## Step 2: Configure the Marketplace
+
+Create `.claude-plugin/generator.config.toml`:
+
+```toml
+# Naming pattern for components (kebab-case)
+naming_pattern = "^[a-z0-9]+(-[a-z0-9]+)*$"
+
+# Reserved words that cannot appear in component names
+reserved_words = ["anthropic", "claude"]
+
+# Plugin discovery paths - adjust to match your categories
+plugin_categories = ["code/**", "analysis/**", "communication/**"]
+
+# Component types to discover
+[discovery]
+plugins = true
+commands = true
+skills = true
+agents = true
+hooks = true
+mcp_servers = true
+
+# Validation rules
+[validation]
+require_description = true
+require_version = true
+min_description_length = 10
+max_description_length = 200
+```
+
+## Step 3: Add the Workflow
+
+Create `.github/workflows/agentic-marketplace.yml`:
+
+```yaml
+name: Update Agentic Marketplace
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
+    with:
+      config-path: .claude-plugin/generator.config.toml
+    secrets:
+      token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Commit and push:
+
+```bash
+git add .
+git commit -m "feat: add agentic marketplace automation"
+git push
+```
+
+## Step 4: Create Your First Plugin
+
+Create a plugin with the two-level directory structure: `category/plugin-name/`
+
+```bash
+# Create plugin directory
+mkdir -p code/my-first-plugin/commands
+
+# Create a command
+cat > code/my-first-plugin/commands/hello.md << 'EOF'
+---
+name: hello
+description: Say hello to the world
+---
+
+Print "Hello, World!" to the console.
+EOF
+```
+
+Your structure should now look like:
+
+```
+your-marketplace/
+├── .claude-plugin/
+│   └── generator.config.toml
+├── .github/
+│   └── workflows/
+│       └── agentic-marketplace.yml
+└── code/
+    └── my-first-plugin/
+        └── commands/
+            └── hello.md
+```
+
+## Step 5: Push and Watch the Magic
+
+```bash
+git add .
+git commit -m "feat: add my-first-plugin"
+git push
+```
+
+The workflow will:
+1. **Discover** your plugin and its components
+2. **Validate** naming and metadata
+3. **Generate** `.claude-plugin/marketplace.json` and `code/my-first-plugin/.claude-plugin/plugin.json`
+4. **Create a PR** with the generated files
+5. **Auto-merge** after CI passes (if enabled)
+
+Check your Actions tab to see it run!
+
+## Step 6: Understanding the Generated Files
+
+After the workflow completes, you'll see:
+
+### `.claude-plugin/marketplace.json`
+
+```json
+{
+  "name": "your-marketplace",
+  "owner": "your-org",
+  "plugins": [
+    {
+      "name": "my-first-plugin",
+      "description": "...",
+      "components": {
+        "commands": [
+          {
+            "name": "hello",
+            "description": "Say hello to the world",
+            "source": "code/my-first-plugin/commands/hello.md"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### `code/my-first-plugin/.claude-plugin/plugin.json`
+
+```json
+{
+  "name": "my-first-plugin",
+  "version": "1.0.0",
+  "description": "...",
+  "commands": ["hello"]
+}
+```
+
+## Step 7: Using Your Marketplace in Claude Code
+
+### Option A: Install from GitHub
+
+Users can install plugins from your marketplace:
+
+```bash
+# Install the entire marketplace
+claude plugin install github:your-org/your-marketplace
+
+# Install a specific plugin
+claude plugin install github:your-org/your-marketplace/code/my-first-plugin
+```
+
+### Option B: Local Development
+
+Clone and link for local development:
+
+```bash
+# Clone your marketplace
+git clone https://github.com/your-org/your-marketplace.git
+
+# Link for local use
+cd your-marketplace
+claude plugin link code/my-first-plugin
+```
+
+## Adding More Components
+
+### Commands
+
+Commands are slash commands users can invoke:
+
+```bash
+mkdir -p code/my-plugin/commands
+cat > code/my-plugin/commands/example.md << 'EOF'
+---
+name: example
+description: Example command
+---
+
+Command implementation here.
+EOF
+```
+
+### Skills
+
+Skills provide instructional content:
+
+```bash
+mkdir -p code/my-plugin/skills
+cat > code/my-plugin/skills/example-skill.md << 'EOF'
+---
+name: example-skill
+description: Example skill
+---
+
+Skill content here.
+EOF
+```
+
+### Agents
+
+Agents are autonomous subagents:
+
+```bash
+mkdir -p code/my-plugin/agents
+cat > code/my-plugin/agents/example-agent.md << 'EOF'
+---
+name: example-agent
+description: Example agent
+color: blue
+---
+
+Agent system prompt here.
+EOF
+```
+
+### Hooks
+
+Hooks respond to events:
+
+```bash
+mkdir -p code/my-plugin/hooks
+cat > code/my-plugin/hooks/hooks.json << 'EOF'
+{
+  "hooks": [
+    {
+      "event": "PreToolUse",
+      "filter": {"toolName": "Bash"},
+      "action": {
+        "type": "prompt",
+        "prompt": "Before running bash commands, check for destructive operations."
+      }
+    }
+  ]
+}
+EOF
+```
+
+## Validation and Testing
+
+### Local Validation
+
+Before pushing, validate your components:
+
+```bash
+# Clone the bc-github-actions repo
+git clone https://github.com/bitcomplete/bc-github-actions.git
+
+# Run validation
+cd your-marketplace
+../bc-github-actions/scripts/dist/discover-components.cjs validate
+```
+
+### Common Validation Errors
+
+**Error: Component name doesn't match pattern**
+```
+Fix: Use kebab-case: my-component (not myComponent or my_component)
+```
+
+**Error: Description too short**
+```
+Fix: Add a meaningful description (min 10 characters)
+```
+
+**Error: Missing required fields**
+```
+Fix: Ensure frontmatter has name and description
+```
+
+## Customization
+
+### Change Naming Convention
+
+Edit `.claude-plugin/generator.config.toml`:
+
+```toml
+# For snake_case
+naming_pattern = "^[a-z0-9]+(_[a-z0-9]+)*$"
+
+# For camelCase
+naming_pattern = "^[a-z][a-zA-Z0-9]*$"
+```
+
+### Disable Auto-Merge
+
+Edit `.github/workflows/agentic-marketplace.yml`:
+
+```yaml
+jobs:
+  update:
+    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
+    with:
+      config-path: .claude-plugin/generator.config.toml
+      auto-merge: false  # Add this line
+    secrets:
+      token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Add Custom Validation
+
+Create a separate workflow for custom validation:
+
+```yaml
+name: Custom Validation
+
+on:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
+        id: validate
+        with:
+          fail-on-error: false
+
+      - name: Custom checks
+        if: steps.validate.outputs.valid == 'false'
+        run: |
+          echo "Custom validation logic here"
+```
+
+## Troubleshooting
+
+### Workflow Not Running
+
+Check:
+- Workflow file is in `.github/workflows/`
+- File has `.yml` extension
+- Syntax is valid YAML
+
+### No Components Discovered
+
+Check:
+- Plugin structure is `category/plugin-name/`
+- Component files have YAML frontmatter
+- `plugin_categories` in config matches your directories
+
+### Validation Failing
+
+Check:
+- Component names use kebab-case (or your configured pattern)
+- All components have name and description
+- Description length is within bounds (10-200 characters)
+
+### PR Not Auto-Merging
+
+Check:
+- Repository settings allow auto-merge
+- No required reviews or status checks blocking
+- Branch protection rules don't prevent auto-merge
+
+## Next Steps
+
+- Read the [full documentation](agentic-marketplace/README.md)
+- Check [example workflows](https://github.com/bitcomplete/bc-llm-skills)
+- Explore [advanced usage patterns](agentic-marketplace/README.md#advanced-usage)
+
+## Getting Help
+
+- Open an issue: https://github.com/bitcomplete/bc-github-actions/issues
+- Check examples: https://github.com/bitcomplete/bc-llm-skills
diff --git a/README.md b/README.md
index 351c46b..d1b5ea4 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 Reusable GitHub Actions workflows for Claude Code development and Platform Engineering. We use these workflows ourselves, and now you can too.
 
+**[📖 Getting Started Guide →](GETTING_STARTED.md)** - New to agentic marketplaces? Start here!
+
 ## Actions
 
 ### Agentic Marketplace Automation
diff --git a/agentic-marketplace/README.md b/agentic-marketplace/README.md
index 2429837..0669945 100644
--- a/agentic-marketplace/README.md
+++ b/agentic-marketplace/README.md
@@ -2,6 +2,8 @@
 
 Automates Claude Code plugin marketplace management through auto-discovery, validation, and synchronization.
 
+**New to agentic marketplaces?** Check out the [Getting Started Guide](../GETTING_STARTED.md) for a step-by-step walkthrough.
+
 ## Overview
 
 The agentic-marketplace action provides three composable actions that work together to manage your Claude Code plugin marketplace:

From b640632aacba5d7fc8bebc5ad17e462a5850d832 Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:31:56 -0800
Subject: [PATCH 3/7] fix: add pluginCategories to test fixture config to limit
 scanning scope

---
 test-fixtures/valid/.claude-plugin/generator.config.toml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/test-fixtures/valid/.claude-plugin/generator.config.toml b/test-fixtures/valid/.claude-plugin/generator.config.toml
index 52a8052..e0de71a 100644
--- a/test-fixtures/valid/.claude-plugin/generator.config.toml
+++ b/test-fixtures/valid/.claude-plugin/generator.config.toml
@@ -9,7 +9,8 @@ name = "Test Owner"
 email = "test@example.com"
 
 [discovery]
-excludeDirs = [".git", "node_modules", ".github", ".claude", "templates", "test-components"]
+pluginCategories = ["analysis/**"]
+excludeDirs = [".git", "node_modules", ".github", ".claude", "templates", "test-components", "docs"]
 excludePatterns = ["**/template/**", "**/*template*/**"]
 maxDepth = 10
 skillFilename = "SKILL.md"

From 6b370271cb26b4dffa88f56cd0e0491babc3c63d Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:32:58 -0800
Subject: [PATCH 4/7] fix: use absolute config paths in test workflows

---
 .github/workflows/test.yml | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 46e8f13..c272e3a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -40,9 +40,6 @@ jobs:
 
   test-discover-action:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: test-fixtures/valid
     steps:
       - name: Checkout code
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -51,7 +48,7 @@ jobs:
         id: discover
         uses: ./agentic-marketplace/discover
         with:
-          config-path: '.claude-plugin/generator.config.toml'
+          config-path: 'test-fixtures/valid/.claude-plugin/generator.config.toml'
 
       - name: Verify discovery output
         run: |
@@ -60,9 +57,6 @@ jobs:
 
   test-validate-action:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: test-fixtures/valid
     steps:
       - name: Checkout code
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -70,7 +64,7 @@ jobs:
       - name: Test validate action
         uses: ./agentic-marketplace/validate
         with:
-          config-path: '.claude-plugin/generator.config.toml'
+          config-path: 'test-fixtures/valid/.claude-plugin/generator.config.toml'
 
   test-end-to-end:
     runs-on: ubuntu-latest

From 3f6b6ccccb8c72ded4bf4b0f0d365357cf0dd190 Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:35:39 -0800
Subject: [PATCH 5/7] fix: move GETTING_STARTED.md to docs/ to avoid component
 scanning

---
 README.md                                     | 2 +-
 agentic-marketplace/README.md                 | 2 +-
 GETTING_STARTED.md => docs/GETTING_STARTED.md | 0
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename GETTING_STARTED.md => docs/GETTING_STARTED.md (100%)

diff --git a/README.md b/README.md
index d1b5ea4..59e3cdb 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 Reusable GitHub Actions workflows for Claude Code development and Platform Engineering. We use these workflows ourselves, and now you can too.
 
-**[📖 Getting Started Guide →](GETTING_STARTED.md)** - New to agentic marketplaces? Start here!
+**[📖 Getting Started Guide →](docs/GETTING_STARTED.md)** - New to agentic marketplaces? Start here!
 
 ## Actions
 
diff --git a/agentic-marketplace/README.md b/agentic-marketplace/README.md
index 0669945..b54f6c1 100644
--- a/agentic-marketplace/README.md
+++ b/agentic-marketplace/README.md
@@ -2,7 +2,7 @@
 
 Automates Claude Code plugin marketplace management through auto-discovery, validation, and synchronization.
 
-**New to agentic marketplaces?** Check out the [Getting Started Guide](../GETTING_STARTED.md) for a step-by-step walkthrough.
+**New to agentic marketplaces?** Check out the [Getting Started Guide](../docs/GETTING_STARTED.md) for a step-by-step walkthrough.
 
 ## Overview
 
diff --git a/GETTING_STARTED.md b/docs/GETTING_STARTED.md
similarity index 100%
rename from GETTING_STARTED.md
rename to docs/GETTING_STARTED.md

From 938ff39ef114d7fd15ac2e7c9c3bd5e16a20d0ae Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:36:35 -0800
Subject: [PATCH 6/7] fix: remove docs to unblock CI (will add back separately)

---
 docs/GETTING_STARTED.md | 428 ----------------------------------------
 1 file changed, 428 deletions(-)
 delete mode 100644 docs/GETTING_STARTED.md

diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
deleted file mode 100644
index b103849..0000000
--- a/docs/GETTING_STARTED.md
+++ /dev/null
@@ -1,428 +0,0 @@
-# Getting Started with Agentic Marketplace
-
-This guide walks you through setting up and using the Agentic Marketplace automation for your Claude Code plugins.
-
-## What You'll Build
-
-By the end of this guide, you'll have:
-- A marketplace repository with automated discovery and validation
-- Plugin components organized in a standardized structure
-- A `marketplace.json` file that updates automatically when you add or modify plugins
-- CI/CD workflows that maintain your marketplace
-
-## Prerequisites
-
-- GitHub repository for your marketplace
-- Git and GitHub CLI (`gh`) installed
-- Basic familiarity with GitHub Actions
-
-## Step 1: Create Marketplace Repository Structure
-
-Create the following directory structure in your repository:
-
-```bash
-# Create the base structure
-mkdir -p .claude-plugin
-mkdir -p .github/workflows
-
-# Create category directories (customize these for your needs)
-mkdir -p code
-mkdir -p analysis
-mkdir -p communication
-```
-
-Your repository should look like:
-
-```
-your-marketplace/
-├── .claude-plugin/
-├── .github/
-│   └── workflows/
-├── code/              # Category for code-related plugins
-├── analysis/          # Category for analysis plugins
-└── communication/     # Category for communication plugins
-```
-
-## Step 2: Configure the Marketplace
-
-Create `.claude-plugin/generator.config.toml`:
-
-```toml
-# Naming pattern for components (kebab-case)
-naming_pattern = "^[a-z0-9]+(-[a-z0-9]+)*$"
-
-# Reserved words that cannot appear in component names
-reserved_words = ["anthropic", "claude"]
-
-# Plugin discovery paths - adjust to match your categories
-plugin_categories = ["code/**", "analysis/**", "communication/**"]
-
-# Component types to discover
-[discovery]
-plugins = true
-commands = true
-skills = true
-agents = true
-hooks = true
-mcp_servers = true
-
-# Validation rules
-[validation]
-require_description = true
-require_version = true
-min_description_length = 10
-max_description_length = 200
-```
-
-## Step 3: Add the Workflow
-
-Create `.github/workflows/agentic-marketplace.yml`:
-
-```yaml
-name: Update Agentic Marketplace
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  update:
-    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
-    with:
-      config-path: .claude-plugin/generator.config.toml
-    secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-Commit and push:
-
-```bash
-git add .
-git commit -m "feat: add agentic marketplace automation"
-git push
-```
-
-## Step 4: Create Your First Plugin
-
-Create a plugin with the two-level directory structure: `category/plugin-name/`
-
-```bash
-# Create plugin directory
-mkdir -p code/my-first-plugin/commands
-
-# Create a command
-cat > code/my-first-plugin/commands/hello.md << 'EOF'
----
-name: hello
-description: Say hello to the world
----
-
-Print "Hello, World!" to the console.
-EOF
-```
-
-Your structure should now look like:
-
-```
-your-marketplace/
-├── .claude-plugin/
-│   └── generator.config.toml
-├── .github/
-│   └── workflows/
-│       └── agentic-marketplace.yml
-└── code/
-    └── my-first-plugin/
-        └── commands/
-            └── hello.md
-```
-
-## Step 5: Push and Watch the Magic
-
-```bash
-git add .
-git commit -m "feat: add my-first-plugin"
-git push
-```
-
-The workflow will:
-1. **Discover** your plugin and its components
-2. **Validate** naming and metadata
-3. **Generate** `.claude-plugin/marketplace.json` and `code/my-first-plugin/.claude-plugin/plugin.json`
-4. **Create a PR** with the generated files
-5. **Auto-merge** after CI passes (if enabled)
-
-Check your Actions tab to see it run!
-
-## Step 6: Understanding the Generated Files
-
-After the workflow completes, you'll see:
-
-### `.claude-plugin/marketplace.json`
-
-```json
-{
-  "name": "your-marketplace",
-  "owner": "your-org",
-  "plugins": [
-    {
-      "name": "my-first-plugin",
-      "description": "...",
-      "components": {
-        "commands": [
-          {
-            "name": "hello",
-            "description": "Say hello to the world",
-            "source": "code/my-first-plugin/commands/hello.md"
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-### `code/my-first-plugin/.claude-plugin/plugin.json`
-
-```json
-{
-  "name": "my-first-plugin",
-  "version": "1.0.0",
-  "description": "...",
-  "commands": ["hello"]
-}
-```
-
-## Step 7: Using Your Marketplace in Claude Code
-
-### Option A: Install from GitHub
-
-Users can install plugins from your marketplace:
-
-```bash
-# Install the entire marketplace
-claude plugin install github:your-org/your-marketplace
-
-# Install a specific plugin
-claude plugin install github:your-org/your-marketplace/code/my-first-plugin
-```
-
-### Option B: Local Development
-
-Clone and link for local development:
-
-```bash
-# Clone your marketplace
-git clone https://github.com/your-org/your-marketplace.git
-
-# Link for local use
-cd your-marketplace
-claude plugin link code/my-first-plugin
-```
-
-## Adding More Components
-
-### Commands
-
-Commands are slash commands users can invoke:
-
-```bash
-mkdir -p code/my-plugin/commands
-cat > code/my-plugin/commands/example.md << 'EOF'
----
-name: example
-description: Example command
----
-
-Command implementation here.
-EOF
-```
-
-### Skills
-
-Skills provide instructional content:
-
-```bash
-mkdir -p code/my-plugin/skills
-cat > code/my-plugin/skills/example-skill.md << 'EOF'
----
-name: example-skill
-description: Example skill
----
-
-Skill content here.
-EOF
-```
-
-### Agents
-
-Agents are autonomous subagents:
-
-```bash
-mkdir -p code/my-plugin/agents
-cat > code/my-plugin/agents/example-agent.md << 'EOF'
----
-name: example-agent
-description: Example agent
-color: blue
----
-
-Agent system prompt here.
-EOF
-```
-
-### Hooks
-
-Hooks respond to events:
-
-```bash
-mkdir -p code/my-plugin/hooks
-cat > code/my-plugin/hooks/hooks.json << 'EOF'
-{
-  "hooks": [
-    {
-      "event": "PreToolUse",
-      "filter": {"toolName": "Bash"},
-      "action": {
-        "type": "prompt",
-        "prompt": "Before running bash commands, check for destructive operations."
-      }
-    }
-  ]
-}
-EOF
-```
-
-## Validation and Testing
-
-### Local Validation
-
-Before pushing, validate your components:
-
-```bash
-# Clone the bc-github-actions repo
-git clone https://github.com/bitcomplete/bc-github-actions.git
-
-# Run validation
-cd your-marketplace
-../bc-github-actions/scripts/dist/discover-components.cjs validate
-```
-
-### Common Validation Errors
-
-**Error: Component name doesn't match pattern**
-```
-Fix: Use kebab-case: my-component (not myComponent or my_component)
-```
-
-**Error: Description too short**
-```
-Fix: Add a meaningful description (min 10 characters)
-```
-
-**Error: Missing required fields**
-```
-Fix: Ensure frontmatter has name and description
-```
-
-## Customization
-
-### Change Naming Convention
-
-Edit `.claude-plugin/generator.config.toml`:
-
-```toml
-# For snake_case
-naming_pattern = "^[a-z0-9]+(_[a-z0-9]+)*$"
-
-# For camelCase
-naming_pattern = "^[a-z][a-zA-Z0-9]*$"
-```
-
-### Disable Auto-Merge
-
-Edit `.github/workflows/agentic-marketplace.yml`:
-
-```yaml
-jobs:
-  update:
-    uses: bitcomplete/bc-github-actions/.github/workflows/agentic-marketplace.yml@v1
-    with:
-      config-path: .claude-plugin/generator.config.toml
-      auto-merge: false  # Add this line
-    secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### Add Custom Validation
-
-Create a separate workflow for custom validation:
-
-```yaml
-name: Custom Validation
-
-on:
-  pull_request:
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: bitcomplete/bc-github-actions/agentic-marketplace/validate@v1
-        id: validate
-        with:
-          fail-on-error: false
-
-      - name: Custom checks
-        if: steps.validate.outputs.valid == 'false'
-        run: |
-          echo "Custom validation logic here"
-```
-
-## Troubleshooting
-
-### Workflow Not Running
-
-Check:
-- Workflow file is in `.github/workflows/`
-- File has `.yml` extension
-- Syntax is valid YAML
-
-### No Components Discovered
-
-Check:
-- Plugin structure is `category/plugin-name/`
-- Component files have YAML frontmatter
-- `plugin_categories` in config matches your directories
-
-### Validation Failing
-
-Check:
-- Component names use kebab-case (or your configured pattern)
-- All components have name and description
-- Description length is within bounds (10-200 characters)
-
-### PR Not Auto-Merging
-
-Check:
-- Repository settings allow auto-merge
-- No required reviews or status checks blocking
-- Branch protection rules don't prevent auto-merge
-
-## Next Steps
-
-- Read the [full documentation](agentic-marketplace/README.md)
-- Check [example workflows](https://github.com/bitcomplete/bc-llm-skills)
-- Explore [advanced usage patterns](agentic-marketplace/README.md#advanced-usage)
-
-## Getting Help
-
-- Open an issue: https://github.com/bitcomplete/bc-github-actions/issues
-- Check examples: https://github.com/bitcomplete/bc-llm-skills

From 1f924471f04dda6b6b0eeb978dc6c7c9799b96e9 Mon Sep 17 00:00:00 2001
From: terra tauri <me@terratauri.com>
Date: Sun, 1 Feb 2026 23:36:41 -0800
Subject: [PATCH 7/7] fix: remove getting started links

---
 README.md                     | 2 --
 agentic-marketplace/README.md | 2 --
 2 files changed, 4 deletions(-)

diff --git a/README.md b/README.md
index 59e3cdb..351c46b 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,6 @@
 
 Reusable GitHub Actions workflows for Claude Code development and Platform Engineering. We use these workflows ourselves, and now you can too.
 
-**[📖 Getting Started Guide →](docs/GETTING_STARTED.md)** - New to agentic marketplaces? Start here!
-
 ## Actions
 
 ### Agentic Marketplace Automation
diff --git a/agentic-marketplace/README.md b/agentic-marketplace/README.md
index b54f6c1..2429837 100644
--- a/agentic-marketplace/README.md
+++ b/agentic-marketplace/README.md
@@ -2,8 +2,6 @@
 
 Automates Claude Code plugin marketplace management through auto-discovery, validation, and synchronization.
 
-**New to agentic marketplaces?** Check out the [Getting Started Guide](../docs/GETTING_STARTED.md) for a step-by-step walkthrough.
-
 ## Overview
 
 The agentic-marketplace action provides three composable actions that work together to manage your Claude Code plugin marketplace: