feat(cli): revamp webviewer app scaffolding

.agents/skills/create-changeset/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: create-changeset
+description: Analyze git changes and create changesets for package releases. Use when preparing pull requests, creating PRs, when branch has commits ready for review, or when user mentions changeset or version bump.
+---
+# Create Changeset Skill
+
+## Purpose
+
+This skill automatically analyzes branch changes and creates appropriate changesets for package releases in this monorepo. It examines git history, determines version bump types based on Conventional Commits, and generates properly formatted changeset files.
+
+## When to Invoke
+
+Automatically invoke this skill when:
+- User is preparing to create a pull request
+- User mentions "PR", "pull request", or "ready for review"
+- Branch has commits ready for review
+- User explicitly mentions "changeset" or "version bump"
+
+Do NOT invoke when:
+- User is only pushing changes without creating a PR
+- Only documentation files have changed (README, .md files)
+- Only CI/CD configuration has changed (.github/workflows/)
+- Only development tool configuration has changed (eslint, prettier, etc.)
+- Commits are only `docs:`, `chore:`, `ci:`, or `test:` types that don't affect packages
+
+## Pre-execution Validation
+
+Before creating a changeset, check if a changeset file already exists for the current changes:
+- Look for `.changeset/*.md` files (excluding README.md)
+- If exists, ask user: "A changeset already exists. Create another one?"
+
+## Implementation Steps
+
+### 1. Check Current State
+
+Execute `git log main..HEAD` (or `origin/main..HEAD`) to check for committed changes on the branch. If no commits exist, exit early without creating a changeset.
+
+### 2. Analyze Changes
+
+Use `git diff main...HEAD` (or `origin/main...HEAD`) to analyze **committed changes only**.
+
+Identify which packages are affected by checking files under `packages/*/`. Review commit messages using `git log main..HEAD --oneline` (or `origin/main..HEAD`).
+
+### 3. Determine Version Bump Type
+
+Analyze commit messages following Conventional Commits 1.0.0 format:
+
+- **major**: Contains `BREAKING CHANGE` in commit body, or breaking changes detected in code
+  - API signature changes
+  - Removed exports or features
+  - Incompatible behavior changes
+- **minor**: Starts with `feat:` or `feat(scope):` - new features (backward compatible)
+  - New components or functionality
+  - New props or options (with defaults)
+  - New exports
+- **patch**: Starts with `fix:` or `fix(scope):` - bug fixes and minor improvements
+  - Bug fixes
+  - Performance improvements
+  - Minor style updates
+- **skip**: Other types (`chore:`, `docs:`, `ci:`, `test:`) typically don't require changesets unless they affect package functionality
+
+Review actual code changes to confirm the appropriate version bump. **When in doubt between minor and patch, prefer patch for safety.**
+
+If the version bump is ambiguous or unclear:
+- Ask user for clarification
+- Explain the reasoning behind the suggested bump type
+- Allow user to override the suggestion
+
+If all commits are types that don't require changesets (`docs:`, `chore:`, `ci:`, `test:`), exit early without creating a changeset.
+
+### 4. Generate Changeset
+
+Create a changeset file with a descriptive filename in `.changeset/` directory.
+
+**Filename format:**
+- Use kebab-case with `.md` extension
+- Examples: `.changeset/add-new-button.md`, `.changeset/fix-layout-bug.md`, `.changeset/update-icon-props.md`
+
+**File content format:**
+```markdown
+---
+"@proofkit/package-name": major|minor|patch
+---
+
+Clear description of the change
+```
+
+**Example for single package:**
+```markdown
+---
+"@proofkit/cli": minor
+---
+
+Add new Button variant for secondary actions
+```
+
+**Example for multiple packages:**
+```markdown
+---
+"@proofkit/cli": minor
+"@proofkit/typegen": patch
+---
+
+- @proofkit/cli: Add new Button variant for secondary actions
+- @proofkit/typegen: Fix color token contrast ratio
+```
+
+**Important guidelines:**
+- The description should be user-friendly as it will appear in CHANGELOG
+- **Use the same language as the commit messages** (Japanese or English). If commit messages are mixed, prefer Japanese.
+- Split changesets into separate files when the same package has changes with different purposes (e.g., new feature + bug fix, breaking change + internal refactoring)
+- This creates individual top-level items in release notes, making it easier for readers to understand the intent of each change
+- Example: Create `.changeset/add-secondary-button.md` for a new feature and `.changeset/fix-button-layout.md` for a bug fix, even if both target the same package
+
+### 5. Lint Changeset
+
+Execute `pnpm textlint .changeset/<filename>.md` to validate the changeset file.
+
+**Error handling:**
+- If linting errors occur, attempt to auto-fix common issues:
+  - Spacing and punctuation
+  - Common grammar mistakes
+- Re-run textlint after auto-fix
+- If errors persist:
+  - Display error details to user
+  - Ask user for guidance on how to fix
+  - Do NOT proceed to commit until lint passes
+
+### 6. Verify and Commit
+
+Display the generated changeset for review:
+- Show the file path
+- Show the file content
+- Confirm it accurately reflects the changes
+
+Once verified, commit the changeset file:
+```bash
+git add .changeset/<filename>.md
+git commit -m "chore: add changeset"
+```

.changeset/cli-webviewer-scaffold-fmhttp.md

@@ -0,0 +1,12 @@
+---
+"@proofkit/cli": minor
+"@proofkit/typegen": minor
+"@proofkit/fmdapi": patch
+"@proofkit/fmodata": patch
+"@proofkit/webviewer": patch
+---
+
+- cli: Revamp the WebViewer Vite template and harden `proofkit init` (ignore hidden files, improve non-interactive prompts, stop generating Cursor rules).
+- cli: Install typegen skills locally when scaffolding projects.
+- typegen: Add optional `fmHttp` config for using an FM HTTP proxy during metadata fetching.
+- fmdapi/fmodata/webviewer: Add initial Codex skills for client and integration workflows.

apps/docs/content/docs/cli/webviewer/getting-started.mdx

@@ -11,24 +11,18 @@ import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock";
 // import Prerequisites from "../../../components/Prerequisites.mdx";
 import InitCommand from "@/components/InitCommand";
 
-Creating a ProofKit project for a FileMaker WebViewer is extremely similar to the browser-based version as covered in the [main Getting Started guide](/docs/cli/guides/getting-started). This document will simply highlight the key differences.
+Creating a ProofKit project for a FileMaker WebViewer is extremely similar to the browser-based version as covered in the [main Getting Started guide](/docs/cli/guides/getting-started). This document highlights the WebViewer-specific workflow.
 
 ## Prep your FileMaker file
 
-- The file must be hosted on a FileMaker server running OttoFMS (4.7 or later)
-- The server must have the Data API enabled.
-- You must have a user account that has the `fmrest` extended privilege enabled.
-- The Full Access user account must have the `fmurlscript` extended privilege enabled (Allow URLs to run FileMaker scripts)
-
-<Callout type="info" title="Why does it have to be hosted?">
-  The ProofKit CLI uses the metadata endpoint of the Data API to learn about the
-  layouts and fields in your file to generate type-safe code that can be used in
-  your webviewer. This is only for development though; once you build your web
-  code for production, it can interact directly with the FileMaker Pro client
-  and will work even offline.
-
-In a future release, we may provide a way to scaffold a new webviewer project for use with local development, but there are other tradeoffs to consider.
+- Install the ProofKit WebViewer add-on into the file you want to target.
+- Make sure the file has the scripts needed by your WebViewer workflow, such as `Launch Web Viewer for Dev` and `UploadWebviewerWidget`.
+- If you want local typegen without a hosted server, start the FM HTTP bridge and keep a connected FileMaker file open.
 
+<Callout type="info" title="Hosted FileMaker is no longer required for scaffolding">
+  A new WebViewer project can be scaffolded without OttoFMS or hosted FileMaker credentials.
+  When you are ready to generate layout clients, ProofKit prefers the local FM HTTP path first.
+  Hosted FileMaker server setup is still available later when you want it.
 </Callout>
 
 ## Creating a ProofKit Project
@@ -39,29 +33,27 @@ Run the following command to scaffold a new ProofKit project, choosing the `webv
 
 Refer to the [main Getting Started guide](/docs/cli/guides/getting-started) for more details on the prompts and options available.
 
-## Install the ProofKit WebViewer Addon
+The scaffolded app already includes Tailwind v4, shadcn config, helper scripts, and a starter `proofkit-typegen.config.jsonc` file wired for FM HTTP.
 
-The ProofKit CLI will automatically install the ProofKit WebViewer to your computer, but you must install it into your FileMaker file to receive the necessary tables, layouts, and scripts.
+## Generate layout clients later
 
-To easily install the add-on, enter Layout mode on any layout and open the "Add-ons" tab in the left pane. Click the + icon in the lower left corner, then select the "ProofKit Auth" add-on from the list.
+When you are ready to add generated FileMaker clients:
 
-<Callout type="warning" title="Troubleshooting">
-If you don't see the add-on after initialing your project with the CLI, quit and re-open FileMaker Pro.
-</Callout>
+- Edit `proofkit-typegen.config.jsonc` and add the layouts you want.
+- Run `pnpm typegen` or `pnpm typegen:ui`.
+- If FM HTTP is running with a connected file, ProofKit can use that local path instead of a hosted server.
 
 ## Developing with the WebViewer
 
-When you run the dev server with the `dev` command, a localhost URL will be displayed for you to see your project in a browser. **DO NOT OPEN THIS URL IN A BROWSER**
+When you run the dev server with the `dev` command, a localhost URL will be displayed. Unlike older templates, the starter app is browser-safe and can render there normally. You still need FileMaker to test script execution and real WebViewer behavior.
 
 In modern FileMaker versions, the WebViewer is just as capable as any other browser, but if your users are going to exclusively be running this code in a WebViewer, you should also be developing with the the WebViewer as your browser. Plus, it's the only way to test the FileMaker interactions that you will likely build.
 
-Thankfully, the ProofKit WebViewer Addon makes it easy to switch your webviewer from dev mode and production mode.
-
 With your dev server running (e.g. `pnpm dev`), open a **seperate** terminal instance and run:
 
 <CliCommand command="launch-fm" />
 
-which will open your FileMaker file in FileMaker Pro and run the `Launch Web Viewer for Dev` script. This script will ensure that you're on the correct layout and that the WebViewer is running in dev mode—pointing to your localhost URL.
+This command prefers a locally connected FM HTTP file first, then falls back to `FM_SERVER` and `FM_DATABASE` from `.env`. It opens FileMaker Pro and runs the `Launch Web Viewer for Dev` script so your WebViewer points at the local dev server.
 
 You can use the other utility scripts to build your own version of this behavior:
 
@@ -82,7 +74,7 @@ The final command is simply a shortcut for running the `build` and `upload` comm
 
 The `build` command will compile your project into a single html file, which will be output to the `dist` directory.
 
-The `upload` command will use the fmp URL protocol to call a script in your FileMaker file with the path to the html file. The FileMaker script will read the data from that file and insert it into a single-record field in the `ProofKitWV` table.
+The `upload` command uses the fmp URL protocol to call a script in your FileMaker file with the path to the built html file. Like `launch-fm`, it prefers a locally connected FM HTTP file before falling back to hosted server env vars.
 
 <Callout type="warning" title="Data Migrations">
 If you are working with a seperated Dev/Production environments and running migrations to deploy your code to production, the uploaded code will not transfer to your production environment. See the [Deployment Methods](/webviewer/deployment-methods) page for more details.

apps/docs/content/docs/cli/webviewer/overview.mdx

@@ -11,7 +11,7 @@ The FileMaker Web Viewer object is a powerful way to build rich, interactive exp
 
 #### What is the difference between the WebViewer and the browser-based project created with the ProofKit CLI?
 
-The primary difference is the framework used. For browser-based projects, we use [Next.js](https://nextjs.org/) and the WebViewer project uses [Vite](https://vitejs.dev/) and [Tanstack Router](https://tanstack.com/router). Next.js is a full-stack framework, meaning that it results in some code that is expected to run on a server AND some code that runs in the browser. Vite allows us to build s single bundle of code for the browser that can be store in FileMaker and if needed, we can use the FileMaker Pro client as the "server" to run private functions and "host" the code.
+The primary difference is the framework and runtime shape. Browser-based projects use [Next.js](https://nextjs.org/) while the WebViewer starter uses [Vite](https://vitejs.dev/) with a small browser-only React app. That keeps the WebViewer scaffold close to a stock Vite starter while still being ready for ProofKit WebViewer integration, Tailwind v4, and shadcn component installs.
 
 #### Can I build WebViewer applications using Next.js?
 
@@ -20,3 +20,7 @@ Yes! This is sometimes preferred if you already hae a web app and want to keep t
 #### Does this technique work in Web Direct?
 
 Yes. The ProofKit WebViewer Addon includes a custom function that wraps your web code so the injected FileMaker JavaScript code will still interface with the WebViewer, even in Web Direct.
+
+#### Do I need a hosted FileMaker server to start?
+
+No. You can scaffold the WebViewer app without hosted FileMaker credentials. When you are ready to generate layout clients, ProofKit prefers the local FM HTTP path first and only needs hosted server setup if you choose that route.

apps/docs/content/docs/typegen/config.mdx

@@ -76,9 +76,9 @@ The typegen tool is configured using the `proofkit-typegen-config.jsonc` file at
         "If set, will generate the client using the @proofkit/webviewer package",
     },
     fmHttp: {
-      type: "{ scriptName?: string }",
+      type: "{ enabled?: boolean; scriptName?: string; baseUrl?: string; connectedFileName?: string }",
       description:
-        "Optional local-only adapter mode for typegen metadata fetch. Generated clients still use the @proofkit/webviewer adapter.",
+        "Optional local FM HTTP mode for metadata fetching during typegen. Generated runtime clients still use the WebViewer adapter.",
     },
     generateClient: {
       type: "boolean",

biome.json

@@ -62,7 +62,7 @@
       "arrowParentheses": "always",
       "quoteStyle": "double"
     },
-    "globals": ["__FMDAPI_VERSION__", "__BETTER_AUTH_VERSION__"]
+    "globals": ["__FMDAPI_VERSION__", "__BETTER_AUTH_VERSION__", "__WEBVIEWER_VERSION__", "__TYPEGEN_VERSION__"]
   },
   "json": {
     "formatter": {

packages/cli/src/cli/add/auth.ts

@@ -4,8 +4,8 @@ import { Command } from "commander";
 import { z } from "zod/v4";
 
 import { addAuth } from "~/generators/auth.js";
-import { ciOption, debugOption } from "~/globalOptions.js";
-import { initProgramState, state } from "~/state.js";
+import { ciOption, debugOption, nonInteractiveOption } from "~/globalOptions.js";
+import { initProgramState, isNonInteractiveMode, state } from "~/state.js";
 import { getSettings } from "~/utils/parseSettings.js";
 import { abortIfCancel } from "../utils.js";
 
@@ -44,7 +44,7 @@ export async function runAddAuthAction() {
   if (type === "fmaddon") {
     const emailProviderAnswer =
       state.emailProvider ??
-      (state.ci ? "none" : undefined) ??
+      (isNonInteractiveMode() ? "none" : undefined) ??
       abortIfCancel(
         await select({
           message: `What email provider do you want to use?\n${chalk.dim(
@@ -88,6 +88,7 @@ export const makeAddAuthCommand = () => {
     .option("--emailProvider <emailProvider>", "Email provider to use (only for FM Add-on Auth)")
     .option("--apiKey <apiKey>", "API key to use for the email provider (only for FM Add-on Auth)")
     .addOption(ciOption)
+    .addOption(nonInteractiveOption)
     .addOption(debugOption)
 
     .action(async () => {