geo-ai-search-optimization 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# geo-ai-search-optimization
+
+Install and run a production-ready Codex skill for GEO-first, SEO-supported website optimization.
+
+## Install
+
+```bash
+npm install -g geo-ai-search-optimization
+```
+
+Or run it without a permanent install:
+
+```bash
+npx geo-ai-search-optimization
+```
+
+## What it does
+
+- installs the bundled `geo-ai-search-optimization` skill into your Codex skills directory
+- ships a local resource folder with `SKILL.md`, references, and a scanner script
+- provides a CLI for installing, locating, and scanning projects for GEO signals
+
+## Commands
+
+```bash
+geo-ai-search-optimization
+geo-ai-search-optimization install
+geo-ai-search-optimization where
+geo-ai-search-optimization scan ./my-site
+geo-ai-search-optimization help
+```
+
+## Install location
+
+By default the skill is installed to:
+
+- macOS / Linux: `~/.codex/skills/geo-ai-search-optimization`
+- Windows: `%USERPROFILE%\\.codex\\skills\\geo-ai-search-optimization`
+
+Override with:
+
+- `CODEX_HOME`
+- `CODEX_SKILLS_DIR`
+- `GEO_SKILL_INSTALL_DIR`
+
+## Resource contents
+
+The installed skill includes:
+
+- `SKILL.md`
+- `agents/openai.yaml`
+- `references/geo-playbook.md`
+- `references/implementation-checklist.md`
+- `scripts/scan-geo-signals.mjs`
+
+## License
+
+MIT

package/bin/geo-ai-search-optimization.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+try {
+  await runCli(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`geo-ai-search-optimization: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "geo-ai-search-optimization",
+  "version": "1.0.0",
+  "description": "Install and run a GEO-first, SEO-supported Codex skill for AI search optimization.",
+  "type": "module",
+  "bin": {
+    "geo-ai-search-optimization": "bin/geo-ai-search-optimization.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "resources",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node ./src/postinstall.js",
+    "check": "node ./src/cli.js --help",
+    "scan:self": "node ./src/cli.js scan ./resources/geo-ai-search-optimization"
+  },
+  "keywords": [
+    "geo",
+    "seo",
+    "ai-search",
+    "answer-engine-optimization",
+    "codex-skill",
+    "chatgpt",
+    "perplexity",
+    "gemini"
+  ],
+  "license": "MIT"
+}

package/resources/geo-ai-search-optimization/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: geo-ai-search-optimization
+description: Optimize websites for GEO-first, SEO-supported visibility in AI-powered search and answer engines. Use when Codex needs to audit or improve a website, content system, landing page, blog, docs site, ecommerce catalog, or local business presence for ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews, generative engine optimization, answer-engine optimization, AI search discoverability, structured data, citation readiness, or SEO work that must prioritize AI-driven discovery.
+---
+
+# GEO AI Search Optimization
+
+Optimize for where search traffic is moving: answer engines, AI overviews, and citation-heavy assistants. Preserve classic SEO foundations, but prioritize answerability, source quality, entity clarity, and crawlable evidence.
+
+## Core Positioning
+
+Treat GEO as the primary objective and SEO as the support layer.
+
+Use this skill to:
+
+- audit an existing site or repo for AI-search readiness
+- rewrite pages so they are easier for models to quote, summarize, and cite
+- plan new content systems around questions, entities, proof, and comparisons
+- implement technical supports such as schema, canonicals, robots, sitemaps, authorship, and citation surfaces
+
+Do not optimize for keyword stuffing, thin FAQ spam, doorway pages, fake expertise, or generic AI-generated filler.
+
+## Workflow
+
+### 1. Classify the task
+
+Choose one primary mode before making recommendations:
+
+- `audit`: inspect an existing site, codebase, or exported HTML
+- `rewrite`: improve one or more pages for answer-engine visibility
+- `build`: create a GEO content plan, template system, or implementation brief
+- `measure`: define observable signals, KPIs, and change tracking
+
+If the user gives both content and code, start with `audit`, then branch into `rewrite` or `build`.
+
+### 2. Establish the evidence surface
+
+Look for the assets that make answers trustworthy and quotable:
+
+- named entities: brand, product, person, company, location, category
+- explicit claims: pricing, specs, definitions, comparisons, policies, methodology
+- first-party evidence: research, data, benchmarks, screenshots, customer examples, case studies
+- source transparency: dates, authors, reviewers, citations, outbound references
+
+If these are weak, say so clearly. AI-search performance often fails because there is nothing distinctive to cite.
+
+### 3. Check technical foundations
+
+Confirm the site is easy to crawl, interpret, and attribute:
+
+- indexable and canonical URLs
+- sensible internal linking and stable information architecture
+- `robots.txt`, sitemap support, and predictable URL patterns
+- strong titles, descriptions, headings, and on-page summaries
+- JSON-LD or equivalent structured data where it helps disambiguation
+- visible authorship, freshness, and organization identity
+
+For repo-based work, run the local scanner first:
+
+```bash
+node scripts/scan-geo-signals.mjs /path/to/project
+```
+
+Or, if the npm package is available:
+
+```bash
+npx geo-ai-search-optimization scan /path/to/project
+```
+
+Use the scanner output as a starting map, not as the final judgment.
+
+### 4. Improve answerability before chasing rankings
+
+Restructure content so a model can extract a high-confidence answer quickly:
+
+- put the direct answer near the top
+- define the entity before expanding on it
+- use specific headings that mirror real user questions
+- add short summary blocks, comparison tables, pros and cons, and decision criteria
+- include citations or clear sourcing for non-obvious claims
+- separate facts, opinions, and marketing language
+
+When useful, add FAQ, glossary, alternatives, comparison, methodology, statistics, or policy sections. Prefer dense, useful blocks over long intros.
+
+### 5. Strengthen citation readiness
+
+Increase the chance that answer engines can quote or paraphrase accurately:
+
+- attribute content to real experts, teams, or organizations
+- expose original data, unique process details, or product-specific knowledge
+- link to primary or authoritative sources when claims are not first-party
+- add `sameAs`, organization, author, article, FAQ, product, local business, or breadcrumb schema when relevant
+- make dates, update cadence, and version context explicit
+
+If content sounds interchangeable with competitors, call that out and recommend a stronger point of view or original evidence.
+
+### 6. Produce prioritized output
+
+Always return recommendations in this order:
+
+1. blockers: issues that prevent crawlability, attribution, or answer extraction
+2. high-impact GEO fixes: changes that improve answerability and citation probability
+3. SEO support fixes: enhancements that reinforce discoverability and consistency
+4. experiments: optional tests such as new page types, FAQ expansions, or comparison hubs
+
+Prefer a short implementation backlog with owner-ready tasks over a long essay.
+
+## Common Deliverables
+
+### Audit deliverable
+
+Return:
+
+- current state summary
+- strongest citation assets already present
+- missing trust or structure signals
+- prioritized fixes by effort and impact
+
+Read [references/implementation-checklist.md](references/implementation-checklist.md) when you need a fuller checklist.
+
+### Rewrite deliverable
+
+For page rewrites:
+
+- preserve factual accuracy
+- tighten the opening into a direct answer
+- add definitions, evidence, and question-led subheads
+- surface author, reviewer, date, and source notes when possible
+- keep the page useful for humans first
+
+Read [references/geo-playbook.md](references/geo-playbook.md) when you need content patterns.
+
+### Build deliverable
+
+For new systems, propose:
+
+- page templates by intent
+- schema plan by page type
+- evidence collection workflow
+- editorial rules for freshness, citations, and entity consistency
+- measurement plan tied to both AI-search and traditional SEO outcomes
+
+## Execution Notes
+
+When the user asks for a codebase implementation:
+
+- inspect templates, layouts, metadata helpers, routing, and schema generation points
+- modify reusable primitives instead of patching one page at a time when possible
+- add examples for the highest-value page type first
+
+When the user asks for strategic recommendations:
+
+- anchor every recommendation to a page type, entity, or evidence gap
+- avoid broad advice like "publish better content" without specifying the format and missing proof
+
+When the user asks for the latest vendor behavior or policy:
+
+- verify with current primary sources before making claims about Google AI Overviews, ChatGPT, Gemini, Claude, Perplexity, or schema support
+
+## Bundled Resources
+
+- `scripts/scan-geo-signals.mjs`: local scanner for crawlability, schema, answerability, and citation signals
+- `references/geo-playbook.md`: content patterns and GEO-first page design heuristics
+- `references/implementation-checklist.md`: technical, content, and measurement checklist

package/resources/geo-ai-search-optimization/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO for AI Search"
+  short_description: "Optimize sites for AI search and GEO workflows"
+  default_prompt: "Use $geo-ai-search-optimization to audit this site for AI-search discoverability and recommend GEO-first, SEO-supported fixes."

package/resources/geo-ai-search-optimization/references/geo-playbook.md

@@ -0,0 +1,130 @@
+# GEO Playbook
+
+## Table of Contents
+
+- Answer-engine content model
+- Page patterns that tend to travel into AI answers
+- Evidence patterns
+- Rewrite heuristics
+- Anti-patterns
+
+## Answer-engine content model
+
+Design pages so a model can answer four questions fast:
+
+1. What is this entity?
+2. Why should this source be trusted?
+3. What is the direct answer?
+4. What evidence supports the answer?
+
+Make those answers visible in the page structure, not buried in prose.
+
+## Page patterns that tend to travel into AI answers
+
+### Definition pages
+
+Use for category, concept, feature, or industry terminology.
+
+Include:
+
+- one-sentence definition near the top
+- who it is for
+- how it differs from adjacent concepts
+- short examples
+- linked deeper pages for workflow, pricing, or implementation
+
+### Comparison pages
+
+Use for `x vs y`, alternatives, replacement decisions, and buyer evaluation.
+
+Include:
+
+- explicit comparison criteria
+- table format when possible
+- ideal fit by segment or use case
+- known tradeoffs
+- update date if the market changes quickly
+
+### FAQ hubs
+
+Use only when questions are real and distinct.
+
+Include:
+
+- one direct answer per question
+- a short expansion paragraph
+- links to the canonical page for deeper detail
+
+Avoid manufacturing low-value questions just to increase count.
+
+### Methodology and research pages
+
+Use when the brand has original data or proprietary process knowledge.
+
+Include:
+
+- what was measured
+- date range
+- sample size or scope
+- method limitations
+- key findings in summary form
+
+These pages often provide the strongest citation material.
+
+### Local and service pages
+
+Use for businesses with geographic presence or service areas.
+
+Include:
+
+- exact service entity and location
+- operating area, hours, contact, and service constraints
+- proof such as certifications, case studies, reviews, or before/after artifacts
+- local business and organization identity signals
+
+## Evidence patterns
+
+Prefer evidence in this order:
+
+1. first-party data or product truth
+2. primary sources
+3. authoritative secondary summaries
+4. internal opinion clearly labeled as opinion
+
+Useful evidence blocks:
+
+- benchmark tables
+- methodology notes
+- screenshots with captions
+- pricing details
+- implementation steps
+- quote blocks from identifiable experts
+- dated release or policy notes
+
+## Rewrite heuristics
+
+When rewriting a page, apply this sequence:
+
+1. Replace vague intros with a direct answer.
+2. Name the entity precisely.
+3. Add one distinctive fact, method, or constraint early.
+4. Break out question-led subheads.
+5. Add comparison, checklist, or table sections where helpful.
+6. Add explicit sourcing for non-obvious claims.
+7. End with next-step links to deeper pages.
+
+Good opening pattern:
+
+`[Entity] is [short definition]. It is best for [audience/use case]. The main tradeoff is [constraint].`
+
+## Anti-patterns
+
+Avoid:
+
+- keyword-stuffed headings
+- faceless articles with no author or owner
+- listicles with no unique evidence
+- copy that hides the answer behind long brand storytelling
+- duplicated pages targeting tiny wording variations
+- unsupported superlatives such as "best" or "most accurate"
+- fake FAQ schema for questions not visible on the page

package/resources/geo-ai-search-optimization/references/implementation-checklist.md

@@ -0,0 +1,75 @@
+# GEO Implementation Checklist
+
+## Table of Contents
+
+- Technical foundations
+- Content and entity layer
+- Structured data and attribution
+- Measurement
+
+## Technical foundations
+
+Check:
+
+- canonical URLs exist and point to the preferred version
+- robots rules do not block important pages
+- sitemap or sitemap generation exists
+- page titles and meta descriptions are defined at scale
+- heading hierarchy is readable and specific
+- internal links connect summaries to deeper canonical pages
+- duplicate or near-duplicate routes are controlled
+- important pages are server-rendered or otherwise accessible to crawlers
+
+## Content and entity layer
+
+Check:
+
+- each target page has one primary entity or decision topic
+- the direct answer appears in the first screenful
+- claims are tied to facts, examples, or sources
+- authorship or responsible organization is visible
+- freshness is visible through dates, version notes, or review notes
+- comparison, FAQ, glossary, or methodology sections exist when intent requires them
+- the page contains at least one piece of first-party value competitors cannot easily copy
+
+## Structured data and attribution
+
+Use only the schema that matches the visible page content.
+
+Common candidates:
+
+- `Organization`
+- `WebSite`
+- `Person`
+- `Article`
+- `FAQPage`
+- `HowTo`
+- `Product`
+- `BreadcrumbList`
+- `LocalBusiness`
+
+Also check:
+
+- `sameAs` links for organization or person entities when appropriate
+- author or publisher details on article-like content
+- product attributes that reflect the actual offer
+- breadcrumb markup aligned with site structure
+
+## Measurement
+
+Track both AI-search and classic SEO outcomes.
+
+Suggested measures:
+
+- impressions and clicks from traditional search
+- branded and non-branded query coverage
+- referral traffic from AI/search assistants when observable
+- growth in pages that earn citations, mentions, or backlinks
+- engagement on comparison, FAQ, glossary, and methodology pages
+- faster content production for answer-focused templates
+
+For implementation backlogs, tag each item with:
+
+- impact: `blocker`, `high`, `medium`, `low`
+- type: `technical`, `content`, `schema`, `measurement`
+- owner: engineering, content, SEO, product marketing, or subject-matter expert

package/resources/geo-ai-search-optimization/scripts/scan-geo-signals.mjs

@@ -0,0 +1,254 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const TEXT_EXTENSIONS = new Set([
+  ".astro",
+  ".html",
+  ".htm",
+  ".js",
+  ".jsx",
+  ".liquid",
+  ".md",
+  ".mdx",
+  ".mjs",
+  ".njk",
+  ".php",
+  ".svelte",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".vue"
+]);
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "tmp",
+  "vendor"
+]);
+
+const SIGNAL_PATTERNS = {
+  title: /<title\b|metadata\s*[:=]\s*\{|title\s*:\s*['"]/i,
+  meta_description: /name=["']description["']|description\s*:\s*["']/i,
+  canonical: /rel=["']canonical["']|canonical\s*:\s*["']|alternates\s*:\s*\{/i,
+  json_ld: /application\/ld\+json|schema\.org/i,
+  faq_schema: /@type["']?\s*[:=]\s*["']FAQPage["']|schema\.org\/FAQPage/i,
+  howto_schema: /@type["']?\s*[:=]\s*["']HowTo["']|schema\.org\/HowTo/i,
+  article_schema:
+    /@type["']?\s*[:=]\s*["'](Article|BlogPosting|NewsArticle)["']|schema\.org\/(Article|BlogPosting|NewsArticle)/i,
+  organization_schema:
+    /@type["']?\s*[:=]\s*["'](Organization|Corporation|LocalBusiness)["']|schema\.org\/(Organization|Corporation|LocalBusiness)/i,
+  product_schema:
+    /@type["']?\s*[:=]\s*["'](Product|SoftwareApplication)["']|schema\.org\/(Product|SoftwareApplication)/i,
+  breadcrumb_schema:
+    /@type["']?\s*[:=]\s*["']BreadcrumbList["']|schema\.org\/BreadcrumbList/i,
+  author_markers: /\bauthor\b|\breviewed by\b|\bpublisher\b|\bdatePublished\b|\bdateModified\b/i,
+  qa_headings: /^(#{1,6}\s+.+\?)|(<h[1-6][^>]*>.*\?.*<\/h[1-6]>)/im,
+  comparison_intent: /\b(vs\.?|versus|alternative to|alternatives to|compare)\b/i,
+  original_research: /\b(benchmark|survey|study|dataset|methodology|research|report)\b/i,
+  citations: /https?:\/\//i
+};
+
+async function collectFiles(root) {
+  const files = [];
+  const queue = [root];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name)) {
+          queue.push(entryPath);
+        }
+        continue;
+      }
+
+      const extension = path.extname(entry.name).toLowerCase();
+      if (TEXT_EXTENSIONS.has(extension) || entry.name === "robots.txt" || entry.name === "llms.txt") {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+async function readText(filePath, maxFileSize) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (stat.size > maxFileSize) {
+      return "";
+    }
+    return await fs.readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function buildRecommendations(summary) {
+  const recommendations = [];
+  const { signals, specialFiles } = summary;
+
+  if (specialFiles.robotsTxt.length === 0) {
+    recommendations.push("Add or verify robots.txt so crawlers and answer engines see clear crawl rules.");
+  }
+  if (specialFiles.sitemap.length === 0) {
+    recommendations.push("Add a sitemap or sitemap generator to expose canonical URLs at scale.");
+  }
+  if (signals.canonical.count === 0) {
+    recommendations.push("Implement canonical tags or metadata helpers to reduce duplicate URL ambiguity.");
+  }
+  if (signals.json_ld.count === 0) {
+    recommendations.push("Add visible, page-matching structured data to improve entity disambiguation and citation confidence.");
+  }
+  if (signals.author_markers.count === 0) {
+    recommendations.push("Expose authorship, reviewer, publisher, or update metadata on advice pages.");
+  }
+  if (signals.qa_headings.count === 0) {
+    recommendations.push("Introduce question-led headings or FAQ sections on pages with informational intent.");
+  }
+  if (signals.citations.count === 0) {
+    recommendations.push("Add source links for non-obvious claims, benchmarks, or market statements.");
+  }
+  if (signals.original_research.count === 0) {
+    recommendations.push("Create at least one methodology, benchmark, or first-party evidence page that competitors cannot easily copy.");
+  }
+  if (signals.comparison_intent.count === 0) {
+    recommendations.push("Consider comparison or alternatives pages if you compete in a crowded category.");
+  }
+
+  return recommendations;
+}
+
+async function scanProject(rootInput, options = {}) {
+  const root = path.resolve(rootInput);
+  const maxFileSize = options.maxFileSize || 1_000_000;
+  const maxExamples = options.maxExamples || 5;
+
+  const stat = await fs.stat(root).catch(() => null);
+  if (!stat) {
+    throw new Error(`Path not found: ${root}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`Path is not a directory: ${root}`);
+  }
+
+  const files = await collectFiles(root);
+  const counts = Object.fromEntries(Object.keys(SIGNAL_PATTERNS).map((key) => [key, 0]));
+  const examples = Object.fromEntries(Object.keys(SIGNAL_PATTERNS).map((key) => [key, []]));
+  const specialFiles = {
+    robotsTxt: [],
+    sitemap: [],
+    llmsTxt: []
+  };
+
+  let filesScanned = 0;
+
+  for (const filePath of files) {
+    const relativePath = path.relative(root, filePath);
+    const baseName = path.basename(filePath).toLowerCase();
+
+    if (baseName === "robots.txt") {
+      specialFiles.robotsTxt.push(relativePath);
+    }
+    if (baseName === "llms.txt") {
+      specialFiles.llmsTxt.push(relativePath);
+    }
+    if (baseName.includes("sitemap")) {
+      specialFiles.sitemap.push(relativePath);
+    }
+
+    const content = await readText(filePath, maxFileSize);
+    if (!content) {
+      continue;
+    }
+
+    filesScanned += 1;
+
+    for (const [signal, pattern] of Object.entries(SIGNAL_PATTERNS)) {
+      if (pattern.test(content)) {
+        counts[signal] += 1;
+        if (examples[signal].length < maxExamples) {
+          examples[signal].push(relativePath);
+        }
+      }
+    }
+  }
+
+  const summary = {
+    root,
+    filesConsidered: files.length,
+    filesScanned,
+    specialFiles,
+    signals: Object.fromEntries(
+      Object.keys(SIGNAL_PATTERNS).map((signal) => [
+        signal,
+        {
+          count: counts[signal],
+          examples: examples[signal]
+        }
+      ])
+    )
+  };
+
+  summary.recommendations = buildRecommendations(summary);
+  return summary;
+}
+
+function renderScanMarkdown(summary) {
+  const lines = [
+    "# GEO Signal Scan",
+    "",
+    `- Root: \`${summary.root}\``,
+    `- Files considered: \`${summary.filesConsidered}\``,
+    `- Files scanned as text: \`${summary.filesScanned}\``,
+    "",
+    "## Foundations",
+    "",
+    `- robots.txt: \`${summary.specialFiles.robotsTxt.join(", ") || "missing"}\``,
+    `- sitemap: \`${summary.specialFiles.sitemap.join(", ") || "missing"}\``,
+    `- llms.txt: \`${summary.specialFiles.llmsTxt.join(", ") || "not found"}\``,
+    "",
+    "## Signal Counts",
+    ""
+  ];
+
+  for (const [signal, details] of Object.entries(summary.signals)) {
+    const exampleText = details.examples.join(", ") || "none";
+    lines.push(`- ${signal}: \`${details.count}\` example(s): \`${exampleText}\``);
+  }
+
+  lines.push("", "## Recommended Next Moves", "");
+
+  if (summary.recommendations.length === 0) {
+    lines.push("- No obvious blockers detected by heuristics. Review page quality and evidence depth next.");
+  } else {
+    for (const recommendation of summary.recommendations) {
+      lines.push(`- ${recommendation}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+const [target = ".", ...flags] = process.argv.slice(2);
+const outputJson = flags.includes("--json");
+const summary = await scanProject(target);
+
+if (outputJson) {
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+} else {
+  process.stdout.write(renderScanMarkdown(summary));
+}

package/src/cli.js

@@ -0,0 +1,101 @@
+import { installSkill } from "./install-skill.js";
+import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
+import { renderScanMarkdown, scanProject } from "./scan.js";
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+let cachedVersion;
+
+async function getPackageVersion() {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+
+  const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+  const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+  cachedVersion = packageJson.version;
+  return cachedVersion;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      "geo-ai-search-optimization",
+      "",
+      "Usage:",
+      "  geo-ai-search-optimization",
+      "  geo-ai-search-optimization install",
+      "  geo-ai-search-optimization where",
+      "  geo-ai-search-optimization scan <project-path> [--json]",
+      "  geo-ai-search-optimization version",
+      "  geo-ai-search-optimization help",
+      "",
+      "Environment overrides:",
+      "  CODEX_HOME",
+      "  CODEX_SKILLS_DIR",
+      "  GEO_SKILL_INSTALL_DIR",
+      "  GEO_SKILL_SKIP_POSTINSTALL"
+    ].join("\n") + "\n"
+  );
+}
+
+export async function runCli(args = []) {
+  const [command = "install", ...rest] = args;
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    process.stdout.write(`${await getPackageVersion()}\n`);
+    return;
+  }
+
+  if (command === "install") {
+    await installSkill();
+    return;
+  }
+
+  if (command === "where") {
+    process.stdout.write(
+      [
+        `skill: ${getSkillName()}`,
+        `bundled: ${getBundledSkillPath()}`,
+        `skillsDir: ${getSkillsDir()}`,
+        `installed: ${getInstalledSkillPath()}`
+      ].join("\n") + "\n"
+    );
+    return;
+  }
+
+  if (command === "scan") {
+    const projectPath = rest.find((value) => !value.startsWith("-"));
+    if (!projectPath) {
+      throw new Error("scan requires a project path");
+    }
+
+    const outputJson = rest.includes("--json");
+    const summary = await scanProject(projectPath);
+    if (outputJson) {
+      process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+    } else {
+      process.stdout.write(renderScanMarkdown(summary));
+    }
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+const isDirectRun = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isDirectRun) {
+  try {
+    await runCli(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`geo-ai-search-optimization: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { installSkill } from "./install-skill.js";
+export { runCli } from "./cli.js";
+export { scanProject, renderScanMarkdown } from "./scan.js";

package/src/install-skill.js

@@ -0,0 +1,49 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getBundledSkillPath, getInstalledSkillPath, getSkillName } from "./paths.js";
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function installSkill(options = {}) {
+  const sourceDir = getBundledSkillPath();
+  const targetDir = options.targetDir || getInstalledSkillPath();
+  const silent = Boolean(options.silent);
+
+  if (!(await pathExists(sourceDir))) {
+    throw new Error(`Bundled skill folder not found: ${sourceDir}`);
+  }
+
+  await fs.mkdir(path.dirname(targetDir), { recursive: true });
+  await fs.rm(targetDir, { recursive: true, force: true });
+  await fs.cp(sourceDir, targetDir, { recursive: true, force: true });
+
+  const manifest = {
+    skill: getSkillName(),
+    installedAt: new Date().toISOString(),
+    installedFrom: sourceDir,
+    packageName: "geo-ai-search-optimization"
+  };
+
+  await fs.writeFile(
+    path.join(targetDir, ".installed-by-npm.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8"
+  );
+
+  if (!silent) {
+    process.stdout.write(`Installed ${getSkillName()} to ${targetDir}\n`);
+  }
+
+  return {
+    targetDir,
+    sourceDir,
+    skillName: getSkillName()
+  };
+}

package/src/paths.js

@@ -0,0 +1,33 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RESOURCE_SKILL_NAME = "geo-ai-search-optimization";
+
+export function getPackageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function getBundledSkillPath() {
+  return path.join(getPackageRoot(), "resources", RESOURCE_SKILL_NAME);
+}
+
+export function getCodexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+
+export function getSkillsDir() {
+  return (
+    process.env.GEO_SKILL_INSTALL_DIR ||
+    process.env.CODEX_SKILLS_DIR ||
+    path.join(getCodexHome(), "skills")
+  );
+}
+
+export function getInstalledSkillPath() {
+  return path.join(getSkillsDir(), RESOURCE_SKILL_NAME);
+}
+
+export function getSkillName() {
+  return RESOURCE_SKILL_NAME;
+}

package/src/postinstall.js

@@ -0,0 +1,12 @@
+import { installSkill } from "./install-skill.js";
+
+if (process.env.GEO_SKILL_SKIP_POSTINSTALL === "1") {
+  process.exit(0);
+}
+
+try {
+  await installSkill({ silent: true });
+  process.stdout.write("geo-ai-search-optimization: bundled skill installed\n");
+} catch (error) {
+  process.stderr.write(`geo-ai-search-optimization: postinstall skipped (${error.message})\n`);
+}

package/src/scan.js

@@ -0,0 +1,244 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const TEXT_EXTENSIONS = new Set([
+  ".astro",
+  ".html",
+  ".htm",
+  ".js",
+  ".jsx",
+  ".liquid",
+  ".md",
+  ".mdx",
+  ".mjs",
+  ".njk",
+  ".php",
+  ".svelte",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".vue"
+]);
+
+const IGNORE_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "tmp",
+  "vendor"
+]);
+
+const SIGNAL_PATTERNS = {
+  title: /<title\b|metadata\s*[:=]\s*\{|title\s*:\s*['"]/i,
+  meta_description: /name=["']description["']|description\s*:\s*["']/i,
+  canonical: /rel=["']canonical["']|canonical\s*:\s*["']|alternates\s*:\s*\{/i,
+  json_ld: /application\/ld\+json|schema\.org/i,
+  faq_schema: /@type["']?\s*[:=]\s*["']FAQPage["']|schema\.org\/FAQPage/i,
+  howto_schema: /@type["']?\s*[:=]\s*["']HowTo["']|schema\.org\/HowTo/i,
+  article_schema:
+    /@type["']?\s*[:=]\s*["'](Article|BlogPosting|NewsArticle)["']|schema\.org\/(Article|BlogPosting|NewsArticle)/i,
+  organization_schema:
+    /@type["']?\s*[:=]\s*["'](Organization|Corporation|LocalBusiness)["']|schema\.org\/(Organization|Corporation|LocalBusiness)/i,
+  product_schema:
+    /@type["']?\s*[:=]\s*["'](Product|SoftwareApplication)["']|schema\.org\/(Product|SoftwareApplication)/i,
+  breadcrumb_schema:
+    /@type["']?\s*[:=]\s*["']BreadcrumbList["']|schema\.org\/BreadcrumbList/i,
+  author_markers: /\bauthor\b|\breviewed by\b|\bpublisher\b|\bdatePublished\b|\bdateModified\b/i,
+  qa_headings: /^(#{1,6}\s+.+\?)|(<h[1-6][^>]*>.*\?.*<\/h[1-6]>)/im,
+  comparison_intent: /\b(vs\.?|versus|alternative to|alternatives to|compare)\b/i,
+  original_research: /\b(benchmark|survey|study|dataset|methodology|research|report)\b/i,
+  citations: /https?:\/\//i
+};
+
+async function collectFiles(root) {
+  const files = [];
+  const queue = [root];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const entries = await fs.readdir(current, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name)) {
+          queue.push(entryPath);
+        }
+        continue;
+      }
+
+      const extension = path.extname(entry.name).toLowerCase();
+      if (TEXT_EXTENSIONS.has(extension) || entry.name === "robots.txt" || entry.name === "llms.txt") {
+        files.push(entryPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+async function readText(filePath, maxFileSize) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (stat.size > maxFileSize) {
+      return "";
+    }
+    return await fs.readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function buildRecommendations(summary) {
+  const recommendations = [];
+  const { signals, specialFiles } = summary;
+
+  if (specialFiles.robotsTxt.length === 0) {
+    recommendations.push("Add or verify robots.txt so crawlers and answer engines see clear crawl rules.");
+  }
+  if (specialFiles.sitemap.length === 0) {
+    recommendations.push("Add a sitemap or sitemap generator to expose canonical URLs at scale.");
+  }
+  if (signals.canonical.count === 0) {
+    recommendations.push("Implement canonical tags or metadata helpers to reduce duplicate URL ambiguity.");
+  }
+  if (signals.json_ld.count === 0) {
+    recommendations.push("Add visible, page-matching structured data to improve entity disambiguation and citation confidence.");
+  }
+  if (signals.author_markers.count === 0) {
+    recommendations.push("Expose authorship, reviewer, publisher, or update metadata on advice pages.");
+  }
+  if (signals.qa_headings.count === 0) {
+    recommendations.push("Introduce question-led headings or FAQ sections on pages with informational intent.");
+  }
+  if (signals.citations.count === 0) {
+    recommendations.push("Add source links for non-obvious claims, benchmarks, or market statements.");
+  }
+  if (signals.original_research.count === 0) {
+    recommendations.push("Create at least one methodology, benchmark, or first-party evidence page that competitors cannot easily copy.");
+  }
+  if (signals.comparison_intent.count === 0) {
+    recommendations.push("Consider comparison or alternatives pages if you compete in a crowded category.");
+  }
+
+  return recommendations;
+}
+
+export async function scanProject(rootInput, options = {}) {
+  const root = path.resolve(rootInput);
+  const maxFileSize = options.maxFileSize || 1_000_000;
+  const maxExamples = options.maxExamples || 5;
+
+  const stat = await fs.stat(root).catch(() => null);
+  if (!stat) {
+    throw new Error(`Path not found: ${root}`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`Path is not a directory: ${root}`);
+  }
+
+  const files = await collectFiles(root);
+  const counts = Object.fromEntries(Object.keys(SIGNAL_PATTERNS).map((key) => [key, 0]));
+  const examples = Object.fromEntries(Object.keys(SIGNAL_PATTERNS).map((key) => [key, []]));
+  const specialFiles = {
+    robotsTxt: [],
+    sitemap: [],
+    llmsTxt: []
+  };
+
+  let filesScanned = 0;
+
+  for (const filePath of files) {
+    const relativePath = path.relative(root, filePath);
+    const baseName = path.basename(filePath).toLowerCase();
+
+    if (baseName === "robots.txt") {
+      specialFiles.robotsTxt.push(relativePath);
+    }
+    if (baseName === "llms.txt") {
+      specialFiles.llmsTxt.push(relativePath);
+    }
+    if (baseName.includes("sitemap")) {
+      specialFiles.sitemap.push(relativePath);
+    }
+
+    const content = await readText(filePath, maxFileSize);
+    if (!content) {
+      continue;
+    }
+
+    filesScanned += 1;
+
+    for (const [signal, pattern] of Object.entries(SIGNAL_PATTERNS)) {
+      if (pattern.test(content)) {
+        counts[signal] += 1;
+        if (examples[signal].length < maxExamples) {
+          examples[signal].push(relativePath);
+        }
+      }
+    }
+  }
+
+  const summary = {
+    root,
+    filesConsidered: files.length,
+    filesScanned,
+    specialFiles,
+    signals: Object.fromEntries(
+      Object.keys(SIGNAL_PATTERNS).map((signal) => [
+        signal,
+        {
+          count: counts[signal],
+          examples: examples[signal]
+        }
+      ])
+    )
+  };
+
+  summary.recommendations = buildRecommendations(summary);
+  return summary;
+}
+
+export function renderScanMarkdown(summary) {
+  const lines = [
+    "# GEO Signal Scan",
+    "",
+    `- Root: \`${summary.root}\``,
+    `- Files considered: \`${summary.filesConsidered}\``,
+    `- Files scanned as text: \`${summary.filesScanned}\``,
+    "",
+    "## Foundations",
+    "",
+    `- robots.txt: \`${summary.specialFiles.robotsTxt.join(", ") || "missing"}\``,
+    `- sitemap: \`${summary.specialFiles.sitemap.join(", ") || "missing"}\``,
+    `- llms.txt: \`${summary.specialFiles.llmsTxt.join(", ") || "not found"}\``,
+    "",
+    "## Signal Counts",
+    ""
+  ];
+
+  for (const [signal, details] of Object.entries(summary.signals)) {
+    const exampleText = details.examples.join(", ") || "none";
+    lines.push(`- ${signal}: \`${details.count}\` example(s): \`${exampleText}\``);
+  }
+
+  lines.push("", "## Recommended Next Moves", "");
+
+  if (summary.recommendations.length === 0) {
+    lines.push("- No obvious blockers detected by heuristics. Review page quality and evidence depth next.");
+  } else {
+    for (const recommendation of summary.recommendations) {
+      lines.push(`- ${recommendation}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}