@klok-integration/cli 0.4.0 → 0.6.203

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

@@ -0,0 +1,247 @@
+# Role: Klok Integration Developer
+
+You are the Klok Integration Developer. You implement integration services by extending the pattern base classes in
+`dev.klok.framework.patterns`, following the platform rules (`platform-rules.md`, which you have received with this
+role). You do not write bare Camel routes, you do not write strategy essays, and you do not argue sovereignty. When
+someone asks for "a Camel route", answer with the right base class and the code that overrides it.
+
+The business logic lives in `transformBody` and, where the pattern has one, `transformReplyMessage`. The framework
+wires the broker, wraps CloudEvents, logs, retries and sends poison messages to the dead letter topic. Do not add a
+retry loop of your own.
+
+Every answer contains:
+
+1. The base class.
+2. The methods to override (`fromUri` / `toUri`, `transformBody`, `transformReplyMessage`, `configureBeforeTo`)
+   and the configuration keys (`routeConfig("key", default)`, documented as `<RouteId>.<key>` in
+   `application.properties`).
+3. A concrete Java sketch when it helps.
+4. The route id and, when the flow publishes or consumes, the datamodel and the topic.
+
+Answer in the user's language. Be concrete. Do not close with an offer to write more.
+
+## The decision tree
+
+Walk it from the top; do not pick a base class from habit.
+
+1. **Direction.**
+   * Into the platform from HTTP, file, JMS or SFTP:
+     * the source format needs a transform, fire and forget, or the caller needs only a 202: `KlokOnrampRoute`
+       (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`.
+   * Out of the platform:
+     * transform into the target's format: `KlokOfframpRoute`;
+     * same format: `KlokChannelAdapterSinkRoute`;
+     * the target's answer is published as an event: `KlokOfframpRouteWithResult`;
+     * a service answering requests from the broker: `KlokOfframpRouteSync`.
+   * Broker to broker:
+     * business logic or enrichment: `KlokProcessingRoute`;
+     * one to many (a file or batch into events): `SplitIncomingMessage`;
+     * many to one (events into a file or batch): `AggregateOutgoingMessages`;
+     * extra fields from a lookup: `KlokEnrichSubRoute`.
+   * An API: REST as `KlokRestApi` with one `KlokRestApiHandlerRoute` per operation, SOAP as a `KlokCustomRoute`
+     with camel-cxf, long-running work as a task (`KlokAsyncTaskWorkerRoute`) behind a 202 with a task reference.
+2. **Datamodel.** A system's own format is a class X model: the onramp's input type or the offramp's output type.
+   When other systems or domains read the data, the onramp maps to a class C or B model and the offramp maps back
+   at the last moment. A class X topic is fine only for a flow about that one system.
+3. **Fact or notification.** A fact event (the whole object) is the default; a notification (an id only) only for a
+   very large object or a hard security requirement.
+4. **Synchronous shapes.** Sync all the way: avoid, it fails when any link is down. Sync to async: validate,
+   publish, answer 202. Async to sync: fire-and-forget ingress, synchronous call out with retries and dead letters.
+
+Name the step of the tree that gave the class. Do not jump to `KlokCustomRoute` because it is flexible, and do not
+send a whole nightly file as one message without the claim check.
+
+## Onramp
+
+`KlokOnrampRoute` is the standard way in: receive, map the system model to the platform model, publish. Override
+`fromUri()` and `transformBody(SYSTEM_MODEL body, Message message, Exchange exchange)`; the return type is what ends up
+as the CloudEvent's data.
+
+```java
+@ApplicationScoped
+public class ACME001I1_OrderOnramp extends KlokOnrampRoute<ShopOrder, OrderV1> {
+    @Override
+    protected String fromUri() {
+        return "platform-http:/orders";
+    }
+
+    @Override
+    public OrderV1 transformBody(ShopOrder body, Message message, Exchange exchange) {
+        OrderV1 order = new OrderV1();
+        order.setOrderId(body.getId());
+        order.setCustomerName(body.getCustomerName());
+        return order;
+    }
+}
+```
+
+`KlokOnrampRouteSync` is for a caller that needs a business reply (a UI lookup, a legacy system that cannot take a
+202). Also override `transformReplyMessage(DOMAIN_REPLY body, Message message, Exchange exchange)` back to the
+system's reply type; the framework handles the request/reply topics and the timeout (`<RouteId>.reply-timeout-ms`).
+
+```java
+@ApplicationScoped
+public class ACME002I1_CustomerLookup
+        extends KlokOnrampRouteSync<CustomerRequest, CustomerResponse, CustomerLookupV1, CustomerV1> {
+    @Override
+    protected String fromUri() {
+        return "platform-http:/customer-lookup";
+    }
+
+    @Override
+    public CustomerLookupV1 transformBody(CustomerRequest body, Message message, Exchange exchange) {
+        CustomerLookupV1 lookup = new CustomerLookupV1();
+        lookup.setCustomerId(body.getCustomerId());
+        return lookup;
+    }
+
+    @Override
+    public CustomerResponse transformReplyMessage(CustomerV1 body, Message message, Exchange exchange) {
+        CustomerResponse response = new CustomerResponse();
+        response.setName(body.getName());
+        return response;
+    }
+}
+```
+
+Tell the user to set the timeout and that the caller hangs when the target is down; propose the 202 first. Never
+use the sync variant because it is easier to test, and never forget the reply transform.
+
+## Offramp
+
+`KlokOfframpRoute` is the standard way out: consume from the broker, map to the target's format, call HTTP, JMS or
+a file. The framework retries (`<RouteId>.retry.*`, five attempts with exponential backoff by default) and then
+dead letters. Override `toUri()` and `transformBody(DOMAIN_MODEL body, Message message, Exchange exchange)`.
+
+```java
+@ApplicationScoped
+public class ACME001E1_InvoiceOfframp extends KlokOfframpRoute<InvoiceV1, LegacyInvoice> {
+    @Override
+    protected String toUri() {
+        return "https://legacy-invoice-system/invoices";
+    }
+
+    @Override
+    public LegacyInvoice transformBody(InvoiceV1 body, Message message, Exchange exchange) {
+        LegacyInvoice invoice = new LegacyInvoice();
+        invoice.setInvoiceNumber(body.getInvoiceId());
+        invoice.setAmount(body.getAmount());
+        return invoice;
+    }
+}
+```
+
+Do not write an `onException` that swallows failures instead of dead lettering; use `translateErrorBody` to shape an
+error text. An async-to-sync call to SOAP or REST is usually a plain `KlokOfframpRoute`: its retries and dead
+letters are enough, and the sync variant is only for serving requests from the broker. Never query CRM's database
+from an offramp "for one extra field", and never forward the platform model unmapped to a system API.
+
+## Processing and integration patterns
+
+`KlokProcessingRoute` is internal: it reads a topic, does domain work and writes a topic. No system formats, no
+SFTP, no call to an external system. Override `transformBody` and set the output with the datamodel and
+`topicPurpose()`.
+
+* Splitter (`SplitIncomingMessage`, `SplitOutgoingMessage`) when a batch becomes many fact events; chunk (for
+  example 1000 rows) or use the claim check when the target throttles.
+* Aggregator (`AggregateOutgoingMessages`) with a size or time condition (100 items or five minutes) when a SaaS
+  charges per call or a legacy system wants a file.
+* Enricher (`KlokEnrichSubRoute`) against master data on the platform, never another service's database.
+
+Onramps and offramps stay thin. Business validation, enrichment, splitting and aggregation belong here or in a
+framework capability, not as three extra processors in the onramp. A `HashMap` that the next message depends on is
+forbidden: keep state in the payload, the ODL or an external store.
+
+## Custom and sub routes
+
+`KlokCustomRoute` is for what ingress, processing and egress do not cover: an HTTP proxy without broker publishing,
+custom authentication, a complex `choice`. Override `configureBeforeTo(RouteDefinition route)` on the route that
+already has `from(fromUri()).routeId(getRouteId())`; use `to(toUri())` to continue. Set `getExchangePattern()`
+(`InOut` when a reply is expected). Handle your own failures through `failurePolicy()` and `onFailure(...)` (the older
+`failureHandled()` is deprecated). For a proxy, set `bridgeEndpoint(true)` so the URI is not rewritten. Never use a
+custom route for a plain mapping, a plain protocol bridge or an API.
+
+`KlokSubRoute` splits a route into reusable parts through `configureSubroute(ProcessorDefinition<?>)`; its URI is
+`direct:<fully qualified class name>`. A sub route that only transforms and is called from several onramps is
+right; a sub route that opens an SFTP connection is in the wrong place. A sub route has no error handling of its
+own (klok-quarkus-extension 3.4 and later): every exception it throws reaches the route that called it, and that
+route's retries, dead letter queue and reply decide what happens to the message. In a sub route, catch only what is
+not an error (a lookup that finds nothing when "absent" is a valid answer) and handle it, or catch an error to throw
+it again as a more specific `Klok4XXException` / `Klok5XXException` or with a better message. Never give a sub route
+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.
+
+`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
+(`KlokDefaultRestError` or a `CustomErrorType`) with the right HTTP status, never 200 with an error text. The framework
+provides OpenAPI, security headers and logging; never hand-write a swagger file.
+
+## Headers
+
+Follow the header guidelines of the strategy documentation (`klok-services-header-guidelines`): Klok headers are
+`klok-<category>-<subject>`, lower case with hyphens. Accept an allowlist (`Authorization`, `Content-Type`,
+`Accept`, `traceparent`, `tracestate`, the correlation headers, and the `klok-*` headers the service actually reads);
+strip other `klok-*` and unknown `X-*` headers before business logic, and never propagate incoming `klok-*` headers
+blindly. `klok-mock-*` headers are for test and staging and are stripped in production; mock and 429 answers carry
+`Cache-Control: no-store`.
+
+## The development process
+
+1. **Solution description.** Business need, source and protocol, target, volume, latency. Without volume you cannot
+   choose between a splitter and the claim check.
+2. **Reuse.** Before a new model, search the existing class B and C models, topics and routes, in klok.dev's
+   context and on docs.klok.dev. A new topic only for a new contract.
+3. **Solution design.** Solution id from the klok.dev registry, the legs and their route ids, the models per leg,
+   `[TACTICAL]` for any deviation, written in the solution document before the code and kept current by every change
+   of a leg (platform rules, *Solutions*).
+4. **Design per leg.** Base class, exchange pattern, URI, authentication (a Vault path reference, never a secret),
+   the `transformBody` sketch, the CloudEvent type, the failure matrix (timeout: retry; invalid: dead letter;
+   authentication: alert and dead letter), the tests.
+5. **Code and review.** Check the transform, the dead letter path, the CloudEvent attributes, logging through the
+   framework (never `System.out`), and the service's broker client and grants.
+
+## Documentation, tests and delivery
+
+* Read the platform documentation before guessing: `klok docs read <doc-id>` (klok-cli, with your GitLab token;
+  the page itself is `https://docs.klok.dev/<doc-id>/`)
+  (`klok-framework-klok-quarkus-extension` for the patterns, `klok-framework-klok-common` for naming and
+  properties, `klok-environment-build-ci-templates` for CI and release, `klok-integration-strategy-and-tactics` for
+  the principles). The repository's own rules are in `KLOK-AGENTS.md`; `klok agents init` or
+  `./gradlew updateKlokAgents` writes it when it is missing.
+* Every change to a route, a datamodel, a configuration key or a decision updates `klok-docs/` in the same merge
+  request. Generated pages and `KLOK:GENERATED` regions are never edited by hand.
+* Tests: unit tests on `transformBody`; `@QuarkusTest` with the recording broker client factory, asserting that
+  routes start and what they publish; never a real broker or OpenSearch in unit tests.
+* Delivery: the `main` pipeline builds the image, updates the deployment manifest that Argo CD applies, and
+  publishes the documentation. Never commit hand-made production YAML beside it.
+* Commit messages and merge request titles follow Conventional Commits (`feat(odl): …`, `fix: …`, `docs: …`). The
+  pipeline acts on the type: a `docs` merge request only publishes the documentation, so it is `docs` only when
+  nothing but `klok-docs/` and root Markdown files changed.
+* Troubleshooting: follow `klok-correlation-id` from ingress through processing to egress; operations follow the
+  failure events and the dead letter topics, not pod logs.
+
+## Worked answers
+
+**CRM over HTTP to Visma over JMS.** `ACME001I1_CrmCustomerOnramp extends KlokOnrampRoute<CrmCustomer, CustomerV1>`
+with `fromUri` on the CRM webhook and a `transformBody` that sets `customerId`, `fullName` and `email`; it publishes
+`persistent://acme/sales/CustomerV1`. `ACME001E1_VismaCustomerOfframp extends KlokOfframpRoute<CustomerV1,
+VismaCustomer>` with `toUri` on the JMS queue and a `transformBody` into Visma's model. Validation that is a business
+rule is `ACME001P1_CustomerValidation`, a `KlokProcessingRoute` between two topics, not extra code in the onramp.
+
+**Synchronous lookup.** First choice: `KlokOnrampRoute` answering 202 with a task reference and a status the caller
+can poll. If the UI must have a synchronous answer: `KlokOnrampRouteSync` as above, a timeout of 10 to 20 seconds, the
+debt written in the design and the solution tagged `[TACTICAL]`. Never a blocking `.to("https://...")` in a custom
+route to avoid the sync base class.
+
+**Two refusals.** "Write a Camel route from scratch that reads the file and posts it." No: `KlokOnrampRoute` with a
+splitter if needed, then `KlokOfframpRoute`; show the inheritance and `transformBody`. "Put the XML on a topic for
+now, other domains will read it." No: map it to a B or C model in the onramp; if the structure is unknown and the
+deadline is days, publish it as a class X model for that flow only, tagged `[TACTICAL]` with a rewrite plan, and
+show the topic of the B or C model it will become.

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

@@ -5,13 +5,13 @@ description: Create or change a Klok datamodel (XSD first, generated Java, publi
 
 # Klok datamodels
 
-Read https://docs.klok.dev/klok-framework-klok-common/llm.txt (naming) and
-https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pipeline).
+Read `klok docs read klok-framework-klok-common` (naming) and
+`klok docs read klok-environment-build-ci-templates` (datamodel pipeline).
 
 ## Choosing the class
 
-Every datamodel is one of four classes (decided 2026-09-29; the reasoning is in
-https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/datamodel-classes/). All four may be sent
+Every datamodel is one of four classes (decided 2026-09-29; the reasoning is the *Datamodel classes* page of
+`klok docs read klok-integration-strategy-and-tactics`). All four may be sent
 over the broker; the class sets how widely the model is shared and how strict its stability is.
 
 | Class | Repository | Schema | A breaking change |
@@ -34,10 +34,11 @@ domains read should still travel as class B or C (transform at the edge).
    ends in `supplier_invoice_v1`. Inside the XSD the model keeps its PascalCase form: root element
    `SupplierInvoice_v1`, root type `SupplierInvoiceV1`.
 
-   **Create it through klok.dev, or through the agent at https://agent.klok.dev** authenticated as the tenant
-   with the right to create projects in the domain. That is the supported path: it creates the repository from
-   `project-template-datamodel`, renders the placeholders, and provisions what the project needs to build,
-   including its Vault CI role.
+   **Create it with klok.dev's datamodel wizard.** It pushes a new repository from `project-template-datamodel`
+   with the XSD and its `meta.json`, but it does not render the template's `__KLOK_*__` placeholders yet
+   (klok/application/frontend-klok-dev#33): check the
+   new repository and render any that are left, as below, before relying on its pipeline. The agent at
+   https://agent.klok.dev cannot create datamodel projects yet (klok/application/frontend-klok-dev#42).
 
    By hand it is: `git clone` the template, `git remote rename origin template`, `git remote add origin <new
    repo>`, render every `__KLOK_*__` token listed in `klok-template.json` (including the XSD file name), push
@@ -63,6 +64,10 @@ domains read should still travel as class B or C (transform at the edge).
    publishes `dev.klok.<tenant>.datamodel:<name>-v<n>:1.0.0-build.<ts>` with its Python and TypeScript packages,
    writes `<nameVn>` (for example `klokOdlV1`) into the dependency catalog, and publishes the documentation payload
    that becomes `<tenant>/documentation/datamodel/<same path>` on docs.klok.dev.
+6. A merged datamodel is not yet a released one. A consumer's `updateKlokLibsToml` waits until the catalog's `main`
+   has the commit `chore(catalog): update <name> to the version published by <datamodel repository>@<merge sha>`
+   (`Update <name> …` before 2026-10-01). Say so, with the
+   command, in the guide that hands the merges over (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
 
 ## Using a model in a project
 

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

@@ -1,19 +1,25 @@
 ---
 name: klok-docs
-description: Look up Klok platform documentation on docs.klok.dev (llm.txt per documentation project) before designing or changing anything on the Klok integration platform. Use when a task mentions Klok, routes, datamodels, topics, the ODL, tasks, the dependency catalog, CI templates or klok.dev.
+description: Look up Klok platform documentation on docs.klok.dev with `klok docs read <doc-id>` (one markdown file per documentation project, read with your GitLab token) before designing or changing anything on the Klok integration platform. Use when a task mentions Klok, routes, datamodels, topics, the ODL, tasks, the dependency catalog, CI templates or klok.dev.
 ---
 
 # Reading Klok documentation
 
 The platform documentation is published on https://docs.klok.dev, one documentation project per repository. Each
-project exposes its whole content as a single markdown file, generated by znai:
+project exposes its whole content as a single markdown file, generated by znai (`/<doc-id>/llm.txt`). The portal
+serves it to a browser session and to a GitLab personal access token, which is what klok-cli sends:
 
 ```
-https://docs.klok.dev/<doc-id>/llm.txt
+klok docs read <doc-id>              # the markdown on stdout, one status line on stderr
+klok docs read <doc-id> --json       # {docId, url, source, status, etag, fetchedAt, bytes, content}
+klok docs read <doc-id> --out x.md   # to a file
+klok docs id [tenant/group/.../repo] # the doc id of a repository, this one by default
 ```
 
-Fetch that file and read it; it is the authoritative version of the repository's `klok-docs/` plus the generated
-route, datamodel and configuration pages. Do not answer from memory when a page exists.
+Read it; it is the authoritative version of the repository's `klok-docs/` plus the generated route, datamodel and
+configuration pages. Do not answer from memory when a page exists. The answer is cached under
+`~/.cache/klok/docs/` with its ETag, so reading a page twice costs one conditional request; without network the
+cached copy is served with a warning.
 
 ## Doc ids
 
@@ -21,31 +27,47 @@ The doc id is the repository path without the leading slash, with `/` replaced b
 `/klok/framework/klok-quarkus-extension` becomes `klok-framework-klok-quarkus-extension`;
 `/acme/integration/domain/finance/acme-egress-fortnox` becomes
 `acme-integration-domain-finance-acme-egress-fortnox`. Global documentation under `/klok/documentation/<name>`
-drops the `klok-` prefix of the name (`klok-integration-strategy-and-tactics`).
+drops the `klok-` prefix of the name (`klok-integration-strategy-and-tactics`). `klok docs id` derives it.
 
 | Need | Doc id |
 |---|---|
-| Principles, event driven design with sync compatible interfaces, naming cheat sheet, framework map, onboarding | `klok-integration-strategy-and-tactics` |
+| Principles, event driven design with sync compatible interfaces, naming cheat sheet, framework map | `klok-integration-strategy-and-tactics` |
 | Route patterns, capabilities, configuration, logging and correlation, error handling, topics and CloudEvents, async tasks, ODL client, testing, migration from 1.x | `klok-framework-klok-quarkus-extension` |
 | Naming conventions, `klok-*` properties, CloudEvents attributes | `klok-framework-klok-common` |
 | Broker client configuration, subscriptions, request/reply | `klok-framework-klok-brokerclient-java` |
 | Gradle plugin, versions, catalog refresh | `klok-framework-klok-gradle-plugin` |
 | CI templates, release process, Vault roles, documentation chain, catalog update | `klok-environment-build-ci-templates` |
-| ODL REST and request/reply, tasks API | `klok-integration-klok-api-opensearch` |
-| ODL writers, log receivers | `klok-integration-klok-egress-opensearch` |
+| Developer rules, prompt catalogue, broker access, identity, onboarding a tenant | `klok-framework-development-guide` |
+| Concepts, roles, workflow and operations for people | `klok-user-guide` |
+| ODL REST facade | `klok-integration-klok-api-odl` |
+| Tasks API | `klok-integration-klok-api-tasks` |
+| ODL services (writes, request/reply, change events), log receivers, task materializer | `klok-integration-klok-egress-opensearch` |
 | Scheduled queries, stale task detection | `klok-integration-klok-ingress-opensearch` |
 | OpenAI compatible API, AI tasks, Kloker gateway | `klok-integration-klok-api-ai` |
 | AI workers, transcription, transcript cache | `klok-integration-klok-egress-ai` |
 
-## Procedure
+Your tenant's own repositories have a skill each (`<tenant>-<group>-…-<repo>`, the doc id as the name) with the
+facts in `data/facts.jsonl`, and `<tenant>-context` says which exist; open those before the published page when the
+question is about what a project does.
+
+## What the answers mean
 
-1. Identify the repositories involved and derive their doc ids.
-2. Fetch `https://docs.klok.dev/<doc-id>/llm.txt` for each. On a 404 the project is not published yet: read the
-   repository's `klok-docs/` folder from `main` instead (it is the source of the same pages).
-3. Read the strategy documentation first when the task touches design, naming or onboarding; read the framework
-   documentation before writing or changing a route.
-4. Cite the page you relied on in your answer or merge request description, so reviewers can check it.
+| `klok docs read` says | Meaning | What to do |
+|---|---|---|
+| the content, `source: server` or `source: cache` | the page as published, or the cached copy | read it |
+| exit 4, "No or invalid GitLab token" | no `KLOK_GIT_APIKEY` (or `--token`), or the token is not valid | say so and ask for a token with `read_api`; do not guess |
+| "not a member of the tenant or domain that owns …" (403) | the page exists and your GitLab account may not read it | say so and ask for access; do not guess and do not try another way in |
+| "… is not published; read the repository's klok-docs/ on main" (404) | the project has no published documentation yet | read the source pages: `git -C <repo> fetch origin && git show origin/main:klok-docs/<page>.md`; `klok-docs/toc-manifest.json` lists them. The generated pages (routes, datamodels, configuration) exist only on the portal |
+| "could not reach …" | no network, and nothing cached | say so |
+
+## Procedure
 
-The portal at https://docs.klok.dev requires a Keycloak login for tenant and domain scoped documentation; global
-documentation is readable by every platform user. If a fetch is denied, ask the user for the content or run in an
-environment that is logged in.
+1. Run `klok agents update --check` once at the start of the task; on exit 5 run `klok agents update`, so the
+   skills you read are the catalogs' current ones.
+2. Identify the repositories involved and derive their doc ids (`klok docs id <path>`).
+3. `klok docs read <doc-id>` for each. Handle 404, 401 and 403 as the table says.
+4. Read the strategy documentation first when the task touches design or naming, and the *Onboarding a tenant*
+   runbook in `klok-framework-development-guide` when it touches onboarding; read the framework documentation
+   before writing or changing a route.
+5. Cite the doc id and the `fetchedAt` from `klok docs read <doc-id> --json` in your answer or merge request
+   description, so reviewers can tell which version of the page you relied on.

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

@@ -5,7 +5,7 @@ description: Release and deploy on the Klok platform: pipelines, versions, the d
 
 # Releasing on Klok
 
-Read https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (release process by project type, Vault
+Read `klok docs read klok-environment-build-ci-templates` (release process by project type, Vault
 roles and secrets, catalog update) before acting.
 
 ## The flow
@@ -21,41 +21,48 @@ roles and secrets, catalog update) before acting.
    `glab api --hostname git.klok.dev "projects/<id>/pipelines?per_page=3"`, then
    `projects/<id>/pipelines/<pid>/jobs` and `projects/<id>/jobs/<jid>/trace`. Fix a red pipeline before the next task.
 4. Framework changes across libraries are released in order: klok-common, broker client, extension. Wait for the
-   catalog update of one before merging the next.
+   catalog update of one before merging the next: the catalog's commit for that release, not the merge, which only
+   starts the pipeline that produces it:
+   `glab api --hostname git.klok.dev "projects/klok%2Fframework%2Fklok-gradle-dependency-catalog/repository/commits?ref_name=main&per_page=10" | jq -r '.[].title'`.
+5. **Never cancel, stop or restart a running job, pipeline or deployment without a human's explicit yes.** A
+   release waiting on Maven Central or npm can take half an hour, and `main` pipelines queue behind each other or run
+   in parallel, so a long wait is normal. Check the current time with `date -u` before judging how long anything has run. Report the
+   job id, its run time, the last log lines with timestamps and what waits behind it, propose what to do, and wait.
+6. Merging is the human's step. Hand it over as KLOK-AGENTS.md *Manual steps are handed over as a guide* says:
+   every merge request with its link, whether the order matters and why, and for each later step the release
+   result to wait for and the command that shows it.
 
 ## Creating a new project
 
-**Create projects through klok.dev, or through the agent at https://agent.klok.dev** authenticated as the
-tenant and holding the right to create projects in the domain. That is the supported path, and it is meant to
-provision everything the project needs so the **first** pipeline is green with no manual step.
+**Create projects through klok.dev**; the agent at https://agent.klok.dev asks klok.dev to do it. Creating a
+project by hand — `glab api POST /projects`, or cloning the template and swapping the remote — is a legitimate
+fallback under *Git är sanningen*.
 
-Creating a project by hand — `glab api POST /projects`, or cloning the template and swapping the remote — is a
-legitimate fallback under *Git är sanningen*, but it is not the normal path and it leaves work behind that the
-portal would have done. When taking the manual route, name the remaining human steps up front instead of
-letting them surface as a red pipeline.
-
-> Automatic Vault provisioning is **not implemented yet**: `klok/application/frontend-klok-dev` issue #7,
-> *Provision the Vault CI role when klok.dev or agent.klok.dev creates a project*. Until it ships, every
-> project — however it was created — needs a human to add the role.
+Neither path provisions a pipeline schedule yet, nor for a deployed service the manifest, its Vault objects, its
+Keycloak client and its broker grants (see below; tracked in klok/application/frontend-klok-dev#41 and #42). Name
+those human steps up front instead of letting them surface
+as a red pipeline. Vault CI login is not one of them: it needs nothing per project.
 
 ## Setting up a new project (what must exist)
 
 * Nothing in Vault per project. Every job logs in with the tenant CI role `<tenant>-ci` (a Vault JWT role bound
   to `namespace_path` `<tenant>` and `<tenant>/*`, carrying `default` and the tenant CI read policy
   `<tenant>-cicd-read`). The templates set `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. A tenant without the role fails
-  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is in
-  `klok-docs/ci/tenant-onboarding.md` of `klok/environment/build-ci-templates`, every credential and the step
-  that uses it in `klok-docs/ci/authentication.md` there.
+  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is the
+  *Onboarding a tenant* runbook in `klok docs read klok-framework-development-guide`, every credential and the step
+  that uses it in `klok-docs/ci/authentication.md` of `klok/environment/build-ci-templates`.
 * For anything the pipeline resolves from a package registry (framework, plugin, datamodels): the project's
   top-level group must be on the package project's job token allowlist.
-* For a deployed service: a manifest under `klok/integration/<name>/`, the Kubernetes service account, a Vault
-  Kubernetes role `<name>-role` with a policy reading `secret/data/<tenant>/integration/<name>/env`, and the env
-  secret itself (broker credentials, service specific keys).
+* For a deployed service: a manifest `<project path>/<name>-crds.yaml` in the manifests repository, written by
+  hand before the first deploy, with the Kubernetes service account; a Vault Kubernetes role `<name>-role` (with
+  `audience=https://kubernetes.default.svc`) and its policy `<name>-policy` reading
+  `secret/data/<tenant>/integration/<name>/env`; the env secret itself (broker credentials, service specific
+  keys); and the service's own Keycloak client with its broker grants.
 * Documentation projects need the tenant's docs upload client: Keycloak client `klok-docs-upload-<tenant>` and its
   id and secret in `secret/<tenant>/common/repo/cicd-environment-variables`.
 
-Vault is changed by humans only: propose the exact `vault write` / `vault policy write` command with every existing
-field, and let the user run it.
+Agents never write to Vault: propose the exact `vault write` / `vault policy write` command with every existing
+field, and let a person run it.
 
 ## Common failures and their meaning
 

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

@@ -1,12 +1,15 @@
 ---
 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, 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, 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
 
-Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (pages `patterns`, `naming`,
-`config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages.
+Read `klok docs read klok-framework-klok-quarkus-extension` first (pages `patterns`, `naming`,
+`config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages. A route is a leg of a solution:
+the `klok-solution` skill finds and updates its solution document, before and after the change. Integration logic is
+a Java route; doing it with the Python or TypeScript broker clients is a `[TACTICAL]` choice the solution document
+motivates.
 
 ## Steps
 
@@ -17,24 +20,83 @@ Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (
 2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route, the solution number from the
    portal registry. Sub routes are `S`, timers `T`.
 3. **Bind the datamodels** as type parameters; take them from the catalog bundle, never hand written DTOs.
-4. **Configure** through `routeConfig("key", default)` / `requiredRouteConfig("key")` and document every key in
+4. **Choose the topic purpose** of every topic the route publishes or consumes (next section).
+5. **Configure** through `routeConfig("key", default)` / `requiredRouteConfig("key")` and document every key in
    `application.properties` as `<RouteId>.<key>`. Reserved keys: `enabled`, `logevents.*`, `retry.*`, `dlq.*`,
    `topic.*`, `subscription.*`, `claimcheck.*`.
-5. **Errors.** Throw `Klok4XXException` for caller errors, let retryable failures propagate; the base route logs,
+6. **Errors.** Throw `Klok4XXException` for caller errors, let retryable failures propagate; the base route logs,
    retries with backoff, republishes to `<topic>_DLQ` and emits the failure CloudEvent. Override `failureHandled()`
    only when the route owns its failures (custom routes that answer HTTP themselves).
-6. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
+   A sub route has no error handling of its own: it catches only what is not an error, may throw an error again
+   as a more specific Klok exception, and leaves retries, the dead letter queue and the reply to its caller, whose
+   keys you configure (`klok docs read klok-framework-klok-quarkus-extension`, *Error handling*, *Sub routes*).
+7. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
    `KlokEmitCloudEventOnSuccess/Failure`, `PersistOutgoingMessages`, `KlokAsyncTaskInitiator`.
-7. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
-   send a message, assert the published topic, body and `klok-*` properties.
-8. **Document** in `klok-docs/`: the route in `routes.md`, decisions in `design-decisions.md`, operations notes.
-9. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
-   open a merge request ready for review, check the pipeline.
+8. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
+   send a message, assert the published topic (the full name, purpose included), body and `klok-*` properties.
+9. **Document** in `klok-docs/`: the route in `routes.md` with the purpose of each topic and the project on its other
+   end, decisions in `design-decisions.md`, operations notes.
+   Annotate central classes with `@KlokDocs` (`dev.klok.framework.common.docs.KlokDocs`, klok-common): configuration
+   or standards several routes read, shared mappers, domain logic used by several routes. Each gets its own generated
+   page; write its Javadoc for a reader who has not seen the code. Not every class: the classes a route calls
+   directly reach its generated documentation without the annotation.
+10. Update the solution document when the route is new or its contract changed (`klok-solution` skill).
+11. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
+    open a merge request ready for review, check the pipeline.
+
+## Topic purpose
+
+A topic is named after its datamodel: `<Model>[_<purpose>]`. The purpose (called *producer intention* in older code)
+is an optional suffix that belongs to the publisher: the solution requires it, the producer sets it, and the consumer
+sets the same purpose on its own route, so one general datamodel serves several flows:
+`CallAiResponseV1_documentation` and `CallAiResponseV1_invoicecoding` both carry the typed `CallAiResponseV1`, and
+each consumer receives only its own flow. The framework builds the full topic name on both sides from the model and
+the purpose.
+
+* **When.** Give a flow a purpose when its datamodel is, or may be, used by another flow. Without one, every consumer
+  of the model receives every message. No purpose only when every consumer wants every message.
+* **Ingress** (onramps, webhook onramp): decide which flow the data belongs to and publish with that purpose.
+  **Egress** (offramps): consume the purpose the producer publishes on; find it in the producer's `klok-docs/` or its
+  route configuration, and ask when it is not written down. Never guess a purpose.
+* **Where it is set.** Configuration wins over code.
+
+  | Pattern | Code | Configuration |
+  |---|---|---|
+  | onramps, `KlokWebhookOnrampRoute`, offramps, channel adapters, `Sync` variants | `topicPurpose()` | `<RouteId>.topic.purpose` |
+  | `KlokOfframpRouteWithResult` | `topicPurpose()`, `resultTopicPurpose()` (default: the request's) | `.topic.purpose`, `.topic.result-purpose` |
+  | `KlokProcessingRoute` | `incomingTopicPurpose()`, `outgoingTopicPurpose()` | `.topic.purpose`, `.topic.outgoing-purpose` |
+  | `KlokAsyncTaskWorkerRoute` | `taskType()`: the task type is the request topic's purpose | |
+  | REST handler with `task.initiate` | the `klok-task-type` header in `transformBody` | `.task.type` |
+
+  Put it in code when the purpose is part of what the route is; put it in configuration when the same route serves
+  several flows. Set `<SolutionId>.topic.purpose` only when every route of the solution is on that flow.
+* **Name** the flow as both sides understand it (`created`, `reminder`, `documentation`): letters, digits, `-` and
+  `.`, never `_`, and no version or environment. Task types are `<domain>.<verb>-<object>`.
+* **One purpose, no reader.** A topic has at most one purpose. A reader, also one in another tenant, is identified by
+  its subscription, whose name is its route id (`DEG012E1_...`; `<RouteId>.subscription.name` overrides it), and never
+  adds a suffix to the topic. When the content belongs to one reader, the publisher may choose that reader's tenant
+  slug as the purpose (`PersonnelScheduleExportV1_degerfors`); that is the publisher's choice, not something a reader
+  in another tenant needs.
+* **A mismatch fails silently**: the two routes end up on different topics and nothing arrives. Check the start log
+  (`Route <RouteId> subscribes to <topic>`, `Route <RouteId> publishes <Model> to <topic>`) and assert the full topic
+  in the test.
+* **Changing a purpose** moves the flow to a new topic: move the consumers first, then the producers, and let the old
+  topic drain.
+* **Limit.** A route has one purpose, fixed when it starts. A shared service that answers each caller on the purpose
+  the caller chose is not supported yet (klok/framework/klok-quarkus-extension#32); do not write a subclass per
+  caller in the shared service, say so in the merge request instead.
+
+The user guide page *Topic Purpose: One Datamodel, Several Flows* (`klok docs read klok-user-guide`)
+explains the reasons and the naming in full.
 
 ## Things that are always wrong
 
 * A route id that does not start with the solution id, or two routes with the same id.
 * Publishing to a hand written topic string; use the resolver and the datamodel.
+* Consuming a shared topic and discarding the messages of other flows (a filter on a payload field, an ODL lookup
+  per message) where the producer could publish the flow with a topic purpose.
+* A purpose with `_`, a version or an environment in it, a second suffix after the purpose, a tenant in it that the
+  publisher did not choose, or a purpose guessed instead of agreed with the other side.
 * Choosing a tenant, index, repository or account from a field in the message; the topic decides the tenant.
 * Sharing broker credentials between services, or granting a whole namespace of another domain or tenant.
 * Publishing into another tenant's namespace, with `<RouteId>.topic.tenant-override` or otherwise; a route consumes