seomd-cli 1.2.0 → 1.4.0

package/README.md

@@ -91,12 +91,14 @@ seomd status --json
 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
@@ -108,9 +110,10 @@ SEOMD_DOMAIN= # override domain header
 
 ### `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
@@ -119,6 +122,7 @@ seomd init --type saas --brand "MyApp" --domain myapp.com --primary-keyword "bil
 ```
 
 **Options:**
+
 | Flag | Description |
 |------|-------------|
 | `-y, --yes` | skip prompts, use defaults |
@@ -130,6 +134,7 @@ seomd init --type saas --brand "MyApp" --domain myapp.com --primary-keyword "bil
 | `--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
@@ -151,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`
 
@@ -223,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "seomd-cli",
-    "version": "1.2.0",
+    "version": "1.4.0",
     "description": "The official CLI for the SEO.md open standard — AEO infrastructure for technical founders",
     "homepage": "https://seomd.dev",
     "repository": {
@@ -35,7 +35,6 @@
         "yaml": "^2.3.4"
     },
     "devDependencies": {
-        "@eslint/js": "^10.0.1",
         "eslint": "^8.50.0",
         "eslint-plugin-n": "^18.1.0",
         "jest": "^29.7.0"

package/src/commands/analyze.js

@@ -11,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);
 }
@@ -105,7 +105,7 @@ export async function analyzeCommand(options) {
     }
 
     // Extract engines
-    let engines = data.aeo?._analysis?.engines_tracked || ['ChatGPT'];
+    let engines = ['ChatGPT', 'Perplexity', 'Claude']; // Default since we removed _analysis
     if (options.engines) {
         engines = options.engines.split(',').map(e => e.trim());
     }
@@ -140,14 +140,14 @@ export async function analyzeCommand(options) {
 
         spinner.text = 'Writing analysis blocks back to repository files...';
 
-        // Writeback to SEO.md
+        // Writeback to .seo/STATUS.yml
         await writeAnalysisToSeoMd(doc, results, cwd);
 
-        // Writeback to SEO.REVERSE.md
+        // Writeback to .seo/REVERSE.md
         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!'));
@@ -166,9 +166,9 @@ export async function analyzeCommand(options) {
         console.log(`Next Analysis Target  : ${chalk.dim(aeo.next_analysis)}`);
         console.log('-----------------------');
         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/STATUS.yml updated.'));
+        console.log(chalk.green('✔ .seo/REVERSE.md updated.'));
+        console.log(chalk.green('✔ .seo/pages/ playbooks generated.'));
         console.log('');
 
     } catch (err) {

package/src/commands/init.js

@@ -60,10 +60,10 @@ export async function initCommand(options) {
             primary_keyword: options.primaryKeyword || '',
             competitors: options.competitors
                 ? options.competitors
-                      .split(',')
-                      .map((c) => c.trim())
-                      .filter(Boolean)
-                      .slice(0, 3)
+                    .split(',')
+                    .map((c) => c.trim())
+                    .filter(Boolean)
+                    .slice(0, 3)
                 : [],
         };
     } else {
@@ -135,25 +135,24 @@ export async function initCommand(options) {
         await fs.writeFile(path.join(workingDir, 'SEO.md'), seomdContent, 'utf8');
         spinner.succeed(chalk.green('SEO.md created'));
 
-        // 2. Generate SEO.REVERSE.md
+        // 2. Create .seo/ directory structure
+        await createSeomdDir(workingDir, answers);
+        spinner.succeed(chalk.green('.seo/ directory created'));
+
+        // 3. Generate .seo/REVERSE.md
         const reverseContent = generateReverseMd(answers);
-        await fs.writeFile(path.join(workingDir, 'SEO.REVERSE.md'), reverseContent, 'utf8');
-        spinner.succeed(chalk.green('SEO.REVERSE.md initialized'));
+        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(workingDir, answers);
-        spinner.succeed(chalk.green('.seomd/ directory created'));
 
-        // 4. Add .seomd/ to .gitignore if it exists
-        await updateGitignore(workingDir);
 
         console.log('');
         console.log(chalk.bold.green('✓ SEO.md initialized successfully'));
         console.log('');
         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/REVERSE.md') + chalk.dim('    — reverse engineer output (platform generated)'));
+        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'));
@@ -168,15 +167,3 @@ export async function initCommand(options) {
         process.exit(1);
     }
 }
-
-async function updateGitignore(cwd) {
-    const gitignorePath = path.join(cwd, '.gitignore');
-    const entry = '\n# seomd intelligence directory\n.seomd/reports/\n';
-
-    if (await fs.pathExists(gitignorePath)) {
-        const content = await fs.readFile(gitignorePath, 'utf8');
-        if (!content.includes('.seomd')) {
-            await fs.appendFile(gitignorePath, entry);
-        }
-    }
-}

package/src/commands/status.js

@@ -1,14 +1,26 @@
 import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import YAML from 'yaml';
 import { parseSeoMd } from '../utils/parser.js';
 
 export async function statusCommand(options) {
     try {
-        const { data } = await parseSeoMd(process.cwd());
+        const cwd = process.cwd();
+        const { data } = await parseSeoMd(cwd);
+        
+        let statusData = {};
+        const statusPath = path.join(cwd, '.seo', 'STATUS.yml');
+        
+        if (await fs.pathExists(statusPath)) {
+            const content = await fs.readFile(statusPath, 'utf8');
+            statusData = YAML.parse(content) || {};
+        }
 
-        const aeoAnalysis = data.aeo?._analysis || {};
-        const intentAnalysis = data.intent?._analysis || {};
+        const aeoAnalysis = statusData.aeo || {};
+        const intentAnalysis = statusData.intent || {};
         const pagesRequired = data.pages?.required || [];
-        const pagesAnalysis = data.pages?._analysis?.pages || [];
+        const pagesAnalysis = statusData.pages?.pages || [];
 
         // Check if there is any analysis data
         const hasOverallData = aeoAnalysis.overall_citation_rate !== null && aeoAnalysis.overall_citation_rate !== undefined;
@@ -18,7 +30,7 @@ export async function statusCommand(options) {
                 console.log(JSON.stringify({ status: "no_data", message: "No analysis data found" }, null, 2));
             } else {
                 console.log('');
-                console.log(chalk.yellow('⚠ No analysis data found in SEO.md.'));
+                console.log(chalk.yellow('⚠ No analysis data found in .seo/STATUS.yml.'));
                 console.log('');
                 console.log('To populate analysis data:');
                 console.log(`  1. Get an API key at ${chalk.cyan('https://seomd.dev/connect')}`);
@@ -47,7 +59,7 @@ export async function statusCommand(options) {
                 overall: {
                     citation_rate: aeoAnalysis.overall_citation_rate,
                     gap_score: aeoAnalysis.overall_gap_score,
-                    last_analyzed: aeoAnalysis.last_analyzed || null,
+                    last_analyzed: statusData.last_analyzed || null,
                 },
                 intent: {},
                 pages: []
@@ -85,7 +97,7 @@ export async function statusCommand(options) {
         // Output beautiful terminal dashboard
         console.log('');
         console.log(chalk.bold('SEO.md Status Dashboard') + chalk.dim(` — ${data.identity?.brand || 'Brand'} (${data.site?.domain || 'domain'})`));
-        console.log(chalk.dim(`Last analyzed: ${aeoAnalysis.last_analyzed || 'N/A'}`));
+        console.log(chalk.dim(`Last analyzed: ${statusData.last_analyzed || 'N/A'}`));
         console.log(chalk.dim('─'.repeat(60)));
         
         // Overall block

package/src/commands/sync.js

@@ -83,14 +83,14 @@ export async function syncCommand(options) {
 
         spinner.text = 'Updating repository files...';
 
-        // Writeback to SEO.md
+        // Writeback to .seo/STATUS.yml
         await writeAnalysisToSeoMd(doc, results, cwd);
 
-        // Writeback to SEO.REVERSE.md
+        // Writeback to .seo/REVERSE.md
         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!'));
@@ -109,9 +109,9 @@ export async function syncCommand(options) {
         console.log(`Next Analysis Target  : ${chalk.dim(aeo.next_analysis)}`);
         console.log('----------------------------');
         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/STATUS.yml updated.'));
+        console.log(chalk.green('✔ .seo/REVERSE.md updated.'));
+        console.log(chalk.green('✔ .seo/pages/ playbooks synchronized.'));
         console.log('');
 
     } catch (err) {

package/src/generators/directory.js

@@ -5,14 +5,12 @@ 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),
@@ -27,49 +25,55 @@ export async function createSeomdDir(cwd, answers) {
             'utf8'
         );
     }
-
-    // Create initial empty report
-    const date = new Date().toISOString().split('T')[0];
-    await fs.writeFile(
-        path.join(seomdDir, 'reports', `${date}.md`),
-        generateInitialReport(brand, domain, date),
-        'utf8'
-    );
 }
 
 function generateSeomdReadme(brand, domain) {
-    return `# .seomd/
+    return `# .seo/
 
 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.
+\`.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/
+.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
+├── STATUS.yml      # gap scores and citation metrics (platform generated)
+└── REVERSE.md      # competitor playbooks (platform generated)
 \`\`\`
 
 ## 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 |
+| \`.seo/pages/\` | tracked | actionable playbooks belong in code review |
+| \`.seo/STATUS.yml\` | tracked | gap scores represent current project state |
+| \`.seo/REVERSE.md\` | tracked | competitor intel is project state |
+
+## How to configure SEO.md
+
+\`SEO.md\` is your declarative configuration file. It tells the AI optimization platform exactly what you care about. Here is a guide on how to fill it out:
+
+### 1. Intent (Queries)
+Add queries your buyers actually type into AI engines. Think about what someone asks ChatGPT or Perplexity when they are looking for a solution like yours.
+
+### 2. Pages
+Declare the key pages on your site. For each page, set its priority and status (\`live | draft | planned\`). The platform will scan these and generate playbooks for each one.
+
+### 3. AI Engine Optimization (AEO) Rules
+Set the strict guidelines you want your writers or AI to follow (e.g. \`answer_first_format: true\`).
+
+### 4. Platform Connection
+To enable live writebacks, connect your platform:
+1. Connect at https://seomd.dev/connect
+2. Add \`SEOMD_API_KEY\` to your \`.env\`
+3. Run \`npx seomd analyze\`
 
-\`.seomd/reports/\` is added to \`.gitignore\` automatically by \`seomd init\`.
+**Note: Never commit your API key to version control.**
 
 ## When to run what
 
@@ -107,22 +111,11 @@ Each \`pages/<id>.md\` contains:
 | 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 |
+| \`.seo/STATUS.yml\` | platform | no |
+| \`.seo/REVERSE.md\` | platform | no |
+| \`.seo/pages/*.md\` | platform | no |
 
 Platform-generated files are overwritten on each \`analyze\` or \`sync\`.
-
-## Platform connection
-
-To enable live writebacks:
-
-1. Connect at https://seomd.dev/connect
-2. Add \`SEOMD_API_KEY\` to your \`.env\`
-3. Run \`npx seomd analyze\`
-
-_Note: Never commit API keys or \`.env\` files to version control._
 `;
 }
 
@@ -160,28 +153,3 @@ fastest_win:
 suggested_content_outline: []
 `;
 }
-
-function generateInitialReport(brand, domain, date) {
-    return `# SEO.md Report — ${date}
-
-## ${brand} (${domain})
-
-### Initial report — run \`npx seomd analyze\` to populate
-
-date: ${date}
-brand: "${brand}"
-domain: ${domain}
-overall_citation_rate: null
-overall_gap_score: null
-
-intent_summary:
-  informational: null
-  comparison: null
-  transactional: null
-  reputational: null
-  category: null
-
-top_opportunities: []
-completed_wins: []
-`;
-}

package/src/templates/blog/SEO.md

@@ -4,14 +4,6 @@
 
 ### spec v1.0 | <https://seomd.dev>
 
-#### generated: {{date}}
-
-## FIELD OWNERSHIP
-
-### no prefix     = founder declares (you own this)
-
-### _analysis:    = platform writes back (do not edit manually)
-
 ## Site
 
 site:
@@ -36,8 +28,6 @@ identity:
 
 keywords:
 
-### FOUNDER DECLARES
-
   primary: "{{primary_keyword}}"
   secondary: []               # add your secondary keywords
   negative:                   # terms that dilute your intent signal
@@ -52,30 +42,10 @@ keywords:
   long_tail: []               # add long-tail variations
   seasonal: null              # add seasonal terms if applicable
 
-### PLATFORM WRITES BACK
-
-  _analysis:
-    source: null
-    primary_search_volume: null
-    primary_intent_type: null
-    primary_trend: null
-    recommended_secondary: []
-    negative_additions_suggested: []
-    last_analyzed: null
-    next_analysis: null
-
 ## Intent
 
 intent:
 
-### FOUNDER DECLARES
-
-#### Add queries your buyers actually type into AI engines
-
-#### Tip: think about what someone asks ChatGPT or Perplexity
-
-#### when they are looking for a solution like yours
-
   informational:
     priority: critical
     queries:
@@ -108,47 +78,11 @@ intent:
       - "best {{primary_keyword}}"
       - "top {{primary_keyword}} 2026"
 
-### PLATFORM WRITES BACK
-
-  _analysis:
-    source: null
-    last_analyzed: null
-    next_analysis: null
-    informational:
-      citation_rate: null
-      top_cited_competitor: null
-      gap_score: null
-      trend: null
-    comparison:
-      citation_rate: null
-      top_cited_competitor: null
-      gap_score: null
-      trend: null
-    transactional:
-      citation_rate: null
-      top_cited_competitor: null
-      gap_score: null
-      trend: null
-    reputational:
-      citation_rate: null
-      top_cited_competitor: null
-      gap_score: null
-      trend: null
-    category:
-      citation_rate: null
-      top_cited_competitor: null
-      gap_score: null
-      trend: null
-
 ## Pages
 
 pages:
   site_type: blog
 
-### FOUNDER DECLARES
-
-#### status: live | draft | planned
-
   required:
     - id: homepage
       url: /
@@ -186,21 +120,10 @@ pages:
       status: planned
       priority: 6
 
-### PLATFORM WRITES BACK
-
-  _analysis:
-    source: null
-    last_analyzed: null
-    pages: []
-    missing_pages: []
-    build_order_recommendation: []
-
 ## Copy
 
 copy:
 
-### FOUNDER DECLARES
-
   h1_contains_primary_keyword: true
   meta_description_length: 150-160
   meta_description_includes_cta: true
@@ -215,8 +138,6 @@ copy:
 
 structure:
 
-### FOUNDER DECLARES
-
   answer_first: true           # direct answer in first 50 words
   faq_section_required: true   # on all key pages
   faq_minimum_questions: 6
@@ -229,8 +150,6 @@ structure:
 
 authority:
 
-### FOUNDER DECLARES
-
   cite_sources: true
   expert_quotes: false         # set true when you have quotes
   eeat_signals:
@@ -243,8 +162,6 @@ authority:
 
 schema:
 
-### FOUNDER DECLARES
-
   types:
     - Article
     - Person
@@ -258,8 +175,6 @@ schema:
 
 crawl:
 
-### FOUNDER DECLARES
-
   sitemap: /sitemap.xml
   robots_txt: /robots.txt
   allow_ai_bots: true
@@ -282,8 +197,6 @@ crawl:
 
 performance:
 
-### FOUNDER DECLARES
-
   lcp: 2.5s
   cls: 0.1
   fid: 100ms
@@ -294,10 +207,6 @@ performance:
 
 aeo:
 
-### FOUNDER DECLARES
-
-### AI Engine Optimization rules
-
   answer_first_format: true
   faq_on_all_key_pages: true
   structured_data_priority: high
@@ -305,27 +214,10 @@ aeo:
   competitors_to_monitor:
 {{competitors_to_monitor}}
 
-### PLATFORM WRITES BACK
-
-  _analysis:
-    source: null
-    overall_citation_rate: null
-    overall_gap_score: null
-    engines_tracked:
-      - chatgpt
-      - perplexity
-      - claude
-      - gemini
-      - grok
-    last_analyzed: null
-    next_analysis: null
-
 ## Monitoring
 
 monitoring:
 
-### FOUNDER DECLARES
-
   sync_schedule: monthly       # monthly | weekly | on_demand
   auto_commit: false           # platform commits directly to repo
   pr_mode: true                # open PR instead of direct commit
@@ -335,14 +227,7 @@ monitoring:
 
 ## Platform Connection
 
-### Connect at <https://seomd.dev/connect>
-
-### Add SEOMD_API_KEY to your .env file
-
-### Never commit your API key to version control
-
 platform:
   provider: null               # foxcite | manual | ahrefs | semrush
   project_id: null
 
-### api_key: loaded from SEOMD_API_KEY environment variable