Documents, files and skills | Basement Gateway

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.