The server knows who is writing

On your own machine, folio serve writes each comment as your git user name. On a machine others reach, the server cannot ask git: many people use it. It reads their name from the sign-in in front of it instead. Put the server behind a proxy that signs people in, and name the request header that proxy sets in folio.yaml:

comments:
  identity_header: X-Forwarded-User
From the reader, through the sign-in proxy, to folio serve Reader signs in, comments Sign-in proxy knows who they are folio serve commits as that name X-Forwarded-User: ada request
The proxy adds the header; the charter names it; the server trusts nothing else. Who the reader is never comes from a field they type.

Ask your agent to set it; the configure skill changes the charter. Then start the server on an outside address: folio serve --host 0.0.0.0. Without the header in the charter, or on a request that lacks it, the panel shows the comments read-only and says why. A comment is never taken from someone the server cannot name.

Served asA comment is fromComments
folio serve on your machineyour git user nametaken and committed
folio serve --host 0.0.0.0, header in the charterthe name the proxy's header carriestaken on a request that carries the header
folio serve --host 0.0.0.0, no header in the charternobody the server can nameread-only; the panel says why
folio export, a static siteno server to asknone: no button, no comment files
Read down the last column: comments are taken only where the server can name the writer.
You run folio serve --host 0.0.0.0 and forgot the charter setting. What happens when a reader comments?
Nothing is saved. The panel says comments are read-only here, because the server cannot tell who is writing.

Each comment is a commit

Every new thread and every reply becomes one commit on the current branch. It holds only that page's comment file, its message is "Comment on" and the document's id, and its author is the commenter. Your own work in progress stays untouched, even what you have staged.

On a deployed server, add --push. The server then pulls before it writes and pushes after it commits, so your copy of the library sees the comments with a plain git pull. Step through one comment.

One comment across the reader, the server, its repository, the remote and your copy Reader Server Repository on the server Remote Your copy 1 comment, signed in 2 pull, rebase 3 write the file 4 commit, as the reader 5 push 6 git pull

  1. Step 1 · The reader sends a comment

    A signed-in reader selects a passage and asks. The request reaches the server with the proxy's header naming them.

  2. Step 2 · The server pulls first

    Started with --push, the server pulls from the remote, with rebase, before it writes anything. It writes on top of the latest comments, never beside them.

  3. Step 3 · It writes the comment file

    The thread goes into the page's comment file, beside the document. The page itself is not touched.

  4. Step 4 · It commits that file alone

    One commit on the current branch, holding only that comment file, with the message "Comment on" and the document's id, authored as the reader. Anything else in the repository, staged or not, stays out of it.

  5. Step 5 · It pushes

    The commit goes to the remote, where every copy of the library can fetch it.

  6. Step 6 · Your copy pulls it

    In your own checkout, a plain git pull brings the comment in. Your agent can then go through it like any other.

Each step lights its place in the lanes; later steps stay grey. With scripts off, the lanes show the whole path and the steps read in order below.

Pull and push succeed

The comment is on the remote, authored as the reader, in a commit of its own.

The pull conflicts, or the push fails

The server undoes its write, refuses the comment and shows the reader the error. The reader can send it again; nothing is half saved.

The remote rejects a push while a reader comments. Where is the comment?
Nowhere: the server rolled back its commit and its file change, and the reader saw the error. Nothing was lost in silence; the reader knows to try again.

An exported site takes no comments

folio export writes plain files, with no server behind them. It leaves the comment files out, hides the Comments button and the Review page, and each page's panel says that comments are open where the library is served with folio serve. Publish the export for readers; serve the library for the people who review it.

Served, for reviewers

folio serve: the Comments button on every page, the threads beside each document, the Review page, and each comment committed as its writer.

Exported, for readers

folio export: the same pages, the same shell, no comment files, no button, no Review page, and a line in the panel pointing to where comments are open.

A reader of your exported site wants to ask about a passage. Where do they go?
To the copy you serve with folio serve, signed in. The exported site shows no comments and takes none.