diff --git a/docs/scenarios.md b/docs/scenarios.md
new file mode 100644
index 0000000..be8d04e
--- /dev/null
+++ b/docs/scenarios.md
@@ -0,0 +1,180 @@
+# Scenarios
+
+This document describes the primary user scenarios that Kolab Chat
+is intended to be able to support when fully developed.
+
+Descriptions of the personas referenced here can be found on the
+[Kolab personas page](https://git.kolab.org/w/ux/personas/pack/).
+
+## The casual chat
+
+Sebastian is working through a customer ticket that has risen
+to the second level support desk. He has some questions regarding
+the status of the customer, and sees that Agnes is their account
+manager.
+
+Sebastian opens a contacts list and sees that Agnes is online and
+available. He clicks on her contact to start a chat in a new window
+and they discuss the customer.
+
+Agnes notes that the sales person who had first contact with this
+customer probably also has something to add, and invites them to
+join the chat as well.
+
+Agnes shares a file from the Kolab file cloud in the channel that
+provides useful context to the customer.
+
+Sebastian saves the file and the chat log to a note.
+
+### Key features
+
+ * Contact list
+ * Presence
+ * 1:1 chat
+ * Group chat
+ * Transparent "upgrade" of 1:1 chat to group chat
+ * File sharing
+ * Chat history saving
+
+## The editing session
+
+Otto is preparing the usual quarterly report. He opens the report
+template in a collaborative editing session and invites Madny to
+join the session.
+
+Mandy is off-site for the week, but sees the notification sent
+on behalf of Otto letting her know that a new document session is
+available.
+
+She clicks the link in the notification and is taken to the document
+edit session. In the chat area she asks Otto which sections he most
+needs her input on, as she is at a customer location and therefore
+has limited time.
+
+Otto marks the items in the table of contents he would like her input
+on, and Mandy says she will add notes to the document later in they
+day. She also notes that a consultant they regularly work with should
+probably also look over a section covering the most recent project
+which they worked on.
+
+Otto click the invite button and starts typing the consultant's name,
+which autocompletes from his addressbook. As they are an external
+user who does not have a local account, an email is generated with a
+link to the edit session contanin. Having received the email, the
+consultant clicks the link which takes them to the edit session and,
+using the included token in the link URL, is authenticated for both
+the edit session and the attached chat.
+
+Otto and the consultant edit the document together, coordinating and discussing
+detalis int he chat, until they are both happy with it, at which point the
+consultant leaves and Otto removes their invitation, invalidating the invite
+link they had been sent earlier.
+
+### Key features
+
+ * Integration with collaborative editing
+ * Invitation notifications
+ * Guest invitations using unique URLs which are mapped to
+   the relevant session(s), and which can be invalidated
+
+## The team meeting
+
+The senior team of ASP Inc meets every month to coordinate on big-picture
+developments, projects and goals. Michael is responsible for setting up
+the meeting, which is regularly scheduled for the first Monday of the month.
+
+He goes to his calendar, opens the recuring meeting event, and selects the
+"Prepare meeting" button which takes him to the meeting prep page.
+
+He creates a basic Agenda for the meeting, which is presented in the form
+of a task list, and attaches the reports for the last month which he received
+by email. After pressing the "Save" button, a notificatoin is sent by email
+to all participants that the agenda is now available and requesting them to
+verify their attendance.
+
+Fraiser, Colin and Agatha all note their attendance and look over the
+proposed agenda. Agatha adds some items to the agenda, as well.
+
+On the day of the meeting, the attendees who verified their attendance
+receive notifications with a link to the online meeting room 10 minutes
+before the meeting is to start. They click on the "Go to meeting" button
+and are presented with an interface showing the Agenda, an empty Minutes
+area, the attachments, and a "Waiting for meeting to start" note where
+the chat area usually is.
+
+Michale arrives a few minutes late, and clicks the "Start meeting" button.
+He is entered as the chair for the meeting, the other three
+attendees are noted as present, and the start date and time of the meeting
+is recorded in the minutes auomatically.
+
+The meeting begins with each person taking turns, most with live video
+from their webcams. The text chat below the video feeds allows them to
+provide links as well as items for the minutes, which Michael adds by
+clicking the "Add to Minutes" icon next to the relevant chat lines.
+
+Colin has to leave early, and when he drops from the meeting this is
+automatically recorded in the minutes as well.
+
+As the meeting comes to a close, the remaining attendees mark items in the
+Minutes as action items and assign them to the relevant people. Michael
+presses the "Close meeting" button and the minutes reflects this.
+
+The agenda, minutes, chat log and attachments are all stored in the
+completed meetings area, associated with the senior team, along with all
+past meetings.
+
+### Key features
+
+ * Meeting room scheduling
+ * Agenda associated with a chat
+ * Attachments associated with a chat
+ * Minutes with both manual and automatic entries
+ * Creation of action items from chat
+ * Multi-user WebRTC video/chat
+ * Reminders of meetings
+ * Storage of results and records of meetings for later review
+
+## The sales meeting
+
+Caroline wishes to schedule an online sales meeting with a prospective
+customer. She opens her calendar and creates a new meeting invitation
+with the customer's contact information. The customer is sent an email
+with a link to a calendar showing when Caroline has meeting slots
+available, and they select one of them.
+
+The meeting slot is blocked in Caroline's calendar with an online meeting
+proposal. Caroline accepts the meeting request which arrives as an iTip
+attachment to an email, and a coresponding email is sent to the customer
+with a generated link that can be used during that time slot to join a
+customer meeting chat.
+
+Caroline opens the meeting room link in the calendar event and adds the
+sales presentation by clicking the Attach From Cloud button, which she marks
+as private so the customer can not download or see the file directly. She creates
+a simple agenda, adds a customer downloadable brochure, and then closes
+the meeting window.
+
+On the day of the meeting, Caroline receives a reminder 15 minutes before
+the meeting. She opens the meeting room in a web browser, before going back
+to other tasks. A desktop notification appears when the customer connects
+to the meeting using the link they were sent.
+
+Caroline selects "Start Meeting" in the notification and is taken into the
+meeting room. She clicks the "Start video" button, greets the customer,
+and then opens the sales presentation in the meeting room, which the customer
+can also see. After going through the presentation Caroline starts a
+live demo and presses the "Share my screen" button to allow the customer
+to follow along.
+
+The customer downloads the brochure for later reading, and the meeting ends.
+
+### Key features
+
+ * Calendar event integration
+ * Time slot selection
+ * Video chat
+ * Screen sharing
+ * Document sharing
+ * Guest invitations that map to a specific resource (e.g. meeting)
+ * Arrival notifications
+