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]>
5.2 KiB
paperclip_version, seo_title, seo_description
| paperclip_version | seo_title | seo_description |
|---|---|---|
| v2026.824.0 | Tailscale HTTPS Broker | Hand out real, cert-valid https preview URLs for the dev servers running inside managed workspaces, instead of untrusted or unreachable links. |
Tailscale HTTPS Broker
Use this page when you want a Paperclip instance to hand out real, cert-valid https:// preview URLs for the dev servers running inside its managed workspaces — instead of only loopback URLs.
That capability is opt-in per service, and it depends on a small host-side helper: the Tailscale HTTPS broker. This page is for the operator who installs and runs it.
What The Broker Is
When a workspace runtime service opts into HTTPS exposure, Paperclip needs to publish an HTTPS listener on the local Tailscale node that forwards to the service's loopback port. That publishing step touches the host's Tailscale state, so Paperclip does not do it from the app process. It delegates to a dedicated broker that runs as its own least-privilege host service and does exactly one job: manage Paperclip-owned, tailnet-only HTTPS-to-loopback mappings, and nothing else.
Keeping the broker separate is the whole point. The app never gets to mutate Tailscale directly, the broker only accepts a narrow, validated set of requests, and the surface it can touch is deliberately tiny.
Why It Runs Separately
The broker is designed deny-by-default. It manages only the mappings Paperclip created, and it refuses anything outside that lane:
- It never touches
:443. Your instance's primary:443 → 127.0.0.1:3100route is left alone; the broker rejects port443outright, along with other privileged and reserved ports, and any ports an operator has explicitly protected. - It only manages Paperclip-owned mappings. Existing Tailscale Serve routes and services you set up yourself are out of scope — the broker will not remove or rewrite them.
- It fails closed. Missing or unsafe configuration makes the broker refuse to start rather than come up silently protecting nothing. A configured HTTPS preview is never reported healthy on a plain-HTTP fallback.
Because it runs as its own account, a compromise or bug in the app can't quietly reach into Tailscale — the app can only ask the broker, and the broker only does the narrow thing it was built for.
The Dedicated Account And Unit
The broker runs under its own system account, paperclip-tsbroker, with no login shell, and is managed by a packaged systemd unit (paperclip-tailscale-https-broker.service). The app talks to it over a Unix socket rather than the network.
The unit runs as User=paperclip-tsbroker and loads its settings from an environment file:
EnvironmentFile=/etc/paperclip/tailscale-https-broker.env
Keep that file readable only by root and the broker account — it names the identities the broker trusts.
The Environment File
Every setting is read from /etc/paperclip/tailscale-https-broker.env. The four identity variables are required; the rest have safe defaults. If a required value is missing, or a path or port is unsafe, the broker refuses to start.
| Variable | Required | Default | Purpose |
|---|---|---|---|
BROKER_NODE_IDENTITY |
Yes | — | Identity of the local Tailscale node the broker publishes HTTPS mappings on. |
BROKER_SERVICE_UID |
Yes | — | UID the broker service itself runs as. |
BROKER_SERVICE_GID |
Yes | — | GID the broker service itself runs as. |
BROKER_RUNTIME_UID |
Yes | — | UID of the Paperclip runtime account allowed to make requests. |
BROKER_PROTECTED_PORTS |
No | (empty) | Ports the broker must never mutate. A malformed list makes the broker refuse to start rather than protect nothing. |
BROKER_SOCKET_PATH |
No | /run/paperclip-tailscale-broker/broker.sock |
Unix socket the broker listens on for requests from the app. |
BROKER_REGISTRY_PATH |
No | /var/lib/paperclip-tailscale-broker/registry.json |
Where the broker records the mappings it owns, for reconciliation. |
BROKER_AUDIT_PATH |
No | /var/log/paperclip-tailscale-broker/audit.log |
Append-only log of every allow/deny decision and mutation outcome. |
BROKER_TAILSCALE_BIN |
No | /usr/bin/tailscale |
Path to the tailscale binary. Must be absolute, or the broker refuses to start. |
Security Posture At A Glance
If you remember only a few things about the broker, remember these:
- Deny-by-default. The broker only manages Paperclip-owned, tailnet-only mappings; everything else is rejected.
:443is untouched. Your primary instance route is protected, and port443is refused along with other privileged, reserved, and operator-protected ports.- Fail-closed. Bad or missing config stops the broker from starting; an exposure is never reported ready on a plain-HTTP fallback.
- Least privilege. A dedicated
paperclip-tsbrokeraccount with no login shell, a narrow socket interface, and an audit trail atBROKER_AUDIT_PATH.
Related Pages
- Tailscale Private Access — reach the Paperclip instance itself over your tailnet.
- Environment Variables — the full set of instance environment variables.