diff --git a/docs/superpowers/plans/2026-05-25-popup-update-panel.md b/docs/superpowers/plans/2026-05-25-popup-update-panel.md
new file mode 100644
index 0000000..9f4fa8f
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-25-popup-update-panel.md
@@ -0,0 +1,179 @@
+# Popup Update Panel Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Redesign the extension popup into a compact enterprise-style tool panel with clearer grouping, better spacing, and more readable update actions while keeping existing behavior unchanged.
+
+**Architecture:** Keep the popup behavior in `src/popup/index.ts` and focus most UI changes in `src/popup/view.ts`. Add only the minimum structural changes needed to support grouped cards, clearer update states, and button hierarchy, then verify the existing popup tests still cover the update workflow.
+
+**Tech Stack:** TypeScript, Chrome MV3 popup UI, Vitest, jsdom
+
+---
+
+## File Map
+
+- Modify: `src/popup/view.ts`
+  - Replace the current long text flow with grouped cards and clearer status blocks.
+- Modify: `src/popup/index.html`
+  - Add popup-level CSS for layout, spacing, typography, and button hierarchy.
+- Modify: `src/popup/index.ts`
+  - Keep logic unchanged unless the new view structure needs small status-render support changes.
+- Modify: `tests/popup-entry.test.ts`
+  - Update popup rendering expectations for the redesigned layout.
+
+### Task 1: Lock the desired popup structure in tests
+
+**Files:**
+- Modify: `tests/popup-entry.test.ts`
+
+- [ ] **Step 1: Write the failing layout assertions**
+
+Update the logged-in and update-available popup tests to assert the new structure exists. Add checks for:
+
+- a compact product header
+- an account card/root section
+- an update card/root section
+- a primary update button and secondary guide button
+
+Use selectors that match the intended new DOM shape, for example:
+
+```ts
+expect(
+  dom.window.document.querySelector('[data-popup-account="card"]')
+).not.toBeNull();
+expect(
+  dom.window.document.querySelector('[data-popup-update="card"]')
+).not.toBeNull();
+```
+
+- [ ] **Step 2: Run the focused popup test**
+
+Run:
+
+```bash
+npm test -- tests/popup-entry.test.ts
+```
+
+Expected: FAIL because the current popup view does not expose the new grouped structure.
+
+### Task 2: Redesign the logged-in popup shell
+
+**Files:**
+- Modify: `src/popup/view.ts`
+- Modify: `src/popup/index.html`
+
+- [ ] **Step 1: Implement the grouped popup shell**
+
+Change the logged-in renderer so it produces:
+
+- a compact header
+- an account card
+- an update card container
+- a low-emphasis footer action area
+
+Keep the same text content, just reorganized.
+
+- [ ] **Step 2: Add popup CSS**
+
+Add scoped CSS in `src/popup/index.html` for:
+
+- wider popup body
+- neutral background
+- white cards
+- consistent spacing
+- smaller title scale
+- primary / secondary / tertiary button styles
+
+Do not add animation-heavy or branding-heavy styles.
+
+- [ ] **Step 3: Re-run popup tests**
+
+Run:
+
+```bash
+npm test -- tests/popup-entry.test.ts
+```
+
+Expected: PASS for structure-related checks, with any remaining failures isolated to update-state details.
+
+### Task 3: Redesign update-state rendering
+
+**Files:**
+- Modify: `src/popup/view.ts`
+- Modify: `src/popup/index.ts` (only if required)
+
+- [ ] **Step 1: Write or update state-specific assertions**
+
+Ensure tests cover:
+
+- `checking` state shows a compact progress line
+- `latest` state hides download actions
+- `available` state shows current version, latest version, notes, and action buttons
+- `error` state renders a readable warning block
+
+- [ ] **Step 2: Run the focused tests**
+
+Run:
+
+```bash
+npm test -- tests/popup-entry.test.ts
+```
+
+Expected: FAIL on any states not yet aligned to the new view.
+
+- [ ] **Step 3: Implement state-specific card rendering**
+
+Refactor `renderUpdateStatus()` to keep one card shell and swap state bodies inside it. Make the available-update state visually prominent but restrained.
+
+- [ ] **Step 4: Verify**
+
+Run:
+
+```bash
+npm test -- tests/popup-entry.test.ts tests/update-check.test.ts
+```
+
+Expected: PASS.
+
+### Task 4: Verify the popup still works end-to-end
+
+**Files:**
+- Modify: `src/popup/view.ts` if polish is needed
+- Modify: `src/popup/index.html` if polish is needed
+
+- [ ] **Step 1: Build the release popup**
+
+Run:
+
+```bash
+npm run build:release
+```
+
+Expected: PASS and updated popup assets written to `dist/`.
+
+- [ ] **Step 2: Run the full test suite**
+
+Run:
+
+```bash
+npm test
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Manual smoke check**
+
+Open the unpacked extension popup from `dist/` and confirm:
+
+- title no longer wraps into a giant stacked block
+- account status is easy to scan
+- update information reads clearly
+- buttons are visually distinct and not cramped
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/popup/view.ts src/popup/index.html src/popup/index.ts tests/popup-entry.test.ts
+git commit -m "feat: redesign popup update panel"
+```
+