## 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
```text
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