content-grade 1.0.4 → 1.0.6

package/bin/content-grade.js

@@ -320,6 +320,8 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
     console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
     blank();
+    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    blank();
     process.exit(1);
   }
 
@@ -464,7 +466,7 @@ async function cmdAnalyze(filePath) {
   // Upsell — show Pro path after user has seen value
   blank();
   if (isProUser()) {
-    console.log(`  ${D}Pro active · ${CY}contentgrade.dev${R}`);
+    console.log(`  ${D}Pro active · ${CY}content-grade.github.io/Content-Grade${R}`);
   } else {
     const usage = getUsage();
     const remaining = Math.max(0, FREE_DAILY_LIMIT - usage.count);
@@ -472,7 +474,10 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${MG}${B}Unlock batch mode:${R}  ${CY}content-grade activate${R}`);
     console.log(`  ${D}  · Analyze entire directories in one command${R}`);
     console.log(`  ${D}  · 100 checks/day (${remaining} remaining today on free tier)${R}`);
-    console.log(`  ${D}  · Get a license at ${CY}contentgrade.dev${R}`);
+    console.log(`  ${D}  · Get a license at ${CY}content-grade.github.io/Content-Grade${R}`);
+    blank();
+    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    console.log(`  ${D}⭐ Unlock deeper analysis →${R} ${CY}npm i content-grade && content-grade activate${R}  ${D}| content-grade.github.io/Content-Grade/${R}`);
   }
   blank();
 }
@@ -501,7 +506,10 @@ Return ONLY valid JSON:
 Use full range: generic = <35, good = 65-79, great = 80+.`;
 
 async function cmdHeadline(text) {
-  if (!text || text.trim().length < 3) {
+  // Strip non-printable control characters (keep tab/newline/carriage-return)
+  if (text) text = text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '').trim();
+
+  if (!text || text.length < 3) {
     blank();
     fail(`No headline provided.`);
     blank();
@@ -516,6 +524,17 @@ async function cmdHeadline(text) {
     process.exit(2);
   }
 
+  // Guard: reject oversized input
+  const MAX_HEADLINE_BYTES = 2000;
+  if (text.length > MAX_HEADLINE_BYTES) {
+    blank();
+    fail(`Headline too long (${text.length} chars). Maximum is ${MAX_HEADLINE_BYTES} characters.`);
+    blank();
+    console.log(`  ${YL}Tip:${R} Trim your headline to the core message and try again.`);
+    blank();
+    process.exit(2);
+  }
+
   // Free tier daily limit
   const limitCheck = checkDailyLimit();
   if (!limitCheck.ok) {
@@ -526,6 +545,8 @@ async function cmdHeadline(text) {
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
     console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
     blank();
+    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    blank();
     process.exit(1);
   }
 
@@ -603,6 +624,11 @@ async function cmdHeadline(text) {
   hr();
   console.log(`  ${D}Compare two headlines:  ${CY}content-grade start${R}  → HeadlineGrader compare${R}`);
   blank();
+  if (!isProUser()) {
+    console.log(`  ${MG}Unlock unlimited analyses →${R}  ${CY}content-grade.github.io/Content-Grade/#pricing${R}`);
+    console.log(`  ${D}⭐ Unlock deeper analysis →${R} ${CY}npm i content-grade && content-grade activate${R}  ${D}| content-grade.github.io/Content-Grade/${R}`);
+    blank();
+  }
 }
 
 // ── Init command ──────────────────────────────────────────────────────────────
@@ -681,7 +707,7 @@ async function cmdInit() {
     console.log(`  ${CY}content-grade start${R}`);
     blank();
   }
-  console.log(`  ${D}Pro tier ($9/mo): 100 analyses/day (vs 50 free) + competitor comparison + URL audits${R}`);
+  console.log(`  ${D}Pro tier: 100 analyses/day + batch mode — ${CY}content-grade.github.io/Content-Grade${R}`);
   blank();
 }
 
@@ -710,37 +736,45 @@ async function cmdActivate() {
   console.log(`  ${D}  · ${CY}content-grade batch <dir>${R}${D} — analyze entire directories${R}`);
   console.log(`  ${D}  · 100 checks/day (vs 50 free)${R}`);
   blank();
-  console.log(`  ${D}Get a license: ${CY}contentgrade.dev${R}${D} → Pricing → Team${R}`);
-  blank();
-
-  process.stdout.write(`  ${CY}License key:${R} `);
-
-  const key = await new Promise(res => {
-    let input = '';
-    const isRaw = process.stdin.isTTY;
-    if (isRaw) process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', function onData(chunk) {
-      if (chunk === '\r' || chunk === '\n') {
-        if (isRaw) process.stdin.setRawMode(false);
-        process.stdin.pause();
-        process.stdin.removeListener('data', onData);
-        process.stdout.write('\n');
-        res(input.trim());
-      } else if (chunk === '\u0003') {
-        if (isRaw) process.stdin.setRawMode(false);
-        process.stdin.pause();
-        process.stdout.write('\n');
-        process.exit(0);
-      } else if (chunk === '\u007f') {
-        if (input.length > 0) { input = input.slice(0, -1); process.stdout.write('\b \b'); }
-      } else {
-        input += chunk;
-        process.stdout.write('*');
-      }
+  console.log(`  ${D}Get a license: ${CY}content-grade.github.io/Content-Grade${R}${D} → Pricing${R}`);
+  blank();
+
+  let key;
+  if (args[1] && args[1].length >= 8) {
+    key = args[1];
+    blank();
+    console.log(`  ${D}Using provided key: ${args[1].slice(0, 8)}...${R}`);
+    blank();
+  } else {
+    process.stdout.write(`  ${CY}License key:${R} `);
+
+    key = await new Promise(res => {
+      let input = '';
+      const isRaw = process.stdin.isTTY;
+      if (isRaw) process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', function onData(chunk) {
+        if (chunk === '\r' || chunk === '\n') {
+          if (isRaw) process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          res(input.trim());
+        } else if (chunk === '\u0003') {
+          if (isRaw) process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdout.write('\n');
+          process.exit(0);
+        } else if (chunk === '\u007f') {
+          if (input.length > 0) { input = input.slice(0, -1); process.stdout.write('\b \b'); }
+        } else {
+          input += chunk;
+          process.stdout.write('*');
+        }
+      });
     });
-  });
+  }
 
   if (!key || key.length < 8) {
     blank();
@@ -749,13 +783,45 @@ async function cmdActivate() {
     process.exit(2);
   }
 
+  // Validate key against server before storing
+  const serverUrl = process.env.CONTENT_GRADE_SERVER_URL || 'https://contentgrade.ai';
+  blank();
+  process.stdout.write(`  ${D}Validating key...${R}`);
+
+  let validated = false;
+  try {
+    const response = await fetch(`${serverUrl}/api/license/validate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ key }),
+    });
+    const data = await response.json();
+    if (data.valid) {
+      validated = true;
+    } else {
+      process.stdout.write('\n');
+      blank();
+      fail(data.message || 'Invalid or expired license key. Visit contentgrade.ai to check your subscription.');
+      blank();
+      process.exit(2);
+    }
+  } catch {
+    // Server unreachable — allow offline activation with a warning
+    process.stdout.write('\n');
+    blank();
+    console.log(`  ${D}⚠ Could not reach server — storing key locally without verification.${R}`);
+    validated = true;
+  }
+
+  process.stdout.write(' done\n');
+
   const config = loadConfig();
   config.licenseKey = key;
   config.activatedAt = new Date().toISOString();
   saveConfig(config);
 
   blank();
-  ok(`License activated! Pro features unlocked.`);
+  ok(`Pro access activated! Your daily limit is now 100 analyses.`);
   blank();
   console.log(`  ${B}Try it:${R}`);
   console.log(`  ${CY}  content-grade batch ./posts/${R}   ${D}# analyze all files${R}`);
@@ -777,7 +843,7 @@ async function cmdBatch(dirPath) {
     console.log(`  ${B}Unlock batch mode:${R}`);
     console.log(`    ${CY}content-grade activate${R}   ${D}(enter your license key)${R}`);
     blank();
-    console.log(`  ${D}Get a license: ${CY}contentgrade.dev${R}`);
+    console.log(`  ${D}Get a license: ${CY}content-grade.github.io/Content-Grade${R}`);
     blank();
     process.exit(1);
   }
@@ -845,6 +911,20 @@ async function cmdBatch(dirPath) {
     const rel = f.startsWith(process.cwd()) ? f.slice(process.cwd().length + 1) : f;
     process.stdout.write(`  ${D}[${i + 1}/${files.length}]${R} ${rel}...`);
 
+    // Guard: check daily limit before each analysis
+    const batchLimitCheck = checkDailyLimit();
+    if (!batchLimitCheck.ok) {
+      process.stdout.write(` ${YL}limit reached${R}\n`);
+      blank();
+      warn(`Daily limit reached (${batchLimitCheck.count}/${batchLimitCheck.limit}). Remaining files skipped.`);
+      break;
+    }
+
+    // Guard: skip files over 500 KB to avoid OOM on large files
+    let fileStat;
+    try { fileStat = statSync(f); } catch { process.stdout.write(` ${RD}unreadable${R}\n`); continue; }
+    if (fileStat.size > 500 * 1024) { process.stdout.write(` ${YL}too large${R}\n`); continue; }
+
     let content;
     try { content = readFileSync(f, 'utf8'); } catch { process.stdout.write(` ${RD}unreadable${R}\n`); continue; }
     if (content.trim().length < 20 || content.includes('\x00')) { process.stdout.write(` ${YL}skipped${R}\n`); continue; }
@@ -1008,8 +1088,16 @@ function cmdStart() {
 
 function cmdHelp() {
   banner();
-  console.log(`  ${D}v${_version}  ·  ${CY}https://github.com/StanislavBG/Content-Grade${R}`);
+  console.log(`  ${D}v${_version}  ·  ${CY}content-grade.github.io/Content-Grade${R}`);
+  blank();
+  console.log(`  ${B}QUICK START${R}`);
   blank();
+  console.log(`    ${CY}npx content-grade headline "Your title here"${R}  ${D}# grade a headline (fastest, ~5s)${R}`);
+  console.log(`    ${CY}npx content-grade analyze ./post.md${R}           ${D}# full AI content analysis (~20s)${R}`);
+  console.log(`    ${CY}npx content-grade demo${R}                        ${D}# live demo on sample content${R}`);
+  console.log(`    ${CY}npx content-grade start${R}                       ${D}# launch web dashboard (6 tools)${R}`);
+  blank();
+
   console.log(`  ${B}USAGE${R}`);
   blank();
   console.log(`    ${CY}content-grade <command> [args]${R}`);
@@ -1088,10 +1176,110 @@ function cmdHelp() {
   console.log(`    · Email subject line optimizer`);
   console.log(`    · Audience archetype decoder`);
   blank();
-  console.log(`    ${CY}content-grade start${R}  then click Upgrade`);
+  console.log(`    ${CY}content-grade.github.io/Content-Grade${R}  → then: ${CY}content-grade activate${R}`);
   blank();
 }
 
+// ── First-run detection ───────────────────────────────────────────────────────
+
+function isFirstRun() {
+  return !existsSync(CONFIG_FILE);
+}
+
+// ── Quick Demo (instant, no Claude required) ──────────────────────────────────
+
+function cmdQuickDemo() {
+  blank();
+  if (isFirstRun()) {
+    console.log(`${B}${CY}  Welcome to ContentGrade!${R}`);
+    console.log(`  ${D}Grade any blog post, landing page, or ad copy in seconds.${R}`);
+    blank();
+    console.log(`  ${D}Here's a sample analysis — then try it on your own content.${R}`);
+  } else {
+    console.log(`${B}${CY}  ContentGrade${R}  ${D}— Sample Analysis (instant, no Claude needed)${R}`);
+    console.log(`  ${D}Run ${CY}npx content-grade analyze ./your-post.md${R}${D} for a real AI-powered result.${R}`);
+  }
+  blank();
+
+  // Pre-rendered analysis of DEMO_CONTENT — identical format to real cmdAnalyze output
+  console.log(`  ${D}Analyzing: "How to Write Better Blog Posts" (generic blog post)${R}`);
+  blank();
+  hr();
+
+  // Overall score
+  console.log(`  ${B}OVERALL SCORE${R}   ${YL}${B}42/100${R}  ${RD}${B}D${R}   ${D}blog post${R}`);
+  console.log(`  ${scoreBar(42, 40)}`);
+  blank();
+
+  // Headline
+  console.log(`  ${B}HEADLINE SCORE${R}   ${scoreBar(35, 20)} 35/100`);
+  console.log(`  ${D}"How to Write Better Blog Posts"${R}`);
+  console.log(`  ${D}↳ Generic title with no specificity, number, or benefit — reads like every other guide.${R}`);
+  blank();
+
+  hr();
+  console.log(`  ${B}DIMENSION BREAKDOWN${R}`);
+  blank();
+  const _demodims = [
+    { label: 'Clarity',        score: 55, note: 'Sentences are clear but vague — "good" and "better" appear 12× with no definition.' },
+    { label: 'Engagement',     score: 38, note: 'No hook, no tension. Opens with a passive statement any writing guide could claim.' },
+    { label: 'Structure',      score: 45, note: 'Numbered list helps scannability but every section carries equal weight — no pyramid.' },
+    { label: 'Value Delivery', score: 30, note: '"Write good content" is not advice. Every tip is a truism with no specific technique.' },
+  ];
+  for (const d of _demodims) {
+    console.log(`  ${WH}${d.label.padEnd(16)}${R} ${scoreBar(d.score, 20)} ${d.score}/100`);
+    console.log(`  ${D}  ↳ ${d.note}${R}`);
+    blank();
+  }
+
+  hr();
+  console.log(`  ${B}VERDICT${R}`);
+  console.log(`  ${YL}Technically correct but forgettable — every sentence could be cut in half and the advice doubled in specificity.${R}`);
+  blank();
+
+  hr();
+  console.log(`  ${B}STRENGTHS${R}`);
+  console.log(`  ${GN}+${R} Logical four-step structure is easy to follow`);
+  console.log(`  ${GN}+${R} Short paragraphs with good white space`);
+  blank();
+
+  hr();
+  console.log(`  ${B}TOP IMPROVEMENTS${R}`);
+  blank();
+  console.log(`  ${RD}●${R} ${B}Headline has no specificity${R}`);
+  console.log(`    ${CY}Fix:${R} Add a number and outcome: "7 Blog Post Mistakes That Kill Readership (And the Fixes That Work)"`);
+  blank();
+  console.log(`  ${RD}●${R} ${B}Tips are high-level truisms${R}`);
+  console.log(`    ${CY}Fix:${R} Replace "write good content" with a technique: "Open with the reader's frustration, not your advice."`);
+  blank();
+  console.log(`  ${YL}●${R} ${B}No proof or examples${R}`);
+  console.log(`    ${CY}Fix:${R} Add a before/after example for one tip to make the advice concrete and credible`);
+  blank();
+
+  hr();
+  console.log(`  ${B}HEADLINE REWRITES${R}`);
+  blank();
+  console.log(`  ${D}1.${R} 7 Blog Post Mistakes That Kill Your Readership (And the Fixes That Work)`);
+  console.log(`  ${D}2.${R} How to Write Blog Posts That People Actually Finish Reading`);
+  blank();
+
+  hr();
+  console.log(`  ${D}↑ This is a ${B}sample${R}${D} — your real content gets a live AI analysis in ~20 seconds.${R}`);
+  blank();
+  console.log(`  ${B}${CY}Try it now:${R}`);
+  blank();
+  console.log(`  ${CY}npx content-grade headline "Your headline here"${R}  ${D}# fastest — grade any headline${R}`);
+  console.log(`  ${CY}npx content-grade analyze ./your-post.md${R}         ${D}# full AI analysis of a file${R}`);
+  console.log(`  ${CY}npx content-grade demo${R}                           ${D}# live demo — takes ~20s with Claude${R}`);
+  blank();
+
+  if (isFirstRun()) {
+    console.log(`  ${D}Requires Claude CLI (free): ${CY}claude.ai/code${R}${D} → install → ${CY}claude login${R}`);
+    console.log(`  ${D}Setup check: ${CY}npx content-grade init${R}`);
+    blank();
+  }
+}
+
 // ── Demo command ──────────────────────────────────────────────────────────────
 
 const DEMO_CONTENT = `# How to Write Better Blog Posts
@@ -1127,8 +1315,8 @@ async function cmdDemo() {
   banner();
   console.log(`  ${B}Demo Mode${R}  ${D}— see ContentGrade in action${R}`);
   blank();
-  console.log(`  ${D}Analyzing a sample blog post with generic writing.${R}`);
-  console.log(`  ${D}Generic content scores low — that's the point. Watch what ContentGrade finds.${R}`);
+  console.log(`  ${D}Analyzing a sample blog post. Watch ContentGrade identify exactly what's weak${R}`);
+  console.log(`  ${D}and how to fix it — this is what you'll see on your own content.${R}`);
   blank();
 
   writeFileSync(tmpFile, DEMO_CONTENT, 'utf8');
@@ -1138,11 +1326,11 @@ async function cmdDemo() {
     // Post-demo CTA — shown AFTER user has seen the analysis output
     blank();
     hr();
-    console.log(`  ${B}${CY}Now try it on your own content:${R}`);
+    console.log(`  ${B}${CY}Your turn — try it on real content:${R}`);
     blank();
-    console.log(`  ${CY}content-grade analyze ./your-post.md${R}         ${D}# any .md or .txt file${R}`);
-    console.log(`  ${CY}content-grade https://your-blog.com/post${R}      ${D}# analyze any URL${R}`);
-    console.log(`  ${CY}content-grade headline "Your headline here"${R}   ${D}# grade a headline${R}`);
+    console.log(`  ${CY}npx content-grade ./your-post.md${R}               ${D}# score any .md or .txt file${R}`);
+    console.log(`  ${CY}npx content-grade https://example.com/blog/post${R} ${D}# fetch and score any URL${R}`);
+    console.log(`  ${CY}npx content-grade headline "Your title here"${R}   ${D}# grade a single headline${R}`);
     blank();
 
     // Show telemetry notice after user has seen value (first run only)
@@ -1150,6 +1338,55 @@ async function cmdDemo() {
       console.log(`  ${D}Anonymous usage data is collected by default. Opt out: ${CY}content-grade telemetry off${R}`);
       blank();
     }
+
+    // Interactive follow-up — strike while the iron is hot
+    if (process.stdin.isTTY) {
+      hr();
+      console.log(`  ${B}${CY}Score your own content right now:${R}`);
+      blank();
+      console.log(`  ${D}Paste a URL (https://...), a headline, or a file path — press Enter to analyze.${R}`);
+      console.log(`  ${D}Or press Enter to skip.${R}`);
+      blank();
+      process.stdout.write(`  ${CY}>${R} `);
+
+      const userInput = await new Promise(res => {
+        let line = '';
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+        const onData = (chunk) => {
+          const str = chunk.toString();
+          if (str.includes('\n') || str.includes('\r')) {
+            process.stdin.pause();
+            process.stdin.removeListener('data', onData);
+            process.stdout.write('\n');
+            res(line.replace(/[\r\n]/g, '').trim());
+          } else if (str === '\u0003') {
+            process.stdin.pause();
+            process.stdin.removeListener('data', onData);
+            process.stdout.write('\n');
+            res('');
+          } else {
+            line += str;
+            process.stdout.write(str);
+          }
+        };
+        process.stdin.on('data', onData);
+      });
+
+      if (userInput) {
+        blank();
+        if (/^https?:\/\//i.test(userInput)) {
+          await cmdAnalyzeUrl(userInput);
+        } else if (looksLikePath(userInput)) {
+          await cmdAnalyze(userInput);
+        } else if (userInput.length >= 5) {
+          await cmdHeadline(userInput);
+        } else {
+          warn(`Couldn't parse that. Try a URL like https://... or a headline like "Your title here".`);
+          blank();
+        }
+      }
+    }
   } finally {
     try { unlinkSync(tmpFile); } catch {}
   }
@@ -1160,7 +1397,7 @@ async function cmdDemo() {
 function fetchUrl(url) {
   return new Promise((resolve, reject) => {
     const get = url.startsWith('https') ? httpsGet : httpGet;
-    const req = get(url, { headers: { 'User-Agent': 'ContentGrade/1.0 (+https://github.com/StanislavBG/Content-Grade)' }, timeout: 15000 }, (res) => {
+    const req = get(url, { headers: { 'User-Agent': 'ContentGrade/1.0 (+https://github.com/content-grade/Content-Grade)' }, timeout: 15000 }, (res) => {
       // Follow one redirect
       if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
         fetchUrl(res.headers.location).then(resolve).catch(reject);
@@ -1201,6 +1438,22 @@ function htmlToText(html) {
 }
 
 async function cmdAnalyzeUrl(url) {
+  // Validate and sanitize URL input
+  const sanitizedUrl = (url || '').replace(/[\x00-\x1F\x7F]/g, '').trim();
+  if (!sanitizedUrl || !/^https?:\/\/.{3,}/i.test(sanitizedUrl)) {
+    blank();
+    fail(`Invalid URL: must start with http:// or https://`);
+    blank();
+    process.exit(2);
+  }
+  if (sanitizedUrl.length > 2048) {
+    blank();
+    fail(`URL too long (${sanitizedUrl.length} chars). Maximum is 2048.`);
+    blank();
+    process.exit(2);
+  }
+  url = sanitizedUrl;
+
   banner();
   console.log(`  ${B}Analyzing URL:${R} ${CY}${url}${R}`);
   blank();
@@ -1438,14 +1691,9 @@ switch (cmd) {
   }
 
   case undefined:
-    // No command — run demo immediately for instant value
-    recordEvent({ event: 'command', command: 'demo' });
-    cmdDemo().catch(err => {
-      blank();
-      fail(`Demo error: ${err.message}`);
-      blank();
-      process.exit(1);
-    });
+    // No command — show instant static demo (no Claude required, zero wait)
+    recordEvent({ event: 'command', command: 'quick_demo' });
+    cmdQuickDemo();
     break;
 
   default:
@@ -1492,15 +1740,30 @@ switch (cmd) {
         process.exit(1);
       });
     } else {
-      blank();
-      fail(`Unknown command: ${B}${raw}${R}`);
-      blank();
-      console.log(`  Available commands:`);
-      console.log(`    ${CY}analyze <file>${R}   ${CY}headline "<text>"${R}   ${CY}demo${R}   ${CY}start${R}   ${CY}init${R}   ${CY}help${R}`);
-      blank();
-      console.log(`  ${D}Pass a file/directory directly: ${CY}content-grade ./my-post.md${R}`);
-      console.log(`  ${D}Run ${CY}content-grade help${R}${D} for full usage${R}`);
-      blank();
-      process.exit(1);
+      // Smart fallback: treat unrecognised input as a headline to grade.
+      // Covers: npx content-grade "Why most startups fail"
+      //         npx content-grade Why most startups fail
+      const allText = args.join(' ').trim();
+      if (allText && allText.length >= 5 && !allText.startsWith('-')) {
+        recordEvent({ event: 'command', command: 'headline_smart' });
+        cmdHeadline(allText).catch(err => {
+          blank();
+          fail(`Unexpected error: ${err.message}`);
+          blank();
+          process.exit(1);
+        });
+      } else {
+        blank();
+        fail(`Unknown command: ${B}${raw}${R}`);
+        blank();
+        console.log(`  Available commands:`);
+        console.log(`    ${CY}analyze <file>${R}   ${CY}headline "<text>"${R}   ${CY}demo${R}   ${CY}start${R}   ${CY}init${R}   ${CY}help${R}`);
+        blank();
+        console.log(`  ${D}Pass a file/directory directly: ${CY}content-grade ./my-post.md${R}`);
+        console.log(`  ${D}Grade a headline: ${CY}content-grade "Your headline text"${R}`);
+        console.log(`  ${D}Run ${CY}content-grade help${R}${D} for full usage${R}`);
+        blank();
+        process.exit(1);
+      }
     }
 }

package/bin/telemetry.js

@@ -17,8 +17,10 @@ const CONFIG_DIR   = join(homedir(), '.content-grade');
 const CONFIG_FILE  = join(CONFIG_DIR, 'config.json');
 const EVENTS_FILE  = join(CONFIG_DIR, 'events.jsonl');
 
-// Telemetry endpoint: set CONTENT_GRADE_TELEMETRY_URL to enable remote reporting
-const REMOTE_URL = process.env.CONTENT_GRADE_TELEMETRY_URL || null;
+// Telemetry endpoint: CLI events are forwarded here when telemetry is enabled.
+// Set CONTENT_GRADE_TELEMETRY_URL to enable remote aggregation (e.g. self-hosted endpoint).
+// Default: local-only (events stored at ~/.content-grade/events.jsonl, no remote send).
+const REMOTE_URL = process.env.CONTENT_GRADE_TELEMETRY_URL || '';
 
 // ── Internal helpers ──────────────────────────────────────────────────────────