From 82f73b1fa38a89e73bc52849e178d82622d3fc38 Mon Sep 17 00:00:00 2001
From: Hongming Wang <hongmingwangalt@gmail.com>
Date: Wed, 29 Apr 2026 20:28:58 -0700
Subject: [PATCH] =?UTF-8?q?docs(chat=5Ffiles):=20update=20header=20?=
 =?UTF-8?q?=E2=80=94=20Download=20is=20HTTP-forward,=20not=20docker-cp?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The header comment claimed:
  "file upload (HTTP-forward) + download (Docker-exec)"
and:
  "Download still uses the v1 docker-cp path; migrating it lives in
   the next PR in this stack"

Both wrong now. RFC #2312 PR-D landed the Download HTTP-forward path:
chat_files.go:336 builds an http.NewRequestWithContext to
${wsURL}/internal/file/read?path=<abs>, with the response streamed
back to the caller. The workspace-side Starlette handler is at
workspace/internal_file_read.py, mounted at workspace/main.py:440.

Update the header to reflect actual code: both upload + download are
HTTP-forward, share the same per-workspace platform_inbound_secret
auth, and work uniformly on local Docker and SaaS EC2.

Pure docs change — no behavior, no build/test impact.
---
 .../internal/handlers/chat_files.go           | 30 ++++++++++++-------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/workspace-server/internal/handlers/chat_files.go b/workspace-server/internal/handlers/chat_files.go
index a7411c51..bed787de 100644
--- a/workspace-server/internal/handlers/chat_files.go
+++ b/workspace-server/internal/handlers/chat_files.go
@@ -1,18 +1,26 @@
 package handlers
 
-// chat_files.go — file upload (HTTP-forward) + download (Docker-exec)
-// for workspace chat.
+// chat_files.go — file upload + download for workspace chat,
+// both HTTP-forward (RFC #2312, fully landed).
 //
-// Upload is the v2 architecture (RFC #2312): the platform proxies the
-// multipart request straight to the workspace's own /internal/chat/
-// uploads/ingest endpoint. The workspace agent then writes to local
-// /workspace/.molecule/chat-uploads. Same code path on local Docker
-// and SaaS — the v1 docker-exec path was structurally broken in SaaS
-// because workspace-server's local Docker client has no visibility
-// into EC2-hosted workspaces (#2308 root cause).
+// Architecture (v2, post-RFC-#2312):
 //
-// Download still uses the v1 docker-cp path; migrating it lives in the
-// next PR in this stack so each surface is reviewable in isolation.
+//   - Upload (POST /workspaces/:id/uploads): the platform proxies the
+//     multipart request straight to the workspace's own
+//     /internal/chat/uploads/ingest endpoint. The workspace agent then
+//     writes to local /workspace/.molecule/chat-uploads.
+//
+//   - Download (GET /workspaces/:id/files): the platform makes an HTTP
+//     GET to the workspace's /internal/file/read?path=<abs> endpoint
+//     and streams the response body to the caller.
+//
+// Same code path on local Docker and SaaS — the v1 docker-exec /
+// docker-cp paths were structurally broken in SaaS because
+// workspace-server's local Docker client has no visibility into
+// EC2-hosted workspaces (#2308 root cause). Both surfaces now use the
+// per-workspace platform_inbound_secret minted at provision time
+// (RFC #2312 PR-F) for auth, and the workspace's HTTP server mounts
+// the corresponding receiver at workspace/main.py.
 //
 // Split from templates.go because these endpoints have a different
 // security model (no /configs write, no template fallback) and a