Repository navigation
docs: clear navigation audit findings and audit redirect coverage #394
Description
Phase 0 of #393. No structural change, no page moves. Merge this whatever we decide about the rest.
What's wrong
python3 scripts/audit_navigation.py reports 30 advisory shape findings: 8 single-child groups, 10 Title Case labels, 3 groups nested deeper than the 2-container limit. Separately, one internal link is broken and the redirect coverage for externally-referenced URLs has never been checked.
Why it matters
Two of these findings are load-bearing for the restructure. Phase 1 renames tabs and groups, and a rename lands on top of existing Title Case inconsistency, so the casing question gets decided once here instead of per-group later. The single-child groups are the shape Phase 1 dissolves anyway.
The redirect audit matters on its own: ~20 docs URLs are compiled into released CLI binaries and can never be updated. If any of them 404 today, customers on older CLIs are already hitting dead ends and we do not know.
Tasks
- Sentence-case the 10 Title Case labels. Decide the
&convention once (Users & rolesis the existing precedent). - Dissolve the 8 single-child groups:
Managing Custom Attestation Types,FAQ,Evaluation,Multi-flow workflows,Controls,Repositories,Reference > GitHub Action Reference > GitHub Action,Reference > Terraform Reference > Provider,List Resources,Helm Charts. - Flatten the 3 over-deep groups:
Tutorials > Security > Detecting Terraform drift,Implementation Guide > Phase 2 > Plan Organizational Structure > Naming Conventions,Reference > Helm Reference > Helm Charts > Kubernetes Reporter. - Fix the broken internal link to
/getting_started/service-accountsintutorials/working_with_controls.mdx. It has a redirect to/getting_started/authenticating_to_kosli, butmint broken-linksdoes not follow redirects, so the link must be rewritten to the real target. - Audit that every URL embedded in a released CLI binary resolves. Generate the list with:
grep -rhoE 'docs\.kosli\.com/[a-zA-Z0-9_/#.-]+' ../cli --include="*.go" --include="*.gotmpl" | sort -u - Same for
kosli-dev/server(--include="*.py"), ~20 more URLs including the anchor/getting_started/environments/#snapshoting-an-environment. - Add a
config/redirects.jsonentry for anything in either list that does not resolve.
URL impact
- No page files move — nav-only change, no redirects needed for the label work
- Page files move
Redirects may be added for already-broken external URLs, but no existing URL changes.
Out of scope
- Do not restructure
Reference > CLI Reference. Single-child groups likekosli allowreflect the CLI's real command tree and are generated byscripts/update-cli-nav.py. - Do not rename the
Referencetab or itsCLI Referencemenu item.update-cli-nav.py:154-158hard-codes both and exits 1 without them. - The
Helm ChartsandKubernetes Reportergroups can be flattened in navigation, but the pages themselves are generated from chart templates inkosli-dev/cli.
Verification
-
python3 scripts/audit_navigation.py— shape findings reduced, integrity clean -
python3 scripts/audit_navigation.py --check— exit 0 -
python3 -m pytest tests/— navigation integrity test passes -
mint broken-links— zero broken links, including theservice-accountsone - Every URL in the CLI and server lists resolves (spot-check a sample in the preview deploy)
Activity
claude commentedon Oct 1, 2026
Monthly doc-structure audit, 2026-10-01 — the shape findings have drifted since this issue was written, so the checklist above is now short of the real list.
python3 scripts/audit_navigation.py --jsontoday reports 33 findings, not 30: 16 single-child groups, 13 Title Case labels, 3 deep-nesting, 1 inconsistent-icons.Integrity is clean —
orphansanddanglingare both empty — so nothing here blocks a build.Single-child groups not in the checklist above (6 new):
Documentation > Administration > Managing EnvironmentsImplementation Guide > Phase 1: Initial DiscoveryImplementation Guide > Phase 2: Configure KosliImplementation Guide > Phase 2: Configure Kosli > Plan Organizational StructureReference > Template Reference > TemplatesChangelog > ChangelogThe checklist also lists
Reference > GitHub Action Reference > GitHub ActionandReference > Terraform Reference > Providerunder a single bullet withList ResourcesandHelm Charts, which reads as 8 but is 10 paths.Title Case labels not in the checklist (the current full set of 13):
Managing Environments,Managing Custom Attestation Types,Cloud Capture,Kosli Learning Labs,Phase 1: Initial Discovery,Roles & Responsibilities,Phase 2: Configure Kosli,Plan Organizational Structure,Naming Conventions,Data Sources,List Resources,Helm Charts,Kubernetes Reporter.One finding kind this issue does not cover at all:
Four of the five top-level tabs have no icon and
Changelogdoes. Worth deciding with the rest of the label work here, since #395 renames every tab anyway — settling it once in Phase 0 avoids relitigating it per tab.The broken
/getting_started/service-accountslink intutorials/working_with_controls.mdxis still present and still the only link target in the repo pointing at a page that does not exist.No new issue filed — this is all inside Phase 0's scope.