pi-jar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunaz
+
+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,288 @@
+# pi-jar
+
+A warm, role-aware TUI and workflow extension for [Pi](https://github.com/earendil-works/pi). pi-jar turns the terminal into a more expressive agent workspace with a living pixel-fire welcome, an adaptive composer, first-class **plan**, **goal** and **role** workflows, tracked tasks, reviewable changes, background shells and parallel subagents.
+
+> Works with the current `@earendil-works/*` Pi API. Pi's core packages are peer dependencies (`"*"`), so pi-jar always runs against the Pi you have installed; it is tested against the latest release (0.87.x).
+
+## See it in action
+
+![pi-jar welcome: pixel flame over the π, the hero message and workspace card, and the composer with Ember](https://raw.githubusercontent.com/ygrip/pi-jar/main/docs/assets/pi-jar-demo.gif)
+
+The showcase is captured from a real pi-jar terminal session: the torch-style `π`, animated flame and embers, live workspace state, tasks, roles and composer are the actual TUI rather than a mockup. Capture and media guidelines live in [docs/SHOWCASE.md](docs/SHOWCASE.md).
+
+## Highlights
+
+| Area | What you get |
+| --- | --- |
+| **Welcome** | A natural pixel flame (rounded base, swaying tip, wisps, embers and sparks) over a large `π`; a large, flame-colored welcome message up top; a live card with project, git, session, plan, goal, tasks and roles; clickable actions (fullscreen) or keyboard hints (regular mode). |
+| **Composer** | Rounded input that grows with your draft (up to ~60% of the terminal), click-to-place cursor in fullscreen, dim **next-prompt suggestions** you accept with <kbd>Tab</kbd>, and **Ember** — a tiny flame mascot that blinks, cheers, focuses, dozes and reacts. |
+| **Plan mode** | Read-only exploration; the agent must write a structured plan file and submit it. You review it in a split view (headings on the left, section on the right) and approve, compact-and-approve, refine or stop. |
+| **Goal mode** | Set an outcome; the agent must break it into tracked tasks and keeps working until they are done, then an **auditor** pass verifies the goal before it can be marked complete. |
+| **Roles** | Named model roles (`default`, `smol`, `slow`, `plan`, `implement`, `advisor`, `task`, `commit`, plus your own) with `@alias` chains, `:effort` suffixes and project overrides; switched automatically as you move between plan, execution, goal rounds and audits, and never over a model you picked yourself. |
+| **Advisor** | A second-opinion model: the agent calls `jar_advisor` for risky decisions or when stuck, `/advisor [focus]` asks on demand, and automatic gates consult it when the agent repeats the same tool call or keeps failing. |
+| **Usage & context** | `/usage` shows session cost and tokens per model (advisor and commit calls included) and plan-limit bars with reset times; `/context` draws a grid of what fills the context window, with a per-file, per-skill and per-tool breakdown. |
+| **Commit** | `/jar commit [note]` drafts a message for the staged changes with the `commit` role, lets you edit it, then commits (never pushes). |
+| **Tasks & questions** | A Claude-style `jar_todo` checklist the agent maintains itself, and `jar_ask` structured questions with options, multi-select and free-form answers. |
+| **Change review** | Every file the agent edits is remembered as it was; `/diff` (<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd>) shows changed files next to a colored diff, with accept or revert per file or all at once. |
+| **Background shells** | `jar_shell` runs dev servers, watchers and long tests in the background; the agent is woken when a watch pattern matches or the process exits, so it never polls. `/jar shells` tails or kills them. |
+| **Subagents** | `jar_delegate` fans out up to four read-only (or opt-in editing) subagents in parallel on your model roles; they show up live as teammates on the welcome card and footer. |
+| **Sessions & history** | Recent sessions (with their goal and plan) on the welcome card, one click from resuming; <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> searches earlier prompts; pasted images show as chips under the composer. |
+| **Footer & themes** | Responsive footer (model, effort, session, cwd, context, RAM, cost, quota, goal, roles, branch) and seven dark themes. |
+
+## Install
+
+```bash
+pi install npm:pi-jar
+```
+
+Or track the repository directly with `pi install git:github.com/ygrip/pi-jar`.
+
+Restart Pi, then pick a theme with `/settings`: `pi-jar-dark`, or `pi-jar-dark-<accent>` (`gray`, `pink`, `teal`, `azure`, `violet`, `amber`). For the closest match set your terminal background to `#0B1018` (Pi themes cannot change the terminal's own background).
+
+Loading only `--extension ./extensions/index.ts` does not register the bundled themes; install the package or also pass `--theme ./themes`. Do not load pi-jar twice.
+
+### Mouse, clicks and copy-on-select
+
+Pi only delivers mouse events in its **fullscreen** TUI mode. In regular mode the terminal owns scrollback and selection, so pi-jar shows keyboard shortcuts instead of buttons.
+
+- Turn it on in **`/jar settings` → Pi → Mouse clicks** (writes Pi's `tuiMode`; restart Pi), or start with `pi --tui-mode fullscreen`.
+- In fullscreen, selecting text copies it automatically (**Pi → Copy on select**, on by default). pi-jar's own views never capture drags, so selection works over the welcome, composer, plan view and dialogs.
+- In regular mode, use your terminal's own copy-on-select option if it has one.
+
+## Commands and shortcuts
+
+| Command | Purpose |
+| --- | --- |
+| `/plan [request]` | Enter plan mode (optionally sending the request). `/plan review` reopens the plan view; `/plan off` exits. |
+| `/goal <outcome>` | Start goal mode. `/goal` edits, `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. |
+| `/roles` | Role manager. `/roles set ROLE provider/model[:effort]\|@role [--project]`, `/roles clear ROLE`, `/roles <role>` activates, `/roles cycle`, `/roles list`. |
+| `/advisor [focus]` | Ask the advisor for a second opinion on the current work; the answer joins the conversation. |
+| `/usage` · `/context` | Usage (cost, tokens per model, plan limits) and context-window breakdown in one tabbed panel. |
+| `/jar commit [note]` | Draft a commit message for the staged changes with the `commit` role, edit it, and commit. Offers `git add -A` when nothing is staged. |
+| `/jar` · `/jar settings` | Visual and workflow preferences. |
+| `/jar status` | One-line status summary. |
+| `/jar tasks [list\|add\|done\|open\|edit\|delete]` | Human view/editor for the agent's checklist. |
+| `/jar history` | Read-only conversation timeline for the active branch. |
+| `/diff` | Review, accept or revert the files the agent changed. |
+| `/jar shells` | Background shells: live output, kill. |
+| `/jar resume [N]` | Resume recent session `N` from the welcome list, or pick one. |
+| `/jar sessions [query]` · `/jar name <title>` | Search/switch sessions; name the current one. |
+| `/jar welcome` | Replay the welcome screen. |
+| `/jar ask [question]` | Answer a question in a dialog and insert the answer into the editor. |
+| `/jar accent [preset]` · `/jar footer` | Switch a loaded accent theme; toggle footer fields. |
+| `/jar composer on\|off` · `/jar animations on\|off` · `/jar ui on\|off` | Toggle the composer, motion, or all pi-jar UI. |
+| `/jar quota on\|off` | Session-only, read-only quota lookups for supported OAuth providers. |
+| `/jar hub` | Open an installed task or subagent manager command. |
+| `/jar demo` · `/jar reset` | Labeled sample roles in the footer / back to live data. |
+
+| Shortcut | Action |
+| --- | --- |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> | Open pi-jar settings |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>R</kbd> | Refresh the welcome (new message and flame), or show it again |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>P</kbd> | Toggle plan mode |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>M</kbd> | Cycle model roles (`cycleOrder`) |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd> | Review agent changes (`/diff`) |
+| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> | Search earlier prompts into the composer |
+| <kbd>Tab</kbd> / <kbd>→</kbd> in an empty composer | Accept the dim suggestion into the input (it is not sent) |
+
+## Welcome screen
+
+The welcome stays until your first prompt, then dissolves (or hides immediately with motion off).
+
+- **Flame** — one continuous flame with a rounded base and a tip that sways and licks, animated with smooth noise and drawn with half-block "pixels" in a ten-step ember→gold palette. Wisps break off the tip; embers and sparks rise from it. Every frame is deterministic per seed, so motion-off shows a frozen, still-lit flame. Terminals without 24-bit color get shaded blocks in theme colors. See [docs/FLAME.md](docs/FLAME.md).
+- **Card** — `pi-jar` version, model, effort and active role; a large hopeful message; project + git branch/dirty; context, quota and cost; plan state; goal progress; open tasks with the next one; configured roles; live teammates (other extensions and `jar_delegate` subagents); and **RECENT** — the last three sessions with their goal and plan. Click a recent row (or run `/jar resume N`) to continue it.
+- **Actions** — `[ ⚙ Settings ]  [ ↻ Refresh ]  [ ◆ Roles ]  [ ▤ Plan ]  [ ◎ Goal ]` in fullscreen (act on press). In regular mode the same row shows `ctrl+alt+s settings · ctrl+alt+r refresh · /roles · /plan · /goal`.
+
+## Composer
+
+- **Grows with your draft**: the input expands to about 60% of the terminal before it scrolls (overflow shows `↑/↓ N more` in the border).
+- **Click to place the cursor** (fullscreen), including multi-line drafts. Autocomplete menus (including Pi's `@file` fuzzy search) render below the frame.
+- **Image chips**: images you paste (<kbd>Ctrl</kbd>+<kbd>V</kbd>) or reference by path appear under the frame as `▣ pasted png · 1280×720 · 240 KB`.
+- **Prompt history search**: <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd> fuzzy-searches every prompt in this session and the opening prompts of recent ones; <kbd>Enter</kbd> puts the pick in the composer to edit. <kbd>↑</kbd>/<kbd>↓</kbd> still walks Pi's history.
+- **Next-prompt suggestions**: when the agent finishes a request it proposes one likely next prompt (`jar_suggest`). It appears as dim ghost text in the empty input; <kbd>Tab</kbd> (or <kbd>→</kbd>, or a click on it) fills it in so you can edit and press <kbd>Enter</kbd>. Typing, sending, or a new run clears it. Toggle in settings.
+- **Ember the mascot** perches on the top-left of the input — the face sits in the border, the flickering tips just above:
+
+  | Mood | Face | When |
+  | --- | --- | --- |
+  | idle / blink | `(•ᴗ•)` `(-ᴗ-)` | waiting for you; blinks every few seconds |
+  | happy / thinking | `(^ᴗ^)` `(°ᴗ°)` | the agent is generating |
+  | focused | `(>ᴗ<)` | a tool is running (sparks fly) |
+  | curious | `(•o•)` | a question or dialog is open |
+  | sleepy | `(-ω-)` | idle for two minutes (`z` rises) |
+  | oops | `(×_×)` | a run failed |
+  | proud | `(★ᴗ★)` | a goal was completed |
+  | poked | `(^o^)` | you clicked it |
+
+  The title also shows Pi's session name (or a stable readable alias like `silver-lantern`). Toggle the mascot in settings; `/jar composer off` restores Pi's editor with your draft intact.
+
+## Plan mode
+
+`/plan` switches Pi into read-only planning:
+
+1. **Tools are gated.** Only known read-only tools stay active; `bash` is limited to an inspection allowlist; a second guard blocks unsafe calls even if another extension exposes them. `write`/`edit` are allowed **only** for markdown files in the plan directory (`$TMPDIR/pi-jar/plans/<session>/`, resolved through symlinks).
+2. **The `plan` role is applied** if assigned, and restored afterwards. An active goal loop pauses.
+3. **The agent writes a plan file** such as `<slug>-plan.md` and must end its turn with `jar_plan_submit`. The file is validated; an incomplete plan is sent back with the missing parts. If the agent ends a turn without submitting, pi-jar reminds it (at most twice per prompt) instead of accepting a chat-only plan.
+
+Required structure:
+
+```markdown
+# <Plan title>
+
+## Context
+Why, the literal request, and the intended end state.
+
+## Approach
+1. Ordered steps grouped by behavior, naming exact files, symbols, reused helpers and error handling.
+
+## Critical files
+- `path/to/file.ts` — symbol — why it changes
+
+## Verification
+- Exact commands and at least one concrete check of new behavior.
+
+## Assumptions
+- Decisions the user could override, each with a fallback.
+```
+
+4. **Plan view** — a full-screen split view: headings on the left (the lone `#` title becomes the header, `###` steps are indented), the selected section rendered as markdown on the right, actions below.
+   - Keys: <kbd>Tab</kbd> cycles focus (headings → body → actions), <kbd>↑↓</kbd>/<kbd>j k</kbd> move or scroll, <kbd>g</kbd>/<kbd>G</kbd>, <kbd>PgUp</kbd>/<kbd>PgDn</kbd>, <kbd>1–4</kbd> pick an action, <kbd>e</kbd> edits the plan (saved back to the file), <kbd>r</kbd> cycles the **continue with** role, <kbd>Esc</kbd> stops. Fullscreen: click headings and actions, wheel scrolls the pane under the pointer.
+   - Actions: **Approve & execute**, **Approve, compact & execute** (compaction keeps the plan), **Refine** (send feedback, stay in plan mode), **Stop**.
+5. **Execution** seeds `jar_todo` from the Approach steps, restores tools and model, optionally switches to the chosen role, and sends the full plan inline (`<plan path="…">…</plan>`) with instructions to work step by step and verify each step.
+
+Plan state is stored in the session branch, so reloading or navigating the tree restores it. Narrow terminals collapse the headings into a `‹ n/m heading ›` pager.
+
+## Goal mode
+
+`/goal Ship the export command` starts an implement → audit loop:
+
+- **Tasks first.** While a goal is active and no task is open, `write`/`edit` and non-read-only shell commands are blocked with "create jar_todo tasks for the goal first". The agent sees the goal and its current checklist at the start of every run.
+- **Implementor.** When a turn ends normally with open tasks (or none yet), pi-jar continues automatically with a hidden continuation listing the goal and open tasks.
+- **Auditor.** When every task is done, the next round switches to the `advisor` role (if assigned) and asks for an independent audit against the repository: run the checks, look for missed requirements. The auditor either adds tasks for gaps (edits stay blocked during the audit), which sends work back to the implementor, or calls `jar_goal complete` with concrete evidence. Completion is refused outside the audit, while tasks are open, or without evidence.
+- **Guard rails.** The loop pauses when you interrupt (<kbd>Esc</kbd>), a run fails, plan mode starts, the agent calls `jar_goal block` (it needs you), or the round budget runs out (default 8 automatic rounds per user message; settings → Pi → Goal auto rounds). A new message from you resets the budget. `/goal resume` continues.
+- The footer and welcome show progress: `◎ goal · Ship · 3/5 tasks · round 2/8 · auditing`.
+
+## Model roles
+
+Roles map a purpose to a model. They live in `~/.pi/agent/pi-jar-roles.json` (Pi's agent directory), with optional per-project overrides in `<project>/.pi/pi-jar-roles.json`:
+
+```json
+{
+  "version": 2,
+  "roles": {
+    "default": "anthropic/claude-sonnet-5",
+    "slow": "anthropic/claude-opus-5-5:high",
+    "plan": "@slow",
+    "advisor": "@slow:xhigh",
+    "smol": "anthropic/claude-haiku-4-5-20251001",
+    "review": "openai/gpt-5:medium"
+  },
+  "cycleOrder": ["smol", "default", "slow"],
+  "tags": { "review": { "name": "Reviewer" } }
+}
+```
+
+- Specs are `provider/model[:effort]`, `@role[:effort]` (alias) or `*` (= `@default`). An effort on the referring role wins over the target's. Alias chains are followed up to five levels; cycles are reported.
+- **Built-in roles and where pi-jar uses them:**
+  | Role | Used for |
+  | --- | --- |
+  | `default` | applied at session start |
+  | `plan` | plan mode (restored when you leave it) |
+  | `implement` | executing an approved plan and goal implement rounds (falls back to the current model) |
+  | `advisor` | `jar_advisor`, `/advisor`, stuck-work gates and the goal audit |
+  | `task` | `jar_delegate` subagents |
+  | `commit` | `/jar commit` messages |
+  | `smol` / `slow` | cycling with <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>M</kbd> |
+
+  Any other valid name (`a-z`, `0-9`, `-`) is a custom role.
+- **Switching is automatic and scoped.** Entering plan mode applies `plan`; approving applies your chosen role or `implement` for the run; goal rounds alternate `implement` and `advisor`. Each temporary switch restores the previous model afterwards — unless you picked a model or effort yourself in the meantime, which always wins.
+- `/roles` opens a split manager: role list on the left; resolved model, alias chain, effort, scope and usage on the right. Keys: `m` model, `a` alias, `t` effort, `s` move between global/project scope, <kbd>Enter</kbd> activate, `c` clear, `n` new role, `d` delete custom role.
+- Older v1 files are read and upgraded in memory; they are rewritten as v2 only when you change a role.
+
+## Advisor
+
+The advisor is a second model (the `advisor` role; the current model if unassigned) that sees a fresh view of the recent conversation plus `git status` and a diff stat, but cannot run tools.
+
+- **`jar_advisor({ question?, draft? })`** — the agent is told to use it before risky or hard-to-reverse choices, after two failed attempts, and before declaring complex work done; it passes its own candidate as `draft`. Available in plan mode too.
+- **`/advisor [focus]`** — ask on demand; the answer is added to the conversation (visible) for the agent's next turn.
+- **Gates** — when the agent makes the same tool call three times within its last eight calls, the call is blocked and the advisor's review is returned instead; after three failing tool results in a row, the advice is steered into the running turn. At most two automatic consultations per prompt.
+- Settings → Pi toggles the advisor and the gates. Advisor calls are counted in `/usage`. The footer and welcome show it as a working teammate while it thinks.
+
+## Usage and context
+
+`/usage` and `/context` open one tabbed panel (<kbd>Tab</kbd> switches, <kbd>Esc</kbd> closes):
+
+- **Usage** — total cost, duration, prompts and responses, tokens (input, output, cache read/write); a per-model breakdown including advisor and commit calls; and, for Anthropic and OpenAI Codex subscriptions, 5-hour and weekly limit bars with reset times (lookups follow `/jar quota on|off`).
+- **Context** — a 10×10 grid (each cell ≈ 1% of the window) beside a legend: system prompt, tools, context files, skills, compaction summary, user and assistant messages, tool results, extension messages, free space and the autocompact buffer. Parts are estimated at ~4 characters per token and scaled to the provider-reported total when one is known; context files, skills and tools are listed individually below.
+
+## Tasks, questions and history
+
+- **`jar_todo`** — a Claude-style task list the agent keeps for any multi-step request. It writes the full list at once; each task is `pending`, `in_progress` (exactly one at a time) or `completed`, with an `activeForm` ("Running tests") that replaces the working spinner text while it runs. The live checklist above the composer shows `✔` struck-through done tasks, a bold `◼` current task and `☐` pending ones; a finished list stays until your next prompt. `/jar tasks` is your view/editor: `a` add, <kbd>Space</kbd>/<kbd>Enter</kbd> check, `e` edit, `d` delete, `f` filter.
+- **`jar_ask`** — structured questions: numbered options with descriptions, single or multi-select, *Type your own answer* (multi-line, paste-friendly) and *Chat about this* to discuss before choosing.
+- **`/diff`** — review what the agent changed since its first edit to each file: files with `+/−` counts on the left, a numbered, colored diff on the right. `a` accept (keep, stop tracking), `r` then `y` revert (restore the original, or remove a file it created), `A`/`R` for all. The footer shows `± N files · /diff` while anything is unreviewed. Only `edit`/`write` changes inside the project are tracked; shell-made changes are not.
+- **`jar_shell`** — `start` (with optional `name`, `watch` regex and `notify`), `list`, `output`, `kill`. Output is ANSI-stripped and bounded (2000 lines). When a watch matches or the process ends, a visible message wakes the agent (queued if it is busy). The footer shows `⚙ N shells`; `/jar shells` opens a live view (`x` kill, `f` follow). All shells stop when the session ends.
+- **`jar_delegate`** — up to four subagents run in parallel as separate one-shot Pi processes with a fresh context, on a role (default `task`, then `default`, then the current model). They are read-only (`read`, `grep`, `find`, `ls`) unless `write: true`; subagents cannot delegate further; aborting the turn stops them. Each shows as a working teammate until it finishes, and the tool result lists every report.
+- **`/jar history`** — separate, read-only timeline of the active branch (paging, search, expandable details). Pi's native transcript is untouched.
+- Pi's built-in read/shell/edit/write tool cards render compactly; the full output or diff stays one click or <kbd>Ctrl</kbd>+<kbd>O</kbd> away.
+
+## Settings
+
+`/jar settings` (or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd>, or the welcome's Settings action) has three tabs:
+
+- **Appearance** — accent, motion, rounded composer, Ember mascot, next-prompt suggestions, pi-jar UI.
+- **Footer** — field visibility.
+- **Pi** — mouse clicks (Pi fullscreen mode), copy on select, goal auto rounds, advisor, advisor gates.
+
+pi-jar preferences are saved in `pi-jar-settings.json` in Pi's agent directory; the Pi tab writes Pi's own settings.
+
+## Integrations
+
+Other extensions can publish teammate roles and quota windows through Pi's public status API; see [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).
+
+## Repository structure
+
+```text
+pi-jar/
+├── extensions/index.ts   extension entry: wiring, welcome, footer, commands
+├── src/
+│   ├── flame.ts          pixel fire simulation
+│   ├── mascot.ts         Ember's moods and sprites
+│   ├── composer.ts       rounded composer, ghost text, mouse mapping
+│   ├── suggest.ts        jar_suggest tool and suggestion state
+│   ├── plan*.ts          plan mode, plan parsing/validation, plan view
+│   ├── goal*.ts          goal state and the implement → audit loop
+│   ├── model-roles.ts    role config, resolution, activation
+│   ├── roles-ui.ts       role manager
+│   ├── advisor.ts        jar_advisor, /advisor and stuck-work gates
+│   ├── side-model.ts     one-shot role model calls and their usage
+│   ├── commit.ts         /jar commit
+│   ├── usage-view.ts     /usage; context-view.ts is /context; panel.ts frames both
+│   ├── split-view.ts     shared two-pane frame
+│   ├── changes.ts        change tracker and line diff; diff-view.ts is /diff
+│   ├── shells.ts         background shells, jar_shell and /jar shells
+│   ├── delegate.ts       jar_delegate subagents
+│   ├── attachments.ts    image chips; prompt-search.ts is prompt history
+│   ├── session-gallery.ts recent sessions for the welcome
+│   ├── welcome.ts        welcome layout and hit-testing
+│   └── …                 footer, tasks, questions, history, settings, quota
+├── themes/               native Pi themes
+├── tests/                node:test suites
+└── docs/                 design, workflows, flame, integrations, development
+```
+
+## Documentation
+
+- [docs/SHOWCASE.md](docs/SHOWCASE.md) — README demo capture and media guidelines.
+- [docs/WORKFLOWS.md](docs/WORKFLOWS.md) — plan, goal, roles and suggestions in depth.
+- [docs/DESIGN.md](docs/DESIGN.md) — palette, motion, layout and accessibility.
+- [docs/FLAME.md](docs/FLAME.md) — how the flame and mascot are drawn.
+- [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) — public status contracts.
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — setup, testing and release checks.
+- [docs/PLAN.md](docs/PLAN.md) — roadmap.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/docs/DESIGN.md

@@ -0,0 +1,85 @@
+# Design
+
+## Identity
+
+pi-jar should feel technical, calm and readable, warm enough not to look like another neon-blue terminal, clearly aware of who (or which role) is doing what, and useful during long sessions.
+
+Rule of thumb: **state first, useful telemetry second, decoration last.** Every animation carries meaning, and everything still works with motion off.
+
+The public README demo is intentionally a real terminal capture rather than a mockup. It should show the flame, workspace card and composer at a readable scale without presenting decorative states that users cannot actually reach. See [SHOWCASE.md](SHOWCASE.md) for capture rules.
+
+## Palette
+
+| Purpose | Color |
+| --- | --- |
+| suggested terminal background | `#0B1018` |
+| surface | `#111927` |
+| default accent (teal) | `#00C2B8` |
+| technical blue | `#7FA8EE` |
+| warning amber | `#E5A940` |
+| success green | `#35C79A` |
+| text | `#F3F6FA` |
+| muted text | `#98A5B6` |
+| danger terracotta | `#EE7A5E` |
+
+`pi-jar-dark` uses the teal accent on deep navy surfaces with semantic status colors. Six alternate themes change only the accent and selection: gray, pink, teal, azure, violet and amber. Success, warning and error never change. `/jar accent <preset>` switches between loaded bundled themes; `default` restores teal. The fire palette used by the flame and mascot is documented in [FLAME.md](FLAME.md).
+
+## Role language
+
+Live teammate names and labels come from publishers (`pi-jar.role.<id>`, see [INTEGRATIONS.md](INTEGRATIONS.md)); pi-jar never invents them. `/jar demo` shows clearly labeled generic samples. Model roles (`/roles`) are a separate concept: they choose which model runs a workflow. The active one shows as `role:<name>` in the footer and on the welcome card.
+
+State colors: thinking/working → accent · reviewing → warning · done → success · failed → error · waiting/idle → dim.
+
+## Motion language
+
+| Surface | Motion | Stops when |
+| --- | --- | --- |
+| Welcome flame | pixel fire, embers, sparks (90 ms) | the welcome closes, or motion is off (frozen frame) |
+| Ember mascot | blinks, mood changes, tip flicker (repaints only on change) | motion off (calm face) or mascot off |
+| Working indicator | `✢ ✣ ✤` while generating, `◐ ◓ ◑ ◒` for tools | the run settles |
+| Footer roles | `◈ ◆`, `◐ ◓ ◑ ◒`, `◔ ◑ ◕ ●` | the role is idle, done or failed |
+
+Rules:
+
+1. labels never move; only glyphs animate;
+2. completed and failed states are static;
+3. idle UI does not repaint continuously;
+4. at most two prominent animations compete at once;
+5. motion is optional and never the only carrier of information.
+
+## Layout
+
+### Welcome
+
+- **Wide (≥ 72 columns):** flame and large `π` in a 28-column art column, with the card on the right, vertically centered.
+- **Medium (32–71):** a slightly cropped flame and compact `π` stacked above the card.
+- **Narrow (< 32):** cropped flame, compact `π` and a single Settings action.
+
+Card sections, top to bottom: header (version · model · effort · role), the **message hero**, workspace (project · git · session), workflow (plan · goal · tasks · roles · team), actions. The hero is the focal point: bold, painted in the flame's gold-to-orange ramp and set in double-width (fullwidth) letters when it fits in three lines, otherwise bold at normal width, with a dim "— welcome to pi-jar —" byline. **Refresh** picks a new message and flame. Long values truncate at the right. Actions are bracketed chips in fullscreen and plain keyboard hints in regular mode. A button is never advertised where it cannot be clicked.
+
+### Composer
+
+The Ember tip row sits above a rounded frame. The top border carries the face, the session title and the `↑ N more` overflow label; the bottom border carries `↓ N more` and dim key hints (hidden below 60 columns). Autocomplete menus render below the frame, aligned with the text. Ghost suggestions are dim and followed by `⇥ tab`.
+
+### Split views (plan view, roles, changes, shells)
+
+A shared frame (`src/split-view.ts`): title bar with a clickable `×`, a sidebar of `clamp(round(w × 0.26), 18, 32)` columns, a `│` divider, a body pane, a divider row, footer rows, and a closing border. Below 64 columns the sidebar collapses into a header pager.
+
+### Footer
+
+- **Wide (100+):** model · effort · session · cwd · context · RAM · cost, then roles and branch, with quota on a third line if needed.
+- **Medium (52–99):** fewer extras; context is always visible.
+- **Narrow (< 52):** model, effort, the active or failed role, context.
+
+The goal line shows `◎ goal · <progress>` when a goal exists.
+
+## Conversation timeline
+
+`/jar history` is an overlay built from a snapshot of the active branch. It is not a restyled transcript. Visible messages, compactions and branch summaries become rows; reasoning, hidden custom messages and image bytes are excluded. Paging (80 rows), 2 KiB / 30-line chunks and page-local search keep it bounded.
+
+## Accessibility
+
+- state never relies on color alone: every active state has a glyph or word;
+- motion-off preserves all information;
+- keyboard paths exist for every pointer action;
+- core rendering uses ordinary Unicode and works without 24-bit color.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,95 @@
+# Development
+
+## Requirements
+
+- Node.js 22.6+ (native TypeScript test runner)
+- npm
+- a current Pi installation
+
+## Local setup
+
+```bash
+git clone https://github.com/ygrip/pi-jar.git
+cd pi-jar
+npm install
+npm run check
+npm test
+```
+
+## Load locally in Pi
+
+Install the working copy as a local Pi package:
+
+```bash
+pi install "$(pwd)"
+```
+
+Or run against a temporary checkout without publishing it.
+
+Use `pi list` to verify the package is loaded. Loading only `--extension ./extensions/index.ts` does not register bundled themes: either install the package and restart Pi, or also pass `--theme ./themes` for a standalone development run. Avoid loading the extension twice by combining a package install with `--extension`.
+
+## Theme testing
+
+Select a theme with `/settings`: `pi-jar-dark`, or a `pi-jar-dark-<accent>` variant (gray/pink/teal/azure/violet/amber). Accent themes are generated from `src/accent.ts` and `themes/pi-jar-dark.json` with `npm run themes:build`. Pi hot-reloads custom theme files; package development may need `/reload`.
+
+Check user messages, tool pending/success/error states, diffs, markdown, syntax highlighting, every thinking level, bash mode, and narrow and wide terminals.
+
+## Extension testing
+
+Automated:
+
+```bash
+npm run check      # tsc --noEmit
+npm test           # node:test suites in tests/
+```
+
+Tests isolate `PI_CODING_AGENT_DIR`, so they never touch your real preferences. Suites cover the flame simulation, welcome layout and hit-testing, composer framing/expansion/ghost text/mouse mapping, the mascot, plan mode (guards, submission, reminders, restore), the plan view, plan parsing, the goal loop, roles v2, suggestions and settings.
+
+Manual smoke test (offline, throwaway agent directory, nothing sent to a model):
+
+```bash
+PI_OFFLINE=1 PI_SKIP_VERSION_CHECK=1 PI_TELEMETRY=0 \
+PI_CODING_AGENT_DIR="$(mktemp -d)" pi -e ./extensions
+```
+
+Then check:
+
+- the welcome at 24, 40, 80 and 120+ columns; <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>R</kbd> refresh; motion off (`/jar animations off`) freezes the flame;
+- the composer: typing `/pl` shows autocomplete below the frame; long drafts grow before scrolling; Ember changes mood while dialogs are open;
+- `/jar settings`: Tab through Appearance → Footer → Pi, toggle mouse mode and check Pi's `settings.json` in the temporary agent dir;
+- `/roles`: the split manager, `n` new role, `a` alias, `s` scope;
+- `/plan`: the status shows `◆ PLAN · read-only` and a directory appears under `$TMPDIR/pi-jar/plans/`.
+
+For pointer interaction start with `--tui-mode fullscreen` (or enable **Pi → Mouse clicks** and restart). Check that welcome actions fire once per press, that clicking composer text moves the cursor, that clicking Ember pokes it, that plan-view headings and actions respond to clicks and the wheel, and that selecting text anywhere still copies it.
+
+With a logged-in model, run end to end:
+
+1. `/plan add a hello command`: the agent writes `<slug>-plan.md`, submits it, the plan view opens; approve and watch `jar_todo` fill from the Approach steps.
+2. `/goal add a hello command with a test`: edits are blocked until tasks exist; the loop continues while tasks are open, then runs an audit and completes with evidence.
+3. After an ordinary request, a dim suggestion appears in the input; <kbd>Tab</kbd> accepts it.
+
+`/jar history` uses the public active-branch `getBranch()` snapshot and `ctx.ui.custom` overlays: `p`/`o` page, `/` search, `n`/`N` matches, `e` expand, `d`/`u` scroll details, `[`/`]` output chunks, <kbd>Esc</kbd> closes. It never mutates the branch.
+
+## Development rules
+
+- keep idle CPU and repaint overhead negligible (unref timers, render only on change);
+- use Pi's public extension API; do not couple to other extensions' internals;
+- keep role rendering generic;
+- no decorative animation that carries no state; preserve behavior with motion off;
+- never swallow pointer drags in pi-jar views (selection and copy-on-select belong to Pi);
+- tolerate hosts without optional APIs (`registerTool`, `registerShortcut`, mouse).
+
+## Startup performance
+
+pi-jar adds about 0.2 s to Pi's first render (mostly module import). To keep startup lean it never blocks `session_start`: the provider quota lookup, the welcome's recent-session scan and its `git` calls start 1.5 s after the session starts, and the card and footer fill in when they finish.
+
+Most startup time in a full setup comes from extension loading, which Pi does one package at a time. Measure a package by launching it alone (`pi -ne -e <path>`) and compare with `pi --no-extensions`. Large packages and ones installed from git (loaded as TypeScript source) cost the most, and the first launch after `pi update` is slow while Pi rebuilds its transpile cache. Keep rarely used packages out of the global `packages` list (load them with `-e`, or in project settings).
+
+## Publishing
+
+pi-jar is published to npm as `pi-jar`. The `pi-package` keyword lists it in the [Pi package gallery](https://pi.dev/packages), and `pi.image` in `package.json` supplies the gallery preview (the demo GIF, served from GitHub rather than shipped in the tarball).
+
+1. `npm run check && npm test`
+2. Bump `version` in `package.json`, commit and push.
+3. `npm pack --dry-run` — the tarball holds `extensions/`, `src/`, `themes/`, `docs/*.md`, `README.md` and `LICENSE` only.
+4. `npm login` (once), then `npm publish`.

package/docs/FLAME.md

@@ -0,0 +1,54 @@
+# Flame and mascot
+
+Both are original, dependency-free and rendered as plain terminal text inside Pi components.
+
+## Welcome flame (`src/flame.ts`)
+
+### Simulation
+
+One continuous flame on a 21 × 24 grid of intensities `0…9`. The width is odd so the flame has a true center column, which also lines up with the `π` beneath it.
+
+1. **Profile.** The half width at a height `h` (0 = base, 1 = tip) is a circular bulb below the belly (`h < 0.3`, up to 5.6 columns) and a smooth taper above it. The base is rounded and narrower than the belly, never a flat bar.
+2. **Motion.** Everything moves through smooth, seeded value noise rather than per-cell randomness: the flame's height breathes, the axis sways and wanders (more at the tip than at the base), and the edges ripple upward — barely at the base, strongly near the tip, so the top licks while the bottom stays calm.
+3. **Heat.** Each cell's heat falls off from the axis toward the rim (`1 − d^1.8`) and cools with height, so the core low in the flame is pale gold and the rim and tip are orange-red. A slow noise texture keeps the interior shimmering.
+4. **Wisps.** Occasionally a small piece breaks off the tip, rises and fades (at most two at a time).
+5. **Particles.** At most eight live particles lift off the upper flame near its axis. Embers rise at 0.3–0.8 rows/frame with a small drift, living 8–20 frames (`•` → `∙` → `·`, fading down the palette). Sparks (≈8% per frame) are fast, bright `✦`/`*` and last 2–4 frames. Particles only draw over empty cells and never on the outer columns.
+
+Randomness comes from a seeded PRNG (mulberry32), and the simulation warms up for 28 steps. So `flameFrame(frame, seed)` is a pure function: tests are deterministic, motion-off shows a still-lit frame, and **Refresh** simply picks a new seed.
+
+### Rendering
+
+Two simulated rows share one terminal row through half blocks: `▀` with the upper cell as foreground and the lower cell as background (`▄` when only the lower cell is lit). The output is 12 rows × 21 columns, fixed width.
+
+Palette (index 0 is transparent):
+
+| Heat | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Color | `#2B0A05` | `#5C1407` | `#8F2207` | `#C7400C` | `#E8601A` | `#F58A24` | `#FFB23A` | `#FFD56A` | `#FFF3C4` |
+
+Without 24-bit color (`COLORTERM` is not `truecolor`/`24bit`), cells become `░▒▓█` shaded with the theme's `dim`, `error` and `warning` colors.
+
+The welcome ticks every 90 ms only while it is visible and motion is on. On terminals narrower than 32 columns the flame is cropped around its center.
+
+## Ember, the composer mascot (`src/mascot.ts`)
+
+Ember is two layers:
+
+- a **face** in the composer's top border — always `( + three glyphs + )`, five columns wide in every mood, so the title never shifts;
+- **flame tips** on the row above the frame, five columns wide, aligned over the face.
+
+Moods come from Pi's observed activity plus local timers:
+
+| Mood | Face | Tips | Trigger |
+| --- | --- | --- | --- |
+| idle | `(•ᴗ•)` | swaying `▴▲▴` | nothing happening |
+| blink | `(-ᴗ-)` | still | 180 ms, every 3–6 s at random |
+| happy / thinking | `(^ᴗ^)` / `(°ᴗ°)` | bouncing / orbiting `∙` | generating (alternates every few seconds) |
+| tool | `(>ᴗ<)` | sparks `*` `·` | a tool is running |
+| waiting | `(•o•)` | `?` | a dialog or question is open |
+| sleepy | `(-ω-)` | dimmed, rising `z` | idle for two minutes |
+| error | `(×_×)` | drooping `ˇ` | a run failed (3 s) |
+| complete | `(★ᴗ★)` | star and sparks | a goal was completed (4 s) |
+| poke | `(^o^)` | bounce | you clicked the face (1.5 s) |
+
+Faces and tips are painted from the flame palette (pale-gold eyes, orange shell, redder when upset) or theme colors without 24-bit color. One unref'd 240 ms timer drives expressions, and it requests a render **only when the sprite actually changes**. Motion-off stops the timer and shows a calm face; turning the mascot off removes both layers. Below 40 columns the tips row is dropped.

package/docs/INTEGRATIONS.md

@@ -0,0 +1,82 @@
+# Integrations
+
+pi-jar presents public statuses from other extensions and owns its own session-local workflows (tasks, plans, goals, suggestions). It never reads another extension's private state. It targets the current `@earendil-works/*` Pi API; the legacy `@mariozechner/*` packages are not supported.
+
+## Public data
+
+The footer reads Pi's model, thinking level, context usage and git branch. It also shows the texts that other extensions publish with `ctx.ui.setStatus(key, text)`, which Pi exposes to custom footers through `footerData.getExtensionStatuses()`. Free-form status text stays free-form: pi-jar never infers roles, ordering or failure from prose.
+
+## Opt-in role contract
+
+An extension with authoritative teammate state can publish it:
+
+```ts
+ctx.ui.setStatus("pi-jar.role.worker-17", JSON.stringify({
+  name: "API Builder", label: "API", state: "working", task: "implement",
+  expiresAt: Date.now() + 30_000
+}));
+// Refresh before expiry while it is live; clear it when finished.
+ctx.ui.setStatus("pi-jar.role.worker-17", undefined);
+```
+
+- Key suffix: lowercase alphanumerics and hyphens, 1–32 characters.
+- `name` is required. `label` and `task` are optional human-readable strings.
+- `state`: `idle | thinking | working | waiting | reviewing | done | failed`.
+- `expiresAt`: epoch milliseconds, in the future and at most 30 s ahead. An expired, malformed or unsupported entry displays as `<id>: unavailable` until the publisher updates or clears it.
+- Fields are sanitized and bounded. The JSON may be at most 4096 characters.
+
+The welcome card's **TEAM** row and the footer roles use this data. Without a publisher, no teammate is shown.
+
+## Quota publisher (preferred over the network fallback)
+
+```ts
+ctx.ui.setStatus("pi-jar.quota.openai-codex", JSON.stringify({
+  fiveHour: { used: 42 }, week: { used: 15 },
+  expiresAt: Date.now() + 60_000
+}));
+```
+
+- `used` is a percentage from 0 to 100. Either window may be omitted, and each can carry an optional `resetsAt` (epoch milliseconds).
+- `expiresAt` is required and may be at most five minutes ahead. A valid published status always wins.
+- `/jar quota on` (the default each session) lets pi-jar resolve the current Anthropic or OpenAI Codex OAuth credentials through Pi's model registry and make a **read-only** request to the provider's quota endpoint when nothing is published.
+- Requests have a 5 s timeout and results (including failures) are cached for 5 minutes. `/jar quota off` cancels pending requests and clears the cache.
+- These provider endpoints are not stable public APIs.
+
+## Session entries owned by pi-jar
+
+| Custom type | Contents | Replay |
+| --- | --- | --- |
+| `pi-jar.task` | versioned to-do events (`write`, `add`, `edit`, `status`, `delete`; legacy `toggle` accepted) | active branch on start, tree navigation and compaction |
+| `pi-jar.goal` | goal events (`set`, `status`, `round`; v1 `set`/`clear` accepted) | active branch |
+| `pi-jar.plan` | plan state (`enabled`, `steps`, `text`, `path`, `title`) | active branch |
+
+Hidden context messages (`pi-jar.plan-context`, `pi-jar.plan-reminder`, `pi-jar.goal-context`, `pi-jar.goal-continuation`, `pi-jar.suggest-reminder`) are filtered or deduplicated in the `context` hook, so they never accumulate.
+
+## Tools pi-jar registers
+
+| Tool | Purpose |
+| --- | --- |
+| `jar_todo` | branch-aware checklist: `todos` full-list writes (`content`, `status` pending/in_progress/completed, `activeForm`), plus `list`, `add`, `start`, `done`, `open`, `edit`, `delete` |
+| `jar_ask` | structured questions answered in the TUI |
+| `jar_plan_submit` | submit a plan file for review (plan mode only) |
+| `jar_goal` | `get`, `complete` (with evidence, audit phase only), `block` |
+| `jar_suggest` | one next-prompt suggestion shown as composer ghost text |
+| `jar_shell` | background shells: `start` (`command`, `name`, `watch`, `notify`), `list`, `output`, `kill` |
+| `jar_delegate` | up to four parallel subagents (`tasks: [{task, name?, role?}]`, `write?`) |
+| `jar_advisor` | second opinion from the `advisor` role (`question?`, `draft?`) |
+
+`jar_shell` events arrive as a visible `pi-jar.shell` custom message that triggers (or queues) an agent turn. `jar_delegate` runs child processes with `PI_JAR_CHILD=1`, which keeps pi-jar in the child from registering `jar_delegate` again, and publishes each running subagent through the role contract above as `pi-jar.role.delegate-<batch>-<n>`. The advisor publishes `pi-jar.role.advisor` while it is consulting, and its `/advisor` and gate answers arrive as visible `pi-jar.advisor` custom messages.
+
+## Commands that overlap other packages
+
+pi-jar registers `/usage`, `/context` and `/advisor`. Pi keeps both commands when two extensions register the same name and suffixes the later one (for example `/usage:2`), so remove packages whose commands you no longer need (such as a separate usage, context or advisor extension) to keep the plain names on pi-jar.
+
+## Working signals and other managers
+
+Working wording, icon colors and Ember's moods use only Pi's public agent, turn, UI-prompt and tool-execution events. "Thinking" means active generation, not access to hidden reasoning. Motion stops when animations are off, the run settles, the UI is disabled or the session shuts down.
+
+`/jar hub` lists installed extension commands `/tasks` and `/subagents-fleet` when present and opens the one you pick. It never reads their data or replaces their controls.
+
+## Editor and footer ownership
+
+`/jar composer on` wraps an existing custom editor factory if another extension installed one, or otherwise replaces Pi's editor with a `CustomEditor` subclass that keeps Pi's application keybindings. `/jar composer off` restores only a factory pi-jar still owns and keeps the draft. `/jar ui off` gives the footer back to Pi.