jui-tools-mcp-server 2.7.0 → 2.8.0

package/data/platform_semantics.json

@@ -0,0 +1,70 @@
+{
+  "version": 1,
+  "title": "Platform-scoped layout semantics",
+  "purpose": "How to make a node render differently (or not at all) on one platform: the node-level 'platform' directive, the layout-root 'platforms' whitelist, and how they differ from 'responsive'. Canonical implementation: jui_tools/jui_cli/core/platform_resolver.py — this file restates it for lookup and must follow it, never lead it.",
+  "keywords": [
+    "platform", "platforms", "ios only", "android only", "web only",
+    "per-platform", "override", "platform-specific", "platform limited",
+    "プラットフォーム", "限定", "出し分け", "iosだけ", "androidだけ", "webだけ",
+    "プラットフォーム別", "機種別"
+  ],
+  "nodeDirective": {
+    "attribute": "platform",
+    "consumedAt": "distribution (jui build). The key never appears in distributed per-platform output; platform-specific emit is produced from it.",
+    "objectForm": {
+      "summary": "Per-platform attribute overrides, merged into the node for the matching platform only. Override wins over the base value; merge is per top-level key (the override value replaces the base value for that key wholesale — it is not deep-merged into it).",
+      "example": {
+        "prompt": "Change fontColor only on iOS",
+        "layout": {
+          "type": "Label",
+          "text": "@{title}",
+          "fontColor": "#333333",
+          "platform": { "ios": { "fontColor": "#FFD700" } }
+        },
+        "resolved": {
+          "ios": { "type": "Label", "text": "@{title}", "fontColor": "#FFD700" },
+          "android": { "type": "Label", "text": "@{title}", "fontColor": "#333333" },
+          "web": { "type": "Label", "text": "@{title}", "fontColor": "#333333" }
+        }
+      },
+      "multiPlatformExample": {
+        "prompt": "Different heights everywhere, plus a web-only extra attribute",
+        "layout": {
+          "type": "View",
+          "height": 200,
+          "platform": {
+            "ios": { "height": 220 },
+            "android": { "height": 180 },
+            "web": { "height": "100vh", "maxWidth": 1200 }
+          }
+        }
+      },
+      "detection": "A dict counts as an override map ONLY when every key is one of 'ios' / 'android' / 'web'. Any other key (e.g. a stray 'class') makes the whole value a non-override, so nothing merges — keep override maps pure.",
+      "nesting": "Override values are themselves resolved recursively, so an override may contain child nodes with their own 'platform' directives."
+    },
+    "stringForm": {
+      "summary": "Node filter: the node (and its whole subtree) is DROPPED on platforms that do not match. Comma-separated tokens allowed.",
+      "example": {
+        "prompt": "Render this node on Android only",
+        "layout": { "type": "View", "platform": "android", "child": [] }
+      },
+      "tokens": {
+        "ios": ["ios", "swift", "swiftui", "uikit"],
+        "android": ["android", "kotlin", "java", "compose", "xml"],
+        "web": ["web", "typescript", "javascript", "react"]
+      }
+    }
+  },
+  "layoutRootPlatforms": {
+    "attribute": "platforms",
+    "summary": "Layout-root array whitelisting the distribution targets of the ENTIRE file (e.g. [\"ios\", \"android\"]). Distinct from the node-level 'platform' directive: 'platforms' picks which platforms get the file at all; 'platform' shapes a single node per platform."
+  },
+  "vsResponsive": {
+    "summary": "'responsive' is resolved at RUNTIME by each platform's framework (window size class / orientation); 'platform' is resolved at BUILD time and is invisible at runtime. Use 'platform' for per-OS differences, 'responsive' for per-form-factor differences. The resolver leaves 'responsive' untouched."
+  },
+  "authoringGuidance": {
+    "spec": "Screen specs stay platform-agnostic; when a node intentionally differs per platform, note the difference in the spec text of the section that owns the node (do not fork the spec per platform). Large screens split into sub-specs list them in the parent's 'subSpecs' array — the sub-spec that owns the node carries the note.",
+    "precedence": "Per-node 'platform' override > inline base attribute > 'style'-provided value. Distribution bakes the override into the node as a plain inline attribute; style merge (applied later, at codegen or dynamic runtime) always yields to inline attributes.",
+    "dynamicFace": "Distribution has already resolved 'platform' by the time a layout reaches a device, so the dynamic face never sees the key either — declaring it costs nothing at runtime on any face."
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {

package/scripts/fetch-manifest.js

@@ -33,6 +33,13 @@ export const FILES = [
     remote: "shared/core/attribute_semantics.json",
     local: "attribute_semantics.json",
   },
+  // Canonical platform-scoping semantics (node 'platform' directive, root
+  // 'platforms', vs 'responsive') — backs get_platform_rules and the
+  // search-side topic-guide index.
+  {
+    remote: "shared/core/platform_semantics.json",
+    local: "platform_semantics.json",
+  },
   // Canonical binding-resolution semantics. This was bundled in data/ but
   // missing from FILES, so the snapshot only ever refreshed by hand and
   // silently went stale — the same trap the screen-identity asset would

package/src/index.ts

@@ -14,6 +14,7 @@ import { register as registerGetBindingRules } from "./tools/spec/get_binding_ru
 import { register as registerGetScreenIdentity } from "./tools/spec/get_screen_identity.js";
 import { register as registerGetPlatformMapping } from "./tools/spec/get_platform_mapping.js";
 import { register as registerGetDataSource } from "./tools/spec/get_data_source.js";
+import { register as registerGetPlatformRules } from "./tools/spec/get_platform_rules.js";
 
 // --- Group B: Project Context ---
 import { register as registerGetProjectConfig } from "./tools/context/get_project_config.js";
@@ -22,6 +23,7 @@ import { register as registerListComponentSpecs } from "./tools/context/list_com
 import { register as registerListLayouts } from "./tools/context/list_layouts.js";
 import { register as registerReadSpecFile } from "./tools/context/read_spec_file.js";
 import { register as registerReadLayoutFile } from "./tools/context/read_layout_file.js";
+import { register as registerSearchSpecs } from "./tools/context/search_specs.js";
 
 // --- Group C: jui CLI ---
 import { register as registerJuiInit } from "./tools/jui/jui_init.js";
@@ -89,7 +91,7 @@ log(
 // Initialize server config for Groups B/C/D
 const config = new ServerConfig();
 
-// Register Group A: Component Spec Lookup (7 tools)
+// Register Group A: Component Spec Lookup (9 tools)
 registerLookupComponent(server, loader);
 registerLookupAttribute(server, loader);
 registerSearchComponents(server, loader);
@@ -98,14 +100,16 @@ registerGetBindingRules(server, loader);
 registerGetScreenIdentity(server, loader);
 registerGetPlatformMapping(server, loader);
 registerGetDataSource(server, loader);
+registerGetPlatformRules(server, loader);
 
-// Register Group B: Project Context (6 tools)
+// Register Group B: Project Context (7 tools)
 registerGetProjectConfig(server, config);
 registerListScreenSpecs(server, config);
 registerListComponentSpecs(server, config);
 registerListLayouts(server, config);
 registerReadSpecFile(server, config);
 registerReadLayoutFile(server, config);
+registerSearchSpecs(server, config);
 
 // Register Group C: jui CLI (8 tools)
 registerJuiInit(server, config);

package/src/spec_loader.ts

@@ -61,6 +61,10 @@ export interface DataSourceInfo {
   /// contract (cross-effect rulings, plan 33). Optional: absent on older
   /// jsonui-cli checkouts.
   attributeSemantics: FileInfo | null;
+  /// shared/core/platform_semantics.json — platform-scoped layout semantics
+  /// (the node-level 'platform' directive, root 'platforms', vs
+  /// 'responsive'). Optional: absent on older jsonui-cli checkouts.
+  platformSemantics: FileInfo | null;
   /// conformance/coverage.json — declared-but-unimplemented (component,
   /// attribute, platform) pairs with their recorded reasons. Optional: absent
   /// on older jsonui-cli checkouts.
@@ -102,6 +106,7 @@ export class SpecLoader {
   private commonAttributesRaw: Record<string, any> = {};
   private bindingSemantics: Record<string, any> | null = null;
   private attributeSemantics: Record<string, any> | null = null;
+  private platformSemantics: Record<string, any> | null = null;
   /// `${component}.${attribute}` -> [{platform, reason, note}] from the
   /// coverage ledger. The ledger tracks pairs that ARE declared (platform
   /// field includes them) but that the platform's codegen does not consume —
@@ -243,9 +248,56 @@ export class SpecLoader {
       }
     }
 
+    // Topic-guide index: task vocabulary ("iOSだけ色を変える", "ios only",
+    // "platform override") does not contain any component or attribute
+    // name, so the loops above can't surface the mechanism. Each guide
+    // declares its own keywords (en + ja) in its semantics file; a hit
+    // pins a pointer to the dedicated tool at the top of the results.
+    for (const guide of this.topicGuides()) {
+      const hit = guide.keywords.some(
+        (kw) => q.includes(kw) || (q.length >= 3 && kw.includes(q))
+      );
+      if (hit) {
+        results.push({
+          guide: guide.topic,
+          score: 100,
+          matches: [guide.summary],
+          nextTool: guide.tool,
+        });
+      }
+    }
+
     return results.sort((a, b) => b.score - a.score);
   }
 
+  /** Keyword-indexed topical guides, each backed by a dedicated MCP tool. */
+  private topicGuides(): Array<{
+    topic: string;
+    tool: string;
+    summary: string;
+    keywords: string[];
+  }> {
+    const guides: Array<{
+      topic: string;
+      tool: string;
+      summary: string;
+      keywords: string[];
+    }> = [];
+    if (this.platformSemantics) {
+      const kws = Array.isArray(this.platformSemantics.keywords)
+        ? (this.platformSemantics.keywords as string[])
+        : [];
+      guides.push({
+        topic: "platform_rules",
+        tool: "get_platform_rules",
+        summary:
+          "Per-platform styling/visibility (e.g. change fontColor on iOS only): node-level 'platform' directive (object form = per-platform overrides, string form = platform filter), root 'platforms' whitelist, vs 'responsive'. Call get_platform_rules for the full semantics with examples.",
+        keywords: kws.map((k) => k.toLowerCase()),
+      });
+    }
+    return guides;
+  }
+
   getModifierOrder(platform?: string): any {
     if (platform) return (MODIFIER_ORDER as any)[platform] || null;
     return MODIFIER_ORDER;
@@ -275,6 +327,7 @@ export class SpecLoader {
       this.dataSource.screenIdentity,
       this.dataSource.bindingSemantics,
       this.dataSource.attributeSemantics,
+      this.dataSource.platformSemantics,
       this.dataSource.coverage,
     ].filter((f): f is FileInfo => f != null);
 
@@ -309,6 +362,15 @@ export class SpecLoader {
     };
   }
 
+  getPlatformRules(): any {
+    // Canonical platform-scoping semantics (SSoT:
+    // shared/core/platform_semantics.json — restates
+    // jui_tools/jui_cli/core/platform_resolver.py). Null on jsonui-cli
+    // checkouts that predate the file; the tool reports that instead of
+    // inventing rules.
+    return this.platformSemantics;
+  }
+
   getPlatformMapping(category?: string): any {
     if (category) return (PLATFORM_MAPPING as any)[category] || null;
     return PLATFORM_MAPPING;
@@ -376,6 +438,23 @@ export class SpecLoader {
       this.attributeSemantics = null;
     }
 
+    // Platform-scoped layout semantics (node 'platform' directive, root
+    // 'platforms', vs 'responsive'). Optional for the same backward-compat
+    // reason.
+    let platformSemanticsResolution: FileInfo | null = null;
+    try {
+      const platSemResolution = this.resolveFile(
+        "shared/core/platform_semantics.json",
+        "data/platform_semantics.json"
+      );
+      this.platformSemantics = JSON.parse(
+        readFileSync(platSemResolution.path, "utf-8")
+      ) as Record<string, any>;
+      platformSemanticsResolution = platSemResolution;
+    } catch {
+      this.platformSemantics = null;
+    }
+
     // Canonical screen identity (screen-identity track). Optional so older
     // jsonui-cli checkouts without the file still load.
     try {
@@ -462,6 +541,7 @@ export class SpecLoader {
       screenIdentity: screenIdentityResolution,
       bindingSemantics: bindingResolution,
       attributeSemantics: attributeSemanticsResolution,
+      platformSemantics: platformSemanticsResolution,
       coverage: coverageResolution,
       componentCount,
       commonAttributeCount: Object.keys(this.commonAttributesRaw).filter(

package/src/tools/context/list_screen_specs.ts

@@ -22,20 +22,38 @@ export function register(server: McpServer, config: ServerConfig) {
         }
 
         const files = readdirSync(specDir).filter((f) => f.endsWith(".spec.json"));
-        const specs = files.map((file) => {
+        const specs: any[] = [];
+        for (const file of files) {
           try {
             const data = JSON.parse(readFileSync(join(specDir, file), "utf-8"));
-            return {
+            specs.push({
               file,
               name: data.metadata?.name || file.replace(".spec.json", ""),
               displayName: data.metadata?.displayName || "",
               type: data.type || "screen_spec",
               layoutFile: data.metadata?.layoutFile || null,
-            };
+            });
+            // A parent spec splits one screen across sub-spec files (its
+            // 'subSpecs' array). Surface them inline so a session can see
+            // the split and read_spec_file the right part without first
+            // opening the parent.
+            if (Array.isArray(data.subSpecs)) {
+              for (const sub of data.subSpecs) {
+                if (!sub?.file) continue;
+                specs.push({
+                  file: sub.file,
+                  name: sub.name || sub.file,
+                  displayName: sub.description || "",
+                  type: "screen_sub_spec",
+                  parent: file,
+                  layoutFile: data.metadata?.layoutFile || null,
+                });
+              }
+            }
           } catch {
-            return { file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null };
+            specs.push({ file, name: file.replace(".spec.json", ""), displayName: "", type: "unknown", layoutFile: null });
           }
-        });
+        }
 
         return { content: [{ type: "text", text: JSON.stringify(specs, null, 2) }] };
       } catch (e: any) {

package/src/tools/context/search_specs.ts

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join, relative } from "path";
+import { ServerConfig } from "../../config.js";
+
+const MAX_RESULTS = 30;
+const SNIPPET_LEN = 200;
+
+/** Recursively collect *.spec.json / *.component.json under dir. */
+function collectSpecFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) {
+      collectSpecFiles(p, out);
+    } else if (entry.endsWith(".spec.json") || entry.endsWith(".component.json")) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Walk a parsed spec and report the JSON paths whose keys or string values
+ * contain the query. One entry per path, with a short snippet.
+ */
+function findMatches(
+  node: any,
+  q: string,
+  path: string,
+  out: { path: string; snippet: string }[]
+) {
+  if (out.length >= MAX_RESULTS) return;
+  if (typeof node === "string") {
+    if (node.toLowerCase().includes(q)) {
+      out.push({ path, snippet: node.slice(0, SNIPPET_LEN) });
+    }
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => findMatches(v, q, `${path}[${i}]`, out));
+    return;
+  }
+  if (node && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      const childPath = path ? `${path}.${k}` : k;
+      if (k.toLowerCase().includes(q)) {
+        const snippet =
+          typeof v === "string"
+            ? v.slice(0, SNIPPET_LEN)
+            : JSON.stringify(v)?.slice(0, SNIPPET_LEN) ?? "";
+        out.push({ path: childPath, snippet });
+        if (out.length >= MAX_RESULTS) return;
+      }
+      findMatches(v, q, childPath, out);
+      if (out.length >= MAX_RESULTS) return;
+    }
+  }
+}
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "search_specs",
+    "Keyword-search across ALL project spec files (screen specs, sub-specs in subdirectories, component specs). Returns file + JSON path + snippet per match — the fast way to find which spec (or which sub-spec of a split screen) covers a topic",
+    {
+      query: z.string().describe("Search keyword (matched case-insensitively against keys and string values)"),
+      project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    },
+    async ({ query, project_dir }) => {
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const projectConfig = config.readProjectConfig(projectDir);
+        const q = query.toLowerCase();
+        if (!q.trim()) {
+          return { content: [{ type: "text", text: "Empty query." }] };
+        }
+
+        const dirs = new Set<string>();
+        for (const field of ["spec_directory", "component_spec_directory"] as const) {
+          try {
+            const d = config.resolveDir(projectConfig, field, projectDir);
+            if (existsSync(d)) dirs.add(d);
+          } catch {
+            /* directory not configured */
+          }
+        }
+        if (dirs.size === 0) {
+          return { content: [{ type: "text", text: "No spec directories found." }] };
+        }
+
+        const results: any[] = [];
+        for (const dir of dirs) {
+          for (const filePath of collectSpecFiles(dir)) {
+            if (results.length >= MAX_RESULTS) break;
+            let matches: { path: string; snippet: string }[] = [];
+            try {
+              const data = JSON.parse(readFileSync(filePath, "utf-8"));
+              findMatches(data, q, "", matches);
+            } catch {
+              continue;
+            }
+            if (matches.length > 0) {
+              results.push({
+                file: relative(dir, filePath),
+                matchCount: matches.length,
+                matches: matches.slice(0, 5),
+              });
+            }
+          }
+        }
+
+        if (results.length === 0) {
+          return { content: [{ type: "text", text: `No matches for '${query}'.` }] };
+        }
+        results.sort((a, b) => b.matchCount - a.matchCount);
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/spec/get_platform_rules.ts

@@ -0,0 +1,26 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SpecLoader } from "../../spec_loader.js";
+
+export function register(server: McpServer, loader: SpecLoader) {
+  server.tool(
+    "get_platform_rules",
+    "Get platform-scoping rules for layouts: how to change an attribute on one platform only (node-level 'platform' object form, e.g. iOS-only fontColor), how to drop a node per platform (string form + language tokens), the layout-root 'platforms' whitelist, precedence, and how this differs from 'responsive'",
+    {},
+    async () => {
+      const result = loader.getPlatformRules();
+      if (!result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "platform_semantics.json not found — the connected jsonui-cli checkout predates it. Fall back to lookup_attribute('platform') for the short definition.",
+            },
+          ],
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+}

package/tests/snapshot_completeness.test.ts

@@ -45,6 +45,7 @@ function reportedFiles(source: DataSourceInfo) {
     source.screenIdentity,
     source.bindingSemantics,
     source.attributeSemantics,
+    source.platformSemantics,
     source.coverage,
   ].filter((f): f is NonNullable<typeof f> => f != null);
 }

package/tests/spec_loader.test.ts

@@ -386,6 +386,61 @@ describe("SpecLoader spec model", () => {
   });
 });
 
+describe("SpecLoader platform rules + topic-guide search", () => {
+  const SEMANTICS = {
+    version: 1,
+    title: "Platform-scoped layout semantics",
+    keywords: ["platform", "ios only", "iosだけ", "出し分け"],
+    nodeDirective: { attribute: "platform" },
+  };
+
+  function loaderWithSemantics(): SpecLoader {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    writeJson(join(mcpRoot, "data/platform_semantics.json"), SEMANTICS);
+    return new SpecLoader(mcpRoot);
+  }
+
+  it("getPlatformRules returns the semantics file verbatim", () => {
+    expect(loaderWithSemantics().getPlatformRules()).toEqual(SEMANTICS);
+  });
+
+  it("getPlatformRules is null (not invented) without the file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    expect(new SpecLoader(mcpRoot).getPlatformRules()).toBeNull();
+  });
+
+  it("task vocabulary surfaces the guide pointer at the top of search", () => {
+    // No component or attribute name in the query — only the guide can hit.
+    const results = loaderWithSemantics().searchComponents(
+      "iosだけフォントカラーを変えたい"
+    );
+    expect(results[0]).toMatchObject({
+      guide: "platform_rules",
+      nextTool: "get_platform_rules",
+      score: 100,
+    });
+  });
+
+  it("an english task query hits the guide too", () => {
+    const results = loaderWithSemantics().searchComponents("ios only color");
+    expect(results.some((r: any) => r.guide === "platform_rules")).toBe(true);
+  });
+
+  it("guide keywords do not fire on unrelated queries", () => {
+    const results = loaderWithSemantics().searchComponents("zebra");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+
+  it("no guide entries without the semantics file", () => {
+    const mcpRoot = makeTempDir("mcp-root");
+    makeBundledDataset(mcpRoot);
+    const results = new SpecLoader(mcpRoot).searchComponents("ios only");
+    expect(results.every((r: any) => r.guide == null)).toBe(true);
+  });
+});
+
 // ----- root helper ----------------------------------------------------------
 
 describe("mcpRootFromImportMetaUrl", () => {

package/tests/tools_context.test.ts

@@ -13,6 +13,7 @@ import { register as registerListComponentSpecs } from "../src/tools/context/lis
 import { register as registerListLayouts } from "../src/tools/context/list_layouts.js";
 import { register as registerReadSpecFile } from "../src/tools/context/read_spec_file.js";
 import { register as registerReadLayoutFile } from "../src/tools/context/read_layout_file.js";
+import { register as registerSearchSpecs } from "../src/tools/context/search_specs.js";
 import {
   cleanupTempDirs,
   createToolHarness,
@@ -38,8 +39,46 @@ beforeEach(() => {
   registerListLayouts(harness.server, config);
   registerReadSpecFile(harness.server, config);
   registerReadLayoutFile(harness.server, config);
+  registerSearchSpecs(harness.server, config);
 });
 
+/** A screen split across a parent spec + sub-spec files in a subdirectory. */
+function writeSplitSpecFixture(root: string) {
+  writeJson(join(root, "docs/screens/json/messages.spec.json"), {
+    type: "screen_parent_spec",
+    metadata: {
+      name: "Messages",
+      displayName: "Messages Screen",
+      layoutFile: "messages",
+    },
+    subSpecs: [
+      {
+        file: "messages/messages-core.spec.json",
+        name: "Messages - Core",
+        description: "Core structure and message list",
+      },
+      {
+        file: "messages/messages-composer.spec.json",
+        name: "Messages - Composer",
+        description: "Input area and attachments",
+      },
+    ],
+  });
+  writeJson(join(root, "docs/screens/json/messages/messages-core.spec.json"), {
+    type: "screen_spec",
+    metadata: { name: "Messages - Core" },
+    structure: { messageList: { paging: true, currentPage: "@{currentPage}" } },
+  });
+  writeJson(
+    join(root, "docs/screens/json/messages/messages-composer.spec.json"),
+    {
+      type: "screen_spec",
+      metadata: { name: "Messages - Composer" },
+      structure: { attachButton: { note: "opens the attachment sheet" } },
+    }
+  );
+}
+
 afterEach(() => {
   delete process.env.JUI_PROJECT_DIR;
   cleanupTempDirs();
@@ -121,6 +160,81 @@ describe("list_screen_specs", () => {
     const text = await harness.call("list_screen_specs", { project_dir: proj });
     expect(text).toContain("Spec directory not found");
   });
+
+  it("expands a parent spec's subSpecs inline so the split is visible", async () => {
+    writeSplitSpecFixture(projectDir);
+    const specs = JSON.parse(
+      await harness.call("list_screen_specs", { project_dir: projectDir })
+    );
+    const core = specs.find(
+      (s: any) => s.file === "messages/messages-core.spec.json"
+    );
+    expect(core).toEqual({
+      file: "messages/messages-core.spec.json",
+      name: "Messages - Core",
+      displayName: "Core structure and message list",
+      type: "screen_sub_spec",
+      parent: "messages.spec.json",
+      layoutFile: "messages",
+    });
+    // The parent itself still lists normally.
+    expect(
+      specs.find((s: any) => s.file === "messages.spec.json")?.type
+    ).toBe("screen_parent_spec");
+  });
+});
+
+describe("search_specs", () => {
+  it("finds a keyword inside a sub-spec file in a subdirectory", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "currentPage",
+        project_dir: projectDir,
+      })
+    );
+    const hit = results.find(
+      (r: any) => r.file === "messages/messages-core.spec.json"
+    );
+    expect(hit).toBeTruthy();
+    expect(hit.matches[0].path).toContain("structure.messageList");
+    expect(hit.matches[0].snippet).toContain("@{currentPage}");
+  });
+
+  it("matches keys as well as string values, case-insensitively", async () => {
+    writeSplitSpecFixture(projectDir);
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ATTACHMENT",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some(
+        (r: any) => r.file === "messages/messages-composer.spec.json"
+      )
+    ).toBe(true);
+  });
+
+  it("searches component specs too", async () => {
+    const results = JSON.parse(
+      await harness.call("search_specs", {
+        query: "ExampleCard",
+        project_dir: projectDir,
+      })
+    );
+    expect(
+      results.some((r: any) => r.file === "example_card.component.json")
+    ).toBe(true);
+  });
+
+  it("reports no matches as a plain message", async () => {
+    const text = await harness.call("search_specs", {
+      query: "zzz_nothing_zzz",
+      project_dir: projectDir,
+    });
+    expect(text).toContain("No matches");
+  });
 });
 
 describe("list_component_specs", () => {