Kokkoja: first public assembly

Assembled from the development repository by tools/make_release.sh.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/introduction.md

@@ -0,0 +1,106 @@
+# Kokkoja: an introduction
+
+Kokkoja lets people at different computers write together on a shared
+*page*.  Everyone in a session sees the same page.  Anyone can write on it
+by hand or type on it, and what one person writes appears on the others'
+screens as it is written.  A page can begin blank, or it can begin with an
+image, such as a scanned sheet or a photograph, which everyone then writes
+on.  Every page is saved automatically to a *notebook* on each person's
+own computer, so that after the session each participant keeps a complete
+copy of everything that was written.
+
+Kokkoja runs in a web browser, beside whatever video call you are already
+using.  It replaces the screen sharing and annotation of a video call
+application with something made for writing together, and it leaves the
+voice and video to the call.
+
+## What Kokkoja does
+
+**A shared page, not a shared screen.**  In a video call one person's
+screen is transmitted as a picture, and annotations float on top of that
+picture.  In Kokkoja every participant's computer holds the page itself:
+the image, if there is one, and every mark made on it.  Only the changes
+travel over the network.  The marks belong to the page, are saved with it,
+and can be shown or hidden later.
+
+**Handwriting and typing.**  Kokkoja is made for a pen on a drawing
+tablet, with pressure giving the line its thickness, but a mouse or a
+finger will do.  Typed text is placed anywhere on the page and wraps at a
+width you choose.  Both come in any colour.
+
+**Everyone writes on their own layer.**  Each participant's writing is a
+layer of its own.  You can erase your own writing and nothing else; nobody
+else can erase yours.  Any layer can be hidden on your own screen without
+affecting anyone else's view.
+
+**A page that grows.**  A page is an A4 sheet.  When writing approaches an
+edge, the sheet grows in that direction, so you are never short of room.
+An image is placed at its natural size; one wider than the sheet is
+scaled down to fit, and the sheet grows downward to hold further images.
+
+**Saved without a save command.**  The page you are on is written to your
+notebook continuously, as it changes.  Nothing is lost if a connection
+drops or a computer crashes.  When the session moves to another page, the
+page being left is kept as a dated file.  You can also keep a dated copy
+of a page at any moment, and export a picture of it as a PNG file.
+
+**Notebooks are yours.**  A notebook is a directory on your own computer
+and a page is a single file in it, an ordinary SVG file that any
+image viewer or vector drawing program can open.  Nothing is stored on any
+server, and there are no accounts: you choose the name the others will
+see, and that is all.
+
+**Private.**  Everything that travels between participants is encrypted
+on their own computers.  The relay server that passes the messages cannot
+read them.  The invitation to a session carries the key, so only those
+who were invited can read the page.
+
+**Nothing to install for guests.**  A guest joins by opening a link in a
+web browser.  Someone who wants a notebook of real files on their own
+computer installs the small Kokkoja program instead; that is also how a
+host runs Kokkoja.
+
+**Free software.**  Kokkoja is free and open-source.  Anyone can use it
+without paying, and nobody depends on a company's service.  It runs in
+Firefox and in browsers built on the Chromium engine, such as Brave and
+Chrome, on Linux and macOS.
+
+## Who uses it
+
+Kokkoja is a general tool for working on a page together at a distance:
+going through a document with a colleague, sketching a diagram while
+talking it over, correcting a draft, teaching anything that is done on
+paper.  Wherever two people would otherwise lean over one sheet, Kokkoja
+puts the sheet between their computers.
+
+Its ideal use, and the one it was made for first, is teaching a foreign
+language over a video call.  The teacher puts a scanned exercise on the
+page.  The student fills it in by hand or by typing, during the lesson,
+while the teacher watches, corrects mistakes as they are made, and adds
+notes in the margin.  Each correction is in the teacher's own hand and
+colour, on the teacher's own layer, where the student cannot change it.
+When the lesson is over, the student's notebook holds every exercise of
+the lesson, with the student's answers and the teacher's corrections
+together on one page, and the teacher's notebook holds the same pages as
+a record of what the student was given.  The teacher's notebooks of
+exercises become a library: loading a page from one of them puts a fresh
+copy in front of a new student, and the original is never changed.
+
+## Hosts and guests
+
+A session has one *host*, the person who starts it, and any number of
+*guests*.  In a lesson the teacher is the host and the students are the
+guests.  The host sends the guests an invitation, by email, in a chat
+message, or by any other means.  The host *drives*: only the host puts
+images on the page, starts new pages or loads pages from a notebook, and
+everyone follows.  The host can give any guest the same abilities, for a
+discussion among colleagues.
+
+The rest of this documentation describes Kokkoja from the guest's point of
+view first, since the host sees the same screen and has a few more
+buttons, then from the host's, and finally explains how it works
+underneath, for those who want to run their own server or read the code.
+
+* [A guest's Kokkoja](guest.md)
+* [A host's Kokkoja](host.md)
+* [How Kokkoja works](implementation.md)