fix: update FM HTTP mode documentation and config details

- Changed model name in btca.config.jsonc to lowercase.
- Updated domain_map.yaml with new FM HTTP features and troubleshooting tips.
- Expanded skill_spec.md to reflect increased failure modes for typegen-setup.
- Added detailed instructions for local WebViewer development using FM HTTP in SKILL.md.
- Clarified critical mistakes related to FmHttpAdapter usage and environment variable settings in typegen-setup documentation.

Author: eluce2

_artifacts/domain_map.yaml

@@ -2,7 +2,7 @@
 # Generated by skill-domain-discovery
 # Library: ProofKit
 # Version: fmdapi@5.0.3-beta.1, fmodata@0.1.0-beta.31, typegen@1.1.0-beta.15, webviewer@3.0.7-beta.0, better-auth@0.4.0-beta.7
-# Date: 2026-03-13
+# Date: 2026-03-16
 # Status: reviewed
 
 library:
@@ -50,6 +50,9 @@ skills:
       - 'Environment variables (FM_SERVER, FM_DATABASE, OTTO_API_KEY, FM_USERNAME, FM_PASSWORD)'
       - 'strictNumbers, strictValueLists options'
       - 'webviewerScriptName option'
+      - 'fmHttp config (local FM HTTP proxy for typegen metadata fetching)'
+      - 'FM HTTP env vars (FM_HTTP_BASE_URL, FM_CONNECTED_FILE_NAME)'
+      - 'FM HTTP auto-discovery of connectedFileName via /connectedFiles'
       - 'Field type overrides for OData'
       - 'reduceMetadata, alwaysOverrideFieldNames'
       - 'Entity ID preservation across regeneration'
@@ -59,6 +62,8 @@ skills:
       - 'Regenerate types after FileMaker schema changes'
       - 'Switch from Data API to OData config'
       - 'Configure environment variables for FM connection'
+      - 'Set up FM HTTP mode for local typegen without credentials'
+      - 'Troubleshoot FM HTTP connectivity issues'
       - 'Customize generated schemas with override files'
     failure_modes:
       - mistake: 'Editing files in generated/ or client/ directories'
@@ -168,6 +173,60 @@ skills:
         status: active
         skills: ['typegen-setup', 'fmdapi-client', 'fmodata-client']
 
+      - mistake: 'Using FmHttpAdapter in production application code'
+        mechanism: 'FmHttpAdapter is internal to typegen metadata fetching. Generated clients use WebViewerAdapter. Agent sees the adapter import in typegen source and uses it in app code.'
+        wrong_pattern: |
+          import { FmHttpAdapter } from "@proofkit/fmdapi/adapters/fm-http";
+          const client = DataApi({
+            adapter: new FmHttpAdapter({ baseUrl: "http://127.0.0.1:1365", connectedFileName: "MyFile" }),
+            layout: "Contacts",
+          });
+        correct_pattern: |
+          // Use typegen-generated client (which uses WebViewerAdapter internally)
+          import { ContactsLayout } from "./schema/client";
+          const { data } = await ContactsLayout.find({ query: { name: "==John" } });
+        source: 'source: typegen.ts, buildLayoutClient.ts'
+        priority: CRITICAL
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'Setting standard FM env vars when using fmHttp mode'
+        mechanism: 'fmHttp mode does not need FM_SERVER, FM_DATABASE, or OTTO_API_KEY. Agent configures both standard and fmHttp env vars, causing confusion when standard vars fail validation.'
+        wrong_pattern: |
+          # .env — agent sets both
+          FM_SERVER=https://fm.example.com
+          FM_DATABASE=MyFile.fmp12
+          OTTO_API_KEY=dk_abc123
+          FM_HTTP_BASE_URL=http://127.0.0.1:1365
+        correct_pattern: |
+          # fmHttp mode only needs these (baseUrl defaults to 127.0.0.1:1365)
+          # connectedFileName is auto-discovered if not set
+          FM_CONNECTED_FILE_NAME=MyFile
+        source: 'source: getEnvValues.ts, constants.ts'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'Suggesting OttoFMS/FetchAdapter fallback when FM HTTP fails'
+        mechanism: 'Agent troubleshoots FM HTTP connection failure by suggesting standard auth. Developer chose fmHttp because they have no hosted credentials or are working offline. Correct troubleshooting: check daemon health (GET http://127.0.0.1:1365/health), check /connectedFiles, ensure FM file has run "Connect to MCP" script and WebViewer window is open in Browse mode.'
+        source: 'maintainer interview'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
+      - mistake: 'FM HTTP WebViewer window closed or in Layout mode'
+        mechanism: 'The FM HTTP proxy works via a WebViewer window opened by the "Connect to MCP" script in FileMaker. If this window is closed or switched to Layout mode, all proxy requests fail. Error may not be obvious — typegen just fails to connect.'
+        correct_pattern: |
+          # Troubleshooting checklist:
+          # 1. Is the fm-http daemon running? GET http://127.0.0.1:1365/health
+          # 2. Is the file connected? GET http://127.0.0.1:1365/connectedFiles
+          # 3. If file not listed: open it in FileMaker, run "Connect to MCP" script
+          # 4. Ensure the WebViewer window stays open in Browse mode (not Layout mode)
+        source: 'maintainer interview'
+        priority: HIGH
+        status: active
+        skills: ['typegen-setup']
+
   - name: 'Data API Client'
     slug: 'fmdapi-client'
     domain: 'data-access'
@@ -646,10 +705,12 @@ skills:
       - 'First typegen run'
       - 'First query with generated client'
       - 'Choosing between Data API and OData'
+      - 'FM HTTP mode for local/offline WebViewer development (no credentials needed)'
     tasks:
       - 'Set up a new project with ProofKit'
       - 'Connect to FileMaker server for the first time'
       - 'Generate types and make first data query'
+      - 'Set up FM HTTP mode for local WebViewer development'
     failure_modes:
       - mistake: 'Missing fmrest or fmodata privilege on FM account'
         mechanism: 'Data API requires fmrest extended privilege. OData requires fmodata privilege. Without these, all API calls return 401/403.'

_artifacts/skill_spec.md

@@ -15,7 +15,7 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 
 | Skill | Type | Domain | What it covers | Failure modes |
 | --- | --- | --- | --- | --- |
-| typegen-setup | core | connecting | Config, CLI, Data API + OData modes, validators, generated file structure, env vars | 7 |
+| typegen-setup | core | connecting | Config, CLI, Data API + OData + FM HTTP modes, validators, generated file structure, env vars | 11 |
 | fmdapi-client | core | data-access | DataApi factory, adapters, token stores, CRUD, find variants, scripts, validation | 6 |
 | fmodata-client | core | data-access | FMServerConnection, schema/field builders, query builder, CRUD, relationships, batch, errors | 8 |
 | webviewer-integration | core | webviewer | fmFetch, callFMScript, WebViewerAdapter, browser-only constraints, local mode perf | 6 |
@@ -25,7 +25,7 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 
 ## Failure Mode Inventory
 
-### typegen-setup (7 failure modes)
+### typegen-setup (11 failure modes)
 
 | # | Mistake | Priority | Source | Cross-skill? |
 | --- | --- | --- | --- | --- |
@@ -36,6 +36,10 @@ ProofKit is a monorepo of TypeScript tools for building web applications integra
 | 5 | Omitting type discriminator for OData config | HIGH | source + docs | — |
 | 6 | Manually redefining types instead of using generated/inferred types | CRITICAL | maintainer | fmdapi-client, fmodata-client |
 | 7 | Mixing Zod v3 and v4 in the same project | HIGH | maintainer | fmdapi-client, fmodata-client |
+| 8 | Using FmHttpAdapter in production application code | CRITICAL | source | — |
+| 9 | Setting standard FM env vars when using fmHttp mode | HIGH | source | — |
+| 10 | Suggesting OttoFMS/FetchAdapter fallback when FM HTTP fails | HIGH | maintainer | — |
+| 11 | FM HTTP WebViewer window closed or in Layout mode | HIGH | maintainer | — |
 
 ### fmdapi-client (6 failure modes)
 

btca.config.jsonc

@@ -8,6 +8,6 @@
       "branch": "main"
     }
   ],
-  "model": "GPT-5.3-Codex",
+  "model": "gpt-5.3-codex",
   "provider": "openai"
 }

packages/typegen/skills/getting-started/SKILL.md

@@ -187,6 +187,56 @@ if (error) {
 }
 ```
 
+### Path D: Local WebViewer Development (FM HTTP — no credentials)
+
+For WebViewer apps running inside FileMaker, you can use FM HTTP mode to generate types from a local FileMaker file without any server credentials.
+
+**Prerequisites:**
+- FM HTTP daemon installed and running (`curl http://127.0.0.1:1365/health`)
+- FileMaker file open locally with "Connect to MCP" script run
+
+1. Install packages:
+
+```bash
+pnpm add @proofkit/fmdapi @proofkit/webviewer zod
+```
+
+2. No `.env` file needed for typegen (baseUrl defaults, connectedFileName is auto-discovered). Optionally set "connectedFileName" in the config.fmHttp.connectedFileName to override the auto-discovery.
+
+3. Create typegen config with `fmHttp` enabled:
+
+```jsonc
+{
+  "$schema": "https://proofkit.dev/typegen-config-schema.json",
+  "config": {
+    "type": "fmdapi",
+    "fmHttp": { "enabled": true },
+    "layouts": [
+      { "layoutName": "api_Contacts", "schemaName": "Contacts" }
+    ],
+    "path": "schema"
+  }
+}
+```
+
+4. Run typegen — it auto-discovers the connected file and writes it back to config:
+
+```bash
+npx @proofkit/typegen
+```
+
+5. First query (runs inside FileMaker WebViewer):
+
+```ts
+import { ContactsLayout } from "./schema/client";
+
+const { data } = await ContactsLayout.findOne({
+  query: { id: "==123" },
+});
+```
+
+The generated client uses `WebViewerAdapter` with `"execute_data_api"` as the default script name. No server URL or API keys are needed at runtime — all calls go through the FileMaker script engine.
+
 ## Choosing Data API vs OData
 
 | Aspect | Data API (`@proofkit/fmdapi`) | OData (`@proofkit/fmodata`) |

packages/typegen/skills/typegen-setup/SKILL.md

@@ -5,7 +5,8 @@ description: >
   validators from FileMaker layouts or OData metadata. Covers
   proofkit-typegen-config.jsonc, validator options (zod/v4, zod/v3),
   generated vs override file structure, envNames, InferTableSchema,
-  InferZodPortals, and the schema/generated/client directory layout.
+  InferZodPortals, schema/generated/client directory layout, and
+  fmHttp mode for local typegen without credentials.
 type: core
 library: proofkit
 library_version: "1.1.0-beta.15"
@@ -181,35 +182,42 @@ import { Customers } from "./schema/odata/generated/Customers";
 type CustomerRow = InferTableSchema<typeof Customers>;
 ```
 
-### Multiple configs (mixed Data API + OData)
+### Multiple configs
+
+The `config` key can be an array mixing `fmdapi` and `fmodata` entries, each with its own `path` and `envNames`.
+
+### FM HTTP mode (local development, no credentials)
+
+FM HTTP mode lets typegen fetch layout metadata from a locally running FileMaker file via the FM HTTP proxy, without needing OttoFMS, a hosted server, or any credentials. Generated clients still use `WebViewerAdapter` — FM HTTP is only used during typegen.
 
 ```jsonc
 {
   "$schema": "https://proofkit.dev/typegen-config-schema.json",
-  "config": [
-    {
-      "type": "fmdapi",
-      "path": "schema/dapi",
-      "layouts": [
-        { "layoutName": "api_Contacts", "schemaName": "Contacts" }
-      ]
-    },
-    {
-      "type": "fmodata",
-      "path": "schema/odata",
-      "envNames": {
-        "server": "ODATA_SERVER_URL",
-        "db": "ODATA_DATABASE_NAME",
-        "auth": { "apiKey": "ODATA_API_KEY" }
-      },
-      "tables": [
-        { "tableName": "Products" }
-      ]
-    }
-  ]
+  "config": {
+    "type": "fmdapi",
+    "fmHttp": { "enabled": true },
+    "layouts": [
+      { "layoutName": "api_Contacts", "schemaName": "Contacts" }
+    ]
+  }
 }
 ```
 
+`fmHttp` 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: `fmHttp.scriptName` > `webviewerScriptName` > `"execute_data_api"`
+- `baseUrl` — FM HTTP 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"`.
+
+**Prerequisites:**
+1. FM HTTP daemon running locally (`GET http://127.0.0.1:1365/health` should return OK)
+2. FileMaker file open on the local machine
+3. "Connect to MCP" script run in the FileMaker file (opens a WebViewer window that bridges HTTP requests)
+4. That WebViewer window must stay open in **Browse mode** (not Layout mode)
+
 ### Custom env variable names
 
 ```jsonc
@@ -418,6 +426,62 @@ Zod v3 and v4 have incompatible APIs (`z.infer` vs `z.output`, different `extend
 
 Source: apps/docs/content/docs/typegen/config.mdx
 
+### CRITICAL: Using FmHttpAdapter in production application code
+
+Wrong:
+```ts
+import { FmHttpAdapter } from "@proofkit/fmdapi/adapters/fm-http";
+
+const client = DataApi({
+  adapter: new FmHttpAdapter({
+    baseUrl: "http://127.0.0.1:1365",
+    connectedFileName: "MyFile",
+  }),
+  layout: "Contacts",
+});
+```
+
+Correct:
+```ts
+// Use the typegen-generated client (uses WebViewerAdapter internally)
+import { ContactsLayout } from "./schema/client";
+
+const { data } = await ContactsLayout.find({ query: { name: "==John" } });
+```
+
+`FmHttpAdapter` is internal to typegen's metadata fetching process. It only runs during code generation, never in production. Generated clients use `WebViewerAdapter` for runtime data access inside FileMaker WebViewer.
+
+### HIGH: Setting standard FM env vars when using fmHttp mode
+
+Wrong:
+```bash
+# Agent configures both standard and fmHttp vars
+FM_SERVER=https://fm.example.com
+FM_DATABASE=MyFile.fmp12
+OTTO_API_KEY=dk_abc123
+FM_HTTP_BASE_URL=http://127.0.0.1:1365
+```
+
+Correct:
+```bash
+# fmHttp mode only — no server/db/auth needed
+# baseUrl defaults to http://127.0.0.1:1365 if not set
+# connectedFileName is auto-discovered if not set
+FM_CONNECTED_FILE_NAME=MyFile
+```
+
+fmHttp mode bypasses the standard FM_SERVER/FM_DATABASE/auth env vars entirely. Setting both causes confusion when standard validation reports missing values.
+
+### HIGH: FM HTTP connection failures — troubleshooting
+
+If typegen fails to connect in fmHttp mode, do NOT suggest falling back to OttoFMS or FetchAdapter. The developer chose fmHttp because they don't have hosted credentials or are working with a local-only file.
+
+Troubleshooting checklist:
+1. **Daemon running?** `curl http://127.0.0.1:1365/health` — should return `{"service":"fm-http","status":"ok"}`
+2. **File connected?** `curl http://127.0.0.1:1365/connectedFiles` — should list the target file
+3. **File not listed?** Open the FileMaker file and run the **"Connect to MCP"** script
+4. **Still not working?** Ensure the WebViewer window opened by "Connect to MCP" is in **Browse mode**, not Layout mode. Closing this window or switching to Layout mode silently breaks the proxy.
+
 ## References
 
 - **fmdapi-client**: Typegen generates the layout-specific clients consumed by `@proofkit/fmdapi`. Override files and `InferZodPortals` bridge typegen output into fmdapi usage.