Skip to content
GRPNR.

02 — Case Studies: Agentic-Era Experience + Classic Adopter Reports

Researched 2026-07-19. Labels: VERIFIED-TODAY = source fetched/read on research date; ASSUMPTION = from training knowledge or synthesis, not re-verified. Sources: research packets R-E1 (agentic experience) and R-E2 (web case studies).

1. Agentic-era experience: what agents ship fastest (2025–2026)

1.1 Stack-by-stack agent throughput

Astro — strongest recent experience reports for exactly this use case (content/marketing/docs).

Next.js — most training data, wrong tool here.

  • Agents have the deepest pattern knowledge of Next.js (cosmicjs 2026), BUT version drift is a documented failure mode (see §1.2). For a 2-viewer local static showcase, Next’s hydration runtime + config surface is pure liability. ASSUMPTION (reasoned, uncontested in sources).

Plain HTML/Tailwind — fastest single page, weakest as a pipeline.

  • blog.luminoid.dev, “Every way to build a website in 2026”: plain HTML/CSS/JS “still works and is often the right call” for 1–5 page sites. Agents excel at single self-contained HTML files (zero config to misremember). ASSUMPTION: breaks down for our actual task — a markdown→pages pipeline with shared nav/layout means hand-rolling templating, i.e. rebuilding an SSG badly.

VitePress / Quartz — the markdown-native lane.

  • Quartz v5 (quartz.jzhao.xyz, v5.0.0, page dated 2026-06-11) — VERIFIED-TODAY (fetched): batteries-included, native Obsidian compatibility (wikilinks, transclusions), JSX layouts, plugin pipeline. No strong agent-experience reports found either way (thin evidence; ASSUMPTION: smaller training corpus means agents lean on reading its source — feasible, it’s small TypeScript). Note: our corpus inventory found zero wikilinks/callouts, so Quartz’s unique asset (Obsidian fidelity) buys us nothing here.
  • VitePress: mature Obsidian→VitePress workflows exist (bryanhogan.com, obsidian-vitepress plugin), but the default theme reads “docs site” — distinctive product pages fight the theme. ASSUMPTION (no direct agent reports found).

1.2 Documented agent failure modes

  • Tailwind v4 training-data lag — the loudest 2025 failure. benjaminlooi.dev (2025-10-10) — VERIFIED-TODAY (fetched, anecdote): agents run dead npx tailwindcss init -p, invent tailwind.config.js/PostCSS configs v4 doesn’t need. Corroborated: Prathit Joshi, tailwindlabs discussion #19594 (official v4 agent skills), community rule-packs (ofershap/tailwind-best-practices). Mitigation is known and cheap: pin v4 syntax in CLAUDE.md / use a skill; the failure is in setup, not day-to-day utility classes.
  • Next.js version/caching drift — silent-failure class (worst kind for agents). Agents emit getServerSideProps into App Router projects; Next silently ignores it — page renders empty, dev debugs for 20 min (powerdigitalmedia.org on Next 16 MCP (2025-10+), anecdote). Caching semantics churned across 15→16 (“use cache” rewrite, nextjs.org/blog/next-16, 2025-10 — VERIFIED release), so training data is persistently stale. Vercel’s answer is a DevTools MCP — i.e. even Vercel concedes agents can’t hold Next.js in their heads.
  • Hydration confusion: Astro’s explicit client:* directives make interactivity opt-in and legible to agents; Next ships a hydration runtime always (cosmicjs 2026). Astro-side failure: agents occasionally invent Next.js patterns inside Astro files — but this is caught at build time, not silently.
  • Plugin rot: no direct 2025–26 reports found for VitePress/Quartz plugin breakage under agents — a gap in evidence, not evidence of absence.

1.3 Anti-slop findings (design ceiling)

Convergent finding: slop is a prompting/tokens problem, not a stack problem.

  • prg.sh, “Why Your AI Keeps Building the Same Purple Gradient Website” (2025-10-26) — VERIFIED-TODAY (fetched): LLMs average their training data → Inter/Roboto, purple gradients, three-box grids. Fixes: explicit negative constraints, 3–5 named design references, per-dimension prompts.
  • Anthropic’s own guidance — Claude Cookbook, “Prompting for frontend aesthetics” + official frontend-design plugin (2025-11-12): commit to a named direction, ban Inter/Roboto and purple gradients, guide typography/color/motion/backgrounds individually. This environment already has frontend-design, impeccable, design-taste-frontend skills installed — the mitigation is on the shelf.
  • DESIGN.md / token-lock pattern: lock palette, fonts, radius, texture, motion in a root file so every page holds one decision (vibecodekit.dev, freedesignmd.com). The Astro rebuild report (§1.1) independently validates: design system first, then agent executes consistently.
  • Ceiling by stack (ASSUMPTION, synthesized): custom CSS/Tailwind v4 with locked tokens = highest ceiling (nothing fights you); shadcn = fast but its defaults ARE the slop look unless re-themed; VitePress default theme = docs-look floor AND ceiling unless replaced; Quartz = JSX layouts + SCSS, mid ceiling, wiki aesthetic by default.

2. Classic case studies

2.1 Quartz — real published gardens & wikis

Named adopters (from official showcase, VERIFIED-TODAY):

  • Nicole van der Hoeven — “Fork My Brain” (notes.nicolevanderhoeven.com). Large public Obsidian vault; no scale numbers published (VERIFIED-TODAY).
  • Juhis (hamatti) — “Garden of Learning” (notes.hamatti.org, post 2024-12-31, updated 2026-05-18, VERIFIED-TODAY). Hundreds of interconnected notes; deliberately manual build+push (no CI) to avoid publishing private notes. What broke: heavy inlined client-side JS made git diffs slow; he stripped contentIndexScript/staticResources.js (“thousands of incredibly long lines”), which killed built-in search. Wrote custom code so dead wikilinks render as <span> not broken anchors.
  • codingkoi.com review (2023-08-28, VERIFIED-TODAY). Stayed with Quartz but catalogued 7 issues: ~4 MiB/page from duplicated unminified inline JS, dead-wikilink rendering, Google Fonts external requests, no .html extensions (broke S3 hosting), confusing theme config. Fixed via custom Remark/Rehype plugins — “very happy” despite complaints. Caveat: pre-dates current Quartz polish.
  • Team/non-personal Quartz (showcase, VERIFIED-TODAY): Morrowind Modding Wiki, Stanford CME 302, Socratica Toolbox, Data Engineering Vault — team use exists but is a minority.
  • ASSUMPTION (high confidence): Quartz v3→v4 was a full rewrite (Hugo→Node/TS) requiring re-migration of customizations — the canonical Quartz upgrade-pain story. Single lead maintainer (jackyzha0) + community PRs.

Pattern: adopters are individuals/small communities at 100s–low-1000s of notes; everyone with opinions ends up patching plugins; nobody reports build-time pain — they report output bloat and customization friction.

2.2 Astro at md-corpus scale (~100–1000+ files)

  • Cloudflare developer docs — Hugo→Astro+Starlight (blog.cloudflare.com, “Open source all the way down”, 2024 + InfoQ 2025-02, VERIFIED-TODAY). Migration PR touched 8,060 files; 6 weeks total (10 days evaluating), only 1 day of code freeze, no rollbacks. Runs Astro 5.13.7; production build is memory-hungry (~6 GB heap) at that scale (DeepWiki build notes, VERIFIED-TODAY). Strongest “md corpus at 100x our scale” proof.
  • Raymond Camden — “I threw thousands of files at Astro” (2026-02-13), VERIFIED-TODAY. 6,742 posts. Wrong way (import.meta.glob in src/pages/): ~70 s per dev-server load. Right way (content collections + content.config): ~7,000-page production build in 8 seconds. Lesson: at corpus scale, content collections are mandatory, not optional. (Our corpus is 86 files — two orders of magnitude below any pain threshold.)
  • Elio Struyf — Hugo→Astro migration of 500+ posts. ASSUMPTION on details: wrote Remark plugins to translate Hugo shortcodes rather than hand-editing posts (approach confirmed via search; post not fetched today).
  • Upgrade pain, ASSUMPTION (well-documented): Astro 5 (Dec 2024) replaced v2-era content collections with the Content Layer; a legacy.collections flag eased it, but every major (2→3→4→5) required config/API touch-ups — annual minor churn, no rewrite-scale events.
  • Agentic-era note, ASSUMPTION (medium confidence): Cloudflare’s docs being plain md/MDX in an open repo is explicitly agent-friendly (markdown/llms.txt endpoints for LLM consumption); Astro+md is now one of the most common stacks in Claude-Code-built sites — deep training-data familiarity.

2.3 Internal program-showcase / “program hub” sites

Public writeups of true internal showcase sites are rare; what exists clusters into three patterns:

  • Spotify TechDocs (backstage.io blog, 2020-09-08 + devrel talk, VERIFIED-TODAY): docs-like-code — engineers write markdown next to code, CI renders via MkDocs, served centrally in Backstage. 5,000+ internal doc sites, ~10,000 daily hits, ~20% of all Backstage traffic (most-used of 130+ plugins). The canonical “internal md→site at scale” case.
  • Backstage-style IDP portals (Red Hat 2024-09-25, Northflank 2026 roundup, platformengineering.org — VERIFIED-TODAY search layer): consistent caveat across writeups — Backstage requires dedicated engineers to maintain; universally cited as overkill below ~50 engineers. For a 2-viewer showcase this is an anti-case: adopt the docs-like-code idea (md beside the work product, auto-rendered), not the portal machinery.
  • Small-scale platform-team practice (ASSUMPTION, from broad exposure): program hubs are almost always either (1) a static docs site (MkDocs Material / Docusaurus / Starlight) with one page per product, or (2) a wiki space (Confluence/Notion) that rots. Repeated public failure mode (e.g. doctave.com culture-of-docs posts, 2021): hubs die when publishing requires steps outside the authors’ normal workflow — survivors render the md the team already writes.
  • Mozilla firefox.com-on-Astro could not be verified — unconfirmed, do not cite.

3. Cross-cutting “what they’d change”

  • Quartz adopters: less inline JS, saner link handling — they patch, they don’t leave. Its unique asset (Obsidian-flavored-md fidelity: wikilinks, callouts, backlinks, graph) is one our corpus doesn’t use.
  • Astro adopters: “use content collections from day one”; budget for small annual major-version churn. Scale headroom is effectively infinite for an 86-file corpus.
  • Internal hubs: the only durable ones render the markdown people already maintain (TechDocs lesson); portal frameworks (Backstage) are the documented over-engineering trap.
  • Agentic builders: lock design tokens in a root file before any page is authored; pin Tailwind v4 syntax rules in CLAUDE.md; prefer stacks whose failures surface at build time (Astro) over ones that fail silently (Next).

Evidence gaps

No measured (non-anecdotal) agent-throughput comparisons across SSGs exist; VitePress/Quartz agent-experience reports are thin; all Lighthouse/KB numbers are from advocacy blogs; Quartz showcase publishes no note counts; internal-hub evidence at true small scale (2–10 viewers) is inference, not published case study.