content-grade 1.0.5 → 1.0.7

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,56 @@
 ## 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"
+```
+
+**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. `npx content-grade grade README.md` works immediately.
+
+**Install globally** (recommended — skips the `npx` download on every run):
+
+```bash
+npm install -g content-grade
+content-grade --help
+```
 
-# 6. Unlock Pro (batch mode, 100/day limit)
-npx content-grade activate
+```bash
+# More commands
+content-grade https://yourblog.com/post    # analyze any URL
+content-grade analyze ./post.md --json     # raw JSON for CI pipelines
+content-grade analyze ./post.md --quiet    # score number only (for scripts)
+content-grade activate                     # unlock Pro: batch mode, 100/day
 ```
 
-**One requirement:** [Claude CLI](https://claude.ai/code) must be installed and logged in. No API keys, no accounts, no data leaves your machine.
+---
+
+## Usage Examples
 
-**Free tier:** 50 analyses/day, no signup needed. `npx content-grade grade README.md` works immediately.
+**Grade a single file:**
+```bash
+npx content-grade article.md
+```
+
+**Grade multiple files with a glob pattern:**
+```bash
+npx content-grade 'blog/**/*.md'
+```
+
+**JSON output for CI integration:**
+```bash
+npx content-grade README.md --format json
+# Returns structured JSON with score, grade, dimensions, and improvements
+# Exit code 1 if score < 50 — useful for blocking low-quality merges
+```
 
 ---
 
@@ -107,6 +135,7 @@ npx content-grade activate
 | `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 |
+| `check-updates` | Check if a newer version is available on npm |
 | `help` | Full usage and examples |
 
 **Flags:**
@@ -116,6 +145,7 @@ npx content-grade activate
 | `--json` | Raw JSON output — pipe to `jq` for CI integration |
 | `--quiet` | Score number only — for shell scripts |
 | `--version` | Print version |
+| `--verbose` | Show debug info (model, timing, Claude response length) |
 | `--no-telemetry` | Skip usage tracking for this run |
 
 **Global flags:**
@@ -141,7 +171,20 @@ 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: **50 analyses/day per tool**. Pro ($19/mo): **100 analyses/day** + all tools.
+Free tier: **50 analyses/day per tool**. Pro ($9/mo): **100 analyses/day** + all tools.
+
+---
+
+## Join the Discussion
+
+**[GitHub Discussions](https://github.com/Content-Grade/Content-Grade/discussions)** — ask questions, share setups, vote on what gets built next.
+
+Active threads:
+- [What content quality checks matter most to you?](https://github.com/Content-Grade/Content-Grade/discussions/1) — General
+- [Show your ContentGrade setup — configs, workflows, CI integrations](https://github.com/Content-Grade/Content-Grade/discussions/2) — Show & Tell
+- [Feature requests & roadmap input](https://github.com/Content-Grade/Content-Grade/discussions/3) — Ideas
+- [Content scoring in CI — who is actually doing this?](https://github.com/Content-Grade/Content-Grade/discussions/4) — General
+- [What integrations would make ContentGrade essential to your workflow?](https://github.com/Content-Grade/Content-Grade/discussions/5) — Ideas
 
 ---
 
@@ -160,6 +203,112 @@ If this fails, run `npx content-grade init` for step-by-step diagnostics.
 
 ---
 
+---
+
+## Troubleshooting
+
+### `Error: Claude CLI not found`
+
+ContentGrade requires Claude CLI. Install it:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+Then verify it works:
+
+```bash
+claude -p "say hi"
+```
+
+If Claude is installed but not on your PATH, set `CLAUDE_PATH`:
+
+```bash
+CLAUDE_PATH=/path/to/claude content-grade analyze ./post.md
+```
+
+Or add it permanently to your shell profile:
+
+```bash
+export CLAUDE_PATH=/path/to/claude
+```
+
+---
+
+### Analysis times out or hangs
+
+Claude CLI calls can take 10–60 seconds on first run. If it hangs beyond 2 minutes:
+
+1. Test Claude directly: `claude -p "say hi"` — if this hangs too, Claude CLI is the issue
+2. Check your internet connection (Claude CLI phones home on first use)
+3. Run `content-grade init` for a guided diagnostic
+
+---
+
+### `Could not parse response as JSON`
+
+This means Claude returned a non-JSON response. Common causes:
+
+- Claude CLI rate-limited your account (try again in a few minutes)
+- The file content was too short or unrecognizable as text content
+- Claude returned an error message instead of scoring output
+
+Run with `--verbose` to see the raw response:
+
+```bash
+content-grade analyze ./post.md --verbose
+```
+
+---
+
+### Daily limit reached
+
+Free tier: 50 CLI analyses/day, resets at midnight UTC.
+
+```
+✗ Daily limit reached (50/50 free checks used today).
+```
+
+Options:
+- Wait until midnight UTC for the limit to reset
+- Unlock 100/day with Pro: `content-grade activate`
+
+---
+
+### `content-grade: command not found` after global install
+
+If `npm install -g content-grade` succeeded but the command isn't found:
+
+```bash
+# Find where npm puts global binaries
+npm bin -g
+
+# Add to PATH — for bash/zsh, add this to ~/.bashrc or ~/.zshrc:
+export PATH="$(npm bin -g):$PATH"
+```
+
+---
+
+### `activate` says "Could not reach server"
+
+The activation server may be temporarily unreachable. The key is stored locally without online verification — this is normal and your Pro access will still work for CLI tools. Re-run `content-grade activate` to re-verify once the server is back.
+
+---
+
+### Something else is broken
+
+Run the built-in diagnostic:
+
+```bash
+content-grade init
+```
+
+This checks: Claude CLI on PATH, live smoke test, production build status. It will tell you exactly what's wrong.
+
+Still stuck? Open an issue: [github.com/Content-Grade/Content-Grade/issues](https://github.com/Content-Grade/Content-Grade/issues)
+
+
 ## CLI reference
 
 ### `analyze` / `check`
@@ -291,6 +440,53 @@ Scans up to 2 directory levels deep for `.md`, `.txt`, and `.mdx` files. Picks t
 
 ---
 
+---
+
+### `check-updates`
+
+```bash
+content-grade check-updates
+```
+
+Checks npm for the latest published version of `content-grade` and compares it against the installed version. If an update is available, prints the upgrade command.
+
+```bash
+  ⚠  Update available: v1.0.4  →  v1.0.5
+  Update with:
+    npm install -g content-grade    (global install)
+    npm install content-grade@latest (local install)
+```
+
+---
+
+### `activate`
+
+```bash
+content-grade activate
+content-grade activate <your-license-key>
+```
+
+Unlocks Pro features by storing your license key locally. Can be run interactively (prompts for the key) or non-interactively by passing the key as an argument — useful for automated setups:
+
+```bash
+# Interactive
+content-grade activate
+
+# Non-interactive (CI/CD or scripted setup)
+CONTENT_GRADE_KEY=your-key-here content-grade analyze ./post.md
+```
+
+The key is validated against the server and saved to `~/.config/content-grade/config.json`. If the server is unreachable (corporate proxy, offline), the key is stored locally anyway with a warning.
+
+**Pro unlocks:**
+- 100 analyses/day (vs 50 free)
+- `content-grade batch <dir>` — analyze entire directories at once
+- A/B headline comparison (web dashboard)
+- Landing page URL audit, ad copy scoring, email optimizer
+
+Get a license: [content-grade.github.io/Content-Grade/](https://content-grade.github.io/Content-Grade/)
+
+
 ## Configuration
 
 All configuration is through environment variables — no config file needed.
@@ -319,7 +515,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 +546,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
@@ -711,7 +912,7 @@ echo "$DATE,$HEADLINE,$SCORE" >> headline-scores.csv
 
 | | Free | Pro |
 |-|------|-----|
-| Price | Free forever | $19/month |
+| Price | Free forever | $9/month |
 | Analyses/day (CLI) | Unlimited | Unlimited |
 | Analyses/day (web dashboard, per tool) | 3 | 100 |
 | HeadlineGrader (single grade) | ✓ | ✓ |
@@ -744,25 +945,25 @@ 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
 
 **[EARLY_ADOPTERS.md](EARLY_ADOPTERS.md)** — The first 50 users who install and share feedback get:
 
-- **Pro tier free for 12 months** ($19/mo value)
+- **Pro tier free for 12 months** ($9/mo value)
 - Direct feedback channel with the maintainer
 - Name in CONTRIBUTORS.md (permanent)
 - 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 +975,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