paperclip-docs

paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 18:37:25 -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
Aron Prins Claude Opus 4.8 DevRel Gemini Paperclip Dotta ClaudeCoder	631a6a0c53	Release docs for paperclip v2026.817.0 (content + screenshot overhaul) (#95 ) Ships the v2026.817.0 docs to live: the doc content that was authored and verified earlier, plus a full screenshot overhaul. The content half (`cdf81e2` and the nightly commits behind it) has already been reviewed. The screenshots are the part that needs eyes — `f24d734`, 342 PNGs. ## Screenshots Everything was recaptured against the release commit `213dabab4f8e1f3bb1803a2924c0fea1289fcd4c` (`upstream/candidate/release-2026.817.0`). The previous shots were 375 parent-commits stale (v2026.720.0), with 228 of 310 entries flagged pending. All 342 registry entries now carry that SHA. > ⚠️ Worth knowing: the release commit is not an ancestor of the parent's > `master`, and local `master` was four days older than it. Capturing against > `master` would have both missed release UI and leaked 93 post-tag commits' worth > of UI into the release docs. ### New coverage (34 entries) Three guides shipped with no images at all despite being 115–136 lines. They now have them: \| Guide \| Shots \| \|---\|---\| \| `guides/day-to-day/decisions.md` \| queue, an agent-proposed decision with its options, triage strip, filter panel, named queue, Decided curtain, empty state \| \| `experimental/status-cards.md` \| board, New card dialog, and all four drawer tabs \| \| `experimental/task-chat.md` \| thread, composer mode picker, side pane \| \| `reference/api/secrets.md` \| the board-side Proposals tab \| Chat-Style Tasks is captured in a separate pass: `enableTaskChatRedesign` is instance-wide, so leaving it on would have turned every classic issue/task/work-mode shot into the redesigned chat. ## Two defects that were already live Both were shipping in the docs before this PR: 1. *`issues/detail-chat.png` and the `tasks/` shots were mostly plugin debug output. The Kitchen Sink example plugin mounts a panel into the issue page that dumps the raw issue JSON, and the seed installed it. Those guides were illustrating a debug panel instead of the task page. The seed no longer installs it. 2. The seeded task thread was a monologue** — four board-user messages in a row, because the board actor cannot post agent comments. It is now a real two-sided exchange. ## Targets repointed because the UI moved \| Target \| Why \| \|---\|---\| \| `activity/` \| `Activity.tsx` deleted; `/activity` renders `pages/audit/CompanyActivity.tsx` \| \| `experimental/cloud-upstream` \| `CloudUpstream.tsx` deleted; the route now redirects to `/company/export` \| \| `settings/`, `plugins/`, `adapters/` \| `/instance/settings/` are legacy redirects now \| \| `dashboard/stale-tasks-panel` \| panel removed from `Dashboard.tsx` — target dropped \| Plus eight targets with silent selector drift. A failed interaction step falls back to "whatever state was reached", so these had been quietly producing wrong images — a plain inbox where the doc promised a mode picker, a whole dashboard where it promised one panel. Full table in `docs/user-guides/screenshots/SCREENSHOTS_PLAN_v2026.817.0.md` §C2. ## Pipeline Decisions, status-card summaries and secret proposals are all agent-authored*, and the board actor the seed runs as is refused by every one of them (`"Agent run context required"`, `"Secret proposals require a verified run-bound agent token"`). Rather than insert rows behind the API, `seed-new-surfaces.mjs` borrows the two doors a real run already has — a board-minted agent API key, and a locally signed agent JWT — so every write goes through the production code path. Also: - `capture.mjs` records a real `captured_against` on a detached checkout instead of the literal string `"HEAD"` (which is what every pre-2026.817 entry recorded), and gains a `scrollTo` step for content below the fold. - `run.mjs` gains `--serve` for iterating on the seed, the task-chat phase, and a keeper that holds the demo board's issue statuses steady — the demo `process` agents finish runs without declaring a disposition, so the stalled-work sweep re-blocks issues every few minutes over a capture that runs far longer. ## Reviewing Light and dark both captured at 1440×900 @2x. The new surfaces are the ones to scrutinise; the rest is a like-for-like refresh. ### One leftover Dropping `dashboard/stale-tasks-panel` leaves `{light,dark}/dashboard/stale-tasks-panel.png` tracked but unused — they need deleting by hand. 🤖 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]> Co-authored-by: Dotta <[email protected]> Co-authored-by: ClaudeCoder <[email protected]>	2026-08-18 12:43:56 +02:00
Aron PrinsandClaude Opus 4.7	56b8d7d52d	Refactor docs IA into Guides + Reference tiers; add 10 new guides Reorganise all docs under a two-tier sidebar (Guides / Reference) with tier-grouped landing cards that auto-size to the section count (3-col default, 2x2 when a tier has 4 cards). Moves - docs/user-guides/guides/** -> docs/guides/{welcome,getting-started, day-to-day,org,projects-workflow,power}/ - docs/{api,cli,adapters,deploy} -> docs/reference/{api,cli,adapters,deploy} - New docs/administration/ for company/settings/plugins/cli-auth - 265 internal cross-links rewritten by scripts/rewrite-links.mjs - site/redirects.json preserves old URLs New guides - guides/org/agents.md (absorbs how-agents-work.md) - guides/day-to-day/issues.md (absorbs managing-tasks.md) - guides/day-to-day/costs.md (absorbs costs-and-budgets.md) - guides/projects-workflow/routines.md (absorbs heartbeats-and-routines.md) - guides/projects-workflow/workspaces.md (absorbs execution-workspaces.md) - guides/projects-workflow/projects.md - guides/projects-workflow/goals.md - guides/org/adapters.md (AdapterManager UI walkthrough) - administration/{company,settings,plugins,cli-auth}.md Expanded - approvals.md, skills.md, org-structure.md with missing UI walkthroughs Site - content.json: tier field, merged Welcome into Getting Started, collapsed Administration to single section - app.js: tier-grouped sidebar + landing; redirect map on route changes - styles.css: tier headers and adaptive landing grid Screenshots - docs/user-guides/screenshots/SCREENSHOTS_TODO.md runbook for capturing on a disposable demo instance. No screenshots captured in this branch. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>	2026-04-22 19:02:48 +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

631a6a0c53

Release docs for paperclip v2026.817.0 (content + screenshot overhaul) (#95 )

Ships the v2026.817.0 docs to live: the doc content that was authored
and verified
earlier, plus a full screenshot overhaul.

The content half (`cdf81e2` and the nightly commits behind it) has
already been
reviewed. **The screenshots are the part that needs eyes** — `f24d734`,
342 PNGs.

## Screenshots

Everything was recaptured against the release commit
`213dabab4f8e1f3bb1803a2924c0fea1289fcd4c`
(`upstream/candidate/release-2026.817.0`). The previous shots were 375
parent-commits stale (v2026.720.0), with 228 of 310 entries flagged
pending. All
342 registry entries now carry that SHA.

> ⚠️ Worth knowing: the release commit is **not** an ancestor of the
parent's
> `master`, and local `master` was four days *older* than it. Capturing
against
> `master` would have both missed release UI and leaked 93 post-tag
commits' worth
> of UI into the release docs.

### New coverage (34 entries)

Three guides shipped with **no images at all** despite being 115–136
lines. They
now have them:

| Guide | Shots |
|---|---|
| `guides/day-to-day/decisions.md` | queue, an agent-proposed decision
with its options, triage strip, filter panel, named queue, Decided
curtain, empty state |
| `experimental/status-cards.md` | board, New card dialog, and all four
drawer tabs |
| `experimental/task-chat.md` | thread, composer mode picker, side pane
|
| `reference/api/secrets.md` | the board-side Proposals tab |

Chat-Style Tasks is captured in a **separate pass**:
`enableTaskChatRedesign` is
instance-wide, so leaving it on would have turned every classic
issue/task/work-mode
shot into the redesigned chat.

## Two defects that were already live

Both were shipping in the docs before this PR:

1. **`issues/detail-chat.png` and the `tasks/*` shots were mostly plugin
debug
output.** The Kitchen Sink example plugin mounts a panel into the issue
page
that dumps the raw issue JSON, and the seed installed it. Those guides
were
illustrating a debug panel instead of the task page. The seed no longer
   installs it.
2. **The seeded task thread was a monologue** — four board-user messages
in a row,
because the board actor cannot post agent comments. It is now a real
two-sided
   exchange.

## Targets repointed because the UI moved

| Target | Why |
|---|---|
| `activity/*` | `Activity.tsx` deleted; `/activity` renders
`pages/audit/CompanyActivity.tsx` |
| `experimental/cloud-upstream` | `CloudUpstream.tsx` deleted; the route
now redirects to `/company/export` |
| `settings/*`, `plugins/*`, `adapters/*` | `/instance/settings/*` are
legacy redirects now |
| `dashboard/stale-tasks-panel` | panel removed from `Dashboard.tsx` —
target dropped |

Plus eight targets with **silent selector drift**. A failed interaction
step falls
back to "whatever state was reached", so these had been quietly
producing wrong
images — a plain inbox where the doc promised a mode picker, a whole
dashboard
where it promised one panel. Full table in
`docs/user-guides/screenshots/SCREENSHOTS_PLAN_v2026.817.0.md` §C2.

## Pipeline

Decisions, status-card summaries and secret proposals are all
**agent-authored**,
and the board actor the seed runs as is refused by every one of them
(`"Agent run context required"`, `"Secret proposals require a verified
run-bound
agent token"`). Rather than insert rows behind the API,
`seed-new-surfaces.mjs`
borrows the two doors a real run already has — a board-minted agent API
key, and a
locally signed agent JWT — so every write goes through the production
code path.

Also:
- `capture.mjs` records a real `captured_against` on a detached checkout
instead of
the literal string `"HEAD"` (which is what every pre-2026.817 entry
recorded), and
  gains a `scrollTo` step for content below the fold.
- `run.mjs` gains `--serve` for iterating on the seed, the task-chat
phase, and a
keeper that holds the demo board's issue statuses steady — the demo
`process`
agents finish runs without declaring a disposition, so the stalled-work
sweep
re-blocks issues every few minutes over a capture that runs far longer.

## Reviewing

Light and dark both captured at 1440×900 @2x. The new surfaces are the
ones to
scrutinise; the rest is a like-for-like refresh.

### One leftover

Dropping `dashboard/stale-tasks-panel` leaves
`{light,dark}/dashboard/stale-tasks-panel.png`
tracked but unused — they need deleting by hand.

🤖 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]>
Co-authored-by: Dotta <[email protected]>
Co-authored-by: ClaudeCoder <[email protected]>

2026-08-18 12:43:56 +02:00

Aron PrinsandClaude Opus 4.7

56b8d7d52d

Refactor docs IA into Guides + Reference tiers; add 10 new guides

Reorganise all docs under a two-tier sidebar (Guides / Reference) with
tier-grouped landing cards that auto-size to the section count (3-col
default, 2x2 when a tier has 4 cards).

Moves
- docs/user-guides/guides/** -> docs/guides/{welcome,getting-started,
  day-to-day,org,projects-workflow,power}/
- docs/{api,cli,adapters,deploy} -> docs/reference/{api,cli,adapters,deploy}
- New docs/administration/ for company/settings/plugins/cli-auth
- 265 internal cross-links rewritten by scripts/rewrite-links.mjs
- site/redirects.json preserves old URLs

New guides
- guides/org/agents.md (absorbs how-agents-work.md)
- guides/day-to-day/issues.md (absorbs managing-tasks.md)
- guides/day-to-day/costs.md (absorbs costs-and-budgets.md)
- guides/projects-workflow/routines.md (absorbs heartbeats-and-routines.md)
- guides/projects-workflow/workspaces.md (absorbs execution-workspaces.md)
- guides/projects-workflow/projects.md
- guides/projects-workflow/goals.md
- guides/org/adapters.md (AdapterManager UI walkthrough)
- administration/{company,settings,plugins,cli-auth}.md

Expanded
- approvals.md, skills.md, org-structure.md with missing UI walkthroughs

Site
- content.json: tier field, merged Welcome into Getting Started, collapsed
  Administration to single section
- app.js: tier-grouped sidebar + landing; redirect map on route changes
- styles.css: tier headers and adaptive landing grid

Screenshots
- docs/user-guides/screenshots/SCREENSHOTS_TODO.md runbook for capturing
  on a disposable demo instance. No screenshots captured in this branch.

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

2026-04-22 19:02:48 +02:00