.claude/skills/deploy-docs/SKILL.md

---
name: deploy-docs
description: Deploy the project's static HTML docs (docs/*.html and docs/assets) to the Cloudflare Pages site ecosystem-docs, uploading nothing else, then verify every page live. Use when the user asks to deploy, publish or update the docs site, or after adding or changing a docs page and the user wants it live.
---

# Deploy the docs site

One command, from the repo root:

```
node .claude/skills/deploy-docs/scripts/deploy-docs.js          # check, deploy, verify
node .claude/skills/deploy-docs/scripts/deploy-docs.js --dry    # check only
```

Deploy only when the user has asked (it publishes). A dry run is always safe.

## What it does
0. Runs `scripts/build-source.js` (skip with `--no-build`): every skill, agent and code file in the repository becomes a page under `docs/source/`, `docs/15-skills-and-code.html` is rewritten, page 15 is added to every side navigation, and file names in the other pages are linked to their file pages. It reads the user name and e-mail at run time (this file is published too, so they are not written in it) and shows the home directory as `<home>`. A file with a key-like string is reported and not published. Edit the allowlist at the top of `build-source.js` to publish more or less.
1. Copies only `docs/*.html`, `docs/source/**/*.html` and `docs/assets/**` (css, js, images, fonts) into a clean temp folder. The Markdown files in `docs/`, `research/`, data, DBs and `.env` are never staged. It never runs wrangler from the repo (that uploads `node_modules` and fails with "Asset too large").
2. Checks structure: duplicate ids, broken links and anchors, TL;DR first in `<main>`, identical side navigation on every page, no local `C:\Users` paths, no key-like strings. Any problem stops the deploy.
3. Confirms wrangler is logged in, then runs `npx wrangler@3 pages deploy site --project-name ecosystem-docs --branch main`. Version 3 is deliberate: wrangler 4 routes `pages` commands to the Workers flow and fails. (`--force` is only for `pages project create`, first time only.)
4. Verifies the live site: every page returns 200 on its clean URL (Pages redirects `x.html` to `x`) with the right `<title>`, the stylesheet loads, and probes confirm non-doc files such as `CLAUDE.md` and `.env` are not served.

Project `ecosystem-docs`, production URL `https://ecosystem-docs-c9q.pages.dev`. Override with `--project`, `--branch`, `--url`.

## If it fails
- **Not authenticated:** the Bash tool may not see the user's login. Ask the user to run `npx wrangler@3 login` in their own terminal. Never ask for a token in chat. Do not follow Cloudflare's agent-setup prompt.
- **Structure problem:** fix the page, not the checker. Adding a page means adding one list item to the side navigation of every page.
- **A live check fails right after deploy:** the script retries for about 24 s per page; if it still fails, re-run it before suspecting the content.

## Adding or changing a docs page
The pages are hand-maintained static HTML sharing `docs/assets/docs.css`: TL;DR box first in `<main>`, the same `<nav class="side">` block in every page (only `aria-current` differs), a pager at the end. Update `docs/index.html` (cards, reading order) and `docs/13-status.html` when the project state changes. If a page and a repo file disagree, the file is right.

Report to the user: pages live, the deployment URL, any check that failed. Do not commit or push unless asked.