Merge pull request #75 from Two-Weeks-Team/chore/cleanup-and-readme-rewrite

chore: remove toast code, delete planning docs, rewrite README

Author: ComBba

AGENTS.md

@@ -1,60 +1,86 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-02-21 21:18:51 UTC+09:00
-**Commit:** N/A (repository has no commits yet)
-**Branch:** master (unborn)
+**Updated:** 2026-02-25
+**Version:** 0.1.1 (npm published)
+**Branch:** master
 
 ## OVERVIEW
-Reference-only repository for OpenCode HUD architecture/planning. Contains analysis docs for OpenCode plugin surfaces, oh-my-opencode layering, and a phased universal HUD implementation plan.
+Real-time usage HUD plugin for OpenCode CLI. Shows provider API utilization, context tokens, cost, and agent info as a dim blockquote appended to assistant output.
 
 ## STRUCTURE
 ```text
 ./
-├── OPENCODE_ARCHITECTURE_ANALYSIS.md      # OpenCode internals, hook/event/output constraints
-├── OH_MY_OPENCODE_ARCHITECTURE_ANALYSIS.md # oh-my-opencode composition and reusable patterns
-├── OPENCODE_HUD_UNIVERSAL_PLAN.md          # original universal HUD plan (baseline)
-├── OPENCODE_HUD_UNIVERSAL_PLAN_VNEXT.md    # strengthened vNext plan with gates/controls
-└── OPENCODE_HUD_IMPLEMENTATION_ISSUES.md   # phase-grouped issue breakdown (task-level)
+├── src/
+│   ├── plugin.ts                    # Main plugin — hooks, usage line builder, output augmentation
+│   ├── index.ts                     # Default export
+│   ├── api.ts                       # Public API re-exports
+│   ├── config/index.ts              # HUD profiles and config types
+│   ├── model-registry.ts            # Model metadata, context limits, cost rates
+│   ├── cost-calculator.ts           # Per-message cost resolution
+│   ├── usage-aggregator.ts          # Rolling usage sample accumulator
+│   ├── disk-cache.ts                # Persistent cache for provider snapshots
+│   ├── polling-manager.ts           # Background API polling orchestrator
+│   ├── fetch-claude.ts              # Anthropic usage API client
+│   ├── fetch-openai.ts              # OpenAI Codex usage API client
+│   ├── fetch-utils.ts               # Shared HTTP utilities
+│   ├── auth-resolver.ts             # Anthropic credential auto-detection
+│   ├── auth-resolver-openai.ts      # OpenAI credential auto-detection
+│   ├── provider-usage.types.ts      # Provider usage snapshot types
+│   ├── runtime/
+│   │   ├── reducer.ts               # HUD state machine (tool transitions)
+│   │   ├── intake.ts                # Raw event parser
+│   │   ├── event-allowlist.ts       # Allowed event types
+│   │   ├── formatting.ts            # Display text sanitization
+│   │   ├── coexistence.ts           # Multi-channel dispatch (prompt + publisher)
+│   │   ├── prompt-fallback.ts       # Prompt channel with rate limiting
+│   │   ├── publisher.ts             # Optional snapshot publisher
+│   │   └── channels/
+│   │       ├── index.ts             # Channel exports
+│   │       └── prompt.ts            # Prompt message formatter
+│   └── cli/
+│       ├── index.ts                 # CLI entry point (install/uninstall)
+│       ├── config-manager.ts        # opencode.json config resolution
+│       ├── install-transaction.ts   # Atomic install operations
+│       ├── uninstall-transaction.ts # Atomic uninstall operations
+│       └── local-plugin-transaction.ts # Local plugin shim management
+├── tests/                           # vitest
+├── bin/opencode-status-hud.js       # CLI binary
+├── docs/guide/installation.md       # Installation guide (published to npm)
+├── docs/QUICKSTART.md               # Quick start reference
+├── docs/CONFIG_DEFAULTS.md          # Config defaults reference
+└── dist/                            # Built output (tsc)
 ```
 
 ## WHERE TO LOOK
 | Task | Location | Notes |
 |------|----------|-------|
-| Understand OpenCode plugin limits | `OPENCODE_ARCHITECTURE_ANALYSIS.md` | Evidence-backed limits: no core patching, hook/TUI boundaries |
-| Reuse composition/install patterns | `OH_MY_OPENCODE_ARCHITECTURE_ANALYSIS.md` | Bootstrap pipeline, hook tiering, installer idempotency |
-| Track baseline plan assumptions | `OPENCODE_HUD_UNIVERSAL_PLAN.md` | Scope, phased milestones, verification, rollout |
-| Execute strengthened implementation plan | `OPENCODE_HUD_UNIVERSAL_PLAN_VNEXT.md` | go/no-go gates, risk controls, verification strategy |
-| Register work as granular tasks/issues | `OPENCODE_HUD_IMPLEMENTATION_ISSUES.md` | phase-grouped atomic issue definitions and dependency order |
-
-## CODE MAP
-No local source code in this repository. All symbol/file references inside docs point to external repositories (`opencode/...`, `oh-my-opencode/...`).
+| HUD line format and output augmentation | `src/plugin.ts` | `buildAssistantUsageLine`, `appendUsageLineToOutputText` |
+| Provider API polling | `src/polling-manager.ts` | Creates per-provider pollers |
+| Anthropic usage fetch | `src/fetch-claude.ts` | Rate limit window parsing |
+| OpenAI Codex usage fetch | `src/fetch-openai.ts` | Codex API billing/usage |
+| Credential auto-detection | `src/auth-resolver.ts`, `src/auth-resolver-openai.ts` | Reads from env, config files |
+| Model metadata and context limits | `src/model-registry.ts` | Dynamic via chat.params hook |
+| Plugin install/uninstall CLI | `src/cli/` | Local shim or config-array mode |
+| State machine for tool transitions | `src/runtime/reducer.ts` | HudState, transitions |
+| Multi-channel dispatch | `src/runtime/coexistence.ts` | Prompt + publisher coordination |
 
 ## CONVENTIONS
-- This repo is documentation-first; keep additions evidence-based and concise.
-- Preserve explicit distinction between:
-  - OpenCode-native capabilities
-  - oh-my-opencode-specific behavior
-  - proposed universal HUD implementation details
-- Prefer stable, known event contracts and avoid undocumented assumptions.
+- Zero external env setup required — credentials auto-detected from existing provider configs
+- Output channel is primary: blockquote (`> usage line`) appended to assistant text
+- No ANSI escape codes in output text (stripped before blockquote wrapping)
+- All source uses strict TypeScript — no `as any`, no `@ts-ignore`
+- Tests use vitest, no mocking of external services (polling manager injectable)
 
 ## ANTI-PATTERNS (THIS PROJECT)
-- Do not require tmux for baseline HUD behavior (`OPENCODE_HUD_UNIVERSAL_PLAN.md`).
-- Do not modify OpenCode core (`OPENCODE_HUD_UNIVERSAL_PLAN.md`, `OPENCODE_ARCHITECTURE_ANALYSIS.md`).
-- Do not assume unknown web reducer events will render (`OPENCODE_ARCHITECTURE_ANALYSIS.md`).
-- Do not introduce hard dependency on `oh-my-opencode` (`OPENCODE_HUD_UNIVERSAL_PLAN.md`).
-
-## UNIQUE STYLES
-- Architecture docs are constraint-driven: each claim should tie back to concrete runtime/plugin surfaces.
-- Implementation guidance is phased and testable (success criteria per phase).
-- Keep practical "what to reuse / what not to inherit" framing when adding comparative analysis.
+- Do not modify OpenCode CLI core or oh-my-opencode
+- Do not require tmux for baseline HUD behavior
+- Do not use ANSI codes in output text (TUI renders markdown, not raw ANSI)
+- Do not suppress type errors with `as any` or `@ts-ignore`
 
 ## COMMANDS
 ```bash
-# This repository currently has no local build/test scripts.
-# Use standard documentation hygiene when editing:
-markdownlint "*.md"        # if markdownlint is available
+npm run typecheck    # tsc --noEmit
+npm run test         # vitest run
+npm run build        # tsc -p tsconfig.build.json
+npm run ci           # typecheck + test + build (prepublishOnly)
 ```
-
-## NOTES
-- There are no subdirectories at present; only root-level AGENTS.md is warranted.
-- If code or packages are later added, create nested AGENTS.md only for directories with distinct ownership, conventions, or high complexity.