formhaus 0.14.2 → 0.19.0

package/README.md

@@ -6,7 +6,35 @@ Adds the [Formhaus](https://formhaus.dev) MCP server and agent instructions to t
 npx formhaus
 ```
 
-Run it inside a project to also add the Cursor rule there. Requires Node 20 or later.
+Run it anywhere inside a project to also add the Cursor rule at the project root: the nearest folder above with `.git`, `package.json` or `.cursor`, below your home directory. Requires Node 22.12 or later.
+
+```text
+Formhaus is ready in Claude Code, Codex, Cursor and Claude Desktop.
+
+  ✓ Claude Code     added MCP server and form skill
+  ✓ Codex           added MCP server
+  ✓ Cursor          added MCP server · run in a project to add the Cursor rule
+  ✓ Claude Desktop  added MCP server
+  – OpenCode        add it by hand: https://formhaus.dev/guide/mcp
+
+Next
+  1. Restart your agents.
+  2. Ask one: "Build a contact form with Formhaus: name, email, message."
+  3. Show it on your site: npm i @formhaus/core @formhaus/react
+     For Vue use @formhaus/vue. Guide: https://formhaus.dev/guide/
+     No site? Publish it and collect responses at https://app.formhaus.dev
+
+Config backups were saved as .bak. See every file: npx formhaus --verbose
+```
+
+Running it again prints `already set up` for each agent. A step that fails is marked `✗` with the fix below it, and the exit code is 1. Symbols are colored only in a terminal, and `NO_COLOR` turns color off.
+
+## What next
+
+1. Restart your agents so they load the Formhaus MCP server.
+2. Ask one to build a form: "Build a contact form with Formhaus: name, email, message."
+3. Render the definition with `npm i @formhaus/core @formhaus/react` or `@formhaus/vue`. See [Getting started](https://formhaus.dev/guide/).
+4. Or publish it without code and collect responses at [app.formhaus.dev](https://app.formhaus.dev).
 
 ## What it changes
 
@@ -14,12 +42,12 @@ Run it inside a project to also add the Cursor rule there. Requires Node 20 or l
 |-------|-------------|--------|
 | Claude Code | `claude` on `PATH` | `claude mcp add --scope user formhaus -- npx -y @formhaus/mcp` and the `formhaus-create-form` skill in `~/.claude/skills` |
 | Codex | `~/.codex` or `codex` on `PATH` | `[mcp_servers.formhaus]` in `~/.codex/config.toml` |
-| Cursor | `~/.cursor` or `cursor` on `PATH` | `formhaus` in `~/.cursor/mcp.json`, and `.cursor/rules/formhaus.mdc` when run inside a project |
+| Cursor | `~/.cursor` or `cursor` on `PATH` | `formhaus` in `~/.cursor/mcp.json`, and `.cursor/rules/formhaus.mdc` at the project root |
 | Claude Desktop | its config directory on macOS and Windows | `formhaus` in `claude_desktop_config.json` |
 
-Windsurf, Gemini CLI, OpenCode, VS Code and Claude Desktop on Linux are detected and listed with manual setup steps.
+Windsurf, Gemini CLI, OpenCode, VS Code and Claude Desktop on Linux are detected and listed with a link to the manual setup steps.
 
-Existing entries are kept. An existing `formhaus` server with another command or args is reported and left unchanged, and a project `.mcp.json` never counts as set up. Before the first change to a file, the original is saved as `<file>.bak`. Formhaus does not write to a file that is a symbolic link, or through a linked directory inside the project. Running it again changes nothing. If the Formhaus Claude Code plugin is installed, Claude Code is left as is.
+Existing entries are kept. An existing `formhaus` server with another command or args is reported and left unchanged, and a project `.mcp.json` never counts as set up. Before the first change to a config file, the original is saved as `<file>.bak`. If you edited the Cursor rule or the skill, Formhaus keeps your version. `--force` replaces it and saves your version as `<file>.bak`. Formhaus does not write to a file that is a symbolic link, or through a linked directory inside the project. Running it again changes nothing. If the Formhaus Claude Code plugin is installed, Claude Code is left as is.
 
 ## Options
 
@@ -27,6 +55,8 @@ Existing entries are kept. An existing `formhaus` server with another command or
 npx formhaus [setup] [options]
 
   --dry-run      Show the planned changes and write nothing
+  --force        Replace your edited skill and rule, saving them as .bak
+  --verbose      List every file it checks or changes, and the backups
   -h, --help     Show help
   -v, --version  Show the version
 ```

package/dist/cli.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 import { homedir } from 'os';
 import { parseArgs, isDeepStrictEqual } from 'util';
-import { existsSync, statSync, accessSync, constants, readFileSync, mkdirSync, copyFileSync, rmSync, writeFileSync, chmodSync, renameSync, lstatSync } from 'fs';
-import { join, isAbsolute, sep, dirname, relative, resolve } from 'path';
+import { join, isAbsolute, resolve, dirname, parse, sep, relative } from 'path';
 import { spawnSync } from 'child_process';
+import { randomBytes, createHash } from 'crypto';
+import { existsSync, statSync, accessSync, constants, realpathSync, readFileSync, mkdirSync, copyFileSync, renameSync, rmSync, lstatSync, writeFileSync, chmodSync } from 'fs';
 
 // package.json
-var version = "0.14.2";
+var version = "0.19.0";
 
 // ../../.cursor/rules/formhaus.mdc
 var formhaus_default = '---\ndescription: Formhaus form definitions. Use when creating, editing or reviewing a Formhaus JSON form definition, or code that passes one to FormEngine or FormRenderer.\nalwaysApply: false\n---\n\n# Formhaus form definitions\n\nA Formhaus form is a JSON definition rendered by `@formhaus/core` with `@formhaus/react` or `@formhaus/vue`. One definition drives the web form and the Figma plugin.\n\n- Start each definition file with `"$schema": "https://formhaus.dev/schema/form-definition.json"`.\n- Required keys: `id` (kebab-case), `title`, `submit: { "label": "..." }`.\n- Use `fields` for a single page or `steps` for a multi-step form, never both.\n- Field `key` values are camelCase and unique across all steps.\n- `show` and `showAny` conditions reference existing field keys and use `eq`, `neq`, `in`, `notIn` or `notEmpty`.\n- Step `routes` only point to later steps. `to: null` ends the form without auto-submission.\n\n## Checking definitions\n\nWhen the `formhaus` MCP server is available (`npx -y @formhaus/mcp`):\n\n- Call `capabilities` for the current field types, validation rules and step semantics.\n- Call `example_definitions` for working examples.\n- Call `validate_definition` after every change and fix all `errors` before finishing.\n- Call `simulate_path` with sample answers to check branching steps and conditions.\n\nReference: https://formhaus.dev/api/definition.html\n';
 
 // ../../plugins/formhaus/skills/formhaus-create-form/SKILL.md
-var SKILL_default = '---\nname: formhaus-create-form\ndescription: |\n  Generate @formhaus/core form definitions from any input: text description,\n  CSV/table, or screenshot of a form. Interactive step/condition builder.\n  Output pastes directly into the Formhaus Figma plugin or FormRenderer.\n  Use when: "generate form", "form definition", "form JSON", "create a form",\n  "formhaus", or when user describes form fields in any format.\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - AskUserQuestion\n  - Agent\n  - mcp__plugin_formhaus_formhaus__validate_definition\n  - mcp__plugin_formhaus_formhaus__simulate_path\n  - mcp__plugin_formhaus_formhaus__capabilities\n  - mcp__plugin_formhaus_formhaus__example_definitions\n  - mcp__plugin_formhaus_formhaus__publish_form\n  - mcp__plugin_formhaus_formhaus__list_forms\n  - mcp__formhaus__validate_definition\n  - mcp__formhaus__simulate_path\n  - mcp__formhaus__capabilities\n  - mcp__formhaus__example_definitions\n  - mcp__formhaus__publish_form\n  - mcp__formhaus__list_forms\n  - Edit\n  - Bash\n---\n\n# Form Definition Generator\n\nYou generate valid `@formhaus/core` form definitions from any input.\nThe output is ready to paste into the Formhaus Figma plugin or use with FormRenderer.\nThe formhaus repo does not need to be cloned. The JSON Schema is published at\n`https://formhaus.dev/schema/form-definition.json`.\n\n## Formhaus MCP tools\n\nCheck whether the `formhaus` MCP server tools are available (`validate_definition`,\n`simulate_path`, `capabilities`, `example_definitions`, `publish_form`). The Formhaus Claude Code plugin\nstarts the server. Without the plugin, it is added with\n`claude mcp add formhaus -- npx -y @formhaus/mcp`.\n\n- `capabilities` returns the current field types, validation rules, condition operators\n  and step semantics. Prefer it over the reference below when they differ.\n- `example_definitions` lists bundled example definitions and returns one by `id`.\n- `validate_definition` checks a definition against the JSON Schema and the engine.\n- `simulate_path` walks a multi-step definition with sample answers and reports the step path.\n- `publish_form` publishes a definition to Formhaus Cloud and returns a live endpoint, a hosted page URL, an embed snippet and a React snippet.\n\nIf the tools are not available, validate by hand against the types below and tell the\nuser that `@formhaus/mcp` can check the result.\n\n## Types Reference\n\nThese are the exact TypeScript types. Your output MUST conform to them.\n\n```typescript\ninterface FormDefinition {\n  id: string;           // kebab-case identifier\n  title: string;        // human-readable form title\n  description?: string; // short intro under the title, up to 1000 characters\n  submit: FormAction;   // submit button config (required)\n  cancel?: FormAction;  // cancel button (optional)\n  fields?: FormField[]; // single-step form\n  steps?: FormStep[];   // multi-step form (use steps OR fields, not both)\n}\n\ninterface FormStep {\n  id: string;\n  title: string;\n  description?: string;\n  fields: FormField[];\n  show?: ShowCondition[];    // step visible when ALL conditions true\n  showAny?: ShowCondition[]; // step visible when ANY condition true\n  routes?: StepRoute[];      // ordered forward destinations\n  next?: FormAction | false; // custom "next" or false to hide it\n  back?: FormAction | false; // custom "back" or false to hide it\n  skip?: FormAction;         // Skip button: resets the step, moves on without validation\n}\n\ninterface StepRoute {\n  to: string | null;         // later step id, or terminal without auto-submission\n  show?: ShowCondition[];\n  showAny?: ShowCondition[];\n}\n\ninterface FormField {\n  key: string;                // camelCase field identifier\n  type: FieldType;\n  label: string;\n  placeholder?: string;\n  helperText?: string;\n  defaultValue?: unknown;\n  autoAdvance?: boolean;     // explicit activation advances; built-in radio supports it\n  show?: ShowCondition[];     // field visible when ALL conditions true\n  showAny?: ShowCondition[];  // field visible when ANY condition true\n  validation?: FieldValidation;\n  options?: FieldOption[];    // for select, multiselect, radio\n  layout?: \'stack\' | \'inline\'; // radio/multiselect; inline only for a few short options\n  optionsFrom?: string;       // dynamic options loaded at runtime\n  optionsDependsOn?: string[];\n  accept?: string;            // for file type: "image/*", ".pdf"\n  rows?: number;              // for textarea\n  mask?: string;              // input mask\n  inputMode?: \'text\' | \'numeric\' | \'decimal\' | \'tel\' | \'email\' | \'url\' | \'search\';\n}\n\ntype FieldType =\n  | \'text\' | \'email\' | \'phone\' | \'number\' | \'password\'\n  | \'select\' | \'autocomplete\' | \'multiselect\'\n  | \'checkbox\' | \'radio\' | \'switch\'\n  | \'file\' | \'date\' | \'datetime\' | \'time\' | \'textarea\' | \'hidden\';\n\ninterface ShowCondition {\n  field: string;                        // references another field\'s key\n  eq?: string | number | boolean;       // equals\n  neq?: string | number | boolean;      // not equals\n  in?: (string | number)[];             // one of\n  notIn?: (string | number)[];          // not one of\n  notEmpty?: boolean;                   // has a value\n}\n\ninterface FieldValidation {\n  required?: boolean | string;  // true or custom message\n  minLength?: number;\n  minLengthMessage?: string;\n  maxLength?: number;\n  maxLengthMessage?: string;\n  min?: number;\n  minMessage?: string;\n  max?: number;\n  maxMessage?: string;\n  pattern?: string;             // regex\n  patternMessage?: string;\n  matchField?: string;          // must match another field (e.g. confirmPassword)\n  matchFieldMessage?: string;\n  validator?: string;           // custom validator name\n}\n\ninterface FieldOption { value: string; label: string; }\ninterface FormAction {\n  label: string;\n  variant?: \'primary\' | \'secondary\' | \'text\';\n  action?: string;\n  disabled?: ShowCondition[];\n}\n```\n\n## Workflow\n\n### Step 1: Detect input format\n\nLook at the user\'s input and classify:\n\n- **Text description**: "Registration form with name, email, password"\n- **CSV/table**: structured data with columns like key, type, label, required\n- **Screenshot**: user provides a path to an image file or says "look at this screenshot"\n- **Existing definition**: user references a bundled example (`example_definitions`)\n\n### Step 2: Extract fields\n\nFrom the input, extract a flat list of fields with: key, type, label, and any\nobvious validation (required, email format, etc).\n\n**Type inference rules:**\n- Email addresses \u2192 `email`\n- Phone numbers \u2192 `phone`\n- Passwords, PINs \u2192 `password`\n- "Agree to terms", "Subscribe" \u2192 `checkbox`\n- "Account type", "Gender" with 2-4 options \u2192 `radio`\n- Dropdowns, "Select..." with 5+ options \u2192 `select`\n- Searchable dropdowns, typeahead \u2192 `autocomplete`\n- Country, city, currency \u2192 `select`\n- Long text, "Description", "Notes", "Bio" \u2192 `textarea`\n- Dates, birthdays, "When" \u2192 `date`\n- Date and time together \u2192 `datetime`\n- Time of day only, "Start time", "Opening hours" \u2192 `time`\n- Tracking values the user never sees, "Source", "Campaign", "Referral code from the link" \u2192 `hidden`\n- File upload, "Attach", "Upload" \u2192 `file`\n- Toggle, "Enable/Disable", notifications \u2192 `switch`\n- Numbers, amounts, quantities \u2192 `number`\n- Everything else \u2192 `text`\n\n### Step 3: Interactive refinement\n\nUse AskUserQuestion for each decision point. ONE question at a time.\n\n**3a: Steps**\n\nIf the form has 5+ fields, ask:\n\n> "This form has N fields. Should it be a single page or split into steps?\n> If steps, describe how to group them (e.g. \'Personal info, Address, Payment\')."\n\nOptions:\n- A) Single step (all fields on one page)\n- B) Multi-step (I\'ll describe the groups)\n- C) Auto-group (you decide based on field types)\n\nIf C: group by semantic similarity (personal info, address, account, payment, etc.).\n\n**3b: Conditions**\n\nIf any field logically depends on another (e.g. "Bank name" only makes sense\nwhen payment method is "bank"), ask:\n\n> "I noticed [field X] probably only shows when [field Y] = [value].\n> Should I add show conditions?"\n\nOptions:\n- A) Yes, add the conditions you suggested\n- B) No conditions, show everything always\n- C) Let me specify which fields depend on what\n\n**3c: Validation**\n\nFor each field, infer validation:\n- Fields marked "required" or with * \u2192 `required: true`\n- Email fields \u2192 pattern for email format\n- Password fields \u2192 minLength: 8\n- Phone fields \u2192 inputMode: \'tel\'\n- Number fields \u2192 inputMode: \'numeric\'\n\nAsk only if there\'s ambiguity: "Should [field] be required?"\n\n### Step 4: Generate JSON\n\nOutput the complete form definition JSON. Follow these rules:\n\n1. `id` is kebab-case derived from the title\n2. `key` for each field is camelCase\n3. Every form MUST have `submit: { label: "..." }`\n4. Use `fields` for single-step, `steps` for multi-step\n5. Only include optional properties when they add value (no empty strings, no `required: false`)\n6. Options for select/radio must have both `value` and `label`\n\nPut `"$schema": "https://formhaus.dev/schema/form-definition.json"` as the first key\nso editors validate and autocomplete the file.\n\n### Step 5: Validate\n\nIf the MCP tools are available:\n\n1. Call `validate_definition` with the definition. Fix every entry in `errors` and\n   re-run until `errors` is empty. Review `warnings` and fix the ones that are real mistakes.\n2. For multi-step definitions with conditions or routes, call `simulate_path` with answers\n   that take each branch and check that the path matches the user\'s intent.\n\n### Step 6: Present and confirm\n\nShow the generated JSON in a code block. Ask:\n\n> "Here\'s your form definition. You can paste this directly into the\n> Formhaus Figma plugin or use with FormRenderer."\n\nOptions:\n- A) Looks good, copy and done\n- B) Make changes (specify what)\n- C) Publish it and get a live endpoint\n\nIf B: apply changes and re-present\n\n### Step 7: Publish and wire into the project\n\nOnly when the user chose C, or asked for a working form, a hosted form or an endpoint.\nRequires the `publish_form` tool and a definition that passed `validate_definition`.\n\n1. Call `publish_form` with the definition. Hosted forms do not support `password`, `file`,\n   `autocomplete`, `optionsFrom` and custom field types. If the tool reports an error, fix every\n   listed path and call it again.\n2. Tell the user the `hosted_url` and `endpoint`. Without an API key the form is unclaimed\n   (7 days, 100 submissions): give them the `claim_url` from the result.\n3. Detect the project: React or Vue in `package.json`, or plain HTML. Install the matching\n   package (`@formhaus/react` or `@formhaus/vue`, plus `@formhaus/core` for `style.css`) with\n   the project\'s package manager.\n4. Add the `react_snippet` from the result where the user wants the form. It imports\n   `FormhausForm` from `@formhaus/react/cloud`. For Vue use `FormhausForm` from\n   `@formhaus/vue/cloud` with the same `id`. For plain HTML use `embed_snippet`.\n5. Publishing again with the same `form_id` ships a new version at the same endpoint, so\n   later edits to the definition do not change the project code.\n\n## Example Definitions\n\nCall `example_definitions` to list the bundled examples and fetch one by `id` when you\nneed to verify a pattern or show the user an example. They cover common field types,\nvalidation, show conditions, linear steps, and branching steps with routes.\n\n## Rules\n\n- NEVER call `publish_form` unless the user asked for a hosted form or Formhaus Cloud. If the project has its own backend, render with `FormRenderer` and submit to that backend.\n- NEVER output invalid JSON. Validate before presenting, with `validate_definition` when available.\n- NEVER invent field types not in the FieldType union.\n- NEVER use `fields` AND `steps` in the same definition. Pick one.\n- Keys must be unique within a definition (across all steps).\n- ShowCondition.field must reference an existing field key.\n- For multi-step: each step needs `id`, `title`, and `fields`.\n- Submit label should match the form\'s purpose ("Submit", "Create transfer", "Register", etc.).\n';
+var SKILL_default = '---\nname: formhaus-create-form\ndescription: |\n  Generate @formhaus/core form definitions from any input: text description,\n  CSV/table, or screenshot of a form. Interactive step/condition builder.\n  Output pastes directly into the Formhaus Figma plugin or FormRenderer.\n  Use when: "generate form", "form definition", "form JSON", "create a form",\n  "formhaus", or when user describes form fields in any format.\nallowed-tools:\n  - Read\n  - Write\n  - Glob\n  - Grep\n  - AskUserQuestion\n  - Agent\n  - mcp__plugin_formhaus_formhaus__validate_definition\n  - mcp__plugin_formhaus_formhaus__simulate_path\n  - mcp__plugin_formhaus_formhaus__capabilities\n  - mcp__plugin_formhaus_formhaus__example_definitions\n  - mcp__plugin_formhaus_formhaus__publish_form\n  - mcp__plugin_formhaus_formhaus__list_forms\n  - mcp__formhaus__validate_definition\n  - mcp__formhaus__simulate_path\n  - mcp__formhaus__capabilities\n  - mcp__formhaus__example_definitions\n  - mcp__formhaus__publish_form\n  - mcp__formhaus__list_forms\n  - Edit\n  - Bash\n---\n\n# Form Definition Generator\n\nYou generate valid `@formhaus/core` form definitions from any input.\nThe output is ready to paste into the Formhaus Figma plugin or use with FormRenderer.\nThe formhaus repo does not need to be cloned. The JSON Schema is published at\n`https://formhaus.dev/schema/form-definition.json`.\n\n## Formhaus MCP tools\n\nCheck whether the `formhaus` MCP server tools are available (`validate_definition`,\n`simulate_path`, `capabilities`, `example_definitions`, `publish_form`). The Formhaus Claude Code plugin\nstarts the server. Without the plugin, it is added with\n`claude mcp add formhaus -- npx -y @formhaus/mcp`.\n\n- `capabilities` returns the current field types, validation rules, condition operators\n  and step semantics. Prefer it over the reference below when they differ.\n- `example_definitions` lists bundled example definitions and returns one by `id`.\n- `validate_definition` checks a definition against the JSON Schema and the engine.\n- `simulate_path` walks a multi-step definition with sample answers and reports the step path.\n- `publish_form` publishes a definition to Formhaus Cloud and returns a live endpoint, a hosted page URL, an embed snippet and a React snippet.\n\nIf the tools are not available, validate by hand against the types below and tell the\nuser that `@formhaus/mcp` can check the result.\n\n## Types Reference\n\nThese are the exact TypeScript types. Your output MUST conform to them.\n\n```typescript\ninterface FormDefinition {\n  id: string;           // kebab-case identifier\n  formatVersion?: string; // "1.3" when the form uses scale, rating, option images or a matrix\n  title: string;        // human-readable form title\n  description?: string; // short intro under the title, up to 1000 characters\n  submit: FormAction;   // submit button config (required)\n  cancel?: FormAction;  // cancel button (optional)\n  fields?: FormField[]; // single-step form\n  steps?: FormStep[];   // multi-step form (use steps OR fields, not both)\n}\n\ninterface FormStep {\n  id: string;\n  title: string;\n  description?: string;\n  fields: (FormField | FormSection)[]; // may be empty for a welcome or statement screen\n  show?: ShowCondition[];    // step visible when ALL conditions true\n  showAny?: ShowCondition[]; // step visible when ANY condition true\n  routes?: StepRoute[];      // ordered forward destinations\n  next?: FormAction | false; // custom "next" or false to hide it\n  back?: FormAction | false; // custom "back" or false to hide it\n  skip?: FormAction;         // Skip button: resets the step, moves on without validation\n}\n\ninterface StepRoute {\n  to: string | null;         // later step id, or terminal without auto-submission\n  show?: ShowCondition[];\n  showAny?: ShowCondition[];\n}\n\ninterface FormField {\n  key: string;                // camelCase field identifier\n  type: FieldType;\n  label: string;\n  placeholder?: string;\n  helperText?: string;\n  defaultValue?: unknown;\n  autoAdvance?: boolean;     // explicit activation advances; built-in radio, scale and rating support it\n  show?: ShowCondition[];     // field visible when ALL conditions true\n  showAny?: ShowCondition[];  // field visible when ANY condition true\n  validation?: FieldValidation;\n  options?: FieldOption[];    // for select, multiselect, radio; anchor labels on the first, middle and last point of scale and rating\n  layout?: \'stack\' | \'inline\'; // radio/multiselect; inline only for a few short options\n  optionsFrom?: string;       // dynamic options loaded at runtime\n  optionsDependsOn?: string[];\n  accept?: string;            // for file type: "image/*", ".pdf"\n  rows?: number;              // for textarea\n  mask?: string;              // input mask\n  inputMode?: \'text\' | \'numeric\' | \'decimal\' | \'tel\' | \'email\' | \'url\' | \'search\';\n}\n\ntype FieldType =\n  | \'text\' | \'email\' | \'phone\' | \'number\' | \'password\'\n  | \'select\' | \'autocomplete\' | \'multiselect\'\n  | \'checkbox\' | \'radio\' | \'switch\'\n  | \'file\' | \'date\' | \'datetime\' | \'time\' | \'textarea\' | \'hidden\'\n  | \'scale\'    // whole number from validation.min (0 or 1, default 1) to validation.max (default 5)\n  | \'rating\';  // stars from 1 to validation.max (default 5, 3 to 10)\n\ninterface FormSection {\n  key: string;\n  type: \'section\';\n  title: string;\n  description?: string;\n  layout?: \'matrix\';          // grid: each field is a radio row with the same options\n  show?: ShowCondition[];\n  fields: FormField[];        // may be empty for a statement between questions\n}\n\ninterface ShowCondition {\n  field: string;                        // references another field\'s key\n  eq?: string | number | boolean;       // equals\n  neq?: string | number | boolean;      // not equals\n  in?: (string | number)[];             // one of\n  notIn?: (string | number)[];          // not one of\n  notEmpty?: boolean;                   // has a value\n  gt?: number; gte?: number;            // numeric comparisons, such as an NPS score\n  lt?: number; lte?: number;\n}\n\ninterface FieldValidation {\n  required?: boolean | string;  // true or custom message\n  minLength?: number;\n  minLengthMessage?: string;\n  maxLength?: number;\n  maxLengthMessage?: string;\n  min?: number;\n  minMessage?: string;\n  max?: number;\n  maxMessage?: string;\n  pattern?: string;             // regex\n  patternMessage?: string;\n  matchField?: string;          // must match another field (e.g. confirmPassword)\n  matchFieldMessage?: string;\n  validator?: string;           // custom validator name\n}\n\ninterface FieldOption {\n  value: string;   // on scale and rating anchors: the point number, such as "0" or "10"\n  label: string;\n  image?: string;  // image URL for radio and multiselect (picture choice)\n}\ninterface FormAction {\n  label: string;\n  variant?: \'primary\' | \'secondary\' | \'text\';\n  action?: string;\n  disabled?: ShowCondition[];\n}\n```\n\n## Workflow\n\n### Step 1: Detect input format\n\nLook at the user\'s input and classify:\n\n- **Text description**: "Registration form with name, email, password"\n- **CSV/table**: structured data with columns like key, type, label, required\n- **Screenshot**: user provides a path to an image file or says "look at this screenshot"\n- **Existing definition**: user references a bundled example (`example_definitions`)\n\n### Step 2: Extract fields\n\nFrom the input, extract a flat list of fields with: key, type, label, and any\nobvious validation (required, email format, etc).\n\n**Type inference rules:**\n- Email addresses \u2192 `email`\n- Phone numbers \u2192 `phone`\n- Passwords, PINs \u2192 `password`\n- "Agree to terms", "Subscribe" \u2192 `checkbox`\n- "Account type", "Gender" with 2-4 options \u2192 `radio`\n- Dropdowns, "Select..." with 5+ options \u2192 `select`\n- Searchable dropdowns, typeahead \u2192 `autocomplete`\n- Country, city, currency \u2192 `select`\n- Long text, "Description", "Notes", "Bio" \u2192 `textarea`\n- Dates, birthdays, "When" \u2192 `date`\n- Date and time together \u2192 `datetime`\n- Time of day only, "Start time", "Opening hours" \u2192 `time`\n- Tracking values the user never sees, "Source", "Campaign", "Referral code from the link" \u2192 `hidden`\n- File upload, "Attach", "Upload" \u2192 `file`\n- Toggle, "Enable/Disable", notifications \u2192 `switch`\n- Numbers, amounts, quantities \u2192 `number`\n- "How likely are you to recommend" with 0 to 10 \u2192 `scale` with `validation: { min: 0, max: 10 }` and anchors `"0": "Not at all likely"`, `"10": "Extremely likely"` (NPS)\n- "Rate", "stars", satisfaction from 1 to 5 \u2192 `rating`\n- "Strongly disagree \u2026 Strongly agree" or "1 to 7" for one statement \u2192 `scale` with start and end anchors\n- Several statements with the same agree/disagree answers \u2192 a `section` with `layout: "matrix"` and one `radio` per statement, all with the same options\n- Options shown as pictures \u2192 `radio` or `multiselect` with `image` on each option\n- An intro, welcome or "thank you for joining" screen \u2192 a step with a title, a description, `next: { label: "Start" }` and `fields: []`\n- Everything else \u2192 `text`\n\n### Step 3: Interactive refinement\n\nUse AskUserQuestion for each decision point. ONE question at a time.\n\n**3a: Steps**\n\nIf the form has 5+ fields, ask:\n\n> "This form has N fields. Should it be a single page or split into steps?\n> If steps, describe how to group them (e.g. \'Personal info, Address, Payment\')."\n\nOptions:\n- A) Single step (all fields on one page)\n- B) Multi-step (I\'ll describe the groups)\n- C) Auto-group (you decide based on field types)\n\nIf C: group by semantic similarity (personal info, address, account, payment, etc.).\n\n**3b: Conditions**\n\nIf any field logically depends on another (e.g. "Bank name" only makes sense\nwhen payment method is "bank"), ask:\n\n> "I noticed [field X] probably only shows when [field Y] = [value].\n> Should I add show conditions?"\n\nOptions:\n- A) Yes, add the conditions you suggested\n- B) No conditions, show everything always\n- C) Let me specify which fields depend on what\n\n**3c: Validation**\n\nFor each field, infer validation:\n- Fields marked "required" or with * \u2192 `required: true`\n- Email fields \u2192 pattern for email format\n- Password fields \u2192 minLength: 8\n- Phone fields \u2192 inputMode: \'tel\'\n- Number fields \u2192 inputMode: \'numeric\'\n\nAsk only if there\'s ambiguity: "Should [field] be required?"\n\n### Step 4: Generate JSON\n\nOutput the complete form definition JSON. Follow these rules:\n\n1. `id` is kebab-case derived from the title\n2. `key` for each field is camelCase\n3. Every form MUST have `submit: { label: "..." }`\n4. Use `fields` for single-step, `steps` for multi-step\n5. Only include optional properties when they add value (no empty strings, no `required: false`)\n6. Options for select/radio must have both `value` and `label`\n7. Set `"formatVersion": "1.3"` when the form has a `scale`, a `rating`, an option `image` or a matrix section. Set at least `"1.1"` when it has sections or groups\n8. Conditions on `scale` and `rating` compare numbers: `{ "field": "nps", "lte": 6 }`. A range is two conditions: `gte` and `lte`\n\nPut `"$schema": "https://formhaus.dev/schema/form-definition.json"` as the first key\nso editors validate and autocomplete the file.\n\n### Step 5: Validate\n\nIf the MCP tools are available:\n\n1. Call `validate_definition` with the definition. Fix every entry in `errors` and\n   re-run until `errors` is empty. Review `warnings` and fix the ones that are real mistakes.\n2. For multi-step definitions with conditions or routes, call `simulate_path` with answers\n   that take each branch and check that the path matches the user\'s intent.\n\n### Step 6: Present and confirm\n\nShow the generated JSON in a code block. Ask:\n\n> "Here\'s your form definition. You can paste this directly into the\n> Formhaus Figma plugin or use with FormRenderer."\n\nOptions:\n- A) Looks good, copy and done\n- B) Make changes (specify what)\n- C) Publish it and get a live endpoint\n\nIf B: apply changes and re-present\n\n### Step 7: Publish and wire into the project\n\nOnly when the user chose C, or asked for a working form, a hosted form or an endpoint.\nRequires the `publish_form` tool and a definition that passed `validate_definition`.\n\n1. Call `publish_form` with the definition. Hosted forms do not support `password`, `file`,\n   `autocomplete`, `optionsFrom` and custom field types. If the tool reports an error, fix every\n   listed path and call it again.\n2. Tell the user the `hosted_url` and `endpoint`. Without an API key the form is unclaimed\n   (7 days, 100 submissions): give them the `claim_url` from the result.\n3. Detect the project: React or Vue in `package.json`, or plain HTML. Install the matching\n   package (`@formhaus/react` or `@formhaus/vue`, plus `@formhaus/core` for `style.css`) with\n   the project\'s package manager.\n4. Add the `react_snippet` from the result where the user wants the form. It imports\n   `FormhausForm` from `@formhaus/react/cloud`. For Vue use `FormhausForm` from\n   `@formhaus/vue/cloud` with the same `id`. For plain HTML use `embed_snippet`.\n5. Publishing again with the same `form_id` ships a new version at the same endpoint, so\n   later edits to the definition do not change the project code.\n\n## Example Definitions\n\nCall `example_definitions` to list the bundled examples and fetch one by `id` when you\nneed to verify a pattern or show the user an example. They cover common field types,\nvalidation, show conditions, linear steps, and branching steps with routes.\n\n## Rules\n\n- NEVER call `publish_form` unless the user asked for a hosted form or Formhaus Cloud. If the project has its own backend, render with `FormRenderer` and submit to that backend.\n- NEVER output invalid JSON. Validate before presenting, with `validate_definition` when available.\n- NEVER invent field types not in the FieldType union.\n- NEVER use `fields` AND `steps` in the same definition. Pick one.\n- Keys must be unique within a definition (across all steps).\n- ShowCondition.field must reference an existing field key.\n- For multi-step: each step needs `id`, `title`, and `fields`.\n- Submit label should match the form\'s purpose ("Submit", "Create transfer", "Register", etc.).\n';
 
 // src/context.ts
 var SetupError = class extends Error {
@@ -21,6 +22,8 @@ var SERVER_NAME = "formhaus";
 var SERVER_PACKAGE = "@formhaus/mcp";
 var SERVER = { command: "npx", args: ["-y", SERVER_PACKAGE] };
 var GUIDE_URL = "https://formhaus.dev/guide/mcp";
+var START_URL = "https://formhaus.dev/guide/";
+var APP_URL = "https://app.formhaus.dev";
 function isOurServer(command2, args) {
   return command2 === SERVER.command && Array.isArray(args) && args.length === SERVER.args.length && args.every((arg, index) => arg === SERVER.args[index]);
 }
@@ -44,38 +47,95 @@ function refuseLinkedDirectories(ctx, root, file) {
   const parts = relative(root, dirname(file)).split(sep).filter(Boolean);
   for (let index = 1; index <= parts.length; index++) refuseSymlink(ctx, resolve(root, ...parts.slice(0, index)));
 }
-function writeText(ctx, file, text, project) {
-  const backup = `${file}.bak`;
-  const temporary = `${file}.tmp`;
+function refuseLinks(ctx, file, project) {
   if (project !== void 0) refuseLinkedDirectories(ctx, project, file);
-  for (const path of [file, backup, temporary]) refuseSymlink(ctx, path);
+  for (const path of [file, `${file}.bak`]) refuseSymlink(ctx, path);
+}
+function temporaryPath(file) {
+  return `${file}.${randomBytes(8).toString("hex")}.tmp`;
+}
+function replaceWith(temporary, file, create) {
+  try {
+    create();
+    renameSync(temporary, file);
+  } catch (error) {
+    if (error.code !== "EEXIST") rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+function writeText(ctx, file, text, project, replaceBackup = false) {
+  const backup = `${file}.bak`;
+  refuseLinks(ctx, file, project);
   if (ctx.dryRun) return;
   mkdirSync(dirname(file), { recursive: true });
-  if (existsSync(file) && !existsSync(backup)) copyFileSync(file, backup, constants.COPYFILE_EXCL);
+  if (existsSync(file) && replaceBackup) {
+    const backupTemporary = temporaryPath(backup);
+    replaceWith(backupTemporary, backup, () => copyFileSync(file, backupTemporary, constants.COPYFILE_EXCL));
+  } else if (existsSync(file) && !existsSync(backup)) copyFileSync(file, backup, constants.COPYFILE_EXCL);
   const mode = statSync(file, { throwIfNoEntry: false })?.mode;
-  rmSync(temporary, { force: true });
-  writeFileSync(temporary, text, { flag: "wx", mode: mode === void 0 ? void 0 : mode & 384 });
-  if (mode !== void 0) chmodSync(temporary, mode & 4095);
-  renameSync(temporary, file);
+  const temporary = temporaryPath(file);
+  replaceWith(temporary, file, () => {
+    writeFileSync(temporary, text, { flag: "wx", mode: mode === void 0 ? void 0 : mode & 384 });
+    if (mode !== void 0) chmodSync(temporary, mode & 4095);
+  });
 }
-function writeIfChanged(ctx, file, text, project) {
+function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function writeAsset(ctx, file, text, shipped, project) {
   const current = readText(file);
   if (current === text) return "present";
-  writeText(ctx, file, text, project);
-  return current === void 0 ? "added" : "updated";
+  refuseLinks(ctx, file, project);
+  if (current === void 0 || shipped.includes(sha256(current))) {
+    writeText(ctx, file, text, project);
+    return current === void 0 ? "added" : "updated";
+  }
+  if (!ctx.force) return "kept";
+  writeText(ctx, file, text, project, true);
+  return "replaced";
+}
+function sameDirectory(a, b) {
+  if (resolve(a) === resolve(b)) return true;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+function isProjectRoot(directory) {
+  return existsSync(join(directory, ".git")) || existsSync(join(directory, "package.json")) || isDirectory(join(directory, ".cursor"));
+}
+function isFilesystemRoot(directory) {
+  return parse(directory).root === directory;
+}
+function findProjectRoot(ctx, isRoot = isFilesystemRoot) {
+  let directory = resolve(ctx.cwd);
+  while (!sameDirectory(directory, ctx.home) && !isRoot(directory)) {
+    if (isProjectRoot(directory)) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return void 0;
+    directory = parent;
+  }
+  return void 0;
 }
 function display(ctx, path) {
-  return path.startsWith(ctx.home + sep) ? `~${path.slice(ctx.home.length)}` : path;
+  return path === ctx.home || path.startsWith(ctx.home + sep) ? `~${path.slice(ctx.home.length)}` : path;
 }
 function step(ctx, agent, item, where, apply) {
   const target = display(ctx, where);
-  const firstBackup = existsSync(where) && !existsSync(`${where}.bak`);
+  const backup = `${where}.bak`;
+  const hadBackup = existsSync(backup);
   try {
     const state = apply();
-    const backedUp = firstBackup && !ctx.dryRun && (state === "added" || state === "updated");
-    return { agent, item, where: backedUp ? `${target} (backup: ${target}.bak)` : target, state };
+    const change = { agent, item, where: target, state };
+    if (!ctx.dryRun && existsSync(backup)) {
+      change.backup = `${target}.bak`;
+      change.newBackup = !hadBackup || state === "replaced";
+    }
+    if (state === "kept") change.note = "Run npx formhaus --force to replace it and save your version as .bak.";
+    return change;
   } catch (error) {
-    return { agent, item, where: target, state: "failed", error: error instanceof Error ? error.message : String(error) };
+    return { agent, item, where: target, state: "failed", note: error instanceof Error ? error.message : String(error) };
   }
 }
 
@@ -141,6 +201,10 @@ function command(ctx, executable, args) {
 // src/claude-code.ts
 var NAME = "Claude Code";
 var PLUGIN_PREFIX = `${SERVER_NAME}@`;
+var SHIPPED_SKILLS = [
+  "e929afc9f58a267647341d962283d84749a18028e5ec2c4bd770a214c26a7c25",
+  "7288b74973a7668592f0baef836793aaf8591f3468546c87ff0c2335c8380065"
+];
 var CLAUDE_ADD_ARGS = ["mcp", "add", "--scope", "user", SERVER_NAME, "--", SERVER.command, ...SERVER.args];
 function configDir(ctx) {
   return ctx.env.CLAUDE_CONFIG_DIR || join(ctx.home, ".claude");
@@ -164,9 +228,11 @@ function hasPlugin(ctx) {
     ([id, installs]) => id.startsWith(PLUGIN_PREFIX) && installedForUser(installs) && enabled[id] === true
   );
 }
+function userConfig(ctx) {
+  return ctx.env.CLAUDE_CONFIG_DIR ? join(ctx.env.CLAUDE_CONFIG_DIR, ".claude.json") : join(ctx.home, ".claude.json");
+}
 function userServer(ctx) {
-  const file = ctx.env.CLAUDE_CONFIG_DIR ? join(ctx.env.CLAUDE_CONFIG_DIR, ".claude.json") : join(ctx.home, ".claude.json");
-  return jsonServerState(readJsonObject(ctx, file));
+  return jsonServerState(readJsonObject(ctx, userConfig(ctx)));
 }
 function projectWarning(ctx) {
   const file = join(ctx.cwd, ".mcp.json");
@@ -197,20 +263,14 @@ var claudeCode = {
     const claude = findOnPath(ctx, "claude");
     const skill = join(configDir(ctx), "skills", "formhaus-create-form", "SKILL.md");
     return [
-      step(ctx, NAME, "MCP server", `claude mcp add --scope user ${SERVER_NAME}`, () => addServer(ctx, claude)),
-      step(
-        ctx,
-        NAME,
-        "formhaus-create-form skill",
-        skill,
-        () => hasPlugin(ctx) ? "present" : writeIfChanged(ctx, skill, SKILL_default)
-      ),
+      step(ctx, NAME, "MCP server", userConfig(ctx), () => addServer(ctx, claude)),
+      step(ctx, NAME, "form skill", skill, () => hasPlugin(ctx) ? "present" : writeAsset(ctx, skill, SKILL_default, SHIPPED_SKILLS)),
       ...projectWarning(ctx)
     ];
   }
 };
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/error.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/error.js
 function getLineColFromPtr(string, ptr) {
   let lines = string.slice(0, ptr).split(/\r?\n/);
   return [lines.length, lines.pop().length + 1];
@@ -254,7 +314,7 @@ ${codeblock}`, options);
   }
 };
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/primitive.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/primitive.js
 function parseString(ctx) {
   let startPtr = ctx.p;
   let c = ctx.s.charCodeAt(ctx.p++);
@@ -355,7 +415,7 @@ function parseString(ctx) {
   TomlError.x("unfinished string", ctx, startPtr);
 }
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/date.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/date.js
 var DATE_TIME_RE = /^(\d{4}-\d{2}-\d{2})?[Tt ]?(?:(\d{2}):\d{2}(?::\d{2}(?:\.\d+)?)?)?(Z|z|[-+]\d{2}:\d{2})?$/i;
 var TomlDate = class _TomlDate extends Date {
   #hasDate = false;
@@ -470,7 +530,7 @@ var TomlDate = class _TomlDate extends Date {
   }
 };
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/extract.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/extract.js
 function isDigit(char, base = 10) {
   return base === 16 ? char > 47 && char < 58 || char > 64 && char < 71 || char > 96 && char < 103 : char > 47 && char < 48 + base;
 }
@@ -557,7 +617,9 @@ function parseNumber(ctx, startPtr, startChr, sign, endChr) {
       state = 2;
     else if ((state === 1 || state === 3) && (c === 101 || c === 69))
       state = 4;
-    else if (state === 4 && (c === 43 || c === 45)) ; else if (!isDigit(c))
+    else if (state === 4 && (c === 43 || c === 45)) {
+      state = 6;
+    } else if (!isDigit(c))
       TomlError.x(`illegal character in numeric literal`, ctx);
     else if (state > 9)
       state -= 11;
@@ -677,7 +739,7 @@ function readDate(ctx, str, type, unsafeDelim, errPtr, temporalSuffix) {
   }
 }
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/util.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/util.js
 function skipComment(ctx) {
   for (; ctx.p < ctx.s.length; ctx.p++) {
     let c = ctx.s.charCodeAt(ctx.p);
@@ -703,7 +765,7 @@ function skipVoid(ctx, banNewLines, banComments) {
   }
 }
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/struct.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/struct.js
 function parseKey(ctx, end = 61) {
   let startPtr;
   let state = 0;
@@ -820,7 +882,7 @@ function parseArray(ctx) {
   TomlError.x("unfinished array", ctx, startPtr);
 }
 
-// ../../node_modules/.pnpm/smol-toml@1.9.0/node_modules/smol-toml/dist/parse.js
+// ../../node_modules/.pnpm/smol-toml@1.9.1/node_modules/smol-toml/dist/parse.js
 function peekTable(ctx, key, table, meta, type) {
   let t = table;
   let m = meta;
@@ -887,7 +949,7 @@ function validateTablePeek(ctx, peek, ptr) {
   if (peek === null || ctx.uk === 2)
     TomlError.x(peek === null ? "trying to redefine an already defined table or value" : "document contains an unsafe property", ctx, ptr);
 }
-function parse(toml, options = {}) {
+function parse2(toml, options = {}) {
   let ctx = {
     s: toml,
     p: 0,
@@ -975,7 +1037,7 @@ function isTable(value) {
 }
 function parseToml(text) {
   try {
-    return parse(text, { integersAsBigInt: true });
+    return parse2(text, { integersAsBigInt: true });
   } catch {
     return void 0;
   }
@@ -1026,9 +1088,7 @@ function claudeDesktopDir(ctx) {
 function found(ctx, directory, bin) {
   return isDirectory(directory) || findOnPath(ctx, bin) !== void 0;
 }
-function isProject(ctx) {
-  return ctx.cwd !== ctx.home && existsSync(join(ctx.cwd, "package.json"));
-}
+var SHIPPED_RULES = ["1bb79502ba88f1d38bef0bb3f34ede713f94487643496eae94ca6be7d2c8a32c"];
 var codex = {
   name: "Codex",
   detect: (ctx) => found(ctx, codexHome(ctx), "codex"),
@@ -1043,9 +1103,12 @@ var cursor = {
   apply(ctx) {
     const file = join(ctx.home, ".cursor", "mcp.json");
     const changes = [step(ctx, "Cursor", "MCP server", file, () => addJsonServer(ctx, file))];
-    if (!isProject(ctx)) return changes;
-    const rule = join(ctx.cwd, ".cursor", "rules", "formhaus.mdc");
-    changes.push(step(ctx, "Cursor", "formhaus rule", rule, () => writeIfChanged(ctx, rule, formhaus_default, ctx.cwd)));
+    const root = findProjectRoot(ctx);
+    if (root === void 0) {
+      return [...changes, { agent: "Cursor", item: "Cursor rule", where: display(ctx, ctx.cwd), state: "skipped" }];
+    }
+    const rule = join(root, ".cursor", "rules", "formhaus.mdc");
+    changes.push(step(ctx, "Cursor", "Cursor rule", rule, () => writeAsset(ctx, rule, formhaus_default, SHIPPED_RULES, root)));
     return changes;
   }
 };
@@ -1071,62 +1134,156 @@ var MANUAL_AGENTS = [
 ];
 
 // src/run.ts
-var LABELS = {
-  added: ["added", "will add"],
-  updated: ["updated", "will update"],
-  present: ["already set up", "already set up"],
-  different: ["different server, check it", "different server, check it"],
-  failed: ["failed", "failed"]
+var WIDTH = 79;
+var INDENT = "  ";
+var DETAIL = "      ";
+var SYMBOLS = {
+  ok: ["\u2713", "32"],
+  manual: ["\u2013", "2"],
+  failed: ["\u2717", "31"],
+  warning: ["!", "33"]
 };
-function label(ctx, state) {
-  return LABELS[state][ctx.dryRun ? 1 : 0];
+function useColor(ctx) {
+  return ctx.tty === true && !ctx.env.NO_COLOR && ctx.env.TERM !== "dumb";
+}
+function paint(ctx, code, text) {
+  return useColor(ctx) ? `\x1B[${code}m${text}\x1B[0m` : text;
 }
-function printChanges(ctx, changes, print) {
-  const width = (pick) => Math.max(...changes.map((change) => pick(change).length));
-  const agentWidth = width((change) => change.agent);
-  const itemWidth = width((change) => change.item);
-  const stateWidth = width((change) => label(ctx, change.state));
-  for (const change of changes) {
-    const row = [change.agent.padEnd(agentWidth), change.item.padEnd(itemWidth), label(ctx, change.state).padEnd(stateWidth), change.where];
-    print(`  ${row.join("  ")}`);
-    if (change.error) print(`    ${change.error}`);
+function wrap(text, first, rest = first) {
+  const lines = [];
+  let line = first;
+  let empty = true;
+  for (const word of text.split(" ")) {
+    if (!empty && line.length + 1 + word.length > WIDTH) {
+      lines.push(line);
+      line = rest + word;
+    } else line += (empty ? "" : " ") + word;
+    empty = false;
+  }
+  lines.push(line);
+  return lines;
+}
+function list(names) {
+  return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+function items(changes, state) {
+  return changes.filter((change) => change.state === state).map((change) => change.item);
+}
+function summary(ctx, changes) {
+  const will = (done, planned) => ctx.dryRun ? planned : done;
+  const parts = [];
+  const add = (state, text) => {
+    const names = items(changes, state);
+    if (names.length > 0) parts.push(text(list(names)));
+  };
+  add("failed", (names) => `${names} failed`);
+  for (const change of changes.filter((change2) => change2.state === "different")) {
+    const place = change.item === "MCP server" ? "is configured" : `in ${change.where}`;
+    parts.push(`another ${SERVER_NAME} server ${place}, check it`);
+  }
+  add("added", (names) => `${will("added", "will add")} ${names}`);
+  add("updated", (names) => `${will("updated", "will update")} ${names}`);
+  add("replaced", (names) => `${will("replaced", "will replace")} ${names}`);
+  add("kept", (names) => `${names} ${names.includes(" and ") ? "have" : "has"} your edits, ${will("kept", "will keep")}`);
+  const active = changes.filter((change) => change.state !== "skipped");
+  if (active.length > 0 && active.every((change) => change.state === "present")) parts.push("already set up");
+  else add("present", (names) => `${names} already set up`);
+  if (items(changes, "skipped").length > 0) parts.push("run in a project to add the Cursor rule");
+  return parts.join(" \xB7 ");
+}
+function details(change) {
+  if (change.state === "skipped") return [`no project found in ${change.where}`];
+  return change.backup ? [change.where, `backup: ${change.backup}`] : [change.where];
+}
+function agentRow(ctx, name, changes) {
+  const has = (state) => changes.some((change) => change.state === state);
+  return {
+    mark: has("failed") ? "failed" : has("different") ? "warning" : "ok",
+    name,
+    summary: summary(ctx, changes),
+    notes: changes.flatMap((change) => change.note ? [change.note] : []),
+    details: changes.flatMap(details)
+  };
+}
+var MANUAL_STEP = `Add a stdio MCP server named "${SERVER_NAME}" with command "${SERVER.command}" and args ${JSON.stringify(SERVER.args)}.`;
+function manualRow(name) {
+  return { mark: "manual", name, summary: `add it by hand: ${GUIDE_URL}`, notes: [], details: [MANUAL_STEP] };
+}
+function printRows(ctx, rows, print) {
+  const width = Math.max(...rows.map((row) => row.name.length)) + 2;
+  for (const row of rows) {
+    const [symbol, code] = SYMBOLS[row.mark];
+    const lead = `${INDENT}${symbol} ${row.name.padEnd(width)}`;
+    const [first, ...rest] = wrap(row.summary, lead, " ".repeat(lead.length));
+    print(first.replace(symbol, paint(ctx, code, symbol)));
+    for (const line of rest) print(line);
+    for (const note of row.notes) for (const line of wrap(note, DETAIL)) print(line);
+    if (ctx.verbose) for (const detail of row.details) for (const line of wrap(detail, DETAIL)) print(line);
   }
 }
-function printManual(names, print) {
-  print(names.length > 0 ? `Set up by hand: ${names.join(", ")}` : "Set up any other MCP client by hand:");
-  print(`  Add a stdio MCP server named "${SERVER_NAME}" with command "${SERVER.command}" and args ${JSON.stringify(SERVER.args)}.`);
-  print(`  Guide: ${GUIDE_URL}`);
+function printNext(ctx, print) {
+  print("");
+  print(paint(ctx, "1", "Next"));
+  print(`${INDENT}1. Restart your agents.`);
+  print(`${INDENT}2. Ask one: "Build a contact form with Formhaus: name, email, message."`);
+  print(`${INDENT}3. Show it on your site: npm i @formhaus/core @formhaus/react`);
+  print(`${INDENT}   For Vue use @formhaus/vue. Guide: ${START_URL}`);
+  print(`${INDENT}   No site? Publish it and collect responses at ${APP_URL}`);
+}
+function printNoAgents(ctx, manual, print) {
+  print("No supported coding agent found.");
+  print("Formhaus sets up Claude Code, Codex, Cursor and Claude Desktop.");
+  if (manual.length > 0) {
+    print("");
+    printRows(ctx, manual.map(manualRow), print);
+  }
+  print("");
+  print("Set up any MCP client by hand:");
+  for (const line of wrap(MANUAL_STEP, INDENT)) print(line);
+  print(`${INDENT}Guide: ${GUIDE_URL}`);
+  return 0;
 }
 function setup(ctx, print) {
   const agents = AGENTS.filter((agent) => agent.detect(ctx));
   const manual = MANUAL_AGENTS.filter((agent) => agent.detect(ctx)).map((agent) => agent.name);
   if (ctx.dryRun) print("Dry run: nothing is written.");
-  if (agents.length === 0) {
-    print("No supported coding agent found. Formhaus sets up Claude Code, Codex, Cursor and Claude Desktop.");
-    printManual(manual, print);
-    return 0;
-  }
-  print(`Found ${agents.map((agent) => agent.name).join(", ")}.`);
-  const changes = agents.flatMap((agent) => agent.apply(ctx));
+  if (agents.length === 0) return printNoAgents(ctx, manual, print);
+  const applied = agents.map((agent) => ({ name: agent.name, changes: agent.apply(ctx) }));
+  const changes = applied.flatMap((agent) => agent.changes);
+  const rows = applied.map((agent) => agentRow(ctx, agent.name, agent.changes));
+  const ready = rows.filter((row) => row.mark === "ok").map((row) => row.name);
+  const failed = rows.some((row) => row.mark === "failed");
+  const different = rows.some((row) => row.mark === "warning");
+  const changed = changes.some((change) => change.state === "added" || change.state === "updated" || change.state === "replaced");
+  const names = list(applied.map((agent) => agent.name));
+  if (ctx.dryRun && changed) print(`Formhaus will set up ${names}.`);
+  else if (ready.length === 0) print(`Formhaus could not finish setup in ${names}.`);
+  else print(`Formhaus is ${changed ? "ready" : "already set up"} in ${list(ready)}.`);
   print("");
-  printChanges(ctx, changes, print);
-  if (manual.length > 0) {
+  printRows(ctx, [...rows, ...manual.map(manualRow)], print);
+  if (different) {
     print("");
-    printManual(manual, print);
+    const warning = `A "${SERVER_NAME}" server with another command is configured where marked. Formhaus left it unchanged. Check that you trust it.`;
+    for (const line of wrap(warning, "")) print(line);
   }
-  const failed = changes.some((change) => change.state === "failed");
-  const changed = changes.some((change) => change.state === "added" || change.state === "updated");
-  print("");
-  const different = changes.some((change) => change.state === "different");
-  if (different) {
-    print(
-      `A "${SERVER_NAME}" server with another command is configured where marked. Formhaus left it unchanged. Check that you trust it.`
-    );
+  if (failed) {
+    print("");
+    print("Fix the errors above and run npx formhaus again.");
+  }
+  if (ctx.dryRun) {
+    print("");
+    print("Run without --dry-run to apply.");
+    return failed ? 1 : 0;
+  }
+  if (ready.length > 0) printNext(ctx, print);
+  const footer = [
+    changes.some((change) => change.newBackup) ? "Config backups were saved as .bak." : "",
+    ctx.verbose ? "" : "See every file: npx formhaus --verbose"
+  ].filter(Boolean);
+  if (footer.length > 0) {
+    print("");
+    print(footer.join(" "));
   }
-  if (failed) print("Some steps failed. Fix the errors above and run formhaus again.");
-  else if (ctx.dryRun) print("Run without --dry-run to apply.");
-  else if (changed) print("Done. Restart your agents to load the Formhaus MCP server.");
-  else if (!different) print("Everything is already set up.");
   return failed ? 1 : 0;
 }
 
@@ -1136,16 +1293,21 @@ var HELP = `Usage: npx formhaus [setup] [options]
 Adds the Formhaus MCP server (npx -y @formhaus/mcp) to the coding agents
 installed on this machine: Claude Code, Codex, Cursor and Claude Desktop.
 Installs the formhaus-create-form skill in Claude Code and, inside a project,
-the Formhaus rule in .cursor/rules. Running it again changes nothing.
+the Formhaus rule in .cursor/rules at the project root. Running it again
+changes nothing. Your edits to the skill and the rule are kept.
 
 Options:
   --dry-run      Show the planned changes and write nothing
+  --force        Replace your edited skill and rule, saving them as .bak
+  --verbose      List every file it checks or changes, and the backups
   -h, --help     Show this help
-  -v, --version  Show the version`;
+  -v, --version  Show the version
+
+Guide: https://formhaus.dev/guide/mcp`;
 function main(argv, ctx, print, printError) {
   let parsed;
   try {
-    parsed = parse2(argv);
+    parsed = parse3(argv);
   } catch (error) {
     printError(`${error instanceof Error ? error.message : String(error)}
 Run npx formhaus --help for usage.`);
@@ -1161,14 +1323,16 @@ Run npx formhaus --help for usage.`);
 Run npx formhaus --help for usage.`);
     return 1;
   }
-  return setup({ ...ctx, dryRun: values["dry-run"] === true }, print);
+  return setup({ ...ctx, dryRun: values["dry-run"] === true, force: values.force === true, verbose: values.verbose === true }, print);
 }
-function parse2(argv) {
+function parse3(argv) {
   return parseArgs({
     args: argv,
     allowPositionals: true,
     options: {
       "dry-run": { type: "boolean" },
+      force: { type: "boolean" },
+      verbose: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" }
     }
@@ -1178,7 +1342,7 @@ function parse2(argv) {
 // src/cli.ts
 process.exitCode = main(
   process.argv.slice(2),
-  { home: homedir(), cwd: process.cwd(), env: process.env, platform: process.platform },
+  { home: homedir(), cwd: process.cwd(), env: process.env, platform: process.platform, tty: process.stdout.isTTY === true },
   (line) => console.log(line),
   (line) => console.error(line)
 );

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "formhaus",
-  "version": "0.14.2",
+  "version": "0.19.0",
   "description": "Set up the Formhaus MCP server and agent instructions in Claude Code, Codex, Cursor and Claude Desktop with one command.",
   "type": "module",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "bin": {
     "formhaus": "./dist/cli.js"
@@ -14,19 +14,19 @@
   ],
   "devDependencies": {
     "@types/node": "^20",
-    "smol-toml": "1.9.0",
+    "smol-toml": "1.9.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
-    "vitest": "^4.1.3"
+    "vitest": "^5.0.3"
   },
   "license": "MIT",
   "homepage": "https://formhaus.dev/guide/mcp.html",
   "bugs": {
-    "url": "https://github.com/ignsm/formhaus/issues"
+    "url": "https://github.com/formhaus-dev/formhaus/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ignsm/formhaus.git",
+    "url": "git+https://github.com/formhaus-dev/formhaus.git",
     "directory": "packages/formhaus"
   },
   "keywords": [