feat: refine and finalize redesign

CLAUDE.md

@@ -12,49 +12,81 @@ that combines GitHub Flow with versioned releases.
 ## Build Commands
 
 ```bash
-# Install tooling (bun) via mise
+# Install tooling (node) via mise
 mise install
 
 # Install dependencies
-bun install
+npm install
 
 # Development server
-bun run dev
+npm run dev
 
-# Build site (outputs to docs/ directory)
-bun run build
+# Build site (outputs to dist/ directory)
+npm run build
 
 # Preview built site
-bun run preview
+npm run preview
+
+# Type checking
+npm run check
+
+# Linting
+npm run lint
+
+# Formatting
+npm run format
+npm run format:check
 
 # Update specs from upstream (fetches from github.com/jimeh/common-flow)
-bun run update
+npm run update-specs
 ```
 
-The site is built to `docs/` for GitHub Pages hosting.
+The site is built to `dist/` and deployed to Cloudflare Workers.
 
 ## Architecture
 
 - **Astro 5.x** static site generator
 - **Tailwind CSS 4.x** for styling with dark mode support
+- **astro-icon** with Heroicons and Simple Icons for icons
 - **Content Collections** for spec markdown files
 - **TypeScript** throughout
-- **Bun** as JavaScript runtime and package manager (managed via mise)
+- **Node.js** as JavaScript runtime (managed via mise)
 
 ### Key Files
 
-- `src/config.ts` - Site configuration with version list
+- `src/config.ts` - Site configuration (metadata, update settings)
 - `src/content.config.ts` - Astro content collection definition
-- `src/layouts/Default.astro` - Main layout with sidebar
-- `src/components/` - Sidebar, MenuToggle, ThemeToggle components
+- `src/styles/global.css` - Global Tailwind styles
+- `src/layouts/BaseLayout.astro` - Base layout with head, meta tags, theme scripts
+- `src/layouts/SpecLayout.astro` - Spec page layout composing all sections
+- `src/components/` - UI components:
+  - `Header.astro` - Site header with navigation
+  - `Footer.astro` - Site footer
+  - `Hero.astro` - Landing page hero section
+  - `AboutSection.astro` - About Common-Flow section
+  - `FAQSection.astro` - FAQ section
+  - `SectionHeader.astro` - Reusable section header (title + subtitle)
+  - `SpecSection.astro` - Spec section with terminology and specification
+  - `SpecSidebar.astro` - Spec page table of contents sidebar
+  - `TocLink.astro` - Reusable TOC link component
+  - `ThemeToggle.astro` - Dark/light mode toggle
+  - `VersionSelector.astro` - Spec version dropdown
+- `src/scripts/` - Client-side TypeScript:
+  - `activeSectionTracker.ts` - Scroll-based active section tracking
+  - `clauseHighlight.ts` - Clause highlight on anchor navigation
+- `src/pages/index.astro` - Landing page
+- `src/pages/404.astro` - 404 error page
 - `src/pages/spec/[version].astro` - Dynamic route for spec versions
+- `src/pages/spec/[version]/raw.astro` - Raw markdown spec page
+- `src/utils/` - Utility functions:
+  - `parseSpecContent.ts` - Markdown parsing utilities
+  - `versions.ts` - Version info helper (derives current version from specs)
 - `src/content/spec/*.md` - Versioned spec documents
 - `public/spec/*.svg` - SVG diagrams for each version
 - `scripts/update-specs.ts` - Fetches specs from GitHub
+- `wrangler.jsonc` - Cloudflare Workers deployment config
 
 ### Updating Spec Versions
 
-1. Add new version to `versions` array in `src/config.ts`
-2. Update `currentVersion` if this is the new default
-3. Run `bun run update` to fetch specs from GitHub
-4. Run `bun run build` to rebuild the site
+1. Run `npm run update-specs` to fetch specs from GitHub
+2. Run `npm run build` to rebuild the site