# Proposal: ~ / $HOME Expansion in Mount Paths

## Context

Users want to write mount target paths like `~/workspace` or `$HOME/workspace` instead of absolute paths like `/home/user/workspace` or `/root/workspace`. Docker Compose does not expand these — they must be resolved before writing the compose file.

## Goal

Resolve `~` and `$HOME` in container target paths to the correct home directory for the target container.

## Direction

**Manifest-aware home directory (Option B)**
- Extract `user.name` from the tool manifest to compute `/home/{name}`
- For root-based manifests (no user block), use `/root`
- For legacy tool types (non-manifest), default to `/root`
- Apply expansion at compose generation time for both regular mounts and git mount targets
- Also set `HOME` env var in the Dockerfile for runtime compatibility

## Acceptance Criteria

1. `~` in a mount target path is expanded to the container's home directory
2. `$HOME` in a mount target path is expanded to the container's home directory
3. For manifest-based tools with `user.name`, home is `/home/{user.name}`
4. For manifest-based tools without user block, home is `/root`
5. For legacy tool types, home is `/root`
6. Git mount `mapping.target_path` also supports `~` and `$HOME`
7. `HOME` env var is set in generated Dockerfile
8. No frontend changes needed (users type `~`, backend resolves it)

## Out of Scope

- `~` expansion in host-side source paths
- `~` expansion in mount file relative paths
- `~user` syntax (e.g., `~alice`)

## Risks

| Risk | Mitigation |
|------|------------|
| Wrong home for custom containers | Document that manifest should declare `user.name` |
| `$HOME` env var not set in container | Set it in Dockerfile via `ENV HOME=...` |

## Related Artifacts

- Exploration: `openspec/explorations/home-path-expansion.md`
- Spec: `openspec/specs/home-path-expansion.md`
- Design: `openspec/designs/home-path-expansion.md`
- Tasks: `openspec/tasks/home-path-expansion.md`