docs: align the repo file structure with the navigation

[dangrondahl]

Phase 3 of #393. The expensive one. Worth doing, and worth doing last.

What's wrong

After Phase 1 the sidebar and the repo describe the same site with two different shapes. A writer opening the repo sees 17 top-level directories whose names only partly match the tabs, and tutorials/ still exists as a directory after it has stopped existing as a tab.

Why it matters

Every new contributor meets two mental models of one site, which is the writer-side problem from #393 in a different costume. Phase 1 fixes what readers see; this fixes what writers see.

It also gets more expensive the longer the two structures stay out of step, because every page added in between is filed under the old shape.

Approach

One directory per PR, each carrying its own redirects and internal-link sweep, so nothing depends on the phase finishing. If it stalls halfway, the half that landed is still coherent.

Two things make this real work rather than a rename:

• 643 root-relative internal links exist in the repo, and roughly 420 point at directories that would move. mint broken-links does not follow redirects, so every one needs rewriting even though the redirect alone would have carried the reader.
• The old paths never fully retire. Released CLI binaries print URLs we cannot recall, so those redirects stay permanently. This buys a clean tree going forward, not a clean slate.

How far it can reach

Directory	Renamable?	What it takes
The 10 hand-authored dirs	Yes	Redirects + link sweep, in this repo
client_reference/	Yes	A flag in update-cli-docs.yml (--dir, --docs-dir) plus two hard-coded prefixes at scripts/update-cli-nav.py:110 and :124
helm/, terraform-reference/, github-action-reference/	Not alone	Paths are baked into upstream templates in kosli-dev/cli; needs a coordinated change there, or they stay

So the end state is mostly aligned, not perfectly. Accept that rather than blocking on it.

Tasks

• Agree the target directory names against the Phase 1 tabs before moving anything.
• Per directory, in its own PR: move files, add a config/redirects.json entry per page, rewrite every internal link pointing at the old path, update config/navigation.json.
• Decide whether client_reference/ is in scope. If yes, it is a separate PR touching the workflow and update-cli-nav.py.
• Decide whether to open an upstream issue in kosli-dev/cli for helm/ and terraform-reference/, or leave them.

URL impact

• No page files move
• Page files move — redirects required for every page, listed old → new per PR

Also check anchors before renaming any heading. Some are referenced from outside this repo: the CLI prints faq/faq#boolean-flags, and kosli-dev/server references /getting_started/environments/#snapshoting-an-environment.

Out of scope

• Do not rename the Reference tab or the CLI Reference menu item (update-cli-nav.py:154-158).
• Do not touch generated page content, only paths, and only where the generator can be pointed at the new path in the same PR.

Verification (per PR, not just at the end)

• python3 -m pytest tests/ — navigation integrity
• mint broken-links — zero broken links, including links that a redirect would have covered
• Every old URL resolves via config/redirects.json
• The URLs embedded in released CLI binaries still resolve
• python3 scripts/update-cli-nav.py … exits 0 if client_reference/ moved