@klok-integration/cli 0.7.327 → 0.9.345

package/assets/agents/AGENTS.documentation.md

@@ -9,7 +9,8 @@ content arrives here. There are two kinds, and they are edited differently:
   from the `KlokProjectDocumentationV1` payload the source repository's `main` pipeline publishes, replaces
   everything under `docs/` on every run and commits the AI sections under `docs/_ai/`. It reads only tenant klok's
   payloads today (klok/integration/klok-documentation-egress#2). Never edit it: a change made here is overwritten by
-  the next run. There are exactly two places to change it:
+  the next run. The one exception is `klok-documentation-settings.json` at the root (see *Rules*). There are exactly
+  two places to change its content:
   * `klok-docs/` in the source repository, in a merge request there: the hand written pages, their order and
     chapter titles (`toc-manifest.json`), and where an AI section appears (`<!-- KLOK:GENERATED:START <id> -->` …
     `<!-- KLOK:GENERATED:END <id> -->`);
@@ -28,7 +29,15 @@ content arrives here. There are two kinds, and they are edited differently:
   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.
+* Who reads the documentation is its visibility, set in `klok-documentation-settings.json` at the root
+  (`{"visibility": "global"}`): `public` (anyone, without login), `global` (every signed-in person of every tenant),
+  `tenant` (every member of the owning tenant), `members` (the owning domain's members and the tenant's owners, admins
+  and developers) or `admins` (the owners and admins of the owning domain and tenant). Without the file the default of
+  the documented path applies: `public` in a `public` group, `global` in tenant klok's `global` group, `tenant`
+  everywhere else. It is the one file people edit in a generated documentation project, the egress never touches it,
+  and tenant owners and admins change it, in GitLab or with `klok docs visibility --set`. Documentation is open by
+  default: narrow it only when someone asks for it. `klok docs publish` fails on a level that is not one, and its
+  dry run prints the level it would publish with. `scope` in `meta.json` decides nothing; a page that must not be seen
+  by the rest of the tenant belongs in a project with that visibility, not behind a note.
 * Preview locally with `znai preview --source=docs`, 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.workspace.md

@@ -46,8 +46,11 @@ What the answers mean:
 * **404**: the project is not published yet. Its hand written pages are in the repository's `klok-docs/` on
   `main`, the source of the same site: `git -C <repo> fetch origin && git show origin/main:klok-docs/<page>.md`
   (`toc-manifest.json` lists the pages). Read them there; nothing else is a substitute.
-* **401 or 403** (no token, or your GitLab account is not a member of the tenant or domain): say so and ask for a
-  token or for access. Never guess what the page says, and never try another way in.
+* **Public documentation needs no token:** `klok docs read` and `klok docs list` work without one and say the read
+  was anonymous. Everything else needs your GitLab token.
+* **401 or 403** (no token for documentation that is not public, or your GitLab account is not among the project's
+  readers, which its visibility decides): say so and ask for a token or for access. Never guess what the page says,
+  and never try another way in.
 
 The `klok-docs` skill describes the lookup in detail. Cite the doc id you relied on, and the `fetchedAt` from
 `klok docs read --json`, in your answer or merge request description.
@@ -80,7 +83,7 @@ it when a task touches the platform:
 
 | File | Holds |
 |---|---|
-| `knowledge/platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL |
+| `knowledge/platform-rules.md` | the current platform rules: principles, roles and access (owners, admins, developers), naming, route ids and legs, changes and work (change requests, implementation issues, beads), topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL, documentation and who reads it |
 | `knowledge/glossary.md` | the Klok terms and what they mean |
 | `knowledge/kloker-identity.md` | Kloker's identity and writing style |
 | `knowledge/roles/` | the role handbooks of the Kloker role models |
@@ -332,9 +335,9 @@ access, Keycloak broker clients or a service that serves several tenants.
   name and rejects a payload that claims another one.
 * **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, `DGR012E1_...`). When the content belongs to one reader, the
-  publisher may choose that reader's tenant slug as the purpose
+  named topic, approved by an owner or admin of the topic's tenant or domain and recorded in Git in the owning
+  tenant. The topic keeps its own name; 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.
 * **Platform services** (logs, the ODL, tasks, AI, documentation) are klok services, and today each one is
@@ -347,15 +350,16 @@ access, Keycloak broker clients or a service that serves several tenants.
   is `service-account-<client id>`; one CI broker client per tenant; every broker client attaches the client scope
   `pulsar` (audience and the `nbf` claim Pulsar requires) instead of copying mappers.
 * **Grants:** `publish` and `consume` on the service's own domain and its tenant's `common`, as namespace grants;
-  anything in another domain or tenant is `consume` on one topic, never `publish`, approved by its owner and
-  recorded in Git in the owning tenant. Pulsar's `produce`/`consume` appear only inside a grant command.
+  anything in another domain or tenant is `consume` on one topic, never `publish`, approved by an owner or admin of
+  its tenant or domain and recorded in Git in the owning tenant. Pulsar's `produce`/`consume` appear only inside a
+  grant command.
 * **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, 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
+  what needs no approval (the generic topic of every datamodel) and what an owner or admin 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`
@@ -375,8 +379,11 @@ Klok documentation has three levels, and a change is finished only when all thre
   project outside them includes `klok/environment/build-ci-templates:/klok-docs-send.yml`).
   `klok docs send --dry-run` shows what would be sent. KlokDocumentationEgress
   (`klok/integration/klok-documentation-egress`, KLK007) builds the repository's documentation project from it. That
-  documentation project is output, and nobody edits it. This runs for tenant klok only: another tenant has no
-  documentation broker client, so its `klok_docs_publish` job fails and, being `allow_failure`, only warns
+  documentation project is output, and nobody edits it except `klok-documentation-settings.json` at its root, which
+  says who reads it (`public`, `global`, `tenant` by default, `members` or `admins`) and which tenant owners and
+  admins change, in Git or with `klok docs visibility --set`; documentation is open by default and narrowed only when
+  someone asks. This runs for tenant klok only: another tenant has no documentation broker client, so its
+  `klok_docs_publish` job fails and, being `allow_failure`, only warns
   (klok/environment/klok-environment-setup#33), and the egress reads only klok's topic
   (klok/integration/klok-documentation-egress#2). There are two places to change a project's documentation:
   `klok-docs/` in the source repository (including the `KLOK:GENERATED` markers that place AI sections in a page),

package/assets/agents/knowledge/README.md

@@ -22,7 +22,7 @@ text of its own.
 | File | What it is | Composed into |
 |---|---|---|
 | `glossary.md` | the Klok terms and their meanings, with the rule never to guess a term | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
-| `platform-rules.md` | the current platform rules: principles, naming, route ids and legs, topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL | the agent runner's doctrine, the role models |
+| `platform-rules.md` | the current platform rules: principles, roles and access (owners, admins, developers), naming, route ids and legs, solutions, changes and work (change requests, implementation issues, beads), topics, datamodel classes, write narrow and consume wide, claim check, tasks, the ODL, documentation and who reads it | the agent runner's doctrine, the role models |
 | `kloker-identity.md` | who Kloker is, and the Unslop writing style | every request to the models `Kloker` and `Kloker-nothink` |
 | `roles/integration-architect.md`, `roles/integration-developer.md` | only what is specific to the role; the rules come from `platform-rules.md` | the role models `Kloker-Integration-Architect` and `Kloker-Integration-Developer` |
 | `retired-patterns.txt` | conventions the platform no longer has, one pattern per line with the reason | tests that fail when a prompt teaches a retired rule |

package/assets/agents/knowledge/glossary.md

@@ -16,6 +16,9 @@ it as the source does.
 | DLQ | Dead letter topic `<topic>_DLQ`, where a message goes after its retries are exhausted; it is provisioned with its topic |
 | Tenant | An organisation on the platform, and its security boundary; every topic, ODL object and GitLab group belongs to one tenant |
 | Domain | A business area inside a tenant. `common` is shared by the tenant's domains, `public` is open to anyone |
+| Role | What a person may do, given by Keycloak groups; a person may hold any number of roles, in any tenants and domains. There are nine: Klok Framework Owner, Admin and Developer on the platform (`/klok/owners`, `/klok/admins`, `/klok/developers`), Tenant Owner, Admin and Developer (`/tenants/<tenant>/owners`, `admins`, `developers`) and Domain Owner, Admin and Developer (`/tenants/<tenant>/domains/<domain>/owners`, `admins`, `developers`). In code they are `KlokOwner`, `TenantAdmin`, `DomainDeveloper` and so on |
+| Owner | The named main contact of the platform, a tenant or a domain; every tenant and domain has one or more. An owner is always also an admin of the same scope, so an owner may do whatever an admin may |
+| Visibility | Who reads a documentation project on docs.klok.dev, widest first: `public` (anyone, without login), `global` (every signed-in person of every tenant), `tenant` (every member of the owning tenant, the default), `members` (the owning domain's owners, admins and developers and the tenant's), `admins` (the owners and admins of the owning domain and of the tenant). Set in `klok-documentation-settings.json` of the documentation project; documentation is open by default and narrowed only when someone asks |
 | Route, route id | One Camel route per Java class (except a `KlokRestApi`, one per operation, and a `KlokRuntimeInstanceRoute`, one per instance `<RouteId>#<instanceKey>`). 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, P processing, E egress, A API, S sub route, T timer |
 | Ingress, egress | An ingress is a route that takes a message from outside the platform onto the broker; an egress takes a message off the broker to the outside. An ingress is an onramp or a channel adapter, an egress an offramp or a channel adapter. As a word for a service (`klok-postmark-ingress`) it says what the service is, never a permission |
@@ -24,6 +27,15 @@ it as the source does.
 | 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 |
+| Change request | A change to the integration landscape: an issue in the tenant's `integration-solutions` registry labelled `change-request`, named `<registry path>#<iid>`; its questions, design, issues, beads and merge requests link back to it |
+| Question | An issue in the registry labelled `question` and linked to a change request: something a person answers, in a comment, before the change can be planned |
+| Design merge request | The one merge request in the registry that designs a change request: it brings the solution document to the new steady state and adds the issue manifest |
+| Issue manifest | `ISSUE_MANIFEST.json` in `solutions/<KEY>_<slug>/changes/<iid>/` of the registry: the implementation issues a change request needs, each `planned`, or `approved` by a person; issues are made from it once it is on `main` |
+| Implementation issue | An issue in the project that does the work, made from an approved manifest item; it carries `solution:<KEY>`, a footer that names its change request, and a link to it |
+| `kloker`, `developer` | The labels of an implementation issue that say who builds it: Kloker, bead by bead, or a developer in a capable harness. Never both |
+| Bead | A file in `.beads/` of a repository that describes one small change of an implementation issue, small enough for Kloker with no judgement left (the bead sizing rules); it is done when the merge request that implements it merges |
+| Harness | The program a person runs a coding agent in, such as Claude Code, Codex, Copilot or OpenCode; only in this literal sense |
+| Background Kloker | The agent service's loop that follows a tenant's `kloker/policy.json` in Git: it repairs Kloker's merge requests and picks up the open beads of `kloker` issues |
 | 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 |
 | Datamodel | A versioned data contract; the major version is in the name (`CustomerV1`). Classes: public (A), common (B) and domain (C) are XSD in a Git project of their own with generated Java, Python and TypeScript; system (X) models one external system and may be plain Java classes. All four classes may travel on the broker |

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

@@ -32,11 +32,36 @@ documentation or the dependency catalog can give you.
   anyone.
 * AI proposes, a human approves, CI verifies. Every write goes through a merge request, an issue or a draft that a
   person accepts.
+* Documentation is open by default. Every member of a tenant reads all of the tenant's documentation, and a
+  documentation project is narrowed to its domain or to the admins only when someone asks: what is built gets reused
+  only when people can find it and read it.
 * A deliberate deviation from these rules is tagged `[TACTICAL]` in the solution document, with its cost and the
   condition for removing it. Never deviate silently.
 * Forbidden even as tactics: reading or writing another service's database, a topic carrying several datamodels,
   and state in a route's memory that the next message depends on.
 
+## Roles and access
+
+A person's roles are Keycloak groups, and a person may hold any number of them, in any tenants and domains.
+
+| Role | Keycloak group | Appointed by |
+|---|---|---|
+| Klok Framework Owner | `/klok/owners` | by hand in Keycloak |
+| Klok Framework Admin | `/klok/admins` | by hand in Keycloak |
+| Klok Framework Developer | `/klok/developers` | by hand in Keycloak |
+| Tenant Owner | `/tenants/<tenant>/owners` | a platform admin: `owners` in tenants.yml |
+| Tenant Admin | `/tenants/<tenant>/admins` | a platform admin: `admins` in tenants.yml |
+| Tenant Developer | `/tenants/<tenant>/developers` | the tenant's owners and admins, in klok.dev |
+| Domain Owner | `/tenants/<tenant>/domains/<domain>/owners` | the tenant's owners and admins, in klok.dev |
+| Domain Admin | `/tenants/<tenant>/domains/<domain>/admins` | the tenant's owners and admins, in klok.dev |
+| Domain Developer | `/tenants/<tenant>/domains/<domain>/developers` | the tenant's owners and admins and the domain's, in klok.dev |
+
+* Every tenant and domain has one or more owners, its named main contacts. An owner is always also an admin of the
+  same scope: whatever reads the groups treats an owners group as owners and admins, and the person is kept in both
+  groups.
+* An approval in a tenant or a domain (a topic, a broker grant, access to documentation) is given by an owner or an
+  admin of that tenant or domain. Klok Framework Owners and Admins act on every tenant.
+
 ## Routes and naming
 
 * One Camel route per Java class. The route id is the class name, the configuration prefix and the solution key:
@@ -96,6 +121,52 @@ documentation or the dependency catalog can give you.
 * New development and maintenance are one process: a change to a leg brings the solution document to the new steady
   state in the same change set, and `klok solutions check` compares the documents with the code on `main`.
 
+## Changes and work
+
+* A change to the integration landscape starts as a **change request**: an issue in `<tenant>/integration-solutions`
+  labelled `change-request`, `solution:<KEY>` (`solution:new` while the solution has no id) and `change:<kind>`, named
+  `<registry path>#<iid>` (`acme/integration-solutions#12`). Everything made for it links back to it. A question to a
+  person is an issue in the registry labelled `question` and linked to the change request; the answer is a comment, and
+  closing the question says it is answered. A comment a tool writes to say where a change stands carries
+  `<!-- klok:status -->`, and the planner reads past it.
+* **The design is one merge request** in the registry that mentions the change request (`Refs <registry>#<iid>`). It
+  brings the solution document to the new steady state, where every leg the change adds is `planned` on every line
+  that names it, and adds the plan: `solutions/<KEY>_<slug>/changes/<iid>/ISSUE_MANIFEST.json` with one
+  `issues/<stableKey>.md` per implementation issue. Planning again while it is open adds to the same merge request. A
+  person approves an item by setting it `approved` in the manifest; issues are created only from a plan on `main`, so
+  merging the design is what lets them be made.
+* **An implementation issue** lives in the project that does the work. It carries `solution:<KEY>`, a `relates_to` link
+  to the change request and to the issues it depends on, and a footer that names its change request, solution, stable
+  key, manifest path and dependencies. Every merge request Kloker opens carries `klok-integration-agent`; a draft whose
+  build never passed also `build-failed`.
+* **Kloker or a developer builds an issue, never both.** Bead creation either splits the issue into beads, labels it
+  `kloker` and opens a merge request with the bead files, or labels it `developer` and says in a comment why it cannot
+  be split. A developer builds a `developer` issue in a capable harness (Claude Code, Codex, Copilot, OpenCode), and
+  Kloker takes no bead of it.
+* **Claim before you start.** Whoever works on a bead reports it `in_progress` before the work starts and `open` again
+  when they let it go, and nobody starts a bead someone else holds. A bead with an open merge request is
+  `needs_review`.
+* **A bead is done when its merge request merges.** The merge request that implements a bead sets the bead file to
+  `done` with a progress entry, so the merge is what makes it done. A bead file on `main` that is `done` or `cancelled`
+  wins over any report, and a bead whose `dependsOn` are not all done on `main` waits.
+* **Two failures hand a bead to a developer.** When Kloker has failed on a bead twice since its file last changed, the
+  bead is reported `blocked`, its issue's label `kloker` is replaced by `developer`, and a comment says why and links
+  the draft merge requests. Changing the bead file gives Kloker two new attempts.
+* **The close rule.** A change request is ready to close when every implementation issue linked to it is closed and the
+  solution document on `main` describes what is built: no leg it added is still `planned`. A person closes it.
+
+**Bead sizing.** A bead is small enough for Kloker, a cheap model with no judgement left, or it is not a bead:
+
+* it changes one thing in one repository;
+* every decision is already named: the paths, the route id, the topics with their purpose, the datamodel and its
+  version, the configuration keys;
+* its acceptance criteria can be checked from the build and the diff;
+* it builds on its own;
+* it needs no missing fact and no step only a person may take (Vault, Ansible, Keycloak, a merge);
+* it is small, under a day's work for a person.
+
+An issue that cannot be split like that is a developer's.
+
 ## Topics and CloudEvents
 
 * `persistent://<tenant>[_<env>]/<domain>/<Model>[_<purpose>]`. Production has no environment suffix
@@ -125,8 +196,9 @@ documentation or the dependency catalog can give you.
 * 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.
+  topic (a purpose, a request/reply pair) and every grant is requested in klok.dev and approved by an owner or admin of
+  the topic's tenant or domain (a Tenant Owner or Admin, or a Domain Owner or Admin 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.
@@ -174,8 +246,9 @@ whether a model may travel on a topic; it decides how widely the model is shared
 * The topic decides the tenant, never the message. A service takes the tenant from the topic's namespace and rejects
   a payload or property that claims another tenant.
 * A tenant publishes only in its own namespace, `<tenant>[_<env>]/<domain>`. Nobody holds `publish` in another
-  tenant's namespace. Reading elsewhere is a `consume` grant on one 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.
+  tenant's namespace. Reading elsewhere is a `consume` grant on one named topic, approved by an owner or admin of the
+  topic's tenant or domain and recorded in Git in the owning tenant. The topic keeps its own name; the reader is known
+  by its subscription.
 * Platform services (logs, the ODL, tasks, AI, documentation) are klok services, today configured for tenant klok
   only. One that serves several tenants follows the same rule: a tenant's requests live in the tenant's namespace
   (`persistent://<tenant>[_<env>]/common/<Model>`), the service is granted `consume` on exactly those topics, and
@@ -183,8 +256,8 @@ whether a model may travel on a topic; it decides how widely the model is shared
   (`persistent://klok[_<env>]/<domain>/<Model>_<tenant>`).
 * 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.
+  approval and what an owner or admin 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.
 
@@ -214,6 +287,24 @@ and reads, searches and writes synchronously through `odl()` (`get`, `search`, `
 request topics are in the `common` domain; a change event goes to the domain of the object. Tenant-tunable behaviour of a service (prompts, sections, languages) is a Klok
 standard shipped with the service plus a tenant override stored in the ODL.
 
+## Documentation
+
+* Every repository documents itself in `klok-docs/`. Its documentation project, `<tenant>/documentation/<same path>`,
+  is generated output, published on docs.klok.dev under its doc id; nobody edits it except its
+  `klok-documentation-settings.json`.
+* Who reads a documentation project is its visibility, widest first: `public` (anyone, without login), `global`
+  (every signed-in person of every tenant), `tenant` (every member of the owning tenant), `members` (the owning
+  domain's owners, admins and developers, and the tenant's) and `admins` (the owners and admins of the owning domain
+  and of the tenant). Klok Framework Owners and Admins read everything; Klok Framework Developers read like a
+  developer of every tenant.
+* The default comes from the path and is the same rule for every tenant, tenant klok included: `public` for a project
+  in a `public` group, `global` for one in tenant klok's `global` group, `tenant` for everything else. A level is set
+  in `klok-documentation-settings.json` at the root of the documentation project (`{"visibility": "global"}`), in
+  Git or with `klok docs visibility --set`: tenant owners and admins set any level, domain owners and admins their
+  domain's projects up to `global`.
+* Public documentation is read without a token (`klok docs read`, `klok docs list`); everything else with a GitLab
+  token or a login.
+
 ## Versions and delivery
 
 * Framework libraries, the Gradle plugin and datamodels are released with timestamped versions from `main` and

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

@@ -46,6 +46,27 @@ topic-dlq # dead letters are <topic>_DLQ
 (?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
 #
+# klok.dev's work package model is retired (2026-10-29): a change request's work is implementation issues and beads in
+# GitLab, linked to the change request.
+(?i)\bwork[- ]packages?\b # the work package model is retired; a change request's work is implementation issues and beads in GitLab
+(?i)\bTodo 360\b # the work package model is retired; a change request's work is implementation issues and beads in GitLab
+# The planner loads the platform rules instead of restating the 11-step process of the old strategy chapter
+# (klok-integration-agent#47); issues are linked with relates_to, and an issue is split into beads, not planned again.
+(?i)\b11-step\b # the development process is described once, in the Klok user guide; a prompt loads the platform rules instead of restating a process
+(?i)\bGitLab Free has no issue links\b # implementation issues are linked to their change request and their dependencies with relates_to, which every GitLab edition has
+(?i)\blocal GSD\b # an implementation issue is split into beads by bead creation; there is no local planning step before it
+#
+# Tenant klok's documentation is read like every tenant's (2026-10-30): its owning scope is tenant, domain or system,
+# and who reads a documentation project is its visibility, set in klok-documentation-settings.json of the
+# documentation project. A project of tenant klok is read by every tenant only when it is set global, or sits in
+# klok's global group.
+(?i)\b(every|all)\b[^.\n]{0,20}\bklok\b[^.\n]{0,20}\bdocumentation\b[^.\n]{0,20}\b(is|are) (always )?(global|read by every tenant|visible to every tenant) # tenant klok's documentation is read by its own members by default; global is a visibility its documentation project sets
+(?i)\bklok('s)? documentation (projects? )?(is|are) (always )?(global|read by every tenant|visible to every tenant) # tenant klok's documentation is read by its own members by default; global is a visibility its documentation project sets
+(?i)\bglobal \(tenant\s*==?\s*klok\) # the owning scope is tenant, domain or system for every tenant; global is a visibility level, not tenant klok's scope
+(?i)\bglobal documentation under\b # a standalone documentation project of tenant klok is read by klok's members unless its settings file sets global
+(?i)\bvisibility follows [`'"]?meta\.json # who reads documentation is set in klok-documentation-settings.json; the scope in meta.json decides nothing
+(?i)\bonly the platform tenant may claim\b # every tenant may set every visibility level, global and public included
+#
 # 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
 KlokTenantBridgeRoute # does not exist; a KlokProcessingRoute in the reading tenant maps a granted topic

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

@@ -1,6 +1,6 @@
 ---
 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, or a file transfer flow's sealed secrets and its write to the ODL.
+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`), who reads a documentation project (`klok docs visibility`), 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, or a file transfer flow's sealed secrets and its write to the ODL.
 ---
 
 # The klok command line
@@ -21,6 +21,8 @@ CLI version, generated from the program itself; when it is missing (an installer
 | 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 |
+| who reads each documentation project of the tenant, and whether the level is set or the default | `klok docs visibility` (`<doc-id>...` for some) |
+| a documentation project's visibility changed, when the person asked for it | `klok docs visibility <doc-id>... --set <level> --reason "<why>"`, or `--default`; klok.dev checks that the person may |
 | 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` |
@@ -30,12 +32,23 @@ CLI version, generated from the program itself; when it is missing (an installer
 | 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` |
+| a change request with its questions, design merge requests and implementation issues, and who builds each | `klok change show <registry>#<iid>` (or the URL of an implementation issue) |
+| a change request planned into its solution document and one issue manifest | `klok agent plan --change <registry>#<iid>` |
 | the beads of the current repository | `klok bead list`, `klok bead show <id>`, `klok bead report <id>` |
+| a bead taken before you start, let go, or done in the merge request that implements it | `klok bead claim <id>`, `klok bead release <id>`, `klok bead done <id> --merge-request <url>` |
 | 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` |
 | a sealing key for a tenant's klok-file-transfer, a secret sealed for a file flow, or flows written to the ODL from Git | `klok file-transfer keygen`, `seal`, `apply --dry-run` (then without) |
 
+## Working on a change request
+
+Who builds an implementation issue, when a bead is claimed and when it is done are in `knowledge/platform-rules.md`,
+*Changes and work*, next to `KLOK-AGENTS.md`. Follow it when a task names a change request, an implementation issue
+or a bead: `klok change show` reads where the change stands, `klok bead claim` takes a bead before you start (a bead
+someone else holds is refused), and `klok bead done --merge-request` sets it done in the merge request that implements
+it. Never take a bead of an issue labelled `developer` unless you are that developer.
+
 ## The workspace
 
 `klok sync pull` brings the workspace current before you read it: every repository under the workspace root (config
@@ -72,7 +85,7 @@ patch` command: a person writes Vault, an agent hands the command over. The oper
 ## 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
+(`klok whoami`, the agent commands, `klok solutions`, `klok docs visibility`). 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