> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Manager Tools

> Centralized file operations for Genesis. Upload, register, attach, list, read, download, and delete files with one-call Git save and rich metadata.

## **Overview**

### **Tool Name**

```json theme={null}
file_manager_tools
```

### **Purpose**

The **file\_manager\_tools** provide unified file operations across the platform. Use them to upload or register files, attach them to entities like projects or threads, preview large text safely, create download links, and streamline Git to storage workflows with a single call.

#### **Functions Available**

> All items below are **`actions of file_manager_tool`**.

1. `UPLOAD_FILE`: *Upload a new text or binary file and optionally attach it immediately.*
2. `REGISTER_EXISTING_FILE`: *Register a file that already exists on disk so it is tracked by the system.*
3. `REGISTER_FILE_FROM_STORAGE`: *Register a file from a storage path and assign a friendly filename.*
4. `SAVE_FROM_GIT`: *Copy from repo to managed storage, register, and attach in one efficient call.*
5. `LIST_FILES`: *List files with filters such as project, data agent, thread, or index.*
6. `GET_FILE_INFO`: *Return metadata for a file by id.*
7. `GET_FILE_CONTENT`: *Read text content with pagination by lines or characters.*
8. `GET_FILE_BY_PATH`: *Resolve a file record using an absolute storage path.*
9. `ATTACH_FILE`: *Attach a registered file to a specific entity.*
10. `DETACH_FILE`: *Remove an entity association without deleting the file.*
11. `DOWNLOAD_FILE`: *Create a safe download link token for user delivery.*
12. `DELETE_FILE`: *Permanently delete a file.*

### Key Features

<Steps>
  <Step title="Upload and Register" icon="cloud-arrow-up">
    Add new files or register existing ones with rich metadata.
  </Step>

  <Step title="Attach to Entities" icon="paperclip">
    Link files to projects, todos, data agents, threads, messages, or indices for traceability.
  </Step>

  <Step title="Search and Filter" icon="magnifying-glass">
    Find files quickly with scoped filters across related entities.
  </Step>

  <Step title="Read and Preview" icon="file-lines">
    Page through large text or code safely by lines or characters.
  </Step>

  <Step title="Save from Git" icon="code-branch">
    One call to save from repo, register, and attach for fast handoffs.
  </Step>

  <Step title="Share Securely" icon="download">
    Generate expiring download links for stakeholders.
  </Step>
</Steps>

## **Input Parameters for Each Function**

### **`file_manager_tool`**

#### `UPLOAD_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `UPLOAD_FILE`. | String |
| **filename** | Descriptive filename. | String |
| **text\_content** | Plain text content to store. | String |
| **content** | Base64 payload for binaries. | String |
| **mime\_type** | MIME type for correct handling. | String |
| **entity\_type** | Entity to attach on upload. | String |
| **entity\_id** | Target entity id. | String |

<Tip>
  Use descriptive filenames that encode purpose, owner, and date to improve discoverability in `LIST_FILES`.
</Tip>

#### `LIST_FILES`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `LIST_FILES`. | String |
| **filters** | Filter object. Start with `{"bot": "<bot_id>"}` or a project id. | Object |

#### `GET_FILE_INFO`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `GET_FILE_INFO`. | String |
| **file\_id** | Unique file identifier. | String |

#### `GET_FILE_CONTENT`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `GET_FILE_CONTENT`. | String |
| **file\_id** | Unique file identifier. | String |
| **pagination\_mode** | `lines`, `chars`, or `null` for chunk based. | String |
| **start** | Zero based offset for the chosen mode. | Integer |
| **count** | Number of lines or chars to return. | Integer |

<Note>
  Prefer `pagination_mode: "lines"` for code or SQL, and `pagination_mode: "chars"` for prose or logs to keep previews snappy.
</Note>

#### `GET_FILE_BY_PATH`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `GET_FILE_BY_PATH`. | String |
| **file\_path** | Absolute storage path to resolve. | String |

#### `REGISTER_FILE_FROM_STORAGE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `REGISTER_FILE_FROM_STORAGE`. | String |
| **filename** | Friendly filename to display. | String |
| **file\_path** | Path to file in storage. | String |

#### `REGISTER_EXISTING_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `REGISTER_EXISTING_FILE`. | String |
| **file\_path** | Absolute path to existing file. | String |
| **filename** | Descriptive filename. | String |

#### `ATTACH_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `ATTACH_FILE`. | String |
| **file\_id** | File to attach. | String |
| **entity\_type** | One of `project` `todo` `asset` `bot` `thread` `message` `index`. | String |
| **entity\_id** | Target id for the attachment. | String |

#### `DETACH_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `DETACH_FILE`. | String |
| **file\_id** | File to detach. | String |
| **entity\_type** | Entity type to remove. | String |
| **entity\_id** | Target id to remove from. | String |

#### `DOWNLOAD_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `DOWNLOAD_FILE`. | String |
| **file\_id** | File to create a download link for. | String |

#### `DELETE_FILE`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `DELETE_FILE`. | String |
| **file\_id** | File to remove permanently. | String |

#### `SAVE_FROM_GIT`

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Must be `SAVE_FROM_GIT`. | String |
| **source\_path** | Absolute path to the repo file. | String |
| **target\_path** | Destination directory in managed storage. | String |
| **target\_filename** | Optional new filename. | String |
| **commit\_message** | Optional provenance message. | String |
| **entity\_type** | Entity to auto attach. | String |
| **entity\_id** | Target entity id. | String |

<Warning>
  \*\*Deletion is permanent. \*\*Confirm backups or retention requirements before calling `DELETE_FILE`.
</Warning>

## **Use Cases**

1. **Project evidence**
   * Attach specs and extracts to a project for review and sign off.
2. **Repo handoff**
   * Save a generated PDF from repo to storage and attach it to the current thread.
3. **Inventory discovery**
   * List and filter files by project or data agent to locate the latest assets quickly.
4. **Large log review**
   * Page through big SQL logs without loading the entire file.
5. **Stakeholder delivery**
   * Generate a download link for stakeholders to retrieve a produced report.

## **Workflow/How It Works**

1. Upload or register files with `UPLOAD_FILE` or `REGISTER_*`.
2. Attach to the relevant entity with `ATTACH_FILE` for context.
3. Explore inventory via `LIST_FILES` and fetch metadata using `GET_FILE_INFO`.
4. Preview text safely with `GET_FILE_CONTENT` and pagination.
5. Share externally with `DOWNLOAD_FILE`.
6. Retire artifacts with `DETACH_FILE` or `DELETE_FILE` when the lifecycle is complete.

## **Integration Relevance**

* **git\_action** to source inputs and save binaries with `SAVE_FROM_GIT`.
* **project\_manager\_tools** to keep artifacts tied to missions and todos.
* **document\_index\_tools** to index stored files for search and Q\&A.
* **artifact\_manager\_tools** for generated outputs that later become managed files.
* **google\_drive\_tools** to export results and then register or attach them.

## **Configuration Details**

* Use absolute paths for registration and ensure read or write permissions.
* Base64 encode binary payloads for `UPLOAD_FILE`.
* Choose precise MIME types for correct rendering and preview behavior.
* Filter hierarchically when listing files to avoid noisy result sets.
* Adopt clear filename conventions that encode purpose and entity context.

## **Limitations or Notes**

1. Very large files may hit upload or storage limits depending on policy.
2. Git operations require network access and repo permissions.
3. Entity attachments will fail if the target id is invalid.
4. Binary corruption can occur if payloads are not base64 encoded correctly.
5. Concurrent writes or deletes may require coordination to avoid conflicts.

### **Output**

* **Upload and Registration**: File id, metadata summary, and storage location.
* **Lists and Info**: Arrays of file records with names, sizes, MIME, timestamps, and relationships.
* **Content Preview**: Text segments plus pagination fields `start`, `count`, `actual_count`, `has_more`.
* **Attachments**: Confirmation of attach or detach operations.
* **Git Save**: Commit info, registration details, and attachment confirmation.
* **Download**: Download token or path reference.
* **Errors**: Descriptive messages with remediation guidance.