docs: settle the audit's remaining findings #58

Merged

claudiomaradonna merged 4 commits from docs/followups into master

2026-10-28 22:17:19 +01:00

motoko commented

2026-10-28 22:15:43 +01:00

Collaborator

Why

The README reorganization set aside five smaller audit findings. In docs/development.md, contributors had to read through the forge runner's setup, which only the publish job's operator needs, and one paragraph opened with an "It" whose subject was in the paragraph before. In docs/bot-accounts.md, the "Your own agent" alternative sat between steps 4 and 5 of the bot procedure. docs/automation.md did not warn supervisors that a launch can spend about a minute pulling and rebuilding before the client starts. The publish script and workflow comments still said hosts "reinstall" their clients, although since 2119fc0 they rebuild them at launch.

What changed

The registry, runner, secret, and QEMU setup now live in a new docs/publishing.md for whoever forks the repository or runs the publish job. Development's Published images keeps the <registry> definition and links there, and so does the README's document list. The release-gate paragraph now reads as one.

"Your own agent" comes after the bot procedure, under the same anchor. It links back to the steps it reuses, and the step that mentions AZKABAN_SSH_AGENT=host links to it.

The Headless contract says that on Linux amd64 and arm64 the pull and a rebuild can delay the client's start by about a minute, and that AZKABAN_AUTO_PULL=0 skips them, linking to Updates.

The publish script and workflow comments say hosts rebuild their clients at launch. Only comments change, with no change to behavior.

How to verify

From a fresh checkout of the branch, open docs/development.md § Published images and follow the link to Publishing. It holds the runner, REGISTRY_TOKEN, and QEMU setup that master keeps inline. In docs/bot-accounts.md, steps 1 to 9 now run without interruption, and the #your-own-agent links from the README and docs/configuration.md still land on that section.

Verify (make lint && .agents/hooks/shellcheck.sh repo && make test) passes on the tip, and a local check of every relative link and anchor finds none broken. The publish job itself was not run, since it needs the forge runner.

Considerations

prettier --check docs/development.md already fails on master in the "Tests live in two level folders" paragraph, which this change leaves as it is.

## Why The README reorganization set aside five smaller audit findings. In `docs/development.md`, contributors had to read through the forge runner's setup, which only the publish job's operator needs, and one paragraph opened with an "It" whose subject was in the paragraph before. In `docs/bot-accounts.md`, the "Your own agent" alternative sat between steps 4 and 5 of the bot procedure. `docs/automation.md` did not warn supervisors that a launch can spend about a minute pulling and rebuilding before the client starts. The publish script and workflow comments still said hosts "reinstall" their clients, although since 2119fc0 they rebuild them at launch. ## What changed The registry, runner, secret, and QEMU setup now live in a new `docs/publishing.md` for whoever forks the repository or runs the publish job. Development's Published images keeps the `<registry>` definition and links there, and so does the README's document list. The release-gate paragraph now reads as one. "Your own agent" comes after the bot procedure, under the same anchor. It links back to the steps it reuses, and the step that mentions `AZKABAN_SSH_AGENT=host` links to it. The Headless contract says that on Linux amd64 and arm64 the pull and a rebuild can delay the client's start by about a minute, and that `AZKABAN_AUTO_PULL=0` skips them, linking to Updates. The publish script and workflow comments say hosts rebuild their clients at launch. Only comments change, with no change to behavior. ## How to verify From a fresh checkout of the branch, open `docs/development.md` § Published images and follow the link to Publishing. It holds the runner, `REGISTRY_TOKEN`, and QEMU setup that `master` keeps inline. In `docs/bot-accounts.md`, steps 1 to 9 now run without interruption, and the `#your-own-agent` links from the README and `docs/configuration.md` still land on that section. Verify (`make lint && .agents/hooks/shellcheck.sh repo && make test`) passes on the tip, and a local check of every relative link and anchor finds none broken. The publish job itself was not run, since it needs the forge runner. ## Considerations `prettier --check docs/development.md` already fails on `master` in the "Tests live in two level folders" paragraph, which this change leaves as it is.

motoko added 4 commits

2026-10-28 22:15:46 +01:00