@holdyourvoice/hyv 2.9.21 → 2.9.23

package/agents/AGENTS.md

@@ -0,0 +1,80 @@
+# 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".
+
+## Auto-trigger — do these automatically
+
+**Before delivering any written content (emails, replies, posts, docs, messages, or prose):**
+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:**
+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
+
+**After the user accepts a substantial edit:**
+- Suggest they run `hyv reinforce --last` so their profile learns from the change
+
+## Which tool to use
+
+| Tool | What it does | When to use |
+|------|-------------|-------------|
+| `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_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 |
+| `hyv_rewrite` | Profile-aware rewrite prompt | After scan/fix |
+| `hyv_validate` | Verify output matches voice profile | After rewrite |
+| `hyv_check` | Quick pass/fail | Spot checks |
+| `hyv_score` | 0-100 voice score | Quantify quality |
+| `hyv_diff` | Before/after comparison | Review changes |
+| `hyv_list_free_tools` | List all free capabilities | What's available |
+
+## Voice profiles
+
+- Run `hyv_profiles` first if unsure which profile is active.
+- Terminal profiles (from `hyv welcome`) are already local — no extra step.
+- Dashboard profiles sync after the user runs `hyv init` once (MCP auto-downloads).
+- Pass `profile: "<slug>"` on tools only when using a non-default profile.
+- If no profile exists yet, free local scan still works — call `hyv_welcome` to onboard.
+
+## Rewrite rules
+
+1. **Never** use AI-slop words: delve, leverage, tapestry, foster, harness, pivotal, innovative, cutting-edge, robust, holistic, nuanced, resonate, unpack, navigate, landscape, ecosystem, transformative, paradigm, revolutionize, unlock, supercharge, game-changer
+2. **Never** use formulaic connectors: firstly, secondly, moreover, furthermore, in conclusion, to conclude, notably
+3. **Never** use hedging: arguably, perhaps, some might say, it's worth noting, it's important to note
+4. **Never** use signpost claims: this is why, this is how, here's where, here's why
+5. **Never** use antithesis patterns: "not just X, but Y", "more than just", "it's not about X, it's about Y"
+6. **Match** the user's sentence rhythm, vocabulary, and tone from their voice profile
+7. **Preserve** roughness that carries voice — don't over-polish
+8. **Open** from concrete observations, not generic setups
+9. **Fix only** flagged lines — preserve clean lines exactly
+10. **Never add** sections, hooks, CTAs, markdown, or commentary
+
+## MCP setup (no terminal needed)
+
+- `hyv_mcp_setup` with `action=status` — see what's integrated and onboarding progress
+- `hyv_mcp_setup` with `action=integrate` — refresh Cursor/Claude configs (`force=true` after hyv upgrade)
+- `hyv_mcp_setup` with `action=chatgpt` — ChatGPT remote OAuth steps (recommended for paid users)
+- `hyv_welcome` — finish voice onboarding inside this chat
+
+## CLI fallback (when MCP tools aren't available)
+
+```bash
+echo "text to check" | hyv scan -
+hyv fix file.md              # apply auto-fixes without LLM
+hyv rewrite file.md          # generate rewrite prompt
+hyv check "inline text"      # quick spot-check
+hyv score file.md            # just a 0-100 number
+hyv diff file.md             # show proposed fixes
+hyv profiles                 # list profiles
+hyv reinforce --last         # learn from last edit
+hyv mcp --setup              # view all MCP configs
+hyv mcp --test               # verify everything works
+```

package/dist/index.js

@@ -4727,6 +4727,41 @@ var init_profile_meta = __esm({
 });
 
 // src/lib/config.ts
+var config_exports = {};
+__export(config_exports, {
+  API_BASE: () => API_BASE,
+  AUTH_FILE: () => AUTH_FILE,
+  CACHE_DIR: () => CACHE_DIR2,
+  CONFIG_FILE: () => CONFIG_FILE,
+  HYV_DIR: () => HYV_DIR,
+  LAST_SESSION_FILE: () => LAST_SESSION_FILE,
+  PROFILES_DIR: () => PROFILES_DIR,
+  QUEUE_DIR: () => QUEUE_DIR,
+  appendSecureLine: () => appendSecureLine,
+  assertSafeOAuthUrl: () => assertSafeOAuthUrl,
+  assertSafeOpenUrl: () => assertSafeOpenUrl,
+  assertSafeProfileName: () => assertSafeProfileName,
+  clearAuth: () => clearAuth,
+  clearQueuedSignals: () => clearQueuedSignals,
+  cliApiUrl: () => cliApiUrl,
+  ensureHyvDir: () => ensureHyvDir,
+  getQueuedSignals: () => getQueuedSignals,
+  getToken: () => getToken,
+  isInitialized: () => isInitialized,
+  listCachedProfiles: () => listCachedProfiles,
+  profilePathForName: () => profilePathForName,
+  queueSignal: () => queueSignal,
+  readAuth: () => readAuth,
+  readCachedProfile: () => readCachedProfile,
+  readConfig: () => readConfig,
+  readLastEditSession: () => readLastEditSession,
+  saveLastEditSession: () => saveLastEditSession,
+  toSafeProfileCacheKey: () => toSafeProfileCacheKey,
+  writeAuth: () => writeAuth,
+  writeCachedProfile: () => writeCachedProfile,
+  writeConfig: () => writeConfig,
+  writeSecureFile: () => writeSecureFile
+});
 function validateApiBase(raw) {
   const trimmed = raw.replace(/\/$/, "");
   let parsed;
@@ -4822,6 +4857,10 @@ function ensureHyvDir() {
     }
   }
 }
+function writeSecureFile(filePath, content) {
+  ensureHyvDir();
+  fs3.writeFileSync(filePath, content, { mode: 384 });
+}
 function appendSecureLine(filePath, line, dir) {
   if (dir) {
     if (!fs3.existsSync(dir))
@@ -4866,6 +4905,11 @@ function writeAuth(auth) {
   }
   fs3.writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2), { mode: 384 });
 }
+function clearAuth() {
+  if (fs3.existsSync(AUTH_FILE)) {
+    fs3.unlinkSync(AUTH_FILE);
+  }
+}
 function readConfig() {
   try {
     if (!fs3.existsSync(CONFIG_FILE))
@@ -4943,6 +4987,17 @@ function queueSignal(signal) {
   const filePath = path2.join(QUEUE_DIR, `${id}.json`);
   fs3.writeFileSync(filePath, JSON.stringify(signal, null, 2), { mode: 384 });
 }
+function clearQueuedSignals() {
+  try {
+    if (!fs3.existsSync(QUEUE_DIR))
+      return;
+    const files = fs3.readdirSync(QUEUE_DIR).filter((f) => f.endsWith(".json"));
+    for (const f of files) {
+      fs3.unlinkSync(path2.join(QUEUE_DIR, f));
+    }
+  } catch {
+  }
+}
 function saveLastEditSession(session) {
   ensureHyvDir();
   const data = { ...session, saved_at: (/* @__PURE__ */ new Date()).toISOString() };
@@ -17087,7 +17142,28 @@ function registerImportCommand(program3) {
       ensureHyvDir();
       writeCachedProfile(name, content);
       console.log(import_chalk13.default.green(`
-\u2713 Profile imported: ${name}`));
+\u2713 Profile imported locally: ${name}`));
+      const { getToken: getToken2 } = await Promise.resolve().then(() => (init_config(), config_exports));
+      const { authenticatedRequest: authenticatedRequest2, cliApiUrl: cliApiUrl2 } = await Promise.resolve().then(() => (init_auth(), auth_exports));
+      const token = getToken2();
+      if (token) {
+        console.log(import_chalk13.default.cyan("\nSyncing profile to your account..."));
+        try {
+          const syncResponse = await authenticatedRequest2(
+            cliApiUrl2("/cli/profiles/new"),
+            { method: "POST", body: { name, content, source: "import" } }
+          );
+          if (syncResponse.status === 200) {
+            console.log(import_chalk13.default.green("  \u2713 synced to your account"));
+          } else {
+            console.log(import_chalk13.default.yellow("  profile saved locally \u2014 run `hyv sync` to push to your account"));
+          }
+        } catch {
+          console.log(import_chalk13.default.yellow("  profile saved locally \u2014 run `hyv sync` to push to your account"));
+        }
+      } else {
+        console.log(import_chalk13.default.dim("\n  not signed in \u2014 profile saved locally. run `hyv init` then `hyv sync` to back it up."));
+      }
     } catch (error) {
       console.error(import_chalk13.default.red(`Error: ${error.message}`));
       process.exit(1);
@@ -19319,6 +19395,69 @@ function formatMcpIntegrateReportText(result, opts = {}) {
   }
   return lines.join("\n");
 }
+function printMcpIntegrateReport(result, opts = {}) {
+  const { agentIdForConfiguredLabel, isAgentIntegrated } = loadPostinstallLib();
+  const configuredIds = new Set(
+    result.configured.map((label) => agentIdForConfiguredLabel(label)).filter(Boolean)
+  );
+  console.log(import_chalk33.default.bold("\nhold your voice \u2014 mcp integration\n"));
+  console.log(import_chalk33.default.dim(`  ${getEngineLabel()}
+`));
+  const welcome = readWelcomeState();
+  const profiles = listLocalProfileNames2();
+  if (profiles.length > 0) {
+    console.log(import_chalk33.default.dim(`  voice profiles: ${profiles.join(", ")}`));
+  } else {
+    console.log(import_chalk33.default.yellow("  no voice profile yet \u2014 mcp still works (free scan). finish onboarding in terminal or in-chat via hyv_welcome"));
+  }
+  if (welcome.completed_steps?.length) {
+    console.log(import_chalk33.default.dim(`  welcome progress: ${welcome.completed_steps.join(", ")}`));
+  }
+  console.log("");
+  if (result.detected.length === 0) {
+    console.log(import_chalk33.default.yellow("  no supported ai apps detected on this machine."));
+    console.log(import_chalk33.default.dim("\n  install cursor, claude desktop, chatgpt desktop, or another supported app,"));
+    console.log(import_chalk33.default.dim("  then run hyv mcp again \u2014 or hyv doctor --fix-agents to configure everything."));
+    console.log(import_chalk33.default.dim("\n  in chatgpt/claude/cursor: call hyv_welcome to onboard without the terminal."));
+    console.log(import_chalk33.default.dim("  chatgpt desktop (paid): developer mode \u2192 new app \u2192 https://holdyourvoice.com/mcp + oauth"));
+    console.log(import_chalk33.default.dim("  full steps: hyv mcp --setup-chatgpt\n"));
+    return;
+  }
+  console.log(import_chalk33.default.bold("detected apps"));
+  for (const app of result.detected) {
+    const justConfigured = configuredIds.has(app.id);
+    const integrated = isAgentIntegrated(app.id) || justConfigured;
+    const mark = app.integration === "manual" ? import_chalk33.default.yellow("\u25CB") : integrated ? import_chalk33.default.green("\u2713") : import_chalk33.default.cyan("\u2192");
+    const status = app.integration === "manual" ? "manual connector \u2014 see ~/.chatgpt/hyv-mcp-connector.txt" : justConfigured ? opts.force ? "updated now" : "configured now" : integrated ? "integrated" : "needs setup";
+    console.log(`  ${mark} ${app.label} \u2014 ${status}`);
+    console.log(import_chalk33.default.dim(`      ${app.reason} \xB7 ${app.integration}`));
+  }
+  if (result.configured.length > 0) {
+    console.log(import_chalk33.default.green(`
+  wired hyv into: ${result.configured.join(", ")}`));
+  }
+  if (result.warnings.length > 0) {
+    console.log(import_chalk33.default.yellow("\n  notes:"));
+    for (const warning of result.warnings) {
+      console.log(import_chalk33.default.yellow(`    ! ${warning}`));
+    }
+  }
+  const mcpApps = result.detected.filter((a) => a.integration === "mcp");
+  const manualApps = result.detected.filter((a) => a.integration === "manual");
+  console.log(import_chalk33.default.bold("\nnext steps"));
+  console.log(import_chalk33.default.dim("  in this app: hyv_welcome (onboarding) \xB7 hyv_mcp_setup (status/refresh) \xB7 hyv_demo (try a scan)"));
+  if (mcpApps.length > 0) {
+    console.log(import_chalk33.default.dim("  restart apps that use mcp (cursor, claude desktop, antigravity, opencode)"));
+  }
+  if (manualApps.length > 0) {
+    console.log(import_chalk33.default.dim("  chatgpt (recommended): developer mode \u2192 new app \u2192 https://holdyourvoice.com/mcp + oauth"));
+    console.log(import_chalk33.default.dim("  chatgpt (free fallback): settings \u2192 connectors \u2192 command hyv, arguments mcp"));
+    console.log(import_chalk33.default.dim("  full steps: hyv mcp --setup-chatgpt"));
+  }
+  console.log(import_chalk33.default.dim("  refresh stale configs after upgrade: hyv mcp --force"));
+  console.log(import_chalk33.default.dim("  verify: hyv mcp --test"));
+  console.log(import_chalk33.default.dim("  all hosts: hyv doctor --verify-hosts\n"));
+}
 
 // src/mcp.ts
 init_mcp_profile_hydrate();
@@ -19758,7 +19897,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 written content.",
+    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.",
     inputSchema: {
       type: "object",
       properties: {
@@ -19971,6 +20110,16 @@ async function startMcpServer() {
       mcpLog("info", `account profile sync skipped: ${r.error}`);
   }).catch(() => {
   });
+  try {
+    const result = runMcpAutoIntegrate({ force: false });
+    if (result.configured.length > 0) {
+      mcpLog("info", `mcp auto-configured: ${result.configured.join(", ")}`);
+    }
+    if (result.detected.length > 0 && result.configured.length === 0) {
+      mcpLog("info", `detected apps (already configured): ${result.detected.map((a) => a.label).join(", ")}`);
+    }
+  } catch {
+  }
   let buffer = "";
   process.stdin.setEncoding("utf-8");
   let requestChain = Promise.resolve();
@@ -20335,7 +20484,7 @@ registerOpenCommand(program2);
 registerWelcomeCommand(program2);
 registerContentCommand(program2);
 registerUpgradeCommand(program2);
-program2.command("mcp").description("Start MCP server (for Claude Desktop and other MCP hosts)").option("--setup", "Show MCP setup for Claude Desktop, Cursor, Windsurf, Codex").option("--test", "Run MCP health check (tools, profile, stdio)").option("--setup-chatgpt", "Show ChatGPT connector setup instructions").action(async (opts) => {
+program2.command("mcp").description("Detect installed apps, configure MCP, and start the MCP server").option("--setup", "Show MCP setup for Claude Desktop, Cursor, Windsurf, Codex").option("--test", "Run MCP health check (tools, profile, stdio)").option("--setup-chatgpt", "Show ChatGPT connector setup instructions").option("--force", "Force re-configure MCP even if already integrated").action(async (opts) => {
   if (opts.setup) {
     printMcpSetup();
     return;
@@ -20394,6 +20543,10 @@ program2.command("mcp").description("Start MCP server (for Claude Desktop and ot
     console.log("");
     return;
   }
+  console.log(import_chalk35.default.bold("\nhold your voice \u2014 detecting and configuring mcp...\n"));
+  const result = runMcpAutoIntegrate({ force: Boolean(opts.force) });
+  printMcpIntegrateReport(result, { force: Boolean(opts.force) });
+  console.log(import_chalk35.default.dim("\nstarting MCP server (press Ctrl+C to stop)...\n"));
   startMcpServer();
 });
 program2.command("export").description("Export voice profile for LLMs").argument("[format]", "Export format (claude, chatgpt, generic, cursor)", "claude").option("--output <file>", "Write to file instead of stdout").option("--json", "Output as JSON").action(async (format, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdyourvoice/hyv",
-  "version": "2.9.21",
+  "version": "2.9.23",
   "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/postinstall-lib.js

@@ -572,7 +572,7 @@ function setupAgents({
     const codexDir = path.join(home, '.codex');
     fs.mkdirSync(codexDir, { recursive: true });
     const agentsFile = path.join(codexDir, 'AGENTS.md');
-    const src = path.join(pkgDir, 'agents', 'codex.md');
+    const src = path.join(pkgDir, 'agents', 'AGENTS.md');
     let existing = '';
     if (fs.existsSync(agentsFile)) existing = fs.readFileSync(agentsFile, 'utf-8');
     const addition = fs.existsSync(src) ? fs.readFileSync(src, 'utf-8') : '';
@@ -648,10 +648,10 @@ function setupAgents({
     if (!ocResult.ok) warnings.push(`opencode: could not update opencode.jsonc (${ocResult.reason})`);
 
     const agentsFile = path.join(ocDir, 'AGENTS.md');
-    const genericSrc = path.join(pkgDir, 'agents', 'generic.md');
+    const agentsSrc = path.join(pkgDir, 'agents', 'AGENTS.md');
     let existing = '';
     if (fs.existsSync(agentsFile)) existing = fs.readFileSync(agentsFile, 'utf-8');
-    const addition = fs.existsSync(genericSrc) ? fs.readFileSync(genericSrc, 'utf-8') : '';
+    const addition = fs.existsSync(agentsSrc) ? fs.readFileSync(agentsSrc, 'utf-8') : '';
     if (addition && shouldUpgradeAgent(agentsFile, agentsMarker, pkgVersion)) {
       const merged = mergeAgentsMd(existing, addition, 'hold-your-voice');
       fs.mkdirSync(ocDir, { recursive: true });
@@ -730,8 +730,8 @@ function setupAgents({
 
   // Generic reference copy (always when auto-configure runs)
   try {
-    const genericSrc = path.join(pkgDir, 'agents', 'generic.md');
-    const genericDest = path.join(hyvDir, 'agents', 'generic.md');
+    const genericSrc = path.join(pkgDir, 'agents', 'AGENTS.md');
+    const genericDest = path.join(hyvDir, 'agents', 'AGENTS.md');
     if (fs.existsSync(genericSrc)) installAgent(genericSrc, genericDest);
   } catch {
     // non-fatal