Docs version skew: accept a ?v= parameter, and decide whether to pin to the latest tag instead of main

[eaitbrahim]

Raised by the keel web UI rewrite — spec at docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md in CodeGateSoftware/keel, tracked there as CodeGateSoftware/keel#539.

The problem

keel's new browser UI stops carrying documentation prose and deep-links here instead — https://keeltrading.com/en/docs/{slug}/#{anchor}. That fixes a real bug: the wheel ships no docs/, so the in-app glossary is empty in every installed deployment.

But this site pins main, while an operator runs a tagged release. engine-docs.manifest.json:

{ "repo": "CodeGateSoftware/keel", "ref": "main", ... }

So a user on v0.11.2 can follow a link from their app and read documentation describing behaviour their build does not have — silently, with nothing on the page saying so.

What keel will send

Outbound links will carry the running version as a query parameter:

https://keeltrading.com/en/docs/glossary/?v=0.11.2#qabd

keel exposes this from GET /api/config on the local server. It costs this site nothing to ignore, so nothing breaks if this issue is declined — the links simply stay silent about skew.

Two options

1. A banner (recommended, small). src/pages/{lang}/docs/[slug].astro reads ?v=, compares it against the ref the page was built from, and renders a notice when they differ — something like "You're running keel 0.11.2; these docs describe main."

Needs the build to record which ref/commit it fetched. scripts/fetch-engine-docs.mjs already resolves the manifest's ref, so writing it into data/docs-meta.json alongside what it writes today is most of the work.

2. Pin the manifest to the latest tag rather than main. Removes the skew for released users instead of announcing it, and matches what someone who installed keel actually has. The cost is that documentation for unreleased work stops being visible on the site — which may be the wrong trade while the project is moving fast.

These compose: pinning narrows the gap, the banner covers what remains.

Explicitly rejected

Per-version documentation trees (/en/docs/v0.11.0/glossary). It would 404 today, and building them means a retention policy multiplied across en/fr/ar and the sitemap — a lot of surface for a problem a query parameter and one line of copy address.

Acceptance

• A decision recorded on option 1, option 2, both, or neither.
• If the banner ships: ?v= is read, compared against the built ref, and a notice renders only on mismatch — in all three locales.
• ?v= never breaks a page or affects the anchor when absent or unrecognised.
• If pinning ships: engine-docs.manifest.json names a tag, and the fetch script still fails loudly when a pinned document disappears.

Note

No GitHub Project exists matching this repository, so this issue is assigned but not added to one.