content/docs/concepts/ocm-controllers.md (1)

7-7: Optional: hasMermaid flag is auto-set.

The hasMermaid: true flag is automatically set by the render-codeblock-mermaid.html template when Mermaid code blocks are rendered (see the relevant code snippet). Including it in frontmatter is redundant but harmless—it can serve as documentation that the page contains diagrams.

🤖 Prompt for AI Agents

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

In `@content/docs/concepts/ocm-controllers.md` at line 7, Remove the redundant
frontmatter key `hasMermaid: true` from the document (it's auto-set by the
`render-codeblock-mermaid.html` template) — open the file containing the
`hasMermaid` frontmatter entry, delete that line so the page relies on the
template to set the flag, and leave a brief inline comment only if you want to
document that the template auto-sets the flag for Mermaid diagrams.

content/docs/concepts/deployer.md (1)

36-38: Optional: Consider more concise wording.

The phrase "In order to get to a deployment" could be simplified to "To reach deployment" for conciseness, though the current wording is not incorrect.

🤖 Prompt for AI Agents

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

In `@content/docs/concepts/deployer.md` around lines 36 - 38, The opening sentence
is wordy—replace "In order to get to a deployment the following chain of objects
has to be reconciled." with a more concise phrasing like "To reach deployment,
the following chain of objects must be reconciled:" and keep the rest of the
paragraph intact; update the sentence that references Repository, Component,
Resource, and Deployer to maintain clarity and punctuation (use a colon after
the concise sentence and ensure the object chain is exactly "Repository ->
Component -> Resource -> Deployer").

content/docs/tutorials/deploy-with-controllers.md (3)

381-381: Add a cautionary note about insecure: true flag.

Setting insecure: true in the OCIRepository spec disables TLS verification and should only be used for local testing or development environments. This could be misleading for users following the tutorial in production settings.

⚠️ Proposed addition of a warning callout

Add a callout after line 388 (before the helmrelease section):

{{<callout context="caution" title="Insecure Registry" icon="outline/alert-triangle">}}
The `insecure: true` flag is set for local testing only. Remove this flag when using TLS-enabled registries in production.
{{</callout>}}

🤖 Prompt for AI Agents

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

In `@content/docs/tutorials/deploy-with-controllers.md` at line 381, Add a
cautionary callout near the OCIRepository spec where the insecure: true flag is
set: insert a warning callout mentioning "Insecure Registry" and that insecure:
true is for local testing only and must be removed for TLS-enabled registries in
production; place this callout immediately before the HelmRelease section
referenced in the doc so readers see it right after the OCIRepository example
that includes insecure: true.

---

34-34: Minor style improvement: simplify "outside of" to "outside".

The phrase "outside of" is slightly redundant in this context.

✏️ Proposed fix

-In this approach, you create the `ResourceGraphDefinition` outside of the OCM component and apply it directly to the cluster.
+In this approach, you create the `ResourceGraphDefinition` outside the OCM component and apply it directly to the cluster.

🤖 Prompt for AI Agents

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

In `@content/docs/tutorials/deploy-with-controllers.md` at line 34, Replace the
phrase "outside of the OCM component" with the simpler "outside the OCM
component" in the sentence that references creating the ResourceGraphDefinition;
locate the sentence containing `ResourceGraphDefinition` and update that wording
to use "outside" instead of "outside of" for the minor style improvement.

---

405-405: Reconsider combining tag and digest in a single Helm values field.

The OCI reference format tag@digest is valid per the image specification and is supported in this project's documentation. However, storing both tag and digest in a single tag field (as ${resourceImage.status.additional.tag}@${resourceImage.status.additional.digest}) deviates from Helm best practices.

The recommended approach is to use separate fields for flexibility:

• Separate tag and digest fields in values, or
• Use a unified version field that can hold either a tag (e.g., 1.0.0) or a digest (e.g., sha256:...)
• Then use a Helm template helper to construct the image reference appropriately (with : for tags, @ for digests)

This approach improves clarity, reusability, and allows easier overrides by users.

🤖 Prompt for AI Agents

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

In `@content/docs/tutorials/deploy-with-controllers.md` at line 405, The Helm
values currently combine tag and digest into one field (`tag:
${resourceImage.status.additional.tag}@${resourceImage.status.additional.digest}`);
change values to expose separate fields (e.g., values.image.tag and
values.image.digest) or a single values.image.version that may hold either a tag
or a digest, and update the chart templates (the helper used to render image
references) to construct the final reference using ":" when a tag is present and
"@" when a digest is present; update any places referencing `tag` to use the new
fields (`values.image.tag`, `values.image.digest`, or `values.image.version`)
and adjust the helper/template that currently consumes `tag` so image references
are built consistently.