build(versioning): wire Docusaurus versioning, short of the first snapshot

AGENTS.md

@@ -106,22 +106,36 @@ same change: that note's table, and the versions in the install lines of `quicks
 version is where breaking changes go. When the SDK tags `vX.Y.0`:
 
 1. `npm run docusaurus docs:version X.Y`. It copies `docs/` into `versioned_docs/version-X.Y/`
-   and writes `versioned_sidebars/` and `versions.json`.
-2. In the docs preset in `docusaurus.config.js`, set `lastVersion: 'X.Y'` so readers land on the
-   release, and label `versions.current` as `Next (unreleased)`. With `routeBasePath: '/'` the
-   release is served at `/` and `master` at `/next/`.
+   and writes `versioned_sidebars/` and `versions.json`. Cut it from an up-to-date `master`, as
+   the last step before the pull request: every merge into `docs/` makes an uncut snapshot stale,
+   and there is no refresh command, only delete and cut again.
+2. In the docs preset in `docusaurus.config.js`, add `versions: { current: { label: 'Next
+   (unreleased)' } }`. Do **not** set `lastVersion`: it defaults to the newest name in
+   `versions.json`, so each later cut moves readers on its own. With `routeBasePath: '/'` the
+   release is then served at `/` and `master` at `/next/`, both by default.
 3. Replace the hardcoded `v1.0` navbar badge with `{ type: 'docsVersionDropdown', position: 'right' }`.
+   Not before the first snapshot: with none, the dropdown renders as a lone link labelled after
+   the development version, which reads as a release.
 4. Rewrite the quick start note in `docs/`: from the first snapshot on, `master` is the "Next"
-   version and the note says so.
+   version and the note says so. Give the snapshot's own copy of the note the versions that
+   shipped, and the same for the install lines it froze.
 5. Build, and check that search and the `/next/` pages both work before `sync-docs` publishes it.
+   Each version gets its own index (`build/search-index.json`, `build/next/search-index.json`);
+   search from a `/next/` page and confirm the hit stays under `/next/`.
+
+Snapshots are cut for released versions only. A version the SDK has not tagged never gets one,
+so the version a reader picks in the navbar is always one they can install.
 
 A snapshot is changed only where it was wrong for its own release, a patch release that changes
 behaviour included. A new feature goes into `docs/`, never back into a snapshot.
 
 **Where this stands.** No snapshot exists yet, so the published site describes `main`, and a
-reader on 0.2.0 can meet calls their version lacks; the quick start note warns them. Nothing
-checks these rules automatically yet. The doc tests being added under `doctests/` are meant to,
-by building against pinned SDK and platform commits.
+reader on 0.2.0 can meet calls their version lacks; the quick start note warns them. The steps
+above are all that is left to run, and `editCurrentVersion` is already set so a snapshot's "Edit
+this page" will point at `docs/`. The first cut waits on the first tagged release; the SDK has
+tagged only `v0.2.0`, and bumped `main` past it without releasing, so no number in between gets a
+snapshot. Nothing checks these rules automatically yet. The doc tests being added under
+`doctests/` are meant to, by building against pinned SDK and platform commits.
 
 ## Every example has to be runnable
 

docusaurus.config.js

@@ -28,10 +28,21 @@ const config = {
         docs: {
           sidebarPath: './sidebars.js',
           routeBasePath: '/',          // docs at site root, GitBook-style
+          // No `versions` block and no snapshot yet: `docs/` is the only version
+          // and is served at '/'. AGENTS.md has the three lines to add when the
+          // first release is tagged. Leave `lastVersion` out then too — it
+          // defaults to the newest name in versions.json, so cutting a snapshot
+          // moves readers onto it with nothing here to keep in step.
+
           // Adds "Edit this page" to every doc. Docusaurus appends the file's
           // path relative to this site directory. Note the branch here is
           // master, unlike datahub-docs which is main.
           editUrl: 'https://github.com/IntelliStream-DataHub/datahub-sdk-docs/edit/master/',
+          // Send every "Edit this page" to docs/, including from a snapshot once
+          // one exists: a snapshot takes corrections for its own release, but a
+          // new feature belongs in docs/, and the stock link would invite the
+          // wrong edit. No effect until the first snapshot.
+          editCurrentVersion: true,
         },
         blog: false,                    // SDK docs site — no blog
         theme: { customCss: './src/css/custom.css' },
@@ -77,8 +88,10 @@ const config = {
           // which pushState's the URL and then renders this site's own 404 —
           // the href looks right in the HTML but the click never leaves the SPA.
           { type: 'html', position: 'right', value: '<a class="navbar__item navbar__link" href="/data-platform-documentation/">Platform documentation</a>' },
-          // Simple version indicator. When the docs start tracking multiple releases,
-          // replace this with a docsVersionDropdown via `npm run docusaurus docs:version`.
+          // The site's own version, not an SDK version. Swap it for
+          // { type: 'docsVersionDropdown', position: 'right' } once a snapshot
+          // exists — with none, the dropdown renders as a lone link labelled
+          // after the development version, which reads as a release.
           { type: 'html', position: 'right', value: '<span class="badge badge--secondary navbar__version-badge">v1.0</span>' },
           // This site's own repo, so "GitHub" is unambiguous. The old link went
           // to the SDK code on Gitea; if a code link is wanted too it needs its