plugin-gentleman 1.0.1 → 1.0.2

package/README.md

@@ -1,47 +1,38 @@
-# plugin-gentleman
+# Plugin Gentleman
 
-OpenCode TUI plugin featuring **Mustachi** — an animated ASCII mascot with eyes, mustache, and optional motivational phrases during busy states.
+> **Mustachi** — An animated ASCII mascot bringing personality to your OpenCode terminal.
 
-## What This Is
+An OpenCode TUI plugin that adds visual flair and environment awareness to your coding sessions:
 
-A TUI plugin for OpenCode that:
-- 🎭 Shows a prominent **ASCII mustache** on the home screen
-- 👤 Shows the full **Mustachi face** with eyes in the sidebar
-- 👀 Subtle **eye animations** in sidebar (optional, low-frequency)
-- 💬 **Motivational phrases** during busy/loading states in sidebar (Rioplatense Spanish style)
-- 🎨 Installs and applies the **Gentleman theme** automatically
-- 🖥️ Detects and displays your **OS and LLM providers** below the prompt
-- ⚙️ Fully **configurable** via `opencode.json`
+- 🎭 **Prominent ASCII mustache** on the home screen
+- 👤 **Full Mustachi face** with eyes in the sidebar
+- 👀 **Subtle eye animations** (optional, low-frequency)
+- 💬 **Motivational phrases** during busy states (Rioplatense Spanish style)
+- 🎨 **Gentleman theme** installed and applied automatically
+- 🖥️ **Environment detection** — displays your OS and LLM providers
+- ⚙️ **Fully configurable** via `opencode.json`
 
 ## Installation
 
-### Recommended: Global Plugin Installation
+### Quick Start
 
-This is the real, verified flow.
-
-1. Install the plugin with OpenCode:
+Install the plugin globally with OpenCode:
 
 ```bash
 opencode plugin plugin-gentleman --global
 ```
 
-2. OpenCode will download the package and update your global TUI config automatically.
-
-3. Restart OpenCode:
-
-```bash
-opencode
-```
+OpenCode will download the package and update your TUI config automatically.
 
-4. You should see:
-   - a prominent ASCII mustache on the home screen
-   - `OpenCode` below it
-   - `Detected: <OS> | <providers>` below the prompt area
-   - full Mustachi in the sidebar
+**Restart OpenCode** to see:
+- Prominent ASCII mustache on the home screen
+- `OpenCode` branding text
+- `Detected: <OS> · <providers>` below the prompt area
+- Full Mustachi face in the sidebar
 
-### Manual Config (only if you prefer editing config yourself)
+### Alternative: Manual Configuration
 
-If you want to manage the config manually instead of using `opencode plugin`, add this to `~/.config/opencode/opencode.json`:
+If you prefer managing config yourself, add this to `~/.config/opencode/opencode.json`:
 
 ```json
 {
@@ -50,11 +41,13 @@ If you want to manage the config manually instead of using `opencode plugin`, ad
 }
 ```
 
-OpenCode will install npm plugins listed there automatically on startup.
+OpenCode will install npm plugins automatically on startup.
+
+---
 
-### Development: Local Testing with npm link
+### For Developers
 
-For plugin development:
+**Local Testing with npm link:**
 
 ```bash
 npm link
@@ -71,92 +64,93 @@ Then add to `~/.config/opencode/opencode.json`:
 
 Restart OpenCode to see changes.
 
-### Development: Local Testing with Tarball
-
-For testing the packed artifact locally:
+**Local Testing with Tarball:**
 
 ```bash
 npm pack
 opencode plugin ./plugin-gentleman-<version>.tgz --global
 ```
 
-If your OpenCode version does not accept a tarball path there, use the recommended published-package flow instead.
+*If your OpenCode version doesn't accept a tarball path, use the published package flow instead.*
+
+---
 
 ## Features
 
-### Visual Layout
+### Visual Components
 
 **Home Screen:**
 - Prominent ASCII mustache (no face, just the mustache)
-- "OpenCode" branding text
-- Environment detection line below the prompt area showing OS and providers
+- "OpenCode" branding text  
+- Environment detection showing `OS · Providers` below the prompt area
 
 **Sidebar:**
 - Full Mustachi face with eyes and mustache
-- Animated eyes that occasionally look around (when animations enabled)
-- Tongue and motivational phrases during busy states (when animations enabled)
+- Animated eyes that occasionally look around *(when animations enabled)*
+- Tongue and motivational phrases during busy states *(when animations enabled)*
 
-### Mustachi Mascot
+### The Mustachi Mascot
 
-Mustachi is an ASCII character with:
-- Two large eyes that occasionally look in different directions (sidebar only)
-- A prominent mustache rendered in theme colors (both home and sidebar)
-- A tongue that appears during busy/loading states (sidebar only)
-- Motivational phrases in Rioplatense Spanish style (sidebar only)
+An ASCII character with personality:
+- **Eyes** that occasionally look in different directions *(sidebar only)*
+- **Mustache** rendered in theme colors *(both home and sidebar)*
+- **Tongue** that appears during busy/loading states *(sidebar only)*
+- **Motivational phrases** in Rioplatense Spanish style *(sidebar only)*
 
-Example phrases shown during busy states:
-- "Ponete las pilas, hermano..."
-- "Dale que va, dale que va..."
-- "Ya casi, ya casi..."
-- "Ahí vamos, loco..."
-- "Un toque más y listo..."
-- "Aguantá que estoy pensando..."
+**Example phrases during busy states:**
+- *"Ponete las pilas, hermano..."*
+- *"Dale que va, dale que va..."*
+- *"Ya casi, ya casi..."*
+- *"Ahí vamos, loco..."*
+- *"Un toque más y listo..."*
+- *"Aguantá que estoy pensando..."*
 
-### Animation Behavior
+### Animations
 
-**Low complexity, low frequency** — designed to be subtle and non-intrusive:
+**Low complexity, low frequency** — subtle and non-intrusive:
 
-1. **Eye Direction Animation** (when `animations: true`)
-   - Every ~4 seconds, Mustachi's eyes may look in a random direction
-   - 20% chance of eye movement per interval
-   - Returns to neutral position most of the time
+**Eye Direction** *(when `animations: true`)*
+- Every ~4 seconds, eyes may look in a random direction
+- 20% chance of movement per interval
+- Returns to neutral position most of the time
 
-2. **Busy State Animation** (when `animations: true`)
-   - Tongue appears when OpenCode is processing
-   - Motivational phrase rotates every 3 seconds
-   - Only active during detected busy states
+**Busy State** *(when `animations: true`)*
+- Tongue appears when OpenCode is processing
+- Motivational phrase rotates every 3 seconds
+- Only active during detected busy states
 
-3. **No Animation** (when `animations: false`)
-   - Mustachi stays in neutral position
-   - No eye movement
-   - No tongue or phrases during busy states
+**Disabled** *(when `animations: false`)*
+- Mustachi stays in neutral position
+- No eye movement, tongue, or phrases
 
-### Theme
+### Gentleman Theme
 
-The plugin bundles the **Gentleman theme** with a refined dark color palette:
-- Background: Deep navy (`#06080f`)
-- Primary: Soft blue (`#7FB4CA`)
-- Accent: Warm gold (`#E0C15A`)
-- Text: Clean white (`#F3F6F9`)
+A refined dark color palette:
+- **Background:** Deep navy (`#06080f`)
+- **Primary:** Soft blue (`#7FB4CA`)
+- **Accent:** Warm gold (`#E0C15A`)
+- **Text:** Clean white (`#F3F6F9`)
 
-Mustachi uses a 3-tone gradient:
-- **Top**: Accent (gold)
-- **Middle**: Primary (blue)
-- **Bottom**: Error/pink (`#CB7C94`)
+**Mustachi gradient** (3-tone):
+- **Top:** Accent gold
+- **Middle:** Primary blue  
+- **Bottom:** Error pink (`#CB7C94`)
 
 ### Environment Detection
 
-The plugin shows a "Detected" line with:
-- **OS Detection**: Reads distro name on Linux, shows "macOS" or "Windows" on other platforms
-- **Provider Detection**: Lists active LLM providers (OpenAI, Copilot, Google, etc.)
+Displays a "Detected" line with:
+- **OS Detection:** Reads distro name on Linux, shows "macOS" or "Windows" on other platforms
+- **Provider Detection:** Lists active LLM providers (OpenAI, Copilot, Google, etc.)
 
 Both are fully configurable and can be hidden.
 
+---
+
 ## Configuration
 
-All options are set via plugin tuple syntax in `opencode.json`:
+All options are configured via plugin tuple syntax in `opencode.json`.
 
-### Default Configuration
+### Default Settings
 
 ```json
 {
@@ -178,7 +172,7 @@ All options are set via plugin tuple syntax in `opencode.json`:
 }
 ```
 
-### Configuration Options
+### Available Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -190,7 +184,9 @@ All options are set via plugin tuple syntax in `opencode.json`:
 | `show_providers` | boolean | `true` | Show detected LLM providers |
 | `animations` | boolean | `true` | Enable Mustachi animations (eyes, busy state) |
 
-### Example: Disable Animations
+### Examples
+
+**Disable Animations:**
 
 ```json
 {
@@ -203,7 +199,7 @@ All options are set via plugin tuple syntax in `opencode.json`:
 
 Mustachi will remain static with neutral eyes and no busy-state expressions.
 
-### Example: Logo Only (No Detection)
+**Logo Only (No Detection):**
 
 ```json
 {
@@ -214,9 +210,9 @@ Mustachi will remain static with neutral eyes and no busy-state expressions.
 }
 ```
 
-Shows only Mustachi and the OpenCode branding, no OS/provider info.
+Shows only Mustachi and OpenCode branding, no OS/provider info.
 
-### Example: Show Only OS
+**Show Only OS:**
 
 ```json
 {
@@ -234,26 +230,32 @@ Shows only Mustachi and the OpenCode branding, no OS/provider info.
 }
 ```
 
+---
+
 ## How It Works
 
-1. **Theme Installation**: On load, installs `gentleman.json` into OpenCode themes
-2. **Theme Activation**: If `set_theme: true`, switches to the gentleman theme
-3. **Home Logo Slot**: Registers `home_logo` slot with mustache-only ASCII art
-4. **Environment Detection Slot**: Registers `home_bottom` slot with OS/provider info below the prompt
-5. **Sidebar Slot**: Registers `sidebar_content` slot with full Mustachi face and animations
-6. **Animation Loop**: If `animations: true`, starts interval timers for eye variations and busy-state detection (sidebar only)
-7. **Busy State Detection**: Attempts to read `api.state.session.running` (best-effort; may not be exposed by all OpenCode versions)
+The plugin integrates with OpenCode's TUI system through slot registration:
+
+1. **Theme Installation:** Installs `gentleman.json` into OpenCode themes on load
+2. **Theme Activation:** Switches to the gentleman theme *(if `set_theme: true`)*
+3. **Home Logo Slot:** Registers `home_logo` with mustache-only ASCII art
+4. **Environment Detection Slot:** Registers `home_bottom` with OS/provider info below the prompt
+5. **Sidebar Slot:** Registers `sidebar_content` with full Mustachi face and animations
+6. **Animation Loop:** Starts interval timers for eye variations and busy-state detection *(if `animations: true`, sidebar only)*
+7. **Busy State Detection:** Attempts to read `api.state.session.running` *(best-effort; may not be exposed by all OpenCode versions)*
 
-### Technical Details
+### Technical Stack
 
-- **No Build Step**: Plain TSX transpiled at runtime by OpenCode
-- **Solid.js Reactivity**: Uses `createSignal` and `createEffect` for animations
-- **Safe Detection**: All OS/provider detection wrapped in try-catch blocks
-- **Cleanup**: Uses `onCleanup` to clear intervals when component unmounts
+- **No Build Step:** Plain TSX transpiled at runtime by OpenCode
+- **Solid.js Reactivity:** Uses `createSignal` and `createEffect` for animations
+- **Safe Detection:** All OS/provider detection wrapped in try-catch blocks
+- **Cleanup:** Uses `onCleanup` to clear intervals when component unmounts
+
+---
 
 ## Supported Providers
 
-The plugin maps these provider IDs to friendly names:
+Friendly name mapping for LLM providers:
 
 | Provider ID | Display Name |
 |-------------|--------------|
@@ -270,75 +272,76 @@ The plugin maps these provider IDs to friendly names:
 | `together` | Together |
 | `perplexity` | Perplexity |
 
-Unknown provider IDs display the configured name or raw ID.
+*Unknown provider IDs display the configured name or raw ID.*
+
+---
+
+## Important Notes
 
-## Local Testing Limitations
+### TUI Plugin vs System Plugin
 
-**IMPORTANT**: This is a **TUI plugin** for npm installation. 
+**This is a TUI plugin for npm installation.**
 
-If you try to use this as a local system plugin (copying `.ts` files to `~/.config/opencode/plugins/`):
+If you copy `.ts` files to `~/.config/opencode/plugins/` (system plugin):
 - ❌ **NO visual changes** — system plugins cannot modify the TUI
-- ❌ **NO Mustachi** — only TUI plugins can register slot components
+- ❌ **NO Mustachi** — only TUI plugins can register slot components  
 - ❌ **NO animations** — JSX/Solid.js components only work in TUI plugins
 
-**For full features, use npm installation** (tarball or link method above).
+**For full features, use npm installation** (recommended global method above).
 
-## Repository Structure
-
-```
-oc-plugin-gentleman/
-├── tui.tsx              # TUI plugin entry point (main implementation) ✅ npm
-├── gentleman.json       # Gentleman theme definition ✅ npm
-├── package.json         # npm package manifest with exports ✅ npm
-├── README.md            # This file ✅ npm (auto-included)
-├── gentleman-local.ts   # Legacy local system plugin (repo-only, not in npm package)
-├── install-local-real.sh # Install script for local plugin (repo-only)
-├── install-local.sh     # Install script for local plugin (repo-only)
-└── mustachi examples/   # PNG reference images (repo-only)
-```
+### Package Contents
 
-**Files included in npm package** (via `files` field in package.json):
+**Files included in npm package** *(via `files` field in `package.json`)*:
 - `tui.tsx` — main plugin implementation
 - `gentleman.json` — theme definition
 - `package.json` — auto-included by npm
 - `README.md` — auto-included by npm
 
-**Local-only files** (excluded from npm, kept in repo for development/reference):
+**Repository-only files** *(excluded from npm package)*:
 - `gentleman-local.ts` — legacy local system plugin with limited features
 - `install-local-real.sh`, `install-local.sh` — local installation scripts
-- `mustachi examples/` — reference images
 
-## Caveats
+---
 
-1. **Busy State Detection**: The plugin attempts to detect busy states via `api.state.session.running`, but this may not be exposed in all OpenCode versions. If unavailable, busy-state animations won't trigger (eye animations still work in sidebar).
+## Known Limitations
 
-2. **Animation Frequency**: Currently set to low frequency (4s for eyes, 3s for phrase rotation). If this feels too fast or too slow in real usage, adjust the intervals in `tui.tsx`.
+1. **Busy State Detection:** The plugin attempts to detect busy states via `api.state.session.running`, but this may not be exposed in all OpenCode versions. If unavailable, busy-state animations won't trigger *(eye animations still work in sidebar)*.
 
-3. **Slot Usage**: The plugin uses these OpenCode TUI slots:
+2. **Animation Frequency:** Currently set to low frequency (4s for eyes, 3s for phrase rotation). Adjust the intervals in `tui.tsx` if needed.
+
+3. **Slot Usage:** The plugin uses these OpenCode TUI slots:
    - `home_logo` — mustache-only ASCII art
    - `home_bottom` — environment detection (OS + providers)
    - `sidebar_content` — full Mustachi face with animations
 
-4. **Theme Compatibility**: The plugin installs and optionally activates the Gentleman theme. If the user has a custom theme they prefer, they should set `set_theme: false`.
+4. **Theme Compatibility:** The plugin installs and optionally activates the Gentleman theme. If you prefer a custom theme, set `set_theme: false`.
+
+---
 
 ## Development
 
-To modify the plugin:
+### Modifying the Plugin
+
+To work on the plugin:
 
 1. Edit `tui.tsx` (main implementation)
 2. Test locally with `npm link` or `npm pack`
 3. No build step needed — OpenCode transpiles TSX at runtime
 4. Restart OpenCode to see changes
 
-To add new eye variations:
-- Edit the `eyeVariations` array in `tui.tsx` (affects sidebar only)
+### Adding New Content
 
-To add new busy phrases:
-- Edit the `busyPhrases` array in `tui.tsx` (affects sidebar only)
+**Eye variations:**
+- Edit the `eyeVariations` array in `tui.tsx` *(affects sidebar only)*
 
-To change animation timings:
+**Busy phrases:**
+- Edit the `busyPhrases` array in `tui.tsx` *(affects sidebar only)*
+
+**Animation timings:**
 - Adjust `setInterval` durations in the `SidebarMustachi` component
 
+---
+
 ## License
 
 ISC

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "plugin-gentleman",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "OpenCode TUI plugin featuring Mustachi - an animated ASCII mascot with eyes, mustache, and optional motivational phrases during busy states",
   "type": "module",
   "exports": {