# Creating a file

Connect writes a file through the `create_file` tool, into the same store every uploaded file goes to. It builds the contents from what is already in the workspace and from the conversation you are having — never from figures it does not have. The result is version 1 of a chain, with provenance saying which request produced it, and it appears on the Files sheet straight away.

- **Status:** Available
- **Audience:** both
- **In the app:** #/home, #/data
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/files-data/create-file/

## What a produced file is built from

A document Connect writes is assembled from material it can point at: records in the workspace, a file you attached, [Knowledge](/docs/knowledge/) the workspace supplied, and the words of the request itself. Everything in the finished file traces back to one of those four.

That is a real constraint, and it shows. Ask for a quotation and Connect will lay out the document, carry across the customer, the items and the dates it can see, and leave the price as an obvious gap rather than a plausible number. The Assistant's authority is deliberately narrower than yours, and pricing is one of the things it does not hold — [what the Assistant may not do](/docs/assistant/assistant-authority/) sets out the rest.

> **Careful** A gap in a generated document is a feature you should not paper over by asking again in different words. If Connect could not find a figure, asking a second time does not create the figure; it only raises the chance of an invented one being talked into existence.

## Which formats it will write

The writable formats are whatever `file_formats` can produce, and that list is narrower than the list of formats Connect can *read*. Asking for something outside it comes back as a refusal that names what is available, rather than a file with unexpected contents inside a familiar extension.

| Direction | What governs it | What a mismatch looks like |
|---|---|---|
| Reading a file you supply | The accepted formats at [validation](/docs/files-data/mime-validation/) | The upload is refused before storage, with the reason |
| Writing a file Connect produces | What `file_formats` can generate | The request is refused and the alternatives are named |
| Changing a file that already exists | The format of the file being changed | See [changing a file](/docs/files-data/modify-file/) |

If you need a specific format for something downstream, say so in the request rather than renaming the file afterwards. A file whose extension disagrees with its bytes is exactly the thing validation exists to catch, and it will be caught the next time it is uploaded anywhere.

## Creating a file is a change, so it is approved like one

`create_file` is a writing tool. In the Assistant it arrives as a [proposed action](/docs/assistant/action-cards/) showing what will be produced, and nothing is written until you run it. Under an autonomy rule that requires a person, the proposal waits in [Needs You](/docs/autonomy/) with everything needed to judge it.

1. Say what the document is for, who it is for, and what must be in it.
   - Result: Connect resolves the record it names — the company, the deal, the case — instead of guessing from a name.
2. Read the proposal, including the fields it says it could not fill.
   - Result: You find out what is missing before the file exists, which is much cheaper than finding out after it has been sent.
3. Run it.
   - Result: The file is written to the workspace file store, an audit entry records the request and the tool, and the file appears on the Files sheet in [the Data grid](/docs/files-data/data-grid/).
4. Link it to the record it belongs to, if that did not happen as part of the request.
   - Result: The document turns up on that company, deal or case for anyone who opens it later — see [linking a file to a record](/docs/files-data/linking-files/).

## Where it lands, and what it is not

**In the workspace file store** — The same `media_assets` store an uploaded file goes to, scoped to your workspace and under row-level security. There is no second place for generated files.
**As version 1** — Every produced file starts a chain. The first change makes version 2 and the original stays readable — [file versions](/docs/files-data/file-versions/) explains what that buys you.
**Not sent anywhere** — Creating a document does not email it, attach it to a thread or share it outside the workspace. Sending is its own action under its own autonomy rule.
**Not a knowledge source** — A generated file does not start grounding future answers. Adding it to Knowledge is a separate decision, and usually the wrong one for a document Connect wrote.

## Questions

### Can Connect produce a file from a conversation on the phone or in email?

Yes — the material is the same, and a call transcript or a mail thread is as good a source as anything else in the workspace. What changes is only how you ask. The document is still written by the same tool into the same store, and it still carries provenance back to the request that produced it.

### Why did the file come back with blanks in it?

Because the workspace does not hold those values and Connect will not invent them. Fill the blanks yourself, or put the missing facts where Connect can see them and ask for a new version. Both are better than a document that reads correctly and is wrong.

### Does creating a file count against anything?

A customer workspace has plan allowances and the Owner workspace has none, which is the only difference between the two audiences here. What is metered and how it is shown belongs to [account and access](/docs/account/) rather than to the file service.

## Related

- [Changing a file](https://connectbyjbrh.com/docs/files-data/modify-file/)
- [File versions](https://connectbyjbrh.com/docs/files-data/file-versions/)
- [Linking a file to a record](https://connectbyjbrh.com/docs/files-data/linking-files/)
- [Creating a document, end to end](https://connectbyjbrh.com/docs/workflows/create-document/)
- [Proposed actions](https://connectbyjbrh.com/docs/assistant/action-cards/)
- [What the Assistant may not do](https://connectbyjbrh.com/docs/assistant/assistant-authority/)

## What this page is based on

- docs-source/sources/GENERAL.md §9 — files and the Data grid
- docs-source/sources/GENERAL.md §8 — the Assistant's writing tools
- `backend/app/file_workspace.py`, `file_formats.py`
- Connect capability registry (docs-source/facts.py) — `file_workspace`