feat(schema): refine and expand extension metadata schema

- Introduce `scope`, `tags`, `min_version`, `homepage`, and `installation` fields for enhanced discoverability and guidance. - Remove `install` and `compatibility` objects, replacing them with a simplified `installation` string field. - Add `examples/` directory with full exemplar files for each extension type. - Update `schema-design.md` to reflect new schema, clarify field definitions, and improve documentation structure.
2026-04-28 04:19:27 +00:00 · 2026-01-12 23:47:06 +00:00 · 2026-01-12 23:47:06 +00:00 · a806755d0f
commit a806755d0f
parent 8f1acd2c7c
9 changed files with 697 additions and 559 deletions
--- a/data/schema.json
+++ b/data/schema.json
@ -8,64 +8,56 @@
    "name": {
      "type": "string",
      "minLength": 1,
-      "description": "Name of the project or tool"
+      "description": "Display name of the project or tool"
    },
    "repo": {
      "type": "string",
      "format": "uri",
-      "description": "URL to the repository"
+      "description": "URL to the repository (https://github.com/...)"
    },
-"tagline": {
+    "tagline": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
-      "description": "Short punchy summary of the project (shown in collapsed view)"
+      "description": "Short punchy summary (shown in collapsed view)"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Full description of the project (shown when expanded)"
    },
-    "install": {
-      "type": "object",
-      "description": "Installation instructions",
-      "properties": {
-        "type": {
-          "type": "string",
-          "enum": ["config", "npm", "pip", "go", "script", "manual"],
-          "description": "Type of installation method"
-        }
+    "scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["global", "project"]
      },
-      "required": ["type"],
-      "additionalProperties": false
-    },
-    "compatibility": {
-      "type": "object",
-      "description": "Compatibility information",
-      "properties": {
-        "platforms": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Supported platforms"
-        },
-        "opencode": {
-          "type": "string",
-          "description": "Compatible Opencode version"
-        }
-      },
-      "required": ["platforms", "opencode"],
-      "additionalProperties": false
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "Installation scope: global (~/.config/opencode/) or project (.opencode/). Defaults to [global] if omitted."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
-      "description": "Tags for categorization"
+      "description": "Tags for filtering and discoverability"
+    },
+    "min_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+",
+      "description": "Minimum OpenCode version required (semver format, e.g. '1.0.0')"
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Documentation URL if different from repository"
+    },
+    "installation": {
+      "type": "string",
+      "description": "Detailed installation instructions in markdown format"
    }
  },
  "required": ["name", "repo", "tagline", "description"],
-  "additionalProperties": false
+  "additionalProperties": true
 }
--- a/docs/schema-design.md
+++ b/docs/schema-design.md
@ -1,7 +1,5 @@
 # OpenCode Extension Schema Design

-> **Working Document** - This document serves as both a planning guide for implementation and a precursor to official documentation. Content may evolve as implementation progresses.
-
 This document describes the YAML schema for the awesome-opencode registry, a data-driven catalog of OpenCode extensions. It covers extension types, configuration locations, schema fields, and downstream compatibility.

 ---
@ -15,7 +13,8 @@ The awesome-opencode registry is a curated collection of extensions that enhance
 - **Human Readable**: YAML format ensures contributors can easily read and edit entries
 - **Downstream Ready**: Schema designed for seamless consumption by platforms like opencode.cafe
 - **Discoverable**: Tags and metadata support filtering and search
- **Scope-Aware**: Clear distinction between global and project-level installations
+- **Extensible**: Schema allows additional fields for future enhancements
+- **Type by Location**: Extension type is derived from directory, not stored in YAML

 ### Directory Structure

@ -34,6 +33,8 @@ awesome-opencode/
 │   │   └── *.yaml       # Guides, configs, MCP servers, tools, commands
 │   └── forks/
 │       └── *.yaml
+├── examples/
+│   └── *.yaml           # Exemplar files showing all fields
 └── docs/
    └── schema-design.md
 ```
@ -191,102 +192,91 @@ If `scope` is set to `[global, project]` and both global and project configs def

 ---

-## 4. Current YAML Schema
+## 4. YAML Schema

-The current awesome-opencode entries use a minimal schema focused on core metadata.
+The awesome-opencode registry uses a flexible schema with four required fields and several optional fields for enhanced discoverability.

-### Current Required Fields
+### Required Fields

 | Field | Type | Description |
 |-------|------|-------------|
 | `name` | string | Display name for the extension (human-readable) |
 | `repo` | string | Repository URL (HTTPS format, e.g., `https://github.com/user/repo`) |
-| `description` | string | Short description (max 100 characters) |
+| `tagline` | string | Short punchy summary, max 120 characters |
+| `description` | string | Full description (can be multi-line) |

-### Current Optional Fields
+### Optional Fields

-| Field | Type | Description |
-|-------|------|-------------|
-| `full_description` | string | Extended explanation of functionality |
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `scope` | array | `[global]` | Installation scope: `[global]`, `[project]`, or `[global, project]` |
+| `tags` | array | `[]` | Strings for filtering and discoverability |
+| `min_version` | string | - | Minimum OpenCode version required (semver, e.g., `"1.0.0"`) |
+| `homepage` | string | - | Documentation URL if different from repository |
+| `installation` | string | - | Detailed installation instructions (markdown format) |

-### Example (Current Format)
+### Type Derivation
+
+Extension type is **not stored in YAML** - it's derived from the directory location:
+
+| Directory | Type |
+|-----------|------|
+| `data/plugins/` | `plugin` |
+| `data/themes/` | `theme` |
+| `data/agents/` | `agent` |
+| `data/projects/` | `project` |
+| `data/resources/` | `resource` |
+| `data/forks/` | `fork` |
+
+### Minimal Valid Entry

 ```yaml
-name: CodeGPT
-repo: https://github.com/company/codegpt
-tagline: AI-powered code completion and refactoring
-description: |
-  CodeGPT provides intelligent code completion using GPT models.
-  Features include:
-  - Real-time suggestions
-  - Context-aware refactoring
-  - Multi-language support
+name: My Extension
+repo: https://github.com/user/my-extension
+tagline: A brief description of what this does
+description: A longer explanation of the extension.
 ```

---
-
-## 5. Proposed Schema Additions
-
-The following fields are being added to enhance discoverability, installation guidance, and downstream compatibility.
-
-### New Required Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | enum | Extension type: `plugin`, `theme`, `agent`, `project`, `resource`, or `fork` |
-| `scope` | array | Installation scope: `[global]`, `[project]`, or `[global, project]` |
-
-### New Optional Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `tags` | array | Strings for filtering and discoverability (e.g., `["ai", "productivity"]`) |
-| `min_version` | string | Minimum OpenCode version required (e.g., `"1.0.0"`) |
-| `homepage` | string | Documentation URL if different from repository |
-| `installation` | markdown | Detailed installation instructions |
-
-### Example (Proposed Format)
+### Complete Entry (All Fields)

 ```yaml
-name: CodeGPT
-repo: https://github.com/company/codegpt
-type: plugin
-scope: [global, project]
-tagline: AI-powered code completion and refactoring
+name: My Extension
+repo: https://github.com/user/my-extension
+tagline: A brief tagline (max 120 chars)
 description: |
-  CodeGPT provides intelligent code completion using GPT models.
-  Features include:
-  - Real-time suggestions
-  - Context-aware refactoring
-  - Multi-language support
+  A longer description explaining
+  the extension in detail.
+scope:
+  - global
+  - project
 tags:
-  - ai
-  - completion
  - productivity
+  - ai
 min_version: "1.0.0"
-homepage: https://codegpt.dev/docs
+homepage: https://example.com/docs
 installation: |
-  ## Prerequisites
-  - OpenCode 1.0.0 or later
-  - Node.js 18+ for local plugins
-
  ## Installation
-  ### Global
-  1. Run `opencode install codegpt`
-  2. Restart OpenCode
-
-  ## Configuration
-  Add to `opencode.json`:
-  ```json
-  {
-    "plugins": ["codegpt"]
-  }
+  ```bash
+  git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension
  ```
 ```

+### Examples Directory
+
+Full exemplar files for each extension type are available in `examples/`:
+
+| Type | Example File |
+|------|-------------|
+| Plugin | `examples/plugin.yaml` |
+| Theme | `examples/theme.yaml` |
+| Agent | `examples/agent.yaml` |
+| Project | `examples/project.yaml` |
+| Resource | `examples/resource.yaml` |
+| Fork | `examples/fork.yaml` |
+
 ---

-## 6. Installation Template
+## 5. Installation Template

 The `installation` field uses a structured template that contributors fill in. Not all sections are required—include what's relevant for the extension.

@ -338,7 +328,7 @@ How to uninstall the extension

 ---

-## 7. Downstream Compatibility
+## 6. Downstream Compatibility

 The awesome-opencode schema is designed for seamless conversion to downstream platforms like opencode.cafe.

@ -348,23 +338,15 @@ The awesome-opencode schema is designed for seamless conversion to downstream pl
 |-----------------------|-------------------|-------|
 | `name` | `displayName` | Display name for UI |
 | `repo` | `repoUrl` | Repository URL |
-| `description` | `description` | Short description |
-| `type` | `type` | Mapped directly (see below) |
+| `tagline` | `tagline` | Short summary |
+| `description` | `description` | Full description |
+| (directory) | `type` | Derived from directory path |
+| (filename) | `productId` | Derived from filename |
+| `scope` | `scope` | Defaults to `["global"]` |
 | `tags` | `tags` | Array of strings |
 | `homepage` | `homepageUrl` | Documentation URL |
 | `installation` | `installation` | Markdown content |
-| (filename) | `productId` | Derived from filename |
-
-### Type Mapping
-
-| awesome-opencode Type | opencode.cafe Type |
-|-----------------------|-------------------|
-| `plugin` | `plugin` |
-| `theme` | `theme` |
-| `agent` | `agent` |
-| `project` | `project` |
-| `resource` | `resource` |
-| `fork` | `fork` |
+| `min_version` | `minVersion` | Semver string |

 ### Conversion Example

@ -373,9 +355,8 @@ The awesome-opencode schema is designed for seamless conversion to downstream pl
 ```yaml
 name: CodeGPT
 repo: https://github.com/company/codegpt
-type: plugin
-scope: [global, project]
 tagline: AI-powered code completion
+description: Intelligent code completion using GPT models.
 ```

 **JSON Output (opencode.cafe format):**
@ -383,22 +364,25 @@ tagline: AI-powered code completion
 ```json
 {
  "productId": "codegpt",
+  "type": "plugin",
  "displayName": "CodeGPT",
  "repoUrl": "https://github.com/company/codegpt",
-  "type": "plugin",
  "tagline": "AI-powered code completion",
-  "tags": [],
-  "installation": ""
+  "description": "Intelligent code completion using GPT models.",
+  "scope": ["global"],
+  "tags": []
 }
 ```

+Note: `type` is derived from `data/plugins/` → `plugin`, and `productId` from filename `codegpt.yaml` → `codegpt`.
+
 ---

-## 8. Future Vision
+## 7. Future Vision

 This section outlines planned features and improvements for the awesome-opencode ecosystem.

-### 8.1 Agent-Powered Plugin Manager
+### 7.1 Agent-Powered Plugin Manager

 A future plugin/agent that uses the `installation` markdown as context to assist with setup. The agent would:
 - Parse the installation instructions
@ -408,7 +392,7 @@ A future plugin/agent that uses the `installation` markdown as context to assist

 This is **not** an automated CLI executor - it's an AI assistant with context about how to install the extension.

-### 8.2 Interactive TUI with Scope Selection
+### 7.2 Interactive TUI with Scope Selection

 A terminal UI that:
 - Reads the `scope` field to present appropriate options
@ -427,485 +411,137 @@ A terminal UI that:
 └─────────────────────────────────────────┘
 ```

-### 8.3 Automatic Backup and Restore
+### 7.3 Automatic Backup and Restore

 When an agent assists with installation, it can:
 - Read the "Files Modified" section to know what to backup
 - Store backups before making changes
 - Enable clean removal with rollback capability

-### 8.4 Export and Sync Scripts
-
-Scripts to export the registry for downstream platforms:
-
-```bash
-# Export to opencode.cafe JSON format
-./scripts/export-json.sh
-
-# Export to custom format
-./scripts/export.sh --format=custom --output=dist/
-```
-
-### 8.5 Contributing Workflow
+### 7.4 Contributing Workflow Improvements

 Future improvements to the contribution process:

 1. **Schema Validation**: CI checks YAML validity and required fields
 2. **Preview Tool**: Generate opencode.cafe JSON preview for PRs
-3. **Category Detection**: Auto-suggest category based on `type` field
-4. **Link Checking**: Verify `repo` and `homepage` URLs are accessible
+3. **Link Checking**: Verify `repo` and `homepage` URLs are accessible

 ---

-## Appendix A: Quick Reference
+## 8. Quick Reference

 ### Extension Type to Directory Mapping

-| Type | Directory | File Extension |
-|------|-----------|----------------|
-| `plugin` | `data/plugins/` | `.yaml` |
-| `theme` | `data/themes/` | `.yaml` |
-| `agent` | `data/agents/` | `.yaml` |
-| `project` | `data/projects/` | `.yaml` |
-| `resource` | `data/resources/` | `.yaml` |
-| `fork` | `data/forks/` | `.yaml` |
+| Type | Directory |
+|------|-----------|
+| `plugin` | `data/plugins/` |
+| `theme` | `data/themes/` |
+| `agent` | `data/agents/` |
+| `project` | `data/projects/` |
+| `resource` | `data/resources/` |
+| `fork` | `data/forks/` |

 ### Minimal Valid Entry

 ```yaml
 name: My Extension
 repo: https://github.com/user/my-extension
-type: plugin
-scope: [global]
 tagline: A brief description
+description: A longer explanation of what this extension does.
 ```

 ### Complete Entry (All Fields)

+See `examples/` directory for full exemplar files.
+
 ```yaml
 name: My Extension
 repo: https://github.com/user/my-extension
-type: plugin
-scope: [global, project]
-tagline: A brief tagline (≤120 chars)
+tagline: A brief tagline (max 120 chars)
 description: |
  A longer description explaining
  the extension in detail.
+scope:
+  - global
+  - project
 tags:
  - productivity
  - ai
 min_version: "1.0.0"
-homepage: https://user.dev/docs
+homepage: https://example.com/docs
 installation: |
  ## Installation
-  Run `opencode install my-extension`
+  ```bash
+  git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension
+  ```
 ```

---
+### Commands

-## 9. Implementation Plan: Schema Additions
-
-**Created**: 2026-01-11
-**Last Updated**: 2026-01-11
-**Status**: planning
-
-This section provides a phased implementation plan for adding the new schema fields (`type`, `scope`, `tags`, `min_version`, `homepage`, `installation`) to the awesome-opencode registry.
-
---
-
-### Current State Overview
-
-| Component | Status |
-|-----------|--------|
-| YAML entries (61 files) | Existing, uses basic schema |
-| JSON schema (`data/schema.json`) | Out of sync with proposed fields |
-| Generation script (`scripts/generate-readme.js`) | Needs update for new fields |
-| Validation script (`scripts/validate.js`) | Needs update for new fields |
-| Contributing guide (`contributing.md`) | Needs documentation update |
-
---
-
-### Phase 1: Schema Update
-**Goal**: Update `data/schema.json` with new fields
-
-#### Phase 1 Deliverables
- [ ] JSON schema validates new `type` field (required enum)
- [ ] JSON schema validates new `scope` field (required array)
- [ ] JSON schema validates new optional fields (`tags`, `min_version`, `homepage`, `installation`)
- [ ] Validation script runs without errors
-
-#### Phase 1 Tasks
-
- [ ] **Task 1.1**: Add `type` field as required enum
-  - [ ] Open `data/schema.json` and read current structure
-  - [ ] Add `type` property with enum values: `plugin`, `theme`, `agent`, `project`, `resource`, `fork`
-  - [ ] Set `type` to required in schema
-  - [ ] Add description for each enum value
-
- [ ] **Task 1.2**: Add `scope` field as required array
-  - [ ] Add `scope` property with items enum: `global`, `project`
-  - [ ] Set `minItems: 1` (at least one scope required)
-  - [ ] Set `uniqueItems: true` (no duplicates)
-  - [ ] Set `scope` to required in schema
-
- [ ] **Task 1.3**: Add `tags` field as optional string array
-  - [ ] Add `tags` property with type `array` of `string`
-  - [ ] Leave `tags` as optional (not in required array)
-
- [ ] **Task 1.4**: Add `min_version` field as optional string
-  - [ ] Add `min_version` property with type `string`
-  - [ ] Add semver regex pattern for validation
-  - [ ] Leave `min_version` as optional
-
- [ ] **Task 1.5**: Add `homepage` field as optional URL
-  - [ ] Add `homepage` property with type `string`
-  - [ ] Add URI format pattern (http/https)
-  - [ ] Leave `homepage` as optional
-
- [ ] **Task 1.6**: Add `installation` field as optional markdown
-  - [ ] Add `installation` property with type `string`
-  - [ ] Add description indicating markdown format
-  - [ ] Leave `installation` as optional
-
- [ ] **Task 1.7**: Validate schema structure
-  - [ ] Run `node scripts/validate.js` to check schema validity
-  - [ ] Fix any JSON syntax errors
-  - [ ] Verify schema against JSON Schema specification
-
-#### Phase 1 Manual Testing
-**Testing Requirements**: User performs hands-on testing in terminal
-
- [ ] Run validation script: `node scripts/validate.js`
- [ ] Verify schema loads without errors
- [ ] Check that new fields are recognized in validation output
- [ ] Test with a sample YAML file containing new fields
-
-#### Phase 1 Review Process
-**User Review Required**: Do NOT proceed to Phase 2 without user sign-off
-
-**Review Checklist**:
- [ ] Schema validates without errors
- [ ] All new field types are correct (required vs optional)
- [ ] Enum values match documented extension types
- [ ] User approves proceeding to next phase
-
-**Go/No-Go Decision**: [_______] (User fills in date and sign-off)
- [ ] **GO** - Proceed to Phase 2
- [ ] **NO-GO** - Fix issues first
-
-**Issues to Fix**:
- [ ] Issue 1: [Description]
- [ ] Issue 2: [Description]
-
---
-
-### Phase 2: Migrate Existing Entries
-**Goal**: Add new required fields (`type`, `scope`) to all 61 YAML entries
-
-#### Phase 2 Deliverables
- [ ] All 61 YAML entries have `type` field
- [ ] All 61 YAML entries have `scope` field
- [ ] Validation passes for all entries
-
-#### Phase 2 Tasks
-
- [ ] **Task 2.1**: Map category folders to extension types
-  - [ ] `data/plugins/` → `type: plugin`
-  - [ ] `data/themes/` → `type: theme`
-  - [ ] `data/agents/` → `type: agent`
-  - [ ] `data/projects/` → `type: project`
-  - [ ] `data/resources/` → `type: resource`
-  - [ ] `data/forks/` → `type: fork`
-
- [ ] **Task 2.2**: Add `type` field to all entries
-  - [ ] Use `grep` to find all YAML files in `data/` subdirectories
-  - [ ] For each file in `data/plugins/`, add `type: plugin` after `description`
-  - [ ] For each file in `data/themes/`, add `type: theme`
-  - [ ] Continue for all category folders (use edit with replaceAll for efficiency)
-  - [ ] Verify files were modified correctly
-
- [ ] **Task 2.3**: Add `scope` field to all entries
-  - [ ] Add `scope: [global, project]` to all entries (most extensions work both places)
-  - [ ] Consider special cases:
-    - Themes: May be `[global]` only
-    - Resources: May vary based on content type
-  - [ ] Add appropriate scope based on extension type analysis
-
- [ ] **Task 2.4**: Run validation on all entries
-  - [ ] Execute `node scripts/validate.js`
-  - [ ] Fix any entries that fail validation
-  - [ ] Re-run validation until all 61 entries pass
-
-#### Phase 2 Manual Testing
-**Testing Requirements**: User verifies migration was successful
-
- [ ] Check 3-5 random YAML files for correct `type` field
- [ ] Check 3-5 random YAML files for correct `scope` field
- [ ] Run `node scripts/validate.js` and verify all entries pass
- [ ] Confirm count: 61 entries should be valid
-
-#### Phase 2 Review Process
-**User Review Required**: Do NOT proceed to Phase 3 without user sign-off
-
-**Review Checklist**:
- [ ] All YAML files have `type` field matching their directory
- [ ] All YAML files have `scope` field
- [ ] Validation script shows 61 valid entries
- [ ] No schema validation errors
- [ ] User approves proceeding to next phase
-
-**Go/No-Go Decision**: [_______] (User fills in date and sign-off)
- [ ] **GO** - Proceed to Phase 3
- [ ] **NO-GO** - Fix issues first
-
-**Issues to Fix**:
- [ ] Issue 1: [Description]
- [ ] Issue 2: [Description]
-
---
-
-### Phase 3: Update Generation Script
-**Goal**: Update `scripts/generate-readme.js` to use new fields
-
-#### Phase 3 Deliverables
- [ ] Template includes new fields in output
- [ ] Backwards compatibility maintained (optional fields can be missing)
- [ ] README regenerates successfully
-
-#### Phase 3 Tasks
-
- [ ] **Task 3.1**: Update README template
-  - [ ] Open `templates/README.template.md`
-  - [ ] Add badges or labels for `type` field (e.g., "[plugin]", "[theme]")
-  - [ ] Add tags display section if `tags` field is present
-  - [ ] Ensure template handles missing optional fields gracefully
-
- [ ] **Task 3.2**: Update generation script logic
-  - [ ] Open `scripts/generate-readme.js`
-  - [ ] Ensure script reads new fields from YAML entries
-  - [ ] Add logic to skip optional fields if empty/missing
-  - [ ] Add type badges to extension listing output
-
- [ ] **Task 3.3**: Regenerate README
-  - [ ] Run `node scripts/generate-readme.js`
-  - [ ] Check `README.md` for new field displays
-  - [ ] Verify backwards compatibility (entries without optional fields render correctly)
-  - [ ] Check that type badges appear correctly
-
-#### Phase 3 Manual Testing
-**Testing Requirements**: User verifies README output
-
- [ ] Open `README.md` and verify type badges are visible
- [ ] Check that entries with tags display them
- [ ] Verify entries without optional fields render without errors
- [ ] Review README for formatting issues
-
-#### Phase 3 Review Process
-**User Review Required**: Do NOT proceed to Phase 4 without user sign-off
-
-**Review Checklist**:
- [ ] New fields appear in generated README
- [ ] Backwards compatibility works (no breaking changes)
- [ ] Formatting looks correct (badges, tags, etc.)
- [ ] User approves proceeding to next phase
-
-**Go/No-Go Decision**: [_______] (User fills in date and sign-off)
- [ ] **GO** - Proceed to Phase 4
- [ ] **NO-GO** - Fix issues first
-
-**Issues to Fix**:
- [ ] Issue 1: [Description]
- [ ] Issue 2: [Description]
-
---
-
-### Phase 4: Update Contributing Guide
-**Goal**: Document new fields in `contributing.md`
-
-#### Phase 4 Deliverables
- [ ] Contributing guide includes complete YAML format reference
- [ ] All new fields documented with examples
- [ ] Type and scope options documented
-
-#### Phase 4 Tasks
-
- [ ] **Task 4.1**: Update `contributing.md` with new required fields
-  - [ ] Open `contributing.md`
-  - [ ] Add `type` field to YAML format reference
-  - [ ] Add `scope` field to YAML format reference
-  - [ ] Mark these as **required** fields
-
- [ ] **Task 4.2**: Add installation template example
-  - [ ] Add `installation` field documentation
-  - [ ] Include markdown example with all sections
-  - [ ] Mark `installation` as **optional**
-
- [ ] **Task 4.3**: Document type and scope options
-  - [ ] Add section listing all valid `type` values with descriptions
-  - [ ] Add section explaining `scope` values (`global`, `project`, `[global, project]`)
-  - [ ] Add `tags`, `min_version`, `homepage` documentation
-
-#### Phase 4 Manual Testing
-**Testing Requirements**: User reviews documentation
-
- [ ] Open `contributing.md` and verify new sections are present
- [ ] Check that YAML examples are valid
- [ ] Verify field descriptions match schema
- [ ] Test that documentation is clear for new contributors
-
-#### Phase 4 Review Process
-**User Review Required**: Do NOT proceed to Phase 5 without user sign-off
-
-**Review Checklist**:
- [ ] All new fields documented in contributing guide
- [ ] Examples are accurate and complete
- [ ] Required vs optional fields clearly marked
- [ ] User approves proceeding to next phase
-
-**Go/No-Go Decision**: [_______] (User fills in date and sign-off)
- [ ] **GO** - Proceed to Phase 5
- [ ] **NO-GO** - Fix issues first
-
-**Issues to Fix**:
- [ ] Issue 1: [Description]
- [ ] Issue 2: [Description]
-
---
-
-### Phase 5: Export Script (Future)
-**Goal**: Create script for downstream JSON export
-
-#### Phase 5 Deliverables
- [ ] `scripts/export-json.js` script created
- [ ] Script outputs opencode.cafe compatible JSON
- [ ] Field mapping documented
-
-#### Phase 5 Tasks
-
- [ ] **Task 5.1**: Create export script
-  - [ ] Create `scripts/export-json.js`
-  - [ ] Load all YAML entries from `data/` directories
-  - [ ] Map fields according to downstream compatibility table (Section 7):
-    - `name` → `displayName`
-    - `repo` → `repoUrl`
-    - `type` → `type` (direct map)
-    - `tags` → `tags`
-    - `homepage` → `homepageUrl`
-    - `installation` → `installation`
-    - filename → `productId`
-
- [ ] **Task 5.2**: Generate productId from filename
-  - [ ] Extract filename without extension (e.g., `codegpt.yaml` → `codegpt`)
-  - [ ] Use as `productId` in output JSON
-
- [ ] **Task 5.3**: Test export output
-  - [ ] Run `node scripts/export-json.js`
-  - [ ] Verify output is valid JSON array
-  - [ ] Check that field mapping is correct
-  - [ ] Validate against opencode.cafe schema (if available)
-
-#### Phase 5 Manual Testing
-**Testing Requirements**: User verifies export script
-
- [ ] Run `node scripts/export-json.js` > dist/output.json
- [ ] Verify output is valid JSON
- [ ] Check 2-3 entries for correct field mapping
- [ ] Verify `productId` is derived from filename
-
-#### Phase 5 Review Process
-**User Review Required**: Phase 5 completion is optional (future enhancement)
-
-**Review Checklist**:
- [ ] Export script runs successfully
- [ ] Output JSON is valid
- [ ] Field mapping matches specification
- [ ] User approves Phase 5 completion
-
-**Go/No-Go Decision**: [_______] (User fills in date and sign-off)
- [ ] **GO** - Phase 5 complete
- [ ] **NO-GO** - Fix issues first
-
-**Issues to Fix**:
- [ ] Issue 1: [Description]
- [ ] Issue 2: [Description]
-
---
-
-### Important Notes
-
-#### What NOT To Do
- **DO NOT run `npm install`** - The project may have existing dependencies; only run if explicitly instructed
- **DO NOT push changes to remote** - Always ask user before committing or pushing
- **DO NOT modify unrelated files** - Stay within the scope of this implementation plan
- **DO NOT delete existing data** - Back up or migrate data, never remove without confirmation
- **DO NOT change existing field behavior** - Only add new fields, don't modify existing ones
-
-#### Commands to Use
 ```bash
 # Validate schema and entries
 node scripts/validate.js

 # Regenerate README
 node scripts/generate-readme.js
-
-# Export JSON (Phase 5)
-node scripts/export-json.js
 ```

-#### File Locations
- Schema: `data/schema.json`
- YAML entries: `data/{category}/*.yaml`
- Generation script: `scripts/generate-readme.js`
- Validation script: `scripts/validate.js`
- Template: `templates/README.template.md`
- Contributing guide: `contributing.md`
- Export script: `scripts/export-json.js` (to be created)
+---
+
+## 9. Future Work
+
+Remaining tasks for the awesome-opencode registry.
+
+### 9.1 Update Contributing Guide
+
+Update `contributing.md` to:
+- Reference `examples/` directory for full field documentation
+- Document optional fields (`scope`, `tags`, `min_version`, `homepage`, `installation`)
+- Explain scope behavior and defaults
+
+### 9.2 README Generation Enhancements (Optional)
+
+Update `scripts/generate-readme.js` to optionally display:
+- Tags for entries that have them
+- Scope indicators
+- Type badges derived from directory
+
+### 9.3 Export Script for Downstream Platforms
+
+Create `scripts/export-json.js` to generate JSON for platforms like opencode.cafe:
+
+```javascript
+// Pseudocode
+for each file in data/{category}/*.yaml:
+  entry = parseYAML(file)
+  entry.type = category           // derived from directory
+  entry.productId = filename      // derived from filename
+  output.push(mapFields(entry))
+writeJSON(output)
+```
+
+**Field mapping:**
+| YAML | JSON Output |
+|------|-------------|
+| `name` | `displayName` |
+| `repo` | `repoUrl` |
+| `tagline` | `tagline` |
+| `description` | `description` |
+| (directory) | `type` |
+| (filename) | `productId` |
+| `scope` | `scope` (default `["global"]`) |
+| `tags` | `tags` (default `[]`) |
+| `homepage` | `homepageUrl` |
+| `installation` | `installation` |
+| `min_version` | `minVersion` |
+
+**Usage:**
+```bash
+node scripts/export-json.js > dist/registry.json
+node scripts/export-json.js --pretty > dist/registry.json
+```

 ---

-## Success Criteria
-
-### Schema Migration Complete When
- [ ] `data/schema.json` includes all new fields with correct types
- [ ] All 61 YAML entries have `type` and `scope` fields
- [ ] `node scripts/validate.js` passes without errors
- [ ] `node scripts/generate-readme.js` produces valid README with new fields
- [ ] `contributing.md` documents all new fields
-
-### Quality Criteria
- [ ] Backwards compatibility maintained (optional fields can be missing)
- [ ] No breaking changes to existing data
- [ ] TypeScript compilation passes (if applicable)
- [ ] Linting passes (if applicable)
- [ ] All tests passing (if tests exist)
-
---
-
-## Progress Log
-
-**Started**: [Date]
-**Last Updated**: 2026-01-11
-
-### Completed Tasks
- [ ] [Date] Task completed - [Brief description]
- [ ] [Date] Another task completed - [Brief description]
-
-### Issues Encountered
- [Date] Issue description and how it was resolved
- [Date] Another issue and resolution
-
-### Phase Status
- Phase 1: [pending | in_progress | testing | review | completed]
- Phase 2: [pending | in_progress | testing | review | completed]
- Phase 3: [pending | in_progress | testing | review | completed]
- Phase 4: [pending | in_progress | testing | review | completed]
- Phase 5: [pending | in_progress | testing | review | completed] (future)
-
---
-
-**End of Implementation Plan**
-
---
-
-*Document Version: 1.1*  
-*Last Updated: January 2026*
+*Document Version: 1.2*
+*Last Updated: 2026-01-12*
--- a/examples/README.md
+++ b/examples/README.md
@ -0,0 +1,40 @@
+# Examples
+
+This directory contains exemplar YAML files showing the full schema for each extension type.
+
+**These are reference examples, not actual entries.**
+
+## Usage
+
+When adding a new entry to `data/{category}/`, use the corresponding example as a reference:
+
+| Adding to... | Reference |
+|-------------|-----------|
+| `data/plugins/` | [plugin.yaml](plugin.yaml) |
+| `data/themes/` | [theme.yaml](theme.yaml) |
+| `data/agents/` | [agent.yaml](agent.yaml) |
+| `data/projects/` | [project.yaml](project.yaml) |
+| `data/resources/` | [resource.yaml](resource.yaml) |
+| `data/forks/` | [fork.yaml](fork.yaml) |
+
+## Required vs Optional Fields
+
+### Required (all entries must have)
+- `name` - Display name
+- `repo` - Repository URL (https://github.com/...)
+- `tagline` - Short description (max 120 chars)
+- `description` - Full description (can be multi-line)
+
+### Optional (include if relevant)
+- `scope` - Installation scope: `[global]`, `[project]`, or `[global, project]` (defaults to `[global]`)
+- `tags` - Array of strings for filtering
+- `min_version` - Minimum OpenCode version (semver)
+- `homepage` - Documentation URL if different from repo
+- `installation` - Markdown installation instructions
+
+## Notes
+
+- **Type is derived from directory** - No `type` field needed; it's inferred from the folder
+- **Scope is optional** - Defaults to `[global]`; add if project-level install is relevant
+- **Installation is markdown** - Use headers, code blocks, lists as needed
+- **Schema allows additional fields** - Future fields can be added without breaking existing entries
--- a/examples/agent.yaml
+++ b/examples/agent.yaml
@ -0,0 +1,89 @@
+# Example Agent Entry
+# Agents are custom AI configurations and skills for specialized tasks.
+# This category includes both agent configs and reusable skills.
+# Place actual entries in: data/agents/your-agent-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example Security Reviewer
+repo: https://github.com/example/opencode-security-agent
+tagline: AI agent specialized in security code review
+description: |
+  A custom agent configuration for security-focused code review.
+  Includes:
+  - Custom system prompts for security analysis
+  - Predefined tools for vulnerability scanning
+  - Skills for OWASP Top 10 detection
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Scope defines where the extension can be installed (defaults to [global])
+# Agents can be installed globally or per-project
+scope:
+  - global   # ~/.config/opencode/agent/
+  - project  # .opencode/agent/
+
+tags:
+  - security
+  - code-review
+  - agent
+  - skill
+
+min_version: "1.0.0"
+
+homepage: https://example.com/docs/security-agent
+
+installation: |
+  ## Prerequisites
+  - OpenCode 1.0.0 or later
+
+  ## Installation
+
+  ### Global (all projects)
+  ```bash
+  # Copy agent configuration
+  mkdir -p ~/.config/opencode/agent/security-reviewer
+  curl -o ~/.config/opencode/agent/security-reviewer/agent.json \
+    https://raw.githubusercontent.com/example/opencode-security-agent/main/agent.json
+  ```
+
+  ### Project-only
+  ```bash
+  # Copy to project agent directory
+  mkdir -p .opencode/agent/security-reviewer
+  curl -o .opencode/agent/security-reviewer/agent.json \
+    https://raw.githubusercontent.com/example/opencode-security-agent/main/agent.json
+  ```
+
+  ## Installing Skills
+  If this agent includes skills:
+  ```bash
+  # Global skill
+  mkdir -p ~/.config/opencode/skill/security-review
+  curl -o ~/.config/opencode/skill/security-review/SKILL.md \
+    https://raw.githubusercontent.com/example/opencode-security-agent/main/SKILL.md
+  ```
+
+  ## Configuration
+  Add to your `opencode.json`:
+  ```json
+  {
+    "agents": {
+      "security-reviewer": {
+        "enabled": true
+      }
+    }
+  }
+  ```
+
+  ## Files Modified
+  - `~/.config/opencode/agent/security-reviewer/agent.json`
+  - `~/.config/opencode/skill/security-review/SKILL.md` (if using skills)
+
+  ## Removal
+  1. Delete the agent directory
+  2. Remove config entry from `opencode.json`
--- a/examples/fork.yaml
+++ b/examples/fork.yaml
@ -0,0 +1,89 @@
+# Example Fork Entry
+# Forks are modified builds of OpenCode with custom features or patches.
+# Place actual entries in: data/forks/your-fork-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example Enterprise Fork
+repo: https://github.com/example/opencode-enterprise
+tagline: OpenCode fork with enterprise authentication and audit logging
+description: |
+  A fork of OpenCode designed for enterprise environments.
+  
+  Additions:
+  - SAML/SSO authentication
+  - Audit logging for compliance
+  - Custom model routing
+  - Air-gapped deployment support
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Note: Forks don't use 'scope' - they replace the entire OpenCode installation
+
+tags:
+  - enterprise
+  - fork
+  - authentication
+  - audit
+
+min_version: "1.0.0"
+
+homepage: https://example.com/opencode-enterprise
+
+installation: |
+  ## Prerequisites
+  - Go 1.21+ (for building from source)
+  - Or: Docker (for containerized deployment)
+
+  ## Installation from Source
+  ```bash
+  # Clone the fork
+  git clone https://github.com/example/opencode-enterprise
+  cd opencode-enterprise
+
+  # Build
+  go build -o opencode-enterprise ./cmd/opencode
+
+  # Install (replaces standard opencode)
+  sudo mv opencode-enterprise /usr/local/bin/opencode
+  ```
+
+  ## Docker Installation
+  ```bash
+  docker pull example/opencode-enterprise:latest
+  alias opencode='docker run -it --rm \
+    -v ~/.config/opencode:/root/.config/opencode \
+    -v $(pwd):/workspace \
+    example/opencode-enterprise'
+  ```
+
+  ## Configuration
+  Enterprise-specific configuration in `opencode.json`:
+  ```json
+  {
+    "enterprise": {
+      "sso": {
+        "provider": "okta",
+        "domain": "company.okta.com"
+      },
+      "audit": {
+        "enabled": true,
+        "destination": "s3://audit-logs/"
+      }
+    }
+  }
+  ```
+
+  ## Files Modified
+  - `/usr/local/bin/opencode` (replaced binary)
+  - `~/.config/opencode/opencode.json` (enterprise config)
+
+  ## Reverting to Standard OpenCode
+  ```bash
+  # Reinstall standard OpenCode
+  curl -fsSL https://opencode.ai/install | bash
+  ```
--- a/examples/plugin.yaml
+++ b/examples/plugin.yaml
@ -0,0 +1,81 @@
+# Example Plugin Entry
+# Plugins are JS/TS modules that extend OpenCode's core functionality.
+# Place actual entries in: data/plugins/your-plugin-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example Plugin
+repo: https://github.com/example/opencode-example-plugin
+tagline: A brief description of what this plugin does (max 120 chars)
+description: |
+  A longer description explaining the plugin in detail.
+  Can be multiple lines and include:
+  - Feature highlights
+  - Use cases
+  - Key benefits
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Scope defines where the extension can be installed (defaults to [global])
+# Most plugins work in both locations - omit or specify only what's relevant
+scope:
+  - global   # ~/.config/opencode/plugin/
+  - project  # .opencode/plugin/
+
+# Tags for filtering and discoverability
+tags:
+  - productivity
+  - ai
+  - authentication
+
+# Minimum OpenCode version required (semver format)
+min_version: "1.0.0"
+
+# Documentation URL if different from repository
+homepage: https://example.com/docs/opencode-plugin
+
+# Detailed installation instructions (markdown format)
+# Include sections relevant to your plugin
+installation: |
+  ## Prerequisites
+  - OpenCode 1.0.0 or later
+  - Node.js 18+ (for local development)
+
+  ## Installation
+
+  ### Global (all projects)
+  ```bash
+  # Clone to global plugins directory
+  git clone https://github.com/example/opencode-example-plugin ~/.config/opencode/plugin/example-plugin
+  ```
+
+  ### Project-only
+  ```bash
+  # Clone to project plugins directory
+  git clone https://github.com/example/opencode-example-plugin .opencode/plugin/example-plugin
+  ```
+
+  ## Configuration
+  Add to your `opencode.json`:
+  ```json
+  {
+    "plugins": {
+      "example-plugin": {
+        "enabled": true,
+        "option1": "value"
+      }
+    }
+  }
+  ```
+
+  ## Files Modified
+  - `~/.config/opencode/opencode.json` (config entry)
+  - `~/.config/opencode/plugin/example-plugin/` (plugin files)
+
+  ## Removal
+  1. Remove the plugin directory
+  2. Remove the config entry from `opencode.json`
--- a/examples/project.yaml
+++ b/examples/project.yaml
@ -0,0 +1,72 @@
+# Example Project Entry
+# Projects are standalone applications and utilities built for/with OpenCode.
+# These are complete apps, not extensions.
+# Place actual entries in: data/projects/your-project-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example OpenCode Dashboard
+repo: https://github.com/example/opencode-dashboard
+tagline: Web-based dashboard for monitoring OpenCode sessions
+description: |
+  A standalone web application for monitoring and managing
+  OpenCode sessions across multiple projects.
+  
+  Features:
+  - Real-time session monitoring
+  - Token usage analytics
+  - Multi-project overview
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Scope is often not relevant for standalone projects
+# Include only if the project can be installed globally vs per-project
+
+tags:
+  - dashboard
+  - monitoring
+  - web-ui
+  - analytics
+
+min_version: "1.0.0"
+
+homepage: https://example.com/opencode-dashboard
+
+installation: |
+  ## Prerequisites
+  - Node.js 18+
+  - OpenCode 1.0.0 or later
+
+  ## Installation
+  ```bash
+  # Clone the repository
+  git clone https://github.com/example/opencode-dashboard
+  cd opencode-dashboard
+
+  # Install dependencies
+  npm install
+
+  # Start the dashboard
+  npm start
+  ```
+
+  ## Configuration
+  Create a `.env` file:
+  ```bash
+  OPENCODE_LOG_DIR=~/.config/opencode/logs
+  PORT=3000
+  ```
+
+  ## Usage
+  Open `http://localhost:3000` in your browser.
+
+  ## Docker (Alternative)
+  ```bash
+  docker run -p 3000:3000 \
+    -v ~/.config/opencode:/opencode:ro \
+    example/opencode-dashboard
+  ```
--- a/examples/resource.yaml
+++ b/examples/resource.yaml
@ -0,0 +1,80 @@
+# Example Resource Entry
+# Resources include guides, configs, MCP servers, tools, and commands.
+# Place actual entries in: data/resources/your-resource-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example MCP Server
+repo: https://github.com/example/opencode-mcp-database
+tagline: MCP server for database access and querying
+description: |
+  A Model Context Protocol (MCP) server that provides
+  OpenCode with database access capabilities.
+  
+  Supports:
+  - PostgreSQL, MySQL, SQLite
+  - Read-only query execution
+  - Schema introspection
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Scope defines where the extension can be installed (defaults to [global])
+# For MCP servers, scope indicates global vs project-specific config
+scope:
+  - global   # System-wide MCP server
+  - project  # Project-specific database access
+
+tags:
+  - mcp-server
+  - database
+  - postgresql
+  - mysql
+
+min_version: "1.0.0"
+
+homepage: https://example.com/docs/mcp-database
+
+installation: |
+  ## Prerequisites
+  - Node.js 18+
+  - Database connection credentials
+
+  ## Installation
+  ```bash
+  # Install globally via npm
+  npm install -g @example/opencode-mcp-database
+  ```
+
+  ## Configuration
+  Add to your `opencode.json`:
+  ```json
+  {
+    "mcpServers": {
+      "database": {
+        "command": "opencode-mcp-database",
+        "args": ["--connection", "postgresql://localhost/mydb"]
+      }
+    }
+  }
+  ```
+
+  ## Environment Variables
+  Alternatively, configure via environment:
+  ```bash
+  export DATABASE_URL="postgresql://localhost/mydb"
+  ```
+
+  ## Security Notes
+  - Use read-only database credentials
+  - Consider connection pooling for production
+  - Review query permissions carefully
+
+  ## Removal
+  ```bash
+  npm uninstall -g @example/opencode-mcp-database
+  ```
+  Remove the `mcpServers.database` entry from `opencode.json`.
--- a/examples/theme.yaml
+++ b/examples/theme.yaml
@ -0,0 +1,59 @@
+# Example Theme Entry
+# Themes customize the OpenCode editor appearance.
+# Place actual entries in: data/themes/your-theme-name.yaml
+
+# ============================================================================
+# REQUIRED FIELDS
+# ============================================================================
+
+name: Example Dark Theme
+repo: https://github.com/example/opencode-example-theme
+tagline: A beautiful dark theme with vibrant accents
+description: |
+  A dark theme designed for extended coding sessions.
+  Features high contrast syntax highlighting and
+  carefully chosen colors to reduce eye strain.
+
+# ============================================================================
+# OPTIONAL FIELDS
+# ============================================================================
+
+# Scope defines where the extension can be installed (defaults to [global])
+# Themes are typically global-only
+scope:
+  - global   # ~/.config/opencode/themes/
+
+tags:
+  - dark
+  - high-contrast
+  - syntax-highlighting
+
+min_version: "1.0.0"
+
+homepage: https://example.com/themes/dark
+
+installation: |
+  ## Installation
+
+  ### Global
+  ```bash
+  # Download theme JSON
+  curl -o ~/.config/opencode/themes/example-dark.json \
+    https://raw.githubusercontent.com/example/opencode-example-theme/main/theme.json
+  ```
+
+  ## Configuration
+  Add to your `opencode.json`:
+  ```json
+  {
+    "theme": "example-dark"
+  }
+  ```
+
+  ## Files Modified
+  - `~/.config/opencode/themes/example-dark.json`
+  - `~/.config/opencode/opencode.json` (theme reference)
+
+  ## Removal
+  1. Delete `~/.config/opencode/themes/example-dark.json`
+  2. Change `theme` in `opencode.json` to another theme