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>

3 files changed, 61 insertions, 3 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 76a7bb8..c26ff7d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,6 +19,7 @@ modules.
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
                       calendar, OBS
       assistant/      the assistant canvas on SUPER+Home, a view over desktop-assistant
+      companion/      a chibi 2B, bottom-right of the focused monitor, on SUPER+\
     window-switcher/  expose: open windows scattered as live previews, on ALT+TAB
                       or the top-right hot corner of DP-1
     keybinds/         live keybind reminder, on SUPER+k
@@ -207,6 +208,12 @@ changing that component. The ones that generalise:
   `Settings.qml`, which imports Controls, `Button { icon: ... }` became the
   Controls button and logged `Unable to assign QString to QQuickIcon`. A file
   that imports Controls builds its buttons from a `Rectangle` instead.
+- **Plain `import QtQuick` shadows a directory's own `Sprite.qml` too.**
+  QtQuick ships a `Sprite` type (for `AnimatedSprite`), and an explicit
+  import beats the implicit directory one, so the companion's `Sprite {
+  onSettled: ... }` failed with `Cannot assign to non-existent property
+  "onSettled"` and took the whole desktop shell down on restart. It is
+  `Figure.qml`. Before naming a component, check it is not a QtQuick type.
 - **`FloatingWindow.maximized` works under Hyprland.** Setting it fills the
   monitor and clearing it restores the old size, checked by eye; the settings
   window's titlebar row uses it, since Hyprland draws no decorations.
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
diff --git a/docs/superpowers/specs/2026-10-23-companion-design.md b/docs/superpowers/specs/2026-10-23-companion-design.md
index 8acffbf..03feaff 100644
--- a/docs/superpowers/specs/2026-10-23-companion-design.md
+++ b/docs/superpowers/specs/2026-10-23-companion-design.md
@@ -59,10 +59,10 @@ assistant, so she reads its state directly. The cost, accepted: restarting
 ```
 desktop/companion/
   Companion.qml   the window, inputs, timers, IPC
-  Sprite.qml      draws a frame; crossfade, bob, squash, explosion
+  Figure.qml      draws a frame; crossfade, bob, squash, explosion
   Mood.js         which state wins, as a pure function (.pragma library)
   test_mood.js    node check of Mood.js, like assistant/test_md.js
-  lines.js        her English lines, grouped by reaction
+  Lines.js        her English lines, grouped by reaction
   prep-frames     bash + ImageMagick: generated images to frames/
   README.md       the component's notes
 ```
@@ -169,7 +169,7 @@ timers.
 
 ### Speech
 
-Fixed English lines from `lines.js`, picked at random per reaction, for
+Fixed English lines from `Lines.js`, picked at random per reaction, for
 example "...Operator, I'm bored.", "Typo again?", "Hey.", "Answer's
 ready.", "Glory to mankind.". A bubble shows 3 s. At most one line per
 30 s, except clicks and the self-destruct.