mangabaka-seeder/docs/DECISIONS.md

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 — 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/<sha256>.<ext>, 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.