docs(run): document that scripts and commands run from the project root

[mikeland73]

Summary

devbox run always executes from the project's root directory — the directory
containing devbox.json — regardless of the subdirectory it was invoked from.
This is enforced in nix.RunScript, which sets cmd.Dir = projectDir
(internal/nix/run.go). Users invoking devbox run from a subdirectory are
surprised that pwd and relative paths resolve against the project root rather
than the current working directory, as reported in #2559.

A maintainer confirmed on the issue that this is intentional: it keeps a command
run via devbox run -- <cmd> consistent with a script defined in devbox.json,
which should always run from the same place. The reporter's remaining ask was
simply that this behavior be surfaced in the command's help.

This PR adds a short paragraph to the devbox run long help explaining that
scripts and commands run from the project root and showing how to run from a
subdirectory when needed:

Scripts and commands always run from the project's root directory (the directory
containing your devbox.json), not the current working directory. If you invoke
devbox run from a subdirectory and need to run there, change into it as part of
your command, e.g. devbox run -- sh -c 'cd subdir && <command>'.

No behavior changes — documentation only.

Closes #2559

cc @alezkv (issue reporter) — thanks for raising this.

How was it tested?

• go build ./internal/boxcli/ and gofmt -l internal/boxcli/run.go are clean.
• Ran devbox run --help and confirmed the new paragraph renders correctly in
  the long description, above the usage/examples output.

Community Contribution License

All community contributions in this pull request are licensed to the project
maintainers under the terms of the
Apache 2 License.

By creating this pull request, I represent that I have the right to license the
contributions to the project maintainers under the Apache 2 License as stated in
the
Community Contribution License.

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[mikeland73]

@claude please review this PR for correctness, and flag anything that would block merging.

[claude]

Claude finished @mikeland73's task in 1m 10s —— View job

---

Review: docs(run) — scripts/commands run from project root

• Gather context (diff, related code)
• Review for correctness
• Post findings

Summary: This is a documentation-only change to the devbox run long help text, and it's correct.

Verification:

• internal/nix/run.go:31 unconditionally sets cmd.Dir = projectDir — confirms the new help text's claim.
• Both code paths in (*Devbox).RunScript (internal/devbox/devbox.go:262) — running a named script (internal/devbox/devbox.go:308-311) and running an arbitrary command (internal/devbox/devbox.go:312-331) — funnel through the same nix.RunScript, so the "scripts and commands always run from the project root" claim applies uniformly to both cases, not just scripts.
• The suggested workaround (devbox run -- sh -c 'cd subdir && <command>') is sound: since cmd.Dir is the project root and the command is executed via sh -c, cd subdir inside that shell correctly relocates relative to the project root before running <command>.
• String formatting/concatenation in internal/boxcli/run.go (lines 48-55) is well-formed Go and consistent with the existing style (backtick-quoted identifiers, trailing \n\n before Example).
• No behavior change — matches the stated intent and closes Question: Why is PWD ignored when using devbox run? #2559 per the maintainer's confirmation that this is intentional/by-design.

Nothing blocking merge. One very minor, non-blocking nit: the new paragraph says "your devbox.json" while the sentence before it says "in devbox.json" — inconsistent possessive vs. bare reference, but purely stylistic and not worth holding up the PR for.

I wasn't able to run go build/gofmt in this sandbox (tool approval required for build commands), but the change is a pure string-literal addition with no syntax risk, and the PR description already confirms clean build/gofmt/manual --help verification.

[mikeland73]

Reviewed for correctness and merge-readiness.

Correctness — looks good ✅

This is a documentation-only change (+5/−1 in internal/boxcli/run.go): it appends one paragraph to the devbox run long help. No code paths change.

• The documented behavior is accurate. devbox run executes from the project root because nix.RunScript sets cmd.Dir = projectDir (internal/nix/run.go:31), and Devbox.RunScript passes d.projectDir into it (internal/devbox/devbox.go:340). The claim "scripts and commands always run from the directory containing your devbox.json" matches the implementation.
• Local checks pass: go build ./internal/boxcli/, go vet ./internal/boxcli/, and gofmt -l internal/boxcli/run.go are all clean.
• Help renders correctly: devbox run --help shows the new paragraph in the long description, above usage/examples.
• No test is needed — help strings aren't unit-tested in this repo, and there's no behavior to cover.

What would block merging

1. The PR is currently a draft (converted by @savil). A draft can't be merged, and GitHub won't restore any auto-merge/merge-queue membership when it's marked ready. I've intentionally left it as a draft rather than re-readying it, since a maintainer set that state. Say the word and I'll mark it ready for review.
2. mergeable_state: blocked — required checks haven't reported yet (status is pending, 0 checks) and branch protection likely also needs a maintainer approval. Nothing actionable on the diff; it just needs CI to run and a review once it's out of draft.

Minor, optional (non-blocking)

The cd subdir in the example is illustrative — the subdirectory a user invokes from won't literally be named subdir relative to the project root. If you'd like it less ambiguous I can reword to something like devbox run -- sh -c 'cd path/relative/to/project/root && <command>', but it reads fine as-is.

Net: the change itself is correct and safe to merge; the only real blocker is the draft state.

---

Generated by Claude Code