Sandbox & Drafts
New code should land in the sandbox first. The sandbox is a dedicated folder, completely separate from any live plugin, theme, or uploads path, so a draft can never overwrite something live just because it has a similar name.
wp-content/wcforge-pro-drafts/Nothing in the sandbox is ever live automatically.
The Workflow
Write a draft
The AI calls wp_write_draft with a name (for example plugins/my-plugin/new-shortcode.php) and the full file content.
Review it
wp_list_drafts shows what is pending. You can also open the Activity tab, which has a draft browser and diff viewer showing the live file next to the proposed one.
Promote or discard
Promote with wp_promote_draft (needs confirm: true) to copy the draft to a real path inside wp-content, or discard it with wp_discard_draft. You can also promote or discard from the Activity tab yourself.
Promoting snapshots the existing live file first if one exists, so wp_restore_file can undo it. If another edit to the same path happened in the last 60 seconds, the result carries a warning, because that is the situation where a restore can land on the wrong "original".
Discarding a draft also removes any folders that became empty, but never the drafts root.
One-Time Upload Links
wp_create_upload_link generates a URL that lets a person, or any HTTP client, upload a file into the sandbox without a WordPress login.
| Option | Default | Notes |
|---|---|---|
draft_path | required | Where the file lands inside the sandbox |
max_bytes | 10 MB | Maximum accepted file size |
expires_in_minutes | 15 | Minimum 1 minute |
The link is single-use and accepts POST only, and it is rate-limited per IP like other public endpoints. The upload lands in the sandbox, never at a live path.
Anyone holding the link can upload during its lifetime. Share it only with the intended person, and keep the expiry short.
Direct Writes vs. Drafts
| Sandbox drafts | Direct writes | |
|---|---|---|
| Tools | wp_write_draft then wp_promote_draft | wp_write_file |
| Default | On | Off |
| Review step | Yes, with a diff viewer | None |
| Snapshot before change | On promote | On every write |
Prefer drafts. Turn on Allow direct live writes on the General tab only when you need it.