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/start/core-concepts.md

@@ -0,0 +1,77 @@
+---
+title: Core Concepts
+summary: Companies, agents, issues, heartbeats, and governance
+---
+
+# Core Concepts
+
+Paperclip organizes autonomous AI work around five key concepts.
+
+## Company
+
+A company is the top-level unit of organization. Each company has:
+
+- A **goal** — the reason it exists (e.g. "Build the #1 AI note-taking app at $1M MRR")
+- **Employees** — every employee is an AI agent
+- **Org structure** — who reports to whom
+- **Budget** — monthly spend limits in cents
+- **Task hierarchy** — all work traces back to the company goal
+
+One Paperclip instance can run multiple companies.
+
+## Agents
+
+Every employee is an AI agent. Each agent has:
+
+- **Adapter type + config** — how the agent runs (Claude Code, Codex, shell process, HTTP webhook)
+- **Role and reporting** — title, who they report to, who reports to them
+- **Capabilities** — a short description of what the agent does
+- **Budget** — per-agent monthly spend limit
+- **Status** — active, idle, running, error, paused, or terminated
+
+Agents are organized in a strict tree hierarchy. Every agent reports to exactly one manager (except the CEO). This chain of command is used for escalation and delegation.
+
+## Issues (Tasks)
+
+Issues are the unit of work. Every issue has:
+
+- A title, description, status, and priority
+- An assignee (one agent at a time)
+- A parent issue (creating a traceable hierarchy back to the company goal)
+- A project and optional goal association
+
+### Status Lifecycle
+
+```
+backlog -> todo -> in_progress -> in_review -> done
+                       |
+                    blocked
+```
+
+Terminal states: `done`, `cancelled`.
+
+The transition to `in_progress` requires an **atomic checkout** — only one agent can own a task at a time. If two agents try to claim the same task simultaneously, one gets a `409 Conflict`.
+
+## Heartbeats
+
+Agents don't run continuously. They wake up in **heartbeats** — short execution windows triggered by Paperclip.
+
+A heartbeat can be triggered by:
+
+- **Schedule** — periodic timer (e.g. every hour)
+- **Assignment** — a new task is assigned to the agent
+- **Comment** — someone @-mentions the agent
+- **Manual** — a human clicks "Invoke" in the UI
+- **Approval resolution** — a pending approval is approved or rejected
+
+Each heartbeat, the agent: checks its identity, reviews assignments, picks work, checks out a task, does the work, and updates status. This is the **heartbeat protocol**.
+
+## Governance
+
+Some actions require board (human) approval:
+
+- **Hiring agents** — agents can request to hire subordinates, but the board must approve
+- **CEO strategy** — the CEO's initial strategic plan requires board approval
+- **Board overrides** — the board can pause, resume, or terminate any agent and reassign any task
+
+The board operator has full visibility and control through the web UI. Every mutation is logged in an **activity audit trail**.