diff --git a/README.md b/README.md index 88d2871..68c5469 100644 --- a/README.md +++ b/README.md @@ -372,3 +372,29 @@ Counts match GitHub for all repositories. Git history, issues, pull requests, la ## Next steps The CLI is authenticated and the first full repository import is complete. Every subsequent Forgejo task you need will be added as a new command under `stoke`. + +## Why the name `stoke`? + +The heavy-duty handbook defines a strict naming style for tools: + +- **one syllable**, plain concrete English — industrial: the shop floor and the site +- **a repurposed common word**, never coined jargon +- **a verb⇄noun with a double meaning** that hints at the job + +Existing tools follow this exactly: `cast` pours a part and is the part; `rig` sets up and is the setup; `jig` holds work and is the fixture; `boss` runs the site and is the supervisor; `hand` works and is the worker; `gig` is a one-off job and the job itself; `gauge` measures and is the instrument. + +The handbook calls the Forgejo instance **"the forge"** — the coordination home where issues, PRs, reviews, and git state live. A forge only stays useful if someone feeds it fuel and air. *To stoke* a fire is to tend it and keep it burning. This CLI does the same thing programmatically: it creates repos, opens issues, imports projects, adds collaborators — it keeps the forge active. + +`stoke` also fits the operator relationship. While `jig`, `boss`, `hand`, and `gauge` are autonomous or daemon-like, this tool is the operator's hand on the forge. You don't forge by accident; you stoke on purpose. + +Other names were considered and rejected: + +- `forge` — too literal; the forge is the platform, not the tool. +- `tap` — machining term, but "tapping" is about threading holes, not tending a forge. +- `weld` / `braze` — join-metal verbs, but the CLI is not primarily joining things. +- `die` / `mold` / `stamp` — shaping tools, but `die` carries a strong negative meaning and `mold` has the fungus connotation. +- `quench` — forge-related, but quenching cools/finishes; the CLI starts and feeds work. +- `draft` / `blast` — air-feeding the forge, but feel like background services, not an operator CLI. +- `flux` — nice metaphor for flow, but reads as chemistry rather than the forge shop. + +`stoke` was the only candidate that was clearly forge-specific, operator-facing, one syllable, and already a common verb/noun.