seo: hand-write titles and descriptions for all 192 pages (#115)

## Why The build derived `<title>` from the **sidebar label** and the description from the **first paragraph clipped to 220 characters**. Both are the wrong source. A sidebar label is written for a 240px-wide nav that supplies its own context; a search result has none. On production that produced: - **7 pages titled "Overview"**, and 32 pages sharing a title with another page - **109 of 193 descriptions cut off mid-word**, and 174 over 160 characters (where Google truncates) ``` /guides/welcome/key-concepts/ BEFORE (220): ...and if you misunderstand them early, the product wi ``` Near-identical titles are the weak-differentiation signal behind "crawled — currently not indexed", which is the exact symptom on this property. ## What changed `seo_title` and `seo_description` frontmatter on **every one of the 192 pages**, written by hand against each page's real content and optimised for the click — lead with what the reader can do, name the concrete things covered, no keyword stuffing, no repeating the title. | | Before | After | |---|---|---| | Duplicate titles | 32 pages | **0** | | Duplicate descriptions | — | **0** | | Descriptions cut mid-word | 109 | **0** | | Descriptions over 160 chars | 174 | **0** | | Title length (incl. suffix) | up to "Overview" | **26–60** | | Description length | 31–240 | **122–158** | **No prose was rewritten.** I measured content overlap between the colliding pairs first — only 17–23%, so these were always distinct pages wearing the same label, not duplicate content. The `docs/` diff is **564 insertions, zero deletions**. ### Examples ``` BEFORE — all seven identical: "Overview | Paperclip Docs" AFTER: "Adapters Overview" "API Overview" "CLI Overview" "Deployment Overview" "Bundled Skills" "Optional Skills" "Experimental Features" BEFORE — both identical: "Issues | Paperclip Docs" AFTER: "Issues: Creating and Tracking Work" /guides/day-to-day/issues/ "Issues API" /reference/api/issues/ ``` ``` /guides/getting-started/five-minute-path/ BEFORE (220): The shortest route from a running Paperclip instance to an agent that has just completed work for you. After Paperclip is installed, the path takes about 5 minutes: create a company, hire a CEO agent, approve its first s AFTER (131): Install Paperclip, create a company, hire a CEO agent, and approve its first strategy — a working AI company in about five minutes. ``` ## Plumbing - **`site/build-release.mjs`** prefers the authored fields; the derived path stays only as a fallback the CI gate prevents ever reaching. `<title>`, `<meta name="description">`, and the `TechArticle` JSON-LD all read from the same source. - **`site/app.js`** uses the same fields, so a client-side transition cannot leave a different title on screen than the crawler was served. Verified in-browser: navigating `/guides/day-to-day/issues/` → `/reference/api/issues/` swaps to exactly the server-rendered values, no JS errors. - **`scripts/verify-seo-metadata.mjs`** (new) enforces presence, uniqueness, length, complete-sentence endings, and the frontmatter-safety rules. Wired into `docs:test` and CI as its own step. I negative-tested the gate rather than assuming it works — it correctly fails on a duplicate title, a mid-word description, and a missing field, and passes again once restored. ## Automating it going forward `skills/sync-docs/SKILL.md` now: - gains an **"Authored SEO metadata"** section: why the fields exist, the enforced rules as a table, and how to actually write them (title names the subject not the nav position; description writes for the click; never generate mechanically from the first paragraph — *that is the fallback the gate exists to prevent*). - requires both fields in the **page-authoring instruction** given to every subagent, with guidance on when to update an existing description versus leave it. - runs `docs:test:seo-metadata` and `docs:test:crawlable-links` as **fail-loud gates in Phase 7** before commit. - documents all six build gates in the files/gates section. So once this lands, a new page cannot ship without hand-written metadata, and a title collision cannot reach production. ## Verified All six verifiers pass: ``` Static route verification passed Asset fingerprint verification passed Hierarchical Skills nav verification passed Skill source block verification passed (11 skill pages, 1 control page) Crawlable-link contract passed: 40886 internal links across 194 pages resolve in one hop Authored-SEO contract passed: 192 pages carry a unique, hand-written seo_title and seo_description ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
2026-11-07 06:16:07 -10:00 · 2026-08-25 22:51:42 +02:00
1 parent 5fa6e1dcbf
commit 325c9eb819
@@ -40,6 +40,10 @@ jobs:
        if: always()
        run: npm run docs:test:crawlable-links

+      - name: Authored SEO metadata
+        if: always()
+        run: npm run docs:test:seo-metadata
+
      - name: Skill source blocks
        if: always()
        run: npm run docs:test:skill-source-blocks
@@ -1,3 +1,8 @@
+---
+seo_title: CLI Auth and Board Claim
+seo_description: Two identity flows for the command line, both built so token material never leaves your browser or CLI. Claim a board, log in by device code, rotate tokens.
+---
+
 # CLI Auth & Board Claim

 Paperclip has two separate identity flows for humans on the command line and browser:
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.609.0
+seo_title: Company Administration
+seo_description: Set your company name and logo, manage members and invites, review join requests, and export or import the whole company from one cluster of screens.
 ---

 # Company Administration
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.529.0
+seo_title: Plugins: Extending Paperclip
+seo_description: Add dashboard widgets, file browsers, and custom tooling. Covers the Plugin Manager, installing, self-installing plugins, enabling, and handling upgrades.
 ---

 # Plugins
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.720.0
+seo_title: Roles and Permissions Reference
+seo_description: The lookup table behind company access: four roles, every permission key, how grants combine by precedence, and where instance admin sits above it all.
 ---

 # Roles & Permissions
@@ -1,3 +1,8 @@
+---
+seo_title: Secret Folders: Organising Credentials
+seo_description: Read secret names as a folder tree, so dev/github/oauth/clientid nests properly. Switch views, move around, create folders, and search across everything.
+---
+
 # Secret folders

 Once a company keeps more than a handful of credentials, a single long list stops being useful. The Secrets screen can read your secret names as a folder tree instead: a secret named `dev/github/oauth/clientid` shows up inside `dev`, then `github`, then `oauth`, with `clientid` as the thing you actually click. Nothing new is stored to make that happen — the folders are simply a different way of looking at the names you already chose.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Secret Scopes and the Responsible User
+seo_description: Company-scoped secrets share one value; user-scoped secrets hold one per person. How a run resolves each, and how to see who reached for a secret.
 ---

 # Secret scopes and the responsible user
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.720.0
+seo_title: Settings: Profile and Instance
+seo_description: Two settings surfaces and why the difference matters. Covers your profile plus instance general, access, adapters, scheduler heartbeats, and experimental.
 ---

 # Settings
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.609.0
+seo_title: Trust and Low-Trust Review
+seo_description: Contain work born from input you cannot vouch for. How presets are chosen, what changes at runtime, and how to review and promote low-trust output.
 ---

 # Trust & Low-Trust Review
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Auto-Create Recovery Tasks
+seo_description: Dependency chains die quietly behind paused agents, missing reviewers, and cancelled blockers. Recovery tasks wake that work instead of letting it wait.
 ---

 # Auto-Create Recovery Tasks
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Auto-Restart Dev Server When Idle
+seo_description: For people developing Paperclip itself: let the dev runner watch backend sources and pending migrations, and restart the server when a boot goes stale.
 ---

 # Auto-Restart Dev Server When Idle
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Cloud Sync to a Paperclip Upstream
+seo_description: Push a local company — agents, projects, issues, skills, portability files — into a Paperclip Cloud stack, previewing exactly what would change first.
 ---

 # Cloud Sync
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.722.0
+seo_title: Connections v3 (Apps)
+seo_description: The experimental home for connecting agents to outside services — Google Sheets, remote MCP servers, and REST APIs — on a rebuilt connections foundation.
 ---

 # Connections v3 (Apps)
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Environments: Remote Execution Targets
+seo_description: Run agents somewhere other than the Paperclip host. Define named targets over SSH or a provider sandbox, and assign them per instance, project, or agent.
 ---

 # Environments
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: External Objects: Live Links on Issues
+seo_description: Turn dead references to pull requests, tickets, and deployments into live status you can read from inside Paperclip instead of opening another tab.
 ---

 # External Objects
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Experimental File Viewer
+seo_description: Read the reports, code changes, and screenshots an agent produced without leaving the task — the files, not just the comment thread that describes them.
 ---

 # Experimental File Viewer
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Isolated Workspaces
+seo_description: Give each task run its own git worktree on its own branch, so several agents can work a project at once without fighting over one shared checkout.
 ---

 # Isolated Workspaces
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Experimental Features
+seo_description: Real, working features shipped behind opt-in flags while they are evaluated against live usage. What lives here, and what turning one on commits you to.
 ---

 # Experimental features
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Task Plan Decomposition Panel
+seo_description: See the machinery that turns an accepted plan into child tasks, and the guarantee it runs exactly once even across retries and interrupted runs.
 ---

 # Task Plan Decomposition Panel
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Server Info Debug View
+seo_description: Answer which commit a server is actually running from inside the app. Adds a Server section to the account drawer for support and development work.
 ---

 # Server Info Debug View
@@ -1,3 +1,8 @@
+---
+seo_title: Status Cards: Answers Without Filtering
+seo_description: Pin the questions you ask daily — is the launch blocked, what changed this week, what is the next action — and read the answer without working the board.
+---
+
 # Status Cards

 You already know the handful of questions you ask every day. *Is the launch still blocked?* *What changed on the migration this week?* *Are we shipping, and if not, what's the next action?* Answering them means opening the board, filtering, reading, and holding it all in your head — again tomorrow.
@@ -1,3 +1,8 @@
+---
+seo_title: Chat-Style Tasks
+seo_description: Read what an agent said and what it actually did in one stream — thinking, commands, and diffs inline, instead of a comment thread beside a transcript.
+---
+
 # Chat-Style Tasks

 Watching an agent work on a task usually means reading two things at once: the comment thread for what it *said*, and the transcript for what it actually *did*. The interesting part — the thinking, the commands, the diffs — sits off to one side, and once the run finishes you scroll past a wall of it to find the reply.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Task Watchdogs (Experimental)
+seo_description: A watchdog wakes when an agent misreads a blocker, claims done without proof, or gives up on a recoverable error, so the issue tree never just goes quiet.
 ---

 # Task Watchdogs
@@ -1,3 +1,8 @@
+---
+seo_title: The Activity Log
+seo_description: A permanent, timestamped record of every status change, comment, hire, and approval in your company — built for accountability and for debugging.
+---
+
 # Activity Log

 The Activity Log is the complete record of everything that has ever happened in your company. Every time an agent changes a task's status, posts a comment, gets hired or paused, spends budget, or has a proposal approved — that event is recorded here with a timestamp and the name of whoever caused it.
@@ -1,3 +1,8 @@
+---
+seo_title: Approvals: Staying in Control
+seo_description: Agents pause for your sign-off before consequential actions. Review hires and strategies, then approve, reject, or send them back for revision.
+---
+
 # Approvals

 Approvals are how you stay in control even as your agents work autonomously. Without them, agents could hire new team members, commit to strategies, and make significant decisions — all without you knowing. Approvals are the governance layer that prevents that: before any agent takes a consequential action, Paperclip pauses and asks for your sign-off.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Artifacts: Files Your Agents Produce
+seo_description: Documents, images, video, and exports from every task in one place. Filter by type, browse stacks by task, and read files in the in-app viewer.
 ---

 # Artifacts
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.513.0
+seo_title: Blocked Inbox: Triaging Stalled Work
+seo_description: The Blocked tab surfaces issues waiting on a decision, a recovery run, an external person, or a paused owner — and shows who owns each unblock.
 ---

 # Blocked Inbox
@@ -1,3 +1,8 @@
+---
+seo_title: The Command Palette
+seo_description: Press Cmd+K or Ctrl+K to jump to any project, task, or page, start common actions, and search as you type without touching the sidebar.
+---
+
 # The Command Palette

 When you want to get somewhere fast — jump to a project, open a task, or start a new agent — you don't have to hunt through the sidebar. Press **⌘K** (or **Ctrl+K** on Windows and Linux) from anywhere in Paperclip and the command palette opens: a single search box that lets you navigate, search, and run common actions from the keyboard.
@@ -1,3 +1,8 @@
+---
+seo_title: Costs: Budgets, Providers, and Spend
+seo_description: Set limits Paperclip enforces automatically. Five tabs cover overview, budgets, providers, billers, and finance, with headline spend metrics on top.
+---
+
 # Costs

 > **Warning:** AI agents make real API calls that cost real money. Every time an agent works — every heartbeat, every task, every comment it reads and writes — it sends and receives text through a provider like Anthropic or OpenAI, which charges you per token (roughly per word). This isn't a Paperclip fee; it's a cost you pay directly to the AI provider. Read this guide before your agents start running in earnest.
@@ -1,3 +1,8 @@
+---
+seo_title: The Dashboard
+seo_description: Your control centre: agent status, overview cards, and the recent activity feed — plus how to read all three at a glance and catch trouble early.
+---
+
 # The Dashboard

 The dashboard is your control centre. When your AI company is running, this is the page you'll return to most — it tells you, at a glance, whether everything is moving forward or whether something needs your attention.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Decisions: One Queue for Human Calls
+seo_description: Approvals, blocked issues, failed runs, and budget warnings in a single ranked queue, so you work through what needs you instead of hunting for it.
 ---

 # Decisions
@@ -1,3 +1,8 @@
+---
+seo_title: Feedback and Voting
+seo_description: Rate agent comments and documents Helpful or Needs work. Votes stay on your own machine by default; export or share them only if you choose to.
+---
+
 # Feedback & Voting

 Every time an agent posts a comment or revises a document, you can rate the result with **Helpful** (thumbs up) or **Needs work** (thumbs down). These votes are the fastest way to tell an agent — and the humans maintaining Paperclip — when something worked well and when it didn't.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Issues: Creating and Tracking Work
+seo_description: Each issue is one unit of work tied to your company goal. Create them yourself or let the CEO do it, then track progress, comment, and close them.
 ---

 # Issues
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.626.0
+seo_title: Task Work Modes: Standard and Ask
+seo_description: Standard mode wants work done; Ask mode wants a question answered. See how each changes the machinery an agent spins up when it picks up a task.
 ---

 # Work modes
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: The Work Timeline
+seo_description: A Gantt-style view of every agent run on one shared time axis: when agents worked, how work passed between them, and where it overlapped.
 ---

 # The Work Timeline
@@ -1,3 +1,8 @@
+---
+seo_title: Quickstart: Your First Agent in 5 Minutes
+seo_description: Install Paperclip, create a company, hire a CEO agent, and approve its first strategy — a working AI company in about five minutes.
+---
+
 # Quickstart Path

 The shortest route from a running Paperclip instance to an agent that has just completed work for you. After Paperclip is installed, the path takes about 5 minutes: create a company, hire a CEO agent, approve its first strategy, watch tasks land on the board.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.529.0
+seo_title: Install Paperclip: Local or Self-Hosted
+seo_description: Two supported install paths: a local Node.js 20 setup via pnpm, or a self-hosted server on your own domain. Both finish at the same onboarding flow.
 ---

 # Installation
@@ -1,3 +1,8 @@
+---
+seo_title: Watching Your Agents Work
+seo_description: Turn on the CEO's heartbeat and follow its first execution cycle: read the run transcript, review the strategy, and watch tasks reach the board.
+---
+
 # Watching Agents Work

 You have a company with a goal and a CEO agent configured. This guide covers what happens next: enabling the CEO's heartbeat, watching it work through its first execution cycle, reviewing the strategy it produces, and seeing the first tasks appear on the board.
@@ -1,3 +1,8 @@
+---
+seo_title: Hire Your First Agent
+seo_description: An agent is a role, an AI system, a budget, and a set of wake-up rules. Choose each when hiring, plus fixes for the snags that trip people up.
+---
+
 # Hire Your First Agent

 An agent isn't just "an AI". It's a configuration — a specific role, with a specific AI system powering it, operating under a specific budget, with defined rules for when and how it wakes up and works.
@@ -1,3 +1,8 @@
+---
+seo_title: Create Your First Company
+seo_description: A company holds your goal, your agents, your task board, and your budget. Set one up before hiring, and learn when running more than one makes sense.
+---
+
 # Create Your First Company

 A Company in Paperclip is the container for everything: your goal, your team of agents, all the tasks they work through, and the budget that keeps spending under control. Before any agents can do anything, they need a company to work inside.
@@ -1,3 +1,8 @@
+---
+seo_title: The Adapter Manager
+seo_description: Enable, disable, configure, reload, and remove adapters. Covers the built-in set plus installing external adapters to extend which runtimes you can use.
+---
+
 # The Adapter Manager

 Every agent in Paperclip needs an **adapter** — the shim that lets the control plane talk to a specific AI runtime. Built-in adapters ship with the product (Claude Code, Codex, Gemini, OpenCode, Cursor, Pi, Hermes, HTTP, Process, OpenClaw Gateway), and you can extend the set by installing **external adapters** from npm or a local path.
@@ -1,3 +1,8 @@
+---
+seo_title: Choosing an Agent Adapter
+seo_description: Compare the adapters that run your agents — Claude Code, Codex, OpenCode, HTTP webhook and more — and pick the right bridge for each role you hire.
+---
+
 # Agent Adapters

 When you create an agent in Paperclip, one of the first things you configure is its adapter. The adapter is the bridge between Paperclip and the AI system that actually runs your agent — it tells Paperclip how to launch the agent, how to pass it work, and how to receive results back.
@@ -1,3 +1,8 @@
+---
+seo_title: Agents: Your AI Employees
+seo_description: Hire agents, browse the agent list, and work the detail page — dashboard, instructions, and references — for the AI employees doing your company's work.
+---
+
 # Agents

 Agents are the AI employees that make up your Paperclip company. They're where the work actually happens: the CEO setting strategy, the engineer shipping code, the marketer drafting posts. Everything else in Paperclip — tasks, approvals, skills, budgets — exists to coordinate and govern what your agents do.
@@ -1,3 +1,8 @@
+---
+seo_title: Delegation: How Work Reaches Agents
+seo_description: Set a goal, approve a plan, and the CEO breaks it into tasks and assigns them. What you own, what the CEO handles, and the agent-to-agent guardrails.
+---
+
 # Delegation

 One of the most powerful things about Paperclip is that you don't have to manage work directly. You set a goal, approve a plan, and the CEO automatically breaks that goal into concrete tasks and assigns them to the right agents. This is delegation — and understanding how it works helps you know when to act and when to let the system run.
@@ -1,3 +1,8 @@
+---
+seo_title: Members and Access: People in a Company
+seo_description: How humans fit alongside agents: one membership model, roles versus grants, instance admin, member profiles, and why leaving a project keeps access.
+---
+
 # Members & Access

 Most of Paperclip is about *agents* — the AI employees that do the work. But a company also has **people**: the humans who sign in, watch the board, approve spend, invite teammates, and set direction. This guide is the mental model for how those people fit in — who can be a member, how access is decided, and how the human side relates to the agent org chart.
@@ -1,3 +1,8 @@
+---
+seo_title: Building Your Org Structure
+seo_description: Reporting lines tell each agent who manages them, who delegates work, and who to escalate to. Common structures, plus adding managers and workers.
+---
+
 # Building Your Org Structure

 Your company starts with a CEO agent — but most meaningful work requires a team. Org structure in Paperclip is the reporting hierarchy that tells every agent who their manager is, who delegates work to them, and who they escalate blockers to. Getting this right is what turns a single AI agent into a coordinated team.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.720.0
+seo_title: Skills: Reusable Agent Procedures
+seo_description: Package a checklist, runbook, or template once and share it across agents. Covers adding skills, folders, Skill Studio, and the cost and performance payoff.
 ---

 # Skills
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.609.0
+seo_title: Team Catalog: Ready-Made Starter Teams
+seo_description: Skip the blank page. Install a working team — agents, reporting lines, projects, routines, and skills — from the app or the terminal in one step.
 ---

 # Team Catalog
@@ -1,3 +1,8 @@
+---
+seo_title: Execution Policy: Enforced Review Gates
+seo_description: The runtime intercepts an executor closing an issue and routes it to review and approval. Covers the three layers, the changes-requested loop, and escalation.
+---
+
 # Execution Policy

 Paperclip's execution policy system keeps tasks honest. Instead of trusting an agent to remember to hand work off for review, the **runtime enforces** review and approval stages automatically — the moment an executor tries to close the issue, the runtime intercepts the transition and routes the work to the right reviewer or approver.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Export and Import a Company
+seo_description: Capture a configured company as a portable package to back up, share, or move between instances. What full fidelity includes, and what a package contains.
 ---

 # Export & Import
@@ -1,3 +1,8 @@
+---
+seo_title: Terminal Setup for Paperclip
+seo_description: Run the onboarding command to download Paperclip, create ~/.paperclip/, initialise the database, and start the server. Plus deployment modes and options.
+---
+
 # Terminal Setup

 > **Note:** This guide goes deeper than the standard setup. If you're installing Paperclip for the first time, start with the [Installation guide](../getting-started/installation.md) — it covers the one-command install step by step.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Custom Sandbox Images
+seo_description: Stop re-installing the same CLIs and dependencies on every run. Build and capture a sandbox image, then manage which one future runs start from.
 ---

 # Custom sandbox images
@@ -1,3 +1,8 @@
+---
+seo_title: Goals: Outcomes Above Projects
+seo_description: Goals are outcome statements that anchor everything below them. Create them, link issues and projects, and build a hierarchy that keeps work pointed right.
+---
+
 # Goals

 A goal in Paperclip is an outcome statement — a description of something the company is trying to achieve. Goals sit above projects and issues in the hierarchy: they do not contain code, they do not get "worked on" directly, and they do not have an execution workspace. Instead, they act as anchors. Projects link up to goals, and the CEO's strategy typically justifies itself by pointing at which goals it is advancing.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.529.0
+seo_title: Projects: Grouping Related Work
+seo_description: Projects bind work to a repository, a working directory, and a budget envelope. Tour the overview, issues, workspaces, configuration, and budget tabs.
 ---

 # Projects
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.626.0
+seo_title: Heartbeats and Routines: Scheduling Work
+seo_description: Why timer heartbeats are opt-in, and how routines schedule recurring work without paused agents, surprise token bills, or a dashboard you fight with.
 ---

 # Heartbeats & Routines
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.626.0
+seo_title: Task Watchdogs: Catching Stalled Work
+seo_description: When an agent misreads a blocker or calls a task done without proof, a watchdog wakes. Set one up, write good instructions, and know its limits.
 ---

 # Task Watchdogs
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Execution Workspaces
+seo_description: Give agents a real folder with your code checked out. Covers workspace modes, keeping reused workspaces consistent, runtime services, and HTTPS previews.
 ---

 # Workspaces
@@ -1,3 +1,8 @@
+---
+seo_title: Glossary of Paperclip Terms
+seo_description: Every term in Paperclip's interface and docs, defined in plain English and sorted A-Z — the place to look when a word in a guide isn't clicking.
+---
+
 # Glossary

 A quick reference for every term used in Paperclip's UI and documentation, in plain English. If you hit a word in a guide that isn't clicking, look it up here.
@@ -1,3 +1,8 @@
+---
+seo_title: Key Concepts: Companies, Agents, Tasks
+seo_description: The seven ideas behind Paperclip — company, agent, task, heartbeat, adapter, budget, approval — explained with analogies before the technical detail.
+---
+
 # Key Concepts

 Before you start clicking around, it's worth spending five minutes here. Paperclip introduces a handful of ideas that don't have perfect equivalents in other software — and if you misunderstand them early, the product will seem confusing in ways that are hard to untangle later.
@@ -1,3 +1,8 @@
+---
+seo_title: What is Paperclip?
+seo_description: Paperclip is an operating system for running an AI company: you set the goals, hire AI agents as employees, and approve every decision that matters.
+---
+
 # What is Paperclip?

 Paperclip is the operating system for your AI company. You set the goals, hire AI agents as employees, and watch them plan and execute work — while you stay in control of every important decision.
@@ -1,3 +1,8 @@
+---
+seo_title: Add a Human Teammate
+seo_description: Bring a co-founder, operator, or read-only viewer into your company as a board member, and pick the access level that matches what they need to do.
+---
+
 # Add a human teammate

 Paperclip companies aren't single-player. You can bring other people in as board members — a co-founder who watches the same agents, an operator who triages the inbox, a viewer who just wants read access to the dashboard. This is the end-to-end flow, done from the app: you create an invite link, they open it and ask to join, and you approve them.
@@ -1,3 +1,8 @@
+---
+seo_title: Add an MCP Server to an Agent
+seo_description: Attach a Model Context Protocol server so one agent picks up new tools — query Postgres, search a vector index, file issues — without changing Paperclip.
+---
+
 # Add an MCP server to an agent's toolkit

 Attach a Model Context Protocol (MCP) server to a specific Paperclip agent so it picks up new tools — read a local Postgres, query a vector index, file GitHub issues — without modifying Paperclip itself. End-to-end on a fresh agent in about 10 minutes for a local server, 20 for a remote one.
@@ -1,3 +1,8 @@
+---
+seo_title: Back Up and Restore a Company
+seo_description: Backups are exports and restores are imports, through one portable markdown package. Walks the API path: preview, export, import, then verify.
+---
+
 # Back up and restore a company

 Backups are exports. Restores are imports. Both flow through the same portable markdown package — the same files you'd hand to a teammate or version-control. This recipe walks the API path: preview → export → import → verify, with the safety rails that the CEO-scoped routes enforce.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.525.0
+seo_title: Bring Your Own Agent
+seo_description: Three ways to wire a non-built-in agent into Paperclip — OpenClaw, an HTTP webhook, or a custom script — through the adapter layer that decouples them.
 ---

 # Bring your own agent (OpenClaw, HTTP webhook, custom script)
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.707.0
+seo_title: Community Desktop App (Unofficial)
+seo_description: An unofficial macOS app that wraps a full Paperclip instance — drag to Applications and run, no terminal. What it is, and the caveats before you rely on it.
 ---

 # Community Desktop App (unofficial)
@@ -1,3 +1,8 @@
+---
+seo_title: Connect an Agent to GitHub and Open PRs
+seo_description: Wire a coding agent to a real repo so every issue you assign produces a branch, a working commit, and a pull request visible from both sides.
+---
+
 # Connect an agent to a GitHub repo and have it open PRs

 Wire a `claude_local` (or `codex_local`) coding agent to a real GitHub repo so every issue you assign produces a branch, a working commit, and a pull request — all visible in both the Paperclip issue thread and the GitHub PR page. End-to-end on a fresh repo in about 20 minutes.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.525.0
+seo_title: Connect an AWS Secrets Manager Vault
+seo_description: Let Paperclip discover the vaults you already use by region, namespace, and name prefix, instead of copying ARNs across by hand.
 ---

 # Connect an AWS Secrets Manager vault
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.525.0
+seo_title: Create a Routine That Runs Daily
+seo_description: Describe recurring work once, attach a cron trigger, and Paperclip mints a fresh issue every tick with the same owner, parent, project, and goal.
 ---

 # Create a routine that runs daily
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.720.0
+seo_title: Debug a Stuck Heartbeat
+seo_description: The handful of symptoms behind almost every agent-not-working report, each diagnosed from the Run history on the agent's detail page.
 ---

 # Debug a stuck heartbeat
@@ -1,3 +1,8 @@
+---
+seo_title: Deploy Paperclip to a VPS or Fly.io
+seo_description: A pragmatic recipe for a working URL with persistent data. Fly.io is the fast path, a single VPS the boring backup, both from the same Docker image.
+---
+
 # Deploy Paperclip to a VPS or Fly.io

 A pragmatic recipe to get a working URL with persistent data. Fly.io is the fast path; a single VPS is the boring backup. Both use the same Docker image.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.513.0
+seo_title: Develop a Plugin Locally
+seo_description: Build a plugin from a folder on your laptop, install it into a running instance straight from disk, and iterate with the worker reloading on every save.
 ---

 # Develop a plugin locally
@@ -1,3 +1,8 @@
+---
+seo_title: Enable Multi-User Login
+seo_description: Move off loopback-only trusted mode so teammates can actually sign in. What to change, and what the switch means for your existing single-operator setup.
+---
+
 # Enable multi-user login

 Out of the box, Paperclip runs in **local trusted** mode: no login, loopback-only, one implicitly-trusted operator. That's perfect for a personal install and terrible the moment a second person needs in. To let teammates sign in, you switch the instance to **authenticated** mode, claim ownership once in the browser, and then invite people from the app.
@@ -1,3 +1,8 @@
+---
+seo_title: Handle Board Approvals for Hires
+seo_description: A manager agent cannot hire on its own; it files a request and waits. Read the proposal, approve it, and Paperclip wakes the requester to carry on.
+---
+
 # Handle board approvals for hires

 When a manager agent (usually the CEO) decides it needs help, it can't just create the new hire itself. It submits a `hire_agent` approval and waits. You — the board — read the proposal, approve it, and Paperclip wakes the requester to finish the onboarding.
@@ -1,3 +1,8 @@
+---
+seo_title: Offboard a Member
+seo_description: Remove someone's access when they leave. Paperclip changes membership status rather than deleting the record, so their history stays intact and auditable.
+---
+
 # Offboard a member

 When someone leaves — a contractor wraps up, a teammate changes roles, an account needs to go dormant — you remove their access from the company. Paperclip does this by changing their **membership status**, not by deleting the record, so the audit trail survives. There's no self-serve "leave company" today; an Owner or Admin does the offboarding from the app.
@@ -1,3 +1,8 @@
+---
+seo_title: Require Board Approval Before Spend
+seo_description: Caps are reactive. For lumpy, discrete spend — a $40/month SaaS signup — make agents ask a human first instead of warning you at 80 percent.
+---
+
 # Require board approval before an agent spends money

 Budget caps are reactive. They warn at 80% and hard-stop at 100% — useful for bounding the runaway case, useless for *"don't sign up for this $40/month SaaS without asking me first."* For lumpy, discrete spend that needs a human go-ahead **before** the dollars move, you want an approval gate: the agent stops, posts a `request_board_approval`, and waits for your decision before continuing.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.525.0
+seo_title: Update or Rotate a Provider API Key
+seo_description: Swap the credential a running agent uses — after a provider rotation, an expiry, or a move from subscription login to a console-issued key.
 ---

 # Update or rotate a provider API key
@@ -1,3 +1,8 @@
+---
+seo_title: Set a Monthly Budget and Enforce It
+seo_description: A misconfigured loop can run a four-figure tab in a weekend. Set a cap Paperclip enforces automatically, with warnings before the hard stop.
+---
+
 # Set a monthly budget and enforce it

 Autonomous agents make real API calls. A misconfigured loop, an over-eager prompt, or a pricing change can run a four-figure tab in a weekend if nothing pulls the brake. Paperclip's budget system is the brake: you set a cap, Paperclip warns at 80%, hard-stops at 100%, and pauses the offending scope until you raise the cap or the calendar month resets.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.609.0
+seo_title: Sync a Local Company to Cloud Upstream
+seo_description: Move a company's agents, projects, issues, skills, and portability files into a connected Cloud stack: preview, resolve conflicts, push, then verify.
 ---

 # Sync a local company to a Paperclip Cloud upstream
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.824.0
+seo_title: Update Paperclip to the Latest Version
+seo_description: Move an existing install to a new release without losing data — what to check first, how to run the update, and how to confirm it actually took.
 ---

 # Update Paperclip to the latest version
@@ -1,3 +1,8 @@
+---
+seo_title: Wire Slack or Discord Notifications
+seo_description: Pipe approvals, blocked high-priority issues, and budget breaches into a channel so the board sees decisions without anyone watching the UI.
+---
+
 # Wire Slack/Discord notifications for approvals

 Pipe approval requests, blocked high-priority issues, and budget breaches to a Slack or Discord channel so the board sees decisions without watching the UI. The recipe is the same for both: a Paperclip routine pings a notifier agent on a schedule, the agent diffs against a "last-seen" cursor, and posts a structured message to a webhook URL.
@@ -1,3 +1,8 @@
+---
+seo_title: Write a Company Skill
+seo_description: Author a small Markdown bundle, install it into your company skill library, and attach it to just the agents that should load it. About 15 minutes.
+---
+
 # Write a company skill and assign it to specific agents

 Author a small Markdown bundle that any agent in your company can load on demand, install it into the company skill library, and attach it to the one or two agents that should actually use it. End-to-end on a fresh skill in about 10 minutes.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.722.0
+seo_title: ACPX Local Adapter (Retired)
+seo_description: ACPX has been retired. It treated ACP as a separate agent choice when it is really an execution detail — this page explains what to use instead.
 ---

 # ACPX Local (retired)
@@ -1,3 +1,8 @@
+---
+seo_title: Adapter UI Parser Contract
+seo_description: Paperclip streams adapter stdout to the run viewer live. Ship a UI parser so structured lines render as tool calls and results instead of raw text.
+---
+
 # Adapter UI Parser Contract

 Paperclip streams adapter stdout to the run viewer in real time. If your adapter emits structured lines, ship a UI parser so the viewer can render tool calls, tool results, thinking blocks, and system messages instead of treating everything as plain assistant text.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.817.0
+seo_title: Claude Code Adapter
+seo_description: Run Anthropic's Claude Code CLI on the Paperclip host, with session persistence, skills injection, and configuration managed from your agent.
 ---

 # Claude Code
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.817.0
+seo_title: Codex Adapter
+seo_description: Run OpenAI's Codex CLI on the Paperclip host as a local coding agent, with persistent session state and a managed CODEX_HOME per agent.
 ---

 # Codex
@@ -1,3 +1,8 @@
+---
+seo_title: Creating a Custom Adapter
+seo_description: Build your own adapter when the built-in ones do not fit your runtime. Covers the code shape and the runtime contracts an adapter must satisfy.
+---
+
 # Creating an Adapter

 Build a custom adapter when the built-in local adapters do not fit your runtime. This page covers the code shape and runtime contracts; if you are packaging an installable plugin, read [External Adapters](./external-adapters.md) first.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.512.0
+seo_title: Cursor Cloud Adapter
+seo_description: Run Cursor Cloud Agents through the official SDK so Cursor handles remote code execution while Paperclip keeps the task state and history.
 ---

 # Cursor Cloud
@@ -1,3 +1,8 @@
+---
+seo_title: Cursor Local Adapter
+seo_description: Run Cursor's Agent CLI on the Paperclip host, keeping chat sessions alive across heartbeats and emitting structured stream output in run views.
+---
+
 # Cursor Local

 `cursor` runs Cursor's Agent CLI on the same machine as Paperclip. Use it when you want Cursor chat session resume across heartbeats and structured stream output in run logs.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.609.0
+seo_title: External Adapters
+seo_description: Ship an adapter as its own npm package or local directory when you want independent versioning, separate distribution, or private runtime code.
 ---

 # External Adapters
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.720.0
+seo_title: Gemini CLI Adapter
+seo_description: Run Google's Gemini CLI on the Paperclip host, with session resume across heartbeats and configurable sandboxing for each agent you point at it.
 ---

 # Gemini CLI
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.517.0
+seo_title: Grok Local Adapter
+seo_description: Run xAI's Grok Build CLI on the Paperclip host as a local coding agent that resumes the same Grok session across every heartbeat.
 ---

 # Grok Local
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.626.0
+seo_title: Hermes Gateway Adapter
+seo_description: Connect to a Hermes API server already running elsewhere — another host or a cloud VM — over HTTP or HTTPS, instead of running it locally.
 ---

 # Hermes Gateway
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.626.0
+seo_title: Hermes Adapter
+seo_description: Run Hermes Agent by Nous Research on the Paperclip host, with persistent memory and a 30-plus tool suite available to the agent on every run.
 ---

 # Hermes
@@ -1,3 +1,8 @@
+---
+seo_title: HTTP Webhook Adapter
+seo_description: Send a JSON webhook to a service you control. Use it when the runtime is remote, long-lived, or already exposed as an API rather than a local CLI.
+---
+
 # HTTP

 The `http` adapter sends a JSON webhook request to a service you control. Use it when the runtime is remote, long-lived, or already exposed as an API instead of a local command.
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.525.0
+seo_title: Modal Sandbox Provider
+seo_description: Provision Modal sandboxes as the execution environment for agent runs when you want managed cloud compute with first-class container images.
 ---

 # Modal
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.618.0
+seo_title: OpenClaw Gateway Adapter
+seo_description: Connect to an OpenClaw instance over the Gateway WebSocket protocol when OpenClaw runs on another machine, in Docker, or behind a network boundary.
 ---

 # OpenClaw Gateway
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.817.0
+seo_title: OpenCode Adapter
+seo_description: Run OpenCode on the Paperclip host when you want provider and model routing in OpenCode's own format, plus session resume across heartbeats.
 ---

 # OpenCode
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.817.0
+seo_title: Adapters Overview
+seo_description: Adapters connect Paperclip's control plane to the runtime that does the work. Start here to compare the options and pick one per agent you hire.
 ---

 # Adapters Overview
@@ -1,5 +1,7 @@
 ---
 paperclip_version: v2026.618.0
+seo_title: Pi Adapter
+seo_description: Run the Pi coding agent CLI on the Paperclip host, with its built-in tool set — read, bash, edit, write, grep, find, ls — and provider configuration.
 ---

 # Pi
@@ -1,3 +1,8 @@
+---
+seo_title: Process Adapter
+seo_description: Run an arbitrary command on the Paperclip host. The right choice when your agent is really a script, a shell command, or a custom runtime.
+---
+
 # Process

 The `process` adapter runs an arbitrary command on the same machine as Paperclip. Use it when your agent is just a script, a shell command, or a custom runtime that already knows how to do its own work.