diff --git a/.order b/.order
new file mode 100644
index 0000000..b23b6b7
--- /dev/null
+++ b/.order
@@ -0,0 +1,10 @@
+getting-started
+reading-and-navigating
+search-and-graph
+writing-a-page
+editor-reference
+templates-and-metadata
+example-kernel-update
+appearance-and-settings
+ai-agents
+faq
diff --git a/README.md b/README.md
deleted file mode 100644
index 4418e16..0000000
--- a/README.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# user-guide
-
diff --git a/_templates/process-runbook.md b/_templates/process-runbook.md
new file mode 100644
index 0000000..2f3db0f
--- /dev/null
+++ b/_templates/process-runbook.md
@@ -0,0 +1,49 @@
+---
+title: Process runbook
+description: Profile, flow diagram, steps, responsibilities and required documents for an operational process.
+---
+
+# {{titel}}
+
+Created on {{datum}} by {{autor}}.
+
+## Profile
+
+| Field | Value |
+| ------------- | ----- |
+| Process ID | |
+| Process owner | |
+| Scope | |
+| Trigger | |
+| Purpose | |
+
+## Process flow
+
+> [!TIP]
+> Type **/** and choose **draw.io diagram** to add a swimlane, one lane per role.
+
+## Steps
+
+1. **Request** —
+2. **Assessment and approval** —
+3. **Preparation** —
+4. **Execution** —
+5. **Acceptance** —
+6. **Closure** —
+
+> [!WARNING]
+> Describe the rollback path before the first execution.
+
+## Responsibilities
+
+| Activity | Requester | Executing team | Approver | Service owner |
+| -------- | --------- | -------------- | -------- | ------------- |
+| | | | | |
+
+*R = Responsible · A = Accountable · C = Consulted · I = Informed*
+
+## Required documents
+
+| Document | Mandatory | Where |
+| -------- | --------- | ----- |
+| | | |
diff --git a/ai-agents/index.md b/ai-agents/index.md
new file mode 100644
index 0000000..a5ada64
--- /dev/null
+++ b/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.
diff --git a/appearance-and-settings/index.md b/appearance-and-settings/index.md
new file mode 100644
index 0000000..d2e6d9c
--- /dev/null
+++ b/appearance-and-settings/index.md
@@ -0,0 +1,46 @@
+---
+id: appearance-and-settings
+title: Appearance and settings
+description: Theme, language, and the accounts you connect to f451.
+tags: [guide, settings]
+lang: en
+---
+
+# Appearance and settings
+
+Everything in this page lives under the account menu's **Settings**.
+
+## Connections
+
+**Connections** lists your Forgejo and GitHub accounts. Each shows
+**Connected** or **Not connected**, with a **Connect** button; an
+expired connection shows **Reconnect** instead, and until you reconnect
+its spaces stay hidden. **Disconnect** removes a connection.
+
+This is also where **write access comes from** — see [[getting-started]]
+for why a connected account is required before you can edit anything.
+
+## Appearance
+
+**Appearance** shows every design value of the interface, grouped by
+role, for **Light** and **Dark** mode separately. Changes take effect
+immediately, but only in this browser — other people and other devices
+do not see them. **Reset group** reverts one group, **Reset everything**
+reverts all of it.
+
+The theme toggle in the top bar switches between light and dark mode at
+any time without going into settings.
+
+## Language
+
+The language switcher in the top bar lets you choose between **German**
+and **English** for the interface. Page content keeps whatever language
+it was written in (each page's frontmatter records its own `lang`);
+switching the interface language does not translate page content.
+
+## Personal access tokens
+
+**Personal access tokens**, further down in settings, is where you
+create tokens for external tools — most notably an AI agent connecting
+over MCP. See [[ai-agents]] for what such a token is for and what it
+lets an agent do.
diff --git a/editor-reference/index.md b/editor-reference/index.md
new file mode 100644
index 0000000..11f3477
--- /dev/null
+++ b/editor-reference/index.md
@@ -0,0 +1,84 @@
+---
+id: editor-reference
+title: Editor reference
+description: Formatting, wikilinks, callouts, images and diagrams in the editor.
+tags: [guide, editor, reference]
+lang: en
+---
+
+# Editor reference
+
+The editor has two modes, switchable at any time: **WYSIWYG** for
+formatted editing, and **Markdown** for the raw text. Under the hood,
+both edit the same Markdown file — the WYSIWYG editor writes it in a
+canonical form, so switching to Markdown and back never surprises you.
+
+## Formatting toolbar
+
+Selecting text shows a toolbar with **Bold (⌘B)**, **Italic (⌘I)**,
+**Inline code (⌘E)**, and **Insert link (⌘K)**. Block-level buttons cover
+**Bullet list**, **Numbered list**, **Task list**, **Insert table**, and
+**Insert image or file**.
+
+## The slash menu
+
+Type **/** on an empty line to open the command menu and insert a block:
+headings (**Heading 1–3**), **Bullet list**, **Numbered list**, **Task
+list**, **Table**, **Code block**, **Quote**, a **Divider**, an
+**Image/File**, a **draw.io diagram**, an **Excalidraw** sketch, a
+**Video**, or a callout (**Note**, **Tip**, **Important**, **Warning**,
+**Caution**).
+
+## Wikilinks
+
+Type **[[** to search for a page by name and insert a link to it —
+either navigate to it directly or insert the link. A wikilink stores the
+target page's id, not its title, so renaming a page's title never breaks
+links to it:
+
+```
+[[getting-started]]
+[[getting-started|Getting started]]
+```
+
+## Callouts
+
+Callouts are GitHub-style alert blocks, available for **Note**, **Tip**,
+**Important**, **Warning**, and **Caution**:
+
+```
+> [!NOTE]
+> Neutral, additional information.
+
+> [!TIP]
+> A helpful suggestion.
+
+> [!IMPORTANT]
+> Something the reader must not miss.
+
+> [!WARNING]
+> A risk to be aware of before proceeding.
+```
+
+## Images
+
+**Insert image or file** (or the slash menu's **Image/File** entry)
+uploads a file and places it in the page; it is stored alongside the
+page in the repository.
+
+## Diagrams
+
+Two diagram types can be edited right inside the page:
+
+- **draw.io diagram** — a flowchart-style diagram, edited in an embedded
+ draw.io canvas.
+- **Excalidraw** — a hand-drawn-style sketch.
+
+Both are saved as an SVG next to the page, with the diagram's own source
+embedded in the file — so opening **Edit diagram** on an existing
+diagram reopens it fully editable, not just as a flattened image.
+
+## Video
+
+The **Video** slash-menu entry asks for a YouTube URL and embeds it as
+its own line in the page.
diff --git a/example-kernel-update/_media/lifecycle.drawio.svg b/example-kernel-update/_media/lifecycle.drawio.svg
new file mode 100644
index 0000000..bb4ffa0
--- /dev/null
+++ b/example-kernel-update/_media/lifecycle.drawio.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/example-kernel-update/_media/rollback.excalidraw.svg b/example-kernel-update/_media/rollback.excalidraw.svg
new file mode 100644
index 0000000..3afd48e
--- /dev/null
+++ b/example-kernel-update/_media/rollback.excalidraw.svg
@@ -0,0 +1,2 @@
+
\ No newline at end of file
diff --git a/example-kernel-update/index.md b/example-kernel-update/index.md
new file mode 100644
index 0000000..58a3cb6
--- /dev/null
+++ b/example-kernel-update/index.md
@@ -0,0 +1,104 @@
+---
+id: example-kernel-update
+title: "Example: Kernel update"
+description: A complete process page — tables, a draw.io swimlane, an Excalidraw sketch and a video — created from the process template.
+tags: [example, process, template]
+lang: en
+---
+
+# Example: Kernel update
+
+This page is a worked example. It documents a fictitious process — updating
+the kernel on a fleet of Linux servers — and shows most of what a page in
+f451 can contain. It was started from the **Process runbook** template; see
+[[templates-and-metadata]] for how templates work.
+
+> [!NOTE]
+> What this page demonstrates: tables, callouts, a **draw.io** diagram
+> (swimlane), an **Excalidraw** sketch, an embedded **YouTube** video and
+> links to other pages. Open it in the editor to see how each is written —
+> both diagrams can be edited right there.
+
+## Profile
+
+| Field | Value |
+| ------------- | ----------------------------------------------- |
+| Process ID | OPS-LNX-001 |
+| Process owner | Platform team |
+| Scope | All Linux servers (development, staging, production) |
+| Trigger | Security advisory, vendor release, planned maintenance window |
+| Purpose | Keep every server on a current, supported and secure kernel |
+
+## Process flow
+
+The lifecycle as a swimlane — one lane per role. This is a **draw.io**
+diagram: the image you see and its editable source live in the same file,
+`_media/lifecycle.drawio.svg`, next to this page.
+
+
+
+The technical core, sketched by hand. This one is an **Excalidraw** drawing
+(`_media/rollback.excalidraw.svg`) — quicker to draw, deliberately informal.
+
+
+
+## Steps
+
+1. **Request** — raise a change: servers, target kernel, maintenance window, risk.
+2. **Assessment and approval** — the platform team assesses; the change manager approves.
+ No approval without the mandatory documents below.
+3. **Preparation** — install the new kernel on development servers and run the smoke tests.
+4. **Staging** — roll out to staging, run the regression tests, record the result.
+5. **Production** — roll out in the approved window, one group of servers at a time.
+6. **Acceptance** — the service owner confirms the functional checks.
+7. **Closure** — close the change, update the inventory, attach the evidence.
+
+> [!WARNING]
+> Keep the previous kernel installed until acceptance. It is the rollback
+> path: if the checks fail after the reboot, boot the previous kernel and
+> reopen the change.
+
+## Technical execution
+
+```sh
+# Record the current state
+uname -r > /var/tmp/kernel-before.txt
+
+# Install the new kernel (Debian/Ubuntu shown; adapt to your distribution)
+sudo apt-get update && sudo apt-get install --only-upgrade linux-image-generic
+
+# Reboot inside the maintenance window, then verify
+sudo systemctl reboot
+uname -r
+systemctl --failed
+```
+
+## Responsibilities
+
+| Activity | Requester | Platform team | Change manager | Service owner |
+| --------------------- | --------- | ------------- | -------------- | ------------- |
+| Raise change | R/A | C | I | C |
+| Technical assessment | I | R | A | C |
+| Approval | I | C | A/R | C |
+| Perform update | I | R/A | I | I |
+| Functional acceptance | I | C | I | R/A |
+
+*R = Responsible · A = Accountable · C = Consulted · I = Informed*
+
+## Required documents
+
+| Document | Mandatory | Where |
+| --------------------------- | --------- | ---------------------- |
+| Change request | yes | Ticket system |
+| Test record (staging) | yes | Attached to the change |
+| Rollback plan | yes | This page, step 7 |
+| Acceptance record | yes | Attached to the change |
+
+## Background
+
+Why the kernel matters, from the person who started it:
+
+https://www.youtube.com/watch?v=o8NPllzkFhE
+
+Related: [[writing-a-page]] explains how a change to this page goes through
+review before it is published.
diff --git a/faq/index.md b/faq/index.md
new file mode 100644
index 0000000..f863860
--- /dev/null
+++ b/faq/index.md
@@ -0,0 +1,51 @@
+---
+id: faq
+title: FAQ
+description: Short answers to questions that come up often.
+tags: [guide, faq]
+lang: en
+---
+
+# FAQ
+
+**Why can't I just edit the page and save it?**
+Because nothing in f451 writes directly to the published version — not
+for you, not for anyone else, not for an AI agent. Every change goes
+through a draft and a review first. See [[writing-a-page]].
+
+**I signed in, but I don't see a space I expect to see.**
+Visibility follows your permissions in the underlying Forgejo or GitHub
+repository, not a separate f451 role. Check that you have access to the
+repository itself, and that your Forgejo or GitHub account is connected
+under **Settings → Connections** — see [[getting-started]].
+
+**I can read a space but can't edit anything in it.**
+Your Git account can read the repository but not push to it. Writing
+needs write access to the space's repository, because every change is
+committed under your own name. Ask whoever manages the repository to
+grant it.
+
+**What happens if two of us edit the same page at once?**
+f451 never discards a change silently. If someone else is already
+editing the same draft, you see who and can choose to proceed anyway; if
+a conflicting save happens, you are shown both versions and choose which
+to keep. See [[writing-a-page]].
+
+**Is the page history preserved?**
+Yes — a page's history is its Git history. Released pages additionally
+get a version number and a change note if the space keeps page versions
+(see [[templates-and-metadata]]).
+
+**Can I write raw Markdown instead of using the formatted editor?**
+Yes. Switch the editor to **Markdown** mode at any time; both modes edit
+the same underlying file. See [[editor-reference]].
+
+**What happens to my changes if my connection drops mid-edit?**
+The editor keeps your changes locally in the browser until the
+connection comes back, so nothing you typed is lost.
+
+**Can an AI agent publish changes on its own?**
+An agent writes through the same review workflow as a person — it can
+create and edit drafts and request a review, but whether it may also
+approve and merge is a separate decision made for that agent. See
+[[ai-agents]].
diff --git a/getting-started/index.md b/getting-started/index.md
new file mode 100644
index 0000000..912ffb7
--- /dev/null
+++ b/getting-started/index.md
@@ -0,0 +1,46 @@
+---
+id: getting-started
+title: Getting started
+description: Sign in, connect your Git account, and understand what each step unlocks.
+tags: [guide, getting-started]
+lang: en
+---
+
+# Getting started
+
+## Sign in
+
+f451 does not have its own accounts. The sign-in page shows one button
+per sign-in method your instance offers — for example **Sign in with
+Microsoft Entra**, **Sign in with Forgejo** or **Sign in with GitHub**.
+There is no separate f451 password to remember.
+
+## Connect your Git account
+
+What you can see depends on your Git account, so f451 needs it linked.
+If you signed in with Forgejo or GitHub, that account is usually linked
+right away and you can skip this step. Otherwise — for example after
+signing in with Microsoft Entra — link your Forgejo or GitHub account
+under **Settings → Connections**:
+
+> Link your f451 account with Forgejo or GitHub to include spaces from
+> the respective repositories.
+
+Open the account menu and choose **Settings**, then **Connections**, and
+select **Connect** for the provider your spaces live on. If a
+connection has expired, the same page shows **Reconnect** — until you
+reconnect, spaces from that provider stay hidden.
+
+> [!IMPORTANT]
+> **Without a linked account you see no spaces.** f451 has no role system
+> of its own: what you may read and write is exactly what your Forgejo or
+> GitHub account may do in the space's repository. Reading needs read
+> access to the repository; writing needs write access, and every change
+> is committed under your own name — f451 never writes on your behalf
+> using a shared or service account.
+
+## Where to go next
+
+- [[reading-and-navigating]] to find your way around a space
+- [[writing-a-page]] once your account is connected and you are ready to write
+- [[appearance-and-settings]] for theme, language and managing connections later
diff --git a/index.md b/index.md
new file mode 100644
index 0000000..5426ecd
--- /dev/null
+++ b/index.md
@@ -0,0 +1,43 @@
+---
+id: welcome
+title: User Guide
+description: What f451 is and how this guide is organised.
+tags: [guide]
+lang: en
+---
+
+# User Guide
+
+f451 is a wiki whose pages live in Git. Every space you see here is a
+repository on Forgejo or GitHub; every page is a Markdown file in it. The
+wiki gives you a page tree, full-text search, an editor and a review
+workflow on top — but the file in the repository stays the single source
+of truth, and its Git history stays the page's history.
+
+Two consequences follow directly from that, and both come up throughout
+this guide:
+
+> [!NOTE]
+> **Permissions come from Git.** There is no separate role system in
+> f451. Whether you can see a space, and whether you can write to it,
+> is decided by your permissions in the underlying Forgejo or GitHub
+> repository.
+
+> [!NOTE]
+> **Nobody writes straight to the published version.** Every change —
+> yours, a colleague's, or an AI agent's — goes through a draft and a
+> review before it is published. See [[writing-a-page]].
+
+## How this guide is organised
+
+- [[getting-started]] — sign in and connect your Git account
+- [[reading-and-navigating]] — the page tree, breadcrumbs, the outline, the phone layout
+- [[search-and-graph]] — full-text search, the graph view, the link report
+- [[writing-a-page]] — draft, review, approval, and what happens on a conflict
+- [[editor-reference]] — formatting, wikilinks, callouts, images, diagrams, video
+- [[templates-and-metadata]] — starting points for new pages and structured fields
+- [[appearance-and-settings]] — theme, language, connected accounts
+- [[ai-agents]] — connecting an AI agent to a space through MCP
+- [[faq]] — short answers to recurring questions
+
+If you only read one other page, make it [[getting-started]].
diff --git a/reading-and-navigating/index.md b/reading-and-navigating/index.md
new file mode 100644
index 0000000..aebbf35
--- /dev/null
+++ b/reading-and-navigating/index.md
@@ -0,0 +1,61 @@
+---
+id: reading-and-navigating
+title: Reading and navigating
+description: The page tree, breadcrumbs, the outline, the info panel, and the phone layout.
+tags: [guide, reading]
+lang: en
+---
+
+# Reading and navigating
+
+## The page tree
+
+The left panel lists the **Pages** in the current space, nested the same
+way their folders are nested in the repository. Click the panel's edge
+(or press **[**) to collapse or expand it — useful when you want the
+reading area at full width.
+
+Below the page list sit the space's tools, grouped as **Find**
+(**Search**, **Graph view**, **Link report** — see [[search-and-graph]])
+and **Configure** (**Templates**, **Metadata schema**, **Connections**,
+**Appearance** — see [[templates-and-metadata]] and
+[[appearance-and-settings]]).
+
+## Breadcrumbs and the running position
+
+Every page shows its breadcrumb trail above the title, so you always
+know which space and which parent page you are under. While you scroll
+a long page, a running indicator shows which section you are in.
+
+## The info panel
+
+The right panel (press **]** to toggle it) carries everything about the
+*current* page:
+
+- **Table of contents** — jump between headings
+- **Tags**
+- **Metadata** — the space's custom fields, if it has a metadata schema (see [[templates-and-metadata]])
+- **Status** — Draft, In review, Released, or Archived
+- **Space** and **Updated**
+- **Related pages** — pages connected to this one by hierarchy, links, or relations
+
+## Page status
+
+A page you are reading can be in one of four states, shown as a badge:
+
+| Status | Meaning |
+|---|---|
+| Released | The published version — what everyone with read access sees |
+| In review | A draft exists and a review (pull request) is open for it |
+| Draft | A draft exists but no review has been requested yet |
+| Archived | Removed from the live tree, kept read-only for history |
+
+If a draft exists for a page you are reading, a notice at the top offers
+a **View draft →** link so you can preview the unreleased content.
+
+## On a phone
+
+On a narrow screen the page tree and info panel move into a bottom bar
+with **Pages**, **Outline** and **Info** sections, plus a **Next**
+button that jumps straight to the next page in the tree — handy for
+reading a space end to end without hunting through the tree each time.
diff --git a/search-and-graph/index.md b/search-and-graph/index.md
new file mode 100644
index 0000000..da2e46a
--- /dev/null
+++ b/search-and-graph/index.md
@@ -0,0 +1,45 @@
+---
+id: search-and-graph
+title: Search and the graph
+description: Full-text search, the knowledge graph, and the link report.
+tags: [guide, search, graph]
+lang: en
+---
+
+# Search and the graph
+
+## Search
+
+Press **⌘K** (Ctrl+K on Windows/Linux) anywhere, or pick **Search** from
+a space's sidebar, to open the search dialog. Start typing to search
+full text across the spaces you have access to; results update as you
+type.
+
+## Graph view
+
+Choose **Graph view** in the sidebar to see a space's pages as a network
+instead of a tree. Nodes are pages, coloured by status (Released,
+Review, Working, Archived); edges show how pages relate to each other:
+
+| Edge | Meaning |
+|---|---|
+| Hierarchy | one page contains the other |
+| Link | one page references the other (a wikilink or Markdown link) |
+| Relation | a named relation such as *depends on* |
+
+Use the filter bar to narrow the view: filter nodes by name, restrict to
+one space, or adjust **Depth** — how many hops around your current
+selection are shown. **Reset** returns to the default view.
+
+> [!TIP]
+> Click a node to see its title, status, links and last update, with an
+> **Open** button to jump straight to that page.
+
+## Link report
+
+Choose **Link report** in the sidebar to see every unresolvable
+reference and relation in the current space in one list — broken
+wikilinks, links to pages that no longer exist, or relations pointing
+nowhere. Broken references are treated as data to clean up, not as
+errors that block anything; if there is nothing to fix, the report says
+so plainly.
diff --git a/templates-and-metadata/index.md b/templates-and-metadata/index.md
new file mode 100644
index 0000000..a3b9b06
--- /dev/null
+++ b/templates-and-metadata/index.md
@@ -0,0 +1,55 @@
+---
+id: templates-and-metadata
+title: Templates and metadata
+description: Starting points for new pages, structured fields, and page versions.
+tags: [guide, templates, metadata]
+lang: en
+---
+
+# Templates and metadata
+
+## Templates
+
+**Templates** in the sidebar lists the starting points offered when you
+create a new page in this space, plus any **global** templates that
+apply across all spaces. Space templates can be renamed, have their
+content edited, and be deleted here — global templates are read-only,
+shown for reference only.
+
+The easiest way to add a template is from a finished draft: use **Save
+as template …** in the editor's status bar to turn its current content
+into a reusable starting point (see [[writing-a-page]]).
+
+This space ships one template, **Process runbook**. The page
+[[example-kernel-update|Example: Kernel update]] was created from it and
+then filled in. Templates may use three placeholders that are filled when
+the page is created: `{{titel}}` (the new page's title), `{{autor}}` (you)
+and `{{datum}}` (today's date).
+
+## Metadata schema
+
+**Metadata schema** in the sidebar defines which structured extra fields
+pages in this space carry — for example a process ID, a status, or who
+released a page. Each field has a type:
+
+| Type | Meaning |
+|---|---|
+| Text | free text |
+| Pattern (regex) | text that must match a pattern |
+| Choice (fixed, single) | one value from a fixed list |
+| Date | a date |
+| Multi-select / tags | several values, or free tags |
+| Person | a person |
+| Automatic (from Git) | filled in from Git — last author or last change |
+
+Changes to the schema take effect immediately for every page in the
+space. When a schema is in place, the editor shows a **Metadata** panel
+on the draft with a field per schema entry, and flags required fields
+that are still open.
+
+## Page versions
+
+If a space keeps page versions, every release gets a version number and
+the change note entered at approval time. On a released page, the
+sidebar shows the current **Version** and a link to **All versions of
+this page**, where you can compare any past version with today's content.
diff --git a/writing-a-page/index.md b/writing-a-page/index.md
new file mode 100644
index 0000000..017fee3
--- /dev/null
+++ b/writing-a-page/index.md
@@ -0,0 +1,80 @@
+---
+id: writing-a-page
+title: Writing a page
+description: Draft, editor, review and approval — and what happens when two people edit at once.
+tags: [guide, writing, review]
+lang: en
+---
+
+# Writing a page
+
+Writing in f451 always follows the same path: **draft → editor → review
+→ approval**. There is no way to change the published version directly
+— not for you, not for anyone else, not for an AI agent (see
+[[ai-agents]]). That is by design: every change is reviewable before it
+goes live, the same way code review works.
+
+> [!IMPORTANT]
+> Writing needs a linked Git account. If you have not connected one yet,
+> see [[getting-started]].
+
+## 1. Start a draft
+
+Click **New page** to create a page, or **Edit** on an existing one to
+open its draft. For a new page you choose a **Title**, a **Parent page**
+(the current page or the space root), and optionally a **Template** to
+start from (see [[templates-and-metadata]]).
+
+Creating a draft creates a branch behind the scenes — you do not need to
+know anything about Git to work with it.
+
+## 2. Write
+
+The editor autosaves as you go; the status bar shows **Saving …** and
+then **Last saved …**, or **Not saved yet** for a brand-new draft. You
+can also save explicitly with **Save (⌘S)**. If the connection drops,
+your changes are kept locally in the browser until it comes back —
+nothing is silently lost.
+
+From the same status bar you can **Discard** the draft, **Reset to last
+release**, go **Back to reading view**, **Save as template …**, or
+**Export as Markdown**. **Delete page** removes the page from the
+repository entirely.
+
+See [[editor-reference]] for formatting, wikilinks, images and diagrams.
+
+## 3. Request review
+
+When the draft is ready, click **Request review**. This opens a review
+(a pull request) against the space's main branch. From here on, the
+change is visible to reviewers as a side-by-side comparison of what
+changed, and the page shows an **In review** status to other readers.
+
+## 4. Approval
+
+A reviewer reads the change, optionally leaves a comment, and either
+clicks **Approve & merge** or **Request changes**. Approving asks for a
+version bump — **Fix**, **Addition**, or **Major rework** — and a short
+**Change note** describing what changed; for a page's first release,
+the version is set automatically. Once merged, the page is released and
+the reader is redirected to the reading view.
+
+## Edit conflicts
+
+f451 never overwrites a change silently. Two situations can come up:
+
+> [!WARNING]
+> **Someone else is editing the same draft.** A banner tells you who,
+> with an **Edit anyway** option if you decide to proceed regardless.
+
+> [!WARNING]
+> **Someone else saved a conflicting change while you were editing.** A
+> dialog shows **your version** and the **version on the server**
+> side by side; you choose **Keep server version** or **Keep my
+> version** — nothing is discarded without you seeing both first.
+
+A related case can happen during review: if the space's main branch has
+changed since the review was opened, the review shows **main has
+changed** and offers **Update draft**, either taking main as the new
+base or keeping your version rebased onto it — the release button stays
+disabled until you resolve it.