docs: add user guide section with CLI and entity management pages

[ygalblum]

What

Add a comprehensive User Guide documentation section covering CLI configuration and all DCM entity management operations.

Why

The existing Getting Started section provides tutorial-style walkthroughs but does not cover the full CLI surface for each entity. Users need reference documentation for managing providers, service types, catalog items, policies, instances, and service provider resources.

Changes

• Added User Guide section with index page linking to all sub-pages
• Added CLI Configuration page covering config file, global flags, TLS, output formats, and shell completion
• Added Providers page documenting read-only provider listing and details
• Added Service Types page documenting read-only service type browsing
• Added Catalog Items page covering full CRUD lifecycle with YAML examples
• Added Policies page covering full CRUD lifecycle including CEL filtering, ordering, and Rego policy structure
• Added Catalog Item Instances page covering lifecycle including rehydration
• Added Service Provider Resources page documenting read-only resource viewing with deletion status support
• Updated docs index to include the new User Guide section

Testing

No automated tests -- documentation-only changes. Verify by running hugo server and checking sidebar navigation, page rendering, and cross-reference links.

Summary by Sourcery

Add a comprehensive User Guide documentation section describing CLI configuration and core DCM entity management operations.

Documentation:

• Document CLI configuration, global flags, TLS options, output formats, and shell completion usage.
• Add reference guides for viewing providers and service types via the CLI.
• Add catalog item documentation covering creation, listing, inspection, and deletion with examples.
• Add catalog item instance documentation including creation, listing, rehydration, and deletion flows.
• Document service provider resources as read-only provider-side objects with listing, filtering, and lifecycle behavior.
• Add detailed policy documentation including Rego structure, CLI management commands, filtering, ordering, and evaluation pipeline.
• Update the main docs index to link to the new User Guide section.

[sourcery-ai]

Hey - I've found 8 issues, and left some high level feedback:

• There are a few terminology inconsistencies that may confuse users (e.g., editable_fields vs. editable, rejected_reason vs. rejection_reason, and the service type name being described as group/Kind while examples use simple values like vm); consider aligning the field names and descriptions with the actual API/CLI surface throughout the new pages.
• The Policies page states that the Rego main rule must define rejected, and either rejected_reason or selected_provider, but the example and later text use rejection_reason; please standardize on a single field name and update the field reference and examples accordingly.
• Scan the new content for small wording/formatting issues (e.g., Kubernets instead of Kubernetes, duplicate numbered steps in the Service Provider Resources lifecycle) to improve clarity and consistency across the User Guide.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- There are a few terminology inconsistencies that may confuse users (e.g., `editable_fields` vs. `editable`, `rejected_reason` vs. `rejection_reason`, and the service type name being described as `group/Kind` while examples use simple values like `vm`); consider aligning the field names and descriptions with the actual API/CLI surface throughout the new pages.
- The Policies page states that the Rego `main` rule must define `rejected`, and either `rejected_reason` or `selected_provider`, but the example and later text use `rejection_reason`; please standardize on a single field name and update the field reference and examples accordingly.
- Scan the new content for small wording/formatting issues (e.g., `Kubernets` instead of `Kubernetes`, duplicate numbered steps in the Service Provider Resources lifecycle) to improve clarity and consistency across the User Guide.

## Individual Comments

### Comment 1
<location path="content/docs/user-guide/providers.md" line_range="7" />
<code_context>
+weight: 2
+---
+
+Providers are infrastructure endpoints registered by service provider instances. Each provider represents a backend system — such as a KubeVirt-enabled Kubernets cluster — that can host virtual machines or other resources managed through DCM.
+
+Providers are **read-only** in the CLI. They are created automatically when a service provider instance connects to DCM and registers its available infrastructure.
</code_context>
<issue_to_address>
**issue (typo):** Fix the spelling of "Kubernetes" in the provider description.

In the phrase "KubeVirt-enabled Kubernets cluster", please correct "Kubernets" to "Kubernetes".

```suggestion
Providers are infrastructure endpoints registered by service provider instances. Each provider represents a backend system — such as a KubeVirt-enabled Kubernetes cluster — that can host virtual machines or other resources managed through DCM.
```
</issue_to_address>

### Comment 2
<location path="content/docs/user-guide/catalog-items.md" line_range="73" />
<code_context>
+|---------|---------|
+| `api_version` | Ties the catalog item to a specific schema version (e.g., `v1alpha1`). |
+| `display_name` | A human-readable name shown in listings and the UI. |
+| `spec.service_type` | Corresponding service type |
+| `spec.fields` | List of fields with const or users values |
+| `spec.fields[].path` | Path of the field within the `service_type` specification |
+| `spec.fields[].display_name` |  A human-readable name shown in listings and the UI |
</code_context>
<issue_to_address>
**issue (typo):** Fix "users values" to "user values" in the spec.fields description.

Update the `spec.fields` row in the table to use the corrected phrasing.

```suggestion
| `spec.fields` | List of fields with const or user values |
```
</issue_to_address>

### Comment 3
<location path="content/docs/user-guide/catalog-item-instances.md" line_range="50-51" />
<code_context>
+|-------|---------|
+| `display_name` | An optional human-readable name shown in listings and the UI. |
+| `spec.catalog_item_id` | References the UID of an existing catalog item to deploy from. |
+| `spec.user_values` | Sets of overrides for fields allowed by the catalog item's `fields` array. Only fields with `editable_fields: true` can be customized here. |
+| `spec.user_values[].path` | Path corresponding to the `path` key in the `catalog_item`'s `fields` item |
+
+> **Note:** Any values provided in `user_values` that are not permitted by the catalog item's `validation_schema` will be rejected. Check the catalog item's `editable_fields` to see which fields you can override.
</code_context>
<issue_to_address>
**issue:** Align `editable_fields` with the `editable` field used in catalog item definitions.

The schema and examples use `editable`, not `editable_fields`, as the flag for editability. Please update the description and note to refer to `editable: true` so the docs match the actual field name.
</issue_to_address>

### Comment 4
<location path="content/docs/user-guide/catalog-item-instances.md" line_range="167" />
<code_context>
+- The underlying resource needs to be recreated or updated.
+- Placement policies have changed and you want the instance to be re-evaluated against the current configuration.
+
+> **Note:** Rehydration will first provision the new resource before trying to delete the old one. Make sure to update and references (e.g. DNS) if needed
+
+## Deleting an Instance
</code_context>
<issue_to_address>
**issue (typo):** Fix wording in the rehydration note ("update and references").

Typo: change "update and references" to "update any references (e.g. DNS) if needed".

```suggestion
> **Note:** Rehydration will first provision the new resource before trying to delete the old one. Make sure to update any references (e.g. DNS) if needed
```
</issue_to_address>

### Comment 5
<location path="content/docs/user-guide/policies.md" line_range="55" />
<code_context>
+  }
+```
+
+> **Note:** This REGO code assumes it can access the `service-provider-manager` to get the list of provider. Then, it filters only the `ready` ones, sorts alphabetically and returns the first one
+
+### Field Reference
</code_context>
<issue_to_address>
**nitpick (typo):** Improve grammar in the REGO example note.

Consider changing this to: "list of providers" and "sorts alphabetically, and returns the first one."

```suggestion
> **Note:** This REGO code assumes it can access the `service-provider-manager` to get the list of providers. Then, it filters only the `ready` ones, sorts alphabetically, and returns the first one.
```
</issue_to_address>

### Comment 6
<location path="content/docs/user-guide/policies.md" line_range="65" />
<code_context>
+| `policy_type` | The scope of policy (e.g., `GLOBAL`). |
+| `priority` | Evaluation order. Lower numbers are evaluated first. |
+| `enabled` | Whether the policy is active (`true` or `false`). |
+| `rego_code` | The Rego source code. Must define a `main` rule with `rejected`, and either `rejected_reason` or `selected_provider` fields. |
+| `label_selector` | `key:value` pairs used to match between the policy and the `metadata.labels` field of the provisioned resource |
+
</code_context>
<issue_to_address>
**issue (bug_risk):** Correct the field name from `rejected_reason` to `rejection_reason`.

To match the examples and actual JSON output, this should be `rejection_reason`; using `rejected_reason` here may cause users to create invalid policies.
</issue_to_address>

### Comment 7
<location path="content/docs/user-guide/policies.md" line_range="68" />
<code_context>
+| `rego_code` | The Rego source code. Must define a `main` rule with `rejected`, and either `rejected_reason` or `selected_provider` fields. |
+| `label_selector` | `key:value` pairs used to match between the policy and the `metadata.labels` field of the provisioned resource |
+
+> **Note:** `label_selector` may also use the `service_type` key to match based on the resource's `service-type`
+
+### Rego Rule Structure
</code_context>
<issue_to_address>
**question:** Clarify whether `service_type` or `service-type` is the intended label key.

The note currently uses both `service_type` and `service-type`. Please either align them on the intended key or briefly explain why the label key intentionally differs from the spec field name.
</issue_to_address>

### Comment 8
<location path="content/docs/user-guide/policies.md" line_range="98" />
<code_context>
+| `patch` | map | No | A dictionary of values to set or override in the request payload. |
+| `constraints` | map | No | Field constraints for subsequent policies, following [JSON Schema (draft 2020-12)](https://json-schema.org/draft/2020-12/json-schema-validation). Supports `const` (immutable), numeric constraints (`minimum`, `maximum`, `multipleOf`), string patterns (`pattern`, `minLength`, `maxLength`), enumerations (`enum`), array constraints (`minItems`, `maxItems`), and conditional logic (`if`/`then`/`else`). |
+
+> **Note:** While no single policy is required to set the `selected_provider` field, the combination of all processed polices must set one; otherwise, placement will fail.
+
+### Create Command
</code_context>
<issue_to_address>
**issue (typo):** Fix the typo "polices" to "policies".

Also update the note to read “processed policies” instead of “processed polices”.

```suggestion
> **Note:** While no single policy is required to set the `selected_provider` field, the combination of all processed policies must set one; otherwise, placement will fail.
```
</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.}

[jenniferubah]

Overall looks good. Just the typos already caught by sourcery

[chadcrum]

Just to note: The dcm version -o json example in cli-configuration.md is inaccurate — the version command silently ignores the -o flag and always outputs plain text. Confirmed with CLI v0.3.1.

Tracked in FLPATH-4057.

[chadcrum]

Looks good to me.

[ygalblum]

@chadcrum since this PR was not yet merged, I adds here the fixes you listed in the ticket. See: 5adf74a, 02c784b, 5ce9f28 and 6b4e827

[pkliczewski]

looks good to me

[gciavarrini]

some minor comments. overall LGTM