# share_file

Copy an existing local file into the current session directory and return a direct download link.

`share_file` and `content_publish` are different tools:

- `share_file` = copy a local file into `session_files/{session_id}/` + return a download link.
- `content_publish` = register a file that is already in `session_files/{session_id}/` + show it as an inline viewer/card.

Use `share_file` when the user should keep/download the file. Use `content_publish` when the user should inspect it directly in chat.

## 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

Do not use this just to create an inline preview. For SVG/HTML/PDF/image/video/STL preview cards, put the file in the session directory and call `content_publish`.

## How it works

1. Takes an **absolute** source path.
2. Copies that file into the current session directory: `session_files/{session_id}/` by default.
3. If the target filename already exists, creates a numbered filename instead of overwriting.
4. Returns a URL: `/sessions/{session_id}/files/{filename}`.
5. The original source file remains unchanged.

Maximum file size: `SHARE_FILE_MAX_SIZE_MB`, default `1024` MB (1 GB).

## 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` is rejected.

### 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 |
| Calling `share_file` for an inline SVG/HTML preview | Put the file in session dir and call `content_publish` |