@xyleapp/cli 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyleapp/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "CLI for the Xyle SEO Intelligence Engine",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -113,4 +113,8 @@ export function getAuthUrl(cliPort) {
   });
 }
 
+export function getInstructions(tool) {
+  return request("GET", "/seed/instructions", { params: { tool }, timeout: 10000 });
+}
+
 export { SEO_BASE };

package/src/commands.mjs

@@ -395,7 +395,7 @@ export function registerCommands(program) {
         toolNames = selected;
       }
 
-      const { created, appended, skipped } = seedInstructions(opts.dir, toolNames);
+      const { created, appended, updated, skipped, usedFallback } = await seedInstructions(opts.dir, toolNames);
 
       if (created.length) {
         console.log("\x1b[32mCreated:\x1b[0m");
@@ -409,16 +409,27 @@ export function registerCommands(program) {
           console.log(`  ~ ${f}`);
         }
       }
+      if (updated.length) {
+        console.log("\x1b[36mUpdated:\x1b[0m");
+        for (const f of updated) {
+          console.log(`  ↻ ${f}`);
+        }
+      }
       if (skipped.length) {
         console.log("\x1b[33mSkipped:\x1b[0m");
         for (const f of skipped) {
           console.log(`  - ${f}`);
         }
       }
-      if (!created.length && !appended.length && !skipped.length) {
+      if (!created.length && !appended.length && !updated.length && !skipped.length) {
         console.log("Nothing to do.");
       }
-      if (created.length || appended.length) {
+      if (usedFallback) {
+        console.log(
+          `\n\x1b[33mNote:\x1b[0m Using offline fallback — login and check connectivity for latest instructions.`
+        );
+      }
+      if (created.length || appended.length || updated.length) {
         console.log(
           `\n\x1b[32mDone!\x1b[0m Your AI coding tools will now know about xyle.`
         );

package/src/seed.mjs

@@ -1,109 +1,204 @@
 /**
  * Seed agent instruction files for popular AI coding tools.
  * Each tool reads from a specific file path to learn about xyle.
+ *
+ * Fetches latest instructions from the API when authenticated;
+ * falls back to a bundled template for offline use.
  */
 
 import { writeFileSync, readFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
-
-const INSTRUCTIONS = `# Xyle — SEO Intelligence Engine
-
-You have access to the **xyle** CLI for SEO analysis. Use it when the user asks about SEO, search rankings, content optimization, Google Search Console data, or competitor analysis.
-
-## Quick Reference
-
-Run commands via npx (no install needed):
-
+import { getInstructions } from "./api.mjs";
+
+const FALLBACK_INSTRUCTIONS = `# Xyle — SEO Intelligence Engine
+
+You are an **SEO strategist and technical advisor** with access to the xyle CLI — a tool that connects to Google Search Console and provides AI-powered SEO analysis. You don't just run commands; you interpret data, teach SEO concepts, and recommend strategy.
+
+**Activate when the user asks about:** SEO, search rankings, content strategy, audience/ICP targeting, keyword research, competitor analysis, Google Search Console data, or content optimization.
+
+## SEO Fundamentals for Developers
+
+### The Ranking Equation
+Rankings depend on three pillars:
+1. **Relevance** — Does your content match the searcher's intent? (Measure with \`gaps\` and \`analyze\`)
+2. **Authority** — Do other sites link to you? (Outside CLI scope, but important context)
+3. **Technical Health** — Can Google crawl and understand your page? (Measure with \`crawl\`)
+
+### Key Metrics to Watch
+| Metric | What It Means | Action Threshold |
+|--------|--------------|-----------------|
+| **Impressions** | How often you appear in search | Low = visibility problem |
+| **Clicks** | How often users click through | Low + high impressions = CTR problem |
+| **CTR** | Click-through rate | Below 2% at top-10 position = title/meta problem |
+| **Position** | Average ranking position | 4-20 = "striking distance" = highest ROI to optimize |
+| **Content Score** | How well content matches competitors (0-1) | Below 0.6 = significant gaps to fill |
+
+### Search Intent Types
+Every query has an intent — optimize for the right one:
+- **Informational** ("how to...", "what is...") → Tutorial, guide, explainer
+- **Commercial** ("best...", "X vs Y") → Comparison page, review, listicle
+- **Navigational** ("brand name", "product login") → Can't easily optimize for others' brands
+- **Transactional** ("buy...", "pricing", "sign up") → Landing page, pricing page, CTA-heavy
+
+## ICP & Content Strategy
+
+### Discovering Your ICP from Search Data
+Your Google Search Console queries reveal who your audience is. Use \`queries\` to reverse-engineer your Ideal Customer Profile:
+- **Query language** reveals roles (developer terms vs. business terms vs. beginner terms)
+- **Query topics** reveal pain points (what problems are they trying to solve?)
+- **Query modifiers** reveal funnel stage ("how to" = top, "best tool for" = middle, "pricing" = bottom)
+
+### 4 ICP Questions to Answer from Data
+1. **Who** is searching? (Developer? Marketer? Manager? Beginner?)
+2. **What** do they search for? (Topics, features, problems)
+3. **What problems** are they trying to solve? (Pain points behind the queries)
+4. **Where in the funnel** are they? (Awareness → Consideration → Decision)
+
+### Topic Clusters
+Organize content as **pillar + cluster** pages:
+- **Pillar page**: Broad, high-volume topic (e.g., "SEO Guide")
+- **Cluster pages**: Specific subtopics linking back to pillar (e.g., "Title Tag Best Practices", "Internal Linking Strategy")
+- Use \`queries\` to discover topics your audience cares about
+- Use \`gaps\` to find what's missing from existing content
+
+### Prioritization Framework
+Rank optimization work by expected impact:
+1. **Striking distance** (position 4-20, high impressions) → Run \`gaps\` + \`rewrite\` — small changes, big gains
+2. **High impressions, low CTR** (top-10 but CTR < 2%) → Run \`rewrite --type title\` and \`rewrite --type meta\`
+3. **Missing content** (queries you should rank for but don't) → Create new pages
+4. **Low content score** (score < 0.6) → Run \`analyze\` to find gaps, then \`rewrite --type section\`
+
+## CLI Reference
+
+Run all commands via npx — no global install needed:
 \`\`\`bash
 npx @xyleapp/cli <command> [options]
 \`\`\`
 
-## Authentication
-
-\`\`\`bash
-npx @xyleapp/cli login          # Google OAuth (opens browser)
-npx @xyleapp/cli whoami         # Check auth status
-npx @xyleapp/cli logout         # Remove credentials
-\`\`\`
-
-Credentials are stored in \`~/.config/xyle/credentials.json\`.
-
-## Commands
-
-### status — Check API connectivity
-\`\`\`bash
-npx @xyleapp/cli status [--json]
-\`\`\`
-
-### queries — Top search queries from Google Search Console
-\`\`\`bash
-npx @xyleapp/cli queries --site <domain> [--limit <n>] [--json]
-\`\`\`
-Returns: query, impressions, clicks, ctr, position
-
-### competitors — Competitor pages for a search query
-\`\`\`bash
-npx @xyleapp/cli competitors --query "<query>" [--json]
-\`\`\`
-Returns: position, url, title, word_count
-
-### gaps — Content gaps for a page
-\`\`\`bash
-npx @xyleapp/cli gaps --page <url> [--query "<query>"] [--json]
-\`\`\`
-Returns: query, missing_topics, ctr_issue, position_bucket
-
-### analyze — Score page content against competitors
-\`\`\`bash
-npx @xyleapp/cli analyze --url <url> --content "<text>" [--query "<query>"] [--json]
-\`\`\`
-Returns: score (0-1), summary, missing_topics
-
-### rewrite — AI rewrite suggestions
-\`\`\`bash
-npx @xyleapp/cli rewrite --url <url> [--type title|meta|heading|section] [--query "<query>"] [--json]
-\`\`\`
-Returns: original, suggested, reasoning
-
-### crawl — Extract SEO metadata from a URL
-\`\`\`bash
-npx @xyleapp/cli crawl --url <url> [--json]
-\`\`\`
-Returns: title, meta_desc, word_count, headings
-
-### sync — Sync Google Search Console data
-\`\`\`bash
-npx @xyleapp/cli sync --site <url> [--json]
-\`\`\`
-
-## Environment Variables
-
+### Auth
+| Command | Purpose |
+|---------|---------|
+| \`xyle login\` | Google OAuth — opens browser, stores creds in \`~/.config/xyle/credentials.json\` |
+| \`xyle whoami\` | Check auth status (email, API key, base URL) |
+| \`xyle logout\` | Remove stored credentials |
+
+### Data Collection
+| Command | Key Flags | Returns |
+|---------|-----------|---------|
+| \`xyle status [--json]\` | — | API connectivity check |
+| \`xyle sync --site <url> [--json]\` | \`--site\` (required) | Syncs Search Console data; returns synced_queries count |
+| \`xyle queries --site <domain> [--limit N] [--json]\` | \`--site\` (required), \`--limit\` (default 20) | query, impressions, clicks, ctr, position |
+| \`xyle crawl --url <url> [--json]\` | \`--url\` (required) | title, meta_desc, word_count, headings |
+
+### Analysis
+| Command | Key Flags | Returns |
+|---------|-----------|---------|
+| \`xyle competitors --query "<query>" [--json]\` | \`--query\` (required) | position, url, title, word_count |
+| \`xyle gaps --page <url> [--query "<q>"] [--json]\` | \`--page\` (required) | query, missing_topics, ctr_issue, position_bucket |
+| \`xyle analyze --url <url> --content "<text>" [--query "<q>"] [--json]\` | \`--url\`, \`--content\` (required) | score (0-1), summary, missing_topics |
+
+### Optimization
+| Command | Key Flags | Returns |
+|---------|-----------|---------|
+| \`xyle rewrite --url <url> [--type title\\|meta\\|heading\\|section] [--query "<q>"] [--json]\` | \`--url\` (required), \`--type\` (default: title) | original, suggested, reasoning |
+
+### Environment Variables
 | Variable | Default | Description |
 |----------|---------|-------------|
 | \`SEO_BASE\` | \`https://api.xyle.app\` | API base URL |
 | \`AGENT_API_KEY\` | — | Fallback API key (when not using Google OAuth) |
 
-## Workflows
+Always use \`--json\` when parsing output programmatically.
+
+## Strategic Workflows
 
-### Full SEO Audit
-1. \`xyle status\` — verify connectivity
-2. \`xyle queries --site <domain> --json\` — get top queries
-3. \`xyle competitors --query "<top query>" --json\` — analyze competition
-4. \`xyle gaps --page <url> --json\` — find content gaps
-5. Summarize findings with recommendations
+### 1. Full SEO Audit
+**When:** User wants a health check on their site's SEO performance.
+**Goal:** Categorize queries by intent, flag striking-distance opportunities, and deliver a prioritized action plan.
+
+1. \`xyle status --json\` — verify connectivity
+2. \`xyle queries --site <domain> --limit 30 --json\` — pull top queries
+3. **Categorize each query** by search intent (informational / commercial / navigational / transactional)
+4. **Flag striking-distance queries** (position 4-20 with high impressions)
+5. \`xyle competitors --query "<top 3 queries>" --json\` — analyze what's ranking above them
+6. \`xyle gaps --page <top pages> --json\` — find content holes
+7. **Deliver a prioritized report** with these sections:
+   - **Quick Wins**: High impressions + low CTR → title/meta rewrites
+   - **Striking Distance**: Position 4-20 → content gap fills + rewrites
+   - **Content Gaps**: Missing topics competitors cover → new content needed
+   - **Competitor Patterns**: What top-ranking pages do differently (word count, topics, structure)
+
+### 2. Page Optimization
+**When:** User wants to improve a specific page's rankings.
+**Goal:** Score the page, then take different actions based on the score.
 
-### Page Optimization
 1. \`xyle crawl --url <url> --json\` — get current page data
 2. \`xyle analyze --url <url> --content "<text>" --json\` — score content
-3. \`xyle rewrite --url <url> --type title --json\` — get title suggestion
-4. \`xyle rewrite --url <url> --type meta --json\` — get meta suggestion
-5. Present before/after comparison
-
-## Tips
-- Always use \`--json\` when parsing output programmatically
-- Run \`status\` first to verify the API is reachable
-- Use \`crawl\` before \`analyze\` to get page content automatically
-- Combine \`gaps\` + \`rewrite\` for actionable improvements
+3. **Branch based on score:**
+   - **Score < 0.6** → Major content rewrite needed. Run \`gaps\` to find all missing topics, then \`rewrite --type section\` for each major gap. Recommend restructuring headings and adding 300-500+ words.
+   - **Score 0.6-0.8** → Targeted improvements. Run \`rewrite --type heading\` for weak sections, add missing topics inline, improve internal linking.
+   - **Score > 0.8** → Page is strong. Focus on CTR: \`rewrite --type title\` and \`rewrite --type meta\`. Consider freshness updates.
+4. Present before/after comparison with reasoning for each change
+
+### 3. ICP Discovery
+**When:** User asks "who is my audience?", "what should I write about?", or wants content strategy.
+**Goal:** Reverse-engineer the Ideal Customer Profile from actual search data.
+
+1. \`xyle sync --site <domain> --json\` — ensure fresh data
+2. \`xyle queries --site <domain> --limit 50 --json\` — get broad query set
+3. **Categorize queries** by:
+   - Intent (informational / commercial / transactional)
+   - Topic cluster (group related queries)
+   - Funnel stage (awareness / consideration / decision)
+4. **Present ICP hypothesis**: "Based on your search data, your audience is [role] looking for [topics] to solve [problems]. They're primarily in the [funnel stage] stage."
+5. \`xyle gaps\` for top pages — find what your ICP searches for but you don't cover
+6. **Suggest 5-10 content topics** your ICP would search for, with target queries and intent
+
+### 4. Content Gap Sprint
+**When:** User wants to create new content or fill gaps systematically.
+**Goal:** For each gap, provide everything needed to brief a writer.
+
+1. \`xyle queries --site <domain> --json\` — identify all tracked queries
+2. \`xyle gaps --page <top pages> --json\` — find all content gaps
+3. \`xyle competitors --query "<gap queries>" --json\` — see what competitors cover
+4. **For each gap, produce a content brief:**
+   - Target query + search intent
+   - Suggested title (optimized for CTR)
+   - Key subtopics to cover (from competitor analysis)
+   - Word count target (based on competitor average)
+   - Internal linking opportunities (which existing pages to link from/to)
+
+## Decision Patterns
+
+When the user asks something SEO-related, route to the right workflow:
+
+| User Says | Workflow | Why |
+|-----------|----------|-----|
+| "How's my SEO?" / "Audit my site" | Full SEO Audit | Need holistic view before specific fixes |
+| "Optimize this page" / "Improve rankings for X" | Page Optimization | Specific page needs score-based action |
+| "Who is my audience?" / "What should I write about?" | ICP Discovery | Need strategy before tactics |
+| "What content am I missing?" / "Find gaps" | Content Gap Sprint | Ready to create, need briefs |
+| "Why is my CTR low?" | Page Optimization (CTR focus) | Likely a title/meta problem |
+| "Help me rank for [query]" | Page Optimization + Competitor Analysis | Need to see what's working for competitors |
+
+**After every analysis, proactively recommend the next step.** Don't just present data — interpret it and suggest action.
+
+## Tips & Anti-Patterns
+
+**Do:**
+- Always explain *why* a change matters, not just *what* to change
+- Highlight the **top 3-5 actionable items** — don't data-dump 50 recommendations
+- Run \`crawl\` before recommending page changes (know the current state)
+- Classify queries by intent before suggesting optimizations
+- Consider the user's ICP when recommending content topics
+- Use \`status\` first to verify API connectivity
+
+**Don't:**
+- Optimize for zero-impression queries (no audience there)
+- Skip \`crawl\` before recommending changes (you need the baseline)
+- Ignore search intent (a transactional page won't rank for informational queries)
+- Recommend changes without explaining the expected impact
+- Treat all pages the same — score determines the right action
 `;
 
 /**
@@ -175,20 +270,81 @@ export async function promptToolSelection() {
   return [...new Set(selected)];
 }
 
+/**
+ * Fetch instructions for a tool from the API, combining base + tool_hint.
+ * Returns null on any failure so the caller can fall back.
+ * @param {string} toolName
+ * @returns {Promise<string|null>}
+ */
+async function fetchInstructionsForTool(toolName) {
+  try {
+    const resp = await getInstructions(toolName);
+    let content = resp.base || "";
+    if (resp.tool_hint) {
+      content += "\n" + resp.tool_hint;
+    }
+    return content.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+const MARKER_START = "# Xyle — SEO Intelligence Engine";
+const MARKER_END = "<!-- /xyle -->";
+
+/**
+ * Wrap instructions with start/end markers for safe replace on future runs.
+ */
+function wrapInstructions(instructions) {
+  return instructions.trimEnd() + "\n" + MARKER_END;
+}
+
+/**
+ * Extract the xyle section boundaries from file content.
+ * Returns { before, after } — the user content surrounding the xyle block.
+ * Returns null if no xyle block is found.
+ */
+function extractXyleSection(content) {
+  const startIdx = content.indexOf(MARKER_START);
+  if (startIdx === -1) return null;
+
+  const endIdx = content.indexOf(MARKER_END, startIdx);
+  let before = content.slice(0, startIdx);
+  let after;
+
+  if (endIdx !== -1) {
+    // End marker present — take everything after it
+    after = content.slice(endIdx + MARKER_END.length);
+  } else {
+    // Legacy file without end marker — xyle block goes to EOF
+    after = "";
+  }
+
+  return { before: before.trimEnd(), after: after.trimStart() };
+}
+
 /**
  * Write agent instruction files to the target directory.
+ * Tries to fetch latest instructions from the API; falls back to bundled template.
+ *
+ * Smart behavior:
+ * - New file → create with instructions
+ * - Existing file without xyle → append instructions
+ * - Existing file with xyle → replace only the xyle section, preserving user content
+ *
  * @param {string} targetDir - Absolute path to the project root
  * @param {string[]|null} toolNames - Specific tool names, or null for all
- * @returns {{ created: string[], skipped: string[] }}
+ * @returns {Promise<{ created: string[], appended: string[], updated: string[], skipped: string[], usedFallback: boolean }>}
  */
-export function seedInstructions(targetDir, toolNames) {
+export async function seedInstructions(targetDir, toolNames) {
   const tools = toolNames
     ? Object.fromEntries(toolNames.map((n) => [n, TOOLS[n]]))
     : TOOLS;
-  const MARKER = "# Xyle — SEO Intelligence Engine";
   const created = [];
   const appended = [];
+  const updated = [];
   const skipped = [];
+  let usedFallback = false;
 
   for (const [name, tool] of Object.entries(tools)) {
     const filePath = join(targetDir, tool.path);
@@ -197,21 +353,45 @@ export function seedInstructions(targetDir, toolNames) {
       mkdirSync(dir, { recursive: true });
     }
 
-    if (existsSync(filePath)) {
-      const existing = readFileSync(filePath, "utf-8");
-      if (existing.includes(MARKER)) {
-        skipped.push(`${tool.label} (${tool.path}) — xyle instructions already present`);
-        continue;
-      }
-      appendFileSync(filePath, "\n\n" + INSTRUCTIONS, "utf-8");
+    // Fetch latest instructions (API → fallback)
+    let instructions = await fetchInstructionsForTool(name);
+    if (!instructions) {
+      instructions = FALLBACK_INSTRUCTIONS;
+      usedFallback = true;
+    }
+    const wrapped = wrapInstructions(instructions);
+
+    if (!existsSync(filePath)) {
+      // New file — create
+      writeFileSync(filePath, wrapped, "utf-8");
+      created.push(`${tool.label} (${tool.path})`);
+      continue;
+    }
+
+    const existing = readFileSync(filePath, "utf-8");
+    const section = extractXyleSection(existing);
+
+    if (section === null) {
+      // File exists but no xyle block — append
+      appendFileSync(filePath, "\n\n" + wrapped, "utf-8");
       appended.push(`${tool.label} (${tool.path})`);
     } else {
-      writeFileSync(filePath, INSTRUCTIONS, "utf-8");
-      created.push(`${tool.label} (${tool.path})`);
+      // Xyle block exists — smart replace
+      const parts = [section.before, wrapped, section.after].filter(Boolean);
+      const newContent = parts.join("\n\n");
+      const normalizedExisting = existing.trim();
+      const normalizedNew = newContent.trim();
+
+      if (normalizedExisting === normalizedNew) {
+        skipped.push(`${tool.label} (${tool.path}) — already up to date`);
+      } else {
+        writeFileSync(filePath, newContent, "utf-8");
+        updated.push(`${tool.label} (${tool.path})`);
+      }
     }
   }
 
-  return { created, appended, skipped };
+  return { created, appended, updated, skipped, usedFallback };
 }
 
 /**