Skip to content

Commit fec90e9

Browse files
ausimianclaude
andcommitted
docs: carve running/1 out of the operator-command claim
The passage explaining what is published and what is hidden named two exceptions and then said every other function is a command an operator invokes. running/1 is not: bin/castle dispatches exactly releases, upgradable, unpack, install, remove and commit, and running/1 has no subcommand - its only shipped caller is the confirmation loop inside bin/castle install. Its own new @doc says so, so AGENTS.md contradicted the file it is describing. It stays published, but for a different reason than the other two: it answers a read-only question and mutates nothing, and automation driving rpc rather than bin/castle needs it to know when an install has finished booting. That is the distinction from make_releases/0, which mutates bookkeeping once and is useless by hand. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 131ef59 commit fec90e9

1 file changed

Lines changed: 10 additions & 2 deletions

File tree

AGENTS.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -976,8 +976,16 @@ nobody should call. It keeps its `@spec` regardless — the spec is the contract
976976
whether or not the function is published. And `install/2..5` is documented as
977977
what it is, a seam the concurrency test drives: one `@doc` covers every arity of
978978
a clause with defaults, so saying nothing about the extra four would leave them
979-
reading as an API. Every other function is a command an operator invokes, and
980-
hiding one of those would document nothing useful anywhere.
979+
reading as an API. `running/1` is a third case, and documented rather than
980+
hidden for a different reason than the other two. It has no subcommand either —
981+
`bin/castle` dispatches exactly `releases`, `upgradable`, `unpack`, `install`,
982+
`remove` and `commit`, and `running/1`'s only shipped caller is the confirmation
983+
loop inside `bin/castle install`. But unlike `make_releases/0` it answers a
984+
read-only question and mutates nothing, and automation driving `rpc` rather than
985+
`bin/castle` needs precisely it to know when an install has finished booting.
986+
Hiding it would strand that caller; publishing it costs nothing. Every remaining
987+
function is a command an operator invokes, and hiding one of those would
988+
document nothing useful anywhere.
981989

982990
The specs say `:: :ok` and nothing more, because that is what `report!/1`
983991
returns; a spec naming the lines, or an error tuple, would be describing

0 commit comments

Comments
 (0)