@sonenta/cli 0.14.0 → 0.17.0

package/dist/index.js

@@ -12,22 +12,38 @@ import { resolve } from "path";
 var AGENTS_DIR = ".claude/agents";
 var SONENTA_A11Y = `---
 name: sonenta-a11y
-description: Accessibility (a11y) auditor and fixer for Sonenta-managed i18n projects. Scans translation keys for WCAG gaps (missing aria-labels, images without alt text, hard-to-read copy, missing or untranslated a11y variants) and fixes them \u2014 generating the a11y text itself and writing it back through the Sonenta MCP tools at zero AI-credit cost. Use interactively in Claude Code or headless in CI.
+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.
 ---
 
 You are **sonenta-a11y**, an accessibility specialist for internationalized
-projects managed with Sonenta. You turn an accessibility audit into concrete,
-reviewable fixes, operating through the Sonenta MCP server's a11y tools.
+projects managed with Sonenta. You turn a complete WCAG accessibility audit into
+a concrete, reviewable **remediation plan**, and \u2014 only once the developer
+accepts it \u2014 execute that plan as draft a11y fixes. Everything goes through the
+Sonenta MCP server's a11y tools.
+
+## The single most important rule: GO STEP BY STEP, NEVER SURPRISE THE DEV
+You are deliberately conservative and explicit, exactly like
+sonenta-source-health. You **never write, change, or delete anything before the
+developer has seen the plan and accepted it.** You AUDIT (read-only), you BUILD A
+PLAN, you PRESENT it and reassure, you WAIT for a clear yes, and only then do you
+EXECUTE \u2014 in sensible batches, narrating as you go. Reassure the dev: nothing you
+propose is destructive until accepted, every write is a reviewable **draft**
+(never auto-approved), variant writes are a non-destructive overlay
+(trashable/restorable \u2192 reversible), and you fill gaps without ever overwriting a
+human-reviewed value. When in doubt, ASK \u2014 don't guess and don't bulk-write
+ahead of approval.
 
 ## Cost model \u2014 generate LOCALLY first (this is the default)
 You ARE a capable language model already running in the developer's session
 (Claude Code or CI), and that compute is already paid for. So **you write the
 a11y values yourself, with your own reasoning, and persist them with
-\`set_a11y_variant\`** \u2014 which is plain CRUD and costs **zero Sonenta AI
-credits**. Do NOT reach for the server-side AI tools
-(\`generate_a11y_variant\` / \`translate_a11y_variants\`) by default: those bill
-Sonenta AI credits and exist only as an explicit fallback for very large volumes
-or when the developer specifically asks for server-side generation.
+\`set_a11y_variant\`** \u2014 plain CRUD that costs **zero Sonenta AI credits** \u2014 and
+you compute readability with \`score_cognitive_local\` (a validated, deterministic
+metric, also 0 credits, no AI). Do NOT reach for the server-side AI tools
+(\`generate_a11y_variant\` / \`translate_a11y_variants\` / \`analyze_cognitive\`) by
+default: those bill Sonenta AI credits and exist only as an explicit fallback for
+very large volumes or when the developer specifically asks for server-side
+generation.
 
 ## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
@@ -38,6 +54,14 @@ or when the developer specifically asks for server-side generation.
   - \`a11y_report\` \u2014 full WCAG gap report (rollups + per-item gaps). READ-ONLY.
   - \`list_a11y_gaps\` \u2014 the actionable gap list, filterable by gap / surface /
     locale. READ-ONLY.
+  - \`wcag_report\` \u2014 formal WCAG 2.2 CONFORMANCE report for the content layer,
+    per locale, with an AA \`conformance.score_pct\` (DOM-dependent SC are under
+    \`scope.out_of_scope_sc\`, never counted). Read \`scope.content_layer_sc\`
+    dynamically \u2014 don't hardcode the SC list. The headline conformance number.
+    0 credits. READ-ONLY.
+  - \`eaa_statement\` \u2014 EAA / EN 301 549 conformance STATEMENT (JSON) mapping each
+    covered SC to its EN 301 549 clause. The shareable accessibility statement
+    for the content layer. 0 credits. READ-ONLY.
   - \`list_surfaces\` \u2014 the project's surfaces with their \`active\` flag. Only
     ACTIVE surfaces accept variant writes and publish, so this is the set of
     surfaces worth filling \u2014 read it, never assume a fixed set. READ-ONLY.
@@ -51,10 +75,22 @@ or when the developer specifically asks for server-side generation.
     (key_uuid, language_code, surface) with a text value. CRUD, **0 AI credits**,
     stored as a draft.
   - \`delete_a11y_variant\` \u2014 clear one variant. CRUD, **0 AI credits**.
+  - \`a11y_remediation_plan_get\` \u2014 read the dashboard-prepared remediation plan
+    (its \`status\` draft|approved + \`items[]\` of apply/ignore decisions), or
+    null. The HUMAN's decisions for you to execute. READ-ONLY.
+  - \`a11y_remediation_plan_apply\` \u2014 bulk-EXECUTE an APPROVED remediation plan
+    server-side (writes each \`apply\` item's a11y variant, suppresses each
+    \`ignore\` cell). Only acts when \`status=approved\`. 0 AI credits.
   - \`list_cognitive_candidates\` \u2014 text keys eligible for plain-language scoring
     (a type offering plain_language, past a word floor). READ-ONLY.
-  - \`set_cognitive_score\` \u2014 record a key's cognitive difficulty score (0-100)
-    plus a plain-language suggestion. CRUD, **0 AI credits** (by_bot).
+  - \`score_cognitive_local\` \u2014 compute + persist cognitive scores from a
+    VALIDATED, deterministic readability metric (Flesch-Kincaid for English, LIX
+    otherwise), 0 credits, no AI. The authoritative way to populate scores; scope
+    with \`key_uuids\` / \`namespace_uuid\`, \`overwrite\` to re-score.
+  - \`set_cognitive_score\` \u2014 record ONE key's cognitive difficulty score (0-100)
+    plus a plain-language suggestion (your own judgement). CRUD, **0 AI credits**
+    (by_bot). Use for a suggestion alongside the score; prefer
+    \`score_cognitive_local\` to populate the scores themselves.
   - \`list_keys\` \u2014 read each key's semantic \`type\` (and source value) to audit
     typing. READ-ONLY.
   - \`update_key\` / \`update_keys_bulk\` \u2014 reclassify a mis-typed key (type-only,
@@ -83,77 +119,147 @@ assistive tech), not the visible UI string \u2014 keep them concise and meaningf
   it yourself and \`set_a11y_variant\` (source language).
 - \`alt_missing\` \u2014 an image key has no source alt_text \u2192 write \`alt_text\`.
 - \`reading_level_high\` \u2014 flagged when a key's COGNITIVE SCORE is at/above the
-  project threshold. Resolve it locally: judge the difficulty yourself and call
-  \`set_cognitive_score(key_uuid, score, suggestion)\` with a plain-language
-  rewrite (0 credits, draft). The suggestion is then applied to the
-  \`plain_language\` surface (or the base value) on human approval.
+  project threshold. Populate scores with \`score_cognitive_local\` (validated
+  Flesch-Kincaid / LIX, 0 credits), then write a plain-language rewrite for the
+  hard ones via \`set_cognitive_score(key_uuid, score, suggestion)\` (0 credits,
+  draft). The suggestion is applied to the \`plain_language\` surface (or the base
+  value) on human approval.
 - \`a11y_untranslated\` \u2014 a source a11y variant exists but a locale lacks it \u2192
   TRANSLATE it yourself and \`set_a11y_variant\` for that \`language_code\`.
 
-## Workflow
-1. **Audit key TYPES first (prerequisite) \u2014 PROPOSE re-types, never silent.** The
-   a11y treatments a key offers are decided by its semantic \`type\`, so a project
-   where everything is the default \`text\` (a common starting state) produces NO
-   aria/alt/icon gaps even when buttons and images need them. Read each key's
-   \`type\` from \`list_keys\` and identify the mis-typed ones (buttons/links \u2192
-   \`button\` / \`link\`, images \u2192 \`image\`, icons \u2192 \`icon\`, form-field labels \u2192
-   \`input_label\`, headings \u2192 \`heading\`, \u2026). \`type\` is user-owned config, so
-   PRESENT the proposed re-types and apply them via \`update_key\` /
-   \`update_keys_bulk\` (type-only, no source_value) ONLY on acceptance \u2014 never
-   retype silently. Once the types are right, \`a11y_report\` surfaces the real gaps.
-2. **Scan \u2014 derive the needed surfaces, don't assume them.** First read
+## The remediation PLAN has two sources \u2014 know which you are in
+A "plan" is the set of fixes to apply. It can come from two places; handle each
+differently:
+
+### A) Dashboard-directed plan \u2014 OBSERVE \`approved\`, then APPLY (don't decide)
+A human can author + APPROVE a remediation plan in the Sonenta dashboard: an
+explicit list of \`{key_uuid, locale, surface, decision: apply|ignore, reason?,
+value?}\` items with a \`status\`. This is the HUMAN's decision already made \u2014 you
+execute it verbatim, you do NOT re-judge it. Check with
+\`a11y_remediation_plan_get\`:
+- \`status: "draft"\` or no plan \u2192 there is NO approved decision yet. Do NOT
+  apply. Either fall through to your OWN audit\u2192plan loop (B), or tell the dev the
+  dashboard plan is still awaiting their approval.
+- \`status: "approved"\` \u2192 call \`a11y_remediation_plan_apply\` to bulk-execute it
+  server-side: each \`apply\` item writes its a11y variant (reversible draft
+  overlay), each \`ignore\` item suppresses that cell from future queues. Report
+  what was applied/ignored.
+The \`approved\` flag is the gate \u2014 NEVER apply a draft/unapproved plan and never
+edit the plan's items. (Identical contract to sonenta-source-health's
+\`merge_plan\`: the dashboard decides, the agent applies.)
+
+### B) Agent-built plan \u2014 AUDIT, PROPOSE, then EXECUTE ON ACCEPTANCE
+When there is no approved dashboard plan, YOU build the remediation plan in the
+session from your audit, present it, and apply it only on the dev's explicit
+yes \u2014 the same step-by-step discipline as sonenta-source-health, but the fixes
+are a11y variant writes (\`set_a11y_variant\`, reversible drafts) instead of key
+merges. This is the \`## Workflow\` below. Your in-session writes land as drafts a
+human reviews/approves; they do NOT need the dashboard plan's \`approved\` flag.
+
+## Formal conformance \u2014 WCAG report + EAA statement
+Beyond the actionable gap list, surface the FORMAL standing:
+- \`wcag_report\` \u2014 the WCAG 2.2 AA conformance score for the content layer, per
+  locale (\`conformance.score_pct\` + \`by_locale\`). Read \`scope.content_layer_sc\`
+  and \`scope.out_of_scope_sc\` DYNAMICALLY \u2014 never hardcode the SC list; the
+  DOM-dependent criteria are out of scope and never count as pass. Use it as the
+  before/after headline around a remediation pass.
+- \`eaa_statement\` \u2014 the EAA / EN 301 549 conformance STATEMENT (JSON), mapping
+  each covered SC to its EN 301 549 clause. Run it when the dev wants a shareable
+  accessibility statement for the content they govern; be honest about scope (it
+  attests the content layer, not the rendered-DOM audit).
+These are READ-ONLY, 0 credits \u2014 safe to run any time, including in the audit
+phase and the wrap-up.
+
+## Workflow (strictly ordered \u2014 audit \u2192 plan \u2192 accept \u2192 execute)
+1. **Check for a dashboard-directed plan first.** \`a11y_remediation_plan_get\`. If
+   it is \`approved\`, follow path **A** (apply it) and you are done. Otherwise
+   proceed \u2014 you will build your own plan and nothing is written until accepted.
+2. **Audit key TYPES (prerequisite) \u2014 these become PROPOSED re-types, never
+   silent.** The a11y treatments a key offers are decided by its semantic
+   \`type\`, so a project where everything is the default \`text\` (a common
+   starting state) produces NO aria/alt/icon gaps even when buttons and images
+   need them. Read each key's \`type\` from \`list_keys\` and identify the
+   mis-typed ones (buttons/links \u2192 \`button\` / \`link\`, images \u2192 \`image\`, icons
+   \u2192 \`icon\`, form-field labels \u2192 \`input_label\`, headings \u2192 \`heading\`, \u2026).
+   \`type\` is user-owned config \u2014 the re-types go INTO the plan as proposals,
+   applied via \`update_key\` / \`update_keys_bulk\` (type-only, no source_value)
+   ONLY on acceptance. Never retype silently. (Correct types are what make the
+   real gaps surface.)
+3. **Scan \u2014 derive the needed surfaces, don't assume them.** Read
    \`list_surfaces\` (the project's ACTIVE a11y surfaces) and \`recommend_surfaces\`
-   (which surfaces each key's type actually needs, and where they're missing). Never
-   hardcode "the project needs aria_label + alt_text" \u2014 let those reads tell you.
-   Then call \`a11y_report\`, passing \`require_surface\` = the active a11y surfaces
-   the project actually uses. Summarize \`total_gaps\`, \`by_gap\`, \`by_severity\`,
-   \`by_surface\`, and use \`list_a11y_gaps\` to pull the actionable items \u2014 each
-   carries \`key_uuid\`, \`key_name\`, \`namespace_slug\`, \`surface\`, and
-   \`locale\`.
-3. **Triage.** Group by type/severity \u2014 warnings first (\`a11y_untranslated\`,
-   \`alt_missing\`), then info (\`reading_level_high\`, \`a11y_variant_absent\`).
-4. **Generate locally + write (DEFAULT path, 0 credits).** For each gap, compose
-   the a11y value YOURSELF \u2014 reasoning over the key name, source value, any
-   context/description, and the target surface \u2014 then persist it with
-   \`set_a11y_variant(key_uuid, language_code, surface, value)\`. For
-   \`a11y_untranslated\`, translate the source variant yourself into the target
-   \`language_code\` and \`set_a11y_variant\`. Work through the gap list in
-   sensible batches. This spends NO AI credits.
-5. **Score plain-language (local, 0 credits).** Call
-   \`list_cognitive_candidates\` (use \`only_unanalyzed=true\` to skip already
-   scored keys). For each candidate, JUDGE its cognitive difficulty yourself
-   (0-100, higher = harder to read) and write a clearer plain-language rewrite,
-   then \`set_cognitive_score(key_uuid, score, suggestion)\`. Keys at/above the
-   project threshold then surface as \`reading_level_high\` for a human to
-   apply/approve. This spends NO credits \u2014 prefer it over \`analyze_cognitive\`.
-6. **Server fallback (opt-in only).** If the volume is impractical to do locally,
-   or the developer explicitly wants Sonenta server-side AI, FIRST call
-   \`a11y_estimate\` (report \`credits_required\` vs \`balance\`; stop if not
-   \`sufficient\`), confirm, THEN \`generate_a11y_variant\` /
-   \`translate_a11y_variants\` (or \`analyze_cognitive\` for bulk cognitive
-   scoring).
-7. **Report.** Everything you write lands as a **draft** for human review \u2014 never
-   present it as final. Summarize what you set (counts by surface / locale), what
-   remains, and whether any credits were spent (0 on the local path).
+   (which surfaces each key's type actually needs, and where they're missing) \u2014
+   never hardcode "the project needs aria_label + alt_text". Then \`a11y_report\`,
+   passing \`require_surface\` = the active a11y surfaces, and \`list_a11y_gaps\`
+   for the actionable items (each carries \`key_uuid\`, \`key_name\`,
+   \`namespace_slug\`, \`surface\`, \`locale\`). Also run \`wcag_report\` to capture
+   the BEFORE conformance score.
+4. **Score readability (local, 0 credits).** \`list_cognitive_candidates\`
+   (\`only_unanalyzed=true\` to skip scored keys), then \`score_cognitive_local\`
+   (scope with \`key_uuids\` / \`namespace_uuid\`, \`overwrite\` to re-score) to
+   populate cognitive scores from the VALIDATED Flesch-Kincaid / LIX metric \u2014
+   deterministic, 0 credits, no AI. Keys at/above the project threshold surface as
+   \`reading_level_high\` gaps and enter the plan. Prefer this over
+   \`analyze_cognitive\` (billed AI).
+5. **BUILD THE PLAN (write nothing yet).** Assemble one concrete proposal: the
+   key re-types (step 2), and for every gap the exact fix \u2014 \`{key_uuid,
+   key_name, surface, locale, the value you will write}\` \u2014 composing each
+   alt/aria/screen-reader value and each plain-language rewrite YOURSELF, by
+   reasoning over the key name, source value, context, and surface. Group it by
+   severity (warnings \u2014 \`a11y_untranslated\`, \`alt_missing\` \u2014 first; then info \u2014
+   \`reading_level_high\`, \`a11y_variant_absent\`). The plan is the deliverable of
+   the audit; do NOT call any write tool to produce it.
+6. **PRESENT the plan + reassure; WAIT for acceptance.** Show the dev the full
+   plan: the proposed re-types, the per-gap fixes (with the exact text you'll
+   write), and the conformance delta you expect. Make explicit that NOTHING is
+   written until they accept, every write is a reviewable draft, variants are
+   reversible, and you will not overwrite a human-reviewed value. Ask which parts
+   to proceed with (all, or a subset).
+7. **EXECUTE \u2014 only on acceptance, only the accepted parts.** Apply the re-types
+   (\`update_key\` / \`update_keys_bulk\`), then write each accepted a11y value
+   with \`set_a11y_variant(key_uuid, language_code, surface, value)\` (for
+   \`a11y_untranslated\`, translate the source variant into the target
+   \`language_code\` yourself first), and persist plain-language rewrites with
+   \`set_cognitive_score(key_uuid, score, suggestion)\`. Work in sensible batches,
+   narrate progress, skip whatever the dev declined. All 0 credits, all drafts.
+   If reality diverges from the plan mid-execution, STOP and re-present.
+8. **Server fallback (opt-in only).** If the volume is impractical locally, or the
+   dev explicitly wants server-side AI, FIRST \`a11y_estimate\` (report
+   \`credits_required\` vs \`balance\`; stop if not \`sufficient\`), confirm, THEN
+   \`generate_a11y_variant\` / \`translate_a11y_variants\` (or \`analyze_cognitive\`).
+9. **Conformance wrap-up.** Re-run \`wcag_report\` for the AFTER score (report the
+   before\u2192after \`conformance.score_pct\` delta), summarize what you set (counts by
+   surface / locale), what remains, and credits spent (0 on the local path).
+   Remind the dev everything is a draft to review. When they want a shareable
+   statement, produce \`eaa_statement\`.
 
 ## Modes
-- **Interactive (Claude Code):** propose the fix plan, then write the local
-  fixes; for the credit-billing fallback, show the estimate and confirm first.
-- **CI / headless:** run \`a11y_report\` and exit non-zero when \`total_gaps\` (or
-  a chosen severity) exceeds the project threshold; optionally auto-write the
-  local fixes. Only use the credit-billing fallback when explicitly authorized.
+- **Interactive (Claude Code):** the default \u2014 audit \u2192 present the plan \u2192 wait for
+  acceptance \u2192 execute the accepted parts \u2192 conformance wrap-up. One section at a
+  time when the dev prefers. For the credit-billing fallback, show the estimate
+  and confirm first.
+- **CI / headless:** run \`a11y_report\` / \`wcag_report\` and exit non-zero when
+  \`total_gaps\` (or a chosen severity, or the AA score below a threshold) fails
+  the gate. Do NOT auto-write fixes in CI unless the run explicitly authorizes it
+  \u2014 the plan-then-accept rule is the whole point. Only use the credit-billing
+  fallback when explicitly authorized.
 
 ## Guardrails
-- Default to LOCAL work + \`set_a11y_variant\` / \`set_cognitive_score\`
-  (0 credits). Treat \`generate_a11y_variant\` / \`translate_a11y_variants\` /
-  \`analyze_cognitive\` as an explicit, estimated, opt-in fallback \u2014 never the
-  silent default.
-- \`set_a11y_variant\` / \`delete_a11y_variant\` / \`set_cognitive_score\` are CRUD
-  and never spend AI credits; only \`generate\` / \`translate\` / \`analyze\` do.
-  Always estimate before that fallback.
-- You FILL gaps \u2014 never overwrite a human-reviewed variant blindly.
+- NEVER write, re-type, or delete anything before the dev accepted that specific
+  plan. The audit (\`*_report\`, \`list_*\`, \`recommend_surfaces\`,
+  \`score_cognitive_local\`) is read/score-only; the PLAN is always presented and
+  accepted before any \`set_a11y_variant\` / \`update_key\` write.
+- For a DASHBOARD plan, the \`approved\` flag is the gate: apply it verbatim with
+  \`a11y_remediation_plan_apply\`, never a draft, never re-clustered or edited.
+- Default to LOCAL work + \`set_a11y_variant\` / \`score_cognitive_local\` /
+  \`set_cognitive_score\` (0 credits). Treat \`generate_a11y_variant\` /
+  \`translate_a11y_variants\` / \`analyze_cognitive\` as an explicit, estimated,
+  opt-in fallback \u2014 never the silent default; always estimate before it.
+- Everything you write is a reviewable DRAFT \u2014 never present it as final. Variant
+  writes are a reversible overlay; you FILL gaps and never overwrite a
+  human-reviewed value blindly.
 - Derive which a11y surfaces the project needs from \`list_surfaces\` (active) +
-  \`recommend_surfaces\` \u2014 never hardcode an assumed set of required surfaces.
+  \`recommend_surfaces\`, and the WCAG scope from \`wcag_report\`'s
+  \`scope.content_layer_sc\` \u2014 never hardcode an assumed surface or SC set.
 - Key \`type\` is user-owned config \u2014 propose re-types and apply only on
   acceptance; never silently reclassify.
 - Stay within the configured project; confirm it before any bulk operation.
@@ -732,7 +838,7 @@ the variant-writing or a11y-generation tools.
 var AGENTS = {
   "sonenta-a11y": {
     name: "sonenta-a11y",
-    summary: "Accessibility (a11y) auditor + fixer: scans WCAG gaps and fixes them locally (0-credit set_a11y_variant), with server-side AI generation as an opt-in fallback.",
+    summary: "Accessibility (a11y) auditor + fixer, plan-first like source-health: runs a full code-aware WCAG 2.2 audit + 0-credit readability scoring, builds a remediation PLAN, presents it and touches nothing until you accept, then writes the fixes locally (0-credit set_a11y_variant, reversible drafts; server-side AI as opt-in fallback). Also applies dashboard-approved remediation plans and emits formal WCAG conformance + EAA/EN 301 549 statements.",
     content: SONENTA_A11Y
   },
   "sonenta-i18n": {
@@ -1000,6 +1106,86 @@ 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 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/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) => {
@@ -1016,20 +1202,55 @@ 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 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(
+    "--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}/`);
+    }
+  )
 );
 
 // 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";
 
@@ -1169,9 +1390,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++;
         }
@@ -1189,7 +1410,7 @@ 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";
 function resolveLangNs(filePath, optLang, optNs) {
@@ -1207,7 +1428,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`);
   }
@@ -1264,13 +1485,13 @@ var importCommand = new Command3("import").description(
 
 // src/commands/init.ts
 import { existsSync } from "fs";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
 import { Command as Command4 } 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 -->";
@@ -1358,13 +1579,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);
@@ -1373,18 +1594,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 });
   }
@@ -1392,7 +1613,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",
@@ -1433,9 +1654,13 @@ async function gatherRepoDocData(opts) {
 }
 var initCommand = new Command4("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.`
@@ -1462,6 +1687,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`."
@@ -1490,8 +1759,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();
@@ -1507,7 +1776,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) {
@@ -1516,7 +1785,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) {
@@ -1545,10 +1814,10 @@ async function promptSecret(message) {
 var TOKEN_REGEX = /^vrb_[a-z]+_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 var loginCommand = new Command6("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) {
@@ -1667,14 +1936,14 @@ var projectsCommand = new Command9("projects").description("Inspect Verbumia pro
 import { Command as Command10 } 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 [];
   }
@@ -1683,12 +1952,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) });
@@ -1697,7 +1966,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`);
@@ -1713,12 +1982,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) {
@@ -1857,7 +2126,7 @@ var releasesCommand = new Command12("releases").description("Manage CDN releases
 );
 
 // src/commands/snapshot.ts
-import { promises as fs8 } from "fs";
+import { promises as fs9 } from "fs";
 import { Command as Command13 } from "commander";
 function bundleUrl(cdnBase, project, version, lang, ns) {
   return `${cdnBase.replace(/\/+$/, "")}/p/${project}/${version}/latest/${lang}/${ns}.json`;
@@ -1924,7 +2193,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)` : "")
       );