@klok-integration/cli 0.6.235 → 0.7.248

package/README.md

@@ -48,6 +48,7 @@ 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. |

package/assets/agents/AGENTS.integration.md

@@ -12,6 +12,8 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
 ./gradlew updateKlokLibsToml         # refresh gradle/klok-libs.versions.toml from the dependency catalog
 ./gradlew quarkusDev                 # run locally against the configured broker
 ./gradlew initDocsGeneration         # route facts to build/klokRoutes/docs.json
+./gradlew klokTopics                 # the broker topics the service needs, to build/klok-topics/topics.json
+./gradlew klokTopicCheck --report    # asks klok.dev whether each topic exists and is granted (KLOK_INTEGRATION_CONTEXT_TOKEN)
 ```
 
 ### Rules
@@ -25,6 +27,10 @@ needs. Read `klok docs read klok-framework-klok-quarkus-extension` before writin
   matches it, and both projects' `klok-docs/` write it down. A topic has at most one purpose; a reader is its
   subscription (its route id), never a suffix. Never consume a shared topic and discard the other flows' messages.
   The `klok-route` skill has the details.
+* The broker creates no topics. After adding or changing a route, a purpose or an override, run
+  `./gradlew klokTopics`, resolve its warnings, and make sure every topic it lists exists: request a missing one (or
+  a grant) in klok.dev, or add it to the tenant's Pulsar file in a merge request, and list it as a manual step. The
+  service fails at startup with `TOPIC_MISSING` or `TOPIC_ACCESS_DENIED` and the fix when one is missing.
 * Errors: throw `Klok4XXException` for caller errors (no retry) and `Klok5XXException` or plain exceptions for
   retryable failures; the framework retries, republishes to `_DLQ` and emits the failure event. Do not add
   `onException` blocks unless the route owns the failure (`failureHandled()`).

package/assets/agents/AGENTS.workspace.md

@@ -12,11 +12,18 @@ 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 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 +53,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 +131,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
@@ -338,9 +346,17 @@ access, Keycloak broker clients or a service that serves several tenants.
 * **Who applies it:** Ansible (`klok/environment/klok-environment-setup`, `keycloak.yml` and `pulsar.yml`) applies
   what those files declare: today the platform and tenant klok's services, plus any entries a person adds there for
   another tenant's service (a playbook per tenant: klok/environment/klok-environment-setup#35). Broker access (a
-  tenant, a namespace, a topic created in advance, a grant) changes only through a merge request to those Pulsar
-  files, applied by Ansible run by a person. klok.dev provisions no broker clients or grants yet
-  (klok/application/frontend-klok-dev#51). A grant made only in the broker's admin API is drift.
+  tenant, a namespace, a topic, a grant) changes only through a merge request to those Pulsar files. klok.dev merges
+  what needs no approval (the generic topic of every datamodel) and what an owner approved in klok.dev, and applies
+  topics and grants from the files; Ansible, run by a person, applies the same files and alone creates namespaces and
+  revokes grants. klok.dev provisions no broker clients yet (klok/application/frontend-klok-dev#51). A topic or grant
+  made only in the broker's admin API is drift.
+* **Topics are provisioned, never created by the broker.** A topic exists when its tenant's Pulsar file lists it and
+  the file is applied; its `_DLQ`, and the `_Response` of a `_Request` topic, come with it. `./gradlew klokTopics`
+  lists what a project needs, and a missing topic or grant fails the deploy (`klokTopicCheck`) and the service's start
+  with `TOPIC_MISSING` or `TOPIC_ACCESS_DENIED` and the fix. Follow the message: request the topic or access in
+  klok.dev, or add the line it names in a merge request, and hand that to a person. Never ask for automatic topic
+  creation and never create a topic through the broker's admin API.
 
 ## Documentation is part of every change
 

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

@@ -93,6 +93,25 @@ documentation or the dependency catalog can give you.
   for reading across tenants.
 * Request/reply: `ReqRes_<Request>_<Reply>[_<purpose>]_Request` and `_Response`. Dead letters: `<topic>_DLQ`.
 * One datamodel per topic. A breaking change is a new major version and therefore a new topic.
+* Topics are provisioned from Git; the broker never creates one by itself. A topic exists when its owning tenant's
+  Pulsar file in `klok/environment/klok-environment-setup`
+  (`ansible-master/playbooks/group_vars/all/pulsar_tenant_<tenant>.yml`) lists it and the file has been applied. A
+  producer or consumer on any other topic is refused. Subscriptions are still created by their consumer.
+* Companions come with every topic and are never requested or listed on their own: `<topic>_DLQ` for every topic, and
+  for a `_Request` topic its `_Response` (with that topic's `_DLQ`).
+* klok.dev declares the generic topic `<Model>` of every datamodel, and the ODL's change event topics. Every other
+  topic (a purpose, a request/reply pair) and every grant is requested in klok.dev and approved by the owner (a
+  TenantAdmin of the tenant or a DomainAdmin of the namespace), or added to the Pulsar file in a merge request.
+* `./gradlew klokTopics` lists the topics a project needs (`build/klok-topics/topics.json`, with a warning for every
+  topic the scan cannot resolve) and `./gradlew klokTopicCheck` asks klok.dev whether each exists and is granted to
+  the service; in CI it blocks the deploy. A service checks the same at startup and does not start without them.
+* A missing topic or grant is `TOPIC_MISSING` or `TOPIC_ACCESS_DENIED`, never retried. The message names the topic,
+  the role, the operation, who approves, the klok.dev request link (`https://klok.dev/monitoring/broker/request?...`)
+  and the line to add by hand. Follow it: hand the request link or the merge request to a person. Never create a topic
+  or a grant through the broker's admin API, never ask for automatic topic creation, and never turn the startup check
+  (`klok.broker.verify-topics`) off in a deployed service.
+* A route that consumes another tenant's topic cannot write its `_DLQ`; where such dead letters go is open
+  (klok/framework/klok-common#11).
 * Every broker message is a CloudEvent in binary content mode: the attributes are message properties, the payload
   is the typed datamodel. `ce-source` is `urn:klok:<tenant>:<solutionId>:<routeId>`; `ce-type` says what happened
   (default `dev.klok.<tenant>.<domain>.<Model>.published`).
@@ -135,9 +154,10 @@ whether a model may travel on a topic; it decides how widely the model is shared
   (`persistent://<tenant>[_<env>]/common/<Model>`), the service is granted `consume` on exactly those topics, and
   what the platform writes back lives in klok's namespace, one topic per tenant
   (`persistent://klok[_<env>]/<domain>/<Model>_<tenant>`).
-* Broker access (a tenant, a namespace, a topic created in advance, a grant) changes only through a merge request to
-  the Pulsar variables in `klok/environment/klok-environment-setup`, applied by Ansible run by a person. A grant made
-  only in the broker's admin API is drift.
+* Broker access (a tenant, a namespace, a topic, a grant) changes only in Git, in the owning tenant's Pulsar file in
+  `klok/environment/klok-environment-setup`. klok.dev applies topics and grants from the file (merging what needs no
+  approval and what an owner approved); Ansible, run by a person, applies the same files and alone creates namespaces
+  and revokes. A topic or grant made only in the broker's admin API is drift.
 * One Keycloak client per running deployment, never shared and never used by a person. Broker rights are called
   `publish` and `consume`; *ingress* and *egress* say what a service is and are never permissions.
 

package/assets/agents/knowledge/retired-patterns.txt

@@ -27,6 +27,13 @@ topic-dlq # dead letters are <topic>_DLQ
 (?i)last purpose segment # a topic has one optional purpose set by the publisher; a reader is its subscription (route id)
 (?i)_<reader> # a topic has one optional purpose set by the publisher; a reader is its subscription (route id)
 (?i)\breader (as|after) the (last )?purpose # a topic has one optional purpose set by the publisher; a reader is its subscription
+# Topics are provisioned from Git and never created by the broker (2026-10-08): a topic exists when its tenant's
+# Pulsar file lists it and the file is applied; its _DLQ and a _Request topic's _Response come with it.
+(?i)\btopics? (is|are) (auto-?)?created (automatically )?(by|on|with|at) (the |its )?first (producer|publisher|consumer|publish|send|use|message) # topics are provisioned from Git, never created on first use
+(?i)created automatically by (the|its) first (producer|publisher|consumer) # topics are provisioned from Git, never created on first use
+(?i)\btopics? (appears?|comes? into existence) (with|on|at) (the |its )?first (producer|publisher|consumer|publish|use|message) # topics are provisioned from Git, never created on first use
+(?i)\ba topic created in advance # every topic is listed in its tenant's Pulsar file before it is used; "in advance" is the only way
+(?i)\b(enable|turn on|switch on) (automatic|auto-?)[ -]?topic[ -]creation # the Klok broker runs with allowAutoTopicCreation=false; request the topic in klok.dev
 #
 # Framework classes that do not exist in the Quarkus extension 2.0 and later.
 KlokSoapApi # removed in 2.0; SOAP is a KlokCustomRoute with camel-cxf

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

@@ -206,6 +206,14 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
    authentication: alert and dead letter), the tests.
 5. **Code and review.** Check the transform, the dead letter path, the CloudEvent attributes, logging through the
    framework (never `System.out`), and the service's broker client and grants.
+6. **Topics.** The broker never creates a topic. A datamodel's generic topic `<Model>` and every companion (`_DLQ`,
+   the `_Response` of a `_Request`) come by themselves; a purpose topic, a request/reply pair and every grant outside
+   the service's own namespaces are requested. Run `./gradlew klokTopics`, then have each missing topic or grant
+   requested in klok.dev (`/monitoring/broker/request`) or proposed as a merge request to the tenant's Pulsar file,
+   approved by the namespace's Domain Admin or the Tenant Admin. When `klokTopicCheck`, the pipeline's
+   `klok_topic_check` or the startup report names a `TOPIC_MISSING` or `TOPIC_ACCESS_DENIED`, follow the message:
+   it holds the request link, the approver and the line to add. Never suggest automatic topic creation. The whole
+   way is the user guide page *Topics On The Klok Broker* (`klok docs read klok-user-guide`).
 
 ## Documentation, tests and delivery
 

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

@@ -0,0 +1,57 @@
+---
+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 | `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 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. 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
+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.
+
+## 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.