Publish a docs site

What you get: the project's docs as a static HTML manual on GitHub Pages, pushed only after your GO.

Inputs

• repo — the local checkout, default the current directory; <owner/repo> comes from git -C <repo> remote get-url origin
• source — where the content lives: OpenWiki pages, the README, or docs/

Steps

1. Preflight — gh auth status, then gh api repos/<owner>/<repo>/pages → run log header — gh missing, unauthenticated or no GitHub remote → log it, give the gh auth login / remote hint, stop; 404 → stop with "Pages not enabled: enable it in repo settings", this playbook does not enable Pages; a private repo whose Pages call is refused for plan reasons → stop with "Pages on a private repo needs a paid plan", and never change the repo's visibility. Then openwiki-skill — wiki refreshed or confirmed current → log line — Pages answered and the wiki is current
2. readme and documentation — source against the code → list of doc gaps in the run log — stops for approval
3. bdbhtmlmanueldocs — approved content → site files in docs/ (or the Pages source path the step 1 response names) — files written, nothing committed; the skill's Pages build-type switch (gh api -X PUT .../pages) and its Pages deploy workflow are NOT run here, only the site files are written
4. Preview — a local preview link or the path to the built index.html in the run log — link or path given
5. [GO] git push — the site files committed to the branch and path the step 1 response names as the Pages source; the WAITING FOR GO line names the branch and the file list. The WAITING FOR GO line also says: a Pages site of a private repo is public. The run stops here until the human types GO. Where the hook runs, it covers git push; it does not cover gh api settings writes, so no Pages setting or workflow is changed in this playbook.
6. github — gh api repos/<owner>/<repo>/pages -q .status equals built (poll, at most 5 minutes), then curl -sI <pages_url> → status line in the run log — returns 200

Run log: production_artifacts/pb-docs-site-<date>.md in the start directory, never committed

Rules

• Anything other than the literal GO (case-insensitive) is not a GO; a GO covers only that one step, one time.
• GO is by contract in every harness. The go-gate hook is only a backstop on Claude Code, OpenCode and agy (Codex: unverified; Cursor, Kimi: none). A missing hook is never permission to proceed.
• A failed check stops the run: write the failure into the run log and report. No silent retries.
• Write one run-log line per step as it completes (N. done|skipped|failed — artifact — check result) and WAITING FOR GO: <step> at each gate.