docs: site-level design contract (2026-10-06 interview) and product brief

DESIGN.md

+# Design — pln-www, the site contract
+
+> Site-level design contract, ratified 2026-10-06 through a six-round owner interview.
+> Every quoted line below is the owner's verbatim answer. Micro-brands keep their own
+> docs next to their code: `app/cosmicfest/{PRODUCT,DESIGN}.md`; ParVagues carries its
+> identity in `app/parvagues/` + `styles/parvagues.module.css`. North-star reference:
+> [bleuje.com](https://bleuje.com/). Blog reading benchmarks: Scott Alexander, The Zvi,
+> Wait But Why, rachelbythebay, gwern.net.
+
+## Register
+
+brand — the design IS the product. This is the home of one person's whole practice.
+
+## Identity & voice
+
+**Fused engineer-artist, gallery-forward.** One pegboard, all hats: creative coder and
+engineer side by side; the gallery leads, professional work is a first-class citizen, not
+a separate rail.
+
+Landing voice: **plain-spoken with nerdy-wink undertones.**
+
+> Owner, verbatim: *"plain spoken and nerdy winks undertones. tbh i say 'Machine Learning
+> de Jour, Machine Dansing de Nuit' on some cards :P"*
+
+Final copy is always the owner's own words; the contract fixes register, not sentences.
+
+## Foundations
+
+- **Phone-first everywhere, stellar desktop reading.**
+  > *"phone first but i wanna stellar desktop blog ux for readers. substack, gwen level again"*
+- **Themes.** Light default (the site is a book and a blog), stellar dark mode with a
+  toggle, dark-always for the creative sections (ParVagues, /atlas).
+  > *"light default (landing, blog), optional changes e.g. parvagues dark. and stellar dark
+  > mode support with a toggle, but light default imo for a book and for a blog?"*
+- **Motion.** Rich yet thoughtful; always reducible when it tires; `prefers-reduced-motion`
+  respected everywhere.
+  > *"motion rich yet thoughtful. we can always reduce if too much"*
+- **Constraints (the design contract's hard floor):**
+  - near-zero (not zero) client JS on reading pages; graceful degradation for no-JS readers;
+    great JS QoL additions, packed lightweight and a11y-validated
+  - stellar mobile performance
+  - accessibility baseline: contrast, focus, keyboard, reduced motion, semantic HTML
+  - no third-party calls on core pages
+  - playful errors designed in from round one (the generative 404), never bolted on
+
+## Navigation
+
+> *"slim persistent nav (and shared fixed footer i think btw except on fullscreen:true
+> experiences but none atm), and a command palette YES! And a stellar, in-browser,
+> typo-tolerant, search experience."*
+
+Slim persistent header (name-mark + blog / projects / apps + language switch), shared fixed
+footer, `⌘K` command palette.
+
+**Search = Pagefind.** Static-only, no third party; indexed at build; stellar-fast,
+typo-tolerant, with highlighting, suggestions, rich rendering.
+
+> *"pagefind, static only, no third party, algolia taught, we apply. indexed at build,
+> stellar fast, typo tolerant, highlighting, suggestions, rich render etc :) use algolia OSS
+> libs wherever it helps :))"*
+
+## Landing
+
+Statement + live pulse. Pulse items: **latest post** + **project thread activity**
+(reception counts may join when first-party analytics land). A mini tile of /atlas links
+out from the front door.
+
+## Blog
+
+**Index:** typographic archive — year-grouped list, date + title + one-line description +
+project badges. Prose-forward, scannable.
+
+**Article page:** the crown jewel. Anatomy (all ratified):
+
+- footnotes/sidenotes: asides inline on desktop, collapsed on mobile
+- sticky mini-TOC on long posts, reading progress, prev/next, related via post↔project links
+- code blocks with copy button + language label (shiki at build); figures with captions,
+  lightbox on click
+- language switch on the article itself, remembers choice; untranslated posts say so honestly
+- search-to-section and load-page-with-highlight-text-to-match (gwern-grade UX)
+  > *"oh yes inspiration is gwen.net ofc also, with stellar notes experience, with asides
+  > rendered inside on desktop, proper on mobile, etc. search to section,
+> load-page-wtih-highlight-text-to-match, etc stellar UX"*
+
+**Bilingual, fully.** Every post exists in fr + en, translated by the author himself.
+
+> *"full biling. tbh i want blog posts to be full biling and my own home translation, ce qui
+> ce concoit bien merite d'etre enonce dans la langue de chaque penseur qui me confie son
+> attention."*
+
+Disk model (owner's proposal, ratified): `content/blog/<slug>/meta.md` (shared metadata)
++ `fr.md` + `en.md`. Per-language frontmatter (title) lives in the language files.
+
+## /projects — the git-graph threads
+
+A **git-graph of the making**: each curated project is a thread through time; shipped
+threads terminate in a node, active threads keep branching; posts are commits, releases are
+merges, and projects that merged into each other are literally drawn merging (the clarté
+tdah/tsa lineage gets its joke).
+
+- **Scope:** curated graph + a lighter "everything else" experiment list beside it.
+- **Data:** hybrid — CMS-declared milestone events carry the story; git-log density
+  (line thickness) carries the texture, never noise-as-content. Git metadata should also be
+  visible in the CMS editor when viewing projects (validate against Sveltia capabilities;
+  a link-out to git.nech.pl is the honest fallback).
+- **Phone:** the graph degrades into a beautiful vertical timeline.
+
+## Project pages
+
+**Bespoke-per-project on a shared kit.** Every project page is its own design, but draws
+from the shared token kit and primitives (nav, footer, date, embeds); deviations must be
+justified; foundational frameworks/libraries chosen deliberately.
+
+> *"ideally shared kit, but dont forbid bespoke when warranted. voerall shared kit, and
+> minimal deviations is the goal. and jsutified foundational framewokrs and libs and tools
+> properly."*
+
+ParVagues is the flagship precedent and keeps its own SPA shell.
+
+## /atlas — the living-field side app
+
+Name ratified: *"**/atlas** c'est cool c'est stellaire fr et en lets go :)"*
+
+A generative rendering of the site's own data and states, as an art piece beside /fleurs
+and /starry-nights. Ambient at rest (slow breathing field), wakes on hover, nodes tuggable,
+project details on tap. Layered by design so new data layers slot in without rearchitecting:
+
+1. **Content graph** (first layer): projects, posts, tags, dates from the CMS build.
+2. **Git pulse:** all public GitHub and GitLab projects, plus the www edit streams
+   (draft/blog edit activity shown aggregated).
+3. **Reception telemetry** (later): first-party analytics once that foundation exists.
+
+## Legacy sections
+
+Fold into the new model — talks, poems, hydras each become an event/thread:
+
+> *"fold into new model, tho they are 'each a project' in a way, with each talk/project/
+> poem/hydra a new event :P"*
+
+Cosmicfest and oblique keep standalone status. Nothing is orphaned.
+
+## Anti-references
+
+- The hiring-page: credentials, stacks, roles up top. Wrong register for this site.
+- The two-rails split ("work" vs "practice") — the fusion is the point.
+- Every-project-fully-bespoke-everything (token chaos, maintenance debt).
+- Dark-only reading; cream/sand AI-default backgrounds; gradient text; side-stripe borders;
+  identical card grids; eyebrow kickers on every section; numbered section scaffolding.
+- The constellation map (intriguing, too conceptual for the main timeline — its spirit
+  lives inside /atlas instead).

PRODUCT.md

+# Product
+
+> Site-level. Micro-brands keep their own product docs next to their code:
+> `app/cosmicfest/PRODUCT.md`, and ParVagues' identity lives with its app.
+
+## Register
+
+brand
+
+## What this is
+
+The home of **PLN**: one person's whole practice on one pegboard — engineer by trade
+(infrastructure, SRE, ML), creative coder by nature (livecoding, generative art, music
+tools). The site is a gallery of that practice, a bilingual long-form blog, and a family
+of small apps.
+
+## Users
+
+Fellow creative coders, engineers, friends, and curious passersby — mostly arriving on
+phones from links (blog posts, project pages, Mastodon/GitLab), staying for the reading
+experience and the work. Some arrive to hire or collaborate; they get the fused identity,
+not a résumé page.
+
+## Purpose
+
+- Show the work: a curated, legible, living timeline of projects (the git-graph) with
+  everything else one click away.
+- Host the writing: fully bilingual (fr/en, own translations) long-form posts at
+  Substack/Gwern reading quality, cross-linked to the projects they grew from.
+- Be the mirror: /atlas renders the site's own data as generative art.
+- All of it self-hosted on the home stack (erable + git.nech.pl), zero third-party
+  dependencies on core pages.
+
+## Success criteria
+
+- PLN edits/publishes from the browser (Sveltia at /admin) without touching a terminal.
+- A reader on a phone on 4G gets a fully readable post in seconds; a desktop reader gets
+  a Gwern-grade article page.
+- The gallery makes the practice legible: what exists, what's alive, what merged into what.
+- Every page light-theme default, dark mode one toggle away, no tracking, no slop.
+
+## Design contract
+
+See [DESIGN.md](DESIGN.md) — the ratified 2026-10-06 contract with the owner's verbatim
+interview answers. Nothing ships that contradicts it without a new ratification.