From 70a5b08331e4877d0233957ebbb21395e495a930 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:04:29 +0200 Subject: [PATCH 1/4] docs: fix broken link and add redirects for unresolved external URLs Phase 0 of #393, part of #394. No navigation changes. Rewrite the /getting_started/service-accounts link in tutorials/working_with_controls.mdx to its real target, /getting_started/authenticating_to_kosli. A redirect already covered the URL, but mint broken-links does not follow redirects, so the link itself had to change. mint broken-links now reports zero broken links. Audit every docs.kosli.com URL referenced from kosli-dev/cli and kosli-dev/server (45 unique, all file types, not just .go and .py) against config/navigation.json, config/redirects.json and production. Every URL compiled into a released CLI binary resolves today. Six 404 in production; add redirects for the three that have a target in this repo: - /kosli_overview/what_is_audit_trail -> /understand_kosli/what_is_kosli - /implementation_guide/phase_2/sso_configuration{,/entra_id_setup,/okta_setup} -> /administration/authentication/single_sign_on (SSO docs shipped in #392 under administration/authentication/, not the path the server runbooks send customers to) - /kosli-logo-dark-main.svg -> /logo/kosli-logo-dark-main.svg (referenced as the API reference logo from server routes_swagger.py:19) The remaining three need upstream fixes and are reported separately. --- config/redirects.json | 20 ++++++++++++++++++++ tutorials/working_with_controls.mdx | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/config/redirects.json b/config/redirects.json index cbe6d8a..4bc6282 100644 --- a/config/redirects.json +++ b/config/redirects.json @@ -110,5 +110,25 @@ { "source": "/client_reference/kosli_request_approval", "destination": "/client_reference/overview" + }, + { + "source": "/kosli_overview/what_is_audit_trail", + "destination": "/understand_kosli/what_is_kosli" + }, + { + "source": "/implementation_guide/phase_2/sso_configuration", + "destination": "/administration/authentication/single_sign_on" + }, + { + "source": "/implementation_guide/phase_2/sso_configuration/entra_id_setup", + "destination": "/administration/authentication/single_sign_on" + }, + { + "source": "/implementation_guide/phase_2/sso_configuration/okta_setup", + "destination": "/administration/authentication/single_sign_on" + }, + { + "source": "/kosli-logo-dark-main.svg", + "destination": "/logo/kosli-logo-dark-main.svg" } ] diff --git a/tutorials/working_with_controls.mdx b/tutorials/working_with_controls.mdx index 7851571..d19be6b 100644 --- a/tutorials/working_with_controls.mdx +++ b/tutorials/working_with_controls.mdx @@ -21,7 +21,7 @@ This tutorial covers how to: ## Prerequisites - [Install Kosli CLI](/getting_started/install). -- [Get a Kosli API token](/getting_started/service-accounts). +- [Get a Kosli API token](/getting_started/authenticating_to_kosli). - Have at least one [Flow](/getting_started/flows) and [Trail](/getting_started/trails) already created. ## Setup From 03b83ae5b761d21e06f845b041ad18870b701dbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:15:28 +0200 Subject: [PATCH 2/4] docs: sentence-case nav labels and dissolve redundant groups Phase 0 of #393, part of #394. Navigation labels and shape only: no page files move, no URLs change, no redirects needed. scripts/audit_navigation.py goes from 32 shape findings to 3, with integrity clean and the page count unchanged at 207. Dissolve 14 groups that wrapped a single entry and returned nothing for the click, promoting their children in place: - Documentation > Tutorials: Evaluation, Multi-flow workflows, Controls, Repositories, and Security > Detecting Terraform drift (which was also 3 containers below its tab, over the limit of 2) - Documentation > FAQ - Documentation > Administration: Managing Environments and Managing Custom Attestation Types, whose group labels duplicated the page titles verbatim - Implementation Guide: Roles & Responsibilities into Phase 1, and Plan Organizational Structure into Phase 2 - Reference: GitHub Action, Provider, Templates, and Helm Charts (which also fixes Kubernetes Reporter being 3 containers deep) - Changelog > Changelog: the tab now points at changelog/index directly Sentence-case the remaining Title Case labels per CLAUDE.md, keeping the existing `&` convention from Users & roles. Because dissolving the two Administration groups promotes their pages into the sidebar, sentence-case those page titles too, plus Managing Tags alongside them. Heading slugs are lowercased, so no anchor changes. Three findings are left deliberately: - Implementation Guide > Phase 2: configure Kosli wraps one group, but both labels carry meaning and the pages under it are titled only "Overview", "Attestation Types" and "Flows and Trails". - Reference > Terraform Reference > List resources parallels Resources and Data sources in the provider's own taxonomy, and will gain siblings. - Inconsistent tab icons are left to Phase 1 (#395), which decides the final tab set. Reference > CLI Reference is untouched: update-cli-nav.py regenerates that subtree from the CLI command tree on every release. --- .../overview.md | 2 +- .../managing_environments/overview.md | 2 +- administration/managing_tags.md | 2 +- config/navigation.json | 152 +++++------------- 4 files changed, 41 insertions(+), 117 deletions(-) diff --git a/administration/managing_custom_attestation_types/overview.md b/administration/managing_custom_attestation_types/overview.md index 24bf01a..166b23d 100644 --- a/administration/managing_custom_attestation_types/overview.md +++ b/administration/managing_custom_attestation_types/overview.md @@ -1,5 +1,5 @@ --- -title: Managing Custom Attestation Types +title: Managing custom attestation types description: Learn how to manage Kosli custom attestation types via Terraform, including creating and importing types with JSON Schema, jq evaluation rules, and summaries. --- diff --git a/administration/managing_environments/overview.md b/administration/managing_environments/overview.md index 5727f0b..72b2898 100644 --- a/administration/managing_environments/overview.md +++ b/administration/managing_environments/overview.md @@ -1,5 +1,5 @@ --- -title: Managing Environments +title: Managing environments description: Learn how to manage Kosli environments via Terraform, including creating and importing physical and logical environments. --- diff --git a/administration/managing_tags.md b/administration/managing_tags.md index dce25bc..5fdb112 100644 --- a/administration/managing_tags.md +++ b/administration/managing_tags.md @@ -1,5 +1,5 @@ --- -title: Managing Tags +title: Managing tags description: Use tags to label and organize Kosli resources with custom key-value pairs via Terraform, CLI, or API. --- diff --git a/config/navigation.json b/config/navigation.json index a536cb5..e463854 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -60,18 +60,8 @@ "administration/managing_users/automated_user_provisioning" ] }, - { - "group": "Managing Environments", - "pages": [ - "administration/managing_environments/overview" - ] - }, - { - "group": "Managing Custom Attestation Types", - "pages": [ - "administration/managing_custom_attestation_types/overview" - ] - }, + "administration/managing_environments/overview", + "administration/managing_custom_attestation_types/overview", "administration/managing_tags" ] }, @@ -116,40 +106,15 @@ { "group": "Security", "pages": [ - { - "group": "Detecting Terraform drift", - "pages": [ - "tutorials/detecting_unexpected_statefile_changes", - "tutorials/detecting_non_terraform_changes" - ] - }, + "tutorials/detecting_unexpected_statefile_changes", + "tutorials/detecting_non_terraform_changes", "tutorials/rotating_api_keys" ] }, - { - "group": "Evaluation", - "pages": [ - "tutorials/evaluate_trails_with_opa" - ] - }, - { - "group": "Multi-flow workflows", - "pages": [ - "tutorials/linking_trails_across_branches" - ] - }, - { - "group": "Controls", - "pages": [ - "tutorials/working_with_controls" - ] - }, - { - "group": "Repositories", - "pages": [ - "tutorials/repositories" - ] - } + "tutorials/evaluate_trails_with_opa", + "tutorials/linking_trails_across_branches", + "tutorials/working_with_controls", + "tutorials/repositories" ] }, { @@ -165,13 +130,7 @@ "troubleshooting/whitespace_path" ] }, - { - "group": "FAQ", - "icon": "circle-question", - "pages": [ - "faq/faq" - ] - }, + "faq/faq", { "group": "Integrations", "icon": "puzzle-piece", @@ -190,7 +149,7 @@ "tab": "Labs", "groups": [ { - "group": "Kosli Learning Labs", + "group": "Kosli learning labs", "pages": [ "labs/index", "labs/lab-01-get-ready", @@ -206,36 +165,26 @@ "tab": "Implementation Guide", "groups": [ { - "group": "Phase 1: Initial Discovery", + "group": "Phase 1: initial discovery", "icon": "lightbulb", "pages": [ - { - "group": "Roles & Responsibilities", - "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" - ] - } + "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" ] }, { - "group": "Phase 2: Configure Kosli", + "group": "Phase 2: configure Kosli", "icon": "gear", "pages": [ { - "group": "Plan Organizational Structure", + "group": "Naming conventions", "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" - ] - } + "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" ] } ] @@ -466,24 +415,14 @@ "item": "GitHub Action Reference", "icon": "github", "groups": [ - { - "group": "GitHub Action", - "pages": [ - "github-action-reference/setup_cli_action" - ] - } + "github-action-reference/setup_cli_action" ] }, { "item": "Terraform Reference", "icon": "cubes", "groups": [ - { - "group": "Provider", - "pages": [ - "terraform-reference/index" - ] - }, + "terraform-reference/index", { "group": "Resources", "pages": [ @@ -500,7 +439,7 @@ ] }, { - "group": "Data Sources", + "group": "Data sources", "pages": [ "terraform-reference/data-sources/environment", "terraform-reference/data-sources/logical_environment", @@ -513,7 +452,7 @@ ] }, { - "group": "List Resources", + "group": "List resources", "pages": [ "terraform-reference/list-resources/control" ] @@ -525,21 +464,16 @@ "icon": "layer-group", "groups": [ { - "group": "Helm Charts", - "pages": [ - { - "group": "Kubernetes Reporter", - "pages": [ - "helm/k8s_reporter/overview", - "helm/k8s_reporter/prerequisites", - "helm/k8s_reporter/installing", - "helm/k8s_reporter/upgrading", - "helm/k8s_reporter/uninstalling", - "helm/k8s_reporter/tls-proxy", - "helm/k8s_reporter/karpenter", - "helm/k8s_reporter/configuration" - ] - } + "group": "Kubernetes reporter", + "pages": [ + "helm/k8s_reporter/overview", + "helm/k8s_reporter/prerequisites", + "helm/k8s_reporter/installing", + "helm/k8s_reporter/upgrading", + "helm/k8s_reporter/uninstalling", + "helm/k8s_reporter/tls-proxy", + "helm/k8s_reporter/karpenter", + "helm/k8s_reporter/configuration" ] } ] @@ -548,12 +482,7 @@ "item": "Template Reference", "icon": "file-code", "groups": [ - { - "group": "Templates", - "pages": [ - "template-reference/flow_template" - ] - } + "template-reference/flow_template" ] }, { @@ -575,13 +504,8 @@ { "tab": "Changelog", "icon": "clock", - "groups": [ - { - "group": "Changelog", - "pages": [ - "changelog/index" - ] - } + "pages": [ + "changelog/index" ] } ] From 268720f5f16165ef867376bfc572126a1ca8b37a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:31:58 +0200 Subject: [PATCH 3/4] fix: use pages arrays where a dissolved group left a bare page string Addresses the doc-review findings on #400. A Mintlify `groups` array holds group objects; only a `pages` array accepts bare page paths alongside nested groups. Four dissolves in the previous commit left a page string inside a `groups` array, so `faq/faq`, `github-action-reference/setup_cli_action`, `terraform-reference/index` and `template-reference/flow_template` sat in a container that cannot hold them. The Changelog tab was converted from `groups` to `pages` correctly; this applies the same shape to the other three containers. Nested group objects are valid inside `pages`, so nothing else moves. Nothing caught this: audit_navigation.py walks `groups` and `pages` identically (scripts/audit_navigation.py:87-96), so all four pages still counted toward the 207 total and --check stayed green, and both mint broken-links and the Mintlify preview build passed. Terraform Reference keeps its `Provider` group rather than being converted. Provider / Resources / Data sources / List resources is the provider's own taxonomy - the same reason List resources is kept - and dissolving it would have promoted an agent-synced Title Case title, "Kosli Terraform Provider", into the sidebar. terraform-reference/ is synced from kosli-dev/terraform-provider-kosli, so editing that title here would drift. Two page titles that dissolving did promote into the sidebar: - template-reference/flow_template: "Flow Template" -> "Flow template", replacing the sentence-case group label `Templates` it inherited from. - github-action-reference/setup_cli_action needs no change; its title, "GitHub Action", is the label its group already used. Also restore the FAQ icon that the dissolve dropped, as `icon: circle-question` in faq/faq.md front matter, so it does not render as the one bare link among the Documentation tab's icon-bearing groups. --- config/navigation.json | 13 +++++++++---- faq/faq.md | 1 + template-reference/flow_template.md | 2 +- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/config/navigation.json b/config/navigation.json index e463854..4886be2 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -2,7 +2,7 @@ "tabs": [ { "tab": "Documentation", - "groups": [ + "pages": [ { "group": "Understand Kosli", "icon": "book-open", @@ -414,7 +414,7 @@ { "item": "GitHub Action Reference", "icon": "github", - "groups": [ + "pages": [ "github-action-reference/setup_cli_action" ] }, @@ -422,7 +422,12 @@ "item": "Terraform Reference", "icon": "cubes", "groups": [ - "terraform-reference/index", + { + "group": "Provider", + "pages": [ + "terraform-reference/index" + ] + }, { "group": "Resources", "pages": [ @@ -481,7 +486,7 @@ { "item": "Template Reference", "icon": "file-code", - "groups": [ + "pages": [ "template-reference/flow_template" ] }, diff --git a/faq/faq.md b/faq/faq.md index 2ad79cf..ba1a90f 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -1,6 +1,7 @@ --- title: FAQ description: "Frequently asked questions" +icon: circle-question --- diff --git a/template-reference/flow_template.md b/template-reference/flow_template.md index b4b46c9..b68a11b 100644 --- a/template-reference/flow_template.md +++ b/template-reference/flow_template.md @@ -1,5 +1,5 @@ --- -title: Flow Template +title: Flow template description: "Reference for the YAML template file used to define compliance controls for a Kosli flow." --- From d73b9d5e7792adc7e5100e628eb5b5747aacfb0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 10 Sep 2026 16:51:56 +0200 Subject: [PATCH 4/4] docs: retitle the Phase 1 overview and fix a stale link text Addresses the remaining doc-review findings on #400. Dissolving `Roles & Responsibilities` promoted a page titled just "Overview" to lead `Phase 1: initial discovery`, which is the opposite call from Phase 2 in the same commit, where the meaningful inner label was kept. Retitle the page to "Roles and responsibilities" so the label survives without restoring the group. Also update the link text in getting_started/environments.md, which named the page by its old Title Case title, "Managing Tags". --- getting_started/environments.md | 2 +- .../phase_1/roles_and_responsibilities/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/getting_started/environments.md b/getting_started/environments.md index ed8723f..bd4283b 100644 --- a/getting_started/environments.md +++ b/getting_started/environments.md @@ -108,7 +108,7 @@ kosli tag env production-k8s \ Tags can also be referenced in [Environment Policy](/getting_started/policies) expressions to make attestation requirements conditional — for example, requiring security scans only for flows tagged `risk-level=high`. -For the full guide on managing tags, recommended patterns, and usage in policies, see [Managing Tags](/administration/managing_tags). +For the full guide on managing tags, recommended patterns, and usage in policies, see [Managing tags](/administration/managing_tags). ## Logical Environments diff --git a/implementation_guide/phase_1/roles_and_responsibilities/overview.md b/implementation_guide/phase_1/roles_and_responsibilities/overview.md index cc30634..e47eea4 100644 --- a/implementation_guide/phase_1/roles_and_responsibilities/overview.md +++ b/implementation_guide/phase_1/roles_and_responsibilities/overview.md @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Roles and responsibilities" description: "Define roles and responsibilities for Kosli implementation" ---