the-grid-cc 1.4.0 → 1.6.0

package/.grid/plans/blog-block-02.md

@@ -1,229 +0,0 @@
----
-cluster: james-weatherhead-blog
-block: 02
-type: execute
-wave: 2
-depends_on: [01]
-files_modified: [src/layouts/BaseLayout.astro, src/components/Header.astro, src/components/Footer.astro, src/components/DarkModeToggle.astro, src/styles/global.css]
-autonomous: false
-
-must_haves:
-  truths:
-    - "Dark mode toggles between light and dark themes"
-    - "Navigation links are visible and functional"
-    - "Layout is responsive on mobile and desktop"
-  artifacts:
-    - path: "src/layouts/BaseLayout.astro"
-      provides: "Base HTML structure with dark mode support"
-      min_lines: 40
-    - path: "src/components/Header.astro"
-      provides: "Site navigation with logo/title and links"
-      min_lines: 20
-    - path: "src/components/DarkModeToggle.astro"
-      provides: "Interactive dark mode toggle button"
-      min_lines: 30
-  key_links:
-    - from: "DarkModeToggle.astro"
-      to: "document.documentElement"
-      via: "classList.toggle('dark')"
-      pattern: "classList\\.toggle\\('dark'\\)"
-    - from: "BaseLayout.astro"
-      to: "localStorage"
-      via: "theme persistence script"
-      pattern: "localStorage\\.getItem\\('theme'\\)"
----
-
-<objective>
-Build the layout system with base layout, header, footer, and dark mode functionality.
-
-Purpose: Create reusable layout components that provide consistent structure, navigation, and theming across all pages.
-Output: Responsive layout with working dark mode toggle, navigation header, and footer.
-</objective>
-
-<context>
-Block 01 completed: Astro project initialized with Tailwind (darkMode: 'class') and Vercel adapter.
-
-This block builds the visual foundation. The layout system must:
-- Support dark mode toggle (class-based, not media query)
-- Be minimal and clean (per requirements)
-- Work on mobile and desktop
-- Include header with site title and nav links
-- Include footer with copyright/contact info
-
-No blog content yet - that comes in Block 03. This focuses purely on structure and theming.
-</context>
-
-<threads>
-
-<thread type="auto">
-  <name>Thread 1: Create base layout with dark mode persistence</name>
-  <files>src/layouts/BaseLayout.astro, src/styles/global.css</files>
-  <action>
-  Create BaseLayout.astro as the foundational layout component:
-
-  1. Create src/layouts/BaseLayout.astro with props interface:
-     - title: string
-     - description?: string
-     - ogImage?: string
-
-  2. Structure:
-     - HTML doctype and head with meta tags (viewport, charset, description)
-     - SEO meta tags (og:title, og:description, twitter:card)
-     - Link to global.css
-     - Inline script in head (before body renders) to prevent flash:
-       ```js
-       const theme = localStorage.getItem('theme') || 'dark'; // default dark per minimal aesthetic
-       if (theme === 'dark') document.documentElement.classList.add('dark');
-       ```
-     - Body with dark:bg-gray-900 bg-gray-50 dark:text-gray-100 text-gray-900
-     - Slot for page content
-
-  3. Create src/styles/global.css:
-     - @tailwind base/components/utilities
-     - Custom font stack: system-ui, -apple-system, sans-serif
-     - Smooth scroll behavior
-     - Focus styles for accessibility
-
-  AVOID: Do not use media query dark mode (requirements specify toggle, not auto). Do not add analytics scripts yet (keep minimal). WHY: User wants control over theme, not automatic switching based on system preference.
-  </action>
-  <verify>
-  Check: src/layouts/BaseLayout.astro exists with inline theme script
-  Check: localStorage persistence script runs before body render
-  Check: global.css imports Tailwind directives
-  Run: grep -r "localStorage.getItem" src/layouts/BaseLayout.astro
-  </verify>
-  <done>
-  - BaseLayout.astro exports layout with title, description props
-  - Inline script prevents FOUC (flash of unstyled content)
-  - Dark mode classes applied to html element
-  - global.css configures Tailwind and typography
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 2: Build Header and Footer components</name>
-  <files>src/components/Header.astro, src/components/Footer.astro</files>
-  <action>
-  Create navigation header and footer components:
-
-  Header.astro:
-  1. Create header element with container max-w-3xl mx-auto px-4 py-8
-  2. Site title "James Weatherhead" as h1 or logo
-  3. Navigation links: Home (/) | Blog (/blog) | About (/about)
-  4. Include DarkModeToggle component (will create in next thread)
-  5. Make responsive: stack on mobile, horizontal on desktop (md:flex)
-  6. Style links with hover:text-blue-600 dark:hover:text-blue-400
-
-  Footer.astro:
-  1. Create footer element with border-t border-gray-200 dark:border-gray-800
-  2. Container max-w-3xl mx-auto px-4 py-8
-  3. Copyright text: © 2024 James Weatherhead
-  4. Optional: Contact links or social media (GitHub, Twitter) if provided
-  5. Small text size: text-sm text-gray-600 dark:text-gray-400
-
-  AVOID: Do not add complex navigation menus (keep minimal - 3 links max). Do not add social media icons unless assets provided. WHY: Requirements specify "minimal design" - extra navigation adds visual clutter.
-  </action>
-  <verify>
-  Check: src/components/Header.astro exists with nav links
-  Check: src/components/Footer.astro exists with copyright
-  Check: Both use max-w-3xl for content width consistency
-  Run: grep -r "max-w-3xl" src/components/
-  </verify>
-  <done>
-  - Header.astro contains site title and 3 navigation links
-  - Footer.astro contains copyright and minimal info
-  - Both components use consistent container width (max-w-3xl)
-  - Responsive styles applied with Tailwind breakpoints
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 3: Implement dark mode toggle component</name>
-  <files>src/components/DarkModeToggle.astro</files>
-  <action>
-  Create interactive dark mode toggle button:
-
-  1. Create DarkModeToggle.astro with client:load directive (needs JS)
-  2. Button element with aria-label="Toggle dark mode" for accessibility
-  3. Icon: Use Unicode characters (☀️ sun / 🌙 moon) or SVG for sun/moon icons
-  4. Client-side script:
-     ```js
-     const toggle = document.querySelector('#dark-mode-toggle');
-     toggle.addEventListener('click', () => {
-       const isDark = document.documentElement.classList.toggle('dark');
-       localStorage.setItem('theme', isDark ? 'dark' : 'light');
-     });
-     ```
-  5. Style: rounded-full p-2 hover:bg-gray-200 dark:hover:bg-gray-800 transition
-  6. Position in Header component (top-right corner)
-
-  AVOID: Do not use React or Vue (keep Astro-native for simplicity). Do not add animations beyond simple transition. WHY: Requirements don't specify framework components, and excessive animations conflict with minimal aesthetic.
-  </action>
-  <verify>
-  Check: DarkModeToggle.astro exists with client:load directive
-  Check: Toggle button has click handler that updates localStorage
-  Check: classList.toggle('dark') targets documentElement
-  Run: grep -r "client:load" src/components/DarkModeToggle.astro
-  </verify>
-  <done>
-  - DarkModeToggle.astro component created with interactive button
-  - Click handler toggles 'dark' class on html element
-  - Theme preference persists in localStorage
-  - Accessible with aria-label
-  </done>
-</thread>
-
-<thread type="checkpoint:human-verify" gate="blocking">
-  <what-built>
-  Complete layout system with:
-  - BaseLayout.astro (theme persistence, no FOUC)
-  - Header.astro (navigation: Home, Blog, About)
-  - Footer.astro (copyright, minimal info)
-  - DarkModeToggle.astro (interactive toggle with localStorage)
-  - global.css (Tailwind config, typography)
-  </what-built>
-  <how-to-verify>
-  1. cd /Users/jacweath/grid/blog && npm run dev
-  2. Create test page at src/pages/index.astro using BaseLayout
-  3. Visit http://localhost:4321
-  4. Check:
-     - Header appears with "James Weatherhead" title and nav links
-     - Footer appears with copyright
-     - Dark mode toggle button visible (sun/moon icon)
-  5. Click dark mode toggle:
-     - Background switches from light to dark (or vice versa)
-     - Text color changes appropriately
-     - Refresh page - theme persists
-  6. Test responsive:
-     - Resize browser to mobile width
-     - Header should stack vertically or remain readable
-  7. Check browser console for errors (should be none)
-  </how-to-verify>
-  <resume-signal>Type "approved" if layout and dark mode work correctly, or describe any issues (e.g., "toggle not working", "colors wrong")</resume-signal>
-</thread>
-
-</threads>
-
-<verification>
-Complete verification checklist:
-1. BaseLayout.astro exists with theme persistence script
-2. Header.astro has navigation links (/, /blog, /about)
-3. Footer.astro has copyright text
-4. DarkModeToggle.astro has client:load and click handler
-5. global.css imports Tailwind directives
-6. Dark mode toggle switches theme without page reload
-7. Theme persists across page refresh (localStorage)
-8. Layout is responsive on mobile and desktop
-9. No FOUC (flash of unstyled content) on page load
-10. Browser console has no errors
-</verification>
-
-<success_criteria>
-- Layout system renders correctly in browser
-- Dark mode toggle switches between light and dark themes
-- Theme preference persists in localStorage
-- Navigation links are visible and clickable
-- Responsive on mobile and desktop
-- No console errors
-- User approves visual appearance and functionality
-</success_criteria>

package/.grid/plans/blog-block-03.md

@@ -1,253 +0,0 @@
----
-cluster: james-weatherhead-blog
-block: 03
-type: execute
-wave: 2
-depends_on: [01]
-files_modified: [src/content/config.ts, src/content/blog/sample-post.md, src/pages/blog/[...slug].astro, src/components/PostList.astro, src/components/Tag.astro]
-autonomous: false
-
-must_haves:
-  truths:
-    - "Blog posts are defined as content collection with schema"
-    - "Individual blog posts render with frontmatter data"
-    - "Tags are extracted and displayed for each post"
-  artifacts:
-    - path: "src/content/config.ts"
-      provides: "Content collection schema for blog posts"
-      exports: ["collections"]
-    - path: "src/pages/blog/[...slug].astro"
-      provides: "Dynamic blog post page template"
-      min_lines: 50
-    - path: "src/components/PostList.astro"
-      provides: "Reusable component for listing blog posts"
-      min_lines: 30
-  key_links:
-    - from: "src/pages/blog/[...slug].astro"
-      to: "getCollection('blog')"
-      via: "Astro content collections API"
-      pattern: "getCollection\\('blog'\\)"
-    - from: "src/content/config.ts"
-      to: "zod schema"
-      via: "defineCollection"
-      pattern: "defineCollection"
----
-
-<objective>
-Implement blog content structure using Astro Content Collections with markdown posts, frontmatter validation, and tag support.
-
-Purpose: Create the core blog functionality - content schema, post rendering, and listing capabilities.
-Output: Content collection configured, sample post created, dynamic post template working.
-</objective>
-
-<context>
-Block 01 completed: Astro project initialized with Tailwind and Vercel adapter.
-Block 02 in progress: Layout system (runs parallel with this block).
-
-This block focuses on the content layer using Astro's Content Collections API. Requirements specify:
-- Markdown-based posts
-- Tags for organization
-- Syntax highlighting (shiki installed in Block 01)
-
-Content Collections provide type-safe frontmatter, automatic routing, and built-in markdown processing. This is the canonical Astro approach for blog content.
-
-Block 02 (layouts) and Block 03 (content) can run in parallel since they modify different files with no overlap.
-</context>
-
-<threads>
-
-<thread type="auto">
-  <name>Thread 1: Configure content collection schema</name>
-  <files>src/content/config.ts, src/content/blog/sample-post.md</files>
-  <action>
-  Set up Astro Content Collections for blog posts:
-
-  1. Create src/content/config.ts with zod schema:
-     ```ts
-     import { defineCollection, z } from 'astro:content';
-
-     const blog = defineCollection({
-       type: 'content',
-       schema: z.object({
-         title: z.string(),
-         description: z.string(),
-         pubDate: z.coerce.date(),
-         updatedDate: z.coerce.date().optional(),
-         tags: z.array(z.string()).default([]),
-         draft: z.boolean().default(false),
-       }),
-     });
-
-     export const collections = { blog };
-     ```
-
-  2. Create src/content/blog/ directory
-
-  3. Create sample post: src/content/blog/sample-post.md
-     - Frontmatter with all required fields (title, description, pubDate, tags)
-     - Markdown content with headings, paragraphs, code blocks
-     - Use tags: ["javascript", "astro", "web-development"]
-     - Include code block to test syntax highlighting
-
-  AVOID: Do not add complex media fields yet (images come later if needed). Do not add author field unless multi-author (single author blog). WHY: Keep schema minimal - only add fields when content requires them.
-  </action>
-  <verify>
-  Run: npm run build (should succeed with no schema errors)
-  Check: src/content/config.ts exports 'collections' with 'blog'
-  Check: sample-post.md exists with valid frontmatter
-  Run: npx astro check (validates content schema)
-  </verify>
-  <done>
-  - src/content/config.ts defines blog collection with zod schema
-  - Schema includes: title, description, pubDate, updatedDate, tags, draft
-  - sample-post.md created with valid frontmatter
-  - Build completes without content validation errors
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 2: Create dynamic blog post template</name>
-  <files>src/pages/blog/[...slug].astro</files>
-  <action>
-  Create dynamic route for individual blog posts:
-
-  1. Create src/pages/blog/[...slug].astro
-
-  2. Implement getStaticPaths():
-     ```ts
-     import { getCollection } from 'astro:content';
-     export async function getStaticPaths() {
-       const posts = await getCollection('blog', ({ data }) => !data.draft);
-       return posts.map(post => ({
-         params: { slug: post.slug },
-         props: post,
-       }));
-     }
-     ```
-
-  3. Destructure props: const { data, render } = Astro.props;
-  4. Render post with BaseLayout:
-     - Pass title and description to layout
-     - Render metadata: title, date, tags
-     - Render content: const { Content } = await render();
-     - Style with Tailwind typography: prose dark:prose-invert max-w-3xl
-
-  5. Date formatting: use Intl.DateTimeFormat or date-fns
-  6. Tags: render as badges with Tag component (create in next thread)
-
-  AVOID: Do not add comments (requirements say "none"). Do not add related posts sidebar (keep minimal). WHY: Feature requirements explicitly exclude comments; related posts adds complexity without requirement.
-  </action>
-  <verify>
-  Run: npm run dev
-  Visit: http://localhost:4321/blog/sample-post
-  Check: Post renders with title, date, tags, and content
-  Check: Code blocks have syntax highlighting
-  Check: Prose typography applied correctly
-  </verify>
-  <done>
-  - [slug].astro implements getStaticPaths with getCollection
-  - Filters out draft posts (data.draft === false)
-  - Renders post content with proper typography
-  - Displays frontmatter data (title, date, tags)
-  - Syntax highlighting works in code blocks
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 3: Build post list and tag components</name>
-  <files>src/components/PostList.astro, src/components/Tag.astro</files>
-  <action>
-  Create reusable components for displaying posts and tags:
-
-  PostList.astro:
-  1. Props interface: posts (array of blog collection entries)
-  2. Map over posts and display:
-     - Title (link to /blog/{slug})
-     - Description
-     - Date (formatted)
-     - Tags (using Tag component)
-  3. Sort by pubDate descending (newest first)
-  4. Style: space-y-8 for vertical spacing, hover states on titles
-  5. No pagination yet (add later if needed)
-
-  Tag.astro:
-  1. Props: tag (string), variant?: 'link' | 'badge'
-  2. If variant === 'link': render as link to /blog/tags/{tag}
-  3. If variant === 'badge': render as span with badge styles
-  4. Style: rounded-full px-3 py-1 text-sm bg-gray-200 dark:bg-gray-800
-
-  AVOID: Do not add filter/search UI (add later if needed). Do not add pagination yet (YAGNI - wait until many posts exist). WHY: Premature optimization - start simple, add features when content volume requires it.
-  </action>
-  <verify>
-  Check: PostList.astro accepts posts prop and maps over entries
-  Check: Tag.astro handles both 'link' and 'badge' variants
-  Check: Tags are clickable links (variant='link') or static badges
-  Run: grep -r "variant=" src/components/Tag.astro
-  </verify>
-  <done>
-  - PostList.astro displays posts with title, description, date, tags
-  - Posts sorted by date descending (newest first)
-  - Tag.astro renders tags as links or badges based on variant prop
-  - Hover states applied to post titles
-  </done>
-</thread>
-
-<thread type="checkpoint:human-verify" gate="blocking">
-  <what-built>
-  Complete blog content system with:
-  - Content collection schema (src/content/config.ts)
-  - Sample blog post (src/content/blog/sample-post.md)
-  - Dynamic post template ([slug].astro)
-  - PostList component (reusable post listing)
-  - Tag component (link and badge variants)
-  </what-built>
-  <how-to-verify>
-  1. cd /Users/jacweath/grid/blog && npm run dev
-  2. Visit http://localhost:4321/blog/sample-post
-  3. Check post page:
-     - Title displays correctly
-     - Date shows formatted (e.g., "January 23, 2024")
-     - Tags appear as badges or links
-     - Markdown content renders properly
-     - Code blocks have syntax highlighting (colors visible)
-     - Dark mode: check prose-invert class applies (text readable on dark bg)
-  4. Check browser console for errors (should be none)
-  5. Run: npm run build
-     - Build should complete successfully
-     - Check: npx astro check (no content schema errors)
-  6. Create test listing page:
-     - Add src/pages/blog/index.astro using PostList component
-     - Visit http://localhost:4321/blog
-     - Sample post appears in list
-  </how-to-verify>
-  <resume-signal>Type "approved" if content renders correctly and schema validates, or describe issues (e.g., "highlighting broken", "schema error", "tags not visible")</resume-signal>
-</thread>
-
-</threads>
-
-<verification>
-Complete verification checklist:
-1. src/content/config.ts defines blog collection with zod schema
-2. Schema includes all required fields (title, description, pubDate, tags, draft)
-3. src/content/blog/sample-post.md exists with valid frontmatter
-4. src/pages/blog/[slug].astro implements getStaticPaths correctly
-5. Dynamic route filters out draft posts
-6. Post template renders content with prose typography
-7. Syntax highlighting works in code blocks
-8. PostList.astro sorts posts by date (newest first)
-9. Tag.astro supports 'link' and 'badge' variants
-10. npm run build completes successfully
-11. npx astro check passes with no errors
-12. User approves content rendering and functionality
-</verification>
-
-<success_criteria>
-- Content collection configured with type-safe schema
-- Sample blog post renders at /blog/sample-post
-- Frontmatter data displays correctly (title, date, tags)
-- Markdown content styled with typography plugin
-- Syntax highlighting functional
-- PostList and Tag components work correctly
-- Build succeeds with no content validation errors
-- User approves rendering and functionality
-</success_criteria>