Your Book Is a Folder You Can Open Without Us.

What’s in the Folder

The Harbour/
  Manuscript/
    01 Arrival/
      01 The Harbour.md
      02 Customs.md
  Notes/
  World/
    Characters/
      Hortense.md
  Templates/
  Inbox/
  .shiro/
  .trash/

Non-fiction and memoir have Research/ in place of World/. The numbers at the front of the names set the order, and anything they can’t express goes in .shiro/order.json. A scene looks like this:

---
id: 7f3a9c
synopsis: Hortense lands with the wrong papers.
status: First draft
---

The customs officer looked at the stamp for longer than a stamp deserves.

The words are all there, in files you can read. .shiro/ holds what surrounds them: project settings, snapshots, comments and the authorship record. .trash/ keeps what you delete, at its original path.

Plain doesn’t quite mean unmarked. Open a scene elsewhere and you may find [[Hortense]] links to the World, %%private notes%%, and suggestions in CriticMarkup. They’re ordinary characters, and easy to strip out if you ever have to. Should Shiro vanish tomorrow, you’d be left with a tidy folder and some odd punctuation. We would prefer you didn’t have to test this. The code that reads and writes the format is MIT-licensed, in case someone wants to.

Editing Outside Shiro

Open a scene in Obsidian, VS Code or whatever you keep on the old laptop, and save it. What happens next depends on what Shiro was doing.

• The scene was sitting idle. Shiro reloads it and tells you.
• Both sides changed. The changes merge three ways. Where the same words changed in both places, the ones in Shiro win and the other version becomes a snapshot.
• You were mid-sentence when the file changed. Saving pauses and Shiro asks which to keep. You can compare them, and the one you don’t keep goes to snapshots.

Either way, neither version is lost. Text changed outside Shiro counts as not recorded in the authorship record, since Shiro wasn’t there to see it.

Offline, With No Account

The desktop app runs on Mac, Windows and Linux without an account and calls no server until you sign in. We test that: a browser test fails if the client makes a request off your machine while you move around home, the lenses and settings. The app collects no usage data and sends no crash reports. A cabin with no signal is a supported configuration.

Automatic snapshots and zip backups land on your own disk, and you can add encrypted backups protected by a passphrase. If you want AI as well, it can run on your computer too.

Move to Cloud, and Back

Move to cloud uploads the project and opens the cloud copy from then on. The folder stays on your computer as a backup, but it’s no longer the book: there’s no two-way folder sync, and later edits to those files go nowhere.

A cloud project is a Yjs document, merged character by character with no conflict copies and cached on each device. You can open it in the web app and write with other people. History goes back 7 days on a free account and 90 on a paid plan.

Download as vault turns it back into a Markdown folder wherever you choose, then removes the cloud copy. The record of which person wrote what stays behind, because only cloud books have it.

Cloud projects aren’t encrypted end to end. The server reads them to provide history, webhooks and agents. If you’re writing the memoir your sister hasn’t seen, or anything else you wouldn’t leave on someone’s server, keep it local. A local project stays on your disk unless you choose otherwise.

The Questions People Ask

Do I have to write in Markdown?

No. You write in a normal editor with italics, footnotes and a slash menu, and Shiro stores the result as Markdown. You only meet the syntax if you open the file somewhere else.

Does Shiro work without an internet connection?

Yes. The desktop app on Mac, Windows and Linux needs neither a connection nor an account for local projects. It makes no call to a Shiro server until you sign in.

Can I keep my book in Git?

Yes. Scenes are text files, so the diffs are readable and you can see exactly what you did to the ending last March.

Are cloud projects encrypted?

Not end to end. They travel over encrypted connections, but Shiro’s server can read them, because it needs to for history, webhooks and agents. If that’s a problem for this book, keep the project local.