diff --git a/docs/guides/compile-servers.mdx b/docs/guides/compile-servers.mdx
index b666a5b56..d0995c0bf 100644
--- a/docs/guides/compile-servers.mdx
+++ b/docs/guides/compile-servers.mdx
@@ -60,6 +60,33 @@ need to reclaim memory before doing something else heavy.
 
 [Reference →](/docs/reference/cli/config/compile-server/)
 
+## Idle self-shutdown
+
+A shared server that hasn't served a client for a while shuts
+itself down, so servers left behind by closed worktrees, JVM
+bumps, or upgraded bleep binaries don't pile up and hold memory
+indefinitely. The default is one hour.
+
+```bash
+bleep config compile-server idle-timeout 120   # minutes
+bleep config compile-server idle-timeout 0      # never self-shut-down
+bleep config compile-server idle-timeout-clear  # back to default 60
+```
+
+The clock measures **fully-idle** time only: it resets whenever a
+client connects and stays reset for as long as any client is
+connected. So a long compile, or an editor left open over lunch,
+keeps the server alive — the timeout only fires once nothing has
+been connected for the whole window. When it does fire, the server
+releases its lock and removes its socket files, so the next `bleep`
+command in that workspace just starts a fresh one.
+
+This is different from the [idle read timeout](#idle-read-timeout)
+below: that drops a single stuck *connection*; this retires the
+whole *server* once it has been unused for long enough.
+
+[Reference →](/docs/reference/cli/config/compile-server/)
+
 ## Memory
 
 The compile server holds Zinc analysis, compiler state, and live
diff --git a/docs/reference/cli/config/compile-server.mdx b/docs/reference/cli/config/compile-server.mdx
index 1a6b9e611..c72fee700 100644
--- a/docs/reference/cli/config/compile-server.mdx
+++ b/docs/reference/cli/config/compile-server.mdx
@@ -88,3 +88,23 @@ bleep config compile-server read-timeout <minutes>
 
 <p>remove read timeout setting (use default: 30 minutes)</p>
 
+## `bleep config compile-server idle-timeout`
+
+<p>set minutes the server stays alive with no connected client before shutting itself down, 0 to stay alive forever (default: 60)</p>
+
+### Synopsis
+
+```bash
+bleep config compile-server idle-timeout <minutes>
+```
+
+### Arguments
+
+| Argument | Type |
+|----------|------|
+| `minutes` | one |
+
+## `bleep config compile-server idle-timeout-clear`
+
+<p>remove idle timeout setting (use default: 60 minutes)</p>
+
diff --git a/docs/reference/cli/remote-cache/index.mdx b/docs/reference/cli/remote-cache/index.mdx
index 3adc9d458..02f6d4af9 100644
--- a/docs/reference/cli/remote-cache/index.mdx
+++ b/docs/reference/cli/remote-cache/index.mdx
@@ -8,7 +8,7 @@ title: bleep remote-cache
 
 # `bleep remote-cache`
 
-<p>push and pull compiled classes to/from a remote S3-compatible cache</p>
+<p>push and pull compiled classes to/from a build cache (S3-compatible service or local directory)</p>
 
 ## Synopsis
 
@@ -18,6 +18,6 @@ bleep remote-cache <subcommand> [args] [flags]
 
 ## Subcommands
 
-- [`bleep remote-cache pull`](./pull): pull cached compiled classes from remote cache
-- [`bleep remote-cache push`](./push): push compiled classes to remote cache
+- [`bleep remote-cache pull`](./pull): pull cached compiled classes from the cache
+- [`bleep remote-cache push`](./push): push compiled classes to the cache
 
diff --git a/docs/reference/cli/remote-cache/pull.mdx b/docs/reference/cli/remote-cache/pull.mdx
index e725b61af..9a852a417 100644
--- a/docs/reference/cli/remote-cache/pull.mdx
+++ b/docs/reference/cli/remote-cache/pull.mdx
@@ -8,7 +8,7 @@ title: bleep remote-cache pull
 
 # `bleep remote-cache pull`
 
-<p>pull cached compiled classes from remote cache</p>
+<p>pull cached compiled classes from the cache</p>
 
 ## Synopsis
 
diff --git a/docs/reference/cli/remote-cache/push.mdx b/docs/reference/cli/remote-cache/push.mdx
index 2566c2c0d..c7fb64a33 100644
--- a/docs/reference/cli/remote-cache/push.mdx
+++ b/docs/reference/cli/remote-cache/push.mdx
@@ -8,7 +8,7 @@ title: bleep remote-cache push
 
 # `bleep remote-cache push`
 
-<p>push compiled classes to remote cache</p>
+<p>push compiled classes to the cache</p>
 
 ## Synopsis