diff --git a/docs/superpowers/specs/2026-08-09-reference-download-progress-indicator-design.md b/docs/superpowers/specs/2026-08-09-reference-download-progress-indicator-design.md
new file mode 100644
index 000000000..2dfc5c405
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-09-reference-download-progress-indicator-design.md
@@ -0,0 +1,102 @@
+# Reference Download Progress Indicator Design
+
+## Objective
+
+Make background reference-bundle downloads visible throughout execution so users can tell which species is being downloaded, how much data has arrived, whether the download completed, and why it failed.
+
+The indicator will appear beside “💡 使用小Tip” in the analysis input toolbar. This change is presentation-only: it must not alter PPI, KaKs, Ortholog, planning, download selection, fallback decisions, or backend execution.
+
+## Current Problem
+
+The frontend already polls `/api/task/{task_id}` and stores download state in `referenceBundleDownloadState`. A progress block also exists, but it is rendered inside the batch-execution confirmation dialog. `startBatchExecute()` closes that dialog before execution begins, so the user cannot see the progress block during the actual background download.
+
+The task API already supplies useful runtime information, including:
+
+- species label;
+- task status and message;
+- percentage when the upstream source provides a total size;
+- `bytes_downloaded` and `total_bytes`;
+- terminal success or failure and the failure reason.
+
+The missing piece is a visible consumer of that existing state.
+
+## Chosen Design
+
+### Placement and interaction
+
+Add a compact “⬇️ 下载进度” status item immediately beside “💡 使用小Tip”. It is hidden when no reference download has been observed in the current page lifecycle.
+
+While visible, its label reflects the current state:
+
+- running: `⬇️ 下载中 8.0 MB`;
+- success: `✅ 下载完成`;
+- failed: `❌ 下载失败`.
+
+Hovering over the item opens a compact detail panel using the existing Tip/Upload hover-panel visual pattern. The panel shows:
+
+- reference species;
+- running/success/failed status;
+- determinate progress when total size is known;
+- indeterminate progress plus downloaded MB when total size is unknown;
+- backend progress or terminal error message;
+- a close action for terminal states.
+
+The running state cannot be dismissed accidentally. Success and failure remain visible until the user closes them. Starting a new download replaces the previous terminal state and shows the new task immediately.
+
+### State handling
+
+Reuse `referenceBundleDownloadState`; do not introduce a second download-state authority.
+
+Extend the state with only the display fields required by the indicator:
+
+- `bytesDownloaded`;
+- `totalBytes`.
+
+`updateReferenceBundleDownloadProgress()` will read these values from the existing task progress payload. If `totalBytes` is unavailable or zero, the progress bar remains indeterminate and the UI reports the downloaded byte count instead of inventing a percentage.
+
+On success, update the existing state to a visible `success` terminal state at 100% rather than immediately clearing it. On failure, retain the visible `failed` state and its exact error message. `clearReferenceBundleDownloadProgress()` remains the single close/reset operation.
+
+### Scope boundary
+
+Only `apps/web/vue3/index.html` is expected to change:
+
+- toolbar markup beside “使用小Tip”;
+- narrowly scoped styles matching existing hover components;
+- the existing `referenceBundleDownloadState` shape and progress updater;
+- success-state retention in the existing monitor path;
+- a small byte-formatting display helper if no equivalent helper already exists.
+
+Explicitly out of scope:
+
+- backend API changes;
+- download retry/resume implementation;
+- fallback-to-At behavior;
+- PPI, KaKs, or Ortholog execution and dependencies;
+- planning or stage identity;
+- cross-refresh persistence;
+- unrelated frontend refactoring.
+
+## Error and Terminal-State Behavior
+
+- Network/download failure: show a red terminal state, downloaded size, and the backend error text.
+- Unknown content length: show an indeterminate bar and downloaded MB; do not display a fabricated percentage.
+- Successful completion: show a green 100% state and completion message until closed.
+- Subsequent download: replace the old terminal state with the new running task.
+
+The indicator reports state only. Existing confirmation dialogs remain responsible for retry, skip, reference choice, and At fallback decisions.
+
+## Verification
+
+Add focused frontend-source/Node tests that exercise the real state-update logic rather than mocking it away.
+
+Acceptance checks:
+
+1. A running task with unknown total bytes renders a visible indeterminate state and downloaded MB.
+2. A running task with known total bytes renders the backend percentage.
+3. Success remains visible and shows the terminal completion state until close.
+4. Failure remains visible and shows the exact failure reason until close.
+5. Close clears a terminal state; a subsequent progress event makes the indicator visible again.
+6. Existing PPI/KaKs scheduling and download-failure tests continue to pass.
+7. The rendered indicator sits beside “使用小Tip”, outside the batch confirmation dialog.
+
+Validation will use the current real job/task payload as a fixture shape, including the observed `IncompleteRead` failure and unknown `total_bytes=0`. No PPI, KaKs, or Ortholog analysis rerun is required to validate this presentation-only change.