@klok-integration/cli 0.6.245 → 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.
@@ -48,11 +48,14 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agents update [--check] [--global]` | Fetch what moved in the platform and tenant catalogs; `--check` writes nothing and exits 5 when something is outdated. |
 | `klok agents status` | Per file and per catalog: current, outdated, missing or unreachable. |
 | `klok bead list\|show\|report` | Progress beads in the current repository. |
+| `klok docs list` | The documentation projects on docs.klok.dev you may read, by doc id. |
 | `klok docs read <doc-id>` | Print a documentation project's `llm.txt` from docs.klok.dev, read with your GitLab token and cached. |
 | `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

@@ -12,11 +12,19 @@ Before anything else, run `klok agents update --check`. Exit 5 means the install
 run `klok agents update` and read the refreshed files. Exit 0 means they are current, and any other code names
 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 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.
+
 The platform documentation is published at https://docs.klok.dev, one documentation project per repository, each
 exposing its whole content as one markdown file. Read it with klok-cli, which sends your GitLab token and caches
-the answer:
+the answer. `klok docs list` comes first when you do not know the doc id:
 
 ```
+klok docs list                     # the documentation projects you may read, by doc id
 klok docs read <doc-id>            # the markdown on stdout, one status line on stderr; --json adds fetchedAt
 klok docs id [tenant/group/.../repo]   # the doc id of a repository, this one by default
 ```
@@ -46,7 +54,7 @@ The `klok-docs` skill describes the lookup in detail. Cite the doc id you relied
 
 ## Tenant skills
 
-Next to the platform skills (`klok-docs`, `klok-solution`, `klok-route`, `klok-datamodel`, `klok-release`,
+Next to the platform skills (`klok-docs`, `klok-cli`, `klok-solution`, `klok-route`, `klok-datamodel`, `klok-release`,
 `klok-worktree`) the skill directories hold your tenant's own skills, generated by KlokDocumentationEgress from the
 tenant's documentation publishes and served from the tenant's private catalog. The egress reads only tenant klok's
 publishes today, so another tenant has no tenant skills yet:
@@ -124,8 +132,9 @@ step by step procedure; the contract every agent follows is:
   exists, use a new id; never delete, reset or force reuse it.
 * Leave the canonical checkout's branch, files and uncommitted changes exactly as found. Never run `checkout`,
   `switch`, `pull`, `reset`, `clean`, `stash`, rebase or merge in the canonical checkout or in another session's
-  worktree. Dirty canonical files are not a blocker: a worktree starts from committed history and does not copy
-  uncommitted or ignored files; if the task needs them, ask for an explicit handoff.
+  worktree. The one exception is `klok sync pull`, which only fast-forwards a canonical checkout and reports one it
+  cannot fast-forward. Dirty canonical files are not a blocker: a worktree starts from committed history and does
+  not copy uncommitted or ignored files; if the task needs them, ask for an explicit handoff.
 * Do every edit, build and test in the task worktree, with explicit working directories or `git -C`. Recreate
   dependencies there; do not copy or symlink `.env`, credentials, `node_modules` or build output from another
   checkout. A worktree is not a sandbox: use isolated ports, containers and output directories where parallel
@@ -292,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
@@ -319,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.
@@ -384,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

@@ -0,0 +1,71 @@
+---
+name: klok-cli
+description: Which klok command does what on the Klok platform (klok-cli, `@klok/cli`), with the full reference of every command and option in reference.md. Use before running a klok command you have not run in this task, when a task needs the local workspace current (`klok sync pull`), a list of the documentation (`klok docs list`), an answer about the integration landscape (`klok agent ask`), or a check of the solution registry, the deployed fleet, the catalog, a CI job, a deploy manifest, a pin, a bead or a datamodel.
+---
+
+# The klok command line
+
+`klok` is the Klok platform's command line tool. It reads with your GitLab token (`KLOK_GIT_APIKEY`, or `--token`)
+and your Keycloak login (`klok login`), and every command takes `--json` for one machine-readable document on stdout.
+This page says which command to reach for. `reference.md` next to it lists every command, option and example of this
+CLI version, generated from the program itself; when it is missing (an installer that copies `SKILL.md` only), run
+`klok --help` and `klok <command> --help`.
+
+## When to use what
+
+| You need | Run |
+|---|---|
+| 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, 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) |
+| what a CI job is, whether a change is documentation only, where CI time goes | `klok ci env`, `klok ci docs-only`, `klok ci timings` |
+| a pipeline's image in its deploy manifest | `klok manifest update --dry-run` (CI runs it without) |
+| a release pinned in an infrastructure repository | `klok pin update ... --dry-run` |
+| the beads of the current repository | `klok bead list`, `klok bead show <id>`, `klok bead report <id>` |
+| the repository, root element and namespace a datamodel's class and name give | `klok datamodel names` |
+| an XSD checked the way the datamodel pipeline checks it | `klok datamodel validate` |
+| this repository's `klok-docs/` checked before the merge request | `klok docs build`, `klok docs verify` |
+
+## The workspace
+
+`klok sync pull` brings the workspace current before you read it: every repository under the workspace root (config
+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. `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. 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,
+or a deployed service). With `--json`, the document says what happened; messages go to stderr.