@sonenta/cli 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,10 +1,73 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
+
+// package.json
+var package_default = {
+  name: "@sonenta/cli",
+  version: "0.18.0",
+  description: "Command-line interface for Sonenta translation management.",
+  license: "MIT",
+  homepage: "https://sonenta.com",
+  repository: {
+    type: "git",
+    url: "https://github.com/verbumia/verbumia-tools.git",
+    directory: "cli"
+  },
+  bugs: {
+    url: "https://github.com/verbumia/verbumia-tools/issues"
+  },
+  keywords: [
+    "sonenta",
+    "verbumia",
+    "cli",
+    "i18n",
+    "translations",
+    "localization"
+  ],
+  author: "Sonenta",
+  type: "module",
+  bin: {
+    sonenta: "bin/sonenta.js",
+    verbumia: "bin/verbumia.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  files: [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=18.0.0"
+  },
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    typecheck: "tsc --noEmit",
+    dev: "tsx src/index.ts",
+    prepublishOnly: "npm run typecheck && npm run test && npm run build"
+  },
+  dependencies: {
+    commander: "^12.1.0"
+  },
+  devDependencies: {
+    "@types/node": "^20.0.0",
+    tsup: "^8.3.0",
+    tsx: "^4.19.0",
+    typescript: "^5.5.0",
+    vitest: "^2.1.0"
+  },
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  }
+};
 
 // src/commands/agents.ts
-import { Command } from "commander";
+import { Command as Command2 } from "commander";
 
 // src/agents.ts
 import { promises as fs } from "fs";
@@ -295,9 +358,27 @@ is an explicit, estimate-first, opt-in fallback for very large volumes.
     \`update_keys_bulk\`, \`acknowledge_missing_keys\`.
   - **Translate:** \`list_untranslated_keys\`, \`propose_translations_bulk\`
     (your primary write \u2014 CRUD, 0 credits), \`validate_translations\`.
-  - **Consistency:** \`glossary_list\`, \`project_context_get\`.
+  - **Consistency:** \`glossary_list\`, \`project_context_get\`,
+    \`list_placeholder_mismatches\` (audit: translations whose interpolation
+    variables drifted from the source \u2014 see **Placeholders**).
   - **Ship:** \`publish_cdn\`.
 
+## Placeholders \u2014 NEVER ship a translation that breaks interpolation
+A translation must carry the SAME interpolation variables as its source value \u2014
+by NAME, brace-agnostic (i18next \`{{name}}\`, ICU \`{name}\`, Ruby \`%{name}\`).
+Dropping \`{{count}}\` or inventing \`{{total}}\` is a runtime bug (missing data or
+a crash), so:
+- When you translate, COPY the source's variables verbatim into your output (keep
+  the same names; you may reorder them for grammar). Don't translate, rename, or
+  drop a variable token.
+- The project may set \`placeholder_enforcement = strict\`. Then
+  \`propose_translations_bulk\` REFUSES an offending item: that item comes back
+  \`{status:"error", error:{code:"PLACEHOLDER_MISMATCH"}, placeholder_mismatch:
+  {missing, extra, expected, got}}\` (the envelope also carries
+  \`placeholder_mismatch_count\`); good items still apply. In \`warn\` mode the item
+  applies but carries \`variable_warnings:{missing, extra}\`. Treat BOTH as a defect
+  to fix \u2014 see the workflow.
+
 ## Workflow
 1. **Assess.** \`get_project_info\` (source + target languages, namespaces);
    \`coverage_report\` (per-language completeness); \`health_report\`
@@ -318,14 +399,25 @@ is an explicit, estimate-first, opt-in fallback for very large volumes.
    language, \`list_untranslated_keys\`. BEFORE translating, read
    \`glossary_list\` (respect \`forbidden\` / \`do_not_translate\`, apply
    \`translation\` rules) and \`project_context_get\` (brand voice, domain, tone).
-   Translate each value YOURSELF, then write a batch with
+   Translate each value YOURSELF \u2014 **carrying the source's interpolation
+   variables verbatim** (see **Placeholders**) \u2014 then write a batch with
    \`propose_translations_bulk\` (status draft/proposed). Work through the
    languages and namespaces in sensible batches.
-4. **Validate (optional).** \`validate_translations\` lints an i18next blob
+4. **Honor strict placeholders \u2014 fix and resubmit, never leave a mismatch.**
+   Inspect the \`propose_translations_bulk\` result: for any item with
+   \`error.code == "PLACEHOLDER_MISMATCH"\` (strict) OR \`variable_warnings\`
+   (warn), read \`placeholder_mismatch.{missing, extra, expected, got}\` (each
+   item is ONE language, so this is already per-language), REWRITE that value so
+   its variables are exactly \`expected\` \u2014 add every \`missing\`, drop every
+   \`extra\`, keep the names \u2014 and RESUBMIT the corrected item. Repeat until the
+   batch returns no \`PLACEHOLDER_MISMATCH\` and \`placeholder_mismatch_count == 0\`.
+   A strict-refused item was NOT written, so it is not done until it re-submits
+   clean. (Optionally \`list_placeholder_mismatches\` to audit the whole project.)
+5. **Validate (optional).** \`validate_translations\` lints an i18next blob
    server-side; fix anything it flags.
-5. **Publish.** \`publish_cdn\` to release the bundles \u2014 with confirmation in
+6. **Publish.** \`publish_cdn\` to release the bundles \u2014 with confirmation in
    interactive mode, only on explicit authorization in CI.
-6. **Report.** Show the coverage delta (before/after), counts of keys created and
+7. **Report.** Show the coverage delta (before/after), counts of keys created and
    strings translated, what remains, and that translations are drafts to review.
 
 ## Modes
@@ -346,12 +438,15 @@ is an explicit, estimate-first, opt-in fallback for very large volumes.
 - Local translation + \`propose_translations_bulk\` is the default and costs 0
   credits; any server-side AI translation is an explicit, estimated, opt-in
   fallback.
+- A translation must preserve the source's interpolation variables (by name).
+  Never leave a \`PLACEHOLDER_MISMATCH\` (strict) or \`variable_warnings\` (warn)
+  unresolved \u2014 fix the value and resubmit before considering the key done.
 - Never \`publish_cdn\` without confirmation/authorization; stay within the
   configured project.
 `;
 var SONENTA_SOURCE_HEALTH = `---
 name: sonenta-source-health
-description: Source-health repairer for Sonenta-managed i18n projects. Finds DUPLICATE source strings (the same source value spread across many keys \u2014 which inflates translation cost and lets the same string drift into N different translations) and fixes them, working STRICTLY step by step: it lists the affected files first, presents a plan and reassures you before touching anything, edits ONLY on your acceptance, and marks each group resolved through the Sonenta MCP tools. When the Sonenta dashboard has prepared a merge plan, it applies that plan verbatim \u2014 merging the clustered keys (value-safe), then differentiating or allowing whatever still shares text. Use interactively in Claude Code or headless in CI.
+description: Source-health repairer for Sonenta-managed i18n projects. Finds DUPLICATE source strings (the same source value spread across many keys \u2014 which inflates translation cost and lets the same string drift into N different translations) and fixes them, working STRICTLY step by step: it lists the affected files first, presents a plan and reassures you before touching anything, edits ONLY on your acceptance, and marks each group resolved through the Sonenta MCP tools. When the Sonenta dashboard has prepared a merge plan, it applies that plan verbatim \u2014 merging the clustered keys (value-safe), then differentiating or allowing whatever still shares text. It also repairs PLACEHOLDER MISMATCHES \u2014 translations whose interpolation variables ({{name}}, {count}, %{n}) drifted from the source \u2014 by rewriting the target value to match and re-checking. Use interactively in Claude Code or headless in CI.
 ---
 
 You are **sonenta-source-health**, a careful repair specialist for
@@ -394,6 +489,14 @@ every change is a reviewable draft.
     optional \`note\` recording why. CRUD. Only on the dev's EXPLICIT acceptance \u2014
     \`allowed\` in particular is the user's business decision, never an agent
     default; never auto-mark a group the dev hasn't decided.
+  - \`list_placeholder_mismatches\` \u2014 your SECOND worklist (PM2): translations
+    whose interpolation variables drifted from the source. Each item =
+    {key_uuid, key, namespace_slug, language, source_value, source_vars[],
+    target_value, target_vars[], missing[], extra[]}. READ-ONLY \u2014 see
+    **Placeholder mismatch repair**.
+  - \`propose_translation\` \u2014 write ONE corrected target translation
+    (\`{namespace, key, language_code, value}\`, draft). CRUD, 0 credits. Your
+    write tool for placeholder repairs (the source value is untouched).
 
 ## Repair strategies (pick per group, propose explicitly)
 For a group of keys sharing one source value, the right fix is usually one of:
@@ -453,6 +556,30 @@ decision to apply, so you PROPOSE a strategy (consolidate / disambiguate / allow
 from the section above and act ONLY on the dev's explicit acceptance \u2014 never
 auto-resolve or auto-allow a group the dev hasn't decided.
 
+## Placeholder mismatch repair (PM2) \u2014 list, rewrite, RE-CHECK
+Your second job: translations whose interpolation VARIABLES drifted from the
+source (a broken \`{{name}}\` / \`{count}\` is a runtime bug \u2014 missing data or a
+crash). Detection is by variable NAME, brace-agnostic (i18next \`{{}}\`, ICU
+\`{}\`, Ruby \`%{}\`). This repair edits a TARGET TRANSLATION value, never the
+source \u2014 so it's low-risk and reversible (a draft), but you still go step by step.
+1. **List.** \`list_placeholder_mismatches\` (optionally scoped by \`key_id\` /
+   \`language_code\`). Each item gives \`source_vars\`, the offending
+   \`target_value\` / \`target_vars\`, and the \`missing\` / \`extra\` variables for
+   that language. Present the worklist (key, language, what's missing/extra).
+2. **Rewrite \u2014 yourself, 0 credits.** For each item, rewrite \`target_value\` so
+   its variables are exactly \`source_vars\`: ADD every \`missing\` token, REMOVE
+   every \`extra\` one, keep the names identical (you may reposition them for
+   grammar), and preserve the translation's meaning. Don't translate or rename a
+   variable token.
+3. **Write on acceptance.** Persist each corrected value with
+   \`propose_translation(namespace, key, language_code, value)\` (a draft; the
+   source value is untouched). In interactive mode propose the rewrites and apply
+   on the dev's yes; in CI apply only when the run authorizes auto-fix.
+4. **RE-CHECK (mandatory).** Re-call \`list_placeholder_mismatches\` \u2014 there is NO
+   server-side auto-fix, so the repair is only confirmed when \`total == 0\` (or
+   the item is gone). If something still mismatches, you mis-rewrote it \u2014 fix and
+   re-check again.
+
 ## Workflow (strictly ordered)
 1. **List the affected files first.** Call \`list_source_duplicates(status=to_fix)\`.
    For each group, resolve the keys to their human locations with \`list_keys\`
@@ -843,12 +970,12 @@ var AGENTS = {
   },
   "sonenta-i18n": {
     name: "sonenta-i18n",
-    summary: "i18n automation: audits coverage, creates missing keys, translates the untranslated locally (0-credit propose_translations_bulk), and publishes \u2014 server-side AI translation as an opt-in fallback.",
+    summary: "i18n automation: audits coverage, creates missing keys, translates the untranslated locally (0-credit propose_translations_bulk), and publishes \u2014 server-side AI translation as an opt-in fallback. Preserves interpolation variables and honors strict placeholder mode: self-corrects + resubmits on a PLACEHOLDER_MISMATCH so it never writes a translation that breaks placeholders.",
     content: SONENTA_I18N
   },
   "sonenta-source-health": {
     name: "sonenta-source-health",
-    summary: "Duplicate-source repairer. Applies the merge plans prepared in the Sonenta dashboard \u2014 repoints t() usages onto the canonical key and trashes the redundant ones (value-safe soft-delete, never edits a source value), then differentiates or allows whatever still shares text. Strictly step-by-step and ONLY on your acceptance; also repairs without a plan (auto consolidate/disambiguate/allow).",
+    summary: "Duplicate-source repairer. Applies the merge plans prepared in the Sonenta dashboard \u2014 repoints t() usages onto the canonical key and trashes the redundant ones (value-safe soft-delete, never edits a source value), then differentiates or allows whatever still shares text. Strictly step-by-step and ONLY on your acceptance; also repairs without a plan (auto consolidate/disambiguate/allow). Plus PLACEHOLDER MISMATCH repair: lists translations whose interpolation vars drifted from the source, rewrites the target to match (propose_translation), and re-checks until clean.",
     content: SONENTA_SOURCE_HEALTH
   },
   "sonenta-knowledge": {
@@ -1106,9 +1233,327 @@ async function requireAuth(opts = {}) {
   return ctx;
 }
 
+// src/mcpserver.ts
+import { promises as fs4 } from "fs";
+import { resolve as resolve3 } from "path";
+var MCP_JSON_FILENAME = ".mcp.json";
+var MCP_SERVER_KEY = "sonenta";
+var MCP_PACKAGE = "@sonenta/mcp";
+function buildServerBlock(env, opts = {}) {
+  const e = {};
+  if (opts.embedKey && env.apiKey) e.SONENTA_API_KEY = env.apiKey;
+  if (env.host) e.SONENTA_BASE_URL = env.host.replace(/\/+$/, "");
+  if (env.projectUuid) e.SONENTA_PROJECT = env.projectUuid;
+  return { command: "npx", args: ["-y", MCP_PACKAGE], env: e };
+}
+async function readWiredServer(baseDir = process.cwd()) {
+  const { json } = await readMcpJson(resolve3(baseDir, MCP_JSON_FILENAME));
+  const servers = json.mcpServers;
+  if (!servers || typeof servers !== "object") return null;
+  const block = servers[MCP_SERVER_KEY];
+  if (!block || typeof block !== "object") return null;
+  return block;
+}
+async function readMcpJson(path) {
+  try {
+    const raw = await fs4.readFile(path, "utf8");
+    const trimmed = raw.trim();
+    if (!trimmed) return { json: {}, existed: true };
+    const parsed = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${MCP_JSON_FILENAME} is not a JSON object`);
+    }
+    return { json: parsed, existed: true };
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return { json: {}, existed: false };
+    }
+    throw err;
+  }
+}
+async function wireMcpServer(env, opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const path = resolve3(baseDir, MCP_JSON_FILENAME);
+  const { json, existed } = await readMcpJson(path);
+  const embeddedKey = Boolean(opts.embedKey && env.apiKey);
+  const block = buildServerBlock(env, { embedKey: opts.embedKey });
+  const servers = json.mcpServers && typeof json.mcpServers === "object" ? json.mcpServers : {};
+  const prior = servers[MCP_SERVER_KEY];
+  const identical = prior !== void 0 && deepEqual(prior, block);
+  servers[MCP_SERVER_KEY] = block;
+  json.mcpServers = servers;
+  const action = !existed ? "created" : identical ? "unchanged" : "updated";
+  if (action !== "unchanged") {
+    await fs4.writeFile(path, JSON.stringify(json, null, 2) + "\n", "utf8");
+  }
+  let gitignoreUpdated = false;
+  const wantGitignore = opts.gitignore ?? embeddedKey;
+  if (wantGitignore) {
+    gitignoreUpdated = await ensureGitignored(baseDir, MCP_JSON_FILENAME);
+  }
+  return { path, action, serverKey: MCP_SERVER_KEY, gitignoreUpdated, embeddedKey };
+}
+async function ensureGitignored(baseDir, entry) {
+  const path = resolve3(baseDir, ".gitignore");
+  let current = "";
+  try {
+    current = await fs4.readFile(path, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+  }
+  const already = current.split(/\r?\n/).map((l) => l.trim()).some((l) => l === entry || l === `/${entry}`);
+  if (already) return false;
+  const prefix = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  const header = current.length === 0 ? "" : "\n# Sonenta MCP server config (contains an API key)\n";
+  await fs4.writeFile(path, `${current}${prefix}${header}${entry}
+`, "utf8");
+  return true;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  return ak.every(
+    (k) => deepEqual(a[k], b[k])
+  );
+}
+
+// src/doctor.ts
+var CANON_HOST = "https://api.sonenta.dev";
+var KEYS_HINT = "create one in the dashboard \u2192 Org Settings \u2192 API Keys (scope mcp:*), then run `sonenta login`";
+function hasMcpScope(scopes) {
+  if (!scopes) return false;
+  return scopes.some((s) => s === "*" || s === "mcp:*" || s.startsWith("mcp:"));
+}
+async function probe(fetchImpl, host, apiKey, path) {
+  const url = `${host.replace(/\/+$/, "")}${path}`;
+  try {
+    const res = await fetchImpl(url, { headers: { Authorization: `ApiKey ${apiKey}` } });
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      json = void 0;
+    }
+    return { status: res.status, ok: res.ok, json };
+  } catch (e) {
+    return { status: 0, ok: false, networkError: e.message };
+  }
+}
+async function runDoctor(opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const dir = opts.dir ?? process.cwd();
+  const checks = [];
+  const { path: cfgPath, config } = await readConfig(dir).catch(() => ({
+    path: null,
+    config: {}
+  }));
+  checks.push({
+    id: "config",
+    title: "Project config",
+    status: cfgPath ? "pass" : "warn",
+    detail: cfgPath ? `sonenta.config.json found${config.project_uuid ? ` (project ${config.project_uuid})` : ""}` : "no sonenta.config.json in this directory",
+    fix: cfgPath ? void 0 : "run `sonenta init --project <uuid>` to scaffold it and bind a project"
+  });
+  let ctx = null;
+  try {
+    ctx = await resolveContext({ hostOverride: opts.hostOverride, cwd: dir });
+    checks.push({
+      id: "login",
+      title: "Login",
+      status: "pass",
+      detail: `credentials resolved for ${ctx.host}`
+    });
+  } catch (e) {
+    checks.push({
+      id: "login",
+      title: "Login",
+      status: "fail",
+      detail: e.message,
+      fix: `run \`sonenta login --host ${opts.hostOverride ?? CANON_HOST}\``
+    });
+  }
+  const wired = await readWiredServer(dir).catch(() => null);
+  checks.push({
+    id: "mcp_wired",
+    title: "MCP server wired",
+    status: wired ? "pass" : "fail",
+    detail: wired ? `.mcp.json declares the "sonenta" server (${MCP_PACKAGE})` : 'no "sonenta" server in .mcp.json',
+    fix: wired ? void 0 : "run `sonenta agents add <name>` (or `sonenta init`) to wire it, then reload your Claude session"
+  });
+  if (!ctx) {
+    return finalize(checks);
+  }
+  const me = await probe(fetchImpl, ctx.host, ctx.apiKey, "/v1/me");
+  if (me.networkError) {
+    checks.push({
+      id: "api",
+      title: "API reachable",
+      status: "fail",
+      detail: `could not reach ${ctx.host}: ${me.networkError}`,
+      fix: `check your connection and the host \u2014 the canonical host is ${CANON_HOST} (\`sonenta login --host ${CANON_HOST}\`)`
+    });
+    return finalize(checks);
+  }
+  if (me.status === 404) {
+    checks.push({
+      id: "api",
+      title: "API reachable",
+      status: "fail",
+      detail: `${ctx.host} returned 404 for /v1/me \u2014 almost certainly the wrong host`,
+      fix: `use the canonical host: \`sonenta login --host ${CANON_HOST}\``
+    });
+    return finalize(checks);
+  }
+  if (me.status === 401) {
+    checks.push({
+      id: "api",
+      title: "API key valid",
+      status: "fail",
+      detail: "the API returned 401 \u2014 your key is invalid or revoked",
+      fix: `run \`sonenta login\` with a current key (${KEYS_HINT})`
+    });
+    return finalize(checks);
+  }
+  if (!me.ok) {
+    checks.push({
+      id: "api",
+      title: "API reachable",
+      status: "fail",
+      detail: `unexpected ${me.status} from ${ctx.host}/v1/me`,
+      fix: `verify the host (${CANON_HOST}) and try again`
+    });
+    return finalize(checks);
+  }
+  checks.push({
+    id: "api",
+    title: "API reachable",
+    status: "pass",
+    detail: `${ctx.host} responded 200 to /v1/me`
+  });
+  const accountActive = me.json?.account_active !== false;
+  if (!accountActive) {
+    checks.push({
+      id: "account",
+      title: "Account active",
+      status: "fail",
+      detail: "your account/subscription is inactive",
+      fix: "reactivate your subscription in the Sonenta dashboard"
+    });
+  } else {
+    checks.push({ id: "account", title: "Account active", status: "pass", detail: "account active" });
+  }
+  const scopes = Array.isArray(me.json?.scopes) ? me.json.scopes : void 0;
+  const mcpOk = hasMcpScope(scopes);
+  checks.push({
+    id: "mcp_scope",
+    title: "Key has mcp:* scope",
+    status: mcpOk ? "pass" : "fail",
+    detail: mcpOk ? "the key carries the mcp:* scope" : `the key lacks the mcp:* scope${scopes ? ` (has: ${scopes.join(", ") || "none"})` : ""}`,
+    fix: mcpOk ? void 0 : `the agents drive the MCP tools, which need an mcp:* key \u2014 ${KEYS_HINT}`
+  });
+  if (!ctx.projectUuid) {
+    checks.push({
+      id: "a11y",
+      title: "a11y tools respond",
+      status: "skip",
+      detail: "no project bound, so the per-project a11y surface can't be probed",
+      fix: "bind a project: `sonenta init --project <uuid>`"
+    });
+    return finalize(checks);
+  }
+  const surf = await probe(
+    fetchImpl,
+    ctx.host,
+    ctx.apiKey,
+    `/v1/mcp/projects/${ctx.projectUuid}/surfaces`
+  );
+  if (surf.ok) {
+    checks.push({
+      id: "a11y",
+      title: "a11y tools respond",
+      status: "pass",
+      detail: "the project's a11y/surface MCP endpoint responded"
+    });
+  } else if (surf.status === 403) {
+    const detail = surf.json?.detail ?? surf.json;
+    const isMissingScope = detail?.code === "MISSING_SCOPE";
+    const howTo = typeof detail?.how_to_get === "string" ? detail.how_to_get : void 0;
+    const msg = typeof detail?.message === "string" ? detail.message : void 0;
+    checks.push({
+      id: "a11y",
+      title: "a11y tools respond",
+      status: "fail",
+      detail: isMissingScope ? `the a11y MCP surface returned 403: this key lacks the ${detail?.required_scope ?? "mcp:*"} scope for this project` : "the a11y MCP surface returned 403 \u2014 the key can't act on this project",
+      fix: msg ?? (howTo ? `get a scoped key: ${howTo}` : `the key needs the mcp:* scope for this project \u2014 ${KEYS_HINT}`)
+    });
+  } else if (surf.status === 404) {
+    checks.push({
+      id: "a11y",
+      title: "a11y tools respond",
+      status: "fail",
+      detail: `project ${ctx.projectUuid} not found on ${ctx.host} (404)`,
+      fix: "check project_uuid in sonenta.config.json and the host (`sonenta init --project <uuid>`)"
+    });
+  } else {
+    checks.push({
+      id: "a11y",
+      title: "a11y tools respond",
+      status: "fail",
+      detail: surf.networkError ? `could not reach the a11y surface: ${surf.networkError}` : `unexpected ${surf.status} from the a11y MCP surface`,
+      fix: `verify the host (${CANON_HOST}) and that the project is reachable`
+    });
+  }
+  return finalize(checks);
+}
+function finalize(checks) {
+  return { checks, ok: !checks.some((c) => c.status === "fail") };
+}
+
+// src/commands/doctor.ts
+import { Command } from "commander";
+var MARK = {
+  pass: "\u2713",
+  fail: "\u2717",
+  warn: "!",
+  skip: "\xB7"
+};
+function formatReport(report) {
+  const lines = ["sonenta doctor \u2014 agent preflight", ""];
+  const width = Math.max(...report.checks.map((c) => c.title.length));
+  for (const c of report.checks) {
+    lines.push(`${MARK[c.status]} ${c.title.padEnd(width)}  ${c.detail}`);
+    if (c.fix && (c.status === "fail" || c.status === "warn" || c.status === "skip")) {
+      lines.push(`${" ".repeat(width + 4)}\u2192 Fix: ${c.fix}`);
+    }
+  }
+  lines.push("");
+  if (report.ok) {
+    lines.push(
+      "All checks passed. If your agent still shows no tools, reload your Claude Code session \u2014 the MCP server connects at session start."
+    );
+  } else {
+    const failed = report.checks.filter((c) => c.status === "fail").length;
+    lines.push(
+      `${failed} check${failed === 1 ? "" : "s"} failed \u2014 fix the step(s) above, then re-run \`sonenta doctor\`.`
+    );
+  }
+  return lines;
+}
+var doctorCommand = new Command("doctor").description(
+  "Preflight the agent setup: verifies the @sonenta/mcp server is wired + reachable, the key has the mcp:* scope, and the project's a11y tools respond \u2014 with an exact fix for anything that's off."
+).option("--dir <path>", "Project directory (default: current directory)").option("--host <url>", "Override host (otherwise from config/credentials)").action(async (opts) => {
+  const report = await runDoctor({ dir: opts.dir, hostOverride: opts.host });
+  for (const line of formatReport(report)) console.log(line);
+  if (!report.ok) process.exit(1);
+});
+
 // src/commands/agents.ts
-var agentsCommand = new Command("agents").description("Install bundled Claude agents (e.g. sonenta-a11y) into .claude/agents/.").addCommand(
-  new Command("list").description("List the bundled agents available to install.").option("--dir <path>", "Project directory (default: current directory)").action(async (opts) => {
+var agentsCommand = new Command2("agents").description("Install bundled Claude agents (e.g. sonenta-a11y) into .claude/agents/.").addCommand(
+  new Command2("list").description("List the bundled agents available to install.").option("--dir <path>", "Project directory (default: current directory)").action(async (opts) => {
     const baseDir = opts.dir;
     const agents = listAgents();
     console.log(`Available agents (${agents.length}):`);
@@ -1122,22 +1567,60 @@ var agentsCommand = new Command("agents").description("Install bundled Claude ag
 Install with: sonenta agents add <name>`);
   })
 ).addCommand(
-  new Command("add").description("Write a bundled agent definition into <dir>/.claude/agents/<name>.md.").argument("<name>", "Agent name (e.g. sonenta-a11y)").option("--dir <path>", "Project directory (default: current directory)").option("--host <url>", "Override host (otherwise from config/credentials)").option("--force", "Overwrite an existing agent definition", false).action(async (name, opts) => {
-    await requireAuth({ hostOverride: opts.host });
-    const path = await writeAgent(name, { baseDir: opts.dir, force: opts.force });
-    console.log(`Wrote ${path}`);
-    console.log(
-      `
-The ${name} agent drives the Sonenta a11y MCP tools. Make sure the Sonenta MCP server is configured (npx -y @sonenta/mcp) with an mcp:* SONENTA_API_KEY, then use the agent in Claude Code or CI.`
-    );
-    console.log(`Agent dir: ${AGENTS_DIR}/`);
-  })
+  new Command2("add").description("Write a bundled agent definition into <dir>/.claude/agents/<name>.md.").argument("<name>", "Agent name (e.g. sonenta-a11y)").option("--dir <path>", "Project directory (default: current directory)").option("--host <url>", "Override host (otherwise from config/credentials)").option("--force", "Overwrite an existing agent definition", false).option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
+    "--embed-key",
+    "Bake the API key into .mcp.json (for CI / no-login); otherwise the server reads it from ~/.sonenta",
+    false
+  ).action(
+    async (name, opts) => {
+      const ctx = await requireAuth({ hostOverride: opts.host });
+      const path = await writeAgent(name, { baseDir: opts.dir, force: opts.force });
+      console.log(`Wrote ${path}`);
+      if (opts.mcp) {
+        const wired = await wireMcpServer(
+          { apiKey: ctx.apiKey, host: ctx.host, projectUuid: ctx.projectUuid },
+          { baseDir: opts.dir, embedKey: opts.embedKey }
+        );
+        const verb = wired.action === "created" ? "Created" : wired.action === "updated" ? "Updated" : "Verified";
+        console.log(
+          `${verb} ${MCP_JSON_FILENAME} \u2192 connected the "${wired.serverKey}" server (${"npx -y @sonenta/mcp"}, host ${ctx.host}${ctx.projectUuid ? `, project ${ctx.projectUuid}` : ""}).`
+        );
+        if (wired.embeddedKey) {
+          console.log(
+            `Embedded your API key in ${MCP_JSON_FILENAME}` + (wired.gitignoreUpdated ? " and added it to .gitignore" : "") + " \u2014 keep it out of git."
+          );
+        } else {
+          console.log(
+            `No secret stored in ${MCP_JSON_FILENAME} \u2014 the server reads your API key from ~/.sonenta at startup (run \`sonenta login\` if it can't). Safe to commit.`
+          );
+        }
+        if (!ctx.projectUuid) {
+          console.log(
+            "Note: no project bound \u2014 run `sonenta init --project <uuid>` so the agent's tools default to one project (or pass project_uuid per call)."
+          );
+        }
+        console.log(
+          `
+\u27F3 Reload your Claude Code session (or restart the MCP client) so the "${wired.serverKey}" server connects \u2014 then ${name}'s tools are available.`
+        );
+      } else {
+        console.log(
+          `
+Skipped .mcp.json (--no-mcp). The ${name} agent needs the Sonenta MCP server (npx -y @sonenta/mcp) with an mcp:* SONENTA_API_KEY to have any tools.`
+        );
+      }
+      console.log(`Agent dir: ${AGENTS_DIR}/`);
+      console.log("");
+      const report = await runDoctor({ dir: opts.dir, hostOverride: opts.host });
+      for (const line of formatReport(report)) console.log(line);
+    }
+  )
 );
 
 // src/commands/export.ts
-import { promises as fs4 } from "fs";
+import { promises as fs5 } from "fs";
 import { join as join2 } from "path";
-import { Command as Command2 } from "commander";
+import { Command as Command3 } from "commander";
 
 // src/i18next_tree.ts
 function unflatten(flat, sep = ".") {
@@ -1262,7 +1745,7 @@ async function collect(ctx, languages, namespace) {
   }
   return out;
 }
-var exportCommand = new Command2("export").description(
+var exportCommand = new Command3("export").description(
   "Export Verbumia translations as i18next JSON. Flat dot-notation by default (--nested for nested trees). Writes <out>/<lang>/<namespace>.json with --out, otherwise prints { locale: { namespace: tree } } to stdout."
 ).option("--language <code>", "Restrict to a single language code").option("--namespace <slug>", "Restrict to a single namespace slug").option("--nested", "Emit nested JSON instead of flat dot-notation", false).option("--out <dir>", "Write files instead of printing to stdout").option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (opts) => {
@@ -1275,9 +1758,9 @@ var exportCommand = new Command2("export").description(
       for (const [lang, nss] of Object.entries(collected)) {
         for (const [ns, flat] of Object.entries(nss)) {
           const dir = join2(opts.out, lang);
-          await fs4.mkdir(dir, { recursive: true });
+          await fs5.mkdir(dir, { recursive: true });
           const p = join2(dir, `${ns}.json`);
-          await fs4.writeFile(p, JSON.stringify(shape(flat), null, 2) + "\n", "utf8");
+          await fs5.writeFile(p, JSON.stringify(shape(flat), null, 2) + "\n", "utf8");
           console.log(`  ${p}  ${Object.keys(flat).length} keys`);
           files++;
         }
@@ -1295,9 +1778,9 @@ var exportCommand = new Command2("export").description(
 );
 
 // src/commands/import.ts
-import { promises as fs5 } from "fs";
+import { promises as fs6 } from "fs";
 import { basename, dirname as dirname3 } from "path";
-import { Command as Command3 } from "commander";
+import { Command as Command4 } from "commander";
 function resolveLangNs(filePath, optLang, optNs) {
   const stem = basename(filePath).replace(/\.json$/i, "");
   const parent = basename(dirname3(filePath));
@@ -1313,7 +1796,7 @@ function resolveLangNs(filePath, optLang, optNs) {
   return { lang, ns };
 }
 async function readTree(filePath) {
-  const parsed = JSON.parse(await fs5.readFile(filePath, "utf8"));
+  const parsed = JSON.parse(await fs6.readFile(filePath, "utf8"));
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${filePath} is not a JSON object`);
   }
@@ -1327,7 +1810,7 @@ function countLeaves(tree) {
   }
   return n;
 }
-var importCommand = new Command3("import").description(
+var importCommand = new Command4("import").description(
   "Import i18next JSON file(s) into Verbumia in ONE call \u2014 creates missing keys and upserts translations (idempotent). Accepts nested or flat JSON. Language/namespace are inferred from the path (<lang>/<namespace>.json) or forced with --language / --namespace."
 ).argument("<files...>", "i18next JSON file(s), e.g. locales/fr/common.json or fr.json").option("--language <code>", "Force the language code for every file").option("--namespace <slug>", "Force the namespace slug for every file").option("--status <status>", "draft | translated (default: translated)").option("--version <slug>", "Target version slug (default: production version)").option("--dry-run", "Print what would be imported without sending", false).option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (files, opts) => {
@@ -1370,13 +1853,13 @@ var importCommand = new Command3("import").description(
 
 // src/commands/init.ts
 import { existsSync } from "fs";
-import { resolve as resolve4 } from "path";
-import { Command as Command4 } from "commander";
+import { resolve as resolve5 } from "path";
+import { Command as Command5 } from "commander";
 
 // src/repodoc.ts
-import { promises as fs6 } from "fs";
-import { resolve as resolve3 } from "path";
-var DOC_API_HOST = "https://api.sonenta.com";
+import { promises as fs7 } from "fs";
+import { resolve as resolve4 } from "path";
+var DOC_API_HOST = "https://api.sonenta.dev";
 var DOC_CDN_HOST = "https://cdn.sonenta.com";
 var REPO_DOC_FILES = ["CLAUDE.md", "AGENTS.md"];
 var BLOCK_BEGIN = "<!-- SONENTA:BEGIN \u2014 managed by `sonenta init`; edits between these markers are overwritten -->";
@@ -1464,13 +1947,13 @@ function renderManagedBlock(d) {
 async function upsertManagedBlock(filePath, block) {
   let existing = null;
   try {
-    existing = await fs6.readFile(filePath, "utf8");
+    existing = await fs7.readFile(filePath, "utf8");
   } catch {
     existing = null;
   }
   const normalizedBlock = block.endsWith("\n") ? block : block + "\n";
   if (existing === null) {
-    await fs6.writeFile(filePath, normalizedBlock, "utf8");
+    await fs7.writeFile(filePath, normalizedBlock, "utf8");
     return "created";
   }
   const begin = existing.indexOf(BLOCK_BEGIN);
@@ -1479,18 +1962,18 @@ async function upsertManagedBlock(filePath, block) {
     const before = existing.slice(0, begin);
     const after = existing.slice(end + BLOCK_END.length);
     const blockCore = block.slice(0, block.indexOf(BLOCK_END) + BLOCK_END.length);
-    await fs6.writeFile(filePath, before + blockCore + after, "utf8");
+    await fs7.writeFile(filePath, before + blockCore + after, "utf8");
     return "updated";
   }
   const sep = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  await fs6.writeFile(filePath, existing + sep + normalizedBlock, "utf8");
+  await fs7.writeFile(filePath, existing + sep + normalizedBlock, "utf8");
   return "inserted";
 }
 async function writeRepoDocs(dir, data) {
   const block = renderManagedBlock(data);
   const results = [];
   for (const file of REPO_DOC_FILES) {
-    const path = resolve3(dir, file);
+    const path = resolve4(dir, file);
     const action = await upsertManagedBlock(path, block);
     results.push({ file, path, action });
   }
@@ -1498,7 +1981,7 @@ async function writeRepoDocs(dir, data) {
 }
 
 // src/commands/init.ts
-var DEFAULT_HOST = "https://api.sonenta.com";
+var DEFAULT_HOST = "https://api.sonenta.dev";
 var ACTION_LABEL = {
   created: "Created",
   updated: "Updated",
@@ -1537,11 +2020,15 @@ async function gatherRepoDocData(opts) {
     };
   }
 }
-var initCommand = new Command4("init").description(
+var initCommand = new Command5("init").description(
   "Scaffold sonenta.config.json AND write a managed Sonenta block into CLAUDE.md / AGENTS.md so coding agents know how this repo uses Sonenta."
-).option("--host <url>", "API base URL", DEFAULT_HOST).option("--project <uuid>", "Project UUID").option("--version <slug>", "Version slug (default: main)", "main").option("--force", "Overwrite an existing sonenta.config.json", false).option("--no-repo-doc", "Skip writing the managed block into CLAUDE.md / AGENTS.md").action(
+).option("--host <url>", "API base URL", DEFAULT_HOST).option("--project <uuid>", "Project UUID").option("--version <slug>", "Version slug (default: main)", "main").option("--force", "Overwrite an existing sonenta.config.json", false).option("--no-repo-doc", "Skip writing the managed block into CLAUDE.md / AGENTS.md").option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
+  "--embed-key",
+  "Bake the API key into .mcp.json (for CI / no-login); otherwise the server reads it from ~/.sonenta",
+  false
+).action(
   async (opts) => {
-    const path = resolve4(process.cwd(), CONFIG_FILENAME);
+    const path = resolve5(process.cwd(), CONFIG_FILENAME);
     if (existsSync(path) && !opts.force) {
       console.error(
         `${CONFIG_FILENAME} already exists at ${path}. Pass --force to overwrite.`
@@ -1568,6 +2055,50 @@ var initCommand = new Command4("init").description(
     } else {
       console.log("Skipped CLAUDE.md / AGENTS.md (--no-repo-doc).");
     }
+    if (opts.mcp) {
+      let liveHost = opts.host !== DEFAULT_HOST ? opts.host : void 0;
+      if (!liveHost) {
+        const creds = await readCredentials().catch(() => null);
+        liveHost = creds?.default ?? void 0;
+      }
+      let resolved = null;
+      try {
+        const ctx = await resolveContext({ hostOverride: liveHost });
+        resolved = { apiKey: ctx.apiKey, host: ctx.host, projectUuid: ctx.projectUuid };
+      } catch {
+        resolved = opts.embedKey ? null : { host: liveHost ?? opts.host, projectUuid: opts.project };
+      }
+      if (resolved) {
+        const wired = await wireMcpServer(
+          {
+            apiKey: resolved.apiKey,
+            host: resolved.host,
+            projectUuid: resolved.projectUuid ?? opts.project
+          },
+          { embedKey: opts.embedKey }
+        );
+        const verb = wired.action === "created" ? "Created" : wired.action === "updated" ? "Updated" : "Verified";
+        console.log(
+          `${verb} ${MCP_JSON_FILENAME} \u2192 connected the "${wired.serverKey}" server (npx -y @sonenta/mcp${resolved.host ? `, host ${resolved.host}` : ""}).`
+        );
+        if (wired.embeddedKey) {
+          console.log(
+            `Embedded your API key in ${MCP_JSON_FILENAME}` + (wired.gitignoreUpdated ? " and added it to .gitignore" : "") + " \u2014 keep it out of git."
+          );
+        } else {
+          console.log(
+            `No secret stored in ${MCP_JSON_FILENAME} \u2014 the server reads your API key from ~/.sonenta at startup (run \`sonenta login\` if it can't). Safe to commit.`
+          );
+        }
+        console.log(
+          `\u27F3 Reload your Claude Code session so the "${wired.serverKey}" server connects.`
+        );
+      } else {
+        console.log(
+          `Note: skipped ${MCP_JSON_FILENAME} wiring (--embed-key needs a login). Run \`sonenta login\` then \`sonenta agents add <name>\`.`
+        );
+      }
+    }
     if (!opts.project) {
       console.log(
         "Tip: pass --project <uuid> to bind this directory to a specific project (or edit project_uuid in the file later), then re-run `sonenta init --force`."
@@ -1577,9 +2108,9 @@ var initCommand = new Command4("init").description(
 );
 
 // src/commands/keys.ts
-import { Command as Command5 } from "commander";
-var keysCommand = new Command5("keys").description("Inspect translation keys for the current project.").addCommand(
-  new Command5("list").description("List keys for the configured project (addressed by namespace slug + key name).").option("--namespace <slug>", "Filter by namespace slug").option("--host <url>", "Override host (otherwise from config/credentials)").action(async (opts) => {
+import { Command as Command6 } from "commander";
+var keysCommand = new Command6("keys").description("Inspect translation keys for the current project.").addCommand(
+  new Command6("list").description("List keys for the configured project (addressed by namespace slug + key name).").option("--namespace <slug>", "Filter by namespace slug").option("--host <url>", "Override host (otherwise from config/credentials)").action(async (opts) => {
     const ctx = await requireAuth({ hostOverride: opts.host });
     const items = await listKeys(ctx, { namespace: opts.namespace });
     console.log(`total: ${items.length}`);
@@ -1588,7 +2119,7 @@ var keysCommand = new Command5("keys").description("Inspect translation keys for
 );
 
 // src/commands/login.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/prompt.ts
 import { createInterface } from "readline";
@@ -1596,8 +2127,8 @@ async function promptLine(message) {
   if (!process.stdin.isTTY) return "";
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return await new Promise((resolve6) => {
-      rl.question(message, (answer) => resolve6(answer.trim()));
+    return await new Promise((resolve7) => {
+      rl.question(message, (answer) => resolve7(answer.trim()));
     });
   } finally {
     rl.close();
@@ -1613,7 +2144,7 @@ async function promptSecret(message) {
   process.stdout.write(message);
   process.stdin.setRawMode(true);
   process.stdin.resume();
-  return await new Promise((resolve6) => {
+  return await new Promise((resolve7) => {
     let buffer = "";
     const onData = (chunk) => {
       for (const byte of chunk) {
@@ -1622,7 +2153,7 @@ async function promptSecret(message) {
           process.stdin.removeListener("data", onData);
           process.stdin.setRawMode(false);
           process.stdin.pause();
-          resolve6(buffer);
+          resolve7(buffer);
           return;
         }
         if (byte === CTRL_C) {
@@ -1649,12 +2180,12 @@ async function promptSecret(message) {
 
 // src/commands/login.ts
 var TOKEN_REGEX = /^vrb_[a-z]+_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
-var loginCommand = new Command6("login").description(
+var loginCommand = new Command7("login").description(
   "Store an API key for a host. Token resolution order: --token, SONENTA_TOKEN env, then interactive prompt (TTY only)."
-).option("--host <url>", "API base URL", "https://api.sonenta.com").option("--token <vrb_live_\u2026>", "API key token (prefix.secret form)").option("--email <email>", "User email associated with the token (optional)").option("--default", "Set this host as the default for future commands", false).action(async (opts) => {
+).option("--host <url>", "API base URL", "https://api.sonenta.dev").option("--token <vrb_live_\u2026>", "API key token (prefix.secret form)").option("--email <email>", "User email associated with the token (optional)").option("--default", "Set this host as the default for future commands", false).action(async (opts) => {
   let host = opts.host;
   if (!host && process.stdin.isTTY) {
-    host = await promptLine("Host (default https://api.sonenta.com): ") || "https://api.sonenta.com";
+    host = await promptLine("Host (default https://api.sonenta.dev): ") || "https://api.sonenta.dev";
   }
   let token = opts.token ?? (process.env.SONENTA_TOKEN ?? process.env.VERBUMIA_TOKEN) ?? "";
   if (!token && process.stdin.isTTY) {
@@ -1700,8 +2231,8 @@ var loginCommand = new Command6("login").description(
 });
 
 // src/commands/logout.ts
-import { Command as Command7 } from "commander";
-var logoutCommand = new Command7("logout").description("Remove stored credentials for a host (default: the current default host).").option("--host <url>", "Host to forget. Omit to forget the current default.").action(async (opts) => {
+import { Command as Command8 } from "commander";
+var logoutCommand = new Command8("logout").description("Remove stored credentials for a host (default: the current default host).").option("--host <url>", "Host to forget. Omit to forget the current default.").action(async (opts) => {
   const creds = await readCredentials();
   const target = opts.host ?? creds.default;
   if (!target) {
@@ -1717,8 +2248,8 @@ var logoutCommand = new Command7("logout").description("Remove stored credential
 });
 
 // src/commands/missing.ts
-import { Command as Command8 } from "commander";
-var missingCommand = new Command8("missing").description(
+import { Command as Command9 } from "commander";
+var missingCommand = new Command9("missing").description(
   "List runtime-detected missing keys for the configured project. Requires the API key to carry the `mcp:*` scope."
 ).option("--namespace <slug>", "Filter by namespace slug").option("--language <code>", "Filter by language code").option("--status <state>", "Filter by status (open|resolved|...)").option("--limit <n>", "Page size (1-200, default 50)", "50").option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (opts) => {
@@ -1752,9 +2283,9 @@ var missingCommand = new Command8("missing").description(
 );
 
 // src/commands/projects.ts
-import { Command as Command9 } from "commander";
-var projectsCommand = new Command9("projects").description("Inspect Verbumia projects accessible to your API key.").addCommand(
-  new Command9("list").description("List the projects this API key can reach.").option("--host <url>", "Override host (otherwise from config/credentials)").action(async (opts) => {
+import { Command as Command10 } from "commander";
+var projectsCommand = new Command10("projects").description("Inspect Verbumia projects accessible to your API key.").addCommand(
+  new Command10("list").description("List the projects this API key can reach.").option("--host <url>", "Override host (otherwise from config/credentials)").action(async (opts) => {
     const ctx = await requireAuth({ hostOverride: opts.host });
     const items = await listProjects(ctx);
     if (items.length === 0) {
@@ -1770,17 +2301,17 @@ var projectsCommand = new Command9("projects").description("Inspect Verbumia pro
 );
 
 // src/commands/pull.ts
-import { Command as Command10 } from "commander";
+import { Command as Command11 } from "commander";
 
 // src/locales.ts
-import { promises as fs7 } from "fs";
-import { join as join3, resolve as resolve5 } from "path";
+import { promises as fs8 } from "fs";
+import { join as join3, resolve as resolve6 } from "path";
 var DEFAULT_LOCALES_DIR = "locales";
 async function listLocaleFiles(rootDir) {
-  const root = resolve5(rootDir);
+  const root = resolve6(rootDir);
   let langDirs;
   try {
-    langDirs = await fs7.readdir(root);
+    langDirs = await fs8.readdir(root);
   } catch {
     return [];
   }
@@ -1789,12 +2320,12 @@ async function listLocaleFiles(rootDir) {
     const langPath = join3(root, lang);
     let stat;
     try {
-      stat = await fs7.stat(langPath);
+      stat = await fs8.stat(langPath);
     } catch {
       continue;
     }
     if (!stat.isDirectory()) continue;
-    const files = await fs7.readdir(langPath);
+    const files = await fs8.readdir(langPath);
     for (const f of files) {
       if (!f.endsWith(".json")) continue;
       out.push({ lang, namespace: f.replace(/\.json$/, ""), path: join3(langPath, f) });
@@ -1803,7 +2334,7 @@ async function listLocaleFiles(rootDir) {
   return out;
 }
 async function readLocaleFile(path) {
-  const raw = await fs7.readFile(path, "utf8");
+  const raw = await fs8.readFile(path, "utf8");
   const parsed = JSON.parse(raw);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${path} is not a flat object`);
@@ -1819,12 +2350,12 @@ async function readLocaleFile(path) {
 }
 async function writeLocaleFile(rootDir, lang, namespace, values) {
   const dir = join3(rootDir, lang);
-  await fs7.mkdir(dir, { recursive: true });
+  await fs8.mkdir(dir, { recursive: true });
   const path = join3(dir, `${namespace}.json`);
   const sorted = Object.fromEntries(
     Object.entries(values).sort(([a], [b]) => a.localeCompare(b))
   );
-  await fs7.writeFile(path, JSON.stringify(sorted, null, 2) + "\n", "utf8");
+  await fs8.writeFile(path, JSON.stringify(sorted, null, 2) + "\n", "utf8");
   return path;
 }
 function diffFlat(local, remote) {
@@ -1848,7 +2379,7 @@ function diffFlat(local, remote) {
 }
 
 // src/commands/pull.ts
-var pullCommand = new Command10("pull").description(
+var pullCommand = new Command11("pull").description(
   "Pull translations from Verbumia into locales/<lang>/<namespace>.json (flat dot-notation). Overwrites local files \u2014 pair with `git status`."
 ).option("--language <code>", "Restrict to a single language code").option("--namespace <slug>", "Restrict to a single namespace slug").option("--dest <dir>", "Output directory", DEFAULT_LOCALES_DIR).option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (opts) => {
@@ -1887,8 +2418,8 @@ var pullCommand = new Command10("pull").description(
 );
 
 // src/commands/push.ts
-import { Command as Command11 } from "commander";
-var pushCommand = new Command11("push").description(
+import { Command as Command12 } from "commander";
+var pushCommand = new Command12("push").description(
   "Push the whole local locales/ tree to Verbumia in ONE import call \u2014 creates missing keys and upserts translations (idempotent). Reads locales/<lang>/<namespace>.json (flat dot-notation)."
 ).option("--language <code>", "Restrict to a single language code").option("--namespace <slug>", "Restrict to a single namespace slug").option("--src <dir>", "Locales directory", DEFAULT_LOCALES_DIR).option("--status <status>", "draft | translated (default: translated)").option("--version <slug>", "Target version slug (default: production version)").option("--dry-run", "Print what would be pushed without sending", false).option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (opts) => {
@@ -1935,9 +2466,9 @@ var pushCommand = new Command11("push").description(
 );
 
 // src/commands/releases.ts
-import { Command as Command12 } from "commander";
-var releasesCommand = new Command12("releases").description("Manage CDN releases for the project.").addCommand(
-  new Command12("publish").description(
+import { Command as Command13 } from "commander";
+var releasesCommand = new Command13("releases").description("Manage CDN releases for the project.").addCommand(
+  new Command13("publish").description(
     "Trigger a CDN release: build bundles for every (language, namespace) and push them to the public CDN. Idempotent \u2014 unchanged bundles are reused. Subscribed SDKs receive a live `translations_published` event."
   ).option("--language <code>", "Restrict to one language (default: all)").option("--namespace <slug>", "Restrict to one namespace (default: all)").option("--version <slug>", "Version slug (default: production version)").option("--dry-run", "Print the planned release without publishing", false).option("--host <url>", "Override host (otherwise from config/credentials)").action(
     async (opts) => {
@@ -1963,8 +2494,8 @@ var releasesCommand = new Command12("releases").description("Manage CDN releases
 );
 
 // src/commands/snapshot.ts
-import { promises as fs8 } from "fs";
-import { Command as Command13 } from "commander";
+import { promises as fs9 } from "fs";
+import { Command as Command14 } from "commander";
 function bundleUrl(cdnBase, project, version, lang, ns) {
   return `${cdnBase.replace(/\/+$/, "")}/p/${project}/${version}/latest/${lang}/${ns}.json`;
 }
@@ -1988,7 +2519,7 @@ async function fetchBundle(url) {
   if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
   return await res.json();
 }
-var snapshotCommand = new Command13("snapshot").description(
+var snapshotCommand = new Command14("snapshot").description(
   "Generate a build-time translations snapshot for @sonenta/react-i18next `initialBundles` (offline-first fallback). Fetches the PUBLIC CDN bundles (exactly what the SDK loads at runtime) and assembles Record<locale, Record<namespace, tree>>. Emits a .ts module (default) or .json."
 ).option("--language <code>", "Restrict to a single language code").option("--namespace <slug>", "Restrict to a single namespace slug").option("--version <slug>", "Version slug (default: the configured version_slug)").option("--format <fmt>", "ts | json (default: ts)", "ts").option("--cdn <base>", "CDN base URL", "https://cdn.sonenta.com").option("--out <file>", "Write to a file instead of stdout").option("--host <url>", "Override host (used to discover languages/namespaces)").action(
   async (opts) => {
@@ -2030,7 +2561,7 @@ var snapshotCommand = new Command13("snapshot").description(
       opts.format === "json" ? "json" : "ts"
     );
     if (opts.out) {
-      await fs8.writeFile(opts.out, output, "utf8");
+      await fs9.writeFile(opts.out, output, "utf8");
       console.log(
         `wrote ${opts.out}: ${fetched} bundle(s)` + (missing ? `, ${missing} not published (404)` : "")
       );
@@ -2042,8 +2573,8 @@ var snapshotCommand = new Command13("snapshot").description(
 );
 
 // src/commands/status.ts
-import { Command as Command14 } from "commander";
-var statusCommand = new Command14("status").description("Diff local locales/ against the remote project state.").option("--language <code>", "Restrict to one language code").option("--namespace <slug>", "Restrict to one namespace slug").option("--src <dir>", "Locales directory", DEFAULT_LOCALES_DIR).option("--host <url>", "Override host (otherwise from config/credentials)").action(
+import { Command as Command15 } from "commander";
+var statusCommand = new Command15("status").description("Diff local locales/ against the remote project state.").option("--language <code>", "Restrict to one language code").option("--namespace <slug>", "Restrict to one namespace slug").option("--src <dir>", "Locales directory", DEFAULT_LOCALES_DIR).option("--host <url>", "Override host (otherwise from config/credentials)").action(
   async (opts) => {
     const ctx = await requireAuth({ hostOverride: opts.host });
     const knownLangs = new Set((await getProjectInfo(ctx)).languages);
@@ -2101,8 +2632,8 @@ var statusCommand = new Command14("status").description("Diff local locales/ aga
 );
 
 // src/commands/whoami.ts
-import { Command as Command15 } from "commander";
-var whoamiCommand = new Command15("whoami").description("Show the configured default host + which API key is in use.").option("--host <url>", "Inspect a specific host instead of the default").action(async (opts) => {
+import { Command as Command16 } from "commander";
+var whoamiCommand = new Command16("whoami").description("Show the configured default host + which API key is in use.").option("--host <url>", "Inspect a specific host instead of the default").action(async (opts) => {
   const creds = await readCredentials();
   if (!creds.default && Object.keys(creds.hosts).length === 0) {
     console.log("Not logged in. Run `sonenta login --host <url> --token <\u2026>`.");
@@ -2130,8 +2661,8 @@ var whoamiCommand = new Command15("whoami").description("Show the configured def
 });
 
 // src/index.ts
-var program = new Command16();
-program.name("sonenta").description("CLI for Sonenta translation management.").version("0.7.1");
+var program = new Command17();
+program.name("sonenta").description("CLI for Sonenta translation management.").version(package_default.version);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(whoamiCommand);
@@ -2147,6 +2678,7 @@ program.addCommand(releasesCommand);
 program.addCommand(snapshotCommand);
 program.addCommand(missingCommand);
 program.addCommand(agentsCommand);
+program.addCommand(doctorCommand);
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : err);
   process.exit(1);