docs: add GitHub workflow guide for AI docs

apps/docs/.env.schema

@@ -0,0 +1,11 @@
+# This env file uses @env-spec - see https://varlock.dev/env-spec for more info
+#
+# @defaultRequired=infer @defaultSensitive=inferFromPrefix('NEXT_PUBLIC_')
+# @generateTypes(lang=ts, path=env.d.ts)
+# ---
+
+# type=string @required @public
+NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=phc_CRjEA3E6xegbZegA9ZjsCREfuuR8XdTJ72CkBeukd5hQ
+
+# type=url @required @public
+NEXT_PUBLIC_POSTHOG_HOST=https://p.proof.sh

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

@@ -0,0 +1,138 @@
+---
+title: GitHub Workflow
+description: A friendly introduction to Git and GitHub for FileMaker developers.
+---
+
+import { Step, Steps } from "fumadocs-ui/components/steps";
+
+If you've spent your career in FileMaker, Git can feel intimidating. The good news: you don't need to memorize commands or become a Git expert. Your AI agent can run the commands for you. What you _do_ need is a mental model of where your code lives and how it moves around. That's what this guide is for.
+
+<Callout type="info" title="Git is already set up in your project">
+  When you create a new ProofKit project, Git is initialized for you — there's nothing to configure inside the project itself.
+
+  If you're completely new to Git, you may want to ask your agent to help you configure Git on your machine. This sets things like your name and email address, which get automatically attached to every commit so the version history knows who made each change.
+</Callout>
+
+## The model you already know
+
+In FileMaker, your file lives on a server. You and your teammates open it, make changes, and everyone sees those changes immediately. There's only ever one copy that matters: the hosted file.
+
+<ThemedImage
+  alt="Diagram showing multiple developers and users connecting to a single hosted FileMaker file."
+  darkSrc="/diagrams/shared-user-model-dark.svg"
+  height={787}
+  lightSrc="/diagrams/shared-user-model-light.svg"
+  width={753}
+/>
+
+This model is simple because there's nothing to sync. The file is in one place, and editing _is_ saving. There's also no real history — once a change is made, the previous version is gone unless someone happened to take a backup.
+
+## How code projects work
+
+Web code projects work differently. Instead of one shared file on a server, every developer has their own complete copy of the project on their own machine. That copy is just a folder, but in Git terms it's called a **repo** (short for repository).
+
+You make changes in your local repo, and when you're ready, you push those changes up to a service like **GitHub**. GitHub holds the canonical copy that everyone else syncs with.
+
+<ThemedImage
+  alt="Diagram showing developers each with a local repo on their machine, syncing to a shared GitHub repo."
+  darkSrc="/diagrams/github-flow-dark.svg"
+  height={924}
+  lightSrc="/diagrams/github-flow-light.svg"
+  width={960}
+/>
+
+The big shift: there is no live shared file. Each developer works in their own copy, and Git is the tool that keeps those copies in sync.
+
+## Terms you'll run into
+
+You don't need to learn these all at once, but it helps to recognize them when your agent (or a teammate) uses them:
+
+- **Repo** — the project folder, tracked by Git. You'll have a local one on your machine and a remote one on GitHub.
+- **Clone** — make a local copy of a remote repo on your machine.
+- **Commit** — a saved snapshot of your changes, with a short message describing what you did. Think of it as a deliberate "save point" you can always return to.
+- **Push** — send your local commits up to GitHub so others can see them.
+- **Pull** — bring down commits that teammates have pushed, so your local copy is up to date.
+- **Branch** — a parallel line of work. You can experiment on a branch without affecting the main version of the project.
+- **Merge** — combine the changes from one branch into another, usually merging a finished branch back into the main one.
+- **Pull request (PR)** — a proposal on GitHub to merge one branch into another, usually with a teammate reviewing the changes first.
+- **Conflict** — what happens when two people change the same lines of the same file. Git asks you to decide which version wins.
+
+If any of these come up and you want a deeper explanation in the context of your own project, just ask your agent.
+
+## What this gives you
+
+Once your project lives on GitHub, you get things FileMaker developers have long wished for:
+
+- **Full history.** Every change is recorded with who made it, when, and why.
+- **Branches.** Try out a risky change in a separate branch without touching the main version. Throw it away if it doesn't work, or merge it in if it does.
+- **Pull requests.** Have a teammate review your changes before they become part of the main project.
+- **Safe collaboration.** Two developers can work on the same project at the same time without overwriting each other.
+
+## Let your agent do the heavy lifting
+
+You don't need to memorize Git commands. When you want to do something, just ask your agent in plain language:
+
+```text title="Commit your changes"
+Commit my current changes with a clear message.
+```
+
+```text title="Create a branch"
+Create a new branch called fix-customer-list and switch to it.
+```
+
+```text title="Push to GitHub"
+Push my work to GitHub.
+```
+
+```text title="Compare local and remote"
+What's the difference between my local copy and what's on GitHub?
+```
+
+If a Git concept comes up that you want to understand better — branches, merges, rebases, conflicts — ask the agent to explain it in the context of your project. That's a much faster way to learn than reading Git documentation cold.
+
+<Callout type="info" title="Use the word 'commit'">
+  In FileMaker, saving and history don't really come up — your changes are just there. In a code project, the equivalent of "saving your work to history" is making a **commit**: a snapshot of the project at a moment in time that you can always come back to.
+
+  When you want your work recorded, ask the agent to **commit** your changes. That keyword is what tells the agent you want a Git snapshot, not just an edit. Get in the habit of committing often — every commit is a safe point you can return to.
+</Callout>
+
+## Publish your project to GitHub
+
+When you create a new ProofKit project, the local repo on your machine is ready to go — but nothing is on GitHub yet. To get the benefits of remote backup, history you can browse online, and collaboration, you'll want to publish it.
+
+<Steps>
+  <Step>
+    **Create a free GitHub account.**
+
+    Go to [github.com](https://github.com) and sign up. The free tier is plenty for personal projects and small teams — there's no need to pay for anything to get started.
+  </Step>
+
+  <Step>
+    **Install the GitHub CLI and sign in.**
+
+    The GitHub CLI (`gh`) is what your agent will use to talk to GitHub on your behalf. Install it from [cli.github.com](https://cli.github.com), then sign in by running this once in your terminal:
+
+    ```bash
+    gh auth login
+    ```
+
+    Follow the prompts to authenticate with your GitHub account. You only need to do this once per machine.
+  </Step>
+
+  <Step>
+    **Ask your agent to publish the project.**
+
+    With the CLI installed and authenticated, your agent can create the GitHub repo and push your project up for you.
+
+    ```text title="Prompt"
+    Publish this project to a new GitHub repo on my account.
+    ```
+
+    The agent will confirm the details before creating anything on your account.
+  </Step>
+</Steps>
+
+## Next step
+
+From here on, the workflow becomes a habit: edit, commit, push, repeat. Any time you're not sure what to do next, ask your agent — that's the fastest way to learn Git in the context of your own project.
+

apps/docs/content/docs/ai/install-and-connect.mdx

@@ -17,7 +17,11 @@ ProofKit installs several pieces that work together: a FileMaker add-on, a FileM
   <Step>
     **Download and run the installer.**
 
-    Before you run it, quit FileMaker Pro and your coding agent, such as Claude Desktop. Then get the installer for your platform: [macOS](/download/mac) or [Windows](/download/win). The installer sets up the local ProofKit tools and registers integrations for supported coding agents.
+    Before you run it, quit FileMaker Pro and your coding agent, such as Claude Desktop. Then get the installer for your platform:
+
+    <DownloadLink />
+
+    The installer sets up the local ProofKit tools and registers integrations for supported coding agents.
 
     After the installer finishes, reopen FileMaker Pro and your coding agent so they load the new ProofKit plug-in and integrations.
   </Step>

apps/docs/content/docs/ai/meta.json

@@ -11,6 +11,7 @@
     "explore-your-file",
     "build-a-webviewer-app",
     "deploy-to-filemaker",
+    "github-workflow",
     "---Understand---",
     "chat-vs-code-mode",
     "agent-workflow",

apps/docs/content/docs/ai/updating-proofkit.mdx

@@ -11,8 +11,7 @@ To update ProofKit, simply run the latest installer on your system. Sometimes th
 
 ## Download the latest installer
 
-- [Download for macOS](/download/mac)
-- [Download for Windows](/download/win)
+<DownloadLink />
 
 ## Updating the Add-on in FileMaker
 

apps/docs/env.d.ts

@@ -0,0 +1,52 @@
+
+// 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑
+// 🛑 THIS IS AN AUTOGENERATED FILE - DO NOT EDIT DIRECTLY 🛑
+// 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑 🛑
+
+// @ts-nocheck
+/* eslint-disable */
+export type CoercedEnvSchema = {
+  /**
+   * **NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN**  
+   * type=string @required @public  
+   * ![icon](data:image/svg+xml;utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2220%22%20height%3D%2220%22%20viewBox%3D%220%200%2032%2032%22%3E%3Cpath%20fill%3D%22%23808080%22%20d%3D%22M29%2022h-5a2.003%202.003%200%200%201-2-2v-6a2%202%200%200%201%202-2h5v2h-5v6h5ZM18%2012h-4V8h-2v14h6a2.003%202.003%200%200%200%202-2v-6a2%202%200%200%200-2-2m-4%208v-6h4v6Zm-6-8H3v2h5v2H4a2%202%200%200%200-2%202v2a2%202%200%200%200%202%202h6v-8a2%202%200%200%200-2-2m0%208H4v-2h4Z%22%2F%3E%3C%2Fsvg%3E)   
+   */
+  NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN: string;
+
+  /**
+   * **NEXT_PUBLIC_POSTHOG_HOST**  
+   * type=url @required @public  
+   * ![icon](data:image/svg+xml;utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2220%22%20height%3D%2220%22%20viewBox%3D%220%200%2032%2032%22%3E%3Cpath%20fill%3D%22%23808080%22%20d%3D%22M29%2022h-5a2.003%202.003%200%200%201-2-2v-6a2%202%200%200%201%202-2h5v2h-5v6h5ZM18%2012h-4V8h-2v14h6a2.003%202.003%200%200%200%202-2v-6a2%202%200%200%200-2-2m-4%208v-6h4v6Zm-6-8H3v2h5v2H4a2%202%200%200%200-2%202v2a2%202%200%200%200%202%202h6v-8a2%202%200%200%200-2-2m0%208H4v-2h4Z%22%2F%3E%3C%2Fsvg%3E)   
+   */
+  NEXT_PUBLIC_POSTHOG_HOST: string;
+
+};
+
+type _CoercedEnvSchema_ec1ed0de = CoercedEnvSchema;
+
+declare module 'varlock/env' {
+  export interface TypedEnvSchema extends Readonly<_CoercedEnvSchema_ec1ed0de> {}
+  export interface PublicTypedEnvSchema extends Readonly<Pick<_CoercedEnvSchema_ec1ed0de, 'NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN' | 'NEXT_PUBLIC_POSTHOG_HOST'>> {}
+}
+
+
+export type EnvSchemaAsStrings = {
+  [Property in keyof CoercedEnvSchema]:
+    CoercedEnvSchema[Property] extends string ? CoercedEnvSchema[Property]
+      : (CoercedEnvSchema[Property] extends boolean ? ('true' | 'false') : string)
+};
+
+type _EnvSchemaAsStrings_ec1ed0de = EnvSchemaAsStrings;
+declare global {
+
+  // add types for global import.meta.env
+  interface ImportMetaEnv extends _EnvSchemaAsStrings_ec1ed0de {}
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+
+  // add types for global process.env
+  namespace NodeJS {
+    interface ProcessEnv extends _EnvSchemaAsStrings_ec1ed0de {}
+  }
+}

apps/docs/next.config.ts

@@ -1,8 +1,10 @@
 import path from "node:path";
+import { varlockNextConfigPlugin } from "@varlock/nextjs-integration/plugin";
 import { createMDX } from "fumadocs-mdx/next";
 import type { NextConfig } from "next";
 
 const withMDX = createMDX();
+const withVarlock = varlockNextConfigPlugin();
 // validateRegistry();
 
 const config: NextConfig = {
@@ -45,4 +47,4 @@ const config: NextConfig = {
   ],
 };
 
-export default withMDX(config);
+export default withVarlock(withMDX(config));

apps/docs/package.json

@@ -25,6 +25,7 @@
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slot": "^1.2.4",
     "@tabler/icons-react": "^3.36.1",
+    "@varlock/nextjs-integration": "^1.1.0",
     "beautiful-mermaid": "^1.1.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -47,6 +48,7 @@
     "tailwind-merge": "^3.4.0",
     "ts-morph": "^26.0.0",
     "twoslash": "^0.3.6",
+    "varlock": "^1.1.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {

apps/docs/src/components/DownloadButton.tsx

@@ -1,29 +1,26 @@
 "use client";
 
 import { ChevronDown, Download } from "lucide-react";
-import Link from "next/link";
 import { useEffect, useState } from "react";
+import { DownloadDialog } from "@/components/DownloadDialog";
 import { ButtonGroup } from "@/components/ui/button-group";
 import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { trackDownloadClick } from "@/lib/analytics";
 import { cn } from "@/lib/utils";
 
 type Platform = "mac" | "win";
 
-const platformOptions: Record<Platform, { label: string; href: string; icon: React.ReactNode }> = {
+const platformOptions: Record<Platform, { label: string; icon: React.ReactNode }> = {
   mac: {
     label: "Download for macOS",
-    href: "/download/mac",
     icon: <Download className="size-5" />,
   },
   win: {
     label: "Download for Windows",
-    href: "/download/win",
     icon: (
       <svg aria-hidden="true" className="size-5" fill="none" viewBox="0 0 24 24">
         <path d="M4 5.5h7v6H4zM13 5.5h7v6h-7zM4 13h7v5.5H4zM13 13h7v5.5h-7z" stroke="currentColor" strokeWidth="1.8" />
@@ -67,6 +64,8 @@ const variantStyles: Record<DownloadButtonVariant, { primary: string; chevron: s
 
 export function DownloadButton({ variant = "light", className }: DownloadButtonProps) {
   const [platform, setPlatform] = useState<Platform>("mac");
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [dialogPlatform, setDialogPlatform] = useState<Platform>("mac");
 
   useEffect(() => {
     setPlatform(detectPlatform());
@@ -77,51 +76,41 @@ export function DownloadButton({ variant = "light", className }: DownloadButtonP
   const other = platformOptions[otherKey];
   const styles = variantStyles[variant];
 
+  const openDialog = (p: Platform) => {
+    setDialogPlatform(p);
+    setDialogOpen(true);
+  };
+
   return (
-    <ButtonGroup className={className}>
-      <Link
-        className={cn("inline-flex items-center gap-3 rounded-l-full font-semibold text-base", styles.primary)}
-        href={primary.href}
-        onClick={() =>
-          trackDownloadClick({
-            detectedPlatform: platform,
-            selectedPlatform: platform,
-            variant,
-          })
-        }
-      >
-        {primary.icon}
-        {primary.label}
-      </Link>
-      <DropdownMenu>
-        <DropdownMenuTrigger
-          aria-label="Show other download options"
-          className={cn(
-            "inline-flex items-center justify-center rounded-r-full font-semibold focus-visible:outline-none",
-            styles.chevron,
-          )}
+    <>
+      <ButtonGroup className={className}>
+        <button
+          className={cn("inline-flex items-center gap-3 rounded-l-full font-semibold text-base", styles.primary)}
+          onClick={() => openDialog(platform)}
+          type="button"
         >
-          <ChevronDown className="size-5" />
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end">
-          <DropdownMenuItem asChild>
-            <Link
-              className="gap-3"
-              href={other.href}
-              onClick={() =>
-                trackDownloadClick({
-                  detectedPlatform: platform,
-                  selectedPlatform: otherKey,
-                  variant,
-                })
-              }
-            >
+          {primary.icon}
+          {primary.label}
+        </button>
+        <DropdownMenu>
+          <DropdownMenuTrigger
+            aria-label="Show other download options"
+            className={cn(
+              "inline-flex items-center justify-center rounded-r-full font-semibold focus-visible:outline-none",
+              styles.chevron,
+            )}
+          >
+            <ChevronDown className="size-5" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem className="gap-3" onSelect={() => openDialog(otherKey)}>
               {other.icon}
               {other.label}
-            </Link>
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
-    </ButtonGroup>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </ButtonGroup>
+      <DownloadDialog onOpenChange={setDialogOpen} open={dialogOpen} platform={dialogPlatform} />
+    </>
   );
 }