Redesign README in KeyMood style

README.md

@@ -1,71 +1,203 @@
-# Codex Usage Widget
+<h1 align="center">Codex Usage Widget</h1>
+
+<p align="center">
+  <img src="docs/assets/readme/widget-hero.svg" alt="Codex Usage Widget preview" width="72%" />
+</p>
+
+<p align="center">
+  <img src="docs/assets/readme/taskbar-preview.svg" alt="Codex Usage Widget on the Windows taskbar" width="72%" />
+</p>
+
+<p align="center">
+  <strong>A compact Windows taskbar gauge for the Codex limits that matter.</strong><br />
+  See the current 5-hour and weekly allowance without reopening Codex.<br /><br />
+  No API key. No auth-file access. No cloud service. No usage estimation.
+</p>
+
+<p align="center">
+  <a href="https://github.com/Everyseok/codex-usage-widget">
+    <img src="https://img.shields.io/badge/Source-GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub repository" />
+  </a>
+  <a href="https://github.com/Everyseok/codex-usage-widget/releases/tag/v1.0.0">
+    <img src="https://img.shields.io/badge/Release-v1.0.0-2563EB?style=for-the-badge" alt="Release v1.0.0" />
+  </a>
+  <img src="https://img.shields.io/badge/Runtime-Windows%2010%2F11-0078D4?style=for-the-badge&logo=windows11&logoColor=white" alt="Windows 10 and 11" />
+  <img src="https://img.shields.io/badge/App-Taskbar%20Widget-0EA5E9?style=for-the-badge" alt="Taskbar widget" />
+  <img src="https://img.shields.io/badge/Updates-Local%20Realtime-16A34A?style=for-the-badge" alt="Local real-time updates" />
+  <img src="https://img.shields.io/badge/Privacy-No%20Auth%20Reads-E11D48?style=for-the-badge" alt="No authentication-file reads" />
+</p>
+
+---
+
+## What Makes It Different
+
+| Usual usage check | Codex Usage Widget |
+|---|---|
+| Reopen Codex and expand the usage panel | Keeps both limits visible on the taskbar |
+| Poll a remote endpoint or store an API key | Reads the rate-limit snapshot Codex already wrote locally |
+| Estimate usage from tokens or elapsed time | Displays the reported `used_percent` value directly |
+| Refresh on a fixed timer only | Reacts to session-file changes in about 500 ms |
+| Looks like a separate desktop overlay | Uses a transparent 232 px Fluent taskbar surface |
+
+The widget is intentionally narrow in scope. It watches Codex `token_count` events, extracts the latest `rate_limits` snapshot, converts usage into remaining percentage, and renders only two taskbar rows: `5H` and `WEEK`.
+
+---
+
+## Core Properties
+
+- **Reported usage, not guessed usage**: values come from Codex rate-limit snapshots.
+- **Two-window glance**: 5-hour and weekly limits stay visible in one compact surface.
+- **Event-driven refresh**: a filesystem watcher reacts to JSONL changes with a 500 ms debounce.
+- **Taskbar-aware placement**: the widget anchors immediately left of the Windows notification area.
+- **Full-screen friendly**: it hides over full-screen apps and returns with the taskbar.
+- **Local privacy boundary**: it does not read `auth.json`, make network requests, or require credentials.
+
+---
+
+## Local Usage Runtime
+
+| Layer | Value |
+|---|---|
+| App type | C# WinForms taskbar widget |
+| Runtime | .NET Framework 4.8 |
+| Session path | `%USERPROFILE%\.codex\sessions\**\*.jsonl` |
+| Event type | `event_msg` → `token_count` |
+| Usage payload | `rate_limits.primary` / `rate_limits.secondary` |
+| Live update | `FileSystemWatcher` + 500 ms debounce |
+| Fallback update | 15-second refresh timer |
+| Taskbar anchor | `Shell_TrayWnd` / `TrayNotifyWnd` |
+| Rendering | Per-pixel alpha layered window |
+| Privacy boundary | No auth files, clipboard, screenshots, or network calls |
+
+### Usage Model
+
+Codex reports how much of a rate-limit window has been used. The widget converts it into the value shown on the taskbar:
 
-A compact Windows 11 taskbar widget that displays the remaining Codex 5-hour and weekly usage limits.
+```text
+remaining_percent = clamp(100 - used_percent, 0, 100)
+```
 
-## Features
+Rate-limit windows are classified by duration:
 
-- Two stacked `5H` and `WEEK` gauges in a 232 px-wide taskbar surface
-- Transparent Fluent styling with Arial Bold and the Windows 11 blue accent
-- Event-driven updates within roughly 0.5 seconds of a Codex session change
-- 15-second fallback refresh and manual refresh on left-click
-- Reset details in a tooltip and a small right-click menu
-- Automatic hiding over full-screen apps
-- Single-instance execution and optional start-at-sign-in installation
-- No network requests, API keys, or reads from Codex authentication files
+```text
+5H   = nearest reported window between 240 and 360 minutes
+WEEK = nearest reported window to 10,080 minutes, with a 6-day minimum
+```
 
-## How it works
+If a reset timestamp has passed before a new snapshot arrives, the local display returns to `100%`. A limit omitted from the latest snapshot is shown as `N/A` rather than replaced with an estimate.
 
-Codex writes rate-limit snapshots to JSONL files under `%USERPROFILE%\.codex\sessions`. The widget watches those files and reads only `token_count` events containing `rate_limits`.
+---
 
-The reported `used_percent` value is converted to remaining usage. A limit that is not present in the latest snapshot is shown as `N/A`. For example, some plans report a weekly window but no separate 5-hour window.
+## Display States
 
-This project uses a local implementation detail rather than a public Codex usage API, so a future Codex session-format change may require a parser update.
+| Condition | Display | Accent |
+|---|---|---|
+| Limit not reported | `N/A` | Neutral gray |
+| More than 35% remaining | Percentage gauge | Windows blue |
+| 16-35% remaining | Percentage gauge | Amber |
+| 0-15% remaining | Percentage gauge | Red |
 
-## Requirements
+Hovering the widget shows the exact remaining value, reset time, and timestamp of the latest Codex snapshot. Left-click refreshes immediately; right-click opens the native Refresh/Exit menu.
 
-- Windows 10 or Windows 11
-- .NET Framework 4.8
-- Codex Desktop or Codex CLI session data under `%USERPROFILE%\.codex\sessions`
+---
 
-## Build
+## Quick Start
+
+Clone and install from source:
+
+```powershell
+git clone https://github.com/Everyseok/codex-usage-widget.git
+cd codex-usage-widget
+.\install.ps1
+```
 
-Open PowerShell in the repository root and run:
+Build without installing:
 
 ```powershell
 .\build.ps1
 ```
 
-The executable is written to `dist\CodexUsageWidget.exe`.
+The standalone executable is written to `dist\CodexUsageWidget.exe`.
 
-## Install
+---
+
+## Verification
+
+Build the same artifact produced by GitHub Actions:
 
 ```powershell
-.\install.ps1
+.\build.ps1
+Get-FileHash .\dist\CodexUsageWidget.exe -Algorithm SHA256
 ```
 
-The installer copies the executable to `%LOCALAPPDATA%\CodexUsageWidget`, adds a Startup shortcut, and launches the widget.
-
-## Uninstall
+Install and confirm the running path:
 
 ```powershell
-.\uninstall.ps1
+.\install.ps1
+Get-Process CodexUsageWidget | Select-Object Path
 ```
 
-## Controls
+The repository workflow builds on `windows-latest` and uploads `CodexUsageWidget.exe` as an Actions artifact.
 
-- Left-click: refresh immediately
-- Right-click: open the Refresh/Exit menu
-- Hover: show remaining usage, reset time, and the latest data timestamp
+---
 
-## Project structure
+## Requirements
 
-```text
-src/CodexUsageWidget/
-  Interop/       Win32 declarations
-  Models/        Rate-limit data models
-  Services/      Session parsing and real-time file monitoring
-  UI/            Layered taskbar window and drawing
-  Program.cs     Single-instance application entry point
-```
+| Requirement | Version / Note |
+|---|---|
+| Windows | Windows 10 or Windows 11 |
+| Runtime | .NET Framework 4.8 |
+| Codex data | Desktop or CLI sessions under `%USERPROFILE%\.codex\sessions` |
+| Network | Required only for clone, Actions, and release download |
+| Installed location | `%LOCALAPPDATA%\CodexUsageWidget` |
+| Taskbar footprint | 232 × 42 px at 100% scaling |
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `5H` shows `N/A` | The latest Codex snapshot may not report a separate 5-hour window for this plan. |
+| Both rows show `N/A` | Use Codex once, then confirm that `.codex\sessions` contains recent JSONL files. |
+| Values look stale | Left-click the widget; the 15-second fallback refresh will also re-read the latest snapshot. |
+| Widget is not visible | Exit the full-screen app or confirm that the Windows taskbar is visible. |
+| Widget starts twice | Re-run `install.ps1`; the single-instance mutex keeps only one runtime active. |
+| Build fails | Confirm that .NET Framework 4.8 and its C# compiler are available. |
+
+---
+
+## Distribution Notes
+
+`build.ps1` produces a single WinForms executable with no third-party runtime packages. `install.ps1` copies it to the local app-data directory, replaces older widget Startup shortcuts that target the same executable, and launches the installed copy.
+
+The `v1.0.0` GitHub release contains the same executable verified by the local build flow. The repository remains source-first: generated files under `dist/` are ignored by Git and published through releases or Actions artifacts instead.
+
+---
+
+## Runtime Contract
+
+Codex Usage Widget treats local rate-limit metadata as display telemetry, not user content.
+
+The runtime scans the tail of recent session files in memory, but parses only lines that match `event_msg` → `token_count` and contain `rate_limits`. All other event types are ignored; prompt and response payloads are not interpreted, retained, or transmitted. The widget does not access authentication files, clipboard data, screenshots, focused-app content, URLs, or browser history, and it makes no network requests.
+
+The current parser depends on Codex's local JSONL session shape rather than a public usage API. A future Codex format change may require an update to `UsageReader`.
+
+---
+
+## Reproduction Prompt
+
+The concise English build prompt is available in [PROMPT.md](PROMPT.md).
+
+---
+
+## Author
+
+**Jun Seok Kim**<br />
+GitHub: [@Everyseok](https://github.com/Everyseok)
+
+---
 
-See [PROMPT.md](PROMPT.md) for a short prompt that can reproduce this project.
+<p align="center">
+  <strong>Five hours. One week. One glance.</strong>
+</p>