docs: correct seven claims the new @docs got wrong

Review of 01ccbf2 found seven inaccuracies, all of them assertions
nothing in this project checks. Two were regressions of rules this
repo had already settled rather than ordinary staleness, and both are
now written down in AGENTS.md so the next draft does not repeat them.

The two regressions:

  * `upgradable/0` said the record is synthesised when the system
    started without a `releases/RELEASES` file "it could read". That is
    the *readable* phrasing five successive corrections to the refusal
    message had already discarded - it misses malformed terms - and it
    named the file unqualified, which castle#23 forbids because RELDIR
    and `{sasl, releases_dir}` relocate it. The @doc now says what the
    refusal says: the file `:release_handler` accepts, no one property
    of the file being the test, and the path qualified.

  * `commit/1` said committing an already-permanent version "succeeds
    and changes nothing". That was true before castle#14 moved
    materialisation inside `commit`'s serialised region.
    `make_permanent/1` is still a no-op for such a version, but the
    target's `sys.config` has been rewritten from current provider
    inputs by then, and a provider that fails now fails the command.

The five others:

  * `report!/1` does not make every failure a `Castle.Error`.
    `installed/5` settles the marker and re-raises what
    `install_release/1` raised, threw or exited with, so automation
    rescuing only `Castle.Error` would read a blown-up command as a
    success. The moduledoc now says which failures become which.

  * The install preflight is documented in the order it happens: the
    ERTS guard, the release-record lookup and its refusal, the
    pending-marker refusal, materialisation, arming - five steps, before
    `install_release/1` rather than before any `:release_handler` call,
    since the lookup is one. The pending-marker refusal was missing
    entirely, and it is what stops a refused caller replacing the
    configuration a pending install is about to boot.

  * "Anything that takes the system down brings the previous version
    back" is false for a restart install. The launcher consumes the
    marker pair on the next start and boots the target; it is the
    restarts after that one which return to the previous permanent
    version. RELEASE.md said the same thing and is corrected with it.

  * `bin/castle commit` with no version selects a `:current` release
    and exits non-zero when there is none - not "the version running
    now", which a system on its permanent release also has.

  * `unpacked` is staged and not currently installed, a version a
    rollback returned to that state included. `running/1`'s own @doc
    already said so.

And the specs: two @specs on a five-arity defaulted definition left
`install/2..4` unspecced, contradicting this branch's own claim that
the whole public surface carries one. All five are now present, checked
with `Code.Typespec.fetch_specs(Castle)` against
`Castle.__info__(:functions)` rather than by reading the source - ExDoc
renders only the widest arity's spec, so the page could not have shown
the gap.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C4oaMvbR1cbxrZBj8qwkqN

Author: ausimian

AGENTS.md

@@ -914,13 +914,23 @@ Castle's job is configuration and release management on a running node.
   reboot takes and which automation reads.
 
 Every one of them is a command entry point, so `Castle` is the command
-boundary: an operation that fails raises `Castle.Error` there, which is what
-leaves a non-zero exit status behind for the shell that asked for it. Raising,
-not halting — the expression runs on the *running* node, so halting would take
-down the system under management; `Kernel.CLI` catches on the node and
-re-raises in the calling VM, and only that VM exits. `Castle.Commands` holds
-the operations themselves, returning their outcome instead of acting on the
-process, which is what makes them testable.
+boundary: an operation that fails raises there, which is what leaves a non-zero
+exit status behind for the shell that asked for it. Raising, not halting — the
+expression runs on the *running* node, so halting would take down the system
+under management; `Kernel.CLI` catches on the node and re-raises in the calling
+VM, and only that VM exits. `Castle.Commands` holds the operations themselves,
+returning their outcome instead of acting on the process, which is what makes
+them testable.
+
+**`Castle.Error` is what `report!/1` raises, and it is not everything a command
+raises.** `report!/1` turns a returned `{:error, message}` into one; an
+exception, a throw or an exit that the operation did not handle goes straight
+past it. That is deliberate for the one place it can happen on purpose —
+`installed/5` settles the marker and re-raises `install_release/1`'s failure
+unchanged, folding it into a message only where the marker could not be settled
+— so anything claiming that a failed command raises `Castle.Error`, in a `@doc`
+or here, has to say which failures. Automation told to rescue `Castle.Error`
+and nothing else would treat a `release_handler` that blew up as a success.
 
 `Castle.customize/1` is the one function in that module which is *not* one of
 them — it runs at build time, in a consumer's `mix.exs`, and returns a value
@@ -956,6 +966,54 @@ returns; a spec naming the lines, or an error tuple, would be describing
 kept by hand, and a claim in a `@doc` about what a command refuses is worth
 checking against `Castle.Commands` before it is trusted.
 
+**A definition with defaults needs one `@spec` per arity, and "every public
+function carries a spec" is a claim about arities.** `install/1..5` is five
+functions and therefore five specs; the first version of this carried two, for
+`install/1` and `install/5`, and left three unspecced while this file and
+`RELEASE.md` both said the surface was complete. Nothing catches that, and
+`mix docs` is no help either: ExDoc renders one spec against a defaulted
+definition, the widest arity's, so the page looks the same with two specs as
+with five. `credo --strict` passes, and there is no Dialyzer. So check it with
+`Code.Typespec.fetch_specs(Castle)` and count — against
+`Castle.__info__(:functions)`, which is the list that has to be covered —
+rather than by reading the source, which is what missed three of them.
+
+**The `@doc`s are claims, nothing checks them, and the first draft of them
+walked back into two rules this file had already settled.** Both are worth
+naming, because both were regressions rather than staleness:
+
+  * `upgradable/0`'s said the record is synthesised when the system started
+    "without a `releases/RELEASES` file it could read" — which is the
+    *readable* phrasing corrected above, admitting the malformed-terms
+    counterexample, and it named the file unqualified besides. A `@doc` that
+    describes a refusal has to say what the refusal says: name the authority
+    (the file `:release_handler` accepts, no single property of it being the
+    test), and qualify the path with `RELDIR` and `{sasl, releases_dir}`.
+  * `commit/1`'s said that committing an already-permanent version "succeeds
+    and changes nothing", which was true of the shape castle#14 replaced.
+    `Commands.commit/5` materialises inside its own serialised region, so the
+    target's `sys.config` is rewritten from current provider inputs before
+    `make_permanent/1` — which is itself a no-op for that version — is called
+    at all. OTP's step being idempotent is not the command being idempotent.
+
+Three more were ordinary staleness of the same kind, and the pattern is that a
+`@doc` describing a *sequence* goes stale where a `@doc` describing a value
+does not: `install/1`'s claimed two steps before `:release_handler` was asked
+for anything, when `install_upgradable/5` asks `which_releases/0` first and
+refuses for a pending marker in between, and the line that matters is
+`install_release/1` rather than any handler call; the rollback an install
+leaves was described as "anything that takes the system down brings that one
+back", which is false for the one reboot a restart install has already asked
+for and the launcher is holding a marker to carry out; and `unpacked` was
+glossed as "staged and never installed", which `running/1`'s own `@doc`
+already contradicts. `bin/castle commit`'s argumentless form was described as
+defaulting to "the version running now", where `castle.sh.eex` selects a
+`:current` release and exits non-zero when there is none.
+
+So: read a `@doc` about a sequence against the function that implements the
+sequence, not against the module's summary of it, and read one about
+`bin/castle` against Forecastle's `priv/castle.sh.eex`.
+
 Forecastle is what arranges for these to be reachable: it leaves the
 configuration Mix wrote alone, adds a `:preboot` script that starts `:castle`,
 and writes the `env.sh` fragment and `bin/castle` wrapper that call into this

RELEASE.md

@@ -254,7 +254,10 @@
   The rollback that provisional state buys is real and needs nothing:
   `make_permanent/1` is the only thing that writes `releases/start_erl.data`, so
   a provisional release that dies before `Castle.commit/1` is followed by an
-  ordinary start of the version that was permanent before.
+  ordinary start of the version that was permanent before. The one restart that
+  is not that is the one the install asked for: while the pair is still
+  unconsumed the next start boots the target, which is the reboot being carried
+  out rather than a rollback being missed.
 
   The two-stage `restart_new_emulator` transition remains unsupported. It reboots
   into a temporary hybrid release whose version directory holds a boot script and
@@ -267,25 +270,37 @@
   the only one meant to be called from other Elixir code, and everything else is
   a command entry point that `bin/castle` reaches over `rpc`. That distinction is
   worth reading before calling any of them, because a command prints its report
-  and returns a bare `:ok`, and a command that fails raises `Castle.Error`
-  instead of returning an error - which is what leaves a non-zero exit status
-  behind for the shell, and is not what a caller expecting an ordinary function
-  would write code for.
+  and returns a bare `:ok`, and a command that fails raises rather than returning
+  an error - which is what leaves a non-zero exit status behind for the shell,
+  and is not what a caller expecting an ordinary function would write code for.
+  The moduledoc is careful about what it raises, because automation acts on it: a
+  refusal the command made and an error `:release_handler` returned become
+  `Castle.Error`, while an exception, throw or exit the operation did not handle
+  is let out unchanged - so a rescue narrowed to `Castle.Error` will miss a
+  command that blew up.
 
   Every command is documented with the `bin/castle` command that reaches it -
   `releases`, `upgradable`, `unpack`, `install`, `commit`, `remove` - and with
   what it refuses and what it leaves behind: that an install is provisional until
-  it is committed and a restart until then returns to the previous version, that
-  `bin/castle install` confirms the version is running rather than trusting the
-  reply, that removing a version deletes what nothing else is using, and that the
-  two questions - `upgradable` and `releases` - answer on a deployment where
-  everything else is refused. `Castle.running/1` is documented too: it has no
-  `bin/castle` command of its own, and it is what automation driving an upgrade
-  over `rpc` needs in order to confirm one.
-
-  Every public function now carries a `@spec`. `Castle.make_releases/0` is
-  deliberately not published: its only caller is the launcher, on the first start
-  of a deployment, and by hand it either does nothing or does what the next start
+  it is committed, and what that does and does not promise (an ordinary restart
+  returns to the previous version, but the reboot a restart transition has
+  already asked for boots the target); the five steps an install takes before
+  `:release_handler.install_release/1` is asked for anything, in the order it
+  takes them; that `bin/castle install` confirms the version is running rather
+  than trusting the reply; that `bin/castle commit` with no version commits the
+  release awaiting commit and fails when there is none, and that an explicit
+  commit re-expands the target's configuration even for a version that is
+  already permanent; that removing a version deletes what nothing else is using;
+  and that the two questions - `upgradable` and `releases` - answer on a
+  deployment where everything else is refused. `Castle.running/1` is documented
+  too: it has no `bin/castle` command of its own, and it is what automation
+  driving an upgrade over `rpc` needs in order to confirm one.
+
+  Every public function now carries a `@spec`, every arity of them:
+  `Castle.install/1` through `install/5` are one definition with defaults, so
+  they are five specs rather than two. `Castle.make_releases/0` is deliberately
+  not published: its only caller is the launcher, on the first start of a
+  deployment, and by hand it either does nothing or does what the next start
   would do anyway.
 
 ### Changed