Combination Math

The number of combinations is always: Keywords Selected x Markets Selected = Total Combinations. This must equal the plan level exactly. There is no rounding, no approximation.

Examples:

• Level A (20 combos): 4 keywords x 5 markets = 20. Or 2 keywords x 10 markets = 20.
• Level B (30 combos): 5 keywords x 6 markets = 30. Or 3 keywords x 10 markets = 30.
• SEO Booster (10 combos): 1 keyword x 10 markets = 10. Or 2 keywords x 5 markets = 10.

What to Extract

Browse the client website thoroughly. Do not skim. Visit the homepage, every service page, the about page, and the contact page. Extract the following:

Business Model Classification

Before leaving this step, classify the client's business model. This classification directly controls which keywords are valid in Step 3.

Using the SEMrush API

Run scripts/semrush_keyword_research.py using each service line as a seed keyword. The SEMrush API key is stored in the SEO Strategist skill.

If the SEMrush API balance is zero, use known industry search volumes from prior research. Document which keywords were sourced from SEMrush vs. estimated, so the data can be verified later.

Keyword Generation Rules

For each service line, generate keyword variants using these modifiers:

Volume Thresholds

Include all keywords with national monthly search volume above 100. Do not discard low-volume keywords at this stage — they may be valuable for niche service lines. The selection decision happens in Step 5, not here.

The Core Rule: Same Core Term Only

A keyword is only a variant within a bucket if it shares the exact same core term. This is not a guideline. It is the rule. If two keywords have different core terms, they are different buckets, regardless of how similar they seem.

How to Build a Bucket

Every bucket must have exactly this structure:

1. Base keyword (variant_type: "base") — the core term with no modifiers. Example: "kitchen cabinets". This is the anchor row. Every bucket must have one, even if the base term alone has low search volume.
2. Near me variant (variant_type: "near_me") — the core term plus "near me". Example: "kitchen cabinets near me". Usually the highest-volume keyword in the bucket.
3. Additional variants — other modifiers applied to the same core term. Example: "custom kitchen cabinets", "kitchen cabinets store".

Bucket Examples for Common Industries

Building the Market List

Run scripts/market_analysis.py for the client's county or region. For multi-county service areas, run per county and combine. Filter to cities within approximately 35-40 miles of HQ.

Always include county seat cities even if their population falls below the tier thresholds. County seats carry disproportionate commercial search demand.

Tiering Rules

Exclusion Rules

Remove any city that the user has explicitly excluded. Document the exclusion and the reason in the strategy notes. Do not add excluded cities to the Not Used section of the strategy site — exclusions are operational notes, not keyword/market decisions.

The Selection Formula

The formula is: Keywords x Markets = Plan Combinations. You must decide how many keywords and how many markets to use. The two strategies are:

Keyword Selection Rules

1. One keyword per service line maximum. Select the highest-volume base keyword from each service line bucket. Do not select two keywords from the same bucket.
2. Maximize service line coverage. A lower-volume keyword for a distinct service line is more valuable than a higher-volume variant of an already-covered line.
3. Business model alignment is mandatory. The selected keywords must match the client's business model. A retail showroom never gets "cabinet makers" or "remodeling contractor." A contractor never gets "showroom."
4. The near me variant is almost always the right choice. "Kitchen cabinets near me" (74,000/mo) beats "kitchen cabinets" (201,000/mo) for local SEO because it has stronger local commercial intent.

Market Selection Rules

1. Calculate the number of markets first: Plan Combinations / Number of Selected Keywords = Number of Markets.
2. Select top-down by population, strictly. Take the top N markets from the sorted Tier 1 list, then Tier 2 if needed. No skipping. No cherry-picking.
3. HQ city is always market #1. No exceptions.
4. Honor all user exclusions. If the user said "not Seattle," Seattle is not in the list regardless of its population rank.

Not Used Keywords

Every keyword that was researched but not selected must be placed in the Not Used section of the strategy site with a clear reason. Valid reasons are:

• Incorrect business model — the keyword implies a business model the client does not have
• Reserved for plan expansion — valid keyword but the plan level does not have room for it
• Low search volume — below the threshold to justify a combination slot
• Outside service area — the keyword implies a geography the client does not serve

Matrix Orientation Rule

The matrix has two valid orientations. Choose based on the number of markets:

Enforcement Rules

• Total combinations must equal the plan level exactly. Count every cell.
• No keyword may appear in both the matrix AND the Not Used section.
• No Not Used keyword may appear in the Additional Opportunities section.
• Row and column totals must be mathematically accurate.

File Structure

Every client strategy site lives at: /home/ubuntu/seo-strategy-repo/{clientdomain}/

The four required files are:

Writing Rules (Non-Negotiable)

• No em dashes or en dashes anywhere. Not in prose, not in labels, not in card text. Use a period, comma, colon, or parentheses instead.
• Plan hero text uses a colon: "Plan Level A: 20 Keyword-City Combinations" — not a dash.
• Tier labels use a colon: "TIER 1: PRIMARY MARKETS" — not a dash or em dash.
• Price fields are numeric: Store 900 not "$900/mo". The renderer adds the formatting.
• new_market is boolean: Store true or false, not a string.

opp-card Structure (Critical)

Every Additional Opportunities card must contain exactly 8 child divs in this order:

1. opp-plan-label
2. opp-price
3. opp-combos-large
4. opp-combos
5. opp-headline
6. opp-desc
7. opp-new-market (use style="visibility:hidden" if no new markets are added)
8. opp-kw-list

If any card has fewer than 8 children, the CSS subgrid alignment breaks for the entire row.

How to Run the Local Preview

cd /home/ubuntu/seo-strategy-repo
python3 -m http.server 8090
# Then navigate to http://localhost:8090/{clientdomain}/

What to Check

Deployment Steps

1. Pull latest from GitHub to avoid conflicts:
   cd /home/ubuntu/seo-strategy-repo && git pull origin main
2. Add the client entry to the clients array in the root index.html
3. Update the README.md client table
4. Commit and push:
   git add .
git commit -m "feat: Add [Client Name] SEO strategy site"
git push origin main
5. Wait 60-90 seconds for Vercel to deploy
6. Navigate to https://seo-strategy.dotcomdesign.com/{clientdomain}/ and verify the live site renders correctly

Writing Rules

Data Type Rules

CSS Subgrid Rules

All card grids use CSS Subgrid for horizontal alignment. The pattern is:

1. Parent container defines grid-template-rows with one track per card element
2. Each card uses grid-row: span N and grid-template-rows: subgrid
3. At max-width: 900px, all cards fall back to display: flex; flex-direction: column; grid-row: span 1

The opp-card specifically uses 8 tracks and grid-row: span 8. If a card has fewer than 8 children, the subgrid breaks for the entire row.

Data Accuracy