docs(superpowers): add implementation plans and specs

Author: pallyoung

docs/superpowers/plans/2026-05-11-supervisor-execution-policy.md

@@ -0,0 +1,180 @@
+# Mobile Terminal Paste/Upload 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:** Add two mobile terminal actions: paste from clipboard and upload files/images from the device picker.
+
+**Architecture:** Keep the existing terminal upload pipeline in `use-paste-drop-upload`, but extend it with explicit entry points for clipboard reads and file picker uploads. `MobileTerminalInputBar` owns the visible buttons and emits user intent; `XtermHost` wires those intents to workspace-scoped upload helpers and disables the controls while uploads are in flight. Desktop terminal behavior stays unchanged.
+
+**Tech Stack:** React, TypeScript, Jotai, browser Clipboard API, browser file input, Vitest, Testing Library.
+
+---
+
+### Task 1: Add mobile toolbar actions and wiring hooks
+
+**Files:**
+- Modify: `packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.tsx`
+- Modify: `packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx`
+- Test: `packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Add assertions that the mobile input bar renders two new buttons labeled `Paste` and `Upload`, and that clicking them invokes dedicated callbacks instead of terminal key handlers.
+
+```tsx
+it("renders paste and upload actions and dispatches their callbacks", () => {
+  const onPaste = vi.fn();
+  const onUpload = vi.fn();
+
+  render(
+    <MobileTerminalInputBar
+      ctrlMode="off"
+      shiftArmed={false}
+      labels={labels}
+      onKeyPress={vi.fn()}
+      onCtrlTap={vi.fn()}
+      onCtrlLongPress={vi.fn()}
+      onShiftTap={vi.fn()}
+      onPaste={onPaste}
+      onUpload={onUpload}
+    />
+  );
+
+  fireEvent.click(screen.getByRole("button", { name: "Paste" }));
+  fireEvent.click(screen.getByRole("button", { name: "Upload" }));
+
+  expect(onPaste).toHaveBeenCalledTimes(1);
+  expect(onUpload).toHaveBeenCalledTimes(1);
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `pnpm vitest packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx -t "renders paste and upload actions and dispatches their callbacks" -v`
+
+Expected: fail because the props and buttons do not exist yet.
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Add `onPaste` and `onUpload` props to `MobileTerminalInputBar`, render two leading action buttons in the mobile bar, and forward clicks to the callbacks. In `xterm-host.tsx`, pass handlers that will be implemented in the next task.
+
+```tsx
+interface MobileTerminalInputBarProps {
+  // existing props...
+  onPaste: () => void;
+  onUpload: () => void;
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `pnpm vitest packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx -v`
+
+Expected: pass, with the new buttons appearing before the terminal key group.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.tsx packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx
+git commit -m "feat: add mobile terminal paste and upload actions"
+```
+
+### Task 2: Implement clipboard paste and file-picker upload flows
+
+**Files:**
+- Modify: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts`
+- Modify: `packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx`
+- Test: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx`
+- Test: `packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Add coverage for two new helpers:
+- a clipboard path that reads `ClipboardItem`s or text and uploads image files when present
+- a file-picker path that uploads selected files and then writes the quoted terminal command back into the PTY
+
+```ts
+it("uploads clipboard image files when paste is requested", async () => {
+  // mock navigator.clipboard.read() to return an image ClipboardItem
+  // assert uploadFiles receives a File and sendTextToTerminal gets the quoted path
+});
+
+it("uploads files selected from the picker when upload is requested", async () => {
+  // mock an <input type=\"file\"> selection and assert the same upload path is used
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run:
+`pnpm vitest packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx -v`
+
+Expected: fail because the new public helpers and host wiring do not exist yet.
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Extend `use-paste-drop-upload` with explicit methods for:
+- reading clipboard files/text from a user gesture
+- uploading an arbitrary `File[]`
+
+Keep the existing paste/drop DOM listeners intact for desktop and non-mobile surfaces. In `xterm-host.tsx`, wire the new mobile buttons to the new helpers and add a hidden file input or equivalent picker flow scoped to mobile only.
+
+```ts
+// shape only; keep existing uploadFiles/quoteShellSingle flow
+type UploadSource = "clipboard" | "picker";
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run:
+`pnpm vitest packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx -v`
+
+Expected: pass, with clipboard and picker uploads both producing quoted terminal insertions and error toasts on failure.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx
+git commit -m "feat: wire mobile terminal clipboard and file upload"
+```
+
+### Task 3: Add labels, polish layout, and verify mobile behavior
+
+**Files:**
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Modify: `packages/web/src/styles/components.css`
+- Test: `packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Extend the mobile input bar test to assert the new action buttons are present, readable, and do not collapse the existing terminal key order on narrow layouts.
+
+```ts
+expect(screen.getByRole("button", { name: "Paste" })).toBeInTheDocument();
+expect(screen.getByRole("button", { name: "Upload" })).toBeInTheDocument();
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `pnpm vitest packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx -v`
+
+Expected: fail until the labels and layout styles are added.
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Add localized labels for the two actions in `en.json` and `zh.json`, then update `components.css` so the two action buttons read as a separate group from the terminal keys without shrinking the existing soft-key row.
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `pnpm vitest packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx -v`
+
+Expected: pass, and the mobile bar should still fit on small screens with horizontal scrolling for the terminal keys.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/locales/en.json packages/web/src/locales/zh.json packages/web/src/styles/components.css packages/web/src/features/terminal-panel/mobile/mobile-terminal-input-bar.test.tsx
+git commit -m "feat: polish mobile terminal paste and upload actions"
+```
+

docs/superpowers/plans/2026-05-12-supervisor-target-scoped-memory-implementation.md

@@ -0,0 +1,134 @@
+# README Top Structure 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:** Restructure the top of both README files for faster product comprehension on GitHub and add a README-friendly animated demo preview.
+
+**Architecture:** Keep the existing repository sections after quick start, but replace the top section with a tighter landing-style structure. Use a lightweight animated GIF as the inline preview in README and keep the existing `mp4` as the full demo target.
+
+**Tech Stack:** Markdown, ffmpeg, existing demo assets in `docs/assets`
+
+---
+
+### Task 1: Create README-Friendly Demo Preview Asset
+
+**Files:**
+- Create: `docs/assets/demo-preview.gif`
+- Modify: `docs/assets/demo.mp4` (no changes expected)
+- Modify: `docs/assets/demo-poster.png` (no changes expected)
+
+- [ ] **Step 1: Generate a compact animated GIF from the recorded MP4**
+
+Run:
+
+```bash
+ffmpeg -y -i docs/assets/demo.mp4 -vf "fps=8,scale=960:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=3" -loop 0 docs/assets/demo-preview.gif
+```
+
+Expected: `docs/assets/demo-preview.gif` is created successfully.
+
+- [ ] **Step 2: Verify the GIF asset exists and is a reasonable size**
+
+Run:
+
+```bash
+ls -lh docs/assets/demo-preview.gif docs/assets/demo.mp4 docs/assets/demo-poster.png
+```
+
+Expected: the GIF exists and remains small enough for repository use.
+
+- [ ] **Step 3: Keep the MP4 as the full demo target**
+
+No file edit required. The README will use the GIF as inline preview and link through to `docs/assets/demo.mp4`.
+
+### Task 2: Refactor README.md Top Section
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Replace the current top block with the approved landing-style structure**
+
+Edit the top portion of `README.md` so it contains:
+
+- logo and title
+- sharper one-line positioning statement
+- supporting paragraph
+- reduced badge set
+- CTA row with `Watch Demo`, `Quick Start`, `Star on GitHub`
+- language/docs links
+- inline GIF preview linked to `docs/assets/demo.mp4`
+- one-line demo framing copy
+- `Why It Feels Different`
+- quick start moved up
+
+- [ ] **Step 2: Remove or move down top-of-page content that competes with the demo**
+
+Specifically remove from the top block:
+
+- blockquote slogan
+- top six-item feature list
+- top static workspace overview screenshot
+- discussions / issues / contributors badges from the first visual block
+
+- [ ] **Step 3: Keep lower repository sections unchanged unless needed for heading continuity**
+
+Preserve existing sections below quick start, including use cases, screenshots, feature overview, docs, roadmap, contributing, and license.
+
+### Task 3: Refactor README.zh-CN.md Top Section
+
+**Files:**
+- Modify: `README.zh-CN.md`
+
+- [ ] **Step 1: Mirror the English information architecture in Chinese**
+
+Edit the top portion of `README.zh-CN.md` so it matches the same structure and CTA order as `README.md`.
+
+- [ ] **Step 2: Use Chinese copy that preserves the same product claims**
+
+The Chinese version should clearly communicate:
+
+- browser-based AI coding workspace
+- cross-device continuity
+- Claude Code and Codex in one workspace
+- demo first, star second
+
+- [ ] **Step 3: Keep lower sections intact**
+
+Do not redesign the rest of the Chinese README in this pass.
+
+### Task 4: Verify README Rendering Inputs
+
+**Files:**
+- Modify: `README.md`
+- Modify: `README.zh-CN.md`
+- Create: `docs/assets/demo-preview.gif`
+
+- [ ] **Step 1: Verify README media references**
+
+Run:
+
+```bash
+rg -n "demo-preview\\.gif|demo\\.mp4|demo-poster\\.png|Quick Start|快速开始" README.md README.zh-CN.md
+```
+
+Expected: both README files reference the new GIF preview and the MP4 target consistently.
+
+- [ ] **Step 2: Inspect the diff for only intended files**
+
+Run:
+
+```bash
+git diff -- README.md README.zh-CN.md docs/assets/demo-preview.gif
+```
+
+Expected: only the approved top-structure and preview changes appear.
+
+- [ ] **Step 3: Verify repository status remains scoped**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected: only intended README/media/spec/plan changes are new in this task; unrelated untracked files remain untouched.