@@ -0,0 +1,29 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): 17 more author-time rule ids print a `fix:` line of one remedy sentence, and `os explain RULE_ID` carries what those lines used to explain
+
+Clause-②: no
+
+- **Shorter fix lines.** Each finding of these 17 rule ids now carries a `hint` (the CLI's `fix:` line, the runtime issue's `hint`) of one remedy sentence of at most 200 characters on every variant the lint suite fires (the lengths here are the `hint` alone; the CLI prints it after `fix: `). The longest of each, before → after:
+  - list-view search: `searchable-field-unknown` (448 → 129), `searchable-field-unprovisioned` (362 → 175) and `searchable-field-unsearchable` (328 → 139);
+  - list-view sort: `sort-field-unprovisioned` (378 → 191), `sort-field-unsortable` (332 → 154) and `sort-field-unknown` (301 → 142);
+  - visibility predicates: `visibility-predicate-unknown-function` (375 → 165), `visibility-bare-identifier` (221 → 102) and `visibility-predicate-syntax` (214 → 113);
+  - flow filters: `flow-filter-token-unknown` (427 → 182);
+  - actions: `action-no-placement` (424 → 171);
+  - import mappings: `mapping-target-field-unknown` (405 → 189);
+  - dashboards: `unconsumed-widget-option` (396 → 135);
+  - app navigation: `nav-object-ungranted` (370 → 118);
+  - hook bodies: `hook-body-write-unprovisioned-anchor` (365 → 178), `hook-body-write-unknown-field` (275 → 110) and `hook-body-source-unparseable` (254 → 105).
+- **One line, one remedy.** Where a fix line explained its remedy, the explanation moved: why a stale or inadmissible `searchableFields` entry is a `400 INVALID_FIELD` on list search, that a view narrows the object's searchable set and never widens it, and that a lookup column stores only an id; that both runtime doors refuse a formula sort with `400 INVALID_SORT`; how to vouch for an unprovisioned anchor (`columnMap`) or opt the object out of the injection (`ownership: 'none'`, `systemFields: { audit: false }`); the two vocabularies a flow filter token resolves in; the other-language operator spellings CEL does not parse, why re-spelling cannot fix an unregistered function, and which namespaces each surface binds; why gating a nav entry does not clear a missing grant; which hook-body write shapes are checked; what a partially parsed body leaves unchecked.
+- **A list the verdict already covers is not echoed.** `searchable-field-unknown`, `sort-field-unknown` and `mapping-target-field-unknown` no longer list every field of the object: the verdict's "Did you mean" names the near miss. `mapping-target-field-unknown` still lists the object's compound fields and their parts, as every import-mapping refusal does.
+- **`os explain RULE_ID` carries the rest.** What the fix lines stopped saying is each id's `RULE_EXPLANATIONS` entry in `@objectstack/lint`, which `os explain RULE_ID` prints. Two ids had no entry and gain one, so their `rule:` line now ends with the `os explain` pointer: `action-no-placement` ("where an action can be placed") and `unconsumed-widget-option` ("which widget options a renderer reads"). Five entries gain text. The action locations the new entry spells out are held to the spec's `ACTION_LOCATIONS` by the rule's test.
+- **At the runtime publish gate** (Studio, REST `PUT /api/v1/meta`, and the MCP and AI authors that write through that door), 10 of the 17 fire; the `hint` FROM → TO, measured at the door:
+  - a `view` write: `sort-field-unknown` (422 `issues[].hint`, a name / a dotted path 114 / 261 → 47 / 135), `sort-field-unsortable` (422, 318 → 140), `sort-field-unprovisioned` (2xx `advisories[].hint`, 363 → 176), `searchable-field-unknown` (422, a name / a dotted path 281 / 430 → 48 / 129), `searchable-field-unsearchable` (422, a formula / outside the declared set / a lookup / a json column 222 / 142 / 323 / 157 → 110 / 68 / 135 / 64), `searchable-field-unprovisioned` (2xx advisory, 361 → 174), `visibility-predicate-syntax` (422, a recognised spelling / none 106 / 214 → 106 / 107), `visibility-predicate-unknown-function` (422, 371 → 165) and `visibility-bare-identifier` (422, a bare name / an unbound namespace 160 / 215 → 41 / 96);
+  - an `object` write: `searchable-field-unknown` (422, the object's own set / a built-in list view 266 / 261 → 55 / 50), `searchable-field-unsearchable` (422, 222 → 110) and `searchable-field-unprovisioned` (2xx advisory, 361 → 174);
+  - a `flow` write: `flow-filter-token-unknown` (422, `{TOMORROW()}` / `{ROUND(x)}` / `{Math.round(x)}` / `{TODAY() - 45 - 10}` 336 / 358 / 427 / 100 → 91 / 113 / 182 / 100).
+
+  Studio's save-advisory toast prints an advisory's `hint` after its message, so the two `*-unprovisioned` toasts shorten; Studio renders no 422 issue's `hint`. No Studio, REST or MCP reader in this repository or in objectui matches on `hint` text; a tool that did should match on `rule` and `path` instead.
+- **Never at the runtime gate:** `action-no-placement`, `mapping-target-field-unknown`, `unconsumed-widget-option`, `nav-object-ungranted` and the three `hook-body-*` ids run on the CLI only.
+- **Unchanged:** every `message` (the verdict), rule id, severity and `path`, and what each rule accepts or refuses.
@@ -343,7 +343,17 @@ function cliFindings(): Array<{ rule: string; message: string; fix?: string }> {
 
 describe('the rule ids packages/cli produces — one verdict line, one fix, and an explanation (#22841)', () => {
   it('fires each from its producer, and they are exactly the explained ids no lint rule produces', () => {
-    const lintIds = new Set<string>([...exportedRuleIds(), ...FUNCTIONAL_COMPLETENESS_RULES]);
+    // `unconsumed-widget-option` is `@objectstack/sdui-parser`'s diagnostic code,
+    // which lint's `validateDashboardWidgetOptions` forwards unchanged — a lint
+    // rule produces it with no constant on lint's barrel, so it is fired from
+    // that producer here (this package does not depend on sdui-parser).
+    const forwarded = lint
+      .validateDashboardWidgetOptions({
+        dashboards: [{ name: 'd', widgets: [{ id: 'w', type: 'metric', dataset: 'ds', options: { unread: true } }] }],
+      })
+      .map((f) => f.rule);
+    expect(forwarded).toEqual(['unconsumed-widget-option']);
+    const lintIds = new Set<string>([...exportedRuleIds(), ...FUNCTIONAL_COMPLETENESS_RULES, ...forwarded]);
     const explainedElsewhere = Object.keys(RULE_EXPLANATIONS).filter((id) => !lintIds.has(id)).sort();
     const fired = [...new Set(cliFindings().map((f) => f.rule))].sort();
     expect(fired).toEqual([
 
@@ -171,3 +171,14 @@ export const PARSE_FAILURE_HINT =
   'The source is parsed (never executed) so it can be checked. A source with syntax errors is only ' +
   'partially recovered, so the checks that follow may have skipped real problems — fix the syntax ' +
   'error and re-run to get a verdict that covers the whole source.';
+
+/**
+ * [#22161] The ONE-LINE form of {@link PARSE_FAILURE_HINT}, for a rule whose
+ * `fix:` line is one remedy: the same instruction, and the rule's `os explain`
+ * entry (`rule-explanations.ts`) carries what a partially recovered tree means
+ * for the checks. A caller still on the long hint converges here when its
+ * `fix:` line is shortened. Not on the root barrel: no caller outside this
+ * package needs it.
+ */
+export const PARSE_FAILURE_FIX =
+  'Fix the syntax error and re-run: until the source parses, the checks cover only what the parser recovered';
@@ -10,6 +10,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
+import { UNCONSUMED_WIDGET_OPTION } from '@objectstack/sdui-parser';
 import { FUNCTIONAL_COMPLETENESS_RULES } from '@objectstack/spec/kernel';
 
 import * as indexBarrel from './index.js';
@@ -22,9 +23,11 @@ const HERE = dirname(fileURLToPath(import.meta.url));
  * Every rule id constant the root barrel exports, by value, plus the ids of the
  * functional-completeness predicate: those rules live in `@objectstack/spec/kernel`
  * and `validate-functional-completeness.ts` forwards their findings unchanged.
+ * The same holds for `@objectstack/sdui-parser`'s widget-option check, whose
+ * code `validate-dashboard-widget-options.ts` forwards unchanged.
  */
 function exportedRuleIds(): Set<string> {
-  const ids = new Set<string>(FUNCTIONAL_COMPLETENESS_RULES);
+  const ids = new Set<string>([...FUNCTIONAL_COMPLETENESS_RULES, UNCONSUMED_WIDGET_OPTION]);
   for (const [name, value] of Object.entries(indexBarrel)) {
     if (/^[A-Z][A-Z0-9_]*$/.test(name) && typeof value === 'string') ids.add(value);
   }
 
@@ -380,6 +380,19 @@ const UNPROVISIONED_ANCHOR_CAUSE =
   'database owns the schema, so the platform registers these anchors without provisioning a ' +
   'column: the name resolves, but no storage stands behind it.';
 
+/**
+ * The three ways out of an unprovisioned anchor, which the one-line `fix:` of
+ * the converted anchor ids (`unprovisionedAnchorFix()`) names without the how:
+ * `sort-field-unprovisioned`, `searchable-field-unprovisioned` and
+ * `hook-body-write-unprovisioned-anchor` write it out.
+ */
+const UNPROVISIONED_ANCHOR_REMEDY =
+  'To fix it, check the remote table. If it really carries the column, declare it in the object\'s ' +
+  'own `fields`, mapped to the remote column through the external binding\'s `columnMap`, so the name ' +
+  'resolves to a column you vouch for. If it does not, drop the reference, or opt the object out of ' +
+  'the injection: `ownership: \'none\'` for the ownership anchors, `systemFields: { audit: false }` ' +
+  'for the audit family.';
+
 const DASHBOARD_FILTER_FIELD_UNPROVISIONED_EXPLANATION: RuleExplanation = {
   rule: 'dashboard-filter-field-unprovisioned',
   covers: 'why a filter on an unprovisioned anchor matches nothing',
@@ -894,6 +907,10 @@ const HOOK_BODY_WRITE_UNKNOWN_FIELD_EXPLANATION: RuleExplanation = {
       'hook\'s input, a target another package declares — because a false positive costs an advisory ' +
       'rule more than a miss. The rule stays a warning: it reads the body through a parser, never by ' +
       'running it.',
+    'Only the literal write shapes in `HOOK_BODY_WRITE_PATTERNS` are checked: a computed key, a spread ' +
+      'and an aliased `ctx.input` are not, so a clean run does not prove every write lands. The warning ' +
+      'never blocks a build. The `fix:` line suggests the nearest declared or system column when one is ' +
+      'close.',
   ],
 };
 
@@ -906,6 +923,7 @@ const HOOK_BODY_WRITE_UNPROVISIONED_ANCHOR_EXPLANATION: RuleExplanation = {
       'target objects, and a multi-target hook is reported only when the anchor is unprovisioned on ' +
       'every one of them: the body may branch per object, so an anchor that is real on one target is a ' +
       'legitimate write there. A `ctx.api.object(NAME)` write is judged against the object it names.',
+    UNPROVISIONED_ANCHOR_REMEDY,
   ],
 };
 
@@ -2015,6 +2033,7 @@ const SORT_FIELD_UNPROVISIONED_EXPLANATION: RuleExplanation = {
       'of the same name is one the author vouches for, and a dotted sort name is refused by the ' +
       'ingress gate on its own. The rule is a warning because it cannot see the remote table, only ' +
       'that the platform provisions no storage.',
+    UNPROVISIONED_ANCHOR_REMEDY,
   ],
 };
 
@@ -2046,9 +2065,13 @@ const SEARCHABLE_FIELD_UNSEARCHABLE_EXPLANATION: RuleExplanation = {
       'them, otherwise the AUTO-DEFAULT set — its text-like columns (text / email / phone / url / ' +
       'autonumber / textarea / markdown / select), never a system/audit column or a hidden field. A ' +
       '`lookup` or `master_detail` column stores only the referenced record\'s id, so it is never a ' +
-      'keyword target. The verdict quotes at most three names of a declared set.',
+      'keyword target: to search by the related record\'s title, mirror it onto a stored text field ' +
+      'and declare that. Declaring `searchableFields` on the object chooses its set explicitly, and a ' +
+      'view then narrows that set, never widens it (ADR-0061). The verdict quotes at most three names ' +
+      'of a declared set.',
     VIRTUAL_FIELD_STORAGE,
-    'A formula entry is refused on EVERY surface, the object\'s own set included: measured, it ' +
+    'A formula entry is refused on EVERY surface, the object\'s own set included — the REST ingress ' +
+      'answers `400 INVALID_FIELD`, the same answer a stale entry gets: measured, it ' +
       'matched 0 rows on driver-memory, and 0 rows with no error on driver-sql. Otherwise the ' +
       'object\'s own `searchableFields` is existence-only: its declared branch scans any stored ' +
       'column, so a json or lookup column declared there is a narrow choice the engine executes, not ' +
@@ -2071,6 +2094,7 @@ const SEARCHABLE_FIELD_UNPROVISIONED_EXPLANATION: RuleExplanation = {
     'Only a name that resolved BECAUSE it is injected is judged: an author-declared column of the ' +
       'same name is one the author vouches for. The rule is a warning because it cannot see the ' +
       'remote table, only that the platform provisions no storage.',
+    UNPROVISIONED_ANCHOR_REMEDY,
   ],
 };
 
@@ -3602,6 +3626,57 @@ const SEMANTIC_ROLE_FIELD_UNPROVISIONED_EXPLANATION: RuleExplanation = {
   ],
 };
 
+// ── Action placement (`validate-action-locations.ts`) ───────────────────────
+
+const ACTION_NO_PLACEMENT_EXPLANATION: RuleExplanation = {
+  rule: 'action-no-placement',
+  covers: 'where an action can be placed',
+  paragraphs: [
+    'An action renders at a location only if it DECLARES that location: every console renderer reads ' +
+      'the one predicate. An action that omits `locations`, and that no view places by name, parses, ' +
+      'publishes and is listed in Setup, and no user can ever click it — the ADR-0078 shape of a ' +
+      'declaration that renders nothing.',
+    // Held equal to `ACTION_LOCATIONS` (`@objectstack/spec/ui`) by the rule's test.
+    'The locations an action can declare: `list_toolbar`, `list_item`, `record_header`, `record_more`, ' +
+      '`record_related`, `record_section`. A list view places an action by NAME instead: naming it in ' +
+      '`bulkActions` or `bulkActionDefs` puts it on the selection bar, which the view drives, never ' +
+      '`locations` (an action that only makes sense over a selection has no single-record location). ' +
+      'A name in `rowActions` counts as placement too.',
+    '`locations: []` is the documented headless shape and is never reported: the action stays callable ' +
+      'over REST, MCP and AI and keeps its capability gate, params contract and audit trail while ' +
+      'claiming no UI surface. ADR-0110 D3 refuses an undeclared handler, so a headless declaration is ' +
+      'the legal way to expose such an action; only a MISSING key is unstated placement.',
+    'A warning, not an error: a view in another installed package can place the action by name. The ' +
+      'rule asks only whether anyone placed the action; whether a declared location is one a renderer ' +
+      'serves, and whether a name resolves (`action-name-undefined`), are other rules\' questions.',
+  ],
+};
+
+// ── Dashboard widget options (`validate-dashboard-widget-options.ts`) ───────
+// The id is `@objectstack/sdui-parser`'s diagnostic code: the rule forwards that
+// package's check unchanged, and the SDUI save gate emits the same code.
+
+const UNCONSUMED_WIDGET_OPTION_EXPLANATION: RuleExplanation = {
+  rule: 'unconsumed-widget-option',
+  covers: 'which widget options a renderer reads',
+  paragraphs: [
+    'A widget\'s `options` bag is declared open (the spec\'s `DashboardWidgetOptionsSchema` passes ' +
+      'extra keys through), so any key parses, validates and publishes, including one no renderer ' +
+      'reads. Every spec-legal widget renders through the dataset-bound path, whose read set is the ' +
+      'warning\'s list, so a key outside it styles nothing and the widget renders as if it were absent. ' +
+      'Open extras stay open; they stop being silent. The rule is a warning, at this door as at the ' +
+      'SDUI save gate, which runs the same check under the same code.',
+    'Presentation has declared homes instead: a number\'s face is the dataset measure\'s `format` and ' +
+      '`currency`, a tile\'s accent is the widget\'s `colorVariant`, and a chart\'s look is the ' +
+      'widget\'s `chartConfig`. `format` and `thresholds` in `options` are the keys most often ' +
+      'believed to work; both draw this warning.',
+    'Not reported: a widget with no `dataset` (a legacy inline form), one in the legacy `component` ' +
+      'format, an expression-valued `options`, and a widget carrying ' +
+      '`suppressWarnings: [\'unconsumed-widget-option\']`, which is how a key with a genuine consumer ' +
+      'outside the renderer says so in metadata.',
+  ],
+};
+
 // ── Rule ids `@objectstack/cli` produces ────────────────────────────────────
 // The CLI's own checks, which `os explain` reads from this one table. The CLI
 // depends on this package, so their id constants cannot be imported here:
@@ -3922,6 +3997,8 @@ export const RULE_EXPLANATIONS: Readonly<Record<string, RuleExplanation>> = Obje
   [SEED_INSERT_MODE_DUPLICATES_ON_REPLAY_EXPLANATION.rule]: SEED_INSERT_MODE_DUPLICATES_ON_REPLAY_EXPLANATION,
   [SEED_VALUE_OUTSIDE_STATE_MACHINE_EXPLANATION.rule]: SEED_VALUE_OUTSIDE_STATE_MACHINE_EXPLANATION,
   [SEMANTIC_ROLE_FIELD_UNPROVISIONED_EXPLANATION.rule]: SEMANTIC_ROLE_FIELD_UNPROVISIONED_EXPLANATION,
+  [ACTION_NO_PLACEMENT_EXPLANATION.rule]: ACTION_NO_PLACEMENT_EXPLANATION,
+  [UNCONSUMED_WIDGET_OPTION_EXPLANATION.rule]: UNCONSUMED_WIDGET_OPTION_EXPLANATION,
   [HOOK_BODY_NOT_LOWERABLE_EXPLANATION.rule]: HOOK_BODY_NOT_LOWERABLE_EXPLANATION,
   [HOOK_BODY_BUNDLED_FALLBACK_EXPLANATION.rule]: HOOK_BODY_BUNDLED_FALLBACK_EXPLANATION,
   [HOOK_BODY_UNPARSEABLE_EXPLANATION.rule]: HOOK_BODY_UNPARSEABLE_EXPLANATION,
 
@@ -235,3 +235,21 @@ export function unprovisionedAnchorHint(objectName: string, field: string): stri
     `the audit family).`
   );
 }
+
+/**
+ * [#22161] The ONE-LINE form of {@link unprovisionedAnchorHint}, for a rule
+ * whose `fix:` line is one remedy: the same three ways out — vouch for the
+ * remote column by declaring it, drop the reference, opt the object out of the
+ * injection — in one clause each, and the rule's `os explain` entry
+ * (`rule-explanations.ts`) carries how (`columnMap`, `ownership: 'none'`,
+ * `systemFields: { audit: false }`). The pairing of
+ * {@link unprovisionedAnchorVerdict} with the long cause, repeated for the fix:
+ * a rule still on the long hint converges here when its `fix:` line is
+ * shortened, so the converted rules cannot drift apart.
+ */
+export function unprovisionedAnchorFix(objectName: string, field: string): string {
+  return (
+    `If the remote table carries '${field}', declare it in ${objectName}'s own fields (mapped ` +
+    `through columnMap); otherwise drop the reference or opt the object out of the injection`
+  );
+}