ericjypark · ericjypark · May 11, 2026
diff --git a/.github/ISSUE_TEMPLATE/api_regression.yml b/.github/ISSUE_TEMPLATE/api_regression.yml
@@ -0,0 +1,54 @@
+name: Upstream API regression
+description: Claude `/api/oauth/usage` or Codex `/wham/usage` started returning unexpected fields, errors, or shape changes.
+title: "fix(usage): <endpoint> returning <symptom>"
+labels: ["bug", "upstream-api"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Both upstream endpoints are undocumented and change without notice. This template captures what's needed to update the parser.
+
+        **Redact your bearer token before posting any `curl` output.**
+
+  - type: dropdown
+    id: endpoint
+    attributes:
+      label: Which endpoint?
+      options:
+        - Claude — `/api/oauth/usage`
+        - Codex — `/wham/usage`
+        - Claude OAuth refresh — `platform.claude.com/v1/oauth/token`
+    validations:
+      required: true
+
+  - type: input
+    id: app-version
+    attributes:
+      label: CodexIsland version
+      placeholder: "0.0.42"
+    validations:
+      required: true
+
+  - type: textarea
+    id: symptom
+    attributes:
+      label: What does the chip show now?
+      placeholder: "HTTP 403 / `auth required` / wrong percentage / missing plan badge"
+    validations:
+      required: true
+
+  - type: textarea
+    id: curl
+    attributes:
+      label: Raw response
+      description: |
+        Paste the JSON body of the actual API response (token redacted). For Claude, include the request headers you used — the endpoint gates on `User-Agent: claude-code/X.Y.Z` and the `oauth-2025-04-20` beta header.
+      render: json
+    validations:
+      required: true
+
+  - type: textarea
+    id: when
+    attributes:
+      label: When did it start?
+      description: Approximate date/time. If a model change or Anthropic announcement preceded it, link it.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,117 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly.
+title: "bug: <short summary>"
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. The more of the fields below you fill in, the faster this gets fixed.
+
+        Before filing: please search [existing issues](https://github.com/ericjypark/codex-island/issues?q=is%3Aissue) to avoid duplicates.
+
+  - type: input
+    id: app-version
+    attributes:
+      label: CodexIsland version
+      description: Click the menu bar chip → About, or run `defaults read dev.codexisland.CodexIsland CFBundleShortVersionString`.
+      placeholder: "0.0.42"
+    validations:
+      required: true
+
+  - type: input
+    id: macos-version
+    attributes:
+      label: macOS version
+      description: Output of `sw_vers -productVersion`. Include chip (Apple Silicon / Intel) if you know it.
+      placeholder: "14.5 (Apple Silicon)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: How did you install?
+      options:
+        - Homebrew cask (`brew install --cask ericjypark/tap/codexisland`)
+        - DMG download from Releases
+        - Built from source (`./build.sh`)
+        - Auto-updated from a previous version
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: One or two sentences. What you were doing and what went wrong.
+      placeholder: "Opened settings → toggled X → the chip showed `HTTP 403` instead of token usage."
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: Numbered steps. If it's intermittent, say how often it happens.
+      placeholder: |
+        1. Launch the app
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which part of the app?
+      multiple: true
+      options:
+        - Window placement / notch detection
+        - Settings panel
+        - Claude usage chip
+        - Codex usage chip
+        - Auto-update (Sparkle)
+        - SparkChart / history
+        - Launch at login
+        - Build / install
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: usage-state
+    attributes:
+      label: Was usage data populated before the bug?
+      description: |
+        If this is a usage-chip bug — was the chip showing real numbers before? `auth required` or `HTTP 4xx` errors usually mean upstream creds are missing/expired, not an app bug. Try `claude /login` (or re-login to Codex) before filing.
+      placeholder: "Claude was showing 47% before; suddenly flipped to HTTP 403 after the app updated to 0.0.42."
+
+  - type: textarea
+    id: defaults
+    attributes:
+      label: Settings dump (optional, for settings/UI bugs)
+      description: Output of `defaults read dev.codexisland.CodexIsland`. Redact anything sensitive.
+      render: shell
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Console logs (optional)
+      description: |
+        Open Console.app → search "CodexIsland" → copy any errors from the timeframe of the bug. For Sparkle update bugs, also include `Sparkle` lines.
+      render: shell
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Screenshots, recordings, related issues, theories.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/ericjypark/codex-island/discussions
+    about: Open-ended questions, ideas, or "is this expected?" — start a discussion instead of an issue.
+  - name: Security disclosure
+    url: https://github.com/ericjypark/codex-island/security/advisories/new
+    about: Report a vulnerability privately. Do NOT open a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,55 @@
+name: Feature request
+description: Suggest a new capability or a change to existing behavior.
+title: "feat: <short summary>"
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing: search [existing issues](https://github.com/ericjypark/codex-island/issues?q=is%3Aissue) and the [Things that need work](https://github.com/ericjypark/codex-island/blob/main/CONTRIBUTING.md#things-that-need-work) list — your idea might already be tracked.
+
+        For open-ended "what if" ideas, a [Discussion](https://github.com/ericjypark/codex-island/discussions) is a better starting point than an issue.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the user-facing pain. Skip the proposed solution for now — focus on the symptom.
+      placeholder: "I have two notched displays and only one shows the panel, so I can't see usage when I'm working on the other monitor."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like the app to do? UI sketches, mock chip text, or rough behavior is fine.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about and why you rejected them. Keeps the discussion focused.
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Rough scope
+      description: Best guess — maintainer will adjust.
+      options:
+        - Small (a setting, a label, a one-file change)
+        - Medium (a new view or a refactor inside one subsystem)
+        - Large (touches build, Sparkle, or multiple subsystems)
+        - Not sure
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: willing
+    attributes:
+      label: Are you willing to help?
+      options:
+        - label: I can help test a build
+        - label: I can open a PR for this
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,60 @@
+<!--
+Title: lowercase Conventional Commits — `feat(scope): summary`, `fix(scope): summary`, `chore: summary`.
+No `Co-Authored-By` lines. No AI vocab (comprehensive, delve, crucial, robust, seamless).
+-->
+
+## What changed
+
+<!-- One or two sentences. The diff is the "what" — focus on the "why". -->
+
+## Why
+
+<!-- The user-facing problem or constraint. Link the issue: `Closes #123`. -->
+
+## How to verify
+
+<!-- Concrete steps a reviewer can run. Without this, the PR can't be reviewed.
+     Example:
+     1. `./build.sh && open build/CodexIsland.app`
+     2. Open Settings → toggle X
+     3. Confirm the chip updates within 5s and shows the new label
+-->
+
+1.
+2.
+3.
+
+## Screenshots / recording
+
+<!-- REQUIRED for any UI change (window placement, settings panel, chip layout, colors).
+     Drag a PNG or short .mov in. -->
+
+## Risk + blast radius
+
+<!-- What could this break? Where should the reviewer look hardest?
+     Examples:
+     - Touches notch detection — needs verification on a non-notched display.
+     - Changes refresh polling — verify we still respect 5m floor (Anthropic rate limits).
+     - Touches Sparkle wiring — see release checklist below. -->
+
+## Release impact
+
+- [ ] No version bump needed (code/doc change with no shipped behavior difference)
+- [ ] Bumps `VERSION` (will trigger a Sparkle auto-update for every install on next CI run)
+- [ ] Touches `build.sh`, `release.sh`, `scripts/setup-sparkle.sh`, or `.github/workflows/release.yml`
+
+## Pre-flight checklist
+
+- [ ] `./scripts/verify.sh` passes locally (builds + smoke-launches)
+- [ ] Manually launched `./build/CodexIsland.app` and exercised the changed code path
+- [ ] Commits follow lowercase Conventional Commits; no `Co-Authored-By` lines
+- [ ] No banned vocab (comprehensive, delve, crucial, robust, seamless) in commits, comments, or docs
+- [ ] No new comments added unless the *why* is non-obvious
+- [ ] No files added under `Vendor/` (gitignored on purpose)
+- [ ] Did **not** hand-edit `Casks/codexisland.rb` version/SHA, or any appcast XML
+
+### Sparkle / release-only PRs (skip if N/A)
+
+- [ ] `VERSION` is monotonic semver (e.g. `0.0.43`, never `1` or `100`)
+- [ ] `SU_PUBLIC_KEY` in `build.sh` is **unchanged** (changing it bricks auto-update for every existing install — see CLAUDE.md hard rule #2)
+- [ ] If bumping `VERSION`, also bumped it in [`ericjypark/codex-island-landing`](https://github.com/ericjypark/codex-island-landing) so the marketing site doesn't lag