> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# Documents, files and skills

## Documents

A document is a page of markdown: your ideal customer profile, your pricing rules, a process. Documents belong to the organization, and every member sees them.

Each change to a document makes a new version. You can list the versions and restore one. Basement records which version each agent read, so you can see when an agent works from an outdated version.

| To do this                     | Use                                        |
| ------------------------------ | ------------------------------------------ |
| List and read                  | `list_docs`, `read_doc`                    |
| Create                         | `create_doc`                               |
| Replace the body               | `update_doc`                               |
| Change one piece of text       | `edit_doc`                                 |
| Rename, delete                 | `rename_doc`, `delete_doc`                 |
| See and restore versions       | `list_doc_versions`, `restore_doc_version` |
| Turn the public link on or off | `share_doc`                                |

A document with a public link is readable by anyone who has the link, without a login. The link serves the document as a page for people and as markdown for agents.

## Files

A file is anything you upload: a PDF, a logo, a spreadsheet, a text file. A file of up to 5 MB can be written through the Gateway. Replacing a file makes a new version.

`read_file` answers the file's details and a temporary link to download it. For a text file of up to 256 KB, it also answers the text.

| To do this                      | Use                       |
| ------------------------------- | ------------------------- |
| List and read                   | `list_files`, `read_file` |
| Upload, or upload a new version | `write_file`              |
| Change one piece of a text file | `edit_file`               |

## Skills

A skill is a text file with instructions that an agent loads when it needs them: how to research an account, how to answer a kind of ticket. Skills are files of their own kind.

| To do this                     | Use           |
| ------------------------------ | ------------- |
| List                           | `list_skills` |
| Read                           | `read_file`   |
| Create, or write a new version | `write_skill` |
| Change one piece               | `edit_skill`  |

## Folders

Files and skills are in folders. Every member sees the **General** folder. A person can create other folders, which are private until that person shares them with members or with the organization.

A key reaches the folders that the person who connected it can reach, and an access level can limit it to some of them. A file in a folder that the key cannot use reads as not found.

| To do this                          | Use                                          |
| ----------------------------------- | -------------------------------------------- |
| List the folders the key can use    | `list_folders`                               |
| Create a private folder             | `create_folder`                              |
| Put a new file or skill in a folder | `folderId` in `write_file` and `write_skill` |
| Share a folder                      | `share_folder`, then `confirm_folder_share`  |

A key cannot share a folder by itself. `share_folder` only asks: Basement emails a 6-digit code to the person who connected the key, and nothing is shared until `confirm_folder_share` gets that code. So a person always approves a share.

## Find text without reading everything

Three tools keep an agent from loading a large document only to find one line:

* `search` finds documents by title and body, and files and skills by name and tags.
* `find_text` finds a phrase inside one document or text file, and answers the lines that match with their line numbers.
* `read_lines` reads a range of lines.

To change a document, a skill or a text file, `edit_doc`, `edit_skill` and `edit_file` replace one piece of text. Give the old text exactly as it is. It must occur one time.