Workspace Upload Targets and ZIP Merge Behavior
How the Upload tab works in edit mode, what Workspace project vs Static preview site mean, how target paths are resolved, and what ZIP merge actually does.
Workspace Upload Targets and ZIP Merge Behavior
Where you see this in the app
This page explains the Upload tab inside the Workspace panel on a post you can edit.
You only see this tab in EDIT mode. Viewers in VIEW mode do not get upload controls.
Workspace project vs static preview site
The Upload target selector gives you two destinations:
| Upload target | What it means |
|---|---|
Workspace project | Upload into the main workspace project tree. Use this for source code, prompts, scripts, assets, and files that belong to the working app or automation project. |
Static preview site | Upload into the configured static preview directory. Use this when you want previewable site files without changing the rest of the project tree. |
Under the selector, the UI shows Destination root. That line tells you where the files will actually land.
If the post uses a custom Static preview directory, the static-preview destination follows that setting. It is not always the default path.
Target path and file rules
The Target path (optional) field only matters for single-file uploads.
| Situation | What happens |
|---|---|
| No files selected yet | The helper text tells you that a relative path is optional for single-file uploads. |
| One normal file selected | You can enter a relative path such as src/example.ts or nested/index.html. |
| One ZIP selected | The field is effectively ignored because ZIP uploads keep the paths stored inside the archive. |
| Multiple files selected | The field is disabled because each file keeps its own name. |
If you leave the field blank for a single normal file, GetPaidX writes the file using its original filename at the selected destination root.
ZIP merge and preview-only warning
The Upload tab explicitly says:
| Behavior | Meaning |
|---|---|
ZIP archives merge into the selected destination | Existing folders are not wiped first. The archive contents are layered into the selected root. |
overwrite matching files | If the archive contains a file that already exists at the same path, the uploaded version replaces it. |
When you target Static preview site, you may also see a yellow warning saying that the upload updates the static preview directory only, while Publish site still reads from the published-site directory.
| State | What it means |
|---|---|
| Preview path and publish path match | Your upload can affect both preview behavior and the files used for later publishing. |
| Preview path and publish path differ | Your upload may change the local preview, but Publish site will keep reading from a different project path until you move or copy the files there. |
How uploads relate to publish site
The success state says Upload applied and then shows how many paths changed.
That success message confirms the files entered the workspace, not that the site is already public.
From an end-user standpoint, the flow is:
- use
Uploadto place or merge files into the workspace, - verify the result in preview,
- use
Publish siteif you want a public artifact-site URL to update.
If you upload only to the static preview directory and your published-site directory is elsewhere, preview and public output can temporarily diverge. That is expected.
Common mistakes / confusing states
| Situation | What it usually means |
|---|---|
Uploads are only allowed in edit mode. | You launched the workspace in viewer mode or no longer have an active edit session. |
| Files appear in preview but not on the public share URL | You updated preview files but did not republish, or the publish directory is different from the preview directory. |
| A ZIP seems to remove changes | The archive probably overwrote matching files at the same paths. ZIP upload is a merge-with-overwrite action. |
| A file lands in an unexpected folder | Check the Destination root line and the optional Target path field before applying the upload. |
Related docs
Related docs
See it in action
Previous
Workspace Template Archive ZIP and Export Fidelity
How template ZIP archives are produced, what they preserve, and why advanced users should not assume the archive contains every ignored or controller-only file from a running workspace.
Next
Workspace Terminal, Helix, and Codex Tool Access
How the live preview and embedded workspace tools differ, what read-only viewer mode means for Terminal, Helix, and Codex, and how sessions and Codex shortcuts fit into edit-mode work.