Set up documentation worktree for mid-feature docs editing

[deanleigh]

Problem

Documentation does not get written, because the thought arrives at the worst moment. You are several files deep in a feature and realise something needs documenting. Acting on it means stashing work, switching branch, writing, switching back, finding your place.

Each instance is a small cost. In aggregate it is fatal: the docs wait, and then they do not happen.

UmBootstrap has a sharper version of this problem than sibling projects: docs.yml currently triggers on main only, so even a typo fix waits for a release.

Approach

A permanent docs/site branch checked out in a git worktree at .worktrees/docs, deploying to GitHub Pages on every push. Write it, push it, it is live, back to work.

Adapted from the UpDoc implementation.

Tasks

• Create permanent docs/site branch off develop, push to origin
• Add worktree at .worktrees/docs, add to .gitignore
• npm install inside the worktree (own working copy, own node_modules)
• Gate 1: point docs.yml at docs/site
• Gate 2: add docs/site to the github-pages environment deployment branch policy
• Write WORKTREES.md at repo root
• Add a Documentation Worktree section to CLAUDE.md, above the existing docs section
• Verify end to end: real change, push, confirm the deploy job succeeds and the live site updates

Deliberate decisions

Publish immediately, do not gate on main. Gating reintroduces the friction the worktree exists to remove. Documenting unreleased features is a writing decision, not a branching one; if something must wait, it waits unpushed in the worktree.

Trigger on docs/site only, dropping main. Both branches would publish different content, and last-writer-wins means a release deploy would silently overwrite newer docs with the older main copy until the next docs push. concurrency: group: pages prevents collisions but not this. One deploying branch removes the ambiguity.

Skip the .gitattributes LF rules. They are only needed where build output is committed. git ls-files docs/dist returns 0 here.

Findings while investigating

GitHub Pages reports build_type: legacy with source gh-pages, which contradicts the workflow. docs.yml uses the Actions artifact flow (upload-pages-artifact / deploy-pages), which requires build_type: workflow.

Not a live problem. Verified:

• Latest docs.yml run: build and deploy both succeeded
• Live site serves Astro v6.0.8 / Starlight v0.38.2, matching main
• gh-pages last commit is Deployed 26f6c59 with MkDocs version: 1.6.1, a fossil from the pre-Starlight site

So the Actions flow publishes correctly and the setting is stale metadata. Recorded because it is misleading to anyone reading Pages settings.

Branches safe to delete, separately from this work:

• gh-pages (dead MkDocs build)
• feature/docs-reorganisation (fully merged into main and develop)
• 5 stale Dependabot branches for the docs npm tree, obsolete after the Astro 7 upgrade