@sonenta/cli 0.17.0 → 0.19.0

package/dist/index.js

@@ -1,15 +1,99 @@
 #!/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.19.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";
 import { resolve } from "path";
 var AGENTS_DIR = ".claude/agents";
+var PREFLIGHT = `## Preflight \u2014 verify your tools FIRST (fail fast, don't guess)
+Before ANY work, confirm the Sonenta MCP tools are actually available to you in
+this session \u2014 make a SINGLE cheap read (e.g. \`get_project_info\` or the first
+read your task needs). Treat the result as a gate:
+- **Tools missing** (you don't see the Sonenta MCP tools in your toolset, or the
+  call errors with "tool not found" / a connection failure) \u2192 the \`@sonenta/mcp\`
+  server isn't connected. **STOP and say so**, e.g.: "I can't run \u2014 I need the
+  \`@sonenta/mcp\` server connected with an \`mcp:*\` API key. Fix it: run
+  \`sonenta agents add <name>\` (it wires \`.mcp.json\` and preflights), then
+  RELOAD this Claude session so the server connects. Run \`sonenta doctor\` to see
+  the exact missing piece \u2014 it checks the wiring, host, key scope, and tools and
+  prints the precise next step."
+- **Auth / scope error** (401 invalid key, or 403 \`MISSING_SCOPE\`) \u2192 the key is
+  missing or lacks \`mcp:*\`. STOP and relay the fix verbatim: a 403 carries
+  \`detail.how_to_get\` / \`detail.message\` (a ready-to-run command) \u2014 show it; or
+  point to \`sonenta doctor\`. Do NOT retry blindly.
+- **Tools respond** \u2192 proceed with the workflow below.
+NEVER probe arbitrary endpoints, guess tool names or URL paths, or hammer a
+failing call \u2014 one clear, actionable message beats a pile of 404s.
+
+`;
 var SONENTA_A11Y = `---
 name: sonenta-a11y
 description: Accessibility (a11y) auditor and fixer for Sonenta-managed i18n projects. Runs a complete code-aware WCAG 2.2 audit, then works like sonenta-source-health \u2014 it builds a remediation PLAN, presents it and reassures you, touches NOTHING until you accept, and only then executes the fixes (a11y variants in bulk, reversible drafts). Generates the alt/aria/screen-reader/plain-language text itself and computes real readability locally, at zero AI-credit cost; server-side AI is an explicit opt-in fallback. Also applies the remediation plans prepared + approved in the Sonenta dashboard, and produces formal WCAG conformance + EAA / EN 301 549 statements. Use interactively in Claude Code or headless in CI.
@@ -45,7 +129,7 @@ default: those bill Sonenta AI credits and exist only as an explicit fallback fo
 very large volumes or when the developer specifically asks for server-side
 generation.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the a11y tools are missing, tell the user to add the server
@@ -283,7 +367,7 @@ results with \`propose_translations_bulk\` as **drafts/proposed** \u2014 plain C
 translation by default; where such a path exists it BILLS Sonenta AI credits and
 is an explicit, estimate-first, opt-in fallback for very large volumes.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Everything goes through its tools \u2014 never call the HTTP API directly.
   If the tools are missing, tell the user to add the server
@@ -295,9 +379,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 +420,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 +459,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
@@ -369,7 +485,7 @@ narrate what you are about to do, and wait for a clear yes. Reassure: nothing yo
 propose is destructive until accepted, deletes are soft (trash, restorable), and
 every change is a reviewable draft.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server
@@ -394,6 +510,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 +577,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\`
@@ -544,7 +692,7 @@ Knowledge is human-owned. You **propose, then confirm before you overwrite**.
 - Everything you write is a reviewable change \u2014 present proposals as proposals,
   not as done deals.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server
@@ -705,7 +853,7 @@ There is no server-side AI in this agent.
   \`update_surface\` response \`affected_variants\` reports how many variants a
   toggle impacts \u2014 always state that blast radius before toggling.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server
@@ -843,12 +991,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": {
@@ -1119,6 +1267,14 @@ function buildServerBlock(env, opts = {}) {
   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");
@@ -1186,9 +1342,239 @@ function deepEqual(a, b) {
   );
 }
 
+// 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}):`);
@@ -1202,7 +1588,7 @@ 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).option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
+  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
@@ -1245,6 +1631,9 @@ Skipped .mcp.json (--no-mcp). The ${name} agent needs the Sonenta MCP server (np
         );
       }
       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);
     }
   )
 );
@@ -1252,7 +1641,7 @@ Skipped .mcp.json (--no-mcp). The ${name} agent needs the Sonenta MCP server (np
 // src/commands/export.ts
 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 = ".") {
@@ -1377,7 +1766,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) => {
@@ -1412,7 +1801,7 @@ var exportCommand = new Command2("export").description(
 // src/commands/import.ts
 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));
@@ -1442,7 +1831,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) => {
@@ -1486,7 +1875,7 @@ var importCommand = new Command3("import").description(
 // src/commands/init.ts
 import { existsSync } from "fs";
 import { resolve as resolve5 } from "path";
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/repodoc.ts
 import { promises as fs7 } from "fs";
@@ -1652,7 +2041,7 @@ 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").option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
   "--embed-key",
@@ -1740,9 +2129,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}`);
@@ -1751,7 +2140,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";
@@ -1812,7 +2201,7 @@ 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.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;
@@ -1863,8 +2252,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) {
@@ -1880,8 +2269,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) => {
@@ -1915,9 +2304,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) {
@@ -1933,7 +2322,7 @@ 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 fs8 } from "fs";
@@ -2011,7 +2400,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) => {
@@ -2050,8 +2439,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) => {
@@ -2098,9 +2487,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) => {
@@ -2127,7 +2516,7 @@ var releasesCommand = new Command12("releases").description("Manage CDN releases
 
 // src/commands/snapshot.ts
 import { promises as fs9 } from "fs";
-import { Command as Command13 } from "commander";
+import { Command as Command14 } from "commander";
 function bundleUrl(cdnBase, project, version, lang, ns) {
   return `${cdnBase.replace(/\/+$/, "")}/p/${project}/${version}/latest/${lang}/${ns}.json`;
 }
@@ -2151,7 +2540,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) => {
@@ -2205,8 +2594,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);
@@ -2264,8 +2653,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>`.");
@@ -2293,8 +2682,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);
@@ -2310,6 +2699,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);