## 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]>
Cumulative docs sync from v2026.817.0 to the v2026.824.0 stable tag.
New/updated: Tailscale HTTPS broker, workspaces HTTPS exposure, release channels + `paperclipai channels`, resumable company import (guide + companies API), secret catalog, Claude setup-token login, adapter device-login, issue file-resource availability, document comments, interaction resolver-policy/governance. Version-stamped touched pages and added the v2026.824.0 docs-changelog entry.
Verified every page against the v2026.824.0 tag; stripped post-tag master leaks (Kimi adapter, reaper-cooldown env var, mission-less onboarding rewrite) that nightly had drafted ahead of the release. Screenshots flagged (192 stale) but not recaptured this release.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
- The per-project Workspaces tab is hidden until the project has workspace
activity (showWorkspacesTab requires summaries > 0); say so instead of
'shows up on each project', and drop the never-shown per-project empty
string. The reliable empty state is the company-wide 'No workspace
activity yet.'
- Correct the surfacing rule: a primary workspace surfaces because it's the
primary (not 'has a working directory and runtime config'); non-primary
project workspaces need runtime services/config.
- Replace the stale 'Each entry shows' list (old table columns: mode /
provider type / opened) with the actual ProjectWorkspaceSummaryCard fields
(kind, name, branch, path, services, status, linked tasks, updated).
- Note plugin tabs appear alongside the base tabs (e.g. workspace-diff's
Changes tab), not strictly after them.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A user reported the Workspaces screen looked empty with "no options," and
that all but one of the workspace screenshots were blank/identical.
Both were real problems:
Docs (docs/guides/projects-workflow/workspaces.md)
- Add a "Before you start" section: workspaces are gated behind the
experimental "Enable Isolated Workspaces" flag, the screen is monitor-only
(no manual create), and it stays empty until an agent runs an isolated
task — with the actual empty-state strings ("No workspace activity yet." /
"No non-default workspace activity yet.").
- Correct the detail screen: it now has Tasks / Services / Configuration /
Runtime logs / Routines tabs (+ plugin tabs), not "three tabs." Rename the
Issues tab to Tasks (its real label) and add a Services tab section. The
former "Workspace commands panel above the tabs" is now the Services tab
plus header quick controls.
- Clarify the company-wide Workspaces screen vs. the per-project Workspaces
tab and the surfacing rules. Fix the misleading "multiple isolated
workspaces" caption.
Screenshots
- Root cause: the seed only created a *project* workspace and pointed the
execution-workspace detail routes at its id, so those pages were captured
mid "Loading workspace…". Execution workspaces have no REST create endpoint
(they're provisioned by a real heartbeat), so seed-execution-workspace.mjs
now inserts a realistic one directly into the instance's embedded Postgres:
an isolated git-worktree workspace with runtime config, a running service,
provision/start/failed-job operation logs, and linked tasks.
- routes.mjs: add the {executionWorkspaceId} token, repoint the detail routes
to it, add a Services tab target, and drop the duplicate
org/execution-workspaces-list target (same URL as workspaces/list).
- Recaptured workspaces/{list,configuration,services,runtime-logs,issues} in
light + dark; all now render real content.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Recapture the 82 stale screenshots (light + dark, 1440×900 @2x) against
a release-code instance booted at v2026.529.0 (911a1e8). Registry was
already stamped at that SHA, so captured_sha is unchanged.
Verification pass against the release codebase also found one authored
claim wrong: the execution-workspace environment precedence is
issue → project → agent → instance default (project policy outranks an
agent's own default), not issue → agent → project. Corrected
docs/guides/projects-workflow/workspaces.md to match
server/src/services/execution-workspace-policy.ts.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add the two release features quarantined from nightly, and stamp
paperclip_version on every touched page.
- Claude Local: document UI-driven live model discovery (#6953) —
/v1/models lookup via ANTHROPIC_API_KEY, 60s cache, built-in fallback,
Bedrock IDs, and the refresh control.
- Workspaces: document reused-workspace environment consistency and
finalize-gated dependent wakes / interaction.accept (#6969).
- Stamp paperclip_version: v2026.529.0 on all 14 touched pages.
- Regenerate SCREENSHOTS_PENDING.md: 90/276 stale for this window.
Inherits the six features already drafted on nightly: resource
memberships (#6677), document annotations (#6733), bundled plugins in
plugin manager (#6734), skills CLI + catalog (#6782), first-admin
claim (#6755).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Captured all required screenshots for the new IA in both light and dark
mode using the Horizon Labs company (PAP). Fixed the app's theme toggle
(ignores prefers-color-scheme; requires clicking its own toggle button)
so all dark shots use the real dark theme.
Fixed broken screenshot paths in administration and guides docs:
- Corrected guides/ path prefix in administration docs
- Updated images/ references to screenshots/light/ across all guides
- Fixed filename mismatches (e.g. dashboard-tab.png → dashboard.png)
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
