## Summary
Improves the docs page Lighthouse profile for the report attached to
[PAP-12441](/PAP/issues/PAP-12441).
- Removed render-blocking third-party docs shell requests for Google Tag
Manager, Google Fonts, and Lucide.
- Vendored the existing `[email protected]` parser locally and copied
`site/vendor` into release builds.
- Replaced Lucide runtime icon rendering with inline SVG paths for the
existing docs section icons.
- Fixed reported accessibility issues: mobile zoom disabling, hidden
drawer focusability, TOC ARIA semantics, footer heading order,
muted-text contrast, TOC button accessible name, and article link
affordance.
- Added smaller responsive WebP variants for the dashboard overview
screenshot and explicit dimensions/fetch hints for article images.
- Minified CSS in release builds.
## Canary
- Commit preview: https://2f89e7fc.paperclip-docs-74t.pages.dev
- Branch preview:
https://codex-lighthouse-docs-scores.paperclip-docs-74t.pages.dev
- Target route from the report:
https://2f89e7fc.paperclip-docs-74t.pages.dev/guides/getting-started/five-minute-path/
## Root Cause
The docs shell was paying for several third-party render-blocking
requests before first contentful render, and the target guide loaded a
large full-size dashboard PNG for a small mobile viewport. Several
Lighthouse accessibility audits were caused by UI semantics rather than
content: a hidden but focusable drawer, menu roles around plain links, a
non-zoomable viewport, footer heading level skips, and color-only
article links.
## Validation
- `npm run docs:build` passes.
- `npm run docs:test:static-routes` passes.
- `npm run docs:test:hierarchical-skills-nav` passes.
- `node --check site/app.js`, `node --check .site/app.js`, and `node
--check site/build-release.mjs` pass.
- Static release checks pass for preserved SEO metadata, removed
third-party assets, zoomable viewport, inert drawer, no footer headings,
underlined article links, responsive screenshot wiring, TOC nav
semantics, and copied optimized assets.
- Cloudflare Pages check passed for commit `129baaa`.
Local Lighthouse could not complete in this container because the
available cached Chromium binaries fail to start without
`libatk-1.0.so.0`. PageSpeed Online is also quota-limited from this
environment. The canary URL above is ready for a browser-capable
Lighthouse run.
---------
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[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]>
Validated the pipeline against a live local_trusted instance and fixed what
the dry run surfaced, plus made the demo company look genuinely in-use.
seed.mjs — rich, idempotent, soft-failing demo dataset:
- brand color + monthly budget; 5-agent org (Ada/Bob/Cleo/Dax/Eve) with
titles, icons, instructions, per-agent budgets, assigned skills
- 4 company skills, 2 goals, 2 projects + a git workspace, 8 issues with
mixed statuses/priorities/assignees, 2 sub-issues, a 4-message chat thread
- routine + one execution-history row, 2 invites, bundled plugins installed,
32 cost events + 5 finance events so the Costs/Finance dashboards are non-zero
- enum/validation fixes from the live run: goal status "active" (not
"in_progress"), workspace sourceType "git_repo", comment authorType "user"
(a board actor cannot post as "agent")
run.mjs:
- kill the server's whole process group on teardown (was orphaning the
server child and holding port 3197)
- pre-clean the scratch home at startup so every run gets a fresh DB and the
one-shot seed steps (comments/invites/events) always fire
sync-registry.mjs: drop the scaffolder's _todo note once route/depends_on
are populated.
package-lock.json: pick up @playwright/test.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
