paperclip-docs

paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-09 17:41:56 -10:00

Commit Graph

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
Dotta DevRel Gemini Paperclip	c7b3f4cacf	Render full SKILL.md as a code snippet on per-skill pages (PAP-16980) (#89 ) > Updated on current main: #87 and the #90 cache hotfix are merged. This PR now targets `main`, was rebased onto merge commit `8c5976f`, and has a fresh successful Cloudflare preview plus post-rebase browser smoke evidence. ## What & why (PAP-16980) Improves SEO/AEO on the bundled/optional per-skill reference pages (from PAP-16670) by clearly separating the human-readable catalog summary (top of page) from the authoritative full skill definition. Previously the "Full skill definition" section rendered the `SKILL.md` as parsed Markdown, so each skill's own `##` headings, lists, and fenced examples became real page content — competing with the summary, inflating the on-page TOC (e.g. qa-acceptance went from 16 → 6 "On this page" entries), and confusing crawlers/answer engines about the page's true structure. Now each per-skill page shows the complete, verbatim `SKILL.md` (frontmatter + body) inline, rendered through the existing production code-snippet treatment. ## Changes - Content (10 per-skill pages): replaced the old `### Skill frontmatter` bullets + parsed `### Skill instructions` layout with the full `SKILL.md` embedded in a fenced ````markdown skill-source` block. Source bytes were taken verbatim from each skill's authoritative `SKILL.md` at the page's pinned `paperclip_version`, verified against the page's own prior instructions body + frontmatter (name/description) so no content drifted. - Renderers (`site/build-release.mjs`, `site/app.js`): a `skill-source` fence renders as `<pre><code class="language-markdown" data-skill-download="SKILL.md">`. Every other code block is delegated to marked's default renderer, so existing snippets are byte-for-byte unchanged. Rendered identically in the crawler-visible build HTML and on client SPA navigation. - Copy + Download (`site/app.js`, `site/styles.css`): `decorateCodeBlocks` reuses the existing Copy affordance and adds a Download `SKILL.md` control beside it. Both share dimensions, styling, hover/focus visibility, and the copied-success state; both carry accessible labels/titles. - Readable full-source wrapping (`site/styles.css`): only the downloadable `SKILL.md` block uses `white-space: pre-wrap` and safe long-token wrapping. Ordinary code snippets retain the existing horizontal-scroll treatment. - Test: `scripts/verify-skill-source-blocks.mjs` (`npm run docs:test:skill-source-blocks`) asserts the render contract (single H1, single `<pre>`, frontmatter present, no legacy headings) and that ordinary docs pages emit no `data-skill-download`. ## Scope statement No catalog-page layout, navigation, typography, summary-copy, metadata-card, or information-architecture changes. `paperclip-website` and generated `.site/` output are untouched. `optional/finance/ramp.md` is intentionally excluded — it is a newer summary page with no embedded full-definition section to reformat. The diff is the 10 skill pages + the narrow renderer/Copy-Download support + the test. ## Evidence 1–2. Before/after (desktop, 1280×900) + mobile after (390×844) — attached to Paperclip issue [PAP-16980](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/3098577a-4f6f-4eb2-9151-a4b61917dffd) (`before-desktop.png`, `after-desktop-controls.png`, `after-controls-zoom.png`, `after-mobile.png`). GitHub cannot render the auth-gated attachment URLs inline, so they live on the issue for reviewers. 4. Raw DOM/HTML (build output, qa-acceptance): - Article renders exactly one H1: `<h1 id="qa-acceptance">QA Acceptance</h1>` - Full source inside a single code block: ```html <pre><code class="language-markdown" data-skill-download="SKILL.md">--- name: qa-acceptance description: Produce QA acceptance criteria and a manual validation plan … key: paperclipai/bundled/quality/qa-acceptance recommendedForRoles: - qa … </code></pre> ``` - Article `<pre>` count: 1 (inner ````` fences stay literal — no breakout). 10/10 skill pages carry the block; 0 non-skill pages do. 5. Copy + Download behavior (Playwright against the built site): ```json { "downloadFilename": "SKILL.md", "downloadMatchesBlock": true, // downloaded file === code block text, byte-identical "downloadBytes": 3853, "copyShowsSuccess": true, // Copy toggles the existing is-copied success state "accessibleLabels": { "copy": "Copy code", "download": "Download SKILL.md" } } ``` Both controls reach `opacity: 1` on `.code-wrap:hover` and on keyboard `:focus-visible` (verified `matches(':focus-visible') === true` → computed opacity `1`). H1 audit (every generated route, incl. all skill URLs — requested on the issue): built the site on current `main` and scanned all 184 generated `index.html` routes (16 skill routes among them). Every route has exactly one `<h1>`. The skill source's own `#`/`##` headings live inside the `<pre><code>` block as literal text, so they do not create competing H1s — the SEO/AEO goal. ## Tests Run against current `main` after #87 and #90: ``` docs:build ............................. ok (184 routes) docs:test:static-routes ................ pass (5 routes + 404 + root + subpath) docs:test:skill-source-blocks .......... pass (10 skill pages, 1 control page) H1 audit (all 184 routes) .............. pass (exactly 1 h1 each; 16 skill routes) ``` Do not merge/deploy — returning to Dotta/reviewers for approval per PAP-16980. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]>	2026-08-10 14:03:47 -07:00
DottaandPaperclip	5b4b489154	[codex] Add Skills docs hierarchy (#34 ) ## Summary - Add generated reference pages for bundled and optional skills. - Add Skills index pages and hierarchy-aware sidebar/breadcrumb navigation. - Add verification scripts for hierarchical Skills routes and static docs routes. ## Verification - `npm run sync:verify-nav` - `npm run docs:test:static-routes` - `npm run docs:build` - QA in PAP-11775 also verified browser rendering for hierarchy, bundled `task-planning`, and optional `last30days` pages with screenshots. ## Issues - PAP-11770 - PAP-11783 --------- Co-authored-by: Paperclip <[email protected]>	2026-06-24 08:32:10 -05: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

c7b3f4cacf

Render full SKILL.md as a code snippet on per-skill pages (PAP-16980) (#89 )

> **Updated on current main:** #87 and the #90 cache hotfix are merged.
This PR now targets `main`, was rebased onto merge commit `8c5976f`, and
has a fresh successful Cloudflare preview plus post-rebase browser smoke
evidence.

## What & why (PAP-16980)

Improves SEO/AEO on the bundled/optional **per-skill reference pages**
(from PAP-16670) by clearly separating the *human-readable catalog
summary* (top of page) from the *authoritative full skill definition*.

Previously the "Full skill definition" section rendered the `SKILL.md`
as **parsed Markdown**, so each skill's own `##` headings, lists, and
fenced examples became real page content — competing with the summary,
inflating the on-page TOC (e.g. qa-acceptance went from **16 → 6** "On
this page" entries), and confusing crawlers/answer engines about the
page's true structure.

Now each per-skill page shows the **complete, verbatim `SKILL.md`**
(frontmatter + body) inline, rendered through the **existing production
code-snippet treatment**.

## Changes

- **Content (10 per-skill pages):** replaced the old `### Skill
frontmatter` bullets + parsed `### Skill instructions` layout with the
full `SKILL.md` embedded in a fenced ````markdown skill-source` block.
Source bytes were taken verbatim from each skill's authoritative
`SKILL.md` at the page's pinned `paperclip_version`, verified against
the page's own prior instructions body + frontmatter (name/description)
so no content drifted.
- **Renderers (`site/build-release.mjs`, `site/app.js`):** a
`skill-source` fence renders as `<pre><code class="language-markdown"
data-skill-download="SKILL.md">`. Every other code block is delegated to
marked's default renderer, so existing snippets are byte-for-byte
unchanged. Rendered identically in the crawler-visible build HTML and on
client SPA navigation.
- **Copy + Download (`site/app.js`, `site/styles.css`):**
`decorateCodeBlocks` reuses the existing Copy affordance and adds a
**Download `SKILL.md`** control beside it. Both share dimensions,
styling, hover/focus visibility, and the copied-success state; both
carry accessible labels/titles.
- **Readable full-source wrapping (`site/styles.css`):** only the
downloadable `SKILL.md` block uses `white-space: pre-wrap` and safe
long-token wrapping. Ordinary code snippets retain the existing
horizontal-scroll treatment.
- **Test:** `scripts/verify-skill-source-blocks.mjs` (`npm run
docs:test:skill-source-blocks`) asserts the render contract (single H1,
single `<pre>`, frontmatter present, no legacy headings) and that
ordinary docs pages emit no `data-skill-download`.

## Scope statement

No catalog-page layout, navigation, typography, summary-copy,
metadata-card, or information-architecture changes. `paperclip-website`
and generated `.site/` output are untouched. `optional/finance/ramp.md`
is intentionally excluded — it is a newer summary page with no embedded
full-definition section to reformat. The diff is the 10 skill pages +
the narrow renderer/Copy-Download support + the test.

## Evidence

**1–2. Before/after (desktop, 1280×900) + mobile after (390×844)** —
attached to Paperclip issue
[PAP-16980](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/3098577a-4f6f-4eb2-9151-a4b61917dffd)
(`before-desktop.png`, `after-desktop-controls.png`,
`after-controls-zoom.png`, `after-mobile.png`). GitHub cannot render the
auth-gated attachment URLs inline, so they live on the issue for
reviewers.

**4. Raw DOM/HTML (build output, qa-acceptance):**
- Article renders exactly **one H1**: `<h1 id="qa-acceptance">QA
Acceptance</h1>`
- Full source inside a single code block:
```html
<pre><code class="language-markdown" data-skill-download="SKILL.md">---
name: qa-acceptance
description: Produce QA acceptance criteria and a manual validation plan …
key: paperclipai/bundled/quality/qa-acceptance
recommendedForRoles:
  - qa
  …
</code></pre>
```
- Article `<pre>` count: **1** (inner ````` fences stay literal — no
breakout). 10/10 skill pages carry the block; 0 non-skill pages do.

**5. Copy + Download behavior (Playwright against the built site):**
```json
{
  "downloadFilename": "SKILL.md",
  "downloadMatchesBlock": true,     // downloaded file === code block text, byte-identical
  "downloadBytes": 3853,
  "copyShowsSuccess": true,          // Copy toggles the existing is-copied success state
  "accessibleLabels": { "copy": "Copy code", "download": "Download SKILL.md" }
}
```
Both controls reach `opacity: 1` on `.code-wrap:hover` and on keyboard
`:focus-visible` (verified `matches(':focus-visible') === true` →
computed opacity `1`).

**H1 audit (every generated route, incl. all skill URLs — requested on
the issue):** built the site on current `main` and scanned **all 184
generated `index.html` routes** (16 skill routes among them). **Every
route has exactly one `<h1>`.** The skill source's own `#`/`##` headings
live *inside* the `<pre><code>` block as literal text, so they do
**not** create competing H1s — the SEO/AEO goal.

## Tests

Run against current `main` after #87 and #90:

```
docs:build ............................. ok (184 routes)
docs:test:static-routes ................ pass (5 routes + 404 + root + subpath)
docs:test:skill-source-blocks .......... pass (10 skill pages, 1 control page)
H1 audit (all 184 routes) .............. pass (exactly 1 h1 each; 16 skill routes)
```

**Do not merge/deploy** — returning to Dotta/reviewers for approval per
PAP-16980.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>

2026-08-10 14:03:47 -07:00

DottaandPaperclip

5b4b489154

[codex] Add Skills docs hierarchy (#34 )

## Summary

- Add generated reference pages for bundled and optional skills.
- Add Skills index pages and hierarchy-aware sidebar/breadcrumb
navigation.
- Add verification scripts for hierarchical Skills routes and static
docs routes.

## Verification

- `npm run sync:verify-nav`
- `npm run docs:test:static-routes`
- `npm run docs:build`
- QA in PAP-11775 also verified browser rendering for hierarchy, bundled
`task-planning`, and optional `last30days` pages with screenshots.

## Issues

- PAP-11770
- PAP-11783

---------

Co-authored-by: Paperclip <[email protected]>

2026-06-24 08:32:10 -05:00