seomd-cli 1.0.3 → 1.1.2

package/README.md

@@ -1,69 +1,164 @@
-# seomd-cli
+# SEO.md CLI
 
-The official command-line interface for the **SEO.md** open standard — AEO (AI Engine Optimization) infrastructure for technical founders.
+<p align="left" style="padding: 100px 0;">
+  <img alt="SEO.md CLI logo" src="./assets/logo.svg" />
+</p>
 
-Use the CLI to scaffold, validate, analyze, and synchronize `SEO.md` configuration files directly from your workspace.
+The official CLI for the [SEO.md](https://seomd.dev) open standard — AEO (AI Engine Optimization) infrastructure for technical founders.
 
----
+Use it to scaffold, validate, analyze, and sync `SEO.md` files directly from your repo.
 
-## Installation
+## Table of Contents
 
-Install the CLI globally using `npm`:
+- [Why SEO.md](#why-seomd)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Commands](#commands)
+- [Local Development](#local-development)
+- [Testing](#testing)
+- [Release Notes (Contributor Tagging)](#release-notes-contributor-tagging)
+- [Security](#security)
+- [Specification Reference](#specification-reference)
+- [License](#license)
+
+## Why SEO.md
+
+SEO.md is a structured, version-controlled specification for describing your site, intent queries, and pages so AI engines can cite you more often.
+
+- Declare what matters (site, identity, keywords, intent, pages)
+- Run audits via your connected platform
+- Write back `_analysis` blocks and per-page playbooks into your repo
+
+## Install
 
 ```bash
 npm install -g seomd-cli
 ```
 
----
+Verify:
+
+```bash
+seomd --help
+```
 
 ## Quick Start
 
-### 1. Initialize a Specification
-Run the interactive setup in the root of your project to generate a tailored `SEO.md` file:
+### 1) Initialize
+
+Run in the root of your project:
 
 ```bash
 seomd init
 ```
-The CLI will ask you five quick questions (e.g., brand name, domain, site type, primary keyword, and competitors) and scaffold the format matching your site type (SaaS, Blog, eCommerce, Marketplace, or Local).
 
-### 2. Validate the File
-Verify that your local file complies with the official open specification rules:
+### 2) Validate
 
 ```bash
 seomd validate
 ```
 
-### 3. Check Local Status
-Check validation state and connection parameters:
+### 3) Run an Audit (Analyze) and Sync
+
+```bash
+seomd analyze
+seomd sync
+```
+
+### 4) View Status
 
 ```bash
 seomd status
+seomd status --json
 ```
 
----
+## Configuration
 
-## Command Reference
+Copy the example env file:
+
+```bash
+cp .env.example .env
+```
+
+Environment variables:
+
+- `SEOMD_API_URL` (optional) API base URL (defaults to `https://api.foxcite.com`)
+- `SEOMD_API_KEY` (optional) platform API key (human dashboard auth)
+- `SEOMD_PAYMENT_TOKEN` (optional) agent-native payment token (x402 pay-per-scan)
+- `SEOMD_DOMAIN` (optional) override domain header
+
+## Commands
 
 ### `seomd init`
-Scaffolds a new `SEO.md` file in the current working directory.
+
+Scaffolds `SEO.md`, `SEO.REVERSE.md`, and the `.seomd/` intelligence directory.
 
 ### `seomd validate`
-Validates the structural integrity and required fields of your `SEO.md` file.
+
+Validates your `SEO.md` against the spec requirements.
 
 ### `seomd status`
-Displays local validation results, connected platforms, and project identification.
+
+Shows current citation rates and gap scores from `_analysis`.
+
+- `--json` outputs machine-readable JSON for scripts/CI
 
 ### `seomd analyze`
-Analyzes your local specification and requests search visibility summaries from your connected platform.
+
+Runs an AI search audit via your connected platform and writes results back into:
+
+- `SEO.md` (`_analysis` blocks)
+- `SEO.REVERSE.md` (generated reverse view)
+- `.seomd/pages/*.md` (per-page playbooks when available)
 
 ### `seomd sync`
-Synchronizes live engine analysis blocks, keyword gap scores, and cited sources from your connected writeback platform.
 
----
+Pulls cached/latest platform intelligence and writes it back to the same files as `analyze`.
+
+- `--dry-run` prints a preview and does not modify files
+
+## Local Development
+
+Prefer the local entrypoint while developing:
+
+```bash
+node ./bin/seomd.js --help
+node ./bin/seomd.js init
+node ./bin/seomd.js validate
+node ./bin/seomd.js status --json
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Release Notes (Contributor Tagging)
+
+To generate a contributor section for a release (commit-based attribution), maintain mappings in `.github/contributors.yml` and generate markdown from a tag range:
+
+```bash
+npm run release:contributors -- --from v1.0.2 --to v1.0.3
+```
+
+To write output to a file:
+
+```bash
+npm run release:contributors -- --from v1.0.2 --to v1.0.3 --out notes/v1.0.3-contributors.md
+```
+
+To generate a full release note (changes + contributors) for a tag:
+
+```bash
+npm run release:notes -- --tag v1.0.3
+```
+
+Automation: the repository includes a GitHub Actions workflow that runs on tag push (`v*`) and creates/updates the GitHub Release using `scripts/release-notes.js`.
 
 ## Platform Connections & API Keys
 
-To enable live citation writebacks (using automated platforms like [Foxcite](https://foxcite.com)):
+To enable live intelligence writebacks (using automated platforms like [Foxcite](https://foxcite.com)):
 
 1. Obtain a developer API key from your platform provider.
 2. Export the key as an environment variable:
@@ -72,9 +167,12 @@ To enable live citation writebacks (using automated platforms like [Foxcite](htt
    ```
 3. Run `seomd sync` or `seomd analyze`.
 
-*Note: Never commit your API keys or `.env` files containing keys to version control.*
+_Note: Never commit your API keys or `.env` files containing keys to version control._
+
+## Security
 
----
+- Never commit `.env` files or API keys
+- Use `.env.example` as the template for required variables
 
 ## Specification Reference
 

package/bin/seomd.js

@@ -32,6 +32,7 @@ program
     .description('Run citation analysis and write back _analysis blocks')
     .option('--page <url>', 'analyze a specific page only')
     .option('--intent <category>', 'analyze a specific intent category only')
+    .option('--engines <list>', 'comma-separated list of engines to scan (e.g. chatgpt,claude)')
     .action(analyzeCommand);
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "seomd-cli",
-    "version": "1.0.3",
+    "version": "1.1.2",
     "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
     "homepage": "https://seomd.dev",
     "repository": {
@@ -14,12 +14,15 @@
     },
     "files": [
         "bin",
+        "scripts",
         "src"
     ],
     "scripts": {
         "dev": "node bin/seomd.js",
         "test": "node --experimental-vm-modules node_modules/.bin/jest",
-        "lint": "eslint src/**/*.js"
+        "lint": "eslint src/**/*.js",
+        "release:contributors": "node scripts/release-contributors.js",
+        "release:notes": "node scripts/release-notes.js"
     },
     "dependencies": {
         "chalk": "^5.3.0",

package/scripts/release-contributors.js

@@ -0,0 +1,196 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import YAML from 'yaml';
+
+function parseArgs(argv) {
+    const out = { from: null, to: null, outFile: null };
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        if (arg === '--from' && next) {
+            out.from = next;
+            i += 1;
+        } else if (arg === '--to' && next) {
+            out.to = next;
+            i += 1;
+        } else if (arg === '--out' && next) {
+            out.outFile = next;
+            i += 1;
+        }
+    }
+    return out;
+}
+
+function readContributorsMap(repoRoot) {
+    const filePath = path.join(repoRoot, '.github', 'contributors.yml');
+    if (!fs.existsSync(filePath)) {
+        return { version: 1, contributors: [] };
+    }
+    const parsed = YAML.parse(fs.readFileSync(filePath, 'utf8')) || {};
+    return {
+        version: parsed.version || 1,
+        contributors: Array.isArray(parsed.contributors) ? parsed.contributors : []
+    };
+}
+
+function normalizeEmail(email) {
+    return String(email || '').trim().toLowerCase();
+}
+
+function normalizeName(name) {
+    return String(name || '').trim().toLowerCase();
+}
+
+function resolveHandle(map, { name, email }) {
+    const nEmail = normalizeEmail(email);
+    const nName = normalizeName(name);
+
+    for (const c of map.contributors) {
+        if (!c || typeof c !== 'object') continue;
+        if (!c.github) continue;
+        const emails = Array.isArray(c.emails) ? c.emails.map(normalizeEmail) : [];
+        if (nEmail && emails.includes(nEmail)) return c.github;
+        const names = Array.isArray(c.names) ? c.names.map(normalizeName) : [];
+        if (nName && names.includes(nName)) return c.github;
+    }
+    return null;
+}
+
+function git(repoRoot, args) {
+    return execSync(`git ${args}`, { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf8');
+}
+
+function getRepoRoot() {
+    return execSync('git rev-parse --show-toplevel', { stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function getCommitBodies(repoRoot, range) {
+    const sepCommit = '\u001e';
+    const sepField = '\u001f';
+    const out = git(repoRoot, `log ${range} --no-color --format=%H${sepField}%an${sepField}%ae${sepField}%B${sepCommit}`);
+    const rawCommits = out.split(sepCommit).map(s => s.trim()).filter(Boolean);
+    return rawCommits.map(entry => {
+        const parts = entry.split(sepField);
+        const [sha, authorName, authorEmail] = parts;
+        const body = parts.slice(3).join(sepField);
+        return { sha, authorName, authorEmail, body };
+    });
+}
+
+function extractCoAuthors(commitBody) {
+    const out = [];
+    const lines = String(commitBody || '').split('\n');
+    for (const line of lines) {
+        const m = line.match(/^Co-authored-by:\s*(.+?)\s*<(.+?)>\s*$/i);
+        if (m) out.push({ name: m[1], email: m[2] });
+    }
+    return out;
+}
+
+function bumpCounter(map, key, display) {
+    const existing = map.get(key);
+    if (existing) {
+        existing.count += 1;
+        return;
+    }
+    map.set(key, { count: 1, display });
+}
+
+function fmtHandle(handle) {
+    if (!handle) return null;
+    return handle.startsWith('@') ? handle : `@${handle}`;
+}
+
+function buildContribMarkdown({ from, to, resolvedCounts, unresolvedCounts }) {
+    const lines = [];
+    const rangeLabel = from && to ? `${from}..${to}` : 'range';
+
+    lines.push(`## Contributors`);
+    lines.push('');
+    lines.push(`Commit range: ${rangeLabel}`);
+    lines.push('');
+
+    const resolved = Array.from(resolvedCounts.entries())
+        .sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]));
+
+    if (resolved.length > 0) {
+        for (const [handle, info] of resolved) {
+            lines.push(`- ${fmtHandle(handle)} (${info.count})`);
+        }
+        lines.push('');
+    } else {
+        lines.push(`- None`);
+        lines.push('');
+    }
+
+    const unresolved = Array.from(unresolvedCounts.entries())
+        .sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0]));
+
+    if (unresolved.length > 0) {
+        lines.push(`## Unmapped Contributors`);
+        lines.push('');
+        for (const [key, info] of unresolved) {
+            lines.push(`- ${info.display} (${info.count})`);
+        }
+        lines.push('');
+        lines.push(`To tag these contributors, add their name/email to .github/contributors.yml.`);
+        lines.push('');
+    }
+
+    return lines.join('\n');
+}
+
+function main() {
+    const args = parseArgs(process.argv);
+    if (!args.from || !args.to) {
+        process.stderr.write('Usage: node scripts/release-contributors.js --from <tag> --to <tag> [--out <file>]\n');
+        process.exit(1);
+    }
+
+    const repoRoot = getRepoRoot();
+    const contribMap = readContributorsMap(repoRoot);
+    const range = `${args.from}..${args.to}`;
+    const commits = getCommitBodies(repoRoot, range);
+
+    const resolvedCounts = new Map();
+    const unresolvedCounts = new Map();
+
+    for (const c of commits) {
+        const authorHandle = resolveHandle(contribMap, { name: c.authorName, email: c.authorEmail });
+        if (authorHandle) {
+            bumpCounter(resolvedCounts, authorHandle, fmtHandle(authorHandle));
+        } else {
+            bumpCounter(unresolvedCounts, `${normalizeName(c.authorName)}|${normalizeEmail(c.authorEmail)}`, `${c.authorName} <${c.authorEmail}>`);
+        }
+
+        for (const co of extractCoAuthors(c.body)) {
+            const coHandle = resolveHandle(contribMap, co);
+            if (coHandle) {
+                bumpCounter(resolvedCounts, coHandle, fmtHandle(coHandle));
+            } else {
+                bumpCounter(unresolvedCounts, `${normalizeName(co.name)}|${normalizeEmail(co.email)}`, `${co.name} <${co.email}>`);
+            }
+        }
+    }
+
+    const md = buildContribMarkdown({
+        from: args.from,
+        to: args.to,
+        resolvedCounts,
+        unresolvedCounts
+    });
+
+    if (args.outFile) {
+        const outPath = path.isAbsolute(args.outFile) ? args.outFile : path.join(repoRoot, args.outFile);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, md, 'utf8');
+        process.stdout.write(`${outPath}\n`);
+        return;
+    }
+
+    process.stdout.write(md + '\n');
+}
+
+main();
+

package/scripts/release-notes.js

@@ -0,0 +1,194 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import YAML from 'yaml';
+
+function parseArgs(argv) {
+    const out = { tag: null, prev: null, outFile: null };
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        if (arg === '--tag' && next) {
+            out.tag = next;
+            i += 1;
+        } else if (arg === '--prev' && next) {
+            out.prev = next;
+            i += 1;
+        } else if (arg === '--out' && next) {
+            out.outFile = next;
+            i += 1;
+        }
+    }
+    return out;
+}
+
+function git(repoRoot, args) {
+    return execSync(`git ${args}`, { cwd: repoRoot, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf8');
+}
+
+function getRepoRoot() {
+    return execSync('git rev-parse --show-toplevel', { stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function readContributorsMap(repoRoot) {
+    const filePath = path.join(repoRoot, '.github', 'contributors.yml');
+    if (!fs.existsSync(filePath)) {
+        return { version: 1, contributors: [] };
+    }
+    const parsed = YAML.parse(fs.readFileSync(filePath, 'utf8')) || {};
+    return {
+        version: parsed.version || 1,
+        contributors: Array.isArray(parsed.contributors) ? parsed.contributors : []
+    };
+}
+
+function normalizeEmail(email) {
+    return String(email || '').trim().toLowerCase();
+}
+
+function normalizeName(name) {
+    return String(name || '').trim().toLowerCase();
+}
+
+function resolveHandle(map, { name, email }) {
+    const nEmail = normalizeEmail(email);
+    const nName = normalizeName(name);
+
+    for (const c of map.contributors) {
+        if (!c || typeof c !== 'object') continue;
+        if (!c.github) continue;
+        const emails = Array.isArray(c.emails) ? c.emails.map(normalizeEmail) : [];
+        if (nEmail && emails.includes(nEmail)) return c.github;
+        const names = Array.isArray(c.names) ? c.names.map(normalizeName) : [];
+        if (nName && names.includes(nName)) return c.github;
+    }
+    return null;
+}
+
+function fmtHandle(handle) {
+    if (!handle) return null;
+    return handle.startsWith('@') ? handle : `@${handle}`;
+}
+
+function bumpCounter(map, key) {
+    map.set(key, (map.get(key) || 0) + 1);
+}
+
+function extractCoAuthors(commitBody) {
+    const out = [];
+    const lines = String(commitBody || '').split('\n');
+    for (const line of lines) {
+        const m = line.match(/^Co-authored-by:\s*(.+?)\s*<(.+?)>\s*$/i);
+        if (m) out.push({ name: m[1], email: m[2] });
+    }
+    return out;
+}
+
+function getCommitBodies(repoRoot, range) {
+    const sepCommit = '\u001e';
+    const sepField = '\u001f';
+    const out = git(repoRoot, `log ${range} --no-color --format=%H${sepField}%an${sepField}%ae${sepField}%s${sepField}%B${sepCommit}`);
+    const rawCommits = out.split(sepCommit).map(s => s.trim()).filter(Boolean);
+    return rawCommits.map(entry => {
+        const parts = entry.split(sepField);
+        const [sha, authorName, authorEmail, subject] = parts;
+        const body = parts.slice(4).join(sepField);
+        return { sha, authorName, authorEmail, subject, body };
+    });
+}
+
+function determinePrevTag(repoRoot, tag) {
+    try {
+        return git(repoRoot, `describe --tags --abbrev=0 ${tag}^`).trim();
+    } catch {
+        return null;
+    }
+}
+
+function buildReleaseMarkdown({ tag, prev, commits, contributors }) {
+    const lines = [];
+
+    lines.push(`# ${tag}`);
+    lines.push('');
+
+    if (prev) {
+        lines.push(`Changes since ${prev}`);
+        lines.push('');
+    }
+
+    if (commits.length > 0) {
+        lines.push(`## Changes`);
+        lines.push('');
+        for (const c of commits) {
+            const sha = String(c.sha || '').slice(0, 7);
+            lines.push(`- ${c.subject} (${sha})`);
+        }
+        lines.push('');
+    }
+
+    lines.push(`## Contributors`);
+    lines.push('');
+
+    const sorted = Array.from(contributors.entries())
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+
+    if (sorted.length === 0) {
+        lines.push(`- None`);
+        lines.push('');
+        return lines.join('\n');
+    }
+
+    for (const [handle, count] of sorted) {
+        lines.push(`- ${fmtHandle(handle)} (${count})`);
+    }
+    lines.push('');
+
+    return lines.join('\n');
+}
+
+function main() {
+    const args = parseArgs(process.argv);
+    if (!args.tag) {
+        process.stderr.write('Usage: node scripts/release-notes.js --tag <tag> [--prev <tag>] [--out <file>]\n');
+        process.exit(1);
+    }
+
+    const repoRoot = getRepoRoot();
+    const prev = args.prev || determinePrevTag(repoRoot, args.tag);
+    const range = prev ? `${prev}..${args.tag}` : args.tag;
+
+    const contribMap = readContributorsMap(repoRoot);
+    const commits = getCommitBodies(repoRoot, range);
+
+    const contributors = new Map();
+
+    for (const c of commits) {
+        const authorHandle = resolveHandle(contribMap, { name: c.authorName, email: c.authorEmail });
+        if (authorHandle) bumpCounter(contributors, authorHandle);
+
+        for (const co of extractCoAuthors(c.body)) {
+            const coHandle = resolveHandle(contribMap, co);
+            if (coHandle) bumpCounter(contributors, coHandle);
+        }
+    }
+
+    const md = buildReleaseMarkdown({
+        tag: args.tag,
+        prev,
+        commits,
+        contributors
+    });
+
+    if (args.outFile) {
+        const outPath = path.isAbsolute(args.outFile) ? args.outFile : path.join(repoRoot, args.outFile);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, md, 'utf8');
+        process.stdout.write(`${outPath}\n`);
+        return;
+    }
+
+    process.stdout.write(md + '\n');
+}
+
+main();
+

package/src/commands/analyze.js

@@ -9,6 +9,23 @@ import { writeAnalysisToSeoMd, writeReverseMd, writePageAnalysis } from '../util
 
 dotenv.config();
 
+function matchRoute(pattern, url) {
+    const cleanPattern = pattern.replace(/\/$/, '');
+    const cleanUrl = url.replace(/\/$/, '');
+    
+    if (cleanPattern.toLowerCase() === cleanUrl.toLowerCase()) {
+        return true;
+    }
+    
+    // Replace "/[param]" with optional group "(?:/([^/]+))?"
+    const regexPattern = cleanPattern
+        .replace(/\/\[[^\]]+\]/g, '(?:\\/([^/]+))?')
+        .replace(/\//g, '\\/');
+        
+    const regex = new RegExp('^' + regexPattern + '\\/?$', 'i');
+    return regex.test(url);
+}
+
 export async function analyzeCommand(options) {
     const apiKey = process.env.SEOMD_API_KEY;
     const paymentToken = process.env.SEOMD_PAYMENT_TOKEN;
@@ -68,21 +85,31 @@ export async function analyzeCommand(options) {
 
     // Filter by options.page if specified
     if (options.page) {
-        pagesList = pagesList.filter(p => p.url === options.page);
+        pagesList = pagesList.filter(p => matchRoute(p.url, options.page));
     }
 
-    // Default to homepage if no pages defined
+    // Default fallback if no page matches or list is empty
     if (pagesList.length === 0) {
+        let fallbackId = 'homepage';
+        if (options.page && options.page !== '/') {
+            fallbackId = options.page
+                .replace(/^\//, '')
+                .replace(/\/$/, '')
+                .replace(/[^a-zA-Z0-9-]/g, '-');
+        }
         pagesList.push({
-            id: 'homepage',
+            id: fallbackId,
             url: options.page || '/',
-            primary_keyword: `best ${niche}`,
+            primary_keyword: data.keywords?.primary || `best ${niche}`,
             status: 'planned'
         });
     }
 
     // Extract engines
-    const engines = data.aeo?._analysis?.engines_tracked || ['ChatGPT'];
+    let engines = data.aeo?._analysis?.engines_tracked || ['ChatGPT'];
+    if (options.engines) {
+        engines = options.engines.split(',').map(e => e.trim());
+    }
 
     console.log(chalk.bold.cyan(`\n📊 Foxcite: Running AI Search Audit for ${chalk.white(domain)}`));
     console.log(chalk.dim(`Engines: ${engines.join(', ')}`));
@@ -92,14 +119,16 @@ export async function analyzeCommand(options) {
     const spinner = ora('Initializing scan sessions...').start();
 
     try {
+        const brand = data.identity?.brand || 'My Brand';
         const payload = {
             domain,
             niche,
+            brand,
             queries,
             engines,
             pages: pagesList.map(p => ({
                 id: p.id,
-                url: p.url,
+                url: options.page || p.url, // Use the specific page requested if provided
                 primary_keyword: p.primary_keyword || data.keywords?.primary || `best ${niche}`,
                 status: p.status
             }))
@@ -116,7 +145,8 @@ export async function analyzeCommand(options) {
         await writeAnalysisToSeoMd(doc, results, cwd);
 
         // Writeback to SEO.REVERSE.md
-        await writeReverseMd(cwd, results);
+        const brandName = data.identity?.brand || 'My Brand';
+        await writeReverseMd(cwd, results, domain, brandName);
 
         // Writeback to .seomd/pages/*.md
         await writePageAnalysis(cwd, results);

package/src/commands/status.js

@@ -28,7 +28,8 @@ export async function statusCommand(options) {
                 console.log(chalk.white('     npx seomd analyze'));
                 console.log('');
             }
-            process.exit(0);
+            process.exitCode = 0;
+            return;
         }
 
         // Format overall metrics
@@ -77,7 +78,8 @@ export async function statusCommand(options) {
             });
 
             console.log(JSON.stringify(output, null, 2));
-            process.exit(0);
+            process.exitCode = 0;
+            return;
         }
 
         // Output beautiful terminal dashboard
@@ -145,7 +147,8 @@ export async function statusCommand(options) {
         console.log(chalk.red('✗ ') + chalk.bold('Failed to display status:'));
         console.log(`  ${chalk.dim(err.message)}`);
         console.log('');
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
 }
 

package/src/commands/sync.js

@@ -79,7 +79,7 @@ export async function syncCommand(options) {
             console.log(`Last Analyzed         : ${chalk.dim(aeo.last_analyzed)}`);
             console.log(chalk.yellow('\n⚠ Dry-run enabled: No files were modified.'));
             console.log('');
-            process.exit(0);
+            return;
         }
 
         spinner.text = 'Updating repository files...';
@@ -88,7 +88,8 @@ export async function syncCommand(options) {
         await writeAnalysisToSeoMd(doc, results, cwd);
 
         // Writeback to SEO.REVERSE.md
-        await writeReverseMd(cwd, results);
+        const brandName = data.identity?.brand || 'My Brand';
+        await writeReverseMd(cwd, results, domain, brandName);
 
         // Writeback to .seomd/pages/*.md
         await writePageAnalysis(cwd, results);

package/src/commands/validate.js

@@ -13,7 +13,8 @@ export async function validateCommand() {
         if (errors.length === 0 && warnings.length === 0) {
             console.log(chalk.green('  ✓ ') + chalk.bold('SEO.md is fully compliant with spec v1.0!'));
             console.log('');
-            process.exit(0);
+            process.exitCode = 0;
+            return;
         }
 
         // Print errors
@@ -41,18 +42,21 @@ export async function validateCommand() {
             console.log(chalk.red.bold(`✗ Validation failed: ${errors.length} error(s) and ${warnings.length} warning(s) found.`));
             console.log(chalk.dim('Please fix the errors to make your SEO.md valid.'));
             console.log('');
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         } else {
             console.log(chalk.yellow.bold(`✓ Validation passed with ${warnings.length} warning(s).`));
             console.log(chalk.dim('Warnings are optional recommendations and do not block compliance.'));
             console.log('');
-            process.exit(0);
+            process.exitCode = 0;
+            return;
         }
 
     } catch (err) {
         console.log(chalk.red('✗ ') + chalk.bold('Validation process failed:'));
         console.log(`  ${chalk.dim(err.message)}`);
         console.log('');
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
 }

package/src/utils/constants.js

@@ -121,12 +121,27 @@ export const PERFORMANCE_THRESHOLDS = {
 };
 
 export const AI_BOTS = [
-    'Googlebot',
-    'Bingbot',
-    'PerplexityBot',
-    'ChatGPT-User',
-    'GPTBot',
-    'ClaudeBot',
-    'anthropic-ai',
-    'cohere-ai',
+    { userAgent: 'GPTBot', allow: '/' },
+    { userAgent: 'OAI-SearchBot', allow: '/' },
+    { userAgent: 'ChatGPT-User', allow: '/' },
+    { userAgent: 'ClaudeBot', allow: '/' },
+    { userAgent: 'Claude-User', allow: '/' },
+    { userAgent: 'Claude-SearchBot', allow: '/' },
+    { userAgent: 'anthropic-ai', allow: '/' },
+    { userAgent: 'PerplexityBot', allow: '/' },
+    { userAgent: 'Perplexity-User', allow: '/' },
+    { userAgent: 'cohere-ai', allow: '/' },
+    { userAgent: 'MistralAI-User', allow: '/' },
+    { userAgent: 'Googlebot', allow: '/' },
+    { userAgent: 'Google-Extended', allow: '/' },
+    { userAgent: 'Bingbot', allow: '/' },
+    { userAgent: 'Meta-ExternalAgent', allow: '/' },
+    { userAgent: 'Meta-ExternalFetcher', allow: '/' },
+    { userAgent: 'Applebot', allow: '/' },
+    { userAgent: 'Applebot-Extended', allow: '/' },
+    { userAgent: 'Bytespider', allow: '/' },
+    { userAgent: 'Amazonbot', allow: '/' },
+    { userAgent: 'CCBot', allow: '/' },
+    { userAgent: 'diffbot', allow: '/' },
+    { userAgent: 'webzio-extended', allow: '/' },
 ];

package/src/utils/writeback.js

@@ -67,7 +67,7 @@ export async function writeAnalysisToSeoMd(doc, response, cwd) {
  * @param {string} cwd - Current working directory
  * @param {any} response - The API response from analyze/sync
  */
-export async function writeReverseMd(cwd, response) {
+export async function writeReverseMd(cwd, response, defaultDomain = 'example.com', defaultBrand = 'My Brand') {
     const reversePath = path.join(cwd, 'SEO.REVERSE.md');
 
     const reversePages = response.page_analysis.map(p => ({
@@ -88,8 +88,8 @@ export async function writeReverseMd(cwd, response) {
     const primaryCompetitor = response.intent_analysis?.comparison?.top_cited_competitor || 'None';
 
     const reverseDoc = {
-        domain: response.domain || 'example.com',
-        brand: response.brand_name || 'My Brand',
+        domain: response.domain || defaultDomain,
+        brand: response.brand_name || defaultBrand,
         primary_competitor: primaryCompetitor,
         last_analyzed: response.aeo_analysis.last_analyzed,
         next_analysis: response.aeo_analysis.next_analysis,