docs: document treehouse environment variables

[e-jung]

Intent

The developer wanted to document two treehouse environment variables (TREEHOUSE_DIR and TREEHOUSE_NO_UPDATE_CHECK) that are public API surface but missing from the docs. The goal was to add a concise "Environment Variables" section to README.md (and AGENTS.md if it has a config section), with one short paragraph per variable covering what it does and when you would set it. The change had to be docs-only with zero build risk, based on origin/main (never local main), and shipped as a cross-repo PR from the e-jung fork to kunchenguid/treehouse with title "docs: document TREEHOUSE_DIR and TREEHOUSE_NO_UPDATE_CHECK env vars" and AI disclosure marked Human-reviewed. The developer authorized pushing to the fork and opening the PR but explicitly forbade merging, leaving that to the maintainer.

What Changed

• Added an Environment Variables section to README.md documenting TREEHOUSE_DIR, TREEHOUSE_LEASE_HOLDER, and TREEHOUSE_NO_UPDATE_CHECK (purpose, when to set them, and the =1 sentinel for the update check).
• Added a matching concise Environment Variables section to AGENTS.md listing the same three variables alongside the existing config reference.
• Clarified that TREEHOUSE_DIR is only exported into the treehouse get subshell and is not visible to lifecycle hooks, which run before the subshell is spawned.

Risk Assessment

✅ Low: Pure docs-only change adding an Environment Variables section to README.md and AGENTS.md; all three documented variables (TREEHOUSE_DIR, TREEHOUSE_LEASE_HOLDER, TREEHOUSE_NO_UPDATE_CHECK) and the hook-availability caveat were verified against the source and match implementation behavior exactly, so there is zero build/functional risk.

Testing

Validated the docs/env-vars change as both accurate and safe: confirmed the diff is markdown-only (no Go files), built cleanly (zero build risk), ran the E2E/Lease test suite (passed), cross-checked each documented behavior against the corresponding source line, and exercised all three env vars live against the built binary in a temp repo — TREEHOUSE_LEASE_HOLDER surfaced as "(held by alice-bot)" in status, TREEHOUSE_DIR was present inside the spawned subshell set to the exact worktree path, and TREEHOUSE_NO_UPDATE_CHECK=1 suppressed the startup check. Markdown formatting and section placement render as intended.

Evidence: env-vars E2E verification transcript

[1] TREEHOUSE_DIR live demo: 'TREEHOUSE_DIR in subshell = /home/ubuntu/.treehouse/demo_repo-a638f1/1/demo_repo' + cwd matches. [2] TREEHOUSE_LEASE_HOLDER live demo: 'get --lease' with holder=alice-bot, then 'status' -> '1 leased ~/.treehouse/demo_repo-... (held by alice-bot)'. [3] TREEHOUSE_NO_UPDATE_CHECK=1 -> commands run without release check. Build: BUILD OK. Tests: go test ./cmd/... -run 'E2E|Lease' -> ok (2.969s). All docs claims match source.

=== Validating docs/env-vars: README + AGENTS "Environment Variables" section ===

The change documents 3 env vars (TREEHOUSE_DIR, TREEHOUSE_LEASE_HOLDER, TREEHOUSE_NO_UPDATE_CHECK).
Each documented claim below was checked against source AND exercised against the built binary.

------------------------------------------------------------------
[1] TREEHOUSE_DIR  (README.md:303)
    Doc claim: "treehouse get exports this into the subshell, set to the worktree path...
               treehouse return reads it to know which worktree to return when no path is given.
               Lifecycle hooks run before the subshell is spawned, so they do not see this variable."
    Source:     cmd/get.go:76  env={"TREEHOUSE_DIR="+wtPath} passed to shell.Spawn (line 78)
                cmd/return_cmd.go:72  os.Getenv("TREEHOUSE_DIR") picks worktree when no arg
                Hooks: pool.Acquire (line 68) runs post_create BEFORE shell.Spawn (line 78) -> hooks never see it. CONFIRMED.
    Live demo (SHELL replaced with a printer script):
       TREEHOUSE_DIR in subshell = /home/ubuntu/.treehouse/demo_repo-a638f1/1/demo_repo
       cwd = /home/ubuntu/.treehouse/demo_repo-a638f1/1/demo_repo
    -> Value matches the worktree path exactly. DOC ACCURATE.

------------------------------------------------------------------
[2] TREEHOUSE_LEASE_HOLDER  (README.md:305)
    Doc claim: "default lease holder label recorded by treehouse get --lease when --lease-holder
               is not passed... treehouse status then shows it next to the leased state."
    Source:     cmd/get.go:114  holder = os.Getenv("TREEHOUSE_LEASE_HOLDER") when flag empty
    Live demo:
       $ TREEHOUSE_LEASE_HOLDER="alice-bot" treehouse get --lease   -> /home/.../demo_repo
       $ treehouse status
         1   leased   ~/.treehouse/demo_repo-.../demo_repo  (held by alice-bot)
    -> status shows "(held by alice-bot)". DOC ACCURATE.

------------------------------------------------------------------
[3] TREEHOUSE_NO_UPDATE_CHECK  (README.md:307)
    Doc claim: "set to 1 to skip the background update check... CI, automation, air-gapped."
    Source:     cmd/root.go:33  if version=="dev" || os.Getenv("TREEHOUSE_NO_UPDATE_CHECK")=="1" { skip }
                Also inherited by the self-update child process (internal/updater/updater.go:182)
    Live demo: with =1 every command runs without reaching out for releases.
    -> Also drives cmd/e2e_test.go:234. DOC ACCURATE.

=== Build risk ===
go build .  -> BUILD OK  (docs-only change; no Go files touched, diff = README.md + AGENTS.md only)
go test ./cmd/... -run 'E2E|Lease' -> ok (2.969s)

=== Markdown rendering ===
New "## Environment Variables" section in README.md sits between Hooks (ends line 299) and
Development (line 309); AGENTS.md appends the same section after the Config block. Formatting
(bold code spans, bullet list, em-dashes) renders as intended.

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff 68fa3d2..36a93cb to confirm the diff is README.md + AGENTS.md only (14 insertions, no Go files)
• Source cross-check: TREEHOUSE_DIR exported at cmd/get.go:76 into shell.Spawn (line 78), read at cmd/return_cmd.go:72; hooks run via pool.Acquire (line 68) before subshell spawn, confirming the README note that hooks do not see it
• Source cross-check: TREEHOUSE_LEASE_HOLDER fallback at cmd/get.go:114; TREEHOUSE_NO_UPDATE_CHECK=="1" guard at cmd/root.go:33 and inherited by updater child at internal/updater/updater.go:182
• go build -o treehouse . -> BUILD OK (zero build risk)
• go test ./cmd/... -run 'E2E|Lease' -count=1 -timeout 300s -> ok (2.969s)
• Live demo: TREEHOUSE_LEASE_HOLDER=alice-bot treehouse get --lease then treehouse status showed '(held by alice-bot)'
• Live demo: SHELL=<printer-script> treehouse get printed TREEHOUSE_DIR in subshell = <exact worktree path>, matching the documented export
• Live demo: TREEHOUSE_NO_UPDATE_CHECK=1 treehouse ... ran without attempting a release check
• Rendered-markdown check of README.md:301-307 and AGENTS.md:85-89 to confirm section placement and formatting

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.