From 641c48c18267760b1ff2dd5d010718fb6506fc7d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 27 Jul 2026 14:13:57 +0000
Subject: [PATCH] feat(generate): add Services section to generated project
 README

`devbox generate readme` documented scripts, packages, environment
variables, and the shell init hook, but never mentioned services. This
made services less discoverable in a project's generated README even
though they are a first-class part of a Devbox environment.

Add a Services section to the generated README that lists each service
(from the project's plugins and its process-compose.yaml) and documents
how to start, stop, and list them. The section is omitted when the
project defines no services.

Fixes #2626

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qgu2wVkmAdXLRKcpgevoBW
---
 internal/devbox/docgen/docgen.go     |  6 ++++++
 internal/devbox/docgen/readme.tmpl   | 10 ++++++++++
 testscripts/generate/readme.test.txt | 26 ++++++++++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 testscripts/generate/readme.test.txt

diff --git a/internal/devbox/docgen/docgen.go b/internal/devbox/docgen/docgen.go
index 957a22f7821..7e77c364268 100644
--- a/internal/devbox/docgen/docgen.go
+++ b/internal/devbox/docgen/docgen.go
@@ -45,6 +45,11 @@ func GenerateReadme(
 		outputPath = defaultName
 	}
 
+	services, err := devbox.Services()
+	if err != nil {
+		return err
+	}
+
 	f, err := os.Create(outputPath)
 	if err != nil {
 		return err
@@ -58,6 +63,7 @@ func GenerateReadme(
 		"EnvVars":  devbox.Config().Env(),
 		"InitHook": devbox.Config().InitHook(),
 		"Packages": devbox.TopLevelPackages(),
+		"Services": services,
 		// TODO add includes
 	})
 }
diff --git a/internal/devbox/docgen/readme.tmpl b/internal/devbox/docgen/readme.tmpl
index ad3306f58cd..94d7309849b 100644
--- a/internal/devbox/docgen/readme.tmpl
+++ b/internal/devbox/docgen/readme.tmpl
@@ -33,6 +33,16 @@ Scripts are custom commands that can be run using this project's environment. Th
 {{- end }}
 {{ end }}
 
+{{- if .Services }}
+## Services
+Services are long-running processes (such as databases or web servers) provided by this project's packages and plugins. This project has the following services:
+{{ range $name, $_ := .Services }}
+* {{ $name }}
+{{- end }}
+
+Start all services with `devbox services up`, and stop them with `devbox services stop`. You can also target an individual service by name, for example `devbox services up <service>`. Run `devbox services ls` to list the services and their status.
+{{ end }}
+
 {{- if .EnvVars }}
 ## Environment
 
diff --git a/testscripts/generate/readme.test.txt b/testscripts/generate/readme.test.txt
new file mode 100644
index 00000000000..0c8d03edc7d
--- /dev/null
+++ b/testscripts/generate/readme.test.txt
@@ -0,0 +1,26 @@
+# Verify `devbox generate readme` includes a Services section listing the
+# services defined for the project. See issue #2626.
+
+exec devbox init
+exists devbox.json
+
+# `devbox generate readme` should discover the services defined in the
+# project's process-compose.yaml (see the embedded file below).
+exec devbox generate readme
+exists README.md
+
+# The generated README should contain a Services section that lists each
+# service and documents how to start/stop them.
+grep '## Services' README.md
+grep '\* web' README.md
+grep '\* worker' README.md
+grep 'devbox services up' README.md
+grep 'devbox services stop' README.md
+
+-- process-compose.yaml --
+version: "0.5"
+processes:
+  web:
+    command: "echo web"
+  worker:
+    command: "echo worker"