proofsh · eluce2 · Jun 26, 2026
diff --git a/.changeset/pk-data-api-script-guidance.md b/.changeset/pk-data-api-script-guidance.md
@@ -0,0 +1,7 @@
+---
+"@proofkit/typegen": patch
+"@proofkit/webviewer": patch
+"@proofkit/fmdapi": patch
+---
+
+Update WebViewerAdapter and FM MCP typegen guidance to use the renamed `PK_execute_data_api` FileMaker script.
diff --git a/.changeset/skill-metadata-schema.md b/.changeset/skill-metadata-schema.md
@@ -0,0 +1,8 @@
+---
+"@proofkit/better-auth": patch
+"@proofkit/fmdapi": patch
+"@proofkit/fmodata": patch
+"@proofkit/webviewer": patch
+---
+
+Move skill package metadata under the Intent metadata frontmatter key.
diff --git a/packages/better-auth/skills/better-auth-setup/SKILL.md b/packages/better-auth/skills/better-auth-setup/SKILL.md
@@ -6,9 +6,10 @@ description: >
   config, migration via npx @proofkit/better-auth migrate, OData prerequisites,
   fmodata privilege, Full Access credentials for schema modification, plugin
   migration workflow, troubleshooting "filemaker is not supported" errors.
-type: core
-library: proofkit
-library_version: "0.4.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "0.4.1"
 requires:
   - fmodata-client
 sources:

diff --git a/packages/fmdapi/skills/fmdapi-client/SKILL.md b/packages/fmdapi/skills/fmdapi-client/SKILL.md
@@ -6,9 +6,10 @@ description: >
   maybeFindFirst, findAll, create, update, delete, get, executeScript,
   containerUpload, Standard Schema validation, portal data access, FileMaker
   Data API, layout-bound clients, schema inference
-type: core
-library: proofkit
-library_version: "5.1.2"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "5.1.2"
 requires:
   - typegen-fmdapi
 sources:

diff --git a/packages/fmdapi/skills/typegen-fmdapi/SKILL.md b/packages/fmdapi/skills/typegen-fmdapi/SKILL.md
@@ -8,9 +8,10 @@ description: >
   development, generated vs override file structure, schema/generated/client
   directory layout, Standard Schema validation, InferZodPortals, fmMcp mode
   prerequisites, and choosing between OttoAdapter and FetchAdapter auth.
-type: core
-library: proofkit
-library_version: "5.1.2"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "5.1.2"
 sources:
   - "proofsh/proofkit:packages/typegen/src/cli.ts"
   - "proofsh/proofkit:packages/typegen/src/typegen.ts"
@@ -213,11 +214,11 @@ FM MCP mode lets typegen fetch layout metadata from a locally running FileMaker
 `fmMcp` accepts an object with optional overrides:
 
 - `enabled` — `true` to enable (default when object is present)
-- `scriptName` — FM script the proxy calls for Data API operations. Resolution: `fmMcp.scriptName` > `webviewerScriptName` > `"execute_data_api"`
+- `scriptName` — FM script the proxy calls for Data API operations. Resolution: `fmMcp.scriptName` > `webviewerScriptName` > `"PK_execute_data_api"`
 - `baseUrl` — FM MCP server URL (default: `http://127.0.0.1:1365`). Can also be set via `FM_HTTP_BASE_URL` env var
 - `connectedFileName` — FileMaker file name. If omitted, auto-discovered from `GET /connectedFiles` and written back to config
 
-The generated client uses `WebViewerAdapter` with `webviewerScriptName` if set, otherwise `"execute_data_api"`.
+The generated client uses `WebViewerAdapter` with `webviewerScriptName` if set, otherwise `"PK_execute_data_api"`.
 
 **Prerequisites:**
 1. FM MCP daemon running locally (`GET http://127.0.0.1:1365/health` should return OK)

diff --git a/packages/fmdapi/src/adapters/fm-mcp.ts b/packages/fmdapi/src/adapters/fm-mcp.ts
@@ -58,7 +58,7 @@ export interface FmMcpAdapterOptions {
   baseUrl: string;
   /** Name of the connected FileMaker file */
   connectedFileName: string;
-  /** Name of the FM script that executes Data API calls. Defaults to "execute_data_api" */
+  /** Name of the FM script that executes Data API calls. Defaults to "PK_execute_data_api" */
   scriptName?: string;
   /** Session ID sent to the bridge. Defaults to FM_MCP_SESSION_ID or a random ID. */
   sessionId?: string;
@@ -89,7 +89,7 @@ export class FmMcpAdapter implements Adapter {
   constructor(options: FmMcpAdapterOptions) {
     this.baseUrl = options.baseUrl.replace(TRAILING_SLASHES_REGEX, "");
     this.connectedFileName = options.connectedFileName;
-    this.scriptName = options.scriptName ?? "execute_data_api";
+    this.scriptName = options.scriptName ?? "PK_execute_data_api";
     this.sessionId = options.sessionId ?? envValue("FM_MCP_SESSION_ID") ?? randomSessionId();
     this.clientName = options.clientName ?? envValue("FM_MCP_CLIENT_NAME") ?? "ProofKit Typegen";
     this.clientDescription =

diff --git a/packages/fmdapi/tests/fm-mcp-adapter.test.ts b/packages/fmdapi/tests/fm-mcp-adapter.test.ts
@@ -76,7 +76,7 @@ describe("FmMcpAdapter", () => {
 
       const body = JSON.parse(init?.body as string);
       expect(body.connectedFileName).toBe("MyFile");
-      expect(body.scriptName).toBe("execute_data_api");
+      expect(body.scriptName).toBe("PK_execute_data_api");
 
       const param = JSON.parse(body.data);
       expect(param.layouts).toBe("TestLayout");

diff --git a/packages/fmodata/skills/fmodata-client/SKILL.md b/packages/fmodata/skills/fmodata-client/SKILL.md
@@ -9,9 +9,10 @@ description: >
   BatchTruncatedError entity IDs FMTID FMFID defaultSelect readValidator writeValidator orderBy asc
   desc top skip single maybeSingle count getSingleField FileMaker OData API schema management
   webhooks getTableColumns select("all")
-type: core
-library: proofkit
-library_version: "0.1.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "0.1.1"
 requires:
   - typegen-fmodata
 sources:

diff --git a/packages/fmodata/skills/odata-query-optimization/SKILL.md b/packages/fmodata/skills/odata-query-optimization/SKILL.md
@@ -7,9 +7,10 @@ description: >
   FMTID for rename resilience, null field query performance, getQueryString() debugging,
   relationship query performance testing, FileMaker OData optimization, avoiding OData
   service overload during testing.
-type: core
-library: proofkit
-library_version: "0.1.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "0.1.1"
 requires:
   - fmodata-client
 sources:

diff --git a/packages/fmodata/skills/typegen-fmodata/SKILL.md b/packages/fmodata/skills/typegen-fmodata/SKILL.md
@@ -8,9 +8,10 @@ description: >
   structure, field exclusion, type overrides, InferTableSchema, env var
   configuration, OData prerequisites, fmodata privilege, and why typegen is
   required for entity ID correctness.
-type: core
-library: proofkit
-library_version: "0.1.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "0.1.1"
 sources:
   - "proofsh/proofkit:packages/typegen/src/cli.ts"
   - "proofsh/proofkit:packages/typegen/src/fmodata/typegen.ts"

diff --git a/packages/typegen/live-fm-mcp-output/client/contacts.ts b/packages/typegen/live-fm-mcp-output/client/contacts.ts
@@ -8,7 +8,7 @@ import { WebViewerAdapter } from "@proofkit/webviewer/adapter";
 import { Zcontacts } from "../contacts";
 
 export const client = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "execute_data_api" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "Contacts",
   schema: { fieldData: Zcontacts },
 });
diff --git a/packages/typegen/src/buildLayoutClient.ts b/packages/typegen/src/buildLayoutClient.ts
@@ -2,7 +2,7 @@ import { type CodeBlockWriter, type SourceFile, VariableDeclarationKind } from "
 import { defaultEnvNames } from "./constants";
 import type { BuildSchemaArgs } from "./types";
 
-const defaultWebviewerScriptName = "execute_data_api";
+const defaultWebviewerScriptName = "PK_execute_data_api";
 
 function normalizeScriptName(scriptName?: string) {
   const normalized = scriptName?.trim();

diff --git a/packages/typegen/src/typegen.ts b/packages/typegen/src/typegen.ts
@@ -217,7 +217,7 @@ const generateTypedClientsSingle = async (
   if (isFmMcpMode && !config.webviewerScriptName) {
     console.log(
       chalk.blue(
-        `INFO: Generated clients will use WebViewerAdapter with script "${fmMcpObj?.scriptName ?? "execute_data_api"}".`,
+        `INFO: Generated clients will use WebViewerAdapter with script "${fmMcpObj?.scriptName ?? "PK_execute_data_api"}".`,
       ),
     );
   }

diff --git a/packages/typegen/src/types.ts b/packages/typegen/src/types.ts
@@ -202,7 +202,7 @@ const fmMcpFieldObject = z.object({
   }),
   scriptName: z.string().optional().meta({
     description:
-      'The FM script the FM MCP bridge calls to execute Data API operations. Overrides webviewerScriptName for the bridge call. Defaults to "execute_data_api".',
+      'The FM script the FM MCP bridge calls to execute Data API operations. Overrides webviewerScriptName for the bridge call. Defaults to "PK_execute_data_api".',
   }),
   baseUrl: z.string().optional().meta({
     description:
@@ -245,7 +245,7 @@ const fmMcpField = z
   .optional()
   .meta({
     description:
-      "Enable the FM MCP proxy for metadata fetching during typegen. Generated clients will use the @proofkit/webviewer adapter with webviewerScriptName or 'execute_data_api' as the default.",
+      "Enable the FM MCP proxy for metadata fetching during typegen. Generated clients will use the @proofkit/webviewer adapter with webviewerScriptName or 'PK_execute_data_api' as the default.",
   });
 
 const reduceMetadataField = z.boolean().optional().meta({

diff --git a/packages/typegen/typegen.schema.json b/packages/typegen/typegen.schema.json
@@ -127,7 +127,7 @@
               ]
             },
             "fmMcp": {
-              "description": "Enable the FM MCP proxy for metadata fetching during typegen. Generated clients will use the @proofkit/webviewer adapter with webviewerScriptName or 'execute_data_api' as the default.",
+              "description": "Enable the FM MCP proxy for metadata fetching during typegen. Generated clients will use the @proofkit/webviewer adapter with webviewerScriptName or 'PK_execute_data_api' as the default.",
               "allOf": [
                 {
                   "$ref": "#/definitions/__schema15"
@@ -326,7 +326,7 @@
           ]
         },
         "scriptName": {
-          "description": "The FM script the FM MCP bridge calls to execute Data API operations. Overrides webviewerScriptName for the bridge call. Defaults to \"execute_data_api\".",
+          "description": "The FM script the FM MCP bridge calls to execute Data API operations. Overrides webviewerScriptName for the bridge call. Defaults to \"PK_execute_data_api\".",
           "allOf": [
             {
               "$ref": "#/definitions/__schema17"

diff --git a/packages/typegen/web/src/components/ConfigEditor.tsx b/packages/typegen/web/src/components/ConfigEditor.tsx
@@ -396,7 +396,7 @@ export function ConfigEditor({ index, onRemove }: ConfigEditorProps) {
                         <FormItem>
                           <FormLabel>Script Name</FormLabel>
                           <FormControl>
-                            <Input placeholder="execute_data_api" {...field} />
+                            <Input placeholder="PK_execute_data_api" {...field} />
                           </FormControl>
                           <FormMessage />
                         </FormItem>

diff --git a/packages/webviewer/skills/webdirect-runtime/SKILL.md b/packages/webviewer/skills/webdirect-runtime/SKILL.md
@@ -5,9 +5,10 @@ description: >
   session state localStorage browser resize reload same deployment embedded bundle
   avoid separate deployment avoid separate web server @proofkit/webviewer
   fmFetch callFMScript WebViewerAdapter WebDirect page refresh
-type: core
-library: proofkit
-library_version: "3.1.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "3.1.1"
 sources:
   - "proofsh/proofkit:apps/docs/content/docs/webviewer/platform-notes.mdx"
   - "proofsh/proofkit:apps/docs/content/docs/webviewer/deployment-methods.mdx"

diff --git a/packages/webviewer/skills/webviewer-integration/SKILL.md b/packages/webviewer/skills/webviewer-integration/SKILL.md
@@ -4,9 +4,10 @@ description: >
   webviewer fmFetch callFMScript WebViewerAdapter globalSettings setWebViewerName
   SendCallback window.FileMaker browser-only FileMaker Web Viewer script execution
   fire-and-forget FMScriptOption PerformScript callback fetchId handleFmWVFetchCallback
-type: core
-library: proofkit
-library_version: "3.1.1"
+metadata:
+  type: core
+  library: proofkit
+  library_version: "3.1.1"
 sources:
   - "proofsh/proofkit:packages/webviewer/src/main.ts"
   - "proofsh/proofkit:packages/webviewer/src/adapter.ts"
@@ -99,7 +100,7 @@ import { DataApi } from "@proofkit/fmdapi";
 import { WebViewerAdapter } from "@proofkit/webviewer/adapter";
 
 const client = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "ExecuteDataApi" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "API_Customers",
 });
 
@@ -220,7 +221,7 @@ import { DataApi } from "@proofkit/fmdapi";
 import { WebViewerAdapter } from "@proofkit/webviewer/adapter";
 
 const client = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "ExecuteDataApi" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "API_Customers",
 });
 
@@ -235,7 +236,7 @@ import { WebViewerAdapter } from "@proofkit/webviewer/adapter";
 import { fmFetch, callFMScript } from "@proofkit/webviewer";
 
 const client = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "ExecuteDataApi" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "API_Customers",
 });
 
@@ -280,11 +281,11 @@ import { DataApi } from "@proofkit/fmdapi";
 import { WebViewerAdapter } from "@proofkit/webviewer/adapter";
 
 const customersClient = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "ExecuteDataApi" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "API_Customers",
 });
 const ordersClient = DataApi({
-  adapter: new WebViewerAdapter({ scriptName: "ExecuteDataApi" }),
+  adapter: new WebViewerAdapter({ scriptName: "PK_execute_data_api" }),
   layout: "API_Orders",
 });
 

diff --git a/scripts/check-skill-versions.mjs b/scripts/check-skill-versions.mjs
@@ -41,7 +41,7 @@ for (const packageDir of packageDirs) {
 
     for (const skillFile of skillFiles) {
       const content = readFileSync(skillFile, "utf8");
-      const match = content.match(/^library_version:\s*"([^"]*)"$/m);
+      const match = content.match(/^  library_version:\s*"([^"]*)"$/m);
       const skillVersion = match?.[1];
 
       if (!skillVersion || skillVersion === packageJson.version) continue;

diff --git a/scripts/sync-skill-versions.mjs b/scripts/sync-skill-versions.mjs
@@ -41,7 +41,10 @@ for (const packageDir of packageDirs) {
 
     for (const skillFile of skillFiles) {
       const content = readFileSync(skillFile, "utf8");
-      const nextContent = content.replace(/^library_version:\s*"[^"]*"$/m, `library_version: "${packageJson.version}"`);
+      const nextContent = content.replace(
+        /^  library_version:\s*"[^"]*"$/m,
+        `  library_version: "${packageJson.version}"`
+      );
 
       if (nextContent === content) continue;