docs: record the theme-Proxy identity trap and the agent-drivable live smoke #51

Merged

owlburtoe merged 1 commit from clfy-docs-proxy-trap-smoke into master

2026-07-16 21:33:52 -04:00

owlburtoe commented

2026-07-16 21:21:36 -04:00

Owner

Docs only — no code. Three facts learned shipping #49/#50 that CLAUDE.md should carry.

1. New "convention that bites": pi's Theme arrives as two object identities

pi hands claudify the same logical theme as both the instance and a forwarding Proxy,
sharing one fgColors container. Keying per-theme state on the theme object gives each
identity its own entry — so whichever arrives second sees claudify's own override already
installed and misrecords it as the theme's original, permanently stranding the override.

This is what broke accentColor: theme restore (fixed in #49, c78b609). It was latent for
the claude accent too, pre-dating that work. Key such state on theme.fgColors instead,
which forwards through the Proxy. Worth a standing warning because any future per-theme state
in index.ts walks into it.

2. The pi-session rule was true but misleading

"Do not launch an interactive pi session — pi hangs forever under a headless pseudo-terminal"
made the mandated pre-release smoke a human-only step. Headless is the operative word: a
detached tmux session gives pi a real PTY, and an agent can drive it with tmux send-keys
and read it with tmux capture-pane -e -p.

Proven this session — the entire CLFY-21 smoke ran unattended: opened /claudify, walked
Hub → Theme → Accent, committed a custom hex, watched it recolor live, switched back to
theme, confirmed pi's teal restored, and pressed / to exercise slash-autocomplete (the
2.3.0 crash reproducer). The rule is corrected rather than deleted — the headless-hang fact is
still true and still worth warning about, and the tests remain the day-to-day verification.

3. The smoke needs BOTH package declarations swapped

~/.pi/agent/settings.json and <repo>/.pi/settings.json each declare
npm:@owlburtoe/pi-claudify. Swap only one and the smoke silently exercises the published
npm build — which is exactly how the first 2.3.1 smoke attempt tested the broken copy.
CLAUDE.md hinted at this; it is now unambiguous that it is two files.

Validation

Documentation only; no code touched, so the suite is unaffected (master was 15/15 green and
tsc --strict clean at af8eeaf). AGENTS.md is a symlink to CLAUDE.md and follows
automatically.

Docs only — no code. Three facts learned shipping #49/#50 that CLAUDE.md should carry. ## 1. New "convention that bites": pi's Theme arrives as two object identities pi hands claudify the same logical theme as **both the instance and a forwarding Proxy**, sharing one `fgColors` container. Keying per-theme state on the theme *object* gives each identity its own entry — so whichever arrives second sees claudify's own override already installed and misrecords it as the theme's original, permanently stranding the override. This is what broke `accentColor: theme` restore (fixed in #49, `c78b609`). It was **latent for the `claude` accent too**, pre-dating that work. Key such state on `theme.fgColors` instead, which forwards through the Proxy. Worth a standing warning because any future per-theme state in `index.ts` walks into it. ## 2. The pi-session rule was true but misleading "Do not launch an interactive pi session — pi hangs forever under a headless pseudo-terminal" made the mandated pre-release smoke a human-only step. **Headless** is the operative word: a detached **tmux** session gives pi a real PTY, and an agent can drive it with `tmux send-keys` and read it with `tmux capture-pane -e -p`. Proven this session — the entire CLFY-21 smoke ran unattended: opened `/claudify`, walked Hub → Theme → Accent, committed a custom hex, watched it recolor live, switched back to `theme`, confirmed pi's teal restored, and pressed `/` to exercise slash-autocomplete (the 2.3.0 crash reproducer). The rule is corrected rather than deleted — the headless-hang fact is still true and still worth warning about, and the tests remain the day-to-day verification. ## 3. The smoke needs BOTH package declarations swapped `~/.pi/agent/settings.json` **and** `<repo>/.pi/settings.json` each declare `npm:@owlburtoe/pi-claudify`. Swap only one and the smoke silently exercises the **published npm build** — which is exactly how the first 2.3.1 smoke attempt tested the broken copy. CLAUDE.md hinted at this; it is now unambiguous that it is two files. ## Validation Documentation only; no code touched, so the suite is unaffected (master was 15/15 green and `tsc --strict` clean at `af8eeaf`). `AGENTS.md` is a symlink to `CLAUDE.md` and follows automatically.

owlburtoe added 1 commit

2026-07-16 21:21:36 -04:00

docs: record the theme-Proxy identity trap and the agent-drivable live smoke

Plane Sync / Close referenced Plane work items (pull_request) Successful in 1s

Details

83f634f482

The accent-restore bug fixed in #49 came from keying per-theme state on
the theme object while pi hands over both the instance and a forwarding
Proxy; record that as a convention that bites.

Also correct the pi-session rule: headless is the operative word — a
detached tmux session gives pi a real PTY, so the mandated pre-release
smoke is now agent-drivable. Note that it targets the local checkout
only when both package declarations are swapped.

owlburtoe merged commit 1e4d037f5a into master

2026-07-16 21:33:52 -04:00

owlburtoe deleted branch clfy-docs-proxy-trap-smoke

2026-07-16 21:33:52 -04:00

owlburtoe referenced this pull request from a commit

2026-07-16 21:33:54 -04:00

Merge pull request 'docs: record the theme-Proxy identity trap and the agent-drivable live smoke' (#51) from clfy-docs-proxy-trap-smoke into master

owlburtoe referenced this pull request

2026-07-16 21:43:39 -04:00

chore: release 2.4.0 #52