@piramilan/seo-expert 0.2.0

package/bin/seo-expert.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// SEO Expert — npx installer
+// Zero runtime dependencies. Node >= 18.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+// --- ANSI helpers (no chalk) ---------------------------------------------
+const tty = process.stdout.isTTY;
+const c = tty ? {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  blue: '\x1b[34m', green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', gray: '\x1b[90m',
+} : { reset: '', bold: '', dim: '', blue: '', green: '', yellow: '', red: '', gray: '' };
+
+const log = (m = '') => process.stdout.write(m + '\n');
+const errf = (m) => process.stderr.write(c.red + 'error: ' + c.reset + m + '\n');
+const ok = (m) => log(c.green + '✓ ' + c.reset + m);
+const warn = (m) => log(c.yellow + '! ' + c.reset + m);
+const head = (m) => log('\n' + c.bold + m + c.reset);
+
+// --- Tool registry --------------------------------------------------------
+// kind:
+//   "rules-file"   → copy a single source file to a target path in cwd
+//   "skill-dir"    → copy a directory tree into ~/.claude/skills/<name>/
+//   "paste-adapter" → copy adapter content to clipboard and print steps
+const TOOLS = {
+  cursor: {
+    label: 'Cursor',
+    kind: 'rules-file',
+    target: '.cursorrules',
+    source: 'adapters/coding-agent-rules.md',
+    note: 'AI-pair-programming editor',
+  },
+  cline: {
+    label: 'Cline',
+    kind: 'rules-file',
+    target: '.clinerules',
+    source: 'adapters/coding-agent-rules.md',
+    note: 'VS Code agent',
+  },
+  windsurf: {
+    label: 'Windsurf',
+    kind: 'rules-file',
+    target: '.windsurfrules',
+    source: 'adapters/coding-agent-rules.md',
+    note: 'Codeium AI editor',
+  },
+  aider: {
+    label: 'Aider',
+    kind: 'rules-file',
+    target: 'CONVENTIONS.md',
+    source: 'adapters/coding-agent-rules.md',
+    note: 'CLI coding agent — pass with `aider --read CONVENTIONS.md`',
+  },
+  continue: {
+    label: 'continue.dev',
+    kind: 'rules-file',
+    target: '.continue/seo-expert.md',
+    source: 'adapters/coding-agent-rules.md',
+    note: 'Open-source agent',
+  },
+  'claude-code': {
+    label: 'Claude Code',
+    kind: 'skill-dir',
+    target: path.join(os.homedir(), '.claude', 'skills', 'seo-expert'),
+    sources: ['SKILL.md', 'core', 'prompts', 'adapters', 'sources'],
+    note: 'Anthropic CLI — installs to ~/.claude/skills/seo-expert/',
+  },
+  'claude-project': {
+    label: 'Claude Project / Desktop',
+    kind: 'paste-adapter',
+    source: 'adapters/claude-project-instructions.md',
+    instructions: [
+      '1. Go to claude.ai → New Project',
+      '2. Paste the copied text into Custom instructions',
+      '3. Upload to Project knowledge: SKILL.md, core/*.md, prompts/*.md, sources/video-index.md',
+    ],
+  },
+  chatgpt: {
+    label: 'ChatGPT (Custom GPT or Project)',
+    kind: 'paste-adapter',
+    source: 'adapters/chatgpt-instructions.md',
+    instructions: [
+      '1. chatgpt.com → My GPTs → Create (or Projects → New Project)',
+      '2. Paste the copied text into Instructions',
+      '3. Upload the 9 knowledge files listed in the adapter',
+    ],
+  },
+  gemini: {
+    label: 'Gemini Gem',
+    kind: 'paste-adapter',
+    source: 'adapters/gemini-gem-instructions.md',
+    instructions: [
+      '1. gemini.google.com → Gems → New Gem',
+      '2. Paste the copied text into Gem instructions',
+      '3. Embed core/*.md content inline or paste at conversation start',
+    ],
+  },
+  perplexity: {
+    label: 'Perplexity Space',
+    kind: 'paste-adapter',
+    source: 'adapters/perplexity-space-instructions.md',
+    instructions: [
+      '1. perplexity.ai → Spaces → Create',
+      '2. Paste the copied text into Space instructions',
+      '3. Add SKILL.md + core/*.md + prompts/*.md to the Space library',
+    ],
+  },
+};
+
+// --- Utilities -----------------------------------------------------------
+function read(rel) {
+  return fs.readFileSync(path.join(ROOT, rel), 'utf8');
+}
+
+function writeFileSafely(target, content) {
+  const abs = path.resolve(target);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  if (fs.existsSync(abs)) {
+    const backup = abs + '.bak.' + Date.now();
+    fs.copyFileSync(abs, backup);
+    warn(`Existing file backed up → ${c.dim}${path.relative(process.cwd(), backup)}${c.reset}`);
+  }
+  fs.writeFileSync(abs, content);
+}
+
+function copyToClipboard(text) {
+  const candidates = process.platform === 'darwin'
+    ? [['pbcopy', []]]
+    : process.platform === 'win32'
+      ? [['clip', []]]
+      : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+  for (const [cmd, args] of candidates) {
+    const r = spawnSync(cmd, args, { input: text });
+    if (r.status === 0) return true;
+  }
+  return false;
+}
+
+// --- Commands ------------------------------------------------------------
+function help() {
+  log(`${c.bold}SEO Expert${c.reset} ${c.dim}v${PKG.version}${c.reset}`);
+  log(`${c.dim}Portable SEO + AI-SEO skill — installs into any AI tool.${c.reset}\n`);
+  log(`${c.bold}Usage${c.reset}`);
+  log(`  npx ${PKG.name} install <tool>   Install skill files for a coding agent`);
+  log(`  npx ${PKG.name} copy <tool>      Copy adapter content for a web AI tool`);
+  log(`  npx ${PKG.name} list             List all supported tools`);
+  log(`  npx ${PKG.name} info             Show version + repo info`);
+  log(`  npx ${PKG.name}                  Interactive menu\n`);
+  log(`${c.bold}Tools${c.reset}`);
+  for (const [id, t] of Object.entries(TOOLS)) {
+    const verb = t.kind === 'paste-adapter' ? `${c.blue}copy   ${c.reset}` : `${c.green}install${c.reset}`;
+    log(`  ${verb} ${c.bold}${id.padEnd(16)}${c.reset} ${c.dim}${t.label} — ${t.note || ''}${c.reset}`);
+  }
+  log(`\n${c.dim}Docs: ${PKG.homepage}${c.reset}`);
+}
+
+async function installTool(id) {
+  const t = TOOLS[id];
+  if (!t) {
+    errf(`unknown tool: ${id}. Run 'npx ${PKG.name} list' to see options.`);
+    process.exit(1);
+  }
+  if (t.kind === 'rules-file') {
+    const content = read(t.source);
+    const target = path.resolve(process.cwd(), t.target);
+    writeFileSafely(target, content);
+    ok(`Installed ${t.label} rules → ${c.bold}${path.relative(process.cwd(), target) || t.target}${c.reset}`);
+    log(`${c.dim}Next: commit the file. Your agent now applies SEO defaults when editing marketing pages, schema, sitemaps, or meta tags.${c.reset}`);
+    return;
+  }
+  if (t.kind === 'skill-dir') {
+    fs.mkdirSync(t.target, { recursive: true });
+    for (const s of t.sources) {
+      const src = path.join(ROOT, s);
+      const dest = path.join(t.target, s);
+      const stat = fs.statSync(src);
+      if (stat.isDirectory()) fs.cpSync(src, dest, { recursive: true });
+      else fs.copyFileSync(src, dest);
+    }
+    ok(`Installed ${t.label} skill → ${c.bold}${t.target}${c.reset}`);
+    log(`${c.dim}Restart Claude Code (or open a new conversation). The skill auto-routes on SEO questions.${c.reset}`);
+    return;
+  }
+  if (t.kind === 'paste-adapter') {
+    return copyTool(id);
+  }
+}
+
+function copyTool(id) {
+  const t = TOOLS[id];
+  if (!t) { errf(`unknown tool: ${id}`); process.exit(1); }
+  if (t.kind !== 'paste-adapter') {
+    errf(`'${id}' is a file-based install. Use: npx ${PKG.name} install ${id}`);
+    process.exit(1);
+  }
+  const content = read(t.source);
+  const copied = copyToClipboard(content);
+  head(`${t.label} adapter`);
+  if (copied) {
+    ok('Copied adapter to clipboard.');
+  } else {
+    const fallback = 'seo-expert-adapter.md';
+    fs.writeFileSync(fallback, content);
+    warn(`Clipboard not available. Adapter written to ${c.bold}${fallback}${c.reset} — open and copy manually.`);
+  }
+  log('');
+  log(`${c.bold}Next steps:${c.reset}`);
+  t.instructions.forEach((line) => log('  ' + line));
+  log(`\n${c.dim}Full setup walkthrough: ${PKG.homepage}/blob/main/INSTALL.md${c.reset}`);
+}
+
+function list() {
+  head('Supported tools');
+  const file = Object.entries(TOOLS).filter(([, t]) => t.kind !== 'paste-adapter');
+  const web = Object.entries(TOOLS).filter(([, t]) => t.kind === 'paste-adapter');
+  log(`\n${c.dim}File-based install (drops files into your project / home):${c.reset}`);
+  for (const [id, t] of file) {
+    log(`  ${c.green}install${c.reset} ${c.bold}${id.padEnd(16)}${c.reset} ${c.dim}${t.label}${c.reset}`);
+  }
+  log(`\n${c.dim}Web-based (copies adapter to clipboard):${c.reset}`);
+  for (const [id, t] of web) {
+    log(`  ${c.blue}copy   ${c.reset} ${c.bold}${id.padEnd(16)}${c.reset} ${c.dim}${t.label}${c.reset}`);
+  }
+  log(`\n${c.dim}Run 'npx ${PKG.name}' with no args for the interactive menu.${c.reset}`);
+}
+
+function info() {
+  log(`${c.bold}${PKG.name}${c.reset} ${c.dim}v${PKG.version}${c.reset}`);
+  log(`${PKG.description}`);
+  log(`License: ${PKG.license}`);
+  log(`Repo:    ${PKG.homepage}`);
+  log(`Node:    ${process.version}`);
+}
+
+async function interactive() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    head('SEO Expert installer');
+    log(`${c.dim}Pick the AI tool you want to install the skill into.${c.reset}\n`);
+    const entries = Object.entries(TOOLS);
+    entries.forEach(([id, t], i) => {
+      const verb = t.kind === 'paste-adapter' ? `${c.blue}copy   ${c.reset}` : `${c.green}install${c.reset}`;
+      log(`  ${(i + 1).toString().padStart(2)}. ${verb} ${c.bold}${id.padEnd(16)}${c.reset} ${c.dim}${t.label}${c.reset}`);
+    });
+    const answer = (await rl.question(`\nNumber or tool id (q to quit): `)).trim().toLowerCase();
+    rl.close();
+    if (answer === 'q' || answer === '') process.exit(0);
+    const byNum = entries[parseInt(answer, 10) - 1];
+    const id = byNum ? byNum[0] : answer;
+    if (!TOOLS[id]) {
+      errf(`unknown tool: ${answer}. Run 'npx ${PKG.name} list' to see options.`);
+      process.exit(1);
+    }
+    await installTool(id);
+  } catch (e) {
+    errf(e.message);
+    process.exit(1);
+  }
+}
+
+// --- Dispatch ------------------------------------------------------------
+async function main() {
+  const [cmd, arg] = process.argv.slice(2);
+  switch (cmd) {
+    case undefined:
+      return interactive();
+    case 'help':
+    case '-h':
+    case '--help':
+      return help();
+    case 'list':
+      return list();
+    case 'info':
+    case '-v':
+    case '--version':
+      return info();
+    case 'install':
+      if (!arg) { errf('usage: install <tool>'); process.exit(1); }
+      return installTool(arg);
+    case 'copy':
+      if (!arg) { errf('usage: copy <tool>'); process.exit(1); }
+      return copyTool(arg);
+    default:
+      errf(`unknown command: ${cmd}`);
+      help();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => { errf(e.message); process.exit(1); });

package/core/ai-seo-operating-system.md

@@ -0,0 +1,60 @@
+# Universal AI SEO Operating System
+
+> **When to use this playbook:** SEO audit, page rewrite, AI-visibility / GEO / AEO plan, measurement plan. Also the default starting point when the task type is ambiguous.
+
+Use this playbook to improve how a brand, page, or content library appears in traditional search and AI-generated answers. The goal is not only ranking; it is becoming a source that AI systems can extract, trust, and cite.
+
+## Core Workflow
+
+1. Diagnose the current search surface: target queries, existing pages, competitors, SERP features, AI answers, citations, and crawl/index status.
+2. Map intent and entities: define the audience problem, primary entity, related entities, decision criteria, and proof needed for trust.
+3. Make content extractable: lead with direct answers, use clear H2/H3 questions, concise paragraphs, tables, lists, FAQ blocks, and source-backed claims.
+4. Build authority signals: cite original sources, add statistics, show first-hand experience, name authors or experts, collect reviews, and earn relevant mentions.
+5. Fix technical blockers: crawlability, canonical URLs, schema, sitemap coverage, internal links, page speed, mobile usability, and indexability.
+6. Validate and monitor: check Google/Bing indexing, AI answer citations, schema validity, rankings, impressions, clicks, leads, and content freshness.
+
+## AI SEO / GEO Principles
+
+- Write answer-first sections that can stand alone outside the page.
+- Use named entities consistently: brand, product, location, category, audience, competitors, and use cases.
+- Prefer comparison tables and decision frameworks for commercial queries.
+- Add explicit sources for claims, statistics, definitions, and recommendations.
+- Refresh pages when facts, prices, tools, policies, or market conditions change.
+- Keep boilerplate low; unique, useful information is easier for AI systems to cite.
+
+## Traditional SEO Principles
+
+- One clear primary keyword intent per page.
+- Unique title tag, meta description, H1, canonical URL, and structured heading hierarchy.
+- Internal links should point from authority pages to pages that need ranking support.
+- Image filenames and alt text should describe what is visible and relevant.
+- Schema should match the visible page content.
+- Avoid indexable thin pages, duplicate content, and orphan pages.
+
+## Output Standard
+
+Every AI tool using this repo should produce:
+
+- Prioritized actions, not generic advice.
+- Specific page or content examples.
+- Verification steps.
+- Risks, assumptions, and dependencies.
+- Source references when drawing from the video-derived corpus.
+
+## Measuring AI Search Surface
+
+- In GA4 → **Reports → Acquisition → Traffic Acquisition**, add a filter where **Session source** contains `chatgpt`, `perplexity`, `gemini`, or `copilot`. The traffic is small today but trending up; tracking it now establishes a baseline.
+- Look at landing pages receiving LLM referrals. Those are the pages currently being cited — study what makes them extractable (clear answers, schema, entity definitions) and apply the pattern elsewhere.
+- Manually prompt ChatGPT, Perplexity, and Google's AI Overview with the target queries. Record which sources they cite and how the brand is described. Citation gaps and incorrect descriptions are your top-priority content work.
+
+## Earning LLM Citations
+
+- LLMs are trained heavily on Reddit, Wikipedia, Stack Exchange, and a small set of high-authority editorial sites. A presence on those platforms — with the brand or product named — increases citation odds independent of traditional ranking.
+- Create a Reddit account using the brand or founder name. Answer questions in subreddits where the audience already asks. Helpful, named, factual answers age into the training data; promotional answers get removed and damage the account.
+- Ensure the brand has a clear entity profile across the open web: a "what is X" definition somewhere indexable, consistent descriptions on directories, and a Wikipedia or Wikidata entry if the business meets notability bars.
+
+## Paid Surface Inside AI Tools
+
+- ChatGPT is rolling out sponsored placements. Inventory is new, so CPCs are low and competition is thin relative to mature platforms.
+- Intent inside ChatGPT is unusually explicit — users describe their problem in full sentences rather than two-word queries. Bid on long-tail intent that converts elsewhere; the targeting matches better than search ads at the same stage.
+- Treat this as a 6–18 month arbitrage window. Once enterprise advertisers move in, CPCs normalize. The same playbook applied to Google Ads in 2003 and Facebook Ads in 2013.

package/core/content-strategy.md

@@ -0,0 +1,38 @@
+# SEO Content Strategy
+
+> **When to use this playbook:** Content brief, topic cluster plan, editorial calendar, content refresh, internal-link planning, visual / repurposing strategy.
+
+## Topic Planning
+
+- Start with audience jobs, pain points, and buying stages.
+- Build topical clusters around entities, not isolated keywords.
+- Cover definitions, comparisons, alternatives, pricing, implementation, mistakes, examples, and templates.
+- Use internal links to make the cluster obvious to users and crawlers.
+
+## Page Patterns
+
+- Definition page: answer what it is, who it is for, how it works, examples, risks, and next steps.
+- Comparison page: show decision criteria, table, best-fit recommendations, tradeoffs, and proof.
+- Local/service page: prove location relevance, service specificity, reviews, process, and conversion path.
+- Programmatic page: combine a repeatable template with unique data, examples, and entity-specific answers.
+
+## Content Refresh
+
+- Update dates only when content materially changes.
+- Replace stale statistics and screenshots.
+- Add new FAQs based on sales calls, support tickets, Search Console queries, and AI answer gaps.
+- Merge or prune pages that compete for the same intent.
+
+## Visual Asset Pipeline
+
+- Convert long-form posts into embeddable infographics: paste the article into ChatGPT (or any image-capable model) and ask for a downloadable infographic, then embed it back into the article. Visual blocks improve dwell time, shareability, and pickup by image SERPs.
+- For video sources, use Google Gemini Canvas — it can read a YouTube URL directly and generate an editable visual asset, which ChatGPT currently cannot do.
+- Use Google NotebookLM to turn a stack of source files (PDFs, blogs, transcripts) into slide decks, infographics, and summaries that you can fact-check and reuse in articles.
+- Always fact-check AI-generated visuals before publishing — hallucinated statistics in an infographic are worse than no infographic.
+
+## AI-Assisted Internal Linking
+
+- Identify a page-2 keyword from Search Console.
+- Open ChatGPT with your sitemap XML (or a list of URLs + titles) and prompt: "I'm ranking on page 2 for [keyword]. From this sitemap, suggest three internal links into the ranking page with natural anchor text and the surrounding sentence context."
+- Implement the suggestions, then reinspect the ranking page in Search Console; movement is usually visible within 2–4 weeks.
+- Anchor text should describe the destination intent, not just contain the keyword.

package/core/local-seo.md

@@ -0,0 +1,24 @@
+# Local SEO Playbook
+
+> **When to use this playbook:** Local SEO plan, Google Business Profile work, map-pack visibility, multi-location / service-area pages, review strategy, local citation building.
+
+## Local Trust Signals
+
+- Keep name, address, phone, hours, services, and service areas consistent.
+- Optimize Google Business Profile categories, services, photos, products, posts, and Q&A.
+- Ask for specific reviews that mention service, location, outcome, and customer type.
+- Add location proof: neighborhoods, landmarks, staff, projects, photos, and testimonials.
+
+## Local Pages
+
+- Avoid thin city-name swaps.
+- Include unique service details, local FAQs, project examples, reviews, and clear calls to action.
+- Link between service pages, location pages, and relevant blog/support content.
+- Use `LocalBusiness` schema only when it matches the business model and visible page content.
+
+## Behavior Signals For Maps Pack
+
+- Encourage real local actions: searches for the brand + service, **Directions** taps from the listing, phone calls, and website clicks from the Maps Pack. Google uses these behavior signals to validate that the business actually serves the area for that query.
+- When staff or owners travel to the business location, having them search the target keyword and tap **Directions** from the listing is a low-friction signal worth doing as a habit — it is behavior the listing should already be earning from customers.
+- Do not fake these signals at scale or from unrelated IPs; Google's spam systems flag obvious manipulation and the penalty is loss of Maps Pack visibility, which is far more damaging than the boost.
+- The durable form of this advice: make it easy for real customers to take real actions — directions, calls, photos, review prompts after service — and the behavior signal builds itself.

package/core/programmatic-seo.md

@@ -0,0 +1,47 @@
+# Programmatic SEO Guardrails
+
+> **When to use this playbook:** Programmatic SEO plan, large-scale templated pages (locations, integrations, comparisons, datasets), directory or catalog builds, index-bloat triage.
+
+Programmatic SEO works when each generated page satisfies a real search intent with useful unique data. It fails when pages are template duplicates with swapped keywords. Treat the template as a delivery vehicle, not the value — the data and the intent are the value.
+
+## Requirements before generating any pages
+
+- **A repeatable search pattern with real demand.** Validate with Search Console queries, third-party keyword tools, or autocomplete + "people also ask" coverage across the pattern. If only a handful of variants have demand, write them by hand instead.
+- **Unique data or examples for every page.** Each URL must answer something a generic article cannot. Common viable inputs: first-party data, structured public datasets, customer reviews, pricing/availability, location-specific facts.
+- **Strong template sections that answer intent directly.** The template's first screen must contain the direct answer. Boilerplate intros pushed above the answer kill extractability.
+- **Internal links between related variants.** Comparison pages link to category and to the items being compared; location pages link to the parent service and to nearby locations.
+- **Quality controls.** Duplication thresholds, thin-content gates, crawl-budget rules (`noindex` filters/sorts/empties), and a kill-switch for variants that produce no value.
+
+## Page-pattern recipes
+
+Use these as starting templates. Each row is a viable programmatic pattern, the minimum unique data per page, and the failure mode to watch for.
+
+| Pattern | Minimum unique data per page | Failure mode |
+| --- | --- | --- |
+| `[service] in [city]` | Local proof: clients, projects, reviews, neighborhoods served | Thin city swaps with identical body copy → Helpful Content demotion |
+| `[product] alternatives` / `vs [competitor]` | Real comparison table, decision criteria, when-to-pick-each | Aggregator-style listings without an opinion → no citation, no ranking |
+| `[tool] integrations / [tool] + [tool]` | Setup steps, supported triggers/actions, screenshots | Generic "you can connect X and Y" filler → indistinguishable from competitors |
+| `[dataset] for [slice]` (e.g., salaries, prices, stats) | Actual numbers, methodology, last-updated date | Stale or fabricated numbers → trust damage that compounds |
+| `[problem] in [industry/role]` | Industry-specific examples, named tools, named workflows | One generic article cloned across industries → cannibalization |
+| Directory `[category] in [city]` | Real listings with structured fields, owner-verified data | Auto-scraped listings → spam classification + legal risk |
+
+## Validation
+
+- **Sample manually before indexing.** Generate 5–10 variants across the value distribution (head, mid, tail). Read them as a user. If two adjacent variants feel interchangeable, the data layer is too thin.
+- **Schema parity.** Schema fields must match visible content. Do not emit `Product`/`Offer`/`LocalBusiness`/`FAQPage` schema with data the page does not display.
+- **Conversion path.** Each variant must have a non-generic call to action tied to its intent (book in this city, compare these specific tools, download the dataset).
+- **Index hygiene.** Canonical/`noindex` rules for filter variants, sort variants, empty results, and duplicate "near-miss" pairs. Watch Search Console **Pages** for "Duplicate, Google chose different canonical" and "Crawled — currently not indexed."
+
+## Monitoring after launch
+
+- Indexed-page count vs. submitted-sitemap URL count. Large gaps signal quality or duplication problems, not crawl problems.
+- Impressions and clicks **per variant**, not just overall. The fat middle is where programmatic wins or dies.
+- Crawl stats (Search Console → Settings → Crawl stats). A pattern that spikes crawl with low new-content yield will lose priority over time.
+- Conversion quality per variant: if traffic grows but conversions don't, the page set is bringing the wrong intent.
+
+## When NOT to go programmatic
+
+- The user has fewer than ~30 viable variants. Hand-write them.
+- The unique data layer is just paraphrased AI output. The variants will collapse into each other and look like spam.
+- There is no clear conversion path per variant. Programmatic pages without a per-variant call to action become a traffic mirage.
+- The category is already saturated by an authority directory (Yelp, G2, Glassdoor). Compete on a sub-slice with proprietary data, not the same slice with weaker data.

package/core/technical-seo.md

@@ -0,0 +1,51 @@
+# Technical SEO Checklist
+
+> **When to use this playbook:** Technical-SEO fix, schema markup plan, Search Console / GA4 measurement, citation and backlink targeting, crawl or index diagnostics.
+
+## Crawl And Index
+
+- Verify `robots.txt` allows important pages and required bots.
+- Confirm XML sitemaps include only canonical, indexable URLs.
+- Check pages return the correct HTTP status and do not rely on blocked resources.
+- Ensure canonical tags are self-referencing unless consolidation is intentional.
+- Remove noindex tags from pages that should rank.
+- Submit the sitemap in Google Search Console under **Sitemaps**. Without an explicit submission, Google may delay or skip discovery of new pages — especially on new domains.
+- For brand-new domains, verify ownership in Search Console first; if a site:yourdomain.com search returns "no results," that is the signal Google has not crawled at all yet.
+- After adding any new section or content cluster, resubmit or "Inspect URL" the hub page to nudge recrawl.
+
+## Site Structure
+
+- Keep important pages within a few internal clicks from the homepage or hub pages.
+- Use descriptive anchor text that matches the destination page intent.
+- Create hub pages for major topic clusters and link to supporting content.
+- Fix broken links, redirect chains, and orphan URLs.
+
+## Structured Data
+
+- Use `Organization`, `WebSite`, `BreadcrumbList`, `Article`, `FAQPage`, `Product`, `LocalBusiness`, or `SoftwareApplication` only when the visible content supports it.
+- Keep schema fields accurate and current.
+- Validate JSON-LD before shipping.
+
+## Performance And Rendering
+
+- Optimize Core Web Vitals, especially LCP, INP, and CLS.
+- Render critical content in HTML whenever possible.
+- Compress images and define image dimensions.
+- Avoid layout shifts from late-loading ads, embeds, or fonts.
+
+## Working With Search Console
+
+- Open **Search Results**, sort by **Position**, and surface keywords ranking 11–20 (page 2). These are the cheapest wins — small content or internal-link improvements often move them onto page 1.
+- Prioritize page-2 keywords with high **Impressions** but low **Clicks**: existing demand, weak conversion of that demand.
+- For each promising query, click into it, see which page is ranking, and ask: does that page actually answer this intent, or is it ranking by accident? If accidental, build a dedicated page for the intent and link to it from the current ranking page.
+- Use Search Console queries as a backlog source: stale FAQs, missing comparison angles, and gaps in topic coverage all surface here.
+
+## Finding Citation And Backlink Opportunities
+
+- Use search operators to surface directories and citation targets that already accept the niche:
+  - `[industry] [city] inurl:directory`
+  - `[industry] "submit your business"`
+  - `[industry] "add your listing"`
+- For competitor reconnaissance, run `"[competitor brand name]" -site:competitor.com` — this exposes every external page mentioning them, which usually includes the directories, podcasts, guest posts, and "best of" lists they have appeared on. Most are open to you too.
+- Prioritize directories with a real audience over high-volume spam lists. Ten relevant placements outperform a hundred low-quality ones, especially after recent algorithm updates that demote sites with thin link profiles.
+- Maintain NAP (Name / Address / Phone) consistency across every listing. Inconsistency dilutes the entity signal.

package/core/video-derived-lessons.md

@@ -0,0 +1,96 @@
+# Video-Derived AI SEO Lessons
+
+Generated: 2026-05-13T17:10:37+00:00
+
+Use these as source-linked operating principles. They are derived notes, not transcript republication.
+
+## Topic Coverage
+
+- `general_seo`: 825 source video(s)
+- `content_strategy`: 185 source video(s)
+- `authority_signals`: 100 source video(s)
+- `conversion_seo`: 76 source video(s)
+- `ai_seo_geo`: 60 source video(s)
+- `technical_seo`: 48 source video(s)
+- `local_seo`: 43 source video(s)
+- `programmatic_seo`: 8 source video(s)
+
+## Operating Principles
+
+### AI SEO / GEO
+- Make claims easy for AI systems to extract, cite, and verify with clear entities, direct answers, and source-backed proof.
+- Recurring terms to inspect in related work: chatgpt, google, seo, https, heytony, audit, com, rank.
+- Source videos: [CduVCb9By1k](https://www.youtube.com/watch?v=CduVCb9By1k), [OH7UJFaTfko](https://www.youtube.com/watch?v=OH7UJFaTfko), [2JrcV2E7L1Y](https://www.youtube.com/watch?v=2JrcV2E7L1Y), [cNTl_x_cnS8](https://www.youtube.com/watch?v=cNTl_x_cnS8), [15CCl7Osv8Y](https://www.youtube.com/watch?v=15CCl7Osv8Y), [5nWP89AlcAc](https://www.youtube.com/watch?v=5nWP89AlcAc), [_UQeZKr136k](https://www.youtube.com/watch?v=_UQeZKr136k), [TzjELQQVIPQ](https://www.youtube.com/watch?v=TzjELQQVIPQ)
+
+### Authority Signals
+- Build visible trust through reviews, citations, backlinks, expertise, and consistent brand signals.
+- Recurring terms to inspect in related work: backlinks, https, seo, google, heytony, audit, com, free.
+- Source videos: [ukHPtXOS6rA](https://www.youtube.com/watch?v=ukHPtXOS6rA), [OH7UJFaTfko](https://www.youtube.com/watch?v=OH7UJFaTfko), [JtmoqvUmzq0](https://www.youtube.com/watch?v=JtmoqvUmzq0), [ez6ZCM5kMgY](https://www.youtube.com/watch?v=ez6ZCM5kMgY), [Sd27zXjfqTo](https://www.youtube.com/watch?v=Sd27zXjfqTo), [3rBfJagQT24](https://www.youtube.com/watch?v=3rBfJagQT24), [cNTl_x_cnS8](https://www.youtube.com/watch?v=cNTl_x_cnS8), [Zfefiqwn8Cw](https://www.youtube.com/watch?v=Zfefiqwn8Cw)
+
+### Content Strategy
+- Map content to search intent and topical authority instead of publishing isolated keyword posts.
+- Recurring terms to inspect in related work: seo, https, heytony, google, audit, content, com, contentmarketing.
+- Source videos: [CduVCb9By1k](https://www.youtube.com/watch?v=CduVCb9By1k), [OH7UJFaTfko](https://www.youtube.com/watch?v=OH7UJFaTfko), [JtmoqvUmzq0](https://www.youtube.com/watch?v=JtmoqvUmzq0), [2JrcV2E7L1Y](https://www.youtube.com/watch?v=2JrcV2E7L1Y), [ez6ZCM5kMgY](https://www.youtube.com/watch?v=ez6ZCM5kMgY), [1sJ3pgnTdso](https://www.youtube.com/watch?v=1sJ3pgnTdso), [cNTl_x_cnS8](https://www.youtube.com/watch?v=cNTl_x_cnS8), [15CCl7Osv8Y](https://www.youtube.com/watch?v=15CCl7Osv8Y)
+
+### Conversion SEO
+- Measure SEO by qualified leads and revenue outcomes, not only rankings or traffic.
+- Recurring terms to inspect in related work: seo, google, https, heytony, audit, com, business, customers.
+- Source videos: [CduVCb9By1k](https://www.youtube.com/watch?v=CduVCb9By1k), [Jj_S37QBYtU](https://www.youtube.com/watch?v=Jj_S37QBYtU), [OH7UJFaTfko](https://www.youtube.com/watch?v=OH7UJFaTfko), [ez6ZCM5kMgY](https://www.youtube.com/watch?v=ez6ZCM5kMgY), [Sd27zXjfqTo](https://www.youtube.com/watch?v=Sd27zXjfqTo), [1sJ3pgnTdso](https://www.youtube.com/watch?v=1sJ3pgnTdso), [3rBfJagQT24](https://www.youtube.com/watch?v=3rBfJagQT24), [cNTl_x_cnS8](https://www.youtube.com/watch?v=cNTl_x_cnS8)
+
+### General SEO
+- Turn each SEO recommendation into a concrete page, content, or technical change that can be verified.
+- Recurring terms to inspect in related work: seo, google, rank, website, don, free, business, doing.
+- Source videos: [LcusOQdYsk4](https://www.youtube.com/watch?v=LcusOQdYsk4), [Z2M2wTvSACc](https://www.youtube.com/watch?v=Z2M2wTvSACc), [GQjfS6m1noc](https://www.youtube.com/watch?v=GQjfS6m1noc), [4PhZ0j9XyZU](https://www.youtube.com/watch?v=4PhZ0j9XyZU), [XSxU3U9TfPg](https://www.youtube.com/watch?v=XSxU3U9TfPg), [stQP8dIzf50](https://www.youtube.com/watch?v=stQP8dIzf50), [vmFRkaIn3n4](https://www.youtube.com/watch?v=vmFRkaIn3n4), [yr8VokbcCJE](https://www.youtube.com/watch?v=yr8VokbcCJE)
+
+### Local SEO
+- Tie local SEO work to calls, reviews, service-area relevance, and Google Business Profile trust signals.
+- Recurring terms to inspect in related work: seo, heytony, google, https, audit, business, com, local.
+- Source videos: [Jj_S37QBYtU](https://www.youtube.com/watch?v=Jj_S37QBYtU), [ez6ZCM5kMgY](https://www.youtube.com/watch?v=ez6ZCM5kMgY), [Sd27zXjfqTo](https://www.youtube.com/watch?v=Sd27zXjfqTo), [3rBfJagQT24](https://www.youtube.com/watch?v=3rBfJagQT24), [15CCl7Osv8Y](https://www.youtube.com/watch?v=15CCl7Osv8Y), [GG-uUzzkf-s](https://www.youtube.com/watch?v=GG-uUzzkf-s), [1dzTGLd5o9s](https://www.youtube.com/watch?v=1dzTGLd5o9s), [vr_LgnOq4tw](https://www.youtube.com/watch?v=vr_LgnOq4tw)
+
+### Programmatic SEO
+- Use repeatable templates only when each page has unique, useful data and a real search intent.
+- Recurring terms to inspect in related work: seo, https, business, heytony, audit, com, here, local.
+- Source videos: [RXxEWOVxmaM](https://www.youtube.com/watch?v=RXxEWOVxmaM), [Lpp5QdHFk80](https://www.youtube.com/watch?v=Lpp5QdHFk80), [UbCIxwN-nuY](https://www.youtube.com/watch?v=UbCIxwN-nuY), [opq02e3crQs](https://www.youtube.com/watch?v=opq02e3crQs), [MXMkQQp1mwc](https://www.youtube.com/watch?v=MXMkQQp1mwc), [TQy39akurjI](https://www.youtube.com/watch?v=TQy39akurjI), [nKP8gdVxYJk](https://www.youtube.com/watch?v=nKP8gdVxYJk), [7enXdUR3f80](https://www.youtube.com/watch?v=7enXdUR3f80)
+
+### Technical SEO
+- Fix crawlability, indexing, internal links, schema, and site structure before scaling content volume.
+- Recurring terms to inspect in related work: seo, google, com, https, website, heytony, audit, here.
+- Source videos: [OH7UJFaTfko](https://www.youtube.com/watch?v=OH7UJFaTfko), [2JrcV2E7L1Y](https://www.youtube.com/watch?v=2JrcV2E7L1Y), [Zfefiqwn8Cw](https://www.youtube.com/watch?v=Zfefiqwn8Cw), [x1dTCLdWs94](https://www.youtube.com/watch?v=x1dTCLdWs94), [2F-6cf-7HJQ](https://www.youtube.com/watch?v=2F-6cf-7HJQ), [mUNrRcnIn7Q](https://www.youtube.com/watch?v=mUNrRcnIn7Q), [pBAufJMSHtE](https://www.youtube.com/watch?v=pBAufJMSHtE), [vr_LgnOq4tw](https://www.youtube.com/watch?v=vr_LgnOq4tw)
+
+## Prompt Seeds
+
+- **It only took 6 months 😲**: Use the SEO lesson from 'It only took 6 months 😲' to audit a page for general seo. Return prioritized fixes, examples, and verification steps.
+- **SEO on easy mode 😲**: Use the SEO lesson from 'SEO on easy mode 😲' to audit a page for ai seo geo, content strategy, conversion seo. Return prioritized fixes, examples, and verification steps.
+- **Google loves these signals**: Use the SEO lesson from 'Google loves these signals' to audit a page for authority signals. Return prioritized fixes, examples, and verification steps.
+- **This will get your phone ringing 😲**: Use the SEO lesson from 'This will get your phone ringing 😲' to audit a page for local seo, conversion seo. Return prioritized fixes, examples, and verification steps.
+- **Their sales grew 500% 😲**: Use the SEO lesson from 'Their sales grew 500% 😲' to audit a page for ai seo geo, technical seo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **This is insane 🤯**: Use the SEO lesson from 'This is insane 🤯' to audit a page for content strategy, authority signals. Return prioritized fixes, examples, and verification steps.
+- **And he’s fully booked**: Use the SEO lesson from 'And he’s fully booked' to audit a page for ai seo geo, technical seo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **Why Your Google Reviews Are Disappearing (And How to Stop It)**: Use the SEO lesson from 'Why Your Google Reviews Are Disappearing (And How to Stop It)' to audit a page for local seo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **You’re likely doing this right now…**: Use the SEO lesson from 'You’re likely doing this right now…' to audit a page for local seo, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **Forget SEO**: Use the SEO lesson from 'Forget SEO' to audit a page for content strategy, conversion seo. Return prioritized fixes, examples, and verification steps.
+- **This is BS**: Use the SEO lesson from 'This is BS' to audit a page for local seo, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **He knows NOTHING about SEO 😲**: Use the SEO lesson from 'He knows NOTHING about SEO 😲' to audit a page for ai seo geo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **Get More Leads From Google. 1 Hour a Week.**: Use the SEO lesson from 'Get More Leads From Google. 1 Hour a Week.' to audit a page for ai seo geo, local seo, content strategy, conversion seo. Return prioritized fixes, examples, and verification steps.
+- **SEO is a lot faster and easier than you think!**: Use the SEO lesson from 'SEO is a lot faster and easier than you think!' to audit a page for ai seo geo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **Anyone can do this 😲**: Use the SEO lesson from 'Anyone can do this 😲' to audit a page for technical seo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **This site just broke Google 😲**: Use the SEO lesson from 'This site just broke Google 😲' to audit a page for ai seo geo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **FORCE Google to rank your site**: Use the SEO lesson from 'FORCE Google to rank your site' to audit a page for content strategy. Return prioritized fixes, examples, and verification steps.
+- **He promised not to get mad 🤣**: Use the SEO lesson from 'He promised not to get mad 🤣' to audit a page for content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **He knows NOTHING about SEO 🤯**: Use the SEO lesson from 'He knows NOTHING about SEO 🤯' to audit a page for ai seo geo, content strategy, conversion seo, authority signals. Return prioritized fixes, examples, and verification steps.
+- **I’m ditching ChatGPT omg**: Use the SEO lesson from 'I’m ditching ChatGPT omg' to audit a page for ai seo geo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **Why is no one talking about this?**: Use the SEO lesson from 'Why is no one talking about this?' to audit a page for content strategy, authority signals. Return prioritized fixes, examples, and verification steps.
+- **The best ChatGPT prompt ever?**: Use the SEO lesson from 'The best ChatGPT prompt ever?' to audit a page for ai seo geo. Return prioritized fixes, examples, and verification steps.
+- **Do you remember this ad?**: Use the SEO lesson from 'Do you remember this ad?' to audit a page for general seo. Return prioritized fixes, examples, and verification steps.
+- **Set up ChatGPT tracking in GA4 (google analytics)**: Use the SEO lesson from 'Set up ChatGPT tracking in GA4 (google analytics)' to audit a page for ai seo geo. Return prioritized fixes, examples, and verification steps.
+- **How to submit your sitemap on google search console**: Use the SEO lesson from 'How to submit your sitemap on google search console' to audit a page for technical seo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **10x your website traffic for free**: Use the SEO lesson from '10x your website traffic for free' to audit a page for technical seo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **This isn’t cheating, it’s just smart.**: Use the SEO lesson from 'This isn’t cheating, it’s just smart.' to audit a page for local seo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **You can’t unlearn this**: Use the SEO lesson from 'You can’t unlearn this' to audit a page for authority signals. Return prioritized fixes, examples, and verification steps.
+- **Should we be scared?**: Use the SEO lesson from 'Should we be scared?' to audit a page for conversion seo. Return prioritized fixes, examples, and verification steps.
+- **Google just DESTROYED ChatGPT**: Use the SEO lesson from 'Google just DESTROYED ChatGPT' to audit a page for ai seo geo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **This works too well**: Use the SEO lesson from 'This works too well' to audit a page for general seo. Return prioritized fixes, examples, and verification steps.
+- **ChatGPT is launching ads… here’s what you need to know.**: Use the SEO lesson from 'ChatGPT is launching ads… here’s what you need to know.' to audit a page for ai seo geo. Return prioritized fixes, examples, and verification steps.
+- **Force Google to know about your site**: Use the SEO lesson from 'Force Google to know about your site' to audit a page for technical seo. Return prioritized fixes, examples, and verification steps.
+- **Canva just destroyed Photoshop**: Use the SEO lesson from 'Canva just destroyed Photoshop' to audit a page for ai seo geo, content strategy. Return prioritized fixes, examples, and verification steps.
+- **It’s kind of scary**: Use the SEO lesson from 'It’s kind of scary' to audit a page for content strategy. Return prioritized fixes, examples, and verification steps.