@klok-integration/cli 0.3.4 → 0.4.0

package/README.md

@@ -43,6 +43,7 @@ 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. |

package/assets/agents/AGENTS.datamodel.md

@@ -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.integration.md

@@ -27,6 +27,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

@@ -152,6 +152,37 @@ 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
 
@@ -159,7 +190,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),
@@ -197,13 +228,17 @@ Klok documentation has three levels, and a change is finished only when all thre
 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 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/skills/klok-datamodel/SKILL.md

@@ -8,6 +8,24 @@ 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>`,
@@ -37,11 +55,14 @@ 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
 

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.