Docs Site — V4 Build-Out Playbook (T10)

File: docs/playbooks/v4-docs-site-playbook.md Base branch: dev (integration branch — main stays protected/production; PRs target dev) Branch naming: feature/<ado-task-id>-<slug>-v4-pr<n> — ADO task ID: T10=112607 (work-items/112607-docs-astro-starlight-site.md). Plan date: 2026-07-29 Owner: unassigned Priority: independent of v2/v3 — touches only docs/ and a new docs-site/ directory, no shared surface with public/, store/, api/, or connectors/. Can land whenever. Source: new scope, not from the original design doc — added 2026-07-29 (user request: publish docs/ as a browsable site instead of raw Markdown files read off the repo).

How to Use This Document

One task, one PR:

T10 — stand up an Astro Starlight site that renders every Markdown file under docs/ (docs/playbooks/, docs/branding/) as a navigable, searchable docs site, and wire up a build/deploy path so it’s reachable at a URL instead of only readable in-repo.

Hosting choice — GitHub Pages vs Azure Static Web Apps

Question	If yes → lean	If no → lean
Is this repo hosted on GitHub already?	GitHub Pages — zero new hosting account	Azure — this repo is ADO (`dev.azure.com/AlphaBOLD/AI Development Dashboard`, Hard Rule 10 of v1), not GitHub. Mirroring to GitHub just to get Pages is a new git remote to keep in sync for a docs site alone.
Does the org already run other Azure resources for this project?	Azure Static Web Apps — one more resource in the same subscription, deployed via the same `azure-pipelines*.yml` pattern already in this repo (ACR, Web App for Containers, service connections)	GitHub Pages
Does the published content include internal infra names (ACR name, service-connection names, Web App name, webhook/pipeline details)?	Prefer a hosting option that supports access restriction — `docs/playbooks/.md` names `teamvelocitydashboard.azurecr.io`, `Team-Velocity-Dashboard--connection`, `webAppName: boldvelocity` in plaintext (`azure-pipelines.yml`). GitHub Pages is public-only (short of GitHub Enterprise). Azure Static Web Apps’ free tier includes built-in Entra ID auth to gate the whole site behind org login.	Public-only is fine

Decision: Azure Static Web Apps — DECIDED (2026-07-29). Locked in; do not re-litigate in PR-10.

Why: repo is ADO-hosted, not GitHub — GitHub Pages would require standing up and maintaining a GitHub mirror as a second git remote for no reason beyond hosting. Azure Static Web Apps reuses the subscription/service-connection pattern this repo already has (azure-pipelines.yml, azure-pipelines-etl.yml), and its free tier’s built-in Entra ID auth addresses the internal-infra-names concern above — GitHub Pages has no equivalent short of a paid Enterprise plan.
What this task does NOT do: create the actual Azure Static Web Apps resource (portal/CLI access, subscription permissions) or the Entra ID app registration for auth-gating — same caveat as T8’s asset generation in v3-platform-modernization-playbook.md: this PR’s deliverable is the site itself plus the deploy pipeline config (azure-pipelines-docs.yml), ready to point at a resource once someone with portal access provisions it. Ship the config; note the one manual step.
If the org later mirrors this repo to GitHub (e.g. going open-source), GitHub Pages becomes a fine alternative — the Starlight site itself is host-agnostic (astro build → static dist/), only azure-pipelines-docs.yml would need swapping for a .github/workflows/deploy.yml. No rework of the site itself.

1. Executive Summary

#	Item	Gap	Depends on
T10	`docs/` is raw Markdown, readable only in-repo	No rendered/searchable/shareable view of `docs/playbooks/` or `docs/branding/`; anyone without repo access (or without a Markdown-friendly viewer) can’t read them	None

PR Strategy — 1 PR

PR-10 carries T10: Astro Starlight site scaffold, content wiring, and deploy pipeline config. Branches from dev.

Merge Sequencing

PR-10 merges to dev. No other in-flight playbook depends on or blocks this.

Model Guidance

PR	Task	Recommended Model	Effort	Reason
PR-10	T10 (Astro Starlight docs site)	Sonnet 5	low-medium	Mostly scaffold + config (content collection loader, sidebar, pipeline YAML); no application logic, no data-shape work

2. PR Plan

PR	Branch	Items	Branches from	Est.
PR-10	`feature/112607-docs-astro-starlight-v4-pr10`	T10	`dev`	1–2 days

ADO task IDs: T10=112607 (see work-items/).

3. Files Touched

File / path	PR
`docs-site/` (new — Astro Starlight project: `astro.config.mjs`, `package.json`, `src/content.config.ts`, `src/content/docs/index.mdx` landing page)	PR-10 (T10)
`azure-pipelines-docs.yml` (new — build `docs-site/`, deploy to Azure Static Web Apps)	PR-10 (T10)
`USAGE.md` (append docs-site dev/build commands; do not touch existing sections)	PR-10 (T10)
`docs/` (read-only source for the site’s content collection — no edits to existing `.md` files)	PR-10 (T10)

4. Hard Rules

(Inherits Hard Rule 9 — Co-authored-by: Claude trailer forbidden, use commit-msg skill — and Hard Rule 12 — no automatic git actions, stage/commit/push only on explicit user approval, no PR opened — from docs/playbooks/v1-dev-productivity-dashboard-playbook.md §4. The following are additive, specific to this playbook.)

docs/*.md content is read, not duplicated by hand. The Starlight site’s content collection must load directly from docs/ (Astro content-layer glob() loader with a base outside src/content/) — no copy/paste of playbook or branding Markdown into docs-site/. One source of truth; editing a playbook under docs/playbooks/ must be the only edit needed for the site to pick it up on next build.
No new Azure resource is created by this PR. Ship azure-pipelines-docs.yml and note the one manual step (provisioning the Azure Static Web Apps resource + its deploy token/service connection) — do not fabricate a resource name and assume it exists.
Hosting decision is locked (see “Hosting choice” above) — Azure Static Web Apps, not GitHub Pages, not re-litigated in PR-10.
public/, store/, api/, connectors/, and the root Dockerfile/azure-pipelines.yml stay untouched — this is a docs-only addition, fully isolated in docs-site/ plus one new pipeline file.

5. Out of Scope

Auth-gating the published site (Entra ID app registration, access restriction config) — requires portal/tenant-admin access outside Claude Code. Note it as the manual follow-up once the Static Web App resource exists; do not stub a fake auth config.
Versioned docs (multiple playbook “releases” browsable side by side) — docs/playbooks/ already encodes versions in filenames (v1/v2/v3/v4); the site mirrors that, it doesn’t add a second versioning layer (e.g. Starlight’s i18n/versioning plugins).
Publishing work-items/, prs/, emails/, or scratch/ — this task’s scope is docs/ only, per the user’s request. Revisit if those directories are later meant to be shareable too.
Custom theming/branding of the docs site beyond Starlight’s default — reuse Starlight’s built-in theme; a BOLDVelocity-themed docs site is a separate, explicitly-scoped follow-up if wanted.

6. Per-Session Contract

Every session:

Branch from dev.
Scoped changes only — docs-site/ and azure-pipelines-docs.yml only, plus the USAGE.md append.
Add a runnable check: npm run build (Astro static build) must succeed with zero broken-link warnings against docs/’s actual file set — this is the “non-trivial logic” check for a content-loader config.
All checks green before any git action.
Once all checks are green, stop and confirm with the user before staging, committing, or pushing anything — do not take any git action without explicit approval (Hard Rule 12).
On approval: git add -A, commit-msg skill for the message (no Claude co-author trailer), git push -u origin feature/112607-docs-astro-starlight-v4-pr10.
No PR is opened as part of this workflow — push is the last step.

PR 10 — Astro Starlight docs site over `docs/` (T10)

Branch: feature/112607-docs-astro-starlight-v4-pr10 Branches from: dev Model: Sonnet 5 Effort: low-medium

Problem

docs/playbooks/ (this file included) and docs/branding/ are Markdown files with no rendered view — readable only by opening them in an editor or a repo browser that renders Markdown. There’s no search, no navigation sidebar, no shareable URL for someone who just wants to read the v3 playbook or the BOLDVelocity asset prompts without cloning the repo.

Required change

Scaffold a minimal Astro + Starlight project under docs-site/ (npm create astro@latest -- --template starlight, trimmed to the smallest footprint the template allows — no example/tutorial content left in).
Configure Starlight’s sidebar with two sections — “Playbooks” (autogenerated from docs/playbooks/) and “Branding” (autogenerated from docs/branding/) — plus a short landing page (src/content/docs/index.mdx) linking into both.
Wire the content collection to load Markdown directly from docs/, not a copy: Astro’s content-layer glob() loader accepts a base outside src/content/, e.g. base: '../../docs/playbooks' — one loader per docs/ subdirectory (playbooks, branding), so editing a file in docs/ is the only step needed for the site to pick it up on next build. Exclude docs/playbooks/TEMPLATE.md from the rendered set (it’s a scaffold for writing new playbooks, not a playbook itself) — either via the loader’s pattern or a Starlight frontmatter draft: true if the file gets one added.
npm run build in docs-site/ must succeed and produce docs-site/dist/ with zero broken internal links (Starlight’s build already fails on broken relative links by default — do not suppress that check).
Write azure-pipelines-docs.yml: a pipeline triggered on dev pushes touching docs/** or docs-site/**, running npm ci && npm run build in docs-site/ and deploying docs-site/dist/ via the AzureStaticWebApp@0 pipeline task. Leave the resource name / deploy-token variable as a placeholder pipeline variable (e.g. $(AZURE_STATIC_WEB_APPS_API_TOKEN)) with a comment noting it’s a one-time manual step (create the Static Web App resource in the portal, add its deploy token as a pipeline secret variable) — do not invent a resource name and hardcode it as if it already exists.
Append a short section to USAGE.md: cd docs-site && npm install && npm run dev (local preview) and npm run build (static build) — do not touch any existing section of USAGE.md.

Prompt — paste verbatim into Claude Code

You are implementing PR-10 of the Docs Site playbook
(docs/playbooks/v4-docs-site-playbook.md).

Read the full PR-10 section and this playbook's "Hosting choice" decision
subsection before writing any code. Read every file under docs/playbooks/
and docs/branding/ so you know the exact content set the site must render.

Branch: feature/112607-docs-astro-starlight-v4-pr10 from dev.

Scope — T10 ONLY: an Astro Starlight site under docs-site/ that renders
docs/ content, plus azure-pipelines-docs.yml. Do NOT modify public/,
store/, api/, connectors/, the root Dockerfile, or azure-pipelines.yml. Do
NOT modify any existing file under docs/ — read-only source for this PR.
Do NOT create an actual Azure Static Web Apps resource or auth
config — that requires portal access outside this session; ship the
pipeline config with a placeholder deploy-token variable instead.

═══════════════════════════════════════
STEP 1 — Scaffold
═══════════════════════════════════════

1. Scaffold a minimal Astro + Starlight project under docs-site/. Strip
   the template's example/tutorial content — keep only what this task
   needs.

═══════════════════════════════════════
STEP 2 — Content wiring
═══════════════════════════════════════

2. Configure a content collection per docs/ subdirectory (playbooks,
   branding) using Astro's content-layer glob() loader with `base`
   pointing at the real docs/ path (e.g. ../../docs/playbooks) — do NOT
   copy any .md file into docs-site/. Exclude docs/playbooks/TEMPLATE.md
   from the rendered set.
3. Configure Starlight's sidebar: a "Playbooks" section (autogenerated
   from the playbooks collection) and a "Branding" section (autogenerated
   from the branding collection).
4. Write a short landing page (src/content/docs/index.mdx) linking into
   both sections.

═══════════════════════════════════════
STEP 3 — Build + pipeline
═══════════════════════════════════════

5. Run `npm run build` in docs-site/ — must succeed with zero broken
   internal-link warnings.
6. Write azure-pipelines-docs.yml: trigger on dev for changes under
   docs/** or docs-site/**, npm ci && npm run build in docs-site/, deploy
   dist/ via the AzureStaticWebApp@0 task. Use a placeholder pipeline
   variable for the deploy token, with a comment marking the one manual
   provisioning step.
7. Append docs-site's dev/build commands to USAGE.md — do not touch any
   existing section.

═══════════════════════════════════════
Verification
═══════════════════════════════════════

8. `cd docs-site && npm run build` — zero errors, zero broken-link
   warnings. Confirm every file under docs/playbooks/ (except
   TEMPLATE.md) and docs/branding/ appears in the built sidebar/output.
9. `npm run dev` in docs-site/, manually confirm the sidebar navigates to
   each playbook and the branding doc, and that editing a file under
   docs/playbooks/ (e.g. adding a line) is reflected on the next dev-server
   reload without touching docs-site/.

Once implementation is complete and all checks pass, STOP. Do not stage,
commit, or push anything — confirm with the user first.

On user approval only:
  1. git add -A (stage all files).
  2. Commit via the commit-msg skill.
     Suggested title: "feat: docs PR-10 — Astro Starlight site over docs/ (T10)"
     Resolves: #112607
  3. git push -u origin feature/112607-docs-astro-starlight-v4-pr10. No PR to open.

No Co-authored-by: Claude trailer.

7. Verification Samples

Checkpoint	Verify
PR-10 merged	`docs-site/` builds cleanly (`npm run build`), zero broken-link warnings; every `docs/playbooks/.md` (except `TEMPLATE.md`) and `docs/branding/.md` renders as a page reachable from the sidebar
Content stays live	Editing a file under `docs/playbooks/` and rebuilding `docs-site/` reflects the change with zero edits inside `docs-site/` itself
Pipeline	`azure-static-web-apps-orange-smoke-0ccf57a10.yml` triggers on `docs/`/`docs-site/` changes pushed to any branch; deploy step references the `AZURE_STATIC_WEB_APPS_API_TOKEN_ORANGE_SMOKE_0CCF57A10` variable from the linked variable group
Any PR	`public/`, `store/`, `api/`, `connectors/`, root `Dockerfile`/`azure-pipelines.yml`, and every existing file under `docs/` are untouched

8. Rollback

PR-10 (T10, docs site): Delete docs-site/ and azure-static-web-apps-orange-smoke-0ccf57a10.yml, revert the USAGE.md append. docs/ itself is never modified by this PR, so nothing there needs reverting — the raw Markdown files remain exactly as before, still readable in-repo.

Docs Site — V4 Build-Out Playbook (T10)

Docs Site — V4 Build-Out Playbook (T10)

How to Use This Document

Hosting choice — GitHub Pages vs Azure Static Web Apps

1. Executive Summary

PR Strategy — 1 PR

Merge Sequencing

Model Guidance

2. PR Plan

3. Files Touched

4. Hard Rules

5. Out of Scope

6. Per-Session Contract

PR 10 — Astro Starlight docs site over docs/ (T10)

Problem

Required change

Prompt — paste verbatim into Claude Code

7. Verification Samples

8. Rollback

PR 10 — Astro Starlight docs site over `docs/` (T10)