Demo content from demo/user-guide (0c17989)

ai-agents/index.md

@@ -0,0 +1,64 @@
+---
+id: ai-agents
+title: AI agents
+description: Connecting an AI agent to a space through MCP, and what it can and cannot do.
+tags: [guide, ai-agents, mcp]
+lang: en
+---
+
+# AI agents
+
+f451 has an MCP service that lets an AI agent read, search and write
+wiki content — an agent works with the same spaces you do, through the
+same rules.
+
+## Connecting an agent
+
+An agent needs two things, both tied to your own account:
+
+1. A **personal access token** with **Read and write** permissions,
+   created under **Settings → Personal access tokens**. This is what
+   authenticates the agent's requests as you. The token is shown only
+   once, right after creation — copy it before leaving the page.
+2. Your own **connected Forgejo or GitHub account** (**Settings →
+   Connections**). Without it, every write attempt the agent makes
+   fails with a permission error, the same error a human would get —
+   a token alone is never enough to commit a change.
+
+Give the agent your MCP server address and the token, and it can start
+working the same way it would through any other MCP client.
+
+## What an agent can do
+
+| Purpose | What it covers |
+|---|---|
+| Orient and read | list spaces, browse the page tree, search, read pages, inspect the raw source, read the graph, list broken links |
+| Write, through review | create or edit a page, update a draft, discard it, request a review, request changes |
+| Attachments | generate a diagram from a description (draw.io), attach a file |
+
+## The same review path as people
+
+An agent's writes go through exactly the path described in
+[[writing-a-page]]: it edits a draft, then requests a review. It does
+not publish directly — nothing does. Whether an agent is also allowed to
+approve and merge its own review is a decision you make for that agent
+(most setups leave that step to a human); ask whoever configured the
+agent if you are unsure what it is permitted to do on your spaces.
+
+## Diagrams
+
+An agent builds diagrams the same way described in
+[[editor-reference]]: it describes the diagram (steps, connections, or —
+for a swimlane diagram — steps with their lane), and the service turns
+that into an editable draw.io diagram. It does not hand over a
+ready-made image or a Mermaid diagram, so the result stays fully
+editable afterwards, exactly like one you built yourself in the editor.
+
+## If something goes wrong
+
+Error messages an agent reports back are the same ones a human sees. A
+permission error naming your account usually means the linked Forgejo
+or GitHub account step above is missing. A "not found" result can mean
+either that the page genuinely does not exist, or that neither you nor
+the agent has access to it — f451 deliberately does not distinguish the
+two, for people or for agents.