Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions .agents/skills/fleet-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,14 +133,19 @@ Recorded **2026-08-21**: a lane was branched from an unrelated `backdrop-blur` c
integration branch, so the symbol its task depended on did not exist.

```sh
MAIN=/Users/gleblinnik/Developer/plex/plex-native-poc
MAIN=/Users/gleblinnik/Developer/plx-native
FLEET=${PLX_FLEET_DIR:-$MAIN/.claude/worktrees} # the external fleet volume when one is configured
git -C "$MAIN" fetch origin # `git log --all` reads only refs you HOLD
BASE=$(git -C "$MAIN" rev-parse origin/main) # or the integration branch
git -C "$MAIN" worktree add -b fleet/<lane> "$MAIN/.claude/worktrees/<lane>" "$BASE"
git -C "$MAIN" worktree add -b fleet/<lane> "$FLEET/<lane>" "$BASE"
```

`.claude/worktrees/` is gitignored (`.gitignore:31`) and is where this project's agent worktrees
already live — three of them on 2026-08-23, beside the main checkout. Verify **from inside the
already live — three of them on 2026-08-23, beside the main checkout. A machine with
`$PLX_FLEET_DIR` set to a second volume instead places the WHOLE lane there: the invariant is
not the directory, it is that a lane's build trees live inside its own checkout (see below), and
`make disk`, `tools/build-gc.sh --orphans` and the disk-budget planner all read
`$PLX_FLEET_DIR`, so external lanes are visible to the same reclaims. Verify **from inside the
lane**, before any work; the worker prompt makes this the first command:

```sh
Expand Down Expand Up @@ -254,7 +259,7 @@ Only two are worth copying, and the list is shorter than it looks because the to
reaches back to the main checkout:

```sh
WT=$MAIN/.claude/worktrees/<lane>
WT=$FLEET/<lane>
cp "$MAIN/src/config.local.h" "$WT/src/" # PMS host + token
cp "$MAIN/tests/manifest.local.json" "$WT/tests/" # only for ./tests/run.py --server
```
Expand Down
41 changes: 39 additions & 2 deletions .agents/skills/tv-session/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,12 @@ read from the gitignored `src/config.local.h` at runtime and never printed.
```bash
tools/tv-session.sh up [--flavor <f>] [--screen <name>] [--server <slot>] [--stream[=PORT]] [--remote[=PORT]] [--no-token]
tools/tv-session.sh status [--flavor <f>] # re-assert without disturbing the session
tools/tv-session.sh key down down ok # key tokens through the real handlers
tools/tv-session.sh key down down ok # key tokens through the real handlers (never focus:/press:/state:)
tools/tv-session.sh click 960 540 # authored 1920x1080 coords
tools/tv-session.sh focus watchlist.grid.card.7 # move focus to an element BY ID (no key walk)
tools/tv-session.sh press nav.watchlist # focus it, then an OK press
tools/tv-session.sh press home.shelf.0.card.2 --rk <ratingKey> # an element that acts on a title it names (card, credit, hero button, menu row, player Next...) REQUIRES the title it must be
tools/tv-session.sh state [--out FILE] # the app's JSON snapshot: route, owner, focused id, every element
tools/tv-session.sh shot [out.png] # panel capture (video plane included)
tools/tv-session.sh log [--flavor <f>] [regex] # the on-device event log
tools/tv-session.sh screen off|on # blank/restore the PANEL only (app keeps running)
Expand Down Expand Up @@ -289,7 +293,40 @@ a log you did not watch being produced.

Every `plxnative-*` trigger in the install's runtime root is read **once at boot**, so it
must be in place before the launch. Anything you want to do to a *running* app goes through
the remote FIFO (`tv-session.sh key` / `click`).
the remote FIFO (`tv-session.sh key` / `click`, or by id: `focus` / `press` / `state`). `key` sends keys
and the like (`down`, `ok`, `ck:<x>,<y>`, `txt:...`) and refuses a `focus:`, `press:` or `state:` word, so each
by-id action has ONE door, the verb, where the id is checked and a title's press must name the title. A word
with whitespace in it is refused too (`key back "ok press:<card>"`): the app cuts a FIFO line at any
whitespace, so it would be two tokens, the second a press nothing had checked.

**Prefer `focus` / `press` by id over key walks.** A walk of `down down right ok` breaks when a row
gains a card; an id (`watchlist.grid.card.7`, `detail.hero.go_to_show`; the grammar is in `tools/a11y.py`)
names the element whatever the row holds. Ids resolve in the namespace of whoever owns input, so a
menu answers `itemmenu.*`, not the screen under it. A press of any element that ACTS ON a title it names (it
plays, restarts, finishes or retries it, marks it watched or unwatched, bookmarks it, acts on the title a menu was
opened for, or opens that title's own page or menu where the title can change under the press: a card, a credit,
the Home carousel's Info, a hero button, an item-menu row, a Play Version row, a player control that starts a
title) needs `--rk <ratingKey>`, the ratingKey of the title the press acts on, which `state` prints as the element's
subject (Mark watched on a started show is the on-deck episode, a player's Next the queue neighbour). Navigation is
not the test: only a control whose target the page fixes (`detail.hero.go_to_show`, the Play Version opener, a
panel opener such as `player.control.subtitles`, a seek, `home.hero.action`) is pressed bare. The ids are
`SUBJECT_BEARING` in `tools/a11y.py`, the one list (`a11y_subject_bearing` in `tools/tv-session.sh` is the same
list, and a test holds them equal), so a re-sorted row, a moved hero or a menu opened on another card cannot press a
different title: the subject is compared where the press is delivered, and the press commits about 200 ms later, so
Home's carousel does not turn while a press stands on a hero control (the 8 s countdown restarts from full while
the press stands, as a focus move restarts it, so no turn is owed when the press settles and the next one comes a
full interval later; Flip and Left/Right at the edge are refused while it stands, dropped rather than applied
when it settles, so send them again then), which keeps the title the press was accepted
against the title it plays (a landing that takes that title out of the hero pool inside the 200 ms is the one
change nothing holds: the press then acts on its successor). At Home's hero/grid door
a quick OK after a key lands on what the picture shows, not on the focused
element: while the picture lags (about 8 frames, 130 ms at 60 fps: the dive's midpoint), a by-id press of the focused element, named or bare, is
refused as `unloaded` (`a11y: refused press <id> unloaded`), and you press again once the screen has settled. On a
real account the `ratingKey` you name must be one you read from the log (the boot rule: never `ok` a title you have not read). `state` is the
structured readback: it sends a random nonce and reads `plxnative-a11y.json` until the nonce comes
back, so a stale file never passes for the answer. Walks stay for tests whose subject is travel
(fps walks, focus fingerprints, `hold`, timed keys). These need a debug (`devtriggers`) build;
a release build answers none of them.

**Some exceptions are deliberate and read LIVE**: `plxnative-failtest` (so a read-out variant
can be swapped mid-playback), `plxnative-testpat` (the same for the synthetic ground),
Expand Down
27 changes: 27 additions & 0 deletions .agents/skills/ui-sim/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,33 @@ Tokens: `up`/`down`/`left`/`right`, `ok`, `back`, `play`/`pause`/`stop`, `ck:X,Y
authored 1920×1080 coords), `okdown`/`okup` (split halves — the only way to drive a press-and-hold
past `press::LONG_MS`), and `shot` (simulator only).

**Reach a target by id, not by walking to it.** A debug (`devtriggers`) build also takes
`focus:<id>`, `press:<id>` (focus, then an ordinary OK) and `press:<id>@<subject>` (refuses and
presses nothing when the element the id NAMES carries another subject than the one given), plus
`state:<nonce>`, which writes `plxnative-a11y.json` in the runtime dir (route, owner, the focused full
id, every element's id, role, rect, `visible`, `loaded`, label and subject) with the nonce echoed back.
An id is a place-based dot path (`nav.watchlist`, `watchlist.grid.card.7`, `detail.hero.play`) in the
namespace of whoever OWNS input, so inside a menu it is the menu's (`itemmenu.watchlist_remove`); a
refusal presses nothing and logs `a11y: refused <act> <id> <reason> owner=<ns>` (`unloaded` is not
an error: the element is not pressable yet, a card whose item has not landed or Home's focused element while its picture
lags a key across the hero/grid door, so press again once the screen has settled). `tools/a11y.py` writes
the tokens (`focus`, `press`) and reads the answer (`expect_focus`). Prefer these over key walks; a walk
stays where the test's subject IS the travel (fps walks, focus fingerprints, a held key).

The simulator boots against the owner's real server unless you aim it at the mock, and OK on a title
can play it, so the command line refuses to press one UNNAMED: `python3 tools/a11y.py press <runtime>
<id>` WITHOUT `--subject <ratingKey>` (and `send press:<id>` without an `@<subject>`) exits 2 and sends
nothing when the id is of an element that ACTS ON a title it names (it plays, restarts, finishes or retries it,
marks it watched or unwatched, bookmarks it, acts on the title a menu was opened for, or opens that title's own page
or menu where the title can change under the press: a card, a credit, the Home carousel's Info, a hero button, an
item-menu row, a Play Version row, a player control that starts a title; only a control whose target the page fixes
stays bare). `SUBJECT_BEARING` in `tools/a11y.py` is the one list of those ids, and the key to name is the ratingKey
of the title the press acts on, which `state` prints as the element's subject. Read the ratingKey from `state`
first. The library functions `a11y.press` / `press_token` stay unguarded, for a script that drives the mock (a
script that imports them against a real server has no check). `a11y.py
send` writes ONE token: a word with whitespace in it (`send "back press:<card>"`) exits 2 and sends
nothing, because the app cuts a FIFO line at any whitespace and the second token would skip that guard.

A desktop keyboard also works directly in `make sim-macos-run`: arrows, RETURN, ESC (`is_ok`/`is_back`
have always accepted keyboard keys), plus space=pause, `p`=play, `s`=stop, backspace=BACK.

Expand Down
Loading
Loading