From 119cc079ccb1a625b962ce2a7fcd9b0d58f1c126 Mon Sep 17 00:00:00 2001
From: Aditya Dhar <74172325+ProJedi1234@users.noreply.github.com>
Date: Mon, 24 Aug 2026 10:08:28 -0400
Subject: [PATCH] feat: publish an image or a video with `stele attach`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The server has stored attachments since it learned to, and its skill
document already tells agents to run this command — so until now the
live contract named a command that did not parse. That is the same
failure `--ttl` had, in the other direction: last time the document was
stale, this time the client was.

The request is a `publish` with a binary content type, because on the
server an attachment is a page whose body is bytes. What earns it a
command of its own is the answer, not the request. An attachment has two
URLs — the bytes under `/static/`, and a viewer page about the file —
and mixing them up fails silently, because an `<img>` pointed at the
viewer renders nothing and both answer 200. So stdout is the bytes,
which is the value `src=$(stele attach chart.png)` captures and the one
a page-writing agent needs; the viewer goes to stderr under the
deadline, for the human who wants to send someone a link.

`--json` names both and calls neither of them `url`. That key means "the
viewer" on every other command, so whichever meaning it took here would
be wrong half the time and wrong silently — a caller reaching for `.url`
would get a working URL of the wrong kind. Absent, they get nothing,
which is a failure they can see.

An unrecognised extension is refused before the upload rather than
guessed at. `publish` may fall through to `text/html` because that is
what it is for; the same shrug on a JPEG spends the upload and comes
back as a 415 naming a type nobody chose. `--filename` defaults to the
file's own basename and is omitted rather than refused when that name is
one the server would reject — the caller never typed it, and the
server's fallback is a working download where a 400 about an unpassed
parameter is not. An explicit `--filename` travels untouched.

Exit 6 and its two messages widen to cover an attachment. The status is
the same and the code stays one, because the caller's next move has the
same shape either way; what differs is the advice, and 413 now carries
both halves rather than telling someone with an oversized video to drop
their inline images.

0.4.0, in this commit: the server version-gates on the User-Agent, and a
capability its skill references should be a version an operator can
require.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md                             |  32 ++--
 Sources/SteleKit/Inputs.swift         |   7 +
 Sources/SteleKit/SteleError.swift     |  15 +-
 Sources/SteleKit/Version.swift        |   2 +-
 Sources/stele/Exit.swift              |   9 +-
 Sources/stele/PageCommands.swift      | 222 +++++++++++++++++++++++++-
 Sources/stele/Stele.swift             |   1 +
 Tests/SteleKitTests/InputsTests.swift |  10 ++
 scripts/integration-smoke.sh          | 100 ++++++++++--
 9 files changed, 371 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 835f0ea..c4cff8a 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,11 @@ $ stele publish report.html --slug q3-report --ttl never
 https://stele.example.com/q3-report
 kept until deleted
 
+$ stele attach chart.png --ttl never
+https://stele.example.com/static/plain-amber-heron
+kept until deleted
+page about it: https://stele.example.com/plain-amber-heron
+
 $ stele update q3-report report.html
 https://stele.example.com/q3-report
 kept until deleted
@@ -48,6 +53,13 @@ document. The deadline under the URL is on stderr for that reason, and it is pri
 because the server's default is *ephemeral* — a page published with no `--ttl` is eventually
 unpublished, and a caller handed only a URL would find that out when the link broke.
 
+`stele attach` is the one command whose stdout is not the URL the server answered with. An
+attachment has two: the bytes, under `/static/`, and a viewer page about the file. The bytes are
+what a page embeds and the viewer is what you send a person, and mixing them up fails silently —
+an `<img>` pointed at the viewer renders nothing, and both answer `200`. So the bytes go to
+stdout, where `src=$(stele attach chart.png)` captures them, and the viewer goes to stderr
+beneath the deadline. `--json` names both and calls neither of them `url`.
+
 ## Commands
 
 | Command | Who runs it | Does |
@@ -56,6 +68,7 @@ unpublished, and a caller handed only a URL would find that out when the link br
 | `stele auth status` | agent or human | Host, client name, scopes, expiry — never the token. |
 | `stele auth logout` | human | Forgets the local credential. Does not revoke it. |
 | `stele publish <file> [--slug <name>] [--ttl <days>]` | agent | `POST /pages`. Prints the URL on stdout and the page's deadline on stderr. |
+| `stele attach <file> [--slug <name>] [--ttl <days>] [--filename <name>]` | agent | `POST /pages` with a binary type. Publishes an image, video or PDF. Prints the URL of the *bytes* on stdout — the one that goes in an `<img src>` — and the viewer's under the deadline on stderr. |
 | `stele update <slug> <file>` | agent | `PUT /pages/:slug`. Never creates, and never changes the deadline. |
 | `stele amend <slug> [--slug <name>] [--ttl <days>]` | agent | `PATCH /pages/:slug`. Renames a page, moves its deadline, or both, without touching a byte of it. A rename is a hard move — the old URL starts 404ing at once. |
 | `stele delete <slug>` | agent | `DELETE /pages/:slug`. Permanent and immediate — the slug is freed and returns to the pool, so every link to it breaks. Prints nothing on stdout; the confirmation is on stderr. |
@@ -206,7 +219,7 @@ table.
 | 3 | the server rejected the credential — ask the user to log in again |
 | 4 | valid credential, insufficient scope — an operator has to run this |
 | 5 | that slug is taken — ask for a different `--slug` |
-| 6 | the page is too large or the wrong type |
+| 6 | the file is too large or a type the server will not store |
 | 7 | no such page or client |
 | 8 | the CLI is too old — reinstall it and retry once |
 | 9 | could not reach the server — retryable |
@@ -402,7 +415,7 @@ mint the first client. Arguments may also arrive as `STELE_SMOKE_HOST`, `STELE_S
 | `--psql <command>` | optional | A command that reaches the server's database, e.g. `docker exec stele-postgres psql -U stele -d stele_smoke`. Only the attribution check needs it, because no route reports who wrote a page — without it that one check prints `skip`. |
 
 It walks the whole documented lifecycle — mint, log in, `auth status`, publish, fetch the bytes
-back and compare them, update, amend, `--expires-in` there *and* back, expiry actually enforced,
+back and compare them, attach, update, amend, `--expires-in` there *and* back, expiry enforced,
 a publish-only credential answered `200` by whoami and `403` by the admin routes, revocation that
 really stops working, the exit-code vocabulary, the version gate, and the byte-identity of every
 `404`. It prints each check, stops at the first failure, and exits non-zero.
@@ -424,13 +437,14 @@ Two things it does not do, stated because a canary you trust wrongly is worse th
   refuses a pipe; the script asserts the *refusal* — which is the load-bearing custody rule — and
   then seeds the credential file at `0600` in the documented format for the rest of the run. The
   prompt, the echo-off read and the verify-before-write are not covered.
-- **It leaves litter.** The server has a delete route but this CLI ships no command that reaches
-  it, so each run leaves eight pages and three
-  credential rows behind; it revokes every credential it mints, but a revoked row is still a row.
-  Five of those pages expire on their own — the lifetime checks publish several deliberately —
-  but three were published or amended to `--ttl never` and will still be there next year. The
-  footer names those three, since they are the only ones a human ever has to clean up. Run it
-  against a throwaway deployment, never against production.
+- **It leaves litter.** Each run leaves ten pages and three credential rows behind. The pages it
+  deletes it deletes on purpose, to prove the verb works; the rest are the evidence the later
+  checks read, so they outlive the run. Credentials cannot be cleaned up at all — it revokes
+  every one it mints, but a revoked row is still a row. Seven of those pages expire on their own
+  — the lifetime checks publish several deliberately — but three were published or amended to
+  `--ttl never` and will still be there next year. The footer names those three, since they are
+  the only ones a human ever has to clean up. Run it against a throwaway deployment, never
+  against production.
 
 It also moves `~/.config/stele/credentials.json` aside and restores it on every exit path,
 including a failed check — see the `HOME` note under Configuration for why it cannot simply use a
diff --git a/Sources/SteleKit/Inputs.swift b/Sources/SteleKit/Inputs.swift
index 3344d22..5cdd723 100644
--- a/Sources/SteleKit/Inputs.swift
+++ b/Sources/SteleKit/Inputs.swift
@@ -59,6 +59,13 @@ public enum ContentType {
     /// What `stele attach --content-type` offers at TAB.
     public static var knownAttachments: [String] { Set(attachmentsByExtension.values).sorted() }
 
+    /// The same table read the other way, for the message a refused file earns.
+    ///
+    /// Extensions rather than types, because they are what the person is holding. Told that a
+    /// deployment takes `image/png`, someone looking at `diagram.graffle` still has to work out
+    /// what to do; told the list is `png, jpg, …`, they already know.
+    public static var knownAttachmentExtensions: [String] { attachmentsByExtension.keys.sorted() }
+
     /// The type to upload a file as, or nil when the extension says nothing.
     ///
     /// Optional where `inferred` is not, and that difference is the whole point. `text/html` is
diff --git a/Sources/SteleKit/SteleError.swift b/Sources/SteleKit/SteleError.swift
index a85c05c..64539d4 100644
--- a/Sources/SteleKit/SteleError.swift
+++ b/Sources/SteleKit/SteleError.swift
@@ -95,16 +95,23 @@ public enum SteleError: Error, Equatable, CustomStringConvertible {
                 name, or retire the existing one with `stele admin clients revoke <name>` and \
                 mint again — rotating a credential is revoke-then-mint under the same name.
                 """
+        // Two limits behind one status, and the advice differs by which was hit. A page's is
+        // small and is usually blown by something that did not need to be inline; an
+        // attachment's is far larger and blowing it means the file is genuinely too big. This
+        // side cannot tell them apart — the status is the same and the command is not in scope
+        // here — so both remedies are named rather than the wrong one being guessed at.
         case .pageTooLarge(let detail):
             return """
-                the page is over the server's size limit\(Self.suffix(detail)) Drop inline \
-                images and link them instead — the limit is on the HTML, and a data: URI \
-                counts against it.
+                the file is over the server's size limit\(Self.suffix(detail)) For a page, \
+                publish images with `stele attach` and link them instead of inlining them — a \
+                data: URI counts against the HTML. For an attachment, it is over this \
+                deployment's ceiling, which is a much larger one.
                 """
         case .unsupportedContentType(let detail):
             return """
                 the server will not store that content type\(Self.suffix(detail)) Publish one \
-                of the types it lists, or leave the type to the CLI.
+                of the types it lists, or leave the type to the CLI — pages and attachments \
+                accept different ones.
                 """
         case .upgradeRequired(let detail):
             return """
diff --git a/Sources/SteleKit/Version.swift b/Sources/SteleKit/Version.swift
index 39f664b..320797d 100644
--- a/Sources/SteleKit/Version.swift
+++ b/Sources/SteleKit/Version.swift
@@ -8,7 +8,7 @@
 public enum SteleVersion {
     /// Bumped by hand. Nothing derives it from git: a release built from a tarball or an
     /// unclean tree must still report a version the server can compare.
-    public static let current = "0.3.0"
+    public static let current = "0.4.0"
 
     /// Sent on every request. The `stele-cli/` product token is what the server matches on.
     public static var userAgent: String { "stele-cli/\(current)" }
diff --git a/Sources/stele/Exit.swift b/Sources/stele/Exit.swift
index 542602f..e24a3fb 100644
--- a/Sources/stele/Exit.swift
+++ b/Sources/stele/Exit.swift
@@ -40,8 +40,11 @@ enum Exit {
     /// which is why the message carries the route's own advice and this table does not repeat it.
     static let slugTaken: Int32 = 5
 
-    /// `413` / `415` — the page itself is the problem. Retrying is pointless; the input changes
-    /// or nothing does.
+    /// `413` / `415` — the file itself is the problem, whether it was a page or an attachment.
+    /// Retrying is pointless; the input changes or nothing does. The two are one code because
+    /// the caller's next move is the same shape either way, and `SteleError` carries the half
+    /// that differs: a page over the limit usually has something inline that `stele attach`
+    /// should have published, and an attachment over it is simply too big for the deployment.
     static let pageRejected: Int32 = 6
 
     /// `404` — an update to a slug that does not exist, an amendment or a deletion aimed at one
@@ -70,7 +73,7 @@ enum Exit {
             (credentialRejected, "the server rejected the credential — ask the user to log in again"),
             (forbidden, "valid credential, insufficient scope — an operator has to run this"),
             (slugTaken, "that slug is taken — ask for a different --slug"),
-            (pageRejected, "the page is too large or the wrong type"),
+            (pageRejected, "the file is too large or a type the server will not store"),
             (notFound, "no such page or client"),
             (upgradeRequired, "the CLI is too old — reinstall it and retry once"),
             (unreachable, "could not reach the server — retryable"),
diff --git a/Sources/stele/PageCommands.swift b/Sources/stele/PageCommands.swift
index 4c5c8d2..edfc814 100644
--- a/Sources/stele/PageCommands.swift
+++ b/Sources/stele/PageCommands.swift
@@ -60,7 +60,10 @@ enum PageIO {
     ///
     /// Absolute, never "in 7 days", for the reason `Format.moment` already gives: the follow-up
     /// question to a relative date is always "so what date is that".
-    private static func lifetime(_ location: PageLocation) -> String {
+    ///
+    /// Not private, because `attach` prints its own stdout line and this one underneath it. One
+    /// spelling of a deadline across every command that has one to report.
+    static func lifetime(_ location: PageLocation) -> String {
         guard let expiry = location.expiresAt else { return "kept until deleted" }
         return "expires \(Format.moment(expiry))"
     }
@@ -146,6 +149,223 @@ struct PublishCommand: SteleCommand {
     }
 }
 
+/// Publishes bytes — an image, a video, a PDF — rather than a page.
+///
+/// The same route as `publish`, because on the server an attachment *is* a page whose body is
+/// bytes. What makes this a separate command is not the request but the answer: an attachment
+/// has two URLs, and which one a caller gets handed decides whether the page they write works.
+struct AttachCommand: SteleCommand {
+    static let configuration = CommandConfiguration(
+        commandName: "attach",
+        abstract: "Publish an image, video or file. Prints the URL of the bytes.",
+        discussion: """
+            For the things a page links to rather than the page itself. Publish the file first, \
+            then put the URL you get back into the page you write:
+
+              src=$(stele attach screenshot.png)
+
+            Prints nothing but that URL on stdout, so the capture above works. It is \
+            deliberately the URL of the *bytes* — the one that belongs in an <img src> or a \
+            <video src>. The attachment has a second URL, a page about the file with its name, \
+            size and deadline, and that is the one to send a person; it goes to stderr under \
+            the deadline, and --json names both. Getting them the wrong way round fails \
+            silently — an <img> pointed at the viewer renders nothing, and both answer 200.
+
+            The type comes from the file's extension, and an extension this tool does not \
+            recognise is refused here rather than uploaded: use --content-type when the \
+            extension is missing or lying. The server keeps the real list and has the last word.
+
+            Attachments expire like pages, and this is the thing to get right because nothing \
+            will warn you: a page and the images inside it are separate publications with \
+            separate deadlines. A permanent page whose screenshots took the default becomes a \
+            page of broken images a week later, with no request failing at the time. Ask for \
+            the same --ttl on both.
+
+            `stele update`, `stele amend` and `stele delete` reach an attachment at its slug \
+            exactly as they reach a page.
+            """
+    )
+
+    @OptionGroup var options: GlobalOptions
+
+    @Argument(
+        help: ArgumentHelp("The file to publish.", valueName: "file"),
+        completion: .file()
+    )
+    var file: String
+
+    @Option(
+        name: .long,
+        help: ArgumentHelp(
+            "Publish at this slug instead of a generated one.",
+            discussion: "Lowercase letters, digits and hyphens. The server has the last word.",
+            valueName: "name"
+        )
+    )
+    var slug: String?
+
+    @Option(
+        name: .long,
+        help: ArgumentHelp("Override the type inferred from the file extension.", valueName: "type"),
+        completion: .list(ContentType.knownAttachments)
+    )
+    var contentType: String?
+
+    @Option(
+        name: .long,
+        help: ArgumentHelp(
+            "How long the file lives: a number of days, or 'never'.",
+            discussion: """
+                Means exactly what it means on `stele publish`, including the default — a file \
+                you say nothing about expires on the server's own schedule. Match it to the \
+                lifetime of the page that embeds it.
+                """,
+            valueName: "days"
+        ),
+        completion: .list([PageTTL.neverKeyword, "7", "30", "90"])
+    )
+    var ttl: String?
+
+    @Option(
+        name: .long,
+        help: ArgumentHelp(
+            "The name a browser saves the file under.",
+            discussion: """
+                Defaults to the name of the file you uploaded. Worth setting when that name is \
+                a temporary one: a slug is a name for a URL, and a download called \
+                quiet-cedar-otter opens in nothing.
+                """,
+            valueName: "name"
+        )
+    )
+    var filename: String?
+
+    func execute() async throws {
+        let bytes = try PageIO.read(file)
+        // Refused before the credential is read and long before the bytes travel. The server
+        // would answer this with a 415 of its own, but it would be answering about a type this
+        // side chose by defaulting — and `text/html` on a JPEG is not a disagreement with the
+        // server, it is a guess nobody made. Naming the flag is the whole value of catching it
+        // here; the same bargain `amend` strikes over having nothing to amend.
+        let type = try contentType ?? ContentType.attachmentInferred(fromPath: file)
+            .orThrow(Failure("""
+                cannot tell what kind of file \(file) is from its extension. Pass \
+                --content-type <type>, or use a file this tool recognises: \
+                \(ContentType.knownAttachmentExtensions.joined(separator: ", ")).
+                """))
+        let lifetime = try ttl.map { raw -> PageTTL in
+            do { return try PageTTL.parse(raw) } catch { throw Failure("\(error)") }
+        }
+        let credential = try options.credential()
+        let location = try await SteleClient(credential: credential).publish(
+            page: bytes,
+            contentType: type,
+            slug: slug,
+            ttl: lifetime,
+            filename: filename ?? Self.derivedFilename(from: file),
+            using: credential
+        )
+        try report(location)
+    }
+
+    /// The name to save the upload under when the caller did not choose one.
+    ///
+    /// The file's own basename, which is what the skill promises and is nearly always the name
+    /// the person meant. Nil when that name is one the server would refuse: those rules exist
+    /// because the value ends up in a `Content-Disposition`, and a filename with a quote in it
+    /// can close the header's quoted string early.
+    ///
+    /// Omitting beats failing here, and only here. This name was *derived* — the caller never
+    /// typed it — so refusing the upload over it would be a 400 about a parameter they did not
+    /// pass, when the server's own fallback (the slug) is a working download. An explicit
+    /// `--filename` skips this entirely and travels untouched, whatever it says, because there
+    /// the caller has an opinion and the server is the one that gets to answer it. The check is
+    /// a hint, not a copy of the rule — the same arrangement `ContentType` runs on.
+    static func derivedFilename(from path: String) -> String? {
+        let name = (path as NSString).lastPathComponent
+        guard !name.isEmpty, name.count <= 255 else { return nil }
+        let refused: Set<Character> = ["\"", "\\", "/", "\r", "\n", "\0"]
+        guard !name.contains(where: { refused.contains($0) || $0.isASCIIControl }) else {
+            return nil
+        }
+        return name
+    }
+
+    /// The report `PageIO.report` cannot make, because the URL an attachment answers with is
+    /// not the URL an attachment is used by.
+    private func report(_ location: PageLocation) throws {
+        // A viewer URL this client cannot turn into a bytes URL is a server answering
+        // strangely. Reported rather than papered over with the viewer: printing that on stdout
+        // would put the wrong URL into a page, which is the one outcome this command exists to
+        // prevent, and it would do it silently.
+        guard let bytes = SteleClient.bytesURL(for: location) else {
+            throw SteleError.malformedResponse(
+                "the server's URL for the attachment was not one this client could read"
+            )
+        }
+        if options.json {
+            Terminal.out(try Format.json(AttachmentReport(location: location, bytes: bytes)))
+            return
+        }
+        // Bare, and the bytes rather than the viewer: this is the value that gets captured and
+        // pasted into an `<img src>`.
+        Terminal.out(bytes)
+        Terminal.error(options.style.dim(PageIO.lifetime(location)))
+        Terminal.error(options.style.dim("page about it: \(location.url)"))
+    }
+}
+
+/// `stele attach --json`.
+///
+/// Hand-written rather than an encoding of `PageLocation`, and neither URL is called `url` —
+/// which is the decision worth keeping. `PageLocation.url` means "the viewer" everywhere else
+/// in this tool, and stdout here is the bytes, so whichever meaning `url` took would be wrong
+/// half the time and wrong *silently*: a caller reaching for `.url` would get a working URL of
+/// the wrong kind. Absent, they get nothing, and nothing is a failure they can see.
+private struct AttachmentReport: Encodable {
+    let slug: String
+    /// The file itself. What goes in an `<img src>`.
+    let bytes: String
+    /// The page about the file. What you send a person.
+    let viewer: String
+    /// Explicitly null for an attachment kept until it is deleted, never absent — a missing key
+    /// and a null one read the same to a careless caller, and `PageLocation` hand-writes its
+    /// encoder for this reason.
+    let expires: Date?
+
+    init(location: PageLocation, bytes: String) {
+        self.slug = location.slug
+        self.bytes = bytes
+        self.viewer = location.url
+        self.expires = location.expiresAt
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case slug, bytes, viewer, expires
+    }
+
+    func encode(to encoder: any Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(slug, forKey: .slug)
+        try container.encode(bytes, forKey: .bytes)
+        try container.encode(viewer, forKey: .viewer)
+        try container.encode(expires, forKey: .expires)
+    }
+}
+
+extension Character {
+    /// The C0 controls, which cannot appear in a header value.
+    var isASCIIControl: Bool { isASCII && (asciiValue ?? 0x20) < 0x20 }
+}
+
+extension Optional {
+    /// `??` for a value that has an error rather than a fallback behind it.
+    func orThrow(_ error: @autoclosure () -> some Error) throws -> Wrapped {
+        guard let self else { throw error() }
+        return self
+    }
+}
+
 struct UpdateCommand: SteleCommand {
     static let configuration = CommandConfiguration(
         commandName: "update",
diff --git a/Sources/stele/Stele.swift b/Sources/stele/Stele.swift
index 4c33be4..560879b 100644
--- a/Sources/stele/Stele.swift
+++ b/Sources/stele/Stele.swift
@@ -29,6 +29,7 @@ struct Stele: AsyncParsableCommand {
         subcommands: [
             AuthCommand.self,
             PublishCommand.self,
+            AttachCommand.self,
             UpdateCommand.self,
             AmendCommand.self,
             DeleteCommand.self,
diff --git a/Tests/SteleKitTests/InputsTests.swift b/Tests/SteleKitTests/InputsTests.swift
index 650e853..a7fd94a 100644
--- a/Tests/SteleKitTests/InputsTests.swift
+++ b/Tests/SteleKitTests/InputsTests.swift
@@ -84,6 +84,16 @@ struct InputsTests {
         #expect(ContentType.inferred(fromPath: "screenshot.png") == ContentType.fallback)
     }
 
+    /// What a refused file's message lists. Extensions, because that is what the person is
+    /// holding — `image/png` is not an answer to "so what do I do with this .graffle".
+    @Test("the refusal message can name the extensions, not just the types")
+    func knownAttachmentExtensionsAreListed() {
+        #expect(
+            ContentType.knownAttachmentExtensions
+                == ["gif", "jpeg", "jpg", "mp4", "pdf", "png", "webm", "webp"]
+        )
+    }
+
     /// SVG is the one image format that is also a document. The server does not accept it, and
     /// offering it here would turn a considered `415` into a type this tool appears to know.
     @Test("svg is not an attachment type this tool offers")
diff --git a/scripts/integration-smoke.sh b/scripts/integration-smoke.sh
index f097e2b..0c35228 100755
--- a/scripts/integration-smoke.sh
+++ b/scripts/integration-smoke.sh
@@ -365,6 +365,88 @@ expect_eq "…and nothing was published" "" "$OUT"
 run_stele publish "$WORK/page.html" --ttl 3650000
 expect_eq "a lifetime past the server's ceiling is a 400, exit 1" "1" "$STATUS"
 
+# ---------------------------------------------------------------------------------
+section "4c. attach publishes bytes, and hands back the right one of two URLs"
+# ---------------------------------------------------------------------------------
+
+# A real PNG rather than bytes that merely claim to be one: the viewer renders it in an <img>,
+# and a server that stored it as text would corrupt it in a way `cmp` catches.
+base64 -d > "$WORK/dot.png" <<'B64'
+iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAFUlEQVR42mP8z8BQz0AEYBxVSF+FABJADveWkH6oAAAAAElFTkSuQmCC
+B64
+
+run_stele attach "$WORK/dot.png"
+expect_eq "attach exits 0" "0" "$STATUS"
+BYTES_URL="$OUT"
+ATTACH_SLUG="${BYTES_URL##*/}"
+VIEWER_URL="$HOST/$ATTACH_SLUG"
+# The whole reason this command prints something `publish` does not. stdout is the bytes,
+# because that is the value that goes into an <img src>; a viewer URL here would render nothing
+# and answer 200 while doing it.
+case "$BYTES_URL" in
+    "$HOST"/static/*) pass "attach prints the bytes URL on stdout ($ATTACH_SLUG)" ;;
+    *) fail "attach prints the bytes URL" "$HOST/static/<slug>" "$BYTES_URL" ;;
+esac
+if [ "$(printf '%s' "$OUT" | wc -l)" -eq 0 ]; then
+    pass "…and stdout is that one line and nothing else"
+else
+    fail "stdout stays one line" "just the bytes URL" "$OUT"
+fi
+expect_contains "…with the deadline on stderr" "expires" "$ERR"
+expect_contains "…and the viewer URL beside it, for a human" "$VIEWER_URL" "$ERR"
+
+curl -sS "$BYTES_URL" -o "$WORK/fetched.png"
+if cmp -s "$WORK/dot.png" "$WORK/fetched.png"; then
+    pass "the attachment comes back byte for byte"
+else
+    fail "the attachment comes back byte for byte" "the PNG that was sent" "differing bytes"
+fi
+expect_eq "…served as the type it went up as" "image/png" \
+    "$(curl -sS -o /dev/null -w '%{content_type}' "$BYTES_URL")"
+
+# The second URL, and the reason the two may not be confused: this one is a document *about*
+# the file. Both answer 200, which is why getting them the wrong way round fails silently.
+expect_eq "the viewer URL answers too" "200" "$(http_status "$VIEWER_URL")"
+expect_contains "…as HTML, not as the bytes" "text/html" \
+    "$(curl -sS -o /dev/null -w '%{content_type}' "$VIEWER_URL")"
+
+# --filename is the one flag attach has that publish does not, and the header is the only place
+# its effect is visible. Without it a browser saves the download under the slug, which opens in
+# nothing.
+run_stele attach "$WORK/dot.png" --filename "architecture diagram.png" --json
+expect_eq "attach --json exits 0" "0" "$STATUS"
+printf '%s' "$OUT" > "$WORK/attach.json"
+expect_eq "…and --json puts nothing on stderr" "" "$ERR"
+expect_contains "…naming the bytes" "/static/" "$(json_field "$WORK/attach.json" bytes)"
+expect_eq "…and the viewer separately" "$HOST/$(json_field "$WORK/attach.json" slug)" \
+    "$(json_field "$WORK/attach.json" viewer)"
+# Neither is called `url`, deliberately: that key means "the viewer" on every other command, so
+# whichever meaning it took here would be wrong half the time and wrong silently.
+expect_eq "…and neither of them is called 'url'" "absent" \
+    "$(json_key_state "$WORK/attach.json" url)"
+expect_contains "the requested filename reaches the download header" "architecture diagram.png" \
+    "$(curl -sS -D - -o /dev/null "$HOST/static/$(json_field "$WORK/attach.json" slug)")"
+
+# Refused here, before the upload, and that is the point: the server would answer a 415 about
+# `text/html`, a type nobody chose, because falling back to it is what `publish` does.
+cp "$WORK/dot.png" "$WORK/mystery"
+run_stele attach "$WORK/mystery"
+expect_eq "a file whose extension says nothing is refused, exit 1" "1" "$STATUS"
+expect_contains "…and the message names the way through" "--content-type" "$ERR"
+expect_eq "…and nothing was published" "" "$OUT"
+
+run_stele attach "$WORK/mystery" --content-type image/png
+expect_eq "…while an explicit --content-type sends it" "0" "$STATUS"
+FORCED_BYTES="$OUT"
+expect_eq "…and it is served" "200" "$(http_status "$FORCED_BYTES")"
+
+# The three verbs that already existed reach an attachment at its slug, because on the server
+# an attachment is a page whose body is bytes. None of them learned what one is.
+run_stele delete "${FORCED_BYTES##*/}"
+expect_eq "delete takes an attachment down" "0" "$STATUS"
+expect_eq "…and the bytes are gone" "404" "$(http_status "$FORCED_BYTES")"
+expect_eq "…as is the page about them" "404" "$(http_status "$HOST/${FORCED_BYTES##*/}")"
+
 # ---------------------------------------------------------------------------------
 section "5. update replaces it in place"
 # ---------------------------------------------------------------------------------
@@ -706,14 +788,14 @@ expect_contains "…and returns the server's own skill document" "stele auth sta
 # ---------------------------------------------------------------------------------
 
 printf '\n\033[32msmoke: %d checks passed.\033[0m\n' "$CHECKS"
-# Eight pages, and the count is kept honest by hand because nothing here tracks them: sections 4
-# and 8 publish one each, 4b publishes four to compare lifetimes, and 5b leaves two. Only the
-# three below are permanent — the rest carry a deadline and the server reclaims them on its own
-# schedule — so those three are the ones named, because they are the ones a human ends up
-# deleting. Naming two of the ephemeral ones instead, as this line used to, sent whoever was
-# tidying up home with six rows still on the deployment.
-printf 'Left behind on %s: 8 pages and %d client rows, revoked.\n' "$HOST" 3
-printf 'Five of the pages expire on their own; these three never do: %s, %s, %s.\n' \
+# Ten rows, and the count is kept honest by hand because nothing here tracks them: sections 4
+# and 8 publish one each, 4b publishes four to compare lifetimes, 4c leaves two attachments, and
+# 5b leaves two. Only the three below are permanent — the rest carry a deadline and the server
+# reclaims them on its own schedule — so those three are the ones named, because they are the
+# ones a human ends up deleting. Naming two of the ephemeral ones instead, as this line used to,
+# sent whoever was tidying up home with six rows still on the deployment.
+printf 'Left behind on %s: 10 pages and %d client rows, revoked.\n' "$HOST" 3
+printf 'Seven of the pages expire on their own; these three never do: %s, %s, %s.\n' \
     "$NEVER_SLUG" "$MOVED" "$KEPT_MOVED"
-printf 'The server has no delete route, so pages and revoked credentials accumulate —\n'
+printf 'Revoked credentials have no route that removes them, so those rows accumulate —\n'
 printf 'which is why this belongs on a throwaway deployment, not a real one.\n'