docs agent failed: could not map git tags to documentation versions

TL;DR

Normalize the tag scheme to semver or build an explicit map from tags to doc versions. Teach the agent to skip non-release tags (nightlies, RCs per policy) and fail loudly on unparseable tags instead of guessing.

The exact error

docs agent could not map git tags to doc versions

Steps

1. Inventory the tags List all git tags and sort them into release tags, pre-release tags, and noise. Success check: You know the full tag landscape.

2. Define the mapping rule Decide the rule: semver tags map directly, prefixed tags strip the prefix, non-release tags are ignored. Write it down as the versioning contract. Success check: The mapping rule is explicit and documented.

3. Implement tag parsing Give the agent a parser implementing the rule; unparseable tags raise an error instead of being guessed. Success check: Every release tag maps to exactly one doc version.

4. Verify versioned output Run the agent's versioned docs build and confirm each version's docs match the tagged code. Success check: Versioned docs exist for every release tag and match.

When to use

• Use when versioned docs do not line up with releases.
• Use when an agent builds versioned documentation from git tags.

When not to use

• Not for missing version switcher UI (frontend problem).
• Not for docs that should not be versioned (unversioned latest-only docs).

Why it happens

Agents guess version mappings from tag strings, and repos accumulate tag schemes over time (v1.2.3, release-1.2.3, 1.2.3-rc1). Each scheme needs its own rule, and guessing across schemes produces wrong version assignments silently.

Edge cases

The explicit contract also documents which tags are ignored, which stops future confusion about nightlies. Docusaurus and mkdocs versioning plugins each expect a specific tag shape; align the contract with the plugin.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_G-vc3dIlf7pMk-G2v3YtIQ