add-seo

> **Plugin check**: Run `node "${CLAUDE_PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# Add SEO

Add essential SEO assets to a Power Pages code site: `robots.txt`, `sitemap.xml`, and meta tags.

> **Prerequisite:** This skill expects an existing Power Pages code site created via `/create-site`. Run that skill first if the site does not exist yet.

## Core Principles

- **Crawlability first:** Every public page must be discoverable by search engines via a valid `robots.txt` and `sitemap.xml` before any other SEO work matters.
- **Accurate metadata:** Meta tags (title, description, Open Graph) must truthfully represent page content — misleading metadata harms rankings.
- **Framework-aware placement:** SEO assets must be placed in the correct location for the detected framework (public directory, layout component, etc.).

**Initial request:** $ARGUMENTS

## Workflow

1. **Phase 1: Verify Site Exists** → Locate the Power Pages project
2. **Phase 2: Gather SEO Configuration** → Site URL, pages, preferences
3. **Phase 3: Plan & Approve** → Present SEO additions inline, get user approval
4. **Phase 4: Add robots.txt** → Create robots.txt in public directory
5. **Phase 5: Add sitemap.xml** → Generate sitemap.xml from site routes
6. **Phase 6: Add Meta Tags** → Add title, description, viewport, Open Graph, and favicon to index.html
7. **Phase 7: Verify & Commit** → Verify via Playwright, commit changes

---

## Phase 1: Verify Site Exists

**Goal:** Confirm a Power Pages code site exists and understand its structure.

### Actions

#### 1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories to find the project root. Use your file-search tool (e.g., `Glob` with patterns `powerpages.config.json` and `*/powerpages.config.json`) rather than a shell-specific command.

**If not found**: Tell the user to create a site first with `/create-site`.

#### 1.2 Read Existing Config

Read `powerpages.config.json` to get the site name and config.

#### 1.3 Detect Framework & Discover Routes

Read `package.json` to determine the framework and locate key files. See `${CLAUDE_PLUGIN_ROOT}/references/framework-conventions.md` for the full framework → public directory → index HTML mapping and route discovery patterns.

Build a list of all routes (e.g., `/`, `/about`, `/contact`, `/blog`).

### Output

- Project root path identified
- Framework detected (React, Vue, Angular, or Astro)
- Full list of discoverable routes

---

## Phase 2: Gather SEO Configuration

**Goal:** Collect all SEO preferences from the user before making any changes.

### Actions

<!-- not-a-gate: data-gathering — production URL + exclusion list shape the upcoming Phase 3 plan but don't write anything on their own -->

Use `AskUserQuestion` to collect SEO preferences:

#### Call 1

| Question | Header | Options |
|----------|--------|---------|
| What is the production URL for your site? (e.g., <https://contoso.powerappsportals.com>) | Site URL | *(free text — use single generic option so user types via "Other")* |
| Which pages should be excluded from search engine indexing? | Exclusions | None — index all pages (Recommended), Admin/auth pages only, Let me specify |

<!-- not-a-gate: data-gathering — meta description + OG tag choice shape the upcoming Phase 3 plan but don't write anything on their own -->

#### Call 2

| Question | Header | Options |
|----------|--------|---------|
| What meta description should appear in search results? | Description | *(free text — use single generic option so user types via "Other")* |
| Add Open Graph tags for social media sharing? | OG Tags | Yes — add Open Graph and Twitter Card tags (Recommended), No — skip social tags |

### Output

- Production URL confirmed
- Exclusion list finalized
- Meta description text
- Open Graph tag preference (yes/no)

---

## Phase 3: Plan & Approve

**Goal:** Present the full SEO plan to the user and get explicit approval before making changes.

### Actions

Present the SEO additions that will be made as a clear, inline summary:

1. **robots.txt content** — which paths will be allowed/disallowed
2. **sitemap.xml content** — all discovered routes with the production URL and priority assignments
3. **Meta tags to add to index.html** — title, description, viewport, charset, Open Graph, Twitter Card
4. **Favicon** — link tag and placeholder SVG

<!-- gate: add-seo:3.plan-approval | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · add-seo:3.plan-approval):** Final sign-off on the SEO additions before any `robots.txt` / `sitemap.xml` / `index.html` write.
>
> **Trigger:** Phase 3 has presented the full plan inline (robots.txt, sitemap.xml, meta tags, favicon).
> **Why we ask:** SEO assets land on disk with the wrong production URL, wrong exclusions, or unwanted OG tags — fixable but noisy in git history.
> **Cancel leaves:** Nothing — no file writes yet.

After presenting the plan, use `AskUserQuestion` to get approval:

| Question | Header | Options |
|----------|--------|---------|
| Here is the SEO plan. How would you like to proceed? | SEO Plan Approval | Approve and proceed (Recommended), I'd like to make changes |

If the user chooses "I'd like to make changes", ask what they want to change, update the plan accordingly, and present the revised plan for approval again.

### Output

- User-approved SEO plan ready for implementation

---

## Phase 4: Add robots.txt

**Goal:** Create a valid `robots.txt` that tells search engines which pages to crawl.

### Actions

Create `robots.txt` in the public directory (`<PROJECT_ROOT>/public/robots.txt`):

```text
User-agent: *
Allow: /

Sitemap: <PRODUCTION_URL>/sitemap.xml
```

If the user specified pages to exclude, add `Disallow` directives:

```text
User-agent: *
Allow: /
Disallow: /admin/
Disallow: /auth/

Sitemap: <PRODUCTION_URL>/sitemap.xml
```

### Output

- `public/robots.txt` created with correct dire