From c066dc283452263e97140c19404ef58203fff755 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Jun 2026 09:10:16 +0200 Subject: [PATCH 1/5] docs: enforce american spelling and fix british variants Replace british spellings (organisation, behaviour, colour, standardised) with american equivalents across published docs. Add a Vale substitution rule at styles/Kosli/AmericanSpelling.yml covering the words that currently appear in the docs, plus a note in CLAUDE.md pointing to it. --- .vale.ini | 3 +++ CLAUDE.md | 1 + README.md | 2 +- changelog/index.mdx | 4 ++-- styles/Kosli/AmericanSpelling.yml | 17 +++++++++++++++++ tutorials/cli_and_http_proxy.md | 2 +- tutorials/custom-attestation-ctrf.md | 4 ++-- tutorials/evaluate_trails_with_opa.mdx | 4 ++-- ...wing_a_git_commit_to_runtime_environments.md | 2 +- tutorials/organizing_with_spaces.mdx | 2 +- tutorials/report_cloud_run_envs.md | 2 +- ...a_production_incident_back_to_git_commits.md | 4 ++-- 12 files changed, 34 insertions(+), 13 deletions(-) create mode 100644 styles/Kosli/AmericanSpelling.yml diff --git a/.vale.ini b/.vale.ini index 9acad25..5d5720d 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,2 +1,5 @@ StylesPath = styles Vocab = Mintlify + +[*.md] +BasedOnStyles = Kosli diff --git a/CLAUDE.md b/CLAUDE.md index f09af78..2e74e08 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,6 +86,7 @@ description: One sentence describing the page purpose. - Use active voice and imperative mood for instructions ("Run `kosli attest`", not "You should run"). - Refer to the product as **Kosli** — not "the Kosli platform" or "KOSLI". - Use "audit trail" not "audit log"; "attest" not "certify". +- Use American spelling (organization, behavior, color), not British. Enforced by Vale via `styles/Kosli/AmericanSpelling.yml`. - Sentence case for all headings. ## Don'ts diff --git a/README.md b/README.md index 619f14a..dcaebe9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Other useful commands: ```bash mint broken-links # Validate all internal links -mint a11y # Check colour contrast and accessibility +mint a11y # Check color contrast and accessibility mint update # Update the mint CLI tool ``` diff --git a/changelog/index.mdx b/changelog/index.mdx index 28f49b4..4fac8c2 100644 --- a/changelog/index.mdx +++ b/changelog/index.mdx @@ -8,7 +8,7 @@ rss: true ## New features -- **Default organisation on user profile** — pick a default organisation from a dropdown on your [profile settings page](https://app.kosli.com/settings/profile) so the Kosli app opens to it on sign-in. +- **Default organization on user profile** — pick a default organization from a dropdown on your [profile settings page](https://app.kosli.com/settings/profile) so the Kosli app opens to it on sign-in. ## Updates @@ -261,7 +261,7 @@ rss: true ## New features -- **`--assert` / `--no-assert` for evaluate commands** — `kosli evaluate trail`, `kosli evaluate trails`, and `kosli evaluate input` now accept a mutually-exclusive `--assert` / `--no-assert` flag pair. Pass `--no-assert` to use these commands as a policy decision point: the verdict is printed and the command exits 0, leaving any assertion to a downstream step. Default behaviour is unchanged — a policy deny still exits non-zero. These commands are now marked `[BETA]`. See the [evaluate trail](/client_reference/kosli_evaluate_trail), [evaluate trails](/client_reference/kosli_evaluate_trails), and [evaluate input](/client_reference/kosli_evaluate_input) references. +- **`--assert` / `--no-assert` for evaluate commands** — `kosli evaluate trail`, `kosli evaluate trails`, and `kosli evaluate input` now accept a mutually-exclusive `--assert` / `--no-assert` flag pair. Pass `--no-assert` to use these commands as a policy decision point: the verdict is printed and the command exits 0, leaving any assertion to a downstream step. Default behavior is unchanged — a policy deny still exits non-zero. These commands are now marked `[BETA]`. See the [evaluate trail](/client_reference/kosli_evaluate_trail), [evaluate trails](/client_reference/kosli_evaluate_trails), and [evaluate input](/client_reference/kosli_evaluate_input) references. ## Updates diff --git a/styles/Kosli/AmericanSpelling.yml b/styles/Kosli/AmericanSpelling.yml new file mode 100644 index 0000000..580ff2c --- /dev/null +++ b/styles/Kosli/AmericanSpelling.yml @@ -0,0 +1,17 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: true +level: error +swap: + organisation: organization + organisations: organizations + organise: organize + organised: organized + organising: organizing + behaviour: behavior + behaviours: behaviors + colour: color + colours: colors + standardise: standardize + standardised: standardized + standardising: standardizing diff --git a/tutorials/cli_and_http_proxy.md b/tutorials/cli_and_http_proxy.md index e05418f..c581e35 100644 --- a/tutorials/cli_and_http_proxy.md +++ b/tutorials/cli_and_http_proxy.md @@ -155,4 +155,4 @@ These two connections must be configured independently. ## What you've accomplished -You have set up Tinyproxy as an HTTP proxy and configured the Kosli CLI to route all traffic through it. This pattern works with any HTTP proxy — replace `http://localhost:8888` with your organisation's proxy URL and run `kosli config --http-proxy=` to apply it globally. +You have set up Tinyproxy as an HTTP proxy and configured the Kosli CLI to route all traffic through it. This pattern works with any HTTP proxy — replace `http://localhost:8888` with your organization's proxy URL and run `kosli config --http-proxy=` to apply it globally. diff --git a/tutorials/custom-attestation-ctrf.md b/tutorials/custom-attestation-ctrf.md index fbb51c5..07c0e00 100644 --- a/tutorials/custom-attestation-ctrf.md +++ b/tutorials/custom-attestation-ctrf.md @@ -3,7 +3,7 @@ title: "Creating custom CTRF attestation type" description: "In this tutorial, we will create a custom attestation type with schema and evaluation for Common Test Report Format" --- -In this tutorial, we will create a custom attestation type for CTRF. +In this tutorial, we will create a custom attestation type for CTRF. By the end, you will have a reusable `ctrf` attestation type in Kosli that validates test reports and enforces a zero-failures compliance rule. ## Prerequisites @@ -56,7 +56,7 @@ Kosli will validate `ctrf-report.json` against the schema and evaluate the jq ru ## What you've accomplished -You have created a reusable `ctrf` custom attestation type and used it to report a test result to Kosli. Any team in your organisation can now use this same type to uniformly enforce a zero-failures quality gate across all projects, regardless of which testing framework they use. +You have created a reusable `ctrf` custom attestation type and used it to report a test result to Kosli. Any team in your organization can now use this same type to uniformly enforce a zero-failures quality gate across all projects, regardless of which testing framework they use. From here you can: * Read the [`kosli create attestation-type`](/client_reference/kosli_create_attestation-type) reference for all available options diff --git a/tutorials/evaluate_trails_with_opa.mdx b/tutorials/evaluate_trails_with_opa.mdx index 79d643e..a3796b1 100644 --- a/tutorials/evaluate_trails_with_opa.mdx +++ b/tutorials/evaluate_trails_with_opa.mdx @@ -90,7 +90,7 @@ With the safe pattern, if `pull_requests` is undefined, `every pr in ...` fails `violations` explains why a policy was denied -- it does not decide whether it was denied. When a `violations` rule body encounters an undefined reference, it silently produces no message. This is the safe failure mode: you lose a diagnostic, not a compliance check. -See the [Rego Policy reference](/policy-reference/rego_policy) for the full policy contract, input data shape, and exit code behaviour. +See the [Rego Policy reference](/policy-reference/rego_policy) for the full policy contract, input data shape, and exit code behavior. @@ -250,7 +250,7 @@ violations contains msg if { **Why the aliases at the top matter** -`max_high := data.params.max_high` is not just shorthand. In the compliance path, `result.high_count <= max_high` is a positive bound check. If `max_high` is absent from the params file, this condition is undefined, `artifact_within_threshold` fails to fire, and `allow` stays `false`. That is the correct fail-safe behaviour. +`max_high := data.params.max_high` is not just shorthand. In the compliance path, `result.high_count <= max_high` is a positive bound check. If `max_high` is absent from the params file, this condition is undefined, `artifact_within_threshold` fails to fire, and `allow` stays `false`. That is the correct fail-safe behavior. Compare this to a policy that drives `allow` through the absence of violations: diff --git a/tutorials/following_a_git_commit_to_runtime_environments.md b/tutorials/following_a_git_commit_to_runtime_environments.md index 610d6ea..a23c028 100644 --- a/tutorials/following_a_git_commit_to_runtime_environments.md +++ b/tutorials/following_a_git_commit_to_runtime_environments.md @@ -20,7 +20,7 @@ The commit we follow fixed a misconfiguration: `runner` should run with three re ## Setup -Set your environment variables to use the public `cyber-dojo` Kosli organisation: +Set your environment variables to use the public `cyber-dojo` Kosli organization: ```shell export KOSLI_ORG=cyber-dojo diff --git a/tutorials/organizing_with_spaces.mdx b/tutorials/organizing_with_spaces.mdx index 26dde44..cd09d92 100644 --- a/tutorials/organizing_with_spaces.mdx +++ b/tutorials/organizing_with_spaces.mdx @@ -44,7 +44,7 @@ Acme Bank In this structure: -- **Acme Bank** is the organisation, also referred to as the "root space" +- **Acme Bank** is the organization, also referred to as the "root space" - **Investment Banking** and **Technology Services** are major divisions represented by Spaces - Each division contains business units (Trading Systems, Platform Engineering), also represented by nested spaces - **Trade Execution Platform** and **DevOps** are a project and a team, also nested spaces within the business units diff --git a/tutorials/report_cloud_run_envs.md b/tutorials/report_cloud_run_envs.md index 331e9eb..1359767 100644 --- a/tutorials/report_cloud_run_envs.md +++ b/tutorials/report_cloud_run_envs.md @@ -131,7 +131,7 @@ gcloud run jobs deploy kosli-reporter \ ``` -Pin the CLI image to a specific version (for example `ghcr.io/kosli-dev/cli:v2.18.0`) so the reporter behaviour does not change unexpectedly when a new release is published. +Pin the CLI image to a specific version (for example `ghcr.io/kosli-dev/cli:v2.18.0`) so the reporter behavior does not change unexpectedly when a new release is published. diff --git a/tutorials/tracing_a_production_incident_back_to_git_commits.md b/tutorials/tracing_a_production_incident_back_to_git_commits.md index cec611d..e7cbeb6 100644 --- a/tutorials/tracing_a_production_incident_back_to_git_commits.md +++ b/tutorials/tracing_a_production_incident_back_to_git_commits.md @@ -3,7 +3,7 @@ title: Tracing a production incident to its git commit description: "Learn how to use Kosli to trace a production 500 error in cyber-dojo back to the specific git commit that caused it — without any access to the production environment." --- -By the end of this tutorial, you will have traced a production incident from a 500 error all the way back to the git commit that caused it, using only Kosli CLI queries against the public cyber-dojo organisation. +By the end of this tutorial, you will have traced a production incident from a 500 error all the way back to the git commit that caused it, using only Kosli CLI queries against the public cyber-dojo organization. Prod cyber-dojo is down with a 500 @@ -16,7 +16,7 @@ By the end of this tutorial, you will have traced a production incident from a 5 ## Setup -The `cyber-dojo` Kosli organisation is public, so any authenticated user can read its data: +The `cyber-dojo` Kosli organization is public, so any authenticated user can read its data: ```shell export KOSLI_ORG=cyber-dojo From 3435664e3fed3111878176efc277a43ab9731ddd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Jun 2026 09:19:33 +0200 Subject: [PATCH 2/5] test: intentional typo to verify vale CI catches it --- understand_kosli/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/understand_kosli/glossary.md b/understand_kosli/glossary.md index 8a8d33c..16137a1 100644 --- a/understand_kosli/glossary.md +++ b/understand_kosli/glossary.md @@ -51,7 +51,7 @@ The compliance definition for a Flow. It specifies the artifacts and attestation ### Organization -The account that owns Kosli resources (Flows, Environments, Policies). Most teams work within a shared organization that maps to their company. Members are invited with specific roles that control access. +The account that owns Kosli resources (Flows, Environments, Policies). Most teams work within a shared organisation that maps to their company. Members are invited with specific roles that control access. ### Risk From c188713f0584891bd7f59251b32967c11961325f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Jun 2026 09:23:17 +0200 Subject: [PATCH 3/5] test: intentional typo in mdx to verify vale catches mdx files --- tutorials/organizing_with_spaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/organizing_with_spaces.mdx b/tutorials/organizing_with_spaces.mdx index cd09d92..6b7bb5b 100644 --- a/tutorials/organizing_with_spaces.mdx +++ b/tutorials/organizing_with_spaces.mdx @@ -5,7 +5,7 @@ description: Learn how to use Kosli Spaces to hierarchically organize your Flows ## Introduction -Spaces addresses a scaling challenge facing large organizations as they attempt to fully automate software delivery governance. Ingesting large amounts of data from hundreds of sources — CI/CD pipelines, security scanners, test frameworks, deployment tools — means that it becomes increasingly difficult for different stakeholders to access the information they need. +Spaces addresses a scaling challenge facing large organisations as they attempt to fully automate software delivery governance. Ingesting large amounts of data from hundreds of sources — CI/CD pipelines, security scanners, test frameworks, deployment tools — means that it becomes increasingly difficult for different stakeholders to access the information they need. Kosli Spaces allows users to: From 0b2c3c40cf368b234e8c77693934c6e1bdb81e9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Jun 2026 09:26:08 +0200 Subject: [PATCH 4/5] test: extend vale scope to mdx files --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 5d5720d..341cd87 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,5 @@ StylesPath = styles Vocab = Mintlify -[*.md] +[*.{md,mdx}] BasedOnStyles = Kosli From 22efd5864770f18cda290f32d9e73e547d6f3cc8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 3 Jun 2026 09:27:32 +0200 Subject: [PATCH 5/5] test: revert intentional typos after verifying vale catches md and mdx --- tutorials/organizing_with_spaces.mdx | 2 +- understand_kosli/glossary.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/organizing_with_spaces.mdx b/tutorials/organizing_with_spaces.mdx index 6b7bb5b..cd09d92 100644 --- a/tutorials/organizing_with_spaces.mdx +++ b/tutorials/organizing_with_spaces.mdx @@ -5,7 +5,7 @@ description: Learn how to use Kosli Spaces to hierarchically organize your Flows ## Introduction -Spaces addresses a scaling challenge facing large organisations as they attempt to fully automate software delivery governance. Ingesting large amounts of data from hundreds of sources — CI/CD pipelines, security scanners, test frameworks, deployment tools — means that it becomes increasingly difficult for different stakeholders to access the information they need. +Spaces addresses a scaling challenge facing large organizations as they attempt to fully automate software delivery governance. Ingesting large amounts of data from hundreds of sources — CI/CD pipelines, security scanners, test frameworks, deployment tools — means that it becomes increasingly difficult for different stakeholders to access the information they need. Kosli Spaces allows users to: diff --git a/understand_kosli/glossary.md b/understand_kosli/glossary.md index 16137a1..8a8d33c 100644 --- a/understand_kosli/glossary.md +++ b/understand_kosli/glossary.md @@ -51,7 +51,7 @@ The compliance definition for a Flow. It specifies the artifacts and attestation ### Organization -The account that owns Kosli resources (Flows, Environments, Policies). Most teams work within a shared organisation that maps to their company. Members are invited with specific roles that control access. +The account that owns Kosli resources (Flows, Environments, Policies). Most teams work within a shared organization that maps to their company. Members are invited with specific roles that control access. ### Risk