From d4f391a3ec9c26d95fe0f3b7bc1583c5750941d2 Mon Sep 17 00:00:00 2001
From: ruben-cytonic <ruben@cytonic.com>
Date: Fri, 6 Feb 2026 13:50:17 +0000
Subject: [PATCH 1/2] feat: add SEO & AEO toolkit templates

Add new "seo" category with two framework-agnostic templates:
- AEO Toolkit: llms.txt, AI crawler management, structured data, citation tracking
- SEO Toolkit: metadata, sitemaps, Core Web Vitals, audit dashboard

Both use a monorepo architecture with adapters for Next.js, Nuxt, Astro, Remix, and Express.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md                |   6 +
 specs/seo/aeo-toolkit.md | 337 +++++++++++++++++++++++++++++++++++++
 specs/seo/seo-toolkit.md | 351 +++++++++++++++++++++++++++++++++++++++
 templates.json           |  23 +++
 4 files changed, 717 insertions(+)
 create mode 100644 specs/seo/aeo-toolkit.md
 create mode 100644 specs/seo/seo-toolkit.md

diff --git a/README.md b/README.md
index 5dc1323..df44968 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,12 @@ Ralph reads these specs and builds the entire project autonomously.
 |----------|-------------|------------|
 | [react-native-app](specs/mobile/react-native-app.md) | Cross-platform mobile app | Intermediate |
 
+### SEO & AEO
+| Template | Description | Difficulty |
+|----------|-------------|------------|
+| [aeo-toolkit](specs/seo/aeo-toolkit.md) | Answer Engine Optimization with llms.txt, AI crawlers, citations | Advanced |
+| [seo-toolkit](specs/seo/seo-toolkit.md) | Technical SEO with metadata, sitemaps, Core Web Vitals | Intermediate |
+
 ### Tools
 | Template | Description | Difficulty |
 |----------|-------------|------------|
diff --git a/specs/seo/aeo-toolkit.md b/specs/seo/aeo-toolkit.md
new file mode 100644
index 0000000..c675f76
--- /dev/null
+++ b/specs/seo/aeo-toolkit.md
@@ -0,0 +1,337 @@
+# AEO Toolkit — Answer Engine Optimization
+
+Build a framework-agnostic Answer Engine Optimization toolkit that makes any website fully discoverable by AI crawlers (GPTBot, ClaudeBot, PerplexityBot) and optimized for citation in AI-generated answers.
+
+## Overview
+
+A production-ready AEO (Answer Engine Optimization) toolkit shipped as a standalone Node.js package with framework adapters for Next.js, Nuxt, Astro, Remix, and Express. As AI-powered answer engines like ChatGPT, Perplexity, and Claude increasingly replace traditional search, websites need a new layer of optimization beyond classic SEO. This toolkit generates `llms.txt` / `llms-full.txt`, configures `robots.txt` with AI crawler directives, produces structured data (JSON-LD) tuned for answer extraction, ensures all critical content is server-rendered in HTML (AI crawlers don't execute JavaScript), and provides a monitoring dashboard to track AI bot traffic and citation performance.
+
+The core library is framework-agnostic — it generates plain text, markdown, XML, and JSON-LD strings. Framework adapters wire these generators into each framework's routing and middleware system. Inspired by the `llms.txt` standard (llmstxt.org), Firecrawl's crawling patterns, and Conductor's AI crawlability research.
+
+## Features
+
+- `llms.txt` and `llms-full.txt` auto-generation from site content map
+- `robots.txt` with granular AI crawler directives (GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot)
+- AI-optimized XML sitemap with priority scoring and `lastmod` timestamps
+- Server-side rendered (SSR) content layer — ensures critical content is in raw HTML, not behind JavaScript
+- Structured data engine: FAQ, Article, HowTo, Product, Organization, and BreadcrumbList schemas (JSON-LD)
+- Answer-first content formatting helpers (concise answer block above the fold, then detail)
+- Entity consistency checker — validates that brand names, product names, and key entities are consistent across pages
+- Authorship and freshness signals (author schema, datePublished, dateModified)
+- Markdown endpoint generator — serves `.md` versions of pages for LLM consumption (per llms.txt spec)
+- AI bot traffic monitoring dashboard — parses server/access logs to track GPTBot, ClaudeBot, PerplexityBot visits
+- Citation tracker — monitors when your content appears in AI answer engine results
+- Core Web Vitals monitoring integration
+- Framework adapters: Next.js, Nuxt, Astro, Remix, Express
+- CLI commands for auditing, generating, and validating all AEO artifacts
+
+## Tasks
+
+### Task 1: Core Library Setup
+
+- [ ] Initialize TypeScript monorepo with `packages/core`, `packages/cli`, and `packages/adapters/*`
+- [ ] Configure Turborepo or npm workspaces for package management
+- [ ] Set up `packages/core` with zero framework dependencies
+- [ ] Create `aeo.config.ts` schema with Zod (site metadata, crawler policies, content map)
+- [ ] Implement config loader that reads from project root
+- [ ] Install core dependencies (unified/remark for markdown, xml2js for XML)
+- [ ] Set up ESLint, Prettier, and Vitest
+
+### Task 2: robots.txt Generator
+
+- [ ] Create `generateRobotsTxt(config)` function in `packages/core/src/robots.ts`
+- [ ] Implement AI crawler directive builder with per-bot Allow/Disallow rules
+- [ ] Support configurable policies: allow-all, block-training-only, selective-access
+- [ ] Add known AI bot user-agents: GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot, Meta-ExternalAgent, Bytespider, Applebot-Extended
+- [ ] Include Sitemap directives pointing to both standard and AI sitemaps
+- [ ] Add Crawl-delay directives for aggressive bots
+- [ ] Write unit tests for all policy modes
+
+### Task 3: llms.txt and llms-full.txt Generator
+
+- [ ] Create `generateLlmsTxt(config)` function in `packages/core/src/llms-txt.ts`
+- [ ] Implement auto-generation from config site content map
+- [ ] Structure output per llmstxt.org spec: H1 title, blockquote summary, H2 sections with link lists
+- [ ] Create `generateLlmsFullTxt(config)` with comprehensive site documentation
+- [ ] Include company overview, product descriptions, target audience, competitive advantages
+- [ ] Add "Optional" section for secondary/supplementary pages
+- [ ] Add `lastUpdated` timestamp to both files
+- [ ] Write unit tests for output format validation
+
+### Task 4: AI-Optimized Sitemap
+
+- [ ] Create `generateSitemap(pages, config)` function in `packages/core/src/sitemap.ts`
+- [ ] Create `generateAISitemap(pages, config)` with AI-specific priority scoring
+- [ ] Implement priority calculation based on content type (landing pages > blog > archives)
+- [ ] Add `lastmod` timestamps from content metadata or git history
+- [ ] Add `changefreq` hints based on content volatility
+- [ ] Reference both sitemaps in robots.txt output
+- [ ] Write tests for XML output validity
+
+### Task 5: Structured Data Engine (JSON-LD)
+
+- [ ] Create `generateJsonLd(type, data)` function in `packages/core/src/structured-data.ts`
+- [ ] Implement Article schema (headline, author, datePublished, dateModified, publisher)
+- [ ] Implement FAQ schema (Question/Answer pairs for featured snippet targeting)
+- [ ] Implement HowTo schema (step-by-step content)
+- [ ] Implement Product schema (name, description, price, availability, reviews)
+- [ ] Implement Organization schema (name, logo, sameAs social profiles, contactPoint)
+- [ ] Implement BreadcrumbList schema for navigation hierarchy
+- [ ] Add schema validator that checks output against schema.org specs
+- [ ] Export framework-agnostic `<script type="application/ld+json">` string builder
+- [ ] Write tests for each schema type
+
+### Task 6: Bot Detection and SSR Middleware
+
+- [ ] Create `isAIBot(userAgent)` detector in `packages/core/src/bot-detector.ts`
+- [ ] Maintain user-agent pattern list for all known AI crawlers
+- [ ] Create `aeoMiddleware(config)` factory that returns a generic request handler
+- [ ] Middleware detects AI bots and sets `x-aeo-bot` header for downstream use
+- [ ] Implement HTML meta tag helper: `<meta name="robots" content="max-snippet:-1, max-image-preview:large">`
+- [ ] Add canonical URL generation utility
+- [ ] Write tests for bot detection accuracy
+
+### Task 7: Markdown Endpoint Generator
+
+- [ ] Create `htmlToMarkdown(html)` converter in `packages/core/src/markdown-endpoints.ts`
+- [ ] Strip navigation, footer, ads, and boilerplate — serve only core content
+- [ ] Add front-matter metadata (title, description, author, date) to markdown output
+- [ ] Create `markdownMiddleware(config)` that intercepts `.md` requests
+- [ ] Cache generated markdown with configurable TTL
+- [ ] Write tests for markdown output quality
+
+### Task 8: Answer-First Content Helpers
+
+- [ ] Create `formatAnswerBlock(answer, detail)` in `packages/core/src/content-helpers.ts`
+- [ ] Create `formatKeyFacts(facts)` — structured key-value pairs for easy extraction
+- [ ] Create `formatFAQ(items)` — FAQ with built-in JSON-LD generation
+- [ ] Implement `formatForExtraction(content)` — structures content with clear heading hierarchy
+- [ ] Export HTML string builders (framework-agnostic) for all helpers
+- [ ] Write tests for output format
+
+### Task 9: Entity Consistency Checker
+
+- [ ] Create entity registry schema in config (brand names, product names, key terms with canonical forms)
+- [ ] Build `checkEntities(files, config)` scanner in `packages/core/src/entity-checker.ts`
+- [ ] Flag variations (e.g., "Next.js" vs "NextJS" vs "Next JS")
+- [ ] Generate report with file locations and suggested fixes
+- [ ] Add pre-commit hook integration option
+- [ ] Write tests for detection accuracy
+
+### Task 10: AI Bot Traffic Monitor
+
+- [ ] Create log parser in `packages/core/src/bot-traffic.ts` that identifies AI bot user-agents
+- [ ] Support common log formats (Apache, Nginx, JSON logs)
+- [ ] Calculate bot visit frequency breakdown (GPTBot, ClaudeBot, PerplexityBot, etc.)
+- [ ] Track pages most frequently crawled by AI bots
+- [ ] Track crawl frequency trends over time (daily/weekly)
+- [ ] Add comparison: AI bot traffic vs Googlebot traffic
+- [ ] Implement alerting for crawl anomalies (sudden drops may indicate blocking issues)
+- [ ] Write tests for log parsing
+
+### Task 11: Citation Tracker
+
+- [ ] Create citation service in `packages/core/src/citation-tracker.ts`
+- [ ] Query Perplexity, ChatGPT search, and Google AI Overviews for brand mentions
+- [ ] Track which pages are cited and in response to which queries
+- [ ] Calculate "AI Share of Voice" metric
+- [ ] Show citation sentiment analysis (positive/neutral/negative)
+- [ ] Display citation trends over time
+- [ ] Write tests for citation parsing
+
+### Task 12: Framework Adapters
+
+- [ ] Create Next.js adapter in `packages/adapters/nextjs/` (route handlers for robots.txt, llms.txt, sitemaps; React components for JSON-LD; middleware)
+- [ ] Create Nuxt adapter in `packages/adapters/nuxt/` (server routes, Vue components, middleware)
+- [ ] Create Astro adapter in `packages/adapters/astro/` (API endpoints, Astro components, middleware)
+- [ ] Create Remix adapter in `packages/adapters/remix/` (resource routes, React components, middleware)
+- [ ] Create Express adapter in `packages/adapters/express/` (Express middleware and route handlers)
+- [ ] Each adapter wires core generators into the framework's routing system
+- [ ] Write integration tests for each adapter
+
+### Task 13: Dashboard UI
+
+- [ ] Build standalone dashboard as a single-page app in `packages/dashboard/`
+- [ ] Bot traffic overview page with visit frequency charts
+- [ ] Citation tracking page with AI Share of Voice
+- [ ] AEO health score page (robots.txt, llms.txt, structured data, SSR status)
+- [ ] Use Recharts for charts and Tailwind CSS for styling
+- [ ] Export as embeddable component and standalone server
+- [ ] Write tests for dashboard data rendering
+
+### Task 14: AEO Audit CLI
+
+- [ ] Create CLI entry point in `packages/cli/` with Commander.js
+- [ ] Implement `npx aeo audit <url>` — runs full AEO health check against any URL
+- [ ] Check robots.txt accessibility and AI bot directives
+- [ ] Validate llms.txt format against llmstxt.org spec
+- [ ] Verify structured data on all pages (JSON-LD validity)
+- [ ] Check that critical content is in static HTML (not JS-dependent)
+- [ ] Verify markdown endpoints are functional
+- [ ] Score site 0-100 with actionable recommendations
+- [ ] Output results as terminal table and optional JSON report
+- [ ] Write tests for audit logic
+
+## Tech Stack
+
+- TypeScript
+- Node.js 18+
+- Turborepo (monorepo management)
+- Zod (config validation)
+- Unified / Remark / Rehype (Markdown processing)
+- gray-matter (front-matter parsing)
+- xml2js (XML generation)
+- Commander.js (CLI)
+- Cheerio (HTML parsing for audits)
+- Recharts (dashboard charts)
+- Tailwind CSS (dashboard styling)
+- Vitest (testing)
+- Playwright (integration tests for SSR verification)
+
+### Framework Adapters Support
+
+- Next.js 14+ (App Router)
+- Nuxt 3+
+- Astro 4+
+- Remix 2+
+- Express 4+
+
+## Files to Create
+
+- `aeo.config.ts`
+- `packages/core/src/index.ts`
+- `packages/core/src/robots.ts`
+- `packages/core/src/llms-txt.ts`
+- `packages/core/src/sitemap.ts`
+- `packages/core/src/structured-data.ts`
+- `packages/core/src/bot-detector.ts`
+- `packages/core/src/markdown-endpoints.ts`
+- `packages/core/src/content-helpers.ts`
+- `packages/core/src/entity-checker.ts`
+- `packages/core/src/bot-traffic.ts`
+- `packages/core/src/citation-tracker.ts`
+- `packages/core/src/config.ts`
+- `packages/core/package.json`
+- `packages/cli/src/index.ts`
+- `packages/cli/src/audit.ts`
+- `packages/cli/package.json`
+- `packages/adapters/nextjs/src/index.ts`
+- `packages/adapters/nextjs/src/routes.ts`
+- `packages/adapters/nextjs/src/components.tsx`
+- `packages/adapters/nextjs/src/middleware.ts`
+- `packages/adapters/nextjs/package.json`
+- `packages/adapters/nuxt/src/index.ts`
+- `packages/adapters/nuxt/src/module.ts`
+- `packages/adapters/nuxt/package.json`
+- `packages/adapters/astro/src/index.ts`
+- `packages/adapters/astro/src/integration.ts`
+- `packages/adapters/astro/package.json`
+- `packages/adapters/remix/src/index.ts`
+- `packages/adapters/remix/src/routes.ts`
+- `packages/adapters/remix/package.json`
+- `packages/adapters/express/src/index.ts`
+- `packages/adapters/express/src/middleware.ts`
+- `packages/adapters/express/package.json`
+- `packages/dashboard/src/App.tsx`
+- `packages/dashboard/src/pages/traffic.tsx`
+- `packages/dashboard/src/pages/citations.tsx`
+- `packages/dashboard/src/pages/health.tsx`
+- `packages/dashboard/package.json`
+- `tests/core/robots.test.ts`
+- `tests/core/llms-txt.test.ts`
+- `tests/core/sitemap.test.ts`
+- `tests/core/structured-data.test.ts`
+- `tests/core/entity-checker.test.ts`
+- `tests/core/markdown-endpoints.test.ts`
+- `tests/core/bot-detector.test.ts`
+- `tests/cli/audit.test.ts`
+- `tests/adapters/nextjs.test.ts`
+- `tests/adapters/express.test.ts`
+- `turbo.json`
+- `package.json`
+- `.env.example`
+
+## Configuration
+
+### Environment Variables
+
+- `SITE_URL` — Canonical site URL (e.g., `https://example.com`)
+- `SITE_NAME` — Brand name used in structured data and llms.txt
+- `AEO_LOG_PATH` — Path to server access logs for bot traffic parsing
+- `PERPLEXITY_API_KEY` — (Optional) For citation tracking via Perplexity API
+- `OPENAI_API_KEY` — (Optional) For citation tracking via ChatGPT search
+
+### aeo.config.ts Example
+
+```typescript
+import { defineAEOConfig } from '@aeo-toolkit/core';
+
+export default defineAEOConfig({
+  site: {
+    name: 'My Company',
+    url: 'https://example.com',
+    description: 'Short description for llms.txt blockquote',
+  },
+  robots: {
+    policy: 'allow-all', // 'allow-all' | 'block-training' | 'selective'
+    customRules: [
+      { userAgent: 'GPTBot', disallow: ['/admin/', '/api/'] },
+    ],
+  },
+  llmsTxt: {
+    sections: [
+      { title: 'Documentation', pages: ['/docs', '/guides', '/api-reference'] },
+      { title: 'Blog', pages: ['/blog'] },
+    ],
+    optional: ['/changelog', '/careers'],
+  },
+  entities: {
+    'Next.js': ['NextJS', 'Next JS', 'Nextjs'],
+    'TypeScript': ['Typescript', 'TS'],
+  },
+  sitemap: {
+    priorities: {
+      '/': 1.0,
+      '/products/*': 0.9,
+      '/blog/*': 0.7,
+      '/docs/*': 0.8,
+    },
+  },
+});
+```
+
+### Framework Integration Examples
+
+```typescript
+// Next.js — app/robots.txt/route.ts
+import { createRobotsHandler } from '@aeo-toolkit/nextjs';
+export const GET = createRobotsHandler();
+
+// Express
+import { aeoMiddleware } from '@aeo-toolkit/express';
+app.use(aeoMiddleware()); // serves /robots.txt, /llms.txt, /sitemap.xml
+
+// Astro — src/pages/robots.txt.ts
+import { createRobotsEndpoint } from '@aeo-toolkit/astro';
+export const GET = createRobotsEndpoint();
+```
+
+## Usage
+
+1. Install: `npm install @aeo-toolkit/core @aeo-toolkit/<framework>`
+2. Create `aeo.config.ts` in your project root
+3. Wire framework adapter into your routes (see examples above)
+4. Run `npx aeo audit https://yoursite.com` for a full AEO health check
+5. Visit `/admin/aeo` for the monitoring dashboard (optional)
+
+## Notes
+
+- AI crawlers (GPTBot, ClaudeBot, PerplexityBot) do NOT execute JavaScript — all critical content must be in the initial HTML response
+- `llms.txt` is an emerging standard; no major AI company has formally adopted it yet, but implementing it is low-risk and future-proofs your site
+- `robots.txt` directives remain the primary and most reliable mechanism for AI crawler control
+- ChatGPT crawls ~8x more frequently than Googlebot; Perplexity ~3x more frequently (Conductor research)
+- First impression matters: AI bots lack manual reindexing — content must be correct on first crawl
+- The entity consistency checker helps avoid confusing AI models with inconsistent naming
+- Citation tracking requires API access to answer engines and may have rate limits
+- The core package has zero framework dependencies — adapters are optional
+- Requires Node.js 18+
diff --git a/specs/seo/seo-toolkit.md b/specs/seo/seo-toolkit.md
new file mode 100644
index 0000000..a073701
--- /dev/null
+++ b/specs/seo/seo-toolkit.md
@@ -0,0 +1,351 @@
+# SEO Toolkit — Technical SEO for Any Framework
+
+Build a framework-agnostic technical SEO toolkit covering metadata, structured data, sitemaps, performance monitoring, and on-page optimization with adapters for Next.js, Nuxt, Astro, Remix, and Express.
+
+## Overview
+
+A production-ready Technical SEO toolkit shipped as a standalone Node.js package with framework adapters. Covers every pillar of modern SEO: metadata management, Open Graph / Twitter Cards, canonical URLs, structured data (JSON-LD), XML sitemaps, RSS feeds, robots.txt, Core Web Vitals monitoring, image optimization auditing, internal linking analysis, and an SEO audit dashboard. The core library generates plain strings and objects with zero framework dependencies — adapters wire it into Next.js, Nuxt, Astro, Remix, or Express.
+
+While the AEO Toolkit focuses on AI answer engines, this toolkit targets traditional search engines (Google, Bing) and social platforms (Facebook, Twitter/X, LinkedIn) — though many optimizations benefit both.
+
+## Features
+
+- Dynamic metadata generation (title, description, OG, Twitter Cards, canonical, hreflang)
+- Open Graph and Twitter Card meta tag builders for every page
+- Canonical URL management and duplicate content prevention
+- XML sitemap generation with automatic page discovery
+- RSS / Atom feed generation for content pages
+- Dynamic `robots.txt` with per-section control
+- JSON-LD structured data (Article, Product, Organization, BreadcrumbList, LocalBusiness, WebSite with SearchAction)
+- Heading hierarchy validator (ensures proper H1 > H2 > H3 nesting)
+- Internal linking analyzer with orphan page detection
+- Image alt text auditor and optimization recommendations
+- Core Web Vitals tracker (LCP, INP, CLS) with web-vitals library
+- SEO audit dashboard with scoring and recommendations
+- Meta tag preview (Google SERP, Facebook, Twitter/X)
+- Redirect manager (301/302)
+- Hreflang tag generator for multi-language sites
+- Framework adapters: Next.js, Nuxt, Astro, Remix, Express
+- CLI for running audits, generating sitemaps, and checking broken links
+
+## Tasks
+
+### Task 1: Core Library Setup
+
+- [ ] Initialize TypeScript monorepo with `packages/core`, `packages/cli`, and `packages/adapters/*`
+- [ ] Configure Turborepo or npm workspaces for package management
+- [ ] Set up `packages/core` with zero framework dependencies
+- [ ] Create `seo.config.ts` schema with Zod (site metadata, defaults, social accounts)
+- [ ] Implement config loader that reads from project root
+- [ ] Install core dependencies (xml2js, feed, cheerio)
+- [ ] Set up ESLint, Prettier, and Vitest
+
+### Task 2: Metadata Engine
+
+- [ ] Create `generateMetaTags(page, config)` in `packages/core/src/metadata.ts`
+- [ ] Implement default metadata fallbacks from config
+- [ ] Add per-page title template support (`%s | Site Name`)
+- [ ] Generate Open Graph tags (og:title, og:description, og:image, og:url, og:type)
+- [ ] Generate Twitter Card tags (twitter:card, twitter:title, twitter:description, twitter:image)
+- [ ] Add canonical URL generation with automatic trailing slash normalization
+- [ ] Implement hreflang tag generation for multi-language pages
+- [ ] Return plain HTML string or structured object (adapter-agnostic)
+- [ ] Write tests for metadata output
+
+### Task 3: OG Image Generation
+
+- [ ] Create `generateOGImage(options)` in `packages/core/src/og-image.ts`
+- [ ] Use Satori for SVG-to-image rendering (framework-agnostic)
+- [ ] Create default OG image template with site branding
+- [ ] Support per-page customization (title, description, author, category)
+- [ ] Add blog post template with author avatar and reading time
+- [ ] Add product template with price and rating
+- [ ] Return PNG buffer for any HTTP framework to serve
+- [ ] Write tests for image generation
+
+### Task 4: Structured Data Engine (JSON-LD)
+
+- [ ] Create `generateJsonLd(type, data)` in `packages/core/src/structured-data.ts`
+- [ ] Implement WebSite schema with SearchAction (enables Google sitelinks search box)
+- [ ] Implement Organization schema (name, logo, sameAs, contactPoint)
+- [ ] Implement Article schema (headline, author, datePublished, dateModified, image)
+- [ ] Implement Product schema (name, description, offers, aggregateRating, review)
+- [ ] Implement BreadcrumbList schema from URL path segments
+- [ ] Implement LocalBusiness schema (address, geo, openingHours, telephone)
+- [ ] Implement FAQPage schema for FAQ sections
+- [ ] Add JSON-LD validator utility
+- [ ] Export `<script type="application/ld+json">` string builder
+- [ ] Write tests for each schema type
+
+### Task 5: XML Sitemap and RSS Feed
+
+- [ ] Create `generateSitemap(pages, config)` in `packages/core/src/sitemap.ts`
+- [ ] Support page list input (URL, lastmod, priority, changefreq)
+- [ ] Add `priority` and `changefreq` based on page depth and type
+- [ ] Create sitemap index generator for large sites (>50,000 URLs)
+- [ ] Create `generateRSSFeed(items, config)` in `packages/core/src/feed.ts`
+- [ ] Create `generateAtomFeed(items, config)` alongside RSS
+- [ ] Return XML strings for any HTTP framework to serve
+- [ ] Write tests for XML and feed validity
+
+### Task 6: robots.txt and Crawl Control
+
+- [ ] Create `generateRobotsTxt(config)` in `packages/core/src/robots.ts`
+- [ ] Support per-environment rules (block crawlers on staging/preview)
+- [ ] Add `Sitemap` directive
+- [ ] Create `createRedirectRules(redirects)` utility for 301/302 redirects
+- [ ] Add `noindex` meta tag helper for excluded pages
+- [ ] Implement `X-Robots-Tag` HTTP header helper
+- [ ] Write tests for robots output and redirect rules
+
+### Task 7: Core Web Vitals Collection
+
+- [ ] Create browser-side `collectVitals(callback)` in `packages/core/src/vitals.ts`
+- [ ] Integrate `web-vitals` library to capture LCP, INP, CLS, TTFB, FCP
+- [ ] Create `scoreVitals(data)` that grades against Google's thresholds
+- [ ] Define storage adapter interface (in-memory, PostgreSQL, analytics service)
+- [ ] Implement in-memory adapter for demo/development
+- [ ] Write tests for vitals scoring
+
+### Task 8: Image Audit
+
+- [ ] Create `auditImages(html)` in `packages/core/src/image-audit.ts`
+- [ ] Detect missing alt text on `<img>` tags
+- [ ] Flag generic alt text ("image", "photo", "screenshot", "untitled")
+- [ ] Check for missing `width`/`height` attributes (CLS risk)
+- [ ] Check for missing lazy loading on below-fold images
+- [ ] Generate image sitemap entries for pages with images
+- [ ] Write tests for detection accuracy
+
+### Task 9: Internal Linking Analyzer
+
+- [ ] Create `analyzeLinkGraph(pages)` in `packages/core/src/link-analyzer.ts`
+- [ ] Accept page list with extracted internal links
+- [ ] Build link graph (which pages link to which)
+- [ ] Detect orphan pages (no internal links pointing to them)
+- [ ] Calculate link depth (clicks from homepage)
+- [ ] Flag broken internal links (404s)
+- [ ] Generate report with recommendations
+- [ ] Write tests for graph analysis
+
+### Task 10: Heading Hierarchy Validator
+
+- [ ] Create `validateHeadings(html)` in `packages/core/src/heading-validator.ts`
+- [ ] Validate single H1 per page
+- [ ] Check for proper nesting (no H3 without preceding H2)
+- [ ] Flag empty headings and headings used only for styling
+- [ ] Return structured report with line numbers
+- [ ] Write tests for hierarchy validation
+
+### Task 11: Framework Adapters
+
+- [ ] Create Next.js adapter in `packages/adapters/nextjs/` (Metadata API helper, route handlers, React `<JsonLd>` component, middleware)
+- [ ] Create Nuxt adapter in `packages/adapters/nuxt/` (useHead composable, server routes, Vue `<JsonLd>` component)
+- [ ] Create Astro adapter in `packages/adapters/astro/` (API endpoints, Astro `<JsonLd>` component, integration)
+- [ ] Create Remix adapter in `packages/adapters/remix/` (meta function helper, resource routes, React `<JsonLd>` component)
+- [ ] Create Express adapter in `packages/adapters/express/` (middleware that serves robots.txt, sitemap, feeds, OG images)
+- [ ] Each adapter wraps core generators into framework-native patterns
+- [ ] Write integration tests for each adapter
+
+### Task 12: Dashboard and SERP Preview
+
+- [ ] Build standalone dashboard as SPA in `packages/dashboard/`
+- [ ] SEO score overview page (0-100 with category breakdown)
+- [ ] Core Web Vitals page with trend charts
+- [ ] Internal linking visualization
+- [ ] SERP preview page (Google, Facebook, Twitter/X with character warnings)
+- [ ] Use Recharts for charts and Tailwind CSS for styling
+- [ ] Export as embeddable component and standalone server
+- [ ] Write tests for dashboard rendering
+
+### Task 13: SEO Audit CLI
+
+- [ ] Create CLI entry point in `packages/cli/` with Commander.js
+- [ ] Implement `npx seo-toolkit audit <url>` — runs full audit against any URL
+- [ ] Check: meta tags, OG tags, canonical URLs, structured data, headings, images, links, robots.txt
+- [ ] Category scores: Metadata, Structured Data, Performance, Content, Crawlability
+- [ ] Implement `npx seo-toolkit check-links <url>` — broken link checker
+- [ ] Implement `npx seo-toolkit check-images <url>` — alt text auditor
+- [ ] Score site 0-100 with prioritized recommendations (critical, warning, info)
+- [ ] Output results as terminal table and optional JSON/HTML report
+- [ ] Write tests for scoring logic
+
+## Tech Stack
+
+- TypeScript
+- Node.js 18+
+- Turborepo (monorepo management)
+- Zod (config validation)
+- Satori (OG image generation)
+- web-vitals (Core Web Vitals)
+- Commander.js (CLI)
+- Cheerio (HTML parsing for audits)
+- xml2js (XML generation)
+- feed (RSS/Atom generation)
+- Recharts (dashboard charts)
+- Tailwind CSS (dashboard styling)
+- Vitest (testing)
+
+### Framework Adapters Support
+
+- Next.js 14+ (App Router)
+- Nuxt 3+
+- Astro 4+
+- Remix 2+
+- Express 4+
+
+## Files to Create
+
+- `seo.config.ts`
+- `packages/core/src/index.ts`
+- `packages/core/src/metadata.ts`
+- `packages/core/src/structured-data.ts`
+- `packages/core/src/sitemap.ts`
+- `packages/core/src/feed.ts`
+- `packages/core/src/robots.ts`
+- `packages/core/src/redirects.ts`
+- `packages/core/src/og-image.ts`
+- `packages/core/src/vitals.ts`
+- `packages/core/src/image-audit.ts`
+- `packages/core/src/link-analyzer.ts`
+- `packages/core/src/heading-validator.ts`
+- `packages/core/src/config.ts`
+- `packages/core/package.json`
+- `packages/cli/src/index.ts`
+- `packages/cli/src/audit.ts`
+- `packages/cli/src/check-links.ts`
+- `packages/cli/src/check-images.ts`
+- `packages/cli/package.json`
+- `packages/adapters/nextjs/src/index.ts`
+- `packages/adapters/nextjs/src/metadata.ts`
+- `packages/adapters/nextjs/src/routes.ts`
+- `packages/adapters/nextjs/src/components.tsx`
+- `packages/adapters/nextjs/src/middleware.ts`
+- `packages/adapters/nextjs/package.json`
+- `packages/adapters/nuxt/src/index.ts`
+- `packages/adapters/nuxt/src/module.ts`
+- `packages/adapters/nuxt/src/composables.ts`
+- `packages/adapters/nuxt/package.json`
+- `packages/adapters/astro/src/index.ts`
+- `packages/adapters/astro/src/integration.ts`
+- `packages/adapters/astro/src/components.ts`
+- `packages/adapters/astro/package.json`
+- `packages/adapters/remix/src/index.ts`
+- `packages/adapters/remix/src/routes.ts`
+- `packages/adapters/remix/src/meta.ts`
+- `packages/adapters/remix/package.json`
+- `packages/adapters/express/src/index.ts`
+- `packages/adapters/express/src/middleware.ts`
+- `packages/adapters/express/package.json`
+- `packages/dashboard/src/App.tsx`
+- `packages/dashboard/src/pages/overview.tsx`
+- `packages/dashboard/src/pages/vitals.tsx`
+- `packages/dashboard/src/pages/links.tsx`
+- `packages/dashboard/src/pages/preview.tsx`
+- `packages/dashboard/package.json`
+- `tests/core/metadata.test.ts`
+- `tests/core/structured-data.test.ts`
+- `tests/core/sitemap.test.ts`
+- `tests/core/robots.test.ts`
+- `tests/core/vitals.test.ts`
+- `tests/core/link-analyzer.test.ts`
+- `tests/core/heading-validator.test.ts`
+- `tests/core/image-audit.test.ts`
+- `tests/cli/audit.test.ts`
+- `tests/adapters/nextjs.test.ts`
+- `tests/adapters/express.test.ts`
+- `turbo.json`
+- `package.json`
+- `.env.example`
+
+## Configuration
+
+### Environment Variables
+
+- `SITE_URL` — Canonical site URL (e.g., `https://example.com`)
+- `SITE_NAME` — Site name for metadata and structured data
+- `SITE_DESCRIPTION` — Default meta description
+- `SITE_LOCALE` — Default locale (e.g., `en_US`)
+- `TWITTER_HANDLE` — Twitter/X handle for card attribution (e.g., `@mysite`)
+- `GA_MEASUREMENT_ID` — (Optional) Google Analytics ID for vitals reporting
+
+### seo.config.ts Example
+
+```typescript
+import { defineSEOConfig } from '@seo-toolkit/core';
+
+export default defineSEOConfig({
+  site: {
+    name: 'My Company',
+    url: 'https://example.com',
+    description: 'We build great software.',
+    locale: 'en_US',
+    twitter: '@mycompany',
+  },
+  metadata: {
+    titleTemplate: '%s | My Company',
+    defaultOgImage: '/og-default.png',
+  },
+  structuredData: {
+    organization: {
+      name: 'My Company',
+      logo: 'https://example.com/logo.png',
+      sameAs: [
+        'https://twitter.com/mycompany',
+        'https://linkedin.com/company/mycompany',
+        'https://github.com/mycompany',
+      ],
+    },
+  },
+  sitemap: {
+    exclude: ['/admin/*', '/api/*'],
+    priorities: {
+      '/': 1.0,
+      '/products/*': 0.9,
+      '/blog/*': 0.7,
+    },
+  },
+  redirects: [
+    { source: '/old-page', destination: '/new-page', permanent: true },
+  ],
+});
+```
+
+### Framework Integration Examples
+
+```typescript
+// Next.js — app/layout.tsx
+import { createMetadata } from '@seo-toolkit/nextjs';
+export const generateMetadata = createMetadata({ title: 'Home' });
+
+// Nuxt — nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@seo-toolkit/nuxt'],
+});
+
+// Express
+import { seoMiddleware } from '@seo-toolkit/express';
+app.use(seoMiddleware()); // serves /robots.txt, /sitemap.xml, /feed.xml
+
+// Astro — astro.config.mjs
+import seoToolkit from '@seo-toolkit/astro';
+export default defineConfig({ integrations: [seoToolkit()] });
+```
+
+## Usage
+
+1. Install: `npm install @seo-toolkit/core @seo-toolkit/<framework>`
+2. Create `seo.config.ts` in your project root
+3. Wire framework adapter into your routes (see examples above)
+4. Run `npx seo-toolkit audit https://yoursite.com` for a full SEO health check
+5. Visit `/admin/seo` for the audit dashboard (optional)
+
+## Notes
+
+- The OG image generator uses Satori (same engine as Vercel's `@vercel/og`) and works in any Node.js runtime
+- Core Web Vitals thresholds follow Google's 2024+ standards: LCP < 2.5s, CLS < 0.1, INP < 200ms
+- The internal link analyzer crawls pages at build time or on-demand — it does not run in production
+- For multi-language sites, configure `hreflang` mappings in `seo.config.ts`
+- Structured data is validated against schema.org specifications
+- The core package has zero framework dependencies — adapters are optional
+- Requires Node.js 18+
diff --git a/templates.json b/templates.json
index 9941842..d34f9d2 100644
--- a/templates.json
+++ b/templates.json
@@ -153,6 +153,24 @@
       "tags": ["chrome", "extension", "react", "typescript", "manifest-v3", "browser"],
       "difficulty": "intermediate",
       "path": "specs/tools/chrome-extension.md"
+    },
+    {
+      "id": "aeo-toolkit",
+      "name": "AEO Toolkit",
+      "description": "Build an Answer Engine Optimization toolkit with llms.txt, AI crawler management, structured data, and citation tracking.",
+      "category": "seo",
+      "tags": ["nextjs", "aeo", "llms-txt", "robots-txt", "structured-data", "ai-crawlers", "typescript"],
+      "difficulty": "advanced",
+      "path": "specs/seo/aeo-toolkit.md"
+    },
+    {
+      "id": "seo-toolkit",
+      "name": "SEO Toolkit",
+      "description": "Build a comprehensive technical SEO toolkit with metadata, sitemaps, Core Web Vitals, and audit dashboard.",
+      "category": "seo",
+      "tags": ["nextjs", "seo", "metadata", "sitemap", "structured-data", "core-web-vitals", "typescript"],
+      "difficulty": "intermediate",
+      "path": "specs/seo/seo-toolkit.md"
     }
   ],
   "categories": [
@@ -180,6 +198,11 @@
       "id": "tools",
       "name": "Tools",
       "description": "CLI tools and browser extensions"
+    },
+    {
+      "id": "seo",
+      "name": "SEO & AEO",
+      "description": "Search engine and answer engine optimization toolkits"
     }
   ]
 }

From 6fea8c69b097c083a65d429d08cfb9e5e706d040 Mon Sep 17 00:00:00 2001
From: ruben-cytonic <ruben@cytonic.com>
Date: Fri, 6 Feb 2026 14:18:08 +0000
Subject: [PATCH 2/2] refactor: slim down AEO and SEO specs

- Remove monorepo/adapter architecture, focus on core concepts
- Add framework auto-detection from package.json (ralph detects stack and generates matching code)
- Reduce file count from 50+ to ~15 per spec
- Remove nextjs tag from registry (specs are now framework-agnostic)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 specs/seo/aeo-toolkit.md | 366 ++++++++++----------------------------
 specs/seo/seo-toolkit.md | 373 ++++++++++-----------------------------
 templates.json           |   4 +-
 3 files changed, 193 insertions(+), 550 deletions(-)

diff --git a/specs/seo/aeo-toolkit.md b/specs/seo/aeo-toolkit.md
index c675f76..9a9b153 100644
--- a/specs/seo/aeo-toolkit.md
+++ b/specs/seo/aeo-toolkit.md
@@ -1,270 +1,132 @@
 # AEO Toolkit — Answer Engine Optimization
 
-Build a framework-agnostic Answer Engine Optimization toolkit that makes any website fully discoverable by AI crawlers (GPTBot, ClaudeBot, PerplexityBot) and optimized for citation in AI-generated answers.
+Build Answer Engine Optimization into an existing project so AI crawlers (GPTBot, ClaudeBot, PerplexityBot) can discover, parse, and cite the site's content.
 
 ## Overview
 
-A production-ready AEO (Answer Engine Optimization) toolkit shipped as a standalone Node.js package with framework adapters for Next.js, Nuxt, Astro, Remix, and Express. As AI-powered answer engines like ChatGPT, Perplexity, and Claude increasingly replace traditional search, websites need a new layer of optimization beyond classic SEO. This toolkit generates `llms.txt` / `llms-full.txt`, configures `robots.txt` with AI crawler directives, produces structured data (JSON-LD) tuned for answer extraction, ensures all critical content is server-rendered in HTML (AI crawlers don't execute JavaScript), and provides a monitoring dashboard to track AI bot traffic and citation performance.
+An AEO (Answer Engine Optimization) implementation that ralph drops into the user's existing project. Ralph first reads `package.json` to detect the framework (Next.js, Nuxt, Astro, Remix, Express, or static), then generates only the files that match that stack. The toolkit covers the core AEO primitives: `robots.txt` with AI crawler directives, `llms.txt` / `llms-full.txt` per the llmstxt.org spec, AI-optimized sitemaps, structured data (JSON-LD) tuned for answer extraction, and a CLI auditor that scores the site's AEO readiness.
 
-The core library is framework-agnostic — it generates plain text, markdown, XML, and JSON-LD strings. Framework adapters wire these generators into each framework's routing and middleware system. Inspired by the `llms.txt` standard (llmstxt.org), Firecrawl's crawling patterns, and Conductor's AI crawlability research.
+AI crawlers do not execute JavaScript — all critical content must be in the initial HTML response. This is the fundamental constraint the toolkit addresses.
 
 ## Features
 
-- `llms.txt` and `llms-full.txt` auto-generation from site content map
-- `robots.txt` with granular AI crawler directives (GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot)
-- AI-optimized XML sitemap with priority scoring and `lastmod` timestamps
-- Server-side rendered (SSR) content layer — ensures critical content is in raw HTML, not behind JavaScript
-- Structured data engine: FAQ, Article, HowTo, Product, Organization, and BreadcrumbList schemas (JSON-LD)
-- Answer-first content formatting helpers (concise answer block above the fold, then detail)
-- Entity consistency checker — validates that brand names, product names, and key entities are consistent across pages
-- Authorship and freshness signals (author schema, datePublished, dateModified)
-- Markdown endpoint generator — serves `.md` versions of pages for LLM consumption (per llms.txt spec)
-- AI bot traffic monitoring dashboard — parses server/access logs to track GPTBot, ClaudeBot, PerplexityBot visits
-- Citation tracker — monitors when your content appears in AI answer engine results
-- Core Web Vitals monitoring integration
-- Framework adapters: Next.js, Nuxt, Astro, Remix, Express
-- CLI commands for auditing, generating, and validating all AEO artifacts
+- Framework auto-detection from `package.json`
+- `robots.txt` with AI crawler directives (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot)
+- `llms.txt` and `llms-full.txt` generation per llmstxt.org spec
+- AI-optimized XML sitemap with priority scoring
+- JSON-LD structured data (Article, FAQ, HowTo, Product, Organization)
+- Bot detection middleware (identifies AI crawlers by user-agent)
+- Markdown endpoint support (`.md` versions of pages for LLM consumption)
+- AEO audit CLI that scores a site 0-100
+- Entity consistency checker
 
 ## Tasks
 
-### Task 1: Core Library Setup
-
-- [ ] Initialize TypeScript monorepo with `packages/core`, `packages/cli`, and `packages/adapters/*`
-- [ ] Configure Turborepo or npm workspaces for package management
-- [ ] Set up `packages/core` with zero framework dependencies
-- [ ] Create `aeo.config.ts` schema with Zod (site metadata, crawler policies, content map)
-- [ ] Implement config loader that reads from project root
-- [ ] Install core dependencies (unified/remark for markdown, xml2js for XML)
-- [ ] Set up ESLint, Prettier, and Vitest
-
-### Task 2: robots.txt Generator
-
-- [ ] Create `generateRobotsTxt(config)` function in `packages/core/src/robots.ts`
-- [ ] Implement AI crawler directive builder with per-bot Allow/Disallow rules
-- [ ] Support configurable policies: allow-all, block-training-only, selective-access
-- [ ] Add known AI bot user-agents: GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot, Meta-ExternalAgent, Bytespider, Applebot-Extended
-- [ ] Include Sitemap directives pointing to both standard and AI sitemaps
-- [ ] Add Crawl-delay directives for aggressive bots
-- [ ] Write unit tests for all policy modes
-
-### Task 3: llms.txt and llms-full.txt Generator
-
-- [ ] Create `generateLlmsTxt(config)` function in `packages/core/src/llms-txt.ts`
-- [ ] Implement auto-generation from config site content map
-- [ ] Structure output per llmstxt.org spec: H1 title, blockquote summary, H2 sections with link lists
-- [ ] Create `generateLlmsFullTxt(config)` with comprehensive site documentation
-- [ ] Include company overview, product descriptions, target audience, competitive advantages
-- [ ] Add "Optional" section for secondary/supplementary pages
-- [ ] Add `lastUpdated` timestamp to both files
-- [ ] Write unit tests for output format validation
+### Task 1: Detect Framework and Setup
+
+- [ ] Read `package.json` to detect framework (next, nuxt, astro, remix, express)
+- [ ] Create `aeo.config.ts` with Zod-validated schema (site name, URL, crawler policies)
+- [ ] Create `src/lib/aeo/` directory for core utilities
+- [ ] Install dependencies (zod, unified/remark, xml2js)
+
+### Task 2: robots.txt with AI Crawler Directives
+
+- [ ] Generate `robots.txt` using the detected framework's routing pattern
+- [ ] Include directives for: GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Google-Extended, CCBot, Meta-ExternalAgent, Bytespider, Applebot-Extended
+- [ ] Support three policies via config: `allow-all`, `block-training`, `selective`
+- [ ] Add Sitemap and Crawl-delay directives
+- [ ] Write tests
+
+### Task 3: llms.txt and llms-full.txt
+
+- [ ] Generate `llms.txt` from config content map (H1 title, blockquote summary, H2 link sections)
+- [ ] Generate `llms-full.txt` with full site documentation (company overview, products, audience)
+- [ ] Serve both files via the framework's routing system
+- [ ] Add `lastUpdated` timestamp
+- [ ] Write tests
 
 ### Task 4: AI-Optimized Sitemap
 
-- [ ] Create `generateSitemap(pages, config)` function in `packages/core/src/sitemap.ts`
-- [ ] Create `generateAISitemap(pages, config)` with AI-specific priority scoring
-- [ ] Implement priority calculation based on content type (landing pages > blog > archives)
-- [ ] Add `lastmod` timestamps from content metadata or git history
-- [ ] Add `changefreq` hints based on content volatility
-- [ ] Reference both sitemaps in robots.txt output
-- [ ] Write tests for XML output validity
-
-### Task 5: Structured Data Engine (JSON-LD)
-
-- [ ] Create `generateJsonLd(type, data)` function in `packages/core/src/structured-data.ts`
-- [ ] Implement Article schema (headline, author, datePublished, dateModified, publisher)
-- [ ] Implement FAQ schema (Question/Answer pairs for featured snippet targeting)
-- [ ] Implement HowTo schema (step-by-step content)
-- [ ] Implement Product schema (name, description, price, availability, reviews)
-- [ ] Implement Organization schema (name, logo, sameAs social profiles, contactPoint)
-- [ ] Implement BreadcrumbList schema for navigation hierarchy
-- [ ] Add schema validator that checks output against schema.org specs
-- [ ] Export framework-agnostic `<script type="application/ld+json">` string builder
+- [ ] Generate XML sitemap with priority scoring (landing pages > docs > blog > archives)
+- [ ] Add `lastmod` timestamps and `changefreq` hints
+- [ ] Reference sitemap in robots.txt
+- [ ] Write tests
+
+### Task 5: Structured Data (JSON-LD)
+
+- [ ] Create JSON-LD generator functions: Article, FAQ, HowTo, Product, Organization, BreadcrumbList
+- [ ] Create component/helper to inject `<script type="application/ld+json">` into pages
+- [ ] Add schema validator utility
 - [ ] Write tests for each schema type
 
-### Task 6: Bot Detection and SSR Middleware
+### Task 6: Bot Detection Middleware
 
-- [ ] Create `isAIBot(userAgent)` detector in `packages/core/src/bot-detector.ts`
-- [ ] Maintain user-agent pattern list for all known AI crawlers
-- [ ] Create `aeoMiddleware(config)` factory that returns a generic request handler
-- [ ] Middleware detects AI bots and sets `x-aeo-bot` header for downstream use
-- [ ] Implement HTML meta tag helper: `<meta name="robots" content="max-snippet:-1, max-image-preview:large">`
-- [ ] Add canonical URL generation utility
-- [ ] Write tests for bot detection accuracy
+- [ ] Create `isAIBot(userAgent)` utility with patterns for all known AI crawlers
+- [ ] Create middleware that tags AI bot requests (sets header or context flag)
+- [ ] Add HTML meta tags: `<meta name="robots" content="max-snippet:-1, max-image-preview:large">`
+- [ ] Add canonical URL helper
+- [ ] Write tests
 
-### Task 7: Markdown Endpoint Generator
+### Task 7: Markdown Endpoints
 
-- [ ] Create `htmlToMarkdown(html)` converter in `packages/core/src/markdown-endpoints.ts`
-- [ ] Strip navigation, footer, ads, and boilerplate — serve only core content
-- [ ] Add front-matter metadata (title, description, author, date) to markdown output
-- [ ] Create `markdownMiddleware(config)` that intercepts `.md` requests
-- [ ] Cache generated markdown with configurable TTL
-- [ ] Write tests for markdown output quality
+- [ ] Create middleware/route to serve `.md` versions of pages
+- [ ] Convert HTML to clean markdown (strip nav, footer, boilerplate)
+- [ ] Add front-matter metadata (title, description, date)
+- [ ] Write tests
 
-### Task 8: Answer-First Content Helpers
+### Task 8: AEO Audit CLI
 
-- [ ] Create `formatAnswerBlock(answer, detail)` in `packages/core/src/content-helpers.ts`
-- [ ] Create `formatKeyFacts(facts)` — structured key-value pairs for easy extraction
-- [ ] Create `formatFAQ(items)` — FAQ with built-in JSON-LD generation
-- [ ] Implement `formatForExtraction(content)` — structures content with clear heading hierarchy
-- [ ] Export HTML string builders (framework-agnostic) for all helpers
-- [ ] Write tests for output format
+- [ ] Create `scripts/aeo-audit.ts` runnable via `npx tsx scripts/aeo-audit.ts`
+- [ ] Check: robots.txt has AI bot directives, llms.txt exists and is valid, structured data present, critical content is in static HTML
+- [ ] Score 0-100 with actionable recommendations
+- [ ] Output as terminal table
+- [ ] Write tests
 
 ### Task 9: Entity Consistency Checker
 
-- [ ] Create entity registry schema in config (brand names, product names, key terms with canonical forms)
-- [ ] Build `checkEntities(files, config)` scanner in `packages/core/src/entity-checker.ts`
-- [ ] Flag variations (e.g., "Next.js" vs "NextJS" vs "Next JS")
-- [ ] Generate report with file locations and suggested fixes
-- [ ] Add pre-commit hook integration option
-- [ ] Write tests for detection accuracy
-
-### Task 10: AI Bot Traffic Monitor
-
-- [ ] Create log parser in `packages/core/src/bot-traffic.ts` that identifies AI bot user-agents
-- [ ] Support common log formats (Apache, Nginx, JSON logs)
-- [ ] Calculate bot visit frequency breakdown (GPTBot, ClaudeBot, PerplexityBot, etc.)
-- [ ] Track pages most frequently crawled by AI bots
-- [ ] Track crawl frequency trends over time (daily/weekly)
-- [ ] Add comparison: AI bot traffic vs Googlebot traffic
-- [ ] Implement alerting for crawl anomalies (sudden drops may indicate blocking issues)
-- [ ] Write tests for log parsing
-
-### Task 11: Citation Tracker
-
-- [ ] Create citation service in `packages/core/src/citation-tracker.ts`
-- [ ] Query Perplexity, ChatGPT search, and Google AI Overviews for brand mentions
-- [ ] Track which pages are cited and in response to which queries
-- [ ] Calculate "AI Share of Voice" metric
-- [ ] Show citation sentiment analysis (positive/neutral/negative)
-- [ ] Display citation trends over time
-- [ ] Write tests for citation parsing
-
-### Task 12: Framework Adapters
-
-- [ ] Create Next.js adapter in `packages/adapters/nextjs/` (route handlers for robots.txt, llms.txt, sitemaps; React components for JSON-LD; middleware)
-- [ ] Create Nuxt adapter in `packages/adapters/nuxt/` (server routes, Vue components, middleware)
-- [ ] Create Astro adapter in `packages/adapters/astro/` (API endpoints, Astro components, middleware)
-- [ ] Create Remix adapter in `packages/adapters/remix/` (resource routes, React components, middleware)
-- [ ] Create Express adapter in `packages/adapters/express/` (Express middleware and route handlers)
-- [ ] Each adapter wires core generators into the framework's routing system
-- [ ] Write integration tests for each adapter
-
-### Task 13: Dashboard UI
-
-- [ ] Build standalone dashboard as a single-page app in `packages/dashboard/`
-- [ ] Bot traffic overview page with visit frequency charts
-- [ ] Citation tracking page with AI Share of Voice
-- [ ] AEO health score page (robots.txt, llms.txt, structured data, SSR status)
-- [ ] Use Recharts for charts and Tailwind CSS for styling
-- [ ] Export as embeddable component and standalone server
-- [ ] Write tests for dashboard data rendering
-
-### Task 14: AEO Audit CLI
-
-- [ ] Create CLI entry point in `packages/cli/` with Commander.js
-- [ ] Implement `npx aeo audit <url>` — runs full AEO health check against any URL
-- [ ] Check robots.txt accessibility and AI bot directives
-- [ ] Validate llms.txt format against llmstxt.org spec
-- [ ] Verify structured data on all pages (JSON-LD validity)
-- [ ] Check that critical content is in static HTML (not JS-dependent)
-- [ ] Verify markdown endpoints are functional
-- [ ] Score site 0-100 with actionable recommendations
-- [ ] Output results as terminal table and optional JSON report
-- [ ] Write tests for audit logic
+- [ ] Define entity registry in config (brand names with canonical forms and variants)
+- [ ] Scan source files for inconsistent naming
+- [ ] Report with file locations and suggested fixes
+- [ ] Write tests
 
 ## Tech Stack
 
 - TypeScript
-- Node.js 18+
-- Turborepo (monorepo management)
 - Zod (config validation)
-- Unified / Remark / Rehype (Markdown processing)
-- gray-matter (front-matter parsing)
+- Unified / Remark (markdown processing)
 - xml2js (XML generation)
-- Commander.js (CLI)
-- Cheerio (HTML parsing for audits)
-- Recharts (dashboard charts)
-- Tailwind CSS (dashboard styling)
 - Vitest (testing)
-- Playwright (integration tests for SSR verification)
-
-### Framework Adapters Support
-
-- Next.js 14+ (App Router)
-- Nuxt 3+
-- Astro 4+
-- Remix 2+
-- Express 4+
+- Framework detected at generation time from `package.json`
 
 ## Files to Create
 
 - `aeo.config.ts`
-- `packages/core/src/index.ts`
-- `packages/core/src/robots.ts`
-- `packages/core/src/llms-txt.ts`
-- `packages/core/src/sitemap.ts`
-- `packages/core/src/structured-data.ts`
-- `packages/core/src/bot-detector.ts`
-- `packages/core/src/markdown-endpoints.ts`
-- `packages/core/src/content-helpers.ts`
-- `packages/core/src/entity-checker.ts`
-- `packages/core/src/bot-traffic.ts`
-- `packages/core/src/citation-tracker.ts`
-- `packages/core/src/config.ts`
-- `packages/core/package.json`
-- `packages/cli/src/index.ts`
-- `packages/cli/src/audit.ts`
-- `packages/cli/package.json`
-- `packages/adapters/nextjs/src/index.ts`
-- `packages/adapters/nextjs/src/routes.ts`
-- `packages/adapters/nextjs/src/components.tsx`
-- `packages/adapters/nextjs/src/middleware.ts`
-- `packages/adapters/nextjs/package.json`
-- `packages/adapters/nuxt/src/index.ts`
-- `packages/adapters/nuxt/src/module.ts`
-- `packages/adapters/nuxt/package.json`
-- `packages/adapters/astro/src/index.ts`
-- `packages/adapters/astro/src/integration.ts`
-- `packages/adapters/astro/package.json`
-- `packages/adapters/remix/src/index.ts`
-- `packages/adapters/remix/src/routes.ts`
-- `packages/adapters/remix/package.json`
-- `packages/adapters/express/src/index.ts`
-- `packages/adapters/express/src/middleware.ts`
-- `packages/adapters/express/package.json`
-- `packages/dashboard/src/App.tsx`
-- `packages/dashboard/src/pages/traffic.tsx`
-- `packages/dashboard/src/pages/citations.tsx`
-- `packages/dashboard/src/pages/health.tsx`
-- `packages/dashboard/package.json`
-- `tests/core/robots.test.ts`
-- `tests/core/llms-txt.test.ts`
-- `tests/core/sitemap.test.ts`
-- `tests/core/structured-data.test.ts`
-- `tests/core/entity-checker.test.ts`
-- `tests/core/markdown-endpoints.test.ts`
-- `tests/core/bot-detector.test.ts`
-- `tests/cli/audit.test.ts`
-- `tests/adapters/nextjs.test.ts`
-- `tests/adapters/express.test.ts`
-- `turbo.json`
-- `package.json`
-- `.env.example`
+- `src/lib/aeo/config.ts`
+- `src/lib/aeo/robots.ts`
+- `src/lib/aeo/llms-txt.ts`
+- `src/lib/aeo/sitemap.ts`
+- `src/lib/aeo/structured-data.ts`
+- `src/lib/aeo/bot-detector.ts`
+- `src/lib/aeo/markdown-endpoints.ts`
+- `src/lib/aeo/entity-checker.ts`
+- `scripts/aeo-audit.ts`
+- `tests/aeo/robots.test.ts`
+- `tests/aeo/llms-txt.test.ts`
+- `tests/aeo/structured-data.test.ts`
+- `tests/aeo/bot-detector.test.ts`
+- `tests/aeo/audit.test.ts`
+
+## Files to Modify
+
+- `package.json` — Add dependencies
+- Framework-specific routing files (detected at generation time) — Wire robots.txt, llms.txt, sitemap routes
 
 ## Configuration
 
-### Environment Variables
-
-- `SITE_URL` — Canonical site URL (e.g., `https://example.com`)
-- `SITE_NAME` — Brand name used in structured data and llms.txt
-- `AEO_LOG_PATH` — Path to server access logs for bot traffic parsing
-- `PERPLEXITY_API_KEY` — (Optional) For citation tracking via Perplexity API
-- `OPENAI_API_KEY` — (Optional) For citation tracking via ChatGPT search
-
-### aeo.config.ts Example
+### aeo.config.ts
 
 ```typescript
-import { defineAEOConfig } from '@aeo-toolkit/core';
+import { defineAEOConfig } from './src/lib/aeo/config';
 
 export default defineAEOConfig({
   site: {
@@ -274,64 +136,24 @@ export default defineAEOConfig({
   },
   robots: {
     policy: 'allow-all', // 'allow-all' | 'block-training' | 'selective'
-    customRules: [
-      { userAgent: 'GPTBot', disallow: ['/admin/', '/api/'] },
-    ],
   },
   llmsTxt: {
     sections: [
-      { title: 'Documentation', pages: ['/docs', '/guides', '/api-reference'] },
+      { title: 'Documentation', pages: ['/docs', '/guides'] },
       { title: 'Blog', pages: ['/blog'] },
     ],
-    optional: ['/changelog', '/careers'],
   },
   entities: {
     'Next.js': ['NextJS', 'Next JS', 'Nextjs'],
-    'TypeScript': ['Typescript', 'TS'],
-  },
-  sitemap: {
-    priorities: {
-      '/': 1.0,
-      '/products/*': 0.9,
-      '/blog/*': 0.7,
-      '/docs/*': 0.8,
-    },
   },
 });
 ```
 
-### Framework Integration Examples
-
-```typescript
-// Next.js — app/robots.txt/route.ts
-import { createRobotsHandler } from '@aeo-toolkit/nextjs';
-export const GET = createRobotsHandler();
-
-// Express
-import { aeoMiddleware } from '@aeo-toolkit/express';
-app.use(aeoMiddleware()); // serves /robots.txt, /llms.txt, /sitemap.xml
-
-// Astro — src/pages/robots.txt.ts
-import { createRobotsEndpoint } from '@aeo-toolkit/astro';
-export const GET = createRobotsEndpoint();
-```
-
-## Usage
-
-1. Install: `npm install @aeo-toolkit/core @aeo-toolkit/<framework>`
-2. Create `aeo.config.ts` in your project root
-3. Wire framework adapter into your routes (see examples above)
-4. Run `npx aeo audit https://yoursite.com` for a full AEO health check
-5. Visit `/admin/aeo` for the monitoring dashboard (optional)
-
 ## Notes
 
-- AI crawlers (GPTBot, ClaudeBot, PerplexityBot) do NOT execute JavaScript — all critical content must be in the initial HTML response
-- `llms.txt` is an emerging standard; no major AI company has formally adopted it yet, but implementing it is low-risk and future-proofs your site
-- `robots.txt` directives remain the primary and most reliable mechanism for AI crawler control
-- ChatGPT crawls ~8x more frequently than Googlebot; Perplexity ~3x more frequently (Conductor research)
-- First impression matters: AI bots lack manual reindexing — content must be correct on first crawl
-- The entity consistency checker helps avoid confusing AI models with inconsistent naming
-- Citation tracking requires API access to answer engines and may have rate limits
-- The core package has zero framework dependencies — adapters are optional
+- Ralph reads `package.json` to detect the framework and generates routes/middleware using that framework's patterns
+- AI crawlers do NOT execute JavaScript — all critical content must be in the initial HTML
+- `llms.txt` is an emerging standard (not yet formally adopted by major AI companies) but is low-risk to implement
+- `robots.txt` remains the primary mechanism for AI crawler control
+- ChatGPT crawls ~8x more than Googlebot; Perplexity ~3x (Conductor research)
 - Requires Node.js 18+
diff --git a/specs/seo/seo-toolkit.md b/specs/seo/seo-toolkit.md
index a073701..5c66704 100644
--- a/specs/seo/seo-toolkit.md
+++ b/specs/seo/seo-toolkit.md
@@ -1,278 +1,139 @@
-# SEO Toolkit — Technical SEO for Any Framework
+# SEO Toolkit — Technical SEO
 
-Build a framework-agnostic technical SEO toolkit covering metadata, structured data, sitemaps, performance monitoring, and on-page optimization with adapters for Next.js, Nuxt, Astro, Remix, and Express.
+Build technical SEO into an existing project covering metadata, structured data, sitemaps, performance monitoring, and on-page optimization.
 
 ## Overview
 
-A production-ready Technical SEO toolkit shipped as a standalone Node.js package with framework adapters. Covers every pillar of modern SEO: metadata management, Open Graph / Twitter Cards, canonical URLs, structured data (JSON-LD), XML sitemaps, RSS feeds, robots.txt, Core Web Vitals monitoring, image optimization auditing, internal linking analysis, and an SEO audit dashboard. The core library generates plain strings and objects with zero framework dependencies — adapters wire it into Next.js, Nuxt, Astro, Remix, or Express.
+A Technical SEO implementation that ralph drops into the user's existing project. Ralph first reads `package.json` to detect the framework (Next.js, Nuxt, Astro, Remix, Express, or static), then generates only the files that match that stack. Covers every pillar of modern SEO: metadata management, Open Graph / Twitter Cards, canonical URLs, structured data (JSON-LD), XML sitemaps, RSS feeds, robots.txt, and an SEO audit CLI that scores the site.
 
-While the AEO Toolkit focuses on AI answer engines, this toolkit targets traditional search engines (Google, Bing) and social platforms (Facebook, Twitter/X, LinkedIn) — though many optimizations benefit both.
+While the AEO Toolkit focuses on AI answer engines, this toolkit targets traditional search engines (Google, Bing) and social platforms (Facebook, Twitter/X, LinkedIn).
 
 ## Features
 
-- Dynamic metadata generation (title, description, OG, Twitter Cards, canonical, hreflang)
-- Open Graph and Twitter Card meta tag builders for every page
-- Canonical URL management and duplicate content prevention
-- XML sitemap generation with automatic page discovery
-- RSS / Atom feed generation for content pages
-- Dynamic `robots.txt` with per-section control
-- JSON-LD structured data (Article, Product, Organization, BreadcrumbList, LocalBusiness, WebSite with SearchAction)
-- Heading hierarchy validator (ensures proper H1 > H2 > H3 nesting)
+- Framework auto-detection from `package.json`
+- Metadata helpers (title templates, OG tags, Twitter Cards, canonical URLs, hreflang)
+- JSON-LD structured data (Article, Product, Organization, BreadcrumbList, LocalBusiness, FAQPage, WebSite with SearchAction)
+- XML sitemap generation
+- RSS / Atom feed generation
+- Dynamic `robots.txt`
+- Heading hierarchy validator
+- Image alt text auditor
 - Internal linking analyzer with orphan page detection
-- Image alt text auditor and optimization recommendations
-- Core Web Vitals tracker (LCP, INP, CLS) with web-vitals library
-- SEO audit dashboard with scoring and recommendations
-- Meta tag preview (Google SERP, Facebook, Twitter/X)
-- Redirect manager (301/302)
-- Hreflang tag generator for multi-language sites
-- Framework adapters: Next.js, Nuxt, Astro, Remix, Express
-- CLI for running audits, generating sitemaps, and checking broken links
+- SEO audit CLI that scores a site 0-100
 
 ## Tasks
 
-### Task 1: Core Library Setup
-
-- [ ] Initialize TypeScript monorepo with `packages/core`, `packages/cli`, and `packages/adapters/*`
-- [ ] Configure Turborepo or npm workspaces for package management
-- [ ] Set up `packages/core` with zero framework dependencies
-- [ ] Create `seo.config.ts` schema with Zod (site metadata, defaults, social accounts)
-- [ ] Implement config loader that reads from project root
-- [ ] Install core dependencies (xml2js, feed, cheerio)
-- [ ] Set up ESLint, Prettier, and Vitest
-
-### Task 2: Metadata Engine
-
-- [ ] Create `generateMetaTags(page, config)` in `packages/core/src/metadata.ts`
-- [ ] Implement default metadata fallbacks from config
-- [ ] Add per-page title template support (`%s | Site Name`)
-- [ ] Generate Open Graph tags (og:title, og:description, og:image, og:url, og:type)
-- [ ] Generate Twitter Card tags (twitter:card, twitter:title, twitter:description, twitter:image)
-- [ ] Add canonical URL generation with automatic trailing slash normalization
-- [ ] Implement hreflang tag generation for multi-language pages
-- [ ] Return plain HTML string or structured object (adapter-agnostic)
-- [ ] Write tests for metadata output
-
-### Task 3: OG Image Generation
-
-- [ ] Create `generateOGImage(options)` in `packages/core/src/og-image.ts`
-- [ ] Use Satori for SVG-to-image rendering (framework-agnostic)
-- [ ] Create default OG image template with site branding
-- [ ] Support per-page customization (title, description, author, category)
-- [ ] Add blog post template with author avatar and reading time
-- [ ] Add product template with price and rating
-- [ ] Return PNG buffer for any HTTP framework to serve
-- [ ] Write tests for image generation
-
-### Task 4: Structured Data Engine (JSON-LD)
-
-- [ ] Create `generateJsonLd(type, data)` in `packages/core/src/structured-data.ts`
-- [ ] Implement WebSite schema with SearchAction (enables Google sitelinks search box)
-- [ ] Implement Organization schema (name, logo, sameAs, contactPoint)
-- [ ] Implement Article schema (headline, author, datePublished, dateModified, image)
-- [ ] Implement Product schema (name, description, offers, aggregateRating, review)
-- [ ] Implement BreadcrumbList schema from URL path segments
-- [ ] Implement LocalBusiness schema (address, geo, openingHours, telephone)
-- [ ] Implement FAQPage schema for FAQ sections
+### Task 1: Detect Framework and Setup
+
+- [ ] Read `package.json` to detect framework (next, nuxt, astro, remix, express)
+- [ ] Create `seo.config.ts` with Zod-validated schema (site name, URL, social accounts, defaults)
+- [ ] Create `src/lib/seo/` directory for core utilities
+- [ ] Install dependencies (zod, xml2js, feed, cheerio)
+
+### Task 2: Metadata Helpers
+
+- [ ] Create `generateMetaTags(page, config)` that returns title, description, OG, and Twitter Card tags
+- [ ] Support title templates (`%s | Site Name`)
+- [ ] Add canonical URL generation with trailing slash normalization
+- [ ] Add hreflang generation for multi-language pages
+- [ ] Create framework-specific integration (Next.js Metadata API, Nuxt useHead, etc.)
+- [ ] Write tests
+
+### Task 3: Structured Data (JSON-LD)
+
+- [ ] Create JSON-LD generator functions: WebSite, Organization, Article, Product, BreadcrumbList, LocalBusiness, FAQPage
+- [ ] Create component/helper to inject `<script type="application/ld+json">` into pages
 - [ ] Add JSON-LD validator utility
-- [ ] Export `<script type="application/ld+json">` string builder
 - [ ] Write tests for each schema type
 
-### Task 5: XML Sitemap and RSS Feed
+### Task 4: XML Sitemap and RSS Feed
 
-- [ ] Create `generateSitemap(pages, config)` in `packages/core/src/sitemap.ts`
-- [ ] Support page list input (URL, lastmod, priority, changefreq)
-- [ ] Add `priority` and `changefreq` based on page depth and type
-- [ ] Create sitemap index generator for large sites (>50,000 URLs)
-- [ ] Create `generateRSSFeed(items, config)` in `packages/core/src/feed.ts`
-- [ ] Create `generateAtomFeed(items, config)` alongside RSS
-- [ ] Return XML strings for any HTTP framework to serve
-- [ ] Write tests for XML and feed validity
+- [ ] Generate XML sitemap with `lastmod`, `priority`, and `changefreq`
+- [ ] Support sitemap index for large sites (>50,000 URLs)
+- [ ] Generate RSS feed and Atom feed for content pages
+- [ ] Serve via the framework's routing system
+- [ ] Write tests
 
-### Task 6: robots.txt and Crawl Control
+### Task 5: robots.txt and Crawl Control
 
-- [ ] Create `generateRobotsTxt(config)` in `packages/core/src/robots.ts`
-- [ ] Support per-environment rules (block crawlers on staging/preview)
+- [ ] Generate `robots.txt` with per-section Allow/Disallow rules
+- [ ] Support per-environment rules (block crawlers on staging)
 - [ ] Add `Sitemap` directive
-- [ ] Create `createRedirectRules(redirects)` utility for 301/302 redirects
 - [ ] Add `noindex` meta tag helper for excluded pages
-- [ ] Implement `X-Robots-Tag` HTTP header helper
-- [ ] Write tests for robots output and redirect rules
+- [ ] Write tests
 
-### Task 7: Core Web Vitals Collection
+### Task 6: Heading Hierarchy Validator
 
-- [ ] Create browser-side `collectVitals(callback)` in `packages/core/src/vitals.ts`
-- [ ] Integrate `web-vitals` library to capture LCP, INP, CLS, TTFB, FCP
-- [ ] Create `scoreVitals(data)` that grades against Google's thresholds
-- [ ] Define storage adapter interface (in-memory, PostgreSQL, analytics service)
-- [ ] Implement in-memory adapter for demo/development
-- [ ] Write tests for vitals scoring
+- [ ] Create `validateHeadings(html)` — checks single H1, proper nesting, empty headings
+- [ ] Return structured report with issues and locations
+- [ ] Write tests
 
-### Task 8: Image Audit
+### Task 7: Image Alt Text Auditor
 
-- [ ] Create `auditImages(html)` in `packages/core/src/image-audit.ts`
-- [ ] Detect missing alt text on `<img>` tags
-- [ ] Flag generic alt text ("image", "photo", "screenshot", "untitled")
-- [ ] Check for missing `width`/`height` attributes (CLS risk)
-- [ ] Check for missing lazy loading on below-fold images
-- [ ] Generate image sitemap entries for pages with images
-- [ ] Write tests for detection accuracy
+- [ ] Create `auditImages(html)` — detects missing or generic alt text
+- [ ] Flag missing `width`/`height` attributes (CLS risk)
+- [ ] Generate image sitemap entries
+- [ ] Write tests
 
-### Task 9: Internal Linking Analyzer
+### Task 8: Internal Linking Analyzer
 
-- [ ] Create `analyzeLinkGraph(pages)` in `packages/core/src/link-analyzer.ts`
-- [ ] Accept page list with extracted internal links
-- [ ] Build link graph (which pages link to which)
+- [ ] Create `analyzeLinkGraph(pages)` — build link graph from page list
 - [ ] Detect orphan pages (no internal links pointing to them)
-- [ ] Calculate link depth (clicks from homepage)
+- [ ] Calculate link depth from homepage
 - [ ] Flag broken internal links (404s)
-- [ ] Generate report with recommendations
-- [ ] Write tests for graph analysis
-
-### Task 10: Heading Hierarchy Validator
-
-- [ ] Create `validateHeadings(html)` in `packages/core/src/heading-validator.ts`
-- [ ] Validate single H1 per page
-- [ ] Check for proper nesting (no H3 without preceding H2)
-- [ ] Flag empty headings and headings used only for styling
-- [ ] Return structured report with line numbers
-- [ ] Write tests for hierarchy validation
-
-### Task 11: Framework Adapters
-
-- [ ] Create Next.js adapter in `packages/adapters/nextjs/` (Metadata API helper, route handlers, React `<JsonLd>` component, middleware)
-- [ ] Create Nuxt adapter in `packages/adapters/nuxt/` (useHead composable, server routes, Vue `<JsonLd>` component)
-- [ ] Create Astro adapter in `packages/adapters/astro/` (API endpoints, Astro `<JsonLd>` component, integration)
-- [ ] Create Remix adapter in `packages/adapters/remix/` (meta function helper, resource routes, React `<JsonLd>` component)
-- [ ] Create Express adapter in `packages/adapters/express/` (middleware that serves robots.txt, sitemap, feeds, OG images)
-- [ ] Each adapter wraps core generators into framework-native patterns
-- [ ] Write integration tests for each adapter
-
-### Task 12: Dashboard and SERP Preview
-
-- [ ] Build standalone dashboard as SPA in `packages/dashboard/`
-- [ ] SEO score overview page (0-100 with category breakdown)
-- [ ] Core Web Vitals page with trend charts
-- [ ] Internal linking visualization
-- [ ] SERP preview page (Google, Facebook, Twitter/X with character warnings)
-- [ ] Use Recharts for charts and Tailwind CSS for styling
-- [ ] Export as embeddable component and standalone server
-- [ ] Write tests for dashboard rendering
-
-### Task 13: SEO Audit CLI
-
-- [ ] Create CLI entry point in `packages/cli/` with Commander.js
-- [ ] Implement `npx seo-toolkit audit <url>` — runs full audit against any URL
-- [ ] Check: meta tags, OG tags, canonical URLs, structured data, headings, images, links, robots.txt
-- [ ] Category scores: Metadata, Structured Data, Performance, Content, Crawlability
-- [ ] Implement `npx seo-toolkit check-links <url>` — broken link checker
-- [ ] Implement `npx seo-toolkit check-images <url>` — alt text auditor
-- [ ] Score site 0-100 with prioritized recommendations (critical, warning, info)
-- [ ] Output results as terminal table and optional JSON/HTML report
-- [ ] Write tests for scoring logic
+- [ ] Write tests
+
+### Task 9: SEO Audit CLI
+
+- [ ] Create `scripts/seo-audit.ts` runnable via `npx tsx scripts/seo-audit.ts`
+- [ ] Check: meta tags, OG tags, canonical URLs, structured data, headings, images, robots.txt
+- [ ] Category scores: Metadata, Structured Data, Content, Crawlability
+- [ ] Score 0-100 with prioritized recommendations (critical, warning, info)
+- [ ] Output as terminal table and optional JSON
+- [ ] Write tests
 
 ## Tech Stack
 
 - TypeScript
-- Node.js 18+
-- Turborepo (monorepo management)
 - Zod (config validation)
-- Satori (OG image generation)
-- web-vitals (Core Web Vitals)
-- Commander.js (CLI)
-- Cheerio (HTML parsing for audits)
+- Cheerio (HTML parsing)
 - xml2js (XML generation)
-- feed (RSS/Atom generation)
-- Recharts (dashboard charts)
-- Tailwind CSS (dashboard styling)
+- feed (RSS/Atom)
 - Vitest (testing)
-
-### Framework Adapters Support
-
-- Next.js 14+ (App Router)
-- Nuxt 3+
-- Astro 4+
-- Remix 2+
-- Express 4+
+- Framework detected at generation time from `package.json`
 
 ## Files to Create
 
 - `seo.config.ts`
-- `packages/core/src/index.ts`
-- `packages/core/src/metadata.ts`
-- `packages/core/src/structured-data.ts`
-- `packages/core/src/sitemap.ts`
-- `packages/core/src/feed.ts`
-- `packages/core/src/robots.ts`
-- `packages/core/src/redirects.ts`
-- `packages/core/src/og-image.ts`
-- `packages/core/src/vitals.ts`
-- `packages/core/src/image-audit.ts`
-- `packages/core/src/link-analyzer.ts`
-- `packages/core/src/heading-validator.ts`
-- `packages/core/src/config.ts`
-- `packages/core/package.json`
-- `packages/cli/src/index.ts`
-- `packages/cli/src/audit.ts`
-- `packages/cli/src/check-links.ts`
-- `packages/cli/src/check-images.ts`
-- `packages/cli/package.json`
-- `packages/adapters/nextjs/src/index.ts`
-- `packages/adapters/nextjs/src/metadata.ts`
-- `packages/adapters/nextjs/src/routes.ts`
-- `packages/adapters/nextjs/src/components.tsx`
-- `packages/adapters/nextjs/src/middleware.ts`
-- `packages/adapters/nextjs/package.json`
-- `packages/adapters/nuxt/src/index.ts`
-- `packages/adapters/nuxt/src/module.ts`
-- `packages/adapters/nuxt/src/composables.ts`
-- `packages/adapters/nuxt/package.json`
-- `packages/adapters/astro/src/index.ts`
-- `packages/adapters/astro/src/integration.ts`
-- `packages/adapters/astro/src/components.ts`
-- `packages/adapters/astro/package.json`
-- `packages/adapters/remix/src/index.ts`
-- `packages/adapters/remix/src/routes.ts`
-- `packages/adapters/remix/src/meta.ts`
-- `packages/adapters/remix/package.json`
-- `packages/adapters/express/src/index.ts`
-- `packages/adapters/express/src/middleware.ts`
-- `packages/adapters/express/package.json`
-- `packages/dashboard/src/App.tsx`
-- `packages/dashboard/src/pages/overview.tsx`
-- `packages/dashboard/src/pages/vitals.tsx`
-- `packages/dashboard/src/pages/links.tsx`
-- `packages/dashboard/src/pages/preview.tsx`
-- `packages/dashboard/package.json`
-- `tests/core/metadata.test.ts`
-- `tests/core/structured-data.test.ts`
-- `tests/core/sitemap.test.ts`
-- `tests/core/robots.test.ts`
-- `tests/core/vitals.test.ts`
-- `tests/core/link-analyzer.test.ts`
-- `tests/core/heading-validator.test.ts`
-- `tests/core/image-audit.test.ts`
-- `tests/cli/audit.test.ts`
-- `tests/adapters/nextjs.test.ts`
-- `tests/adapters/express.test.ts`
-- `turbo.json`
-- `package.json`
-- `.env.example`
+- `src/lib/seo/config.ts`
+- `src/lib/seo/metadata.ts`
+- `src/lib/seo/structured-data.ts`
+- `src/lib/seo/sitemap.ts`
+- `src/lib/seo/feed.ts`
+- `src/lib/seo/robots.ts`
+- `src/lib/seo/heading-validator.ts`
+- `src/lib/seo/image-audit.ts`
+- `src/lib/seo/link-analyzer.ts`
+- `scripts/seo-audit.ts`
+- `tests/seo/metadata.test.ts`
+- `tests/seo/structured-data.test.ts`
+- `tests/seo/sitemap.test.ts`
+- `tests/seo/robots.test.ts`
+- `tests/seo/heading-validator.test.ts`
+- `tests/seo/audit.test.ts`
+
+## Files to Modify
+
+- `package.json` — Add dependencies
+- Framework-specific routing files (detected at generation time) — Wire sitemap, robots.txt, feed routes
+- Framework-specific layout/head (detected at generation time) — Integrate metadata helpers
 
 ## Configuration
 
-### Environment Variables
-
-- `SITE_URL` — Canonical site URL (e.g., `https://example.com`)
-- `SITE_NAME` — Site name for metadata and structured data
-- `SITE_DESCRIPTION` — Default meta description
-- `SITE_LOCALE` — Default locale (e.g., `en_US`)
-- `TWITTER_HANDLE` — Twitter/X handle for card attribution (e.g., `@mysite`)
-- `GA_MEASUREMENT_ID` — (Optional) Google Analytics ID for vitals reporting
-
-### seo.config.ts Example
+### seo.config.ts
 
 ```typescript
-import { defineSEOConfig } from '@seo-toolkit/core';
+import { defineSEOConfig } from './src/lib/seo/config';
 
 export default defineSEOConfig({
   site: {
@@ -290,20 +151,11 @@ export default defineSEOConfig({
     organization: {
       name: 'My Company',
       logo: 'https://example.com/logo.png',
-      sameAs: [
-        'https://twitter.com/mycompany',
-        'https://linkedin.com/company/mycompany',
-        'https://github.com/mycompany',
-      ],
+      sameAs: ['https://twitter.com/mycompany', 'https://github.com/mycompany'],
     },
   },
   sitemap: {
     exclude: ['/admin/*', '/api/*'],
-    priorities: {
-      '/': 1.0,
-      '/products/*': 0.9,
-      '/blog/*': 0.7,
-    },
   },
   redirects: [
     { source: '/old-page', destination: '/new-page', permanent: true },
@@ -311,41 +163,10 @@ export default defineSEOConfig({
 });
 ```
 
-### Framework Integration Examples
-
-```typescript
-// Next.js — app/layout.tsx
-import { createMetadata } from '@seo-toolkit/nextjs';
-export const generateMetadata = createMetadata({ title: 'Home' });
-
-// Nuxt — nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@seo-toolkit/nuxt'],
-});
-
-// Express
-import { seoMiddleware } from '@seo-toolkit/express';
-app.use(seoMiddleware()); // serves /robots.txt, /sitemap.xml, /feed.xml
-
-// Astro — astro.config.mjs
-import seoToolkit from '@seo-toolkit/astro';
-export default defineConfig({ integrations: [seoToolkit()] });
-```
-
-## Usage
-
-1. Install: `npm install @seo-toolkit/core @seo-toolkit/<framework>`
-2. Create `seo.config.ts` in your project root
-3. Wire framework adapter into your routes (see examples above)
-4. Run `npx seo-toolkit audit https://yoursite.com` for a full SEO health check
-5. Visit `/admin/seo` for the audit dashboard (optional)
-
 ## Notes
 
-- The OG image generator uses Satori (same engine as Vercel's `@vercel/og`) and works in any Node.js runtime
-- Core Web Vitals thresholds follow Google's 2024+ standards: LCP < 2.5s, CLS < 0.1, INP < 200ms
-- The internal link analyzer crawls pages at build time or on-demand — it does not run in production
-- For multi-language sites, configure `hreflang` mappings in `seo.config.ts`
-- Structured data is validated against schema.org specifications
-- The core package has zero framework dependencies — adapters are optional
+- Ralph reads `package.json` to detect the framework and generates routes/components using that framework's patterns
+- Core Web Vitals thresholds: LCP < 2.5s, CLS < 0.1, INP < 200ms
+- The internal link analyzer runs on-demand via CLI — not in production
+- Structured data is validated against schema.org specs
 - Requires Node.js 18+
diff --git a/templates.json b/templates.json
index d34f9d2..935f43c 100644
--- a/templates.json
+++ b/templates.json
@@ -159,7 +159,7 @@
       "name": "AEO Toolkit",
       "description": "Build an Answer Engine Optimization toolkit with llms.txt, AI crawler management, structured data, and citation tracking.",
       "category": "seo",
-      "tags": ["nextjs", "aeo", "llms-txt", "robots-txt", "structured-data", "ai-crawlers", "typescript"],
+      "tags": ["aeo", "llms-txt", "robots-txt", "structured-data", "ai-crawlers", "typescript"],
       "difficulty": "advanced",
       "path": "specs/seo/aeo-toolkit.md"
     },
@@ -168,7 +168,7 @@
       "name": "SEO Toolkit",
       "description": "Build a comprehensive technical SEO toolkit with metadata, sitemaps, Core Web Vitals, and audit dashboard.",
       "category": "seo",
-      "tags": ["nextjs", "seo", "metadata", "sitemap", "structured-data", "core-web-vitals", "typescript"],
+      "tags": ["seo", "metadata", "sitemap", "structured-data", "json-ld", "typescript"],
       "difficulty": "intermediate",
       "path": "specs/seo/seo-toolkit.md"
     }