# Handoff Docs

- [Overview](/docs): What Handoff is, why teams adopt it, and how a workspace, a registry, and three surfaces fit together.
- [Architecture](/docs/architecture): How Handoff actually works, the two run modes, the DATABASE_URL switch, the three-surfaces principle, and the workspace-to-registry pipeline.
- Workspace
  - [Workspace](/docs/workspace): Running Handoff inside a client project repo, install, config, conventions, and the token pipeline.
  - [Install](/docs/workspace/install): Adding handoff-app to a workspace repo, and scaffolding a new one.
  - [handoff.config.* Resolution](/docs/workspace/config-resolution): How Handoff locates and resolves a workspace's config file, the full config shape, and the hooking architecture.
  - [Directory Conventions](/docs/workspace/directory-conventions): The standard folder layout inside a Handoff workspace, component declaration formats, and patterns observed across real client workspaces.
  - [.handoff/ Runtime State](/docs/workspace/runtime-state): What Handoff stores in the workspace's local .handoff/ directory, and why it's gitignored.
  - [Token Pipeline (Figma → DTCG → dist)](/docs/workspace/token-pipeline): How design tokens flow from Figma to compiled CSS/SCSS/Tailwind output.
  - [CLI Reference](/docs/workspace/cli-reference): Every handoff-app command, grouped, with real flags from the CLI source.
  - [Local Preview](/docs/workspace/local-preview): Running a filesystem-backed preview of your workspace before pushing to a registry.
- Registry
  - [Registry](/docs/registry): Deploying and running a Handoff registry, the clean, standalone handoff-app deployment that stores all tenant data in Postgres.
  - [Registry Model (Registry-as-a-Service)](/docs/registry/model): The architectural model behind treating a Handoff registry as a service, not a per-client build.
  - [Deploy (Docker + Vercel)](/docs/registry/deploy): Standing up a Handoff registry locally with Docker, or in production on Vercel.
  - [Environment Variables](/docs/registry/env-vars): Registry-side and workspace-side environment variables.
  - [First-Admin Setup](/docs/registry/first-admin-setup): Bootstrapping the first administrator account on a freshly deployed registry.
  - [Singleton Config Rows](/docs/registry/singleton-config): How registry-wide config, theme, navigation, and DTCG data are stored as singleton database rows.
  - [Auth (NextAuth)](/docs/registry/auth): How registry web-app authentication works for admins and stakeholders.
  - [Stakeholder-Facing UI Routes](/docs/registry/stakeholder-ui): The pages of a registry meant for non-developer stakeholders to browse.
- API
  - [API](/docs/api): The full Handoff REST API, covering OpenAPI spec, auth, and the route clusters.
  - [OpenAPI Spec](/docs/api/openapi-spec): Where the spec lives, how to browse it, and how it's kept current.
  - [Auth & Scopes](/docs/api/auth-scopes): How API requests are authenticated, and what scopes gate which routes.
  - [/api/registry](/docs/api/registry-cluster): The push/read endpoints a workspace uses to sync data to its registry.
  - [/api/sync (push / pull pipeline)](/docs/api/sync-cluster): The component, pattern, and page sync pipeline between a workspace and its registry.
  - [/api/handoff (app + AI + admin)](/docs/api/handoff-cluster): The session-authenticated CRUD, AI, and admin surface under /api/handoff, plus a couple of public component routes outside it.
  - [/api/oauth (device flow + OAuth 2.1)](/docs/api/oauth-cluster): RFC 8628 device authorization and the OAuth 2.1 connector flow, for CLI and MCP login.
  - [/api/mcp](/docs/api/mcp-cluster): The Model Context Protocol server endpoint.
- MCP
  - [MCP](/docs/mcp): The Model Context Protocol server, the most differentiated, agent-facing surface in Handoff 2.
  - [Route & Transport](/docs/mcp/route-transport): The MCP server endpoint and its supported transport.
  - [Tool Catalog](/docs/mcp/tool-catalog): The full MCP tool catalog, organized by category.
  - [MCP Apps](/docs/mcp/mcp-apps): Interactive, app-like surfaces exposed through MCP.
  - [Stack Guides](/docs/mcp/stack-guides): Per-framework guidance the handoff_get_stack_guide tool returns to an agent.
  - [Authentication](/docs/mcp/auth): How MCP clients authenticate against a Handoff registry.
  - [Onboarding (mcp-init / mcp-token)](/docs/mcp/onboarding): Getting a new MCP client connected to a Handoff registry.
- Concepts
  - [Concepts](/docs/concepts): Per-entity reference pages, every core Handoff data type and its UI + REST + MCP surface.
  - [Tokens (DTCG)](/docs/concepts/tokens): Design tokens as structured DTCG data, from Figma to compiled output to consumption.
  - [Components (Structured + Raw + Rendered)](/docs/concepts/components): How Handoff represents a component across its documentation, raw source, and rendered preview.
  - [Patterns](/docs/concepts/patterns): Reusable compositions of components, one level up from a single component.
  - [Pages / Docs](/docs/concepts/pages-docs): Freeform markdown documentation pages stored in a registry.
  - [Design Artifacts](/docs/concepts/design-artifacts): AI design-workbench outputs, generated images with a derived component spec.
  - [Assets (Icons, Fonts, Logos)](/docs/concepts/assets): Icon catalogs, logo sets, font files, and general uploaded assets.
  - [Changelog / Audit](/docs/concepts/changelog-audit): Unified change history across every entity type in a registry.