docs: remove self-install references and update architecture docs

Updated to reflect Phase 1-3 changes:
- Removed all SelfInstall/self-installation references
- Updated CONTRIBUTING.md to use RegisterManagerV2 pattern
- Updated architecture.md to remove self-install capabilities
- Updated code-map.md to remove deleted tools.go reference
- Updated package-management.md to remove bootstrap examples
- Updated cli.md to clarify manager prerequisites

All docs now correctly state package managers must be
pre-installed, with plonk doctor providing instructions.

Author: richhaase

CONTRIBUTING.md

@@ -132,13 +132,12 @@ One of the most impactful contributions is adding support for new package manage
 
 1. **Implement the PackageManager interface** in `internal/resources/packages/`
 2. **Add required operations**: Install, Uninstall, ListInstalled, etc.
-3. **Implement optional capabilities**: Search, Info, Upgrade, Health, Self-Install (through capability interfaces)
-4. **Add health checking**: Implement `CheckHealth()` method
-5. **Add self-installation**: Implement `SelfInstall()` method
-6. **Add upgrade support**: Implement `Upgrade()` and `Outdated()` methods
-7. **Register the manager** in the package manager registry
-8. **Add tests** for all functionality
-9. **Update documentation** with examples and supported operations
+3. **Implement optional capabilities**: Search, Info, Upgrade, Health (through capability interfaces)
+4. **Add health checking**: Implement `CheckHealth()` method with installation instructions
+5. **Add upgrade support**: Implement `Upgrade()` method if applicable
+6. **Register the manager**: Use `RegisterManagerV2` with executor injection pattern
+7. **Add tests** for all functionality
+8. **Update documentation** with examples and supported operations
 
 See existing implementations like `homebrew.go`, `npm.go`, or `cargo.go` as examples.
 

docs/architecture.md

@@ -69,7 +69,7 @@ Resources are organized by type:
 - Package specification parsing (`spec.go`)
 - Command execution abstraction (`executor.go`)
 - Operations for install, uninstall, search, info, upgrade
-- Health checking and self-installation capabilities
+- Health checking capabilities
 - Outdated package detection
 
 Supported package managers:
@@ -123,7 +123,6 @@ The lock file uses a versioned format for future compatibility.
 
 - Clone command implementation
 - Git repository cloning
-- Automatic package manager installation via SelfInstall()
 - Dependency-aware installation that resolves package manager dependencies and installs in correct order
 - Tool installation
 
@@ -151,12 +150,13 @@ Plonk works without any configuration files by using sensible defaults:
 Each package manager implements a common interface following the Interface Segregation Principle (ISP). This allows:
 - Consistent behavior across different tools
 - Easy addition of new package managers
-- Optional capability detection via type assertions (search, info, upgrade, health checks, self-install)
+- Optional capability detection via type assertions (search, info, upgrade, health checks)
 - Managers implement only the capabilities they support
 - Self-health checking and diagnostics
-- Automatic self-installation during environment setup
 - Package upgrade management
 
+**Note**: Package managers must be installed manually or via other supported package managers before use. The `plonk doctor` command provides installation instructions for missing managers. All managers are registered using `RegisterManagerV2` with executor injection for testability.
+
 See [Capability Usage Examples](#capability-usage-examples) for implementation patterns.
 
 ### 3. State-Based Management
@@ -231,10 +231,10 @@ All commands support multiple output formats (table, JSON, YAML) to support:
 
 1. Implement the `PackageManager` interface in `internal/resources/packages/`
 2. Implement required operations (Install, Uninstall, ListInstalled, etc.)
-3. Implement optional capabilities through interfaces (search, info, upgrade, health, self-install)
+3. Implement optional capabilities through interfaces (search, info, upgrade, health)
 4. Implement health checking via CheckHealth() method
-5. Implement self-installation via SelfInstall() method
-6. Implement package upgrade capabilities via Upgrade() and Outdated() methods
+5. Implement package upgrade capabilities via Upgrade() and Outdated() methods
+6. Register using `RegisterManagerV2` with executor injection
 
 ### Adding a New Resource Type
 
@@ -282,9 +282,8 @@ Plonk uses structured error handling:
 - No elevated privileges required for user packages
 - Atomic file operations prevent corruption
 - Backup files created before modifications
-- Package manager self-installation may execute remote scripts (opt-in via SelfInstall capability)
 - Git operations use standard git binary
-- Users should review package manager installation scripts before using automatic installation
+- Package managers must be installed separately before use
 
 ## Future Considerations
 
@@ -321,11 +320,6 @@ if upgrader, ok := mgr.(packages.PackageUpgrader); ok {
 if hc, ok := mgr.(packages.PackageHealthChecker); ok {
     _, _ = hc.CheckHealth(ctx)
 }
-
-// Self-install (PackageSelfInstaller)
-if si, ok := mgr.(packages.PackageSelfInstaller); ok {
-    _ = si.SelfInstall(ctx)
-}
 ```
 
 Helper predicates:
@@ -334,7 +328,6 @@ if packages.SupportsInfo(mgr) { /* safe to assert PackageInfoProvider */ }
 if packages.SupportsSearch(mgr) { /* safe to assert PackageSearcher */ }
 if packages.SupportsUpgrade(mgr) { /* safe to assert PackageUpgrader */ }
 if packages.SupportsHealthCheck(mgr) { /* safe to assert PackageHealthChecker */ }
-if packages.SupportsSelfInstall(mgr) { /* safe to assert PackageSelfInstaller */ }
 ```
 
 These examples demonstrate the intent of the capability model: managers may omit optional features; callers should not assume availability without checking.

docs/cli.md

@@ -36,25 +36,21 @@ Options:
 
 ### plonk install
 
-Install packages and add them to management. Supports automatic package manager bootstrapping.
+Install packages and add them to management.
 
 ```bash
-# Bootstrap package managers (automatic detection)
-plonk install pnpm cargo uv pipx     # Self-installs the managers themselves
-
 # Install packages with default manager
-plonk install ripgrep fd bat         # Default manager
+plonk install ripgrep fd bat
 
 # Install packages with specific managers
 plonk install brew:wget npm:prettier pnpm:typescript conda:numpy uv:ruff pixi:tree
 
-# Mixed operations
-plonk install pnpm ripgrep npm:prettier  # Bootstrap pnpm, install ripgrep via default, install prettier via npm
-
 # Preview changes
-plonk install --dry-run pnpm ripgrep # Preview what would be installed
+plonk install --dry-run ripgrep
 ```
 
+**Note**: Package managers must be available before installing packages. Use `plonk doctor` to check for missing managers.
+
 ### plonk uninstall
 
 Uninstall packages and remove from management.

docs/cmds/package-management.md

@@ -28,7 +28,7 @@ Without prefix, uses `default_manager` from configuration (default: brew).
 
 ## Install Command
 
-Installs packages and adds them to plonk management. Also supports automatic package manager bootstrapping.
+Installs packages and adds them to plonk management.
 
 ### Synopsis
 
@@ -42,11 +42,9 @@ plonk install [options] <package>...
 
 ### Behavior
 
-**Package Manager Self-Installation:**
-- **Bare manager names** (e.g., `pnpm`, `cargo`) → triggers manager self-installation
-- **Prefixed names** (e.g., `brew:npm`) → installs package normally via specified manager
-
-**Regular Package Installation:**
+**Package Installation:**
+- Package managers must be available before installing packages
+- Use `plonk doctor` to check for missing package managers and view installation instructions
 - **Not installed** → installs package, adds to plonk.lock
 - **Already installed** → adds to plonk.lock (success)
 - **Already managed** → skips (no reinstall)
@@ -57,20 +55,14 @@ plonk install [options] <package>...
 ### Examples
 
 ```bash
-# Bootstrap package managers (automatic detection)
-plonk install pnpm cargo uv pipx
-
 # Install packages with default manager
 plonk install ripgrep fd bat
 
 # Install packages with specific managers
 plonk install brew:wget npm:prettier pnpm:typescript cargo:exa pipx:black conda:numpy uv:ruff pixi:tree
 
-# Mixed operations (manager bootstrap + package install)
-plonk install pnpm ripgrep npm:prettier
-
 # Preview installation
-plonk install --dry-run pnpm ripgrep
+plonk install --dry-run ripgrep
 ```
 
 ---

docs/code-map.md

@@ -106,7 +106,6 @@ This document provides a comprehensive map of the plonk codebase to aid in imple
 ### Clone Utilities (`internal/clone/`)
 - `setup.go` - Clone command implementation and package manager detection
 - `git.go` - Git operations for cloning
-- `tools.go` - Automated package manager installation via SelfInstall interface
 
 ### Diagnostics (`internal/diagnostics/`)
 - `health.go` - System health check implementations
@@ -141,8 +140,7 @@ This document provides a comprehensive map of the plonk codebase to aid in imple
 - Logic: `internal/clone/setup.go`
 - Dependency resolution: `internal/resources/packages/dependencies.go`
 - Git operations: `internal/clone/git.go`
-- Tool installation: `internal/clone/tools.go`
-- Uses: `internal/diagnostics/health.go` for health checks; package manager installation handled via `SelfInstall()` during clone
+- Uses: `internal/diagnostics/health.go` for health checks; package managers must be pre-installed, `plonk doctor` provides installation instructions
 
 ### apply command
 - Entry: `internal/commands/apply.go`