@klok-integration/cli 0.3.3 → 0.4.0

package/README.md

@@ -43,6 +43,9 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agents init` | Write the Klok agent instructions and skills into a repository. |
 | `klok bead list\|show\|report` | Progress beads in the current repository. |
 | `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. |
 | `klok sync clone\|pull\|status` | Clone and refresh every repository you can see, in one workspace folder. |
 
@@ -93,8 +96,8 @@ Cursor (`.cursor/mcp.json`):
 ## Agent instructions
 
 `klok agents init` writes `KLOK-AGENTS.md` with the rules, one managed row in every harness file
-(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.clinerules`,
-`.github/copilot-instructions.md`), the klok named rule files (`.cursor/rules`, `.agents/rules`) and the
+(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.clinerules` or a file inside a
+`.clinerules/` directory, `.github/copilot-instructions.md`), the klok named rule files (`.cursor/rules`, `.agents/rules`) and the
 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.

package/assets/agents/AGENTS.datamodel.md

@@ -10,12 +10,20 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the pipeli
 * One root element `<Name>_vN` that references every complex type; a single `xs:` prefix; `targetNamespace` and
   `xmlns:tns` set; `elementFormDefault="qualified"`. Validate with the XSD validation of the CI template before
   pushing (`python3 scripts/validate-xsd.py` from build-ci-templates, or the pipeline's `generate_avro_from_xsd`).
-* The major version is part of the model name (`Customer_v1`, class `CustomerV1`); a breaking change is a new
-  major version and a new topic, never a silent change of an existing one.
+* One name, in kebab case, from the repository down: `customer-v1` is the repository, the XSD file
+  (`customer-v1.xsd`), the Maven artifact and the npm and Python packages, and `customer_v1` ends the Java package.
+  Inside the XSD the model keeps its PascalCase form: root element `Customer_v1`, root type and class `CustomerV1`.
+* The major version is part of the model name; a breaking change is a new major version and a new topic, never a
+  silent change of an existing one.
 * `meta.json` uses the flat form with `targetNamespace`; it drives the generated project's group, name and
   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) and is mirrored to the documentation project.
+  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,15 +1,25 @@
 ## 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 (docs sync) for how content arrives here.
+https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (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:
+  * `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> -->`);
+  * what is generated and how (chapters, sections, prompts, languages, model): klok.dev, Tenant Administration,
+    Documentation generation, which tenant admins change.
+* **A standalone documentation project** (directly under `<tenant>/documentation/`, such as
+  `klok-integration-strategy-and-tactics`) is written by hand in this repository, and the egress never touches it.
+  Keep `docs/toc` and `docs/toc-manifest.json` in sync when adding a page.
 
 ### Rules
 
-* `docs/klok-docs/` and `docs/generated/` are written by the docs sync of the source repository. Never edit them
-  here; change `klok-docs/` in the source repository, or the generator. Only `KLOK:GENERATED` regions of AI
-  maintained pages are rewritten automatically.
-* Human pages live in `docs/` next to them (`overview`, `architecture`, `operations`, `changelog`); keep
-  `docs/toc` and `docs/toc-manifest.json` in sync when adding a page.
 * The doc id must start with the tenant prefix (`<tenant>-...`); the pipeline refuses others. Do not set the
   tenant, the Vault path or upload tokens in the project CI. This project's `.gitlab-ci.yml` is the include of
   `klok/environment/build-ci-templates:/klok-docs-publish.yml` and nothing else; the job is `klok docs publish`.

package/assets/agents/AGENTS.integration.md

@@ -27,10 +27,19 @@ 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.
-* On `main` the pipeline builds the image, updates the deployment manifest and syncs the documentation; check it.
+* On `main` the pipeline builds the image, updates the deployment manifest and publishes the documentation payload
+  that KlokDocumentationEgress turns into the documentation project; check it.
 * The `Dockerfile` copies `build/quarkus-app/lib/` in a `COPY` of its own before `quarkus-run.jar`, `quarkus/`
   and `app/`, all with `COPY --chown`, never `COPY build/quarkus-app/ .` followed by `RUN chown -R`, which stores
   every dependency twice in every build.

package/assets/agents/AGENTS.workspace.md

@@ -19,6 +19,9 @@ content as one markdown file at `https://docs.klok.dev/<doc-id>/llm.txt`; fetch
 | 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.
@@ -149,15 +152,51 @@ step by step procedure; the contract every agent follows is:
   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
+https://docs.klok.dev/klok-framework-development-guide/llm.txt 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
 
 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`), which KlokDocumentationEgress merges
-  with the pages it generates from the code into the repository's documentation project on every `main` pipeline.
-  That documentation project is output: never edit it; what is generated is set by tenant admins in klok.dev. 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 request.
+* **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
+  (`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),
+  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
+  request.
 
   `klok-docs/` has to answer **two different questions**, and a repository that answers only the first is not
   documented:
@@ -180,22 +219,27 @@ Klok documentation has three levels, and a change is finished only when all thre
   and tactics (`klok-integration-strategy-and-tactics`) and the framework, CI and tooling documentation. They
   describe how the platform is used and why. A change that alters a rule, a convention, a workflow, a command or
   a published contract belongs there too, even when the code that changed lives somewhere else entirely.
-* **Generated pages** (`docs/generated/`, `KLOK:GENERATED` regions), which are never edited by hand. A wrong
-  generated page is a bug in the generator.
+* **Generated pages**: everything KlokDocumentationEgress writes into a documentation project, including the AI
+  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.
 
 ### 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
+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 (`https://docs.klok.dev/<doc-id>/llm.txt`)
    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 two readers: the reviewer, and the documentation flow that runs after
-   the merge. State what changed, why, and which documentation it affects or might affect. A description that
+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.
 
 ### After the merge

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

@@ -8,11 +8,31 @@ description: Create or change a Klok datamodel (XSD first, generated Java, publi
 Read https://docs.klok.dev/klok-framework-klok-common/llm.txt (naming) and
 https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pipeline).
 
+## Choosing the class
+
+Every datamodel is one of four classes (decided 2026-09-29; the reasoning is in
+https://docs.klok.dev/klok-integration-strategy-and-tactics/platform-2-0/datamodel-classes/). All four may be sent
+over the broker; the class sets how widely the model is shared and how strict its stability is.
+
+| Class | Repository | Schema | A breaking change |
+|---|---|---|---|
+| A, public | `<tenant>/datamodel/public/<name>-v<n>` | XSD | the strictest: every reader notified; the old version runs at least 12 months after the notice |
+| B, common | `<tenant>/datamodel/common/<name>-v<n>` | XSD | coordinated across the tenant's domains; the old version runs at least 3 months |
+| C, domain | `<tenant>/datamodel/domain/<d>/<name>-v<n>` | XSD | decided within the domain; no fixed minimum |
+| X, system | `<tenant>/datamodel/system/<s>/<name>-v<n>`, **or** plain Java classes in the integration's own source | XSD not required | follows the external system; no fixed minimum |
+
+A class X model mirrors one external system's format. It does not need an XSD: simple Java classes in the
+integration, explained in the source, are enough, and the steps below do not apply to them. Give it a repository
+with an XSD when more than one integration or a service in another language needs it. Data that other systems or
+domains read should still travel as class B or C (transform at the edge).
+
 ## Creating or changing a model
 
 1. The model lives in its own repository `<tenant>/datamodel/<common|public|domain/<d>|system/<s>>/<name>-v<n>`,
-   where the repository name is the model name in kebab case (`supplier-invoice-v1`); the XSD file inside keeps
-   the PascalCase form (`SupplierInvoice_v1.xsd`).
+   where the repository name is the model name in kebab case (`supplier-invoice-v1`). The XSD file has the same
+   name (`supplier-invoice-v1.xsd`), and so do the Maven artifact and the npm and Python packages; the Java package
+   ends in `supplier_invoice_v1`. Inside the XSD the model keeps its PascalCase form: root element
+   `SupplierInvoice_v1`, root type `SupplierInvoiceV1`.
 
    **Create it through klok.dev, or through the agent at https://agent.klok.dev** authenticated as the tenant
    with the right to create projects in the domain. That is the supported path: it creates the repository from
@@ -35,17 +55,21 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pip
 3. `meta.json` in the flat form with `targetNamespace`, and `klok-docs/` with the purpose, the important fields and
    the producers and consumers.
 4. A breaking change is a new major version (`Customer_v2`), which is a new class, a new topic and a new catalog
-   key; a compatible change (optional field) stays in the same version.
+   key; a compatible change (optional field) stays in the same version. The old and the new version run in
+   parallel while readers move, at least the class's minimum (table above) and until every known reader
+   has moved.
 5. Work in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch, open a merge request;
    the pipeline validates the XSD and generates the Java project. On `main` it
-   publishes `dev.klok.<tenant>.datamodel:<name>-v<n>:1.0.0-build.<ts>` and writes `<nameVn>` (for example
-   `klokOdlV1`) into the dependency catalog.
+   publishes `dev.klok.<tenant>.datamodel:<name>-v<n>:1.0.0-build.<ts>` with its Python and TypeScript packages,
+   writes `<nameVn>` (for example `klokOdlV1`) into the dependency catalog, and publishes the documentation payload
+   that becomes `<tenant>/documentation/datamodel/<same path>` on docs.klok.dev.
 
 ## Using a model in a project
 
 * Run `./gradlew updateKlokLibsToml` in the consumer, commit the refreshed `gradle/klok-libs.versions.toml`, and
   reference the alias (`klokLibs.klokOdlV1` or the bundle). Never type a version.
-* The generated class is `dev.klok.<tenant>.datamodel.<group>.<name>_v<n>.<Name>Vn`; the ODL type of an object is
-  the fully qualified class name.
+* The generated class is `dev.klok.<tenant>.datamodel.<group>.<name_with_underscores>_v<n>.<Name>Vn` (for
+  `klok-task-event-v1`: `dev.klok.klok.datamodel.common.klok_task_event_v1.KlokTaskStatusEventV1`); the ODL type of an object is the
+  fully qualified class name, so moving a class to another package is a data migration of its ODL index.
 * The topic for the model is derived from the class (`persistent://<tenant>[_<env>]/<domain>/<Name>Vn`); do not
   invent topic strings.

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

@@ -30,7 +30,7 @@ drops the `klok-` prefix of the name (`klok-integration-strategy-and-tactics`).
 | Naming conventions, `klok-*` properties, CloudEvents attributes | `klok-framework-klok-common` |
 | Broker client configuration, subscriptions, request/reply | `klok-framework-klok-brokerclient-java` |
 | Gradle plugin, versions, catalog refresh | `klok-framework-klok-gradle-plugin` |
-| CI templates, release process, Vault roles, docs sync, catalog update | `klok-environment-build-ci-templates` |
+| CI templates, release process, Vault roles, documentation chain, catalog update | `klok-environment-build-ci-templates` |
 | ODL REST and request/reply, tasks API | `klok-integration-klok-api-opensearch` |
 | ODL writers, log receivers | `klok-integration-klok-egress-opensearch` |
 | Scheduled queries, stale task detection | `klok-integration-klok-ingress-opensearch` |

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

@@ -35,5 +35,9 @@ Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (
 
 * A route id that does not start with the solution id, or two routes with the same id.
 * Publishing to a hand written topic string; use the resolver and the datamodel.
+* Choosing a tenant, index, repository or account from a field in the message; the topic decides the tenant.
+* Sharing broker credentials between services, or granting a whole namespace of another domain or tenant.
+* Publishing into another tenant's namespace, with `<RouteId>.topic.tenant-override` or otherwise; a route consumes
+  another tenant's topic with the override and a `consume` grant, and publishes only in its own tenant.
 * Catching exceptions to return HTTP 200 with an error text.
 * Pinning a framework or datamodel version in `gradle/klok-libs.versions.toml` by hand.