osdy-pi 0.1.8 → 1.2.0

package/README.md

@@ -1,184 +1,238 @@
-# 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/).
+## Quick start
 
-## What you get
-
-- **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.
-
-<img width="1280" height="433" alt="image" src="https://github.com/user-attachments/assets/20c7624d-9ad8-4494-97fb-6b6d81aaf328" />
-
-## Install in Pi
-
-Install the published package from npm:
+Install from npm:
 
 ```bash
 pi install npm:osdy-pi
 ```
 
-You can also install it directly from GitHub:
+Or install directly from GitHub:
 
 ```bash
 pi install git:github.com/OsdyOrtiz/Osdy-Pi
 ```
 
-Then start Pi normally:
+Start Pi normally:
 
 ```bash
 pi
 ```
 
-Osdy Pi enables the `osdy-pi-dark` theme and custom UI automatically on `session_start`.
+`pi install` installs Osdy Pi's extension resources. When you later run plain `pi`, a valid Osdy default account automatically hands off once to the bundled launcher and resumes the saved session under that profile. With no default, Pi remains unmanaged; run `/osdy-account` to create a profile and establish a default. On session start, Osdy Pi enables its UI when a UI is available and preserves your selected Pi theme.
 
-## Choose the theme manually
+## OpenAI account profiles
 
-If you only want to switch themes, open Pi settings:
+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.
 
-```text
-/settings
+### Create and use profiles
+
+**In Pi, run `/osdy-account`** to open the complete account manager:
+
+| Action | Behavior |
+| --- | --- |
+| **Switch** | Restarts Pi safely with another profile, resumes the current saved session, and makes that profile the default. |
+| **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 lowercase letters, numbers, and hyphens, up to 63 characters. Spaces, paths, uppercase letters, and the reserved names `default`, `profiles`, and `auth.json` are rejected. `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>` saves that existing profile as the default before it starts Pi. Inside Pi, `/osdy-account` does the same after you select another profile. Osdy Pi waits for active work to finish, starts the replacement Pi with the current saved session, confirms that the new Pi process started, and only then closes the previous process. This is a controlled restart, not an in-process credential swap.
+
+To resume a specific session directly from the terminal:
+
+```bash
+osdy-pi account use work -- --session /absolute/path/to/session.jsonl
+```
+
+> **Privacy:** only Pi's managed `auth.json` is isolated per profile. Session history, settings, installed packages, and extension resources are shared, so every profile can access that local state. Osdy Pi never reads, copies, prints, or passes OAuth credentials. It keeps Pi's canonical `openai-codex` provider and delegates authentication to Pi's built-in `/login` flow.
+
+### 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 | Selectable `osdy-theme` and `classic` header/mascot styles |
+| Input | Responsive auto editor by default, with selectable simple Pi-native or extended framed modes |
+| Status | Custom working spinner, responsive footer metrics, and dynamic extension statuses |
+| 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.
-
-## Commands
+### Header, mascot, and animation
 
-Osdy Pi includes a small command group:
+`osdy-theme` is the default header style; `classic` is the alternative. In normal mode, both styles render their full selected header and mascot. The header animation and mascot edge glow resolve through the active theme, so each installed palette supplies its own accents. Use `/osdy-pi osdy-theme` or `/osdy-pi classic`, or their direct aliases `/osdy-pi-osdy-theme` and `/osdy-pi-classic`.
 
-```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
-```
+Animation is enabled by default with an intro animation. Configure it through `OSDY_PI_ANIMATION`:
 
-- `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 wizard-style in-app diff viewer 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.
+| Value | Result |
+| --- | --- |
+| `0`, `off` | Static art |
+| `1`, `on`, `continuous` | Continuous animation |
+| `intro` | Intro animation, then static art |
 
-After changing a local extension, run `/reload` or restart Pi so the updated commands are registered.
+### Responsive layout
 
-### Working tree widget
+| 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) |
 
-Osdy Pi can show a persistent git working-tree summary above or below the editor.
+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.
 
-Current behavior:
+The editor mode and working-tree visibility preference 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. The selected editor mode and working-tree placement are restored when the terminal moves normal → small → normal.
 
-- 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.
-
-Use these commands to control it:
+## Commands
 
-```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
-```
+| Group | Command |
+| --- | --- |
+| Main | `/osdy-pi` |
+| Main | `/osdy-pi enable\|disable\|status` |
+| Accounts | `/osdy-account` |
+| Header | `/osdy-pi osdy-theme\|classic` |
+| 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` |
+| Alias | `/osdy-pi-osdy-theme` |
+| Alias | `/osdy-pi-classic` |
 
-The `/osdy-pi diff` viewer now behaves like a simple wizard and opens with a wider centered modal by default:
+`/osdy-pi` reports status. `enable` applies the Osdy Pi UI without changing the selected Pi theme; `disable` restores Pi's built-in header, editor, footer, and working row while preserving that theme. The editor mode, working-tree visibility, and sound configuration persist globally; other UI toggles are current-session desired state.
 
-1. select a changed file in a centered modal
-2. open its patch in a second centered view
-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`. 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: `↑` / `↓` 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. 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.
 
-### 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).
-
-Saved global sound paths apply across restarts and projects that use Osdy Pi.
+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.
 
-### 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 +242,49 @@ 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.
+
+## Local install and development
 
-1. startup flag
-2. saved global Osdy Pi setting
-3. unconfigured
+For the normal in-Pi development flow, no global `osdy-pi` link is required:
 
-Notes:
+1. Start the local extension:
 
-- 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.
+   ```bash
+   npm run pi:dev
+   ```
 
-## Local install
+2. Inside Pi, run `/osdy-account`.
+3. Choose **Add**, enter a profile name, then choose **Switch** and select it.
+4. After the managed restart, run `/login` and choose **ChatGPT Plus/Pro (Codex)**.
+5. From then on, `npm run pi:dev` starts the default profile automatically. Use `/osdy-account` for every profile-management action.
 
-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:
+The terminal interface remains available for recovery and automated testing:
 
 ```bash
-npm run pi:dev
+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
 ```
 
-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.
-
-You can still launch it manually if needed:
+`npm run pi:dev` launches `pi -e <absolute repository root>` with `PI_CODING_AGENT_DIR=<absolute repository root>/.pi-dev` when no default is set. If its `.pi-dev` metadata names a valid profile, it routes through this checkout's local launcher and starts that profile while retaining `-e <absolute repository root>`. The development `.pi-dev` profile store and the installed Pi profile store are separate. For an installed package, plain `pi` loads extension resources; at startup Osdy Pi hands off through its bundled launcher when the installed store has a valid default, while no default leaves ordinary unmanaged Pi running. Account commands use this checkout's local launcher, so no global `osdy-pi` link is needed. The development extension root is inherited by profile launches, keeping the local extension loaded after an `/osdy-account` handoff. The manual equivalent is:
 
 ```bash
-PI_CODING_AGENT_DIR="$PWD/.pi-dev" pi -e .
+PI_CODING_AGENT_DIR="$PWD/.pi-dev" OSDY_PI_DEV_EXTENSION_ROOT="$PWD" pi -e "$PWD"
 ```
 
-To install it from a local path:
+Install a local checkout into Pi with:
 
 ```bash
 pi install /absolute/path/to/Osdy-Pi
 ```
 
-![Osdy Pi preview](https://raw.githubusercontent.com/OsdyOrtiz/Osdy-Pi/main/mapche1.png)
-
-## Package contents
-
-```text
-themes/osdy-pi-dark.json
-themes/osdy-pi-light.json
-themes/osdy-pi-simple.json
-extensions/osdy-pi.ts
-extensions/osdy-pi/
-```
+After changing a local extension, run `/reload` or restart 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.
-
-## Development
-
-If you are working on the package locally, you can run:
+For package checks and local development:
 
 ```bash
 npm run typecheck
@@ -252,16 +292,24 @@ 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.
 
-To temporarily turn off the custom UI inside Pi:
+## Disable, uninstall, and license
+
+Temporarily turn off the custom UI:
 
 ```text
 /osdy-pi disable
 ```
 
-To remove the package completely, use Pi's package management command for installed packages.
-
-## License
+To remove the package, use Pi's package-management command for installed packages.
 
 MIT

package/bin/osdy-pi.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import {
+	clearDefaultAccount,
+	ensureProfileLayout,
+	getSharedAgentDir,
+	listProfiles,
+	parseAccountCommand,
+	planDefaultLaunch,
+	planPiLaunch,
+	readDefaultAccount,
+	removeProfile,
+	renameProfile,
+	setDefaultAccount,
+	validateExistingProfile,
+} from "../scripts/osdy-pi-account-profiles.mjs";
+
+function writeStdout(message) {
+	process.stdout.write(`${message}\n`);
+}
+
+function writeStderr(message) {
+	process.stderr.write(`${message}\n`);
+}
+
+function printUsage() {
+	writeStderr(
+		"Usage: osdy-pi account list | create <name> | add <name> | rename <old> <new> | remove <name> --confirm <name> [--replacement <other>] | use <name> [-- <pi args...] | default [<name> | --clear]",
+	);
+}
+
+function boundedMessage(error) {
+	const message =
+		error instanceof Error ? error.message : "Unable to manage Osdy Pi accounts.";
+	return message.slice(0, 240);
+}
+
+function sendLauncherMessage(message) {
+	if (typeof process.send === "function") process.send(message);
+}
+
+function reportLauncherFailure(error) {
+	const message = boundedMessage(error);
+	sendLauncherMessage({ type: "osdy-pi-error", message });
+	writeStderr(message);
+}
+
+function startPi(plan) {
+	const child = spawn(plan.command, plan.args, {
+		stdio: "inherit",
+		env: { ...process.env, ...plan.env },
+	});
+	child.once("spawn", () => {
+		sendLauncherMessage({ type: "osdy-pi-ready" });
+	});
+	child.on("error", (error) => {
+		reportLauncherFailure(new Error(`Failed to start Pi: ${error.message}`));
+		process.exitCode = 1;
+	});
+	child.on("exit", (code, signal) => {
+		if (signal) process.kill(process.pid, signal);
+		else process.exitCode = code ?? 1;
+	});
+}
+
+try {
+	const args = process.argv.slice(2);
+	const sharedAgentDir = getSharedAgentDir();
+	if (args.length === 0) {
+		const result = await planDefaultLaunch(sharedAgentDir);
+		if (result.defaultAccount.status === "invalid")
+			writeStderr("Ignoring invalid Osdy Pi default account metadata.");
+		startPi(result.plan);
+	} else {
+		const command = parseAccountCommand(args);
+		if (command.action === "list") {
+			const profiles = await listProfiles(sharedAgentDir);
+			if (profiles.length === 0)
+				writeStdout(
+					"No Osdy Pi accounts. Add one with: osdy-pi account add <name>",
+				);
+			else writeStdout(profiles.join("\n"));
+		} else if (command.action === "default") {
+			if (command.operation === "query") {
+				const account = await readDefaultAccount(sharedAgentDir);
+				if (account.status === "valid") writeStdout(account.profile);
+				else if (account.status === "unset") writeStdout("No default account.");
+				else
+					writeStdout("Default account metadata is invalid; no account selected.");
+			} else if (command.operation === "clear") {
+				await clearDefaultAccount(sharedAgentDir);
+				writeStdout("Default account cleared.");
+			} else {
+				await setDefaultAccount(sharedAgentDir, command.name);
+				writeStdout(`Default account set to ${command.name}.`);
+			}
+		} else if (command.action === "create") {
+			await ensureProfileLayout(sharedAgentDir, command.name);
+			writeStdout(
+				"Account profile created. Use /osdy-account Switch, then run /login and select ChatGPT Plus/Pro (Codex).",
+			);
+		} else if (command.action === "add") {
+			await ensureProfileLayout(sharedAgentDir, command.name);
+			writeStdout(
+				"Account profile is ready. In Pi, run /login and select ChatGPT Plus/Pro (Codex).",
+			);
+			startPi(planPiLaunch(sharedAgentDir, command.name));
+		} else if (command.action === "rename") {
+			await renameProfile(sharedAgentDir, command.oldName, command.newName);
+			writeStdout(`Account profile renamed to ${command.newName}.`);
+		} else if (command.action === "remove") {
+			await removeProfile(sharedAgentDir, command.name, {
+				confirmation: command.name,
+				replacement: command.replacement,
+			});
+			writeStdout(`Account profile ${command.name} permanently removed.`);
+		} else {
+			await validateExistingProfile(sharedAgentDir, command.name);
+			await setDefaultAccount(sharedAgentDir, command.name);
+			startPi(planPiLaunch(sharedAgentDir, command.name, command.piArgs));
+		}
+	}
+} catch (error) {
+	reportLauncherFailure(error);
+	printUsage();
+	process.exitCode = 1;
+}