@klok-integration/cli 0.4.0 → 0.6.203

package/README.md

@@ -22,8 +22,12 @@ klok                           # opens the terminal UI
 
 Configuration lives in `~/.config/klok/config.json`. Every value can be overridden by an environment
 variable: `KLOK_AGENT_URL`, `KLOK_TENANT`, `KLOK_DOMAIN`, `KLOK_DEV_URL`, `KLOK_KEYCLOAK_ISSUER`,
-`KLOK_KEYCLOAK_CLIENT_ID`, `KLOK_GIT_URL`, `KLOK_GIT_LOCAL_WORKSPACE`. Run `klok config list` to see
-what is set and where it comes from.
+`KLOK_KEYCLOAK_CLIENT_ID`, `KLOK_GIT_URL`, `KLOK_GIT_LOCAL_WORKSPACE`, `KLOK_GIT_APIKEY`. Run
+`klok config list` to see what is set and where it comes from.
+
+The GitLab token can be stored with `klok config set klokApiKey` (a hidden prompt, so it stays out of the shell
+history). It is shown as `****` everywhere unless you run `klok config get klokApiKey --reveal`, and the file
+is kept at mode 0600.
 
 Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 
@@ -40,8 +44,12 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agent tasks`, `klok agent open <taskId>`, `klok agent cancel <taskId>` | Work with tasks. |
 | `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 and skills into a repository. |
+| `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` 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. |
+| `klok docs id [path]` | The doc id of a repository path. |
 | `klok docs publish` | Build this repository's znai documentation and upload it to the docs portal. |
 | `klok docs build` | Build this repository's `klok-docs/` with znai the way its documentation project will, uploading nothing. |
 | `klok solutions validate` | Check the descriptors of an integration solution registry against the descriptor contract. |
@@ -101,7 +109,12 @@ Cursor (`.cursor/mcp.json`):
 Klok skills. `KLOK-AGENTS.md`, the klok rule files and the `klok-*` skills belong to Klok and are
 replaced wholesale; every other file keeps its content and only has its single row created or replaced,
 so an update can never duplicate text. Klok skills the CLI no longer ships are removed.
-`klok agents status` shows whether a repository is up to date with the CLI version you have installed.
+Your tenant's skills (`<tenant>-context` and one skill per documented repository) come from the tenant's private
+catalog with your GitLab token (`KLOK_GIT_APIKEY`); they are installed, kept out of git, and refreshed by
+`klok agents update`. `klok agents status` shows whether a repository is up to date with the catalogs.
+After you install or update the CLI, the first interactive run tells you when the instructions you installed
+with `klok agents init --global` or `--workspace` are older than the CLI, and prints the commands that update
+them.
 
 ## Licence and support
 

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.application.md

@@ -2,7 +2,7 @@
 
 A Klok application (portal, docs portal, agent service or another container) that is built and deployed with the
 platform pipelines: image to `repo.klok.dev`, deployment manifest in the manifests repository, secrets through
-Vault. Read https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the release process and the
+Vault. Read `klok docs read klok-environment-build-ci-templates` for the release process and the
 repository's own `README.md` and `docs/` for its architecture.
 
 ### Rules

package/assets/agents/AGENTS.datamodel.md

@@ -2,8 +2,8 @@
 
 A Klok datamodel: an XSD (or JSON schema) under `schema-definition-xsd/`, converted by the pipeline to Avro and to
 a generated Java project that is published as `dev.klok.<tenant>.datamodel:<name>-v<n>` and written into the
-dependency catalog. Read https://docs.klok.dev/klok-framework-klok-common/llm.txt for naming and
-https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the pipeline.
+dependency catalog. Read `klok docs read klok-framework-klok-common` for naming and
+`klok docs read klok-environment-build-ci-templates` for the pipeline.
 
 ### Rules
 

package/assets/agents/AGENTS.documentation.md

@@ -1,14 +1,15 @@
 ## This repository: documentation project
 
 A znai documentation project published to https://docs.klok.dev under the doc id in `klok-docs-sync.json`. Read
-https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (documentation from a source repository) for how
+`klok docs read klok-environment-build-ci-templates` (documentation from a source repository) for how
 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.framework.md

@@ -2,7 +2,7 @@
 
 Part of the Klok framework (klok-common, the broker client, the Quarkus extension, the gradle plugin or the CI
 templates). Changes here reach every tenant, so read the library's `klok-docs/` and its published documentation
-(`https://docs.klok.dev/klok-framework-<repo>/llm.txt`) before changing behaviour.
+(`klok docs read klok-framework-<repo>`) before changing behaviour.
 
 ### Rules
 

package/assets/agents/AGENTS.integration.md

@@ -3,7 +3,7 @@
 A Klok integration on the Quarkus extension 2.0: one Camel route per class, each extending a framework pattern
 (`KlokOnrampRoute`, `KlokProcessingRoute`, `KlokOfframpRoute`, their `Sync` variants, `KlokRestApi` and
 `KlokRestApiHandlerRoute`, `KlokAsyncTaskWorkerRoute`, `KlokCustomRoute`) and implementing the capabilities it
-needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt before writing a route.
+needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writing a route.
 
 ### Commands
 
@@ -20,6 +20,11 @@ needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt
   Configuration keys are `<RouteId>.<key>` with fallback to `<SolutionId>.<key>` and `klok.route-defaults.<key>`.
 * 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`). 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()`).
@@ -28,10 +33,12 @@ needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt
 * 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

@@ -8,23 +8,82 @@ otherwise yours. Do not copy rules into them.
 
 ## Read the documentation before guessing
 
-The platform documentation is published at https://docs.klok.dev. Every documentation project exposes its full
-content as one markdown file at `https://docs.klok.dev/<doc-id>/llm.txt`; fetch it instead of relying on memory.
+Before anything else, run `klok agents update --check`. Exit 5 means the installed skills are behind a catalog:
+run `klok agents update` and read the refreshed files. Exit 0 means they are current, and any other code names
+what went wrong (no token, no network); say so instead of guessing.
+
+The platform documentation is published at https://docs.klok.dev, one documentation project per repository, each
+exposing its whole content as one markdown file. Read it with klok-cli, which sends your GitLab token and caches
+the answer:
+
+```
+klok docs read <doc-id>            # the markdown on stdout, one status line on stderr; --json adds fetchedAt
+klok docs id [tenant/group/.../repo]   # the doc id of a repository, this one by default
+```
 
 | Topic | Read |
 |---|---|
-| Platform principles, event driven design, naming, onboarding | https://docs.klok.dev/klok-integration-strategy-and-tactics/llm.txt |
-| Route framework (patterns, config, logging, errors, topics, tasks) | https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt |
-| Naming conventions, message properties, CloudEvents | https://docs.klok.dev/klok-framework-klok-common/llm.txt |
-| Broker client | https://docs.klok.dev/klok-framework-klok-brokerclient-java/llm.txt |
-| Gradle plugin, versions, catalog | https://docs.klok.dev/klok-framework-klok-gradle-plugin/llm.txt |
-| CI templates, release process, Vault roles | https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt |
-| Developer rules: identity and access, Keycloak, Vault paths, certificates, infrastructure as code | https://docs.klok.dev/klok-framework-development-guide/llm.txt |
-| How people use the platform: concepts, roles and access, workflow, operations | https://docs.klok.dev/klok-user-guide/llm.txt |
-| Infrastructure: stateful services, certificates, Ansible, Keycloak clients | https://docs.klok.dev/klok-environment-klok-environment-setup/llm.txt |
-
-A 404 means the documentation project is not published yet; read the repository's `klok-docs/` folder instead.
-The `klok-docs` skill describes the lookup in detail.
+| 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; 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` |
+
+What the answers mean:
+
+* **404**: the project is not published yet. Its hand written pages are in the repository's `klok-docs/` on
+  `main`, the source of the same site: `git -C <repo> fetch origin && git show origin/main:klok-docs/<page>.md`
+  (`toc-manifest.json` lists the pages). Read them there; nothing else is a substitute.
+* **401 or 403** (no token, or your GitLab account is not a member of the tenant or domain): say so and ask for a
+  token or for access. Never guess what the page says, and never try another way in.
+
+The `klok-docs` skill describes the lookup in detail. Cite the doc id you relied on, and the `fetchedAt` from
+`klok docs read --json`, in your answer or merge request description.
+
+## Tenant skills
+
+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`,
+  `routes.jsonl`, `datamodels.jsonl`, `topics.jsonl` and `solutions.jsonl`.
+* `<tenant>-<group>-…-<repo>` is one skill per documented repository (the name is its doc id): what the project
+  does, its routes, datamodels, topics, solution and configuration keys, with every fact as one JSON row in
+  `data/facts.jsonl` (`kind` first: `project`, `route`, `topic`, `datamodel`, `solution`, `config-key`, `doc-page`,
+  `component`).
+* Search the facts instead of reading everything: `grep -i <term> .claude/skills/<skill>/data/facts.jsonl`, or
+  `jq -c 'select(.kind=="route")' .claude/skills/<skill>/data/facts.jsonl` (`.agents/skills/` for Codex, OpenCode
+  and Antigravity).
+* They are installed, never committed: `klok agents update` refreshes them from the catalog and keeps them out of
+  git through `info/exclude`. Never edit them; a wrong fact is fixed in the repository's `klok-docs/` or code, and
+  the next documentation publish regenerates the skill.
+
+## Klok knowledge
+
+The folder `knowledge/` next to this file holds the platform knowledge that Klok's models and agents share. Read
+it when a task touches the platform:
+
+| File | Holds |
+|---|---|
+| `knowledge/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 |
+| `knowledge/glossary.md` | the Klok terms and what they mean |
+| `knowledge/kloker-identity.md` | Kloker's identity and writing style |
+| `knowledge/roles/` | the role handbooks of the Kloker role models |
+| `knowledge/retired-patterns.txt` | conventions the platform no longer has, one pattern per line with the reason |
+
+* 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/` 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.
 
 ## Git is the truth, everything must work by hand
 
@@ -86,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`
@@ -98,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
@@ -106,21 +191,81 @@ step by step procedure; the contract every agent follows is:
   layers, no layer cache, push from `main` only. Never use or propose a privileged runner, `docker:dind`, or a
   relaxed seccomp or AppArmor profile. A Dockerfile copies dependencies, assets and application code as separate
   `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 https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt
+  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.
+* **Never cancel a running job without a human's yes.** Cancelling, stopping, killing, deleting or force-restarting
+  anything that runs is never done on an agent's own judgement: a CI job or pipeline, a release, a deployment
+  rollout, a pod, a container, a broker consumer, a scheduled task. Describe what you see (job id, how long it has
+  run by the current time from `date -u`, never an assumed time, the last log lines with their timestamps, what
+  waits behind it), say what you propose and what it would break, and wait for an explicit yes. "It looks hung",
+  "it blocks the `main` lane" and "it can be retried" are reasons to ask at once, not to act: a release that waits
+  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
 
@@ -146,7 +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`).
+  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.
@@ -159,7 +307,7 @@ step by step procedure; the contract every agent follows is:
 ## Broker access and tenant isolation
 
 Read the *Broker Access And Tenant Isolation* page of
-https://docs.klok.dev/klok-framework-development-guide/llm.txt before designing anything that touches broker
+`klok docs read klok-framework-development-guide` before designing anything that touches broker
 access, Keycloak broker clients or a service that serves several tenants.
 
 * **The topic decides the tenant, never the message.** Pulsar does not tell a consumer who published; a `tenant`
@@ -167,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
@@ -223,6 +384,21 @@ 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
+the framework development guide (`klok docs read klok-framework-development-guide`) lists every place.
+A change to a platform rule, the strategy, naming, the datamodel classes or the glossary checks the catalogue. It
+updates every prompt that restates the change, or files an issue in the owning repository for each one it leaves. A
+new prompt, persona, tool description or agent instruction is added to the catalogue in the same merge request.
+Prompts never carry `/think` or `/no_think` tokens; the model name (`Kloker-nothink`, `Kloker`) is the only switch.
+
 ### Before the merge request
 
 1. Update the repository's `klok-docs/` in the same merge request as the change — ideally in the same commit as
@@ -233,7 +409,7 @@ Klok documentation has three levels, and a change is finished only when all thre
    cannot parse fails now instead of stopping the documentation project from publishing after the merge, where
    nobody in this repository sees it.
 3. Ask what a reader of the platform documentation would now find wrong: a renamed command, a new rule, a changed
-   default, a workflow with one more step. Read the affected pages (`https://docs.klok.dev/<doc-id>/llm.txt`)
+   default, a workflow with one more step. Read the affected pages (`klok docs read <doc-id>`)
    instead of guessing what they say.
 4. Correct what you can judge yourself. A central page that is now plainly wrong is fixed in its own small merge
    request against that documentation project, linked from the change. What you cannot judge is written down
@@ -248,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
 
@@ -257,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*).