AI Agent Context Bootstrap

strategy/agent-context.md · strategy · 1 versions

AI Agent Context Bootstrap

START HERE. This is the single entry point for AI agents working on Adwave content. Point to this file when starting a new context.

---

Documentation Hierarchy

Understanding Auto-Applied vs Reference Docs

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 1: AUTO-APPLIED RULES (.cursor/rules/*.mdc)              │
│  ────────────────────────────────────────────────────────────── │
│  These are AUTOMATICALLY injected into every conversation.      │
│  You don't need to read them; they're already in your context.  │
│                                                                 │
│  • adwave-product.mdc   → Adwave facts, features, pricing       │
│  • adwave-voice.mdc     → Tone, style, AI scrubbing rules       │
│  • adwave-formatting.mdc → Structure, headings, lists           │
│  • adwave-seo.mdc       → SEO requirements (⚠️ READ THIS FILE)  │
│  • adwave-quality.mdc   → Quality checklist                     │
│  • adwave-competitor-content.mdc → What NOT to mention          │
│                                                                 │
│  ⚠️ NOT AUTO-APPLIED (must read manually before generating):    │
│  • adwave-images.mdc    → Image styles, colors, prompts         │
│    (Summary included in this file under "Image Generation")     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  LAYER 2: THIS FILE (strategy/agent-context.md) ← YOU ARE HERE  │
│  ────────────────────────────────────────────────────────────── │
│  Central hub with essential constants, workflows, quick ref.    │
│  Links to detailed guides when more depth is needed.            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  LAYER 3: REFERENCE GUIDES (strategy/*.md)                      │
│  ────────────────────────────────────────────────────────────── │
│  Detailed guides for specific workflows. Read when needed.      │
│                                                                 │
│  PUBLISHING:                                                    │
│  • publishing-guide.md         → Full publishing workflow       │
│  • content-playbooks.md        → Content type outlines          │
│  • prose-first-writing-guide.md → Prose vs lists guidance       │
│                                                                 │
│  STAT SNAPSHOTS:                                                │
│  • stat-snapshot-writing-guidelines.md → Section structure      │
│  • stat-snapshot-qc-checklist.md       → Pre-publish QC         │
│                                                                 │
│  SOCIAL MEDIA:                                                  │
│  • social-media-guide.md         → Content + images + workflow  │
│  • social-media-distribution-guide.md → Scheduling              │
│                                                                 │
│  REFERENCE:                                                     │
│  • industry-taxonomy.md        → Industry/subindustry values    │
│  • documentation-gaps.md       → Known issues (living doc)      │
└─────────────────────────────────────────────────────────────────┘

When to Read What

Task	Read These
Any content creation	This file (auto-applied rules already loaded)
Stat snapshot post	+ `stat-snapshot-writing-guidelines.md` + `stat-snapshot-qc-checklist.md`
Industry page	+ `industry-taxonomy.md` + `briefs/_TEMPLATE-industry-page.md`
Other blog posts	+ `content-playbooks.md`
Publishing to Contentful	+ `publishing-guide.md`
⚠️ Generating images	Image section in this file OR `.cursor/rules/adwave-images.mdc`
Social media content	+ `social-media-guide.md`
Social scheduling	+ `social-media-distribution-guide.md`

---

⛔ CRITICAL: All Facts and Statistics MUST Be Sourced

NEVER cite facts, statistics, or data that cannot be verified with a source. Spreading false or unverified information damages credibility.

The Golden Rule

If you cannot link to a source, do not present it as a fact.

What Requires a Source (MANDATORY)

ALL of the following MUST have linked citations:

Market sizes and spending figures (e.g., "$33 billion CTV ad spend")
Percentages and shares (e.g., "38% of TV ad spend is CTV")
Year-over-year changes (e.g., "up 16% from 2024")
Projections and forecasts (e.g., "expected to reach $40B by 2027")
Platform-specific numbers (e.g., "Netflix has 94M ad tier users")
Industry breakdowns (e.g., "DTC brands allocate 55% to CTV")
Geographic or demographic data (e.g., "Top 10 DMAs see 42% CTV share")
Historical comparisons (e.g., "up from 15% in 2020")
Expert quotes (must be real, verifiable quotes)
Research findings (e.g., "86% of advertisers use GenAI")

What Does NOT Require a Source

These are acceptable without citation:

Common knowledge (e.g., "TV advertising has traditionally been expensive")
Adwave product facts (e.g., "$50 minimum", "100+ channels", "$25 CPM average")
General explanations (e.g., "CTV stands for Connected TV")
Logical analysis (e.g., "Lower ad loads mean less inventory, which affects pricing")
Recommendations and advice (e.g., "Start with $200-500 for a test campaign")

How to Handle Uncertain Data

If you find a statistic but cannot verify the source:

DO NOT USE IT
Search for an alternative statistic with a verifiable source
If no sourced alternative exists, describe the concept without specific numbers

If you want to present analysis or estimates:

Clearly label as "industry estimates" or "based on available data"
Never present estimates as verified facts
Use qualifying language: "typically ranges from," "generally," "approximately"

Source Quality Requirements

Acceptable sources:

Industry research firms (eMarketer, Nielsen, IAB, Statista)
Company reports and earnings (SEC filings, investor relations)
Major news outlets citing primary research
Trade publications with cited data
Government statistics

Unacceptable sources:

Random blogs without citations
Social media posts
Marketing materials making unverified claims
Your own calculations unless clearly labeled
"Common industry knowledge" for specific numbers

Pre-Publish Data Audit

Before publishing ANY content:

Review every specific number, percentage, or statistic
Verify each has a linked source in the text
If any data point lacks a source, either add one or remove the claim
Check the Supporting Data section: every bullet must have a source link

Examples

❌ WRONG (unsourced):

CTV captures 38% of total TV ad spend, representing $33B of the $88B market.

✅ CORRECT (sourced):

U.S. CTV ad spending reached $33.35 billion in 2025, according to [eMarketer](https://www.emarketer.com/).

❌ WRONG (unsourced breakdown):

By category:
- DTC brands: 55% CTV
- Retail: 42% CTV
- Auto: 38% CTV

✅ CORRECT (honest about limitations):

CTV adoption varies by category. Digital-native brands tend to allocate more heavily to CTV due to their data-driven mindsets, while categories with stricter regulatory requirements may adopt more slowly.

---

⛔ CRITICAL: Mandatory Sitemap Verification for ALL Links

BEFORE using ANY internal link in ANY content, you MUST verify it exists in the current sitemap.

# REQUIRED: Fetch sitemap BEFORE writing ANY content
firecrawl_map(url: "https://adwave.com")

Rules:

NEVER assume a link is valid based on pattern or memory
NEVER use a link that isn't in the sitemap you just fetched
ALWAYS verify EVERY /industries/ and /resources/ link against the sitemap
Check for exact matches including full path structure (e.g., /industries/home-services/hvac/tv-advertising-hvac-companies NOT /industries/home-services/hvac/tv-advertising-hvac)

Common broken link patterns to watch for:

Missing suffixes: tv-advertising-hvac → tv-advertising-hvac-companies
Wrong path structure: /industries/healthcare/tv-advertising-dentists/ → /industries/healthcare/dental-practices/tv-advertising-dentists/
Typos in slugs: streaming-tv-ad-costs → streaming-tv-ad-cost

If you're not 100% certain a link exists, DO NOT USE IT. Fetch the sitemap and verify.

---

What Is This Project?

Adwave is an AI-powered platform that lets small businesses create and run TV commercials on streaming platforms (CTV) starting at just $50.

This repository contains the content strategy, briefs, and drafts for Adwave's blog. The goal is to create content that:

Captures search traffic for CTV/TV advertising topics
Educates SMBs about TV advertising opportunities
Positions Adwave as the accessible solution

---

Essential Constants

CONTENTFUL_SPACE_ID: fia320z3blxi
CONTENTFUL_ENVIRONMENT_ID: master
CONTENT_TYPE_FOR_POSTS: resource
DEFAULT_LOCALE: en-US

---

Writing Style Guidelines

Adwave content should read like advice from a knowledgeable friend. Use a natural mix of prose and lists based on what serves the content best.

General Approach

Don't avoid lists when they genuinely help (steps, features, quick reference)
Don't overuse lists as a crutch to avoid writing prose
Prioritize word count targets over format preferences
Add context to list items when explanation helps the reader

When Lists Work Well

Sequential steps in how-to content
Quick reference information (features, specs, requirements)
Parallel items that benefit from easy scanning

When Prose Works Better

Explaining concepts and reasoning
Building narrative and context
Introductions, transitions, and conclusions
FAQ answers (complete prose answers work best)

Full guide: strategy/prose-first-writing-guide.md

---

Content Types & Workflows

Content Types & Where to Find Briefs

Type	Word Count	Schedule	Briefs
Stat Snapshot Pages	3,000-4,000	`stat-snapshot-calendar.md`	`stat-snapshot-writing-guidelines.md`
Industry Pages	2,000-3,000	`editorial-calendar.md`	See "Industry Vertical Briefs" section
Platform/Technical Guides	3,000-4,000	`editorial-calendar.md`	See "Platform & Technical Briefs" section
Political Content	2,000-3,500	`editorial-calendar.md`	See "Political Advertising Briefs" section
SMB Guides & Comparisons	3,000-4,000	`editorial-calendar.md`	`content-playbooks.md`

📅 All scheduling and briefs are now consolidated in editorial-calendar.md

Regular Blog Post Length by Type

Content Type	Target Words	Min/Max
Platform Guides	3,000-3,500	3,000-4,000
Case Studies	1,200-1,500	1,000-1,800
Comparison Posts	3,000-3,500	3,000-4,000
Vertical Playbooks	2,000-2,500	1,800-3,000
Statistics Roundups	1,500-2,000	1,200-2,500
How-To Guides	3,000-3,500	3,000-4,000
Thought Leadership	1,200-1,800	1,000-2,200

---

⚠️ CRITICAL: Slug Verification (ALL Content Types)

ALWAYS verify the slug is available BEFORE creating any Contentful entry.

Duplicate slugs will cause publishing failures or overwrite existing content. This step is NON-NEGOTIABLE for every piece of content.

# Run this BEFORE creating any entry
npm run check-slug -- "your-slug-here"

If the slug is taken:

Check if it's the same content being updated (get entry ID from calendar)
If it's different content, choose a new slug
Never proceed with a duplicate slug

---

Workflow 1: Stat Snapshot Pages

Stat snapshot pages are data-driven "quick reference" pages answering specific questions (e.g., "What is YouTube's share of TV viewing?"). They're designed for featured snippets and authority building.

Key Requirements

Word count: 3,000-4,000 words (HARD MINIMUM: 3,000)
Internal links: 8-12 minimum
External sources: 5+ with working links
Images: 4 minimum (1 hero + 3 body)
Statistics boxes: 3 stats at top (embedded statisticGroup)
11 required sections (see guide)

Stat Snapshot Workflow

Check calendar: calendar/stat-snapshot-calendar.md
Verify slug is available: npm run check-slug -- "slug-from-calendar"
Read guidelines: strategy/stat-snapshot-writing-guidelines.md
Deep research: Multiple sources, 5+ citations required
Write draft: All 11 sections, prose-first, 3,000+ words
Verify word count: wc -w drafts/stat-snapshots/[file].md (need 3,200+ in markdown)
AI scrub: Remove emdashes, AI telltale words
Generate images: 4 minimum using nano-banana
⛔ MANDATORY QC CHECKPOINT: Complete strategy/stat-snapshot-qc-checklist.md

- [ ] Word count ≥ 3,000 (verified via wc -w) - [ ] All 11 sections present with minimum word counts - [ ] 4+ images uploaded with asset IDs - [ ] 8+ internal links included - [ ] 5+ source citations with working links - [ ] AI content scrubbed (zero emdashes, zero flagged words) - [ ] Statistics entries created - ⛔ DO NOT PROCEED TO STEP 10 UNTIL ALL BOXES CHECKED

Create Contentful entries: Statistics → StatisticGroup → Resource

- Resource entry MUST include ALL required fields: - title (with quarter marker) - slug (verified available) - headerImage (hero image asset) - resourceDate (YYYY-MM-DD from calendar) - resourceType ("Insights" for stat snapshots) - seoDescription (meta description) - bodyContent (with statisticGroup embedded first)

Update tracking: Mark complete in calendar with word count and image count

Stat Snapshot Section Structure

0. Hero Image (headerImage field)
1. Statistics Boxes (embedded statisticGroup - 3 stats)
2. Opening paragraph (150-200 words)
3. ## What the data shows (500-700 words)
4. ## Breaking down the numbers (400-600 words)
5. ## Why it matters for your business (400-500 words)
6. ## How to take advantage of this trend (400-500 words)
7. ## The bigger picture (350-450 words)
8. ## What experts are saying (250-350 words)
9. ## Common questions answered (400-500 words, 5-6 FAQs)
10. ## Supporting data (200-300 words, linked bullets)
11. ## Get started with TV advertising (100-150 words, CTA)

Note: The "Common questions answered" section (FAQ) is required for ALL content types. See below.

---

Workflow 2: Industry Pages

Industry pages are conversion-focused content targeting specific business verticals (e.g., "TV Advertising for Dentists").

Key Requirements

Word count: 2,000-3,000 words (HARD MINIMUM: 2,000)
Internal links: 4+ minimum
Images: 4 minimum (1 hero + 3 body)
Required fields: industryType and subindustryType
Prose-first: Benefits explained, not listed

Industry Page Workflow

Check calendar: calendar/editorial-calendar.md (look for Industries category)
Verify slug is available: npm run check-slug -- "slug-from-brief"
Read template: briefs/_TEMPLATE-industry-page.md
Check taxonomy: strategy/industry-taxonomy.md for correct industryType values
Fetch sitemap: firecrawl_map(url: "https://adwave.com") for internal links
Write draft: Prose-first, 2,000-3,000 words
Generate images: 4 minimum using nano-banana
⛔ QC CHECKPOINT: Before publishing, verify:

- [ ] Word count ≥ 2,000 (verified via wc -w) - [ ] 4+ images uploaded with asset IDs - [ ] 4+ internal links included (verified against sitemap) - [ ] AI content scrubbed (zero emdashes, zero flagged words) - [ ] industryType and subindustryType set correctly - ⛔ DO NOT PROCEED UNTIL ALL BOXES CHECKED

Publish to Contentful: Resource with resourceType: "Industries"
Update tracking: Mark complete in calendar with word count and image count

Industry Page Section Structure

1. Introduction (~150-200 words)
2. ## Why TV advertising works for [industry] (prose, NOT bullets)
3. ## Real results from [industry] TV ads (narrative, NOT bullet list)
4. ## Targeting strategies for [industry]
   - H3: Geographic targeting
   - H3: Demographic targeting
   - H3: Interest-based targeting
5. ## Budget considerations for [industry]
6. ## Creating effective [industry] TV commercials
7. ## How it works for [industry] (narrative walkthrough)
8. ## Measuring success for [industry]
9. ## Common mistakes to avoid (prose explanations, NOT bullet list)
10. ## Common questions answered (250-350 words, 4-5 FAQs)
11. ## Getting started (pricing + CTA)

Valid `industryType` Values (19 total)

Healthcare, Home Services, Automotive, Professional Services, Food & Beverage, Retail, Beauty & Wellness, Fitness & Recreation, Education & Enrichment, Events & Entertainment, Real Estate, Pet Services, Travel & Hospitality, E-commerce, Creators & Influencers, Community & Nonprofit, Financial, Legal, Political

---

Required Section: Common Questions Answered (FAQ)

Every article must include a "Common questions answered" section. This is required for all content types, not just stat snapshots.

Why FAQs Are Required

Featured snippets: FAQ format targets "People Also Ask" and featured snippet opportunities
Long-tail traffic: Captures search queries phrased as questions
Reader value: Addresses natural follow-up questions readers have after the main content
Completeness: Signals comprehensive coverage to both readers and search engines

FAQ Format

## Common questions answered

### [Question 1]?

[2-4 sentences of prose answering the question completely. Write it as you would explain it to a colleague, not as bullet points.]

### [Question 2]?

[Direct prose answer with context and explanation.]

### [Question 3]?

[Direct prose answer.]

(Continue for 4-6 questions depending on content type)

FAQ Guidelines by Content Type

Content Type	Min Questions	Word Count	Notes
Stat Snapshots	5-6	400-500	Technical/methodology questions
Industry Pages	4-5	250-350	Industry-specific concerns
Platform Guides	4-5	250-350	Platform capabilities, costs, access
How-To Guides	3-4	200-300	Common stumbling blocks
Comparison Posts	3-4	200-300	"When to use which" questions
Case Studies	3-4	150-250	Applicability/transferability questions
Thought Leadership	3-4	200-300	Future/implications questions

Writing FAQ Answers

Prose only: Each answer should be 2-4 sentences of flowing prose
No bullets: Don't turn answers into lists unless genuinely listing 4+ items
Complete answers: Each answer should stand alone without requiring reading the main article
Natural language: Write questions as readers would actually ask them
Industry-specific: Tailor questions to the specific topic, not generic "what is CTV" questions

FAQ Placement

Place the FAQ section near the end of the article, typically:

After main content sections
Before "Supporting data" (if applicable)
Before final CTA section

---

Workflow 3: Regular Blog Posts

Regular blog posts include guides, case studies, comparisons, and thought leadership.

Regular Post Workflow

Find next article: calendar/editorial-calendar.md (look for 🔲 status)
Read the brief: briefs/YYYY-MM-DD-slug.md
Verify slug is available: npm run check-slug -- "slug-from-brief" ⚠️ REQUIRED
Check playbook: strategy/content-playbooks.md for content type outline
Fetch sitemap: firecrawl_map(url: "https://adwave.com") for internal links
Write draft: Prose-first, follow brief outline
Generate images: 4+ minimum using nano-banana
⛔ QC CHECKPOINT: Before publishing, verify:

- [ ] Word count meets target for content type (see table above) - [ ] 4+ images uploaded with asset IDs - [ ] 4+ internal links included (verified against sitemap) - [ ] AI content scrubbed (zero emdashes, zero flagged words) - [ ] FAQ section included (see requirements below) - ⛔ DO NOT PROCEED UNTIL ALL BOXES CHECKED

Publish to Contentful: See publishing workflow below
Update tracking: Mark complete in calendar with word count and image count

---

Internal Linking Requirements

Content Type	Minimum Links	Priority Sources
Stat Snapshots	8-12	`/resources/` pages, industry pages
Industry Pages	4+	`/industries/`, `/how-it-works/`, `/resources/`
Regular Posts	4+	`/resources/` pages (prioritize variety)

⛔ MANDATORY: Verify EVERY Link Against Sitemap

You MUST fetch and verify links before writing ANY content:

# Step 1: ALWAYS fetch sitemap first
firecrawl_map(url: "https://adwave.com")

# Step 2: Search results for EXACT URL you want to use
# Step 3: If not found, DO NOT USE THAT LINK

Common mistakes that cause broken links:

Using /tv-advertising-hvac instead of /tv-advertising-hvac-companies
Missing subpath like /dental-practices/ in /industries/healthcare/dental-practices/tv-advertising-dentists
Plural vs singular: /streaming-tv-ad-costs vs /streaming-tv-ad-cost

NEVER guess or assume a link exists. ALWAYS verify against the sitemap you just fetched.

Link Selection Priority

First: /resources/ pages matching article topic
Second: /industries/ pages when discussing verticals (verify full path!)
Third: Core pages (/how-it-works/, /pricing/, /faq/) only when directly relevant

---

⛔ CRITICAL: Image Generation Requirements

ALL content types require minimum 4 images (1 hero + 3 body).

⛔ MANDATORY: Read Image Guidelines BEFORE Generating

The .cursor/rules/adwave-images.mdc file is NOT auto-applied. You MUST read it before generating any images, or read the summary below.

Brand Color Palette (MANDATORY - NO EXCEPTIONS)

Color	Hex Code	Usage
Navy	`#222239`	Primary text, main doodles, outlines, solid tape
Teal	`#57b4ad`	Accents, highlights, secondary elements, patterned tape
Lime	`#d7df27`	Bright accents, emphasis, celebratory elements (stars, sparkles)
Cream/Off-White	-	Background color only

⛔ FORBIDDEN COLORS: coral, orange, red, purple, pink, golden yellow, or any color not listed above.

In ALL prompts, ALWAYS specify colors with hex codes:

"navy (#222239)", "teal (#57b4ad)", "lime (#d7df27)"

Hero Image Style: "Digital Scrapbook" (MANDATORY)

Every hero image MUST include ALL of these elements:

Textured Background: Off-white cardstock or recycled paper texture (NEVER flat white)
"Taped Down" Elements: Everything attached with washi tape strips in solid navy or patterned teal
Hand-Drawn Overlays: Imperfect marker-style arrows, circles, stars, underlines
Subtle Drop Shadows: Elements look like paper resting on the background
Brand Colors Only: Navy, teal, lime, cream - nothing else

Hero Image Recipes by Content Type

Type	Central Elements	Hand-Drawn Doodles
Platform Guides	Schematic wireframes, device cutouts	Technical annotations, gears, data flow arrows
Case Studies	Photo of smiling person (taped)	Celebratory circles around stats, stars, confetti
Comparison Posts	Vertical split with tape, two icons	VS in center, checkmarks vs X marks
Vertical Playbooks	Aspirational industry photo	Industry-specific tools (keys, stethoscopes, etc.)
Statistics/Data	Chart cutouts, bold numbers (NO people)	Magnifying glasses, precise arrows
How-To Guides	3-4 sticky notes/index cards in a row	Curved arrows showing progression
Thought Leadership	Metaphorical objects (lightbulbs, networks)	Swirling lines, sparkles, question marks

Body Image Style: "Editorial Clean" for Charts

Charts and data visualizations use a different style:

No backgrounds or borders - chart sits on white/cream
Brand colors only - Teal for primary data, Navy for secondary, Lime for highlights
Zero effects - No gradients, shadows, glows, or 3D
Bold typography - Large data callouts directly on chart
No gridlines or tick marks - Minimal, clean axes

Image Generation Prompt Template

[DESCRIBE SCENE]. Digital scrapbook style on textured off-white cardstock 
background. Elements taped down with washi tape in navy (#222239) and 
teal (#57b4ad) patterns. Hand-drawn marker overlays including [arrows/
circles/stars]. Colors ONLY: navy (#222239), teal (#57b4ad), lime (#d7df27), 
cream background. Subtle drop shadows. 16:9 format. No text except [specific 
text if needed].

⛔ Image QC Checklist (MANDATORY Before Upload)

Run this checklist for EVERY generated image:

[ ] Colors correct: Only navy (#222239), teal (#57b4ad), lime (#d7df27), cream
[ ] NO forbidden colors: No coral, orange, red, purple, pink, golden yellow
[ ] Background textured: Off-white cardstock (not flat white)
[ ] Elements taped down: Washi tape visible attaching elements
[ ] Hand-drawn overlays: Marker-style arrows, circles, or stars present
[ ] Text reviewed: All text checked character-by-character for typos
[ ] Correct recipe: Using the right style for the content type

⛔ If ANY checkbox fails, regenerate the image. DO NOT PROCEED with wrong colors.

Image Placeholder Format (REQUIRED)

Standard markdown images !alt DO NOT WORK. Use this format:

<!-- IMAGE: unique-id -->
**Placement:** [Where in article]
**Type:** [Chart | Diagram | Concept]
**Description:** [Alt text for accessibility]
**Filename:** exact-filename.png
<!-- /IMAGE -->

Image Generation Workflow

Generate images using nano-banana MCP (generate_image, continue_editing)
Copy to article folder: drafts/images/YYYY-MM-DD-slug/
Upload all images: npm run upload-images -- "drafts/images/SLUG/" "Title"
Add placeholders to draft with exact filenames from asset-ids.json

---

Table Handling

⚠️ Markdown tables CANNOT be used directly in Contentful RichText.

Tables must be created as separate table entries in Contentful, then embedded.

Table Workflow

Create table entry in Contentful (Content Type: table)
Publish the table entry
In markdown, use placeholder format:

<!-- TABLE: table-id -->
**Title:** Table Name
**Entry ID:** CONTENTFUL_TABLE_ENTRY_ID
<!-- /TABLE -->

The markdown-to-richtext script embeds the table automatically

---

Publishing Workflow (Quick Reference)

# 1. ⚠️ VERIFY SLUG IS AVAILABLE (MANDATORY - DO NOT SKIP)
npm run check-slug -- "your-slug-here"
# If slug is taken, STOP and resolve before proceeding

# 2. Upload images
npm run upload-images -- "drafts/images/SLUG/" "Article Title"

# 3. Convert to RichText (strip npm log prefix)
npm run markdown-to-richtext -- "drafts/SLUG.md" "drafts/images/SLUG/asset-ids.json" > /tmp/richtext-raw.json
tail -n +4 /tmp/richtext-raw.json > /tmp/richtext.json

# 4. Create tables (if any) via Contentful MCP
#    For each <!-- TABLE: id --> block:
#      a. create_entry contentTypeId="table", fields={title, tableMarkdown}, then publish_entry
#      b. sed 's/__TABLE_PLACEHOLDER_<id>__/<ENTRY_ID>/g' /tmp/richtext.json > /tmp/final-richtext.json
#    Verify:  grep -c TABLE_PLACEHOLDER /tmp/final-richtext.json   # must be 0
#    If no tables: cp /tmp/richtext.json /tmp/final-richtext.json

# 5. Create entry via Contentful MCP (create_entry)
# 6. Update body (npm run update-entry-body -- "ENTRY_ID" /tmp/final-richtext.json)
#    NOTE: update-entry-body auto-publishes — no separate publish_entry needed.

Full details: strategy/publishing-guide.md

---

AI Content Scrubbing (MANDATORY)

Every draft must be scrubbed before publishing.

Emdash Removal (CRITICAL)

NEVER use emdashes (—). Replace with commas, parentheses, colons, or periods.

Words to Remove/Replace

AI Telltale	Replace With
Delve	explore, dig into, look at
Landscape	market, space, industry
Leverage	use, take advantage of
Robust	strong, solid
Seamless	smooth, easy
Utilize	use
Myriad	many, lots of
Embark	start, begin
Comprehensive	(be specific)
It's important to note	(just state it)
In conclusion	(conclude naturally)

Scrubbing Workflow

Search for emdashes (—) and replace ALL
Search for AI telltale words and replace
Remove hedging phrases
Read aloud for natural flow
Check sentence variety

---

Contentful Field Reference

Field	Type	Required	Notes
title	Symbol	Yes	Article title
subtitle	Symbol	No	Supporting headline
slug	Symbol	Yes	URL slug (no leading /)
shortDescription	Symbol	No	Card/preview text
headerImage	Asset Link	No	Hero image
resourceDate	Date	Yes	YYYY-MM-DD
resourceType	Symbol	Yes	Case Study, Guides, Industries, Insights, News, Using Adwave
industryType	Symbol	Industries only	See valid values above
subindustryType	Symbol	Industries only	Specific niche
bodyContent	RichText	Yes	Article body
seoDescription	Symbol	Yes	Meta description

---

Critical Rules (Quick Reference)

Never Mention These Competitors

MNTN, Vibe/Vibe.co, Creatify, tvScientific, Simpli.fi, or any other CTV ad platform

OK to Mention (Streaming Platforms)

Roku, Hulu, Amazon Fire TV, Peacock, Tubi, Pluto TV, NBC, ESPN, CBS, ABC, Fox

Adwave Accuracy

Minimum spend: $50
Ad creation: Free
CPM: $15-35 (average $25)
Ad generation: ~2 minutes
Total launch time: Under 10 minutes
Channels: 100+ premium networks
Ad length: 30 seconds

Voice/Tone

Use contractions (you'll, it's)
Speak to "you" directly
Never use emdashes (—)
Mix prose and lists naturally (prioritize word count targets)
Scrub AI words

---

File Structure Reference

content-writing/
├── .cursor/rules/                    # AUTO-APPLIED rules (don't need to read)
│   ├── adwave-product.mdc           # Adwave facts & pricing
│   ├── adwave-voice.mdc             # Tone, style, AI scrubbing
│   ├── adwave-formatting.mdc        # Structure, headings, lists
│   ├── adwave-seo.mdc               # SEO requirements
│   ├── adwave-quality.mdc           # Quality checklist
│   ├── adwave-images.mdc            # Image styles (source of truth)
│   └── adwave-competitor-content.mdc # What NOT to mention
├── briefs/                           # Article briefs
│   ├── _TEMPLATE-industry-page.md    # Industry page template
│   └── YYYY-MM-DD-slug.md            # Individual briefs
├── calendar/
│   ├── editorial-calendar.md         # ⭐ MAIN calendar (schedule + all briefs)
│   └── stat-snapshot-calendar.md     # Stat snapshot schedule (separate content type)
├── keywords/                          # Keyword research (converted from xlsx)
│   ├── already-targeted.md           # ⛔ CHECK BEFORE WRITING (158 keywords)
│   ├── phase1-smb-broad.md           # Phase 1: SMB advertising keywords (1,051)
│   ├── phase3-tv-industry.md         # Phase 3: TV + industry keywords (261)
│   └── phase4-industry-no-tv.md      # Phase 4: Industry no TV (247)
├── drafts/
│   └── stat-snapshots/               # Stat snapshot drafts
├── strategy/
│   ├── agent-context.md              # THIS FILE - entry point
│   ├── publishing-guide.md           # Full publishing workflow
│   ├── content-playbooks.md          # Content type outlines
│   ├── prose-first-writing-guide.md  # Prose vs lists guidance
│   ├── stat-snapshot-writing-guidelines.md   # Stat snapshot sections
│   ├── stat-snapshot-qc-checklist.md         # ⛔ MANDATORY pre-publish QC
│   ├── social-media-guide.md         # Social content + images + workflow
│   ├── social-media-distribution-guide.md    # Social scheduling
│   ├── industry-taxonomy.md          # Industry/subindustry values
│   └── documentation-gaps.md         # Known gaps (living doc)
└── scripts/                          # Publishing & maintenance scripts
    ├── append-faq-to-entry.ts       # Add FAQ section to existing entry
    ├── check-slug.ts                # Verify slug availability
    ├── comprehensive-stats-audit.ts # Audit all stats posts
    ├── delete-entry.ts              # Delete Contentful entry
    ├── embed-images-in-entry.ts     # Add images to entry
    ├── fetch-post-content.ts        # Fetch entry content
    ├── fix-all-stats-richtext.ts    # Fix RichText for all stats posts
    ├── fix-entry-richtext.ts        # Fix RichText for single entry
    ├── fix-stats-posts.ts           # Remove/fix stats groups
    ├── markdown-to-richtext.ts      # Convert MD to Contentful RichText
    ├── update-entry-body.ts         # Update bodyContent field
    ├── update-entry-bodycontent.ts  # Update entry with RichText
    └── upload-images.ts             # Upload images to Contentful

---

MCP Tools Available

Contentful (user-contentful-*)

create_entry - Create new content
update_entry - Update fields
publish_entry - Publish draft
get_entry - Fetch entry details
search_entries - Find content
upload_asset - Upload via URL

Nano-Banana (user-nano-banana-*)

generate_image - Create new image from prompt
continue_editing - Refine last generated image
edit_image - Modify specific image file

Firecrawl (user-firecrawl-mcp-*)

firecrawl_scrape - Get content from URL
firecrawl_map - List URLs on a site (for internal links)
firecrawl_search - Web search

---

Quick Commands

# Check what's next
grep "🔲" calendar/editorial-calendar.md

# Read a brief
cat briefs/YYYY-MM-DD-slug.md

# Check if slug is available
npm run check-slug -- "your-slug-here"

# Create image folder
mkdir -p drafts/images/YYYY-MM-DD-slug/

# Upload images
npm run upload-images -- "drafts/images/SLUG/" "Title"

# Convert markdown
npm run markdown-to-richtext -- "drafts/SLUG.md" "drafts/images/SLUG/asset-ids.json"

# Update entry body
npm run update-entry-body -- "ENTRY_ID" /tmp/final-richtext.json

# Verify word count
wc -w drafts/stat-snapshots/YYYY-MM-DD-slug.md

---

When Starting a New Context

Tell the AI:

"Read strategy/agent-context.md and follow the workflow to [specific task]"

This file contains everything needed to get started. The .cursor/rules/ files provide additional context automatically.

For specific content types, also reference:

Stat Snapshots: strategy/stat-snapshot-writing-guidelines.md
Industry Pages: briefs/_TEMPLATE-industry-page.md
Other Posts: strategy/content-playbooks.md

---

Changelog

Date	Change
2025-12-29	Scripts cleanup: Consolidated and documented remaining scripts. Deleted 26+ one-off, debug, and redundant scripts. Updated file structure reference with remaining utility scripts.
2025-12-29	Stats audit cleanup: Removed obsolete audit JSON files. Documented posts that should NOT have statisticGroups in calendars.
2025-12-19	Image QC Addition: Added comprehensive image generation section with brand colors, hero recipes, Editorial Clean chart style, and mandatory QC checklist. Clarified that adwave-images.mdc is NOT auto-applied.
2025-12-19	Guidelines consolidation: Added clear 3-layer documentation hierarchy, updated file structure to reflect consolidated social media guide, referenced .cursor/rules as auto-applied
2025-12-17	Added mandatory QC checkpoint (step 9) to stat snapshot workflow; created `stat-snapshot-qc-checklist.md` for pre-publish verification
2025-12-16	Major rewrite: Added content type workflows (stat-snapshots, industry pages), prose-first emphasis, updated word counts by type, added stat snapshot calendar reference, reorganized for clarity as single source of truth
2025-12-08	Added mandatory image text review step to prevent typos in AI-generated images

Version history

v1 · 6/20/2026, 3:11:54 AM · migration import

AI Agent Context Bootstrap

AI Agent Context Bootstrap

Documentation Hierarchy

Understanding Auto-Applied vs Reference Docs

When to Read What

⛔ CRITICAL: All Facts and Statistics MUST Be Sourced

The Golden Rule

What Requires a Source (MANDATORY)

What Does NOT Require a Source

How to Handle Uncertain Data

Source Quality Requirements

Pre-Publish Data Audit

Examples

⛔ CRITICAL: Mandatory Sitemap Verification for ALL Links

What Is This Project?

Essential Constants

Writing Style Guidelines

General Approach

When Lists Work Well

When Prose Works Better

Content Types & Workflows

Content Types & Where to Find Briefs

Regular Blog Post Length by Type

⚠️ CRITICAL: Slug Verification (ALL Content Types)

Workflow 1: Stat Snapshot Pages

Key Requirements

Stat Snapshot Workflow

Stat Snapshot Section Structure

Workflow 2: Industry Pages

Key Requirements

Industry Page Workflow

Industry Page Section Structure

Valid industryType Values (19 total)

Required Section: Common Questions Answered (FAQ)

Why FAQs Are Required

FAQ Format

FAQ Guidelines by Content Type

Writing FAQ Answers

FAQ Placement

Workflow 3: Regular Blog Posts

Regular Post Workflow

Internal Linking Requirements

⛔ MANDATORY: Verify EVERY Link Against Sitemap

Link Selection Priority

⛔ CRITICAL: Image Generation Requirements

⛔ MANDATORY: Read Image Guidelines BEFORE Generating

Brand Color Palette (MANDATORY - NO EXCEPTIONS)

Hero Image Style: "Digital Scrapbook" (MANDATORY)

Hero Image Recipes by Content Type

Body Image Style: "Editorial Clean" for Charts

Image Generation Prompt Template

⛔ Image QC Checklist (MANDATORY Before Upload)

Image Placeholder Format (REQUIRED)

Image Generation Workflow

Table Handling

Table Workflow

Publishing Workflow (Quick Reference)

AI Content Scrubbing (MANDATORY)

Emdash Removal (CRITICAL)

Words to Remove/Replace

Scrubbing Workflow

Contentful Field Reference

Critical Rules (Quick Reference)

Never Mention These Competitors

OK to Mention (Streaming Platforms)

Adwave Accuracy

Voice/Tone

File Structure Reference

MCP Tools Available

Contentful (user-contentful-*)

Nano-Banana (user-nano-banana-*)

Firecrawl (user-firecrawl-mcp-*)

Quick Commands

When Starting a New Context

Changelog

Version history

Valid `industryType` Values (19 total)