Aron PrinsandClaude Opus 5
4644dda3a3
Picks up the regression test from #104 (@cryppadotta) — closed as superseded, but its fixture design was the best part of it and worth landing on its own. ## Why this gap mattered The sitemap `lastmod` bug shipped twice, and **neither failure was detectable by any check in `docs:test`**: | | Symptom | Why nothing caught it | |---|---|---| | #117 | 0 dates in production for weeks | Shallow checkout doesn't make `git log` *fail* — it succeeds, returning one date per file | | #118 | 192 concurrent `git fetch --unshallow` fighting over `.git/shallow.lock`, dateless sitemap | Reproduces only on a shallow clone — never locally, never in CI | Both are Cloudflare-only failure modes. The only detector we had was reading the live sitemap, which is how this whole thread started. ## What landed `scripts/verify-sitemap-lastmod-history.mjs`, wired into `docs:test`. Three cases against **real depth-1 clones** — the fixture design and `--no-local` insight are @cryppadotta's: 1. Full history publishes real per-document dates 2. Shallow clone that can reach origin recovers history 3. Shallow clone with unreachable origin omits dates rather than lying Two changes on top of the original: **Overlay the working-tree builder into the clone.** The clone carries committed HEAD, so without this the shallow cases silently test the last commit instead of the change being made. No-op in CI; the difference is real locally, and it is what makes the check usable while iterating. **Assert no single date covers >75% of pages.** The existing "more than one distinct date" assertion passes at *2* distinct dates — precisely the state #118 fixed, where 190 of 193 pages carried the date of a frontmatter-only sweep. Bounding the largest cluster catches that class without pinning a date that legitimate edits will move. ## Verified by breaking it A check that has never failed proves nothing, so I reverted each fix in turn: **Revert body-aware dating (#118):** ``` ok lastmod values vary across documents (2 distinct) rather than one build date FAIL full history: no single date dominates (2026-08-25 covers 190/193, 98% <= 75%) ``` Note the pre-existing assertion passing right above the failure — that is the gap this closes. **Revert the single-flight memo (#118):** ``` FAIL unshallowed build dates every route (2/193) FAIL unshallowed build produces varied dates (1 distinct) ``` The `.git/shallow.lock` race, caught by Case 2 and nothing else. Restored, clean run is green: 193/193 dated, 31 distinct, largest cluster 28%. ## Cost **~55s** added to `docs:test` for three builds (`docs-test` was 32s). Steep for a test suite, and worth flagging rather than burying — but the alternative detector for this failure class is noticing the live sitemap is wrong. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
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 —
paperclipcommand 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
maindeploy production athttps://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
Copyright (c) 2026 Paperclip Community.
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.