diff --git a/.claude/skills/doc-review/SKILL.md b/.claude/skills/doc-review/SKILL.md index 2157f5fb..4b4f2025 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-structure/SKILL.md b/.claude/skills/doc-structure/SKILL.md index 9b98c4b0..f0ac0958 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 0180317c..b0faf000 100644 --- a/.claude/skills/doc-write/SKILL.md +++ b/.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. diff --git a/CLAUDE.md b/CLAUDE.md index 78b2b558..f8beb7c4 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 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 | diff --git a/administration/managing_users/mapping_users_to_roles.md b/administration/managing_users/mapping_users_to_roles.md index c357db61..f033977e 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 4886be2a..017bf627 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -1,192 +1,193 @@ { "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 and controls", + "icon": "shield-halved", + "pages": [ + "understand_kosli/risks", + "understand_kosli/controls", + "tutorials/working_with_controls", + { + "group": "Policies and evaluation", + "pages": [ + "getting_started/enforce_policies", + "tutorials/evaluate_trails_with_opa" ] }, { - "group": "Troubleshooting", - "icon": "wrench", + "group": "Investigate and audit", "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" + "tutorials/querying_kosli", + "tutorials/following_a_git_commit_to_runtime_environments", + "tutorials/tracing_a_production_incident_back_to_git_commits" ] }, - "faq/faq", { - "group": "Integrations", - "icon": "puzzle-piece", + "group": "Drift detection", "pages": [ - "integrations/kosli_actions", - "integrations/ci_cd", - "integrations/slack", - "integrations/launchdarkly", - "integrations/sonar", - "integrations/mcp_server" + "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": "Integrations", + "pages": [ + "integrations/sonar", + "integrations/slack", + "integrations/launchdarkly", + "integrations/mcp_server" ] } ] @@ -504,7 +505,8 @@ } ] } - ] + ], + "icon": "book" }, { "tab": "Changelog", diff --git a/faq/faq.md b/faq/faq.md index ba1a90fe..2ad79cfa 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 20a69345..cb524149 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.