docs: present the CLI as shipped, not an MVP - #48
Merged
Conversation
Remove leftover "current MVP" framing from the README intro now that akua is a real, shipped product (v0.10.1+, installable via `brew install akua-dev/tap/akua`, proven end-to-end against production: install, login, free cluster, free managed worker, package, install). Bump the pinned copy-paste install examples and the release-artifact table from v0.9.0 to the current v0.10.1 release; v0.9.0 archives predate the embedded package-runtime change (#42) and don't contain the `node_modules/@akua-dev` tree the current install script extracts and (on Windows) copies, so the old pinned version silently breaks the documented install path. Update test/docs.test.ts's pinned asset-name literals to match. Verified every command example in the README against this repo's current source: `akua --help`, `akua auth login`/`status`/`logout`, `akua commands`, `akua workspaces --help` (human mode), and `akua pkg version` all match what the CLI at v0.10.1 actually outputs. Tested: bun test test/docs.test.ts; bun test (165 pass)
Rework the README's intro and structure to lead with what akua does (create clusters, add machines, package and install apps) and who it serves (a human at a terminal, a CI pipeline, a coding agent) before any mechanism explanation. Name all three audiences explicitly instead of only "humans, automation, and coding agents" in passing. Remove every mention of Effect, the internal library the CLI happens to be built with. It is not something a user installing and running the CLI needs to know. Where a sentence's real content was the useful, user-facing fact that commands are generated from the OpenAPI spec and therefore never drift out of sync, keep that fact and state it in outcome terms instead of naming the framework. Move the OpenAPI-generation mechanics out of the primary usage flow and into the Development section, since that detail matters to contributors, not to someone running `akua workspaces list`. Reorder first-use so sign-in gets its own section, and consolidate the human vs. CI vs. agent output story into one section explicitly titled for all three. Verified every command and flag shown against the current CLI: `akua --help`, `--version`, `commands --limit 1|5`, `pkg version`, `pkg --help`, `auth --help`, `auth login --help`, `auth status`, `workspaces --help`, and the `workspaces list --input -` stdin-piping example, all run directly from src/bin/akua.ts. Updated test/docs.test.ts's pinned README literals to match: dropped the "generated typed Effect API" and "Generated API commands execute" assertions (text no longer present by design) in favor of phrases that match the new copy, and added a regression test asserting the README never mentions Effect and does name all three audiences.
Move the Development section (codegen mechanics, release packaging/ verification/smoke, Release Please/Homebrew tap process) into a new CONTRIBUTING.md so README.md only covers using the shipped `akua` executable: what it does, install, sign in, run commands, and where to find the full reference. README now points to docs.akua.dev for the command reference and to CONTRIBUTING.md for repo development. Rationale: reviewer feedback on PR #48 - anything a developer using the CLI doesn't need to see belongs in its own file, not the README. Tested: bun test (168 pass), bun scripts/generate-commands.ts --check, bun scripts/generate-effect-api.ts --check, bun run build.
The per-OS GitHub Release install steps (checksum verification, extraction, PATH setup for macOS/Linux/Windows) cluttered the primary README flow for a path almost no one uses; Homebrew is the install method for the vast majority of users. Move the detailed fallback into docs/install.md and leave a single pointer line in README.md. The fallback stays documented (not deleted) because docs/quickstart.mdx in the cnap repo references it as the non-Homebrew install path for agents.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
akuais a real, shipped product (v0.10.1+,brew install akua-dev/tap/akua), proven end-to-end against production today: install → login → free cluster → free managed worker → package → install.akuabinary, while the current install script (added alongside that change) extracts and, on Windows, explicitly copies anode_modules/@akua-devtree that doesn't exist in v0.9.0 archives — so the old pinned version would break a copy-pasting user on Windows and silently ship a binary without the embedded native package runtime everywhere else.test/docs.test.ts's pinned asset-name literals to match the version bump.No other MVP/early-access/"coming soon" language was found elsewhere in the README — the rest of the doc (auth, output modes, OpenAPI command generation, release process) already accurately describes the current, real command surface. I verified every command example against this repo's actual CLI output (
akua --help,akua auth login/status/logout,akua commands,akua workspaces --helpin human mode,akua pkg version) rather than trusting the prior prose.Test plan
bun test test/docs.test.ts— 4 passbun test(full suite) — 165 pass, 0 failakua --help,akua auth login --help,akua commands --limit 5,akua workspaces --help --output human,akua pkg --help,akua pkg versionagainst the currentsrc/bin/akua.tsto confirm README examples match real outputnode_modules/@akua-devembedded-runtime difference that motivated the version bump