# AGENTS.md

## Project

`opencode-greenpt-usage` — an OpenCode **TUI** plugin (Solid + OpenTUI) that
shows the remaining GreenPT API credit balance in the sidebar. Distributed by
`git clone`; there is no npm publish.

## Commands

```bash
npm install              # install dev dependencies
npm test                 # unit tests (vitest)
npm run typecheck        # tsc --noEmit
GREENPT_API_KEY=... npm run test:integration   # live API test
```

## Conventions

- The plugin entry is the `default export { id, tui }` in `src/index.tsx`.
  Types come from `@opencode-ai/plugin/tui` as **type-only** imports; the
  host provides `solid-js` and `@opentui/solid` at runtime.
- The section is registered on the `sidebar_content` slot and is hidden when
  no GreenPT credential is present (`showWhenUnavailable` opts into a hint).
- Balance probing must stay **free**: `HEAD /v1/chat/completions` returns
  `400` plus `x-credits-remaining`. Never replace it with a billable call.
- Credential resolution order: `apiKey` option, `GREENPT_API_KEY`, active
  OpenCode `auth.json` (`greenpt`, `type: "api"`). No profile-switching
  command may leak into this logic.
- No code comments unless functionally required.