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

# Files

> Bring documents, spreadsheets, and images into ClarityQ so the agent can use them.

Files let you give the agent knowledge that doesn't live in your warehouse. Upload a CSV of extra data, a catalog you maintain in a spreadsheet, a PDF of business definitions, or an image of a dashboard you want to replicate — and the agent can use it when it answers.

Files work in both directions. You can bring files in, and you can ask the agent to produce them: a CSV of results, a PDF summary, and other formats it can generate in the chat.

## Two Ways to Bring a File In

Where you put a file decides how long it lasts and who else benefits from it.

|                   | **Context Layer files**                         | **Chat attachments**                    |
| ----------------- | ----------------------------------------------- | --------------------------------------- |
| Where you add it  | The **Files** page                              | The chat composer                       |
| How long it lasts | Permanently, across every session               | That conversation only                  |
| Who can use it    | You, or everyone in the workspace once approved | Just that chat                          |
| Use it for        | Reference data the agent should always know     | A one-off file relevant to one question |

The rest of this page is about Context Layer files. For attaching a file to a single conversation — and for asking the agent to generate one — see [Files in a Chat](/ask-anything/asking-questions#files-in-a-chat).

## The Files Page

Files live under **Context Layer → Files** in the sidebar. The table lists each file with its **File name**, **Size**, **Description**, **Uploaded by**, **Last Modified**, and **Status**.

You can search by name or description, and filter by uploader or status. The uploader filter starts set to **you**, so you see your own files first — clear it to see everything in the workspace.

A capacity bar shows how much of your workspace's file storage is used, broken down by approved, private, and excluded files.

## Uploading Files

Click **Upload file**, or drag files onto the table.

Supported formats:

* **Documents** — PDF, Word (DOCX), OpenDocument (ODT), RTF, EPUB, PowerPoint (PPTX)
* **Text** — Markdown, TXT, HTML
* **Data** — CSV, TSV, JSON, Excel (XLSX)
* **Images** — JPEG, PNG, GIF, WEBP

Limits:

* **50 MB** per file
* **10 files** per upload
* **5 GB** total per workspace by default — your workspace may be configured with a different capacity

Uploads run one at a time, and a progress toaster tracks them. You can keep working while they finish, and cancel any that haven't started.

## Descriptions Make Files Discoverable

A file's description is how the agent decides whether the file is relevant to a question. This matters more than anything else on this page.

For text-based files, ClarityQ reads the file and **generates a description automatically**. While that's happening the row shows as processing.

For files it can't read as text — images, mostly — a **wizard opens after your upload finishes** and asks you to describe each one. You can step through them, or skip: a file with no description simply won't be found automatically, though you can still bring it into a chat by `@mentioning` it by name.

You can edit any description later from the Description column.

## File Statuses

Every file has one of three statuses. New uploads always start as **Private**.

| Status       | What it means                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Private**  | The agent uses it only in *your* chats.                                                                                                          |
| **Approved** | Part of the shared workspace context — the agent uses it for everyone with access to the workspace.                                              |
| **Excluded** | Hidden from the agent entirely. It stays on the Files page and still counts toward your storage capacity, and you can re-include it at any time. |

**Downloading** is narrower than seeing the row. Anyone who can see an **Approved** file can download it. A **Private** file's contents stay with the person who uploaded it — admins included.

<Note>
  A private file's *contents* are restricted to its uploader, but its **row is visible to everyone in the workspace** — name, description, size, and who uploaded it. Treat "private" as controlling who can open the file, not who can see that it exists. Don't upload a file whose *name* or *description* is itself sensitive.
</Note>

There are two exceptions where someone else can download a private file — both cases where you already handed it over deliberately: when you `@mentioned` it in a chat you shared, and when you `@mentioned` it in a request you sent to an analyst for review.

## Managing Files

Each row has a menu: **Download**, **Approve**, **Make private**, **Exclude**, **Re-include**, and **Delete**. You can also select several files and act on them together.

Who can do what:

| Action                        | Who                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| Upload                        | Anyone with Ask Anything access                                                            |
| Approve / Make private        | The file's uploader                                                                        |
| Exclude / Re-include / Delete | **Admin** or **Analyst Contributor** on any file; everyone else on their own private files |
| Edit description              | The uploader, or an Admin/Analyst Contributor on an approved file                          |

Approving a file makes it available to anyone in the org with access to the workspace. Making it private again removes that access. Deleting is permanent.

<Note>
  Files are **live** — they take effect as soon as you change them. Unlike metrics or entities, they aren't part of the draft-and-deploy cycle and have no version history. See [Context Layer Versioning](/context-layer/building/context-layer-versioning).
</Note>

## Using Files in a Chat

Type `@` in the chat and pick from the **Files** group to point the agent at a specific file. This works even for files with no description, and it's the reliable way to say "use this one."

In a sent message, clicking a file mention downloads the file. Private files are marked so you can tell them apart at a glance.

Behind the scenes the agent reads each file's name, description, and type first, and downloads the contents only when it actually needs them. Excluded files are never fetched.

<Note>
  Files must be enabled for your workspace. If you don't see **Files** in the sidebar, contact your ClarityQ representative. Files aren't available in workspaces that answer across several other workspaces.
</Note>