# Decisions Append-only. Never edit or delete an entry — supersede it with a new one that links back. One entry per decision a future maintainer would otherwise have to reverse-engineer. No index: `grep -n '^## ' docs/DECISIONS.md` lists every entry (date, title, line number). ## 2026-10-14 — Adopt AGENTS.md as single source of truth **Status:** accepted **Context:** Agents had no durable project context and no consistent workflow between sessions. The design context lived in `HANDOVER.md`, which is now split into this file, the spec and `docs/TODO.md`. **Decision:** `AGENTS.md` is canonical; `CLAUDE.md`/`GEMINI.md` are pointers. Specs are permanent in `docs/specs/`. Plans live in `docs/plans/` only while work is in progress and are removed before the merge request. Both override the superpowers default paths. **Alternatives:** Per-tool rule files (drift, synchronisation debt); no rules file (agents re-explore the repo every session — measurably slower and more tokens). **Consequences:** Rule changes happen in one file; pointer files must stay thin. Plans are working artefacts: kept after merge they go stale and contradict the code, so the spec is the record. ## 2026-10-14 — Spec signed off; self-hosted only; password gate deferred **Status:** accepted (narrows the entry below) **Context:** The user signed off spec 001 and said the app will run self-hosted, and that password-gating should wait: "if it gets abused or we see too big amounts of traffic, we will deal with it then." **Decision:** First version runs `server/app.ts` under `Bun.serve` on our own machine behind our reverse proxy. No gate, no Cloudflare entry; both stay designed in the spec (§4.10, §4.11) and are listed under Someday in `docs/TODO.md`. The handler stays web-standard so either can be added later. **Alternatives:** Build the gate now (cost without a demonstrated need). **Consequences:** The site is open: the host allowlist, the 20 MB cap and the per-IP rate limit are the only protections. The rate limit needs the real client IP from our reverse proxy (`MBSEED_TRUST_PROXY`). ## 2026-10-14 — Also support catbox/litterbox; optional password gate; self-hostable server **Status:** accepted (extends the two entries below) **Context:** The user asked for catbox/litterbox support as well, and for a way to password-gate the static site "such that we could lock the service behind our own server". **Decision:** Image hosts are `server` (our storage, 30 days, default when configured), `litterbox` (≤ 72h; uploaded straight from the browser, which works because litterbox sends CORS headers), `catbox` (permanent; through our server for the page, direct for the userscript) and `direct`. The server is one web-standard `fetch` handler with two thin entries: Cloudflare Workers (R2 binding) and `Bun.serve` (S3-compatible bucket) for our own machine. An optional shared password (`MBSEED_PASSWORD`) gates every route, static assets included, with an HMAC-signed session cookie, plus `Authorization: Bearer` for the userscript. Self-hosted instances may use the reverse proxy's auth instead. "Behind our own server" was read as covering both the built-in gate and self-hosting. **Alternatives:** Cloudflare Access in front of the Worker (free for small teams, but Cloudflare-only and no help when self-hosting); per-user accounts (not needed for a small group); Basic auth (can't log out, and the browser prompt is clumsy for the userscript). **Consequences:** On Workers, assets must run through the Worker (`run_worker_first`) or the gate leaks the page. The userscript works without any server when using litterbox or catbox. Litterbox links may die before a slow review; the UI warns about it. ## 2026-10-14 — Temporary image hosting: Cloudflare R2 with a 30-day expiry **Status:** accepted (supersedes "Rehosting on catbox.moe" below) **Context:** A static page can't upload to catbox.moe (no CORS). The user said temporary hosting is fine with an expiry of at most a month: if moderators take longer, the user reruns. **Decision:** The Worker rehosts into R2 at `covers/.`, with a bucket lifecycle rule deleting objects after 30 days. `direct` (no rehost) stays as an option. **Alternatives:** litterbox (CORS works, but 72h maximum — likely shorter than a review); 0x0.st (CORS and MangaBaka acceptance unverified); catbox (no CORS, permanent). **Consequences:** Needs a Cloudflare account with a card on file (R2). Expected cost is $0 on free tiers; abuse of the Worker is the cost risk, hence the allowlist and the per-IP rate limit. ## 2026-10-14 — Static page + Cloudflare Worker, and a userscript; Bun; links given directly **Status:** accepted (supersedes "Stack: TypeScript / Node CLI" and "Automatic series matching" below) **Context:** The user wants a static web page first, with the CLI as secondary, Bun instead of Node, and to pass both the MangaBaka and Webtoons links. Checked 2026-10-14: `api.mangabaka.org` sends `access-control-allow-origin: *` (submissions too); Webtoons HTML, pstatic images and Wayback do not. **Decision:** One pure core with an injected `Transport`. The page uses a Worker proxy (allowlisted hosts) for Webtoons/Wayback and calls MangaBaka directly. The userscript uses `GM_xmlhttpRequest` and needs no proxy for fetching. The user chose to pursue both front ends. Tooling is Bun (`bun test`, `bun build`). No automatic MangaBaka search; a `title_no` link check only warns. **Alternatives:** Local Bun server only (not a hosted page); userscript only. **Consequences:** Two front ends to keep in step; the Worker is public infrastructure to protect. Cloudflare IPs may be throttled by Webtoons/Wayback — the userscript doesn't have that risk. ## 2026-10-14 — Original design decisions (from the design conversation) **Status:** partly superseded — see the two entries above **Context:** Recorded in the former `HANDOVER.md`. **Decision:** - Stack: TypeScript, chosen over Go (yambs is Go) to keep a browser extension or userscript possible. *Runtime superseded: Bun, not Node.* - Submission path: the API when a token is available, otherwise help with manual entry. - Which images: all — poster, square thumbnail, banner/background and foreground art. - Historical covers through the Wayback Machine. - Main cover: the current poster (square for canvas) gets `is_default: true`, existing covers `false`. - Rehosting on catbox.moe by default. *Superseded: R2, 30 days.* - Content rating chosen by the user, default `safe`; mature titles show a warning. - Image bytes kept in memory; sizes up to ~650 KB seen; 20 MB cap. - Extensibility: new sources and image hosts are one module plus one registry line. - Safety: nothing uploaded or sent without explicit user action; `save_mode: "review"`. - Not now: fields other than images; following language editions. - Automatic series matching via `/v2/series/match`. *Superseded: links given directly.* **Alternatives:** not recorded **Consequences:** See the spec.