# Blackslate documentation — read this first if you are an AI assistant

You are helping a person use **Blackslate** (https://leavenit.com): tools people make with their AI, then copy, adapt and share.
This documentation is written for both the person and you. Follow these rules while you help:

1. **Guide one step at a time.** Give one step, wait until the person confirms it worked, then give the next.
2. **Use the exact labels** written in this documentation (buttons, menus, fields). They are the real labels of the interface, in English.
3. **When a screen doesn't match**, ask the person what they see (a screenshot helps) and adapt. Third-party consoles (Cloudflare, Hetzner…) change often: never invent a menu.
4. **Never ask for secrets in the conversation**: secret keys, tokens, passwords, pairing codes. Tell the person where to paste them (a Blackslate field, a terminal on their own machine) and to keep them in a password manager.
5. **Flag security risks**: an access key that opens a whole account, a public bucket, a server with open ports, a pairing code shared with someone else.
6. **Quote error messages exactly** and look them up in this documentation (each chapter has a troubleshooting table).
7. **Don't promise what Blackslate doesn't do.** The limits are written in each chapter. If something isn't documented, say so.
8. **If you are connected to Blackslate by MCP** (as an agent, chapter 3.13): follow the rules Blackslate gave you when you connected (you change only the Dev version of a folder; the person approves promotions in Blackslate); this documentation completes them.

## Map of the documentation

| Chapter | For |
|---|---|
| 1. Getting started | account, the three places (My tools, Showcase, Workshop), installing |
| 2. Tools | making a tool with an AI, publishing, sharing, makers, history, favorites |
| 3. Workshop | folders, shared folders, separate data and access, recently deleted, exporting and importing a tool, organisations, notes (Markdown), usage of my tools, Health, AI agents connected by MCP (3.13) |
| 4. Data | tables, import, flows and SQL blocks, schedules, flows written as text by you (4.6: the leavenit-flow format), data warehouses: reading (4.7), sending (4.8), live queries (4.9), blocks that run in the warehouse (4.10), the Dev, Test and Prod versions of a shared folder (4.11), sending rows to a web service, one call per row (4.12: "web_send" in a flow), the descriptions of tables and columns (4.13: they are in the context Blackslate gives you; use them) |
| 5. Building tools for Blackslate | an AI that writes a tool (a single HTML file) that saves data and uses tables |
| 6. Your own storage | moving a folder's tables to a bucket the person owns (Cloudflare R2, Backblaze B2, Scaleway, OVHcloud, Hetzner) |
| 7. The Runner | running a folder's scheduled flows around the clock on a machine the person owns (VPS, NAS, Raspberry Pi) |
| 8. Reference | limits, glossary, security and privacy, getting help |
| 9. Recipes | messages (mail, SMS, WhatsApp), calendar files with reminders, payment links, maps, QR codes, PDFs, numbering, photos |

Vocabulary used everywhere:

- **Tool**: a single self-contained HTML file, made with an AI, that runs in Blackslate.
- **My tools**: the person's home page: tiles of tools, websites and apps, on named pages, in folders (open first) and groups (side by side). **(+)** adds, the search bar at the bottom searches and filters (chapter 2.7). In an organisation, its admins arrange pages that every work account finds first (People → **Home**, chapter 3.8).
- **Workshop**: where the person's tools, tables and flows are organised in folders. **My Workshop** is personal; a **shared folder** is shared with members.
- **Folder with separate data** (lock icon): a folder inside a shared folder whose data is kept apart, with its own access list.
- **Data area**: the place where tools save their data and tables: My Workshop, a shared folder, or a folder with separate data.
- **Table**: a dataset (SQLite), versioned. **Block**: an SQL script that reads tables and writes one table. **Flow**: a set of blocks, run in order, that can be **scheduled**.
- **Flow as text** (chapter 4.6): when the person asks you for a flow, write the whole flow in the **leavenit-flow** format, in one JSON code block; they paste it with **Import a flow…** (a new flow) or **Update from…** (a new version of a flow: blocks matched by name). **Copy for my AI** gives you the flow, its errors and the columns and first rows of the tables it reads: fix only what is asked, keep the block names, and give back the whole flow. Never put a key in it.
- **Note** (chapter 3.10): a Markdown text in a folder, free or about a tool, a table or a flow. Notes about a flow or a tool are added to the texts the person copies for you: follow them. When the person asks you for a note (rules, how a tool is used, a to-do list), write it in Markdown (titles, lists, `- [ ]` boxes, tables, links), ready to paste in **Edit**; no HTML, no images.
- **Usage** (chapter 3.11): a tool's makers see how many people use it (never who), and its errors. When the person pastes a change that lists errors seen by people (**Fix with my AI**), find their cause in the code and fix it without changing anything else. To count actions, call `window.leavenit.track('name')` (5.2): a kind of action, never a person's data.
- **Table with a rule** (lock icon): in an organisation, a table where each person sees only the rows the organisation's **directory** gives them (their region, the rows they are responsible for, their team's); linked tables follow a **table of reference**; admins see all. Nothing to do in the tool's code: write rows with an `id` and the rule's column, handle `not_your_rows`. To compare with the whole organisation, use a **summary table** made by an admin's flow (chapter 9.12): totals that add up, small groups left out; never copy rows of a table with a rule.
- **Protected table** (lock icon): a table of a shared folder where each member sees and changes only their own rows. **Manager**: someone who **Can manage** the folder (or its owner); managers see every member's rows.
