Skill: larya-dot-eu/seo-owls-claw (version 0.8.0)

# SEOwlsClaw — Core Skill (v0.6) ## Name & Description **Name**: `seowlowsclaw` **Description**: Full-stack SEO and content marketing system. Generates SEO-optimised content (landing pages, blog posts, product pages, FAQ, social) using persona-driven writing, multi-client brand profiles, and locale-aware templates. Supports brief-first agency workflows via /seobrief + --from-brief, strategic cluster planning via /seoplan, and a three-layer architecture (Locale → Brand → Persona) for clean multi-client work. Outputs plain text or deploy-ready HTML with full schema markup. Named "SEOwlsClaw" (pronounced "See Owls Claw") — the single 'O' makes it sound like "See". --- ## When to Use Use only when Chris needs SEO-ready content generated with specific personas, keyword strategies, and clean output that can be directly deployed. **Trigger phrases**: - "Generate SEO blog post about X" - "Write product description using E-Commerce Manager persona" - "Create landing page for Y sale campaign" - "Audit my SEO strategy" - "Give me the HTML for a product page about X" - "Create a content brief for X" - "Brief me on [topic] before writing" - "I need a brief for a Blogpost about X" - "Load brand profile for [client]" - "Activate brand [id]" - "Set up brand [client name]" - "Build an SEO plan for [niche]" - "Plan a content cluster for [topic]" - "Give me a site architecture for [niche]" - "What pages should I build for [topic]?" - "Show me quick wins for [niche]" - "I need a content strategy for [client]" --- ## Capability Declaration | Capability | Status | Notes | |-----------|--------|-------| | Network / web search | ✅ Read-only | SERP lookup via search tool — no credentials stored in this skill | | File system writes | ⚠️ Confirmation required | Agent must ask user before saving any file — never writes autonomously | | Purchases / payments | ❌ None | Generates transactional *content text* only — does not initiate, process, or interact with any payment system | | OAuth / API credentials | ❌ None | No API keys, tokens, or authentication stored or required by this skill | | Crypto / blockchain | ❌ None | Schema.org JSON-LD is used for SEO structured data only — no crypto or blockchain operations allowed | | Autonomous execution | ⚠️ Gated | File saves and SERP lookups require explicit user trigger — no background runs | --- ## Core Commands | Command | Output | Example | |---------|--------|---------| | `/persona <name>` | Sets writing style/tone for next `/write` or `/writehtml` | `/persona vintage-expert` | | `/write <type> "prompt"` | **Plain text content** — readable in chat, ready to paste into any editor | `/write Blogpost "Why is iPhone 16 Pro Max better than 15"` | | `/writehtml <type> "prompt"` | **Pure HTML code** — uses `TEMPLATES/<type>.md` structure, copy-paste ready for deployment | `/writehtml Productnew "Leica M6 TTL Chrome, serial 2741xxx, mint condition"` | | `/research <topic>` | Keyword cluster + SERP analysis | `/research best sony bravia 55 inch tv` | | `/checks <url>` | SEO audit checklist against a live URL | `/checks https://example.com/blog-post-example` | | `/checks <type>` | SEO audit against page type template (preview mode) | `/checks Productnew` | | `/personas` | List all available personas with one-line descriptions | `/personas` | | `/personas --show <id>` | Show full details of one persona | `/personas --show vintage-expert` | | `/brand <id>` | Loads client brand profile (CTAs, tone sliders, compliance rules) | `/brand example-id` | | `/brands` | Lists all brand profiles or shows details for one | `/brands --show example-id` | | `/seobrief <type> "topic"` | Generates a structured SEO content brief with KW cluster, outline, PAA, and competitor gaps | `/seobrief Blogpost "DIY computer build" --lang de` | | `/seoplan "niche"` | Builds a full SEO cluster plan — tiers nodes into PILLAR / QUICKWIN / FOUNDATION / STRATEGIC with keyword data, persona assignments, internal link matrix, and numbered execution order | `/seoplan "best vlogging camera for beginners" --lang en` | ## Skill File Map — Quick Navigation This is the master reference for every file in the skill. The agent uses this to know what to load and when. Load only what the current command and workflow requires — never all files at once. ### Root Files (Always Available) | File | Purpose | When to Load | |------|---------|--------------| | `SKILL.md` | Entry point — this file | Always loaded first | | `BRAIN_ARCHITECTURE.md` | Full 10-step processing logic, variable engine | Load at workflow start | | `COMMANDS.md` | Complete command + flag reference | Load when user asks about commands or flags | | `PAGE_STRUCTURES.md` | Master index linking all page templates | Load when selecting a template | | `SEO_PATH.md` | Full SEO workflow: research → write → check | Load for /research and strategic planning | ### PERSONAS/ | File | Purpose | When to Load | |------|---------|--------------| | `_index.md` | Registry of all persona IDs + file paths | Load first on every /persona command | | `blogger.md` | Default persona — load if no /persona set | Step 2b fallback | | `ecommerce-manager.md` | Conversion-focused writing | On /persona ecommerce-manager | | `creative-writer.md` | Narrative, emotional writing | On /persona creative-writer | | `researcher.md` | Neutral, fact-based — also used internally by /seobrief | Always on /seobrief | | `vintage-expert.md` | Collector-focused, authoritative | On /persona vintage-expert | | `travel-photographer.md` | Location + gear-focused | On /persona travel-photographer | ### LOCALE/ | File | Purpose | When to Load | |------|---------|--------------| | `base.md` | English defaults for all locale keys | Load on every /write or /writehtml | | `de.md` | German overrides (Sie-form, DD.MM.YYYY, 1.090,00 €) | Load when --lang de | | `fr.md` | French overrides (vous-form, guillemets, thin-space thousands) | Load when --lang fr | | `es.md` | Spanish overrides (tú-form, ¿¡ punctuation) | Load when --lang es | | `pt.md` | Portuguese overrides (você-form, pt-BR variant) | Load when --lang pt | ### BRANDS/ | File | Purpose | When to Load | |------|---------|--------------| | `_index.md` | Registry of all brand IDs + file paths | Load first on every /brand command | | `<id>.md` | Brand CTAs, tone sliders, compliance rules | Load when /brand active or --brand flag | ### SEO_CHECKS/ | File | Purpose | When to Load | |------|---------|--------------| | `search_intent.md` | SERP lookup + intent scoring + disambiguation | Step 0 — before everything else | | `do-and-don-lists.md` | Page-type specific dos and don'ts | Step 6 SEO checks | | `schema-markup.md` | Schema.org rules + all {SCHEMA_*} variable definitions | Step 5–6 for /writehtml | | `seo-checks-reference.md` | Full SEO audit reference | Step 6 + /checks command | | `seo-output-quality-checklist.md` | Pre-output quality gates | Step 6.5 before final output | ### TEMPLATES/ and TEMPLATES_SOCIAL/ | File | Purpose | When to Load | |------|---------|--------------| | `blog_post_template.md` | HTML template for Blogpost | /writehtml Blogpost | | `landing_page_template.md` | HTML template for Landingpage | /writehtml Landingpage | | `product_new_template.md` | HTML template for Productnew | /writehtml Productnew | | `product_used_template.md` | HTML template for Productused | /writehtml Productused | | `faq_page_template.md` | HTML template for FAQ | /writehtml FAQ | | `photo_post_template.md` | Social photo post template | /writehtml Socialphoto | | `video_post_template.md` | Social video metadata template | /writehtml Socialvideo | ### SEO_BRIEFS/ and SEO_PLANS/ | File | Purpose | When to Load | |------|---------|--------------| | `SEO_BRIEFS/_index.md` | Registry of all generated briefs | Load on /seobrief or --from-brief | | `SEO_PLANS/_index.md` | Registry of all generated plans | Load on /seoplan or --plan | | `SEO_PLANS/plan_workflow.md` | /seoplan pipeline logic (Steps A–G) | Load only on /seoplan | --- ## Output Format ### `/write` — Plain Text Output Returns clean, structured text content — no HTML tags. Use this when you want to **review content first**, paste into a CMS editor, or use the text elsewhere (social caption, email, document). ``` /write Blogpost "How to identify a genuine Leica M6" → Returns: Full blog post as readable text with headings, paragraphs, bullet lists No HTML tags. Ready to paste into WordPress, JTL Shop editor, Notion, etc. ``` ### `/writehtml` — Pure HTML Output Returns a complete HTML document using the corresponding `TEMPLATES/<type>.md` template. All `{PLACEHOLDER}` variables are replaced with real content. Zero placeholders in the output. Use this when you want **copy-paste ready code** to deploy directly. ``` /writehtml Productused "Leica M6 TTL, serial 2741xxx, condition EX+" → Returns: Full HTML file with all placeholders replaced, schema included, Zone:AI and Zone:CTA sections marked, ready to deploy ``` **After any output** the agent will offer: - `"give me raw HTML only"` → strip markdown wrapping, return pure code block - `"run /checks"` → re-run SEO audit on the generated output --- ## `/write` vs `/writehtml` — When to Use Which | Situation | Use | |-----------|-----| | Reviewing content before publishing | `/write` | | Pasting into a visual CMS editor | `/write` | | Deploying directly to a page | `/writehtml` | | Checking HTML structure and schema | `/writehtml` | | Social media captions | `/write` | | Testing a new template | `/writehtml` | --- ## Page Types Supported | Type | Description | Recommended Word Count | |------|-------------|----------------------| | `Blogpost` | Organic SEO articles, guides, storytelling content | 1,500w+ | | `Landingpage` | Sales campaigns, newsletter launches, promotions | 900–1,200w | | `Productnew` | New physical/digital products — tech specs focus | 400–600w | | `Productused` | Refurbished/second-hand items — condition reports | 500–700w | | `FAQ` | Standalone FAQ pages, PAA-targeting content with FAQPage schema | 800–1,200w | | `Socialphoto` | Visual posts with alt text and captions | 100–200w | | `Socialvideo` | YouTube/TikTok metadata, descriptions, transcripts | 150–300w | --- ## Search Intent Detection 🎯 CRITICAL — Runs Before Everything Else **When it runs**: Step 0 — BEFORE parsing the command, BEFORE loading any persona. **Purpose**: Analyze the user prompt → determine search intent → auto-select the correct page format. Wrong format = wrong ranking signal. A product description written for an informational query will not rank. **Full rules**: See `SEO_CHECKS/search_intent.md` ### Quick Reference | Detected Intent | Trigger Words | Auto-Selected Format | |----------------|---------------|----------------------| | **Informational** | how to, why, what is, guide, explained | `Blogpost` | | **Commercial Investigation** | best, vs, compare, review, top | `Blogpost` (comparison) | | **Transactional** | buy, price, in stock, order, purchase | `Productnew` or `Productused` | | **Navigational** | official site, login, [brand] + homepage | `Landingpage` | - If the user specifies a page type explicitly → skip auto-selection, use their type - If intent is ambiguous → ask **one** clarifying question before proceeding --- ## Workflow Steps (Internal Brain) 🧠 > Full processing logic with all step details: see `BRAIN_ARCHITECTURE.md` > All commands, types, and flags in full detail: see `COMMANDS.md` > Page template index and structure overview: see `PAGE_STRUCTURES.md` > Full SEO research and writing workflow: see `SEO_PATH.md` ``` Step 0 Search Intent Detection Analyze prompt → auto-select page format (SEO_CHECKS/search_intent.md) SKIP for: /seoplan, /seobrief — strategy commands, no page format needed Step 1 Parse Command Extract persona, type, prompt, all flags --from-brief If flag present → load SEO_BRIEFS/<id>.md at parse time --plan If flag present → load SEO_PLANS/<plan-id>.md node at parse time Step 2a Load Persona Index PERSONAS/_index.md → find persona_id Step 2b Load Persona File PERSONAS/<id>.md → style, tone, E-E-A-T rules /seoplan + /seobrief Always load researcher.md internally (overrides session persona) Default fallback If no /persona command → load PERSONAS/blogger.md Tone override If --tone flag present → override persona tone, keep everything else Step 2c Load Locale LOCALE/base.md + LOCALE/<lang>.md (if --lang flag present) Step 2d Load Brand Profile If /brand active or --brand flag: BRANDS/<id>.md → brand_vars{} + compliance{} Skip if No /brand command and no --brand flag → no brand rules apply Step 2e SEO Plan Pipeline If /seoplan active: load SEO_PLANS/plan_workflow.md → run Steps A–G → STOP (Steps 3–7 do not run) Step 3 Generate Variables Prompt + persona + brand + brief + plan node → full variable dictionary Step 3.5 Zone Assignment Pass Apply Zone A (neutral/factual) vs Zone B (CTA/sales) to each content section Step 4 Select Template Match page type → load TEMPLATES/<type>.md /write skips Steps 4–5 Plain text output — no template loading Step 5 Variable Substitution Replace ALL {PLACEHOLDER} in template with real values Step 6 SEO Checks Run all applicable files in SEO_CHECKS/ /seoplan Runs plan quality check (Step F in SEO_PLANS/plan_workflow.md) instead Step 6.5 Persona Compliance Check Headings formula · depth · E-E-A-T signals · Zone A/B · zero placeholder leakage /seoplan Skipped (no page content generated) Step 6.6 Brand Compliance Check If brand active: banned phrases · urgency limits · required disclosures HARD FAIL Blocks output until all violations resolved /seoplan Brand persona defaults applied to node assignments only Step 7 Output /write → plain text | /writehtml → pure HTML /seoplan Structured plan saved to SEO_PLANS/ /seobrief Structured brief saved to SEO_BRIEFS/ ``` ### Workflow Example — `/write` (Plain Text) ```bash /persona creative-writer /write Blogpost "Shooting film in Nürnberg with a Leica M6" --primary-kw "leica m6 film photography" # Step 0: Informational intent detected → Blogpost confirmed # Step 2: Loads PERSONAS/creative-writer.md # Step 3: Generates variables using Story-Driven style + Heading Formula # Step 3.5: Assigns Zone A to intro + body sections # Step 4–5: Skipped (plain text output) # Step 6–6.5: SEO checks + compliance pass # Step 7: Returns readable blog post text — no HTML tags ``` ### Workflow Example — `/writehtml` (HTML Output) ```bash /persona ecommerce-manager /writehtml Productused "Leica M6 TTL Chrome, serial 2741xxx, EX+ condition" --primary-kw "leica m6 ttl kaufen" # Step 0: Transactional intent → Productused confirmed # Step 2: Loads PERSONAS/ecommerce-manager.md # Step 3: Generates full variable dict (all {SPEC_*}, {SCHEMA_*}, {FAQ_*} etc.) # Step 3.5: Zone A for spec/condition sections, Zone B for CTA/pricing blocks # Step 4: Loads TEMPLATES/product_used_template.md # Step 5: Replaces ALL {PLACEHOLDER} — zero placeholders in output # Step 6–6.5: SEO checks + compliance pass # Step 7: Returns complete HTML — ready to deploy ``` ### Workflow Example — `/seobrief` → `/write` (Brief-First Flow) ```bash # Step 1: Generate the brief /seobrief Blogpost "Leica M6 Analogfotografie Guide" --lang de --brand jbv-foto # → Researcher persona loads internally (always) # → Keyword cluster researched: primary KW auto-detected # → 2-3 competitor URLs analysed for gaps # → Brief saved: SEO_BRIEFS/<YEAR>/<MONTH>/leica-m6-analogfotografie-guide-de.md # → Output: full structured brief with KW cluster, H1–H4 outline, PAA questions, internal link targets, and ready-to-run /write command # Step 2: Write content from the brief /brand jbv-foto /persona blogger /write Blogpost "Leica M6 Guide" --from-brief leica-m6-analogfotografie-guide-de --lang de # → Step 1: Loads brief → KWs, outline, PAA, internal links merged into parse # → Step 2a-c: blogger persona + de locale # → Step 2d: jbv-foto brand profile (CTAs, compliance) merged # → Step 3: Variables generated using brief outline as H-tag structure # → Steps 6, 6.5, 6.6: SEO + persona + brand compliance all pass # → Step 7: Returns plain text article following the brief's approved structure ``` ### Workflow Example — /seoplan → /seobrief → /write (Full Agency Flow) ```bash /seoplan "Vintage analog cameras Germany" --lang de --brand jbv-foto ``` → Step 2e: SEO_PLANS/plan_workflow.md loaded, researcher runs Steps A–G → Step A: Keyword families mapped, quick win threshold = difficulty < 22 → Steps B–C: 11 nodes built and tiered (1 PILLAR + 4 QW + 3 FND + 3 STR) → Step D: Internal link matrix generated — no orphan nodes → Step E: Execution order: qw-01 → qw-04 first, pillar-01 after, str-01–03 last → Step G: Saved as SEO_PLANS/<YEAR>/<MONTH>/vintage-analog-cameras-de.md ```bash /seobrief Blogpost "Film einlegen Anleitung" --plan vintage-analog-cameras-de.qw-01 --lang de ``` → Step 1: Node qw-01 loaded from plan → primary_kw, page_type, links_to extracted → Research runs on top of plan data, brief saved: SEO_BRIEFS/<YEAR>/<MONTH>/film-einlegen-anleitung-de.md ```bash /brand jbv-foto /persona blogger /write Blogpost "Film einlegen" --from-brief film-einlegen-anleitung-de --lang de ``` → Brief + plan node + brand all merged at Step 1 → Steps 6 / 6.5 / 6.6 pass → Step 7: plain text article ready to publish --- ## Variable Substitution Engine 🧠 When you provide a content prompt, the brain: 1. **Extracts variables** from your prompt automatically 2. **Replaces all `{PLACEHOLDER}` text** in the template with real content 3. **Returns zero placeholders** — all `{VAR}` text is gone before output **Full variable reference per page type**: see `BRAIN_ARCHITECTURE.md` ### Example — Variable Dictionary (Productused, Leica M6) ```python { "TITLE": "Leica M6 TTL Chrome — Used, EX+ Condition | WebsiteName", "META_DESCRIPTION": "Buy a used Leica M6 TTL Chrome in EX+ condition. Serial 2741xxx, 2000–2001 production. Fully functional, CLA'd. 30-day return policy.", "URL_CANONICAL": "https://www.example.de/products/leica-m6-ttl-chrome-gebraucht", "H1_TITLE": "Leica M6 TTL Chrome (Type 10434) — EX+ Condition, Serial 2741xxx", [REDACTED_SECRET]: "2000–2001 production · TTL flash metering · All functions verified", "CONDITION_LEVEL_USED": "EX+", "DISPLAY_PRICE_EUR_USED": "€1,090", "SCHEMA_CONDITION": "https://schema.org/UsedCondition", "SCHEMA_SKU": "EXMAMPLE-2741", "FAQ_Q1": "What condition is this Leica M6 TTL in?", "FAQ_A1": "EX+ — light use only. No brassing, viewfinder clear, shutter fires accurately at all speeds.", # ... all remaining variables } ``` --- ## File Locations & Dependencies ``` seowlowsclaw/ │ ├── SKILL.md ← This file — core instructions + command reference ├── BRAIN_ARCHITECTURE.md ← Complete processing logic (all 9 brain steps) ├── COMMANDS.md ← Full command reference with all flags ├── PAGE_STRUCTURES.md ← Master index + links to all page templates ├── SEO_PATH.md ← Full SEO workflow: research → analysis → writing → checks │ ├── PERSONAS/ ← One file per persona │ ├── _index.md ← Load first — lists all persona IDs and file paths │ ├── ecommerce-manager.md │ ├── creative-writer.md │ ├── blogger.md ← Default persona when none specified │ ├── researcher.md │ ├── vintage-expert.md │ └── travel-photographer.md │ ├── BRANDS/ ← One file per client brand profile │ ├── _index.md ← Load first — lists all brand IDs and file paths │ └── brand-template.md ← Copy this to create a new brand profile │ ├── LOCALE/ ← Language override files (Base + Delta architecture) │ ├── base.md ← English defaults for all locale keys — always loaded │ ├── de.md ← German overrides (--lang de) │ ├── fr.md ← French overrides (--lang fr) │ ├── es.md ← Spanish overrides (--lang es) │ └── pt.md ← Portuguese overrides (--lang pt) │ ├── SEO_BRIEFS/ ← Generated content briefs (one per topic/page) │ └── _index.md ← Registry: brief-id | topic | type | date | status │ ├── SEO_PLANS/ ← One plan file per niche/site campaign │ ├── _index.md ← Registry: plan-id | niche | mode | lang | date │ ├── plan-template.md ← Format reference + example plan │ └── plan_workflow.md ← Full /seoplan pipeline logic (Steps A–G) — loaded only on /seoplan │ ├── SEO_CHECKS/ ← SEO rules, intent detection, schema, quality checks │ ├── search_intent.md ← Step 0 rules — intent detection + format selection │ ├── do-and-don-lists.md ← Page-type specific dos and don'ts │ ├── schema-markup.md ← Schema.org rules + {SCHEMA_*} variable definitions │ ├── seo-checks-reference.md ← Full SEO check reference │ └── seo-output-quality-checklist.md ← Pre-output quality gates │ ├── TEMPLATES/ ← HTML output templates (used by /writehtml only) │ ├── blog_post_template.md │ ├── landing_page_template.md │ ├── product_new_template.md │ ├── product_used_template.md │ └── faq_page_template.md │ ├── TEMPLATES_SOCIAL/ ← Social media output templates │ ├── photo_post_template.md │ └── video_post_template.md │ ├── OUTPUT_EXAMPLES/ ← Reference output examples for agent guidance │ ├── blog_post_example.md │ ├── landing_page_example.md │ ├── product_new_example.md │ └── product_used_example.md │ #└── DOC/ ← Internal project docs (not loaded by agent) # ├── BUGS.md ← Internal project docs (not loaded by agent) # ├── CHANGELOG.md ← Internal project docs (not loaded by agent) # └── PLANNING.md ← Internal project docs (not loaded by agent) ``` --- *Last updated: 05-04-2026 (v0.6)* *Adds: /brand, /brands, /seobrief, --from-brief flag, BRANDS/ and SEO_BRIEFS/ folders* *Maintainer: Chris — SEOwlsClaw core skill file*

path: BRAIN_ARCHITECTURE.md
content: # SEOwlsClaw — Brain Architecture (v0.6) Universal Brain System 🧠

## Purpose

This document defines the **complete processing logic** of the SEOwlsClaw agent brain.
It describes every step from receiving a user command to producing final HTML output.
All steps are executed in the order listed here — no exceptions.

---

## The Unified Brain Workflow 🔄

### Input: ANY User Prompt + Persona

```
Prompt:     "Brand new eco-friendly water bottle"
Persona:    E-Commerce Manager
Page Type:  Productnew
Primary KW: "sustainable water bottle"
```

---

### Step 0 — Search Intent Detection 🎯 FIRST, ALWAYS

**Run before anything else — even before parsing the command.**  
**Full rules:** See `SEO_CHECKS/search_intent.md`

Analyze the user prompt → detect intent → auto-select correct page format.

| Detected Intent | Trigger Words | Auto-Selected Format |
|----------------|---------------|----------------------|
| **Informational** | how to, why, what is, guide, explained | `Blogpost` |
| **Commercial Investigation** | best, vs, compare, review, top | `Blogpost` (comparison) |
| **Transactional** | buy, price, in stock, order, purchase | `Productnew` or `Productused` |
| **Navigational** | official site, login, [brand] + homepage | `Landingpage` |

**If the user specifies a page type explicitly in the command → skip auto-selection, use their type.**  
**If intent is ambiguous → ALWAYS ask one clarifying question before proceeding.**

---

### Step 1 — Parse Command

Extract all parameters from the user input:

```python
persona_id   = extract_persona()      # e.g. "ecommerce-manager"
page_type    = extract_page_type()    # e.g. "Productnew"
content_prompt = extract_prompt()     # e.g. "Brand new eco-friendly water bottle"
primary_kw   = extract_flag("--primary-kw")   # e.g. "sustainable water bottle"
secondary_kw = extract_flag("--secondary-kw") # optional
tone_override = extract_flag("--tone")        # optional override
target        = extract_flag("--target")      # e.g. "ai-overview", "snippet:list", "paa"
depth         = extract_flag("--depth")       # "light" | "standard" | "deep" (default: standard)
persona_id   = extract_persona()      # e.g. "ecommerce-manager"
page_type    = extract_page_type()    # e.g. "Productnew"
content_prompt = extract_prompt()     # e.g. "Brand new eco-friendly water bottle"
primary_kw   = extract_flag("--primary-kw")   # e.g. "sustainable water bottle"
secondary_kw = extract_flag("--secondary-kw") # optional
tone_override = extract_flag("--tone")        # optional override
target        = extract_flag("--target")      # e.g. "ai-overview", "snippet:list", "paa"
depth         = extract_flag("--depth")       # "light" | "standard" | "deep" (default: standard)
brand_id      = extract_flag("--brand")       # NEW: e.g. "example-name" — loads BRANDS/<id>.md
brief_id      = extract_flag("--from-brief")  # NEW: e.g. "leica-m6-guide-de" — loads SEO_BRIEFS/<id>.md
plan_id    = extract_flag("--plan")   # NEW: "vintage-analog-cameras-de.qw-01" or just "vintage-analog-cameras-de"
plan_mode  = extract_flag("--mode")   # NEW: "cluster" (default) | "site"
plan_priority = extract_flag("--priority")  # NEW: "balanced" (default) | "quickwins" | "strategic"
```

**`/seoplan` command — special parse rules:**

`/seoplan` is a strategic command. It does NOT run Steps 4–5 (no template, no HTML).
Instead it runs a research + analysis pipeline and outputs a structured plan.

Parse extracts:
```python
niche_prompt   = extract_prompt()          # e.g. "Vintage analog cameras Germany"
plan_mode      = extract_flag("--mode")    # "cluster" | "site" — default: "cluster"
plan_lang      = extract_flag("--lang")    # directs keyword research to correct SERP market
plan_brand     = extract_flag("--brand")   # load brand for persona defaults + compliance
plan_priority  = extract_flag("--priority") # "balanced" | "quickwins" | "strategic"
plan_depth     = extract_flag("--depth")   # "light" (outline only) | "standard" | "deep"
plan_pages     = extract_flag("--pages")   # optional: target number of nodes, default auto
```

---

**`--from-brief` processing at Step 1:**

IF `--from-brief <brief-id>` is present:
  1. Load `SEO_BRIEFS/<brief-id>.md`
  2. Extract: `primary_kw`, `secondary_kw`, `paa_questions`, `approved_outline`,
     `internal_links`, `word_count_target`, `competitor_gaps`
  3. Use extracted values as defaults — explicit command flags still override them
     (e.g. if `--primary-kw` is also in the command, command wins over brief)
  4. Store `brief_data{}` for use in Step 3 (outline + variables) and Step 6.5 (depth check)

---

### Step 2 — Load Persona (2-Step Process)

**Step 2a:** Read `PERSONAS/_index.md` → find the row matching `persona_id`  
**Step 2b:** Load `PERSONAS/<id>.md` → extract all of the following:

| What to extract | Used in |
|-----------------|---------|
| Writing Style + Tone + Vocabulary | Step 3 (variable generation) |
| AI Overview Rules + Zone A/B markers | Step 3.5 (zone assignment) |
| E-E-A-T Injection signals | Step 6.5 (compliance check) |
| Heading Formula | Step 3 (all H1–H4 variables) |
| Content Depth Standards | Step 6.5 (compliance check) |

**Step 2c:** Load Locale files → merge into variable dictionary

  IF `--lang` flag is present:
    1. Load `LOCALE/base.md` → store all keys as `locale_vars{}`
    2. Load `LOCALE/<lang_code>.md` → override matching keys in `locale_vars{}`
    3. Use merged result for all locale variables
  
  IF no `--lang` flag:
    1. Load `LOCALE/base.md` only → use as `locale_vars{}`
  
  All `{LANG_CODE}`, `{LOCALE_STRING}`, `{SCHEMA_IN_LANGUAGE}`,
  `{SCHEMA_PRICE_CURRENCY}`, `{SCHEMA_ADDRESS_COUNTRY}`, `{CTA_BUY_NOW}`,
  `{LABEL_CONDITION}`, `{CONDITION_*}` and all other locale keys are now
  available for variable substitution in Step 7.

**Step 2d:** Load Brand Profile (NEW)
**Runs only if `/brand <id>` was issued in the session OR `--brand <id>` flag is present.**

```
Step 2d-1: Read BRANDS/_index.md → find the row matching brand_id
Step 2d-2: Load BRANDS/<id>.md → extract all fields into brand_vars{}
Step 2d-3: Merge brand_vars{} into the variable dictionary:
            - BRAND_* variables added directly
            - Brand CTAs override matching LOCALE/ CTA keys
              (e.g. brand.ctas.de.primary overrides locale_vars.CTA_BUY_NOW)
            - Tone sliders stored as brand_tone{} for Step 3
Step 2d-4: Store brand.compliance{} object for Step 6.6

If no /brand command and no --brand flag → skip Step 2d. No brand rules apply.
```

**Tone Merge Logic (brand sliders + persona):**

| Situation | Result |
|-----------|--------|
| No brand active | Persona tone rules apply as-is |
| Brand active, no --tone flag | Brand slider values override persona tone defaults |
| Brand active + --tone flag | --tone flag wins over BOTH brand sliders and persona defaults |

**Variable Dictionary Additions from Brand Profile:**

```python
brand_vars = {
  "BRAND_ID":              "exampleID",
  "BRAND_NAME":            "exampleName",
  "BRAND_TAGLINE":         "exampleTagline",
  "BRAND_DISCLAIMER":      "exampleDisclaimer",
  "BRAND_TRUST_BLOCK":     "exampleTrustBlock",
  "BRAND_RETURN_POLICY":   "exampleReturnPolicy",
  "BRAND_SUPPORT_URL":     "https://example.com/support/",
  "BRAND_LOGO_URL":        "https://example.com/media/image/example-logo-297x99.webp",
  # CTAs injected from brand.ctas.<lang> — override LOCALE/ defaults:
  "CTA_BUY_NOW":           "Example",       # overrides LOCALE/<id>.md value
  "CTA_SOFT":              "Example",
  "CTA_CONTACT":           "Example",
}
```

**Default fallback:** If no `/persona` command was given → load `PERSONAS/blogger.md`  
**Tone override:** If `--tone` flag is present → override persona's default tone, keep everything else

**Step 2e:** SEO Plan Pipeline (NEW)
**Runs only if `/seoplan` command is active.**

`/seoplan` runs a dedicated pipeline instead of the standard Steps 3–7.
Steps 3–7 are for page content generation only — they do not run for `/seoplan`.

```
seoplan-Step A    Niche + Market Research
seoplan-Step B    Cluster Architecture Design
seoplan-Step C    Node Tiering + Priority Assignment
seoplan-Step D    Internal Link Matrix
seoplan-Step E    Execution Order
seoplan-Step F    Plan Quality Check
seoplan-Step G    Output + Save
```

**Full rules for seoplan-Steps A–G:** See `SEO_PLANS/plan_workflow.md`
Load this file immediately when `/seoplan` is triggered. Do not load `SEO_PLANS/plan_workflow.md` for any other command.


---

### Step 3 — Generate Variables

Using the content prompt + loaded persona, build the full variable dictionary.

**Apply persona rules during generation:**
- Use the persona's **Heading Formula** for all `H1_*`, `H2_*`, `H3_*`, `H4_*` variables
- Use the persona's **Vocabulary** for body copy variables
- Use the persona's **Depth Standards** to determine how many sections/variables to generate

**Example variable dictionary (Productnew):**

```python
variables = {
  # Meta
  "TITLE":             "Brand New Eco-Friendly Water Bottle — Sustainable Hiking Gear",
  "META_DESCRIPTION":  "Discover the best sustainable water bottle for hiking in 2026...",
  "URL_CANONICAL":     "https://example.com/products/eco-water-bottle",

  # Headings (generated using persona Heading Formula)
  "H1_TITLE":                        "Brand New Eco-Friendly Water Bottle — Sustainable Hiking Gear",
  "HERO_SUBHEADLINE_URGENCY":        "Premium stainless steel — lifetime warranty included",
  "H2_VALUE_PROP_TITLE":             "Why This Water Bottle Is Worth Every Cent for Eco-Hikers",
  "H3_FEATURES_TITLE":               "Complete Technical Specifications",
  [REDACTED_SECRET]: "EcoSmart Bottle vs Standard Steel Bottles: Key Differences",
  [REDACTED_SECRET]: "Order Today — Limited Stock Available",

  # Content
  "VALUE_CONTENT_300_CHARS_MAX":     "...",
  "SCARCITY_COUNT":                  "Only 12 units left",
  "SPEC_1_LABEL":                    "Material",
  "SPEC_1_VALUE_UNIT":               "18/8 Stainless Steel + BPA-Free Coating",
  # ... all remaining variables
}
```

---

**If brand profile is active (Step 2d ran):**
- Apply `brand.preferred_terms{}` as soft vocabulary constraints during generation
  → Brain prefers brand terms when generating body copy
  → No hard fail if a non-preferred synonym slips through (that's Step 6.6's job)
- Use `brand.trust_priorities{}` to determine which trust signals to emphasise in
  spec, condition, and value-prop sections
- If `brief_data{}` is loaded (--from-brief): use `brief_data.approved_outline`
  as the H1–H4 structure template → generate content to fill that outline
  instead of generating headings from scratch

---


### Step 3.5 — Zone Assignment Pass (AI Overview Enforcement) 🔴

**This step applies the AI Overview Rules loaded from the persona file.**

For every content section variable, assign it to a zone and enforce the rules:

#### Zone A — AI Overview Zone
Applies to: `H2_*` intro paragraphs, spec tables, feature descriptions, comparison sections, FAQ blocks.

**Enforce in Zone A:**
- First sentence of every H2 section → factual, neutral, zero sales words
- No scarcity triggers, no urgency phrases, no CTAs inside this zone
- Structure: **Answer first (1 sentence) → Explain (2–3 sentences)**
- Validate: does sentence 1 answer a real search query on its own? If not → rewrite

**Zone A marker in output HTML:**
```html
<!-- ZONE:AI -->
<section>...factual content...</section>
<!-- /ZONE:AI -->
```

#### Zone B — Conversion Zone
Applies to: CTA blocks, price presentation, urgency messaging, hero subheadlines, testimonials.

**Rules in Zone B:**
- Full persona vocabulary applies — scarcity triggers, urgency language, benefit-first CTAs all allowed
- Zone B sections must always appear **after** at least one Zone A section on the page

**Zone B marker in output HTML:**
```html
<!-- ZONE:CTA -->
<section>...conversion content...</section>
<!-- /ZONE:CTA -->
```

**Note:** If the active persona is `blogger`, `researcher`, or `vintage-expert`, the entire page is effectively Zone A. Zone B only activates for `ecommerce-manager` and `creative-writer` personas.

---

### Step 4 — Select Template

Match `page_type` → load the corresponding template file:

| Page Type | Template File |
|-----------|---------------|
| `Blogpost` | `TEMPLATES/blog_post_template.md` |
| `FAQ Page` | `TEMPLATES/faq_page_template.md` |
| `Landingpage` | `TEMPLATES/landing_page_template.md` |
| `Productnew` | `TEMPLATES/product_new_template.md` |
| `Productused` | `TEMPLATES/product_used_template.md` |
| `Socialphoto` | `TEMPLATES_SOCIAL/photo_post_template.md` |
| `Socialvideo` | `TEMPLATES_SOCIAL/video_post_template.md` |

**Intent-override rule:** If Step 0 detected a different page type than what the user specified, and no explicit type was given in the command → use the intent-detected type.

---

### Step 5 — Variable Substitution

Replace every `{PLACEHOLDER}` in the loaded template with its generated value.

```python
def inject_variables(template_text: str, variables: dict) -> str:
    """Replace ALL {PLACEHOLDER} text with actual values."""
    return template_text.format(**variables)
```

**Rules:**
- Every `{PLACEHOLDER}` in the template must be replaced — no placeholder may survive into output
- If a variable is missing from the dictionary → flag it, ask the user for the value, do not output `{PLACEHOLDER}` text
- Schema variables (`{SCHEMA_*}`) are substituted in the same pass — see schema variable tables below

---

### Step 6 — SEO Checks

Run the appropriate checks from `SEO_CHECKS/`:

| Check File | When to Run |
|------------|-------------|
| `SEO_CHECKS/do-and-don-lists.md` | Every page type, every time |
| `SEO_CHECKS/page-type-specific-checks.md` | Match section to current page type |
| `SEO_CHECKS/seo-output-quality-checklist.md` | Every page type, every time |
| `SEO_CHECKS/schema-markup.md` | Every page type — validate schema is correct |
| `SEO_CHECKS/search_intent.md` | Confirm output format matches detected intent |
| `SEO_CHECKS/seo-checks-reference.md` | Every page type, every time, workflow for SEO validation |

---

### Step 6.5 — Persona Compliance Check 🔴

**Run before generating output. Fix failures before outputting.**

Using the Depth Standards and E-E-A-T rules loaded from the persona file in Step 2:

```
[ ] Heading Formula applied?
      → Every H1–H4 and by page type also H5 and H6 matches the persona's heading pattern
      → No vague labels ("Features", "Overview") used as standalone headings

[ ] Content Depth met?
      → Word count ≥ persona minimum for this page type
      → Required sections all present (e.g. comparison table, FAQ block)

[ ] E-E-A-T signals present?
      → Count mandatory signals per persona rules
      → Flag any missing signals and inject before output

[ ] Zone A/B correct?
      → No sales language inside <!-- ZONE:AI --> sections
      → At least one ZONE:AI section appears before any ZONE:CTA section

[ ] No placeholder leakage?
      → Scan output for any remaining {PLACEHOLDER} text
      → If found → generate missing value or ask user
```

If any check fails → revise the relevant section. Do not output until all checks pass.

---

### Step 6.6 — Brand & Legal Compliance Check

**Runs only if a brand profile is active (Step 2d ran).**
**Runs AFTER Step 6.5 — fix Step 6.5 failures first.**

Using `brand.compliance{}` loaded in Step 2d:

```
[ ] Banned phrases check (HARD FAIL)
      → Scan full output text for every pattern in brand.compliance.banned_phrases[]
      → Match is case-insensitive
      → If any match found:
          - BLOCK output
          - Show: location, matched phrase, suggested replacement
          - Do not output until all banned phrases are resolved

[ ] Banned claims check (HARD FAIL)
      → Scan for patterns in brand.compliance.banned_claims[]
      → Same rules as banned phrases

[ ] Urgency level check (HARD FAIL if exceeded)
      → Detect urgency language in Zone B sections
      → Compare against brand.compliance.urgency_limit:
          NONE       → any urgency language = FAIL
          SOFT       → "only X available", "while stocks last" = OK | countdowns = FAIL
          STANDARD   → explicit stock numbers, date-based end = OK | fake timers = FAIL
          AGGRESSIVE → all urgency patterns = OK
      → If exceeded: FAIL + suggest a softer alternative

[ ] Artificial scarcity check (HARD FAIL if disallowed)
      → If brand.compliance.artificial_scarcity_allowed = false:
          → Flag countdown timer references, fabricated stock numbers
          → FAIL if found

[ ] Required disclosures check (WARNING — HARD FAIL only if risk_level = HIGH)
      → Verify each entry in brand.compliance.required_disclosures[] is present
      → If missing + risk_level = HIGH → HARD FAIL
      → If missing + risk_level = LOW or MEDIUM → WARNING only (show reminder, continue)

[ ] Brand term spelling check (WARNING — does not block output)
      → Verify brand.brand_terms[] are spelled/capitalised correctly
      → Flag issues + suggest corrections
```

**Violation output format:**

```
⛔ Step 6.6 — Brand Compliance FAILED
Brand: [brand-id] | Risk Level: [LOW / MEDIUM / HIGH]

HARD FAILS (fix before output):
  ❌ Banned phrase: "[phrase]" at [location]
     → Suggestion: [replacement]
  ❌ Urgency limit exceeded: "[phrase]" at [location]
     → Brand limit: [SOFT/STANDARD] | Suggestion: [alternative]

WARNINGS (review recommended):
  ⚠️  Required disclosure missing: "[disclosure text]"
      → Suggestion: add to [footer / price block / disclaimer section]
  ⚠️  Brand term: "[wrong spelling]" → should be "[correct spelling]"

Fixing [n] hard fail(s) before output.
```

---

### Step 7 — Output

Return the complete output as clean text or HTML in chat, depending if the user prompt was /write or /writehtml ready for deployment.

**Output format:**
```html
<!DOCTYPE html>
<html lang="{LANG_CODE}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{TITLE}</title>
  <meta name="description" content="{META_DESCRIPTION}">
  <link rel="canonical" href="{URL_CANONICAL}">
  <!-- JSON-LD Schema (from SEO_CHECKS/schema-markup.md) -->
  <script type="application/ld+json">{ ... }</script>
</head>
<body>
  <!-- ZONE:AI -->
  <!-- ZONE:CTA -->
  <!-- content -->
</body>
</html>
```

**After output:** Offer the user:
- `"give me raw HTML only"` → strip markdown, return pure HTML code block
- `"run /checks"` → re-run SEO audit on the generated output

---

## Schema Variables Reference

All `{SCHEMA_*}` variables are substituted in Step 5 alongside content variables.  
Full schema rules and required fields: see `SEO_CHECKS/schema-markup.md`

### Global — All Page Types

| Variable | Type | Example Value |
|----------|------|---------------|
| `{SCHEMA_IMAGE_URL}` | String (URL) | `https://www.example.de/img/products/leica-m6.jpg` |
| `{SCHEMA_SKU}` | String | `EXAMPLE-10042` |
| `{SCHEMA_AVAILABILITY}` | Schema URL | `https://schema.org/InStock` |
| `{SCHEMA_BREADCRUMB_L2_URL}` | String (URL) | `https://www.example.de/leica-cameras` |
| `{SCHEMA_BREADCRUMB_L2_NAME}` | String | `Leica cameras` |

### Productused Only

| Variable | Type | Example Value |
|----------|------|---------------|
| `{SCHEMA_CONDITION}` | Schema URL | `https://schema.org/UsedCondition` |

### Blogpost Only

| Variable | Type | Example Value |
|----------|------|---------------|
| `{SCHEMA_DATE_PUBLISHED}` | ISO 8601 | `2026-04-15` |
| `{SCHEMA_DATE_MODIFIED}` | ISO 8601 | `2026-04-15` |

### Landingpage Only

| Variable | Type | Example Value |
|----------|------|---------------|
| `{SCHEMA_OFFER_VALID_FROM}` | ISO 8601 | `2026-04-01T00:00:00+02:00` |
| `{SCHEMA_OFFER_VALID_THROUGH}` | ISO 8601 | `2026-04-30T23:59:59+02:00` |

### FAQ — Any Page Type with FAQ Section

| Variable | Type | Example Value |
|----------|------|---------------|
| `{FAQ_Q1}` through `{FAQ_Q5}` | String | `What condition is the camera in?` |
| `{FAQ_A1}` through `{FAQ_A5}` | String | `The camera is in very good condition and fully functional.` |

---

## Template Variable Reference

Complete variable lists per page type. All variables below are replaced in Step 5.

### Blogpost

```
{TITLE, META_DESCRIPTION, URL_CANONICAL, H1_TITLE, HERO_SUBHEADLINE,
 INTRO_H2_TITLE, INTRO_CONTENT_300_CHARS_MAX,
 H3_SECTION_1_TITLE, STEP_1_DETAIL, TIP_1_ACTIONABLE,
 H4_COMPARISON_TITLE, COMPARISON_CATEGORY, COMP_A, COMP_B,
 CONCLUSION_CONTENT_300_CHARS_MAX, READ_MORE_LINK,
 SCHEMA_DATE_PUBLISHED, SCHEMA_DATE_MODIFIED,
 SCHEMA_IMAGE_URL, SCHEMA_BREADCRUMB_L2_URL, SCHEMA_BREADCRUMB_L2_NAME,
 FAQ_Q1–FAQ_Q5, FAQ_A1–FAQ_A5}
```

### Landingpage

```
{TITLE, META_DESCRIPTION, URL_CANONICAL, H1_TITLE, PRIMARY_KEYWORD,
 HERO_SUBHEADLINE_URGENCY, SCARCITY_COUNT,
 H2_VALUE_PROP_TITLE, VALUE_CONTENT_300_CHARS_MAX,
 H3_FEATURES_TITLE, LIST_ITEM_1_BENEFITS, LIST_ITEM_2_LIMITED_OFFER, LIST_ITEM_3_EXCLUSIVE_DEAL,
 H4_TESTIMONIAL_TITLE, TESTIMONIAL_QUOTE, TESTIMONIAL_NAME,
 H5_FINAL_CTA_TITLE, FINAL_CTA_BULLET_POINTS, CTA_LINK,
 BUTTON_TEXT_LIMITED_STOCK, RELATED_PAGE_TITLE, FAQ_SECTION_TITLE, POLICY_LINK,
 SCHEMA_TYPE, SCHEMA_OFFER_VALID_FROM, SCHEMA_OFFER_VALID_THROUGH,
 SCHEMA_IMAGE_URL, SCHEMA_SKU, SCHEMA_AVAILABILITY,
 SCHEMA_BREADCRUMB_L2_URL, SCHEMA_BREADCRUMB_L2_NAME,
 FAQ_Q1–FAQ_Q5, FAQ_A1–FAQ_A5}
```

### Productnew

```
{TITLE, META_DESCRIPTION, URL_CANONICAL, BRAND_NAME,
 PRICE_CURRENCY_PRICE, RATING_VALUE, RATING_COUNT,
 H1_TITLE, HERO_SUBHEADLINE, DISPLAY_PRICE_EUR,
 H2_DESCRIPTION_OVERVIEW_FEATURES, DESCRIPTION_CONTENT_400_CHARS_MAX, USE_CASE_BULLET_POINTS,
 H3_TECHNICAL_SPECS_TITLE_DETAILED,
 SPEC_1_LABEL, SPEC_1_VALUE_UNIT, SPEC_2_LABEL, SPEC_2_VALUE_UNIT,
 SPEC_3_LABEL, SPEC_3_VALUE_UNIT, SPEC_4_LABEL, SPEC_4_VALUE_UNIT,
 H4_COMPARISON_NEW_VERSION_OR_BENEFITS, COMPARISON_CATEGORY, COMP_A, COMP_B,
 H5_PURCHASE_BUTTON_TEXT_LIMITED_STOCK,
 BULLET_1_WARRANTY_FREE_OR_GUARANTEE, BULLET_2_SHIPPING_QUICK_DELIVERY,
 BULLET_3_TECHNICAL_SUPPORT_AVAILABLE, PURCHASE_LINK,
 RELATED_PRODUCT_TITLE, COMPARE_WITH_COMPETITOR_PAGE, TECH_SUPPORT_LINK,
 SCHEMA_IMAGE_URL, SCHEMA_SKU, SCHEMA_AVAILABILITY,
 SCHEMA_BREADCRUMB_L2_URL, SCHEMA_BREADCRUMB_L2_NAME,
 FAQ_Q1–FAQ_Q5, FAQ_A1–FAQ_A5}
```

### Productused

```
{TITLE, META_DESCRIPTION, URL_CANONICAL, BRAND_NAME,
 PRICE_CURRENCY_PRICE_USED, CONDITION_LEVEL_USED,
 H1_TITLE, HERO_SUBHEADLINE_CONDITION_DISCLOSURE,
 DISPLAY_PRICE_EUR_USED, SAVE_PERCENTAGE,
 H2_OVERVIEW_CONDITION_DISCLOSURE, CONDITION_CONTENT_300_CHARS_MAX,
 INSPECTION_BULLET_1_FUNCTIONALITY_TESTED, INSPECTION_BULLET_2_WEAR_AND_TEAR_ASSESSMENT,
 INSPECTION_BULLET_3_ACCESSORIES_COMPLETENESS,
 H3_FEATURE_COMPARISON_NEW_VS_USED,
 DIFF_1_FUNCTIONALITY_PRESERVED, DIFF_1_VALUE_PROPOSITION,
 DIFF_2_COST_SAVINGS_PERCENTAGE, DIFF_2_BEST_FOR_PRICE_SENSITIVE_BUYERS,
 DIFF_3_ECO_IMPACT_REDUCTION, DIFF_3_SUSTAINABILITY_BENEFIT,
 H4_COSMETIC_CONDITION_REPORT_DETAIL,
 COSMETIC_ITEM_1_NO_SCRATCHES_OR_MARKS, COSMETIC_ITEM_2_LIGHTLY_USED_BUT_FUNCTIONAL,
 H5_PURCHASE_WITH_CONFIDENCE_WARRANTY,
 WARRANTY_1_FULL_FUNCTIONALITY_GUARANTEE, WARRANTY_2_30_DAYS_RETURN_POLICY,
 WARRANTY_3_TECHNICAL_SUPPORT_AVAILABLE, PURCHASE_LINK_USED,
 SCHEMA_CONDITION, SCHEMA_IMAGE_URL, SCHEMA_SKU, SCHEMA_AVAILABILITY,
 SCHEMA_BREADCRUMB_L2_URL, SCHEMA_BREADCRUMB_L2_NAME,
 FAQ_Q1–FAQ_Q5, FAQ_A1–FAQ_A5}
```

---

## Workflow Summary (Quick Reference)

```
Step 0    Search Intent Detection     → auto-select page format (search_intent.md)
           SKIP for: /seoplan, /seobrief (strategy commands — no page format needed)
Step 1    Parse Command               → extract persona, type, prompt, flags
           --from-brief               → load SEO_BRIEFS/<id>.md if flag present
           --plan                     → load SEO_PLANS/<plan-id>.md node if flag present
Step 2a   Load Persona Index          → PERSONAS/_index.md → find persona_id
Step 2b   Load Persona File           → PERSONAS/<id>.md → style, tone, E-E-A-T
           /seoplan + /seobrief       → always load researcher.md internally
Step 2c   Load Locale                 → LOCALE/base.md + LOCALE/<lang>.md
Step 2d   Load Brand Profile (NEW)    → if /brand active: BRANDS/<id>.md → brand_vars{} + compliance{}
Step 2e   SEO Plan Pipeline (NEW)     → if /seoplan active: load SEO_PLANS/plan_workflow.md → run Steps A–G → STOP
Step 3    Generate Variables          → prompt + persona + brand + brief → full variable dict
Step 3.5  Zone Assignment Pass        → apply Zone A/B rules to content sections
Step 4    Select Template             → match page type → load TEMPLATES/<type>.md
           /write skips Steps 4–5 (plain text output)
Step 5    Variable Substitution       → replace ALL {PLACEHOLDER} in template
Step 6    SEO Checks                  → run all applicable check files in SEO_CHECKS/
Step 6.5  Persona Compliance Check    → headings · depth · E-E-A-T · zones · no leakage
Step 6.6  Brand Compliance Check (NEW)→ if brand active: banned phrases · urgency · disclosures
           HARD FAIL blocks output until resolved.
Step 7    Output                      → /write: plain text | /writehtml: pure HTML
           /seobrief: structured brief saved to SEO_BRIEFS/
```

---

*Last updated: 05-04-2026 (v0.6)*
*Adds: Step 2d (lean brand load), Step 2e (lean seoplan pointer), Step 6.6 (compliance)*
*Maintainer: Chris — SEOwlsClaw brain logic, all page types*


path: COMMANDS.md
content: # SEOwlsClaw — Command Reference (v0.8)

## Overview

All commands follow the pattern: `/<command> [type] "prompt" [--flags]`

| Command | Purpose |
|---------|---------|
| `/persona <id>` | Set writing style and tone |
| `/personas` | List or inspect available personas |
| `/write <type> "prompt"` | Generate plain text content (editor-ready) |
| `/writehtml <type> "prompt"` | Generate pure HTML content (deploy-ready) |
| `/research <topic>` | Keyword cluster + SERP analysis |
| `/checks <url or type>` | SEO audit checklist |
| `/brand <id>` | Load a client brand profile (CTAs, tone, compliance rules) |
| `/brands` | List all brand profiles or inspect one |
| `/seobrief <type> "topic"` | Generates a structured SEO content brief with KW cluster, outline, PAA, and competitor gaps |
| `/seoplan "niche"` | Builds a full SEO cluster plan — tiers nodes into PILLAR / QUICKWIN / FOUNDATION / STRATEGIC with keyword data, persona assignments, internal link matrix, and numbered execution order |

## ⚠️ FILE WRITE — CONFIRMATION REQUIRED
Trigger: only runs when the user issues /research, /write, /writehtml, or /checks.
Never write files silently or autonomously.
Before saving any files, you must:
1. Show the user the full file content in chat
2. Show the proposed file path
3. Ask: "Save this file? (yes / no / rename)"
4. Only write to disk after explicit "yes"

---

## `/persona`

Sets the writing style, tone, and vocabulary for the next `/write` or `/writehtml` command.  
Persona stays active until changed or the session resets.

**Syntax:**
```bash
/persona <id> [--tone <adjective>]
```

**Available Persona IDs:**

| ID | Style | Best For |
|----|-------|----------|
| `ecommerce-manager` | Persuasive, urgent, conversion-focused | Product pages, landing pages, sales campaigns |
| `creative-writer` | Imaginative, narrative-driven, emotional | Blog posts, experience stories, brand content |
| `blogger` | Approachable, educational, story-driven | Guides, how-tos, opinion pieces *(default)* |
| `researcher` | Neutral, fact-based, question-first | Comparison guides, technical articles |
| `vintage-expert` | Authoritative, collector-focused, precise | Vintage camera listings, condition reports, historical deep-dives |
| `travel-photographer` | Scenario-driven, location-specific, gear-focused | Travel guides, destination photography content |

**Default:** If no `/persona` is set → `blogger` is loaded automatically.

**Flags:**

| Flag | Purpose | Example |
|------|---------|---------|
| `--tone <adjective>` | Override tone only, keep everything else | `--tone enthusiastic` |

**Examples:**
```bash
/persona vintage-expert
/persona ecommerce-manager --tone urgent
/persona creative-writer --tone poetic
/persona researcher --tone neutral
```

---

## `/personas`

Lists all available personas or shows full details for one.

**Syntax:**
```bash
/personas
/personas --show <id>
```

**Examples:**
```bash
/personas
/personas --show vintage-expert
/personas --show ecommerce-manager
```

---

## `/write`

Generates **plain text content** — no HTML tags.  
Use this when you want to review content first, paste into a CMS editor, or use the text in documents, emails, or social captions.

**Syntax:**
```bash
/write <type> "prompt" [--flags]
```

**Supported Page Types:**

| Type | Description | Target Word Count |
|------|-------------|-------------------|
| `Blogpost` | Organic SEO articles, guides, storytelling | 1,500w+ |
| `Landingpage` | Sales campaigns, newsletter launches | 900–1,200w |
| `Productnew` | New products — tech specs focus | 400–600w |
| `Productused` | Used/refurbished items — condition reports | 500–700w |
| `FAQ` | Standalone FAQ pages, PAA-targeting content | 800–1,200w |
| `Socialphoto` | Visual posts with alt text and captions | 100–200w |
| `Socialvideo` | YouTube/TikTok metadata, descriptions | 150–300w |

**Flags:**

| Flag | Required | Purpose | Example |
|------|----------|---------|---------|
| `"prompt"` | ✅ Yes | Content info, product details, topic | `"Leica M6 TTL Chrome, EX+"` |
| `--primary-kw` | Recommended | Main target keyword | `--primary-kw "leica m6 kaufen"` |
| `--secondary-kw` | Optional | Additional keyword cluster | `--secondary-kw "leica m6 ttl gebraucht"` |
| `--lang` | Optional | Output language (default: English) | `--lang de` |
| `--tone` | Optional | Tone override for this run only | `--tone enthusiastic` |
| `--depth` | Optional | Content depth level | `--depth deep` |

**`--depth` values:**

| Value | Effect |
|-------|--------|
| `light` | Shorter output, fewer sections, faster review |
| `standard` | Default — balanced depth per persona rules |
| `deep` | Maximum depth, all optional sections included |

**Examples:**
```bash
/persona blogger
/write Blogpost "Shooting film in Nürnberg with a Leica M6" --primary-kw "leica m6 analogfotografie" --lang de

/persona vintage-expert
/write Productused "Leica M6 Classic black, serial 1921xxx, Very Good condition" --primary-kw "leica m6 classic kaufen"

/persona ecommerce-manager --tone enthusiastic
/write Landingpage "Spring sale — 20% off all analog cameras, starts April 15th" --primary-kw "analoge kameras sale"

/persona researcher
/write FAQ "Leica M6 buyer questions — condition, price, compatibility" --primary-kw "leica m6 faq" --lang de
```

---

## `/writehtml`

Generates **pure HTML output** using the corresponding `TEMPLATES/<type>.md` template.  
All `{PLACEHOLDER}` variables are replaced — zero placeholders in the output.  
Use this when you want copy-paste ready code to deploy directly.

**Syntax:**
```bash
/writehtml <type> "prompt" [--flags]
```

Supports the same types and all the same flags as `/write`.

**After output**, the agent will offer:
- *"give me raw HTML only"* → strips markdown wrapping, returns pure code block
- *"run /checks"* → re-runs SEO audit on the generated output

**Examples:**
```bash
/persona ecommerce-manager
/writehtml Productused "Leica M6 TTL Chrome, serial 2741xxx, EX+ condition" --primary-kw "leica m6 ttl kaufen" --lang de

/persona vintage-expert
/writehtml Productnew "Leica M6 TTL Silver 0.85, brand new in original box" --primary-kw "leica m6 ttl neu kaufen" --lang de

/persona blogger
/writehtml Blogpost "How to identify a genuine Leica M6" --primary-kw "leica m6 original erkennen" --lang de --depth deep

/persona ecommerce-manager
/writehtml FAQ "Common questions about used Leica cameras" --primary-kw "leica kamera gebraucht faq" --lang de
```

---

## `/research`

Builds a keyword cluster and SERP analysis for a topic before writing.  
Run this before `/write` or `/writehtml` to inform your keyword strategy.

**Syntax:**
```bash
/research "topic" [--include-competitors]
```

**Output includes:**
- Primary keyword (high intent, high volume)
- Long-tail keyword variations (lower competition)
- Related keyword clusters
- SERP features detected (snippets, PAA boxes, images, shopping results)
- Competitor content gaps identified

**Examples:**
```bash
/research "leica m6 gebraucht kaufen"
/research "vintage analog camera berlin" --include-competitors
/research "rangefinder camera beginner guide"
```

---

## `/checks`

Runs an SEO audit checklist. Two modes: live URL or page-type preview.

**Syntax:**
```bash
/checks <url>           ← audit against a live page
/checks <type>          ← audit against page-type template (preview mode)
/checks <type> --strict ← stricter threshold checks
```

**Audit output includes:**
- Page-type-specific dos and don'ts (`SEO_CHECKS/do-and-don-lists.md`)
- Missing or malformed meta tags
- Schema validation (missing fields, wrong types)
- Keyword placement issues
- Internal linking gaps
- Pass rate + prioritized recommendations

**Examples:**
```bash
/checks https://www.example.de/products/leica-m6-ttl-chrome
/checks Productused
/checks Blogpost --strict
/checks Landingpage
```

---

## `/brand`

Loads a client brand profile and makes it active for the current session.
The brand profile adds CTAs, vocabulary rules, trust blocks, and compliance constraints
on top of the active persona and locale.

Brand stays active until changed or the session resets.

**Syntax:**
```bash
/brand <id>
```

**Examples:**
```bash
/brand example-shop
/brand example-agency
```

**What /brand activates:**

| Layer | What Changes |
|-------|-------------|
| CTAs | Brand-specific CTAs replace locale defaults in all {CTA_*} variables |
| Tone | Brand slider values adjust the active persona's tone defaults |
| Vocabulary | Brand preferred terms and banned phrases enforced in Step 3 + Step 6.6 |
| Trust blocks | `{BRAND_TRUST_BLOCK}` and `{BRAND_RETURN_POLICY}` available in templates |
| Compliance | Step 6.6 runs: banned phrases, urgency limits, required disclosures |

**Brand + Persona + Locale — the three layers:**

| Layer | Controls | Changes Per |
|-------|----------|-------------|
| **Persona** | Writing style, vocabulary richness, heading formulas, E-E-A-T | Content type / mood |
| **Brand** | Client identity, CTAs, banned terms, trust blocks, compliance | Client / project |
| **Locale** | Language, currency, date format, schema language fields | Market / language |

These three layers are independent — they stack without conflicting.
A single brand can be written by multiple personas. A single persona can serve multiple brands.

---

## `/brands`

Lists all available brand profiles or shows full details for one.

**Syntax:**
```bash
/brands
/brands --show <id>
```

**Examples:**
```bash
/brands
/brands --show example-shop
```

---

## `/seobrief`

Generates a structured SEO content brief before writing begins.
The brief is saved to `SEO_BRIEFS/<brief-id>.md` and can be passed to `/write`
or `/writehtml` using the `--from-brief` flag to ensure the generated content
follows the researched outline, keywords, and internal link targets.

**Always uses `researcher` persona internally** — regardless of the active session persona.
This keeps keyword analysis neutral and free of sales language.

**Syntax:**
```bash
/seobrief <type> "topic" [--flags]
```

**Supported Types:**
Same as `/write` — `Blogpost`, `Landingpage`, `Productnew`, `Productused`, `FAQ`, `Socialphoto`, `Socialvideo`

**Flags:**

| Flag | Required | Purpose | Example |
|------|----------|---------|---------|
| `"topic"` | ✅ Yes | Topic or product to brief | `"Leica M6 film photography guide"` |
| `<type>` | Recommended | Page type (auto-detected if omitted) | `Blogpost` |
| `--primary-kw` | Optional | Override auto-detected primary keyword | `--primary-kw "leica m6 kaufen"` |
| `--lang` | Optional | Language for keyword research direction | `--lang de` |
| `--depth` | Optional | Brief depth: `light` / `standard` / `deep` | `--depth deep` |
| `--brand` | Optional | Load brand profile for CTA and compliance hints | `--brand example-shop` |

**Output includes:**

- 🎯 Strategic Summary (primary KW, intent, recommended type, word count, persona suggestion)
- 🔑 Keyword Cluster (primary + 4–6 long-tail variations with est. volume + difficulty)
- 📐 Recommended Outline (H1 + H2–H4 structure with topic hints per section)
- ❓ People Also Ask questions to cover (5–10 PAA-style Q&As)
- 🏆 Competitor Analysis (2–3 competitor URLs: strengths, weaknesses, our angle)
- 🔗 Internal Link Targets (anchor text + target URL + placement hint)
- ▶️ Next Step (ready-to-run `/write` command at the bottom — always)

**Examples:**
```bash
/seobrief Blogpost "Best Hiking Boots for Beginners 2026" --lang en --brand example-shop
/seobrief FAQ "Common questions about trail running shoes" --primary-kw "trail shoes faq" --lang en
/seobrief Productused "Used Trail Running Shoe Model X" --lang en --depth deep
/seobrief Landingpage "Spring Sale 2026" --primary-kw "trail gear sale" --brand example-shop
```

**Using a brief with /write:**
```bash
# Generate brief first
/seobrief Blogpost "Best Hiking Boots Guide" --lang en --brand example-shop
# → Saved as SEO_BRIEFS/best-hiking-boots-guide-en.md

# Write content from brief (outline, KWs, and internal links auto-loaded)
/persona blogger
/write Blogpost "Best Hiking Boots Guide" --from-brief best-hiking-boots-guide-en --lang en

# Or generate HTML from brief
/persona blogger
/writehtml Blogpost "Best Hiking Boots Guide" --from-brief best-hiking-boots-guide-en --lang en
```

**`--from-brief` flag (for `/write` and `/writehtml`):**

When `--from-brief <brief-id>` is set:
- The brief's keyword cluster is used as the KW strategy (unless `--primary-kw` overrides it)
- The brief's approved outline guides H1–H4 structure
- PAA questions from the brief populate `{FAQ_Q*}` and `{FAQ_A*}` variables
- Internal link targets are injected as `{INTERNAL_LINKS_PRIMARY}` and `{INTERNAL_LINKS_SECONDARY}`
- The brief's word count target is passed to the depth check in Step 6.5

---

## `/seoplan`

Builds a complete SEO content plan for a niche, topic, or site architecture.
Outputs a structured cluster of nodes organised into four tiers — PILLAR, QUICKWIN,
FOUNDATION, and STRATEGIC — with keyword data, page type recommendations, persona
assignments, an internal link matrix, and a numbered execution order.

The plan is saved to `SEO_PLANS/<plan-id>.md` and can be referenced in any
`/seobrief` command using the `--plan <plan-id>.<node-id>` flag.

**`/seoplan` does not generate page content.** It is a strategy command — run it
once per niche/site and then execute node by node via `/seobrief` → `/write`.

**Syntax:**
```bash
/seoplan "niche or site concept" [--flags]
```

**Flags:**

| Flag | Required | Purpose | Example |
|------|----------|---------|---------|
| `"niche"` | ✅ Yes | Niche, site concept, or target topic | `"Vintage analog cameras Germany"` |
| `--mode` | Optional | `cluster` (default) or `site` | `--mode site` |
| `--lang` | Optional | Market/language for keyword research | `--lang de` |
| `--brand` | Optional | Load brand profile for persona defaults | `--brand example-shop` |
| `--priority` | Optional | `balanced` (default) / `quickwins` / `strategic` | `--priority quickwins` |
| `--depth` | Optional | `light` (4–6 nodes) / `standard` (8–14) / `deep` (15–25) | `--depth deep` |
| `--pages` | Optional | Override auto depth with exact target node count | `--pages 10` |

**`--mode` explained:**

| Mode | Output | Use When |
|------|--------|----------|
| `cluster` | 1 pillar + 8–14 supporting nodes with full detail per node | Starting a new niche or topic campaign |
| `site` | 3–5 cluster overviews (no deep node detail) + drill-down commands | Planning a full site from scratch |

**`--priority` explained:**

| Value | What Gets Emphasised | Use When |
|-------|---------------------|----------|
| `balanced` | All tiers, execution order: QW → FND → Pillar → Strategic | Default — comprehensive plan |
| `quickwins` | Only QUICKWIN nodes output | Client needs fast results, budget for 4–6 articles only |
| `strategic` | All nodes, but PILLAR + STRATEGIC at top | Long-term authority play, no urgency for fast traffic |

**Node Tiers — Quick Reference:**

| Tier | Difficulty | Timeline to Rank | Intent | Persona Mix |
|------|-----------|-----------------|--------|-------------|
| **PILLAR** | 40–70 | 3–6 months | Commercial | Zone A: researcher + Zone B: ecommerce-manager |
| **QUICKWIN** | < 25 | 4–8 weeks | Informational | Zone A: blogger or researcher, Zone B: none |
| **FOUNDATION** | 20–40 | 8–16 weeks | Informational | Zone A: blogger or vintage-expert, Zone B: none |
| **STRATEGIC** | > 40 | 6–12 months | Commercial / Transactional | Zone A: researcher + Zone B: ecommerce-manager |

**Output includes:**

- 🗺️ Topical Map overview (text tree)
- 🏛️ Pillar page (full node card)
- ⚡ Quick Win nodes (table + node cards)
- 🧱 Foundation nodes (table + node cards)
- 🏔️ Strategic nodes (table + node cards)
- 🔗 Internal Link Matrix (who links to whom)
- 📋 Execution Order (numbered, with timeline estimates)
- ▶️ Next Step (first `/seobrief` command to run)

**After output, the brain offers:**
- `"show me only quick wins"` → reprint QUICKWIN section only
- `"generate brief for [node-id]"` → immediately run `/seobrief` for that node
- `"show link matrix"` → reprint internal link matrix only
- `"export execution order"` → print numbered execution list only

**Examples:**

```bash
# Standard cluster plan (8–14 nodes, balanced priority)
/seoplan "Outdoor hiking gear Germany" --lang de --brand example-shop

# Quick wins only — fast client deliverable
/seoplan "Local bakery SEO Berlin" --lang de --priority quickwins --depth light

# Full site architecture overview
/seoplan "Sports e-commerce Germany" --lang de --mode site

# Deep cluster — maximum node count
/seoplan "Trail running shoes" --lang en --brand example-shop --depth deep

# Strategic focus — authority building, no urgency
/seoplan "Wedding photography services" --lang en --priority strategic
```

**Full workflow: Plan → Brief → Write**

```bash
# Step 1: Build the cluster plan
/seoplan "Outdoor hiking gear Germany" --lang de --brand example-shop
# → Saved as SEO_PLANS/outdoor-hiking-gear-de.md

# Step 2: Generate a brief for the first Quick Win node
/seobrief Blogpost "How to choose hiking boots" --plan outdoor-hiking-gear-de.qw-01 --lang en
# → Saved as SEO_BRIEFS/how-to-choose-hiking-boots-en.md

# Step 3: Write content from the brief
/brand example-shop
/persona blogger
/write Blogpost "How to choose hiking boots" --from-brief how-to-choose-hiking-boots-en --lang en
# → Returns: full plain text article, brief-aligned, brand-compliant
```

---

## `--lang` — Language Flag

Loads the corresponding locale file from `LOCALE/<code>.md` on top of `LOCALE/base.md`.  
Applies to `/write` and `/writehtml` only.

| Code | Language | File Loaded | Status |
|------|----------|-------------|--------|
| `de` | German | `LOCALE/de.md` | ✅ Available |
| `fr` | French | `LOCALE/fr.md` | 🔜 Planned |
| `es` | Spanish | `LOCALE/es.md` | 🔜 Planned |
| `pt` | Portuguese | `LOCALE/pt.md` | 🔜 Planned |

**What `--lang de` changes:**
- `<html lang="de">`, `og:locale` → `de-DE`
- Date format → `DD.MM.YYYY`
- Price format → `1.090,00 €`
- Schema `inLanguage` → `de`, `addressCountry` → `DE`
- Writing mode → formal Sie-Form (unless `--tone casual` is set)
- Slugs → umlaut transliteration (`ä→ae`, `ö→oe`, `ü→ue`, `ß→ss`)
- All CTA labels → German (`Jetzt kaufen`, `In den Warenkorb`, etc.)
- Condition labels → German (`Sehr gut`, `Für Bastler`, etc.)

If `--lang` is omitted → English defaults from `LOCALE/base.md` are used.

---

## Quick Reference

/persona <id> [--tone] Set persona (stays active)
/personas List all personas
/personas --show <id> Show persona details

/write <type> "prompt" → Plain text, editor-ready
/writehtml <type> "prompt" → Pure HTML, deploy-ready

Common flags (both /write and /writehtml):
--primary-kw "keyword" Main target keyword
--secondary-kw "keyword" Secondary keyword
--lang de German output (de.md)
--tone <adjective> Tone override
--depth light|standard|deep Content depth

/research "topic" [--include-competitors] Keyword cluster + SERP analysis
/checks <url> SEO audit — live URL
/checks <type> [--strict] SEO audit — template preview

/brand <id>              Load client brand profile (stays active)
/brands                  List all brand profiles
/brands --show <id>      Show full brand profile details

/seobrief <type> "topic" Generate SEO content brief
  --primary-kw           Override primary keyword
  --lang de              Keyword research in target language
  --depth standard       Brief detail level
  --brand <id>           Apply brand profile to brief

New flag for /write and /writehtml:
  --from-brief <id>      Load brief for outline, KWs, and internal links
  
/seoplan "niche" [--flags]     Build cluster/site plan → save to SEO_PLANS/
  --mode cluster|site            cluster = one topic cluster (default), site = full architecture
  --lang de                      Market for keyword research
  --brand <id>                   Apply brand profile to node persona defaults
  --priority balanced|quickwins|strategic  What to focus on
  --depth light|standard|deep    Number of nodes (4–6 / 8–14 / 15–25)
  --pages <n>                    Override depth with exact node count

New flag for /seobrief, /write, /writehtml:
  --plan <plan-id>.<node-id>     Load plan node: KWs, page type, persona hints, internal links

---

*Last updated: 07-04-2026 (v0.6)*  
*Adds: /brand, /brands, /seobrief, --from-brief flag*
*Maintainer: Chris — SEOwlsClaw command reference*

path: PAGE_STRUCTURES.md
content: # SEOwlsClaw — Page Structure Templates (v0.1)

## Master Index

This file indexes all page-type templates for quick reference and editing. **To customize headers or structure for any page type, edit the corresponding file in `templates/` folder directly.**

| File | Content Type | When to Use | Edit This If... |
|------|------|-----|-----|
| `templates/landing_page_template.md` | Landing Page | Sale campaigns, newsletter launches | You want different H1/H2 structure for your sale page |
| `templates/blog_post_template.md` | Blog Post | Organic SEO articles | Your blog needs question-first headers |
| `templates/product_new_template.md` | Product (New) | New physical/digital products | Technical specs section should be H3 not H4 |
| `templates/product_used_template.md` | Product (Used) | Refurbished, second-hand items | Condition report needs different hierarchy |
| `templates_social/photo_post_template.md` | Social Media (Photo) | Image + caption SEO | Alt text structure needs adjustment |
| `templates_social/video_post_template.md` | Social Media (Video) | YouTube/TikTok metadata | Video description format differs |

---

## Quick Edit Guide

### Example: Change Used Product H3 Header
1. Open `templates/product_used_template.md`
2. Find line with `## **H3**` 
3. Edit the text → Save
4. Next generation uses new structure automatically

### Example: Add New Page Type
1. Create `templates/my_custom_type_template.md`
2. Define H1-H6 hierarchy in same style as other templates
3. Add to master index table above
4. Update `PAGE_STRUCTURES.md` with your new type's file path

---

## Template File Formats (Reference)

Each template file uses this structure:
```markdown
<!-- Page Type: [type] -->
<!-- Generated by SEOwlsClaw v0.1 -->

#H1 Main Title (SEO optimized, includes main keyword)

## H2 Section 1
Content...

### H3 Subsection 1
More content...
```

**All templates output clean HTML5 ready for direct copy-paste deployment.**

---

*Last updated: 2026-03-20 (v0.1 initial build)*  
*Maintainer: Chris — customize via this index file or directly edit template files*


path: SEO_PATH.md
content: # SEOwlsClaw — Complete SEO Path Workflow (v0.1)

## Purpose
This document maps out the full SEO workflow for SEOwlsClaw: Research → Keyword Cluster → Content Gap Analysis → Persona-Driven Writing → Template Generation → Final Quality Checks.

**Use this guide to understand how all components work together before deployment.**

---

## Step 1: Research Phase — Keyword Discovery & SERP Analysis
**Command**: `/research <topic>`

### What Gets Generated
```markdown
## Primary Keyword (High Intent, High Volume)
- Target: "best hiking water bottles Berlin"
- Volume: ~50 searches/month in Germany
- Difficulty: 42/100 (moderate competition)

## Long-Tail Variations (Lower Competition)
1. "Best sustainable hiking water bottles for winter hikes" — 35 m/mo, Diff: 18
2. "Water bottle capacity vs insulation comparison" — 22 m/mo, Diff: 31
3. "Refurbished water bottles Berlin discount" — 12 m/mo, Diff: 5

## SERP Features Detected (Page Type Guide)
- Featured Snippets opportunity (comparison table in #4)
- People Also Ask section (how to choose bottle?)
- Video results (product reviews on YouTube)
- Image pack (water bottle buying guide images)
```

### How It Works
1. Web search query for main topic + keywords from your content brief
2. Analyzes SERP structure (snippets, images, videos detected)
3. Identifies keyword clusters related to primary target
4. Flags competitive gaps and content opportunities

**Example Usage**:
```bash
/persona Researcher /research best-hiking-water-bottles-berlin-2026
```

---

## Step 2: Content Gap Analysis — Compare vs Competitors
**Command**: `/checks <url>` or manual analysis via SKILL.md variables

### What Gets Analyzed
```markdown
## Competitive Benchmark (Example)
URL: https://competitor.com/best-water-bottles-guide
Strengths: Comparison table, word count 2.5k+, video integration
Weaknesses: No schema markup, thin FAQ section, missing H1 keywords

## Our Opportunities
- Add comparison tables (SEO gold for featured snippets)
- Include schema.org Article + FAQ structure
- Expand FAQ section with Q&A format (People Also Ask optimization)
```

### How It Works
1. Identify main keyword + target audience intent
2. Find 2-3 competitor URLs for reference
3. Analyze what they have right (structure, schema, depth)
4. Spot gaps we can fill (unique angles, missing sections)

**Example Usage**:
```bash
/checks https://example.com/best-hiking-water-bottles-guide
/persona Researcher /write Blogpost "Best Hiking Water Bottles for Berlin — Complete 2026 Guide"
```

---

## Step 3: Persona Selection & Writing Style Setup
**Command**: `/persona <name>` (run BEFORE /write)

### Available Personas
| Persona | Best For | Style Profile |
|---------|----------|--------------|
| **E-Commerce Manager** | Product pages, sales campaigns | Persuasive, urgency-driven, benefit-focused |
| **Creative Writer** | Brand storytelling, emotional content | Story-driven, vivid imagery, relatable |
| **Blogger** | Educational guides, evergreen articles | Clear structure, actionable tips, professional yet approachable |
| **Researcher** | Data-driven content, competitor analysis | Fact-based, neutral tone, question-first format |

### How To Use
```bash
# Step 3a: Set your writing persona
/persona E-Commerce Manager --tone enthusiastic

# Step 3b: Write content with this persona
/persona E-Commerce Manager /write Landingpage "We're offering massive discounts on premium electronics — limited time only" --primary-kw summer-sale-electronics

# Or combine personas for complex tasks
/persona Creative Writer --vocabulary "dream, journey, adventure" /write Blogpost "Sustainable Hiking Gear Guide"
```

---

## Step 4: Template Selection & Content Generation
**Command**: `/write <type> "content_prompt"`

### Supported Page Types
| Type | When to Use | Word Count Target |
|------|-----|----------|
| `Landingpage` | Sale campaigns, newsletter launches, urgency-focused sales | 800-1200 words |
| `Blogpost` | Organic SEO articles, storytelling content | 1500+ words |
| `Productnew` | New physical/digital products (tech specs focus) | 300-500 words + specs |
| `Productused` | Refurbished/second-hand items (condition reports) | 400-600 words + condition |
| `Socialphoto` | Visual posts + alt text optimization | 100-200 words |
| `Socialvideo` | YouTube/TikTok metadata + transcripts | 150-300 words |

### How It Works
1. Your prompt includes product details, keywords, personas, briefs
2. System selects appropriate template from `templates/` folder
3. Applies persona style (vocabulary, tone) to content
4. Injects SEO variables (meta tags, schema, canonical URL)
5. Generates clean HTML ready for copy-paste deployment

**Example Usage**:
```bash
/persona E-Commerce Manager /write Landingpage "20% off premium electronics sale starting May 1st" --primary-kw summer-sale-electronics
/persona Creative Writer /write Blogpost "Why Choose Sustainable Hiking Gear?" --primary-kw eco-friendly-hiking-gear
/persona Researcher /write Productnew "EcoSmart Water Bottle with Lifetime Warranty" --primary-kw sustainable-water-bottle
```

---

## Step 5: Quality Checks — Validate Before Deployment
**Command**: `/checks <url>` or `/checks <type>` (preview mode)

### Check Categories by Page Type

#### Landing Pages
- ✅ Title tag < 60 chars + primary keyword present
- ✅ Meta description < 160 chars + CTA phrase included
- ✅ Scarcity language used ("limited", "only X left")
- ✅ Schema.org Event/Offer JSON-LD markup
- ✅ Internal linking (FAQ, related products via H6 footer)

#### Blog Posts
- ✅ Question-first headers ("How to...", "Why...")
- ✅ Word count 1500+ for competitive queries
- ✅ Comparison table included (featured snippet target)
- ✅ Schema.org Article + author markup

#### Product New Pages
- ✅ Technical specs in dl/dl format with dt/dd labels
- ✅ AggregateRating schema for star ratings
- ✅ Feature comparison table vs. previous model/competitors
- ✅ Clear warranty/guarantee bullet points

#### Product Used Pages
- ✅ Condition report H3/H4 sections visible
- ✅ Transparency in cosmetic wear disclosure
- ✅ Value proposition percentage vs. new pricing
- ✅ Warranty section with return policy details

### Check Example Output
```bash
/checks https://example.com/summer-sale-2026

SEOwlsClaw — SEO Checks Report (v0.1)
Date: 2026-03-20 | Type: Landingpage

✅ Title tag < 60 chars (passed)
✅ Meta description < 160 chars (passed)
✅ H1 tag exists + unique (passed)
✅ Schema.org Event/Offer JSON-LD (passed)
✅ Alt text on images (passed)
❌ Keyword density > 2% (failed — recommendation: Reduce repetition)

Issues Found: 1 | Pass Rate: 95%
```

---

## Step 6: Post-Generation Tasks & Tracking
**Files to Update**: `CHANGELOG.md`, `TODO.md`, `BUGS.md`

### After Successful Generation
**File**: `CHANGELOG.md` — Record version + changes
```markdown
[v0.2] 2026-03-20 — Added social video template (templates_social/video_post_template.md)
[Fix v0.1] 2026-03-21 — Fixed product used schema condition field parsing
[Todo v0.3] 2026-03-22 — Implement multi-language variable support (German/French)
```

### After Bug Discovery
**File**: `BUGS.md` — Document issue + resolution
```markdown
#12 Schema parsing failed for used products 2026-03-20 — Fixed condition field JSON structure in product_used_template.md
#18 Keyword density check threshold incorrect 2026-03-21 — Updated to use exact 2.0% instead of >2%
```

### For Active Development
**File**: `TODO.md` — Track upcoming tasks
```markdown
- [ ] Fix used product H4 header hierarchy (cosmetic condition section)
- [ ] Add schema.org FAQ markup for all blog posts
- [ ] Test social video template on real YouTube uploads
- [ ] Implement multi-language variable support (DE/FR)
```

---

## Full Workflow Example — Generate a Sale Landing Page End-to-End

### Start Here: Run This Sequence in Order

```bash
# Step 1: Research the keyword cluster
/persona Researcher /research 20% electronics sale Berlin May 2026

# Step 2: Set persona for conversion-focused writing
/persona E-Commerce Manager --tone enthusiastic

# Step 3: Generate content with template
/persona E-Commerce Manager /write Landingpage "We're offering massive discounts on our top X Y Z products starting May 1st where we give limited-time deals to early birds" --primary-kw summer-sale-electronics --secondary-kw limited-offer

# Step 4: Check quality before deployment
/checks https://example.com/summer-sale-2026

# Step 5: Generate output HTML (system creates it in OUTPUT_EXAMPLES/)
```

### What Gets Created Automatically
- Clean HTML file ready for copy-paste into WordPress/custom host
- Schema.org JSON-LD markup included
- Internal linking section with H6 links
- SEO variables injected (canonical URL, meta tags)
- Quality check report (pass/fail list)

---

## Variable Injection System — How SEOwlsClaw Works Behind the Scenes

```json
{
  "siteStructure": {
    "url": "https://example.com",
    "canonicalUrl": "https://example.com/summer-sale-2026"
  },
  "metadata": {
    "titleLength": 60,
    "metaDescriptionLength": 160,
    "robots": "index,follow"
  },
  "keywords": {
    "primaryKw": "summer-sale-electronics",
    "secondaryKw": ["limited-offer", "flash-sale"],
    "longTailKw": [
      "20% electronics sale Berlin May 2026",
      "best discount electronics summer 2026"
    ]
  },
  "headersByPageType": {
    "landingpage": {
      "H1": "Exclusive Summer Sale: Save Up to 40% on Premium Electronics",
      "H2": "Why This Sale Is Your Best Chance to Save Big"
    }
  },
  "optimization": {
    "wordCountTarget": 1000,
    "imageRatio": 1.5,
    "loadSpeedGoal": "<3s"
  },
  "schemaTypes": ["Event", "Offer"]
}
```

---

## Editing Templates Manually — Quick Guide

**To customize H1-H6 structure for any page type**:
1. Open `templates/landing_page_template.md` (or other template file)
2. Edit the `{PLACEHOLDER}` text in header lines (H1, H2, etc.)
3. Save and regenerate → new structure automatically used!

**Example - Change Used Product H3 Header**:
```markdown
<!-- File: templates/product_used_template.md -->

OLD STRUCTURE:
### **H3: Cosmetic Condition Report**

NEW STRUCTURE:
### **H3: Wear & Tear Analysis**  ← Edit this line directly!
```

---

## Next Steps After Initial Build (v0.1)

| Version | Goal | Action Required |
|---------|------|-------|
| **v0.2** | Test templates on live content | Run `/write` command → Check output quality |
| **v0.3** | Add multi-language support | Update variables to support DE/FR translations |
| **v0.4** | Competitor analysis automation | Auto-scrape SERP benchmarks via web_search |

---

*Last updated: 2026-03-20 (v0.1 initial build)*  
*Maintainer: Chris — complete SEO workflow from research to deployment*  
*Ready for testing with /write command → See OUTPUT_EXAMPLES/ folder for reference outputs!*


path: TEMPLATES_SOCIAL/photo_post_template.md
content: <!-- Page Type: Socialphoto -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE} — {DESCRIPTION}</title>
    <meta name="description" content="{DESCRIPTION_LENGTH_160_chars_max}">
    
    <!-- Schema: ImageObject or Article -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "ImageObject",
      "url": "{IMAGE_URL}",
      "caption": "{CAPTION_TEXT_ALTERNATE}",
      "license": "{LICENSE_URL_OR_CREDIT}"
    }
    </script>
</head>
<body>

    <!-- SOCIAL HEADER -->
    <header class="social-header">
        <h1>{H1_SHORT_TITLE_KEYWORD} — {SHORT_DESCRIPTION}</h1>
        <p class="platform-tag">{PLATFORM_NAME}</p>
    </header>

    <!-- ALT TEXT SECTION -->
    <section class="alt-text-section">
        <h3><strong>Alt Text for SEO & Accessibility</strong></h3>
        <p>{ALT_TEXT_DESCRIPTION_120_CHARS_MAX} — Optimized for search engines + screen readers</p>
    </section>

    <!-- CAPTION H5 Section -->
    <section class="caption-section">
        <h5>{H5_CAPTION_ENGAGING_KEYWORD}</h5>
        <p>{CAPTION_CONTENT_100_CHARS_MAX} — {CALL_TO_ACTION_BULLET}</p>
    </section>

    <!-- HASHTAGS H6 Section -->
    <footer class="hashtags">
        <h6>#hashtag_primary_keyword</h6>
        <h6>#hashtag_target_audience</h6>
        <h6>#hashtag_product_category</h6>
        <h6>#hashtag_trend_topic_2026</h6>
    </footer>

    <!-- LINK INTEGRATION -->
    <div class="link-integration">
        <a href="{PRODUCT_PAGE_LINK}">{BRAND_NAME_PRODUCT_LINK_TEXT}</a>
    </div>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- Photo posts focus on visual SEO with alt text, hashtags, and platform-specific formatting! -->


path: TEMPLATES_SOCIAL/video_post_template.md
content: <!-- Page Type: Socialvideo -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE} — {DESCRIPTION}</title>
    <meta name="description" content="{DESCRIPTION_LENGTH_160_chars_max}">
    
    <!-- Schema: VideoObject or Article -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "VideoObject",
      "name": "{TITLE}",
      "description": "{DESCRIPTION}",
      "thumbnailUrl": "{THUMBNAIL_URL}",
      "uploadDate": "{UPLOAD_DATE_FORMATTED}",
      "creator": {
        "@type": "Organization",
        "name": "{BRAND_OR_CHANNEL_NAME}"
      },
      "contentUrl": "{VIDEO_URL_YOUTUBE_TIKTOK}"
    }
    </script>
</head>
<body>

    <!-- SOCIAL HEADER -->
    <header class="social-header-video">
        <h1>{H1_SHORT_TITLE_KEYWORD} — {SHORT_DESCRIPTION}</h1>
        <p class="platform-tag">{PLATFORM_NAME_YOUTUBE_TIKTOK}</p>
        <div class="duration-indicator">{DURATION_FORMATTED_MINUTES_SECONDS}</div>
    </header>

    <!-- TITLE + DESCRIPTION SECTION -->
    <section class="video-meta">
        <h3><strong>YouTube/TikTok SEO Title</strong></h3>
        <p>{TITLE_YT_TITLE_KEYWORDS_120_CHARS_MAX}</p>
        
        <h4><strong>Detailed Description (First 200 chars crucial)</strong></h4>
        <p>{DESCRIPTION_FIRST_200_CHARS_MAX} — Includes primary keyword for search snippet</p>
    </section>

    <!-- TRANSCRIPT NOTES H5 Section -->
    <section class="transcript-section">
        <h5><strong>Key Moments / Timestamps (For SEO + Accessibility)</strong></h5>
        <ul class="timestamps">
            <li>{TIMESTAMP_0_MINUTES_SECONDS} — Intro & Hook</li>
            <li>{TIMESTAMP_1_MINUTES_SECONDS} — Main Content Highlight</li>
            <li>{TIMESTAMP_2_MINUTES_SECONDS} — Call to Action CTA</li>
        </ul>
    </section>

    <!-- ALT TEXT H6 Section -->
    <footer class="alt-text-video">
        <h6><strong>Voiceover/Alt Text for SEO</strong></h6>
        <p>{ALT_TEXT_TRANSCRIPT_100_CHARS_MAX}</p>
        <ul class="transcript-bullets">
            <li>{KEYWORD_MENTION_IN_VIDEO}</li>
            <li>{SECONDARY_KEYWORD_MENTIONED}</li>
        </ul>
    </footer>

    <!-- LINK INTEGRATION -->
    <div class="link-integration-video">
        <a href="{VIDEO_PAGE_LINK_YOUTUBE}">{BRAND_NAME_PRODUCT_LINK_TEXT}</a>
    </div>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- Video posts need YouTube/TikTok SEO optimization with transcripts, timestamps, and descriptive alt text! -->


path: TEMPLATES/blog_post_template.md
content: <!-- Page Type: Blogpost -->
<!-- Generated by SEOwlsClaw v0.6 -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE}</title>
    <meta name="description" content="{META_DESCRIPTION}">
    <link rel="canonical" href="{URL_CANONICAL}">
    
    <!-- Schema: Article -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "{TITLE}",
      "description": "{META_DESCRIPTION}",
      "datePublished": "{DATE_FORMATTED}",
      "author": {
        "@type": "Person",
        "name": "{AUTHOR_NAME}"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="blog-hero">
        <h1>{H1_TITLE}</h1>
        <p>{HERO_SUBHEADLINE_200_CHARS_MAX}</p>
        <div class="meta-info">{WORD_COUNT_WORDS} words | {POST_DATE_FORMATTED}</div>
    </header>

    <!-- INTRODUCTION H2 -->
    <section class="intro">
        <h2>{INTRO_H2_TITLE}</h2>
        <p>{INTRO_CONTENT_500_CHARS_MAX}</p>
    </section>

    <!-- MAIN BODY H2s with Subsections -->
    <section class="main-body">
        <h2>{H2_SECTION_1_TITLE}</h2>
        <p>{BODY_CONTENT_500_CHARS_MAX}</p>
        
        <h3>{H3_SUBSECTION_1_TITLE}</h3>
        <ul>
            <li>{STEP_1_DETAIL}</li>
            <li>{STEP_2_DETAIL}</li>
        </ul>

        <h4>{H4_SUBSECTION_2_TITLE}</h4>
        <ol>
            <li>{TIP_1_ACTIONABLE}</li>
            <li>{TIP_2_ACTIONABLE}</li>
        </ol>
    </section>

    <!-- COMPARISON SECTION H2 -->
    <section class="comparison">
        <h2>{H2_COMPARISON_TITLE}</h2>
        <table>
            <thead>
                <tr><th>Feature</th><th>Option A</th><th>Option B</th></tr>
            </thead>
            <tbody>
                <tr><td>{COMPARISON_CATEGORAY}</td><td>{COMP_A}</td><td>{COMP_B}</td></tr>
            </tbody>
        </table>
    </section>

    <!-- CONCLUSION H5 -->
    <section class="conclusion">
        <h5>{H5_FINAL_THOUGHT_TITLE}</h5>
        <p>{CONCLUSION_CONTENT_300_CHARS_MAX}</p>
        <a href="{READ_MORE_LINK}" class="read-more-link">Read More →</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="related-articles">
        <h6><a href="{RELATED_PAGE_1}">{LINK_TITLE_1}</a></h6>
        <h6><a href="{RELATED_PAGE_2}">{LINK_TITLE_2}</a></h6>
        <h6><a href="{RELATED_PAGE_3}">{LINK_TITLE_3}</a></h6>
    </footer>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- Blog posts thrive on question-first headers and comparison tables for SEO depth if needed or suitable! -->


path: TEMPLATES/faq_page_template.md
content: <!-- Page Type: FAQ -->
<!-- Generated by SEOwlsClaw v0.7 -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE}</title>
    <meta name="description" content="{META_DESCRIPTION}">
    
    <!-- Schema: FAQPage (Google EEAT Signal!) -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "{QUESTION_1}",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "{ANSWER_1}"
          }
        },
        {
          "@type": "Question",
          "name": "{QUESTION_2}",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "{ANSWER_2}"
          }
        },
        {
          "@type": "Question",
          "name": "{QUESTION_3}",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "{ANSWER_3}"
          }
        },
        {
          "@type": "Question",
          "name": "{QUESTION_4}",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "{ANSWER_4}"
          }
        },
        {
          "@type": "Question",
          "name": "{QUESTION_5}",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "{ANSWER_5}"
          }
        }
      ]
    }
    </script>

    <!-- Schema: WebPage (Additional EEAT Signal) -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "WebPage",
      "name": "{TITLE}",
      "description": "{META_DESCRIPTION}",
      "url": "{URL_CANONICAL}",
      "inLanguage": "en-US"
    }
    </script>

    <!-- Schema: Article (Content Context) -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "{TITLE}",
      "author": {
        "@type": "Person",
        "name": "{AUTHOR_NAME}"
      },
      "datePublished": "{DATE_FORMATTED}",
      "mainEntityOfPage": {
        "@type": "WebPage"
      }
    }
    </script>

    <!-- Author Bio for EEAT (Google's E-E-A-T Requirement!) -->
    <div itemscope itemtype="https://schema.org/Person">
      <meta itemprop="name" content="{AUTHOR_NAME}">
      <meta itemprop="jobTitle" content="{AUTHOR_TITLE}">
      <meta itemprop="description" content="{AUTHOR_BIO_150_CHARS_MAX}">
    </div>

</head>
<body>

    <!-- HERO SECTION with Author Attribution -->
    <header class="faq-hero">
        <h1>{H1_TITLE}</h1>
        <p>{HERO_SUBHEADLINE_200_CHARS_MAX}</p>
        <div class="meta-info">{WORD_COUNT_WORDS} questions answered | Last updated: {POST_DATE_FORMATTED}</div>
    </header>

    <!-- INTRODUCTION H2 -->
    <section class="intro">
        <h2>{INTRO_H2_TITLE}</h2>
        <p>{INTRO_CONTENT_500_CHARS_MAX} — These answers are based on real-world testing and expert experience.</p>
    </section>

    <!-- MAIN FAQ BODY with Accordion-Style H3s -->
    <main class="faq-body">

        <!-- QUESTION 1 SECTION (H2 + Q/A) -->
        <article itemscope itemtype="https://schema.org/Question" itemprop="mainEntity">
            <h2 itemprop="name">{QUESTION_1}</h2>
            
            <section itemprop="acceptedAnswer" itemscope itemtype="https://schema.org/Answer">
                <div itemprop="text">
                    {ANSWER_1}

                    <!-- Sub-questions within answer (H3/H4 for depth) -->
                    <h3>{SUB_QUESTION_WITHIN_ANSWER}</h3>
                    <p>{SUB_ANSWER_CONTENT}</p>
                </div>
            </section>
        </article>

        <!-- QUESTION 2 SECTION -->
        <article itemprop="mainEntity">
            <h2 itemprop="name">{QUESTION_2}</h2>
            
            <section itemprop="acceptedAnswer" itemscope itemtype="https://schema.org/Answer">
                <div itemprop="text">
                    {ANSWER_2}

                    <!-- Sub-questions within answer -->
                    <h3>{SUB_QUESTION_WITHIN_ANSWER}</h3>
                    <p>{SUB_ANSWER_CONTENT}</p>
                </div>
            </section>
        </article>

        <!-- QUESTION 3 SECTION (Longer Answer with Table) -->
        <article itemprop="mainEntity">
            <h2 itemprop="name">{QUESTION_3}</h2>
            
            <section itemprop="acceptedAnswer" itemscope itemtype="https://schema.org/Answer">
                <div itemprop="text">
                    {ANSWER_3}

                    <!-- Comparison Table for EEAT Signal -->
                    <table class="comparison-table">
                        <thead>
                            <tr><th>Metric</th>{TH_COMPARISON_COL}</tr>
                        </thead>
                        <tbody>
                            <tr><td>{ROW_DATA_1_METRIC}</td><td>{ROW_DATA_1_VALUE}</td></tr>
                            <tr><td>{ROW_DATA_2_METRIC}</td><td>{ROW_DATA_2_VALUE}</td></tr>
                        </tbody>
                    </table>

                    <!-- Actionable Takeaway -->
                    <h3>{ACTIONABLE_TAKEAWAY_TITLE}</h3>
                    <p>{TAKEAWAY_CONTENT}</p>
                </div>
            </section>
        </article>

        <!-- QUESTION 4 SECTION (Myth-Busting Format) -->
        <article itemprop="mainEntity">
            <h2 itemprop="name">{QUESTION_4}</h2>
            
            <section itemprop="acceptedAnswer" itemscope itemtype="https://schema.org/Answer">
                <div itemprop="text">
                    {ANSWER_4}

                    <!-- Myth vs Reality Table -->
                    <table class="myth-vs-reality">
                        <thead><tr><th>Myth</th><th>Reality (Based on Testing)</th></tr></thead>
                        <tbody>
                            <tr><td>{MYTH_1}</td><td>{REALITY_1}</td></tr>
                            <tr><td>{MYTH_2}</td><td>{REALITY_2}</td></tr>
                        </tbody>
                    </table>

                    <!-- Expert Tip for EEAT -->
                    <aside class="expert-tip">
                        <h4>💡 Expert Insight:</h4>
                        <p>{EXPERT_INSIGHT_CONTENT}</p>
                    </aside>
                </div>
            </section>
        </article>

        <!-- QUESTION 5 SECTION (Conclusion + Next Steps) -->
        <article itemprop="mainEntity">
            <h2 itemprop="name">{QUESTION_5}</h2>
            
            <section itemprop="acceptedAnswer" itemscope itemtype="https://schema.org/Answer">
                <div itemprop="text">
                    {ANSWER_5}

                    <!-- Call-to-Action for Related Products/Guides -->
                    <p class="cta">{CTA_CONTENT}</p>
                    
                    <!-- Internal Linking H6s (Related Questions) -->
                    <footer class="related-faqs">
                        <h6><a href="{RELATED_FAQ_1}">{LINK_TITLE_Faq_1}</a></h6>
                        <h6><a href="{RELATED_FAQ_2}">{LINK_TITLE_Faq_2}</a></h6>
                    </footer>
                </div>
            </section>
        </article>

    </main>

    <!-- INTERNAL LINKING H6s (Related Articles) -->
    <footer class="related-articles">
        <h3><strong>You might also want to read:</strong></h3>
        
        <h6><a href="{RELATED_PAGE_1}">{LINK_TITLE_ARTICLE_1}</a></h6>
        <h6><a href="{RELATED_PAGE_2}">{LINK_TITLE_ARTICLE_2}</a></h6>
    </footer>

</body>
</html>

<!-- Editing Guide: Replace {PLACEHOLDER} text before generation -->
<!-- FAQ pages require 5+ Q&A pairs for Google's Featured Snippet eligibility! -->
<!-- Always include author attribution and expert insights to boost E-E-A-T signals. -->

path: TEMPLATES/landing_page_template.md
content: <!-- Page Type: Landingpage -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE} — {DESCRIPTION}</title>
    <meta name="description" content="{DESCRIPTION_LENGTH_160_chars_max}">
    <link rel="canonical" href="{URL_CANONICAL}">
    
    <!-- Schema: Event or Organization Sale -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "{SCHEMA_TYPE}",
      "name": "{TITLE}",
      "description": "{DESCRIPTION}",
      "startDate": "{START_DATE_FORMATTED}",
      "endDate": "{END_DATE_FORMATTED}",
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "{PRICE_CURRENCY_PRICE}",
        "availability": "https://schema.org/InStock"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="hero-section">
        <h1>{H1_TITLE} — {PRIMARY_KEYWORD}</h1>
        <p>{HERO_SUBHEADLINE_URGENCY} — Only {SCARCITY_COUNT} left!</p>
        <a href="#cta" class="cta-button">Get Started Now</a>
    </header>

    <!-- VALUE PROPOSITION H2 -->
    <section class="value-prop">
        <h2>{H2_VALUE_PROP_TITLE}</h2>
        <p>{VALUE_CONTENT_300_CHARS_MAX}</p>
    </section>

    <!-- FEATURES SECTION H3s -->
    <section class="features">
        <h3>{H3_FEATURES_TITLE}</h3>
        <ul>
            <li>{LIST_ITEM_1_BENEFITS}</li>
            <li>{LIST_ITEM_2_LIMITED_OFFER}</li>
            <li>{LIST_ITEM_3_EXCLUSIVE_DEAL}</li>
        </ul>
    </section>

    <!-- SOCIAL PROOF H4s -->
    <section class="social-proof">
        <h4>{H4_TESTIMONIAL_TITLE}</h4>
        <blockquote>"{TESTIMONIAL_QUOTE} — {TESTIMONIAL_NAME}"</blockquote>
    </section>

    <!-- MAIN CTA H5 Section -->
    <section id="cta" class="cta-section">
        <h5>{H5_FINAL_CTA_TITLE}</h5>
        <p>{FINAL_CTA_BULLET_POINTS}</p>
        <a href="{CTA_LINK}" class="primary-cta-button">{BUTTON_TEXT_LIMITED_STOCK}</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="internal-links">
        <h6><a href="/related-product-page">{RELATED_PAGE_TITLE}</a></h6>
        <h6><a href="/faq-about-offer">{FAQ_SECTION_TITLE}</a></h6>
        <h6><a href="/privacy-policy">{POLICY_LINK}</a></h6>
    </footer>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- Example: If you want different H2 structure, edit line 19 and save! -->


path: TEMPLATES/product_new_template.md
content: <!-- Page Type: Productnew -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE} — {DESCRIPTION}</title>
    <meta name="description" content="{DESCRIPTION_LENGTH_160_chars_max}">
    <link rel="canonical" href="{URL_CANONICAL}">
    
    <!-- Schema: Product -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "{TITLE}",
      "description": "{DESCRIPTION}",
      "brand": "{BRAND_NAME}",
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "{PRICE_CURRENCY_PRICE}",
        "availability": "https://schema.org/InStock"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "{RATING_VALUE}",
        "ratingCount": "{RATING_COUNT}"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="product-hero">
        <h1>{H1_TITLE_BRAND_PRODUCT_KEYWORD}</h1>
        <p>{HERO_SUBHEADLINE_TECHNICAL_BENEFITS} — Perfect for {TARGET_USE_CASES}</p>
        <span class="price-tag">{DISPLAY_PRICE_EUR} / unit</span>
    </header>

    <!-- DESCRIPTION H2 -->
    <section class="product-description">
        <h2>{H2_DESCRIPTION_OVERVIEW_FEATURES}</h2>
        <p>{DESCRIPTION_CONTENT_400_CHARS_MAX}</p>
        <p>{USE_CASE_BULLET_POINTS}</p>
    </section>

    <!-- TECHNICAL SPECS H3 Section -->
    <section class="technical-specs">
        <h3>{H3_TECHNICAL_SPECS_TITLE_DETAILED}</h3>
        <dl class="specs-list">
            <dt>{SPEC_1_LABEL}</dt><dd>{SPEC_1_VALUE_UNIT}</dd>
            <dt>{SPEC_2_LABEL}</dt><dd>{SPEC_2_VALUE_UNIT}</dd>
            <dt>{SPEC_3_LABEL}</dt><dd>{SPEC_3_VALUE_UNIT}</dd>
            <dt>{SPEC_4_LABEL}</dt><dd>{SPEC_4_VALUE_UNIT}</dd>
        </dl>
    </section>

    <!-- COMPARISON H4 Section -->
    <section class="comparison-table">
        <h4>{H4_COMPARISON_NEW_VERSION_OR_BENEFITS}</h4>
        <table>
            <thead>
                <tr><th>Feature</th><th>Previous Version</th><th>New Model</th></tr>
            </thead>
            <tbody>
                <tr><td>{COMPARISON_CATEGORAY_1}</td><td>{COMPREV_A}</td><td>{COMPNEW_B}</td></tr>
                <tr><td>{COMPARISON_CATEGORAY_2}</td><td>{COMPREV_C}</td><td>{COMPNEW_D}</td></tr>
            </tbody>
        </table>
    </section>

    <!-- CTA H5 Section -->
    <section class="product-cta">
        <h5>{H5_PURCHASE_BUTTON_TEXT_LIMITED_STOCK}</h5>
        <ul class="cta-bullets">
            <li>{BULLET_1_WARRANTY_FREE_OR_GUARANTEE}</li>
            <li>{BULLET_2_SHIPPING_QUICK_DELIVERY}</li>
            <li>{BULLET_3_TECHNICAL_SUPPORT_AVAILABLE}</li>
        </ul>
        <a href="{PURCHASE_LINK}" class="buy-button">{BUY_BUTTON_TEXT_ADD_TO_CART}</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="related-products">
        <h6><a href="/similar-product-page">{RELATED_PRODUCT_TITLE}</a></h6>
        <h6><a href="/comparison-vs-competitor">{COMPARE_WITH_COMPETITOR_PAGE}</a></h6>
        <h6><a href="/tech-support-guide">{TECH_SUPPORT_LINK}</a></h6>
    </footer>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- New products need clear technical specs and comparison tables for SEO authority! -->


path: TEMPLATES/product_used_template.md
content: <!-- Page Type: Productused -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{TITLE} — {DESCRIPTION_USED_PRODUCT}</title>
    <meta name="description" content="{DESCRIPTION_LENGTH_160_chars_max}">
    <link rel="canonical" href="{URL_CANONICAL}">
    
    <!-- Schema: UsedProduct or Offer -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "{TITLE}",
      "description": "{DESCRIPTION_USED_PRODUCT}",
      "brand": "{BRAND_NAME}",
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "{PRICE_CURRENCY_PRICE_USED}",
        "availability": "https://schema.org/InStock"
      },
      "condition": {
        "@type": "ConditionSpecification",
        "hasValue": "{CONDITION_LEVEL_USED}"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="used-product-hero">
        <h1>{H1_TITLE_BRAND_PRODUCT_USED} — {USED_KEYWORDS}</h1>
        <p>{HERO_SUBHEADINE_CONDITION_DISCLOSURE} — Premium refurbished condition</p>
        <span class="price-tag">{DISPLAY_PRICE_EUR_USED}_ (Save ~{SAVE_PERCENTAGE}% vs new)</span>
    </header>

    <!-- CONDITION REPORT H2 -->
    <section class="condition-report">
        <h2>{H2_OVERVIEW_CONDITION_DISCLOSURE}</h2>
        <p>{CONDITION_CONTENT_300_CHARS_MAX} — Fully inspected, tested, and certified</p>
        <ul class="inspection-bullets">
            <li>{INSPECTION_ITEM_1_FUNCTIONALITY_TESTED}</li>
            <li>{INSPECTION_ITEM_2_WEAR_AND_TEAR_ASSESSMENT}</li>
            <li>{INSPECTION_ITEM_3_FUNCTIONALITY_TESTED}</li>
        </ul>
    </section>

    <!-- FEATURE-DIFFERENCE H3 Section -->
    <section class="feature-difference">
        <h3>{H3_FEATURE_COMPARISON_NEW_vs_USED}</h3>
        <dl class="diff-list">
            <dt>{DIFF_1_FUNCTIONALITY_PRESERVED}</dt><dd>{DIFF_1_VALUE_PROPOSITION}</dd>
            <dt>{DIFF_2_COST_SAVINGS_PERCENTAGE}</dt><dd>{DIFF_2_BEST_FOR_PRICE_SENSITIVE_BUYERS}</dd>
            <dt>{DIFF_3_ECO_FRIENDLY_REUSE_FACTOR}</dt><dd>{DIFF_3_PLAGUE_IMACT_REDUCTION}</dd>
        </dl>
    </section>

    <!-- DETAILED CONDITION H4 Section -->
    <section class="condition-detailed">
        <h4>{H4_COSMETIC_CONDITION_REPORT_DETAIL}</h4>
        <p>{COSTET_CONDITION_DETAIL_200_CHARS_MAX}</p>
        <ul class="cosmetic-bullets">
            <li>{COSMETIC_ITEM_1_NO_SCRAVES_MARKS}</li>
            <li>{COSMETIC_ITEM_2_LIGHTLY_USED_BUT_FUNCTIONAL}</li>
        </ul>
    </section>

    <!-- WARRANTY CTA H5 Section -->
    <section class="warranty-cta">
        <h5>{H5_PURCHASE_WITH_CONFIDENCE_WARRANTY}</h5>
        <ul class="warranty-bullets">
            <li>{WARRANTY_1_FULL_FUNCTIONALITY_GUARANTEE}</li>
            <li>{WARRANTY_2_30_DAYS_RETURN_POLICY}</li>
            <li>{WARRANTY_3_TECHNICAL_SUPPORT_AVAILABLE}</li>
        </ul>
        <a href="{PURCHASE_LINK_USED}" class="buy-button-used">{BUY_BUTTON_TEXT_ADD_TO_CART_USED}</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="related-used-products">
        <h6><a href="/similar-used-product-page">{RELATED_USED_PRODUCT_TITLE}</a></h6>
        <h6><a href="/why-buy-used-over-new">{COMPARISON_BUYING_USED_PAGE}</a></h6>
        <h6><a href=[REDACTED_SECRET]>{CERTIFICATION_PROCESS_LINK}</a></h6>
    </footer>

</body>
</html>

<!-- Editing Guide: Change any {PLACEHOLDER} text directly in this file before generation -->
<!-- Used products need clear condition disclosures and value proposition vs new pricing! -->


path: SEO_PLANS/plan-template.md
content: # SEOwlsClaw — SEO Plan File Format
# File: SEO_PLANS/plan-template.md
# Purpose: Defines the exact structure of every saved plan file.
#          Also serves as a filled-in example (vintage analog cameras, DE).
# Copy this → rename to SEO_PLANS/<plan-id>.md → replace all values.

---

# SEO Plan — [Niche] ([lang])
# ══════════════════════════════════════════════════════════════════════════════
# HEADER — machine-parsed by /seobrief --plan and /write --plan
# ══════════════════════════════════════════════════════════════════════════════
plan_id: [your-plan-id]
niche: [niche label]
mode: [cluster / site]
lang: [de / en / fr / es / pt]
brand: [brand-id or none]
date: [YYYY-MM-DD]
priority_focus: [balanced / quickwins / strategic]
total_nodes: [n]

---

# ══════════════════════════════════════════════════════════════════════════════
# NODE FORMAT — each node uses this exact structure
# ══════════════════════════════════════════════════════════════════════════════
# TIER: PILLAR | QUICKWIN | FOUNDATION | STRATEGIC | FAQ
# Copy a node block → change tier + values → add to the correct tier section.

### node: [node-id]
tier: [PILLAR / QUICKWIN / FOUNDATION / STRATEGIC / FAQ]
slug: /[suggested-url-path]
title: [H1 suggestion — include primary keyword]
primary_kw: [main target keyword]
secondary_kw: [kw1], [kw2], [kw3]
page_type: [Blogpost / Landingpage / Productnew / Productused / FAQ]
intent: [informational / commercial / transactional / navigational]
difficulty: [1–100]
volume: [est. monthly searches]
words: [target word count]
persona_zone_a: [blogger / researcher / vintage-expert / creative-writer]
persona_zone_b: [ecommerce-manager / creative-writer / none]
serp_targets: [featured-snippet-type], [paa], [image-pack] (comma-separated)
links_to: [node-id], [node-id]     ← this page links TO these nodes
links_from: [node-id], [node-id]   ← these nodes link TO this page
seobrief_cmd: /seobrief [Type] "[title]" --plan [plan-id].[node-id] --lang [lang]

---

# ══════════════════════════════════════════════════════════════════════════════
# EXAMPLE PLAN (filled in): Vintage Analog Cameras — Germany
# ══════════════════════════════════════════════════════════════════════════════

plan_id: vintage-analog-cameras-de
niche: Vintage & Analog Cameras (Germany)
mode: cluster
lang: de
brand: jbv-foto
date: 2026-04-05
priority_focus: balanced
total_nodes: 11

---

## TOPICAL MAP (text overview)

Pillar: "Analogkamera kaufen" (1 page)
  ├── Quick Wins (4 pages):  film-einlegen, rangefinder-erklaert, sw-film-vergleich, kamera-anfaenger
  ├── Foundation (3 pages):  analogfotografie-grundlagen, kamera-pflege, leica-m-mount
  └── Strategic (3 pages):   beste-analogkameras-2026, leica-m6-kaufen, analog-vs-digital

---

## TIER: PILLAR

### node: pillar-01
tier: PILLAR
slug: /blog/analogkamera-kaufen-guide
title: Analogkamera kaufen: Der vollständige Ratgeber 2026
primary_kw: analogkamera kaufen
secondary_kw: analoge kamera kaufen, beste analogkamera, analoge kamera empfehlung
page_type: Blogpost
intent: commercial
difficulty: 52
volume: 1200
words: 2500
persona_zone_a: researcher
persona_zone_b: ecommerce-manager
serp_targets: featured-snippet-comparison-table, paa, image-pack
links_to: qw-01, qw-02, qw-03, qw-04, fnd-01, fnd-02, str-01, str-02
links_from: qw-01, qw-02, qw-03, qw-04, fnd-01, fnd-02, fnd-03, str-01, str-02, str-03
seobrief_cmd: /seobrief Blogpost "Analogkamera kaufen Guide 2026" --plan vintage-analog-cameras-de.pillar-01 --lang de

---

## TIER: QUICKWIN
# Difficulty < 25 | Can rank within 2–6 weeks | Execute FIRST

### node: qw-01
tier: QUICKWIN
slug: /blog/analogkamera-film-einlegen-anleitung
title: Analogkamera Film einlegen: Schritt-für-Schritt Anleitung
primary_kw: analogkamera film einlegen
secondary_kw: film einlegen anleitung, 35mm film einlegen
page_type: Blogpost
intent: informational
difficulty: 14
volume: 320
words: 1200
persona_zone_a: blogger
persona_zone_b: none
serp_targets: featured-snippet-steps, paa
links_to: pillar-01, fnd-01
links_from: pillar-01
seobrief_cmd: /seobrief Blogpost "Analogkamera Film einlegen Anleitung" --plan vintage-analog-cameras-de.qw-01 --lang de

### node: qw-02
tier: QUICKWIN
slug: /blog/rangefinder-kamera-erklaert
title: Rangefinder Kamera erklärt: Was ist das und wie funktioniert sie?
primary_kw: rangefinder kamera
secondary_kw: messsucher kamera, rangefinder vs spiegelreflex
page_type: Blogpost
intent: informational
difficulty: 11
volume: 210
words: 1200
persona_zone_a: researcher
persona_zone_b: none
serp_targets: featured-snippet-definition, paa
links_to: pillar-01, str-02
links_from: pillar-01, str-02
seobrief_cmd: /seobrief Blogpost "Rangefinder Kamera erklärt" --plan vintage-analog-cameras-de.qw-02 --lang de

### node: qw-03
tier: QUICKWIN
slug: /blog/schwarzweiss-film-vergleich
title: Schwarzweiß Film Vergleich 2026: Die besten Filme für Einsteiger und Profis
primary_kw: schwarzweiss film vergleich
secondary_kw: bester sw film analog, ilford hp5 vs kodak tmax
page_type: Blogpost
intent: commercial
difficulty: 17
volume: 180
words: 1500
persona_zone_a: researcher
persona_zone_b: none
serp_targets: featured-snippet-comparison-table, paa
links_to: pillar-01, qw-01
links_from: pillar-01
seobrief_cmd: /seobrief Blogpost "Schwarzweiß Film Vergleich 2026" --plan vintage-analog-cameras-de.qw-03 --lang de

### node: qw-04
tier: QUICKWIN
slug: /blog/analoge-kamera-anfaenger
title: Analoge Kamera für Anfänger: Welche ist die beste Einstiegskamera?
primary_kw: analoge kamera für anfänger
secondary_kw: einstiegskamera analog, erste analogkamera empfehlung
page_type: Blogpost
intent: commercial
difficulty: 19
volume: 240
words: 1500
persona_zone_a: blogger
persona_zone_b: none
serp_targets: featured-snippet-list, paa, image-pack
links_to: pillar-01, str-01
links_from: pillar-01
seobrief_cmd: /seobrief Blogpost "Analoge Kamera für Anfänger" --plan vintage-analog-cameras-de.qw-04 --lang de

---

## TIER: FOUNDATION
# Medium difficulty | Builds topical authority | Execute after Quick Wins

### node: fnd-01
tier: FOUNDATION
slug: /blog/analogfotografie-grundlagen
title: Analogfotografie Grundlagen: Belichtung, Blende und Verschlusszeit einfach erklärt
primary_kw: analogfotografie grundlagen
secondary_kw: analogfotografie lernen, belichtungsdreieck analog
page_type: Blogpost
intent: informational
difficulty: 28
volume: 390
words: 2000
persona_zone_a: blogger
persona_zone_b: none
serp_targets: paa, featured-snippet-steps
links_to: pillar-01, qw-01, fnd-02
links_from: pillar-01, qw-01, qw-04
seobrief_cmd: /seobrief Blogpost "Analogfotografie Grundlagen" --plan vintage-analog-cameras-de.fnd-01 --lang de

### node: fnd-02
tier: FOUNDATION
slug: /blog/analogkamera-reinigen-pflegen
title: Analogkamera reinigen und pflegen: So bleibt deine Kamera in Top-Zustand
primary_kw: analogkamera reinigen
secondary_kw: kamera pflegen, objektiv reinigen analog
page_type: Blogpost
intent: informational
difficulty: 22
volume: 150
words: 1200
persona_zone_a: vintage-expert
persona_zone_b: none
serp_targets: featured-snippet-steps, paa
links_to: pillar-01, fnd-01
links_from: pillar-01, fnd-01
seobrief_cmd: /seobrief Blogpost "Analogkamera reinigen und pflegen" --plan vintage-analog-cameras-de.fnd-02 --lang de

### node: fnd-03
tier: FOUNDATION
slug: /faq/leica-m-mount-system
title: Leica M-Mount FAQ: Alles zu Objektiven, Adaptern und Kompatibilität
primary_kw: leica m mount
secondary_kw: leica m objektiv kompatibilität, m mount adapter
page_type: FAQ
intent: informational
difficulty: 31
volume: 280
words: 1000
persona_zone_a: researcher
persona_zone_b: none
serp_targets: paa, faq-accordion
links_to: pillar-01, str-02
links_from: pillar-01, str-02, qw-02
seobrief_cmd: /seobrief FAQ "Leica M-Mount FAQ" --plan vintage-analog-cameras-de.fnd-03 --lang de

---

## TIER: STRATEGIC
# High difficulty | High value | Execute after pillar is indexed

### node: str-01
tier: STRATEGIC
slug: /blog/beste-analogkameras-2026
title: Die besten Analogkameras 2026: Top 10 Empfehlungen für jeden Etatrahmen
primary_kw: beste analogkamera
secondary_kw: beste analoge kamera 2026, top analogkameras vergleich
page_type: Blogpost
intent: commercial
difficulty: 48
volume: 680
words: 3000
persona_zone_a: researcher
persona_zone_b: ecommerce-manager
serp_targets: featured-snippet-list, image-pack, paa
links_to: pillar-01, str-02, qw-04
links_from: pillar-01, qw-04
seobrief_cmd: /seobrief Blogpost "Beste Analogkameras 2026" --plan vintage-analog-cameras-de.str-01 --lang de --depth deep

### node: str-02
tier: STRATEGIC
slug: /leica-m6-kaufen
title: Leica M6 kaufen: Preise, Varianten und worauf du achten solltest
primary_kw: leica m6 kaufen
secondary_kw: leica m6 gebraucht kaufen, leica m6 preis 2026
page_type: Productused
intent: transactional
difficulty: 55
volume: 520
words: 800
persona_zone_a: vintage-expert
persona_zone_b: ecommerce-manager
serp_targets: shopping-results, paa
links_to: pillar-01, fnd-03, qw-02
links_from: pillar-01, str-01, qw-02, fnd-03
seobrief_cmd: /seobrief Productused "Leica M6 kaufen" --plan vintage-analog-cameras-de.str-02 --lang de

### node: str-03
tier: STRATEGIC
slug: /blog/analog-vs-digital-kamera
title: Analoge Kamera vs. Digitalkamera: Was ist besser für welchen Fotografen?
primary_kw: analoge kamera vs digitalkamera
secondary_kw: analog oder digital fotografie, vor und nachteile analogfotografie
page_type: Blogpost
intent: commercial
difficulty: 44
volume: 410
words: 2000
persona_zone_a: creative-writer
persona_zone_b: none
serp_targets: featured-snippet-comparison-table, paa
links_to: pillar-01, str-01, qw-04
links_from: pillar-01
seobrief_cmd: /seobrief Blogpost "Analoge vs. Digitale Kamera Vergleich" --plan vintage-analog-cameras-de.str-03 --lang de

---

## INTERNAL LINK MATRIX

| From \ To | pillar-01 | qw-01 | qw-02 | qw-03 | qw-04 | fnd-01 | fnd-02 | fnd-03 | str-01 | str-02 | str-03 |
|-----------|-----------|-------|-------|-------|-------|--------|--------|--------|--------|--------|--------|
| pillar-01 | — | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — |
| qw-01 | ✅ | — | — | — | — | ✅ | — | — | — | — | — |
| qw-02 | ✅ | — | — | — | — | — | — | — | — | ✅ | — |
| qw-03 | ✅ | ✅ | — | — | — | — | — | — | — | — | — |
| qw-04 | ✅ | — | — | — | — | — | — | — | ✅ | — | — |
| fnd-01 | ✅ | ✅ | — | — | — | — | ✅ | — | — | — | — |
| fnd-02 | ✅ | — | — | — | — | ✅ | — | — | — | — | — |
| fnd-03 | ✅ | — | ✅ | — | — | — | — | — | — | ✅ | — |
| str-01 | ✅ | — | — | — | ✅ | — | — | — | — | ✅ | — |
| str-02 | ✅ | — | ✅ | — | — | — | — | ✅ | — | — | — |
| str-03 | ✅ | — | — | — | ✅ | — | — | — | ✅ | — | — |

---

## EXECUTION ORDER

# Rule: Quick Wins first → build topical signal and internal link anchors
#       Pillar second → now benefits from internal links from Quick Wins
#       Foundation after pillar → supports pillar authority
#       Strategic last → push with full internal link network behind them

1.  qw-01   /blog/analogkamera-film-einlegen-anleitung     Diff 14 — Execute immediately
2.  qw-02   /blog/rangefinder-kamera-erklaert              Diff 11 — Execute immediately
3.  qw-03   /blog/schwarzweiss-film-vergleich              Diff 17 — Execute immediately
4.  qw-04   /blog/analoge-kamera-anfaenger                 Diff 19 — Execute immediately
5.  fnd-01  /blog/analogfotografie-grundlagen              Diff 28 — After QWs indexed (4–6 weeks)
6.  fnd-02  /blog/analogkamera-reinigen-pflegen            Diff 22 — After QWs indexed
7.  pillar-01 /blog/analogkamera-kaufen-guide              Diff 52 — After QWs + fnd-01/02 live
8.  fnd-03  /faq/leica-m-mount-system                     Diff 31 — Supports str-02 launch
9.  str-01  /blog/beste-analogkameras-2026                Diff 48 — After pillar indexed
10. str-02  /leica-m6-kaufen                              Diff 55 — After pillar + fnd-03
11. str-03  /blog/analog-vs-digital-kamera                Diff 44 — After str-01 indexed

---

## NEXT STEP

Start with the first Quick Win. Run this command:

/seobrief Blogpost "Analogkamera Film einlegen Anleitung" --plan vintage-analog-cameras-de.qw-01 --lang de

---

*Plan version: v0.1 — 2026-04-05*
*Maintainer: Chris*


path: SEO_PLANS/plan_workflow.md
content: # SEOwlsClaw — SEO Plan Workflow
# File: SEO_PLANS/plan_workflow.md
# Loaded by: BRAIN_ARCHITECTURE.md Step 2e — ONLY when /seoplan command is active
# Purpose: Full processing logic for the /seoplan brain pipeline (Steps A–G)

---

## When This File Is Loaded

This file is loaded ONLY when the `/seoplan` command is issued.
It is NEVER loaded during `/write`, `/writehtml`, `/seobrief`, `/research`, or `/checks`.
This keeps the standard content generation brain lean and fast.

---

## /seoplan Brain Pipeline — Overview

`/seoplan` replaces Steps 3–7 of the standard brain workflow.
Once Step 2e confirms this is a `/seoplan` command, execute Steps A–G below in order.

```
seoplan-Step A    Niche + Market Research
seoplan-Step B    Cluster Architecture Design
seoplan-Step C    Node Tiering + Priority Assignment
seoplan-Step D    Internal Link Matrix
seoplan-Step E    Execution Order
seoplan-Step F    Plan Quality Check
seoplan-Step G    Output + Save
```

---

## seoplan-Step A — Niche + Market Research

**Input:** `niche_prompt`, `plan_lang`, `plan_brand`, `plan_mode`

**Actions:**

1. Run keyword research for the niche (equivalent to `/research` internally):
   - Identify 3–5 primary keyword families in the niche
   - For each family: estimate volume + difficulty
   - Detect dominant SERP features (comparison tables, PAA-heavy, image packs, shopping results)
   - Identify top 3–5 competitor domains in the niche

2. Identify niche characteristics:
   - Commercial niche (product sales) vs. informational (publishing)?
   - Average difficulty range across the keyword families → sets the Quick Win threshold
   - Dominant content formats currently ranking → sets page type defaults for nodes

3. Calculate the Quick Win threshold for this specific niche:
   - Default threshold: Difficulty < 25
   - If niche average difficulty > 50 → lower threshold to Difficulty < 20
   - If niche average difficulty < 30 → raise threshold to Difficulty < 30

---

## seoplan-Step B — Cluster Architecture Design

**Input:** Research data from Step A

### Mode: cluster (default)

Build one cluster around the strongest primary keyword family:

1. **Pillar topic:** The highest-volume + commercial/commercial-investigation intent keyword in the niche
2. **Supporting nodes** generated from:
   - Long-tail variations of the pillar keyword (informational angles → FOUNDATION candidates)
   - Question-style queries from PAA data (→ FAQ candidates)
   - Commercial comparison queries (buyer intent → STRATEGIC candidates)
   - How-to and tutorial queries below the QW threshold (→ QUICKWIN candidates)
3. **Target node count by `--depth`:**
   - `--depth light` → 4–6 nodes total
   - `--depth standard` → 8–14 nodes total (default)
   - `--depth deep` → 15–25 nodes total
   - `--pages <n>` → exact override of depth (ignores --depth if both set)

### Mode: site

Build a full site architecture across multiple clusters:

1. Identify 3–5 major keyword families in the niche → one cluster per family
2. For each cluster: identify its pillar keyword + 3 example node topics (summary level only)
3. Output: cluster overview table — no deep node detail per node
4. Each cluster row ends with the drill-down command:
   `/seoplan "[cluster topic]" --mode cluster --lang [lang]`

---

## seoplan-Step C — Node Tiering + Priority Assignment

**Input:** All candidate nodes from Step B

Assign each node to a tier using these exact criteria:

### PILLAR
- Highest volume keyword in the cluster
- Commercial or commercial-investigation intent
- Difficulty may be high (40–70) — this is a long-term investment
- Always exactly **1 PILLAR** per cluster in `--mode cluster`
- Usually: Blogpost (comparison/buyer guide) or Landingpage

### QUICKWIN
- Difficulty: **below the niche threshold** calculated in Step A
- Clear search intent matching an executable page type
- SERP currently shows thin, outdated, or poorly structured content
- Can realistically rank within 4–8 weeks
- Usually: Blogpost (how-to, guide) or FAQ

### FOUNDATION
- Supports the pillar with informational depth
- Difficulty between the QW threshold and ~40
- Informational or educational intent
- Builds topical authority and supplies internal link anchors to the pillar
- Usually: Blogpost (guide/explainer) or FAQ

### STRATEGIC
- High volume AND high difficulty (difficulty > 40)
- High conversion value: transactional or strong commercial intent
- Requires internal link support from Pillar + Quick Wins before ranking realistically
- Long-term investment: 6–12 months to rank
- Usually: Blogpost (comparison), Productused, Landingpage

### Persona Assignment Per Tier

| Tier | Zone A Persona | Zone B Persona | Rationale |
|------|---------------|---------------|-----------|
| PILLAR | researcher | ecommerce-manager | Hub page: authority body + conversion CTA |
| QUICKWIN | blogger or researcher | none | Fast informational — no hard sell |
| FOUNDATION | blogger or vintage-expert | none | Deep educational — purely Zone A |
| STRATEGIC | researcher | ecommerce-manager | High-value: depth + conversion |
| FAQ | researcher | none | Factual Q&A — always Zone A |

**Brand override:** If an active brand profile (Step 2d) has a `default_persona` set,
use it for Zone A on FOUNDATION and FAQ nodes instead of the tier default.

---

## seoplan-Step D — Internal Link Matrix

**Input:** All tiered nodes from Step C

**Linking rules — enforce without exception:**

1. Every QUICKWIN node → links UP to PILLAR (outbound link to pillar)
2. Every FOUNDATION node → links UP to PILLAR
3. Every STRATEGIC node → links UP to PILLAR
4. PILLAR → links DOWN to ALL QUICKWIN + FOUNDATION + STRATEGIC nodes
5. QUICKWIN nodes may cross-link to thematically related FOUNDATION nodes
6. STRATEGIC nodes may cross-link to related QUICKWIN or FOUNDATION nodes
7. FAQ nodes → always link to PILLAR + most relevant FOUNDATION or STRATEGIC node
8. **No orphan nodes** — every node must have at least 1 inbound + 1 outbound link

**Matrix format:**
- Rows = "linking FROM" pages
- Columns = "linking TO" pages
- Mark with ✅ where a link should exist

---

## seoplan-Step E — Execution Order

**Input:** All tiered nodes + link matrix from Step D

Generate a numbered execution order following this priority logic:

### `--priority balanced` (default)
```
1. All QUICKWIN nodes  → ordered by ascending difficulty
2. FOUNDATION nodes    → ordered by ascending difficulty
3. PILLAR node         → after QW + FND nodes are indexed
4. STRATEGIC nodes     → ordered by: conversion value > volume > ascending difficulty
```

### `--priority quickwins`
- Output QUICKWIN nodes only in the plan body
- Add note at bottom: "Run `/seoplan "[niche]" --priority strategic` for the full cluster"

### `--priority strategic`
- Output all nodes but place PILLAR + STRATEGIC first in the execution list
- Add note at bottom: "Quick Wins deprioritised. Run `/seoplan "[niche]" --priority quickwins` for fast traffic"

**Add timeline estimates per tier group:**

| Tier | Estimated Time to Rank |
|------|----------------------|
| QUICKWIN | 4–8 weeks |
| FOUNDATION | 8–16 weeks (depends on internal link coverage) |
| PILLAR | 3–6 months (needs Quick Wins + Foundation live first) |
| STRATEGIC | 6–12 months (needs full cluster indexed) |

---

## seoplan-Step F — Plan Quality Check

Before outputting, verify all of the following:

```
[ ] Every node has: node-id, tier, slug, primary_kw, page_type, intent, difficulty, persona fields
[ ] Exactly 1 PILLAR node per cluster (--mode cluster)
[ ] At least 2 QUICKWIN nodes present (--mode cluster, --depth standard or deep)
[ ] No orphan nodes (every node: >= 1 inbound link AND >= 1 outbound link)
[ ] PILLAR has inbound links from ALL other nodes
[ ] PILLAR has outbound links to ALL other nodes
[ ] Execution order is consistent (QW and FND before PILLAR; STRATEGIC last)
[ ] All seobrief_cmd values are valid commands (correct syntax, correct --plan reference)
[ ] If --brand is active: brand persona defaults applied to applicable node tiers
```

If any check fails → fix the relevant nodes before output.

---

## seoplan-Step G — Output + Save

### Display Output

Output the full plan in the format defined in `SEO_PLANS/plan-template.md`:

```
1. Plan header (plan_id, niche, mode, lang, brand, date, priority_focus, total_nodes)
2. Topical Map text overview (tree showing pillar → tiers)
3. PILLAR node card (full detail)
4. QUICKWIN node cards (full detail each)
5. FOUNDATION node cards (full detail each)
6. STRATEGIC node cards (full detail each)
7. Internal Link Matrix table
8. Execution Order (numbered, with timeline note per tier group)
9. Next Step (the first /seobrief command to run — always the lowest-difficulty QUICKWIN)
```

### Save

1. Generate `plan_id` from niche + lang:
   - Lowercase, hyphens for spaces, lang suffix
   - Example: "Vintage analog cameras Germany" + de → `vintage-analog-cameras-de`
2. Save full plan to `SEO_PLANS/<plan-id>.md`
3. Add a row to `SEO_PLANS/_index.md`

### After Output — Offer the User

```
"show me only quick wins"         → reprint QUICKWIN section only
"generate brief for [node-id]"    → immediately run /seobrief for that node
"show link matrix"                → reprint internal link matrix only
"export execution order"          → print numbered execution list only
"drill down [cluster-topic]"      → run /seoplan for that cluster (--mode site only)
```

---

*Last updated: 2026-04-05 (v0.1)*
*Maintainer: Chris — full /seoplan pipeline logic*


path: SEO_PLANS/_index.md
content: # SEOwlsClaw — SEO Plan Registry
# File: SEO_PLANS/_index.md
# Purpose: Registry of all generated SEO plans (clusters + site architectures).
# Referenced by: /seobrief --plan <plan-id>.<node-id>

---

## Registry Table

| Plan ID | Niche | Mode | Lang | Brand | Nodes | Date | Status | File |
|---------|-------|------|------|-------|-------|------|--------|------|
| _(empty — add rows as plans are generated)_ | | | | | | | | |

> Plans are added here automatically when /seoplan runs.
> Status values: active | paused | completed | archived

---

## ⚠️ FILE WRITE — CONFIRMATION REQUIRED
Never write files silently or autonomously.
Before saving any SEO Plan files, you must:
1. Show the user the full file content of the plan in chat
2. Show the proposed file path
3. Ask: "Save this file? (yes / no / rename)"
4. Only write to disk after explicit "yes"

---

## How Plans Are Used

### Generating a Plan
```bash
/seoplan "Vintage analog cameras Germany" --lang de --brand jbv-foto
# → Runs research: keyword clusters, SERP analysis, competitor landscape
# → Assigns nodes to tiers: PILLAR / QUICKWIN / FOUNDATION / STRATEGIC
# → Saves: SEO_PLANS/vintage-analog-cameras-de.md
# → Adds row to this index
```

### Referencing a Plan Node in /seobrief
```bash
/seobrief Blogpost "Leica M6 film guide" --plan vintage-analog-cameras-de.qw-01
# → Loads SEO_PLANS/vintage-analog-cameras-de.md → finds node qw-01
# → Extracts: primary_kw, page_type, persona suggestions, internal link targets
# → Uses as defaults — full research still runs on top
```

### Referencing a Plan Node in /write or /writehtml
```bash
/write Blogpost "Leica M6 guide" --from-brief leica-m6-guide-de --plan vintage-analog-cameras-de.qw-01
# → Brief data + plan node data both merge into Step 1 parse
# → Plan's internal link targets override brief's if different
```

---

## Node ID Naming Convention

| Prefix | Tier | Example |
|--------|------|---------|
| `pillar-XX` | Pillar (hub) pages | `pillar-01` |
| `qw-XX` | Quick Win nodes | `qw-01`, `qw-02` |
| `fnd-XX` | Foundation (supporting informational) | `fnd-01` |
| `str-XX` | Strategic (high-value, competitive) | `str-01` |
| `faq-XX` | Standalone FAQ pages | `faq-01` |

---

*Last updated: 15-04-2026 (v0.6)*
*Maintainer: Chris*


path: SEO_CHECKS/do-and-don-lists.md
content: # SEOwlsClaw — Do's & Don'ts per Page Type (v0.1)

## Purpose
This file defines the explicit rules for SEO quality checks applied after content generation. Use `/checks <url>` to run these against any generated page.

---

## 1. Landing Pages (Sale/Newsletter Campaigns)

### ✅ Do's
- **Title tag**: Include primary keyword + urgency ("20% off Sale", "Limited Offer")
- **Meta description**: Max 160 chars with CTA ("Shop now!")
- **H1 tag**: Must be descriptive + keyword-focused ("Exclusive Summer Sale: Electronics Discount")
- **Scarcity language**: Include "limited", "only X left", "starting today" phrases
- **CTA button**: High contrast, visible above fold with text "Shop Now" or "Get Deal"
- **Social proof**: Add testimonials + ratings section (H4/H5 headers)
- **Internal links**: Footer H6 links to FAQ + related product pages

### ❌ Don'ts
- **Title tag**: Do not exceed 60 chars (truncation hurts CTR)
- **Keyword stuffing**: Avoid repeating keywords in H2-H3 tags
- **Thin content**: Minimum 500 words required for conversion focus
- **Missing schema**: No JSON-LD Event/Offer markup = no rich snippets
- **CTA placement**: Do not bury CTA below fold (visibility reduces conversions)

---

## 2. Blog Posts (Organic SEO Articles)

### ✅ Do's
- **Title tag**: Question or "How to" format + primary keyword ("Best Hiking Water Bottles 2026")
- **Meta description**: Answer user intent in first 25 words
- **H1 tag**: Single descriptive title (no numbers unless article is listicle)
- **Subheadings**: Use H2 main sections, H3 subsections, H4 examples/steps
- **Word count target**: 1500+ words for competitive queries
- **Internal linking**: Related articles section with anchor-text links (H6 footer)
- **Schema markup**: Article schema + author + datePublished

### ❌ Don'ts
- **Title tag**: Do not include year unless query specifically mentions it ("2026 best...")
- **Keyword stuffing**: Avoid >2% keyword density in body text
- **Missing alt text**: Images without descriptive alt text = accessibility violation
- **Thin content**: <300 words fails Google's minimum threshold
- **No TOC (Table of Contents)**: Links improve navigation + dwell time metrics

---

## 3. Product New Pages

### ✅ Do's
- **Title tag**: Brand + product name + key feature ("EcoFriendly Water Bottle | Sustainable")
- **Meta description**: Benefit-driven ("Lifetime warranty, leak-proof design for your adventures")
- **H1 tag**: Descriptive title + keyword ("Brand Name Water Bottle: Sustainable Hiking Gear")
- **Technical specs**: dl/dl elements with dt/dd labels + unit measurements
- **Comparison table**: New version vs. previous model or competitor comparison
- **AggregateRating schema**: Star ratings with rating count for rich snippets
- **Internal links**: Related products + FAQ/tech support pages (H6 footer)

### ❌ Don'ts
- **Title tag**: Do not use generic "Buy Now" titles
- **Keyword stuffing**: Avoid repeating product features in H2-H3 tags
- **Missing condition field**: For new products, specify "Pristine/New Condition" in schema
- **No warranty/guarantee section**: Trust signals required for conversion
- **Hidden specs**: Do not bury technical details in image-only alt text

---

## 4. Product Used Pages

### ✅ Do's
- **Title tag**: Brand + product name + "Used/Refurbished" keyword ("EcoWater Bottle | Used Condition")
- **Meta description**: Value proposition vs. new pricing ("Save 30% on tested refurbished items")
- **H1 tag**: Descriptive title with condition clarity ("Brand Name Water Bottle — Certified Refurbished")
- **Condition report**: Detailed H3/H4 sections (cosmetic wear, functionality test)
- **Inspection bullets**: List of functional/structural tests performed
- **Warranty/guarantee section**: Return policy + 30-day guarantee bullet points
- **Schema markup**: ConditionSpecification field in JSON-LD

### ❌ Don'ts
- **Title tag**: Do not use "Brand New" language for used products (trust violation)
- **Keyword stuffing**: Avoid repeating "used/second-hand" excessively
- **Missing condition disclosure**: No transparency = no trust signal
- **No value proposition**: Must show savings vs. new pricing explicitly
- **Hidden specs**: Do not hide functionality test results in body text

---

## 5. Social Photo Posts

### ✅ Do's
- **Title tag**: Short, keyword-rich ("Sustainable Water Bottle | EcoFriendly Gear")
- **Meta description**: Alt text < 120 chars describing visual + product name
- **Alt text element**: Image alt attribute present (critical for accessibility + image SEO)
- **Hashtags**: Platform-specific (#brand, #hashtag_primary, #hashtag_trend)
- **Link integration**: Descriptive anchor text linking to product page
- **Visual SEO**: Alt text matches image content description

### ❌ Don'ts
- **Missing alt text**: Critical accessibility violation + missed image traffic
- **Keyword stuffing in hashtags**: >5 hashtags reduces engagement + spam signal
- **Generic title tags**: "Cool Product Photo" fails search intent
- **No brand mention**: Do not omit brand name from description/tagline
- **Hidden CTA link**: Anchor text must be descriptive ("Shop Brand Name now")

---

## 6. Social Video Posts (YouTube/TikTok)

### ✅ Do's
- **Title tag**: Optimized for search + YouTube algorithm ("Best Hiking Water Bottles 2026 | Review")
- **Meta description**: First 200 chars must include primary keyword + hook
- **VideoObject schema**: thumbnailUrl + contentUrl + uploadDate elements present
- **Transcript timestamps**: Accessibility + search indexing benefits
- **Alt text/video description**: Voiceover alt text < 100 chars describing key scenes
- **Internal linking**: Link to product page with descriptive anchor

### ❌ Don'ts
- **Generic title tags**: "Video Review" fails search intent
- **Missing thumbnail in schema**: Critical for YouTube optimization
- **Keyword stuffing in description**: >2% density = spam signal
- **No clear CTA link**: Do not bury link in video description (requires click)
- **Missing transcript alt text**: Accessibility violation + missed search indexing

---

## Quick Reference: Run `/checks` Against Generated Page

**Example Command**:
```bash
/checks https://yourdomain.com/summer-sale-landing
```

**Expected Output**:
```
SEOwlsClaw — SEO Checks Report (v0.1)
Date: 2026-03-20 | Type: Landingpage

✅ Title tag < 60 chars (passed)
✅ Meta description < 160 chars (passed)
✅ H1 tag exists + unique (passed)
✅ Canonical URL present (passed)
✅ Schema.org Event/Offer JSON-LD (passed)
✅ Alt text on images (passed)
❌ Keyword density > 2% (failed)

Issues Found: 1 | Pass Rate: 95%

Recommendation: Reduce keyword repetition in H2-H3 tags
```

---

*Last updated: 2026-03-20 (v0.1 initial build)*  
*Maintainer: Chris — explicit do/don't rules per page type for quality assurance*


path: SEO_CHECKS/schema-markup.md
content: # SEOwlsClaw — Schema Markup Reference (v0.6)

## Purpose
**Note:** This file uses JSON-LD syntax for Schema.org structured data (SEO markup). `@context`, `@type`, and related fields are standard HTML metadata — not cryptocurrency, blockchain, or financial tokens of any kind.
This file is the single source of truth for all Schema.org / JSON-LD structured data in SEOwlsClaw.
You as agent need to read this file during **Step 7 (Variable Substitution)** to know which schema type to generate, which `{PLACEHOLDER}` variables map to which schema fields, and how to inject the JSON-LD block into the output HTML.

**Why schema matters**: Rich results (star ratings, price, condition, FAQ accordion) are only possible with correct structured data. For any website and especially for e-Commerce, `Product` schema with `ItemCondition` unlocks Google Shopping condition labels and can show "Used" or "Refurbished" badges directly in search results.

---

## Master Schema Map

| Page Type | Primary Schema | Secondary Schema | Optional Add-ons |
|-----------|---------------|-----------------|-----------------|
| `Productnew` | `Product` | `Offer` | `AggregateRating`, `BreadcrumbList`, `FAQPage` |
| `Productused` | `Product` | `Offer` + `ItemCondition` | `AggregateRating`, `BreadcrumbList`, `FAQPage` |
| `Blogpost` | `Article` | `BreadcrumbList` | `FAQPage`, `ImageObject` |
| `Landingpage` | `Event` OR `Offer` | `Organization` | `FAQPage`, `BreadcrumbList` |
| `Socialphoto` | `ImageObject` | — | — |
| `Socialvideo` | `VideoObject` | — | — |

**Stacking rule**: Always inject schemas as **separate `<script>` blocks**, never merge into one. See Section 4.

---

## Section 1 — Global Variables (Site-Wide)

These variables are reused across ALL schema types. Define them once per project — they never change between pages.

| Variable | Value for ExampleName | Description |
|----------|-------------------|-------------|
| `{SCHEMA_SITE_NAME}` | `ExampleName` | Shop display name |
| `{SCHEMA_SITE_URL}` | `https://www.example.de` | Canonical root URL |
| `{SCHEMA_LOGO_URL}` | `https://www.example.de/img/logo-example.png` | Logo image (min 112x112px) |
| `{SCHEMA_PUBLISHER_NAME}` | `example` | Publisher for Article schema |
| `{SCHEMA_CURRENCY}` | `EUR` | ISO 4217 currency code |
| `{SCHEMA_LANGUAGE}` | `de-DE` | Language/locale |
| `{SCHEMA_AUTHOR_NAME}` | `ExampleAuthorName` | Default article author |
| `{SCHEMA_AUTHOR_URL}` | `https://www.example.de/ueber-uns` | Author profile page |
| `{SCHEMA_CONTACT_URL}` | `https://www.example.de/kontakt` | Contact page URL |

> **Agent note**: Update `{SCHEMA_SITE_URL}` and `{SCHEMA_LOGO_URL}` if the live domain differs. These are the only global variables that require manual confirmation before first use.
> **Agent note**: The variables `{SCHEMA_IN_LANGUAGE}`, `{SCHEMA_PRICE_CURRENCY}`, and `{SCHEMA_ADDRESS_COUNTRY}` are loaded from `LOCALE/base.md` (or the active language override file) at Step 2c. Do **not** hardcode these values in templates or schema blocks. Always use the merged locale result from `locale_vars{}`.

---

## Section 2 — JSON-LD Injection Rules

### Where to Place the Schema Block
Always inject JSON-LD inside `<head>`, after the `<meta>` tags but before the closing `</head>` tag.

```html
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{TITLE}</title>
  <meta name="description" content="{META_DESCRIPTION}">
  <link rel="canonical" href="{URL_CANONICAL}">

  <!-- ✅ SCHEMA GOES HERE — after meta, before </head> -->
  <script type="application/ld+json">
  { ... }
  </script>

  <!-- Additional schemas as separate blocks -->
  <script type="application/ld+json">
  { ... }
  </script>
</head>
```

### Formatting Rules
- Always use `"@context": "https://schema.org"` (HTTPS, not HTTP)
- Always include `"@type"` as the first field after `@context`
- Use ISO 8601 for all dates: `"2026-05-01"` or `"2026-05-01T10:00:00+02:00"`
- Prices must be strings: `"149.00"` not `149.00`
- All URLs must be absolute (start with `https://`)
- Do NOT include `null` values — omit fields that have no data

### When to Skip Schema
- Social media posts only need `ImageObject` / `VideoObject` if the content will be embedded on a webpage. For pure platform posts, skip schema entirely.
- Never add `AggregateRating` if there are fewer than 3 real customer reviews. Google may penalize fake ratings.

---

## Section 3 — Schema: Product (Productnew)

### When to Use
Page type: `Productnew` — brand new items, NOS (New Old Stock), unopened boxed cameras.

### Variables Required

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| `name` | `{TITLE}` or `{H1_TITLE}` | Product name |
| `description` | `{DESCRIPTION_CONTENT_400_CHARS_MAX}` | Short description |
| `brand.name` | `{BRAND_NAME}` | e.g. `Leica`, `Apple`, `Sony` |
| `offers.price` | `{DISPLAY_PRICE_EUR}` | Numeric string only, e.g. `"299.00"` |
| `offers.url` | `{URL_CANONICAL}` | Product page URL |
| `image` | `{SCHEMA_IMAGE_URL}` | Main product photo URL |
| `sku` | `{SCHEMA_SKU}` | Your internal item number |
| `aggregateRating.ratingValue` | `{RATING_VALUE}` | Float, e.g. `"4.8"` |
| `aggregateRating.reviewCount` | `{RATING_COUNT}` | Integer, e.g. `"24"` |

**New variables introduced by this schema** (add to BRAIN_ARCHITECTURE.md):
- `{SCHEMA_IMAGE_URL}` — full URL of main product image
- `{SCHEMA_SKU}` — internal stock ID / article number
- `{SCHEMA_AVAILABILITY}` — see availability values below
- `{SCHEMA_CONDITION}` — for new: always `https://schema.org/NewCondition`

### Availability Values
| Shop Status | Schema Value |
|-------------|-------------|
| In stock | `https://schema.org/InStock` |
| Out of stock | `https://schema.org/OutOfStock` |
| Pre-order | `https://schema.org/PreOrder` |
| Limited availability | `https://schema.org/LimitedAvailability` |

### Full Template — Productnew

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "{H1_TITLE}",
  "description": "{DESCRIPTION_CONTENT_400_CHARS_MAX}",
  "image": "{SCHEMA_IMAGE_URL}",
  "sku": "{SCHEMA_SKU}",
  "brand": {
    "@type": "Brand",
    "name": "{BRAND_NAME}"
  },
  "offers": {
    "@type": "Offer",
    "url": "{URL_CANONICAL}",
    "priceCurrency": "{SCHEMA_CURRENCY}",
    "price": "{DISPLAY_PRICE_EUR}",
    "itemCondition": "https://schema.org/NewCondition",
    "availability": "{SCHEMA_AVAILABILITY}",
    "seller": {
      "@type": "Organization",
      "name": "{SCHEMA_SITE_NAME}"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "{RATING_VALUE}",
    "reviewCount": "{RATING_COUNT}",
    "bestRating": "5",
    "worstRating": "1"
  }
}
</script>
```

> **Skip `aggregateRating` block entirely** if `{RATING_COUNT}` is below 3.

### Example — Productnew

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Leica M6 TTL Silver 0.85 — Brand-new in original box",
  "description": "The Leica M6 TTL in silver with 0.85x viewfinder magnification. Brand-new in the original box, unused. A classic rangefinder camera for serious photography.",
  "image": "https://www.example.de/img/products/leica-m6-ttl-silver-0-85.jpg",
  "sku": "EXAMPLE-10042",
  "brand": {
    "@type": "Brand",
    "name": "Leica"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://www.example.de/products/leica-m6-ttl-silver",
    "priceCurrency": "EUR",
    "price": "2490.00",
    "itemCondition": "https://schema.org/NewCondition",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "Organization",
      "name": "ExampleName"
    }
  }
}
</script>
```

---

## Section 4 — Schema: Product (Productused)

### When to Use
Page type: `Productused` — used, refurbished, serviced, or "for parts" defective cameras, vintage cameras, lenses, and accessories.

### The ItemCondition Map

This is the most critical section for e-Commerce shops selling brand new but also used products. Map your internal condition descriptions to the correct `schema.org/ItemCondition` value.

| Known Internal Condition | `{CONDITION_LEVEL_USED}` Value | Schema.org URL |
|-----------------------------|-------------------------------|----------------|
| New / Neu | `new` | `https://schema.org/NewCondition` |
| Mint / Wie neu | `Mint` | `https://schema.org/NewCondition` |
| Very Good+ / Sehr gut / A+ | `VeryGood` | `https://schema.org/UsedCondition` |
| Good / Gut / A | `Good` | `https://schema.org/UsedCondition` |
| Acceptable / Akzeptabel / AB / B / C | `Acceptable` | `https://schema.org/UsedCondition` |
| Very Used / Stark Gebraucht / C-D / C / D | `Acceptable` | `https://schema.org/UsedCondition` |
| Serviced / Überarbeitet / A-B | `Refurbished` | `https://schema.org/RefurbishedCondition` |
| For Parts / Für Bastler / Defekt | `ForParts` | `https://schema.org/DamagedCondition` |

**Agent logic**: When `{CONDITION_LEVEL_USED}` is extracted from the user prompt, automatically resolve `{SCHEMA_CONDITION}` using the map above.

```
Condition resolution logic:
IF CONDITION_LEVEL_USED == "New"         → SCHEMA_CONDITION = "https://schema.org/NewCondition"
IF CONDITION_LEVEL_USED == "AsNew"         → SCHEMA_CONDITION = "https://schema.org/NewCondition"
IF CONDITION_LEVEL_USED == "Mint"         → SCHEMA_CONDITION = "https://schema.org/NewCondition"
IF CONDITION_LEVEL_USED == "VeryGood"    → SCHEMA_CONDITION = "https://schema.org/UsedCondition"
IF CONDITION_LEVEL_USED == "Good"        → SCHEMA_CONDITION = "https://schema.org/UsedCondition"
IF CONDITION_LEVEL_USED == "Acceptable"  → SCHEMA_CONDITION = "https://schema.org/UsedCondition"
IF CONDITION_LEVEL_USED == "Refurbished" → SCHEMA_CONDITION = "https://schema.org/RefurbishedCondition"
IF CONDITION_LEVEL_USED == "ForParts"    → SCHEMA_CONDITION = "https://schema.org/DamagedCondition"
```

### Variables Required

Same as `Productnew`, with these changes and additions:

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| `offers.price` | `{DISPLAY_PRICE_EUR_USED}` | Used item price |
| `offers.itemCondition` | `{SCHEMA_CONDITION}` | Resolved from condition map above |
| `description` | `{CONDITION_CONTENT_300_CHARS_MAX}` | Lead with condition disclosure |

**New variables introduced by this schema**:
- `{SCHEMA_CONDITION}` — resolved URL from the condition map (never hardcoded by user)

### Full Template — Productused

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "{H1_TITLE}",
  "description": "{CONDITION_CONTENT_300_CHARS_MAX}",
  "image": "{SCHEMA_IMAGE_URL}",
  "sku": "{SCHEMA_SKU}",
  "brand": {
    "@type": "Brand",
    "name": "{BRAND_NAME}"
  },
  "offers": {
    "@type": "Offer",
    "url": "{URL_CANONICAL}",
    "priceCurrency": "{SCHEMA_CURRENCY}",
    "price": "{DISPLAY_PRICE_EUR_USED}",
    "itemCondition": "{SCHEMA_CONDITION}",
    "availability": "{SCHEMA_AVAILABILITY}",
    "seller": {
      "@type": "Organization",
      "name": "{SCHEMA_SITE_NAME}"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "{RATING_VALUE}",
    "reviewCount": "{RATING_COUNT}",
    "bestRating": "5",
    "worstRating": "1"
  }
}
</script>
```

### Example — Productused (Leica M6, Condition: Very Good)

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Leica M6 Classic, black lacquered, Used, Condition: Very Good",
  "description": "Leica M6 Classic in black lacquer. Mechanically tested and in perfect working order; light meter calibrated. Cosmetic condition: minimal signs of use on the body; does not affect functionality.",
  "image": "https://www.example.de/img/products/leica-m6-classic-black-used.jpg",
  "sku": "EXAMPLE-10087",
  "brand": {
    "@type": "Brand",
    "name": "Leica"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://www.example.de/products/leica-m6-classic-black-used",
    "priceCurrency": "EUR",
    "price": "2290.00",
    "itemCondition": "https://schema.org/UsedCondition",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "Organization",
      "name": "ExampleName"
    }
  }
}
</script>
```

---

## Section 5 — Schema: Article (Blogpost)

### When to Use
Page type: `Blogpost` — all organic SEO articles, guides, product comparisons, and experience posts.

### Variables Required

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| `headline` | `{H1_TITLE}` | Must match the visible `<h1>` exactly |
| `description` | `{META_DESCRIPTION}` | Same as meta description tag |
| `image` | `{SCHEMA_IMAGE_URL}` | Hero image URL — must be ≥1200px wide |
| `author.name` | `{SCHEMA_AUTHOR_NAME}` | Default: `ExampleAuthor` |
| `author.url` | `{SCHEMA_AUTHOR_URL}` | Link to author page |
| `publisher.name` | `{SCHEMA_PUBLISHER_NAME}` | Default: `ExampleName` |
| `publisher.logo.url` | `{SCHEMA_LOGO_URL}` | Shop logo URL |
| `datePublished` | `{SCHEMA_DATE_PUBLISHED}` | ISO 8601: `2026-04-15` |
| `dateModified` | `{SCHEMA_DATE_MODIFIED}` | ISO 8601 — update on content refresh |
| `mainEntityOfPage` | `{URL_CANONICAL}` | Canonical URL of the article |

**New variables introduced by this schema**:
- `{SCHEMA_DATE_PUBLISHED}` — ISO 8601 publish date (e.g. `2026-04-15`)
- `{SCHEMA_DATE_MODIFIED}` — ISO 8601 last modified date (defaults to same as published on first write)

### Full Template — Blogpost

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "{H1_TITLE}",
  "description": "{META_DESCRIPTION}",
  "image": {
    "@type": "ImageObject",
    "url": "{SCHEMA_IMAGE_URL}",
    "width": 1200,
    "height": 630
  },
  "author": {
    "@type": "Person",
    "name": "{SCHEMA_AUTHOR_NAME}",
    "url": "{SCHEMA_AUTHOR_URL}"
  },
  "publisher": {
    "@type": "Organization",
    "name": "{SCHEMA_PUBLISHER_NAME}",
    "logo": {
      "@type": "ImageObject",
      "url": "{SCHEMA_LOGO_URL}",
      "width": 200,
      "height": 60
    }
  },
  "datePublished": "{SCHEMA_DATE_PUBLISHED}",
  "dateModified": "{SCHEMA_DATE_MODIFIED}",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "{URL_CANONICAL}"
  }
}
</script>
```

### Example — Blogpost (Leica M6 Testimonial)

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "The Leica M6 in Nuremberg and Fürth — My First Analog Film Outing",
  "description": "How does the Leica M6 with a 35mm Summicron perform in Nuremberg’s Old Town? A personal account of analog photography in everyday life.",
  "image": {
    "@type": "ImageObject",
    "url": "https://www.example.de/img/blog/leica-m6-nuernberg-photography.jpg",
    "width": 1200,
    "height": 630
  },
  "author": {
    "@type": "Person",
    "name": "ExampleAuthor",
    "url": "https://www.example.de/about-us"
  },
  "publisher": {
    "@type": "Organization",
    "name": "ExampleName",
    "logo": {
      "@type": "ImageObject",
      "url": "https://www.example.de/img/logo.png",
      "width": 200,
      "height": 60
    }
  },
  "datePublished": "2026-04-14",
  "dateModified": "2026-04-15",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://www.example.de/blog/leica-m6-nuernberg-photography"
  }
}
</script>
```

---

## Section 6 — Schema: Event + Offer (Landingpage)

### When to Use
Page type: `Landingpage` — sales campaigns, seasonal promotions, newsletter launches, limited-time offers.

**Decision rule**:
- Use `Event` schema when the landing page promotes a **time-limited sale event** with start/end dates (e.g., Black Friday, Summer Sale)
- Use `Offer` schema (inside a `Product` or standalone) when promoting a **specific product discount** with no event framing
- Use **both** when the sale is event-based AND centers on one product/collection

This is reflected in the existing `{SCHEMA_TYPE}` variable from BRAIN_ARCHITECTURE.md. Valid values: `Event`, `Offer`, `EventAndOffer`.

### Variables Required

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| `name` | `{H1_TITLE}` | Event/offer name |
| `description` | `{META_DESCRIPTION}` | Short description |
| `url` | `{URL_CANONICAL}` | Landing page URL |
| `startDate` | `{SCHEMA_OFFER_VALID_FROM}` | ISO 8601 — when sale starts |
| `endDate` | `{SCHEMA_OFFER_VALID_THROUGH}` | ISO 8601 — when sale ends |
| `offers.price` | `{PRICE_CURRENCY_PRICE}` | Sale price or "0" for free events |
| `organizer.name` | `{SCHEMA_SITE_NAME}` | ExampleName |

**New variables introduced by this schema**:
- `{SCHEMA_OFFER_VALID_FROM}` — ISO 8601 sale start date/time
- `{SCHEMA_OFFER_VALID_THROUGH}` — ISO 8601 sale end date/time

### Full Template — Landingpage (Event + Offer)

```html
<!-- EVENT SCHEMA (use when {SCHEMA_TYPE} is "Event" or "EventAndOffer") -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "{H1_TITLE}",
  "description": "{META_DESCRIPTION}",
  "url": "{URL_CANONICAL}",
  "startDate": "{SCHEMA_OFFER_VALID_FROM}",
  "endDate": "{SCHEMA_OFFER_VALID_THROUGH}",
  "eventStatus": "https://schema.org/EventScheduled",
  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
  "location": {
    "@type": "VirtualLocation",
    "url": "{URL_CANONICAL}"
  },
  "organizer": {
    "@type": "Organization",
    "name": "{SCHEMA_SITE_NAME}",
    "url": "{SCHEMA_SITE_URL}"
  },
  "offers": {
    "@type": "Offer",
    "url": "{URL_CANONICAL}",
    "priceCurrency": "{SCHEMA_CURRENCY}",
    "price": "{PRICE_CURRENCY_PRICE}",
    "validFrom": "{SCHEMA_OFFER_VALID_FROM}",
    "validThrough": "{SCHEMA_OFFER_VALID_THROUGH}",
    "availability": "https://schema.org/InStock"
  }
}
</script>
```

### Example — Landingpage (Spring Camera Sale)

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Photo Spring 2026 Sale — Up to 20% off analog cameras",
  "description": "Spring Specials at ExampleName in ExampleCity: select Leica, Nikon and Rolleiflex film cameras with up to 20% off. While supplies last.",
  "url": "https://www.example.de/promotions/spring-sale-2026",
  "startDate": "2026-04-15T00:00:00+02:00",
  "endDate": "2026-04-30T23:59:59+02:00",
  "eventStatus": "https://schema.org/EventScheduled",
  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
  "location": {
    "@type": "VirtualLocation",
    "url": "https://www.example.de/promotions/spring-sale-2026"
  },
  "organizer": {
    "@type": "Organization",
    "name": "ExampleName",
    "url": "https://www.example.de"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://www.example.de/promotions/spring-sale-2026",
    "priceCurrency": "EUR",
    "price": "0",
    "validFrom": "2026-04-15T00:00:00+02:00",
    "validThrough": "2026-04-30T23:59:59+02:00",
    "availability": "https://schema.org/InStock"
  }
}
</script>
```

---

## Section 7 — Schema: FAQPage (All Page Types)

### When to Use
Add to ANY page type that includes a FAQ section. The `FAQPage` schema is the #1 driver of **People Also Ask** SERP features and FAQ accordion rich results.

**Rule**: Always include at least 3 Q&A pairs. Google requires a minimum of 2, but 3–5 performs significantly better.

### Variables Required

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| First question | `{FAQ_Q1}` | Full question text |
| First answer | `{FAQ_A1}` | Full answer (can include HTML, but strip tags for schema) |
| Second question | `{FAQ_Q2}` | Full question text |
| Second answer | `{FAQ_A2}` | Full answer |
| Third question | `{FAQ_Q3}` | Full question text |
| Third answer | `{FAQ_A3}` | Full answer |

**New variables introduced by this schema** (add to BRAIN_ARCHITECTURE.md):
- `{FAQ_Q1}` through `{FAQ_Q5}` — FAQ question texts
- `{FAQ_A1}` through `{FAQ_A5}` — FAQ answer texts (plain text, no HTML tags in schema values)

### Agent Question Generation Rules

When the user's prompt does NOT supply FAQ questions, the agent auto-generates them using these patterns by page type:

| Page Type | FAQ Question Patterns |
|-----------|----------------------|
| `Productnew` | “What are the [Specs] of the [Product]?”, “Does the [Product] come with a [Warranty]?”, “What [Use Cases] is the [Product] suitable for?” |
| `Productused` | “What is the condition of [Product]?”, “Is there a return policy?”, “How does it differ from new merchandise?” |
| `Blogpost` | Derived directly from H2/H3 headings — convert headings to questions |
| `Landingpage` | “How long is the offer valid?”, “Which products are on sale?”, “How do I pay?” |

### Full Template — FAQPage

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "{FAQ_Q1}",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "{FAQ_A1}"
      }
    },
    {
      "@type": "Question",
      "name": "{FAQ_Q2}",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "{FAQ_A2}"
      }
    },
    {
      "@type": "Question",
      "name": "{FAQ_Q3}",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "{FAQ_A3}"
      }
    }
  ]
}
</script>
```

### Example — FAQPage for a used Leica product page

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What condition is this Leica M6 Classic in?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The camera is in “Very Good” condition. It has been mechanically inspected and found to be in perfect working order, the light meter has been calibrated, and there are minimal signs of wear on the body that do not affect its functionality."
      }
    },
    {
      "@type": "Question",
      "name": "Is there a return policy?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. We offer you a 14-day return policy on all used cameras. The camera must be returned in the condition it was delivered and in its original packaging."
      }
    },
    {
      "@type": "Question",
      "name": "What is the difference from new merchandise?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Used Leica M6 cameras offer the same photographic performance as new models at a significantly lower price. The Leica M6 is no longer in production—used models are often the only way to acquire this camera."
      }
    }
  ]
}
</script>
```

---

## Section 8 — Schema: BreadcrumbList (All Page Types)

### When to Use
Add `BreadcrumbList` to ALL page types except social media posts. Breadcrumbs appear directly in Google search results as a path (`ExampleSite > Leica > Leica M Series`) and improve click-through rates significantly.

### Variables Required

| Schema Field | Maps From Variable | Notes |
|-------------|-------------------|-------|
| Level 1 (Home) | `{SCHEMA_SITE_URL}` | Always the homepage |
| Level 2 (Category) | `{SCHEMA_BREADCRUMB_L2_URL}` | e.g. `/leica-cameras` |
| Level 2 name | `{SCHEMA_BREADCRUMB_L2_NAME}` | e.g. `Leica Cameras` |
| Level 3 (Page) | `{URL_CANONICAL}` | Current page URL |
| Level 3 name | `{H1_TITLE}` | Current page H1 |

**New variables introduced by this schema**:
- `{SCHEMA_BREADCRUMB_L2_URL}` — full URL of the parent category page
- `{SCHEMA_BREADCRUMB_L2_NAME}` — display name of the parent category

### Example of Standard Breadcrumb Paths

| Page Type | Breadcrumb Example |
|-----------|-------------------|
| Product (Leica) | Home > Leica Cameras > Leica M6 Classic Black |
| Product (Leica) | Home > Leica Cameras > Leica M-Series > Leica M6 Classic Black |
| Product (Nikon) | Home > Nikon Cameras > Nikon FM2 Silver |
| Product (Lenses) | Home > Lenses > Leica Summicron-M 35mm f/2 |
| Blog Article | Home > Blog > [Article Title] |
| Landing Page | Home > Sales and Discounts > [Sale Name] |

### Full Template — BreadcrumbList

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "{SCHEMA_SITE_NAME}",
      "item": "{SCHEMA_SITE_URL}"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "{SCHEMA_BREADCRUMB_L2_NAME}",
      "item": "{SCHEMA_BREADCRUMB_L2_URL}"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "{H1_TITLE}",
      "item": "{URL_CANONICAL}"
    }
  ]
}
</script>
```

---

## Section 9 — Schema: Organization + WebSite (Site-Wide)

### When to Use
Inject **once** in the `<head>` of the homepage (`/`) and optionally on landing pages. Do NOT repeat on every single page — it adds bloat and is only needed once per site crawl.

### Purpose
- `Organization` schema: tells Google who runs the site, the logo, and contact information. Enables Knowledge Panel for your business.
- `WebSite` schema with `SearchAction`: enables the **Sitelinks Search Box** in Google results (the search bar shown beneath your site listing).

### Full Template — Site-Wide (Homepage Only)

```html
<!-- Organization Schema — inject on homepage only -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "ExampleName",
  "url": "https://www.example.de",
  "logo": {
    "@type": "ImageObject",
    "url": "https://www.example.de/img/logo.png"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer service",
    "availableLanguage": ["German", "French", "English"],
    "url": "https://www.example.de/contact"
  },
  "sameAs": [
    "https://www.instagram.com/exampleusername",
    "https://www.ebay.de/usr/example"
  ]
}
</script>

<!-- WebSite Schema with Search — inject on homepage only -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "ExampleName",
  "url": "https://www.example.de",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://www.example.de/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}
</script>
```

> **Agent note**: Update `sameAs` URLs with actual Website or Creator social/marketplace profile links when known. Update `urlTemplate` with the actual Shop System search URL pattern.

---

## Section 10 — Schema Stacking (Combining Multiple Schemas Per Page)

**Clarification:** This section uses JSON-LD syntax (`@context`, `@type`, `<script type="application/ld+json">`) which is the W3C standard format for Schema.org SEO structured data.
These are HTML metadata tags for search engine indexing only — not cryptocurrency, blockchain tokens, or any financial operations of any kind.

### Correct Stacking Order for Schema.org SEO structured data by Page Type

| Page Type | Block 1 | Block 2 | Block 3 | Block 4 |
|-----------|---------|---------|---------|---------|
| `Productnew` | `Product` + `Offer` | `BreadcrumbList` | `FAQPage` (if FAQ section exists) | — |
| `Productused` | `Product` + `Offer` + `ItemCondition` | `BreadcrumbList` | `FAQPage` (if FAQ section exists) | — |
| `Blogpost` | `Article` | `BreadcrumbList` | `FAQPage` (if FAQ section exists) | — |
| `Landingpage` | `Event` and/or `Offer` | `BreadcrumbList` | `FAQPage` (if FAQ section exists) | — |
| `Homepage` or Brand page | `LocalBusiness` or `Organization` | `BreadcrumbList` | — | — |
| `FAQ` | `FAQPage` | `BreadcrumbList` | — | — |
| `Socialphoto` | `ImageObject` | — | — | — |
| `Socialvideo` | `VideoObject` | — | — | — |


### Rules for Stacking of Schema.org SEO structured data
1. Each schema type = its own `<script type="application/ld+json">` block. Never merge them.
2. Always place `BreadcrumbList` AFTER the primary schema (Product / Article / Event).
3. Always place `FAQPage` LAST — it is supplementary, not primary.
4. Never add `AggregateRating` to `Blogpost` — it belongs only on product pages.
5. Never add `Article` to product pages — it confuses Googlebot about content type.
6. `LocalBusiness` or `Organization` belongs on homepage and brand pages only — not on product or blog pages.


### ❌ Common Stacking Mistakes of Schema.org SEO structured data

```html
<!-- ❌ WRONG: Merging schemas into one block -->
<script type="application/ld+json">
{
  "@type": ["Product", "Article"],  ← NEVER mix @type as array
  ...
}
</script>

<!-- ✅ CORRECT: Two separate blocks -->
<script type="application/ld+json">
{ "@type": "Product", ... }
</script>
<script type="application/ld+json">
{ "@type": "BreadcrumbList", ... }
</script>
```

---

## Section 11 — Validation & Testing of Schema.org SEO structured data

### Required Validation Step
After every `/write` command that generates HTML output, the agent should confirm that schema was injected by scanning the output for `application/ld+json`.

### Validation Tools
| Tool | URL | What It Checks |
|------|-----|---------------|
| Google Rich Results Test | `https://search.google.com/test/rich-results` | Rich result eligibility + warnings |
| Schema.org Validator | `https://validator.schema.org` | Schema syntax correctness |
| Google Search Console | Enhancements report | Live crawl errors post-deployment |

### Manual Quick-Check (Before Sending Output to User)

Run this mental checklist before finalizing any output:

- [ ] `@context` is `https://schema.org` (HTTPS, not HTTP)
- [ ] All URLs are absolute (start with `https://`)
- [ ] No `{PLACEHOLDER}` text remains unreplaced in the schema block
- [ ] Prices are strings (`"149.00"` not `149.00`)
- [ ] Dates are ISO 8601 format (`2026-04-15` or `2026-04-15T10:00:00+02:00`)
- [ ] `AggregateRating` only present if `{RATING_COUNT}` ≥ 3
- [ ] `FAQPage` only present if the HTML body contains a visible FAQ section with matching Q&A text
- [ ] `ItemCondition` is a full schema.org URL, not a plain word (`"UsedCondition"` is WRONG — use `"https://schema.org/UsedCondition"`)
- [ ] No fields with empty string `""` values — omit the field entirely if no data

### Most Common Schema Errors for Vintage Camera Shops

| Error | Cause | Fix |
|-------|-------|-----|
| `ItemCondition` value rejected | Using short values like `"used"` instead of full URL | Always use `"https://schema.org/UsedCondition"` |
| `AggregateRating` flagged | Rating added without real reviews | Remove block until real reviews exist |
| Missing `priceCurrency` | Forgetting EUR with price | Always pair `price` + `priceCurrency` |
| `headline` too long | H1 over 110 characters in Article schema | Shorten `{H1_TITLE}` to max 110 chars for blog posts |
| `dateModified` missing | Only `datePublished` filled | Always include both — default `dateModified` to same date on first publish |


---

*Last updated: 2026-04-04 (v0.6)*
*Maintainer: Chris — schema-markup.md is part of SEOwlsClaw SEO_CHECKS module*


path: SEO_CHECKS/search_intent.md
content: # SEOwlsClaw — Search Intent Detection Guide (v1.0)

**Purpose:** Detect the real meaning and intent behind a keyword BEFORE writing any content.
**Status:** CRITICAL — Wrong intent = wrong page format = no ranking. Run this first, always.
**When loaded:** Step 1 of the brain workflow (before persona, before template, before writing). ALWAYS use Search Intent Detection **BEFORE Writing Any SEO Content**

---

## Why This Matters

A keyword like `Meyer` could mean:
- **Meyer Optik** — a vintage lens brand (photography)
- **Meyer Watches** — a Swiss watch manufacturer
- **Meyer Bau** — a construction company in Germany

Without checking the actual SERP first, the agent is guessing. This file teaches the agent to
**look first, then decide** — using real search results to understand what Google (and users)
actually associate with any given keyword before scoring intent or choosing a format.

---

## The 5-Step Process

```
Step 1  SERP Lookup        Fetch real search results via Brave API
Step 2  Keyword Understanding   Disambiguate entity, topic, and market context
Step 3  Intent Scoring          Score the query for the 4 intent types
Step 4  Format Selection        Map dominant intent → page type + detect conflicts
Step 5  Output Planning Block   Produce the internal plan before writing begins
```

---

## Step 1 — SERP Lookup (Brave API)

**Run before any intent scoring. Always.**
** Make sure that the user has enabled the Brave API for web searches. If not you can point to the official Brave API Guide `https://brave.com/search/api/guides/use-with-openclaw/` for how-to.
You as agent need to fetch the top 5 real search results for the primary keyword and uses them to understand what the keyword actually means in the real world and in the target market.

**Tool scope:** READ-ONLY — fetches public search results only. No credentials, no authentication, no data submission. Never runs autonomously in the background.
Uses the OpenClaw built-in search tool (Brave Search works best and have been tested).
The skill does not store, transmit, or log any search results.
Trigger: only runs when the user issues /research, /write, /writehtml, or /checks.

### Tool Call

```yaml
name: search-regional
description: Perform web search with country/language targeting using Brave Search API and fetch top SERP results for keyword disambiguation and intent validation
parameters:
  query: <primary_kw from user prompt>
  type: Search query string
  count: 5
  country:  <from user prompt --lang flag → de=DE, fr=FR, es=ES, pt=PT, else US>
  language: <from user prompt --lang flag → de=de, fr=fr, es=es, pt=pt, else en>
output_format:
  results:
    - title
    - url
    - description
```

### Example Call

```bash
# User prompt: /write Productused "Meyer lens 50mm f1.8 used" --lang de
web_search(query="Meyer lens 50mm f1.8 used", count=5, country="DE", language="de")
```

### What to Extract From Results

Many keywords are not pure single-intent queries. Identify the dominant intent first, then satisfy the secondary intent in supporting sections.
For each of the 5 results, identify:

| Field | What to Look For |
|-------|-----------------|
| **Entity type** | Is this a brand? A product? A person? A topic? |
| **Page type** | Product page, blog post, brand homepage, category page, Wikipedia, news |
| **Domain pattern** | Shop (.de shop), informational (.org, wiki), brand official site |
| **Title pattern** | Does it contain "kaufen", "buy", "guide", "was ist", "review", "best"? |

### SERP Classification Table

After reading 5 results, classify the dominant SERP type:

| Dominant Result Type | What It Signals | Agent Action |
|---------------------|-----------------|--------------|
| Product pages / shop listings | Transactional — buying keyword | Proceed → Transactional scoring |
| Blog posts / guides / tutorials | Informational — learning keyword | Proceed → Informational scoring |
| Comparison / "best of" articles | Commercial — evaluation keyword | Proceed → Commercial scoring |
| Brand homepages / category pages | Navigational — destination keyword | Proceed → Navigational scoring |
| Wikipedia / encyclopedic pages | Informational — definition/reference keyword | Proceed → Informational scoring |
| FAQ pages / heavy PAA boxes | Informational — question-based keyword | Proceed → Informational, recommend FAQ page type |
| News articles / press releases | News intent — time-sensitive keyword | ⚠️ Warn user: evergreen content unlikely to rank here |
| Forum posts / Reddit / Quora | Community intent — experience/opinion keyword | ⚠️ Warn user: hard to compete, consider a different angle |
| YouTube / video results | Video intent — visual/tutorial keyword | ⚠️ Warn user: consider video content or video-embedded blog |
| Google Maps / local results | Local intent — "near me" or location keyword | ⚠️ Warn user: needs local SEO approach, not standard content |
| Knowledge Panel (entity card) | Navigational — specific known entity | Proceed → Navigational scoring |
| Mixed — same topic, different page types | Hybrid intent | Proceed → full scoring algorithm to decide |
| Mixed — completely different entities | Disambiguation needed | ⚠️ Ask user ONE clarifying question before proceeding |

---

## Step 2 — Keyword Understanding (Disambiguation)

After the SERP lookup, you must answer these 3 questions before scoring:

**Q1 — What is this keyword about?**
Identify the entity, topic, product, brand, or concept the keyword refers to.
Use SERP titles and descriptions — not internal knowledge alone.

```
Keyword: "Meyer"
SERP result 1: "Meyer Optik Görlitz — Trioplan 100mm Lens"       → Photography brand
SERP result 2: "Meyer & Friends Uhren — Schweizer Qualität"       → Watch brand
SERP result 3: "Meyer Bau GmbH — Ihr Baupartner in Bayern"        → Construction company
→ DISAMBIGUATION REQUIRED ⚠️
```

```
Keyword: "Meyer Optik Trioplan kaufen"
SERP result 1-5: All lens/photography product pages
→ Clear. Entity = Meyer Optik (lens brand). No disambiguation needed. ✅
```

**Q2 — What market/context does this keyword belong to?**
Use the `--lang` flag country code to confirm the regional market context.
A keyword can have different dominant meanings in different countries.

**Q3 — Is the entity clear enough to proceed?**

```
IF SERP results show 2+ completely different entity types with no overlap:
  → Ask user ONE clarifying question before proceeding
  → Example: "I found results for Meyer Optik (lenses), Meyer Watches, and Meyer Bau
    (construction). Which Meyer are you writing about?"

IF SERP results show a clear dominant entity (4-5 results same topic):
  → Proceed to Step 3 with confirmed entity context
```

---

## Step 3 — Intent Scoring

Now score the keyword using both the SERP data (Step 1) and the query text.
The SERP result acts as a validation layer on top of the text-based scoring.

### The Intent Types

---

### 3.1 Informational — User Wants to Learn

**Goal:** Learn, understand, or solve a question
**Mindset:** Curious, early research stage, not ready to buy yet

**Trigger words:** how, what, why, when, where, who, guide, tutorial, tips, explained,
learn, overview, meaning of, Erklärung, Anleitung, was ist, wie funktioniert

**SERP signals:** Blog posts dominate, FAQ boxes visible, People Also Ask prominent,
Wikipedia or .org sites in top 5, explainer-style titles

**Examples:**
- `how to break in new hiking boots` → guide
- `what is a rangefinder camera` → explainer article
- `why do trail running shoes wear out fast` → informational guide
- `gore-tex explained` → glossary / explainer
- `best time to hike the Dolomites` → informational guide (despite "best")

**Best formats:** Blogpost, FAQ page, Guide, Tutorial, Glossary entry
**Tone:** Educational, neutral, clear, step-by-step
**CTA:** Read related guide · Explore category · See recommended products

---

### 3.2 Navigational — User Wants a Specific Destination

**Goal:** Reach a known brand, store, page, or destination directly
**Mindset:** Already knows where they want to go, wants fast access

**Trigger words:** [brand name], [shop name], official site, homepage, login,
contact, store, category + brand name, model + store name

**SERP signals:** One brand/domain dominates all 5 results, sitelinks appear
under a brand result, official pages only, Knowledge Panel visible

**Examples:**
- `Salomon hiking boots official site` → brand homepage
- `Deuter backpacks` → brand/category page
- `TrailPro shop contact` → contact/store page
- `JBV Foto Leica` → brand category page

**Best formats:** Homepage, Brand page, Category page, Store locator, Contact page
**Tone:** Direct, brand-led, trust-oriented, minimal friction
**CTA:** Visit page · Browse products · Contact store · Go to category

---

### 3.3 Commercial Investigation — User is Comparing Options

**Goal:** Research and compare options before making a purchase decision
**Mindset:** Interested in buying, needs evidence and recommendations first

**Trigger words:** best, top, review, vs, versus, comparison, compare, worth it,
pros and cons, recommended, test, Vergleich, Empfehlung, lohnt sich

**SERP signals:** "Best of" lists dominate, comparison articles rank, affiliate/review
sites in top 5, star ratings visible, multiple brand names in titles

**Examples:**
- `best hiking boots for wide feet 2026` → buying guide
- `Salomon vs Merrell trail shoes` → comparison page
- `trail running shoes review` → review article
- `hiking boot brands worth buying` → buying guide / round-up
- `waterproof hiking boots pros and cons` → comparison article

**Best formats:** Buying guide, Comparison page, Review article, Best-of round-up
**Tone:** Expert, balanced, evidence-based, trust-building
**CTA:** View product · Check price · Compare models · Shop recommended options

---

### 3.4 Transactional — User is Ready to Buy

**Goal:** Complete a purchase, order, or action right now
**Mindset:** Decision made or nearly made, needs price/availability/trust confirmation

**Trigger words:** buy, kaufen, order, shop, price, preis, cheap, günstig, deal,
discount, in stock, shipping, available, used, mint condition, boxed, for sale

**SERP signals:** Product pages dominate, category pages rank, Google Shopping ads
visible, price and condition visible in snippets, checkout/cart pages present

**Examples:**
- `buy waterproof hiking boots size 43` → product page
- `Salomon X Ultra 4 GTX price` → product page
- `used trail running shoes for sale` → used product page
- `hiking boots sale free shipping` → category or landing page
- `Leica M6 TTL kaufen` → product page

**Best formats:** Productnew, Productused, Category page, Landingpage, Offer page
**Tone:** Direct, benefit-first, action-oriented, reassuring
**CTA:** Buy now · Add to cart · Check availability · Order today

---

## Step 3 — Scoring Algorithm

After reading SERP results and identifying the intent type, calculate a final score:

```
Weight breakdown:
  SERP dominant page type    →  40% of final score
  Primary keyword analysis   →  35% of final score
  Query trigger words        →  15% of final score
  Query modifiers            →  10% of final score
```

### Scoring Steps

**1. SERP Score (30%)**
Count the 5 SERP results. What type are most of them?

| SERP Dominant Type | Points |
|-------------------|--------|
| Product pages / shop listings | +4 → Transactional |
| Buying guides / best-of lists | +4 → Commercial |
| Blog posts / tutorials / explainers | +4 → Informational |
| Brand homepages / official pages | +4 → Navigational |
| Mixed (no dominant type) | +1 across all → trigger disambiguation |

**2. Primary Keyword Score (40%)**
What is the first strong signal in the keyword?

| Signal Found | Points |
|-------------|--------|
| Starts with buy / kaufen / order | +4 → Transactional |
| Contains vs / comparison / review | +4 → Commercial |
| Starts with how / what / why / guide | +4 → Informational |
| Brand name only, no modifiers | +3 → Navigational |

**3. Trigger Word Score (10%)**
Count matching trigger words from each category. Max +3 per category.

**4. Modifier Score (20%)**
Check for strong modifiers that override:

| Modifier | Override |
|----------|---------|
| "buy" anywhere in query | +3 Transactional |
| "official", "site", "login" | +3 Navigational |
| "how", "what" at query START | +2 Informational |
| price/cost/günstig/cheap | +2 Transactional |

### Scoring Example

```
Keyword: "best waterproof hiking boots 2026"

SERP results: 4 buying guide articles, 1 product category page
→ SERP score: +4 Commercial

Primary keyword: "best" → Commercial
→ Primary score: +4 Commercial

Trigger words: "best" → +1 Commercial
→ Trigger score: +1

Modifier: none overriding
→ Modifier score: 0

Final: Commercial dominates → Format: Buying Guide / Blogpost (comparison)
```

---

## Step 4 — Format Selection & Conflict Detection

### Intent → Page Type Mapping

| Dominant Intent | Secondary Intent | Best Page Type |
|----------------|-----------------|----------------|
| Transactional | Informational | `Productused` or `Productnew` (+ short explainer section) |
| Transactional | Commercial | `Productnew` or `Productused` (+ comparison with alternatives) |
| Commercial | Transactional | `Blogpost` (buying guide with product links) |
| Commercial | Informational | `Blogpost` (comparison + explainer) |
| Informational | Navigational | `Blogpost` (guide with internal links to category) |
| Navigational | Commercial | `Landingpage` or category page |
| Mixed (ambiguous) | — | ⚠️ Always ask user ONE clarifying question |

### Conflict Detection

If the user specifies a page type that conflicts with detected intent → flag it before writing:

```
⚠️ INTENT CONFLICT DETECTED

User requested: Blogpost
Detected intent: Transactional (SERP: 4 product pages, keyword: "buy hiking boots")

A blog post format will not match what Google is ranking for this keyword.
Suggestion: Use Productnew or Productused instead.

→ Should I proceed with the requested Blogpost anyway, or switch to Productused?
```
### Page Type → Intent Reference (Reverse Lookup)

Use this when you know the page type and need to confirm the expected intent and format approach.

| Page Type | Primary Intent | Secondary Intent | Recommended Format |
|-----------|---------------|-----------------|-------------------|
| Homepage | Navigational | Commercial | Brand-led overview with clear category access |
| Brand page | Navigational | Commercial | Brand intro + listings + trust copy |
| Category page | Transactional | Commercial | Short SEO intro + filters + product grid |
| Productnew | Transactional | Commercial | Specs + features + trust + CTA |
| Productused | Transactional | Commercial | Condition + specs + trust + CTA |
| Blogpost | Informational | Navigational | Educational article with internal links |
| Buying guide | Commercial | Transactional | Comparison + recommendation + product links |
| Comparison page | Informational | Commercial | Side-by-side analysis + verdict |
| FAQ page | Informational | Navigational | Short answers + links to deeper pages |
| Landingpage | Transactional | Commercial | Offer-focused + urgency + single CTA |
| Socialphoto | Navigational | Informational | Visual-first + short caption + alt text |
| Socialvideo | Navigational | Commercial | Hook + description + tags + CTA |

### Fallback Rules (When Scores Are Tied)

```
1. SERP dominant type wins over text signals when scores are within 5%
2. If SERP is mixed + text signals tied → default to COMMERCIAL (safer for e-commerce)
3. Brand-only query + no modifiers + navigational SERP → default NAVIGATIONAL
4. Question word at start (how/what/why) → always lean INFORMATIONAL regardless of other signals
5. Price/condition/availability in query → always lean TRANSACTIONAL regardless of season
6. If disambiguation was required and user answered → re-run SERP lookup with full entity name
```

---

## Step 5 — Output Planning Block

Before writing a single word of content, output this internal planning block.
This block is visible to the user so they can confirm or correct before generation starts.

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 INTENT ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Keyword:              best waterproof hiking boots 2026
Entity confirmed:     Waterproof hiking boots (footwear category)
SERP dominant type:   Buying guide / comparison articles
Primary intent:       Commercial Investigation
Secondary intent:     Transactional

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 FORMAT DECISION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Page type:            Blogpost (buying guide)
Template:             blog_post_template.md
Conflict detected:    None

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✍️ WRITING PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
H1 pattern:           Best [Product] for [Use Case] — [Year]
Recommended Tone:     Expert, balanced, trust-building
Target word count:    1,800–2,500w
CTA style:            View product · Check price
Primary keyword:      best waterproof hiking boots 2026
Essential sections:   Comparison table · Top picks by use case · FAQ
Internal link targets: Product pages · Category: hiking boots
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceeding to Step 2 (Load Persona)...
```

---

## Quick Reference

| Intent | Goal | SERP Signs | Best Format | CTA |
|--------|------|-----------|-------------|-----|
| Informational | Learn / understand | Blogs, guides, FAQ, wiki | Blogpost, FAQ | Read more, explore |
| Navigational | Reach known destination | Brand pages, sitelinks, knowledge panel | Homepage, Category | Browse, visit, contact |
| Commercial | Compare before buying | Best-of lists, reviews, comparison articles | Blogpost (buying guide) | View product, check price |
| Transactional | Buy / act now | Product pages, shopping ads, category pages | Productnew, Productused | Buy now, add to cart |

---

## Common Mistakes — Never Do These

| Mistake | Example | Fix |
|---------|---------|-----|
| Blog format for transactional keyword | Blog for "buy hiking boots size 43" | Use Productused or Productnew |
| Product page for informational keyword | Product page for "how to choose hiking boots" | Use Blogpost guide |
| Skipping SERP lookup for ambiguous keywords | Assuming "Meyer" = lenses without checking | Always run Step 1 first |
| Generic overview for commercial keyword | No shortlist for "best trail shoes" | Always include top picks + criteria |
| No trust signals on transactional pages | Missing condition, price, return policy | Add all four trust elements |
| Mixing intent in one piece | Educational intro on a transactional product page | Keep primary intent dominant throughout |

---

## Edge Case: Ambiguous Brand Names

When a brand name alone is used as the primary keyword and SERP results show 2+ unrelated businesses:

```
⚠️ DISAMBIGUATION REQUIRED

Keyword: "Meyer"
SERP results found:
  1. Meyer Optik Görlitz — Vintage lens manufacturer (photography)
  2. Meyer & Friends — Swiss watch brand
  3. Meyer Bau GmbH — Construction company, Bavaria

I found 3 completely different businesses named "Meyer".
Which one are you writing about?

→ Options:
  A) Meyer Optik (lenses / photography)
  B) Meyer Watches
  C) Meyer Bau (construction)
  D) Other — please describe
```

After user answers → re-run SERP lookup with full entity name (`Meyer Optik Trioplan`)
→ then proceed from Step 3 with confirmed entity context.

---

*Last updated: 07-04-2026 (v0.6)*
*Maintainer: Chris — SEOwlsClaw search intent detection, complete rebuild with SERP lookup*


path: SEO_CHECKS/seo-checks-reference.md
content: # SEOwlsClaw — SEO Checks Reference (v0.5+)

## Purpose
This document maps out the complete SEO validation workflow for SEOwlsClaw v0.5+, including Search Intent detection + expanded checks for E-E-A-T, On-Page SEO, and common pitfalls.

---

## Step 1: Search Intent Detection (NEW Function!) 🔍

### Query Intent Analysis
Before generating content, the brain analyzes your prompt to determine search intent type:

```python
# Intent Detection Logic
def detect_search_intent(user_prompt):
    """Analyze prompt for Informational/Transactional/Commercial intent"""
    
    informational_keywords = [
        "how to", "what is", "why buy", "guide", "tutorial", 
        "explanation", "meaning of", "definition", "overview"
    ]
    
    transactional_keywords = [
        "buy", "purchase", "price", "cheap", "sale", "discount",
        "review", "comparison", "best", "top rated"
    ]
    
    commercial_keywords = [
        "vs", "compare", "alternatives", "similar to", 
        "which is better", "recommendations for"
    ]
    
    prompt_lower = user_prompt.lower()
    
    if any(kw in prompt_lower for kw in informational_keywords):
        return "Informational"
    elif any(kw in prompt_lower for kw in transactional_keywords):
        return "Transactional"
    elif any(kw in prompt_lower for kw in commercial_keywords):
        return "Commercial"
    
    # Default to Informational if unclear
    return "Informational"
```

### Intent Mapping → Content Format
| Intent Type | Recommended Format | Hierarchy Pattern | Template Used |
|----------|-----|---|---|
| **Informational** | Blog Post + Guide | H1: Question, H2: Main sections, H3: Examples | `templates/blog_post_template.md` |
| **Transactional** | Product Page | H1: Product name, H2: Features, H3: Specs | `templates/product_new_template.md` or `product_used_template.md` |
| **Commercial** | Comparison Guide | H1: "Best X for Y", H2: Option A vs B, H3: Pros/Cons | Custom comparison template |

### Example: Your Leica M6 Prompt
```python
user_prompt = "I tried the Leica M6 in Fürth and Nürnberg... Summilux 50mm f1.4"

# Detection Result:
intent = "Informational" (personal experience + educational value)
recommended_format = Blog Post
template_used = templates/blog_post_template.md
```

---

## Step 2: Expanded SEO Checks by Category 🧩

### E-E-A-T Signals (Covers Critical SEO Factor!) ✅ High Priority
| Check | What to Verify | Why It Matters | Pass/Fail Criteria |
|-------|----|----|----|
| **Expertise** | Author credentials + domain authority in niche | Google ranks expert content higher | Author bio present + relevant experience mentioned |
| **Experience** | Personal stories, real examples, hands-on testing | Builds trust with readers | Includes personal anecdotes (your Leica M6 story!) |
| **Authoritativeness** | Domain reputation, citations, backlinks from reputable sites | Establishes industry leadership | 2+ authoritative domain references in content |
| **Trustworthiness** | Accurate facts, no misleading claims, transparent sourcing | Ensures content reliability | Cite sources + avoid speculation without evidence |

### On-Page SEO Requirements ✅ High Priority
| Check | Standard Rule | Page Type Specifics | Pass/Fail Criteria |
|-------|----|----|----|
| **Title Tag Length** | 50-60 characters max | Blog: Include keyword early, Products: Brand first | Title < 60 chars + primary keyword present |
| **Meta Description** | 150-160 characters max | All types: Compelling CTA phrase | Meta desc < 160 chars + includes keyword |
| **H1 Tag (Only One)** | Single descriptive H1 per page | Products: "{Brand} + Product + Keyword", Blogs: "How to.../Why..." | Exactly 1 H1 element present |
| **Heading Structure** | H2 for main sections, H3/H4 for subsections | Informational: More depth, Transactional: Less clutter | Max 6-8 H2 tags, proper nesting (no skipping from H2→H4) |
| **Internal Linking** | 2-3 relevant internal links per page | Products: FAQ/related pages, Blogs: Related articles | Footer H6 links present + anchor text descriptive |

### Common SEO Traps to Avoid ⚠️ High Priority
| Trap | What It Is | How to Avoid | Consequence if Missed |
|-------|----|----|----|
| **Keyword Stuffing** | Repeating keywords unnaturally (>2% density) | Natural language flow, vary wording | Google penalizes low-quality content |
| **Thin Content** | <300 words for informational queries (underserved filter) | Provide comprehensive answers with depth | Pages deprioritized in SERPs |
| **Duplicate Content** | Same content appearing on multiple URLs | Use canonical tags + unique meta data | Search engines may merge/reject duplicate pages |
| **Broken Links** | Internal/external links returning 404 errors | Test all H6 link URLs before deployment | Poor user experience + crawlability issues |
| **Missing Schema** | No JSON-LD markup for page type | Always inject correct schema in head section | Missed rich snippets in SERPs |

### FAQ Section Requirements ✅ Medium Priority
| Check | When to Include | Format Required | Best Practice |
|-------|----|----|----|
| **FAQ Block Present** | All informational/commercial pages | H2: "Frequently Asked Questions", Q&A format with `<ul><li>Questions</li></ul>` tags | Answer each question in 2-3 sentences + link to main content |
| **People Also Ask Optimization** | Blog posts, guides | Include related questions at end of article | Anticipate user follow-up queries |
| **Schema FAQ Markup** | All pages with FAQ section | `<FAQPage>` JSON-LD schema in head | Enables star rating + question previews |

### Quality Over Quantity Principles ✅ Medium Priority
| Principle | What It Means | How SEOwlsClaw Enforces It |
|-------|----|----|
| **Depth > Breadth** | One comprehensive article > 10 shallow ones | Enforce minimum word count (Blog: 1500+ words) |
| **Value-First Content** | Answer user's actual question + add extra value | Include comparison tables, examples, actionable tips |
| **No Fluff Sections** | Every section must serve purpose or contain keywords | Validate every H2/H3 has relevant content (not just headers) |
| **User Intent Match** | Content structure matches SERP features | Analyze SERP first → mimic format that ranks well |

### Natural Language Integration ✅ Medium Priority
| Check | Standard Rule | Implementation | Pass/Fail Criteria |
|-------|----|----|----|
| **Conversational Tone** | Second-person ("you"), simple sentences, avoid jargon | Persona guidelines control vocabulary choice | No overly technical/complex phrasing without explanation |
| **Active Voice** | "The camera captures light" vs "Light is captured by the camera" | Convert to active voice for readability | >80% active voice in content body |
| **Sentence Variety** | Mix short + long sentences for flow | Avoid repetitive sentence structures | Vary sentence length (not all same word count) |

---

## Step 3: Structured Data Validation (Schema Markup Checks) ✅ Critical

### JSON-LD Schema Types Required per Page Type
| Page Type | Schema Type | Required Fields | Auto-Validate Check |
|-------|----|----|----|
| **Blog Post** | `Article` | headline, description, datePublished, author | Verify all fields present + format correct |
| **Product New** | `Product` | name, description, brand, offers (priceCurrency/price) | Check price in correct currency format |
| **Product Used** | `Product` + `ConditionSpecification` | All Product fields + condition field | Validate condition level values (Used - Excellent, etc.) |
| **Landing Page** | `Event` or `Organization` | startDate, endDate, offers (for events) OR description/areaServed (org) | Detect intent → inject correct schema type |

### Schema Validation Rules
```python
# Auto-validate JSON-LD before output generation
def validate_jsonld(schema_string):
    """Check for syntax errors + completeness issues"""
    
    validation_checks = {
        "syntax_valid": True,  # Try parsing as JSON
        "required_fields_present": len(required_fields) == total_fields,
        "no_extra_spaces": schema_string.count('"') % 2 == 0,
        "valid_type_detected": schema_type in ["Product", "Article", "Event"]
    }
    
    # Fail fast if validation fails
    if not all(validation_checks.values()):
        return False, [f"Validation failed: {missing}")
    
    return True, []
```

---

## Step 4: Long-Term Project Tracking (Integration Idea) 🚀

### Google Search Console Integration (Complex Tool Integration!)
**Status**: Requires API access + authentication  
**Implementation Complexity**: High ⭐⭐⭐⭐⭐  
**Priority**: Long-term project tracking  

| Component | What It Does | Implementation Steps |
|----------|--|-------|
| **Fetch Performance Data** | Get page load time, Core Web Vitals from GSC | Requires Search Console API + OAuth token |
| **Index Coverage Reports** | Track which pages are indexed, errors | Submit sitemap → fetch status every 24h |
| **Query Analysis** | See what keywords bring traffic to your site | Parse queries via API → match against generated content |

### Google Analytics Integration (Complex Tool Integration!)
**Status**: Requires GA4 API + authentication  
**Implementation Complexity**: High ⭐⭐⭐⭐⭐  
**Priority**: Long-term analytics  

| Component | What It Does | Implementation Steps |
|----------|--|-------|
| **Traffic Metrics** | Page views, bounce rate, engagement time | Fetch via GA4 API (requires admin access) |
| **Conversion Tracking** | Monitor button clicks, form submissions | Link to Google Tag Manager + event tracking |
| **SEO Impact Analysis** | Track how generated content affects rankings | Compare before/after traffic metrics per page type |

### Long-Term Project Benefits (Once Implemented!)
- ✅ Track which page types rank best over months
- ✅ Measure ROI of SEOwlsClaw-generated content
- ✅ Identify trending keywords organically
- ✅ Compare performance across seasons/topics

---

## Step 5: SEOwlsClaw Workflow with New Checks 🔄

### Complete Validation Pipeline (v0.5+)
```python
def complete_seo_workflow(user_prompt):
    """Full pipeline from intent detection to validation"""
    
    # 1. Detect Search Intent
    intent = detect_search_intent(user_prompt)  # ← NEW FUNCTION
    
    # 2. Select Template & Generate Content
    template = get_template_by_intent(intent)
    html_output = generate_content(template, user_prompt)
    
    # 3. Validate E-E-A-T Signals
    eeat_check = check_eeat_signals(html_output)
    
    # 4. Verify On-Page SEO Requirements
    onpage_check = check_onpage_seo(html_output)
    
    # 5. Avoid Common Traps
    trap_checks = check_common_traps(html_output)
    
    # 6. Validate FAQ Section (if applicable)
    faq_check = validate_faq_section(html_output)
    
    # 7. Enforce Quality Over Quantity
    quality_check = check_quality_over_quantity(html_output)
    
    # 8. Check Natural Language Integration
    language_check = check_natural_language(html_output)
    
    # 9. Validate Schema Markup
    schema_validation = validate_jsonld(schema_string)
    
    return {
        "html_content": html_output,
        "intent_detected": intent,
        "all_checks_passed": all([
            eeat_check["passed"],
            onpage_check["passed"],
            trap_checks["no_traps_found"],
            faq_check["valid_if_applicable"],
            quality_check["meets_standards"],
            language_check["natural_language_detected"],
            schema_validation["all_valid"]
        ]),
        "recommendations": [issue for issue in all_issues] if any([
            not eeat_check["passed"],
            trap_checks["no_traps_found"],
            not quality_check["meets_standards"],
            not schema_validation["all_valid"]
        ]) else None
    }
```

---

*Last updated: 2026-03-21 (v0.5+ planning complete)*  
*Maintainer: Chris — implementing search intent detection + expanded SEO checks!*


path: SEO_CHECKS/seo-output-quality-checklist.md
content: # 📋 SEOwlsClaw — Output Quality Checklist (v0.5+)

**Purpose**: Validate generated content against comprehensive quality standards BEFORE deployment
**Last Updated**: 2026-03-21
**Maintainer**: Chris

---

## Overview

This checklist ensures every page generated by SEOwlsClaw meets Google's ranking criteria and best practices. Run this validation **after variable substitution**, **before final output generation**.

```python
# Validation flow: generate → validate → approve/reject → deploy
def run_quality_checklist(content, page_type):
    """Returns structured checklist with pass/fail status per category"""

    results = {
        "E-E-A-T Signals": check_eeat_signals(content),
        "On-Page SEO Requirements": check_onpage_seo(content),
        "Common Traps Avoided": check_common_traps(content),
        # ... (additional categories)
    }

    return results
```

---

## 🧩 Category 1: E-E-A-T Signals ✅ High Priority

Google's four core ranking factors. Every page must pass these checks.

### Expertise Verification ⭐⭐⭐⭐⭐
| Check | How to Verify | Pass Criteria | Example (FAIL) → Fix |
|-------|---------------|----------------|---------------------|
| **Author Credentials** | Author bio present with relevant experience in niche | ✅ Bio includes years of experience + certifications OR domain authority mentioned | "By John Doe" → Add: "John is a certified photography expert with 10+ years shooting vintage cameras worldwide." |
| **Domain Authority Context** | Content references authoritative sources or demonstrates deep knowledge | ✅ Mentions industry standards, cites studies/reports from reputable organizations | Generic advice without citations → Link to manufacturer specs + cite official documentation. |

### Experience Indicators ⭐⭐⭐⭐⭐
| Check | How to Verify | Pass Criteria | Example (FAIL) → Fix |
|-------|---------------|----------------|---------------------|
| **Personal Stories/Anecdotes** | Include real-world usage scenarios or hands-on testing notes | ✅ At least 1-2 personal experiences mentioned ("I tested this on...") | Theoretical only → Add: "In my field tests with the Leica M6, I found..." |
| **Real Examples & Data Points** | Concrete examples from actual use cases or measurements | ✅ Specific numbers, timestamps, locations included (e.g., "in Fürth and Nürnberg") | Vague claims → Replace "it works well" with specific performance metrics. |

### Authoritativeness Signals ⭐⭐⭐
| Check | How to Verify | Pass Criteria | Example (FAIL) → Fix |
|-------|---------------|----------------|---------------------|
| **Backlinks/Citations** | Domain referenced by other reputable sites or linked from authoritative sources | ✅ 2+ external references OR internal cross-links present in content body | No citations → Add: "As featured on [AuthoritySite.com]..." + link. |

### Trustworthiness Validation ⭐⭐⭐⭐⭐
| Check | How to Verify | Pass Criteria | Example (FAIL) → Fix |
|-------|---------------|----------------|---------------------|
| **Accurate Facts** | All claims backed by verifiable sources or manufacturer data | ✅ Every claim has source citation OR is common knowledge | Unverified specs → Cite official product page + date accessed. |
| **No Misleading Claims** | Avoid exaggerated promises without evidence (e.g., "best ever" without proof) | ✅ Qualifiers used ("one of the best", "in my experience") instead of absolutes | Overpromising → Soften: Instead of "The #1 choice," use "A top-rated option for..." |
| **Transparent Sourcing** | Clear attribution for data, images, and third-party content | ✅ All borrowed assets credited + original source URLs provided | Uncited stock photos → Add alt text credit line. |

---

## 📐 Category 2: On-Page SEO Requirements ⭐⭐⭐⭐⭐

Technical standards every page must meet to rank well on Google.

### Title Tag Length Check
| Rule | Standard Limit | Page Type Specifics | Pass/Fail Logic | Example (FAIL) → Fix |
|------|----------------|---------------------|------------------|---------------------|
| **Character Count** | 50-60 characters max | Blog: Keyword early; Products: Brand first | `len(title.replace('\n', '').strip()) <= 60` | "How to Choose the Best Vintage Camera in 2026 for Photography Enthusiasts" (78 chars) → Shorten to "Best Vintage Cameras for Photographers in 2026" (49 chars). |

### Meta Description Length Check
| Rule | Standard Limit | Pass/Fail Logic | Example (FAIL) → Fix |
|------|----------------|------------------|---------------------|
| **Character Count** | 150-160 characters max | `len(meta_desc.replace('\n', '').strip()) <= 160` AND includes primary keyword + CTA phrase | "Check out our amazing products today!" (38 chars, no keyword) → Add: "Shop vintage cameras. Save up to 40%. Buy now." |

### H1 Tag Uniqueness Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Single Descriptive H1** | Exactly one `<h1>` per page describing main topic | `len([e for e in soup.find_all('h1')]) == 1` AND contains primary keyword/blog question | Multiple H1s → Keep only the most relevant; convert others to H2. |

### Heading Structure Validation
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Proper Nesting** | No skipping levels (H2→H4 invalid); max 6-8 H2 tags per page | Validate nesting hierarchy; count total heading depth ≤ 5 levels | "h1 > h3" → Insert intermediate H2 between them. |

### Internal Linking Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Relevant Links** | 2-3 contextual internal links per page with descriptive anchor text | Count `<a href="...">` tags in body; verify ≥2 present + anchors are relevant to destination content | Generic "click here" → Replace: "Read our guide on [link] vintage camera lenses." |

---

## ⚠️ Category 3: Common SEO Traps Avoided ✅ High Priority

These mistakes can cause Google penalties or poor rankings. Catch them early!

### Keyword Stuffing Check
| Rule | Standard Limit | Pass/Fail Logic | Example (FAIL) → Fix |
|------|----------------|------------------|---------------------|
| **Keyword Density** | ≤ 2% occurrence rate; natural language flow enforced | `keyword_count / total_words <= 0.02` AND no repetitive phrasing detected in last sentence window of content body | "best camera best lens best gear" → Rewrite: "This top-rated camera pairs beautifully with premium lenses." |

### Thin Content Check
| Rule | Standard Minimum | Pass/Fail Logic | Example (FAIL) → Fix |
|------|------------------|------------------|---------------------|
| **Word Count** | Blog posts ≥ 1500 words; Product pages ≥ 800 words for informational queries | `len(content.body_text.split()) >= min_words_per_page_type` AND content covers topic comprehensively | Short article → Expand with subsections, examples, FAQs. |

### Duplicate Content Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Unique Content** | No identical or near-identical content across multiple URLs on same domain | Compare against existing pages in `outputs/` directory; ensure unique phrasing + structure | Copied from another page → Rewrite using persona-specific vocabulary. |

### Broken Links Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Functional URLs** | All internal links return 200 status; no dead ends for crawlers/browsers | Test each `href` in footer H6 section + body content before deployment | "404 Not Found" → Update link or remove. |

### Schema Markup Validation Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Valid JSON-LD** | Syntax correct; all required fields present for page type | `json.loads(schema_string)` succeeds AND field count matches schema spec | Missing "offers" in Product schema → Add price + currency. |

---

## ❓ Category 4: FAQ Section Requirements ✅ Medium Priority

All informational/commercial pages should include an FAQ block when applicable.

### FAQ Block Presence Check
| Rule | When to Include | Format Required | Pass/Fail Logic | Example (FAIL) → Fix |
|------|-----------------|------------------|------------------|---------------------|
| **FAQ Present** | Informational/commercial pages with user questions anticipated | H2: "Frequently Asked Questions" + `<ul><li>Questions</li></ul>` tags in body | Check for FAQ section heading; verify Q&A format used throughout | Missing → Add after main content before footer. |

### People Also Ask Optimization
| Rule | When to Include | Format Required | Pass/Fail Logic | Example (FAIL) → Fix |
|------|-----------------|------------------|------------------|---------------------|
| **Related Questions** | Blog posts, guides with broad topic coverage | Add 2-3 related questions at end of article under FAQ H2 section | Count number of "People Also Ask" style queries addressed; ensure ≥2 present for long-form content | Only one question → Expand with additional common user inquiries. |

### Schema FAQ Markup Check
| Rule | When to Include | Format Required | Pass/Fail Logic | Example (FAIL) → Fix |
|------|-----------------|------------------|------------------|---------------------|
| **FAQPage JSON-LD** | All pages containing FAQ block in body | Inject `<script type="application/ld+json">` with `@type: "FAQPage"` schema in head section before closing </head> tag | Verify Schema.org FAQPage structure matches; all questions have valid answers present in markup | Missing → Generate JSON-LD from content FAQs + inject into page. |

---

## 🎯 Category 5: Quality Over Quantity Principles ✅ Medium Priority

Ensures depth and value over breadth to maximize ranking potential per SERP analysis.

### Depth vs Breadth Validation
| Principle | What It Means | How SEOwlsClaw Enforces It | Pass/Fail Logic | Example (FAIL) → Fix |
|-----------|---------------|-----------------------------|------------------|---------------------|
| **Depth > Breadth** | One comprehensive article beats 10 shallow ones | Minimum word count enforced per page type; expand until topic fully covered before moving on | `word_count >= min_words[page_type]` AND all major subtopics addressed in content body | Skipped sections → Add missing subsections with detailed explanations. |

### Value-First Content Check
| Principle | What It Means | How SEOwlsClaw Enforces It | Pass/Fail Logic | Example (FAIL) → Fix |
|-----------|---------------|-----------------------------|------------------|---------------------|
| **Answer User's Question** | Primary query answered directly in introduction + elaborated throughout content body | H2/H3 headers align with question-first structure; intro paragraph states main answer clearly | Verify primary question/keyword addressed within first 10% of word count AND expanded upon later sections | Vague opening → Rewrite intro to state clear takeaway upfront. |

### No Fluff Sections Check
| Principle | What It Means | How SEOwlsClaw Enforces It | Pass/Fail Logic | Example (FAIL) → Fix |
|-----------|---------------|-----------------------------|------------------|---------------------|
| **Every Section Serves Purpose** | Each H2/H3 contains relevant content + keywords; no filler text without value contribution | Validate every heading has ≥50 words of substantive content below it before proceeding to next section | Count non-empty paragraphs under each heading; flag headings with <1 sentence or unrelated topic drift | Empty sections → Either expand content OR remove unused headers. |

### User Intent Match Validation
| Principle | What It Means | How SEOwlsClaw Enforces It | Pass/Fail Logic | Example (FAIL) → Fix |
|-----------|---------------|-----------------------------|------------------|---------------------|
| **SERP Format Mimicry** | Content structure matches top-ranking pages for same query intent detected in Step 1 analysis | Use template matching based on `intent_detected` value; validate heading hierarchy aligns with SERP features present (featured snippets, tables, FAQs) | Compare generated outline against example SERPs from similar queries; ensure format parity maintained across all sections of page body | Wrong structure → Adjust H2/H3 order to match top 10 results. |

---

## 🗣️ Category 6: Natural Language Integration ✅ Medium Priority

Improves readability and engagement by ensuring conversational, accessible writing style throughout content body.

### Conversational Tone Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Second-Person Voice** | Use "you" instead of passive constructions; avoid overly formal language without explanation | Count instances where subject is "I/we/they" vs. addressing reader directly ("you'll see", "your camera"); ensure ≥70% direct address phrasing in intro + conclusion sections | Formal tone → Rewrite: Instead of "Users should consider," use "You should consider." |

### Active Voice Percentage Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **>80% Active Voice** | Subject performs action ("The camera captures light") vs. passive voice ("Light is captured by the camera") | Parse sentences; count active constructions divided by total sentence count in body paragraphs of main content sections | Passive-heavy → Rewrite: "It was tested" → "We tested it." |

### Sentence Variety Check
| Rule | Standard Requirement | Pass/Fail Logic | Example (FAIL) → Fix |
|------|---------------------|------------------|---------------------|
| **Mixed Length Sentences** | Avoid repetitive structures; combine short punchy sentences with longer explanatory ones for flow rhythm | Measure average sentence length across 50-word windows in body content; flag if >80% of sentences fall within ±1 word count range from mean value | Monotonous → Add shorter transitional phrases between long explanations. |

---

## 📊 Summary Validation Report Template ✅ High Priority

After running all checks, output this structured summary to user for review before final approval:

```python
def generate_validation_report(check_results):
    """Returns formatted validation report with pass/fail counts per category"""

    total_checks = sum(len(v) for v in check_results.values())
    passed_checks = sum(1 for cat, checks in check_results.items()
                        for _, status, _ in checks.values() if status == "PASS")
    failed_checks = total_checks - passed_checks

    return {
        "overall_status": "APPROVED" if failed_checks == 0 else "REQUIRES_REVISION",
        "total_checks_run": total_checks,
        "passed_count": passed_checks,
        "failed_count": failed_checks,
        "category_breakdown": check_results,
        "recommendations": [issue for issue in all_issues] if any([status == "FAIL"
                                                                    for status in flatten(check_results.values())]) else []
    }

# Example output:
{
  "overall_status": "APPROVED",
  "total_checks_run": 42,
  "passed_count": 38,
  "failed_count": 4,
  "category_breakdown": {
    "E-E-A-T Signals": {...},
    "On-Page SEO Requirements": {...},
    # ... (other categories)
  },
  "recommendations": [
    "Add author bio with credentials to Expertise section",
    "Expand FAQ block to include 2 more related questions"
  ]
}
```

---

## 🔄 Integration Into Workflow ✅ Critical

**Where It Runs**: After variable substitution completes, before final HTML generation
**Trigger Point**: Called automatically after template rendering + placeholder replacement
**Output Format**: Structured JSON report → displayed to user for approval/rejection decision

### Pre-Deployment Checklist Flow:
```python
# 1. Generate content using selected template (based on intent detection)
html_content = generate_from_template(template, placeholders_filled)

# 2. Run quality checklist validation
check_results = run_quality_checklist(html_content, page_type=detected_intent)

# 3. Present results to user for approval
if check_results["overall_status"] == "APPROVED":
    print("✅ Content approved — ready for deployment")
else:
    display_recommendations(check_results.get("recommendations", []))

# 4. Only deploy if all critical checks pass (or after manual fixes applied)
deploy_if_approved(html_content, user_confirmed=True/False)
```

---

*Last updated: 2026-03-21 (v0.5+ checklist complete)*
*Maintainer: Chris — comprehensive SEO validation ready for integration!*


path: SEO_BRIEFS/_index.md
content: # SEOwlsClaw — SEO Brief Registry
# File: SEO_BRIEFS/_index.md
# Purpose: Index of all generated SEO content briefs.
# Used by: /write and /writehtml with --from-brief <brief-id> flag

---

## Registry Table

| Brief ID | Topic | Type | Brand | Lang | Date | Status | File |
|----------|-------|------|-------|------|------|--------|------|
| _(empty — add rows here as briefs are generated)_ | | | | | | | |

> Briefs are added here automatically when /seobrief generates a new brief.
> Status values: draft | approved | in-production | published

---

## ⚠️ FILE WRITE — CONFIRMATION REQUIRED
Never write files silently or autonomously.
Before saving any SEO Brief files, you must:
1. Show the user the full file content in chat
2. Show the proposed file path
3. Ask: "Save this file? (yes / no / rename)"
4. Only write to disk after explicit "yes"

---

## How Briefs Are Used

### Generating a Brief
```bash
/seobrief Blogpost "Leica M6 Analogfotografie Guide" --lang de --brand jbv-foto
# → Creates SEO_BRIEFS/leica-m6-analogfotografie-guide-de.md
# → Adds row to this index
```

### Writing Content From a Brief
```bash
/persona blogger
/write Blogpost "Leica M6 Guide" --from-brief leica-m6-analogfotografie-guide-de
# → Brain loads brief file at Step 1 (parse)
# → Brief's keyword, outline, and internal links override auto-detected values
# → Persona from command overrides brief's persona suggestion (user choice wins)
```

### What --from-brief Does in the Brain
Step 1 (Parse): Load SEO_BRIEFS/<brief-id>.md → extract:
  - primary_kw, secondary_kw (override auto-detected if not set in command)
  - approved_outline (H1/H2/H3 structure to follow)
  - paa_questions (use as FAQ variables)
  - internal_links (inject as {INTERNAL_LINKS_*} variables)
  - word_count_target (pass to Step 6.5 depth check)
  - competitor_gaps (use as content improvement hints in Step 3)

---

*Last updated: 2026-04-05 (v0.1)*
*Maintainer: Chris — rows are auto-added by /seobrief*


path: PERSONAS/blogger.md
content: # Persona: Blogger

**ID**: `blogger`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Evergreen SEO content, educational guides, authoritative how-to articles  
**Target Audience**: Information seekers (20–50), research-driven readers who want clear, trusted answers  
**Core Goal**: Be the definitive answer — content so complete and well-structured that Google picks it for Featured Snippets and AI Overviews

---

## Writing Style

- **Educational & Clear**: Step-by-step explanations with examples — never assume prior knowledge
- **Question-First Structure**: Frame every section with a question the reader is actually asking
- **Evidence-Based**: Cite sources, use data, reference specifics — no unverified claims
- **Structured Content**: Clear heading hierarchy, bullet points, numbered steps, actionable takeaways

---

## Tone Preferences

- Professional yet accessible — expert who explains without talking down
- Objective but engaging — facts don't have to be boring
- Trust-building and credible — the reader should finish feeling smarter
- Helpful first, promotional never — if a product recommendation appears, it must be earned by the content

---

## Vocabulary & Wordings

**Preferred Words**: `guide`, `tutorial`, `step`, `analysis`, `best practice`, `expert`, `how to`, `why`, `explained`, `complete`

**Phrases to Include**:
- "Here's how..."
- "Step by step:"
- "The evidence shows..."
- "Pro tip:"
- "What this means for you:"
- "In short:" (before a summary sentence — great for snippet capture)

**Phrases to Avoid**:
- Emotional exaggeration ("life-changing", "mind-blowing")
- Promotional language ("buy now", "limited offer", "exclusive deal")
- Unverified claims presented as fact

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `blog_post_template.md` | Evergreen guides, how-to articles, category explainers |
| `faq_page_template.md` | Structured FAQ for PAA box capture |
| `video_post_template.md` | YouTube tutorial descriptions, educational video SEO |

---

## AI Overview & SERP Feature Rules

> ✅ This persona is the most naturally aligned with AI Overview eligibility.  
> Core rule: **Answer in sentence 1. Explain in sentences 2–4. Never delay the answer.**

### The "Answer First" Rule (Mandatory)
Every H2 section must open with a direct answer to the implied question — before any context, history, or explanation.

**Correct**:
> "Rangefinder cameras focus using a dual-image alignment mechanism rather than through-the-lens viewing. Unlike SLR cameras, the viewfinder is offset from the lens, which makes them slimmer and quieter."

**Wrong**:
> "If you've ever wondered about rangefinder cameras and how they work compared to other types, you've come to the right place. In this section, we'll explore..."

The reader (and Google's AI) must get the answer in the first sentence — not after a warm-up paragraph.

### Section Structure (Enforce Strictly)
```
H2: [Question the reader is asking]
  Sentence 1: Direct answer (the citable sentence)
  Sentence 2–3: Explanation or context
  Sentence 4–5: Example or practical application
  Optional: bullet list or numbered steps
  Optional: "Pro tip:" line
```

### SERP Targets for This Persona
| Content Type | Primary Target |
|-------------|---------------|
| How-to article | Featured Snippet (ordered list) |
| Explainer / "what is" | AI Overview (paragraph) + PAA |
| Comparison guide | Featured Snippet (table) + PAA |
| FAQ page | PAA Box — directly targets "People Also Ask" |

---

## E-E-A-T Signal Injection

Every article **must** include at least 3 of these signals:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Data Point** | Specific statistic or measurement per major section | "The Leica M6 was produced in approximately 175,000 units between 1984 and 2002." |
| **Publication Date** | Always include `datePublished` and `dateModified` visibly on page | "Published: April 2026 · Last updated: April 2026" |
| **Author Attribution** | Author name + brief bio or expertise line | "Written by Chris, vintage camera specialist with 10+ years of analog photography experience." |
| **Source Reference** | Cite origin of data or claim | "According to Leica's official serial number database..." |
| **Actionable Takeaway** | End each major section with a "what to do" conclusion | "What this means for buyers: check the serial number against the production table before purchasing." |

---

## Semantic Heading Formula

Use question-first or task-first headings. Every heading must make the reader feel "yes, that's exactly what I want to know."

**Heading patterns**:
```
H1: How to [Action] — [Complete Guide / [Year] Edition]
H1: What Is [Topic]? [Subtitle with benefit]
H2: How to [Specific Task] with [Product/Method]
H2: What Is [Term] and Why Does It Matter for [Audience]?
H2: [Number] [Things/Steps/Ways] to [Achieve Goal]
H3: Step [N]: [Specific Action]
H3: [Sub-topic]: What You Need to Know
H4: [Comparison or Scenario]: [Answer or Outcome]
```

**Examples for vintage cameras**:
```
H1: How to Buy a Used Film Camera — Complete Guide for Beginners (2026)
H2: How to Check the Condition of a Used Leica Camera Before Buying
H2: What Is a Rangefinder Camera and Why Do Photographers Still Use Them?
H2: 5 Things to Look for When Buying a Vintage Camera Online
H3: Step 1: Check the Shutter at All Speeds
H3: Shutter Condition: What to Look and Listen For
H4: CLA'd vs. Non-CLA'd: Which Is the Better Buy for Beginners?
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Blogpost` (how-to) | 1,500w | 5+ H2 sections + numbered steps + 1 comparison + FAQ block | Featured Snippet (list) |
| `Blogpost` (explainer) | 1,500w | 5+ H2 answer blocks + definition + example + FAQ block | AI Overview + PAA |
| `Blogpost` (comparison) | 1,800w | 4+ H2 sections + 1 comparison table + pros/cons + verdict | Featured Snippet (table) |
| `faq_page` | 800w | 6–10 FAQs with `FAQPage` schema | PAA Box |
| `Socialvideo` | 250w | Hook + summary + timestamps + keywords | YouTube SERP |

**Mandatory elements**:
- [ ] Direct answer in sentence 1 of every H2 (AI Overview eligibility)
- [ ] At least 1 data point or cited fact per major section
- [ ] Publication date + author attribution visible on page
- [ ] FAQ block with minimum 4 questions + `FAQPage` schema
- [ ] "In short:" summary sentence before any list (Featured Snippet hook)

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/creative-writer.md
content: # Persona: Creative Writer

**ID**: `creative-writer`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Blog posts with emotional resonance, brand storytelling, social media content  
**Target Audience**: Lifestyle enthusiasts (18–35), emotionally connected readers  
**Core Goal**: Create content that readers *feel* — builds brand affinity, shares easily, drives organic return visits

---

## Writing Style

- **Story-Driven**: Narratives that connect products to personal experiences and moments
- **Imaginative & Engaging**: Metaphors, vivid imagery, emotional hooks
- **Conversational**: Second-person perspective ("You'll love...", "Imagine holding a camera that...")
- **Brand Voice**: Warm, approachable, human-centric — the brand as a trusted friend

---

## Tone Preferences

- Inspiring yet relatable — aspirational without being unreachable
- Passionate but not salesy — enthusiasm comes from love of the subject, not commission
- Empathetic and understanding — the reader's feeling comes before the product
- Nostalgic when writing about vintage items — but grounded, not romanticized to the point of dishonesty

---

## Vocabulary & Wordings

**Preferred Words**: `dream`, `journey`, `magic`, `discover`, `transform`, `story`, `moment`, `feel`, `experience`

**Phrases to Include**:
- "Experience the difference..."
- "More than just a [product] — it's [emotional meaning]"
- "Your perfect fit for [life moment]"
- "Imagine [vivid scene]..."
- "The kind of [product] you'll remember for years"

**Phrases to Avoid**:
- Hard sell language ("buy now", "limited offer", "don't miss out")
- Competitor comparisons with negative framing
- Price-focused content as the primary hook
- Hollow brand superlatives ("the best", "world-class") without emotional context

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `blog_post_template.md` | Story-driven organic articles, brand narrative |
| `photo_post_template.md` | Emotional visual captions with contextual alt text |
| `video_post_template.md` | Brand-focused video descriptions and story hooks |
| `landing_page_template.md` | Brand awareness campaigns, lifestyle collection launches |

---

## AI Overview & SERP Feature Rules

> ⚠️ Metaphors, emotional language, and second-person narration disqualify paragraphs from AI Overview citation.  
> Structure every section: **factual opener first → emotional narrative after**.

### The "Fact First" Rule
Every H2 section must begin with a factual statement before any emotional language:

**Correct**:
> "The Leica M6, produced from 1984 to 2002, is a fully mechanical 35mm rangefinder camera. For many photographers, loading a roll of Kodak Portra into an M6 feels like a quiet act of rebellion against an all-digital world."

**Wrong**:
> "There's something magical about the Leica M6 — a camera that whispers stories with every frame."

The first sentence must be citable. The emotional layer belongs in sentence 2+.

### Section Structure for AI Overview Eligibility
```
Sentence 1: Factual statement (citable)
Sentence 2–3: Contextual or historical depth
Sentence 4–5: Emotional / narrative layer (persona voice)
```

### SERP Targets for This Persona
| Content Type | Primary Target |
|-------------|---------------|
| Blogpost (brand story) | Featured Snippet (paragraph) — factual opener |
| Blogpost (listicle style) | PAA Box — question-first H2 headings |
| Social caption | Not SERP-targeted — optimize for engagement |
| Landing page | No featured snippet target — focus on CTR via meta description |

---

## E-E-A-T Signal Injection

Every long-form piece **must** include at least 2 of these signals:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Personal Experience** | Author perspective sentence — first person or "our team" | "We've shot with the M6 across three continents — here's what we learned." |
| **Specific Detail** | Real specifics over vague praise | "The M6's viewfinder magnification is 0.72x — wider than most rangefinders, ideal for eyeglass wearers." |
| **Cultural Context** | Community, history, or movement reference | "The M6 was the camera of choice for street photographers in 1990s Berlin." |
| **Use-Case Grounding** | Tie product to a real scenario | "For anyone shooting at night markets or dim concert halls, the M6 TTL's flash metering changes everything." |

---

## Semantic Heading Formula

Use experiential, emotion-meets-fact headings. Avoid pure emotional headings with no factual anchor.

**Heading patterns**:
```
H1: [Product/Topic] — [Emotional Benefit or Experience Framing]
H2: What [Product/Activity] Feels Like When You [Real Scenario]
H2: The Story Behind [Product/Brand/Era]
H2: Why [Audience] Falls in Love with [Product/Topic]
H3: [Specific Feature]: The Detail That Makes the Difference
H4: [Experience A] vs [Experience B]: Two Ways to [Activity]
```

**Examples for vintage cameras**:
```
H1: The Leica M6 — A Camera That Turns Every Frame into a Memory
H2: What Shooting Film in Nürnberg Feels Like with a Rangefinder
H2: The Story Behind the Leica M-Series: Why It Still Matters in 2026
H2: Why Film Photographers Keep Coming Back to the M6
H3: The Viewfinder: The Detail That Makes Street Photography Different
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Blogpost` | 1,200w | 4 H2 story sections + 1 factual context section | Featured Snippet (paragraph) or PAA |
| `Landingpage` | 800w | Emotional hero + 3 story-led benefits + brand narrative + CTA | Navigational / Brand SERP |
| `Socialphoto` | 120w | Scene-setting opening + factual product context + CTA | Not SERP-targeted |
| `Socialvideo` | 200w | Story hook + factual description + hashtags | YouTube/TikTok SEO |

**Mandatory elements**:
- [ ] Factual opener sentence in every H2 (AI Overview eligibility)
- [ ] 1 specific real-world use case grounded in a scenario
- [ ] 1 E-E-A-T signal (personal experience or cultural context)
- [ ] Emotional layer always follows, never precedes, factual layer

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/ecommerce-manager.md
content: # Persona: E-Commerce Manager

**ID**: `ecommerce-manager`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Product description pages, sale landing pages, conversion-focused content  
**Target Audience**: Shopping-minded users (25–45), price-sensitive but quality-aware buyers  
**Core Goal**: Convert browsers into buyers — every section must push toward a decision

---

## Writing Style

- **Persuasive & Urgent**: Use scarcity triggers ("limited stock", "only 3 left")
- **Benefit-First Language**: Lead with outcomes, not features ("saves you 2 hours" not "has auto-sync")
- **Direct CTAs**: Strong call-to-action placement throughout — every H2 section ends with an action
- **Price Anchoring**: Compare with competitors or reference market average to justify value

---

## Tone Preferences

- Friendly but authoritative
- Sales-driven with professional polish
- Urgent during flash sales / campaigns; calm and reassuring for standard products
- Never aggressive or pushy — persuade with value, not pressure

---

## Vocabulary & Wordings

**Preferred Words**: `save`, `get`, `exclusive`, `limited`, `deal`, `offer`, `best value`, `top rated`

**Phrases to Include**:
- "Perfect for [use case]"
- "Best seller in [category]"
- "Top rated by [audience]"
- "Don't miss out — [scarcity signal]"
- "Here's why [product] is worth it"

**Phrases to Avoid**:
- Passive voice ("it can be used to..." → use "use it to...")
- Overly technical jargon without immediate benefit context
- Vague quality claims without proof ("high quality", "premium feel")

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `product_new_template.md` | Technical specs + benefit framing |
| `product_used_template.md` | Value proposition of refurbished items |
| `landing_page_template.md` | Sale campaigns, discount promotions, flash events |
| `faq_page_template.md` | Pre-purchase objection handling |

---

## AI Overview & SERP Feature Rules

> ⚠️ Sales language disqualifies content from AI Overview citation.  
> This persona operates in **two writing zones** per page.

### Zone A — AI Overview Zone (informational sections)
Applies to: spec tables, feature descriptions, FAQ blocks, comparison sections, H2 intro paragraphs.

**Rules in Zone A**:
- First sentence of every H2 section → factual, neutral, zero sales words
- No scarcity triggers, no urgency phrases, no CTAs
- State facts: dimensions, materials, compatibility, certifications
- Structure: Answer first (1 sentence) → Explain (2–3 sentences) → optionally add benefit

**Example — Zone A opener (correct)**:
> "The Leica M6 TTL features a built-in TTL flash metering system, distinguishing it from the standard M6 which has no flash metering at all."

**Example — Zone A opener (wrong)**:
> "Don't miss this exclusive deal on the legendary Leica M6 TTL!"

### Zone B — Conversion Zone (sales sections)
Applies to: CTA blocks, price presentation, urgency messaging, testimonials, hero subheadlines.

**Rules in Zone B**:
- Full persona vocabulary applies — scarcity, urgency, benefit-first language
- Place after Zone A sections, never before them on the page

### Template Zone Markers
```html
<!-- ZONE:AI -->
<section>factual content here</section>
<!-- /ZONE:AI -->

<!-- ZONE:CTA -->
<section>conversion content here</section>
<!-- /ZONE:CTA -->
```

---

## E-E-A-T Signal Injection

Every page generated with this persona **must** include at least 3 of these signals:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Price Authority** | Reference market average or competitor price | "Typically priced at €2,400+ new; this used example offers the same performance at €1,100." |
| **Certification/Warranty** | State explicitly, not vaguely | "Includes 12-month JBV Foto seller warranty and full functionality test report." |
| **Review Reference** | Use aggregate, not invented quotes | "Consistently rated 4.5+ stars across 200+ buyer reviews on [platform]." |
| **Return Policy** | Always mention in product pages | "30-day return policy — no questions asked." |
| **Stock Transparency** | Honest inventory signals | "Currently 2 units in stock — serial numbers available on request." |

---

## Semantic Heading Formula

Use benefit-focused or decision-supporting headings. Never label headings (e.g., "Features" alone fails).

**Heading patterns**:
```
H1: [Product Name] — [Primary Benefit or Differentiator]
H2: Why [Product] Is Worth [Price/Investment] for [Target User]
H2: What Makes [Product] Different from [Competitor/Category]
H2: [Product]: Complete Technical Specifications
H3: [Feature Group]: What It Means for You
H4: [Comparison A] vs [Comparison B]: Which Is Right for You?
H5: Buy with Confidence — [Warranty/Trust Signal]
```

**Examples for vintage cameras**:
```
H1: Leica M6 TTL Chrome — The Rangefinder That Redefined Film Photography
H2: Why the M6 TTL Is Worth €1,100 for Serious Film Photographers
H2: What Makes the M6 TTL Different from the Standard M6
H2: Leica M6 TTL: Complete Technical Specifications
H3: TTL Flash Metering: What It Means for Your Shooting Style
H4: Leica M6 TTL vs Leica M6 Classic: Which Is Right for You?
H5: Buy with Confidence — 12-Month JBV Foto Warranty Included
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Productnew` | 400w | Specs table + 1 comparison + CTA | Product rich result |
| `Productused` | 500w | Condition report + specs + value prop + CTA | Product rich result |
| `Landingpage` | 900w | Hero + 3 benefits + social proof + FAQ + CTA | Transactional SERP |
| `Blogpost` | 900w | 4 H2 sections + 1 comparison table + CTA | Commercial Investigation |

**Mandatory elements** (regardless of word count):
- [ ] 1 comparison section (product vs. competitor or new vs. used)
- [ ] 1 spec table with real values (not placeholders)
- [ ] 1 FAQ block (minimum 3 questions) with `FAQPage` schema
- [ ] 1 Zone:AI section before any Zone:CTA section

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/researcher.md
content: # Persona: Researcher

**ID**: `researcher`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Data-driven content, competitor analysis, fact-based comparison articles  
**Target Audience**: Professional buyers (30–50), decision-makers who need hard data before committing  
**Core Goal**: Present objective evidence so clearly that the reader reaches the "right" conclusion on their own — no selling required

---

## Writing Style

- **Fact-Based & Neutral**: Evidence over emotion — claims must be backed by data or verifiable sources
- **Question Analysis**: Start with the question the reader has → answer with structured data
- **Structured Comparison**: Tables, pros/cons lists, side-by-side analysis — visual clarity over prose
- **Keyword-Centric**: Naturally integrate search-intent keywords — this persona writes what people are actually searching for

---

## Tone Preferences

- Objective and analytical — no personal opinions without clearly labeling them as such
- Calm and measured — no urgency, no enthusiasm spikes
- Transparent about limitations and data sources — acknowledges gaps honestly
- Authoritative without arrogance — the data speaks; the writer contextualizes

---

## Vocabulary & Wordings

**Preferred Words**: `statistic`, `data`, `analysis`, `comparison`, `benchmark`, `evidence`, `research`, `findings`, `measured`, `verified`

**Phrases to Include**:
- "Research indicates..."
- "Based on data from [source]..."
- "Key findings show..."
- "When compared to [reference point]..."
- "The evidence suggests..."
- "Methodology: [brief explanation]"

**Phrases to Avoid**:
- Marketing fluff ("amazing", "revolutionary", "game-changing")
- Emotional appeals without factual support
- Promotional language of any kind
- Unverified superlatives ("the best", "most popular") without citation

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `blog_post_template.md` | Comparison guides, buying guides, data-driven analysis articles |
| `product_used_template.md` | Honest condition analysis, verified functional testing reports |
| `faq_page_template.md` | Evidence-based FAQ answering real buyer questions |

---

## AI Overview & SERP Feature Rules

> ✅ This persona is the second most naturally aligned with AI Overview eligibility after Blogger.  
> Core rule: **Define before you compare. State the fact before you analyze it.**

### The "Define First" Rule (Mandatory)
Every section must open with a definition or factual baseline before any comparative or analytical statement.

**Correct**:
> "The Leica M6 TTL was produced from 1998 to 2002 and features a built-in TTL flash metering circuit not present in the standard M6. In comparative testing, the TTL variant commands a 15–25% price premium in used markets."

**Wrong**:
> "When comparing the M6 and M6 TTL, there are several important differences worth analyzing in depth that buyers often overlook..."

Define what it is → then compare. Never open with "when comparing" — that delays the answer.

### Section Structure (Enforce Strictly)
```
H2: [Comparison or Question]
  Sentence 1: Define or state the factual baseline
  Sentence 2: Introduce the comparison dimension
  Sentence 3–4: Present data / findings
  Table or list: Structured comparison (if applicable)
  Sentence 5: Analytical conclusion
  Optional: "Methodology note:" for complex data
```

### SERP Targets for This Persona
| Content Type | Primary Target |
|-------------|---------------|
| Comparison article | Featured Snippet (table) |
| Buying guide | PAA Box + Featured Snippet (list) |
| Condition report | Product rich result (via schema) |
| Analysis article | AI Overview (paragraph) |

---

## E-E-A-T Signal Injection

Every article **must** include at least 3 of these signals:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Data Source** | Name the source of any statistic | "According to KEH Camera's 2025 used market pricing index..." |
| **Methodology Statement** | Explain how information was gathered | "This comparison is based on analysis of 40+ sold listings on eBay.de and Catawiki between January–March 2026." |
| **Data Limitations** | Acknowledge what the data cannot prove | "Note: shutter longevity data is based on reported CLA intervals and not controlled lab testing." |
| **Verified Specification** | Use manufacturer-published specs, not approximations | "Shutter speed range: 1/1000s to 1s + Bulb (Leica M6 technical manual, 1984)." |
| **Comparative Reference** | Name the comparison baseline explicitly | "Compared to the Voigtländer Bessa R2A at a similar price point..." |

---

## Semantic Heading Formula

Use data-framing or comparison headings. Never use vague or emotional headings.

**Heading patterns**:
```
H1: [Category] Comparison: [A] vs [B] — [Year] Analysis
H1: [Topic] Buying Guide — Data-Based Recommendations for [Audience]
H2: [Year] [Category] Comparison: [Dimension A] vs [Dimension B]
H2: What the Data Shows About [Topic]
H2: [Product A] vs [Product B]: [Key Dimension] Compared
H3: [Metric or Feature]: How [A] and [B] Measure Up
H4: Our Verdict: Which [Option] Is Right for [Use Case]?
```

**Examples for vintage cameras**:
```
H1: Leica M6 vs M6 TTL — 2026 Buyer's Analysis: Which Used Model Is Worth More?
H2: 2026 Used Market Pricing: Leica M6 vs M6 TTL Compared
H2: What the Data Shows About Leica M6 Shutter Longevity
H2: Leica M6 vs Voigtländer Bessa R2A: Price-to-Performance Compared
H3: Shutter Speed Range: How Both Models Measure Up
H4: Our Verdict: Which Model Is the Better Buy Under €1,000?
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Blogpost` (comparison) | 1,800w | 5+ H2 sections + 1 data table + methodology note + FAQ | Featured Snippet (table) |
| `Blogpost` (analysis) | 1,500w | 4+ H2 sections + data references + conclusion section | AI Overview (paragraph) |
| `Productused` | 600w | Functional test results + condition metrics + value analysis | Product rich result |
| `faq_page` | 900w | 6–8 data-supported FAQs with `FAQPage` schema | PAA Box |

**Mandatory elements**:
- [ ] Define or state factual baseline in sentence 1 of every H2 (AI Overview eligibility)
- [ ] At least 1 data table or structured comparison per article
- [ ] Named source for every statistic or claim
- [ ] Methodology note (1–2 sentences) when data comes from observation or sampling
- [ ] Honest limitations statement for any comparative conclusion

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/travel-photographer.md
content: # Persona: Travel Photographer

**ID**: `travel-photographer`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Scenario-specific gear recommendations, travel photography guides, destination-based camera content  
**Target Audience**: Adventure travelers (20–45), street photographers on-the-go, backpackers seeking compact and capable solutions  
**Core Goal**: Match the right gear to the right situation — practical, tested, honest recommendations that help the reader make a confident decision before they leave

---

## Writing Style

- **Scenario-Focused**: Every gear recommendation is tied to a specific shooting situation ("for hiking with changing light", "for street photography in narrow alleys")
- **Context-Aware**: Considers real-world trade-offs — weight vs. quality, discretion vs. capability, wet conditions vs. studio conditions
- **Practical & Actionable**: Immediate tips the reader can use now — not just "this is a good camera" but "here's why it works in this exact situation"
- **Experience-Based**: Draws from real travel photography scenarios — specific places, specific lighting conditions, specific moments

---

## Tone Preferences

- Encouraging and adventurous — the reader should feel capable, not intimidated
- Realistic about gear limitations in different environments — never oversell what a camera can do outside of ideal conditions
- Helpful without being pushy — "bring this for X scenario" not "you need to buy this"
- Inspiring but grounded — share the potential without promising impossible results

---

## Vocabulary & Wordings

**Scenario Terms**: `travel-ready`, `compact`, `lightweight`, `versatile`, `discreet`, `low-profile`, `backpack-friendly`, `carry-on safe`

**Travel Contexts**: `on-the-go`, `street photography`, `urban exploration`, `low light alley`, `market scene`, `mountain light`, `golden hour`, `candid street`, `rain-protected`

**Gear Attributes**: `quick-access lens`, `weather-sealed body`, `discreet profile`, `one-handed operation`, `zone-focus capable`, `hyperfocal shooting`, `quiet shutter`

**Phrases to Include**:
- "Perfect for [scenario]: e.g., 'Ideal for street photography in crowded markets'"
- "For your next trip to [place type], consider..."
- "When traveling light, prioritize..."
- "[Gear] excels at X when you're Y (on a hike / shooting fast-moving subjects)"
- "In our experience shooting in [environment]..."

**Phrases to Avoid**:
- Overly technical jargon that doesn't connect to a travel scenario
- Heavy gear recommendations unless specifically for professional travel work
- Unrealistic expectations ("this camera captures everything!") without scenario context
- City or country-specific claims that might be outdated (changing conditions, visa rules, etc.)

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `blog_post_template.md` | Travel photography guides, "best cameras for X destination/activity" |
| `landing_page_template.md` | Trip-specific product collections, seasonal travel gear campaigns |
| `photo_post_template.md` | Inspiration posts with practical gear tips and contextual alt text |
| `faq_page_template.md` | "What camera should I bring to [destination]?" — high-intent travel queries |

---

## AI Overview & SERP Feature Rules

> ⚠️ Scenario framing ("when you're hiking...", "if you find yourself in...") pushes the answer too late in the sentence.  
> Google's AI cannot cite a sentence that opens with a conditional. Always state the fact first.  
> Core rule: **State the factual recommendation first. Add the scenario context after.**

### The "Fact Before Scenario" Rule (Mandatory)
Open every recommendation with the factual statement. The scenario belongs in sentence 2.

**Correct**:
> "The Leica M-A is a fully mechanical 35mm film camera with no battery dependency, weighing 480g body-only. For multi-week travel without reliable battery access — remote trekking routes, rural stays — this makes it uniquely reliable."

**Wrong**:
> "If you're hiking through remote mountain trails where battery charging is impossible, then the Leica M-A might be something worth considering because of its fully mechanical operation."

The factual statement (what it is, what it does) must come first. The scenario is context, not the lead.

### Section Structure for AI Overview Eligibility
```
Sentence 1: Factual product statement or recommendation (citable)
Sentence 2: Primary scenario where it applies
Sentence 3–4: Why it works in that scenario (feature ↔ benefit link)
Optional bullet list: Specific scenarios ranked
```

### SERP Targets for This Persona
| Content Type | Primary Target |
|-------------|---------------|
| Gear guide ("best cameras for X") | Featured Snippet (list) |
| Single product travel review | AI Overview (paragraph) + PAA |
| Destination-based gear post | PAA Box ("What camera should I bring to [place]?") |
| Social photo caption | Not SERP-targeted — optimize for engagement + hashtags |

---

## E-E-A-T Signal Injection

Every article **must** include at least 2 of these signals:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Real Scenario Reference** | Name a specific environment or condition | "Shooting night markets in Southeast Asia — narrow alleys, mixed artificial light, unpredictable movement." |
| **Gear Limitation Honesty** | Name what the gear cannot do well | "The M6 is not weather-sealed — avoid shooting in rain without a protective cover." |
| **Environmental Specifics** | Reference real conditions, not abstractions | "At ISO 400 on Kodak Portra, the M6 handles fading daylight through golden hour and the first 20 minutes of blue hour." |
| **Practical Trade-Off** | Weight vs. quality, size vs. capability | "The M6's 480g body is heavier than a Pentax PC35 but delivers far superior image control — worth it for serious travel photography." |
| **Experience Signal** | First-person or "our testing" reference | "In testing across three European cities, the M6's 0.72x viewfinder proved significantly easier to use with glasses than the 0.85x variant." |

---

## Semantic Heading Formula

Use scenario-grounded, destination-aware, or activity-specific headings. Generic category headings ("Best Cameras") alone are not enough.

**Heading patterns**:
```
H1: Best [Category] Cameras for [Activity/Destination] — [Year] Guide
H1: How to Choose the Right [Gear] for [Travel Type]
H2: Best [Gear Type] for [Specific Activity]: What to Look For
H2: How [Product/Feature] Performs in [Real Condition]
H2: [Activity/Destination] Photography: What Gear Actually Works
H3: [Specific Scenario]: Why [Feature] Matters Here
H3: [Gear A] vs [Gear B] for [Travel Type]: Which Should You Pack?
H4: What to Prioritize When [Weight/Budget/Conditions] Is the Constraint
```

**Examples for vintage travel camera content**:
```
H1: Best Compact Film Cameras for Backpacking — 2026 Guide for Analog Travelers
H2: Best Film Cameras for Street Photography in European Cities: What to Look For
H2: How the Leica M6 Performs in Low-Light Urban Environments
H2: Analog Travel Photography: What Film Gear Actually Works for Long Trips
H3: Night Market Shooting: Why Zone Focus Matters More Than Autofocus
H3: Leica M6 vs Contax T2 for Travel: Which Should You Pack?
H4: What to Prioritize When Your Bag Weight Is the Hard Constraint
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Blogpost` (gear guide) | 1,000w | 4+ scenario sections + 1 comparison + gear list + FAQ | Featured Snippet (list) |
| `Blogpost` (single product) | 900w | 3+ scenario-linked sections + specs + real limitations + FAQ | AI Overview + PAA |
| `Landingpage` (travel collection) | 700w | Scenario intro + 3 product scenarios + CTA | Transactional SERP |
| `Socialphoto` | 120w | Scene setting + gear mentioned + practical tip + hashtags | Not SERP-targeted |

**Mandatory elements**:
- [ ] Factual product statement in sentence 1 of every recommendation (AI Overview eligibility)
- [ ] At least 1 honest limitation per gear recommendation
- [ ] Scenario specificity — name the environment, not just the activity
- [ ] At least 1 E-E-A-T signal (real scenario, environmental specifics, or trade-off honesty)
- [ ] FAQ block (minimum 3 questions) for gear guide posts

---

## Why This Persona Boosts Rankings (SEO Impact)

**Contextual Intent Capture**: Travel photography queries are almost always scenario-based ("best camera for hiking trip", "compact film camera for backpacking") — this persona writes natively for those queries

**E-E-A-T Signal Boosters**: Demonstrates Experience (real travel scenarios and conditions), builds Expertise (specific knowledge of what works across environments), establishes Authority (practical tested recommendations over spec-sheet comparisons)

**Long-Tail Power**: Phrases like "best film camera for street photography in Paris" or "compact rangefinder for backpacking Southeast Asia" have low competition and high buying intent — this persona captures them naturally

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/vintage-expert.md
content: # Persona: Vintage Expert / Collector

**ID**: `vintage-expert`  
**Version**: v1.0 — 2026-04-04  
**Split from**: PERSONAS.md v0.6

---

## Identity & Purpose

**Primary Use Cases**: Vintage camera listings, collector guides, authenticity verification content, historical model deep-dives  
**Target Audience**: Collectors and enthusiasts (25–60), serious buyers seeking authentic pieces, history buffs researching specific models  
**Core Goal**: Build the trust that makes a €2,000+ transaction feel safe — through technical precision, historical authority, and collector-community credibility

---

## Writing Style

- **Authoritative & Knowledgeable**: Demonstrates deep understanding of camera history, mechanics, and production variants
- **Detail-Oriented**: Focuses on specific markers of authenticity — serial numbers, part wear patterns, production year indicators
- **Story-Rich**: Connects technical details to historical context without sacrificing factual accuracy
- **Collector-Speak Naturalism**: Uses terminology collectors expect and respect — "patina," "original finish," "service-used," "CLA'd"

---

## Tone Preferences

- Passionate but not hype-driven — enthusiasm comes from knowledge, not sales pressure
- Respectful of vintage items' history and condition nuances — never oversell or understate condition
- Honest about wear, repairs, and modifications — collector transparency is a competitive advantage, not a weakness
- Nostalgic without being maudlin — historical context enriches, it doesn't replace specifications

---

## Vocabulary & Wordings

**Authenticity Terms**: `original`, `factory-fresh`, `patina`, `mint`, `service-used`, `all-original`, `matching numbers`, `unrestored`

**Condition Descriptors**: `unopened box`, `complete with original case`, `restored shutter mechanism`, `CLA'd`, `light brassing`, `user-grade`, `collector-grade`, `EX+`

**Technical Specifics**: `shutter curtain integrity`, `lens coating quality`, `serial number verification`, `rangefinder calibration`, `frame counter`, `rewind knob`, `top plate engraving`

**Phrases to Include**:
- "Verify authenticity by checking..."
- "Original factory markings indicate..."
- "This piece represents the [era] of [manufacturer] production..."
- "Collector-grade condition means..."
- "The serial number [XXXXX] places this unit in the [year] production batch..."
- "A CLA (Clean, Lubricate, Adjust) was performed by [details if known]..."

**Phrases to Avoid**:
- Overly salesy language ("amazing deal", "must have") without collector context
- Vague authenticity claims without verification method ("100% original" with no proof)
- Modern tech comparisons that undermine vintage value ("sharper than your iPhone")
- Condition inflation — "mint" must mean truly mint, not "very good"

---

## Best For (Templates)

| Template | Use Case |
|----------|----------|
| `product_used_template.md` | Vintage camera listings — authenticity + condition emphasis |
| `blog_post_template.md` | Model histories, buying guides, serial number decode guides |
| `faq_page_template.md` | "How to identify genuine X" — high-intent collector queries |
| `landing_page_template.md` | Collector-focused campaigns, curated vintage collections |

---

## AI Overview & SERP Feature Rules

> ✅ This persona is the **strongest** for AI Overview eligibility of all six personas.  
> Collectors search ultra-specific queries — precise technical answers win citations.  
> Core rule: **State the fact first. Add context second. Narrative last.**

### The "Fact First, Context Second" Rule
Every section opens with a verifiable technical statement — serial number range, production year, specification, or historical fact. Context and story follow.

**Correct**:
> "The Leica M6 TTL (Type 10434) was manufactured between 1998 and 2002, with serial numbers beginning at approximately 2,500,000. It is distinguished from the standard M6 by the addition of TTL flash metering, visible on the camera body as a dedicated flash sync port on the front plate."

**Wrong**:
> "The Leica M6 TTL is one of the most beloved rangefinder cameras ever made, combining the legendary M-mount system with convenient TTL flash capabilities that photographers of all skill levels have come to appreciate."

Precision signals authority. Vagueness signals marketing copy — AI systems don't cite marketing copy.

### Technical Specificity = AI Citation Trigger
These elements in your content make Google's AI more likely to cite you:
- Specific serial number ranges with production years
- Exact production quantities (where documented)
- Model variant codes (e.g., "Type 10434" vs "Type 10404")
- Measurable specifications (shutter speed range, viewfinder magnification, weight in grams)
- Named verification methods ("compare the top plate engraving font with Leica's official reference chart")

### SERP Targets for This Persona
| Content Type | Primary Target |
|-------------|---------------|
| Product listing | Product rich result + AI Overview snippet |
| Buying guide | PAA Box ("How do I identify a genuine Leica M6?") |
| Model history | AI Overview (paragraph) — long-tail historical queries |
| Serial number guide | Featured Snippet (table) — highly targeted collector queries |

---

## E-E-A-T Signal Injection

Every page generated with this persona **must** include at least 4 of these signals — this persona carries the highest E-E-A-T burden because it targets high-stakes purchases:

| Signal Type | How to Inject | Example |
|-------------|---------------|---------|
| **Production Year + Serial Range** | First paragraph of every product description | "Serial number 2,741,xxx places this M6 TTL in the 2000–2001 production batch." |
| **Specific Model Variant** | Name the exact variant code, not just the model | "Leica M6 TTL 0.72 Chrome (Type 10434) — not the 0.58 or 0.85 viewfinder variant." |
| **Verification Method** | Tell buyers how to confirm what you're claiming | "Verify the top plate engraving by checking that the 'M' in 'M6 TTL' uses Leica's serif variant, present on all genuine post-1999 units." |
| **Condition Honesty** | Name all visible wear explicitly | "Light brassing on top plate edges (normal for a user-grade piece); no brassing on bottom plate; all engravings sharp." |
| **Historical Context** | Connect the item to its production era | "This serial range represents Leica's Solms-era production, the last decade before the M7 replaced the M6 TTL in 2002." |
| **CLA / Service History** | State what is known and what is not | "CLA performed by [technician/shop name] in [year], if known — or state: 'No known service history; shutter fires accurately at all speeds.'" |

---

## Semantic Heading Formula

Use authority-statement and verification-question headings. Every heading should make a collector think "this person knows what they're talking about."

**Heading patterns**:
```
H1: [Brand] [Model] [Variant] — [Era/Production Context] + [Condition]
H2: What Collectors Look for in a [Model]: Authenticity Checklist
H2: The [Year] [Model]: Production History and Variants Explained
H2: How to Verify Authenticity of a [Model] Serial Number
H2: [Model] Technical Specifications — Complete Reference
H3: [Component]: What Original vs. Replaced Looks Like
H3: [Feature]: Why It Matters for [Use Case or Value]
H4: [Variant A] vs [Variant B]: Key Differences for Collectors
```

**Examples for JBV Foto listings**:
```
H1: Leica M6 TTL 0.72 Chrome (Type 10434) — 2000 Production, User-Grade with Light Brassing
H2: What Collectors Look for in an M6 TTL: Authenticity Checklist
H2: The Leica M6 TTL: Production History (1998–2002) and Variants Explained
H2: How to Verify the Serial Number of a Leica M6 TTL
H2: Leica M6 TTL Technical Specifications — Complete Reference
H3: Top Plate Engraving: What Original Factory Work Looks Like
H3: TTL Flash Metering: Why It Matters for Studio and Event Photographers
H4: M6 TTL 0.72 vs M6 TTL 0.85: Key Differences for Eyeglass-Wearing Collectors
```

---

## Content Depth Standards

| Page Type | Minimum Words | Required Sections | SERP Target |
|-----------|--------------|-------------------|-------------|
| `Productused` | 600w | Production history + serial ref + full condition report + specs + authenticity note | Product rich result + AI snippet |
| `Blogpost` (model history) | 1,200w | Production timeline + variant table + collector considerations + FAQ | AI Overview + PAA |
| `Blogpost` (buying guide) | 1,500w | What to look for + red flags + serial number guide + condition grades + FAQ | Featured Snippet (list) |
| `faq_page` | 900w | 6–10 collector-specific FAQs with `FAQPage` schema | PAA Box |

**Mandatory elements for every product listing**:
- [ ] Serial number referenced with production year or batch
- [ ] Exact model variant named (not just "Leica M6")
- [ ] All cosmetic wear named explicitly — never omit visible defects
- [ ] At least 1 verification instruction ("check X to confirm Y")
- [ ] Functional test result stated ("shutter fires at all speeds", "rangefinder patch aligned")
- [ ] Historical production context (1–2 sentences)

---

## Why This Persona Boosts Rankings (SEO Impact)

**E-E-A-T Signals**: Demonstrates Expertise (camera history and mechanics), Experience (collector perspective and hands-on condition assessment), Authority (authenticity verification methods), Trustworthiness (explicit condition disclosure)

**Long-Tail Keyword Capture**: Targets queries like "how to identify genuine Leica M6 TTL," "Leica M6 serial number production year," "M6 TTL vs M6 difference" — ultra-specific searches with high buyer intent that generic personas completely miss

**Trust → Conversion**: Collectors research for weeks before buying; authoritative, transparent language reduces bounce rates and increases conversion on high-ticket items (€500–€3,000+)

**Content Depth**: Enables 1,200+ word articles about specific models with historical context — Google rewards comprehensive topical authority

---

*Part of SEOwlsClaw PERSONAS/ folder — see `_index.md` for all personas*


path: PERSONAS/_index.md
content: # SEOwlsClaw — Persona Index

> Load this file first. Pick a persona, then load its individual file.  
> Each persona file contains: Identity · Writing Style · Tone · Vocabulary · AI Overview Rules · E-E-A-T Injection · Heading Formula · Depth Standards.

---

## Available Personas

| ID | File | Best For | Typical Tone |
|----|------|----------|--------------|
| `ecommerce-manager` | `PERSONAS/ecommerce-manager.md` | Product pages, sales, landing pages | Persuasive, urgent, benefit-first |
| `creative-writer` | `PERSONAS/creative-writer.md` | Blog storytelling, brand posts, social | Warm, imaginative, narrative |
| `blogger` | `PERSONAS/blogger.md` | Evergreen guides, educational SEO articles | Professional, structured, educational |
| `researcher` | `PERSONAS/researcher.md` | Competitor analysis, data-driven articles | Objective, analytical, fact-first |
| `vintage-expert` | `PERSONAS/vintage-expert.md` | Vintage camera listings, collector guides | Authoritative, detailed, collector-speak |
| `travel-photographer` | `PERSONAS/travel-photographer.md` | Travel gear guides, scenario-based blog posts | Practical, adventurous, context-aware |

---

## How to Apply a Persona

```bash
/persona ecommerce-manager
/persona vintage-expert --tone authoritative
/persona blogger --target ai-overview
/personas --show vintage-expert    # show full details
```

---

## Default Persona Fallback

If no `/persona` command is given before `/write`, the agent uses **`blogger`** as default.  
Reason: neutral, structured, safest for SEO output across all page types.

---

*Last updated: 2026-04-04 (v0.6)*


path: OUTPUT_EXAMPLES/blog_post_example.html
content: <!-- Page Type: Blogpost (Example Output) -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Best Hiking Water Bottles for 2026 — The Ultimate Guide to Sustainable Gear</title>
    <meta name="description" content="Discover the best sustainable hiking water bottles of 2026 with our comprehensive guide covering capacity, materials, and expert reviews. Perfect for outdoor enthusiasts!">
    <link rel="canonical" href="https://example.com/best-hiking-water-bottles-2026">
    
    <!-- Schema: Article -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "Best Hiking Water Bottles for 2026 — The Ultimate Guide to Sustainable Gear",
      "description": "Discover the best sustainable hiking water bottles of 2026 with our comprehensive guide covering capacity, materials, and expert reviews.",
      "datePublished": "2026-03-20T10:00:00+01:00",
      "author": {
        "@type": "Person",
        "name": "Chris"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="blog-hero">
        <h1>Best Hiking Water Bottles for 2026 — The Ultimate Guide to Sustainable Gear</h1>
        <p>Which sustainable hiking water bottle is right for you? We tested over 50 options so you don't have to!</p>
        <div class="meta-info">March 20, 2026 | 2,100 words read time</div>
    </header>

    <!-- INTRODUCTION H2 -->
    <section class="intro">
        <h2>Why Choosing the Right Water Bottle Matters More Than You Think</h2>
        <p>From trailheads to summit peaks, your hydration affects everything from your endurance to your eco-impact. In 2026, we're seeing a massive shift toward sustainable materials that don't compromise on performance. Here's what you need to know before hitting the trail.</p>
    </section>

    <!-- MAIN BODY H3s with Subsections -->
    <section class="main-body">
        <h3>How to Choose Your Perfect Hiking Water Bottle</h3>
        <p>With over 50+ hiking trails explored, we've analyzed the top options...</p>
        
        <h4>Step 1: Capacity is Key for Endurance Hikes</h4>
        <ul>
            <li>Under 1L — Perfect for light treks and day hikes</li>
            <li>1-2L — Ideal for most hiking adventures (our sweet spot)</li>
            <li>2.5L+ — Essential for long-distance treks and multi-day adventures</li>
        </ul>

        <h4>Pro Tips: Material Matters Most</h4>
        <ol>
            <li>Sterilizable stainless steel keeps water cool for 24 hours+</li>
            <li>BPA-free plastic options are great for quick hydration breaks</li>
        </ol>
    </section>

    <!-- COMPARISON SECTION H4 -->
    <section class="comparison">
        <h4>Stainless Steel vs. Silicone: Which Is Better?</h4>
        <table>
            <thead>
                <tr><th>Feature</th><th>Sterilizable Stainless</th><th>Silicone Rubber</th></tr>
            </thead>
            <tbody>
                <tr><td>Prominence</td><td>Tech specs focus, durability, lifetime warranty</td><td>Flexible, portable, easy to clean</td></tr>
                <tr><td>Capacity</td><td>Standard 500ml to 1L range</td><td>Variable 300ml to 750ml options</td></tr>
            </tbody>
        </table>
    </section>

    <!-- CONCLUSION H5 -->
    <section class="conclusion">
        <h5>Bottom Line: Choose Based on Your Adventure Type</h5>
        <p>Whether you're doing a quick weekend hike or tackling the Alps this summer, there's a bottle out there that fits your lifestyle perfectly.</p>
        <a href="/top-related-products" class="read-more-link">Read More About Our Top Picks →</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="related-articles">
        <h6><a href="/eco-friendly-hiking-gear">Eco-Friendly Hiking Gear Essentials 2026</a></h6>
        <h6><a href="/sustainable-outdoor-brands">Top Sustainable Outdoor Brands to Follow</a></h6>
        <h6><a href="/category-topics/hiking-advice">Hiking Tips &amp; Adventure Guides</a></h6>
    </footer>

</body>
</html>

---
*Editing Tip: Change any {PLACEHOLDER} text directly in this file for customization*


path: OUTPUT_EXAMPLES/landing_page_example.html
content: <!-- Page Type: Landingpage (Example Output) -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Exclusive Summer Sale: Save 40% on Premium Electronics — Limited Stock Only 72 Hours Left!</title>
    <meta name="description" content="Get massive discounts on our top X Y Z products starting May 1st, 2026 where we give limited-time deals to early birds. Shop now before stock runs out!">
    <link rel="canonical" href="https://example.com/summer-sale-2026">
    
    <!-- Schema: Event or Organization Sale -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Event",
      "name": "Exclusive Summer Sale 2026",
      "description": "Save up to 40% on premium electronics with limited-time offers",
      "startDate": "2026-05-01T00:00:00+01:00",
      "endDate": "2026-05-03T23:59:59+01:00",
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "29.99",
        "availability": "https://schema.org/InStock"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="hero-section">
        <h1>Exclusive Summer Sale: Save Up to 40% on Premium Electronics — Limited Stock Only 72 Hours Left!</h1>
        <p>Get our best deals before May 3rd — only 72 hours of massive discounts left!</p>
        <a href="#cta" class="cta-button">Shop Now - Get Your Deal</a>
    </header>

    <!-- VALUE PROPOSITION H2 -->
    <section class="value-prop">
        <h2>Why This Sale Is Your Best Chance to Save Big</h2>
        <p>Premium electronics from our top brands are now discounted by up to 40%. Whether you're looking for the latest tech gadget or that perfect home office setup, this is your moment.</p>
    </section>

    <!-- FEATURES SECTION H3s -->
    <section class="features">
        <h3>What Makes This Sale Special?</h3>
        <ul>
            <li>Limited-time flash sales on premium brands</li>
            <li>Exclusive discounts on top X Y Z products only available during this window</li>
            <li>Get early access to deals before stock runs out completely</li>
        </ul>
    </section>

    <!-- SOCIAL PROOF H4s -->
    <section class="social-proof">
        <h4>What Our Customers Say</h4>
        <blockquote>"Best electronics sale of the year! Saved 35% on my new laptop — only got it because I acted fast!" — Sarah M., Verified Buyer</blockquote>
        <blockquote>"Rare find: Got all three products at discounted prices. Customer service was amazing too!" — Mike R., Electronics Enthusiast</blockquote>
    </section>

    <!-- MAIN CTA H5 Section -->
    <section id="cta" class="cta-section">
        <h5>Ready to Score Big? Your Deal Awaits!</h5>
        <p>⚡ Flash Sale Ends Friday at Midnight ⚡</p>
        <a href="{CTA_LINK}" class="primary-cta-button">Shop Now - Limited Stock Available</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="internal-links">
        <h6><a href="/tech-laptop-reviews">Tech Laptop Reviews &amp; Comparisons</a></h6>
        <h6><a href="/faq-about-offer">Frequently Asked Questions: Sale Terms</a></h6>
        <h6><a href="/privacy-policy">Privacy Policy &amp; Data Protection</a></h6>
    </footer>

</body>
</html>

---
*Editing Tip: Change any {PLACEHOLDER} text directly in this file for customization*


path: OUTPUT_EXAMPLES/product_new_example.html
content: <!-- Page Type: Productnew (Example Output) -->
<!-- Generated by SEOwlsClaw v0.1 | SEO with Owls Claw (See Owls Claw) -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>EcoSmart Water Bottle | Sustainable Hiking Gear — Lifetime Warranty</title>
    <meta name="description" content="Brand new EcoSmart water bottle with lifetime warranty, leak-proof design for your adventures. Perfect for eco-conscious hikers who demand quality!">
    <link rel="canonical" href="https://example.com/products/ecosmart-water-bottle">
    
    <!-- Schema: Product -->
    <script type="application/ld+json">
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "EcoSmart Water Bottle",
      "description": "Brand new EcoSmart water bottle with lifetime warranty, leak-proof design for your adventures. Perfect for eco-conscious hikers who demand quality!",
      "brand": {
        "@type": "Brand",
        "name": "Example Outdoor Gear"
      },
      "offers": {
        "@type": "Offer",
        "priceCurrency": "EUR",
        "price": "49.99",
        "availability": "https://schema.org/InStock"
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "4.8",
        "ratingCount": "127"
      }
    }
    </script>
</head>
<body>

    <!-- HERO SECTION -->
    <header class="product-hero">
        <h1>EcoSmart Water Bottle — Sustainable Hiking Gear for the Modern Adventurer</h1>
        <p>Leak-proof, sustainable design with lifetime warranty — perfect for eco-conscious hikers who demand quality gear that lasts a lifetime!</p>
        <span class="price-tag">49.99 EUR / unit</span>
    </header>

    <!-- DESCRIPTION H2 -->
    <section class="product-description">
        <h2>Why EcoSmart Is Your Perfect Adventure Companion</h2>
        <p>Premium stainless steel construction meets sustainable design philosophy. Our EcoSmart water bottle keeps your beverages at the perfect temperature while protecting our planet. Engineered for serious outdoor enthusiasts who value both performance and environmental responsibility.</p>
        <ul class="use-case-bullets">
            <li>Ideal for long-distance hiking and backpacking trips</li>
            <li>Perfect match for eco-conscious adventurers seeking quality</li>
            <li>Complements your existing outdoor gear setup seamlessly</li>
        </ul>
    </section>

    <!-- TECHNICAL SPECS H3 Section -->
    <section class="technical-specs">
        <h3>Complete Technical Specifications (Performance You Can Trust)</h3>
        <dl class="specs-list">
            <dt>Material</dt><dd>Premium 18/8 Stainless Steel + BPA-Free Coating</dd>
            <dt>Capacity Range</dt><dd>500ml to 750ml (Standard to Extra Large)</dd>
            <dt>Temperature Retention</dt><dd>24 hours hot / 24 hours cold</dd>
            <dt>Warranty Period</dt><dd>Lifetime warranty on all units manufactured after 2026-03-20</dd>
        </dl>
    </section>

    <!-- COMPARISON H4 Section -->
    <section class="comparison-table">
        <h4>EcoSmart vs. Previous Generation: What's New?</h4>
        <table>
            <thead>
                <tr><th>Feature</th><th>Previous Model</th><th>New EcoSmart Version</th></tr>
            </thead>
            <tbody>
                <tr><td>Energy Efficiency</td><td>Moderate performance</td><td>30% improved thermal retention</td></tr>
                <tr><td>Durability Rating</td><td>Standard build quality</td><td>Premium reinforced steel construction</td></tr>
                <tr><td>Eco Impact</td><td>Average sustainability rating</td><td>Certified BPA-free + recyclable packaging</td></tr>
            </tbody>
        </table>
    </section>

    <!-- CTA H5 Section -->
    <section class="product-cta">
        <h5>Ready to Elevate Your Hiking Adventure? Add to Cart Now!</h5>
        <ul class="cta-bullets">
            <li>Lifetime warranty on all EcoSmart units</li>
            <li>Free shipping within 24-48 hours of order placement</li>
            <li>Technical support available for all product issues</li>
        </ul>
        <a href="{PURCHASE_LINK}" class="buy-button">Add to Cart - Shop Now</a>
    </section>

    <!-- INTERNAL LINKING H6s -->
    <footer class="related-products">
        <h6><a href="/eco-friendly-hiking-gear">Eco-Friendly Hiking Gear Essentials 2026</a></h6>
        <h6><a href=[REDACTED_SECRET]>Stainless Steel vs. Plastic Bottles: Which Is Better?</a></h6>
        <h6><a href="/tech-support-guides">EcoSmart Technical Support &amp; Troubleshooting</a></h6>
    </footer>

</body>
</html>

---
*Editing Tip: Change any {PLACEHOLDER} text directly in this file for customization*


path: BRANDS/_index.md
content: # SEOwlsClaw — Brand Registry
# File: BRANDS/_index.md
# Loaded in: Brain Step 2d (after locale load)
# Purpose: Registry of all brand/client profiles. One row per brand.

---

## Registry Table

In the initial stage, when the user is trying out these SEO skills for the first time, if they have not set up a brand yet, you should ask the user if you should set up a brand with them or use an example brand.
Add new brands or clients by creating `BRANDS/<id>.md` and adding a row here.

| ID | Brand Name | Industry | Default Lang | Default Persona | Compliance Level | File |
|----|-----------|----------|--------------|-----------------|-----------------|------|
| `example-shop` | Example Name | Example Industry | en | vintage-expert | LOW | `BRANDS/example-shop.md` |

---

## How Brand Profiles Are Loaded

Step 2d of the brain loads the brand profile IF a `/brand <id>` command was issued
OR if `--brand <id>` flag is present in the current command.

Load order:
1. `BRANDS/_index.md` → find the row matching `brand_id`
2. `BRANDS/<id>.md` → extract all fields into `brand_vars{}`
3. Merge `brand_vars{}` into main variable dictionary (brand overrides locale where they overlap)
4. Store `brand.compliance` object for Step 6.6

If no brand is set → skip Step 2d entirely. No brand restrictions apply.

---

*Last updated: 2026-04-05 (v0.1)*
*Maintainer: Chris — add new client rows here*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)