orbit-code-ai 0.1.37 → 0.1.39

package/skills/apic-api/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: apic-api
-description: Generate a complete IBM API Connect (APIC) API definition for the DataPower API Gateway — full OpenAPI 2.0 (or 3.0) YAML including the x-ibm-configuration assembly (middleware logging, JWT validate, token-expiration switch, ESB response envelope, and catch handlers). Standard NHC middleware is baked in with opt-out flags.
+description: Generate a complete IBM API Connect (APIC) API definition for the DataPower API Gateway — full OpenAPI 2.0 (or 3.0) YAML including the x-ibm-configuration assembly (middleware logging, JWT validate, token-expiration switch, ESB response envelope, and catch handlers). Standard middleware is baked in with opt-out flags.
 trigger: /apic-api
 ---
 
 # /apic-api
 
 Generate a full APIC API definition (the `*.yaml` you import into API Connect / publish to the
-DataPower API Gateway). Output mirrors the house template used by the live AhelApp / Muamalaty /
-AmerApp APIs: a Swagger/OpenAPI contract **plus** the complete `x-ibm-configuration` assembly.
+DataPower API Gateway). Output mirrors the house template, illustrated by three reference shapes (SamplePost / SampleFwd /
+SampleDetect): a Swagger/OpenAPI contract **plus** the complete `x-ibm-configuration` assembly.
 
 ## Usage
 
@@ -18,25 +18,33 @@ AmerApp APIs: a Swagger/OpenAPI contract **plus** the complete `x-ibm-configurat
 Flags:
   --openapi 2.0|3.0     target spec version — USER'S CHOICE. If omitted, ask the user which one
                         they want before generating. Orbit does not assume a version.
+  --pattern P           integration pattern (see "Two integration patterns"):
+                        backend (default)  = APIC calls a raw backend and WRAPS the response in the
+                                             ESB {Header,Body} envelope.
+                        wrapper         = APIC publishes an existing integration service (ACE OR
+                                             webMethods) that ALREADY returns the ESB envelope, so
+                                             APIC is a thin proxy and does NOT re-wrap (implies
+                                             --no-envelope).
+                        If unspecified, ASK which pattern before generating.
   --crypto <name>       jws-crypto object for JWT validation (default: <appsegment>-crypto-object)
-  --backend-auth <name> APIC variable injected as backend auth header (e.g. servicenow-auth)
+  --backend-auth <name> APIC variable injected as backend auth header (e.g. backend-auth)
   --jwt                 force JWT on (skip the prompt); --no-jwt forces it off. If neither is
                         given, ASK the user whether JWT validation is required (see Clarify step).
   --no-jwt              omit jwt-validate + Check Expiration + 400 throw + ExpiredToken catch
                         (no token enforcement)
-  --no-logging          omit the middleware UpsertMDLogQ logging invoke (AmerApp-style)
+  --no-logging          omit the middleware UpsertMDLogQ logging invoke (SampleDetect-style)
   --no-envelope         return the raw backend body instead of the {Header,Body} ESB envelope
   --no-cors             disable CORS
 
   Backend-call tuning (all optional — infer sensible values from the prompt if not given):
   --backend-verb V      backend invoke verb: GET|POST|keep (default = API verb; "keep" forwards the
-                        caller's verb, AmerApp-style)
+                        caller's verb, SampleDetect-style)
   --backend-type T      backend response handling: json|detect (default json; "detect" =
-                        content-type based, used by AmerApp)
+                        content-type based, used by SampleDetect)
   --invoke-version V    backend invoke policy version: 2.2.0|2.3.0 (default 2.2.0; 2.3.0 adds
                         stop-on-error + graphql-send-type)
   --backend-auth-header H  header the --backend-auth value is set on (default Authorization;
-                        Muamalaty uses "Token")
+                        SampleFwd uses "Token")
   --backend-headers k=v,...  extra STATIC headers set before the backend call
                         (e.g. REST-Framework-Version=4)
   --pass-headers a,b,...  headers FORWARDED to the backend → invoke header-control allowlist
@@ -45,37 +53,43 @@ Flags:
                         params. CRITICAL: every query param the backend needs must be listed, or the
                         gateway strips it.
   --parse P             backend parse: json (inline document_type json, default) | default
-                        (apic-default-parsesettings, AmerApp-style)
-  --use-content-type    add use-content-type: true to the backend parse (Muamalaty/AmerApp)
-  --envelope-placement P  where Prepare Response Header goes: in-case (default, Ahel/AmerApp) |
-                        top-level (after the switch, Muamalaty)
+                        (apic-default-parsesettings, SampleDetect-style)
+  --use-content-type    add use-content-type: true to the backend parse (SampleFwd/SampleDetect)
+  --envelope-placement P  where Prepare Response Header goes: in-case (default, SamplePost/SampleDetect) |
+                        top-level (after the switch, SampleFwd)
 
 Examples:
-  /apic-api AmerAppGetUserInfo GET /v1/AmerApp \
-    backend $(erp-base-url)/hcmRestApi/resources/latest/workers?onlyData=true; query param expand
-  /apic-api AhelUpdateCustomer POST /v1/AhelApp \
-    backend $(servicenow-url)api/.../UpdateCustomerPersonalInformation; --backend-auth servicenow-auth; \
+  /apic-api SampleGetUserInfo GET /v1/SampleApp \
+    backend $(backend-base-url)/api/resource/workers?onlyData=true; query param expand
+  /apic-api SampleUpdateCustomer POST /v1/SampleApp \
+    backend $(backend-base-url)/api/UpdateCustomer; --backend-auth backend-auth; \
     body fields: customerSysId,email,idNumber,name,avatar,gender,dateOfBirth,attachment_records
 ```
 
 ## Variables to Derive
 
 From the inputs:
-- `{ApiTitle}` = Title Case of ApiName, e.g. `AmerApp Get User Info`
-- `{x-ibm-name}` = kebab-case of ApiName, e.g. `amerapp-get-userinfo` (also the file stem)
-- `{AppSegment}` = the app portion of basePath after `/v1/`, e.g. `AmerApp`
-- `{appsegmentlower}` = lowercase AppSegment, e.g. `amerapp`
+- `{ApiTitle}` = Title Case of ApiName, e.g. `SampleDetect Get User Info`
+- `{x-ibm-name}` = kebab-case of ApiName, e.g. `sampledetect-get-userinfo` (also the file stem)
+- `{AppSegment}` = the app portion of basePath after `/v1/`, e.g. `SampleDetect`
+- `{appsegmentlower}` = lowercase AppSegment, e.g. `sampledetect`
 - `{version}` = `1.0.0` unless supplied
-- `{operation-path}` = the API's own path, **derived from the API name** (PascalCase, leading slash):
-  `Get Customer Balance` → `/GetCustomerBalance`, like `AmerApp Get User Info` → `/GetUserInfo`.
-  **NEVER** take it from the backend target-url's path (the backend path is unrelated to the
-  exposed API path). Use a supplied path only if the user gives one explicitly.
+- `{operation-path}` = the API's own exposed path.
+  - **If the user supplies an explicit path — use it VERBATIM, exact casing, no re-derivation.**
+    Any of `path: /getCommodities`, `exposed path /getCommodities`, or a gateway path like
+    `commodity/api/v1.0/getCommodities` (→ take the segment after basePath: `/getCommodities`) counts
+    as explicit. A supplied `/getCommodities` must NOT become `/GetCommodities`.
+  - Only when NO path is supplied, derive it from the API name (PascalCase, leading slash):
+    `Get Customer Balance` → `/GetCustomerBalance`.
+  - **NEVER** take it from the backend target-url's path (the backend path is unrelated to the
+    exposed API path) — except the explicit-gateway-path case above, where the exposed segment is
+    stated by the user.
 - `{verb}` = GET or POST (lowercase in `paths`)
 - `{crypto-object}` = `--crypto` or `{appsegmentlower}-crypto-object`
 - `{backend-target-url}` = backend URL from the description (keep `$(...)` APIC vars verbatim,
   including claim injections like `?userEmail=$(decoded.claims.EmailAddress)`)
 - `{backend-auth-var}` = `--backend-auth` value (only emitted if provided)
-- `{backend-auth-header}` = `--backend-auth-header` or `Authorization` (Muamalaty: `Token`)
+- `{backend-auth-header}` = `--backend-auth-header` or `Authorization` (SampleFwd: `Token`)
 - `{backend-verb}` = `--backend-verb` or the API verb (may be `keep` — forwards caller's verb)
 - `{backend-type}` = `--backend-type` or `json` (or `detect`)
 - `{query}` = list of backend query params (from `--query` or inferred from the backend URL / prompt)
@@ -93,13 +107,18 @@ in a single batched follow-up** (alongside the 2.0/3.0 question). Do NOT invent
 values for these:
 
 - **OpenAPI version** — 2.0 or 3.0 (always ask if unspecified).
+- **Integration pattern** — is APIC calling a **raw backend** (it must wrap the response in the ESB
+  envelope → `backend`), or **publishing an existing integration service (ACE or webMethods)** that
+  already returns the ESB envelope (APIC is a thin proxy, no re-wrap → `wrapper`)? Ask unless
+  `--pattern` is given or the prompt makes it clear (e.g. "expose our ACE flow", "wrap the webMethods
+  service", "the backend already returns the envelope").
 - **JWT validation** — **ASK whether this API requires JWT validation** unless `--jwt`/`--no-jwt`
   was passed or the prompt clearly states it. JWT is NOT assumed on. If **yes**, include the JWT
   policies and ask for the crypto object (below). If **no**, omit JWT entirely (see the
   "No-JWT shape" section) and do not ask for a crypto object.
-- **Channel / app + basePath** — e.g. `/v1/AmerApp`. The app segment also drives naming. There is
+- **Channel / app + basePath** — e.g. `/v1/SampleDetect`. The app segment also drives naming. There is
   no way to infer this from the operation name; ask (offer the known channels if helpful).
-- **JWT crypto object** — e.g. `$(amerapp-crypto-object)`. Tied to the channel, not the operation.
+- **JWT crypto object** — e.g. `$(sampledetect-crypto-object)`. Tied to the channel, not the operation.
   **Only ask this when JWT is enabled.** Do not derive it from the API name.
 - **Backend auth** — the APIC variable and the header it goes on (`Authorization` vs `Token`), if
   the backend needs auth. Ask only if the prompt implies the backend is protected.
@@ -108,6 +127,58 @@ If the user prefers not to answer, fall back to clearly-marked placeholders
 (`$(CHANGEME-crypto-object)`, `basePath: /v1/CHANGEME`) and list every placeholder in the summary —
 never a guess that looks real.
 
+## Two integration patterns
+
+Every APIC API generated here is one of two shapes. Pick from `--pattern`, the prompt, or the
+Clarify answer.
+
+**`backend` (default) — APIC → raw backend.** APIC calls a backend service that returns a *raw*
+body, so APIC is responsible for the ESB contract: it runs the full middleware and **wraps the
+backend response** in the `{Header, Body}` envelope via the `Prepare Response Header` gatewayscript.
+This is the skeleton exactly as written below.
+
+**`wrapper` — APIC → existing integration service (TRUE thin proxy).** The backend *is* an existing
+integration service — **ACE or webMethods** — that already owns the response contract (envelope,
+business errors, correlation). APIC adds only gateway concerns (client-id/secret, optional JWT,
+optional logging) and forwards the service's request/response **unchanged**. The pattern is identical
+whichever platform sits behind it; only `{backend-target-url}` differs.
+
+A thin wrapper must **NOT stamp house-specific conventions** onto a service that has its own. So,
+unlike `backend`, wrapper mode drops all of these:
+- **No `Prepare Response Header`** — do not re-wrap the success body (report "ESB envelope: off
+  (service-provided)").
+- **No RefId-enforcing `Prepare Request`.** The frozen Prepare Request rejects on a missing `RefId`
+  header — that is one house's standard, not universal, and would reject a client that uses a
+  different correlation header. Omit it. If the spec names a correlation header (e.g. `X-Request-Id`),
+  optionally capture it with a **non-rejecting** `set-variable`; never `context.reject(...)`.
+- **No ESB `{Header, Body}` error envelope in `catch`.** The frozen `DeFaultCatch` writes the house
+  envelope and depends on `context.customheaders.*` that a wrapper never sets. Use the **neutral
+  catch** below (surfaces the gateway error plainly). Business errors are unaffected — they come back
+  as a normal response body from the wrapped service.
+- **Declare the spec's ACTUAL inbound headers** in `paths` (e.g. `X-Request-Id`), **not** the house
+  `RefId` / `CallerReqTime`.
+- `{backend-target-url}` is the upstream service endpoint (an internal `$(...)` base-url variable),
+  not an external vendor URL.
+- Keep security (client-id/secret); apply JWT / MW logging only as the flags/Clarify decide.
+
+**For the actual YAML to emit in wrapper mode, use the complete standalone template in the
+"## Wrapper skeleton (COMPLETE …)" section** — copy that entire file and fill the slots. Do NOT
+assemble from the backend "## OpenAPI 2.0 skeleton"; the wrapper skeleton is self-contained and
+already excludes the `Prepare Request`, `map`, `Prepare Response Header`, and ESB catch.
+
+## Configurable middleware / backend variables
+
+The `$(...)` names below are **placeholders you map to your gateway's real APIC variables** — they
+contain no organization-specific names:
+- `$(mw-auth)` and `$(mw-log-base-url)` — the standard middleware logging auth + base URL. Set these
+  to whatever your DataPower catalog actually calls them. **Deploy-critical:** if the names don't
+  match real gateway variables, logging silently fails.
+- `$(backend-auth)` and `$(backend-base-url)` — the backend's auth variable and base URL.
+- `$({crypto-object})` — the JWT crypto object (only when JWT is on).
+
+Never invent real-looking values for these; when unknown, keep the placeholder and list it in the
+summary (see the Clarify rules).
+
 ## Generation rules
 
 1. **The spec version is the user's choice — Orbit supports both 2.0 and 3.0 equally.** Never
@@ -119,13 +190,27 @@ never a guess that looks real.
 2b. **JWT is optional and not assumed.** Decide JWT on/off from `--jwt`/`--no-jwt`, an explicit
    statement in the prompt, or the clarify answer. With JWT **off**, build the simpler "No-JWT shape"
    (no jwt-validate, no Check Expiration, no switch, no ExpiredToken catch) — see that section.
-3. **Paste the frozen gatewayscript verbatim.** The JS strings below must be byte-exact — DataPower
-   rejects malformed assembly. Do not "clean up" or reformat them.
-4. **GET vs POST**: GET → query/header params, no request `map`, no `definitions`. POST with body
-   fields → add a request `map` policy + a `Request` definition (AhelApp pattern).
+2c. **WRAPPER MODE IS A HARD OVERRIDE — obey before anything below.** When `--pattern wrapper`, the
+   assembly is the **"Thin-wrapper assembly"** block (in "Two integration patterns") — emit THAT,
+   not the main skeleton. Regardless of any "frozen/verbatim" rule below, in wrapper mode you MUST
+   **NOT emit** any of the following (they belong to `backend` only):
+   - ❌ the `Prepare Request` gatewayscript (the RefId `context.reject` guard) — omit entirely;
+   - ❌ the ESB `{Header, Body}` `DeFaultCatch` — use the **neutral catch** (`{code, message}`) instead;
+   - ❌ the `Prepare Response Header` gatewayscript — never re-wrap;
+   - ❌ the `RefId` / `CallerReqTime` path-level header params — declare the spec's real headers instead;
+   - ❌ any request `map` — a wrapper forwards the body **as-is** (no identity map, even for POST).
+   The frozen fragments' "paste verbatim" only means: IF a fragment is emitted, it is byte-exact. It
+   does NOT mean every fragment must appear. Wrapper mode emits fewer fragments — that is correct.
+3. **Paste the frozen gatewayscript verbatim** (in the `backend` pattern). The JS strings below must
+   be byte-exact — DataPower rejects malformed assembly. Do not "clean up" or reformat them. (Wrapper
+   mode omits several of them — see rule 2c.)
+4. **GET vs POST** (`backend` pattern): GET → query/header params, no request `map`, no `definitions`.
+   POST with body fields → add a request `map` policy + a `Request` definition (SamplePost pattern).
+   **Wrapper mode: NEVER add a request `map`** (the body is forwarded unchanged); still emit the
+   POST `definitions/Request` for the contract, and the leading `parse`.
 5. Respect opt-out flags by omitting the corresponding policy (see annotations in the skeleton).
 6. **Preserve every `$(...)` APIC variable reference exactly** — never strip the wrapper. In
-   particular `jws-crypto` MUST be `$({crypto-object})` (e.g. `$(amerapp-crypto-object)`), not the
+   particular `jws-crypto` MUST be `$({crypto-object})` (e.g. `$(sampledetect-crypto-object)`), not the
    bare name. A bare value is treated by the gateway as a literal string, not a variable, and breaks
    JWT validation. Same for `target-url`, backend auth values, and any `$(...)` in the fragments.
 7. **Backend `parameter-control` allowlist MUST list every backend query param.** An empty allowlist
@@ -143,7 +228,7 @@ never a guess that looks real.
 10. **Do not hand-append allowlisted query params to the backend `target-url`.** Params listed in the
     invoke `parameter-control` allowlist are forwarded automatically. Only manually append values
     that are NOT request params — i.e. injected claims like `?userEmail=$(decoded.claims.EmailAddress)`
-    (Muamalaty) or `&q=...$(decoded.claims.EmailAddress)` (AmerApp). Appending
+    (SampleFwd) or `&q=...$(decoded.claims.EmailAddress)` (SampleDetect). Appending
     `?accountId=$(request.parameters.accountId)` for an already-allowlisted `accountId` is wrong.
 11. **Reproduce every gatewayscript `source` character-for-character.** Do not strip comments, blank
     lines, or re-indent. The single-line quoted form (`"...\n..."`) is canonical and must be copied
@@ -153,7 +238,14 @@ never a guess that looks real.
 
 ## OpenAPI 2.0 skeleton
 
-Assemble the file in this order. Fill `{slots}`; paste frozen fragments unchanged.
+> ⛔ **`--pattern wrapper`: DO NOT USE THIS SKELETON AT ALL.** Skip straight to the **"## Wrapper
+> skeleton (COMPLETE …)"** section below and emit that entire file instead. It is a complete,
+> standalone document — there is nothing to copy from here. The `Prepare Request`, `map`,
+> `Prepare Response Header`, and ESB `DeFaultCatch` fragments in this skeleton do NOT exist in wrapper
+> output; if you paste any of them for a wrapper, it is a bug.
+
+Assemble the file in this order. Fill `{slots}`; paste frozen fragments unchanged. **(`backend`
+pattern — for `wrapper`, see the box above.)**
 
 ```yaml
 swagger: '2.0'
@@ -171,7 +263,7 @@ x-ibm-configuration:
   testable: true
   assembly:
     execute:
-      # ── POST-WITH-BODY ONLY: leading parse of the incoming request (AhelApp). Omit for GET. ──
+      # ── POST-WITH-BODY ONLY: leading parse of the incoming request (SamplePost). Omit for GET. ──
       # Place this as the FIRST policy, before logging, so message.body is parsed for the map.
       - parse:
           version: 2.2.0
@@ -194,7 +286,7 @@ x-ibm-configuration:
           title: Log-set-variable
           actions:
             - set: message.headers.Authorization
-              value: $(nhc-mw-auth)
+              value: $(mw-auth)
               type: string
       - invoke:
           version: 2.0.0
@@ -214,7 +306,7 @@ x-ibm-configuration:
           keep-payload: true
           output: outResp
           target-url: >-
-            $(sakani-mw-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
+            $(mw-log-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
 
       # ── JWT (only when JWT is enabled). If JWT is OFF, omit jwt-validate + Check Expiration AND
       #    drop the switch below — run the backend call directly. See "No-JWT shape". ──
@@ -237,8 +329,8 @@ x-ibm-configuration:
             - condition: ($statusCode() = 200)
               execute:
                 # Backend auth + static headers — emit only if --backend-auth / --backend-headers given.
-                # Header name = {backend-auth-header} (default Authorization; Muamalaty uses "Token").
-                # Add one action per --backend-headers entry (e.g. REST-Framework-Version: '4', AmerApp).
+                # Header name = {backend-auth-header} (default Authorization; SampleFwd uses "Token").
+                # Add one action per --backend-headers entry (e.g. REST-Framework-Version: '4', SampleDetect).
                 - set-variable:
                     version: 2.0.0
                     title: set-variable
@@ -253,15 +345,15 @@ x-ibm-configuration:
                 # POST-with-body ONLY → request map (see "POST request map" section). Omit for GET.
 
                 # ── Backend call ──
-                # verb: {backend-verb} (GET|POST|keep — "keep" forwards caller's verb, AmerApp)
-                # backend-type: {backend-type} (json default | detect, AmerApp)
+                # verb: {backend-verb} (GET|POST|keep — "keep" forwards caller's verb, SampleDetect)
+                # backend-type: {backend-type} (json default | detect, SampleDetect)
                 # version 2.3.0 ⇒ also include stop-on-error: [] and graphql-send-type: detect (see variations ref)
                 - invoke:
                     version: 2.2.0          # or 2.3.0
                     title: invoke
                     backend-type: json      # or detect
                     header-control:
-                      type: blocklist       # → allowlist with {pass-headers} when forwarding custom headers (Muamalaty: Token, rolename)
+                      type: blocklist       # → allowlist with {pass-headers} when forwarding custom headers (SampleFwd: Token, rolename)
                       values: []
                     parameter-control:
                       type: allowlist
@@ -278,8 +370,8 @@ x-ibm-configuration:
                     target-url: >-
                       {backend-target-url}
                 # Backend parse — pick ONE form (see --parse / variations ref):
-                #   inline json (default) ── or ── named default: apic-default-parsesettings (AmerApp)
-                # add `use-content-type: true` when --use-content-type (Muamalaty/AmerApp).
+                #   inline json (default) ── or ── named default: apic-default-parsesettings (SampleDetect)
+                # add `use-content-type: true` when --use-content-type (SampleFwd/SampleDetect).
                 - parse:
                     version: 2.2.0
                     title: parse
@@ -288,8 +380,8 @@ x-ibm-configuration:
                         document_type: json
 
                 # ── FROZEN: Prepare Response Header — OMIT if --no-envelope. ──
-                # Default placement: HERE (inside the 200 case, Ahel/AmerApp).
-                # If --envelope-placement top-level (Muamalaty): move this policy OUT of the switch,
+                # Default placement: HERE (inside the 200 case, SamplePost/SampleDetect).
+                # If --envelope-placement top-level (SampleFwd): move this policy OUT of the switch,
                 # to top-level execute AFTER the switch and BEFORE the log policy.
                 - gatewayscript:
                     version: 2.0.0
@@ -368,11 +460,15 @@ x-ibm-configuration:
     error-content: payload
 paths:
   {operation-path}:
-    parameters:                   # path-level shared params (RefId may be required: true, Muamalaty)
+    # `backend` pattern: house correlation headers (RefId / CallerReqTime), as below.
+    # `wrapper` pattern: DELETE the RefId and CallerReqTime entries below entirely and put the spec's
+    #   ACTUAL inbound headers here (e.g. X-Request-Id). Do NOT keep RefId/CallerReqTime AND add the
+    #   spec header — replace, don't append. (See rule 2c.)
+    parameters:                   # path-level shared params (RefId may be required: true, SampleFwd)
       - name: RefId
         in: header
         type: string
-        # required: true          # add when RefId is mandatory (Muamalaty)
+        # required: true          # add when RefId is mandatory (SampleFwd)
       - name: CallerReqTime
         in: header
         type: string
@@ -388,12 +484,12 @@ paths:
         #     GET example:  - { name: inboxId, in: query, type: string, required: true }
         #  2. POST-with-body: - { name: body, in: body, required: true, schema: { $ref: '#/definitions/Request' } }
         #  3. authorization header (below)
-        #  4. any extra forwarded headers, e.g. rolename (Muamalaty, required: true)
+        #  4. any extra forwarded headers, e.g. rolename (SampleFwd, required: true)
         - name: authorization
           required: true
           in: header
           type: string
-        # - name: rolename        # example: custom forwarded header (Muamalaty)
+        # - name: rolename        # example: custom forwarded header (SampleFwd)
         #   required: true
         #   in: header
         #   type: string
@@ -417,6 +513,145 @@ basePath: {basePath}
 
 ---
 
+## Wrapper skeleton (COMPLETE — use this ENTIRE file for `--pattern wrapper`)
+
+For `--pattern wrapper`, **emit exactly this file** and fill the `{slots}`. It already omits the
+`Prepare Request`, the `map`, the `Prepare Response Header`, and the ESB catch — do NOT add any of
+them back, and do NOT copy anything from the backend skeleton above. There is no subtraction to do:
+this is the whole document. (If `--jwt` is on for a wrapper — rare — add `jwt-validate` +
+`Check Expiration` + `switch` before `invoke` per the main skeleton, keeping everything else here.)
+
+```yaml
+swagger: '2.0'
+info:
+  title: {ApiTitle}
+  x-ibm-name: {x-ibm-name}
+  version: {version}
+x-ibm-configuration:
+  cors:
+    enabled: true            # --no-cors → false
+  gateway: datapower-api-gateway
+  type: rest
+  phase: realized
+  enforced: true
+  testable: true
+  assembly:
+    execute:
+      # POST-with-body ONLY: leading parse. Omit this policy entirely for GET.
+      - parse:
+          version: 2.2.0
+          title: parse
+          parse-settings-reference:
+            parse-settings:
+              document_type: json
+              max_value_length: 0
+              max_width: 0
+
+      # OPTIONAL correlation capture — ONLY if the spec names an inbound correlation header.
+      # Non-rejecting. Use the spec's real header name. Omit this whole policy if none.
+      - set-variable:
+          version: 2.0.0
+          title: Capture Correlation Id
+          actions:
+            - set: context.customheaders.CorrelationId
+              value: $(request.headers.X-Request-Id)   # ← spec's real header
+              type: string
+
+      # MW logging — include the Log-set-variable + Log-invoke pair from the backend skeleton
+      # ONLY if NOT --no-logging. Omit both for --no-logging.
+      # Backend auth — include a set-variable ({backend-auth-header}: $({backend-auth-var}))
+      # ONLY if --backend-auth was given.
+
+      # ── Backend call → the ACE/webMethods service (direct, no switch) ──
+      - invoke:
+          version: 2.2.0
+          title: invoke
+          backend-type: json
+          header-control:
+            type: blocklist         # → allowlist {pass-headers} if forwarding specific headers
+            values: []
+          parameter-control:
+            type: allowlist
+            values: []              # list every backend {query} param; empty = none forwarded
+          timeout: 60
+          verb: {verb}
+          http-version: HTTP/1.1
+          chunked-uploads: true
+          persistent-connection: true
+          cache-response: protocol
+          cache-ttl: 900
+          websocket-upgrade: false
+          target-url: >-
+            {backend-target-url}
+      - parse:
+          version: 2.2.0
+          title: parse
+          parse-settings-reference:
+            parse-settings:
+              document_type: json
+      - log:
+          version: 2.1.0
+          title: log
+          log-level: default
+          mode: gather-and-send
+    finally: []
+    # Neutral catch — surface the gateway error plainly. NO ESB {Header,Body} envelope.
+    catch:
+      - default:
+          - gatewayscript:
+              version: 2.0.0
+              title: DeFaultCatch
+              source: "var code = context.get('error.status.code');\nvar reason = context.get('error.message');\ncontext.message.statusCode = code;\nsession.output.write({ \"code\": code, \"message\": reason });"
+  properties:
+    target-url:
+      value: http://example.com/operation-name
+      description: The URL of the target service
+      encoded: false
+  activity-log:
+    enabled: true
+    success-content: activity
+    error-content: payload
+paths:
+  {operation-path}:
+    parameters:
+      # The spec's REAL inbound headers ONLY. Example correlation header shown.
+      # Do NOT add RefId or CallerReqTime here.
+      - name: X-Request-Id       # ← replace with the spec's actual header(s)
+        in: header
+        type: string
+    {verb}:                       # get: or post:
+      responses:
+        '200':
+          description: success
+          schema:
+            type: string
+      parameters:
+        # POST-with-body: body param (GET: omit). Plus any backend {query} params as in: query.
+        - name: body
+          in: body
+          required: true
+          schema:
+            $ref: '#/definitions/Request'
+securityDefinitions:
+  clientID:
+    type: apiKey
+    in: header
+    name: X-IBM-Client-Id
+  clientSecret:
+    type: apiKey
+    name: X-IBM-Client-Secret
+    in: header
+security:
+  - clientID: []
+    clientSecret: []
+schemes:
+  - https
+basePath: {basePath}
+# definitions: only for POST-with-body — same Request block as the backend skeleton.
+```
+
+---
+
 ## No-JWT shape (when JWT validation is OFF)
 
 When the API does **not** require JWT, generate a simpler assembly: there's no token to validate, so
@@ -435,7 +670,7 @@ call runs directly, and the `catch` keeps only the `default` handler.
           source: "<<< the FROZEN Prepare Request source, verbatim >>>"
 
       # Middleware logging — include unless --no-logging (same as main skeleton)
-      - set-variable: { version: 2.0.0, title: Log-set-variable, actions: [ { set: message.headers.Authorization, value: $(nhc-mw-auth), type: string } ] }
+      - set-variable: { version: 2.0.0, title: Log-set-variable, actions: [ { set: message.headers.Authorization, value: $(mw-auth), type: string } ] }
       - invoke:    # ...the Log-invoke (UpsertMDLogQ) policy, verbatim...
 
       # Backend auth + static headers (only if --backend-auth / --backend-headers given)
@@ -497,7 +732,7 @@ Notes for the No-JWT shape:
 ## POST request map (only when body fields are given)
 
 Insert this `map` **inside the 200 case, before the backend `invoke`**, and add the matching
-`definitions` block. Pattern from AhelApp — first output field defaults from a JWT claim, the rest
+`definitions` block. Pattern from SamplePost — first output field defaults from a JWT claim, the rest
 copy through from input:
 
 ```yaml
@@ -545,20 +780,20 @@ definitions:
 ## Policy variations reference (drawn from the three live samples)
 
 Use these exact forms when the prompt calls for them. The three samples map to:
-**AhelApp** = POST + leading parse + request map + logging(v2.3.0) + envelope in-case;
-**Muamalaty** = GET + logging(v2.0.0) + Token-header backend + forwarded headers + envelope top-level;
-**AmerApp** = GET + NO logging + verb keep + backend-type detect + named parse + envelope in-case.
+**SamplePost** = POST + leading parse + request map + logging(v2.3.0) + envelope in-case;
+**SampleFwd** = GET + logging(v2.0.0) + Token-header backend + forwarded headers + envelope top-level;
+**SampleDetect** = GET + NO logging + verb keep + backend-type detect + named parse + envelope in-case.
 
-### Logging invoke — two variants (omit entirely if `--no-logging`, AmerApp)
+### Logging invoke — two variants (omit entirely if `--no-logging`, SampleDetect)
 
-**(a) v2.0.0 "json" (Muamalaty)** — current skeleton default:
+**(a) v2.0.0 "json" (SampleFwd)** — current skeleton default:
 ```yaml
       - invoke:
           version: 2.0.0
           title: Log-invoke
           verb: POST
           target-url: >-
-            $(sakani-mw-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
+            $(mw-log-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
           follow-redirects: false
           timeout: 60
           parameter-control: { type: allowlist, values: [] }
@@ -570,7 +805,7 @@ Use these exact forms when the prompt calls for them. The three samples map to:
           keep-payload: true
           chunked-uploads: true
 ```
-**(b) v2.3.0 "detect" (AhelApp)** — preceded by its own `set-variable` setting `Authorization: $(nhc-mw-auth)`:
+**(b) v2.3.0 "detect" (SamplePost)** — preceded by its own `set-variable` setting `Authorization: $(mw-auth)`:
 ```yaml
       - invoke:
           version: 2.3.0
@@ -589,11 +824,11 @@ Use these exact forms when the prompt calls for them. The three samples map to:
           websocket-upgrade: false
           graphql-send-type: detect
           target-url: >-
-            $(sakani-mw-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
+            $(mw-log-base-url)/MW/MWLogServices/GeneralLog/UpsertMDLogQ?Environment=$(env.path)&ServiceName=$(api.name)&UserName=$(client.app.id)&RequestDt=$(system.datetime)
           output: logResp
 ```
 
-### Backend invoke — v2.3.0 / detect / keep (AmerApp)
+### Backend invoke — v2.3.0 / detect / keep (SampleDetect)
 Same as the skeleton invoke, but with these fields:
 ```yaml
                 - invoke:
@@ -613,17 +848,17 @@ Same as the skeleton invoke, but with these fields:
                     websocket-upgrade: false
                     graphql-send-type: detect
                     target-url: >-
-                      $(erp-base-url)/hcmRestApi/resources/latest/workers?onlyData=true&q=emails.EmailAddress='$(decoded.claims.EmailAddress)'
+                      $(backend-base-url)/api/resource/workers?onlyData=true&q=emails.EmailAddress='$(decoded.claims.EmailAddress)'
 ```
 
-### Backend with forwarded headers (Muamalaty) — Token auth + allowlist
+### Backend with forwarded headers (SampleFwd) — Token auth + allowlist
 ```yaml
                 - set-variable:
                     version: 2.0.0
                     title: set-variable
                     actions:
                       - set: message.headers.Token
-                        value: $(nhc-cts-auth)
+                        value: $(backend-auth)
                         type: string
                 - invoke:
                     version: 2.2.0
@@ -639,24 +874,24 @@ Same as the skeleton invoke, but with these fields:
                     verb: GET
                     # ...rest as skeleton...
                     target-url: >-
-                      $(nhc-cts-url)/CTSIPADUtilities/action/GetCorrespondences?userEmail=$(decoded.claims.EmailAddress)
+                      $(backend-base-url)/api/GetCorrespondences?userEmail=$(decoded.claims.EmailAddress)
 ```
 
-### Multi-action set-variable (AmerApp) — auth + static framework header
+### Multi-action set-variable (SampleDetect) — auth + static framework header
 ```yaml
                 - set-variable:
                     version: 2.0.0
                     title: set-variable
                     actions:
                       - set: message.headers.Authorization
-                        value: $(erp-ameruser-auth)
+                        value: $(backend-auth)
                         type: string
                       - set: message.headers.REST-Framework-Version
                         value: '4'
                         type: string
 ```
 
-### Backend parse — named-default form (AmerApp)
+### Backend parse — named-default form (SampleDetect)
 ```yaml
                 - parse:
                     version: 2.2.0
@@ -666,13 +901,13 @@ Same as the skeleton invoke, but with these fields:
                     use-content-type: true
 ```
 
-### Envelope placement — top-level (Muamalaty)
+### Envelope placement — top-level (SampleFwd)
 The `Prepare Response Header` gatewayscript sits at **top-level execute, after the `switch`,
 before `log`** — not inside the 200 case. The `switch` there is `version: 2.1.0`.
 
 ### Quick per-sample knob table
 
-| Knob | AhelApp | Muamalaty | AmerApp |
+| Knob | SamplePost | SampleFwd | SampleDetect |
 |---|---|---|---|
 | method | POST | GET | GET |
 | leading parse | yes | no | no |
@@ -680,7 +915,7 @@ before `log`** — not inside the 200 case. The `switch` there is `version: 2.1.
 | request map + definitions | yes | no | no |
 | backend version / type | 2.2.0 / json | 2.2.0 / json | 2.3.0 / detect |
 | backend verb | POST | GET | keep |
-| backend auth header | Authorization $(servicenow-auth) | Token $(nhc-cts-auth) | Authorization $(erp-ameruser-auth) + REST-Framework-Version '4' |
+| backend auth header | Authorization $(backend-auth) | Token $(backend-auth) | Authorization $(backend-auth) + REST-Framework-Version '4' |
 | forwarded headers (allowlist) | — | Token, rolename | — |
 | query params (allowlist) | — | inboxId,index,pageSize,language,userEmail | expand |
 | backend parse | inline json | inline json (use-content-type) | default apic-default-parsesettings (use-content-type) |
@@ -720,12 +955,13 @@ below referencing the path you wrote.
 After the file is written, print a short summary:
 
 ```
-✓ {ApiTitle} — APIC {2.0|3.0} definition generated → {x-ibm-name}_{version}.yaml
+✓ {ApiTitle} — APIC {2.0|3.0} definition generated → {x-ibm-name}_{version}.yaml   [apic-skill rev-W2]
 
+  pattern         {backend | wrapper (ACE/webMethods)}
   verb            {VERB} {operation-path}   (basePath {basePath})
   JWT validate    {on|off}   crypto: $({crypto-object})
   MW logging      {on|off}
-  ESB envelope    {on|off}
+  ESB envelope    {on|off  (wrapper → off, service-provided)}
   backend         {backend-target-url}
   request map     {yes (N fields)|no}