Aron PrinsandClaude Opus 5
325c9eb819
## 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]>
3.6 KiB
paperclip_version: v2026.824.0 seo_title: Adapters API seo_description: The control-plane surface for the server-side adapter registry: which agent runtimes Paperclip can reach, how each is configured, and how packages install.
Adapters API
The adapters API is the control-plane surface for the server-side adapter registry: which agent runtimes Paperclip can talk to, how each is configured, and how external adapter packages get installed at the instance level.
For per-adapter configuration semantics, jump to Reference → Adapters → Overview. This page documents the REST endpoints.
All routes here are mounted under
/api. They are instance-admin / board-scoped — they shape the server itself, not a single company.
List installed adapters
GET /api/adapters
Returns the registry of server-side adapters Paperclip currently knows about: built-in adapter types plus any external adapters installed on the instance.
Install an external adapter
POST /api/adapters/install
Installs an external adapter package on the instance. Used by the Adapter Manager UI and the paperclipai adapter install CLI workflow.
Update an adapter's instance config
PATCH /api/adapters/:type
Persists instance-level configuration for the adapter identified by :type (for example claude_local, codex_local, openclaw_gateway).
Override adapter behaviour
PATCH /api/adapters/:type/override
Sets the operator-controlled override block for an adapter — used to force-disable, pin, or otherwise override registry defaults without editing instance config directly.
Delete an installed adapter
DELETE /api/adapters/:type
Removes an external adapter from the registry. Built-in adapter types cannot be deleted.
Reload an adapter
POST /api/adapters/:type/reload
Drops and re-loads the adapter module in-place. Useful after editing on-disk config without restarting the server.
Reinstall an adapter
POST /api/adapters/:type/reinstall
Re-runs the install flow for an external adapter (re-fetch, re-extract, re-register).
Read an adapter's config schema
GET /api/adapters/:type/config-schema
Returns the JSON schema the Adapter Manager uses to render the adapter's settings form.
Adapter UI parser bundle
GET /api/adapters/:type/ui-parser.js
Serves the adapter-supplied UI parser bundle. The Paperclip UI fetches this script to render run output for the adapter. The wire contract is documented in Adapter UI Parser.
Adapter device login
Some adapters authenticate with a device login — the kind where the tool prints a code and a URL, you approve it in a browser, and the CLI finishes signing in. These routes drive that flow from Paperclip for a company, scoped to one environment. They currently apply to the Codex adapter.
| Route | Purpose |
|---|---|
POST /api/companies/{companyId}/adapters/{type}/login-sessions |
Start a device-login session. Body: { "environmentId": "<id>", "ttlSeconds"?: <number> }. Returns 201; a 409 means a session is already in flight. |
GET /api/companies/{companyId}/adapters/{type}/login-sessions/{sessionId} |
Read the session — its state and the code/URL to complete the login in a browser. |
POST /api/companies/{companyId}/adapters/{type}/login-sessions/{sessionId}/cancel |
Cancel the session. |
These are board routes: the caller must be on the board, have access to the company, and be allowed to manage the company's adapters. type must be an adapter that supports device login (Codex today); other types are rejected.