Changelog - 2025-04-25 (01)

Site Scaffold from Astro Knots Conventions

Why Care?

For the firm (Mike): This is the first end-to-end test of whether our Astro Knots documentation actually works as a self-serve onboarding path. An AI assistant — handed only CLAUDE.md, README.md, and the New-Site-Quickstart-Guide.md — produced a working site skeleton on the first attempt. Build passes, three-mode toggle works, brand kit + design system pages render, content collections compile. That means the next site can be spun up in hours instead of days, without me having to walk anyone through the patterns. The investment in writing down the conventions (blueprints, prompts, CLAUDE.md) is paying compounding interest.

For our end users (VCs visiting fullstack-vc.com): Nothing user-facing yet — this is internal scaffolding. But the foundation that landed determines what every page on the site will feel like:

• Three rendering modes (light / dark / vibrant) with a one-click toggle in the header. VCs who like clean docs get light. VCs who live in their terminal get dark. VCs who want loud get vibrant. The toggle persists across sessions.
• Devtools-meets-dojo aesthetic improvised in the absence of a brand kit — violet primary, lime accent, JetBrains Mono for code, Space Grotesk for display, Inter for body. Anchors the brand in “this is for technical VCs” without being grim.

---

What landed

Workspace + config

• sites/fullstack-vc/ registered in pnpm-workspace.yaml. Astro 6 / Tailwind 4 / TypeScript 6.
• astro.config.mjs with the canonical monorepo vite.server.fs.allow: ['../..'] and path aliases.
• Site URL set to https://fullstack-vc.com.

Theme + mode subsystem (firm-wide policy)

• src/styles/theme.css — two-tier token architecture per blueprint §2.1: 14 named tokens (--color__violet-electric, --font__lato, etc.) + semantic aliases (--color-primary, --font-heading-1) + per-mode --fx-* blocks for light / dark / vibrant.
• src/utils/theme-switcher.js + src/utils/mode-switcher.js — adapted from the new packages/ui/theme-mode/ pattern reference. Three modes hard-coded; theme axis is single-theme (default) for now.
• BaseThemeLayout boots both switchers and renders the Header on every page.
• Header.astro (sticky, blurred backdrop) hosts the ModeToggle chrome button.

Reference pages (firm-wide policy)

• /brand-kit — five required sections (named colors, semantic colors, typography, marks, signature layout). Inspection toggle for picking a specific mode.
• /design-system — component catalog with cards, buttons, fx-token reference table, and a component index. Both pages emit noindex, nofollow.

Content collections (data model only — no views yet)

• src/content.config.ts defines pages and webinars collections with Zod schemas. Webinars view + sample entry + detail page land in entry 02.

Index page

Hero with mode-aware gradient headline (“Give your firm AI superpowers.”), CTA buttons, and a code-comment status note. Improvised — iterate freely.

---

Doc gaps surfaced and fixed in the same pass

The scaffolding exposed real holes in the documentation. Each was closed before this changelog landed:

1. Hypernova switchers were 2-mode only. The Quickstart said “copy from sites/hypernova-site/src/utils/” but those files only handled light/dark. Wrote a 3-mode mode-switcher.js, then extracted to packages/ui/theme-mode/ as the new canonical reference. Quickstart now points at the package.
2. No mandatory chrome-toggle policy. The Themes blueprint mentioned toggles only on /brand-kit. Added §5.0 “Mandatory Site-Chrome Mode Toggle” — every site MUST expose the 3-mode toggle in persistent header/footer chrome.
3. Parallel switcher implementations across sites. Banner-site’s ModeToggle.astro had inline switcher logic with its own localStorage key ('emblem-mode' instead of 'mode'). The canonical extraction at packages/ui/theme-mode/components/ModeToggle.astro reads window.modeSwitcher (booted by BaseThemeLayout) so the UI and the shared utility can never drift again.

---

Skipped on purpose (Phase 8 + deployment)

• LFM markdown rendering. Site has no extended markdown needs yet. Will adopt @lossless-group/lfm if/when content authoring requires citations, callouts, or directives.
• Submodule conversion. Site is currently a regular subdirectory of astro-knots. Becomes its own repo + Vercel-watched submodule once a GitHub repo exists.

Next

• Webinars collection rendering — list page, calendar-style cards, detail pages. (Entry 02.)
• Real Luma URLs once the launch event is created.