Adoption Guide for PlacementDecision API

## Adoption Guide for PlacementDecision API

The PlacementDecision API (KEP-5313) gives schedulers a standard way to publish which clusters were chosen for a workload, and gives consumers a single API to watch instead of integrating with each scheduler individually. OCM is tracking support for producing these objects (https://github.com/open-cluster-management-io/ocm/issues/1373), but there's currently no guide explaining how to actually use the API from either side. It would be helpful to have a practical adoption guide covering both producer and consumer roles.

### For scheduler implementers (producers)

The guide should walk through: installing the CRDs, importing the generated clientset, creating a PlacementDecision with `decisions[]` entries that reference ClusterProfile objects via `clusterProfileRef`, setting `schedulerName` to identify the producing scheduler, and optionally populating `decisions[].reason` for audit/debug purposes. An important section would be the multi-slice pattern, when a placement selects more than 100 clusters, you need to split across multiple PlacementDecision objects using the `multicluster.x-k8s.io/decision-key` label (same value on all slices), `multicluster.x-k8s.io/decision-index` for ordering, and optionally `multicluster.x-k8s.io/placement-key` to link back to the originating workload. This is essentially the same pattern as EndpointSlice and is worth explaining with examples. The guide should also cover lifecycle management — updating decisions when scheduling changes, cleaning up when the originating placement request is deleted, and using ownerReferences appropriately.

### For workload consumers

The guide should cover: watching PlacementDecision objects in relevant namespaces, filtering by `schedulerName` or label selectors, correlating multi-slice decisions by `decision-key` and `decision-index`, and resolving each `clusterProfileRef` to a ClusterProfile and then to a live cluster connection via `pkg/access.BuildConfigFromCP()`. It should discuss how to react to decision changes — diffing old vs new decisions to figure out which clusters were added or removed, and what to do about workload migration. Some integration pattern examples would be useful: GitOps tools watching decisions and syncing apps to decided clusters, batch systems dispatching jobs, operators deploying components. A minimal consumer code example that watches a PlacementDecision and deploys something simple (like a ConfigMap) to each decided cluster would make things concrete.

### End-to-end walkthrough

It would be really helpful to have a combined walkthrough that ties both APIs together: a cluster manager creates ClusterProfile objects for a few clusters, a scheduler reads the profiles and selects a subset, writes a PlacementDecision referencing the chosen clusters, and then a consumer watches the decision and deploys workloads. This gives people the full picture of how the pieces fit together and is something the repo's existing `examples/controller-example/` partially demonstrates for the ClusterProfile side but doesn't cover for PlacementDecision yet.

### Where this should live

In the `docs` folder alongside the ClusterProfile adoption guide.

### References

- PlacementDecision types: `apis/v1alpha1/placementdecision_types.go`
- KEP-5313: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/5313-placement-decision-api/README.md
- OCM PlacementDecision tracking: https://github.com/open-cluster-management-io/ocm/issues/1373
- Existing integration tests: `test/integration/placementdecision_test.go`
- Generated client: `client/clientset/versioned/typed/apis/v1alpha1/`
- Current implementations page: https://multicluster.sigs.k8s.io/implementations/cluster-inventory-api-implementations/

/sig multicluster