docs(cli): say why the flows translation group stays author-warned

.changeset/20339-flows-reader-text.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/cli': patch
+---
+
+docs(cli): give the true reason the `flows` translation group stays author-warned (#20339)
+
+The doc comment on `authorWarnedTranslationGroups` (published in `dist/` as
+`utils/i18n-extract.js` and `.d.ts`) said no shipped runner reads the `flows`
+group, so a translated wizard string is stored and never shown. That stopped
+being true when the liveness ledger flipped `translation.flows.screens` to
+`live`: the console's screen-flow runner reads each screen's `title` and each
+field's `label` / `placeholder`. The comment now matches the ledger's `flows`
+row: only the flow's own `label` is read by nothing yet (#20318), and the warn
+is group-level, so it still covers the whole group.
+
+No behaviour moves. The `flows` row is still `planned` with `authorWarn`, so
+`os lint` and `os i18n extract` still hold back every `flows.*` key exactly as
+before; that lifts when the row flips, with no edit to the CLI.
+
+Clause-②: no

packages/cli/src/utils/i18n-extract.ts

@@ -1055,16 +1055,18 @@ function walkObjectTabs(config: any, out: ExpectedEntry[]): void {
  * `i18n/missing-*` family. Under `--i18n-strict` the demand side is an error,
  * so a project could be *forced* to author keys it is then warned for.
  *
- * ⛔ The warn side is not the bug and must not be softened: no shipped runner
- * reads the group, so a translated wizard string really is stored and never
- * shown. The demand is the half that is premature.
+ * ⛔ The warn side is not the bug and must not be softened. Only part of the
+ * group is read: the console's screen-flow runner reads `screens`, but the
+ * flow's own `label` is read by nothing yet (#20318), so a translated flow
+ * label really is stored and never shown. The warn is group-level, so it still
+ * covers the whole group. The demand is the half that is premature.
  *
  * ## Shape
  *
  * Group-general, not `flows`-specific, and read from the ledger rather than a
- * switch of our own: the day the objectui screen-flow runner lands and the row
- * flips to `live` (dropping its `authorWarn`), the bucket turns itself back on
- * with no edit here — and any FUTURE group that acquires a warn is covered on
+ * switch of our own: the day the row flips to `live` (dropping its
+ * `authorWarn`; for `flows` that waits on #20318), the bucket turns itself back
+ * on with no edit here — and any FUTURE group that acquires a warn is covered on
  * the day it is marked, rather than re-opening this collision one group at a
  * time.
  *

packages/cli/test/i18n-flow-liveness-gate.test.ts

@@ -9,7 +9,9 @@
 // `flow` coverage bucket, new in #11615, harvested `flows.<f>.label`,
 // `flows.<f>.screens.<n>.title` and the per-field `label`/`placeholder`. The
 // `flows` row of `@objectstack/spec/liveness/translation.json` is
-// `status: planned` + `authorWarn: true` — no shipped runner reads the group.
+// `status: planned` + `authorWarn: true` — only part of the group is read: the
+// console's screen-flow runner reads `screens`, but the flow's own `label` is
+// read by nothing yet (#20318).
 //
 // Measured on one stack before the fix:
 //
@@ -22,10 +24,11 @@
 // restored. Under `--i18n-strict` the demand side is an ERROR, so a project
 // could be forced to author keys it is then warned for.
 //
-// ⛔ The warn side is NOT the bug and is not softened here. Nothing reads the
-// group, so a translated wizard string really is stored and never shown —
-// the failure mode `validationMessages` was removed in 17.0.0 for. The demand
-// is the premature half, and it is what is gated.
+// ⛔ The warn side is NOT the bug and is not softened here. The flow's own
+// `label` is read by nothing yet (#20318), so a translated flow label really is
+// stored and never shown — the failure mode `validationMessages` was removed in
+// 17.0.0 for. The warn is group-level, so it still covers the whole group. The
+// demand is the premature half, and it is what is gated.
 //
 // ## What is pinned
 //
@@ -165,9 +168,9 @@ describe('the liveness gate on the i18n coverage walk', () => {
     expect(flowWarnings(app(false))).toEqual([]);
 
     expect(flowDemands(app(true))).toEqual([]);
-    // ⛔ The warning is true and stays: nothing reads the group, so this copy is
-    // stored and never shown. Its rule id says `planned`, i.e. "keep it", not
-    // "remove it".
+    // ⛔ The warning is true and stays: the flow's own `label` is read by
+    // nothing yet, so its translated copy is stored and never shown. Its rule
+    // id says `planned`, i.e. "keep it", not "remove it".
     const warned = flowWarnings(app(true));
     expect(warned.length).toBeGreaterThan(0);
     for (const f of warned) expect(f.rule).toBe('liveness-planned-property');

packages/cli/test/i18n-flow-screen-coverage.test.ts

@@ -38,8 +38,9 @@
 // `authorWarn`, and `os lint` runs this bucket in the SAME pass as
 // `lintLivenessProperties`, so demanding the keys while the ledger warns
 // authors for writing them left the author with no move that satisfies both.
-// The bucket is now gated on that row, and it turns itself back on the day an
-// objectui screen-flow runner lands and the row flips.
+// The bucket is now gated on that row, and it turns itself back on the day the
+// row flips to `live` (dropping its `authorWarn`; for `flows` that waits on
+// #20318).
 //
 // So these pins are re-anchored, not retired: the mock below is the ledger
 // warning on nothing, i.e. exactly the post-flip world. Retiring them instead