mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
39633c22178a604ef878f6c4298728e34a74dc94
23
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
39633c2217 |
docs: connectors catalog, operator-first third revision (#124)
Connector catalog, setup guides, and shared access documentation, followed by a final code-accuracy repair pass. This PR does not change application behavior. ## Final accuracy pass Checked against shipped Paperclip `v2026.916.0`, commit `dffc2b3ca1b9e88fa21cb17493083e682dffd1ca`, rather than the dirty local checkout or the earlier canary baseline. - Corrects connector/method-specific identity choices, human audiences, and managed GitHub versus PAT scope and verification. - Explains that **Always allow** covers different arguments for the same agent/action/connection, with project scope when present; uses actual button labels and removes the test-panel control from review instructions. - Qualifies new-action quarantine, including safe-default read exceptions. Removes unconditional approval guarantees. - Separates provider channel/repository reach from Paperclip sender authorization. - Completes sandbox sign-in and model credential-selection instructions from the current UI implementation. - Repairs Notion's hub summary, removes incomplete optional Notion/Sentry client-registration procedures, and corrects Linear's provider-versus-Paperclip attribution. - Removes unsupported Postman tier claims, contradictory Cloudinary/Mem0 verification assertions, API-equivalence claims, and overbroad successful-test assurances. - Retains Supabase's required project reference: both released method definitions explicitly require it. An earlier review suggested otherwise; release code is authoritative here. - Updates the release baseline and removes draft commit chronology from the public introduction. ## Availability and remaining runtime gates - **Google:** Verification is pending. Per the product-owner clarification, authorization can continue where Google offers an Advanced option; this is not available for every account and does not override Workspace policy or other Google prerequisites. Notices on the hub and all Google guides now distinguish an unverified-app warning from blocked authorization. - **Slack is available but not yet fully functional; follow-up fixes are planned.** For agent tools, the released OAuth endpoint/scope defaults differ from Slack's documented MCP contract. The page now warns against treating that route as production-ready and removes the misleading bot-scope walkthrough. Chat-channel bot setup remains separate. Engineering must reconcile the integration and run OAuth plus one read before removing this warning. Source: https://docs.slack.dev/ai/slack-mcp-server/ - No credentialed connector run was performed in this pass. Code consistency, provider documentation, UI rendering, and successful live execution are separate evidence levels. No claim of runtime certification for all connectors. ## Validation - Root build: 253 crawlable documentation pages. - Full `docs:test`: all eight suites passed locally, including root/subpath routes, sitemap history, fingerprints, navigation, skill source blocks, crawlable links, doc-link resolution, and SEO metadata. - Internal-link lint: 258 Markdown files; no broken internal links. - Latest cleanup: full build, all eight docs:test suites, internal-link lint and diff whitespace checks passed; 1,878 link-resolution checks. - Fixed the Calendar MCP reference URL; browser-checked the five inconclusive external destinations (Miro article loads; Asana, Google Cloud, OpenAI and xAI reach sign-in/console screens). Authenticated destinations were not tested beyond those screens. - Replaced the Sandbox providers editorial TODO with a scope note and removed the CLI overview's unfinished-guide announcement. - Browser client navigation: 687 checks passed using installed Chrome. Initial launch lacked the downloaded Playwright browser; rerun used `DOCS_CHROMIUM_PATH` without changing the tests. - Nine representative connector/shared pages at 1440px and 390px: HTTP 200, one article H1, no page-level horizontal overflow. Mobile screenshot inspected; approval page opened in the Codex browser. - Navigation audit reports three existing non-connector orphan files; this patch does not alter those files or their navigation. The previous revision's provider-page expansion, Google shared setup guide, navigation additions, and accidental node_modules-symlink cleanup remain in this PR. Internal review ledgers remain outside the publication branch. No merge or production deployment authorized. --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Claude Opus 5 (1M context) <[email protected]> Co-authored-by: Michael Nguyen <[email protected]> |
||
|
Aron PrinsandClaude Opus 5
|
29beedeb6a |
seo: make the docs link graph crawlable (#113)
## Why Google has indexed effectively nothing on `docs.paperclip.ing`. Search Console over 3 months: **8 of 192 URLs** have ever drawn an impression, **681 of 975 impressions (70%) go to `/guides/agent-developer/comments-and-communication`** — a legacy URL that 301s and isn't in the sitemap. Strip that, the homepage, and the team's own `site:` queries, and the canonical docs corpus earned **~7 organic impressions in 90 days**. It isn't an eligibility problem. Pages are fetchable, self-canonical, `index, follow`, and identical under a Googlebot UA. It's the internal link graph. ## What was actually broken **1. Every relative markdown link 404'd.** Authors write `./glossary.md`, but pages are served from trailing-slash route directories, so links resolved one level too deep: ``` page: /guides/welcome/key-concepts/ href: ./glossary.md → /guides/welcome/key-concepts/glossary.md 404 ( /guides/welcome/glossary.md would be 200 ) ``` Crawled all 192 live pages: **all 742 unique `.md` targets return 404**. That's **1,283 of 1,306 in-body internal links — 98% — broken**, leaving **0.1 working in-body links per page**. It went unnoticed because `app.js:postProcessInternalLinks` repairs these at runtime. Crawlers index the pre-render. **2. The sidebar wasn't server-rendered.** Interior pages shipped `<div id="sb-sections"></div>`, filled by JS. So the raw HTML offered the logo, prev, next — and ~7 dead links. No link equity reached deep pages. Search Console classified 98% of crawling as refresh, 2% as discovery. Net effect: a crawler saw every page as a dead end that was 98% broken links. Crawl demand collapsed — 14 crawled of 184, 15% of crawl responses 404. ## Changes - **Rewrite markdown links to canonical routes at build time**, and fail the build on any link no nav page publishes. (Passed first run with zero unresolved — every link had a valid destination, just emitted in a 404ing form.) - **Server-render the sidebar and breadcrumb** into every interior route from the manifest `app.js` already uses. `app.js` detects `data-server-rendered` and keeps the DOM rather than re-rendering identical markup. The mobile drawer stays client-built — it's `inert`/`aria-hidden` until a JS toggle opens it, so rendering it duplicated 192 links/page (~41KB) for no crawl benefit. - **Intercept canonical route links in articles** so in-page navigation stays a soft transition instead of a full reload. - **Omit sitemap `<lastmod>` when git history is untrustworthy.** Reproduced the real mechanism: in a `--depth=1` clone, `git log -1` returns the single fetched commit's date for *every* file. Two files that differ locally (`2026-08-18` / `2026-07-08`) both come back `2026-08-25` shallow. That is exactly the live `192 × 2026-08-20`. Cloudflare Pages shallow-clones by default. - **Ship `redirects.json`** — `app.js` fetches it at boot and it 404'd. - **Canonicalise the footer's `/reference/api/overview`** link, which spent a 301 on all 193 pages. - **Add `scripts/verify-crawlable-links.mjs` + CI**, gating on raw `.md` hrefs, missing targets, redirecting targets, relative hrefs, an unrendered sidebar, and uniform sitemap dates. The last two were both caught by the new verifier on its first run. ## Result | | Before (production) | After (generated bundle) | |---|---|---| | Broken in-body links | 1,283 (98%) | **0** | | Working in-body links | 23 | **1,501** | | Crawlable nav links/page | 0 | **192** | | Distinct sitemap dates | 1 | **24** (0 on shallow CI) | `Crawlable-link contract passed: 41078 internal links across 194 pages resolve in one hop.` ## Verified Built and driven in a real browser at `localhost:4321`: - Raw HTML (crawler / no-JS view): 192 inline sidebar links, breadcrumb rendered, **0 local `.md` hrefs**, single H1. Remaining empty containers are JS-only UI (search modal, drawer, runtime status). - SPA intact, no reloads, no JS errors: in-article links, prev/next, sidebar links, mobile drawer (opens, 192 links, closes on navigate), search (8 results for "adapter"). Breadcrumb and active-link state follow correctly throughout. - Subpath build for gh-pages emits correct `/paperclip-docs/...` hrefs. - Homepage unchanged: 15 landing cards, 192 directory links. - Shallow-clone build confirmed to warn and emit zero `<lastmod>`. ## Notes for review - **This can't ship until the Cloudflare GitHub App is unsuspended.** Everything here is verified against a local build only. - **CI will be red on one pre-existing, unrelated failure**: `docs:test:skill-source-blocks` on `docs/reference/skills/optional/content/simplified-english.md` (missing its skill-source block, from release #95). Confirmed failing on clean `main`. Left in the aggregate rather than weakening the suite — fixing it needs the real `SKILL.md` from the parent repo, which is sync-docs work. - **Production will now ship no `lastmod` at all** on Cloudflare's shallow clone. Correct versus lying. To get real dates back, set the Pages build command to `git fetch --unshallow || true; npm run docs:build` — documented in the generated `DEPLOY.md`. - Page weight 67KB → 109KB from the inlined nav. Highly repetitive, compresses well, but it is a real increase. - Weak/duplicate titles were deliberately skipped, per the plan's own ranking (secondary). - Plan item 4 (contextual links from high-authority surfaces to 20–25 priority pages) is a `paperclip-website` change plus editorial judgment, so it's out of scope here. Worth noting that fixing the internal graph recovers most of what that item was meant to buy — the dominant authority failure was internal, not off-site. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]> |
||
|
|
c7b3f4cacf |
Render full SKILL.md as a code snippet on per-skill pages (PAP-16980) (#89)
> **Updated on current main:** #87 and the #90 cache hotfix are merged. This PR now targets `main`, was rebased onto merge commit `8c5976f`, and has a fresh successful Cloudflare preview plus post-rebase browser smoke evidence. ## What & why (PAP-16980) Improves SEO/AEO on the bundled/optional **per-skill reference pages** (from PAP-16670) by clearly separating the *human-readable catalog summary* (top of page) from the *authoritative full skill definition*. Previously the "Full skill definition" section rendered the `SKILL.md` as **parsed Markdown**, so each skill's own `##` headings, lists, and fenced examples became real page content — competing with the summary, inflating the on-page TOC (e.g. qa-acceptance went from **16 → 6** "On this page" entries), and confusing crawlers/answer engines about the page's true structure. Now each per-skill page shows the **complete, verbatim `SKILL.md`** (frontmatter + body) inline, rendered through the **existing production code-snippet treatment**. ## Changes - **Content (10 per-skill pages):** replaced the old `### Skill frontmatter` bullets + parsed `### Skill instructions` layout with the full `SKILL.md` embedded in a fenced ````markdown skill-source` block. Source bytes were taken verbatim from each skill's authoritative `SKILL.md` at the page's pinned `paperclip_version`, verified against the page's own prior instructions body + frontmatter (name/description) so no content drifted. - **Renderers (`site/build-release.mjs`, `site/app.js`):** a `skill-source` fence renders as `<pre><code class="language-markdown" data-skill-download="SKILL.md">`. Every other code block is delegated to marked's default renderer, so existing snippets are byte-for-byte unchanged. Rendered identically in the crawler-visible build HTML and on client SPA navigation. - **Copy + Download (`site/app.js`, `site/styles.css`):** `decorateCodeBlocks` reuses the existing Copy affordance and adds a **Download `SKILL.md`** control beside it. Both share dimensions, styling, hover/focus visibility, and the copied-success state; both carry accessible labels/titles. - **Readable full-source wrapping (`site/styles.css`):** only the downloadable `SKILL.md` block uses `white-space: pre-wrap` and safe long-token wrapping. Ordinary code snippets retain the existing horizontal-scroll treatment. - **Test:** `scripts/verify-skill-source-blocks.mjs` (`npm run docs:test:skill-source-blocks`) asserts the render contract (single H1, single `<pre>`, frontmatter present, no legacy headings) and that ordinary docs pages emit no `data-skill-download`. ## Scope statement No catalog-page layout, navigation, typography, summary-copy, metadata-card, or information-architecture changes. `paperclip-website` and generated `.site/` output are untouched. `optional/finance/ramp.md` is intentionally excluded — it is a newer summary page with no embedded full-definition section to reformat. The diff is the 10 skill pages + the narrow renderer/Copy-Download support + the test. ## Evidence **1–2. Before/after (desktop, 1280×900) + mobile after (390×844)** — attached to Paperclip issue [PAP-16980](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/3098577a-4f6f-4eb2-9151-a4b61917dffd) (`before-desktop.png`, `after-desktop-controls.png`, `after-controls-zoom.png`, `after-mobile.png`). GitHub cannot render the auth-gated attachment URLs inline, so they live on the issue for reviewers. **4. Raw DOM/HTML (build output, qa-acceptance):** - Article renders exactly **one H1**: `<h1 id="qa-acceptance">QA Acceptance</h1>` - Full source inside a single code block: ```html <pre><code class="language-markdown" data-skill-download="SKILL.md">--- name: qa-acceptance description: Produce QA acceptance criteria and a manual validation plan … key: paperclipai/bundled/quality/qa-acceptance recommendedForRoles: - qa … </code></pre> ``` - Article `<pre>` count: **1** (inner ````` fences stay literal — no breakout). 10/10 skill pages carry the block; 0 non-skill pages do. **5. Copy + Download behavior (Playwright against the built site):** ```json { "downloadFilename": "SKILL.md", "downloadMatchesBlock": true, // downloaded file === code block text, byte-identical "downloadBytes": 3853, "copyShowsSuccess": true, // Copy toggles the existing is-copied success state "accessibleLabels": { "copy": "Copy code", "download": "Download SKILL.md" } } ``` Both controls reach `opacity: 1` on `.code-wrap:hover` and on keyboard `:focus-visible` (verified `matches(':focus-visible') === true` → computed opacity `1`). **H1 audit (every generated route, incl. all skill URLs — requested on the issue):** built the site on current `main` and scanned **all 184 generated `index.html` routes** (16 skill routes among them). **Every route has exactly one `<h1>`.** The skill source's own `#`/`##` headings live *inside* the `<pre><code>` block as literal text, so they do **not** create competing H1s — the SEO/AEO goal. ## Tests Run against current `main` after #87 and #90: ``` docs:build ............................. ok (184 routes) docs:test:static-routes ................ pass (5 routes + 404 + root + subpath) docs:test:skill-source-blocks .......... pass (10 skill pages, 1 control page) H1 audit (all 184 routes) .............. pass (exactly 1 h1 each; 16 skill routes) ``` **Do not merge/deploy** — returning to Dotta/reviewers for approval per PAP-16980. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
e2adb1c167 |
PR1 — server-render the docs root and split it from interior routes (Phase 1) [DO NOT MERGE] (#87)
# PR1 — server-render the docs root and split it from interior routes (Phase 1) **Do not merge — Dotta alone may merge.** This PR is opened for review only, per the hard write-gate on the approved plan. ## Provenance | item | link | |---|---| | Accepted plan | [PAP-16672 · plan document](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16672#document-plan) | | Phase 0 review packet | [PAP-16671 · packet comment](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16671#comment-f653273d-6450-4f8d-bcd6-f805ad28b923) | | Implementation candidate | [PAP-16682](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16682) | | Independent QA — **PASS** | [PAP-16683](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16683) | | Finalization / this PR | [PAP-16684](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16684) | | Full evidence gallery (screenshots + raw JSON probes) | https://pages.paperclip.ing/pap-16684-pr1-evidence/ | Base: approved `main` @ `2ab76e8e4`. Head: `f5bbba24c` (exactly one commit on top; `main` has not moved). ## What changed - **1.1 — root-only landing shell.** The hero is *physically absent* from interior documents (removed at build time, not CSS/JS/ARIA hidden); the build throws if removal fails. Header, footer, search, sidebar, breadcrumbs and article nav are preserved on every page. - **1.2 — server-rendered homepage directory** generated from the same canonical `site/content.json` manifest that already feeds the sidebar, breadcrumbs, prev/next, routes and sitemap. No second URL manifest was introduced. - **Single descriptive H1 per interior page** (was 2 — the hero H1 bled onto every route). - **Truthful runtime UI.** `Loading…` / `Could not load this guide.` no longer ship inside success HTML; they are produced only by `app.js` at runtime on the empty, `hidden` `#runtime-status` mount, so they can only appear during a genuine client transition or failure. ``` scripts/verify-static-routes.mjs | 200 +++++++++++++++++++++++++++++++++- site/app.js | 90 ++++++++++++---- site/build-release.mjs | 189 ++++++++++++++++++++++++++++++-- site/index.html | 17 ++-- site/styles.css | 70 ++++++++++- 5 files changed, 528 insertions(+), 38 deletions(-) ``` `.site/` is **generated build output and remains uncommitted** (gitignored): `git ls-files | grep '^\.site/'` → 0 files. ## Before → after, raw HTTP/HTML for the six representative routes Both trees built with the identical command and base path, then served by a production-equivalent static server (real 404 status, honors `_redirects`). "Before" is a real build of approved `main` @ `2ab76e8e4`. | route | HTTP | content type | H1 count before → **after** | H1 text (after) | `id="landing"` before → after | `Loading…` | `Could not load this guide.` | internal directory anchors | |---|---|---|---|---|---|---|---|---| | `/` | 200 | `text/html` | 1 → **1** | Everything you need to run Paperclip. | 1 → 1 (root-only ✓) | 1 → **0** | 1 → **0** | 4 → **184** | | `/guides/welcome/what-is-paperclip/` | 200 | `text/html` | 2 → **1** | What is Paperclip? | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/reference/api/overview/` | 200 | `text/html` | 2 → **1** | API Overview | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/how-to/add-mcp-server-to-agent/` | 200 | `text/html` | 2 → **1** | Add an MCP server to an agent's toolkit | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/reference/changelog/` | 200 | `text/html` | 2 → **1** | Documentation Changelog | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/guides/welcome/this-route-does-not-exist/` | **404** | `text/html; charset=utf-8` | 1 → **1** | Not found | 0 → 0 | 0 → 0 | 0 → 0 | 0 → 0 | Machine-readable probes: [before-raw.json](https://pages.paperclip.ing/pap-16684-pr1-evidence/before-raw.json) · [after-raw.json](https://pages.paperclip.ing/pap-16684-pr1-evidence/after-raw.json). ### Homepage bleed and false state — absence proof - `id="landing"` returns **zero** matches in every interior document. Only inlined `#landing-*` **CSS selector text** remains (stylesheet, not markup). - Interiors carry no directory manifest (4 internal anchors — the footer); the 184-anchor directory is root-only. - The two false-state phrases appear in **0** built HTML files across the whole bundle. ### 404 / noindex / sitemap - Real HTTP **404** for the nonexistent route (root base and `/paperclip-docs/` subpath build). - `404.html`: exactly one `<h1>Not found</h1>`, `<meta name="robots" content="noindex, nofollow">`, `<title>Not found | Paperclip Docs</title>`. - Absent from `sitemap.xml` (0 occurrences); no built file for the route. - `sitemap.xml` has 184 `<loc>` (183 routes + root) and the root directory anchor set covers **183/183** non-root sitemap routes — 0 missing. - `_redirects` contains **no wildcard `200` rewrite** (0 lines with a `200` status), so unknown routes cannot be masked as success. - `robots.txt`: `User-agent: * / Allow: /` + `Sitemap: https://docs.paperclip.ing/sitemap.xml`. ## Focused checks — rerun on the final revision (`f5bbba24c`) | command | result | |---|---| | `npm run docs:test:static-routes` | **PASS** — "Static route verification passed (5 representative routes + /guides/welcome/this-route-does-not-exist/, root and /paperclip-docs/ builds)." | | `npm run docs:build` | **PASS** — "Generated 183 crawlable route pages plus sitemap.xml and robots.txt." | `git status` is clean after the build (no generated output enters the tree). ## Browser matrix — desktop 1440×900 and mobile 390×844 Run with Playwright + Chromium 1228. The QA sandbox could not exercise this (blank-glyph text rendering); the root cause turned out to be that **no fonts are installed on the host at all** — installing DejaVu TTFs with a minimal fontconfig makes text render correctly, which unblocked the full interactive matrix here. Screenshots: https://pages.paperclip.ing/pap-16684-pr1-evidence/ ### Per-route, JavaScript enabled (both viewports) All six routes on both viewports: expected HTTP status, **exactly 1 `<h1>`** with the correct text, `#landing` present **only** on `/`, no `Loading`/`Could not load this guide.` text in the rendered body, `#runtime-status` hidden, **no horizontal overflow**. ### Interactive | check | result | |---|---| | root directory link → interior (client nav) | ✅ `/guides/welcome/what-is-paperclip/`, single H1 "What is Paperclip?", hero gone, not stuck loading | | direct load vs client-nav parity | ✅ identical H1 set | | back / forward history | ✅ back → `/` with hero restored; forward → interior with correct H1 | | home nav from an interior doc | ✅ `/` with hero | | theme toggle | ✅ toggles (`dark` → light) | | desktop sidebar / TOC / breadcrumbs / prev-next / search / footer | ✅ 191 sidebar links, 14 TOC links, breadcrumbs rendered, article nav present, search control present, 15 footer links | | mobile drawer | ✅ opens (screenshot `mobile-drawer-open.png`) | | mobile horizontal scroll | ✅ none | | unknown route | ✅ 404 page, single H1, noindex | ### JavaScript disabled | check | result | |---|---| | `/` directory usable with JS off | ✅ 202 anchors present in raw markup; hero + card directory fully rendered | | clicking a directory link with JS off | ✅ full page load to `/reference/api/overview/` | | that interior page with JS off | ✅ 1 H1 ("API Overview"), no hero, no false loading/error state, 6368 chars of real article text | | mobile with JS off | ✅ root and interior both render correctly | ### Console / network No JavaScript errors and no page errors on any route. Exactly two non-2xx requests, **both reproduced identically on approved `main` @ `2ab76e8e4`** — neither is introduced by this PR: - `GET /redirects.json` → 404. Pre-existing: neither the before nor after build emits this file. Verified byte-for-byte identical behaviour on `main`. - `GET https://api.github.com/repos/paperclipai/paperclip` → 403. Unauthenticated GitHub API rate limit for the header star counter; environmental, external, not a product defect. Also confirmed unchanged before → after on the same interior page: header (1), footer (1), search controls (4), sidebar links (191), TOC links (14), article nav (2), article text length (4328 chars). The **only** rendered difference is the intended H1 2 → 1 and the removed hero. ## Verified against the real Cloudflare Pages deploy, not just a local server The Cloudflare Pages check on this PR is **green** and produced a live preview: **https://pap-16682-server-render-root.paperclip-docs-74t.pages.dev** I reran the entire matrix against that real deploy. Every invariant reproduces **identically** to the local run — so these results hold on actual production hosting, including Cloudflare's own 404 handling: | route | HTTP | H1 | `#landing` | `Loading…` | `Could not load…` | noindex | anchors | |---|---|---|---|---|---|---|---| | `/` | 200 | 1 — Everything you need to run Paperclip. | present (root-only) | 0 | 0 | – | 184 | | `/guides/welcome/what-is-paperclip/` | 200 | 1 — What is Paperclip? | absent | 0 | 0 | – | 4 | | `/reference/api/overview/` | 200 | 1 — API Overview | absent | 0 | 0 | – | 4 | | `/how-to/add-mcp-server-to-agent/` | 200 | 1 — Add an MCP server to an agent's toolkit | absent | 0 | 0 | – | 4 | | `/reference/changelog/` | 200 | 1 — Documentation Changelog | absent | 0 | 0 | – | 4 | | nonexistent route | **404** | 1 — Not found | absent | 0 | 0 | **yes** | 0 | Browser matrix on the live preview, desktop 1440×900 and mobile 390×844: identical outcomes — client nav, direct-load parity, back/forward, home-nav, theme toggle, 191 sidebar links, 14 TOC links, mobile drawer opens, no horizontal scroll, and with **JavaScript disabled** the root directory (202 anchors) navigates by real page load into an interior with 1 H1, no hero, no false state and 6368 chars of article text. **Console/network on the live deploy: zero page errors.** The same two known non-product requests appear (`/redirects.json` and the GitHub star-count API). `/redirects.json` returns **404 on live production `docs.paperclip.ing` today** and on the `main` branch preview — conclusively pre-existing and unrelated to this PR. Screenshots from both the Cloudflare deploy and the local server are in the gallery: https://pages.paperclip.ing/pap-16684-pr1-evidence/ ## Out of scope — pre-existing observation, not a regression On the `--base-path /paperclip-docs/` subpath build, 4 footer links (`/reference/api/overview`, `/guides/org/agents/`, `/guides/org/adapters/`, `/guides/getting-started/five-minute-path/`) are emitted un-prefixed. Building approved `main` @ `2ab76e8e4` with the identical flag reproduces **exactly the same 4 links**, so this is a pre-existing footer-template issue untouched by this PR. Smallest fix would be routing the footer's hardcoded hrefs through the base-path prefixer, in a separate ticket. ## Merge policy `.site/` is generated output and is intentionally uncommitted. **This PR must remain open and unmerged — Dotta alone may merge it.** Co-authored-by: ClaudeCoder <[email protected]> Co-authored-by: Claude Opus 5 (1M context) <[email protected]> |
||
|
Michael Nguyenandanicca
|
f80e8a7289 |
Make docs navigation crawlable and sitemap dates accurate (#77)
## Summary - emit previous and next article navigation as real anchors in generated HTML - preserve the existing client-side navigation behavior - derive sitemap lastmod values from each Markdown file's Git history - omit lastmod when history is unavailable instead of publishing the build date - remove ignored changefreq and priority values - add regression assertions for crawlable links and sitemap dates ## Verification - npm run docs:test:static-routes - npm run sync:lint-links - npm run docs:build - generated 183 pages with zero server-rendered orphans, minimum one inbound link, and 23 distinct lastmod dates - git diff --check ## Risk Low. No routes, redirect rules, canonicals, robots directives, or index/noindex policy changed. Production still requires merge through the existing workflow. Co-authored-by: anicca <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
8c21935aa6 |
Add documentation changelog page with reusable accordion (#73)
## What Adds a **Changelog** category (Reference tier) with a **Docs** page that tracks what changed in *these docs* — pages added, rewritten, or expanded — per release. It's framed as a changelog for the documentation itself, not a mirror of Paperclip's product release notes (which it links out to). Backfilled with the full documentation history: **10 releases** from `v2026.513.0` (this repo's genesis) through `v2026.722.0`, reconstructed from each release commit's own docs summary. Each release is a collapsible accordion; the newest stays open. ## New design-system component Introduces a reusable native `<details>`/`<summary>` **accordion** (no JS): - `site/styles.css` — `details.accordion` styled with existing tokens (border/radius, parchment hover, rotating chevron, theme-aware), with an optional `.accordion-meta` right-aligned label. - `site/app.js` — allowlists `DETAILS`/`SUMMARY` + the `open` attribute in the client-side markdown sanitizer so collapsible content survives SPA rendering. Usage: ```html <details class="accordion" open> <summary>Title <span class="accordion-meta">meta</span></summary> <div class="accordion-body"> Markdown content — keep the blank lines so it parses. </div> </details> ``` ## Files - `docs/reference/changelog.md` (new) - `site/content.json` — Changelog category / Docs page nav entry - `site/styles.css`, `site/app.js` — accordion component ## Verification - `npm run sync:lint-links` — clean, no broken internal links (links verified against current tree; renamed/retired pages point at live targets). - `npm run sync:verify-nav` — passes (only orphans are the intentional CLI redirect pages). - `npm run docs:build` — all 10 accordions render, `/reference/changelog/` route builds. ## Note This is a **manual** changelog for now. A follow-up could hook a "prepend a new accordion" step into the `/sync-docs` release phase so future releases self-populate. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <[email protected]> |
||
|
|
dcd77edb7e |
Use white text in dark theme (#66)
## Summary - replace the dark-theme manila primary text color with white - update dark code blocks, navbar CTA states, and footer text consistently ## Verification - `npm run docs:build` - confirmed generated output contains no `#f3e6c4`, `manila`, or `manilla` references Issue: PAP-14695 --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
b214cdebda |
[codex] Improve docs Lighthouse scores (#41)
## 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]> |
||
|
Dotta
|
a21e720dff |
Implement persistent docs On this page sidebar (#33)
## Summary - Adds a persistent wide-screen `On this page` right rail to article pages. - Realigns the docs shell to a wider three-column grid with the left docs nav moved farther left. - Keeps the existing compact TOC dropdown for narrower widths and mobile. - Refactors TOC generation so route changes clear/rebuild both desktop and compact TOC mounts, with stable h2/h3 scrollspy and reduced-motion-safe active styling. ## Verification - `npm run docs:build:auto` - `npm run docs:test:static-routes` - `node --check site/app.js` - Served `.site` locally at `http://127.0.0.1:4321/`. ## Browser inspection note Attempted Playwright inspection for desktop/tablet/mobile against `docs/reference/api/issues`, but local Chromium could not launch because the container is missing `libatk-1.0.so.0`; `npx playwright install-deps chromium` could not complete because sudo requires a password. Existing QA follow-up should perform real browser review on the PR/canary. ## Canary No Cloudflare canary URL is available from this local PR creation step yet. |
||
|
DottaandPaperclip
|
5b4b489154 |
[codex] Add Skills docs hierarchy (#34)
## Summary - Add generated reference pages for bundled and optional skills. - Add Skills index pages and hierarchy-aware sidebar/breadcrumb navigation. - Add verification scripts for hierarchical Skills routes and static docs routes. ## Verification - `npm run sync:verify-nav` - `npm run docs:test:static-routes` - `npm run docs:build` - QA in PAP-11775 also verified browser rendering for hierarchy, bundled `task-planning`, and optional `last30days` pages with screenshots. ## Issues - PAP-11770 - PAP-11783 --------- Co-authored-by: Paperclip <[email protected]> |
||
|
DottaandClaude Opus 4.8
|
b65db4d0e1 |
Fix horizontal scroll on docs pages on mobile
Long unbreakable inline code tokens (file paths, API routes, config
keys like <paperclipInstanceRoot>/skills/{companyId}/...) and tab bars
with many tabs (e.g. one per provider) widened the page past the
viewport on narrow screens, causing horizontal scroll — most visibly
on /reference/skills.
- Inline <code> now wraps long tokens (overflow-wrap:anywhere) while
block code in <pre> keeps its own horizontal scroll.
- #article and links wrap long words/URLs.
- .tabs-bar scrolls horizontally instead of overflowing the page;
tab buttons keep their width (matches the code-tabs variant).
Verified with headless Chromium across all 135 docs pages at 320px
and 375px viewports: no page exceeds the viewport width (0 overflow).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
||
|
Aron PrinsandClaude Opus 4.7
|
515366b322 |
Align docs site with brand guide + mobile top-bar fixes (#17)
* style: align docs site with paperclip.ing brand guide Bring the docs site in line with the canonical brand tokens and fix two layout bugs found while verifying: - Radius scale: adopt the brand ramp (xs 4 / sm 10 / md 16 / lg 24 / pill) and apply by role (cards 16, controls/code/tables 10, chips/code 4, search modal 24). - Pill rule: reserve the pill shape for the primary Star CTA only; convert secondary controls (search, TOC toggle, copy-link group) to 10px rects and metadata/count chips to 4px. - Color: error red -> #DC2626, complete the named status palette, align callout deeps and dark-mode secondary/muted text to brand exact hexes. - Typography: enable OpenType ss01 + cv11 on body, tabular-nums on mono, tighten display-1 tracking to -0.04em. - Default to dark mode (set pre-paint in <head> to avoid a light flash). - Fix "All docs" sidebar button clipped on the left by overflow-x. - Fix doc body width: set --content-max to 920px so content fills the layout and lines up with the header/footer. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(nav): rework mobile top bar layout On mobile (<=560px) the top bar is now balanced and centered: - hamburger moved to the far left, with the search trigger beside it - paperclip icon + wordmark + "Docs" stay dead-centered - GitHub icon sits left of the Star button on the right - drop the star count on mobile so the side groups balance and the logo centers via flex (no overlap) Search is duplicated for the left/mobile slot and both triggers bind via a shared .js-search-open class. Desktop layout is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(nav): prevent header overflow on very narrow phones Hide the "Docs" logo suffix at <=360px. With the mobile search + GitHub buttons shown, the min content width of hamburger+search | Paperclip Docs | GitHub+Star was ~352px, overflowing viewports around 320px. "Docs" stays visible on common phones (375px+). Addresses Codex review P2. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(a11y): raise dark muted-text contrast to WCAG AA Dark --ash was set to the brand caption color #6E6960 (~3.4:1 on the dark bg), but --ash is reused for normal-size text (navbar links, counts, metadata, placeholders). Raise to #8A8579 (~5:1, AA) while keeping it dimmer than the secondary text token. Addresses Codex review P2. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
7604cbaeee |
nav: split centered logo into Paperclip (→ paperclip.ing) + Docs (→ docs.paperclip.ing)
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
fdec9f4e1e |
ui: italicize em via real Inter Tight italic, drop card left accent
- Load italic axis for Inter Tight/Inter from Google Fonts so #landing-title em renders true italic instead of synthetic slant - Drop the dimmed graphite color on em; inherit ink to match paperclip.ing - Remove the green left-edge ::after strip on .card (and its hover state) Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
894f3e0ec2 |
nav: mirror paperclip.ing footer, polish topbar font + colors
- Replace docs footer with paperclip.ing's structure (wordmark row, 4-column grid, bottom row) and pin it to the dark palette - Move search trigger from the left to the right of the navbar - Load Inter Tight as a variable font so weight 450 renders correctly - Set light-mode page background to pure white (matches paperclip.ing) - Bind navbar text colors to --graphite (light) / --ash (dark) so dark mode matches paperclip.ing's --mono (#9A958A) exactly Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
e3a6c14696 |
nav: align widths, swap sub-bar for search modal, add Blog/Docs menu
- Match paperclip.ing's layout frame exactly (max-width 1280, 24px padding) - Replace navbar links with Blog/Docs to mirror the marketing site - Add a navbar search trigger (icon + label + ⌘K kbd chip) - Move search into a centered modal opened by the trigger or ⌘K - Remove the sticky search sub-bar; relocate breadcrumb above article Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
5c2591263e |
nav: mirror paperclip.ing navbar with star counter + floating theme toggle
Replaces the docs topbar with paperclip.ing's three-column navbar (centered logo, left nav links, right Star CTA with live count), moves the theme toggle to a fixed bottom-right pill button, and relocates the search bar to a sticky sub-bar directly below the navbar. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
9ef52141d5 |
redesign: align docs design system with paperclip.ing
Retunes color tokens to paperclip.ing's "materials" palette (bond/manila/stone/charcoal/ink), swaps the display font from Instrument Serif to Inter Tight at weight 600 / -0.03em tracking, and tightens radii to 8/12 to match. The dark theme shifts from cool blue-grey to warm charcoal with manila cream text. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
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]>
|
||
|
Claude
|
9415607e4f |
Add copyright and license notice to site footer
Mirrors the README license section: copyright to Aron & Sharon (aronandsharon.com), links to the Paperclip software repo for its open-source license, and CC BY-NC-ND 4.0 for the docs with the no-commercial-use clause. |
||
|
Aron PrinsandClaude Opus 4.7
|
ecefa37003 |
Add icon to On this page toggle and collapse action labels on mobile
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
b206be6d81 |
Hide article hr dividers by using transparent border
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
6f380a1620 |
Move site shell to /site, split into html/css/js, add favicon
Separate the docs SPA from its content: docs/docs-website/ becomes site/ at the repo root so docs/ holds only markdown. Extract inline <style> and <script> from index.html into styles.css and app.js. Add an inline-SVG favicon using the header paperclip glyph. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |