website/content/docs/getting-started/setup-controller-environment.md (1)

236-243: Make expected Helm output less version-specific to reduce doc churn.

Since the command does not pin a chart version, fixed version/digest/timestamp values can age quickly.

Suggested resilient output wording

-<summary>You should see this output</summary>
+<summary>You should see similar output (version, digest, and timestamp may differ)</summary>

 ```text
-Pulled: ghcr.io/open-component-model/kubernetes/controller/chart:0.4.0
-Digest: sha256:eac0dc587a1d288f36ef1961bb69f0ffb2791e0153f86d1fdbe54ae2f36f1194
+Pulled: ghcr.io/open-component-model/kubernetes/controller/chart:<resolved-version>
+Digest: sha256:<resolved-digest>
 NAME: ocm-k8s-toolkit
-LAST DEPLOYED: Tue Apr 28 17:42:51 2026
+LAST DEPLOYED: <current-date-time>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @website/content/docs/getting-started/setup-controller-environment.md around
lines 236 - 243, Replace the version-, digest-, and timestamp-specific Helm
output in the "You should see this output" example with generic placeholders so
the doc doesn’t age; specifically update the Pulled line (currently referencing
chart:0.4.0) to use chart:, the Digest line to
sha256:, and the LAST DEPLOYED line to
(keep NAME: ocm-k8s-toolkit as-is) in the example block in
setup-controller-environment.md so the output stays resilient when the chart is
not pinned.

</details>

</blockquote></details>
<details>
<summary>website/content/docs/how-to/verify-component-version-controller.md (2)</summary><blockquote>

`232-244`: **Use “Symptom contains” wording to match wrapped controller errors.**

These messages are typically prefixes in logs (followed by extra context). Wording them as exact strings can mislead copy/paste troubleshooting.


<details>
<summary>Proposed doc wording tweak</summary>

```diff
-### Symptom: "signature verification failed for signature default"
+### Symptom contains: `signature verification failed for signature default:`

 ...
-### Symptom: "signature default not found in component"
+### Symptom contains: `signature default not found in component`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@website/content/docs/how-to/verify-component-version-controller.md` around
lines 232 - 244, Update the two symptom headings and any exact-match example
phrases so they indicate partial/wrapped log matching by using "Symptom
contains: ..." instead of exact quoted strings; specifically change the headings
currently showing "signature verification failed for signature default" and
"signature default not found in component" to "Symptom contains: 'signature
verification failed for signature default'" and "Symptom contains: 'signature
default not found in component'", and update the surrounding guidance (including
the `verify` configuration mention and the `ocm get cv ...` example) to state
these are prefix/contains matches for wrapped controller errors rather than
exact strings.

---

230-273: Consider adding a digest-verification troubleshooting entry.

You already document signature and secret failures; adding the digest-failure case would complete the common controller verification errors.

Suggested section addition

 ## Troubleshooting

+### Symptom contains: `digest verification failed for signature "default"`
+
+**Cause:** The signed descriptor content no longer matches the digest embedded in the signature payload.
+
+**Fix:** Recreate/sign the component version after descriptor changes, transfer it again, and ensure the referenced version is the newly signed one.
+
 ### Symptom: "signature verification failed for signature default"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@website/content/docs/how-to/verify-component-version-controller.md` around
lines 230 - 273, Add a troubleshooting entry for digest verification failures:
describe the symptom (e.g., "digest verification failed" or "manifest digest
mismatch"), explain the cause (the component's recorded digest doesn't match the
actual artifact digest or the `digest` field in the `verify` configuration is
wrong), and give concise remediation steps referencing the `verify`
configuration, the `digest` field, and the ComponentVersion (CV) output from
`ocm get cv ... -o yaml` to inspect the recorded digest and `signatures:` block;
include instructions to fetch the artifact's actual digest from the registry
(e.g., using an image inspection tool) and to update either the `verify.digest`
value or the component's published metadata so the digests match.