jui-tools-mcp-server 2.14.0 → 2.15.2

package/README.md

@@ -70,7 +70,7 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 | `list_screen_specs` | 画面 spec 一覧（メタデータ付き） |
 | `list_component_specs` | コンポーネント spec 一覧 |
 | `list_layouts` | Layout JSON ファイル一覧 |
-| `read_spec_file` | spec ファイルの内容を返す |
+| `read_spec_file` | spec ファイルの内容を返す。散文フィールド（description / notes / intent / purpose / processing / handling / rule / meaning / note / reason〔`harnessConditions`・`canonicalDivergence` の下を除く〕/ condition〔トップレベルの `transitions` の下のみ〕）の `{"md": "key"}`（`<name>.texts.yaml` への参照）は `{"md", "text"}` に展開して返す（編集は YAML 側）。参照の無い spec はファイルそのまま。`search_specs` は texts ファイルの本文を検索しない |
 | `read_layout_file` | Layout JSON の内容を返す |
 | `search_specs` | 全 spec（画面・サブディレクトリの sub-spec・コンポーネント）をキーワード検索し、ファイル・JSON path・抜粋を返す |
 

package/data/attribute_definitions.json

@@ -697,11 +697,17 @@
         "string",
         "array"
       ],
-      "description": "Click handler function name (selector-based, lowercase) - string only, no binding"
+      "description": "Click handler function name (selector-based, lowercase) - string only, no binding",
+      "notApplicableTo": {
+        "Web": "the embedded page takes the taps; a tap laid over it would break the page's own taps and scrolling (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onClick": {
       "type": "binding",
-      "description": "Click handler (camelCase) - binding only (@{functionName}). On a type the SSoT does not declare (an app's own component) JsonUI gives the tap no screen-reader role; the component carries its own."
+      "description": "Click handler (camelCase) - binding only (@{functionName}). On a type the SSoT does not declare (an app's own component) JsonUI gives the tap no screen-reader role; the component carries its own.",
+      "notApplicableTo": {
+        "Web": "the embedded page takes the taps; a tap laid over it would break the page's own taps and scrolling (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onLongPress": {
       "type": "binding",
@@ -714,7 +720,12 @@
     },
     "onPan": {
       "type": "binding",
-      "description": "Pan gesture handler (camelCase) - binding only (@{functionName}). Invoked repeatedly while the user drags. Payload: cumulative translation since the gesture began (iOS CGSize, Android Offset; web passes the PointerEvent). A handler declared () -> Void is called without the payload."
+      "description": "Pan gesture handler (camelCase) - binding only (@{functionName}). Invoked repeatedly while the user drags. Payload: cumulative translation since the gesture began (iOS CGSize, Android Offset; web passes the PointerEvent). A handler declared () -> Void is called without the payload.",
+      "notApplicableTo": {
+        "TextField": "the field's own drag (text selection, caret placement) takes the gesture; a pan laid over it would break editing (ruling 2026-10-03: not delivered, the build warns)",
+        "TextView": "the field's own drag (text selection, caret placement) takes the gesture; a pan laid over it would break editing (ruling 2026-10-03: not delivered, the build warns)",
+        "Slider": "the slider's own drag moves its value; a pan laid over it would break that (ruling 2026-10-03: not delivered, the build warns)"
+      }
     },
     "onPinch": {
       "type": "binding",
@@ -732,7 +743,7 @@
         "string",
         "binding"
       ],
-      "description": "Tint color - hex string or color name from colors.json (binding supported)"
+      "description": "Tint color - hex string or color name from colors.json (binding supported). It is the accent of the node's operable parts, SwiftUI `.tint` / CSS `accent-color`: a control's accent, a link's colour, the text cursor - never the text colour (jsonui-cli 1.9.0 ruling). From 1.9.0 Compose no longer tints the text or icons inside a tinted node (the LocalContentColor wrap is gone), as iOS and web never did. The per-type declarations say what the accent is on that type (TextField: the cursor; Switch / Slider / Progress: the tint; Segment / TabView: the selected item). A container's tintColor reaches the controls inside it (included views, cells and embedded screens too), as SwiftUI's `.tint` does: on Compose, from the release after jsonui-cli 1.9.1, through the library's LocalJsonUITint; a control's own tintColor (or a more specific colour such as onTintColor) wins. Images and icons do not take it."
     },
     "binding": {
       "type": [
@@ -767,7 +778,7 @@
     },
     "include": {
       "type": "string",
-      "description": "Include another JSON layout (filename without extension)"
+      "description": "Include another JSON layout (its path from the layouts root, without extension). An include is an inline expansion: the included layout is drawn where this node is, and it reads the including layout's data — the parent owns the ViewModel. Under an `id`, the id prefixes the included layout's ids and data names, camelCase-joined (id `side` + `title` -> `sideTitle`), so the included layout's `@{title}` reads the including layout's `sideTitle`; without one it reads `title`. The include node's object maps, `shared_data` and then `data`, are laid over the including layout's data: a key is a name the included layout binds, a value is a literal or a binding read in the including layout's scope. The same on every platform and in Dynamic mode (ruling 2026-10-02). Until jsonui-cli 1.9.6 web handed an include without a map none of the including layout's data (the included layout drew its own defaults), and sjui / kjui codegen ignored an object map."
     },
     "variables": {
       "type": "object",
@@ -777,7 +788,7 @@
     },
     "shared_data": {
       "type": "object",
-      "description": "Data passed to included components"
+      "description": "On an include node: an object map laid over the including layout's data for the included layout, before `data` (`data` wins on a key both set). A key is a name the included layout binds; a value is a literal or a binding read in the including layout's scope (see `include`)."
     },
     "style": {
       "type": "string",
@@ -901,7 +912,7 @@
           "systemChromeMaterial": "Chrome"
         },
         "default": "Regular",
-        "description": "Visual effect (blur) style. Measured across the three converters 2026-08-05: the UIKit trio Light/Dark/ExtraLight is what all three map (sjui blur_converter.rb:71, kjui blurview_component.rb:38, rjui blur_converter.rb:98), and web additionally maps the SwiftUI material names. Every converter downcases before matching, so the casing here is presentational. `Regular` is the fallback all three already use for an unrecognised or absent value, hence the declared default. Enumerated because it was declared as a bare string while Blur.effectStyle — the same concept on the component that owns it — carried the enum: the split let the common spelling reach the render stage unvalidated, which is what the codegen-effect gate reported once the mode audit put these fixtures back in scope. Declared on `common`, so it applies on all three platforms and not only on Blur; the ios material/tint table is pinned in attribute_semantics.json -> effectStyle, which is also where the system* valueAliases and the tint layer order are ruled."
+        "description": "Visual effect (blur) style. A value is its declared spelling, case and all (jsonui-cli 1.9.0): no converter downcases before matching, so `thick` or `light` is an undeclared spelling, which the validator names and which draws the default. A node that declares its own effectStyle is judged on that declaration: a Blur takes only Blur.effectStyle's Light / Dark / ExtraLight, so Thick on a Blur draws the default too. The spellings here apply to every other node. The `system*Material` spellings are valueAliases of the material names (systemMaterial -> Regular, systemUltraThinMaterial -> UltraThin, and so on). `Regular` is the fallback every path uses for an unrecognised or absent value, hence the declared default. Enumerated because it was declared as a bare string while Blur.effectStyle — the same concept on the component that owns it — carried the enum: the split let the common spelling reach the render stage unvalidated, which is what the codegen-effect gate reported once the mode audit put these fixtures back in scope. Declared on `common`, so it applies on all three platforms and not only on Blur; the ios material/tint table is pinned in attribute_semantics.json -> effectStyle, which is also where the system* valueAliases and the tint layer order are ruled."
       },
     "tag": {
       "type": [
@@ -981,7 +992,7 @@
     },
     "data": {
       "type": "array",
-      "description": "Data model definitions for binding"
+      "description": "Data model definitions for binding: an array of declarations ({name, class, defaultValue}). On an include node an array is declarations merged into the included layout's, and an object is a map laid over the including layout's data for the included layout, after `shared_data` — `data` wins on a key both set (see `include`)."
     },
     "bindingScript": {
       "type": "string",
@@ -1233,7 +1244,7 @@
         "string",
         "binding"
       ],
-      "description": "Text content (can be data binding, supports interpolation). PLAIN TEXT: markdown is not interpreted, so \"[label](/path)\", \"**bold**\" and backticks render literally, brackets and all. To emphasise or link part of the string, use partialAttributes ('range' plus font/color/underline, and 'onClick' for a tappable span). Rendering real markdown is out of scope for Label — write a custom component."
+      "description": "Text content: a literal, or one data binding (`@{text}`). A value that mixes literal text with a binding (`Title: @{x}`) is a build warning, binding-mixed-text — compose the string in the ViewModel and bind it as one value (until jsonui-cli 1.9.6 this read \"supports interpolation\"). PLAIN TEXT: markdown is not interpreted, so \"[label](/path)\", \"**bold**\" and backticks render literally, brackets and all. To emphasise or link part of the string, use partialAttributes ('range' plus font/color/underline, and 'onClick' for a tappable span). Rendering real markdown is out of scope for Label — write a custom component."
     },
     "hint": {
       "type": "string",
@@ -1307,7 +1318,7 @@
         "center",
         "right"
       ],
-      "description": "Where the label's text sits across the label's own width: Left the start, Center the middle, Right the end (binding supported). Without textAlign, the horizontal part of gravity places it (left / right / centerHorizontal, center); without either, the start. Vertically the text sits at the vertical gravity names, else the middle (gravityDefaults -> leafOwnFrameChannel). The lines of a multi-line or wrapped label follow the same rule across. (4f ruling 2026-09-27, and the user's ruling for iOS, round 6: align iOS to start.) The web draws it so from jsonui-cli 1.9.0, its lines too (rjui gives gravity's text-center / text-right when textAlign is not declared; measured in Chromium, a wrapped label's lines stayed at the start until then); Compose from jsonui-cli 1.9.0 (4f round 17); iOS from jsonui-cli 1.9.0 and SwiftJsonUI 10.29.0 (round 6) - until then, measured on sjui codegen and SwiftJsonUI Dynamic, a fixed-width label with neither drew its text in the middle (\"Mon\" in 50, a 200 x 44 label), one with gravity right or center at the start, and the lines of a multi-line one at the start whatever its gravity."
+      "description": "Where the label's text sits across the label's own width: Left the start, Center the middle, Right the end (binding supported). Without textAlign, the horizontal part of gravity places it (left / right / centerHorizontal, center); without either, the start. When gravity names both a center part (center / centerHorizontal) and right, center wins, on every platform. Vertically the text sits at the vertical gravity names, else the middle (gravityDefaults -> leafOwnFrameChannel). The lines of a multi-line or wrapped label follow the same rule across. (Ruled 2026-09-27; for iOS: align to start.) The web draws it so from jsonui-cli 1.9.0, its lines too (rjui gives gravity's text-center / text-right when textAlign is not declared; measured in Chromium, a wrapped label's lines stayed at the start until then); Compose from jsonui-cli 1.9.0, except the lines of a wrapContent-width label whose text wraps (by reading, they stayed at the start) and a gravity naming both center and right (by reading, it took right), both from the release after jsonui-cli 1.9.1; iOS from jsonui-cli 1.9.0 and SwiftJsonUI 10.29.0 (round 6) - until then, measured on sjui codegen and SwiftJsonUI Dynamic, a fixed-width label with neither drew its text in the middle (\"Mon\" in 50, a 200 x 44 label), one with gravity right or center at the start, and the lines of a multi-line one at the start whatever its gravity."
     },
     "lines": {
       "type": [
@@ -2380,7 +2391,7 @@
         "string",
         "binding"
       ],
-      "description": "Button text (can be data binding, supports interpolation)"
+      "description": "Button text: a literal, or one data binding (`@{title}`). A value that mixes literal text with a binding is a build warning, binding-mixed-text — compose the string in the ViewModel and bind it as one value (until jsonui-cli 1.9.6 this read \"supports interpolation\")."
     },
     "font": {
       "type": "string",
@@ -2617,7 +2628,13 @@
       "valueAliases": {
         "ScaleToFill": "fill"
       },
-      "description": "Content mode (binding supported). ScaleToFill is a declared synonym of fill (the stretch — see attribute_semantics.json#semantics.image); the normalizer folds it, fixtures are generated for the canonical spelling only."
+      "description": "Content mode (binding supported). ScaleToFill is a declared synonym of fill (the stretch — see attribute_semantics.json#semantics.image); the normalizer folds it, fixtures are generated for the canonical spelling only.",
+      "bindingInfo": {
+        "platform": [
+          "swift"
+        ],
+        "note": "a contentMode bound to a value that is AspectFill at run time is cropped to its frame by the generated code only when width and height are numbers; on a frame that is not two numbers the image can be drawn past the frame (jsonui-cli ticket sjui-aspectfill-image-is-not-cropped-to-its-frame, known gap). A literal contentMode is cropped on every frame."
+      }
     },
     "renderingMode": {
       "type": "string",
@@ -2753,7 +2770,13 @@
         "AspectFit",
         "Center"
       ],
-      "description": "Content mode (binding supported)"
+      "description": "Content mode (binding supported)",
+      "bindingInfo": {
+        "platform": [
+          "swift"
+        ],
+        "note": "a contentMode bound to a value that is AspectFill at run time is cropped to its frame by the generated code only when width and height are numbers; on a frame that is not two numbers the image can be drawn past the frame (jsonui-cli ticket sjui-aspectfill-image-is-not-cropped-to-its-frame, known gap). A literal contentMode is cropped on every frame."
+      }
     },
     "cachePolicy": {
       "type": "string",
@@ -2880,7 +2903,7 @@
       "valueAliases": {
         "datetime": "dateAndTime"
       },
-      "description": "Date picker mode. datetime is a declared synonym of dateAndTime and the normalizer folds it: sjui and rjui accept both spellings (selectbox_converter.rb case arms; rjui downcases), but KotlinJsonUI's DateSelectBox matches \"dateAndTime\" literally and datetime would silently fall to the date-only branch — so the UIKit spelling is canonical, same reasoning as gradientDirection's capitalised canon."
+      "description": "Date picker mode. datetime is a declared synonym of dateAndTime and the normalizer folds it: sjui and rjui accept both spellings as declared, case and all (sjui matches them literally in selectbox_converter.rb's case arms; rjui's select_box_converter.rb takes a value only when it is a declared spelling, through EnumSpelling.lowered, and lowercases it just for its own case arms), but KotlinJsonUI's DateSelectBox matches \"dateAndTime\" literally and datetime would silently fall to the date-only branch — so the UIKit spelling is canonical, same reasoning as gradientDirection's capitalised canon."
     },
     "datePickerStyle": {
       "type": "string",
@@ -3094,11 +3117,10 @@
     },
     "onValueChange": {
       "type": "binding",
-      "description": "Value change handler - binding only (@{functionName}). The handler receives the new value of the selection binding, the same on every platform: with selectedIndex bound it is the Int index (declare ((Int) -> Void)?, or ((String, Int) -> Void)? for viewId + index); with selectedItem / selectedValue bound it is the String item (declare ((String, String) -> Void)? for viewId + item). A lone (String) parameter is the selected item as a String, with selectedIndex bound too; the viewId comes only as the first of two parameters. (() -> Void)? receives nothing and the ViewModel reads the bound value back."
-    },
-    "onValueChanged": {
-      "type": "binding",
-      "description": "Value change handler (alias for onValueChange) - binding only (@{functionName})"
+      "description": "Value change handler - binding only (@{functionName}). The handler receives the new value of the selection binding, the same on every platform: with selectedIndex bound it is the Int index (declare ((Int) -> Void)?, or ((String, Int) -> Void)? for viewId + index); with selectedItem / selectedValue bound it is the String item (declare ((String, String) -> Void)? for viewId + item). A lone (String) parameter is the selected item as a String, with selectedIndex bound too; the viewId comes only as the first of two parameters. (() -> Void)? receives nothing and the ViewModel reads the bound value back. `onValueChanged` folds here, as on Slider, Collection and CheckBox; it was declared as its own attribute, so the normalizer never folded it and sjui codegen called nothing for it (ticket sjui-selectbox-onvaluechanged-alias-is-never-called).",
+      "aliases": [
+        "onValueChanged"
+      ]
     },
     "colorScheme": {
       "type": "string",
@@ -3564,7 +3586,7 @@
           "Diagonal": "Oblique"
         },
         "default": "Vertical",
-        "description": "Gradient direction. Canon copied from GradientView.gradientDirection, which declared the enum for the same concept while this spelling stayed a bare string. Vertical is the fallback on all three. CASE MATTERS on ios: sjui matches 'Horizontal'/'Oblique' literally (modifier_helper.rb:16) without downcasing, while Compose and web downcase — so the capitalised spellings are canonical and the aliases normalise to them before any converter sees the value. RightToLeft and BottomToTop are declared without an alias on purpose: they are reversed directions web implements (gradient_view_converter.rb:88,90) and the other two have no equivalent, so folding them into Horizontal/Vertical would silently reverse the gradient rather than preserve it.",
+        "description": "Gradient direction. Canon copied from GradientView.gradientDirection, which declared the enum for the same concept while this spelling stayed a bare string. Vertical is the fallback on all three. A value is its declared spelling, case and all (jsonui-cli 1.9.0): sjui matches the capitalised spellings literally (modifier_helper.rb gradient_expression), so 'horizontal' is an undeclared spelling that draws the Vertical fallback; the aliases normalise to the capitalised canon before any converter sees the value. Compose and web do not read this declaration (platform swift); their GradientView converters read GradientView.gradientDirection by the same rule (EnumSpelling.lowered: a declared spelling only, lowercased just for their own case arms). RightToLeft and BottomToTop are declared without an alias on purpose: they are reversed directions (sjui draws them trailing to leading and bottom to top), so folding them into Horizontal/Vertical would silently reverse the gradient rather than preserve it.",
         "platform": "swift"
       },
     "locations": {
@@ -3862,7 +3884,7 @@
         "binding"
       ],
       "min": 1,
-      "description": "Number of columns. Literal int -> static GridCells.Fixed(N) / Array(repeating: ..., count: N). Binding @{prop} -> runtime-resolved data.prop; the Collection always renders on the multi-column grid path (LazyVerticalGrid / LazyHorizontalGrid on Android, LazyVGrid / LazyHGrid on iOS) even when the binding resolves to 1, so the grid layout stays stable across runtime column changes."
+      "description": "Number of columns. Literal int -> static GridCells.Fixed(N) / Array(repeating: ..., count: N). Binding @{prop} -> runtime-resolved data.prop; the Collection always renders on the multi-column grid path (LazyVerticalGrid / LazyHorizontalGrid on Android, LazyVGrid / LazyHGrid on iOS) even when the binding resolves to 1, so the grid layout stays stable across runtime column changes. On a horizontal Collection `columns` is the number of lanes (jsonui-cli 1.9.0; until then every horizontal route drew one lane), and a section's own `columns` is that section block's lanes. A paging Collection draws no lanes: paging is not a lane route, whatever `columns` says."
     },
     "columnSpacing": {
       "type": "number",
@@ -4089,7 +4111,7 @@
         "binding"
       ],
       "binding_direction": "one-way",
-      "description": "Collection page/selection change handler. Canonical; prefer over onPageChanged.",
+      "description": "Collection page/selection change handler. Canonical; prefer over onPageChanged. Called when the page changes — by a swipe, a scrollTo or a currentPage write — with the new page; not called when the pager first appears (ruling 2026-10-02).",
       "platform": [
         "swift",
         "kotlin",
@@ -4836,7 +4858,7 @@
         "binding"
       ],
       "binding_direction": "one-way",
-      "description": "Tab/page selection change handler. Canonical; prefer over onTabChange/onPageChanged.",
+      "description": "Tab/page selection change handler. Canonical; prefer over onTabChange/onPageChanged. Called when the selected tab changes — by a tap on another tab or a selectedIndex write — with the new index; not called when the TabView first appears, nor when the selected tab is tapped again (ruling 2026-10-02).",
       "platform": [
         "swift",
         "kotlin",

package/data/binding_semantics.json

@@ -10,8 +10,8 @@
   },
   "contexts": {
     "text": {
-      "description": "Mixed-text interpolation. A string attribute may contain any number of '@{...}' occurrences with surrounding literal text; each occurrence is replaced by the stringified resolved value.",
-      "interpolation": true,
+      "description": "A text attribute's binding: the whole value is one '@{...}' expression, stringified. A value that mixes literal text with a binding ('Title: @{x}', '@{a} / @{b}') is a warning, binding-mixed-text (ruling 2026-10-02): compose the string in the ViewModel and bind it as one value — a layout holds no logic, and a composed string cannot be localized as one text. Until jsonui-cli 1.9.6 this context declared mixed-text interpolation (each occurrence replaced by its stringified value); sjui and rjui still interpolate such a value and kjui draws its first binding alone, outside any guarantee.",
+      "interpolation": false,
       "features": ["path", "default"],
       "unresolved": "emptyString"
     },
@@ -28,8 +28,8 @@
       "unresolved": "dropKey"
     },
     "nameRef": {
-      "readBy": "Hand-mirrored per face, measured 2026-09-10 and pinned per face: sjui_tools/lib/swiftui/views/base_view_converter.rb (onClick = binding, onclick = bare selector name) pinned by sjui_tools/spec/swiftui/views/handler_name_spelling_spec.rb; kjui_tools/lib/compose/helpers/modifier_builder.rb (camelCase events require the binding form) pinned by kjui_tools/spec/compose/components/handler_name_spelling_spec.rb; rjui_tools/lib/react/converters/base_converter.rb (onClick = binding only, onclick = bare only) pinned by rjui_tools/spec/react/converters/handler_name_spelling_spec.rb. 0 vectors: this context is code generation, not runtime resolution. Known gap, declared here and not a rule: a bare camelCase handler compiles to a no-op with no build-time report (an inline ERROR comment on kjui and rjui, nothing on sjui). A validator rule would need scoping to the declared event attributes first — consumer layouts also use camelCase keys as custom-component props (measured 2026-09-10).",
-      "description": "Event / handler NAME references. The camelCase event attributes (onClick, onAppear, onLongPress, …) take the binding form only: '@{name}' names the handler, and a bare string is NOT a handler on any face (measured 2026-09-10: kjui and rjui emit an inline ERROR comment and no call; sjui emits an empty action). The lowercase `onclick` is the UIKit selector legacy and takes the bare name only. Name extraction, not value resolution: path, default and negation are not applicable. Until 2026-09-10 this entry said the two spellings were equivalent; no generator ever implemented that, and the sentence was corrected to what they do.",
+      "readBy": "Hand-mirrored per face and pinned per face: sjui_tools/lib/swiftui/views/base_view_converter.rb (onClick = binding, onclick = bare selector name; handler_reference? = binding or bare name for the string-declared events) pinned by sjui_tools/spec/swiftui/views/handler_name_spelling_spec.rb and sjui_tools/spec/swiftui/bare_handler_on_string_events_spec.rb; kjui_tools/lib/compose/helpers/modifier_builder.rb pinned by kjui_tools/spec/compose/components/handler_name_spelling_spec.rb; rjui_tools/lib/react/converters/base_converter.rb (onClick = binding only, onclick = bare only) pinned by rjui_tools/spec/react/converters/handler_name_spelling_spec.rb. The binding-only rule is shared/core/binding_validator_core.rb check_bare_event, pinned by each face's spec/core/binding_bare_event_spec.rb, scoped to the types the SSoT declares (consumer layouts use camelCase keys as custom-component props). 0 vectors: this context is code generation, not runtime resolution. Measured 2026-10-02 over 48 event attributes: a bare name on a string-declared event was still dropped by kjui and rjui on a Collection's onValueChange / onItemAppear and TabView onValueChange (sjui calls it from jsonui-cli 1.9.6) — ticket bare-event-handler-is-dropped-without-a-warning.",
+      "description": "Event / handler NAME references. What a camelCase event attribute takes is its declared type (attribute_definitions): declared binding-only (type \"binding\" with no \"string\": onClick, onLongPress, Switch / Slider / Segment / CheckBox / Radio / SelectBox onValueChange, …) it takes '@{name}' only, and a bare string is not a handler — the binding validator reports one (binding-bare-event); declared with \"string\" (onAppear, TextField / TextView onTextChange, TextField onSubmit, a Collection's onValueChange / onItemAppear, TabView onValueChange, …) it takes '@{name}' or the bare name, both naming the data's closure. The lowercase `onclick` is the UIKit selector legacy and takes the bare name only. Name extraction, not value resolution: path, default and negation are not applicable. Until 2026-09-10 this entry said the two spellings were equivalent everywhere, and from then until 2026-10-02 that every camelCase event took the binding form only; neither matched the declarations (the conformance generator writes onAppear's bare name), and the sentence follows the declared types since.",
       "interpolation": false,
       "features": [],
       "unresolved": "platformEventContract"
@@ -122,6 +122,8 @@
     {"id": "binding-negation-context", "severity": "error", "context": "text|embedParams|nameRef|twoWay", "rule": "'!' negation used outside a boolean value context."},
     {"id": "binding-default-in-params", "severity": "error", "context": "embedParams", "rule": "'??' default used in an embed params leaf (defaults belong to the embedded screen's data section)."},
     {"id": "binding-params-array", "severity": "error", "context": "embedParams", "rule": "Array anywhere inside params (pre-existing rule from the embed isolated+params track; restated here)."},
-    {"id": "binding-cell-parent-scope", "severity": "warning", "context": "collectionCell", "rule": "Cell layout binds a key that is only present in the parent screen's data."}
+    {"id": "binding-cell-parent-scope", "severity": "warning", "context": "collectionCell", "rule": "Cell layout binds a key that is only present in the parent screen's data."},
+    {"id": "binding-mixed-text", "severity": "warning", "context": "text|value", "rule": "A value of an attribute the component declares holds a binding and is not one binding (literal text around it, or two bindings). Compose the string in the ViewModel (it also keeps the text localizable) and bind it as one value; a layout holds no logic."},
+    {"id": "binding-bare-event", "severity": "warning", "context": "nameRef", "rule": "A bare name given to an event attribute of a declared type whose declared type is binding-only (\"binding\" with no \"string\")."}
   ]
 }

package/data/component_metadata.json

@@ -43,7 +43,7 @@
       }
     },
     "rules": [
-      "text attribute supports interpolation with @{binding} syntax",
+      "text is a literal or one binding (@{name}); a value that mixes literal text with a binding is the binding-mixed-text warning",
       "partialAttributes allows styling ranges within text",
       "linkable enables auto-detection of URLs",
       "Frame alignment must be .leading for textAlign to work correctly (Swift)"

package/dist/spec_texts.d.ts

@@ -0,0 +1,18 @@
+export declare const TEXT_KEYS: readonly string[];
+export declare const TEXT_KEY_SCOPE: Readonly<Record<string, ["not-under" | "only-under", readonly string[]]>>;
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export declare function isTextField(ancestors: readonly string[], key: string): boolean;
+export interface TextsExpansion {
+    /** The spec with each reference expanded, or the input when it has none. */
+    data: unknown;
+    /** How many references were found / expanded. */
+    found: number;
+    expanded: number;
+    /** One line per reference that could not be expanded. */
+    problems: string[];
+    /** Texts files read (relative to the spec's directory). */
+    files: string[];
+}
+export declare function pairedTextsName(specFile: string): string;
+export declare function expandSpecTexts(data: unknown, specPath: string): TextsExpansion;

package/dist/spec_texts.js

@@ -0,0 +1,145 @@
+// Expands `{"md": ...}` prose references in a spec for a reader.
+//
+// A spec's prose fields (TEXT_KEYS below, scoped by TEXT_KEY_SCOPE) may
+// point into a YAML texts file instead of holding the text inline (jsonui-cli
+// shared/core/spec_texts.py is the definition, and `isTextField` mirrors its
+// `is_text_field`):
+//
+//   {"md": "a.b.c"}                   -> <spec name>.texts.yaml, key path a.b.c
+//   {"md": "shared/x.texts.yaml#a.b"} -> that file (relative to the spec)
+//
+// This is a READER, not the validator. It expands what it can and marks what
+// it cannot; the YAML rules (string keys, no '.', no duplicates, ...) are
+// enforced by `jsonui-doc validate spec`, and are deliberately not copied
+// here — a second copy of a rule is the drift this codebase keeps removing.
+//
+// Each reference becomes `{"md": <as written>, "text": <the text>}` rather
+// than the bare text: an agent reading the spec must see both what it says
+// and WHERE it lives, or it edits the JSON and the YAML stays stale. The
+// `text` key is not valid in a spec, so a copy pasted back is refused by the
+// validator instead of silently kept.
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { parse } from "yaml";
+// Mirrors TEXT_KEYS / TEXT_KEY_SCOPE / is_text_field in jsonui-cli
+// shared/core/spec_texts.py. Prose only: a key a tool parses, matches as a
+// name or emits as code is not here, and at the paths TEXT_KEY_SCOPE names
+// the same key is not prose either.
+export const TEXT_KEYS = [
+    "description", "notes", "intent", "purpose", "processing",
+    "handling", "rule", "meaning", "note", "reason", "condition",
+];
+// key -> [mode, ancestor keys]. "not-under": prose unless one of those keys
+// is an ancestor; "only-under": prose only when the first (top-level)
+// ancestor is one of them.
+export const TEXT_KEY_SCOPE = {
+    reason: ["not-under", ["harnessConditions", "canonicalDivergence"]],
+    condition: ["only-under", ["transitions"]],
+};
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export function isTextField(ancestors, key) {
+    if (!TEXT_KEYS.includes(key))
+        return false;
+    const scope = Object.prototype.hasOwnProperty.call(TEXT_KEY_SCOPE, key)
+        ? TEXT_KEY_SCOPE[key]
+        : undefined;
+    if (scope === undefined)
+        return true;
+    const [mode, names] = scope;
+    if (mode === "not-under")
+        return !ancestors.some((a) => names.includes(a));
+    return ancestors.length > 0 && names.includes(ancestors[0]);
+}
+const REF_KEY = "md";
+export function pairedTextsName(specFile) {
+    let name = basename(specFile);
+    for (const suffix of [".spec.json", ".component.json", ".json"]) {
+        if (name.endsWith(suffix)) {
+            name = name.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return `${name}.texts.yaml`;
+}
+function isReference(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value) &&
+        REF_KEY in value);
+}
+export function expandSpecTexts(data, specPath) {
+    const baseDir = dirname(specPath);
+    const paired = pairedTextsName(specPath);
+    const cache = new Map();
+    const result = { data, found: 0, expanded: 0, problems: [], files: [] };
+    const load = (rel) => {
+        if (!cache.has(rel)) {
+            const abs = join(baseDir, rel);
+            if (!existsSync(abs)) {
+                cache.set(rel, new Error(`${rel} does not exist`));
+            }
+            else {
+                try {
+                    cache.set(rel, parse(readFileSync(abs, "utf-8")));
+                    result.files.push(rel);
+                }
+                catch (e) {
+                    cache.set(rel, new Error(`${rel} could not be parsed: ${e.message}`));
+                }
+            }
+        }
+        return cache.get(rel);
+    };
+    const expand = (ref, where) => {
+        result.found += 1;
+        const target = ref[REF_KEY];
+        if (typeof target !== "string" || !target.trim()) {
+            result.problems.push(`${where}: malformed reference`);
+            return ref;
+        }
+        const hash = target.indexOf("#");
+        const file = hash >= 0 ? target.slice(0, hash) : paired;
+        const key = hash >= 0 ? target.slice(hash + 1) : target;
+        const doc = load(file);
+        if (doc instanceof Error) {
+            result.problems.push(`${where}: ${doc.message}`);
+            return ref;
+        }
+        let node = doc;
+        for (const part of key.split(".")) {
+            node = typeof node === "object" && node !== null && !Array.isArray(node)
+                ? node[part]
+                : undefined;
+        }
+        if (typeof node !== "string") {
+            result.problems.push(`${where}: '${file}#${key}' is ${node === undefined ? "not defined" : "not a text"}`);
+            return ref;
+        }
+        result.expanded += 1;
+        return { ...ref, text: node };
+    };
+    const walk = (node, path, inText, ancestors) => {
+        if (Array.isArray(node)) {
+            // `notes: [...]` — each entry is prose too. Deeper lists under a text
+            // key are not prose, so the flag is not carried past one.
+            return node.map((v, i) => walk(v, `${path}[${i}]`, inText && !Array.isArray(v), ancestors));
+        }
+        if (typeof node === "object" && node !== null) {
+            if (isReference(node)) {
+                if (inText)
+                    return expand(node, path);
+                // Outside a prose field the validator refuses it; a reader leaves it.
+                return node;
+            }
+            const out = {};
+            for (const [k, v] of Object.entries(node)) {
+                out[k] = walk(v, path ? `${path}.${k}` : k, isTextField(ancestors, k), [...ancestors, k]);
+            }
+            return out;
+        }
+        return node;
+    };
+    const walked = walk(data, "", false, []);
+    if (result.found > 0)
+        result.data = walked;
+    return result;
+}

package/dist/tools/context/read_spec_file.js

@@ -1,8 +1,18 @@
 import { z } from "zod";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
+import { expandSpecTexts } from "../../spec_texts.js";
 export function register(server, config) {
-    server.tool("read_spec_file", "Read the contents of a screen or component spec file", {
+    server.tool("read_spec_file", "Read the contents of a screen or component spec file. Prose fields " +
+        "(description / notes / intent / purpose / processing / handling / " +
+        "rule / meaning / note / reason — not under harnessConditions or " +
+        "canonicalDivergence — and condition under transitions only) written " +
+        "as {\"md\": \"key\"} live in a " +
+        "YAML texts file (<name>.texts.yaml beside the spec, or " +
+        "{\"md\": \"file.texts.yaml#key\"}); they are returned expanded as " +
+        "{\"md\": ..., \"text\": ...} — edit the text in the YAML file, not " +
+        "here. A spec without such references is returned byte-for-byte. " +
+        "search_specs does not search text held in a texts file.", {
         file: z.string().describe("Filename (e.g., 'login.spec.json' or 'my_card.component.json')"),
         project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
     }, async ({ file, project_dir }) => {
@@ -18,7 +28,29 @@ export function register(server, config) {
                 return { content: [{ type: "text", text: `File not found: ${filePath}` }] };
             }
             const content = readFileSync(filePath, "utf-8");
-            return { content: [{ type: "text", text: content }] };
+            // Only a spec that uses texts references is re-serialised; every
+            // other spec comes back exactly as it is on disk.
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return { content: [{ type: "text", text: content }] };
+            }
+            const texts = expandSpecTexts(parsed, filePath);
+            if (texts.found === 0) {
+                return { content: [{ type: "text", text: content }] };
+            }
+            const blocks = [{ type: "text", text: JSON.stringify(texts.data, null, 2) }];
+            const summary = `texts: ${texts.expanded}/${texts.found} reference(s) expanded as ` +
+                `{"md", "text"} from ${texts.files.join(", ") || "(no file read)"} — ` +
+                `the "text" key is for reading only; edit the YAML file.`;
+            const problems = texts.problems.length
+                ? "\nunresolved (run jsonui-doc validate spec for the full check):\n" +
+                    texts.problems.map((p) => `  - ${p}`).join("\n")
+                : "";
+            blocks.push({ type: "text", text: summary + problems });
+            return { content: blocks };
         }
         catch (e) {
             return { content: [{ type: "text", text: `Error: ${e.message}` }] };

package/docs/design.md

@@ -100,7 +100,7 @@ These are served directly by the `get_modifier_order`,
 | `list_screen_specs` | Screen-spec index with metadata. |
 | `list_component_specs` | Component-spec index with metadata. |
 | `list_layouts` | Layout JSON inventory. |
-| `read_spec_file` | One spec file (no parsing beyond `JSON.parse`). |
+| `read_spec_file` | One spec file. Byte-for-byte unless it carries `{"md": ...}` prose references (jsonui-cli `shared/core/spec_texts.py`); those are expanded to `{"md", "text"}` from the YAML texts file by `src/spec_texts.ts` — a reader only, the YAML rules stay in `jsonui-doc validate`. Which fields are prose is path-aware and mirrors `is_text_field` (description / notes / intent / purpose / processing / handling / rule / meaning / note / reason — not under `harnessConditions` / `canonicalDivergence` — and `condition` under top-level `transitions` only). `search_specs` does not search texts-file text. |
 | `read_layout_file` | One layout JSON file. |
 
 ### Group C — `jui` CLI wrappers (8)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.14.0",
+  "version": "2.15.2",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {
@@ -15,6 +15,7 @@
   "type": "module",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.9.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/scripts/fetch-definitions.js

@@ -44,7 +44,7 @@ const DATA_DIR = join(PROJECT_ROOT, "data");
 //   3. `npm run fetch-definitions` and commit the data/ diff together with
 //      this pin in one commit
 // JSONUI_CLI_RAW_BASE still overrides the whole base URL for manual testing.
-const JSONUI_CLI_TAG = "v1.9.0";
+const JSONUI_CLI_TAG = "v1.9.7";
 const BASE_URL =
   process.env.JSONUI_CLI_RAW_BASE ||
   `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;

package/src/spec_texts.ts

@@ -0,0 +1,167 @@
+// Expands `{"md": ...}` prose references in a spec for a reader.
+//
+// A spec's prose fields (TEXT_KEYS below, scoped by TEXT_KEY_SCOPE) may
+// point into a YAML texts file instead of holding the text inline (jsonui-cli
+// shared/core/spec_texts.py is the definition, and `isTextField` mirrors its
+// `is_text_field`):
+//
+//   {"md": "a.b.c"}                   -> <spec name>.texts.yaml, key path a.b.c
+//   {"md": "shared/x.texts.yaml#a.b"} -> that file (relative to the spec)
+//
+// This is a READER, not the validator. It expands what it can and marks what
+// it cannot; the YAML rules (string keys, no '.', no duplicates, ...) are
+// enforced by `jsonui-doc validate spec`, and are deliberately not copied
+// here — a second copy of a rule is the drift this codebase keeps removing.
+//
+// Each reference becomes `{"md": <as written>, "text": <the text>}` rather
+// than the bare text: an agent reading the spec must see both what it says
+// and WHERE it lives, or it edits the JSON and the YAML stays stale. The
+// `text` key is not valid in a spec, so a copy pasted back is refused by the
+// validator instead of silently kept.
+
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join } from "path";
+import { parse } from "yaml";
+
+// Mirrors TEXT_KEYS / TEXT_KEY_SCOPE / is_text_field in jsonui-cli
+// shared/core/spec_texts.py. Prose only: a key a tool parses, matches as a
+// name or emits as code is not here, and at the paths TEXT_KEY_SCOPE names
+// the same key is not prose either.
+export const TEXT_KEYS: readonly string[] = [
+  "description", "notes", "intent", "purpose", "processing",
+  "handling", "rule", "meaning", "note", "reason", "condition",
+];
+
+// key -> [mode, ancestor keys]. "not-under": prose unless one of those keys
+// is an ancestor; "only-under": prose only when the first (top-level)
+// ancestor is one of them.
+export const TEXT_KEY_SCOPE: Readonly<Record<string, ["not-under" | "only-under", readonly string[]]>> = {
+  reason: ["not-under", ["harnessConditions", "canonicalDivergence"]],
+  condition: ["only-under", ["transitions"]],
+};
+
+/** Whether `key`, reached through `ancestors` (the dict keys above it, list
+ * indices left out), is a prose field a reference may stand in. */
+export function isTextField(ancestors: readonly string[], key: string): boolean {
+  if (!TEXT_KEYS.includes(key)) return false;
+  const scope = Object.prototype.hasOwnProperty.call(TEXT_KEY_SCOPE, key)
+    ? TEXT_KEY_SCOPE[key]
+    : undefined;
+  if (scope === undefined) return true;
+  const [mode, names] = scope;
+  if (mode === "not-under") return !ancestors.some((a) => names.includes(a));
+  return ancestors.length > 0 && names.includes(ancestors[0]);
+}
+const REF_KEY = "md";
+
+export interface TextsExpansion {
+  /** The spec with each reference expanded, or the input when it has none. */
+  data: unknown;
+  /** How many references were found / expanded. */
+  found: number;
+  expanded: number;
+  /** One line per reference that could not be expanded. */
+  problems: string[];
+  /** Texts files read (relative to the spec's directory). */
+  files: string[];
+}
+
+export function pairedTextsName(specFile: string): string {
+  let name = basename(specFile);
+  for (const suffix of [".spec.json", ".component.json", ".json"]) {
+    if (name.endsWith(suffix)) {
+      name = name.slice(0, -suffix.length);
+      break;
+    }
+  }
+  return `${name}.texts.yaml`;
+}
+
+function isReference(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" && value !== null && !Array.isArray(value) &&
+    REF_KEY in (value as object)
+  );
+}
+
+export function expandSpecTexts(data: unknown, specPath: string): TextsExpansion {
+  const baseDir = dirname(specPath);
+  const paired = pairedTextsName(specPath);
+  const cache = new Map<string, unknown | Error>();
+  const result: TextsExpansion = { data, found: 0, expanded: 0, problems: [], files: [] };
+
+  const load = (rel: string): unknown | Error => {
+    if (!cache.has(rel)) {
+      const abs = join(baseDir, rel);
+      if (!existsSync(abs)) {
+        cache.set(rel, new Error(`${rel} does not exist`));
+      } else {
+        try {
+          cache.set(rel, parse(readFileSync(abs, "utf-8")));
+          result.files.push(rel);
+        } catch (e: any) {
+          cache.set(rel, new Error(`${rel} could not be parsed: ${e.message}`));
+        }
+      }
+    }
+    return cache.get(rel);
+  };
+
+  const expand = (ref: Record<string, unknown>, where: string): unknown => {
+    result.found += 1;
+    const target = ref[REF_KEY];
+    if (typeof target !== "string" || !target.trim()) {
+      result.problems.push(`${where}: malformed reference`);
+      return ref;
+    }
+    const hash = target.indexOf("#");
+    const file = hash >= 0 ? target.slice(0, hash) : paired;
+    const key = hash >= 0 ? target.slice(hash + 1) : target;
+    const doc = load(file);
+    if (doc instanceof Error) {
+      result.problems.push(`${where}: ${doc.message}`);
+      return ref;
+    }
+    let node: unknown = doc;
+    for (const part of key.split(".")) {
+      node = typeof node === "object" && node !== null && !Array.isArray(node)
+        ? (node as Record<string, unknown>)[part]
+        : undefined;
+    }
+    if (typeof node !== "string") {
+      result.problems.push(
+        `${where}: '${file}#${key}' is ${node === undefined ? "not defined" : "not a text"}`);
+      return ref;
+    }
+    result.expanded += 1;
+    return { ...ref, text: node };
+  };
+
+  const walk = (
+    node: unknown, path: string, inText: boolean, ancestors: readonly string[],
+  ): unknown => {
+    if (Array.isArray(node)) {
+      // `notes: [...]` — each entry is prose too. Deeper lists under a text
+      // key are not prose, so the flag is not carried past one.
+      return node.map((v, i) =>
+        walk(v, `${path}[${i}]`, inText && !Array.isArray(v), ancestors));
+    }
+    if (typeof node === "object" && node !== null) {
+      if (isReference(node)) {
+        if (inText) return expand(node, path);
+        // Outside a prose field the validator refuses it; a reader leaves it.
+        return node;
+      }
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node)) {
+        out[k] = walk(v, path ? `${path}.${k}` : k, isTextField(ancestors, k), [...ancestors, k]);
+      }
+      return out;
+    }
+    return node;
+  };
+
+  const walked = walk(data, "", false, []);
+  if (result.found > 0) result.data = walked;
+  return result;
+}

package/src/tools/context/read_spec_file.ts

@@ -3,11 +3,21 @@ import { z } from "zod";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { ServerConfig } from "../../config.js";
+import { expandSpecTexts } from "../../spec_texts.js";
 
 export function register(server: McpServer, config: ServerConfig) {
   server.tool(
     "read_spec_file",
-    "Read the contents of a screen or component spec file",
+    "Read the contents of a screen or component spec file. Prose fields " +
+      "(description / notes / intent / purpose / processing / handling / " +
+      "rule / meaning / note / reason — not under harnessConditions or " +
+      "canonicalDivergence — and condition under transitions only) written " +
+      "as {\"md\": \"key\"} live in a " +
+      "YAML texts file (<name>.texts.yaml beside the spec, or " +
+      "{\"md\": \"file.texts.yaml#key\"}); they are returned expanded as " +
+      "{\"md\": ..., \"text\": ...} — edit the text in the YAML file, not " +
+      "here. A spec without such references is returned byte-for-byte. " +
+      "search_specs does not search text held in a texts file.",
     {
       file: z.string().describe("Filename (e.g., 'login.spec.json' or 'my_card.component.json')"),
       project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
@@ -29,7 +39,29 @@ export function register(server: McpServer, config: ServerConfig) {
         }
 
         const content = readFileSync(filePath, "utf-8");
-        return { content: [{ type: "text", text: content }] };
+        // Only a spec that uses texts references is re-serialised; every
+        // other spec comes back exactly as it is on disk.
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(content);
+        } catch {
+          return { content: [{ type: "text", text: content }] };
+        }
+        const texts = expandSpecTexts(parsed, filePath);
+        if (texts.found === 0) {
+          return { content: [{ type: "text", text: content }] };
+        }
+        const blocks = [{ type: "text" as const, text: JSON.stringify(texts.data, null, 2) }];
+        const summary =
+          `texts: ${texts.expanded}/${texts.found} reference(s) expanded as ` +
+          `{"md", "text"} from ${texts.files.join(", ") || "(no file read)"} — ` +
+          `the "text" key is for reading only; edit the YAML file.`;
+        const problems = texts.problems.length
+          ? "\nunresolved (run jsonui-doc validate spec for the full check):\n" +
+            texts.problems.map((p) => `  - ${p}`).join("\n")
+          : "";
+        blocks.push({ type: "text" as const, text: summary + problems });
+        return { content: blocks };
       } catch (e: any) {
         return { content: [{ type: "text", text: `Error: ${e.message}` }] };
       }

package/tests/tools_context.test.ts

@@ -2,11 +2,12 @@
  * Group B tools (project context) — exercised against a tmp-dir fixture
  * project (jui.config.json + specs + layouts). No real project is touched.
  */
-import { symlinkSync, writeFileSync } from "fs";
+import { mkdirSync, symlinkSync, writeFileSync } from "fs";
 import { join } from "path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { ServerConfig } from "../src/config.js";
+import { isTextField } from "../src/spec_texts.js";
 import { register as registerGetProjectConfig } from "../src/tools/context/get_project_config.js";
 import { register as registerListScreenSpecs } from "../src/tools/context/list_screen_specs.js";
 import { register as registerListComponentSpecs } from "../src/tools/context/list_component_specs.js";
@@ -341,6 +342,115 @@ describe("read_spec_file", () => {
   });
 });
 
+describe("read_spec_file — texts-file prose", () => {
+  // `{"md": ...}` in a prose field (description / notes / intent / ...,
+  // path-scoped for reason and condition) points into a YAML file
+  // (jsonui-cli shared/core/spec_texts.py). The reader expands it next to the
+  // reference, so an agent sees the text AND where to edit it.
+  const specDir = () => join(projectDir, "docs/screens/json");
+  const spec = {
+    type: "app_contracts_spec",
+    version: "1.0",
+    metadata: { name: "app", description: { md: "overview" } },
+    unitContracts: [
+      {
+        target: "ApiClient",
+        cases: [
+          { name: "retries", intent: { md: "cases.api.retries" } },
+          { name: "shared", intent: { md: "shared/net.texts.yaml#timeout" } },
+          { name: "inline", intent: "plain" },
+        ],
+      },
+    ],
+  };
+
+  async function callFull(file: string) {
+    const tool = harness.tools.get("read_spec_file")!;
+    const result = await tool.handler({ file, project_dir: projectDir });
+    return result.content.map((c: { text: string }) => c.text);
+  }
+
+  beforeEach(() => {
+    writeJson(join(specDir(), "app.spec.json"), spec);
+    writeFileSync(
+      join(specDir(), "app.texts.yaml"),
+      "overview: |\n  # Title\n\n  - item\ncases:\n  api:\n    retries: \"**once**\"\n"
+    );
+  });
+
+  it("expands paired and named references as {md, text}", async () => {
+    const shared = join(specDir(), "shared");
+    mkdirSync(shared, { recursive: true });
+    writeFileSync(join(shared, "net.texts.yaml"), "timeout: ten seconds\n");
+    const [json, summary] = await callFull("app.spec.json");
+    const data = JSON.parse(json);
+    expect(data.metadata.description).toEqual({ md: "overview", text: "# Title\n\n- item\n" });
+    const cases = data.unitContracts[0].cases;
+    expect(cases[0].intent).toEqual({ md: "cases.api.retries", text: "**once**" });
+    expect(cases[1].intent.text).toBe("ten seconds");
+    expect(cases[2].intent).toBe("plain");
+    expect(summary).toContain("3/3 reference(s) expanded");
+    expect(summary).toContain("edit the YAML file");
+  });
+
+  it("names a reference it cannot expand and leaves it as written", async () => {
+    const [json, summary] = await callFull("app.spec.json");
+    const cases = JSON.parse(json).unitContracts[0].cases;
+    expect(cases[1].intent).toEqual({ md: "shared/net.texts.yaml#timeout" });
+    expect(summary).toContain("2/3 reference(s) expanded");
+    expect(summary).toContain("shared/net.texts.yaml does not exist");
+  });
+
+  it("expands purpose / reason / condition-under-transitions, and leaves reason and condition where they are not prose", async () => {
+    const scoped = {
+      type: "screen_spec",
+      metadata: { name: "Scoped" },
+      decorativeElements: [{ id: "bg", purpose: { md: "p" } }],
+      apiOutcomeRules: [{ op: "get", reason: { md: "r" } }],
+      transitions: [{ destination: "Next", condition: { md: "c" } }],
+      harnessConditions: [{ name: "h", reason: { md: "r" } }],
+      contracts: { canonicalDivergence: [{ reason: { md: "r" } }] },
+      displayLogic: [{ condition: { md: "c" } }],
+      navigation: { transitions: [{ condition: { md: "c" } }] },
+    };
+    writeJson(join(specDir(), "scoped.spec.json"), scoped);
+    writeFileSync(join(specDir(), "scoped.texts.yaml"), "p: the purpose\nr: the reason\nc: the condition\n");
+    const [json, summary] = await callFull("scoped.spec.json");
+    const data = JSON.parse(json);
+    expect(data.decorativeElements[0].purpose).toEqual({ md: "p", text: "the purpose" });
+    expect(data.apiOutcomeRules[0].reason).toEqual({ md: "r", text: "the reason" });
+    expect(data.transitions[0].condition).toEqual({ md: "c", text: "the condition" });
+    // Not prose at these paths: found, left exactly as written.
+    expect(data.harnessConditions[0].reason).toEqual({ md: "r" });
+    expect(data.contracts.canonicalDivergence[0].reason).toEqual({ md: "r" });
+    expect(data.displayLogic[0].condition).toEqual({ md: "c" });
+    // `transitions` must be the FIRST ancestor, not any ancestor.
+    expect(data.navigation.transitions[0].condition).toEqual({ md: "c" });
+    expect(summary).toContain("3/3 reference(s) expanded");
+  });
+
+  it("isTextField matches jsonui-cli is_text_field", () => {
+    expect(isTextField([], "description")).toBe(true);
+    expect(isTextField(["userActions"], "processing")).toBe(true);
+    expect(isTextField(["apiOutcomeRules"], "reason")).toBe(true);
+    expect(isTextField(["harnessConditions"], "reason")).toBe(false);
+    expect(isTextField(["x", "canonicalDivergence", "y"], "reason")).toBe(false);
+    expect(isTextField(["transitions"], "condition")).toBe(true);
+    expect(isTextField([], "condition")).toBe(false);
+    expect(isTextField(["validation", "serverSide"], "condition")).toBe(false);
+    expect(isTextField(["a", "transitions"], "condition")).toBe(false);
+    expect(isTextField([], "displayName")).toBe(false);
+    expect(isTextField([], "toString")).toBe(false);
+  });
+
+  it("returns a spec without references byte-for-byte", async () => {
+    const raw = '{"type":"screen_spec",  "metadata":{"name":"X","description":"a\\nb"}}';
+    writeFileSync(join(specDir(), "raw.spec.json"), raw);
+    const texts = await callFull("raw.spec.json");
+    expect(texts).toEqual([raw]);
+  });
+});
+
 describe("read_layout_file", () => {
   it("reads a top-level layout", async () => {
     const text = await harness.call("read_layout_file", {