docs: rewrite README and identity docs for users #62

Merged

claudiomaradonna merged 4 commits from docs/readme-user-guide into master

2026-10-30 18:03:25 +01:00

motoko commented

2026-10-30 17:53:53 +01:00

Collaborator

Why

A user who opens the README to decide whether azkaban fits learns that
it runs three clients in containers, but not why they would want that,
nor which features it has. The quick start assumes a checkout and, read
literally, launches the agent in the azkaban checkout itself. A user
who then wants to set up their own profile finds no walk-through: the
only worked example that fills an identity's home/ is the bot-account
guide, what an identity can customise is spread over three sections, and
nothing says what the container's home keeps after a session.
Dockerfile.azkaban is explained in one dense paragraph without an
example. A documentation audit of the user pages found these gaps; a
separate docs/identities.md was weighed and set aside, since moving
Identities and Accounts would rewrite every link to them.

What changed

The README now opens with the problem azkaban solves: agents working
without approval prompts, kept to a container that sees only the
project, with identities and accounts keeping who acts apart. The quick
start clones over HTTPS, installs, and launches from a project folder. A
Features list, one line each with its link, comes before Usage, and the
Security model follows them; the documentation index keeps only the
pages the features do not link. The macOS link notes that the platform
is not yet verified on a real Mac.

docs/configuration.md defines an identity as who acts and an account
as where a client's login lives, and opens Identities with "Set up the
default identity": a private folder with an env for the API key, a
gitconfig in home/, and a goals.md, followed by a table of what a
launch can customise. Home files now says the home path and user are
fixed by the image and that whatever lies outside the client's state,
the workspace, and writable mounts is gone when the container exits.

docs/custom-images.md says when to choose Dockerfile.azkaban over a
client's own file, names the three client images its FROM can start
from, and shows a minimal file ending with USER 1000.

How to verify

On a Linux host with azkaban installed and no
~/.azkaban/identities/default folder, run the commands of "Set up the
default identity" from the checkout, set ANTHROPIC_API_KEY in the new
env, and run claude . in a project folder. ls -ld ~/.azkaban/identities ~/.azkaban/identities/default shows drwx------
for both; inside the session, git config user.name prints
Ada Example, and the session follows the instruction in goals.md.
After exiting, a file written to ~/ inside the container is absent at
the next launch.

Verify (make lint && .agents/hooks/shellcheck.sh repo && make test)
passes on the tip. The scenario above was not run here, since it needs
a real rootless Podman and an API key.

Considerations

The README's Security model moved below Features and Usage but keeps
its text: it is the only home of the environment-file and
trusted-adapter facts, which docs/development.md links, and its other
passages say what a user does to keep the boundary.

## Why A user who opens the README to decide whether azkaban fits learns that it runs three clients in containers, but not why they would want that, nor which features it has. The quick start assumes a checkout and, read literally, launches the agent in the azkaban checkout itself. A user who then wants to set up their own profile finds no walk-through: the only worked example that fills an identity's `home/` is the bot-account guide, what an identity can customise is spread over three sections, and nothing says what the container's home keeps after a session. `Dockerfile.azkaban` is explained in one dense paragraph without an example. A documentation audit of the user pages found these gaps; a separate `docs/identities.md` was weighed and set aside, since moving Identities and Accounts would rewrite every link to them. ## What changed The README now opens with the problem azkaban solves: agents working without approval prompts, kept to a container that sees only the project, with identities and accounts keeping who acts apart. The quick start clones over HTTPS, installs, and launches from a project folder. A Features list, one line each with its link, comes before Usage, and the Security model follows them; the documentation index keeps only the pages the features do not link. The macOS link notes that the platform is not yet verified on a real Mac. `docs/configuration.md` defines an identity as who acts and an account as where a client's login lives, and opens Identities with "Set up the default identity": a private folder with an `env` for the API key, a gitconfig in `home/`, and a `goals.md`, followed by a table of what a launch can customise. Home files now says the home path and user are fixed by the image and that whatever lies outside the client's state, the workspace, and writable mounts is gone when the container exits. `docs/custom-images.md` says when to choose `Dockerfile.azkaban` over a client's own file, names the three client images its `FROM` can start from, and shows a minimal file ending with `USER 1000`. ## How to verify On a Linux host with azkaban installed and no `~/.azkaban/identities/default` folder, run the commands of "Set up the default identity" from the checkout, set `ANTHROPIC_API_KEY` in the new `env`, and run `claude .` in a project folder. `ls -ld ~/.azkaban/identities ~/.azkaban/identities/default` shows `drwx------` for both; inside the session, `git config user.name` prints `Ada Example`, and the session follows the instruction in `goals.md`. After exiting, a file written to `~/` inside the container is absent at the next launch. Verify (`make lint && .agents/hooks/shellcheck.sh repo && make test`) passes on the tip. The scenario above was not run here, since it needs a real rootless Podman and an API key. ## Considerations The README's Security model moved below Features and Usage but keeps its text: it is the only home of the environment-file and trusted-adapter facts, which `docs/development.md` links, and its other passages say what a user does to keep the boundary.

motoko added 4 commits

2026-10-30 17:53:57 +01:00

chore(agents): upgrade Agent Foundry to 2546ee9 03c1e4f71b

Merge Agent Foundry 0fa0312..2546ee9: the main-checkout guard now
resolves .. and symlinks, later-round reviewers run on sonnet in
Claude Code, fj.md trims its template section, and the templates'
comments are rewrapped. No migration applies.

docs(configuration): guide the default identity setup 55146f1059

Add a walk-through of the default identity's folder with a table of
what an identity customises, define identity and account apart, and
say what the container's home keeps after a session ends.

docs(custom-images): show a Dockerfile.azkaban example 094d86996c

Say when to choose the shared file over a client's own, name the three
client images its FROM can start from, and show a minimal file.

docs(readme): lead with what azkaban solves 432fc58c8d

Say what problem azkaban solves, start the quick start from the clone
and a project folder, list the main features with links, and move usage
ahead of the security model. The documentation index keeps only the
pages the features do not link.