# Library

> Folders of text files for your account or one project, to keep scripts, agent skills and notes so they aren't lost. Stored only, never run.

The **Library** is a place to keep text files in folders: scripts, agent skills (a `SKILL.md` and its helper files), prompts, notes. **Nothing in it runs and nothing in it is public**; it is stored so you don't lose it, and so your agents can find it again.

There are two Libraries:

| Scope | Where | In the API |
| --- | --- | --- |
| **Account** | console ▸ **Library** | no `project_id` |
| **Project** | console ▸ a project ▸ **Library** | `project_id` set |

They are separate trees: a file in a project's Library isn't in the account's, and the other way round. A deleted project's Library goes with it. Other accounts never see yours.

```bash
vibiz library put ./skills/seo skills/seo     # a whole folder (a skill), recursively
vibiz library ls skills                        # what is in a folder
vibiz library cat skills/seo/SKILL.md          # one file's text
vibiz library get skills/seo ./skills          # a folder back to disk: ./skills/seo
vibiz library mkdir scripts/deploy
vibiz library mv scripts/old.sh scripts/archive/old.sh
vibiz library rm -r scripts/archive
vibiz library ls --project prj_…               # a project's Library
```

Agents use the `vibiz_library_list`, `vibiz_library_read`, `vibiz_library_write`, `vibiz_library_mkdir`, `vibiz_library_move` and `vibiz_library_delete` tools (each takes an optional `project_id`), the SDK (`vibiz.library.*`) or the API below. Every answer carries a `console_url` that opens that folder or file.

## Saving a skill

A skill is a folder: `SKILL.md` plus anything it uses (`scripts/`, `reference/`). Push the folder and it lands with its structure:

```bash
vibiz library put ./my-skill skills/my-skill
```

`put` sends a folder in one import (all or nothing), skips `.git`, `node_modules` and anything that isn't text, and replaces files already there, so pushing again updates the skill. `get` writes the folder back, empty folders included.

## Paths and limits

- Paths start at the top of the Library, with `/` between folders: `skills/seo/SKILL.md`. Leading, trailing and doubled slashes are dropped.
- A name can't be `.` or `..`, nor hold a backslash or a control character; at most 255 characters a name, 512 a path, 24 folders deep.
- Writing a file makes the folders above it. Folders exist on their own, so an empty folder stays.
- Text only: UTF-8, no NUL bytes, at most **1 MB** a file. Images, videos and other binaries belong in a project's [Files](https://thelastapi.dev/docs/files).
- At most 5,000 folders and files and 100 MB in each Library; an import takes up to 1,000 files and 20 MB, an export returns up to 50 MB.
- Moving a folder takes everything in it. Moving onto something that exists is refused unless you ask to replace it (`overwrite`, `vibiz library mv --force`).
- Deleting a folder that isn't empty needs `recursive` (`vibiz library rm -r`).

Every refusal says what failed, why and how to fix it, with the field in `param`.

## Who can use it

Any account key, Full access or Limited, and the console. It is the owner's and their agents' own storage, so the app key (`VIBIZ_APP_KEY`, your app's users' traffic) can't read or write it.

## API

| Call | Does |
| --- | --- |
| `GET /v1/library?path=&recursive=1` | one folder's entries (or everything below it), with sizes, no text |
| `GET /v1/library/file?path=` | one file with its `content` |
| `PUT /v1/library/file` `{ path, content }` | create or overwrite a file |
| `POST /v1/library/folders` `{ path }` | make a folder |
| `POST /v1/library/move` `{ from, to, overwrite? }` | move or rename |
| `DELETE /v1/library?path=&recursive=1` | delete a file or folder |
| `POST /v1/library/import` `{ path, files: [{ path, content }] }` | many files into a folder at once |
| `GET /v1/library/export?path=` | a folder back as files |

Add `project_id` (a query parameter, or a body field) to any of them for a project's Library.
