@klok-integration/cli 0.5.0 → 0.6.203

package/README.md

@@ -45,7 +45,7 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agent answer <taskId> --question <qid> --text "..."` | Answer a clarification and continue. |
 | `klok agent serve [--port 3091]` | Loopback MCP and A2A proxy for IDEs and other agents. |
 | `klok agents init` | Write the Klok agent instructions, the platform skills and your tenant's skills into a repository, with a Claude Code hook that keeps them fresh. |
-| `klok agents update [--check] [--global]` | Fetch what moved in the platform and tenant catalogs; `--check` exits 5 when something is outdated. |
+| `klok agents update [--check] [--global]` | Fetch what moved in the platform and tenant catalogs; `--check` writes nothing and exits 5 when something is outdated. |
 | `klok agents status` | Per file and per catalog: current, outdated, missing or unreachable. |
 | `klok bead list\|show\|report` | Progress beads in the current repository. |
 | `klok docs read <doc-id>` | Print a documentation project's `llm.txt` from docs.klok.dev, read with your GitLab token and cached. |

package/THIRD-PARTY-NOTICES.md

@@ -53,6 +53,18 @@ 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.
 ```
 
+## @klok-integration/brokerclient@0.3.114
+
+Licence: Apache-2.0 — https://git.klok.dev/klok/framework/klok-brokerclient-java/-/tree/main/typescript/klok-brokerclient-typescript
+
+_No licence file shipped with the package; see the project homepage._
+
+## @klok-integration/datamodel-klok-project-documentation-v1@1.0.0-build.260930043552
+
+Licence: Apache-2.0 — https://git.klok.dev/klok/datamodel/public/klok-project-documentation-v1
+
+_No licence file shipped with the package; see the project homepage._
+
 ## @modelcontextprotocol/sdk@1.30.0
 
 Licence: MIT — https://modelcontextprotocol.io
@@ -201,6 +213,32 @@ 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.
 ```
 
+## avsc@5.7.9
+
+Licence: MIT — https://github.com/mtth/avsc
+
+```
+Copyright (c) 2015-2017, Matthieu Monsch.
+
+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.
+```
+
 ## bundle-name@4.1.0
 
 Licence: MIT

package/assets/agents/AGENTS.documentation.md

@@ -7,8 +7,9 @@ content arrives here. There are two kinds, and they are edited differently:
 * **The documentation project of a source repository** (`<tenant>/documentation/<group>/.../<repo>`, mirroring the
   source path) is output. KlokDocumentationEgress (`klok/integration/klok-documentation-egress`, KLK007) builds it
   from the `KlokProjectDocumentationV1` payload the source repository's `main` pipeline publishes, replaces
-  everything under `docs/` on every run and commits the AI sections under `docs/_ai/`. Never edit it: a change made
-  here is overwritten by the next run. There are exactly two places to change it:
+  everything under `docs/` on every run and commits the AI sections under `docs/_ai/`. It reads only tenant klok's
+  payloads today (klok/integration/klok-documentation-egress#2). Never edit it: a change made here is overwritten by
+  the next run. There are exactly two places to change it:
   * `klok-docs/` in the source repository, in a merge request there: the hand written pages, their order and
     chapter titles (`toc-manifest.json`), and where an AI section appears (`<!-- KLOK:GENERATED:START <id> -->` …
     `<!-- KLOK:GENERATED:END <id> -->`);

package/assets/agents/AGENTS.integration.md

@@ -21,9 +21,10 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
 * Datamodels are the type parameters of the pattern class and come from the catalog bundles; never hand write DTOs
   for something a datamodel project should own.
 * A datamodel used in more than one flow gets a **topic purpose** per flow (`<Model>_<purpose>`, set with
-  `topicPurpose()` or `<RouteId>.topic.purpose`), agreed with the project on the other end and written in both
-  projects' `klok-docs/`. Never consume a shared topic and discard the other flows' messages. The `klok-route` skill
-  has the details.
+  `topicPurpose()` or `<RouteId>.topic.purpose`). The publisher sets it as the solution requires, the consumer
+  matches it, and both projects' `klok-docs/` write it down. A topic has at most one purpose; a reader is its
+  subscription (its route id), never a suffix. Never consume a shared topic and discard the other flows' messages.
+  The `klok-route` skill has the details.
 * Errors: throw `Klok4XXException` for caller errors (no retry) and `Klok5XXException` or plain exceptions for
   retryable failures; the framework retries, republishes to `_DLQ` and emits the failure event. Do not add
   `onException` blocks unless the route owns the failure (`failureHandled()`).
@@ -32,10 +33,12 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
 * Tests: `@QuarkusTest` with the recording broker client factory; assert routes started and published messages,
   never talk to a real broker or OpenSearch in unit tests.
 * A route that serves several tenants (a shared platform service) consumes each tenant's own request topic,
-  `<tenant>[_<env>]/common/<Model>`, from the subscription list klok.dev keeps in the klok ODL; it takes the tenant
-  from the namespace it received on and rejects a message whose payload or properties name another tenant. It never
-  picks an index, repository or account from a field in the message, and what it writes back for a tenant goes to
-  klok's namespace, one topic per tenant.
+  `<tenant>[_<env>]/common/<Model>`; it takes the tenant from the namespace it received on and rejects a message
+  whose payload or properties name another tenant. It never picks an index, repository or account from a field in
+  the message, and what it writes back for a tenant goes to klok's namespace, one topic per tenant. Today every
+  platform service is configured for tenant klok only, and the broker client has no topic list that can grow while
+  a service runs (klok/framework/klok-brokerclient-java#31, klok/application/frontend-klok-dev#53); say so in the
+  design instead of assuming one.
 * The service connects to the broker with a client of its own (`KLOK_BROKER_AUTH_CLIENT_ID`), granted `publish` and
   `consume` on its own tenant's namespaces only; a topic of another tenant is a `consume` grant on that one topic,
   reached with `<RouteId>.topic.tenant-override`. Never reuse another service's credentials.

package/assets/agents/AGENTS.workspace.md

@@ -23,13 +23,13 @@ klok docs id [tenant/group/.../repo]   # the doc id of a repository, this one by
 
 | Topic | Read |
 |---|---|
-| Platform principles, event driven design, naming, onboarding | `klok docs read klok-integration-strategy-and-tactics` |
+| Platform principles, event driven design, naming | `klok docs read klok-integration-strategy-and-tactics` |
 | Route framework (patterns, config, logging, errors, topics, tasks) | `klok docs read klok-framework-klok-quarkus-extension` |
 | Naming conventions, message properties, CloudEvents | `klok docs read klok-framework-klok-common` |
 | Broker client | `klok docs read klok-framework-klok-brokerclient-java` |
 | Gradle plugin, versions, catalog | `klok docs read klok-framework-klok-gradle-plugin` |
 | CI templates, release process, Vault roles | `klok docs read klok-environment-build-ci-templates` |
-| Developer rules: identity and access, Keycloak, Vault paths, certificates, infrastructure as code | `klok docs read klok-framework-development-guide` |
+| Developer rules: identity and access, Keycloak, Vault paths, certificates, infrastructure as code; onboarding a tenant | `klok docs read klok-framework-development-guide` |
 | How people use the platform: concepts, roles and access, workflow, operations | `klok docs read klok-user-guide` |
 | Infrastructure: stateful services, certificates, Ansible, Keycloak clients | `klok docs read klok-environment-klok-environment-setup` |
 
@@ -46,9 +46,10 @@ The `klok-docs` skill describes the lookup in detail. Cite the doc id you relied
 
 ## Tenant skills
 
-Next to the platform skills (`klok-docs`, `klok-route`, `klok-datamodel`, `klok-release`, `klok-worktree`) the
-skill directories hold your tenant's own skills, generated by KlokDocumentationEgress from every documentation
-publish in the tenant and served from the tenant's private catalog:
+Next to the platform skills (`klok-docs`, `klok-solution`, `klok-route`, `klok-datamodel`, `klok-release`,
+`klok-worktree`) the skill directories hold your tenant's own skills, generated by KlokDocumentationEgress from the
+tenant's documentation publishes and served from the tenant's private catalog. The egress reads only tenant klok's
+publishes today, so another tenant has no tenant skills yet:
 
 * `<tenant>-context` is the router: what exists in the tenant (repositories, systems, datamodels, topics,
   solutions), where it lives, and which skill to open for it. Start there. Its `data/` holds `projects.jsonl`,
@@ -79,7 +80,7 @@ it when a task touches the platform:
 
 * Klok knowledge is edited **only** in klok-integration-agent, `packages/cli/assets/agents/knowledge/`. Every other
   copy is generated and never edited: `knowledge/` next to an installed `KLOK-AGENTS.md`, the catalog's
-  `agents/knowledge/`, `build/generated/klok-knowledge/`, `generated/klok-knowledge/` and the copies in images.
+  `agents/knowledge/`, `build/generated/klok-knowledge/` and the copies in images.
 * A prompt, persona or agent instruction that needs the glossary or the platform rules loads the knowledge block.
   It never restates it.
 * Text that matches a line of `retired-patterns.txt` teaches a rule the platform no longer has; fix it at its source.
@@ -144,6 +145,32 @@ step by step procedure; the contract every agent follows is:
 * Repository discovery and sync (`klok sync`, workspace generators) exclude `<root>/worktrees`; a task tree is
   never a canonical repository.
 
+## Commits follow Conventional Commits
+
+Every commit in a Klok repository follows [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/),
+and so does every merge request title. The type says what kind of change it is, and the pipelines act on it: the
+Klok templates choose which jobs run from the type of the change.
+
+* The header is `<type>[(<scope>)][!]: <description>`: a lower case type, an optional scope naming the part that
+  changed, `!` for a breaking change, and a short imperative description (`feat(odl): add a scheduled query leg`,
+  `fix: take the tenant from the topic`, `docs(ci): explain the docs lane`). The body follows a blank line and says
+  why. Footers follow another blank line: `BREAKING CHANGE: <what breaks>`, `Refs: #12`, `Closes #7`.
+* Types: `feat` a new capability, `fix` a bug fix, `docs` documentation only, `refactor`, `perf`, `test`, `build`
+  (build system and dependencies, the catalog copy included), `ci` (pipeline configuration), `style`, `revert`, and
+  `chore` for anything else that changes no behaviour.
+* The merge request title is what `main` sees. Merge requests land as merge commits, and GitLab's default merge
+  commit message carries the title on its third line, where the template rules look. Give the merge request the
+  type of its whole change, not of its last commit.
+* `docs` must be true. It covers `klok-docs/`, the Markdown files at the repository root and the bead files under
+  `.beads/`, nothing else. A `docs` merge request in a project built from a Klok template skips the build, the
+  image, the release and the deployment and only builds and publishes the documentation; `klok ci docs-only` fails
+  its pipeline when any other file changed. A merge request that mixes documentation with anything else takes the
+  type of the other change.
+* A commit with no type, such as one made in the GitLab web editor, gets the full pipeline. So does a pipeline
+  started by hand (*Run pipeline*), by a schedule or through the API: that is how a change is built in full when it
+  was typed `docs` by mistake. The templates and the check are described on the *Change types* page of
+  `klok docs read klok-environment-build-ci-templates`.
+
 ## Versions come from the dependency catalog
 
 * Framework libraries, the gradle plugin and datamodels are released with timestamped versions from `main`
@@ -156,7 +183,7 @@ step by step procedure; the contract every agent follows is:
 
 ## Pipelines, secrets and infrastructure
 
-* After every push to git.klok.dev, check the pipeline (`glab api "projects/<id>/pipelines?per_page=3"`, job traces)
+* After every push to git.klok.dev, check the pipeline (`glab api --hostname git.klok.dev "projects/<id>/pipelines?per_page=3"`, job traces)
   and fix failures before moving on. Publishing, image pushes, manifest updates and catalog updates only happen on
   `main`; merge request pipelines build and test.
 * Container images are built without privileges, always. Every image job extends `.klok_image_build` from
@@ -166,16 +193,18 @@ step by step procedure; the contract every agent follows is:
   `COPY` layers and sets owners with `COPY --chown`, never `RUN chown -R`, so that a build stores only what
   changed. Read the *Container images* page of `klok docs read klok-environment-build-ci-templates`
   before changing a Dockerfile or an image job.
-* Vault (`vault.ipaas.se`) is changed by a human only. Agents may read to diagnose and must then propose the exact
-  command, including every existing field of the object.
-* New projects are created 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 and it provisions what the
-  project needs to build. Creating a project by hand is a legitimate fallback under *Git är sanningen*, but it is
-  not the normal path: say up front what a human will still have to do, rather than letting it surface as a red
-  pipeline. Vault needs nothing per project: the tenant CI role `<tenant>-ci` accepts every project under the
-  tenant's root group. A tenant without it fails every job at `auth/jwt/login` with
-  `role "<tenant>-ci" could not be found`; setting a tenant up is described in `klok-docs/ci/tenant-onboarding.md`
-  of `klok/environment/build-ci-templates`.
+* **Agents never write to Vault** (`vault.ipaas.se`). People write it, by hand or with the playbooks they run. The
+  only automated writer allowed is klok.dev's own provisioning identity, within its policy, and that identity does
+  not exist yet (klok/environment/klok-environment-setup#34). An agent may read to diagnose, and then proposes the
+  exact command, including every existing field of the object.
+* New projects are created through klok.dev (the agent at https://agent.klok.dev asks klok.dev), or by hand, which
+  is a legitimate fallback under *Git är sanningen*. Neither path provisions a pipeline schedule, a deployment
+  manifest, a Vault Kubernetes role, a Keycloak client or broker grants yet: say up front what a human still has to
+  do (the `klok-release` skill lists it), rather than letting it surface as a red pipeline (tracked in
+  klok/application/frontend-klok-dev#41). Vault CI needs nothing
+  per project: the tenant CI role `<tenant>-ci` accepts every project under the tenant's root group. A tenant
+  without it fails every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; setting a tenant up
+  is the *Onboarding a tenant* runbook in `klok docs read klok-framework-development-guide`.
 * Never push to `main` of an existing repository, never force push, never merge. Work on a branch and open a
   merge request that is ready for review; only a brand new repository gets its first commit on `main`. A draft
   merge request is not the default, it is what you open when the work is knowingly unfinished, and you say why.
@@ -188,6 +217,56 @@ step by step procedure; the contract every agent follows is:
   for Maven Central or npm can legitimately take half an hour. On 2026-09-29 an agent cancelled the Gradle
   plugin's release while it correctly waited for Maven Central, because it misread the time.
 
+## Manual steps are handed over as a guide
+
+Whatever a task leaves for a human (merging merge requests, a Vault write, an Ansible run, a Keycloak or cluster
+change, a decision) is handed over as a numbered step-by-step guide at the end of every answer that has such steps.
+Someone who did not follow the work must be able to carry it out without working anything out:
+
+* **What, why and how.** Each step says what to do and why, gives the exact commands in copyable code blocks (one
+  command per block, a dry run first where there is one, such as `ansible-playbook … --check --diff`), and says what
+  "done" looks like before the next step. Repeat the whole guide in the final answer, even when the steps were
+  mentioned earlier.
+* **Commands run as pasted, from any directory.** The person pastes a command into a terminal that is not in your
+  worktree, so a command never relies on the working directory to tell it where it is: `glab` takes its host from
+  the git remote of the current directory and otherwise falls back to gitlab.com, where every Klok project is a 404,
+  so every `glab api` command carries `--hostname git.klok.dev`. Run a command from a neutral directory such as
+  `/tmp` before you hand it over.
+* **Merging is a manual step.** List every merge request with its link and say whether the merge order matters and
+  why (the catalog before its consumers; klok-common, then the broker client, then the Quarkus extension; a
+  datamodel before the code that uses it), or say plainly that it does not.
+* **Wait for the result, not for the merge.** Pipelines on `main` may run in parallel, so never assume that one job
+  runs at a time or that a merge means a release. When a step needs what an earlier pipeline produces (a datamodel
+  or framework version in the dependency catalog, an image in the deploy manifest, the agent files in the catalog, a
+  staged npm package, a published documentation project), the guide says to wait for that result and gives the
+  command that shows it. The catalog records every release as a commit on its `main`
+  (`chore(catalog): update <name> to the version published by <repository>@<sha>`,
+  `chore(catalog): update klok-agents to <version>`; releases before 2026-10-01 have the same titles without the
+  `chore(catalog): ` prefix and with a capital `Update`):
+
+  ```
+  glab api --hostname git.klok.dev "projects/klok%2Fframework%2Fklok-gradle-dependency-catalog/repository/commits?ref_name=main&per_page=10" | jq -r '.[].title'
+  ```
+* **Hold points.** A plan that mixes agent work with such steps stops at numbered hold points, says exactly what the
+  human does there, and continues when they say so.
+
+## Design and maintenance start from the solution
+
+Every task that designs, builds, changes or fixes a service, an integration, an API or a route starts from the
+solution it belongs to, and new development and maintenance follow the same process (the `klok-solution` skill):
+
+* Find the solution from the route id prefix and read its document in `<tenant>/integration-solutions` on `main`;
+  `klok solutions check` says whether the document still matches the code. A new solution gets its id and its
+  document before its first route.
+* The document classifies every service (new project, new routes in an existing project, reused with a change,
+  reused as is, client change) and maps the legs: route ids, patterns, topics with purpose, datamodels.
+* Integration logic is Java Klok routes. Doing integration work with the Python or TypeScript broker clients, or
+  inside an application or an external engine, is a `[TACTICAL]` choice whose motivation, cost and removal condition
+  the solution document states. An external engine (a GPU model server, a vendor service) stays a simple REST
+  service; priority, retries, claim checks and task state live in a Java leg.
+* Every merge request that adds, changes or removes a leg brings the solution document to the new steady state, so
+  the registry describes the landscape that is built and deployed.
+
 ## Logic lives in the Klok tools, not in the pipelines
 
 * Klok functionality belongs in the Klok tools: **klok-cli** (`@klok/cli`), **the Klok Gradle plugin** and **the
@@ -212,8 +291,10 @@ step by step procedure; the contract every agent follows is:
   and the solution key.
 * Topics: `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`, request/reply
   `ReqRes_<Req>_<Res>_Request|_Response`, dead letters `<topic>_DLQ`. The datamodel major version is in the class
-  name (`CustomerV1`). The purpose is a flow that producer and consumer agree on, so one datamodel serves several
-  flows and each consumer reads only its own; it never contains `_`.
+  name (`CustomerV1`). The purpose is optional and the publisher's: the solution requires it so that one datamodel
+  serves several flows, and each consumer reads only the purpose of its flow. A topic has at most one purpose, and
+  the purpose never contains `_`. A reader is identified by its subscription, named after its route id, and never
+  appears in the topic name.
 * Context properties: `klok-correlation-id`, `klok-invocation-id`, `klok-parent-invocation-id`, `klok-task-id`,
   `klok-solution-id`, `klok-route-id`, `klok-tenant`, `klok-domain`, `klok-environment`; same spelling as HTTP
   header, Pulsar property and CloudEvents extension, `klok.`-prefixed as MDC key.
@@ -234,32 +315,45 @@ access, Keycloak broker clients or a service that serves several tenants.
   name and rejects a payload that claims another one.
 * **Write narrow, consume wide.** A tenant publishes only in its own namespace, `<tenant>[_<env>]/<domain>`; nobody
   holds `publish` in another tenant's namespace, not even on one topic. Reading elsewhere is a `consume` grant on a
-  named topic, approved by the owner and recorded in Git in the owning tenant. A topic read across tenants carries
-  its reader as the last purpose segment (`persistent://konvoj/hr/PersonnelScheduleExportV1_degerfors`).
-* **Platform services** (logs, the ODL, AI, mail, SMS, documentation) are shared klok workers that follow the same
-  rule: a tenant's requests live in the tenant's namespace (`persistent://<tenant>[_<env>]/common/KlokLogEventV5`)
-  and the worker is granted `consume` on exactly those topics, taking the tenant from the namespace; what the
-  platform writes back lives in klok's namespace, one topic per tenant (`klok[_<env>]/<domain>/<Model>_<tenant>`).
-  The worker subscribes to a list of topics kept in the klok ODL, never to a pattern. The ODL runs as one instance
-  per tenant.
+  named topic, approved by the owner and recorded in Git in the owning tenant. The topic keeps its own name; the
+  reader is known by its subscription (its route id, `DEG012E1_...`). 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.
+* **Platform services** (logs, the ODL, tasks, AI, documentation) are klok services, and today each one is
+  configured for tenant klok only (`klok.tenant=klok`; other tenants: klok/application/frontend-klok-dev#51). A
+  platform service that serves several tenants follows the same rule: a tenant's requests live in the tenant's
+  namespace (`persistent://<tenant>[_<env>]/common/KlokProjectDocumentationV1_prepared`), the service is granted
+  `consume` on exactly those topics and takes the tenant from the namespace, and what it writes back lives in klok's
+  namespace, one topic per tenant (`klok[_<env>]/<domain>/<Model>_<tenant>`).
 * **Identities:** one Keycloak client per running deployment, never shared, never used by a person; its Pulsar role
   is `service-account-<client id>`; one CI broker client per tenant; every broker client attaches the client scope
   `pulsar` (audience and the `nbf` claim Pulsar requires) instead of copying mappers.
 * **Grants:** `publish` and `consume` on the service's own domain and its tenant's `common`, as namespace grants;
   anything in another domain or tenant is `consume` on one topic, never `publish`, approved by its owner and
   recorded in Git in the owning tenant. Pulsar's `produce`/`consume` appear only inside a grant command.
-* **Who applies it:** Ansible (`klok/environment/klok-environment-setup`) for the platform and tenant klok's
-  services, klok.dev for tenant projects. A grant made only in the broker's admin API is drift.
+* **Who applies it:** Ansible (`klok/environment/klok-environment-setup`, `keycloak.yml` and `pulsar.yml`) applies
+  what those files declare: today the platform and tenant klok's services, plus any entries a person adds there for
+  another tenant's service (a playbook per tenant: klok/environment/klok-environment-setup#35). Broker access (a
+  tenant, a namespace, a topic created in advance, a grant) changes only through a merge request to those Pulsar
+  files, applied by Ansible run by a person. klok.dev provisions no broker clients or grants yet
+  (klok/application/frontend-klok-dev#51). A grant made only in the broker's admin API is drift.
 
 ## Documentation is part of every change
 
 Klok documentation has three levels, and a change is finished only when all three have been considered:
 
-* **The repository's own `klok-docs/`** (znai markdown, `toc-manifest.json`). On every `main` pipeline
-  `./gradlew publishKlokDocs` publishes it, together with the scan of the code, as `KlokProjectDocumentationV1` on
-  `persistent://<tenant>[_<env>]/common/KlokProjectDocumentationV1_prepared`. KlokDocumentationEgress
+* **The repository's own `klok-docs/`** (znai markdown, `toc-manifest.json`). On every `main` pipeline it is
+  published as `KlokProjectDocumentationV1` on
+  `persistent://<tenant>[_<env>]/common/KlokProjectDocumentationV1_prepared`: by `./gradlew publishKlokDocs`, with
+  the scan of the code, in a Gradle project, and by `klok docs send` in any other (the Klok templates do this; a
+  project outside them includes `klok/environment/build-ci-templates:/klok-docs-send.yml`).
+  `klok docs send --dry-run` shows what would be sent. KlokDocumentationEgress
   (`klok/integration/klok-documentation-egress`, KLK007) builds the repository's documentation project from it. That
-  documentation project is output, and nobody edits it. There are two places to change a project's documentation:
+  documentation project is output, and nobody edits it. This runs for tenant klok only: another tenant has no
+  documentation broker client, so its `klok_docs_publish` job fails and, being `allow_failure`, only warns
+  (klok/environment/klok-environment-setup#33), and the egress reads only klok's topic
+  (klok/integration/klok-documentation-egress#2). There are two places to change a project's documentation:
   `klok-docs/` in the source repository (including the `KLOK:GENERATED` markers that place AI sections in a page),
   and the documentation generation settings in klok.dev, which tenant admins own. A change that adds or alters a
   route, a datamodel, a configuration key, a CI job, a command or a decision updates `klok-docs/` in the same merge
@@ -290,6 +384,12 @@ Klok documentation has three levels, and a change is finished only when all thre
   sections that fill `KLOK:GENERATED` regions. They are never edited by hand. A wrong generated page is fixed in
   the egress or in the documentation generation settings in klok.dev.
 
+**Documentation describes only what exists, in one place.** A cross-cutting topic lives in the framework
+documentation projects under `klok/documentation/`, everything else in the owning project's `klok-docs/`; other
+places link there instead of repeating it. A wrong statement is removed or corrected, never marked as outdated. A
+wanted feature written as if it existed becomes an issue in the repository that would build it, and the text is
+removed. Never use the present tense for something that is not built.
+
 **Prompts and agent instructions carry the same knowledge.** System prompts, section prompts, personas, tool
 descriptions, these agent instructions and the skills teach platform rules to a model, and they load the shared
 blocks from *Klok knowledge* above instead of restating them. The *Prompt Catalogue* in
@@ -324,8 +424,9 @@ The pipeline on `main` publishes the project's documentation payload (`KlokProje
 sources, configuration keys and the whole `klok-docs/` folder with a hash per file). KlokDocumentationEgress
 (`klok/integration/klok-documentation-egress`) turns it into the project's published documentation: your
 `klok-docs/` pages as written, with `KLOK:GENERATED` regions filled, next to generated pages for routes,
-datamodels and configuration. Nothing behind you updates the central platform documentation, so the steps above
-are the ones that matter.
+datamodels and configuration. The egress reads only tenant klok's topic today
+(klok/integration/klok-documentation-egress#2), so another tenant's projects get no generated documentation yet.
+Nothing behind you updates the central platform documentation, so the steps above are the ones that matter.
 
 ## How to work
 
@@ -333,9 +434,12 @@ are the ones that matter.
 2. Create the task worktree and branch before the first edit (see *One task, one worktree, one branch*) and say
    which repository, worktree and branch you work in.
 3. Build and test locally with the repository's standard commands before pushing; keep every commit green.
-4. Small, reviewable merge requests with a description that states what changed, why, and which documentation
-   it affects.
+4. Small, reviewable merge requests with a Conventional Commits title (see *Commits follow Conventional Commits*)
+   and a description that states what changed, why, and which documentation it affects.
 5. A new project cloned from a template refreshes the catalog copy and the agent instructions before the first
-   push: `./gradlew updateKlokLibsToml updateKlokAgents`. klok.dev does the same HTTP fetch when it creates the
-   project. Re-run the tasks later to pick up a new catalog or a new skill set.
+   push: `./gradlew updateKlokLibsToml updateKlokAgents`. klok.dev fetches only the versions catalog when it creates
+   a project; the agent instructions come as committed in the template. Re-run the tasks later to pick up a new
+   catalog or a new skill set.
 6. Report outcomes faithfully: failing tests, skipped steps and open questions are stated, not hidden.
+7. End with the step-by-step guide of everything left for a human, merges included (see *Manual steps are handed
+   over as a guide*).

package/assets/agents/knowledge/README.md

@@ -10,8 +10,8 @@ text of its own.
 * Klok knowledge is edited **only** in klok-integration-agent, `packages/cli/assets/agents/knowledge/`, through a
   merge request like any other change.
 * Everything else is a generated copy and is never edited: `knowledge/` next to an installed `KLOK-AGENTS.md`, the
-  catalog's `agents/knowledge/` and `klok-agents.zip`, `build/generated/klok-knowledge/` in a Java build,
-  `generated/klok-knowledge/` in klok.dev, and the copies inside images. A wrong copy is fixed here and refreshed.
+  catalog's `agents/knowledge/` and `klok-agents.zip`, `build/generated/klok-knowledge/` in a Java build, and the
+  copies inside images. A wrong copy is fixed here and refreshed.
 * A prompt that needs the glossary or the platform rules loads the block. It never restates it, and it never
   paraphrases a rule "to keep the prompt short".
 * A change here is also a prompt change: check the *Prompt Catalogue* in the framework development guide
@@ -21,8 +21,8 @@ text of its own.
 
 | File | What it is | Composed into |
 |---|---|---|
-| `glossary.md` | the Klok terms and their meanings, with the rule never to guess a term | every Kloker prompt that explains or documents Klok, the documentation egress's sections |
-| `platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL | the agent runner's doctrine, the role models, klok.dev's datamodel and planning helpers |
+| `glossary.md` | the Klok terms and their meanings, with the rule never to guess a term | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
+| `platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL | the agent runner's doctrine, the role models |
 | `kloker-identity.md` | who Kloker is, and the Unslop writing style | every request to the models `Kloker` and `Kloker-nothink` |
 | `roles/integration-architect.md`, `roles/integration-developer.md` | only what is specific to the role; the rules come from `platform-rules.md` | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
 | `retired-patterns.txt` | conventions the platform no longer has, one pattern per line with the reason | tests that fail when a prompt teaches a retired rule |
@@ -47,15 +47,14 @@ can add to the knowledge but not drop it.
 | Coding agents in a home folder | `klok agents init --global` writes `~/.klok/agents/knowledge/` | same |
 | The agent runner (agent.klok.dev) | the image copies `packages/cli/assets/agents` to `/app/assets/agents` (`KLOK_RUNNER_AGENT_ASSETS_DIR`) | `platform-rules.md` once, on first use, as the doctrine of every task; bead-implementation also seeds `knowledge/` into the sandbox |
 | The dependency catalog | the `update_klok_agents_catalog` job on `main` copies the whole asset tree to `agents/knowledge/` and into `klok-agents.zip` | — |
-| Java services: the Kloker gateway (klok-api-ai), klok-egress-ai, the documentation egress | planned: the Gradle plugin extracts `agents/knowledge/**` from the catalog into `build/generated/klok-knowledge/` on the classpath with a `klok-knowledge.properties` (catalog commit, `blocks=`), and `KlokKnowledge` in klok-common reads the blocks once at start | once, at start; never per request |
-| klok.dev | planned: a prebuild step extracts the catalog's `agents/knowledge/**` into `generated/klok-knowledge/`, read once at module load | once, at start |
+| Java services | the Gradle plugin's `extractKlokKnowledge` bundles the catalog's `agents/knowledge/**` into `build/generated/klok-knowledge/` on the classpath with a `klok-knowledge.properties` (catalog commit, `blocks=`), and `KlokKnowledge` in klok-common reads the blocks. No service reads them that way yet: the Kloker gateway (klok-api-ai) composes the role models from its own copies under `/kloker/prompts/` (klok/integration/klok-api-ai#13) | once, at start; never per request |
 
 An installer replaces the files it ships wholesale and leaves any other file in the installed `knowledge/` alone. It
 does not remove a file this folder no longer ships, so a renamed or retired block is deleted from an installed copy
 by hand (or by the merge request that refreshes it).
 
 No consumer fetches the knowledge at run time, and none reads a database for it, so an AI request costs no extra I/O.
-Each build records the catalog commit it bundled.
+A build that bundles it with `extractKlokKnowledge` records the catalog commit it bundled.
 
 ## How an update spreads
 
@@ -63,8 +62,8 @@ Each build records the catalog commit it bundled.
    `retired-patterns.txt`.
 2. After the merge, the `main` pipeline copies the assets into the dependency catalog (`agents/knowledge/`,
    `klok-agents.zip`).
-3. Consumers that build from the catalog pick up the new text on their next build. Starting those builds
-   automatically when this folder changes is planned (`klok knowledge propagate`).
+3. A project that builds with `extractKlokKnowledge` bundles the new text on its next build; nothing starts those
+   builds when this folder changes (klok/application/klok-integration-agent#37).
 4. The agent runner gets it with its next image, which is built from the same commit.
 5. Developers get it with the next klok-cli release (`klok agents init`), or right away from the catalog with
    `./gradlew updateKlokAgents`.

package/assets/agents/knowledge/glossary.md

@@ -17,6 +17,7 @@ it as the source does.
 | Route, route id | One Camel route per Java class. 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 |
 | Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007` |
+| 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 |
 | Correlation id | `klok-correlation-id`: follows one business flow across routes and messages |
 | Task | Long-running work tracked by the platform (`KlokTaskV1` events, visible in klok.dev and the task API), for example an `ai.chat` task that asks Kloker for text |
 | Datamodel | A versioned data contract; the major version is in the name (`CustomerV1`). Classes: public (A), common (B) and domain (C) are XSD in a Git project of their own with generated Java, Python and TypeScript; system (X) models one external system and may be plain Java classes. All four classes may travel on the broker |

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

@@ -61,6 +61,21 @@ documentation or the dependency catalog can give you.
   * documentation is mirrored under `<tenant>/documentation/<same path>`; a documentation id is
     `slug(<tenant>-<group>-...-<repo>)`.
 
+## Solutions
+
+* Every route belongs to a solution, and every solution has a document: `README.md` and `solution.meta.json` in
+  `<tenant>/integration-solutions/solutions/<SOLUTIONID>_<slug>/`. A new solution gets its id and its document before
+  its first route; the id is taken from the code, never reused, and a leg and sequence (`KLK002A11`) names one route.
+* The document classifies every service the solution needs: new project, new routes in an existing project, reused
+  with a change, reused as is, client change. It maps the legs (route id, project, pattern, topics with purpose,
+  datamodels) and links each project's `klok-docs/` for the details.
+* Integration logic is Java Klok routes on the Quarkus extension. Integration work done with the Python or TypeScript
+  broker clients, or inside an application or an external engine, is `[TACTICAL]`. An external engine (a GPU model
+  server, a vendor service) stays a simple REST service; priority, retries, claim checks and task state live in a
+  Java leg.
+* New development and maintenance are one process: a change to a leg brings the solution document to the new steady
+  state in the same change set, and `klok solutions check` compares the documents with the code on `main`.
+
 ## Topics and CloudEvents
 
 * `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`. Production has no environment suffix
@@ -68,6 +83,14 @@ documentation or the dependency catalog can give you.
 * `<Model>` is the datamodel's class name with its major version (`InvoiceV1`). The purpose has no underscore of its
   own and is set with `topicPurpose()` or `<RouteId>.topic.purpose`; the framework computes the whole topic name.
   Never write topic strings by hand.
+* The purpose is optional, and it is the publisher's: the solution requires it so that one general datamodel serves
+  several flows, the publisher sets it and the reader consumes the purpose the publisher chose. A topic name has at
+  most one purpose, never a second suffix.
+* A reader is identified by its subscription, whose name is its route id (`<RouteId>.subscription.name` overrides
+  it), so the reading tenant's short name is in it (`DEG012E1_...`). A reader never appears in the topic name.
+  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.
 * 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.
 * Every broker message is a CloudEvent in binary content mode: the attributes are message properties, the payload
@@ -106,12 +129,15 @@ whether a model may travel on a topic; it decides how widely the model is shared
   a payload or property that claims another tenant.
 * A tenant publishes only in its own namespace, `<tenant>[_<env>]/<domain>`. Nobody holds `publish` in another
   tenant's namespace. Reading elsewhere is a `consume` grant on one named topic, approved by the owner and recorded in
-  Git in the owning tenant. A topic read across tenants carries its reader as the last purpose segment
-  (`persistent://konvoj/hr/PersonnelScheduleExportV1_degerfors`).
-* Platform services (logs, the ODL, AI, mail, documentation) are shared klok workers under the same rule: a tenant's
-  requests live in the tenant's namespace (`persistent://<tenant>[_<env>]/common/<Model>`), the worker is granted
-  `consume` on exactly those topics, and what the platform writes back lives in klok's namespace, one topic per
-  tenant (`persistent://klok[_<env>]/<domain>/<Model>_<tenant>`).
+  Git in the owning tenant. The topic keeps its own name; the reader is known by its subscription.
+* Platform services (logs, the ODL, tasks, AI, documentation) are klok services, today configured for tenant klok
+  only. One that serves several tenants follows the same rule: a tenant's requests live in the tenant's namespace
+  (`persistent://<tenant>[_<env>]/common/<Model>`), the service is granted `consume` on exactly those topics, and
+  what the platform writes back lives in klok's namespace, one topic per tenant
+  (`persistent://klok[_<env>]/<domain>/<Model>_<tenant>`).
+* Broker access (a tenant, a namespace, a topic created in advance, a grant) changes only through a merge request to
+  the Pulsar variables in `klok/environment/klok-environment-setup`, applied by Ansible run by a person. A grant made
+  only in the broker's admin API is drift.
 * One Keycloak client per running deployment, never shared and never used by a person. Broker rights are called
   `publish` and `consume`; *ingress* and *egress* say what a service is and are never permissions.
 
@@ -137,8 +163,8 @@ asynchronously through events, never inline in a request.
 The ODL stores any datamodel object per tenant, keyed by its type (the fully qualified Java class name) and an id,
 backed by OpenSearch (index `klok-odl-<tenant>-<slug(type)>`). Every write emits a change event
 `KlokOdlObjectEventV1_<Type>`. A route stores its body with `persistToOdl()` or `odlPersist(...)` (fire and forget)
-and reads, searches and writes synchronously through `odl()` (`get`, `search`, `persistSync`, `delete`). The ODL
-topics are in the `common` domain. Tenant-tunable behaviour of a service (prompts, sections, languages) is a Klok
+and reads, searches and writes synchronously through `odl()` (`get`, `search`, `persistSync`, `delete`). The ODL's
+request topics are in the `common` domain; a change event goes to the domain of the object. Tenant-tunable behaviour of a service (prompts, sections, languages) is a Klok
 standard shipped with the service plus a tenant override stored in the ODL.
 
 ## Versions and delivery
@@ -148,5 +174,9 @@ standard shipped with the service plus a tenant override stored in the ODL.
   `./gradlew updateKlokLibsToml` refreshes `gradle/klok-libs.versions.toml`.
 * Work on a branch and open a merge request; never push to `main` of an existing repository. Publishing, images,
   manifests and catalog updates happen on `main` only.
+* What only a person may do (merge a merge request, write Vault, run Ansible, change Keycloak) is handed over as a
+  numbered guide with the exact commands, the merge order and why. The commands run as pasted from any directory,
+  so a `glab api` command names the host (`--hostname git.klok.dev`). A step that needs an earlier release waits for
+  its result (the version in the dependency catalog), not for the merge: `main` pipelines may run in parallel.
 * Every change that adds or alters a route, a datamodel, a configuration key or a decision updates the repository's
   `klok-docs/` in the same merge request.

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

@@ -23,6 +23,10 @@ pulsar:// # topics are persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>
 <tenant>_<env>/ # the environment suffix is optional; production has none: <tenant>[_<env>]
 topic-dlq # dead letters are <topic>_DLQ
 (?i)owner hosts the topics # write narrow, consume wide: the writer's namespace holds the topic
+# A reader is never part of the topic name (2026-10-06): one optional purpose, set by the publisher.
+(?i)last purpose segment # a topic has one optional purpose set by the publisher; a reader is its subscription (route id)
+(?i)_<reader> # a topic has one optional purpose set by the publisher; a reader is its subscription (route id)
+(?i)\breader (as|after) the (last )?purpose # a topic has one optional purpose set by the publisher; a reader is its subscription
 #
 # Framework classes that do not exist in the Quarkus extension 2.0 and later.
 KlokSoapApi # removed in 2.0; SOAP is a KlokCustomRoute with camel-cxf

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

@@ -57,6 +57,9 @@ visible.
 * **Egress** adapts the broker to an external protocol, transforms into the target's format, and owns retries,
   backpressure and the delivery guarantee.
 
+Every design names its solution and lists its services by kind and its legs, as the platform rules' *Solutions*
+describe; a design that moves integration logic out of Java legs says why, as a tactic.
+
 A design that says "one service that polls CRM, maps and posts to Visma" hides three legs. Split it and name each
 leg. Onramps and offramps stay thin (protocol and format); business enrichment, splitting a nightly file and
 aggregating for a chatty vendor belong in processing or in a framework capability.

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

@@ -166,7 +166,12 @@ 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.
+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
 
@@ -194,7 +199,8 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
 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.
+   `[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.
@@ -215,6 +221,9 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
   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.