🔱 Getting Started with BOB-Astro v0.1.0

“कर्मण्येवाधिकारस्ते मा फलेषु कदाचन।
मा कर्मफलहेतुर्भूर्मा ते सङ्गोऽस्त्वकर्मणि॥”
You have a right to perform your prescribed duty, but you are not entitled to the fruits of action. Never consider yourself the cause of the results of your activities, and never be attached to not doing your duty.
— श्रीमद्भगवद्गीता (Bhagavad Gītā 2.47)

Welcome to BOB-Astro v0.1.0 (Break Ordinary Boundaries of Astro) — the sovereign, agent-native web substrate. Engineered with Astro 7.4, Tailwind CSS v4, Lenis 1.3, and 100% pure static edge architecture, BOB-Astro is designed to be the ultimate starting canvas for students, human builders, and autonomous AI coding agents.

Whether you are a university student building your first 10,000-page content blog, an indie founder launching a high-ticket SaaS platform, an e-commerce craftsman building a decoupled headless storefront, or an autonomous AI agent generating an Awwwards-tier agency flagship in under 3 minutes — BOB-Astro provides an uncompromising, pure static, zero-cost edge foundation.

---

1. Quickstart & Installation

You can initialize a new sovereign digital experience in seconds:

# Option A: Clone the public repository
git clone https://github.com/div197/BOB-Astro.git my-sovereign-site
cd my-sovereign-site

# Option B: Use the GitHub Template feature
# Navigate to https://github.com/div197/BOB-Astro and click "Use this template"

# Install dependencies (zero unnecessary external bloat)
npm install

# Run the 10-Gate Cloudflare Pages Purity Audit
npm run test:static

# Run the local development server (http://localhost:4321)
npm run dev

---

2. Autonomous Single-File Customization Contract

BOB-Astro strictly enforces the Zero-Hardcoding Principle. You never need to hunt through dozens of .astro, .tsx, or .css files to change brand names, logos, colors, navigation, or SEO tags. Everything is commanded through a single typed configuration file:

📁 src/config/site.config.ts:

export const siteConfig: SiteConfig = {
  brand: {
    name: 'NEXUS ARCHITECTURE',
    ticker: 'NEXUS//01',
    tagline: 'High-Concept Architectural Studio',
    badge: '100% STATIC EDGE',
    domain: 'https://nexus.pages.dev',
    // ...
  },
  theme: {
    palette: {
      accentPrimary: 'oklch(0.78 0.17 150)', // Cyber Emerald
      // ...
    }
  }
};

Mathematical OKLCH Palette Presets Out of the Box:

1. Solar Amber (amber): oklch(0.82 0.16 85) — Radiant, warm, commanding editorial authority.
2. Cyber Emerald (emerald): oklch(0.78 0.17 150) — High-tech, cryptographic, terminal precision.
3. Deep Cobalt (cobalt): oklch(0.70 0.19 250) — Sovereign, enterprise-grade, institutional trust.
4. Cosmic Crimson (crimson): oklch(0.68 0.22 25) — Bold, dynamic, visceral creative energy.
5. Quantum Violet (violet): oklch(0.72 0.20 300) — Deep tech, synthetic intelligence, ethereal luxury.
6. Solar Paper (paper): oklch(0.97 0.01 90) — Archival gallery register with tactile warm-light contrast.

Modifying site.config.ts cascades at build-time to your <head> SEO metadata, OpenGraph cards, JSON-LD schemas, header logo, ticker, mega-menus, hero headlines, footer dispatch, and CSS variables with mathematical consistency.

---

3. The Four Sovereign Builder Archetypes

BOB-Astro is not a rigid boilerplate; it is an adaptable foundation engineered to power four distinct production archetypes:

                                  ┌───────────────────────────────┐
                                  │   BOB-ASTRO v0.1.0 SUBSTRATE   │
                                  │ Astro 7.4 + Tailwind 4 + Edge │
                                  └───────────────┬───────────────┘
                                                  │
                 ┌────────────────┬───────────────┴───────────────┬────────────────┐
                 │                │                               │                │
                 ▼                ▼                               ▼                ▼
         📚 ARCHETYPE 1   🛍️ ARCHETYPE 2                  🚀 ARCHETYPE 3   🎨 ARCHETYPE 4
           10,000-PAGE      DECOUPLED                       HIGH-TICKET      LUXURY AGENCY
          STATIC BLOG      STOREFRONT                      SAAS PLATFORM       PORTFOLIO

📚 Archetype 1: 10,000-Page Content Blogs & Digital Gardens

For students, researchers, publication houses, and high-volume SEO publishers.

• Zero Cloud Costs: Host 10,000+ markdown/MDX articles on Cloudflare Pages free tier with $0 server or database costs and unlimited edge bandwidth.
• Astro 7 Content Layer: Backed by Rust Sätteri compiler and Vite 8 for blazing incremental builds under seconds.
• Search & Navigation: Integrated ⌘K Command Palette for fuzzy search across articles, automatic reading time computation, hardware-accelerated reading progress bar (ScrollProgressBar.astro), and dynamic Table of Contents.
• SEO & Discoverability: Automatic Schema.org BlogPosting and Article JSON-LD structured data, RSS 2.0 feed (/rss.xml), and dynamic sitemap index (/sitemap-index.xml).

🛍️ Archetype 2: Decoupled Headless E-Commerce Storefronts

For brands and craftsmen selling products, digital assets, or bespoke commissions.

• Decoupled Architecture: Connect seamlessly to headless backends including Medusa v2, Shopify Storefront API, or Stripe Checkout.
• Craft Shopping Primitives:
  • DrawerModal.astro: Silky 60fps sliding slide-over cart drawer that operates without heavy SPA frameworks.
  • SpotlightCard.astro & TiltCard.astro: Interactive, 3D-angled product showcase cards with specular lighting.
  • ClipImageReveal.astro: Hardware-accelerated gallery zooms and editorial crop reveals.
  • AudioHaptics.astro: Emil Kowalski Web Audio tactile micro-clicks on “Add to Cart” and checkout triggers.
  • Toast.astro: Zero-layout-shift notifications for cart updates and order confirmations.
• Static Edge Delivery: Pre-render product catalogs statically at the edge for sub-15ms TTFB, hydrating only dynamic cart state via lightweight client islands.

🚀 Archetype 3: High-Ticket SaaS & Startup Platforms

For software platforms, API providers, enterprise tools, and autonomous agent infrastructure.

• Conversion-Tuned Architecture:
  • PricingTable.astro: Tiered interactive pricing matrix featuring monthly/annual billing toggle, highlighted enterprise tier, feature comparison checkmarks, and ROI badges.
  • Accordion.astro: Schema.org FAQPage JSON-LD rich snippet integration for dominating Google search results.
  • Header.astro: Smart auto-hide header with dynamic CTA buttons, multi-tier mega-menus, and keyboard shortcut indicators.
• Machine-Readable Agent Context: Statically pre-rendered /llms.txt, /llms-full.txt, /api/manifest, and /api/health enabling AI agents and crawlers to understand your product instantly.

🎨 Archetype 4: Luxury Editorial & Creative Agency Flagships

For architectural studios, design agencies, photographers, and creative directors.

• Awwwards Jury 8.0+ Standards:
  • SmoothScroll.astro: Sustained 60fps kinetic scrolling powered by Lenis 1.3, synchronized with browser frame budgets.
  • SignatureCanvas.astro: Mathematical Fibonacci particle constellation ($\phi = 1.618$) that auto-pauses off-screen to preserve 100% CPU/GPU resources.
  • CustomCursor.astro: Smooth trailing halo pointer with magnetizing hover interactions.
  • NoiseOverlay.astro: Procedural SVG fractal film grain eliminating flat digital plastic looks.
  • MaskedReveal.astro: Staggered word reveals with zero Cumulative Layout Shift (CLS = 0) and full prefers-reduced-motion accessibility fallbacks.

---

4. The 34 Supreme Craft Primitives

BOB-Astro ships with 34 production-ready craft primitives located in src/components/craft/:

Category	Primitives
Motion & Scroll	SmoothScroll (Lenis 1.3), ScrollProgressBar, FloatingBackToTop, MaskedReveal
Surfaces & Cards	SpotlightCard, TiltCard, Card, ContainerLines, CornerDiagonals, NoiseOverlay
Interactive Canvases	SignatureCanvas ($\phi=1.618$), OklchLab (Dynamic Color Synthesizer)
Media & Visuals	ClipImageReveal, ProjectShowcase, CustomCursor, Shimmer
Typography & Numbers	TextScramble, CountUp, NumberDetail, SectionHeader, BadgePill
UI Components	Accordion (FAQ), Tabs, Breadcrumb (Schema.org), Pagination, Divider
Feedback & Modals	DrawerModal, Toast, CommandPalette (⌘K), KeyboardShortcutsModal (?), AccessibilityModal (Alt+A)
Audio & Telemetry	AudioHaptics (Emil Kowalski Web Audio), TelemetryHud (Alt+T)
Conversion & Commercial	PricingTable (Annual/Monthly SaaS Matrix), TerminalWindow (CLI & Code Preview)

---

5. Verification Suite & Cloudflare Edge Compliance

Always verify system purity before deployment. BOB-Astro includes both static architecture audits and automated end-to-end headless browser regression tests:

# 1. Astro & TypeScript Diagnostics (0 errors, 0 warnings, 0 hints)
npm run check

# 2. 10-Gate Cloudflare Pages Static Edge Purity Audit
npm run test:static

# 3. Automated End-to-End Headless Browser Suite
npm run test:e2e

# 4. Compile static edge artifacts to dist/
npm run build

The 10 Automated Audit Gates:

1. Zero Worker Functions Check: Verifies zero runtime Workers in functions/.
2. Static Routes Config Check: Verifies public/_routes.json excludes all routes ("exclude": ["/*"]).
3. Security Headers & Edge Cache: Verifies HSTS, X-Frame-Options, CSP, and immutable caching.
4. Tailwind 4 & CSS Variable Purity: Verifies zero hardcoded hex colors in core styling.
5. Site Config Integrity: Verifies single-source-of-truth configuration consistency.
6. Build Output Static Verification: Verifies all pre-rendered HTML/JSON artifacts exist in dist/.
7. Performance & Resource Budgets: Verifies total CSS bundle is under 150KB.
8. Craft Primitives Integrity: Verifies all core craft components are intact.
9. Content Layer & Docs Verification: Verifies markdown manuals and Zod schemas compile cleanly.
10. CLI & Scaffolding Toolchain: Verifies executable permissions and functionality of ./bin/bob-astro.

---

6. One-Command Autonomous Scaffolding (npm run fork)

For developers and AI coding agents creating new client projects:

# Interactive Mode
npm run fork

# Non-Interactive Autonomous Mode
npm run fork -- \
  --name "KRONOS DYNAMICS" \
  --tagline "Autonomous Orbital Computing Infrastructure" \
  --author "Kronos Global Ltd" \
  --url "https://kronos.pages.dev" \
  --palette emerald \
  --detach-git

This re-brands the site, configures the OKLCH palette, creates a fresh virgin git commit, and verifies that all 10 gates pass.

---

7. Deploying to Cloudflare Pages

Push your repository to GitHub and connect it to Cloudflare Pages, or deploy instantly via Wrangler:

npm run deploy

• Framework Preset: None (Static HTML / Astro)
• Build Command: npm run build
• Build Output Directory: dist
• Node.js Version: >= 18.20.8 (Recommended: Node 20+)
• Monthly Cost: $0.00 on Cloudflare Pages free tier with zero cold start.