@klok-integration/cli 0.7.269 → 0.7.279

package/assets/agents/AGENTS.datamodel.md

@@ -14,7 +14,9 @@ dependency catalog. Read `klok docs read klok-framework-klok-common` for naming
   (`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.
+  silent change of an existing one. The pipeline's `klok_datamodel_compatibility` fails a merge request whose change
+  breaks a service built with any earlier release, in either direction: read its `breaking:` lines, then make the
+  change compatible or create the next major version (the `klok-datamodel` skill).
 * `klok-datamodel-project.json` at the root is the model's metadata (name, description, class, model type,
   `targetNamespace`, template version), rendered from `klok/environment/project-template-datamodel`; klok.dev and
   the documentation payload read it. The pipeline takes the artifact and the Java package from the repository path

package/assets/agents/AGENTS.documentation.md

@@ -13,8 +13,8 @@ content arrives here. There are two kinds, and they are edited differently:
   * `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.
+  * what is generated and how (chapters, sections, prompts, languages, model): klok.dev, Run → Documentation,
+    tab 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.

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

@@ -141,9 +141,11 @@ whether a model may travel on a topic; it decides how widely the model is shared
 * The major version is part of the name: repository `<model>-v<n>` in kebab case, XSD root element `<Model>_v<n>`,
   class and topic `<Model>V<n>`. A compatible change (a new optional field) stays in the major version; consumers
   ignore unknown fields. A breaking change (remove, rename or retype a field, change its meaning, make an optional
-  field required) is a new major version in a new repository, run in parallel with the old one, bridged by
-  `KlokSchemaUpgradeBridge` / `KlokSchemaDowngradeBridge` while readers move. A published version is never edited
-  into a new shape.
+  field required, add or remove an enumeration value) is a new major version in a new repository, run in parallel
+  with the old one, bridged by `KlokSchemaUpgradeBridge` / `KlokSchemaDowngradeBridge` while readers move. A
+  published version is never edited into a new shape. The datamodel pipeline enforces it: every merge request is
+  compared with every earlier release of the datamodel, both ways, because producers and consumers deploy in any
+  order, and a change that breaks one fails (`klokDatamodelCompatibilityCheck`).
 * A, B and C (and X with its own repository) generate Java, Python and TypeScript classes that are compatible on the
   wire, and their versions are written into the dependency catalog.
 

package/assets/agents/skills/klok-cli/reference.md

@@ -897,7 +897,7 @@ Deployment manifests in the GitOps repository that Argo CD applies
 klok manifest update [options]
 ```
 
-Set the image of one container in one manifest file, then commit and push it
+Set the image of one container in one manifest file and in the service's per-tenant instances, then commit and push
 
 | Option | Description |
 |---|---|
@@ -909,6 +909,7 @@ Set the image of one container in one manifest file, then commit and push it
 | `--container <name>` | Container to update (default: KLOK_MANIFEST_CONTAINER, else the only one in the file) |
 | `--workload <name>` | [<kind>/]<name> of the workload, when the container name repeats (default: KLOK_MANIFEST_WORKLOAD) |
 | `--branch <name>` | Branch to push to (default: KLOK_MANIFEST_BRANCH, then main) |
+| `--no-instances` | Leave the per-tenant instances <tenant>/platform/<name>/<name>-crds.yaml alone (default: update them; KLOK_MANIFEST_INSTANCES=false turns it off too) |
 | `-n, --dry-run` | Clone and edit, print the diff, commit and push nothing |
 
 ```
@@ -918,6 +919,12 @@ catalog) is then a new reference that Argo CD rolls out, while an image that cam
 the same digest and changes nothing. Without a digest the manifest says only the tag, and a new image under an old tag is
 never rolled out: nodes keep the copy they cached.
 
+Instances: a platform service can run once per tenant from the same image, each instance in its own manifest
+<tenant>/platform/<name>/<name>-crds.yaml, where <name> is the repository name of <project path>/<name>-crds.yaml.
+Every such file in another tenant's folder whose containers run the same image repository (any tag or digest) gets
+the new image in the same commit; only those image lines change. A file of another image is left as it is, and so is
+the project's own tenant folder. --no-instances updates the project's own manifest alone.
+
 Credentials: in CI the job logs in to Vault with its identity token (VAULT_ID_TOKEN) and the role
 <tenant>-ci-protected (KLOK_VAULT_DEPLOY_KEY_ROLE overrides it), which only pipelines of a protected branch or tag
 can use, and reads the deploy key and the pinned host key from secret/<tenant>/CICD_KEY and

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

@@ -65,7 +65,15 @@ domains read should still travel as class B or C (transform at the edge).
 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. 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.
+   has moved. The pipeline decides which is which: `klok_datamodel_compatibility` compares the Avro schema the
+   generated classes register on the broker with every earlier release, both ways, and fails on a numeric or
+   boolean element added without `minOccurs="0"`, a removed or renamed field, a changed type, a field made required
+   or optional, an added or removed enumeration value and a removed type. Its `breaking:` lines name the field. Make
+   the change compatible (add optional fields only; keep a field you no longer need and stop filling it), or create
+   `<name>-v<n+1>`. Only when no service runs some earlier releases any more does the owner record that in
+   `klok-datamodel-project.json` (`"compatibility": {"since": "<release>", "reason": "<who moved, when>"}`); never
+   to get a new break through. The rules are on the *Datamodel compatibility* page of
+   `klok docs read klok-framework-klok-gradle-plugin`.
 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>` with its Python and TypeScript packages,

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

@@ -72,6 +72,11 @@ as a red pipeline. Vault CI login is not one of them: it needs nothing per proje
   keys); the service's own Keycloak client with its broker grants; and every topic `./gradlew klokTopics` lists, in
   its owning tenant's Pulsar file and applied (requested in klok.dev, or a merge request to
   `klok/environment/klok-environment-setup`). A topic's `_DLQ` and a `_Request` topic's `_Response` come with it.
+* For a platform service's instance in another tenant (the ODL, tasks, the OpenSearch ingress and egress): the same
+  image, deployed from `<tenant>/platform/<name>/<name>-crds.yaml` in the manifests repository, written by hand with
+  the service's current image and the tenant's namespace, Vault role, env secret and Keycloak client. Nobody updates
+  its image by hand: the service's own `update_manifest` (`klok manifest update`) sets every instance that runs the
+  same image repository in the same commit.
 * Documentation projects need the tenant's docs upload client: Keycloak client `klok-docs-upload-<tenant>` and its
   id and secret in `secret/<tenant>/common/repo/cicd-environment-variables`.