# CmdForge Collections

Collections are curated groups of tools that can be installed together with a single command.

## Use Cases

1. **Thematic bundles**: "writing-toolkit" with grammar, tone, simplify tools
2. **Application stacks**: "data-science" with json-extract, csv-insights, etc.
3. **Source bundles**: "fabric-text" with all Fabric text processing patterns
4. **Workflow packages**: Tools that work well together for a specific task

## Collection Manifest Format

Collections are defined in the registry repo under `collections/`:

```yaml
# collections/writing-toolkit.yaml
name: writing-toolkit
display_name: Writing Toolkit
description: Essential tools for writers and editors
icon: pencil  # Optional icon identifier
maintainer: official  # Publisher who maintains this collection

tools:
  - official/fix-grammar
  - official/simplify
  - official/tone-shift
  - official/expand
  - official/proofread

# Optional: version constraints
pinned:
  official/fix-grammar: "^1.0.0"

# Optional: suggested order for documentation
order:
  - official/fix-grammar
  - official/proofread
  - official/simplify
  - official/tone-shift
  - official/expand

tags:
  - writing
  - editing
  - grammar
```

## CLI Usage

```bash
# List available collections
cmdforge collections list

# View collection details
cmdforge collections info writing-toolkit

# Install all tools in a collection
cmdforge collections install writing-toolkit

# Install with version constraints from collection
cmdforge collections install writing-toolkit --pinned
```

## API Endpoints

```
GET  /api/v1/collections              # List all collections
GET  /api/v1/collections/:name        # Get collection details with tool info
GET  /api/v1/collections/:name/tools  # Get just the tools list
```

## Database Schema

```sql
CREATE TABLE collections (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    display_name TEXT NOT NULL,
    description TEXT,
    icon TEXT,
    maintainer TEXT NOT NULL,
    tools TEXT NOT NULL,           -- JSON array of tool refs
    pinned TEXT,                   -- JSON object of version constraints
    tags TEXT,                     -- JSON array
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_collections_name ON collections(name);
CREATE INDEX idx_collections_maintainer ON collections(maintainer);
```

## Web UI

- `/collections` - Browse all collections
- `/collections/:name` - Collection detail page with tool grid
- Install button that shows CLI command
- Filter by tag, maintainer

## Sync from Registry Repo

Collections sync from the registry repo just like tools:

```
CmdForge-Registry/
├── tools/
│   └── ...
└── collections/
    ├── writing-toolkit.yaml
    ├── data-science.yaml
    ├── fabric-text.yaml
    └── fabric-code.yaml
```

The webhook sync process reads `collections/*.yaml` and upserts to database.