paperclip-docs

265 Commits 57 Branches 11 Tags

3 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
Aron PrinsandClaude Opus 4.8	6c4519af4a	Release docs for paperclip v2026.824.0 (#110 ) 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]>	2026-08-25 10:02:16 +02:00
Aron PrinsandClaude Opus 4.7	2b5368e5af	release: address v2026.512.0 coverage gaps Closes the four coverage gaps surfaced by the docs audit: Gap 1 — env vars (verify-edit: 0 high-confidence unverified) - docs/reference/deploy/environment-variables.md - Added `BETTER_AUTH_SECRET` row to "Deployment And Auth" (falls back to `PAPERCLIP_AGENT_JWT_SECRET`; server refuses to start without either), and `SERVE_UI` row to "Server Configuration" (overrides `server.serveUi`). Both values copied verbatim from parent at v2026.512.0 (.env.example + server/src/auth/better-auth.ts). Gap 2 — skill bundles (verify-edit: 0 unverified) - docs/reference/skills.md - Added one-liner entries for `diagnose-why-work-stopped`, `paperclip-converting-plans-to-tasks`, `para-memory-files`, `terminal-bench-loop`. Descriptions distilled from each parent `SKILL.md` frontmatter at v2026.512.0. Gap 3 — Plugin SDK page (verify-edit: 0 high-confidence unverified) - docs/reference/plugins/sdk.md (new) - site/content.json (new "Plugins" section under Reference tier) - Comprehensive reference for @paperclipai/plugin-sdk. Every public export (definePlugin, runWorker, startWorkerRpcHost, test harness, bundler presets, dev server, host-client factory, JSON-RPC protocol helpers, all manifest/protocol types, zod re-export, constants) is listed verbatim from packages/plugins/sdk/src/index.ts at v2026.512.0. 13 unverified items are SHOUT_CASE SDK constants mis-classified as env vars by verify-edit (all confidence: null). Gap 4 — REST routes (verify-edit: 0 high-confidence unverified) - docs/reference/api/adapters.md (new) — 9 endpoints from server/src/routes/adapters.ts. - docs/reference/api/plugins.md (new) — install/lifecycle/config/jobs/ webhooks/local-folders/bridge endpoints from server/src/routes/plugins.ts. - docs/reference/api/instance-admin.md (new) — umbrella covering instance-settings, instance-database-backups, llms reflection, environments, and execution-workspaces. - site/content.json — added the three new pages to the API section. - All seven flagged route files turned out to be public/admin surfaces; none qualified as internal-only. FOLLOW-UPS.md - Added "Internal REST routes — intentionally undocumented" section recording the Gap 4 triage outcome. Verification gates - npm run sync:test — 26/26 passed - npm run docs:build — clean (90 markdown files) - npm run sync:lint-links — same 3 pre-existing broken screenshots - npm run sync:verify-nav — same 1 pre-existing orphan - check-drift: 41 -> 43 (+2; both are the new SERVE_UI / BETTER_AUTH_SECRET rows hitting the known env-var-missing false-positive class tracked in FOLLOW-UPS.md; the routes-missing item for instance-admin.md is a filename-normalization false positive — routes exist in parent). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>	2026-05-13 15:51:54 +02:00

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

Aron PrinsandClaude Opus 4.8

6c4519af4a

Release docs for paperclip v2026.824.0 (#110 )

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]>

2026-08-25 10:02:16 +02:00

Aron PrinsandClaude Opus 4.7

2b5368e5af

release: address v2026.512.0 coverage gaps

Closes the four coverage gaps surfaced by the docs audit:

Gap 1 — env vars (verify-edit: 0 high-confidence unverified)
- docs/reference/deploy/environment-variables.md
- Added `BETTER_AUTH_SECRET` row to "Deployment And Auth" (falls back
  to `PAPERCLIP_AGENT_JWT_SECRET`; server refuses to start without
  either), and `SERVE_UI` row to "Server Configuration" (overrides
  `server.serveUi`). Both values copied verbatim from parent at
  v2026.512.0 (.env.example + server/src/auth/better-auth.ts).

Gap 2 — skill bundles (verify-edit: 0 unverified)
- docs/reference/skills.md
- Added one-liner entries for `diagnose-why-work-stopped`,
  `paperclip-converting-plans-to-tasks`, `para-memory-files`,
  `terminal-bench-loop`. Descriptions distilled from each parent
  `SKILL.md` frontmatter at v2026.512.0.

Gap 3 — Plugin SDK page (verify-edit: 0 high-confidence unverified)
- docs/reference/plugins/sdk.md (new)
- site/content.json (new "Plugins" section under Reference tier)
- Comprehensive reference for @paperclipai/plugin-sdk. Every public
  export (definePlugin, runWorker, startWorkerRpcHost, test harness,
  bundler presets, dev server, host-client factory, JSON-RPC protocol
  helpers, all manifest/protocol types, zod re-export, constants)
  is listed verbatim from packages/plugins/sdk/src/index.ts at
  v2026.512.0. 13 unverified items are SHOUT_CASE SDK constants
  mis-classified as env vars by verify-edit (all confidence: null).

Gap 4 — REST routes (verify-edit: 0 high-confidence unverified)
- docs/reference/api/adapters.md (new) — 9 endpoints from
  server/src/routes/adapters.ts.
- docs/reference/api/plugins.md (new) — install/lifecycle/config/jobs/
  webhooks/local-folders/bridge endpoints from
  server/src/routes/plugins.ts.
- docs/reference/api/instance-admin.md (new) — umbrella covering
  instance-settings, instance-database-backups, llms reflection,
  environments, and execution-workspaces.
- site/content.json — added the three new pages to the API section.
- All seven flagged route files turned out to be public/admin surfaces;
  none qualified as internal-only.

FOLLOW-UPS.md
- Added "Internal REST routes — intentionally undocumented" section
  recording the Gap 4 triage outcome.

Verification gates
- npm run sync:test       — 26/26 passed
- npm run docs:build      — clean (90 markdown files)
- npm run sync:lint-links — same 3 pre-existing broken screenshots
- npm run sync:verify-nav — same 1 pre-existing orphan
- check-drift: 41 -> 43 (+2; both are the new SERVE_UI / BETTER_AUTH_SECRET
  rows hitting the known env-var-missing false-positive class tracked
  in FOLLOW-UPS.md; the routes-missing item for instance-admin.md is a
  filename-normalization false positive — routes exist in parent).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

2026-05-13 15:51:54 +02:00