0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00

Files

T

Aron PrinsandClaude Opus 5 63e10a3cd6 sync-docs: require verifying the release is live before calling it shipped (#112 )

## What happened

Today's `v2026.824.0` release **did** write its docs-changelog entry.
The accordion is on `main` in `docs/reference/changelog.md`, every one
of the 15 pages the release touched is listed, and `npm run docs:build`
renders it correctly with exactly one open accordion.

What didn't happen is publication. `docs.paperclip.ing` is still serving
the build from `ebbab07` (#100, the pre-release hotfix):

| Check | Expected | Live |
|---|---|---|
| `/reference/deploy/tailscale-https-broker/` | `200` | `404` |
| `paperclipai channels` on `/reference/cli/installation/` | present |
absent |
| top changelog entry | `v2026.824.0` | `v2026.817.0` |

The `main`-branch Pages preview is stale in the same way, so neither
commit pushed to `main` today (#110, #111) deployed. `npm run
docs:build` succeeds from a clean checkout of `main`, so it isn't a
build break — the Cloudflare Pages deploy simply never ran.

## Why the skill didn't catch it

Phase 7 builds into `.site`, which is gitignored — nothing reader-facing
is ever committed — and Phase 8 hands off at the merge. There was no
step that looked at the live site. The runbook had a soft "Confirm
`docs.paperclip.ing` is rebuilt successfully" bullet with no method and
no fallback, and it was skipped along with its siblings: the
`docs/v2026.824.0` tag was never cut (last one is `docs/v2026.707.0`),
and `nightly`'s `.sync-state.json` still reads `branch_mode: "release"`.

## What this changes

- **`skills/sync-docs/SKILL.md`** — new **Phase 9 — Publish & verify
live** (release mode only): do every post-merge follow-up (tag, realign,
flip `branch_mode`), verify production against three independent live
signals, republish via `wrangler pages deploy` if stale, and report the
status codes as evidence. Verification is mandatory even when pushing
isn't approved. Plus a failure-mode row, a diagnosis-order special case,
and a pointer from Phase 6.5 (the entry isn't done until it's live).
- **`maintenance/runbook.md`** — replaces the soft "confirm" bullet with
the actual checks and the manual republish fallback.
- **`README.md`** — it claimed there is no Wrangler publish step for
this repo; notes the auto-deploy isn't guaranteed and documents the
fallback.

No changelog content changed — the `v2026.824.0` entry needed no
correction. Merging this PR pushes to `main`, which should also
re-trigger the deploy that stalled.

## Verification

- `npm run docs:build` — clean
- `npm run sync:check` — lint-links and verify-nav pass; the 5
`rest-route-missing` drift candidates are pre-existing medium-confidence
`Verify:` entries from the release, untouched here

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

Co-authored-by: Claude Opus 5 (1M context) <[email protected]>

2026-08-25 12:25:33 +02:00

3.0 KiB

Raw Blame History

Paperclip Docs

Source for the Paperclip documentation site — user guides, API and CLI reference, adapter docs, and deployment notes.

Read the docs: https://docs.paperclip.ing/

What's inside

Guides — Getting started, core concepts, and day-to-day usage.
API reference — Control-plane endpoints and payload schemas.
CLI reference — paperclip command surface.
Adapters — Plugin authoring and the integrations catalogue.
Deploy — Self-hosting, upgrades, and operational guidance.

The site is a single static shell that renders the Markdown files in docs/ directly — no framework, no build step required to read the raw pages.

Build and deployment

Build a release bundle locally with:

npm run docs:build

Cloudflare Pages is connected directly to paperclipai/paperclip-docs through GitHub. There is no normal Wrangler publish step for this repo:

Pushes to main deploy production at https://docs.paperclip.ing/.
Pushes to other branches create Cloudflare Pages preview/canary deployments.
Canary URLs are created by Cloudflare for each deployment, for example https://92b9a99c.paperclip-docs-74t.pages.dev. Use the URL shown in the Cloudflare Pages deployment row or GitHub deployment/check for the pushed branch and commit.

That auto-deploy is not guaranteed — it has silently failed to fire on a push to main before. After anything reader-facing lands, check the live site rather than the merge, and republish by hand if it's stale:

npm run docs:build
npx wrangler pages deploy .site --project-name paperclip-docs --branch main

Contributing

Spotted a typo, a broken link, or something that could be clearer? There are two easy paths, both linked from the footer of every docs page:

Suggest an edit — opens the underlying Markdown file in GitHub's web editor. Make the change and submit a PR without leaving the browser.
Report an issue — opens a prefilled Docs feedback issue with the page URL already attached.

For larger changes, fork the repo and open a PR against main. Screenshots live under docs/user-guides/screenshots/{light,dark}/ and should be provided in both themes when replacing UI captures.

Community

License

The Paperclip software is open source — see the main paperclip repository for its license.

The documentation in this repository is licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0). You may read and share it for non-commercial purposes with attribution. Commercial use of any kind requires prior written permission from the copyright holders. See LICENSE for the full text.

3.0 KiB Raw Blame History