File System

# File System Skillpack

Use this tool family when you need a private per-user file workspace for documents, notes, JSON files, exports, uploads, or binary assets.

## What it is

- Every user gets their own private file root on disk.
- All paths are relative to that user root.
- Users can create folders, read and write files, move them, copy them, and delete them.
- The tool blocks path traversal outside the user root.

## View in the Clono app

JSON responses include **`viewInAppUrl`**: the same Files browser URL as **View Files** in the UI (with `?path=` when relevant). Share it when the user may want to browse or preview in the dashboard.

## Core operations

- `files.info`
- `files.exists`
- `files.list`
- `files.mkdir`
- `files.read_text`
- `files.write_text`
- `files.read_base64`
- `files.write_base64`
- `files.move`
- `files.copy`
- `files.delete`

## When to use File System vs Database

- Use `files` for actual documents, exports, prompts, JSON blobs, images, PDFs, or arbitrary binary content.
- Use `database` for structured relational data that you want to query with SQL.

## Recommended workflow

1. Use `files.info` or `files.list` to inspect the workspace.
2. Use `files.mkdir` before writing into a new directory structure.
3. Use `files.write_text` for text, markdown, JSON, CSV, and code-like content.
4. Use `files.write_base64` for binary content.
5. Use `files.read_text` or `files.read_base64` to retrieve stored content later.
6. Use `files.move`, `files.copy`, and `files.delete` to manage files and folders.

## Large-result behavior

- `files.read_text` returns inline text for normal-sized files.
- If a text read is too large for a safe inline response, Clono returns an inline preview plus artifact metadata with a `downloadPath`.
- `files.read_base64` returns inline base64 for smaller files.
- If a binary read is too large for a safe inline response, Clono returns artifact metadata with a `downloadPath` instead of a huge base64 blob.

## Good agent behavior

- Prefer descriptive folder structures instead of dumping everything into the root.
- Use text files for human-readable notes and metadata.
- Use the database tool to index or catalog files when structured lookup is useful.
- Avoid deleting directories recursively unless you are sure the user wants that content removed.

## Example

1. `files.mkdir`
   - path: `exports/reports`
2. `files.write_text`
   - path: `exports/reports/summary.md`
   - content: markdown text
3. `files.list`
   - path: `exports`
4. `files.read_text`
   - path: `exports/reports/summary.md`