docs: rewrite navigation into seven job-based tabs

[dangrondahl]

Phase 1 of #393. One edit to config/navigation.json. No file moves, no redirects, no URL changes. Revertible in a single commit.

Interactive preview of the target structure: https://claude.ai/code/artifact/94c14e95-8be9-4a3a-be46-bb1b0f979f9d

Why it matters

This is the phase that answers "where does my page go?", and it carries essentially all of the value in the parent issue at essentially no risk. See #393 for the writer and reader costs it removes.

Current structure

Documentation   (61 pages, 8 groups, all four Diátaxis types)
Labs            (6)
Implementation Guide (8)
Reference       (129)
Changelog       (1)

Proposed structure

Tab order is fixed. Each tab carries a one-sentence membership test; if a page fails every test, the structure is wrong, not the page.

Discover Kosli — the reader has not started yet: orientation, first run, learning, getting unstuck

Understand Kosli          what_is_kosli, how_kosli_works, glossary
Get started               install, authenticating_to_kosli, try_kosli_locally
Core concepts             flows, trails, artifacts, attestations, environments, policies
Learning labs             labs/index, lab-01 … lab-05
Help and troubleshooting  faq/faq, all 7 troubleshooting/*, ai_docs_access

Platform administration — the reader is configuring Kosli itself for an organization

Your account              user/default_organization, user/personal_api_keys
Users and access          roles_in_kosli, mapping_users_to_roles, authentication/*, rotating_api_keys
Organization structure    managing_tags, managing_custom_attestation_types/overview, naming_conventions/*
Planning your rollout     implementation_guide/phase_1/*

Risks & Controls — the reader is deciding what must be true, or proving it was

Risks and controls        understand_kosli/risks, understand_kosli/controls
Policies                  getting_started/enforce_policies  (+ cross-links to policy-reference/*)
Working with controls     tutorials/working_with_controls
Investigate and audit     querying_kosli, following_a_git_commit_to_runtime_environments,
                          tracing_a_production_incident_back_to_git_commits
Drift detection           detecting_unexpected_statefile_changes, detecting_non_terraform_changes
Advanced evaluation       evaluate_trails_with_opa  (+ cross-link to policy-reference/rego_policy)

Environment and runtimes — the reader is reporting, or interpreting, what is actually running

Reporting your runtime    report_k8s_envs, report_aws_envs, report_cloud_run_envs
Kosli Capture             administration/kosli_capture (#380),
                          tutorials/snapshotting_with_kosli_capture (#337),
                          kosli-capture-reference/config (#337)
How reporting works       administration/managing_environments/kubernetes_reporting (#391)
Managing environments     administration/managing_environments/overview

Record evidence — the reader is instrumenting a pipeline to produce evidence

Flows and trails          organizing_with_spaces, linking_trails_across_branches, repositories
Attestations              attest_custom, attest_snyk, attest_large_documents, custom-attestation-ctrf
CI/CD                     integrations/ci_cd, integrations/kosli_actions, trail_summaries_in_ci,
                          cli_and_http_proxy
Evidence sources          integrations/sonar, integrations/slack, integrations/launchdarkly,
                          integrations/mcp_server

Reference — unchanged. Changelog — unchanged.

URL impact

• No page files move — nav-only change, no redirects needed
• Page files move

A URL comes from the file path, not from sidebar position. helm/k8s_reporter/overview sits four containers deep under Reference and its URL is still /helm/k8s_reporter/overview. Every page keeps its address; only the tab it appears under changes.

Out of scope

• Do not rename the Reference tab or its CLI Reference menu item. scripts/update-cli-nav.py:154-158 hard-codes tab == "Reference" and item == "CLI Reference" and calls sys.exit(1) without them. It runs from update-cli-docs.yml on every CLI release, so a rename breaks the next release's doc sync.
• Do not restructure the groups inside CLI Reference; they are regenerated from the CLI command tree.
• Do not move or rename any file. That is Phase 3.
• Pages from open PRs (feat: new Kosli Capture drop-in AWS snapshotting tutorial #337, docs: add Kosli Capture Managed Service page #380, docs: document how the k8s reporter handles job and cronjob pods #391) are listed above for placement, but this issue should land against whatever is on main. Add them as those PRs merge.

Notes for whoever implements this

• config/navigation.json is the only file to edit. docs.json holds a $ref to it.
• Tab order in the file is the tab order on the site.
• tests/ enforces navigation integrity: every page file needs an entry and every entry needs a file, so the rewrite must be complete in one commit.
• Sentence case for group labels (CLAUDE.md). Phase 0 should have settled the & convention.

Verification

• python3 scripts/audit_navigation.py --check — integrity clean, no orphans, no dangling entries
• python3 -m pytest tests/ — 44 passing
• mint broken-links — no new broken links
• python3 scripts/update-cli-nav.py --docs-dir client_reference/ --nav-file config/navigation.json still exits 0
• Preview deploy: every tab renders, no empty groups, no page missing from the sidebar