From 56806d372229e733f939b6b830e2a85db302cd0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:26:57 +0200 Subject: [PATCH 1/4] docs: rewrite navigation into seven job-based tabs Phase 1 of #393. Closes #395. One edit to config/navigation.json: no page files move, no URLs change, no redirects needed, revertible in this commit. A URL comes from the file path, not from sidebar position, so every one of the 207 pages keeps its address while changing tab. Replace the five tabs, which mixed four organizing principles, with seven named after subjects. Each carries a one-sentence membership test: - Discover Kosli (27) - the reader has not started yet: orientation, first run, learning, getting unstuck - Platform administration (21) - the reader is configuring Kosli itself for an organization - Risks & controls (10) - the reader is deciding what must be true, or proving it was - Environments and runtime (4) - the reader is reporting, or interpreting, what is actually running - Record evidence (15) - the reader is instrumenting a pipeline to produce evidence - Reference (129) - the reader knows what they want and needs exact syntax or values - Changelog (1) - what shipped Documentation held 61 pages across 8 groups spanning all four Diataxis 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 Diataxis needs sit in one tab, sorted by form inside it. Tab labels are sentence case per CLAUDE.md, so `Risks & controls` and `Environments and runtime` rather than the Title Case forms in #395. This resolves open decision 5 in the proposal and keeps Phase 0's casing work from being undone two tabs later. Every tab now carries an icon, clearing the last inconsistent-icons finding. Reference is unchanged beyond gaining an icon. H1: update-cli-nav.py:154-158 hard-codes `tab == "Reference"` and `item == "CLI Reference"` and exits 1 without them, so neither label can move. Three deviations from the proposal's group layout, all because the group it specifies would hold a single page and reintroduce what Phase 0 just removed: - Policies and Advanced evaluation are merged into `Policies and evaluation`. The proposal's policy-reference/* entries are cross-links, which stay in Reference. - Working with controls joins `Risks and controls` rather than heading a group of one. - Environments and runtime carries managing_environments/overview as a direct page beside `Reporting your runtime`. The proposal's `Infrastructure as code` group is omitted: its Terraform and Helm entry points are cross-links into Reference, so it would hold no pages of its own. The `Kosli Capture` and `How reporting works` groups are also omitted because all four of their pages are still in unmerged PRs (#380, argument for the tab. Verified: 207 pages before and after, set-identical with no duplicates; audit_navigation.py down to 1 advisory finding; pytest 44 passed; mint broken-links clean. --- config/navigation.json | 267 +++++++++++++++++++++-------------------- 1 file changed, 137 insertions(+), 130 deletions(-) diff --git a/config/navigation.json b/config/navigation.json index 4886be2..c3610db 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -1,192 +1,198 @@ { "tabs": [ { - "tab": "Documentation", - "pages": [ + "tab": "Discover Kosli", + "icon": "compass", + "groups": [ { "group": "Understand Kosli", - "icon": "book-open", "pages": [ "understand_kosli/what_is_kosli", - "understand_kosli/risks", - "understand_kosli/controls", "understand_kosli/how_kosli_works", - "understand_kosli/glossary", - "understand_kosli/ai_docs_access" + "understand_kosli/glossary" ] }, { - "group": "Getting started", - "icon": "rocket", + "group": "Get started", "pages": [ "getting_started/install", "getting_started/authenticating_to_kosli", + "tutorials/try_kosli_locally" + ] + }, + { + "group": "Core concepts", + "pages": [ "getting_started/flows", "getting_started/trails", "getting_started/artifacts", "getting_started/attestations", "getting_started/environments", - "getting_started/policies", - "getting_started/enforce_policies" + "getting_started/policies" + ] + }, + { + "group": "Learning labs", + "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" ] }, { - "group": "User", - "icon": "user", + "group": "Help and troubleshooting", + "pages": [ + "faq/faq", + "troubleshooting/what_do_i_do_if_kosli_is_down", + "troubleshooting/docker_api_version_error", + "troubleshooting/repo_digest_unavailable", + "troubleshooting/zsh_no_such_user", + "troubleshooting/github_kosli_api_token", + "troubleshooting/subshell_stderr", + "troubleshooting/whitespace_path", + "understand_kosli/ai_docs_access" + ] + } + ] + }, + { + "tab": "Platform administration", + "icon": "sliders", + "groups": [ + { + "group": "Your account", "pages": [ "user/default_organization", "user/personal_api_keys" ] }, { - "group": "Administration", - "icon": "cog", + "group": "Users and access", "pages": [ - { - "group": "Authentication & access", - "pages": [ - "administration/authentication/single_sign_on", - "administration/authentication/magic_link", - "administration/authentication/api_authentication_methods", - "administration/authentication/service_accounts", - "administration/authentication/api_key_rotation" - ] - }, - { - "group": "Users & roles", - "pages": [ - "administration/managing_users/roles_in_kosli", - "administration/managing_users/mapping_users_to_roles", - "administration/managing_users/automated_user_provisioning" - ] - }, - "administration/managing_environments/overview", + "administration/managing_users/roles_in_kosli", + "administration/managing_users/mapping_users_to_roles", + "administration/managing_users/automated_user_provisioning", + "administration/authentication/single_sign_on", + "administration/authentication/magic_link", + "administration/authentication/api_authentication_methods", + "administration/authentication/service_accounts", + "administration/authentication/api_key_rotation", + "tutorials/rotating_api_keys" + ] + }, + { + "group": "Organization structure", + "pages": [ + "administration/managing_tags", "administration/managing_custom_attestation_types/overview", - "administration/managing_tags" + "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/overview", + "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/attestation_types", + "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/flows_and_trails" ] }, { - "group": "Tutorials", - "icon": "graduation-cap", + "group": "Planning your rollout", "pages": [ - { - "group": "Getting started", - "pages": [ - "tutorials/try_kosli_locally", - "tutorials/cli_and_http_proxy", - "tutorials/organizing_with_spaces" - ] - }, - { - "group": "Attesting", - "pages": [ - "tutorials/attest_custom", - "tutorials/attest_snyk", - "tutorials/custom-attestation-ctrf", - "tutorials/attest_large_documents" - ] - }, - { - "group": "Reporting environments", - "pages": [ - "tutorials/report_aws_envs", - "tutorials/report_k8s_envs", - "tutorials/report_cloud_run_envs" - ] - }, - { - "group": "Querying & tracing", - "pages": [ - "tutorials/querying_kosli", - "tutorials/following_a_git_commit_to_runtime_environments", - "tutorials/tracing_a_production_incident_back_to_git_commits", - "tutorials/trail_summaries_in_ci" - ] - }, - { - "group": "Security", - "pages": [ - "tutorials/detecting_unexpected_statefile_changes", - "tutorials/detecting_non_terraform_changes", - "tutorials/rotating_api_keys" - ] - }, - "tutorials/evaluate_trails_with_opa", - "tutorials/linking_trails_across_branches", - "tutorials/working_with_controls", - "tutorials/repositories" + "implementation_guide/phase_1/roles_and_responsibilities/overview", + "implementation_guide/phase_1/roles_and_responsibilities/platform_engineers", + "implementation_guide/phase_1/roles_and_responsibilities/app_developers", + "implementation_guide/phase_1/roles_and_responsibilities/security_compliance", + "implementation_guide/phase_1/roles_and_responsibilities/sponsors" + ] + } + ] + }, + { + "tab": "Risks & controls", + "icon": "shield-halved", + "groups": [ + { + "group": "Risks and controls", + "pages": [ + "understand_kosli/risks", + "understand_kosli/controls", + "tutorials/working_with_controls" ] }, { - "group": "Troubleshooting", - "icon": "wrench", + "group": "Policies and evaluation", "pages": [ - "troubleshooting/what_do_i_do_if_kosli_is_down", - "troubleshooting/docker_api_version_error", - "troubleshooting/repo_digest_unavailable", - "troubleshooting/zsh_no_such_user", - "troubleshooting/github_kosli_api_token", - "troubleshooting/subshell_stderr", - "troubleshooting/whitespace_path" + "getting_started/enforce_policies", + "tutorials/evaluate_trails_with_opa" ] }, - "faq/faq", { - "group": "Integrations", - "icon": "puzzle-piece", + "group": "Investigate and audit", "pages": [ - "integrations/kosli_actions", - "integrations/ci_cd", - "integrations/slack", - "integrations/launchdarkly", - "integrations/sonar", - "integrations/mcp_server" + "tutorials/querying_kosli", + "tutorials/following_a_git_commit_to_runtime_environments", + "tutorials/tracing_a_production_incident_back_to_git_commits" + ] + }, + { + "group": "Drift detection", + "pages": [ + "tutorials/detecting_unexpected_statefile_changes", + "tutorials/detecting_non_terraform_changes" ] } ] }, { - "tab": "Labs", - "groups": [ + "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": "Implementation Guide", + "tab": "Record evidence", + "icon": "clipboard-check", "groups": [ { - "group": "Phase 1: initial discovery", - "icon": "lightbulb", + "group": "Flows and trails", "pages": [ - "implementation_guide/phase_1/roles_and_responsibilities/overview", - "implementation_guide/phase_1/roles_and_responsibilities/platform_engineers", - "implementation_guide/phase_1/roles_and_responsibilities/app_developers", - "implementation_guide/phase_1/roles_and_responsibilities/security_compliance", - "implementation_guide/phase_1/roles_and_responsibilities/sponsors" + "tutorials/organizing_with_spaces", + "tutorials/linking_trails_across_branches", + "tutorials/repositories" ] }, { - "group": "Phase 2: configure Kosli", - "icon": "gear", + "group": "Attestations", "pages": [ - { - "group": "Naming conventions", - "pages": [ - "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/overview", - "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/attestation_types", - "implementation_guide/phase_2/plan_organizational_structure/naming_conventions/flows_and_trails" - ] - } + "tutorials/attest_custom", + "tutorials/attest_snyk", + "tutorials/attest_large_documents", + "tutorials/custom-attestation-ctrf" + ] + }, + { + "group": "CI/CD", + "pages": [ + "integrations/ci_cd", + "integrations/kosli_actions", + "tutorials/trail_summaries_in_ci", + "tutorials/cli_and_http_proxy" + ] + }, + { + "group": "Evidence sources", + "pages": [ + "integrations/sonar", + "integrations/slack", + "integrations/launchdarkly", + "integrations/mcp_server" ] } ] @@ -504,7 +510,8 @@ } ] } - ] + ], + "icon": "book" }, { "tab": "Changelog", From 08d21a3888fb9184eb4d29381fe8fe34808b8d9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:28:16 +0200 Subject: [PATCH 2/4] docs: document the seven tabs and their membership tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of #393. Pulled forward from #398, because the previous commit is what makes this guidance wrong. The doc-write skill's placement table mapped page types to `Documentation ▸ Tutorials`, `Documentation ▸ Administration` and the other old tabs. None of them exist after the tab rewrite, so an author following the skill would file a page under a tab that is not there - the exact failure #393 exists to remove, reintroduced through the tool authors actually consult. Replace that table with the seven membership tests, and state the rule the old table contradicted: tabs are named after subjects, so Diataxis decides a page's form while the membership test decides its place. Add the same table to CLAUDE.md, which is loaded on every session, along with the H1 warning not to rename the Reference tab or its CLI Reference menu item. Also drop 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. --- .claude/skills/doc-write/SKILL.md | 31 +++++++++++++++++-------------- CLAUDE.md | 26 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 14 deletions(-) diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index 0180317..6196b46 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -50,22 +50,25 @@ 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 | +Pick the tab whose membership test the page satisfies. If a page fails every test, the structure is wrong, not the page — raise it rather than forcing a fit. + +| Tab | Membership test — the reader… | |---|---| -| 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 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. - -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. +| **Discover Kosli** | …has not started yet: orientation, first run, learning, getting unstuck | +| **Platform administration** | …is configuring Kosli itself for an organization | +| **Risks & 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 | + +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. + +Two tests can both look plausible. When they do, 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 diff --git a/CLAUDE.md b/CLAUDE.md index 78b2b55..ec6a2aa 100644 --- a/CLAUDE.md +++ b/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 & 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 | From 9c86c0fb6e4c9163dc4d1e53444e8bd9f30e83c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:53:47 +0200 Subject: [PATCH 3/4] docs: one source for the membership tests, and fix stale tab names Addresses the doc-review findings on #401. The membership table was copied into both CLAUDE.md and the doc-write skill, and the two copies had already diverged in the commit that created them: only the skill carried "Reference wins on content shape", only CLAUDE.md carried the warning against renaming the Reference tab. Neither copy was complete and neither was authoritative. CLAUDE.md now holds the table, and the skill points at it and keeps only the three rules the table does not carry. Sweep the tab names this rewrite deletes but left behind in prose: - understand_kosli/what_is_kosli.md sent readers to "the Implementation Guide", now Platform administration > Planning your rollout - administration/managing_users/mapping_users_to_roles.md named the same destination - .claude/skills/doc-structure/SKILL.md weighed findings against "the Documentation tab", which no longer exists - and that skill is what audits this navigation every month Rename the tab `Risks & controls` to `Risks and 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. Dissolve `Risks and controls > Risks and controls`, which repeated its tab's label. Its three pages read correctly at tab level beside the remaining groups. Rename `Evidence sources` to `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. Remove the FAQ page icon added in 268720f. It was right on the layer below, where FAQ sat among icon-bearing groups in the Documentation tab; here faq/faq is one of nine pages in `Help and troubleshooting`, none of which carry an icon, so the icon creates the inverse inconsistency. --- .claude/skills/doc-structure/SKILL.md | 2 +- .claude/skills/doc-write/SKILL.md | 20 +++++-------------- CLAUDE.md | 2 +- .../managing_users/mapping_users_to_roles.md | 2 +- config/navigation.json | 17 ++++++---------- faq/faq.md | 1 - understand_kosli/what_is_kosli.md | 2 +- 7 files changed, 15 insertions(+), 31 deletions(-) diff --git a/.claude/skills/doc-structure/SKILL.md b/.claude/skills/doc-structure/SKILL.md index 9b98c4b..f0ac095 100644 --- a/.claude/skills/doc-structure/SKILL.md +++ b/.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 diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index 6196b46..ec51d69 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -52,23 +52,13 @@ Tutorials teach through doing; how-to guides solve one problem for someone who a 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. -Pick the tab whose membership 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 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. -| 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 & 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 | - -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. - -Two tests can both look plausible. When they do, 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. +Three rules the table does not carry: -Read the pages already in your chosen group before writing, and follow the convention they set rather than creating a parallel group beside them. +- **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 diff --git a/CLAUDE.md b/CLAUDE.md index ec6a2aa..f8beb7c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -145,7 +145,7 @@ four needs, so they sit in one tab, sorted by form inside it. |---|---| | Discover Kosli | …has not started yet: orientation, first run, learning, getting unstuck | | Platform administration | …is configuring Kosli itself for an organization | -| Risks & controls | …is deciding what must be true, or proving it was | +| 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 | diff --git a/administration/managing_users/mapping_users_to_roles.md b/administration/managing_users/mapping_users_to_roles.md index c357db6..f033977 100644 --- a/administration/managing_users/mapping_users_to_roles.md +++ b/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) diff --git a/config/navigation.json b/config/navigation.json index c3610db..017bf62 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -106,17 +106,12 @@ ] }, { - "tab": "Risks & controls", + "tab": "Risks and controls", "icon": "shield-halved", - "groups": [ - { - "group": "Risks and controls", - "pages": [ - "understand_kosli/risks", - "understand_kosli/controls", - "tutorials/working_with_controls" - ] - }, + "pages": [ + "understand_kosli/risks", + "understand_kosli/controls", + "tutorials/working_with_controls", { "group": "Policies and evaluation", "pages": [ @@ -187,7 +182,7 @@ ] }, { - "group": "Evidence sources", + "group": "Integrations", "pages": [ "integrations/sonar", "integrations/slack", diff --git a/faq/faq.md b/faq/faq.md index ba1a90f..2ad79cf 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -1,7 +1,6 @@ --- title: FAQ description: "Frequently asked questions" -icon: circle-question --- diff --git a/understand_kosli/what_is_kosli.md b/understand_kosli/what_is_kosli.md index 20a6934..cb52414 100644 --- a/understand_kosli/what_is_kosli.md +++ b/understand_kosli/what_is_kosli.md @@ -30,7 +30,7 @@ You report events of interest (builds, test results, deployments, environment st Read [Risks](/understand_kosli/risks), [Controls](/understand_kosli/controls), and [How Kosli works](/understand_kosli/how_kosli_works) in order. Use the [Glossary](/understand_kosli/glossary) as a reference along the way. When you are ready to try it hands-on, work through the [Learning Labs](/labs). - Head to [Getting Started](/getting_started/install) for step-by-step setup, or see the [Implementation Guide](/implementation_guide/phase_1/roles_and_responsibilities/overview) for organizational rollout planning. + 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. See the [Glossary](/understand_kosli/glossary) for quick-reference definitions of every Kosli term. From df29f18d42b40a7702d8bb770ab4cb5d673afac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 17:00:11 +0200 Subject: [PATCH 4/4] docs: repoint the guidance the de-duplication left dangling Addresses findings 1, 2 and 4 of the second doc-review pass on #401. The first two are regressions from 9c86c0f, which moved the placement table to CLAUDE.md without following its inbound references. - .claude/skills/doc-review/SKILL.md told reviewers to "apply the placement table in the doc-write skill", which that commit deleted. It now points at CLAUDE.md. This is the skill that runs on every PR, so it was reviewing placement against a table that no longer existed. - doc-write's "Writing" step 1 said "pick the destination from the table above". After the move, the nearest table above it is the Diataxis type table - the one the skill explicitly says placement does not follow. Also relax doc-write's group threshold from three sibling pages to two. The seven-tab structure ships three two-page groups (`Your account`, `Policies and evaluation`, `Drift detection`), so the old threshold judged the next author by a rule the navigation itself breaks. Two matches the rule's own rationale and what audit_navigation.py enforces: it flags a group of exactly one. --- .claude/skills/doc-review/SKILL.md | 2 +- .claude/skills/doc-write/SKILL.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/doc-review/SKILL.md b/.claude/skills/doc-review/SKILL.md index 2157f5f..4b4f202 100644 --- a/.claude/skills/doc-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/doc-write/SKILL.md b/.claude/skills/doc-write/SKILL.md index ec51d69..b0faf00 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.claude/skills/doc-write/SKILL.md @@ -63,7 +63,7 @@ Three rules the table does not carry: ## 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". @@ -75,7 +75,7 @@ Three rules the table does not carry: ## 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.