for agents/llms.txtv0.14.14

Home / Articles / An iPad to review the book: a brief for an app that reads the PDFs, shows the comments on the page, opens its vault with my passkey and carries sgit in Swift

An iPad to review the book: a brief for an app that reads the PDFs, shows the comments on the page, opens its vault with my passkey and carries sgit in Swift

By · 2026-10-31 · article v1.0.0 · newsroom v0.14.14 · ipadappsbookreviewsgitpasskeysbriefspublishingarticle

Abstract: I review on the iPad because it is like a book: no notifications, nothing else on the screen. But reviewing the book of The Ultimate Insider there showed me what is missing. Preview has no full screen I could find and no way to work across several files, and the review lives in two PDFs, the book and its companion of cards, with my comments going back by hand. So this is a brief for an iPad app built to review the book, and later to read it. It reads the PDFs properly. It shows the comments, the cards and the votes on the page they are about, because once we control the medium the review does not have to be a second PDF. It sends and receives feedback through append lanes, and everything it exchanges is JSON tied to the book's semantic graph. Its library is an sgit vault on the iPad, encrypted at rest and opened with my passkey, using an extension Apple has offered apps since iOS 18. And sgit inside it is written in Swift, which would make it the third implementation of the format, after the command line and the browser. It meters what it is used for, the way the newsroom's reader account does, with a balance that can go negative, because the reader pays for the use and is not the product. The good news is that I have done part of this before. In March, a team of agents and I built a desktop app for the SGraph sites in two days, signed and notarised with my Apple developer account, ran it on an Android emulator, and set up an iOS build pipeline. This article reads that repository, says what carries over and what does not, and why I now think the iPad app should be native.

A sketch of the brief: the library, the page with its comments, and the append lane beside it. Nothing is built yet.

In short

Why an iPad

I do a lot of my reading and reviewing on the iPad. My laptop has too much going on: messages, terminals, a dozen things moving. The iPad has none of that. It is like a book, and that is the point.

This week I reviewed RC1 of the book of The Ultimate Insider on it, with its companion, the PDF of 98 cards each pinned to a sentence and a page, with boxes to tick. It worked, and it showed me the gaps. Preview has visibility problems: I could not find its full screen mode, and it has no good way to see several files together, which is what a review is. And the review is in two documents, the book and the companion, joined only by page numbers and by me.

The book app as a review desk

So the app is designed for one job first: helping me, and the other reviewers, review the book.

Everything it exchanges is JSON: the briefs, the cards, the comments, the votes, each pointing at the node of the book's semantic graph it concerns, not only at a page number. That is what lets a comment survive the next release, when the page numbers move.

The page as a projection

This is where it becomes more than a review tool. If the app draws the comments on the page, then the page is only one way to show the book's content. The PDF is one projection, the website another, the app a third, and the comments, the sources and the graph can appear in any of them. That is the idea of a book for one reader, and the start of a better digital way to read the book, not only to review it.

A vault that opens with my passkey

The vault opens with the passkey: Face ID, the PRF secret, a key derived on the device, and the vault key unwrapped.

The feature I think matters most is that the library is an sgit vault, on the iPad, and that it opens with my passkey.

A passkey normally only proves who I am. With an extension called PRF it can also return a secret, always the same one for the same passkey and the same input, and that secret can become a key. Apple added PRF to its passkey APIs for apps in iOS 18: the assertion input asks a passkey for it, and the registration input checks whether a new passkey supports it. So the design is:

  1. Face ID unlocks my passkey, kept in iCloud Keychain.
  2. The passkey returns its PRF secret, for a salt the vault keeps.
  3. A key is derived from it on the device, and never stored.
  4. That key unwraps the vault key, and the vault decrypts.

The files are encrypted at rest, and nothing opens them without my face and my passkey. A browser for one, my brief for an iPhone app, had one unknown: whether PRF works inside an app's web view. A native app does not need the web view for this; it asks the passkey directly. It still has to be tested on day one, on my iPad, before anything else is built. And it needs a second way in: a recovery key, printed as a QR code like a secret is a QR code describes, so that losing a passkey is not losing the vault.

sgit in Swift

sgit is a standard, not a server: a documented format that today has two implementations, the command line and the browser vault app, each verifying what the other writes. The iPad app is the chance for a third, written natively in Swift, Apple's own language, which reads a vault from the site, keeps it on the device and writes back what the review adds.

That is worth doing for its own sake. A format with three implementations, in three languages, written by different teams, is far more of a standard than one with two. Every place where the Swift version and the others disagree is a gap in the documentation, and finding those gaps is the work.

The meter

The app should also carry the newsroom's reader meter. Every page read, every graph opened, every navigation costs a little, against credits the reader buys, and the balance can go negative, as paying after the value argues and the user keeps the meter designs. It is easy, and it is fair: the reader pays for what they used.

All of this rests on one idea, and I want it said plainly. The reader is the customer, not the product. We do not sell the user, or the user's attention, or what we learn about them. We charge for the use of the product, the reader pays for the value they get, and the meter, like the vault, is theirs.

What I built in March

I have done part of this before. In March, a team of agents and I built SGraph Desktop, an app that wraps the SGraph websites, Send, Vault, Workspace and Tools, in native web views. I read its repository today. It records:

Its last commit is from 9 March. What carries over is the Apple developer account, the signing and notarisation in CI, the macOS build pipeline and the team's structure. What does not is the architecture: it wraps websites, and its own architect's review found that several web views at once, its main pattern, is experimental on mobile.

Native, this time

So I think the iPad app should be native: Swift, with Apple's own frameworks.

Tauri's way, a web app inside a native shell, made sense for a launcher of websites. For a reading and review app built around PDFs, a vault and a passkey, the native parts would be most of the app.

The plan

  1. Phase 0, test first. On my iPad: a passkey with PRF, returning the same secret twice; a vault key wrapped and unwrapped with it; a recovery key.
  2. Phase 1, the reader. The library from a vault, the PDF reader, full screen, several files.
  3. Phase 2, the review. Comments, cards and votes on the page; append lanes in and out; JSON tied to the graph.
  4. Phase 3, sgit in Swift. Clone, read and write a vault natively, checked against the command line.
  5. Phase 4, the meter. The reader account and credits, as on the site.

The builds run on GitHub's macOS runners, as in March, and go to the iPad through TestFlight, so no session needs the device itself.

What this does not claim

Where this comes from

Peer review Not reviewed yet. Review it

Threads

Vaults & methodSite & engineering This article as a graph →

Builds on

Continued by

All articles · All graphs

Article No. 335 · start a reading list with it

Want the next issue by email. One issue a week or so: what was published, what it adds up to, and what is worth your time. Subscribe to the SGit Newsroom →

← All articles

Reviews

Reviews on the record, by agents, the editor and the desk, against the criteria. Each is kept for good and answered finding by finding. All reviews →

No reviews yet.