@klok-integration/cli 0.3.4 → 0.5.0

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,9 +44,14 @@ 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` 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. |
 | `klok ci env` | Show what klok-cli detected about the CI job it runs in. |
 | `klok manifest update` | Set a container's image in a deploy manifest of your GitOps repository, then commit and push. |
@@ -100,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/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
 
@@ -19,7 +19,11 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the pipeli
   documentation.
 * Consumers reference the artifact only through the catalog alias (`klokLibs.<key>`), never by literal version.
 * Datamodel documentation lives in `klok-docs/` (purpose, fields that need explanation, producers and consumers,
-  design decisions). Datamodel projects publish no documentation payload yet, because the datamodel template runs
-  no Klok Gradle task, so these pages do not reach docs.klok.dev until it does; write them anyway.
+  design decisions). The datamodel pipeline's `klok_docs_publish` job sends it with the XSD to docs.klok.dev, where
+  the model is documented from the XSD (a structure page, then AI sections from the complex types up) under
+  `<tenant>/documentation/datamodel/<same path>`. Put `xs:documentation` on types and fields; that is what the
+  generated text is written from.
+* The repository's path is its class: `public` (A), `common` (B), `domain/<d>` (C) or `system/<s>` (X). The wider
+  the scope, the stricter a breaking change; see the `klok-datamodel` skill.
 * On `main` the pipeline publishes and updates the catalog; check it, then refresh consumers with
   `./gradlew updateKlokLibsToml`.

package/assets/agents/AGENTS.documentation.md

@@ -1,7 +1,7 @@
 ## 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

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,10 @@ 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`), 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.
 * 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()`).
@@ -27,6 +31,14 @@ needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt
   (`KlokTaskInitiation`, `KlokAsyncTaskWorkerRoute`).
 * 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.
+* 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.
 * `application.properties` keeps every `klok.*` key explicit; secrets come from environment variables that the
   Vault env secret provides in Kubernetes (`KLOK_BROKER_AUTH_CLIENT_ID`, ...).
 * Update `klok-docs/` (overview, design decisions, routes, operations) in the same merge request as the change.

package/assets/agents/AGENTS.workspace.md

@@ -8,23 +8,81 @@ 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, onboarding | `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` |
+| 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-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:
+
+* `<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/`, `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
 
@@ -106,7 +164,7 @@ 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.
@@ -121,6 +179,14 @@ step by step procedure; the contract every agent follows is:
 * 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.
 
 ## Logic lives in the Klok tools, not in the pipelines
 
@@ -146,12 +212,44 @@ 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 a flow that producer and consumer agree on, so one datamodel serves several
+  flows and each consumer reads only its own; it never contains `_`.
 * 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.
 * Repositories: `<tenant>/integration/domain/<d>/<repo>`, `<tenant>/datamodel/...`, mirrored documentation under
   `<tenant>/documentation/...`; documentation ids are `slug(<tenant>-<group>-...-<repo>)`.
+* Permission words, one meaning each: *ingress/egress* says what a service is and is never a permission; broker
+  rights are `publish` and `consume` (Pulsar's own `produce`/`consume` only inside a grant command); `read` and
+  `ingest` belong to klok.dev's integration context graph and never to the broker.
+
+## Broker access and tenant isolation
+
+Read the *Broker Access And Tenant Isolation* page of
+`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`
+  field or property can be forged by any client allowed on the topic. A service takes the tenant from the topic
+  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.
+* **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.
 
 ## Documentation is part of every change
 
@@ -159,7 +257,7 @@ Klok documentation has three levels, and a change is finished only when all thre
 
 * **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://klok[_<env>]/common/KlokProjectDocumentationV1_prepared`. KlokDocumentationEgress
+  `persistent://<tenant>[_<env>]/common/KlokProjectDocumentationV1_prepared`. 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:
   `klok-docs/` in the source repository (including the `KLOK:GENERATED` markers that place AI sections in a page),
@@ -192,18 +290,31 @@ 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.
 
+**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
    the code it describes. Documentation that is promised for a later merge request is documentation that never
    arrives, and a final "docs" commit at the end of a branch is the same promise wearing a hat.
-2. 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`)
+2. Run `klok docs build` where a znai CLI is at hand (the Klok build image has one; `--znai <path>` points at
+   another). It builds `klok-docs/` with znai the way the repository's documentation project will, so a page znai
+   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 (`klok docs read <doc-id>`)
    instead of guessing what they say.
-3. Correct what you can judge yourself. A central page that is now plainly wrong is fixed in its own small merge
+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
    rather than dropped.
-4. Write the merge request description for the reviewer: state what changed, why, and which documentation it
+5. Write the merge request description for the reviewer: state what changed, why, and which documentation it
    affects or might affect. A description that
    says only "fixes the build" produces no documentation update.
 

package/assets/agents/knowledge/README.md

@@ -0,0 +1,77 @@
+# Klok knowledge
+
+This folder is the single source of the platform knowledge that Klok teaches its models and agents: the glossary,
+the platform rules, Kloker's identity and writing style, the role handbooks, and the list of retired conventions.
+Every system prompt, agent instruction and tool that needs this knowledge loads these files. None of them keeps a
+text of its own.
+
+## Edit only here
+
+* 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.
+* 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
+  (`klok docs read klok-framework-development-guide`) and update it in the same piece of work.
+
+## The files
+
+| 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 |
+| `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 |
+
+**Blocks.** A block is a Markdown file in this folder other than `README.md`. Its name is its path under
+`knowledge/` without `.md`: `glossary`, `platform-rules`, `kloker-identity`, `roles/integration-architect`,
+`roles/integration-developer`. The Gradle plugin lists the block names in the `blocks=` line of
+`klok-knowledge.properties`, which the build-time loader reads. So keep file names lowercase with hyphens, end a
+block in `.md`, put role handbooks in `roles/`, and do not rename a block without updating every consumer that loads
+it by name. `README.md` and `retired-patterns.txt` are not blocks.
+
+A role model's system prompt is composed in this order: `kloker-identity.md`, `platform-rules.md`, `glossary.md`,
+the role file. Plain `Kloker` gets `kloker-identity.md` only; framework knowledge is opt-in through the role models.
+A shared block is always appended by the service, never part of a text a tenant can override, so a tenant override
+can add to the knowledge but not drop it.
+
+## Who loads it, and how
+
+| Consumer | How it gets the files | When it reads them |
+|---|---|---|
+| Coding agents in a repository | `klok agents init` (the CLI's bundled copy) and `./gradlew updateKlokAgents` (catalog `main`) write `knowledge/` next to `KLOK-AGENTS.md`: byte for byte copies of every file here, without a marker, so both installers give identical results | the agent reads the files `KLOK-AGENTS.md` points to |
+| 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 |
+
+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.
+
+## How an update spreads
+
+1. A merge request changes a file here. Its pipeline runs the tests, including the check against
+   `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`).
+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`.
+
+## retired-patterns.txt
+
+One pattern per line: a regular expression in the syntax JavaScript and Java share, then ` # ` and the reason. A
+leading `(?i)` makes the pattern case-insensitive; blank lines and lines starting with `#` are comments. When a rule
+is retired, add its old form here in the same merge request that changes `platform-rules.md`, so every consumer's
+test catches a copy that still teaches it.

package/assets/agents/knowledge/glossary.md

@@ -0,0 +1,26 @@
+# Klok glossary
+
+The sources you are given use Klok platform terms. Use these meanings, spell out an abbreviation only as written
+here, and never guess the meaning of a Klok term that is neither in this list nor explained in the sources: write
+it as the source does.
+
+| Term | Meaning |
+|---|---|
+| Klok | The integration platform the documented project runs on (iPaaS): Camel routes on Quarkus, an Apache Pulsar broker, datamodels, and the portal klok.dev |
+| ODL | Operative Data Layer: the platform's store for datamodel objects, keyed by the object's datamodel type and an id, per tenant; routes write, read and search it (backed by OpenSearch) |
+| Claim check | A large payload stored in the platform's object storage; the message carries only a reference to it (a `klokcc://` URI) instead of the bytes |
+| Broker, topic | Apache Pulsar. A topic is named `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]` and carries CloudEvents whose data is a datamodel |
+| CloudEvent | The standard envelope of every broker message: id, type, source, time, and the datamodel as data |
+| DLQ | Dead letter queue: `<topic>_DLQ`, where a message goes after its retries are exhausted |
+| Tenant | An organisation on the platform, and its security boundary; every topic, ODL object and GitLab group belongs to one tenant |
+| Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
+| Route, route id | One Camel route per Java class. 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` |
+| 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 |
+| Dependency catalog | The file that pins every Klok library and datamodel version (`klok-libs.versions.toml`) |
+| Kloker | Klok's own AI model, reached through the platform's AI gateway |
+| klok.dev | The platform's web portal: projects, tenants, settings, the ODL and tasks |
+| klok-docs | The folder in every repository with its hand-written documentation, published to docs.klok.dev |