diff --git a/doc/CLIPHUB.md b/doc/CLIPHUB.md new file mode 100644 index 00000000..6a55c325 --- /dev/null +++ b/doc/CLIPHUB.md @@ -0,0 +1,336 @@ +# 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 §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:/ +``` +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:/` 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)