The aipub Format — Specification

Version: aipub/0.1 Status: Draft. Stable enough to build against; the version line moves before anything breaks. Date: 2026-08-01 Author: Jimmy Thornburg — The Fort That Holds LLC Canonical URL: https://research.thefortthatholds.com/research-archive/the-aipub-format-specification Reference implementation: build_aipub.py (The Writing Voices LLC) Reference publication: The Lucero String, aipub #1 — https://lucero.thewritingvoices.com Spec license: free to implement, by anyone, forever (see §13).

1. Abstract

An aipub is a book file for a world where both people and machines read.

It is a valid, DRM-free EPUB carrying three additional layers inside the same container: a self-contained human reader, a machine-readable manifest, and an agent layer that tells software what the file is and what it may do with it.

The base layer means an aipub is never a gamble: rename it .epub and any ordinary reading system opens it as a book. The added layers mean an aipub can be worked — played, mapped, queried, translated, re-voiced, re-rendered — by whatever software the reader happens to have, without asking the publisher for anything.

2. Why the format exists

Every book format before this one froze the experience at publish time: one layout, one voice, one shape, fixed forever. That assumption held while the reader was a person holding a screen.

It stops holding when the reader has an agent — and it breaks completely on surfaces with no page at all (glasses, in-ear, and whatever renders directly into experience next). On those surfaces a book cannot be a fixed artifact. It has to be a canonical source plus enough structure that any renderer can produce the right expression for the moment.

So the aipub’s governing rule is:

The text is the only sacred object. Every other expression — layout, voice, screen, episode — is a disposable render, and the file grants permission to make them.

An aipub is therefore explicitly not DRM-adjacent. A format whose whole purpose is to be re-expressed by the reader’s own tools cannot also be locked against them.

3. Conformance language

MUST / MUST NOT / SHOULD / MAY are used per RFC 2119. A file is a conforming aipub if it satisfies every MUST in §4–§9.

4. The container

An aipub MUST be a ZIP archive that is a valid EPUB (EPUB 3 or later), which means:

• mimetype MUST be the first entry, stored uncompressed, containing exactly application/epub+zip and nothing else. (The base layer’s validity depends on this; the aipub’s own media type is declared elsewhere — §10.)
• META-INF/container.xml MUST point at a package document (.opf).
• The publication MUST pass EPUBCheck with zero errors.
• The publication MUST NOT carry DRM, encryption, or obfuscation of any resource.

Everything an aipub adds rides in the same ZIP as ordinary resources.

5. The four layers

Media (audio, video, additional formats) MAY appear at any path the manifest declares — see §9 for how parallel renditions of the same work are mapped.

Every added resource SHOULD be declared in the EPUB package manifest, so the publication remains self-describing to ordinary EPUB tooling.

6. /aipub.json — the machine layer

A JSON object. It MUST carry:

It SHOULD carry, when the publication has them: blurb, genre, content_notes (array), words, and media maps. A media map SHOULD state which part of the text each media file covers — this span mapping is what lets a renderer hand off between modalities at the same point in the work:

"audiobook": {
  "full":  { "file": "/audio/BOOK.mp3", "duration": "1:28:47", "sha256_16": "…" },
  "parts": [ { "file": "/audio/part_01.mp3", "covers": "Opening · Ch 1" }, … ]
}

Paths MUST be resolvable: relative to the container root in a FULL edition, absolute URLs in a LIGHT edition (§8).

Every media entry MUST additionally carry an absolute, streamable url, in both editions. A FULL edition’s relative file serves offline use; the url serves the far more common case where the consuming agent cannot play media itself and must hand the reader something that plays. Without it the agent’s only remaining move is to return the extracted file — see §7. The url MUST support byte-range requests so a reader can seek and resume.

7. /AGENTS.md — the agent layer

Prose, addressed to software, in the second person. It MUST state:

1. What this file is, and where the canonical text and manifest are.
2. What an agent may do with it — at minimum whether it may answer from the text, play the media, and render fresh expressions.
3. What must survive every derived expression — byline, any required disclosure, content notes, and the no-DRM condition.

It SHOULD state what an agent should not do (e.g. answer from general knowledge instead of the text; present a derived expression as the canonical work).

Never hand the reader a file. AGENTS.md MUST state this, because it is the format’s most likely failure and it is invisible to every other check. A person hands an assistant an aipub precisely so they don’t have to open it; an assistant that unpacks the media and returns it as downloads has converted one file into fifteen chores and inverted the point of the format. The required behaviour:

• play the media if the surface can play media;
• otherwise hand over the entry’s url (§6) — one tappable link that streams and seeks;
• if it can do neither, say so plainly and offer the text.

Returning attachments, extracted media, an archive, or a list of things for the reader to fetch is non-conforming. So is requiring the reader to install, register for, or visit anything in order for the agent to do its job: everything needed was in the file it was handed.

This layer is a grant of permission, not a lock. An aipub that uses AGENTS.md to forbid all machine use is not a conforming aipub — it is an EPUB with a note in it.

The handoff line. A person handing an aipub to any assistant should not have to explain the format. The canonical instruction is one sentence, and every publication SHOULD print it where a human will find it (the root readme, the download page, the publisher’s site):

“Read AGENTS.md, then work this aipub.”

It is deliberately vendor-neutral and needs no product name: an assistant that can open a zip finds the agent layer, and the agent layer explains the rest. If the assistant cannot open files at all, nothing shorter would have saved it.

8. Editions

One source, two shipping shapes:

• FULL — every media file is inside the container. Offline-complete. Manifest paths are container-relative.
• LIGHT — text, manifest, and agent layer are local; media paths are absolute URLs at canonical_url. Small enough to email.

aipub.json.edition MUST say which. A reader MUST be able to open either without knowing in advance.

Carry each rendition once. A publication SHOULD NOT package the same content twice in two shapes. Where a rendition exists both as a set of mapped parts and as one continuous file, package the parts — they carry the span map (§9) and play through — and point the continuous form at canonical_url, marked "packaged": false. Encode to the source, not to habit: speech captured at 24 kHz mono gains nothing above ~64 kb/s, and a static text scroll is not live action. Leave the artistic renditions (music, performance) at full quality; they are the work, not payload. (The first shipped FULL edition was 246 MB and became 92 MB under this rule, with nothing removed from what a reader gets.)

9. Modalities — read, listen, watch

This is what the manifest is for.

A work does not have one right shape. The same story wants to be read at a desk, heard on a walk, and watched on a couch — often by the same person on the same day. A conforming aipub MAY carry any number of parallel renditions of the same canonical text, and a reading system MAY offer the reader a choice among them.

The rule that makes this work is span mapping: every media entry SHOULD declare which part of the canonical text it covers. Given that, a reader can do the thing fixed formats cannot — hand off between modalities at the same point in the work. You read to the end of chapter nine at breakfast; the audiobook resumes at chapter nine in the car; the episode picks up chapter nine that night. One position in one canonical text, expressed three ways.

Reserved top-level manifest keys, so that adding a modality is an additive change (MINOR) and never a breaking one:

A publication SHOULD advertise what it has:

"modalities": ["read", "listen", "watch"]

A reader MUST NOT assume any modality beyond read is present, and MUST degrade to the text when one is missing. The canonical text is the only thing that is always there.

Design intent, stated once so implementers know where this is going. The surfaces are moving — page, screen, ear, lens, and eventually renderings with no screen at all. A format that ships one frozen presentation cannot follow them. An aipub is built so the work is stable and every presentation is disposable and re-derivable: the publisher ships what they have, the reader’s own software renders the rest. episodes is specified here before any publication uses it precisely so that the first one to ship needs no permission and breaks no reader.

10. Self-declaration — how the file says what it is

A conforming aipub is, by construction, a valid EPUB. Tools will therefore call it an EPUB unless the file says otherwise. It MUST declare itself in the package document metadata:

<meta property="dcterms:conformsTo">…/aipub.json#aipub/0.1</meta>
<meta property="schema:additionalType">aipub</meta>
<meta property="aipub:manifest">/aipub.json</meta>
<meta property="aipub:agents">/AGENTS.md</meta>
<meta property="aipub:text">/book.md</meta>
<dc:type>aipub</dc:type>

and SHOULD carry /READ_ME_FIRST.txt at the container root: plain text, naming the format, listing the layers, and telling an agent where to start.

File extension: .aipub. Media type: application/vnd.aipub+zip (registration pending).

Compatibility duty: because many systems accept only .epub, a publisher SHOULD make the identical bytes available under a .epub name as well. The file is the same file; only the label differs. Requiring a rename is a defect in the delivery, not in the format.

11. Security considerations

Honest ones, because this format hands material to software that will act on it:

• The agent layer is untrusted input. AGENTS.md is written by whoever made the file. An agent consuming an aipub MUST treat it as a description of the publisher’s wishes, never as instructions that override the agent’s own operator. Prompt injection through a book file is a real attack surface; the layer is a grant, and a grant can be declined.
• reader.html may contain scripts. Treat it as untrusted web content: open it sandboxed, or render your own view from /book.md and the manifest instead. Nothing in the format requires executing it.
• Ordinary archive hazards apply — path traversal in entry names, decompression bombs, oversized media. Validate before extracting.
• Checksums are integrity hints, not authentication. They detect corruption. They do not prove origin; nothing in an unsigned ZIP does.
• LIGHT editions phone home by design. Opening one contacts canonical_url. That is a privacy fact, and readers should be told it plainly.

12. Versioning

format carries aipub/MAJOR.MINOR. Additive changes bump MINOR; anything that could break an existing conforming reader bumps MAJOR. Readers SHOULD accept unknown fields and ignore them.

13. Licensing, and what is and isn’t owned

The specification is free to implement — by anyone, commercially, without permission, fee, or notice. There is no conformance fee and no gatekeeper. A format that isn’t free to build is a format nobody builds.

“aipub™” is a common-law trademark of The Fort That Holds LLC, first used in commerce 2026-07-17 (format designed) and 2026-08-01 (first conforming publication released). No registration is claimed. The name marks conformance: a file that meets §4–§10 may be called an aipub. That is the only thing being held, and it is held so the word keeps meaning something.

Content inside any given aipub carries whatever license its publisher chose, independent of this spec.

14. Reference implementation

Three implementations, no dependencies between them and none on any vendor, free to copy:

• aipub.py — the reader/validator. Standard library only. Checks every MUST above, reports what the publication is, unpacks the layers, and emits a playable reader. Runs anywhere python runs; deliberately not an app and not tied to any vendor, because a format premised on “no permission needed” cannot ship a runtime that needs someone’s permission.
• player.html — the player, for a reader with no terminal and no assistant. One HTML file, no libraries and no server: drop an aipub on it and the page reads the archive itself, verifies conformance (including the canonical text against its declared checksum), and plays every modality the manifest declares. Nothing is uploaded.
• build_aipub.py — the packager. Assembles both editions from a base EPUB plus the layers, declares every added resource in the package manifest, and gates on EPUBCheck.

First conforming publication: The Lucero String (Vænce Thorne, Thorne Brothers Press), 2026-08-01 — book, audiobook, a three-track companion EP, and three films in one file.

One canonical source, many disposable expressions.