@bitefoundry/retrieviewer 0.0.2 → 0.0.4

package/ASSET-PROVENANCE.md

@@ -35,6 +35,12 @@ must be checked again for the final release bytes.
 
 ## Remaining limits
 
+Later source candidate: belly/sleep reuse existing licensed roll/rest frames.
+Tug adds eight built-in imagegen keys referenced only from the existing generated
+puppy sheet, not new photographs. COMFORT-ART.md records the prompt, source hash
+and fixed-scale preparation. The ninth archive is covered explicitly by
+ASSETS-LICENSE.md and ATTRIBUTION.md. Original sheet PNGs remain outside npm.
+
 Copyrightability of AI-generated expression, the precise derivative-work analysis,
 and worldwide name clearance are not conclusively determined here. Existing
 domestic trademark research records possible similar marks; owning an npm scope

package/ASSETS-LICENSE.md

@@ -15,7 +15,7 @@ photographers retain their rights under their original licenses.
 
 ## Covered assets
 
-These eight artwork archives and their associated pose/registration metadata,
+These nine artwork archives and their associated pose/registration metadata,
 decoded images and alternative encodings are covered:
 
 - `puppy-stride-tweens-q5.bin.gz`
@@ -26,6 +26,7 @@ decoded images and alternative encodings are covered:
 - `puppy-paper-behaviors-q5.bin.gz`
 - `puppy-paper-actions-v9-q5.bin.gz`
 - `puppy-companion-interactions-v3-q5.bin.gz`
+- `puppy-companion-comfort-q5.bin.gz`
 
 ## Practical summary
 

package/ATTRIBUTION.md

@@ -47,7 +47,12 @@ change description if you modify it, in a manner reasonable to the medium.
 
 AI-generated pose sheets were extracted, aligned, interpolated, contact-corrected
 and encoded as 32-level Q5 frame stores. These are modifications, not unaltered
-photographs or motion capture. The package contains eight generated-art archives.
+photographs or motion capture. The package contains nine generated-art archives.
+The comfort extension reuses the existing roll/rest poses and adds eight
+AI-generated tug keys, registered at one scale with the existing seat as its
+animation endpoint. No additional photographic or video inputs were used for
+this extension. Its source hash and preparation are recorded in COMFORT-ART.md
+and puppy-companion-comfort.json; the same artwork license applies.
 Reference photo collections, YouTube footage, experimental Meshy models,
 noncommercial motion research/datasets, interpolation tools/model weights and
 worker logs are not distributed in this package. No exclusive copyright in

package/COMFORT-ART.md

@@ -0,0 +1,65 @@
+# Comfort extension art record
+
+Source code MIT; generated puppy art and frame data CC BY-SA4.0, retaining the
+credits in ATTRIBUTION.md. This is a development-source record, not new legal
+clearance. No external photograph, YouTube frame or downloaded rig was introduced.
+
+## Assets and preparation
+
+- Belly-up: existing v9 `roll-down`, eased to its measured `roll7` edge boundary,
+  held without a new bitmap, then completed to the existing seat.
+- Sleep: existing `rest` eyes-closed endpoint. The body does not zoom or squash.
+  A small code-drawn rising z cue is silent; no audio engine is installed.
+- Tug: built-in imagegen output from the existing generated
+  `puppy-behaviors16-sheet.png` identity reference. Original PNG is preserved at
+  `dist/comfort-art/tug-source-v1.png` locally and is not bundled in npm.
+  SHA-256: `10fde9dacca5cb45acd68f387e7ed3bcf88cd72cf0f9c4220d31d819db91731e`.
+  Eight keys plus the original seat are packed in
+  `puppy-companion-comfort-q5.bin.gz`; registration/hash/byte counts are in
+  `puppy-companion-comfort.json`. One scale is applied to all poses; only ground
+  and body-center translation varies. Playback repeats discrete authored keys,
+  not opacity crossfades, whole-body scale animation or a pre-expanded30fps film.
+
+Rebuild (development only, Python Pillow plus existing Node codec):
+
+```sh
+node tools/prepare-comfort-art.mjs /absolute/path/to/tug-source-v1.png
+node tools/check-comfort.mjs
+```
+
+Runtime does not use Python/Pillow or image-generation services for these poses.
+The reference/output/preparation originals are preserved; existing runtime art
+archives were not overwritten. Windows off-screen snapshots are diagnostic,
+not final end-user approval. Other-platform live appearance remains unverified.
+
+## Generation prompt (built-in tool)
+
+Use case: stylized-concept. Project asset: Retrieviewer tiny tug-play sprite
+sheet, faithful to the input reference puppy. The reference image is identity/style
+reference, not an output to edit. Create ONE2048x1024 sprite sheet: exactly4 equal
+columns and2 equal rows, eight separate full-body isolated sprites on absolutely
+pure black, no borders, no lettering or grid. Every cell is exactly512x512. Same
+adorable fluffy pale golden retriever puppy, realistic soft long fine fur, black
+nose/eyes, small dark bandana as input. Grayscale only. Fixed frontal slightly
+elevated viewpoint matching reference third row seated puppy. Fixed optical focal
+length, same head/body proportions and puppy scale, identical grounded paw
+baselines at y=456 inside every cell and centered body. Body silhouette about290px
+wide. ALL eight cells show the puppy seated with front paws planted in exact same
+place: no jumps, no camera moves, no size changes, no head squashing or body
+inflation. A small pale braided rope tug toy runs horizontally through mouth and
+extends to puppy's right, without human/hand. First cell: puppy curious, mouth just
+about to grip rope. Second: gently closing jaws around rope, naturally opening
+mouth. Third: firm grip, lower jaw and muzzle believable. Fourth: gently leaning
+just the head back8px while rump and paws planted. Fifth: holding same toy, head
+tugs8px left, both eyes focused on toy. Sixth: head tugs8px right (tiny sideways
+pull), ears follow naturally. Seventh: eases back to center and loosens grip.
+Eighth: lets go and faces viewer, happy soft closed mouth; toy end just below nose.
+Make each cell an adjacent pose of the SAME animation with extremely small
+differences. No dot dithering, no ASCII, no pixel blocks; preserve detailed soft
+fur, runtime will convert to fine Braille. No extra limbs, no new collar, no
+cartoony cylinders, no shadows or floor background. Full tail/body entirely inside
+each cell, ample pure-black margin.
+
+Observed output is1774×887 rather than the requested size; the preparation script
+extracts equal cells from actual dimensions. The resulting authored keys still
+need visual review for small body/face differences at transitions.

package/DESKTOP-PLATFORMS.md

@@ -0,0 +1,75 @@
+# Native desktop adapters — 0.0.4
+
+Version0.0.3 includes Windows, Linux X11 and experimental macOS adapters. Windows
+and the AlmaLinux8 X11 baseline have live verification; macOS has no runtime verification.
+Installation takes two steps: `npm install -g @bitefoundry/retrieviewer`,
+then `retrieviewer desktop`. No app patch, wrapper, shell profile or auto-start entry.
+
+Version0.0.4 adds compact comfort behaviors and the tug control. Windows native
+checks were repeated. New Linux/macOS control changes have grammar/protocol
+checks, not new live GUI verification; the Linux live evidence below is the
+earlier0.0.3 baseline. macOS remains experimental.
+
+## Design and status
+
+| Platform | Adapter | Current verification boundary |
+| --- | --- | --- |
+| Windows10/11 | .NET Framework/Win32 layered window | Live verified; shared-adapter regression checks passed on this host |
+| macOS | Built-in osascript/JXA AppKit, no Python/Xcode/browser runtime | Experimental; no macOS runtime available on this Windows host |
+| Linux X11 | Python3.6+ stdlib ctypes + X11/Xrender/Xext | AlmaLinux8 GLIBC2.28/Python3.6.8/Node22.23.4 live checks passed on owned Xvfb + Openbox + xcompmgr |
+| Linux native Wayland | No arbitrary-window tracking adapter | Refused, including sessions exposing an Xwayland DISPLAY; no insecure compositor workaround |
+
+Linux needs a running Xorg/X11 desktop with an ARGB visual, SHAPE input extension
+and a compositing window manager. A headless/server-only AlmaLinux installation
+cannot display desktop windows. System Python3.6+ is used; AlmaLinux8's
+`/usr/libexec/platform-python` is a fallback. No pip packages, GTK, Qt, Electron,
+native npm addons or on-machine C/C++ compilation are required on Linux. Missing
+capabilities cause a clear error rather than silently installing packages or
+changing a login/session/privacy setting. The source must not require a newer
+GLIBC just because the development workstation has one.
+
+AlmaLinux8 users should use an officially maintained Node22 build compatible
+with their GLIBC2.28 system. The package's Node>=20 range is not a promise that
+every future upstream Node binary will run on an old OS. The baseline test uses
+official Node22.23.4 linux-x64, SHA256
+`1805bcd35e6815559bd2eb97db438d3fdb0eb3a5e6a977b7c1badca76337e9ce`.
+
+## Low-resource behavior
+
+Linux/macOS worker loops default to15fps, Windows retains30fps. Real elapsed time
+drives the existing fixed-step animation: fewer drawn frames do not deliberately
+speed the dog up. There is at most one frame in flight. Only the cropped, nonblank
+Braille rectangle crosses the pipe and is painted. Hidden/inactive/minimized
+time is paused and never replayed on reveal. Native adapters should default to
+coarser cells/bounded grids on large displays instead of rendering a4K framebuffer.
+This is a design target, not a claim of zero CPU use or a measured memory minimum.
+
+In the owned1280×800 Alma8 test the Node engine RSS was about179MiB, plus the
+Python helper. This is not a minimum-memory requirement or proof of4K performance.
+
+All adapters reuse the same Q5 art and behavior engine. POSIX control sockets use
+short `/tmp/retrieviewer-overlay-<uid>-<uuid>.sock` addresses with0600 permissions,
+an independently random token in the0600 session record, and conservative cleanup.
+Windows named pipes remain compatible with the previous launcher. No token is
+printed in status or sent over a network. Same-user hostile software remains
+outside the security boundary. Stop/remove must not kill or modify the target app.
+
+## Evidence
+
+Keep actual checks, failures, skips and the tested OS separate. Static macOS source
+tests cannot establish AppKit/JXA behavior or privacy permissions. An Ubuntu test
+with a newer libc is not AlmaLinux8/GLIBC2.28 certification. A fake window manager
+is not proof of composited visual quality. Test containers may install their own
+QA tools, but product launch never installs OS packages or changes the user's OS.
+
+Recorded Linux checks: real ARGB painting, empty input shape, moved target geometry,
+stale-frame discard, hide on unmap, target disappearance, foreground retention,
+actual Node-to-Python worker painting, accepted ball interaction,0600 UNIX socket,
+rejected wrong token, clean worker/helper exit, and remove lifecycle. This covers
+an isolated desktop, not every GNOME/KDE theme, compositor or physical monitor.
+Evidence: `dist/alma8-qa/posix-worker.json` and source QA script output.
+
+- [Node build platform requirements](https://github.com/nodejs/node/blob/v22.23.4/BUILDING.md)
+- [X11 Shape protocol](https://xorg.freedesktop.org/archive/X11R7.7/doc/xextproto/shape.html)
+- [Wayland client surface isolation](https://wayland.pages.freedesktop.org/wayland.freedesktop.org/docs/book/Protocol.html)
+- [Apple NSWindow](https://developer.apple.com/documentation/appkit/nswindow)

package/INSTALLING.md

@@ -1,16 +1,19 @@
 # Install Retrieviewer
 
-Windows desktop setup (Node20+ and the Windows .NET Framework4 compiler required):
+Desktop setup (Node20+; [OS requirements and verification](DESKTOP-PLATFORMS.md)):
 
 1. `npm install -g @bitefoundry/retrieviewer`
 2. `retrieviewer desktop` — select the app window in the picker.
 
 No agent configuration is needed for this separate transparent companion.
-See [desktop controls, compatibility and removal](WINDOWS-COMPANION.md).
+Windows and AlmaLinux8/GLIBC2.28 X11 have live test evidence. macOS support is
+experimental and not runtime verified; native Wayland is unsupported. Linux needs
+system Python3.6+, X11/Xrender/Xext and a compositor; Windows needs the .NET
+Framework4 compiler. See [Windows controls and removal](WINDOWS-COMPANION.md).
 
 ## Optional native OpenCode integration
 
-0.0.2 also includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
+0.0.3 also includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
 that every MCP client can display animated UI. Native OpenCode rendering uses its
 official TUI plugin slot, not another terminal, a wrapper, or a modified binary.
 Other agent IDs are discoverable but refused until an adapter is implemented.
@@ -62,8 +65,8 @@ the new package. No automatic global install is done by the package itself.
 
 ## Commands
 
-For the separate Windows overlay (included since0.0.2),
-see [Windows companion](WINDOWS-COMPANION.md). It does not register a Codex plugin
+For the separate native overlay (Windows since0.0.2; Linux X11 and experimental macOS since0.0.3),
+see [desktop platforms](DESKTOP-PLATFORMS.md). It does not register a Codex plugin
 or change the way an agent is launched:
 
 ```powershell

package/PLUGIN.md

@@ -1,6 +1,6 @@
-# Retrieviewer plugin · 0.0.1
+# Retrieviewer plugin
 
-An autonomous Braille dog, embedded in **your pane**. Only ball and treat need user
+An autonomous Braille dog, embedded in **your pane**. Ball, treat and tug need user
 input. The rest is its own seeded behavior. No screen, stdin or layout takeover.
 No telemetry, keys, account signup or paid APIs in the runtime.
 
@@ -9,21 +9,22 @@ No telemetry, keys, account signup or paid APIs in the runtime.
 Install from npm:
 
 ```sh
-npm install @bitefoundry/retrieviewer@0.0.1
+npm install @bitefoundry/retrieviewer
 ```
 
 Portable distribution (independent of the source directory):
 
 ```sh
-npm install /path/to/bitefoundry-retrieviewer-0.0.1.tgz
+npm install /path/to/bitefoundry-retrieviewer-VERSION.tgz
 ```
 
 The generated tarball is in `dist/`. Node >=20, ESM and a monospaced Unicode
 Braille font are required. The npm package name is `@bitefoundry/retrieviewer`;
 imports from the old playground name must be updated.
 The tarball carries Q5 art, runtime code, types and examples. npm installs the pinned
-`three` dependency separately (network/cache or host provisioning required).
-No install/build scripts. Offline install requires that dependency already cached.
+`jsonc-parser` dependency for configuration editing separately. The current source
+runtime does not require Three.js; it remains a development-only comparison tool.
+No install/build scripts. Offline install requires the production dependency cached.
 
 For supported agent-native installation use `retrieviewer enable`; see
 [INSTALLING.md](./INSTALLING.md). The library contract below remains unchanged.
@@ -49,6 +50,7 @@ const puppy = await createPetPlugin({
 puppy.start();
 ballButton.on('click', () => puppy.interact('ball'));
 treatButton.on('click', () => puppy.interact('treat'));
+tugButton.on('click', () => puppy.interact('tug'));
 // pane unmount / host shutdown:
 puppy.dispose();
 ```
@@ -87,7 +89,7 @@ synchronous; avoid retaining borrowed frame pixels. See types for custom schedul
 | JS/TS terminal widget | `/plugin` host callbacks, or core `step/frame` | Generic contract + installed consumer tested |
 | Ink/React, Blessed | Lifecycle calls plugin, render text in widget | Contract fits; framework-specific mounts not tested |
 | Python/Rust/Go TUI | JSONL subprocess, one `tick` request per frame | Bridge + Python sample; Node required |
-| Browser | Core/plugin + deployed assets + `three` mapping | Existing browser core preview checked; arbitrary bundlers untested |
+| Browser | Core/plugin + deployed assets; no Three.js import map | Existing browser core preview checked; arbitrary bundlers untested |
 
 Not a native binary, editor extension, MCP plugin, or automatic injection into
 closed-source TUI apps. Such hosts need an extension hook to display a pane.
@@ -105,6 +107,7 @@ The package check creates a tarball, installs it into a fresh temp consumer offl
 with lifecycle scripts disabled, exercises exports, default art, interactions,
 start/pause/dispose, all JS examples and JSONL. Evidence is retained in
 `dist/package-check.json`. It does not publish. Art originals/references/workers
-are excluded. Source art is18.7 MB gzip; full tarball is approximately20.6 MB,
-excluding npm's separate Three dependency. This is still a substantial pet, not
-a kilobyte icon; see memory/startup tradeoffs in the comparison document.
+are excluded. Q5 art is about18.8 MB gzip; the0.0.4 tarball
+is about18.9 MB. Installed production files total about19.5 MB in the local consumer
+check, including dependencies. This is still a substantial pet, not a kilobyte icon;
+see measurements and release distinctions in [PUPPY-MEMORY.md](./PUPPY-MEMORY.md).

package/PREREQUISITES.md

@@ -0,0 +1,95 @@
+# Node, npm and your desktop
+
+[한국어 안내](README.ko.md#nodejs가-없다면) · [Install Retrieviewer](README.md#bring-one-home)
+
+## Choose the computer first
+
+Install where the app window is displayed. For Cursor/VS Code Remote SSH, this
+usually means your local Windows/macOS computer, not the remote Linux terminal.
+A Linux DISPLAY such as :1 may belong to a remote VNC desktop; it does not mean
+the local Cursor window lives there. Desktop Linux needs X11 plus a compositor.
+
+## Install Node/npm
+
+Check `node --version` and `npm --version`. The package needs Node>=20; prefer a
+maintained release. Node22.23.4 is our tested Alma8 baseline.
+
+- **Windows:** use the official [Node.js download page](https://nodejs.org/en/download)
+  and choose the Windows installer. Keep npm and Add to PATH enabled. Open a new
+  PowerShell afterwards; do not run inside your SSH terminal.
+- **macOS:** use the official macOS installer from the same page; reopen Terminal.
+  Node installation does not mean our experimental Mac overlay has been verified.
+- **AlmaLinux8:** an administrator can inspect `dnf module list nodejs`, then on
+  a system with no conflicting Node stream install `sudo dnf module install nodejs:22`.
+  See [RHEL8.10 stream instructions](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/8.10_release_notes/new-features)
+  and [Alma8's Node22 packages](https://errata.almalinux.org/8/ALSA-2026-54530.html).
+  Do not reset/switch a company-managed stream without your administrator.
+- **Other Linux:** use your distribution's maintained Node22+ package or the
+  official platform download; do not assume an old distribution's `nodejs` package
+  meets Node>=20. The official [Node22 release](https://nodejs.org/en/blog/release/v22.23.4/)
+  includes binaries and checksums. Avoid random install scripts and do not replace
+  system GLIBC to make a newer binary start.
+
+No administrator access? Use an approved per-user Node installation or ask the
+machine administrator. Node/npm and desktop libraries are prerequisites, not
+dependencies that Retrieviewer silently installs.
+
+## Linux native prerequisites
+
+System Python3.6+, libX11, libXrender and libXext, an ARGB32 visual, SHAPE input
+extension, EWMH window manager and a compositor are required. No pip, GTK, Qt,
+Electron, native npm build or C++ compiler is required by the Linux helper.
+On AlmaLinux8, Python can fall back to `/usr/libexec/platform-python`.
+
+On a managed machine, ask your administrator for missing desktop libraries;
+don't change the login session, compositor or display permissions blindly.
+Native Wayland is unsupported. Check session variables without shell-specific
+unset-variable errors:
+
+```sh
+printenv XDG_SESSION_TYPE DISPLAY WAYLAND_DISPLAY
+```
+
+## Command not found
+
+First check the install location:
+
+```sh
+npm ls -g @bitefoundry/retrieviewer --depth=0
+npm prefix -g
+```
+
+On Linux/macOS the executable is under `<printed-prefix>/bin`. On Windows it is
+directly under the printed prefix. Add the actual directory to your user's PATH.
+Retrieviewer never edits a shell profile automatically.
+
+For **bash/zsh**, this fixes the current shell:
+
+```sh
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+For **csh/tcsh**, if the printed prefix is `/home/you/.npm-global`, replace that
+example with your actual result:
+
+```csh
+set path = ( /home/you/.npm-global/bin $path )
+rehash
+```
+
+Persist the appropriate line manually in your shell's own startup file if needed.
+For Windows, reopen PowerShell first; if necessary add the printed npm prefix in
+Windows User Environment Variables → Path. Do not overwrite the entire PATH.
+If PowerShell policy blocks npm.ps1 or retrieviewer.ps1, use `npm.cmd` and
+`retrieviewer.cmd` instead. Do not weaken your execution policy just for this pet.
+
+If global npm install reports EACCES, use a properly configured per-user npm
+prefix/Node installation with your administrator's guidance—not blanket sudo npm.
+Meanwhile the one-off command does not require global PATH setup:
+
+```sh
+npx --yes --package @bitefoundry/retrieviewer@latest retrieviewer desktop
+```
+
+`npx` still needs Node/npm and a compatible GUI desktop, and may download the
+package into npm's cache. It does not create a permanent global command.

package/PUPPY-MEMORY.md

@@ -1,4 +1,105 @@
-# Lossless runtime cache reduction
+# Runtime weight and performance
+
+## Comfort behaviors (0.0.4)
+
+Belly-up flopping and eyes-closed sleeping reuse the existing action/rest art.
+Tug adds eight authored keys and the exact existing seat endpoint, not a dense
+tween film:103,549 compressed bytes and291,337 resident Q5 pixel bytes. The sampler
+allocates its single RGBA output only on first use; source reconstruction remains
+a two-frame LRU. No new runtime dependency, background process or timer is added.
+
+The legacy interaction sheet contains101 unique frames that no active clip can
+reach. The Q5 loader now retains only the23 unique frames used by treat/pickup/drop.
+All active samples compare byte-for-byte against the full store. Normal codec
+loading still retains every frame unless explicitly supplied a validated index
+list; requesting an excluded frame fails rather than displaying a substitute.
+
+| Resident cropped pixel payload | Bytes |
+| --- | ---: |
+| Before comfort extension | 66,515,834 |
+| Remove unreachable interaction pixels | −4,444,163 |
+| Add tug keys | +291,337 |
+| Current total | 62,363,008 |
+
+Thus new poses use about4.15 MB less resident art than the previous source version.
+This is an art-payload measurement, not a guarantee that OS-reported RSS falls by
+the same amount. In three fresh Windows benchmark samples, mean frame time median
+was3.22 ms versus3.29 ms previously; peak process RSS median was262.3 versus263.3
+MiB (small differences, not a meaningful promised performance improvement).
+The same450-frame ball hash still matches exactly. Source measurements live in
+`dist/performance/comfort-{1,2,3}.json` locally.
+
+`puppy-comfort-runtime.test.mjs` checks repeated load/render/tug/dispose, allowing
+native gzip callbacks and GC to finish before checking retained arrays. No pet
+buffers or timer handles remain after this bounded test. RSS reclamation remains
+allocator/GC-dependent; dispose is not advertised as an immediate RSS reduction.
+
+`node tools/check-comfort.mjs` produces deterministic off-screen dot snapshots
+for all three behaviors under `dist/comfort-qa/`. Snoring is a silent rising dot
+cue, not audio playback. Ball/treat/tug wake a sleeping pet through the existing
+recovery instead of waiting out the long sleep hold. Belly also shortens its hold
+on interaction and finishes the authored roll safely.
+
+## Earlier runtime optimization (also included in0.0.4)
+
+The dot-art actor already integrates its own travel, stride and perspective. Its
+former Three.js animal only supplied a position copied from that actor's target;
+mesh deformation and inverse kinematics were not used by the dot renderer. The
+runtime now uses a small position adapter instead. The original 3D implementation
+remains in the working tree for comparison, but is excluded from the npm package;
+Three.js is a development dependency only.
+
+Stable Braille conversion skips black/transparent background pixels and packs cell
+masks directly, preserving the original Float32 luminance rounding and thresholds.
+The native frame pump also skips identical output frames while continuing the
+simulation clock. Art, palette, camera and frame rate are unchanged.
+
+Median of three paired fresh-process measurements on Windows, Node24.19.0:
+
+| Metric | Before | After |
+| --- | ---: | ---: |
+| Asset load | 706.4 ms | 667.8 ms |
+| 1,800 simulation steps | 114.3 ms | 3.2 ms |
+| Mean render time per frame | 7.13 ms | 3.29 ms |
+| Render time p95 | 9.93 ms | 5.77 ms |
+| Peak benchmark-process RSS | 304.8 MiB | 263.3 MiB |
+
+The rendering workload is450 frames at480×135 Braille cells (native4K output
+with8px cells), seed731 and the same ball interaction. All six runs produced the
+same SHA-256 text-frame hash:
+`3a296d0a737eaa1d9a5923e3496e8c62b2d5e99fbe871806b907429515597a3d`.
+The independent original-3D/body comparison also matches4,000 actor steps exactly.
+Additional autonomous episodes reuse existing art: scanning, a same-depth patrol,
+rolling, returning to the viewer and occasional playful turning. They are not part
+of the fixed interactive benchmark trajectory.
+
+Installed production files, including dependencies, decreased from45,188,203 to
+19,423,382 bytes. Tarball size decreased from20,615,763 to18,788,415 bytes. These
+are different measures: installation shrank about57%, the tarball about9%.
+
+These are local test-process samples, not desktop memory budgets or guarantees.
+RSS includes loading transients, two sequential pet instances and allocator/GC
+behavior. Browser, macOS and Linux performance were not measured in this pass.
+The decoded Q5 art still occupies about66.5 MB; this change does not reduce that
+resident art in that earlier pass; the comfort pass above reduces it further.
+
+Reproduce from the development checkout:
+
+```sh
+node --expose-gc tools/benchmark-pet.mjs ./retrieviewer.mjs ./dist/performance/current.json
+npm test
+npm run test:package
+```
+
+The benchmark also accepts the absolute path to an installed older
+`retrieviewer.mjs` as its first argument. It renders off-screen without changing
+desktop settings. Paired results are retained under `dist/performance/` locally.
+
+## Earlier lossless runtime cache reduction
+
+The measurements below describe the earlier RVF1 lossless pass, before Q5 art
+and the current optimization. They are retained as historical comparisons, not
+current package or memory figures. See `PUPPY-Q5-COMPARISON.md` for the palette pass.
 
 The weight came from 2,341 full-size grayscale frames stored as concatenated
 320² or 480² rasters, including exact duplicates and black padding. These are

package/README.ko.md

@@ -0,0 +1,110 @@
+<p align="center"><a href="https://bitefoundry.github.io/retrieviewer/?lang=ko"><img src="https://raw.githubusercontent.com/BiteFoundry/retrieviewer/main/docs/assets/preview.png" alt="흑백 점자 도트로 그린 보송한 리트리버 Retrieviewer" width="960"></a></p>
+<h1 align="center">Retrieviewer</h1>
+<p align="center">일하는 화면에, 작은 친구 하나.</p>
+<p align="center"><a href="https://bitefoundry.github.io/retrieviewer/?lang=ko">직접 만나 보기</a> · <a href="README.md">English</a> · <a href="https://www.npmjs.com/package/@bitefoundry/retrieviewer">npm</a> · <a href="https://github.com/BiteFoundry/retrieviewer/issues">피드백</a></p>
+
+앱 창 위에서 혼자 걷고, 뛰고, 앉아서 쉬는 보송한 점자 도트 리트리버예요.
+발라당 누워 쉬거나 눈을 감고 잠들기도 해요. 가끔 공·간식·터그로 놀아주세요.
+나머지 시간에는 각자의 일을 하면 돼요.
+[BiteFoundry](https://github.com/BiteFoundry)가 만듭니다.
+런타임에는 계정, 모델 API, 텔레메트리가 필요하지 않아요.
+
+## 데려오기
+
+**앱 화면이 보이는 컴퓨터**의 터미널에서 실행하세요.
+Node.js/npm이 없다면 [먼저 설치](PREREQUISITES.md)해 주세요.
+
+1. 설치 또는 업데이트:
+
+   ```sh
+   npm install -g @bitefoundry/retrieviewer@latest
+   ```
+
+2. 실행한 뒤, 선택창에서 강아지를 붙일 앱 창을 고르세요.
+
+   ```sh
+   retrieviewer desktop
+   ```
+
+다음부터는 `retrieviewer desktop`만 실행하면 돼요. 앱을 개조하거나 MCP로
+그림을 주입하지 않아요. 별도의 투명 네이티브 창으로 따라다니며 일반 클릭은
+통과시킵니다. 앱 창 단위로 동작하고, 대상 창이 비활성화·최소화되면 숨습니다.
+자동 시작이나 셸 래퍼는 등록하지 않아요.
+
+> **Cursor / VS Code Remote SSH 사용자:** 원격 서버의 터미널이 아닌,
+> Cursor 화면이 떠 있는 **로컬 PC의 PowerShell/터미널**에 설치하세요.
+> 서버의 `DISPLAY=:1`은 서버 쪽 X11 화면을 뜻합니다. VNC로 그 화면을 보고
+> 있다면 그 안에서 쓸 수 있지만, 로컬 Cursor 창에 자동으로 붙는 것은 아니에요.
+
+<details>
+<summary>npx로 한 번 써보기 / 명령을 찾을 수 없을 때</summary>
+
+```sh
+npx --yes --package @bitefoundry/retrieviewer@latest retrieviewer desktop
+```
+
+`npx`는 영구 명령 등록이 아니에요. 이후 짧은 명령으로 실행하려면 위의 전역
+설치를 해주세요. 전역 설치 후에도 command not found라면 npm 실행 경로를
+PATH에 넣어야 해요. [bash·csh/tcsh·Windows별 안내](PREREQUISITES.md#command-not-found).
+무조건 sudo npm으로 해결하지 마세요.
+
+</details>
+
+## Node.js가 없다면
+
+- **Windows:** [공식 Node.js 설치 페이지](https://nodejs.org/en/download)의
+  Windows 설치 파일을 쓰세요. npm·PATH 추가 옵션을 유지하고 PowerShell을 새로 여세요.
+- **macOS:** 같은 공식 페이지의 macOS 설치 파일을 쓰세요. 다만 강아지의 macOS
+  오버레이는 아직 실기 검증 전인 실험적 지원이에요.
+- **AlmaLinux8:** 관리자와 Node22 모듈 사용을 확인하세요. 기존 Node 스트림이 없는
+  환경이라면 `sudo dnf module install nodejs:22`를 사용할 수 있어요.
+  회사 관리 환경의 모듈을 임의로 reset하거나 바꾸지 마세요.
+- `node --version`, `npm --version`으로 확인하세요. 패키지는 Node20+를 요구하고,
+  Alma8에서는 Node22.23.4를 검증했어요. [자세한 의존 도구·PATH 안내](PREREQUISITES.md).
+
+## 지원 환경
+
+| 환경 | 상태와 필요 조건 |
+| --- | --- |
+| Windows10/11 x64 | 실제 실행 검증. Node + .NET Framework4 컴파일러. 처음 실행 시 헬퍼 자동 빌드. |
+| Linux X11 | AlmaLinux8 / GLIBC2.28 / Python3.6.8 / Node22.23.4를 격리된 GUI에서 검증. Python3.6+, X11/Xrender/Xext, compositor 필요. |
+| macOS | **실험적 지원. 실제 Mac 실행 미검증.** 기본 osascript/AppKit 사용. |
+| 네이티브 Wayland·화면 없는 SSH | 데스크톱 오버레이 미지원. 세션·보안 설정을 자동 변경하지 않아요. |
+
+Linux는 저사양 기본값인 16px 셀·15fps, Windows는 8px 셀·30fps여서 Linux의
+점이 더 거칠게 보일 수 있어요. 그림 원본은 같은 Q5 자산입니다.
+무부하·초경량 도구는 아니에요. npm 압축본은 약19MB예요. 이전0.0.3의 작은
+Alma8 테스트에서는 Node RSS가 약180MiB였고 Python 헬퍼는 별도였어요.
+이 값은 메모리 상한이나0.0.4의 새 Linux GUI 검증 결과는 아니에요.
+[지원 범위와 검증 내용](DESKTOP-PLATFORMS.md).
+
+## 쉽게 종료하고 제거하기
+
+컨트롤에서 종료하거나 `retrieviewer desktop-stop`을 실행하세요.
+자체 캐시와 패키지를 제거하려면:
+
+```sh
+retrieviewer desktop-remove --yes
+npm uninstall -g @bitefoundry/retrieviewer
+```
+
+데스크톱 동반자는 에이전트 인증정보·실행 파일·셸 프로필을 수정하지 않아요.
+별도로 [OpenCode 네이티브 등록](INSTALLING.md)을 했다면 해당 등록을 disconnect한
+뒤 제거하세요. Codex/Claude/Cursor 등에 MCP만 연결해 내부 그림을 띄우는 기능은 없어요.
+
+## 직접 만든 TUI에 붙이기
+
+JS 플러그인과 JSONL 브리지를 제공해요. 화면·입력·시간 제어는 호스트가 소유합니다.
+[English 예제](README.md#put-it-inside-your-own-tui) · [플러그인 수명주기](PLUGIN.md) ·
+[코어와 브리지](EMBEDDING.md) · [기여하기](CONTRIBUTING.md).
+
+## 코드와 그림의 라이선스는 달라요
+
+**코드 MIT / 그림 CC BY-SA4.0.** 각 조건에 따른 상업적 재사용이 가능해요.
+그림은 출처 표시와 해당하는 동일조건변경허락 의무를 지켜주세요.
+패키지 전체가 MIT인 것은 아닙니다.
+[그림 조건](ASSETS-LICENSE.md) · [필수 크레딧](ATTRIBUTION.md) ·
+[서드파티 고지](THIRD-PARTY-NOTICES.md) · [브랜드 안내](TRADEMARKS.md).
+
+AI로 생성한 그림에 자세 정렬·접지·프레임 처리를 적용한 애니메이션입니다.
+실제 모션 캡처나 자의식이 있는 강아지라고 주장하지 않아요.