docs: document label passthrough from catalog items to policy engine

[chadcrum]

Summary

Connects the dots across the catalog items, catalog item instances, and policies user-guide pages so policy authors understand that metadata labels must be declared as catalog item fields to reach input.spec in Rego policies.

• Added "Fields and Policy Evaluation" subsection to the Catalog Items page explaining the governance boundary
• Extended the validation note on the Catalog Item Instances page to explain how user_values flow to input.spec
• Added "How input.spec is Constructed" section and an end-to-end label policy example to the Policies page

Resolves: FLPATH-4124

🤖 Generated with Claude Code

Summary by Sourcery

Clarify how catalog item fields and instance user_values populate input.spec for policy evaluation and provide an end-to-end label-based policy example.

Documentation:

• Document how catalog item fields and instance user_values are the only sources for input.spec in Rego policies.
• Explain the governance boundary created by catalog item fields and how labels must be declared as fields to be visible to policies.
• Update catalog item instance documentation to describe how validated user_values flow into input.spec for policy evaluation.
• Add an example policy showing how instance labels propagate from catalog item definition to Rego policy input.

---

Preview: https://chadcrum.github.io/dcm-project.github.io/

Changed sections:

• Catalog Items — Fields and Policy Evaluation
• Catalog Item Instances — Key Fields (new note)
• Policies — How input.spec is Constructed
• Policies — Example: Policy Using Instance Labels

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• In the new explanations of how input.spec is built, consider explicitly stating how conflicts between catalog item default values and user_values are resolved (i.e., that user_values effectively override defaults), so policy authors aren't left to infer the precedence.
• The description of the governance boundary (“only catalog item fields are visible to policies”) is repeated across the three pages; you might centralize the full explanation in one place and keep the others shorter with a pointer to avoid future drift between them.
• In the catalog item instances note, you reference input.spec.metadata.labels.env “for the label shown above,” but the immediate example uses metadata.labels.region; aligning the example label name across sections would reduce potential confusion.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the new explanations of how `input.spec` is built, consider explicitly stating how conflicts between catalog item `default` values and `user_values` are resolved (i.e., that `user_values` effectively override defaults), so policy authors aren't left to infer the precedence.
- The description of the governance boundary (“only catalog item fields are visible to policies”) is repeated across the three pages; you might centralize the full explanation in one place and keep the others shorter with a pointer to avoid future drift between them.
- In the catalog item instances note, you reference `input.spec.metadata.labels.env` “for the label shown above,” but the immediate example uses `metadata.labels.region`; aligning the example label name across sections would reduce potential confusion.

## Individual Comments

### Comment 1
<location path="content/docs/user-guide/catalog-item-instances.md" line_range="53" />
<code_context>
+> **Note:** Each value provided in `user_values` will be validated against its corresponding item in the catalog item's `fields` list. If the `field` is not editable (`editable=false`) or the `value` does not pass the `validation_schema` the request will be rejected. After validation, these values become part of the resource spec evaluated by placement [policies](../policies/), accessible as `input.spec.*` in Rego code (e.g., `input.spec.metadata.labels.env` for the label shown above). Only fields declared in the catalog item are included; see [How `input.spec` is Constructed](../policies/#how-inputspec-is-constructed) for details.
</code_context>
<issue_to_address>
**suggestion (typo):** Add a comma before "the request will be rejected" for smoother grammar.

In this sentence, add a comma before "the request will be rejected" so it reads: "...does not pass the `validation_schema`, the request will be rejected."

```suggestion
> **Note:** Each value provided in `user_values` will be validated against its corresponding item in the catalog item's `fields` list. If the `field` is not editable (`editable=false`) or the `value` does not pass the `validation_schema`, the request will be rejected. After validation, these values become part of the resource spec evaluated by placement [policies](../policies/), accessible as `input.spec.*` in Rego code (e.g., `input.spec.metadata.labels.env` for the label shown above). Only fields declared in the catalog item are included; see [How `input.spec` is Constructed](../policies/#how-inputspec-is-constructed) for details.
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[ygalblum]

Small comment, I'm fine also if you disagree.