@klok-integration/cli 0.2.0 → 0.3.2

package/README.md

@@ -43,6 +43,7 @@ Credentials are written to `~/.config/klok/credentials.json` with mode 0600.
 | `klok agents init` | Write the Klok agent instructions and skills into a repository. |
 | `klok bead list\|show\|report` | Progress beads in the current repository. |
 | `klok docs publish` | Build this repository's znai documentation and upload it to the docs portal. |
+| `klok manifest update` | Set a container's image in a deploy manifest of your GitOps repository, then commit and push. |
 | `klok sync clone\|pull\|status` | Clone and refresh every repository you can see, in one workspace folder. |
 
 Global flags: `--json`, `--no-tui`, `--stream`, `--tenant <slug>`, `--domain <slug>`,

package/THIRD-PARTY-NOTICES.md

@@ -403,29 +403,7 @@ THE SOFTWARE.
 
 Licence: MIT — https://github.com/TehShrike/deepmerge
 
-```
-The MIT License (MIT)
-
-Copyright (c) 2012 James Halliday, Josh Duff, and other contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-```
+_No licence file shipped with the package; see the project homepage._
 
 ## default-browser@5.5.1
 
@@ -1221,6 +1199,26 @@ The above copyright notice and this permission notice shall be included in all c
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## yaml@2.9.1
+
+Licence: ISC — https://eemeli.org/yaml/
+
+```
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+```
+
 ## yoga-layout@3.2.1
 
 Licence: MIT — https://yogalayout.dev/

package/assets/agents/AGENTS.application.md

@@ -14,4 +14,8 @@ repository's own `README.md` and `docs/` for its architecture.
 * Tenant, domain and role separation is enforced on the server side; never rely on the UI hiding something.
 * Secrets and environment configuration come from the Vault env secret of the deployment, never from committed
   files.
+* Each image is built by a job that includes `klok-image-build.yml` from `klok/environment/build-ci-templates` and
+  `extends: .klok_image_build`, never by a copied kaniko or Docker job. In the Dockerfile, production dependencies,
+  `public/` or other assets, and the build output are separate `COPY --chown` layers; large data such as model
+  weights stays out of the image or gets a layer of its own.
 * Update `klok-docs/` (or `docs/`) with every change of behaviour, API or configuration.

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.integration.md

@@ -31,3 +31,6 @@ needs. Read https://docs.klok.dev/klok-framework-klok-quarkus-extension/llm.txt
   Vault env secret provides in Kubernetes (`KLOK_BROKER_AUTH_CLIENT_ID`, ...).
 * Update `klok-docs/` (overview, design decisions, routes, operations) in the same merge request as the change.
 * On `main` the pipeline builds the image, updates the deployment manifest and syncs the documentation; check it.
+* The `Dockerfile` copies `build/quarkus-app/lib/` in a `COPY` of its own before `quarkus-run.jar`, `quarkus/`
+  and `app/`, all with `COPY --chown`, never `COPY build/quarkus-app/ .` followed by `RUN chown -R`, which stores
+  every dependency twice in every build.

package/assets/agents/AGENTS.workspace.md

@@ -98,6 +98,13 @@ step by step procedure; the contract every agent follows is:
 * After every push to git.klok.dev, check the pipeline (`glab api "projects/<id>/pipelines?per_page=3"`, job traces)
   and fix failures before moving on. Publishing, image pushes, manifest updates and catalog updates only happen on
   `main`; merge request pipelines build and test.
+* Container images are built without privileges, always. Every image job extends `.klok_image_build` from
+  `klok/environment/build-ci-templates` (`klok-image-build.yml`): kaniko in an ordinary container, reproducible
+  layers, no layer cache, push from `main` only. Never use or propose a privileged runner, `docker:dind`, or a
+  relaxed seccomp or AppArmor profile. A Dockerfile copies dependencies, assets and application code as separate
+  `COPY` layers and sets owners with `COPY --chown`, never `RUN chown -R`, so that a build stores only what
+  changed. Read the *Container images* page of https://docs.klok.dev/klok-environment-build-ci-templates/llm.txt
+  before changing a Dockerfile or an image job.
 * Vault (`vault.ipaas.se`) is changed by a human only. Agents may read to diagnose and must then propose the exact
   command, including every existing field of the object.
 * New projects are created through klok.dev, or through the agent at https://agent.klok.dev authenticated as the
@@ -148,6 +155,24 @@ Klok documentation has three levels, and a change is finished only when all thre
 * **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
   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
+  documented:
+
+  1. **Why it is built this way.** The design decisions, what was weighed against what, and the invariants that
+     must not be broken. This is the kind everyone remembers to write.
+  2. **How each role is meant to use it.** One guide per audience the product actually has — for a ticketing
+     product that is platform administrator, organizer, exhibitor and buyer; for an integration it may be the
+     operator and the consuming team. Write it as a walk through the real flow, naming the pages and commands a
+     person will actually touch. This is the kind that gets forgotten, and it is the kind a new colleague reads
+     first.
+
+  Write both **as the work happens**, not at the end of the branch. By the end nobody remembers why a choice was
+  made, and a guide written from memory describes the product somebody meant to build.
+
+  Keep `klok-docs/` as the single copy. Do not mirror a page into a second `docs/` folder: two copies of one page
+  are two pages that quietly stop agreeing. `docs/` may hold what is genuinely not product documentation, such as
+  a strategy document that predates the code.
 * **The platform documentation** under `<tenant>/documentation/`: the user guide (`klok-user-guide`), strategy
   and tactics (`klok-integration-strategy-and-tactics`) and the framework, CI and tooling documentation. They
   describe how the platform is used and why. A change that alters a rule, a convention, a workflow, a command or
@@ -157,8 +182,9 @@ Klok documentation has three levels, and a change is finished only when all thre
 
 ### Before the merge request
 
-1. Update the repository's `klok-docs/` in the same merge request as the change. Documentation that is promised
-   for a later merge request is documentation that never arrives.
+1. Update the repository's `klok-docs/` in the same merge request as the change — ideally in the same commit as
+   the code it describes. Documentation that is promised for a later merge request is documentation that never
+   arrives, and a final "docs" commit at the end of a branch is the same promise wearing a hat.
 2. Ask what a reader of the platform documentation would now find wrong: a renamed command, a new rule, a changed
    default, a workflow with one more step. Read the affected pages (`https://docs.klok.dev/<doc-id>/llm.txt`)
    instead of guessing what they say.