docs: split the README into an entry point and docs/ #57

Merged

claudiomaradonna merged 4 commits from docs/reorganize-readme into master

2026-10-28 22:01:41 +01:00

claudiomaradonna commented

2026-10-28 22:00:48 +01:00

Owner

Why

The README took about 24 minutes to read, while the project's writing rule asks five to eight. A newcomer had to get through configuration, custom images, and macOS details before learning how to try azkaban. Facts about shared state were repeated four times, and some answers were missing entirely: the fixed 512-process limit, how to update, and that OpenCode has not passed its release gate. A documentation audit found these, and the owner chose a README limited to what the project does, a quick start, the essentials with links, and the license. Two alternatives were set aside: the audit's narrower split, which leaves the README around 2,200 words, and a single docs/usage.md, which would only move the length elsewhere.

What changed

The README is now about 900 words: what azkaban does, a quick start (install one client, PATH, first launch in a folder holding nothing the agent must not read), the security model, usage with the options table, an index of the documents, and the license. The details moved by topic, largely word for word, into docs/installation.md (prerequisites, install, a new Updates section), docs/configuration.md (state, accounts, identities, environment, mounts, MCP, nested sandboxes, dry run), docs/custom-images.md, docs/macos.md, and docs/troubleshooting.md. Every link and examples/ reference into the old README sections points to the new homes.

Repeated passages now have a single home: account and state sharing, the local-base procedure, the client release gate, and the image cleanup commands.

Readers now find the 512-process limit (Security model and Troubleshooting), how to update azkaban and the clients (Updates), and OpenCode's release status (Install).

AGENTS.md's Architecture names containers/Dockerfile and the publish workflow and script, linking to Published images. No behavior or code changes.

How to verify

From a fresh checkout of the branch, open README.md. It reads in a few minutes, and each section ends with a link to the docs/ document holding the detail. Follow the links in the Documentation section, then those from docs/automation.md, docs/bot-accounts.md, and examples/env.azkaban.example. Each one lands on an existing heading. On master, the same content sits in one 24-minute README.

Verify (make lint && .agents/hooks/shellcheck.sh repo && make test) passes on the tip, as does prettier --check on README.md and the docs/ files this change touches. A local link check covering every relative link and anchor in README.md, AGENTS.md, docs/, and the examples/ references finds none broken. macOS behavior was not tried, for lack of a Mac.

Considerations

prettier --check AGENTS.md already fails on master, at the Quality gates line, which this change leaves as it is. One low review finding was set aside as a later-round wording issue: in Updates, the image cleanup sentence could put each platform first.

## Why The README took about 24 minutes to read, while the project's writing rule asks five to eight. A newcomer had to get through configuration, custom images, and macOS details before learning how to try azkaban. Facts about shared state were repeated four times, and some answers were missing entirely: the fixed 512-process limit, how to update, and that OpenCode has not passed its release gate. A documentation audit found these, and the owner chose a README limited to what the project does, a quick start, the essentials with links, and the license. Two alternatives were set aside: the audit's narrower split, which leaves the README around 2,200 words, and a single `docs/usage.md`, which would only move the length elsewhere. ## What changed The README is now about 900 words: what azkaban does, a quick start (install one client, `PATH`, first launch in a folder holding nothing the agent must not read), the security model, usage with the options table, an index of the documents, and the license. The details moved by topic, largely word for word, into `docs/installation.md` (prerequisites, install, a new Updates section), `docs/configuration.md` (state, accounts, identities, environment, mounts, MCP, nested sandboxes, dry run), `docs/custom-images.md`, `docs/macos.md`, and `docs/troubleshooting.md`. Every link and `examples/` reference into the old README sections points to the new homes. Repeated passages now have a single home: account and state sharing, the local-base procedure, the client release gate, and the image cleanup commands. Readers now find the 512-process limit (Security model and Troubleshooting), how to update azkaban and the clients (Updates), and OpenCode's release status (Install). `AGENTS.md`'s Architecture names `containers/Dockerfile` and the publish workflow and script, linking to Published images. No behavior or code changes. ## How to verify From a fresh checkout of the branch, open `README.md`. It reads in a few minutes, and each section ends with a link to the `docs/` document holding the detail. Follow the links in the Documentation section, then those from `docs/automation.md`, `docs/bot-accounts.md`, and `examples/env.azkaban.example`. Each one lands on an existing heading. On `master`, the same content sits in one 24-minute README. Verify (`make lint && .agents/hooks/shellcheck.sh repo && make test`) passes on the tip, as does `prettier --check` on `README.md` and the `docs/` files this change touches. A local link check covering every relative link and anchor in `README.md`, `AGENTS.md`, `docs/`, and the `examples/` references finds none broken. macOS behavior was not tried, for lack of a Mac. ## Considerations `prettier --check AGENTS.md` already fails on `master`, at the Quality gates line, which this change leaves as it is. One low review finding was set aside as a later-round wording issue: in Updates, the image cleanup sentence could put each platform first.

claudiomaradonna added 4 commits

2026-10-28 22:00:51 +01:00

docs: split the README into an entry point and docs/ d411c44cc2

The README took about 24 minutes to read. It now holds what azkaban
does, a quick start, the security model, usage, an index of the
documents, and the license. Installation and updates, configuration,
custom images, macOS, and troubleshooting each move to a document of
their own under docs/, with the duplicated account and local-base
passages removed and every link and example reference repointed.

docs: add the process limit, updates, and OpenCode status dccf76a8e8

docs(adding-a-client): state the release gate once aa354b912d

docs(agents): name the publish pipeline in Architecture e2dc08dbca