Release: docs: clarify --artifact-type=docker requires registry digest (#834)

* docs: clarify --artifact-type=docker requires registry digest

A customer hit "repo digest unavailable for the image, has it been
pushed to or pulled from a registry?" after kosli attest artifact with
--artifact-type=docker in CI, where the image was built but never
pushed. The constraint that the docker artifact type requires a
registry-resident image was only stated in the error itself.

Add a note to the long descriptions of attest commands (via
fingerprintDesc) and kosli fingerprint, covering the constraint and
pointing at oci and dir as alternatives.

Help-text only; no behaviour change. Auto-generated docs in
kosli-dev/docs will pick this up on the next CLI release.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: drop dir suggestion from artifact-type=docker note

Source-dir fingerprinting only works as an end-to-end identity if the
runtime side also fingerprints the source dir. Standard Kosli runtime
reporters fingerprint the running image, so suggesting dir as a generic
swap is misleading — the attested and running artifacts would never
link. Push and oci are the safe answers for the typical case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tooky

docs.kosli.com/assets/metadata.json

@@ -1 +1 @@
-{"currentversion": "v2.17.1"}
+{"currentversion": "v2.17.2"}

docs.kosli.com/content/client_reference/kosli_allow_artifact.md

@@ -15,12 +15,18 @@ kosli allow artifact [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
 
 Add an artifact to an environment's allowlist.  
 
-The artifact fingerprint can be provided directly with the `--fingerprint` flag, or 
+The artifact fingerprint can be provided directly with the `--fingerprint` flag, or
 calculated based on `--artifact-type` flag.
 
 Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container
 images in registries or "docker" for local docker images.
 
+Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon.
+The image must have been pushed to or pulled from a registry for a repo digest to exist;
+a freshly built image (just `docker build`) will not have one. If the image is already in
+a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the
+registry without needing a local Docker daemon.
+
 
 
 ## Flags

docs.kosli.com/content/client_reference/kosli_assert_approval.md

@@ -16,12 +16,18 @@ kosli assert approval [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
 Assert an artifact in Kosli has been approved for deployment.  
 Exits with non-zero code if the artifact has not been approved.  
 
-The artifact fingerprint can be provided directly with the `--fingerprint` flag, or 
+The artifact fingerprint can be provided directly with the `--fingerprint` flag, or
 calculated based on `--artifact-type` flag.
 
 Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container
 images in registries or "docker" for local docker images.
 
+Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon.
+The image must have been pushed to or pulled from a registry for a repo digest to exist;
+a freshly built image (just `docker build`) will not have one. If the image is already in
+a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the
+registry without needing a local Docker daemon.
+
 
 
 ## Flags

docs.kosli.com/content/client_reference/kosli_attest_artifact.md

@@ -15,12 +15,18 @@ kosli attest artifact {IMAGE-NAME | FILE-PATH | DIR-PATH} [flags]
 
 Attest an artifact creation to a Kosli flow.  
 
-The artifact fingerprint can be provided directly with the `--fingerprint` flag, or 
+The artifact fingerprint can be provided directly with the `--fingerprint` flag, or
 calculated based on `--artifact-type` flag.
 
 Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container
 images in registries or "docker" for local docker images.
 
+Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon.
+The image must have been pushed to or pulled from a registry for a repo digest to exist;
+a freshly built image (just `docker build`) will not have one. If the image is already in
+a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the
+registry without needing a local Docker daemon.
+
 To specify paths in a directory artifact that should always be excluded from the SHA256 calculation, you can add a `.kosli_ignore` file to the root of the artifact.
 Each line should specify a relative path or path glob to be ignored. You can include comments in this file, using `#`.
 The `.kosli_ignore` will be treated as part of the artifact like any other file, unless it is explicitly ignored itself.

docs.kosli.com/content/client_reference/kosli_create_flow.md

@@ -47,9 +47,9 @@ You can specify flow parameters in flags.
 
 {{< tabs "live-examples" "col-no-wrap" >}}{{< tab "GitHub" >}}View an example of the `kosli create flow` command in GitHub.
 
-In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bcreate%2Bflow){{< /tab >}}{{< tab "GitLab" >}}View an example of the `kosli create flow` command in GitLab.
+In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bcreate%2Bflow), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=kosli%2Bcreate%2Bflow).{{< /tab >}}{{< tab "GitLab" >}}View an example of the `kosli create flow` command in GitLab.
 
-In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Bcreate%2Bflow){{< /tab >}}{{< /tabs >}}
+In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=gitlab&command=kosli%2Bcreate%2Bflow), which created [this Kosli Event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=gitlab&command=kosli%2Bcreate%2Bflow).{{< /tab >}}{{< /tabs >}}
 
 ## Examples Use Cases
 

docs.kosli.com/content/client_reference/kosli_evaluate_input.md

@@ -2,7 +2,7 @@
 title: "kosli evaluate input"
 beta: false
 deprecated: false
-summary: "Evaluate a local JSON input against a Rego policy."
+summary: "[BETA] Evaluate a local JSON input against a Rego policy."
 ---
 
 # kosli evaluate input
@@ -13,15 +13,18 @@ summary: "Evaluate a local JSON input against a Rego policy."
 kosli evaluate input [flags]
 ```
 
-Evaluate a local JSON input against a Rego policy.
+[BETA] Evaluate a local JSON input against a Rego policy.
 Read JSON from a file or stdin and evaluate it against a Rego policy.
 The input file should contain the raw JSON object your policy expects —
 not the wrapper produced by `--show-input`. Use `jq '.input'` to extract
 the policy input from a `--show-input --output json` capture.
 
 The policy must use `package policy` and define an `allow` rule.
 An optional `violations` rule (a set of strings) can provide human-readable denial reasons.
-The command exits with code 0 when allowed and code 1 when denied.
+
+By default a deny exits with code 1. Pass `--no-assert` to print the verdict
+and exit 0 even on deny, when this command is feeding another tool as a
+policy decision point.
 
 When `--input-file` is omitted, JSON is read from stdin.
 
@@ -31,8 +34,10 @@ This accepts inline JSON or a file reference (`@file.json`).
 ## Flags
 | Flag | Description |
 | :--- | :--- |
+|        --assert  |  [optional] Exit with a non-zero status when the policy denies. This is the current default; pass --assert to lock it in across future releases.  |
 |    -h, --help  |  help for input  |
 |    -i, --input-file string  |  [optional] Path to a JSON input file. Reads from stdin if omitted.  |
+|        --no-assert  |  [optional] Print the result and always exit 0, even when the policy denies. Use when this command feeds another tool as a policy decision point.  |
 |    -o, --output string  |  [defaulted] The format of the output. Valid formats are: [table, json]. (default "table")  |
 |        --params string  |  [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params.  |
 |    -p, --policy string  |  Path to a Rego policy file to evaluate against the input.  |
@@ -109,5 +114,15 @@ kosli evaluate input
 	--input-file trail-data.json 
 	--policy policy.rego 
 	--params @params.json
+
+```
+
+##### evaluate as a decision point (print verdict, never fail the step)
+
+```shell
+kosli evaluate input 
+	--input-file trail-data.json 
+	--policy policy.rego 
+	--no-assert
 ```
 

docs.kosli.com/content/client_reference/kosli_evaluate_trail.md

@@ -2,7 +2,7 @@
 title: "kosli evaluate trail"
 beta: false
 deprecated: false
-summary: "Evaluate a trail against a policy."
+summary: "[BETA] Evaluate a trail against a policy."
 ---
 
 # kosli evaluate trail
@@ -13,7 +13,7 @@ summary: "Evaluate a trail against a policy."
 kosli evaluate trail TRAIL-NAME [flags]
 ```
 
-Evaluate a trail against a policy.
+[BETA] Evaluate a trail against a policy.
 Fetch a single trail from Kosli and evaluate it against a Rego policy.
 The trail data is passed to the policy as `input.trail`.
 
@@ -24,9 +24,11 @@ full data structure available to the policy. Use `--output json` for structured
 ## Flags
 | Flag | Description |
 | :--- | :--- |
+|        --assert  |  [optional] Exit with a non-zero status when the policy denies. This is the current default; pass --assert to lock it in across future releases.  |
 |        --attestations strings  |  [optional] Limit which attestations are included. Plain name for trail-level, dot-qualified (artifact.name) for artifact-level.  |
 |    -f, --flow string  |  The Kosli flow name.  |
 |    -h, --help  |  help for trail  |
+|        --no-assert  |  [optional] Print the result and always exit 0, even when the policy denies. Use when this command feeds another tool as a policy decision point.  |
 |    -o, --output string  |  [defaulted] The format of the output. Valid formats are: [table, json]. (default "table")  |
 |        --params string  |  [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params.  |
 |    -p, --policy string  |  Path to a Rego policy file to evaluate against the trail.  |
@@ -45,6 +47,12 @@ full data structure available to the policy. Use `--output json` for structured
 |        --org string  |  The Kosli organization.  |
 
 
+## Live Examples in different CI systems
+
+{{< tabs "live-examples" "col-no-wrap" >}}{{< tab "GitHub" >}}View an example of the `kosli evaluate trail` command in GitHub.
+
+In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=kosli%2Bevaluate%2Btrail){{< /tab >}}{{< /tabs >}}
+
 ## Examples Use Cases
 
 These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](https://docs.kosli.com/getting_started/install/#assigning-flags-via-environment-variables). 
@@ -91,5 +99,14 @@ kosli evaluate trail yourTrailName
 kosli evaluate trail yourTrailName 
 	--policy yourPolicyFile.rego 
 	--params @params.json 
+
+```
+
+##### evaluate a trail as a decision point (print verdict, never fail the step)
+
+```shell
+kosli evaluate trail yourTrailName 
+	--policy yourPolicyFile.rego 
+	--no-assert 
 ```
 

docs.kosli.com/content/client_reference/kosli_evaluate_trails.md

@@ -2,7 +2,7 @@
 title: "kosli evaluate trails"
 beta: false
 deprecated: false
-summary: "Evaluate multiple trails against a policy."
+summary: "[BETA] Evaluate multiple trails against a policy."
 ---
 
 # kosli evaluate trails
@@ -13,7 +13,7 @@ summary: "Evaluate multiple trails against a policy."
 kosli evaluate trails TRAIL-NAME [TRAIL-NAME...] [flags]
 ```
 
-Evaluate multiple trails against a policy.
+[BETA] Evaluate multiple trails against a policy.
 Fetch multiple trails from Kosli and evaluate them together against a Rego policy.
 The trail data is passed to the policy as `input.trails` (an array), unlike
 `evaluate trail` which passes `input.trail` (a single object).
@@ -25,9 +25,11 @@ full data structure available to the policy. Use `--output json` for structured
 ## Flags
 | Flag | Description |
 | :--- | :--- |
+|        --assert  |  [optional] Exit with a non-zero status when the policy denies. This is the current default; pass --assert to lock it in across future releases.  |
 |        --attestations strings  |  [optional] Limit which attestations are included. Plain name for trail-level, dot-qualified (artifact.name) for artifact-level.  |
 |    -f, --flow string  |  The Kosli flow name.  |
 |    -h, --help  |  help for trails  |
+|        --no-assert  |  [optional] Print the result and always exit 0, even when the policy denies. Use when this command feeds another tool as a policy decision point.  |
 |    -o, --output string  |  [defaulted] The format of the output. Valid formats are: [table, json]. (default "table")  |
 |        --params string  |  [optional] Policy parameters as inline JSON or @file.json. Available in policies as data.params.  |
 |    -p, --policy string  |  Path to a Rego policy file to evaluate against the trails.  |
@@ -83,5 +85,14 @@ kosli evaluate trails yourTrailName1 yourTrailName2
 kosli evaluate trails yourTrailName1 yourTrailName2 
 	--policy yourPolicyFile.rego 
 	--params '{"min_approvers": 2}' 
+
+```
+
+##### evaluate trails as a decision point (print verdict, never fail the step)
+
+```shell
+kosli evaluate trails yourTrailName1 yourTrailName2 
+	--policy yourPolicyFile.rego 
+	--no-assert 
 ```
 

docs.kosli.com/content/client_reference/kosli_fingerprint.md

@@ -21,6 +21,11 @@ images in registries or "docker" for local docker images.
 Fingerprinting container images can be done using the local docker daemon or the fingerprint can be fetched
 from a remote registry.
 
+Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon, so
+the image must have been pushed to or pulled from a registry. A freshly built image (just
+`docker build`) does not have a repo digest. For images already in a registry, prefer
+`--artifact-type=oci` to fetch the digest directly from the registry.
+
 When fingerprinting a 'dir' artifact, you can exclude certain paths from fingerprint calculation 
 using the `--exclude` flag.
 Excluded paths are relative to the DIR-PATH and can be literal paths or glob patterns.

docs.kosli.com/content/client_reference/kosli_report_approval.md

@@ -15,12 +15,18 @@ kosli report approval [IMAGE-NAME | FILE-PATH | DIR-PATH] [flags]
 
 Report an approval of deploying an artifact to an environment to Kosli.  
 
-The artifact fingerprint can be provided directly with the `--fingerprint` flag, or 
+The artifact fingerprint can be provided directly with the `--fingerprint` flag, or
 calculated based on `--artifact-type` flag.
 
 Artifact type can be one of: "file" for files, "dir" for directories, "oci" for container
 images in registries or "docker" for local docker images.
 
+Note: `--artifact-type=docker` reads the image's repo digest via the local Docker daemon.
+The image must have been pushed to or pulled from a registry for a repo digest to exist;
+a freshly built image (just `docker build`) will not have one. If the image is already in
+a registry, prefer `--artifact-type=oci`, which fetches the digest directly from the
+registry without needing a local Docker daemon.
+
 
 
 ## Flags