@geekity/cms 0.27.0 → 0.29.0

package/README.md

@@ -86,26 +86,27 @@ message on a site whose `site.json` has not set a period.
 site (or `npx geekity`, or a `package.json` script, which is how the generated
 `sync` script calls it).
 
-| Command                                   | What it does                                                                                                                                                                       |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `geekity serve`                           | Boot from the config file and listen, in a worker the command supervises: Reload on the Plugins screen replaces it, and a crash respawns it. The default when no command is given. |
-| `geekity init <dir>`                      | Create a new site in `<dir>`. Refuses a directory that is not empty.                                                                                                               |
-| `geekity sync`                            | Rebuild the content index once and exit. Exits non-zero if any file could not be parsed.                                                                                           |
-| `geekity rebuild`                         | Delete `data/geekity.db` and build it again from the files.                                                                                                                        |
-| `geekity resend --all`, `<slug>...`       | Send announced posts to every follower and relay again, as they now read. See [Quote posts](#quote-posts).                                                                         |
-| `geekity maintenance on`, `off`, `status` | Take the public site down on purpose with a 503 and `Retry-After`, or bring it back, without a restart. `on --until <time>` names when it should be back.                          |
-| `geekity strip-metadata`                  | Remove location and camera metadata from files already in `content/uploads`. See [The media library](#the-media-library).                                                          |
-| `geekity user add <name>`                 | Create an admin account, so a site can get its first login without the setup screen.                                                                                               |
-| `geekity plugin add <package>`, `remove`  | Install a plugin package's bundle from the npm registry into the plugins folder (`GEEKITY_PLUGINS_DIR`), or delete a disabled one. Reload on the Plugins screen loads the change.  |
-| `geekity --help`, `-h`                    | The same table, on the terminal.                                                                                                                                                   |
-| `geekity --version`                       | The installed version.                                                                                                                                                             |
+| Command                                   | What it does                                                                                                                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `geekity serve`                           | Boot from the config file and listen, in a worker the command supervises: a change to the plugins folder replaces it, and a crash respawns it. The default when no command is given.  |
+| `geekity init <dir>`                      | Create a new site in `<dir>`. Refuses a directory that is not empty.                                                                                                                  |
+| `geekity sync`                            | Rebuild the content index once and exit. Exits non-zero if any file could not be parsed.                                                                                              |
+| `geekity rebuild`                         | Delete `data/geekity.db` and build it again from the files.                                                                                                                           |
+| `geekity resend --all`, `<slug>...`       | Send announced posts to every follower and relay again, as they now read. See [Quote posts](#quote-posts).                                                                            |
+| `geekity maintenance on`, `off`, `status` | Take the public site down on purpose with a 503 and `Retry-After`, or bring it back, without a restart. `on --until <time>` names when it should be back.                             |
+| `geekity dev-mode on`, `off`, `status`    | Hold everything the site would send to the outside world while it is built or migrated, or take it live. See [Dev mode](#dev-mode).                                                   |
+| `geekity strip-metadata`                  | Remove location and camera metadata from files already in `content/uploads`. See [The media library](#the-media-library).                                                             |
+| `geekity user add <name>`                 | Create an admin account, so a site can get its first login without the setup screen.                                                                                                  |
+| `geekity plugin add <package>`, `remove`  | Install a plugin package's bundle from the npm registry into the plugins folder (`GEEKITY_PLUGINS_DIR`), or delete a disabled one. A running `geekity serve` reloads with the change. |
+| `geekity --help`, `-h`                    | The same table, on the terminal.                                                                                                                                                      |
+| `geekity --version`                       | The installed version.                                                                                                                                                                |
 
 An installed plugin may add commands of its own, which `geekity --help` lists
 under _Plugin commands_ and which run whether or not the plugin is enabled.
 That includes a plugin in the plugins folder. The repository README's
 _Plugins_ section describes `geekity plugin add` and writing a plugin.
 
-`serve`, `sync`, `rebuild`, `resend`, `maintenance`, `strip-metadata`, `user add`, `plugin` and every plugin command take
+`serve`, `sync`, `rebuild`, `resend`, `maintenance`, `dev-mode`, `strip-metadata`, `user add`, `plugin` and every plugin command take
 `--config <file>`; without it they look for `geekity.config.ts`, then
 `geekity.config.js`, then `geekity.config.mjs` in the working directory, and run
 on defaults if there is none.
@@ -289,6 +290,7 @@ directory; absolute ones are used as given.
 | `accessLogAddress` | `false`                               | `GEEKITY_ACCESS_LOG_ADDRESS` | Put the client address on the end of each access-log line. `trustProxy` decides which address that is.                                                                                                                                                          |
 | `accessLogWriter`  | stdout                                | —                            | Where the lines go instead. See [The access log](#the-access-log).                                                                                                                                                                                              |
 | `maintenance`      | `false`                               | `GEEKITY_MAINTENANCE`        | Keep the site in maintenance mode, answering 503, until a restart without it.                                                                                                                                                                                   |
+| `devMode`          | `false`                               | `GEEKITY_DEV_MODE`           | Start the site in dev mode, which holds every outbound side effect until `geekity dev-mode off`. See [Dev mode](#dev-mode).                                                                                                                                     |
 | `compression`      | `true`                                | `GEEKITY_COMPRESSION`        | Compress text responses with brotli or gzip. Turn it off behind a proxy that compresses. See [Compression](#compression).                                                                                                                                       |
 | `securityHeaders`  | [see below](#security-headers)        | —                            | Headers every response carries. A string replaces a default or adds a header, `false` removes one.                                                                                                                                                              |
 | `onDocumentChange` | none                                  | —                            | Hook run for every change to the index. See [Hooks](#hooks).                                                                                                                                                                                                    |
@@ -426,7 +428,7 @@ something a site is told it may lose:
 | `ap_deliveries`                                     | Nothing. The federation screen shows its posts with "Nothing recorded."      |
 | `ap_relays`                                         | The relay list in `site.json`: boot sends each of them a fresh `Follow`.     |
 | `password_resets`, `spent_tokens`                   | Nothing. Every reset link and every one-click moderation link stops working. |
-| `cms_state`                                         | Nothing. One key, the scheduler's watermark.                                 |
+| `cms_state`                                         | Nothing. The scheduler's watermark and its first run.                        |
 | `migrations`, `admin_migrations`                    | The package. They record which schema versions have run.                     |
 
 So four things are actually lost:
@@ -681,6 +683,50 @@ database.
 
 [FEP-044f]: https://codeberg.org/fediverse/fep/src/branch/main/fep/044f/fep-044f.md
 
+### Replies to fediverse replies
+
+Somebody who answers a fediverse reply on one of the site's posts addresses
+the person they answer, not the site, so their reply never reaches the inbox.
+Most servers list a note's replies in its `replies` collection, and the site
+reads those collections to bring such replies in. The sweep starts when
+the site serves and runs every hour, within these limits:
+
+| Limit    | Value    | Meaning                                                                                               |
+| -------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| Interval | 6 hours  | How long a thread is left alone after it was read.                                                    |
+| Age      | 30 days  | How old a post gets before its thread is no longer read, by the post's date.                          |
+| Depth    | 4 levels | How far below the post a fediverse reply may sit and still have its collection read.                  |
+| Pages    | 3        | How many pages of one collection are read. Mastodon's first page holds the author's own replies only. |
+
+Every request is signed as the site's first account, as the actor profile
+fetches are. A reply is kept only when it answers the note whose collection
+listed it, is addressed to the public, and is written by an actor on the
+note's own server. A note on the site's own origin is never fetched, because
+the site already knows what it published.
+
+A reply found this way is logged as the `Create` nobody delivered: a line in
+`content/_data/federation/inbox/{yyyy}-{mm}.jsonl` with `"fetched": true` in
+front of it, an `actor` taken from the note's `attributedTo` and the id
+`{note id}#fetched`. From there it is a reply like any other. It is threaded
+under the reply it answers with its own URL, counted, given a `/replies/` feed
+and listed on the federation screen, and its author's `Delete` takes it back.
+A note held once is never logged twice. The sweep skips a note the inbox
+already holds, and a delivery of a note the sweep fetched first replaces the
+fetched line.
+
+The site removes a fetched reply, with the fetched replies under it, when its
+server answers 404 or 410 for it, or when a collection read to its end no
+longer lists it. A delivered reply is never removed this way. A note with no
+`replies` collection, a server that answers with any other error, and a
+collection cut off by the page limit change nothing. The thread keeps what it
+holds, and the sweep goes on to the next reply.
+
+The site reads `replies` and not the conversation a note names in `context`
+([FEP-7888]), because Mastodon publishes `replies` and few servers publish a
+`context` collection yet.
+
+[FEP-7888]: https://codeberg.org/fediverse/fep/src/branch/main/fep/7888/fep-7888.md
+
 ### Relays
 
 A [Mastodon-style relay][fepae0c] boosts every public activity it is sent on to
@@ -790,9 +836,9 @@ ignored.
 
 A site that moved here from the WordPress ActivityPub plugin keeps its people's
 actor ids and its posts' object ids, which are identity and are the CMS's own
-(above). What it needs for a while besides is the plugin's old paths, which
+(above). What it needs besides is its content, the plugin's old paths, which
 followers' servers keep delivering to until they refetch the actor, and an
-import that brings each person's key pair and followers across. Both are the
+import that brings each person's key pair and followers across. All three are the
 [`@geekity/plugin-wordpress`](../plugin-wordpress/README.md) package, which a
 site born on the CMS never installs. decision-14's switch is that plugin now:
 where the cutover used to say "turn the switch on", it says install and enable
@@ -800,27 +846,43 @@ the WordPress plugin.
 
 #### The cutover, end to end
 
-1. **Export, while the WordPress site is still up.** Each person's key pair,
+1. **Start the new site in dev mode.** Set `GEEKITY_DEV_MODE=true` before
+   its first boot (see [Dev mode](#dev-mode)). Followers, relays, links and
+   mail are all real from here on, and dev mode keeps every one of them from
+   hearing about the import, the edits or a scheduled post until step 4.
+2. **Export, while the WordPress site is still up.** Each person's key pair,
    and the followers if the old site is going away before the import runs. The
    plugin's README says how. Note the actor id and the numeric actor id off
-   `https://example.com/?author=2`, and bring the content across.
-2. **Install the WordPress plugin and import.** Add `@geekity/plugin-wordpress`
-   to the site's dependencies and to `plugins` in its config, then run `geekity import
-wordpress-actor ada --actor-id … --wordpress-id … --keypair ada.keypair.json`.
-   The command works before the plugin is enabled. Check the report: every
-   follower should be added, and any that were skipped should be re-run once
-   their servers answer.
-3. **Enable the WordPress plugin.** Enable it under `/admin/plugins`, then move
-   the DNS. Followers' servers go on delivering to
-   the plugin's old inbox paths until they next refetch the actor, and the
-   plugin is what catches those deliveries.
-4. **Watch.** `/admin/federation` lists the users with their actor ids and
+   `https://example.com/?author=2`, take a WXR export under Tools > Export,
+   and copy `wp-content/uploads`, which the export does not carry.
+3. **Install the WordPress plugin and import.** Add `@geekity/plugin-wordpress`
+   to the site's dependencies and to `plugins` in its config, then run
+   `geekity import wordpress example.WordPress.xml --uploads wp-content/uploads`
+   for the content and media, and
+   `geekity import wordpress-actor ada --actor-id … --wordpress-id … --keypair ada.keypair.json`
+   for each person. Both work before the plugin is enabled. Check the reports:
+   every post should be written, every conflict or clash resolved, every
+   follower added, and any follower that was skipped re-run once its server
+   answers. Tools > Dev mode shows that the imports sent nothing. Both imports
+   are safe to run again: run them over a fresh export just before step 4 to
+   pick up what WordPress received in the meantime.
+4. **Enable the WordPress plugin, move the DNS and go live.** Enable it under
+   `/admin/plugins`, then move the DNS. Remove `GEEKITY_DEV_MODE` and run
+   `geekity dev-mode off`: nothing held during the migration is sent.
+   Followers' servers go on delivering to the plugin's old inbox paths until
+   they next refetch the actor, and the plugin is what catches those
+   deliveries. Once WordPress no longer answers, run both imports one last time
+   over its final export: they merge what arrived between the export and the
+   DNS move, and leave alone whatever this site wrote or edited since.
+5. **Watch.** `/admin/federation` lists the users with their actor ids and
    followers; the plugin's own screen under Plugins lists each old path with
    the instant it was last asked for. Deliveries should thin out as each
    follower's server refetches the actor and learns the new endpoints.
-5. **Disable it.** Once every path says _Never_ again for long enough — weeks
+6. **Disable it.** Once every path says _Never_ again for long enough — weeks
    rather than days, since a quiet instance refetches rarely — disable the
-   plugin. The paths go away on the very next request, with nothing restarted,
+   plugin. Disabling it also ends the redirects from the old
+   `/wp-content/uploads/` media URLs, so a site that still gets links to
+   those keeps it enabled. The paths go away on the very next request, with nothing restarted,
    and if something was still using them you can enable it again just as
    quickly.
 
@@ -918,13 +980,95 @@ half is sent by a peer built in the script rather than by `fedify inbox`.
 [Fedify]: https://fedify.dev/
 [`fedify tunnel`]: https://fedify.dev/cli
 
+## Dev mode
+
+Building or migrating a site means running it with production data: the real
+base URL, the real actor and keys, real followers, real links. Dev mode keeps
+that site quiet until you take it live (decision-35). While it is on, nothing
+the site does reaches the outside world:
+
+- No ActivityPub delivery to followers or relays, no relay `Follow` or `Undo`,
+  and no `Accept` or `Reject` answering an inbox. This holds whatever caused
+  the change: the watcher, the admin, the scheduler, `geekity resend` or a
+  reply context arriving.
+- No webmention. Endpoint discovery is skipped too.
+- No rssCloud or WebSub ping.
+- No IndexNow submission.
+- No email.
+
+Reads still go out: reply contexts and cited pages, actor profiles, oEmbed,
+avatars, the check of an incoming webmention, and a plugin's `host.fetch`. A
+read tells nobody about the site, and without them it could not show its
+replies or profiles. Inbound federation is accepted: follows, replies, likes
+and webmentions are stored as on a live site, and the `Accept` a follow would
+get is held. Plugins need no switch of their own. A plugin's federation hands
+what it receives to the site's inbox, so its answers are held the same way.
+
+Each held side effect is a line in `data/dev-mode.jsonl`: when, what kind,
+what would have been sent, and to whom. Tools > Dev mode in the admin lists
+them, newest first. Every admin screen shows a banner while the mode is on,
+and `geekity serve` says so when it boots.
+
+```sh
+$ geekity dev-mode on
+Dev mode is on: nothing the site does is sent until `geekity dev-mode off`.
+$ geekity dev-mode status
+Dev mode is on.
+$ geekity dev-mode off
+Dev mode is off: the site is live. Nothing held while it was on will be sent.
+```
+
+`devMode: true` in the config, or `GEEKITY_DEV_MODE=true`, starts a site in
+dev mode: boot writes `data/dev-mode.json`, and the file keeps the mode on
+from then on. Losing the variable does not take the site live. Only
+`geekity dev-mode off` does, and it refuses while the config or the
+environment still asks for dev mode, because the next boot would turn it on
+again. The running site checks the file before every send, so going live
+needs no restart, unless the server was started with the variable: that
+process stays in dev mode until it restarts without it. Going live is a line
+in the record too.
+
+Going live replays nothing. A held side effect is dropped, not queued, and no
+delivery or webmention is recorded as failed, so neither the Federation screen
+nor `geekity resend` offers it again. A post announced while the mode was on
+counts as announced, so its next edit goes out as an `Update`. A relay listed
+while the mode was on stays pending: press Retry on the Federation screen once
+the site is live.
+
+Password recovery mail is held too, so in dev mode a password is reset from
+the shell. A peer that followed while the mode was on never got its `Accept`,
+and has to follow again.
+
+### Dev mode on Docker
+
+Set the variable in the service's environment before the first boot, so the
+container never starts live:
+
+```yaml
+services:
+  geekity:
+    environment:
+      GEEKITY_DEV_MODE: 'true'
+```
+
+To go live, remove the variable, recreate the container (the file in the
+`data` volume keeps the mode on through the restart), then run:
+
+```sh
+docker compose exec geekity geekity dev-mode off
+```
+
+`geekity dev-mode status` in the same container says which state the site is
+in. The record is in the `data` volume at `data/dev-mode.jsonl`.
+
 ## Comments
 
 A reader can answer a post on the page, and what they leave joins the same
 thread as the fediverse replies rather than sitting in a section of its own.
 
 A comment is a file. `content/_data/comments/{slug}.json` holds one post's
-comments — id, source, kind, status, author, the Markdown and the HTML it
+comments (a slug that is not plain ASCII is percent-encoded in the name, so
+`i-♥-rss` is `i-%E2%99%A5-rss.json`) — id, source, kind, status, author, the Markdown and the HTML it
 rendered to, when it was submitted, a salted hash of the address, and what it
 answers — so they are in git beside the posts, an Eleventy build of the same
 directory shows them, and the `comments` table is an index emptied and read
@@ -975,6 +1119,68 @@ A checker that throws is treated as having no opinion and logged, so a service
 that is down never stops a site taking comments. `/admin/comments` is the
 moderation queue and the dashboard carries the number waiting.
 
+### A comment's own page
+
+A comment left through the form has a page of its own at `/comment/{id}/`,
+the comment's id percent-encoded. That page is the comment's URL in the thread
+and in both comments feeds, so a site that replies to the comment fetches the
+comment rather than the whole post. The `#comment-{id}` anchor on the post
+stays, so an old link still scrolls to it. A webmention or a fediverse reply
+has no such page: its URL is where it came from.
+
+The page holds the comment as its one `h-entry`, with `u-in-reply-to` the post
+or the comment it answers. Above it is the thread from the post down, each step
+a nested `u-in-reply-to h-cite`, and below it the replies to it at every depth.
+An ancestor a reader may not see is a placeholder saying the comment is no
+longer shown, and the thread on the post prints the same placeholder above an
+approved reply to a pending, spam or deleted comment. The page answers only an approved comment, and only as the post
+would: 410 once the post is deleted, 404 while the post is not public or not
+showing its conversation. It is `noindex` and absent from the sitemap, the post
+feeds and search. Backlog doc-6 has the rules.
+
+### Replying while signed in
+
+A comment is something somebody else says on the site. A post is something a
+signed-in user says. So a reply written by somebody signed in to the site, in
+the thread or in the Reply box on the moderation screen, is a reply post, not a
+comment. It is one file under `posts/`, saved
+the way the editor and Micropub save one, and the thread shows it inline under
+what it answers. Its `in-reply-to` is what it answers:
+
+| Answering          | `in-reply-to`                     | It also                                                  |
+| ------------------ | --------------------------------- | -------------------------------------------------------- |
+| The post           | The post's permalink              |                                                          |
+| A native comment   | The comment's `/comment/{id}/`    | Emails the commenter once, if they asked about replies.  |
+| A webmention reply | The page the webmention came from | Sends that page a webmention.                            |
+| A fediverse reply  | The note's id                     | Federates in reply to the note, addressed to its author. |
+| A reply post       | The reply post's permalink        |                                                          |
+
+The signed-in form and the moderation screen's Reply box have an "Include in
+posts and feeds" checkbox, unchecked by default. Unchecked, the reply post is [unlisted](#unlisted-posts): its own page
+and the thread, but no listing or post feed. Checked, it is public. It reaches
+whoever it answers either way. A visitor's form has no such box.
+
+Somebody signed in gets a Reply link on every reply in a thread, webmentions
+and fediverse replies included. A visitor gets one on native comments only. A
+visitor's reply is always a native comment, so a visitor answering a fediverse
+reply sends nothing over ActivityPub.
+
+A reply post written in the editor or over Micropub joins a thread the same way
+when its `in-reply-to` names the post or anything in its thread: a comment's
+page or `#comment-` anchor, a webmention's page, a note's id. Its reply context
+quotes that comment from the site's own records instead of the page it is on,
+and says "In reply to a comment by" its writer. A reply post answering one of
+the site's own posts or pages takes that post's title, words and author from
+the index too, so the site never fetches its own page. The commenter's email
+goes once for a reply post from any of these doors, sent when the reply post is
+first published and never again when it is edited, trashed and restored, or the
+site restarts. In the thread, a reply post's author link carries no
+`rel="nofollow ugc"`, which is kept for visitors, webmentions and the
+fediverse. A
+webmention or a fediverse reply to a reply post threads under it in the
+original thread too. Comments written before this stay comments. Backlog doc-6
+and decision-47 have the rules.
+
 ### Being told about one
 
 With mail configured, a comment or a webmention entering the queue emails every
@@ -1107,6 +1313,19 @@ it was showing. One outcome is recorded per link (`sent`, `none` for a page that
 takes none, or `failed`), shown per post on `/admin/federation`, and the Resend
 button there sends them again from the file as it now reads.
 
+**Links to the site's own pages** send no webmention. A post that cites another
+post on the same site does not go through moderation, does not add to a comment
+count and does not make an HTTP request to the site itself. The index records
+the link instead. The linked post or page then lists the linking one among its
+backlinks, which the default theme prints as "Linked from" under it, apart from
+the comments. A link counts for the document the site serves at its URL: a link
+to `/` counts for the page the Reading setting makes the homepage, and a link
+to a URL the site redirects, such as an imported `/?p=123`, counts for the
+document the redirect leads to. Redirects are followed when the backlinks are
+read, so editing a redirect file moves a backlink without touching the post
+that holds the link. A draft, future-dated, unlisted, private or trashed post is never
+a backlink. See `themes/default/README.md` for the `backlinks` context.
+
 **Receiving** advertises `/_geekity/webmention` two ways — a `Link` header on
 every representation of a document, and a `<link rel="webmention">` in the head
 — and takes a form `POST` of `source` and `target`. It answers `202` for
@@ -1119,6 +1338,12 @@ queue as everything else — through the same `commentChecker` seam, so a checke
 can tell one from a form submission by its `source`. Akismet is told it is a
 `webmention` rather than a `comment`.
 
+A reply whose `u-in-reply-to` names a reply already on the post (a comment by
+its own page or its `#comment-{id}` anchor, an earlier webmention by the page it
+was sent from, a fediverse reply by its url or id) threads under that reply, and
+moves with it when the source is edited and sent again. A webmention sent to a
+comment's page, `/comment/{id}/`, lands on that comment's post.
+
 The source URL is its identity. A page that sends its webmention again updates
 what it left rather than adding a second, and one whose link has gone — or which
 answers 404 or 410 — takes it away. Closing rules do not apply: a post that
@@ -1687,8 +1912,8 @@ The rule works for pages too.
 | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | Its permalink, in every representation                                     | 200, with `X-Robots-Tag: noindex`. The default theme also prints `<meta name="robots" content="noindex">`.                                   |
 | The home page, tag, category and author archives, the `archive: true` page | Absent, and not counted in a pager or a tag count.                                                                                           |
-| Previous and next links under other posts, the front page's recent posts   | Absent.                                                                                                                                      |
-| Every RSS, Atom and JSON feed, and the site-wide comments feed             | Absent. Saving one pings no notify server.                                                                                                   |
+| Previous and next links under other posts, a front page's `newestPosts`    | Absent.                                                                                                                                      |
+| Every RSS, Atom and JSON feed, and the site-wide comments feed             | Absent. Saving one pings no notify server. An unlisted reply post shown in a thread is still in that thread's comments feeds.                |
 | The sitemap, search (HTML and JSON) and `llms.txt`                         | Absent.                                                                                                                                      |
 | IndexNow                                                                   | Not submitted. A public post that becomes unlisted is submitted once, so a search engine reads the `noindex`.                                |
 | The ActivityPub outbox and featured collection                             | Absent.                                                                                                                                      |
@@ -2032,9 +2257,38 @@ choice is WordPress's own, and so are its two answers:
   the default, and it is what an empty `homepage` means.
 - **A static page.** The page is served at `/`, its own permalink answers `301`
   to `/` so the front page has one URL, and the menu links it at `/`. The
-  default theme draws it with `layouts/front-page.njk` — the page's own words,
-  then `Recent Posts`, then the line of links and the bio — and a theme lays it
-  out differently by overriding that one file.
+  default theme draws it with `layouts/front-page.njk`, which prints the
+  page's own title and words and nothing else (decision-44). It lists no
+  posts, prints no links and prints no bio.
+
+A site that wants more on its front page, such as its newest posts or links
+to its archives, overrides `layouts/front-page.njk` in its own theme. The
+front page's context carries `newestPosts(count)`, a function that returns the
+newest `count` published posts as the same entries a listing prints. Drafts,
+future-dated, unlisted and trashed posts are left out. The theme chooses the
+count, and the query runs only when the theme calls it. For example, this
+override lists the five newest posts under the page's words:
+
+```njk
+{% extends "layouts/base.njk" %}
+
+{% block content %}
+<div class="page-body e-content">{{ content | safe }}</div>
+
+<h2 class="section-title">Recent Posts</h2>
+{% set posts = newestPosts(5) %}
+{% set feedHeading = 3 %}
+{% include "partials/post-list.njk" %}
+{% endblock %}
+```
+
+On a solo author site the default theme's base layout puts the author's
+`rel="me"` claims in the head of `/` as `<link rel="me">` elements, one for
+their author archive and one for each profile link, whatever the front page
+prints (decision-45). A static front page prints no h-card. A site that wants
+its homepage to carry a representative h-card writes one in the homepage's
+words, or includes `partials/bio.njk` with `bioHome` set in its override, as
+the [theme README](./themes/default/README.md#the-front-page) shows.
 
 With a homepage set, a second pick gives the listing a page of its own: the
 **posts page**. Its permalink carries the listing, with the page's own title
@@ -2439,6 +2693,11 @@ export default defineConfig({
 A name that is not a header name, or a value that is empty or has a line break
 in it, stops the site at boot. There is no environment variable for these.
 
+A policy that limits scripts has to allow whatever the site's theme adds to
+every page. For the Umami and Google Analytics snippets, the theme README's
+[Adding to every page](./themes/default/README.md#adding-to-every-page) lists
+the directives each one needs.
+
 Every response under `/admin`, static files and redirects included, gets three
 stricter values in their place, whatever `securityHeaders` says:
 
@@ -2558,6 +2817,7 @@ Booting mounts the public site on the app. The routes are:
 | `/author/{username}/feed/` and siblings | The same, for one person.                                                                                              |
 | `/comments/feed/`                       | Every reply the inbox has been sent, as RSS 2.0.                                                                       |
 | `{permalink}feed/`                      | One post's replies, the same way.                                                                                      |
+| `/comment/{id}/`                        | One comment left through the form, on a page of its own: see [Comments](#comments). Noindex and on no list.            |
 | `/sitemap.xml`                          | Every public URL, for a search engine.                                                                                 |
 | `/sitemap-{n}.xml`                      | One file of a sitemap too big to be a single one.                                                                      |
 | `/robots.txt`                           | What a crawler may have, and where the sitemap is.                                                                     |
@@ -2742,9 +3002,20 @@ The list is in the file, so deleting `data/geekity.db` keeps it working.
 
 A URL in the list only redirects while nothing else lives there: a new document
 given that URL takes it over. Moving a document back to a URL in its list takes
-that URL off the list. A draft that was never published moves without leaving
-anything behind. Correcting a published post's date files it under the new
-day but keeps its URL.
+that URL off the list. A draft that was never published and has no comments
+moves without leaving anything behind; one with comments was read at its URL,
+so it keeps a `redirect_from` like a published one. Correcting a published
+post's date files it under the new day but keeps its URL.
+
+A moved document keeps its conversation. Its comments and stored webmentions
+move to its new slug, a reply post answering any URL in its `redirect_from`
+stays in its thread, and its feeds keep their guid: a post keeps its object id
+as its `activitypub.id`, and a page keeps the URL it left as its `guid`, so the
+`/replies/` feed a reader subscribed to keeps answering. The record of the
+webmentions a post has sent moves with it too. A move made by hand is followed
+the same way when the file names the old URL in `redirect_from`; a permalink
+changed by hand with no `redirect_from` leaves the old URL answering 404 and its
+comments where they were, until the file names it.
 
 ### Declared redirects
 
@@ -2797,6 +3068,25 @@ first request after the file changes, and it is skipped. The following entries a
 A file that is not a JSON list serves no redirects and is reported the same
 way.
 
+#### More than one file
+
+Every `*.json` file in `content/_data/redirects/` is read after
+`redirects.json`, in name order, and served the same way. A tool that generates
+redirects, such as an import, writes a file of its own there and never touches
+the list a person keeps. A file there, or `redirects.json` itself, may also be
+an object that maps each `from` to its `to`, every one a `301`:
+
+```json
+{
+  "/?p=123": "/2026/01/hello/",
+  "/old-section/": "/new-section/"
+}
+```
+
+Where two files declare the same `from`, the one read first wins, so
+`redirects.json` wins over every file in the folder, and the other declaration
+is reported. A loop across files is found and skipped as within one.
+
 Every redirect the CMS sends carries `X-Redirect-By: Geekity CMS`. This
 includes the declared redirects, moved URLs, trailing slashes, feed spellings
 and the admin's redirects. Someone who traces a chain of redirects through a
@@ -2941,6 +3231,7 @@ so a site moving off it keeps every subscriber it had:
 | `/category/{name}/feed/` | One category archive, the same three             |
 | `/comments/feed/`        | Every reply the site has been sent, in RSS       |
 | `{permalink}feed/`       | One post's replies, in RSS                       |
+| `/replies/{id or key}/`  | One item's direct replies, in RSS                |
 
 `/feed/` is RSS because that is the format nearly every existing subscriber
 holds. The two archive bases are settings (`tagBase`, `categoryBase`), so the
@@ -2980,15 +3271,17 @@ The three formats render one **feed item**, derived once per post, rather than
 each reading the file for itself. So they agree about the three things a reader
 actually keys on.
 
-**Identity.** A post is named by its ActivityStreams object id, which is its
-permalink (see [Federation](#federation)) or the `activitypub.id` the front
-matter stores for a post migrated from elsewhere. That id is RSS's `guid`,
-Atom's `id` and JSON Feed's `id`. The permalink is always the link: RSS's
-`link`, Atom's `link rel="alternate"` and JSON Feed's `url`. The two are the
-same URL for every post born on this CMS, and differ only for one carrying a
-stored id — which is what lets a migrated post keep the name its WordPress
+**Identity.** A post is named by the first of three things it has: the `guid`
+its front matter sets, when that parses as a URL; else the `activitypub.id`
+the front matter stores for a post migrated from elsewhere; else its permalink
+(see [Federation](#federation)). That name is RSS's `guid`, Atom's `id` and
+JSON Feed's `id`. The permalink is always the link: RSS's `link`, Atom's
+`link rel="alternate"` and JSON Feed's `url`. The two are the same URL for
+every post born on this CMS, and differ only for one carrying a stored id or a
+`guid` — which is what lets a migrated post keep the name its WordPress
 subscribers already hold. RSS's `isPermaLink` says which of the two a `guid`
-is: `true` when it is the permalink, `false` for a stored id like `?p=813`.
+is: `true` only when it equals the permalink, `false` for anything else, such
+as a stored `?p=813`.
 
 **Terms.** Every format lists the post's categories and then its tags, in file
 order, as one flat list: RSS's `category` elements, Atom's `category term`
@@ -3025,8 +3318,8 @@ do not know it to ignore:
 The key is `_geekity` because an extension is named after its publisher, and
 `in_reply_to` spells the microformats `in-reply-to` property the JSON way. A
 post that is not a reply, or whose `in-reply-to` is not such a URL, carries
-neither. RSS 2.0 has no equivalent element, so an RSS item for a reply is
-written the same as any other.
+neither. RSS 2.0 has no equivalent element, so an RSS item carries the target
+as the [source namespace][source-ns]'s `<source:inReplyTo>`.
 
 **Languages.** Every feed declares the site's `language` once: RSS as the
 channel's `language`, Atom as the feed's `xml:lang` and JSON Feed as its
@@ -3056,17 +3349,21 @@ avatar when the site has one.
 An item carries `title`, `link`, `guid`, `pubDate` in RFC 822, `dc:creator` from
 the post's author or the site's, one `category` per term, `description` holding
 the summary, `content:encoded` holding the whole rendered post, and
-`source:markdown` holding the Markdown the post was written from. The `guid`,
-the terms and the summary are the ones described above.
+`source:markdown` holding the Markdown the post was written from. A reply also
+carries `source:inReplyTo` holding the URL it answers. The `guid`, the terms
+and the summary are the ones described above.
 
 `source:markdown` is Dave Winer's [source namespace][source-ns]: a reader that
 understands Markdown should render from it rather than from `content:encoded`.
 It is the same text the ActivityStreams `Article` carries as its `source`.
 
-Every item also says where its comments are, three ways: `comments` is the page
-to read them on, `wfw:commentRss` (the [Well-Formed Web][wfw-ns] comment API) is
-the feed to poll, and `source:comments` is that same feed with a `count`
-attribute, so a reader can say "3 comments" without fetching anything.
+Every item also says where its comments are: `comments` is the page to read
+them on and `wfw:commentRss` (the [Well-Formed Web][wfw-ns] comment API) is the
+feed of the whole thread to poll. A post with replies also carries
+`source:comments`, whose `count` is how many replies answer the post directly
+and whose `feedUrl` is its `/replies/{key}/` feed holding only those (see
+[Walking a thread](#walking-a-thread)). A post nobody answered carries no
+`source:comments`.
 
 When the site has a license (Settings > General, or `license` in `site.json`),
 the channel carries a `creativeCommons:license` holding its URL, and every item
@@ -3087,34 +3384,68 @@ post as under it.
 
 ### Comments
 
-This CMS stores no comments of its own. What it has instead is the fediverse
-replies its inbox has been sent: a `Create` of a `Note` whose `inReplyTo` names
-a post's ActivityStreams object id (see [Federation](#federation)). Those are
-what the comments feeds publish, at the URLs WordPress publishes its own at —
-`{permalink}feed/` for one post, `/comments/feed/` for the whole site.
+The comments feeds publish a document's conversation, at the URLs WordPress
+publishes its own at: `{permalink}feed/` for one post or page, and
+`/comments/feed/` for the whole site. Both are read from the same conversation
+the page draws under the post, so they carry what a reader sees there:
+
+- native comments left through the form, once a moderator approves them;
+- webmention replies and mentions;
+- fediverse replies, a `Create` of a `Note` whose `inReplyTo` names the post
+  or a reply under it (see [Federation](#federation)), and the quotes of a
+  post its author approved;
+- reply posts written on this site that answer the post or a reply under it.
+
+Likes, boosts and reposts are counted on the page and are in no feed.
 
 Both are RSS 2.0 and nothing else: a comments feed has no Atom or JSON spelling
-here, so `{permalink}feed/atom/` 404s. A post with no replies answers an empty
-feed rather than a 404 — it exists, and a reader that subscribed before anybody
-answered should keep polling — while a permalink that is no published post 404s
-like any other. A page has no comments feed at all: only posts federate, so
-nothing can ever have replied to one.
+here, so `{permalink}feed/atom/` 404s. A post has a comments feed whether or
+not it still takes comments. A page has one while it takes comments
+(`comments: true` in its front matter, and comments on for the site), which is
+when it shows its conversation; any other page's `{permalink}feed/` 404s, and
+its comments are left out of `/comments/feed/` too. A document with no replies
+answers an empty feed rather than a 404, because it exists and a reader that
+subscribed before anybody answered should keep polling. A permalink that is no
+published document 404s like any other. The page advertises its own feed with
+a `<link rel="alternate" type="application/rss+xml">` in its `<head>`.
 
 A channel carries the usual `title` (`Comments on: {post}`), `link`,
 `description`, `language`, `lastBuildDate`, `generator`, `atom:link rel="self"`
 and the same notify-server elements every other feed carries. An item carries the author's name as its `title` and `dc:creator`,
-the reply's `url` as its `link` and its id as `guid isPermaLink="false"`, the
-`published` time the note gave (or when it arrived, if it gave none),
-`description` holding a plain-text excerpt and `content:encoded` holding the
-note. On the site-wide feed the title names the post as well: `{author} on
-{post}`.
-
-The author's name is the profile the site stored when that actor followed it,
-and otherwise the `@user@host` the actor's own URL implies. Naming them
+the reply's `url` as its `link` (a comment left through the form links to its
+own page at `/comment/{id}/`), a `guid`, the `published` time the reply gave (or
+when it arrived, if it gave none), `description` holding a plain-text excerpt
+and `content:encoded` holding the reply. The `guid` of a comment left through the
+form is its page, `isPermaLink="true"`; any other reply's is its own id: a
+fediverse note's id, a webmention's stored id, a reply post's object id. A
+comment imported from WordPress keeps the `guid` WordPress's comments feed
+published, so a reader sees nothing new after the move.
+`isPermaLink` is `true` exactly when the `guid` is the `link`.
+
+Each item also carries, from the [source namespace][source-ns]:
+
+- `source:inReplyTo`, the `guid` of what it answers in these feeds: the post's
+  feed `guid` for an answer to the post, else the `guid` of the reply it
+  answers. A reply under a comment a reader may not see (one waiting for a
+  moderator, spam or deleted) names the nearest reply above it a reader can
+  see, or the post, and is counted as that one's reply.
+- `source:comments`, only on an item with replies: `count` is how many answer
+  it directly and `feedUrl` its `/replies/` feed.
+- `<source url="…">Name</source>`, the core RSS element, when the site knows a
+  feed for the author: a webmention author's `h-card` URL or site, or a site
+  user's author feed `/author/{username}/feed/`. A comment left through the
+  form and a fediverse reply carry none.
+
+On the site-wide feed the title names the post or page as well: `{author} on
+{post}`, or `{author} replying to {parent author} on {post}` for an answer to
+another reply a reader can see.
+
+A fediverse reply's author is named by the profile the site stored when that
+actor followed it, and otherwise the `@user@host` the actor's own URL implies. Naming them
 properly would mean dereferencing the actor, which is a network round trip per
 comment shown.
 
-**The note's HTML is sanitised before it is published.** It is markup a
+**A reply's HTML is sanitised before it is published.** It is markup a
 stranger wrote, so it is tokenised and rebuilt from an allowlist rather than
 passed through: `p`, `br`, `a`, `em`, `strong`, `del`, `code`, `pre`,
 `blockquote` and the list elements survive; `script` and `style` are dropped
@@ -3123,10 +3454,37 @@ every attribute goes except an `a`'s `href`, which must be `http`, `https` or
 `mailto` and is marked `rel="nofollow noopener noreferrer"`. `sanitizeCommentHtml`
 is exported for a site that shows comments in its own templates.
 
-A reply to a post that has since been unpublished or moved to the trash
-disappears from `/comments/feed/`, and that post's own feed 404s with the post.
+A reply to a document that has since been unpublished or moved to the trash
+disappears from `/comments/feed/`, and that document's own feed 404s with it.
 `feedSize` caps both feeds.
 
+### Walking a thread
+
+`{permalink}feed/` is the whole thread, flat, which is what WordPress
+publishes and `wfw:commentRss` points at. A program that wants the tree
+(Dave Winer's [rss.chat][rss-chat] reads conversations this way) walks it one
+level at a time instead: from a post item's `source:comments` to a feed of the
+replies that answer the post directly, and from each of those items' own
+`source:comments` to the replies that answer it, until an item has none.
+Every reply a reader can see is reached once.
+
+Each of those feeds is at `/replies/{segment}/`, RSS 2.0, newest first, its
+items in the same shape as the comments feeds:
+
+- `/replies/{id}/` for a comment left through the form, by the same id as its
+  page at `/comment/{id}/`, percent-encoded.
+- `/replies/{key}/` for everything else: a post or a page, a webmention, a
+  fediverse reply or a reply post. A document has no id of its own and slugs
+  are not unique across posts and pages, so the key is the first 16 hex digits
+  of the SHA-256 of the item's feed `guid`.
+
+A segment of exactly 16 lowercase hex digits is a key, and anything else is a
+comment id. A comment whose id happens to look like a key is named by its key
+instead, so no segment can name two items. An item nobody answered answers an
+empty feed; a key or an id that names nothing a reader can see 404s.
+
+[rss-chat]: https://github.com/scripting/rss.chat
+
 ### Atom and JSON Feed
 
 An Atom entry carries `id` (the post's object id), `title`, `updated`,
@@ -3416,8 +3774,10 @@ commentsRssFeed({
 
 `conversation.thread(document)` is the same reading for one post — the shape the
 theme's `conversation.njk` is handed — `spokenIn` flattens it into the entries a
-feed carries, and `conversation.counts(documents)` is the number `source:comments`
-puts beside each item of a post feed.
+feed carries, each with the reply it sits under, `conversation.counts(documents)`
+is the number of direct replies `source:comments` puts beside each item of a
+post feed, and `conversation.repliesTo(segment)` is what one `/replies/` feed
+holds.
 
 ## Sitemap and robots.txt
 
@@ -3677,6 +4037,17 @@ The admin is not themed. Its templates and its static files live in a tree of
 their own with a loader of their own, deliberately off this search path, so no
 theme can shadow the login form or the CSRF field inside it.
 
+Analytics and other markup that goes on every page need no layout at all. The
+packaged `layouts/base.njk` includes `partials/head-end.njk` last in `<head>`
+and `partials/body-end.njk` last in `<body>`, both empty in the package, so a
+theme of `theme.json` and `partials/head-end.njk` holding the Umami or Google
+Analytics snippet adds it to every public HTML page and keeps every other
+packaged template. Neither is printed in a feed, a Markdown, text or JSON
+representation, mail, the admin or the editor's preview. The theme README's
+[Adding to every page](./themes/default/README.md#adding-to-every-page) has the
+Umami and GA4 example, the Docker volume, and what a Content-Security-Policy
+has to allow for them.
+
 The packaged theme is the Paper design (doc-9) on the andrewshell.org shell
 (decision-16). Its stylesheet is written in Tailwind v4 in
 `themes/default/src/style.css` and compiled to `themes/default/static/style.css`
@@ -3834,10 +4205,24 @@ Layouts are yours. The directory data files name them — `posts.json` says
 Eleventy layout receives is the one this package's theme mirrors, so a layout
 can often be moved across with only its `{% extends %}` removed.
 
-The feeds are the one thing that does not carry over: `/feed/`, `/feed/atom/`
-and `/feed/json/` are generated in code here, not by a template, so an Eleventy
-build needs its own. `/sitemap.xml` and `/robots.txt` are the same story, and
-for the same reason. Everything else is the same directory.
+The default theme's own layouts and partials build too, copied into
+`content/_includes/` as `layouts/` and `partials/`: the config adds the theme's
+other filters (`absoluteUrl`, `asset`, `host`, `fediverseHandle`) and the
+`newestPosts(count)` a front page override lists posts with, so a site theme's
+`front-page.njk` calling `{% set posts = newestPosts(5) %}` builds. They get
+only the context the config gives, though: `collections.menus` rather than
+`menus`, the `conversation` filter rather than the key, and no comment form,
+search or listing pagination.
+
+Some things do not carry over. `/feed/`, `/feed/atom/` and `/feed/json/` are
+generated in code here, not by a template, so an Eleventy build needs its own;
+`/sitemap.xml` and `/robots.txt` are the same story, for the same reason. A
+comment's own page at `/comment/{id}/` is not written, since a build has no
+server to take a comment, so a comment links to its `#comment-{id}` anchor on
+the post. The site's own reply posts are not threaded under what they answer,
+and a document's backlinks are not listed: both read the CMS's index of every
+document, which the config's filters do not have. The config's header lists
+the same.
 
 ### The compatibility test