@malloy-publisher/server 0.0.227 → 0.0.228

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.227",
+   "version": "0.0.228",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"

package/publisher.config.example.bigquery.json

@@ -2,19 +2,19 @@
   "frozenConfig": false,
   "environments": [
     {
-      "name": "malloy-samples",
+      "name": "examples",
       "packages": [
         {
-          "name": "ecommerce",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+          "name": "storefront",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/storefront"
         },
         {
-          "name": "imdb",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+          "name": "governed-analytics",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/governed-analytics"
         },
         {
-          "name": "faa",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+          "name": "html-data-app",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/html-data-app"
         },
         {
           "name": "bigquery-hackernews",

package/publisher.config.example.duckdb.json

@@ -2,19 +2,19 @@
   "frozenConfig": false,
   "environments": [
     {
-      "name": "malloy-samples",
+      "name": "examples",
       "packages": [
         {
-          "name": "ecommerce",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+          "name": "storefront",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/storefront"
         },
         {
-          "name": "imdb",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+          "name": "governed-analytics",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/governed-analytics"
         },
         {
-          "name": "faa",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+          "name": "html-data-app",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/html-data-app"
         }
       ],
       "connections": []

package/publisher.config.json

@@ -2,23 +2,19 @@
   "frozenConfig": false,
   "environments": [
     {
-      "name": "malloy-samples",
+      "name": "examples",
       "packages": [
         {
-          "name": "ecommerce",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+          "name": "storefront",
+          "location": "../../examples/storefront"
         },
         {
-          "name": "imdb",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+          "name": "governed-analytics",
+          "location": "../../examples/governed-analytics"
         },
         {
-          "name": "faa",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
-        },
-        {
-          "name": "faa-givens-demo",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa-givens-demo"
+          "name": "html-data-app",
+          "location": "../../examples/html-data-app"
         }
       ],
       "connections": []

package/src/config.spec.ts

@@ -1040,8 +1040,8 @@ describe("Config path resolution (--config and bundled default)", () => {
 
       expect(result.environments.length).toBeGreaterThan(0);
       const env = result.environments[0];
-      expect(env.name).toBe("malloy-samples");
-      expect(env.packages.some((p) => p.name === "ecommerce")).toBe(true);
+      expect(env.name).toBe("examples");
+      expect(env.packages.some((p) => p.name === "storefront")).toBe(true);
       expect(env.packages.some((p) => p.name === "bigquery-hackernews")).toBe(
          false,
       );

package/src/controller/package.controller.ts

@@ -5,6 +5,13 @@ import { EnvironmentStore } from "../service/environment_store";
 
 type ApiPackage = components["schemas"]["Package"];
 
+/**
+ * Which path a reload took. `in-place` recompiles the tree already on disk and
+ * leaves it alone; `reinstalled` re-fetches from the package's install location,
+ * which overwrites on-disk edits.
+ */
+export type PackageReloadMode = "in-place" | "reinstalled";
+
 /**
  * Everything that is strict-at-publish, joined into one 400 message (or
  * undefined when the package is publishable): invalid explores entries plus
@@ -50,45 +57,69 @@ export class PackageController {
       packageName: string,
       reload: boolean,
    ): Promise<ApiPackage> {
+      if (reload) {
+         return (await this.reloadPackage(environmentName, packageName))
+            .metadata;
+      }
+
       const environment = await this.environmentStore.getEnvironment(
          environmentName,
          false,
       );
-
-      if (reload) {
-         // Resolve the package's source location from the currently-cached
-         // metadata WITHOUT triggering a stale-state reload. If a `location`
-         // is set, route the reload through `installPackage` so that
-         // download-then-load happens atomically; otherwise fall back to an
-         // in-place reload of the existing on-disk content.
-         let location: string | undefined;
-         try {
-            const cached = await environment.getPackage(packageName, false);
-            location = cached.getPackageMetadata().location;
-         } catch {
-            // Not previously loaded — nothing to reinstall from.
-         }
-         if (location) {
-            const reinstalled = await environment.installPackage(
-               packageName,
-               (stagingPath) =>
-                  this.downloadInto(
-                     environmentName,
-                     packageName,
-                     location,
-                     stagingPath,
-                  ),
-            );
-            return reinstalled.getPackageMetadata();
-         }
-         const _package = await environment.getPackage(packageName, true);
-         return _package.getPackageMetadata();
-      }
-
       const _package = await environment.getPackage(packageName, false);
       return _package.getPackageMetadata();
    }
 
+   /**
+    * Reload a package and report WHICH path ran. The two are not equivalent to
+    * anyone holding on-disk edits: an in-place reload recompiles the tree that
+    * is already there, while a reinstall re-fetches from the package's install
+    * location and overwrites it. A caller that surfaces the reload to a user
+    * needs to be able to say which happened, so it is returned rather than
+    * inferred. `getPackage` keeps returning bare metadata, so the REST contract
+    * is unchanged.
+    */
+   public async reloadPackage(
+      environmentName: string,
+      packageName: string,
+   ): Promise<{ metadata: ApiPackage; mode: PackageReloadMode }> {
+      const environment = await this.environmentStore.getEnvironment(
+         environmentName,
+         false,
+      );
+
+      // Resolve the package's source location from the currently-cached
+      // metadata WITHOUT triggering a stale-state reload. If a `location`
+      // is set, route the reload through `installPackage` so that
+      // download-then-load happens atomically; otherwise fall back to an
+      // in-place reload of the existing on-disk content.
+      let location: string | undefined;
+      try {
+         const cached = await environment.getPackage(packageName, false);
+         location = cached.getPackageMetadata().location;
+      } catch {
+         // Not previously loaded, so there is nothing to reinstall from.
+      }
+      if (location) {
+         const reinstalled = await environment.installPackage(
+            packageName,
+            (stagingPath) =>
+               this.downloadInto(
+                  environmentName,
+                  packageName,
+                  location,
+                  stagingPath,
+               ),
+         );
+         return {
+            metadata: reinstalled.getPackageMetadata(),
+            mode: "reinstalled",
+         };
+      }
+      const _package = await environment.getPackage(packageName, true);
+      return { metadata: _package.getPackageMetadata(), mode: "in-place" };
+   }
+
    async addPackage(environmentName: string, body: ApiPackage) {
       if (this.environmentStore.publisherConfigIsFrozen) {
          throw new FrozenConfigError();

package/src/default-publisher.config.json

@@ -2,19 +2,19 @@
   "frozenConfig": false,
   "environments": [
     {
-      "name": "malloy-samples",
+      "name": "examples",
       "packages": [
         {
-          "name": "ecommerce",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+          "name": "storefront",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/storefront"
         },
         {
-          "name": "imdb",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+          "name": "governed-analytics",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/governed-analytics"
         },
         {
-          "name": "faa",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+          "name": "html-data-app",
+          "location": "https://github.com/malloydata/publisher/tree/main/examples/html-data-app"
         }
       ],
       "connections": []

package/src/mcp/handler_utils.spec.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "bun:test";
+import { MalloyError } from "@malloydata/malloy";
+import { classifyToolError } from "./handler_utils";
+import {
+   AccessDeniedError,
+   BadRequestError,
+   ModelCompilationError,
+   PackageNotFoundError,
+   ServiceUnavailableError,
+} from "../errors";
+
+/**
+ * classifyToolError decides what an agent is told to do about a failure, so
+ * every branch is pinned by the advice it produces, not just by "an error came
+ * back". Asserting only that an error exists is what let every class funnel
+ * through the Malloy helper unnoticed.
+ *
+ * The routing is by error CLASS on purpose. getMalloyErrorDetails refines on
+ * message patterns the shipped engine does not emit, so "did it refine?" would
+ * send real compile errors to the internal branch.
+ */
+describe("classifyToolError", () => {
+   const advice = (e: unknown) =>
+      JSON.stringify(classifyToolError("op", "env/pkg", e).suggestions);
+
+   it("homes a missing package as not-found, not as Malloy", () => {
+      const details = classifyToolError(
+         "op",
+         "env/pkg",
+         new PackageNotFoundError("Package 'nope' not found"),
+      );
+      expect(details.message).toContain("Resource not found");
+      expect(JSON.stringify(details.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("homes back-pressure as retryable, not as Malloy", () => {
+      const details = classifyToolError(
+         "op",
+         "env/pkg",
+         new ServiceUnavailableError("Memory limit reached"),
+      );
+      expect(details.message).toContain("Memory limit reached");
+      expect(JSON.stringify(details.suggestions)).toContain("Retry");
+      expect(JSON.stringify(details.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("keeps Malloy advice for a raw engine error", () => {
+      // The regression guard for executeQuery. A bad query throws MalloyError,
+      // NOT ModelCompilationError: the engine's error reaches the tool's catch
+      // unwrapped. Route it by the internal branch and a syntax error tells the
+      // agent an "unexpected internal error occurred", which is worse than the
+      // bug this classifier was written to fix.
+      const details = classifyToolError(
+         "executeQuery",
+         "env/pkg/m.malloy",
+         new MalloyError("unexpected '@'", []),
+      );
+      expect(details.message).not.toContain("unexpected internal error");
+      expect(advice(new MalloyError("unexpected '@'", []))).toContain("Malloy");
+   });
+
+   it("keeps Malloy advice for a wrapped compile error", () => {
+      // What a failed reload throws. #890's promise is that a failed reload
+      // returns the compile errors, so this must not read as an internal fault.
+      const details = classifyToolError(
+         "reloadPackage",
+         "env/pkg",
+         new ModelCompilationError({
+            message: "Error(s) compiling model: unexpected '@'",
+         }),
+      );
+      expect(details.message).not.toContain("unexpected internal error");
+   });
+
+   it("keeps Malloy advice for an authorize denial and a malformed request", () => {
+      expect(
+         classifyToolError(
+            "op",
+            "env/pkg",
+            new AccessDeniedError('Access denied for source "orders"'),
+         ).message,
+      ).not.toContain("unexpected internal error");
+      expect(
+         classifyToolError(
+            "op",
+            "env/pkg",
+            new BadRequestError("Invalid query request."),
+         ).message,
+      ).not.toContain("unexpected internal error");
+   });
+
+   it("reports anything else as internal rather than blaming the Malloy", () => {
+      // A bug in our own code, a filesystem failure, or a worker crash. Telling
+      // the agent to check its syntax sends it to edit a model that is fine.
+      for (const error of [
+         new TypeError("cannot read properties of undefined"),
+         Object.assign(new Error("EACCES: permission denied"), {
+            code: "EACCES",
+         }),
+      ]) {
+         const details = classifyToolError("op", "env/pkg", error);
+         expect(details.message).toContain("unexpected internal error");
+         expect(JSON.stringify(details.suggestions)).not.toContain(
+            "Malloy file",
+         );
+      }
+   });
+});

package/src/mcp/handler_utils.ts

@@ -1,10 +1,15 @@
+import { MalloyError } from "@malloydata/malloy";
 import { EnvironmentStore } from "../service/environment_store";
 import {
    AccessDeniedError,
+   BadRequestError,
    PackageNotFoundError,
    ModelNotFoundError,
    ModelCompilationError,
    EnvironmentNotFoundError,
+   NotQueryableError,
+   PayloadTooLargeError,
+   QueryTimeoutError,
    ServiceUnavailableError,
 } from "../errors";
 import {
@@ -16,6 +21,98 @@ import {
 import type { Model } from "../service/model";
 import { logger } from "../logger";
 
+/**
+ * Remediation for a ServiceUnavailableError, shared by every caller that homes
+ * one. The error covers both the memory governor and the concurrency slots, so
+ * the wording names both rather than only memory.
+ */
+export const BACK_PRESSURE_SUGGESTIONS: readonly string[] = [
+   "Retry once the publisher is below its configured memory or concurrency limit.",
+   "If this persists, raise the limit or scale up the pod.",
+];
+
+/**
+ * Turns a thrown error into agent-facing ErrorDetails, homed by error class.
+ *
+ * Without this, a tool that funnels every failure through getMalloyErrorDetails
+ * dresses each one up as a Malloy language problem: a missing package tells the
+ * agent to check its Malloy syntax, and a back-pressure rejection sends it
+ * hunting for a typo instead of retrying.
+ *
+ * Only the classes that really are about the caller's Malloy or request reach
+ * the Malloy advice; anything else is reported as internal rather than blamed
+ * on the model. Routing by class and not by message is deliberate:
+ * getMalloyErrorDetails refines on message patterns that the shipped engine
+ * does not emit (its syntax pattern wants "no viable alternative at input"
+ * where a real error says "unexpected '@'"), so "did it refine?" would send
+ * genuine compile errors to the internal branch.
+ *
+ * @param operation The operation that failed (e.g. 'compile', 'reloadPackage').
+ * @param identifier The resource it failed on (e.g. 'env/package').
+ */
+export function classifyToolError(
+   operation: string,
+   identifier: string,
+   error: unknown,
+): ErrorDetails {
+   if (
+      error instanceof EnvironmentNotFoundError ||
+      error instanceof PackageNotFoundError ||
+      error instanceof ModelNotFoundError ||
+      // A query-boundary denial is a deliberate 404, and reporting it as a
+      // server fault would tell the caller to contact support about a boundary
+      // that is working. getNotFoundError also drops the source name this class
+      // is careful not to confirm.
+      error instanceof NotQueryableError
+   ) {
+      return getNotFoundError(identifier);
+   }
+   if (error instanceof ServiceUnavailableError) {
+      // Back-pressure: surface the server's own message so the caller knows to
+      // retry rather than to go edit its Malloy.
+      return {
+         message: error.message,
+         suggestions: [...BACK_PRESSURE_SUGGESTIONS],
+      } satisfies ErrorDetails;
+   }
+   if (
+      error instanceof QueryTimeoutError ||
+      error instanceof PayloadTooLargeError
+   ) {
+      // The query was too slow or too big. Both classes already carry their own
+      // "refine the query" remediation in the message, so the suggestions say
+      // the part the message leaves out and the internal branch got backwards:
+      // this is not transient, and retrying it unchanged fails identically.
+      // That distinction is the whole reason these are 504/413 and not the
+      // retryable 503 (see the QueryTimeoutError docstring in errors.ts).
+      return {
+         message: error.message,
+         suggestions: [
+            "This is not transient. The same query will fail the same way, so change the query rather than retrying it.",
+            "If it is already minimal, raise the configured cap named in the message.",
+         ],
+      } satisfies ErrorDetails;
+   }
+   if (
+      // A raw engine error: what a bad query throws (syntax, undefined name,
+      // field not found). executeQuery's catch sees these, so they must keep
+      // the Malloy advice.
+      error instanceof MalloyError ||
+      // The same thing wrapped: what a failed compile or reload throws.
+      error instanceof ModelCompilationError ||
+      // An #(authorize) denial, whose message getMalloyErrorDetails recognizes.
+      error instanceof AccessDeniedError ||
+      // A malformed request is the caller's to fix, not ours to retry.
+      error instanceof BadRequestError
+   ) {
+      return getMalloyErrorDetails(operation, identifier, error);
+   }
+   // Everything else (a filesystem EACCES, a TypeError, a worker crash, a
+   // timeout) is not the caller's Malloy. Telling them to check their syntax
+   // sends them to edit a model that is fine.
+   return getInternalError(operation, error);
+}
+
 /**
  * Fetches and validates the Package and Model instances needed for query execution.
  * Handles errors related to package/model access and initial compilation.
@@ -82,10 +179,7 @@ export async function getModelForQuery(
          // server's own message so the MCP caller knows to retry.
          errorDetails = {
             message: error.message,
-            suggestions: [
-               "Retry after the publisher's memory usage drops below the configured low-water mark.",
-               "If this happens repeatedly, raise PUBLISHER_MAX_MEMORY_BYTES or scale up the pod.",
-            ],
+            suggestions: [...BACK_PRESSURE_SUGGESTIONS],
          } satisfies ErrorDetails;
       } else {
          // Unexpected error during setup

package/src/mcp/server.protocol.spec.ts

@@ -2,6 +2,7 @@ import { beforeAll, describe, expect, it } from "bun:test";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { initializeMcpServer } from "./server";
+import { RELOAD_FAILURE_IS_SAFE } from "./tools/reload_package_tool";
 import type { EnvironmentStore } from "../service/environment_store";
 
 /**
@@ -37,6 +38,8 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(names.has("malloy_getContext")).toBe(true);
       expect(names.has("malloy_searchDocs")).toBe(true);
       expect(names.has("malloy_executeQuery")).toBe(true);
+      expect(names.has("malloy_compile")).toBe(true);
+      expect(names.has("malloy_reloadPackage")).toBe(true);
    });
 
    it("exposes the skill set as dual-channel prompts", async () => {
@@ -45,6 +48,17 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(prompts.some((p) => p.name === "malloy-analysis")).toBe(true);
    });
 
+   it("delivers orientation instructions to the connecting client", () => {
+      const instructions = client.getInstructions();
+      expect(instructions).toBeDefined();
+      expect(instructions).toContain("malloy_getContext");
+      // Pin the shared fragment, not just that instructions exist. The whole
+      // point of exporting it is that this surface and the tool description
+      // cannot drift, and they have drifted twice. Without this, deleting the
+      // interpolation leaves the suite green and the drift comes back.
+      expect(instructions).toContain(RELOAD_FAILURE_IS_SAFE);
+   });
+
    it("malloy_searchDocs returns relevant docs over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_searchDocs",
@@ -72,6 +86,50 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(res.isError).toBe(true);
    });
 
+   /**
+    * Assert the tool's OWN error payload, not just isError. The SDK sets
+    * isError for any uncaught throw, so `expect(res.isError).toBe(true)` passes
+    * even with the tool's catch deleted entirely. Only these tools emit a
+    * resource block carrying structured JSON; a raw throw yields the SDK's text
+    * content instead, so this shape is what actually pins the catch.
+    */
+   function expectToolErrorPayload(result: unknown): {
+      error: string;
+      suggestions: string[];
+   } {
+      const res = result as {
+         isError?: boolean;
+         content?: Array<{ type?: string; resource?: { text?: string } }>;
+      };
+      expect(res.isError).toBe(true);
+      expect(res.content?.[0]?.type).toBe("resource");
+      const payload = JSON.parse(res.content?.[0]?.resource?.text ?? "{}");
+      expect(typeof payload.error).toBe("string");
+      expect(Array.isArray(payload.suggestions)).toBe(true);
+      return payload;
+   }
+
+   it("malloy_compile returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_compile",
+         arguments: {
+            environmentName: "nope",
+            packageName: "nope",
+            modelPath: "x.malloy",
+            source: "run: x -> { aggregate: c is count() }",
+         },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+   });
+
+   it("malloy_reloadPackage returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_reloadPackage",
+         arguments: { environmentName: "nope", packageName: "nope" },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+   });
+
    it("a skill prompt returns its body", async () => {
       const res = await client.getPrompt({ name: "malloy-analysis" });
       const content = res.messages[0].content as { text?: string };

package/src/mcp/server.ts

@@ -2,9 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { EnvironmentStore } from "../service/environment_store";
 
 import { formatDuration, logger } from "../logger";
+import { registerCompileTool } from "./tools/compile_tool";
 import { registerDocsSearchTool } from "./tools/docs_search_tool";
 import { registerExecuteQueryTool } from "./tools/execute_query_tool";
 import { registerGetContextTool } from "./tools/get_context_tool";
+import {
+   registerReloadPackageTool,
+   RELOAD_FAILURE_IS_SAFE,
+} from "./tools/reload_package_tool";
 import skillsBundle from "./skills/skills_bundle.json";
 
 export const testServerInfo = {
@@ -22,17 +27,40 @@ const AGENT_SKILLS = (
    }
 ).skills;
 
+// Orientation delivered to any connecting MCP client via the initialize
+// response (the on-the-wire analog of AGENTS.md), so an agent that reached the
+// server over npx without cloning the repo still knows how to work. Kept
+// workflow-focused rather than a tool catalog, which the client already gets
+// from listTools, so it does not drift as the tool set changes.
+// SECURITY: this is delivered pre-authorization to any connecting client, so it
+// must stay STATIC. It may interpolate module-scope string LITERALS (see
+// RELOAD_FAILURE_IS_SAFE, shared with the tool description so the two cannot
+// drift). Not "constants": `const x = process.env.FOO` is a module-scope
+// constant and would put deployment config into an unauthenticated string. It
+// must never interpolate environment, package, connection, or request data.
+const MCP_INSTRUCTIONS = `Malloy Publisher serves one or more Malloy semantic-model packages, so you can discover what data exists and answer questions against it, grounded in the names the model actually defines.
+
+Start with malloy_getContext. Call it with no arguments to list the environments (each with its packages), with an environment to list its packages, with a package to list its sources, and with a package plus a plain-English question to get the sources, views, and fields most relevant to it. Use the names it returns verbatim and do not guess. Then run a query with malloy_executeQuery. To change a model: validate the edit with malloy_compile, save it, then call malloy_reloadPackage so the new sources and views become queryable by name without restarting the server. ${RELOAD_FAILURE_IS_SAFE}
+
+Task-specific guidance is served as prompts you can fetch by name: malloy-getting-started to begin, malloy-modeling to build or change a model, malloy-analysis to explore and answer questions, and malloy-review to check correctness.
+
+Results and any charts render in the Publisher web UI on the REST port (4000 by default).`;
+
 export function initializeMcpServer(
    environmentStore: EnvironmentStore,
 ): McpServer {
    logger.info("[MCP Init] Starting initializeMcpServer...");
    const startTime = performance.now();
 
-   const mcpServer = new McpServer(testServerInfo);
+   const mcpServer = new McpServer(testServerInfo, {
+      instructions: MCP_INSTRUCTIONS,
+   });
 
    registerExecuteQueryTool(mcpServer, environmentStore);
    registerGetContextTool(mcpServer, environmentStore);
    registerDocsSearchTool(mcpServer, environmentStore);
+   registerCompileTool(mcpServer, environmentStore);
+   registerReloadPackageTool(mcpServer, environmentStore);
 
    // Dual-channel: also expose each skill as an MCP prompt, so hosts that ingest
    // MCP but do not load skill files (e.g. Codex, ChatGPT, Cursor) can pull the