docs: add COS update design spec

docs/superpowers/specs/2026-05-25-cos-extension-update-design.md

@@ -0,0 +1,84 @@
+# COS Extension Update Design
+
+## Goal
+
+Use COS as the release source for extension updates. When the popup opens, it checks a public `latest.json` on COS. If the COS version is newer than the installed extension version, the popup shows an update card with download actions for the ZIP and the PDF guide, plus manual reload instructions.
+
+## Confirmed Scope
+
+- Update prompt appears only in the extension popup.
+- No star chart page banner in this change.
+- The user keeps the current manual install flow: download, unzip, replace the folder, then reload in `chrome://extensions`.
+
+## Reusable Implementation
+
+The current repo already has most of the flow:
+
+- `src/shared/update-check.ts` parses the manifest and compares versions.
+- `src/popup/index.ts` checks for updates when the popup boots.
+- `src/popup/view.ts` renders the update status and download actions.
+- `src/background/index.ts` downloads the ZIP/PDF through `chrome.downloads`.
+- `scripts/write-latest-manifest.mjs` generates `release/latest.json`.
+
+This change is mostly activation and configuration, not a rewrite.
+
+## Manifest Contract
+
+The public COS manifest must keep these fields:
+
+- `latestVersion`
+- `minSupportedVersion`
+- `publishedAt`
+- `releaseNotes`
+- `zipUrl`
+- `guideUrl`
+
+Rules:
+
+- All asset URLs must be public HTTPS URLs.
+- Version comparison stays numeric dotted comparison.
+- Popup logic only needs `latestVersion` to decide whether to show the update card.
+- `minSupportedVersion` stays in the manifest for forward compatibility.
+
+## COS Layout
+
+Use a fixed release layout like:
+
+- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/latest.json`
+- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/star-chart-search-enhancer-internal.zip`
+- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/星图增强插件-超简单安装使用指南.pdf`
+
+## User Flow
+
+1. User opens the popup.
+2. Popup reads the current extension version.
+3. Popup fetches COS `latest.json` with `no-store`.
+4. If `latestVersion` is not newer, show “当前已是最新版本”.
+5. If `latestVersion` is newer, show “发现新版本” plus release notes.
+6. User clicks:
+   - `下载更新包` for the ZIP
+   - `下载使用说明` for the PDF
+7. Popup shows the manual upgrade instructions after download starts.
+
+## Error Handling
+
+- If the manifest is missing, invalid, or unreachable, the popup should show a non-blocking update error.
+- If download fails, the popup should show a download error and keep the plugin usable.
+- Update check failures must not block auth or normal plugin behavior.
+
+## Release Process
+
+1. Build the release package.
+2. Package the internal ZIP.
+3. Generate `latest.json` with the real COS base URL.
+4. Upload `latest.json`, the ZIP, and the PDF to the COS folder.
+5. Replace the placeholder manifest URL in `src/shared/update-config.ts`.
+6. Rebuild and verify the popup update card.
+
+## Out of Scope
+
+- Automatic in-place extension updates.
+- Auto-reload after download.
+- Star chart page update prompts.
+- Chrome Web Store publishing.
+