@klok-integration/cli 0.8.336 → 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, changes and work (change requests, implementation issues, beads), 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, solutions, changes and work (change requests, implementation issues, beads), 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 |

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:
@@ -171,8 +196,9 @@ An issue that cannot be split like that is a developer's.
 * 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.
@@ -220,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
@@ -229,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.
 
@@ -260,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

@@ -56,6 +56,17 @@ topic-dlq # dead letters are <topic>_DLQ
 (?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` |
@@ -83,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

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

@@ -882,7 +882,7 @@ Read the platform documentation on docs.klok.dev, and publish this repository’
 klok docs read [options] <doc-id>
 ```
 
-Print the llm.txt of a documentation project on docs.klok.dev, the one markdown file with its whole content, read with your GitLab token. Cached under ~/.cache/klok/docs with the ETag, so a second read is one conditional request; without network the cache is served with a warning. A doc id that moved (its project was renamed) is followed once to the new one, said on stderr and cached under the new id; with --json, docId is the id read, requestedDocId the one asked for and movedTo is set. With --json the document carries the content and where it came from; otherwise the content goes to stdout and one status line to stderr.
+Print the llm.txt of a documentation project on docs.klok.dev, the one markdown file with its whole content, read with your GitLab token. Public documentation is read without a token too; documentation that is not public then exits 4 and says that it needs a token. Cached under ~/.cache/klok/docs with the ETag, so a second read is one conditional request; without network the cache is served with a warning. A doc id that moved (its project was renamed) is followed once to the new one, said on stderr and cached under the new id; with --json, docId is the id read, requestedDocId the one asked for and movedTo is set. With --json the document carries the content and where it came from; otherwise the content goes to stdout and one status line to stderr.
 
 | Argument | Description |
 |---|---|
@@ -900,19 +900,47 @@ Print the llm.txt of a documentation project on docs.klok.dev, the one markdown
 klok docs list [options]
 ```
 
-List the documentation projects on docs.klok.dev that your GitLab account may read, from the portal’s index: one line per project, its doc id (what `klok docs read` takes), title and description. With --json the document carries every field of the index.
+List the documentation projects on docs.klok.dev that your GitLab account may read, from the portal’s index: one line per project, its doc id (what `klok docs read` takes), title and description. Without a token it lists the public documentation and says that a token lists more. With --json the document carries every field of the index, and anonymous: true when no token was sent.
 
 | Option | Description |
 |---|---|
 | `--token <token>` | GitLab personal access token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
 
+### klok docs visibility
+
+```
+klok docs visibility [options] [doc-ids...]
+```
+
+Who reads each documentation project of the tenant (--tenant, else the configured one or your login’s), through klok.dev as you (`klok login`): one line per project with the level (public, global, tenant, members or admins) and whether it is the default or set; name doc ids to see only those. With --set <level> or --default it changes the named projects instead: klok.dev checks that you may and commits klok-documentation-settings.json in each documentation project, whose pipeline then publishes the documentation with the new level. Exit 3 when klok.dev refuses every failed change, 1 for any other failure.
+
+| Argument | Description |
+|---|---|
+| `[doc-ids...]` | The documentation projects to show or change, by doc id (default: every project of the tenant) |
+
+| Option | Description |
+|---|---|
+| `--set <level>` | Set the level of the named projects: public, global, tenant, members or admins |
+| `--default` | Go back to the default of each named project (removes its klok-documentation-settings.json) |
+| `--reason <text>` | Why: the body of the commit klok.dev makes |
+
+```
+Documentation is open by default and narrowed only when someone asks for it. The level reaches docs.klok.dev when the
+documentation project's pipeline has published it, not when this command returns.
+
+Examples:
+  klok docs visibility
+  klok docs visibility klok-user-guide klok-framework-klok-common --set global --reason "Every tenant builds on these"
+  klok docs visibility klok-pms --default
+```
+
 ### klok docs id
 
 ```
 klok docs id [options] [path]
 ```
 
-The doc id and documentation identity of a repository path (default: this repository, from CI_PROJECT_PATH or the git remote)
+The doc id and documentation identity of a repository path (default: this repository, from CI_PROJECT_PATH or the git remote): its documentation project, its owning scope and the visibility it has while its documentation project sets none
 
 | Argument | Description |
 |---|---|
@@ -977,7 +1005,7 @@ Publish this repository’s klok-docs/ to the documentation chain (projects not
 klok docs publish [options]
 ```
 
-Build the znai project and upload it under this project’s doc id. When klok-documented-project.json at the repository root says state "retired", unpublish its docId and every previousDocIds entry instead (DELETE with the upload token; 404 counts as done) and upload nothing.
+Build the znai project and upload it under this project’s doc id. The visibility that klok-documentation-settings.json at the repository root sets (public, global, tenant, members or admins) is written into the uploaded meta.json, never into the working tree; without it the portal applies the default of the documented repository’s path, and a level that is not one fails the command before anything is built. When klok-documented-project.json at the repository root says state "retired", unpublish its docId and every previousDocIds entry instead (DELETE with the upload token; 404 counts as done) and upload nothing.
 
 | Option | Description |
 |---|---|
@@ -985,7 +1013,7 @@ Build the znai project and upload it under this project’s doc id. When klok-do
 | `--doc-id <id>` | Publish under this doc id instead of the derived one |
 | `--repo-path <path>` | Repository path to derive from (default: CI_PROJECT_PATH or the git remote) |
 | `--znai <path>` | The znai executable (default: znai on PATH) |
-| `-n, --dry-run` | Resolve what would be published and build it with znai, upload nothing; for a retired project, say what would be unpublished |
+| `-n, --dry-run` | Resolve what would be published, its visibility included, and build it with znai, upload nothing; for a retired project, say what would be unpublished |
 | `--no-build` | With --dry-run: only resolve the plan, do not run znai |
 
 ## klok file-transfer

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

@@ -1,13 +1,14 @@
 ---
 name: klok-docs
-description: Look up Klok platform documentation on docs.klok.dev with `klok docs read <doc-id>` (one markdown file per documentation project, read with your GitLab token) 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.
+description: Look up Klok platform documentation on docs.klok.dev with `klok docs read <doc-id>` (one markdown file per documentation project, read with your GitLab token; public documentation without one) 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 (`/<doc-id>/llm.txt`). The portal
-serves it to a browser session and to a GitLab personal access token, which is what klok-cli sends:
+serves it to a browser session and to a GitLab personal access token, which is what klok-cli sends. Public
+documentation needs no token: without one, klok-cli reads it anonymously and says so.
 
 ```
 klok docs list                       # the projects you may read: doc id, title, description
@@ -18,20 +19,26 @@ klok docs id [tenant/group/.../repo] # the doc id of a repository, this one by d
 ```
 
 `klok docs list` reads the portal's index, so it is where to find the doc id of a project you do not know yet. A
-docs server without the index answers 404; derive the doc id with `klok docs id` instead.
+docs server without the index answers 404; derive the doc id with `klok docs id` instead. Without a token the index
+holds only the public documentation, and the command says that a token lists more.
 
 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. The answer is cached under
 `~/.cache/klok/docs/` with its ETag, so reading a page twice costs one conditional request; without network the
 cached copy is served with a warning.
 
+Who may read a project is its visibility (`public`, `global`, `tenant`, `members` or `admins`;
+`knowledge/platform-rules.md`, *Documentation*). It is set in the documentation project's
+`klok-documentation-settings.json`, and `klok docs visibility` lists it for your tenant.
+
 ## 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`). `klok docs id` derives it.
+`acme-integration-domain-finance-acme-egress-fortnox`. A standalone documentation project of tenant klok,
+`/klok/documentation/<name>`, drops the `klok-` prefix of the name (`klok-integration-strategy-and-tactics`).
+`klok docs id` derives it.
 
 | Need | Doc id |
 |---|---|
@@ -60,8 +67,10 @@ question is about what a project does.
 |---|---|---|
 | the content, `source: server` or `source: cache` | the page as published, or the cached copy | read it |
 | `klok docs read: <old-id> moved to <new-id>` on stderr, then the content | the project was renamed or moved; the content is the new id's | read it, cite the new id (`docId` of `--json`), and fix the link or note the old id came from |
-| exit 4, "No or invalid GitLab token" | no `KLOK_GIT_APIKEY` (or `--token`), or the token is not valid | say so and ask for a token with `read_api`; do not guess |
-| "not a member of the tenant or domain that owns …" (403) | the page exists and your GitLab account may not read it | say so and ask for access; do not guess and do not try another way in |
+| exit 4, "No or invalid GitLab token" | the token sent (`KLOK_GIT_APIKEY` or `--token`) is not valid | say so and ask for a token with `read_api`; do not guess |
+| exit 4, "… is not public documentation, so reading it needs a GitLab token" | no token was sent, and the project is not public | say so and ask for a token with `read_api`; do not guess |
+| "not among the readers of …" (403) | the page exists and its visibility leaves your GitLab account out: another tenant's project that is not global, or one narrowed to its domain's members or to the admins | say so and ask for access, which an owner or admin of the owning tenant or domain gives; do not guess and do not try another way in |
+| `klok docs list` says on stderr "This is the public documentation" | no token was sent, so the list holds the public projects only | set `KLOK_GIT_APIKEY` (`read_api`) to list what your account may read |
 | "… is not published; read the repository's klok-docs/ on main" (404) | the project has no published documentation yet | read the source pages: `git -C <repo> fetch origin && git show origin/main:klok-docs/<page>.md`; `klok-docs/toc-manifest.json` lists them. The generated pages (routes, datamodels, configuration) exist only on the portal |
 | "could not reach …" | no network, and nothing cached | say so |