osdy-pi 1.2.0 → 1.3.0

package/README.md

@@ -4,27 +4,114 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 <img width="1857" height="847" alt="Osdy Pi interface" src="https://github.com/user-attachments/assets/028eeb14-3f43-4f1c-9603-0c55a8d2856d" />
 
+## Release highlights
+
+| 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. |
+
+## Prerequisites
+
+- [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)
+
 ## Quick start
 
-Install 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
-pi install npm:osdy-pi
+npm install --global osdy-pi
+osdy-pi setup
+osdy
 ```
 
-Or install directly from GitHub:
+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 git:github.com/OsdyOrtiz/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
 ```
 
-Start Pi normally:
+`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
+git clone https://github.com/Gentleman-Programming/gentle-pi.git
+osdy-pi gentle setup "$(pwd)/gentle-pi"
 ```
 
-`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.
+## Gentle coexistence setup
+
+To load a local `gentle-pi` checkout while keeping Osdy Pi's UI authoritative, run:
+
+```bash
+osdy-pi gentle setup /absolute/path/to/gentle-pi
+```
+
+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.
+
+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.
+
+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.
 
 ## OpenAI account profiles
 
@@ -36,7 +123,7 @@ Osdy Pi can keep multiple ChatGPT Plus/Pro accounts authenticated and let you ch
 
 | Action | Behavior |
 | --- | --- |
-| **Switch** | Restarts Pi safely with another profile, resumes the current saved session, and makes that profile the default. |
+| **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. |
@@ -71,7 +158,7 @@ osdy-pi account remove personal --confirm personal --replacement work
 osdy-pi account default --clear
 ```
 
-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.
+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
 
@@ -81,7 +168,7 @@ When Pi was launched through a profile, Osdy Pi shows its profile name in the ed
 - **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.
+`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:
 
@@ -89,7 +176,9 @@ To resume a specific session directly from the terminal:
 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.
+> **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
 
@@ -104,9 +193,10 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 | 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 |
+| 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, and dynamic extension statuses |
+| 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 |
 
@@ -149,7 +239,16 @@ Or set the theme in Pi's `settings.json`:
 
 ### Header, mascot, and animation
 
-`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`.
+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`:
 
@@ -167,31 +266,51 @@ Animation is enabled by default with an intro animation. Configure it through `O
 | 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 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.
+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
 
 | Group | Command |
 | --- | --- |
 | Main | `/osdy-pi` |
-| Main | `/osdy-pi enable\|disable\|status` |
+| Main | `/osdy-pi enable\|disable\|on\|off\|status` |
 | Accounts | `/osdy-account` |
-| Header | `/osdy-pi osdy-theme\|classic` |
+| 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` |
-| Alias | `/osdy-pi-osdy-theme` |
-| Alias | `/osdy-pi-classic` |
+| Codex subscription | `/usage` |
+
+`/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.
+
+### Codex subscription usage
 
-`/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.
+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.
+
+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.
+
+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`.
+
+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.
+
+> **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.
+
+## Native message cards
+
+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.
+
+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.
 
 ## Editor and working indicator
 
-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.
+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.
 
 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.
 
@@ -199,7 +318,7 @@ A custom spinner appears above the editor while work is active. Osdy Pi hides Pi
 
 ## Working tree and diff
 
-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.
+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.
 
 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.
 
@@ -215,7 +334,7 @@ Use `working-tree position top` or `bottom` to place the summary above or below
 
 ## Audio notifications
 
-Osdy Pi can play readable `.mp3` or `.wav` files on macOS and Windows. Other platforms safely skip playback.
+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`).
 
 | Event | Current meaning |
 | --- | --- |
@@ -248,16 +367,22 @@ Precedence is startup flag, then saved global setting, then unconfigured. Empty
 
 For the normal in-Pi development flow, no global `osdy-pi` link is required:
 
-1. Start the local extension:
+1. Install the checkout's dependencies:
+
+   ```bash
+   npm install
+   ```
+
+2. Start the local extension:
 
    ```bash
    npm run pi:dev
    ```
 
-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.
+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.
 
 The terminal interface remains available for recovery and automated testing:
 
@@ -270,7 +395,7 @@ npm run pi:dev -- account rename personal private
 npm run pi:dev -- account remove private --confirm private
 ```
 
-`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:
+`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_CODING_AGENT_DIR="$PWD/.pi-dev" OSDY_PI_DEV_EXTENSION_ROOT="$PWD" pi -e "$PWD"
@@ -301,15 +426,20 @@ npm run pi:dev
 - 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
 
-Temporarily turn off the custom UI:
+Turn off the custom UI persistently (including across `/reload`):
 
 ```text
 /osdy-pi disable
+# Alias: /osdy-pi off
 ```
 
+Restore it with `/osdy-pi enable` or `/osdy-pi on`.
+
 To remove the package, use Pi's package-management command for installed packages.
 
 MIT

package/bin/osdy-pi.mjs

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setupOsdyProfile } from "../scripts/osdy-pi-profile-setup.mjs";
+import { configureGentleCoexistence } from "../scripts/osdy-pi-gentle-coexistence.mjs";
 import {
 	clearDefaultAccount,
 	ensureProfileLayout,
@@ -12,7 +17,7 @@ import {
 	removeProfile,
 	renameProfile,
 	setDefaultAccount,
-	validateExistingProfile,
+	switchAccountAuth,
 } from "../scripts/osdy-pi-account-profiles.mjs";
 
 function writeStdout(message) {
@@ -25,7 +30,7 @@ function writeStderr(message) {
 
 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]",
+		"Usage: osdy-pi setup | gentle setup <absolute-source-path> | account list | create <name> | add <name> | rename <old> <new> | remove <name> --confirm <name> [--replacement <other>] | use <name> [-- <pi args...] | default [<name> | --clear]",
 	);
 }
 
@@ -65,13 +70,31 @@ function startPi(plan) {
 
 try {
 	const args = process.argv.slice(2);
-	const sharedAgentDir = getSharedAgentDir();
-	if (args.length === 0) {
+	if (args[0] === "setup") {
+		if (args.length !== 1) throw new Error("Usage: osdy-pi setup");
+		const home = homedir();
+		const result = await setupOsdyProfile({
+			officialDir: process.env.OSDY_PI_SOURCE_AGENT_DIR || join(home, ".pi", "agent"),
+			profileDir: process.env.OSDY_PI_AGENT_DIR || join(home, ".pi", "osdy-agent"),
+			osdyRoot: process.env.OSDY_PI_EXTENSION_ROOT || resolve(dirname(fileURLToPath(import.meta.url)), ".."),
+			gentleRoot: process.env.GENTLE_PI_EXTENSION_ROOT || undefined,
+		});
+		writeStdout(`Isolated Osdy profile ${result.status}: ${result.profileDir}`);
+	} else if (args[0] === "gentle") {
+		if (args[1] !== "setup" || args.length !== 3)
+			throw new Error("Usage: osdy-pi gentle setup <absolute-source-path>");
+		const result = await configureGentleCoexistence(args[2]);
+		writeStdout(
+			`Gentle coexistence ${result.status}. Restart Pi or run /reload to apply it.`,
+		);
+	} else if (args.length === 0) {
+		const sharedAgentDir = getSharedAgentDir();
 		const result = await planDefaultLaunch(sharedAgentDir);
 		if (result.defaultAccount.status === "invalid")
 			writeStderr("Ignoring invalid Osdy Pi default account metadata.");
 		startPi(result.plan);
 	} else {
+		const sharedAgentDir = getSharedAgentDir();
 		const command = parseAccountCommand(args);
 		if (command.action === "list") {
 			const profiles = await listProfiles(sharedAgentDir);
@@ -104,6 +127,7 @@ try {
 			writeStdout(
 				"Account profile is ready. In Pi, run /login and select ChatGPT Plus/Pro (Codex).",
 			);
+			await switchAccountAuth(sharedAgentDir, command.name);
 			startPi(planPiLaunch(sharedAgentDir, command.name));
 		} else if (command.action === "rename") {
 			await renameProfile(sharedAgentDir, command.oldName, command.newName);
@@ -115,8 +139,7 @@ try {
 			});
 			writeStdout(`Account profile ${command.name} permanently removed.`);
 		} else {
-			await validateExistingProfile(sharedAgentDir, command.name);
-			await setDefaultAccount(sharedAgentDir, command.name);
+			await switchAccountAuth(sharedAgentDir, command.name);
 			startPi(planPiLaunch(sharedAgentDir, command.name, command.piArgs));
 		}
 	}

package/bin/osdy.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/* global process, console */
+import { spawn } from "node:child_process";
+import { constants as osConstants, homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { setupOsdyProfile } from "../scripts/osdy-pi-profile-setup.mjs";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const home = homedir();
+const officialDir = process.env.OSDY_PI_SOURCE_AGENT_DIR || join(home, ".pi", "agent");
+const profileDir = process.env.OSDY_PI_AGENT_DIR || join(home, ".pi", "osdy-agent");
+const osdyRoot = process.env.OSDY_PI_EXTENSION_ROOT || packageRoot;
+const gentleRoot = process.env.GENTLE_PI_EXTENSION_ROOT || undefined;
+
+try {
+	if (process.argv[2] === "setup" && process.argv.length !== 3)
+		throw new Error("Usage: osdy setup");
+	const result = await setupOsdyProfile({ officialDir, profileDir, osdyRoot, gentleRoot });
+	if (process.argv[2] === "setup") {
+		console.log(`Isolated Osdy profile ${result.status}: ${result.profileDir}`);
+	} else {
+		const child = spawn("pi", process.argv.slice(2), {
+			stdio: "inherit",
+			env: {
+			...process.env,
+			PI_CODING_AGENT_DIR: result.profileDir,
+			OSDY_PI_DEV_EXTENSION_ROOT: osdyRoot,
+		},
+		});
+		child.on("error", (error) => {
+			console.error(`osdy: Could not launch installed pi from PATH: ${error.message}`);
+			process.exitCode = 1;
+		});
+		child.on("exit", (code, signal) => {
+			if (signal) process.exitCode = 128 + (osConstants.signals[signal] ?? 1);
+			else process.exitCode = code ?? 1;
+		});
+	}
+} catch (error) {
+	console.error(`osdy: ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+}