Make versioned docs incremental with immutable release snapshots

[kjanat]

Problem

The current @micro509/vitepress-versioned-docs design deliberately renders the complete documentation history in one VitePress build:

• / — newest published release
• /next/ — checked-out tree
• /vX.Y.Z/ — every superseded release

versionedDocs() fetches the npm packument, downloads/materializes every tagged source tree, regenerates the API reference for every release, and then exposes all of those pages to one VitePress build. The local tag-tree cache saves downloads, but clean CI builds still regenerate and render an increasingly large number of old sites. Build time and output size therefore grow with every release, and the existing 19,500-file guardrail will eventually become the limiting factor.

Today that cost is paid twice per push: the GitHub Pages workflow and Cloudflare's push-triggered build each render the complete history, and every PR preview repeats it on Cloudflare's always-clean builders.

Old documentation is immutable build output. It should be built once and preserved, not reconstructed from source on every deployment.

Proposed architecture

Keep the existing Cloudflare deployment and custom domain. Do not move to GitHub Pages and do not create a hostname/subdomain per version. Continue serving path-based versions from one origin:

/             latest stable release
/next/        current master
/v0.11.0/     immutable release snapshot
/v0.10.0/     immutable release snapshot
...

Use a generated orphan branch, e.g. docs-site, as a persistent deployment tree:

/
├── index.html
├── assets/              # latest stable root build
├── guide/
├── reference/
├── api/
├── next/                # replaced on each master deployment
├── v0.11.0/             # written once
├── v0.10.0/             # written once
├── versions.json        # small mutable global catalog
└── ...

Cloudflare should deploy this already-built tree. GitHub Actions performs the incremental mutation; Cloudflare does not need to rebuild VitePress.

Build behaviour

Push to master

Build only the checked-out tree for /next/:

1. Check out docs-site into a worktree such as .publish.
2. Build the current source with the /next/ base/prefix.
3. Replace only .publish/next/ using rsync --delete within that directory.
4. Refresh versions.json metadata if necessary.
5. Preserve /, /v*/, and every other archived path untouched.
6. Commit/push the resulting deployment tree and deploy it.

The cost remains one VitePress build regardless of the number of releases.

Release tag vX.Y.Z

Build only the new release:

1. Check out the existing docs-site tree.
2. Build the tag with base /vX.Y.Z/ and write it to .publish/vX.Y.Z/.
3. Refuse to overwrite an existing release directory unless an explicit repair mode is used; release snapshots should be immutable.
4. Build the same tag once more with base / and replace only the root/latest files, excluding next/ and v*/ from deletion.
5. Update versions.json.
6. Commit/push and deploy.

A release therefore costs at most two builds: one immutable versioned snapshot and one root/latest build. No older release is read or rebuilt.

A later optimization could redirect the unversioned root to the latest /vX.Y.Z/ snapshot and eliminate the second build, but preserving the current root URLs and SEO behaviour is simpler initially.

Pull request preview

Cloudflare PR preview builds are the one retained benefit of push-triggered building. A preview renders only the checked-out tree as a single next-style target with release discovery offline: one VitePress build, no packument fetch, no tag trees. Previews never touch docs-site.

Required refactor

1. Split release discovery from release rendering

The plugin currently resolves the complete release catalog and materializes every release before VitePress starts. Introduce a single-target build mode instead, for example:

DOCS_CHANNEL=next
DOCS_CHANNEL=latest DOCS_VERSION=v0.11.0
DOCS_CHANNEL=archive DOCS_VERSION=v0.11.0

Exact names are not important, but one build must materialize and render only one source tree. The full npm release list should be metadata, not a list of source trees that must all be generated.

The existing all-versions mode can remain temporarily as a bootstrap/repair command, but it should no longer be used for normal deployments.

2. Make the version switcher use the global catalog at runtime

Currently themeConfig.versions is compiled into every generated site. An immutable old snapshot would therefore never learn about newer versions unless rebuilt.

Serve the authoritative catalog at /versions.json and have VersionSwitcher load it from the absolute root at runtime, with the embedded build-time list only as a fallback. This allows an old /vX.Y.Z/ snapshot to show every later release without modifying its files.

Version-specific sidebars, import maps, page rewrites, source links, and API docs remain static and baked into the snapshot.

3. Scope deletion carefully

Never run rsync --delete over the whole publish tree without exclusions.

For next:

rsync -a --delete site/.vitepress/dist/ .publish/next/

For root/latest, delete stale root files while preserving archives:

rsync -a --delete \
  --exclude '/next/' \
  --exclude '/v*/' \
  site/.vitepress/dist/ \
  .publish/

The exact staging paths may differ once single-target mode exists, but deletion must be constrained to the target being replaced.

4. Serialize deployments

Use one GitHub Actions concurrency group for the publish tree:

concurrency:
  group: docs-site
  cancel-in-progress: false

This prevents a master deployment and release deployment from checking out the same old docs-site tip and overwriting each other.

5. Keep generated-branch history bounded

docs-site should be an orphan branch containing generated output only. Avoid accumulating every historical replacement of large generated files forever.

Either:

• amend/squash the branch to one current snapshot and push with --force-with-lease, or
• periodically recreate/squash the branch while keeping the deployed tree identical.

The immutable documentation directories remain present in the current tree; they do not need Git history to provide immutability.

6. Deploy the prebuilt tree to Cloudflare

Cloudflare is the only production origin. The GitHub Pages deployment serves no consumer and is retired as part of this work; its removal costs nothing because per-PR previews, the one feature in use, come from Cloudflare (preview_urls).

Two viable implementations:

• GitHub Actions directly runs wrangler deploy against .publish, or
• Cloudflare watches the generated docs-site branch and performs no VitePress build (exit 0, branch root as the static asset directory).

Direct deployment from the workflow is probably less magical and keeps the mutation and deployment atomic, while still retaining docs-site as an inspectable, host-independent artifact.

Migration

1. Run the current complete-history build once to bootstrap docs-site with all existing versions.
2. Add single-target build support to vitepress-versioned-docs.
3. Change VersionSwitcher to consume /versions.json dynamically.
4. Add the serialized incremental deployment workflow.
5. Point Cloudflare at the prebuilt output/direct Wrangler deployment.
6. Retire the GitHub Pages deployment (deploy-site.yml); Cloudflare serves production and PR previews.
7. Stop using the complete-history build for ordinary master, release, and PR preview deployments.
8. Keep an explicit manual repair workflow capable of rebuilding one selected version or, if genuinely necessary, bootstrapping the complete site again.

Acceptance criteria

• A normal master deployment invokes VitePress exactly once and changes only /next/ plus global metadata.
• A release deployment invokes VitePress at most twice and creates only the new /vX.Y.Z/ snapshot plus root/latest.
• Existing /vX.Y.Z/ directories are byte-for-byte untouched by later deployments.
• Old snapshots display newly released versions through the version switcher without being rebuilt.
• Version-specific import maps still resolve the matching library release.
• Links, sidebars, source links, canonical/noindex behaviour, sitemap output, and live examples remain version-correct.
• Deployment work remains effectively O(1) as the number of archived versions grows.
• A PR preview build renders only the checked-out tree: one VitePress invocation, offline release discovery.
• Exactly one production origin remains; the GitHub Pages deployment is removed.
• The current /, /next/, and /vX.Y.Z/ public URL scheme remains valid.
• Concurrent master/release runs cannot lose each other's changes.
• The generated branch does not accumulate unbounded historical build output.

Non-goals

• Moving the site to GitHub Pages.
• Creating a Cloudflare Worker/project or custom domain per release.
• Rebuilding old releases merely to update global navigation metadata.
• Switching existing patch-version URLs to minor-version URLs as part of this change; that can be considered separately without coupling it to the incremental deployment work.

[coderabbitai]

🔗 Related PRs

#1 - Exports harmonization, standards compliance, docs site [merged]
#10 - CI runtime smoke (workerd + browser) and manual-publish guard [merged]
#44 - Versioned docs: root = npm latest, /next/ canary, /vX.Y/ archives [merged]
#54 - Runnable examples: one HTML file, and a Vite app [merged]
#59 - refactor(docs): adopt importmapify [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Split discovery from rendering so versionedDocs() builds exactly one tree per invocation (DOCS_CHANNEL/DOCS_VERSION + per-target VitePress base), keeping the all-versions path only for bootstrap/repair.
• Make versions.json a cheap, decoupled metadata catalogue and have VersionSwitcher fetch it at runtime (with the baked list as fallback) so immutable snapshots learn of new releases without rebuilding.
• Deploy incrementally from a serialised (concurrency: docs-site) GitHub Actions workflow that mutates a persistent docs-site orphan branch with tightly-scoped rsync --delete, squashes history via --force-with-lease, and runs wrangler deploy — leaving old /vX.Y.Z/ snapshots byte-for-byte untouched and deployment cost effectively O(1).
• Arrr, and document the whole rig in the AGENTS.md/CHANGELOG so no future scallywag rebuilds the entire fleet by accident.

Design Choices

Design Choice 1: How should the prebuilt tree reach Cloudflare?

Options Considered:

1. GitHub Actions runs wrangler deploy against .publish directly (mutation and deploy stay atomic in one job).
2. Cloudflare watches docs-site and serves the branch root with no build step.

Chosen Option: 1

Rationale: Option 1 — the ticket itself favours it as "less magical", it keeps mutation and deployment atomic under one concurrency group, and it avoids relying on Cloudflare's branch-watch timing which could race the git push.

Design Choice 2: How is the global `versions.json` catalog produced now that a build only knows one version?

Options Considered:

1. Keep emitVersionIndex() writing only the built version's entry and merge entries in the workflow.
2. Decouple catalog generation into a metadata-only builder that fetches the packument (no source trees) and writes the complete versions.json on every deploy.

Chosen Option: 2

Rationale: Option 2 — the release list is metadata, not source trees; a decoupled builder produces the authoritative catalog cheaply and idempotently regardless of which single target was built, satisfying "the full npm release list should be metadata, not a list of source trees that must all be generated."

Design Choice 3: How does a single-target build root its asset URLs under the correct path?

Options Considered:

1. Keep base / and continue prefix-rewriting inside one build.
2. Set VitePress base to the target's prefix (/next/, /vX.Y.Z/, or /) per single-target build so assets resolve correctly within the snapshot directory.

Chosen Option: 2

Rationale: Option 2 — setting base per build produces a self-contained, relocatable snapshot whose assets resolve under its own directory, which is exactly what rsync-into-a-subdirectory requires.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Teach the plugin to build one tree at a time

The whole treasure hinges on this: versionedDocs() must stop materialising the entire history and instead render exactly one source tree per invocation, while release discovery becomes cheap metadata used only to write the global catalogue. The all-versions path survives, but only as a bootstrap/repair tool, not the daily driver.

Task 1: Introduce a single-target selector into the plugin

Add an explicit build-target concept so one invocation renders one DocsVersion.

• Extend VersionedDocsOptions in packages/vitepress-versioned-docs/src/index.ts with an optional target descriptor (channel next/latest/archive plus an optional version/tag), keeping the existing all-versions behaviour when no target is supplied.
• Refactor resolveVersions() so that, when a target is present, it produces a single-element DocsVersion[]: next renders from options.repoRoot; latest and archive render from a tag tree obtained via the existing ensureTagTree() and materializePages(), calling generateApi() once for just that tree.
• Set each single-target version's prefix to '' for latest, next/ for next, <tag>/ for archive, so downstream rewrites/sidebar/head/html/import-map logic keeps working unchanged for the one version present.
• Preserve the existing multi-version loop behind the "no target" branch for bootstrap/repair use only.

Task 2: Thread `DOCS_CHANNEL`/`DOCS_VERSION` and VitePress `base` through the site config

Wire the environment-driven selection and correct asset rooting in the consumer.

• In site/.vitepress/config.ts, read DOCS_CHANNEL/DOCS_VERSION (using the existing envOf helper style) and pass the resulting target into versionedDocs().
• Compute VitePress base from the resolved target's prefix (/, /next/, or /vX.Y.Z/) so each single-target build's assets resolve within its own directory.
• Keep the existing DOCS_OFFLINE/PR-preview logic intact for local/PR builds (default such builds to the next target, no packument fetch), so CI PR checks and site:dev keep working exactly as before.
• Ensure devLabel, library.moduleUrl, and githubLinks({ ref }) continue to be derived per target so import maps and source links stay baked correctly into each snapshot.

Task 3: Decouple catalogue generation from rendering

Make versions.json a metadata product independent of any single build.

• Add a metadata-only catalogue builder (reusing fetchReleases()'s packument parsing without touching ensureTagTree/generateApi) that assembles the full next + latest + archive list and writes the existing schemaVersion-3 versions.json shape.
• Expose it both as a plugin export and via a thin script under scripts/ (e.g. site-versions-catalog) that the workflow can run to refresh the catalogue on every deploy, honouring DOCS_OFFLINE for previews.
• Move the fileGuardrail check out of the per-build emitVersionIndex() path (which now only ever sees one version) so guardrail enforcement can instead count the assembled .publish tree in the deployment workflow (Phase 3).

🤖 Prompt for AI agents

Implement single-target build support in the versioned-docs plugin so one
invocation renders exactly one `DocsVersion`, keeping all-versions rendering
only for bootstrap/repair.

- In `packages/vitepress-versioned-docs/src/index.ts`, extend
`VersionedDocsOptions` with an optional target descriptor (channel
`next`/`latest`/`archive` plus optional version/tag). When no target is
supplied, keep existing all-versions behaviour.
- Refactor `resolveVersions()` so a supplied target produces a single-element
`DocsVersion[]`: `next` renders from `options.repoRoot`; `latest`/`archive`
render from a tag tree via existing `ensureTagTree()` and `materializePages()`,
calling `generateApi()` once for just that tree.
- Set prefixes per target: `''` for `latest`, `next/` for `next`, `<tag>/` for
`archive`, so existing `rewrites`/`sidebar`/`head`/`html`/import-map logic keeps
working unchanged.
- Preserve the existing multi-version loop behind the "no target" branch,
reserved for bootstrap/repair.
- In `site/.vitepress/config.ts`, read `DOCS_CHANNEL`/`DOCS_VERSION` (following
the existing `envOf` helper style) and pass the resolved target into
`versionedDocs()`.
- Compute VitePress `base` from the resolved target's prefix (`/`, `/next/`, or
`/vX.Y.Z/`).
- Preserve existing `DOCS_OFFLINE`/PR-preview logic for local/PR builds,
defaulting such builds to the `next` target with no packument fetch, so
`site:dev` and CI PR checks continue working unchanged.
- Ensure `devLabel`, `library.moduleUrl`, and `githubLinks({ ref })` are derived
per target so import maps and source links stay correctly baked into each
snapshot.
- Add a metadata-only catalogue builder that reuses `fetchReleases()`'s
packument parsing (without touching `ensureTagTree`/`generateApi`) to assemble
the full `next + latest + archive` list and write the existing schemaVersion-3
`versions.json` shape.
- Expose the catalogue builder both as a plugin export and via a thin script
under `scripts/` (e.g. `site-versions-catalog`) that a workflow can invoke to
refresh the catalogue on every deploy, honouring `DOCS_OFFLINE` for previews.
- Move the `fileGuardrail` check out of the per-build `emitVersionIndex()` path
(since it now only ever sees one version) so guardrail enforcement instead
counts the assembled `.publish` tree during deployment (handled in a later
phase).

Phase 2: Make the version switcher read the live catalogue

Immutable snapshots must not be frozen in ignorance. The switcher learns about newer releases at runtime from the root catalogue, falling back to the baked-in list for offline/dev/PR builds.

Task 1: Fetch `/versions.json` at runtime in `VersionSwitcher`

Replace the build-time-only version list with a runtime catalogue plus fallback.

• Update site/.vitepress/theme/components/VersionSwitcher.vue to fetch the absolute-root /versions.json on mount, mapping its { label, tag, channel, base } entries into the switcher's entry shape.
• Fall back to theme.value.versions when the fetch fails or is unavailable (dev/offline/PR previews), so nothing regresses when no catalogue is served.
• Keep hrefFor producing plain root-relative /${prefix}${page} links (no withBase()), since every version shares one origin and cross-snapshot links must not be re-prefixed with the current snapshot's base.

Task 2: Confirm the remaining version-scoped UI stays baked

Verify no other component silently depends on a stale in-memory list.

• Confirm VersionedNav.vue and the build-time consumers (sidebar, rewrites, head, html, isIndexable, sitemap filter) remain driven by each snapshot's own baked DocsVersion, which is correct and immutable per snapshot — only the switcher's cross-version list needs the runtime catalogue.

🤖 Prompt for AI agents

Update the version switcher UI to fetch the live version catalogue at runtime
instead of relying solely on the build-time baked list.

- In `site/.vitepress/theme/components/VersionSwitcher.vue`, fetch the
absolute-root `/versions.json` on mount, mapping its `{ label, tag, channel,
base }` entries into the switcher's entry shape.
- Fall back to `theme.value.versions` when the fetch fails or is unavailable
(covers dev/offline/PR preview builds) so behaviour does not regress when no
catalogue is served.
- Ensure `hrefFor` continues to produce plain root-relative `/${prefix}${page}`
links without using `withBase()`, since every version shares one origin and
cross-snapshot links must not be re-prefixed with the current snapshot's base.
- Verify (no code change expected) that `VersionedNav.vue` and the build-time
consumers (`sidebar`, `rewrites`, `head`, `html`, `isIndexable`, sitemap filter)
remain driven by each snapshot's own baked `DocsVersion`, confirming only the
switcher's cross-version list needs the runtime catalogue.

Phase 3: Serialised incremental Cloudflare deployment

Here be the rigging: one workflow that checks out the persistent docs-site orphan branch, mutates only the target path, refreshes the catalogue, and deploys the prebuilt tree straight to Cloudflare — all under a single concurrency group so master and release voyages never overwrite each other's booty.

Task 1: Create the deployment workflow skeleton

Establish triggers, serialisation, and the persistent publish tree.

• Add .github/workflows/docs-deploy.yml triggered on push to master and on tags v*.*.*, plus workflow_dispatch, with concurrency: { group: docs-site, cancel-in-progress: false } and permissions: { contents: write }.
• Check out the repo, run .github/actions/setup-ts (bun+node+deno), then fetch/check out the docs-site orphan branch into a worktree at .publish (creating it empty if it does not yet exist).
• Read CLOUDFLARE_API_TOKEN/CF_ACCOUNT_ID secrets for the deploy step.

Task 2: Implement the master (`/next/`) path

One build, replace only /next/, preserve everything else.

• Build the checked-out tree with DOCS_CHANNEL=next (base /next/) via site:build.
• Replace only the target: rsync -a --delete site/.vitepress/dist/ .publish/next/.
• Regenerate .publish/versions.json via the catalogue script, count .publish files against the guardrail, then squash-commit and git push --force-with-lease the docs-site branch.

Task 3: Implement the release (`vX.Y.Z`) path

At most two builds: the immutable snapshot plus root/latest.

• Refuse to proceed if .publish/vX.Y.Z/ already exists unless an explicit repair input is set (immutability guard).
• Build with DOCS_CHANNEL=archive DOCS_VERSION=vX.Y.Z (base /vX.Y.Z/) and rsync into .publish/vX.Y.Z/ (no --delete needed for a fresh dir).
• Build the same tag with DOCS_CHANNEL=latest (base /) and replace root/latest with scoped deletion: rsync -a --delete --exclude '/next/' --exclude '/v*/' site/.vitepress/dist/ .publish/.
• Regenerate .publish/versions.json, enforce the guardrail, squash-commit, and git push --force-with-lease.

Task 4: Deploy the prebuilt tree and retire the old paths

Point Cloudflare at .publish and remove the superseded deploy paths.

• Add a Wrangler config for the publish tree (an assets-only Worker reusing the micro509 name and custom domain, [assets] directory pointing at .publish) and invoke wrangler deploy from the workflow after the push.
• Remove/retire the GitHub Pages deploy-site.yml deploy and the Cloudflare deploy-hook POST in publish.yml's deploy-docs job, since deployment is now atomic within docs-deploy.yml (non-goal: do not move to GitHub Pages — this consolidates onto Cloudflare).
• Keep test.yml's docs site:build CI check as-is (it already builds the next tree offline for PRs).

🤖 Prompt for AI agents

Build a single serialised GitHub Actions workflow that incrementally deploys
prebuilt docs snapshots to Cloudflare via a persistent `docs-site` orphan
branch, replacing the previous full-rebuild deploy flow.

- Add `.github/workflows/docs-deploy.yml` triggered on push to `master`, on tags
matching `v*.*.*`, and via `workflow_dispatch`, with `concurrency: { group:
docs-site, cancel-in-progress: false }` and `permissions: { contents: write }`.
- Check out the repo, run `.github/actions/setup-ts` (bun+node+deno), then
fetch/check out the `docs-site` orphan branch into a worktree at `.publish`
(create it empty if it does not yet exist).
- Read `CLOUDFLARE_API_TOKEN`/`CF_ACCOUNT_ID` secrets for the deploy step.
- For the master path: build with `DOCS_CHANNEL=next` (base `/next/`) via
`site:build`, then replace only the target with `rsync -a --delete
site/.vitepress/dist/ .publish/next/`. Regenerate `.publish/versions.json` via
the catalogue script, count `.publish` files against the guardrail, then
squash-commit and `git push --force-with-lease` to `docs-site`.
- For the release (tag `vX.Y.Z`) path: first refuse to proceed if
`.publish/vX.Y.Z/` already exists unless an explicit repair input is set
(immutability guard). Build with `DOCS_CHANNEL=archive DOCS_VERSION=vX.Y.Z`
(base `/vX.Y.Z/`) and rsync into `.publish/vX.Y.Z/` (no `--delete` needed for a
fresh directory). Then build the same tag with `DOCS_CHANNEL=latest` (base `/`)
and replace root/latest with scoped deletion: `rsync -a --delete --exclude
'/next/' --exclude '/v*/' site/.vitepress/dist/ .publish/`. Regenerate
`.publish/versions.json`, enforce the guardrail, squash-commit, and `git push
--force-with-lease`.
- Add a Wrangler config for the publish tree: an assets-only Worker reusing the
`micro509` name and custom domain, with `[assets] directory` pointing at
`.publish`, and invoke `wrangler deploy` from the workflow after the push.
- Retire the GitHub Pages deploy in `deploy-site.yml` and the Cloudflare
deploy-hook POST in `publish.yml`'s `deploy-docs` job, since deployment is now
atomic within `docs-deploy.yml`. Do not move deployment to GitHub Pages — this
consolidates everything onto Cloudflare.
- Leave `test.yml`'s docs `site:build` CI check unchanged, since it already
builds the `next` tree offline for PRs.

Phase 4: Bootstrap/repair tooling and governance

Finally, the paperwork a proper perfectionist cannot leave undone: a manual escape hatch to reseed or repair the branch, and the AGENTS.md/CHANGELOG updates the repo conventions demand.

Task 1: Add a manual bootstrap/repair workflow

Keep an explicit route to reseed the whole site or rebuild one version.

• Add a workflow_dispatch workflow (or inputs on docs-deploy.yml) that can (a) run the all-versions bootstrap build once to seed docs-site with the complete existing history, and (b) rebuild a single selected version with the immutability guard overridden (repair mode).
• Reuse the same docs-site concurrency group and .publish worktree flow so manual runs cannot race automated deployments.

Task 2: Update governance documentation and changelog

Document the new architecture where the conventions require it.

• Create packages/vitepress-versioned-docs/AGENTS.md (and optionally a README modelled on packages/deno-import-map/README.md) describing single-target build mode, the catalogue contract, and immutability guarantees.
• Update root AGENTS.md (add the packages/ workspace and the incremental deploy architecture), site/AGENTS.md (the new build/deploy/branch conventions, touching the existing import-map/publishing-strategy and branch-coupling notes), and .github/actions/AGENTS.md if any new composite action is introduced.
• Add an entry under the existing ## [Unreleased] section of CHANGELOG.md.

🤖 Prompt for AI agents

Add manual bootstrap/repair tooling and update project governance documentation
to reflect the new incremental deployment architecture.

- Add a `workflow_dispatch` workflow (or inputs on `docs-deploy.yml`) capable of
(a) running the all-versions bootstrap build once to seed `docs-site` with the
complete existing history, and (b) rebuilding a single selected version with the
immutability guard overridden (repair mode).
- Reuse the same `docs-site` concurrency group and `.publish` worktree flow so
manual runs cannot race automated deployments.
- Create `packages/vitepress-versioned-docs/AGENTS.md` (optionally with a README
modelled on `packages/deno-import-map/README.md`) describing single-target build
mode, the catalogue contract, and immutability guarantees.
- Update root `AGENTS.md` to add the `packages/` workspace and describe the
incremental deploy architecture.
- Update `site/AGENTS.md` with the new build/deploy/branch conventions, touching
the existing import-map/publishing-strategy and branch-coupling notes.
- Update `.github/actions/AGENTS.md` if any new composite action is introduced.
- Add an entry under the existing `## [Unreleased]` section of `CHANGELOG.md`.

Research

The versioned-docs machinery is a single-file plugin, packages/vitepress-versioned-docs/src/index.ts, consumed solely by site/.vitepress/config.ts. Today resolveVersions() fetches the npm packument, downloads/unpacks every release tag into a tag-tree cache, calls generateApi() and materializePages() for every release, and hands one enormous in-memory DocsVersion[] to a single vitepress build. That array feeds rewrites, sidebar, markdown link rewriting, per-version import maps, head/html noindex/canonical logic, isIndexable (sitemap), and emitVersionIndex() (which writes dist/versions.json, schemaVersion 3, and enforces the 19,500-file fileGuardrail). The releases.offline boolean is the only existing "build less" lever — an all-or-nothing switch that serves only the checked-out tree. The switcher components (VersionSwitcher.vue, VersionedNav.vue) read theme.versions baked in at build time, never fetching anything. Deployment currently goes to GitHub Pages (deploy-site.yml) with a secondary Cloudflare deploy-hook POST in publish.yml; the real Cloudflare config is site/.vitepress/wrangler.toml ([assets] directory = "dist/", custom domain micro509.kjanat.dev). There is no orphan-branch/rsync/worktree tooling, no DOCS_CHANNEL concept, no tests for the plugin, and no AGENTS.md/README inside the package.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement single-target build support in the versioned-docs plugin so one
invocation renders exactly one `DocsVersion`, keeping all-versions rendering
only for bootstrap/repair.

- In `packages/vitepress-versioned-docs/src/index.ts`, extend
`VersionedDocsOptions` with an optional target descriptor (channel
`next`/`latest`/`archive` plus optional version/tag). When no target is
supplied, keep existing all-versions behaviour.
- Refactor `resolveVersions()` so a supplied target produces a single-element
`DocsVersion[]`: `next` renders from `options.repoRoot`; `latest`/`archive`
render from a tag tree via existing `ensureTagTree()` and `materializePages()`,
calling `generateApi()` once for just that tree.
- Set prefixes per target: `''` for `latest`, `next/` for `next`, `<tag>/` for
`archive`, so existing `rewrites`/`sidebar`/`head`/`html`/import-map logic keeps
working unchanged.
- Preserve the existing multi-version loop behind the "no target" branch,
reserved for bootstrap/repair.
- In `site/.vitepress/config.ts`, read `DOCS_CHANNEL`/`DOCS_VERSION` (following
the existing `envOf` helper style) and pass the resolved target into
`versionedDocs()`.
- Compute VitePress `base` from the resolved target's prefix (`/`, `/next/`, or
`/vX.Y.Z/`).
- Preserve existing `DOCS_OFFLINE`/PR-preview logic for local/PR builds,
defaulting such builds to the `next` target with no packument fetch, so
`site:dev` and CI PR checks continue working unchanged.
- Ensure `devLabel`, `library.moduleUrl`, and `githubLinks({ ref })` are derived
per target so import maps and source links stay correctly baked into each
snapshot.
- Add a metadata-only catalogue builder that reuses `fetchReleases()`'s
packument parsing (without touching `ensureTagTree`/`generateApi`) to assemble
the full `next + latest + archive` list and write the existing schemaVersion-3
`versions.json` shape.
- Expose the catalogue builder both as a plugin export and via a thin script
under `scripts/` (e.g. `site-versions-catalog`) that a workflow can invoke to
refresh the catalogue on every deploy, honouring `DOCS_OFFLINE` for previews.
- Move the `fileGuardrail` check out of the per-build `emitVersionIndex()` path
(since it now only ever sees one version) so guardrail enforcement instead
counts the assembled `.publish` tree during deployment (handled in a later
phase).
===============================================================================

Task: 2

Update the version switcher UI to fetch the live version catalogue at runtime
instead of relying solely on the build-time baked list.

- In `site/.vitepress/theme/components/VersionSwitcher.vue`, fetch the
absolute-root `/versions.json` on mount, mapping its `{ label, tag, channel,
base }` entries into the switcher's entry shape.
- Fall back to `theme.value.versions` when the fetch fails or is unavailable
(covers dev/offline/PR preview builds) so behaviour does not regress when no
catalogue is served.
- Ensure `hrefFor` continues to produce plain root-relative `/${prefix}${page}`
links without using `withBase()`, since every version shares one origin and
cross-snapshot links must not be re-prefixed with the current snapshot's base.
- Verify (no code change expected) that `VersionedNav.vue` and the build-time
consumers (`sidebar`, `rewrites`, `head`, `html`, `isIndexable`, sitemap filter)
remain driven by each snapshot's own baked `DocsVersion`, confirming only the
switcher's cross-version list needs the runtime catalogue.
===============================================================================

Task: 3

Build a single serialised GitHub Actions workflow that incrementally deploys
prebuilt docs snapshots to Cloudflare via a persistent `docs-site` orphan
branch, replacing the previous full-rebuild deploy flow.

- Add `.github/workflows/docs-deploy.yml` triggered on push to `master`, on tags
matching `v*.*.*`, and via `workflow_dispatch`, with `concurrency: { group:
docs-site, cancel-in-progress: false }` and `permissions: { contents: write }`.
- Check out the repo, run `.github/actions/setup-ts` (bun+node+deno), then
fetch/check out the `docs-site` orphan branch into a worktree at `.publish`
(create it empty if it does not yet exist).
- Read `CLOUDFLARE_API_TOKEN`/`CF_ACCOUNT_ID` secrets for the deploy step.
- For the master path: build with `DOCS_CHANNEL=next` (base `/next/`) via
`site:build`, then replace only the target with `rsync -a --delete
site/.vitepress/dist/ .publish/next/`. Regenerate `.publish/versions.json` via
the catalogue script, count `.publish` files against the guardrail, then
squash-commit and `git push --force-with-lease` to `docs-site`.
- For the release (tag `vX.Y.Z`) path: first refuse to proceed if
`.publish/vX.Y.Z/` already exists unless an explicit repair input is set
(immutability guard). Build with `DOCS_CHANNEL=archive DOCS_VERSION=vX.Y.Z`
(base `/vX.Y.Z/`) and rsync into `.publish/vX.Y.Z/` (no `--delete` needed for a
fresh directory). Then build the same tag with `DOCS_CHANNEL=latest` (base `/`)
and replace root/latest with scoped deletion: `rsync -a --delete --exclude
'/next/' --exclude '/v*/' site/.vitepress/dist/ .publish/`. Regenerate
`.publish/versions.json`, enforce the guardrail, squash-commit, and `git push
--force-with-lease`.
- Add a Wrangler config for the publish tree: an assets-only Worker reusing the
`micro509` name and custom domain, with `[assets] directory` pointing at
`.publish`, and invoke `wrangler deploy` from the workflow after the push.
- Retire the GitHub Pages deploy in `deploy-site.yml` and the Cloudflare
deploy-hook POST in `publish.yml`'s `deploy-docs` job, since deployment is now
atomic within `docs-deploy.yml`. Do not move deployment to GitHub Pages — this
consolidates everything onto Cloudflare.
- Leave `test.yml`'s docs `site:build` CI check unchanged, since it already
builds the `next` tree offline for PRs.
===============================================================================

Task: 4

Add manual bootstrap/repair tooling and update project governance documentation
to reflect the new incremental deployment architecture.

- Add a `workflow_dispatch` workflow (or inputs on `docs-deploy.yml`) capable of
(a) running the all-versions bootstrap build once to seed `docs-site` with the
complete existing history, and (b) rebuilding a single selected version with the
immutability guard overridden (repair mode).
- Reuse the same `docs-site` concurrency group and `.publish` worktree flow so
manual runs cannot race automated deployments.
- Create `packages/vitepress-versioned-docs/AGENTS.md` (optionally with a README
modelled on `packages/deno-import-map/README.md`) describing single-target build
mode, the catalogue contract, and immutability guarantees.
- Update root `AGENTS.md` to add the `packages/` workspace and describe the
incremental deploy architecture.
- Update `site/AGENTS.md` with the new build/deploy/branch conventions, touching
the existing import-map/publishing-strategy and branch-coupling notes.
- Update `.github/actions/AGENTS.md` if any new composite action is introduced.
- Add an entry under the existing `## [Unreleased]` section of `CHANGELOG.md`.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!