@klok-integration/cli 0.7.248 → 0.7.279

package/README.md

@@ -25,8 +25,8 @@ variable: `KLOK_AGENT_URL`, `KLOK_TENANT`, `KLOK_DOMAIN`, `KLOK_DEV_URL`, `KLOK_
 `KLOK_KEYCLOAK_CLIENT_ID`, `KLOK_GIT_URL`, `KLOK_GIT_LOCAL_WORKSPACE`, `KLOK_GIT_APIKEY`. Run
 `klok config list` to see what is set and where it comes from.
 
-The GitLab token can be stored with `klok config set klokApiKey` (a hidden prompt, so it stays out of the shell
-history). It is shown as `****` everywhere unless you run `klok config get klokApiKey --reveal`, and the file
+The GitLab token can be stored with `klok config set klokApiKey`: it asks `Enter API key:` and shows a `*` for
+each character, so the token stays off the screen and out of the shell history. It is shown as `****` everywhere unless you run `klok config get klokApiKey --reveal`, and the file
 is kept at mode 0600.
 
 Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
@@ -53,7 +53,9 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok docs id [path]` | The doc id of a repository path. |
 | `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 solutions next` | The next free solution id of the tenant, from the registry, its open merge requests and the route classes on every branch of the workspace. |
+| `klok solutions new "<name>"` | Reserve the next solution id by a merge request in the registry, from a task worktree. |
+| `klok solutions validate` | Check the descriptors of an integration solution registry against the descriptor contract and, in a merge request, that no solution is removed and no solution id reused or taken twice. |
 | `klok ci env` | Show what klok-cli detected about the CI job it runs in. |
 | `klok fleet status\|rebuild` | Every deployed service: what it was built from, whether that is the latest commit and the catalog's broker client, and which clients the broker sees; rebuild the stale ones one pipeline at a time. |
 | `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

@@ -8,19 +8,25 @@ dependency catalog. Read `klok docs read klok-framework-klok-common` for naming
 ### Rules
 
 * 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`).
+  `xmlns:tns` set; `elementFormDefault="qualified"`. Validate with `klok datamodel validate` before pushing; it
+  applies the rules of the pipeline's `generate_avro_from_xsd`.
 * 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.
+  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
+  and the XSD file name, never from metadata.
+* Consumers reference the artifact only through the catalog alias (`klokLibs.<key>` for tenant klok's models,
+  `tenantLibs.<key>` for another tenant's), never by literal version.
 * Datamodel documentation lives in `klok-docs/` (purpose, fields that need explanation, producers and consumers,
-  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
+  design decisions); `klok-docs/README.md` says which page holds which, and is never published. 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

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.
@@ -24,6 +24,10 @@ content arrives here. There are two kinds, and they are edited differently:
 * 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`.
+* `klok-documented-project.json` at the root names the source project and the doc ids, and KlokDocumentationEgress
+  writes it. `"state": "retired"` there makes `klok docs publish` take every doc id it names (`docId`,
+  `previousDocIds`) off the portal instead of uploading; `--dry-run` lists them. Do not edit it to keep a project
+  published: its state follows the source project.
 * Visibility follows `meta.json` `scope` (`global`, `tenant`, `domain`, `system`); a page that must not be seen by
   another domain belongs in a project with that scope, not behind a note.
 * Preview locally with `znai preview --source=docs`, and check what a publish would do with

package/assets/agents/AGENTS.integration.md

@@ -18,7 +18,8 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
 
 ### Rules
 
-* Route class name = route id `<TENANTSHORT><NNN><LEG><seq>_<Description>`; one solution id per business flow.
+* Route class name = route id `<TENANTSHORT><NNN><LEG><seq>_<Description>`; one solution id per business flow, and
+  its prefix is a solution registered in `<tenant>/integration-solutions` (a new one: `klok solutions new`).
   Configuration keys are `<RouteId>.<key>` with fallback to `<SolutionId>.<key>` and `klok.route-defaults.<key>`.
 * Datamodels are the type parameters of the pattern class and come from the catalog bundles; never hand write DTOs
   for something a datamodel project should own.
@@ -50,7 +51,9 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
   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.
+* Update `klok-docs/` (overview, design decisions, routes, usage, operations) in the same merge request as the
+  change. `klok-docs/README.md` says which page answers which question and how the folder reaches docs.klok.dev;
+  it is the folder's guide and is never published.
 * 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/`

package/assets/agents/AGENTS.workspace.md

@@ -14,7 +14,8 @@ what went wrong (no token, no network); say so instead of guessing.
 
 On a workstation, `klok sync pull` then brings the workspace current before you read it: it fast-forwards every
 canonical checkout under the workspace root, never merges or resets one, and skips `<root>/worktrees`. It is the one
-sanctioned update of a canonical checkout. A service never clones a repository just to read it: klok.dev and the agent
+sanctioned update of a canonical checkout. A checkout whose GitLab project moved, was archived or is gone is reported
+with the commands that fix it, and those are the person's to run. A service never clones a repository just to read it: klok.dev and the agent
 read through the GitLab API, docs.klok.dev and the integration context. The `klok-cli` skill says which klok command
 does what.
 
@@ -300,6 +301,11 @@ solution it belongs to, and new development and maintenance follow the same proc
 * Route ids: `<TENANTSHORT><NNN><LEG><seq>_<Description>` (`KLK002I1_OdlScheduledQuery`); legs `I` ingress,
   `P` processing, `E` egress, `A` API, `S` sub route, `T` timer. The class name is the route id, the config prefix
   and the solution key.
+* `<TENANTSHORT>` is the tenant's `shortname` in tenants.yml of `klok/environment/klok-environment-setup`: the first
+  three consonants of the tenant slug in upper case (`klok` KLK, `degerfors` DGR, `konvoj` KNV), decided by the
+  platform. A solution id `<TENANTSHORT><NNN>` is allocated by the merge request that adds its folder to
+  `<tenant>/integration-solutions` (`klok solutions new`) and never reused; a solution that stops running is retired
+  with `"status": "retired"`.
 * Topics: `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`, request/reply
   `ReqRes_<Req>_<Res>_Request|_Response`, dead letters `<topic>_DLQ`. The datamodel major version is in the class
   name (`CustomerV1`). The purpose is optional and the publisher's: the solution requires it so that one datamodel
@@ -327,7 +333,7 @@ access, Keycloak broker clients or a service that serves several tenants.
 * **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. The topic keeps its own name; the
-  reader is known by its subscription (its route id, `DEG012E1_...`). When the content belongs to one reader, the
+  reader is known by its subscription (its route id, `DGR012E1_...`). When the content belongs to one reader, the
   publisher may choose that reader's tenant slug as the purpose
   (`persistent://konvoj/hr/PersonnelScheduleExportV1_degerfors`); that is the publisher's choice, not a condition
   for reading across tenants.
@@ -392,6 +398,9 @@ Klok documentation has three levels, and a change is finished only when all thre
   Write both **as the work happens**, not at the end of the branch. By the end nobody remembers why a choice was
   made, and a guide written from memory describes the product somebody meant to build.
 
+  `klok-docs/README.md` is the folder's own guide for the people and agents who write it: a project made from a
+  Klok template has one that says which page answers which question. It is neither published nor read by Kloker.
+
   Keep `klok-docs/` as the single copy. Do not mirror a page into a second `docs/` folder: two copies of one page
   are two pages that quietly stop agreeing. `docs/` may hold what is genuinely not product documentation, such as
   a strategy document that predates the code.

package/assets/agents/knowledge/glossary.md

@@ -16,7 +16,8 @@ it as the source does.
 | Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
 | Route, route id | One Camel route per Java class. Its id is `<TENANTSHORT><NNN><LEG><seq>_<Description>`, for example `KLK007T1_PublishKlokStandard`; the class name is the id |
 | Leg | The letter in a route id: I ingress (onramp, brings data in), P processing, E egress (offramp, delivers data out), A API, S sub route, T timer |
-| Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007` |
+| Tenant short name | `TENANTSHORT`, three upper case letters that start every solution and route id of a tenant: the first three consonants of the tenant's name (`KLK` for klok, `DGR` for degerfors), decided by the platform |
+| Solution | The business flow a set of routes implements; its id is the route id's prefix, for example `KLK007`. The id is allocated once, by a merge request in the tenant's `integration-solutions` registry, and never reused; a solution is reserved, active or retired |
 | Solution document | The `README.md` of a solution in the tenant's `integration-solutions` registry: its services, legs and flows, kept true to what is built |
 | Correlation id | `klok-correlation-id`: follows one business flow across routes and messages |
 | Task | Long-running work tracked by the platform (`KlokTaskV1` events, visible in klok.dev and the task API), for example an `ai.chat` task that asks Kloker for text |

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

@@ -29,9 +29,11 @@ documentation or the dependency catalog can give you.
 ## Routes and naming
 
 * One Camel route per Java class. The route id is the class name, the configuration prefix and the solution key:
-  `<TENANTSHORT><NNN><LEG><seq>_<Description>` (`KLK002I1_OdlScheduledQuery`, `ACME001E1_FortnoxInvoiceOfframp`).
-  * `TENANTSHORT`: the tenant short name, upper case. `NNN`: the solution number from the klok.dev registry, at
-    least three digits. The solution id is `<TENANTSHORT><NNN>` (`KLK002`).
+  `<TENANTSHORT><NNN><LEG><seq>_<Description>` (`KLK002I1_OdlScheduledQuery`, `ACM001E1_FortnoxInvoiceOfframp`).
+  * `TENANTSHORT`: the tenant's short name, three upper case letters: the first three consonants of the tenant
+    slug (`klok` KLK, `degerfors` DGR, `konvoj` KNV), decided by the platform and recorded as `shortname` in
+    tenants.yml of `klok/environment/klok-environment-setup`. `NNN`: the solution number, three digits; 900–999
+    are the framework's. The solution id is `<TENANTSHORT><NNN>` (`KLK002`).
   * Legs: `I` ingress, `P` processing, `E` egress, `A` API (REST, SOAP, MCP), `S` sub route or custom route,
     `T` timer. `seq` numbers the routes of one leg in a solution.
 * Every route extends exactly one pattern base class; never write a bare Camel `RouteBuilder`:
@@ -65,7 +67,10 @@ documentation or the dependency catalog can give you.
 
 * Every route belongs to a solution, and every solution has a document: `README.md` and `solution.meta.json` in
   `<tenant>/integration-solutions/solutions/<SOLUTIONID>_<slug>/`. A new solution gets its id and its document before
-  its first route; the id is taken from the code, never reused, and a leg and sequence (`KLK002A11`) names one route.
+  its first route. The id is allocated by the merge request that adds the folder (`klok solutions new`; `klok
+  solutions next` shows the next free number and why), and a number is never reused, not even a removed
+  solution's. A solution is `reserved`, `active` or `retired` (`status` in `solution.meta.json`); one that stops
+  running is retired, not deleted. A leg and sequence (`KLK002A11`) names one route.
 * The document classifies every service the solution needs: new project, new routes in an existing project, reused
   with a change, reused as is, client change. It maps the legs (route id, project, pattern, topics with purpose,
   datamodels) and links each project's `klok-docs/` for the details.
@@ -87,7 +92,7 @@ documentation or the dependency catalog can give you.
   several flows, the publisher sets it and the reader consumes the purpose the publisher chose. A topic name has at
   most one purpose, never a second suffix.
 * A reader is identified by its subscription, whose name is its route id (`<RouteId>.subscription.name` overrides
-  it), so the reading tenant's short name is in it (`DEG012E1_...`). A reader never appears in the topic name.
+  it), so the reading tenant's short name is in it (`DGR012E1_...`). A reader never appears in the topic name.
   When the content belongs to one reader, the publisher may choose that reader's tenant slug as the purpose
   (`persistent://konvoj/hr/PersonnelScheduleExportV1_degerfors`); that is the publisher's choice, not a condition
   for reading across tenants.
@@ -136,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/knowledge/retired-patterns.txt

@@ -17,6 +17,12 @@
 # Route ids are <TENANTSHORT><NNN><LEG><seq>_<Description>, legs I P E A S T.
 \bS<(NNNN|ID|SolutionID|Solution|NNN)> # old S-prefixed integration ids; use <TENANTSHORT><NNN><LEG><seq>_<Description>
 \bS[0-9]{4}[IEP][0-9] # old S-prefixed route id such as S0001I1; use KLK002I1_... style ids
+# Solution ids are allocated by a merge request in <tenant>/integration-solutions and never reused (2026-10-08); the
+# tenant short name is the first three consonants of the tenant slug, shortname in tenants.yml.
+(?i)\bsolution (number|id)s?\s+(is\s+|are\s+)?(taken\s+)?from\s+the\s+(klok\.dev|portal|klok\.dev\s+solution|portal\s+solution)\s+registry # a solution id is allocated by a merge request in <tenant>/integration-solutions (klok solutions new), never reused
+(?i)\bid is taken from the code # a solution id is allocated by a merge request in <tenant>/integration-solutions (klok solutions new); the code on every branch only counts as used
+(?i)\bfirst\s+(three|3)\s+letters\s+of\s+the\s+tenant # the tenant short name is the first three consonants of the tenant slug, its shortname in tenants.yml
+(?i)\bshort\s+(name|code)s?\s+(is|are)\s+the\s+(tenant'?s?\s+)?(name'?s?\s+|slug'?s?\s+)?first\s+(three|3)\s+letters # the tenant short name is the first three consonants of the tenant slug, its shortname in tenants.yml
 #
 # Topics are persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>].
 pulsar:// # topics are persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]
@@ -56,3 +62,8 @@ klok-(ingress|egress)-< # integration repositories are named <tenant>-<system>-<
 (^|[^<`\\])/think\b # a prompt token of an old Qwen model; the model name is the only switch (a quoted mention in a rule is fine)
 (^|[^`])/no_think\b # a prompt token of an old Qwen model; the model name is the only switch
 Kloker-Long # not a gateway model name; use Kloker-nothink or Kloker
+#
+# A datamodel's metadata is klok-datamodel-project.json, rendered from project-template-datamodel; the pipeline reads
+# no metadata, and klok.dev does not create datamodel repositories yet (frontend-klok-dev#33, 2026-10-10).
+(?i)meta\.json`? (uses|in) the flat form # a datamodel's metadata is klok-datamodel-project.json; *.meta.json is only klok.dev's fallback for an older repository
+(?i)create it with klok\.dev's datamodel wizard # klok.dev's wizard edits existing models; it does not create datamodel repositories yet (frontend-klok-dev#33), they are made by hand from project-template-datamodel

package/assets/agents/knowledge/roles/integration-architect.md

@@ -13,7 +13,8 @@ name the parts, and say what is wrong when it is wrong.
 1. Name the datamodel class of every payload you mention (A, B, C or X) and who reads it.
 2. Name the legs: ingress, processing, egress, API, or a solution of several legs.
 3. Choose one pattern base class per leg, as a design decision.
-4. Propose the solution id, the route ids and the topic names, following the platform rules.
+4. Propose the route ids and the topic names, following the platform rules. A new solution's id is never made up:
+   it is the next free number, reserved by a merge request in the tenant's registry (`klok solutions new`).
 5. Flag every tactical deviation with `[TACTICAL]`, its cost and its unwind condition, or say the design is
    strategy-pure.
 
@@ -21,7 +22,7 @@ A correct answer looks like this:
 
 "Visma exports invoices in its own format, a class X model. Finance and sales both read invoices, so the ingress
 maps each invoice to the class B model `InvoiceV1` before it reaches the broker. Use `KlokOnrampRoute` as
-`ACME001I1_VismaInvoiceOnramp`, split the nightly file into one fact event per invoice, and publish on
+`ACM001I1_VismaInvoiceOnramp`, split the nightly file into one fact event per invoice, and publish on
 `persistent://acme/finance/InvoiceV1`. If a consumer later needs Visma's format, that mapping belongs in an egress."
 
 A rejection names the problem and gives the broker-shaped replacement:
@@ -164,10 +165,10 @@ direct database or file share only for a system older than the team).
 Imitate the density of these answers, with the user's names.
 
 **Visma nightly invoice file.** The export is class X. Invoices are read by more than one domain, so the target is
-the class B model `InvoiceV1`. Ingress: `KlokOnrampRoute` as `ACME001I1_VismaInvoiceOnramp`, splitting the file
+the class B model `InvoiceV1`. Ingress: `KlokOnrampRoute` as `ACM001I1_VismaInvoiceOnramp`, splitting the file
 into one fact event per invoice (a processing splitter if the mapping is heavy), published on
 `persistent://acme/finance/InvoiceV1`. Do not publish the file as one large message unless the claim check carries
-it and the event holds only the reference. A later Visma-shaped export is an egress, `ACME001E1_...`, mapping B to
+it and the event holds only the reference. A later Visma-shaped export is an egress, `ACM001E1_...`, mapping B to
 X. Strategy-pure while each message stays small.
 
 **A front end that wants a JSON body now.** Ingress that cannot be fire and forget: `KlokOnrampRouteSync` as a

package/assets/agents/knowledge/roles/integration-developer.md

@@ -62,7 +62,7 @@ as the CloudEvent's data.
 
 ```java
 @ApplicationScoped
-public class ACME001I1_OrderOnramp extends KlokOnrampRoute<ShopOrder, OrderV1> {
+public class ACM001I1_OrderOnramp extends KlokOnrampRoute<ShopOrder, OrderV1> {
     @Override
     protected String fromUri() {
         return "platform-http:/orders";
@@ -84,7 +84,7 @@ system's reply type; the framework handles the request/reply topics and the time
 
 ```java
 @ApplicationScoped
-public class ACME002I1_CustomerLookup
+public class ACM002I1_CustomerLookup
         extends KlokOnrampRouteSync<CustomerRequest, CustomerResponse, CustomerLookupV1, CustomerV1> {
     @Override
     protected String fromUri() {
@@ -118,7 +118,7 @@ dead letters. Override `toUri()` and `transformBody(DOMAIN_MODEL body, Message m
 
 ```java
 @ApplicationScoped
-public class ACME001E1_InvoiceOfframp extends KlokOfframpRoute<InvoiceV1, LegacyInvoice> {
+public class ACM001E1_InvoiceOfframp extends KlokOfframpRoute<InvoiceV1, LegacyInvoice> {
     @Override
     protected String toUri() {
         return "https://legacy-invoice-system/invoices";
@@ -198,7 +198,8 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
    choose between a splitter and the claim check.
 2. **Reuse.** Before a new model, search the existing class B and C models, topics and routes, in klok.dev's
    context and on docs.klok.dev. A new topic only for a new contract.
-3. **Solution design.** Solution id from the klok.dev registry, the legs and their route ids, the models per leg,
+3. **Solution design.** The solution id, reserved by a merge request in `<tenant>/integration-solutions` (`klok
+   solutions new`), the legs and their route ids, the models per leg,
    `[TACTICAL]` for any deviation, written in the solution document before the code and kept current by every change
    of a leg (platform rules, *Solutions*).
 4. **Design per leg.** Base class, exchange pattern, URI, authentication (a Vault path reference, never a secret),
@@ -237,11 +238,11 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
 
 ## Worked answers
 
-**CRM over HTTP to Visma over JMS.** `ACME001I1_CrmCustomerOnramp extends KlokOnrampRoute<CrmCustomer, CustomerV1>`
+**CRM over HTTP to Visma over JMS.** `ACM001I1_CrmCustomerOnramp extends KlokOnrampRoute<CrmCustomer, CustomerV1>`
 with `fromUri` on the CRM webhook and a `transformBody` that sets `customerId`, `fullName` and `email`; it publishes
-`persistent://acme/sales/CustomerV1`. `ACME001E1_VismaCustomerOfframp extends KlokOfframpRoute<CustomerV1,
+`persistent://acme/sales/CustomerV1`. `ACM001E1_VismaCustomerOfframp extends KlokOfframpRoute<CustomerV1,
 VismaCustomer>` with `toUri` on the JMS queue and a `transformBody` into Visma's model. Validation that is a business
-rule is `ACME001P1_CustomerValidation`, a `KlokProcessingRoute` between two topics, not extra code in the onramp.
+rule is `ACM001P1_CustomerValidation`, a `KlokProcessingRoute` between two topics, not extra code in the onramp.
 
 **Synchronous lookup.** First choice: `KlokOnrampRoute` answering 202 with a task reference and a status the caller
 can poll. If the UI must have a synchronous answer: `KlokOnrampRouteSync` as above, a timeout of 10 to 20 seconds, the

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

@@ -18,11 +18,12 @@ CLI version, generated from the program itself; when it is missing (an installer
 | to know the agent instructions and skills are current, at the start of a task | `klok agents update --check` (exit 5: run `klok agents update`) |
 | the local workspace current before you read it | `klok sync pull` |
 | a repository you can see in GitLab but do not have locally | `klok sync clone --dry-run`, then `klok sync clone` |
-| what is dirty, unpushed or behind in the workspace | `klok sync status` (`--fetch` for a current "behind") |
+| what is dirty, unpushed or behind in the workspace, or moved, archived or gone in GitLab | `klok sync status` (`--fetch` for a current "behind") |
 | the documentation projects you may read | `klok docs list` |
 | one project's documentation | `klok docs read <doc-id>`; `klok docs id <tenant/group/.../repo>` derives a doc id |
 | an answer about the integration landscape, with links | `klok agent ask "<question>"`; `--session <first task id>` for a follow-up |
 | the impact of a datamodel change | `klok agent impact <datamodel> --change minor\|major\|remove` |
+| the next free solution id of the tenant, with why, or a new solution's id reserved by a merge request | `klok solutions next`, `klok solutions new "<name>" --dry-run`, then without `--dry-run` |
 | the solution registry checked against its contract, or against the code | `klok solutions validate`, `klok solutions check` |
 | whether the deployed services run what `main` and the catalog say | `klok fleet status` |
 | the platform catalog's agent assets or its dependents | `klok catalog publish-agents`, `klok catalog release-dependents` (both run in CI) |
@@ -40,17 +41,30 @@ CLI version, generated from the program itself; when it is missing (an installer
 key `workspace`, `KLOK_GIT_LOCAL_WORKSPACE`, default `~/devklok`) is fetched and fast-forwarded (`git pull
 --ff-only`). It never merges, rebases or resets, so a checkout with local commits or a diverged branch is reported,
 not changed, and `<root>/worktrees` (the task worktrees) is skipped. It is the one sanctioned update of a canonical
-checkout, made on a workstation. Edits still happen in a task worktree (the `klok-worktree` skill). A service never
+checkout, made on a workstation. `pull` and `status` also ask GitLab about each checkout and report one whose project
+moved, was archived or is gone, with the commands that fix it (`remote set-url`, `mv`, `git worktree repair`); they
+move nothing, and those commands are the person's to run. `klok sync clone` does not clone a project that is already
+checked out under its old path. Edits still happen in a task worktree (the `klok-worktree` skill). A service never
 clones a repository just to read it: klok.dev and the agent read through the GitLab API, docs.klok.dev and the
 integration context.
 
 ## Reading
 
 `klok docs list`, then `klok docs read <doc-id>`, is how to read the platform's documentation; the `klok-docs` skill
-has the doc ids that matter most and what a 401, 403 or 404 means. `klok agent ask` asks Kloker, which reads the
+has the doc ids that matter most and what a 401, 403 or 404 means. A doc id that moved with its renamed project is
+followed to the new one, and stderr says `<old-id> moved to <new-id>`: use the new id from then on. `klok agent ask` asks Kloker, which reads the
 solution registry, the integration context and the documentation you may read, and answers with links; it is the
 quickest way to find which project, leg or topic handles something.
 
+## klok.dev
+
+The CLI is meant to do everything klok.dev does, as the person, but only part of the portal has its command yet
+(`klok whoami`, the agent commands, `klok solutions`). When a task needs something klok.dev shows and no klok command
+prints it, such as a broker topic's publishers and subscriptions, an ODL record or a task's events, say so and ask the
+person to look it up in klok.dev or to send it. Do not scrape the portal, and do not reach for credentials the task
+was not given (a service token, a secret read out of Vault) to get around the gap. `klok fleet status --broker` is an
+operator command for the person to run, not a way in.
+
 ## Exit codes
 
 `0` ok, `1` error, `2` a task waits for input, `3` denied by policy, `4` not authenticated, `5` outdated (instructions,

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

@@ -118,7 +118,7 @@ Print one effective configuration value; secrets show as **** unless --reveal
 klok config set [options] <key> [value]
 ```
 
-Set a value. Keys: agentUrl, tenant, klokDevUrl, keycloakIssuer, keycloakClientId, protocol, domain, gitUrl, workspace, klokerBasePath, klokerUrl, klokerModel, summaryLanguage, klokApiKey. Leave out the value of a secret (klokApiKey) to type it at a hidden prompt or pipe it in, so it stays out of the shell history
+Set a value. Keys: agentUrl, tenant, klokDevUrl, keycloakIssuer, keycloakClientId, protocol, domain, gitUrl, workspace, klokerBasePath, klokerUrl, klokerModel, summaryLanguage, klokApiKey. Leave out the value of a secret (klokApiKey) to type it at a prompt that shows * for each character, or pipe it in, so it stays off the screen and out of the shell history
 
 | Argument | Description |
 |---|---|
@@ -661,7 +661,7 @@ Read the platform documentation on docs.klok.dev, and publish this repository’
 klok docs read [options] <doc-id>
 ```
 
-Print the llm.txt of a documentation project on docs.klok.dev, the one markdown file with its whole content, read with your GitLab token. Cached under ~/.cache/klok/docs with the ETag, so a second read is one conditional request; without network the cache is served with a warning. With --json the document carries the content and where it came from; otherwise the content goes to stdout and one status line to stderr.
+Print the llm.txt of a documentation project on docs.klok.dev, the one markdown file with its whole content, read with your GitLab token. Cached under ~/.cache/klok/docs with the ETag, so a second read is one conditional request; without network the cache is served with a warning. A doc id that moved (its project was renamed) is followed once to the new one, said on stderr and cached under the new id; with --json, docId is the id read, requestedDocId the one asked for and movedTo is set. With --json the document carries the content and where it came from; otherwise the content goes to stdout and one status line to stderr.
 
 | Argument | Description |
 |---|---|
@@ -756,7 +756,7 @@ Publish this repository’s klok-docs/ to the documentation chain (projects not
 klok docs publish [options]
 ```
 
-Build the znai project and upload it under this project’s doc id
+Build the znai project and upload it under this project’s doc id. When klok-documented-project.json at the repository root says state "retired", unpublish its docId and every previousDocIds entry instead (DELETE with the upload token; 404 counts as done) and upload nothing.
 
 | Option | Description |
 |---|---|
@@ -764,7 +764,7 @@ Build the znai project and upload it under this project’s doc id
 | `--doc-id <id>` | Publish under this doc id instead of the derived one |
 | `--repo-path <path>` | Repository path to derive from (default: CI_PROJECT_PATH or the git remote) |
 | `--znai <path>` | The znai executable (default: znai on PATH) |
-| `-n, --dry-run` | Resolve what would be published and build it with znai, upload nothing |
+| `-n, --dry-run` | Resolve what would be published and build it with znai, upload nothing; for a retired project, say what would be unpublished |
 | `--no-build` | With --dry-run: only resolve the plan, do not run znai |
 
 ## klok fleet
@@ -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
@@ -1017,11 +1024,86 @@ The integration solution registry (<tenant>/integration-solutions)
 klok solutions validate [options]
 ```
 
-Check every solutions/<SOLUTIONID>_<slug>/solution.meta.json against the descriptor contract
+Check every solutions/<SOLUTIONID>_<slug>/solution.meta.json against the descriptor contract and, against a base, that no solution is removed, no number reused, no retired solution revived and no id taken by an earlier merge request
 
 | Option | Description |
 |---|---|
 | `--root <dir>` | Checkout of the registry (default: the current directory) |
+| `--base <ref>` | Compare the change with this commit (default: the diff base of a merge request pipeline; none elsewhere) |
+| `--token <token>` | GitLab token that lists the registry's open merge requests (default: KLOK_GIT_APIKEY, then config klokApiKey, then the CI job token) |
+| `--offline` | Do not ask GitLab for the open merge requests (skips solution-id-claimed) |
+
+```
+In a merge request pipeline the base is CI_MERGE_REQUEST_DIFF_BASE_SHA and the job needs the whole history
+(GIT_DEPTH: "0"). On a branch or main pipeline there is no base, so removing a solution is possible there: that is
+how a platform admin removes one, on main. A number stays spent either way.
+
+Examples:
+  klok solutions validate                                  # in a checkout of the registry
+  klok solutions validate --base origin/main               # a change on a branch, before pushing it
+```
+
+### klok solutions next
+
+```
+klok solutions next [options]
+```
+
+The next free solution id of the tenant: one more than the highest number in the registry, its history, its branches and open merge requests, and the route classes on every branch of the tenant's repositories
+
+| Option | Description |
+|---|---|
+| `--root <dir>` | Checkout of the registry (default: <workspace>/<tenant>/integration-solutions) |
+| `--workspace <dir>` | Workspace root that `klok sync` mirrors into (default: the configured workspace) |
+| `--tenant-short <short>` | The tenant's short name, three upper case letters (default: the one the registry's solution ids share) |
+| `--token <token>` | GitLab token that reads the registry's open merge requests (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--offline` | Neither fetch the registry nor ask GitLab for its open merge requests |
+
+```
+Fetches the registry first (git fetch --prune origin). The repositories are read as last fetched; when one was
+fetched more than a day ago it says so, and `klok sync pull` refreshes them. Numbers 900-999 are the framework's and
+a gap is never filled. Nothing is written: reserve the id with `klok solutions new`.
+
+Examples:
+  klok solutions next
+  klok solutions next --root . --json        # in a checkout or worktree of the registry
+```
+
+### klok solutions new
+
+```
+klok solutions new [options] <name>
+```
+
+Reserve the next solution id: a task worktree of the registry, a folder with a reserved descriptor and a stub document, one commit, and a push that opens the merge request, which is the allocation
+
+| Argument | Description |
+|---|---|
+| `<name>` | required |
+
+| Option | Description |
+|---|---|
+| `--root <dir>` | Checkout of the registry (default: <workspace>/<tenant>/integration-solutions) |
+| `--workspace <dir>` | Workspace root that `klok sync` mirrors into (default: the configured workspace) |
+| `--tenant-short <short>` | The tenant's short name, three upper case letters (default: the one the registry's solution ids share) |
+| `--token <token>` | GitLab token that reads the registry's open merge requests (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--offline` | Neither fetch the registry nor ask GitLab for its open merge requests |
+| `--slug <slug>` | kebab-case name of the folder and the url (default: from the name) |
+| `--domain <domain>` | Information domain (Finance, HR, AI, ...) |
+| `--description <text>` | One or two sentences: what the solution keeps in step, in business terms |
+| `--dry-run` | Print the id, the worktree and the files, and create nothing |
+
+```
+The id is the one `klok solutions next` gives, after fetching the registry. The worktree is
+<workspace>/worktrees/<tenant>/integration-solutions/<YYYYMMDD>-solution-<id>-<8 hex> on the branch agent/<task id>,
+based on the registry's default branch; the canonical checkout is not touched. The push uses your own git setup and
+asks GitLab, with push options, to open the merge request against the default branch. The commit is
+docs(<ID>): reserve <ID> for <name>.
+
+Examples:
+  klok solutions new "Payroll export to Personec" --domain HR --dry-run
+  klok solutions new "Payroll export to Personec" --domain HR
+```
 
 ### klok solutions check
 
@@ -1070,10 +1152,11 @@ Discover every repository you can see and clone the missing ones
 klok sync pull [options]
 ```
 
-Fast-forward every repository in the workspace
+Fast-forward every repository in the workspace, and report checkouts whose GitLab project moved, was archived or is gone
 
 | Option | Description |
 |---|---|
+| `--no-remote-check` | Do not ask GitLab whether the checkouts’ projects moved, were archived or are gone |
 | `-w, --workspace <path>` | Workspace directory (default: config workspace) |
 | `--token <token>` | GitLab token (default: KLOK_GIT_APIKEY, then config klokApiKey) |
 | `-j, --jobs <n>` | Parallel git operations (default: `6`) |
@@ -1086,7 +1169,7 @@ Fast-forward every repository in the workspace
 klok sync status [options]
 ```
 
-Show dirty trees, unpushed commits and branches behind their remote (as of the last fetch)
+Show dirty trees, unpushed commits and branches behind their remote (as of the last fetch), and checkouts whose GitLab project moved, was archived or is gone
 
 | Option | Description |
 |---|---|
@@ -1094,3 +1177,5 @@ Show dirty trees, unpushed commits and branches behind their remote (as of the l
 | `-j, --jobs <n>` | Parallel git operations (default: `12`) |
 | `-a, --all` | List every repository, not only the ones needing attention |
 | `--fetch` | Fetch every repository first, so "behind" is current |
+| `--token <token>` | GitLab token for the GitLab check (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+| `--no-remote-check` | Do not ask GitLab whether the checkouts’ projects moved, were archived or are gone |