docs: add NOTES.md documentation and refresh template descriptions

.github/workflows/ci.yml

@@ -21,13 +21,13 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Check description length (max 80 chars)
+      - name: Check description length (max 88 chars)
         run: |
           failed=0
           while IFS= read -r file; do
             desc=$(jq -r '.description' "$file")
             len=${#desc}
-            if [[ $len -gt 80 ]]; then
+            if [[ $len -gt 88 ]]; then
               echo "FAIL ($len chars): $file"
               echo "  $desc"
               failed=1

README.md

@@ -41,15 +41,15 @@ If you use [Renovate](https://docs.renovatebot.com/) or Dependabot, they can aut
 
 | Template | Registry | Description |
 |----------|----------|-------------|
-| [Bun](src/bun) | `ghcr.io/bare-devcontainer/templates/bun` | A JavaScript/TypeScript development environment based on the bare-devcontainer Bun image, with the Bun runtime installed. |
-| [Debian](src/debian) | `ghcr.io/bare-devcontainer/templates/debian` | A minimal Debian development environment based on the bare-devcontainer Debian image. |
-| [Go](src/golang) | `ghcr.io/bare-devcontainer/templates/golang` | A Go development environment based on the bare-devcontainer Go image. |
-| [mise](src/mise) | `ghcr.io/bare-devcontainer/templates/mise` | A development environment with mise (polyglot runtime manager) on Debian, for managing multiple language runtimes per project. |
-| [Node.js](src/node) | `ghcr.io/bare-devcontainer/templates/node` | A Node.js development environment based on the bare-devcontainer Node.js image. |
-| [Rust](src/rust) | `ghcr.io/bare-devcontainer/templates/rust` | A Rust development environment based on the bare-devcontainer Rust image, with Rust installed via rustup. |
-| [Terraform](src/terraform) | `ghcr.io/bare-devcontainer/templates/terraform` | An infrastructure-as-code development environment based on the bare-devcontainer Terraform image, with the Terraform CLI and terraform-ls installed. |
-| [uv](src/uv) | `ghcr.io/bare-devcontainer/templates/uv` | A Python development environment based on the bare-devcontainer uv image, with uv installed for managing Python versions and packages. |
-| [Zig](src/zig) | `ghcr.io/bare-devcontainer/templates/zig` | A Zig development environment based on the bare-devcontainer Zig image. |
+| [Bun](src/bun) | `ghcr.io/bare-devcontainer/templates/bun` | Security-focused Bun dev container for JS/TS with hardened defaults and cached installs. |
+| [Debian](src/debian) | `ghcr.io/bare-devcontainer/templates/debian` | Security-focused minimal Debian base for any stack, with hardened container defaults. |
+| [Go](src/golang) | `ghcr.io/bare-devcontainer/templates/golang` | Security-focused Go dev container with hardened defaults and rebuild-friendly caches. |
+| [mise](src/mise) | `ghcr.io/bare-devcontainer/templates/mise` | Security-focused mise dev container for multiple runtimes, with rebuild-friendly caches. |
+| [Node.js](src/node) | `ghcr.io/bare-devcontainer/templates/node` | Security-focused Node.js dev container for JS/TS with hardened, non-root defaults. |
+| [Rust](src/rust) | `ghcr.io/bare-devcontainer/templates/rust` | Security-focused Rust dev container with rust-analyzer and persistent Cargo caches. |
+| [Terraform](src/terraform) | `ghcr.io/bare-devcontainer/templates/terraform` | Security-focused Terraform dev container with terraform-ls and rebuild-friendly caching. |
+| [uv](src/uv) | `ghcr.io/bare-devcontainer/templates/uv` | Security-focused Python dev container with uv, hardened defaults, and cached packages. |
+| [Zig](src/zig) | `ghcr.io/bare-devcontainer/templates/zig` | Security-focused Zig dev container with zls integration and a persistent build cache. |
 
 ## License
 

src/bun/NOTES.md

@@ -0,0 +1,26 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/bun` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Persistent Caches
+
+Bun's global install cache is persisted in a named volume, so rebuilding the container to pick up image updates doesn't require re-downloading packages:
+
+| Volume | Mount path | Purpose |
+|--------|------------|---------|
+| `${devcontainerId}-bun-install-cache` | `/home/dev/.bun/install/cache` | Bun's global install cache |
+
+## Editor Integration
+
+- Installs the `oven.bun-vscode` VS Code extension, with `bun.runtime` preconfigured to the Bun binary shipped in the image (`/usr/local/bin/bun`).
+
+## Tips
+
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/bun/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "bun",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "name": "Bun",
-  "description": "Minimal, supply-chain-secure dev container with Bun for JS/TypeScript.",
+  "description": "Security-focused Bun dev container for JS/TS with hardened defaults and cached installs.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/bun",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/debian/NOTES.md

@@ -0,0 +1,22 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/debian` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Usage Notes
+
+This template is a minimal Debian base for any development stack — no language toolchain is preinstalled. To add tooling, you can:
+
+- layer [Dev Container Features](https://containers.dev/features) on top of the image,
+- extend the image with your own `Dockerfile`, or
+- switch to a stack-specific Bare Dev Container template (Go, Rust, Node.js, ...).
+
+## Tips
+
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/debian/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "debian",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "name": "Debian",
-  "description": "Minimal, supply-chain-secure Debian base for any development stack.",
+  "description": "Security-focused minimal Debian base for any stack, with hardened container defaults.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/debian",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/golang/NOTES.md

@@ -0,0 +1,29 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/golang` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Persistent Caches
+
+The Go module and build caches are persisted in named volumes, so rebuilding the container to pick up image updates doesn't require re-downloading modules or recompiling packages:
+
+| Volume | Mount path | Purpose |
+|--------|------------|---------|
+| `${devcontainerId}-golang-pkg-mod` | `/home/dev/go/pkg/mod` | Go module cache (`GOMODCACHE`) |
+| `${devcontainerId}-golang-build-cache` | `/home/dev/.cache/go-build` | Go build cache (`GOCACHE`) |
+
+## Editor Integration
+
+- Installs the `golang.go` VS Code extension, with format-on-save and organize-imports enabled for Go files and gopls semantic tokens turned on.
+- Automatic updates of the Go tools are disabled (`go.toolsManagement.autoUpdate: false`, update checks are local only), so the editor does not download tools behind your back.
+
+## Tips
+
+- To use the debugger (delve), uncomment `"capAdd": ["SYS_PTRACE"]` in `devcontainer.json`.
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/golang/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "golang",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "name": "Go",
-  "description": "Minimal, supply-chain-secure dev container with Go toolchain.",
+  "description": "Security-focused Go dev container with hardened defaults and rebuild-friendly caches.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/golang",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/mise/NOTES.md

@@ -0,0 +1,34 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/mise` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Persistent Caches
+
+mise's data directory and download cache are persisted in named volumes, so toolchains installed with mise survive container rebuilds and don't need to be re-downloaded:
+
+| Volume | Mount path | Purpose |
+|--------|------------|---------|
+| `${devcontainerId}-mise-data` | `/home/dev/.local/share/mise` | mise-managed toolchains |
+| `${devcontainerId}-mise-cache` | `/home/dev/.cache/mise` | mise's download cache |
+
+## Usage Notes
+
+[mise](https://mise.jdx.dev/) is a polyglot runtime manager. Install and pin the runtimes your project needs, for example:
+
+```sh
+mise use node@24
+mise use python@3.13
+```
+
+The installed runtimes are stored in the persisted data volume, so they remain available after rebuilding the container.
+
+## Tips
+
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/mise/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "mise",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "name": "mise",
-  "description": "Minimal, supply-chain-secure dev container with mise for multiple runtimes.",
+  "description": "Security-focused mise dev container for multiple runtimes, with rebuild-friendly caches.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/mise",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/node/NOTES.md

@@ -0,0 +1,24 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/node` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Tips
+
+- To keep npm's download cache across container rebuilds, add a named volume to `mounts` in `devcontainer.json`:
+
+  ```json
+  {
+    "source": "${devcontainerId}-npm-cache",
+    "target": "/home/dev/.npm",
+    "type": "volume"
+  }
+  ```
+
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/node/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "node",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "name": "Node.js",
-  "description": "Minimal, supply-chain-secure Node.js dev container for JS/TypeScript.",
+  "description": "Security-focused Node.js dev container for JS/TS with hardened, non-root defaults.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/node",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/rust/NOTES.md

@@ -0,0 +1,30 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/rust` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Persistent Caches
+
+Cargo's registry and git caches are persisted in named volumes, so rebuilding the container to pick up image updates doesn't require re-downloading crates:
+
+| Volume | Mount path | Purpose |
+|--------|------------|---------|
+| `${devcontainerId}-rust-cargo-registry` | `/home/dev/.cargo/registry` | Cargo registry cache |
+| `${devcontainerId}-rust-cargo-git` | `/home/dev/.cargo/git` | Cargo's cache of git-sourced dependencies |
+
+Only `registry/` and `git/` are mounted; `~/.cargo/bin` is intentionally left in the image layer so the toolchain binaries always come from the image.
+
+## Editor Integration
+
+- Installs the `rust-lang.rust-analyzer` VS Code extension, with format-on-save enabled for Rust files.
+
+## Tips
+
+- To use the debugger, uncomment `"capAdd": ["SYS_PTRACE"]` in `devcontainer.json`.
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/rust/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "rust",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "name": "Rust",
-  "description": "Minimal, supply-chain-secure dev container with Rust.",
+  "description": "Security-focused Rust dev container with rust-analyzer and persistent Cargo caches.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/rust",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",

src/terraform/NOTES.md

@@ -0,0 +1,26 @@
+## Security Hardening
+
+This template applies the shared hardening defaults of Bare Dev Container Templates:
+
+- Runs as the non-root `dev` user.
+- Drops all Linux capabilities (`--cap-drop=ALL`) and sets the `no-new-privileges` security option, so processes cannot gain elevated privileges inside the container. Remove `no-new-privileges` from `securityOpt` if you need `su`/`sudo`.
+- Starts an init process (`"init": true`) to reap zombie processes.
+- The base image `ghcr.io/bare-devcontainer/terraform` is a minimal [Bare Dev Container Image](https://github.com/bare-devcontainer/images) that limits trusted upstreams to official sources to reduce supply-chain risk.
+
+After applying the template, we recommend pinning the image to a digest so every rebuild uses exactly the image you expect — see [Pinning Images to a Digest](https://github.com/bare-devcontainer/templates#pinning-images-to-a-digest).
+
+## Persistent Caches
+
+The Terraform plugin cache directory is persisted in a named volume, so rebuilding the container to pick up image updates doesn't require re-downloading providers:
+
+| Volume | Mount path | Purpose |
+|--------|------------|---------|
+| `${devcontainerId}-terraform-plugin-cache` | `/home/dev/.terraform.d/plugin-cache` | Terraform provider plugin cache |
+
+## Editor Integration
+
+- Installs the `hashicorp.terraform` and `hashicorp.hcl` VS Code extensions, with the language server paths preconfigured to the `terraform-ls` and `terraform` binaries shipped in the image, and format-on-save enabled for `.tf` and `.tfvars` files.
+
+## Tips
+
+- If you use VS Code, uncomment the `remoteEnv` block in `devcontainer.json` to open `$EDITOR`/`$VISUAL`/`$GIT_EDITOR` (e.g. `git commit`) in a VS Code tab.

src/terraform/devcontainer-template.json

@@ -1,8 +1,8 @@
 {
   "id": "terraform",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "name": "Terraform",
-  "description": "Minimal, supply-chain-secure dev container with Terraform CLI and terraform-ls.",
+  "description": "Security-focused Terraform dev container with terraform-ls and rebuild-friendly caching.",
   "publisher": "Bare Dev Container Maintainers",
   "documentationURL": "https://github.com/bare-devcontainer/templates/tree/main/src/terraform",
   "licenseURL": "https://github.com/bare-devcontainer/templates/blob/main/LICENSE",