@klok-integration/cli 0.6.245 → 0.7.248

package/README.md

@@ -48,6 +48,7 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agents update [--check] [--global]` | Fetch what moved in the platform and tenant catalogs; `--check` writes nothing and exits 5 when something is outdated. |
 | `klok agents status` | Per file and per catalog: current, outdated, missing or unreachable. |
 | `klok bead list\|show\|report` | Progress beads in the current repository. |
+| `klok docs list` | The documentation projects on docs.klok.dev you may read, by doc id. |
 | `klok docs read <doc-id>` | Print a documentation project's `llm.txt` from docs.klok.dev, read with your GitLab token and cached. |
 | `klok docs id [path]` | The doc id of a repository path. |
 | `klok docs publish` | Build this repository's znai documentation and upload it to the docs portal. |

package/assets/agents/AGENTS.workspace.md

@@ -12,11 +12,18 @@ Before anything else, run `klok agents update --check`. Exit 5 means the install
 run `klok agents update` and read the refreshed files. Exit 0 means they are current, and any other code names
 what went wrong (no token, no network); say so instead of guessing.
 
+On a workstation, `klok sync pull` then brings the workspace current before you read it: it fast-forwards every
+canonical checkout under the workspace root, never merges or resets one, and skips `<root>/worktrees`. It is the one
+sanctioned update of a canonical checkout. A service never clones a repository just to read it: klok.dev and the agent
+read through the GitLab API, docs.klok.dev and the integration context. The `klok-cli` skill says which klok command
+does what.
+
 The platform documentation is published at https://docs.klok.dev, one documentation project per repository, each
 exposing its whole content as one markdown file. Read it with klok-cli, which sends your GitLab token and caches
-the answer:
+the answer. `klok docs list` comes first when you do not know the doc id:
 
 ```
+klok docs list                     # the documentation projects you may read, by doc id
 klok docs read <doc-id>            # the markdown on stdout, one status line on stderr; --json adds fetchedAt
 klok docs id [tenant/group/.../repo]   # the doc id of a repository, this one by default
 ```
@@ -46,7 +53,7 @@ The `klok-docs` skill describes the lookup in detail. Cite the doc id you relied
 
 ## Tenant skills
 
-Next to the platform skills (`klok-docs`, `klok-solution`, `klok-route`, `klok-datamodel`, `klok-release`,
+Next to the platform skills (`klok-docs`, `klok-cli`, `klok-solution`, `klok-route`, `klok-datamodel`, `klok-release`,
 `klok-worktree`) the skill directories hold your tenant's own skills, generated by KlokDocumentationEgress from the
 tenant's documentation publishes and served from the tenant's private catalog. The egress reads only tenant klok's
 publishes today, so another tenant has no tenant skills yet:
@@ -124,8 +131,9 @@ step by step procedure; the contract every agent follows is:
   exists, use a new id; never delete, reset or force reuse it.
 * Leave the canonical checkout's branch, files and uncommitted changes exactly as found. Never run `checkout`,
   `switch`, `pull`, `reset`, `clean`, `stash`, rebase or merge in the canonical checkout or in another session's
-  worktree. Dirty canonical files are not a blocker: a worktree starts from committed history and does not copy
-  uncommitted or ignored files; if the task needs them, ask for an explicit handoff.
+  worktree. The one exception is `klok sync pull`, which only fast-forwards a canonical checkout and reports one it
+  cannot fast-forward. Dirty canonical files are not a blocker: a worktree starts from committed history and does
+  not copy uncommitted or ignored files; if the task needs them, ask for an explicit handoff.
 * Do every edit, build and test in the task worktree, with explicit working directories or `git -C`. Recreate
   dependencies there; do not copy or symlink `.env`, credentials, `node_modules` or build output from another
   checkout. A worktree is not a sandbox: use isolated ports, containers and output directories where parallel

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

@@ -0,0 +1,57 @@
+---
+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.
+---
+
+# The klok command line
+
+`klok` is the Klok platform's command line tool. It reads with your GitLab token (`KLOK_GIT_APIKEY`, or `--token`)
+and your Keycloak login (`klok login`), and every command takes `--json` for one machine-readable document on stdout.
+This page says which command to reach for. `reference.md` next to it lists every command, option and example of this
+CLI version, generated from the program itself; when it is missing (an installer that copies `SKILL.md` only), run
+`klok --help` and `klok <command> --help`.
+
+## When to use what
+
+| You need | Run |
+|---|---|
+| to know the agent instructions and skills are current, at the start of a task | `klok agents update --check` (exit 5: run `klok agents update`) |
+| the local workspace current before you read it | `klok sync pull` |
+| a repository you can see in GitLab but do not have locally | `klok sync clone --dry-run`, then `klok sync clone` |
+| what is dirty, unpushed or behind in the workspace | `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 |
+| 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 solution registry checked against its contract, or against the code | `klok solutions validate`, `klok solutions check` |
+| whether the deployed services run what `main` and the catalog say | `klok fleet status` |
+| the platform catalog's agent assets or its dependents | `klok catalog publish-agents`, `klok catalog release-dependents` (both run in CI) |
+| 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` |
+| the beads of the current repository | `klok bead list`, `klok bead show <id>`, `klok bead report <id>` |
+| 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` |
+
+## The workspace
+
+`klok sync pull` brings the workspace current before you read it: every repository under the workspace root (config
+key `workspace`, `KLOK_GIT_LOCAL_WORKSPACE`, default `~/devklok`) is fetched and fast-forwarded (`git pull
+--ff-only`). It never merges, rebases or resets, so a checkout with local commits or a diverged branch is reported,
+not changed, and `<root>/worktrees` (the task worktrees) is skipped. It is the one sanctioned update of a canonical
+checkout, made on a workstation. Edits still happen in a task worktree (the `klok-worktree` skill). A service never
+clones a repository just to read it: klok.dev and the agent read through the GitLab API, docs.klok.dev and the
+integration context.
+
+## Reading
+
+`klok docs list`, then `klok docs read <doc-id>`, is how to read the platform's documentation; the `klok-docs` skill
+has the doc ids that matter most and what a 401, 403 or 404 means. `klok agent ask` asks Kloker, which reads the
+solution registry, the integration context and the documentation you may read, and answers with links; it is the
+quickest way to find which project, leg or topic handles something.
+
+## Exit codes
+
+`0` ok, `1` error, `2` a task waits for input, `3` denied by policy, `4` not authenticated, `5` outdated (instructions,
+or a deployed service). With `--json`, the document says what happened; messages go to stderr.