@@ -154,7 +154,7 @@ other adapter.
 | Method | Endpoint | SDK | Description |
 |:-------|:---------|:----|:------------|
 | POST | `/storage/upload/presigned` | `storage.getPresignedUrl` | Step 1 — mint an upload target for a new `sys_file` row |
-| POST | `/storage/upload/complete` | `storage.upload` | Step 3 — commit the uploaded bytes |
+| POST | `/storage/upload/complete` | `storage.upload` | Step 3 — commit the uploaded bytes; with `attachTo`, also attach the file to a record as the caller |
 | POST | `/storage/upload/chunked` | `storage.initChunkedUpload` | Open a chunked / resumable session |
 | PUT | `/storage/upload/chunked/:uploadId/chunk/:chunkIndex` | `storage.uploadPart` | Send one chunk |
 | POST | `/storage/upload/chunked/:uploadId/complete` | `storage.completeChunkedUpload` | Assemble the parts |
@@ -167,6 +167,13 @@ other adapter.
 so for a file whose type the browser does not know (`file.type === ''`) the
 helper sends `application/octet-stream`; a typed file keeps its own type.
 
+To attach the upload to a record's Attachments, send `attachTo: { parentObject,
+parentId }` with step 3 (and start the upload with `scope: 'attachments'`): the
+commit and the `sys_attachment` row are one unit, written as the signed-in
+caller, and the answer carries the `attachmentId`
+([attachment access](/docs/permissions/attachments-access)). A refused attach
+leaves the upload pending.
+
 A file field takes the `fileId` only after step 3. A signed-in record write
 that names a file whose upload was never completed is refused with `400
 VALIDATION_FAILED`, one `invalid_value` entry naming the field and the file,
 
@@ -72,6 +72,39 @@ drops a non-system caller's `uploaded_by` and reports it in `droppedFields`,
 and the rest of the write lands. System-context writes keep the value they
 supply.
 
+### Attaching an upload from the browser
+
+The Attachments panel attaches a file in the call that completes its upload:
+the presigned upload's `POST /api/v1/storage/upload/complete` carries
+`attachTo: { parentObject, parentId }`, and the server commits the file and
+writes its `sys_attachment` row as one unit, **as the signed-in user**. Every
+check above judges that user: the permission to create an attachment, edit
+access to the record, the record object's `enable.files`, and the file
+reference itself. The answer carries the new `attachmentId`. A refused attach
+leaves the upload `pending` and attached to nothing, and the pending-upload
+retention reclaims it.
+
+The file must be the caller's own upload, still `pending`, in the
+`attachments` scope, attached to nothing and owned by no record field, with its
+bytes stored. Any other file id — another user's upload, an id that names no
+file — is refused before anything is written:
+
+| Code | Status | When |
+| --- | --- | --- |
+| `PERMISSION_DENIED` | 403 | The file is another user's upload (the commit door's uploader rule) |
+| `FILE_NOT_FOUND` | 404 | The id names no file |
+| `RESOURCE_CONFLICT` | 409 | The upload is already completed, already attached or owned by a field, or its bytes are not stored |
+| `INVALID_REQUEST` | 400 | `attachTo` is malformed, or the upload was not started in the `attachments` scope |
+| `NOT_IMPLEMENTED` | 501 | The deployment composes no auth service or no data engine, so there is no caller to attach as |
+
+This is how a member who may attach files but holds no read on `sys_file`
+attaches one: a `sys_attachment` create through the generic data API
+(`POST /api/v1/data/sys_attachment`) names its `file_id` as any other
+`lookup` value, which the caller must be able to read, and a file they cannot
+read is refused `400 VALIDATION_FAILED` (`reference_not_found` on `file_id`).
+The attach on completion vouches for that one file, in that one call, and
+grants no read of `sys_file` or of anything else.
+
 | Code | Status | When |
 | --- | --- | --- |
 | `RECORD_NOT_ACCESSIBLE` | 403 | The session names no signed-in user to record as the uploader |
@@ -224,6 +257,7 @@ can be shared across records). Reclamation is handled by the platform LifecycleS
 | Operation | Requirement | Deny code |
 | --- | --- | --- |
 | Attach (create) | parent object opts in (`enable.files`) | `FILES_DISABLED` (403) |
+| Attach on upload completion (`attachTo`) | the caller's own pending, unattached `attachments`-scope upload, then every create check | `PERMISSION_DENIED` (403) / `RESOURCE_CONFLICT` (409), then the create codes |
 | Attach (create), re-point | a by-id update of the parent record by the caller would be admitted | `ATTACHMENT_PARENT_ACCESS` (403); `OBJECT_NOT_FOUND` (404) when the parent object is not registered |
 | List / read | inherits parent read visibility | *(filtered out)* |
 | Delete | uploader or parent editor (+ RBAC delete grant) | `ATTACHMENT_DELETE_DENIED` (403); `PERMISSION_DENIED` (403) when the parent is not readable or no delete grant is held |
 
@@ -129,7 +129,7 @@ All routes are mounted at `/api/v1/storage` (configurable via `basePath`).
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/upload/presigned` | Get presigned upload URL |
-| POST | `/upload/complete` | Mark upload as committed |
+| POST | `/upload/complete` | Mark upload as committed; with `attachTo: { parentObject, parentId }`, attach the caller's own pending upload to that record as the caller, in the same unit |
 | POST | `/upload/chunked` | Initiate chunked upload |
 | PUT | `/upload/chunked/:uploadId/chunk/:chunkIndex` | Upload a chunk |
 | POST | `/upload/chunked/:uploadId/complete` | Complete chunked upload |