A production-ready, pure-static programmatic SEO frontend framework built for AI Agent directories (Claude Code, Antigravity, Cursor, OpenAI Skills). Designed specifically to achieve indexation equilibrium (M \approx N) and eliminate crawl traps.

📊 1. Core Framework: The `N / M / X` Indexation Health Model

Based on real production telemetry from agentskillshub.top:

Metric	Case Study Value	Meaning	Health State & Problem Diagnosis
`N` (Total Generated)	~19,600	Total indexable URLs created	Generated set
Sitemap Submitted	4,050	Submitted to GSC	⚠️ Huge Defect: ~15,550 URLs missing from sitemap!
`X` (Google Discovered)	6,010	URLs Google has encountered	⚠️ Crawl Blindness: `N \gg X`, Google doesn't know 70% of the site
`M` (Google Indexed)	3,380	URLs successfully in SERP	⚠️ Quality Barrier: `X \gg M`, 2,630 crawled pages discarded

The Golden Rule

Healthy equilibrium: M \approx N and X \rightarrow N.

$N \gg X$: Crawl trap, orphan pages, or sitemap omissions.

$X \gg M$: Thin content, repetitive templates, or duplicate parameter URLs.

⚡ 2. The 6 Sudden Death Traps in pSEO & Solutions

Trap	Failure Trigger	Architectural Mitigation in this Repo
1. Batch Launching	`N` surges 10x overnight; `X` & `M` lag; domain flagged as spam.	Quality Gates: `getIndexableSkills()` filters out shallow content (<40 words) from XML sitemaps.
2. Migrations & Renaming	URLs change (e.g. `ppt-skills`); creates 404s in sitemaps.	`sitemap:validate` script checks 100% of sitemap URLs against static output.
3. Parameter Explosion	Filter/sort combinations multiply URLs infinitely (`N!`).	Self-referencing canonicals strip `?sort=`, `?page=`. `robots.txt` Disallows `/?`.
4. Threshold Changes	Bulk deletion creates 404/noindex cascade.	Deterministic quality criteria version-controlled in `src/config/site.ts`.
5. Template-wide Bugs	Canonical or robots error in single template affects 20k pages.	Centralized `<SEOHead />` component with automated pre-commit linting.
6. Deployment Bugs	Misconfigured `robots.txt` crashes index in 72h.	Automated `npm run check:all` runs before static deployment.

⚠️ 3. Crucial SEO Law: `noindex` does NOT Save Crawl Budget

Misconception: Putting <meta name="robots" content="noindex"> on 50,000 filter URLs saves crawl budget.
Reality: Googlebot must make an HTTP request and download the HTML to read the noindex tag. It still eats your crawl budget!
Correct Practice:
1. Filter/sorting is handled client-side without URL permutations.
2. Dynamic query routes are disallowed in robots.txt:
```
User-agent: *
Disallow: /*?*
Disallow: /?*
Disallow: /api/*
```

🛠️ 4. Quick Start & Static Build

Requirements

Node.js >= 18
pnpm (or npm / bun)

Development

# Start local development server
pnpm dev

Static Export & Automated SEO Audits

# Full static HTML build + SEO header audit + 100% Sitemap coverage validation
pnpm check:all

Individual commands:

# 1. Export pure static HTML to dist/
pnpm build

# 2. Automated SEO header, canonical, OpenGraph, JSON-LD audit
pnpm seo:audit

# 3. Verify that 100% of indexable HTML pages are included in XML sitemaps
pnpm sitemap:validate

🤖 5. Agent & Claude SEO Skills Integration

Antigravity Custom Skill: Located at .gemini/antigravity/skills/programmatic-seo/SKILL.md.

Claude Code SEO Skill:

# Install AgriciDaniel/claude-seo
/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
# Run audit
/seo audit https://agentskillshub.top

README.md

AgentSkillsHub (pSEO High-Scale Framework)

📊 1. Core Framework: The N / M / X Indexation Health Model