@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/seo-machine/references/quality-bars.md

@@ -0,0 +1,99 @@
+# Quality Bars (Verification Gates)
+
+Every page-shipping phase ends with a quality check. If it fails, fix it before declaring the phase complete. Don't ship under-spec work — it underperforms in rankings and you'll have to come back to fix it anyway.
+
+## The four checks
+
+| Check | Tool | Per pattern |
+|---|---|---|
+| Word count | `scripts/word_count.py` | A ≥600, B/C ≥800, D ≥700, E ≥2,500 |
+| Internal-link minimums | `scripts/link_audit.py` | See per-pattern minimums below |
+| Schema markup | Manual JSON-LD check (or `scripts/tech_audit.py`) | See per-pattern schema requirements |
+| Honesty section (alts only) | Manual visual check | Pattern A only — 3-4 rows |
+
+## Internal-link minimums (per pattern)
+
+The skill enforces these via `scripts/link_audit.py`.
+
+### Pattern A — `/alternatives/[slug]`
+
+- **Outbound from this page:** ≥2 sibling `/alternatives/*`, ≥1 `/features/*`, ≥1 `/tools/*` (or stack-equivalent)
+- **Inbound to this page:** ≥2 existing pages must link here. Common spots: homepage, sibling alts, related feature pages.
+
+### Pattern B/C — `/for/[slug]`
+
+- **Outbound:** ≥2 `/features/*`, ≥2 `/tools/*`, ≥1 sibling `/for/*`
+- **Inbound:** ≥2 existing pages
+
+### Pattern D — `/compare/[slug]`
+
+- **Outbound:** `/alternatives/[a]`, `/alternatives/[b]`, ≥1 relevant `/for/*`, `/pricing`
+- **Inbound:** both `/alternatives/[a]` and `/alternatives/[b]` link here
+
+### Pattern E — `/playbooks/[slug]`
+
+- **Outbound (in body, not sidebar):** ≥3 `/features/*`, ≥2 `/tools/*`, ≥2 `/for/*`, ≥1 `/alternatives/*`
+- **Inbound:** ≥2 existing pages (commonly other playbooks + a related `/for/*`)
+
+## Universal rule
+
+**Every page must be reachable from ≥2 other pages.** No orphans. Check via:
+
+```bash
+# Find pages that nobody links to (orphans)
+python scripts/link_audit.py --orphan-check
+```
+
+## Schema requirements (per pattern)
+
+| Pattern | Required JSON-LD |
+|---|---|
+| Homepage | `SoftwareApplication` (or `Product`), `Organization` |
+| `/alternatives/[slug]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` |
+| `/for/[slug]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` |
+| `/compare/[slug]` | `BreadcrumbList`, `FAQPage` |
+| `/playbooks/[slug]` | `Article`, `BreadcrumbList` |
+| `/tools/[slug]` | `SoftwareApplication` or `WebApplication`, `BreadcrumbList` |
+
+Validate at https://validator.schema.org/ on the rendered URL. The skill can curl-and-check via `scripts/tech_audit.py --schema <url>`.
+
+## Meta tag requirements (every page)
+
+- Unique `<title>`, 30-60 chars
+- Unique `<meta name="description">`, 100-155 chars
+- `<link rel="canonical">` set to the absolute URL (no query params, no trailing slash if your convention is slashless)
+- `<meta property="og:type">`, `og:title`, `og:description`, `og:image`, `og:url`
+- `<meta name="twitter:card">` (`summary_large_image` is standard)
+- Exactly one `<h1>` per page
+
+## Honesty section (Pattern A only)
+
+Verify presence visually. The section must have:
+
+- An eyebrow + H2 labelling it (e.g. "Honest tradeoffs" / "Where [competitor] still wins")
+- 3-4 rows, each with a feature/dimension and a 30+ word body
+- Concrete: each row references a specific feature, not a vague "they're more polished"
+- Honest: each row should be a real strength of the competitor, not a fake weakness in you
+
+If the honesty section is missing or thin, the phase fails the quality gate. Rewrite before shipping.
+
+## Verification gate flow
+
+When a phase's page work is done:
+
+1. Run `python scripts/word_count.py <stack-output-path>` — must be ≥ pattern minimum
+2. Run `python scripts/link_audit.py --slug <slug> --pattern <a|b|c|d|e>` — must pass
+3. If applicable, run `python scripts/tech_audit.py --schema <url>` — must validate
+4. Manually verify honesty section (Pattern A)
+5. Visit URL in browser, view-source, confirm:
+   - Full SSR HTML (search engines see content)
+   - Title + description + canonical present
+   - JSON-LD blocks render
+6. **Only after all pass:** update tracker row to `completed` and write the phase summary
+
+A failing gate is information, not blame. Often it surfaces:
+- A thin section that needed more depth
+- A missing internal link (easy to forget)
+- A schema helper that didn't fire (existing helper has a bug)
+
+Fix the root cause; don't paper over it.

package/skills/seo-machine/references/stacks/astro.md

@@ -0,0 +1,156 @@
+# Stack adapter — Astro
+
+Astro is the cleanest fit for this skill: static-first, content-collections built-in, fast crawl performance, trivially indexable.
+
+## Conventions to use
+
+- **Content collections** for each pattern. Define schemas in `src/content/config.ts`.
+- **Dynamic routes** via `src/pages/[pattern]/[slug].astro` with `getStaticPaths` from the collection.
+- **Layouts** in `src/layouts/<Pattern>Layout.astro` — shared structure.
+- **Sitemap** via `@astrojs/sitemap` integration (or hand-rolled `src/pages/sitemap.xml.ts`).
+- **Schema/meta** in each layout's `<head>` via slot data.
+
+## Content collection setup
+
+`src/content/config.ts`:
+
+```typescript
+import { defineCollection, z } from 'astro:content'
+
+const alternatives = defineCollection({
+  type: 'data',
+  schema: z.object({
+    competitor_name: z.string(),
+    hero_eyebrow: z.string(),
+    hero_h1: z.string(),
+    hero_lede: z.string(),
+    table_h2: z.string(),
+    table_lede: z.string(),
+    comparison_rows: z.array(z.object({ /* ... */ })),
+    switch_reasons: z.array(z.object({ /* ... */ })),
+    honesty_rows: z.array(z.object({ feature: z.string(), body: z.string() })),
+    faqs: z.array(z.object({ question: z.string(), answer: z.string() })),
+    // ...
+  }),
+})
+
+const useCases   = defineCollection({ type: 'data', schema: /* ForData */ })
+const comparisons = defineCollection({ type: 'data', schema: /* ComparisonData */ })
+const playbooks  = defineCollection({ type: 'content', schema: /* metadata only; body in MDX */ })
+
+export const collections = { alternatives, useCases, comparisons, playbooks }
+```
+
+Each entry lives in `src/content/alternatives/<slug>.json` (or `.yaml`). Schema enforces shape.
+
+## Pattern A — `src/pages/alternatives/[slug].astro`
+
+```astro
+---
+import { getCollection } from 'astro:content'
+import AlternativeLayout from '@/layouts/AlternativeLayout.astro'
+
+export async function getStaticPaths() {
+  const entries = await getCollection('alternatives')
+  return entries.map(entry => ({ params: { slug: entry.id }, props: { data: entry.data } }))
+}
+
+const { data } = Astro.props
+---
+<AlternativeLayout data={data} />
+```
+
+The layout handles `<head>` (title, description, canonical, OG, JSON-LD) and renders the body.
+
+## Pattern E — playbooks in MDX
+
+Astro's content collections support MDX natively. Put each playbook in `src/content/playbooks/<slug>.mdx` with frontmatter:
+
+```mdx
+---
+title: "B2B social media strategy: a 2,500-word playbook"
+slug: "b2b-social-media-strategy"
+date_published: 2026-01-15
+read_time_min: 18
+related: [...]
+---
+
+import PlaybookLayout from '@/layouts/PlaybookLayout.astro'
+import VignetteCard from '@/components/VignetteCard.astro'
+
+# Section 1
+
+Body content here, freely interleaving MDX components.
+
+<VignetteCard scenario="..." surprise="..." lesson="..." />
+
+# Section 2
+...
+```
+
+Renders via `src/pages/playbooks/[slug].astro` with `getCollection('playbooks')`.
+
+## Sitemap
+
+Use the `@astrojs/sitemap` integration. It auto-discovers all pages including dynamic routes.
+
+```javascript
+// astro.config.mjs
+import sitemap from '@astrojs/sitemap'
+
+export default defineConfig({
+  site: 'https://example.com',
+  integrations: [sitemap({
+    filter: (page) => !page.includes('/admin'),
+    lastmod: new Date('2026-MM-DD'),  // bump on phase merges, or use file mtime
+  })],
+})
+```
+
+## JSON-LD pattern in layouts
+
+```astro
+---
+const { data } = Astro.props
+const faqSchema = data.faqs && {
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  mainEntity: data.faqs.map(f => ({
+    "@type": "Question",
+    name: f.question,
+    acceptedAnswer: { "@type": "Answer", text: f.answer },
+  })),
+}
+---
+<html>
+  <head>
+    <title>{data.meta_title}</title>
+    <meta name="description" content={data.meta_description}>
+    <link rel="canonical" href={canonical}>
+    {faqSchema && <script type="application/ld+json" set:html={JSON.stringify(faqSchema)} />}
+  </head>
+  <!-- body -->
+</html>
+```
+
+## File-write checklist for any phase
+
+- [ ] Data file added at `src/content/<pattern>/<slug>.json` (or MDX for playbooks)
+- [ ] Schema validates (`npm run astro check` or build)
+- [ ] Sibling page references updated (≥2 spots in other content files)
+- [ ] Sitemap rebuilds (automatic if using `@astrojs/sitemap`)
+- [ ] `npm run build` succeeds and emits the new page to `dist/`
+- [ ] Verify HTML output: `grep -c '<h1' dist/alternatives/<slug>/index.html` — must be >0
+- [ ] `docs/seo-machine.md` tracker row updated in same commit
+
+## Astro-specific advantages
+
+- **Zero JS by default.** Marketing pages ship pure HTML/CSS — fastest possible LCP, best Core Web Vitals.
+- **Content collections enforce schema** — typos in data files fail the build.
+- **MDX is first-class** — playbooks can use React/Vue/Svelte components inline without bundle overhead.
+
+## Astro-specific gotchas
+
+- **Don't use client-side React for marketing copy.** Use Astro components or framework components with `client:visible` only for interactive widgets, never for static text.
+- **`getStaticPaths` runs at build time.** Adding a new entry requires a rebuild + redeploy. Plan to deploy on every phase merge.
+- **`Astro.glob` is deprecated in v4+** — use content collections.

package/skills/seo-machine/references/stacks/detection.md

@@ -0,0 +1,61 @@
+# Stack Detection
+
+Goal: pick the right adapter reference file before generating any pages.
+
+## Signal table
+
+Run from the repo root. First match wins; if none match, fall back to `markdown-fallback.md`.
+
+| Signal | Adapter |
+|---|---|
+| `Gemfile` contains `inertia_rails` | `rails-inertia.md` |
+| `Gemfile` contains `rails` (no inertia) | `rails-erb.md` (or `markdown-fallback.md` if not present) |
+| `package.json` has `next` in deps + `app/` directory present | `nextjs.md` (App Router) |
+| `package.json` has `next` in deps + `pages/` directory present | `nextjs-pages.md` (or `nextjs.md` with a Pages-router note) |
+| `astro.config.*` exists | `astro.md` |
+| `package.json` has `@remix-run/*` | `remix.md` (or `markdown-fallback.md`) |
+| `nuxt.config.*` exists | `nuxt.md` (or `markdown-fallback.md`) |
+| `svelte.config.*` exists + SvelteKit deps | `sveltekit.md` (or `markdown-fallback.md`) |
+| `_config.yml` (Jekyll) | `markdown-fallback.md` with Jekyll frontmatter notes |
+| `config.toml` + Hugo signals | `markdown-fallback.md` with Hugo frontmatter notes |
+| `gatsby-config.*` | `markdown-fallback.md` (Gatsby's prog-page API works with markdown) |
+| None of the above | `markdown-fallback.md` |
+
+## What to capture once detected
+
+Add to `.seo/config.json`:
+
+```json
+{
+  "stack": "nextjs-app-router",
+  "language": "tsx",
+  "marketing_route_prefix": "src/app",
+  "marketing_layout": "src/app/(marketing)/layout.tsx",
+  "components_dir": "src/components/marketing",
+  "data_dir": "src/data/seo",
+  "sitemap_path": "src/app/sitemap.ts",
+  "robots_path": "public/robots.txt",
+  "tailwind_config": "tailwind.config.ts",
+  "ahrefs_project_id": null,
+  "roadmap_path": "docs/seo-machine.md"
+}
+```
+
+This config is read by every phase. If a value is null, the phase asks once and persists.
+
+## Ambiguity resolution
+
+When two adapters could match (e.g. Next.js with both `app/` AND `pages/` directories, common during migrations), ask the user via `AskUserQuestion`:
+
+- "I see both `app/` and `pages/` directories. Which is the active marketing surface?"
+
+Never assume. Use the answer to pick the adapter and write it to `.seo/config.json`.
+
+## Marketing-pages-in-app vs marketing-pages-in-separate-repo
+
+Both are valid. Ask if there's ambiguity:
+
+- **In-app marketing** (this skill's reference repo): marketing controller/pages live alongside the product. `/alternatives/*` is served by the same Rails app as the product dashboard.
+- **Separate marketing site**: a different repo (`marketing.example.com`) shipped to a different host (Vercel, Netlify, Cloudflare Pages). Often a static-site generator.
+
+For separate marketing sites, this skill should be run *from the marketing-site repo*, not from the product app repo. Confirm if there's any doubt.

package/skills/seo-machine/references/stacks/markdown-fallback.md

@@ -0,0 +1,181 @@
+# Stack adapter — Markdown fallback (universal)
+
+When the framework isn't directly supported, emit content as markdown files with structured frontmatter. The user wires them into their templating layer once; the skill keeps producing markdown for every phase after.
+
+## File layout (universal)
+
+```
+content/seo/
+├── alternatives/
+│   ├── hootsuite.md
+│   ├── buffer.md
+│   └── ...
+├── for/
+│   ├── agencies.md
+│   ├── social-listening.md
+│   └── ...
+├── compare/
+│   ├── buffer-vs-hootsuite.md
+│   └── ...
+└── playbooks/
+    ├── b2b-social-media-strategy.mdx
+    └── ...
+```
+
+## Frontmatter schemas
+
+### `content/seo/alternatives/<slug>.md`
+
+```yaml
+---
+slug: hootsuite
+competitor_name: Hootsuite
+meta_title: "Hootsuite Alternative — ExampleCo (free, $25/mo Pro)"
+meta_description: "Looking for a Hootsuite alternative? ExampleCo is the lightweight social monitoring tool with a free tier — no $249/mo Enterprise pricing."
+canonical: "https://example.com/alternatives/hootsuite"
+hero_eyebrow: "Hootsuite alternative"
+hero_h1: "Looking for a Hootsuite alternative?"
+hero_lede: "..."
+table_h2: "Best Hootsuite alternatives in 2026"
+table_lede: "..."
+comparison_rows:
+  - feature: "Free plan"
+    yours: { state: yes,  note: "Free forever for 1 X account" }
+    theirs: { state: no, note: "Discontinued in 2023" }
+  - feature: "Starting price"
+    yours: { state: text, note: "$25/mo Pro" }
+    theirs: { state: text, note: "$249/mo Professional" }
+  # ... ≥10 rows total
+switch_reasons:
+  - icon: bolt
+    title: "Reply in 30 seconds, not 5 minutes"
+    body: "..."  # ≥40 words
+  # ... 4 total
+honesty_rows:
+  - feature: "Multi-platform scheduling"
+    body: "..."  # ≥30 words
+  # ... 3-4 total
+faqs:
+  - question: "Why did Hootsuite end its free plan?"
+    answer: "..."  # ≥40 words
+  # ... 4-6 total
+cta_h2: "..."
+cta_lede: "..."
+related_internal_links:
+  alternatives: [buffer, sprout-social]
+  features: [twitter-monitoring]
+  tools: [reply-templates]
+schemas:
+  - FAQPage
+  - SoftwareApplication
+  - BreadcrumbList
+---
+
+(Body is optional with this shape — the frontmatter contains all rendered data.)
+```
+
+### `content/seo/for/<slug>.md`
+
+Same idea — full `ForData` shape as frontmatter:
+
+```yaml
+---
+slug: agencies
+name: Agencies
+meta_title: "Social media tools for agencies — ExampleCo"
+hero_eyebrow: "For agencies"
+hero_h1: "Social media monitoring built for agencies"
+hero_lede: "..."
+pain_h2: "The agency reality"
+pains:
+  - title: "..."
+    body: "..."
+solution_h2: "..."
+solutions:
+  - icon: bolt
+    title: "..."
+    body: "..."
+faqs: [...]
+related_internal_links:
+  features: [twitter-monitoring, brand-monitoring]
+  tools: [hashtag-generator, share-of-voice]
+  siblings: [freelancers]
+---
+```
+
+### `content/seo/playbooks/<slug>.mdx`
+
+Playbooks are different — frontmatter holds metadata, body holds the 2,500+ word prose:
+
+```mdx
+---
+slug: b2b-social-media-strategy
+title: "B2B social media strategy: a 2,500-word playbook"
+meta_title: "B2B social media strategy — ExampleCo playbook"
+meta_description: "..."
+date_published: 2026-01-15
+date_modified: 2026-01-15
+read_time_min: 18
+related_internal_links:
+  features: [twitter-monitoring, brand-monitoring, linkedin-inbox]
+  tools: [reply-templates, share-of-voice]
+  for_pages: [b2b-saas, agencies]
+  alternatives: [hootsuite]
+---
+
+# B2B social media strategy: a 2,500-word playbook
+
+## Section 1 — the problem framing
+
+Body content here.
+
+## Section 2 — the mental model
+...
+```
+
+## How the user wires this into their template
+
+After the skill writes its first markdown file, hand off with this note:
+
+> The skill writes content as markdown to `content/seo/`. You'll need to wire your framework to read these files and render them. Common patterns:
+>
+> - **Hugo:** drop the files in `content/seo/alternatives/`, use a custom layout per content type
+> - **Jekyll:** use collections (`_alternatives/`, etc.) configured in `_config.yml`
+> - **Eleventy:** use a `_data/` directory or collection front-matter
+> - **Gatsby:** source-filesystem plugin + `createPages` in `gatsby-node.js`
+> - **VitePress/Docusaurus:** treat as MDX pages
+> - **WordPress:** use a custom theme that parses these or import as posts
+>
+> Once wired, every subsequent phase just adds another file in the same directory. The skill handles the data; you handle the rendering.
+
+## Sitemap (universal)
+
+Most SSG frameworks generate sitemaps automatically once content is in the right collection. If yours doesn't:
+
+```
+content/seo/sitemap-data.yaml         # generated by skill, alphabetical
+```
+
+Then have your build step emit `/sitemap.xml` from this file. Example shape:
+
+```yaml
+last_modified: 2026-MM-DD
+urls:
+  - loc: https://example.com/alternatives/hootsuite
+    changefreq: monthly
+    priority: 0.8
+  - loc: https://example.com/for/agencies
+    changefreq: monthly
+    priority: 0.8
+  # ...
+```
+
+## File-write checklist for any phase (markdown mode)
+
+- [ ] New markdown file at the right `content/seo/<pattern>/<slug>.md` path
+- [ ] Frontmatter validates against the pattern schema
+- [ ] Sibling files updated to add the new slug under `related_internal_links` (≥2 spots)
+- [ ] `sitemap-data.yaml` updated if used
+- [ ] User's build step ran successfully (rebuild + verify HTML output)
+- [ ] HTML output: `grep -c '<h1' build-output/alternatives/<slug>/index.html` — must be >0
+- [ ] `docs/seo-machine.md` tracker row updated in same commit

package/skills/seo-machine/references/stacks/nextjs.md

@@ -0,0 +1,108 @@
+# Stack adapter — Next.js (App Router)
+
+For Next.js 13+ with the `app/` directory. For Pages Router, see `nextjs-pages.md`.
+
+## Conventions to use
+
+- **Routes:** file-based via `app/[pattern]/[slug]/page.tsx`. Use `generateStaticParams` for build-time generation.
+- **Data:** TypeScript constants in `src/data/seo/<pattern>.ts`, exported as typed records keyed by slug.
+- **Components:** shared layouts in `src/components/marketing/<Pattern>Layout.tsx`.
+- **Metadata:** Next's `generateMetadata` per route to emit dynamic titles/descriptions/OG.
+- **Sitemap:** `app/sitemap.ts` exporting a function that returns all URLs.
+- **Schema:** JSON-LD via `<Script type="application/ld+json">` in each page component.
+
+## Pattern A — `/alternatives/[slug]/page.tsx`
+
+```
+src/
+├── data/seo/alternatives.ts        # AlternativeData by slug
+├── components/marketing/
+│   └── AlternativeLayout.tsx       # shared layout
+└── app/(marketing)/alternatives/
+    ├── page.tsx                    # /alternatives directory
+    └── [slug]/
+        └── page.tsx                # /alternatives/[slug]
+```
+
+The `[slug]/page.tsx` exports:
+
+- `generateStaticParams()` → returns `Object.keys(ALTERNATIVES).map(slug => ({ slug }))`
+- `generateMetadata({ params })` → returns `{ title, description, openGraph, alternates: { canonical } }`
+- Default export → React component reading `ALTERNATIVES[params.slug]`, rendering `<AlternativeLayout />`, including `<Script>` for JSON-LD
+
+## Pattern B/C — `/for/[slug]/page.tsx`
+
+Same shape as Pattern A but for `USE_CASES` data and `ForLayout`.
+
+## Pattern D — `/compare/[slug]/page.tsx`
+
+Same shape, `COMPARISONS` data, `ComparisonLayout`.
+
+## Pattern E — `/playbooks/[slug]/page.tsx`
+
+Different from A-D — playbooks are long-form components rather than data-driven.
+
+Option 1 (recommended for ≤20 playbooks): one file per playbook, `app/playbooks/[slug]/page.tsx` is a switch / dynamic import based on slug. Each playbook is its own component in `src/content/playbooks/<slug>.tsx`.
+
+Option 2 (for many playbooks): MDX in `src/content/playbooks/<slug>.mdx`, rendered via `next-mdx-remote` or `@next/mdx`. The MDX files can use the `PlaybookLayout` component with frontmatter.
+
+## Sitemap (`app/sitemap.ts`)
+
+```typescript
+import { MetadataRoute } from 'next'
+import { ALTERNATIVES } from '@/data/seo/alternatives'
+import { USE_CASES } from '@/data/seo/use-cases'
+import { COMPARISONS } from '@/data/seo/comparisons'
+import { PLAYBOOKS } from '@/data/seo/playbooks'
+
+const SITE = 'https://example.com'
+const lastModified = new Date('2026-MM-DD')  // bump on every phase merge
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const entries: MetadataRoute.Sitemap = []
+  for (const slug of Object.keys(ALTERNATIVES))   entries.push({ url: `${SITE}/alternatives/${slug}`, lastModified, changeFrequency: 'monthly', priority: 0.8 })
+  for (const slug of Object.keys(USE_CASES))      entries.push({ url: `${SITE}/for/${slug}`,         lastModified, changeFrequency: 'monthly', priority: 0.8 })
+  for (const slug of Object.keys(COMPARISONS))    entries.push({ url: `${SITE}/compare/${slug}`,     lastModified, changeFrequency: 'monthly', priority: 0.7 })
+  for (const slug of Object.keys(PLAYBOOKS))      entries.push({ url: `${SITE}/playbooks/${slug}`,   lastModified, changeFrequency: 'monthly', priority: 0.7 })
+  return entries
+}
+```
+
+## Per-page JSON-LD pattern
+
+```tsx
+<Script
+  id="ld-faqpage"
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "FAQPage",
+      mainEntity: data.faqs.map(f => ({
+        "@type": "Question",
+        name: f.question,
+        acceptedAnswer: { "@type": "Answer", text: f.answer },
+      })),
+    }),
+  }}
+/>
+```
+
+Render in the page component, not the layout. One JSON-LD `<Script>` per schema type.
+
+## File-write checklist for any phase
+
+- [ ] Data entry added to `src/data/seo/<pattern>.ts`
+- [ ] `generateStaticParams` will pick it up (no manual route registration needed)
+- [ ] Sibling page references updated (≥2 spots in other data files)
+- [ ] Sitemap `lastModified` constant bumped
+- [ ] `next build` succeeds and includes the new route in the build manifest
+- [ ] Local SSR check: `curl -s http://localhost:3000/<url> | grep '<h1'` — H1 must be in the response
+- [ ] `docs/seo-sprint.md` tracker row updated in same commit
+
+## App Router gotchas
+
+- **Server components by default** — good for SEO (full HTML in response). Only opt into `"use client"` for islands of interactivity.
+- **Metadata is per-route, not per-layout.** Each `page.tsx` must export `generateMetadata` (or static `metadata`).
+- **Canonical URLs need explicit setting** via `metadata.alternates.canonical`. Next does NOT auto-emit canonical tags.
+- **OG images** — co-locate `opengraph-image.tsx` next to the page if you want dynamic OG via Next's image generation. Otherwise reference a static image URL in `openGraph.images`.