docs: document manifest-aware project upgrades

Assisted-by: OpenAI Codex (model: GPT-5, autonomous)

Author: PascalThuet

docs/upgrade.md

@@ -12,7 +12,7 @@
 | **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. |
 | **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
 | **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. |
-| **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |
+| **Project Files** | `specify integration upgrade <key>` + `specify extension update` | Refresh installed integration files and extensions in your project |
 | **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
 
 ---
@@ -89,91 +89,94 @@ specify self check
 
 ## Part 2: Updating Project Files
 
-When Spec Kit releases new features (like new slash commands or updated templates), you need to refresh your project's Spec Kit files.
+When Spec Kit releases new features (like new slash commands, updated templates, or extension changes), you need to refresh the Spec Kit files that were installed into your project.
 
 ### What gets updated?
 
-Running `specify init --here --force` will update:
+For existing Spec Kit projects, use the manifest-aware upgrade path first:
 
-- ✅ **Slash command files** (`.claude/commands/`, `.github/prompts/`, etc.)
-- ✅ **Script files** (`.specify/scripts/`) — **only with `--force`**; without it, only missing files are added
-- ✅ **Template files** (`.specify/templates/`) — **only with `--force`**; without it, only missing files are added
-- ✅ **Shared memory files** (`.specify/memory/`) - **⚠️ See warnings below**
+- ✅ **Integration command/skill files** (`.claude/commands/`, `.github/prompts/`, `.agents/skills/`, etc.)
+- ✅ **Managed shared scripts and templates** (`.specify/scripts/`, `.specify/templates/`) when they are unchanged from the previous managed copy
+- ✅ **Installed extensions** when you run `specify extension update`
+
+The integration upgrade command uses the install manifest to detect local edits. If a managed integration file was modified after install, the command stops and asks you to inspect the change or rerun with `--force`.
 
 ### What stays safe?
 
-These files are **never touched** by the upgrade—the template packages don't even contain them:
+These files are **never touched** by the manifest-aware integration/extension upgrade path:
 
 - ✅ **Your specifications** (`specs/001-my-feature/spec.md`, etc.) - **CONFIRMED SAFE**
 - ✅ **Your implementation plans** (`specs/001-my-feature/plan.md`, `tasks.md`, etc.) - **CONFIRMED SAFE**
+- ✅ **Your constitution** (`.specify/memory/constitution.md`) when using `specify integration upgrade`
 - ✅ **Your source code** - **CONFIRMED SAFE**
 - ✅ **Your git history** - **CONFIRMED SAFE**
 
 The `specs/` directory is completely excluded from template packages and will never be modified during upgrades.
 
-### Update command
+### 1. Check installed integrations
 
 Run this inside your project directory:
 
 ```bash
-specify init --here --force --integration <your-agent>
+specify integration status
 ```
 
-Replace `<your-agent>` with your AI coding agent. Refer to this list of [Supported AI Coding Agent Integrations](reference/integrations.md)
+This reports the default integration, all installed integrations, and any modified or missing managed files. You can also inspect `.specify/integration.json`; installed integrations are listed under `installed_integrations`.
 
-**Example:**
+### 2. Upgrade each installed integration
+
+Run this inside your project directory:
 
 ```bash
-specify init --here --force --integration copilot
+specify integration upgrade <key>
 ```
 
-### Understanding the `--force` flag
+Replace `<key>` with an installed integration key such as `copilot`, `claude`, or `codex`. In projects with multiple installed integrations, run the command once per installed key.
 
-Without `--force`, the CLI warns you and asks for confirmation:
+**Example:**
 
-```text
-Warning: Current directory is not empty (25 items)
-Template files will be merged with existing content and may overwrite existing files
-Proceed? [y/N]
+```bash
+specify integration upgrade claude
+specify integration upgrade codex
 ```
 
-With `--force`, it skips the confirmation and proceeds immediately. It also **overwrites shared infrastructure files** (`.specify/scripts/` and `.specify/templates/`) with the latest versions from the installed Spec Kit release.
+See the [integration reference](reference/integrations.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`.
 
-Without `--force`, shared infrastructure files that already exist are skipped — the CLI will print a warning listing the skipped files so you know which ones were not updated.
+### 3. Update installed extensions
 
-**Important: Your `specs/` directory is always safe.** The `--force` flag only affects template files (commands, scripts, templates, memory). Your feature specifications, plans, and tasks in `specs/` are never included in upgrade packages and cannot be overwritten.
-
----
+Run:
 
-## ⚠️ Important Warnings
+```bash
+specify extension update
+```
 
-### 1. Constitution file will be overwritten
+With no extension name, this updates all installed extensions. Use `specify extension update <name>` to update only one extension. See the [extensions reference](reference/extensions.md#update-extensions) for details.
 
-**Known issue:** `specify init --here --force` currently overwrites `.specify/memory/constitution.md` with the default template, erasing any customizations you made.
+### Fallback: re-run init
 
-**Workaround:**
+If a project predates manifests, has missing integration metadata, or needs a broader recovery, you can still re-run init:
 
 ```bash
-# 1. Back up your constitution before upgrading
-cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
+specify init --here --force --integration <your-agent>
+```
 
-# 2. Run the upgrade
-specify init --here --force --integration copilot
+Use this as an escape hatch rather than the default project-file upgrade path. It refreshes the selected integration and shared project scaffolding, but it does not use the same per-integration manifest checks before overwriting files.
 
-# 3. Restore your customized constitution
-mv .specify/memory/constitution-backup.md .specify/memory/constitution.md
-```
+## ⚠️ Important Warnings
 
-Or use git to restore it:
+### 1. Constitution file and memory customizations
 
-```bash
-# After upgrade, restore from git history
-git restore .specify/memory/constitution.md
-```
+`specify integration upgrade <key>` does not update `.specify/memory/constitution.md`.
+
+The fallback `specify init --here --force --integration <your-agent>` path also preserves an existing `.specify/memory/constitution.md`; if the file is missing, init creates it from the current constitution template. You do not need a constitution backup/restore step for the manifest-aware upgrade path.
 
-### 2. Custom script or template modifications
+As with any broad fallback refresh, commit or back up local customizations before using `init --here --force` so you can review the resulting diff.
 
-If you customized files in `.specify/scripts/` or `.specify/templates/`, the `--force` flag will overwrite them. Back them up first:
+### 2. Custom integration, script, or template modifications
+
+`specify integration upgrade <key>` blocks when manifest-tracked integration files were modified locally, unless you pass `--force`.
+
+Shared scripts and templates are refreshed when they still match the previously recorded managed copy. Local customizations are preserved unless you explicitly use a force/refresh option that overwrites them. If you customized files in `.specify/scripts/` or `.specify/templates/`, commit or back them up first:
 
 ```bash
 # Back up custom templates and scripts
@@ -215,29 +218,29 @@ Restart your IDE to refresh the command list.
 # Upgrade CLI (auto-detects uv tool vs pipx install)
 specify self upgrade
 
-# Update project files to get new commands
-specify init --here --force --integration copilot
+# Inspect installed integrations
+specify integration status
 
-# Restore your constitution if customized
-git restore .specify/memory/constitution.md
+# Update project files to get new commands
+specify integration upgrade <key>
+specify extension update
 ```
 
 ### Scenario 2: "I customized templates and constitution"
 
 ```bash
-# 1. Back up customizations
-cp .specify/memory/constitution.md /tmp/constitution-backup.md
+# 1. Commit or back up customizations
+git status
 cp -r .specify/templates /tmp/templates-backup
 
 # 2. Upgrade CLI
 specify self upgrade
 
-# 3. Update project
-specify init --here --force --integration copilot
+# 3. Use the manifest-aware project update first
+specify integration upgrade <key>
+specify extension update
 
-# 4. Restore customizations
-mv /tmp/constitution-backup.md .specify/memory/constitution.md
-# Manually merge template changes if needed
+# 4. If the upgrade reports modified managed files, inspect the diff before using --force
 ```
 
 ### Scenario 3: "I see duplicate slash commands in my IDE"
@@ -262,14 +265,14 @@ rm speckit.old-command-name.md
 The git extension is now opt-in, so upgrades do not install it unless you add it explicitly.
 
 ```bash
-# Manually back up files you customized
-cp .specify/memory/constitution.md .specify/memory/constitution.backup.md
+# Upgrade CLI
+specify self upgrade
 
-# Run upgrade
-specify init --here --force --integration copilot
+# Refresh integration files and installed extensions
+specify integration upgrade <key>
+specify extension update
 
-# Restore customizations
-mv .specify/memory/constitution.backup.md .specify/memory/constitution.md
+# The git extension is not added unless you run `specify extension add git`
 ```
 
 If you later decide you want the git extension's commands and hooks, install it explicitly:
@@ -315,19 +318,21 @@ Alternatively, run the `/speckit.specify` command which creates `.specify/featur
    - Codex requires `CODEX_HOME` environment variable
    - Some agents need workspace restart or cache clearing
 
-### "I lost my constitution customizations"
+### "Will init overwrite my constitution customizations?"
+
+Current `specify init --here --force` preserves an existing `.specify/memory/constitution.md`; it creates the file from the template only when it is missing.
 
-**Fix:** Restore from git or backup:
+If you previously lost constitution changes through an older workflow or manual replacement, restore from git or backup:
 
 ```bash
-# If you committed before upgrading
+# If you committed the customized constitution
 git restore .specify/memory/constitution.md
 
 # If you backed up manually
 cp /tmp/constitution-backup.md .specify/memory/constitution.md
 ```
 
-**Prevention:** Always commit or back up `constitution.md` before upgrading.
+**Prevention:** Use `specify integration upgrade <key>` for routine project-file updates. If you need the fallback `specify init --here --force` path, commit first so you can review the full diff afterward.
 
 ### "Warning: Current directory is not empty"
 
@@ -354,7 +359,7 @@ Only Spec Kit infrastructure files:
 - Agent command files (`.claude/commands/`, `.github/prompts/`, etc.)
 - Scripts in `.specify/scripts/`
 - Templates in `.specify/templates/`
-- Memory files in `.specify/memory/` (including constitution)
+- Missing memory files such as `.specify/memory/constitution.md` may be created from templates; an existing constitution is preserved
 
 **What stays untouched:**
 
@@ -365,7 +370,7 @@ Only Spec Kit infrastructure files:
 
 **How to respond:**
 
-- **Type `y` and press Enter** - Proceed with the merge (recommended if upgrading)
+- **Type `y` and press Enter** - Proceed with the merge when using the fallback init path
 - **Type `n` and press Enter** - Cancel the operation
 - **Use `--force` flag** - Skip this confirmation entirely:
 
@@ -375,11 +380,11 @@ Only Spec Kit infrastructure files:
 
 **When you see this warning:**
 
-- ✅ **Expected** when upgrading an existing Spec Kit project
+- ✅ **Expected** when using the fallback init path in an existing Spec Kit project
 - ✅ **Expected** when adding Spec Kit to an existing codebase
 - ⚠️ **Unexpected** if you thought you were creating a new project in an empty directory
 
-**Prevention tip:** Before upgrading, commit or back up your `.specify/memory/constitution.md` if you customized it.
+**Prevention tip:** Before using the fallback init path, commit your current work so any refreshed files are easy to review or restore.
 
 ### "CLI upgrade doesn't seem to work"
 
@@ -418,14 +423,15 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
 
 ### "Do I need to run specify every time I open my project?"
 
-**Short answer:** No, you only run `specify init` once per project (or when upgrading).
+**Short answer:** No, you only run `specify init` once per project, or later as a fallback recovery path.
 
 **Explanation:**
 
 The `specify` CLI tool is used for:
 
 - **Initial setup:** `specify init` to bootstrap Spec Kit in your project
-- **Upgrades:** `specify init --here --force` to update templates and commands
+- **Routine project-file upgrades:** `specify integration upgrade <key>` and `specify extension update`
+- **Fallback recovery:** `specify init --here --force` when integration metadata is missing or the manifest-aware path cannot be used
 - **Diagnostics:** `specify check` to verify tool installation
 
 Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, `.pi/prompts/`, `.omp/commands/`, etc.). Your AI coding agent reads these command files directly—no need to run `specify` again.