diff --git a/README.md b/README.md
index 3308beb..a0b944b 100644
--- a/README.md
+++ b/README.md
@@ -175,7 +175,7 @@ the project-vs-bundle MCP diff.
 umbel list                              # scope-grouped bundle table
 umbel show [name]                       # resolved manifest + sources + MCP diff
 umbel build [name] [--no-cache]         # warm cache, print path
-umbel apply [name] [--vanilla]          # pin <project>/.umbel-bundle (--vanilla = pin "no bundle")
+umbel apply [name] [--vanilla]          # pin <project>/.umbel-bundle + warm cache (--vanilla = pin "no bundle")
 umbel unpin                             # remove the pin
 umbel run [name] [-- ...claude args]    # launch claude (bundle if name/pin, vanilla otherwise)
 umbel init                              # multi-step authoring wizard
@@ -186,6 +186,12 @@ umbel shim path                         # print the shim's absolute path
 umbel skills [options]                  # low-level skill installer (v0 picker)
 ```
 
+`apply` also **builds** the chosen bundle as a side effect: it warms the
+cache and atomically updates the `by-name/<name>` symlink, then prints a
+`built <path>` line beside the `pinned …` line, so a subsequent plain
+`umbel run` launches without a rebuild. (`apply --vanilla` only writes the
+pin — it builds nothing.)
+
 When invoked without `[name]` on a TTY, `run` / `apply` / `show` / `build`
 open a picker — **full** or **scoped**, depending on the pin:
 
diff --git a/docs/bundles-spec.md b/docs/bundles-spec.md
index a8e2d72..f956b22 100644
--- a/docs/bundles-spec.md
+++ b/docs/bundles-spec.md
@@ -409,8 +409,11 @@ it only appears if `__vanilla__` is listed.
 **Candidates are not pre-built.** Each builds lazily on first pick or
 non-interactive resolution (the existing `building bundle 'X'…` notice).
 
-`umbel apply <name>` writes a single-candidate bundle pin. `umbel apply --vanilla`
-writes the `__vanilla__` sentinel. `umbel unpin` removes the file entirely.
+`umbel apply <name>` builds the bundle — warming the cache and atomically
+updating the `by-name/<name>` symlink, and printing a `built <path>` line
+beside the `pinned …` line — then writes a single-candidate bundle pin.
+`umbel apply --vanilla` writes the `__vanilla__` sentinel (no build).
+`umbel unpin` removes the file entirely.
 `umbel apply` refuses (exit 2, hint to run `umbel unpin` first) to overwrite an
 existing multi-candidate pin — multi-candidate pins are hand-authored. The
 bundle-name regex (`^[a-z][a-z0-9-]{1,40}$`) rejects underscores so the
@@ -658,7 +661,7 @@ project's own `.mcp.json` is additive rather than hidden.
 
 ```
 umbel run    [<name>] [--no-cache] [-- ...args]   # exec claude
-umbel apply  [<name>] [--vanilla]                 # write pin (--vanilla = pin "no bundle")
+umbel apply  [<name>] [--vanilla]                 # build + write pin (--vanilla = pin "no bundle", no build)
 umbel unpin                                       # remove pin
 umbel list                                        # table
 umbel show   [<name>]                             # resolved view