content-grade 1.0.5 → 1.0.6

package/README.md

@@ -3,10 +3,12 @@
 > AI-powered content quality scoring for developers and content teams. Score any blog post, landing page, ad copy, or email — in under 30 seconds. No API keys. No accounts. Runs on your local Claude CLI.
 
 [![npm](https://img.shields.io/npm/v/content-grade.svg)](https://www.npmjs.com/package/content-grade)
+[![npm downloads/month](https://img.shields.io/npm/dm/content-grade.svg)](https://www.npmjs.com/package/content-grade)
+[![npm downloads/week](https://img.shields.io/npm/dw/content-grade.svg)](https://www.npmjs.com/package/content-grade)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![Requires Claude CLI](https://img.shields.io/badge/requires-Claude%20CLI-orange)](https://claude.ai/code)
-[![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-blue?logo=github)](https://github.com/StanislavBG/Content-Grade/discussions)
+[![GitHub Discussions](https://img.shields.io/badge/GitHub-Discussions-blue?logo=github)](https://github.com/content-grade/Content-Grade/discussions)
 [![Early Adopter seats open](https://img.shields.io/badge/Early%20Adopter-50%20seats%20open-success)](EARLY_ADOPTERS.md)
 
 ---
@@ -14,30 +16,28 @@
 ## 60-second quickstart
 
 ```bash
-# 1. Verify Claude CLI is installed and logged in
-claude -p "say hi"
-
-# 2. Run instant demo — no file needed, see results in ~30 seconds
+# Step 1: See it in action — instant demo, no file needed
 npx content-grade
 
-# 3. Analyze your own content (grade is an alias for analyze)
+# Step 2: Score your own content
+npx content-grade grade README.md
 npx content-grade grade ./my-post.md
-npx content-grade analyze ./my-post.md
 
-# 4. CI pipeline — get raw JSON or score-only output
-npx content-grade analyze ./post.md --json
-npx content-grade analyze ./post.md --quiet   # prints score number only
-
-# 5. Grade a headline
+# Step 3: Grade a headline
 npx content-grade headline "Why Most Startups Fail at Month 18"
-
-# 6. Unlock Pro (batch mode, 100/day limit)
-npx content-grade activate
 ```
 
-**One requirement:** [Claude CLI](https://claude.ai/code) must be installed and logged in. No API keys, no accounts, no data leaves your machine.
+**One requirement:** [Claude CLI](https://claude.ai/code) must be installed and logged in (`claude login`). No API keys, no accounts, your content never leaves your machine.
 
-**Free tier:** 50 analyses/day, no signup needed. `npx content-grade grade README.md` works immediately.
+**Free tier:** 50 analyses/day. No signup. `npx content-grade grade README.md` works immediately.
+
+```bash
+# More commands
+npx content-grade https://yourblog.com/post    # analyze any URL
+npx content-grade analyze ./post.md --json     # raw JSON for CI pipelines
+npx content-grade analyze ./post.md --quiet    # score number only (for scripts)
+npx content-grade activate                     # unlock Pro: batch mode, 100/day
+```
 
 ---
 
@@ -319,7 +319,7 @@ Stripe variables are entirely optional — all tools work without them; upgrade
 ## Self-hosting / Development
 
 ```bash
-git clone https://github.com/StanislavBG/Content-Grade
+git clone https://github.com/content-grade/Content-Grade
 cd Content-Grade
 npm install
 npm run dev     # hot reload: server at :4000, client at :3000
@@ -350,6 +350,11 @@ tests/
 
 **REST API:** The web dashboard exposes a full REST API at `http://localhost:4000`. See [`docs/api.md`](./docs/api.md) for the complete reference — every endpoint, request shape, response schema, and cURL examples.
 
+**Documentation:**
+- [`docs/getting-started.md`](./docs/getting-started.md) — step-by-step first-run guide
+- [`docs/examples.md`](./docs/examples.md) — real-world examples for all 6 tools, CI/CD workflows, Node.js integration
+- [`docs/api.md`](./docs/api.md) — full REST API reference
+
 **Run tests:**
 
 ```bash
@@ -744,13 +749,13 @@ ContentGrade is built in public. The community is the roadmap.
 
 ### GitHub Discussions
 
-**[Join the conversation →](https://github.com/StanislavBG/Content-Grade/discussions)**
+**[Join the conversation →](https://github.com/content-grade/Content-Grade/discussions)**
 
 | Category | What it's for |
 |----------|--------------|
-| [Q&A](https://github.com/StanislavBG/Content-Grade/discussions/new?category=q-a) | "Why is my score lower than expected?" — questions get answered here |
-| [Show & Tell](https://github.com/StanislavBG/Content-Grade/discussions/new?category=show-and-tell) | Share your workflow, integration, or results — early adopters post here |
-| [Ideas](https://github.com/StanislavBG/Content-Grade/discussions/new?category=ideas) | Feature requests and suggestions before they become issues |
+| [Q&A](https://github.com/content-grade/Content-Grade/discussions/new?category=q-a) | "Why is my score lower than expected?" — questions get answered here |
+| [Show & Tell](https://github.com/content-grade/Content-Grade/discussions/new?category=show-and-tell) | Share your workflow, integration, or results — early adopters post here |
+| [Ideas](https://github.com/content-grade/Content-Grade/discussions/new?category=ideas) | Feature requests and suggestions before they become issues |
 
 ### Early Adopter Program — 50 seats
 
@@ -762,7 +767,7 @@ ContentGrade is built in public. The community is the roadmap.
 - Roadmap preview + design input before features ship
 - 30-minute onboarding call (optional)
 
-One action to claim: run ContentGrade, then post in [Show & Tell](https://github.com/StanislavBG/Content-Grade/discussions/new?category=show-and-tell) with `[Early Adopter]` in the title.
+One action to claim: run ContentGrade, then post in [Show & Tell](https://github.com/content-grade/Content-Grade/discussions/new?category=show-and-tell) with `[Early Adopter]` in the title.
 
 ### Champions Program
 
@@ -774,16 +779,28 @@ See **[CONTRIBUTING.md](CONTRIBUTING.md)** for local dev setup, PR guidelines, a
 
 ### Roadmap
 
-**[ROADMAP.md](ROADMAP.md)** — what's built, what's next, what's planned, and what we're deliberately not doing. Open a [Discussion](https://github.com/StanislavBG/Content-Grade/discussions/new?category=ideas) to challenge or extend it.
+**[ROADMAP.md](ROADMAP.md)** — what's built, what's next, what's planned, and what we're deliberately not doing. Open a [Discussion](https://github.com/content-grade/Content-Grade/discussions/new?category=ideas) to challenge or extend it.
 
 ### Feedback Loop
 
-**[FEEDBACK_LOOP.md](FEEDBACK_LOOP.md)** — how feedback flows into product decisions. Monthly structured check-ins, 48h triage SLA, and roadmap sync. Use the [monthly feedback template](https://github.com/StanislavBG/Content-Grade/issues/new?template=monthly_feedback.yml) to share your experience.
+**[FEEDBACK_LOOP.md](FEEDBACK_LOOP.md)** — how feedback flows into product decisions. Monthly structured check-ins, 48h triage SLA, and roadmap sync. Use the [monthly feedback template](https://github.com/content-grade/Content-Grade/issues/new?template=monthly_feedback.yml) to share your experience.
 
 ### Contributors
 
 **[CONTRIBUTORS.md](CONTRIBUTORS.md)** — everyone who has improved ContentGrade. Code, bug reports, and real-world feedback all count. Early Adopters and Champions are listed here permanently.
 
+### Use ContentGrade in your project
+
+Add a badge to show your content meets the bar:
+
+```markdown
+[![content-grade](https://img.shields.io/badge/content--grade-passing-brightgreen)](https://www.npmjs.com/package/content-grade)
+```
+
+Score-specific badge: `https://img.shields.io/badge/content--grade-{SCORE}%2F100-brightgreen`
+
+See [docs/social-proof/built-with-badge.md](docs/social-proof/built-with-badge.md) for SVG assets and CI integration examples.
+
 ---
 
 ## License

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,7 +736,7 @@ 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}`);
+  console.log(`  ${D}Get a license: ${CY}content-grade.github.io/Content-Grade${R}${D} → Pricing${R}`);
   blank();
 
   let key;
@@ -817,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);
   }
@@ -885,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; }
@@ -1048,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}`);
@@ -1128,8 +1176,108 @@ 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 ──────────────────────────────────────────────────────────────
@@ -1167,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');
@@ -1178,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)
@@ -1194,10 +1342,10 @@ async function cmdDemo() {
     // Interactive follow-up — strike while the iron is hot
     if (process.stdin.isTTY) {
       hr();
-      console.log(`  ${B}${CY}Try it on YOUR content right now:${R}`);
+      console.log(`  ${B}${CY}Score your own content right now:${R}`);
       blank();
-      console.log(`  ${D}Paste a URL, type a headline, or a file path — then press Enter.${R}`);
-      console.log(`  ${D}(Press Enter to skip)${R}`);
+      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} `);
 
@@ -1249,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);
@@ -1290,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();
@@ -1527,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:

package/bin/telemetry.js

@@ -18,8 +18,9 @@ const CONFIG_FILE  = join(CONFIG_DIR, 'config.json');
 const EVENTS_FILE  = join(CONFIG_DIR, 'events.jsonl');
 
 // Telemetry endpoint: CLI events are forwarded here when telemetry is enabled.
-// Override with CONTENT_GRADE_TELEMETRY_URL env var (e.g. for self-hosted or staging).
-const REMOTE_URL = process.env.CONTENT_GRADE_TELEMETRY_URL || 'https://contentgrade.ai/api/telemetry';
+// 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 ──────────────────────────────────────────────────────────