docs: align the documents with the code #71

Merged

claudiomaradonna merged 3 commits from docs/align-with-code into master

2026-11-11 15:06:05 +01:00

motoko commented

2026-11-11 14:40:07 +01:00

Collaborator

Why

The README and docs/ tell users how to launch a client in its
container and contributors how to work on the launcher. An audit of
them against the code found the commands, options, and links right, and
a few passages wrong or silent.

The one that matters most: the README said the first argument is the
workspace. When that argument is not an existing folder, the launcher
passes it to the client and mounts the current directory instead,
asking first on a terminal and unasked otherwise, so a mistyped folder
exposes the whole current directory to the container.

The rest are smaller: the shared env example lacked one control, two
sentences of docs/configuration.md contradicted the code, several
rules the launcher enforces were stated nowhere, two installer errors
had no troubleshooting entry, and two facts had more than one home.

What changed

A user reading Usage now learns what happens to a first argument that
is not a folder, and docs/automation.md points a script author to it.

An operator now finds, in docs/configuration.md: the form identity
and account names take; that AZKABAN_SKIP_CUSTOM_IMAGES,
AZKABAN_AUTO_PULL, and AZKABAN_UNMASK_PROC take 0 or 1 only;
which container variable values are dropped with a warning; that a
workspace .env.<client> must not be a symlink; that containers never
see custom image approvals; and that a launch passes the terminal's
size as well as its type. docs/custom-images.md says a workspace
Dockerfile must not be a symlink, docs/troubleshooting.md has the two
installer errors, and examples/env.azkaban.example lists
AZKABAN_UNMASK_PROC.

A contributor now finds, in docs/development.md: how to run the
launcher from a checkout, the Makefile's TZ, and that two test files
fail inside Claude Code's Bash sandbox. docs/adding-a-client.md states
the API-key field's rule once.

No code or test changes. Not in this change: the README keeps its
sentence on the workspace .env.<client>, which the audit offered to
shorten.

How to verify

Have Git and Bash 4.4 or newer, on Linux. No container engine is
needed: a dry run prints the launch without making it.

git clone https://git.unitoo.it/claudiomaradonna/azkaban.git
cd azkaban
scratch="$(cd "$(mktemp -d)" && pwd -P)"
mkdir "$scratch/home" "$scratch/bin" "$scratch/project"
ln -s "$PWD/bin/azkaban" "$scratch/bin/claude"
(cd "$scratch" && HOME="$scratch/home" bin/claude ./projct --dry-run </dev/null)
sed -n '/^## Usage/,/^Every command/p' README.md

The launch, the same on master and on the branch, prints
claude: Workspace: <scratch> and a command that mounts
<scratch>:/workspace and ends with claude-code ./projct: the
mistyped ./projct went to the client and the current directory became
the workspace. On master the README's Usage says only "The first
positional argument is the workspace and must precede native-client
arguments". After git switch docs/align-with-code it says "when it is
an existing folder" and adds "Any other first argument goes to the
client, and the workspace is then the current directory".

Checks run on the tip: make lint && .agents/hooks/shellcheck.sh repo && make test
passes, 352 tests; prettier --check README.md docs/*.md passes; a
reviewer confirmed each added fact against the code line it describes.
Not tried: the macOS rule for dropped values, read from the code only.

## Why The README and `docs/` tell users how to launch a client in its container and contributors how to work on the launcher. An audit of them against the code found the commands, options, and links right, and a few passages wrong or silent. The one that matters most: the README said the first argument is the workspace. When that argument is not an existing folder, the launcher passes it to the client and mounts the current directory instead, asking first on a terminal and unasked otherwise, so a mistyped folder exposes the whole current directory to the container. The rest are smaller: the shared env example lacked one control, two sentences of `docs/configuration.md` contradicted the code, several rules the launcher enforces were stated nowhere, two installer errors had no troubleshooting entry, and two facts had more than one home. ## What changed A user reading Usage now learns what happens to a first argument that is not a folder, and `docs/automation.md` points a script author to it. An operator now finds, in `docs/configuration.md`: the form identity and account names take; that `AZKABAN_SKIP_CUSTOM_IMAGES`, `AZKABAN_AUTO_PULL`, and `AZKABAN_UNMASK_PROC` take `0` or `1` only; which container variable values are dropped with a warning; that a workspace `.env.<client>` must not be a symlink; that containers never see custom image approvals; and that a launch passes the terminal's size as well as its type. `docs/custom-images.md` says a workspace Dockerfile must not be a symlink, `docs/troubleshooting.md` has the two installer errors, and `examples/env.azkaban.example` lists `AZKABAN_UNMASK_PROC`. A contributor now finds, in `docs/development.md`: how to run the launcher from a checkout, the Makefile's `TZ`, and that two test files fail inside Claude Code's Bash sandbox. `docs/adding-a-client.md` states the API-key field's rule once. No code or test changes. Not in this change: the README keeps its sentence on the workspace `.env.<client>`, which the audit offered to shorten. ## How to verify Have Git and Bash 4.4 or newer, on Linux. No container engine is needed: a dry run prints the launch without making it. ```bash git clone https://git.unitoo.it/claudiomaradonna/azkaban.git cd azkaban scratch="$(cd "$(mktemp -d)" && pwd -P)" mkdir "$scratch/home" "$scratch/bin" "$scratch/project" ln -s "$PWD/bin/azkaban" "$scratch/bin/claude" (cd "$scratch" && HOME="$scratch/home" bin/claude ./projct --dry-run </dev/null) sed -n '/^## Usage/,/^Every command/p' README.md ``` The launch, the same on `master` and on the branch, prints `claude: Workspace: <scratch>` and a command that mounts `<scratch>:/workspace` and ends with `claude-code ./projct`: the mistyped `./projct` went to the client and the current directory became the workspace. On `master` the README's Usage says only "The first positional argument is the workspace and must precede native-client arguments". After `git switch docs/align-with-code` it says "when it is an existing folder" and adds "Any other first argument goes to the client, and the workspace is then the current directory". Checks run on the tip: `make lint && .agents/hooks/shellcheck.sh repo && make test` passes, 352 tests; `prettier --check README.md docs/*.md` passes; a reviewer confirmed each added fact against the code line it describes. Not tried: the macOS rule for dropped values, read from the code only.

motoko added 2 commits

2026-11-11 14:40:09 +01:00

docs: align user documents with the code 74cf614b8b

The documents drifted from the launcher: the first-argument rule
omitted that a non-folder argument makes the current directory the
workspace, which a typo turns into mounting it whole. Also state the
name rules, the 0 or 1 controls, the dropped container values, the
symlink refusals, the TERM, COLUMNS, and LINES pass-through, and the
approvals containers never see; list AZKABAN_UNMASK_PROC in the env
example; add the two installer failures to troubleshooting.

docs: align contributor documents with the code a8f60b17a8

Document running the launcher from a checkout, the Makefile's TZ, and
which integration tests fail in Claude Code's Bash sandbox. Keep the
optional API-key field rule and OpenCode's release-gate status in one
home each and link to it.

motoko force-pushed docs/align-with-code from a8f60b17a8 to 2eebef022a

publish-images / publish (push) Successful in 37m16s

Details

2026-11-11 14:47:31 +01:00

Compare

motoko referenced this pull request

2026-11-11 14:47:40 +01:00

test: remove tests that repeat another test #73