@howaboua/pi-pet 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @howaboua/pi-pet
+
+## 0.1.1
+
+### Changes
+
+- [#304](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/304) [`4b4e42f`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/4b4e42f7659e42854ec81cb502bf69a48422d9eb) Thanks [@IgorWarzocha](https://github.com/IgorWarzocha)! - Run Pi Pet as a first-class GipPity companion.
+
+  - Meet Clawa through the browser, voice, desktop dictation, a transparent desktop window, or the headless pet-state feed.
+  - Import compatible Codex and ChatGPT pets or author new pets through free-form `/pet` requests.
+  - Keep authored pets and generated displays in durable Pi agent storage, with optional per-repository pet selection.
+  - Attach the local device directly or remote devices through Pi-owned SSH sessions, with each folder remembering where its sessions appear.
+  - Get exact install and reload guidance when GipPity Control is missing or outdated.
+
+- Updated dependencies [[`4b4e42f`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/4b4e42f7659e42854ec81cb502bf69a48422d9eb)]:
+  - @howaboua/pi-gippity-control@0.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Warzocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Pi Pet
+
+Pi Pet turns [GipPity Control](../pi-gippity-control) into an animated companion. Its bundled Clawa miniapp receives Pi activity, prompts, final replies, and realtime voice through GipPity Remote's existing browser SDK; Pi Pet contributes only pet rendering, reactions, assets, and an optional transparent Electron shell.
+
+![Clawa running in a Pi Pet window.](docs/pi-pet.png)
+
+## Install
+
+```bash
+pi install npm:@howaboua/pi-gippity-control
+pi install npm:@howaboua/pi-pet
+```
+
+Run `/gippity server` or its configured shortcut. With Pi Pet loaded, GipPity serves Clawa at `/_gippity/apps/pi-pet/` on every announced server URL. GipPity's bundled or explicitly configured main remote UI remains at `/`.
+
+Open `<gippity-url>/_gippity/apps/pi-pet/` and accept GipPity's local certificate. The same Clawa app provides:
+
+- working, waiting, failure, and settled animation from Pi events;
+- synchronized text prompts through `GippityRemote.send()`;
+- realtime conversation through `GippityRemote.audio`;
+- bounded final-reply bubbles;
+- local action previews and sixteen pointer-look directions.
+
+`pet_show` is the only model tool. It triggers an intentional named reaction; routine activity animates automatically and GipPity already owns speech and final text.
+
+Electron is optional. With no attached device, Pi Pet still publishes its versioned `{ pet, revision, action, note? }` state through GipPity alongside the session activity and tool events used by any browser renderer.
+
+## Transparent desktop pet
+
+The Electron shell loads the same GipPity-hosted app in a transparent, frameless, always-on-top window. It adds local cursor tracking, size, quiet mode, and snooze without another agent runtime or remote protocol.
+
+Attach the device running Pi directly:
+
+```text
+/pet attach local
+```
+
+For another device, give it an SSH alias and confirm key-based access once outside Pi:
+
+```bash
+ssh desktop true
+```
+
+The remote device needs npm and Node 22 or newer; runtime extraction uses PowerShell on Windows and standard `unzip` on macOS/Linux. Attach it from Pi:
+
+```text
+/pet attach desktop
+```
+
+Pi Pet starts GipPity for the active Pi session and uses its saved LAN settings unless `/pet attach <device> <gippity-url>` supplies an override. Local attachment runs the Pi-owned bootstrap directly; remote attachment sends it through SSH. Both keep the desktop source and build at `~/.pi/agent/pi-pet` on that device. On connection Pi Pet compares the loaded package version and source digest with the recorded build, runs the copy, `npm install`, and `npm run build` steps only when they differ, then starts Electron. Pi or Clawa exiting stops Electron and GipPity but does not discard the build. It creates no application installation, login item, or background service.
+
+The global registry at `<pi-agent-directory>/pi-pet.json`, normally `~/.pi/agent/pi-pet.json`, retains reusable local and SSH device definitions. The current folder's `.pi/pi-pet.json` selects which devices receive that folder's Pi sessions. Later sessions opened in the same folder start only those devices automatically. Inspect them with `/pet status`, relaunch them with `/pet restart`, or remove one from the folder with `/pet detach desktop`. SSH options, keys, proxies, and host routing stay in `~/.ssh/config`.
+
+```json
+{
+  "schemaVersion": 1,
+  "devices": {
+    "local": { "kind": "local" },
+    "desktop": { "kind": "ssh", "target": "desktop" }
+  },
+  "defaultDevices": []
+}
+```
+
+If attachment or a build fails, Pi reports the failing phase and error. Ask Pi to diagnose and repair `~/.pi/agent/pi-pet` on that device; no application reinstall or directory reset is normally needed.
+
+Electron accepts GipPity's self-signed certificate only for the configured origin. The source-only `desktop/` package is also directly runnable with `npm install`, `npm run build`, and `npm start` from a source checkout.
+
+## Pet authoring
+
+Authoring guides are loaded only when requested rather than exposed as permanent skills. Pass a natural-language request to the same routed command:
+
+```text
+/pet add a catching-mouse animation
+/pet hatch a fluorescent office ferret
+```
+
+Pi Pet resolves `authoring/PET-GUIDE.md` from its own source or npm installation and asks Pi to follow it. That guide routes one-action work or full character hatching into the bundled references, deterministic atlas tooling, and visual review process.
+
+Pi resolves its installed package from the guide path and uses its npm/Node authoring commands without requiring Bun or a monorepo checkout. Bundled pets are templates: the first edit copies one to `~/.pi/agent/pi-pet/pets/`, authoring evidence stays under `~/.pi/agent/pi-pet/runs/`, and generated miniapp assets stay under `~/.pi/agent/pi-pet/web/`. Package updates therefore do not overwrite user pets.
+
+A repository can select any generated durable pet and its devices without duplicating assets in `.pi/pi-pet.json`:
+
+```json
+{ "schemaVersion": 1, "pet": "office-ferret", "devices": ["local", "desktop"] }
+```
+
+Repository pet selection overrides the global default; otherwise Pi Pet uses the global selection and then bundled Clawa. Repository devices override the registry's defaults. `/pet attach` and `/pet detach` maintain the current folder's device list without changing its pet selection.
+
+Run `/reload` after rebuilding to select the authored pet and refresh attached devices. Pet packages remain inert JSON and bounded PNG/WebP files; they cannot supply scripts, HTML, URLs, or commands.
+
+See [`docs/architecture.md`](docs/architecture.md), [`SECURITY.md`](SECURITY.md), and [`docs/research.md`](docs/research.md).

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security model
+
+Pi Pet adds no listener, credential store, prompt endpoint, or remote session ownership. GipPity Control owns those boundaries.
+
+## Miniapp
+
+- GipPity confines static files to Pi Pet's registered realpath and reserves its SDK/API routes.
+- Browser prompts and voice use the hosted `GippityRemote` client rather than a pet-specific transport.
+- Custom reaction state is normalized and bounded by GipPity before browser delivery.
+- Pet manifests are strict inert JSON. Assets are bounded regular PNG/WebP files; traversal, escaping symlinks, excessive decoded size, and out-of-frame geometry fail during builds.
+- Authored pets stay under the Pi agent directory and reach the generated web root only after validation. Package updates refresh executable web-shell files without overwriting user pet sources or run evidence. Invalid durable state reports a warning and falls back to bundled Clawa.
+
+## Electron
+
+- Remote devices are reached only through the user's existing SSH authentication and host configuration. Pi Pet passes a bounded Node bootstrap over SSH stdin; SSH targets cannot contain command options. The same bootstrap runs as a direct child on the device running Pi.
+- The extension copies a fixed, bounded set of desktop source files from its own installed package into `~/.pi/agent/pi-pet` on the device. It records the package version and source digest only after a successful npm build, reuses matching builds, and leaves the directory in place when Electron exits. An owner heartbeat closes Electron when its local or SSH channel ends. It creates no login item, service, or application installation.
+- Dependency lifecycle scripts stay disabled. The npm build downloads the pinned Electron package's official current-platform archive and verifies the checksum bundled with that exact package before extraction. npm and Electron download caches remain governed by those tools.
+- The configured GipPity URL must be a credential-free HTTPS origin.
+- GipPity's self-signed certificate is accepted only for that exact configured origin and only for an unknown-authority error.
+- Chromium sandboxing, context isolation, and web security remain enabled; Node integration is disabled.
+- Navigation stays within the configured origin. New windows and permission requests fail closed.
+- The preload bridge carries only validated cursor positions.
+
+GipPity's trusted-LAN policy remains authoritative. Do not expose its server to an untrusted network or public reverse proxy.

package/authoring/PET-GUIDE.md

@@ -0,0 +1,65 @@
+# Pi Pet guide
+
+This guide is the on-demand entry point for `/pet <request>`. Resolve every relative path from this file. Its installed package owns bundled templates and tools; durable user pets and authoring runs live under `<pi-agent-directory>/pi-pet/`, normally `~/.pi/agent/pi-pet/`.
+
+## Route the request
+
+- To import an existing Codex or ChatGPT pet package, read `references/import-existing-pet.md` and follow it instead.
+- For live reactions, action catalogs, one additional animation, or repair of one existing action, continue below.
+- For a complete new character, full atlas repair, nine standard animations, or sixteen look directions, read `hatch/HATCH-GUIDE.md` and follow it instead.
+- To select a pet for the current repository, ensure that durable pet has been rebuilt, write the repository config described below, then tell the user to run `/reload`.
+- Separate pet data from renderer behavior. An animation such as `catching-mouse` can be authored as inert data; automatically triggering it near a pointer requires a separate renderer change.
+
+## Repository selection
+
+The project Pi config directory is normally `.pi/`. Write or update `pi-pet.json` there:
+
+```json
+{ "schemaVersion": 1, "pet": "<pet-id>" }
+```
+
+This selects an existing durable pet without copying assets into the repository. Preserve an existing `devices` array exactly when changing only the pet; `/pet attach` and `/pet detach` own device selection. Repository selection overrides the global default; a missing repository selection uses the global default, then bundled Clawa. Do not claim success until `<pi-agent-directory>/pi-pet/web/<pet-id>/catalog.json` exists; if needed, rebuild that pet first.
+
+## Live control
+
+1. Use `pet_show` only when the reaction carries useful task state or personality; lifecycle states already update automatically.
+2. Read the active pet's `PET.md` and manifests before choosing an unfamiliar action.
+3. Unknown actions are a data-authoring task. Do not guess aliases repeatedly.
+
+The bundled actions are `idle`, `running-right`, `running-left`, `waving`, `jumping`, `failed`, `waiting`, `running`, and `review`. Semantic aliases include `active→running`, `working→running`, `thinking→running`, `settled→review`, `success→jumping`, `error→failed`, and `hello→waving`. Sixteen pointer-direction poses are renderer-owned and are not agent actions.
+
+## Extend a pet
+
+Read `references/pet-format.md`, then:
+
+1. Resolve the installed package from this guide's absolute path and use it as command working directory. If the repository config selects a pet, run `npm run pet:prepare -- <that-id>`; otherwise run `npm run pet:prepare` or pass an explicit ID. It copies a bundled template only when no durable user pet exists and prints the user pet and run paths. Read that pet's `PET.md`, `pet.json`, and optional `pet.pi.json`. For a complete new character, switch to `hatch/HATCH-GUIDE.md`.
+2. Preserve character identity and every passing action. Prefer a separate bounded PNG/WebP atlas plus a `pet.pi.json` entry for one new action.
+3. Define frame coordinates and durations explicitly. Names use lowercase letters, numbers, dots, underscores, or hyphens; `list` is reserved for action discovery.
+4. Follow **Rebuild and load** below. The build validates manifests, traversal, assets, decoded dimensions, and frame geometry before producing the GipPity miniapp.
+5. Inspect the animation at actual pet scale. Reject clipping, identity drift, static loops, frame popping, opaque backgrounds, and colored alpha fringe.
+6. Update `PET.md` with personality, action semantics, and provenance, then exercise the action with `pet_show` after the user reloads Pi.
+
+## Rebuild and load
+
+The `/pet` prompt gives this guide's absolute installed path. Resolve the package root exactly two directories up from that path (`<package>/authoring/PET-GUIDE.md` → `<package>`), use it as the command working directory, and do not assume the current directory is a checkout or monorepo. After changing the durable user pet printed by `pet:prepare`, run there:
+
+```bash
+npm run pet:validate -- <absolute-user-pet-directory>
+npm run pet:rebuild -- <pet-id>
+```
+
+The rebuild writes the generated miniapp under the durable Pi Pet directory and makes that pet the global default; it never modifies the npm package. A repository selection still takes precedence. The running extension keeps its catalog in memory, so after a successful rebuild tell the user to run `/reload`; slash commands are user actions. Reloading Pi resolves the repository, global, then bundled selection and restarts the folder's configured Electron devices. A separately opened browser window may also need a page refresh. Only then exercise new or repaired actions with `pet_show`.
+
+## Boundaries
+
+- Pet packages are inert data. Never add JavaScript, shell commands, remote URLs, HTML, or event handlers to a manifest.
+- Asset paths stay relative to the pet directory and cannot use `..`, absolute paths, backslashes, or escaping symlinks.
+- Do not mutate the original Codex rows merely to add a Pi-only action; use `pet.pi.json` and a separate asset unless a full repair is intended.
+- Do not package a failing or visually unreviewed pet. Preserve source and licensing uncertainty explicitly.
+
+## Recovery
+
+- **GipPity unavailable:** report the concrete error; do not start another server or transport as fallback.
+- **Unknown action:** inspect the active pet manifests and use or add valid data.
+- **Build fails:** fix the reported package error and rerun the build once; do not bypass validation or ask the user to reload a failed build.
+- **Image capability unavailable:** accept supplied artwork or stop at a validated plan; do not claim visual completion.

package/authoring/hatch/HATCH-GUIDE.md

@@ -0,0 +1,136 @@
+# Hatch a Pi Pet
+
+Use this guide for a complete character, full Codex-v2 atlas repair, nine standard animations, or sixteen look directions. Deterministic tooling requires uv and Python 3.11+. Visual work requires an image-generation capability, supplied images, or an explicit external handoff. See `LICENSE.txt` for the authoring-tool license.
+
+## Run boundary
+
+1. The `/pet` prompt gives `PET-GUIDE.md`'s absolute installed path. Resolve `PI_PET_PACKAGE` to its package directory, `HATCH_DIR` to this guide's directory, `PET_DATA` to `<pi-agent-directory>/pi-pet`, and `RUN_DIR` to `$PET_DATA/runs/<pet-id>`. The Pi agent directory is `PI_CODING_AGENT_DIR` when set, otherwise `~/.pi/agent`.
+2. Collect a concept, optional name/description, style, brand cues, and reference images. Infer omitted creative details; ask only when identity direction is genuinely ambiguous.
+3. Keep generated work in `RUN_DIR`, outside `$PET_DATA/pets/`; reuse an existing run only when deliberately resuming it.
+4. For an existing pet, preserve every passing row. Never overwrite its package until the replacement passes and the user requested replacement.
+5. Keep this visible progression: **prepare → establish identity → generate poses → review and hatch**.
+
+Variable names in command blocks are path placeholders, not required environment variables. Substitute their resolved absolute paths using the host's command/workdir syntax. Use available file and JSON operations; when none fit, use Python through the locked uv environment. Do not require a POSIX shell or utilities such as `jq` and `cp`.
+
+Read `references/pet-contract.md` and `references/animation-rows.md` before preparing a run.
+
+## Visual capability
+
+Choose by capability, not vendor or tool name:
+
+1. Prefer an available image-generation capability that can accept prompts, reference images, and produce downloadable PNG/WebP files.
+2. Use one isolated generation worker per visual job when workers are available. Up to three independent standard-row jobs may run concurrently after the canonical base exists.
+3. Every row job must receive every `input_images` entry from `visual-jobs.json`. Only the base may be prompt-only.
+4. Never ask a generator for the complete atlas. Generate the base, standard strips, cardinal strip, and two coherent look strips as separate jobs; deterministic scripts own extraction and assembly.
+5. If no native image generation exists, follow `references/visual-generation.md`. Offer a prompt-and-upload handoff for ChatGPT, Gemini, Grok Imagine, or another service. If authorized browser control is available, offer to operate the user's logged-in service without requesting credentials or purchasing anything.
+6. A missing generator is not permission to draw, tile, rotate, or procedurally synthesize the missing art. Prepare the run and exact handoff, then resume when images exist.
+
+## Prepare
+
+Use the locked authoring environment:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/prepare_pet_run.py" \
+  --pet-name "<Name>" \
+  --description "<one sentence>" \
+  --reference /absolute/reference.png \
+  --pet-notes "<stable identity description>" \
+  --style-preset auto \
+  --style-notes "<optional constraints>" \
+  --output-dir "$RUN_DIR"
+```
+
+Omit flags that have no input. For a bare brand/product request, first research 2–4 preferably official sources and save a compact brief; do not copy logos, slogans, UI, or readable marks. Pass the brief and source URLs to `prepare_pet_run.py`.
+
+The command creates:
+
+- `pet_request.json`: identity, style, chroma key, geometry, and provenance inputs.
+- `visual-jobs.json`: dependency graph, prompts, references, output paths, and job status.
+- `prompts/`: service-neutral prompts.
+- `references/layout-guides/`: slot-count and safe-area guides; generated art must not reproduce guide marks.
+
+Inspect `visual-jobs.json`. A pending job is ready only when every `depends_on` job is complete. Send only jobs with a non-null `generation_capability` to an image generator; `visual-approval-gate` jobs are evidence-backed parent transitions.
+
+## Establish identity and standard rows
+
+1. Generate `base`; inspect one centered, full-body pet on its flat chroma background. Copy the selected file to `decoded/base.png` and `references/canonical-base.png`; record its path and completion in `visual-jobs.json` atomically.
+2. Generate `idle` and `running-right` first. Confirm identity, calm idle motion, and readable gait before spending the remaining jobs.
+3. Mirror `running-left` only when markings, lighting, props, and handedness remain correct:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/derive_running_left_from_running_right.py" \
+  --run-dir "$RUN_DIR" --confirm-appropriate-mirror \
+  --decision-note "<why identity and meaning survive mirroring>"
+```
+
+The derivation leaves `running-left` staged, not complete. Run the same extraction and visual QA as any generated row, then mark it complete. Otherwise generate it independently. Generate all other standard rows independently from the canonical base.
+
+4. After copying each selected strip to its declared `decoded/` path, immediately run:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/extract_strip_frames.py" \
+  --decoded-dir "$RUN_DIR/decoded" --output-dir "$RUN_DIR/qa/rows/<job-id>/frames" \
+  --states "<job-id>" --method auto
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/inspect_frames.py" \
+  --frames-root "$RUN_DIR/qa/rows/<job-id>/frames" \
+  --json-out "$RUN_DIR/qa/rows/<job-id>/review.json" --states "<job-id>" --require-components
+```
+
+Do not mark the job complete until deterministic inspection and a quick visual check pass. Repair known clipping, extraction, identity, or semantics immediately. `stable-slots` is allowed only when the generated strip itself has stable scale and placement but component extraction introduces popping.
+
+5. When all nine rows pass, extract all frames, inspect them, compose the intermediate 8×9 atlas, and create the contact sheet and previews using the commands in `references/standard-assembly.md`. Inspect every preview before look generation. The 8×9 atlas is never packageable.
+
+## Look directions
+
+Read `references/look-directions.md` before this stage.
+
+1. Write `qa/look-mechanics.md`: what anchors, what leads the gaze, what follows, eye construction, body deformation, and prop constraints.
+2. Generate one four-pose strip: `000 up`, `090 screen-right`, `180 down`, `270 screen-left`. Extract it with `extract_cardinal_anchors.py`, inspect at pet size, and compose `decoded/look-anchors-approved.png`. Regenerate an ambiguous cardinal before continuing. Complete the evidence gate only after those artifacts pass:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/approve_cardinals.py" \
+  --run-dir "$RUN_DIR" --reviewed-by "<agent or user identity>" \
+  --qa-note "<visible evidence that all four cardinals are correct>"
+```
+3. Generate row 9 as one coherent eight-pose family from approved cardinals. Register it immediately with `assemble_extended_atlas.py --look-row-9`; inspect its registered cells and edge report.
+4. Generate row 10 only after row 9 passes. Attach the approved cardinals and completed row 9 so scale, registration, and the `157.5→180` / `337.5→000` boundaries remain coherent.
+5. A failed direction regenerates its complete eight-pose row. Never patch one normalized final cell into a new pet.
+
+## Assemble and review
+
+Run the final commands in `references/final-assembly.md` in order:
+
+1. Assemble both look rows into the 8×11 atlas.
+2. Apply exactly one edge-local chroma despill pass.
+3. Validate geometry, alpha, used cells, transparent unused cells, and chroma contamination.
+4. Produce the extended contact sheet, focused direction sheet, blind A/B sheet, and continuity report.
+5. Use three isolated vision-capable reviewers for the blind sheet, combine strict-majority verdicts, then run one independent final visual reviewer. Follow `references/reviewer-protocol.md`.
+6. If isolated reviewers are unavailable, ask the user to inspect the blind and labeled sheets. Record reduced assurance and `reviewed_by: "user"`; never claim multi-agent consensus.
+
+Deterministic success does not replace visual QA. Visual confidence does not waive deterministic failure.
+
+## Package
+
+Package only after `references/qa-rubric.md` passes:
+
+```text
+pets/<pet-id>/
+├── PET.md
+├── pet.json
+├── spritesheet.webp
+└── validation.json
+```
+
+- Copy only the final despilled `spritesheet-extended.webp` as `spritesheet.webp`.
+- Write `pet.json` with `spriteVersionNumber: 2` and `spritesheetPath: "spritesheet.webp"`.
+- Write `PET.md` with identity, personality, included actions, generation inputs, tool/service provenance, review method, and licensing uncertainty.
+- Copy final deterministic validation as `validation.json`; retain full QA evidence in the run directory.
+- Write the accepted package to `$PET_DATA/pets/<pet-id>`. From `PI_PET_PACKAGE`, run `npm run pet:validate -- $PET_DATA/pets/<pet-id>` and `npm run pet:rebuild -- <pet-id>`. Tell the user to run `/reload`, then inspect at display scale and exercise every standard action.
+
+## Repair and stop conditions
+
+- Classify failures as semantics, identity, source geometry, connectivity, extraction, chroma, continuity, or final visual QA.
+- Prefer deterministic correction for deterministic failure. Regenerate only when source art is wrong.
+- Preserve passing properties and regenerate the smallest package-eligible unit: one standard row or one complete coherent look row.
+- If the same root failure recurs twice, change strategy rather than paraphrasing the same prompt.
+- Stop when all acceptance gates pass, the user cancels, or an external capability is unavailable after producing a resumable handoff. Never package a partial pet as complete.

package/authoring/hatch/LICENSE.txt

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/authoring/hatch/NOTICE.md

@@ -0,0 +1,5 @@
+# Source notice
+
+The deterministic Python workflow in this directory derives from an Apache-2.0 Codex Hatch Pet skill snapshot inspected on 2026-07-21.
+
+Pi Pet modifications replace Codex-specific generation, runtime, manifest, and packaging assumptions with capability-neutral visual jobs, an isolated uv runtime, Pi Pet packages, and external/browser-assisted generation handoffs. See `LICENSE.txt`.

package/authoring/hatch/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "hatch-pi-pet-tools"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["Pillow>=12,<14"]
+
+[tool.uv]
+package = false

package/authoring/hatch/references/animation-rows.md

@@ -0,0 +1,29 @@
+# Animation rows
+
+| Row | Action | Used columns | Durations (ms) |
+|---:|---|---:|---|
+| 0 | idle | 0–5 | 280, 110, 110, 140, 140, 320 |
+| 1 | running-right | 0–7 | 120 × 7, 220 |
+| 2 | running-left | 0–7 | 120 × 7, 220 |
+| 3 | waving | 0–3 | 140 × 3, 280 |
+| 4 | jumping | 0–4 | 140 × 4, 280 |
+| 5 | failed | 0–7 | 140 × 7, 240 |
+| 6 | waiting | 0–5 | 150 × 5, 260 |
+| 7 | running | 0–5 | 120 × 5, 220 |
+| 8 | review | 0–5 | 150 × 5, 280 |
+| 9 | look A | 0–7 | 000, 022.5, 045, 067.5, 090, 112.5, 135, 157.5° |
+| 10 | look B | 0–7 | 180, 202.5, 225, 247.5, 270, 292.5, 315, 337.5° |
+
+`000°` means up. Neutral/front is the pointer deadzone and falls back to idle.
+
+## Semantics
+
+- `idle`: calm breathing/blinking; first frame also works as reduced-motion still.
+- `running-right` / `running-left`: lateral locomotion with alternating cadence and correct facing.
+- `waving`: greeting with clear gesture and return.
+- `jumping`: anticipation, lift, peak, descent, settle.
+- `failed`: readable blocked/deflated response without detached decoration.
+- `waiting`: expectant request for user input, distinct from idle and review.
+- `running`: active task work or processing, not literal locomotion.
+- `review`: focused inspection of ready output.
+- look rows: one continuous clockwise family using pet-specific eyes, head, body, appendages, and props.