Skip to content

docs: make every documented af-stack invocation match the CLI (29 audit fixes) - #218

Merged
AbirAbbas merged 9 commits into
mainfrom
docs/cli-conformance
Sep 2, 2026
Merged

docs: make every documented af-stack invocation match the CLI (29 audit fixes)#218
AbirAbbas merged 9 commits into
mainfrom
docs/cli-conformance

Conversation

@AbirAbbas

@AbirAbbas AbirAbbas commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Summary

After #215, #216, and #217 each fixed one break a first-time user hit, I ran every documented af-stack invocation (193 of them, across README, AGENTS.md, docs/, docs-site, and the skill) against the real v0.12.4 binary and the source. 69 candidate mismatches came back; 57 survived independent three-way refutation; 29 were small enough to fix now and are in this PR. The 8 larger ones are listed at the bottom as follow-ups.

Every fix was made against the binary or the source, not from memory, and each of the 29 was then re-checked by an independent verifier against the final tree.

What changed, by area

  • README / AGENTS.md. The fork-branding line passed --logo ./logo.png, a file no clone has, and because the logo is copied before brand.yaml is written, the whole init aborted with nothing applied. README sent readers to the operator console without the login it requires in the default saas mode. AGENTS.md's proof-of-wiring curl targets supportdesk.echo, which af-stack init --name renames away; the prose now explains the <node_id>.echo shape, and the CLI now rewrites that literal in AGENTS.md too. adapter list and billing were listed as no-key commands.
  • CLI reference (docs/cli-distribution.md, docs/cli-admin.md). secrets and db were listed as unshipped; both ship. A retracted backai.dev/install.sh one-liner, a nonexistent af-stack serve, operator create's DATABASE_URL ordering, --json over-promised for db, and missing docs for adapter new and agent|module validate.
  • dx docs. run.md's quick start ran af-stack dev with no clone step; theming.md overstated what init --logo does on a fresh clone; adapters.md presented adapter list as offline; sdk-strategy.md named CLI commands that do not exist; three docs pointed at a cost-explorer plugin that was never in the repo.
  • Workload-module docs. Claimed there is no runtime loader and documented a manifest filename and schema the runtime rejects; product.md listed af-stack harness list/install as shipped.
  • Runbooks. The restore runbook and scripts/restore.sh told operators to run af-stack migrate up (no such subcommand; it would boot a second runtime); KMS rotation documented secrets rotate-kms and AF_STACK_KMS_KEY_NEW, which are unimplemented; the shutdown smoke test started "the runtime" with af-stack &, which is the operator CLI.
  • Skill. Canonical-workflow step 4 still told coding agents to run af-stack init <name> --template coding-agent, which the positional form rejects (this is what fix(cli): explain the checkout requirement and fix the docs that led users outside one #216's header fix missed). The customer-app surface was described as an (app)/ route group that does not exist. Four cross-references pointed at missing files, plus the wrong path for the OpenAPI document.
  • CLI help text. init --help described only the in-checkout form and advertised a template the positional form rejects; the usage example failed non-interactively; --no-open's flag help said the opposite of its behaviour; three shipped subcommands were absent from help.

Verification

  • Per-item independent verification against the final tree (resolved + accurate); anything that came back flagged was corrected before this PR settled.
  • go build, go vet, go test ./... pass; golangci-lint v2.13.1 in CI's new-issues mode reports 0 new issues; docs lint and the docs-site build (47 pages) pass; scripts/restore.sh is shellcheck-clean. The two dashboard source edits are comments.

Deferred (real, but need a CLI or product decision)

  1. af-stack mode succeeds outside a checkout and writes a stray .env.
  2. af-stack init --name renames the default agent node id, invalidating SDK READMEs and conformance scripts that hardcode supportdesk.echo.
  3. The documented exit-code contract (2 for usage, 6 for transport) is not honoured by most commands.
  4. There is no per-command --help for 27 of 30 commands.
  5. agent|module validate takes a path but reports a bare id in its error.
  6. Positional af-stack init <name> cannot produce a fork, and --template coding-agent is flag-form only.
  7. The runtime binary boots a full server on any unrecognised first argument.
  8. KMS key rotation is documented in the Helm README but unimplemented.

🤖 Generated with Claude Code

AbirAbbas and others added 8 commits September 2, 2026 12:45
@AbirAbbas @claude
docs(quickstart): make the README and AGENTS.md sequences runnable as…
c05a0ba 
… written

An audit ran every documented af-stack invocation against the real CLI;
this commit takes the root-level findings.

- README's fork-branding line passed `--logo ./logo.png`, a file no
  clone contains; since the logo is copied before brand.yaml is written,
  the whole init aborted with nothing applied. The runnable line is now
  `af-stack init --name "Acme AI" --color "#2563EB"` with the logo as an
  opt-in comment. Same in examples/starter/README.md.
- README sent readers to the operator console without the seeded login
  it requires in the default saas mode. It now gives the credentials,
  how to seed different ones before first boot, and that `af-stack mode
  personal` turns login off. The two dashboard source comments that
  claimed this was already documented now are true.
- AGENTS.md's proof-of-wiring curl is written against `supportdesk.echo`,
  but `af-stack init --name` rewrites the agent node id, so the call
  target vanishes on every branded fork. The prose now explains the
  `<node_id>.echo` shape and how to list what is registered.
- AGENTS.md listed `adapter list` under "no key"; it needs a running
  runtime and an operator key, as does billing. Recategorised.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(cli): bring the CLI reference back in line with the binary
e9503dd 
- `secrets` and `db` were listed as "planned / not yet shipped"; both
  ship and cli-admin.md documents them.
- Scaffold and deploy blocks now state the checkout precondition, and
  `af-stack init --logo` no longer points at a file no clone has.
- Drop the retracted `backai.dev/install.sh` one-liner and the claim
  that `af-stack serve` is the server mode (no such command).
- `operator create` needs DATABASE_URL before it runs, not after.
- The app-developer table no longer promises `--json` for `db` and
  notes db's checkout precondition; `adapter new` and the
  `agent|module validate` subcommands are documented.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(dx): state preconditions and stop describing things that do not …
57ed033 
…exist

- run.md's quick start ran `af-stack dev` with no clone step; it and
  the hub now start inside a checkout. `--no-open` is described as it
  behaves.
- theming.md claimed `init --logo` copies the logo into the app public
  paths and runs generate:brand; on a fresh clone it writes brand.yaml
  and brand/logo.* and skips generation until deps are installed.
- adapters.md presented `adapter list` as offline; it needs a running
  runtime and an operator key. `adapter new` is documented.
- sdk-strategy.md's "not in any SDK" list named CLI commands that do not
  exist; dashboard-plugins.md and stack.md pointed at a `cost-explorer`
  example plugin that was never in the repo.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(modules): describe the module loader and manifest that actually …
2aad7db 
…ship

The workload-module docs said there was no runtime loader and documented
a manifest filename and schema the runtime rejects; product.md listed
`af-stack harness list/install` as shipped CLI commands. Rewritten
against the loader and manifest in the tree.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(runbooks): remove commands the operator CLI does not have
a6cb260 
The restore runbook (and scripts/restore.sh) told operators to run
`af-stack migrate up`, which does not exist as a subcommand and would
boot a second runtime; KMS rotation documented `af-stack secrets
rotate-kms` and `AF_STACK_KMS_KEY_NEW`, which are unimplemented; the
graceful-shutdown smoke test started "the runtime" with `af-stack &`,
which is the operator CLI on PATH. Each now names the real command or
says plainly that the capability is not implemented yet. Stale
`supportdesk.echo` literals note that a branded fork renames the node.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(skill): fix the workflow step, paths, and references coding agen…
d02288e 
…ts follow

- Canonical-workflow step 4 still told agents to run `af-stack init
  <name> --template coding-agent`, which the positional form rejects;
  it now clones and brands in place like the header.
- The customer-app surface was described as an `(app)/` route group
  with layouts and pages that do not exist; corrected to the real
  `src/app/` layout, including the snippet.
- Cross-references pointed at four files that do not exist, a
  `cost-explorer` plugin that was never in the repo, and a wrong path
  for the checked-in OpenAPI document.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs(site): drop the cost-explorer plugin reference that never existed
fa7ffc7 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
fix(cli): make help and usage text match what the commands accept
9f5990d 
- `af-stack init --help` documented only the in-checkout form and
  advertised `--template coding-agent` for the positional form, which
  rejects it; both forms are now described where each applies.
- The usage example `af-stack init --template coding-agent` fails
  non-interactively because --name is required; the example now passes
  it.
- `agent validate`, `module validate`, and `adapter new` ship but were
  absent from help; `--no-open`'s flag help described the opposite of
  its behaviour; the generated saas app's next steps named a command
  that does not exist.
- AGENTS.md joins the files whose `<node_id>.echo` literal
  `af-stack init --name` rewrites, so the proof-of-wiring curl follows
  the branded node id.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas @claude
docs: corrections from independent verification of the sweep
27ac9ee 
Each of the 29 fixes was re-checked by a separate verifier against the
final tree and the binary. Ten came back with a leftover or an
overstatement in the new text; this commit takes them:

- README told readers to change the seeded operator password "from the
  console"; the console has no such page. Say how the seed actually
  works instead, and fix .env.example's wrong port and same claim.
- run.md quoted the pre-#216 checkout error text.
- architecture.md still showed manifest.yaml/handler.go and a jobs/crons
  field for workload modules; EDITING.md still named the nonexistent
  (app)/ route group and sidebar file.
- The cost-explorer phantom survived in the docs-site reference page and
  as dead code in scripts/capture-screenshots.mjs; rules/sdk.md pointed
  at example plugins as SDK usage when they use plain fetch.
- product.md claimed a harness dashboard page that does not exist.
- The restore runbook and restore.sh said the runtime exits non-zero on
  any failed migration; only core migrations are fatal, module and jobs
  failures are logged and disable that piece, so grep for both.
- adapters.md omitted that personal mode needs no operator key; SKILL.md
  claimed init prompts only on a TTY (it always prompts on stdin).
- scripts/test-quickstart.sh hardcoded supportdesk.echo, which breaks on
  a branded fork; it now reads the node id from compose. The SDK
  conformance scripts note the same assumption.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Abir Abbas <abirabbas1998@gmail.com>
@AbirAbbas
AbirAbbas merged commit dd5f84b into main Sep 2, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@santoshkumarradha santoshkumarradha Awaiting requested review from santoshkumarradha santoshkumarradha is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AbirAbbas