---
yatl_version: 1
title: 'Docs: Document @path vs @command disambiguation logic'
id: 137fkdy1
created: 2026-01-28T04:41:04.117280Z
updated: 2026-01-28T04:48:33.529569Z
author: Brian McCallister
priority: medium
tags:
- docs
- hosts.rs
---

In hosts.rs:50-65, there's subtle logic for determining whether `@path_or_cmd` should be treated as a file path or a shell command:

```rust
Some(s) if s.starts_with('@') => {
    let path_or_cmd = &s[1..];
    let path = Path::new(path_or_cmd);

    let content = if path.exists() {
        // If path exists, read it or execute it (if executable)
        if is_executable(path)? {
            execute_script(path)?
        } else {
            fs::read_to_string(path)?
        }
    } else {
        // If path doesn't exist, treat as shell command
        run_shell_command(path_or_cmd)?
    }
    ...
}
```

**Problem**: This logic is non-obvious:
1. First checks if path exists as a file
2. If exists and executable -> execute it
3. If exists but not executable -> read as file
4. If doesn't exist -> treat as shell command

This means `@ls` would run the shell command `ls` (because no file named "ls" exists in CWD), but `@./ls` would execute `./ls` if it exists.

**Suggestion**: Add a doc comment explaining this disambiguation logic and its rationale.

---
# Log: 2026-01-28T04:41:04Z Brian McCallister

Created task.

---
# Log: 2026-01-28T04:48:33Z Brian McCallister

Closed: Added detailed comments explaining @path vs @command disambiguation logic
