mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 23:02:28 -10:00
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.2 KiB
3.2 KiB
seo_title, seo_description
| seo_title | seo_description |
|---|---|
| Cursor Local Adapter | 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.
When To Use
- You already use Cursor Agent CLI locally.
- You want Paperclip to run Cursor with session resume (
--resume) across heartbeats. - You want structured stream output (
--output-format stream-json) in run logs.
When Not To Use
- You need webhook-style external invocation. Use OpenClaw Gateway or HTTP.
- You only need one-shot shell commands. Use Process.
- Cursor Agent CLI is not installed or not available on
PATH.
Common Fields
| Field | Required | Notes |
|---|---|---|
cwd |
no | Absolute working directory. Recommended. Created when permissions allow; otherwise falls back to the process working directory. |
model |
no | Cursor model id. Defaults to auto. Common choices include auto, composer-1.5, gpt-5.3-codex, opus-4.6-thinking, sonnet-4.6, gemini-3-pro, grok. |
mode |
no | Cursor execution mode passed as --mode. Accepts plan or ask. Leave unset for normal autonomous runs. |
promptTemplate |
no | Run prompt template. |
instructionsFilePath |
no | Absolute path to a Markdown instructions file prepended to the run prompt. |
command |
no | Defaults to agent. Override only for a non-default executable path. |
extraArgs |
no | Extra CLI arguments appended to the Cursor invocation. |
env |
no | Environment variables. Secret refs supported. |
timeoutSec |
no | Run timeout in seconds. 0 means no timeout. |
graceSec |
no | SIGTERM grace period before a forced stop. |
Session Persistence
Cursor Local stores the Cursor session id and resumes it with --resume on the next heartbeat when the stored session cwd matches the current cwd. If the stored cwd no longer matches, a fresh session starts.
Execution Details
- Runs are invoked as
agent -p --output-format stream-json .... - The prompt is piped to Cursor via stdin.
- The structured stream output is parsed by the Cursor UI parser into transcript entries.
Models
Common model ids accepted by the adapter:
auto
composer-1.5, composer-1
gpt-5.3-codex, gpt-5.3-codex-high, gpt-5.3-codex-xhigh
gpt-5.2, gpt-5.2-codex, gpt-5.2-codex-high
gpt-5.1-codex-max, gpt-5.1-codex-mini
opus-4.6, opus-4.6-thinking, opus-4.5, opus-4.5-thinking
sonnet-4.6, sonnet-4.6-thinking, sonnet-4.5, sonnet-4.5-thinking
gemini-3.1-pro, gemini-3-pro, gemini-3-flash
grok, kimi-k2.5
auto is the safe default — Cursor picks the right model for the job.
Example
{
"adapterType": "cursor",
"adapterConfig": {
"cwd": "/Users/me/projects/paperclip-workspace",
"model": "auto",
"promptTemplate": "You are the engineering lead. Work carefully and report progress.",
"timeoutSec": 300,
"graceSec": 15
}
}