generatesaas 3.7.0 → 3.8.0

package/dist/skill/content/generatesaas-update/SKILL.md

@@ -1,56 +1,44 @@
 ---
 name: update
-description: Update a GenerateSaaS project to the latest boilerplate version. Use this whenever the user asks to "update my GenerateSaaS project", "update auto", update their GenerateSaaS boilerplate/template, or pull the latest GenerateSaaS changes. Fetches and stages the new version, surfaces newly available options, classifies files, analyzes dependencies, and applies changes while preserving user customizations - the user controls every decision. Saying "auto" runs the whole update unattended, stopping only for risky or uncertain decisions.
+description: Update a GenerateSaaS project to the latest boilerplate version. Use this whenever the user asks to "update my GenerateSaaS project", update their GenerateSaaS boilerplate/template, or pull the latest GenerateSaaS changes. Fetches and stages the new version, surfaces newly available options, classifies files, and merges every upstream change into the user's customizations - stopping only when a change is risky, uncertain, or alters what the app does or how it looks.
 ---
 
 # GenerateSaaS Update
 
 Update your project to the latest GenerateSaaS boilerplate version while preserving all your customizations.
 
+## Intent
+
+The owner wants **every change from the new version**. A customization the user made is **kept and merged with the upstream change in the same file**. The only reason to hold an upstream change back is a conflict with a customization you cannot resolve with confidence, or one of the [mandatory stops](#mandatory-stops).
+
+Run the whole update **unattended** by default - fetch, stage, classify, merge, validate, and complete - without asking the user to pick a mode or confirm each step. Stop only at a mandatory stop, and only there.
+
 ## Core Principles
 
-1. **User decides everything** - Present clear information and options. Never make decisions that affect user code without explicit approval. Every meaningful change requires the user's input.
-2. **Never break user code** - If an upstream change conflicts with user modifications, present the situation and let the user choose. When in doubt, keep the user's version and explain what was skipped.
-3. **Full transparency** - For every change, explain: what changed upstream, why it changed, and how it affects the user's code. The user should always know exactly what is happening.
-4. **Track everything** - Every change is tracked in a checklist. Mark items as completed, skipped, or failed with clear reasons.
+1. **Take every upstream change** - bring the new version in fully and merge it with the user's customizations in the same file. Never silently drop an upstream change.
+2. **Never break user code** - when an upstream change conflicts with a customization you cannot merge with confidence, stop and ask. Keep the user's version if they choose, and record what was skipped.
+3. **Full transparency** - the final report says what was auto-applied, what was merged, what was held and why, and what the user must still do (migrations, env).
+4. **Track everything** - every change is tracked in the plan file: completed, merged, skipped, or failed, with a reason.
 
 ## Workflow Overview
 
 ```
 Step 0: Pre-flight safety checks
 Step 1: Fetch + stage + prepare update data (you run the CLI, then the script)
-Step 2: Present changelog to user
+Step 2: Summarize the changelog
 Step 2.5: Review newly available options - adopt or keep default (re-stage if adopted)
 Step 3: Classify files (script)
 Step 4: Analyze dependencies
-Step 5: Present update plan - user chooses interaction mode
+Step 5: Write the plan, then apply
 Step 6: Apply safe auto-updates (script)
-Step 7: Review modified files with user - one by one
+Step 7: Merge modified files - stopping only at a mandatory stop
 Step 8: Post-update validation
 Step 9: Complete update (script)
 ```
 
-**You own the whole flow.** When the user says "update my GenerateSaaS project," do
-everything end-to-end - including fetching and staging the new version (Step 1).
-The user does not run any CLI command themselves.
-
-**Automatic mode.** If the user's request includes the word "auto" (e.g. "update auto",
-"update my GenerateSaaS project, auto"), or `staging.json` has `"mode": "auto"` (set by
-`generatesaas update auto`), run the entire update **unattended** in Automatic mode: skip
-the Step 5 mode prompt and proceed start to finish, making the best decisions to bring in
-upstream changes while preserving the user's customizations. Automatic mode still **stops to
-ask** whenever a decision is genuinely risky or you are not confident - and it always runs
-the Step 2.5 new-options review (surfacing a new feature is never a decision to assume). The
-exact always-ask triggers are listed in Step 5 and "When to Always Ask".
-
-**What the staged update contains (important):** `generatesaas update` re-shapes the
-new version's template into THIS project's exact configuration before staging - same
-frontend, payment provider, database, feature flags, etc. So everything in
-`.generatesaas/staging/` and the `.generatesaas/template/` baseline is buyer-shaped:
-you will never see another framework's files, a provider the project doesn't use, the
-boilerplate's internal tooling, or dev-only secrets. Every diff you surface already
-applies to this project. The 3-way merge baseline (`.generatesaas/template/`) is a
-faithful pristine copy of what this project started from - trust it.
+**You own the whole flow.** When the user says "update my GenerateSaaS project," do everything end-to-end - including fetching and staging the new version (Step 1). The user does not run any CLI command themselves.
+
+**What the staged update contains (important):** `generatesaas update` re-shapes the new version's template into THIS project's exact configuration before staging - same frontend, payment provider, database, feature flags, etc. So everything in `.generatesaas/staging/` and the `.generatesaas/template/` baseline is buyer-shaped: you will never see another framework's files, a provider the project doesn't use, the boilerplate's internal tooling, or dev-only secrets. Every diff you surface already applies to this project. The 3-way merge baseline (`.generatesaas/template/`) is a faithful pristine copy of what this project started from - trust it.
 
 ---
 
@@ -84,29 +72,25 @@ If starting fresh, delete the old plan file. Note: files that were auto-applied
 
 ### Step 1: Fetch, Stage, and Prepare Update Data
 
-**1a. Stage the new version yourself.** Unless a staged update already exists
-(`.generatesaas/staging.json` present), run the CLI to fetch the latest version and
-stage it - re-shaped for this project's exact configuration:
+**1a. Stage the new version yourself.** Unless a staged update already exists (`.generatesaas/staging.json` present), run the CLI to fetch the latest version and stage it - re-shaped for this project's exact configuration:
 
 ```bash
 npx generatesaas@latest update
 ```
 
-This resolves the saved API key from `~/.generatesaas` (written at init), so it runs
-non-interactively - it never prompts you for a key. It refreshes the skill files,
-downloads the new version, shapes it into this project's configuration, and writes
-`.generatesaas/staging/` + `staging.json`. If it reports "Already on the latest
-version," there is nothing to update - tell the user and stop. If it fails because the
-API key is missing or rejected, ask the user to run `generatesaas auth` (which sets the
-key once and saves it), then re-run the update. For a network error, ask them to retry.
+This resolves the saved API key from `~/.generatesaas` (written at init), so it runs non-interactively - it never prompts you for a key. It refreshes the skill files, downloads the new version, shapes it into this project's configuration, and writes `.generatesaas/staging/` + `staging.json`. If it reports "Already on the latest version," there is nothing to update - tell the user and stop. If it fails because the API key is missing or rejected, ask the user to run `generatesaas auth` (which sets the key once and saves it), then re-run the update. For a network error, ask them to retry.
+
+**If `update` exits asking a question.** A few decisions are the buyer's alone (a retired desktop-AI shape, a retired option whose new default spends money or profiles end users). Because you run the CLI without a terminal, it cannot prompt you: it prints the question with a **stable id** and its **allowed choices**, then exits non-zero. Do not guess. Relay the question and its choices to the user, collect their answer, and re-run with the choice appended:
+
+```bash
+npx generatesaas@latest update --answer <id>=<choice>
+```
+
+`--answer` is repeatable - pass one per question if the CLI asks more than one. An unknown id or choice is rejected with the valid values, so read the error and correct the flag.
 
-> Note: this command also rewrites the skill scripts to their latest version. That is
-> expected - the scripts you run in the following steps are the freshly-installed ones.
+> Note: this command also rewrites the skill scripts to their latest version. That is expected - the scripts you run in the following steps are the freshly-installed ones.
 
-**Re-read this SKILL.md now**, from `__SKILL_ROOT__/generatesaas-update/SKILL.md`. The command
-just overwrote it along with the scripts, so the copy in your context is the PREVIOUS release's
-instructions while every script you are about to run is the new one. Follow the file on disk
-wherever the two disagree.
+**Re-read this SKILL.md now**, from `__SKILL_ROOT__/generatesaas-update/SKILL.md`. The command just overwrote it along with the scripts, so the copy in your context is the PREVIOUS release's instructions while every script you are about to run is the new one. Follow the file on disk wherever the two disagree.
 
 **1b. Prepare the diff/classification data:**
 
@@ -116,16 +100,10 @@ node __SKILL_ROOT__/generatesaas-update/scripts/prepare-update.js
 
 Creates:
 - `references/changelog.md` - what changed and why
-- `references/diffs/<path>.diff` - one unified diff per changed file, named by the
-  file's project-relative path with `.diff` appended (e.g.
-  `references/diffs/packages/config/src/index.ts.diff`). Diffs cover `modified` +
-  `added` files; `unmodified`, `deleted`, and `removed` files have none.
-- `references/update-manifest.json` - lists of added, modified, and removed files,
-  plus `renamed` (upstream renames detected by identical content: `[{from, to}]`)
-  and `sensitive` (database schema, `packages/database/drizzle/`, and
-  `.env.example` changes that carry follow-up work: migrations, new env vars)
+- `references/diffs/<path>.diff` - one unified diff per changed file, named by the file's project-relative path with `.diff` appended (e.g. `references/diffs/packages/config/src/index.ts.diff`). Diffs cover `modified` + `added` files; `unmodified`, `deleted`, and `removed` files have none.
+- `references/update-manifest.json` - lists of added, modified, and removed files, plus `renamed` (upstream renames detected by identical content: `[{from, to}]`) and `sensitive` (database schema, `packages/database/drizzle/`, and `.env.example` changes that carry follow-up work: migrations, new env vars)
 
-### Step 2: Present Changelog
+### Step 2: Summarize the Changelog
 
 Read `references/changelog.md`. When the update spans multiple releases, it contains one `# vX.Y.Z` section per release, oldest first - read ALL of them, not just the last; a breaking change can sit in any intermediate release. A `[BREAKING]` marker on a section header is authoritative (it comes from the version index: a major bump or release notes flagged BREAKING) - always call those releases out explicitly.
 
@@ -136,7 +114,7 @@ Each release's notes may be one of two shapes:
 
 Also read `sensitive` in `references/update-manifest.json`: database schema changes mean a migration is likely required, anything under `packages/database/drizzle/` means upstream migrations that must be regenerated into the project's own history before they will run (see [Database](#database-schema-migrations)), and `.env.example` changes mean new or changed environment variables. Mention all three in the summary and again in the final post-update steps.
 
-Present a clear, organized summary:
+Present a clear, organized summary (this is a summary, not a gate - continue straight to the next step):
 
 > ## What's New in v{targetVersion}
 >
@@ -147,19 +125,11 @@ Present a clear, organized summary:
 
 **Be honest about uncertainty.** Never present an inferred "Breaking changes: None" or "Migration steps: None" as if it were authoritative when the changelog is raw PR titles - say it's not specified and that you'll watch for schema/config/env changes during the file review. A silently-missed migration (e.g. a new DB column) is the worst failure mode.
 
-Then ask: *"Ready to proceed with the file analysis?"*
-
-Wait for the user to confirm before continuing.
-
 ### Step 2.5: Review Newly Available Options
 
-The boilerplate adds features over time. When this project predates one, `generatesaas update`
-records it in `staging.json` under `newOptions` (and has already default-filled the manifest so
-it stays complete). Read `newOptions` from `.generatesaas/staging.json`. **If it is absent or
-empty, skip this step entirely.**
+The boilerplate adds features over time. When this project predates one, `generatesaas update` records it in `staging.json` under `newOptions` (and has already default-filled the manifest so it stays complete). Read `newOptions` from `.generatesaas/staging.json`. **If it is absent or empty, skip this step entirely.**
 
-Otherwise, present each option so the user can decide whether to adopt it. Each entry has
-`{ key, label, hint, default, impact, choices?, requiresLabel? }`. For each one:
+Otherwise, present each option so the user can decide whether to adopt it. Adopting a new feature is a [mandatory stop](#mandatory-stops) - surfacing it is never a decision to assume. Each entry has `{ key, label, hint, default, impact, choices?, requiresLabel? }`. For each one:
 
 ```
 ### New since your version: {label}
@@ -177,9 +147,7 @@ it is a large surface you didn't originally choose" or "Safe to adopt - it is pu
 > 2. **Adopt it** - turn this feature on
 ```
 
-**An entry with `choices` is not a yes/no.** It takes one of several values, so the two-way block
-above cannot express it - offer the values as a numbered pick list instead, one line per choice,
-with the entry's `default` marked as the current behavior:
+**An entry with `choices` is not a yes/no.** It takes one of several values, so the two-way block above cannot express it - offer the values as a numbered pick list instead, one line per choice, with the entry's `default` marked as the current behavior:
 
 ```
 **Default:** `{default}` (your project's current behavior is unchanged).
@@ -191,34 +159,19 @@ with the entry's `default` marked as the current behavior:
 > 3. **`{choices[2]}`** ...one line per choice, however many there are
 ```
 
-**Ask the user about every new option, in every mode - including Automatic.** Surfacing a new
-feature is exactly the kind of decision the update must never assume. Give your recommendation,
-but the user decides.
+Give your recommendation, but the user decides.
 
 **Applying the decisions:**
 
-1. For each option the user **adopts**, write the value they picked into
-   `.generatesaas/manifest.json` under the entry's `key`. For an option with no `choices` that value
-   is `true` (e.g. set `"desktop": true`); for one with `choices` it is the choice they named,
-   verbatim (e.g. set `"errorTracking": "sentry"`). Never write `true` for an option that has
-   `choices` - the CLI refuses any value outside them and stages nothing at all. The manifest is the
-   single shaping input.
-2. **If the user adopted at least one option, re-stage once** so re-shaping produces the
-   feature's files. Re-run the CLI (append `auto` if you are in Automatic mode, so the staged
-   metadata keeps the unattended signal):
+1. For each option the user **adopts**, write the value they picked into `.generatesaas/manifest.json` under the entry's `key`. For an option with no `choices` that value is `true` (e.g. set `"desktop": true`); for one with `choices` it is the choice they named, verbatim (e.g. set `"errorTracking": "sentry"`). Never write `true` for an option that has `choices` - the CLI refuses any value outside them and stages nothing at all. The manifest is the single shaping input.
+2. **If the user adopted at least one option, re-stage once** so re-shaping produces the feature's files:
 
    ```bash
    npx generatesaas@latest update
    ```
 
-   Because the manifest now carries the adopted flags, the new `.generatesaas/staging/` includes
-   the feature - config flags and whole new trees alike - with no hand-editing. This is why
-   adoption is handled the same way for `config` and `structural` options: both are applied by
-   re-shaping, never by mimicking the generator. The adopted keys are now present in the
-   manifest, so they will not re-appear in `newOptions`.
-3. Re-read `staging.json`, then continue to Step 3. Classification runs on the final staging, so
-   the adopted feature's files are classified as `new` and created in Step 6. Nothing is applied
-   before this point, so a re-stage never leaves a half-applied tree.
+   Because the manifest now carries the adopted flags, the new `.generatesaas/staging/` includes the feature - config flags and whole new trees alike - with no hand-editing. This is why adoption is handled the same way for `config` and `structural` options: both are applied by re-shaping, never by mimicking the generator. The adopted keys are now present in the manifest, so they will not re-appear in `newOptions`.
+3. Re-read `staging.json`, then continue to Step 3. Classification runs on the final staging, so the adopted feature's files are classified as `new` and created in Step 6. Nothing is applied before this point, so a re-stage never leaves a half-applied tree.
 4. If the user adopted nothing, continue to Step 3 directly.
 
 ### Step 3: Classify Files
@@ -230,11 +183,11 @@ node __SKILL_ROOT__/generatesaas-update/scripts/classify-files.js
 Read `references/classification.json`. It contains:
 
 - **unmodified** - file matches the original template, safe to replace
-- **modified** - user has customized this file, needs careful review
+- **modified** - user has customized this file, needs a merge
 - **deleted** - user deleted this file, skip update for it
 - **new** - file doesn't exist locally and its directory tree is genuinely new upstream, safe to create
-- **newInDeletedTree** - file is new upstream BUT lives inside a directory tree the user intentionally deleted (the tree existed in the baseline and is now gone on disk). **Never auto-create these.** Ask the user whether to bring the tree back (see "For New Files In Deleted Trees" in Step 7).
-- **removed** - file was removed upstream, user decides whether to delete
+- **newInDeletedTree** - file is new upstream BUT lives inside a directory tree the user intentionally deleted (the tree existed in the baseline and is now gone on disk). **Never auto-create these** (a [mandatory stop](#mandatory-stops)). Ask the user whether to bring the tree back (see "For New Files In Deleted Trees" in Step 7).
+- **removed** - file was removed upstream, you decide whether to delete (see Step 7)
 - **crossDependencies** - import relationships between categories (if detected)
 
 ### Step 4: Analyze Dependencies
@@ -247,7 +200,7 @@ This step prevents breaking the user's code through indirect effects.
    - `newImportsModified` - new files that import from modified files
 
 2. **For each cross-dependency**, read the relevant diff at `references/diffs/<path>.diff`. Handle all three directions the classifier emits:
-   - **`modifiedImportsUnmodified`** - a modified file imports from an auto-apply (unmodified) file. If the auto-apply file's diff changes **exports, function signatures, types, or interfaces** that the modified file uses → promote it from `unmodified` to `modified` (it needs user review alongside its dependent, so the merge accounts for the new API).
+   - **`modifiedImportsUnmodified`** - a modified file imports from an auto-apply (unmodified) file. If the auto-apply file's diff changes **exports, function signatures, types, or interfaces** that the modified file uses → promote it from `unmodified` to `modified` (it needs a merge alongside its dependent, so the merge accounts for the new API).
    - **`unmodifiedImportsModified`** - an auto-apply file imports from a modified file. After the modified file is handled in Step 7, re-check this auto-apply file: if the user kept their version of the modified file but the auto-apply file's new version expects the upstream API, the auto-apply file may not be compatible. Flag it and revisit in the Step 7 cascade-awareness check.
    - **`newImportsModified`** - a new file imports from a modified file. The new file will be auto-created in Step 6. After the modified file is handled, verify the new file's imports resolve against whatever version of the modified file the user ended up with (their merge, their kept version, or upstream). If the new file expects the upstream API but the user kept their version, surface it.
 
@@ -255,11 +208,9 @@ This step prevents breaking the user's code through indirect effects.
 
 4. If there are no cross-dependencies or all cross-dependencies are safe (no API changes), no reclassification is needed.
 
-### Step 5: Present Update Plan and Choose Mode
-
-Generate the plan file at `.generatesaas/updates/update-{currentVersion}-to-{targetVersion}.md`.
+### Step 5: Write the Plan, Then Apply
 
-Present the plan organized by category:
+Generate the plan file at `.generatesaas/updates/update-{currentVersion}-to-{targetVersion}.md`:
 
 ```markdown
 # Update: {currentVersion} → {targetVersion}
@@ -277,8 +228,8 @@ These files haven't been customized and will be updated automatically:
 New in this version:
 - [ ] `path/to/new-file.ts` - {what this file does}
 
-## Files Needing Review ({count} files)
-These files have your customizations. Each one will be presented for your decision:
+## Files Needing a Merge ({count} files)
+These files have your customizations. Each is merged with the upstream change:
 - [ ] `path/to/modified.ts` - Risk: {Low/Medium/High} - {what changed}
 
 ## Removed Upstream ({count} files)
@@ -289,119 +240,68 @@ Removed in the new version - you decide whether to delete:
 {Empty - items move here during execution with reasons}
 ```
 
-**If Automatic mode was triggered** (the request contained "auto", or `staging.json.mode === "auto"`),
-**skip this prompt** - do not ask the user to choose a mode. Use Automatic mode (described below)
-and proceed. Note in the plan that Automatic mode was selected.
+Then show the user a **short plan** and continue - no mode question, no proceed gate:
 
-Otherwise, ask the user to choose their interaction level:
-
-> **How would you like to handle this update?**
+> **Update plan: v{currentVersion} → v{targetVersion}**
+>
+> - {N} safe files auto-applied, {N} new files created
+> - {N} customized files merged with the upstream change
+> - {N} removed upstream, {N} needing your decision
 >
-> 1. **Recommended** - Auto-apply safe files, then I'll walk you through each modified file with my recommendation. You approve or adjust each one.
-> 2. **Careful** - I'll present every single change for your approval, including auto-updates. Nothing happens without your explicit OK.
-> 3. **Quick** - Auto-apply safe files, auto-apply my recommended merges for low-risk files, and only ask you about medium/high-risk changes.
-> 4. **Automatic** - Run the whole update unattended: auto-apply safe files and auto-merge low- and medium-risk files I'm confident about, only stopping to ask when a decision is genuinely risky or I'm unsure. (This is what `update auto` selects.)
-
-**Wait for the user's choice.** Default to **Recommended** if they just say "proceed" or similar.
-
-#### Automatic mode behavior
-
-In Automatic mode, run the entire flow without prompting **except** at the mandatory stops below:
-
-- **Auto-apply** safe (`unmodified`) and genuinely-`new` files, same as Recommended.
-- **Auto-merge Low AND Medium risk** modified files when you are confident the merge preserves
-  the user's customizations (this is the difference from Quick, which stops at Low). Report each
-  merge you apply.
-- **Always stop and ask** - even in Automatic mode - for:
-  - High-risk or structurally conflicting files, and files the user heavily rewrote (>30% diverged).
-  - Database schema changes (never auto-merge schema).
-  - `.env.example` changes that imply a decision (new required variables).
-  - Removed-upstream files that other project code imports (run the import search first).
-  - Renames where the user customized the old path (porting customizations is a judgment call).
-  - **Any merge you are not confident preserves the user's intent.** When unsure, ask. It is
-    always better to interrupt than to assume.
-- **Removed files:** auto-delete only when the user never modified the file AND no importers are
-  found; otherwise ask.
-- **New files in deleted trees (`newInDeletedTree`):** keep them deleted (never resurrect a tree
-  the user removed); note it in the summary, no prompt needed.
-- **Validation (Step 8):** run the FULL ladder - lint, type check, tests, dependency
-  parity, the auth probe when auth changed, and the e2e gate; if the update introduced
-  breakage you can fix with confidence, fix it and re-verify; if not, stop and ask.
-  Unattended never means ungated: the e2e rung is still required.
-
-The Step 2.5 new-options review still runs and still asks per option - Automatic mode never
-auto-adopts a new feature.
+> **I'll stop to ask you about:** {list the mandatory stops you expect for THIS update - e.g. a schema change, a new required env var, {N} new options, a removed file still imported, a merge that changes a route or a screen. Say "none expected" if you anticipate none.}
 
-### Step 6: Apply Safe Auto-Updates
+Then proceed to Step 6.
 
-Based on the user's chosen mode:
+### Step 6: Apply Safe Auto-Updates
 
-**Recommended / Quick / Automatic mode:**
+Preview first (optional), then apply:
 
-Preview first (especially useful in Careful mode or when unsure), then apply:
 ```bash
 node __SKILL_ROOT__/generatesaas-update/scripts/apply-auto.js --dry-run   # lists every file it would update/create, changes nothing
 node __SKILL_ROOT__/generatesaas-update/scripts/apply-auto.js
 ```
+
 `apply-auto.js` copies only `unmodified` (safe replace) + `new` (any upstream-added file whose tree the buyer has not deleted). It will **never** touch `newInDeletedTree` files, and it aborts without writing anything if any source is missing from staging (no half-applied tree). Report what was applied. Mark all auto-update and new file items as `[x]` in the plan - **except any file the script reports as held back**, which was never applied and moves to **Skipped** with the regenerate reason. Marking a held-back migration `[x]` records a table that does not exist as delivered, in the one artifact that outlives the session.
 
 It also holds back everything under `packages/database/drizzle/` and lists what it skipped. Those are NOT pending work you can copy in afterwards - migrations must be regenerated into the project's own history or they never run. See [Database](#database-schema-migrations).
 
-**Careful mode:**
-Present the list of safe auto-updates and new files to the user:
-> These {N} files haven't been customized and can be safely replaced with the new version. {N} new files will be created. Want me to apply all of these, or would you like to review any specific ones first?
-
-If the user wants to review specific files, show them the diff for each requested file. Apply only after approval. Do not count held-back migrations in either number - they are not being created, and presenting them as applied is the same error as marking them `[x]`.
+### Step 7: Merge Modified Files
 
-### Step 7: Review Modified Files
-
-This is the most important step. Work through each file in the `modified` category.
+This is the most important step. Work through each file in the `modified` category. Merge the upstream change into the user's file, preserving their customizations - and stop to ask only when a [mandatory stop](#mandatory-stops) applies.
 
 #### For Each Modified File
 
-For each file, you have three versions available for proper three-way merge context:
+For each file, you have three versions available for a proper three-way merge:
 
 1. **Old template:** `.generatesaas/template/<path>` - the original boilerplate version
 2. **New template:** `.generatesaas/staging/<path>` - the updated boilerplate version
 3. **User's version:** the current file on disk - their customized version
 
-The diff at `references/diffs/<path>.diff` shows **pure upstream changes** (old template → new template), making it easy to see exactly what we changed and why.
-
-If `.generatesaas/template/<path>` does not exist (backward compat), fall back to comparing the user's file against staging directly. If no diff file exists, read both files to understand the differences.
+The diff at `references/diffs/<path>.diff` shows **pure upstream changes** (old template → new template), making it easy to see exactly what changed and why. If `.generatesaas/template/<path>` does not exist (backward compat), fall back to comparing the user's file against staging directly. If no diff file exists, read both files to understand the differences.
 
-**Present the situation clearly:**
+**Assess the merge:**
 
-```
-### `{file path}`
+- **What changed upstream** (old template → new template, from the diff and changelog)
+- **What the user changed** (old template → user's file)
+- **Overlap** (None / Partial / Significant) and **Risk** (Low = changes don't overlap; Medium = some overlap, cleanly resolvable; High = structural conflict or a heavily rewritten file)
 
-**What changed upstream:** {describe changes from old template → new template, referencing the diff and changelog}
-**What you changed:** {describe changes from old template → user's file - compare the two to identify customizations}
-**Overlap:** {None / Partial / Significant}
-**Risk:** {Low / Medium / High}
+**Then act by whether a mandatory stop applies:**
 
-{Explain risk: Low = changes don't overlap. Medium = some overlap but cleanly resolvable. High = significant structural conflict or the file was heavily rewritten.}
-
-**My recommendation:** {one of the actions below}
-
-{If recommending a merge, show the proposed result with comments marking the source:}
-```
-
-**Then present the user's options:**
+- **No mandatory stop, and you are confident the merge preserves the user's customizations:** apply the merge and report it (one line: what upstream added, what user code it kept). This is the default path for most files.
+- **A mandatory stop applies** (you are not confident; the merge changes observable behaviour or how a screen looks; or another stop below): present both versions side by side and let the user choose:
 
+> ### `{file path}`
+>
+> **What changed upstream:** {…}
+> **What you changed:** {…}
+> **Why I'm asking:** {which mandatory stop - low confidence, a changed route/default/limit/flow, changed layout/copy/theme, …}
+>
 > **What would you like to do?**
 > 1. **Accept merge** - {brief description of the merged result}
 > 2. **Keep my version** - Skip this upstream change entirely
 > 3. **Use upstream version** - Replace with the new template version (your changes will be lost)
-> 4. **Show me the diff** - Display the raw upstream diff so I can review it
-> 5. **Let me customize** - Tell me exactly what you want
-
-**In Quick mode:** For **Low risk** files, apply the recommended merge automatically and report what was done. For **Medium/High risk**, always ask.
-
-**In Automatic mode:** For **Low and Medium risk** files, apply the recommended merge automatically when you are confident it preserves the user's customizations, and report what was done. For **High risk** files - and any merge you are not confident about - always ask (see "Automatic mode behavior" in Step 5).
-
-**In Recommended mode:** Present each file and wait for the user's decision.
-
-**In Careful mode:** Present each file with the full proposed merged code shown, and wait for the user's decision.
+> 4. **Show me the diff** - Display the raw upstream diff
+> 5. **Combine them differently** - Tell me exactly what you want
 
 #### For Removed Files
 
@@ -411,21 +311,10 @@ If `.generatesaas/template/<path>` does not exist (backward compat), fall back t
 - If the user **modified** the old file: their customizations exist nowhere in the new version. Port them to the `to` path (show the proposed result) before deleting the old file. Never let a rename silently drop customizations.
 - Imports of the old path elsewhere in the project must be updated to the new path - run the import search below for the old path either way.
 
-Before presenting each removed file, **search the entire project** for imports of it. Use grep to find `import ... from` or `require(...)` statements referencing the file's path (check relative paths, aliases, and package paths). This is critical - the classification script only scans files in the update, not user-created files that may also depend on the removed file.
-
-```
-### `{file path}` - Removed Upstream
-
-**Why it was removed:** {reason from changelog}
-**Your modifications:** {describe if the user modified it, or "None - file is unmodified"}
-**Files that import this:** {list ALL files found by searching, or "None found"}
+Before deleting each removed file, **search the entire project** for imports of it. Use grep to find `import ... from` or `require(...)` statements referencing the file's path (check relative paths, aliases, and package paths). This is critical - the classification script only scans files in the update, not user-created files that may also depend on the removed file.
 
-> **What would you like to do?**
-> 1. **Delete it** - It's no longer needed upstream
-> 2. **Keep it** - I still use this file
-```
-
-If ANY files import the removed file, always warn before deletion and explain what would break.
+- **No importers and the user never modified it:** delete it, and note it in the plan.
+- **Any importer, or the user modified it:** this is a [mandatory stop](#mandatory-stops). Warn before deletion, list every importer, and let the user choose to delete or keep it.
 
 #### For Deleted-by-User Files
 
@@ -433,7 +322,7 @@ Files the user intentionally deleted - skip silently. Just note in the plan: "Sk
 
 #### For New Files In Deleted Trees (`newInDeletedTree`)
 
-These are files the new version adds inside a directory the user previously deleted (e.g. a feature package they removed). Auto-creating them would silently resurrect the deleted tree. Group them by their deleted ancestor directory and ask once per tree:
+These are files the new version adds inside a directory the user previously deleted (e.g. a feature package they removed). Auto-creating them would silently resurrect the deleted tree, so this is a [mandatory stop](#mandatory-stops). Group them by their deleted ancestor directory and ask once per tree:
 
 ```
 ### New upstream files under `{deleted dir}/` (which you removed)
@@ -450,7 +339,7 @@ Default to **keep deleted** unless the user says otherwise. If they keep it dele
 
 #### After Each File
 
-1. Apply the user's chosen action immediately
+1. Apply the chosen action immediately
 2. Mark the item as `[x]` (completed) or move to **Skipped** with the reason
 3. **Update the plan file** after every file so progress is saved
 
@@ -472,10 +361,7 @@ Similarly, if an auto-applied file changed its exports and a modified file that
 
 ### Step 8: Post-Update Validation
 
-After all files are processed, run the validation ladder below - every rung. The static
-rungs cannot see hook-level auth breakage, a missing static asset, or content wiring;
-the e2e suite is the only gate that exercises sign-in, registration, payments and the
-rendered pages. **Do not declare the update complete while any rung is red.**
+After all files are processed, run the validation ladder below - every rung. The static rungs cannot see hook-level auth breakage, a missing static asset, or content wiring; the e2e suite is the only gate that exercises sign-in, registration, payments and the rendered pages. **Do not declare the update complete while any rung is red.** A verification failure you cannot fix with confidence is a [mandatory stop](#mandatory-stops).
 
 1. **Static gates:**
    - Scan merged files for syntax errors or broken imports
@@ -517,7 +403,7 @@ rendered pages. **Do not declare the update complete while any rung is red.**
 >
 > These appear to be caused by the update. Want me to fix them?
 
-7. Fix any issues the user approves, then re-verify the affected rungs.
+7. Fix any issues the user approves, then re-verify the affected rungs. If a failure resists a confident fix, stop and ask (a mandatory stop).
 
 ### Step 9: Complete Update
 
@@ -527,10 +413,7 @@ rendered pages. **Do not declare the update complete while any rung is red.**
 - Modified files where the user chose "Keep my version"
 - Modified files that were skipped for any reason (couldn't merge, user excluded, etc.)
 - Auto-apply files that were reverted in the cascade awareness step
-- Template test/spec files you adapted to the project's customizations during validation
-  (e.g. an e2e spec whose seeded-balance or gating assumption the project legitimately
-  breaks) - the adaptation is a kept-your-version outcome, and recording it keeps the
-  next update's diff honest
+- Template test/spec files you adapted to the project's customizations during validation (e.g. an e2e spec whose seeded-balance or gating assumption the project legitimately breaks) - the adaptation is a kept-your-version outcome, and recording it keeps the next update's diff honest
 
 **Do NOT include:**
 - Files where the user accepted a merge or chose "Use upstream version" (template changes were applied)
@@ -544,12 +427,7 @@ rendered pages. **Do not declare the update complete while any rung is red.**
 
 If no files were held back, skip creating this file.
 
-> Note: the completion script runs a safety net that auto-holds-back upstream
-> changes which were demonstrably never applied (the file was not touched during
-> the entire update). Do NOT rely on it - it cannot detect a file you edited
-> during a merge or that the user customized between updates - always write
-> held-back.json yourself. Treat its warnings as a signal that your bookkeeping
-> missed something.
+> Note: the completion script runs a safety net that auto-holds-back upstream changes which were demonstrably never applied (the file was not touched during the entire update). Do NOT rely on it - it cannot detect a file you edited during a merge or that the user customized between updates - always write held-back.json yourself. Treat its warnings as a signal that your bookkeeping missed something.
 
 2. **Run the completion script:**
 
@@ -559,48 +437,55 @@ node __SKILL_ROOT__/generatesaas-update/scripts/complete-update.js
 
 This updates `.generatesaas/manifest.json` to the new version, regenerates file hashes, and cleans up staging.
 
-3. **Present the final summary:**
+3. **Present the final report:**
 
 ```markdown
 ## Result
 
 - **Status:** Completed
 - **Files auto-updated:** {count}
-- **Files merged with your input:** {count}
+- **Files merged:** {count}
 - **New files created:** {count}
-- **Changes skipped:** {count}
+- **Changes held back:** {count}
 - **Issues fixed:** {count or "None"}
 
 ### Post-update steps
 - Run `pnpm install` if dependencies changed
 - Run database migrations if schema was updated
+- CI no longer runs on push: `ci.yml` now runs on pull requests and manual dispatch, so your pushes are quiet by design - run `pnpm preflight` locally and the full set from the Actions tab ("Run workflow")
 - If your host auto-deploys on push, follow [Deploy Discipline](#deploy-discipline) below before pushing
 - {any other steps from the changelog}
 
-### Skipped changes
-{For each skipped item: what was skipped and why - so the user can revisit later}
+### Held back
+{For each held-back item: what it was and why - so the user can revisit later}
 ```
 
 ---
 
+## Mandatory stops
+
+The update runs unattended, but it **always stops and asks** at any of these. This is the one rule; nothing below it is optional:
+
+- **Database schema changes** - never auto-merge schema (see [Database](#database-schema-migrations)).
+- **An env or config change that introduces a new required value** (a new required env var, a config key with no safe default).
+- **Every new option** - never auto-adopt a feature (handled in [Step 2.5](#step-25-review-newly-available-options)).
+- **A removed file that something still imports** - run the import search first (Step 7).
+- **A `newInDeletedTree` file** - never resurrect a tree the user deleted (Step 7).
+- **A merge you are not confident preserves the user's intent** - when unsure, ask. It is always better to interrupt than to assume.
+- **A merge that changes application behaviour the user can observe** - a route, a default, a limit, a flow.
+- **A merge that changes how a screen looks** - layout, copy the user customized, theme.
+- **A verification failure you cannot fix with confidence** (Step 8).
+
+For the two behaviour/appearance stops, show the two versions side by side and ask which to keep or how to combine them. Stopping is always safe - keep the user's version and record it in `held-back.json`.
+
 ## Deploy Discipline
 
-An update usually ends with a push, and many hosts (Dokploy, Coolify, Vercel, Railway)
-auto-deploy that push. The update is not "done locally" on such a project - the push IS
-the deploy. Rules:
-
-1. **Never push a branch that auto-deploys until the full Step 8 ladder - the e2e gate
-   included - is green locally.** Pushing first and validating after turns a red gate
-   into a production incident.
-2. **After pushing, watch the CI run to its conclusion.** A red run on a commit that
-   already deployed is an incident to act on now, not a follow-up for later.
-3. **If a push webhook deploys the project, never trigger a manual deployment alongside
-   it.** Two racing deploys can fail with "service already exists" (HTTP 409) and leave
-   the service half-recreated. Trigger manually only when the deploy queue has been
-   empty for several minutes.
-4. The structural fix is to deploy from a CI job that runs **after** the test jobs
-   succeed, instead of from the push webhook - then a red gate can never reach
-   production. See the deployment docs' going-to-production checklist.
+An update usually ends with a push, and many hosts (Dokploy, Coolify, Vercel, Railway) auto-deploy that push. The update is not "done locally" on such a project - the push IS the deploy. Rules:
+
+1. **Never push a branch that auto-deploys until the full Step 8 ladder - the e2e gate included - is green locally.** Pushing first and validating after turns a red gate into a production incident.
+2. **Validate before the push, not after.** `ci.yml` no longer runs on push - it runs on pull requests and manual dispatch - so the push that deploys triggers no gate. Run `pnpm preflight` locally (or a green Actions dispatch) before pushing; a red gate found after a commit already deployed is an incident to act on now.
+3. **If a push webhook deploys the project, never trigger a manual deployment alongside it.** Two racing deploys can fail with "service already exists" (HTTP 409) and leave the service half-recreated. Trigger manually only when the deploy queue has been empty for several minutes.
+4. The structural fix is to deploy from a CI job that runs **after** the test jobs succeed, instead of from the push webhook - then a red gate can never reach production. See the deployment docs' going-to-production checklist.
 
 ## Merge Strategies
 
@@ -614,25 +499,25 @@ Config files are the most commonly customized.
 - Add new config keys with their default values
 - If a key was renamed upstream, migrate the user's value to the new key name
 - Keep user's formatting preferences if they differ
-- Present the merged config to the user for review
+- A config change that alters a default the app runs on is a [mandatory stop](#mandatory-stops)
 
 ### Components (`.vue`, `.tsx`)
 
 - Preserve user-added props, slots, event handlers, and custom logic
 - Apply upstream structural changes (new elements, accessibility improvements, bug fixes)
 - Keep user's custom CSS classes and styles
-- If the component was significantly restructured upstream AND the user heavily modified it: present both versions side by side and let the user decide
+- A change to layout, customized copy, or theme is a [mandatory stop](#mandatory-stops): present both versions side by side and let the user decide
 
 ### API Routes (`routes/*.ts`)
 
 - Preserve user-added endpoints and middleware
 - Apply upstream bug fixes and security patches to existing endpoints
 - Keep user-added business logic intact
-- Watch for new imports or dependency changes
+- Watch for new imports or dependency changes; a changed route, default, or limit is a [mandatory stop](#mandatory-stops)
 
 ### Database (schema, migrations)
 
-- NEVER auto-merge schema files - always present for user review
+- NEVER auto-merge schema files - always a [mandatory stop](#mandatory-stops)
 - Warn about schema changes that may require new migrations
 
 **Never copy an upstream migration into `packages/database/drizzle/` as-is, and never overwrite the project's `drizzle/meta/_journal.json` or `drizzle/meta/*_snapshot.json` with the upstream versions.** A project's migration history is its own: upstream changes get re-derived into it, never pasted over it. Regenerate instead:
@@ -675,6 +560,7 @@ Whichever path applies, `db:deploy` re-reads the live schema afterwards and fail
 
 - Add new environment variables with their example values and comments
 - Preserve user-added variables
+- A new **required** variable is a [mandatory stop](#mandatory-stops) - the app will not boot without it
 - Never touch actual `.env` files
 
 ## When to Skip
@@ -691,14 +577,3 @@ When skipping, always explain:
 1. What the upstream change was trying to do
 2. Why it was skipped
 3. Whether the user should revisit it later
-
-## When to Always Ask
-
-Even in Quick or Automatic mode, always ask the user about:
-
-- Database schema changes
-- Files where user modifications are extensive (>30% of the file differs from template)
-- Changes where upstream and user modifications touch the same code sections
-- Removed files that other code depends on
-- Config changes where user's value format conflicts with new requirements
-- Any change where you're unsure about the right action