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

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Files

> Upload unstructured content — documents, PDFs, playbooks — as searchable resources with defineFile.

**Files** are unstructured resources — documents, PDFs, transcripts, playbooks. When attached to an agent or tool, their content is chunked and embedded so it can be retrieved by meaning (semantic search), not just keywords. You upload one from a local path with `defineFile`.

## Define a file

```ts files/playbook.ts theme={null}
import { defineFile } from "@cargo-ai/cdk";

export const playbook = defineFile("playbook", {
  path: new URL("./playbook.md", import.meta.url).pathname,
});
```

The content is uploaded on deploy; the file handle can then be referenced as an agent resource.

## Supported types

| Type          | Extensions                 |
| ------------- | -------------------------- |
| Documents     | `.pdf`, `.docx`, `.doc`    |
| Text          | `.txt`, `.md`, `.markdown` |
| Presentations | `.pptx`, `.ppt`            |
| Spreadsheets  | `.xlsx`, `.xls`, `.csv`    |

## Using files in agents

Attach files (or folders of files) as agent [resources](/agents/resources-and-context). The agent searches them with vector similarity — a query for "pricing concerns" surfaces content about "cost objections" even without the exact words. Add a prompt to steer how the agent prioritizes the content.

## From the CLI

```bash theme={null}
cargo-ai content file upload --file ./playbook.pdf
cargo-ai content file list
cargo-ai content library list      # group files into retrieval libraries
```

<Note>
  For structured, queryable data (CRM objects, tables) use [models](/models/overview)
  instead — files are for unstructured knowledge.
</Note>