refactor: implement comprehensive documentation framework

.claude/docs/augur-architecture.md

@@ -0,0 +1,54 @@
+## Project Overview
+Astro-based teaser website for the Augur prediction market reboot. Retro-futuristic landing page with CRT-style animations, deployed on GitHub Pages with React components for interactivity.
+
+**Key Feature**: Real-time fork risk monitoring system displaying Augur v2 protocol fork risk based on active dispute bonds. Features automated blockchain data collection, interactive gauge visualization, and development demo modes.
+
+## Tech Stack
+- **Astro 5.10+** - Static site generator with component islands
+- **React 19** - For interactive components (client-side hydration)
+- **Tailwind CSS 4.1** - CSS-first styling approach via `@tailwindcss/vite` plugin
+- **Wrangler** - Cloudflare deployment tooling
+- **Cloudflare Workers** - Static hosting with edge functions
+- **GitHub & GitHub Pages** - Version control and primary deployment environment
+
+## Codebase Structure
+```
+├── src/
+│   ├── styles/                  # Global styles
+│   │   └── global.css           # Tailwind configuration
+│   ├── components/              # All UI components
+│   │   ├── *.astro              # Server-rendered static components
+│   │   ├── *.tsx                # Client-interactive components
+│   │   └── [COMPONENT_GROUP]    # Complex component grouped in it's own folder
+│   │       ├── *.astro          # Server-rendered static components
+│   │       └── *.tsx            # Client-interactive components
+│   ├── providers/               # React Context providers
+│   ├── scripts/                 # Backend scripts
+│   ├── stores/                  # Nanostores global state management
+│   ├── assets/                  # Static resources (SVGs, images)
+│   ├── lib/                     # Shared utilities and helper functions
+│   ├── layouts/                 # Page layout components
+│   └── pages/                   # Route definitions and page components
+├── .github/
+│   └── workflows/               # GitHub Actions CI/CD
+│       └── *.yml                # GitHub Actions definition file 
+├── public/                      # Static files served directly
+│   └── data/                    # Generated files or publicly available data
+├── contracts/                   # Smart contract definitions
+│   └── augur-abis.json          # Augur v2 contract ABIs
+└── .workbench/                  # Development worktrees (gitignored)
+```
+
+## Environments
+- **Production Deployment**: GitHub Pages (static) - main branch auto-deploys to https://augur.net
+- **Staging Environment**: Cloudflare Workers via Astro plugin
+- **Dev Server**: Defaults to localhost:4321
+
+## CI/CD Pipeline Architecture
+GitHub Actions workflow (`build-and-deploy.yml`):
+1. **Trigger**: Push to main branch or hourly cron
+2. **Data Collection**: Runs `calculate-fork-risk.ts` with RPC failover
+3. **Build**: Astro static site generation with fork risk data
+4. **Deploy**: Automated deployment to GitHub Pages
+5. **Monitoring**: Hourly updates ensure fresh fork risk data
+

.claude/docs/augur-component-patterns.md

@@ -0,0 +1,60 @@
+# Component Patterns
+
+## Project-Specific Component Patterns
+This document covers component organization and patterns specific to the Augur project's retro-futuristic interface.
+
+## Animation Patterns
+
+### CRT-Style Effects
+Components use CSS keyframes for authentic monitor simulation:
+- Power-on sequences with scan line reveals
+- Flicker effects for damaged terminal aesthetics
+- Glow transitions for interactive states
+
+### Typewriter Animation System
+Text revelation follows terminal-style patterns:
+- Character-by-character reveals for authenticity
+- Configurable typing speeds for different content types
+- Cursor blink integration during active typing
+
+### Background Animation Architecture
+The PerspectiveGridTunnel component creates the signature 3D grid effect:
+- WebGL-based perspective rendering
+- Smooth animation loops without performance degradation
+- Responsive scaling across viewport sizes
+
+## WebGL & Resource Management
+**ALWAYS** implement proper dispose() methods for WebGL resources (buffers, programs, shaders)
+**MUST** call dispose() in React component cleanup effects to prevent GPU memory leaks
+**NEVER** render after disposal - add isDisposed guards in render methods
+
+## Interactive Component Patterns
+
+### Terminal Interface Components
+Components that simulate command-line interfaces:
+- Prompt styling with authentic cursor positioning
+- Input validation with terminal-style error messages
+- Command history and autocomplete behaviors
+
+### CRT Display Components
+Components that simulate monitor hardware:
+- Screen bezel effects and rounded corners
+- Refresh rate simulation through subtle animations
+- Power state transitions (on/off sequences)
+
+## Complex Component Organization
+
+### Fork Risk Monitoring System
+Hierarchical component organization:
+```
+ForkMonitor (main container)
+├── ForkDisplay (layout orchestrator)
+│   ├── ForkGauge (SVG visualization)
+│   └── ForkStats (data panels)
+├── ForkControls (development tools)
+└── ForkBadge (status indicator)
+
+Data Flow:
+ForkDataProvider → ForkRiskContext → Components
+ForkMockProvider → DemoContext → Components (dev mode)
+```

.claude/docs/augur-development-guidelines.md

@@ -0,0 +1,95 @@
+# Development Guidelines
+
+## Rules & Recommendations
+
+**MUST** read `.claude/docs/augur-architecture.md` prior to any development work
+**MUST** create development worktrees in `.workbench` directory for isolated feature development
+**ALWAYS** use descriptive branch names: `feature-name`, `fix-issue`, `workflow-enhancements`
+**NEVER** commit work nor push changes in `main` branch
+**ALWAYS** run `npm run cf-typegen` when changing `wrangler.jsonc` file
+
+## Source Code Navigation
+Use `.claude/docs/augur-architecture.md` as reference to understand tech stack and codebase structure
+Use `git ls-files` or similar tools to understand codebase structure
+
+## Development Workflow
+
+### 1. Issue Assessment
+- Check if GitHub issue has a linked PR
+- Review issue requirements and acceptance criteria
+- Identify related documentation and component patterns
+
+### 2. Worktree Setup
+```bash
+# Create new worktree for feature/fix
+git worktree add .workbench/issue-123-feature-name -b issue-123-feature-name
+
+# Navigate to worktree
+cd .workbench/issue-123-feature-name
+
+# Verify location
+pwd  # Should show .workbench/issue-123-feature-name path
+```
+
+### 3. Development Process
+- Implement changes following architectural patterns
+- Test changes locally with `npm run dev`
+- Run quality checks: `npm run lint && npm run typecheck`
+- Ensure build succeeds: `npm run build`
+
+### 4. Commit and PR
+- Commit with conventional message format
+- Create PR with descriptive title and summary
+- Link PR to original issue
+
+## Build and Deployment Workflow
+
+### Local Testing
+```bash
+# Start development server
+npm run dev  # Access at localhost:4321
+
+# Test production build locally
+npm run build && npm run preview
+```
+
+### Pre-deployment Checks
+- Type checking: `npm run typecheck`
+- Linting: `npm run lint`
+- Production build: `npm run build`
+
+### Deployment Environments
+
+#### Staging (Cloudflare Workers)
+- Manual deployment: `npm run deploy`
+- Uses Cloudflare adapter for SSR testing
+- Preview environment before production
+
+#### Production (GitHub Pages)
+- **Automatic**: Push to `main` branch triggers deployment
+- **Manual**: GitHub Actions can be manually triggered
+- **URL**: https://augur.net
+
+### Deployment Verification
+- Verify build completed successfully
+- Check basic site functionality
+- Monitor for deployment errors
+
+## Development Commands
+
+**Core Development**
+| Command | Action |
+|---------|---------|
+| `npm run dev` | Start development server at localhost:4321 |
+| `npm run build` | Build production site to ./dist/ |
+| `npm run preview` | Preview production build locally with Cloudflare adapter |
+| `npm run deploy` | Deploy to Cloudflare Pages |
+| `npm run cf-typegen` | Generate Cloudflare Worker types |
+
+**Data & Risk Calculation**
+| Command | Action |
+|---------|---------|
+| `npm run build:fork-data` | Calculate fork risk data using TypeScript scripts |
+| `npm run typecheck` | Type-check all TypeScript files using project references |
+| `npm run lint` | Run Biome linter with tab indentation and single quotes |
+

.claude/docs/augur-styling-guidelines.md

@@ -0,0 +1,100 @@
+# Styling Guidelines
+
+## Design System Strategy
+
+### Retro-Futuristic Aesthetic Philosophy
+The visual language centers on CRT monitor simulation with authentic scan lines, glow effects, and terminal-style interactions. Design decisions prioritize atmospheric immersion over conventional usability patterns.
+
+### Color Strategy
+Primary palette derives from classic CRT phosphor colors with emphasis on green terminals and amber highlights. Glow effects use color-matched shadows to simulate authentic monitor bleeding.
+
+### Typography Approach
+Monospace fonts dominate the interface to reinforce terminal aesthetics. Text animations use typewriter effects rather than modern transitions to maintain period authenticity.
+
+## Tailwind CSS 4.1 Guidelines
+
+### CSS-First Philosophy
+All configuration lives in `src/styles/global.css` using native CSS syntax. No separate configuration files exist to maintain simplicity and avoid context switching between CSS and JavaScript.
+
+### @theme Directive Usage
+Use `@theme` for foundational design tokens:
+- Colors that need semantic naming
+- Spacing values specific to the grid system
+- Animation timing that affects multiple components
+
+### @utility Directive Strategy
+Create custom utilities for:
+- **Visual effects** that combine multiple CSS properties (`fx-glow`, `fx-scanlines`)
+- **Layout patterns** used across 3+ components
+- **Animation presets** that maintain design consistency
+
+Avoid utilities for:
+- Single-property shortcuts already covered by Tailwind
+- Component-specific styles that won't be reused
+- Complex animations better handled in component CSS
+
+## Custom Utility Creation
+
+### Naming Conventions
+- **Effect utilities**: `fx-*` prefix for visual effects (`fx-glow`, `fx-box-glow`)
+- **Size variants**: Standard Tailwind suffixes (`-sm`, `-lg`, `-xl`)
+- **State variants**: Descriptive suffixes (`-active`, `-disabled`)
+
+### Organization Patterns
+Group related utilities in dedicated `@utility` blocks:
+```css
+@utility {
+  .fx-glow { /* base glow */ }
+  .fx-glow-sm { /* small variant */ }
+  .fx-glow-lg { /* large variant */ }
+}
+```
+
+### Utility Scope Guidelines
+- **Global effects**: Terminal-wide animations, CRT artifacts
+- **Component effects**: Button glows, input focus states
+- **Interactive effects**: Hover states, transition presets
+
+## Visual Effect Patterns
+
+### Glow Effect Strategy
+CRT monitors naturally bleed light beyond character boundaries. Implement using:
+- Multiple box-shadow layers for depth
+- Color-matched shadows using CSS variables
+- Size variants for different interface elements
+
+### Scan Line Implementation
+Subtle horizontal lines simulate CRT refresh patterns:
+- Semi-transparent overlays using gradients
+- Animation optional for active states
+- Avoid overuse that impacts readability
+
+### Terminal Aesthetics
+Maintain authentic computer terminal feel:
+- High contrast text on dark backgrounds
+- Cursor blink animations for active inputs
+- Typewriter text reveals for dynamic content
+
+## Component Styling Approach
+
+### Scoped vs Utility Balance
+- **Scoped styles**: Complex animations, component-specific layouts
+- **Utility classes**: Spacing, colors, common effects
+- **Custom utilities**: Cross-component visual patterns
+
+### Animation Strategy
+Prefer CSS keyframes over JavaScript animations for:
+- CRT power-on sequences
+- Text typing effects
+- Background grid animations
+
+Use JavaScript only for:
+- Complex timing coordination
+- User interaction responses
+- Dynamic value calculations
+
+### Responsive Design
+CRT aesthetic constrains responsive behavior:
+- Maintain terminal proportions across breakpoints
+- Scale effects proportionally, not linearly
+- Preserve readability at smaller sizes

.gitignore

@@ -54,3 +54,6 @@ public/data/fork-risk.json
 
 # TypeScript build cache
 .tscache/
+
+# Git Worktrees
+.workbench