orbit-code-ai 0.1.0

package/skills/apic-api/SKILL.md

@@ -0,0 +1,645 @@
+---
+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/Qiwa 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.
+
+## Usage
+
+```
+/apic-api <ApiName> <GET|POST> <basePath> [description: params, backend URL, request/response fields]
+
+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.
+  --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)
+  --no-jwt              omit jwt-validate + Check Expiration + 400 throw (no token enforcement)
+  --no-logging          omit the middleware UpsertMDLogQ logging invoke (AmerApp-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)
+  --backend-type T      backend response handling: json|detect (default json; "detect" =
+                        content-type based, used by AmerApp)
+  --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")
+  --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
+                        (e.g. Token,rolename). Without this, header-control is blocklist [].
+  --query a,b,...       backend query params → invoke parameter-control allowlist AND paths query
+                        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)
+
+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; \
+    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`
+- `{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.
+- `{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-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)
+- `{pass-headers}` = `--pass-headers` (headers forwarded to backend, e.g. `Token,rolename`)
+
+Output filename: `{x-ibm-name}_{version}.yaml`
+
+---
+
+## Clarify before generating (do this FIRST)
+
+Some values are **unguessable and deploy-critical** — never fabricate them from the API name.
+Before generating, collect any of the following that the prompt did not supply, and **ask the user
+in a single batched follow-up** (alongside the 2.0/3.0 question). Do NOT invent plausible-looking
+values for these:
+
+- **OpenAPI version** — 2.0 or 3.0 (always ask if unspecified).
+- **Channel / app + basePath** — e.g. `/v1/AmerApp`. 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.
+  Only needed when JWT is enabled (default). Ask; 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.
+
+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.
+
+## Generation rules
+
+1. **The spec version is the user's choice — Orbit supports both 2.0 and 3.0 equally.** Never
+   silently assume a version. If `--openapi` was not passed and the user did not state a version,
+   **ask** ("OpenAPI 2.0 or 3.0?") before generating. Then emit 2.0 from the skeleton below, or
+   apply the 3.0 transform section.
+2. **The `x-ibm-configuration.assembly` block is identical in 2.0 and 3.0.** Only the *contract*
+   (paths/definitions/security/schemes) changes between versions.
+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).
+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
+   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
+   silently strips query params at the gateway. The same param set appears as `in: query` entries in
+   `paths`. Likewise, any header forwarded to the backend (`--pass-headers`) goes in BOTH the invoke
+   `header-control` allowlist AND as an `in: header` path param.
+8. **Match policy variants to the backend, using the Policy variations reference.** Pick backend
+   `verb`/`backend-type`/`invoke-version`, the auth header name, parse form, and envelope placement
+   from the prompt; when unspecified, default to the skeleton (GET/POST, json, 2.2.0, Authorization,
+   inline json parse, in-case envelope). When in doubt about which shape a known backend uses, ask.
+9. **Logging must be consistent.** Unless `--no-logging`, emit BOTH the `Log-set-variable` and the
+   `Log-invoke` (UpsertMDLogQ) policies between Prepare Request and jwt-validate, and report
+   "MW logging on" in the summary. If you omit the block, report "off". The summary must always match
+   the assembly that was actually written.
+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
+    `?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
+    verbatim; if a block scalar (`|-` / `|2-`) is used, preserve its body exactly.
+
+---
+
+## OpenAPI 2.0 skeleton
+
+Assemble the file in this order. Fill `{slots}`; paste frozen fragments unchanged.
+
+```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 of the incoming request (AhelApp). Omit for GET. ──
+      # Place this as the FIRST policy, before logging, so message.body is parsed for the map.
+      - parse:
+          version: 2.2.0
+          title: parse
+          parse-settings-reference:
+            parse-settings:
+              document_type: json
+              max_value_length: 0
+              max_width: 0
+
+      # ── FROZEN: Prepare Request (RefId / CallerReqTime guard + custom headers) ──
+      - gatewayscript:
+          version: 2.0.0
+          title: Prepare Request
+          source: "var reqtime;\nvar RefId = \"\";\n\ntry {\n\tRefId = context.get('message.headers.RefId');\n}\ncatch(err) {\n\tRefId = null;\n}\n\nif (context.get('message.headers.CallerReqTime') == null) {\n\treqtime = new Date();\n}\nelse {\n\treqtime = context.get('message.headers.CallerReqTime');\n}\n\nif (RefId == null) {\n\tcontext.message.status.code = 400;\n\tcontext.message.status.reason = 'RefId is missing in the header';\n\tvar error = new Error('RefId is missing in the header');\n\terror.code = \"400\";\n\tcontext.reject('RefId is missing in the header', error);\n}\nelse {\n\tRefId = context.get('message.headers.RefId');\n}\n\nvar Chid = context.get('client.org.name');\nvar uuid1 = context.get('message.headers.X-Global-Transaction-ID');\n\ncontext.set('context.customheaders.CallerReqTime',reqtime);\ncontext.set('context.customheaders.RefId',RefId);\ncontext.set('context.customheaders.ChId',Chid);\ncontext.set('context.customheaders.ReqID',uuid1);"
+
+      # ── FROZEN: middleware logging — OMIT this set-variable + invoke if --no-logging ──
+      - set-variable:
+          version: 2.0.0
+          title: Log-set-variable
+          actions:
+            - set: message.headers.Authorization
+              value: $(nhc-mw-auth)
+              type: string
+      - invoke:
+          version: 2.0.0
+          title: Log-invoke
+          backend-type: json
+          header-control:
+            type: blocklist
+            values: []
+          parameter-control:
+            type: allowlist
+            values: []
+          timeout: 60
+          verb: POST
+          chunked-uploads: true
+          persistent-connection: true
+          follow-redirects: false
+          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)
+
+      # ── FROZEN: JWT — OMIT jwt-validate + Check Expiration if --no-jwt (then switch goes always-200) ──
+      - jwt-validate:
+          version: 2.0.0
+          title: jwt-validate
+          jwt: request.headers.authorization
+          output-claims: decoded.claims
+          jws-jwk: ''
+          jws-crypto: $({crypto-object})
+      - gatewayscript:
+          version: 2.0.0
+          title: Check Expiration
+          source: "\nvar tokenDate = context.get('decoded.claims.ExpirationDate');\nvar expirationDate = new Date(tokenDate);\n\n// Get the current time\nvar currentTime = new Date();\n\n// Check if the token has expired\nif (expirationDate <= currentTime) {\n    context.set('message.status.code',400);\n} else {\n    context.set('message.status.code',200);\n}"
+
+      - switch:
+          version: 2.0.0
+          title: switch
+          case:
+            - 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).
+                - set-variable:
+                    version: 2.0.0
+                    title: set-variable
+                    actions:
+                      - set: message.headers.{backend-auth-header}
+                        value: $({backend-auth-var})
+                        type: string
+                      # - set: message.headers.REST-Framework-Version   # example extra static header
+                      #   value: '4'
+                      #   type: string
+
+                # 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)
+                # 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)
+                      values: []
+                    parameter-control:
+                      type: allowlist
+                      values: []            # MUST list every backend query param ({query}); empty = params stripped
+                    timeout: 60
+                    verb: {verb}            # or "keep"
+                    http-version: HTTP/1.1
+                    chunked-uploads: true
+                    persistent-connection: true
+                    cache-response: protocol
+                    cache-ttl: 900
+                    websocket-upgrade: false
+                    # 2.3.0 only: stop-on-error: []   and   graphql-send-type: detect
+                    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).
+                - parse:
+                    version: 2.2.0
+                    title: parse
+                    parse-settings-reference:
+                      parse-settings:
+                        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,
+                # to top-level execute AFTER the switch and BEFORE the log policy.
+                - gatewayscript:
+                    version: 2.0.0
+                    title: Prepare Response Header
+                    source: "var code = context.get('message.status.code');\nvar reason = context.get('message.status.reason');\nvar output = context.get('message.body');\n\nvar response = {\n\t\"Header\": {\n\t\t\"ResTime\": new Date(),\n\t\t\"ChId\": context.get('context.customheaders.ChId'),\n\t\t\"RefId\": context.get('context.customheaders.RefId'),\n\t\t\"ReqID\": context.get('context.customheaders.ReqID'),\n\t\t\"Status\": {\n            \"Code\": code,\n\t\t\t\"Description\": reason\n\t\t}\n\t},\n\t\"Body\": output\n};\n\nsession.output.write(response);"
+            - condition: ($statusCode() = 400)
+              execute:
+                - throw:
+                    version: 2.1.0
+                    title: throw
+                    name: ExpiredToken
+                    error-status-code: '403'
+                    error-status-reason: forbidden
+                    message: JWT Token Expired
+
+      - log:
+          version: 2.1.0
+          title: log
+          log-level: default
+          mode: gather-and-send
+    finally: []
+    # ── FROZEN: catch (ExpiredToken + default), both write the ESB error envelope ──
+    catch:
+      - errors:
+          - ExpiredToken
+        execute:
+          - gatewayscript:
+              version: 2.0.0
+              title: ExpiredToken
+              source: |2-
+
+                    var code = context.get('error.status.code');
+                    var reason = context.get('error.message');
+                    var error = { "Header":{
+                    "ResTime": new Date(),
+                    "ChId": context.get('context.customheaders.ChId'),
+                    "RefId": context.get('context.customheaders.RefId'),
+                    "ReqID": context.get('context.customheaders.ReqID'),
+                    "Status": {
+                        "Code": code,
+                        "Description": reason
+                     }
+                }
+                };
+                context.message.statusCode = code;
+                session.output.write(error);
+      - default:
+          - gatewayscript:
+              version: 2.0.0
+              title: DeFaultCatch
+              source: |2-
+
+                    var code = context.get('error.status.code');
+                    var reason = context.get('error.message');
+                    var error = { "Header":{
+                    "ResTime": new Date(),
+                    "ChId": context.get('context.customheaders.ChId'),
+                    "RefId": context.get('context.customheaders.RefId'),
+                    "ReqID": context.get('context.customheaders.ReqID'),
+                    "Status": {
+                        "Code": code,
+                        "Description": reason
+                     }
+                }
+                };
+                context.message.statusCode = code;
+                session.output.write(error);
+  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:                   # path-level shared params (RefId may be required: true, Muamalaty)
+      - name: RefId
+        in: header
+        type: string
+        # required: true          # add when RefId is mandatory (Muamalaty)
+      - name: CallerReqTime
+        in: header
+        type: string
+    {verb}:                       # get: or post:
+      responses:
+        '200':
+          description: success
+          schema:
+            type: string
+      parameters:
+        # Emit, in this order:
+        #  1. one entry per backend query param ({query}); add `required: true` where mandatory
+        #     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)
+        - name: authorization
+          required: true
+          in: header
+          type: string
+        # - name: rolename        # example: custom forwarded header (Muamalaty)
+        #   required: true
+        #   in: header
+        #   type: string
+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 (see below)
+```
+
+---
+
+## 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
+copy through from input:
+
+```yaml
+                - map:
+                    inputs:
+                      input:
+                        schema:
+                          $ref: '#/definitions/Request'
+                        variable: message.body
+                    outputs:
+                      output:
+                        schema:
+                          $ref: '#/definitions/Request'
+                        variable: message.body
+                    actions:
+                      - set: output.customerSysId
+                        default: $(decoded.claims.SysId)   # claim-defaulted field (optional)
+                      - set: output.<field>
+                        from: input.<field>                # one per remaining body field
+                    version: 2.1.0
+                    title: map
+                    options:
+                      mapEmulateV4EmptyJSONObject: false
+                      mapEmulateV4DefaultRequiredProps: false
+                      mapEnablePostProcessingJSON: false
+                      mapReferenceLimit: 1
+                      mapResolveApicVariables: true
+                    parse-settings-reference:
+                      default: apic-default-parsesettings
+```
+
+```yaml
+definitions:
+  Request:
+    type: object
+    properties:
+      <field>:
+        type: string          # one per body field
+    example: >-
+      { "<field>": "<sample>" }
+```
+
+---
+
+## 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.
+
+### Logging invoke — two variants (omit entirely if `--no-logging`, AmerApp)
+
+**(a) v2.0.0 "json" (Muamalaty)** — 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)
+          follow-redirects: false
+          timeout: 60
+          parameter-control: { type: allowlist, values: [] }
+          header-control: { type: blocklist, values: [] }
+          inject-proxy-headers: true
+          persistent-connection: true
+          backend-type: json
+          output: outResp
+          keep-payload: true
+          chunked-uploads: true
+```
+**(b) v2.3.0 "detect" (AhelApp)** — preceded by its own `set-variable` setting `Authorization: $(nhc-mw-auth)`:
+```yaml
+      - invoke:
+          version: 2.3.0
+          title: log-invoke
+          backend-type: detect
+          header-control: { type: blocklist, values: [] }
+          parameter-control: { type: allowlist, values: [] }
+          http-version: HTTP/1.1
+          timeout: 60
+          verb: POST
+          chunked-uploads: true
+          persistent-connection: true
+          cache-response: protocol
+          cache-ttl: 900
+          stop-on-error: []
+          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)
+          output: logResp
+```
+
+### Backend invoke — v2.3.0 / detect / keep (AmerApp)
+Same as the skeleton invoke, but with these fields:
+```yaml
+                - invoke:
+                    version: 2.3.0
+                    title: invoke
+                    backend-type: detect
+                    header-control: { type: blocklist, values: [] }
+                    parameter-control: { type: allowlist, values: [expand] }
+                    http-version: HTTP/1.1
+                    timeout: 60
+                    verb: keep
+                    chunked-uploads: true
+                    persistent-connection: true
+                    cache-response: protocol
+                    cache-ttl: 900
+                    stop-on-error: []
+                    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 with forwarded headers (Muamalaty) — Token auth + allowlist
+```yaml
+                - set-variable:
+                    version: 2.0.0
+                    title: set-variable
+                    actions:
+                      - set: message.headers.Token
+                        value: $(nhc-cts-auth)
+                        type: string
+                - invoke:
+                    version: 2.2.0
+                    title: invoke
+                    backend-type: json
+                    header-control:
+                      type: allowlist
+                      values: [Token, rolename]
+                    parameter-control:
+                      type: allowlist
+                      values: [inboxId, index, pageSize, language, userEmail]
+                    timeout: 60
+                    verb: GET
+                    # ...rest as skeleton...
+                    target-url: >-
+                      $(nhc-cts-url)/CTSIPADUtilities/action/GetCorrespondences?userEmail=$(decoded.claims.EmailAddress)
+```
+
+### Multi-action set-variable (AmerApp) — auth + static framework header
+```yaml
+                - set-variable:
+                    version: 2.0.0
+                    title: set-variable
+                    actions:
+                      - set: message.headers.Authorization
+                        value: $(erp-ameruser-auth)
+                        type: string
+                      - set: message.headers.REST-Framework-Version
+                        value: '4'
+                        type: string
+```
+
+### Backend parse — named-default form (AmerApp)
+```yaml
+                - parse:
+                    version: 2.2.0
+                    title: parse
+                    parse-settings-reference:
+                      default: apic-default-parsesettings
+                    use-content-type: true
+```
+
+### Envelope placement — top-level (Muamalaty)
+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 |
+|---|---|---|---|
+| method | POST | GET | GET |
+| leading parse | yes | no | no |
+| logging | v2.3.0 detect | v2.0.0 json | none |
+| 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' |
+| 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) |
+| envelope placement | in-case | top-level | in-case |
+| switch version | 2.0.0 | 2.1.0 | 2.0.0 |
+
+---
+
+## OpenAPI 3.0 transform (`--openapi 3.0`)
+
+Keep `x-ibm-configuration` byte-identical. Transform **only the contract**:
+
+| 2.0 | 3.0 |
+|---|---|
+| `swagger: '2.0'` | `openapi: 3.0.0` |
+| `basePath: /v1/X` + `schemes: [https]` | `servers: [ { url: https://<host>/v1/X } ]` |
+| `securityDefinitions:` | `components.securitySchemes:` |
+| `definitions:` | `components.schemas:` |
+| body param (`in: body`, `schema`) | `requestBody.content.application/json.schema` |
+| response `schema:` | `responses.'200'.content.application/json.schema` |
+| `$ref: '#/definitions/Request'` | `$ref: '#/components/schemas/Request'` |
+| param `type: string` | param `schema: { type: string }` |
+
+> Both versions are first-class outputs. Note only that the target APIC/DataPower instance must
+> have OpenAPI 3.0 API support enabled to import a 3.0 file — a deployment fact for the user to
+> confirm, not a reason for Orbit to prefer one version over the other.
+
+---
+
+## After generating
+
+**Use the Write tool to create the file `{x-ibm-name}_{version}.yaml` in the current working
+directory** (the directory Orbit was launched in). Do NOT merely print the YAML to the terminal —
+the deliverable is a real `.yaml` file on disk. Write the full document, then print the summary
+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
+
+  verb            {VERB} {operation-path}   (basePath {basePath})
+  JWT validate    {on|off}   crypto: $({crypto-object})
+  MW logging      {on|off}
+  ESB envelope    {on|off}
+  backend         {backend-target-url}
+  request map     {yes (N fields)|no}
+
+Import into API Connect or publish to the DataPower API Gateway.
+```