@sonenta/cli 0.20.0 → 0.21.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command as Command17 } from "commander";
 // package.json
 var package_default = {
   name: "@sonenta/cli",
-  version: "0.20.0",
+  version: "0.21.0",
   description: "Command-line interface for Sonenta translation management.",
   license: "MIT",
   homepage: "https://sonenta.com",
@@ -171,9 +171,12 @@ ${PREFLIGHT}## Requirements
     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.
+    PLUS a plain-language \`suggestion\` (your own rewrite), CRUD, **0 AI credits**
+    (by_bot). The \`suggestion\` is what populates \`keys.cognitive_suggestion\` \u2014
+    the dashboard's "Plain language" / cognitive tab \u2014 so it must be set whenever
+    you simplify a key (see **Plain language**), NOT just the score. Prefer
+    \`score_cognitive_local\` to populate the scores themselves; use this for the
+    suggestion (and a score when scoring locally).
   - \`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,
@@ -197,16 +200,33 @@ ${PREFLIGHT}## Requirements
 a11y values are SEMANTIC (the accessible name / alt / simplified wording for
 assistive tech), not the visible UI string \u2014 keep them concise and meaningful.
 
+## Plain language \u2014 write the variant AND \`cognitive_suggestion\` (both, always)
+A plain-language simplification lives in TWO places that must stay consistent:
+the \`plain_language\` a11y VARIANT (per locale) and the key's
+\`cognitive_suggestion\` field (the dashboard's "Plain language" / cognitive
+tab). Writing only the variant leaves that tab empty even though the overlay
+exists. So whenever you simplify a key, do BOTH \u2014 at **0 credits**:
+1. \`set_a11y_variant(key_uuid, language_code, "plain_language", <simplified>)\`
+   for each locale you simplify (the source locale first, then translations).
+2. \`set_cognitive_score(key_uuid, score, suggestion=<simplified SOURCE-language
+   text>)\` \u2014 the \`suggestion\` is the simplified text in the SOURCE language (i.e.
+   exactly the source locale's \`plain_language\` value), so the cognitive tab
+   shows the proposed rewrite and matches the overlay. (Score it with
+   \`score_cognitive_local\` or your own 0-100 judgement.)
+Both are drafts for human approval; never approve them yourself.
+
 ## Gap types and how you resolve each (locally, by yourself)
 - \`a11y_variant_absent\` \u2014 a required surface is missing in the source \u2192 compose
   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. 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.
+  Flesch-Kincaid / LIX, 0 credits), then simplify the hard ones \u2014 writing BOTH
+  the \`plain_language\` variant (\`set_a11y_variant\`) AND the
+  \`cognitive_suggestion\` (\`set_cognitive_score(key_uuid, score, suggestion)\`)
+  with the same simplified SOURCE-language text, per **Plain language** (0
+  credits, drafts). Don't write one without the other, or the cognitive tab and
+  the overlay disagree.
 - \`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\`.
 
@@ -301,10 +321,12 @@ phase and the wrap-up.
    (\`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.
+   \`language_code\` yourself first). For every plain-language simplification write
+   BOTH the \`plain_language\` variant AND \`set_cognitive_score(key_uuid, score,
+   suggestion=<simplified SOURCE text>)\` so the cognitive tab matches the overlay
+   (see **Plain language**) \u2014 never just one. 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