content-grade 1.0.12 → 1.0.14

package/CONTRIBUTING.md

@@ -1,198 +1,47 @@
-# Contributing to ContentGrade
+# Contributing to Content-Grade
 
-Thanks for wanting to contribute. ContentGrade is a CLI + web dashboard for AI-powered content scoring. It runs entirely on local Claude CLI — no API keys, no external services (unless you add Stripe).
+## Reporting bugs
 
----
+Open an issue using the **Bug report** template. Include:
+- Your Node.js version (`node --version`)
+- The exact command you ran
+- Output of `npx content-grade init` if it's a setup issue
+- Expected vs. actual behavior
 
-## Prerequisites
+## Suggesting features
 
-- **Node.js 18+**
-- **pnpm** (`npm install -g pnpm`)
-- **Claude CLI** — installed and logged in ([claude.ai/code](https://claude.ai/code))
-- Verify: `claude -p "say hi"`
+Open an issue using **Feature request**, or post in [GitHub Discussions → Ideas](https://github.com/StanislavBG/Content-Grade/discussions/categories/ideas). Describe the use case, not just the feature.
 
----
+## Submitting a pull request
 
-## Local development setup
+1. Fork the repo, create a branch from `main`
+2. Make changes — see code style notes below
+3. Run the full check before opening a PR:
 
 ```bash
-git clone https://github.com/Content-Grade/Content-Grade
-cd Content-Grade
-pnpm install
-pnpm dev
+npm test          # all tests must pass
+npm run typecheck # zero TypeScript errors
 ```
 
-This starts two processes concurrently:
-- **Client** (Vite) at [http://localhost:3000](http://localhost:3000) with hot reload
-- **Server** (tsx watch) at [http://localhost:4000](http://localhost:4000) with hot reload
+4. Open a PR with a clear description of what changed and why
 
-The client proxies API requests to the server automatically.
+## Code style
 
----
+Scripts from `package.json` tell you what tools are in play:
 
-## Project structure
+| Script | What it does |
+|--------|-------------|
+| `npm test` | vitest — run once, all tests green |
+| `npm run test:watch` | vitest watch mode during development |
+| `npm run test:coverage` | coverage report (v8) |
+| `npm run typecheck` | `tsc --noEmit` — types must be clean |
+| `npm run build` | vite + tsc server build — must pass before release |
 
-```
-bin/
-  content-grade.js          CLI entry point — all CLI commands live here
-server/
-  app.ts                    Fastify app factory (used by server and tests)
-  index.ts                  Production server entry (binds port)
-  claude.ts                 Claude CLI wrapper (server-side)
-  db.ts                     SQLite setup — usage tracking, stripe subscriptions
-  routes/
-    demos.ts                API routes for all 6 web dashboard tools
-    stripe.ts               Stripe checkout, webhooks, subscription management
-  services/
-    claude.ts               askClaude() helper for route handlers
-    stripe.ts               Stripe helpers — subscription checks, customer management
-src/
-  App.tsx                   React app router
-  main.tsx                  React entry point
-  views/
-    HeadlineGraderView.tsx
-    PageRoastView.tsx
-    AdScorerView.tsx
-    ThreadGraderView.tsx
-    EmailForgeView.tsx
-    AudienceDecoderView.tsx
-    ContentGradeShared.tsx  Shared UI components
-  data/
-    api.ts                  API client for the web dashboard
-tests/
-  unit/                     Unit tests (no Claude required)
-  integration/              Integration tests (spins up Fastify)
-  helpers/
-    db.ts                   Test database helpers
-```
-
----
-
-## Running tests
-
-```bash
-pnpm test               # run all tests once
-pnpm test:watch         # watch mode — reruns on file changes
-pnpm test:coverage      # full coverage report
-```
-
-Tests live in `tests/unit/` and `tests/integration/`. Integration tests spin up a real Fastify server but mock Claude responses — they don't require a live Claude CLI.
-
-Unit tests cover:
-- `tests/unit/validation.test.ts` — input validation
-- `tests/unit/cli-utils.test.ts` — CLI helper functions
-- `tests/unit/rate-limit.test.ts` — rate limit logic
-- `tests/unit/edge-cases.test.ts` — edge case handling
-- `tests/unit/quality-hardening.test.ts` — error path hardening
-
----
-
-## TypeScript
-
-```bash
-pnpm typecheck    # run tsc --noEmit — check types without building
-```
-
-The project has two TypeScript configs:
-- `tsconfig.json` — client (Vite, React, ESNext)
-- `tsconfig.server.json` — server (Node.js ESM, outputs to `dist-server/`)
-
-Both must pass before merging.
-
----
-
-## Building for production
-
-```bash
-pnpm build    # builds client (dist/) and server (dist-server/)
-pnpm start    # runs the production server
-```
-
-After building, test the full CLI flow:
-
-```bash
-node bin/content-grade.js init
-node bin/content-grade.js demo
-node bin/content-grade.js start
-```
-
----
-
-## Making changes
-
-### Adding or modifying CLI commands
-
-All CLI logic lives in `bin/content-grade.js`. The router is the `switch (cmd)` block at the bottom.
-
-Pattern for a new command:
-1. Add a `cmdFoo(args)` async function
-2. Add a `case 'foo':` branch in the switch
-3. Follow the existing error handling pattern: `blank()`, `fail()`, `process.exit(1)`
-4. Use `checkClaude()` before any `askClaude()` call
-
-### Adding a new web dashboard tool
-
-1. Create `src/views/FooView.tsx` — follow the pattern of existing views
-2. Add a route in `App.tsx`
-3. Add an API endpoint in `server/routes/demos.ts`
-4. Add the endpoint name to `FREE_TIER_LIMIT` tracking in `demos.ts`
-5. Add to the tool list in `bin/content-grade.js` `cmdStart()` output
-
-### Modifying Claude prompts
-
-Prompts are inline in `bin/content-grade.js` (CLI) and `server/routes/demos.ts` (web). Both require JSON-only responses — the parser handles both clean JSON and JSON embedded in markdown fences.
-
-The scoring calibration note at the bottom of each prompt is load-bearing: without it, Claude uses a compressed range and most content scores 50-70. Keep it.
-
----
-
-## Claude model selection
-
-| Use case | Model | Why |
-|----------|-------|-----|
-| `analyze` command | `claude-sonnet-4-6` | Richer analysis, better calibration |
-| `headline` command | `claude-haiku-4-5-20251001` | Fast, good enough for structured scoring |
-| `init` smoke test | `claude-haiku-4-5-20251001` | Just needs a JSON ping |
-| Web dashboard tools | `claude-haiku-4-5-20251001` | Server-side, latency-sensitive |
-
----
-
-## Rate limiting
-
-The web dashboard uses SQLite-backed IP rate limiting:
-- Free tier: 3 analyses/day per tool per IP (IP is SHA-256 hashed, never stored raw)
-- Pro tier: 100 analyses/day — verified against Stripe API with a 5-minute cache
-- AudienceDecoder: one-time purchase model (different Stripe Price ID)
-
-The CLI (`analyze`, `headline`) has no rate limiting — it calls Claude directly from your machine.
-
----
-
-## Stripe setup (optional)
-
-The app works without Stripe — upgrade prompts show "Coming Soon" instead of a checkout button.
-
-To enable payments:
-1. Copy `.env.example` to `.env`
-2. Add your Stripe keys
-3. Create products in Stripe dashboard — get the Price IDs
-4. Add `STRIPE_PRICE_CONTENTGRADE_PRO` and `STRIPE_PRICE_AUDIENCEDECODER`
-5. Set up a webhook pointing to `/api/stripe/webhook`
-
----
-
-## Pull request checklist
-
-- [ ] `pnpm typecheck` passes (zero TypeScript errors)
-- [ ] `pnpm test` passes (all tests green)
-- [ ] CLI smoke test passes: `node bin/content-grade.js demo`
-- [ ] No hardcoded API keys or credentials
-- [ ] Error paths follow the existing pattern (`blank()`, `fail()`, `process.exit(1)`)
-- [ ] New Claude prompts include the scoring calibration note
-- [ ] PR description explains what changed and why
-
----
+- TypeScript throughout — no `any` without a comment explaining why
+- CLI errors use `fail()` helper, never raw `console.error` + `process.exit`
+- New Claude prompts must include the scoring calibration note (see existing prompts)
+- No hardcoded API keys or credentials anywhere
 
 ## Questions
 
-Open an issue or start a GitHub Discussion. Include your Node.js version, OS, and the output of `npx content-grade init` if it's a setup issue.
+Post in [GitHub Discussions → Q&A](https://github.com/StanislavBG/Content-Grade/discussions/categories/q-a).

package/README.md

@@ -63,7 +63,7 @@ npx content-grade 'blog/**/*.md'
 
 **JSON output for CI integration:**
 ```bash
-npx content-grade README.md --format json
+npx content-grade README.md --json
 # Returns structured JSON with score, grade, dimensions, and improvements
 # Exit code 1 if score < 50 — useful for blocking low-quality merges
 ```
@@ -549,6 +549,7 @@ tests/
 
 **Documentation:**
 - [`docs/getting-started.md`](./docs/getting-started.md) — step-by-step first-run guide
+- [`docs/cli-reference.md`](./docs/cli-reference.md) — full CLI reference: all commands, flags, output schema, exit codes
 - [`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
 
@@ -974,6 +975,8 @@ Power users who go beyond early adoption get early access to `@beta` releases, a
 
 See **[CONTRIBUTING.md](CONTRIBUTING.md)** for local dev setup, PR guidelines, and how to write good bug reports. The short version: clone → `pnpm install` → `pnpm dev` → file a PR. All contributions get a review within 48 hours.
 
+Looking for a starting point? Browse **[`good first issue`](https://github.com/StanislavBG/Content-Grade/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)** — scoped tasks completable in a few hours with no prior codebase knowledge required. Each one has acceptance criteria and a pointer to exactly which file to touch.
+
 ### 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.

package/bin/content-grade.js

@@ -66,7 +66,7 @@ function incrementUsage() {
   return u.count;
 }
 
-const FREE_DAILY_LIMIT = 50;
+const FREE_DAILY_LIMIT = 5;
 
 function checkDailyLimit() {
   if (isProUser()) return { ok: true };
@@ -252,20 +252,30 @@ SCORING CALIBRATION:
 
 async function cmdAnalyze(filePath) {
   if (!filePath) {
+    if (_demoMode) {
+      return cmdDemo();
+    }
     blank();
     fail(`No file specified.`);
     blank();
-    console.log(`  Usage:`);
+    console.log(`  ${B}Usage:${R}`);
     console.log(`    ${CY}content-grade analyze <file>${R}    ${D}(or: check <file>)${R}`);
     blank();
-    console.log(`  Examples:`);
-    console.log(`    ${D}content-grade analyze ./blog-post.md${R}`);
-    console.log(`    ${D}content-grade check ./email-draft.txt${R}`);
-    console.log(`    ${D}content-grade analyze ~/landing-page-copy.md${R}`);
+    console.log(`  ${B}Examples:${R}`);
+    console.log(`    ${CY}content-grade analyze ./blog-post.md${R}`);
+    console.log(`    ${CY}content-grade check ./email-draft.txt${R}`);
+    console.log(`    ${CY}content-grade analyze ~/landing-page-copy.md${R}`);
     blank();
-    console.log(`  ${D}No file? Try the demo: ${CY}content-grade demo${R}`);
+    console.log(`  ${GN}Tip:${R} See it in action first — no file needed:`);
+    console.log(`    ${CY}content-grade --demo${R}              ${D}# live AI analysis on built-in sample${R}`);
+    console.log(`    ${CY}content-grade demo${R}                ${D}# same thing${R}`);
     blank();
-    process.exit(2);
+    process.exit(1);
+  }
+
+  // If input looks like a URL, delegate to URL analyzer
+  if (/^https?:\/\//i.test(filePath)) {
+    return cmdAnalyzeUrl(filePath);
   }
 
   const safeFilePath = sanitizeFilePath(filePath);
@@ -273,7 +283,7 @@ async function cmdAnalyze(filePath) {
     blank();
     fail(`Invalid file path.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
   filePath = safeFilePath;
 
@@ -285,7 +295,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(2);
+    process.exit(1);
   }
 
   // Guard: reject directories
@@ -296,7 +306,7 @@ async function cmdAnalyze(filePath) {
     blank();
     console.log(`  ${D}Pass a text file (.md, .txt) — not a directory.${R}`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   // Guard: reject files over 500 KB before reading into memory
@@ -307,7 +317,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(2);
+    process.exit(1);
   }
 
   const content = readFileSync(absPath, 'utf8');
@@ -320,14 +330,14 @@ 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(2);
+    process.exit(1);
   }
 
   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(2);
+    process.exit(1);
   }
 
   // Free tier daily limit
@@ -338,9 +348,9 @@ async function cmdAnalyze(filePath) {
     blank();
     console.log(`  ${B}Options:${R}`);
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
-    console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
+    console.log(`  ${D}· Unlock unlimited: ${CY}content-grade activate${R}`);
     blank();
-    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://buy.stripe.com/5kQeVfew48dT7nf2W48k801${R}`);
     blank();
     process.exit(1);
   }
@@ -491,20 +501,38 @@ async function cmdAnalyze(filePath) {
   // Track usage
   incrementUsage();
 
-  // Upsell — show Pro path after user has seen value
+  // Save to file if --save flag is set
+  if (_saveMode && result) {
+    const defaultSaveName = basename(absPath, extname(absPath)) + '.content-grade.md';
+    const outPath = resolve(process.cwd(), _savePath || defaultSaveName);
+    try {
+      writeFileSync(outPath, analysisToMarkdown(result, basename(absPath), new Date().toISOString().slice(0, 10)), 'utf8');
+      blank();
+      ok(`Saved to ${outPath}`);
+    } catch (saveErr) {
+      warn(`Could not save: ${saveErr.message}`);
+    }
+  }
+
+  // Next step — graduated CTA after user has seen value
   blank();
+  hr();
   if (isProUser()) {
-    console.log(`  ${D}Pro active · ${CY}content-grade.github.io/Content-Grade${R}`);
+    console.log(`  ${D}Pro active · Next: ${CY}content-grade batch ./posts/${R}${D} to analyze a whole directory${R}`);
   } else {
     const usage = getUsage();
     const remaining = Math.max(0, FREE_DAILY_LIMIT - usage.count);
-    hr();
-    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}content-grade.github.io/Content-Grade${R}`);
+    console.log(`  ${B}What to do next:${R}`);
     blank();
-    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${CY}content-grade headline "Your title here"${R}      ${D}# grade a headline in ~5s${R}`);
+    console.log(`  ${CY}content-grade analyze ./another-post.md${R}       ${D}# analyze another file${R}`);
+    console.log(`  ${CY}content-grade analyze https://yoursite.com/post${R}  ${D}# audit any live URL${R}`);
+    blank();
+    if (remaining <= 10) {
+      console.log(`  ${YL}${remaining} free checks left today.${R} Unlock unlimited: ${CY}content-grade activate${R}`);
+    } else {
+      console.log(`  ${D}${remaining} free checks left today · Pro ($9/mo): ${CY}content-grade.github.io/Content-Grade${R}`);
+    }
   }
 
   // CI exit code — shown after full output so user sees the score before exit
@@ -563,7 +591,7 @@ async function cmdHeadline(text) {
     console.log(`    ${D}content-grade headline "How We Grew From 0 to 10k Users Without Ads"${R}`);
     console.log(`    ${D}content-grade headline "Stop Doing This One Thing in Your Email Subject Lines"${R}`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   // Guard: reject oversized input
@@ -574,7 +602,7 @@ async function cmdHeadline(text) {
     blank();
     console.log(`  ${YL}Tip:${R} Trim your headline to the core message and try again.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   // Free tier daily limit
@@ -585,31 +613,41 @@ async function cmdHeadline(text) {
     blank();
     console.log(`  ${B}Options:${R}`);
     console.log(`  ${D}· Wait until tomorrow (limit resets at midnight)${R}`);
-    console.log(`  ${D}· Unlock 100 checks/day: ${CY}content-grade activate${R}`);
+    console.log(`  ${D}· Unlock unlimited: ${CY}content-grade activate${R}`);
     blank();
-    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://buy.stripe.com/5kQeVfew48dT7nf2W48k801${R}`);
     blank();
     process.exit(1);
   }
 
-  banner();
-  console.log(`  ${B}Grading headline:${R}`);
-  console.log(`  ${D}"${text}"${R}`);
-  blank();
+  if (!_jsonMode && !_quietMode) {
+    banner();
+    console.log(`  ${B}Grading headline:${R}`);
+    console.log(`  ${D}"${text}"${R}`);
+    blank();
+  }
 
   if (!checkClaude()) {
     fail(`Claude CLI not found. Run: ${CY}content-grade init${R}`);
     process.exit(1);
   }
 
-  process.stdout.write(`  ${D}Analyzing...${R}`);
+  if (!_jsonMode && !_quietMode) process.stdout.write(`  ${D}Analyzing...${R}`);
 
   let result;
   try {
     const raw = await askClaude(`Grade this headline: "${text}"`, HEADLINE_SYSTEM, 'claude-haiku-4-5-20251001');
-    process.stdout.write(`\r  ${GN}✓${R} Done${' '.repeat(20)}\n`);
+    if (!_jsonMode && !_quietMode) process.stdout.write(`\r  ${GN}✓${R} Done${' '.repeat(20)}\n`);
     result = parseJSON(raw);
     recordEvent({ event: 'headline_result', score: result.score });
+    if (_jsonMode) {
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+      return;
+    }
+    if (_quietMode) {
+      process.stdout.write(`${result.score}\n`);
+      return;
+    }
   } catch (err) {
     process.stdout.write(`\n`);
     blank();
@@ -667,7 +705,7 @@ async function cmdHeadline(text) {
   console.log(`  ${D}Compare two headlines:  ${CY}content-grade start${R}  → HeadlineGrader compare${R}`);
   blank();
   if (!isProUser()) {
-    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://content-grade.github.io/Content-Grade/${R}`);
+    console.log(`  ${MG}Upgrade to Pro ($9/mo) for unlimited analyses →${R}  ${CY}https://buy.stripe.com/5kQeVfew48dT7nf2W48k801${R}`);
     blank();
   }
 }
@@ -821,11 +859,11 @@ async function cmdActivate() {
     blank();
     fail(`Invalid key — must be at least 8 characters.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   // Validate key against server before storing
-  const serverUrl = process.env.CONTENT_GRADE_SERVER_URL || 'https://contentgrade.ai';
+  const serverUrl = process.env.CONTENT_GRADE_SERVER_URL || 'https://content-grade.github.io';
   blank();
   process.stdout.write(`  ${D}Validating key...${R}`);
 
@@ -842,9 +880,9 @@ async function cmdActivate() {
     } else {
       process.stdout.write('\n');
       blank();
-      fail(data.message || 'Invalid or expired license key. Visit contentgrade.ai to check your subscription.');
+      fail(data.message || 'Invalid or expired license key. Visit content-grade.github.io/Content-Grade to check your subscription.');
       blank();
-      process.exit(2);
+      process.exit(1);
     }
   } catch {
     // Server unreachable — allow offline activation with a warning
@@ -896,7 +934,7 @@ async function cmdBatch(dirPath) {
     console.log(`  Usage: ${CY}content-grade batch <directory>${R}`);
     console.log(`  Example: ${CY}content-grade batch ./posts${R}`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   const safeDirPath = sanitizeFilePath(dirPath);
@@ -904,7 +942,7 @@ async function cmdBatch(dirPath) {
     blank();
     fail(`Invalid directory path.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
   dirPath = safeDirPath;
 
@@ -913,7 +951,7 @@ async function cmdBatch(dirPath) {
     blank();
     fail(`Directory not found: ${absDir}`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   const st = statSync(absDir);
@@ -921,7 +959,7 @@ async function cmdBatch(dirPath) {
     blank();
     fail(`${dirPath} is not a directory. Use ${CY}content-grade analyze${R} for single files.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
 
   const files = [];
@@ -1090,7 +1128,7 @@ function cmdStart() {
       info(`  EmailForge      — ${url}/email-forge`);
       info(`  AudienceDecoder — ${url}/audience`);
       blank();
-      info(`Free tier: 50 analyses/day. Upgrade at ${url}`);
+      info(`Free tier: 5 analyses/day. Upgrade at ${url}`);
       info(`Press Ctrl+C to stop`);
       blank();
       openBrowser(url);
@@ -1269,10 +1307,11 @@ function cmdHelp() {
   blank();
   console.log(`  ${B}QUICK START${R}`);
   blank();
-  console.log(`    ${CY}npx content-grade headline "Your Headline Here"${R}  ${D}# grade a headline (fastest, ~5s)${R}`);
-  console.log(`    ${CY}npx content-grade analyze ./my-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}`);
+  console.log(`    ${CY}npx content-grade --demo${R}                            ${D}# live AI demo — no file needed, see it first${R}`);
+  console.log(`    ${CY}npx content-grade headline "Your Headline Here"${R}     ${D}# grade a headline (fastest, ~5s)${R}`);
+  console.log(`    ${CY}npx content-grade analyze ./my-post.md${R}              ${D}# full AI analysis of a file (~20s)${R}`);
+  console.log(`    ${CY}npx content-grade analyze https://example.com${R}       ${D}# audit any live URL (~20s)${R}`);
+  console.log(`    ${CY}npx content-grade start${R}                            ${D}# launch web dashboard (6 tools)${R}`);
   blank();
 
   console.log(`  ${B}USAGE${R}`);
@@ -1314,8 +1353,10 @@ function cmdHelp() {
   blank();
   console.log(`  ${B}FLAGS${R}`);
   blank();
+  console.log(`    ${CY}--demo${R}                  Run the live AI demo on built-in sample content`);
   console.log(`    ${CY}--json${R}                  Output raw JSON (great for CI pipelines)`);
   console.log(`    ${CY}--quiet${R}                 Output score number only (for scripting)`);
+  console.log(`    ${CY}--save [file]${R}           Save analysis to a markdown file (default: <input>.content-grade.md)`);
   console.log(`    ${CY}--ci${R}                    Exit 0 if score passes threshold, exit 1 if it fails`);
   console.log(`    ${CY}--threshold <n>${R}         Score threshold for --ci mode (default: 60)`);
   console.log(`    ${CY}--verbose${R}               Show debug info: model, timing, raw response length`);
@@ -1456,18 +1497,29 @@ function cmdQuickDemo() {
   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();
-
+  hr();
   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}`);
+    console.log(`  ${B}${CY}Try it on real content — 3 ways to start:${R}`);
+    blank();
+    console.log(`  ${B}1.${R} Grade a headline ${D}(~5 seconds, works right now)${R}`);
+    console.log(`     ${CY}npx content-grade headline "Your headline here"${R}`);
+    blank();
+    console.log(`  ${B}2.${R} Run the live AI demo ${D}(full analysis on sample content)${R}`);
+    console.log(`     ${CY}npx content-grade --demo${R}`);
+    blank();
+    console.log(`  ${B}3.${R} Analyze your own file`);
+    console.log(`     ${CY}npx content-grade analyze ./your-post.md${R}`);
     blank();
+    console.log(`  ${D}All three require Claude CLI (free): ${CY}claude.ai/code${R}${D} → install → ${CY}claude login${R}`);
+    console.log(`  ${D}First time? Run: ${CY}npx content-grade init${R}${D} to verify setup.${R}`);
+  } else {
+    console.log(`  ${B}${CY}Grade your own content:${R}`);
+    blank();
+    console.log(`  ${CY}npx content-grade --demo${R}                       ${D}# live AI demo${R}`);
+    console.log(`  ${CY}npx content-grade headline "Your headline here"${R}  ${D}# ~5 seconds${R}`);
+    console.log(`  ${CY}npx content-grade analyze ./your-post.md${R}         ${D}# full analysis${R}`);
   }
+  blank();
 }
 
 // ── Demo command ──────────────────────────────────────────────────────────────
@@ -1585,10 +1637,10 @@ async function cmdDemo() {
 
 // ── URL fetcher ───────────────────────────────────────────────────────────────
 
-function fetchUrl(url) {
+function fetchUrl(url, { rejectUnauthorized = true } = {}) {
   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/content-grade/Content-Grade)' }, timeout: 15000 }, (res) => {
+    const req = get(url, { headers: { 'User-Agent': 'ContentGrade/1.0 (+https://github.com/content-grade/Content-Grade)' }, timeout: 15000, rejectUnauthorized }, (res) => {
       // Follow one redirect — validate location is http/https before following
       if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location) {
         const loc = res.headers.location;
@@ -1597,7 +1649,7 @@ function fetchUrl(url) {
           res.resume();
           return;
         }
-        fetchUrl(loc).then(resolve).catch(reject);
+        fetchUrl(loc, { rejectUnauthorized }).then(resolve).catch(reject);
         res.resume();
         return;
       }
@@ -1611,7 +1663,16 @@ function fetchUrl(url) {
       res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8', 0, 500000)));
       res.on('error', reject);
     });
-    req.on('error', reject);
+    req.on('error', (err) => {
+      // TLS cert failures: retry without verification (dev tool — user may be auditing
+      // internal sites with self-signed certs or proxies that intercept TLS)
+      const isCertErr = err.code && /CERT|SELF_SIGNED|UNABLE_TO/i.test(err.code);
+      if (isCertErr && rejectUnauthorized) {
+        fetchUrl(url, { rejectUnauthorized: false }).then(resolve).catch(reject);
+        return;
+      }
+      reject(err);
+    });
     req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
   });
 }
@@ -1641,13 +1702,13 @@ async function cmdAnalyzeUrl(url) {
     blank();
     fail(`Invalid URL: must start with http:// or https://`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
   if (sanitizedUrl.length > 2048) {
     blank();
     fail(`URL too long (${sanitizedUrl.length} chars). Maximum is 2048.`);
     blank();
-    process.exit(2);
+    process.exit(1);
   }
   url = sanitizedUrl;
 
@@ -1746,6 +1807,78 @@ function findBestContentFile(dirPath) {
   return scored[0].path;
 }
 
+// ── Save analysis to markdown ─────────────────────────────────────────────────
+
+function analysisToMarkdown(result, sourceName, analyzedAt) {
+  const grade = result.grade ?? gradeLetter(result.total_score).replace(/\x1b\[[0-9;]*m/g, '');
+  const lines = [];
+  lines.push(`# ContentGrade Report: ${sourceName}`);
+  lines.push(``);
+  lines.push(`Analyzed: ${analyzedAt}  `);
+  lines.push(`Overall score: **${result.total_score}/100 (${grade})**  `);
+  if (result.content_type) lines.push(`Content type: ${result.content_type.replace('_', ' ')}`);
+  lines.push(``);
+
+  if (result.headline?.text) {
+    lines.push(`## Headline`);
+    lines.push(``);
+    lines.push(`> ${result.headline.text}`);
+    lines.push(``);
+    lines.push(`Score: ${result.headline.score}/100`);
+    if (result.headline.feedback) lines.push(`${result.headline.feedback}`);
+    lines.push(``);
+  }
+
+  if (result.one_line_verdict) {
+    lines.push(`## Verdict`);
+    lines.push(``);
+    lines.push(`${result.one_line_verdict}`);
+    lines.push(``);
+  }
+
+  if (result.dimensions) {
+    lines.push(`## Dimension Breakdown`);
+    lines.push(``);
+    for (const [, dim] of Object.entries(result.dimensions)) {
+      lines.push(`**${dim.label}**: ${dim.score}/100`);
+      if (dim.feedback) lines.push(`${dim.feedback}`);
+      lines.push(``);
+    }
+  }
+
+  if (result.strengths?.length) {
+    lines.push(`## Strengths`);
+    lines.push(``);
+    for (const s of result.strengths) lines.push(`- ${s}`);
+    lines.push(``);
+  }
+
+  if (result.improvements?.length) {
+    lines.push(`## Top Improvements`);
+    lines.push(``);
+    for (const imp of result.improvements) {
+      const pri = imp.priority === 'high' ? '🔴' : '🟡';
+      lines.push(`### ${pri} ${imp.issue}`);
+      lines.push(``);
+      lines.push(`**Fix:** ${imp.fix}`);
+      lines.push(``);
+    }
+  }
+
+  if (result.headline_rewrites?.length) {
+    lines.push(`## Headline Rewrites`);
+    lines.push(``);
+    for (let i = 0; i < result.headline_rewrites.length; i++) {
+      lines.push(`${i + 1}. ${result.headline_rewrites[i]}`);
+    }
+    lines.push(``);
+  }
+
+  lines.push(`---`);
+  lines.push(`Generated by [ContentGrade](https://buy.stripe.com/5kQeVfew48dT7nf2W48k801) v${_version}`);
+  return lines.join('\n');
+}
+
 // ── Router ────────────────────────────────────────────────────────────────────
 
 const _rawArgs    = process.argv.slice(2);
@@ -1757,10 +1890,17 @@ const _threshIdx  = _rawArgs.indexOf('--threshold');
 const _ciThreshold = (_threshIdx !== -1 && _rawArgs[_threshIdx + 1])
   ? (parseInt(_rawArgs[_threshIdx + 1], 10) || 60)
   : 60;
+const _saveIdx  = _rawArgs.indexOf('--save');
+const _saveMode = _saveIdx !== -1;
+const _savePath = (_saveMode && _rawArgs[_saveIdx + 1] && !_rawArgs[_saveIdx + 1].startsWith('-'))
+  ? _rawArgs[_saveIdx + 1]
+  : null;
+const _demoMode = _rawArgs.includes('--demo');
 const args = _rawArgs.filter((a, i) => {
-  if (['--no-telemetry', '--json', '--quiet', '--verbose', '--ci'].includes(a)) return false;
+  if (['--no-telemetry', '--json', '--quiet', '--verbose', '--ci', '--save', '--demo'].includes(a)) return false;
   if (a === '--threshold') return false;
   if (i > 0 && _rawArgs[i - 1] === '--threshold') return false;
+  if (_saveMode && i > 0 && _rawArgs[i - 1] === '--save' && !a.startsWith('-')) return false;
   return true;
 });
 const raw  = args[0];
@@ -1779,7 +1919,119 @@ function looksLikePath(s) {
   try { statSync(resolve(process.cwd(), s)); return true; } catch { return false; }
 }
 
-switch (cmd) {
+// Per-command --help: "content-grade <cmd> --help" → command-specific help
+if (_rawArgs.includes('--help') || _rawArgs.includes('-h')) {
+  switch (cmd) {
+    case 'analyze':
+    case 'analyse':
+    case 'check':
+    case 'grade':
+      blank();
+      console.log(`  ${B}content-grade analyze <file>${R}  ${D}(aliases: grade, check)${R}`);
+      blank();
+      console.log(`  Analyzes written content and returns an AI-powered score (0–100) with`);
+      console.log(`  dimension breakdown, specific improvements, and headline rewrites.`);
+      blank();
+      console.log(`  ${B}Arguments:${R}`);
+      console.log(`    ${CY}<file>${R}              Path to a .md, .txt, or .mdx file`);
+      blank();
+      console.log(`  ${B}Flags:${R}`);
+      console.log(`    ${CY}--demo${R}             Run on built-in sample content (no file needed)`);
+      console.log(`    ${CY}--json${R}             Output raw JSON (great for CI pipelines)`);
+      console.log(`    ${CY}--quiet${R}            Output score number only (for scripting)`);
+      console.log(`    ${CY}--ci${R}               Exit 0 if score passes, 1 if it fails`);
+      console.log(`    ${CY}--threshold <n>${R}    Score threshold for --ci (default: 60)`);
+      console.log(`    ${CY}--verbose${R}          Show debug info: model, timing, response length`);
+      blank();
+      console.log(`  ${B}Examples:${R}`);
+      console.log(`    ${CY}content-grade analyze --demo${R}                   ${D}# live demo on sample content${R}`);
+      console.log(`    ${CY}content-grade analyze ./blog-post.md${R}`);
+      console.log(`    ${CY}content-grade analyze ./readme.md --json${R}`);
+      console.log(`    ${CY}content-grade analyze ./copy.md --ci --threshold 70${R}`);
+      console.log(`    ${D}# store score in a variable${R}`);
+      console.log(`    ${CY}score=\$(content-grade analyze ./post.md --quiet)${R}`);
+      blank();
+      process.exit(0);
+      break;
+    case 'headline':
+      blank();
+      console.log(`  ${B}content-grade headline "<text>"${R}`);
+      blank();
+      console.log(`  Grades a single headline using 4 direct response copywriting frameworks:`);
+      console.log(`  Rule of One, Value Equation, Readability, and Proof/Promise.`);
+      console.log(`  Returns a 0–100 score, verdict, and 2 stronger rewrites. Takes ~5 seconds.`);
+      blank();
+      console.log(`  ${B}Arguments:${R}`);
+      console.log(`    ${CY}"<text>"${R}           The headline to grade (quote it to avoid shell expansion)`);
+      blank();
+      console.log(`  ${B}Flags:${R}`);
+      console.log(`    ${CY}--json${R}             Output raw JSON`);
+      console.log(`    ${CY}--quiet${R}            Output score number only`);
+      console.log(`    ${CY}--verbose${R}          Show debug info`);
+      blank();
+      console.log(`  ${B}Examples:${R}`);
+      console.log(`    ${CY}content-grade headline "The 5-Minute Fix That Doubles Landing Page Conversions"${R}`);
+      console.log(`    ${CY}content-grade headline "How We Grew From 0 to 10k Users" --json${R}`);
+      blank();
+      process.exit(0);
+      break;
+    case 'seo-audit':
+    case 'seoaudit':
+      blank();
+      console.log(`  ${B}content-grade seo-audit <url>${R}`);
+      blank();
+      console.log(`  Fetches a live URL, extracts readable content, and runs the same full AI`);
+      console.log(`  analysis as the analyze command. Good for auditing competitors or your own pages.`);
+      blank();
+      console.log(`  ${B}Arguments:${R}`);
+      console.log(`    ${CY}<url>${R}              Full URL starting with http:// or https://`);
+      blank();
+      console.log(`  ${B}Flags:${R}`);
+      console.log(`    ${CY}--json${R}             Output raw JSON`);
+      console.log(`    ${CY}--quiet${R}            Output score number only`);
+      console.log(`    ${CY}--ci${R}               Exit 0/1 based on score threshold`);
+      console.log(`    ${CY}--threshold <n>${R}    Score threshold for --ci (default: 60)`);
+      blank();
+      console.log(`  ${B}Examples:${R}`);
+      console.log(`    ${CY}content-grade seo-audit https://yoursite.com/blog-post${R}`);
+      console.log(`    ${CY}content-grade seo-audit https://example.com --json${R}`);
+      blank();
+      process.exit(0);
+      break;
+    case 'batch':
+      blank();
+      console.log(`  ${B}content-grade batch <directory>${R}  ${MG}[Pro]${R}`);
+      blank();
+      console.log(`  Analyzes all .md, .txt, and .mdx files in a directory and prints a sorted`);
+      console.log(`  summary with scores. Requires a Pro license.`);
+      blank();
+      console.log(`  ${B}Arguments:${R}`);
+      console.log(`    ${CY}<directory>${R}        Path to a directory containing content files`);
+      blank();
+      console.log(`  ${B}Flags:${R}`);
+      console.log(`    ${CY}--json${R}             Output results as a JSON array (replaces styled output)`);
+      blank();
+      console.log(`  ${B}Examples:${R}`);
+      console.log(`    ${CY}content-grade batch ./posts${R}`);
+      console.log(`    ${CY}content-grade batch ./content --json${R}`);
+      blank();
+      process.exit(0);
+      break;
+    default:
+      cmdHelp();
+      process.exit(0);
+  }
+}
+
+if (_demoMode) {
+  recordEvent({ event: 'command', command: 'demo' });
+  cmdDemo().catch(err => {
+    blank();
+    fail(`Demo error: ${err.message}`);
+    blank();
+    process.exit(1);
+  });
+} else switch (cmd) {
   case 'analyze':
   case 'analyse':
   case 'check':
@@ -1851,7 +2103,7 @@ switch (cmd) {
       console.log(`  ${B}Usage:${R}   ${CY}content-grade seo-audit <url>${R}`);
       console.log(`  ${B}Example:${R} ${CY}content-grade seo-audit https://yoursite.com/blog-post${R}`);
       blank();
-      process.exit(2);
+      process.exit(1);
     }
     cmdAnalyzeUrl(args[1]).catch(err => {
       blank();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-grade",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "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": {