@klok-integration/cli 0.7.327 → 0.9.345

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

@@ -32,9 +32,12 @@ Examples:
   klok agent ask "Which legs consume InvoiceV1?"
   klok agent ask "..." --json | jq .task.resultSummary
   klok agent impact InvoiceV1 --change major --json
+  klok agent plan --change acme/integration-solutions#12
   klok agent plan KLK001 --change-request change.md
+  klok change show acme/integration-solutions#12
   klok agent serve
-  klok bead report fortnox-egress-1 --status done --message "Merged MR !12"
+  klok bead claim issue-4-route
+  klok bead done issue-4-route --merge-request https://git.klok.dev/acme/r/-/merge_requests/12
   klok code                       # the bundled terminal agent: tools in src/klokcode/, MCP from klokcode.jsonc
   klok agents init                # KLOK-AGENTS.md, harness rows, platform and tenant skills, the session hook
   klok agents update              # fetch the platform and tenant catalogs, write what moved, prune by marker
@@ -186,21 +189,33 @@ Impact analysis for a node id or datamodel name
 ### klok agent plan
 
 ```
-klok agent plan [options] <solutionKey>
+klok agent plan [options] [solutionKey]
 ```
 
-Plan a solution change from a change request file (or - for stdin)
+Plan a change request into its solution document and one issue manifest, delivered as the design merge request (--change), or a change written in a file (--change-request)
 
 | Argument | Description |
 |---|---|
-| `<solutionKey>` | required |
+| `[solutionKey]` | optional |
 
 | Option | Description |
 |---|---|
+| `--change <ref>` | The change request, <registry path>#<iid>; its issue, comments and questions are read |
 | `--change-request <file>` | Path to the change request text, or - for stdin |
 | `--answer <questionId=text...>` | Clarification answers |
+| `--git-url <url>` | GitLab base URL, to read the solution of --change (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token, to read the solution of --change (default: KLOK_GIT_APIKEY, then config klokApiKey) |
 | `--no-wait` | Create the task and return immediately |
 
+```
+With --change, the solution is the change request's label solution:<KEY> unless [solutionKey] names it, and the plan
+goes onto the change request's open design merge request when it has one.
+
+Examples:
+  klok agent plan --change acme/integration-solutions#12
+  klok agent plan KLK001 --change-request change.md
+```
+
 ### klok agent implement
 
 ```
@@ -323,6 +338,80 @@ Print one bead
 |---|---|
 | `<beadId>` | required |
 
+### klok bead claim
+
+```
+klok bead claim [options] <beadId>
+```
+
+Take a bead before you start on it: report it in_progress to klok.dev, without changing its file
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--message <text>` | What you are about to do |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+| `--force` | Claim it even though someone else holds it unfinished |
+
+```
+The agent service refuses the claim (409) when someone else holds the bead unfinished (in_progress or needs_review)
+in klok.dev; --force takes it anyway, so agree with them first.
+
+Examples:
+  klok bead claim issue-4-route
+  klok bead claim issue-4-route --message "Mapping the currency first"
+```
+
+### klok bead done
+
+```
+klok bead done [options] <beadId>
+```
+
+Set a bead to done in its file, for the merge request that implements it, and report the merge request
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--merge-request <url>` | The merge request that implements the bead |
+| `--message <text>` | What the merge request does |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+| `--local-only` | Update the bead file without reporting to klok.dev |
+
+```
+A bead is done when the merge request that implements it merges: commit the changed bead file in that merge request.
+klok.dev shows the bead needs_review until then.
+
+Examples:
+  klok bead done issue-4-route --merge-request https://git.klok.dev/acme/integration/domain/finance/acme-fortnox-egress/-/merge_requests/7
+```
+
+### klok bead release
+
+```
+klok bead release [options] <beadId>
+```
+
+Let a bead go: report it open to klok.dev, so someone else or Kloker can take it
+
+| Argument | Description |
+|---|---|
+| `<beadId>` | required |
+
+| Option | Description |
+|---|---|
+| `--message <text>` | Why you let it go |
+| `--by <name>` | Reporter name; defaults to the logged-in user |
+| `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
+
 ### klok bead report
 
 ```
@@ -339,10 +428,46 @@ Append progress to a bead and report it to klok.dev
 |---|---|
 | `--status <status>` | open \| blocked \| in_progress \| needs_review \| done \| cancelled |
 | `--message <text>` | What happened |
+| `--merge-request <url>` | The merge request of the work |
 | `--by <name>` | Reporter name; defaults to the logged-in user |
 | `--repo-path <path>` | GitLab project path, when it cannot be derived from the origin remote |
 | `--local-only` | Update the bead file without reporting to klok.dev |
 
+## klok change
+
+```
+klok change [options] [command]
+```
+
+Change requests: an issue in the solution registry, and the questions, design and issues linked to it
+
+### klok change show
+
+```
+klok change show [options] <target>
+```
+
+Print a change request, read from GitLab: its comments, questions, status, design merge requests and implementation issues with who builds each
+
+| Argument | Description |
+|---|---|
+| `<target>` | required |
+
+| Option | Description |
+|---|---|
+| `--git-url <url>` | GitLab base URL (default: config gitUrl) |
+| `--token <token>` | GitLab personal access token with read_api (default: KLOK_GIT_APIKEY, then config klokApiKey) |
+
+```
+<target> is the change request (<registry path>#<iid>), the URL of its issue, or the URL of an implementation issue,
+whose footer names its change request.
+
+Examples:
+  klok change show acme/integration-solutions#12
+  klok change show https://git.klok.dev/acme/integration/domain/finance/acme-fortnox-egress/-/issues/4
+  klok change show acme/integration-solutions#12 --json | jq '.changeRequest.implementationIssues'
+```
+
 ## klok agents
 
 ```
@@ -757,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 |
 |---|---|
@@ -775,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 |
 |---|---|
@@ -852,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 |
 |---|---|
@@ -860,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 |
 

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

@@ -71,6 +71,15 @@ shared platform service) in `klok/integration-solutions`.
     carries `planned` in the Status column of its table row; `klok solutions check` relies on it. After the merges,
     run `klok solutions check` again.
 
+## Working on a change request
+
+A change often arrives as a change request: an issue in `<tenant>/integration-solutions` labelled `change-request`.
+How it becomes one design merge request with its plan under `changes/<iid>/`, implementation issues that Kloker or a
+developer builds, and beads that are done when their merge request merges, is in `knowledge/platform-rules.md`,
+*Changes and work*, next to `KLOK-AGENTS.md`. Read the change request with its comments and its linked `question`
+issues before step 3, and mention it (`Refs <registry>#<iid>`) in the merge request that brings the document to the new
+steady state.
+
 ## Maintenance is the same process
 
 * A fix or a change in one route starts at step 1: find its solution and read it before touching the code.