@klok-integration/cli 0.3.1 → 0.3.3

package/assets/agents/AGENTS.documentation.md

@@ -15,5 +15,5 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (docs sync) fo
   `klok/environment/build-ci-templates:/klok-docs-publish.yml` and nothing else; the job is `klok docs publish`.
 * Visibility follows `meta.json` `scope` (`global`, `tenant`, `domain`, `system`); a page that must not be seen by
   another domain belongs in a project with that scope, not behind a note.
-* Preview locally with `znai --source-root docs --preview`, and check what a publish would do with
+* 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

@@ -111,8 +111,10 @@ step by step procedure; the contract every agent follows is:
   tenant with the right to create projects in the domain. That is the supported path and it provisions what the
   project needs to build. Creating a project by hand is a legitimate fallback under *Git är sanningen*, but it is
   not the normal path: say up front what a human will still have to do, rather than letting it surface as a red
-  pipeline. Today that always includes the Vault CI role `<tenant>-ci-project-<gitlab id>`, which needs both
-  `default` and the tenant CI read policy; see `klok/application/frontend-klok-dev` issue #7.
+  pipeline. Vault needs nothing per project: the tenant CI role `<tenant>-ci` accepts every project under the
+  tenant's root group. A tenant without it fails every job at `auth/jwt/login` with
+  `role "<tenant>-ci" could not be found`; setting a tenant up is described in `klok-docs/ci/tenant-onboarding.md`
+  of `klok/environment/build-ci-templates`.
 * Never push to `main` of an existing repository, never force push, never merge. Work on a branch and open a
   merge request that is ready for review; only a brand new repository gets its first commit on `main`. A draft
   merge request is not the default, it is what you open when the work is knowingly unfinished, and you say why.
@@ -152,8 +154,9 @@ step by step procedure; the contract every agent follows is:
 
 Klok documentation has three levels, and a change is finished only when all three have been considered:
 
-* **The repository's own `klok-docs/`** (znai markdown, `toc-manifest.json`), which the CI mirrors into the
-  repository's documentation project. A change that adds or alters a route, a datamodel, a configuration key, a
+* **The repository's own `klok-docs/`** (znai markdown, `toc-manifest.json`), which KlokDocumentationEgress merges
+  with the pages it generates from the code into the repository's documentation project on every `main` pipeline.
+  That documentation project is output: never edit it; what is generated is set by tenant admins in klok.dev. A change that adds or alters a route, a datamodel, a configuration key, a
   CI job, a command or a decision updates `klok-docs/` in the same merge request.
 
   `klok-docs/` has to answer **two different questions**, and a repository that answers only the first is not
@@ -198,12 +201,11 @@ Klok documentation has three levels, and a change is finished only when all thre
 ### After the merge
 
 The pipeline on `main` publishes the project's documentation payload (`KlokProjectDocumentationV1`: routes,
-sources, configuration keys and the whole `klok-docs/` folder with a hash per file). A documentation flow that
-reads that payload together with the merge request description and the diff, and proposes the central updates as
-merge requests for a human to review, is being built; until it runs, nothing behind you looks at the central
-documentation. Either way the steps above are the ones that matter: an author who knows what changed writes
-better documentation than a flow that reads the diff afterwards, and a proposal is a safety net for what was
-missed, never a reason to skip writing it.
+sources, configuration keys and the whole `klok-docs/` folder with a hash per file). KlokDocumentationEgress
+(`klok/integration/klok-documentation-egress`) turns it into the project's published documentation: your
+`klok-docs/` pages as written, with `KLOK:GENERATED` regions filled, next to generated pages for routes,
+datamodels and configuration. Nothing behind you updates the central platform documentation, so the steps above
+are the ones that matter.
 
 ## How to work
 

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

@@ -26,9 +26,9 @@ https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt (datamodel pip
    (`klok-datamodel-project.json`, `klok-template.json`, the agent instruction files, the three page
    `klok-docs/datamodel/` layout).
 
-   A hand created project has **no Vault CI role**, so its first `publish_java_projects` fails with
-   `role "<tenant>-ci-project-<id>" could not be found`. Say that up front and give the user the command; see
-   the `klok-release` skill.
+   Vault needs nothing per project: the tenant CI role `<tenant>-ci` accepts every project under the tenant's
+   root group. If `publish_java_projects` fails at `auth/jwt/login`, the tenant itself is not set up; see the
+   `klok-release` skill.
 2. Write the XSD under `schema-definition-xsd/`: single `xs:` prefix, `targetNamespace` with `xmlns:tns`,
    `elementFormDefault="qualified"`, one root element `<Name>_vN` that references every complex type. Enumerations
    as `xs:enumeration`.

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

@@ -40,17 +40,19 @@ letting them surface as a red pipeline.
 
 ## Setting up a new project (what must exist)
 
-* Vault JWT role `<tenant>-ci-project-<gitlab id>` bound to that `project_id`, carrying **both** `default` and
-  the tenant CI read policy (`klok-cicd-read` for tenant `klok`). A role with only `default` authenticates but
-  cannot read the shared secrets, and `publish` still fails — that is why the pipelines of projects 175 and 191
-  were red for months. Without any role at all the job fails at `auth/jwt/login` with
-  `role "<tenant>-ci-project-<id>" could not be found`.
+* Nothing in Vault per project. Every job logs in with the tenant CI role `<tenant>-ci` (a Vault JWT role bound
+  to `namespace_path` `<tenant>` and `<tenant>/*`, carrying `default` and the tenant CI read policy
+  `<tenant>-cicd-read`). The templates set `VAULT_AUTH_ROLE: $KLOK_TENANT-ci`. A tenant without the role fails
+  every job at `auth/jwt/login` with `role "<tenant>-ci" could not be found`; the tenant setup is in
+  `klok-docs/ci/tenant-onboarding.md` of `klok/environment/build-ci-templates`, every credential and the step
+  that uses it in `klok-docs/ci/authentication.md` there.
 * For anything the pipeline resolves from a package registry (framework, plugin, datamodels): the project's
   top-level group must be on the package project's job token allowlist.
 * For a deployed service: a manifest under `klok/integration/<name>/`, the Kubernetes service account, a Vault
   Kubernetes role `<name>-role` with a policy reading `secret/data/<tenant>/integration/<name>/env`, and the env
   secret itself (broker credentials, service specific keys).
-* Documentation projects need the tenant's docs upload client in Keycloak and in Vault (`secret/<tenant>`).
+* Documentation projects need the tenant's docs upload client: Keycloak client `klok-docs-upload-<tenant>` and its
+  id and secret in `secret/<tenant>/common/repo/cicd-environment-variables`.
 
 Vault is changed by humans only: propose the exact `vault write` / `vault policy write` command with every existing
 field, and let the user run it.
@@ -59,8 +61,9 @@ field, and let the user run it.
 
 | Symptom | Cause |
 |---|---|
-| `role "<tenant>-ci-project-<id>" could not be found` at `auth/jwt/login` | no Vault CI role for the project; it was created without provisioning |
-| `permission denied` reading `secret/.../cicd-environment-variables` | CI role exists but lacks the tenant CI read policy (has only `default`) |
+| `role "<tenant>-ci" could not be found` at `auth/jwt/login` | the tenant has no CI role yet (tenant onboarding) |
+| `claim "namespace_path" does not match` at `auth/jwt/login` | the project is outside the tenant's root group, or `VAULT_AUTH_ROLE` names another tenant's role |
+| `permission denied` reading `secret/.../cicd-environment-variables` | the CI role lacks the tenant CI read policy (has only `default`) |
 | `403` on `groups/<tenant>/-/packages/maven/...` | job token allowlist of the package project lacks the reader's group |
 | `Could not find dev.klok...:<version>` | the version is not published yet, or the catalog copy is stale (`updateKlokLibsToml`) |
 | `already deployed` from JReleaser | Maven Central already has that version; a `main` build is a new timestamp, do not retry the same job |