From f6b8e1001f7f6ae0769557b52bc782a57362abb7 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:14:46 +0100 Subject: [PATCH 1/2] docs: site build names its one write outside the output directory The site chapter's opening and the public one-line description of `abcd site build` both said the build writes only inside the directory it is given. Since the build completes a ui.json that lacks a declared label (addMissingLabels, called from Build unless LeaveUI), it also writes that one file outside the output directory. The chapter's Behaviour section already records the exception; the opening now matches it, and the manifest sentence (regenerated into the CLI reference, the surface snapshot and `site build --help`) names the label write. Found by the v0.12.0 docs review at df8815a58. Assisted-by: Claude:claude-opus-5-5 --- .abcd/development/brief/04-surfaces/22-site.md | 3 ++- .abcd/development/release/surface.json | 2 +- docs/reference/cli/commands.md | 2 +- internal/core/surface/sentences.go | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.abcd/development/brief/04-surfaces/22-site.md b/.abcd/development/brief/04-surfaces/22-site.md index 9373110b8..818dd55b2 100644 --- a/.abcd/development/brief/04-surfaces/22-site.md +++ b/.abcd/development/brief/04-surfaces/22-site.md @@ -14,7 +14,8 @@ to remember to update it. The bare form is **strictly read-only**: it reports what the repository has declared and what the output directory holds. The build is the render, and it writes -only inside the directory it is given. The check that gates a rendered tree is the site +inside the directory it is given, and outside it only the missing-label completion +of the interface-string file (below). The check that gates a rendered tree is the site target of the one lint ([`16-lint.md`](16-lint.md), itd-2609212130136102): it renders first when the directory holds no `index.html` — the one write path besides the build, confined to the same directory. Bare `abcd lint` runs the diff --git a/.abcd/development/release/surface.json b/.abcd/development/release/surface.json index b53c48608..fdc4f9435 100644 --- a/.abcd/development/release/surface.json +++ b/.abcd/development/release/surface.json @@ -2738,7 +2738,7 @@ { "path": "abcd site build", "hidden": false, - "sentence": "Render the website into the output directory: Writes only inside that directory; refuses a non-empty directory it did not write.", + "sentence": "Render the website into the output directory: Writes there, plus a missing label into site-src/ui.json; refuses a non-empty directory it did not write.", "flags": [ { "name": "commit", diff --git a/docs/reference/cli/commands.md b/docs/reference/cli/commands.md index 9d7627c5d..cf623dc83 100644 --- a/docs/reference/cli/commands.md +++ b/docs/reference/cli/commands.md @@ -2981,7 +2981,7 @@ Report what the website declares and what was built: Writes nothing; refuses any #### `abcd site build` -Render the website into the output directory: Writes only inside that directory; refuses a non-empty directory it did not write. +Render the website into the output directory: Writes there, plus a missing label into site-src/ui.json; refuses a non-empty directory it did not write. **Usage:** `abcd site build [flags]` diff --git a/internal/core/surface/sentences.go b/internal/core/surface/sentences.go index 608c4c392..1e7dde5dd 100644 --- a/internal/core/surface/sentences.go +++ b/internal/core/surface/sentences.go @@ -323,7 +323,7 @@ var sentences = map[string]string{ "abcd site": "Report what the website declares and what was built: " + "Writes nothing; refuses any argument.", "abcd site build": "Render the website into the output directory: " + - "Writes only inside that directory; refuses a non-empty directory it did not write.", + "Writes there, plus a missing label into site-src/ui.json; refuses a non-empty directory it did not write.", "abcd site setup": "Take the website from this checkout to a live address: " + "Writes its files, and the forge and host changes once confirmed; refuses a folder abcd does not manage.", From 1a589512612f913f47ceefa82778027141a6d445 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:14:48 +0100 Subject: [PATCH 2/2] docs: describe drain's placement comment against the verb as built The comment beside drain's help placement said the verb's one form is a dry run until the run is built. The run form exists: each invocation performs one move and names the run an agent drives. The comment now says so; the placement itself is unchanged. Assisted-by: Claude:claude-opus-5-5 --- internal/surface/cli/helpgroups.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/internal/surface/cli/helpgroups.go b/internal/surface/cli/helpgroups.go index 6c08a1203..a8a2d3e19 100644 --- a/internal/surface/cli/helpgroups.go +++ b/internal/surface/cli/helpgroups.go @@ -142,8 +142,9 @@ var helpPlacements = map[string]helpPlacement{ "intent prepass": {page: "commands/intent.md"}, // itd-146 decision 2 files drain under records, but the person's list is at - // its fifteen-verb ceiling, and until the run is built the verb's one form - // is a dry run an agent reads. Listed here until the product thinker rules. + // its fifteen-verb ceiling, and each run invocation performs one move and + // names the run an agent drives with `implement step`, so an agent reads it + // either way. Listed here until the product thinker rules. "drain": {group: groupAgents, page: "commands/drain.md"}, }