2 Commits

Include renames

Author	SHA1	Message	Date
Aron PrinsandClaude Opus 5	325c9eb819	seo: hand-write titles and descriptions for all 192 pages (#115) ... ## 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]>	2026-08-25 22:51:42 +02:00
4 people	8121a9c947	Release docs for paperclip v2026.720.0 (#67) ... Ships the docs for **paperclip v2026.720.0** to `docs.paperclip.ing`. Window: `v2026.707.0...v2026.720.0` — 196 commits, 1,523 changed files, 0 truncated leaves. Most of this release was already drafted on `nightly` over the past cycle (Cases, Folders, Decision Training, Attention, Built-in Agents, company skill policy, inbox agent policy, `costStatus`, the ACP engine graduation and `acpx_local` retirement, and `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET`). This PR adds the surfaces nightly had **not** yet covered, then stamps the release version across everything touched this cycle. ## New pages **`docs/reference/api/tool-gateway.md`** — the MCP Tool Gateway, the headline experimental feature. Covers applications and connections, catalog entries and risk levels, profiles/entries/bindings, the tool-access policy and its decision outcomes, named MCP gateways and their tokens, the audit feed, and the Smoke Lab. Documents the five `tools:*` permission keys and the viewer/membership rules on routes that don't use a permission key. Flags both experimental gates (`enableApps`, and `enableSmokeLab` separately). **`docs/reference/api/summary-slots.md`** — the built-in Summarizer and summary slots. Covers slot addressing (`scopeKind` / `scopeId` / `slotKey`), generation, revisions, and the `enableSummaries` gate. Cross-references Built-in Agents rather than duplicating it. ## Updated **`docs/guides/org/skills.md`** — Skill Studio (the three-pane authoring workspace, saved inputs, test runs and their unavailability reasons, run templates, version history), nested skill folders and the My Skills view, importing skills straight from a project, and company skill forks. Cross-references the existing Folders and Company Skill Policy API pages instead of restating them. ## Release stamping `paperclip_version: v2026.720.0` applied to all 26 pages touched this cycle — bumped on 10 that already had frontmatter, added to 13 that had none (including the API pages nightly authored, which were intentionally versionless until they merged to `main`). ## ↻ Renames detected `detect-renames.mjs` reports no directory renames. It flags one `removed_dirs_no_match`: - `packages/adapters/acpx-local` — **already reconciled on nightly.** The adapter was retired upstream (ACP became a capability of each harness adapter rather than a standalone adapter). `docs/reference/adapters/acpx-local.md` is now a retired stub that points at Claude Code / Codex / Gemini CLI and documents the automatic migration. No action needed. ## Screenshots — full overhaul recommended **248 of 298** registry entries are stale. This release landed a design-system convergence (single-source design tokens, retuned theme, broad Card/Badge adoption, a multiplicative radius ladder, unified list surfaces, Lucide task-status glyphs), so nearly every captured surface moved. This is an overhaul cycle, not a targeted refresh: ```sh npm run screenshots:refresh:all ``` Full per-entry breakdown in `SCREENSHOTS_PENDING.md`. Captures go to their own PR for review — nothing is auto-pushed. ## Verification - **Drift:** clean — 0 records against `903bd15` (8 parent paths, 57 CLI commands, 66 env vars, 389 REST routes, 18 permission keys, 4 roles). - **Claim verification:** `verify-edit.mjs` against `v2026.720.0` — **0 unverified, 0 suspicious** across all three authored files. - **Reconciliation:** no disappeared manifest entries. - **`npm run docs:build`:** passes — 169 markdown files, sitemap and robots generated. - **`npm run sync:check`:** links clean (172 files), nav clean, screenshots indexed, drift clean. - **Nav orphans:** `docs/reference/cli/commands.md` and `docs/reference/cli/control-plane-commands.md` — intentional redirect anchors, expected. `.sync-state.json` bumped to `base_release_tag: v2026.720.0` / `base_release_sha: 903bd157…`, which also repoints the drift checker's pinned ref (the previous `f12bb27…` no longer resolves upstream). No open `nightly-draft/*` PRs to fold in. ## Checklist - [ ] Tool Gateway page reads correctly for an operator enabling `enableApps` for the first time - [ ] Summary Slots experimental gating is accurate - [ ] Skill Studio guide matches what you see in the running UI - [ ] Decide whether to run the screenshot overhaul before or after merging this - [ ] **After squash-merging: run `node scripts/sync/realign-nightly.mjs release/v2026.720.0 --push` before the next nightly sync.** The squash severs `main`↔`nightly` ancestry; the realign (shipped in this PR) prevents add/add conflicts at the next nightly run. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]>	2026-07-20 19:59:18 +02:00