docs: add external documentation site content

Add structured documentation covering quickstart, architecture, core
concepts, API reference, adapter guides, CLI commands, deployment
options, and operator/developer guides.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/cli/control-plane-commands.md

@@ -0,0 +1,93 @@
+---
+title: Control-Plane Commands
+summary: Issue, agent, approval, and dashboard commands
+---
+
+# Control-Plane Commands
+
+Client-side commands for managing issues, agents, approvals, and more.
+
+## Issue Commands
+
+```sh
+# List issues
+pnpm paperclip issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
+
+# Get issue details
+pnpm paperclip issue get <issue-id-or-identifier>
+
+# Create issue
+pnpm paperclip issue create --title "..." [--description "..."] [--status todo] [--priority high]
+
+# Update issue
+pnpm paperclip issue update <issue-id> [--status in_progress] [--comment "..."]
+
+# Add comment
+pnpm paperclip issue comment <issue-id> --body "..." [--reopen]
+
+# Checkout task
+pnpm paperclip issue checkout <issue-id> --agent-id <agent-id>
+
+# Release task
+pnpm paperclip issue release <issue-id>
+```
+
+## Company Commands
+
+```sh
+pnpm paperclip company list
+pnpm paperclip company get <company-id>
+```
+
+## Agent Commands
+
+```sh
+pnpm paperclip agent list
+pnpm paperclip agent get <agent-id>
+```
+
+## Approval Commands
+
+```sh
+# List approvals
+pnpm paperclip approval list [--status pending]
+
+# Get approval
+pnpm paperclip approval get <approval-id>
+
+# Create approval
+pnpm paperclip approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+
+# Approve
+pnpm paperclip approval approve <approval-id> [--decision-note "..."]
+
+# Reject
+pnpm paperclip approval reject <approval-id> [--decision-note "..."]
+
+# Request revision
+pnpm paperclip approval request-revision <approval-id> [--decision-note "..."]
+
+# Resubmit
+pnpm paperclip approval resubmit <approval-id> [--payload '{"..."}']
+
+# Comment
+pnpm paperclip approval comment <approval-id> --body "..."
+```
+
+## Activity Commands
+
+```sh
+pnpm paperclip activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
+```
+
+## Dashboard
+
+```sh
+pnpm paperclip dashboard get
+```
+
+## Heartbeat
+
+```sh
+pnpm paperclip heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
+```

docs/cli/overview.md

@@ -0,0 +1,62 @@
+---
+title: CLI Overview
+summary: CLI installation and setup
+---
+
+# CLI Overview
+
+The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
+
+## Usage
+
+```sh
+pnpm paperclip --help
+```
+
+## Global Options
+
+All commands support:
+
+| Flag | Description |
+|------|-------------|
+| `--api-base <url>` | API base URL |
+| `--api-key <token>` | API authentication token |
+| `--context <path>` | Context file path |
+| `--profile <name>` | Context profile name |
+| `--json` | Output as JSON |
+
+Company-scoped commands also accept `--company-id <id>`.
+
+## Context Profiles
+
+Store defaults to avoid repeating flags:
+
+```sh
+# Set defaults
+pnpm paperclip context set --api-base http://localhost:3100 --company-id <id>
+
+# View current context
+pnpm paperclip context show
+
+# List profiles
+pnpm paperclip context list
+
+# Switch profile
+pnpm paperclip context use default
+```
+
+To avoid storing secrets in context, use an env var:
+
+```sh
+pnpm paperclip context set --api-key-env-var-name PAPERCLIP_API_KEY
+export PAPERCLIP_API_KEY=...
+```
+
+Context is stored at `~/.paperclip/context.json`.
+
+## Command Categories
+
+The CLI has two categories:
+
+1. **[Setup commands](/cli/setup-commands)** — instance bootstrap, diagnostics, configuration
+2. **[Control-plane commands](/cli/control-plane-commands)** — issues, agents, approvals, activity

docs/cli/setup-commands.md

@@ -0,0 +1,102 @@
+---
+title: Setup Commands
+summary: Onboard, run, doctor, and configure
+---
+
+# Setup Commands
+
+Instance setup and diagnostics commands.
+
+## `paperclip run`
+
+One-command bootstrap and start:
+
+```sh
+pnpm paperclip run
+```
+
+Does:
+
+1. Auto-onboards if config is missing
+2. Runs `paperclip doctor` with repair enabled
+3. Starts the server when checks pass
+
+Choose a specific instance:
+
+```sh
+pnpm paperclip run --instance dev
+```
+
+## `paperclip onboard`
+
+Interactive first-time setup:
+
+```sh
+pnpm paperclip onboard
+```
+
+Prompts for:
+
+1. Deployment mode (`local_trusted` or `authenticated`)
+2. Exposure policy (if authenticated: `private` or `public`)
+3. Public URL (if authenticated + public)
+4. Database and secrets configuration
+
+## `paperclip doctor`
+
+Health checks with optional auto-repair:
+
+```sh
+pnpm paperclip doctor
+pnpm paperclip doctor --repair
+```
+
+Validates:
+
+- Server configuration
+- Database connectivity
+- Secrets adapter configuration
+- Storage configuration
+- Missing key files
+
+## `paperclip configure`
+
+Update configuration sections:
+
+```sh
+pnpm paperclip configure --section server
+pnpm paperclip configure --section secrets
+pnpm paperclip configure --section storage
+```
+
+## `paperclip env`
+
+Show resolved environment configuration:
+
+```sh
+pnpm paperclip env
+```
+
+## `paperclip allowed-hostname`
+
+Allow a private hostname for authenticated/private mode:
+
+```sh
+pnpm paperclip allowed-hostname my-tailscale-host
+```
+
+## Local Storage Paths
+
+| Data | Default Path |
+|------|-------------|
+| Config | `~/.paperclip/instances/default/config.json` |
+| Database | `~/.paperclip/instances/default/db` |
+| Logs | `~/.paperclip/instances/default/logs` |
+| Storage | `~/.paperclip/instances/default/data/storage` |
+| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |
+
+Override with:
+
+```sh
+PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclip run
+```