@holdyourvoice/hyv 2.9.26 → 2.9.28

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable CLI changes. Also mirrored to [holdyourvoice.com/changelog](https://holdyourvoice.com/changelog) for user-facing releases.
 
+## [2.9.28] — 2026-07-31
+
+### Fixed
+- **Scoped MCP activation** — installed rules, export prompts, and MCP metadata now use HYV automatically for publishable copy or an explicit voice request, while routine chat and engineering work bypass it
+- **Agent refresh** — `hyv doctor --fix-agents` refreshes the new scoped instructions through the package version marker
+
+## [2.9.27] — 2026-07-15
+
+### Fixed
+- **MCP scan hang** — `hyv_scan`, `hyv_fix`, `hyv_check`, `hyv_score`, `hyv_diff`, and `hyv_validate` no longer block on account profile sync; they use local `~/.hyv` cache immediately (matching `hyv scan` CLI) and hydrate profiles in the background
+
 ## [2.9.26] — 2026-07-09
 
 ### Improved
@@ -227,4 +238,4 @@ All notable CLI changes. Also mirrored to [holdyourvoice.com/changelog](https://
 - Published package excludes Python dev scripts and `src/`
 
 ### Fixed
-- Bundled CLI reads correct `package.json` version from `dist/`
+- Bundled CLI reads correct `package.json` version from `dist/`

package/README.md

@@ -29,7 +29,7 @@ Already have node 18+?
 npm i -g @holdyourvoice/hyv
 ```
 
-postinstall copies agent rules and configures MCP for claude desktop and cursor (plus claude code, windsurf, codex, command code skills when detected). set `HYV_AUTO_CONFIGURE_AGENTS=0` to skip.
+postinstall copies scoped agent rules and configures MCP for claude desktop and cursor (plus claude code, windsurf, codex, command code skills when detected). HYV runs automatically for publishable copy or an explicit voice request, not routine chat or engineering work. set `HYV_AUTO_CONFIGURE_AGENTS=0` to skip.
 
 ## free vs paid
 
@@ -96,7 +96,7 @@ hyv doctor --fix-agents
 | tool | description |
 |------|-------------|
 | `hyv_welcome` / `hyv_demo` | onboarding + live free scan demo |
-| `hyv_scan` | fast local scan (free, offline) |
+| `hyv_scan` | fast local scan (free, offline; uses `~/.hyv` cache, no network wait) |
 | `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 |
@@ -209,6 +209,10 @@ HYV_API_URL=https://staging.holdyourvoice.com hyv init
 - [blog](https://holdyourvoice.com/blog)
 - [community](https://holdyourvoice.com/community)
 
+## documentation ownership
+
+Changes under `cli/` update this README, the more-specific owner README when applicable, and the root repository README. Package-relative paths, bin names, published files, and postinstall behavior are contracts; validate them with `npm run validate:publish` before merging.
+
 ## license
 
-UNLICENSED — [holdyourvoice.com](https://holdyourvoice.com)
+UNLICENSED — [holdyourvoice.com](https://holdyourvoice.com)

package/agents/AGENTS.md

@@ -1,20 +1,22 @@
 # Hold Your Voice — Agent Instructions
 
-The user has a voice profile that defines their unique writing style. Your job is to make ALL written content match their voice automatically — without waiting for them to mention "voice" or "hyv".
+The user has a voice profile for publishable copy. Use it for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Also use it whenever the user explicitly asks for HYV, a voice profile, or writing in their voice.
 
 ## Auto-trigger — do these automatically
 
-**Before delivering any written content (emails, replies, posts, docs, messages, or prose):**
+**For eligible publishable copy or an explicit HYV/voice request:**
 1. Run `hyv_scan` for a fast local check (free, offline, works without a profile)
 2. Run `hyv_clean` for the full scan → fix → validate pipeline, or `hyv_fix` then `hyv_rewrite`
 3. Run `hyv_validate` to verify the output matches their voice
 
-**When the user asks you to write, draft, compose, edit, improve, or rewrite anything:**
+**When the user asks you to create or rewrite eligible copy:**
 1. Write your draft normally
 2. Run `hyv_scan` or `hyv_clean` on it
 3. Run `hyv_rewrite` to match their voice profile
 4. Deliver the voice-matched version
 
+**Do not auto-run HYV** for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, or internal engineering-status messages. If the request is ambiguous, bypass HYV unless the user explicitly asks for it.
+
 **After the user accepts a substantial edit:**
 - Suggest they run `hyv reinforce --last` so their profile learns from the change
 
@@ -25,7 +27,7 @@ The user has a voice profile that defines their unique writing style. Your job i
 | `hyv_welcome` | Onboarding guide (name → samples → test → signup) | New users, first time |
 | `hyv_mcp_setup` | Status, integrate apps, ChatGPT connector | Check/refresh setup |
 | `hyv_profiles` | List voice profiles | See which profiles are available |
-| `hyv_scan` | Fast local AI-pattern scan (free, 220+ patterns) | Before any prose delivery |
+| `hyv_scan` | Fast local AI-pattern scan (free, 220+ patterns) | Eligible publishable copy or an explicit HYV request |
 | `hyv_analyze` | Full hybrid scan (local + server, paid) | Important drafts |
 | `hyv_clean` | Scan → fix → validate → rewrite in one call | Best single-call pipeline |
 | `hyv_fix` | Auto-fix deterministic patterns (no LLM) | Before rewrite |

package/agents/README.md

@@ -0,0 +1,20 @@
+# `cli/agents/`
+
+## Purpose
+
+`cli/agents/` contains agent resources included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Changes must preserve package inclusion and postinstall discovery behavior. All host instructions share the same activation boundary: publishable copy or an explicit voice request uses HYV; routine chat and engineering work bypass it.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.

package/agents/chatgpt.md

@@ -1,6 +1,8 @@
 # Hold Your Voice — Writing Rules
 
-The user has a voice profile. All writing must match their personal style.
+The user has a voice profile for publishable copy: social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Apply it whenever the user explicitly asks for HYV, a voice profile, or writing in their voice.
+
+Do not apply these rules to routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, or internal engineering-status messages. If a request is ambiguous, bypass HYV unless the user explicitly requests it.
 
 ## Rules
 1. Never use AI-slop words: delve, leverage, tapestry, foster, harness, pivotal, innovative, cutting-edge, state-of-the-art, robust, holistic, multifaceted, nuanced

package/agents/claude-code.md

@@ -1,22 +1,17 @@
 # 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".
+The user has a voice profile for publishable copy. Use HYV for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Always use HYV when the user explicitly asks for it, a voice profile, or writing in their voice.
 
 ## 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
+Run `hyv_scan` or use the `hyv_scan` MCP tool before delivering eligible publishable copy:
+- Social posts, threads, and public replies
+- Newsletters, blogs, articles, and landing or product pages
+- Campaigns and external audience-facing emails
+
+Run `hyv_rewrite` or use the `hyv_rewrite` MCP tool when eligible copy needs voice work, or whenever the user explicitly asks for HYV or voice-profile writing.
+
+Bypass HYV for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. If the request is ambiguous, bypass it unless the user explicitly requests HYV.
 
 ## How to use
 

package/agents/codex.md

@@ -1,11 +1,11 @@
 # Hold Your Voice
 
-The user has a voice profile for their writing style. Use HYV for ALL writing tasks.
+The user has a voice profile for publishable copy. Use HYV for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Always use HYV when the user explicitly asks for it, a voice profile, or writing in their voice.
 
 ## Auto-trigger rules
 
-Run these MCP tools (or CLI commands) for any writing task:
-- `hyv_scan` or `hyv_analyze` on any text before delivering it
+Run these MCP tools (or CLI commands) for eligible publishable copy:
+- `hyv_scan` or `hyv_analyze` 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
@@ -25,6 +25,7 @@ hyv mcp --setup
 ```
 
 ## Rules
-- Always scan before delivering prose content
+- Bypass HYV for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. If ambiguous, bypass it unless HYV is explicitly requested.
+- Always scan eligible publishable copy
 - Always fix/rewrite if scan finds issues
-- Preserve meaning, match voice profile
+- Preserve meaning, match voice profile

package/agents/cursor.md

@@ -1,13 +1,14 @@
 # Hold Your Voice
 
-Use HYV MCP tools for all writing tasks. If no profile exists yet, call `hyv_welcome` or `hyv_profiles` first — free local scan works without a profile. For MCP host setup or refresh, call `hyv_mcp_setup` (no terminal).
+Use HYV MCP tools for publishable copy: social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Always use HYV when the user explicitly asks for it, a voice profile, or writing in their voice. If no profile exists yet, call `hyv_welcome` or `hyv_profiles` first — free local scan works without a profile. For MCP host setup or refresh, call `hyv_mcp_setup` (no terminal).
 
 ## When to use
-- Any email, post, doc, or content creation
-- Before delivering any prose to the user
-- When editing or improving text
+- Social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails
+- Any request that explicitly names HYV, a voice profile, or writing in the user's voice
 - New users: `hyv_welcome` (name → samples via extract_prompt → scan → signup last)
 
+Bypass HYV for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. If ambiguous, bypass it unless HYV is explicitly requested.
+
 ## Tool flow (preferred)
 1. `hyv_scan` — fast local check (free, offline)
 2. `hyv_analyze` — full hybrid engine when user is on a paid plan
@@ -29,7 +30,7 @@ Use HYV MCP tools for all writing tasks. If no profile exists yet, call `hyv_wel
 - `hyv_profiles` — list profiles
 
 ## Rules
-- Always scan before delivering content
+- Always scan eligible publishable copy
 - 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

@@ -1,21 +1,23 @@
 # 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.
+You have access to the Hold Your Voice MCP tools. Use the user's voice profile for publishable copy: social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Also use it whenever the user explicitly asks for HYV, a voice profile, or writing in their voice.
 
 ## Auto-trigger rules
 
-You MUST use these tools automatically — do NOT wait for the user to mention "voice" or "hyv":
+Use these tools automatically for eligible publishable copy. Always honor an explicit HYV or voice-profile request:
 
-**Before delivering any written content (emails, posts, docs, messages):**
+**Before delivering eligible publishable copy:**
 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:**
+**When the user asks you to create or rewrite eligible copy:**
 1. Write your draft
 2. Run `hyv_scan` or `hyv_clean` on it
 3. Deliver the cleaned version
 
+**Bypass HYV** for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. If the request is ambiguous, bypass it unless the user explicitly requests HYV.
+
 **After the user accepts a substantial edit:**
 - Suggest they run `hyv reinforce --last` so their profile learns from the change
 
@@ -41,7 +43,7 @@ You MUST use these tools automatically — do NOT wait for the user to mention "
 - `hyv_profiles` — list voice profiles
 
 ## Rules
-- NEVER skip scanning for user-facing content
+- NEVER skip scanning for eligible publishable copy
 - Preserve original meaning exactly when rewriting
 - Match the voice profile's rhythm, vocabulary, and tone
-- If no profile exists, run onboarding via `hyv_welcome` (step 2 extract_prompt from chat history)
+- If no profile exists, run onboarding via `hyv_welcome` (step 2 extract_prompt from chat history)

package/agents/windsurf.md

@@ -1,9 +1,9 @@
 # Hold Your Voice
 
-Use HYV MCP tools for all writing tasks. The user has a voice profile.
+Use HYV MCP tools for publishable copy: social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails. Always use HYV when the user explicitly asks for it, a voice profile, or writing in their voice.
 
 ## Auto-trigger
-- `hyv_scan` or `hyv_analyze` before delivering any text
+- `hyv_scan` or `hyv_analyze` before delivering eligible publishable copy
 - `hyv_clean` for scan → fix → validate in one call
 - `hyv_fix` then `hyv_rewrite` for stepwise fixes
 - `hyv_validate` after rewriting
@@ -14,6 +14,7 @@ Use HYV MCP tools for all writing tasks. The user has a voice profile.
 - `hyv_check` / `hyv_score` / `hyv_diff`
 
 ## Rules
-- Always scan user-facing content
+- Bypass HYV for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. If ambiguous, bypass it unless HYV is explicitly requested.
+- Always scan eligible publishable copy
 - Use `hyv_fix` before `hyv_rewrite` when possible
-- Preserve meaning, match voice profile
+- Preserve meaning, match voice profile

package/assets/README.md

@@ -0,0 +1,20 @@
+# `cli/assets/`
+
+## Purpose
+
+`cli/assets/` contains assets included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Keep package paths and postinstall consumers intact.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.

package/dist/index.js

@@ -16662,7 +16662,9 @@ function buildRewritePrompt(options) {
   const template = loadPromptTemplate();
   const prompt = template.replace("{profile_block}", profileBlock).replace("{constraints_block}", constraints || "(none)").replace("{tier_one_lines}", tierOneLines).replace("{other_lines}", otherLines).replace("{draft_name}", draftPath).replace("{numbered_draft}", numberedDraft);
   return {
-    prompt,
+    prompt: skipScan ? `${prompt}
+
+none found by deterministic scan` : prompt,
     profileUsed,
     issuesFound: issues.length
   };
@@ -17938,6 +17940,7 @@ var MCP_SERVER_ARGS = ["mcp", "--stdio"];
 // src/lib/cli-entry.ts
 function resolveCliEntry() {
   const candidates = [
+    typeof __filename !== "undefined" ? path17.resolve(__filename) : "",
     path17.resolve(process.argv[1] || ""),
     path17.resolve(__dirname, "index.js"),
     path17.resolve(__dirname, "..", "dist", "index.js")
@@ -17949,7 +17952,7 @@ function mcpServerCommand() {
   if (entry) {
     return { command: process.execPath, args: [entry, ...MCP_SERVER_ARGS] };
   }
-  return { command: "hyv", args: [...MCP_SERVER_ARGS] };
+  throw new Error("could not resolve hyv CLI entry \u2014 reinstall @holdyourvoice/hyv or run via node dist/index.js");
 }
 function mcpServerSnippet() {
   const { command, args: args2 } = mcpServerCommand();
@@ -19827,6 +19830,10 @@ async function resolveProfile(slug) {
   }
   return profile;
 }
+async function loadLocalProfileForTool(slug) {
+  void ensureMcpProfilesHydrated();
+  return loadProfileForCommand(slug);
+}
 function jsonRpcOk(id, result) {
   return JSON.stringify({ jsonrpc: "2.0", id, result });
 }
@@ -19884,7 +19891,7 @@ async function toolScan(args2) {
     return "Error: no text or file provided";
   try {
     let scanText2 = text;
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     if (filePath) {
       try {
         scanText2 = readScanFile(filePath);
@@ -19932,7 +19939,7 @@ async function toolValidate(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(profileSlug);
+    const profile = await loadLocalProfileForTool(profileSlug);
     if (!profile)
       return "Error: no voice profile available. Run hyv init or use hyv scan for free generic checks.";
     const result = validateRewrite(text, text, profile);
@@ -19955,7 +19962,7 @@ async function toolFix(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, true);
     if (result.changes.length === 0)
       return "No auto-fixable issues found.";
@@ -19974,7 +19981,7 @@ async function toolCheck(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, false);
     if (result.stats.totalSignals === 0)
       return `Clean \u2014 score: ${result.score}/100. No AI patterns found.`;
@@ -19992,7 +19999,7 @@ async function toolScore(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, false);
     return result.score.toString();
   } catch (err) {
@@ -20004,7 +20011,7 @@ async function toolDiff(args2) {
   if (!text.trim())
     return "Error: no text provided";
   try {
-    const profile = await resolveProfile(args2.profile);
+    const profile = await loadLocalProfileForTool(args2.profile);
     const result = runPipeline(text, profile, true);
     if (result.changes.length === 0)
       return "No auto-fixable changes available.";
@@ -20183,7 +20190,7 @@ var TOOLS = [
   },
   {
     name: "hyv_rewrite",
-    description: "Rewrite text to match the user's voice profile. Auto-fixes 80+ AI patterns. ALWAYS use when the user asks to write, rewrite, edit, or improve text.",
+    description: "Rewrite publishable copy to match the user's voice profile. Use for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails, or when the user explicitly asks for HYV, a voice profile, or writing in their voice. Do not auto-use for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, or internal engineering-status messages.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20195,7 +20202,7 @@ var TOOLS = [
   },
   {
     name: "hyv_analyze",
-    description: "Full analysis: local scan + optional server hybrid engine when authed (paid). Use for important drafts. Falls back to local offline.",
+    description: "Full analysis for eligible publishable copy or an explicit HYV/voice-profile request: local scan + optional server hybrid engine when authed (paid). Falls back to local offline.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20208,7 +20215,7 @@ var TOOLS = [
   },
   {
     name: "hyv_clean",
-    description: "Composite clean: scan \u2192 auto-fix \u2192 validate \u2192 LLM rewrite prompt for remaining issues. Best agent loop for polishing drafts.",
+    description: "Composite clean for eligible publishable copy or an explicit HYV/voice-profile request: scan \u2192 auto-fix \u2192 validate \u2192 LLM rewrite prompt for remaining issues.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20221,7 +20228,7 @@ var TOOLS = [
   },
   {
     name: "hyv_scan",
-    description: "Fast local scan for 80+ AI patterns + profile never-list/learned rules. FREE, offline. ALWAYS scan before finalizing any written content \u2014 emails, posts, docs, replies, messages, or prose.",
+    description: "Fast local scan for 80+ AI patterns + profile never-list/learned rules. FREE, offline. Auto-use only for eligible publishable copy (social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails) or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20233,7 +20240,7 @@ var TOOLS = [
   },
   {
     name: "hyv_fix",
-    description: "Apply deterministic auto-fixes without an LLM. FREE, works offline.",
+    description: "Apply deterministic auto-fixes without an LLM. FREE, works offline. Auto-use only for eligible publishable copy or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20245,7 +20252,7 @@ var TOOLS = [
   },
   {
     name: "hyv_check",
-    description: "Quick inline text check \u2014 score and issues. FREE, works offline.",
+    description: "Quick inline text check \u2014 score and issues. FREE, works offline. Auto-use only for eligible publishable copy or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20257,7 +20264,7 @@ var TOOLS = [
   },
   {
     name: "hyv_score",
-    description: "Return a 0-100 voice score. FREE, works offline.",
+    description: "Return a 0-100 voice score. FREE, works offline. Auto-use only for eligible publishable copy or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20269,7 +20276,7 @@ var TOOLS = [
   },
   {
     name: "hyv_diff",
-    description: "Show auto-fixes as before/after diff. FREE, works offline.",
+    description: "Show auto-fixes as before/after diff. FREE, works offline. Auto-use only for eligible publishable copy or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20286,7 +20293,7 @@ var TOOLS = [
   },
   {
     name: "hyv_validate",
-    description: "Validate text against a voice profile (never-list, cadence, learned rules).",
+    description: "Validate text against a voice profile (never-list, cadence, learned rules). Auto-use only for eligible publishable copy or an explicit HYV/voice-profile request.",
     inputSchema: {
       type: "object",
       properties: {
@@ -20309,7 +20316,7 @@ var HYV_STATUS_PROMPT = `Use hold your voice MCP tools:
 0. MCP setup \u2192 hyv_mcp_setup (status | integrate | chatgpt). Profiles \u2192 hyv_profiles (lists MCP-ready profiles).
 1. Profiles work automatically: terminal \`hyv welcome\` saves locally; dashboard profiles need \`hyv init\` once on this machine (MCP auto-syncs).
 2. New onboarding in chat \u2192 hyv_welcome. Step 2: mode=extract_prompt. Save markdown \u2192 hyv import or dashboard.
-3. Writing (use active profile from hyv_profiles): hyv_scan \u2192 hyv_fix / hyv_rewrite \u2192 hyv_validate. Optional profile= slug.
+3. Eligible publishable copy (social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails), or an explicit HYV/voice-profile request: hyv_scan \u2192 hyv_fix / hyv_rewrite \u2192 hyv_validate. Bypass HYV for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages.
 4. Paid extras \u2192 hyv init + hyv plan --upgrade (signup last).
 
 Keep the answer compact.`;
@@ -20650,11 +20657,11 @@ init_api();
 var FORMATS = {
   claude: {
     name: "Claude / Claude Code",
-    wrap: (profile, body) => `You are rewriting text to match a specific voice profile. Use this voice profile for all writing:
+    wrap: (profile, body) => `You are rewriting publishable copy to match a specific voice profile. Use the HYV voice profile only for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails, or when explicitly asked to use HYV, a voice profile, or to write in this voice.
 
 ${body}
 
-When asked to write or rewrite "in my voice", match this profile exactly. Preserve meaning. Match rhythm, vocabulary, tone, and sentence patterns. Never use words from the never-list.`
+Bypass it for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. Preserve meaning. Match rhythm, vocabulary, tone, and sentence patterns. Never use words from the never-list.`
   },
   chatgpt: {
     name: "ChatGPT Custom Instructions",
@@ -20662,7 +20669,7 @@ When asked to write or rewrite "in my voice", match this profile exactly. Preser
 
 ${body}
 
-When I ask you to "write in my voice" or "rewrite this in my voice", match this profile. Same rhythm. Same vocabulary. Same patterns. No AI-slop words.`
+Use the HYV voice profile only for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails, or when I explicitly ask to use HYV, a voice profile, or to write in my voice. Do not apply it to routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, or internal engineering-status messages. Same rhythm. Same vocabulary. Same patterns. No AI-slop words.`
   },
   generic: {
     name: "Generic System Prompt",
@@ -20671,7 +20678,7 @@ When I ask you to "write in my voice" or "rewrite this in my voice", match this
 ${body}
 
 ## Instructions
-Rewrite text to match this voice profile. Preserve meaning. Match rhythm, vocabulary, and tone. Remove AI-slop patterns (delve, leverage, tapestry, etc.).`
+Use the HYV voice profile only for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails, or when explicitly asked to use HYV, a voice profile, or to write in this voice. Bypass it for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages. Preserve meaning. Match rhythm, vocabulary, and tone. Remove AI-slop patterns (delve, leverage, tapestry, etc.).`
   },
   cursor: {
     name: "Cursor Rules",
@@ -20680,7 +20687,9 @@ Rewrite text to match this voice profile. Preserve meaning. Match rhythm, vocabu
 ${body}
 
 ## Rewrite Rules
-- Match this voice profile for all writing
+- Use the HYV voice profile only for social posts, newsletters, blogs, landing or product pages, campaigns, and external audience-facing emails
+- Also use it when explicitly asked to use HYV, a voice profile, or to write in this voice
+- Bypass it for routine chat, Q&A, analysis, research, planning, coding, debugging, reviews, logs, operational work, code comments, and internal engineering-status messages
 - Preserve meaning
 - Remove AI-slop patterns
 - Use the same rhythm and vocabulary`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "2.9.26",
+  "version": "2.9.28",
   "description": "Free local AI writing scan for cursor & claude. MCP server, 220+ pattern detection, voice profiles. npx @holdyourvoice/hyv welcome",
   "main": "dist/index.js",
   "bin": {

package/scripts/README.md

@@ -0,0 +1,23 @@
+# `cli/scripts/`
+
+## Purpose
+
+`cli/scripts/` contains package install, publish validation, smoke-test, and supporting CLI scripts.
+
+## Contracts
+
+Scripts are referenced by `cli/package.json` and the npm package `files` list. Package-relative paths must remain valid when the package is published.
+
+`postinstall-lib.js` writes the managed host instructions. A CLI version bump refreshes them through the `~/.hyv/agents-version.json` marker when users run install or `hyv doctor --fix-agents`. `validate-publish.js` accepts npm's array and package-name keyed dry-run manifests.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+npm run test:smoke
+```
+
+## Documentation ownership
+
+Changes under this folder update this README, `cli/README.md`, and the root `README.md`.

package/skills/README.md

@@ -0,0 +1,20 @@
+# `cli/skills/`
+
+## Purpose
+
+`cli/skills/` contains skills included in the published CLI package.
+
+## Contracts
+
+The directory is included by the `files` list in `cli/package.json`. Changes must preserve package inclusion and any postinstall or agent configuration paths that reference these files.
+
+## Validation
+
+```bash
+cd cli
+npm run validate:publish
+```
+
+## Documentation ownership
+
+Changes update this README, `cli/README.md`, and the root `README.md`.