@klok-integration/cli 0.7.302 → 0.7.314

package/THIRD-PARTY-NOTICES.md

@@ -437,6 +437,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+## cross-spawn@7.0.6
+
+Licence: MIT — https://github.com/moxystudio/node-cross-spawn
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
 ## deepmerge@4.3.1
 
 Licence: MIT — https://github.com/TehShrike/deepmerge
@@ -557,6 +585,35 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## eventsource@3.0.7
+
+Licence: MIT — https://github.com/EventSource/eventsource#readme
+
+```
+The MIT License
+
+Copyright (c) EventSource GitHub organisation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
 ## eventsource-parser@3.1.1
 
 Licence: MIT — https://github.com/rexxars/eventsource-parser#readme
@@ -838,6 +895,28 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## isexe@2.0.0
+
+Licence: ISC — https://github.com/isaacs/isexe#readme
+
+```
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
 ## jose@6.2.12
 
 Licence: MIT — https://github.com/panva/jose
@@ -958,6 +1037,50 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## path-key@3.1.1
+
+Licence: MIT
+
+```
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## pkce-challenge@5.0.1
+
+Licence: MIT — https://github.com/crouchcd/pkce-challenge#readme
+
+```
+MIT License
+
+Copyright (c) 2019 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## react@18.3.1
 
 Licence: MIT — https://reactjs.org/
@@ -1074,6 +1197,38 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## shebang-command@2.0.0
+
+Licence: MIT
+
+```
+MIT License
+
+Copyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
+## shebang-regex@3.0.0
+
+Licence: MIT
+
+```
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
 ## signal-exit@3.0.7
 
 Licence: ISC — https://github.com/tapjs/signal-exit
@@ -1190,6 +1345,28 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## which@2.0.2
+
+Licence: ISC — git://github.com/isaacs/node-which.git
+
+```
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
 ## widest-line@5.0.0
 
 Licence: MIT

package/assets/agents/knowledge/glossary.md

@@ -9,13 +9,18 @@ it as the source does.
 | Klok | The integration platform the documented project runs on (iPaaS): Camel routes on Quarkus, an Apache Pulsar broker, datamodels, and the portal klok.dev |
 | ODL | Operative Data Layer: the platform's store for datamodel objects, keyed by the object's datamodel type and an id, per tenant; routes write, read and search it (backed by OpenSearch) |
 | Claim check | A large payload stored in the platform's object storage; the message carries only a reference to it (a `klokcc://` URI) instead of the bytes |
-| Broker, topic | Apache Pulsar. A topic is named `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]` and carries CloudEvents whose data is a datamodel |
+| Broker | The platform's one central Apache Pulsar service, its storage included: the point every system talks to instead of to each other. Klok has no mesh of brokers or sidecars: say the broker |
+| Topic | A named, persisted, ordered log on the broker, `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`, owned by the publisher's tenant; it carries CloudEvents whose data is one datamodel. A topic is never called a queue |
+| Subscription | A reader's named cursor on a topic, named after its route id. Its type decides how the topic is read: `exclusive` or `failover` as a stream (one consumer, strict order), `shared` as a queue (competing consumers, each message goes to one of them and the order is given up), `key_shared` as a stream per key (order within a key, parallel across keys). Several subscriptions on one topic each get every message (publish/subscribe) |
 | CloudEvent | The standard envelope of every broker message: id, type, source, time, and the datamodel as data |
-| DLQ | Dead letter queue: `<topic>_DLQ`, where a message goes after its retries are exhausted |
+| DLQ | Dead letter topic `<topic>_DLQ`, where a message goes after its retries are exhausted; it is provisioned with its topic |
 | Tenant | An organisation on the platform, and its security boundary; every topic, ODL object and GitLab group belongs to one tenant |
 | Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
 | Route, route id | One Camel route per Java class (except a `KlokRestApi`, one per operation, and a `KlokRuntimeInstanceRoute`, one per instance `<RouteId>#<instanceKey>`). Its id is `<TENANTSHORT><NNN><LEG><seq>_<Description>`, for example `KLK007T1_PublishKlokStandard`; the class name is the id |
-| Leg | The letter in a route id: I ingress (onramp, brings data in), P processing, E egress (offramp, delivers data out), A API, S sub route, T timer |
+| Leg | The letter in a route id: I ingress, P processing, E egress, A API, S sub route, T timer |
+| Ingress, egress | An ingress is a route that takes a message from outside the platform onto the broker; an egress takes a message off the broker to the outside. An ingress is an onramp or a channel adapter, an egress an offramp or a channel adapter. As a word for a service (`klok-postmark-ingress`) it says what the service is, never a permission |
+| Onramp, offramp | An onramp is an ingress with mapping: the system's own format (class X) becomes a platform model (class A, B or C) before it reaches the broker. An offramp is an egress that maps a platform model to the receiving system's format at the last moment |
+| Channel adapter | An ingress or egress that only converts the protocol (HTTP to the broker, the broker to SFTP); the payload stays as it was received. Good design when it is motivated, for example receiving with minimal handling so that no call is lost while a later leg maps; a system's format put on the broker without such a reason is an anti-pattern |
 | Tenant short name | `TENANTSHORT`, three upper case letters that start every solution and route id of a tenant: the first three consonants of the tenant's name (`KLK` for klok, `DGR` for degerfors), decided by the platform |
 | Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007`. The id is allocated once, by a merge request in the tenant's `integration-solutions` registry, and never reused; a solution is reserved, active or retired |
 | Solution document | The `README.md` of a solution in the tenant's `integration-solutions` registry: its services, legs and flows, kept true to what is built |

package/assets/agents/knowledge/platform-rules.md

@@ -12,9 +12,20 @@ documentation or the dependency catalog can give you.
   possible by hand in GitLab.
 * Systems talk to the broker, never to each other. Point-to-point calls, a shared database or a shared file system
   between systems are not a Klok design.
-* Transform at the edge. When data from one system is to reach other systems or domains, the ingress transforms
-  it from the system's format to a class C or B model, and the egress transforms it to the receiving system's
+* Ingress and egress are the routes that take messages from outside onto the broker and off the broker to the
+  outside. An ingress is an **onramp** (with mapping: system format X to a platform model A, B or C) or a
+  **channel adapter** (protocol conversion only, the payload stays as received); an egress is an offramp or a sink
+  channel adapter.
+* Transform at the edge. When data from one system is to reach other systems or domains, the onramp transforms
+  it from the system's format to a class C or B model, and the offramp transforms it to the receiving system's
   format at the last moment. Replacing a system then changes only its own ingress and egress.
+* A channel adapter that puts a system's format on the broker is good design when it is motivated: you receive
+  with as little handling as possible so that no call from the system is lost, the message waits safely on the
+  topic (it can be processed again, or wait for a receiving system that is down), and a later processing leg or
+  egress maps it. The solution document says why, which leg maps, and that no other system or domain reads the X
+  topic. Example: Postmark inbound mail in KLK006, received by a channel adapter in `klok-postmark-ingress` so that a support mail never bounces while a product is redeployed. Letting class X onto the broker carelessly and without such a
+  reason is an anti-pattern and breaks Klok best practice; ask of every ingress "onramp or channel adapter, and
+  why?" (https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/ingress-and-egress/).
 * Prefer fact events (the whole object) over notifications (an id only).
 * Hierarchy: tenant (the security boundary; every topic, ODL object and GitLab group belongs to one), then domain
   (a business area inside the tenant). Domain `common` is shared by the tenant's domains, `public` is open to
@@ -45,7 +56,8 @@ documentation or the dependency catalog can give you.
   * out of the platform: `KlokOfframpRoute`, `KlokOfframpRouteSync` (serves requests from the broker),
     `KlokOfframpRouteWithResult`;
   * on the broker: `KlokProcessingRoute`, `KlokSchemaUpgradeBridge` / `KlokSchemaDowngradeBridge`;
-  * protocol only, same payload: `KlokChannelAdapterSourceRoute` / `KlokChannelAdapterSinkRoute`;
+  * protocol only, the payload as received (a channel adapter, see the principles): `KlokChannelAdapterSourceRoute`
+    / `KlokChannelAdapterSinkRoute`;
   * APIs: `KlokRestApi` with one `KlokRestApiHandlerRoute` per operation; a SOAP API is a `KlokCustomRoute` with
     camel-cxf; long-running work is a `KlokAsyncTaskWorkerRoute` behind a 202 with a task reference;
   * everything else: `KlokCustomRoute`; reusable pieces: `KlokSubRoute`, `KlokEnrichSubRoute`.
@@ -99,6 +111,11 @@ documentation or the dependency catalog can give you.
   When the content belongs to one reader, the publisher may choose that reader's tenant slug as the purpose
   (`persistent://konvoj/hr/PersonnelScheduleExportV1_degerfors`); that is the publisher's choice, not a condition
   for reading across tenants.
+* The topic stores, the subscription decides how it is read. A topic is always a persisted, ordered log; whether its
+  reader behaves like a stream or a queue is the subscription type (`<RouteId>.subscription.type`): `exclusive`
+  (the default) or `failover` read it as a stream in strict order, `shared` as a queue with competing consumers (the
+  order is given up), `key_shared` as a stream per message key. Every subscription on a topic gets every message, and
+  the framework dead letters to `<topic>_DLQ` whatever the type.
 * Request/reply: `ReqRes_<Request>_<Reply>[_<purpose>]_Request` and `_Response`. Dead letters: `<topic>_DLQ`.
 * One datamodel per topic. A breaking change is a new major version and therefore a new topic.
 * Topics are provisioned from Git; the broker never creates one by itself. A topic exists when its owning tenant's

package/assets/agents/knowledge/retired-patterns.txt

@@ -14,6 +14,11 @@
 (?i)class X on the (mesh|broker) # all four datamodel classes may go on the broker; transform at the edge is about readers
 (?i)class B \(Global\) # class B is "common", shared across the tenant's domains
 #
+# Klok has one central broker, not a mesh (2026-10-22): say the broker, a topic or a subscription.
+(?i)\b(the|an?|klok|event|events|integration|async|asynchronous|event-driven|message-based|service) mesh\b # Klok has one central broker, not a mesh: say the broker, a topic or a subscription
+(?i)\b(mesh(en|ens|et|ets)|meddelandemesh(en)?|klok-mesh(en|ens)?)\b # Klok har en central broker, ingen mesh: skriv brokern, en topic eller en subscription
+(?i)\bmesh[- ](theory|teori)\b # the chapter is event-driven integration; Klok has one central broker, not a mesh
+#
 # Route ids are <TENANTSHORT><NNN><LEG><seq>_<Description>, legs I P E A S T.
 \bS<(NNNN|ID|SolutionID|Solution|NNN)> # old S-prefixed integration ids; use <TENANTSHORT><NNN><LEG><seq>_<Description>
 \bS[0-9]{4}[IEP][0-9] # old S-prefixed route id such as S0001I1; use KLK002I1_... style ids

package/assets/agents/knowledge/roles/integration-architect.md

@@ -86,7 +86,10 @@ Into the platform:
 * A webhook sender: `KlokWebhookOnrampRoute`.
 * The caller needs a full business reply now: `KlokOnrampRouteSync`. Call it coupling and debt, with an aggressive
   timeout.
-* Same payload, protocol only: `KlokChannelAdapterSourceRoute`.
+* Same payload, protocol only: `KlokChannelAdapterSourceRoute`. Either the payload already is the model its readers
+  need, or receiving with minimal handling is the point (no call may be lost, the message must wait on the topic
+  for a receiver that is down) and a later leg maps. Write the reason in the solution document; a system's format
+  let onto the broker without one is the anti-pattern.
 
 Out of the platform:
 
@@ -176,6 +179,13 @@ synchronous bridge, a timeout of about ten seconds, `[TACTICAL]` on the solution
 the target is down. The strategy-aligned alternative: `KlokOnrampRoute` answering 202 with a task reference, and the
 front end polling or listening on a websocket. If they keep the bridge, write down the debt and the unwind condition.
 
+**Postmark inbound mail for five products.** A support mail must not bounce because QuickRace is redeployed or
+down for a day of planned upgrade. Ingress: a channel adapter per account in
+`klok-postmark-ingress` (KLK006): receive the webhook, put the payload on a topic unchanged, answer Postmark once
+the broker has it. An egress per product delivers each message to the right inbox and maps there. The solution
+document names the reason and the mapping leg; no other domain reads the Postmark topic. That is a motivated
+channel adapter, not `[TACTICAL]`.
+
 **"The offramp can just read the CRM database for the e-mail field."** Reject: that couples the offramp to CRM's
 schema. CRM publishes customer facts; if the e-mail is missing, extend the fact event or add an enricher in
 processing against a master data API on the platform. No SQL credential crosses a domain boundary.

package/assets/agents/knowledge/roles/integration-developer.md

@@ -30,7 +30,9 @@ Walk it from the top; do not pick a base class from habit.
        (the egress then owns retries, dead letters and alerts);
      * a webhook: `KlokWebhookOnrampRoute`;
      * the caller needs a full business reply now: `KlokOnrampRouteSync`, hard coupling, use rarely;
-     * the payload already is the model the readers need, protocol only: `KlokChannelAdapterSourceRoute`.
+     * protocol only, the payload as received: `KlokChannelAdapterSourceRoute`, when the payload already is the
+       model the readers need, or when receiving with minimal handling is the motivated design and a later leg
+       maps (see *Channel adapters and APIs*).
    * Out of the platform:
      * transform into the target's format: `KlokOfframpRoute`;
      * same format: `KlokChannelAdapterSinkRoute`;
@@ -175,8 +177,12 @@ its own `retry.*`, `dlq.*` or `failure.*` keys; configure its caller.
 
 ## Channel adapters and APIs
 
-A channel adapter is a dumb pipe: the same payload over another protocol, only `fromUri()` and `toUri()`. As soon as
-a field is mapped it is an onramp or an offramp.
+A channel adapter only converts the protocol: the same payload over another protocol, only `fromUri()` and
+`toUri()`. As soon as a field is mapped it is an onramp or an offramp. Use a source channel adapter for a system's
+own format only for a reason the solution document states: you must accept every call without losing a message, so
+the route does as little as possible, the message waits on the topic, and a processing leg or the egress maps it
+later (Postmark inbound mail in KLK006). A system's format on the broker without that reason, read by other domains,
+is the anti-pattern the refusals below describe.
 
 `KlokRestApi` declares its operations in `get()`, `post()`, `put()` and `delete()`, one `KlokRestApiHandlerRoute`
 per operation; an operation's route id is `<ApiRouteId>.<verb><path>`. Errors are answered as JSON

package/assets/agents/skills/klok-cli/reference.md

@@ -35,6 +35,7 @@ Examples:
   klok agent plan KLK001 --change-request change.md
   klok agent serve
   klok bead report fortnox-egress-1 --status done --message "Merged MR !12"
+  klok code                       # the bundled terminal agent: tools in src/klokcode/, MCP from klokcode.jsonc
   klok agents init                # KLOK-AGENTS.md, harness rows, platform and tenant skills, the session hook
   klok agents update              # fetch the platform and tenant catalogs, write what moved, prune by marker
   klok agents update --check      # exit 5 when a catalog is outdated or missing, write nothing
@@ -600,6 +601,100 @@ Examples:
   klok ci timings --project "klok/integration/*" --no-logs
 ```
 
+## klok code
+
+```
+klok code [options] [command]
+```
+
+A small coding agent in the terminal: reads a task, calls tools, answers
+
+| Option | Description |
+|---|---|
+| `-m, --model <model>` | Model name (default: klokcode.jsonc `model`, then klok config klokerModel) |
+| `--base-url <url>` | OpenAI compatible base URL, without /chat/completions (default: Kloker) |
+
+### klok code run
+
+```
+klok code run [options] <message...>
+```
+
+Send one message, print the answer and exit
+
+| Argument | Description |
+|---|---|
+| `<message...>` | required |
+
+### klok code mcp
+
+```
+klok code mcp [options] [command]
+```
+
+Manage the MCP servers of ~/.config/klokcode/klokcode.jsonc, or $XDG_CONFIG_HOME/klokcode/klokcode.jsonc when it is set
+
+#### klok code mcp add
+
+```
+klok code mcp add [options] [name] [command...]
+```
+
+Add an MCP server: a remote one with --url, or a local one with the command after --, e.g. `klok code mcp add shop --url http://localhost:4141/mcp` or `klok code mcp add files -- npx -y @modelcontextprotocol/server-filesystem .`. Asks for what is left out.
+
+| Argument | Description |
+|---|---|
+| `[name]` | optional |
+| `[command...]` | optional |
+
+| Option | Description |
+|---|---|
+| `--url <url>` | URL of a remote MCP server |
+| `--header <KEY=VALUE>` | HTTP header for a remote MCP server (repeatable) |
+| `--env <KEY=VALUE>` | Environment variable for a local MCP server (repeatable) |
+
+#### klok code mcp list
+
+```
+klok code mcp list [options]
+```
+
+Connect to every MCP server and list its tools
+
+#### klok code mcp remove
+
+```
+klok code mcp remove [options] <name>
+```
+
+Remove an MCP server from the global configuration
+
+| Argument | Description |
+|---|---|
+| `<name>` | required |
+
+### klok code demo
+
+```
+klok code demo [options] [command]
+```
+
+Demo services for workshops
+
+#### klok code demo shop
+
+```
+klok code demo shop [options]
+```
+
+Start the demo shop: an MCP server with orders and e-mail, and a page showing both (Ctrl+C stops)
+
+| Option | Description |
+|---|---|
+| `--port <port>` | Port to listen on (default: `4141`) |
+| `--report-to <address>` | Address the orders ask for reports to be sent to (default: `rapport@extern-redovisning.example`) |
+| `--dry-run` | Log the mail instead of handing it to Postmark |
+
 ## klok datamodel
 
 ```

package/assets/agents/skills/klok-route/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: klok-route
-description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, topics and topic purpose, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
+description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, channel adapter, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, topics and topic purpose, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
 ---
 
 # Writing a Klok route
@@ -13,8 +13,12 @@ motivates.
 
 ## Steps
 
-1. **Pick the pattern.** Ingress from a system: `KlokOnrampRoute<SYS, DOM>`; transformation between datamodels:
-   `KlokProcessingRoute<IN, OUT>`; egress to a system: `KlokOfframpRoute<DOM, SYS>`; synchronous request/reply:
+1. **Pick the pattern.** Ingress from a system: an onramp, `KlokOnrampRoute<SYS, DOM>`, which maps; or a channel
+   adapter, `KlokChannelAdapterSourceRoute<MODEL>`, which only converts the protocol, when receiving with minimal
+   handling is the motivated design and a later leg maps (the solution document says why; a system's own format
+   let onto the broker without a reason is an anti-pattern,
+   https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/ingress-and-egress/); transformation
+   between datamodels: `KlokProcessingRoute<IN, OUT>`; egress to a system: `KlokOfframpRoute<DOM, SYS>`; synchronous request/reply:
    the `Sync` variants; REST: `KlokRestApi` plus one `KlokRestApiHandlerRoute` per operation; long running work:
    `KlokAsyncTaskWorkerRoute<REQ, RES>`; anything else: `KlokCustomRoute`.
 2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route. `<TENANTSHORT><NNN>` is the id of

package/assets/agents/skills/klok-solution/SKILL.md

@@ -45,7 +45,8 @@ shared platform service) in `klok/integration-solutions`.
 6. **Classify every service** the solution needs: *new project*, *new routes in an existing project*, *reused,
    slight change*, *reused as is*, *client change*. Name the repository of each.
 7. **Map the legs.** For every route: id (`<TENANTSHORT><NNN><LEG><seq>_<Description>`, leg and sequence not used
-   before — `klok solutions check` reports duplicates), project, pattern base class, topics with their purpose,
+   before — `klok solutions check` reports duplicates), project, pattern base class (for an ingress: onramp or
+   channel adapter, and why — a channel adapter needs its reason and the leg that maps), topics with their purpose,
    datamodels and their class, task types, configuration keys, and how the legs interact (diagrams in the flows
    section). Route configuration and details stay in the project's `klok-docs/`; the solution links there.
 8. **Choose the technology deliberately.**