seomd-cli 1.2.0 → 1.4.0

package/src/templates/saas/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: medium
     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: saas
 
-### FOUNDER DECLARES
-
-#### status: live | draft | planned
-
   required:
     - id: homepage
       url: /
@@ -210,21 +144,10 @@ pages:
       status: planned
       priority: 10
 
-### 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
@@ -239,8 +162,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
@@ -253,8 +174,6 @@ structure:
 
 authority:
 
-### FOUNDER DECLARES
-
   cite_sources: true
   expert_quotes: false         # set true when you have quotes
   eeat_signals:
@@ -267,8 +186,6 @@ authority:
 
 schema:
 
-### FOUNDER DECLARES
-
   types:
     - SoftwareApplication
     - Organization
@@ -282,8 +199,6 @@ schema:
 
 crawl:
 
-### FOUNDER DECLARES
-
   sitemap: /sitemap.xml
   robots_txt: /robots.txt
   allow_ai_bots: true
@@ -306,8 +221,6 @@ crawl:
 
 performance:
 
-### FOUNDER DECLARES
-
   lcp: 2.5s
   cls: 0.1
   fid: 100ms
@@ -318,10 +231,6 @@ performance:
 
 aeo:
 
-### FOUNDER DECLARES
-
-### AI Engine Optimization rules
-
   answer_first_format: true
   faq_on_all_key_pages: true
   structured_data_priority: high
@@ -329,27 +238,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
@@ -359,14 +251,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

package/src/utils/writeback.js

@@ -1,12 +1,11 @@
 import fs from 'fs-extra';
 import path from 'path';
 import YAML from 'yaml';
-import { writeSeoMd } from './parser.js';
 
 /**
- * Merges platform analysis blocks back into the SEO.md YAML document.
+ * Writes platform analysis blocks into the .seo/STATUS.yml file.
  * 
- * @param {YAML.Document} doc - The YAML Document of SEO.md
+ * @param {YAML.Document} doc - The YAML Document of SEO.md (deprecated, but kept for signature compatibility)
  * @param {any} response - The API response from analyze/sync
  * @param {string} cwd - Current working directory
  */
@@ -14,61 +13,60 @@ export async function writeAnalysisToSeoMd(doc, response, cwd) {
     const lastAnalyzed = response.aeo_analysis.last_analyzed;
     const nextAnalysis = response.aeo_analysis.next_analysis;
 
-    // 1. Update AEO analysis
-    doc.setIn(['aeo', '_analysis', 'source'], 'foxcite');
-    doc.setIn(['aeo', '_analysis', 'overall_citation_rate'], response.aeo_analysis.overall_citation_rate);
-    doc.setIn(['aeo', '_analysis', 'overall_gap_score'], response.aeo_analysis.overall_gap_score);
-    doc.setIn(['aeo', '_analysis', 'engines_tracked'], response.aeo_analysis.engines_tracked);
-    doc.setIn(['aeo', '_analysis', 'last_analyzed'], lastAnalyzed);
-    doc.setIn(['aeo', '_analysis', 'next_analysis'], nextAnalysis);
-
-    // 2. Update Intent analysis
-    doc.setIn(['intent', '_analysis', 'source'], 'foxcite');
-    doc.setIn(['intent', '_analysis', 'last_analyzed'], lastAnalyzed);
-    doc.setIn(['intent', '_analysis', 'next_analysis'], nextAnalysis);
+    const statusData = {
+        source: 'foxcite',
+        last_analyzed: lastAnalyzed,
+        next_analysis: nextAnalysis,
+        aeo: {
+            overall_citation_rate: response.aeo_analysis.overall_citation_rate,
+            overall_gap_score: response.aeo_analysis.overall_gap_score,
+            engines_tracked: response.aeo_analysis.engines_tracked,
+        },
+        intent: {},
+        pages: {
+            pages: response.page_analysis.map(p => ({
+                id: p.id,
+                url: p.url,
+                citation_rate: p.citation_rate,
+                gap_score: p.gap_score,
+                top_cited_competitor: p.top_cited_competitor
+            })),
+            missing_pages: [],
+            build_order_recommendation: []
+        },
+        keywords: {}
+    };
 
     const categories = ['informational', 'comparison', 'transactional', 'reputational', 'category'];
     for (const cat of categories) {
         if (response.intent_analysis && response.intent_analysis[cat]) {
-            doc.setIn(['intent', '_analysis', cat, 'citation_rate'], response.intent_analysis[cat].citation_rate);
-            doc.setIn(['intent', '_analysis', cat, 'top_cited_competitor'], response.intent_analysis[cat].top_cited_competitor);
-            doc.setIn(['intent', '_analysis', cat, 'gap_score'], response.intent_analysis[cat].gap_score);
-            doc.setIn(['intent', '_analysis', cat, 'trend'], response.intent_analysis[cat].trend || 'stable');
+            statusData.intent[cat] = {
+                citation_rate: response.intent_analysis[cat].citation_rate,
+                top_cited_competitor: response.intent_analysis[cat].top_cited_competitor,
+                gap_score: response.intent_analysis[cat].gap_score,
+                trend: response.intent_analysis[cat].trend || 'stable'
+            };
         }
     }
 
-    // 3. Update Pages analysis
-    doc.setIn(['pages', '_analysis', 'source'], 'foxcite');
-    doc.setIn(['pages', '_analysis', 'last_analyzed'], lastAnalyzed);
-
-    const pageSummaries = response.page_analysis.map(p => ({
-        id: p.id,
-        url: p.url,
-        citation_rate: p.citation_rate,
-        gap_score: p.gap_score,
-        top_cited_competitor: p.top_cited_competitor
-    }));
-    doc.setIn(['pages', '_analysis', 'pages'], pageSummaries);
-    doc.setIn(['pages', '_analysis', 'missing_pages'], []);
-    doc.setIn(['pages', '_analysis', 'build_order_recommendation'], []);
-
-    // 4. Update Keywords analysis
-    doc.setIn(['keywords', '_analysis', 'source'], 'foxcite');
-    doc.setIn(['keywords', '_analysis', 'last_analyzed'], lastAnalyzed);
-    doc.setIn(['keywords', '_analysis', 'next_analysis'], nextAnalysis);
-
-    // Write back to SEO.md
-    await writeSeoMd(doc, cwd);
+    const seomdDir = path.join(cwd, '.seo');
+    await fs.ensureDir(seomdDir);
+    const statusPath = path.join(seomdDir, 'STATUS.yml');
+    
+    const header = `# .seo/STATUS.yml\n#\n# This file is auto-generated by your connected SEO.md platform.\n# Do not edit manually — run \`npx seomd analyze\` to update.\n# Run \`npx seomd sync\` to pull latest intelligence.\n\n`;
+    await fs.writeFile(statusPath, header + YAML.stringify(statusData), 'utf8');
 }
 
 /**
- * Generates and writes the SEO.REVERSE.md file.
+ * Generates and writes the .seo/REVERSE.md file.
  * 
  * @param {string} cwd - Current working directory
  * @param {any} response - The API response from analyze/sync
  */
 export async function writeReverseMd(cwd, response, defaultDomain = 'example.com', defaultBrand = 'My Brand') {
-    const reversePath = path.join(cwd, 'SEO.REVERSE.md');
+    const seomdDir = path.join(cwd, '.seo');
+    await fs.ensureDir(seomdDir);
+    const reversePath = path.join(seomdDir, 'REVERSE.md');
 
     const reversePages = response.page_analysis.map(p => ({
         id: p.id,
@@ -97,26 +95,20 @@ export async function writeReverseMd(cwd, response, defaultDomain = 'example.com
         pages: reversePages
     };
 
-    const header = `# SEO.REVERSE.md
-#
-# This file is generated by the foxcite platform.
-# Do not edit manually — run \`npx seomd analyze\` to update.
-# Run \`npx seomd sync\` to pull latest intelligence.
-
-`;
+    const header = `# .seo/REVERSE.md\n#\n# This file is auto-generated by your connected SEO.md platform.\n# Do not edit manually — run \`npx seomd analyze\` to update.\n# Run \`npx seomd sync\` to pull latest intelligence.\n\n`;
 
     const yamlContent = YAML.stringify(reverseDoc);
     await fs.writeFile(reversePath, header + yamlContent, 'utf8');
 }
 
 /**
- * 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);