[Bug]: Container machine docs disagree on the home directory path
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
The new container machine docs describe the home directory in two different ways.
### What I found
In `docs/container-machine.md`, the first section says:
```text
Your repo lives in $HOME on macOS and is mounted at /Users/ inside the container machine.
```
But the quickstart right below it says:
```bash
container machine run -n dev pwd # /home/ — your Mac home dir, mounted in
```
Those two paths point users in different directions:
- `/Users/` sounds like the macOS path is preserved inside the Linux machine
- `/home/` sounds like a normal Linux home directory
### What the code seems to do
The implementation and tests point to `/home/` as the machine user's home.
`Sources/Services/MachineAPIService/Client/MachineConfiguration.swift`:
```swift
public var home: String {
"/home/\(username)"
}
```
The CLI test also checks for that exact path:
```swift
#expect(home == "/home/\(hostUsername)", "HOME should be set to /home/")
```
### Expected
The docs should use one clear story for this.
Something like:
```text
Your macOS home is shared into the container machine and exposed as the Linux user's home at /home/.
```
That keeps the docs aligned with the code and avoids users looking for their files under `/Users/` inside the machine.
### Why this matters
Container machines are meant to feel like a persistent Linux dev environment. The first thing users will check is `pwd`, `$HOME`, and where their repo is mounted. If the docs mention both `/Users/` and `/home/`, it is easy to think the mount is broken when it is actually just the doc wording.
Contributor guide
Research direction
Start with docs/container-machine.md and compare its first section with the quickstart example. Use Sources/Services/MachineAPIService/Client/MachineConfiguration.swift and the cited CLI test to verify the documented home path. Done means the documentation consistently explains that the macOS home is exposed as /home/ inside the machine.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100