osdy-pi 0.1.9 → 1.3.0

package/README.md

@@ -1,184 +1,357 @@
-# Osdy Pi
+# Osdy Pi — a themed, responsive Pi workspace
 
-<img width="1857" height="847" alt="image" src="https://github.com/user-attachments/assets/028eeb14-3f43-4f1c-9603-0c55a8d2856d" />
+Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive terminal presentation with a header, editor, working indicator, and Git view. Visit the [Osdy landing page](https://landing-osdy.vercel.app/).
 
-Theme package for [Pi](https://github.com/earendil-works/pi) with the Osdy terminal style: neon pink/purple colors, a custom ASCII header, and a framed editor experience.
+<img width="1857" height="847" alt="Osdy Pi interface" src="https://github.com/user-attachments/assets/028eeb14-3f43-4f1c-9603-0c55a8d2856d" />
 
-Visit the Osdy landing page: [landing-osdy.vercel.app](https://landing-osdy.vercel.app/).
+## Release highlights
 
-## What you get
+| Area | What ships |
+| --- | --- |
+| Message cards | Pi-native, theme-aware user and assistant cards; assistant accents follow the theme and user accents are white. |
+| Header and mascot | A theme-aware `neon` header and selectable `bts` mascot, both responsive and persisted independently. |
+| Accounts | `/osdy-account` switches Codex profiles in place with atomic activation, rollback, bounded auth files, and process-safe locks. |
+| Quota | `/usage` and compact bars emphasize remaining Codex quota at warning (40% or less) and error (15% or less) thresholds. |
 
-- **Dark theme:** `osdy-pi-dark`, enabled by default when the package starts.
-- **Light theme:** `osdy-pi-light`, with the same Osdy palette adapted for light terminals.
-- **Simple theme:** `osdy-pi-simple`, a blue/red/slate console theme for the full Pi interface.
-- **Custom header:** two selectable header styles with responsive status metadata: `osdy-theme` (default) and `classic`.
-- **Custom editor:** full-width framed input area with model, thinking, token, cost, and context status.
-- **Custom working indicator:** a dedicated working widget/spinner appears above the text box, outside the editor frame.
-- **Clean layout:** the built-in working row is hidden while Osdy Pi is enabled to avoid duplicated UI.
-- **Optional audio notifications:** configurable `.mp3`/`.wav` files for `completion`, `error`, `permission`, and `question` events on macOS and Windows.
+## Prerequisites
 
-<img width="1280" height="433" alt="image" src="https://github.com/user-attachments/assets/20c7624d-9ad8-4494-97fb-6b6d81aaf328" />
+- [Pi](https://github.com/earendil-works/pi)
+- Node.js **22.19.0 or later**
+- Git, for Osdy Pi's working-tree and diff features (and for Git-based installs)
 
-## Install in Pi
+## Quick start
 
-Install the published package from npm:
+1. Install Osdy Pi from npm:
+
+   ```bash
+   pi install npm:osdy-pi
+   ```
+
+   Or install directly from GitHub:
+
+   ```bash
+   pi install git:github.com/OsdyOrtiz/Osdy-Pi
+   ```
+
+2. Start Pi:
+
+   ```bash
+   pi
+   ```
+
+Osdy Pi's own extension and all **14 themes** are bundled with this installation—do not install them separately. Launch through `osdy-pi` (or `npm run pi:dev`) to activate a valid Osdy default account into Pi's shared agent directory before Pi starts. With no default, Pi remains unmanaged; run `/osdy-account` to create a profile and establish a default. On session start, Osdy Pi restores its persisted enabled state when a UI is available and preserves your selected Pi theme. When disabled, it leaves Gentle Shell (or Pi's native UI) untouched.
+
+### Optional: isolated `osdy` command
+
+Use this path when you want **installed, normal Pi** with Osdy-specific settings and sessions, without changing the official Pi profile. `pi install` loads package resources in Pi; it does not guarantee that package executables are available on your shell's `PATH`. To use the packaged commands, install the CLI separately (or run the scripts directly from a checkout):
+
+```bash
+npm install --global osdy-pi
+osdy-pi setup
+osdy
+```
+
+From an Osdy Pi checkout, `node bin/osdy-pi.mjs setup` or `node bin/osdy.mjs setup` works without a global CLI installation; `node bin/osdy.mjs` launches Pi. `osdy-pi setup` is explicit and repeatable; `osdy` also checks/reconciles the isolated profile before each launch and forwards its arguments to the installed `pi` executable. The default source is `~/.pi/agent`, the isolated destination is `~/.pi/osdy-agent`, and the Osdy source is the package containing the CLI. Set `OSDY_PI_SOURCE_AGENT_DIR`, `OSDY_PI_AGENT_DIR`, or `OSDY_PI_EXTENSION_ROOT` to override them with absolute paths. The setup needs one valid local `gentle-pi` checkout declared as an absolute source in official Pi's package settings; if none or several match, set `GENTLE_PI_EXTENSION_ROOT=/absolute/path/to/gentle-pi` before setup and launch. Missing or invalid Gentle sources fail with an actionable error rather than silently omitting Gentle. No Pi fork, build, or PATH shim is required.
+
+**What is isolated?** Official `~/.pi/agent/settings.json` is read but never rewritten by `osdy-pi setup` or `osdy`. Osdy keeps its own settings, selected theme, sessions, crash logs, and command history. Other existing top-level official resources are linked into the isolated profile only when absent—including `auth.json`, so credentials are **shared**, not isolated. Existing isolated files and symlinks are not replaced; the managed isolated settings are reconciled atomically. Named Codex accounts under `/osdy-account` are a separate feature, not this profile separation.
+
+**Already have `~/.local/bin/osdy`?** Check `type -a osdy` (or `command -v osdy`) before using the new command: a home-local launcher earlier on `PATH` still wins. Setup does **not** remove or replace it. To try the packaged launcher without changing PATH, use `node "$(npm root -g)/osdy-pi/bin/osdy.mjs" --version` after installing the CLI; `node "$(npm root -g)/osdy-pi/bin/osdy.mjs" setup` runs the same explicit setup. Compare `pi --version` and `osdy --version` once the intended command resolves. Keep the old launcher until you confirm which executable you want; migration/removal is manual.
+
+## Optional: complete Osdy Pi suite
+
+Add these maintained extensions after installing Osdy Pi. They are optional; each extends Pi independently.
+
+| Package | Purpose |
+| --- | --- |
+| `gentle-engram` | Persistent memory shared across sessions, compactions, and MCP agents. |
+| `pi-intercom` | Brokered communication between Pi agents and sessions. |
+| `@juicesharp/rpiv-ask-user-question` | Structured, typed questionnaires when an agent needs clarification. |
+| `pi-web-access` | Web search and URL fetching, plus repository, PDF, YouTube, and local-video analysis. |
+| `pi-lens` | Real-time code feedback through LSP, linters, formatters, type checking, and structural analysis. |
+| `pi-btw` | Parallel side conversations through `/btw`. |
+| `@open-pets/pi` | OpenPets integration for Pi. |
+| `pi-playwright` | Playwright browser-automation skills. |
+| `pi-mcp-adapter` | MCP server and tool adapter for Pi. |
+| `pi-subagents-j0k3r` | Markdown-defined subagents, delegation tools, history, and model profiles. |
+| `@juicesharp/rpiv-todo` | A persistent live todo overlay for the agent. |
+| `gentle-pi` | The Gentle senior-architect harness, with SDD/OpenSpec, subagents, TDD evidence, and skills. |
+
+Install the ordinary npm packages once:
 
 ```bash
-pi install npm:osdy-pi
+pi install npm:gentle-engram
+pi install npm:pi-intercom
+pi install npm:@juicesharp/rpiv-ask-user-question
+pi install npm:pi-web-access
+pi install npm:pi-lens
+pi install npm:pi-btw
+pi install npm:@open-pets/pi
+pi install npm:pi-playwright
+pi install npm:pi-mcp-adapter
+pi install npm:pi-subagents-j0k3r
+pi install npm:@juicesharp/rpiv-todo
 ```
 
-You can also install it directly from GitHub:
+`gentle-pi` is deliberately not included in that package-install block: clone and register it through the coexistence setup below, which applies Osdy-specific exclusions instead of adding a duplicate ordinary package entry.
 
 ```bash
-pi install git:github.com/OsdyOrtiz/Osdy-Pi
+git clone https://github.com/Gentleman-Programming/gentle-pi.git
+osdy-pi gentle setup "$(pwd)/gentle-pi"
 ```
 
-Then start Pi normally:
+## Gentle coexistence setup
+
+To load a local `gentle-pi` checkout while keeping Osdy Pi's UI authoritative, run:
 
 ```bash
-pi
+osdy-pi gentle setup /absolute/path/to/gentle-pi
 ```
 
-Osdy Pi enables the `osdy-pi-dark` theme and custom UI automatically on `session_start`.
+The command validates that the absolute source is a readable `gentle-pi` package with Gentle's todo and agents extensions before atomically updating `$PI_CODING_AGENT_DIR/settings.json` (or `~/.pi/agent/settings.json`). It registers the local package immediately before the first configured Osdy Pi package entry, so Gentle Shell initializes first, with exclusions only for Gentle's `gentle-todo.ts` and `gentle-agents.ts`, plus `themes: []`. Restart Pi or run `/reload` after setup.
 
-## Choose the theme manually
+Gentle Shell intentionally remains fully active underneath Osdy, including its footer and widgets. While Osdy is enabled, Osdy claims the footer and editor; disabling Osdy restores the editor Gentle Shell provided at session startup. Gentle's changes widget may coexist with Osdy's visual widgets.
 
-If you only want to switch themes, open Pi settings:
+The exclusions prevent Gentle's todo and agents extensions from competing with the suite. `@juicesharp/rpiv-todo` remains the authoritative todo overlay, `pi-subagents-j0k3r` remains the authoritative subagent system, and `@juicesharp/rpiv-ask-user-question` remains the authoritative structured-question plugin; their package entries are left untouched.
 
-```text
-/settings
+## OpenAI account profiles
+
+Osdy Pi can keep multiple ChatGPT Plus/Pro accounts authenticated and let you choose which one starts Pi. `personal` and `work` are only examples—you can create as many named profiles as you need.
+
+### Create and use profiles
+
+**In Pi, run `/osdy-account`** to open the complete account manager:
+
+| Action | Behavior |
+| --- | --- |
+| **Switch** | Waits for idle, safely replaces Pi's canonical auth with the selected profile, and updates active/default together without restarting Pi. |
+| **Add** | Creates an isolated profile without restarting or changing the default. Select it with **Switch**, then run `/login`. |
+| **Default** | Shows, changes, or clears the profile used by future plain installed `pi` and `npm run pi:dev` launches. It does not switch the current process. |
+| **Rename** | Renames an inactive profile. The default follows the new name when applicable. |
+| **Remove** | Permanently deletes an inactive profile after exact-name confirmation. Removing the default requires a replacement. |
+| **Account info** | Shows the available profiles and marks the active and default profiles without reading credentials. |
+
+Pi does not expose a supported API for extensions to invoke its OAuth login dialog. After switching to a newly created profile, run Pi's native `/login` and choose **ChatGPT Plus/Pro (Codex)**. This is the only step that remains a separate Pi command; it does not require leaving Pi or opening another terminal.
+
+Terminal commands remain available as recovery and automation alternatives:
+
+```bash
+# Create a profile without launching or changing the default.
+osdy-pi account create personal
+
+# Legacy recovery flow: create a profile and open Pi for /login.
+osdy-pi account add work
+
+# List profiles, choose the default, or launch one now.
+osdy-pi account list
+osdy-pi account default personal
+osdy-pi account default
+osdy-pi account use personal
+
+# Rename a profile, or permanently remove an inactive profile.
+osdy-pi account rename work consulting
+osdy-pi account remove consulting --confirm consulting
+
+# Removing the default requires an existing replacement.
+osdy-pi account remove personal --confirm personal --replacement work
+
+# Remove the preference without removing any profile.
+osdy-pi account default --clear
 ```
 
-Then select one of these theme names:
+Profile names accept ASCII letters, numbers, and hyphens, up to 63 characters, preserving their spelling (for example, `Personal` or `WORK`). Spaces, paths, and the reserved names `default`, `profiles`, and `auth.json` (in any casing) are rejected. Profile identity is case-insensitive, so names that differ only by casing cannot coexist. `account add` opens a profile for login but does not change the default.
+
+### See and switch the active account
+
+When Pi was launched through a profile, Osdy Pi shows its profile name in the editor:
+
+- **Simple/native editor:** beside the model, for example `gpt-5.6-sol · personal · think high`.
+- **Extended/framed editor:** `personal` replaces the `Osdy-Pi` title.
+- **No managed profile:** the existing model line and `Osdy-Pi` title remain unchanged.
+
+`account use <name>` activates the profile in Pi's shared agent directory, saves it as active/default, then starts Pi. Inside Pi, `/osdy-account` waits for active work to finish and swaps the canonical `auth.json` in place; the next request resolves the new account without a spawn, shutdown, session handoff, or restart.
+
+To resume a specific session directly from the terminal:
+
+```bash
+osdy-pi account use work -- --session /absolute/path/to/session.jsonl
+```
+
+> **Privacy:** each profile keeps a private `auth.json`; Pi runs against its canonical shared `auth.json`. Osdy Pi atomically copies opaque auth files between those private locations only to activate or preserve an account; it never parses, prints, logs, or passes OAuth credentials. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
+
+Account switching is serialized in-process and protected by a private cross-process lock. Osdy Pi accepts only bounded regular auth files, refuses symlink-based auth sources, writes replacements with private permissions, and restores the previous canonical auth and account metadata when activation fails. A separate namespace lock protects concurrent profile creation, rename, and removal. Launchers activate the selected auth before starting Pi while continuing to use the shared agent directory; existing managed-directory links from earlier profile layouts are resolved for compatibility.
+
+### Rename and permanently remove profiles
+
+Use `osdy-pi account rename <old> <new>` to rename an existing inactive profile. If it was the default, its default selection follows the new name.
+
+Use `osdy-pi account remove <name> --confirm <name>` for a non-default profile. This permanently deletes its isolated profile directory. Removing the default additionally requires `--replacement <other>`; the existing, different replacement becomes the default before deletion. A replacement is rejected for non-default removal.
+
+Before rename or removal, close this Pi process when it uses the target and **manually close every other Pi process using that target profile**. Osdy Pi does not scan or stop other processes. Inside Pi, use `/osdy-account` (or `/osdy-account rename` / `remove`); the guided flow shows the active profile but refuses changes to it until you Switch first, asks for a new default when needed, and requires typing the exact profile name. Cancellation changes nothing. Do not start two Pi processes with the same `--session` path.
+
+## What ships
+
+| Area | Included behavior |
+| --- | --- |
+| Themes | 14 built-in themes, including Osdy, Kanagawa, Dracula, Catppuccin, Matrix, and Lucent Orange palettes |
+| Header and mascot | Independently selectable `osdy-theme`/`neon` headers and `current`/`bts` mascots |
+| Messages | Pi-native, theme-aware user and assistant message cards |
+| Input | Responsive auto editor by default, with selectable simple Pi-native or extended framed modes |
+| Status | Custom working spinner, responsive footer metrics, dynamic extension statuses, and Codex subscription quota with low-capacity emphasis |
+| Git | Working-tree summary and a centered, filterable diff panel |
+| Audio | Optional event sounds on macOS and Windows |
+
+<img width="1280" height="433" alt="Osdy Pi header and editor" src="https://github.com/user-attachments/assets/20c7624d-9ad8-4494-97fb-6b6d81aaf328" />
+
+## Appearance
+
+### Themes
+
+| Theme | Use |
+| --- | --- |
+| `osdy-pi-new` | Landing palette: cyan, violet, silver, and navy. |
+| `osdy-pi-dark` | Dark alternative. |
+| `osdy-pi-sexy` | Gentleman neon pink palette. |
+| `osdy-pi-tokyo-night` | Tokyo Night dark palette. |
+| `osdy-pi-kanagawa-wave` | Kanagawa Wave dark palette. |
+| `osdy-pi-kanagawa-dragon` | Kanagawa Dragon dark palette. |
+| `osdy-pi-kanagawa-lotus` | Kanagawa Lotus light palette. |
+| `osdy-pi-dracula` | Dracula Classic dark palette. |
+| `osdy-pi-catppuccin-latte` | Catppuccin Latte light palette. |
+| `osdy-pi-catppuccin-frappe` | Catppuccin Frappé dark palette. |
+| `osdy-pi-catppuccin-macchiato` | Catppuccin Macchiato dark palette. |
+| `osdy-pi-catppuccin-mocha` | Catppuccin Mocha dark palette. |
+| `osdy-pi-matrix` | OpenCode Matrix dark palette. |
+| `osdy-pi-lucent-orange` | Lucent Orange dark palette with terminal-background passthrough. |
+
+Osdy Pi preserves your selected Pi theme when it enables, reapplies, or disables its UI. Choose any theme in Pi:
 
 ```text
-osdy-pi-dark
-osdy-pi-light
-osdy-pi-simple
+/settings
 ```
 
-You can also set it in your Pi `settings.json`:
+Or set the theme in Pi's `settings.json`:
 
 ```json
 {
-  "theme": "osdy-pi-dark"
+  "theme": "osdy-pi-sexy"
 }
 ```
 
-Use `osdy-pi-light` if you prefer the light version, or `osdy-pi-simple` if you want the blue/red/slate palette across the whole console.
+### Header, mascot, and animation
+
+Header and mascot choices are independent:
+
+| Element | Choices | Command |
+| --- | --- | --- |
+| Header | `osdy-theme` (default), `neon` | `/osdy-pi header osdy-theme|neon` |
+| Mascot | `current` (default), `bts` | `/osdy-pi mascot current|bts` |
+
+Both commands update the UI immediately. Add `status` instead of a choice to inspect the current selection. Choices persist in the global Osdy Pi settings across reloads and sessions. The old top-level style commands and `classic` header aliases are no longer registered.
+
+In normal mode, the selected header and mascot render side by side. The Neon header derives its highlights from the active theme rather than using one fixed palette. Each mascot keeps its own tone map while its animated edge glow can resolve through theme colors. Header and mascot scaling remain independent, so any combination follows the same responsive layout rules.
+
+Animation is enabled by default with an intro animation. Configure it through `OSDY_PI_ANIMATION`:
+
+| Value | Result |
+| --- | --- |
+| `0`, `off` | Static art |
+| `1`, `on`, `continuous` | Continuous animation |
+| `intro` | Intro animation, then static art |
+
+### Responsive layout
+
+| Terminal mode | Header and mascot | Editor and Git | Footer |
+| --- | --- | --- | --- |
+| Normal | Full selected header and mascot side by side | Auto mode shows the framed editor by default; simple selects Pi's native editor and extended selects the framed editor; Git summary when enabled | Native editor: model/thinking, usage, path/branch, then statuses; framed editor: path/branch then statuses |
+| Compact (72+ columns) | Proportionally scaled mascot above a readable header, reduced only when needed | Selected editor mode and Git behavior | Same editor-aware footer behavior as normal/small modes |
+| Small (<72 columns) | Mascot only; art and tone map scale proportionally | Pi native editor for every editor mode; Git summary hidden | Model + styled thinking level, usage, path/branch, then dynamic extension statuses (except Pi Lens) |
+
+In the extended framed editor, the active thinking level is rendered in bold in the top-right model metadata so it remains easy to scan.
+
+Small and compact modes trim only fully empty mascot-art and tone-map margins before applying one proportional width-and-height scale; mascot width starts near four-fifths of the available width. The header moves below the mascot as soon as side-by-side width would force the mascot into an additional width-limited reduction. Compact headers retain their source art when it fits and reduce proportionally only when a width or row bound requires it. Compact headers and mascots share a bounded terminal-row budget, so the header is omitted rather than collapsed into an unreadable one-row logo when there is not enough vertical space. The small-mode footer places the model and styled bare thinking level above usage, path/branch, and dynamic extension statuses. Pi Lens's footer status is hidden in small mode, but Pi Lens continues running. Usage includes input/output/cache-read/cache-write tokens, cost, and context. Extension statuses are supplied dynamically by Pi/extensions and may include Osdy Pi, MCP, or LSP; they are not hardcoded.
+
+The enabled state, editor mode, working-tree visibility preference, header, and mascot persist globally across Pi reloads and sessions, shared by all projects. They are saved in `$PI_CODING_AGENT_DIR/extensions/osdy-pi/settings.json`, or `~/.pi/agent/extensions/osdy-pi/settings.json` when `PI_CODING_AGENT_DIR` is unset. Existing settings without the new visual fields safely default to `osdy-theme` and `current`; the former `raccoon` mascot value migrates to `bts`. The selected editor mode and working-tree placement are restored when the terminal moves normal → small → normal.
 
 ## Commands
 
-Osdy Pi includes a small command group:
+| Group | Command |
+| --- | --- |
+| Main | `/osdy-pi` |
+| Main | `/osdy-pi enable\|disable\|on\|off\|status` |
+| Accounts | `/osdy-account` |
+| Header | `/osdy-pi header osdy-theme\|neon\|status` |
+| Mascot | `/osdy-pi mascot current\|bts\|status` |
+| Editor | `/osdy-pi editor auto\|extended\|simple\|on\|off\|toggle\|status` |
+| Working tree | `/osdy-pi working-tree on\|off\|toggle\|status` |
+| Working tree | `/osdy-pi working-tree position top\|bottom\|status` |
+| Audio | `/osdy-pi sound setup` |
+| Diff | `/osdy-pi diff` |
+| Codex subscription | `/usage` |
 
-```text
-/osdy-pi enable
-/osdy-pi disable
-/osdy-pi status
-/osdy-pi sound setup
-/osdy-pi working-tree on
-/osdy-pi working-tree off
-/osdy-pi working-tree toggle
-/osdy-pi working-tree status
-/osdy-pi working-tree position top
-/osdy-pi working-tree position bottom
-/osdy-pi diff
-/osdy-pi osdy-theme
-/osdy-pi classic
-/osdy-pi-osdy-theme
-/osdy-pi-classic
-```
+`/osdy-pi` reports status. `enable` (or `on`) applies the Osdy Pi UI without changing the selected Pi theme; `disable` (or `off`) restores the Gentle Shell or Pi UI captured at session startup while preserving that theme. The enabled state, editor mode, working-tree visibility, and sound configuration persist globally.
 
-- `enable` applies the dark Osdy theme, custom header, custom editor, and clean layout.
-- `disable` restores Pi's built-in header, editor, footer, and working visibility, then switches back to the previous theme or `dark`.
-- `status` shows whether the Osdy Pi UI is currently enabled, including the active style.
-- `sound setup` opens the guided global sound-setup wizard for audio notifications.
-- `working-tree on|off|toggle|status` controls the persistent git working-tree summary widget.
-- `working-tree position top|bottom` moves the summary widget above or below the editor.
-- `diff` opens a floating centered diff window to inspect the current per-file diff without leaving Pi.
-- `osdy-theme` is the default OsdyTheme header with pink, cyan, and purple styling, plus the mascot glow on the right edge.
-- `classic` keeps the previous classic header shape with the shared mascot.
-- `/osdy-pi-osdy-theme` and `/osdy-pi-classic` are direct aliases.
+### Codex subscription usage
 
-After changing a local extension, run `/reload` or restart Pi so the updated commands are registered.
+Run `/usage` to open the Codex subscription dashboard for the active managed `openai-codex` profile and model. Press `r` to refresh; `esc` or `q` closes it. The dashboard shows these controls at the bottom.
 
-### Working tree widget
+The main windows are labeled **Session** and **Weekly** (the API/domain remains primary/secondary). Their remaining-capacity bars are full at 100% remaining and empty at 0%; labels use the active theme's bold accent, Session uses the accent fill, Weekly uses `mdLink`, and empty segments are muted. The remaining percentage stays muted above 40%, changes to the theme's warning color at 40% or less, and changes to its error color at 15% or less. The same thresholds apply in the `/usage` dashboard and compact footer/editor quota bars. A double themed frame, section dividers, and spacing separate the display. Detail cards show each duration and relative, local, and UTC reset times. Plan, availability, credits/reset count, and additional buckets appear only when the service supplies them; absent optional values are omitted.
 
-Osdy Pi can show a persistent git working-tree summary above or below the editor.
+At wide widths, the modal pairs the Session and Weekly detail cards. Below 72 content columns, cards and bars stack and account/model data wraps. The native footer and extended editor also show compact Session/Weekly remaining-capacity bars below model and thinking metadata whenever a current Codex snapshot exists. Wide widths combine those bars; narrow widths stack them. Additional buckets appear only in `/usage`.
 
-Current behavior:
+Usage loads once when the session starts and refreshes when the modal opens or `r` is pressed; it does not poll. A refresh clears the previous snapshot before authentication resolves, and shutdown clears state, so quota data cannot cross account or profile boundaries.
 
-- shows file count, `+/-` totals, and staged/unstaged/new counts;
-- previews the top changed files;
-- refreshes automatically when Pi finishes mutating tools such as `edit`, `write`, `ast_grep_replace`, or `bash`;
-- is intentionally scoped to changes observed during Pi-driven work for now.
+> **Privacy:** OAuth is resolved only through Pi's `modelRegistry`. Osdy Pi does not read `auth.json`, persist or log credentials, or display account IDs, tokens, response bodies, or endpoint internals in the UI. Requests use a fixed HTTPS endpoint with bounded timeout, response size, and redirects.
 
-Use these commands to control it:
+## Native message cards
 
-```text
-/osdy-pi working-tree on
-/osdy-pi working-tree off
-/osdy-pi working-tree toggle
-/osdy-pi working-tree status
-/osdy-pi working-tree position top
-/osdy-pi working-tree position bottom
-/osdy-pi diff
-```
+Osdy Pi delegates conversation rendering to Pi's native message-card components. It does not install a Markdown transformer or inject card markup into assistant responses. This preserves Pi's own streaming, selection, and Markdown behavior while allowing every bundled Osdy theme to style the native cards.
 
-The `/osdy-pi diff` viewer now opens in the most viable floating-window form for Osdy Pi: a centered floating dialog with a selector step and a patch step.
+User and assistant cards have separate background, text, and accent tokens. Assistant accents follow each theme's primary accent; user accents are white for a consistent visual distinction. Disabling Osdy Pi continues to restore the underlying Gentle Shell or Pi presentation normally.
 
-1. select a changed file in the floating window
-2. open its patch in the same centered floating window
-3. return with `esc` / `backspace` or close with `q`
+## Editor and working indicator
 
-Controls:
+The default `auto` editor mode preserves the responsive behavior: it uses the framed editor when space permits and Pi's native editor on small terminals. Select `simple` for Pi's native editor at every width, or `extended` to request the framed editor explicitly: `/osdy-pi editor auto|extended|simple`. Simple mode actually unmounts the custom editor component rather than hiding it. Small terminals always use Pi's native editor, including when `extended` is selected. The legacy commands remain compatible where feasible: `on` maps to `extended`, `off` maps to `simple`, and `toggle` switches between extended and simple.
 
-- selector: type to filter, `↑` / `↓` or `j` / `k`, then `enter` or `→`
-- patch view: `PgUp` / `PgDn`
-- back: `esc` / `backspace` or `←`
-- close: `q`
+In auto or extended mode at a non-small width, the framed editor shows the model and thinking level in its title and session usage in its footer. For an account-profile launch, the left title shows the active profile name instead of `Osdy-Pi`. When the native editor is effective (simple mode or any small terminal), the Osdy footer instead shows model, active profile when present, thinking, and usage rows before its path/branch and status rows. It uses the currently active Pi/Osdy theme palette; no separate editor theme selector exists. Usage covers input, output, cache read, cache write when present, cost, and context. If Pi supports autocomplete, the editor uses Pi's native autocomplete rendering while the completion UI is visible.
 
-## Audio notifications
+A custom spinner appears above the editor while work is active. Osdy Pi hides Pi's built-in working row while enabled to avoid a duplicate indicator.
 
-Osdy Pi can play your own sound files for these product-level events:
+## Working tree and diff
 
-- `completion`: the full orchestrator flow finishes and Pi returns control to input.
-- `error`: a real tool execution failure occurs during the flow.
-- `permission`: reserved for future explicit Pi approval hooks, dormant by default today.
-- `question`: reserved for future explicit Pi question hooks, dormant by default today.
+The working-tree summary is enabled by default. It reads the repository state at session start, including existing changes, and reports staged, unstaged, and untracked counts with total `+/-` changes. It also has clean and unavailable states. `working-tree off` unregisters the widget completely, and a persisted disabled preference leaves it unmounted when the next session starts. `working-tree on` remounts and refreshes it without requiring a restart. After successful `edit`, `write`, `ast_grep_replace`, or `bash` tool execution, it refreshes.
 
-Initial audio playback support is implemented for:
+Use `working-tree position top` or `bottom` to place the summary above or below the editor. The widget supplies trailing blank space and adds leading separation when it is below the editor or the spinner is active, keeping the surrounding layout readable without promising a fixed number of blank lines in every state.
 
-- macOS
-- Windows
+`/osdy-pi diff` opens a centered diff panel. Type to filter paths, then inspect staged, unstaged, or untracked patches for a file.
 
-Unsupported platforms fall back safely without crashing Osdy Pi.
+| Action | Controls |
+| --- | --- |
+| Move selection | Arrow keys or `j` / `k` |
+| Open a patch | `enter`, `right`, `space`, or `l` |
+| Scroll a patch | `PgUp` / `PgDn` (or `space` forward) |
+| Go back | `esc`, `backspace`, `left`, or `h` |
+| Close | `q` or `ctrl+c` |
 
-### Supported files
+## Audio notifications
 
-Only readable `.mp3` and `.wav` files are accepted.
+Osdy Pi can play readable `.mp3` or `.wav` files on macOS and Windows. Other platforms safely skip playback. macOS playback requires the system `afplay` command; Windows playback requires `powershell.exe` and the Windows Media Player COM component (`WMPlayer.OCX`).
 
-### Configure sounds
+| Event | Current meaning |
+| --- | --- |
+| `completion` | An agent run ends. |
+| `error` | The first failed tool execution in an agent run. |
+| `permission` | Hook is available but dormant until an explicit Pi approval integration uses it. |
+| `question` | Hook is available but dormant until an explicit Pi question integration uses it. |
 
-The preferred setup path is the guided Osdy Pi wizard:
+Run the guided wizard:
 
 ```text
 /osdy-pi sound setup
 ```
 
-The wizard:
-
-- walks through `completion`, `error`, `permission`, and `question`;
-- lets you keep, replace, clear, or skip each event;
-- validates every selected path before save;
-- blocks save if any selected file is missing, unreadable, not a regular file, or not `.mp3`/`.wav`;
-- stores accepted settings globally at `~/.pi/agent/extensions/osdy-pi/audio-notifications.json` (or `$PI_CODING_AGENT_DIR/extensions/osdy-pi/audio-notifications.json` when that env var is set).
+It configures `completion`, `error`, `permission`, and `question`; validates selected readable audio files; and saves global settings to `~/.pi/agent/extensions/osdy-pi/audio-notifications.json`, or `$PI_CODING_AGENT_DIR/extensions/osdy-pi/audio-notifications.json` when `PI_CODING_AGENT_DIR` is set.
 
-Saved global sound paths apply across restarts and projects that use Osdy Pi.
-
-### Startup flags still work
-
-You can still pass sound paths as Pi flags when starting the session:
+Startup flags can override a saved path per event:
 
 ```bash
 pi \
@@ -188,63 +361,55 @@ pi \
   --osdy-pi-sound-question /absolute/path/question.wav
 ```
 
-Precedence is per event:
+Precedence is startup flag, then saved global setting, then unconfigured. Empty flags do not override saved settings; relative startup paths resolve from the current working directory, while the wizard saves normalized absolute paths. Missing, unreadable, or unsupported files are skipped safely.
 
-1. startup flag
-2. saved global Osdy Pi setting
-3. unconfigured
+## Local install and development
 
-Notes:
+For the normal in-Pi development flow, no global `osdy-pi` link is required:
 
-- Empty or omitted flags mean that event does not override the saved global setting.
-- Relative startup-flag paths resolve from the current working directory.
-- The setup wizard saves normalized absolute paths for global settings.
-- `~` expands to your home directory.
-- Invalid, unreadable, or unsupported files are skipped at playback time without changing existing UI behavior.
-- If a file was valid when saved but later disappears or becomes unreadable, Osdy Pi fails safely and skips playback for that event.
-- Audio notifications and sound setup are additive only, they do not change the current header, editor, footer, working indicator, theme, or commands.
+1. Install the checkout's dependencies:
 
-## Local install
+   ```bash
+   npm install
+   ```
 
-If you cloned this repository and want to test it locally without colliding with an already installed global `osdy-pi`, use the isolated dev launcher:
+2. Start the local extension:
 
-```bash
-npm run pi:dev
-```
+   ```bash
+   npm run pi:dev
+   ```
 
-This command runs `pi -e .` with `PI_CODING_AGENT_DIR=.pi-dev`, so it uses a separate local Pi config/package/extensions directory and does not load your global installed `osdy-pi` package.
+3. Inside Pi, run `/osdy-account`.
+4. Choose **Add**, enter a profile name, then choose **Switch** and select it.
+5. Without restarting, run `/login` and choose **ChatGPT Plus/Pro (Codex)**.
+6. From then on, `npm run pi:dev` starts the default profile automatically. Use `/osdy-account` for every profile-management action.
 
-You can still launch it manually if needed:
+The terminal interface remains available for recovery and automated testing:
 
 ```bash
-PI_CODING_AGENT_DIR="$PWD/.pi-dev" pi -e .
+npm run pi:dev -- account create personal
+npm run pi:dev -- account list
+npm run pi:dev -- account use personal
+npm run pi:dev -- account default personal
+npm run pi:dev -- account rename personal private
+npm run pi:dev -- account remove private --confirm private
 ```
 
-To install it from a local path:
+`npm run pi:dev` launches `pi -e <absolute repository root>` with `PI_CODING_AGENT_DIR=<absolute repository root>/.pi-dev`. If its `.pi-dev` metadata names a valid profile, it activates that profile's auth before launching Pi and retains `-e <absolute repository root>`. The development `.pi-dev` profile store and the installed Pi profile store are separate. Account commands use this checkout's local launcher, so no global `osdy-pi` link is needed. The development extension root remains loaded after an in-process `/osdy-account` switch. The manual equivalent is:
 
 ```bash
-pi install /absolute/path/to/Osdy-Pi
+PI_CODING_AGENT_DIR="$PWD/.pi-dev" OSDY_PI_DEV_EXTENSION_ROOT="$PWD" pi -e "$PWD"
 ```
 
-![Osdy Pi preview](https://raw.githubusercontent.com/OsdyOrtiz/Osdy-Pi/main/mapche1.png)
-
-## Package contents
+Install a local checkout into Pi with:
 
-```text
-themes/osdy-pi-dark.json
-themes/osdy-pi-light.json
-themes/osdy-pi-simple.json
-extensions/osdy-pi.ts
-extensions/osdy-pi/
+```bash
+pi install /absolute/path/to/Osdy-Pi
 ```
 
-`extensions/osdy-pi.ts` is the package entrypoint. The implementation lives in the modular `extensions/osdy-pi/` folder (runtime, UI, metrics, working controller, animation, border, and formatting helpers).
-
-The Pi manifest is declared in `package.json` through `pi.themes` and `pi.extensions`, so Pi can discover the themes and extension after installation.
+After changing a local extension, run `/reload` or restart Pi.
 
-## Development
-
-If you are working on the package locally, you can run:
+For package checks and local development:
 
 ```bash
 npm run typecheck
@@ -252,16 +417,29 @@ npm run lint
 npm run pi:dev
 ```
 
-## Uninstall or turn off
+![Osdy Pi preview](https://raw.githubusercontent.com/OsdyOrtiz/Osdy-Pi/main/mapche1.png)
+
+## Limits and troubleshooting
+
+- The custom UI requires a Pi session with a UI; otherwise it does not mount.
+- A compact terminal stacks a scaled mascot over a source-size header when it fits, reducing the header only when needed; below 72 columns it switches to mascot-only, native editor, and no Git summary until space returns.
+- The Git summary reports unavailable when Git commands cannot read a working tree.
+- Diff patches depend on readable repository files; a file whose patch cannot load shows the reported error in the panel.
+- Audio playback is limited to macOS and Windows and to readable `.mp3`/`.wav` files.
+- `/usage` requires an active `openai-codex` login. Run `/login` and choose **ChatGPT Plus/Pro (Codex)**; run `/reload` after local extension changes.
+- A `401` indicates an expired session, while a `403` means usage is unavailable. Optional backend fields may be absent and simply do not render.
+
+## Disable, uninstall, and license
 
-To temporarily turn off the custom UI inside Pi:
+Turn off the custom UI persistently (including across `/reload`):
 
 ```text
 /osdy-pi disable
+# Alias: /osdy-pi off
 ```
 
-To remove the package completely, use Pi's package management command for installed packages.
+Restore it with `/osdy-pi enable` or `/osdy-pi on`.
 
-## License
+To remove the package, use Pi's package-management command for installed packages.
 
 MIT