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.7 KiB
paperclip_version, seo_title, seo_description
| paperclip_version | seo_title | seo_description |
|---|---|---|
| v2026.707.0 | Cloud Sync to a Paperclip Upstream | Push a local company — agents, projects, issues, skills, portability files — into a Paperclip Cloud stack, previewing exactly what would change first. |
Cloud Sync
Deprecated — being removed. Host-to-host Cloud Sync has been retired upstream and replaced by full-fidelity company Import/Export, which moves a company — agents, projects, issues, skills, portability files — between any two instances (local-to-local, over a URL, or from GitHub) without the experimental flag or a live upstream connection. See Back up and restore a company. This page is kept temporarily for anyone on an older build and will be removed in a future release.
Cloud Sync connects a locally-run Paperclip instance to a Paperclip Cloud upstream so you can push a local company — agents, projects, issues, skills, portability files — into a cloud stack. You preview exactly what would change, resolve conflicts, push, and then review activation before any automation resumes on the cloud side.
Why it exists
Plenty of companies start life on a laptop. Cloud Sync is the migration path: move that local company to a hosted stack without hand-exporting, with a dry-run preview and schema-compatibility check first, and with cloud automations paused until you explicitly activate them so nothing fires unexpectedly mid-move.
Turn it on
- Go to Settings → Instance settings → Experimental.
- Turn on Cloud Sync — "Show local Paperclip Cloud upstream connection, preview, push, retry, and activation review surfaces."
Unlike most flags on the page, this one gates the API too: with it off, the cloud-upstream endpoints refuse requests and paperclipai cloud push errors out — not just hidden UI.
Using it
- Open Company Settings → Cloud upstream (the nav item appears once the flag is on).
- Connect — paste your Paperclip Cloud stack URL and approve the authorization grant on the cloud side.
- Preview push — a summary of what will be sent, with warnings, conflicts, and a schema-compatibility check. Push stays disabled until the schemas are compatible.
- Push to cloud — creates a push run with live progress, a downloadable report, and Retry/Re-run on failure.
- Review activation — after a push completes, the activation table lets you decide which entity types (agents, routines, monitors) wake up on the cloud stack.
The step-by-step recipe — including the CLI flow and troubleshooting — is in Sync a local company to a Paperclip Cloud upstream.
When it's off
The Cloud upstream page shows "Cloud sync is disabled. Enable it in Instance Settings to show upstream connection and push tools.", the Send to Paperclip Cloud button disappears, and the API and CLI refuse cloud-sync operations. Saved connections and run history are preserved and return when you re-enable.
Caveats
- Requires board-level access on the local instance and enough rights on the cloud stack to approve the authorization grant.
- The target stack must advertise the
cloud_synctransfer feature. - Pushes are gated on schema compatibility between the two stacks — upgrade the older side if the preview reports a mismatch.
Where to go next
- Sync a local company to a Paperclip Cloud upstream — the full how-to.
- Company export & import — the offline alternative for moving companies.
- Experimental features overview