docs: rewrite navigation into seven job-based tabs

[dangrondahl]

Phase 1 of #393. Closes #395.

Stacked on #400 (Phase 0) — review that first; this PR's diff is only the tab rewrite. Interactive preview of the target structure: https://claude.ai/code/artifact/94c14e95-8be9-4a3a-be46-bb1b0f979f9d

URL impact

• No page files move — config/navigation.json only, no redirects needed
• Page files move

A URL comes from the file path, not from sidebar position, so all 207 pages keep their address while changing tab. Revertible in one commit.

The change

Documentation held 61 pages across 8 groups spanning all four Diátaxis types, with no rule for what belonged in it. Splitting Documentation from Reference by page form forced authors to classify a page before they could place it. Naming tabs after subjects means one subject's four Diátaxis needs sit in one tab, sorted by form inside it.

Tab	Membership test — the reader…	Pages
Discover Kosli	…has not started yet: orientation, first run, learning, getting unstuck	27
Platform administration	…is configuring Kosli itself for an organization	21
Risks and controls	…is deciding what must be true, or proving it was	10
Environments and runtime	…is reporting, or interpreting, what is actually running	4
Record evidence	…is instrumenting a pipeline to produce evidence	15
Reference	…knows what they want and needs exact syntax or values	129
Changelog	…wants to know what shipped	1

Tab labels are sentence case per CLAUDE.md — Risks and controls, Environments and runtime — rather than the Title Case forms written into #395. This resolves open decision 5 in the proposal and stops Phase 0's casing work being undone two tabs later. Every tab now carries an icon, clearing the last inconsistent-icons finding.

Reference is unchanged beyond gaining an icon. Per H1, scripts/update-cli-nav.py:154-158 hard-codes tab == "Reference" and item == "CLI Reference" and exits 1 without them, so neither label can move.

Deviations from the proposal, and why

Three of the proposal's groups would have held a single page, reintroducing exactly what #400 removes:

• Policies and Advanced evaluation are merged into Policies and evaluation. The proposal's policy-reference/* entries are cross-links, and those pages stay in Reference.
• working_with_controls joins the risks-and-controls pages rather than heading a group of one.
• Environments and runtime carries managing_environments/overview as a direct page beside Reporting your runtime.

Two groups are omitted:

• Infrastructure as code — its Terraform and Helm entry points are cross-links into Reference, so the group would hold no pages of its own.
• Kosli Capture and How reporting works — all four pages are still in unmerged PRs (docs: add Kosli Capture Managed Service page #380, feat: new Kosli Capture drop-in AWS snapshotting tutorial #337, docs: document how the k8s reporter handles job and cronjob pods #391). Those PRs now have an obvious home to land in, which was the argument for this tab in the first place.

Environments and runtime is therefore thin at 4 pages. That is deliberate: it is the tab that makes the seven undocumented reporters visible as a gap rather than an absence.

Three further changes came out of review:

• The tab is Risks and controls, not Risks & controls. It was the only label in the whole navigation using & — the precedents that justified it, Users & roles and Authentication & access, are groups this rewrite dissolves.
• Its Risks and controls group is dissolved rather than repeating the tab's own label; its three pages sit at tab level beside the remaining groups.
• Evidence sources is renamed Integrations. The group claimed more than it held: integrations/slack is a notification surface and integrations/mcp_server is a query surface, and neither produces evidence.

Second commit: the authoring guidance

The doc-write skill's placement table mapped page types to Documentation ▸ Tutorials and the other old tabs. None survive this rewrite, so an author following the skill would file a page under a tab that does not exist — the exact failure #393 exists to remove, reintroduced through the tool authors actually consult.

That table is now the seven membership tests, and the same table is in CLAUDE.md, which loads every session. This work was assigned to #398; it moved here because the first commit is what makes the old guidance wrong.

I also dropped the note telling authors that a group's label may not describe its contents. It was true of Documentation ▸ Tutorials, which held mostly how-to guides. It is not true of the new groups, and keeping it would teach authors to distrust labels that are now accurate.

Conflicts to expect

Four open PRs also touch config/navigation.json: #391 and #380 are active, #338 and #337 are stale drafts. This PR rewrites the file wholesale, so whichever lands second pays the conflict. The suggestion is not to block on them — land #391 and #380 on their own track and rebase this stack, and let the two stale drafts absorb the conflict when someone revives them.

Verification

• 207 pages before and after, set-identical, no duplicates
• python3 scripts/audit_navigation.py — 1 advisory finding left, down from 32 across the stack
• python3 scripts/audit_navigation.py --check — exit 0
• python3 -m pytest tests/ — 44 passed
• mint broken-links — zero broken links
• Reference tab and CLI Reference item labels unchanged (H1)

[claude]

Claude encountered an error after 4m 2s —— View job

---

Doc review — third pass (head df29f18)

• Read the diff and every changed file at branch head
• Cross-check config/navigation.json against prose, the skills and CLAUDE.md
• Re-check the second pass's findings against head
• Post findings

df29f18 closes findings 1, 2 and 4 of the second pass: doc-review/SKILL.md and doc-write/SKILL.md step 1 both point at CLAUDE.md's "Where a page goes" now, and the group threshold matches what audit_navigation.py enforces. I re-read all four guidance files at head — no reference to a deleted tab survives in CLAUDE.md, doc-write, doc-review or doc-structure. (The runner's working tree still has those four files reverted to the base layer, so I read them via git show HEAD:.)

Two findings this pass, both inline.

1. administration/managing_environments/overview is a Terraform how-to (config/navigation.json:151) — and this corrects the second pass. Its own line 13 says "This page covers managing environments via Terraform. For creating environments via the CLI or UI, see Getting started: Environments." So it is not the entry point the earlier suggestion tried to hoist to the top of Environments and runtime, and against the tab's published test — "…is reporting, or interpreting, what is actually running" — it reads as configuration, not runtime. Details inline.

2. understand_kosli/what_is_kosli.md:33 is still half-updated — [Getting Started] names a label that no longer exists; the group is Get started. 9c86c0f fixed the other half of the same line. Suggestion inline.

Outstanding from the second pass, not re-argued

• The two "pages" tabs still disagree about direction. Risks and controls (111–114) puts direct pages before its groups; Environments and runtime (142–151) puts its one direct page after. Finding 1 above changes which page belongs at the top of that tab but not the inconsistency itself.
• Record evidence ▸ Integrations still holds slack and mcp_server, which do not produce evidence. Noted as deferred to docs: restructure navigation into seven job-based tabs #393; I won't restate the argument.

Could not run

python3 scripts/audit_navigation.py, pytest tests/, mint broken-links and gh queries all need approval that this run does not have, so I verified navigation structure by reading audit_navigation.py (group-size limit 12, so the two 9-page groups are clear; Kosli is in _PROPER_NOUNS, so Understand Kosli is not a Title Case finding) and confirmed update-cli-nav.py:154-172 still finds Reference ▸ CLI Reference — the trailing "icon": "book" after "menu" survives its json.load/json.dump round-trip, though it is the only tab whose icon is not the key after tab. Your own run of the three commands stands; I did not re-verify the counts.

No new page files, no moves, so no config/redirects.json entry is needed. No relative links introduced.
· branch docs/nav-seven-tabs

[claude]

Two of these four fail the tab's own membership test.

Record evidence is defined in this PR as "…is instrumenting a pipeline to produce evidence."

• integrations/slack — "receive notifications about changes in your environments and query Kosli … without leaving Slack". Consumption, not production.
• integrations/mcp_server — "exposes the Kosli API to AI assistants … ask which environments are non-compliant, and why?". Querying, not evidence.

integrations/sonar is a genuine evidence source; integrations/ci_cd and integrations/kosli_actions above are too. The Slack and MCP pages are notification/query surfaces, and per this PR's own rule ("If a page fails every test, the structure is wrong, not the page — raise it") they either need a home that fits or the tab set needs a seventh test for "get Kosli's answers where I already work."

[claude]

Two things here, both structural rather than cosmetic.

"pages" instead of "groups". Every other content tab in this file (Discover Kosli, Platform administration, Risks & controls, Record evidence) uses "groups". Mintlify accepts a group object inside a tab-level "pages", so this renders, but it is the only tab shaped differently.

The bare page lands at the bottom. administration/managing_environments/overview is titled "Managing environments" and is the closest thing this tab has to an entry point, but as an ungrouped sibling after the group it renders below the three reporting how-tos. A reader arriving at the tab meets report_k8s_envs first.

Suggested change

	"tab": "Environments and runtime",
	"icon": "server",
	"pages": [
	{
	"group": "Kosli learning labs",
	"group": "Reporting your runtime",
	"pages": [
	"labs/index",
	"labs/lab-01-get-ready",
	"labs/lab-02-flows-and-trails",
	"labs/lab-03-build-controls",
	"labs/lab-04-release-controls",
	"labs/lab-05-runtime-controls"
	"tutorials/report_k8s_envs",
	"tutorials/report_aws_envs",
	"tutorials/report_cloud_run_envs"
	]
	}
	},
	"administration/managing_environments/overview"
	]
	"tab": "Environments and runtime",
	"icon": "server",
	"groups": [
	"administration/managing_environments/overview",
	{
	"group": "Reporting your runtime",
	"pages": [
	"tutorials/report_k8s_envs",
	"tutorials/report_aws_envs",
	"tutorials/report_cloud_run_envs"
	]
	}
	]
	},

(The Terraform Reference menu item at line 430 already uses this string-then-group form under "groups", so it is an established pattern in this file.)

Separately: at four pages this is the thinnest tab, while Risks & controls ▸ Drift detection holds two pages about detecting unexpected changes in running infrastructure — arguably "interpreting what is actually running." Worth deciding deliberately rather than by inheritance.

[claude]

Two label problems in five lines.

& vs and. This is the only tab using an ampersand — Environments and runtime spells it out. The commit before this one in the stack (03b83ae) was specifically about label hygiene, and the base nav's Authentication & access / Users & roles / Querying & tracing groups were all dissolved here. Picking one form and applying it is worth the churn now, before both spellings get quoted into CLAUDE.md and the skill.

The group repeats the tab. Risks & controls ▸ Risks and controls is the redundant wrapper 03b83ae set out to remove. Its three pages (understand_kosli/risks, understand_kosli/controls, tutorials/working_with_controls) could sit directly under the tab, or take a label that says what distinguishes them from the other three groups — something like Define risks and controls.

[claude]

This table is byte-for-byte the same as the one added to .claude/skills/doc-write/SKILL.md in the same commit. Two copies of a membership test will drift the first time a tab is renamed, and the reader has no way to tell which is authoritative.

Consider keeping the table in one place and pointing at it from the other — CLAUDE.md already does this for the doc-write/doc-review/doc-structure skills in its Skills section.

[claude]

faq/faq.md:4 carries icon: circle-question, added two commits ago (268720f) for a reason this commit removes:

Also restore the FAQ icon that the dissolve dropped … so it does not render as the one bare link among the Documentation tab's icon-bearing groups.

faq/faq is no longer a bare link beside icon-bearing groups — it is the first page inside Help and troubleshooting, and the other eight pages in that group have no front-matter icon. The icon now produces the inverse of the inconsistency it was added to fix: one icon-bearing page among eight plain siblings.

Drop the front-matter icon, or give the group's pages a consistent treatment. Either way it is a decision this commit made and did not follow through on.

[claude]

Moving these two out of Understand Kosli breaks the only ordered reading path the site publishes.

understand_kosli/what_is_kosli.md:30, under New to Kosli?:

Read Risks, Controls, and How Kosli works in order.

After this change, steps 1 and 2 of that sequence are in Risks & controls while steps 0, 3 and the glossary stay in Discover Kosli ▸ Understand Kosli. A reader who follows the sidebar instead of the accordion goes what_is_kosli → how_kosli_works → glossary and never meets Risks or Controls.

Both pages describe themselves as orientation, not decision-making — "Why modern software delivery introduces risks, and how to think about them" and "Why SDLC controls exist, how they mitigate software delivery risks" — which is the Discover Kosli test ("has not started yet: orientation…"), not Risks & controls ("is deciding what must be true, or proving it was"). tutorials/working_with_controls passes the new tab's test; these two read as the concepts behind it.

Either keep them in Discover Kosli ▸ Understand Kosli and let the new tab hold the doing, or rewrite the accordion so the path it promises matches the sidebar.

[dangrondahl]

All six addressed in 9c86c0f. Taking them in order of how much they mattered:

4. The two copies of the membership table already disagree — the sharpest finding, and correct. I created the drift in the same commit that created the copies. CLAUDE.md now holds the table as the single source; the skill points at it and keeps only the three rules the table does not carry (Reference-wins-on-shape, the both-tests-plausible tiebreaker, read-the-group-first).

3. Prose and agent guidance still name deleted tabs — fixed all three. Agreed that doc-structure mattered most: it audits this navigation monthly and was weighing findings against a tab that no longer exists.

6. The three open items — all three taken, not deferred:

• Risks & controls → Risks and controls. Checked before changing it: after this rewrite it was the only label in the entire nav using &, because the precedents I had cited for keeping it (Users & roles, Authentication & access) are groups this PR dissolves. The justification was gone.
• The echoing Risks and controls group is dissolved; its three pages sit at tab level.
• Evidence sources → Integrations. You were right that Slack is notifications and the MCP server is a query surface. Renaming the group states what it holds without re-homing pages against the proposal's own assignment — if those two should move tabs, that is a call for docs: restructure navigation into seven job-based tabs #393 rather than a rename.

1. FAQ icon — removed here. Worth noting it stays on #400, where it is correct: FAQ sits among icon-bearing groups in the Documentation tab there. Adding it below and removing it above is the stack behaving as intended, each layer internally consistent.

5. Your correction to the earlier inline suggestion — confirmed, and thank you for catching it against 268720f rather than restating it. "pages" on that tab is deliberate.

2. The ordered reading path spanning two tabs — acknowledged and not changed. what_is_kosli.md:30 still sends readers through Risks → Controls → How Kosli works, and the first two now live in Risks and controls. The links resolve and the stated order still holds, so nothing is broken for a reader following them. But you are right that it is a real seam, and it turns on whether understand_kosli/risks and controls are orientation (Discover Kosli) or decision-making (Risks and controls). The proposal assigns them to the latter deliberately; re-litigating that is a #393 question, not something to settle in a review thread. Flagged for the author.

Re-verified at head: audit_navigation.py --check exit 0 (2 advisory findings, both the accepted Terraform taxonomy exceptions), pytest tests/ 44 passed, mint broken-links clean, 207 pages set-identical.

On your process note — the uncommitted revert of CLAUDE.md and SKILL.md in the runner's tree was a local git checkout to the layer below, where those files legitimately have no changes. Nothing was lost, and reviewing 6afb548 via git show was the right call.

[claude]

The tab's entry point still renders below the how-tos, and this file now contradicts itself about where direct pages go.

Risks and controls (lines 111–114) was reshaped in 9c86c0f to put its direct pages before its groups. This tab keeps the opposite order, so administration/managing_environments/overview — "Managing environments", the only page here that explains what an environment is — renders after report_k8s_envs. A reader who opens the tab meets a Kubernetes how-to first.

Suggested change

	"pages": [
	{
	"group": "Kosli learning labs",
	"group": "Reporting your runtime",
	"pages": [
	"labs/index",
	"labs/lab-01-get-ready",
	"labs/lab-02-flows-and-trails",
	"labs/lab-03-build-controls",
	"labs/lab-04-release-controls",
	"labs/lab-05-runtime-controls"
	"tutorials/report_k8s_envs",
	"tutorials/report_aws_envs",
	"tutorials/report_cloud_run_envs"
	]
	}
	},
	"administration/managing_environments/overview"
	]
	"pages": [
	"administration/managing_environments/overview",
	{
	"group": "Reporting your runtime",
	"pages": [
	"tutorials/report_k8s_envs",
	"tutorials/report_aws_envs",
	"tutorials/report_cloud_run_envs"
	]
	}
	]

[claude]

Renaming this group from Evidence sources to Integrations moves the mismatch up a level rather than resolving it — and creates a second one.

The tab's membership test, now published in CLAUDE.md:150, is "…is instrumenting a pipeline to produce evidence." integrations/slack ("receive notifications … and query Kosli without leaving Slack") and integrations/mcp_server ("ask which environments are non-compliant, and why?") are consumption surfaces; neither produces evidence, so they fail the tab, not just the group.

The label also now competes with the group above it: integrations/ci_cd and integrations/kosli_actions are integrations too, and they sit in CI/CD. A reader scanning for "Integrations" will not expect the CI ones to be elsewhere.

Record evidence ▸ Evidence sources for sonar and launchdarkly was the accurate part. The open question is where the two query/notification pages go — per this PR's own rule (CLAUDE.md:152, "If a page fails every test, the structure is wrong, not the page"), that is a missing test, not a page to force in.

[claude]

Half of this line was updated to the new labels. [Getting Started] is the other half: the group it points at is now Discover Kosli ▸ Get started, and the Getting started label it quotes no longer exists anywhere in config/navigation.json.

Suggested change

	Head to [Getting Started](/getting_started/install) for step-by-step setup, or see [Planning your rollout](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning.
	Head to [Get started](/getting_started/install) for step-by-step setup, or see [Planning your rollout](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning.

Line 30, three lines up, has the larger version of the same problem — see the top-level comment.

[claude]

This page is a Terraform how-to, which changes the earlier round's read of it — including mine.

administration/managing_environments/overview.md:3 describes itself as "manage Kosli environments via Terraform", and line 13 is explicit:

This page covers managing environments via Terraform. For creating environments via the CLI or UI, see Getting started: Environments.

So two things follow:

• It is not this tab's entry point. Hoisting it above Reporting your runtime — which the previous round suggested, and which Risks and controls now does with its direct pages — would put a resource "kosli_environment" HCL block in front of a reader who has not been told what a Kosli environment is. Please disregard that part of the earlier suggestion; the ordering inconsistency between the two "pages" tabs is still real, but this is not the page that fixes it.
• It reads against the tab's own test. "…is reporting, or interpreting, what is actually running" describes the three reporting how-tos; declaring environments as IaC is closer to "configuring Kosli itself for an organization". The PR body dropped the proposal's Infrastructure as code group because its entries were cross-links — this is the one page that would have belonged in it.

The page the tab is actually missing is the conceptual one it defers to, getting_started/environments, which lands in Discover Kosli ▸ Core concepts. That is defensible for a first-run reader, but it leaves Environments and runtime with no page that explains its own subject.

Fix this →

[claude]

Still half-updated at head. 9c86c0f fixed the second link's text (Implementation Guide → Planning your rollout) and left the first: Getting Started is not a label in config/navigation.json any more — the group is Discover Kosli ▸ Get started (line 16).

Suggested change

	Head to [Getting Started](/getting_started/install) for step-by-step setup, or see [Planning your rollout](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning.
	Head to [Get started](/getting_started/install) for step-by-step setup, or see [Planning your rollout](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning.

Fix this →