# share_file

Make a file available to the user as a direct download link.

## When to call

Call this any time you produce a file the user will want to keep:
- Archives (.zip, .tar.gz)
- Generated documents (.pdf, .docx, .csv, .json)
- Built binaries or packages
- Any output file created by terminal, code_exec, or filesystem

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `path` | yes | **Absolute** path to the file on disk |
| `filename` | no | Clean download name shown to the user (defaults to the original filename) |

## Critical: path must be absolute

`path` must be an absolute filesystem path. A relative path like `game_project.zip` or `workspace/report.csv` will fail or resolve to the wrong location.

### How to get the absolute path

**Option 1** — you just wrote the file with `filesystem` or `terminal`, you know the full path:
```
path: "/home/gmikcon/Projects/navi-1/workspace/game_project.zip"
```

**Option 2** — you only have a relative path, resolve it first:
```
terminal(command="realpath game_project.zip")
# → /home/gmikcon/Projects/navi-1/game_project.zip
```

**Option 3** — use `filesystem(action="info", path="workspace/game_project.zip")` — the result includes the absolute path.

## What to do with the result

On success the tool returns:
```
Download ready: game_project.zip (4.2 MB)
URL: http://server:8000/sessions/abc123/files/game_project.zip
```

**You must include the URL in your reply to the user.** Format it as a markdown link:

```
Here's your file: [game_project.zip](http://server:8000/sessions/abc123/files/game_project.zip)
```

Do not just say "the file is ready" without the link. The user cannot find the URL themselves.

## Full example

```
# 1. Create the archive
terminal(command="cd /home/gmikcon/Projects && zip -r /tmp/game_project.zip game_project/")

# 2. Share it — use the absolute path from step 1
share_file(path="/tmp/game_project.zip", filename="game_project.zip")

# 3. In your reply:
"Here's the archive: [game_project.zip](http://...)"
```

## Common mistakes

| Wrong | Right |
| --- | --- |
| `path: "game_project.zip"` | `path: "/home/gmikcon/Projects/navi-1/game_project.zip"` |
| `path: "workspace/report.csv"` | `path: "/home/gmikcon/Projects/navi-1/workspace/report.csv"` |
| Saying "the file is ready" without the link | Posting the URL as a markdown link |