companion: README, AGENTS listing, Lines.js and Figure.qml in the spec

The README records the measurements the code depends on: where typing
and BackSpace come from, why the dodge waits for the pointer, the
IdleMonitor enabled default, and fullscreen 2 against maximised 1.
AGENTS.md gains the QtQuick Sprite trap beside the Controls Button one,
since it took the desktop shell down on restart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 51 insertions, 0 deletions

diff --git a/desktop/companion/README.md b/desktop/companion/README.md
new file mode 100644
index 0000000..e0eaaf3
--- /dev/null
+++ b/desktop/companion/README.md
@@ -0,0 +1,51 @@
+# companion
+
+A chibi 2B in the bottom-right corner of the focused monitor, on SUPER+\.
+The design, with what was measured on the way, is
+`docs/superpowers/specs/2026-10-23-companion-design.md`.
+
+## Files
+
+| File | |
+| --- | --- |
+| `Companion.qml` | the window, inputs, timers, speech, IPC (`companion toggle/show/hide`) |
+| `Figure.qml` | draws a frame: crossfade, bob, drop out and back, explosion |
+| `Mood.js` | which state wins, from a snapshot; all the timings are its `T` |
+| `Lines.js` | her lines and the opening monologue |
+| `prep-frames` | generated images to display frames |
+| `gen-frames`, `frames.txt` | the generated images, through sd-server |
+
+`Figure.qml` is not `Sprite.qml` because QtQuick has a `Sprite` type, and
+it wins over the directory's own file (see AGENTS.md).
+
+## Art
+
+Not in the repo: the character is Square Enix's and this repo is GPLv2.
+It lives in `~/.local/share/keystone/companion/2b/`:
+
+    dress/<name>.png, leotard/<name>.png   generated, 1024x1024 on white
+    frames/<outfit>/<name>.png             what she shows, from prep-frames
+    recipe.txt                             how each was made, and what failed
+
+Run `prep-frames` after adding or replacing any generated image. A missing
+frame falls back to its outfit's `base`.
+
+## Inputs
+
+- Typing and BackSpace come from `sections/companion.lua` in the
+  hypr-theme repo, as `custom>>keystone-typing` and
+  `custom>>keystone-delete` on socket2. Nothing else about the keyboard
+  reaches her. The BackSpace bind is `non_consuming`; checked by hand that
+  it still deletes in a terminal and in the browser.
+- She only feels the pointer while it is over her: Quickshell has no
+  global pointer and Hyprland sends no motion events. Hence the 0.6 s
+  dodge rather than moving away as the pointer approaches.
+- `IdleMonitor.enabled` read false on creation when left out, so each of
+  the three sets it.
+- Fullscreen is `lastIpcObject.fullscreen === 2`. Maximised is 1, and
+  most windows here are maximised.
+- The lock screen covers every layer, so locking needs no code.
+
+## Check
+
+    node desktop/companion/test_mood.js