@klok-integration/cli 0.5.0 → 0.6.205

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

@@ -166,7 +166,12 @@ custom route for a plain mapping, a plain protocol bridge or an API.
 
 `KlokSubRoute` splits a route into reusable parts through `configureSubroute(ProcessorDefinition<?>)`; its URI is
 `direct:<fully qualified class name>`. A sub route that only transforms and is called from several onramps is
-right; a sub route that opens an SFTP connection is in the wrong place.
+right; a sub route that opens an SFTP connection is in the wrong place. A sub route has no error handling of its
+own (klok-quarkus-extension 3.4 and later): every exception it throws reaches the route that called it, and that
+route's retries, dead letter queue and reply decide what happens to the message. In a sub route, catch only what is
+not an error (a lookup that finds nothing when "absent" is a valid answer) and handle it, or catch an error to throw
+it again as a more specific `Klok4XXException` / `Klok5XXException` or with a better message. Never give a sub route
+its own `retry.*`, `dlq.*` or `failure.*` keys; configure its caller.
 
 ## Channel adapters and APIs
 
@@ -194,7 +199,8 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
 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,
-   `[TACTICAL]` for any deviation.
+   `[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),
    the `transformBody` sketch, the CloudEvent type, the failure matrix (timeout: retry; invalid: dead letter;
    authentication: alert and dead letter), the tests.
@@ -215,6 +221,9 @@ blindly. `klok-mock-*` headers are for test and staging and are stripped in prod
   routes start and what they publish; never a real broker or OpenSearch in unit tests.
 * Delivery: the `main` pipeline builds the image, updates the deployment manifest that Argo CD applies, and
   publishes the documentation. Never commit hand-made production YAML beside it.
+* Commit messages and merge request titles follow Conventional Commits (`feat(odl): …`, `fix: …`, `docs: …`). The
+  pipeline acts on the type: a `docs` merge request only publishes the documentation, so it is `docs` only when
+  nothing but `klok-docs/` and root Markdown files changed.
 * Troubleshooting: follow `klok-correlation-id` from ingress through processing to egress; operations follow the
   failure events and the dead letter topics, not pod logs.
 

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

@@ -34,9 +34,11 @@ 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 through klok.dev, or through the agent at https://agent.klok.dev** authenticated as the tenant
-   with the right to create projects in the domain. That is the supported path: it creates the repository from
-   `project-template-datamodel`, renders the placeholders, and provisions what the project needs to build.
+   **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).
 
    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
@@ -62,6 +64,10 @@ domains read should still travel as class B or C (transform at the edge).
    publishes `dev.klok.<tenant>.datamodel:<name>-v<n>:1.0.0-build.<ts>` with its Python and TypeScript packages,
    writes `<nameVn>` (for example `klokOdlV1`) into the dependency catalog, and publishes the documentation payload
    that becomes `<tenant>/documentation/datamodel/<same path>` on docs.klok.dev.
+6. A merged datamodel is not yet a released one. A consumer's `updateKlokLibsToml` waits until the catalog's `main`
+   has the commit `chore(catalog): update <name> to the version published by <datamodel repository>@<merge sha>`
+   (`Update <name> …` before 2026-10-01). Say so, with the
+   command, in the guide that hands the merges over (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
 
 ## Using a model in a project
 

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

@@ -31,16 +31,17 @@ drops the `klok-` prefix of the name (`klok-integration-strategy-and-tactics`).
 
 | Need | Doc id |
 |---|---|
-| Principles, event driven design with sync compatible interfaces, naming cheat sheet, framework map, onboarding | `klok-integration-strategy-and-tactics` |
+| Principles, event driven design with sync compatible interfaces, naming cheat sheet, framework map | `klok-integration-strategy-and-tactics` |
 | Route patterns, capabilities, configuration, logging and correlation, error handling, topics and CloudEvents, async tasks, ODL client, testing, migration from 1.x | `klok-framework-klok-quarkus-extension` |
 | Naming conventions, `klok-*` properties, CloudEvents attributes | `klok-framework-klok-common` |
 | Broker client configuration, subscriptions, request/reply | `klok-framework-klok-brokerclient-java` |
 | Gradle plugin, versions, catalog refresh | `klok-framework-klok-gradle-plugin` |
 | CI templates, release process, Vault roles, documentation chain, catalog update | `klok-environment-build-ci-templates` |
-| Developer rules, prompt catalogue, broker access, identity | `klok-framework-development-guide` |
+| Developer rules, prompt catalogue, broker access, identity, onboarding a tenant | `klok-framework-development-guide` |
 | Concepts, roles, workflow and operations for people | `klok-user-guide` |
-| ODL REST and request/reply, tasks API | `klok-integration-klok-api-opensearch` |
-| ODL writers, log receivers | `klok-integration-klok-egress-opensearch` |
+| ODL REST facade | `klok-integration-klok-api-odl` |
+| Tasks API | `klok-integration-klok-api-tasks` |
+| ODL services (writes, request/reply, change events), log receivers, task materializer | `klok-integration-klok-egress-opensearch` |
 | Scheduled queries, stale task detection | `klok-integration-klok-ingress-opensearch` |
 | OpenAI compatible API, AI tasks, Kloker gateway | `klok-integration-klok-api-ai` |
 | AI workers, transcription, transcript cache | `klok-integration-klok-egress-ai` |
@@ -65,7 +66,8 @@ question is about what a project does.
    skills you read are the catalogs' current ones.
 2. Identify the repositories involved and derive their doc ids (`klok docs id <path>`).
 3. `klok docs read <doc-id>` for each. Handle 404, 401 and 403 as the table says.
-4. Read the strategy documentation first when the task touches design, naming or onboarding; read the framework
-   documentation before writing or changing a route.
+4. Read the strategy documentation first when the task touches design or naming, and the *Onboarding a tenant*
+   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.

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

@@ -21,42 +21,48 @@ roles and secrets, catalog update) before acting.
    `glab api --hostname git.klok.dev "projects/<id>/pipelines?per_page=3"`, then
    `projects/<id>/pipelines/<pid>/jobs` and `projects/<id>/jobs/<jid>/trace`. Fix a red pipeline before the next task.
 4. Framework changes across libraries are released in order: klok-common, broker client, extension. Wait for the
-   catalog update of one before merging the next.
+   catalog update of one before merging the next: the catalog's commit for that release, not the merge, which only
+   starts the pipeline that produces it:
+   `glab api --hostname git.klok.dev "projects/klok%2Fframework%2Fklok-gradle-dependency-catalog/repository/commits?ref_name=main&per_page=10" | jq -r '.[].title'`.
 5. **Never cancel, stop or restart a running job, pipeline or deployment without a human's explicit yes.** A
-   release waiting on Maven Central or npm can take half an hour, and the `main` lane runs one job at a time, so a
-   long queue is normal. Check the current time with `date -u` before judging how long anything has run. Report the
+   release waiting on Maven Central or npm can take half an hour, and `main` pipelines queue behind each other or run
+   in parallel, so a long wait is normal. Check the current time with `date -u` before judging how long anything has run. Report the
    job id, its run time, the last log lines with timestamps and what waits behind it, propose what to do, and wait.
+6. Merging is the human's step. Hand it over as KLOK-AGENTS.md *Manual steps are handed over as a guide* says:
+   every merge request with its link, whether the order matters and why, and for each later step the release
+   result to wait for and the command that shows it.
 
 ## Creating a new project
 
-**Create projects through klok.dev, or through the agent at https://agent.klok.dev** authenticated as the
-tenant and holding the right to create projects in the domain. That is the supported path, and it is meant to
-provision everything the project needs so the **first** pipeline is green with no manual step.
+**Create projects through klok.dev**; the agent at https://agent.klok.dev asks klok.dev to do it. Creating a
+project by hand — `glab api POST /projects`, or cloning the template and swapping the remote — is a legitimate
+fallback under *Git är sanningen*.
 
-Creating a project by hand — `glab api POST /projects`, or cloning the template and swapping the remote — is a
-legitimate fallback under *Git är sanningen*, but it is not the normal path and it leaves work behind that the
-portal would have done: a pipeline schedule, and for a deployed service the manifest and its Vault objects (see
-below). When taking the manual route, name the remaining human steps up front instead of letting them surface as
-a red pipeline. Vault CI login is not one of them: it needs nothing per project.
+Neither path provisions a pipeline schedule yet, nor for a deployed service the manifest, its Vault objects, its
+Keycloak client and its broker grants (see below; tracked in klok/application/frontend-klok-dev#41 and #42). Name
+those human steps up front instead of letting them surface
+as a red pipeline. Vault CI login is not one of them: it needs nothing per project.
 
 ## Setting up a new project (what must exist)
 
 * Nothing in Vault per project. Every job logs in with the tenant CI role `<tenant>-ci` (a Vault JWT role bound
   to `namespace_path` `<tenant>` and `<tenant>/*`, carrying `default` and the tenant CI read policy
   `<tenant>-cicd-read`). The templates set `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. A tenant without the role fails
-  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is in
-  `klok-docs/ci/tenant-onboarding.md` of `klok/environment/build-ci-templates`, every credential and the step
-  that uses it in `klok-docs/ci/authentication.md` there.
+  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is the
+  *Onboarding a tenant* runbook in `klok docs read klok-framework-development-guide`, every credential and the step
+  that uses it in `klok-docs/ci/authentication.md` of `klok/environment/build-ci-templates`.
 * For anything the pipeline resolves from a package registry (framework, plugin, datamodels): the project's
   top-level group must be on the package project's job token allowlist.
-* For a deployed service: a manifest under `klok/integration/<name>/`, the Kubernetes service account, a Vault
-  Kubernetes role `<name>-role` with a policy reading `secret/data/<tenant>/integration/<name>/env`, and the env
-  secret itself (broker credentials, service specific keys).
+* For a deployed service: a manifest `<project path>/<name>-crds.yaml` in the manifests repository, written by
+  hand before the first deploy, with the Kubernetes service account; a Vault Kubernetes role `<name>-role` (with
+  `audience=https://kubernetes.default.svc`) and its policy `<name>-policy` reading
+  `secret/data/<tenant>/integration/<name>/env`; the env secret itself (broker credentials, service specific
+  keys); and the service's own Keycloak client with its broker grants.
 * Documentation projects need the tenant's docs upload client: Keycloak client `klok-docs-upload-<tenant>` and its
   id and secret in `secret/<tenant>/common/repo/cicd-environment-variables`.
 
-Vault is changed by humans only: propose the exact `vault write` / `vault policy write` command with every existing
-field, and let the user run it.
+Agents never write to Vault: propose the exact `vault write` / `vault policy write` command with every existing
+field, and let a person run it.
 
 ## Common failures and their meaning
 

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

@@ -6,7 +6,10 @@ description: Write or change a Camel route on the Klok Quarkus extension 2.0 (on
 # Writing a Klok route
 
 Read `klok docs read klok-framework-klok-quarkus-extension` first (pages `patterns`, `naming`,
-`config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages.
+`config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages. A route is a leg of a solution:
+the `klok-solution` skill finds and updates its solution document, before and after the change. Integration logic is
+a Java route; doing it with the Python or TypeScript broker clients is a `[TACTICAL]` choice the solution document
+motivates.
 
 ## Steps
 
@@ -24,6 +27,9 @@ Read `klok docs read klok-framework-klok-quarkus-extension` first (pages `patter
 6. **Errors.** Throw `Klok4XXException` for caller errors, let retryable failures propagate; the base route logs,
    retries with backoff, republishes to `<topic>_DLQ` and emits the failure CloudEvent. Override `failureHandled()`
    only when the route owns its failures (custom routes that answer HTTP themselves).
+   A sub route has no error handling of its own: it catches only what is not an error, may throw an error again
+   as a more specific Klok exception, and leaves retries, the dead letter queue and the reply to its caller, whose
+   keys you configure (`klok docs read klok-framework-klok-quarkus-extension`, *Error handling*, *Sub routes*).
 7. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
    `KlokEmitCloudEventOnSuccess/Failure`, `PersistOutgoingMessages`, `KlokAsyncTaskInitiator`.
 8. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
@@ -34,16 +40,18 @@ Read `klok docs read klok-framework-klok-quarkus-extension` first (pages `patter
    or standards several routes read, shared mappers, domain logic used by several routes. Each gets its own generated
    page; write its Javadoc for a reader who has not seen the code. Not every class: the classes a route calls
    directly reach its generated documentation without the annotation.
-10. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
+10. Update the solution document when the route is new or its contract changed (`klok-solution` skill).
+11. Build (`./gradlew build`) in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch,
     open a merge request ready for review, check the pipeline.
 
 ## Topic purpose
 
 A topic is named after its datamodel: `<Model>[_<purpose>]`. The purpose (called *producer intention* in older code)
-is a suffix that the producer and the consumer agree on and each set on their own route, so one datamodel serves
-several flows: `CallAiResponseV1_documentation` and `CallAiResponseV1_invoicecoding` both carry the typed
-`CallAiResponseV1`, and each consumer receives only its own flow. The framework builds the full topic name on both
-sides from the model and the purpose.
+is an optional suffix that belongs to the publisher: the solution requires it, the producer sets it, and the consumer
+sets the same purpose on its own route, so one general datamodel serves several flows:
+`CallAiResponseV1_documentation` and `CallAiResponseV1_invoicecoding` both carry the typed `CallAiResponseV1`, and
+each consumer receives only its own flow. The framework builds the full topic name on both sides from the model and
+the purpose.
 
 * **When.** Give a flow a purpose when its datamodel is, or may be, used by another flow. Without one, every consumer
   of the model receives every message. No purpose only when every consumer wants every message.
@@ -63,8 +71,12 @@ sides from the model and the purpose.
   Put it in code when the purpose is part of what the route is; put it in configuration when the same route serves
   several flows. Set `<SolutionId>.topic.purpose` only when every route of the solution is on that flow.
 * **Name** the flow as both sides understand it (`created`, `reminder`, `documentation`): letters, digits, `-` and
-  `.`, never `_`, and no version, tenant or environment. Task types are `<domain>.<verb>-<object>`. A topic read by
-  another tenant appends the reader after the purpose: `<Model>_<purpose>_<reader>`.
+  `.`, 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
+  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.
 * **A mismatch fails silently**: the two routes end up on different topics and nothing arrives. Check the start log
   (`Route <RouteId> subscribes to <topic>`, `Route <RouteId> publishes <Model> to <topic>`) and assert the full topic
   in the test.
@@ -83,8 +95,8 @@ explains the reasons and the naming in full.
 * Publishing to a hand written topic string; use the resolver and the datamodel.
 * Consuming a shared topic and discarding the messages of other flows (a filter on a payload field, an ODL lookup
   per message) where the producer could publish the flow with a topic purpose.
-* A purpose with `_`, a version, a tenant or an environment in it, or a purpose guessed instead of agreed with the
-  other side.
+* A purpose with `_`, a version or an environment in it, a second suffix after the purpose, a tenant in it that the
+  publisher did not choose, or a purpose guessed instead of agreed with the other side.
 * Choosing a tenant, index, repository or account from a field in the message; the topic decides the tenant.
 * Sharing broker credentials between services, or granting a whole namespace of another domain or tenant.
 * Publishing into another tenant's namespace, with `<RouteId>.topic.tenant-override` or otherwise; a route consumes

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

@@ -0,0 +1,88 @@
+---
+name: klok-solution
+description: Design, build or maintain a Klok integration solution and keep its solution document true to what is built. Use whenever a task asks to design or develop a service, integration, API or route, to change, fix or extend an existing one, or to explain how a flow is built — before the first route of a new solution and on every change of a leg.
+---
+
+# Designing and maintaining a solution
+
+New development and maintenance follow one process. A **solution** is the business level unit that a set of
+integration legs belongs to; its **solution document** (`README.md` in the tenant's `integration-solutions`
+registry) says what the legs are, how they interact and why. The document is written before the code of a new
+solution and is brought to the new steady state by every change of a leg, so that the registry describes the
+integration landscape as it is built and deployed, not as it was once planned.
+
+Read first: the registry's own `README.md` on `main` (the section list of a solution document, the classification
+of services, the descriptor contract), `klok docs read klok-integration-strategy-and-tactics` (*From solution
+documents to design documents*, *Event driven with sync compatible interfaces*) and
+`klok docs read klok-framework-klok-quarkus-extension`. Reference examples:
+`solutions/KLK010_personnel_scheduling_services/` (two systems) and `solutions/KLK008_ai_image_generation/` (a
+shared platform service) in `klok/integration-solutions`.
+
+## Steps
+
+1. **Find the solution.** The route id prefix is the solution id (`KLK010I1_…` belongs to `KLK010`); a project
+   names its solution in `klok-system-project.json` (`solutionId`). The document is
+   `<tenant>/integration-solutions/solutions/<SOLUTIONID>_<slug>/README.md` on `main` (fetch first). The tenant's
+   `<tenant>-context` skill lists solutions, routes and topics (`data/solutions.jsonl`, `data/routes.jsonl`).
+2. **Check that the document is still true** before relying on it: `klok solutions check --root <registry>`
+   compares every solution document with the route classes on the default branch of every repository of the tenant
+   in the workspace (`klok sync` first). Findings are drift to fix in this task or to file as an
+   issue, never to ignore.
+3. **Read the design.** The solution document and any design page next to it, then each project's `klok-docs/`
+   (`klok docs read <doc-id>`, `klok docs id <repo path>` gives the id).
+4. **A new solution gets an id and a document before code.** Take the id from the code, not the next free
+   number: grep the integration repositories, pushed branches included, and run `klok solutions validate`. Write
+   `README.md`, `solution.meta.json` (`generatedBy: "manual"`) and, when the details do not fit, a design page next
+   to it, in a worktree of the registry. The sections are listed in the registry README.
+5. **Reuse before building.** Look for an existing solution or platform capability first: tasks and the task API
+   (KLK002), the ODL, the AI services (KLK003), mail (KLK006), the claim check, datamodels in the catalog. A
+   capability that needs a change to serve the solution is *reused, slight change*, with its own merge request in
+   the owning project.
+6. **Classify every service** the solution needs: *new project*, *new routes in an existing project*, *reused,
+   slight change*, *reused as is*, *client change*. Name the repository of each.
+7. **Map the legs.** For every route: id (`<TENANTSHORT><NNN><LEG><seq>_<Description>`, leg and sequence not used
+   before — `klok solutions check` reports duplicates), project, pattern base class, topics with their purpose,
+   datamodels and their class, task types, configuration keys, and how the legs interact (diagrams in the flows
+   section). Route configuration and details stay in the project's `klok-docs/`; the solution links there.
+8. **Choose the technology deliberately.**
+   * Integration logic is **Java Klok routes** on the Klok Quarkus extension. They are documented by the platform
+     with their topics, datamodels and configuration, and related integrations group in one project and reuse its
+     services.
+   * Integration logic written with the Python or TypeScript broker clients, or kept inside an application, is a
+     **`[TACTICAL]`** choice: write the motivation, its cost and the condition for removing it in the solution's
+     tactical section.
+   * An external engine (a GPU model server, a vendor service) stays **simple and dumb**: it does one request at a
+     time over REST. Priority, queues, retries, claim checks and task state live in a Java egress. The engine may be
+     written in any language; that is not tactical, logic moved into it would be.
+9. **Order the delivery.** Datamodels and framework changes are released and merged into the dependency catalog
+   before their consumers; steps only a person may take (creating projects in klok.dev, Vault, running Ansible,
+   merging) are numbered hold points in the document's delivery order. The answer that hands them over is a
+   step-by-step guide with the commands, the merge order and the release result each step waits for
+   (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
+10. **Build each leg** with the `klok-route`, `klok-datamodel` and `klok-release` skills, every repository in its own
+    worktree with the same task id (`klok-worktree` skill).
+11. **Keep the document true.** Every merge request that adds, changes or removes a leg updates the solution
+    document in the same change set: the legs table, the flows and the status. A leg that is not on `main` yet
+    carries `planned` in the Status column of its table row; `klok solutions check` relies on it. After the merges,
+    run `klok solutions check` again.
+
+## Maintenance is the same process
+
+* A fix or a change in one route starts at step 1: find its solution and read it before touching the code.
+* A change that alters a leg's contract (a topic, a purpose, a datamodel, an API, a task type, a configuration key
+  another project reads) updates the solution document as well as the project's `klok-docs/`.
+* When the document and the code disagree, the code on `main` is what is built: correct the document. When the code
+  differs from what was agreed, file an issue in the owning project and name it in the document's open questions.
+* The deployed landscape counts too: a leg that is on `main` but not deployed, or deployed from somewhere the
+  document does not name, is written down. Deployment manifests are in `klok/environment/ipaas-se-deploy-manifests`,
+  hosts and stateful services in the Ansible inventories of `klok/environment/klok-environment-setup`.
+
+## Things that are always wrong
+
+* Code for a new solution before its document exists, or a route id whose prefix is not a registered solution.
+* A leg in code that its solution document does not name, or a document that names a leg as built that is not.
+* Reusing a leg and sequence (`KLK002A11`) for a second route.
+* Integration logic in a Python or TypeScript client, or in an external engine, without a `[TACTICAL]` entry.
+* A solution document that describes an unbuilt part in the present tense without saying it is planned.
+* Copying a leg's route configuration or route table details into the solution document instead of linking the
+  project's `klok-docs/`.

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

@@ -100,12 +100,17 @@ cleanup task, never moved or deleted on the way.
 ## Finish
 
 1. Validate the requested behaviour, inspect the final diff, and commit to the task branch: stage specific paths,
-   check for secrets and unrelated files. Respect an explicit request to leave changes uncommitted.
-2. Push and open a merge request ready for review when the task or the established workflow allows it (see the
+   check for secrets and unrelated files, and write the message as a Conventional Commit (`fix(odl): …`; see
+   *Commits follow Conventional Commits* in `KLOK-AGENTS.md`). Respect an explicit request to leave changes
+   uncommitted.
+2. Push and open a merge request ready for review, with a Conventional Commits title that types the whole change
+   (`docs` only when nothing but documentation changed), when the task or the established workflow allows it (see the
    `klok-release` skill for what to check afterwards). Do not invent approval requirements and do not assume a
    permission that was not given.
 3. Report: canonical repository path, worktree path, branch, commits, tests run, push and merge request status,
    remaining changes and the next action. Unfinished work gets a clear handoff and keeps its worktree.
+4. End with the step-by-step guide of everything left for a human, merging the merge requests included
+   (KLOK-AGENTS.md *Manual steps are handed over as a guide*).
 
 ## Cleanup