seomd-cli 1.1.1 → 1.2.0

package/README.md

@@ -1,69 +1,225 @@
-# 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
 ```
 
----
+Or run without installing (zero-install):
+
+```bash
+npx seomd-cli init
+```
+
+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:
+Or non-interactively with flags:
+
+```bash
+seomd init -y --type local
+# or
+seomd init --brand "Acme" --domain acme.com --primary-keyword "local seo"
+```
+
+### 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
+
+Copy `.env.example` from your platform provider docs, or create one with the vars you need:
+
+Required for live audits:
+```bash
+SEOMD_API_URL=
+SEOMD_API_KEY=your_key_here
+```
+
+Optional:
+```bash
+SEOMD_PAYMENT_TOKEN= # x402 pay-per-scan token
+SEOMD_DOMAIN= # override domain header
+```
 
-## Command Reference
+> If you don't have a platform key yet, `seomd init` still works without `.env`.
+
+## 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.
+
+**Usage:**
+```bash
+seomd init                              # interactive 5-question flow
+seomd init -y --type local              # skip prompts, use defaults
+seomd init --brand "Acme" --domain acme.com  # non-interactive with partial flags
+seomd init --type saas --brand "MyApp" --domain myapp.com --primary-keyword "billing automation" --output ./new-project
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | skip prompts, use defaults |
+| `--type <type>` | site type: saas, ecommerce, local, blog, marketplace |
+| `--brand <name>` | brand name |
+| `--domain <domain>` | primary domain |
+| `--primary-keyword <keyword>` | primary keyword |
+| `--competitors <list>` | comma-separated competitor list |
+| `--output <dir>` | scaffold into a new (empty) directory instead of cwd |
+
+**Behavior:**
+- Interactive flow by default (5 questions)
+- Non-interactive when `-y` is set **OR** any config flag (`--brand`, `--domain`, `--primary-keyword`, `--competitors`) is provided
+- `--type` alone pre-selects site type in the interactive flow
+- `--output` writes all files to the target directory (must be empty or non-existent)
 
 ### `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
+
+## Built-in Templates
+
+`seomd-cli` ships with type-specific templates under `src/templates/`. `seomd init --type <type>` uses the matching template automatically.
+
+| Type | Template dir | Best for |
+|------|-------------|----------|
+| `saas` | `src/templates/saas/` | Software products, B2B tools, web apps |
+| `blog` | `src/templates/blog/` | Content sites, newsletters, personal brands |
+| `ecommerce` | `src/templates/ecommerce/` | Online stores, DTC brands, product catalogs |
+| `local` | `src/templates/local/` | Service-area businesses, locations pages |
+| `marketplace` | `src/templates/marketplace/` | Two-sided platforms, directories |
+
+Each template contains:
+
+- `SEO.md` — pre-filled with type-specific intent queries, page structures, and negative keywords
+- `SEO.REVERSE.md` — reverse-engineer output scaffold with placeholders for competitor analysis
+
+Want to customize a template? Copy the relevant folder, edit the placeholders (`{{brand}}`, `{{domain}}`, etc.), and use `--type` with your custom scaffold.
+
+## 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 +228,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

@@ -25,6 +25,19 @@ program
     .description('Scaffold SEO.md for your project')
     .option('-y, --yes', 'skip prompts and use defaults')
     .option('--type <type>', 'site type: saas, ecommerce, local, blog, marketplace')
+    .option('--brand <brand>', 'brand name')
+    .option('--domain <domain>', 'primary domain')
+    .option('--primary-keyword <keyword>', 'primary keyword')
+    .option('--competitors <list>', 'comma-separated competitor list')
+    .option('--output <dir>', 'scaffold into a new directory instead of cwd')
+    .addHelpText('after', `
+
+Examples:
+  seomd init                              # interactive 5-question flow
+  seomd init -y --type local              # skip prompts, use defaults
+  seomd init --brand "Acme" --domain acme.com --primary-keyword "local seo"
+  seomd init --type saas --brand "MyApp" --domain myapp.com --output ./new-project
+`)
     .action(initCommand);
 
 program
@@ -33,23 +46,47 @@ program
     .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)')
+    .addHelpText('after', `
+
+Examples:
+  seomd analyze                           # full audit
+  seomd analyze --page /pricing           # single page audit
+  seomd analyze --intent transactional --engines chatgpt,claude
+`)
     .action(analyzeCommand);
 
 program
     .command('sync')
     .description('Sync latest platform intelligence to your SEO.md files')
     .option('--dry-run', 'preview changes without writing')
+    .addHelpText('after', `
+
+Examples:
+  seomd sync                              # sync latest data
+  seomd sync --dry-run                    # preview changes only
+`)
     .action(syncCommand);
 
 program
     .command('status')
     .description('Show current citation rates and gap scores')
     .option('--json', 'output as JSON')
+    .addHelpText('after', `
+
+Examples:
+  seomd status                            # human-readable summary
+  seomd status --json                     # machine-readable JSON
+`)
     .action(statusCommand);
 
 program
     .command('validate')
     .description('Validate your SEO.md against the spec')
+    .addHelpText('after', `
+
+Example:
+  seomd validate
+`)
     .action(validateCommand);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "seomd-cli",
-    "version": "1.1.1",
+    "version": "1.2.0",
     "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
     "homepage": "https://seomd.dev",
     "repository": {
@@ -14,26 +14,31 @@
     },
     "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": {
+        "axios": "^1.6.0",
         "chalk": "^5.3.0",
         "commander": "^11.0.0",
+        "dotenv": "^16.3.1",
         "enquirer": "^2.4.1",
-        "ora": "^7.0.1",
-        "yaml": "^2.3.4",
         "fs-extra": "^11.1.1",
-        "axios": "^1.6.0",
-        "dotenv": "^16.3.1"
+        "ora": "^7.0.1",
+        "yaml": "^2.3.4"
     },
     "devDependencies": {
-        "jest": "^29.7.0",
-        "eslint": "^8.50.0"
+        "@eslint/js": "^10.0.1",
+        "eslint": "^8.50.0",
+        "eslint-plugin-n": "^18.1.0",
+        "jest": "^29.7.0"
     },
     "engines": {
         "node": ">=18.0.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

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'fs-extra';
-import path from 'path';
 import dotenv from 'dotenv';
 import { parseSeoMd } from '../utils/parser.js';
 import { client } from '../utils/api-client.js';

package/src/commands/init.js

@@ -16,8 +16,19 @@ export async function initCommand(options) {
     console.log(chalk.dim('The open standard for AI-era SEO configuration.'));
     console.log('');
 
-    // Check if SEO.md already exists
-    const seomdPath = path.join(process.cwd(), 'SEO.md');
+    // Determine target directory
+    let workingDir = process.cwd();
+    if (options.output) {
+        const resolved = path.resolve(options.output);
+        if (await fs.pathExists(resolved) && (await fs.readdir(resolved)).length > 0) {
+            console.log(chalk.red(`Output directory must be empty or non-existent: ${resolved}`));
+            process.exit(1);
+        }
+        await fs.ensureDir(resolved);
+        workingDir = resolved;
+    }
+
+    const seomdPath = path.join(workingDir, 'SEO.md');
     if (await fs.pathExists(seomdPath)) {
         console.log(chalk.yellow('⚠ SEO.md already exists in this directory.'));
         const { overwrite } = await prompt({
@@ -34,14 +45,26 @@ export async function initCommand(options) {
 
     let answers;
 
-    if (options.yes) {
-        // Default values for --yes flag
+    // Mode 5: non-interactive if -y OR any config field provided
+    const hasConfigFlags =
+        options.brand !== undefined ||
+        options.domain !== undefined ||
+        options.primaryKeyword !== undefined ||
+        options.competitors !== undefined;
+
+    if (options.yes || hasConfigFlags) {
         answers = {
             site_type: options.type || 'saas',
-            domain: 'example.com',
-            brand: 'My Brand',
-            primary_keyword: '',
-            competitors: '',
+            domain: options.domain || 'example.com',
+            brand: options.brand || 'My Brand',
+            primary_keyword: options.primaryKeyword || '',
+            competitors: options.competitors
+                ? options.competitors
+                      .split(',')
+                      .map((c) => c.trim())
+                      .filter(Boolean)
+                      .slice(0, 3)
+                : [],
         };
     } else {
         // The 5-question init flow
@@ -109,21 +132,20 @@ export async function initCommand(options) {
     try {
         // 1. Generate SEO.md
         const seomdContent = generateSeoMd(answers);
-        await fs.writeFile(seomdPath, seomdContent, 'utf8');
+        await fs.writeFile(path.join(workingDir, 'SEO.md'), seomdContent, 'utf8');
         spinner.succeed(chalk.green('SEO.md created'));
 
         // 2. Generate SEO.REVERSE.md
-        const reversePath = path.join(process.cwd(), 'SEO.REVERSE.md');
         const reverseContent = generateReverseMd(answers);
-        await fs.writeFile(reversePath, reverseContent, 'utf8');
+        await fs.writeFile(path.join(workingDir, 'SEO.REVERSE.md'), reverseContent, 'utf8');
         spinner.succeed(chalk.green('SEO.REVERSE.md initialized'));
 
         // 3. Create .seomd/ directory structure
-        await createSeomdDir(process.cwd(), answers);
+        await createSeomdDir(workingDir, answers);
         spinner.succeed(chalk.green('.seomd/ directory created'));
 
         // 4. Add .seomd/ to .gitignore if it exists
-        await updateGitignore(process.cwd());
+        await updateGitignore(workingDir);
 
         console.log('');
         console.log(chalk.bold.green('✓ SEO.md initialized successfully'));

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

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import fs from 'fs-extra';
-import path from 'path';
 import dotenv from 'dotenv';
 import { parseSeoMd } from '../utils/parser.js';
 import { client } from '../utils/api-client.js';
@@ -79,7 +78,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...';

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/generators/directory.js

@@ -40,38 +40,89 @@ export async function createSeomdDir(cwd, answers) {
 function generateSeomdReadme(brand, domain) {
     return `# .seomd/
 
-Intelligence directory for ${brand} (${domain})
+AI search optimization workspace for **${brand}** (${domain})
 Generated by SEO.md CLI — https://seomd.dev
 
+## What is this?
+
+\`.seomd/\` stores platform-generated intelligence from citation audits, competitor analysis, and reverse-engineered playbooks. It lives alongside your source code so SEO strategy is version-controlled and reviewable in PRs.
+
 ## Directory Structure
 
 \`\`\`
 .seomd/
-├── pages/          # per-page reverse engineer analysis
+├── pages/          # per-page reverse-engineer analysis
+│   ├── homepage.md
+│   ├── services.md
+│   └── ...
 ├── reports/        # dated snapshot reports (gitignored by default)
+│   └── 2026-06-10.md
 └── competitors/    # competitor citation profiles
+    └── comp-1.md
 \`\`\`
 
-## Usage
+## Git behavior
+
+| Path | Git | Why |
+|------|-----|-----|
+| \`.seomd/pages/\` | tracked | actionable playbooks belong in code review |
+| \`.seomd/competitors/\` | tracked | competitor intel is project state |
+| \`.seomd/reports/\` | ignored | dated snapshots are noise in git history |
+
+\`.seomd/reports/\` is added to \`.gitignore\` automatically by \`seomd init\`.
+
+## When to run what
 
 \`\`\`bash
-# Run citation analysis and update all files
+# First full audit — scans all pages + intents
 npx seomd analyze
 
-# Sync latest platform intelligence
+# Refresh from cached platform data (no new scan)
 npx seomd sync
 
-# View current status
+# Check current gap scores without modifying files
 npx seomd status
+npx seomd status --json
 \`\`\`
 
-## File Ownership
+| Command | Use when |
+|---------|----------|
+| \`analyze\` | You want a fresh audit, new competitor data, or updated playbooks |
+| \`sync\` | You just want the latest cached data from your platform |
+| \`status\` | You want a quick health check without writebacks |
+
+## Reading a page playbook
+
+Each \`pages/<id>.md\` contains:
+
+- **why_page_won** — what top-cited competitors do right
+- **citation_hooks** — patterns to replicate
+- **gaps_for_brand** — where your page falls short
+- **remediation_playbook** — step-by-step fixes with effort/impact
+- **fastest_win** — highest ROI action to take now
+- **suggested_content_outline** — ready-to-use outline for your writer or AI
+
+## File ownership
+
+| File/dir | Owner | Editable? |
+|-----------|-------|----------|
+| \`SEO.md\` | you | yes |
+| \`SEO.REVERSE.md\` | platform | no |
+| \`.seomd/pages/*.md\` | platform | no |
+| \`.seomd/competitors/*.md\` | platform | no |
+| \`.seomd/reports/*.md\` | platform | no |
+
+Platform-generated files are overwritten on each \`analyze\` or \`sync\`.
+
+## Platform connection
+
+To enable live writebacks:
 
-- \`pages/\` — platform generated, do not edit manually
-- \`reports/\` — platform generated, gitignored by default
-- \`competitors/\` — platform generated, do not edit manually
+1. Connect at https://seomd.dev/connect
+2. Add \`SEOMD_API_KEY\` to your \`.env\`
+3. Run \`npx seomd analyze\`
 
-Connect your platform at https://seomd.dev/connect
+_Note: Never commit API keys or \`.env\` files to version control._
 `;
 }
 

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: '/' },
 ];