content-grade 1.0.0 → 1.0.2

package/README.md

@@ -21,7 +21,10 @@ npx content-grade
 # 3. Analyze your own content
 npx content-grade ./my-post.md
 
-# 4. Grade a single headline
+# 4. Analyze a live URL directly
+npx content-grade https://yoursite.com/blog/post
+
+# 5. Grade a single headline
 npx content-grade headline "Why Most Startups Fail at Month 18"
 ```
 
@@ -72,11 +75,7 @@ npx content-grade headline "Why Most Startups Fail at Month 18"
   1. Why 90% of SaaS Startups Fail at Month 18 (and How to Be the 10%)
   2. The Month 18 Startup Trap: What Kills Growth-Stage Companies
 
-  Free analysis complete. Pro unlocks:
-    · Competitor headline comparison
-    · Landing page URL audit (full CRO analysis)
-    · Ad copy scoring (Google, Meta, LinkedIn)
-    · 100 analyses/day vs 3 free
+  Unlock team features at contentgrade.dev
 ```
 
 ---
@@ -86,6 +85,7 @@ npx content-grade headline "Why Most Startups Fail at Month 18"
 | Command | What it does |
 |---------|-------------|
 | *(no args)* | Instant demo on built-in sample content |
+| `<url>` | Fetch and analyze a live URL — `npx content-grade https://example.com/blog/post` |
 | `<file>` | Analyze a file directly — `npx content-grade ./post.md` |
 | `.` or `<dir>` | Scan a directory, find and analyze the best content file |
 | `demo` | Same as no args |
@@ -96,8 +96,17 @@ npx content-grade headline "Why Most Startups Fail at Month 18"
 | `grade "<text>"` | Alias for `headline` |
 | `init` | First-run setup: verify Claude CLI, run smoke test |
 | `start` | Launch the full web dashboard (6 tools) |
+| `telemetry [on\|off]` | View or toggle anonymous usage tracking |
 | `help` | Full usage and examples |
 
+**Global flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--no-telemetry` | Skip usage tracking for this one invocation |
+| `--version`, `-v`, `-V` | Show installed version |
+| `--help`, `-h` | Show help |
+
 ---
 
 ## The 6 web dashboard tools
@@ -113,7 +122,7 @@ Launch with `content-grade start` — opens at [http://localhost:4000](http://lo
 | **EmailForge** | `/email-forge` | Subject line + body copy for click-through optimization |
 | **AudienceDecoder** | `/audience` | Twitter handle → audience archetypes and content patterns |
 
-Free tier: **3 analyses/day per tool**. Pro ($9/mo): **100 analyses/day** + all tools.
+Free tier: **50 analyses/day per tool**. Pro ($9/mo): **100 analyses/day** + all tools.
 
 ---
 
@@ -207,6 +216,26 @@ Use this when something isn't working — it tells you exactly what to fix.
 
 ---
 
+### `telemetry`
+
+```bash
+content-grade telemetry          # show current status
+content-grade telemetry off      # opt out — persisted permanently
+content-grade telemetry on       # opt back in
+```
+
+Anonymous usage tracking (command name + score range, no file contents, no PII). Enabled by default; `telemetry off` writes a local flag file and is honoured by all future invocations.
+
+**One-time opt-out per invocation:**
+
+```bash
+content-grade analyze ./post.md --no-telemetry
+```
+
+Pass `--no-telemetry` to any command to skip tracking for that run only without changing the saved preference.
+
+---
+
 ### `start` / `serve`
 
 ```bash
@@ -312,6 +341,353 @@ npm run test:coverage # coverage report
 
 ---
 
+## Output format
+
+When `content-grade analyze` runs, Claude returns structured JSON that is rendered to the terminal. The raw schema:
+
+```json
+{
+  "content_type": "blog | email | ad | social | landing",
+  "total_score": 72,
+  "grade": "B+",
+  "headline": {
+    "text": "Why Most Startups Fail",
+    "score": 61,
+    "feedback": "Too vague — the reader doesn't know if this applies to them."
+  },
+  "dimensions": {
+    "clarity":        { "score": 80, "note": "Well-organized with clear section breaks." },
+    "engagement":     { "score": 60, "note": "Opens with a statistic but drops momentum in paragraph 3." },
+    "structure":      { "score": 72, "note": "Good use of subheadings but the conclusion is thin." },
+    "value_delivery": { "score": 65, "note": "Core advice is solid but needs a concrete takeaway." }
+  },
+  "one_line_verdict": "Strong structure undermined by a weak headline — fix that first.",
+  "strengths": [
+    "Well-organized with clear section breaks",
+    "Specific statistics in the opening hook"
+  ],
+  "improvements": [
+    {
+      "issue": "Headline is too vague",
+      "priority": "high",
+      "fix": "Why 90% of SaaS Startups Fail at Month 18 (and How to Be the 10%)"
+    },
+    {
+      "issue": "Paragraph 2 makes claims without evidence",
+      "priority": "medium",
+      "fix": "Cite a specific study — 'CB Insights found...' beats 'many startups...'"
+    }
+  ],
+  "headline_rewrites": [
+    "Why 90% of SaaS Startups Fail at Month 18 (and How to Be the 10%)",
+    "The Month 18 Startup Trap: What Kills Growth-Stage Companies"
+  ]
+}
+```
+
+For `content-grade headline`, the schema:
+
+```json
+{
+  "score": 74,
+  "grade": "B",
+  "verdict": "Strong promise but lacks the proof element that separates a 74 from an 88.",
+  "scores": {
+    "rule_of_one":        { "score": 22, "max": 30, "note": "Single idea present but promise is vague." },
+    "value_equation":     { "score": 22, "max": 30, "note": "Dream outcome clear; likelihood undermined by '10x' without proof." },
+    "readability":        { "score": 16, "max": 20, "note": "Short, no jargon — reads well." },
+    "proof_promise_plan": { "score": 14, "max": 20, "note": "Timeframe adds proof; missing the 'how'." }
+  },
+  "rewrites": [
+    "How I Doubled Conversions in 30 Days by Fixing One Headline",
+    "The 3 Headline Fixes That Grew My Conversions 10x (Backed by 847 A/B Tests)"
+  ]
+}
+```
+
+---
+
+## Scoring methodology
+
+ContentGrade uses Claude as a scoring engine with **calibrated anchor examples** that force use of the full 0–100 range. This prevents the common AI problem of all scores bunching in the 60–80 band.
+
+**Score thresholds (for `analyze`):**
+
+| Score | What it means |
+|-------|--------------|
+| 90–100 | Exceptional — data authority, curiosity gap, ultra-specific, publication-ready |
+| 80–89 | Strong — clear value equation, good proof, specific promise |
+| 65–79 | Good — readable, structured, some specificity gaps |
+| 50–64 | Adequate — readable but vague, generic structure |
+| 35–49 | Poor — clichés, no hook, commodity topic |
+| 0–34 | Very weak — no structure, zero reader benefit, or content too short |
+
+**Dimensions:**
+
+- **Clarity** — Organization, section breaks, readability. Does the reader always know where they are?
+- **Engagement** — Hook strength, momentum, reader retention. Would someone read to the end?
+- **Structure** — Heading hierarchy, flow, conclusion strength. Is there a logical arc?
+- **Value Delivery** — Concrete advice, takeaways, actionable insights. Does the reader leave with something useful?
+
+**Content-type calibration:** The scoring prompt knows it's reading a blog post vs. an email vs. ad copy. A 200-word email doesn't get penalized for "thin structure" the way a blog post would.
+
+**Headline framework calibration anchors:**
+
+| Score range | What it takes |
+|-------------|--------------|
+| 95+ | Data authority + curiosity gap + ultra-specificity + clear reader identity |
+| 88–92 | Strong proof + promise + plan, low jargon, 6–10 words |
+| 75–84 | Clear value equation, objection handling, some specificity |
+| 65–74 | Clear differentiator or positioning, but vague on proof |
+| 50–64 | Decent structure but generic or lacking urgency |
+| 35–49 | Standard cliché phrasing, no hook element |
+| 0–34 | Commodity topic, passive voice, zero benefit stated |
+
+---
+
+## Programmatic use (REST API)
+
+Start the server with `content-grade start`, then call any tool via HTTP:
+
+### Grade a headline
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/headline-grader \
+  -H 'Content-Type: application/json' \
+  -d '{"headline": "Why Most Startups Fail at Month 18"}' | jq .
+```
+
+Response:
+```json
+{
+  "total_score": 74,
+  "grade": "B",
+  "diagnosis": "Strong promise but lacks the proof element that separates a 74 from an 88.",
+  "framework_scores": {
+    "rule_of_one":        { "score": 22, "max": 30, "note": "..." },
+    "value_equation":     { "score": 22, "max": 30, "note": "..." },
+    "readability":        { "score": 16, "max": 20, "note": "..." },
+    "proof_promise_plan": { "score": 14, "max": 20, "note": "..." }
+  },
+  "rewrites": ["...", "..."],
+  "usage": { "remaining": 2, "limit": 3, "isPro": false }
+}
+```
+
+### Compare two headlines (Pro)
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/headline-grader/compare \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "headlineA": "Why Most Startups Fail",
+    "headlineB": "Why 90% of SaaS Startups Fail at Month 18",
+    "email": "you@example.com"
+  }' | jq .
+```
+
+### Audit a landing page URL (Pro)
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/page-roast \
+  -H 'Content-Type: application/json' \
+  -d '{"url": "https://example.com", "email": "you@example.com"}' | jq .
+```
+
+### Score ad copy
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/ad-scorer \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "adCopy": "Stop wasting money on ads that don'\''t convert.",
+    "platform": "facebook",
+    "email": "you@example.com"
+  }' | jq .
+```
+
+### Grade a Twitter thread
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/thread-grader \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "threadText": "1/ Most people think productivity is about working more hours...\n\n2/ They'\''re wrong.",
+    "email": "you@example.com"
+  }' | jq .
+```
+
+### Generate an email
+
+```bash
+curl -s -X POST http://localhost:4000/api/demos/email-forge \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "product": "A CLI tool that grades content quality",
+    "audience": "developers who write technical blog posts",
+    "goal": "cold_outreach",
+    "tone": "casual",
+    "email": "you@example.com"
+  }' | jq .
+```
+
+**Rate limit response** (when daily free limit is hit):
+```json
+{
+  "gated": true,
+  "isPro": false,
+  "remaining": 0,
+  "limit": 50,
+  "message": "Free daily limit reached (50/day). Get 100 analyses/day with Pro"
+}
+```
+
+See [`docs/api.md`](./docs/api.md) for the full reference — every endpoint, complete request/response shapes, and more cURL examples.
+
+---
+
+## Workflows & integrations
+
+### GitHub Actions — CI content quality gate
+
+Fail the build if content quality drops below a threshold. Useful for content-heavy repos (marketing site, docs, blog).
+
+```yaml
+# .github/workflows/content-quality.yml
+name: Content quality check
+
+on:
+  pull_request:
+    paths:
+      - 'content/**'
+      - 'blog/**'
+      - '*.md'
+
+jobs:
+  grade:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Claude CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Login to Claude (non-interactive)
+        run: echo "${{ secrets.ANTHROPIC_API_KEY }}" | claude login --api-key
+        # Note: Claude CLI requires authentication. Store your API key in GitHub secrets.
+
+      - name: Grade changed content
+        run: |
+          for f in $(git diff --name-only origin/main...HEAD | grep -E '\.(md|txt|mdx)$'); do
+            echo "=== Grading $f ==="
+            npx content-grade analyze "$f" --no-telemetry
+          done
+```
+
+> **Note:** Claude CLI must be authenticated. In CI, this requires an Anthropic API key. Set `ANTHROPIC_API_KEY` in your repository secrets and use it to log in.
+
+---
+
+### Pre-commit hook
+
+Grade content before it enters the repo. Add this to `.git/hooks/pre-commit` (make it executable with `chmod +x .git/hooks/pre-commit`):
+
+```bash
+#!/bin/sh
+# Content quality pre-commit hook
+# Grades staged .md/.txt files and blocks commit if any score below threshold
+
+THRESHOLD=40
+
+staged=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(md|txt|mdx)$')
+
+if [ -z "$staged" ]; then
+  exit 0
+fi
+
+echo "Running ContentGrade on staged files..."
+
+for file in $staged; do
+  # Only check files over 100 characters (skip tiny files)
+  chars=$(wc -c < "$file" 2>/dev/null || echo 0)
+  if [ "$chars" -lt 100 ]; then
+    continue
+  fi
+
+  echo "  Grading $file..."
+  npx content-grade analyze "$file" --no-telemetry
+done
+
+echo "✓ Content quality check complete."
+exit 0
+```
+
+To block low-scoring commits, parse the score from output and compare against `$THRESHOLD`. The current output format prints `OVERALL SCORE   72/100` — grep for the number and exit 1 if below threshold.
+
+---
+
+### Batch processing a directory
+
+Grade every content file in a directory and save results:
+
+```bash
+# Grade all markdown files and save output
+find ./content -name '*.md' -not -name 'README.md' | while read f; do
+  echo "--- $f ---"
+  npx content-grade analyze "$f" --no-telemetry
+  echo ""
+done > content-grades-$(date +%Y%m%d).txt
+
+# Or use the built-in directory scan (picks the best candidate):
+npx content-grade ./content
+```
+
+---
+
+### Comparing scores over time
+
+Track score progression across revisions:
+
+```bash
+# Score the current version of a post
+npx content-grade analyze ./blog/my-post.md --no-telemetry > scores/my-post-$(date +%Y%m%d).txt
+
+# Compare two versions side-by-side
+diff scores/my-post-20240101.txt scores/my-post-20240201.txt
+
+# Quick numeric comparison
+grep "OVERALL SCORE" scores/my-post-*.txt
+```
+
+For structured tracking, use the REST API (run `content-grade start` first):
+
+```bash
+# Score via API, extract just the number
+curl -s -X POST http://localhost:4000/api/demos/headline-grader \
+  -H 'Content-Type: application/json' \
+  -d '{"headline": "Your Post Title Here"}' \
+  | jq '.total_score'
+```
+
+Log to a CSV:
+
+```bash
+DATE=$(date +%Y-%m-%d)
+HEADLINE="Your Post Title Here"
+SCORE=$(curl -s -X POST http://localhost:4000/api/demos/headline-grader \
+  -H 'Content-Type: application/json' \
+  -d "{\"headline\": \"$HEADLINE\"}" | jq '.total_score')
+
+echo "$DATE,$HEADLINE,$SCORE" >> headline-scores.csv
+```
+
+---
+
 ## Pricing
 
 | | Free | Pro |

package/bin/content-grade.js

@@ -18,6 +18,8 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, statSyn
 import { resolve, dirname, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { promisify } from 'util';
+import { get as httpsGet } from 'https';
+import { get as httpGet } from 'http';
 import { initTelemetry, recordEvent, disableTelemetry, enableTelemetry, telemetryStatus, isOptedOut } from './telemetry.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -187,7 +189,7 @@ async function cmdAnalyze(filePath) {
     blank();
     console.log(`  ${D}No file? Try the demo: ${CY}content-grade demo${R}`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
   const absPath = resolve(process.cwd(), filePath);
@@ -198,7 +200,7 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${YL}Check the path and try again.${R}`);
     console.log(`  ${D}Tip: use a relative path like ./my-file.md or an absolute path.${R}`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
   // Guard: reject directories
@@ -209,7 +211,7 @@ async function cmdAnalyze(filePath) {
     blank();
     console.log(`  ${D}Pass a text file (.md, .txt) — not a directory.${R}`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
   // Guard: reject files over 500 KB before reading into memory
@@ -220,7 +222,7 @@ async function cmdAnalyze(filePath) {
     blank();
     console.log(`  ${YL}Tip:${R} Copy the relevant section into a new file and analyze that.`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
   const content = readFileSync(absPath, 'utf8');
@@ -233,20 +235,22 @@ async function cmdAnalyze(filePath) {
     console.log(`  ${YL}ContentGrade analyzes written content — blog posts, emails, ad copy, landing pages.${R}`);
     console.log(`  ${D}Supported formats: .md, .txt, .mdx, or any plain-text file.${R}`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
   if (content.trim().length < 20) {
     blank();
     fail(`File is too short to analyze (${content.trim().length} chars). Add some content and try again.`);
     blank();
-    process.exit(1);
+    process.exit(2);
   }
 
-  banner();
-  console.log(`  ${B}Analyzing:${R} ${CY}${basename(absPath)}${R}`);
-  console.log(`  ${D}${content.length.toLocaleString()} characters · detecting content type...${R}`);
-  blank();
+  if (!_jsonMode && !_quietMode) {
+    banner();
+    console.log(`  ${B}Analyzing:${R} ${CY}${basename(absPath)}${R}`);
+    console.log(`  ${D}${content.length.toLocaleString()} characters · detecting content type...${R}`);
+    blank();
+  }
 
   // Check Claude
   if (!checkClaude()) {
@@ -271,7 +275,7 @@ async function cmdAnalyze(filePath) {
 
   const truncated = content.length > 6000 ? content.slice(0, 6000) + '\n\n[Content truncated for analysis]' : content;
 
-  process.stdout.write(`  ${D}Running analysis (this takes ~15 seconds)...${R}`);
+  if (!_jsonMode && !_quietMode) process.stdout.write(`  ${D}Running analysis (this takes ~15 seconds)...${R}`);
 
   let result;
   try {
@@ -280,9 +284,12 @@ async function cmdAnalyze(filePath) {
       ANALYZE_SYSTEM,
       'claude-sonnet-4-6'
     );
-    process.stdout.write(`\r  ${GN}✓${R} Analysis complete${' '.repeat(30)}\n`);
+    if (!_jsonMode && !_quietMode) process.stdout.write(`\r  ${GN}✓${R} Analysis complete${' '.repeat(30)}\n`);
     result = parseJSON(raw);
     recordEvent({ event: 'analyze_result', score: result.total_score, content_type: result.content_type });
+    // Machine-readable output modes (exit cleanly, skip styled output)
+    if (_jsonMode)  { process.stdout.write(JSON.stringify(result, null, 2) + '\n'); return; }
+    if (_quietMode) { process.stdout.write(`${result.total_score}\n`); return; }
   } catch (err) {
     process.stdout.write(`\n`);
     blank();
@@ -373,18 +380,9 @@ async function cmdAnalyze(filePath) {
     blank();
   }
 
-  // ── Pro teaser
-  hr();
-  console.log(`  ${D}Free analysis complete. ${MG}Pro unlocks:${R}`);
-  console.log(`  ${D}  · Competitor headline comparison${R}`);
-  console.log(`  ${D}  · Landing page URL audit (full CRO analysis)${R}`);
-  console.log(`  ${D}  · Ad copy scoring (Google, Meta, LinkedIn)${R}`);
-  console.log(`  ${D}  · Twitter thread grader with shareability score${R}`);
-  console.log(`  ${D}  · Email subject line optimizer${R}`);
-  console.log(`  ${D}  · 100 analyses/day vs 3 free${R}`);
+  // ── Subtle upsell
   blank();
-  console.log(`  ${D}Start the web dashboard:  ${CY}content-grade start${R}`);
-  console.log(`  ${D}Grade a headline:         ${CY}content-grade headline "Your text here"${R}`);
+  console.log(`  ${D}Unlock team features at ${CY}contentgrade.dev${R}`);
   blank();
 }
 
@@ -579,7 +577,7 @@ async function cmdInit() {
     console.log(`  ${CY}content-grade start${R}`);
     blank();
   }
-  console.log(`  ${D}Pro tier ($9/mo): 100 analyses/day + competitor comparison + URL audits${R}`);
+  console.log(`  ${D}Pro tier ($9/mo): 100 analyses/day (vs 50 free) + competitor comparison + URL audits${R}`);
   blank();
 }
 
@@ -657,7 +655,7 @@ function cmdStart() {
       info(`  EmailForge      — ${url}/email-forge`);
       info(`  AudienceDecoder — ${url}/audience`);
       blank();
-      info(`Free tier: 3 analyses/day. Upgrade at ${url}`);
+      info(`Free tier: 50 analyses/day. Upgrade at ${url}`);
       info(`Press Ctrl+C to stop`);
       blank();
       openBrowser(url);
@@ -758,7 +756,7 @@ function cmdHelp() {
 
   console.log(`  ${B}PRO TIER${R}  ${MG}$9/month${R}`);
   blank();
-  console.log(`    · 100 analyses/day (vs 3 free)`);
+  console.log(`    · 100 analyses/day (vs 50 free)`);
   console.log(`    · Competitor headline A/B comparison`);
   console.log(`    · Landing page URL audit`);
   console.log(`    · Ad copy scoring (Google, Meta, LinkedIn)`);
@@ -787,6 +785,18 @@ In conclusion, these productivity tips are very helpful. Try them today and you
 `;
 
 async function cmdDemo() {
+  // If Claude isn't installed, skip the demo and run guided setup instead
+  if (!checkClaude()) {
+    console.log('');
+    console.log(`  ${B}${CY}Welcome to ContentGrade${R}`);
+    console.log('');
+    console.log(`  ${D}ContentGrade needs Claude CLI to run analysis.${R}`);
+    console.log(`  ${D}Let's get you set up — it only takes a minute.${R}`);
+    console.log('');
+    await cmdInit();
+    return;
+  }
+
   const tmpFile = `/tmp/content-grade-demo-${process.pid}-${Date.now()}.md`;
 
   banner();
@@ -799,6 +809,107 @@ async function cmdDemo() {
   blank();
 
   writeFileSync(tmpFile, DEMO_CONTENT, 'utf8');
+  try {
+    await cmdAnalyze(tmpFile);
+    // Show telemetry notice after user has seen value (first run only)
+    if (_showTelemNotice) {
+      console.log(`  ${D}Anonymous usage data is collected by default. Opt out: ${CY}content-grade telemetry off${R}`);
+      blank();
+    }
+  } finally {
+    try { unlinkSync(tmpFile); } catch {}
+  }
+}
+
+// ── URL fetcher ───────────────────────────────────────────────────────────────
+
+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) => {
+      // Follow one redirect
+      if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
+        fetchUrl(res.headers.location).then(resolve).catch(reject);
+        res.resume();
+        return;
+      }
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        res.resume();
+        return;
+      }
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8', 0, 500000)));
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+  });
+}
+
+function htmlToText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<nav[\s\S]*?<\/nav>/gi, ' ')
+    .replace(/<footer[\s\S]*?<\/footer>/gi, ' ')
+    .replace(/<header[\s\S]*?<\/header>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<(h[1-6])[^>]*>([\s\S]*?)<\/\1>/gi, (_, _t, txt) => `\n\n## ${txt}\n\n`)
+    .replace(/<(p|li|blockquote)[^>]*>([\s\S]*?)<\/\1>/gi, (_, _t, txt) => `\n${txt}\n`)
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ')
+    .replace(/[ \t]{2,}/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+async function cmdAnalyzeUrl(url) {
+  banner();
+  console.log(`  ${B}Analyzing URL:${R} ${CY}${url}${R}`);
+  blank();
+
+  if (!checkClaude()) {
+    fail(`Claude CLI not found.`);
+    blank();
+    console.log(`  ContentGrade uses your local Claude CLI — no API keys needed.`);
+    console.log(`  Install from ${CY}https://claude.ai/code${R} then run ${CY}claude login${R}`);
+    blank();
+    process.exit(1);
+  }
+
+  process.stdout.write(`  ${D}Fetching page...${R}`);
+  let html;
+  try {
+    html = await fetchUrl(url);
+    process.stdout.write(`\r  ${GN}✓${R} Page fetched${' '.repeat(20)}\n`);
+  } catch (err) {
+    process.stdout.write(`\n`);
+    blank();
+    fail(`Could not fetch URL: ${err.message}`);
+    blank();
+    console.log(`  ${YL}Check:${R}`);
+    console.log(`  ${D}· URL is accessible (try opening it in a browser)${R}`);
+    console.log(`  ${D}· You have internet access${R}`);
+    blank();
+    process.exit(1);
+  }
+
+  const text = htmlToText(html);
+  if (text.length < 50) {
+    blank();
+    fail(`Could not extract readable content from ${url}`);
+    blank();
+    console.log(`  ${D}The page may be JavaScript-rendered. Try saving the page content to a .md file and running:${R}`);
+    console.log(`  ${CY}  content-grade analyze ./page.md${R}`);
+    blank();
+    process.exit(1);
+  }
+
+  const tmpFile = `/tmp/content-grade-url-${process.pid}-${Date.now()}.md`;
+  writeFileSync(tmpFile, `# ${url}\n\n${text}`, 'utf8');
   try {
     await cmdAnalyze(tmpFile);
   } finally {
@@ -853,19 +964,17 @@ function findBestContentFile(dirPath) {
 
 // ── Router ────────────────────────────────────────────────────────────────────
 
-const args = process.argv.slice(2).filter(a => a !== '--no-telemetry');
+const _rawArgs   = process.argv.slice(2);
+const _jsonMode  = _rawArgs.includes('--json');
+const _quietMode = _rawArgs.includes('--quiet');
+const args = _rawArgs.filter(a => a !== '--no-telemetry' && a !== '--json' && a !== '--quiet');
 const raw  = args[0];
 const cmd  = raw?.toLowerCase();
 
 // ── Telemetry init ────────────────────────────────────────────────────────────
 const _telem = initTelemetry();
-if (_telem.isNew) {
-  // Show notice once, on first run
-  blank();
-  console.log(`  ${D}ContentGrade collects anonymous usage data (command name, score, duration).${R}`);
-  console.log(`  ${D}No file contents, no PII. To opt out: ${CY}content-grade telemetry off${R}${D} or pass ${CY}--no-telemetry${R}`);
-  blank();
-}
+// Defer first-run telemetry notice so users see value first
+const _showTelemNotice = _telem.isNew;
 
 // Smart path detection: first arg is a path if it starts with ., /, ~ or is an existing FS entry
 function looksLikePath(s) {
@@ -984,7 +1093,15 @@ switch (cmd) {
     break;
 
   default:
-    if (looksLikePath(raw)) {
+    if (/^https?:\/\//i.test(raw)) {
+      recordEvent({ event: 'command', command: 'analyze_url' });
+      cmdAnalyzeUrl(raw).catch(err => {
+        blank();
+        fail(`Unexpected error: ${err.message}`);
+        blank();
+        process.exit(1);
+      });
+    } else if (looksLikePath(raw)) {
       // Directory: find best content file inside it
       let target;
       try {

package/dist-server/server/routes/demos.js

@@ -5,7 +5,7 @@ import { getDb } from '../db.js';
 import { askClaude } from '../claude.js';
 import { hasActiveSubscriptionLive, hasPurchased } from '../services/stripe.js';
 // ── Usage tracking utilities ──────────────────────────────────────
-const FREE_TIER_LIMIT = 3;
+const FREE_TIER_LIMIT = 50;
 const PRO_TIER_LIMIT = 100;
 const HEADLINE_GRADER_ENDPOINT = 'headline-grader';
 const UPGRADE_URL = 'https://contentgrade.ai/#pricing';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-grade",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "AI-powered content analysis CLI. Score any blog post, landing page, or ad copy in under 30 seconds — runs on Claude CLI, no API key needed.",
   "type": "module",
   "bin": {
@@ -50,7 +50,12 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "stats": "node scripts/npm-stats.js",
-    "stats:week": "node scripts/npm-stats.js --week"
+    "stats:week": "node scripts/npm-stats.js --week",
+    "metrics": "node scripts/metrics.js",
+    "metrics:save": "node scripts/metrics.js --save",
+    "metrics:history": "node scripts/metrics.js --history",
+    "metrics:csv": "node scripts/metrics.js --csv",
+    "github-traffic": "node scripts/github-traffic.js"
   },
   "dependencies": {
     "@fastify/cors": "^9.0.1",