docs: Add comprehensive upgrading guide for Spec Kit

- Add upgrading-spec-kit.md with detailed upgrade instructions and troubleshooting
- Update table of contents to include upgrading guide in Getting Started section
- Update documentation index and README links
- Address user questions about updating initialized projects from GitHub discussions

Co-authored-by: GitHub Copilot <github.copilot@github.com>
Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>

Author: anchildress1

.gitignore

@@ -32,6 +32,7 @@ env/
 *.swp
 *.swo
 .DS_Store
+*.tmp
 
 # Project specific
 *.log

README.md

@@ -61,7 +61,7 @@ specify init <PROJECT_NAME>
 specify check
 ```
 
-To upgrade specify run:
+To upgrade Specify, see the [Upgrading Spec Kit guide](./docs/upgrading-spec-kit.md) for detailed instructions. Quick upgrade:
 
 ```bash
 uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
@@ -205,7 +205,7 @@ specify init --here --ai copilot
 
 # Force merge into current (non-empty) directory without confirmation
 specify init . --force --ai copilot
-# or 
+# or
 specify init --here --force --ai copilot
 
 # Skip git initialization
@@ -308,6 +308,10 @@ If you encounter issues with an agent, please open an issue so we can refine the
 
 ## 📖 Learn More
 
+- **[Installation Guide](./docs/installation.md)** - First-time installation instructions
+- **[Quick Start Guide](./docs/quickstart.md)** - Get started with a new project
+- **[Existing Project Guide](./docs/existing-project-guide.md)** - Add Spec Kit to your current codebase
+- **[Upgrading Spec Kit](./docs/upgrading-spec-kit.md)** - Update CLI and project files
 - **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process
 - **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide
 
@@ -550,7 +554,7 @@ This helps refine the implementation plan and helps you avoid potential blind sp
 You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.
 
 >[!NOTE]
->Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
+>Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
 
 ### **STEP 6:** Generate task breakdown with /speckit.tasks
 

docs/index.md

@@ -10,9 +10,10 @@ Spec-Driven Development **flips the script** on traditional software development
 
 ## Getting Started
 
-- [Installation Guide](installation.md)
-- [Quick Start Guide](quickstart.md)
-- [Local Development](local-development.md)
+- [Installation Guide](installation.md) - First-time installation of Spec Kit
+- [Quick Start Guide](quickstart.md) - Start a new project with Spec Kit
+- [Upgrading Spec Kit](upgrading-spec-kit.md) - Update CLI and project files
+- [Local Development](local-development.md) - Contribute to Spec Kit development
 
 ## Core Philosophy
 

docs/toc.yml

@@ -9,10 +9,11 @@
       href: installation.md
     - name: Quick Start
       href: quickstart.md
+    - name: Upgrading Spec Kit
+      href: upgrading-spec-kit.md
 
 # Development workflows
 - name: Development
   items:
     - name: Local Development
       href: local-development.md
-