docs: restructure navigation into seven job-based tabs

[dangrondahl]

Nobody knows where to put a new page. This is a proposal to fix the top-level structure so that the question has an answer, plus five phases to get there.

Full write-up with an interactive tab explorer: https://claude.ai/code/artifact/94c14e95-8be9-4a3a-be46-bb1b0f979f9d

Why it matters

Two costs, both on record:

As a writer. Documenting how the K8s reporter handles Job pods (#387) meant answering "is this a tutorial, a how-to, reference, or explanation?" before anything else. The page was filed in understand_kosli/, moved to administration/, then split again. Five review rounds on one page (#391).

As a reader. A customer asked "are Kubernetes Jobs and CronJobs detected by the reporter?" Search led to tutorials/report_k8s_envs, which describes pods and never mentions Jobs. Nothing said where to look next, so they asked us instead. That question is #387.

Neither cost shows up in a page count. Both land on the same missing rule: nothing tells a writer or a reader which tab owns a subject.

What's wrong

The top level mixes four organizing principles, so no page has an obvious home:

Tab today	Organizing principle	Pages
Documentation	everything that isn't one of the others	61
Labs	delivery format	6
Implementation Guide	rollout program / phase	8
Reference	Diátaxis doc type	129
Changelog	chronological feed	1

Documentation holds 8 groups spanning all four Diátaxis types. It is a junk drawer.

Evidence

Measured over 62 pages added in 8.5 months (excluding the initial import and the four generated trees, counting only pages that still exist), plus 9 open PRs and 14 open content issues.

Signal	What the evidence shows	Source
tutorials/ takes a third of everything	21 of 62 new pages, 3x the next directory, stable at ~1/3 every quarter	git log
Authors call it a tutorial regardless	21 of the 23 pages ever added to tutorials/ arrived in a commit calling it a "tutorial", including an HTTP proxy guide and an API-key rotation procedure	commit subjects
The author knew better	PR titled "add how-to guide for reporting AWS Bedrock AgentCore environments", filed as tutorials/report_agentcore_envs.md	#356
One feature, three homes	Kosli Capture is being written into administration/, tutorials/ and a brand-new kosli-capture-reference/	#337, #380
Placement negotiated in issue titles	5 of 14 open content issues name their destination directory in the title	#385, #170, #167, #279, #135
Mistakes stick	2 cross-directory page moves in the whole history, against 8 cross-directory redirects	git log, redirects.json

The principle

Name tabs after subjects, not document types.

One subject draws all four Diátaxis needs. Someone working on environments may want to understand snapshots, be walked through their first one, look up a flag, or fix an error. Same subject, four needs, so they belong in one tab, sorted by page form inside it.

Today we do the reverse: Documentation versus Reference splits by form first, which forces authors to classify a page before they can place it.

So give every tab a one-sentence membership test. If you cannot write one that decides whether a page belongs, the tab is wrong.

Proposed structure

Tab	Membership test	Pages
Discover Kosli	The reader has not started yet: orientation, first run, learning, getting unstuck.	~22
Platform administration	The reader is configuring Kosli itself for an organization.	~12
Risks & Controls	The reader is deciding what must be true, or proving it was.	~13
Environment and runtimes	The reader is reporting, or interpreting, what is actually running.	~8
Record evidence	The reader is instrumenting a pipeline to produce evidence.	~15
Reference	The reader knows what they want and needs exact syntax or values.	129
Changelog	What shipped.	1

URL impact

• No page files move in Phase 1 — nav-only change, no redirects needed
• Page files move — deferred to Phase 3, which carries its own redirects

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. So a page can change tab without changing address.

Out of scope

Confirmed this proposal does not restructure generated navigation:

• Reference > CLI Reference is generated by scripts/update-cli-nav.py. It also hard-codes the strings tab == "Reference" and item == "CLI Reference" and calls sys.exit(1) without them (update-cli-nav.py:154-158), so neither label can be renamed. It runs from update-cli-docs.yml on every CLI release.
• client_reference/kosli*, all 8 helm/k8s_reporter/*, terraform-reference/*, github-action-reference/* are generated or agent-synced. 123 of 205 pages. Re-homing them in navigation is fine; editing them is not.

Constraints that bind every phase

• ~20 docs URLs are compiled into released CLI binaries and can never be updated: /integrations/ci_cd (15 references), /getting_started/install, /faq/#boolean-flags, /helm/k8s_reporter/karpenter, several /client_reference/*. Their redirects are permanent.
• mint broken-links does not follow redirects. Proven: /getting_started/service-accounts has a redirect and is still reported broken in tutorials/working_with_controls.mdx. A redirect satisfies external links but not the internal check.
• ~20 more URLs come from kosli-dev/server, including the anchor /getting_started/environments/#snapshoting-an-environment, which freezes that heading.

Phases

• Phase 0 docs: clear navigation audit findings and audit redirect coverage #394: hygiene and redirect audit
• Phase 1 docs: rewrite navigation into seven job-based tabs #395: rewrite navigation into seven tabs
• Phase 2 docs: split the oversized pages the new structure exposes #396: split the oversized pages the new structure exposes
• Phase 3 docs: align the repo file structure with the navigation #397: align the repo file structure with the navigation
• Phase 4 docs: enforce tab membership and redirect coverage in CI #398: enforce membership and redirect coverage in CI

Phases 0 and 1 together carry essentially all of the value at essentially no risk. Phase 3 is the expensive one and should be scheduled deliberately rather than left open.