# /seo-site-structure

> Backed by `.claude/context/ai-seo/playbook/04-site-structure.md` (+ Topical Relevance prompt in `prompts/`).


# /seo-site-structure — Core 30 + Topical Map

Backed by `.claude/context/ai-seo/playbook/04-site-structure.md` (+ Topical Relevance prompt in `prompts/`).

## When to trigger
- "Build the Core 30 for ACME Agency", "what pages should this site have", "make a topical map", "/seo-site-structure".
- After `/local-seo-audit` flags a content-structure gap. Run this before `/seo-content` (structure first, then write the pages).

## What it produces
A Google Doc "Site Structure (Core 30) — <Client>" with: the full page plan with target keyword + word-count per page, the URL hierarchy + internal-linking map, the topical map (topical clusters before geographic), location-page plan, and a gap analysis vs the current site.

## Step-by-Step

### 1. Parse
First positional = client/business. Flags: `--url`, `--location` (primary city), `--niche` (e.g. "plumbing", "dental"), `--dry-run`.

### 2. Gather context
```bash
node ACME Agency/scripts/seo_run.mjs --skill structure --mode gather --client "<name>" --url "<url>" --location "<city>"
```
The gather scrapes the homepage and tries `/sitemap.xml` so you can audit existing pages. Read the CONTEXT.

### 3. Read the method
Read `.claude/context/ai-seo/playbook/04-site-structure.md` fully. Lock in the exact Core 30 composition (counts + word counts), the **<id>** rule, the internal-linking pattern, the GBP-proximity ceiling for location pages, and the sitemap rule. Load the verbatim Topical Relevance prompt via `prompts/` and run it (mentally / with the niche) to generate the topical clusters.

### 4. Build the structure (markdown)
- **Page plan** — table: `| URL | Page type | Target keyword | Word count |`. Category pages (3-10, 1,500-2,500 words), service pages (20-30, 1,000-2,000 words), GBP landing page, About, Contact, Locations.
- **URL hierarchy** — the tree + the internal-linking pattern (which pages link to which; nav-link cap from field notes).
- **Topical map** — clusters built for topical relevance first, derived from the Topical Relevance prompt for this niche.
- **Geographic layer** — location/city pages, sequenced AFTER topical depth, each bounded by the GBP's real reach (don't plan city pages the GBP can't rank for).
- **Gap analysis** — current pages (from the scrape/sitemap) vs the plan: keep / rewrite / create.
Write to `ACME Agency/clients/<Client>/SEO/site-structure.md` (or `/tmp`).

### 5. Save + report
```bash
node ACME Agency/scripts/seo_run.mjs --skill structure --mode save --client "<name>" \
  --in "<site-structure.md>" --title "Site Structure (Core 30) — <Client>" \
  --slack "*Site Structure (Core 30) — <Client>*
Plan: <N> pages (<c> category, <s> service). <k> already exist, <m> to create."
```
Add `--dry-run` to skip Drive/Slack. Output the Doc link.

## Guardrails
- **Respect the ordering rule:** topical relevance before geographic — never plan a geo layer with no topical foundation.
- **Proximity ceiling:** don't promise/plan rankings in cities the GBP address can't reach.
- Hand the page plan to `/seo-content` to actually write the pages.