@klok-integration/cli 0.2.0

package/assets/agents/AGENTS.application.md

@@ -0,0 +1,17 @@
+## This repository: application
+
+A Klok application (portal, docs portal, agent service or another container) that is built and deployed with the
+platform pipelines: image to `repo.klok.dev`, deployment manifest in the manifests repository, secrets through
+Vault. Read https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the release process and the
+repository's own `README.md` and `docs/` for its architecture.
+
+### Rules
+
+* Follow the repository's build and test commands from `README.md` or `package.json`; keep type checks and tests
+  green before pushing.
+* Anything the application stores about Git content (projects, datamodels, catalog, documentation) is derived data
+  with a refresh path from `main`; there is no feature that only works through the application.
+* Tenant, domain and role separation is enforced on the server side; never rely on the UI hiding something.
+* Secrets and environment configuration come from the Vault env secret of the deployment, never from committed
+  files.
+* Update `klok-docs/` (or `docs/`) with every change of behaviour, API or configuration.

package/assets/agents/AGENTS.datamodel.md

@@ -0,0 +1,21 @@
+## This repository: datamodel project
+
+A Klok datamodel: an XSD (or JSON schema) under `schema-definition-xsd/`, converted by the pipeline to Avro and to
+a generated Java project that is published as `dev.klok.<tenant>.datamodel:<name>-v<n>` and written into the
+dependency catalog. Read https://docs.klok.dev/klok-framework-klok-common/llm.txt for naming and
+https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt for the pipeline.
+
+### 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`).
+* The major version is part of the model name (`Customer_v1`, class `CustomerV1`); 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.
+* Datamodel documentation lives in `klok-docs/` (purpose, fields that need explanation, producers and consumers,
+  design decisions) and is mirrored to the documentation project.
+* On `main` the pipeline publishes and updates the catalog; check it, then refresh consumers with
+  `./gradlew updateKlokLibsToml`.

package/assets/agents/AGENTS.documentation.md

@@ -0,0 +1,19 @@
+## This repository: documentation project
+
+A znai documentation project published to https://docs.klok.dev under the doc id in `klok-docs-sync.json`. Read
+https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (docs sync) for how content arrives here.
+
+### Rules
+
+* `docs/klok-docs/` and `docs/generated/` are written by the docs sync of the source repository. Never edit them
+  here; change `klok-docs/` in the source repository, or the generator. Only `KLOK:GENERATED` regions of AI
+  maintained pages are rewritten automatically.
+* Human pages live in `docs/` next to them (`overview`, `architecture`, `operations`, `changelog`); keep
+  `docs/toc` and `docs/toc-manifest.json` in sync when adding a page.
+* 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`.
+* 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 --source-root docs --preview`, and check what a publish would do with
+  `klok docs publish --dry-run`; the `llm.txt` the build generates is what agents read.

package/assets/agents/AGENTS.framework.md

@@ -0,0 +1,19 @@
+## This repository: framework library
+
+Part of the Klok framework (klok-common, the broker client, the Quarkus extension, the gradle plugin or the CI
+templates). Changes here reach every tenant, so read the library's `klok-docs/` and its published documentation
+(`https://docs.klok.dev/klok-framework-<repo>/llm.txt`) before changing behaviour.
+
+### Rules
+
+* Public API changes are documented in `klok-docs/` in the same merge request, including a design decision entry
+  when a convention changes; a breaking change is a new major version.
+* Names and property keys are defined once in klok-common and mirrored by the other libraries and clients; never
+  spell a topic name or a `klok-*` property by hand elsewhere.
+* Builds: `./gradlew build` must stay green, tests run on the JUnit Platform, and the extension's runtime and
+  deployment modules must get exactly the same version (one timestamp per build).
+* Releases happen from `main` only, in dependency order (klok-common, broker client, extension), each waiting for
+  its publish and the catalog update before the next is merged. Maven Central is immutable: a version is never
+  republished.
+* CI template changes are tested with a dry run (`KLOK_CATALOG_UPDATE_DRY_RUN=true`, a branch pointing at the
+  template branch) before they are merged to `main`, because every project includes the templates from `main`.

package/assets/agents/AGENTS.integration.md

@@ -0,0 +1,33 @@
+## This repository: integration project
+
+A Klok integration on the Quarkus extension 2.0: one Camel route per class, each extending a framework pattern
+(`KlokOnrampRoute`, `KlokProcessingRoute`, `KlokOfframpRoute`, their `Sync` variants, `KlokRestApi` and
+`KlokRestApiHandlerRoute`, `KlokAsyncTaskWorkerRoute`, `KlokCustomRoute`) and implementing the capabilities it
+needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt before writing a route.
+
+### Commands
+
+```
+./gradlew build                      # compile, unit and @QuarkusTest tests (no broker, recording clients)
+./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
+```
+
+### Rules
+
+* Route class name = route id `<TENANTSHORT><NNN><LEG><seq>_<Description>`; one solution id per business flow.
+  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.
+* 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()`).
+* Large payloads go through the claim check (`KlokClaimCheckStore`), long running work through tasks
+  (`KlokTaskInitiation`, `KlokAsyncTaskWorkerRoute`).
+* Tests: `@QuarkusTest` with the recording broker client factory; assert routes started and published messages,
+  never talk to a real broker or OpenSearch in unit tests.
+* `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.
+* On `main` the pipeline builds the image, updates the deployment manifest and syncs the documentation; check it.

package/assets/agents/AGENTS.workspace.md

@@ -0,0 +1,193 @@
+# Klok platform rules for AI agents
+
+These rules apply to every AI coding agent (Claude Code, Codex, OpenCode, Cursor, Antigravity, Copilot, Cline and
+others) working on Klok repositories. `KLOK-AGENTS.md` is the single source of instructions and Klok owns that
+file outright: it is replaced wholesale on every update, so never edit it by hand. The harness files (`AGENTS.md`,
+`CLAUDE.md`, `GEMINI.md`, `.cursor/rules`, `.agents/rules`) carry one managed row that points here and are
+otherwise yours. Do not copy rules into them.
+
+## Read the documentation before guessing
+
+The platform documentation is published at https://docs.klok.dev. Every documentation project exposes its full
+content as one markdown file at `https://docs.klok.dev/<doc-id>/llm.txt`; fetch it instead of relying on memory.
+
+| Topic | Read |
+|---|---|
+| Platform principles, event driven design, naming, onboarding | https://docs.klok.dev/klok-integration-strategy-and-tactics/llm.txt |
+| Route framework (patterns, config, logging, errors, topics, tasks) | https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt |
+| Naming conventions, message properties, CloudEvents | https://docs.klok.dev/klok-framework-klok-common/llm.txt |
+| Broker client | https://docs.klok.dev/klok-framework-klok-brokerclient-java/llm.txt |
+| Gradle plugin, versions, catalog | https://docs.klok.dev/klok-framework-klok-gradle-plugin/llm.txt |
+| CI templates, release process, Vault roles | https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt |
+
+A 404 means the documentation project is not published yet; read the repository's `klok-docs/` folder instead.
+The `klok-docs` skill describes the lookup in detail.
+
+## Git is the truth, everything must work by hand
+
+* `main` in Git is the only source of truth for code, datamodels, the dependency catalog, project metadata,
+  templates and documentation sources. Fetch fresh `main` before reading or changing a repository; a local clone or
+  a database row is never a source.
+* klok.dev is a convenience layer on top of Git. Whatever it does must also be possible by editing repositories in
+  GitLab by hand, and klok.dev must notice such manual changes. Never build a feature that makes the portal the
+  only path, and never introduce a cache or copy of Git content without a refresh mechanism.
+* Ask of every change: "what happens if someone does this directly in GitLab?" A mismatch between Git and klok.dev
+  is a bug in klok.dev.
+
+## One task, one worktree, one branch
+
+Every task that changes repository files runs in its own Git worktree on its own branch, created by the agent as
+part of the task. Read-only investigation may use the canonical checkout. The `klok-worktree` skill has the
+step by step procedure; the contract every agent follows is:
+
+* Workspace root: the directory `klok sync` mirrors into (config key `workspace`, default `~/devklok`; expand `~`
+  to the real home directory, never assume a user name). Canonical checkout: `<root>/<tenant>/<group>/.../<repo>`.
+  Task worktree: `<root>/worktrees/<tenant>/<group>/.../<repo>/<task-id>`. Task branch: `agent/<task-id>`.
+
+  | Purpose | Path |
+  |---|---|
+  | Canonical | `~/devklok/klok/integration/klok-api-konvoj` |
+  | Session A | `~/devklok/worktrees/klok/integration/klok-api-konvoj/20260911-auth-a1b2c3d4` |
+  | Session B | `~/devklok/worktrees/klok/integration/klok-api-konvoj/20260911-tests-e5f6a7b8` |
+
+* Preserve the complete repository path including every subgroup. Never flatten to the repository name, never put
+  a worktree inside `.claude`, inside the canonical checkout or in a tool specific directory. If a tool's own
+  worktree automation uses another layout, configure it to follow this contract or create the worktree by hand.
+* `<task-id>` is unique per writing session: lowercase letters, digits and hyphens, `YYYYMMDD-<topic>-<8 hex>`
+  (`20260911-auth-a1b2c3d4`). One session owns one worktree per repository; never share a worktree between
+  concurrent writers, and give every delegated writer its own worktree and branch. A task that spans repositories
+  uses the same task id under each repository's path and records repository, base commit, branch and worktree.
+* Base the worktree on the remote default branch after a fetch (`origin/main` once verified through the remote
+  HEAD, not assumed) unless the task names another base. If a branch or directory with the chosen name already
+  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.
+* 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
+  tasks would collide, and never write through absolute paths into another checkout.
+* Instruction files along the canonical path (`<root>/KLOK-AGENTS.md`, `<root>/<tenant>/KLOK-AGENTS.md`) are not
+  above a worktree under `<root>/worktrees`; read them deliberately, together with the `KLOK-AGENTS.md` of the worktree
+  revision, and resolve conflicts before editing.
+* State the repository, worktree path and branch before the first edit. A tool that cannot reach the worktree
+  reports that limitation instead of silently editing the canonical checkout.
+* Commit finished work to the task branch (stage specific paths, check for secrets and unrelated files), push and
+  open a merge request when the task or the established workflow allows it, and report the repository path,
+  worktree, branch, commits, tests and merge request status. Unfinished work gets a clear handoff and keeps its
+  worktree.
+* Keep the worktree until the branch is merged or cleanup is asked for; a clean status does not mean the commits
+  are pushed. Remove with `git worktree remove <exact path>` without force, never `rm -rf`, and never delete a
+  branch merely because a session ended. Legacy worktrees are reported, not moved or deleted.
+* Repository discovery and sync (`klok sync`, workspace generators) exclude `<root>/worktrees`; a task tree is
+  never a canonical repository.
+
+## Versions come from the dependency catalog
+
+* Framework libraries, the gradle plugin and datamodels are released with timestamped versions from `main`
+  (`0.3.0+260910043154`, `1.0.0-build.260909105636`). After a release the CI writes the version into
+  `klok/framework/klok-gradle-dependency-catalog`.
+* Never pin or edit these versions by hand in a project. Refresh the project's copy with
+  `./gradlew updateKlokLibsToml` and commit the refreshed `gradle/klok-libs.versions.toml`.
+* A change that spans framework libraries is merged and published in dependency order: klok-common, then the broker
+  client, then the Quarkus extension.
+
+## Pipelines, secrets and infrastructure
+
+* After every push to git.klok.dev, check the pipeline (`glab api "projects/<id>/pipelines?per_page=3"`, job traces)
+  and fix failures before moving on. Publishing, image pushes, manifest updates and catalog updates only happen on
+  `main`; merge request pipelines build and test.
+* Vault (`vault.ipaas.se`) is changed by a human only. Agents may read to diagnose and must then propose the exact
+  command, including every existing field of the object.
+* New projects are created 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 and it provisions what the
+  project needs to build. Creating a project by hand is a legitimate fallback under *Git är sanningen*, but it is
+  not the normal path: say up front what a human will still have to do, rather than letting it surface as a red
+  pipeline. Today that always includes the Vault CI role `<tenant>-ci-project-<gitlab id>`, which needs both
+  `default` and the tenant CI read policy; see `klok/application/frontend-klok-dev` issue #7.
+* Never push to `main` of an existing repository, never force push, never merge. Work on a branch and open a
+  merge request that is ready for review; only a brand new repository gets its first commit on `main`. A draft
+  merge request is not the default, it is what you open when the work is knowingly unfinished, and you say why.
+
+## Logic lives in the Klok tools, not in the pipelines
+
+* Klok functionality belongs in the Klok tools: **klok-cli** (`@klok/cli`), **the Klok Gradle plugin** and **the
+  Klok build image** (which carries klok-cli). A job in a Klok-owned template is one command, `./gradlew <task>`
+  or `klok <command>`, plus the shared Vault login. Inline `curl`, multi-line shell, `if` guards, JSON assembly,
+  git plumbing or embedded Python/Node in a `.gitlab-ci.yml` is logic in the wrong place: move it into a tool,
+  where it is versioned, unit tested and runnable by hand.
+* The reason is portability. The ecosystem must not be coupled to GitLab; a customer should get Klok running on
+  Azure DevOps or GitHub with minimal effort. Everything that lives in a tool moves for free, everything that lives
+  in a template has to be rewritten. Read the CI variables (tenant, repository path, commit, pipeline) in one place
+  inside the tool, never spread across jobs.
+* The rule is strict for what customers include: `build-ci-templates`, the `project-template-*` repositories and
+  the documentation publish include. `application/*` repositories are more free form.
+* The same design is what lets a project that was not created from a Klok template opt in: running klok-cli in its
+  own pipeline gives it, for example, documentation publishing. Tool commands are the product surface; templates
+  are only the convenient wiring of them.
+
+## Naming
+
+* 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.
+* 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`).
+* Context properties: `klok-correlation-id`, `klok-invocation-id`, `klok-parent-invocation-id`, `klok-task-id`,
+  `klok-solution-id`, `klok-route-id`, `klok-tenant`, `klok-domain`, `klok-environment`; same spelling as HTTP
+  header, Pulsar property and CloudEvents extension, `klok.`-prefixed as MDC key.
+* Repositories: `<tenant>/integration/domain/<d>/<repo>`, `<tenant>/datamodel/...`, mirrored documentation under
+  `<tenant>/documentation/...`; documentation ids are `slug(<tenant>-<group>-...-<repo>)`.
+
+## Documentation is part of every change
+
+Klok documentation has three levels, and a change is finished only when all three have been considered:
+
+* **The repository's own `klok-docs/`** (znai markdown, `toc-manifest.json`), which the CI mirrors into the
+  repository's documentation project. A change that adds or alters a route, a datamodel, a configuration key, a
+  CI job, a command or a decision updates `klok-docs/` in the same merge request.
+* **The platform documentation** under `<tenant>/documentation/`: the user guide (`klok-user-guide`), strategy
+  and tactics (`klok-integration-strategy-and-tactics`) and the framework, CI and tooling documentation. They
+  describe how the platform is used and why. A change that alters a rule, a convention, a workflow, a command or
+  a published contract belongs there too, even when the code that changed lives somewhere else entirely.
+* **Generated pages** (`docs/generated/`, `KLOK:GENERATED` regions), which are never edited by hand. A wrong
+  generated page is a bug in the generator.
+
+### Before the merge request
+
+1. Update the repository's `klok-docs/` in the same merge request as the change. Documentation that is promised
+   for a later merge request is documentation that never arrives.
+2. Ask what a reader of the platform documentation would now find wrong: a renamed command, a new rule, a changed
+   default, a workflow with one more step. Read the affected pages (`https://docs.klok.dev/<doc-id>/llm.txt`)
+   instead of guessing what they say.
+3. Correct what you can judge yourself. A central page that is now plainly wrong is fixed in its own small merge
+   request against that documentation project, linked from the change. What you cannot judge is written down
+   rather than dropped.
+4. Write the merge request description for two readers: the reviewer, and the documentation flow that runs after
+   the merge. State what changed, why, and which documentation it affects or might affect. A description that
+   says only "fixes the build" produces no documentation update.
+
+### After the merge
+
+The pipeline on `main` publishes the project's documentation payload (`KlokProjectDocumentationV1`: routes,
+sources, configuration keys and the whole `klok-docs/` folder with a hash per file). A documentation flow that
+reads that payload together with the merge request description and the diff, and proposes the central updates as
+merge requests for a human to review, is being built; until it runs, nothing behind you looks at the central
+documentation. Either way the steps above are the ones that matter: an author who knows what changed writes
+better documentation than a flow that reads the diff afterwards, and a proposal is a safety net for what was
+missed, never a reason to skip writing it.
+
+## How to work
+
+1. Restate the task, then read the relevant documentation and the repository's `KLOK-AGENTS.md` and `klok-docs/`.
+2. Create the task worktree and branch before the first edit (see *One task, one worktree, one branch*) and say
+   which repository, worktree and branch you work in.
+3. Build and test locally with the repository's standard commands before pushing; keep every commit green.
+4. Small, reviewable merge requests with a description that states what changed, why, and which documentation
+   it affects.
+5. A new project cloned from a template refreshes the catalog copy and the agent instructions before the first
+   push: `./gradlew updateKlokLibsToml updateKlokAgents`. klok.dev does the same HTTP fetch when it creates the
+   project. Re-run the tasks later to pick up a new catalog or a new skill set.
+6. Report outcomes faithfully: failing tests, skipped steps and open questions are stated, not hidden.

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

@@ -0,0 +1,51 @@
+---
+name: klok-datamodel
+description: Create or change a Klok datamodel (XSD first, generated Java, published to the dependency catalog) and wire consumers to it. Use when a task adds a domain object, changes a schema or asks which datamodel a route should use.
+---
+
+# Klok datamodels
+
+Read https://docs.klok.dev/klok-framework-klok-common/llm.txt (naming) and
+https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pipeline).
+
+## Creating or changing a model
+
+1. The model lives in its own repository `<tenant>/datamodel/<common|public|domain/<d>|system/<s>>/<name>-v<n>`,
+   where the repository name is the model name in kebab case (`supplier-invoice-v1`); the XSD file inside keeps
+   the PascalCase form (`SupplierInvoice_v1.xsd`).
+
+   **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,
+   including its Vault CI role.
+
+   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).
+
+   A hand created project has **no Vault CI role**, so its first `publish_java_projects` fails with
+   `role "<tenant>-ci-project-<id>" could not be found`. Say that up front and give the user the command; 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.
+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.
+5. Work in the task worktree (`klok-worktree` skill), push its `agent/<task-id>` branch, open a merge request;
+   the pipeline validates the XSD and generates the Java project. On `main` it
+   publishes `dev.klok.<tenant>.datamodel:<name>-v<n>:1.0.0-build.<ts>` and writes `<nameVn>` (for example
+   `klokOdlV1`) into the dependency catalog.
+
+## 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.
+* The generated class is `dev.klok.<tenant>.datamodel.<group>.<name>_v<n>.<Name>Vn`; the ODL type of an object is
+  the fully qualified class name.
+* The topic for the model is derived from the class (`persistent://<tenant>[_<env>]/<domain>/<Name>Vn`); do not
+  invent topic strings.

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

@@ -0,0 +1,51 @@
+---
+name: klok-docs
+description: Look up Klok platform documentation on docs.klok.dev (llm.txt per documentation project) before designing or changing anything on the Klok integration platform. Use when a task mentions Klok, routes, datamodels, topics, the ODL, tasks, the dependency catalog, CI templates or klok.dev.
+---
+
+# Reading Klok documentation
+
+The platform documentation is published on https://docs.klok.dev, one documentation project per repository. Each
+project exposes its whole content as a single markdown file, generated by znai:
+
+```
+https://docs.klok.dev/<doc-id>/llm.txt
+```
+
+Fetch that file and read it; it is the authoritative version of the repository's `klok-docs/` plus the generated
+route, datamodel and configuration pages. Do not answer from memory when a page exists.
+
+## Doc ids
+
+The doc id is the repository path without the leading slash, with `/` replaced by `-`, lower case:
+`/klok/framework/klok-quarkus-extension` becomes `klok-framework-klok-quarkus-extension`;
+`/acme/integration/domain/finance/acme-egress-fortnox` becomes
+`acme-integration-domain-finance-acme-egress-fortnox`. Global documentation under `/klok/documentation/<name>`
+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` |
+| 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, docs sync, catalog update | `klok-environment-build-ci-templates` |
+| ODL REST and request/reply, tasks API | `klok-integration-klok-api-opensearch` |
+| ODL writers, log receivers | `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` |
+
+## Procedure
+
+1. Identify the repositories involved and derive their doc ids.
+2. Fetch `https://docs.klok.dev/<doc-id>/llm.txt` for each. On a 404 the project is not published yet: read the
+   repository's `klok-docs/` folder from `main` instead (it is the source of the same pages).
+3. Read the strategy documentation first when the task touches design, naming or onboarding; read the framework
+   documentation before writing or changing a route.
+4. Cite the page you relied on in your answer or merge request description, so reviewers can check it.
+
+The portal at https://docs.klok.dev requires a Keycloak login for tenant and domain scoped documentation; global
+documentation is readable by every platform user. If a fetch is denied, ask the user for the content or run in an
+environment that is logged in.

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

@@ -0,0 +1,68 @@
+---
+name: klok-release
+description: Release and deploy on the Klok platform: pipelines, versions, the dependency catalog, deployment manifests, Vault roles and secrets, and what to check after a push. Use when a task involves merging, publishing, deploying, CI failures or setting up a new project.
+---
+
+# Releasing on Klok
+
+Read https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (release process by project type, Vault
+roles and secrets, catalog update) before acting.
+
+## The flow
+
+1. Work in the task worktree on its `agent/<task-id>` branch (`klok-worktree` skill); open a merge request that
+   is ready for review (draft only when the work is knowingly unfinished). The merge request pipeline builds and
+   tests only.
+2. After a merge to `main`: framework libraries publish to the GitLab registry and Maven Central and update the
+   dependency catalog; datamodels publish the generated artifact and update the catalog; integrations build and
+   push an image and update the deployment manifest in `klok/environment/ipaas/ipaas-service-deploy-manifests`,
+   which ArgoCD applies; documentation projects publish to https://docs.klok.dev.
+3. Check the pipeline after every push:
+   `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.
+
+## 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.
+
+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. When taking the manual route, name the remaining human steps up front instead of
+letting them surface as a red pipeline.
+
+> Automatic Vault provisioning is **not implemented yet**: `klok/application/frontend-klok-dev` issue #7,
+> *Provision the Vault CI role when klok.dev or agent.klok.dev creates a project*. Until it ships, every
+> project — however it was created — needs a human to add the role.
+
+## Setting up a new project (what must exist)
+
+* Vault JWT role `<tenant>-ci-project-<gitlab id>` bound to that `project_id`, carrying **both** `default` and
+  the tenant CI read policy (`klok-cicd-read` for tenant `klok`). A role with only `default` authenticates but
+  cannot read the shared secrets, and `publish` still fails — that is why the pipelines of projects 175 and 191
+  were red for months. Without any role at all the job fails at `auth/jwt/login` with
+  `role "<tenant>-ci-project-<id>" could not be found`.
+* 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).
+* Documentation projects need the tenant's docs upload client in Keycloak and in Vault (`secret/<tenant>`).
+
+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.
+
+## Common failures and their meaning
+
+| Symptom | Cause |
+|---|---|
+| `role "<tenant>-ci-project-<id>" could not be found` at `auth/jwt/login` | no Vault CI role for the project; it was created without provisioning |
+| `permission denied` reading `secret/.../cicd-environment-variables` | CI role exists but lacks the tenant CI read policy (has only `default`) |
+| `403` on `groups/<tenant>/-/packages/maven/...` | job token allowlist of the package project lacks the reader's group |
+| `Could not find dev.klok...:<version>` | the version is not published yet, or the catalog copy is stale (`updateKlokLibsToml`) |
+| `already deployed` from JReleaser | Maven Central already has that version; a `main` build is a new timestamp, do not retry the same job |
+| `sed: can't read klok/integration/<name>/<name>-crds.yaml` | no deployment manifest for the service yet |
+| `cannot run ssh` | the job needs `openssh-client`; the templates install it before pushing over SSH |

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

@@ -0,0 +1,39 @@
+---
+name: klok-route
+description: Write or change a Camel route on the Klok Quarkus extension 2.0 (onramp, processing, offramp, REST API handler, async task worker, custom route) with the correct naming, configuration, error handling, tests and klok-docs. Use for any change inside a Klok integration project.
+---
+
+# Writing a Klok route
+
+Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt first (pages `patterns`, `naming`,
+`config`, `error-handling`, `testing`); read the `klok-docs` skill for other pages.
+
+## Steps
+
+1. **Pick the pattern.** Ingress from a system: `KlokOnrampRoute<SYS, DOM>`; transformation between datamodels:
+   `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`.
+3. **Bind the datamodels** as type parameters; take them from the catalog bundle, never hand written DTOs.
+4. **Configure** through `routeConfig("key", default)` / `requiredRouteConfig("key")` and document every key in
+   `application.properties` as `<RouteId>.<key>`. Reserved keys: `enabled`, `logevents.*`, `retry.*`, `dlq.*`,
+   `topic.*`, `subscription.*`, `claimcheck.*`.
+5. **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).
+6. **Capabilities** as interfaces: `SplitIncomingMessage`, `AggregateOutgoingMessages`, `ClaimCheck`,
+   `KlokEmitCloudEventOnSuccess/Failure`, `PersistOutgoingMessages`, `KlokAsyncTaskInitiator`.
+7. **Test** with `@QuarkusTest` and the recording broker client factory: assert the route status is `Started`,
+   send a message, assert the published topic, body and `klok-*` properties.
+8. **Document** in `klok-docs/`: the route in `routes.md`, decisions in `design-decisions.md`, operations notes.
+9. 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.
+
+## Things that are always wrong
+
+* A route id that does not start with the solution id, or two routes with the same id.
+* Publishing to a hand written topic string; use the resolver and the datamodel.
+* Catching exceptions to return HTTP 200 with an error text.
+* Pinning a framework or datamodel version in `gradle/klok-libs.versions.toml` by hand.