@@ -51,17 +51,8 @@ const row = lineOf([
   backticked,
 ]);
 
-/** What action-docs writes between its markers, by position after the opening marker's own line ends:
- *
- * ""                                          the rest of the marker line
- * "## Inputs"
- * ""
- * "| name | description | required | default |"
- * "| --- | --- | --- | --- |"
- * one row per input                           a description never holds a "|" (test/docs/inputs.test.ts)
- * ""                                          before the closing marker
- *
- * A region of blank lines alone (a fresh marker pair) is also a rendering's shape. */
+/** The first entry is the rest of the opening marker's own line. A "|" in a description would split its rendered row
+ * past `row`'s four cells and refuse it as authored, so test/docs/inputs.test.ts pins every description free of one. */
 const LEADING: ((line: string) => boolean)[] = [
   (line) => line === "",
   (line) => line === "## Inputs",
 
@@ -10,27 +10,14 @@
  *   refs/tags/vX                   -> the same commit, moved on each release in the line
  *
  * Every artifact is a function of its main commit alone, so runs for different commits never wait on each other
- * and a rerun mints the same name and verifies instead of appending. latest and vX move through movePointer alone:
- * forward along main, under a compare-and-set on the value origin advertised, never back.
+ * and a rerun mints the same name and verifies instead of appending. latest and vX move through movePointer alone.
+ * Every subcommand but prerelease-version runs under a workflow step, bare or in the step's shell; no step runs two.
  *
- * release-please cuts the DRAFT release without a tag (`draft` on, `force-tag-creation` off); one subcommand runs
- * per workflow step:
+ * release-please cuts the DRAFT release without a tag (`draft` on, `force-tag-creation` off) and creates or
+ * refreshes the release PR only when a releasable commit lands (release-please-config.json leaves always-update
+ * off); that refresh is what publishes the `next` pre-release.
  *
- *   package-commit                 post-green.yml          GITHUB_SHA, RUN_URL (optional)
- *   anchor                         update-release-pr.yml   GITHUB_SHA
- *   npm-verdict next               update-release-pr.yml   GITHUB_SHA, NPM_REGISTRY_URL (optional)
- *   npm-confirm next               update-release-pr.yml   GITHUB_SHA, NPM_REGISTRY_URL (optional), NPM_CONFIRM_PAUSE_MS (optional)
- *   npm-verdict stable             update-release.yml      TAG, GITHUB_SHA, NPM_REGISTRY_URL (optional)
- *   npm-floor                      both publish jobs       (nothing; npm on PATH)
- *   package, retag-major           update-release.yml      TAG, GITHUB_SHA, RUN_URL (optional, package only)
- *   boundary-check, anchor-check   checks.yml              (the checkout alone)
- *   prerelease-version             by hand                 GITHUB_SHA (the version a commit's next publish carries)
- *
- * The `next` pre-release publishes when release-please creates or refreshes the release PR, which it does only when a
- * releasable commit lands (release-please-config.json leaves always-update off); npm-verdict next is the guard on
- * npm state that follows, never the decision to publish.
- *
- * Node builtins only: bun runs this before `bun install`. Tests: test/scripts/release-pipeline*.test.ts over release-pipeline-fixture.ts.
+ * Node builtins only: bun runs this before `bun install`.
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
@@ -454,15 +441,9 @@ export interface PointerMove {
  * The one way a pointer (latest, vX) moves: forward along main, never back. A pointer's source is its commit's
  * parent when that parent is on main; the candidate's source is on main by its caller's check.
  *
- *   pointer's source is the candidate's or descends from it  -> left: the same package, or a rerun of an older commit's run
- *   same source, another tree                                -> refused: two builds of one main commit
- *   pointer's source unknown (off main, a root)              -> moved: a value this pipeline did not mint
- *   otherwise                                                -> moved, under a lease on the value observed
- *
  * A value left in place must be a package of the commit it is read as packaging, or a hand-pushed bare child of a
  * newer commit would stand as "already past". Main's head is read AFTER the pointer on every pass: a pointer a rival
- * moved to a newer commit's package has that commit on main by then. A lease lost to a rival re-observes and
- * decides again; a push refused with the ref unmoved is thrown.
+ * moved to a newer commit's package has that commit on main by then.
  */
 export function movePointer(cwd: string, ref: string, candidate: Packaged): PointerMove {
   for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt++) {
 
@@ -89,15 +89,14 @@ export interface ExcludePattern {
 }
 
 /**
- * `nocase`: repository names compare case-insensitively on GitHub. `dot`: a leading "." is an ordinary character
- * in a repository name (".github"), not the hidden-file marker picomatch skips by default. `posix`: "[!ab]" is a
- * negated class, as in a shell, instead of a class holding "!". `fastpaths: false`: the shortcut regexes picomatch
- * mints for star-led patterns demand a character after a literal dot, so "*.*" would miss "archive."; the full
- * parser keeps "*" any run of characters. `debug`: an invalid class like "[z-a]" throws instead of compiling to a
- * never-matching regex. `windows: false`: the main entry otherwise follows the host OS, and a slug is a GitHub
- * identifier, not a path, so the matcher is the same on every runner. `literalBrackets: false`: a class compiles
- * to the class alone, not an alternation with its literal text, which no name holds; thousands of classes then
- * compile in milliseconds instead of reaching the engine's size limit.
+ * picomatch is built for file paths and a slug is a GitHub identifier, so each option is set for a name, none left to its default:
+ *   nocase          -> GitHub compares repository names case-insensitively
+ *   dot             -> a leading "." is an ordinary name character (".github"), not the hidden-file marker
+ *   posix           -> "[!ab]" is a negated class, as in a shell, not a class holding "!"
+ *   fastpaths       -> the star-led shortcut regexes demand a character after a literal dot, so "*.*" would miss "archive."
+ *   debug           -> an invalid class like "[z-a]" throws instead of compiling to a never-matching regex
+ *   windows         -> pinned: only picomatch's main callable reads the host OS; makeRe never does
+ *   literalBrackets -> no alternation with the class's literal text (no name holds it); thousands compile in milliseconds, under the engine's limit
  */
 const EXCLUDE_GLOB_OPTIONS = {
   nocase: true,
 
@@ -1,13 +1,13 @@
 /**
- * The one place a run writes a settings document (a snapshot, the merged file, init's starting file): staged beside
- * the destination and renamed into place, so a write that fails partway (disk full, an interrupted run) leaves the
- * previous file intact instead of a truncated one. The rename is atomic on POSIX and a single replace call on
- * Windows. The staging name is unique to the write (pid and random bytes), so no file of the user's is ever unlinked
- * or written through: an existing path there fails the write instead. A destination that is a symlink is replaced by
- * the rename, the link itself, never its referent, so the written document is always a regular file at `path`. The
- * guards over the writer hold one promise: an input layer is never the destination, under any name the read follows
- * or the rename reaches; deliberate evasion (hardlinks, mounts, races) is out of scope. A hard crash mid-write leaves
- * the staging file for the user to remove (.gitignore hides it); no run sweeps a file another process may be writing.
+ * The one place a run writes a settings document (a snapshot, the merged file, init's starting file). The guards
+ * over the writer hold one promise: an input layer is never the destination, under any name the read follows or the
+ * rename reaches. Deliberate evasion (hardlinks, mounts, races) is out of scope.
+ *
+ *   staged beside the destination, renamed in -> a write that fails partway leaves the previous file intact
+ *   the rename                                 -> atomic on POSIX, a single replace call on Windows
+ *   a symlink at the destination               -> the link itself is replaced, never its referent: `path` is always a regular file after
+ *   a hard crash mid-write                     -> the staging file is left for the user to remove (.gitignore hides it); no run
+ *                                                 sweeps a file another process may be writing
  */
 
 import { randomBytes } from "node:crypto";
 
@@ -49,9 +49,6 @@ function renderKeyPath(path: readonly string[]): string {
  * a property         -> read through its descriptor; an enumerable accessor is rejected UNREAD (a getter could sabotage globals)
  * an object's keys   -> only Object.keys are copied, so symbol and non-enumerable keys never reach the copy (array indices do)
  * a container again  -> rejected when it is one of its own ancestors (a YAML alias cycle); a sibling alias is copied twice
- * the wire           -> only the copy is sent
- *
- * A rejection is the NotPlainData the walk hands up, an instance no payload value can be.
  */
 function normalizePlainData(
   value: unknown,
 
@@ -14,15 +14,11 @@ import { grantFor, type SectionPermission, samePermission } from "./permissions.
  * What ends a section's work, as a value. `message` is the whole line the loops report; `kind` is read for policy
  * alone (a denial's partial-success handling in engine/orchestrate.ts), never to rebuild prose.
  *
- *   request kinds (failureFor and the request helpers): rate-limit, rejected, server-error, unauthorized,
- *                  validation, transport, malformed
- *   duplicate kinds (the identity checks): declared-duplicate, live-duplicate
- *   live-shape     -> GitHub's answer parsed but cannot be reconciled (an item without an id, a repeated rule type)
- *   refused        -> the section declines to proceed: the settings file conflicts with live state, an actor cannot
- *                     be resolved, a write would drop live values the file omits
- *   unverified     -> a write landed but its echo disagrees with what was set
- *   thrown         -> an exception escaped a section: the client's own throw on an unmarked request, or a BUG
- *                     invariant; the loops report its message like any other failure
+ *   live-shape  -> GitHub's answer parsed but cannot be reconciled (an item without an id, a repeated rule type)
+ *   refused     -> the section declines to proceed: the settings file conflicts with live state, an actor cannot be
+ *                  resolved, a write would drop live values the file omits
+ *   unverified  -> a write landed but its echo disagrees with what was set
+ *   thrown      -> an exception escaped a section: the client's own throw on an unmarked request, or a BUG invariant
  */
 export type SectionFailure =
   | {
 
@@ -45,13 +45,7 @@ const STANDARD_PERMISSIONS = ["pull", "triage", "push", "maintain", "admin"] as
  * The two wrong spellings hide until apply: "write" on an existing Write collaborator converges with zero drift
  * (the live role_name IS "write") while the same entry on a new one PUTs {"permission":"write"} and 422s.
  *
- *   read, write (any case)            -> the vocabulary GET reports a role in; the grant takes pull, push
- *   Push, ADMIN (a mis-cased standard) -> the lowercase form
- *   "", " push", "push\n" (block scalar) -> nothing to grant, or whitespace GitHub would not match
- *
- * One regex, so the published schema carries the same rule as a `pattern` (a pattern has no flags, hence the
- * case classes): an exact standard permission, or one line with no whitespace at either end that folds to none
- * of the seven words.
+ * One regex, so the published schema carries the same rule as a `pattern`; a pattern has no flags, hence the case classes.
  */
 const REFUSED_FOLDED = [...STANDARD_PERMISSIONS, ...PERMISSION_FOR_ROLE.keys()];
 const caseless = (word: string) => [...word].map((c) => `[${c.toUpperCase()}${c}]`).join("");