CLAUDE.md

@@ -57,6 +57,16 @@ Bromite userscript (isolated world, per-site adapters, localStorage cache)
   value now differs, moving `updated_at` and reordering the list. This is a
   known, accepted limitation for a single-user deployment, not a bug to fix.
 - **`updated_at` drives list order, so it moves only on real reading progress:** the server applies its timestamp when the row is new or `last_chapter_num` changes, and otherwise keeps the stored value — favouriting a series or recording a newly published chapter must not reorder the list. `PUT` therefore returns the row **as stored**, and clients must adopt that response rather than their own payload. See `plans/2026-07-25-bookmark-list-favorites-design.md` §4.
+- **Lifecycle buckets:** `status` on each bookmark is `reading` | `archived` |
+  `finished`, orthogonal to `favorite`. Archived and finished appear only in
+  their own tab — not in All, Updated, Favourites, or the recent strip. The
+  poller keeps checking archived series and skips finished ones. `finished` is
+  settable only from the web UI; `PUT /bookmarks/{key}` rejects it with 400.
+  **An empty incoming status means "keep the stored one"** — resolved on the
+  `VALUES` side of `Store.Upsert`, not in the conflict clause, because
+  `excluded.*` is the post-evaluation row and a default applied there would
+  wipe the bucket on every PUT from a client that predates the column. See
+  `docs/superpowers/specs/2026-07-27-status-buckets-design.md`.
 - **Config via env:** `API_TOKEN`, `ALLOWED_ORIGINS` (comma list), `DB_PATH`
   (default `/data/bookmarks.db`), `PORT` (default `8080`), `WEB_PASSWORD`
   (gates the browser UI; unset disables it),
@@ -68,7 +78,10 @@ Bromite userscript (isolated world, per-site adapters, localStorage cache)
 1. **Site adapters** — one per host, `detect(location, document)` returns page `type` + IDs. Identify type/IDs from **URL regex** (most stable); pull `title`/`cover` from **`og:title`/`og:image` meta tags**, not CSS classes.
 2. **API client** — `apiGet/apiPut/apiDelete` with bearer header; `localStorage` key `mangabm:cache` for instant render + offline fallback.
 3. **Progress logic** — auto-upsert `last_chapter` only when `chapterNum >= stored last_chapter_num` (re-reading old chapters must not regress progress; unparseable -> set current). Manual panel override forces any value.
-4. **UI** — rendered inside a **Shadow DOM** root to isolate from site CSS (critical on mobile).
+4. **UI** — rendered inside a **Shadow DOM** root to isolate from site CSS
+   (critical on mobile). Three tabs (All / Favourites / Archived) and a row of
+   link chips to the web UI and both manga sites; `WEB_BASE` sits in the CONFIG
+   block next to `API_BASE`.
 5. **SPA navigation** — Asura is Astro, client-routed on the comic/chapter pages: patch `history.pushState`/`replaceState` + listen `popstate`, re-run `detect()` on URL change so auto-update fires without reload. Demonic uses classic reloads (initial `document-idle` run suffices).
 
 ### Live URL shapes (verified 2026-07-26, may drift — re-check against live pages before trusting)

README.md

@@ -148,6 +148,15 @@ desktop for faster testing — install the same file unchanged.
 - **Favourites**: the ☆ on any row toggles it; the **★ Favourites** tab narrows
   the list. Favourited series still appear under **All**. The flag syncs, so it
   follows you across devices; the chosen tab does not persist.
+- **Archive**: the **Archive** button on any row parks a series — it drops out
+  of **All** and **★ Favourites** and moves to the **Archived** tab. The server
+  keeps checking it for new chapters, so it is worth coming back to. Archiving
+  does not touch read progress, and reading an archived series leaves it
+  archived.
+- **Finished**: series you have completed live in a **Finished** tab in the web
+  UI only. It is set there and nowhere else — the API rejects the value — and
+  finished series are hidden from every userscript tab and are no longer polled
+  for new chapters.
 - Bookmarks made on Asura appear when the panel is opened on Demonic, and vice
   versa — the backend is the shared store.