{"blyg":"0.4","id":"2d244a6ff5tz7mfe5gd4m41a4p","kind":"thread","version":1,"at":"2026-11-22T00:01:44Z","note":"TN-8: the contributor guide, made a technical note.","pinned":true,"origin":"https://blyg.blygger.org/","author":{"name":"Venkatesh Rao","url":"https://blyg.blygger.org/"},"content_md":"\n# TN-8 — Where does my change belong? A contributor's map\n\n**Technical note · non-normative · 2026-11-21 (session 78).** First written for the\n2026 hackathon as `blygger-studio/docs/where-does-it-go.md` (session 74, 2026-11-18) and\npublished at [blygger.org/contribute/](https://blygger.org/contribute/); made a note so\nthat it is numbered, cited and announced like the others (Venkat, session 78). It maps\nwhere a change belongs across the four repositories, with the Studio as the worked\nexample: the protocol decides nothing here, and other clients may draw their own ladder.\nRevised as the Studio changes; the studio file is now a pointer to this one.\n\nYou 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.\n\nThis 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](#your-first-hour).\n\n## The ladder\n\nAnswer these questions in order and **stop at the first yes**.\n\n| # | Question | Then it is | It goes to |\n|---|---|---|---|\n| 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](https://github.com/blygger/blygger-spec/issues/new/choose) |\n| 2 | Is it a bug, or something every blyg would want with no setting? | **A pull request to the Studio** | [blygger-studio](https://github.com/blygger/blygger-studio) |\n| 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 |\n| 4 | Is it interface for one owner, in the browser, in a slot that already exists? | **An extension** | [blygger-studio](https://github.com/blygger/blygger-studio), or your own repository, vendored in |\n| 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](https://github.com/blygger/blygger-studio) |\n| 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 |\n| 7 | Does it only make sense on your node (your branding, your infrastructure), with no general form? | **A local patch** | Your own deployment |\n| 8 | Does it need to change what the Studio is? | **Another client** | A fork with its own name |\n\nThe 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.\n\n### 1. A spec question\n\nThis 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](https://github.com/blygger/blygger-spec), not built first and argued about afterwards.\n\nExpect to hit these refusals in your first hour. [`protocol-v0.4.md` §16.8](https://github.com/blygger/blygger-spec/blob/main/docs/protocol-v0.4.md) 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.\n\n**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`](https://github.com/blygger/blygger-studio/blob/main/docs/studio-style.md).\n\n### 2. A pull request to the Studio\n\nBugs, 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.\n\nWhat review looks like:\n- `npm test` must pass.\n- 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.\n- A reviewer may push a small fix to your branch and say so.\n- Your PR description may carry instructions for the reviewer, such as \"demo this before merging\", and will be read in full before merge.\n\n### 3. A tool or configuration\n\nA tool that acts as an editor would. It creates items, edits settings and pins versions through `{mount}/api` on a [scoped token](https://github.com/blygger/blygger-studio/blob/main/docs/client-access.md), 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`](https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#1-configuration-through-the-owner-api) and the [owner API guide](https://github.com/blygger/blygger-studio/blob/main/docs/api.md).\n\n### 4. An extension\n\nCode 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`](https://github.com/blygger/blygger-studio/blob/main/docs/extensions.md), and [`extension-vendoring.md`](https://github.com/blygger/blygger-studio/blob/main/docs/extension-vendoring.md) for one kept in your own repository.\n\n### 5. A hook, proposed upstream\n\nWhen 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`](https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#the-bar-a-hook-must-clear)):\n\n- [ ] **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.\n- [ ] **Wire-silent.** It does not change the bake, `feed.xml`, item documents or `blyg.json`.\n- [ ] **Read-only on the server.** Writes happen in the browser through the extension's `client`, or from outside on a token.\n\nSay which mod needs it and why rungs 3 and 4 do not reach.\n\n### 6. A mod\n\nA mod is a kind of blyg, not a pile of settings. [blykker](https://github.com/blygger/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`](https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#three-promises-a-mod-keeps)): the generator string stays `blygger-studio/x.y.z`, model text it inserts is disclosed, and it does not fork.\n\n### 7. A local patch\n\nSomething 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](#local-patches) below make that cheap.\n\n### 8. Another client\n\nIf 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](https://github.com/blygger/blygger-studio/blob/main/README.md#if-you-fork-this).\n\n## Your first hour\n\nTested 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).\n\n```sh\ngit clone https://github.com/blygger/blygger-studio.git\ncd blygger-studio\ngit switch -c my-work\nnpm ci\n```\n\n`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`.\n\nCreate `.dev.vars`, which is ignored by git, with a local password and cookie secret:\n\n```sh\nprintf 'OWNER_PASSWORD=pick-a-local-password\\nCOOKIE_SECRET=%s\\n' \"$(openssl rand -hex 32)\" > .dev.vars\n```\n\nCompile in the `example` extension. `extensions.local.json` is ignored by git too:\n\n```sh\necho '{ \"compile\": [\"example\"] }' > extensions.local.json\n```\n\n**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:\n\n```sh\nnpx wrangler d1 migrations apply DB --local\nnpm run dev\n```\n\nOpen `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.\n\nWhen 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.\n\n### Never develop against a live blyg\n\nUse 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.\n\n## Local patches\n\nA 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.\n\n1. **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.\n2. **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.\n3. **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.\n4. **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](https://github.com/blygger/blygger-studio/blob/main/README.md#if-you-fork-this) and read every release's `Migrations:` line. The third breaks the ecosystem census and update notices.\n5. **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.\n6. **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.\n7. **Tell us what you patched**, in the [local patches issue](https://github.com/blygger/blygger-studio/issues/150). 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.\n\n`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`.\n\nA 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](https://github.com/blygger/blygger-studio/blob/main/README.md#install-from-source).\n\n## Ideas to start from\n\nOne for each of the main rungs, so you can see the ladder applied:\n\n- **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](https://github.com/blygger/blygger-spec/blob/main/docs/v0.4-plan.md); the backlog entry is in [`backlog.md` §2](https://github.com/blygger/blygger-spec/blob/main/docs/backlog.md).\n- **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.\n- **Rung 3:** a script that imports a folder of Markdown notes as drafts through the owner API.\n- **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.\n- **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.\n- **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.\n\n## Working with an AI agent\n\nPoint your agent at [`AGENTS.md`](https://github.com/blygger/blygger-studio/blob/main/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.\n\n## Where to ask\n\n- **A protocol question or proposal:** an issue on [blygger-spec](https://github.com/blygger/blygger-spec/issues/new/choose).\n- **A Studio bug or feature:** an issue on [blygger-studio](https://github.com/blygger/blygger-studio/issues/new/choose).\n- **Something you built that speaks Blygger,** to have it listed: [blygger-org](https://github.com/blygger/blygger-org/issues/new/choose).\n\nWhen an issue is accepted, it gets a row in the [public roadmap](https://blygger.org/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.\n\n\n\n*This note's canonical text is at [blygger.org/notes/tn-8/](https://blygger.org/notes/tn-8/), and its source is [`docs/notes/tn-8-where-does-my-change-belong.md`](https://github.com/blygger/blygger-spec/blob/main/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.*\n","content_html":"<div class=\"blyg-tk-gen\"><h1>TN-8 — Where does my change belong? A contributor's map</h1>\n<p><strong>Technical note · non-normative · 2026-11-21 (session 78).</strong> First written for the\n2026 hackathon as <code>blygger-studio/docs/where-does-it-go.md</code> (session 74, 2026-11-18) and\npublished at <a href=\"https://blygger.org/contribute/\">blygger.org/contribute/</a>; made a note so\nthat it is numbered, cited and announced like the others (Venkat, session 78). It maps\nwhere a change belongs across the four repositories, with the Studio as the worked\nexample: the protocol decides nothing here, and other clients may draw their own ladder.\nRevised as the Studio changes; the studio file is now a pointer to this one.</p>\n<p>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.</p>\n<p>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 <a href=\"#your-first-hour\">first hour</a>.</p>\n<h2>The ladder</h2>\n<p>Answer these questions in order and <strong>stop at the first yes</strong>.</p>\n<table>\n<thead>\n<tr>\n<th>#</th>\n<th>Question</th>\n<th>Then it is</th>\n<th>It goes to</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>1</td>\n<td>Would it change the bytes another blyg or reader receives (an item document, the feed, <code>blyg.json</code>, <code>content_html</code>), or would another client have to change to work with it?</td>\n<td><strong>A spec question.</strong> Nothing is built until it is ruled</td>\n<td>An issue on <a href=\"https://github.com/blygger/blygger-spec/issues/new/choose\">blygger-spec</a></td>\n</tr>\n<tr>\n<td>2</td>\n<td>Is it a bug, or something every blyg would want with no setting?</td>\n<td><strong>A pull request to the Studio</strong></td>\n<td><a href=\"https://github.com/blygger/blygger-studio\">blygger-studio</a></td>\n</tr>\n<tr>\n<td>3</td>\n<td>Can it be done from outside, with a token, through <code>{mount}/api</code> and Settings, with no code inside the Studio?</td>\n<td><strong>A tool or configuration</strong></td>\n<td>Your own repository</td>\n</tr>\n<tr>\n<td>4</td>\n<td>Is it interface for one owner, in the browser, in a slot that already exists?</td>\n<td><strong>An extension</strong></td>\n<td><a href=\"https://github.com/blygger/blygger-studio\">blygger-studio</a>, or your own repository, vendored in</td>\n</tr>\n<tr>\n<td>5</td>\n<td>Does it need a slot or setting the Studio lacks, in a form any blyg could use?</td>\n<td><strong>A hook, proposed upstream</strong></td>\n<td>A pull request to <a href=\"https://github.com/blygger/blygger-studio\">blygger-studio</a></td>\n</tr>\n<tr>\n<td>6</td>\n<td>Is it several of 3 to 5 together, making a kind of blyg (a book, a course, a lab notebook)?</td>\n<td><strong>A mod</strong></td>\n<td>Its own repository</td>\n</tr>\n<tr>\n<td>7</td>\n<td>Does it only make sense on your node (your branding, your infrastructure), with no general form?</td>\n<td><strong>A local patch</strong></td>\n<td>Your own deployment</td>\n</tr>\n<tr>\n<td>8</td>\n<td>Does it need to change what the Studio is?</td>\n<td><strong>Another client</strong></td>\n<td>A fork with its own name</td>\n</tr>\n</tbody>\n</table>\n<p>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.</p>\n<h3>1. A spec question</h3>\n<p>This question comes first because <strong>most ideas that sound like features are changes to the wire</strong>: 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 <a href=\"https://github.com/blygger/blygger-spec\">blygger-spec</a>, not built first and argued about afterwards.</p>\n<p>Expect to hit these refusals in your first hour. <a href=\"https://github.com/blygger/blygger-spec/blob/main/docs/protocol-v0.4.md\"><code>protocol-v0.4.md</code> §16.8</a> 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 <strong>Protocol proposal</strong> template and describe the problem before the solution.</p>\n<p><strong>What a page looks like is not a spec question.</strong> 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 <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/studio-style.md\"><code>studio-style.md</code></a>.</p>\n<h3>2. A pull request to the Studio</h3>\n<p>Bugs, and anything every blyg would want with no setting. <strong>The Studio should be boring.</strong> 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.</p>\n<p>What review looks like:</p>\n<ul>\n<li><code>npm test</code> must pass.</li>\n<li>CI also runs the browser suite (<code>npm run test:e2e</code>) and <code>npm run check:template</code>, which checks that the committed repository carries nobody's deployment.</li>\n<li>A reviewer may push a small fix to your branch and say so.</li>\n<li>Your PR description may carry instructions for the reviewer, such as &quot;demo this before merging&quot;, and will be read in full before merge.</li>\n</ul>\n<h3>3. A tool or configuration</h3>\n<p>A tool that acts as an editor would. It creates items, edits settings and pins versions through <code>{mount}/api</code> on a <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/client-access.md\">scoped token</a>, 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 <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#1-configuration-through-the-owner-api\"><code>mods.md</code></a> and the <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/api.md\">owner API guide</a>.</p>\n<h3>4. An extension</h3>\n<p>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 <code>/api/ext/&lt;name&gt;/</code>, a home page order. Nothing loads at run time, server routes are reads only, and nothing reaches the wire. Copy <code>extensions/example/</code>. See <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/extensions.md\"><code>extensions.md</code></a>, and <a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/extension-vendoring.md\"><code>extension-vendoring.md</code></a> for one kept in your own repository.</p>\n<h3>5. A hook, proposed upstream</h3>\n<p>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 (<a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#the-bar-a-hook-must-clear\"><code>mods.md</code></a>):</p>\n<ul>\n<li>[ ] <strong>General.</strong> It is named for what it does, not for the mod that wants it. A &quot;book layout&quot; slot is refused; an owner stylesheet would be considered.</li>\n<li>[ ] <strong>Wire-silent.</strong> It does not change the bake, <code>feed.xml</code>, item documents or <code>blyg.json</code>.</li>\n<li>[ ] <strong>Read-only on the server.</strong> Writes happen in the browser through the extension's <code>client</code>, or from outside on a token.</li>\n</ul>\n<p>Say which mod needs it and why rungs 3 and 4 do not reach.</p>\n<h3>6. A mod</h3>\n<p>A mod is a kind of blyg, not a pile of settings. <a href=\"https://github.com/blygger/blykker\">blykker</a>, the first, keeps a blyg arranged as a book. It began as a <code>book.json</code> and a script on the owner API, added extensions second, and proposed hooks upstream third. A mod keeps three promises (<a href=\"https://github.com/blygger/blygger-studio/blob/main/docs/mods.md#three-promises-a-mod-keeps\"><code>mods.md</code></a>): the generator string stays <code>blygger-studio/x.y.z</code>, model text it inserts is disclosed, and it does not fork.</p>\n<h3>7. A local patch</h3>\n<p>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 <a href=\"#local-patches\">Local patches</a> below make that cheap.</p>\n<h3>8. Another client</h3>\n<p>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 <a href=\"https://github.com/blygger/blygger-studio/blob/main/README.md#if-you-fork-this\">If you fork this</a>.</p>\n<h2>Your first hour</h2>\n<p>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).</p>\n<pre><code class=\"language-sh\">git clone https://github.com/blygger/blygger-studio.git\ncd blygger-studio\ngit switch -c my-work\nnpm ci\n</code></pre>\n<p><code>npm ci</code> also builds the Studio. npm 11 warns that the install scripts of <code>esbuild</code>, <code>fsevents</code> and <code>workerd</code> are not covered by <code>allowScripts</code>. The build and the dev server work anyway. If a fresh <code>npm install</code> without the lockfile crashes in the peer resolver (npm 10.9 does), add <code>--legacy-peer-deps</code>.</p>\n<p>Create <code>.dev.vars</code>, which is ignored by git, with a local password and cookie secret:</p>\n<pre><code class=\"language-sh\">printf 'OWNER_PASSWORD=pick-a-local-password\\nCOOKIE_SECRET=%s\\n' &quot;$(openssl rand -hex 32)&quot; &gt; .dev.vars\n</code></pre>\n<p>Compile in the <code>example</code> extension. <code>extensions.local.json</code> is ignored by git too:</p>\n<pre><code class=\"language-sh\">echo '{ &quot;compile&quot;: [&quot;example&quot;] }' &gt; extensions.local.json\n</code></pre>\n<p><strong>Apply the database migrations by hand before the first run.</strong> <code>wrangler dev</code> does not apply them, and the test suite applies its own, so nothing else will tell you:</p>\n<pre><code class=\"language-sh\">npx wrangler d1 migrations apply DB --local\nnpm run dev\n</code></pre>\n<p>Open <code>http://localhost:8787/studio</code>, sign in with your local password, write a fragment and publish it. It appears at <code>http://localhost:8787/feed.xml</code>. In <strong>Settings → extensions</strong>, check <code>example</code> and save: it fills every slot with something visible and harmless, so you can see where yours would go.</p>\n<p>When you add migrations later, run <code>wrangler d1 migrations apply DB --local</code> again. To run the browser tests, <code>npx playwright install chromium</code> once, then <code>npm run test:e2e</code>. The suite starts its own server on port 8789, so run only one copy at a time on one machine.</p>\n<h3>Never develop against a live blyg</h3>\n<p>Use a local database and <code>npm run dev</code>. 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.</p>\n<h2>Local patches</h2>\n<p>A source installation's <code>npm run upgrade</code> 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.</p>\n<ol>\n<li><strong>Try the places that are not patches first.</strong> Settings, a theme, the local files (<code>extensions.local.json</code>, <code>models.local.json</code>, <code>wrangler.private.jsonc</code>) and an extension all survive every upgrade by construction.</li>\n<li><strong>One patch, one commit, on your own branch,</strong> with a message that starts <code>local:</code> and says why in a line. Never leave a patch uncommitted or in a stash. A stash is how a patch gets lost.</li>\n<li><strong>Add rather than edit where you can.</strong> A new file never conflicts. Keep an edit to a shared file to as few lines as possible, with no reformatting around it.</li>\n<li><strong>Harmless means three things.</strong> The patch does not change what the blyg serves to others (item documents, the feed, <code>blyg.json</code>, <code>content_html</code>). It adds no migration and changes no table. It does not rename the client (<code>generator</code>). 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 <code>9000_</code> as <a href=\"https://github.com/blygger/blygger-studio/blob/main/README.md#if-you-fork-this\">the README asks</a> and read every release's <code>Migrations:</code> line. The third breaks the ecosystem census and update notices.</li>\n<li><strong>Every patch names its exit:</strong> 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.</li>\n<li><strong>Upgrade often.</strong> One release at a time means a small conflict or none; five at once is an afternoon. Security fixes arrive only by upgrading.</li>\n<li><strong>Tell us what you patched</strong>, in the <a href=\"https://github.com/blygger/blygger-studio/issues/150\">local patches issue</a>. 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.</li>\n</ol>\n<p><code>npm run patches</code> lists your local commits since the release you are on, flags any without the <code>local:</code> label, and warns about any that touch the files rule 4 is about. <code>npm run upgrade</code> prints the same list before it merges and names the commits that conflicted after. Studio's <strong>Settings → updates</strong> 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 <code>blyg.json</code>.</p>\n<p>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 <a href=\"https://github.com/blygger/blygger-studio/blob/main/README.md#install-from-source\">source installation</a>.</p>\n<h2>Ideas to start from</h2>\n<p>One for each of the main rungs, so you can see the ladder applied:</p>\n<ul>\n<li><strong>Rung 1, answered no: suggested edits.</strong> It sounds like a protocol change: &quot;propose a change to someone else's post&quot;. 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 &quot;suggest an edit&quot;, and a view that shows incoming <code>fork</code> mentions as diffs against the owner's pin. Reasoning in the spec's <a href=\"https://github.com/blygger/blygger-spec/blob/main/docs/v0.4-plan.md\"><code>v0.4-plan.md</code> §25</a>; the backlog entry is in <a href=\"https://github.com/blygger/blygger-spec/blob/main/docs/backlog.md\"><code>backlog.md</code> §2</a>.</li>\n<li><strong>Rung 1, answered yes:</strong> any wire idea (a new item field, a typed relation), written up as a proposal issue with the problem first, and not built.</li>\n<li><strong>Rung 3:</strong> a script that imports a folder of Markdown notes as drafts through the owner API.</li>\n<li><strong>Rung 4:</strong> a reading-view extension, such as a byline badge or a sheet that summarizes a thread's sources. <code>reading-time</code> and <code>word-count</code> are small working examples.</li>\n<li><strong>Rung 5:</strong> 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.</li>\n<li><strong>Rung 6:</strong> 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.</li>\n</ul>\n<h2>Working with an AI agent</h2>\n<p>Point your agent at <a href=\"https://github.com/blygger/blygger-studio/blob/main/AGENTS.md\"><code>AGENTS.md</code></a> 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.</p>\n<h2>Where to ask</h2>\n<ul>\n<li><strong>A protocol question or proposal:</strong> an issue on <a href=\"https://github.com/blygger/blygger-spec/issues/new/choose\">blygger-spec</a>.</li>\n<li><strong>A Studio bug or feature:</strong> an issue on <a href=\"https://github.com/blygger/blygger-studio/issues/new/choose\">blygger-studio</a>.</li>\n<li><strong>Something you built that speaks Blygger,</strong> to have it listed: <a href=\"https://github.com/blygger/blygger-org/issues/new/choose\">blygger-org</a>.</li>\n</ul>\n<p>When an issue is accepted, it gets a row in the <a href=\"https://blygger.org/roadmap/\">public roadmap</a> 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.</p>\n</div>\n<div class=\"blyg-tk-gen\"><p><em>This note's canonical text is at <a href=\"https://blygger.org/notes/tn-8/\">blygger.org/notes/tn-8/</a>, and its source is <a href=\"https://github.com/blygger/blygger-spec/blob/main/docs/notes/tn-8-where-does-my-change-belong.md\"><code>docs/notes/tn-8-where-does-my-change-belong.md</code></a> in blygger-spec. The page there is what the spec cites. To comment, respond to this item from your own blyg.</em></p>\n</div>\n","content_hash":"sha256:2408244fb38ca1114c3c74100945808d519c398285210831d07feaf581219873","transclusions":[],"generated":[{"sources":[],"model":"claude-opus-5-5"},{"sources":[],"model":"claude-opus-5-5"}]}