Merge pull request 'docs: rewrite negative patterns to positive actionable instructions' (#88) from docs/positive-language-rewrite into main

Reviewed-on: #88
2026-06-21 14:01:59 +02:00 · 2026-06-21 14:01:59 +02:00 · 99755fa8b7
commit 99755fa8b7
parent d1d420fb91 f10216db12
4 changed files with 91 additions and 82 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -3,16 +3,16 @@
 ## Agent Identity and Current Role Split
 The XFCE operator USB work now uses a git-coordinated split. Agents may review
-or suggest across boundaries, but should not silently take over another role's
+or suggest across boundaries, but must coordinate explicitly before taking over
-load-bearing responsibility.
+another role's load-bearing responsibility.
 | Role name                          | Identity                            | Owns                                                                                         | Restrictions                                                                                         |
 | ---------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | **Pi ISO Developer**               | Pi harness (this dev agent)         | Source changes, docs, static checks, commits, pushes                                         | Does not start ISO builds or flash media unless explicitly assigned                                  |
-| **Codex ISO Builder**              | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation                      | Should avoid broad source refactors; reports exact logs/output back through git or handoff notes     |
+| **Codex ISO Builder**              | codex pkg on the FreeBSD build host | `./build.sh`, mounted-image inspection, publishing, hardware validation                      | Focuses on targeted changes; broad source refactors require prior review; reports exact logs/output back through git or handoff notes     |
-| **Hermes USB/IMG Deployer**        | Hermes on Debian/Linux              | Downloading verified published artifacts, USB target identification, flashing                | Does not need git-host access; never flashes unverified artifacts or partition paths                 |
+| **Hermes USB/IMG Deployer**        | Hermes on Debian/Linux              | Downloading verified published artifacts, USB target identification, flashing                | Only flashes verified artifacts to whole-disk target paths; does not need git-host access                         |
-| **Claude Reviewer / XFCE Tweaker** | Claude (Linux)                      | Review/plans plus Track E XFCE GUI polish                                                    | Cannot build ISO, cannot run FreeBSD-only validation, should mark speculative runtime claims as such |
+| **Claude Reviewer / XFCE Tweaker** | Claude (Linux)                      | Review/plans plus Track E XFCE GUI polish                                                    | Builds ISO only through Codex ISO Builder; validates with Linux tooling; marks speculative runtime claims as such |
-| **Opencode / Z.ai Integrator**     | Opencode CLI on Linux               | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Cannot claim FreeBSD runtime proof; uses Sam-provided API keys only for provider validation          |
+| **Opencode / Z.ai Integrator**     | Opencode CLI on Linux               | Linux-side Colibri/dashboard experiments plus Pi/DeepSeek v4 provider-lane validation wiring | Validates on Linux and refers FreeBSD runtime claims to the build host; uses Sam-provided API keys only for provider validation          |
 | **Operator (Sam)**                 | Human operator                      | Product, hardware, acceptance, release judgment                                              | Human approval required for release/tagging decisions                                                |
 ## Agent / Codebase Check-In Matrix
@ -64,7 +64,8 @@ If it fails, format only the touched markdown files, then rerun the check:
 npx --yes prettier@3 --write path/to/file.md
 ```
-Do not hand-align Markdown tables or reflow prose manually. `.prettierrc` uses
+Use Prettier for all Markdown formatting; rely on tool-owned formatting
 rather than manual alignment. `.prettierrc` uses
 `proseWrap: preserve` so existing prose line breaks stay intentional, while
 Prettier still catches table padding, list spacing, and emphasis drift.
@ -72,8 +73,8 @@ Prettier still catches table padding, list spacing, and emphasis drift.
 `private/` is gitignored and may contain operator-private strategy notes or PRDs.
 Agents on this host may read files there only when directly relevant to the
-assigned work. Do not commit, quote, summarize publicly, or copy private content
+assigned work. Keep private content in `private/`; share to Forgejo only with
-to Forgejo unless the operator explicitly approves it.
+explicit operator approval.
 If working on custom ISO / hardware-report monetization, check
 `private/PRD-CUSTOM-ISO.md` when present. Codex ISO Builder should focus first
@ -83,12 +84,12 @@ surface should expose for report collection and review.
 ### Linux Agent Constraints
-Linux agents MUST NOT attempt to build the ISO (`./build.sh`, `./build-vps.sh`).
+Linux agents route all ISO builds to Codex ISO Builder on the FreeBSD
-ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`, `pkg`).
+host. ISO builds require FreeBSD system tools (`mdconfig`, `mount_msdosfs`,
-Instead, guide Codex ISO Builder with exact commands to run on the FreeBSD
+`pkg`). Instead, guide Codex ISO Builder with exact commands to run on the
-system.
+FreeBSD system.
-Agents on any platform MUST NOT start a new ISO build unless explicitly assigned.
+Agents on any platform start ISO builds only when explicitly assigned.
 Builds are long-running, mutate repo-local caches, and can leave mounted md(4)
 devices that require cleanup.
@ -110,8 +111,9 @@ the ISO does **not** build Rust while the image is mounted.
  the required binaries. Validation images can add the local fake-agent helper
  with `COLIBRI_STAGE_TEST_AGENT=YES`.
-**Invariant:** do not `cargo clean` `/home/clawdie/ai/colibri` until the ISO
+**Invariant:** preserve `/home/clawdie/ai/colibri/target/release` until the ISO
-preflight/build has consumed `/home/clawdie/ai/colibri/target/release`.
+preflight/build has consumed it; run `cargo clean` only after the ISO build
 completes successfully.
 ---
@ -120,8 +122,9 @@ preflight/build has consumed `/home/clawdie/ai/colibri/target/release`.
 The active branch target is the XFCE live operator USB. Authoritative state
 lives in `packages/` (what ships) and `PLAN-OPERATOR-USB-NEXT.md` (round-scope
 decisions and any "for now" retention notes). Final graphical validation
-requires real hardware — do not treat bhyve, nested VMs, or static image
+requires real hardware — treat bhyve, nested VMs, and static image
-inspection as final proof that SDDM/XFCE works.
+inspection as build gates only; real hardware is the final proof that
 SDDM/XFCE works.
 ---
@ -132,8 +135,8 @@ inspection as final proof that SDDM/XFCE works.
 - On the FreeBSD build host, operator-facing commands may use `sudo`.
 - Inside the live USB, `sudo` is intentionally absent.
 - Live privileged actions use FreeBSD `mac_do` via `mdo -u root <command>`.
- Agent runtime code must not shell out to `sudo` for privileged host changes.
+- Agent runtime code uses the hostd RPC layer for privileged host changes,
- Privileged Clawdie-AI host operations go through the hostd RPC layer.
+  routing through the hostd RPC layer instead of shelling out to `sudo`.
 ---
@ -148,11 +151,10 @@ PROJECT_TMP="$PROJECT_ROOT/tmp"
 mkdir -p "$PROJECT_TMP"
 ```
-Use `$PROJECT_TMP/...` for generated checks, transient logs, extracted manifests,
+Create all scratch files under `$PROJECT_TMP` for generated checks, transient
-image-inspection notes, helper-script test output, and other disposable files.
+logs, extracted manifests, image-inspection notes, helper-script test output,
-Do not create new `/tmp/clawdie-*`, `/tmp/colibri-*`, or ad-hoc `/tmp/...` paths
+and other disposable files. Use host-global `/tmp` paths only when the operator
-from agent work unless the operator explicitly asks for a host-global scratch
+explicitly asks for a scratch location outside the repo.
 location.
 Live-USB runtime code usually has no git checkout/project root. In that case,
 prefer an app-owned cache/state path such as `$XDG_CACHE_HOME/clawdie`,
@ -191,10 +193,10 @@ ISO builds use repo-local `tmp/` for large caches and output artifacts:
 - `tmp/output` — generated `.img.xz` artifacts and checksums
 - `tmp/packages` — fetched package archives
-`tmp/cache/mnt` is an ISO-builder-specific mountpoint exception. Do not mount
+`tmp/cache/mnt` is an ISO-builder-specific mountpoint exception. Use `tmp/`
-unrelated datasets, recovery filesystems, or scratch filesystems elsewhere under
+mounts only for ISO builder work (cache/mnt); mount unrelated datasets,
-repo `tmp/`. If a build is interrupted, use the `iso-build-cleanup` skill before
+recovery filesystems, or scratch filesystems elsewhere. If a build is
-retrying.
+interrupted, use the `iso-build-cleanup` skill before retrying.
 ---
@ -209,8 +211,8 @@ Clawdie spans three repos. Changes often require coordinated updates.
 | `Colibri`     | Cross-platform Rust control plane core   | `git@code.smilepowered.org:clawdie/colibri.git`     |
 Primary remote: `code.smilepowered.org` (self-hosted Forgejo, SSH via local host
-config). Codeberg is the public mirror only; do not treat it as the source of
+config). Treat `code.smilepowered.org` as the source of truth for agent
-truth for agent coordination or branch-state claims.
+coordination and branch-state claims; Codeberg is the public mirror only.
 When changes span both repos, create a handoff doc in the secondary repo
 listing what needs updating. See `Clawdie-AI/AGENTS.md` for full protocol.
--- a/BUILD.md
+++ b/BUILD.md
@ -55,7 +55,8 @@ from the running USB with `mdo -u root tailscale up`.
 ### Colibri artifacts
 The operator USB stages Colibri as the live control plane. It expects prebuilt
-FreeBSD release binaries; it does not compile Rust while the image is mounted.
+FreeBSD release binaries; Rust compilation takes place before image mounting,
 and only prebuilt binaries land on the mounted image.
 Default adjacent-checkout flow:
@ -119,8 +120,8 @@ Installed/deployed system
 No current ISO build flag stages `service clawdie`. That name is reserved for
 installed/deployed systems until the real persistent host service is chosen. The
-baseline live USB uses Colibri directly and must not ship the old mini-binary as
+baseline live USB ships Colibri directly and excludes the old mini-binary
-if it were the final deployed service.
+intended for the final deployed service.
 ---
@ -166,7 +167,8 @@ sudo dd if=tmp/output/clawdie-quindecim-0.10.0.img of=/dev/daX bs=1M status=prog
 sync
 ```
-Use the whole USB device (`/dev/daX`), not a partition. See [FLASHING.md](FLASHING.md)
+Target the whole USB device (`/dev/daX`); flashing to a partition is unsafe and
 unsupported. See [FLASHING.md](FLASHING.md)
 for Linux commands, checksum verification, and stale-label cleanup.
 ---
@ -262,7 +264,7 @@ Current implementation:
 **Distribution-safety note:** public keys are public, so baking one in is
 not a confidentiality issue — but anyone with the image file can SSH into a
 live boot of it. For dev/test builds that's the right tradeoff. For public
-release images, do not pass `--ssh-key` at all; operators add a key
+release images, omit `--ssh-key` entirely; operators add a key
 themselves after first boot or build their own image. The dedicated
 `clawdie-live-usb` key avoids leaking personal keys into shareable images.
@ -302,9 +304,9 @@ The implementation contract:
 **Scope discipline:** mDNS is **only** for LAN discovery of the live
 USB itself. Clawdie's internal service names continue to live under
 `home.arpa` (`ai.home.arpa`, `cms.home.arpa`, `git.home.arpa`,
-`<tenant>.home.arpa`). Do not switch internal services to `.local` —
+`<tenant>.home.arpa`). Keep internal service names under `home.arpa`;
-RFC 6762 reserves `.local` for mDNS, and mixing the two namespaces
+reserve `.local` exclusively for mDNS — RFC 6762 reserves `.local` for
-breaks both.
+mDNS, and mixing the two namespaces breaks both.
 **Network caveat:** some corporate networks, hotel Wi-Fi, and isolated
 guest VLANs block multicast traffic. In those environments
@ -319,10 +321,10 @@ open, inbound limited to SSH, mDNS, ICMP, DHCP-client, and Tailscale's
 UDP 41641. The actual access restriction on SSH is carried by `sshd`
 auth policy (pubkey only), not PF interface scoping.
-**No logging stack on disk or in memory by default.** `pflog_enable`
+**PF logging stack is opt-in by default.** `pflog_enable`
-and `pflogd_enable` are both left at their `NO` defaults. The ruleset
+and `pflogd_enable` remain at their `NO` defaults. The ruleset
-has no `log` keywords, so there is nothing to capture anyway. When
+has no `log` keywords, so nothing is captured by default. When
-debugging from a booted live USB, the operator brings the stack up by
+debugging from a booted live USB, the operator enables the stack by
 hand:
 ```sh
@ -471,8 +473,8 @@ path (fetched, not installed on live), but different long-term homes:
   ffmpeg/libpulse/mesa-libs/boost surface would partially un-do the
   lean-rootfs payoff we want during the early hardware-validation
   cycle. **Long-term home: back on the live USB** once dependency
-   surface is audited and operator workflow exists. Do not categorise
+   surface is audited and operator workflow exists. Classify it as
-   it as desktop-spin cruft in a future audit.
+   roadmap-essential in all future audits, not desktop-spin cruft.
 **Intent:** keep this table as the authoritative "what we will deploy
 to disk" reference so the work is not lost between commits. The
@ -609,9 +611,8 @@ When OSA gets tight on disk, prefer deleting **repo-local build artifacts**
 (`tmp/packages`, `tmp/cache/work.img`, cached FreeBSD memstick images, old output
 artifacts) over pruning host packages.
-Do **not** treat the remaining host-side graphics/media stack as disposable "old
+Preserve the remaining host-side graphics/media stack; it supports current
-X11". On OSA it is not a full desktop environment anymore; it is a shared runtime
+operator tooling and validation lanes, not an old X11 desktop:
 closure that supports current operator tooling and validation lanes:
 - `ffmpeg` + `py311-pillow` back the Hermes/image-render and screenshot path.
 - `gtk3`, `cairo`, `pango`, `fontconfig`, `libX11`, `mesa-*`, `wayland`,
--- a/PLAN-OPERATOR-USB-NEXT.md
+++ b/PLAN-OPERATOR-USB-NEXT.md
@ -16,9 +16,9 @@ Live boot has cleared the "does it come up at all on real hardware" gate.
 | NVIDIA     | Pending                | Laptop candidate arriving; not validated yet                                      |
 **Load-bearing decision: keep SDDM as the live display manager.**
-SDDM is the validated live display-manager path for Intel and AMD GUI boot. Do
+SDDM is the validated live display-manager path for Intel and AMD GUI boot.
-not replace it without equivalent real-hardware proof. SDDM is now part of the
+Retain SDDM until equivalent real-hardware proof validates any replacement.
-operator-USB contract.
+SDDM is now part of the operator-USB contract.
 Other now-stable pieces from recent commits worth not regressing:
@ -97,8 +97,8 @@ hook so regressions are caught on the next build.
   - `operator-workflow` (firefox, codex, pi tools, tmux, ...)
   - `diagnostic` (btop, hw-probe, dmidecode, ...)
   - `candidate-to-defer` (used rarely or replaceable by a base tool)
-     Write the result as comments next to each line; do NOT remove anything
+     Write the result as comments next to each line; categorize first and
-     yet — categorization first, removal in a follow-up.
+     defer removal to a follow-up round after the data is in.
 2. **Size accounting.** For each line, add the pkg + flat size as a
   trailing comment (`# 12M / 38M`). Use `pkg info -s <name>` on the
   FreeBSD build host. This makes future "is X cheap to add" calls honest
@ -108,7 +108,8 @@ hook so regressions are caught on the next build.
   - SDDM is enabled in `rc.conf`.
   - `clawdie-live-gpu` rc.d service is enabled.
   - Required kmods present in `/boot/modules` for Intel/AMD; NVIDIA
-     kmods are _present in the offline repo but NOT loaded by default_.
+     kmods are \textit{available in the offline repo} and remain unloaded
     unless explicitly configured.
   - Live operator pkg-list contents are actually installed in the image.
   - Panel module gates (`xfce4-mixer`, `clipman`) honor their runtime
     conditions (audio backend up, X session up).
@ -148,7 +149,7 @@ This round does **not** ship a full installer. It sets up the plumbing.
   built image in bhyve, runs the disk-install path with
   `CLAWDIE_PROFILE=xfce`, and asserts `blender` (the roadmap-essential
   member of disk-install-extras) ends up installed on the target disk.
-   Bhyve is fine for plumbing; per `AGENTS.md` it's NOT proof for
+   Bhyve is suitable for plumbing verification; use real hardware for
   graphical validation — leave that for Track A/E on real hardware.
 **Definition of done:**
@ -241,8 +242,8 @@ contract between agents.
  them.
 - FreeBSD safety remains local: builds, mounts, flashes, watchdog checks,
  and privileged host actions are not delegated to a remote chat agent.
- Do not add a separate dashboard/pane-fabric dependency to the live USB for
+- Rely on Colibri as the sole control-plane surface for this track; add no
-  this track; Colibri is the control-plane surface.
+  separate dashboard/pane-fabric dependency to the live USB.
 - Cross-host coordination starts with small JSON manifests and summaries;
  raw logs, screenshots, and pcaps move only on demand.
 - Skills should be additive and runnable without an interactive dashboard. The
@ -631,9 +632,9 @@ folder so `$HOME` stays uncluttered:
 **Implementation notes:**
- Seed clean checkouts or source snapshots only; do not copy API keys,
+- Seed clean checkouts or source snapshots only; include only code and exclude
-  `.env` files, SSH private keys, build caches, package caches, `tmp/`, or
+  API keys, `.env` files, SSH private keys, build caches, package caches,
-  other private host state.
+  `tmp/`, and other private host state.
 - Prefer the exact branch/commit used by the image build, recorded in
  `/usr/local/share/clawdie-iso/build-manifest.json` and visible from
  `hw-report`.
@ -644,8 +645,9 @@ folder so `$HOME` stays uncluttered:
 - If full `.git` history is too large, use shallow clones or archive snapshots
  plus a small manifest that records remote URL, branch, commit, and modified
  state.
- This is a live-debug aid, not a build-host replacement: Linux agents still do
+- This is a live-debug aid, not a build-host replacement: Linux agents direct
-  not build the ISO, and real hardware proof remains operator/Codex-owned.
+  build commands to Codex ISO Builder on the FreeBSD host, and real hardware
  proof remains operator/Codex-owned.
 **Why it matters:** when Colibri, XFCE, rc.d, input, or package-list bugs only
 show up on real hardware, a local Pi session can read `/var/log`, `hw-report`,
@ -743,8 +745,8 @@ I accept the **Codex ISO developer** role for this round:
 - docs/static checks
 - commits and pushes
-I do not treat GUI success as proven without Pi Builder / hardware output, and
+I treat GUI success as proven only with Pi Builder / hardware output, and
-I do not start ISO builds or flash media unless explicitly assigned.
+I start ISO builds or flash media only when explicitly assigned.
 ---
@ -753,7 +755,7 @@ I do not start ISO builds or flash media unless explicitly assigned.
 - VSCode or Cursor on the live image. Both deferred per project memory.
  VSCode is a candidate for disk-install extras _later_, after Track B
  gives us a real size + dep budget.
- Replacing SDDM. Load-bearing; do not touch.
+- Replacing SDDM. Load-bearing; SDDM stays as-is for this round.
 - KDE profile content. Track C only scaffolds the selector; KDE pkg list
  comes in a later round.
 - Linuxulator integration of any kind.
--- a/skills/iso-build/SKILL.md
+++ b/skills/iso-build/SKILL.md
@ -9,8 +9,9 @@ Use this skill for the normal FreeBSD host build path from the checked-out
 `clawdie-iso` repo. This is the current repo-local operator workflow, not the
 older “clone elsewhere and publish to nginx” flow.
-Only run an ISO build when the operator explicitly assigns it. If the task is
+Run ISO builds only when the operator explicitly assigns one. For planning,
-planning, docs, package-list edits, or static inspection only, do not build.
+docs, package-list edits, or static inspection tasks, use static checks
 instead of building.
 ## Current operator-USB expectations
@ -18,7 +19,7 @@ planning, docs, package-list edits, or static inspection only, do not build.
 - Live browser: Firefox, not Chromium
 - SDDM interactive login as `clawdie`; no live autologin
 - `CLAWDIESEED` exists as FAT32 slice 3 for post-flash, pre-boot seed import
- Live CLI policy: ship `codex`, `pi`, `gemini`; do not ship `claude`
+- Live CLI policy: ship `codex`, `pi`, `gemini`; omit `claude` from the live image
 - Operator editors: `mousepad`, `geany`, and `micro`
 - Hardware/custom-ISO report collector: `hw-report`
 - Vulkan diagnostic tool: `vulkaninfo` from `vulkan-tools`; Zed remains deferred
@ -53,7 +54,8 @@ conventions.
 - Prefer `tmux` for long builds
 - Use an elevated shell in the tmux pane so the build command itself runs
  without a `sudo` prefix
- Run one command at a time; do not hide failures behind chained shell commands
+- Run each command individually so failures are visible and attributable;
  chain commands only when a prior success is required and verified
 - Fetch before reporting remote state or starting a build
 - If disk is tight, the image build was interrupted, or `tmp/cache/mnt` is
  still mounted, use `iso-build-cleanup` first
@ -81,7 +83,8 @@ tmux capture-pane -pt clawdie:3.1 -S -30
 ps auxww | egrep '[b]uild.sh|[s]cript -q tmp/operator-usb-.*-build.log'
 ```
-If a build is still active, do not clobber it. Stop or wait deliberately.
+If a build is still active, preserve it — stop it deliberately or wait for
 completion before reusing the pane.
 ### 3. Start clean after a failed attempt
@ -133,11 +136,11 @@ switch to `iso-build-cleanup`.
 The operator USB uses Colibri as its lightweight live control plane. The ISO
 build stages FreeBSD-native Colibri artifacts from `/home/clawdie/ai/colibri`;
 it does **not** build Rust while the image is mounted. Validation builds should
-ship `colibri_daemon_enable=YES`; the rc.d service starts after LOGIN and must
+ship `colibri_daemon_enable=YES`; the rc.d service starts after LOGIN and
-not block SDDM/XFCE startup.
+completes before SDDM/XFCE are user-facing, avoiding any startup delay.
-Build Colibri on the FreeBSD/OSA host, not on Debian/Linux. Do not cross-ship
+Build Colibri on the FreeBSD/OSA host first; fall back to cross-shipping from
-from debby unless the native OSA build fails.
+debby only if the native OSA build fails.
 Run this before the ISO build:
@ -185,10 +188,10 @@ sh -n build.sh
 sh -n scripts/stage-colibri-iso.sh
 ```
-Important cleanup timing: **do not run `cargo clean` immediately after the
+Important cleanup timing: **preserve Colibri artifacts until the ISO build
-Colibri build.** The ISO preflight/build consumes `/home/clawdie/ai/colibri/target/release`.
+consumes them.** The ISO preflight/build reads from
-Only clean Colibri after the ISO build or after deciding those artifacts are no
+`/home/clawdie/ai/colibri/target/release`. Clean Colibri only after the ISO
-longer needed:
+build or after deciding those artifacts are no longer needed:
 ```sh
 cd /home/clawdie/ai/colibri
@ -206,16 +209,17 @@ should be verified with the required binaries.
 `service clawdie` is reserved for installed disk/server targets, but the current
 operator USB does not stage a `clawdie` rc.d service or mini-binary. The live USB
 uses `colibri_daemon` directly. Add deployed-system service packaging only after
-the real persistent host service implementation is chosen; do not repurpose the
+the real persistent host service implementation is chosen; keep the old
-old Colibri-side mini-binary as the final service by default.
+Colibri-side mini-binary for reference only until then.
 ### Next build: carry the XFCE operator-USB fixes
 The next operator-USB image must retain the proven XFCE/live-GUI fixes
 (`PLAN-OPERATOR-USB-NEXT.md`, `doc/AMD-ASUS-XFCE-LIVE-USB-FINDINGS.md`):
- **SDDM remains the supported live display manager** — load-bearing; do not
+- **SDDM remains the supported live display manager** — load-bearing; retain
-  replace without equivalent real-hardware proof for Intel + AMD live GUI boot.
+  SDDM until equivalent real-hardware proof validates any replacement for
  Intel + AMD live GUI boot.
 - **`clawdie-live-gpu`** pre-SDDM rc.d KMS pick (conservative; NVIDIA/AMD safe).
 - **Hardened USB-root power policy** (`b9290ab`): `powerdxx`, C3 C-state default,
  `hw.usb.no_suspend=1`, boot-time `power_profile`.