Set Up Folio AI

Set Up Folio AI

Folio AI is the assistant in the side panel. It runs on a Cursor key, it works with your wiki through the same tools an outside agent gets over MCP, and it never has more rights than the person asking. Without a key, everything else in Folio works as usual.

1. Provide a key

Folio does not resell AI and adds no markup: whoever owns the key pays. Cursor is the only provider for now. A run uses the first key that exists, in this order:

1. Personal key: each person adds their own in account settings (AI assistant).
2. Space key: a space administrator sets it in the space menu, Folio AI key.
3. Instance key: an instance administrator sets it on the Shared key tab of Assistant analytics, and can turn personal keys off so everyone uses the shared one.
4. CURSOR_API_KEY in the server environment (.env).

Shared keys are encrypted with FOLIO_SECRET, never shown again after saving, and every change is in the audit log. Visitors of a public site have no key of their own; their questions use the space key, then the instance key, then the environment key.

2. Ask or Agent

Mode	Does	Guard
Ask	Reads only: find, summarize, compare, explain across pages you can open	Write tools are removed on the server, not just hidden
Agent	Reads and writes: drafts pages, edits tables, draws boards, restructures sections	Inside your rights, never beyond them

Runs live on the server: close the browser and the work continues; come back and read on. Deadlines per run default to 5 minutes (Ask), 30 minutes (Agent) and 10 minutes without activity (CURSOR_AGENT_TIMEOUT_MS, CURSOR_AGENT_TIMEOUT_MS_AGENT, CURSOR_AGENT_IDLE_TIMEOUT_MS).

3. What it can build

Pages (Markdown), data tables (rows, columns, views), whiteboards, forms with the table their answers go to, and Obsidian bases. Since 0.4 it has skills for forms and for the syntax of bases. Example requests:

• "Add an initiative to the roadmap table and tell me which ones are urgent."
• "Make a form for the week-one check and put the answers in a table."
• "Draw the release process as a board."

Every change is a Git commit under your name and can be reverted from the page history.

4. Teach it with .agent

Every space has a .agent folder. Pages in it become the assistant's instructions for that space, in Ask and Agent modes alike: its role, tone, glossary, rules, templates, the process to walk people through. Only space administrators see and edit it. About 60,000 characters are used; if there is more, whole pages at the end are left out and the assistant says so. Different spaces get different agents: support answers like support, legal never improvises.

Don't put secrets in .agent: on a public site a visitor can get the rules paraphrased.

5. Watch the quality (admins)

• 👍 / 👎 on any saved answer, and a short survey after every third answer.
• Questions without an answer: the assistant records what the pages could not answer, with the person's own words and the pages it read.

Instance administrators open Assistant analytics (/admin/assistant, account menu); space administrators see only their spaces. Opening a conversation is written to the audit log and shown on the conversation page. See Set Up Onboarding.

Limits

• Needs a Cursor subscription, and the pages the assistant reads go to Cursor.
• Search is keyword-based, with no embeddings; page titles and wording matter.
• Links in answers are written by the model: open the source before you act.
• One agent configuration per space.
• The public demo has the assistant switched off.

See also

Connect AI Agents · Blog: onboarding assistant · Docs as Code · README: Folio AI