CLAUDE.md: fix msf completion regen, gem paths are mandatory

The extract-to-tmp generator command as documented never worked on its
own. The embedded ruby has /opt/metasploit-framework baked in as its
prefix, so bundler resolves gems there regardless of the extract dir and
fails with Bundler::GemNotFound. It only appeared to work when a host
install sat at that path, which also meant it read the installed version
rather than the one being packaged.

Add the required GEM_HOME/GEM_PATH/BUNDLE_GEMFILE, note that the ruby
version in the gem path moves on upstream bumps, and drop the advice to
fall back to a live /opt install.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 29 insertions, 6 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index bd7d9a8..0b50ab4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -101,8 +101,21 @@ running ruby at build time (hermetic build, no build-time dep).
 **Regenerate it on every version bump.** No host install needed: `test-build
 --keep` produces a `.txz`; extract it to a scratchpad dir and run the
 generator against the *extracted* framework's bundled ruby. This avoids `sudo
-installpkg` and is fully in Claude's hands (verified identical output to a
-host install, 2026-07-30).
+installpkg` and is fully in Claude's hands.
+
+**The `GEM_HOME`/`GEM_PATH`/`BUNDLE_GEMFILE` vars below are mandatory.** The
+embedded ruby has `/opt/metasploit-framework` baked in as its prefix, so
+bundler resolves gem paths there no matter where the tree was extracted, and
+the run dies with:
+
+```
+Could not find metasploit-payloads-X, rex-socket-X, ... in locally installed
+gems (Bundler::GemNotFound)
+```
+
+Pointing the gem vars at the extracted tree fixes it. Note `3.4.0` in that
+path is the embedded **ruby version** and moves when upstream bumps ruby;
+check `$FW/embedded/lib/ruby/gems/` if the path is wrong.
 
 ```bash
 KEPT=/data/sbo-test-build/kept/metasploit-framework-bin-$VERSION-x86_64-*.tgz
@@ -110,14 +123,23 @@ tar xf $KEPT -C $SCRATCH/msf-extract
 FW=$SCRATCH/msf-extract/opt/metasploit-framework
 curl -o $SCRATCH/gen.rb \
   https://gitlab.com/kalilinux/packages/metasploit-framework/-/raw/kali/master/debian/generate-msfvenom-bash-completion.rb
+cd $FW/embedded/framework
+GEM_HOME=$FW/embedded/lib/ruby/gems/3.4.0 \
+GEM_PATH=$FW/embedded/lib/ruby/gems/3.4.0 \
+BUNDLE_GEMFILE=$FW/embedded/framework/Gemfile \
 $FW/embedded/bin/ruby \
   -I$FW/embedded/framework/lib $SCRATCH/gen.rb \
   > metasploit-framework-bin/msfvenom.bash-completion
 ```
 
-(If `/opt/metasploit-framework` happens to already be live from a host
-install, running the generator against that works too and gives byte-identical
-output.)
+**Do not fall back to running the generator against a live
+`/opt/metasploit-framework`.** Without the gem vars the extracted-tree run
+only appears to work when a host install happens to sit at that path, and it
+then reads the *installed* version, silently emitting completion data for
+whatever is on the host rather than the version being packaged. That is how
+the 2026-07-30 "byte-identical, no host install needed" claim was reached; it
+was actually reading a host install. Corrected 2026-08-07 during the 6.5.1
+bump, where the host `/opt` still held 6.4.147.
 
 Verify the output is non-empty and the `%s` slots were filled (grep for real
 payload names like `windows/meterpreter`), then commit it with the bump.
@@ -171,7 +193,8 @@ from the configured SBo tree, builds in a `--rm` container, and lints with
 `sbopkglint`. Use `--keep` to copy the built `.txz` out (e.g. a binary repack
 like `metasploit-framework-bin` whose post-install artifacts are regenerated by
 extracting the kept `.txz` and running the generator against it, no host
-install). See `../sbo-dockerbuild` for the full tool and its image-builder
+install, but see the gem-path gotcha in the msfvenom bash-completion section
+above). See `../sbo-dockerbuild` for the full tool and its image-builder
 chain.
 
 The one artifact worth keeping from a clean bump is the **SBo submission