seomd-cli 1.1.2 → 1.3.0

package/README.md

@@ -36,6 +36,12 @@ SEO.md is a structured, version-controlled specification for describing your sit
 npm install -g seomd-cli
 ```
 
+Or run without installing (zero-install):
+
+```bash
+npx seomd-cli init
+```
+
 Verify:
 
 ```bash
@@ -52,6 +58,14 @@ Run in the root of your project:
 seomd init
 ```
 
+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
@@ -74,24 +88,57 @@ seomd status --json
 
 ## Configuration
 
-Copy the example env file:
+Copy `.env.example` from your platform provider docs, or create one with the vars you need:
+
+Required for live audits:
 
 ```bash
-cp .env.example .env
+SEOMD_API_URL=
+SEOMD_API_KEY=your_key_here
 ```
 
-Environment variables:
+Optional:
 
-- `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
+```bash
+SEOMD_PAYMENT_TOKEN= # x402 pay-per-scan token
+SEOMD_DOMAIN= # override domain header
+```
+
+> If you don't have a platform key yet, `seomd init` still works without `.env`.
 
 ## Commands
 
 ### `seomd init`
 
-Scaffolds `SEO.md`, `SEO.REVERSE.md`, and the `.seomd/` intelligence directory.
+Scaffolds `SEO.md`, `SEO.REVERSE.md`, and the `.seo/` 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`
 
@@ -109,7 +156,7 @@ 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)
+- `.seo/pages/*.md` (per-page playbooks when available)
 
 ### `seomd sync`
 
@@ -117,6 +164,25 @@ Pulls cached/latest platform intelligence and writes it back to the same files a
 
 - `--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:
@@ -162,9 +228,11 @@ To enable live intelligence writebacks (using automated platforms like [Foxcite]
 
 1. Obtain a developer API key from your platform provider.
 2. Export the key as an environment variable:
+
    ```bash
    export SEOMD_API_KEY="your_api_key_here"
    ```
+
 3. Run `seomd sync` or `seomd analyze`.
 
 _Note: Never commit your API keys or `.env` files containing keys to version control._

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.2",
+    "version": "1.3.0",
     "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
     "homepage": "https://seomd.dev",
     "repository": {
@@ -25,18 +25,19 @@
         "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": "^8.50.0",
+        "eslint-plugin-n": "^18.1.0",
+        "jest": "^29.7.0"
     },
     "engines": {
         "node": ">=18.0.0"

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';
@@ -12,16 +11,16 @@ 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);
 }
@@ -148,7 +147,7 @@ export async function analyzeCommand(options) {
         const brandName = data.identity?.brand || 'My Brand';
         await writeReverseMd(cwd, results, domain, brandName);
 
-        // Writeback to .seomd/pages/*.md
+        // Writeback to .seo/pages/*.md
         await writePageAnalysis(cwd, results);
 
         spinner.succeed(chalk.green('Analysis completed successfully!'));
@@ -169,7 +168,7 @@ export async function analyzeCommand(options) {
         console.log('');
         console.log(chalk.green('✔ SEO.md updated.'));
         console.log(chalk.green('✔ SEO.REVERSE.md updated.'));
-        console.log(chalk.green('✔ .seomd/pages/ playbooks generated.'));
+        console.log(chalk.green('✔ .seo/pages/ playbooks generated.'));
         console.log('');
 
     } catch (err) {

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);
-        spinner.succeed(chalk.green('.seomd/ directory created'));
+        // 3. Create .seo/ directory structure
+        await createSeomdDir(workingDir, answers);
+        spinner.succeed(chalk.green('.seo/ directory created'));
 
-        // 4. Add .seomd/ to .gitignore if it exists
-        await updateGitignore(process.cwd());
+        // 4. Add .seo/ to .gitignore if it exists
+        await updateGitignore(workingDir);
 
         console.log('');
         console.log(chalk.bold.green('✓ SEO.md initialized successfully'));
@@ -131,7 +153,7 @@ export async function initCommand(options) {
         console.log(chalk.dim('Files created:'));
         console.log('  ' + chalk.cyan('SEO.md') + chalk.dim('             — your living SEO config'));
         console.log('  ' + chalk.cyan('SEO.REVERSE.md') + chalk.dim('     — reverse engineer output (platform generated)'));
-        console.log('  ' + chalk.cyan('.seomd/') + chalk.dim('            — intelligence directory'));
+        console.log('  ' + chalk.cyan('.seo/') + chalk.dim('            — intelligence directory'));
         console.log('');
         console.log(chalk.dim('Next steps:'));
         console.log('  ' + chalk.white('npx seomd analyze') + chalk.dim('  — run your first citation analysis'));
@@ -149,11 +171,11 @@ export async function initCommand(options) {
 
 async function updateGitignore(cwd) {
     const gitignorePath = path.join(cwd, '.gitignore');
-    const entry = '\n# seomd intelligence directory\n.seomd/reports/\n';
+    const entry = '\n# seomd intelligence directory\n.seo/reports/\n';
 
     if (await fs.pathExists(gitignorePath)) {
         const content = await fs.readFile(gitignorePath, 'utf8');
-        if (!content.includes('.seomd')) {
+        if (!content.includes('.seo')) {
             await fs.appendFile(gitignorePath, entry);
         }
     }

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';
@@ -91,7 +90,7 @@ export async function syncCommand(options) {
         const brandName = data.identity?.brand || 'My Brand';
         await writeReverseMd(cwd, results, domain, brandName);
 
-        // Writeback to .seomd/pages/*.md
+        // Writeback to .seo/pages/*.md
         await writePageAnalysis(cwd, results);
 
         spinner.succeed(chalk.green('Sync completed successfully!'));
@@ -112,7 +111,7 @@ export async function syncCommand(options) {
         console.log('');
         console.log(chalk.green('✔ SEO.md updated.'));
         console.log(chalk.green('✔ SEO.REVERSE.md updated.'));
-        console.log(chalk.green('✔ .seomd/pages/ playbooks synchronized.'));
+        console.log(chalk.green('✔ .seo/pages/ playbooks synchronized.'));
         console.log('');
 
     } catch (err) {

package/src/generators/directory.js

@@ -5,14 +5,14 @@ import { REQUIRED_PAGES } from '../utils/constants.js';
 export async function createSeomdDir(cwd, answers) {
     const { site_type, brand, domain } = answers;
     const pages = REQUIRED_PAGES[site_type] || REQUIRED_PAGES.saas;
-    const seomdDir = path.join(cwd, '.seomd');
+    const seomdDir = path.join(cwd, '.seo');
 
     // Create directory structure
     await fs.ensureDir(path.join(seomdDir, 'pages'));
     await fs.ensureDir(path.join(seomdDir, 'reports'));
     await fs.ensureDir(path.join(seomdDir, 'competitors'));
 
-    // Create README inside .seomd/
+    // Create README inside .seo/
     await fs.writeFile(
         path.join(seomdDir, 'README.md'),
         generateSeomdReadme(brand, domain),
@@ -38,40 +38,91 @@ export async function createSeomdDir(cwd, answers) {
 }
 
 function generateSeomdReadme(brand, domain) {
-    return `# .seomd/
+    return `# .seo/
 
-Intelligence directory for ${brand} (${domain})
+AI search optimization workspace for **${brand}** (${domain})
 Generated by SEO.md CLI — https://seomd.dev
 
+## What is this?
+
+\`.seo/\` 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
+.seo/
+├── 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 |
+|------|-----|-----|
+| \`.seo/pages/\` | tracked | actionable playbooks belong in code review |
+| \`.seo/competitors/\` | tracked | competitor intel is project state |
+| \`.seo/reports/\` | ignored | dated snapshots are noise in git history |
+
+\`.seo/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 |
+| \`.seo/pages/*.md\` | platform | no |
+| \`.seo/competitors/*.md\` | platform | no |
+| \`.seo/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/writeback.js

@@ -110,13 +110,13 @@ export async function writeReverseMd(cwd, response, defaultDomain = 'example.com
 }
 
 /**
- * Writes individual page playbooks into .seomd/pages/{id}.md files.
+ * Writes individual page playbooks into .seo/pages/{id}.md files.
  * 
  * @param {string} cwd - Current working directory
  * @param {any} response - The API response from analyze/sync
  */
 export async function writePageAnalysis(cwd, response) {
-    const seomdDir = path.join(cwd, '.seomd');
+    const seomdDir = path.join(cwd, '.seo');
     const pagesDir = path.join(seomdDir, 'pages');
 
     await fs.ensureDir(pagesDir);