chore: wip

Author: chrisbbreuer

docs/advanced/cache-optimization.md

@@ -31,6 +31,20 @@ Cache keys are generated using a deterministic approach:
 - **Bun Cache:** `{version}` (e.g., `1.2.3`)
 - **Temporary Cache:** `{timestamp}-{hash}` for downloads in progress
 
+### Environment Selection Cache
+
+Launchpad also maintains a lightweight shell-side cache for environment activation. It stores:
+
+- a persistent marker for fast-path activation, and
+- a `.deps_fingerprint` file inside the environment with the dependency fingerprint used to select it.
+
+On directory change, Launchpad validates fast-path cache with two signals:
+
+- "Cache invalid: dependency newer than cache" (dep file mtime > cache mtime)
+- "Cache invalid: fingerprint mismatch" (computed fingerprint != stored fingerprint)
+
+When either triggers, Launchpad skips fast-path and refreshes the environment selection, ensuring the correct versions are active.
+
 ## Performance Optimization
 
 ### Cache Hit Optimization

docs/advanced/performance.md

@@ -60,6 +60,10 @@ cd /path/to/project  # Even faster (cache hit)
 - Optimized PATH management (no duplicates)
 - Reduced filesystem syscalls
 
+#### Dependency Fingerprint Overhead
+
+Launchpad computes a dependency fingerprint by md5 hashing the dependency file (e.g. `deps.yaml`). This cost is O(file-size) and negligible for typical YAML/JSON files. The fingerprint is used only to select the environment directory and to validate cache freshness.
+
 ### 4. Dependency Detection Memoization
 
 Intelligent caching of dependency analysis results:

docs/faq.md

@@ -132,6 +132,15 @@ producing a path like:
 
 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.
 
+Recognized dependency files include:
+
+- `deps.yaml` / `deps.yml`
+- `dependencies.yaml` / `dependencies.yml`
+- `pkgx.yaml` / `pkgx.yml`
+- `launchpad.yaml` / `launchpad.yml`
+- `package.json`
+- `pyproject.toml`
+
 To see this live, enable verbose logging and cd into the project:
 
 ```bash

docs/features/package-management.md

@@ -271,6 +271,22 @@ Launchpad's update system provides:
 4. **Helpful messages**: Provides installation instructions for uninstalled packages
 5. **Dry-run mode**: Preview updates safely before applying changes
 
+### Version Switching on cd
+
+Launchpad encodes dependency versions into the environment directory via a dependency fingerprint (md5 of your dependency file). When you change pinned versions in your dependency file and `cd` into the project, Launchpad automatically selects a new env path:
+
+```
+~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>
+```
+
+This guarantees immediate version switches without manual cleanup. Enable verbose logs to see the chosen `env_dir`, dependency file, and fingerprint:
+
+```bash
+export LAUNCHPAD_VERBOSE=true
+cd my-project
+# 🔍 Env target: env_dir=… dep_file=… dep_hash=…
+```
+
 ### Update Examples
 
 ```bash

docs/usage.md

@@ -341,7 +341,7 @@ Supported dependency file formats:
 ### Environment Isolation
 
 Each project gets its own isolated environment:
-- Project-specific installation directory: `~/.local/share/launchpad/envs/{project-hash}/`
+- Project-specific installation directory: `~/.local/share/launchpad/envs/<project>_<hash>-d<dep_hash>`
 - Isolated PATH and environment variables
 - Binary stubs with environment isolation
 - Automatic cleanup when leaving project directory
@@ -491,13 +491,20 @@ Launchpad uses human-readable hash identifiers for environments:
 
 ### Updating Dependencies
 
-To update dependencies in your project, you'll need to manually edit your `dependencies.yaml` file and then reactivate the environment:
+To update dependencies in your project, edit your dependency file (e.g. `deps.yaml` / `dependencies.yaml`) and then reactivate the environment:
 
 ```bash
-# Edit your dependencies.yaml file
-# Change: node@22 to node@23
-# Then reactivate the environment
-cd . # This triggers environment reactivation with new dependencies
+# Edit your dependency file
+# Change: node@22 -> node@23 (or bun.sh: 1.2.19 -> 1.2.20)
+
+# Reactivate the environment (new env_dir is selected automatically)
+cd .. && cd my-project
+
+# Optional: inspect selection decisions
+export LAUNCHPAD_VERBOSE=true
+cd my-project
+# 🔍 Env target: env_dir=… dep_file=… dep_hash=…
+# 🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no
 ```
 
 ## Bootstrap Setup