Merge branch 'main' into kc/cooldown

Author: kelvin-chappell

README.md

@@ -131,17 +131,7 @@ You can also run `devenv check` to verify that the generated devcontainer.json f
 
 ## Configuration
 
-**Project config**: `.devcontainer/devenv.yaml` - Project-specific settings (name, ports, IDE plugins, commands, etc). Checked into version control.
-
-**User config**: `~/.config/devenv/devenv.yaml` - Personal preferences (dotfiles, additional IDE plugins). Merged with project config for the user-specific devcontainer.
-
-Two devcontainer files are generated:
-- `.devcontainer/user/devcontainer.json` - Merged config with your personal settings
-- `.devcontainer/shared/devcontainer.json` - Project-only config for team use
-
-Your user-specific file is excluded from the Git repository with a .gitignore entry. The general project file can be checked in to provide a project environment for cloud-based editors.
-
-For detailed configuration specifications, see the [Configuration Reference](docs/configuration.md).
+For detailed configuration specifications, including all supported fields, modules and the escape hatch, see the [Configuration Reference](docs/configuration.md).
 
 ## Development
 
@@ -169,6 +159,13 @@ The project also includes generation tests that validate the real program output
 ./generation-tests/run-tests.sh
 ```
 
+### Contributing
+
+#### Adding a module
+
+See [docs/contributing/adding-a-module.md](docs/contributing/adding-a-module.md) 
+for a guide on implementing, testing and documenting a new built-in module.
+
 ### Release
 
 The project uses a GitHub action to build and publish date-based releases that contain native binaries for macOS arm64 (m-series processors), Linux amd64 and Linux arm64.

core/src/test/resources/userConfig.yaml

@@ -8,4 +8,4 @@ dotfiles:
   repository: "https://github.com/example/dotfiles.git"
   targetPath: "~"
   installCommand: "install.sh"
-containerSize: small
+containerSize: small

docs/configuration.md

@@ -78,14 +78,17 @@ The user config (`~/.config/devenv/devenv.yaml`) supports the following (optiona
 
 ### Dotfiles Configuration
 
-The `dotfiles` field in the user config allows you to specify a GitHub repository containing your personal dotfiles to
-be cloned and installed into the devcontainer. All three fields are required.
-
-| Field            | Description                                                 |
-|------------------|-------------------------------------------------------------|
-| `repository`     | GitHub repository (format: `username/repo`)                 |
-| `targetPath`     | Path where dotfiles will be cloned in the container         |
-| `installCommand` | Script to run for installation (executed from `targetPath`) |
+The `dotfiles` field allows you to specify a GitHub repository containing your personal dotfiles to be cloned and
+installed into the devcontainer. All three fields are required.  
+The dotfiles setup runs after project/container setup
+to avoid interfering with shared configuration. The repository is cloned into the container at the specified path and
+the `installCommand` is executed from there.
+
+| Field            | Description                                                             |
+|------------------|-------------------------------------------------------------------------|
+| `repository`     | Full GitHub repository URL (eg. `https://github.com/username/dotfiles`) |
+| `targetPath`     | Path where dotfiles will be cloned in the container                     |
+| `installCommand` | Script to run for installation (executed from `targetPath`)             |
 
 ### Example
 
@@ -95,9 +98,9 @@ plugins:
     - usernamehw.errorlens
     - eamodio.gitlens
 dotfiles:
-  repository: "your-github-id/your-dotfiles-repo"
+  repository: "https://github.com/username/dotfiles"
   targetPath: "~/dotfiles"
-  installCommand: "install.sh"
+  installCommand: "./install.sh"
 ```
 
 ## Escape Hatch Spec
@@ -172,20 +175,10 @@ modules:
   - docker-in-docker  # Now enabled
 ```
 
-## Dotfiles
-
-You can configure personal dotfiles in your user config (`~/.config/devenv/devenv.yaml`) to automatically clone and
-install them during container creation:
-
-```yaml
-dotfiles:
-  repository: "your-github-id/your-dotfiles-repo"
-  targetPath: "~/dotfiles"
-  installCommand: "install.sh"
-```
+### Adding a new module
 
-The dotfiles setup runs after project/container setup to avoid interfering with shared configuration. The repository is
-cloned into the container at the specified path, and the `installCommand` is executed from there.
+See the [Adding a Module](contributing/adding-a-module.md) guide for a full walkthrough of how to
+implement, test and document a new built-in module.
 
 ## Container Size