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]>
4.4 KiB
paperclip_version, seo_title, seo_description
| paperclip_version | seo_title | seo_description |
|---|---|---|
| v2026.722.0 | ACPX Local Adapter (Retired) | 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)
This adapter has been retired.
acpx_localis no longer a choice when you create an agent. ACP is now a capability of each harness adapter rather than a separate adapter, so pick the adapter that matches your harness and let ACP handle itself:
What replaced it
ACPX used to be the one adapter that could target Claude, Codex, or a custom ACP server. That turned ACP into a separate agent choice, when really it is an execution capability of the harness you already picked.
Now claude_local, codex_local, and gemini_local each speak ACP natively. Leave engine on its default auto and you get ACP whenever the host can support it, with an automatic fallback to the CLI lane when it cannot. Set engine: "acp" if ACP is required and a missing prerequisite should stop the run outright.
Each of those pages documents the ACP fields — agentCommand, mode, nonInteractivePermissions, stateDir, warmHandleIdleMs — in its own configuration section.
Runs natively on Windows
Good news if you work on Windows: your local ACP agents now run there too, right alongside Linux. The embedded ACPX engine used to launch each local agent command by wrapping it in a generated Bash script, which meant it only worked where a Bash shell was available. That wrapper is gone. Claude, Codex, Gemini, and any custom ACP adapter now spawn as a native process on whichever platform you're on — no shell script in the middle.
You don't need to change anything to get this. Set engine to auto (the default) or acp, pick the adapter that matches your harness, and the run starts the same way on Windows as it does on Linux.
Here's what changed under the hood so the native path behaves cleanly:
- Environment variables travel through ACPX session options. Instead of being baked into a shell script, your agent's environment (including the values Paperclip injects for a run) is handed to the ACPX runtime as part of the session options and applied when the process spawns.
- Agent output on stderr is captured in-process. The engine reads the child process's stderr directly rather than relying on shell redirection, so diagnostics still show up in your run log on every platform.
.cmdshims are preferred on Windows. When the engine resolves a bundlednpm/pnpmbinary fromnode_modules/.bin, on Windows it looks for the.cmdshim first (for examplepnpm.cmd) before falling back to the bare name — which is how these tools are actually installed on Windows.- Symlinks fall back to copies. Paperclip stages runtime skills and config files into place with symlinks. On Windows, creating a symlink can fail with an
EPERMpermission error; when that happens, the engine copies the file instead so setup still succeeds.
If you had an ACPX agent
You do not need to do anything. Existing acpx_local agents were migrated for you when your instance upgraded. The migration reads each agent's old agent field and moves it to the matching adapter:
Old adapterConfig.agent |
New adapter | New config |
|---|---|---|
codex |
codex_local |
engine: "acp" |
| anything else (including unset) | claude_local |
engine: "acp" |
For Codex agents, the old effort, reasoningEffort, and thinkingEffort fields are consolidated onto a single modelReasoningEffort value.
If you still see acpx_local in an error
Paperclip deliberately keeps the retired adapter registered so that a stale row fails with a clear message instead of silently falling back to the process adapter. If a run logs a retirement message naming acpx_local, that agent's row predates the migration — open the agent and switch it to claude_local or codex_local with engine set to acp.
Related
- Claude Code — Claude harness, ACP by default.
- Codex — Codex harness, ACP by default.
- Gemini CLI — Gemini harness, ACP by default.
- Adapters Overview — the full list of adapters you can pick today.
- Creating An Adapter — author your own when none of the built-ins fit.