handbook A — repo, MkDocs scaffold and Pages publishing

[serina-mcfall]

Dependencies

Blocked by: nothing — this is the first sub-issue to start.
Blocks: #7 (the page contract), and therefore everything downstream of it.

Start here. It de-risks the one part nobody has tested: Pages on this org, and this Actions workflow.

---

Part of #4 — the handbook knowledge layer.

Stand up launchpad-26/handbook and prove it publishes automatically, before any real content exists.

This goes first deliberately. Nobody in the cohort has enabled GitHub Pages on this org or run this workflow. It is the only part of the design that could hit a wall changing everything downstream — so find that out with a placeholder page, not with twelve real ones.

Scope

• Create launchpad-26/handbook, private
• Configure GitHub Pages access control so only organisation members can view the site
• MkDocs project at the repository root
• Navigation skeleton for the eleven categories: Getting started, Architecture, Deployment, Operations, Agents and AgentOps, Development workflows, Security, Upstream Buzz, Launchpad-specific behaviour, Troubleshooting, Reference
• GitHub Actions workflow: on push to the default branch, run mkdocs build and deploy to Pages using the workflow's own GITHUB_TOKEN
• One placeholder page so the site renders

Acceptance

• First, before anything else: confirm a private launchpad-26 repo can serve a Pages site restricted to org members. If it cannot, stop and reopen the scope question — do not proceed by making the repo public.
• A site is live at the URL GitHub assigns to a private Pages site
• A logged-out browser cannot read it; an org member can
• Merging a change to the default branch republishes it without manual steps
• The built HTML is workflow output — not committed, not hand-editable
• No deployment secret was needed

Corrected: the site URL is not launchpad-26.github.io/handbook

The original wording of the second criterion was wrong, and the first criterion is what caught it.

A private, access-controlled Pages site is served from a randomised *.pages.github.io subdomain, assigned by GitHub. The predictable <org>.github.io/<repo> form exists only for public sites. launchpad-26.github.io/handbook will never resolve, so a criterion demanding it could never have been met.

The live site is https://ideal-adventure-2yyn6ow.pages.github.io/. site_url is deliberately left unset in mkdocs.yml rather than hardcoded to a value GitHub assigns and could change.

§9 of the design document states the same wrong URL and needs the same correction.

Evidence

Verified 2026-08-11, in the order the criteria demand.

Access control is available and on:

GET /repos/launchpad-26/handbook/pages
{"build_type": "workflow", "public": false, "https_enforced": true}

public: false is the org-only restriction. Available because launchpad-26 is on the enterprise plan.

A logged-out request does not get the content:

anonymous GET https://ideal-adventure-2yyn6ow.pages.github.io/
  -> HTTP 302
  -> location: https://github.com/pages/auth?nonce=...&page_id=83048225
  -> follows to github.com/login

The site builds and publishes on push to main: the Publish workflow completed success on the scaffold commit, and all eleven category pages render.

Built locally first: mkdocs build --strict passes; site/ is gitignored and never committed.

No deployment secret: deploys with the workflow's own GITHUB_TOKEN.

Why private, and why this is the riskiest step

Two of the five source repositories the handbook draws on — launchpad-26/launchpad and launchpad-26/skills — are private. A public site citing them would fail two ways at once: a reader outside the org following a [cohort] citation gets a 404, and an agent synthesising a page from a private repo would publish cohort material to the internet.

A private, org-scoped site removes both, because every reader of a citation is someone already entitled to read its source.

This is possible because launchpad-26 is on the enterprise plan, where a private repo can publish a Pages site with access restricted to org members. That is a platform feature governed by enterprise policy, so verify it works before building on it — hence the first acceptance criterion. If it turns out to be unavailable, the fallback is restricting the handbook to public sources only, which is a scope decision and not this issue's to make.

Watch out for

• Nothing sensitive, from the very first commit — no live hostnames, keys, tokens, .env bodies, or member rosters. Private lowers the blast radius; it does not change the rule. A private repo is read by everyone in a 1,948-seat org, cloned to laptops, and one settings change from public.

[serina-mcfall]

Done — all criteria met, and the first one earned its place

launchpad-26/handbook is created (private), scaffolded, and publishing. Every criterion above is ticked with evidence in the body.

The verify-first criterion caught a wrong assumption before anything was built on it. This issue demanded a site at https://launchpad-26.github.io/handbook. That URL will never exist: a private, access-controlled Pages site is served from a randomised *.pages.github.io subdomain, and the predictable <org>.github.io/<repo> form is public-sites-only.

Had the criteria not put verification first, the scaffold, the workflow and possibly the page contract would all have been written against a URL that cannot resolve.

Live at https://ideal-adventure-2yyn6ow.pages.github.io/ — renders when signed in to GitHub, bounces to login when not.

What landed

• MkDocs + Material, versions pinned — a site that builds differently next Tuesday cannot be reproduced, and reproducibility is the point of pinning a source commit on every page
• Navigation skeleton for all eleven categories, organised by user need not repository layout (Ruling 3)
• Every category page says plainly that it is empty. An empty category is worse than an absent one; a placeholder implying coverage is worse than both
• index.md warns that nothing on the site is authoritative yet, and tells readers not to cite it until handbook B — the page contract: frontmatter, claim rule, origin prefixes #7 and handbook E — first content set across the eleven categories #10 land
• Actions workflow building with --strict, so a broken internal link or a page missing from the nav fails rather than ships
• Pages write permission on the deploy job only; concurrency does not cancel in progress, because a cancelled deploy can leave the site serving a half-written build

Still to correct elsewhere

§9 of the design document states the same wrong URL. It lives in a private repository, so that correction goes through the review gate.

Unblocked

#7 — the page contract. Everything else depends on it: #8 enforces it, #9 produces it, #11 reads it.