> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/seo.md).

# SEO optimization

Last reviewed: 2026-07-13

This directory is Suigar's persistent SEO operating system. Read it before changing public page copy, route metadata, sitemap coverage, robots policy, structured data, social previews, blog content generation, performance-critical rendering, public docs, or acquisition pages.

The goal is not a static checklist. The goal is a memory layer that lets humans and AI agents converge toward repeatable, measurable, high-quality SEO work across Suigar.

## Reading Order

1. [Guidelines](/suigar-docs/seo/guidelines.md): global rules that apply to every public Suigar surface.
2. [Channels](/suigar-docs/seo/channels.md): what we track, why it matters, how mature each channel should become.
3. [Status](/suigar-docs/seo/status.md): current maturity, evidence, owners, and next actions.
4. [Subprojects](/suigar-docs/seo/subprojects.md): project-specific overlays for frontend, blog, docs, admin, backend/API, and experimental frontends.
5. [Blog generation](/suigar-docs/seo/blog-generation.md): AI-backed blog production rules, templates, and review gates.
6. [Page checklist](/suigar-docs/seo/page-checklist.md): route-level launch and audit checklist plus current frontend route indexability inventory.
7. [Automation roadmap](/suigar-docs/seo/automation-roadmap.md): path from docs to automated SEO agents, CI checks, and feedback loops.
8. [Optimization log](/suigar-docs/seo/optimization-log.md): dated decisions, validation, and follow-ups.

## Current Maturity Snapshot

| Area                              | Maturity | Direction                                                                                                                                                                                                                                        |
| --------------------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Production frontend technical SEO |        4 | Static route heads, build validation, one-host sitemap/robots validation, canonical host redirects, legacy-route redirects, deploy cache policy, and live post-deploy checks exist; next needs richer previews and duplicate metadata reporting. |
| SweetHouse SEO                    |        3 | `house.suigar.com` now has a scoped sitemap/robots policy, mainnet/non-mainnet indexability guards, and static export validation; next needs Search Console submission and rendered-head evidence.                                               |
| Blog SEO                          |        3 | Database-backed Next blog now has ISR pages, on-demand revalidation, sitemap/RSS/Atom feeds, and runtime-build validation; production still needs the standalone runtime deployment wired before DB publishing is instant live.                  |
| Docs/content SEO                  |        1 | Docs are useful but not yet tracked as an SEO channel with metadata, sitemap, or content refresh policy in this directory.                                                                                                                       |
| AI search/GEO readiness           |        1 | Crawlers are allowed in main robots policy, but entity coverage, answer extraction, and source-backed content are not yet systematically tracked.                                                                                                |
| Measurement and feedback          |        1 | Analytics exist in the app/blog, but Search Console, Core Web Vitals, query/page cohorts, and editorial learnings are not yet folded back into docs.                                                                                             |
| Automation                        |        1 | Some frontend SEO checks exist; no repo-wide SEO agent loop or CI gate has been formalized yet.                                                                                                                                                  |

Maturity levels are defined in [channels.md](/suigar-docs/seo/channels.md).

## Implementation Map

### Production Frontend

* `frontend/src/components/PageTitle.tsx` emits the page title, canonical link, description, Open Graph tags, Twitter card tags, optional `noindex,nofollow`, and JSON-LD scripts.
* `frontend/src/configs/seo.ts` owns site-level defaults: site URL, default description, social profiles, default image, locale, and title suffix.
* `frontend/src/utils/seo.ts` builds reusable metadata and structured data for home, generic pages, games, organization, website, software app, web page, game, and breadcrumb entities.
* `frontend/scripts/sitemap-routes.mjs` is the source of truth for indexed and excluded frontend routes.
* `frontend/scripts/sitemap-generator.mjs` validates every concrete TanStack route as either indexed or excluded, then builds `sitemap.xml` with canonical URLs and source-derived `lastmod` only.
* `frontend/scripts/sitemap-index-generator.mjs` builds the deterministic same-site app/blog/docs sitemap index without unverifiable timestamps.
* `frontend/scripts/seo-metadata-report.mjs` checks indexed route titles/descriptions for duplicates and practical snippet-length issues.
* `frontend/scripts/write-seo-assets.mjs` writes production `robots.txt`, `sitemap.xml`, and validated static route HTML; non-mainnet networks and forced `noindex` builds omit sitemaps, block crawling, and emit `noindex,nofollow` route HTML.
* `.github/workflows/frontend.yaml` deploys through the shared static-site action and validates live route heads, robots policy, canonical host redirects, and legacy route redirects after deploy.
* `scripts/seo/search-console-report.mjs` turns Search Console page/query performance and URL Inspection checks into a repeatable markdown report.
* `frontend/public/robots.txt` contains the base crawler policy that production post-processing normalizes with the live sitemap URL.
* `scripts/seo/check-static-site-seo.mjs` validates sitemap XML and robots policy against host-scoping, URL-count, file-size, `lastmod`, duplicate, and sitemap-directive rules; with `--check-html`, it also verifies sitemap URLs map to static HTML with matching canonical, title, description, and no `noindex`.
* `scripts/seo/check-live-sitemap-system.mjs` retains the full production sitemap audit for manual use. Automated execution is disabled unless `ENABLE_LIVE_SITEMAP_AUDIT=true` is configured.

### SweetHouse

* `sweethouse-website/lib/seo.ts` owns SweetHouse indexable/excluded route policy and stable `lastModified` values.
* `sweethouse-website/app/sitemap.ts` emits only `house.suigar.com` URLs on mainnet and no URLs on non-mainnet.
* `sweethouse-website/app/robots.ts` advertises only `https://house.suigar.com/sitemap.xml` on mainnet and blocks non-mainnet.
* `sweethouse-website/app/app/layout.tsx` emits noindex metadata for wallet-connected app routes.
* `sweethouse-website/package.json` exposes `pnpm run check:seo` for static export validation, including sitemap/robots host checks and rendered canonical/metadata checks for sitemap URLs.
* `.github/workflows/sweethouse.yaml` runs the SweetHouse build with the sitemap/robots check.

### Blog Site

* `blog-site/src/app/layout.tsx` defines blog-wide Next metadata.
* `blog-site/src/app/posts/[slug]/page.tsx` generates per-post metadata and canonical URLs.
* `blog-site/src/app/sitemap.ts` emits the blog homepage and post URLs.
* `blog-site/src/app/robots.ts` emits blog crawler policy and sitemap reference.
* `blog-site/src/app/rss.xml/route.ts` and `blog-site/src/app/atom.xml/route.ts` emit ISR feed XML for reader and off-site discovery.
* `blog-site/src/app/api/revalidate/route.ts` exposes the secret-protected on-demand revalidation hook for homepage, post, sitemap, RSS, and Atom refreshes.
* `blog-site/src/app/assets/blog/db/[...path]/route.ts` serves database-backed blog assets at stable public URLs when a new post references an image not present in an old static export.
* `blog-site/scripts/verify-runtime-build.mjs` verifies the standalone runtime, ISR routes, feeds, sitemap, DB asset route, and revalidation route.
* `blog-site/src/lib/site-config.ts` separates mainnet blog, game, and docs URLs from testnet URLs.
* `blog-site/db/migrations/` defines the post and asset tables that DB publishing must satisfy.

## Working Agreement

1. Every SEO change must state affected channels: indexability, metadata, structured data, content, blog generation, internal links, images, performance, social previews, measurement, AI search/GEO, or off-site discovery.
2. Every indexable page must have one canonical URL, unique title, useful description, crawlable primary content, meaningful internal links, and an owner.
3. Every excluded route must have a clear reason. Private, tokenized, callback, authenticated, development, duplicate, or thin dynamic routes should stay excluded.
4. Metadata and page copy must be understandable to users, not just crawlers. Avoid keyword stuffing, vague hype, guaranteed-return language, or technical internals.
5. AI-generated blog work must use [blog-generation.md](/suigar-docs/seo/blog-generation.md) before drafting and must update constraints when a new editorial rule is learned.
6. After implementation, run the smallest meaningful validation. Use `pnpm run test:seo` plus `pnpm --filter @suigar/ui run check:seo` for sitemap/indexability contract changes, `pnpm --filter @suigar/blog-ui run typecheck` for blog metadata/content-model changes, and `NODE_ENV=production NETWORK=mainnet pnpm run build && pnpm run check:seo` from `sweethouse-website/` for SweetHouse sitemap/robots changes.
7. Keep the live sitemap audit opt-in. Run the `SEO Live Contract` workflow manually, or set `ENABLE_LIVE_SITEMAP_AUDIT=true` when automatic deployment and scheduled auditing is intentionally re-enabled.
8. Add a dated entry to [optimization-log.md](/suigar-docs/seo/optimization-log.md) when SEO work is completed or when a meaningful SEO decision is made.

## Official References

* [Google Search Central SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide)
* [Google Search technical requirements](https://developers.google.com/search/docs/essentials/technical)
* [Google crawling and indexing docs](https://developers.google.com/search/docs/crawling-indexing)
* [Google canonical URL guidance](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)
* [Google robots meta tag guidance](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag)
* [Google structured data intro](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)
* [Google JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics)
* [Google people-first content guidance](https://developers.google.com/search/docs/fundamentals/creating-helpful-content)
* [Google generative AI content guidance](https://developers.google.com/search/docs/fundamentals/using-gen-ai-content)
* [web.dev Web Vitals](https://web.dev/articles/vitals)
* [web.dev Core Web Vitals thresholds](https://web.dev/articles/defining-core-web-vitals-thresholds)