@klok-integration/cli 0.7.248 → 0.7.279

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

@@ -34,31 +34,46 @@ domains read should still travel as class B or C (transform at the edge).
    ends in `supplier_invoice_v1`. Inside the XSD the model keeps its PascalCase form: root element
    `SupplierInvoice_v1`, root type `SupplierInvoiceV1`.
 
-   **Create it with klok.dev's datamodel wizard.** It pushes a new repository from `project-template-datamodel`
-   with the XSD and its `meta.json`, but it does not render the template's `__KLOK_*__` placeholders yet
-   (klok/application/frontend-klok-dev#33): check the
-   new repository and render any that are left, as below, before relying on its pipeline. The agent at
-   https://agent.klok.dev cannot create datamodel projects yet (klok/application/frontend-klok-dev#42).
+   **Create it by hand from the template.** klok.dev edits existing models through a merge request but does not
+   create datamodel repositories yet, because it cannot render the template's `__KLOK_*__` placeholders for them
+   (klok/application/frontend-klok-dev#33); it points to the way by hand instead. The agent at
+   https://agent.klok.dev cannot create datamodel projects either (klok/application/frontend-klok-dev#42).
+   `klok datamodel names --class <A|B|C|X> --name <PascalCase> --major <n>` (with `--system` for class X and the
+   global `--domain` for class C) prints every derived value: repository, XSD file, root element, root type,
+   `targetNamespace` and the documentation project.
 
    By hand it is: `git clone` the template, `git remote rename origin template`, `git remote add origin <new
    repo>`, render every `__KLOK_*__` token listed in `klok-template.json` (including the XSD file name), push
    `main`. Keep the `template` remote so later template improvements can be pulled in. Never assemble the
    project by copying files out of a sibling datamodel: the copies go stale and whole files get missed
-   (`klok-datamodel-project.json`, `klok-template.json`, the agent instruction files, the three page
-   `klok-docs/datamodel/` layout).
+   (`klok-datamodel-project.json`, `klok-template.json`, the agent instruction files, `klok-docs/` with its
+   guide `README.md` and the `datamodel/` pages).
 
    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`.
-3. `meta.json` in the flat form with `targetNamespace`, and `klok-docs/` with the purpose, the important fields and
-   the producers and consumers.
+   as `xs:enumeration`. `klok datamodel validate` checks it with the pipeline's rules before you push.
+3. `klok-datamodel-project.json` at the root is the model's metadata (name, description, class, model type,
+   `targetNamespace`, template version), rendered from the template; klok.dev and the documentation payload read
+   it. An older repository's `schema-definition-xsd/*.meta.json` is only klok.dev's fallback for a repository
+   without it, so keep one of the two, not both. The pipeline takes the artifact and the Java package from the
+   repository path and the XSD file name, never from metadata. `klok-docs/datamodel/` holds the three pages of the
+   template (`index`, `usage`, `changes`): the purpose, the fields that need explaining, the producers and consumers
+   and the history of compatible changes.
 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,
@@ -72,7 +87,8 @@ domains read should still travel as class B or C (transform at the edge).
 ## 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.
+  reference the alias, the project name in camel case (`klokLibs.klokOdlV1` or the bundle for tenant klok's
+  models, `tenantLibs.<alias>` for another tenant's). Never type a version.
 * 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.

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

@@ -12,7 +12,7 @@ serves it to a browser session and to a GitLab personal access token, which is w
 ```
 klok docs list                       # the projects you may read: doc id, title, description
 klok docs read <doc-id>              # the markdown on stdout, one status line on stderr
-klok docs read <doc-id> --json       # {docId, url, source, status, etag, fetchedAt, bytes, content}
+klok docs read <doc-id> --json       # {docId, requestedDocId, movedTo, url, source, status, etag, fetchedAt, bytes, content}
 klok docs read <doc-id> --out x.md   # to a file
 klok docs id [tenant/group/.../repo] # the doc id of a repository, this one by default
 ```
@@ -59,6 +59,7 @@ question is about what a project does.
 | `klok docs read` says | Meaning | What to do |
 |---|---|---|
 | the content, `source: server` or `source: cache` | the page as published, or the cached copy | read it |
+| `klok docs read: <old-id> moved to <new-id>` on stderr, then the content | the project was renamed or moved; the content is the new id's | read it, cite the new id (`docId` of `--json`), and fix the link or note the old id came from |
 | exit 4, "No or invalid GitLab token" | no `KLOK_GIT_APIKEY` (or `--token`), or the token is not valid | say so and ask for a token with `read_api`; do not guess |
 | "not a member of the tenant or domain that owns …" (403) | the page exists and your GitLab account may not read it | say so and ask for access; do not guess and do not try another way in |
 | "… is not published; read the repository's klok-docs/ on main" (404) | the project has no published documentation yet | read the source pages: `git -C <repo> fetch origin && git show origin/main:klok-docs/<page>.md`; `klok-docs/toc-manifest.json` lists them. The generated pages (routes, datamodels, configuration) exist only on the portal |
@@ -75,4 +76,5 @@ question is about what a project does.
    runbook in `klok-framework-development-guide` when it touches onboarding; read the framework documentation
    before writing or changing a route.
 5. Cite the doc id and the `fetchedAt` from `klok docs read <doc-id> --json` in your answer or merge request
-   description, so reviewers can tell which version of the page you relied on.
+   description, so reviewers can tell which version of the page you relied on. After a move, `docId` is the new id;
+   cite that one.

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`.
 

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

@@ -17,8 +17,9 @@ motivates.
    `KlokProcessingRoute<IN, OUT>`; egress to a system: `KlokOfframpRoute<DOM, SYS>`; synchronous request/reply:
    the `Sync` variants; REST: `KlokRestApi` plus one `KlokRestApiHandlerRoute` per operation; long running work:
    `KlokAsyncTaskWorkerRoute<REQ, RES>`; anything else: `KlokCustomRoute`.
-2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route, the solution number from the
-   portal registry. Sub routes are `S`, timers `T`.
+2. **Name it.** `<TENANTSHORT><NNN><LEG><seq>_<Description>`, one class per route. `<TENANTSHORT><NNN>` is the id of
+   the solution in `<tenant>/integration-solutions`, allocated there by a merge request (`klok solutions new`).
+   Sub routes are `S`, timers `T`.
 3. **Bind the datamodels** as type parameters; take them from the catalog bundle, never hand written DTOs.
 4. **Choose the topic purpose** of every topic the route publishes or consumes (*Topic purpose*), and make sure every
    topic exists (*Topics on the broker*): the broker never creates one.
@@ -74,7 +75,7 @@ the purpose.
 * **Name** the flow as both sides understand it (`created`, `reminder`, `documentation`): letters, digits, `-` and
   `.`, never `_`, and no version or environment. Task types are `<domain>.<verb>-<object>`.
 * **One purpose, no reader.** A topic has at most one purpose. A reader, also one in another tenant, is identified by
-  its subscription, whose name is its route id (`DEG012E1_...`; `<RouteId>.subscription.name` overrides it), and never
+  its subscription, whose name is its route id (`DGR012E1_...`; `<RouteId>.subscription.name` overrides it), and never
   adds a suffix to the topic. When the content belongs to one reader, the publisher may choose that reader's tenant
   slug as the purpose (`PersonnelScheduleExportV1_degerfors`); that is the publisher's choice, not something a reader
   in another tenant needs.

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

@@ -30,10 +30,14 @@ shared platform service) in `klok/integration-solutions`.
    issue, never to ignore.
 3. **Read the design.** The solution document and any design page next to it, then each project's `klok-docs/`
    (`klok docs read <doc-id>`, `klok docs id <repo path>` gives the id).
-4. **A new solution gets an id and a document before code.** Take the id from the code, not the next free
-   number: grep the integration repositories, pushed branches included, and run `klok solutions validate`. Write
-   `README.md`, `solution.meta.json` (`generatedBy: "manual"`) and, when the details do not fit, a design page next
-   to it, in a worktree of the registry. The sections are listed in the registry README.
+4. **A new solution gets an id and a document before code.** The merge request that adds the solution's folder to
+   the registry is the allocation: `klok solutions new "<name>" --dry-run`, then without `--dry-run`, opens it from a
+   worktree of the registry with the next free number (`klok solutions next` says why that one: the registry, its
+   history and open merge requests, and the route classes on every branch). Never choose another number, and never
+   reuse one, not even a removed solution's. The folder starts `"status": "reserved"`; write `README.md`, the
+   describing fields of `solution.meta.json` and, when the details do not fit, a design page next to it, and set the
+   status to `active`. The sections are listed in the registry README. `klok solutions validate --base origin/main`
+   checks the change against the registry's history and its open merge requests.
 5. **Reuse before building.** Look for an existing solution or platform capability first: tasks and the task API
    (KLK002), the ODL, the AI services (KLK003), mail (KLK006), the claim check, datamodels in the catalog. A
    capability that needs a change to serve the solution is *reused, slight change*, with its own merge request in
@@ -81,6 +85,9 @@ shared platform service) in `klok/integration-solutions`.
 ## Things that are always wrong
 
 * Code for a new solution before its document exists, or a route id whose prefix is not a registered solution.
+* A solution number that is not the next free one (`klok solutions next`), or one used before.
+* Deleting a solution's folder in a merge request: a solution that stops running gets `"status": "retired"`; only a
+  platform admin removes one, on `main`, and its number stays spent.
 * A leg in code that its solution document does not name, or a document that names a leg as built that is not.
 * Reusing a leg and sequence (`KLK002A11`) for a second route.
 * Integration logic in a Python or TypeScript client, or in an external engine, without a `[TACTICAL]` entry.

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

@@ -36,7 +36,9 @@ basename, never put the worktree inside `.claude`, inside the canonical checkout
    you. Keep the existing project rules; this skill does not replace them.
 3. **Inspect, do not touch.** `git -C <canonical> status --short`, `git -C <canonical> worktree list --porcelain`
    and the canonical branch. Never `stash`, `reset`, `clean`, `checkout` or `switch` there; the only update of a
-   canonical checkout is `klok sync pull`, which fast-forwards it or reports why it cannot. Uncommitted changes in
+   canonical checkout is `klok sync pull`, which fast-forwards it or reports why it cannot. When it reports that the
+   checkout's GitLab project moved, the move and the `git worktree repair` it lists are the person's: hand them over,
+   and base the worktree on the project at its new path. Uncommitted changes in
    the canonical checkout are not a blocker; the worktree starts from committed history. If the task depends on
    those changes, say so and ask for a handoff instead of moving them.
 4. **Choose the base.** Fetch the remote and resolve its default branch from the remote HEAD