claudiomaradonna/azkaban
1
1
Fork 0
Code Issues Pull requests Activity

docs: reorganize the README around its readers #37

Merged
claudiomaradonna merged 6 commits from docs/reorganize-readme into master 2026-10-07 21:22:52 +02:00
Conversation 0 Commits 6 Files changed 8 +539 -528
motoko commented 2026-10-07 21:21:58 +02:00
Collaborator
Copy link

Why

The README had grown to 843 lines serving five readers at once: someone
installing azkaban, a bot operator, a supervisor author, and contributors.
First-run login sat after about 450 lines of bot, headless, and build
material, and Identities was the last subsection of the bot runbook,
although every launch runs as one.

What changed

  • The README follows the person who installs and runs azkaban: what the
    images ship, security model, prerequisites with the Mac setup, install,
    commands and options, one Authentication and state section, Identities,
    configuration, mounts, MCP, custom images, dry run, macOS, troubleshooting.
  • The bot-account runbook, the headless contract, and the contributor
    material move to docs/bot-accounts.md, docs/automation.md, and
    docs/development.md.
  • Fixes: the env files' dropped host-side names are documented,
    contributor docs link the Verify command instead of a partial list,
    collection counts and repeated warnings are gone, and the example
    comments and adapter guide lose stale wording.
  • Anchors of moved README sections, such as #headless-contract, now
    live on the new pages.

Verification

  • make lint && .agents/hooks/shellcheck.sh repo && make test: 33 shell
    files clean, 304 tests, 0 failures.
  • prettier --check README.md docs/*.md passes; every relative link and
    anchor resolves.
## Why The README had grown to 843 lines serving five readers at once: someone installing azkaban, a bot operator, a supervisor author, and contributors. First-run login sat after about 450 lines of bot, headless, and build material, and Identities was the last subsection of the bot runbook, although every launch runs as one. ## What changed - The README follows the person who installs and runs azkaban: what the images ship, security model, prerequisites with the Mac setup, install, commands and options, one Authentication and state section, Identities, configuration, mounts, MCP, custom images, dry run, macOS, troubleshooting. - The bot-account runbook, the headless contract, and the contributor material move to `docs/bot-accounts.md`, `docs/automation.md`, and `docs/development.md`. - Fixes: the env files' dropped host-side names are documented, contributor docs link the Verify command instead of a partial list, collection counts and repeated warnings are gone, and the example comments and adapter guide lose stale wording. - Anchors of moved README sections, such as `#headless-contract`, now live on the new pages. ## Verification - `make lint && .agents/hooks/shellcheck.sh repo && make test`: 33 shell files clean, 304 tests, 0 failures. - `prettier --check README.md docs/*.md` passes; every relative link and anchor resolves. 
Fix what the documentation audit confirmed against the code before the
README is reorganized, so the moves that follow carry correct text.

- Name the variables the launcher drops from the env files: host-side
  names and the client's workspace marker (bin/azkaban); "Safe keys"
  was never defined.
- Point contributors at the Verify command in AGENTS.md, which also
  runs .agents/hooks/shellcheck.sh repo, instead of a partial list.
- Replace counts of clients, adapters, and targets.
- Drop the OpenCode run --auto repeat; the Security model and the
  command examples hold it.
- Reword the adapter guide positively and drop "common environment
  layers", a concept removed with the shared env files.
- examples: every other client's key is dropped, not "the other";
  OpenCode's example shows an ordinary variable instead of one the
  image already sets.
The README served the bot operator inline, and Identities sat as the
last subsection of that runbook although every launch runs as one.

docs/bot-accounts.md now holds the setup steps, operations, and a
Several bots section with the roles, the account per role, and the
watcher/coder example. The README gains Identities as a section of its
own before Environment configuration, opening with what an identity
is; the folder tree points at the new page instead of step numbers.
The example comments name the page that now holds the steps.
Supervisor authors read the guarantees for headless runs; the person
installing and running azkaban does not need them inline.

docs/automation.md holds the contract, the cidfile rules, and the
fresh-workspace-per-job advice that sat in Identities. The README
points supervisors at the page after the options table. The stdout
guarantee links to the README's Dry run, which stays the home of
dry-run output.
The README carried the dispatcher internals, the make image targets,
and the check commands for contributors between its user sections.

docs/development.md holds the runtime layout, separate image builds,
and verification, which now links to the Test and Verify commands in
AGENTS.md instead of a partial copy. The entrypoint paragraph is not
carried over: it repeated the Security model. The README keeps a
one-sentence note on how the commands reach the dispatcher, links the
image builds from Install, and ends with a short Development pointer;
the adapter guide links the new page.
The README now follows a new user's questions: what azkaban is and what
its images ship, the security model, prerequisites with the Mac setup
before install, commands and options, then logging in.

- The image contents move from Prerequisites to the intro.
- The Podman machine setup joins Prerequisites as macOS setup; the
  remaining Mac differences become prose in a macOS section after Dry
  run.
- The three per-client authentication sections become one
  Authentication and state section placed after the options. One
  paragraph states for every client that state is shared across the
  identity's workspaces; Codex lacked it before.
- MCP binaries follow mounts, and Custom images precede Dry run.
The change review and the documentation audit of the branch found
context lost in the moves and a few imprecise new sentences.

- Identities opens with what an identity is without calling every
  identity a bot or implying a folder; the identity line says it is
  printed on standard error, which the runbook used to introduce.
- Per-identity state keeps only what Authentication and state lacks.
- The real-Mac caveat precedes the Mac setup, and the host's Git 2.48
  requirement is back in Prerequisites.
- The Several bots example links the separate-checkouts rule, and the
  headless page states the fresh-workspace advice as advice.
- The adapter guide drops a repeat of where adapters load, keeps that
  hooks add only their state mounts to the launch command, says where
  a client's state and login docs go, and drops an undefined "safe"
  and a negative restatement.
claudiomaradonna deleted branch docs/reorganize-readme 2026-10-07 21:22:55 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
claudiomaradonna/azkaban!37
No description provided.