## Summary
Adds the hosted beta getting-started guide and FAQ at `/hosted-beta/`,
using the existing docs header, sidebar, article layout, theme controls,
and table of contents.
The page remains outside the navigation/search manifest, homepage
listings, previous/next links, and sitemap, with a `noindex` directive.
Direct-link visitors can navigate into the regular docs. This is a
public, unlisted page rather than access-controlled content.
## Validation
- Root and subpath builds and unlisted discovery checks pass.
- Existing static route verification passes.
- Desktop and mobile browser checks show no overflow or runtime errors.
- Table-of-contents anchors and navigation into regular docs verified.
Local preview: http://127.0.0.1:4337/hosted-beta/
Hosted preview:
https://aa3d8178.paperclip-docs-74t.pages.dev/hosted-beta/
Cloudflare deployment succeeded for commit 4b94d17.
## 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]>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The public docs site is how operators and contributors discover
reference material and guides.
> - The docs pages were routed through hash URLs, which makes individual
pages harder for crawlers and link previews to treat as first-class
documents.
> - The release build needs to emit static HTML pages for each docs
route while preserving the client-side docs experience.
> - This pull request adds static docs route generation and verification
around canonical, crawlable route output.
> - The benefit is that docs pages can be indexed and shared as normal
path-based URLs without losing local navigation behavior.
## Linked Issues or Issue Description
No public GitHub issue exists for this docs-site improvement.
Problem:
- Docs pages were reachable primarily through hash routes such as
`/#/reference/skills`.
- Crawlers and social previews benefit from static route-specific HTML
at normal paths such as `/reference/skills`.
- The release build should publish those pages predictably and verify
that they include canonical metadata, page titles, and visible article
content.
## What Changed
- Added static route generation to the docs release build so each nav
route gets an `index.html` output with route-specific title, canonical
URL, article content, and sitemap entry.
- Updated the browser app bootstrap to support path-based docs routes
and retain compatibility with hash links.
- Added `docs:test:static-routes` coverage for generated static route
output.
- Documented Cloudflare Pages preview and production deployment details.
## Verification
- `npm run docs:test:static-routes`
- `npm run docs:build`
## Risks
Low to medium risk. This changes release output shape for the docs site,
so the main risk is a Pages deployment configuration mismatch. The build
keeps existing client-side rendering behavior and includes a
static-route verification script to catch missing canonical pages before
publishing.
## Model Used
OpenAI GPT-5 Codex coding agent, tool-using software engineering mode.
Exact service context window was not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <[email protected]>
Documentation content is now copyrighted to Aron & Sharon
(aronandsharon.com) and licensed under CC BY-NC-ND 4.0, which
prohibits commercial use without prior written permission. The
Paperclip software itself remains open source under its own
license.
README now focuses on what the docs cover, how to read them, and how to
contribute via the per-article edit/issue links. All operational content
(commands, base-path notes, layout, publish flow) moved to
MAINTENANCE.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Michael Nguyen