+
+---
+
+## 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**
+GitHub: [@Everyseok](https://github.com/Everyseok)
+
+---
-See [PROMPT.md](PROMPT.md) for a short prompt that can reproduce this project.
+
+ Five hours. One week. One glance.
+
diff --git a/docs/assets/readme/taskbar-preview.svg b/docs/assets/readme/taskbar-preview.svg
new file mode 100644
index 0000000..f3415de
--- /dev/null
+++ b/docs/assets/readme/taskbar-preview.svg
@@ -0,0 +1,56 @@
+
diff --git a/docs/assets/readme/widget-hero.svg b/docs/assets/readme/widget-hero.svg
new file mode 100644
index 0000000..5088e9d
--- /dev/null
+++ b/docs/assets/readme/widget-hero.svg
@@ -0,0 +1,79 @@
+
+
+
+ 
+ 
+ 
+ 
+ 
+