docs: clear navigation audit findings and audit redirect coverage

[dangrondahl]

Phase 0 of #393. Closes #394.

Navigation labels, shape, and redirect coverage. No page files move, no URLs change. Bottom layer of a two-layer stack; Phase 1 (#395) builds the seven-tab rewrite on top of this.

URL impact

• No page files move — nav-label and redirect-only change
• Page files move

Redirects are added for URLs that already 404 in production. No existing URL changes.

What this does

1. Fixes the one broken internal link

tutorials/working_with_controls.mdx linked /getting_started/service-accounts. A redirect covered it, but mint broken-links does not follow redirects, so the link itself had to change — now /getting_started/authenticating_to_kosli, which matches the "Get a Kosli API token" link text. mint broken-links reports zero broken links.

2. Audits every docs URL referenced from outside this repo

Grepped kosli-dev/cli and kosli-dev/server across all file types, not just *.go and *.py as #394 suggested — real references also live in *.html, *.tsx, *.yml and *.gotmpl. That found 45 unique URLs, checked against config/navigation.json, config/redirects.json and production over HTTP.

Every URL compiled into a released CLI binary resolves. That was the live risk in #394 and it isn't one. Six 404 in production; redirects added for the three with a target here:

Broken URL	Redirects to	Referenced from
/kosli_overview/what_is_audit_trail	/understand_kosli/what_is_kosli	archived server/docs/old/*.txt
/implementation_guide/phase_2/sso_configuration (+ entra_id_setup, okta_setup)	/administration/authentication/single_sign_on	server/docs/sso_configuration.md
/kosli-logo-dark-main.svg	/logo/kosli-logo-dark-main.svg	server/src/app/routes_swagger.py:19

The other three need upstream fixes and are filed as kosli-dev/server#6837 — two doubled-slash URLs the SSO runbooks paste to customers, and the broken API-reference logo. /tutorials/snyk is a test fixture in cli/internal/docgen/mintlify_test.go that never existed here, so deliberately no redirect.

3. Clears the navigation audit

scripts/audit_navigation.py: 32 shape findings → 3. Integrity clean, page count unchanged at 207.

Dissolved 14 groups that wrapped a single entry — more than the 8 #394 listed, since the audit reports more than the issue captured. All 3 over-deep groups are gone, two as a side effect of dissolving their parents.

Two of those groups, Managing Environments and Managing Custom Attestation Types, wrapped a single page whose title was the group label verbatim. Dissolving them promotes those titles into the sidebar, so their page titles are sentence-cased here too, plus managing_tags.md alongside them. Heading slugs are lowercased, so no anchors move.

Remaining Title Case nav labels are sentence-cased per CLAUDE.md, keeping the existing & convention from Users & roles.

Four findings left deliberately

• Implementation Guide > Phase 2: configure Kosli wraps one group. Both labels carry meaning, and dissolving the inner one would leave a bare "Overview" that is not a Phase 2 overview.
• Reference > Terraform Reference > Provider is kept, not dissolved. Provider / Resources / Data sources / List resources is the provider's own taxonomy, and dissolving it would promote an agent-synced Title Case title, Kosli Terraform Provider, into the sidebar — which the next upstream sync would undo if corrected here.
• Reference > Terraform Reference > List resources, for the same taxonomy reason, and it will gain siblings.
• Inconsistent tab icons are left to docs: rewrite navigation into seven job-based tabs #395, which decides the final tab set.

So the audit goes 32 → 4, and the Provider entry is an accepted exception rather than a fix — it was converted back deliberately after review, to avoid a schema-shaped fix that traded one problem for another.

Reference > CLI Reference is untouched. update_navigation in scripts/update-cli-nav.py:144-166 only replaces item['groups'] for that one menu item, so everything else here survives the next CLI release.

Follow-up worth adding to #398

The Title Case problem is roughly twice what #394 implies. audit_navigation.py inspects only navigation labels, but 21 hand-authored pages carry Title Case front-matter titles — Environment Policies, Platform Engineers, Lab 3: Build Controls, Rego Policy — and each renders as a sidebar label. Not swept here: some are product names (Magic Link, Kosli Actions) and the lab titles are a judgment call. The enforcement fix belongs in #398: check page titles, not just nav labels.

Verification

• python3 scripts/audit_navigation.py --check — exit 0
• python3 -m pytest tests/ — 44 passed
• mint broken-links — zero broken links
• Every URL referenced from kosli-dev/cli and kosli-dev/server either resolves or is covered by a new redirect, except the three filed upstream
• Page count unchanged at 207

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Sep 10, 2026, 2:55 PM

[claude]

Claude encountered an error after 5m 45s —— View job

---

Doc review

All three findings from the previous pass are fixed at d73b9d5 — the four bare-string-in-groups cases now use pages, Provider is restored for Terraform Reference, faq/faq.md carries icon: circle-question, and the Phase 1 hub is retitled Roles and responsibilities. Four new findings, none blocking.

---

getting_started/enforce_policies.md:155, tutorials/rotating_api_keys.mdx:107

Improvement — five in-repo links still resolve only through a redirect, the same pattern this PR fixed for /getting_started/service-accounts.

/helm/k8s_reporter is not a page — helm/ contains only k8s_reporter/*.mdx, and the URL works solely because of config/redirects.json:3. By the reasoning in the PR body (a redirect covered the old link too, but the link itself still had to change), these are the same defect:

File	Line
getting_started/enforce_policies.md	155
tutorials/rotating_api_keys.mdx	107
changelog/index.mdx	1210 (×2), 1357, 1404

The two live doc pages are worth changing to /helm/k8s_reporter/overview. The changelog entries are historical prose and reasonable to leave.

This also reconciles a loose end in the PR body: if mint broken-links genuinely does not follow redirects, these five should have been reported alongside the service-accounts link. Since the run came back clean, it evidently does consult config/redirects.json — which means the link check will never surface this class, and only a grep will.

Fix this →

implementation_guide/phase_1/roles_and_responsibilities/overview.md:26

Improvement — in the Stakeholders list, Sponsors is the only one of the four not linked to its page. Dissolving Roles & Responsibilities promotes all five pages to siblings under Phase 1: initial discovery, which makes this page the hub for the other four, so the one dead entry is more visible than before. The target is known-good — administration/managing_users/mapping_users_to_roles.md:33 already links /implementation_guide/phase_1/roles_and_responsibilities/sponsors.

Fix this →

implementation_guide/phase_1/roles_and_responsibilities/overview.md:13,28,69

Suggestion — the same page keeps three Title Case headings (Phases of Implementation, RACI Matrix, Connecting Responsibilities to Permissions) against CLAUDE.md's sentence-case rule, now sitting under a title this PR sentence-cased. Slugs are unaffected by the fix — ## RACI matrix still slugs to raci-matrix — so no anchors move. The other pages this PR retitled (managing_tags.md, both administration/managing_*/overview.md) are already sentence-cased throughout, so this is the only page where the title and its own headings now disagree.

---

Upstream — does not block this merge

• helm/k8s_reporter/overview.mdx:2 is titled Kubernetes Reporter Helm Chart, and now sits directly under the sentence-cased group label Kubernetes reporter (config/navigation.json:472), so the two render adjacent in the sidebar with different conventions. The page is generated by helm-docs, so a fix here is reverted on the next release — it belongs in kosli-dev/cli → charts/k8s-reporter/mintlify/overview.md.gotmpl. Its seven siblings are already sentence-cased.

Notes

• Restoring the Provider group in 268720f reintroduces a single-child group, so audit_navigation.py shape findings should now read 4, not the 3 the PR body and its "Three findings left deliberately" section claim. Worth correcting before docs: rewrite navigation into seven job-based tabs #395 is stacked on this, since that PR inherits the baseline.
• The PR body's durability claim holds: update_navigation (scripts/update-cli-nav.py:144-166) matches item['item'] == 'CLI Reference' and only reassigns that item's groups, and CLI Reference is still keyed groups at head — the four groups→pages conversions are outside its reach.
• I could not run audit_navigation.py, pytest tests/, mint broken-links, gh pr checks, or fetch the Mintlify preview in this environment (Bash and WebFetch approvals were declined), so all counts above come from reading the tree, and the preview-sidebar confirmation the previous pass asked for is still only the author's. If you want those run here, the review job needs --allowedTools widened for python3, gh, and WebFetch.

2 Improvements, 1 Suggestion, 1 upstream note. Advisory — nothing here blocks the merge.
· branch docs/nav-audit-hygiene

[dangrondahl]

Doc review findings addressed in 268720f.

1. Bare page strings inside groups arrays — confirmed and fixed. All four were real. Documentation, GitHub Action Reference and Template Reference now use pages, matching the shape the Changelog tab already got right.

The review's point about why nothing caught it is the useful part: audit_navigation.py walks groups and pages identically (scripts/audit_navigation.py:87-96), so all four pages still counted toward the 207 total and --check stayed green — and mint broken-links and the Mintlify preview build both passed too. Worth a test in #398: assert no groups array contains a string.

Terraform Reference took the other fix instead — its Provider group is restored rather than converted. Provider / Resources / Data sources / List resources is the provider's own taxonomy, the same reason List resources is kept, and it avoids the drift problem the review flagged: terraform-reference/ is agent-synced, so sentence-casing Kosli Terraform Provider here would be undone by the next sync.

2. Promoted Title Case titles — fixed for the one that needed it. template-reference/flow_template is now Flow template. terraform-reference/index is handled by keeping its group, per above. github-action-reference/setup_cli_action needs no change — its title, GitHub Action, is the label its group already used.

3. FAQ icon — fixed. icon: circle-question added to faq/faq.md front matter.

Re-verified: audit_navigation.py --check exit 0, pytest tests/ 44 passed, mint broken-links clean, 207 pages.

One note on scope: finding 2 does not apply to #401 stacked on top, which dissolves the Documentation tab entirely and puts faq/faq under Discover Kosli ▸ Help and troubleshooting.

[claude]

Improvement — dissolving Roles & Responsibilities leaves a page titled just "Overview" sitting directly under the phase.

The sidebar under Phase 1: initial discovery now reads: Overview / Platform Engineers / Application Developers / Security and Compliance / Sponsors. "Overview" now looks like an overview of the whole phase, but implementation_guide/phase_1/roles_and_responsibilities/overview.md is specifically the roles overview — RACI matrix, role-by-role expectations — and is linked elsewhere as exactly that (administration/managing_users/mapping_users_to_roles.md:29: "Implementation Guide: Roles and Responsibilities").

This is also the opposite call from Phase 2 in the same commit, where the middle wrapper (Plan Organizational Structure) was dissolved and the meaningful inner label (Naming conventions) kept.

Cheapest fix that keeps the phase symmetry: retitle the page rather than restore the group —

title: Roles and responsibilities

Its description already says "Define roles and responsibilities for Kosli implementation", and the heading slugs on the page don't change, so no anchors move.

Fix this →