[DOCS#EV-6623]: Fill HEP policy recommendation docs gaps — selector syntax and status lifecycle

calico-enterprise/network-policy/recommendations/hep-policy-recommendations.mdx

@@ -66,8 +66,10 @@ to the staged and enforced global network policies in that tier.
 
 - [Enable host-policy recommendations](#enable-host-policy-recommendations)
 - [View recommended policies](#view-recommended-policies)
+- [Scope recommendations to specific hosts](#scope-recommendations-to-specific-hosts)
 - [Tune global settings](#tune-global-settings)
 - [Manage the life cycle of recommendations](#manage-the-life-cycle-of-recommendations)
+- [Track recommendation readiness](#track-recommendation-readiness)
 - [Confirm a recommendation is matching real traffic](#confirm-a-recommendation-is-matching-real-traffic)
 - [Disable host-policy recommendations](#disable-host-policy-recommendations)
 
@@ -114,6 +116,38 @@ you can set — `Learn`, `Set`, or `Ignore` — tracked by the
 `projectcalico.org/spec.stagedAction` label and `spec.stagedAction` field.
 See [Manage the life cycle of recommendations](#manage-the-life-cycle-of-recommendations).
 
+### Scope recommendations to specific hosts
+
+By default, every host endpoint in the cluster is eligible for
+recommendations. To restrict the engine to a subset, set
+`hostEndpointSpec.selector` to a Calico label-selector expression that
+matches the labels of the host endpoints you want to cover.
+
+```bash
+# Recommend policies only for host endpoints labelled environment=prod.
+kubectl patch policyrecommendationscope default --type=merge --patch-file=/dev/stdin <<'EOF'
+spec:
+  hostEndpointSpec:
+    recommendationStatus: Enabled
+    selector: environment == 'prod'
+EOF
+```
+
+This table shows common selector patterns for host endpoint policy
+recommendations:
+
+| Goal                                             | Expression                                                       |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| Match all host endpoints                         | `all()` (or omit `selector`)                                     |
+| Match a single label value                       | `role == 'edge'`                                                 |
+| Match any of several values                      | `role in { 'edge', 'gateway' }`                                  |
+| Match host endpoints that carry a given label    | `has(zone)`                                                      |
+| Combine conditions with boolean operators        | <code>environment == 'prod' && !has(quarantined)</code>          |
+
+For the full operator reference — comparison, set membership,
+substring, and boolean composition — see
+[label selectors](../../reference/resources/policyrecommendations.mdx#selectors).
+
 ### Tune global settings
 
 Two top-level fields on the
@@ -283,6 +317,58 @@ kubectl delete globalnetworkpolicy.projectcalico.org <name>
 On the next processing cycle, the engine creates a fresh staged
 recommendation in `Learn`.
 
+### Track recommendation readiness
+
+In addition to the `stagedAction` lifecycle described above (which **you**
+control), the engine reports its own view of each recommendation through
+the `policyrecommendation.tigera.io/status` annotation on the staged
+global network policy. Use it to know when a recommendation has stopped
+changing long enough to be ready to enforce.
+
+This table describes the values the engine assigns to the
+`policyrecommendation.tigera.io/status` annotation:
+
+| Value         | Meaning                                                                                                                      |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `Learning`    | Engine is still actively adding or modifying rules from flow logs. This is the initial value and is reset whenever the engine changes the recommendation. |
+| `Stabilizing` | Engine has not modified the recommendation for longer than `2 × interval`, but no more than `stabilizationPeriod`. Rules look settled but the engine is still watching. |
+| `Stable`      | Engine has not modified the recommendation for longer than `stabilizationPeriod`. The recommendation is considered ready to enforce. |
+
+The status transitions are driven by the time since the engine last
+modified the recommendation, not by elapsed time alone:
+
+- A host that suddenly sends new traffic during a `Stabilizing` period
+  returns to `Learning` while the engine incorporates the new rules.
+- The `stabilizationPeriod` and `interval` values in
+  [Tune global settings](#tune-global-settings) directly control how
+  quickly a recommendation can reach `Stable`.
+
+Read the annotation with `kubectl`:
+
+```bash
+kubectl get stagedglobalnetworkpolicy.projectcalico.org <name> \
+  -o jsonpath='{.metadata.annotations.policyrecommendation\.tigera\.io/status}{"\n"}'
+```
+
+List the status of every host-policy recommendation at once:
+
+```bash
+kubectl get stagedglobalnetworkpolicies.projectcalico.org \
+  -l projectcalico.org/tier=hostendpoint-isolation \
+  -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.policyrecommendation\.tigera\.io/status}{"\n"}{end}'
+```
+
+:::tip
+
+Wait for `Stable` before
+[accepting](#activate-a-recommendation) and
+[enforcing](#enforce-a-recommendation) a recommendation. Accepting a
+recommendation while it is still learning or stabilizing pins the
+current — possibly incomplete — set of rules and stops the engine from
+refining it further.
+
+:::
+
 ### Confirm a recommendation is matching real traffic
 
 Use `calicoctl get` with `--show-policy-activities` to check when the

calico-enterprise/reference/resources/policyrecommendations.mdx

@@ -52,7 +52,7 @@ $ kubectl patch policyrecommendationscope default -p '{"spec":{"<parameter>":"<v
 | Field                              | Description                                                  | Accepted Values | Schema | Default        |
 | ---------------------------------- | ------------------------------------------------------------ | --------------- | ------ | -------------- |
 | `recStatus`                        | Defines the namespace policy recommendation engine status.   | Enabled/Disabled |        | Disabled       |
-| `selector`                         | Selects the namespaces for generating recommendations.       |                 |        | `!(projectcalico.org/name starts with ''tigera-'') && !(projectcalico.org/name starts with ''calico-'') && !(projectcalico.org/name starts with ''kube-'')` |
+| `selector`                         | Selects the namespaces for generating recommendations. Accepts any [label selector](#selectors) expression. |                 |        | `!(projectcalico.org/name starts with ''tigera-'') && !(projectcalico.org/name starts with ''calico-'') && !(projectcalico.org/name starts with ''kube-'')` |
 | `intraNamespacePassThroughTraffic` | When true, sets all intra-namespace traffic to Pass          | true/false |        | false |
 | `tierName`                         | Tier where the generated staged network policies are created. The tier must already exist. | | string | `namespace-isolation` |
 
@@ -61,5 +61,51 @@ $ kubectl patch policyrecommendationscope default -p '{"spec":{"<parameter>":"<v
 | Field                    | Description                                                  | Accepted Values  | Schema | Default                 |
 | ------------------------ | ------------------------------------------------------------ | ---------------- | ------ | ----------------------- |
 | `recommendationStatus`   | Defines the host policy recommendation engine status.        | Enabled/Disabled |        | Disabled                |
-| `selector`               | Selects which HostEndpoints the engine generates recommendations for. If omitted, every HostEndpoint is eligible. | | string | (all HostEndpoints)     |
+| `selector`               | Selects which HostEndpoints the engine generates recommendations for. If omitted, every HostEndpoint is eligible. Accepts any [label selector](#selectors) expression. | | string | (all HostEndpoints)     |
 | `tierName`               | Tier where the generated staged global network policies are created. The tier must already exist. | | string | `hostendpoint-isolation` |
+
+## Annotations on generated recommendations
+
+The engine annotates each staged network policy and staged global
+network policy it generates so you can inspect its progress and source
+without re-reading the spec. Annotations live under the
+`policyrecommendation.tigera.io/` prefix.
+
+| Annotation                                   | Description                                                                                                                                                                                                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `policyrecommendation.tigera.io/status`      | Engine's readiness signal for this recommendation. See [Recommendation status lifecycle](#recommendation-status-lifecycle) below.                                                                                                                |
+| `policyrecommendation.tigera.io/lastUpdated` | RFC 3339 timestamp of the engine's last modification to the generated staged policy's spec (the recommendation itself, not the PolicyRecommendationScope spec). Drives the `Learning → Stabilizing → Stable` transitions.                          |
+| `policyrecommendation.tigera.io/scope`       | Scope the recommendation was generated for. One of `namespace` (namespace recommendations) or `hostEndpoint` (host recommendations). Individual rules can also carry per-rule `scope` annotations such as `Domains`, `Private`, `Public`, `Service`, `NetworkSet`. |
+| `policyrecommendation.tigera.io/name`        | Name of the source object (namespace for namespace recommendations, HostEndpoint for host recommendations).                                                                                                                                       |
+| `policyrecommendation.tigera.io/namespace`   | For namespace recommendations: the namespace the recommendation applies to.                                                                                                                                                                       |
+
+### Recommendation status lifecycle
+
+The `policyrecommendation.tigera.io/status` annotation moves through
+the following values as the engine refines a recommendation. The
+transitions are driven by `lastUpdated`: the longer the generated
+staged policy's spec has remained unchanged, the further the
+recommendation has progressed.
+
+| Status        | When it is set                                                                                                                                  |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Learning`    | Initial value for every new recommendation. Reset to this whenever the engine modifies the spec.                                                |
+| `Stabilizing` | Set when the spec has been unchanged for more than `2 × interval` but no more than `stabilizationPeriod`. Rules look settled but are still being watched. |
+| `Stable`      | Set when the spec has been unchanged for more than `stabilizationPeriod`. Treat as ready to accept and enforce.                                 |
+
+`interval` and `stabilizationPeriod` are the top-level fields on this
+resource. Adjusting them directly controls how quickly a recommendation
+can reach `Stable`. See [Spec](#spec).
+
+The engine resets the status to `Learning` and bumps `lastUpdated` any
+time it adds, removes, or changes a rule, so a recommendation that
+absorbs new traffic late in its life cycle returns to `Learning` until
+it next stabilizes.
+
+## Selectors
+
+The `selector` fields on `namespaceSpec` and `hostEndpointSpec` accept
+the same label-selector expression language used elsewhere in Calico
+network policy.
+
+<Selectors />