Home / Replicate / The reader API: a map, and a review
Phase 0 of the move: map
The reader API: a map, and a review
Everything a reader does on this site, before it moves: the files and their hashes, what a reader can click, type or pay, where their data goes, the contracts other sites and agents program against, and what a line-by-line review found.
“API” here means what the brief means by it: client-side. Components, formats and contracts the browser runs, with no server of ours and nothing to deploy but files. It is what other sites and agents program against: the meter’s configuration, the reading-list link, the article numbers, the persona links, the share’s envelope. This page maps all of it as it is at v0.12.72, before anything moves, and reviews it. It is regenerated on every build from the tree, and from the tables kept beside the code in admin/build/api_map.py; the same map is map.json, and the review is also a note.
What the hashes are for. The brief’s rule for the move is that the live site serves the same bytes after it as before, proved by hash and not by reading the diff. The hashes below are that “before”: scripts, styles and JSON raw; pages with the site chrome and version stamps normalised, as the gate already does for imported pages. They change when the files change, and they are meant to.
In numbers
| Reader code that runs in a browser | 10,263 lines in 47 files; 5,697 more lines in 20 frozen files of earlier meter versions, served and never changed |
| Pages that carry it | 30 pages written for it; the balance chip and a charged-page element on every page of the site |
| Views, controls, inputs | 12 views of one element, 56 kinds of control, 11 ways data comes in, 9 ways it goes out |
| Contracts | 14, listed below; the two that other sites and agents already program against are the reading-list link and articles/ids.json |
| Tests | 511 check calls in three files (loops make more checks at run time), now run in CI before a tag (R11) |
| Pages with a Content-Security-Policy | 0 (R10) |
| Upstreams | two: sgit.ai for the account pages, subscribe, the contact file and the meter to 1.3.1, rewritten on import to this site's 1.4.0 (R12) |
The files
The code a reader runs, where it comes from, and what each file reaches for. 5 of the 47 code files come from sgit.ai byte for byte and cannot be changed here by a rule of the import; that is R4 and R12 below.
| File | What it is | From | Lines | Reaches | SHA-256 (normalised for pages) |
|---|---|---|---|---|---|
assets/components/sg-meter/v1/v1.4/v1.4.1/sg-meter.js | SG Meter, the element: twelve views, the reader card, the share form, the graph | this site, from sgit.ai's v1.3.1 | 817 | 2 fetch, sg:meter.changed, confirm(), WebCrypto | ba46eeca15d5d9b2 |
assets/components/sg-meter/v1/v1.4/v1.4.1/sg-meter-core.js | SG Meter, the meter: prices, the charge, ratings, declining, credit, personas, picks, the share text | this site, from sgit.ai's v1.3.1 | 513 | 1 fetch, localStorage, sessionStorage, sg:meter.changed, sg:meter.charged, sg:meter.declined, sg:meter.persona, sg:meter.reset, sg:meter.restored, sg:meter.shared, sg:meter.toppedup | 9986294b0fbc5a62 |
assets/components/sg-meter/v1/v1.4/v1.4.1/sg-meter.css | SG Meter styles, adopted into the shadow root | this site, from sgit.ai's v1.3.1 | 192 | — | 3f464b7d1df4e15f |
assets/components/sg-meter/v1/v1.4/v1.4.1/sg-meter.tpl | SG Meter markup (one div) | this site, from sgit.ai's v1.3.1 | 1 | — | 104c7c1ded976408 |
assets/components/base/v1/v1.0/v1.0.0/sg-component.js | The component base: fetches the .tpl and .css beside a component and calls onReady() | sgit.ai, verbatim | 118 | 1 fetch, sg-meter:error, innerHTML | e566a78ad98fbd18 |
for/reading-list.js | A reading list in a link: parse, build, show, open as a persona | this site | 343 | 1 fetch | 5f8fa1378b99c24c |
for/make.js | The page that makes a reading list and previews it | this site | 254 | 1 fetch | ec9abc1f40b5f564 |
for/for.css | Styles for the two reading-list pages | this site | 109 | — | 6ad9b2f9c39e9974 |
assets/subscribe.js | The subscribe form: encrypts the address and posts it to the lane | sgit.ai, verbatim | 117 | 2 fetch, WebCrypto | fe2eec58c28f15e5 |
wire/vault-reader.js | Reads an sgit vault in the browser with a published read key: ref, commit, tree, blobs, decrypted with Web Crypto; the markdown renderer | this site, vendored from sgit.ai's vault-docs.js | 182 | 1 fetch, WebCrypto | 332509b6be44538d |
wire/graphs.js | The wires' graphs: a provenance strip per story, stories per day by beat, the threads on a date axis, the entities stories share, a sources tally, a story-by-persona matrix; SVG from the bundle, text nodes only, colours as theme tokens | this site | 356 | — | 22f48fcb1185389f |
admin/build/infographics.py | One card per story and one hero per edition through dev.tools.sgraph.ai, with a cost ledger per edition and per wire; the key from the environment only, a dry run without it | this site | 704 | hosts: dev.tools.sgraph.ai, openrouter.ai | c5dee92d109b48eb |
wire/wire.js | The wires: the edition with its lens, release notes and corrections, a map or a stack when the vault has one, the sources, the documents, drawn from the vault as text; one code for every wire | this site | 604 | 2 fetch, localStorage, sessionStorage, innerHTML | c7d5e1ecbed37d7b |
wire/wire.css | Styles for the wire pages | this site | 279 | — | f134589e1aac457e |
wire/subscribe.js | Subscribe to one wire alone: the newsletter's envelope and lane (assets/subscribe.js, unedited), with X-SGit-List naming the wire | this site | 103 | 2 fetch, WebCrypto | e08913d389ede55f |
admin/build/wire-reach.json | The organisation routes this site found for each wire's reach page, under the published contact rules: page, date, hash, role addresses | this site | 109 | — | 380f4d81d3f129e2 |
admin/build/wire-vault.json | The Industry Wire's vault: endpoint, vault id, the public read key (the only kind of key on this site) | this site | 14 | — | c8c84bea5a65df09 |
admin/build/wire-vault.owasp.json | The OWASP Wire's vault (wire/owasp/): the same contract, its own public read key | this site | 17 | — | d584c029352338f2 |
admin/build/wire-vault.aws.json | The AWS Wire's vault (wire/aws/): the same contract, its own public read key | this site | 17 | — | 3c0448d6e39bfeea |
admin/build/wire-vault.portugal.json | The Portugal Wire's vault (wire/portugal/): the same contract, its own public read key; the bundle is bilingual | this site | 17 | — | 752b9fbb38c9015d |
wire/snapshot.json | The Industry Wire as it was in the vault at the last release: headlines, primary links, corrections, the latest release note; the fallback and the agents' index | this site, generated | 1,337 | — | 62085ccd612b1abf |
wire/owasp/snapshot.json | The OWASP Wire at the last release, the same shape | this site, generated | 292 | — | 42aa828998de833a |
wire/aws/snapshot.json | The AWS Wire at the last release, the same shape, with the stack's deadlines | this site, generated | 944 | — | 073f0270783a41d2 |
wire/portugal/snapshot.json | The Portugal Wire at the last release, the same shape, with each headline in Portuguese too | this site, generated | 515 | — | e188f02148e47a55 |
assets/vault-ui-embed.js | The study page: embeds the vault browser from dev.vault.sgraph.ai and hands it a read key | sgit.ai, verbatim | 126 | hosts: dev.vault.sgraph.ai, innerHTML | 308af99563423f5e |
assets/shots.js | Figures: sets each image's address at runtime | sgit.ai, verbatim | 278 | 1 fetch | 6c03d07971ec6808 |
assets/site.js | Page behaviour: nav, copy buttons, reveal-on-scroll | sgit.ai, verbatim | 81 | — | 0069c69190c8afc1 |
assets/nav.js | Nav behaviour on the pages this site writes | this site | 42 | — | bf18958cd99e10b5 |
.well-known/sgit-subscribe.json | The lane and the public key the share and the subscription are encrypted to and written into | sgit.ai, verbatim | 25 | hosts: dev.send.sgraph.ai | 1414b8bb22c50b86 |
articles/ids.json | A number for every article: the contract reading lists are built on | this site, generated | 2,114 | — | b6ec65cb73926839 |
persona/links.json | The persona links, for whoever writes to someone | this site, generated | 268 | — | 1db0c1f2e342a8c1 |
articles/graphs.json | The feed the picks and the graph read: every article with topics, tags and citations | sgit.ai, imported | 35,933 | — | 3a8b7ff07506f886 |
assets/newsroom-vault.js | The newsroom's vault module: create, open, read, write and publish through the vendored library; the door, master and reader vaults; unlock; add a door | this site | 258 | localStorage, WebCrypto | aaa49a06cb76f82c |
assets/door.js | From a passkey's PRF bytes (or a recovery code) to a door vault's key: the article's derivation, shared by the lab and the pane | this site | 139 | WebCrypto | 740779876d19aceb |
assets/vault-pane/vault-pane.js | The vault pane on every page with the meter, in four tabs: this page (the three steps, what the browser knows about the page, the notes, write to the newsroom, send to the newsroom, the lane's read key), reading (every page read here, with its decision), the vault (enable with the passkey, create or join, update the vault, the table across devices, bring their activity here), the keys (every vault of the account); above the tabs, what is only in this browser | this site | 904 | hosts: dev.send.sgraph.ai, dev.vault.sgraph.ai, localStorage, sessionStorage, innerHTML | 40f1981a99cdcc18 |
assets/vault-pane/notes.js | The reader's notes as records: one tap at a piece (done, read later, follow up, not for me, more like this, liked, wrong, fix this, idea) with words and the selected phrase, or a message alone, kept in localStorage sgit.notes.v1; keep, add words, remove, mark sent; the decision at a page | this site | 139 | localStorage | 283e816e1fe72456 |
assets/search/search.js | Search in the browser: the index from search/docs.json and search/text.json, BM25 over fields and paragraphs, phrases, numbers, prefixes, snippets; the search page | this site | 318 | 2 fetch | a1602529e616f0be |
assets/search/search.css | Styles for the search page | this site | 25 | — | 1fcdffcfa53fc8d3 |
assets/search/ask.js | Ask: the top passages, numbered, given to Chrome's built-in model or to openrouter.ai with the reader's own key, answered with citations; the key in the tab unless kept | this site; openrouter.ai, only with the reader's key | 184 | hosts: openrouter.ai, 1 fetch, localStorage, sessionStorage | ec50bb11017fe7fb |
assets/search/ask.css | Styles for Ask on the search page | this site | 23 | — | 9f8cd3cb95d659e8 |
assets/vault-pane/inbox.js | The inbox (049): the reader's RSA-OAEP key pair, the link (sgi1.<vault>.<token>.<key>), sgit's hybrid envelope, the append routes (configure, write, list, fetch, mark-processed), the drain, the QR code | dev.send.sgraph.ai /api/vault/append/* | 227 | hosts: dev.send.sgraph.ai, 1 fetch, WebCrypto | 0d31b92a8827d26a |
assets/vault-pane/send.js | The sending side of the inbox, for a browser with the link and no passkey: its own records as one device file, sealed and appended | dev.send.sgraph.ai /api/vault/append/write | 104 | localStorage, WebCrypto | 06b1b151b35f927b |
assets/vendor/qrcode-generator/2.0.4/qrcode.mjs | QR code generator (Kazuhiko Arase, MIT), vendored unchanged, for the inbox link | this site | 2,237 | hosts: www.d-project.com, www.denso-wave.com, www.opensource.org | ea91d7118a539528 |
assets/search/search-nav.css | The Search link in the nav, on every page | this site | 5 | — | c750cab906e8d159 |
assets/vault-pane/wire-state.js | What this browser knows about the wire: stories seen and when, the visit, the lens chosen; and which of the vault's releases to show | this site | 78 | localStorage, sessionStorage | 36e1d5bbbd300c62 |
assets/vault-pane/pending.js | What this browser holds that the reader vault does not yet: reads, top-ups, notes and stories seen since the last update | this site | 47 | localStorage | 4d4c30ec10e0ebe1 |
assets/vault-pane/reading.js | What this browser knows about what it has read, from the meter's records: one page summed up (times, when, how far, cost, rating) and the reading history | this site | 41 | localStorage | e8f2b778f2b2eec0 |
assets/vault-pane/sync.js | The activity vault's logic as pure functions: a device's file (reads, top-ups, personas, notes), the consolidated view, totals recomputed, merging into local state | this site | 237 | — | f00763d6b4f17156 |
assets/vault-pane/vault-pane.css | Styles for the pane, its tabs, the chips and the notes, and the page shift | this site | 119 | — | 8a6aa362c7ee9b86 |
assets/vendor/sg-vault/local/sg-vault--create-with-id.js | SGVault.createWithId: a vault at a derived id, a local patch pending upstream | this site, pending upstream | 99 | — | b668c4ab0062a3b3 |
assets/vendor/sg-vault/v0.2.3/sg-send/sg-send-crypto.js | AES-256-GCM and PBKDF2 over Web Crypto | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 151 | WebCrypto | 2c4af16bbaf4f43e |
assets/vendor/sg-vault/v0.2.3/sg-send/sg-send.js | The HTTP client: read, write, batch, presigned; x-sgraph-access-token | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 275 | 4 fetch | 9bc98e580f5fc1ad |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault-crypto.js | Key derivation: read key, write key, ref and index ids; key prefixes | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 302 | WebCrypto | f8d31359204a9e33 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault-object-store.js | Content-addressed objects, the write batch, the block caches | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 290 | WebCrypto | a45d7ad0f9dbd916 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault-ref-manager.js | Refs and the branch index; write-if-match | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 158 | — | 5b8ea87ace83d59e |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault-commit.js | Commits and trees, every field encrypted | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 175 | WebCrypto | e686de3756eaeed1 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault.js | SGVault: create, open, openReadOnly, the tree, the commit | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 566 | WebCrypto | 0108884f9b8d539e |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault--file-ops.js | addFile, updateFile, getFile, removeFile, renameFile, moveFile | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 157 | — | f114db89754638b5 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault--folder-ops.js | Folders, lazy sub-trees | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 125 | — | 10fea1377422c536 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault--sync.js | push, pushIfMatch, pull, merge, ahead and behind | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 456 | — | b9f521e7b70ca66f |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault--history.js | History: commits, trees and files at a commit | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 89 | — | 265b215e27216ad2 |
assets/vendor/sg-vault/v0.2.3/sg-vault/sg-vault--branches.js | Branches from the index | SGraph-AI__App__Send v0.2.3, vendored and unedited (VENDOR.md) | 57 | — | bc1eec8bbc2326a7 |
The page loader: an inline script on every imported page (17 lines, SHA-256 f114004ba2928d82) that loads the stylesheet and assets/site.js, by the vault bridge when the page is inside a vault and otherwise by fetching the text and evaluating it. 506 pages carry a script that evaluates fetched text (R10). The 20 files of earlier meter versions (1.0.0 to 1.3.1, 5,697 lines) are published artefacts on immutable paths; they move frozen, and their only test is that they are still served byte for byte.
Labs, beside the reader code and not part of it
Code that runs in a browser on this site, is not on a reader’s path, and will move with the rest: today, the passkey lab. It makes no change to the reading account and is counted apart.
| File | What it is | Lines | SHA-256 |
|---|---|---|---|
passkey/lab.js | The passkey lab: WebAuthn with PRF, the door derivation, sgit's key derivation, and real vaults through assets/newsroom-vault.js | 345 | 08c47eae0b95943e |
passkey/lab.css | its styles | 29 | ca352ad9cdc8631d |
passkey/vectors.json | its test vectors, from sgit's Python | 19 | d50a3642c131bbaa |
passkey/index.html | the page | 328 | 6620cffd5731fd4b |
The pages
| Page | What | Lines | SHA-256, chrome and stamps normalised |
|---|---|---|---|
account/index.html | the reading account | 262 | bc2f591e3a452542 |
account/newsroom.html | the reader's newsroom | 257 | d51094542674dd01 |
account/personas.html | the personas | 257 | 21ad4f65ea6c5ad0 |
account/share.html | send us your reading | 259 | a21883ac53716f44 |
account/top-up.html | the top-up | 257 | 6a94fbab4eace27c |
account/topped-up.html | the page a payment returns to | 256 | 74dc5138c9559741 |
subscribe/index.html | subscribe | 277 | 1251580b865830dd |
persona/index.html | the persona picker | 240 | 7c0c30a9ae0de576 |
persona/founder/index.html | a persona link | 247 | 043526965d23edb0 |
persona/journalist/index.html | a persona link | 247 | 8c9acb523b68c36f |
persona/security/index.html | a persona link | 247 | 2db575acd574852c |
persona/builder/index.html | a persona link | 247 | fce8ebd416a924a8 |
persona/board/index.html | a persona link | 247 | 384885a41bf6abad |
for/index.html | a reading list | 254 | cbd0376dd53283fe |
for/make.html | make a reading list | 244 | 2e61fd52d2b8fc98 |
wire/index.html | the Industry Wire's edition | 264 | a89dfc55f0e31f7e |
wire/sources.html | the wire's sources | 245 | ff37914b86bdcd7c |
wire/how.html | how the wire is read, and its documents | 250 | 74e7248838ce7d1b |
wire/owasp/index.html | the OWASP Wire's edition, with the projects graph | 265 | fc2c31f75ffeb12e |
wire/aws/index.html | the AWS Wire's edition, with the stack and its deadlines | 265 | 3ea762f3c45529c1 |
wire/portugal/index.html | the Portugal Wire's edition, in English and Portuguese, with the ecosystem map | 265 | eea9703a0319827a |
wire/days.html | every wire day by day | 246 | 21de5ee688ca6010 |
wire/costs.html | what the wires' pictures cost: every image, edition, wire and month, and the key's budget; wire/costs.json is the data | 254 | bc2f78a98c4fdb78 |
wire/charter.html | the charter of the wires | 258 | 1f4cc9dc555555d8 |
wire/desk-brief.html | the brief for the desks | 264 | 9ab290dea086eb67 |
wire/reach.html | who should know, by organisation route | 245 | 5d4214dad6ff3f65 |
vault/index.html | your vault: the reading account carried between devices, with the pane open | 269 | 7db79ab551958dfa |
meter/index.html | SG Meter, documented | 398 | 55656dcab6bf2887 |
meter/security.html | the meter's security model | 283 | 9fc8faaf1fc72627 |
demos/vaults/newsroom-synthetic-users/index.html | the synthetic-readers study, with the embedded vault | 344 | e8d83c803a3e0e72 |
Which pages carry which view: account on 1, landing on 6, newsroom on 1, page on 691, personas on 1, share on 1, topped-up on 1, topup on 1. The balance chip is in the nav of every page; every page is a charged or free page.
Capabilities and web controls
Everything a reader can click, type or pay, by view, with the call it makes. Where a control changes money or a persona, the call is named so a test can target it.
balance · every page (the nav chip)
| Control | Label | What it does |
|---|---|---|
| link | the balance | opens the account page |
page · every charged page, at the foot
| Control | Label | What it does |
|---|---|---|
| link | How paying for reading works here | opens links.how |
| link | Balance | opens the account page |
| button | + Add to your reading list / ✓ In your reading list | meter.curate(slug, 'on' | '') |
| 5 buttons × 3 | How useful was this? · More like this? · Level of detail | meter.rate(field, 1–5); usefulness re-prices the page |
| link | Your newsroom | opens links2.newsroom |
| button | Something wrong with this page? Don’t charge me | shows the four reasons |
| 4 buttons | the reasons | meter.decline(reason): refunds the page |
account · account/index.html
| Control | Label | What it does |
|---|---|---|
| link | Top up £5.00 | navigates to the Stripe payment link (topup.link) |
| button | Export as JSON | downloads reading-account.json (the whole state) |
| links | Your newsroom · Your personas · Send us your reading | own pages |
| links | one per history row | the page read, from the log's own path |
| file input | Restore from an export… | confirm(), then meter.restore(text) |
topup · account/top-up.html
| Control | Label | What it does |
|---|---|---|
| link | Pay £5.00 | navigates to the Stripe payment link; with no link, the simulated cart |
topped-up · account/topped-up.html
| Control | Label | What it does |
|---|---|---|
| on load | ?session_id=… | meter.credit(amount, 'link', id), once per id, unverified |
| link | Your account |
picks · the front page
| Control | Label | What it does |
|---|---|---|
| links | one per pick | opens the article |
newsroom · account/newsroom.html, and under a persona banner
| Control | Label | What it does |
|---|---|---|
| buttons | the persona chips | meter.setActive(id) |
| link | + Add or manage personas | the personas page |
| link | A newsroom designed for you | the share page (not when compact) |
| 2 buttons per pick | Add to reading list · Not for this persona | meter.curate(slug, 'on' | 'off', active) |
| button per kept / put-out article | remove · bring back | meter.curate(slug, '') |
| buttons | Add this persona (per preset) · Add a blank persona | meter.addPersona(preset | '') |
personas · account/personas.html
| Control | Label | What it does |
|---|---|---|
| input + button per persona | name · Rename | meter.renamePersona(id, name) |
| button per persona | Make active | meter.setActive(id) |
| link per persona | Open its newsroom | setActive, then the newsroom page |
| button per persona | Remove | confirm(), then meter.removePersona(id) |
| buttons | the preset cards | meter.addPersona |
graph · account and newsroom pages
| Control | Label | What it does |
|---|---|---|
| links | one per article dot | opens the article |
link · pages that carry it
| Control | Label | What it does |
|---|---|---|
| link | Your newsroom |
landing · persona/index.html and persona/<id>/
| Control | Label | What it does |
|---|---|---|
| on load | the persona named by the attribute or the #fragment | meter.visit(id): added as a visitor, made active, nothing charged |
| buttons | Keep this persona · Remove it | meter.keepPersona(id) · meter.removePersona(id) |
| button | Read as <name> again | meter.visit(id) after a removal |
| links | Your personas · Other personas | own pages |
| per preset (the picker) | Read as this persona · Copy link | opens persona/<id>/ · clipboard |
share · account/share.html
| Control | Label | What it does |
|---|---|---|
| button | Copy to clipboard · Copy it instead | clipboard; meter.noteShared('copied') |
| inputs | name · email (required) · note · consent · newsletter · a hidden honeypot | the form; nothing is sent without consent |
| submit | Send it, encrypted | fetch the contact file, verify the key's fingerprint, encrypt an .eml, POST to the lane |
reading list (for/) · for/index.html
| Control | Label | What it does |
|---|---|---|
| on load | the fields after the # | parse(); visitList(): a visitor persona named for the two people, its articles as the reading list |
| link | Start reading | the first article |
| link | Reply to <sender> | mailto:, only when the link carries e= |
| buttons | Keep this list as a persona · Remove it · Add it again | meter.keepPersona · meter.removePersona · visitList |
| links | every article, every persona or collection to follow | own pages |
make a reading list · for/make.html
| Control | Label | What it does |
|---|---|---|
| inputs | From · To · a note · your email | validated as the recipient's page validates them |
| search and two selects | title, topic or number · topic · persona | filters the article list |
| 2 buttons per article | Read · Look | puts the article in a group |
| per chosen article | ↑ · ↓ · To look / To read · Remove, and drag | orders the list |
| checkboxes | personas and collections to follow | |
| button | Copy link | clipboard |
| link | Open as the recipient | for/#… in a new tab |
| input + button | Edit an existing link · Load | parse() into the form |
| button | Clear the list |
subscribe form · subscribe/index.html
| Control | Label | What it does |
|---|---|---|
| inputs | email · name · consent · a hidden honeypot | |
| submit | Subscribe | fetch the contact file, verify the fingerprint, encrypt an .eml, POST to the lane; on failure, a mailto: link with the same text |
the study page · demos/vaults/newsroom-synthetic-users/
| Control | Label | What it does |
|---|---|---|
| on load | two iframes from dev.vault.sgraph.ai | the published read key is handed over postMessage; the vault is decrypted in the frame |
article foot · every article
| Control | Label | What it does |
|---|---|---|
| link | start a reading list with it | for/make.html#r=<number> |
Inputs
| Where data comes in | What | Who controls it, and how it is checked | In the code |
|---|---|---|---|
| Element attributes | view · kind · date · topics · title · quiet · count · persona · compact | the page's own markup (trusted: it is this site's build) | sg-meter.js |
| The page's config | <script type="application/json" id="sg-meter-config"> | this site's build, written once per page; every key has a default | sg-meter-core.js _config() |
| The address: query | ?session_id= on account/topped-up.html | whoever made the link; any value is credited once (accepted, documented) | _toppedUp() |
| The address: fragment | #<persona id> on persona/; #from,to,r,s,f,n,e on for/ and for/make.html | whoever made the link; validated field by field, the rest dropped and listed | _named(), reading-list.js parse() |
| The address: path | location.pathname | the charge is keyed on it; the slug is taken from it; the share records it | open(), _page(), _send() |
| Local storage | sgit.meter.v1 (the state), sgit.meter.v1.seen (session: the charge per path) | this browser, written by the meter; also by the reader, who may edit it (accepted) | _read(), _seen() |
| A file | Restore from an export… | whoever made the file; checked for balance:number and log:array only | restore() |
| Forms | the share form, the subscribe form, the make page | the reader; email checked by a loose pattern, names by a strict one | _send(), subscribe.js, make.js |
| The wires' vaults | data/bundle.json (with wire, map or stack when the vault has them), data/deliveries.json, data/releases.json, docs/*.md, decrypted in the browser; one vault per wire | whoever holds the vault's write key (the wire's agents); drawn as text, links only from http(s) values, markdown rendered by an escaping renderer; the vault's own HTML is not used | wire/wire.js |
| Own-origin data | articles/graphs.json · articles/ids.json · .well-known/sgit-subscribe.json · sg-meter.tpl · sg-meter.css | this site's build; the contact file's key is checked against its fingerprint | feed(), openList(), _send() |
| postMessage | replies from the dev.vault.sgraph.ai frames | origin-checked; drives a status line only | vault-ui-embed.js |
Where the reader’s data is kept
One key in this origin’s local storage, sgit.meter.v1, holds all of it; a session key holds the charge per path so a reload does not charge twice. Keys for the share and the subscription exist only in memory while the page encrypts. There is no cookie and no server-side store.
| Field in sgit.meter.v1 | Holds |
|---|---|
v | 3 |
created | ISO time |
balance · spent · declined | pence, to 0.1p |
reads | pages opened |
paused | always false since v1.4.0 |
log[] | ≤ 500 entries: id, at, path, title, kind, topics, price, depth, cost, persona, autoKept?, rating{useful,more,detail,at}?, declined{reason,at,refunded}? |
topups[] | ref (≤ 40 chars), at, credit, source: link | simulated |
sessions[] | every payment reference credited, unbounded |
cart[] | the simulated cart (unused with a live link) |
active | the active persona's id |
personas[] | id, preset, name, created, on[], off[], visitor?, list? (a reading list's key), theme? |
shares[] | ≤ 20: at, how, pages |
What leaves the browser, and external calls
No page loads a script from another origin. These are the ways anything leaves, each tied to something the reader does, except the first.
| What leaves the browser | Carrying | When | Who sees it |
|---|---|---|---|
| GET, own origin | every page, script, style, image and JSON | whenever a page opens | GitHub Pages, which sees the request as any host does |
| POST https://dev.send.sgraph.ai/api/vault/append/write/y9j3nc60 | {append_token, payload}: an .eml encrypted in the browser to the lane's public key | when the reader presses Send on the share page or Subscribe | the vault host; it sees ciphertext, a size and a time |
| Navigation to https://buy.stripe.com/… | the reader leaves for Stripe's page and returns to /account/topped-up.html?session_id=… | when the reader presses Top up / Pay | Stripe (card, email, name, postcode) |
| GET https://dev.send.sgraph.ai/api/vault/read/u9i9jp0l/… | the ciphertext of the wire's vault: its head pointer, commit, tree and the files the page needs, decrypted in the browser with the published read key | when a wire page opens, and when the reader asks for a new commit; the pointer at most every two minutes | the vault server; it sees the request and nothing of the reader |
| iframe https://dev.vault.sgraph.ai/?embed=1 | two frames; the published read key is posted to them | on the study page only | the vault UI host |
| mailto: | Reply to <sender> on a reading list; the subscribe fallback | when pressed; the page sends nothing | the reader's mail client |
| A download | reading-account.json: the whole state, payment references included | Export as JSON | the reader's disk |
| The clipboard | a link, or the share text | Copy | the reader's clipboard |
| postMessage to the parent window | {type:'sg-app-ready'} with targetOrigin * | when a page is framed | whoever framed it |
The contracts
| Contract | Shape | Owner |
|---|---|---|
| The meter config | storageKey, start, newDays, symbol, prices{article_new,article,issue,note,collection,page,free}, depth, minDepth, topup{amount,link}, packs, links{account,topup,how}, rating{price[5],more[5]}, autoKeep, picks{feed,base}, links2{newsroom,personas,share}, share{contact,form,site,max}, personas{presets[],names{}}, root | sg-meter-core.js DEFAULTS; written into every page by sgit.ai's build and re-pointed by the import |
| A charged page | <sg-meter view="page" kind="article|issue|note|collection|page|free" date="…" topics="a b" title="…" [quiet]>: the price class comes from the page | sgit.ai's build for imported pages; page.py (kind=free, quiet) for this site's |
| A persona link | /persona/<id>/ and /persona/#<id>, id ∈ {founder, journalist, security, builder, board} | personas.py, persona/links.json |
| A reading list link | /for/#from=&to=&r=&s=&f=&n=&e=: names ≤ 40 chars of letters, spaces, hyphens, apostrophes; r,s article numbers, 1–50 in all; f persona ids or c:<collection>, ≤ 10; n ≤ 240 chars; e an address | for/reading-list.js LIMITS, parse(), build() |
| Article numbers | articles/ids.json: n and slug are the contract, assigned once in publication order, never changed or reused; every other field is display text | admin/build/ids.py; validate.js check 12 |
| The return page | ?session_id=<ref>: credited once per distinct value, never verified | _toppedUp(), credit() |
| The export | the state as JSON; restore accepts any file with balance:number and log:array | restore() |
| The share | a text summary then the same data as JSON {v:1, site, at, balance, spent, declined, reads, topups, active, personas, topics, cols, log}, as an .eml with X-SGit-Form, X-SGit-Reply-To, X-SGit-Name, X-SGit-Subscribe, X-SGit-Page | shareData(), _send() |
| The envelope | sgit hybrid envelope v2: {v:2, w, i, c} (RSA-OAEP-SHA256 wrapped AES-256-GCM key, iv, ciphertext), base64, then base64 again as the lane payload | envelope(), subscribe.js encrypt() |
| The contact file | sgit-subscribe/v1: recipient{address, fingerprint, encrypt}, inbox{vault, endpoint, encrypt_to, status, lane{name, append_token}}; the fingerprint is recomputed from the PEM before use | .well-known/sgit-subscribe.json |
| The wires' vaults | u9i9jp0l (the Industry Wire), eitf274v (OWASP), v202bla5 (AWS), p6twygul (Portugal) on dev.send.sgraph.ai, read keys published; data/bundle.json {beats, stories, sources, personas, brief; wire, map, stack when present}, data/deliveries.json, data/releases.json (wire-releases/v1, one entry per publish), docs/*.md; story fields, changes and status shown as written; everything in a vault is public, for ever | admin/build/wire-vault*.json; wire/how.html; each wire's agents own its content |
| Events | sg:meter.changed · charged · rated · declined · toppedup · reset · restored · persona · shared; sg-meter:error | sg-meter-core.js _emit(), sg-component.js failed() |
| A component | static jsUrl, get resourceName(), onReady(); a .tpl and a .css beside the .js; published at an immutable versioned path | sg-component.js |
| The import's rules | the meter path rewrite (v1.3.1 → v1.4.1), the top-up link, ten text rules, the article number line, the moved banner cut, the foot of every issue; each stops the import when its anchor moves | sync_newsroom.py items 9–15 |
The build, the gate and the tests
| Build and gate | What it does | Lines |
|---|---|---|
admin/build/ids.py | assigns article numbers, writes articles/ids.json | 156 |
admin/build/lists.py | writes the two reading-list pages | 103 |
admin/build/personas.py | writes the persona pages and persona/links.json | 160 |
admin/build/page.py | the page template, with the meter block every page this site writes carries | 117 |
admin/build/sync_newsroom.py | the import: re-points the meter to v1.4.1, applies the text rules, prints the article number | 709 |
admin/build/newsroom-meter.json | the top-up link, applied on import | 5 |
admin/build/newsroom-text.json | the ten text rules, applied on import | 167 |
admin/build/wire.py | writes the three pages of every wire (wire/, wire/owasp/, wire/aws/) and, from a clone, each wire's snapshot.json | 380 |
admin/build/vault_page.py | writes the vault page | 113 |
admin/build/lane.py | the newsroom's end of the feedback loop: clones or pulls a reader's lane with its read key (from the environment, never a file) and prints the notes by page | 147 |
admin/build/search_index.py | writes search/docs.json, search/text.json and the search page from the published pages, the article graphs and versions, the wires' snapshots and the notes | 356 |
admin/build/engineering.py | renders /engineering/ from admin/engineering/: the board, one page per issue card, one per release, issues.json | 203 |
admin/build/md.py | the small markdown renderer the engineering pages use; escapes everything first | 144 |
admin/build/chrome.py | the nav and footer on every page, with the meter's balance and the Vault button and pane on pages that carry the meter | 361 |
admin/build/validate.js | the gate: checks 2d (live link), 5 (key tripwire), 11 (imports unedited), 12 (numbers hold) | 493 |
| Test file | What it drives | Check calls | Lines | In CI |
|---|---|---|---|---|
admin/build/test_meter.mjs | the meter in Chromium | 40 | 222 | yes |
admin/build/test_lists.mjs | the parser in Node and the list pages in Chromium | 58 | 214 | yes |
admin/build/test_review.mjs | the review's findings, pinned as the behaviour is today | 14 | 145 | yes |
admin/build/test_passkey.mjs | the passkey lab in Chromium, with a virtual authenticator that has PRF, against the mock of the vault API | 33 | 159 | yes |
admin/build/test_wire.mjs | every wire's pages in Chromium, each reading its real vault | 65 | 236 | yes |
admin/build/test_vault.mjs | real vaults in Node: the vendored library against the mock of the vault API, and the sgit CLI round trip | 28 | 180 | yes |
admin/build/test_sync.mjs | the activity vault's logic in Node, with two devices' states | 48 | 127 | yes |
admin/build/test_pane.mjs | the vault pane in Chromium: the reading account carried between two devices through the mock vault, and a third opened with the recovery code | 31 | 164 | yes |
admin/build/test_search.mjs | search: the index and the ranking in Node, the page in Chromium | 37 | 148 | yes |
admin/build/test_ask.mjs | ask: the passages and the messages in Node; no model, the reader's key (openrouter.ai answered by a route) and the built-in model (faked) in Chromium | 32 | 175 | yes |
admin/build/test_inbox.mjs | the inbox: the link, the envelope, the refusals in Node; a browser with a passkey and one without, the QR code decoded, the drain and a new link, in Chromium against the mock with the append routes | 48 | 247 | yes |
admin/build/test_notes.mjs | the feedback loop in Chromium: notes on an article and at a wire story, carried by the vault, sent to the lane, read by the sgit CLI and lane.py with the read key alone, brought into a second device | 77 | 329 | yes |
admin/build/vault-mock.mjs | the mock of the vault API the two vault tests run against | 0 | 207 | no |
The review
Read line by line on 11 October 2026, as villager code is read: the meter element and core, the component base, the subscribe script, the reading-list code, the loader, the build scripts and the gate. Each finding has its evidence and, where it is a bug, a test in admin/build/test_review.mjs that passes while the behaviour stays as it is, so that the fix is a visible change to the test. Severity is for a reader’s money or data first, the move second. Nothing here was changed in the code, by the brief’s rule: no behaviour changes until phase five. The one exception is R11, which is the pipeline and not the product.
| # | Severity | Area | Finding | Evidence | Pinned by | Proposed change |
|---|---|---|---|---|---|---|
| R1 | medium | the meter's logic | Declining a page as “not relevant” leaves it in the persona's reading list. open() auto-keeps an article on first open; decline() refunds the charge but does not undo the auto-keep, so the article stays under “Its reading list” and profile() adds +5 for it while the decline subtracts 2: a page the reader rejected pulls its topics up. | sg-meter-core.js open() [autoKeep], decline(); seen in a browser on 11 October | test_review.mjs R1 (passes while the article stays in the list) | decline() removes an autoKept entry from the active persona's on[]; a reader who added it by hand keeps it |
| R2 | low | restore from a file | restore() checks that the file has a numeric balance and a log array and nothing else. A persona without on[] and off[] makes the personas and newsroom views throw and show nothing; a log entry's path is rendered as the history link's href as it is; a persona's theme is written into a style attribute as it is. The file is the reader's own, so the exposure is a file someone else sent them to restore. | sg-meter-core.js restore(), _read(); sg-meter.js _account() history rows, _chip() style | test_review.mjs R2 (the blank personas page); the href and theme cases are described, not pinned | normalise on read: personas get arrays, paths must be same-origin paths, themes must be a hex colour; unknown fields dropped |
| R3 | low | the return page | A malformed percent sequence in ?session_id= (for example %E0%A4%A) makes decodeURIComponent throw inside onReady, so the element fails with “did not load: URI malformed” instead of saying the reference is missing. | sg-meter.js _toppedUp() | test_review.mjs R3 | try/catch around the decode; treat an undecodable id as no id |
| R4 | medium | data correctness | A reading share or a subscription sent from this site is labelled sgit.ai: the imported config has share.site = "sgit.ai" (so the text begins “My reading on sgit.ai”), subscribe.js writes From: site@sgit.ai, and the contact file says site: sgit.ai. The agent that drains the lane can tell the two sites apart only by the Sent from line. | index.html sg-meter-config share.site; assets/subscribe.js eml(); .well-known/sgit-subscribe.json | test_review.mjs R4 | a recorded meter rule for share.site (admin/build/newsroom-meter.json); subscribe.js and the contact file are verbatim imports and need this site's own copies, or a parameter, after the move |
| R5 | note | operations | On the live site the lane for shares and subscriptions is on dev.send.sgraph.ai and the study page's vault frames come from dev.vault.sgraph.ai. Both hosts are named “dev”. Production reader data goes to them. | .well-known/sgit-subscribe.json inbox.endpoint; assets/vault-ui-embed.js ORIGIN | test_review.mjs R5 (records the hosts) | a decision, not a code change: either these are the production hosts and say so, or the files point at production ones |
| R6 | low | display | Money is kept to a tenth of a penny and shown to a penny. Balance and spent are each formatted on their own, so a half-penny state shows, from £5.00, a balance of £4.95 and £0.06 spent, which do not add up; the history shows 5.5p. A reader who checks the arithmetic finds a penny missing. | sg-meter-core.js money(), r1(); seen with balance 494.5 | test_review.mjs R6 | one rounding rule for the pair (format spent as start − balance, or keep both to 0.1p on the account page) |
| R7 | question | picks | picks() excludes every page in the log, whichever persona read it, while profile() is per persona. An article read as Morgan is never picked for Rowan. | sg-meter-core.js picks() | test_review.mjs R7 (records the behaviour) | decide: per-persona exclusion, or keep and say so on the newsroom page |
| R8 | low | robustness | feed() caches a failed fetch as null for the life of the page, so one transient failure leaves “The list of articles could not be loaded” on every view until a reload. | sg-meter-core.js feed() | test_review.mjs R8 | do not cache a failure; retry on the next call |
| R9 | medium | the number contract | If sgit.ai renames an article (a new slug), ids.py marks the old number withdrawn and gives the article a new number. A reading list that named the old number then says the article is no longer published, although it is. | admin/build/ids.py assign() | described; a rename has not happened yet | a renamed_to field on the old entry, followed by the list page; the gate requires it when a slug disappears and a new one appears in the same import |
| R10 | high for the move | Content-Security-Policy | Every imported page loads assets/site.js, subscribe.js and shots.js by fetching the text and running it with (0, eval)(text) (the loader's bridge path), and the loader and the meter config are inline. A script-src policy without 'unsafe-eval' and without hashes breaks every page. frame-ancestors cannot be set in a meta tag at all, and GitHub Pages sets no headers, so framing (the Keep, Remove and Top up buttons under another site) is not prevented today. | the loader IIFE on every imported page; subscribe/index.html | test_review.mjs R10 (counts the pages that eval) | load scripts with <script src> or import(); then a meta CSP for script-src and connect-src; frame-ancestors needs a host that sets headers |
| R11 | high per the brief | the pipeline | The one workflow ran validate.js only; the browser tests (46 + 65 checks) never ran in CI. | .github/workflows/deploy-pages.yml | fixed in this release: a reader-tests job runs all three test files before the tag | done; the move's pipeline adds WebKit and Firefox and a pre-production copy |
| R12 | note for the move | two upstreams | The account pages, subscribe, the contact file and the component base are imported from sgit.ai on every sync and cannot be changed here except by a recorded rule, and verbatim files (scripts, JSON) cannot be changed by rule at all. R4 is the first consequence. The newsroom's meter is v1.4.0 while sgit.ai's is v1.3.1. | sync_newsroom.py VERBATIM, MOVED_DIRS | the brief's phase 1 removes it | the move: both sites pin released files |
| R13 | note | what leaves | The export includes the payment references (sessions, topups[].ref) that the share deliberately leaves out. A reader who sends their export instead of their share sends them. | sg-meter.js _export(); shareData() | described | say so beside the button, or export without sessions |
| R14 | low | bounds | sessions[] and topups[] grow without bound, and a payment reference is not checked for shape before it is stored. | sg-meter-core.js credit() | described | cap both; keep references that look like cs_… only |
| R15 | low | personas | persona(id) falls back to personas[0], which is “me” only when “me” is first; after a restore that puts another persona first, an unknown id resolves to that persona. | sg-meter-core.js persona(), _read() | described | fall back to the persona with id me |
| R16 | process | caching | Imported pages load the meter as sg-meter.js?v=<sgit.ai's release>, so the cache-buster never changes for a release of this site. That is fine while a published version is never edited in place, which is the rule; it is written here because v1.4.0 was edited in place while it was being built. | the import's own_meter() keeps sgit.ai's ?v= | described | a change is a new version path, always |
| R17 | note | reading lists | A list's persona is keyed by a 32-bit hash of the names and numbers, so two different lists can share one persona with probability about one in four billion per pair. | for/reading-list.js listKey() | described | a longer hash, or the fragment itself as the key |
| R18 | note | listeners | The landing view adds a window hashchange listener per element and never removes it, and re-renders on every meter change (the picker's “Copied” label resets). | sg-meter.js _landing() | described | one listener, removed on disconnect |
Accepted, and said so
| Accepted gap | Why | Where it is said |
|---|---|---|
| The return page credits any session id | a static page cannot verify a payment; building the address by hand credits the reader's own screen | meter/security.html |
| The reader can edit their own balance | the state is in their storage; nothing is behind a wall | meter/security.html, No server by design |
| The names in a reading list are whatever the link says | there is no signature yet; a signed list is a later step on RFC 0001's keys | for/index.html |
| A page is charged by the deepest point reached, and the reader card is at the foot | reaching the card to rate a page is reading to the end | going-live-with-the-reading-meter.html |
What the move takes from here
- The before-hashes in the file and page tables, to be compared with the live site after the move with the same normalisation.
- The controls and inputs tables as the checklist for the browser tests in three engines, and for the adversarial exercise: change what a reader sees or pays without a test failing.
- The contracts table as the README of the new repository: these are the things that must not change in a pure refactoring.
- The findings, one issue each, labelled with the phase they belong to; R10 and R12 are the shape of the work, the rest are its first items.
For an agent
This page maps the client-side API of newsroom.sgit.ai at v0.12.72: every reader file with its hash, every view and control, every input, what leaves the browser, the contracts, and a review with 18 findings. The same data is at https://newsroom.sgit.ai/newsroom-api/map.json. It is regenerated by admin/build/api_map.py on each build; the findings are pinned by admin/build/test_review.mjs. The brief it answers is https://newsroom.sgit.ai/articles/explorer-to-villager-newsroom.html.