@klok-integration/cli 0.7.248 → 0.7.269

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,23 @@ 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.
+* `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

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

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
@@ -1017,11 +1017,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 +1145,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 +1162,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 +1170,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 |

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

@@ -34,27 +34,34 @@ 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
@@ -72,7 +79,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-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.