Fix architecture diagrams

apps/docs/content/docs/ai/agent-workflow.mdx

@@ -3,35 +3,24 @@ title: Agent Workflow
 description: How ProofKit closes the loop for coding agents building FileMaker apps.
 ---
 
-import { Callout } from "fumadocs-ui/components/callout";
+import { AgentWorkflowLoop } from "@/components/AgentWorkflowLoop";
 
 ProofKit is designed for agents that can do more than produce snippets. The workflow gives the agent real FileMaker context, a project it can edit, and feedback it can use to fix mistakes.
 
 ## The loop
 
-```mermaid
-flowchart LR
-  readSchema["Read FileMaker schema"] --> writeCode["Write app code"]
-  writeCode --> runChecks["Run typecheck and lint"]
-  runChecks --> previewApp["Preview in browser"]
-  previewApp --> fixIssues["Fix issues"]
-  fixIssues --> deployApp["Deploy to FileMaker"]
-  fixIssues --> writeCode
-```
+<AgentWorkflowLoop />
 
 ## What each step needs
 
+- **Next change**: the user asks for a new screen, behavior, or refinement.
 - **Read FileMaker schema**: the MCP server exposes file metadata and data context to the agent.
 - **Write app code**: the agent edits a normal web project using React, TypeScript, Tailwind, and shadcn/ui.
 - **Run checks**: TypeGen and TypeScript catch many schema and field-name mistakes before runtime.
 - **Preview in browser**: the agent can inspect the app as it runs, not just reason about code.
 - **Fix issues**: errors, screenshots, and build output become feedback for the next edit.
 - **Deploy to FileMaker**: the final bundle is pushed into the file and loaded by the Web Viewer.
 
-<Callout title="TODO: Diagram - Agent workflow">
-  Replace or polish the Mermaid diagram with the final agent workflow visual if a branded SVG or React component is created.
-</Callout>
-
 ## Why this matters
 
 Without the loop, you are usually copying FileMaker metadata into a chat, pasting code back into a project, discovering errors manually, and asking the model to try again. ProofKit gives the agent enough context and feedback to handle more of that cycle directly.

apps/docs/content/docs/ai/build-a-webviewer-app.mdx

@@ -3,7 +3,6 @@ title: Build a Web Viewer App
 description: Scaffold and iterate on a FileMaker Web Viewer app with your coding agent.
 ---
 
-import { Callout } from "fumadocs-ui/components/callout";
 import { Step, Steps } from "fumadocs-ui/components/steps";
 
 After ProofKit is connected and your agent understands the file, switch from exploration to building. The goal is a local web project that previews in the browser and can later be deployed into FileMaker.
@@ -14,23 +13,39 @@ After ProofKit is connected and your agent understands the file, switch from exp
   <Step>
     **Ask the agent to scaffold a Web Viewer project.**
 
+    Open your coding agent, such as Cursor, Claude Code, Codex, OpenCode, or another MCP-compatible agent, in an empty project folder before you start.
+
+    Copy this prompt into your agent:
+
+    ```text title="Prompt"
+    Set up a ProofKit Web Viewer project in this folder.
+    ```
+
     The project should use the ProofKit CLI and the current ProofKit stack: React, TypeScript, Vite, Tailwind, shadcn/ui, TanStack Query, and TypeGen.
   </Step>
 
   <Step>
     **Run the local preview.**
 
-    The agent should start the dev server and open the app in a browser so it can inspect the result.
+    The agent should start the dev server and open the app in a browser so it can inspect the result. Agents also have embedded browsers, so they can inspect the result without leaving the agentic loop. If the agent doesn't open a browser, ask it to use it's preview browser.
 
-    <Callout title="TODO: Screenshot - Local preview">
-      Capture the generated Web Viewer app running locally in a browser with FileMaker-backed data visible.
-    </Callout>
+    ```text title="Prompt"
+    Use your embedded browser or preview browser to inspect and monitor your work.
+    ```
   </Step>
 
   <Step>
     **Ask for a specific screen.**
 
     Start with one workflow: a dashboard, detail view, calendar, kanban board, rich form, or data grid.
+
+    ```text title="Prompt"
+    Build a customer viewer with a searchable list view.
+    ```
+
+    ![Local preview of a generated ProofKit Web Viewer app showing FileMaker-backed customer data.](/screenshots/ai/local-preview-filemaker-webviewer.png)
+
+    _After you ask the agent to build a screen, the desktop session can look like this: agent messages on the left and an embedded browser preview on the right, showing FileMaker data from the connected FileMaker file._
   </Step>
 
   <Step>
@@ -40,21 +55,19 @@ After ProofKit is connected and your agent understands the file, switch from exp
   </Step>
 </Steps>
 
-## Prompt shape
-
-```text
-Build a ProofKit Web Viewer screen for the Contacts workflow.
-Use the FileMaker layouts and fields you discovered earlier.
-Start with a read-only list and detail view, then run checks and preview it in the browser.
-```
-
 ## Style and theme
 
 ProofKit projects use shadcn/ui and Tailwind, so the agent can apply a theme or preset by editing normal project files.
 
-<Callout title="TODO: Screenshot - Theme applied">
-  Capture a before/after of a generated screen after applying a shadcn/ui preset or branded theme.
-</Callout>
+Use [shadcn/ui Create](https://ui.shadcn.com/create?) to explore visual presets. Copy a preset code, then ask your agent to apply it to the project to quickly change colors, typography, icons, and component styling.
+
+```text title="Prompt"
+Apply this shadcn/ui preset to the project: <preset-code>
+```
+
+![The same generated customer viewer after applying a different visual preset.](/screenshots/ai/theme-preset-filemaker-webviewer.png)
+
+_The same generated screen after applying a different preset, with updated colors, typography, and corner radiuses._
 
 ## Reference docs
 

apps/docs/content/docs/ai/deploy-to-filemaker.mdx

@@ -3,42 +3,55 @@ title: Deploy to FileMaker
 description: Bundle your Web Viewer app and deploy it into a FileMaker file.
 ---
 
-import { Callout } from "fumadocs-ui/components/callout";
 import { Step, Steps } from "fumadocs-ui/components/steps";
 
 Deployment for a ProofKit Web Viewer app means bundling the web app and storing it in your FileMaker file so it can load inside a Web Viewer layout.
 
 This is different from deploying a browser app to a hosting provider. The deployed artifact is HTML and JavaScript living in the FileMaker file.
 
+## Ask the agent to deploy
+
+Once the app works locally and FileMaker is connected to ProofKit, you can ask the agent to handle deployment for you:
+
+```text title="Prompt"
+Deploy the app to my connected file maker file.
+```
+
+The agent should treat deployment as a release step, not just a file copy. It should run available checks, build the production bundle, deploy the generated HTML through ProofKit, and then verify the result inside FileMaker.
+
+Because `deploy_html` writes the bundled app into the connected FileMaker file, only run it against the file you mean to update. If users are connected to a production file, they may see the change immediately, so prefer a development file or a controlled deployment window. Most MCP clients let you disable tools or toggle automatic prompting for individual tools; keep deployment approval on unless you are intentionally working in a safe dev environment.
+
 ## Deploy the app
 
+When you ask the agent to deploy the app, it should run through these steps for you. The final verification step is the one you should review yourself inside FileMaker.
+
 <Steps>
   <Step>
     **Run checks before deployment.**
 
-    Ask the agent to run the project checks it has available, such as typechecking, linting, and a production build.
+    The agent runs the project checks it has available, such as typechecking, linting, and a production build.
   </Step>
 
   <Step>
     **Bundle the Web Viewer app.**
 
-    The project build should produce a deployable single-file bundle for the FileMaker Web Viewer.
+    The agent builds the project into a deployable single-file bundle for the FileMaker Web Viewer.
   </Step>
 
   <Step>
     **Deploy through ProofKit.**
 
-    ProofKit sends the bundle through the local bridge and stores it in the FileMaker file.
+    The agent uses ProofKit to send the bundle through the local bridge and store it in the FileMaker file.
   </Step>
 
   <Step>
     **Verify inside FileMaker.**
 
     Navigate to the Web Viewer layout and confirm the deployed app loads with real data.
 
-    <Callout title="TODO: Screenshot - Deployed app in FileMaker">
-      Capture the finished app running inside a FileMaker Web Viewer layout.
-    </Callout>
+    ![A deployed ProofKit dashboard running inside a FileMaker Web Viewer layout.](/screenshots/ai/deployed-filemaker-webviewer.png)
+
+    _A deployed ProofKit app running inside FileMaker, with FileMaker's layout chrome around the Web Viewer and live FileMaker data rendered in the dashboard._
   </Step>
 </Steps>
 

apps/docs/content/docs/ai/getting-started.mdx

@@ -14,7 +14,9 @@ This guide is the happy path for ProofKit v2. It mirrors the planned video serie
 
 ## Before you start
 
-You need FileMaker Pro, Node.js LTS, and an MCP-compatible coding agent such as Cursor, Claude Code, Codex, OpenCode, or another agent that can use MCP servers.
+You need FileMaker Pro, a supported Node.js LTS release, and an MCP-compatible coding agent such as Cursor, Claude Code, Codex, OpenCode, or another agent that can use MCP servers.
+
+For Node.js, choose a release that is explicitly marked LTS. Today that means **Node.js 22**, **Node.js 24**, or **Node.js 26**. If you are setting up Node for the first time, start with the [official Node.js download page](https://nodejs.org/en/download/).
 
 See [Technical Requirements](/docs/ai/technical-requirements) for the full support matrix.
 

apps/docs/content/docs/ai/technical-requirements.mdx

@@ -3,6 +3,8 @@ title: Technical Requirements
 description: What you need to build and run ProofKit v2 apps.
 ---
 
+import { Tab, Tabs } from "fumadocs-ui/components/tabs";
+
 ProofKit v2 is designed for FileMaker developers using agentic coding tools to build Web Viewer apps.
 
 ## FileMaker version
@@ -16,11 +18,52 @@ Future ProofKit releases will track the next major FileMaker release cycle so Pr
 To build ProofKit apps, you need:
 
 - **FileMaker Pro** with the target file open.
-- **Node.js LTS** installed locally.
+- **Node.js LTS** installed locally. Choose a release that is explicitly marked LTS. Today that means **Node.js 22**, **Node.js 24**, or **Node.js 26**.
 - **An MCP-compatible coding agent**, such as Cursor, Claude Code, Codex, OpenCode, or another agent that supports MCP servers.
 
 FileMaker Server is not required for the development loop. ProofKit can work against a local or hosted file as long as it is open in FileMaker Pro.
 
+## Node.js
+
+ProofKit projects use Node.js for the local development tools that scaffold, build, preview, and deploy Web Viewer apps. Pick an LTS release rather than the newest "Current" release. Node's odd-numbered releases are short-lived, and not every even-numbered release is the right choice forever; use a version that [nodejs.org marks as LTS](https://nodejs.org/en/download/).
+
+If you are not already managing Node versions, the native installer from nodejs.org is the simplest option.
+
+<Tabs items={["Native installer", "Homebrew", "Version manager"]}>
+  <Tab value="Native installer">
+    Download the LTS installer for macOS or Windows from [nodejs.org/download](https://nodejs.org/en/download/). Choose Node.js 26 LTS when available, or Node.js 24 LTS or Node.js 22 LTS if your environment standardizes on one of those versions.
+
+    After installing, verify the version:
+
+    ```sh
+    node -v
+    npm -v
+    ```
+  </Tab>
+
+  <Tab value="Homebrew">
+    On macOS, Homebrew is convenient if you already use it. Install a versioned LTS formula instead of the unversioned `node` formula, which may track a newer non-LTS release.
+
+    ```sh
+    brew install node@24
+    node -v
+    ```
+
+    If `node` is not found after installation, run `brew info node@24` and follow Homebrew's PATH instructions.
+  </Tab>
+
+  <Tab value="Version manager">
+    Use a version manager if you switch between projects with different Node requirements.
+
+    ```sh
+    nvm install --lts
+    nvm use --lts
+    ```
+
+    `fnm` and Volta are good alternatives. The important part is pinning your project to an LTS line such as Node.js 26, Node.js 24, or Node.js 22.
+  </Tab>
+</Tabs>
+
 ## Developer background
 
 You do not need to be a web developer to get started. Familiarity with React, TypeScript, a terminal, and Git will help, but the workflow is designed so the agent does much of the setup and implementation work.
@@ -51,7 +94,7 @@ ProofKit v2 enables agentic coding of Web Viewer apps. It does not currently ena
 | --- | --- |
 | FileMaker version | FileMaker 22 or greater |
 | Agent environment | Any MCP-compatible agent |
-| Development requirements | FileMaker Pro and Node.js LTS |
+| Development requirements | FileMaker Pro and Node.js 22, 24, or 26 LTS |
 | FileMaker Server | Not required for local development |
 | Runtime platforms | FileMaker Pro, FileMaker Go, WebDirect |
 | Agent writing scope | Web Viewer app code |

apps/docs/content/docs/webviewer/architecture.mdx

@@ -10,7 +10,7 @@ ProofKit has two related architectures: the development loop that lets an agent
 ## Development architecture
 
 ```mermaid
-flowchart LR
+flowchart TD
   agent["Coding agent"] <-->|"MCP"| mcp["ProofKit MCP server"]
   mcp <-->|"Local API"| plugin["FileMaker plug-in"]
   plugin <-->|"Script calls"| addon["ProofKit add-on"]
@@ -20,30 +20,35 @@ flowchart LR
   bundle --> file
 ```
 
-<Callout title="TODO: Diagram - Development architecture">
-  Replace or polish this Mermaid diagram with the final branded architecture visual if needed.
+<Callout title="Connection labels">
+  - **MCP**: Model Context Protocol, the tool protocol the coding agent uses to talk to the ProofKit MCP server.
+  - **Local API**: The local bridge between the ProofKit MCP server and the FileMaker plug-in.
+  - **Script calls**: FileMaker script execution used by the plug-in and add-on to work with your FileMaker file.
 </Callout>
 
 ## Runtime architecture
 
 ```mermaid
 flowchart LR
-  user["User"] <--> webviewer["Web Viewer React app"]
-  webviewer <-->|"JSON through script bridge"| scripts["FileMaker scripts"]
-  scripts <--> database["FileMaker database"]
+  webviewer["Web Viewer app"]
+  webviewer -->|"ProofKit type safe<br/>client"| executeDataApi["Execute Data<br/>API Step"]
+  webviewer -->|"fmFetch()"| scripts["FileMaker scripts"]
+  executeDataApi --> database["FileMaker database"]
+  scripts --> database
   scripts --> externalApis["External APIs"]
   scripts --> fileSystem["File system"]
   scripts --> printing["Printing and PDF"]
 ```
 
-<Callout title="TODO: Diagram - Runtime architecture">
-  Replace or polish this Mermaid diagram with the final runtime/data-flow visual.
+<Callout title="Connection labels">
+  - **ProofKit type safe client**: Generated client code that calls FileMaker's Data API through the Execute Data API script step.
+  - **fmFetch()**: A lightweight script bridge for calling FileMaker scripts from the Web Viewer app.
 </Callout>
 
 ## How to think about it
 
 - During development, the agent uses ProofKit tools to understand the FileMaker file and deploy bundles.
-- At runtime, the deployed web app talks to FileMaker scripts through the Web Viewer bridge.
+- At runtime, the deployed web app talks to FileMaker through fmFetch scripts and the type-safe Data API path.
 - FileMaker scripts remain the secure place for privileged operations, external API secrets, filesystem work, and print/PDF flows.
 
 ## Related pages

apps/docs/src/app/global.css

@@ -178,3 +178,10 @@
     @apply bg-background text-foreground;
   }
 }
+
+@layer components {
+  .prose img {
+    background: var(--card);
+    border: 1px solid var(--border);
+  }
+}