generatesaas 1.2.0 → 1.2.2

package/dist/skill/content/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update
-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, classifies files, analyzes dependencies, and applies changes while preserving user customizations — the user controls every decision.
+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, classifies files, analyzes dependencies, and applies changes while preserving user customizations - the user controls every decision.
 ---
 
 # GenerateSaaS Update
@@ -9,10 +9,10 @@ Update your project to the latest GenerateSaaS boilerplate version while preserv
 
 ## 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. **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.
 
 ## Workflow Overview
 
@@ -22,25 +22,25 @@ Step 1: Fetch + stage + prepare update data (you run the CLI, then the script)
 Step 2: Present changelog to user
 Step 3: Classify files (script)
 Step 4: Analyze dependencies
-Step 5: Present update plan — user chooses interaction mode
+Step 5: Present update plan - user chooses interaction mode
 Step 6: Apply safe auto-updates (script)
-Step 7: Review modified files with user — one by one
+Step 7: Review modified files with user - one by one
 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).
+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
+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.
+faithful pristine copy of what this project started from - trust it.
 
 ---
 
@@ -48,13 +48,13 @@ faithful pristine copy of what this project started from — trust it.
 
 Before starting the update:
 
-1. **Check git status.** Run `git status --porcelain -- . ':(exclude).generatesaas'` (or otherwise ignore changes under `.generatesaas/`). The update process writes its own artifacts there — `staging.json`, `manifest.json` (license refresh), `held-back.json`, hash files — so those must NOT count as a dirty tree. If, ignoring `.generatesaas/`, there are ANY uncommitted changes (staged, unstaged, or untracked files in tracked directories), **STOP immediately**. Do NOT proceed with the update. Tell the user:
+1. **Check git status.** Run `git status --porcelain -- . ':(exclude).generatesaas'` (or otherwise ignore changes under `.generatesaas/`). The update process writes its own artifacts there - `staging.json`, `manifest.json` (license refresh), `held-back.json`, hash files - so those must NOT count as a dirty tree. If, ignoring `.generatesaas/`, there are ANY uncommitted changes (staged, unstaged, or untracked files in tracked directories), **STOP immediately**. Do NOT proceed with the update. Tell the user:
 
-> You have uncommitted changes. The update cannot proceed until your working tree is clean — this ensures you have a safe rollback point if anything needs to be reverted.
+> You have uncommitted changes. The update cannot proceed until your working tree is clean - this ensures you have a safe rollback point if anything needs to be reverted.
 >
 > **What would you like to do?**
-> 1. **I'll handle it myself** — Stop the update so you can commit, stash, or discard changes on your own terms, then re-run the update
-> 2. **Help me commit** — I'll help you create a commit with your current changes, then we continue
+> 1. **I'll handle it myself** - Stop the update so you can commit, stash, or discard changes on your own terms, then re-run the update
+> 2. **Help me commit** - I'll help you create a commit with your current changes, then we continue
 
 **NEVER** commit, stash, reset, or alter git state without the user's explicit choice. The user may have intentionally reverted work or have changes they don't want committed. Wait for their decision.
 
@@ -67,30 +67,31 @@ If the user chooses option 1, stop completely. Do not continue the update.
 > It looks like a previous update was started but not completed. The plan file shows progress from a prior attempt.
 >
 > **What would you like to do?**
-> 1. **Start fresh** — Discard the old plan and begin the update from scratch
-> 2. **Stop** — Let me review what happened before continuing
+> 1. **Start fresh** - Discard the old plan and begin the update from scratch
+> 2. **Stop** - Let me review what happened before continuing
 
-If starting fresh, delete the old plan file. Note: files that were auto-applied in the previous attempt may now have V2 content but template-hashes.json still has V1 hashes — these will be correctly classified as "modified" (since they differ from the V1 template hash) and the AI will see they match the staging file, making them trivial merges.
+If starting fresh, delete the old plan file. Note: files that were auto-applied in the previous attempt may now have V2 content but template-hashes.json still has V1 hashes - these will be correctly classified as "modified" (since they differ from the V1 template hash) and the AI will see they match the staging file, making them trivial merges.
 
 ### 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:
+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 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 for lack of an API key or network, ask the user to run
-`npx generatesaas@latest update` themselves, then continue.
+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.
 
 > 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.
+> expected - the scripts you run in the following steps are the freshly-installed ones.
 
 **1b. Prepare the diff/classification data:**
 
@@ -99,30 +100,30 @@ 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
+- `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
+- `references/update-manifest.json` - lists of added, modified, and removed files
 
 ### Step 2: Present Changelog
 
 Read `references/changelog.md`. It may be one of two shapes:
 
-- **Curated** — contains explicit `## Breaking`, `## Migration`, `## Features`, `## Fixes` (or similar) sections. Use those sections verbatim; they are authoritative.
-- **Raw** — auto-generated release notes (a flat list of PR titles, no sections). This is the common case. You can group PR titles into features/fixes by reading them, but you **cannot** reliably infer breaking changes or migration steps from PR titles.
+- **Curated** - contains explicit `## Breaking`, `## Migration`, `## Features`, `## Fixes` (or similar) sections. Use those sections verbatim; they are authoritative.
+- **Raw** - auto-generated release notes (a flat list of PR titles, no sections). This is the common case. You can group PR titles into features/fixes by reading them, but you **cannot** reliably infer breaking changes or migration steps from PR titles.
 
 Present a clear, organized summary:
 
 > ## What's New in v{targetVersion}
 >
-> **Breaking changes:** {from a Breaking section, or "⚠️ Not specified in the changelog — review the diffs in Step 7 carefully, especially database/schema and config files"}
+> **Breaking changes:** {from a Breaking section, or "⚠️ Not specified in the changelog - review the diffs in Step 7 carefully, especially database/schema and config files"}
 > **New features:** {list}
 > **Bug fixes:** {list}
-> **Migration steps required:** {from a Migration section, or "⚠️ None listed — if this update changes the database schema or required env vars, you may still need to migrate. I'll flag schema/config changes as we review them."}
+> **Migration steps required:** {from a Migration section, or "⚠️ None listed - if this update changes the database schema or required env vars, you may still need to migrate. I'll flag schema/config changes as we review them."}
 
-**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.
+**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?"*
 
@@ -136,27 +137,27 @@ 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
-- **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
-- **crossDependencies** — import relationships between categories (if detected)
+- **unmodified** - file matches the original template, safe to replace
+- **modified** - user has customized this file, needs careful review
+- **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
+- **crossDependencies** - import relationships between categories (if detected)
 
 ### Step 4: Analyze Dependencies
 
 This step prevents breaking the user's code through indirect effects.
 
 1. **Read `crossDependencies`** from classification.json (if present). This shows:
-   - `modifiedImportsUnmodified` — modified files that import from auto-apply files
-   - `unmodifiedImportsModified` — auto-apply files that import from modified files
-   - `newImportsModified` — new files that import from modified files
+   - `modifiedImportsUnmodified` - modified files that import from auto-apply files
+   - `unmodifiedImportsModified` - auto-apply files that import from modified files
+   - `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).
-   - **`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.
+   - **`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).
+   - **`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.
 
 3. **Update `references/classification.json`**: before making any changes, copy the file to `references/classification-original.json` as a backup. Then move any promoted files from the `unmodified` array to the `modified` array. This ensures `apply-auto.js` only touches truly safe files. If you need to redo the analysis, restore from the backup.
 
@@ -178,31 +179,31 @@ Date: {YYYY-MM-DD}
 
 ## Safe Auto-Updates ({count} files)
 These files haven't been customized and will be updated automatically:
-- [ ] `path/to/file.ts` — {brief description of change}
+- [ ] `path/to/file.ts` - {brief description of change}
 
 ## New Files ({count} files)
 New in this version:
-- [ ] `path/to/new-file.ts` — {what this file does}
+- [ ] `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:
-- [ ] `path/to/modified.ts` — Risk: {Low/Medium/High} — {what changed}
+- [ ] `path/to/modified.ts` - Risk: {Low/Medium/High} - {what changed}
 
 ## Removed Upstream ({count} files)
-Removed in the new version — you decide whether to delete:
-- [ ] `path/to/old-file.ts` — {why it was removed}
+Removed in the new version - you decide whether to delete:
+- [ ] `path/to/old-file.ts` - {why it was removed}
 
 ## Skipped
-{Empty — items move here during execution with reasons}
+{Empty - items move here during execution with reasons}
 ```
 
 Then ask the user to choose their interaction level:
 
 > **How would you like to handle this update?**
 >
-> 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.
+> 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.
 
 **Wait for the user's choice.** Default to **Recommended** if they just say "proceed" or similar.
 
@@ -233,9 +234,9 @@ This is the most important step. Work through each file in the `modified` catego
 
 For each file, you have three versions available for proper three-way merge context:
 
-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
+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.
 
@@ -247,7 +248,7 @@ If `.generatesaas/template/<path>` does not exist (backward compat), fall back t
 ### `{file path}`
 
 **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}
+**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}
 
@@ -261,11 +262,11 @@ If `.generatesaas/template/<path>` does not exist (backward compat), fall back t
 **Then present the user's options:**
 
 > **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
+> 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.
 
@@ -275,25 +276,25 @@ If `.generatesaas/template/<path>` does not exist (backward compat), fall back t
 
 #### For Removed Files
 
-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.
+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
+### `{file path}` - Removed Upstream
 
 **Why it was removed:** {reason from changelog}
-**Your modifications:** {describe if the user modified it, or "None — file is unmodified"}
+**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"}
 
 > **What would you like to do?**
-> 1. **Delete it** — It's no longer needed upstream
-> 2. **Keep it** — I still use this file
+> 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.
 
 #### For Deleted-by-User Files
 
-Files the user intentionally deleted — skip silently. Just note in the plan: "Skipped — user previously deleted this file."
+Files the user intentionally deleted - skip silently. Just note in the plan: "Skipped - user previously deleted this file."
 
 #### For New Files In Deleted Trees (`newInDeletedTree`)
 
@@ -302,15 +303,15 @@ These are files the new version adds inside a directory the user previously dele
 ```
 ### New upstream files under `{deleted dir}/` (which you removed)
 
-The new version adds {N} files under `{deleted dir}/` — a directory you previously deleted:
-- `{path}` — {what it is}
+The new version adds {N} files under `{deleted dir}/` - a directory you previously deleted:
+- `{path}` - {what it is}
 
 > **What would you like to do?**
-> 1. **Keep it deleted** — Skip these files (you removed this feature on purpose)
-> 2. **Bring the tree back** — Create these files (you want this feature after all)
+> 1. **Keep it deleted** - Skip these files (you removed this feature on purpose)
+> 2. **Bring the tree back** - Create these files (you want this feature after all)
 ```
 
-Default to **keep deleted** unless the user says otherwise. If they keep it deleted, note in the plan and do nothing (the completion script handles the hashes correctly — these files simply won't exist).
+Default to **keep deleted** unless the user says otherwise. If they keep it deleted, note in the plan and do nothing (the completion script handles the hashes correctly - these files simply won't exist).
 
 #### After Each File
 
@@ -329,10 +330,10 @@ After processing ALL modified files, review the results:
 >
 > **Options:**
 > 1. **Revert `{auto-file}`** to the previous version
-> 2. **Keep it** — I'll check if it still works
+> 2. **Keep it** - I'll check if it still works
 > 3. **Let me look at both files** to decide
 
-Similarly, if an auto-applied file changed its exports and a modified file that imports from it was merged — verify the merge accounts for the new API.
+Similarly, if an auto-applied file changed its exports and a modified file that imports from it was merged - verify the merge accounts for the new API.
 
 ### Step 8: Post-Update Validation
 
@@ -341,15 +342,15 @@ After all files are processed:
 1. **Check for obvious issues:**
    - Scan merged files for syntax errors or broken imports
    - If the project has TypeScript, run the type check (`pnpm check-types`)
-   - **Run the test suite (`pnpm test`) too — do not rely on the type check alone.** Most packages scope `check-types` to `src/**` and exclude `tests/**`, so a type error introduced into a **test file** during a merge will pass `check-types` silently. If any of your merges landed in a `tests/` file, the test suite is the only gate that exercises it. When in doubt, also type-check the specific merged test files directly (e.g. `npx tsc --noEmit <file>` with the package's tsconfig settings).
+   - **Run the test suite (`pnpm test`) too - do not rely on the type check alone.** Most packages scope `check-types` to `src/**` and exclude `tests/**`, so a type error introduced into a **test file** during a merge will pass `check-types` silently. If any of your merges landed in a `tests/` file, the test suite is the only gate that exercises it. When in doubt, also type-check the specific merged test files directly (e.g. `npx tsc --noEmit <file>` with the package's tsconfig settings).
    - Note: auto-applied files may have changed their exports/API in ways that affect **user-created files** (files not part of the template). The classification script only scans template files for cross-dependencies. A type check + test run is the best way to catch breakage in user-created files.
 
-> All changes have been applied. I'll run the type check **and** the test suite to verify nothing is broken — the type check alone skips test files, and some auto-applied files may have changed their API in ways that affect your custom code or tests.
+> All changes have been applied. I'll run the type check **and** the test suite to verify nothing is broken - the type check alone skips test files, and some auto-applied files may have changed their API in ways that affect your custom code or tests.
 
 2. If issues are found, present them:
 
 > Found {N} issues after the update:
-> - `{file}:{line}` — {description}
+> - `{file}:{line}` - {description}
 >
 > These appear to be caused by the update. Want me to fix them?
 
@@ -366,7 +367,7 @@ After all files are processed:
 
 **Do NOT include:**
 - Files where the user accepted a merge or chose "Use upstream version" (template changes were applied)
-- Removed files (not in staging — template-hashes handles these automatically)
+- Removed files (not in staging - template-hashes handles these automatically)
 - New files, whether created or rejected (handled correctly by staging presence)
 - Any file where the template's intended change was successfully applied
 
@@ -402,7 +403,7 @@ This updates `.generatesaas/manifest.json` to the new version, regenerates file
 - {any other steps from the changelog}
 
 ### Skipped changes
-{For each skipped item: what was skipped and why — so the user can revisit later}
+{For each skipped item: what was skipped and why - so the user can revisit later}
 ```
 
 ---
@@ -437,7 +438,7 @@ Config files are the most commonly customized.
 
 ### Database (schema, migrations)
 
-- NEVER auto-merge schema files — always present for user review
+- NEVER auto-merge schema files - always present for user review
 - New migration files can be added directly
 - Warn about schema changes that may require new migrations
 
@@ -446,7 +447,7 @@ Config files are the most commonly customized.
 - Add new dependencies from upstream
 - Update version ranges only for intentional upstream changes (security, breaking change requirements)
 - Preserve user-added dependencies
-- Never touch `pnpm-lock.yaml` — user runs `pnpm install` after
+- Never touch `pnpm-lock.yaml` - user runs `pnpm install` after
 
 ### Translation Files (`en.json`)
 

package/dist/skill/content/scripts/_helpers.js

@@ -1,6 +1,6 @@
 /**
  * Shared helpers for update scripts.
- * CommonJS module — used by prepare-update.js, apply-auto.js, classify-files.js, complete-update.js.
+ * CommonJS module - used by prepare-update.js, apply-auto.js, classify-files.js, complete-update.js.
  */
 
 const fs = require("node:fs");

package/dist/skill/content/scripts/apply-auto.js

@@ -36,7 +36,7 @@ function main() {
 		process.exit(1);
 	}
 
-	// `new` only ever contains genuinely-new trees — files inside buyer-deleted
+	// `new` only ever contains genuinely-new trees - files inside buyer-deleted
 	// trees land in `newInDeletedTree`, which the AI handles by prompt (never here).
 	const filesToCopy = [...classification.unmodified, ...classification.new];
 
@@ -49,12 +49,12 @@ function main() {
 	const unmodifiedSet = new Set(classification.unmodified);
 
 	// Pre-flight: every source must exist in staging. Abort BEFORE touching the
-	// project if any are missing — never leave a half-applied tree (there is no
+	// project if any are missing - never leave a half-applied tree (there is no
 	// rollback besides git). Buyer-shaped staging should always contain them; a
 	// miss means staging is stale or incomplete.
 	const missing = filesToCopy.filter((f) => !fs.existsSync(path.join(stagingDir, f)));
 	if (missing.length > 0) {
-		console.error(`Error: ${missing.length} file(s) not found in staging — aborting without changes:`);
+		console.error(`Error: ${missing.length} file(s) not found in staging - aborting without changes:`);
 		for (const f of missing) console.error(`  - ${f}`);
 		console.error("Re-stage the update (run 'npx generatesaas@latest update') and retry.");
 		process.exit(1);

package/dist/skill/content/scripts/classify-files.js

@@ -15,7 +15,7 @@ const { findProjectRoot, hashFile, TEMPLATE_HASHES_FILE, HASHES_FILE, STAGING_DI
 
 /**
  * Extract local import paths from file content.
- * Only captures relative (./, ../), alias (~/, @/), and # imports — skips packages.
+ * Only captures relative (./, ../), alias (~/, @/), and # imports - skips packages.
  */
 function extractImports(content, filePath) {
 	// For Vue SFCs, extract all script block contents (both <script> and <script setup>)
@@ -54,7 +54,7 @@ function matchImportToFile(importPath, fromFilePath, knownFileSet) {
 	if (importPath.startsWith("./") || importPath.startsWith("../")) {
 		basePath = path.normalize(path.join(path.dirname(fromFilePath), importPath));
 	} else if (importPath.startsWith("~/") || importPath.startsWith("@/") || importPath.startsWith("#")) {
-		// Alias — strip prefix. ~ and @ typically resolve from the app root.
+		// Alias - strip prefix. ~ and @ typically resolve from the app root.
 		basePath = importPath.replace(/^[~@#]\//, "");
 	} else {
 		return null;
@@ -163,7 +163,7 @@ function buildCrossDependencies(root, classification, stagingDir) {
 		if (content) scanFileContent(f, content, "modified");
 	}
 
-	// Scan unmodified files — both current AND staging versions
+	// Scan unmodified files - both current AND staging versions
 	// (staging is what will actually be placed, so its imports matter)
 	for (const f of classification.unmodified) {
 		const content = readSafe(path.join(root, f));
@@ -250,15 +250,15 @@ function main() {
 		if (!fs.existsSync(fullPath)) {
 			classification.deleted.push(filePath);
 		} else if (!baselineHash) {
-			// No baseline hash — treat as modified to be safe
+			// No baseline hash - treat as modified to be safe
 			classification.modified.push(filePath);
 		} else {
 			const currentHash = hashFile(fullPath);
 			if (currentHash === baselineHash) {
-				// File matches the original template — safe to auto-update
+				// File matches the original template - safe to auto-update
 				classification.unmodified.push(filePath);
 			} else {
-				// File differs from template — user has customized
+				// File differs from template - user has customized
 				classification.modified.push(filePath);
 			}
 		}
@@ -271,7 +271,7 @@ function main() {
 			classification.modified.push(filePath);
 		} else if (deletedTreeAncestor(filePath, root, baselineFiles)) {
 			// Upstream added a file inside a directory tree the buyer deleted on
-			// purpose. Don't silently recreate the tree — surface for a decision.
+			// purpose. Don't silently recreate the tree - surface for a decision.
 			classification.newInDeletedTree.push(filePath);
 		} else {
 			classification.new.push(filePath);
@@ -314,7 +314,7 @@ function main() {
 	console.log("");
 
 	if (classification.newInDeletedTree.length > 0) {
-		console.log("New files inside trees you deleted (do NOT auto-create — ask the user):");
+		console.log("New files inside trees you deleted (do NOT auto-create - ask the user):");
 		for (const f of classification.newInDeletedTree) {
 			console.log(`  - ${f}`);
 		}

package/dist/skill/content/scripts/complete-update.js

@@ -7,7 +7,7 @@
  * .generatesaas/manifest.json, and cleans up staging + references.
  *
  * Reads .generatesaas/held-back.json (if present) to skip updating template
- * files that were held back — their old template version is preserved so the
+ * files that were held back - their old template version is preserved so the
  * next update generates correct diffs that include the missed changes.
  */
 
@@ -54,6 +54,43 @@ function collectProjectFiles(dir, baseDir) {
 	return files;
 }
 
+/**
+ * Archive a finished update plan file. The skill writes its checklist to
+ * .generatesaas/updates/update-<from>-to-<to>.md and ticks items off as it goes;
+ * once the update completes we move it into updates/history/ so its presence no
+ * longer reads as an "incomplete previous update" on the next run, while keeping
+ * the record of what was skipped. Best-effort: bookkeeping must never fail a
+ * completed update.
+ */
+function archivePlanFile(root) {
+	const updatesDir = path.join(root, INTERNAL_DIR, "updates");
+	if (!fs.existsSync(updatesDir)) return;
+
+	let entries;
+	try {
+		entries = fs.readdirSync(updatesDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	const plans = entries.filter((e) => e.isFile() && /^update-.+\.md$/.test(e.name));
+	if (plans.length === 0) return;
+
+	const historyDir = path.join(updatesDir, "history");
+	for (const plan of plans) {
+		const src = path.join(updatesDir, plan.name);
+		const dest = path.join(historyDir, plan.name);
+		try {
+			ensureDir(historyDir);
+			fs.rmSync(dest, { force: true });
+			fs.renameSync(src, dest);
+			console.log(`Archived plan file to ${path.relative(root, dest)}`);
+		} catch (err) {
+			console.warn(`  Warning: could not archive plan file "${plan.name}": ${err.message}`);
+		}
+	}
+}
+
 function main() {
 	const root = findProjectRoot();
 	if (!root) {
@@ -85,7 +122,7 @@ function main() {
 	);
 
 	if (heldBack.size > 0) {
-		console.log(`${heldBack.size} files were held back — preserving their old template versions.`);
+		console.log(`${heldBack.size} files were held back - preserving their old template versions.`);
 	}
 
 	// ── Update template directory from staging ──
@@ -97,23 +134,23 @@ function main() {
 		const stagingFiles = new Set(walkDir(stagingDir, stagingDir));
 
 		// Validate held-back entries (non-fatal). A held-back file is supposed to be
-		// a real upstream change the user chose to skip — preserving its old template
+		// a real upstream change the user chose to skip - preserving its old template
 		// version so the next update re-surfaces the missed change. Warn on entries
 		// that can't be that: a path not in staging (nothing to hold back), or a file
 		// identical between old template and staging (no upstream change to preserve).
 		// A wrong held-back entry silently corrupts the next update's diff baseline.
 		for (const rel of heldBack) {
 			if (!stagingFiles.has(rel)) {
-				console.warn(`  Warning: held-back "${rel}" is not in staging — nothing to hold back. Check .generatesaas/held-back.json.`);
+				console.warn(`  Warning: held-back "${rel}" is not in staging - nothing to hold back. Check .generatesaas/held-back.json.`);
 				continue;
 			}
 			const oldTemplateFile = path.join(templateDir, rel);
 			if (fs.existsSync(oldTemplateFile) && hashFile(oldTemplateFile) === hashFile(path.join(stagingDir, rel))) {
-				console.warn(`  Warning: held-back "${rel}" is identical in the old template and staging — no upstream change to preserve.`);
+				console.warn(`  Warning: held-back "${rel}" is identical in the old template and staging - no upstream change to preserve.`);
 			}
 		}
 
-		// Copy staging files to template dir (skip held-back — old version stays)
+		// Copy staging files to template dir (skip held-back - old version stays)
 		let copied = 0;
 		let skipped = 0;
 		for (const rel of stagingFiles) {
@@ -203,13 +240,21 @@ function main() {
 	fs.writeFileSync(hashesPath, JSON.stringify(fileHashes, null, "\t") + "\n", "utf-8");
 	console.log(`Tracked ${Object.keys(fileHashes).length} file hashes in ${HASHES_FILE}`);
 
+	// Archive the finished plan file so the next update's pre-flight check doesn't
+	// mistake a completed update for an interrupted one.
+	archivePlanFile(root);
+
 	console.log(`\nUpdate to ${targetVersion} complete!`);
 	console.log("Run 'pnpm install' if package.json was updated.");
 }
 
-try {
-	main();
-} catch (err) {
-	console.error("Error:", err.message);
-	process.exit(1);
+if (require.main === module) {
+	try {
+		main();
+	} catch (err) {
+		console.error("Error:", err.message);
+		process.exit(1);
+	}
 }
+
+module.exports = { main, archivePlanFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generatesaas",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "type": "module",
   "description": "CLI for scaffolding and managing GenerateSaaS projects",
   "bin": {