@klok-integration/cli 0.3.2 → 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.
@@ -111,8 +114,10 @@ step by step procedure; the contract every agent follows is:
   tenant with the right to create projects in the domain. That is the supported path and it provisions what the
   project needs to build. Creating a project by hand is a legitimate fallback under *Git är sanningen*, but it is
   not the normal path: say up front what a human will still have to do, rather than letting it surface as a red
-  pipeline. Today that always includes the Vault CI role `<tenant>-ci-project-<gitlab id>`, which needs both
-  `default` and the tenant CI read policy; see `klok/application/frontend-klok-dev` issue #7.
+  pipeline. Vault needs nothing per project: the tenant CI role `<tenant>-ci` accepts every project under the
+  tenant's root group. A tenant without it fails every job at `auth/jwt/login` with
+  `role "<tenant>-ci" could not be found`; setting a tenant up is described in `klok-docs/ci/tenant-onboarding.md`
+  of `klok/environment/build-ci-templates`.
 * 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.
@@ -152,9 +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 the CI mirrors into the
-  repository's documentation project. 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:
@@ -177,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
 
@@ -191,19 +203,18 @@ 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
 
 The pipeline on `main` publishes the project's documentation payload (`KlokProjectDocumentationV1`: routes,
-sources, configuration keys and the whole `klok-docs/` folder with a hash per file). A documentation flow that
-reads that payload together with the merge request description and the diff, and proposes the central updates as
-merge requests for a human to review, is being built; until it runs, nothing behind you looks at the central
-documentation. Either way the steps above are the ones that matter: an author who knows what changed writes
-better documentation than a flow that reads the diff afterwards, and a proposal is a safety net for what was
-missed, never a reason to skip writing it.
+sources, configuration keys and the whole `klok-docs/` folder with a hash per file). KlokDocumentationEgress
+(`klok/integration/klok-documentation-egress`) turns it into the project's published documentation: your
+`klok-docs/` pages as written, with `KLOK:GENERATED` regions filled, next to generated pages for routes,
+datamodels and configuration. Nothing behind you updates the central platform documentation, so the steps above
+are the ones that matter.
 
 ## How to work
 

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
@@ -26,9 +28,9 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pip
    (`klok-datamodel-project.json`, `klok-template.json`, the agent instruction files, the three page
    `klok-docs/datamodel/` layout).
 
-   A hand created project has **no Vault CI role**, so its first `publish_java_projects` fails with
-   `role "<tenant>-ci-project-<id>" could not be found`. Say that up front and give the user the command; see
-   the `klok-release` skill.
+   Vault needs nothing per project: the tenant CI role `<tenant>-ci` accepts every project under the tenant's
+   root group. If `publish_java_projects` fails at `auth/jwt/login`, the tenant itself is not set up; see the
+   `klok-release` skill.
 2. Write the XSD under `schema-definition-xsd/`: single `xs:` prefix, `targetNamespace` with `xmlns:tns`,
    `elementFormDefault="qualified"`, one root element `<Name>_vN` that references every complex type. Enumerations
    as `xs:enumeration`.
@@ -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` |

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

@@ -40,17 +40,19 @@ letting them surface as a red pipeline.
 
 ## Setting up a new project (what must exist)
 
-* Vault JWT role `<tenant>-ci-project-<gitlab id>` bound to that `project_id`, carrying **both** `default` and
-  the tenant CI read policy (`klok-cicd-read` for tenant `klok`). A role with only `default` authenticates but
-  cannot read the shared secrets, and `publish` still fails — that is why the pipelines of projects 175 and 191
-  were red for months. Without any role at all the job fails at `auth/jwt/login` with
-  `role "<tenant>-ci-project-<id>" could not be found`.
+* Nothing in Vault per project. Every job logs in with the tenant CI role `<tenant>-ci` (a Vault JWT role bound
+  to `namespace_path` `<tenant>` and `<tenant>/*`, carrying `default` and the tenant CI read policy
+  `<tenant>-cicd-read`). The templates set `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. A tenant without the role fails
+  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is in
+  `klok-docs/ci/tenant-onboarding.md` of `klok/environment/build-ci-templates`, every credential and the step
+  that uses it in `klok-docs/ci/authentication.md` there.
 * For anything the pipeline resolves from a package registry (framework, plugin, datamodels): the project's
   top-level group must be on the package project's job token allowlist.
 * For a deployed service: a manifest under `klok/integration/<name>/`, the Kubernetes service account, a Vault
   Kubernetes role `<name>-role` with a policy reading `secret/data/<tenant>/integration/<name>/env`, and the env
   secret itself (broker credentials, service specific keys).
-* Documentation projects need the tenant's docs upload client in Keycloak and in Vault (`secret/<tenant>`).
+* 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`.
 
 Vault is changed by humans only: propose the exact `vault write` / `vault policy write` command with every existing
 field, and let the user run it.
@@ -59,8 +61,9 @@ field, and let the user run it.
 
 | Symptom | Cause |
 |---|---|
-| `role "<tenant>-ci-project-<id>" could not be found` at `auth/jwt/login` | no Vault CI role for the project; it was created without provisioning |
-| `permission denied` reading `secret/.../cicd-environment-variables` | CI role exists but lacks the tenant CI read policy (has only `default`) |
+| `role "<tenant>-ci" could not be found` at `auth/jwt/login` | the tenant has no CI role yet (tenant onboarding) |
+| `claim "namespace_path" does not match` at `auth/jwt/login` | the project is outside the tenant's root group, or `VAULT_AUTH_ROLE` names another tenant's role |
+| `permission denied` reading `secret/.../cicd-environment-variables` | the CI role lacks the tenant CI read policy (has only `default`) |
 | `403` on `groups/<tenant>/-/packages/maven/...` | job token allowlist of the package project lacks the reader's group |
 | `Could not find dev.klok...:<version>` | the version is not published yet, or the catalog copy is stale (`updateKlokLibsToml`) |
 | `already deployed` from JReleaser | Maven Central already has that version; a `main` build is a new timestamp, do not retry the same job |