docs: rewrite navigation into seven job-based tabs

.claude/skills/doc-review/SKILL.md

@@ -76,7 +76,7 @@ A change is rarely confined to the files it touches. Grep the rest of the site f
 ### 2. Placement and navigation
 
 - Every new page must appear in `config/navigation.json`. Missing entry is **Critical**.
-- **Ask whether the page is in the right tab and group**, not just whether it is listed somewhere. Apply the placement table in the `doc-write` skill. A page whose content is complete factual lookup belongs in the **Reference** tab even when it documents an integration. *Precedent: a GitHub Action reference page was first authored into `integrations/`; a human reviewer had to ask for the move to Reference. That question should come from this review.*
+- **Ask whether the page is in the right tab and group**, not just whether it is listed somewhere. Apply the tab membership tests in CLAUDE.md, under "Where a page goes". A page whose content is complete factual lookup belongs in the **Reference** tab even when it documents an integration. *Precedent: a GitHub Action reference page was first authored into `integrations/`; a human reviewer had to ask for the move to Reference. That question should come from this review.*
 - Flag a new group created to hold a single page, and any page nested more than three levels below its tab.
 
 ### 3. Redirects

.claude/skills/doc-structure/SKILL.md

@@ -53,7 +53,7 @@ Judgment, not mechanics. Read the group labels and the pages under them and ask:
 - **Does a top-level tab deliver what it promises?** A tab is the strongest navigational claim the site makes. A tab holding a handful of stub pages under an ambitious name over-promises.
 - **Where would a reader look first?** For the five or six most common tasks, trace the path from the landing page. Count the clicks and the guesses.
 
-Weigh a finding by how many readers hit it. A mislabeled group at the top of the Documentation tab matters; a nesting quirk four levels into a reference section does not.
+Weigh a finding by how many readers hit it. A mislabeled group at the top of a tab matters; a nesting quirk four levels into a reference section does not.
 
 ## Step 4 — Changelog coverage
 

.claude/skills/doc-write/SKILL.md

@@ -50,27 +50,20 @@ Tutorials teach through doing; how-to guides solve one problem for someone who a
 
 ## Decide where the page goes
 
-Classification determines placement. Getting this wrong costs a follow-up commit and a reviewer's time, so decide it before writing, not after.
+Tabs are named after subjects, not document types, so **placement follows the reader's job, not the classification above.** One subject draws all four Diátaxis needs, and they belong in the same tab, sorted by page form inside it.
 
-| The page is… | Tab ▸ group |
-|---|---|
-| A concept, or the reasoning behind a design | Documentation ▸ Understand Kosli |
-| Part of the first-run sequence a new user follows in order | Documentation ▸ Getting started |
-| A task an org admin performs (users, roles, auth, org-wide settings) | Documentation ▸ Administration |
-| A task a user performs with Kosli | Documentation ▸ Tutorials |
-| Setting up Kosli with a third-party product | Documentation ▸ Integrations |
-| A specific error message or symptom | Documentation ▸ Troubleshooting |
-| Complete factual lookup — CLI, API, Terraform, Helm, schema, policy | **Reference** tab |
-| Rollout and adoption guidance for a team standing Kosli up | Implementation Guide |
+**The tab set and its membership tests live in CLAUDE.md, under "Where a page goes".** Read them there — including the warning not to rename the `Reference` tab or its `CLI Reference` menu item — and pick the tab whose test the page satisfies. If a page fails every test, the structure is wrong, not the page: raise it rather than forcing a fit.
 
-The Reference tab wins on content shape, not on subject. A reference page about an integration belongs in Reference — a GitHub Action reference page was once authored into `integrations/` and had to be moved in a follow-up commit.
+Three rules the table does not carry:
 
-A group's label may not describe its contents — read the pages already in your chosen group before writing. Where label and contents disagree, follow the convention the existing pages set; do not create a parallel group alongside it.
+- **Reference wins on content shape, not on subject.** A reference page about an integration belongs in Reference — a GitHub Action reference page was once authored into `integrations/` and had to be moved in a follow-up commit.
+- **When two tests both look plausible, ask which reader is holding the page.** Someone standing Kosli up for the first time is in Discover Kosli even if the task is administrative; someone hardening an existing org is in Platform administration even if it is their first week.
+- **Read the pages already in your chosen group before writing**, and follow the convention they set rather than creating a parallel group beside them.
 
 ## Navigation rules
 
 - **Creating a page and adding it to `config/navigation.json` are one task.** A page absent from navigation does not exist on the site.
-- Add it to an existing group. Only create a group when you are adding three or more sibling pages — a group wrapping a single page adds a click and gives nothing back.
+- Add it to an existing group. Only create a group for two or more sibling pages — a group wrapping a single page adds a click and gives nothing back, which is the shape `audit_navigation.py` flags.
 - Keep pages within three levels of their tab.
 - **Sentence case for group labels**, matching CLAUDE.md's heading rule: "Naming conventions", not "Naming Conventions".
 
@@ -82,7 +75,7 @@ A group's label may not describe its contents — read the pages already in your
 
 ## Writing
 
-1. Classify the doc type and pick the destination from the table above.
+1. Classify the doc type, then pick the tab from the membership tests in CLAUDE.md, under "Where a page goes". The type table above decides the page's form, not its place.
 2. Outline against the doc type.
 3. Write the file. Root-relative links only (`/getting_started/install`). Frontmatter `title` and `description` are required.
 4. Add the navigation entry.

CLAUDE.md

@@ -135,6 +135,32 @@ description: One sentence describing the page purpose.
   - **Explanation** — concepts and background (e.g., "What is Kosli?")
 - **MAY** Add an `icon` field to front matter using [Font Awesome](https://fontawesome.com/icons) names.
 
+### Where a page goes
+
+Tabs are named after subjects, not document types. Diátaxis decides a page's
+*form*; the tab's membership test decides its *place*. One subject draws all
+four needs, so they sit in one tab, sorted by form inside it.
+
+| Tab | Membership test — the reader… |
+|---|---|
+| Discover Kosli | …has not started yet: orientation, first run, learning, getting unstuck |
+| Platform administration | …is configuring Kosli itself for an organization |
+| Risks and controls | …is deciding what must be true, or proving it was |
+| Environments and runtime | …is reporting, or interpreting, what is actually running |
+| Record evidence | …is instrumenting a pipeline to produce evidence |
+| Reference | …knows what they want and needs exact syntax or values |
+| Changelog | …wants to know what shipped |
+
+If a page fails every test, the structure is wrong, not the page — raise it.
+
+Sidebar position is independent of the file path, so a page can change tab
+without changing its URL. Directory names still follow the old structure;
+aligning them is #397.
+
+**Don't rename the `Reference` tab or its `CLI Reference` menu item.**
+`scripts/update-cli-nav.py` hard-codes both and exits 1 without them, which
+breaks the next CLI release's doc sync.
+
 ### MDX Components
 
 | Component | Use for |

administration/managing_users/mapping_users_to_roles.md

@@ -26,7 +26,7 @@ The key principle: Assign the minimum role required for someone to fulfill their
 
 For detailed guidance on each organizational role's responsibilities during Kosli implementation, see:
 
-- [Implementation Guide: Roles and Responsibilities](/implementation_guide/phase_1/roles_and_responsibilities/overview)
+- [Roles and responsibilities](/implementation_guide/phase_1/roles_and_responsibilities/overview)
 - [Platform Engineers](/implementation_guide/phase_1/roles_and_responsibilities/platform_engineers)
 - [Application Developers](/implementation_guide/phase_1/roles_and_responsibilities/app_developers)
 - [Security & Compliance](/implementation_guide/phase_1/roles_and_responsibilities/security_compliance)