docs: document Trait removes and toEndpointResources macro

- Add a "Removing Resources" section to the Patching Syntax page covering
  the Trait spec.removes section: target shape, execution order, the
  workload-kind removal restriction, and forEach removal.
- Document the opt-in workload.toEndpointResources() CEL macro under
  Workload Helpers, with route fields and gRPC/HTTP examples, and link to
  it from the workload context-variables reference.

Signed-off-by: Chathuranga Dassanayake <chathura2ihl@gmail.com>

Author: ChathurangaKCD

docs/platform-engineer-guide/component-types/patching-syntax.md

@@ -15,6 +15,8 @@ Traits can modify existing resources using patches, which are JSON Patch operati
 - CEL-based resource targeting
 - forEach iteration support
 
+A Trait can also **delete** whole resources produced by the ComponentType or earlier traits using the `spec.removes` section. See [Removing Resources](#removing-resources).
+
 ## Basic Patch Structure
 
 Patches are defined in the Trait's `spec.patches` section:
@@ -272,6 +274,73 @@ patches:
           name: ${port.name}
 ```
 
+## Removing Resources
+
+Patches modify resources in place. When a Trait needs to **delete** a whole resource produced by the ComponentType or by an earlier trait, use the `spec.removes` section instead. Each entry matches resources by GVK (with an optional `where` filter) and removes the matched resources entirely from the rendered output.
+
+```yaml
+apiVersion: openchoreo.dev/v1alpha1
+kind: Trait
+metadata:
+  name: drop-default-route
+spec:
+  removes:
+    - target:
+        kind: HTTPRoute
+        group: gateway.networking.k8s.io
+        version: v1
+      targetPlane: dataplane
+```
+
+A remove entry uses the same `target` shape as a patch, but has no `operations` — the whole matched resource is deleted:
+
+| Field             | Required | Description                                                            |
+| ----------------- | -------- | ---------------------------------------------------------------------- |
+| `target.kind`     | Yes      | Resource kind to remove (e.g. `HTTPRoute`, `ConfigMap`)                |
+| `target.group`    | Yes      | API group; use `""` for core API resources                             |
+| `target.version`  | Yes      | API version (e.g. `v1`)                                                |
+| `target.where`    | No       | CEL expression filtering which matching resources are removed          |
+| `targetPlane`     | No       | Plane whose resources are targeted; defaults to `"dataplane"`          |
+| `forEach` / `var` | No       | Iterate over a CEL list, binding each item to `var` for use in `where` |
+
+**Execution order** - Within a single trait, removes run **after** its `creates` and `patches`. This lets one trait fully express a substitution: create a replacement resource and then remove the original.
+
+```yaml
+spec:
+  creates:
+    - template:
+        apiVersion: v1
+        kind: ConfigMap
+        metadata:
+          name: ${metadata.name}-tuned-config
+        data:
+          mode: optimized
+  removes:
+    # Drop the ConfigMap the ComponentType emitted, now that the tuned one exists
+    - target:
+        kind: ConfigMap
+        group: ""
+        version: v1
+        where: ${resource.metadata.name == metadata.name + "-default-config"}
+```
+
+:::warning Workload resources cannot be removed
+The primary workload is defined by the ComponentType, so traits **must not** delete it. The admission webhook rejects removes that target a built-in workload GVK — kinds `Deployment`, `StatefulSet`, `DaemonSet`, `CronJob`, or `Job` in the `apps` or `batch` groups. The match is on the full GVK, so a custom CRD that merely shares one of these kind names in a different group (e.g. `group: example.com`, `kind: Deployment`) is **not** rejected.
+:::
+
+`forEach` is supported just like in patches, letting you remove a set of resources derived from a CEL list:
+
+```yaml
+removes:
+  - target:
+      kind: HTTPRoute
+      group: gateway.networking.k8s.io
+      version: v1
+      where: ${resource.metadata.labels["openchoreo.dev/endpoint-name"] == route}
+    forEach: ${parameters.routesToDrop}
+    var: route
+```
+
 ## Path Resolution Behavior
 
 | Path Type         | Operation            | Behavior                                   |

docs/reference/cel/context-variables.md

@@ -192,6 +192,13 @@ containers:
           port: ${workload.endpoints[endpoint].port}
 ```
 
+**Helper methods:** The `workload` object exposes two endpoint helpers:
+
+- `workload.toServicePorts()` — converts the endpoints map into Kubernetes Service ports.
+- `workload.toEndpointResources(endpointName)` — opt-in; parses the named endpoint's `schema` (OpenAPI for HTTP, protobuf for gRPC) into a CEL optional wrapping a list of `{kind, service, method, path}` routes, for rendering exact per-route gateway matches. Consume it with `.orValue([])` or `.hasValue()`/`.value()`.
+
+See [Helper Functions — Workload Helpers](./helper-functions.md#workload-helpers) for details.
+
 ### configurations
 
 Configuration and secret references extracted from the workload container.

docs/reference/cel/helper-functions.md

@@ -603,6 +603,73 @@ spec:
 - **BasePath usage**: For HTTPRoute path rewriting, use `workload.endpoints[endpointName].basePath` to configure URL path prefixes
 - **TargetPort distinction**: `targetPort` (container listening port) vs `port` (service port) - the helper uses the correct values for each
 
+### workload.toEndpointResources(endpointName)
+
+Parses a single endpoint's API schema (the OpenAPI document for HTTP endpoints, the protobuf definition for gRPC endpoints) and returns the flat list of routes it declares. This lets a ComponentType render **exact** per-route gateway matches — one match per OpenAPI path/method, or per gRPC service/method — instead of a single catch-all rule.
+
+This helper is **opt-in**: endpoint schemas are only parsed when a template actually calls `workload.toEndpointResources(...)`, so templates that don't use it pay no parsing cost.
+
+**Parameters:**
+
+| Parameter      | Type   | Description                                                                           |
+| -------------- | ------ | ------------------------------------------------------------------------------------- |
+| `endpointName` | string | The endpoint map key (e.g. `"http"`, `"grpc"`) — the key used in `workload.endpoints` |
+
+**Returns:** a CEL **optional** wrapping a list of route objects. Consume it with `.orValue([])`, or guard with `.hasValue()` / `.value()`. Each route object contains:
+
+| Field     | Type   | Description                                                                             |
+| --------- | ------ | --------------------------------------------------------------------------------------- |
+| `kind`    | string | Protocol of the route: `"HTTP"` or `"gRPC"`                                             |
+| `service` | string | Fully-qualified gRPC service name (e.g. `greeter.Greeter`). Empty for HTTP routes       |
+| `method`  | string | HTTP verb (`GET`/`POST`/...) for HTTP routes, or the gRPC method name (e.g. `SayHello`) |
+| `path`    | string | HTTP path template (e.g. `/v1/pets/{id}`). Empty for gRPC routes                        |
+
+Routes are returned in a deterministic (sorted) order so rendered output is stable.
+
+:::note Best-effort extraction
+A missing, empty, or unparseable schema (or an endpoint protocol with no extractor, such as TCP/UDP) yields an empty list — never a render failure. Schema format is inferred from the endpoint type (`HTTP` → OpenAPI, `gRPC` → protobuf) unless `workload.endpoints[name].schema.type` overrides it. Only OpenAPI and protobuf extractors exist today; GraphQL and AsyncAPI are reserved and currently degrade to an empty list.
+:::
+
+**Examples:**
+
+```yaml
+# gRPC: render one GRPCRoute match per (service, method) from the proto schema.
+# Falls back to a catch-all rule (no matches) when the endpoint has no parseable schema.
+rules:
+  - matches: >-
+      ${workload.toEndpointResources(endpoint.key).hasValue()
+        ? workload.toEndpointResources(endpoint.key).value().map(r,
+            {"method": {"type": "Exact", "service": r.service, "method": r.method}})
+        : oc_omit()}
+    backendRefs:
+      - name: ${metadata.componentName}
+        port: ${endpoint.value.port}
+```
+
+```yaml
+# HTTP: render one HTTPRoute rule per (path, method) from the OpenAPI schema.
+# Parameterized paths (/books/{id}) become a RegularExpression match; static paths use Exact.
+rules: >-
+  ${workload.toEndpointResources(endpoint.key).orValue([]).map(r, {
+      "matches": [{
+        "path": {
+          "type": r.path.contains("{") ? "RegularExpression" : "Exact",
+          "value": r.path.contains("{")
+            ? r.path.split("/").map(s, s.startsWith("{") ? "[^/]+" : s).join("/")
+            : r.path
+        },
+        "method": r.method
+      }],
+      "backendRefs": [{"name": metadata.componentName, "port": endpoint.value.port}]
+    })}
+```
+
+**Notes:**
+
+- Returns a CEL optional, not a plain list — always unwrap with `.orValue([])` or `.hasValue()`/`.value()`.
+- Reads from `workload.endpoints[endpointName].schema`; an endpoint with no schema yields an empty list.
+- Complete, runnable ComponentType examples ship in the OpenChoreo repo under `samples/component-types/component-grpc-service/` and `samples/component-types/component-http-openapi-service/`.
+
 ## Common Usage Patterns
 
 ### Complete Deployment with Configurations