paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-09 17:41:56 -10:00
Code Issues Packages Projects Releases Wiki Activity
265 Commits 59 Branches 11 Tags
codex/https-setup-guide
Commit Graph
3 Commits
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.7 c7a93614ee release: address review gaps from catchup-2 
- cursor-cloud.md: add JSON Example block with adapterType: cursor_cloud
  mirroring claude-local's structure (placeholder secret-ref for
  env.CURSOR_API_KEY).
- acpx-local.md: add JSON Example block with adapterType: acpx_local
  plus a leading sentence reiterating the staged-runtime callout.
- environment-variables.md: audited 428->512 window via compare-window.mjs
  intersected with the env-vars watcher's parent_paths; only
  server/src/config.ts and a new cloudflare driver config.ts touched —
  no new env-vars beyond the existing PAPERCLIP_SECRETS_STRICT_MODE row
  (refactor only). Frontmatter bumped to v2026.512.0.
- FOLLOW-UPS.md: track deferred items (tutorial narrative additions,
  sandbox per-vendor depth, drift triage, screenshot anchors,
  pre-existing doc issues).

verify-edit.mjs: 79 claims verified across the 3 verifiable touched
files (cursor-cloud 26/27, acpx-local 20/21, environment-variables
33/62). Remaining unverified records are pre-existing false-positive
classes documented in FOLLOW-UPS.md (env-vars watcher source list,
adapter-config envelope key not present in adapter package source,
placeholder secret-id literal).

Build clean. sync:test 26/26. sync:lint-links and sync:verify-nav
unchanged from baseline (same 3 pre-existing broken screenshot refs,
same 1 pre-existing orphan).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
 2026-05-13 14:38:17 +02:00
Aron PrinsandClaude Opus 4.7 c27d427dd9 release: bring docs forward to v2026.512.0 
Manifest summary:
- pr/cli-commands: NEW `paperclipai secrets list|declarations|create|link|doctor|providers|migrate-inline-env` command group [evidence: cli/src/commands/client/secrets.ts added].
- pr/adapters/cursor-cloud: NEW adapter package (genuinely new per detect-renames; agentConfigurationDoc surfaced from src/index.ts).
- pr/adapters/acpx-local: NEW adapter package (genuinely new); ACPX runtime execution still being enabled in stages.
- pr/adapters (sandbox-providers): NEW cloudflare, daytona, exe-dev sandbox provider plugins (genuinely new per detect-renames). E2B already shipped in v2026.427.0; now grouped with siblings on the new sandbox-providers page.
- auto-merge/env-vars: 20 file matches but no new env vars added beyond a code re-org of PAPERCLIP_SECRETS_STRICT_MODE.
- pr/rest-routes: 12 modifications, no new top-level routes.
- pr/agent-skills: NEW skills/diagnose-why-work-stopped and skills/terminal-bench-loop (genuinely new) — internal skills.
- pr/plugin-sdk, pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal.

Edits applied: 5
- docs/reference/adapters/cursor-cloud.md (NEW page mirroring cursor-local structure)
- docs/reference/adapters/acpx-local.md (NEW page mirroring claude-local structure)
- docs/reference/adapters/sandbox-providers.md (NEW page covering cloudflare, daytona, exe-dev, e2b)
- docs/reference/cli/commands.md (add `secrets` command group; bump paperclip_version)
- site/content.json (nav additions: Cursor Cloud, ACPX Local, Sandbox Providers in Adapters Reference)

Verification:
- All `paperclipai secrets` subcommand names and flags verified verbatim against cli/src/commands/client/secrets.ts.
- All cursor-cloud and acpx-local field names verified verbatim against agentConfigurationDoc strings in packages/adapters/*/src/index.ts.
- Sandbox provider env vars (DAYTONA_API_KEY, EXE_API_KEY, E2B_API_KEY) flagged as high-confidence-unverified — known false positives: these env vars are documented in plugin README.md and plugin manifest.ts files, not in server/src/config.ts. verify-edit.mjs only searches the server env source set. Logged in CATCHUP_RUN_REPORT_2.md.

Renames detected: none (detect-renames confirmed all five new dirs are genuinely new)
Reconcile flags: none

Release notes one-liner: "Secrets CLI, Cursor Cloud and ACPX adapters, Cloudflare/Daytona/exe.dev sandbox providers."

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
 2026-05-13 14:09:34 +02:00