agileflow 3.4.3 → 4.0.0-alpha.10

package/content/plugins/seo/skills/agileflow-seo/references/eeat-framework.md

@@ -0,0 +1,144 @@
+# E-E-A-T Framework Reference
+
+**Load this when:** analyzing content quality, reviewing YMYL pages,
+or recommending content improvements for ranking.
+
+E-E-A-T = **Experience, Expertise, Authoritativeness, Trustworthiness**
+
+Google's Quality Raters use E-E-A-T to evaluate page quality. It's especially
+important for YMYL (Your Money or Your Life) content.
+
+## The four dimensions
+
+### Experience
+
+_Has the author/site actually done this thing?_
+
+Signals:
+
+- First-person accounts ("I tested this for 30 days")
+- Original photos, screenshots, or video
+- Specific details only someone with experience would know
+- Product reviews with personal purchase/use evidence
+- Case studies with real results and numbers
+
+Missing signals: generic descriptions, no original media, "based on research" disclaimers everywhere.
+
+### Expertise
+
+_Does the author have the knowledge to write about this?_
+
+Signals:
+
+- Author bio with relevant credentials, education, or years of experience
+- Citations to primary sources (studies, official docs)
+- Correct use of domain terminology
+- Nuanced takes that show depth (not just surface-level how-tos)
+- Regular publication in the niche
+
+Missing signals: no author attribution, no credentials, shallow coverage, factual errors.
+
+### Authoritativeness
+
+_Is this site/author recognized as a source in this field?_
+
+Signals:
+
+- Backlinks from authoritative sites in the same niche
+- Author cited or quoted by other publications
+- Wikipedia mentions
+- Brand searches (people search for your brand + topic)
+- Mentions in industry publications
+
+Missing signals: no external recognition, no links from topically relevant sites.
+
+### Trustworthiness
+
+_Can I trust this site and its content?_
+
+Signals:
+
+- HTTPS
+- Clear contact information and physical address
+- About page with team/company info
+- Privacy policy and terms of service
+- Transparent disclosure of affiliates, sponsors, AI use
+- Accurate, up-to-date content (no outdated facts)
+- User reviews and ratings (for ecommerce)
+- Corrections policy for mistakes
+
+Missing signals: no contact info, no privacy policy, deceptive design, hidden fees.
+
+## YMYL — highest E-E-A-T requirements
+
+YMYL = pages where wrong information could harm someone's money, health, safety, or wellbeing.
+
+| YMYL category       | Examples                             | E-E-A-T requirement                       |
+| ------------------- | ------------------------------------ | ----------------------------------------- |
+| Medical/health      | Symptoms, treatments, medications    | Medical professional credentials required |
+| Financial           | Investment advice, taxes, insurance  | Financial professional credentials        |
+| Legal               | Legal advice, rights                 | Legal professional credentials            |
+| Safety              | Emergency procedures, product safety | Expert verification                       |
+| News/current events | Breaking news, politics              | Editorial standards, sources              |
+
+For YMYL pages: anonymous content or thin author bios are almost always a ranking problem.
+
+## E-E-A-T by content type
+
+### Blog posts / guides
+
+- Author bio with photo, credentials, and links to social/LinkedIn
+- "Reviewed by" expert if author isn't the domain expert
+- Last updated date (and actually update it)
+- Original research or data where possible
+- Citations to primary sources
+
+### Product pages (ecommerce)
+
+- Detailed product descriptions (not manufacturer copy)
+- Original product photos from multiple angles
+- User reviews with verified purchase signals
+- Clear return/refund policy
+- Stock and shipping information
+
+### Service pages (local/agency)
+
+- Team member profiles with credentials
+- Portfolio/case studies with real results
+- Client testimonials with full names and companies
+- Certifications and awards
+
+### AI-generated content
+
+Google doesn't penalize AI content per se, but AI content often lacks:
+
+- Experience signals (no first-hand accounts)
+- Original data or media
+- Nuance from actual expertise
+
+If publishing AI content: add human expert review, original examples, and real data.
+
+## Quick E-E-A-T audit checklist
+
+```
+Experience
+⬜ Original media (photos, screenshots, video)
+⬜ First-person experience where relevant
+⬜ Specific details only an expert would know
+
+Expertise
+⬜ Author bio with relevant credentials
+⬜ Primary source citations
+⬜ Accurate, up-to-date information
+
+Authoritativeness
+⬜ Backlinks from topically relevant sites
+⬜ Author has external recognition in niche
+
+Trustworthiness
+⬜ HTTPS
+⬜ Clear contact information
+⬜ Privacy policy and terms
+⬜ Affiliate/sponsored disclosure where applicable
+⬜ No deceptive design patterns
+```

package/content/plugins/seo/skills/agileflow-seo/references/keyword-research-guide.md

@@ -0,0 +1,125 @@
+# Keyword Research Guide
+
+**Load this when:** Building a keyword strategy, evaluating keyword difficulty vs. volume tradeoffs, or planning content around search intent.
+
+## Search Intent Types
+
+| Intent                   | Query signal                               | Content match                | Example                                     |
+| ------------------------ | ------------------------------------------ | ---------------------------- | ------------------------------------------- |
+| Informational            | "how to", "what is", "why does"            | Guide, tutorial, explainer   | "how to migrate postgres database"          |
+| Navigational             | Brand name, product name                   | Brand page, docs             | "vercel dashboard login"                    |
+| Commercial investigation | "best", "vs", "review", "alternatives"     | Comparison, review, listicle | "best CI/CD tools 2025"                     |
+| Transactional            | "buy", "download", "pricing", "free trial" | Landing page, pricing        | "agile project management software pricing" |
+
+**Match content type to intent.** Writing a blog post for a transactional query loses to landing pages. Writing a landing page for informational queries loses to tutorials.
+
+---
+
+## Difficulty vs. Volume Tradeoffs
+
+| Scenario                     | Strategy                                                         |
+| ---------------------------- | ---------------------------------------------------------------- |
+| High volume, high difficulty | Only target if strong domain authority (DA 50+). Long-term play. |
+| High volume, low difficulty  | Prioritize — best ROI, target immediately                        |
+| Low volume, low difficulty   | Long-tail wins; high conversion, compound over time              |
+| Low volume, high difficulty  | Skip — too expensive for too little reward                       |
+
+### Difficulty thresholds by domain authority
+
+| Your DA | Realistic KD target |
+| ------- | ------------------- |
+| 0–20    | KD 0–20             |
+| 20–40   | KD 0–35             |
+| 40–60   | KD 0–50             |
+| 60–80   | KD 0–65             |
+| 80+     | Any                 |
+
+---
+
+## Long-Tail Strategy
+
+### Why long-tail
+
+- 70% of all searches are long-tail (4+ words)
+- Lower KD, lower competition
+- Higher purchase intent (more specific = closer to decision)
+- Compound: 100 pages at 200 visits/month > 1 page at 10,000/month (often easier to achieve)
+
+### Long-tail expansion patterns
+
+```
+Seed keyword: "project management"
+→ Long-tail: "project management for remote teams"
+→ Longer: "project management for remote engineering teams"
+→ Question: "how to manage remote engineering teams effectively"
+→ Comparison: "jira vs linear for remote teams"
+→ Local: "project management software for startups in NYC"
+```
+
+### Tools for long-tail discovery
+
+- Google autocomplete and "People Also Ask"
+- Ahrefs / Semrush: Questions filter
+- AnswerThePublic
+- Reddit / Quora searches
+- Your own site search queries
+
+---
+
+## Keyword Clustering
+
+Group keywords by semantic similarity and intent before mapping to content:
+
+```
+Cluster: "CI/CD tools"
+├── "best CI/CD tools" [commercial, high vol]
+├── "CI/CD tools comparison" [commercial, med vol]
+├── "CI/CD tools for small teams" [commercial, low vol, low KD]
+├── "what is CI/CD" [informational, high vol]
+└── "CI/CD pipeline tutorial" [informational, high vol]
+
+One cluster = one content piece (or hub + spokes)
+```
+
+**Rule:** Never create two pages targeting the same cluster — they cannibalize each other.
+
+---
+
+## Keyword Metrics Reference
+
+| Metric                  | Tool                   | What it tells you                    |
+| ----------------------- | ---------------------- | ------------------------------------ |
+| Search volume           | Ahrefs, Semrush, GKP   | Monthly search demand                |
+| Keyword difficulty (KD) | Ahrefs, Semrush        | How hard to rank (0–100)             |
+| CPC                     | Google Keyword Planner | Commercial value proxy               |
+| SERP features           | Ahrefs, Semrush        | Featured snippets, image packs, etc. |
+| Click-through rate      | Ahrefs (CTR curve)     | Actual clicks vs. searches           |
+| Position                | GSC                    | Current ranking                      |
+
+---
+
+## SERP Feature Targets
+
+| Feature          | How to target                                                         |
+| ---------------- | --------------------------------------------------------------------- |
+| Featured snippet | Answer the question directly in first 40–60 words; use H2 as question |
+| People Also Ask  | Answer related questions in FAQ section                               |
+| Image pack       | Alt text + filename match keyword; compress images; structured data   |
+| Video carousel   | YouTube video with keyword in title + description                     |
+| Knowledge panel  | Schema markup + Wikipedia / Wikidata presence                         |
+| Local pack       | Google Business Profile + local SEO signals                           |
+
+---
+
+## Keyword Prioritization Scorecard
+
+Score each keyword candidate 1–5:
+
+| Factor               | Weight | Scoring notes                                |
+| -------------------- | ------ | -------------------------------------------- |
+| Search volume        | 20%    | 5 = >10k/mo, 1 = <100/mo                     |
+| KD vs. your DA       | 30%    | 5 = KD well below DA, 1 = KD >> DA           |
+| Business relevance   | 30%    | 5 = core ICP query, 1 = tangentially related |
+| Conversion potential | 20%    | 5 = transactional, 1 = pure informational    |
+
+**Priority score = Σ(score × weight)** — target highest scores first.

package/content/plugins/seo/skills/agileflow-seo/references/schema-types.md

@@ -0,0 +1,139 @@
+# Schema Markup Types Reference
+
+**Load this when:** recommending structured data, validating JSON-LD,
+or generating schema markup for a specific business type.
+
+## Which schema type for which site
+
+| Site type           | Primary schema             | Supporting schema                          |
+| ------------------- | -------------------------- | ------------------------------------------ |
+| SaaS / Software     | `SoftwareApplication`      | `Organization`, `FAQPage`, `HowTo`         |
+| Ecommerce / store   | `Product`, `Offer`         | `BreadcrumbList`, `Organization`, `Review` |
+| Local business      | `LocalBusiness` (subtype)  | `OpeningHoursSpecification`, `Review`      |
+| Blog / content      | `Article` or `BlogPosting` | `Person` (author), `BreadcrumbList`        |
+| News publisher      | `NewsArticle`              | `Organization`, `Person`                   |
+| Recipe site         | `Recipe`                   | `HowToStep`, `AggregateRating`             |
+| Job listings        | `JobPosting`               | `Organization`                             |
+| Events              | `Event`                    | `Place`, `Offer`                           |
+| Courses / education | `Course`                   | `EducationalOrganization`                  |
+| FAQ pages           | `FAQPage`                  | —                                          |
+| How-to guides       | `HowTo`                    | `HowToStep`, `HowToTool`                   |
+
+## Google-supported rich result types (confirmed)
+
+Only these produce rich results in Google Search:
+
+| Schema type                  | Rich result                          | Eligibility requirements                              |
+| ---------------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `Article` / `NewsArticle`    | Top stories carousel                 | AMP or signed exchange (news)                         |
+| `Product`                    | Price, availability, ratings in SERP | Required: name, image, description                    |
+| `Recipe`                     | Cooking carousel                     | Required: name, image, steps                          |
+| `FAQPage`                    | Expandable FAQ in SERP               | Genuine FAQ content, not SEO spam                     |
+| `HowTo`                      | Step-by-step in SERP                 | Clear steps with instructions                         |
+| `Event`                      | Event dates in SERP                  | Required: name, startDate, location                   |
+| `JobPosting`                 | Job listing in SERP                  | Required: title, hiringOrganization, datePosted       |
+| `LocalBusiness`              | Knowledge panel                      | Required: name, address, telephone                    |
+| `Review` / `AggregateRating` | Star ratings in SERP                 | Cannot be self-reviews                                |
+| `VideoObject`                | Video thumbnail                      | Required: name, description, thumbnailUrl, uploadDate |
+| `BreadcrumbList`             | Breadcrumb trail in URL              | Page hierarchy                                        |
+| `SiteLinksSearchBox`         | Search box in SERP                   | Large sites only                                      |
+
+## JSON-LD template: Product
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "image": ["https://example.com/image.jpg"],
+  "description": "Product description",
+  "sku": "SKU123",
+  "brand": {
+    "@type": "Brand",
+    "name": "Brand Name"
+  },
+  "offers": {
+    "@type": "Offer",
+    "url": "https://example.com/product",
+    "priceCurrency": "USD",
+    "price": "29.99",
+    "availability": "https://schema.org/InStock",
+    "itemCondition": "https://schema.org/NewCondition"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.5",
+    "reviewCount": "89"
+  }
+}
+```
+
+## JSON-LD template: LocalBusiness
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Business Name",
+  "image": "https://example.com/logo.jpg",
+  "telephone": "+1-555-555-5555",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main St",
+    "addressLocality": "City",
+    "addressRegion": "ST",
+    "postalCode": "12345",
+    "addressCountry": "US"
+  },
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": 40.7128,
+    "longitude": -74.006
+  },
+  "url": "https://example.com",
+  "openingHoursSpecification": [
+    {
+      "@type": "OpeningHoursSpecification",
+      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
+      "opens": "09:00",
+      "closes": "17:00"
+    }
+  ]
+}
+```
+
+## JSON-LD template: FAQPage
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "Question text here?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Answer text here."
+      }
+    }
+  ]
+}
+```
+
+## Common schema mistakes
+
+| Mistake                             | Problem                  | Fix                                                   |
+| ----------------------------------- | ------------------------ | ----------------------------------------------------- |
+| Markup not matching visible content | Manual action risk       | Markup must match what users see                      |
+| Self-reviews in `AggregateRating`   | Policy violation         | Only use genuine third-party reviews                  |
+| `FAQPage` on every page for SEO     | Spam — Google may ignore | Only on genuine FAQ pages                             |
+| Missing required properties         | Rich result won't show   | Check Google's docs for required fields               |
+| Multiple `@type` conflicts          | Parser confusion         | Use array: `"@type": ["LocalBusiness", "Restaurant"]` |
+| Schema on 404 / thin pages          | Wasted markup            | Only add schema to quality pages                      |
+
+## Validation tools
+
+- **Google Rich Results Test**: test.google.com/rich-results — shows if eligible for rich results
+- **Schema Markup Validator**: validator.schema.org — general schema validity
+- **Google Search Console**: search.google.com/search-console → Enhancements — field data on schema errors

package/content/plugins/seo/skills/agileflow-seo/references/technical-seo-checklist.md

@@ -0,0 +1,139 @@
+# Technical SEO Checklist
+
+**Load this when:** Auditing technical SEO, diagnosing crawl or indexation issues, or building an SEO-ready site.
+
+## Crawlability
+
+- [ ] `robots.txt` exists at `/robots.txt` and is valid
+- [ ] `robots.txt` does not block important resources (CSS, JS, images)
+- [ ] No `noindex` directives on pages that should be indexed
+- [ ] No `Disallow: /` in production `robots.txt` (common staging leftover)
+- [ ] Internal links use crawlable `<a href>` tags (not JS-only navigation)
+- [ ] No crawl traps: infinite pagination, session ID URLs, calendar archives
+- [ ] Site crawl depth: important pages reachable within 3 clicks from homepage
+
+### robots.txt format
+
+```
+User-agent: *
+Disallow: /admin/
+Disallow: /api/
+Allow: /api/public/
+
+User-agent: Googlebot
+Disallow: /staging/
+
+Sitemap: https://example.com/sitemap.xml
+```
+
+---
+
+## Indexation
+
+- [ ] XML sitemap exists and submitted to Google Search Console
+- [ ] Sitemap includes only canonical, indexable URLs
+- [ ] Sitemap excludes 404s, 301s, and `noindex` pages
+- [ ] Sitemap updated automatically on content publish
+- [ ] `<link rel="canonical">` on every page pointing to the preferred URL
+- [ ] No duplicate content from `www` vs. non-`www` (redirect to one)
+- [ ] No duplicate content from `http` vs. `https` (redirect to HTTPS)
+- [ ] No duplicate content from trailing slash vs. no trailing slash
+
+### Canonical tag format
+
+```html
+<link rel="canonical" href="https://example.com/page/" />
+```
+
+---
+
+## URL Structure
+
+| Best practice                | Rule                                                           |
+| ---------------------------- | -------------------------------------------------------------- |
+| Use hyphens, not underscores | `/my-page` not `/my_page`                                      |
+| Lowercase only               | `/about` not `/About`                                          |
+| Short and descriptive        | `/blog/seo-guide` not `/blog/post-123-seo-guide-for-beginners` |
+| Include keyword              | `/blog/technical-seo-checklist`                                |
+| No stop words                | Avoid "a", "the", "and" where possible                         |
+| Consistent trailing slash    | Pick one, redirect the other, use canonical                    |
+
+---
+
+## HTTPS and Security
+
+- [ ] Site fully on HTTPS with valid certificate
+- [ ] No mixed content (HTTP resources on HTTPS pages)
+- [ ] HSTS header set
+- [ ] Certificate is not expiring within 30 days
+- [ ] HTTPS redirect chain is a single 301 (not 301 → 301 → 200)
+
+---
+
+## Page Speed (Technical SEO Impact)
+
+- [ ] Core Web Vitals passing (LCP <2.5s, INP <200ms, CLS <0.1)
+- [ ] Time to First Byte (TTFB) <800ms
+- [ ] Server-side or edge caching for static/semi-static pages
+- [ ] Images lazy-loaded, correctly sized
+- [ ] `<link rel="preload">` on LCP element (hero image, critical font)
+- [ ] No render-blocking scripts in `<head>` without `async` or `defer`
+
+---
+
+## Mobile
+
+- [ ] Responsive design (passes Google Mobile-Friendly Test)
+- [ ] Viewport meta tag: `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- [ ] Tap targets ≥48px
+- [ ] Font size ≥16px for body text
+- [ ] No horizontal scroll on mobile
+- [ ] Mobile and desktop serve same content (no mobile-only exclusions)
+
+---
+
+## Structured Data
+
+- [ ] `Organization` schema on homepage
+- [ ] `WebSite` schema with `SearchAction` for sitelinks search box
+- [ ] `Article` / `BlogPosting` schema on blog posts
+- [ ] `Product` / `Offer` schema on product pages
+- [ ] `FAQPage` schema on FAQ sections
+- [ ] `BreadcrumbList` schema on deep pages
+- [ ] No schema errors (validate at schema.org/validator or Rich Results Test)
+
+---
+
+## International SEO
+
+- [ ] `hreflang` tags for multilingual content
+- [ ] `hreflang` includes `x-default` for fallback
+- [ ] Language codes are ISO 639-1 (e.g., `en`, `fr`, not `english`)
+- [ ] Regional targeting set in Google Search Console per property
+
+---
+
+## Redirects
+
+| Rule                                | Requirement                      |
+| ----------------------------------- | -------------------------------- |
+| Use 301 for permanent moves         | Not 302 (temporary)              |
+| No redirect chains >2 hops          | A → B → C should be A → C        |
+| No redirect loops                   | A → B → A                        |
+| 404s on truly gone pages            | Don't 301 to homepage            |
+| Verify old URL equity passes to new | Check crawl tool after migration |
+
+---
+
+## Core Technical SEO Monitoring
+
+| What to monitor         | Tool                    | Frequency    |
+| ----------------------- | ----------------------- | ------------ |
+| Crawl errors            | Google Search Console   | Weekly       |
+| Index coverage          | Google Search Console   | Weekly       |
+| Core Web Vitals (field) | CrUX / GSC              | Monthly      |
+| Sitemap errors          | GSC / crawl tool        | Monthly      |
+| Broken internal links   | Screaming Frog / Ahrefs | Monthly      |
+| New 404s                | GSC                     | Weekly       |
+| Soft 404s               | GSC                     | Monthly      |
+| Manual actions          | GSC                     | Weekly alert |

package/content/plugins/seo/skills/agileflow-seo/workflows/audit.md

@@ -0,0 +1,98 @@
+# Audit Workflow — Full Website SEO Audit
+
+**Triggers:** "run an SEO audit", "audit my website for SEO", "what are my SEO issues", "SEO health score", "check SEO for example.com", "full SEO review"
+
+**Goal:** Deploy 6 SEO analyzers in parallel against a website, synthesize results into a weighted health score (0–100), and produce a prioritized action plan with specific, actionable fixes.
+
+## Inputs needed
+
+| Input     | Required | How to get it                                                         |
+| --------- | -------- | --------------------------------------------------------------------- |
+| URL       | Yes      | Ask for it if not provided                                            |
+| site type | No       | Auto-detect from homepage, or already captured in opening flow        |
+| context   | No       | Traffic level, recent changes, target keywords — ask conversationally |
+
+## Steps
+
+1. **If URL is not provided**, ask: _"What's the URL? I'll fetch your site and start the analysis."_ Accept homepage or any page. Don't offer fake options for this — just ask for the URL.
+
+2. **Gather context** (2-3 questions, conversational not interrogation):
+   - _"Roughly how much organic traffic does the site get per month? And have you made any big changes recently — migration, redesign, new CMS?"_ — traffic level affects prioritization, recent changes are the #1 cause of drops
+   - If they have target keywords: _"Any specific pages or keywords you want me to focus on?"_
+   - Skip these if they already answered in the opening flow
+
+3. **Fetch the homepage** to detect site type (e-commerce, SaaS, local business, publisher, etc.) if not already known. Also fetch `robots.txt` and `sitemap.xml`.
+
+4. **Deploy all 6 analyzers simultaneously** — default to quick depth, no need to ask:
+   - **Technical** — crawlability, indexability, HTTPS, redirects, canonical tags, mobile viewport, Core Web Vitals indicators
+   - **Content** — title tags, meta descriptions, heading structure, content quality, E-E-A-T signals, word count by page type
+   - **Schema** — structured data presence, correct schema types for detected business type, markup validity
+   - **Performance** — page speed signals, LCP, CLS, FID, render-blocking resources
+   - **Images** — alt text coverage, file sizes, next-gen formats (WebP/AVIF), lazy loading
+   - **Sitemap** — presence, coverage, freshness, consistency with robots.txt
+
+5. **Apply business-type-specific benchmarks.** E-commerce needs Product schema; local business needs LocalBusiness schema; publisher needs Article schema and E-E-A-T signals.
+
+6. **Weighted scoring:** Technical 20%, Content 20%, Schema 15%, Performance 15%, Images 15%, Sitemap 15%.
+
+7. **Present the SEO Health Score (0–100)** with category breakdown:
+
+   ```
+   Site: example.com
+   Business type: SaaS
+
+   Category       Score   Top Issue
+   Technical       61      12 pages missing canonical tags
+   Content         74      Meta descriptions missing on 8 pages
+   Schema          45      No structured data found — rich results blocked
+   Performance     82      LCP 3.1s — above 2.5s threshold
+   Images          58      31 images missing alt text
+   Sitemap         90      —
+
+   Overall: 68/100 — needs work
+   ```
+
+8. **Prioritized action plan:**
+   - **P0** (score < 60 or blocking issue): Fix immediately — indexing, canonical, noindex errors
+   - **P1** (quick wins): High ROI, low effort — missing schema, alt text, meta descriptions
+   - **P2** (structural): Performance, content depth, E-E-A-T signals
+   - **P3** (fine-tuning): Sitemap freshness, internal linking optimization
+
+9. **Guide next step with AskUserQuestion** — make it specific to actual findings:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Audit complete. {site} scored {X}/100 — {critical} critical issues, {high} high. Biggest blocker: {top_issue}.",
+  "header": "What to tackle",
+  "multiSelect": false,
+  "options": [
+    {"label": "Fix {top_p0_issue} now (Recommended)", "description": "{specific fix + expected impact, e.g. 'Add canonical tags to 12 pages — prevents Google from choosing the wrong version to rank'}"},
+    {"label": "Generate {missing_schema_type} JSON-LD markup", "description": "I'll produce copy-paste structured data for your {page_type} — takes 2 minutes to add"},
+    {"label": "Deep-dive into {lowest_category} ({score}/100)", "description": "Worst area — I'll give you implementation-ready fixes for every finding"},
+    {"label": "Analyze a specific page in depth", "description": "6-dimension report card on your most important page — homepage, pricing, or top landing page"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Customize every option — don't show schema option if schema scored 90+. Don't show the page analysis if they specifically said they want site-wide fixes.
+
+## Output
+
+SEO Health Score (0–100) with per-category scores. Prioritized action plan (P0–P3). Business-type-specific recommendations. Baseline for tracking improvement over time.
+
+## Fallbacks
+
+**If AskUserQuestion is unavailable:**
+Present options as a numbered list. Example:
+
+```
+What would you like to tackle first?
+1. Fix the P0 issues now
+2. Generate missing schema markup
+3. Deep-dive into the lowest-scoring category
+```
+
+**If agent spawning is unavailable:**
+Run each analysis inline sequentially using the reference files in `references/`. Consolidate into the same output format — same result, just slower.