@holdyourvoice/hyv 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — @holdyourvoice/hyv
+
+All notable CLI changes. Also mirrored to [holdyourvoice.com/changelog](https://holdyourvoice.com/changelog) for user-facing releases.
+
+## [2.8.0] — 2026-06-12
+
+### Added
+- Full Phase 1–4 product plan: free local engine, hybrid analysis, MCP `hyv_analyze` / `hyv_clean`, learning loop UX, packaging hardening
+- `npm run test:smoke` — 28+ CLI regression checks
+- `npm run validate:publish` — prepublish tarball verification
+- Golden prompt tests, postinstall idempotency tests, edge-case suite
+
+### Fixed
+- `hyv check ""` no longer reports false clean — rejects empty input
+- Bundled CLI resolves correct package + rules version from `dist/`
+- Smoke tests avoid SIGPIPE false failures when piping CLI output
+
+## [2.7.1] — 2026-06-12
+
+### Added
+- `hyv upgrade` — check and install latest global CLI
+- `hyv mcp --setup` and `hyv mcp --test` — agent setup + health check
+- MCP tools: `hyv_analyze` (hybrid server+local), `hyv_clean` (scan→fix→validate pipeline)
+- `hyv reinforce --last` — learn from last fix/rewrite session
+- Free-first local engine: scan, fix, check, score, diff work offline without subscription
+- `hyv welcome` / `hyv free` — onboarding with live demo
+- Profile-aware local pipeline: never-list, learned patterns, anchors, cadence
+- Opt-in telemetry: `HYV_TELEMETRY=1`
+
+### Improved
+- Postinstall upgrades agent instructions via `~/.hyv/agents-version.json`
+- `hyv status` shows engine/rules version, drift, evolution summary
+- `hyv doctor` reports full engine label + `--fix-agents`
+- Published package excludes Python dev scripts and `src/`
+
+### Fixed
+- Bundled CLI reads correct `package.json` version from `dist/`

package/README.md

@@ -30,27 +30,49 @@ hyv rewrite draft.md
 
 ## MCP server
 
-`hyv` includes a built-in MCP server for Claude Desktop, Claude Code, and other MCP hosts.
+`hyv` includes a built-in MCP server for Claude Desktop, Claude Code, Cursor, Windsurf, and Codex.
 
 ```bash
-# start the MCP server (used by Claude Desktop automatically)
+# setup instructions for all supported agents
+hyv mcp --setup
+
+# health check (tools, demo pipeline, profile)
+hyv mcp --test
+
+# start the MCP server (stdio — used by Claude Desktop automatically)
 hyv mcp
 ```
 
+Postinstall copies agent rules to `~/.cursor/rules/hyv.md`, `~/.claude/commands/hyv.md`, etc. Re-run anytime:
+
+```bash
+hyv doctor --fix-agents
+```
+
 ### tools
 
 | tool | description |
 |------|-------------|
-| `hyv_rewrite` | rewrite text to match your voice profile |
-| `hyv_scan` | scan text for AI writing patterns |
-| `hyv_profiles` | list your voice profiles |
-| `hyv_validate` | validate text against a voice profile |
+| `hyv_welcome` / `hyv_demo` | onboarding + live free scan demo |
+| `hyv_scan` | fast local scan (free, offline) |
+| `hyv_analyze` | hybrid local + server analysis (paid when online) |
+| `hyv_clean` | scan → fix → validate → rewrite prompt |
+| `hyv_fix` / `hyv_check` / `hyv_score` / `hyv_diff` | local utilities |
+| `hyv_rewrite` | profile-aware rewrite prompt |
+| `hyv_validate` | verify text against voice profile |
+| `hyv_profiles` | list cached or account profiles |
 
 ### prompts
 
 | prompt | description |
 |--------|-------------|
-| `hyv-status` | show account context, profiles, and usage |
+| `hyv-status` | account mode, profiles, recommended tool flow |
+
+### agent workflow
+
+1. `hyv_scan` or `hyv_analyze` on draft text
+2. `hyv_clean` or `hyv_fix` → `hyv_rewrite` → `hyv_validate`
+3. After user accepts edits: `hyv reinforce --last` (CLI learning loop)
 
 ## commands
 
@@ -68,6 +90,9 @@ hyv mcp
 | `hyv mcp` | start MCP server |
 | `hyv export [format]` | export profile for LLMs |
 | `hyv plan` | manage subscription |
+| `hyv upgrade` | install latest global CLI |
+| `hyv welcome` | free demo + capability tour |
+| `hyv reinforce --last` | learn from last fix session |
 
 ## voice profiles
 
@@ -93,6 +118,9 @@ the onboarding walks you through questions about your writing style, audience, a
 | variable | description |
 |----------|-------------|
 | `HYV_API_URL` | API base URL (default: `https://holdyourvoice.com`) |
+| `HYV_LOCAL_ONLY` | Force offline mode (`1` or `true`) |
+| `HYV_TELEMETRY` | Log MCP tool usage to `~/.hyv/telemetry/` (`1` to enable) |
+| `HYV_POSTINSTALL_QUIET` | Suppress postinstall output (`1`) |
 
 ```bash
 # Staging

package/agents/chatgpt.md

@@ -18,11 +18,10 @@ The user has a voice profile. All writing must match their personal style.
 - Never add sections, hooks, CTAs, or commentary
 
 ## Available tools
-- `hyv_scan` — check text for AI patterns
-- `hyv_fix` — auto-fix simple patterns (word swaps) without LLM
-- `hyv_rewrite` — fix issues and match voice
-- `hyv_check` — quick inline check, returns score + issues
-- `hyv_score` — just a 0-100 score
-- `hyv_diff` — show what auto-fixes would change
-- `hyv_validate` — verify output matches voice
+- `hyv_welcome` / `hyv_demo` — onboarding
+- `hyv_scan` / `hyv_analyze` — check for AI patterns (+ hybrid when paid)
+- `hyv_clean` — full scan → fix → validate pipeline
+- `hyv_fix` / `hyv_rewrite` / `hyv_validate`
+- `hyv_check` / `hyv_score` / `hyv_diff`
 - `hyv_profiles` — list available profiles
+- CLI: `hyv reinforce --last` after user accepts edits

package/agents/claude-code.md

@@ -21,13 +21,12 @@ ALWAYS run `hyv_rewrite` or use the `hyv_rewrite` MCP tool when:
 ## How to use
 
 ### MCP tools (preferred — if MCP is connected):
-1. `hyv_scan` with the text → get issues
-2. `hyv_fix` with the text → auto-fix simple word swaps (delve→dig, leverage→use)
-3. `hyv_rewrite` with the text → get full rewrite with LLM prompt for remaining issues
-4. `hyv_validate` after rewriting → verify the output matches the voice
-5. `hyv_check` for quick inline spot-checks → get score + issues
-6. `hyv_score` when you just need a 0-100 number
-7. `hyv_diff` to show what auto-fixes would change before applying
+1. `hyv_welcome` / `hyv_demo` for new users
+2. `hyv_scan` (fast local) or `hyv_analyze` (hybrid when paid) → get issues
+3. `hyv_clean` → scan + fix + validate + rewrite prompt in one call
+4. Or stepwise: `hyv_fix` → `hyv_rewrite` → `hyv_validate`
+5. `hyv_check` / `hyv_score` / `hyv_diff` for quick checks
+6. After user accepts edits: suggest `hyv reinforce --last` (CLI learning loop)
 
 ### CLI commands (fallback):
 ```bash
@@ -48,3 +47,4 @@ hyv history                  # track scores over time
 - Preserve the original meaning exactly when rewriting
 - Match the voice profile's rhythm, vocabulary, and patterns
 - If no profile is set up yet, run `hyv profiles` to check
+- Setup: `hyv mcp --setup` | health: `hyv mcp --test`

package/agents/codex.md

@@ -5,25 +5,26 @@ The user has a voice profile for their writing style. Use HYV for ALL writing ta
 ## Auto-trigger rules
 
 Run these MCP tools (or CLI commands) for any writing task:
-- `hyv_scan` on any text before delivering it
-- `hyv_fix` to auto-fix simple patterns (word swaps) without LLM
-- `hyv_rewrite` to fix remaining issues with LLM
+- `hyv_scan` or `hyv_analyze` on any text before delivering it
+- `hyv_clean` for the full pipeline, or `hyv_fix` → `hyv_rewrite`
 - `hyv_validate` to verify the output
+- Suggest `hyv reinforce --last` after substantial accepted edits
 
 ## Quick tools
-- `hyv_check` for inline spot-checks
-- `hyv_score` when you just need a 0-100 number
-- `hyv_diff` to show what would change before applying
+- `hyv_welcome` / `hyv_demo` for new users
+- `hyv_check` / `hyv_score` / `hyv_diff`
 
 ## CLI fallback
 ```bash
 echo "text" | hyv scan -
 hyv fix file.md
 hyv rewrite file.md
+hyv reinforce --last
 hyv profiles
+hyv mcp --setup
 ```
 
 ## Rules
 - Always scan before delivering prose content
 - Always fix/rewrite if scan finds issues
-- Preserve meaning, match voice profile
+- Preserve meaning, match voice profile

package/agents/cursor.md

@@ -6,19 +6,28 @@ The user has a voice profile. Use HYV MCP tools for all writing tasks.
 - Any email, post, doc, or content creation
 - Before delivering any prose to the user
 - When editing or improving text
+- New users: call `hyv_welcome` or `hyv_demo` first
+
+## Tool flow (preferred)
+1. `hyv_scan` — fast local check (free, offline)
+2. `hyv_analyze` — full hybrid engine when user is on a paid plan
+3. `hyv_fix` — deterministic word swaps
+4. `hyv_clean` — scan → fix → validate → rewrite prompt in one call
+5. `hyv_rewrite` — profile-aware rewrite prompt for remaining issues
+6. `hyv_validate` — verify output matches voice
+7. After user accepts a big edit: suggest `hyv reinforce --last` (CLI)
 
 ## Tools
-- `hyv_scan` — check text for AI patterns
-- `hyv_fix` — auto-fix simple patterns (word swaps) without LLM
-- `hyv_rewrite` — fix issues and match voice
-- `hyv_check` — quick inline check, returns score + issues
-- `hyv_score` — just a 0-100 score
-- `hyv_diff` — show what auto-fixes would change
-- `hyv_validate` — verify output matches voice
-- `hyv_profiles` — list available profiles
+- `hyv_welcome` / `hyv_list_free_tools` / `hyv_demo` — onboarding (free)
+- `hyv_scan` — local AI pattern + profile scan
+- `hyv_analyze` — hybrid local + server analysis (paid when online)
+- `hyv_clean` — full clean pipeline for agents
+- `hyv_fix` / `hyv_check` / `hyv_score` / `hyv_diff` — local utilities
+- `hyv_rewrite` / `hyv_validate` — voice matching
+- `hyv_profiles` — list profiles
 
 ## Rules
 - Always scan before delivering content
-- Use `hyv_fix` for quick word swaps before `hyv_rewrite`
+- Use `hyv_fix` before `hyv_rewrite` when possible
 - Preserve meaning when rewriting
-- Match the user's voice profile exactly
+- Match the user's voice profile exactly

package/agents/generic.md

@@ -7,33 +7,32 @@ You have access to the Hold Your Voice MCP tools. The user has a voice profile t
 You MUST use these tools automatically — do NOT wait for the user to mention "voice" or "hyv":
 
 **Before delivering any written content (emails, posts, docs, messages):**
-1. Run `hyv_scan` on the text
-2. If issues found, run `hyv_fix` for quick word swaps, then `hyv_rewrite` for structural issues
+1. Run `hyv_scan` (fast) or `hyv_analyze` (full hybrid when paid)
+2. Run `hyv_clean` for the full scan → fix → validate loop, or `hyv_fix` then `hyv_rewrite`
 3. Run `hyv_validate` to verify the result
 
 **When the user asks you to write, draft, edit, or improve anything:**
 1. Write your draft
-2. Run `hyv_scan` on it
-3. Fix issues with `hyv_fix` (auto-swaps) and `hyv_rewrite` (LLM rewrites)
-4. Deliver the cleaned version
+2. Run `hyv_scan` or `hyv_clean` on it
+3. Deliver the cleaned version
 
-**For quick checks:**
-- Use `hyv_check` for inline spot-checks
-- Use `hyv_score` when you just need a quality number
-- Use `hyv_diff` to show what would change before applying fixes
+**After the user accepts a substantial edit:**
+- Suggest they run `hyv reinforce --last` so their profile learns from the change
+
+**For new users:**
+- Call `hyv_welcome` or `hyv_demo` to show free capabilities
 
 ## Available tools
-- `hyv_scan` — scan text for AI patterns and voice drift
-- `hyv_fix` — auto-fix simple patterns (word swaps) without LLM
-- `hyv_rewrite` — auto-fix patterns and generate LLM prompt for remaining issues
-- `hyv_check` — quick inline check, returns score + issues
-- `hyv_score` — just a 0-100 score
-- `hyv_diff` — show what auto-fixes would change
-- `hyv_validate` — score text against voice profile
-- `hyv_profiles` — list available voice profiles
+- `hyv_welcome` / `hyv_list_free_tools` / `hyv_demo` — onboarding
+- `hyv_scan` — local scan (free, offline)
+- `hyv_analyze` — hybrid server + local (paid)
+- `hyv_clean` — composite clean pipeline
+- `hyv_fix` / `hyv_rewrite` / `hyv_validate`
+- `hyv_check` / `hyv_score` / `hyv_diff`
+- `hyv_profiles` — list voice profiles
 
 ## Rules
 - NEVER skip scanning for user-facing content
 - Preserve original meaning exactly when rewriting
 - Match the voice profile's rhythm, vocabulary, and tone
-- If no profile exists, tell the user to run `hyv init` then `hyv new <name>`
+- If no profile exists, tell the user to run `hyv init` then `hyv new <name>`

package/agents/windsurf.md

@@ -3,17 +3,17 @@
 Use HYV MCP tools for all writing tasks. The user has a voice profile.
 
 ## Auto-trigger
-- `hyv_scan` before delivering any text
-- `hyv_fix` to auto-fix simple patterns (word swaps) without LLM
-- `hyv_rewrite` to fix remaining issues with LLM
+- `hyv_scan` or `hyv_analyze` before delivering any text
+- `hyv_clean` for scan → fix → validate in one call
+- `hyv_fix` then `hyv_rewrite` for stepwise fixes
 - `hyv_validate` after rewriting
+- `hyv reinforce --last` after user accepts big edits (CLI)
 
 ## Quick tools
-- `hyv_check` for inline spot-checks
-- `hyv_score` when you just need a 0-100 number
-- `hyv_diff` to show what would change before applying
+- `hyv_welcome` / `hyv_demo` for onboarding
+- `hyv_check` / `hyv_score` / `hyv_diff`
 
 ## Rules
 - Always scan user-facing content
-- Use `hyv_fix` for quick word swaps before `hyv_rewrite`
-- Preserve meaning, match voice profile
+- Use `hyv_fix` before `hyv_rewrite` when possible
+- Preserve meaning, match voice profile

package/assets/detection-rules.json

@@ -0,0 +1,18 @@
+{
+  "version": "1.0.0",
+  "engine": "node",
+  "source": "cli/src/lib/signals.ts",
+  "updated": "2026-06-12",
+  "categories": {
+    "ai-slop": { "description": "Dead AI language and overused words", "severity_default": "red" },
+    "voice-drift": { "description": "Hedging, generic openers, voice drift", "severity_default": "yellow" },
+    "structure": { "description": "Formulaic structure and antithesis tells", "severity_default": "yellow" },
+    "cadence": { "description": "Sentence rhythm violations", "severity_default": "yellow" },
+    "learned": { "description": "User-specific learned patterns", "severity_default": "yellow" },
+    "engagement-bait": { "description": "Engagement bait patterns", "severity_default": "red" },
+    "ai-cringe": { "description": "AI cringe phrases", "severity_default": "yellow" },
+    "insider-claim": { "description": "Insider knowledge claims", "severity_default": "yellow" }
+  },
+  "pattern_count": 220,
+  "notes": "Node signals.ts is canonical for npm package. Server syncs this manifest; supplemental rules may ship in ~/.hyv/cache/supplemental-rules.json"
+}