paperclip/doc/CLIPHUB.md

# ClipHub — The Company Registry

**Download a company.**

ClipHub is the public registry where people share, discover, and download Paperclip company configurations. A company template is a portable artifact containing an entire org — agents, reporting structure, adapter configs, role definitions, seed tasks — ready to spin up with one command.

---

## What It Is

ClipHub is to Paperclip what a package registry is to a programming language. Paperclip already supports exportable org configs (see [SPEC.md](./SPEC.md) §2). ClipHub is the public directory where those exports live.

A user builds a working company in Paperclip — a dev shop, a marketing agency, a research lab, a content studio — exports the template, and publishes it to ClipHub. Anyone can browse, search, download, and spin up that company on their own Paperclip instance.

The tagline: **you can literally download a company.**

---

## What Gets Published

A ClipHub package is a **company template export** — the portable artifact format defined in the Paperclip spec. It contains:

| Component | Description |
|---|---|
| **Company metadata** | Name, description, intended use case, category |
| **Org chart** | Full reporting hierarchy — who reports to whom |
| **Agent definitions** | Every agent: name, role, title, capabilities description |
| **Adapter configs** | Per-agent adapter type and configuration (SOUL.md, HEARTBEAT.md, CLAUDE.md, process commands, webhook URLs — whatever the adapter needs) |
| **Seed tasks** | Optional starter tasks and initiatives to bootstrap the company's first run |
| **Budget defaults** | Suggested token/cost budgets per agent and per company |

Templates are **structure, not state.** No in-progress tasks, no historical cost data, no runtime artifacts. Just the blueprint.

### Sub-packages

Not every use case needs a whole company. ClipHub also supports publishing individual components:

- **Agent templates** — a single agent config (e.g. "Senior TypeScript Engineer", "SEO Content Writer", "DevOps Agent")
- **Team templates** — a subtree of the org chart (e.g. "Marketing Team: CMO + 3 reports", "Engineering Pod: Tech Lead + 4 Engineers")
- **Adapter configs** — reusable adapter configurations independent of any specific agent role

These can be mixed into existing companies. Download an agent, slot it into your org, assign a manager, go.

---

## Core Features

### Browse & Discover

The homepage surfaces companies across several dimensions:

- **Featured** — editorially curated, high-quality templates
- **Popular** — ranked by downloads, stars, and forks
- **Recent** — latest published or updated
- **Categories** — browseable by use case (see Categories below)

Each listing shows: name, short description, org size (agent count), category, adapter types used, star count, download count, and a mini org chart preview.

### Search

Search is **semantic, not keyword-only.** Powered by vector embeddings so you can search by intent:

- "marketing agency that runs facebook ads" → finds relevant company templates even if those exact words aren't in the title
- "small dev team for building APIs" → finds lean engineering orgs
- "content pipeline with writers and editors" → finds content studio templates

Also supports filtering by: category, agent count range, adapter types, star count, recency.

### Company Detail Page

Clicking into a company template shows:

- **Full description** — what this company does, how it operates, what to expect
- **Interactive org chart** — visual tree of every agent with role, title, and capabilities
- **Agent list** — expandable details for each agent (adapter type, config summary, role description)
- **Seed tasks** — the starter initiatives and tasks included
- **Budget overview** — suggested cost structure
- **Install command** — one-line CLI command to download and create
- **Version history** — changelog, semver, previous versions available
- **Community** — stars, comments, forks count

### Install & Fork

Two ways to use a template:

**Install (fresh start):**
```
paperclip install cliphub:<publisher>/<company-slug>
```
Downloads the template and creates a new company in your local Paperclip instance. You add your own API keys, set budgets, customize agents, and hit go.

**Fork:**
Forking creates a copy of the template under your own ClipHub account. You can modify it, republish it as your own variant, and the fork lineage is tracked. This enables evolutionary improvement — someone publishes a marketing agency, you fork it, add a social media team, republish.

### Stars & Comments

- **Stars** — bookmark and signal quality. Star count is a primary ranking signal.
- **Comments** — threaded discussion on each listing. Ask questions, share results, suggest improvements.

### Download Counts & Signals

Every install is counted. The registry tracks:

- Total downloads (all time)
- Downloads per version
- Fork count
- Star count

These signals feed into search ranking and discovery.

---

## Publishing

### Who Can Publish

Anyone with a GitHub account can publish to ClipHub. Authentication is via GitHub OAuth.

### How to Publish

From within Paperclip, export your company as a template, then publish:

```
paperclip export --template my-company
paperclip publish cliphub my-company
```

Or use the web UI to upload a template export directly.

### What You Provide

When publishing, you specify:

| Field | Required | Description |
|---|---|---|
| `slug` | yes | URL-safe identifier (e.g. `lean-dev-shop`) |
| `name` | yes | Display name |
| `description` | yes | What this company does and who it's for |
| `category` | yes | Primary category (see below) |
| `tags` | no | Additional tags for discovery |
| `version` | yes | Semver (e.g. `1.0.0`) |
| `changelog` | no | What changed in this version |
| `readme` | no | Extended documentation (markdown) |
| `license` | no | Usage terms |

### Versioning

Templates use semantic versioning. Each publish creates an immutable version. Users can install any version or default to `latest`. Version history and changelogs are visible on the detail page.

### The `sync` Command

For power users who maintain multiple templates:

```
paperclip cliphub sync
```

Scans your local exported templates and publishes any that are new or updated. Useful for maintaining a portfolio of company templates from a single repo.

---

## Categories

Company templates are organized by use case:

| Category | Examples |
|---|---|
| **Software Development** | Full-stack dev shop, API development team, mobile app studio |
| **Marketing & Growth** | Performance marketing agency, content marketing team, SEO shop |
| **Content & Media** | Content studio, podcast production, newsletter operation |
| **Research & Analysis** | Market research firm, competitive intelligence, data analysis team |
| **Operations** | Customer support org, internal ops team, QA/testing shop |
| **Sales** | Outbound sales team, lead generation, account management |
| **Finance & Legal** | Bookkeeping service, compliance monitoring, financial analysis |
| **Creative** | Design agency, copywriting studio, brand development |
| **General Purpose** | Starter templates, minimal orgs, single-agent setups |

Categories are not exclusive — a template can have one primary category plus tags for cross-cutting concerns.

---

## Moderation & Trust

### Verified Publishers

Publishers who meet certain thresholds (account age, published templates with good signals) earn a verified badge. Verified templates rank higher in search.

### Security Review

Company templates contain adapter configurations, which may include executable commands (process adapter) or webhook URLs (HTTP adapter). The moderation system:

1. **Automated scanning** — checks adapter configs for suspicious patterns (arbitrary code execution, exfiltration URLs, credential harvesting)
2. **Community reporting** — any signed-in user can flag a template. Auto-hidden after multiple reports pending review.
3. **Manual review** — moderators can approve, reject, or request changes

### Account Gating

New accounts have a waiting period before they can publish. This prevents drive-by spam.

---

## Architecture

ClipHub is a **separate service** from Paperclip itself. Paperclip is self-hosted; ClipHub is a hosted registry that Paperclip instances talk to.

### Integration Points

| Layer | Role |
|---|---|
| **ClipHub Web** | Browse, search, discover, comment, star — the website |
| **ClipHub API** | Registry API for publishing, downloading, searching programmatically |
| **Paperclip CLI** | `paperclip install`, `paperclip publish`, `paperclip cliphub sync` — built into Paperclip |
| **Paperclip UI** | "Browse ClipHub" panel in the Paperclip web UI for discovering templates without leaving the app |

### Tech Stack

| Layer | Technology |
|---|---|
| Frontend | React + Vite (consistent with Paperclip) |
| Backend | TypeScript + Hono (consistent with Paperclip) |
| Database | PostgreSQL |
| Search | Vector embeddings for semantic search |
| Auth | GitHub OAuth |
| Storage | Template zips stored in object storage (S3 or equivalent) |

### Data Model (Sketch)

```
Publisher
  id, github_id, username, display_name, verified, created_at

Template
  id, publisher_id, slug, name, description, category,
  tags[], readme, license, created_at, updated_at,
  star_count, download_count, fork_count,
  forked_from_id (nullable)

Version
  id, template_id, version (semver), changelog,
  artifact_url (zip), agent_count, adapter_types[],
  created_at

Star
  id, publisher_id, template_id, created_at

Comment
  id, publisher_id, template_id, body, parent_id (nullable),
  created_at, updated_at

Report
  id, reporter_id, template_id, reason, created_at
```

---

## User Flows

### "I want to start a company"

1. Open ClipHub, browse by category or search "dev shop for building SaaS"
2. Find a template that fits — "Lean SaaS Dev Shop (CEO + CTO + 3 Engineers)"
3. Read the description, inspect the org chart, check the comments
4. Run `paperclip install cliphub:acme/lean-saas-shop`
5. Paperclip creates the company locally with all agents pre-configured
6. Set your API keys, adjust budgets, add your initial tasks
7. Hit go

### "I built something great and want to share it"

1. Build and iterate on a company in Paperclip until it works well
2. Export: `paperclip export --template my-agency`
3. Publish: `paperclip publish cliphub my-agency`
4. Fill in description, category, tags on the web UI
5. Template is live — others can find and install it

### "I want to improve someone else's company"

1. Find a template on ClipHub that's close to what you need
2. Fork it to your account
3. Install your fork locally, modify the org (add agents, change configs, restructure teams)
4. Export and re-publish as your own variant
5. Fork lineage visible on both the original and your version

### "I just need one great agent, not a whole company"

1. Search ClipHub for agent templates: "senior python engineer"
2. Find a well-starred agent config
3. Install just that agent: `paperclip install cliphub:acme/senior-python-eng --agent`
4. Assign it to a manager in your existing company
5. Done

---

## Relationship to Paperclip

ClipHub is **not required** to use Paperclip. You can build companies entirely from scratch without ever touching ClipHub. But ClipHub dramatically lowers the barrier to entry:

- **New users** get a working company in minutes instead of hours
- **Experienced users** share proven configurations with the community
- **The ecosystem** compounds — every good template makes the next company easier to build

ClipHub is to Paperclip what a package registry is to a language runtime: optional, but transformative.

---

## V1 Scope

### Must Have

- [ ] Template publishing (upload via CLI or web)
- [ ] Template browsing (list, filter by category)
- [ ] Template detail page (description, org chart, agent list, install command)
- [ ] Semantic search (vector embeddings)
- [ ] `paperclip install cliphub:<publisher>/<slug>` CLI command
- [ ] GitHub OAuth authentication
- [ ] Stars
- [ ] Download counts
- [ ] Versioning (semver, version history)
- [ ] Basic moderation (community reporting, auto-hide)

### V2

- [ ] Comments / threaded discussion
- [ ] Forking with lineage tracking
- [ ] Agent and team sub-packages
- [ ] Verified publisher badges
- [ ] Automated security scanning of adapter configs
- [ ] "Browse ClipHub" panel in Paperclip web UI
- [ ] `paperclip cliphub sync` for bulk publishing
- [ ] Publisher profiles and portfolios

### Not in Scope

- Paid / premium templates (everything is free and public, at least initially)
- Private registries (may be a future enterprise feature)
- Running companies on ClipHub (it's a registry, not a runtime — consistent with Paperclip's own philosophy)