From e6604200938fcbe742e02e1cb934b1ed3b5904b4 Mon Sep 17 00:00:00 2001 From: Eric Luce <37158449+eluce2@users.noreply.github.com> Date: Thu, 7 May 2026 14:38:23 -0500 Subject: [PATCH 1/3] docs: add GitHub workflow guide for AI docs Adds a friendly Git/GitHub intro for FileMaker devs anchored to the shared user model they know, with light/dark themed diagrams via a new ThemedImage MDX component. Co-Authored-By: Claude Opus 4.7 (1M context) --- apps/docs/content/docs/ai/github-workflow.mdx | 138 ++++++++++++++++++ apps/docs/content/docs/ai/meta.json | 1 + .../docs/public/diagrams/github-flow-dark.svg | 5 + .../public/diagrams/github-flow-light.svg | 5 + .../diagrams/shared-user-model-dark.svg | 5 + .../diagrams/shared-user-model-light.svg | 5 + apps/docs/src/components/ThemedImage.tsx | 32 ++++ apps/docs/src/mdx-components.tsx | 2 + 8 files changed, 193 insertions(+) create mode 100644 apps/docs/content/docs/ai/github-workflow.mdx create mode 100644 apps/docs/public/diagrams/github-flow-dark.svg create mode 100644 apps/docs/public/diagrams/github-flow-light.svg create mode 100644 apps/docs/public/diagrams/shared-user-model-dark.svg create mode 100644 apps/docs/public/diagrams/shared-user-model-light.svg create mode 100644 apps/docs/src/components/ThemedImage.tsx diff --git a/apps/docs/content/docs/ai/github-workflow.mdx b/apps/docs/content/docs/ai/github-workflow.mdx new file mode 100644 index 00000000..d2950fd9 --- /dev/null +++ b/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. + + + 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. + + +## 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. + + + +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. + + + +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. + + + 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. + + +## 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. + + + + **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. + + + + **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. + + + + **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. + + + +## 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. + diff --git a/apps/docs/content/docs/ai/meta.json b/apps/docs/content/docs/ai/meta.json index 2943f837..d7a8c891 100644 --- a/apps/docs/content/docs/ai/meta.json +++ b/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", diff --git a/apps/docs/public/diagrams/github-flow-dark.svg b/apps/docs/public/diagrams/github-flow-dark.svg new file mode 100644 index 00000000..664cac48 --- /dev/null +++ b/apps/docs/public/diagrams/github-flow-dark.svg @@ -0,0 +1,5 @@ + + +GitHubDev JimDev EmilyCode>_Code>_>_Code>_ \ No newline at end of file diff --git a/apps/docs/public/diagrams/github-flow-light.svg b/apps/docs/public/diagrams/github-flow-light.svg new file mode 100644 index 00000000..b13bccd3 --- /dev/null +++ b/apps/docs/public/diagrams/github-flow-light.svg @@ -0,0 +1,5 @@ + + +GitHubDev JimDev EmilyCode>_Code>_>_Code>_ \ No newline at end of file diff --git a/apps/docs/public/diagrams/shared-user-model-dark.svg b/apps/docs/public/diagrams/shared-user-model-dark.svg new file mode 100644 index 00000000..94b8a6dd --- /dev/null +++ b/apps/docs/public/diagrams/shared-user-model-dark.svg @@ -0,0 +1,5 @@ + + +FileMaker ServerMyApp.fmp12Dev JimDev EmilyUser Jack \ No newline at end of file diff --git a/apps/docs/public/diagrams/shared-user-model-light.svg b/apps/docs/public/diagrams/shared-user-model-light.svg new file mode 100644 index 00000000..9c5d0cf9 --- /dev/null +++ b/apps/docs/public/diagrams/shared-user-model-light.svg @@ -0,0 +1,5 @@ + + +FileMaker ServerMyApp.fmp12Dev JimDev EmilyUser Jack \ No newline at end of file diff --git a/apps/docs/src/components/ThemedImage.tsx b/apps/docs/src/components/ThemedImage.tsx new file mode 100644 index 00000000..cd00c14e --- /dev/null +++ b/apps/docs/src/components/ThemedImage.tsx @@ -0,0 +1,32 @@ +import Image from "next/image"; +import { cn } from "../lib/cn"; + +interface ThemedImageProps { + lightSrc: string; + darkSrc: string; + alt: string; + width: number; + height: number; + className?: string; +} + +export function ThemedImage({ lightSrc, darkSrc, alt, width, height, className }: ThemedImageProps) { + return ( + <> + {alt} + {alt} + + ); +} diff --git a/apps/docs/src/mdx-components.tsx b/apps/docs/src/mdx-components.tsx index d08ad112..9cfc9bf5 100644 --- a/apps/docs/src/mdx-components.tsx +++ b/apps/docs/src/mdx-components.tsx @@ -6,6 +6,7 @@ import { Tab, Tabs } from "fumadocs-ui/components/tabs"; import defaultComponents from "fumadocs-ui/mdx"; import type { MDXComponents } from "mdx/types"; import { Mermaid } from "@/components/Mermaid"; +import { ThemedImage } from "@/components/ThemedImage"; import { YouTubeVideo } from "@/components/YouTubeVideo"; const generator = createGenerator(); @@ -17,6 +18,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents { Mermaid, Tab, Tabs, + ThemedImage, YouTubeVideo, ...Twoslash, ...components, From 214b8c3df98386d1b28f62f46bc33bd52df61c1b Mon Sep 17 00:00:00 2001 From: Eric Luce <37158449+eluce2@users.noreply.github.com> Date: Fri, 8 May 2026 12:39:24 -0500 Subject: [PATCH 2/3] Add email download dialog to docs - replace direct download links with email capture - wire docs to varlock env loading - add shared dialog and select primitives --- apps/docs/.env.schema | 11 + apps/docs/env.d.ts | 52 ++++ apps/docs/next.config.ts | 4 +- apps/docs/package.json | 2 + apps/docs/src/components/DownloadButton.tsx | 83 +++---- apps/docs/src/components/DownloadDialog.tsx | 98 ++++++++ apps/docs/src/components/ui/button.tsx | 14 +- apps/docs/src/components/ui/dialog.tsx | 81 +++++++ apps/docs/src/components/ui/select.tsx | 69 ++++++ apps/docs/src/instrumentation-client.ts | 5 +- apps/docs/src/lib/analytics.ts | 10 +- biome.json | 9 + package.json | 1 + pnpm-lock.yaml | 252 ++++++++++++-------- 14 files changed, 541 insertions(+), 150 deletions(-) create mode 100644 apps/docs/.env.schema create mode 100644 apps/docs/env.d.ts create mode 100644 apps/docs/src/components/DownloadDialog.tsx create mode 100644 apps/docs/src/components/ui/dialog.tsx create mode 100644 apps/docs/src/components/ui/select.tsx diff --git a/apps/docs/.env.schema b/apps/docs/.env.schema new file mode 100644 index 00000000..7ff76971 --- /dev/null +++ b/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 diff --git a/apps/docs/env.d.ts b/apps/docs/env.d.ts new file mode 100644 index 00000000..a72360c5 --- /dev/null +++ b/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> {} +} + + +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 {} + } +} \ No newline at end of file diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts index 85a8c81c..ae82e610 100644 --- a/apps/docs/next.config.ts +++ b/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)); diff --git a/apps/docs/package.json b/apps/docs/package.json index c7041104..aee9ff62 100644 --- a/apps/docs/package.json +++ b/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": { diff --git a/apps/docs/src/components/DownloadButton.tsx b/apps/docs/src/components/DownloadButton.tsx index ab65a090..1c2f34d1 100644 --- a/apps/docs/src/components/DownloadButton.tsx +++ b/apps/docs/src/components/DownloadButton.tsx @@ -1,8 +1,8 @@ "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, @@ -10,20 +10,17 @@ import { DropdownMenuItem, DropdownMenuTrigger, } from "@/components/ui/dropdown-menu"; -import { trackDownloadClick } from "@/lib/analytics"; import { cn } from "@/lib/utils"; type Platform = "mac" | "win"; -const platformOptions: Record = { +const platformOptions: Record = { mac: { label: "Download for macOS", - href: "/download/mac", icon: , }, win: { label: "Download for Windows", - href: "/download/win", icon: (
+
+ +
+

Check your email

+

+ We sent a download link to{" "} + {submittedEmail}. +

+
+ ) : ( + <> + + Download ProofKit + Enter your email below and we'll send you a download link. + +
+
+ + setEmail(e.target.value)} + placeholder="you@example.com" + required + type="email" + value={email} + /> +
+ +
+ + )} + + + ); +} diff --git a/apps/docs/src/components/ui/button.tsx b/apps/docs/src/components/ui/button.tsx index b6c1b39a..bc5cafe1 100644 --- a/apps/docs/src/components/ui/button.tsx +++ b/apps/docs/src/components/ui/button.tsx @@ -1,4 +1,7 @@ import { cva, type VariantProps } from "class-variance-authority"; +import type * as React from "react"; + +import { cn } from "@/lib/utils"; const variants = { primary: "bg-fd-primary text-fd-primary-foreground hover:bg-fd-primary/80", @@ -7,12 +10,11 @@ const variants = { secondary: "border bg-fd-secondary text-fd-secondary-foreground hover:bg-fd-accent hover:text-fd-accent-foreground", } as const; -export const buttonVariants = cva( +const buttonVariants = cva( "inline-flex items-center justify-center rounded-md p-2 font-medium text-sm transition-colors duration-100 focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50", { variants: { variant: variants, - // fumadocs use `color` instead of `variant` color: variants, size: { sm: "gap-1 px-2 py-1.5 text-xs", @@ -24,4 +26,10 @@ export const buttonVariants = cva( }, ); -export type ButtonProps = VariantProps; +type ButtonProps = VariantProps; + +function Button({ className, variant, size, ...props }: React.ComponentProps<"button"> & ButtonProps) { + return + + + ); +} diff --git a/apps/docs/src/mdx-components.tsx b/apps/docs/src/mdx-components.tsx index 9cfc9bf5..b0de863d 100644 --- a/apps/docs/src/mdx-components.tsx +++ b/apps/docs/src/mdx-components.tsx @@ -5,6 +5,7 @@ import { AutoTypeTable } from "fumadocs-typescript/ui"; import { Tab, Tabs } from "fumadocs-ui/components/tabs"; import defaultComponents from "fumadocs-ui/mdx"; import type { MDXComponents } from "mdx/types"; +import { DownloadLink } from "@/components/DownloadLink"; import { Mermaid } from "@/components/Mermaid"; import { ThemedImage } from "@/components/ThemedImage"; import { YouTubeVideo } from "@/components/YouTubeVideo"; @@ -15,6 +16,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultComponents, AutoTypeTable: (props) => , + DownloadLink, Mermaid, Tab, Tabs,