chore: wip

Author: chrisbbreuer

docs/config.md

@@ -572,6 +572,31 @@ Example:
 
 ```bash
 LAUNCHPAD_VERBOSE=true LAUNCHPAD_INSTALL_PATH=~/apps launchpad install node@22
+
+## Environment Activation Model
+
+When you cd into a project directory that contains a dependency file (e.g. `deps.yaml`, `dependencies.yaml`, `pkgx.yml`, `launchpad.yml`, `package.json`, `pyproject.toml`), Launchpad computes:
+
+- A project hash based on the physical path
+- A dependency fingerprint based on the content of the dependency file (md5)
+
+The target environment directory is derived as:
+
+```
+~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>
+```
+
+This guarantees that editing dependency versions switches to a distinct environment on the next `cd`, ensuring the correct tools are active immediately.
+
+To inspect selection and cache behavior, enable verbose logging:
+
+```bash
+export LAUNCHPAD_VERBOSE=true # or set in .env
+cd my-project
+# 🔍 Env target: env_dir=… dep_file=… dep_hash=…
+# 🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no
+# 🔁 Cache invalid: dependency newer than cache
+# 🔁 Cache invalid: fingerprint mismatch
 ```
 
 ## Shell Message Customization

docs/faq.md

@@ -86,14 +86,15 @@ Currently, Launchpad is distributed via npm/bun/yarn/pnpm. However, after global
 
 ### How do environment activations work?
 
-When you enter a directory with a `dependencies.yaml` file:
+When you enter a directory with a dependency file (e.g. `deps.yaml`, `dependencies.yaml`, `pkgx.yml`, `launchpad.yml`, `package.json`, `pyproject.toml`):
 
-1. **Launchpad generates a hash** based on the project path
-2. **Creates an isolated environment** at `~/.local/share/launchpad/envs/{hash}/`
-3. **Installs project packages** to the isolated environment
-4. **Modifies PATH** to prioritize project binaries
-5. **Sets environment variables** from the dependency file
-6. **Shows activation message** (customizable)
+1. Launchpad generates a hash based on the project path
+2. Launchpad computes a dependency fingerprint (md5 of the dependency file content)
+3. It creates/selects an environment at `~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>`
+4. Installs project packages into that isolated environment (if needed)
+5. Modifies PATH to prioritize project binaries
+6. Sets environment variables from the dependency file
+7. Shows an activation message (customizable)
 
 When you leave the directory, everything is automatically restored.
 
@@ -116,6 +117,44 @@ cat dependencies.yaml
 launchpad dev:dump --dryrun
 ```
 
+### Why didn't my tool version switch after I changed deps.yaml?
+
+When you cd into a project, Launchpad now derives the environment directory from:
+
+- a hash of the project path, and
+- a dependency fingerprint (md5 of the dependency file content),
+
+producing a path like:
+
+```
+~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>
+```
+
+Changing versions in `deps.yaml` (or `dependencies.yml`, `pkgx.yml`, `launchpad.yml`, `package.json`, `pyproject.toml`, etc.) changes the fingerprint, so a new env dir is selected and the correct versions are installed/activated automatically.
+
+To see this live, enable verbose logging and cd into the project:
+
+```bash
+export LAUNCHPAD_VERBOSE=true
+cd my-project
+```
+
+You’ll see a line like:
+
+```
+🔍 Env target: env_dir=… dep_file=… dep_hash=…
+```
+
+If the env didn’t change, confirm the `dep_file` is the one you edited and that `dep_hash` differs from the previous run. You can also inspect cache decisions:
+
+```
+🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no
+🔁 Cache invalid: dependency newer than cache
+🔁 Cache invalid: fingerprint mismatch
+```
+
+Tip: if you previously activated a project and then edited dependencies, simply `cd .. && cd my-project` to pick up the new env.
+
 ### Can I disable shell messages?
 
 **Yes!** You have several options:

docs/features/environment-management.md

@@ -17,28 +17,29 @@ Environment management in Launchpad consists of two main components:
 When you enter a directory containing dependency files (like `dependencies.yaml`), Launchpad automatically:
 
 1. **Generates a unique environment hash** based on the project path
-2. **Creates an isolated environment directory** at `~/.local/share/launchpad/envs/{hash}/`
-3. **Installs project-specific packages** to the isolated environment
-4. **Modifies PATH** to prioritize the project's binaries
-5. **Sets up environment variables** as specified in the dependency file
-6. **Creates deactivation hooks** to restore the original environment when leaving
-7. **Displays customizable messages** for activation and deactivation
+2. **Computes a dependency fingerprint** (md5 of the dependency file content)
+3. **Creates/selects an isolated environment directory** at `~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>`
+4. **Installs project-specific packages** to the isolated environment
+5. **Modifies PATH** to prioritize the project's binaries
+6. **Sets up environment variables** as specified in the dependency file
+7. **Creates deactivation hooks** to restore the original environment when leaving
+8. **Displays customizable messages** for activation and deactivation
 
 ### Environment Hash Format
 
 Launchpad uses a human-readable hash format for environment directories:
 
-**Format:** `{project-name}_{8-char-hex-hash}`
+**Format:** `{project-name}_{8-char-hex-hash}-d{8-char-dep-hash}`
 
 **Examples:**
-- `my-web-app_1a2b3c4d` - For a project in `/home/user/projects/my-web-app`
-- `api-server_5e6f7g8h` - For a project in `/work/api-server`
-- `final-project_7db6cf06` - For a deeply nested project
+- `my-web-app_1a2b3c4d-d9f1a2b3` - Project `/home/user/projects/my-web-app`, dependency fingerprint `d9f1a2b3`
+- `api-server_5e6f7g8h-d0c1e2f3` - Project `/work/api-server`, dependency fingerprint `d0c1e2f3`
 
 **Benefits:**
 - **Human-readable** - Easy to identify which project an environment belongs to
+- **Version-aware** - Dependency changes always map to a distinct environment
 - **Unique** - 8-character hex hash prevents collisions between projects
-- **Consistent** - Same project path always generates the same hash
+- **Consistent** - Same project path and same deps yield the same env path
 - **Collision-resistant** - Different paths with same project name get different hashes
 
 ### Supported Dependency Files