@holdyourvoice/hyv 2.4.0 → 2.4.2

package/README.md

@@ -1,131 +1,99 @@
-# Hold Your Voice
+# hold your voice
 
-Portable writing-voice toolkit. Works in any AI coding tool or terminal.
-Zero dependencies outside Python 3.10+.
+make your ai agent sound exactly like you.
 
-- build a voice profile from a writer's own samples
-- scan drafts for AI-writing patterns (220+ rules across 31 regex patterns)
-- rewrite only the flagged lines — no flattening
-- **profile evolves with every session** — patterns you accept get stronger,
-  patterns you ignore fade away
-- auto-sync profiles to Cloudflare R2 for backup (near-zero cost)
+`hyv` is a CLI-first voice gate layer for AI workflows. it scans text for AI writing patterns, builds a voice profile from your own writing, and rewrites drafts to match your personal style.
 
-## Install
+## install
 
 ```bash
-npm install -g @holdyourvoice/hyv
+npm i -g @holdyourvoice/hyv
 ```
 
-Or clone and run directly:
+this automatically configures MCP for Claude Desktop if it's installed.
 
-```bash
-git clone https://github.com/holdyourvoice/hold-your-voice.git
-cd hold-your-voice
-python3 scripts/hold_voice.py --help
-```
-
-## Quick start
-
-### 1. Build a voice profile
+## quick start
 
 ```bash
-hyv profile \
-  --name "my voice" \
-  --out .hold-your-voice/voice-profile.json \
-  path/to/writing-samples/
-```
-
-### 2. Scan a draft for AI patterns
-
-```bash
-hyv scan --meta .hold-your-voice/voice-profile.meta.json draft.md
-```
+# sign in (opens browser)
+hyv init
 
-### 3. Rewrite flagged lines only
+# create your voice profile
+hyv new my-voice
 
-```bash
-hyv rewrite-prompt \
-  --profile .hold-your-voice/voice-profile.json \
-  --meta .hold-your-voice/voice-profile.meta.json \
-  draft.md
-```
-
-### 4. After user accepts the revision, evolve the profile
+# scan a draft for AI patterns
+hyv scan draft.md
 
-```bash
-hyv profile-evolve \
-  --original draft.md \
-  --accepted accepted.md \
-  --profile .hold-your-voice/voice-profile.json
+# generate a rewrite prompt
+hyv rewrite draft.md
 ```
 
-This automatically diffs original vs accepted, extracts which patterns the user
-kept and which they overrode, updates temporal confidence weights, merges new
-stats, and **auto-syncs to Cloudflare R2** if configured.
-
-## Cloud sync (optional)
+## MCP server
 
-Set once:
+`hyv` includes a built-in MCP server for Claude Desktop, Claude Code, and other MCP hosts.
 
 ```bash
-export HYV_R2_ACCESS_KEY_ID="your-access-key"
-export HYV_R2_SECRET_ACCESS_KEY="your-secret-key"
-export HYV_R2_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
-export HYV_R2_BUCKET="hyv-voice-profiles"
-pip install boto3
+# start the MCP server (used by Claude Desktop automatically)
+hyv mcp
 ```
 
-`profile-evolve` auto-syncs after every session (> 23h since last sync).
-R2 has zero egress fees. With ~20KB profiles, annual cost is $0.
+### tools
 
-## What the learning does
+| 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 |
 
-After a few days of use:
+### prompts
 
-- `ai_vocab_density` — confidence 0.76 → reliably catches AI-speak
-- `inflated_verbs` — confidence 0.32 → user removes most of these
-- `em_dash` — confidence 0.08 → user uses em dashes, pattern auto-suppressed
+| prompt | description |
+|--------|-------------|
+| `hyv-status` | show account context, profiles, and usage |
 
-Patterns track `first_seen`, `last_confirmed`, per-date contradictions,
-`status` (active/declining/stale), and `source_samples` for full provenance.
-Untouched patterns decay over 14 days. Contradicted patterns drop to declining
-after 3 overrides, stale after 5.
+## commands
 
-## Commands
-
-| Command | What it does |
+| command | description |
 |---------|-------------|
-| `hyv profile` | Build voice profile from samples |
-| `hyv scan` | Flag AI-writing patterns in a draft |
-| `hyv rewrite-prompt` | Generate line-level rewrite prompt |
-| `hyv profile-evolve` | **Auto-evolve** — extract signals + update meta + merge stats |
-| `hyv profile-update` | Merge new samples into existing profile (rolling averages) |
-| `hyv profile-status` | Pretty-print learning state with confidence bars |
-| `hyv reinforce` | Diff original vs accepted, emit signal report |
-| `hyv profile-export` | Bundle profile into .hyv file |
-| `hyv profile-import` | Import .hyv bundle |
-| `hyv-sync` | Manually sync to R2 (runs automatically via evolve) |
+| `hyv init` | authenticate with hold your voice |
+| `hyv status` | show CLI and auth status |
+| `hyv new <name>` | create a voice profile |
+| `hyv profiles` | list voice profiles |
+| `hyv rename <name>` | rename a voice profile |
+| `hyv scan <file>` | scan text for AI patterns |
+| `hyv rewrite <file>` | generate rewrite prompt |
+| `hyv sync` | sync profiles from server |
+| `hyv doctor` | diagnose and fix issues |
+| `hyv mcp` | start MCP server |
+| `hyv export [format]` | export profile for LLMs |
+| `hyv plan` | manage subscription |
+
+## voice profiles
+
+profiles are stored in `~/.hyv/profiles/` as markdown files. create one with:
+
+```bash
+hyv new my-voice
+```
 
-## Why `.hold-your-voice/`
+the onboarding walks you through questions about your writing style, audience, and tone. the profile is saved locally and synced to the server.
 
-Profiles live in your project. They're not hidden in `~/.codex/` or `~/.commandcode/` —
-they're in `.hold-your-voice/` at the root of whatever project you're writing for.
-Portable. Version-control-able. No global state.
+## content formats
 
-## Changelog
+`hyv scan` and `hyv rewrite` detect 220+ AI writing patterns across categories:
 
-### 0.2.0 — auto-improving profiles
+- **ai-slop** — overused AI words (delve, leverage, tapestry, pivotal, foster)
+- **formulaic** — connector words (firstly, moreover, in conclusion)
+- **voice-drift** — hedging language (arguably, perhaps, some might say)
+- **structure** — AI structural tells (antithesis, signpost claims, lesson setups)
 
-- `profile-evolve` replaces manual reinforce + update — one command per session
-- Temporal pattern confidence tracking (active/declining/stale lifecycle)
-- `scan --meta` and `rewrite-prompt --meta` filter out learned-not-applicable patterns
-- Voice.md as standard readable output (`profile-status --write-voice`)
-- Auto-sync to Cloudflare R2 with daily rate-limiting and 1MB safety cap
-- Universal `hyv` / `hyv-sync` CLI — works in any tool, not just Codex
+## environment variables
 
-### 0.1.0 — initial
+| variable | description |
+|----------|-------------|
+| `HYV_API_URL` | API base URL (default: `https://holdyourvoice.com`) |
 
-- `profile`, `scan`, `rewrite-prompt` commands
-- 220+ AI-writing pattern detection (31 regex + 9 structural signals)
-- `reinforce`, `profile-update`, `profile-export/import`
+## license
 
+UNLICENSED — [holdyourvoice.com](https://holdyourvoice.com)

package/agents/chatgpt.md

@@ -0,0 +1,18 @@
+# Hold Your Voice — Writing Rules
+
+The user has a voice profile. All writing must match their personal style.
+
+## Rules
+1. Never use AI-slop words: delve, leverage, tapestry, foster, harness, pivotal, innovative, cutting-edge, state-of-the-art, robust, holistic, multifaceted, nuanced
+2. Never use formulaic connectors: firstly, secondly, moreover, furthermore, in conclusion
+3. Never use hedging: arguably, perhaps, some might say, it's worth noting
+4. Never use signpost claims: this is why, this is how, here's where
+5. Match the user's sentence rhythm and vocabulary
+6. Preserve roughness that carries voice — don't over-polish
+7. Open from concrete observations, not generic setups
+
+## When rewriting
+- Fix only flagged lines, preserve clean lines
+- Remove AI patterns line by line
+- Match the user's voice profile exactly
+- Never add sections, hooks, CTAs, or commentary

package/agents/claude-code.md

@@ -0,0 +1,39 @@
+# Hold Your Voice
+
+The user has a voice profile that defines their writing style. Use HYV tools for ALL writing tasks — not just when they say "voice" or "hyv".
+
+## When to use HYV
+
+ALWAYS run `hyv_scan` or use the `hyv_scan` MCP tool before delivering any written content:
+- Writing emails, replies, or messages
+- Drafting blog posts, articles, or documentation
+- Creating social media posts (Twitter, LinkedIn, etc.)
+- Editing or improving any text
+- Responding to questions with longer answers
+- Any task where the output is prose/text the user will publish or send
+
+ALWAYS run `hyv_rewrite` or use the `hyv_rewrite` MCP tool when:
+- The user asks to "write", "draft", "compose", "edit", "improve", or "fix" text
+- The user says "make this better", "clean this up", "fix the tone"
+- The user asks for any content creation
+- The scan finds issues and you need to fix them
+
+## How to use
+
+### MCP tools (preferred — if MCP is connected):
+1. `hyv_scan` with the text → get issues
+2. `hyv_rewrite` with the text → get auto-fixed version + LLM prompt for remaining issues
+3. `hyv_validate` after rewriting → verify the output matches the voice
+
+### CLI commands (fallback):
+```bash
+echo "text to check" | hyv scan -
+hyv rewrite file.md
+hyv profiles
+```
+
+## Rules
+- Never skip the scan step for user-facing content
+- 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

package/agents/codex.md

@@ -0,0 +1,22 @@
+# Hold Your Voice
+
+The user has a voice profile for their writing style. Use HYV for ALL writing tasks.
+
+## Auto-trigger rules
+
+Run these MCP tools (or CLI commands) for any writing task:
+- `hyv_scan` on any text before delivering it
+- `hyv_rewrite` to fix issues found by scan
+- `hyv_validate` to verify the output
+
+## CLI fallback
+```bash
+echo "text" | hyv scan -
+hyv rewrite file.md
+hyv profiles
+```
+
+## Rules
+- Always scan before delivering prose content
+- Always rewrite if scan finds issues
+- Preserve meaning, match voice profile

package/agents/cursor.md

@@ -0,0 +1,19 @@
+# Hold Your Voice
+
+The user has a voice profile. Use HYV MCP tools for all writing tasks.
+
+## When to use
+- Any email, post, doc, or content creation
+- Before delivering any prose to the user
+- When editing or improving text
+
+## Tools
+- `hyv_scan` — check text for AI patterns
+- `hyv_rewrite` — fix issues and match voice
+- `hyv_validate` — verify output matches voice
+- `hyv_profiles` — list available profiles
+
+## Rules
+- Always scan before delivering content
+- Preserve meaning when rewriting
+- Match the user's voice profile exactly

package/agents/generic.md

@@ -0,0 +1,30 @@
+# Hold Your Voice — Agent Instructions
+
+You have access to the Hold Your Voice MCP tools. The user has a voice profile that defines how they write. Your job is to make ALL written content match their voice.
+
+## Auto-trigger rules
+
+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_rewrite` to fix them
+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_rewrite`
+4. Deliver the cleaned version
+
+## Available tools
+- `hyv_scan` — scan text for AI patterns and voice drift
+- `hyv_rewrite` — auto-fix patterns and generate LLM prompt for remaining issues
+- `hyv_validate` — score text against voice profile
+- `hyv_profiles` — list available 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>`

package/agents/windsurf.md

@@ -0,0 +1,12 @@
+# Hold Your Voice
+
+Use HYV MCP tools for all writing tasks. The user has a voice profile.
+
+## Auto-trigger
+- `hyv_scan` before delivering any text
+- `hyv_rewrite` to fix found issues
+- `hyv_validate` after rewriting
+
+## Rules
+- Always scan user-facing content
+- Preserve meaning, match voice profile

package/assets/ai-eliminator-skill.md

@@ -0,0 +1,63 @@
+---
+name: ai-writing-eliminator
+description: Use when the user wants to remove AI writing patterns, humanize a draft, make prose less generic, scan for AI cadence, or rewrite only the lines that sound synthetic.
+---
+
+# AI Writing Eliminator (v2)
+
+This skill removes machine-shaped writing without destroying the draft. The
+algorithm now detects 220+ named AI writing patterns across 31 composite regex
+rules, plus 9 structural/rhythmic signals (burstiness, paragraph uniformity,
+contraction density, formal hedging, intensifier overuse, fragment ratio,
+staccato detection, over-structured lists, uniform sentence rhythm).
+
+## Non-Negotiables
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+- Fix flagged lines only unless the user asks for a full rewrite.
+- Preserve the original argument and local meaning.
+- Do not add praise, summaries, preambles, CTAs, or extra sections.
+- Do not replace specific roughness with smooth generic prose.
+- After editing, rescan the result.
+
+## Scan
+
+Use the helper script when a draft is in a file:
+
+```bash
+hyv scan <draft path>
+```
+
+For pasted text, apply the same rules manually from
+`assets/ai-eliminator-rules.md`.
+
+## Repair Prompt
+
+When a model rewrite is needed, generate a line-level prompt:
+
+```bash
+hyv rewrite-prompt \
+  --profile .hold-your-voice/voice-profile.json \
+  <draft path>
+```
+
+If there is no profile, still repair the AI patterns, but do not claim the
+result is voice-matched.
+
+## Bad Fixes
+
+Reject fixes that:
+
+- turn the draft into a tidy founder post
+- make every paragraph land as a lesson
+- replace a concrete scene with an abstract principle
+- use dramatic line breaks to fake rhythm
+- make the writer sound more professional but less specific
+

package/assets/chatgpt-instructions.txt

@@ -0,0 +1,8 @@
+when i ask you to "write in my voice" or "rewrite this in my voice":
+
+- read `~/.hyv/voice.md` for my voice profile
+- run `hyv rewrite --text "<text>"` to get the structured prompt
+- execute the prompt and rewrite the text
+- match my rhythm, vocabulary, and patterns exactly
+- never use words i avoid
+- present the rewritten version

package/assets/claude-code-skill.md

@@ -0,0 +1,24 @@
+## Hold Your Voice — automated voice rewriting
+
+when the user asks to "write in my voice", "rewrite this in my voice", or "make this sound like me":
+
+1. read their voice profile at `~/.hyv/voice.md`
+2. run `hyv rewrite --text "<their text>"` to generate a structured rewrite prompt
+3. execute the prompt — rewrite the text yourself using your own llm
+4. present the rewritten text
+5. when the user accepts it, run `hyv reinforce original.md edited.md` to teach the system
+
+### available commands
+
+- `hyv scan <file>` — check a draft for voice drift and ai patterns
+- `hyv rewrite <file>` — generate a rewrite prompt for your llm
+- `hyv validate <file>` — verify a rewrite matches the voice profile
+- `hyv reinforce <original> <edited>` — teach the system what was accepted
+- `hyv sync` — refresh cached profiles and rules
+- `hyv status` — show auth and plan info
+
+### important
+
+- hyv never calls an llm. it generates prompts you execute yourself.
+- voice profiles live at `~/.hyv/voice.md`
+- always call `hyv validate` after rewriting to verify the result

package/assets/cursor-rules.md

@@ -0,0 +1,12 @@
+# Hold Your Voice — Cursor Rules
+
+when writing or rewriting content, match the voice profile below. do not use AI-slop words (delve, leverage, tapestry, in today's fast-paced, not just X but Y, etc.). match rhythm, vocabulary, and sentence patterns from the profile.
+
+your voice profile is at `~/.hyv/voice.md`. load it and use it as your writing guide.
+
+when the user says "rewrite in my voice", "make this sound like me", or similar:
+
+1. run: `hyv rewrite --text "<text>"`
+2. the cli generates a structured rewrite prompt
+3. execute the prompt yourself — rewrite the text matching the voice profile
+4. present the result

package/assets/hold-your-voice-skill.md

@@ -0,0 +1,174 @@
+---
+name: hyv-hold-your-voice
+description: "Use when the user wants Hold Your Voice-style writing help across any project: build a voice profile from samples, match a writer's voice, remove AI-writing drift, rewrite drafts without flattening voice, or preserve project-specific writing style."
+---
+
+# Hold Your Voice
+
+This is the orchestration skill. Use the narrower `voice-matcher` and
+`ai-writing-eliminator` skills when a task is only one half of the workflow.
+
+## Core Doctrine
+
+- Hold Your Voice is not a generic AI humanizer. It is a voice-preservation
+  layer around the writing.
+- The benchmark is the writer's own samples, not a universal "good writing"
+  style guide.
+- Trust samples over stated preferences when they disagree.
+- Rewrite only the lines that fail the voice or AI-pattern check.
+- Preserve surrounding text unless the user explicitly asks for a full rewrite.
+- Rough private-note texture beats polished founder cadence.
+
+## Workflow
+
+1. Identify the target writer and output format.
+2. Find or ask for source samples. Prefer real writing from the current project:
+   posts, emails, essays, docs, landing copy, changelog notes, founder notes.
+3. Build a profile when no current profile exists:
+
+   ```bash
+   hyv profile \
+     --name "project voice" \
+     --out .hold-your-voice/voice-profile.json \
+     <sample paths>
+   ```
+
+4. Scan the draft:
+
+   ```bash
+   hyv scan \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+   Passing `--meta` skips patterns the system has learned are not applicable.
+
+5. Rewrite by line, not by vibe:
+
+   ```bash
+   hyv rewrite-prompt \
+     --profile .hold-your-voice/voice-profile.json \
+     --meta .hold-your-voice/voice-profile.meta.json \
+     <draft path>
+   ```
+
+6. Verify by rescanning the revised draft.
+
+## Output Standard
+
+When returning prose to the user, lead with the finished writing. Keep process
+notes short. If you changed only flagged lines, say that plainly.
+
+For project work, store generated profiles under:
+
+```text
+.hold-your-voice/voice-profile.json
+```
+
+Do not store private samples inside the plugin folder. Keep project-specific
+profiles inside the project that owns the writing.
+
+## Auto-Improvement (default)
+
+The profile **evolves automatically** after every accepted writing session. No
+manual reinforce or update commands needed.
+
+### How it works
+
+After the user accepts a revision, run **one command**:
+
+```bash
+hyv profile-evolve \
+  --original <original draft file> \
+  --accepted <accepted/output draft file> \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--new-samples <paths>` to merge new writing samples in the same step.
+Optional: `--meta <path>` if you need a custom meta file location (defaults to
+`voice-profile.meta.json` alongside the profile).
+
+This does three things simultaneously:
+
+1. **Signal extraction** — diffs original vs accepted to find which AI patterns
+   the user agreed with (`patterns_accepted`) vs overrode (`patterns_overridden`).
+2. **Temporal meta update** — each pattern now tracks `first_seen`,
+   `last_confirmed`, `contradictions`, `confidence` (0.0–1.0), and status
+   (`active` / `declining` / `stale`). Accepted signals boost confidence.
+   Overrides penalize it. Untouched patterns slowly decay.
+3. **Profile stat merge** — sentence length, paragraph shape, and opening moves
+   use weighted rolling averages so the voice benchmark improves with every
+   session.
+
+### Pattern lifecycle
+
+- **Active** — confidence ≥ 0.30, last confirmed within 14 days. These
+  patterns fire during scans.
+- **Declining** — 3+ contradictions and confidence < 0.30. Still tracked
+  but no longer flagged in scan output.
+- **Stale** — 5+ contradictions and confidence < 0.15, or untouched for
+  > 14 days. Archived; does not fire.
+
+This means after a few days of usage:
+
+- Patterns the user consistently accepts (e.g., "inflated_verbs") become
+  high-confidence and reliably flag real AI drift.
+- Patterns the user consistently ignores (e.g., "the user's writing style
+  uses landscape-era phrasing intentionally") quietly fade out.
+- The profile's sentence/paragraph stats converge on the actual voice.
+
+### Check learning state
+
+```bash
+hyv profile-status \
+  --profile .hold-your-voice/voice-profile.json
+```
+
+Optional: `--write-voice voice.md` produces the human-readable voice profile
+with confidence bars per pattern.
+
+### Auto-sync to cloud (daily)
+
+`profile-evolve` automatically tries to sync to Cloudflare R2 after each
+evolution. Sync only happens if:
+
+- The env vars `HYV_R2_ACCESS_KEY_ID`, `HYV_R2_SECRET_ACCESS_KEY`,
+  `HYV_R2_ENDPOINT`, `HYV_R2_BUCKET` are set.
+- The last sync was more than 23 hours ago (no wasteful pushes).
+- The payload is under 1MB (safety cap).
+
+To set up one-time:
+
+```bash
+export HYV_R2_ACCESS_KEY_ID="your-access-key"
+export HYV_R2_SECRET_ACCESS_KEY="your-secret-key"
+export HYV_R2_ENDPOINT="https://<account-id>.r2.cloudflarestorage.com"
+export HYV_R2_BUCKET="hyv-voice-profiles"
+pip install boto3  # only dependency
+```
+
+R2 has **zero egress fees**. With ~5-20KB profiles synced once daily, annual
+cost rounds to zero. No Cloudflare Workers, no compute — just S3 PUT.
+
+Manual sync (force override):
+
+```bash
+hyv-sync \
+  --profile .hold-your-voice/voice-profile.json \
+  --force
+```
+
+### Export and import
+
+```bash
+hyv profile-export \
+  --profile .hold-your-voice/voice-profile.json \
+  --out ~/my-voice.hyv
+
+hyv profile-import \
+  --profile .hold-your-voice/voice-profile.json \
+  --source ~/my-voice.hyv
+```
+
+The learning is entirely local — no API calls, no third-party services.
+