@klok-integration/cli 0.3.3 → 0.3.4

package/README.md

@@ -43,6 +43,8 @@ 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 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 +95,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,16 @@ 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). 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.
 * 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

@@ -30,7 +30,8 @@ needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt
 * `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.
@@ -154,10 +157,15 @@ step by step procedure; the contract every agent follows is:
 
 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://klok[_<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,8 +188,9 @@ 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
 
@@ -194,8 +203,8 @@ Klok documentation has three levels, and a change is finished only when all thre
 3. 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
+4. 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

@@ -11,8 +11,10 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pip
 ## 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
@@ -45,7 +47,8 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pip
 
 * 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` |