RSS ⧉

Blygger

Venkatesh Rao

The official blyg of the blygger protocol: RFCs open for comment, release announcements from every client, and technical notes. The spec itself lives at blygger.org/spec/.

thread

Where does my change belong? TN-8, a map for contributors

The hackathon is in its second day. Before building anything, it pays to decide where it should go, and the map for that now has a number: TN-8, Where does my change belong?, also an item on this blyg.

It is a ladder of eight questions, asked in order, stopping at the first yes:

  1. Would another blyg or reader receive different bytes? Then it is a spec question, and it is ruled before it is built.
  2. Is it a bug, or something every blyg would want? A pull request to the Studio.
  3. Can it be done from outside, with a token? A tool of your own.
  4. Is it interface for one owner, in a slot that exists? An extension.
  5. Does it need a slot the Studio lacks? A hook, proposed upstream.
  6. Is it several of those together, making a kind of blyg? A mod.
  7. Does it only make sense on your node? A local patch.
  8. Does it change what the Studio is? Another client.

The cheapest place that works is the right one. A tool on a token costs the Studio nothing; a hook costs every future release a little; a local patch costs you a little at every upgrade. The note also walks through your first hour on a local install, the rules that keep a local patch easy to carry, and where to ask.

The guide was first published at blygger.org/contribute/ for the start of the hackathon, and it stays there. Making it a technical note gives it a number to cite, a history of revisions, and an item here you can respond to. If a rung is wrong, or your change fits none of them, respond to this item from your own blyg or open an issue on blygger-spec.

Source: docs/posts/2026-11-21-where-does-my-change-belong.md in blygger-spec, which is where revisions are made. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 22, 2026

thread

TN-8 — Where does my change belong? A contributor's map

Technical note · non-normative · 2026-11-21 (session 78). First written for the 2026 hackathon as blygger-studio/docs/where-does-it-go.md (session 74, 2026-11-18) and published at blygger.org/contribute/; made a note so that it is numbered, cited and announced like the others (Venkat, session 78). It maps where a change belongs across the four repositories, with the Studio as the worked example: the protocol decides nothing here, and other clients may draw their own ladder. Revised as the Studio changes; the studio file is now a pointer to this one.

You have an idea for a blyg: a feature, a fix, a tool, a different look. Before you write any code, decide where it goes. There are eight places, from a request for a protocol ruling to a client of your own. Each has a different cost to you and to everyone else, and a change built in the wrong place is usually rebuilt later.

This page is the map. It links to the documents that explain each place and does not repeat them. If you are new, read the ladder below, then do the first hour.

The ladder

Answer these questions in order and stop at the first yes.

# Question Then it is It goes to
1 Would it change the bytes another blyg or reader receives (an item document, the feed, blyg.json, content_html), or would another client have to change to work with it? A spec question. Nothing is built until it is ruled An issue on blygger-spec
2 Is it a bug, or something every blyg would want with no setting? A pull request to the Studio blygger-studio
3 Can it be done from outside, with a token, through {mount}/api and Settings, with no code inside the Studio? A tool or configuration Your own repository
4 Is it interface for one owner, in the browser, in a slot that already exists? An extension blygger-studio, or your own repository, vendored in
5 Does it need a slot or setting the Studio lacks, in a form any blyg could use? A hook, proposed upstream A pull request to blygger-studio
6 Is it several of 3 to 5 together, making a kind of blyg (a book, a course, a lab notebook)? A mod Its own repository
7 Does it only make sense on your node (your branding, your infrastructure), with no general form? A local patch Your own deployment
8 Does it need to change what the Studio is? Another client A fork with its own name

The order matters. The cheapest place that works is the right one. A tool on a token costs the Studio nothing. A hook costs every future release a little. A local patch costs you a little at every upgrade.

1. A spec question

This question comes first because most ideas that sound like features are changes to the wire: a reaction, a tag, a reply, a like, a follower count, a new field on an item. If another blyg would see it or have to understand it, it belongs to the protocol, and the protocol is decided in blygger-spec, not built first and argued about afterwards.

Expect to hit these refusals in your first hour. protocol-v0.4.md §16.8 lists what will never appear on the wire: reply primitives, follower graphs, addressable authors, metrics of any kind, and a relation that names a person. Identity is deliberately left out of the protocol. These refusals are not oversights. Blygger is a network of soapboxes, not a conversation medium. That said, a well-argued case against a locked decision is welcome, and several have won. File it with the Protocol proposal template and describe the problem before the solution.

What a page looks like is not a spec question. The project polices the wire, not the page. A layout, a theme, a reading view or a count shown on your own page belongs to the client. It might be a theme, a mod or the Studio's own style, which is written down (in draft) in studio-style.md.

2. A pull request to the Studio

Bugs, and anything every blyg would want with no setting. The Studio should be boring. It is the reference client: it shows each protocol construct in its plainest form, so that other clients do not mistake its interface for the expected design. A pull request that adds an opinion will be asked to become an extension.

What review looks like:

  • npm test must pass.
  • CI also runs the browser suite (npm run test:e2e) and npm run check:template, which checks that the committed repository carries nobody's deployment.
  • A reviewer may push a small fix to your branch and say so.
  • Your PR description may carry instructions for the reviewer, such as "demo this before merging", and will be read in full before merge.

3. A tool or configuration

A tool that acts as an editor would. It creates items, edits settings and pins versions through {mount}/api on a scoped token, from anywhere and in any language, and the Studio never knows it exists. To react to changes, poll the resources you need with conditional GETs and their ETags. There are no webhooks. See mods.md and the owner API guide.

4. An extension

Code compiled into a Studio build that fills a slot: a reading byline, an action in the ⋯ menu, a sheet, a page of its own, owner reads under /api/ext/<name>/, a home page order. Nothing loads at run time, server routes are reads only, and nothing reaches the wire. Copy extensions/example/. See extensions.md, and extension-vendoring.md for one kept in your own repository.

5. A hook, proposed upstream

When a tool or an extension can't reach far enough, propose the missing slot or setting as a pull request. A hook must pass all three of these tests (mods.md):

  • [ ] General. It is named for what it does, not for the mod that wants it. A "book layout" slot is refused; an owner stylesheet would be considered.
  • [ ] Wire-silent. It does not change the bake, feed.xml, item documents or blyg.json.
  • [ ] Read-only on the server. Writes happen in the browser through the extension's client, or from outside on a token.

Say which mod needs it and why rungs 3 and 4 do not reach.

6. A mod

A mod is a kind of blyg, not a pile of settings. blykker, the first, keeps a blyg arranged as a book. It began as a book.json and a script on the owner API, added extensions second, and proposed hooks upstream third. A mod keeps three promises (mods.md): the generator string stays blygger-studio/x.y.z, model text it inserts is disclosed, and it does not fork.

7. A local patch

Something that makes sense only on your node. People patch their Studio anyway, then put off upgrading because the upgrade means redoing the patch. The rules in Local patches below make that cheap.

8. Another client

If you need to change what the Studio is, fork it, give it its own name, and tell us it exists. That is fine; several clients already exist. See If you fork this.

Your first hour

Tested on Node 24 and npm 11 with the v0.62.0 release on a clean machine. Develop locally, never against a live blyg (see below).

git clone https://github.com/blygger/blygger-studio.git
cd blygger-studio
git switch -c my-work
npm ci

npm ci also builds the Studio. npm 11 warns that the install scripts of esbuild, fsevents and workerd are not covered by allowScripts. The build and the dev server work anyway. If a fresh npm install without the lockfile crashes in the peer resolver (npm 10.9 does), add --legacy-peer-deps.

Create .dev.vars, which is ignored by git, with a local password and cookie secret:

printf 'OWNER_PASSWORD=pick-a-local-password\nCOOKIE_SECRET=%s\n' "$(openssl rand -hex 32)" > .dev.vars

Compile in the example extension. extensions.local.json is ignored by git too:

echo '{ "compile": ["example"] }' > extensions.local.json

Apply the database migrations by hand before the first run. wrangler dev does not apply them, and the test suite applies its own, so nothing else will tell you:

npx wrangler d1 migrations apply DB --local
npm run dev

Open http://localhost:8787/studio, sign in with your local password, write a fragment and publish it. It appears at http://localhost:8787/feed.xml. In Settings → extensions, check example and save: it fills every slot with something visible and harmless, so you can see where yours would go.

When you add migrations later, run wrangler d1 migrations apply DB --local again. To run the browser tests, npx playwright install chromium once, then npm run test:e2e. The suite starts its own server on port 8789, so run only one copy at a time on one machine.

Never develop against a live blyg

Use a local database and npm run dev. Extension code runs in the owner's session, where it can publish, withdraw and mint tokens, so a bug in it is a bug with the owner's authority, and a published item cannot be unpublished, only withdrawn. That is also why nothing loads at run time: an operator has to choose to compile your code in.

Local patches

A source installation's npm run upgrade already merges the newest release into your checkout. A patch kept as a commit survives every upgrade that does not touch the same lines. These seven rules make the most of that.

  1. Try the places that are not patches first. Settings, a theme, the local files (extensions.local.json, models.local.json, wrangler.private.jsonc) and an extension all survive every upgrade by construction.
  2. One patch, one commit, on your own branch, with a message that starts local: and says why in a line. Never leave a patch uncommitted or in a stash. A stash is how a patch gets lost.
  3. Add rather than edit where you can. A new file never conflicts. Keep an edit to a shared file to as few lines as possible, with no reformatting around it.
  4. Harmless means three things. The patch does not change what the blyg serves to others (item documents, the feed, blyg.json, content_html). It adds no migration and changes no table. It does not rename the client (generator). A patch that fails one of these is not a local patch. The first makes it a spec question (rung 1). The second will collide with upstream's schema: if you truly need a table, number the migration from 9000_ as the README asks and read every release's Migrations: line. The third breaks the ecosystem census and update notices.
  5. Every patch names its exit: the upstream issue or pull request it is waiting for, or one line on why it will never be general. A patch with an exit is a bridge. A patch without one is a slow fork.
  6. Upgrade often. One release at a time means a small conflict or none; five at once is an afternoon. Security fixes arrive only by upgrading.
  7. Tell us what you patched, in the local patches issue. New hooks are added when there is measured need, and this is the measurement: when three nodes carry the same patch, it should be a hook.

npm run patches lists your local commits since the release you are on, flags any without the local: label, and warns about any that touch the files rule 4 is about. npm run upgrade prints the same list before it merges and names the commits that conflicted after. Studio's Settings → updates shows how many local patches the build carries, and the bug template asks for that number. Nothing about patches appears on any public page or in blyg.json.

A Worker archive installation has no source, so it cannot carry a patch. If you want one, the first step is to move to a source installation.

Ideas to start from

One for each of the main rungs, so you can see the ladder applied:

  • Rung 1, answered no: suggested edits. It sounds like a protocol change: "propose a change to someone else's post". It isn't. The protocol already carries it (decision #110). A suggester forks and edits a pinned item, or writes a stub quoting passages of an unpinned one, and a verified mention reaches the author. Acceptance is the author's own next version. What is missing is interface: an extension that offers "suggest an edit", and a view that shows incoming fork mentions as diffs against the owner's pin. Reasoning in the spec's v0.4-plan.md §25; the backlog entry is in backlog.md §2.
  • Rung 1, answered yes: any wire idea (a new item field, a typed relation), written up as a proposal issue with the problem first, and not built.
  • Rung 3: a script that imports a folder of Markdown notes as drafts through the owner API.
  • Rung 4: a reading-view extension, such as a byline badge or a sheet that summarizes a thread's sources. reading-time and word-count are small working examples.
  • Rung 5: an owner stylesheet for the public pages. It was accepted in principle for blykker and is not built yet; the public pages take a custom palette today.
  • Rung 6: a mod for a different kind of blyg, such as a course with ordered lessons or a lab notebook, starting from a config file and a script, as blykker did.

Working with an AI agent

Point your agent at AGENTS.md and at this page before it starts. The same ladder applies to what an agent proposes, and agents are especially prone to building a wire change as if it were a feature. Ask it which rung its change is on before it writes code.

Where to ask

  • A protocol question or proposal: an issue on blygger-spec.
  • A Studio bug or feature: an issue on blygger-studio.
  • Something you built that speaks Blygger, to have it listed: blygger-org.

When an issue is accepted, it gets a row in the public roadmap linking back to it, and the issue stays open for discussion until the work ships. Unsure which repository? File it anywhere; a misfiled issue is moved, and is much better than an unfiled one.

This note's canonical text is at blygger.org/notes/tn-8/, and its source is docs/notes/tn-8-where-does-my-change-belong.md in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.

read the thread →

v1 · pinned: v1

“TN-8: the contributor guide, made a technical note.”

Created: Nov 22, 2026

thread

TN-7 — Comments sections: a curated display of responses, every comment a real item

Technical note · non-normative · promoted from RFC-2 on 2026-11-05 (session 60) after its comment period closed on 2026-11-04. Comments were stubs on blyg.blygger.org (v1, pinned) and blygger-spec#15; this note is v2 of the same item, and section 12 says what the comments changed. Status: unbuilt. The first client to host comments under this shape revises this note (decision #90: close is promotion, first build is the revision trigger). Drafted by Opus 5.5 at Venkat Rao's request; edited by Fable 5.1 in session 40 (2026-10-07), whose rulings on the seven open questions are section 11; revised by Fable 5.1 in session 60, and by Fable 5.2 on 2026-11-16 (the counts bullet in section 8, decisions #107 and #108). This is a Recommendation for clients that want a comments section. Like every technical note, it constrains nothing. Blygger Studio will not implement it; its public responses list stays a citation trail. It depends softly on tn-6 (mentions across identifier schemes, section 9), which was RFC-1: kind 1 and kind 3 need nothing from it, kind 2 takes its address book, provenance and bylines, which is why the RFCs were ordered this way. RFC-4 (responding from anywhere, #82) is the companion for responders who have no blyg and no comments origin to sign in to. Written against protocol 0.3, promoted against 0.4; no pre-1.0 version promises anything (#21).

The medium's first answer to "how do I comment" is from your own blyg (kind 1, section 5). Hosted comments (kinds 2 and 3) are an on-ramp for people who have no blyg yet, and the house that hosts them takes on their accountability. The comment period of the RFC ran that way itself: comments on it were stubs on blyg.blygger.org's RFC item (#66).

1. The question

Comments are the most requested feature from people running blygs. Venkat named three kinds:

  1. Responses from other blygs — Webmentions that fit a pattern, such as a stub with a short note, listed under the original item as comments.
  2. Signed-in commenters — people who sign in to this blyg with distinct identities and comment in an ordinary threaded comments section. Each comment goes out on the wire as an ordinary top-level item, so the thread is flattened to fit the spec.
  3. Anonymous commenters — if the owner chooses, a form whose submissions are vetted and then published as items under a byline such as anon or anon 7f3k.

This note recommends how a client builds all three, and argues that none of them needs a wire change.

2. The stance: no reply primitive, a comments section is presentation

The protocol has refused a reply primitive since #12 and says so at §16.8: "a network of soapboxes, not a conversation medium". §10.6 adds that a stub is "not a reply. There is no thread of replies, no conversation object". A Recommendation for comments sections has to leave that stance intact. It can, because the stance is about what the wire carries, and a comments section is what a page shows.

The whole recommendation rests on one idea:

A comments section is the owner's curated display of published responses. Every comment is a real item at some origin. Each one is a stub of the item it answers, under its writer's own byline. The tree is rebuilt from stub_of for display and never exists on the wire.

Everything the design needs is already built:

  • stub_of, the response marker (§10.6);
  • verified mentions, which tell an origin it was answered (§15);
  • curation display, which lets a page show other people's content with attribution (§13.5); §13.5 already names verified mentions as displayable under that rule;
  • per-item author, which puts many writers on one origin (§5.5, tn-3 shape B);
  • withdrawal, the only exit (§9).

What the protocol does not give is a way for anyone to put words on a target's page (§15.5). Under this design they still cannot. The owner displays responses, as curation, and can stop displaying any of them.

3. One display path for all three kinds

The three kinds differ in who publishes the comment and where. The comments section does not have to care, because each kind ends up the same way:

Kind Who publishes the comment At which origin How the original's page learns of it
1. Response from a blyg the responder their own a verified stub mention (§15.4)
2. Signed-in commenter the house, under the commenter's byline the house's comments origin (section 4) a verified stub mention, same as kind 1
3. Anonymous, vetted the house, under an anon byline the comments origin same as kind 1

So a client builds one renderer: the verified stubs of this item, with the stubs of those stubs nested beneath them. Kinds 2 and 3 are a publishing tool that the house runs on behalf of people who have no blyg.

4. Where house-published comments live: a comments origin

Kinds 2 and 3 are published by the house. There are two places they can go.

Option S — the same origin as the posts. This is conformant, but every comment is a publish event. §7 puts one feed entry per publish event, and §6.2 lists every item ever published. Subscribers to the house's essays would get every "great post!" in their reading list, every edit to a comment would resurface it, and every moderation withdrawal would leave a withdrawn entry in the feed. For a blyg with a handful of comments a month that cost may be acceptable. For a busy one it turns the house's soapbox into its own comment stream.

Option C — a sibling comments origin. Recommended. The house runs a second blyg next to the first, for example https://house.example/comments/ (path-mounted, #14) or https://comments.house.example/. All comments the house publishes go there. Each one is a stub whose stub_of names the post on the main origin.

Why C:

  • The main feed stays the house's own writing. Readers who want the conversation subscribe to the comments origin. Its blogroll entry, or a link on every post, makes it one click away.
  • It reduces kinds 2 and 3 to kind 1. A stub from the comments origin to the main origin is a cross-origin reference. It sends a real mention, and the main origin verifies it exactly as it would a stranger's. Since #61 a document under /comments/ cannot verify in the name of /, so the two origins cannot speak for each other even on one host. One renderer handles everything.
  • The house collects every reply to the comments it hosts. A reply to a hosted comment, from anyone, is a stub of an item on the comments origin, so the mention arrives there.
  • Accountability is legible. By tn-3's test, the comments origin is a masthead: the house withdraws anything on it and answers for everything on it, which is what moderation is. Its manifest author names the house, for example { "name": "House comments", "url": "https://house.example/" }.

The cost is a second origin with its own deployment, its own archive, its own Webmention endpoint (replies to hosted comments arrive there) and its own permanence (withdrawal endcaps are served forever). A client that offers comments SHOULD run both origins from one install, so the owner deploys one thing: a second deployment is a heavy price for a solo blyg, and the people most likely to want comments are the ones least likely to run two. The comments origin must also import the main origin as a subscription, because a partial transclusion in a comment resolves only against a local or imported item (§10.2); one install can share the store, but the resolution rule is the same.

5. Kind 1 — responses from other blygs as comments

5.1 What counts

  • Relation stub only. Being stubbed is being answered. Being transcluded is being quoted inside someone's own piece, and being forked is being descended from. Both are worth showing, but separately, for example as "quoted in" and "forked as" lists. Presenting them as comments would misstate what their authors did.
  • Comment versus response. A short stub reads as a comment and a long one reads as an essay. A client MAY show the full text of short stubs inline and only an excerpt plus a link for long ones. Measure the stubber's own words, leaving out the baked quote of this item (section 5.3). The threshold is presentation and the client's choice. §10.6 rule 2 tells readers to rely on the marker and never on body inspection. This does not break that rule: the marker alone decides that something is a response, and length decides only how much of it is shown (section 11, Q7).
  • Links and reposts are notices, not comments. A [[id]] link to this item now sends a mention with relation link (#79), and a wordless repost is classified the same way (#80). A notice is not a response and never counts as a comment; a client MAY show notices apart, as "linked from" or "reposted by".

There is no typed stub on the wire and none is planned: the general meta bag that blygger-spec#10 asked for stays refused. But how a client sorts the verified stubs it displays into sections — comments, resolutions in a prediction journal, anything else — is presentation, and it may use any signal the client itself defines, by any convention a genre agrees among its own clients. The marker decides that an item is a response; which section it lands in is the owner's display.

5.2 Showing the text, and keeping it honest

§15.4 step 5 says a verified mention stores no content: "what it points at is fetched from its origin when displayed, or not at all." A comments section that shows text is therefore displaying another origin's content. The rules for that are §13.5's, and §13.5 names mentions explicitly:

  • Fetch on display, cache briefly, refresh. The receiver re-fetches the stub's live item document when showing it, through an ordinary HTTP cache. Edits are not reliably signalled: under §15.2, a stub whose target version did not change is not re-sent, so a refresh schedule is the only way to keep displayed text current (section 11, Q2–Q3).
  • Gone means gone. If the stub is withdrawn, re-fetched as an endcap, or the mention re-verifies as gone, it leaves the display. §13.4's retention rule applies as it does to any displayed import: show a pinned version only if the origin pins it, otherwise show nothing.
  • Attribution every time. Show the stubber's byline as their origin asserts it (§5.5 pass-through). Under tn-6 it is an h-card, together with their origin and a link to the stub's page. A comment is never shown detached from where it lives.
  • Sanitize as an import (the reference reader's importer/sanitize.ts is a working model).

5.3 Strip the quote of this item

A stub usually starts by transcluding its target (§10.6 rule 2's aesthetic). Shown under the target, that quote repeats the post back to the reader. A comments display SHOULD collapse any baked blyg-transclusion whose data-blyg-id is this item and whose data-blyg-origin is this origin. A partial quote (blyg-partial) is the exception: it should stay, because "replying to this passage" is exactly what a reader needs to see. A collapsed whole quote can still show a small "quoting the post" marker.

5.4 Moderation

Display is the owner's act, so the owner decides who is shown. Clients SHOULD offer three modes per blyg, overridable per item:

  • pre-moderated — nothing shows until approved;
  • post-moderated — verified stubs show at once, and the owner can hide any;
  • trusted — post-moderated for origins in the owner's blogroll or address book, pre-moderated for everyone else.

The reference client's public responses list (studio, session 23) is the post-moderated mode, with links only. That list is kind 1, in every Blygger Studio: showing the text is the one step it declines, because the studio stays boring. Nor can the text be added as a studio extension, because extensions do not reach public pages (#89); a client that wants it builds it. Hiding a comment is a display choice, never a delete: the stub is the stubber's speech on their own soapbox (§10.6), and it stays there.

5.5 Depth

Replies to a kind-1 comment stub that comment, so their mentions go to the commenter's origin, not to this one. This origin sees one level of external responses, plus any reply that also references this item. Showing "N replies elsewhere" would need a responses surface, and #41 and #47 closed that surface. Clients SHOULD show one level and link through. Kind 2 and 3 comments have no such limit (section 4: the house receives replies to everything it hosts).

6. Kind 2 — signed-in commenters

6.1 Signing in

The commenter signs in to the house's client with any provider the client supports:

  • IndieAuth, the best fit: it proves control of the commenter's own URL, which is #35's identity directly;
  • Mastodon or Bluesky OAuth, which yield an actor or a DID;
  • GitHub or Google, which yield a profile URL.

The client records the commenter in its address book (tn-6 section 5.1):

  • the identifier from the login gets provenance bound, because the house checked it at sign-in;
  • the commenter's display name is theirs to set;
  • member stays false: a commenter is a guest, not a masthead writer.

Commenters receive a comment scope: a token in the shape #31 describes (bearer, owner-revocable), minted by the house's client to a guest at sign-in. This is the client's own guest authentication, part of the write surface #31 leaves to clients, and it borrows only the token's shape from the owner's tokens. It can do only:

  • publish a stub on the comments origin whose stub_of names an item on the main origin or the comments origin;
  • edit and withdraw that commenter's own comments;
  • nothing else: no drafts that last, no hoppers, no subscriptions, no studio.

The byline is fixed to the signed-in identity, and the commenter cannot choose it. This is the "a member is a token with a member's scopes" model (#38, tn-3 section 2), with a narrower scope.

6.2 What a comment is on the wire

A comment is a thread on the comments origin:

{
  "blyg": "0.3",
  "id": "3q8m1x…",
  "kind": "thread",
  "origin": "https://house.example/comments/",
  "author": { "name": "Ada Ruiz", "url": "https://ada.example/", "ids": ["did:plc:…"] },
  "stub_of": { "origin": "https://house.example/", "id": "7c9wk2…", "version": 4 },
  "content_md": "This is the part I'd push back on: …",
  …
}
  • Kind thread, because §10.6 makes stubs threads. A comment that quotes a passage of the post uses a partial transclusion (§10.1). That is the quote-reply comments sections have always wanted, and it is verified.
  • A reply to a comment is a stub of that comment. Its stub_of names the comments origin. The display rebuilds the tree by following stub_of chains, so the wire stays flat.
  • Edits are new versions (§5.2). They get no feed vocabulary, and the comments origin's feed shows the edit like any other publish event.
  • Delete is withdrawal (§9). The commenter withdraws their own comments, and the house withdraws anyone's, which is moderation. The endcap stays, and a reply to a withdrawn comment keeps its place in the display with a "withdrawn" placeholder.
  • Generated text is disclosed through generated[], as anywhere (§5.7). An agent can be a commenter under #38's rules: its own byline, an operator named, and content in every comment, since #36's line against content-free stubbing applies.

6.3 Limits a client should set

  • No transclusion of third parties by default. A transclusion of another origin in a comment sends a mention from the house's comments origin to a stranger, on a commenter's say-so. Allow quotes of this house's own items, and make anything wider an owner setting.
  • Pre- or post-moderation, as in section 5.4. Signed-in commenters are more accountable than anonymous ones, but a comment, once out, is on the wire for good: withdrawal leaves an endcap, and other readers may have quoted it.
  • Tell commenters what publishing means, in plain words at the comment box: the comment is public, it can be quoted, and deleting it leaves a "withdrawn" marker.

6.4 Commenters who have their own blyg

If the signed-in identity is a blyg origin, or the address book knows one for it, offer "respond from your own blyg" next to the comment box. That makes it a kind-1 comment, on their soapbox and under their accountability. A comment hosted by the house is the fallback for people without a blyg, not the default for people who have one (tn-3's withdrawal test applied to comments).

6.5 Portability

The commenter's verified URL is what keeps their comments recognisable if they later start their own blyg: tn-6's ids and url match across origins once they are verified (#35 reader rule 2). As tn-3 section 5 says, the person is portable, the items are not.

6.6 Telling hosted commenters about replies

A signed-in commenter wants to know when someone answers. The house may tell them: this is house behaviour, and it is accepted. The commenter signed in, the house holds an identity for them, and section 4 already delivers every reply to a hosted comment to the comments origin as a verified stub. Telling its guest is the house's own relationship with that guest, off the wire. It adds no count and no reply primitive; it is what a blog's reply email has always been. Four conditions:

  • Opt-in, per comment or per thread.
  • Sent only when a stub has verified, never on receipt of a mention. Otherwise the Webmention endpoint becomes a relay from any spammer to the commenter's inbox.
  • The message carries the stub's byline, origin and page link, never its text. §15.4 step 5 makes a verified mention a pointer; an email is a durable copy that would outlive the stub's withdrawal.
  • The address lives with the sign-in record, never in any item document.

Anonymous commenters (kind 3) get no such message. Section 7.3 keeps only the text, the browser token and a rate-limit key, and an address is the one thing that reverses the anonymity. Deleting the address at the moderation decision, which was proposed, would also make it useless, because replies arrive after the decision. What kind 3 gets instead: the browser token behind the anon 7f3k suffix (section 7.2) already identifies the browser, so a client MAY show that browser the replies to its own comments when it returns. Nothing new is held.

7. Kind 3 — anonymous comments, vetted

This kind is entirely the owner's choice, and off by default in any client that offers it.

7.1 Flow

  1. A form on the item's page takes the text and, optionally, a display name. It has no URL field: a URL nobody verified is exactly the unchecked claim tn-6 keeps off the wire. It has no email field either (section 6.6).
  2. The submission enters a mandatory pre-moderation queue. For anonymous speech that is not optional, because approval is what makes the house's publication of it an editorial act rather than a pipe (#36). Machine triage MAY sort the queue. A person approves.
  3. On approval the house publishes a stub on the comments origin, exactly as in section 6.2, under an anonymous byline.
  4. The submitter receives a one-time withdrawal link at submission. Without an account, it is their only way to retract. Using it withdraws the item (§9).

7.2 The byline

  • {"name": "anon"} when the client does not tell anonymous commenters apart.
  • {"name": "anon 7f3k"} when it does. The suffix comes from a random token kept in the commenter's browser and is stable across their comments while the token lives. It MUST NOT be derived from an IP address, an email address or any hash of one: those can be reversed by trying candidates, and an "anonymous" label that can be reversed is worse than none.
  • No url, no ids. Nothing about an anonymous commenter is checkable, so nothing is asserted. Bylines that are byte-equal group only for display within this origin (§5.5), never across origins and never as an identity.
  • Readers see the house's assertion, as with every byline (§5.5). A client SHOULD label these comments "anonymous, approved by the editor" so that the house's role is visible.

7.3 Data the house keeps

Store only what vetting needs. Keep the text, the browser token and a rate-limit key, and delete the rate-limit key once a decision is made. Never put submission metadata into the item document. The house publishes the words, not the person. No email address is kept, even for reply notices (section 6.6).

8. Presentation rules common to all three

  • Different chrome for each source. "From their own blyg (verified)", "signed in via GitHub as ada.example", "anonymous, approved". #35's first reader rule says to show verified claims as verified and everything else as claims. A comments section that makes all three look alike erases the differences readers most need.
  • Order by observation time (§13.7), not by the commenter's self-asserted created. A stranger's clock does not get to move their comment to the top.
  • No count on the wire; on the page, the client's choice (revised 2026-11-16, decisions #107 and #108; this bullet used to read "No counts"). No item document, feed or index carries a count of comments, and the next bullet keeps one out of markup: a number a publisher asserts cannot be checked, and one that software can read is the first thing a ranking attaches to (#12, #13, #47). Whether the page says "42 comments" to the person reading it is presentation. Blygger Studio's own answer for its responses list (a count of what is shown, nothing ordered by it, no totals) is in its studio style and is one answer, not the answer.
  • No machine-readable comments markup on the post page. IndieWeb practice puts h-cite comment markup inside the post's h-entry. Doing that turns the display into exactly the machine-readable responses surface #41 tells readers never to parse and #47 declined. The comments origin already is the machine-readable record: real items, with real stub_of, in a real feed and index. Individual comments carry tn-6's h-card bylines, which say who wrote something, not that it responds.
  • The comments section is never part of the item. It is not in content_html, not in the feed <description>, and not baked into anyone's transclusion of the post. Quoting a post never quotes its comments.

9. Wire impact: none

Nothing new appears anywhere a reader sees. The design uses only:

  • stub_of (§10.6);
  • author with tn-6's conventional members (§5.5);
  • partial transclusion (§10.1);
  • withdrawal (§9);
  • verified mentions (§15);
  • curation display (§13.5);
  • mount independence for the comments origin (#14);
  • exact verification between sibling origins (#61).

No field, no relation, no feed element, no manifest key. A reader that knows nothing about comments sees a blyg (the comments origin) full of short stubs with different bylines, which is a correct reading of it.

The dependency on tn-6 is real but soft. Kind 2 works with today's {name, url} bylines. tn-6 supplies the address book, the bound provenance that sign-in produces, ids for recognising commenters across origins, and the h-card byline. A client could ship kind 1 and kind 3 before any client builds tn-6. Kind 2 is where identity matters, and that is why the RFCs were ordered this way.

10. Rejected designs

Recorded because each will be re-proposed.

  1. A reply primitive or an in_reply_to field. stub_of already is "this answers that", verified. A second field would be a reply primitive (§16.8).
  2. A comment kind. Kinds describe what an item is (§5.3), and a comment is a short stub. A kind would ask readers to treat it differently, which is a version change by #43, for a distinction length already makes in presentation.
  3. Comments embedded in the post's item document, or carried in its content_html. That would put other people's words into this origin's item under this origin's content_hash, which re-emits them (§13.5) and lets stubbers write on the target's page (§15.5).
  4. A responses or comments list in the manifest or as a file. That is #47's closed surface, and the first place a count would attach.
  5. House comments on the main origin by default (option S). It is conformant, but it floods the house's feed (section 4). Clients may offer it for low-volume blygs, and should not default to it.
  6. Publishing anonymous comments without vetting. The result would be a pipe (#36) feeding permanent endcaps into every subscriber's archive.
  7. Pseudonyms derived from IP or email hashes. They can be reversed (section 7.2).
  8. Off-wire comments — an ordinary comment database rendered on the page and never published. This is not rejected: it is conformant, since the protocol governs only the page's protocol surface (#3) and says nothing about chrome. It is not recommended, because the comments then cannot be cited, quoted, forked or subscribed to, and they disappear with the client. The point of putting comments on the wire is that they become part of the medium. A client that wants Disqus can have Disqus.

11. Rulings (Fable 5.1, session 40, 2026-10-07)

The draft closed with seven questions. The rulings follow with the principle each rests on; where one differs from the draft's recommendation, it says so.

1. Fit with §16.8 and §10.6. Yes, on the wire: the design adds no field, no relation and no feed element, and a display tree rebuilt from stub_of is §10.6's own nesting, since a stub of a stub is a thread transcluding a thread. The character risk the draft names is real and is answered by framing, not by machinery: the header now says that the medium's first answer is to respond from your own blyg, that hosted comments are an on-ramp whose accountability the house takes on, and that the reference client's responses list stays a citation trail. Section 2's sentence, the owner's curated display of published responses, is the whole of what a comments section is, and this note must never describe a comment as a reply.

2. Displayed text against §15.4 step 5. A bounded cache is fetching on display. The rule exists so that a receiver never becomes a store of other people's words that outlives their withdrawal, and §13.5 names verified mentions as displayable under curation. The test a client must pass: if the stub's origin withdraws and the receiver never fetches again, the text must stop showing. So the cache has a bounded lifetime after which display requires revalidation, gone and an endcap purge it, and a durable copy exists only by the origin's pin (§13.4). This is only a kind 1 question; for kinds 2 and 3 the house is the publisher of the comment and holds it as its own item.

3. Edits are not signalled. (a) and (b), no spec change. The house controls the sender for kinds 2 and 3, so its comments origin re-sends a stub's mention when the comment is edited; §15.2 already permits it. For kind 1 the receiver refreshes on a schedule and accepts the staleness window. (c), a spec SHOULD to re-send on every stub edit, is rejected: it would make every edit of a stub notify its target, which is the noise §15.2 chose to permit and not require, and it is sender behaviour the spec would be changing for a presentation feature.

4. Steering clients toward a sibling origin. Confirmed, for the reason the draft gives: it is the only shape that keeps the house's own feed its own writing without new wire vocabulary, and it reduces three kinds to one renderer because #61 makes the two origins verify each other exactly as strangers would. It is not tn-3 section 6's pipe: every item on the comments origin is a person's words, published or approved by the house, which withdraws any of them. Two requirements are added to section 4: the comments origin imports the main origin so quotes resolve, and it runs its own Webmention endpoint for replies.

5. Counts and comments markup. Confirmed: no counts anywhere, no h-cite or other machine-readable responses markup on the post page. #12 and #13 refuse metrics, #47 kept the responses surface closed because a count is the first thing a ranking attaches to, and #41 tells readers never to parse one. The comments origin's feed and index are the machine-readable record, as the draft says. The h-card bylines inside comments say who wrote them and nothing more. Amended 2026-11-16 (Fable 5.2, decisions #107 and #108): "no counts anywhere" is narrowed to the wire and to markup. What a page tells a person is the client's own style. The markup half of this ruling is unchanged.

6. Anonymous bylines. Consistent with §5.5 and #38. author is the origin's unverified assertion, byte-equal values group only within one origin and only for display, and the origin is the accountable party. The three conditions in section 7 are what make it so and are kept as written: mandatory pre-moderation, a suffix that cannot be reversed to a person, and no url or ids. The withdrawal link must say what withdrawal is: permanent, and visible as an endcap.

7. Classifying by length. On the right side of §10.6 rule 2. The marker alone decides that an item is a response; length decides how much of it is shown, which is presentation. Measuring the stubber's own words by leaving out the baked blyg-transclusion of the target reads a wire token for the purpose it exists for, and is the same reading §5.6 rule 6 and this note's section 5.3 already make.

What happened. Published for comment on blyg.blygger.org under #66 on 2026-10-07, after RFC-1, and recorded as decision #68 beside RFC-1's #67. The period closed on 2026-11-04 with comments (section 12). On 2026-11-05 the RFC was promoted as this note, tn-7 (decision #92, reasoning in v0.4-plan.md §18): closing the comment period is the promotion, and the build gate the draft named here became the trigger for a revision instead (#90). The reference client still builds nothing from it. The first client that hosts comments under this shape revises this note.

12. Comments received, and what changed

Session 60, 2026-11-05.

Aneesh Sathe (2026-11-04) asked for three things. Reply notification for commenters became section 6.6: yes for signed-in commenters, as house behaviour off the wire, and no for anonymous ones, because an address is the one thing that reverses the anonymity, and deleting it at moderation would make it useless since replies come later; anonymous commenters get the browser-token MAY instead. Running both origins from one install is now a SHOULD in section 4, for the reason he gave: a second deployment is heavy for a solo blyg. Kind 1 in every Studio is answered in section 5.4: it already is, links only, and the text cannot come as a studio extension because extensions do not reach public pages (#89).

Mike Casey (2026-11-02) found that the stance holds in practice: responding from his own drafts blyg was one tap. His request for typed stubs became the paragraph in section 5.1: no type on the wire, but sorting verified stubs into sections is the owner's display, on any signal the client defines.

ksurya agreed that a dedicated reply primitive should not exist. His wish to receive Webmentions from places that are not blygs is the subject of RFC-4 (responding from anywhere, #82), and his example is forwarded there.

Matthew McDowell-Sweet linked the RFC in passing in Bronze eels, with no request.

This note's canonical text is at blygger.org/notes/tn-7/, and its source is docs/notes/tn-7-comments-sections.md in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.

read the thread →

v3 · pinned: v1, v2, v3

“Promoted to TN-7 after the comment period; see §12.”

Created: Oct 7, 2026 Most recent: Nov 19, 2026, v3

thread

TN-6 — Mentions across identifier schemes: petnames in the studio, full identifiers on the wire

Technical note · non-normative · promoted from RFC-1 on 2026-11-05 (session 60) after its comment period closed on 2026-11-04. Comments arrived as stubs of the blyg item blyg.blygger.org/t/7eeh3bfzfcnhh90d5pkvkc2r1n/ (version 1, pinned) and on blygger-spec#14; this note is version 2 of the same item, and section 11 says what the comments changed. Status: first built. Blygger Studio has emitted mention h-cards since 0.55.0 (2026-11-06), marks up item pages as section 5.4 describes since 0.55.3, and has the found-mentions list of section 6 since 0.56.0, as a lens in Reading. Member rosters, the wider schemes of section 5.1 and section 5.5's byline check are not built, and no second client resolves these mentions yet. By decision #90 an RFC becomes a note when its comment period closes, and the first build is a revision trigger, not the promotion gate. Drafted by Opus 5.5 at Venkat Rao's request (session 40, 2026-10-07); edited the same session by Fable 5.1, whose rulings on the five open questions are section 10; revised by Fable 5.1 at promotion (session 60). Technical notes record design reasoning alongside the normative spec; like the RFC it was, this note constrains nothing. It builds on locked decisions #11 (the opaque author), #35 (identity practice, proposed in docs/proposals/identity-practice-proposal.md, which becomes tn-2), #36 (groups, tn-3), #20 (studio grammar versus wire grammar) and #79 (the markdown link is the silent citation; it reversed #32, on which the draft relied). Written against protocol 0.3 as published on 2026-10-07 and promoted against 0.4, whose #79 forced the one change in sections 5.3, 9 and 10; no pre-1.0 version promises anything (#21).

1. The question

Several early users have asked for multi-author blygs, and with them comes a second request: @-mentions of the people who write there and of people elsewhere. The request (Venkat Rao, session 40) was for three things:

  1. a consistent recommendation for user identifiers within a domain that can travel through the protocol;
  2. an evaluation of how markup in the item body could carry the major identifier schemes — W3C DIDs, Ethereum accounts, ActivityPub, ATProto and h-card — so that clients sharing a convention can resolve @-mentions;
  3. a convention in which the client keeps an address book of contacts across schemes. The author types a short @handle, the client looks up the full identifiers in that address book, and the full identifiers travel on the wire, so that another client can resolve whichever scheme it speaks.

The third request is the design. Sections 2–4 clear the ground, section 5 is the convention, and sections 6–9 cover reading, scheme details, the reference client's default and what is rejected. Section 10 records the rulings, and section 11 the comments received at promotion.

The constraints are fixed. Authors are never addressable (§5.5, §16.8). The protocol has no reply primitive (§16.8), and no mention relation can name a person: every relation in §15.4 targets an item. (The draft said "no fourth mention relation"; 0.4 has five, with source and #79's link, and none of them reaches a person.) The protocol has no normative write surface (#31), so nothing here comes from Micropub, in keeping with that decision while staying close to the IndieWeb in spirit. Whatever this note recommends has to be HTML and studio practice, not protocol.

2. Correcting a premise: the single author does not block multi-author blygs

The worry was that an item's author field holds only one name, so a multi-author blyg would have to sign everything as "community" unless the spec changed in a way that breaks RSS. Two parts of that are true and one is not.

  • A multi-author blyg does not need more than one name per item. author is per-item (§5.5). A masthead blyg with five writers publishes items whose bylines differ item by item. That is shape B of tn-3, specified since #11, and the feed rule is single-publisher, never single-author. "Community" is only needed if you want it: the Protocol Institute node already uses the byline "Editor".
  • RSS is not the binding constraint. In RSS 2.0, the core <author> element is a single email address, and the protocol does not emit it. The feed carries <dc:creator> (§7). Dublin Core lets that element repeat, and Atom allows several <author> elements. Many feed readers show only the first creator, which is a display limit, not a format limit.
  • The real single-valued thing is the protocol's own §5.5. author is one JSON object. Only co-authored items need more than one person in it, and §5.5's extension point already lets them carry more without a spec change (section 4.1 below).

So multi-author blygs work today and need nothing from the protocol. What the reference client lacks is studio-side: one author_name setting stamps every item (protocol.ts sets author.url to the origin). That is a client gap, and section 8 addresses it.

The census, re-run 2026-10-07 against the 20 blygs listed at blygger.com (19 reachable), the three newest items each: every item author is {name, url}, {name}, or absent. No client has invented an authorspace grammar, no item has two people in it, and no body contains an h-card or mention markup. Manifest-level author has grown bio, links and avatar in several clients. The per-item field is still empty, so this is still the cheapest time to recommend something.

3. Identifiers within a domain

In shape B (one origin, many bylines), what identifies a member? The answer follows from #35's spine — a person is a URL they control — with one concession for people who have no URL of their own:

Member has… author.url What it proves
their own site, profile or actor URL that URL portable. If the page links back (section 5.5), a reader can confirm the byline from the member's side.
nothing of their own a house-hosted member page, e.g. https://house.example/people/alice/ only that the house says so. That is honest: in shape B the house answers for everything (tn-3 section 5).

The member page is presentation. It is an HTML page like any page, not a protocol construct, so it does not make authors addressable in §16.8's sense: nothing in the protocol references it. It has a second job, which section 5.5 gives it: it is the origin-side end of the reciprocal proof for a member who does have their own URL. A member who later moves to their own origin (shape A) takes their own URL with them. A house URL does not travel. That is the practical reason to prefer the member's own URL whenever they have one.

No user@domain grammar inside an origin. @alice as typed in the studio is a petname, a name that is meaningful only in this address book (section 5). It never reaches the wire as an identifier. DNS remains the namespace (#11).

4. The five schemes, evaluated

Each scheme answers four questions:

  • What is its stable identifier, as opposed to its human-readable name?
  • Can a reader resolve it with an ordinary fetch?
  • How does a person prove control of it?
  • What does it reduce to under #35's two proofs: a reciprocal link, or a signature?
Scheme Human name (mutable) Stable identifier to put on the wire Resolution Proof Reduces to
Web / h-card the URL itself https://alice.example/ fetch, then parse the representative h-card rel="me" reciprocal links link (it is #35)
ActivityPub @alice@social.example acct:alice@social.example (RFC 7565), plus the actor's https URL WebFinger (RFC 7033) maps acct: to the actor URL Mastodon-family servers check rel="me" on the links in a profile and serve rel="me" on profiles themselves link
ATProto handle alice.example or alice.bsky.social the DID, usually did:plc:… DNS TXT _atproto.<handle> or https://<handle>/.well-known/atproto-did, and the DID document's alsoKnownAs points back two-way handle↔DID binding. A domain handle is DNS control. link (a domain handle is a URL the person controls)
W3C DID none did:<method>:… method-specific. did:web is an HTTPS fetch. did:plc needs a directory. did:key and did:pkh resolve locally. did:web: DNS. Others: a key in the document did:web reduces to a link. The others reduce to a signature.
Ethereum ENS name alice.eth the account as a DID, did:pkh:eip155:1:0xAb… (the CAIP-10 account eip155:1:0xAb… wrapped; see section 7) ENS needs chain access (an RPC endpoint); the account needs nothing EIP-191 signature (e.g. over content_hash, #35 §4.2); EIP-4361 for sign-in signature

Four observations decide the design.

  1. h-card is not a rival scheme. It is the envelope. It is the IndieWeb's format for "here is a person and their identifiers": p-name, u-url (which may repeat), u-uid, and u-key. Every other row can be written inside an h-card. That makes it the natural carrier for request 3, and it is already how Mastodon marks up mentions in HTML (<span class="h-card"><a class="u-url mention" href="…">@<span>alice</span></a></span>).
  2. Put the stable identifier on the wire, never the name. ENS names expire and transfer, ATProto handles change, and fediverse accounts migrate. The address, the DID and the actor's acct: are what a distant reader can still match a year later. The web is the exception, because the URL is both the name and the identifier. That is exactly why #35 chose it.
  3. Three of the five reduce to "a URL the person controls". Those are the web, ActivityPub, and ATProto with a domain handle. did:web joins them. Only did:plc/did:key and Ethereum need a signature or a non-HTTP resolver. The default can therefore stay boring (section 8) and lose almost nothing.
  4. The schemes differ in cost to the reader, not just in reach. Resolving an ENS name needs chain access, and did:plc needs a third-party directory. A static reader cannot do either. Any convention has to work for a reader that resolves nothing, and that pushes the visible fallback onto a plain https link.

A fifth, smaller observation sets the wire vocabulary: with Ethereum accounts written as did:pkh:, everything on the wire is an https:, acct: or did: URI. Three schemes, three normalization rules (section 6), and a matcher needs nothing else.

4.1 What author can carry for co-authored items

A co-authored item keeps one author object, as §5.5 requires. It can use the extension point §5.5 grants, so no spec change is needed:

"author": {
  "name": "Alice Ng and Bob Ruiz",
  "url": "https://house.example/",
  "coauthors": [
    { "name": "Alice Ng", "url": "https://alice.example/", "ids": ["did:plc:7iza6de2dwap2sbkpav7c6c6"] },
    { "name": "Bob Ruiz", "url": "https://social.example/users/bob", "ids": ["acct:bob@social.example"] }
  ]
}

A reader that knows only name shows "Alice Ng and Bob Ruiz", which is correct. <dc:creator> carries the same combined string. Emitting one <dc:creator> per person is legal, but readers that show only the first would drop Bob. For a single author, ids sits directly in author beside url. ids is the same array as a mention's alternate identifiers (section 5), with the same emission rule, and is ruled in as a conventional member in section 10, ruling 5. It is distinct from the manifest-level links that several clients already emit: links are labelled links for display, ids are identifiers for matching.

5. The convention: an address book of petnames, full identifiers on the wire

This is the design the request asked for. It takes its shape from petname systems, and in particular from Zooko's triangle. Zooko's observation was that a name cannot be global, secure and memorable all at once. The standard resolution, used by Stiegler's petname designs and by every phone's contact list, is to keep the memorable name local, to the person who chose it, and to send the global, secure identifier. @kyle is memorable only in one studio. did:plc:… is global and verifiable but nobody can type it. So the address book holds the mapping, and the wire carries only what other clients can check.

5.1 The address book (studio-private)

Each contact record holds:

  • handle: the petname the author types (kyle). It is unique within the book. It never leaves the studio.

  • name: the display name used when the mention renders.

  • url: the primary https URL, used as the link target. It is optional only for a contact who has no web presence at all, for example an Ethereum-only contact.

  • ids[]: alternate identifiers in their stable form (section 4 observation 2). Each carries provenance:

    • self means the contact publishes it themselves, for example as a rel="me" link or an h-card u-url at their url, or as an alsoKnownAs entry in their DID document;
    • bound means the scheme's own two-way binding was checked. Examples are a handle and DID that point at each other, or WebFinger agreeing with the actor;
    • entered means the author typed it in, and nothing has checked it.
  • member: true for people who publish at this origin. In shape B the house's member roster is simply the book's member entries. The roster supplies each member's byline, and the members sign in with #31's scoped tokens. The roster changes nothing about accountability: the house still withdraws any item and owns every pin (tn-3 section 5).

How the book fills itself. When the author adds a contact by any single identifier, the studio resolves outward from it and gathers what it can:

  • from a URL, it fetches the page and reads the representative h-card and the rel="me" links, which reveal the person's fediverse, Bluesky and GitHub profiles, all self;
  • from @alice@social.example, it runs WebFinger, reaches the actor, and reads the actor's profile links;
  • from an ATProto handle, it resolves the DID and checks the DID document's alsoKnownAs;
  • from did:web, it fetches the DID document.

Subscriptions supply contacts for free: every subscribed blyg's author already carries a name and url, and the studio can offer to add it.

5.2 Writing: @handle is studio grammar and is consumed at publish

The editor offers autocomplete on @. The grammar is studio-private under #20's two-layer split, like TK. It is consumed at publish, and it never appears in content_md:

  • @kyle that matches a contact turns into a mention.
  • @word that matches nothing stays literal text, and the editor shows a soft warning with an "add contact" action. It is never a publish error, because @ is common in prose, in code and in email addresses. Text in code spans and code blocks is never touched, which is the same rule as #54.

The resolver is the publishing server's, on every write path (session 60). The @handle resolver runs in the publish step of the publishing client, not in its editor, and it runs on every write path: the editor, the API, and any tool on a scoped token. Submitted markdown may carry @handle; published content_md never does. Every @word the resolver could not match is returned as a warning in the publish response, to every client that publishes, not only to agents (section 5.6, item 3, relies on this). The editor's autocomplete is a convenience over the same resolver. The principle that forces this is #63, below: forkers re-parse content_md, so a resolver that ran only in the editor would make the API path a leak, carrying petnames to the wire whenever a tool published. One correction to the draft's reading: an unmatched @alice reaches the wire as literal prose, not as a rejection. Section 9, item 2, rejected a design, leaving petnames in the text for readers to resolve, not the characters.

Why it must be consumed rather than left in content_md: forkers re-parse content_md (#63). If @kyle stayed in the text, it would travel to a forker whose address book has no kyle, or a different one. That would make one person's petname resolve to another person in someone else's fork. Under #43's boundary test, a grammar that a third party has to re-parse belongs to the protocol. This one must not become protocol (§16.8), so it must not survive publish.

The same fact sets what a fork keeps. A forked thread descends from the pinned document (#57), so its baked content_html carries the h-cards. A forked fragment is re-rendered from content_md (#63), so it carries the plain link and not the alternate identifiers, unless the forking client's own book knows the URL and re-wraps it. That is correct: the identifiers were the original publisher's statement about their contact, and a fork is the forker's speech.

5.3 What goes on the wire

In content_md: a plain markdown link, which any markdown reader understands:

Thanks to [@Kyle Mathews](https://bricolage.io/) for the edge-cache work.

In content_html: the same link, wrapped as an h-card that carries the contact's alternate identifiers:

<span class="h-card"><a class="u-url" href="https://bricolage.io/">@<span class="p-name">Kyle Mathews</span></a><data class="u-url" value="did:plc:7iza6de2dwap2sbkpav7c6c6"></data><data class="u-url" value="acct:kyle@social.example"></data></span>

The markup follows these rules:

  • The visible anchor is the contact's https URL. A reader that knows nothing about h-card shows a link, and clicking it works. A contact without a URL renders as <span class="h-card">@<span class="p-name">Name</span>…</span>, which shows a name with no link. The @ sits outside p-name, so a parser gets the name and the page gets the sigil.
  • Each alternate identifier is a <data class="u-url" value="…">. microformats2 parsers read <data value> for u-* properties, and u-url is allowed to repeat. <data> renders nothing, so readers that ignore it lose nothing. All these values are absolute URIs, so §5.2's rule that content_html is self-contained holds.
  • Only self and bound identifiers go on the wire by default. The entered identifiers stay in the book. Putting an unchecked DID beside someone's URL tells every reader that the two are the same person, and the author never verified that. The author MAY choose to publish entered identifiers per contact, but the studio should not do it unasked.
  • Order carries no meaning. The anchor's href is the primary identifier; everything else is unordered.
  • Mentions are silent on the wire, for two reasons. First, a mention's wire form in content_md is the markdown link, [text](URL), which is the form #79 deliberately kept as the one silent citation when it made the bracket form disclose (§10.1). Second, its target is a person's page, never an item, so no relation in §15 and no links[] entry (§10.3a) can name it: authors are never addressable (§5.5, §16.8). Mentions add no transclusions[] entry, no links[] entry, no relation (§15.4) and no new field, and they send nothing (section 10, ruling 2). The draft grounded this on [[id]] being silent (#32); #79 reversed #32 after this text was published, and the conclusion stands on the grounds above.

Why this is not a spec construct: the markup is ordinary HTML using a published W3C-community vocabulary, inside a field that already accepts any editorial HTML. No reader, receiver or publisher has to change for it to work, so it fails every part of #43's test for protocol. It uses no blyg- class and no data-blyg-* attribute. Those prefixes are spec vocabulary (§10.2), and using one would turn this into a spec construct by the back door.

5.4 The byline uses the same record

When a member publishes, the studio fills author from their contact record: name, url, and the same filtered ids. A permalink page renders the byline as an h-card (p-author h-card) inside the item's h-entry. A microformats-aware reader then gets the byline and the mentions from one parse, and the item becomes a valid IndieWeb post without any work on the reader's part.

5.5 The proof on a shared origin

#35's proof is a reciprocal rel="me" link: author.url names a page that links back to the identity origin, and the sentence both links make is "this is also me". For a one-person blyg that sentence is true in both directions. On a shared origin it is false in one: Alice is not the house.

The ruling (section 10, ruling 3) keeps the proof and moves its origin-side end. On a shared origin the reciprocal rel="me" runs between author.url and the member's page under the origin (section 3), and both directions are now true statements, because both pages are Alice:

  • https://alice.example/ carries <a rel="me" href="https://house.example/people/alice/">;
  • https://house.example/people/alice/ carries <a rel="me" href="https://alice.example/">.

A reader verifying a byline fetches author.url and looks for a rel="me" link whose href is either the identity origin itself (#35 as written, the one-person case) or a URL that has the identity origin as its prefix (the shared case). In the second case it fetches that page and requires a rel="me" back to author.url. Two bounded fetches, cached per (author.url, origin) pair, and the result is shown with the same chrome as any other verified claim: there are two states, verified and claim, and this adds no third. The house can write whatever it likes on its side of the pair, but the house is already the party asserting the byline; what it cannot forge is Alice's page, which is exactly the half #35 relies on. A member whose author.url is the house page has nothing on the far side to check, and the byline stays a claim, as section 3 says.

This is also what makes tn-3 section 5's portability concrete: when Alice leaves, the house removes its rel="me", Alice's page points at her new origin, and the same reader rule follows her there.

5.6 Agent members

An AI that runs on the same client as the human publisher and publishes with a member's rights needs almost nothing from this convention, because #38 already settled the protocol side: an agent is a valid opaque author, at the studio it is a token with a member's scopes, and the protocol never asks who acted. Four client-side accommodations remain, none of them on the wire.

  1. The roster says what the client cannot tell. A member: true record can be a person or an agent, and nothing in a token reveals which. An agent member's record carries operator, the URL of the human or organisation that answers for it (tn-2 section 7), and a declared model. Both flow into what the studio stamps on the agent's items.
  2. The token scope decides the byline. This item is about whose name goes on the item. #52 already requires publishing to be a distinct verb from drafting, and that distinction is #38's response-versus-pipe line made mechanical. A draft-only token means a human approves and publishes: the human's byline, and one generated[] span naming the model. A publish-scope token means the agent publishes on its own initiative: the agent's byline with operator, and a whole-item generated[] span. The byline says who, the provenance says how, and the operator says who answers; none of the three is collapsed into another.
  3. Provenance in the address book is set by the resolver, never by the caller. This item is about what the address book may believe; it has nothing to do with the byline. No API path may assert self or bound. Anything an agent adds to the book is entered and stays off the wire until the studio resolves it. Without this rule an agent holding a contacts scope becomes the identity broker that rejected design 5 guards against. Unresolved @word warnings come back in the publish response in machine-readable form, as section 5.2 says for every client; an agent depends on them because it never sees the editor's soft warning.
  4. No pin or withdraw scopes for agent tokens by default. A pin is an irrevocable hosting promise and withdrawal is the only exit; tn-3's test says the house answers for both. Scope names are the build's (#52), and the default is conservative.

Two of the rulings in section 10 are what make agents safe here. Ruling 2, mentions are silent, matters most: an agent writing a hundred items with @-mentions produces no notifications, where an opt-in would have been the flood tn-3 section 6.2 describes by another route. Ruling 3 covers the byline: an agent with only a house member page stays a claim, which is honest, and operator is likewise a claim by the origin, the party already accountable under invariant 4, so there is nothing further to prove.

One question is left to the client: whether a house with several human members shares one address book or keeps one per member. Petnames are personal by construction, and a shared newsroom contact list is also ordinary practice. Either works with everything above.

6. Reading: resolving a mention in the scheme you speak

A receiving client finds .h-card elements in content_html and collects the href and the <data class="u-url"> values. It then does whatever its own schemes allow:

  • Match against its own address book. It normalises each identifier per scheme, three rules for three schemes:

    • https URLs: as §15.4 normalizes an origin — scheme and host case-insensitive, default port dropped, trailing slash normalized;
    • acct: identifiers: compare case-insensitively;
    • DIDs: compare exactly, except that a did:pkh:eip155:… account is compared case-insensitively on the address, and a bare CAIP-10 eip155:… met in the wild is read as the same account (section 7).

    The client then looks for a contact holding any of the identifiers. On a match it MAY show the mention as the reader's own contact, under the reader's petname.

  • Resolve schemes it speaks. An ATProto-aware reader can link the DID to a Bluesky profile, a wallet-aware reader can show the ENS reverse name, and a fediverse-aware reader can offer to follow the actor.

  • Do nothing. The link still works, which is the floor.

Three rules protect readers. They mirror #35's reader rules:

  1. A relabel replaces the whole mention. If the reader shows its own contact's petname, it also uses its own contact's URL as the link. Otherwise a publisher could pair the victim's DID with the attacker's href, and a reader would print the victim's name over the attacker's link. With this rule, a forged pairing makes the reader show its own, correct contact, with no way to redirect the click.
  2. A mention's identifiers are the publisher's claim and never prove anything. An h-card that lists a URL and a DID together does not tell the reader that they belong to one person. A reader MUST NOT add a mention's identifiers to its own contact record without checking them. This is #35's rule against merging identities across origins without a verified claim, applied to mentions. A match against the reader's book is a display decision, never a merge (§13.1 rules 5 and 7).
  3. No counts on the wire and no gating. "You were mentioned 40 times" is a follower metric by another name (#12, #13), and no document or feed carries one. A client may list mentions of a contact for its own owner. What it shows on a page is its own style (revised 2026-11-16, decision #108; this rule used to end "It never publishes them as a number").

A found-mentions list (session 60). A reading client MAY list, for its owner, mentions of the owner found in items it has already imported, under four conditions:

  • (a) the match is against the owner's own member record in the book, its url and ids (section 10, ruling 5), never against a new field;
  • (b) h-cards inside a baked blyg-transclusion are excluded: they are the quoted author's speech (below), and they are found when that author's own item is read;
  • (c) the list is kept apart from verified mentions and labelled as a find on the reading side, because nothing has been verified and nothing was received;
  • (d) no count, by rule 3.

Nothing is sent, so ruling 2 is untouched: this is the reader reading its own shelf. The wider ask, finding mentions in feeds the owner does not read, is refused: such a mention can reach the owner only if someone tells them, which is the notification ruling 2 refuses, or if a crawler finds it, which is a search engine's job and outside any client.

Quotations carry other people's mentions. A baked transclusion copies the source's content_html, h-cards included (§10.2, verbatim). Those mentions are the quoted author's speech. The quoting client MUST NOT treat them as its own, whether for notification, for its book, or for display as "mentioned by me".

The reference reader's sanitizer drops this markup today. blygger-studio/src/importer/sanitize.ts keeps class, but data is not in its tag list, so the element is unwrapped and its value removed. It also strips any href that is not http(s)/mailto/tel, which is right. The fix is small: allow the <data> element with value (inert text, never fetched). Without it, the reference client would publish the full identifiers and then throw them away on every read. Other clients' sanitizers will vary. Every reader keeps the visible link, so the design degrades to an ordinary link.

7. Scheme notes

  • ActivityPub. On the wire, an acct: identifier plus the actor URL as href. Actually notifying a fediverse account requires delivery to its inbox as an ActivityPub actor. A blyg is not an actor and should not become one in order to do this. Bridges such as Bridgy Fed, which turn Webmention-sending web sites into fediverse presences, are the route for anyone who wants it, outside the protocol.
  • ATProto. Emit the DID, not the handle. A handle that is the person's own domain is the best case of all: their url is https://alice.example/ and their DID resolves back to that domain. One record then counts as bound in two schemes.
  • DIDs. did:web is a URL with extra steps (#35). Other methods are stored and emitted when self (listed in the person's h-card or rel="me" links) and are otherwise left to clients that resolve them.
  • Ethereum. Emit the account as did:pkh:eip155:<chain>:<address>, which is the CAIP-10 account in DID clothing and the same bytes. Writing it as a DID keeps the wire to three URI schemes and spares readers a fourth normalizer; readers accept a bare eip155:… as the same account. ENS is an input convenience, because a name that can expire must never be the wire identifier. Proof of control is a signature, which is #35's second proof. A signed byline (EIP-191 over content_hash) is that proposal's mechanism, unchanged. Whatever the address book does, a wallet scheme is meaningful in a mention only when the person themselves published the address at their URL.
  • h-card. It is the carrier format. The contact's own representative h-card is also where the book learns their other identifiers. In practice, a person who wants to be mentionable across schemes lists them on their home page.

8. Recommendation for the reference client

The client should stay boring (the ruling that tabled blygger-studio#35: "studio should be boring"), so its default is narrow, and every wider scheme belongs in other clients or in extensions.

  1. Per-item bylines from a member roster, which closes the real multi-author gap. A member's author.url is their own URL when they have one, otherwise a house member page. Tie this in with #31 tokens so each member's scoped token publishes under that member's byline.
  2. An address book with @handle autocomplete, consumed at publish, by the server, on every write path, into a markdown link in content_md and an h-card in content_html, as in section 5 (section 5.2 on where the resolver runs).
  3. Schemes it resolves when a contact is added: https (h-card and rel="me"), fediverse handles (WebFinger) and ATProto handles (DNS or well-known, giving the DID), plus did:web. These all reduce to a URL or a DNS check, and none of them needs a vendored dependency (the session-29 ruling).
  4. Schemes it stores but does not resolve: other DIDs and did:pkh accounts. It accepts them as entered, and emits them only when the contact's own page lists them. ENS lookups, wallet sign-in and signature checking belong in an extension, not the base client.
  5. Its sanitizer keeps <data value>, so it reads the markup it writes.
  6. No notification. A mention is a markdown link to a person's page, so it is silent (section 5.3); the reference client sends no Webmention for one, and offers no switch to (section 10, ruling 2).
  7. Byline verification on a shared origin follows section 5.5 when the reader side of #35 is built: one rule, two fetches, two display states.
  8. Agent members per section 5.6: operator and model on the roster record, the byline chosen by the token's scope, resolver-only provenance in the book, publish warnings returned by the API, and no pin or withdraw scopes on agent tokens by default.
  9. Later: IndieAuth for member sign-in. IndieAuth proves that a member controls their URL at the moment the house mints their token, so the roster's url becomes verified from the member's side without a second fetch. It fits #52 (an OAuth-style minting flow) and is the one IndieWeb spec besides Webmention and microformats that the studio has a use for.
  10. A found-mentions list under section 6's four conditions (session 60): matched against the owner's own record, quotes excluded, labelled as a find on the reading side, no count. It is kept off the Mentions surface, which shows verified Webmentions.

Of the five schemes, the reference client should emit h-card markup and recognise the web, ActivityPub, ATProto and did:web natively, and treat Ethereum and other DID methods as data it carries but does not interpret. The full identifier list still goes on the wire for every scheme, which is what lets a wallet-aware or ATProto-native client resolve what the reference client only carries.

9. Rejected designs

Recorded because each will be re-proposed.

  1. An @ construct in the spec (a MAY directive in §10.1, a mentions[] field in the item, a blyg:mention feed element). Rejected because it would make authors addressable (§16.8). It would also add a reference kind that receivers would be expected to act on, which is a reply primitive by another route. Finally, it would freeze one identifier vocabulary into a permanent surface while the schemes themselves keep moving.
  2. Leaving @handle in content_md for each reader to resolve. A petname means something only in the book that defined it. Shipping one gives every forker and reader a name that resolves to whoever they call kyle (section 5.2).
  3. One canonical scheme that everyone must use (all DIDs, or all fediverse). This picks a winner among live communities. It also adds a resolver as a dependency for every reader. The census shows that the field already chose the URL.
  4. user@domain addressing inside a shared origin. Closed at #11 and again in tn-3 section 8: the path or subdomain already serves as the namespace.
  5. Putting entered identifiers on the wire by default. That would make every author an unwitting identity broker, publishing guesses about which accounts belong together.
  6. data-blyg-ids. It would survive today's sanitizer because of the data-blyg- prefix. Rejected because that prefix is spec vocabulary, and using it here would add a construct silently. Fix the sanitizer instead.
  7. Micropub as the members' write path. No normative write surface (#31). The studio's own API with scoped tokens already serves the purpose.
  8. Salmention-style propagation of mentions upstream. It pushes other people's responses onto a target's page. §15.5 forbids that: nothing lets a stubber put words on the target's page.
  9. A Webmention for every mention, or an opt-in switch for one in the reference client. A mention is a markdown link, the silent citation #79 kept, and its target is a person, whom no relation can name (section 5.3). The draft cited #32 here; #79 reversed #32 for the bracket form only, and the rejection stands. The reasoning is section 10, ruling 2; what a client that does send must respect is there too.
  10. An "acknowledged" display class between verified and claim, for a member's link to a shared origin. Rejected because any link from Alice's page to the house proves only that Alice linked to something there, and a third chrome state is more display for less proof. Section 5.5 keeps the reciprocal rel="me" and two states.
  11. Bare CAIP-10 as the wire form of an Ethereum account. It is a fourth URI scheme for the same bytes did:pkh: already carries (section 7).

10. Rulings (Fable 5.1, session 40, 2026-10-07)

The draft closed with five questions. The rulings follow, each with the principle it rests on; where a ruling differs from the draft's own recommendation, it says so.

1. Sequencing. The route is confirmed, and where it runs was decided the same session (decision #66): the project's own blyg at blyg.blygger.org carries RFCs, and comment periods run there. (a) This edited draft is published as a thread on that blyg, with a stated close date in the text; the version under comment is pinned, a revision during the period is a new version, pinned in turn when comments should move to it. (b) Comments are the protocol's own responses: a stub of the RFC item, whose stub_of.version records which draft it answers; a quote is a partial transclusion; a counter-proposal is a fork from the pin. Anyone without a blyg can open an issue on blygger-spec instead, and the item says so. There is no RFC section on blygger.org. (c) Nothing in section 8 is built in the reference client until the period closes. (d) After that, the RFC becomes a technical note of its own by the gate #35 uses for tn-2: one client emits mention h-cards and a second resolves them. It does not fold into tn-2. That note's subject is one person's URL and the two proofs of it; this one's is a client convention for naming other people (decision #90 later moved the promotion to the close of the comment period and made this gate the first revision trigger instead; see the header), and folding them would make the identity note carry a studio design. Two rulings here are about author rather than about mentions, and tn-2 absorbs them when it is written: the shared-origin proof (ruling 3) and ids (ruling 5). The git file stays the single source throughout; the blyg publishes versions of it, never hand-edited copies (#66).

2. A mention does not notify. Mentions are silent, and the reference client sends nothing for one and offers no switch to. As written in session 40 this was #32's principle carried over: a link asserts nothing on the target's behalf, so a receiver has nothing to verify, and a notification with no verifiable claim behind it is the trackback class §15.6 holds down. #79 reversed #32 after this text was published, making the bracket form [[id]] disclose through links[] and notify as a notice. The ruling stands unchanged, on two grounds that #79 does not touch. First, a mention's wire form in content_md is the markdown link, which is exactly the form #79 kept as the one silent citation; the @ form is a markdown link with a better name, and it inherits that link's silence. Second, a mention's target is a person's page and never an item, so no relation in §15 and no links[] entry can name it: authors are never addressable (§5.5, §16.8). "@ notifies" is an expectation from media with reply primitives, which this one refuses (§16.8). Two further facts settle the edges. §16.8's bar on new relations is not in play either way, for that second reason; §15 governs mentions between blyg items, and this was never a §15 question. And where a person's URL happens to be a blyg page, a plain Webmention to it is refused outright (§15.3 step 1: the target must name a published item) or marked failed (§15.4 step 4), so it could only ever cost the receiver fetches. What remains is the open web: any client may send a W3C Webmention to a non-blyg page for a link it publishes, as IndieWeb sites do, and this note neither blesses nor forbids that. A client that does so should observe three things: never to a target inside a blyg origin; never for an h-card inside a baked quote (§10.2 verbatim, the quoted author's speech); never by default, only per mention at the author's choice. This differs from the draft, which recommended a per-mention opt-in in the reference client. The client stays boring (blygger-studio#35), and the one way to cite without notifying stays wide.

3. Reciprocity on a shared origin. Not an acknowledgement class. The proof is #35's reciprocal rel="me", unchanged; what moves is its origin-side end, from the origin to the member's page under it (section 5.5). Both links then say "this is also me" truthfully, because both pages are the member. The reader rule is one rule with two acceptable far ends: the identity origin itself, or a page that has it as a prefix and links back. Two fetches, two display states, no third chrome. The draft's alternative, any link from author.url to the origin shown as "linked from", was rejected because a link proves that the member linked to something at the house, not that they write there, and because a third state is more display for less proof (section 9, item 10). This is a ruling about identity semantics, so it is Fable's under #58, and tn-2 carries it when written. tn-3 section 5 already promised that a verified byline survives a move from shape B to shape A; this is what makes that true.

4. The spec says nothing. Confirmed. A sentence about preserving microformats in content_html would be the spec's first word, however indirect, about identity markup, and #11's silence on identity is a principle rather than an omission. Under #43 it would in any case be a revision that readers already handle, and a convention one client emits is not yet a reader question. The fix lives in the reference client's sanitizer (section 8, item 5). Revisit when a second client emits the markup and a sanitizing reader's loss of it has caused a failure someone can name; the candidate home would be §13.1, not §5.2.

5. ids in author. Allowed as a conventional member, filtered as section 5.3 filters mentions. #35 already places two conventional members in author, the signature and an agent's operator, so a third of the same character adds no principle. The shape: an unordered array of absolute URIs in the three wire schemes, https:, acct: and did: (Ethereum as did:pkh:, section 7), each self or bound from the member's own publications. Because of that filter the house relays what the member publishes about themselves and asserts nothing new. §5.5's pass-through rule binds ids as it binds every author member, and §13.1 rules 5 and 7 still hold: a reader matching ids against its book is making a display decision, never a merge. The draft's reason stands as the practical one: a reader should not need a fetch to match a byline against its address book.

What happened. Published for comment under ruling 1 on 2026-10-07. The period closed on 2026-11-04 with comments (section 11). The RFC was promoted on 2026-11-05 as this note, tn-6 (decision #91, reasoning in v0.4-plan.md §18). The decision list carries one entry for the five rulings (#67), with this section as its reasoning. The reference client's RFC-1 work is unblocked, since ruling 1(c)'s condition is met, and it is built as revised by the resolver paragraph in section 5.2 and the found-mentions list in section 6. The first build revises this note.

11. Comments received, and what changed

Comments were read at promotion (session 60, 2026-11-05).

Mike Casey (caseyjr.org, 2026-11-02) asked two things. His question on section 5.2, where the @handle resolver runs and what happens to an API publish, produced the paragraph on the publishing server's resolver: it runs at publish on every write path, its warnings go to every client, and an unmatched @word is literal prose. His reading of section 5.6, which took the byline rule and the address-book provenance rule as one, showed that the two items needed to say what each governs; each now opens with that sentence, and no rule changed.

Aneesh Sathe (blyg.aneeshsathe.com, 2026-11-04) asked for a way to see where one is mentioned. The half that concerns items a reader already holds is now section 6's found-mentions list, with section 8 item 10, under four conditions that keep it a reading of the owner's own shelf. The half that concerns feeds the owner does not read is refused, because only a notification, which ruling 2 refuses, or a crawler, which is a search engine's job, could find such a mention.

Matthew McDowell-Sweet linked the RFC in passing (msweet.net, "Bronze eels") without a request, so nothing changed for it.

Independently of the comments, the 0.4 text forced one change. Decision #79 reversed #32 after the RFC was published, so the grounds for a mention's silence in sections 5.3, 8, 9 and 10 were restated: the markdown link is the silent citation #79 kept, and a person is never addressable. Ruling 2's conclusion is unchanged.

This note's canonical text is at blygger.org/notes/tn-6/, and its source is docs/notes/tn-6-mentions-and-identifier-schemes.md in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.

read the thread →

v4 · pinned: v1, v2, v3, v4

“Promoted to TN-6 after the comment period; see §11.”

Created: Oct 7, 2026 Most recent: Nov 19, 2026, v4

thread

TN-3 — Groups need no new construct: N origins, one masthead, and the stubbing anti-pattern

Technical note · non-normative · session 28, 2026-09-28 (Opus 5, writing up decision #36 — ruled session 27 by Fable + Venkat). Decision record for locked decision #36. Technical notes record design reasoning — especially rejected designs — alongside the normative spec; they constrain nothing and are citable rationale, not protocol. Written against protocol 0.3 as published on 2026-09-28; every construct named here is built and live, but no pre-1.0 version promises anything (#21), so check the living text before you lean on a detail.

Revised session 38, 2026-10-06 (Opus 5.5), after decision #61: §3 gains the consequence that members on one host cannot verify mentions in each other's name, which was not true of the 0.3 text this note was first written against.

1. The question

Two requests arrived from early users within days of the first strangers standing up their own blygs:

  1. "A multi-user blyg with separate folders." A publication or workgroup wants several people writing under one roof, each with their own space.
  2. "An aggregator that stubs everything." A site wants to be the one place to follow a group, and proposed doing it by emitting a stub for every item the members publish.

Both read like requests for a new construct — a group, a space, a members list, a pipe. Neither is. The first decomposes into two shapes the protocol already has, distinguished by one question; the second is an anti-pattern, and the interesting part is why it cannot be stopped by a rule.

The spec's own involvement in all of this is two sentences of documentation: a warning in §10.6 and the honest shape named in §13.5. This note is the reasoning behind those sentences.

2. There is no folder on the wire

Start with what "separate folders" would have to mean. A blyg is a directory of files under an origin: one blyg.json, one feed.xml, one items/index.json, and item documents (spec §4). Every reference in the protocol — transclusions[], stub_of, forked_from — names {origin, id, version} (§5.9). Subscription targets an origin (§12.2). Withdrawal is an act by an origin about its own item (spec §9). Pins are hosting promises made by an origin (spec §8).

Nothing in that list has a place to put a folder, and adding one would mean adding an addressable sub-identity beneath the origin — which is exactly what #11 refuses ("authors are never addressable … permanently") and what invariant 4 refuses one level up ("the only authenticated entity is the publishing client at its domain").

So the folder, if it exists, is a studio view: a way of organising the authoring tool, invisible on the page, which is precisely where #1's studio/page split puts it. Members in the studio are #31's scoped bearer tokens — owner-minted, owner-revoked, per-client, with coarse verb scopes. A member is a token with a member's scopes, and the wire never learns that any of this happened.

What the request actually asks, once the folder is set aside, is: how many origins? There are two answers, and they are different protocols of trust, not different implementations of one.

3. Shape A — N origins under one host

Mount independence (#14) means a blyg's origin is any absolute base URL, and no protocol construct may infer anything from the path. So one host serves as many blygs as it likes:

https://house.example/alice/     blyg.json, feed.xml, items/…
https://house.example/bob/       blyg.json, feed.xml, items/…
https://house.example/           the house's own blyg (optional)

Subdomains work identically (alice.house.example) and were exercised in the wild by a stranger who path-mounted at /blyg/ without being told it was allowed.

The index is a blogroll. The house publishes blogroll.opml (§11) listing its members. A reader importing that one OPML file subscribes to every member at once — and nothing custom was needed to make that work, because each member's feed carries <blyg:manifest>, so plain OPML resolves to the blyg upgrade for free (§11, #13, #17). The members list a group construct would have introduced already exists, in a format other people's tooling reads, published as a deliberate curated act with no completeness claim.

Optionally a house blyg. The house origin can be a blyg of its own, and if the house has an editorial voice it should be: editorials, announcements, curated hoppers of member work (§13.5), stubs that actually respond to members' pieces. The house is then a publisher among publishers, with its own accountability, rather than a directory pretending to be a publication.

Consequences worth naming before choosing this shape:

  • Each member withdraws their own items (spec §9) and owns their own pins (spec §8).
  • Each member's author is their own assertion at their own origin.
  • Cross-member quoting is ordinary cross-client transclusion (#26) and sends real Webmentions (§15). The house's internal conversation is publicly checkable exactly like anybody else's — a feature, not overhead.
  • Members cannot speak in each other's name. A mention verifies only if the source's item document was fetched from exactly {origin}items/{id}.json for the origin it declares (§15.4 step 2, decision #61). So a document served under house.example/alice/ that claims to be house.example/bob/ fails, and Bob's items are safe from Alice even though they share a host. This was not true when this note was first written: the 0.3 text compared scheme, host and port only, and Aneesh Sathe's conformance model found the hole in exactly this shape (finding F1). The eighth revision of the spec closed it on 2026-10-06, and blygger-studio 0.32.2 implements it. A receiver still running older code keeps the hole until it upgrades, so a house on a shared host should run current clients for all its members.
  • The cost is real: N deploys, N polling crons, N sets of pin promises, N archives to keep serving forever. Withdrawal being permanent and pins being irrevocable means an origin is a long commitment, and this shape makes N of them.

4. Shape B — one origin with bylines

The masthead, specified since #11: one origin, one feed, one archive index, one manifest, and per-item author bylines. The feed invariant is single-publisher, never single-author (§5.5), precisely so that this shape is conformant without a social layer.

Consequences, which are the mirror image of shape A's:

  • The publisher can withdraw anyone's item and owns every pin. One party is accountable for everything at that origin, which is the point.
  • No member has a citation surface of their own. A stub of Alice's piece is a stub of the house's item, carrying Alice's byline as passed-through data.
  • One subscription, one blogroll, one editorial identity, one deploy, one cron.
  • A member's items cannot leave with them. Ids are origin-scoped (#2, §5.1); the same words at a new origin are a new item, or a fork from a pin (§5.6).

5. The test: who can withdraw

#36 names one question to choose between the shapes, and it is not "how many people are there":

Can this person's accountability be someone else's?

Operationally: who gets to withdraw, and who owns the pins. Withdrawal is the protocol's only exit and it is permanent (#8); a pin is an irrevocable promise to serve one version forever. Those two are the whole of what an origin is on the hook for. A member whose retractions must be their own decision, and whose citations must survive a falling-out with the house, needs their own origin. A member who is content for the house to answer for their work does not.

This cuts across the intuitive axis. A five-person magazine with a real editor is one origin — the editor withdrawing a piece is the editorial relationship working. Two friends who trust each other completely but publish under professionally distinct names need two origins, because the thing they need separate is not affection but accountability.

The choice is less fateful than it looks, because of #35. Practice for identity (proposed in docs/proposals/identity-practice-proposal.md) is that a person is a URL they control, provable by a reciprocal link or a signature. A byline carrying a verified home URL is recognisable after a move from shape B to shape A, which is otherwise impossible: §5.5 forbids treating equal author values at different origins as the same entity, and a verified claim is the only thing that lifts it. Be precise about what is portable, because this is where an implementer will over-promise: the person is portable, the items are not. Moving means new ids at a new origin, with lineage expressed as forks from pins if the old origin pinned anything.

6. Why content-free stubbing is an anti-pattern

The aggregator-by-stub proposal is the interesting half, because the pipe it describes is byte-for-byte conformant. Every document it emits is a valid thread with a valid stub_of (§10.6). Every mention it sends passes structural verification (§15.4). No rule in the spec is broken. It is still wrong, for three independent reasons, and then there is the question of why the spec responds with prose instead of a MUST NOT.

6.1 The marker is the one claim nothing can check

stub_of is the protocol's only machine-readable assertion that this is a response to that. §10.6 rule 2 makes readers rely on the marker and never on body inspection — deliberately, because inspecting a body to decide whether it is a response would require the protocol to read prose, and it would let a reader overrule an author about what they wrote.

That design puts the marker's entire value in its honesty. Structural verification does not help: §15.4 checks that the source document really names the target at the origin it claims — it proves the relation exists, never that the relation means anything. A pipe satisfies it perfectly. So a stub emitted with nothing to say is not a weak response; it is a false statement in the one field where the protocol has no defence but truthfulness.

6.2 It floods the only scarce inbound signal there is

The protocol has no follower list, no follower count and no metrics on the wire, at any level, ever (#12, #13, §11; "on the wire" added 2026-11-16, decision #108: what a client's page shows is not the protocol's). A publisher's entire inbound signal is verified mentions (§15.5) — and #41 identifies it as the strongest discovery signal available, because someone who responded to you demonstrably read you.

That signal is scarce by construction, which is what makes it informative. Pipe-generated stubs are indistinguishable from real ones at the receiver — the receiver sees a valid thread with a valid marker — so they degrade the signal to noise with no filter available, and the noise is loudest for exactly the publishers a group aggregator would target.

This is the trackback failure reproduced inside the protocol. Trackback died of unverified spam, and the protocol answered it with structural verification (#13). Verification defeats the impostor, who claims a relation that isn't in the document. It does nothing about the relay, whose relation is genuinely there and genuinely empty.

6.3 It reprices re-emission to zero, which §13.5 forbids by cost

§13.5's ban on re-emitting imported items has two halves with two different enforcement mechanisms. The mechanical half — imported items MUST NOT appear in your feed, index, or item documents — is enforced by the blyg:id rollup contract and the single-publisher invariant: violating it breaks readers, so it holds itself up. The editorial half — "speech about someone else's content costs editorial work" (#12) — is enforced by nothing but the cost. Write an item; that is the price.

Automating stub creation sets that price to zero. The result is the naked retweet that #12 refused, rebuilt out of legal parts: content appears on your feed under your origin with no editorial act anywhere in the loop. Nothing mechanical catches it, because there is nothing mechanically different to catch.

6.4 The line is content-free, not automated, and not non-human

This must be said explicitly, because the obvious summary of sections 6.1–6.3 above is "don't let robots stub", and that summary is wrong. #38 rules the protocol agent-agnostic at every level: an agent is a valid author (§5.5), generated prose is disclosed by generated (§5.7), and invariant 3 constrains the reader side and the wire, never who writes.

An agent that reads each member item and answers it under its own byline, disclosed as generated, is stubbing legitimately, however many stubs that is — a critic, not a planet. Many mentions from one busy respondent are fine; each one says a real thing about a real item (#44 makes the same point for generation sources). What is illegitimate is a response with nothing in it, whoever or whatever emits it. A human who copy-pastes "interesting" under fifty transclusions a day has built the same pipe by hand.

6.5 Why this is a warning sentence and not a MUST NOT

The natural instinct is to forbid it: "a stub MUST carry editorial content." That rule cannot be written, for two reasons.

It is not checkable. "Has something to say" has no machine test. A word count is trivially defeated and would fail legitimate one-line responses. A similarity check against the target is an editorial judgement the protocol has no business making. A MUST that nothing can test is worse than no MUST: it teaches implementers that this spec's requirements are aspirational, which devalues the ones that are real. #48's conformance partition depends on MUST-clauses being exactly the set a checker fails on.

The constructs are identical. A pipe's output and a critic's output differ only in what the prose says. There is no field, count, flag, or shape that separates them — which is the same reason #38 refuses an "I am an agent" flag (a spammer would not set it) and #34 refuses a maintenance declaration (the software that would have to say it is the software nobody updates).

So the spec does the only thing available: it says plainly, in §10.6, that a stub emitted without a response is a misuse, names the honest alternative in the same breath, and leaves it as reputation rather than validation. A protocol that cannot enforce a norm can still refuse to pretend the norm doesn't exist.

7. The honest aggregator, which needs nothing new

Everything the "one place to follow a group" request actually wants is already built:

  1. Curation display (§13.5). Import the members, display their items publicly with source attribution and links to the origin. Publicity is a property of the displayed list, never of an imported item — there is no per-item public toggle and there will not be, because that is the naked retweet again.
  2. A blogroll of the members (§11). One OPML import subscribes a reader to every member. This is the aggregator's most valuable output: it makes itself unnecessary for readers who have a blyg-aware client, which is the correct relationship for a directory to have with the medium it indexes.
  3. Optionally a plain RSS digest, outside the blyg surface (§13.5). Excerpts and links to origin permalinks, no blyg: namespace, not feed.xml. Its consumers are L0 readers who need nothing from the protocol, and keeping it outside the surface is what stops it being re-emission.
  4. Optionally its own blyg, if it has an editorial voice — see section 3 above. A digest is plumbing; an editorial voice is a publisher, and a publisher's stubs are real responses.

No re-emission at any step, and no stubs on the members' behalf.

8. Rejected designs

Recorded because each will be re-proposed.

  1. A group or space construct — a members array in the manifest, a group key, a shared parent identity. Rejected three ways: it is a follower-list-shaped surface and the first place a count could attach (#12/#13, and #47 refused a per-item responses list for the same reason); it makes something below the origin addressable, which #11 forbids permanently; and it duplicates the blogroll, which is already the members list, already curated, already read by other people's tooling.
  2. user@server or any two-level addressing. Closed at #11: DNS is the namespace. Mount independence is what makes the second level unnecessary — a path is a namespace, and house.example/alice/ is a first-class origin with no new grammar.
  3. Per-author feeds carved out of one origin (feed.xml?author=alice). The feed URL is bound up with subscription identity (§12.2), and the manifest's feed value is what locates it (#51). A per-member feed with its own manifest is not a variant of shape B; it is shape A, with the deployment cost hidden until the first withdrawal.
  4. Letting an aggregator re-emit member items. Not a policy call but a collision: blyg:id rollup plus the single-publisher invariant means the copy and the original present as one item with two publishers (§13.5).
  5. A digest construct on the wire. Unnecessary — the digest's audience is plain RSS readers, so it needs no blyg vocabulary, and giving it some would put a second lossy notification plane inside a surface that already has one.
  6. The aggregator-by-stub pipe, per section 6 above.

9. What stands

  • No new construct for groups, at any level. Two supported shapes: N origins under one host with a house blogroll (and optionally a house blyg), or one origin with per-item bylines.
  • The test is who can withdraw — accountability, not headcount. #35's verified home URL is what keeps a byline recognisable if the answer changes later; the person moves, the items do not.
  • Members are studio-side, as #31's scoped tokens. There are no author folders on the wire: one origin, one feed, one index, and the byline is the distinction.
  • A stub emitted without a response is a misuse — false in the one field nothing can verify, a flood of the only scarce inbound signal, and a repricing of re-emission to zero. Said as a warning in §10.6 rather than a rule, because no rule can distinguish the pipe from the critic, and an unenforceable MUST would cost more than it bought.
  • The honest aggregator is §13.5 plus §11, plus a plain RSS digest outside the surface if it wants one. This is locked decision #36; relitigating it starts from this note.

This note's canonical text is at blygger.org/notes/tn-3/, and its source is docs/notes/tn-3-groups-and-aggregation.md in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.

read the thread →

v2

“TN-3 revised; see the source history.”

Created: Oct 7, 2026 Most recent: Nov 19, 2026, v2

thread

Blygger Studio 0.64.1: Security: Hono and fast-xml-parser upgrades

Released 2026-11-19, the reference client. v0.64.1 on GitHub.

Upgrade if you run your own node. Hono, the framework that routes every request, goes from 4.13.14 to 4.13.18. The older version has published advisories, among them one where the router can skip wildcard middleware for some routes and for paths with an encoded line terminator (GHSA-h7mg-cq63-vhpq, GHSA-4m76-xfj5-7975, GHSA-46wx-v44x-9hh2, GHSA-4h7h-rv7c-7m2v, GHSA-3gg2-335m-rxc6). The studio attaches its sign-in checks as wildcard middleware, so this release does not wait to find out whether any route was reachable. fast-xml-parser, which reads the feeds you subscribe to, goes from 5.11.2 to 5.12.1 for a low-severity CPU-exhaustion advisory (GHSA-474x-hrwr-fgx4). npm audit reports no runtime vulnerabilities after it. No behaviour changes. Private contract 5.13.0, SDK 0.19.0, unchanged. Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 19, 2026

thread

Blygger Studio 0.64.0: Shared components, link notices apart, two tangling fixes

Released 2026-11-19, the reference client. v0.64.0 on GitHub.

Shared UI components (Shannon's studio#88). The studio's controls now come from one set of primitives, most of them on Base UI: buttons, icon buttons, toggles and toggle groups, tabs, fields and inputs, checkboxes, radios, selects, accordions, tooltips, dialogs, sheets and toasts. Each has documented names, variants and states, with better keyboard and screen-reader behaviour. Two things look different: the reading filters are a toggle group instead of pills, and the secondary button is a lighter shade. Everything else looks and behaves as before. On a phone, toasts now appear at the top of the screen, so one that appears under the last tap is not held open by the hover Safari keeps there; a WebKit browser test guards it.

Link notices apart (spec 0.4 §15.5; ROADMAP row 77). On the responses page, each item's links from other blygs are listed under "Linked from", after its responses, labelled as notices that are never shown on the public page. The counts line says how many blygs link there, and "on the page now" no longer counts them.

Tangling fixes (tangling plan §2.4, §2.6). A thread version that no longer quotes or links a part it made publishes as before, and the publish warning names the part, which stays published on its own. In a stub, the passage chooser leaves alone a quote inside a ![[+ …]] span, since that quote belongs to the new item, and a quote added with the cursor inside a span goes after it.

MentionGroup gains links, and its visible no longer counts link notices. Private contract 5.13.0, SDK 0.19.0. Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 19, 2026

thread

Tangling: write the essay, publish the parts

Blygger Studio 0.63.0 adds tangling. You write one piece, mark the passages that can stand on their own, and publish once. Each marked passage becomes an item of its own, with its own page, history and feed entry. The piece you wrote becomes a thread that quotes them, so it reads exactly as it did.

Why

A blyg is made of small pieces that quote each other. A fragment can be cited, quoted in someone else's thread, and pinned at a version. That is the medium's strength. It is also a discipline most writers do not have. Nobody sits down to write a commonplace book of standalone claims. People write essays, and only afterwards notice which paragraphs were the ones worth keeping.

Until now, getting those paragraphs out meant doing it by hand: copy the passage into a new item, publish it, and go back to replace the passage with a quote. Tangling does that bookkeeping for you. The name comes from Knuth's literate programming, where one document "tangles" into the separate pieces a machine needs. Here the machine is the reader, and the pieces are the parts of your argument that other people will want to point at.

How it looks

Mark a passage with ![[+ and ]]:

Most of what we call infrastructure is invisible until it breaks.

![[+ Stigmergy is the mechanism by which a protocol becomes invisible
to the people inside it. The trail tells you where to go, and you
stop noticing that someone laid it.]]

That is why protocol failures feel like betrayals rather than accidents.

The preview shows the marked passage as a dashed quote, so you can see what will become its own item. When you publish, the studio counts first: "This will publish 1 new item and this thread." Nothing is created until you choose publish all. Then the new item is published, then the thread, and the thread's source is rewritten to an ordinary quote of the new item:

![[k3v9… | Stigmergy is the mechanism by which…]]

From there on it is a normal quote. Edit the new item and the thread can pick up the edit like any other quote. Delete the quote from the thread and the item stays published.

A single publish can mark up to ten passages. If any of them would fail to publish, or the thread itself would, nothing is created at all. If the publish stops part way, for example because the connection drops, the next publish finishes it.

Placeholders: the ideas you haven't written yet

The same release adds a smaller relative. [[+ text]] inside a sentence, without the !, marks an idea you mean to come back to:

This connects to [[+ the economics of trail maintenance]],
which deserves its own post.

Publishing makes a new thread whose text is just that phrase, as a heading, and turns the phrase in your sentence into a link to it. The new thread's working copy carries a private note saying which thread and which sentence it came from, so that when you come back in a month you know why it exists. Notes like that are comments to yourself and are never published. Later you open the placeholder, write the post, and publish again. Everyone who followed the link now finds the real thing at the same address.

Some ways to use it

  • Essays that yield quotable claims. Write the argument end to end, then mark the three or four sentences you would want someone to quote. Each gets a stable address that a reply can cite.
  • Definitions in a longer piece. Mark each term's definition where it first appears. Your later writing, and other people's, can quote the definition instead of restating it.
  • Meeting or reading notes. Write the notes as one document and mark the decisions or the passages worth keeping. The notes stay as the record, and each decision becomes something you can link to.
  • Outlining forward. Write the overview and use placeholders for the sections you haven't written. The overview publishes now, with working links to each section's future home.
  • A book's chapters. A contents page can link chapters written separately, and a chapter can be drafted as one long piece and tangled into sections.

What your readers see

One act of writing now produces several items, and every item is a real publication with its own feed entry. The spec has no quiet publish, because a publish the feed leaves out is hidden from subscribers. Without care, one tangled essay would arrive as half a dozen separate entries in a reader's feed.

So readers fold them. Blygger Studio's reader shows the thread as one entry, marked +N parts, and moves the parts it quotes into Background, where they can still be opened and nothing is lost. Placeholders fold the same way, but only when they say nothing beyond the link's own words. A chapter that a contents page links seconds after it was published stays its own arrival. The rule for that last case was settled the day 0.63.0 shipped, in the eighteenth revision of the spec, §13.7.

None of this needs anything new on the wire. The ![[+ …]] and [[+ …]] forms are the studio's own authoring syntax and are rewritten before anything is published. A blyg reading yours sees ordinary items and an ordinary thread that quotes and links them, plus links[], which 0.63.0 also starts to publish. Any client can fold a burst from what is already in the item documents.

Try it

Tangling is in Blygger Studio 0.63.0, live on blyg.blygger.org, venkateshrao.com/blyg and blyg.protocol-institute.org. The syntax page in the studio (more → syntax) has both forms. If you run your own node, npm run upgrade brings it in, along with two migrations. The design is in docs/tangling-plan.md, and the history of the idea is on blygger-studio#20.

Source: docs/posts/2026-11-18-tangling.md in blygger-spec, which is where revisions are made. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 19, 2026

thread

Blygger Studio 0.63.0: Tangling, placeholders, and links on the wire

Released 2026-11-18, the reference client. v0.63.0 on GitHub.

Tangling (decisions #78, #100; ROADMAP row 45). Wrap a passage in ![[+ …]] and publishing makes it a new item of its own, quoted back where it stood: the thread keeps reading the same, and the passage gains its own page, version history and feed entry. Each new item is a thread. Publish shows a count first ("this will create N new items") and asks before minting them, for the studio and for any client on the API (a publish that would tangle answers 409 tangle-confirmation-required until it sends tangle: true). Nothing is minted unless every new item and the thread itself would publish; the new items publish first, then the thread, so the thread is the newest entry (§13.7). A tangle that stopped part way is finished by the next publish. Up to 10 spans per publish. The preview shows a span as a dashed quote; spans are inert in code, TK scopes and comments.

Placeholders. [[+ text]] inline makes a new thread for an idea not yet written and turns the sentence's text into a link to it, [[id | text]]. The new thread's text is the anchor text as a heading, and its working copy carries a comment naming the thread and the sentence it came from (comments never publish). Placeholders share tangling's count, cap and confirmation.

Links on the wire (spec 0.4 §10.3a, decision #79; ROADMAP row 77). Every version records the items its [[id]] links resolve to, in text order, and item documents carry them as links[], each with an origin when it is another blyg's. Imports store them. A link to another blyg's item now sends it a mention; the receiver files it as link, the last of the §15.4 relations. A link is a notice: it is never listed among an item's public responses (§15.5). The syntax page says so beside [[id]].

Folding (spec §13.7, eighteenth revision, decision #112). A thread's placeholders fold under it as its parts do, but only when published in the same act and saying no more than the link's own text. A chapter linked by a contents page published seconds later is its own arrival. Your own items fold by link only when the thread minted them.

Local patches. npm run patches lists the commits this install carries that upstream does not, and flags the ones that touch the wire. Settings shows "This build carries N local patches". npm run upgrade lists them before merging and names the local commits in any file that conflicts. The bug template asks for the count. The developers' guide, Where does my change belong?, says when a change should be a patch, a mod, an extension or a pull request.

Publish takes tangle and answers parts: [{id, version}]; items carry tangled_from; versions carry links_json; the mention relation enum gains link. Private contract 5.12.0, SDK 0.18.0. Migrations: two. 0047_tangled_from.sql adds items.tangled_from; 0048_links.sql adds versions.links_json and imported_items.links_json. Both recreate their tables' change triggers. Versions published before 0048 carry no links[] until they are next published.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 19, 2026

thread

Mathematics on a Blyg

Blygger Studio 0.62.0 can write mathematics. Put TeX between dollar signs and it publishes as MathML, which every current browser draws: no script, no stylesheet and no font travels with the page. This post is itself the demonstration. Every formula below was typed between dollars in the studio's editor.

How to write it

One dollar on each side for a formula inside a sentence, two for one on its own lines:

Euler's identity, $e^{i\pi} + 1 = 0$, inside a sentence.

$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}$$

which reads as: Euler's identity, eiπ+1=0e^{i\pi} + 1 = 0, inside a sentence.

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

The rule is pandoc's: an opening dollar must be followed by a character that is not a space, and a closing one must follow such a character and must not be followed by a digit. So prices are left alone. A coffee costs $4 and a pastry $5, and that sentence has no mathematics in it. A dollar sign you want to keep literal can be escaped as \$, and anything in code stays exactly as typed. The Σ button in the editor's toolbar wraps a selection in dollars, or starts an empty formula.

A small gallery

The quadratic formula:

x=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}

Bayes' theorem:

P(A|B)=P(B|A)P(A)P(B)P(A \mid B) = \frac{P(B \mid A)\,P(A)}{P(B)}

The Basel problem, a sum with limits: ∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}. Inline formulas with tall parts sit inside the line without pushing it apart.

A matrix and its determinant:

det⁡(abcd)=ad−bc\det\begin{pmatrix} a & b \\ c & d \end{pmatrix} = ad - bc

A function defined in pieces:

|x|={xif x≥0−xif x<0|x| = \begin{cases} x & \text{if } x \ge 0 \\ -x & \text{if } x < 0 \end{cases}

Maxwell's equations, aligned:

∇⋅𝐄=ρε0∇⋅𝐁=0∇×𝐄=−∂𝐁∂t∇×𝐁=μ0𝐉+μ0ε0∂𝐄∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned}

The Fourier transform:

fˆ(ξ)=∫−∞∞f(x)e−2πixξdx\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\, e^{-2\pi i x \xi}\, dx

A limit, a binomial coefficient and a continued fraction: limn→∞⁡(1+1n)n=e\lim_{n \to \infty} \left(1 + \frac{1}{n}\right)^n = e, (nk)=n!k!(n−k)!\binom{n}{k} = \frac{n!}{k!\,(n-k)!}, and

2=1+12+12+12+⋯\sqrt{2} = 1 + \cfrac{1}{2 + \cfrac{1}{2 + \cfrac{1}{2 + \cdots}}}

Sets and logic: for every ε>0\varepsilon > 0 there is a δ>0\delta > 0 such that |x−a|<δ⟹|f(x)−f(a)|<ε|x - a| < \delta \implies |f(x) - f(a)| < \varepsilon, for all x∈ℝx \in \mathbb{R}.

What other clients see

The item document carries the formula as MathML Core inside content_html, with the TeX you typed kept beside it in an application/x-tex annotation. A client that draws MathML shows it as it appears here. One that doesn't can show the TeX, which is still readable. The markdown in content_md keeps the dollars, so a client that renders from the source can draw formulas its own way.

When Blygger Studio reads another blyg's post, or a quote baked into a thread, it does not trust the MathML it is given. It discards each formula and redraws it from its TeX annotation with the same renderer it publishes with, so nothing inside a formula on your screen is markup from someone else's page. A formula with no annotation is dropped. Past a thousand formulas in one document, or on any error, a formula shows as its TeX in code instead.

Quotes, excerpts and the edges

  • A partial quote must not cut through a formula. The stub editor refuses such a selection, and so does publishing.
  • Excerpts, titles and labels show a formula as its TeX between dollars, so a link to this post reads sensibly anywhere.
  • A formula that doesn't parse shows in red in the preview and blocks publishing, naming the formula.
  • A few commands that browsers don't draw are refused with their name: \cancel, \bcancel, \xcancel, \sout, \angl, \phase and \longdiv. \boxed and \fbox draw without the box.

The drawing is done by temml, in the server only. The design is decision #105 in the spec's 0.4 revision (§2, §5.2 and §14), and the build is studio#149.

Source: docs/posts/2026-11-16-mathematics.md in blygger-spec, which is where revisions are made. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 16, 2026

thread

Blygger Studio 0.62.0: Mathematics, and bursts fold under their thread

Released 2026-11-16, the reference client. v0.62.0 on GitHub.

Mathematics (decision #105; spec 0.4 §2, §5.2, §14; studio#149). Write $…$ inline and $$…$$ on their own lines, by pandoc's tex_math_dollars rule: money, lone dollars, escaped \$ and anything in code render exactly as before. A formula publishes as MathML Core with its TeX in an application/x-tex annotation, and nothing else: no stylesheet, script or font. A formula that does not parse shows in red in the preview and blocks publishing, naming it; a partial quote that cuts through a formula is refused. Excerpts, titles and labels show a formula as its TeX in dollars. A Σ button and a Mathematics section on the syntax page. Drawing is temml 0.14.0 (MIT, no dependencies), in the Worker only; the build fails if it reaches the browser bundle. In the reader, every formula in an imported or quoted document is discarded and redrawn from its TeX annotation by the same renderer, so nothing inside a formula is ever the publisher's markup; one with no annotation is dropped, and past 1,000 formulas or on any error a formula shows as its TeX in code. Reviewed twice by Fable (sessions 69–70) and checked on an iPad.

A thread published with its parts folds them (spec §13.7; ROADMAP row 112, Background phase 3, pulled forward so readers fold a tangle before the studio can publish one). When a thread version is the first to name items from its own blyg that were first published within 15 minutes before it, those items go to Background as part of a burst, and the thread shows +N parts, listing them in place. Times are clamped to when this reader first saw them, so a future-dated item folds nothing. A part's later version is an ordinary update and leaves Background; a thread quoting an older item, or another blyg's, folds nothing. Your own tangles fold the same way in your own reading feed. The rule is one definition shared with the public pace-layered order (src/burst.ts). Public pages and feed.xml are unchanged: every part is still published and imported (§7, §13.1).

Two more Background rules: no words of its own (a version that is only quotes of other posts, §15.4's repost test as §13.2 allows) and republished unchanged (the same text and the same quotes, §13.2). Each rule has its own toggle in Settings → Feed → Background, on by default; turning one off moves its items back at once. They apply to versions that arrive from now on; nothing already held is reclassified.

ReadingEntry.parts lists a thread's burst; a settings PATCH may name only the Background rules it changes. Private contract 5.11.0, SDK 0.17.0. Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 16, 2026

thread

Blygger Studio 0.60.1 to 0.61.0

2 releases of the reference client, newest first. Read each one's Migrations line before upgrading.

0.61.0: The Reading redesign: Shelf, Background, lenses in a new order

Released 2026-11-15. v0.61.0 on GitHub.

Lenses in a new order: All, Mentions, Smart Feed, Fragments, Threads, Shelf, Background (ROADMAP row 115).

The Shelf (#137, Aneesh Sathe; rows 114 and 115): a private, owner-ordered list of items, synced across clients through GET/PUT {mount}/api/shelf. An entry is { sub, remoteId }, named the way hopper membership names an item ("~own" for your own). A PUT replaces the whole list and must send expectedRevision; a stale one is a 409 revision-conflict carrying the current list. Entries that do not resolve (a withdrawn own item, an imported tombstone without its pin, an unknown subscription) are dropped quietly. The shelf never reaches an item document, a feed, the manifest or a public page, and never will. In the studio:

  • every reading entry has + add to shelf beside + add to hopper… (below 430 px both shorten to + shelf and + hopper…);
  • the Shelf lens lists shelved entries in your order, whatever their Background placement (GET /reading?shelf=true);
  • your own shelved items, drafts included, sit at the top of the compose list, with move up, move down and remove; each compose row and the editor's ⋯ menu add or remove one.

Background, phase 1 (row 112; plan in blygger-spec docs/background-plan.md): an entry is in Background by your choice on it, else on its blyg, else an enabled rule; withdrawn posts always are. An entry's ⋯ menu moves it to Background or Foreground, clears the choice, or moves its whole blyg; the source inspector has an in Background checkbox; in the Background lens the byline says why. Settings → Feed has a Background card: withdrawn always on, your own minor changes (typo, minor, refresh) on by default. PUT /reading/placement, background on PATCH /subscriptions/{id}, the backgroundRules setting.

A stub of an item this blyg does not hold (row 116) froze f/{id}/ as its citation, a 404 for every thread. It now names the item's document, as a mention does; publishing stays network-free.

The download backup includes the shelf and Background placements.

Private contract 5.10.0, SDK 0.16.0. Migrations: 0044 (the shelf) and 0046 (Background). Apply both before deploying: /changes selects every change domain by name, and the reading queries read the new columns. 0044 sorts before 0.58.0's 0045; wrangler applies migrations by name, so a node that has 0045 still applies 0044. Both were proven on a remote D1 (the CASE … END; splitter check) before release.

0.60.1: Discover offers only blygs you do not follow; tooltips

Released 2026-11-15. v0.60.1 on GitHub.

Discover's "new" view offered blygs you already follow (on a first visit, all of them): it filtered on the seen mark alone. It now lists only the blygs you do not follow, newest listing first, five at a time with show more until they run out; rows listed since your last visit carry a new badge. All is unchanged and still shows followed blygs. The sheet waits for your subscriptions to load, so a followed blyg never flashes into "new".

The setup walk-through ends with Discover: the finish screen offers discover blygs. It is not a step, because subscribing writes at once and the steps write nothing until the end.

Tooltips are one pattern. Every hover hint on a control (the reading page's icons, thumbs and ⋯ on entries, the composer and editor toolbars, copy + link, the update badge) is a styled tooltip that shows on hover and on keyboard focus, after a shared 300 ms delay, instead of the browser's slow title. Tooltip and IconButton in src/ui/primitives.tsx are taken from the design-system work in #88, with the same names and classes.

Contract and SDK unchanged. Migrations: none.

This announcement is drafted from the releases' sections of CHANGELOG.md, which is where they are maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 15, 2026

thread

Blygger Studio 0.60.0: Download a backup, discover blygs

Released 2026-11-14, the reference client. v0.60.0 on GitHub.

Download backup (ROADMAP row 15). More → download backup streams the whole blyg as one .tar from {studio}/backup: every database table as JSON lines under tables/, paged so no table is held in memory, every uploaded file under media/ by its storage key, a README.txt, and backup.json last, naming the client, the latest applied migration and the counts, with complete: true. A backup without backup.json did not finish. Plain tar, since media is already compressed. The owner's browser session only, never a delegated token. Left out: the OAuth and security tables (grants, tokens, signing keys, rate-limit budgets), wrangler's migration ledger and the feed cache. Restoring one into a fresh node is row 53 and not built.

The button is marked beta: it runs inside one Worker request, which caps storage reads, so on a blyg with very many files it can stop partway (and then has no backup.json). For those, npm run backup -- --base https://your.blyg/ [--env NAME] makes the same archive from a deployment checkout through wrangler, one request per table page and per file with retries, so the cap does not apply; a large blyg is only slower. It uses your wrangler login session and the deployment's wrangler config. npm run export is still the public site only, for moving to a static host, not a backup.

Tables are copied by allow-list. The auth library makes its own tables at runtime (session, jwks, oauthAccessToken, user and kin), outside migrations/; a deny-list missed them on a live node before release. A new test makes every migration's table either backed up or named as left out.

Discover (ROADMAP row 17). ✦ beside + on every reading screen opens the blygs listed on blygger.com, read from the browser through blygger.com's /blygs.json: new (listed since you last looked) or all, most active first, each with its activity level and last post, a preview ↗ link that opens the blyg in a new tab, and whether you already follow it. Subscribe one at a time or tick several; both go through the OPML import's paced walk with backfill: false, and stay out of the blogroll unless the box is ticked. Your own blyg is never offered. "New" is one timestamp, the newest listing date shown, in the new discoverSeenAt setting.

Private contract 5.9.0, SDK 0.15.0 (discoverSeenAt). Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 15, 2026

thread

Sealed Content and Payments: Two RFCs for Level 3

Everything a blyg publishes today is public. Anyone who can reach the origin gets the same bytes, and every item, quote and changelog note can be read by anyone. That is what made the first four protocol versions simple. It is also why a whole class of ordinary writing has nowhere to go: the board memo with one name that can't be shared yet, the working notes meant for a team, the essay you want to charge a dollar for.

Two new requests for comments open Level 3, the protocol's next layer. RFC-6, sealed content and permissions, lets an item carry encrypted words beside its readable ones, and says how a reader gets the key. RFC-7, payments, treats paying as one more reason to hand over a key. They come out together because RFC-7 is built entirely from RFC-6's parts. Both are drafts, and both are open for your comments. This post explains them in plain language.

The use case: sharing inside an organisation, with no assumed structure

The first user is the Protocol Institute, a decentralised organisation with no single sign-on. Some of what its members write should reach everyone, some only a working group, and some only one officer. A traditional company with one central set of permission groups has to fit the same design, and so does a reader at another organisation, using a different client, asking to see something.

One case shaped the design more than any other: redaction. Picture a sentence that should be public, except for one phrase inside it that only the board may read.

Covers: what older readers see

Here is what that sentence looks like on the wire:

There is an acquisition offer from the acquirer. The board meets on Friday.

"The acquirer" is a cover: ordinary words the author wrote to stand in for the sealed ones. The real name is encrypted and sits in a new sealed list in the item document. A reader that holds the key swaps the cover for the real text. Every other reader shows the cover.

This brings no new markup and no placeholder syntax. A cover is ordinary prose, so every client that exists today keeps working: it shows a sensible sentence, the feed entry reads normally, and a reader that has never heard of Level 3 sees nothing broken. The same mechanism works at three sizes: a phrase inside a sentence, a whole item behind a teaser, and a sealed item quoted into a thread.

Locks, not lists of readers

The obvious design is to list every reader in the document, each with a copy of the key encrypted to them. RFC-6 rejects it, because that list would be public. Everyone could see how many people can read an item and watch the number change over time. The protocol has always refused follower lists, and an audience list is one under another name.

Instead, a document names locks. A lock is a random id standing for a key. Holding the lock's key means you're in the group, and the group's membership is never written down anywhere public. One entry can carry several locks (any one of them opens it), and sealed content can sit inside other sealed content, so a reader has to hold both keys.

Grants as files at secret addresses

How does a reader get a lock key? Each lock has a home: a URL that answers requests for keys. A key granted to you is wrapped to your public key and saved as a plain static file at an address only you and the home can work out. To check whether you've been let in, you fetch that address. Nobody else can tell which addresses exist or for whom.

So a home can pre-approve people without ever contacting them. It writes the file, and the reader finds it on the next check.

When a request has to be decided, the home works through what RFC-6 calls a ladder: pre-approved, automatic yes, automatic no, or ask a person. That person can be the lock's owner or the owner's AI delegate, working from standing instructions. How a home decides is entirely its own business. It might use a roster, a sign-on token, a signed NDA or a payment.

One rule protects member lists. Anyone can put a stranger's address in a request, so a home tells a reader where it stands only when the request proves it comes from that reader. The proof uses a secret that only the home and the reader can work out, and it convinces nobody else. A request without it gets the answer anyone would get, so nobody can learn from a home whether someone else is a member.

A promise the publisher can't quietly break

Two smaller pieces of cryptography do a lot of work here.

A publisher can't show two readers two different texts. Each sealed entry carries a public commitment that every key holder checks. Without it, a dishonest publisher could craft one encrypted message that opens to two different texts under two different keys, and give each reader a different one.

Nobody can confirm a guess. An earlier sketch put a hash of the sealed text in public view. Anyone who suspected the redacted name was "Northwind Capital" could have hashed that guess and compared. The draft drops it.

Quoting doesn't widen the audience

Quoting is at the heart of Blygger, so quoting sealed content had to work. When you quote an item that has a sealed span, your thread carries a copy of the encrypted entry, not the plaintext. Readers who hold the key see through the redaction in your thread too. Everyone else sees the cover. Quoting into a thread meant for a wider audience lets nobody new read the sealed words. In the RFC's phrase: audience travels with the lock, not with the context.

What it does not pretend to do

RFC-6 is plain about its limits. Revocation stops future grants and future content, and nothing more. Nothing recalls a key or a text someone already opened. A pinned version keeps its keys forever. And a stranger can still see that a sealed item exists, roughly how large it is, when it changed, and what it cites. The RFC lists every such leak so that you can judge whether it is acceptable for your use.

RFC-7: payment is one more way to earn a key

RFC-7 starts from one principle. Payment rests on competing schemes, as identity does, so the protocol holds as little opinion about it as it can. The draft adds nothing to the wire. A payment is one more piece of evidence a home can accept, alongside a sign-on token or a signed agreement. A paid-for lock is an ordinary lock.

The interesting choices:

  • Any payment method, unmodified. A lock's or entry's request URL answers HTTP 402, "Payment Required", in the payment method's own format. That covers x402 (on-chain payments), MPP (which also carries card payments, through Stripe among others), Lightning, or a checkout link for a person at a browser. The protocol names no preferred method. If one wins outright, nothing needs undoing.
  • No prices anywhere in the protocol's files. There is no price, currency or for-sale flag in any item or manifest. Changing a price is a change at the home, with no new version and no feed event. The cost: an agent has to ask the home about each sealed entry, and the home sees what it looked at.
  • Two doors. An entry's door sells that one piece. A lock's door sells everything sealed under it for the current period: a subscription. A key bought for version 3 still opens version 4 if the sealed text didn't change.
  • Rent or purchase is the seller's choice, made by which keys it hands out. Give subscribers the lock key for each paid period and they keep that period's content after they stop paying. Give them one key per item as they read it and access ends when payment does, which is rent as most people know it. The draft recommends neither, and says plainly that "purchase" is weaker than the word suggests unless the seller pins what was sold.
  • Agents are the expected buyers. The draft assumes the typical purchase is made by an agent working within a spending limit a person set ("anything by this author about biology, under a dollar"), not by a person at a checkout page. It writes rules for that agent: treat the seller's description as untrusted text that may try to steer you, never pay for what you already hold, and keep the receipt and the commitment as evidence of what was advertised against what was delivered.
  • Buying without a blyg. Pay at an ordinary storefront, then redeem the voucher into a pass: a bare key your reader app generates, which works without an account. The draft is plain that a pass is a bearer instrument, like a ticket.

What RFC-7 refuses: anything in the protocol that claims to restrict use after delivery, such as expiry dates, read counts or metering. Nothing could enforce it. Rental as a business is fine. Pretending cryptography can take back what a reader already opened is not.

Thirteen assumptions to attack

RFC-7 lists the thirteen assumptions it rests on, each with what would change if it is wrong. Agents buy more than people do. People set limits rather than approving each purchase. Small payments are economic on at least one payment method. Subscriptions matter as much as single purchases. Readers without a blyg are a real population. This is the part of the drafts where your experience is worth the most. If you think one of them is wrong, say which and what you see instead.

How to comment

Both RFCs are published on this blyg with a comment period open until 28 November 2026. They are published as drafted, before the protocol's editorial pass, so expect revisions during the period; each one is a new version of the same item. Comments use the medium itself:

  • Respond by stubbing the RFC from your own blyg. Your response names the exact version you read.
  • Quote the passage you're answering with a partial quote.
  • Counter-propose by forking the RFC and changing what you'd change.
  • No blyg? Comment on GitHub: blygger-spec#34 for RFC-6, blygger-spec#35 for RFC-7.

Each RFC ends with questions for implementers. Would you run a home, or use someone else's? Can your platform do AES-256-GCM, HKDF and X25519 today? Which payment methods would you accept? Is one request per sealed entry tolerable for your agents? Answers to those, from anyone building or planning a client, shape what gets built first.

When the period closes, the rulings are revised in light of what was said and each RFC becomes a technical note. The build then starts small: sealed spans with keys handed over by hand, which alone opens protocol version 0.5. Origin keys, homes and grant files, the request endpoint, and subscriptions follow, each usable without the next.

Source: docs/posts/2026-11-14-sealed-content-and-payments.md in blygger-spec, which is where revisions are made. To comment, respond to this item from your own blyg.

read the thread →

v2

“One paragraph revised to follow RFC-6's edit: a home tells a reader where it stands only when the request proves it is that reader's.”

Created: Nov 14, 2026 Most recent: Nov 15, 2026, v2

thread

RFC-7 — Payments: one more ground for a grant, any rail at the door

Request for comments · non-normative · OPEN FOR COMMENT until 2026-11-28 on blyg.blygger.org (#66); without a blyg, comment on blygger-spec#35 · session 68, 2026-11-12; published session 70, 2026-11-14, and edited by Fable 5.2 the same day (decision #106). Drafted by Opus 5.5 at Venkat Rao's request from docs/v0.5-plan.md §8 (the payments direction of decision #104) and research R1 (plans/l3/r1-payment-rails.md), with x402, MPP and the payment link relation re-checked against their primary sources the same day (section 13). Fable's edit changed little here: it follows RFC-6's two changes at the door (a request may prove it is the recipient's own, and a refusal is guarded as a grant is; sections 3 and 5), and the rest stands as the position the comment period argues with. The two RFCs publish together, because three of RFC-6's constructs exist for this RFC's sake and a commenter needs both. Like a technical note, an RFC constrains nothing. It proposes no wire construct: everything payments need on the wire is in RFC-6. It is a recommendation for how homes and readers do payments, and when its comment period closes it becomes a technical note (#90). Written against protocol 0.4 at its fifteenth revision; no pre-1.0 version promises anything (#21).

Every choice this draft makes that the plan did not is marked Proposal (Opus). This RFC names no preferred rail.

Summary

  • Payment supervenes on permission. A payment is one more ground on which a lock's home grants a key (RFC-6). A paid-up lock is an ordinary lock. On the wire there is one dimension: keys.
  • Every rail yields a proof, never a key (R1), so a home is always in the path. The protocol names no rail, and any rail rides unmodified.
  • The door. A lock's or an entry's request URL answers 402 in the rail's own format: x402's PAYMENT-REQUIRED, MPP's WWW-Authenticate: Payment, both, or others. Hold, then probe, then ask; an agent never pays for what it holds.
  • Two doors per entry. The entry's door sells one entry's content. The lock's door sells the class for the current epoch: a subscription.
  • No price, currency, rail or for-sale flag in any protocol document. A price change is a change at the home: no version, no feed event. The cost is that an agent asks the home once per sealed entry and the home sees what it looked at.
  • Rent or purchase is the home's choice, by which keys it hands out: epoch lock keys (the subscriber keeps what was sealed in paid epochs) or entry keys on demand (the home stops answering on lapse). The wire does not choose, and this RFC recommends neither.
  • Buying without an origin: pay at a storefront, redeem a voucher into a pass.
  • Refused: any construct on the wire that claims to restrict use after delivery (expiry, read counts, metering). Rental as a business model is not refused.

1. The principle

Venkat's, from session 67 (#104): payment rests on competing schemes, as identity does, so the protocol holds as little opinion as it can and lets any rail and any verification scheme ride it. Base cases are card payments, x402 and MPP. Older patterns such as NFT gating are not to be blocked and are not the target. Future bearer tokens may change that.

The protocol already took this position on identity: identity is never in the protocol (#11), and the only authenticated entity is the origin. Payment gets the same treatment. The home that holds a lock key decides who gets it, and a payment is evidence, as a sign-on token or a signed acceptance of terms is evidence.

2. Assumptions

The design rests on these. Each is an assumption about demand or about the world, not a finding, and each is open to attack: if you think one is wrong, say so, and say what you see instead. The consequence named is what to revisit if it is wrong.

  1. Agent-first. The typical buyer is an agent with delegated spending authority, buying fast and often under a standing instruction ("buy anything by this author that is about biology and under a dollar"). A person at a checkout page is the minority path. If wrong: the door's one-exchange shape is over-built, and the storefront and deep-link paths (section 6) deserve the design effort.
  2. People set policy, not purchases. People mostly set spending limits and broad preferences; they do not approve individual purchases. If wrong: a confirm step belongs in clients, still off the wire.
  3. The buyer's side holds the means. An origin or a reader service keeps a card on file, a wallet with a cap, or a scoped payment token, with limits. None of it is on the wire. If wrong: nothing in the protocol changes; clients do.
  4. Rails compete and will keep changing, as identity schemes do. x402 and MPP are both under two years old and neither is a standard (section 13). So the protocol names no rail and any rail must ride unmodified. If one rail wins outright: nothing needs undoing, which is the point.
  5. Base cases: cards, x402, MPP. These must work well. NFT and token gating must not be blocked and is not designed for. If bearer tokens on chains become the main pattern: the pass is the hook, and its rules (RFC-6 item 20) are what to revisit.
  6. Every rail yields a proof, never a key (R1), so a home is always in the path. If a rail appears that releases keys itself (threshold networks are the nearest): a home is a URL, and such a network can stand behind one.
  7. Small payments are economic on at least one rail. Per-entry buying under a dollar assumes stablecoin or session-style settlement; cards have a floor near fifty cents (Stripe's MPP card minimum is 0.50 USD, R1 §2). If not: subscriptions and bundles carry the load, which the lock already is.
  8. Subscriptions are a main relation, not an afterthought: standing access to a class of content for a renewing period.
  9. Readers without an origin are a real population, and will mostly buy at a storefront and redeem. RFC-6 asks implementers whether this population is real (its section 10, question 1); this RFC depends on the answer. If not: the pass and the voucher path can wait.
  10. Descriptions are the seller's own and may be adversarial. about, covers and terms are written by the party being paid, and will be read by agents. If sellers turn out to be honest: nothing is lost by treating their text as data.
  11. Law enforces terms; the protocol cites them. No mechanism restricts use after delivery, and none will. If sellers need enforcement: it is not available without per-reader serving or a trusted runtime (section 10), and this RFC says so instead of pretending.
  12. Per-entry probing is tolerable: an agent asking a home once per sealed entry, and the home seeing what was looked at, is an acceptable cost of keeping prices off the wire. If not: a static offer list at the home, in its rail's format, is the first remedy; a price on the wire is the last.
  13. Buyers expect rent. Today's subscriber assumes access lapses when payment stops. The design delivers that by cooperation and by which keys are handed out, never by cryptography against a reader who already holds a key (section 5). If buyers or sellers need more than that: it is not available without per-reader serving or a trusted runtime, and this RFC says so.

3. The door

The request URL of RFC-6 section 3.11 answers 402 in the rail's own format. Nothing is added to it: no Blygger header, no Blygger price format, no Blygger payment object.

  1. Hold, then probe, then ask. A reader that holds a key uses it (RFC-6 section 4 step 1). One that does not checks its grant path (step 2). Only then does it ask. An agent never pays for what it already holds, and a reader whose subscription already covers an entry finds its grant before it meets a price.
  2. Probe. A GET of the request URL with no body names no recipient, so its answer cannot depend on who asks. It returns the offer: x402's PAYMENT-REQUIRED, MPP's WWW-Authenticate: Payment, both, or other schemes. The same offer for everyone, and not cacheable: MPP requires Cache-Control: no-store on every 402 and issues a fresh challenge id each time; x402 says to keep the 402 out of shared caches (section 13). This corrects the plan (§8.2 step 2 and its §12.2 example, which said "cacheable" and showed max-age=3600).
  3. Pay. The buyer POSTs the request (RFC-6 section 3.11) naming its recipient, an origin or a pass, with the rail's credential. The answer carries the key wrapped to the recipient and the rail's receipt, and the home writes the grant file, so the key can be fetched again without paying again. A paid request needs no proof of the recipient (RFC-6 section 3.11): the grant follows from the payment, and it is wrapped to the recipient named, so paying for someone else's key is a gift and nothing worse.
  4. A person at a browser. The 402 carries Link: <…>; rel="payment" to a checkout page bound to the request. The person pays there, and the reader polls its grant path as for any pending request.

Two doors per entry. The per-entry URL ({home}e/{commit}) sells one entry's content. Because RFC-6 carries an unchanged entry byte for byte into the next version, a key bought at version 3 opens version 4 if the sealed text did not change. The per-lock URL ({home}l/{lock}) sells the lock key for the current epoch: everything sealed under that lock in that epoch, a subscription period. The agent chooses by its instruction, from author, about or the cover, the terms, and the offer.

The rail's own description fields. x402's PaymentRequired.resource.description and MPP's description parameter are display text the home writes; MPP says its parameter "MUST NOT be relied upon for payment verification". Proposal (Opus): a home SHOULD make them agree with the entry's about (or cover), since about is the description the commitment binds (RFC-6 section 3.4) and the rail's field is not.

Binding the payment to the recipient. A payment that is not bound to the request's recipient could be replayed to name a different one. MPP lets a challenge bind the request body with its digest parameter (RFC 9530), which the draft says servers SHOULD include for requests with a body; x402's payment payload echoes the resource. Proposal (Opus): a home binds each challenge to the recipient it will wrap to, by whatever binding its rail offers, and refuses a credential presented with a different recipient.

No price on the wire. A price change is a change at the home: no version, no feed event, no document touched. The plan's guidance stands: a home may serve a static price list in its rail's format, and neither this RFC nor RFC-6 specifies one.

4. Worked exchanges

One sealed item, one entry, one lock, homed at https://keys.example.org/. The entry's commitment is abbreviated c9Xq…; the lock id k7f3…. Header values are abbreviated. These are illustrations of each rail riding RFC-6's request URL unmodified; the rails' own specifications govern every header shown.

4.1 An agent paying with x402

GET  https://keys.example.org/e/c9Xq…                  probe: no body, no recipient

402  Payment Required
     Cache-Control: no-store
     PAYMENT-REQUIRED: <base64 PaymentRequired: x402Version 2, resource { url, description },
                        accepts [ { scheme "exact", network "eip155:8453", amount, asset, payTo } ]>

POST https://keys.example.org/e/c9Xq…                   inside the agent's spending limit
     PAYMENT-SIGNATURE: <base64 PaymentPayload: the signed transfer authorization>
     Content-Type: application/json
     { "recipient": { "origin": "https://blyg.reader.example/" } }

200  OK
     PAYMENT-RESPONSE: <base64 SettlementResponse: success, transaction, network, payer>
     { "key": "<entry key, HPKE-sealed to the origin's encryption_key>" }

The agent's origin unwraps with its own private key, checks the commitment, and reads. The home has also written the grant file at the path only it and that origin can compute, so the agent's origin can fetch the key again later with a GET.

4.2 An agent paying with MPP

POST https://keys.example.org/e/c9Xq…
     { "recipient": { "pass": "<buyer's X25519 public key>" } }

402  Payment Required
     Cache-Control: no-store
     WWW-Authenticate: Payment id="…", realm="keys.example.org", method="tempo",
         intent="charge", request="<base64url JCS JSON>", expires="…",
         digest="sha-256=:…:", description="Full write-up, 4,200 words …"

POST https://keys.example.org/e/c9Xq…                   body unchanged, so the digest matches
     Authorization: Payment <credential echoing the challenge>
     { "recipient": { "pass": "<buyer's X25519 public key>" } }

200  OK
     Cache-Control: private
     Payment-Receipt: <base64url JSON: status "success", method, timestamp, reference>
     { "key": "<entry key, HPKE-sealed to the pass>" }

Here the buyer used a pass, so the agent needs no origin of its own. If the home also needs Authorization for a sign-on token, MPP's header="Payment-Authorization" parameter moves the payment credential to its own field (draft §5.1.2).

4.3 A person paying by card through a checkout link

POST https://keys.example.org/l/k7f3…                   a subscription: the lock's door
     { "recipient": { "pass": "<reader app's pass key>" } }

402  Payment Required
     Cache-Control: no-store
     WWW-Authenticate: Payment id="…", method="stripe", intent="charge", request="…"
     Link: <https://pay.example.org/c/abc123>; rel="payment"

     … the reader app opens the checkout link; the person pays by card …

GET  https://keys.example.org/g/<path from the home key and the pass>
200  { "for": { "lock": "k7f3…", "epoch": 12 }, "key": "<lock key, sealed to the pass>",
       "terms": { "origin": "…", "id": "…", "version": 2 }, "at": "…" }

The checkout page is bound to the request (the home put the request's recipient into the checkout session), so payment lands at that pass and nowhere else. The same 402 can carry an MPP challenge for agents and the rel="payment" link for people.

About rel="payment". It is registered in the IANA Link Relations registry, described as "a resource where payment is accepted", and the registration says it "is not intended to initiate an automated transaction" (section 13). That is the right relation for a person's checkout link and the wrong one for an agent, which uses the challenge.

5. Subscriptions, rent and purchase

A subscription is standing access to a lock (RFC-6 section 3.12). Renewal has no construct: it is obtaining the next epoch's key, or continuing to be answered. A home that charges automatically writes the next epoch's grant ahead of time and the client finds it by probing; otherwise the agent meets a 402 at the lock's door and pays.

Rent is the expected default, and the wire does not choose between rent and purchase (assumption 13; #104, revised the same session on Venkat's question). The home chooses by which keys it hands out:

Mode The subscriber is given On lapse Cost
Holding The lock key for each paid epoch Keeps everything sealed in those epochs, opened or not None at read time: no traffic, nothing logged
On demand No lock key. One entry key per item as it is opened, free under the subscription (the ladder's rule is "has a live subscription") The home stops answering. The reader holds only keys for what it opened The home sees every first read, and must be reachable for it

On demand is rent as buyers know it: a lapsed subscriber of an incumbent service loses the archive and keeps the emails already received. It uses entry-key grants and nothing new. Each request carries the proof of RFC-6 section 3.11: "has a live subscription" is a fact about who the recipient is, which a home says live only to a request proven to be that recipient's. Without the proof the reader is told "pending" and fetches its grant path, one round trip more. The trade-off is a reading log at the home against a real lapse. This RFC recommends neither. A home may mix them, for example epoch keys for the current period and on demand for the archive.

Lapse as a retention event (RFC-6 section 5, item 15). A conforming reader that finds a lapse notice at its grant path drops the key and its decrypted copies, as it drops withdrawn content (§13.4). This is cooperation, stated as such. It is what makes "rental" in a terms document mean something among conforming clients. With it, rent is three things together: the home stops issuing, conforming readers drop, and the terms say so in law. A holding-mode home that means subscribers to keep past epochs writes no lapse notice for them.

Purchase is weaker than the word suggests, and sellers should know it:

  • An entry key opens one entry's content. A change to the sealed text is a new key. Whether earlier buyers are granted it is the home's policy; this RFC recommends that corrections be free (grant the new entry key to everyone who bought the old one).
  • Superseded versions stop being served unless pinned (§8.4). There is no pinning guarantee.
  • Withdrawal reaches paid content: a conforming reader drops an unpinned withdrawn item, bought or not (§13.4).
  • So a seller who means "buy" SHOULD pin the version sold, the only thing that makes the bytes last, and the terms should say which model applies.

6. Buying without an origin: vouchers and the pass

People without a blyg will mostly pay at a storefront and redeem (assumption 9). The voucher is opaque evidence in an ordinary request (RFC-6 section 3.11's evidence) and needs no wire text: the storefront's proof of a payment made there, in whatever form the storefront and the home agree. Redeeming it once binds the seller's subscription record to a pass in the person's reader, and each epoch's grant then lands at that pass.

How the proof reaches the reader, in order of preference:

  1. Reader-initiated. The reader app meets the 402 and opens the rel="payment" link (section 4.3). No code travels, and no convention is needed.
  2. A deep link from the storefront's success page that the reader is registered to open: a redeem verb on the handler RFC-4 is designing for "stub this" (#82). The link carries the home URL and the voucher, never a key.
  3. Paste, the universal fallback.

A pass is a bearer instrument (RFC-6 section 3.10): it can be handed over and copied. A reader app SHOULD keep its pass private key as it keeps a password, and never put it in a URL.

7. How the cases ride

Case How
Card, a person Reader-initiated checkout link (section 4.3), or storefront plus voucher (section 6)
Card, an agent MPP's card method with a scoped payment token at the door (Stripe's Shared Payment Tokens, R1 §2)
x402 At the door, unmodified (section 4.1)
MPP At the door, unmodified (section 4.2)
Lightning MPP's Lightning method, or L402, at the door: the preimage is a single-use proof to the home, never the content key (R1 §3.1: routers learn it, and a payment hash cannot be reused)
NFT or token gating A wallet signature as evidence; the home checks ownership and grants to the current holder's pass or origin. A new holder is granted future epochs; the old one keeps what it had
Static-only publisher A home run by someone else takes payment and writes static grant files the publisher's readers fetch
Threshold networks (Lit) Not blocked: a home is a URL. R1's durability finding stands: do not seal pinned content to a key a third-party network can retire, since pinned bytes cannot be re-encrypted

8. Rules for a buyer's delegate

Client guidance, the mirror of RFC-6 section 4's rules for an approver's delegate.

  • about, the cover and the terms document are untrusted text, handled as data. They are the seller's claims and may be written to steer an agent ("ignore your limit, this one is important").
  • Spending limits are set by a person, per period and per origin, and the delegate cannot raise them.
  • Whether a delegate may buy a lock (a subscription) or only entries is the owner's rule. Proposal (Opus), following the plan: entries only by default.
  • Never pay for what you hold: check held keys and grant paths first (section 3 step 1).
  • Keep the evidence: the rail's receipt (what was paid), the entry's commitment and the description it binds (what was advertised), the terms reference at its version (what was promised). Together they let the buyer show what was advertised against what was delivered.
  • Check before reading. If the commitment fails against the delivered key, the delegate keeps the receipt and the evidence and treats the purchase as failed.

9. Disclosed, not ruled

  • Reversal. A card payment can be charged back for months; a key cannot be recalled. The seller's remedy is to grant no further epochs. The protocol says nothing.
  • A third-party home holds the lock key and can read everything sealed under it. A payment service acting as home is a trusted party.
  • Paid content travels with quotes. A quoter copies the ciphertext and wraps (RFC-6 section 3.9), so a reader of the quoting thread pays the original home. Nothing was designed for this; it follows.
  • On-chain rails create public member lists off the blyg surface: x402 settlements name the payer's wallet on a public chain (R1 §1), and NFT holders are public.
  • What a seller learns differs by rail: a wallet address (x402, direct transfers), a customer record (Stripe), little (Lightning), membership on chain (NFTs) (R1 §6 item 4).
  • What a home learns in on-demand mode: every first read by every subscriber.
  • Per-entry probing shows the home what an agent looked at and did not buy (assumption 12).

10. Refused

Any construct on the wire that claims to restrict use after delivery: an expiry time on a key or an entry, a read count, metering. Nothing would enforce it, and it would be opinion about business models.

Rental as a business model is not refused (narrowed in session 67, #104). It is delivered by which keys a home hands out, by the cooperative retention rule, and by terms (section 5). What stays impossible, and is not offered, is locking a non-cooperating reader out of content it has already opened. That would take per-reader serving of ciphertext (refused by #93 as C2), re-encrypting the back catalogue every period (a new version of every item, against pins and the feed), or a trusted client runtime.

Also not on the wire, ever: a price, a currency, a rail, a for-sale flag, a preferred rail. Batching and sessions inside a rail are the rail's business.

11. Questions for implementers

  1. Rails. Which would you run at a home: cards, x402, MPP, Lightning, something else? Would you offer more than one in the same 402?
  2. Probing. Is one request per sealed entry tolerable for your agents? If not, what would you want first: a static offer list at the home, bundles, something else?
  3. A home as a service. If you publish from static files, would you use a home run by someone else? What would you need to trust it with your lock keys?
  4. about. What does an agent need in it to decide? Is 300 characters enough? Should anything in it be structured (the plan says no)?
  5. Rent or purchase. Which mode would your subscribers expect, and would you mix them?
  6. Readers without an origin. Would your readers redeem a voucher into a pass, or do they all have origins?
  7. Agents. Would you let an agent buy subscriptions, or only entries?
  8. Assumptions. Which of section 2's thirteen is wrong for you?

12. Relation to other documents

  • RFC-6: every construct this RFC uses. The request endpoint and challenges (RFC-6 section 3.11), the pass (3.10), epochs (3.12), about and the commitment (3.1, 3.4), terms (3.13), lapse (5).
  • docs/v0.5-plan.md §8: the direction. Where this RFC differs (the 402 is not cacheable, section 3), it says so.
  • plans/l3/r1-payment-rails.md: the rails fact sheet.
  • RFC-4 (responding from anywhere, unwritten): its handler gains the redeem verb of section 6.

13. Sources, re-checked 2026-11-12

Both rails' specifications move, so each claim above was re-checked on the day of this draft.

  • x402. github.com/x402-foundation/x402 at commit 07c4caf (2026-11-12). specs/x402-specification-v2.md: "Protocol Version: 2"; version history v0.1 2025-08-29, v0.2 2025-10-03, v2.0 2025-12-09. specs/transports-v2/http.md: the three headers are PAYMENT-REQUIRED (server to client, base64 PaymentRequired), PAYMENT-SIGNATURE (client to server, base64 PaymentPayload) and PAYMENT-RESPONSE (server to client, base64 SettlementResponse); v1's X-PAYMENT and X-PAYMENT-RESPONSE are still named for dual-version servers. Under "Browser clients", a resource server reachable from a browser SHOULD expose and allow these headers by name in CORS, answer the preflight without payment, and "keep the 402 out of shared caches". PaymentRequired.resource carries an optional description. Schemes in specs/schemes/: exact, upto, batch-settlement, auth-capture.
  • MPP. draft-httpauth-payment-01, "The 'Payment' HTTP Authentication Scheme", by B. Ryan, J. Moxey, T. Meagher (Tempo Labs), J. Weinstein, S. Kaliski (Stripe), dated 9 September 2026, active until 13 March 2027, an individual submission with no stream (IETF Datatracker API, read 2026-11-12). Its earlier name, draft-ryan-httpauth-payment-01, expired 2026-09-19 (R1's header carries the same correction). From the text: 402 with WWW-Authenticate: Payment carrying REQUIRED id, realm, method, intent, request and OPTIONAL digest, expires, description, header, opaque (§5.1); credentials in Authorization: Payment, or in Payment-Authorization when the challenge's header parameter selects it (§5.1.2); Payment-Receipt on success with status, method, timestamp, reference (§5.3); "Servers MUST send Cache-Control: no-store with 402 responses" and receipts carry Cache-Control: private (§11.10); challenge ids bound to the challenge parameters (§5.1.2.1). Clients MAY declare supported methods with an Accept-Payment header (§7.4).
  • rel="payment". IANA Link Relations registry (CSV, last modified 2026-10-13, read 2026-11-12): payment, "Indicates a resource where payment is accepted", reference RFC 8288; the registration note says it "makes no assumptions on the type of payment or transaction protocol" and "is not intended to initiate an automated transaction". Fable cited it from memory in session 67; it is confirmed.
  • Card minimums, facilitator fees and Lightning facts are R1's, read the same day.

Source: docs/rfcs/rfc-7-payments.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

v2 · pinned: v1, v2

“RFC-7 edited by Fable (decision #106), following RFC-6's changes at the door.”

Created: Nov 14, 2026 Most recent: Nov 15, 2026, v2

thread

RFC-6 — Sealed content and permissions: covers on the wire, keys by lock, grants as files

Request for comments · non-normative · OPEN FOR COMMENT until 2026-11-28 on blyg.blygger.org (#66); without a blyg, comment on blygger-spec#34 · session 68, 2026-11-12; published session 70, 2026-11-14. Drafted by Opus 5.5 at Venkat Rao's request from docs/v0.5-plan.md (the design direction of decisions #101 and #104) and the Level 3 research in plans/l3/ (R1–R7). Published together with RFC-7, which depends on it (#104), as Opus's draft on Venkat's word, and edited by Fable 5.2 the same day (session 70, decision #106): section 9 opens with what that edit ruled, what it changed and what stays open for the comment period. Like a technical note, an RFC constrains nothing. When its comment period closes it becomes a technical note (#90), and its constructs feed the 0.5 document once they are built and exercised (#21, #43). Written against protocol 0.4 at its fifteenth revision; no pre-1.0 version promises anything (#21).

How to read the proposals. The plan fixed the direction; it left names, shapes and twenty-four questions open. Every choice this draft makes that the plan did not is marked Proposal (Opus); a change made at the edit is marked Fable, at the edit. Section 9 lists the items, each with its options, the proposal and a test that would show the proposal right or wrong, under a table of where each stands after the edit. Where the draft departs from the plan, it says so and why (section 9 items 12, 23 and 24, and section 11).

Summary

Level 3 begins with one mechanism: sealed content. An item document may carry encrypted content beside the readable text, and a reader holding the right key reads it.

  • Covers on the wire, no new markup. content_md carries only what a reader without a key reads: clear text and the author's own covers ("the acquirer", "restricted", a teaser). The sealed words live in an OPTIONAL sealed list on the item document. content_html wraps each cover in a new permanent class, blyg-sealed. A Level 2 reader ignores the list and shows the covers, so every sealed item is a valid 0.4 document and a valid feed entry. content_hash stays the hash of what a keyless reader reads.
  • One mechanism, three sizes. A sealed span (a phrase or a block inside any item), a sealed item (one span covering the whole body), and a sealed item quoted with the existing ![[id]] directive. Entries nest (AND) and carry several wraps (OR).
  • Keys by lock. A lock is an opaque id naming a key. Holding the lock key is standing membership. An entry's key is wrapped under one or more lock keys, so the document names locks, never readers. No list of readers, of any size, is on the wire.
  • Grants as static files. A grant wraps a lock key or one entry key to a recipient (an origin's published key, another lock, or a reader's bare pass key) and sits at a path only the granter and the recipient can compute. A reader probes with a GET.
  • A home answers requests. A lock's home is a URL that answers requests for keys: granted, pending or refused. How it decides (a roster, a sign-on token, a person, a person's AI delegate, a payment) is private. The home is the protocol's second dynamic surface, OPTIONAL like the Webmention receiver.
  • Identity is the origin's. An origin MAY publish one encryption-only public key in its manifest. Never a key per author, never a signing key.
  • Terms are a citation. A reference to a stable document, in stub_of's two shapes, may sit on a wrap, a grant, an item or the manifest. It is never enforcement and has no rights vocabulary.
  • Honest limits. Revocation stops future grants and future content; nothing recalls what a reader already opened; a pinned sealed version keeps its wraps forever. A sealed item's existence, size class, timing, version count and citations are public.

Proposals of this draft that the plan did not make (section 9 has each in full): AES-256-GCM, HKDF-SHA-256 and HPKE over X25519 as the one suite; a key commitment that replaces the plan's clear sealed_hash, which would have let anyone confirm a guess at the sealed text; an unchanged entry carried byte for byte into the next version, so that "maintenance" stays computable and an entry key is per content, not per version; a text selector on each span for markdown-rendering clients; a small home document carrying the home's public key, from which grant paths are derived without contact; a home that answers about a recipient only to a request proven to come from that recipient (the edit's change, section 3.11); and a correction to the plan from the rails themselves: a 402 must not be cached (MPP requires Cache-Control: no-store), so "the same first answer for everyone" means the same in substance, not cacheable bytes.

1. The question and the use case

Venkat opened Level 3 in session 64 (#99): privacy, encryption and paid access, as protocol version 0.5. The session-66 round chose the first feature (#101): encrypted content on the wire as static files, and permission to read it granted by rule, by a person, or by a person's delegate. Payment is one more ground for a grant and is RFC-7.

The use case (plan §1): ordinary information sharing inside an organisation, with no assumed structure. Anybody can publish to the eligible population or any segment of it, and decide for each segment who is pre-approved, who is approved or refused automatically, and what goes to a person as an exception.

  • The first user is the Protocol Institute, a decentralised organisation without single sign-on. Sign-on may be used where it exists and must never be required.
  • A traditional organisation (one shared set of permission groups) and a decentralised one (every node keeps its own) must both fit, without the protocol knowing which it is looking at.
  • Across organisations and clients. Requesting access from another organisation, using another client, is in scope.
  • Redaction is a main case: a phrase inside a sentence, sealed to a narrower group than the sentence around it.

What the existing text already rules out, and this RFC keeps (RFC-5 section 10, #93): per-reader bytes within one origin under any gate (C2, refused); split-horizon origins. What it keeps open as client territory: a redacted wire with a fuller rendition off the mount (C1). This RFC is the shape #93 named as where the Level 3 round starts: C3, encrypted static content.

2. Vocabulary

Term Meaning
Sealed entry One piece of encrypted content in an item document: ciphertext, the wraps that open it, and a commitment.
Cover The readable text standing where sealed content is, written by the author. Ordinary published content: hashed, quotable, in the feed.
Entry key The random key that decrypts one entry. Fresh whenever the sealed content changes.
Lock An opaque random id naming a lock key. Holding the lock key is standing membership: it unwraps every entry key wrapped under it. The member list is never on the wire.
Epoch One generation of a lock's key. The lock id is stable; each epoch has its own key.
Wrap An entry key encrypted under one lock's key at one epoch, with the lock's home.
Home The URL where a lock's keys are asked for. Not necessarily on the publishing origin.
Home document Proposal (Opus). A small JSON file at the home URL: the home's public key and where its grant files and request URLs are.
Grant A key (a lock key at an epoch, or one entry key) wrapped to one recipient, served as a static file.
Recipient An origin (its manifest key), another lock (that lock's key), or a pass.
Pass A bare public key a reader's client generates, used as a recipient by a reader with no origin. A bearer instrument.
Ladder The home's private rules for deciding a request: pre-approved, automatic yes, automatic no, or ask a person or their delegate.
About Optional plain text on an entry saying what is sealed. The seller's or author's own claim. Not the cover.
Commitment A digest in the clear that binds an entry's key, ciphertext and description, so that one entry cannot show two readers two texts.
Terms A reference to a stable document stating the terms under which a key is held or content is offered. A citation, never enforcement.

Two grant sizes matter throughout: a lock key (standing membership, for an epoch) and one entry key (a single exception).

3. The design on the wire

Field names are proposals unless the plan named them; the plan's own names (sealed, about, blyg-sealed, terms) are kept. All of section 3 is new wire and therefore Fable's to rule.

3.1 The sealed member, covers and the class

An item document gains one OPTIONAL top-level member, sealed, a list of entries.

{
  "blyg": "0.5",
  "id": "5q1k8w3zc7n0d2v9h6m4r8t2xa",
  "kind": "thread",
  "version": 4,
  "origin": "https://blyg.protocol-institute.org/",
  "content_md": "There is an acquisition offer from the acquirer. The board meets on Friday.",
  "content_html": "<p>There is an acquisition offer from <span class=\"blyg-sealed\" data-blyg-entry=\"e1\">the acquirer</span>. The board meets on Friday.</p>",
  "content_hash": "sha256:…",          // over content_md: what a keyless reader reads
  "sealed": [
    { "entry": "e1",
      "selector": { "exact": "the acquirer", "prefix": "offer from ", "suffix": ". The board" },
      "wraps": [
        { "lock": "k7f3m0q9…", "epoch": 2, "home": "https://keys.protocol-institute.org/",
          "key": "<entry key wrapped under lock k7f3 epoch 2>" }
      ],
      "commit": "<base64url SHA-256 commitment, §3.4>",
      "nonce": "<12 bytes, base64url>",
      "ct": "<AES-256-GCM ciphertext of the padded plaintext, base64url>" }
  ]
}
  • content_md carries only covers and clear text. No new markup, no marker, no placeholder syntax: a cover is ordinary prose. This is the two-plane pattern of generation provenance (#20, §5.7): marker-free source, a list in the item document, a baked class in content_html.
  • content_html wraps each cover in <span class="blyg-sealed" data-blyg-entry="…"> (inline) or <div class="blyg-sealed" data-blyg-entry="…"> (block). blyg-sealed is a permanent wire token, like blyg-transclusion and blyg-tk-gen. A reader holding the key replaces the element's contents with the decrypted content; every other reader shows the cover.
  • content_hash is unchanged in meaning: SHA-256 of content_md, which is what a keyless reader reads. #20's "the hash covers exactly what readers read" holds for that reader. Section 3.4 gives the key holder its own integrity.
  • The authoring mark for a sealed span is studio-private, as the generation grammar is (#20), and never reaches the wire.
  • A sealed item is the case where one entry covers the whole body: content_html is one blyg-sealed block whose contents are the cover, and content_md is the cover. There is no new kind (#100 keeps the kind fixed, and a new kind would make every Level 2 reader ignore the item rather than show its cover, R4 §2.2).
  • selector (Proposal (Opus); plan §9 item 5). A span's entry carries the §10.3 text-quote selector of its cover, so a client that renders from content_md can find the cover without parsing content_html. REQUIRED on a span, absent on a whole-item seal. The selector names cover text, which is public, so it leaks nothing.
  • about (the plan's shape; plan §3.1, §9 item 18). An entry MAY carry plain text describing what is sealed, for a person or an agent deciding whether to ask or to buy. Free text only: no tags, categories, prices or structured fields. Plain like a label (#102), escaped by any renderer. Proposal (Opus): a cap of 300 code points (§5.3's unit, #103). Self-asserted and unverifiable before the key is held. It is never the item's title (#46): a reader MUST NOT present it as one or as anything but the publisher's description. One rule for a reader or an agent: about if present, else the cover. For a fully sealed item the cover is usually the natural abstract and about is absent; an author may use both, a teaser as cover and a factual description in about.

3.2 The plaintext is a content object

Proposal (Opus). An entry's plaintext, after decryption and unpadding, is a JSON object with the same content members an item has, scoped to the span:

{ "content_md": "Northwind Capital",          // the sealed words, markdown
  "content_html": "Northwind Capital",        // self-contained, absolute URLs (§5.2, #53)
  "media": [ … ],                             // OPTIONAL: media only the sealed words use
  "generated": [ … ],                         // OPTIONAL: provenance of generated words inside
  "sealed": [ … ] }                           // OPTIONAL: nested entries (§3.5)

A reader holding the key substitutes content_html for the cover's contents, or content_md for the cover in a markdown rendering. A block span's plaintext is block content; an inline span's is inline. Why an object and not bare text: sealed words carry their own media, their own generation provenance and their own nested entries, and those must be inside the ciphertext or they leak (R4 §2.2, media[] and generated[] rows).

3.3 Algorithms

Proposal (Opus); plan §9 item 3. One suite, no negotiation, an alg member reserved so a second suite can be added later (section 9 item 16):

Use Primitive Why
Entry encryption AES-256-GCM, 96-bit random nonce, 128-bit tag The only AEAD in stable WebCrypto (R2 §1.1); in Go's stdlib and Python's cryptography
Wrap under a lock key AES-256-GCM, its own random nonce, over the 32-byte entry key One AEAD for everything; a wrap is 12 + 32 + 16 = 60 bytes, 80 characters in base64url
Wrap to a public key (grants) HPKE (RFC 9180) base mode, DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, AES-256-GCM Composable from WebCrypto's X25519, HKDF and AES-GCM; native in Go 1.26 crypto/hpke; ≈ 80 bytes per grant (R3)
Key derivation, grant paths HKDF-SHA-256 (RFC 5869) In WebCrypto and Go; ten lines over Python's hmac
Commitment SHA-256 Every standard library

Associated data binds each ciphertext to where it belongs, so an entry cannot be transplanted into another item and pass for that item's own:

  • entry: AAD = "blyg-seal-v1" ‖ origin ‖ id ‖ entry, the item's identity origin and id and the entry's id. Not the version (section 3.6 carries unchanged entries forward).
  • wrap: AAD = "blyg-wrap-v1" ‖ lock ‖ epoch ‖ commit.

Padding (Proposal (Opus); plan §9 item 4). The plaintext object is serialised as UTF-8 JSON, prefixed with its byte length as a 4-byte big-endian integer, and padded with zero bytes to the next bucket: 256 bytes, then powers of two to 64 KiB, then multiples of 64 KiB. A three-word redaction and a forty-word one are the same 256 bytes; a reader of the wire learns a size class, not a length. The cost: a short span costs about 380 characters of base64url in the document instead of about 60.

3.4 The commitment, and why the plan's sealed_hash is dropped

AES-GCM does not bind a key to a ciphertext: a publisher can craft one ciphertext that decrypts validly under two keys to two texts and hand each to a different reader (the "invisible salamanders" result, R2 §1.2). A later reveal would then prove nothing.

Proposal (Opus); plan §9 items 2, 19, 23.

desc   = SHA-256(UTF-8 of `about` if present, else the cover's text content)
commit = SHA-256("blyg-commit-v1" ‖ entry_key ‖ nonce ‖ SHA-256(ct) ‖ desc)
  • It binds the key. Every holder checks the same clear commit against the key it was given; a second key for the same entry cannot match. This settles equivocation for every reader who checks.
  • It binds the ciphertext, so a home cannot hand out a key for different bytes.
  • It binds the description the reader was shown (about, else the cover's text content as §10.2 defines text content), so a buyer can show what was advertised against what was delivered (plan §3.1, #104).
  • It reveals nothing to a stranger. The entry key is 256 random bits, so the digest cannot be inverted or tested against a guess.

The plan's clear sealed_hash is dropped (its §12.1 example; §9 items 1 and 23). A hash of the sealed plaintext in the clear is exactly the guess-confirmation target R4 found for content_hash: anyone who suspects the redacted name is "Northwind Capital" hashes the guess and compares. Inside the ciphertext it would add nothing to the AEAD's own integrity. What a holder needs a second hash for, telling maintenance from new writing, is given by section 3.6 instead.

3.5 Nesting (AND) and several wraps (OR)

  • Nesting is containment. An entry's plaintext may carry its own sealed list (section 3.2), to any depth, under any locks. A reader needs the outer key to learn that an inner entry exists. "More restrictive" is the author's intent, not something the protocol checks: locks are independent. A client SHOULD warn when an inner lock has members the outer one lacks.
  • Several wraps. An entry's key may be wrapped under several locks. Any one opens it; which a reader used is local and unobservable. Locks compose by OR within an entry and by AND through nesting.
  • Each layer is checked. An inner entry's AAD uses the same item origin and id, and its commitment is checked like any other.

3.6 Versions: unchanged entries are carried byte for byte

Proposal (Opus); plan §9 items 1, 21; R4 §2.7. A publisher that publishes a new version in which an entry's sealed content and description are unchanged MUST carry the entry byte-identical (same entry, nonce, ct, commit); it MAY change its wraps (add a lock, move to a new epoch). An entry whose sealed content or description changed gets a fresh entry key and a fresh nonce.

What follows:

  • Maintenance is per audience. A Level 2 reader compares content_hash, which covers the covers: if the covers did not change, what it reads did not change, and §13.2's same-hash rule is correct for it. A Level 3 reader without the key also compares each entry's commit: a changed commitment means the sealed content changed. A holder compares the decrypted plaintext it holds. Nobody needs a clear hash of sealed text.
  • An entry key is per content, not per version. A key bought or granted for an entry at version 3 still opens it at version 4 if the entry was carried. Corrections to the clear text cost a reader nothing (RFC-7 recommends that corrections to sealed text be free too).
  • Stealth edits stay detectable. A changed ct under the same version is §13.3's stealth edit, detectable by anyone, because ciphertext is produced once per content and served byte-identical.
  • Re-wrapping is cheap. Widening one entry to a new lock (section 5) is a new version that adds a wrap; the ciphertext and commitment do not change, so it reads as maintenance to everyone.

3.7 What stays clear

Proposal (Opus); plan §9 item 6; R4's rows. References and counters clear, words sealed, member by member:

Member Proposal Why
id, kind, version, created, updated, changelog[].at, pinned clear The watermark (§13.3), reconciliation (§13.2) and staleness (§5.9) need them. The timing leak is disclosed (section 7)
content_md, content_html, content_hash clear; covers and clear text only Level 2 display and the feed (#4)
transclusions[], links[], forked_from, generated[].sources[] identities (origin, id, version) for a reference made in clear text; stub_of always clear Mentions verify (§15.4) and staleness works only if a stranger can read them. A stub is a public response to its target; a response whose target must stay secret is not a stub
Any reference member that carries words: selector, cited.excerpt, cited.author, a directive's label inside the plaintext when the quote or link sits in sealed text These are sealed words in another field (R4 §3 item 1)
A reference made only inside sealed text the publisher's choice, per reference: clear, or inside the plaintext (Fable, at the edit) Clear, it verifies and notifies, and tells everyone what the sealed words cite: in a redaction, that can name the thing redacted, and a published reference cannot be taken back. Inside, it sends no mention and nobody outside the audience learns of it. Recommended to clients: inside for a span, clear for a wholly sealed item (section 9, item 6)
media[] media used only by sealed words are listed inside the plaintext; their files are encrypted A clear image beside a sealed caption publishes the image. Encrypted media: section 3.8
generated[] entries for clear generated text clear; entries for generated text inside a seal inside the plaintext model and sources describe sealed words
author clear The byline is the publication's face (#11 untouched). A sealed byline is a sealed span in the prose
changelog[].note clear, under a new depth-rule clause A note is the feed title (§7). A clear note MUST NOT reproduce sealed content, even between two pinned versions: §5.2's allowance rests on both pins being public, and a sealed pin is not
terms clear A reader needs it before holding a key (section 3.12)

3.8 Media

Proposal (Opus). A media file used only by sealed words is encrypted under its own random key (AES-256-GCM, chunked in 64 KiB records for large files) and served as application/octet-stream at an ordinary media path; its key, nonce and real mime and alt are in the plaintext's media list. §5.4's immutability and §8 rule 4's retention apply to the ciphertext file. The file's size class is visible; padding media is not proposed.

3.9 Quoting sealed content

The plan's rule (§3.5): a quoter carries a sealed copy of what it quotes, needs no key, and widens nobody's access.

Proposal (Opus) for the shape:

  • The bake is §10.2's, unchanged. The quoter bakes the target's content_html verbatim, which contains the target's blyg-sealed elements and their covers.
  • The quoter's sealed list gains a copy of each entry the baked bytes contain, byte-identical, plus one member saying where it came from: "from": { "origin": "…", "id": "…", "version": n, "entry": "e1" }, and an entry id local to the quoter.
  • Matching. A blyg-sealed element inside a blyg-transclusion blockquote refers to the copied entry whose from matches the blockquote's data-blyg-origin (or the quoter's own origin), data-blyg-id and data-blyg-version and the element's data-blyg-entry. Nothing inside the bake is rewritten.
  • Decryption uses the source's AAD (from.origin, from.id, from.entry), so a copy decrypts exactly as the original did and cannot be passed off as the quoter's own.
  • Nested quotes carry nested copies: a thread quoting a thread that quoted a sealed item carries the copies the inner thread carried, with from chains intact.
  • Partial quotes. A partial quote's selection is a substring of the target's text content, covers included. Proposal: a selection that includes any part of a cover MUST include the whole cover and carries that entry's copy; one that cuts a cover is a publish error. Whether a partial bake keeps the blyg-sealed element is section 9 item 25.
  • Snapshot independence is kept (§10.4): the copy does not depend on the source afterwards. Redactions survive quoting, key holders still see through, and quoting a sealed item into a thread for another audience does not widen who can read it. Audience travels with the lock, not with the context.
  • A span is bound to its document: its AAD names the item. A passage that should be reusable on its own is made an item and quoted.
  • Fragments. A fragment carries no directive (#102), so it never carries copies. A sealed fragment is a fragment whose plaintext obeys the fragment rules, including the length cap, counted on the plaintext's content_md.

3.10 Origin keys, the home document, and grant files

The origin key. An origin MAY publish one public key in its manifest:

"encryption_key": { "alg": "X25519", "key": "<32 bytes, base64url>" }

It is the origin's, never an author's. It is for encryption only: it signs nothing and claims no authorship (section 6). Proposal (Opus) for the name and shape; a rotated origin key leaves earlier grants wrapped to the old one, so an origin keeps its old private keys for as long as it wants to read them.

The home document (Proposal (Opus); the plan's §3.6 needed a secret shared by home and recipient and did not say where it came from). A GET of the home URL returns:

{ "blyg_home": "0.5",
  "key": { "alg": "X25519", "key": "<home's public key>" },
  "grants": "g/{path}",
  "request_lock": "l/{lock}",
  "request_entry": "e/{commit}" }

grants, request_lock and request_entry are RFC 6570 level-1 templates resolved against the home URL, defaulting to the values shown (the manifest-template pattern of #51). A static-only home omits the two request templates.

Grant paths. For a recipient with a public key (an origin or a pass):

shared = X25519(home private key, recipient public key)        // either side computes it
path   = base32(HKDF-SHA-256(shared, salt = home URL,
                info = "blyg-grant-v1" ‖ subject))[0..26]       // 128 bits, lowercase
subject = "lock:" ‖ lock ‖ ":" ‖ epoch      or      "entry:" ‖ commit

For a lock recipient (a lock-to-lock grant), shared is the recipient lock's key at one of its own epochs, so every holder of lock B at that epoch can compute where the grants to B are. A holder tries each epoch key of B it holds. A home that means a lock-to-lock grant to continue writes it again for each new epoch of B; one it does not rewrite stays with those who held B then (Fable, at the edit). Pre-approval needs no contact: the home writes the grant before the recipient asks, and the recipient finds it by computing the path.

The grant file:

// GET {home}g/{path}
{ "for": { "lock": "k7f3m0q9…", "epoch": 2 },     // or { "entry": "<commit>" }
  "key": "<HPKE-sealed key to the recipient>",    // or AES-GCM under lock B, for lock-to-lock
  "terms": { "origin": "…", "id": "…", "version": 2 },   // OPTIONAL: terms in force at grant
  "at": "2026-11-12T17:30:00Z" }

A reader probes with an ordinary GET: 200 is granted, 404 is not (yet). Nobody else can tell which paths exist for whom, and there is no listing. A refusal MAY be delivered the same way: a file at the same path holding {"for": …, "refused": true, "note": "<sealed to the recipient>"}. A withdrawn grant is replaced by a lapse notice (section 5).

Recipients are of three sorts. An origin (its manifest key); a lock (lock-to-lock: every holder of B also reads everything granted to B, which is how an organisation expresses "the board reads whatever the executives read" with no hierarchy on the wire); a pass, a bare X25519 public key the reader's client generates and sends with a request. A pass gives a reader with no origin a static, re-fetchable grant with no account: the home learns a key and nothing else. It is a bearer instrument: whoever holds the private key holds the entitlement, it can be handed over, and it can be copied, which is no worse than a shared key and is said plainly. A wallet's or a token's control of a pass is evidence for the ladder, never a second key type on the wire.

3.11 The request endpoint

A lock's home MAY answer requests. It is a second dynamic surface, OPTIONAL at every level, like the Webmention receiver (#13, §15.7). A static-only publisher issues grants by hand, or homes its locks at a home someone else runs.

  • Two request URLs, from the home document: one per lock ({home}l/{lock}, standing membership for the current epoch) and one per entry ({home}e/{commit}, one entry's key). Proposal (Opus); plan §9 item 24: the entry URL is keyed by the commitment, which already identifies one entry's content uniquely and is URL-safe.

  • The request is a POST:

    { "recipient": { "origin": "https://blyg.example.org/" },
      "note": "I'm on the audit committee",
      "evidence": [ { "type": "…", "value": "…" } ] }
    

    recipient is { "origin": … } or { "pass": "<base64url X25519>" }. note is untrusted text the home handles as data. evidence is opaque to the protocol: a sign-on token, a payment voucher, a signed acceptance of terms, whatever the home's ladder accepts.

  • Proof of the recipient (Fable, at the edit; section 9 item 28). A request MAY carry

    "proof": { "at": "2026-11-14T22:10:05Z", "mac": "<base64url HMAC-SHA-256>" }
    

    where mac = HMAC-SHA-256(k, "blyg-request-v1" ‖ request URL ‖ at), k = HKDF-SHA-256(shared, salt = home URL, info = "blyg-request-v1"), and shared is the X25519 secret between the home's key and the recipient's, the one grant paths are derived from (section 3.10). Only the holder of the recipient's private key can compute it, and the home checks it with its own. The home refuses a proof whose at is more than five minutes from its clock. It is a MAC, not a signature: it convinces the home and nobody else, so an origin's key still signs nothing (section 6). A proven request is the recipient's own. An unproven one may come from anybody, whatever origin it names.

  • Three answers: granted (200, with the key wrapped to the recipient, or a statement that the grant file now exists), pending (202; the requester polls its grant path), refused (403, optional note). The home wraps any grant to the key in the named origin's manifest, so a false claim of origin earns a file the claimant cannot open.

  • Challenges. A home MAY answer a request with any HTTP challenge — 401, 402, any scheme — and the protocol names none. A reader that cannot satisfy one treats the request as not granted. RFC-7 is how 402 is used.

  • A GET with no body is a probe. It names no recipient, so its answer cannot depend on who asks, and the first answer is the same for everyone in substance: the same challenge, the same offer. Correction to the plan (§3.7, §8.2, §12.2): it is not cacheable. MPP's draft requires Cache-Control: no-store on every 402 and its challenge ids are unique per challenge (draft-httpauth-payment-01 §11.10, §5.1.2.1); x402's HTTP transport says to keep the 402 out of shared caches (specs/transports-v2/http.md, "Browser clients"). A home may still serve a static, cacheable offer list in its rail's own format; the protocol specifies none.

  • A home answers about a recipient only to that recipient (Fable, at the edit; replaces the draft's rule, section 9 item 12). Anyone can name a stranger's origin in a request. If the answer depended on whether that origin is on a roster, the home would be an oracle for its own member list, which is the follower list #12 and #13 refuse, served one query at a time. So:

    • To a proven request a home may answer anything live: granted, pending, refused. The asker has shown it is the recipient, and learning one's own standing is no leak.
    • To an unproven request a home gives the answer it would give anyone: a challenge, or a grant that follows from what the request itself carried (its evidence, its payment), wrapped to the named recipient. Whatever depends on who the recipient is — a grant or a refusal — is not said live: the answer is "pending", in the same time, and the outcome is found at the grant path, which only the recipient can compute.
    • A home SHOULD NOT put an unproven request in front of a person or a delegate as coming from the origin it names. Its note is anybody's text. The draft's rule covered grants and left refusals: a home that refused non-members live and answered members "pending" told the two apart.
  • CORS. A request endpoint meant for browser readers sends credentialed-CORS headers for the calling origin, never * with credentials (R4 §2.1), and exposes whatever challenge headers its rail uses (x402 lists its own).

  • Rate limits are the home's and private.

3.12 Epochs

  • A lock has a stable id and numbered epochs, each with its own key. A wrap names the lock and the epoch. Grant paths are derived per lock and epoch.
  • When an epoch ends and what a period is are the home's. Only the number is on the wire.
  • Standing access is a standing claim on the lock: each new epoch's key is granted to the recipient while the home's ladder says so (a roster, a paid subscription).
  • A held key keeps working. A recipient no longer granted new epochs still holds the epoch keys it was given. That is a fact about keys, not a policy, and what a lapsed reader is left with depends on which keys the home handed out (RFC-7 section 5: holding or on demand).
  • Whether the past is included is a lock-to-lock grant from an epoch to the one before it, at the home's choice and invisible on the wire.

3.13 Terms

There is no rights or licence construct anywhere in the 0.4 text. Level 3 needs one (an NDA, an officer's disclosure, what a buyer is buying) and so does a public blyg that wants to say "CC BY". One construct serves all of them: a reference to a stable document.

  • Shape: stub_of's two shapes. {origin, id, version} naming a blyg item at a version, or {url} for a document off Blygger. Proposal (Opus): a {url} target MAY carry sha256, the digest of the document as the referrer read it, so a later reader can tell whether the document at that URL is still the one cited.
  • A blyg target SHOULD be a pinned version. Unpinned history is never served (§8.4), so an unpinned earlier version of a terms thread cannot be fetched by anyone once it is revised. A pin keeps those bytes forever. A studio should pin a terms thread when it is first used.
  • Where it attaches: (a) a wrap, beside the lock: the terms of holding that key; (b) a grant file, optionally: the terms in force when the grant was made, so a subscriber's terms do not move when the lock's do; (c) an item and the manifest, an origin default with a per-item override: the terms of public content.
  • Different rights are different locks. Two wraps on one entry with different terms open the same bytes. The difference is legal only, and that is said plainly.
  • Accepting terms is evidence at the home, like a sign-on token or a payment proof. Whether a click-through or a signed document is required is the ladder's.
  • Lines held: a citation, never enforcement — nothing on the wire makes "delete after 30 days" happen. No rights vocabulary: no machine-readable permissions, no licence codes; an agent matches a well-known URL or reads the prose. A reader MUST NOT refuse to show public content over its terms. A terms reference sends no mention and is never a relation (§15.4). The terms document itself should be public. This is the protocol's first rights construct of any kind (#104).

4. How a reader gets content

  1. Hold. The entry names its locks and their homes. A reader holding any of the lock keys at the named epoch unwraps locally: no request, no traffic, nothing logged. This covers nested entries whose locks it holds.
  2. Probe. Holding none, it computes its grant paths at each home: the lock at that epoch, this one entry, or (through lock-to-lock grants) a lock it holds. A 200 is a grant.
  3. Ask. Finding nothing, it may POST a request to whichever home it thinks likeliest to agree, with a proof that it is the recipient it names (section 3.11), so that the home may answer it at once.
  4. Decide. The home runs its ladder: pre-approved (the grant already exists), automatic (a rule over origins, rosters — an OPML list is one natural form — or presented evidence), or exception (queued for the lock's owner or their AI delegate, working from the owner's standing instructions).
  5. Receive. A grant file appears, or a refusal, or nothing.
  6. Check. Before showing decrypted content, the reader checks the entry's commitment against the key and the ciphertext, and the description it was shown. A mismatch is shown as an error, never as content.

Rules for an approver's delegate (client guidance, as the plan states them): a requester's note is untrusted text and is handled as data; a delegate may grant entry keys only, never a lock key; an exception does not recurse (a key for an outer entry opens no inner one).

Where the centralisation lives. A traditional organisation homes common locks at one place and every author seals under them: wrapping is symmetric, so any holder of a lock key can seal under it from their own origin. A decentralised one homes locks per node, each with its own rosters, which agree only where nodes choose to share one. The wire says "this lock, ask here" in both cases.

5. Widening, revocation and lapse

Widening (declassifying):

Scope How Visible on the wire
One entry A new version adding a wrap under the wider lock; ciphertext and commitment unchanged, so it reads as maintenance Yes: the entry now names two locks
One group includes another A lock-to-lock grant No
One pinned entry A grant of that entry's key (by commitment) to a lock or origin; the pinned bytes are untouched No
Public Reveal the entry key in the clear (any reader then checks it against the commitment), or publish a new version with the words in place of the cover Yes

Fable, at the edit (the draft had a wrap under a lock named "public"): the reveal is a member of the entry, "revealed": "<entry key, base64url>", beside its wraps. A lock id is an opaque random string, and a reserved word among them is a second meaning for the field. A conforming reader checks the revealed key against the commitment and shows the content as ordinary content; a Level 2 reader still shows the cover until the publisher replaces it. A reveal is a new version that changes no ciphertext, so it reads as maintenance, and it cannot be undone: the same key opens every earlier and pinned version that carries the entry.

Revocation, stated in the register of §9 ("cooperation, not cryptography"):

  • It stops future grants and, after a lock moves to a new epoch, future content. Nothing else.
  • Nothing recalls a key or text a reader already holds, and nothing stops a holder republishing it.
  • A pinned version keeps the wraps it was pinned with, forever, so anyone who could open it at pin time can open it always.
  • Widening is one-way.

Lapse as a retention event (the plan's proposal, §8.3 and §9 item 15; shape by Opus). When a home withdraws a grant it replaces the grant file with a lapse notice:

{ "for": { "lock": "k7f3m0q9…", "epoch": 2 }, "lapsed": "2026-12-01T00:00:00Z" }

A conforming reader that finds a lapse notice at a grant path it used SHOULD drop the key and the decrypted copies it opened with it, as it drops withdrawn content (§13.4). A plain 404 where a grant used to be is not a lapse — hosts fail — and a reader treats it as a fetch failure (§12.3). Proposal: a reader rechecks its grant paths when it next opens content under that key, and at least as often as it polls the item's origin. This is cooperation, said as such: it is what makes "rental" in a terms document mean something among conforming clients, and a non-conforming reader keeps what it holds. A home that gives subscribers epoch keys and means them to keep what they paid for simply never writes a lapse notice for past epochs (RFC-7 section 5).

6. Identity

The design authenticates origins, as Webmention verification does (§15.4, invariant 4). Which person an origin belongs to is the approver's own knowledge: a roster, sign-on evidence, an h-card.

It sits inside #11 under the two conditions #101 named, which Fable rules here:

  • One key per origin, in the manifest, never inside author. A per-author key would make people addressable (#11, §16.8).
  • Encryption only. It signs nothing and claims no authorship. That stays with the identity practice of #35 and tn-2.

The key belongs in the manifest because other clients read it to write grants, and page markup cannot carry a claim that crosses clients (#41). An h-card may mirror it.

Shared origins. Where several people publish from one host as one origin (tn-3 shape B), a grant reaches the origin. Who inside may read it is the house's business, run off the wire as comments are (tn-7). The house can read everything granted to the origin; a member who cannot accept that needs their own origin (tn-3 shape A). A person who only reads either keeps a minimal origin or uses a pass.

6.1 Re-reading #35, tn-3 and #52 against this section

The session-66 brief asked for this re-read (opus-brief session 66 item 1; plan §7, §9 item 10). What it found:

  1. tn-3 gains a second test. #36's test for choosing between shapes is "who can withdraw". Sealed content adds a parallel one: who can read what is granted to the origin. In shape B the house reads every grant. That is the same answer for the same reason (the origin is the accountable party), and a member who needs their own key needs their own origin, exactly as one who needs their own withdrawals does. tn-3 section 5 should say so when this RFC closes.
  2. #35's signature proof covers only the cover. #35 proves authorship by a detached signature over content_hash, and content_hash covers what a keyless reader reads. A signature over a sealed item's content_hash says nothing about the sealed words. Proposal for tn-2, not for this RFC: a signed digest over content_hash followed by each entry's commit in document order covers the whole version, since each commitment binds its content. Nothing on the wire changes; tn-2 defines what is signed.
  3. #35's reciprocal-link proof is untouched, and so is the rule against cross-origin identity merges without a verified claim.
  4. #52 forbids a manifest key and .well-known for auth, meaning the write surface: how a tool discovers and authenticates to a studio. Two things here are near it:
    • The home URL sits in each wrap, not the manifest, and is not discovered through .well-known. That is clear of #52's invariant 2 on any reading.
    • The origin's encryption_key is in the manifest. It is not an auth construct: it grants nothing, authenticates no one to anything, and is useless to a tool wanting to publish. It is a public key for receiving confidential bytes, and it is authenticated the only way anything is in this protocol, by being served from the origin. The reading this draft takes is that #52's line is about the write surface and does not reach it. That is a reading of a locked decision, so it is Fable's (four-question test, Q3).

7. What is public, and what this does not protect

Under this design a stranger learns, and the RFC says so rather than hiding it:

  • Existence and timing. A sealed item is in the archive index and the feed like any item (§6.2, §7); its version, created, updated and changelog at are clear.
  • Size class, to a padding bucket (section 3.3).
  • Which entries share a lock, since lock ids are clear (section 9 item 7), and which home each lock uses.
  • Citations, where the publisher leaves them clear, and stub_of always (section 3.7).
  • Epoch cadence, which may reveal a home's rotation or billing period (section 9 item 21).
  • Member counts if the grants host lists. Grant paths are unguessable, but a host that lists directories, or a public repository that holds the grant files, shows how many grants a home has written and when: a member count and churn. A home SHOULD serve grants from a host that does not list, and MUST NOT publish them in a public repository.

What no family of design prevents (R7): the reader who republishes what they opened; a former member's past and pinned access; the origin's control of a page that decrypts in the browser with its own script. A page that decrypts with script served by the origin protects content from the network, not from the origin or its host (R7 §2). Decryption in the reader's own client avoids that for subscribers, not for someone who arrives from a link.

Harvest now, decrypt later. The item document carries only symmetric wraps (AES-256 under lock keys), which known quantum attacks do not threaten beyond Grover's square root (R2 §3). The classical exposure is in grant files, which wrap keys to X25519 public keys; they are public bytes at unguessable paths, so an attacker must first find them. This is a better position than R3's per-reader wrapped-key lists, which would have put classical wraps in every public document. Section 9 item 16.

8. How the existing text reads under it

The wire impact, construct by construct. R4's table (plans/l3/r4-spec-audit.md) is the full checklist; these are its answers under this design.

0.4 construct Under sealed content
§3 levels; ignore unknown A sealed item is a valid L2 document showing its covers; L3 is a superset
§3 conformance cost A non-decrypting reader's rules stay standard-library (SHA-256, JSON). Decryption does not: section 9 item 3
§4 same bytes for everyone Holds: ciphertext, wraps and grant files are the same bytes for anyone who fetches them
§4 static surface Holds for the origin. The home's request endpoint is a second dynamic surface, optional (item 10)
§5.1 content_hash Unchanged: over the covers. Holders get the commitment (section 3.4)
§5.2 depth rule Gains a clause: a clear note never reproduces sealed content (section 3.7)
§5.3 kinds, cap No new kind; a sealed fragment's cap counts its plaintext
§5.4 media Encrypted media for sealed words (section 3.8)
§5.6 forks A forker without the key cannot fork the sealed words, and keeps the seal by carrying each entry as a copy with from, exactly as a quote does (section 3.9): the entry's AAD names the source item, so it cannot be re-homed. One with the key may do the same, or publish the words in its own audience. Client policy, as #93 F3 treated quoting across a boundary (item 14)
§5.7 generation Sealed text fed to a generator lands in the generating item's audience. Client policy (item 14)
§5.9 references, cited Identities clear; cited.excerpt of a sealed target is sealed words and goes inside or is omitted
§6.2 index, §7 feed Sealed items listed with covers; spans add no events; a plain RSS reader sees covers (item 8)
§8 pins A sealed version may be pinned; the promise is ciphertext (item 9)
§10.2 bake Unchanged; entries copied beside it (section 3.9)
§10.3 selector Inside the plaintext when the quote sits in sealed text
§13.2 maintenance Per audience (section 3.6)
§13.3 stealth edits Detectable by anyone (section 3.6)
§13.4 retention Gains lapse as a retention event (section 5)
§13.5 curation display A holder displaying an imported sealed item in a public hopper page publishes it. Client policy: display the cover
§14 Gains the disclosures of section 7
§15.4 verification Works on clear references; a receiver classifying a repost reads the cover (item 13)
§16.8 never No follower graph: wrapped keys name locks, grants sit at unguessable paths, the live answer is never an oracle
§16.9 cid A cid on a sealed pin makes the ciphertext durable beyond the origin; nothing on the wire depends on it being secret

9. Items to be ruled

Every item is new wire (four-question test, Q2 yes), so every item is Fable's, at the edit or at the close. Each states the options, the proposal and a test: the check that would show the proposal right or wrong. Items 1–24 are the plan's §9, in its order; items 25–27 were new in the draft; item 28 was added at the edit.

Where each item stands after the edit (Fable 5.2, session 70, decision #106)

A ruling made at the edit is the position the comment period argues with, not a closed question: the close revises it in the light of what was said (#90). "Stands" means the proposal is the position; "open" means the edit did not rule, and says what would.

Item After the edit
1, 23 Second hash, sealed_hash Ruled as proposed: no hash of sealed text anywhere in the clear. A hash an outsider can test a guess against is not an integrity feature
2, 19 Commitment Ruled as proposed. The probe confirms the two-key case is rejected
3 Algorithms; the conformance-cost criterion Suite: stands, open until the probe has run it in a browser, a Worker, Go and Python. Criterion: ruled, option (a). §3's paragraph on what conformance costs describes a reader that does not decrypt, and stays true of it: such a reader ignores sealed, shows covers and compares commitments as strings. A reader that decrypts holds its platform's cryptography library, and the 0.5 text will say so. One suite, chosen because browsers have it, is what keeps that cost the same for every client
4 Padding Stands; the bucket sizes are open to the probe's measurements
5 Selector Ruled as proposed
6 What stays clear Ruled with one change: a reference made only in sealed text is clear or inside at the publisher's choice, with no default on the wire. The draft's "clear by default" would have had a redaction publish, in links[], the identity it redacts. Recommended to clients: inside for a span, since a span exists to hide something in a public text and what it cites is the likeliest thing hidden; clear for a wholly sealed item, since that is a publication to a narrower audience and its use of other people's words is the case #44's reasoning on notification speaks to. stub_of is always clear
7 Lock ids visible Ruled as proposed, for a different reason. The draft said a home's URLs are per lock; they are not, a home serves many. The reason is that a reader who holds nothing must be able to name the lock it is asking for
8 Index and feed Ruled as proposed
9 Pins Ruled as proposed
10 Carve-out; #52 Ruled as proposed. #52's line is about how a tool finds and authenticates to a studio's write surface. A key for receiving confidential bytes authorises nothing, and is authenticated as everything here is, by being served from the origin
11 Grant paths Stands, with the lock-to-lock epoch made explicit (section 3.10); two implementations agreeing is the test
12 The oracle Ruled with a change: section 3.11's rule, resting on item 28
13 Mentions Ruled as proposed, for clear references
14 Generation, forks, display Ruled as proposed (client policy), with the mechanics of a kept seal stated (section 8, §5.6 row)
15 Lapse Ruled as proposed: SHOULD, cooperation, said as such
16 Post-quantum Ruled as proposed: disclose, reserve alg
17 Conformance Stands; the clauses are written when the constructs are built (#21)
18 about Stands; the cap is open to implementers' answers (section 10)
20 The pass Stands; whether readers without an origin are a real population is section 10's first question
21 Epochs Ruled as proposed
22 Terms Stands, and is not split out. The item and manifest uses stay in this RFC until the close, so the construct is argued once
24 Request shape Stands, with proof added (item 28)
25 Partial quotes Ruled as proposed: whole covers only
26 Home document Ruled as proposed
27 Reveal Ruled with a change: an entry member revealed, not a reserved lock id (section 5)
28 Request proof New, ruled at the edit; the MAC's exact input is open to the probe

Wire shape

1. A second hash.

  • Options: (a) a clear hash of the sealed plaintext; (b) a hash inside the ciphertext; (c) no second hash; maintenance per audience from content_hash, each entry's commit and the holder's own plaintext.
  • Proposal: (c), with section 3.6's carry-over rule.
  • Test: write out §13.2's maintenance decision for an L2 reader, an L3 non-holder and a holder across the four cases (cover changed or not, sealed text changed or not); each must be decidable and none may need a guessable clear hash.

2. Key commitment.

  • Options: (a) none, disclose equivocation; (b) a committing AEAD construction; (c) a clear SHA-256 commitment over key, nonce, ciphertext and description.
  • Proposal: (c), section 3.4. (b) is cleaner cryptography, but no committing AEAD is in WebCrypto.
  • Test: the probe (R8, on Venkat's word) builds an AES-GCM ciphertext that opens under two keys and confirms the commitment check rejects the second key.

3. Algorithms, and the stdlib rule.

  • Options for the suite: AES-GCM + HKDF + X25519 HPKE (the browser intersection); ChaCha20-Poly1305 (not in WebCrypto); post-quantum hybrids (not in stable browsers).
  • Options for §3's conformance-cost criterion (#103 item 7), which Python cannot meet for decryption (R2 §0): (a) exempt decryption, stating that a reader which decrypts holds a platform cryptography library (WebCrypto, Go's standard library, Python's cryptography); (b) restate the criterion as "each platform's primary crypto library"; (c) keep the criterion and treat decryption as a client feature outside the rules.
  • Proposal: the suite of section 3.3; criterion option (a), with the line drawn at decrypting: every rule a non-decrypting reader follows stays standard-library (it ignores sealed, shows covers, may compare commitments as strings). This reinterprets #103 and needs Fable.
  • Test: the probe seals and opens an entry with nested entries in a browser, a Worker, Go and Python. Workers' support for X25519 in crypto.subtle is unconfirmed (R2 did not cover Workers; this draft did not check either): the probe settles it.

4. Padding.

  • Options: none; power-of-two buckets; fixed block sizes (WNFS).
  • Proposal: section 3.3's buckets, 256 bytes minimum.
  • Test: sizes measured by the probe for a three-word span, a paragraph and a 4,000-word item; the overhead on a typical redacted thread should be under 2 KB.

5. Locating a span in content_md.

  • Options: (a) clients render content_html only; (b) a text selector on each span's entry; (c) markup in content_md (refused by #101: no new markup).
  • Proposal: (b), section 3.1.
  • Test: a markdown-rendering reader substitutes every span of a fixture correctly from content_md and the selectors alone, including two identical covers in one item (the prefix and suffix must disambiguate; if they cannot, the publisher must refuse).

6. What stays clear.

  • Proposal: section 3.7's table: references and counters clear, words sealed, a clear note never reproduces sealed content. At the edit: a reference made only in sealed text is the publisher's choice, clear or inside (see the table above).
  • Test: every row of R4's audit table has an answer under the proposal, and no member that carries a target's words is clear when the words are sealed.

7. Lock ids are visible.

  • Options: accept; blind them per entry (an HMAC of the lock id under the lock key, so only holders recognise their locks).
  • Proposal: accept and disclose. At the edit: the reason is that a reader holding nothing asks for a lock by its id ({home}l/{lock}), so a blinded id leaves it nothing to ask for.
  • Test: none needed beyond the disclosure; revisit if an implementer names a case where shared-lock visibility harms them.

Surface

8. The index and the feed.

  • Proposal: sealed items are listed and announced like any item, with their covers; a span adds no event; a plain RSS reader sees covers. §6.2's "every item ever published" and §7's "no quiet publish" hold unchanged.
  • Test: a feed with a sealed item validates as RSS 2.0 and reads sensibly in two plain RSS readers.

9. Pins.

  • Proposal: a sealed version may be pinned; the promise is the ciphertext. A publisher that pins a sealed version SHOULD keep the keys that open it for as long as it grants them, and the RFC discloses that a pin defeats revocation for anyone who could open it at pin time, and that a lost key leaves a kept promise unreadable.
  • Test: none; a disclosure.

10. The carve-out, and #52.

  • Proposal: the request endpoint is a second dynamic surface under #13's carve-out, OPTIONAL at every level; the home URL sits in the wrap, not the manifest; the origin's encryption_key in the manifest is not an auth construct under #52 (section 6.1 item 4).
  • Test: a static-only origin can seal, grant by hand from a static home, and be read by a second client, with no dynamic surface anywhere.

11. Grant path derivation.

  • Proposal: section 3.10: X25519 between home and recipient, HKDF to a 128-bit path; lock-to-lock paths from the lock key. Hosts that list directories or publish their repositories defeat the secrecy of which paths exist (member counts and churn), not of the grants themselves, which are wrapped. Disclosed, with a SHOULD and a MUST NOT (section 7).
  • Test: two independent implementations compute the same path from the same keys.

12. Abuse of the request endpoint, and the oracle.

  • Proposal: section 3.11: a probe's answer is the same for everyone in substance and is not cached; rate limits private. This departs from the plan's "cacheable", because both rails forbid caching a 402. At the edit: a home answers about a recipient only to a proven request (item 28); an unproven one learns nothing that depends on who the recipient is, grant or refusal.
  • Test: unproven requests naming an origin on a roster and one that is not get answers indistinguishable in content and in time; a proven request from the rostered origin is granted live.

Behaviour

13. Mentions.

  • Proposal: yes. A clear reference sends and verifies a mention like any other, so a sealed item with clear references behaves like any item; the receiver displays the cover; repost classification reads the cover. A reference listed inside the plaintext sends nothing.
  • Test: a sealed stub of a public item verifies on a 0.4 receiver unchanged.

14. Generation, forks and display across a boundary.

  • Proposal: client policy, as #93 F3 treated quoting across an enterprise boundary. The reference client's defaults, recommended to others: a generator's output from a sealed source is sealed under the narrowest lock among its sources unless the author says otherwise; a fork of a sealed item keeps the seal; a hopper page displays a sealed import's cover.
  • Test: none; revisit if two clients disagree in a way a reader can see.

15. Revocation as a retention event.

  • Proposal: yes, SHOULD, cooperation; the lapse notice of section 5; a 404 is not a lapse; recheck on next open and at least as often as polling. A reader holding a lock key whose later epochs lapse keeps earlier epochs unless the notice names them.
  • Test: a conforming reader drops a lapsed entry's plaintext and shows the cover.

16. Post-quantum.

  • Options: require a hybrid KEM now; disclose and reserve alg.
  • Proposal: disclose and reserve. The public documents carry only symmetric wraps; the classical exposure is in grant files at unguessable paths (section 7). X-Wing is not in stable WebCrypto (R2 §3), so requiring it now would exclude browser readers.
  • Test: revisit when a hybrid KEM ships in stable WebCrypto.

17. Conformance.

  • Proposal: existing clauses stand, since a sealed document is a valid L2 document; new publisher clauses at 0.5 (commitment format, carry-over, AAD, padding, class and selector agreement); the live crawler needs no L3 mode before the first sealed entry, and gains a check that each blyg-sealed element has a matching entry.
  • Test: the publisher suite run against a sealed fixture passes every existing clause.

Added session 67

18. about.

  • Proposal: section 3.1: optional, 300 code points, plain text, never a title, never required.
  • Test: an agent instructed to buy on topic can decide from about-else-cover for the probe's fixtures.

19. What the commitment binds.

  • Proposal: key, nonce, ciphertext and the description shown (section 3.4).
  • Test: changing any of the four makes the check fail.

20. The pass.

  • Proposal: grant paths from X25519 between the home and the pass key, as for origins; a pass may receive entry keys and lock keys (a reader with no origin can subscribe); the RFC tells readers that a pass is a bearer instrument, to be kept like a password and never put in a URL.
  • Test: a reader with no origin buys an entry, closes the browser, and refetches the grant with only the pass's private key.

21. Epochs.

  • Proposal: section 3.12; a wrap carries lock and epoch. Epoch numbers and timing leak a home's rotation cadence, which may be its billing period; a home that minds rotates on a fixed schedule independent of billing.
  • Test: none; a disclosure.

22. Terms.

  • Proposal: the member is terms (rights reads as a grant of rights, license fails NDAs); a {url} target MAY carry sha256; the item and manifest uses stay in this RFC, so the construct is designed once, and Fable may rule them apart early as a 0.4 revision, since they are useful at Level 2 today.
  • Test: the construct reads correctly for CC BY on a public blyg, an NDA on a lock and a per-subscriber licence on a grant.

23. sealed_hash.

  • Proposal: not on the wire (section 3.4). The plan's example placed it in the clear.
  • Test: as item 1.

24. The request's shape.

  • Proposal: section 3.11: POST to {home}l/{lock} or {home}e/{commit} from the home document's templates, body {recipient, note?, evidence?}.
  • Test: the worked example of RFC-7 section 4 runs end to end against it.

New in this draft

25. Partial quotes that include a cover.

  • Options: (a) the partial bake keeps the blyg-sealed element and carries the copy; (b) a partial quote may not include a cover at all.
  • Proposal: (a), whole covers only (section 3.9).
  • Test: a partial quote spanning a redacted name verifies by §10.2's substring rule against the target's text content and opens for a holder.

26. The home document.

  • Proposal: section 3.10. Without it, grant paths need a secret the plan never said how home and recipient share.
  • Test: a pre-approved recipient finds its grant with no prior contact.

27. Revealing a key in the clear.

  • Proposal (Opus): a wrap under a lock named "public". At the edit: an entry member revealed (section 5).
  • Test: a Level 3 reader shows a revealed entry; the commitment checks.

Added at the edit

28. Proof that a request is the recipient's.

  • Options: (a) none: any request may name any origin, and the home guards its roster by never answering live about a recipient (the draft); (b) a signature by the recipient's key, which needs a signing key the design refuses (section 6); (c) a MAC under the secret the home and the recipient already share for grant paths.
  • Ruled: (c), section 3.11. It needs nothing the suite lacks (X25519, HKDF, HMAC), it proves nothing to a third party, and it lets a home answer its own members at once, which on-demand subscriptions need (RFC-7 section 5).
  • Open: the exact bytes under the MAC and the clock window.
  • Test: a request with a valid proof is answered live; the same request with the proof of a different key, or one six minutes old, is answered as an unproven request.

10. Questions for implementers

  1. Readers without an origin. Is this a real population for you? RFC-7 depends on the answer: the pass exists for it.
  2. Homes. Would you run one home per organisation, one per node, or use someone else's?
  3. Evidence. What would your ladder want to see: sign-on tokens, rosters, signed terms, payment, something else?
  4. Redaction. Are author-written covers enough, or do you need something the cover cannot express?
  5. Rendering. Do you render content_html or content_md? If content_md, do the selectors (item 5) work for your documents?
  6. Crypto. Can your platform do AES-256-GCM, HKDF-SHA-256 and X25519 today? Which library?
  7. What leaks. Of section 7's list, which is unacceptable for your use?

11. Rejected designs

Recorded because each will be proposed.

  1. Per-reader wrapped keys in the document (R3 §1.1). Publishes the audience's size, and its churn over versions, to everyone forever: a follower list (#12, #13, §16.8).
  2. A new kind for sealed items. Level 2 readers ignore unknown kinds, so the item would vanish for them instead of showing its cover (R4 §2.2), and kinds are fixed (#100).
  3. Ciphertext in content_md. Level 2 readers would show base64 as prose.
  4. Per-reader bytes or URLs on the surface (the per-subscriber feed). C2, refused by #93; and §12.2 would make the secret part of the subscription identity (R4 §2.6).
  5. A clear hash of the sealed plaintext. Guess confirmation (section 3.4).
  6. Deterministic encryption so equal plaintexts give equal ciphertexts. It lets anyone test equality across items. Carry-over (section 3.6) gives byte-identical re-serving without it.
  7. A key service named in the manifest. It would bind every client to one service and sit on #52's line; the home sits in each wrap.
  8. Expiry, read counts or metering on keys or entries. Refused in advance by #101 as narrowed by #104: nothing would enforce them.
  9. Sealed fragments as the block mechanism. Dropped in session 66 for spans, which cost no feed events.
  10. A cacheable 402. The plan's; both rails forbid it (section 3.11).
  11. A signature on a request. It would give every origin a signing key, which section 6 refuses. The MAC of section 3.11 proves the same thing to the one party that needs it.
  12. A reserved lock id meaning "public". A second meaning for a field of opaque ids; the reveal is its own member (section 5).

12. Relation to other documents

  • docs/v0.5-plan.md: the direction this RFC turns into a design. Where they differ, this RFC says why (items 12, 23, 24, 26).
  • RFC-7: payments. It adds no wire construct; it uses the request endpoint, challenges, the pass, epochs, about and terms from this RFC.
  • plans/l3/ R1–R7: the research. R4's audit is section 8's checklist; R7's worksheet dispositions are proposed in section 13.
  • RFC-5 (to become tn-8): one audience per origin, the C1/C2/C3 classification this RFC starts from.
  • tn-3: groups; gains the second test of section 6.1.
  • tn-2 (identity, unwritten): gains the signed-digest proposal of section 6.1.
  • RFC-4 (responding from anywhere, unwritten): its handler gains a redeem verb (RFC-7 section 6).

13. R7's worksheet, with dispositions proposed

R7 (plans/l3/r7-threat-model.md) left a disposition column for the round. This design is none of R7's three families exactly: entry keys ride along wrapped to locks (symmetric, naming no reader), and readers obtain lock keys off the document through grant files and homes. The rows below say what this design does and propose a disposition for each. All are proposals (Opus).

Adversary and capability Under this design Proposed disposition
Stranger reads sealed content Needs a lock key or an entry key Prevent (AES-256-GCM)
Stranger learns existence, timing, edit count, size class Index, feed, counters, padded length Disclose (section 7)
Stranger learns audience size or membership No reader is named in any document; grant paths are unguessable; a home answers about a recipient only to a proven request Prevent, except a listing host: disclose with a SHOULD and a MUST NOT (section 7)
Stranger confirms a guess at the sealed text No clear hash of sealed text; the commitment includes a 256-bit key Prevent (section 3.4)
Harvest now, decrypt later Documents carry only symmetric wraps; grant files carry classical X25519 wraps at hidden paths Disclose for 0.5, alg reserved (item 16)
Stranger learns the citation graph of sealed items A reference made in sealed text is clear or inside, at the publisher's choice; stub_of is clear Disclose what is left clear (section 3.7)
Stranger probes or floods a home, or asks in another origin's name Optional endpoint, private rate limits, uniform answer to unproven requests, which reach no person under the name they claim Prevent the impersonation and the oracle (section 3.11); the rest out of scope
Former member keeps what they decrypted, and pinned versions Nothing recalls a held key Disclose (section 5)
Former member reads content published after revocation Not without a later epoch's key or a new entry key Prevent, for content sealed under later epochs only
Paying reader republishes, inside or outside the protocol Quotes copy ciphertext, not plaintext; a holder can still copy the plaintext anywhere Disclose; generation and forks across a boundary are client policy (item 14)
Paying reader shares a key or a pass A pass is a bearer instrument Disclose (section 3.10)
Leak traced to a reader Every holder gets the same bytes; no watermarking Out of scope (per-reader bytes are refused, #93)
Host reads sealed content Not from what it serves; yes if readers decrypt in a page whose script it serves Prevent for clients that decrypt locally; disclose for in-page decryption (section 7)
Host or publisher shows different readers different text One ciphertext, one commitment, checked by every holder Prevent (section 3.4)
Host observes who fetches what Request logs, and grant-path fetches at the home Disclose
Compromised studio reads, publishes, adds itself to locks It holds the keys Out of scope (client security), disclosed
Lost keys A pin is kept and unreadable Disclose (item 9)
Third-party home operator Holds lock keys, reads everything under them, sees requests Disclose (RFC-7 section 9)
Payment processor, routing nodes Rail-specific Out of scope, rail by rail (RFC-7 section 9)

14. What happens next

The two RFCs were published together on blyg.blygger.org on 2026-11-14, with a comment period to 2026-11-28 (#66, #104) and a blygger-spec issue each for people without a blyg (#34, #35). Fable edited both the same day (decision #106; the table at the head of section 9 says what was ruled and what is open), published as version 2 of each item; any later edit is a new version too. At the close the rulings are revised and the RFC is promoted as a technical note (#90). Then the build order, to be confirmed at the close (plan §11): the envelope and spans with keys handed over by hand (this alone exercises a Level 3 construct and opens the 0.5 document); origin keys, the home document and grant files; the request endpoint and ladder; lock-to-lock grants and epochs. Each step is usable without the next. A throwaway probe (R8) runs before the close only on Venkat's word.

Source: docs/rfcs/rfc-6-sealed-content.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

v2 · pinned: v1, v2

“RFC-6 edited by Fable (decision #106): section 9 opens with what was ruled.”

Created: Nov 14, 2026 Most recent: Nov 15, 2026, v2

thread

Blygger Studio 0.58.2 to 0.59.0

3 releases of the reference client, newest first. Read each one's Migrations line before upgrading.

0.59.0: Extensions from other repositories, menu zones and editor regions

Released 2026-11-13. v0.59.0 on GitHub.

Three changes for extension authors and operators, held on main since 0.58.1. It also carries everything in 0.58.2 and 0.58.3, which were released from a branch without them.

Vendoring an extension from another repository (#59, decision #89). An operator can compile a browser-only extension published in someone else's repository into their own build: npm run ext:add -- <https repo> <commit> fetches exactly that commit on the operator's machine, checks its layout, that it has no server half, its imports and a typecheck against the extension API, prints every file and a tree hash, and vendors it only after a yes. ext:update and ext:remove do the rest. The source goes into the gitignored extensions-vendor/ and the lock into extensions.local.json, so nothing vendored is committed and a release build never carries one; npm run build re-hashes each vendored tree and refuses one edited since. No Studio loads anything at run time, and there is no registry. See docs/extension-vendoring.md.

Menu zones (#143). An extension page asks for a place in the main menu with page.mainMenu.zone: top (one page, above reading), visible (one page, above compose; the default, and where mainMenu: { icon } put a page before) or hidden (More). The Studio decides: a full zone moves a page down, never up, in compiled order, and the page's context says what it asked for and where it landed (menu: { asked, zone }). Template: extensions/menu-top-example.

Editor regions (#144). An extension can keep parts of the full editor's text out of its text box, for text a tool writes and the author should not edit by hand, such as chapter navigation. editorRegions({ text, item }) returns ranges; the box shows the rest, and every edit is joined back with the regions before the draft sees it, so autosave, preview, counts and publish keep the whole text. Hidden each time the editor opens, read-only when shown, and if a join does not round-trip the edit is saved whole and the editor shows everything. Full editor only. Template: extensions/regions-example.

Extensions and the error log (0.58.2's hooks, carried to the new surfaces): an extension page's context is built per extension, so its errors are logged under its name and it has showError.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none. A node coming from before 0.58.0 needs 0045.

0.58.3: Sublists, verse and code blocks are easier to type

Released 2026-11-13. v0.58.3 on GitHub.

Sublists, line breaks inside a paragraph and code blocks always rendered: the Studio's markdown is CommonMark. What was missing was a way to type them in a text box.

  • Tab and Shift+Tab move the list item under the cursor in and out a level; with several lines selected they all move, and undo takes it back. A numbered item that opens a sublist is renumbered to 1, which is the only way markdown reads it as a list. Off a list, or on the first item of one, Tab moves focus as usual.
  • Shift+Enter breaks a line without ending the paragraph, for verse or an address. It types markdown's backslash line break, which you can see in the text. Inside a code block it types a plain newline.
  • The full editor's toolbar has a button for each, and one that puts the selected lines in a code block (or starts an empty one), for an iPad's keyboard, which has no Tab key.
  • The syntax page has a Markdown section saying how to write each by hand.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none. A node coming from before 0.58.0 needs 0045.

0.58.2: An error log you can read and send, and focus view on an iPad

Released 2026-11-13. v0.58.2 on GitHub.

The Studio keeps an error log (Settings → Errors). An error banner can be gone before you have read it; what it said is now kept, with the time, the page you were on, the item, the request that failed with its status and error code, the Studio version and a stack. Every banner has a details link to its entry. Errors that never reach a banner are kept too: uncaught exceptions, unhandled promise rejections, and a page that failed to load. A failure repeated within a minute is one entry with a count and the time it first happened.

  • The log stays on the device. It lives in the browser's own storage, holds the latest 100 entries, and is sent nowhere. Each device has its own. It records failures, not writing: no draft text, and no query strings.
  • Export error log hands over a dated JSON file with the entries, the Studio version and the device (browser, platform, screen and window size, whether the Studio was opened from the home screen, language, timezone). A phone or tablet opens the share sheet; a desktop saves the file. Copy diagnostics puts the same as plain text on the clipboard, for an issue. Clear error log empties it.
  • Not logged: messages to the author such as a link that does not resolve, requests the Studio cancelled, and requests the browser dropped because you were leaving the page.
  • Only the browser Studio is covered. Cron, the importer and Webmention run on the server with no browser attached, and their errors are in the Worker's own logs.

Extensions. What an extension throws in a slot is logged under its name and the slot (the slot still renders nothing until the page reloads). An error caught by context.run is logged the same way, as well as shown. New: context.showError(error) shows an error the extension found for itself in the screen's error line and logs it; pass an Error or a message. Existing extensions need no change. The example extension uses it, and docs/extensions.md describes it.

Focus view on an iPad closed as soon as it opened. iPad Safari has browser fullscreen and leaves it when the on-screen keyboard comes up; the Studio took that for Escape. On an iPad and iPhone the view no longer asks for browser fullscreen, so Safari's toolbar stays and the view stays open.

Hiding or showing a response could fail with "Collection must be in 'ready' state for manual sync operations" if you left the page before the server answered: the one write 0.58.1's fix (#142) had missed.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none. A node coming from before 0.58.0 needs 0045.

This announcement is drafted from the releases' sections of CHANGELOG.md, which is where they are maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 14, 2026

In response to blyg.aneeshsathe.com ↗

thread

Aneesh, the Mentions view you asked for in your RFC-1 comment shipped in Blygger Studio 0.56.0 (studio#134). It's a lens on the Reading tab.

It works the way you described. When an item you've imported carries an h-card whose URL matches your author URL or your blyg's own address, it's listed under Mentions, and your name is highlighted where it appears. Quotes are left out, because an h-card inside a quote is the quoted author's words, not a mention by the person quoting. The list is labelled as found by your reader and kept apart from verified Webmentions. It shows no count, and nothing is sent to anyone, so ruling 2 stands.

Two limits are deliberate. It reads only what you already read: blygs you don't follow aren't crawled or queried, so mentions from feeds you aren't subscribed to don't appear. And until a member record exists, it matches on your author URL and your blyg's address. The old mentions tab is now called responses.

read the thread →

Created: Nov 9, 2026

thread

Blygger Studio 0.58.1: Stubs from Reading open again, and long chapters type quickly

Released 2026-11-09, the reference client. v0.58.1 on GitHub.

stub ↗ on Reading could fail with "Collection must be in 'ready' state for manual sync operations" (#142, reported by fredcy). It happened once the studio had dropped its copy of your items after you left the pages that use it: the server made the draft, but the editor never opened, and each try left another empty draft behind. Those drafts are safe to discard. The same could happen to a link post, an extension page's create, or adding a subscription, hopper or client token; all of them now carry on.

Comments to self (/* … */, 0.57.0):

  • A comment now opens only at the start of a line or after a space, and never as /**. So src/*.ts publishes as written instead of refusing, and /**bold**/ no longer disappears. A /* attached to a word with a */ after it in the same paragraph (word/*note*/) refuses publish and says to put a space before it, so a note written that way under 0.57.0 cannot slip out.
  • Typing in a long document with many comments no longer lags. The editor counts and checks for unpublished changes after a pause in typing instead of on every keystroke.

Focus view keeps a fragment's tint whether or not the text box has focus (it showed only while you were typing). Quick edit shows the word count beside the character count when the word-count extension is on, with the counts on their own row on a phone.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none. A node coming from before 0.58.0 needs 0045.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 9, 2026

thread

Blygger Studio 0.57.0 to 0.58.0

2 releases of the reference client, newest first. Read each one's Migrations line before upgrading.

0.58.0: Changelogs you can read, and an order that ignores the noise

Released 2026-11-07. v0.58.0 on GitHub.

Changelog display (#140, decision #95). Settings → Feed → changelog chooses, for your own item pages and separately for blyg items in your reader, what to show of an item's changelog: the latest note (the default, as before), the full history of notes newest first, or an AI summary of them. A summary is written from the notes only, never from the text of earlier versions, so it cannot reveal what the author left unpinned. It is labelled with the model's name and stays in your studio, never in the item document or the feed. Each summary is written once per version and kept: on your pages, in the background on a version's first view, with the full history shown meanwhile; in your reader, only when you open an item. Settings → AI → changelog summaries takes your instructions for how summaries should read.

Summarize the history to date (#140). The editor's note card has a new checkbox, off each time: a drafted note then covers every version so far, ending with this one, up to 400 characters, under the same rule as any note against quoting unpinned text. The note becomes the start of that version's feed title.

The pace-layered order (#141, RFC-3, decision #97). A version republished unchanged, or with an edit of a few characters, no longer climbs. A thread published together with the fragments it names, within 15 minutes, is one publication: it takes one place in the order, with the fragments beneath the thread. A withdrawn thread's fragments stand on their own. The order's fixtures now live in blygger-spec (conformance/feeds/), where other clients can check against them.

Private contract 5.8.0 (additive: POST /changelog-summary, history on draftNote, three settings); SDK 0.14.0. Protocol version unchanged ("0.4").

Migrations: 0045 (changelog_summaries). Apply it before deploying.

0.57.0: Writing a book on the studio

Released 2026-11-07. v0.57.0 on GitHub.

Most of this release was asked for while writing a book on the studio (the blykker pilot, New Nature).

Comments to self (#131). In a working copy, /* … */ holds a note for you: inline or over several lines, kept across saves and publishes, and left out of everything public: the page, feeds, item documents, history and quotes. A TK scope inside one can be generated as usual. Editing only a comment is not an unpublished change. An unclosed /*, or a */ on its own, blocks publish rather than risk showing the note. In code they are literal; elsewhere \/* and \*/ write the characters. Existing text can change meaning: a working copy that already has /* outside code will either refuse to publish with a reason or, if a */ follows, drop the text between them at its next publish or quote refresh. The preview shows this first, and already-published versions don't change. Discarding changes or restoring a version removes comments, and the confirm dialog says so.

Focus view (#126). A full-screen writing view in the full editor: the icon at the right of the editor's head line, or ⌘⇧↩ / Ctrl+Shift+Enter; Esc leaves. It has typewriter scrolling, controls that fade while you type, the counts in a corner, and a preview tab (⌘⌥↩ / Ctrl+Alt+Enter). Text, caret, scroll and undo history all survive the switch, and autosave keeps running.

Word count while writing (#125). The word-count extension now also shows its count beside the character count, in the composer and the full editor, through a new general draftCounter extension slot. Like the character count, it leaves comments to self out.

Extension pages can sit in the main menu (#133). page.mainMenu: { icon } links an extension page from the main menu, above compose, instead of from More. Browser only.

A quote's label is shown to readers (#136, ROADMAP row 79, decision #81). A labelled directive, ![[id | text]], bakes data-blyg-label on its blockquote. Public pages, the reader and fork flattening use it as the attribution link's text. What the link said before stays beside it, so a label never hides whose quote it is and is never shown as the quoted item's title. Unlabelled quotes bake byte-identically. The reader conformance suite goes from 74 to 79 passing.

Single-node deploys (#138). A self-host whose wrangler.private.jsonc has no env block (one target, "env": "") now passes npm test and deploy:all's cross-check. The pinned-account_id guard still applies.

Private contract, SDK and protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the releases' sections of CHANGELOG.md, which is where they are maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 8, 2026

thread

Changelog Rollup and Background Routing in Studio

A blyg is a set of living documents, not a stream of posts. Items get revised, quotes get refreshed, threads get tightened over months. That is the point of the medium, and it creates a problem every reader of a busy blyg runs into sooner or later: most of the traffic a living document generates is necessary and trivial. A typo fixed. A quoted passage brought up to date with its source. A fragment published as part of a thread, a minute before the thread itself. Each of these is a new version, and each one shows up in a feed.

Two things have to be true at once. You should be able to keep up easily with the changes that matter in documents that keep changing. And the trivial traffic, which is most of it, should get out of your way, either handled automatically or routed by rules you set yourself. Blygger Studio's next two features are built around that pair: changelog rollup, which makes the history of a document readable at a glance, and background routing, which keeps the trivial versions out of your main reading view.

Changelog rollup

Every blyg item already carries its full changelog on the wire: each version's note, its time, and whether the author pinned it. Until now, Studio showed you only the latest note. That was the right default for a stream, and the wrong one for a document you return to after a month, when the question you have is not "what changed last" but "how did this get to where it is now".

Studio 0.58.0 adds three ways to show a changelog, chosen separately for your own public item pages and for blyg items in your reader:

  • The latest note, as before.
  • The full history: every version's note, newest first, with pinned versions linked to their frozen pages.
  • An AI summary: a few sentences on how the piece has developed, written from the notes.

A summary is written from the changelog's notes only, never from the text of earlier versions. That is a deliberate limit. The protocol never makes an unpinned earlier version reachable, and a summary written from those texts would be a back door to exactly what the author chose not to keep public. Notes are public by construction and already follow that rule, so a summary of them cannot leak anything. Summaries are labelled as machine-written, with the model named, and they stay in your studio: they never enter the item's document or your feed. Each one is written once per version and kept, so a page viewed a thousand times costs one model call, and your reader writes a summary only when you open an item.

There is a writing-side half too. When you draft a change note, you can now ask for one that summarizes the full history to date, ending with this version's change. For a document with a long life, that note becomes the running account readers see first. Settings has a place for your own instructions on how roll-ups should read.

Background routing

Rollup makes important changes legible. Routing makes unimportant ones quiet. Studio's reader already has a Background view, but today it holds only withdrawn items. An earlier heads-up said it would grow; the plan now widens it to everything a reader can reasonably treat as maintenance, and gives you the controls.

The automatic rules all work from what the reader can see for itself:

  • Same text. The item was republished without a word changed.
  • Quotes refreshed. A thread brought its quoted passages up to date with their sources and changed nothing of its own. This one is common in a medium built on quotation, and easy to detect: the item's content fingerprint covers the author's text and the quote markers, not the quoted versions, so it stays the same while the quotes move.
  • A small edit. The text changed by a few characters.
  • No words of its own. A post that is nothing but quotes.
  • Superseded. The same blyg published a newer item within a few minutes, so the earlier one is bumped sideways rather than left at the top.
  • Part of a burst. Fragments published together with the thread that names them fold into that thread, which shows "+N fragments".

On top of the rules, you can move any item, or a whole blyg, to the Background yourself, and move it back from there. Your choice on an item beats your choice on a blyg, and both beat the rules. Background never marks anything read and never changes what you publish; it is a view, not a verdict. Every item in it says why it is there.

Delegated authority

The interesting question was what to do with the author's own words about a change. A note that says "minor typo fix" is useful information. It is also an easy way to bury a rewrite, and the protocol has long said that no word in a note carries meaning on the wire, so that nobody can write to a convention that clients honour.

The answer the project settled on draws a line between a client deciding something on everyone's behalf and you deciding something for yourself. Studio will not route on a note of its own accord, in either direction. But you may tell it to. A standing instruction like "if a changelog says minor, believe it; if there are signs of spam, flag it" is your own reading, delegated to an agent, the way a mail filter acts on your rules. Nothing about it reaches the wire, and the author cannot know whether any reader honours the word, so no convention forms. The instruction starts empty, any item it routes says so, and you can change it at any time. When a note's claim and the measured change disagree, say the note says "minor" and half the text changed, the item stays in front of you with a flag saying why.

The same holds on the publishing side. What a note says is the author's own, including words a client writes on the author's instruction. Studio does not police it. If a feed misrepresents its changes, that is for its readers to answer by how they read it. The one thing that stays enforced is the rule that keeps unpinned history unreachable.

An opt-in setting will let a small decision model judge other blygs' changes from the two texts, for readers who want more than measurement. It costs one call per new version of anything you read, and Settings says so.

Where this stands

Changelog rollup ships in Studio 0.58.0. Background routing is planned in four parts. The first part comes next and brings the controls, plus the change classifier's verdicts on your own items, so your own small fixes leave your reading view without any new model calls. The measured rules come second. The model, your routing instructions over notes, and the disagreement flag come third, once there is a measured change to check notes against. The burst folding that the planned inline-fragment authoring will need comes fourth.

The pace-layered home page order follows the same thinking and is now an RFC open for comment until 10 December: a version that changed nothing worth resurfacing no longer climbs, and a burst counts as one publication. Both rules exist for the same reason: a document that keeps getting better should not have to be noisy about it.

Source: docs/posts/2026-11-07-changelog-rollup-and-background-routing.md in blygger-spec, which is where revisions are made. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 8, 2026

thread

RFC-3 — The pace-layered order: what keeps mattering stays near the top

Request for comments · non-normative · OPEN FOR COMMENT until 2026-12-10 on blyg.blygger.org (#66); without a blyg, comment on blygger-spec#29 · session 61, 2026-11-07. Drafted by Opus 5.5 at Venkat Rao's request, from the reference client's plan (blygger-studio/docs/pace-layered-feed.md), its code (src/feeds/pace-layered.ts) and its fixtures (test/fixtures/feeds/). Ruled by Fable 5.1 the same session (section 7, decision #97); publishes on blyg.blygger.org with a comment period (#66, #73). Like a technical note, an RFC constrains nothing: a client that orders its home page newest first is as conformant as one that does this. When the comment period closes it becomes a technical note (#90). Written against protocol 0.4 at its eleventh revision; no pre-1.0 version promises anything (#21).

Blygger Studio has shipped this order since 0.42.0 (2026-10-11) and uses it as the default home page on a fresh install. This RFC describes it so another client can implement the same order and check it against the same fixtures. Section 7 records the four rulings, and section 8 asks implementers questions. Two of the rulings (R2, R3) changed the reference; Blygger Studio 0.58.0 builds them, and the fixtures this RFC points at are the ruled ones.

Summary

Blygger keeps time two ways. The synchronic view is what is new now: newest first, which every feed reader already shows. The diachronic view is how things change, and this order is one way to show it. Items sink as new ones arrive. They sink more slowly the more they have been pinned, and they climb a place each time they are revised. In the limit, a heavily pinned item that keeps being revised holds the top: the familiar "pinned post", reached by what the author did rather than declared by a flag.

  • It reads the wire, plus one judgement of the client's own. Every input but one is in a blyg's public files: ids and withdrawal from the index and item documents, versions and pins from each item's changelog, and quotes from version documents. The one other input is whether a version was maintenance (R2), which the client derives, as §13.2 lets every reader. A reader can order someone else's blyg as its author's client does.
  • It is a function of the publishing history, not of the clock. Time is counted in arrivals, not seconds, so the order is the same for every reader at any moment and changes only when the blyg publishes.
  • The model is the convention; the numbers are reference values. A client claiming this order implements the model in section 2. It may tune the constants in section 3 and should say so, because a fixture checks one set of constants.
  • It changes nothing on the wire. One OPTIONAL member already ruled, pinned_at (§16.9), would refine it (section 5).

1. The question

A blyg is a set of living documents, not a stream of posts. Items are revised, and the author pins the versions that matter: a pin is an irrevocable promise to serve that version forever (§8), the medium's one costly signal of significance (#19, TN-1). A newest-first home page uses none of this. It shows a blyg as a stream: last week's fragment sits above the thread the author has revised for a year and pinned four times.

The question is what order shows a blyg as a body of work. Decision #73 answered it for the reference client and asked for an RFC recommending the answer to other clients.

2. The model

Ticks. Time is counted in ticks, one each time a new item enters the order. A revision is not a tick, and neither is a pin.

Depth. Every item in the order has a depth, and the order is shallowest first. A new item enters at depth 0. On that tick, every item already in the order sinks by its layer's speed.

Layers. An item's layer is its weight, floored and capped at the deepest layer. Layer n sinks at 2^-n depth per tick, so each layer down sinks at half the speed of the one above. The reference uses six layers and gives them Stewart Brand's pace-layer names, fastest first: fashion, commerce, infrastructure, governance, culture, nature.

Weight. An item's weight is the number of its own pinned versions, plus half the weight of each item that quotes it in a pinned version, recursively, halving per hop. A pin on a thread freezes what the thread quotes, so it is evidence that the quoted item matters. Weight flows from the quoting item to the quoted one and never back: the other direction would reward quoting popular things. Because the recursion is counted over walks and bounded in hops, a cycle of quotes adds a little and then fades.

Climbing. A new version of an item already in the order moves it past the item directly above it, once per climb. The reference climbs one place per version: a revision moves an item up one place, not to the top. If the item is already at the top, it stays there. A maintenance version climbs zero (R2): one the client judged to change nothing worth resurfacing — the same text as the version before it (#77), or under the client's near-sameness threshold (#83).

Bursts. Items published together as one act are one publication (spec §13.7): a thread version and the own items it is the first to name whose first publication falls within the burst window before it. A burst takes one tick (R3): everything else sinks once, and its items enter at depth 0 together, the thread on top and its fragments beneath it in publication order. A thread already in the order comes back to the top with its burst, since the burst is a new publication and the thread is its entry. A withdrawn thread is no entry to fold into, so its fragments take their own ticks.

Withdrawal. A withdrawn item leaves the order and takes no tick. Its pinned versions still lend weight to what they quote, because pinned versions are served forever (§8) and stay on the wire after the endcap.

What it orders. A home page or any other presentation of a blyg's own items. The feed, the archive and every protocol surface are untouched: §7's feed stays an ordered list of publish events, and nothing about this order is published.

2.1 The algorithm

Replay the blyg's history in publication order, one event per version.

visible  := items that are not withdrawn
bursts   := for each visible thread version, oldest first: the own items it is the
            first to name whose first version is within BURST_WINDOW before it
events   := every (item, version) pair, sorted by version.at
            (equal times keep listing order: the index's order, oldest first,
             and an item's own versions in sequence)
for each event (item, version), in order:
    if version is pinned:
        pins[item] += 1
        for each own-origin item q this version quotes, q != item:
            quoters[q] += {item}
        recompute every layer from the weights           -- layers change from here on
    if item is not visible: continue
    if item has no depth yet and belongs to a burst: continue   -- it enters with the thread
    if (item, version) is a thread version with a burst:          -- one tick for all of it
        for each other item o with a depth: depth[o] += 2^-layer[o]
        for each member m, latest-published first: depth[m] := 0; entered[m] := next tick number
        depth[item] := 0; entered[item] := next tick number
        continue
    if item has no depth yet:                            -- a tick
        for each other item o with a depth: depth[o] += 2^-layer[o]
        depth[item] := 0; entered[item] := next tick number
    else:                                                -- a revision
        repeat climbs(version) times:
            if item is first in the order: stop
            swap depth[item] with the depth of the item directly above
            if the two depths were equal: entered[item] := next tick number
order := items with a depth, by depth ascending,
         then by entered descending (at equal depth, the later entrant is on top)

Weights are recomputed at each pin, and each tick sinks an item at its layer at that tick. A pin therefore slows an item from the moment it is counted and does not rewrite the depth it already gained. The order depends on the history alone; it does not depend on the order items are listed in when their times differ (the reference tests this on every fixture).

2.2 A worked example

Fixture 02-pinned-item-sticks.json. Item a is published with two pinned versions, giving it weight 2, layer 2 and a quarter of the base sinking speed. Then b through f arrive, one tick each. After the five ticks, a has sunk 1.25. d, two arrivals from the end, has sunk 2, and c has sunk 3. The order is f, e, a, d, c, b: a holds third place among six with nothing but two pins.

3. Reference constants

Constant Reference value What it controls
Layers 6 (Brand's names) How deep pins can slow an item
Sinking speed of layer n 2^-n per tick How much each layer down slows sinking
Weight passed per hop ½ How much a pinned quote counts toward the quoted item
Hops counted 6 How far a pin's weight travels up the quoting tree
Climb per version 1 place; 0 for a maintenance version (R2) How far a revision moves an item
Burst window 15 minutes How long before a thread its fragments may be published and still enter with it (R3)

These are values, not rules. #73's reasoning: making them normative "would make the RFC a specification of one client's taste". A client that tunes them still implements this order. It no longer matches the fixtures, which check the reference values, and it should say which values it uses.

4. Inputs: the wire, mapped

Model input Where it is on the wire
Item ids, kinds, listing order items/index.json (§6.2)
Withdrawal the item document's endcap, kind: "withdrawn" (§9)
Versions and their times the item's changelog[]: version, at (§5.2)
Pins changelog[].pinned (§5.2, §8)
Who quotes whom, per pinned version transclusions[] in items/{id}/v{n}.json, entries with no origin (own items)
Bursts the same transclusions[], with created and the thread version's at (spec §13.7)
Maintenance (R2) not on the wire: the client's own judgement, from the two texts it holds at reconciliation (same content_hash, #77; near-same, #83)

The endcap is not a version for this purpose. Quotes of other origins' items are ignored: they say nothing about this blyg's own items. Quotes in unpinned versions are ignored too, because only a pin is a promise. A reader can fetch the pinned documents it needs at the cost of one fetch per pinned version, which is the most expensive input.

The reference client builds this history from its own database (src/feeds/history.ts), but the shape it builds is exactly the wire's, so the same code could order an imported blyg. The contract is FeedHistory in src/feeds/types.ts, which is also the fixture format.

5. What the wire does not say, and pinned_at

When a version was pinned. changelog[].pinned says that a version is pinned, not when the promise was made, so the reference counts a pin from its version's publication. An item pinned a year after it was written is treated as if it had been pinned at once, and its early ticks are counted at a slower speed than the reader saw at the time.

Decision #73 ruled the missing fact as an OPTIONAL member, changelog[].pinned_at (§16.9), self-asserted and present only beside "pinned": true; absent means unknown, with the current fallback. When it is present, a client should count the pin as an event at pinned_at rather than at the version's at. This is the one change the model wants from the wire, and it is already ruled; it waits for a client to emit it (the reference client stores the time and does not publish it yet) and another to read it.

Pins on other blygs. A pin on another origin's thread that quotes this blyg is real evidence, but it is not in this blyg's files. Mentions are private to the receiver (#28), and a pin MAY re-send its mentions (§15.2, #73), but nothing requires it. The reference leaves inbound pins out, and a client that counts them is running an extension of this order, not the reference.

6. Conformance: the fixtures

Nine fixtures in blygger-spec/conformance/feeds/ (canonical, R4; Blygger Studio keeps a CI-checked copy), each a JSON object with a description, a history and the expected order, worked by hand; the directory's README gives the format:

Fixture What it checks
01-no-pins With no pins and no revisions every item sinks at one speed, so the order is newest first
02-pinned-item-sticks Two pins put an item in layer 2; it holds third place as five newer items arrive
03-versions-climb Each new version climbs past the item directly above; at the top it stays
04-one-climb One revision moves an item one place, not to the top
05-quoted-by-pinned-threads Two pinned threads each pass half a pin to the fragment they quote; at equal depth the later entrant is on top
06-withdrawn A withdrawn item takes no tick, but its pinned versions still lend weight to what they quote
07-maintenance-no-climb A maintenance version climbs zero (R2)
08-burst-one-tick A burst takes one tick: thread on top, fragments beneath in order, everything else sinks once (R3)
09-burst-window A fragment outside the burst window takes its own tick (R3)

A client claiming the order passes all nine with the reference constants. The reference suite (test/feeds.test.ts) also checks invariants the fixtures only sample: that the order does not depend on listing order; that an item pinned and revised as often as anything is published holds the top; that an unpinned item revised as often climbs only one place each time; that weight halves per hop and flows only from quoter to quoted; and that a cycle of quotes stays finite. A second client is invited to propose fixtures of its own.

7. Rulings (Fable 5.1, session 61, 2026-11-07; decision #97)

The four-question test, applied: nothing here changes what a reader, receiver or importer must do; nothing is added to the wire; pinned_at is #73's own ruled shape. Four calls were Fable's because they say what the convention is. All four are ruled as the draft recommended, with a mechanism added to R4:

  • R1, confirmed. A client implements the pace-layered order when it implements the model in section 2; the constants are reference values; the fixtures check the reference values; a client that tunes the constants still implements the order and says which values it uses.
  • R2, confirmed. A version the client treats as maintenance — the same content_hash as the version before it (#77), or under the client's own near-sameness threshold (#83) — climbs zero. Climbing a place is resurfacing in miniature, and #77 says SHOULD NOT resurface. climbFor is where it goes; one fixture.
  • R3, confirmed, and ruled together with the reader's burst rule (background-plan.md): they are §13.7's one fold seen from two sides. A burst takes one tick: its items enter at depth 0 together, the thread first and its fragments beneath it in publication order; everything else sinks once. Two fixtures.
  • R4, confirmed, with a mechanism. The canonical fixtures move to blygger-spec/conformance/feeds/. A client cannot read another repository at build time, so the reference client keeps a copy with a CI check that the two are identical, as VOICE.md is kept in two repositories.

The items as drafted, for the record:

  • R1. The model as the convention, constants as reference values (#73). Confirm that a client "implements the pace-layered order" when it implements section 2, even with tuned constants, and that the fixtures check only the reference values.
  • R2. Maintenance versions do not climb? #77 makes a same-hash republish maintenance, and #83 extends that to versions under a reader-local near-sameness threshold. The reference climbs on every version, so an agent's snapshot refresh moves an item up a place, and readers are told elsewhere to treat that version as nothing new. The draft recommends that a version a client treats as maintenance climbs zero, and that climbFor, the reference's stub for changelog-driven climbing, is where it goes. The two rulings point the same way; Fable should confirm it before the RFC recommends it.
  • R3. A burst is one tick? §13.7 lets a reader fold items published together into one publication (#78). Under the reference, one authoring act that produces many items takes a tick for each: a client that chops a document into ten fragments (bradydale.com does this today) sinks everything else by ten arrivals at once, and tangling (the studio's planned ![[+ text]]) would do the same for a thread and its fragments. The draft recommends that a burst §13.7 would fold takes one tick, with the thread entering and its fragments entering beneath it. This changes the reference, so it needs a ruling and new fixtures.
  • R4. Where the fixtures live. They are in the studio repo today. A convention other clients run belongs where they can find it without reading a client: the draft suggests blygger-spec/conformance/feeds/, beside the reader suite, with the studio reading them from there.

8. Open questions for comment

  1. The constants. Do six layers and halving speeds suit blygs that publish daily as well as ones that publish monthly? A tick-based model is indifferent to the calendar by design, but the number of layers sets how much a pin can matter.
  2. Changelog-driven climbing. Should a major revision climb further? The wire carries no category (#19), so any classification is the reader's own, derived from the two versions it holds, as #77 and #83 derive maintenance. What would a client use?
  3. Pins on other blygs. Would an ordering extension that counts inbound pins, from re-sent mentions, be worth building, given that a pin's mentions are only a MAY?
  4. The reading view. ROADMAP row 69 asks for the same order on a reader's merged reading surface. Across origins, a tick is an arrival from any subscription, and timestamps are self-asserted (§13.7), so a future-dated origin could take ticks it should not. Is a per-origin order merged by recency enough, or does the model need a cross-origin form?
  5. Presentation. Should a client show an item's layer, or the reason it sits where it does? The reference does neither. A visible layer is easy to read as a popularity score, which this order is not (no counts, #12, #13).

9. Rejected designs

  • Decay by the clock. Sinking by elapsed time would bury a slow blyg's whole front page during a quiet month, and it would make the order depend on when it is read, so two readers would see different orders of the same files. Counting arrivals makes the order a function of the history.
  • Engagement signals. Counts of readers, responses or subscriptions are not on the wire and must not be (#12, #13). Pins are the author's own costly signal, and they are public.
  • Weight flowing from the quoted to the quoter. It would reward quoting popular items, not writing items worth quoting.
  • A declared "pinned post" or sticky flag. That is significance markup on the wire, which #19 refuses. The order reaches the same place from pins and revisions.
  • Normative constants. One client's taste, made a rule (#73).

10. Relation to other documents

  • Decision #73 (v0.4-plan.md §12.1) orders this RFC, rules pinned_at and lets a pin re-send its mentions.
  • Spec 0.4: §5.2 and §8 (changelog and pins), §9 (withdrawal), §6.2 (the index), §13.2 and §13.7 (maintenance and bursts, for R2 and R3), §16.9 (pinned_at).
  • TN-1 (tn-1-versioning-and-pins.md): why pins, not version structure, carry significance. This order is one consumer of that design.
  • Reference implementation: blygger-studio 0.42.0 and later, src/feeds/, with feed_order: "pace-layered" the default on fresh installs.

Source: docs/rfcs/rfc-3-pace-layered-order.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

v1 · pinned: v1

“RFC-3 open for comment until 2026-12-10.”

Created: Nov 8, 2026

thread

Mentions: you can now name people, and find out when you've been named

Blygger Studio went from 0.54 to 0.56 over three days. The biggest change is @-mentions, so most of this post explains how they work. The rest of the highlights are at the end. Screenshots use an invented writer, Ada Ruiz, and an invented reader, Sam Okafor.

What a mention is

Type @ada while writing. When you publish, it becomes a link to Ada, under the name you gave.

That's most of it. The handle ada is your own shorthand and stays private to you. Readers see "@Ada Ruiz", linked to wherever you said Ada can be found.

A mention notifies nobody. It's closer to writing someone's name with a link than to tagging them on a social network. Nothing is sent to Ada, and no count of mentions exists anywhere.

Adding someone to your address book

Your Studio keeps an address book of people you might mention. There are three ways to add someone.

From something you're reading. This is the easy one. Find a post by the person in your reading feed.

A post by Ada in the reading feed

Open its ⋯ menu and choose add author to address book.

The menu, with "add author to address book" at the bottom

The form comes up already filled in with what the post says about its author. Check it, and choose add contact.

The form, filled in with handle ada, display name Ada Ruiz and a URL

The three fields do different jobs:

  • Handle is what you'll type after the @. It's private to you, so call people whatever you'll remember.
  • Display name is what readers see on your public page.
  • URL is where the link goes. Use wherever the person is best found: their own site or blyg first, a social profile if that's all they have.

When you subscribe. Subscribing to a blyg by hand now offers to add it, in the same sheet, right after you subscribe. Bulk imports don't ask.

By hand. Settings → Address book has the same form.

When you add someone, your Studio also reads the page at that URL for rel="me" links, which is how people list their other accounts. Those travel with the mention, invisibly (more on that below).

Writing one

Type @ and the first letters of a handle or name, and your book offers matches. Press Enter or Tab to take one.

The compose box with "@ad" typed, and a panel offering @ada, Ada Ruiz

If you type an @word that isn't in your book, it stays as plain text, and the editor warns you with a link to add a contact. An @ in an email address, a code block or a quotation is left alone.

Your draft keeps @ada. The published version gets the link:

The published sentence, with @Ada Ruiz as a link

Two things follow from that. If you fix someone's URL, the next version you publish uses the new one, and older versions keep the link they had. And this happens when you publish, so it works the same from the editor, the API or any tool that publishes through your Studio.

Finding out when someone mentions you

Since a mention notifies nobody, how would you ever know? Your own reader can look.

Reading has a new Mentions lens: items you already read that name you, with the mention highlighted and scrolled into view.

The Mentions lens, with one post and @Sam Okafor highlighted in it

It's a find, not a notification. Nobody told you, and nothing has been verified. Some limits are deliberate:

  • Only what you already read. Finding mentions in feeds you don't follow would take someone telling you, which mentions refuse, or a crawler, which is a search engine's job.
  • Only the writer's own words. A mention of you inside a post they're quoting belongs to whoever they quoted, and you'll find it when you read that post.
  • No tally. "You were mentioned 40 times" is a follower count by another name.

It matches on your author URL and your blyg's own address. So if someone mentions you at an old social profile, it won't find that unless their mention also carries one of those addresses. Listing your accounts with rel="me" on your own page helps with this, because a writer's Studio picks them up when they add you.

Older items you've imported get read in the background, so older mentions show up over a while. Items from legacy RSS feeds aren't included.

A change of words: "responses"

The tab that used to be called mentions is now responses. It lists other posts that stub, quote, fork or link to yours, and it needed a different name now that "mentions" means people. Only the label changed.

For other client authors

A mention is ordinary markup. There's no new protocol field and nothing to implement to keep working. In content_md it's a plain markdown link, and in content_html the same link wrapped in an h-card:

<span class="h-card"><a class="u-url" href="https://smallhours.example/">@<span class="p-name">Ada Ruiz</span></a><data class="u-url" value="did:web:smallhours.example"></data></span>

A reader that knows nothing about h-cards shows a working link. One that does can match the identifiers against its own contacts. Those identifiers are the publisher's claim and prove nothing, so don't merge them into a contact without checking. Item pages are also now microformats2 h-entrys, with the author as a hidden p-author h-card.

The reasoning is in TN-6. This started as RFC-1, and the comment period changed it: Mike Casey's question is why handles resolve on the server for every tool, and Aneesh Sathe's is why the Mentions lens exists.

The other highlights

In the editors

  • Fragment mode is easier to notice: the box has a light tint, and thread-only tools are greyed out instead of disappearing.
  • The character count is bolder, appears in quick edit too, and goes red with the text past 1000 in a fragment.
  • Cmd/Ctrl+B, I and K make bold, italics and a link.
  • In the full editor, the text box and the preview start level, and quotes in the preview look as they do on your public page.

Elsewhere

  • A word-count extension shows word counts in the reader, with totals for a contents thread. Operators compile it in, and owners turn it on in Settings.
  • The address book section in Settings has its own form and help text.
  • The hopper picker no longer comes up empty if you open it before the list has loaded (Kyle Mathews).

Each release has its own announcement on this blyg with full notes.

Upgrading: 0.56.0 needs migrations 0042 and 0043, applied before you deploy.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.56.0: Mentions means people now

Released 2026-11-06, the reference client. v0.56.0 on GitHub.

A Mentions lens in the reader (#134, tn-6). Reading's new lens lists items you already read whose own h-cards name you: your author URL or your blyg's address. The mention is highlighted wherever you read it, and in this lens the card scrolls to it. It is a find, not a notification: nobody told you, nothing is verified, nothing is sent, and it shows no tally. Quotes of someone else's words don't count, feeds you don't read aren't searched, and legacy RSS items aren't indexed. Items imported earlier are read by a backfill, 500 every 15 minutes, so older mentions appear over a while.

The old mentions tab is now "responses". Only the label changes: /mentions, the API and the protocol's own term stay.

Private contract 5.7.0 (additive: mentions=true on GET /reading and /reading/summary); SDK 0.13.0. Protocol version unchanged ("0.4").

Migrations: 0043 (imported_mentions, imported_mentions_backfill). Apply it before deploying.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.55.3: Item pages say who wrote them, to software

Released 2026-11-06, the reference client. v0.55.3 on GitHub.

Item pages are microformats2 h-entries (#132, tn-6). Live and pinned-version pages mark up the URL, date, content and author, with the byline as a p-author h-card, so a parser gets the author and any mentions from one read. It is hidden, so pages look as they did. It is page markup only: nothing reaches item documents or feeds.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none. A node coming from before 0.55.0 needs 0042.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.55.2: Knowing which mode you are in, and the editors' keyboard

Released 2026-11-06, the reference client. v0.55.2 on GitHub.

Fragment or thread at a glance (#128). In the composer, full editor and quick edit, a fragment's box takes a light tint of the theme's accent. Thread-only tools stay in the row, greyed, so nothing shifts when the kind changes. The count is bolder and now appears in quick edit; past 1000 in a fragment, it and the text go red. The full editor's count never went red before: a stylesheet rule cancelled it.

Bold, italics and links from the keyboard (#129). Cmd/Ctrl+B, I and K in all three editors. Pressing again takes the formatting off, and undo works. Macs use Cmd only, so Ctrl+B and Ctrl+K keep their system meanings.

The full editor's panes start level, and its preview's quotes look like the public page's (#130). The toolbar sits above both panes. Quotes take the public styling, and a thread preview shows the line under each one.

Subscribing stays in one sheet (#127). After subscribing to a blyg, the sheet carries on to the address book offer instead of closing and opening another.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.55.1: The address book meets you where you find people

Released 2026-11-06, the reference client. v0.55.1 on GitHub.

Subscribing offers the blyg (#124). Subscribe to one blyg by hand and the Studio asks "Add this blyg to address book?", filled in from its manifest. It doesn't ask for OPML imports, RSS feeds or hopper subscriptions, or when the URL is already in the book.

The reading menu's "add author to address book" does the same for an entry's author.

Help text on each field, and the address book has its own form. It used to sit inside the settings form, so "save settings" sat beside it and did nothing for it, and Enter would have saved settings. "Name" is now "Display name".

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.55.0: An address book, and @mentions that become links at publish

Released 2026-11-06, the reference client. v0.55.0 on GitHub.

Type @handle while writing (#123, tn-6). Add people in Settings → Address book. At publish, a handle that names a contact becomes a link in content_md and an h-card in content_html, on every write path: the editor, the API and any tool. Your working copy keeps the @handle. A handle that names nobody stays plain text, and publish and preview return it as unresolvedHandles, with a warning in the editor.

A mention notifies nobody. Nothing new reaches the wire: no member, no relation, nothing sent.

Adding a contact reads their page for rel="me" links, and those identifiers travel with the mention. Identifiers added by hand or through the API stay in the book and never go on the wire. A contact needs an https URL for now.

Private contract 5.6.0 (additive: /contacts, POST /contacts/{id}/resolve, unresolvedHandles); SDK 0.12.0. Protocol version unchanged ("0.4").

Migrations: 0042 (contacts). Apply it before deploying.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

Blygger Studio 0.54.1: One theme colour at the door, and mention identifiers survive import

Released 2026-11-05, the reference client. v0.54.1 on GitHub.

The themed login page carries one theme-color tag. It had the default and the theme's, so which one a browser used was up to the browser.

Imported HTML keeps <data value>. A mention's alternate identifiers travel in <data class="u-url" value="…"> (tn-6 section 5.3), and the sanitizer used to unwrap them. value is allowed on <data> only. It is inert text and is never fetched. Nothing in the Studio writes this markup yet.

Private contract and SDK unchanged. Protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 7, 2026

thread

RFC-5 — Blygger inside an organisation: one audience per origin, a boundary the publisher enforces

Request for comments · non-normative · OPEN FOR COMMENT until 2026-12-03 on blyg.blygger.org (#66); without a blyg, comment on blygger-spec#27 · session 59–60, 2026-11-04/05. Drafted by Opus 5.5 (session 59) at Venkat Rao's request as research only: no code, no client change. Edited and ruled by Fable 5.1 (session 60), whose rulings are section 10. Like a technical note, an RFC constrains nothing. When the comment period closes it becomes a technical note, for people building enterprise products on Blygger (decision #90: the close is the promotion, and the first build is a revision trigger). It is about the protocol and about what any client serving enterprise use has to handle. An enterprise product is expected to be a client of its own, so it describes no particular client. Written against protocol 0.4 at its tenth revision, which carries the sentences F1 and F5 add; no pre-1.0 version promises anything (#21).

Five questions in this RFC needed Fable under the four-question test (F1–F5). Section 6 states each item, with the test as it was applied, and section 10 rules it.

Summary

The protocol has no fundamental blocker for enterprise use. Nothing on the wire assumes public DNS or the public internet. An origin is a URL string. Resolution and verification are fetches. Every fetch failure already degrades safely: a poll failure discards nothing (§12.3), and an unreachable source is a failed mention (§15.4). The blyg: namespace URI is an opaque token that is never fetched (§7).

Three things need care, and only one of them is a missing capability:

  1. One audience per origin. A whole origin behind SSO or a private network works today. Different readers seeing different items within one origin is L3, which #7 defers. Enterprises get audiences by running one origin per audience: the N-origins group shape, tn-3 shape A. This is the missing capability (F1, F4).
  2. References leak across a boundary. A quote bakes the bytes. Every reference carries an origin string, and cited can carry an excerpt. A sent mention POSTs the internal URL to the outside receiver. The protocol permits all of this. An enterprise client has to refuse it at publish time (F3).
  3. Retention law runs against two promises the medium makes: published documents answer 200 forever, and pins are irrevocable (F5).

Everything else is client work, and section 4 lists it: SSO and roles, reader credentials, egress policy, audit and retention, hosting and residency, AI controls, and the publish-time boundary.

1. The question

Venkat asked whether anything fundamental stops Blygger being used as an enterprise tool, deployed inside an organisation's boundary with the usual enterprise features: SSO, an internal DNS scope, private networks, audit, retention.

The answer matters beyond enterprises. The protocol's claim is that anything able to serve files can host a blyg (§1). An intranet file server can serve files. If the claim held only on the public internet, it would be narrower than it says.

plans/private-items-proposal.md §8 (same session) recorded Venkat's answer that "enterprise deployments are under discussion" and are the concrete case likely to open L3. This RFC is the enterprise half of that thread. It does not repeat the private-items design. It asks what an enterprise needs before L3, and whether L3 is on its critical path.

2. Deployment shapes

Shape What it is Audience per origin Protocol status
A. Fully internal Every blyg sits on an internal DNS zone (for example under .internal, which ICANN reserved for private use in 2024) or behind a gateway. Nothing is reachable from outside. uniform (employees) conformant today, given F1
B. Internal plus selectively public Some origins internal, some public: a public engineering blog next to internal team blygs. uniform per origin; different origins, different audiences conformant today; the boundary between origins is F3
C. Mixed federation Internal blygs subscribe to and quote public blygs, and the reverse is attempted. as B inbound (public → internal) is safe; outbound is F3
D. Vendor multi-tenant hosting A vendor hosts many organisations' blygs, each tenant one or more origins. uniform per origin conformant today: #14, #36, #61, #84 make N origins on one host safe
E. Per-item audiences in one origin One team blyg where some items are for the team, some for the company, some public. mixed L3 (#7). Not available.

Shapes A–D need no new protocol. Shape E is the only one that does, and the recommendation in section 3.3 is to build A–D first and treat E as the measured need that opens L3 (F4).

Shape B is "promotion" by publishing anew. Withdrawal is the only exit from public (#8), and an origin's audience never changes (F1). So an internal item does not become public. Its author publishes a new item in the public origin. Whether that new item may name its internal ancestor is F3: forked_from or a quote would carry the internal origin string outward.

3. Protocol analysis: is anything blocking?

Each claim below is checked against the 0.4 text, not assumed.

3.1 Nothing assumes public DNS

Construct What it needs Internal origin?
Origin, identity origin (§2, §12.2, #14, #17) an absolute base URL; identity is the final fetch URL minus its last segment Fine. No rule requires a publicly resolvable name. §12.1 step 1 expects HTTPS; an internal CA is a transport matter.
Reference shape (§5.9) {origin, id, version} as strings Fine as data. A reader outside cannot check staleness, which §12.3 already treats as an ordinary failure.
content_html absolute URLs (§5.2, #53) every URL in the content absolute Fine inside. A baked copy taken outside carries internal hostnames with it (section 3.2).
Namespace URI https://blygger.org/ns/0.1 (§7) "an opaque wire token" Fine. Never fetched, so an air-gapped reader needs no access to blygger.org.
generator_url (§6.1) informative, MUST NOT gate Fine.
Resolution (§12.1) at most six fetches from the reader's network position Fine for any reader that can reach the origin.
Verification (§15.4) the receiver fetches the source from its asserted origin Fine when the receiver can reach the source. Otherwise failed, which is honest (F2).
Webmention endpoint (§15.1) optional at every level Fine. A static internal blyg omits it (§15.7).
CORS (§4) Access-Control-Allow-Origin: * is a SHOULD Fine. A gated origin answers credentialed CORS instead; the SHOULD bends for a stated reason.
Census (§3.2) "the manifest is a file the protocol requires to be public" Wording only. The census simply never sees internal blygs. "Public" here means the same bytes to every reader who can reach the origin (F1, ruled in section 10; §4 now says so).

One hazard to rule out: split-horizon DNS for a blyg origin. If one name resolves to an internal server inside the network and a different server outside, then "the item at that origin" depends on where the reader stands. That breaks §12.2's guarantee that two readers given the same URL arrive at the same identity, and it reproduces per-reader content under one origin, which is shape E by the back door. Internal origins should use names that do not exist publicly. Section 8 lists this as a rejected design.

3.2 References across the boundary

Every cross-origin construct carries the target's origin string, and two of them carry words:

  • A quote bakes bytes. §10.2 bakes the publisher's local snapshot into content_html. §10.4 says the snapshot survives anything the source does, and §14 says so plainly ("anything published can be quoted into a thread whose snapshot its publisher cannot recall"). A quote of an internal item into a public blyg copies the internal text, and its internal absolute links (#53), out of the boundary for good.
  • A cited object (§5.9) may carry an excerpt and a url, so even a bare stub_of or forked_from can carry words.
  • Origin strings alone leak internal hostnames, mount paths and item ids. That is true of stub_of, forked_from, links[] (§10.3a), transclusions[] and generated[].sources[] (§5.7).
  • A sent mention leaks in the other direction. §15.2 says a publisher SHOULD send a mention for every remote reference. From an internal blyg that quotes a public one, the POST hands the public receiver the internal page URL as source. The receiver then tries to fetch it: the fetch fails (good), but it has learned the hostname and the fact of the quote (bad).
  • Generation is a quote by model. A TK span drawing on an internal item, published publicly, carries the internal origin in generated[].sources[] and paraphrased content in the text. The 0.4 rationale for the source relation, that "paraphrase by model must not be the one way to use a stranger's words without telling them", cuts the same way here.

None of this is a protocol defect. The protocol is a public-speech medium, and quoting is its primitive (#12). It does mean that the boundary is enforced by the publisher at publish time, or not at all. No reader-side or wire-side mechanism can recall a baked quote. That is the same conclusion private-items-proposal.md §3.4 reached for private items, generalised from "private versus public" to "narrower versus wider audience".

The rule a boundary-aware client applies:

A version published at an origin with audience W may carry no reference (of any kind, cited included) to an origin whose audience is narrower than W, and sends no mention to a receiver outside the audience of its own origin.

The audiences are client configuration: a list of origin prefixes per audience. Both halves are within what the spec already permits. Refusing to quote is a publish error the client chooses. Not sending a mention is a SHOULD the client declines for a stated reason. The spec says nothing more (F3, ruled in section 10): §14 already carries the sentence that matters, "anything published can be quoted into a thread whose snapshot its publisher cannot recall", and the rule above is client guidance in this note.

3.3 "Readable only by members": static, L1/L2, or L3?

The distinction that settles this is where the audience boundary falls.

  • Origin-uniform audience. The whole surface (manifest, feed, index, item documents, pins, media, pages) sits behind one gate: a private network, a VPN, an identity-aware proxy, Cloudflare Access. Everything inside the gate is plain static files, every reader who passes the gate sees the same bytes, and §4's 404/200 rules hold for every such reader. The gate is transport, like TLS. This is conformant at L1 and L2 and needs nothing new (F1, confirmed in section 10). §4 now says it in one sentence: "What an origin serves does not depend on who asks: every reader who can reach it gets the same bytes, and reachability is the deployment's."
  • Per-item or per-reader audience in one origin. Two readers asking for the same items/{id}.json get different answers (200 versus 401/404, or full versus redacted content). That is the gate private-items-proposal.md §5 analyses as C1–C3. Section 10 classifies them: C2 is refused, C3 is where an L3 round starts, and C1 is client territory under one invariant. The proposal's "not an option", a gated page over an open JSON, applies here too.

So an enterprise gets members-only reading today by running one origin per audience behind a gate. A company-wide blyg, a team blyg and a public blyg are three origins, on one host if it likes (tn-3 shape A). The cost is the one tn-3 names: N origins, N archives, N sets of pins.

What this does not give is an item that is team-only today and company-wide tomorrow: the publish-anew path (section 2). That is where L3, or a studio-side cross-origin "promote" with honest lineage, would earn its cost. Section 10 rules it the trigger for L3 (F4), measured when a deployment hits that cost with a named case.

3.4 Reader side

  • Readers must reach the origin. A subscribing studio behind the gate needs network reach and, when the gate is identity-aware, a machine credential (a service token, mTLS, workload identity) for each gated origin. That credential is transport. The protocol has no opinion on request headers, and §12.3's polling rules are unchanged. It is client work (section 4.2).
  • Failures are already safe. A reader that loses access keeps its stored state and backs off (§12.3). It never treats 401 as withdrawal, because only an endcap is withdrawal (§13.4).
  • Sanitize-at-render is unchanged (§14). The internal-content risk is egress, not rendering.
  • Retention follows the origin (§13.4). A records system that keeps withdrawn content because the law requires it acts outside the protocol, and keeps the archive off every surface the spec governs (F5, ruled in section 10). §14 now says: "Law may compel a publisher to remove what it promised to serve, or a reader to retain what an origin withdrew. Both are acts outside the protocol: a compelled removal is a 404 with no marker, and a compelled retention never reaches any surface this document governs."

3.5 Identity and SSO

Invariant 4 and #11 say that identity is never in the protocol, and that the only authenticated entity is the origin. This helps enterprise use rather than blocking it. The protocol takes no position on how an owner, an editor or a reader proves who they are, so SSO is entirely the client's:

  • Write side. §14's last bullet and §16.6 put authoring auth out of scope, and #31 rules out a normative write surface. A client's authoring auth is its own; an IdP session can be its root credential. The pattern #31 recommends (scoped, owner-revocable tokens for tools, a root credential no tool holds) carries over unchanged.
  • Bylines. An SSO-backed studio can assert verified employee bylines (author.name, author.url pointing to an internal directory profile). #35's rel="me" proof works inside the network exactly as outside. RFC-1's ids and address book apply unchanged. Bylines are still the origin's claim (§5.5), which inside one organisation is the right trust model.
  • Multi-author. The invariant is single publisher per origin, not single author (#11). A team blyg with many SSO users is tn-3 shape B, the masthead. #36's test, "who can withdraw", decides between shape A and shape B per team.
  • Reader identity. This is where SSO touches the protocol, and only in shape E, where a group needs named readers. That is F4, and #11 calls it out ("keys imply identity").

3.6 Verdict

Item Kind Where
Public DNS or internet assumed anywhere none found 3.1
Whole-origin gating (SSO proxy, private network) interpretation; one §4 sentence F1, ruled, §10
Verification when the source is unreachable interpretation, small F2, ruled, §10
Cross-boundary quoting and reference leakage client rule, no spec text F3, ruled, §10
Per-item audiences in one origin missing capability (L3) F4, ruled, §10
Compelled deletion; compliance archives of others' content out of protocol; one §14 sentence F5, ruled, §10
SSO, roles, audit, residency, egress, AI controls, DLP client and product work 4

4. Concerns for clients serving enterprise use

The protocol governs only the published surface (#3). Everything below is the client's business. It is listed so that implementers see the whole job, and so that two enterprise clients can make compatible choices where they touch.

4.1 Authoring identity: SSO and roles

  • The organisation's IdP (OIDC, or SAML through a broker) is the root credential. No tool holds it; tools get scoped, revocable tokens (the pattern of #31).
  • Many people may author in one origin. The protocol needs one publisher per origin, not one author (#11), so a team blyg is tn-3 shape B with bylines, or shape A with one origin per member. #36's test, "who can withdraw", decides between them.
  • IdP groups map onto the client's roles. Deprovisioning (SCIM or equivalent) revokes a departing user's sessions and tokens.
  • Verified bylines: author.url can point at the internal directory profile, and #35's rel="me" proof works inside the network as outside.

4.2 Reading gated origins

  • Gate the whole surface (manifest, feed, index, item documents, pins, media, pages) with one gate, so that every reader past it gets the same bytes (F1). Gating only the HTML leaves the full text in the JSON.
  • A subscribing client needs a machine credential per gated origin (service token, mTLS, workload identity). Attach it only on an exact origin-prefix match, and never follow a redirect with it to another origin: §12.2 allows cross-host redirects, and a credential that follows one leaks.
  • Caches must be keyed so that nothing cached for one audience is served to another.

4.3 Network reach and egress

  • Internal names. A client fetches manifests, feeds and documents (§12), and a receiver fetches mention sources (§15.4). Inside the network those names often exist only in internal DNS, and a resolver that consults public DNS will not find them.
  • The probe risk. §14 asks receivers to refuse private-network addresses where they could be used to probe them. The Webmention endpoint is the dangerous one: anyone who can POST to it chooses a URL for the receiver to fetch. An internal deployment needs an allowlist (host suffixes or origins, plus address ranges), not a switch that turns the check off, and the endpoint should fetch allowlisted sources only for claims that arrived from inside (F2).
  • Air gaps. In an air-gapped deployment, no feature may reach a public host: CDN scripts, update checks, embeds, hosted AI providers.
  • Rebinding. A resolve-then-fetch check does not pin the connection. Enforce egress at the network boundary as well.

4.4 Audit, retention and legal hold

  • Audit. An append-only, exportable log of sign-ins, token grants and revocations, publish, withdraw and pin, visibility and settings changes, subscriptions, outbound mentions, and AI calls (model and provider; not prompt text by default).
  • Legal hold mostly comes free on the published side: withdraw-not-delete (#8) keeps every published version, and pins keep their bytes. The gaps are unpublished material (drafts, private items, media), which a hold must turn from deletes into soft deletes.
  • Retention schedules and compelled deletion run the other way. A records policy, a court order or an erasure request can require removing a published item that §4 promised would answer 200 forever and a pin promised to keep (§8). The removal is an act outside the protocol: the document answers 404, with no status code, marker or reason (F5, ruled in section 10; the §14 sentence is quoted in section 3.4).
  • Archives of external content. Keeping other origins' withdrawn content because the law requires it is outside the protocol too. A client that is both reader and archive keeps the archive off every surface the spec governs: no presentation, no re-serving, no quote from it (§13.4, F5).

4.5 Hosting and data residency

The protocol is host-neutral: any server that can serve the files conforms (§4), so the published surface can sit on an internal file server behind any gate. It loses only the Webmention endpoint, which is optional (§15.7). Where the authoring side runs, and where its data lives, is the client's design. Residency is a property of that design and of its hosts.

4.6 AI provider controls

AI is never in the protocol (#5). An enterprise client needs:

  • an operator-controlled list of allowed models and providers, with no free-entry way around it;
  • the ability to point at an internal gateway;
  • AI calls inside the egress policy;
  • the boundary rule (section 3.2) applied to generation sources, since a TK source from a narrower audience is a cross-boundary reference.

4.7 The publish-time boundary (DLP)

This is F3, and the most important enterprise control. Section 10 rules that it is client policy with no spec text: declining a SHOULD for a stated reason is what SHOULD means, and §14 already warns that anything published can be quoted out of its publisher's reach. Revisit only if two boundary-building clients disagree.

  • Audiences are configuration: named sets of origin prefixes.
  • Publish block. A version may carry no reference (transclusions, stub_of, forked_from, links[], generated[].sources[], cited) to an origin narrower than its own. Say which references block, and offer to remove them. This is the same block plans/private-items-proposal.md §3.4 describes for private items, keyed on audience.
  • Mentions. Send none to a receiver outside the origin's own audience, and show the author why the §15.2 SHOULD was declined.
  • Content scan. Optionally, check content_html for absolute URLs under narrower origins (#53 makes them easy to find): a plain link leaks a hostname.
  • Egress as backstop. A wider-audience deployment that cannot fetch a narrower origin cannot quote it either.

4.8 Multi-tenant hosting

N origins on one host are safe on the wire: #61 stops one tenant's documents verifying in another's name, #84 makes target membership exact, and #87 fixes the manifest name at every identity. Each tenant is the publisher of its origins (#11), not the vendor. Isolation of data, egress policy, audit and IdP per tenant is the vendor's design.

5. Wire impact

None. F1 and F5 are each one sentence in the living 0.4 text that readers already handle; F2 and F3 add nothing; F4's shape E stays L3. Shapes A–D use only existing constructs, and the boundary rule is a client publish error and a declined SHOULD.

6. The five items and their tests

The four questions are those in CLAUDE.md → Model routing: (1) readers must change; (2) reader-visible addition; (3) narrows, widens or reinterprets a locked decision; (4) a locked decision already settles it. The items are kept as the record of the test as the draft applied it; each Proposal now opens with the ruling.

F1. Audience is a property of the origin.

  • Proposal: Ruled, section 10: confirmed, with one sentence in §4. The draft: the spec governs the bytes an origin serves to whoever can reach it. Reachability, including an identity-aware gate across the whole surface, is deployment. A gated origin conforms at L1 and L2, provided that every reader who passes the gate gets the same bytes. Per-reader difference within an origin stays L3. §3.2's "required to be public" reads as "served to its audience". A blyg origin MUST NOT be split-horizon.
  • Test: Q1 no. Q2 no. Q3 yes: it reads #1 and #7 ("privileged-group access is deferred to L3") as being about per-item audiences, not whole-origin ones, and that is an interpretation Opus should not make alone. Q4: #3 and #14 point the same way, but do not settle it.
  • Touches: #1, #3, #7, #14, #17; §3, §3.2, §4 (200 forever, CORS), §12.2, §16.7.

F2. Verification across a network boundary.

  • Proposal: Ruled, section 10: confirmed, no text. The draft: a mention whose source the receiver cannot fetch is failed, with no new state. §14's "refusal to fetch private-network addresses where the deployment could be used to probe them" is met by a deployment-scoped allowlist, because internal fetches that the deployment intends are not probes.
  • Test: Q1 no. Q2 no. Q3 maybe: it reads §14's private-network SHOULD as configurable. Q4: #28 and #61 settle the mechanics, but not §14's wording. Small.
  • Touches: #13, #28, #61, #84; §14, §15.2, §15.4.

F3. References that cross a boundary.

  • Proposal: Ruled, section 10: confirmed as client policy, no text. The draft: client policy in this RFC (section 3.2's rule), with no spec text yet. Revisit only if a second client builds a boundary and the two disagree.
  • Test: Q1 no and Q2 no while it stays client policy. Q3 maybe: declining §15.2's SHOULD wholesale for a class of receivers, and a publish error the spec does not list in §10.2 step 3. Q4: #3 lets the client refuse anything at publish. If Fable wants a sentence in §14 ("a quote is an export"), that is spec text.
  • Touches: #9, #12, #26, #53; §5.6, §5.7, §5.9 cited, §10.2, §10.3a, §14, §15.2; private-items-proposal.md §3.4.

F4. Group visibility is L3, and is enterprise its trigger?

  • Proposal: Ruled, section 10: confirmed, with C1–C3 classified. The draft: enterprise does not need L3 to start (section 3.3). Shape E is the trigger, measured when a deployment hits the publish-anew cost in practice. Until then, group tokens wait, as private-items-proposal.md §8.3 says.
  • Test: any form of shape E is Q1, Q2 and Q3 yes (C2), or Q3 yes (C1).
  • Touches: #1, #7, #11, #35, #43; §3, §4, §16.7; private-items-proposal.md §5, §8.3; backlog L3 row.

F5. Compelled removal and compliance retention.

  • Proposal: Ruled, section 10: a sentence in §14, no marker. The draft: say in §14 that a legally compelled removal is an out-of-protocol act. The origin breaks a promise and readers see a 404, which §12.3 already tolerates. Add no status code or marker. For the reader side, ask whether a non-presenting compliance archive is "hoarding" under §13.4.
  • Test: a §14 sentence is Q1 no, Q2 no, Q3 yes (it qualifies #8's "200 forever" and the irrevocable pin). A marker such as 410 with a reason would be Q1 and Q2 yes.
  • Touches: #8; §4, §8, §9, §13.4, §14.

7. Open questions for comment

For implementers building enterprise products on Blygger. F1–F5 are ruled (section 10); these questions are about what implementers need, and where an answer bears on a ruling it says which.

  1. Is one origin per audience enough? Name the case where publishing anew across audiences fails you. That case is what opens L3 (F4).
  2. Reader credentials. How should a subscribing client authenticate to a gated origin: service tokens, mTLS, workload identity, something else? Is a shared convention worth an RFC, or is it each product's business?
  3. Outbound mentions from inside. Should an internal blyg ever notify a public one that it quoted it? If so, under what explicit act?
  4. Promotion. When an internal item is republished publicly, should the public item name its internal ancestor (leaking the origin), carry a public lineage note, or carry nothing?
  5. Retention. Which do you need: compelled deletion of published items, legal hold over drafts, a compliance archive of external content, or all three? Does the §14 sentence (F5) cover what you need to build, and if not, what else do you need — legal hold on drafts, archives, something the sentence does not reach?
  6. Hosting. Where must the authoring side run, and what residency do your buyers need?
  7. Audit. Which events, which format, which sink?
  8. Teams. For your users, is a team blyg shape A (members' own origins) or shape B (one masthead)? Who withdraws?
  9. Should the boundary rule (section 3.2) ever become spec text? It is client policy today (F3); name the disagreement between two clients that would change that.

8. Rejected designs

Recorded because each will be proposed.

  1. Split-horizon blyg origins. One name, two servers, two contents. This breaks §12.2's determinism and is per-reader content under one origin (section 3.1).
  2. Gating the HTML pages only. The JSON carries the full text (private-items proposal §5, "not an option").
  3. A 401 or 403 on chosen item documents within an otherwise readable origin. This is C2. §4 has no third answer, and §15.4 cannot verify against it. It is L3.
  4. Turning private-network refusal off wholesale for an internal deployment. It works, and it makes the Webmention endpoint an internal fetch proxy for anyone who can reach it. Use an allowlist (section 4.3).
  5. An enterprise "audience" member in the manifest or item documents. Readers cannot act on it without identity, which is #11's line. Audience is the client's configuration plus the gate.
  6. A removal marker (a 410 with a reason, a tombstone). A removal marker is the tombstone #8 refused, and a delete signal invites delete requests. A compelled removal is a 404 with no marker, which readers already tolerate (§12.3; F5, section 10).

9. Relation to other documents

  • plans/private-items-proposal.md: the owner-only level and its publish block. This RFC generalises that block to audiences (section 4.7) and supplies F4's trigger framing for its §8.3.
  • docs/notes/tn-3-groups-and-aggregation.md: shapes A and B are the enterprise team shapes.
  • docs/notes/tn-6-mentions-and-identifier-schemes.md (formerly RFC-1): bylines, ids and agent members under SSO (section 3.5).
  • docs/notes/tn-7-comments-sections.md (formerly RFC-2): hosted commenters, which inside an organisation are SSO users commenting through the house's comments origin.

10. Rulings (Fable 5.1, session 60, 2026-11-05)

The draft closed with five items for Fable. The rulings follow, each with the principle it rests on. All five confirm the draft's direction; F4 adds a classification the draft did not make, and F5 settles the reader side the draft left as a question.

F1. Audience is a property of the origin — confirmed, with spec text. Decision #1 makes the protocol a static file contract, and #14 makes an origin any absolute URL; nothing in the text requires that an origin be publicly reachable. "Public" in #7 and in §3.2 means the same bytes to every reader who can reach the origin. Reachability is deployment, like TLS. Per-reader difference within one origin is L3 (#7), and a split-horizon origin is that difference by the back door, because it breaks §12.2's determinism. The tenth revision of 0.4 adds the sentence to §4: "What an origin serves does not depend on who asks: every reader who can reach it gets the same bytes, and reachability is the deployment's."

F2. Verification across a network boundary — confirmed, no text. §14's clause is already conditional: it asks for refusal "where the deployment could be used to probe them". A fetch the deployment intends, under an allowlist, is not a probe. A source the receiver cannot reach is failed (§15.4), which is honest: the receiver could not verify it.

F3. References that cross a boundary — confirmed as client policy, no text. §14 already says the sentence the draft wanted: "anything published can be quoted into a thread whose snapshot its publisher cannot recall". The boundary rule (section 3.2: no reference of any kind, cited included, to a narrower origin; no mention to a receiver outside the origin's audience) lives in this note as client guidance. Declining a SHOULD for a stated reason is what SHOULD means, so a client that withholds §15.2's mentions across the boundary conforms. Revisit only if two boundary-building clients disagree.

F4. Group visibility is L3 — confirmed, and the three shapes classified. Enterprise does not need L3 to start. Shape E is the trigger, measured when a deployment has hit the publish-anew cost with a named case. Of the private-items proposal's three gate shapes:

  • C2 (a 401 or 403 on chosen documents, under any gate descriptor) is refused. It is not static, and it is L3 by the back door.
  • C3 (encrypted static content) is the shape the L3 round starts from when the trigger fires.
  • C1 (a redacted wire, with a fuller rendition served off the mount to signed-in readers) is client territory under #3, not L3, under one invariant: nothing on the protocol surface may name, link to or depend on the fuller rendition, and the public document is complete in itself. The redaction is the author's own visible edit (#78). That is a paywalled newsletter beside a blyg, which the protocol has never forbidden.

F5. Compelled removal and compliance retention — a sentence in §14, no marker. "200 forever" and the irrevocable pin are the publisher's promises. Law may force the publisher to break them, and the protocol does not legislate the law. Readers already tolerate a 404 (§12.3). There is no status code and no reason: a removal marker is the tombstone #8 refused, and a delete signal invites delete requests (section 8, item 6). On the reader side, §13.4 governs what a conformant reader presents and re-serves. A records system that retains under law is outside the protocol in the same way, and a client that is both reader and archive keeps the archive off every surface the spec governs. The tenth revision of 0.4 adds to §14: "Law may compel a publisher to remove what it promised to serve, or a reader to retain what an origin withdrew. Both are acts outside the protocol: a compelled removal is a 404 with no marker, and a compelled retention never reaches any surface this document governs."

What happens next. Published for comment under #66 on 2026-11-05; the period closes on 2026-12-03 (four weeks). Decision #93 records the five rulings, with this section as their reasoning (v0.4-plan.md §18). Comments are stubs on the item, and counter-proposals are forks of the pin.

Source: docs/rfcs/rfc-5-enterprise-deployment.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

v1 · pinned: v1

“RFC-5 open for comment until 2026-12-03.”

Created: Nov 5, 2026

thread

Blygger Studio 0.54.0: Word counts, a hopper picker that waits for its list

Released 2026-11-05, the reference client. v0.54.0 on GitHub.

The word-count extension (#117). Each reading entry's byline shows its word count, published and in draft. A thread whose outline forms a clean tree (list items that are nothing but [[id]] links, as a table of contents is written) also gets the words in the whole document under it, again on both sides. Inline links and transclusions are not followed. A cycle, a repeated item, a link to anything that is not one of your own items, or a tree over 500 items gives no total, and the tooltip says why. It has a server half, so releases don't carry it: compile it in through extensions.local.json, then turn it on in Settings → extensions. Nothing reaches the wire. docs/extensions.md has the rule.

The editor's "add to hopper…" picker waits for its list (Kyle Mathews, #122). Opening the actions menu before the hopper list had loaded could offer only "new hopper…", because the menu kept the empty list it started with. The Mentions half of #118 is still open.

A test that expired. classifyLinks compared its cache's age with the wall clock rather than the now it was given, so test/peek.test.ts began to fail on 2026-11-05 on every checkout. No effect on a running node.

Private contract 5.5.0 (additive: GET /api/ext/word-count/counts, which answers 404 unless the extension is compiled in and enabled); SDK 0.11.0. Protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 5, 2026

thread

Two studio releases, and planning for private posts and enterprise use

Blygger Studio 0.52.0 and 0.53.0 shipped on 2026-11-04, and both are live on the four reference nodes. The day also started two planning threads: private posts, and Blygger inside organisations. This post summarises both. The full record is the program devlog.

Faster reading, and reads that cost less

0.52.0 is mostly about the reader using less of the database.

  • Batched reads (Kyle Mathews, studio#114). Independent reads on a studio page now travel together in one request. On the server, the database statements in each batch share calls. Mentions opens with 10 posts and 10 mentions each. In review, the browser half turned out to wait on a timer, which browsers throttle in background tabs; Kyle switched it to dispatch without timers before it merged.
  • Two table scans removed (studio#113, reported by patwater, fixed in #115). On Cloudflare's free plan, database rows read count against a daily limit, and one owner's reader was using it up. The main cause, the inbox ordering, was fixed in 0.49.12, so nodes older than that should upgrade. The report also surfaced two lookups that still read whole tables: finding an item you follow by its id, and listing which collections each reading entry is in. Both now use an index.
  • Collections without your own collection feeds (Aneesh Sathe, studio#112). You can subscribe to another blyg's public collection whether or not your node publishes collection feeds of its own.

Search, and studios you can tell apart

0.53.0 adds things you can see.

  • Search on the reading and compose pages (studio#120). It is the same search the [[ picker runs. Type in the box at the top, and the results replace the list. The search goes in the address, so the back button returns to your results. On the reading page, it searches the source you have selected, with a button to widen it. On the compose page, it searches your own blyg by default, drafts included.
  • The login page wears your blyg's theme (studio#119). It used to be the studio's default blue.
  • Each studio's browser tab says which blyg it is (studio#121). The title names the blyg, and the ❝ icon takes the theme's accent colour. If you run several blygs, you can now tell the tabs apart without clicking in.
  • Read batches are more robust (Kyle Mathews, studio#116). A malformed address in one read no longer fails the reads around it.

Both releases have announcements on this blyg with their full notes. The release posts for 0.49.1, 0.49.12, 0.50.0 and 0.51.0, which had been missed, went up the same day.

Planning: private posts

A private level for posts is being worked out. It is for finished work you haven't decided whether to publish. The current shape, from an exploration in blygger-spec (plans/private-items-proposal.md):

  • Visibility goes user / group / public, like Unix permissions, and is separate from draft. A private post can have versions and pending changes like a public one. Only public posts are ever served.
  • A private post can be quoted and linked from your own drafts and private posts. Publishing anything that refers to it is blocked until you remove the reference or make the private post public first.
  • Group (a named set of readers) is the protocol's deferred privileged-access level. It waits for a design round of its own.
  • One question goes to the protocol's design review: when a post that reached its third private version goes public, does it start at version 1 on the wire?

Nothing is built yet.

Planning: Blygger inside organisations

A draft RFC asks whether anything fundamental stops Blygger being used inside an organisation: on an internal network, behind single sign-on, under retention rules. The short answer is no, not at the protocol level.

  • Nothing in the protocol assumes the public internet. A blyg on an internal network, or behind a sign-on gate, is a blyg whose audience is everyone who can reach it.
  • Different readers seeing different posts within one blyg is the deferred privileged-access level again. One blyg per audience works today.
  • The real risks are a quote of internal work copying it out (a quote bakes the text) and retention law running against "published stays published".

The RFC is written for anyone building an enterprise product on Blygger, which is expected to be a client of its own. After a design review it will be published here for comment, then become a technical note.

Where the code is

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.53.0: Search, the install's theme at the door, tabs that say which studio

Released 2026-11-04, the reference client. v0.53.0 on GitHub.

Search on the reading and compose pages (#120). The search the [[ picker runs, on two more pages. Type in the box at the top; the query goes in the address (?q=), so back returns to the results. / focuses the box and Escape clears it. Matched words are marked.

  • Reading searches what the picker offers: your published items and the blygs you follow. With one source selected it searches that source only; a button widens it to everything. Hits open in the reader.
  • Compose searches this blyg only by default, or everything. It finds drafts and unpublished changes too, marked as such. Your own items open in the editor.

The picker is unchanged: it still offers only what a quote or link can name.

The login page wears the install's theme (#119). It used to show the studio's own light/dark colours until you logged in; now it is painted in the theme the studio switches to, wrong-password page included.

Each studio's tab says which it is (#121). The tab title is "blyg studio — {site title}", and the ❝ tab icon takes the theme's accent, so several open studios can be told apart without clicking in.

Read batches keep malformed paths to themselves (Kyle Mathews, #116). A path with malformed Unicode now fails only its own read, with a 400, after the usual permission and quota checks; the other reads in the batch keep their results.

Private contract 5.4.0 (additive: include=drafts on GET /search, draft on its results); SDK 0.10.0. Protocol version unchanged ("0.4").

Migrations: none.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.52.0: Collection read batches and smaller Mentions loads

Released 2026-11-04, the reference client. v0.52.0 on GitHub.

Mentions opens with 10 groups and 10 receipts per group. Each list keeps its own cursor and full counts. Corrected page sizes avoid extra continuation requests, and simultaneous freshness checks share one pending read.

Studio batches independent reads by collection operation while retaining the existing endpoints, query validation, permissions, and work budgets. Each child keeps its own status and retry hints. Within each server read batch, ready SQL and admission statements share D1 calls without a timer window or query rewrites. Logical read charges stay unchanged. Batch results are not cached, and a mutation starts a fresh revision check.

Browser batches dispatch in microtasks, so they do not wait for timers that can be throttled in background tabs.

The group query aggregates counts and uses indexed winner lookups instead of ranking every receipt with window functions. No rollup table or trigger is added.

Private contract 5.3.0 (additive POST /read-batch); SDK 0.9.0. Protocol version unchanged ("0.4").

Subscribing to a collection no longer needs your own collection feeds on (Aneesh Sathe, #112). Pasting the page or feed URL of another blyg's public collection now proposes a collection subscription on every node; the hopper_feeds setting governs only publishing this node's own collection feeds. API clients that want the whole blyg send wholeBlyg: true.

Two lookups no longer read whole tables (#113, reported by patwater). Resolving an imported item by id alone, and listing each reading entry's collections, each scanned a table on free-plan D1, where the reads count against a daily limit. Both now use an index. (The reader inbox's own ordering index shipped in 0.49.12; nodes older than that should upgrade for it.)

Migrations: 0040 (one covering expression index on mentions_in) and 0041 (indexes on imported_items(remote_id) and hopper_items membership). Indexes only. Apply before deploying.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.51.0: Faster Studio actions, paged Mentions

Released 2026-11-03, the reference client. v0.51.0 on GitHub.

Buttons act at once (Kyle Mathews, #111). Saving, read marks, thumbs and other row actions now change the row you are looking at straight away, and the server's answer confirms it. They used to wait for the server and then reload whole collections, which is why many buttons felt slow. A write that fails puts the row back. Rapid clicks on one row are applied in order. Each view now loads only what it shows: the editor asks for one item, Updates only the stale ones.

Mentions opens quickly on a busy blyg. It loads 25 posts at a time, each with its first 10 mentions, and "load more" fetches the rest. Totals are still complete. Source cards load as they scroll into view and never hold up navigation.

Private contract 5.2.0 (additive: GET /mention-groups, GET /mentions/summary, GET /mentions?targetItemId=…); SDK 0.8.0. TanStack DB 1.0.0-rc.1.2. Protocol version unchanged ("0.4").

Migrations: 0039 (one index on mentions_in, no data change). Apply before deploying.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.50.0: Hopper feeds, and two quoting fixes

Released 2026-11-01, the reference client. v0.50.0 on GitHub.

Hopper feeds (Aneesh Sathe, #84; spec 0.4 §16.12, decision #86). Off until you turn on Settings → Network → hopper feeds. With it on:

  • Each public hopper gets an RSS feed at {mount}/h/{slug}/feed.xml. The feed is the whole list, newest-joined first. Each entry is an excerpt that links to the member's own page, with <source> naming the member's blyg. It carries no blyg: markup, so blyg-aware readers never take it for a second feed of your blyg. The hopper page links to it.
  • Your manifest gains a hoppers list naming your public hoppers. A private hopper is never listed, and its feed answers 404.
  • Subscribing: paste a hopper's page or feed URL from another blyg, and the subscribe sheet offers that hopper, with "whole blyg instead" beside it. A hopper subscription lives next to a whole-blyg subscription to the same blyg. Its entries are summaries and links: they are never quoted or used as a source, and they never stand in for the blyg's own citation. An entry that leaves the hopper leaves your reading at the next poll. If the blyg stops listing the hopper, the subscription pauses and says so. It never turns into a whole-blyg subscription on its own.
  • Your feed, item documents and archive index are byte-identical with the setting on or off.

Partial quotes follow CommonMark's blockquote (Aneesh Sathe, #106, fixes #104; decision #76). A line written directly under a quote, without its own >, is now part of the quoted passage, as it is when the quote renders. It used to publish as your own words. An unprefixed ![[id]] line still ends the quote. If you have a draft that relied on the old reading, add a blank line after the quote.

Quotes in generated text with provenance (Aneesh Sathe, #107, fixes #105; decision #60). An own-line ![[id]] in the output of a generated block that records its sources is now quoted at publish, inside the generated block. It used to stay literal text, while the publish warning said it had been quoted. The thread preview does the same.

Private contract 5.1.0 (additive: Subscription.hopperFeedUrl, hopper subscribe proposals, wholeBlyg on createSubscription, the hopperFeeds setting); SDK 0.7.0. Protocol version unchanged ("0.4").

Migrations: 0038 (subscriptions.hopper_feed, a unique index on hopper subscriptions, the subscriptions change trigger recreated). Apply before deploying. 0037 is left unused on purpose. It is reserved for a later migration, and applying 0038 first is safe.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.49.12: Host-root /api alias for mounted nodes

Released 2026-11-01, the reference client. v0.49.12 on GitHub.

0.49.7 moved REST to {mount}/api with no alias. A node mounted at a path (/blyg is one of the two recommended mounts) broke every tool still calling host-root /api. The old address answers again, for two releases: requests to /api/… on a mounted node are served as {mount}/api/…, with Deprecation: true and a Link: <…{mount}/api>; rel="successor-version" header. Bearer tokens issued for the old {origin}/api audience are accepted on both addresses, and a stored grant for it can still refresh. Discovery (capabilities, OpenAPI servers, resource metadata, data-api-base) names only the mounted address. Root-mounted nodes are unchanged. Move tools to {mount}/api before the alias is removed.

Migrations: none.

Also in this release

0.49.12 is the first release since 0.49.1, so it also ships 0.49.11, 0.49.10, 0.49.9, 0.49.8, 0.49.7, 0.49.6, 0.49.5, 0.49.4, 0.49.3, 0.49.2, which were never released on their own. Their notes follow; read their Migrations lines before upgrading.

0.49.11 — Digest media URLs

New uploads use media/{id}/{sha256}.{ext}, including unattached files. A verified digest URL retained by a published version uses immutable public caching. Legacy URLs, current avatars, and later attachments without a published reference keep ETag revalidation. Private bytes stay private and no-store.

Discarding a draft preserves media rows used by published posts or the current avatar. Digest URL text wraps in Studio attachment cards on phones. Private API preflight explicitly sends no-store. Existing duplicate uploads retain their URL and revision, including legacy URLs.

Migrations: None. Existing media URLs and publication bytes need no rewrite. This release uses private contract5.0.0 and SDK0.6.0 from0.49.10.

0.49.10 — Bounded cursor pages

Private collection reads use opaque cursor pages. Studio loads bounded item, history, hopper, signal and browse windows through the native TanStack pager. Item and hopper detail no longer include whole historical/member collections. Named summary reads provide counts. Relevant mutations expire continuations with409 cursor-expired so clients restart the acquisition.

This is a hard private contract cutover to5.0.0 and SDK0.6.0. Update clients and API together. HTTP offset, imported-feed next, embedded history and hopper preview inputs are removed. Public protocol representations do not change.

Imported created/updated dates normalize to ISO8601 UTC at storage. Invalid dates become null. Existing timestamps need the bundled resumable metadata repair before deployment. It preserves content, versions, observation times and read state. Finish pending writes and generation, then avoid edits through repair/deployment.

Migrations: 0036_cursor_generations.sql adds interactions/browse change domains and cursor indexes. After schema migration, run node --import tsx scripts/normalize-import-dates.ts --remote for source installs, or node normalize-import-dates.mjs --remote for Worker archives, before deploying. The current updater and deploy-all run this step. Older running updaters need the explicit command after declining their deploy prompt. See README upgrade steps.

0.49.9 — Explicit private resources

The private API and SDK use camelCase fields and explicit resources. Imported metadata contains structured values, retains unknown remote members, and falls back per damaged stored column. Item kind stays fragment or thread after withdrawal, with publication state in status. Media URLs are absolute and include the deployment mount. Private errors use code, message, and optional details. Studio and SDK0.5.0 use private contract4.0.0 together.

This is a hard private API cutover. Update clients with the server. Storage and public Blygger protocol formats stay intact, including legacy media URLs. Finish pending writes and generation before upgrading, and avoid edits until deployment finishes.

Migrations: none in this release. Earlier stack releases include 0035.

0.49.8 — Conditional item writes

Item reads and creation return a private revision. Item commands require expectedRevision and return the resulting revision. Stale commands return409 with code: "revision-conflict". Text, generation provenance, attachment membership, and publication changes share the same conditional transition. Studio keeps the revision tied to its accepted text and serializes its writes. Private contract version:3.0.0. SDK version:0.4.0.

Migrations: 0035 adds the private revision and updates private item polling invalidation. Finish pending writes, including generation, before this upgrade. Avoid edits until deployment finishes. Old in-flight writes do not participate in the new revision checks.

0.49.7 — Mounted private API

REST now lives at {mount}/api. Set SDK base URLs to that full address. Mounted nodes remove host-root /api; replace old REST tokens or request new OAuth consent. MCP audiences stay the same. Private contract version: 2.0.0. SDK version: 0.3.0.

Migrations: none.

0.49.6 — 2026-10-31

Migrations: none.

  • REST and MCP invoke shared domain operations after identity verification. The shared runner applies scopes, conditional permissions, live extension gates, validation, and work budgets. MCP no longer creates internal REST requests or multipart forms.
  • Both upload adapters supply the same decoded media bytes and metadata. Existing duplicate handling, published-item permissions, rollback, retained bytes, publication warnings, and background effects remain part of the shared operations.
  • Server extension read handlers receive a domain context and validated input, and return typed outcomes. See docs/extensions.md for the callback change. Private API payloads, paths, and generated SDK stay stable in this part.

0.49.5 — 2026-10-31

Migrations: none.

  • Authenticated clients can read /api/capabilities for canonical endpoints, the contract version, available operations, and extension state. Each grant can inspect its own capabilities, including a grant with only reading:state.
  • REST and MCP use each operation's declared scopes and conditional permission rules. MCP discovery filters disabled and uncompiled extensions. Execution checks current feature state again. Static OpenAPI and SDKs retain all routes.
  • MCP hints describe effects rather than HTTP verbs. Live previews spend the read budget. Link classification retains read authority and spends the write budget because it can fetch remote pages and store its probe cache.

0.49.4 — 2026-10-31

Migrations: 0034 (versions.kind, nullable for unresolved legacy rows).

  • Normal empty and media-only publications retain their authored kind. They can be pinned, restored, forked, and compared without being mistaken for withdrawal endcaps. Studio history offers the same pin and restore actions.
  • New publications and withdrawals store explicit version state. The migration backfills facts supported by retained data and leaves ambiguous old rows unclassified. Those rows keep each reader's existing legacy interpretation. Frozen publication fields remain unchanged. Old Workers can still insert rows during the migration/deploy window.
  • Authored-kind reads use stored version state across private reading, public pages, feeds, provenance, forks, and mentions. Publishing-history ordering includes explicit empty publications and excludes withdrawals.

0.49.3 — 2026-10-31

Migrations: none.

  • Public JSON, OPML, CSS, Studio assets, and legacy media URLs provide ETags and conditional GET/HEAD responses. JSON validators cover all emitted data, including changelog pin flags and mutable author/origin metadata on pins. Legacy random-ID media URLs revalidate rather than promise immutable caching.
  • CORS and cache policy apply to actual OAuth responses, public wire errors, explicit conditional preflight, and bearer-authenticated private media reads. Browser clients can inspect validators, retry delays, supported methods, returned locations, and authentication challenges where CORS permits reads.
  • Authorization endpoints exclude CORS on canonical and trailing-slash routes, including preflight. Early private size-limit errors and MCP origin denials have an explicit no-store policy. Native OAuth discovery retains its public cache lifetime, and signing-key metadata has an explicit revalidation policy.
  • Wrong-method responses include owner grant administration, schema delivery, and MCP in their Allow headers. Enabled Webmention reports POST as its method; disabled Webmention remains absent.

0.49.2 — 2026-10-31

Migrations: none.

  • Restoring an item version restores its attachment membership with its text. Discard restores detached published attachments and excludes unpublished additions. Earlier versions retain their media and bytes. A stale restore returns 409 without changing text or membership.
  • A provenance-only PATCH guards the stored text used to validate its TK scopes. A concurrent text change returns 409. A PATCH supplying replacement text and matching provenance keeps its existing behavior.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread

Blygger Studio 0.49.1

Released 2026-10-30, the reference client. v0.49.1 on GitHub.

Migrations: none.

Two contributed Studio changes (Kyle Mathews' #85 and #86) and two end-to-end test fixes. No API, contract or data changes.

  • The studio title links to the reading page (#86). The site name and "blygger studio" in the top bar are now a link, with a visible keyboard focus outline.
  • Preloads and polling use TanStack Query's own machinery (#85). Hovering or focusing a Studio link now completes the preload: route loaders warm hopper previews, mention source details and reader targets before the page renders. The custom polling scheduler and its per-component hooks are gone; live collections opt into Query's 15-second polling with visibility handling, and Settings and Authorizations refresh on return, reconnect or write without a timer. Reader links (quoted layers, body links, breadcrumbs, history, peek sources) are router links, so they open in new tabs and preload on intent. Hover and focus do not change the browsing trail or log a visit. DB and React DB move to 1.0.0-rc.1, Query Collection to 1.5.0 and Query Core to 5.105.0; DB is now an explicit dependency.
  • AGENTS.md is the project instructions file (#85), with CLAUDE.md kept as a symlink to it.
  • Tests: reader-browse waits for the feed to end the walk before re-entering an item, and generated-highlight runs under the per-test edge identity and resets its setting in afterEach.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Nov 4, 2026

thread · 1 quoted

Update, 1 November 2026: hopper feeds ship, a new API, three rulings, and a reader test suite

Three working sessions in one day across the spec, Blygger Studio and the two sites. This is what changed, what it means if you run a node or build a client, and what is next.

Hopper feeds are live (Blygger Studio 0.50.0)

A public hopper, a curated collection on a blyg, can now be subscribed to on its own, without subscribing to the whole blyg it lives on. The request came from the World Machines bridge, which collects the posts its members put in a WM hopper. When it opened this morning, it had to work around the gap:

Hoppers don't have their own feeds yet, so the WM blyg follows your whole blyg in order to import posts. But it only collects the posts that are in the hopper you submitted.

from worldmachines.org ↗ · excerpt of v1

As of tonight they do, and a node on 0.50.0 can follow a member's hopper directly. Aneesh Sathe proposed the design (blygger-spec#18) and built it (blygger-studio#84). It was ruled in the afternoon as decision #86 and released tonight as 0.50.0.

  • Turn it on under Settings → Network → hopper feeds. It is off by default.
  • Each public hopper then has an RSS feed at {mount}/h/{slug}/feed.xml, and the manifest gains a hoppers list naming them.
  • To subscribe, paste a hopper's page URL into Subscribe. The studio offers that hopper, with "whole blyg instead" beside it.
  • Entries are summaries and links, newest-joined first. One that leaves the hopper leaves your reading at the next poll.
  • Nothing about your own feed or item documents changes. A hopper feed carries no blyg: markup, so it can never be mistaken for a second feed of your blyg, and no item document ever names a hopper. Hoppers stay a list, not tags.

The cross-node gate ran live: venkateshrao.com/blyg/ published a test hopper, blyg.protocol-institute.org subscribed to it by pasting its page URL, removing a member dropped the entry at the next poll, and the existing whole-blyg subscription between the two nodes was untouched. On the strength of that, the rules moved from a ruled-but-unbuilt appendix into the normative 0.4 text (eighth revision): §6.1 (hoppers), §12.1 step 7 (resolving a hopper URL), §12.2 (identity) and §13.5–§13.6 (the feed and the reader's rules).

For other clients: to read hopper feeds, implement step 7. It needs no extra fetch: you compare the URL you were given against the manifest's hoppers list. A reader that skips it resolves a hopper URL to the whole blyg, exactly as before.

Also in 0.50.0, both from Aneesh: a partial quote now takes CommonMark's full blockquote, so a line written directly under a > line is part of the passage, as it is when the quote renders (#104). And an own-line quote inside generated text that records its sources is now quoted at publish, as it always was without sources (#105). Migration 0038 runs before deploy.

A new private API (0.49.12)

Kyle Mathews' API cleanup landed earlier in the day: eleven pull requests tracked in blygger-studio#92.

  • REST now lives at {mount}/api.
  • Bodies are camelCase.
  • Every item write names the revision it read, so two tools can't silently overwrite each other.
  • Lists page by cursor, and media is addressed by its digest.
  • REST and MCP share one set of operations.

This is private contract 5.0.0, now 5.1.0 with the hopper additions. On a node mounted at a path, the old host-root /api still answers for two releases, with Deprecation and successor Link headers. If you have a tool writing to a blyg, move it to {mount}/api and send expectedRevision. This blyg's own publishing scripts needed exactly that change tonight.

Three rulings (seventh revision of 0.4)

  • #86: hopper feeds, above.
  • #87: the fixed name holds at every identity. Wherever a blyg's identity origin is, {origin}blyg.json MUST answer, as the manifest itself or by a same-identity redirect. A manifest may still be named elsewhere, but everyone who holds only an identity probes the fixed name, and two clients had disagreed about one live origin (blygger-spec#21, from chrisbodhi).
  • #88: origin succession. A blyg that moves says so twice: the old origin permanently redirects its manifest, and the new one lists the old in an OPTIONAL moved_from. Readers offer to follow only when both are there, and never adopt the new origin silently. This came from Florian Lohse's real move (blygger-studio#102). Until the studio builds it, one subscriber's copy was fixed by hand, and blygger.com now folds a moved blyg's old listing into its new one.

A reader conformance suite

Aneesh's reader suite (blygger-spec#22) is merged in conformance/reader/. It holds 100 fixtures, written from the spec text, that check what any client's renderer bakes into content_html: quotes, labels, partial quotes, links, absolute URLs and generation disclosure. Any renderer can run it through a small adapter. Blygger Studio passed 72 of 100 against 0.49.12. Two of the four findings are fixed in 0.50.0, and the other two (links[] and data-blyg-label) are queued. Nine places where the 0.4 text leaves a choice are now with Fable.

Also today

  • Tangling is planned: top-down authoring where marked passages become fragments at publish. It comes with a reader-side Background lens, so bursts don't flood anyone. The heads-up post explains it, and what other clients can prepare.
  • Contributors and ecosystem pages refreshed: Shannon, Ned Twigg, Florian Lohse, Rafael David and Ruthvik Peddawandla are credited, and blygd, blygcaster and blyg-watch are listed (contributors, ecosystem).
  • Shannon's Base UI groundwork for the studio (blygger-studio#88) is in review.

Next

  • The RFC-1 and RFC-2 comment periods close on 4 November.
  • Building moved_from.
  • The Background lens.
  • Splitting the hopper-feeds setting, so a node can subscribe to hoppers without publishing feeds of its own.

Source: docs/posts/2026-11-01-update.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

Created: Nov 2, 2026

thread

Heads-up: tangling is coming to Blygger Studio, and readers should fold bursts

A note for anyone building a Blygger client. This is not an RFC: nothing on the wire changes, and every protocol rule it leans on is already in the 0.4 text. It says what Blygger Studio is about to do, so other clients can get ready for the traffic it makes.

What is coming

Top-down authoring, the way Roam and Obsidian writers work. Write an essay, mark the passages that stand on their own, and publish once:

Here is the opening, which stays in the essay.

![[+ Stigmergy is the mechanism by which a protocol becomes invisible
to the people inside it.]]

And here is what follows from that.

At publish, each marked passage becomes its own fragment, with its own id, page and feed entry. The essay becomes a thread that quotes them, and its source is rewritten to ordinary directives:

![[<new id> | Stigmergy is the mechanism by which…]]

The idea is old. It is Knuth's tangle from literate programming, applied to a blyg. The fragment is the medium's unit, but essayists find the parts by writing the whole. Tangling lets the commonplace book fall out of the essay instead of being a second discipline.

The ![[+ …]] marker is Blygger Studio's own authoring syntax. It is rewritten before publish and never reaches the wire (decision #70). On the wire a tangled thread is fragments plus a thread, the same as if you had written each fragment by hand and quoted them.

The cost, and why it lands on readers

One act now publishes many items. Every one is a real publication, so every one gets a feed event: §7 has no quiet publish, because an event the feed leaves out is content hidden from subscribers. A ten-passage essay is eleven entries in a feed window that holds fifty.

Mentions can flood the same way. A thread of bare quotes sends a notice to every source it quotes, and fragments full of [[id]] links send one per link.

The protocol's answer, ruled across decisions #77, #78, #80 and #83, is the same each time: nothing on the wire marks an item as minor, so readers work it out from what is already there, and queue it low instead of hiding it. No author can write to a signal that is never declared.

What Blygger Studio will do

As a publisher:

  • Publish the fragments first and the thread last, so the thread is the newest entry (§7).
  • Show the count before anything is published ("this will publish 3 fragments and this thread"). API and MCP callers have to confirm it too.
  • Cap one publish at 10 passages.

As a reader, a new Background lens collects what is worth having but not worth interrupting you for:

  • Bursts: fragments that arrived with a thread quoting them. The thread stays in your main feed with a "+3 fragments" control (§13.7).
  • Wordless items: a stub or thread that is only quotes, with no words of its own. This is the same test §15.4 applies to mentions.
  • Maintenance: a republish with the same content_hash, or an edit too small to matter (§13.2). The threshold is the reader's own and is never published.
  • Withdrawn items, as today.

Nothing is dropped. Every item is still imported (§13.1); Background is a place, not a filter. Link mentions and reposts become notices, held apart from responses (§15.5).

What other clients can do

  • If you publish several items in one act, publish one event per item and the thread last. Don't invent a "quiet" or "minor" flag. The spec refuses those on purpose.
  • If your client has its own authoring syntax, rewrite it before publish. content_md is what readers get.
  • If you read blygs, fold bursts under their thread, and queue maintenance versions and wordless items low. Everything you need is already in the item documents: created, updated, transclusions[], content_hash, content_md.
  • If you receive mentions, classify reposts and links as notices, not responses.

Two sentences in the spec are being tightened as part of this. §13.7 says a burst folds under "a thread created with them", but created is when a draft was started, so a thread drafted on Monday and tangled on Friday would not match. It should say published with them. And §13.2 will say that the wordless test may be used in reading, not only for mentions.

Where to read more

The full plan, including the edge cases (crash recovery, spans inside code, what happens on republish) and the order of the build, is docs/tangling-plan.md in blygger-spec. Discussion is on blygger-studio#20.

Inline placeholders, where [[+ text]] mid-sentence would create a fragment to fill in later and link it, are reserved for a later build.

Source: docs/posts/2026-11-01-tangling-heads-up.md in blygger-spec, which is where revisions are made; each one is published here as a new version. To comment, respond to this item from your own blyg: a stub is a comment, a partial quote names the passage, and a fork of the pinned version is a counter-proposal.

read the thread →

Created: Nov 2, 2026

thread

Blygger Studio 0.49.0

Released 2026-10-29, the reference client. v0.49.0 on GitHub.

Migrations: 0033 (browse_log, link_probe; both studio-private). Apply it to every D1 before deploying.

  • Browse the thicket from the reader. Every quoted layer in an entry, at any depth, now says whose it is and opens in the reader; so does any ordinary link that names a blyg item (the server looks at the page the link points to, §5.8's rel="alternate" item document, and remembers the answer for a week). An item of a blyg you hold opens at its own address; one you do not hold opens at /peek, read from its origin with nothing stored, with a subscribe button. A stub opened that way shows what it responds to, and that opens too. Back retraces the descent one entry at a time, and a breadcrumb shows the path.

  • Browsing history. The walk is logged privately (browse_log, a tree: each step names the step it was reached from) and a history pane beside the reader (a bottom sheet on a phone) shows this walk and earlier ones, with clear history. Never on the wire or a public page.

  • Public pages name every nested quote. injectNestedProvenance: the provenance line, with a link, now appears on quotes inside quotes too; an absent data-blyg-origin takes the origin of the layer that baked it. Links behave as ordinary links.

  • Links that are not blyg items open in a new tab, so reading your place is kept; and opening an item of a blyg you do not subscribe to shows an alert, You're not subscribed to this blyg — subscribe?, with the subscribe sheet prefilled.

  • Withdrawn posts are background. The Background lens, a placeholder until now, lists withdrawn posts (your own endcaps and the blygs you read); every other lens, the sources counts and hopper timelines leave them out. GET /reading takes background=true.

  • A revised post leads with its latest changelog entry. On a feed card for an imported blyg item past its first version the line V3: … comes first, read from the origin's changelog once the card is on screen (nothing new is stored); with no note for that version it says V3: No changelog entry available.

  • New operations: peekItem, classifyLinks (both owner:read), listBrowse (owner:read), logBrowse and clearBrowse (reading:state).

  • A stub's passage is selected in the editor's own preview. The separate chooser pane, which showed the quoted post a second time, is gone. Select text inside the stub's quote in the preview and press quote only this; the passage is written under that quote's ![[id]], whichever of several it is. On a phone the button select a passage in the preview switches panes, and the draft returns after the choice. Quote another passage adds a whole-post quote after the cursor to select from, replacing add as another quote and replace the first quote. Selections inside a nested quote, or while the preview is out of step with the draft, offer nothing.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 29, 2026

thread · 1 quoted

The day in Blygger, 19 October 2026: links that notify, reposts as notices, and two-way quotes on your own blyg

Protocol 0.4 took its fourth revision, now live on blygger.org, with five new decisions, #79 through #83. They started from one observation: there is demand for simple responses. Blygger Studio 0.48.0 shipped the same day with nine contributor pull requests, among them Kyle Mathews' fix for mentions showing up out of order, and two new features of its own: your own posts can be stubbed from the reading feed, and every public page now lists the posts on the same blyg that quote it.

Blygger Studio 0.48.0

Released 2026-10-19, the reference client. v0.48.0 on GitHub.

Migrations: 0028, 0030, 0031, 0032 — apply them before deploying (wrangler d1 migrations apply DB --remote). 0031 backfills version_media so no live document changes at upgrade. Optional new secret TYPESAFE_API_KEY, needed only to use Jev as the change classifier. Implements protocol 0.4.

  • Own items in the reading feed get stub ↗, add to hopper and fork (Venkat). Your own entries offered only edit and link post. A stub of your own post quotes its live version and cites it with a same-origin stub_of, which sends no mention (§15.2); a withdrawn post is cited without a quote. The lineage sheet now offers these actions on your own posts and says what differs.
  • Local mentions on public pages (Venkat). A fragment or thread page lists this blyg's own published items that stub, quote or fork it, each linked back, so a transclusion is walkable in both directions on your site. Like Responses it is page chrome, never in a document, feed or hash; unlike Responses it needs no opt-in, because every row is your own. Only live versions count: a quote edited out, or a withdrawn quoter, leaves the list.
  • Attachments per version (studio#7, Aneesh Sathe; migration 0031). Each published version records the attachments it showed. Removing an attachment drops it from the next version only; earlier versions keep listing it and its bytes keep serving. Before, an attachment appended below a post could have its bytes deleted while a published version still listed it.
  • Duplicate uploads return the existing file (studio#7, Aneesh Sathe; migration 0028). The same bytes, type and placement on the same item store nothing new; POST /api/media answers 200 with duplicate: true.
  • Optional change classifier (Aneesh Sathe; migration 0030). Off unless Settings → AI → change classifier names a decision model (Clef or Clef-flash on Workers AI, or TypeSafe's Jev). It suggests typo, minor or major for a new version in the publish dialog, refresh for a republish of the same words with no model call, and can lead the change note with that word. The label is kept privately with the version; readers see it only as words in your note, and no client gives it meaning (decision #83).
  • OPML import (studio#63, Aneesh Sathe). Import subscriptions from an OPML file in Sources, with a preview, per-feed choice, an optional add-to-blogroll, and a per-row result. Imported feeds are fetched by the next background poll.
  • Mentions show up as they arrive (Aneesh Sathe; migration 0032). Verified responses, and hiding or showing one, now refresh the public page at once instead of after the edge cache expired (up to about six minutes), and the studio's mention views re-read only when something changed.
  • Newest Webmention responses first (Kyle Mathews). Response groups on the Webmentions page had come back in random id order.
  • Label grammar: six edge cases fixed (#70, Aneesh Sathe), found porting the renderer to another client, among them a label escaped twice inside a generated block and a backtick in one label disabling a later link.
  • Studio on the phone (Aneesh Sathe): no more random zoom on iOS (fields under 16px, double-tap), compact reading cards, full-screen reading, and a quieter composer and editor.
  • TanStack DB packages updated (Kyle Mathews).

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

thread ↗ · snapshot of v1

The rulings

  • Links notify (#79, reversing #32). A resolved [[id]] now goes on the wire as an entry in a new links[] array: {id} for your own items, {id, origin} for another blyg's. A link names a page, not a version, so an entry carries no version and no citation. A remote entry SHOULD send a mention, and the receiver records a fifth relation, link. The silent citation survives as the plain markdown link [text](url), which nobody inspects. You choose by how you write the link. (§10.3a)
  • Reposts are notices (#80). A bare ![[id]] is not discouraged: it is the reference client's repost shape. The receiver takes the fetched document, strips directive lines, attached passages, labels and whitespace, and if nothing is left, it is a repost. No marker is added; the wire already says it. Verified mentions now come in two classes: responses (stubs, quotes, forks and sources, with words of their own) and notices (links and reposts). Notices never appear in a responses list. (§15.4, §15.5)
  • The quote's label travels (#81). The label in ![[id | text]] is now baked onto the quote as data-blyg-label, and is RECOMMENDED as the text of the "quoted from" line, so subscribers and forks see it too. It is the quoter's words about the target, never the target's title.
  • Respond from anywhere (#82). Quoting and stubbing no longer need a subscription. The old rule, "from any subscribed origin", was a client-local notion that had leaked into the wire. Any snapshot a client holds from the item's own origin will do, whether it was polled or fetched once. The recommended client shape is a deep link that takes any URL, so a bookmarklet, the share sheet or a browser extension can open the stub composer. A "stub this" button on every blyg page has to work across clients, so it goes to an RFC first: RFC-4, now being drafted. (§16.11)
  • No significance token (#83). A changelog note may say a change is minor, in words; that is what the note is for (TN-1). But no word in a note has wire meaning, and no client may give one any. A token that readers route on is the "this matters less" flag already refused, with a worse spec: [skip ci] is the precedent, and its own attack is softening a strong claim under the token so subscribers don't re-read it. The author's lever is not publishing a change that isn't worth an event. Readers get near-sameness instead: a version whose text barely differs from the one before it MAY be queued as maintenance, by a threshold each reader keeps to itself.

If you run a blyg

  • Blygger Studio 0.48.0. Apply migrations 0028, 0030, 0031 and 0032 before deploying.
    • Stub your own posts. Your own entries in the reading feed get stub ↗, add to hopper and fork. A stub of your own post quotes its live version and cites it on the same blyg, so no mention goes out.
    • Local mentions. Every fragment and thread page lists the posts on the same blyg that stub, quote or fork it, each linked back. Together with the "quoted from" line a quote already carries, a quote can now be followed in both directions on your own site. Like Responses, the list is page chrome, never part of an item document or feed. Unlike Responses it needs no opt-in, because every row is yours.
    • Attachments per version (Aneesh Sathe). Removing an attachment drops it from the next version only; earlier versions keep showing it. Uploading the same file twice to the same post stores it once.
    • An optional change classifier (Aneesh Sathe), off by default. A cheap decision model (Clef on Workers AI, or TypeSafe's Jev) suggests typo, minor or major for a new version, and can lead your change note with that word. Under #83 it is prose: your words, which readers may read and no client acts on.
    • OPML import (Aneesh Sathe), with a preview, a choice per feed, and an optional add-to-blogroll.
    • Mentions in the right order (Kyle Mathews, studio#76). The studio's Webmentions page groups mentions by the post they answer, and the groups came back in random order, because mention ids are random. A response that had just arrived could sit below months-old ones and look as if it had not arrived at all. Kyle rewrote the page's query as a TanStack DB live query: groups sort by their newest verified mention, and their counts and visibility are computed in the same query. An oracle test checks it against an independent model, and mutation checks reject any broken ordering or visibility. Delivery and verification were never at fault; only the view was.
    • Responses appear at once (Aneesh Sathe). A newly verified response, or hiding or showing one, used to take up to six minutes to reach the public page.
    • On the phone (Aneesh Sathe): no more random zoom on iOS, compact cards and full-screen reading.
    • Six edge cases in the 0.47 label grammar fixed, found by Aneesh while porting the renderer to another client.

If you write a client

  • Build to the fourth revision. The changes on the wire are small and additive: links[] on item documents and data-blyg-label on the quote blockquote. A 0.3 reader ignores both. The rest is receiver behaviour: the link relation, the repost test, and keeping notices out of responses lists.
  • Never parse a change note (§5.2), and treat near-sameness as your own reader-side choice: keep the threshold small, since one word can negate a sentence, and never omit a version, only queue it.
  • Respond from any URL. If your client can fetch an item's document once, it can let its author stub it. RFC-4 will settle how a page offers that across clients; until it publishes, please don't add a "stub this" link to public pages.

Next

The reference client builds the rest of today's rulings: disclosed links with "linked this" lines in local mentions, the repost test, the traveling label and near-sameness, then a plan for stubbing from any URL and the RFC-4 draft. RFC-1 and RFC-2 are open for comment here until 4 November.

read the thread →

Created: Oct 20, 2026

thread

Blygger Studio 0.48.0

Released 2026-10-19, the reference client. v0.48.0 on GitHub.

Migrations: 0028, 0030, 0031, 0032 — apply them before deploying (wrangler d1 migrations apply DB --remote). 0031 backfills version_media so no live document changes at upgrade. Optional new secret TYPESAFE_API_KEY, needed only to use Jev as the change classifier. Implements protocol 0.4.

  • Own items in the reading feed get stub ↗, add to hopper and fork (Venkat). Your own entries offered only edit and link post. A stub of your own post quotes its live version and cites it with a same-origin stub_of, which sends no mention (§15.2); a withdrawn post is cited without a quote. The lineage sheet now offers these actions on your own posts and says what differs.
  • Local mentions on public pages (Venkat). A fragment or thread page lists this blyg's own published items that stub, quote or fork it, each linked back, so a transclusion is walkable in both directions on your site. Like Responses it is page chrome, never in a document, feed or hash; unlike Responses it needs no opt-in, because every row is your own. Only live versions count: a quote edited out, or a withdrawn quoter, leaves the list.
  • Attachments per version (studio#7, Aneesh Sathe; migration 0031). Each published version records the attachments it showed. Removing an attachment drops it from the next version only; earlier versions keep listing it and its bytes keep serving. Before, an attachment appended below a post could have its bytes deleted while a published version still listed it.
  • Duplicate uploads return the existing file (studio#7, Aneesh Sathe; migration 0028). The same bytes, type and placement on the same item store nothing new; POST /api/media answers 200 with duplicate: true.
  • Optional change classifier (Aneesh Sathe; migration 0030). Off unless Settings → AI → change classifier names a decision model (Clef or Clef-flash on Workers AI, or TypeSafe's Jev). It suggests typo, minor or major for a new version in the publish dialog, refresh for a republish of the same words with no model call, and can lead the change note with that word. The label is kept privately with the version; readers see it only as words in your note, and no client gives it meaning (decision #83).
  • OPML import (studio#63, Aneesh Sathe). Import subscriptions from an OPML file in Sources, with a preview, per-feed choice, an optional add-to-blogroll, and a per-row result. Imported feeds are fetched by the next background poll.
  • Mentions show up as they arrive (Aneesh Sathe; migration 0032). Verified responses, and hiding or showing one, now refresh the public page at once instead of after the edge cache expired (up to about six minutes), and the studio's mention views re-read only when something changed.
  • Newest Webmention responses first (Kyle Mathews). Response groups on the Webmentions page had come back in random id order.
  • Label grammar: six edge cases fixed (#70, Aneesh Sathe), found porting the renderer to another client, among them a label escaped twice inside a generated block and a backtick in one label disabling a later link.
  • Studio on the phone (Aneesh Sathe): no more random zoom on iOS (fields under 16px, double-tap), compact reading cards, full-screen reading, and a quieter composer and editor.
  • TanStack DB packages updated (Kyle Mathews).

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 20, 2026

thread · 1 quoted

The day in Blygger, 17 October 2026: protocol 0.4, labels, and a new front page

Protocol 0.4 opened and was published with its first snapshot, then took two revisions the same evening. Nine decisions were recorded, #70 through #78: the [[id | text]] label, received conventions over taste, the 0.4 opening, the pace-layered RFC with pinned_at, cid on pins, image sizing, the conformance clarifications with member tables measured against all 22 live blygs, ignyr as a derived reader-side queue, and inline fragment authoring. Three pending Opus rulings were confirmed. Five GitHub threads were answered and one closed. The Fable queue went from seventeen items to one.

Blygger protocol 0.4 is published: blygger.org/spec/0.4/, with its first dated snapshot at /spec/0.4/2026-10-18/. 0.3 is superseded and stays citable.

Two constructs ruled earlier are now normative, each built and tested across live blygs first:

  • Remote generation sources (§5.7, §15.4): a model may draw on another blyg's item, which is disclosed as a source and notifies its origin.
  • The manifest locates the surface (§4, §6.1): a manifest may say where its feed, items and pins live, which is how WordPress publishes natively.

And the grammar gains an optional label: [[id | text]], ![[id | text]] (§10.1). Blygger Studio supports it from 0.47.0.

A valid 0.3 document is a valid 0.4 document unchanged.

fragment ↗ · snapshot of v1

If you run a blyg

  • Blygger Studio 0.47.0 is the first client to write the new label: [[id | text]] on a link sets its text, ![[id | a note]] on a quote keeps a thread's source readable and never reaches readers. The picker and copy [[id]] write the long form for you. Generated text no longer publishes stray brackets.
  • Blygger Studio 0.46.3 carries Kyle Mathews' fix for OAuth clients that leave out resource, which may be what kept the MCP server out of Cloudflare's MCP portals (studio#54), and hover text on the editor toolbar (Ned Twigg, studio#48).
  • blygger.com now hands subscribers each blyg's own feed, as its manifest names it, so a blyg on WordPress via Soapbox for Blygger is listed with a feed that works.
  • blygger.org has a new front page in two tabs, For Publishers and For Developers, a glossary, and a page on the thicket, the network of blygs formerly called the blygosphere, with the idea for an explorer of it, which will live on blygger.com.

If you write a client

  • 0.4's new constructs: a generator may draw on another blyg's item, disclosed as a source that notifies its origin (§5.7, §15.4); a manifest may say where its feed, items and pins live (§4, §6.1); and the optional label after an id (§10.1). A valid 0.3 document is a valid 0.4 document.
  • Ruled shapes you could build now (§16): pinned_at on pinned changelog entries, cid naming a pinned document's exact bytes (spec#13), and Pandoc-style {width=…} on images (studio#37).
  • Clarified: member tables for item documents and manifests, eight conformance findings from Aneesh Sathe's toolkit, a same-hash republish as maintenance rather than news, and multi-item publishes (one event per item, thread last), which readers may fold into one publication (studio#20).
  • Coming: RFC-3, the pace-layered order as a recommendation for every client. RFC-1 (mentions) and RFC-2 (comments sections) stay open for comment on this blyg until 4 November.

Threads

spec#2 closed: Robert Peake's Soapbox switches to "0.4". spec#16, Ned Twigg's request for comments inside ids, ruled and shipped. Surya Kasturi's questions on Webmention flooding, DNS firewalls and feed scoring answered (studio#72, #49, #57); Aneesh's studio#11 closed with everything on its list shipped, and his extension registry (studio#59) is next for a ruling. And a question for Kyle on whether a CI check should depend on outside registries (studio#73).

Everything above is on the roadmap, and comments are welcome as stubs of this post.

read the thread →

Created: Oct 18, 2026

Blygger protocol 0.4 is published: blygger.org/spec/0.4/, with its first dated snapshot at /spec/0.4/2026-10-18/. 0.3 is superseded and stays citable.

Two constructs ruled earlier are now normative, each built and tested across live blygs first:

  • Remote generation sources (§5.7, §15.4): a model may draw on another blyg's item, which is disclosed as a source and notifies its origin.
  • The manifest locates the surface (§4, §6.1): a manifest may say where its feed, items and pins live, which is how WordPress publishes natively.

And the grammar gains an optional label: [[id | text]], ![[id | text]] (§10.1). Blygger Studio supports it from 0.47.0.

A valid 0.3 document is a valid 0.4 document unchanged.

Created: Oct 18, 2026

thread

Blygger Studio 0.47.0

Released 2026-10-17, the reference client. v0.47.0 on GitHub.

Migrations: none. No config change. Implements protocol 0.4, opened today.

  • Labels on links and quotes: [[id | text]] and ![[id | text]] (0.4 §10.1, decision #70; blygger-spec#16, ROADMAP row 66). On a link the label is the link text, in place of the target's heading or an excerpt. On a quote it is a note for you that keeps a thread's source readable, and it never reaches the published quote, transclusions[] or provenance. The id comes first; the label runs to ]], may contain a pipe, and an empty one is no label. The picker and copy [[id]] now write the long form, labelled with the text the link would have shown, so nothing changes until you edit it. Search results carry that text as a new label field. Labelled forms are inert inside code like the rest of the grammar, and fork flattening keeps a labelled link's text.
  • Generated text no longer publishes literal brackets (ROADMAP row 67). A model that echoed [[id]] or an inline ![[id]] from its context left raw brackets in the post. The generation prompt now asks for none, and any that survive are removed before the text reaches the draft, keeping a label's words. A quote alone on its own line still quotes, as before (decision #60).
  • The bracket grammar is defined once (src/grammar.ts) and every reader of it, server and studio, builds from there. Code comments now cite protocol 0.4's sections instead of 0.3's appendix.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 18, 2026

thread

Blygger Studio 0.46.3

Released 2026-10-17, the reference client. v0.46.3 on GitHub.

Migrations: none. No config change. The code is 0.46.2's, released under a new number because 0.46.2's tag could not be: the conformance-suite images that 0.46.2's new oauth-interop CI job pins by digest were deleted from GitLab's registry when GitLab rebuilt the release-v5.3.2 tag, so that commit's Check could not pass. Both images are re-pinned to the tag's current digests. If you upgraded to 0.46.2 from its tag, nothing changes but the version string.

0.46.2 — 2026-10-17 (tagged, never released)

Migrations: none. No config change.

  • OAuth clients that leave out resource now get a working token (Kyle Mathews, #66; reported as #54). A client that omits the RFC 8707 resource indicator, as generic OAuth clients and manually configured MCP proxies do, could complete the owner's consent and then fail at the token endpoint with invalid_grant. The authorization request now defaults to the node's MCP resource before login, consent and code issuance, and the consent page shows that MCP address. An explicit resource is validated as before, and the default grant cannot reach the REST API: REST clients still ask for the API resource by name. No new routes, no host-root paths. docs/oauth-interop.md and docs/issue-54-cloudflare-mcp.md have the findings and the Cloudflare portal setup.
  • Hover text on the editor toolbar (#48). The [[, ![[ and TK buttons had labels for screen readers only; each now says what it does when pointed at, and attach image does too.
  • CI: a new oauth-interop job runs MCP Inspector 2.10.1 and selected OpenID Foundation conformance modules against disposable Workers, with the package version and container digests pinned (#66).

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 18, 2026

thread

Blygger Studio 0.46.1

Released 2026-10-13, the reference client. v0.46.1 on GitHub.

Migrations: none. No config change.

  • Publishing shows at once on public pages. Since 0.39.0 the edge cache kept serving a page's old copy for up to a minute after a publish, a withdrawal or a settings change, and a reload could not get past it. The cache key now carries the blyg's public revision (the change_state counters for items, subscriptions, hoppers, settings and feed), so the first read after a change goes to a fresh entry. Each public read costs one small D1 query. The owner's reading state and thumbs do not move the key. Hiding or showing an inbound mention still waits out the 60-second window: mentions have no revision counter yet.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 13, 2026

thread

Five releases in a day: Blygger Studio 0.42 to 0.46

Blygger Studio shipped five releases on October 12. Most of what changed is visible on the public side of a blyg: how its home page reads, how a reader finds their way around it, and what the owner can put where. Each release has its own announcement, linked under each section; this is the tour.

A home page that keeps time two ways

0.42.0 added the pace-layered home page. Items sink as new ones arrive and climb one place with each new version, and pins slow the sinking, so what keeps mattering stays near the top while what is new still arrives. It reads only what any subscriber can see (changelogs, pins, quotes), so other clients can compute the same order. It is the default for fresh installs; a blyg that has already published keeps newest first until its owner chooses. The same release added a setup walk-through that shows every setting beside its default.

Release notes: “Blygger Studio 0.42.0 Released 2026-10-12, the reference cli…”

A static front page

0.43.0 lets a blyg greet readers with a thread of its owner's choosing at its root, the way a WordPress site can use a static front page. The latest items move to /posts/ (the address is a setting), and every public page links there. The thread is still an ordinary thread: edited like any other and still in the feed, the archive and the index, so nothing changes for other blygs reading it. The release also removed an intermittent CancelledError banner while editing, a fix contributed by Kyle Mathews.

Release notes: “Blygger Studio 0.43.0 Released 2026-10-12, the reference cli…”

A main menu, and a masthead menu

0.44.0 added a menu on every public page: threads the owner picks (an About page, a Now page), public collections, the owner's own links, and a line of standard links to the blogroll's OPML file, blygger.org and blygger.com. 0.45.0 made it a proper side menu, one link per line in a narrow column with the blyg's name set over the content, and on a phone a Menu button under the name instead of a list at the foot of the page. Since 0.46.0 it sits on the left by default.

Release notes: “Blygger Studio 0.44.0 Released 2026-10-12, the reference cli…”, “Blygger Studio 0.45.0 Released 2026-10-12, the reference cli…”

Your own posts in hoppers

Hoppers used to hold only what you read. Since 0.45.0 an owner can put their own posts in a hopper beside other people's, from a post's menu, and a public hopper's page shows them as the home page would. A hopper can now be a reading list, a portfolio, or both.

Release notes: “Blygger Studio 0.45.0 Released 2026-10-12, the reference cli…”

Writing without the buttons going grey

Autosave used to disable publish and save draft every time the writer paused, until the save came back. Since 0.45.0 it saves quietly, and a publish clicked meanwhile waits for the save and publishes the newest text.

Release notes: “Blygger Studio 0.45.0 Released 2026-10-12, the reference cli…”

Settings on one page

0.46.0 reorganizes Settings into one page with a sidebar: General, Feed, Appearance, Links, AI, Network. Under Links, the two menus are named for where they appear: the masthead menu under the author's name and the main menu beside the content. Under AI, each function's model sits beside its own instructions, so [TK] generation, change notes and the smart feed each read as one unit. Choosing a front page or a menu thread is now a search rather than a long list.

Release notes: “Blygger Studio 0.46.0 Released 2026-10-12, the reference cli…”

Next on the roadmap

Five items joined the roadmap along the way: the owner API moving under the blyg's own address, so a blyg can share a domain with other software (asked for by Surya Kasturi); [[text | id]] links with chosen link text; links written by [TK] generation that currently publish as raw brackets; the blogroll listed entry by entry in the main menu; and a pace-layered order for the reading view.

read the thread →

Created: Oct 13, 2026

thread

Blygger Studio 0.46.0

Released 2026-10-12, the reference client. v0.46.0 on GitHub.

Migrations: none. One default changes: the main menu (links_position) now sits on the left unless the owner chose otherwise, so a blyg that never set it moves its menu from below the content to a left sidebar on upgrade. Choose Below the content in Settings → Links to keep the old place.

  • Settings on one page, in sections, with a sidebar of anchors: General, Feed, Appearance, Links, AI, Network (and Extensions when the build has any). The section in view is marked, settings#ai and the like link straight to one, and on a phone the sidebar is a row of chips under the top bar. Under Links, the two menus are named for where they appear: the masthead menu (your author links) and the main menu. Under AI, each function's model sits beside its own instructions: TK generation with the house style, change notes with auto-drafting, the smart feed with its scoring prompt.
  • The front page is chosen by search, like the main menu's threads, with use latest items to go back.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 13, 2026

thread

Blygger Studio 0.45.0

Released 2026-10-12, the reference client. v0.45.0 on GitHub.

Migrations: none.

  • Your own posts in hoppers. Add to hopper… in a post's ⋯ menu puts it in a hopper beside what you have read (or in a new one). A public hopper's page shows it as your home page does, once published and not after withdrawal; the studio's hopper view lists it with edit and remove. Clients: PUT /api/hoppers/{id}/items/~own/{itemId} (the existing route, with ~own in place of a subscription id).
  • Typing no longer greys out publish. Autosave ran through the same busy state as publish and save draft, so every pause disabled both until the save returned. It now saves quietly; a publish clicked meanwhile waits for the save and publishes the newest text.
  • The side menu, done properly. On the left or right, one link per line in a narrow column; your name and title sit over the content rather than the menu; on a phone or a narrow window the menu folds behind a Menu button under your name instead of falling to the bottom of the page.
  • Find threads by search when choosing what the links section lists, instead of scrolling one long list.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 13, 2026

thread

Blygger Studio 0.44.0

Released 2026-10-12, the reference client. v0.44.0 on GitHub.

Migrations: none. The new settings are ordinary settings rows.

  • A links section on every public page (Settings → links section). It lists threads you choose, in your order (an About or Now page, say), your public collections, your own links (one per line, label | url), and a line of standard links: your blogroll as OPML when it lists anyone, Made with Blygger (blygger.org) and Find more blygs (blygger.com). Each group can be turned off; the standard links start on. It sits below the content by default, so no page moves on upgrade; choose left or right for a sidebar on wide screens, which falls below the content on a phone. A listed thread that is withdrawn drops out, and the front page's entry links to the root. Collections now appear here rather than at the foot of the home page and archive, unless that group is off.
  • Settings save after a withdrawal. A front page or listed thread that had since been withdrawn made every later Settings save fail, because the form sends each field back. A stored value is now accepted as it is, and a withdrawn listed thread is dropped.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 13, 2026

thread

Blygger Studio 0.43.0

Released 2026-10-12, the reference client. v0.43.0 on GitHub.

Migrations: none. Both new settings are ordinary settings rows, written only when the owner changes them.

  • A static front page, as on WordPress. Choose a published thread in Settings → home page, or with set as front page in the thread's ⋯ menu, and readers arriving at your blyg see it instead of your latest items. You edit it like any thread. The latest items move to {mount}/posts/, which every public page then links to in its header; the address is a setting (one lowercase segment; names the blyg already uses, such as feed, archive and studio, are refused) and is served whether or not a front page is set. The thread's permalink keeps working and names the root as canonical. The front page is left off the posts page but stays in feed.xml, the archive and items/index.json, so nothing changes on the wire. If it is later withdrawn, the root shows the latest items again. The static export saves the posts page too.
  • Canceled reads stay out of the error banner (#71, Kyle Mathews). TanStack Query cancels a pending read during normal updates, and the studio showed that as a CancelledError banner, intermittently, while editing.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 13, 2026

thread

Blygger Studio 0.42.0

Released 2026-10-12, the reference client. v0.42.0 on GitHub.

Migrations: 0029_feed_order_and_setup.sql (two settings rows, written only on a node that has published: feed_order = reverse-chronological and setup = notice). Apply it before deploying: wrangler d1 migrations apply <database> --remote. 0028 is reserved for the duplicate-upload guard (#7) and is not skipped by mistake.

  • A pace-layered home page: the diachronic view (docs/pace-layered-feed.md). Items sink as new ones arrive and climb one place with each new version. Pins slow the sinking: each unit of pin weight drops an item one of six layers (fashion to nature), each sinking at half the speed of the one above. An item's weight is its own pinned versions plus half the weight of each item that quotes it in a pinned version, out to six hops. An item pinned and revised often holds the top. It reads only what is public (changelog, pins, own-origin transclusions), so other clients can compute the same order; test/fixtures/feeds/ holds worked histories with their expected orders. Only the home page follows it: feeds and the archive stay newest first.
  • The home page order is a setting (Settings → home page): pace-layered, the default for a fresh install, or newest first. A node that has published keeps newest first until its owner chooses.
  • Extensions can add home page orders (docs/extensions.md, "Feed orders"). An order sees the same public history and returns ids; the page shows published items only, once each, and renders every card itself. extensions/feed-example ("Pinned first") is the template.
  • A setup walk-through (/studio/setup): you, look, home page, writing and AI, others, then a review. Every setting shows its current value and its default; nothing is saved until the end, and then only what changed. A fresh install is greeted with it; a node that had published is told once that it exists. Settings can run it again.
  • Discard changes leaves the item clean. It now restores the published version whole, its stub citation included, so a stub whose quote had moved on no longer showed "unpublished changes" that neither discard nor publish could clear. Publish also writes the version-agreed citation back to the working copy, which is how the two drifted apart.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 12, 2026

thread

Blygger Studio 0.41.1

Released 2026-10-10, the reference client. v0.41.1 on GitHub.

Migrations: none.

  • TK grammar quoted in code inside a scope is text (#68). The parser skipped code only when looking for an opening TK, so inside a scope a TK in a code span read as a nested scope and a [/TK] as its close, and an impyrt scope that quoted the grammar could not publish ("nested TK scopes are not supported"). Every token search now skips code.
  • The AI box's source links take the page's link colour instead of the browser default (0.41.0's "Drew on …" line).
  • CI (#67): Check runs its jobs in parallel and scopes a pull request's e2e and mutation suites to the files it changes; Release publishes after the tagged commit's green Check on main instead of rerunning the suite. Nothing an operator runs changes.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 11, 2026

thread

Soapbox for Blygger 0.1.2 is on WordPress.org

Released 2026-10-10 by Robert Peake, an independent client. Soapbox for Blygger on WordPress.org · source.

Soapbox for Blygger makes a WordPress site a blyg. Every post you publish also becomes an item, with a permanent id that survives edits, renames and moves, a new version each time its visible content changes, and withdrawal when a post goes back to draft. It needs WordPress 6.6 and PHP 7.4.

It's the client the manifest-template construct was written for (§16.6e, decision #51). WordPress serves the item and pin documents from its REST API rather than at the default paths, so the manifest says where they are, with item and pin URL templates. robertpeake.com was where that construct was exercised: a Blygger Studio node subscribed, quoted an item, and the mention verified on the WordPress side (gate G9).

At WordPress.org's request the plugin is now named Soapbox for Blygger (slug soapbox-for-blygger). Nothing a reader sees has changed; the manifest's generator now reads soapbox-for-blygger/<version>.

Live at robertpeake.com/blyg/.

Releases of independent clients are announced here by hand. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 11, 2026

thread

Blygger Studio 0.41.0

Released 2026-10-10, the reference client. v0.41.0 on GitHub.

Migrations: 0027_imported_generated.sql (imported_items.generated_json, and the imported-items change trigger recreated to watch it). Apply it before deploying: wrangler d1 migrations apply <database> --remote.

Protocol: the version key is now "0.4" in the manifest, item documents and pinned files. This build implements remote generation sources (spec 0.3 §16.3, decision #44), the first construct a receiver must act on to be correct; it is the build that opens the 0.4 document. Readers accept any 0.x value, so nothing that reads a blyg changes. A pinned file's content is unchanged; its blyg key reports what the serving deployment implements, as at 0.3.

  • A TK scope can draw on any item a quote can name (#44). Sources resolve like a directive: your published items of either kind, then an imported item that is current or withdrawn with a pinned snapshot kept. Threads and other blygs' items are sources now; drafts, plain RSS (L0) items and an id imported from two origins are refused by name. The generator reads the local snapshot, never a live fetch: a fragment's text, or a thread as its readers see it, quotes included.
  • A remote source is disclosed and notifies. Its generated[].sources[] entry carries origin and a cited frozen when the scope was generated, and publishing sends that blyg a mention. A receiver running this build verifies it as the new relation source and lists it publicly as "drew on this"; a 0.3 receiver reports it failed, which is correct for 0.3. An item that both quotes and draws on the same post sends one mention.
  • Imports keep generated verbatim (migration 0027): on GET /api/imports/{sub}/{id} as generated_json, and on GET /api/reading/imported as generated.
  • Studio. Typing ![[ in a scope's instruction, inline or on its own line, opens the picker as a source picker. The TK panel lists each scope's sources, "draws on Friend's Blyg · excerpt · its author is told", or why one would be refused, before you generate. The public "AI-generated" box lists remote sources by their citation. The syntax page is updated, including decision #60's rule that only the instruction names sources.
  • API: relation on mentions may be source; preview scopes carry sources; GenerationSource (id, version, origin?, cited?) types generated[].sources[].
  • The lineage-glyph extension ignores source mentions for now.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 10, 2026

thread

Blygger Studio 0.40.0

Released 2026-10-10, the reference client. v0.40.0 on GitHub.

Migrations: none. Six contributor PRs, merged together.

/api, all additive: GET /api/reading/imported (#61); Settings gains custom_theme, custom_theme_dark, custom_theme_name and font (#58); in GET /api/ai/models a provider's key_secret is optional and a Workers AI provider carries binding (#60); the lineage-glyph extension's two reads under /api/ext/lineage-glyph/ (#53, 404 unless compiled in and enabled).

Reading API (Aneesh Sathe, #61)

  • GET /api/reading/imported, under owner:read: every imported item, newest observed first, with the fields a client authors from (markdown, author, signal, hopper ids, the origin's transclusions, stubOf and forkedFrom verbatim, readVersion). Paged by an opaque keyset cursor over (observed_at, subscription, id), so ties split exactly and a poll between two requests never shifts or repeats rows. A cursor the server did not issue is a 400; limit is 1–100, default 50. For clients such as Blygger Desktop that would otherwise need one /imports/{sub}/{id} call per row.

Public pages (Aneesh Sathe, #62, closes #9)

  • A paragraph that is only a bare YouTube link becomes a click-to-play poster. Strict URL rule (YouTube's own hosts, video path shapes, an 11-character id, no credentials or port). The poster comes from i.ytimg.com with no referrer; nothing loads from YouTube itself until play, and then the player is youtube-nocookie.com. The link stays as the caption.
  • An off-origin image that fails to load becomes "Image: alt ↗ (host)", a link to it (a span inside an existing link, so links never nest).
  • Both are done by a page script on screen only: content_html, feeds and item JSON are unchanged, every version (pinned ones too) gets the same treatment, and with scripts off the link is a plain link.

Theme and typeface (Miguel, #58, roadmap row 4)

Custom theme. A Custom tile beside the presets opens an editor for the author's own palette: the same nine values a preset has (dark plus page, paper, ink, inkSoft, rule, pencil, genBg, genRule), so the public pages and the studio take it through the same path as any preset. It starts from whichever preset was showing, previews live, warns when text, secondary text, links or generated highlights fall below WCAG AA contrast on the paper (advisory, never blocking), and exports and imports the palette as JSON so a look can be passed from one blyg to another. Colours only: every value must be #rrggbb, checked in the studio and again by the server before it is stored, so nothing but a colour reaches style.css.

Light and dark. Follow the reader's light/dark setting adds a dark companion (custom_theme_dark): the custom theme then behaves like Auto, with the author's colours — the light palette in the base block, the dark one under prefers-color-scheme: dark, and the studio flipping with the device the same way. Most devices switch on their own now, and a custom theme that ignored that would be a step back from Auto. The pair must be coherent (light dark: false, companion dark: true, never a companion without a light half), checked in the studio and by the server. Without a companion, a custom palette is fixed, like a preset. A pair exports and imports as {"light": {…}, "dark": {…}}.

A name for the look. Name this look (custom_theme_name, optional, one line, at most 40 characters) labels the Custom tile and travels with the look when it is shared: {"name": "Pink Quill", "light": {…}, "dark": {…}}. It is shown as text and never reaches the stylesheet.

Switching to a preset keeps the palette, so switching back restores it; custom_theme: null clears it, and is refused while the theme in use is custom.

Reading typeface. A choice of eight system font stacks (from Modern Font Stacks, CC0): Book (the default, unchanged), Transitional, Humanist sans, Geometric sans, System sans, Rounded, Slab serif, Monospace. Each names fonts already on the reader's device, so nothing is downloaded and no third party sees a reader; "no web fonts" still holds. Only --serif changes, so all reading text follows the choice while the apparatus keeps its sans. Unknown ids are refused (400). Public pages only; the studio keeps its own type.

AI providers (Aneesh Sathe, #60, closes #8)

  • Cloudflare Workers AI (studio#8, after Aneesh Sathe's local patch). A workers-ai provider in models.json runs @cf/… models on the Worker's own ai binding, with no API key; Gemma 4 26B, Llama 4 Scout, Llama 3.3 70B and Mistral Small 3.1 are listed, and any @cf/… id can be typed in. The binding is commented out in wrangler.jsonc and in what npm run init writes: uncomment it to offer these models. Nothing runs on it until a model is chosen in Settings: still no default model and no fallback. Reasoning a model inlines into its answer is removed, and Gemma 4 is asked not to think.
  • OpenAI-compatible endpoints. An openai-chat provider calls any Chat Completions endpoint at its base_url (OpenRouter, Groq, Together, Cloudflare's OpenAI-compatible endpoint, a local Ollama), with its key in a Worker secret named by key_secret. Add one in models.local.json; README § AI models has an example. The build now refuses a manifest whose provider could not be called: an unknown api, a missing key secret or base URL, a base URL that is not https or carries credentials, or a key_secret naming OWNER_PASSWORD or COOKIE_SECRET.
  • Both spend the daily AI budget like every other provider.
  • API: in GET /api/ai/models, a provider's key_secret is now optional (absent for Workers AI and keyless endpoints) and a Workers AI provider carries binding. configured means the key is set, the binding is bound, or neither is needed.
  • Tests never reach real, billed Workers AI (remoteBindings: false).

Extensions (Aneesh Sathe, #53)

  • lineage-glyph, #35's lineage glyph, hex view and action ring, ported onto the extension mechanism. It has a server half (two owner reads), so it is compiled in by an operator and never ships in release archives; extensions.json is unchanged. Hrefs from foreign documents must pass isFollowableUrl.

Fixes

  • Composer tools place the caret at once (Aneesh Sathe, #64). TK, [[, ![[, link from clipboard, scan and the bracket picker placed the caret one animation frame late, so anything that selected or typed in between had its selection collapsed and appended instead of replacing. This was the CI flake in compose-pwa.spec.ts:179.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 10, 2026

thread

Blygger Studio 0.39.0

Released 2026-10-09, the reference client. v0.39.0 on GitHub.

Migrations: 0026_read_state.sql (a read_state table and five triggers). Apply it before deploying: wrangler d1 migrations apply <database> --remote.

  • Read state for imported items (Aneesh Sathe, #44 and #45). Reading entries show an unread dot. Opening an entry marks it read, and a select mode marks several read or unread at once, or the whole feed read. Read state is stored per imported item with the version you read, so a new version of an item shows as unread again. Marking unread leaves a tombstone, so a stale "read" from a client that was offline cannot undo it. It stays in the studio: nothing about it reaches the feed, the item documents or other blygs.
  • API: PUT and DELETE /api/reading/{sub}/{remoteId}/read, the batch routes POST /api/reading/read and POST /api/reading/unread (up to the batch limit in one write), and readVersion on GET /api/reading. A change advances the reading revision in GET /api/changes. Read state is deleted along with its imported item or subscription.
  • A new scope, reading:state, for marking read and unread. A reader app that only syncs read state does not need owner:manage, which can also delete subscriptions, and owner:manage does not include read state. Existing grants are unchanged; a client that wants read state asks for the new scope.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 10, 2026

thread

Blygger Studio 0.38.0

Released 2026-10-09, the reference client. v0.38.0 on GitHub.

Migrations: none.

  • Two extensions come with every release, both off. Until now releases compiled in no extensions, so trying the 0.37.0 mechanism meant building from source. Two browser-only ones now ship, each turned on in Settings → extensions:

    • Reading time puts an estimate at the end of each reading entry's byline ("· 4 min", the word count on hover). Words count at 230 a minute, Han, kana and Hangul characters at 500.
    • Inspect adds "inspect" to an entry's ⋯ sheet: the record this Studio holds for it (id, kind, version, state, content hash, stub_of, forked_from, transclusions) and its JSON with the bodies left out, with a copy button. It reads your own item or the imported copy through the existing API and fetches nothing from the item's origin.

    Neither has a server half or routes, and a test keeps anything that does out of extensions.json. An operator who wants neither can put {"remove": ["inspect", "reading-time"]} in extensions.local.json. The Settings card now appears on every node.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 9, 2026

thread

Blygger Studio 0.37.0

Released 2026-10-09, the reference client. v0.37.0 on GitHub.

Migrations: none.

  • Studio extensions (Aneesh Sathe, blygger-studio#52). A way to run UI experiments on a real node without them becoming the reference design. An extension is first-party TypeScript in extensions/<name>/, compiled in only when the operator lists it in a gitignored extensions.local.json, and then enabled per node in Settings → extensions. Releases compile none in, and with none enabled the Studio's markup is unchanged. Extensions get slots on the reading entry (byline, ⋯ sheet rows, a sheet of their own) and a page at /studio/ext/<name> linked from More. Server routes are owner reads only, at GET /api/ext/<name>/…, behind the owner API's auth, scope and budget middleware, and 404 while disabled. Nothing reaches the wire. Read the security model in docs/extensions.md before compiling one in: an extension's UI holds the owner's session. New setting: extensions (empty).
  • Fresh installs deploy again (ruthvik-947, blygger-studio#46). Since 0.28, npm run init wrote a config without nodejs_compat, so a new install's first deploy failed with No such module "node:crypto". Init now writes it, and CI checks that init's config and wrangler.jsonc agree on every runtime setting. An install that hit the error can add "compatibility_flags": ["nodejs_compat"] to its own wrangler.jsonc.
  • Autosave keeps one write in flight (Kyle Mathews, blygger-studio#47). Typing that outpaces the backend now merges into the latest pending save instead of queueing every snapshot; generate, publish, restore and delete still run in order after the saves before them. TanStack DB paced mutations replace the hand-written promise queues. Upgrades React DB to 0.5.7 and Query DB Collection to 1.4.2.
  • Shared item and hopper reads (Kyle Mathews, blygger-studio#55). Opening an editor makes one item request, and hopper collections share identical requests instead of each fetching the same response. A discarded draft no longer shows a false read-error banner.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 9, 2026

thread

Blygger Studio 0.36.1

Released 2026-10-07, the reference client. v0.36.1 on GitHub.

Migrations: none.

  • Webmention receiver: repeat claims and the verification queue. The hourly caps count rows, and a repeat claim for a source/target pair already stored adds none, so the same POST could be sent without limit, each time spending two outbound fetches and flipping a verified mention back to pending. A pair claimed again within a minute is now refused with a 429, and the stored row is left alone. A second cap refuses new claims while 30 are awaiting verification (rows touched in the last ten minutes, so a row whose verification died ages out). Both 429s now carry their own Retry-After (the remaining cooldown, or five minutes) instead of a flat hour. The per-host, per-domain and global hourly caps and the 30-day prune of failed rows (0.4.1) are unchanged.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 8, 2026

thread

Blygger Studio 0.36.0

Released 2026-10-07, the reference client. v0.36.0 on GitHub.

Migrations: none.

  • A generated block at the end of a post renders as a block. A scope followed by a single trailing newline (or preceded by a leading one) was taken as sharing a paragraph with prose, so its disclosure rendered inline. The edges of the document now count as blank lines, whitespace and one newline included. publish_blyg.py had worked around this by stripping the final newline; the workaround is no longer needed.
  • Author URL in settings. author.url in item documents was always the blyg's own address. A new author_url setting (Settings → profile) sets it; blank keeps the old behaviour. Must be an absolute http(s) URL.
  • [[id]] links take a heading as their text. When the target opens with a heading (a thread's H1 is its title by convention) the link reads as that heading, in plain text; otherwise the quoted excerpt is used as before. Frozen into content_html at publish, so existing posts are unchanged until republished.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 8, 2026

thread

Blygger Studio 0.35.1

Released 2026-10-07, the reference client. v0.35.1 on GitHub.

Migrations: none.

  • An absolute page is used as it is. §16.6e lets a blyg's permalinks live outside its mount (Soapbox's are WordPress post URLs), but every link built from page glued it onto the origin, giving https://site/blyg/https://site/archives/…. That covered reading-view source links, quote attribution, stub citations, and the target of every mention sent to such a blyg, so a mention to Soapbox would have failed on arrival. Found subscribing the official blyg to robertpeake.com.

Protocol: implements 0.3 (eleventh revision), plus the reader half of the §16.6e 0.4 shape.

This announcement is drafted from the release's section of CHANGELOG.md, which is where it is maintained. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 8, 2026

thread · 1 quoted

Blygger Studio 0.35: reading blygs that live on WordPress

Until now, every blyg kept its files at fixed paths under its origin: items/{id}.json, feed.xml, items/index.json. A managed WordPress host cannot serve those paths without rewrite rules that shared hosting often forbids, so the largest CMS on the web could not publish a blyg.

Spec §16.6e changes that. A manifest may now say where everything lives, as URLs and templates. The first blyg to use it is Robert Peake's, published by his WordPress plugin Soapbox at robertpeake.com/blyg/: 853 posts, with every file on WordPress's REST routes.

Blygger Studio 0.35 reads it. This blyg subscribes to his, and here is a passage from one of his posts, quoted through his own templates:

Taking up the idea of protocols as engineered arguments, this talk explores the timeless algorithms that give poetry its power to evolve—from an ancient mnemonic device to a transformational way of being.

from Robert Peake ↗ · excerpt of v1

Publishing this sends his blyg a mention, and his blyg checks it against our surface, as ours checks his. When that check passes, §16.6e has been exercised end to end by two independent clients, which is the condition for it to become normative in the 0.4 spec.

Release notes: 0.35.0 and 0.35.1. If you run blygger-studio, apply migration 0025 before upgrading.

read the thread →

Created: Oct 7, 2026

thread

Introducing the official Blygger blyg

This is the official blyg of the blygger protocol. It sits beside blygger.org, which keeps the spec, and blygger.com, the directory of blygs. Anything about the protocol that announces a change or asks for a response is published here, so this is the one place to follow the project from a reader.

What appears here:

  • RFCs. Proposed conventions for clients, published for a comment period before any client builds them, so that a convention reaches the reference client only after other implementers have had their say. Each RFC is a thread, and the version under comment is pinned. To comment, respond from your own blyg: a stub is a comment, a partial quote names the passage you are answering, and a fork of the pinned version is a counter-proposal. Each RFC also links a GitHub issue for anyone without a blyg. The first two cover mentions across identifier schemes and comments sections.
  • Release announcements from every client. Releases of the reference client, and of any other blygger client, tool or integration. If you maintain one, open an issue on blygger/blygger-spec when you ship and the release will be announced here.
  • Technical notes. The design reasoning behind the spec, especially the designs it rejected, starting with TN-1 (versioning and pins) and TN-3 (groups). Their canonical text stays at blygger.org/notes/, which the spec cites; the copies here are where they take responses.
  • Spec revisions and snapshots, each announced with what changed.

What stays elsewhere: the spec itself, at blygger.org/spec/, and the reference pages on blygger.org such as the ecosystem list.

On bylines: most of what appears here is drafted by AI models and approved by Venkatesh Rao, whose name is the byline. Each such item discloses the model that wrote it, as this one does.

To follow, subscribe to https://blyg.blygger.org/ from any blyg-aware reader, or add https://blyg.blygger.org/feed.xml to an ordinary feed reader.

read the thread →

v2

“Markup fix: the post rendered inside a stray inline span.”

Created: Oct 7, 2026 Most recent: Oct 7, 2026, v2

thread

TN-1 — Versioning stays a bare counter: semver, editions, and the pin pattern

Technical note · non-normative · session 12, 2026-08-10 (Fable + Venkat). Decision record for locked decision #19. Technical notes record design reasoning — especially rejected designs — alongside the normative spec; they constrain nothing and are citable rationale, not protocol.

1. The question

Item versions are a bare integer counter: version increments by exactly 1 per publish event (spec §5.2). Venkat proposed switching to semantic versioning so that version structure could carry an author-asserted significance signal — the motivating use case being client-side auto-pinning heuristics ("a node might declare a rule that every major version change be auto-pinned"), with the auto-pinning logic itself explicitly outside protocol scope.

The underlying need is real: a machine-readable way for an author to mark a publish event as significant, which client features can key off. The question is whether version structure is the right carrier. Two designs were considered and both rejected; the reasoning is worth keeping because the question will recur.

2. Why not semantic versioning

Three independent arguments, each sufficient:

  1. The counter's rigidity is load-bearing. "Increments by exactly 1" means a version number alone tells an importer exactly how many publish events it missed, and any decrease is unambiguously a history rewrite — the no-silent-regression watermark (decision #18) leans directly on this. Under semver, "+1 exactly" becomes "some component incremented": is 2.3 → 4.0 a gap? Is 2.0 → 1.9.1 a regression or intent? Every comparison becomes structured parsing, and origin violations stop being crisply detectable.
  2. The counter is wire-permanent surface. It rides in the GUID scheme (blyg:{id}:v{n}), pin URLs (items/{id}/v{n}.json), transclusions provenance, and the reserved ![[id@vN]] and forked_from shapes (decisions #14/#16). With two live nodes deployed, restructuring it is the protocol's first breaking wire migration — a cost that only grows.
  3. Semver encodes the wrong semantics. Its parts are API compatibility claims — patch-vs-minor is a statement about callers not breaking. Prose has no callers. Whatever significance structure writing has, it is not three-valued compatibility.

3. The edition counter-proposal (recorded, also rejected)

An intermediate design was drafted: keep version untouched and add an optional author-asserted "edition" integer (default 1, monotonically non-decreasing, bumped as a deliberate publish-time act). Publishing-native ("second edition"), additive, zero wire breakage; auto-pin heuristics key off edition bumps; a semver-looking display ({edition}.{rev}) derivable as pure presentation.

Rejected by Venkat — not on cost grounds (the cost is near zero) but on design-intent grounds, which is the actual content of this note:

4. The pin pattern is the significance primitive

The protocol already has a construct for "this state of this work matters": the pin — an irrevocable promise to serve one exact version forever (spec §8). The design intent is that publishers think consciously in pins, and a parallel significance lane would obscure that:

  • An edition bump is cheap talk; a pin is a costly signal. Marking a version "major" costs nothing and promises nothing. A pin costs an irrevocable hosting commitment. The protocol prefers the significance signal an author must back with a promise — that asymmetry is what makes the signal honest, and it would be exactly the asymmetry a free-floating significance field lets authors route around.
  • Version-structure significance is publishing skeuomorphism. Editions and major versions are conventions imported from books and software — cosmetic structure over what is, in this medium, a single living stream of states with deliberate frozen citations. The medium's own native gesture is the pin; dressing the stream up in edition numbers teaches publishers the wrong mental model.
  • The motivating feature doesn't need the field. "Auto-pin on major bump" dissolves into pin-suggestion UX: a studio may prompt, nudge, batch, or apply any local rule it likes for proposing pins — studio sugar, zero protocol bytes. This is the standing pattern's next application: AI, identity, and editorial convenience are never in the protocol; neither is significance markup. What reaches the wire is the pin itself.

Human-readable significance keeps its existing home: the changelog note (free text, per publish event). Machine-readable significance is the pin.

5. What stands

  • version remains a bare positive integer, +1 per publish event — the protocol's ordering primitive, unchanged everywhere it appears.
  • No semver, no edition field, no significance markup on the wire, at any level. This is locked decision #19; relitigating it starts from this note.
  • Clients remain free to build any pinning convenience (prompts, local rules, batch review) on studio-side state — the protocol surface they produce is ordinary deliberate pins.

This note's canonical text is at blygger.org/notes/tn-1/, and its source is docs/notes/tn-1-versioning-and-pins.md in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.

read the thread →

Created: Oct 7, 2026