@@ -0,0 +1,18 @@
+---
+"@objectstack/cli": patch
+"@objectstack/lint": patch
+"@objectstack/objectql": patch
+---
+
+fix(cli): the nine rule ids the CLI produces print one verdict sentence each, `os explain <rule-id>` carries their reasoning, and the undeclared-handlers boot line is one line
+
+Clause-②: no
+
+- **One verdict sentence of at most 200 characters.** Measured on every finding the CLI's suites fire (message length; before → after):
+  - `os lint`'s hook-body rules: `hook-body/not-lowerable` 565–661 → 165–178, `hook-body/bundled-fallback` 324–947 → 109–171, `hook-body/unparseable` 469 → 157, `hook-body/extraction-failed` 331 → 140. Over every refusal the extractor can throw (14 forbidden constructs and 7 parameter refusals), `hook-body/bundled-fallback` runs 296–1,011 → 113–199: the verdict quotes the extractor's own verdict clause, cut to fit and marked `…` when cut.
+  - package docs (`os build`, `os validate`, `os lint`): `docs/uncollected-directory` 433–558 → 124–183, `docs/nav-target` 263–299 → 147–184, `docs/frontmatter-tags` 233–285 → 135–195, `docs/duplicate-name` 330 → 167 (its within-package arm is unchanged at 101). A doc finding no longer repeats its path, which every printer already leads with; lists of files, packages and directories name the first three and count the rest.
+  - `picklist-reference-unverified` (the `os validate` / `os build` notice): 240–245 → 173–175, naming at most two outside dependencies and counting the rest.
+- **A `fix:` line for the hook-body rules.** Their remedy moves out of the message into the finding's `fix`, at most 200 characters: `os lint` prints it as `→ fix:` under `--fix`, and `os lint --json` now carries `fix` on these four ids' issues. The remedy is still chosen per case: inline a module-scope name, or keep a check on a host-only global such as `Intl` in a string handler ref or a validation rule. A doc finding carries no separate fix, so its sentence ends with the remedy; the picklist notice's `hint` is unchanged.
+- **`os explain <rule-id>` carries the rest.** Each of the nine ids gains a `RULE_EXPLANATIONS` entry in `@objectstack/lint`, the one table `os explain` reads, and `os lint`'s `rule:` line now points at it. They hold what the messages stopped saying: why a bundled handler is a change of deployment shape and how to bundle on purpose, what the sandbox cannot run and where `os build` prints the full refusal, why an instrument limit is not a verdict, where package docs are read from and why the collector never guesses, why a doc name may appear once, what a doc navigation item can open, how doc tags are read, and why a reference into a dependency outside the stack is not judged.
+- **The `[action-governance]` boot line for registered handlers with no declaration** (`os dev`, `os serve`, and any host that boots ObjectQL) is one line of 192 characters, where it was 628: it names the three sources it read, states the 404 as expected rather than measured, and says to declare each with `defineAction`. Its structured `count` / `handlers` tail is unchanged, and the dead-button line beside it is unchanged.
+- **Unchanged:** every rule id, severity and `path`, the boot lines' level and payload, and what each check accepts or refuses. A tool that matched on this message text should match on `rule` and `path` instead.
@@ -123,20 +123,21 @@ describe('checkHookBodyLowering', () => {
       // The wrong-remedy failure is worse than none: there is nothing to inline
       // `Intl` from, so an author (or a code-writing model) told to inline it
       // lands on a second broken shape. The remedy sentence is chosen from the
-      // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+      // refusal's own `nodeOnlyIdentifiers`, never re-derived here. [#22161]
+      // The remedy is the finding's `fix:` line; the verdict stays one sentence.
       const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
-      expect(issue.message).toContain('provided by the Node host');
-      expect(issue.message).toContain('cannot be inlined');
-      expect(issue.message).toContain('string handler ref');
-      expect(issue.message).toContain('validation rule');
-      expect(issue.message).not.toContain('Inline the value(s) into the handler');
+      expect(issue.fix).toContain('provided by the Node host');
+      expect(issue.fix).toContain('cannot be inlined');
+      expect(issue.fix).toContain('string handler ref');
+      expect(issue.fix).toContain('validation rule');
+      expect(issue.fix).not.toContain('Inline the value(s) into the handler');
     });
 
     it('leaves the module-scope remedy exactly as it was', () => {
       // The reverse leg: the sentence commit ada3834ad wrote must not have been rewritten for
       // every author by a branch added for one new sub-case.
       const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
-      expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+      expect(issue.fix).toBe('Inline the value(s) into the handler, or reach them through `ctx`.');
       expect(issue.message).not.toContain('provided by the Node host');
     });
   });
 
@@ -117,10 +117,46 @@ export const UNPARSEABLE_BODY_RULE = 'hook-body/unparseable';
 /** The rule name when the extraction instrument itself threw (kind `unknown`). */
 export const EXTRACTION_FAILED_RULE = 'hook-body/extraction-failed';
 
-const DELIBERATE_BUNDLE_REMEDY =
-  'If a bundled closure is what you want, say so: give the hook an explicit `body`, ' +
-  'or move the function into the top-level `functions:` map and reference it by name ' +
-  '(`handler: \'<fn_name>\'`) — neither is lowered to a metadata body.';
+// [#22161] Each finding prints one verdict sentence of at most this many
+// characters and one `fix:` line; the reasoning — why a bundle is a change of
+// deployment shape, the two ways to bundle on purpose, why an instrument limit
+// is not a verdict — is each rule's `RULE_EXPLANATIONS` entry in
+// `@objectstack/lint`, behind `os explain <rule-id>`.
+const VERDICT_LIMIT = 200;
+
+/** How many names a verdict quotes before it counts the rest. */
+const MAX_QUOTED_NAMES = 3;
+
+const nameList = (names: readonly string[]): string =>
+  names.length <= MAX_QUOTED_NAMES
+    ? names.join(', ')
+    : `${names.slice(0, MAX_QUOTED_NAMES).join(', ')} and ${names.length - MAX_QUOTED_NAMES} more`;
+
+/** `text` cut to `limit` characters at a word boundary, marked `…` when it was cut. */
+function bounded(text: string, limit: number = VERDICT_LIMIT): string {
+  if (text.length <= limit) return text;
+  const cut = text.slice(0, limit - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${space > limit / 2 ? cut.slice(0, space) : cut}…`;
+}
+
+/**
+ * The extractor's verdict on a refused handler, as one clause: the first line
+ * of its refusal without the `[hook-body-extract] <origin>: ` lead the
+ * finding's own subject already carries, cut where the verdict clause ends.
+ *
+ * The extractor writes each refusal verdict first — what the sandbox cannot
+ * supply, then ` — ` and why, the remedy and the bundled alternative — so its
+ * first ` — ` (or first full stop) ends the verdict. Nothing the cut drops is
+ * lost: `os build` prints the whole first line for every bundled handler, and
+ * `os build --strict-body` the full diagnostic.
+ */
+function refusalVerdict(firstLine: string, originLabel: string): string {
+  const lead = `[hook-body-extract] ${originLabel}: `;
+  const reason = firstLine.startsWith(lead) ? firstLine.slice(lead.length) : firstLine;
+  const ends = [reason.indexOf(' — '), reason.indexOf('. ')].filter((i) => i > 0);
+  return ends.length > 0 ? reason.slice(0, Math.min(...ends)) : reason.replace(/\.\s*$/, '');
+}
 
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
   typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -157,8 +193,8 @@ function judge(fn: AnyFn, originLabel: string, path: string, face: LoweringFace)
       // send an author (or a code-writing model) after a second broken shape.
       const moduleScope = free.filter((n) => !nodeOnly.includes(n));
       const hostRemedy =
-        `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
-        `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+        `${nameList(nodeOnly)} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host, ` +
+        `not by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
         `keep the check in a string handler ref, or move it to a validation rule.`;
       const inlineRemedy =
         `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
@@ -167,18 +203,17 @@ function judge(fn: AnyFn, originLabel: string, path: string, face: LoweringFace)
           ? inlineRemedy
           : moduleScope.length === 0
             ? hostRemedy
-            : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
-              `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+            : `${hostRemedy} Inline ${nameList(moduleScope)} into the handler, ` +
               `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
       return {
         severity: 'error',
         rule: NOT_LOWERABLE_RULE,
-        message:
-          `${originLabel} cannot be lowered to a metadata-only body: it references ` +
-          `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
-          `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
-          `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
-          `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
+        message: bounded(
+          `${originLabel} cannot be lowered to a metadata-only body, so it is bundled (a change of ` +
+            `deployment shape, not of behaviour): ${nameList(free)} ` +
+            `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox`,
+        ),
+        fix: bounded(remedy),
         path,
       };
     }
@@ -192,18 +227,30 @@ function judge(fn: AnyFn, originLabel: string, path: string, face: LoweringFace)
       // something the sandbox cannot provide"), which asserts a verdict about
       // the handler. Kept distinct on purpose (commit ada3834ad): an instrument failure
       // must not read as a verdict about the author.
-      const [rule, instrument] =
-        kind === 'unparseable'
-          ? ([UNPARSEABLE_BODY_RULE, 'the extractor found no function body it could judge'] as const)
-          : ([EXTRACTION_FAILED_RULE, 'the extraction instrument itself failed'] as const);
+      if (kind === 'unparseable') {
+        // The extractor's own line says only that it could not parse the body
+        // and asks for a rewrite, which is this finding's verdict and fix.
+        return {
+          severity: 'warning',
+          rule: UNPARSEABLE_BODY_RULE,
+          message: bounded(
+            `${originLabel} could not be analysed: the extractor found no function body it could judge, ` +
+              `which is a limit of the instrument, not a verdict about the handler`,
+          ),
+          fix: 'Rewrite it as a single arrow function or named function expression; until then `os build` bundles it.',
+          path,
+        };
+      }
+      // The thrown error is the only clue to what broke, so the verdict quotes
+      // its first line, cut to the room the sentence leaves.
+      const frame = (thrown: string): string =>
+        `${originLabel} could not be analysed: the extraction instrument itself failed (${thrown}), ` +
+        `which is not a verdict about the handler`;
       return {
         severity: 'warning',
-        rule,
-        message:
-          `${originLabel} could not be analysed: ${instrument}. ${firstLine} ` +
-          `This is a limit of the instrument, not a verdict about the handler — it does NOT mean ` +
-          `a bundled closure was chosen; whether this body could ship as pure metadata is ` +
-          `undetermined. \`os build\` still bundles it via the designed fallback.`,
+        rule: EXTRACTION_FAILED_RULE,
+        message: frame(bounded(firstLine, Math.max(40, VERDICT_LIMIT - frame('').length))),
+        fix: 'Nothing to change in the handler: `os build` bundles it, and `os build --strict-body` prints the error in full.',
         path,
       };
     }
@@ -214,10 +261,12 @@ function judge(fn: AnyFn, originLabel: string, path: string, face: LoweringFace)
     return {
       severity: 'warning',
       rule: BUNDLED_FALLBACK_RULE,
-      message:
-        `${originLabel} is bundled rather than shipped as a metadata-only body. ${firstLine} ` +
-        `This is the designed fallback — the body uses something the sandbox cannot provide — ` +
-        `but the app is not pure metadata while it is here.`,
+      message: bounded(
+        `${originLabel} is bundled, not shipped as a metadata-only body: ${refusalVerdict(firstLine, originLabel)}`,
+      ),
+      fix:
+        'None, if the bundle is intended; to ship it as metadata, remove what the refusal names ' +
+        '(`os build` prints the refusal and its remedy in full).',
       path,
     };
   }
 
@@ -200,7 +200,7 @@ describe('collectDocsFromSrc reads src/<pkg>/docs/ for a resolvable package', ()
 
 // ── Clause 4: the #18428 warning stays, and says WHY ───────────────────────
 describe('the #18170 warning stays for a directory neither convention reads', () => {
-  it('a stack with no packages[] gets the original sentence, unchanged', () => {
+  it('a stack with no packages[] gets the single-package sentence', () => {
     writePackageDoc('sales', 'crm_index', 'MARKER-none');
     const { docs, packageDocs, issues } = collectDocsFromSrc(configPath);
 
@@ -210,14 +210,12 @@ describe('the #18170 warning stays for a directory neither convention reads', ()
     expect(issues[0].severity).toBe('warning');
     expect(issues[0].rule).toBe('docs/uncollected-directory');
     expect(issues[0].path).toBe('src/sales/docs');
-    // The exact pre-#18431 text, so a rewrite of the single-package message
-    // fails here rather than in a customer's build log.
+    // The exact text, so a rewrite of the single-package message fails here
+    // rather than in a customer's build log. [#22161] One verdict sentence:
+    // the reasoning it used to carry is `os explain docs/uncollected-directory`.
     expect(issues[0].message).toBe(
-      'src/sales/docs/ holds 1 Markdown file(s) that were NOT collected: package docs are read from src/docs/ only'
-      + " (ADR-0046 §3.2), so these are absent from the artifact's `docs[]` and from every book that includes them."
-      + ' Move them into src/docs/ (doc names carry the package namespace prefix, so packages do not collide there),'
-      + ' declare them inline as `defineStack({ docs })`, or delete them if they are not package docs.'
-      + ' Found: crm_index.md',
+      '1 Markdown file(s) NOT collected (crm_index.md) — package docs are read from src/docs/ only'
+      + ' (ADR-0046 §3.2); move them there',
     );
   });