# SendOff — files land in the user's own tree, and a push says where

**From:** mobile · **Date:** 2026-08-23 · **v2, replacing this morning's spec entirely.** The v1
design (staging area, transfer/target/file tables, ack lifecycle, TTL cleanup) is withdrawn — Andre's
observation kills it: every user already has a filesystem on the server, a file browser on the web,
and a Files app on the phone. SendOff is not a new storage system; it is a folder convention, one
endpoint, and a push.

## The convention

```
~/Downloads/sendoff/from-<username>/   ← a file another USER sent you
~/Downloads/sendoff/<machine>/         ← a file you sent yourself, aimed at a named device
```

That is the whole data model. Nothing to ack, nothing to expire, nothing to clean up — the files are
ordinary files in the recipient's tree, visible in every file UI that already exists, managed like
anything else they own.

## The endpoint

```
POST /api/sendoff/send
  multipart: any number of `file` parts + a `meta` part:
    { "toUser": "<username>" }        — cross-user: writes into THEIR tree, from-<sender>/
    { "machine": "<device name>" }    — self: writes into own tree, <machine>/
  → { path: "Downloads/sendoff/…", files: [{ name, size }] }
```

Server-side because of the cross-user case: `/api/file-browser/upload` correctly writes only the
caller's own tree, and that must not change. This endpoint is the one sanctioned door into another
user's filesystem, and it writes ONLY under `Downloads/sendoff/from-<sender>/` — the sender's
identity comes from their token, never from the payload, so the folder name cannot lie about who
sent it. Filenames sanitised, collisions suffixed `(1)` — never overwritten; a second send of the
same name is a second file.

Whether user A may send to user B at all is a platform policy decision (everyone on the server? a
grant?) — flagging it rather than deciding it here.

## The push

On write, push to the recipient's devices through the existing pipeline:

```
{ "officer": { "c": "officer/core:sendoff.landed", "path": "Downloads/sendoff/from-andre" } }
alert: "photo.jpg from andre" / "3 files from omega"
```

The push catalogue's route for the category:

```
officer://files?path={path}
```

Mobile opens routes from the catalogue verbatim (`openNotificationRoute`), and Officer now parses
`officer://files?path=…` into the Files app at that folder. The web can deep-link its file browser
the same way.

For a `machine`-targeted send, push only to that machine's device if it can be identified; to all
the user's devices otherwise — the path in the folder name already says who it was for.

## Devices

The `machine` name needs a picker on the sending side, so a minimal registry survives from v1:

```
devices: id (client uuid), user_id, name, platform, last_seen_at
POST /api/devices/register { id, name, platform }   (upsert; called on every app start)
GET  /api/devices → { devices }                     (the "send to my…" picker)
PATCH /api/devices/:id { name } · DELETE /api/devices/:id
```

No link to transfers — nothing references a device row except the picker and, best-effort, push
targeting.

## Web UI

One send form: files + target (one of my machines / another user), POST, done. Received files need
no UI at all — they are in the file browser already.

## What mobile already does (shipped against this)

- Registers the device on start (silent failure until the endpoint exists).
- Parses `officer://files?path=…` and opens the Files app at that path — this is the piece that
  makes the push tap land somewhere.
- SendOff screen: the device's name (the folder senders will aim at), and an explanation of where
  arrivals land. Sending FROM the phone comes later, likely through the existing share sheet.

## Out of scope

Receiving in the browser (already exists — it is the file browser); cross-user permission model
(platform decision); phone-side arbitrary-file sending (needs a document picker; the share sheet is
the natural door and is a later step).