portfolio-next/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-11-09 — Stack: Bun + TypeScript + React, with Astro

Status: accepted Context: The owner self-hosts and prefers Bun, TypeScript and React. The site must show content on first paint (no loading screens) and be easy to post to (1–3 personal items a month). Decision: Astro renders static HTML at build time; React is used only for interactive islands (⌘K palette, AI filter, side sheet, players, comic reader, showcases). Content is Markdown/MDX with frontmatter, posted by git push. Trakt and Hardcover are fetched at build time with scheduled rebuilds. Output is static files in a small container, self-hosted. Alternatives: A plain React SPA (blank first paint, against the no-loading principle). Bun's own fullstack approach (Bun.serve() + HTML imports, which bun init's CLAUDE.md recommends over Vite) was not yet weighed against Astro, which builds on Vite. See TODO. Consequences: Astro runs under Bun but uses Vite internally, so it diverges from bun init's frontend advice.

2026-11-09 — Personal space is the "rich wall" with a half-yearly issue

Status: accepted Context: The personal side hosts things the owner loves and thinks about (comics, games, films, songs, drawings, essays, life story, Trakt/Hardcover), at 1–3 items a month. Decision: mockups/personal-r2-b.html, plus a half-yearly zine/newspaper roundup inspired by personal-r2-c. Alternatives: shelves (r2-a), seasonal zine as the front page (r2-c), personal homepage (r2-d), and round 1 (P1–P5, too band-centric). Verdicts in docs/inspiration.md. Consequences: Cards are typed by content kind; the design must look full with 10–20 items.

2026-11-09 — Work space is the dark showcase (tech-r3-c)

Status: accepted Context: Four tech rounds. Paper metaphors felt boring; the sleek round 4 felt too modern. Decision: mockups/tech-r3-c.html as it is. tech-r4-a/b are kept as reference only. Alternatives: T1–T5, tech-r2-a…d, tech-r3-a/b, tech-r4-a/b. Consequences: The start page's left gate (light grid paper) and tech-r3-c (dark) don't yet match; open question.

2026-11-09 — Two gates, not three spaces

Status: accepted Context: An early reading split the site into "by hand before / with AI now / as a person". Decision: Two gates, work and personal (mockups/nav-d.html), plus a small link to an "everything at once" garden. The old 2021 site stays as an archive, reachable only via the "by hand only" AI preference, not promoted. The AI level is a filter, not a section. Alternatives: three doors (nav-a), a lens switch (nav-b), one garden as the home page (nav-c). Consequences: Every project needs an AI level (ai-made / some-ai / by-hand / unknown).

2026-11-09 — Adopt AGENTS.md as single source of truth

Status: accepted Context: Agents had no durable project context and no consistent workflow between sessions. 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. bun init's generated CLAUDE.md rules (use Bun over Node/npm/jest, bunx, no dotenv) were merged into AGENTS.md; its Bun.serve/HTML-import frontend advice was not, pending the stack question above. 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.