docs: a cce-ui change reaches a client only when that client is rebuilt

The toolkit is a static Rust library, so committing and installing cce-ui
changes nothing about the ~20 crates that link it. That is easy to miss
because `ccebuild status` cannot report it: cmd_status compares each
binary's mtime in target/release against the one in ~/.local/bin, so a
client nobody rebuilt has both old and equal and reads as up to date. It
is stale against a *dependency*, which is the one kind of staleness that
check has no notion of.

Learned the slow way from cce-ui@2416904, which raised each client's
RLIMIT_NOFILE: the fix was committed and cce-ui installed, and every
client still ran at the old limit until its own crate was rebuilt — thirteen
of them.

So the note records all three stages (commit, rebuild dependents,
relaunch), the one-cargo-invocation sweep, the reason to keep cce-browser
out of it, and the habit that catches a skipped middle stage: look inside
the installed binary for something the change introduced rather than
trusting that the build ran.

It goes here rather than in the root CLAUDE.md, which is unversioned and
lost on a fresh clone.

Co-Authored-By: Claude Opus 5 <[email protected]>

 CLAUDE.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8ff76e3..af25bb6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -91,6 +91,32 @@ script and the `.desktop` entries above both started out.
 `ccebuild restart` deliberately cannot reach the compositor: `cce-fx` is not a user
 unit (startcce launches it), and restarting it would tear down the session.
 
+**A change to `cce-ui` reaches a client only when that client is rebuilt.** The
+toolkit is a static Rust library, so committing and installing `cce-ui` itself
+changes nothing about the ~20 crates that link it — each has to be rebuilt and
+reinstalled before it carries the change. `ccebuild status` will not flag this:
+those binaries are not stale against *their own* sources, only against a
+dependency, which is exactly the case it cannot see.
+
+Then there is a second step: a **running** process keeps its old inode until it
+is relaunched (that is the `(deleted)` exe `status` and `restart` key on), and
+`cce-fx` itself keeps its own until the next login. So a toolkit fix lands in
+three stages — commit, rebuild dependents, relaunch — and it is the middle one
+that gets skipped.
+
+Learned from cce-ui@2416904, which raised each client's `RLIMIT_NOFILE`: the
+fix was committed and cce-ui installed, yet every client still ran at the old
+limit until its own crate was rebuilt. Sweep with one cargo invocation over the
+dependents (`cargo build --release -p ... -p ...`, one shape — alternating with
+a bare `--workspace` build re-resolves features and invalidates crates), then
+`ccebuild install --no-build <crate>` for each. Verify by looking *inside* the
+installed binary for something the change introduced, e.g.
+`strings ~/.local/bin/<crate> | grep -q '<new log string>'`, rather than
+trusting that the build ran. **Leave `cce-browser` out of such a sweep unless
+asked** — it builds Servo, which costs far more than the rest of the workspace
+combined; it keeps whatever toolkit version it was last built against until
+someone decides that trade is worth making.
+
 Building emits a harmless warning that per-package `[profile.*]` in this `Cargo.toml`
 is ignored because profiles are only honored at the workspace root.