@pixlcore/xycli 1.0.9 → 1.1.0

package/README.md

@@ -27,6 +27,7 @@ Browse the [screenshot gallery](docs/screenshots.md) for more views, or jump to
 - [Global CLI switches](#global-cli-switches)
 - [Tutorial: your first Event, job, and Web Hook](docs/tutorial.md)
 - [Tutorial: two-way sync with Git](docs/two-way-git-tutorial.md)
+- [Tutorial: two-way sync with event-driven deletes](docs/two-way-delete-tutorial.md)
 - [Explore and manage xyOps](#explore-and-manage-xyops)
 - [Transfer data between systems](#transfer-data-between-systems)
 - [Sync your automation with local files](#sync-your-automation-with-local-files)
@@ -513,10 +514,12 @@ The push above updates xyOps immediately. Remove `--dry` from the pull command t
 
 Sync supports Alerts, API Keys, Categories, Channels, Events and workflows, Groups, Monitors, Plugins, Tags, and Web Hooks. It updates existing objects and files; use creation commands, imports, setup, or exports to introduce new ones. Two-way sync is experimental and uses modification times, so one-way sync is a better fit for a Git-based source of truth.
 
-Delete mode is for up-sync only: it removes eligible xyOps objects missing from your local inventory. Objects with a `stock` or `marketplace` property are always protected from deletion and need no local files. Keep a complete inventory of the other objects you intend to retain for each selected type, and review a dry run before applying it. Sync applies changes without a confirmation step unless you use `--dry`.
+Delete mode works in one direction per run. Up-only deletion removes eligible xyOps objects missing from your local inventory; down-only deletion removes local XYPDF definitions and Bucket files missing from xyOps. Objects with a `stock` or `marketplace` property are protected from deletion. Keep a complete inventory on the authoritative side for each selected type, and review a dry run before applying it. Sync applies changes without a confirmation step unless you use `--dry`.
 
 Follow the [Two-Way Git Sync Tutorial](docs/two-way-git-tutorial.md) to connect one persistent checkout to a shared repository, commit downloaded changes, discover new Events, and schedule the complete workflow with cron or xySat.
 
+For an event-driven workflow that deletes in both directions, creates new definitions only in xyOps, and uses no recurring sync schedule, follow the [Two-Way Git Sync with Event-Driven Deletes Tutorial](docs/two-way-delete-tutorial.md).
+
 Read the dedicated [Sync Guide](docs/sync.md) for setup, file layouts, every option, saved defaults, two-way sync, deletion, notifications, and automation with cron, Git hooks, and GitHub Actions.
 
 - **Command reference:** [Sync commands](docs/help.md#sync) and [Sync setup](docs/help.md#sync-setup).

package/docs/help.md

@@ -188,7 +188,7 @@ Your configured permissions still apply during import. If an item fails, import
 
 ## sync
 
-For setup, configuration, file layouts, and automation examples, see the dedicated [Filesystem Sync Guide](sync.md).
+For setup, configuration, file layouts, and automation examples, see the dedicated [Filesystem Sync Guide](sync.md). For separate Git- and xyOps-triggered delete passes, see the [event-driven two-way delete tutorial](two-way-delete-tutorial.md).
 
 Sync existing xyOps definitions with a directory of XYPDF files. Each run scans the directory and its subdirectories, shows any differences, and applies changes in the directions you select. **Changes are applied immediately unless you add `--dry`; there is no `--confirm` step.**
 
@@ -225,20 +225,22 @@ Repeated sources with the same type and ID generate warnings, even if their cont
 
 External string properties are loaded automatically from adjacent files named `BASENAME-PROPERTY.EXT`, such as `My-Plugin-script.js` beside `My-Plugin.json`, or `My-Event-params.script.sh` beside `My-Event.json`. The extension is your choice. Keep only one external file per property, and rename its basename along with the JSON file.
 
-Bucket metadata uses a normal XYPDF source. For a Bucket titled `My Bucket Name`, its separate JSON data and uploaded files live beside `buckets/My-Bucket-Name.json` in `buckets/My-Bucket-Name/data.json` and `buckets/My-Bucket-Name/files/`. Both `data.json` and `files/` are required for a selected local bucket. Bucket data upsync replaces the entire remote data object. Bucket files are matched by xyOps filename normalization and transferred according to size and modification time. Two-way bucket sync uses the data record and file timestamps from xyOps; a transfer updates local file times to match. Bucket files missing locally are deleted remotely only with up-only `--delete buckets`.
+Bucket metadata uses a normal XYPDF source. For a Bucket titled `My Bucket Name`, its separate JSON data and uploaded files live beside `buckets/My-Bucket-Name.json` in `buckets/My-Bucket-Name/data.json` and `buckets/My-Bucket-Name/files/`. Both `data.json` and `files/` are required for a selected local bucket. Bucket data upsync replaces the entire remote data object. Bucket files are matched by xyOps filename normalization and transferred according to size and modification time. Two-way bucket sync uses the data record and file timestamps from xyOps; a transfer updates local file times to match. Up-only `--delete buckets` removes remote files missing locally; down-only `--delete buckets` removes local files missing remotely.
 
 **Delete mode**
 
-Add `--delete TYPES` to delete xyOps objects that have no matching source in the scanned directories. Deletion requires up-only sync and a complete local inventory. The CLI rejects deletion if upsync is disabled or any downsync direction is enabled, including saved defaults and dry runs. Use `--down false` to disable inherited downsync. See [Delete mode](sync.md#delete-mode) before using it.
+Add `--delete TYPES` to remove definitions missing from the authoritative side of a one-way sync. With `--up` only, it deletes xyOps objects missing from the local tree. With `--down` only, it deletes local XYPDF sources missing from xyOps, plus their external property files. The CLI rejects deletion when both directions or neither direction are enabled, including saved defaults and dry runs. Use `--up false` or `--down false` to disable an inherited direction. See [Delete mode](sync.md#delete-mode) before using it.
 
 ```sh
 xy sync ./ --up events,plugins --delete events --dry
 xy sync ./ --up events,plugins --delete events
+xy sync ./ --up false --down events,plugins --delete events,plugins --dry
+xy sync ./ --up false --down events,plugins --delete events,plugins
 ```
 
-**Objects with a `stock` or `marketplace` property are always ignored by deletion**, including during dry runs. They do not need local source files, and setup inclusion flags cannot override this protection.
+**Objects with a `stock` or `marketplace` property are ignored by deletion**, including during dry runs. Upward deletion checks the xyOps definition; downward deletion checks the local XYPDF. Setup inclusion flags cannot override this protection.
 
-**The scanned directories must contain a complete inventory of the other objects you intend to keep for every type selected for deletion.** Delete mode is not limited to previously synced objects. A missing file, incomplete export, or unavailable mount can cause unintended deletions of your own definitions. Verify that all source directories are available and inspect a dry run before removing `--dry`. Source warnings or scan errors stop the run before any updates begin. If an update or sync-tracking API operation fails, earlier successful updates remain in place, but the entire delete pass is skipped for that run.
+**The authoritative side must have a complete inventory of the objects you intend to keep for every type selected for deletion.** Delete mode is not limited to previously synced objects. A missing local file can delete a remote object during upsync; a new local file not yet created in xyOps can be deleted during downsync. Ensure the API Key can see the complete remote inventory, review a dry run, and coordinate separate up and down jobs before enabling automatic deletion. Warnings or errors before the delete phase skip that phase; earlier successful updates remain in place.
 
 **System Hook deletions**
 
@@ -265,7 +267,7 @@ xy sync ./ --up events,plugins \
 - `--error_email ADDRESS` sends warnings and errors by email through xyOps.
 - `--error_event EVENT_ID` runs an Event on warnings or errors.
 
-Completion commands run in a local shell in the first base directory. Successful up-only deletion triggers `up_cmd`; local System Hook deletion triggers an explicitly supplied `down_cmd`. Event notifications receive `input.data.errors` and `input.data.warnings`.
+Completion commands run in a local shell in the first base directory. Successful up-only deletion triggers `up_cmd`; down-only and System Hook deletions trigger `down_cmd` when it is configured. Event notifications receive `input.data.errors` and `input.data.warnings`.
 
 The configured API Key needs the appropriate resource permissions and `update_state` for sync tracking updates. Notification actions also need their usual permissions. Earlier successful changes are not rolled back if a later operation fails. Retry the sync after correcting an error; previously applied updates compare equal, and deletion remains disabled until the pre-delete phase completes without warnings or errors.
 

package/docs/sync.md

@@ -40,10 +40,12 @@ Sync has two directions. **Up** sends local definitions to xyOps. **Down** write
 
 **Sync applies changes immediately. There is no confirmation step.** Add `--dry` to preview a run before allowing it to change xyOps or your files.
 
-Sync updates *changes* to objects that already exist on both sides. It does not create new xyOps objects, generate local files for newly created objects (except during [setup](#set-up-your-first-sync-tree)), or remove local files when objects disappear from xyOps. Use resource creation commands or imports to create objects, and setup or exports to introduce their local files.
+Sync updates *changes* to objects that already exist on both sides. It does not create new xyOps objects or generate local files for newly created objects (except during [setup](#set-up-your-first-sync-tree)). Use resource creation commands or imports to create objects, and setup or exports to introduce their local files. One-way [delete mode](#delete-mode) can remove definitions missing from the authoritative side.
 
 For a Git-based deployment workflow, start with up-only sync. A fresh checkout is a good source for an explicit push, but its filesystem timestamps are not reliable evidence for two-way conflict decisions.
 
+For two-way deletion driven by accepted Git pushes and xyOps System Activity triggers, see the [event-driven two-way delete tutorial](two-way-delete-tutorial.md).
+
 ## Supported resources and requirements
 
 Install and connect xyCLI as described in [Getting started](../README.md#getting-started). The CLI requires Node.js 20.19.0 or later and xyOps 1.0.96 or later. The machine running sync needs network access to the xyOps API and access to the local directories you select.
@@ -70,7 +72,7 @@ Secret Vaults, Users, and Roles are not supported by sync. Individual workers, j
 
 ### Permissions
 
-Your API Key needs permission to read the definitions you scan and to edit each type you push. Delete mode additionally requires the corresponding delete privileges. Resource restrictions, such as Category and Group access, still apply.
+Your API Key needs permission to read the definitions you scan and to edit each type you push. Up-only delete mode additionally requires the corresponding delete privileges. Down-only deletion removes local files and does not call the remote delete APIs. Resource restrictions, such as Category and Group access, still apply.
 
 Sync also maintains remote-management tracking which requires the [update_state](https://docs.xyops.io/privileges/update_state) privilege. A pull or two-way run can update this tracking too. Notification email requires the [send_emails](https://docs.xyops.io/privileges/send_emails) privilege; an error Event requires the [run_jobs](https://docs.xyops.io/privileges/run_jobs) privilege, permission to use that Event's resources, and an enabled manual trigger.
 
@@ -153,7 +155,7 @@ Setup normally omits objects marked as stock or installed from the Marketplace.
 xy sync setup all --stock --marketplace --file_props script,params.script
 ```
 
-These switches are optional export choices, not requirements for delete mode. Objects with a `stock` or `marketplace` property are always excluded from sync deletion, even when they have no local file. Leave Marketplace Plugins managed by the Marketplace and its upgrade system; a standard sync tree can focus on definitions you maintain yourself.
+These switches are optional export choices, not requirements for delete mode. Up-only deletion excludes remote objects marked `stock` or `marketplace`. Down-only deletion excludes local sources carrying either property. Leave Marketplace Plugins managed by the Marketplace and its upgrade system; a standard sync tree can focus on definitions you maintain yourself.
 
 ### Rerun setup carefully
 
@@ -393,9 +395,9 @@ Relative paths resolve against the CLI's current working directory. Completion c
 | --- | --- | --- | --- |
 | `--up TYPES` | `sync.up` | Disabled | Sync upwards to xyOps from local sources for these types. |
 | `--down TYPES` | `sync.down` | Disabled | Down downwards to existing local sources from xyOps for these types. |
-| `--delete TYPES` | `sync.delete` | Disabled | Delete remote objects with no local source. Use only in an up-only workflow; see [Delete mode](#delete-mode). |
+| `--delete TYPES` | `sync.delete` | Disabled | Delete definitions missing from the sole enabled direction's authoritative side. Requires up-only or down-only sync; see [Delete mode](#delete-mode). |
 | `--syshook ACTION` | n/a | Disabled | Handle one supported definition deletion activity from STDIN as a local-only deletion; see [System Hook deletion](#system-hook-deletion). |
-| `--ignore_missing` | `sync.ignore_missing` | Off | Skip local sources whose type and ID are absent from xyOps, without a warning or failure. Leave their files untouched. |
+| `--ignore_missing` | `sync.ignore_missing` | Off | Skip local sources whose type and ID are absent from xyOps, without a warning or failure. Down-only deletion takes precedence for types selected by `--delete`. |
 | `--up_cmd COMMAND` | `sync.up_cmd` | None | Run a local shell command after at least one successful upsync. |
 | `--down_cmd COMMAND` | `sync.down_cmd` | None | Run a local shell command after at least one successful downsync, or an explicit command after a System Hook deletion. |
 | `--cmd_timeout SECONDS` | `sync.cmd_timeout` | `30` | Timeout for each completion command. |
@@ -453,13 +455,13 @@ For automatic two-way operation, use a persistent tree and run every minute. Bot
 
 ### Remove a definition during two-way sync
 
-Two-way sync does not propagate deletions. Definition deletions are usually infrequent, so coordinating them manually is generally practical. Keep `--delete false` in the scheduled command, and remove a definition from both sides deliberately:
+One command with both sync directions does not propagate deletions. Keep `--delete false` in a scheduled two-way command, and remove a definition from both sides deliberately:
 
 1. Delete the definition in the xyOps web interface first.
 2. Remove its local XYPDF JSON file and any neighboring external property files. If the tree is stored in Git, commit and push their removal so the dedicated sync checkout receives the deletion.
 3. Run sync again, or resume the schedule, after the local files are gone. Without `--ignore_missing`, pause the schedule during these steps if you want to avoid a failed pass between the two removals.
 
-If a sync runs after the xyOps deletion but before local cleanup, the leftover source normally produces a missing-object warning and stops the run before any definition changes. Add `--ignore_missing` to ordinary sync and any following `sync setup --new` command to skip that source and keep processing other definitions. This does not remove the local files or propagate the deletion to Git. Remove those files yourself to complete the deletion. Other scan warnings and errors still stop the run.
+If a sync runs after the xyOps deletion but before local cleanup, the leftover source normally produces a missing-object warning and stops the run before any definition changes. Add `--ignore_missing` to ordinary sync and any following `sync setup --new` command to skip that source and keep processing other definitions. This does not remove the local files or propagate the deletion to Git. Remove those files yourself to complete the deletion. Other scan warnings and errors still stop the run. For an event-driven workflow with one authoritative direction per run, see [Delete mode](#delete-mode).
 
 Do not remove the Git files first while the definition still exists in xyOps. A scheduled `sync setup --new` pass can export the still-existing definition back into the repository. See the [Two-Way Git Sync Tutorial](two-way-git-tutorial.md#delete-a-definition-from-both-sides) for the Git workflow.
 
@@ -523,9 +525,15 @@ Make sure only one sync instance talks to one xyOps installation.
 
 ## Delete mode
 
-Delete mode treats missing local definitions as a request to delete them **in xyOps**. Use it exclusively with an up-only source of truth. It is not a way to clean local files during downsync, and it does not provide two-way deletion propagation.
+Delete mode removes definitions missing from the authoritative side of a **one-way** sync. With `--up` only, it deletes xyOps definitions that have no local XYPDF source. With `--down` only, it deletes local XYPDF sources that have no matching visible xyOps definition, along with their external property files. Select the affected resource types with `--delete TYPES`. The CLI rejects deletion if both directions, or neither direction, are enabled, including directions inherited from saved configuration. A single two-way sync command cannot use delete mode.
+
+The chosen direction applies to every missing definition of the selected types. A newly added Git file that has not yet been imported into xyOps looks the same as a definition deleted in xyOps, so a down-only delete run removes that file. Likewise, an xyOps definition that has not yet been exported looks the same as one deleted from Git to an up-only delete run. Coordinate Git-triggered and xyOps-triggered jobs so they do not overlap or process pending changes out of order. A host-local PID lock cannot serialize jobs on different machines.
+
+The [event-driven two-way delete tutorial](two-way-delete-tutorial.md) shows separate authoritative triggers for Git pushes, xyOps updates and deletions, and xyOps creations.
 
-### Prepare a complete inventory
+### Up-only deletion
+
+#### Prepare a complete inventory
 
 The scanned directories must contain a source for **every other remote object of each type selected for deletion** that you intend to keep. Delete mode considers all eligible objects in the visible remote collection, not just objects previously synced or carrying a remote-management warning.
 
@@ -541,7 +549,7 @@ xy sync setup events plugins categories
 
 Verify that every object eligible for deletion that you intend to keep has a corresponding source, including workflows under the `events` selection. Stock and Marketplace objects may be omitted. Avoid filename collisions, omitted resources, missing mounts, and hidden source directories.
 
-### Preview a deliberate deletion
+#### Preview a deliberate deletion
 
 Remove the source file(s) for the Event you intend to delete, then preview from the complete inventory:
 
@@ -559,10 +567,25 @@ Deleting an Event does not automatically remove its dependencies. Remote API rul
 
 Deletion only begins after every update has completed and the sync-tracking state has been written without warnings or errors. If either phase fails, the entire delete pass is skipped for that run. Earlier successful updates remain in place, so correct the error and retry; definitions already updated will compare equal. Once deletion begins, successful earlier deletions are not rolled back if a later deletion fails.
 
-With `--delete buckets`, a remote Bucket file missing from a selected local Bucket's `files/` directory is deleted individually. Removing the Bucket XYPDF source deletes the whole Bucket, including all its data and files. A missing or invalid `data.json`, incomplete file inventory, or failed transfer prevents Bucket file deletion and the whole-object delete pass.
+With up-only `--delete buckets`, a remote Bucket file missing from a selected local Bucket's `files/` directory is deleted individually. Removing the Bucket XYPDF source deletes the whole Bucket, including all its data and files. A missing or invalid `data.json`, incomplete file inventory, or failed transfer prevents Bucket file deletion and the whole-object delete pass.
 
 An unavailable base directory stops the scan, but an existing empty directory can look like an empty inventory. Do not treat that guard as protection against an empty mount, accidental file removal, or missing exports of your own definitions.
 
+### Down-only deletion
+
+Run a down-only pass when xyOps should determine which local definitions remain. Specify the full local sync tree, and use `--up false` if saved configuration would otherwise enable upsync:
+
+```sh
+xy sync /srv/xyops-sync --up false --down events,plugins --delete events,plugins --dry
+xy sync /srv/xyops-sync --up false --down events,plugins --delete events,plugins --down_cmd ./commit-downloads.sh
+```
+
+Down-only deletion removes matching local XYPDF sources and their validated external property files. It matches by item type and exact ID, not filename. A missing local source is not created by ordinary downsync; run `xy sync setup TYPES --new` separately to export newly created xyOps definitions. Setup runs from the current directory, so run it from the sync tree's root.
+
+For Buckets, down-only `--delete buckets` also removes local uploaded files absent from an existing remote Bucket. If the entire Bucket is absent from xyOps, it removes the local Bucket XYPDF, `data.json`, and uploaded files, then removes the empty content directories. Unexpected content in a Bucket directory stops the whole-object local delete pass. Stock and Marketplace markers in a local XYPDF exclude that definition from deletion.
+
+The local delete pass starts only after the source scan, definition downloads, sync-state update, and Bucket content pass finish without warnings or errors. It checks every candidate before removing any whole-object files. A successful local deletion triggers `down_cmd`, including when there was no ordinary download. If a later file removal fails, earlier removals remain and the run exits nonzero; inspect the tree and retry.
+
 Keep deletion disabled in general-purpose cron, Git hooks, and CI until you have a deliberate policy for maintaining and checking the complete inventory. Disable saved deletion for other runs with `--delete false`.
 
 It is also highly recommended that you [keep daily backups of critical data](https://docs.xyops.io/hosting/daily-backups) before enabling sync, especially sync with delete.
@@ -585,7 +608,7 @@ xy sync ./ --down events,plugins --down_cmd "./commit-downloads.sh" --cmd_timeou
 ### When commands run
 
 - `up_cmd` runs if at least one object was successfully upsynced (this includes deletes).
-- `down_cmd` runs if at least one object was successfully downsynced. In `--syshook` mode, an explicitly supplied `down_cmd` runs after the matching local files are deleted.
+- `down_cmd` runs if at least one object was successfully downloaded or locally deleted by down-only sync. In `--syshook` mode, an explicitly supplied `down_cmd` runs after the matching local files are deleted.
 - During setup, an explicitly supplied `down_cmd` runs if at least one definition was written.
 - If both apply, `up_cmd` runs first, then `down_cmd`.
 - Neither runs for an identical/no-op run, a scan that stopped before changes, or a dry run.
@@ -978,13 +1001,13 @@ Repository concurrency controls these workflow runs. Coordinate all writers to t
 | The wrong directory is scanned | Positional paths take precedence, followed by `base_dirs`, then the current directory. Check your command and config; use absolute paths in automation. |
 | A config override seems to vanish | The user file replaces a system `sync` object as a whole. Environment settings take precedence over files. See [configuration](#configuration-and-option-reference). |
 | An object is missing from the local tree | Ordinary downsync does not discover it. Export that object or run setup in a separate staging directory. |
-| A source cannot find its remote object | Match its exact `type` and `data.id` to an existing visible object in this xyOps installation. Create/import missing objects separately. |
+| A source cannot find its remote object | Match its exact `type` and `data.id` to an existing visible object in this xyOps installation. Create/import missing objects separately, or use down-only delete mode if xyOps is authoritative and the local source should be removed. |
 | A duplicate-source warning stops sync | Keep one file per resource type and ID, even when the copies are identical. Remove duplicates and avoid overlapping base directories, then retry. |
 | One bad file stops unrelated updates | The scan validates all JSON sources before applying changes. Fix malformed JSON, multi-item XYPDF, unsupported types, missing objects, or unreadable property files. |
 | A script edit has no effect | Check the matching JSON stem, property suffix, filename extension, and property path. Hidden paths are skipped. |
 | Two-way sync overwrites an unexpected side | Compare the remote modification time with the newest JSON/property-file mtime. Fresh checkouts, clock skew, or touched files can make local sources appear newer. |
 | An Event or workflow does not execute | Sync saves definitions; it does not run them. Use `xy run EVENT_ID` separately. |
-| `down_cmd` does not run | Normal sync requires a successful download. Setup requires at least one written definition and an explicit `--down_cmd`. No-op and dry runs do not trigger it. |
+| `down_cmd` does not run | Normal sync requires a successful download or down-only deletion. Setup requires at least one written definition and an explicit `--down_cmd`. No-op and dry runs do not trigger it. |
 | A download commit launches another sync | Disable deployment Git hooks for commits made by `down_cmd`. The nested sync will otherwise be rejected by the built-in PID lock. |
 | Sync reports another PID is running | Another local sync owns the lock. Let it finish. If the PID is no longer alive, the next run recovers the stale file automatically. If the PID belongs to an unrelated recycled process, verify that no sync is active before removing the reported lock file. |
 | A scheduled run prints nothing | `--quiet` suppresses routine output. Warnings and errors still print to standard error. Check that the scheduler captures it. |
@@ -1002,7 +1025,7 @@ Before important deployments, review a dry run, retain recoverable versions of b
 
 Sync uses IDs rather than titles or filenames, and does not remap IDs for a different xyOps installation. Duplicate sources for the same type and ID generate warnings and stop the run before changes; keep one source per object and avoid overlapping base directories. Split inventories by ownership when useful, but remember that each run replaces the shared up-only remote-management tracking map rather than combining independent jobs' maps.
 
-New remote objects, objects removed remotely, filename changes, and dependency ordering need explicit maintenance. Deletion remains an up-only workflow with a complete inventory. Two-way sync remains experimental and resolves whole objects by modification time, without a merge or conflict prompt.
+New definitions still require explicit creation or setup export. Deletion requires separate one-way runs with a complete inventory on the authoritative side. Two-way sync remains experimental and resolves existing whole objects by modification time, without a merge or conflict prompt.
 
 - **Command reference:** [Sync](help.md#sync), [Sync setup](help.md#sync-setup), [Exports](help.md#export), [Imports](help.md#import), and [Run](help.md#run).
 - **Learn more about xyOps:** [xyOps Portable Data Format](https://docs.xyops.io/xypdf) and [xyOps API Keys](https://docs.xyops.io/api#api-keys).

package/docs/two-way-delete-tutorial.md

@@ -0,0 +1,259 @@
+# Two-Way Git Sync with Event-Driven Deletes
+
+This tutorial keeps Events, workflows, and Plugins in both xyOps and Git. Existing definitions can be edited on either side, and deletions can start on either side. New definitions are created in the xyOps UI and exported to Git. Every sync runs because Git accepted a push or xyOps recorded an activity. There are no cron jobs or recurring sync schedules.
+
+Use xyCLI version **v1.1.0+** (with down-sync delete support) and xyOps version **v1.1.3+** (with System Activity triggers). Both features must be available before you enable this workflow.
+
+> [!IMPORTANT]
+> **Two-way deletion requires authoritative triggers in both directions.** Run `--up --delete` only in response to an accepted Git change, and run `--down --delete` only in response to xyOps activity. Each invocation has exactly one authoritative side. A single command with both `--up` and `--down` cannot use `--delete`.
+
+| Authoritative action | Trigger | Command | Result |
+| --- | --- | --- | --- |
+| Git accepts a contributor push | Git `post-receive` hook or GitHub `push` webhook | `xy sync ... --up events,plugins --down false --delete events,plugins` | Git updates existing definitions and removes missing ones from xyOps. |
+| xyOps updates or deletes an Event or Plugin | **System Activity** Event | `xy sync ... --up false --down events,plugins --delete events,plugins` | xyOps updates existing files and removes missing XYPDF files and their owned neighbors. |
+| xyOps creates an Event or Plugin | Separate **System Activity** Event | `xy sync setup events plugins --new ...` | New definitions are exported, committed, and pushed to Git. |
+
+> [!CAUTION]
+> There is a potential race condition between creating an item in xyOps and exporting it to Git. If a Git-triggered up-delete runs before the new XYPDF file reaches the checkout, it can delete that newly created item from xyOps. The shared job queue prevents runs from overlapping, but it cannot guarantee which trigger arrives first. See [Ordering and recovery](#ordering-and-recovery).
+
+The examples in this tutorial include **Events** (which includes Workflows) and **Plugins**. To manage other resource types, add them to the commands and choose their corresponding activity types. 
+
+## Before you begin
+
+Use one persistent Git checkout on a machine running xySat. Target all three xyOps Events below to that machine, where the checkout, xyCLI configuration, and Git credentials are available. The xyOps conductor does not need a copy of the repository. Use one operating-system account for all three jobs.
+
+You will need:
+
+- A xyOps API Key that can see the **complete** Event and Plugin inventories, update and delete those types, and update global sync state. A restricted or partial inventory is unsafe for up-only deletion.
+- A dedicated repository and a persistent checkout, such as `/srv/xyops-automation`, with noninteractive Git pull and push access.
+- A Git author identity for commits generated by xyOps.
+- Shared xyOps job capacity and queue limits on all three Events.
+- A way to monitor failed xyOps jobs and Git webhook deliveries, then retry them after checking both sides.
+
+This is a full-inventory workflow. Do not point it at a partial export, empty mount, fresh clone missing files, or API Key with an incomplete view. Stock and Marketplace definitions are naturally excluded.
+
+## 1. Prepare the checkout
+
+Clone the repository on the sync worker, then configure the account that will run the jobs:
+
+```sh
+git clone git@github.com:YOUR_ORG/xyops-automation.git /srv/xyops-automation
+cd /srv/xyops-automation
+git config user.name "xyOps Sync"
+git config user.email "xyops-sync@example.com"
+xy config --base_url https://xyops.example.com --api_key YOUR_API_KEY
+xy dashboard
+```
+
+Keep the API Key and Git credentials outside the repository. Use `main` as the dedicated branch in the examples below, or replace it consistently with your branch name.
+
+Export a complete starter inventory from the repository root. `--file_props` keeps common Plugin and Event scripts in neighboring files:
+
+```sh
+xy sync setup events plugins --file_props script,params.script --dry
+xy sync setup events plugins --file_props script,params.script
+git status --short
+```
+
+Review the generated files, including scripts and potentially sensitive configuration. Confirm that every non-stock Event, workflow, and Plugin visible to the sync API Key is present. Then commit and push the initial tree:
+
+```sh
+git add --all
+git commit -m "Export xyOps automation"
+git push -u origin main
+```
+
+Create the automation Events described below only after this inventory exists. Export them before enabling the Git trigger, so an early up-only delete pass cannot mistake an automation Event for a Git deletion.
+
+## 2. Add a commit helper
+
+Save this script as `/usr/local/sbin/commit-xyops-sync` on the sync worker. Both xyOps-originated jobs will use it as their explicit `--down_cmd`, to run after local changes have been made:
+
+```sh
+#!/bin/sh
+set -eu
+
+cd /srv/xyops-automation
+
+# This checkout is dedicated to xyOps automation. Stage removals as well as
+# new and updated files, then avoid an empty commit if nothing changed in Git.
+git add --all
+if git diff --cached --quiet; then
+	exit 0
+fi
+
+# The Git trigger should ignore commits carrying this prefix. They came from
+# xyOps and must not cause a second authoritative up-delete run.
+git commit -m "[xyops-sync] Export xyOps changes"
+git push origin HEAD:main
+```
+
+Make it executable with `chmod 755 /usr/local/sbin/commit-xyops-sync`. This helper assumes the repository contains only the automation tree. If it contains unrelated work, narrow the staged paths and review the resulting commit before using it unattended.
+
+## 3. Add one sync script for the three jobs
+
+Save this as `/usr/local/sbin/xyops-git-sync` on the sync worker:
+
+```sh
+#!/bin/sh
+set -eu
+
+# Include the directories containing Node.js, xyCLI, and Git on this worker.
+PATH="/usr/local/bin:/usr/bin:/bin"
+export PATH
+
+REPO_DIR="/srv/xyops-automation"
+XY_BIN="/usr/local/bin/xy"
+COMMIT_CMD="/usr/local/sbin/commit-xyops-sync"
+SYNC_TYPES="events,plugins"
+MODE="${1:-}"
+
+cd "$REPO_DIR"
+
+# Work only from the dedicated branch and a clean, existing checkout. A
+# missing tree or leftover change must never be treated as a deletion.
+if [ "$(git symbolic-ref --quiet --short HEAD)" != main ]; then
+	echo "Sync stopped: checkout is not on main." >&2
+	exit 1
+fi
+if [ -n "$(git status --porcelain)" ]; then
+	echo "Sync stopped: checkout has uncommitted changes." >&2
+	exit 1
+fi
+if [ ! -d events ] || [ ! -d plugins ]; then
+	echo "Sync stopped: Event or Plugin inventory directory is missing." >&2
+	exit 1
+fi
+
+# Pull accepted Git changes before scanning. A failed fast-forward requires
+# review rather than a reset that could discard a xyOps-generated commit.
+git pull --quiet --ff-only origin main
+
+case "$MODE" in
+	up)
+		"$XY_BIN" sync "$REPO_DIR" \
+			--up "$SYNC_TYPES" --down false --delete "$SYNC_TYPES" \
+			--up_cmd false --down_cmd false
+		;;
+	
+	down)
+		"$XY_BIN" sync "$REPO_DIR" \
+			--up false --down "$SYNC_TYPES" --delete "$SYNC_TYPES" \
+			--down_cmd "$COMMIT_CMD" --cmd_timeout 120
+		;;
+	
+	create)
+		# Setup scans the current directory and adds only remote definitions
+		# whose type and ID are not already represented in the checkout.
+		"$XY_BIN" sync --setup "$SYNC_TYPES" --new \
+			--file_props script,params.script \
+			--down_cmd "$COMMIT_CMD" --cmd_timeout 120
+		;;
+	
+	*)
+		echo "Usage: $0 up|down|create" >&2
+		exit 2
+		;;
+esac
+```
+
+Make it executable with `chmod 755 /usr/local/sbin/xyops-git-sync`. Change the paths and `PATH` for your worker. The directory checks are a basic guard against a missing checkout. They do not prove that the inventory is complete, so inspect it before enabling deletion and after any Git or API failure.
+
+Set a suitable job timeout for Git network operations. All three Events will share a xyOps capacity pool so only one can use this checkout at a time.
+
+## 4. Configure the xyOps Activity Events
+
+Create three Shell Plugin Events in xyOps, initially disabled. Target only the sync worker and give each Event the indicated trigger and script. The [System Activity trigger](https://docs.xyops.io/triggers#activity) lets you select multiple activity types in the UI; it launches a job when any of them occur. Note that the xyOps scheduler must be enabled for Activity triggers to run.
+
+| Event | Trigger | Select these activities | Shell script body |
+| --- | --- | --- | --- |
+| **Sync deletions and updates from xyOps** | System Activity | `event_update`, `plugin_update`, `event_delete`, `plugin_delete` | `/usr/local/sbin/xyops-git-sync down` |
+| **Export creations from xyOps** | System Activity | `event_create`, `plugin_create` | `/usr/local/sbin/xyops-git-sync create` |
+| **Apply accepted Git pushes** | Manual | No activity selection | `/usr/local/sbin/xyops-git-sync up` |
+
+The update activities make xyOps UI edits flow back to Git too. The separate creation Event runs `sync setup --new`, because ordinary downsync updates existing local sources but does not create files for new xyOps definitions. The setup command's `--down_cmd` runs only when it writes files; the down-delete command's `--down_cmd` runs only after local changes. Neither creates an empty Git commit on a no-op run.
+
+The Git Event has an enabled **Manual** trigger so a Git hook or verified webhook receiver can launch it with `xy run` or the [`run_event` API](https://docs.xyops.io/api#run_event). It has no schedule. The Git push is still the authoritative reason for that run.
+
+On **each** of these three Events, set a **[Max Jobs Limit](https://docs.xyops.io/#Docs/limits/max-jobs-limit)** of `1` with the same **[Shared Capacity Key](https://docs.xyops.io/#Docs/limits/shared-capacity-key)**, such as `xyops_git_sync`. Also set a **[Max Queue Limit](https://docs.xyops.io/#Docs/limits/max-queue-limit)** with the same positive amount on each Event, sized for the bursts you expect. This creates one shared, FIFO job queue for all sync operations. Without queue capacity, a trigger arriving while another sync job runs may be aborted instead of waiting. See xyOps's [shared capacity and queue limits](https://docs.xyops.io/limits#shared-capacity-key). Use the same priority on all three Events unless you deliberately want to change queue order, and monitor jobs that fail or exhaust the queue.
+
+Before enabling any of the three Events, export their new definitions from the checkout root:
+
+```sh
+cd /srv/xyops-automation
+/usr/local/sbin/xyops-git-sync create
+```
+
+The `create` mode uses `sync setup --new` and its `--down_cmd` to commit and push those files. Review that commit and confirm the tree is complete. Then enable the three Events and test with disposable definitions before allowing normal Git pushes to trigger up-delete.
+
+## 5. Trigger upsync from accepted Git pushes
+
+Choose the Git trigger that matches your repository hosting. Both options launch the **same** Git Event after a push has been accepted. Do not enable both for one repository.
+
+### Self-hosted Git: a `post-receive` hook
+
+On a self-hosted **bare remote repository**, save the following as `hooks/post-receive` and make it executable. This hook runs on the Git server after refs have been updated, not in each contributor's clone or the sync worker's checkout. The Git server needs xyCLI credentials that permit launching the Git Event, but it does not need the sync checkout.
+
+```sh
+#!/bin/sh
+set -eu
+
+deploy=false
+while read -r old_oid new_oid ref; do
+	[ "$ref" = refs/heads/main ] || continue
+	git cat-file -e "$new_oid^{commit}" 2>/dev/null || continue
+	
+	# A commit generated by the down/create helper is already from xyOps.
+	# Do not turn its push into another authoritative up-delete run.
+	case "$(git log -1 --format=%s "$new_oid")" in
+		'[xyops-sync]'*) continue ;;
+	esac
+	deploy=true
+done
+
+[ "$deploy" = true ] || exit 0
+/usr/local/bin/xy run SYNC_UP_EVENT_ID
+```
+
+Replace `SYNC_UP_EVENT_ID` with the xyOps Git Event's exact ID. Git's [`post-receive` hook](https://git-scm.com/docs/githooks#post-receive) runs after a push succeeds; a later hook or job failure cannot undo that push. Monitor the launched job and retry it after fixing any problem.
+
+### GitHub: a `push` webhook
+
+If GitHub hosts the repository, use its **push** webhook to notify your existing webhook receiver. In GitHub, open **Settings > Webhooks > Add webhook**, set its payload URL to that receiver, choose `application/json`, set a secret, and select only the **Pushes** event. The receiver should:
+
+1. Verify `X-Hub-Signature-256` against the raw request body, and accept only the intended repository and `refs/heads/main`.
+2. Ignore GitHub's initial `ping`, deleted branches, and commits whose head message starts with `[xyops-sync]`.
+3. Deduplicate by `X-GitHub-Delivery`, then launch `SYNC_UP_EVENT_ID` through xyOps's `run_event` API using an API Key with `run_jobs` access.
+4. Acknowledge only after recording the delivery for processing, and monitor the resulting xyOps job. Retry a failed job or redeliver a missed webhook after reviewing the Git and xyOps state.
+
+The API request made by the verified receiver is a JSON `POST` to `/api/app/run_event/v1` with an `X-API-Key` header and body `{"id":"SYNC_UP_EVENT_ID"}`. The Event runs on the sync worker, so the receiver does not need the checkout. Do not put an xyOps API Key in the GitHub payload URL. A direct xyOps Magic Link can start an Event, but it does not verify GitHub's webhook signature; use a receiver that does that verification for this workflow. See GitHub's [webhook setup](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks), [signature validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), and [delivery guidance](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks).
+
+## 6. Test each direction before enabling automatic deletion
+
+Run these tests with disposable Events and Plugins, not production definitions:
+
+1. Create an Event or Plugin in xyOps. Confirm that the **create** Activity Event exports its XYPDF, commits it, and pushes it to Git.
+2. Edit that definition in the xyOps UI. Confirm that the **down** Activity Event downloads the change and commits it.
+3. Delete it in xyOps. Confirm that the **down** Event removes the XYPDF and owned neighbor files and pushes the deletion.
+4. Edit an existing definition in Git and push. Confirm that the accepted-push trigger runs **up** and updates xyOps.
+5. Delete a different existing definition in Git and push. Confirm that **up** deletes only that definition in xyOps.
+
+Before the first live delete, preview each direction against the complete checkout and inspect every proposed deletion:
+
+```sh
+cd /srv/xyops-automation
+xy sync . --up events,plugins --down false --delete events,plugins --dry
+xy sync . --up false --down events,plugins --delete events,plugins --dry
+```
+
+Remember that a dry run previews the inventory **at that moment**. It cannot establish what a later Git push or xyOps activity means. Keep recoverable Git history and xyOps backups.
+
+## Ordering and recovery
+
+Authoritative triggers tell each pass which side should win. They do not make a full-inventory sweep transactional or remove all races. For example, an Event newly created in xyOps but not yet exported looks missing to an up-delete run; a new Git XYPDF that has not been created in xyOps looks missing to a down-delete run. This tutorial permits **creation only in xyOps**, so contributors should edit or delete existing XYPDF sources, not add new IDs in Git.
+
+Keep all three jobs on the same worker and checkout, serialize the entire Git plus xyCLI sequence with their shared capacity key, and process pending xyOps creations before allowing a Git up-delete pass to treat the inventory as complete. The queue prevents overlap, but it cannot guarantee that independently delivered Git and xyOps triggers arrive in causal order. If changes on both sides occur together, pause automatic deletion, inspect the Git diff and both inventories, resolve the intended order, and rerun the appropriate job. Do not assume a successful webhook acknowledgment means the xyOps job succeeded.
+
+If a job or push fails, leave the checkout and xyOps as they are until you have inspected them. A failed Git push can leave a local commit that needs to be pushed or reconciled before another `git pull --ff-only`. A failed Activity launch or webhook delivery needs a deliberate retry; there is no cron pass to pick it up later. GitHub [does not automatically redeliver failed webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries).
+
+For all sync options and deletion safeguards, see the [Filesystem Sync Guide](sync.md#delete-mode). For a scheduled, modification-time-based workflow without automatic two-way deletion, see the [Two-Way Git Sync Tutorial](two-way-git-tutorial.md).

package/docs/two-way-git-tutorial.md

@@ -108,7 +108,9 @@ This considers both directions for every local Event and workflow source:
 - A newer xyOps definition is downloaded to its existing local file.
 - Identical definitions are left alone.
 
-The `--delete false` switch is intentional. Two-way sync does not propagate deletions. Keep deletion disabled in the scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item.
+The `--delete false` switch is intentional. A single command with both directions does not propagate deletions. Keep deletion disabled in this scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item. Separate one-way [up and down delete modes](sync.md#delete-mode) are available for workflows that can coordinate their triggers and inventories.
+
+If you want deletion in both directions without a recurring schedule, use the separate [event-driven two-way delete tutorial](two-way-delete-tutorial.md).
 
 Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
 

package/lib/sync-buckets.js

@@ -87,6 +87,25 @@ module.exports = {
 		return { paths, data, data_stat: stat, files };
 	},
 	
+	getSyncBucketLocalDeletePlan(item) {
+		// A deleted Bucket owns its sibling data.json and uploaded files.  Only
+		// remove that directory when it has the exact structure produced by
+		// setup; an unexpected entry could belong to someone else.
+		var local = this.readSyncBucketLocal(item);
+		var dir_stat = fs.lstatSync(local.paths.dir);
+		if (!dir_stat.isDirectory() || dir_stat.isSymbolicLink()) {
+			throw new Error("Invalid bucket content directory: " + local.paths.dir);
+		}
+		var entries = fs.readdirSync(local.paths.dir).sort();
+		if (entries.length !== 2 || entries[0] !== 'data.json' || entries[1] !== 'files') {
+			throw new Error("Unexpected file in bucket content directory: " + local.paths.dir);
+		}
+		return {
+			files: [...local.files.values()].map( entry => entry.path ).concat(local.paths.data),
+			dirs: [local.paths.files, local.paths.dir]
+		};
+	},
+	
 	stampSyncBucketFile(path, epoch) {
 		// Keep the access time intact. Server times are Unix seconds; Node accepts
 		// the same unit for utimes(), including fractional seconds if provided.
@@ -187,6 +206,7 @@ module.exports = {
 		var down = sconfig.down && sconfig.down.includes('buckets');
 		var delete_files = sconfig.delete && sconfig.delete.includes('buckets');
 		var deletes = [];
+		var local_deletes = [];
 		
 		for (const entry of prepared) {
 			var id = entry.item.data.id;
@@ -233,6 +253,7 @@ module.exports = {
 					var target = manifest.get(name);
 					if (!target) {
 						if (up) uploads.push({ name, source });
+						else if (delete_files) local_deletes.push({ id, title, name, path: source.path });
 						continue;
 					}
 					var local_time = source.stat.mtimeMs / 1000;
@@ -294,7 +315,7 @@ module.exports = {
 		
 		// Deletions are the final content phase. Any earlier warning or error
 		// suppresses all bucket file deletes, just like whole-object deletion.
-		if (deletes.length && (this.errors.length || this.warnings.length)) {
+		if ((deletes.length || local_deletes.length) && (this.errors.length || this.warnings.length)) {
 			this.logSyncWarning("Bucket file delete pass skipped because sync encountered warnings or errors.");
 			return;
 		}
@@ -311,5 +332,18 @@ module.exports = {
 				return;
 			}
 		}
+		for (const entry of local_deletes) {
+			this.printSyncBucketHeading('🗑️', this.dry ? 'Would delete local bucket file' : 'Deleting local bucket file', entry.title, entry.id, true);
+			println( "    " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(entry.name) );
+			if (this.dry) continue;
+			try {
+				fs.unlinkSync(entry.path);
+				this.downSynced = true;
+			}
+			catch (err) {
+				this.logSyncError("Local bucket file deletion failed: " + err);
+				return;
+			}
+		}
 	}
 };

package/lib/sync.js

@@ -76,10 +76,10 @@ module.exports = {
 		if (sconfig.delete && !Tools.includesAll(supported_lists, sconfig.delete)) this.die("Invalid sync.delete list: " + sconfig.delete.join(', '));
 		if (sconfig.delete && !sconfig.delete.length) sconfig.delete = false;
 		
-		// Deletion requires up-only sync, including directions inherited from config.
-		// Validate before scanning or applying any changes, even for a dry run.
-		if (sconfig.delete && (!sconfig.up || sconfig.down)) {
-			this.die("Delete mode requires up-only sync. Enable --up and disable --down.");
+		// Deletion follows the sole enabled direction.  Validate settings inherited
+		// from config as well as command-line args before scanning or writing.
+		if (sconfig.delete && (!!sconfig.up === !!sconfig.down)) {
+			this.die("Delete mode requires exactly one sync direction: --up or --down.");
 		}
 		
 		// Bucket content needs the replacement API and data timestamps introduced
@@ -142,6 +142,7 @@ module.exports = {
 		
 		// load all xypdf files
 		var items = [];
+		var local_delete_items = [];
 		var seen_sources = new Map();
 		
 		files.filter( file => !!file.path.match(/\.json$/i) && !this.isSyncBucketExtraFile(file.path, bucket_extra_dirs) ).forEach( file => {
@@ -286,13 +287,25 @@ module.exports = {
 				// include neighbor metadata for downsync
 				if (!item.neighbors) item.neighbors = {};
 				item.neighbors[ prop_path ] = neighbor.path;
+				if (!item.delete_neighbors) item.delete_neighbors = [];
+				item.delete_neighbors.push(neighbor.path);
 			} ); // foreach neighbor
 			
 			// do not include item if neighbor loading or validation failed
 			if (neighbor_error) return;
 			
+			item.list = type_def.list;
+			item.file = file.path;
 			var xy_item = Tools.findObject(list, { id: item.data.id });
 			if (!xy_item) {
+				// In a down-only delete run, xyOps owns this definition type.
+				// Queue its local files for the final destructive pass, after every
+				// source and neighbor has passed the normal scan validation.
+				if (sconfig.delete && sconfig.down && sconfig.delete.includes(item.list)) {
+					local_delete_items.push(item);
+					return;
+				}
+				
 				// An opted-in Git sync can briefly retain a source after its xyOps
 				// definition is deleted.  Skip only that source and keep scanning.
 				if (ignore_missing) {
@@ -307,12 +320,6 @@ module.exports = {
 			// include effective mtime in item for two-way sync
 			item.mtime = file.mtime;
 			
-			// include list name for convenience below
-			item.list = type_def.list;
-			
-			// include file for downsync
-			item.file = file.path;
-			
 			// add to sync list
 			items.push(item);
 		} ); // foreach json file
@@ -413,7 +420,12 @@ module.exports = {
 		// now handle deletes
 		if (!sconfig.delete) return await this.completeSync();
 		
-		// (deletes always happen upward, i.e. in xyops)
+		if (sconfig.down) {
+			this.deleteSyncLocalItems(local_delete_items);
+			return await this.completeSync();
+		}
+		
+		// Up-only deletion removes remote definitions absent from the local tree.
 		var list_data_types = [];
 		for (var id in this.config.ui.data_types) {
 			var type_def = this.config.ui.data_types[id];
@@ -450,6 +462,95 @@ module.exports = {
 		await this.completeSync();
 	},
 	
+	deleteSyncLocalItems(items) {
+		// Validate every selected local deletion before removing any files.  The
+		// normal source scan has already checked XYPDF identity and neighboring
+		// property paths; recheck the source and file types in case a checkout or
+		// another process changed the tree while this sync was running.
+		var plans = [];
+		for (const item of items) {
+			// Match the protection used by upward deletion for bundled or
+			// Marketplace definitions.  A local source may retain these markers
+			// even after its remote record has disappeared.
+			if (Object.hasOwn(item.data, 'stock') || Object.hasOwn(item.data, 'marketplace')) continue;
+			
+			var bucket_plan = null;
+			try {
+				if (item.type === 'bucket') bucket_plan = this.getSyncBucketLocalDeletePlan(item);
+			}
+			catch (err) {
+				this.logSyncError("Local delete preflight failed: " + err.message);
+				return;
+			}
+			var targets = [...new Set(item.delete_neighbors || []), ...(bucket_plan ? bucket_plan.files : []), item.file];
+			var dirs = bucket_plan ? bucket_plan.dirs : [];
+			try {
+				for (const file of targets) {
+					var stat = fs.lstatSync(file);
+					if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Local deletion target is not a regular file: " + file);
+				}
+				for (const dir of dirs) {
+					var stat = fs.lstatSync(dir);
+					if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Local deletion target is not a regular directory: " + dir);
+				}
+				var source = Tools.parseJSON(fs.readFileSync(item.file, 'utf8'));
+				var source_item = source && Array.isArray(source.items) && (source.items.length === 1) ? source.items[0] : null;
+				if (!source || (source.type !== 'xypdf') || (source.version !== '1.0') || !source_item ||
+					(source_item.type !== item.type) || !source_item.data || (source_item.data.id !== item.data.id)) {
+					throw new Error("Local XYPDF source changed during sync: " + item.file);
+				}
+			}
+			catch (err) {
+				this.logSyncError("Local delete preflight failed: " + err.message);
+				return;
+			}
+			plans.push({ item, targets, dirs });
+		}
+		
+		for (const plan of plans) {
+			println( "\n " + cli.emoji('🗑️') + ' ' + red.bold(this.dry ? "Would delete local " : "Deleting local ") +
+				red.bold(plan.item.type) + ": " + red.bold(plan.item.data.title || plan.item.data.id) +
+				gray(" (" + plan.item.data.id + ")") );
+			// Keep the XYPDF JSON source last so a partial filesystem failure
+			// leaves the identity available for a later retry.
+			for (const file of plan.targets.slice(0, -1)) {
+				println("    " + file);
+				if (this.dry) continue;
+				try {
+					fs.unlinkSync(file);
+					this.downSynced = true;
+				}
+				catch (err) {
+					this.logSyncError("Failed to delete local file: " + file + ": " + err.message);
+					return;
+				}
+			}
+			for (const dir of plan.dirs) {
+				println("    " + dir + Path.sep);
+				if (this.dry) continue;
+				try {
+					fs.rmdirSync(dir);
+					this.downSynced = true;
+				}
+				catch (err) {
+					this.logSyncError("Failed to delete local directory: " + dir + ": " + err.message);
+					return;
+				}
+			}
+			var source_file = plan.targets[plan.targets.length - 1];
+			println("    " + source_file);
+			if (this.dry) continue;
+			try {
+				fs.unlinkSync(source_file);
+				this.downSynced = true;
+			}
+			catch (err) {
+				this.logSyncError("Failed to delete local file: " + source_file + ": " + err.message);
+				return;
+			}
+		}
+	},
+	
 	getSyncLockFile() {
 		// Allow a fixed path for service installations.  Otherwise, serialize all
 		// local syncs targeting the exact same configured xyOps base URL.  Local

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.9",
+	"version": "1.1.0",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",

package/test/README.md

@@ -66,10 +66,10 @@ node --test test/config.test.js test/sync-buckets-unit.test.js test/sync-unit.te
 | `secrets` | Vault metadata, assignments, redacted previews, full field replacement, confirmed decryption, deletion, validation, help |
 | `servers` | Active and recently offline lists, local filters, installer generation, historical search, live and historical Server details, charts, processes, connections, pagination, validation, help |
 | `system` | Admin dashboard, conductors, connected users, export, maintenance, optimization, rate resets, diagnostics, broadcasts, help |
-| `sync` | Setup export, isolated filesystem discovery, external property files, dry-run, upsync, downsync, composite global-state governance, no-op detection, and guarded delete mode |
-| `sync-buckets` | Disposable Bucket setup, JSON replacement, file upload and download, and timestamp alignment on xyOps 1.1.2 or later |
+| `sync` | Setup export, isolated filesystem discovery, external property files, dry-run, upsync, downsync, composite global-state governance, no-op detection, up-only deletion, and down-only Event and Plugin file deletion |
+| `sync-buckets` | Disposable Bucket setup, JSON replacement, file upload and download, timestamp alignment, and down-only local file and whole-Bucket deletion on xyOps 1.1.2 or later |
 | `sync-buckets-unit` | Offline Bucket version gating, content setup, upload and download, timestamp alignment, and pre-delete safety |
-| `sync-unit` | Offline setup extension fallbacks, new-only exports and setup completion commands, PID locking and stale recovery, up-only deletion guards, pre-delete failure blocking, stock/Marketplace deletion protection, inherited settings and CLI overrides, warning/error exit status, duplicates, quiet/dry runs, completion failures, and notification delivery after warnings or errors |
+| `sync-unit` | Offline setup extension fallbacks, new-only exports and setup completion commands, PID locking and stale recovery, one-way deletion guards, pre-delete failure blocking, stock/Marketplace deletion protection, inherited settings and CLI overrides, warning/error exit status, duplicates, quiet/dry runs, completion failures, and notification delivery after warnings or errors |
 | `tags` | CRUD, metadata search, sparse future-proof updates, JSON input, validation, pagination, help |
 | `tickets` | Search, CRUD, number resolution, comments, attachment uploads/downloads, Events, related Job lookup, sparse updates, validation, help |
 | `toast` | Warning-box word wrapping and terminal-width limits |

package/test/sync-buckets-unit.test.js

@@ -127,6 +127,37 @@ test('downsync replaces changed files and preserves the server timestamp', async
 	assert.equal(fs.statSync(env.paths.data).mtimeMs / 1000, 150);
 });
 
+test('down-only bucket deletion removes local files absent from the remote manifest', async t => {
+	const keep = { filename: 'keep.txt', path: 'files/bucket/bucket_unit/key/keep.txt', size: 4, date: 80 };
+	const env = fixture(t, { localData: { keep: true }, remoteData: { keep: true }, remoteFiles: [keep] });
+	const keep_path = Path.join(env.paths.files, 'keep.txt');
+	const stale_path = Path.join(env.paths.files, 'stale.txt');
+	fs.writeFileSync(keep_path, 'keep');
+	fs.utimesSync(keep_path, 80, 80);
+	fs.writeFileSync(stale_path, 'stale');
+	
+	await env.app.syncBucketContents([env.item], { down: ['buckets'], delete: ['buckets'] });
+	assert.equal(env.app.errors.length, 0);
+	assert.equal(fs.existsSync(keep_path), true);
+	assert.equal(fs.existsSync(stale_path), false);
+	assert.equal(env.app.downSynced, true);
+	assert.deepEqual(env.calls, []);
+});
+
+test('down-only bucket deletion previews files and skips them after a failed download', async t => {
+	const remote_file = { filename: 'remote.txt', path: 'files/bucket/bucket_unit/key/remote.txt', size: 6, date: 80 };
+	for (const dry of [true, false]) {
+		const env = fixture(t, { localData: { keep: true }, remoteData: { keep: true },
+			remoteFiles: [remote_file], dry });
+		const stale_path = Path.join(env.paths.files, 'stale.txt');
+		fs.writeFileSync(stale_path, 'stale');
+		await env.app.syncBucketContents([env.item], { down: ['buckets'], delete: ['buckets'] });
+		assert.equal(fs.existsSync(stale_path), true);
+		if (dry) assert.equal(env.app.errors.length, 0);
+		else assert.match(env.app.errors[0], /Missing remote bytes/);
+	}
+});
+
 test('two-way sync chooses the newer data and file copies independently', async t => {
 	const old = { filename: 'remote.txt', path: 'files/bucket/bucket_unit/key/remote.txt', size: 6, date: 140 };
 	const env = fixture(t, {

package/test/sync-buckets.test.js

@@ -115,6 +115,42 @@ test('bucket filesystem sync', async t => {
 			assert.equal(Math.floor(fs.statSync(file).mtimeMs / 1000), remoteFile.date);
 			assert.equal(Math.floor(fs.statSync(dataFile).mtimeMs / 1000), bucket.meta.mod);
 		});
+		
+		await check('down-only delete removes a local Bucket file absent from xyOps', async () => {
+			const content = Path.join(activeRoot, 'buckets', slug);
+			const extra = Path.join(content, 'files', 'LocalOnly.txt');
+			fs.writeFileSync(extra, 'only in the local sync tree');
+			const before = await call('getBucket', { id });
+			
+			const preview = xy(['sync', activeRoot, '--up', 'false', '--down', 'buckets', '--delete', 'buckets', '--dry']);
+			assert.match(preview, /Would delete local bucket file/);
+			assert.ok(fs.existsSync(extra), 'Dry run preserves the local file');
+			
+			const output = xy(['sync', activeRoot, '--up', 'false', '--down', 'buckets', '--delete', 'buckets']);
+			assert.match(output, /Deleting local bucket file/);
+			assert.ok(!fs.existsSync(extra), 'Missing remote file was removed locally');
+			assert.ok(fs.existsSync(Path.join(content, 'files', 'seed.json')), 'Existing remote file remains');
+			assert.deepEqual((await call('getBucket', { id })).files, before.files, 'Remote Bucket files are unchanged');
+		});
+		
+		await check('down-only delete removes a deleted Bucket and its local content', async () => {
+			const source = Path.join(activeRoot, 'buckets', slug + '.json');
+			const content = Path.join(activeRoot, 'buckets', slug);
+			await call('deleteBucket', { id });
+			created = false;
+			assert.ok(fs.existsSync(source), 'Local source remains before down-delete');
+			assert.ok(fs.existsSync(content), 'Local content remains before down-delete');
+			
+			const preview = xy(['sync', activeRoot, '--up', 'false', '--down', 'buckets', '--delete', 'buckets', '--dry']);
+			assert.match(preview, /Would delete local bucket/);
+			assert.ok(fs.existsSync(source), 'Dry run preserves the Bucket source');
+			assert.ok(fs.existsSync(content), 'Dry run preserves Bucket content');
+			
+			const output = xy(['sync', activeRoot, '--up', 'false', '--down', 'buckets', '--delete', 'buckets']);
+			assert.match(output, /Deleting local bucket/);
+			assert.ok(!fs.existsSync(source), 'Deleted Bucket source was removed');
+			assert.ok(!fs.existsSync(content), 'Deleted Bucket content was removed');
+		});
 	}
 	finally {
 		// Ordinary sync writes a shared management map. Restore it exactly, then

package/test/sync-unit.test.js

@@ -15,26 +15,30 @@ const script = `
 	const options = JSON.parse(process.argv[1]);
 	cli.args.quiet = options.quiet !== false;
 	const sync = require('./lib/sync.js');
+	const bucketSync = require('./lib/sync-buckets.js');
 	if (options.setupCwd) process.chdir(options.setupCwd);
 	const calls = [];
 	const requests = [];
 	const apiOptions = [];
 	const app = {
 		...sync,
+		...bucketSync,
 		args: options.args,
 		config: {
 			base_url: 'https://fixture.invalid',
 			sync: options.config || {},
 			ui: {
-				list_list: ['categories', 'events', 'plugins'].map(id => ({ id })),
-				data_types: { category: { list: 'categories' }, event: { list: 'events' }, plugin: { list: 'plugins' } }
+				list_list: (options.includeBuckets ? ['buckets', 'categories', 'events', 'plugins'] : ['categories', 'events', 'plugins']).map(id => ({ id })),
+				data_types: { bucket: { list: 'buckets' }, category: { list: 'categories' }, event: { list: 'events' }, plugin: { list: 'plugins' } }
 			}
 		},
-		state: {},
+		state: options.state || {},
+		buckets: options.buckets || [],
 		categories: options.categories || [],
 		events: options.events || [],
 		plugins: options.plugins || [],
 		version: 'test',
+		xyopsVersion: '1.1.2',
 		dry: !!options.args.dry,
 		color() { return cli.chalk.white; },
 		markdown(text) { return text; },
@@ -95,6 +99,15 @@ function runSync(t, options) {
 				items: [{ type: source.type, data: source.data }]
 			});
 			fs.writeFileSync(file, contents);
+			if (source.bucketFiles) {
+				var bucket_dir = file.replace(/\.json$/i, '');
+				fs.mkdirSync(Path.join(bucket_dir, 'files'), { recursive: true });
+				fs.writeFileSync(Path.join(bucket_dir, 'data.json'), JSON.stringify(source.bucketData || {}));
+				for (const [name, contents] of Object.entries(source.bucketFiles)) {
+					fs.writeFileSync(Path.join(bucket_dir, 'files', name), contents);
+				}
+				if (source.bucketExtra) fs.writeFileSync(Path.join(bucket_dir, source.bucketExtra), 'keep');
+			}
 		});
 	}
 	if (options.missingDir) args.other = [Path.join(dir, 'missing')];
@@ -189,16 +202,16 @@ test('sync update guard rejects malformed confirmation values', async () => {
 	);
 });
 
-test('sync rejects deletion with down-only, two-way, or mixed directions before writes', t => {
+test('sync rejects deletion without exactly one direction before writes', t => {
 	for (const args of [
-		{ down: 'categories', delete: 'categories' },
 		{ up: 'categories', down: 'categories', delete: 'categories', dry: true },
 		{ up: 'categories', down: 'events', delete: 'categories' },
-		{ up: [], delete: 'categories' }
+		{ up: [], delete: 'categories' },
+		{ down: [], delete: 'categories' }
 	]) {
 		const result = runSync(t, { args });
 		assert.equal(result.status, 1);
-		assert.match(result.stderr, /Delete mode requires up-only sync/);
+		assert.match(result.stderr, /Delete mode requires exactly one sync direction/);
 		assert.deepEqual(result.report.calls, []);
 	}
 });
@@ -218,6 +231,101 @@ test('sync validates inherited deletion and direction settings after CLI overrid
 	assert.equal(emptyDown.status, 0);
 });
 
+test('down-only delete removes one missing local source and its neighbors', t => {
+	const result = runSync(t, {
+		categories: [{ id: 'keep', title: 'Keep', notes: 'Same' }],
+		events: [{ id: 'missing', title: 'Same ID on another type' }],
+		existingSources: [
+			{ path: 'categories/Stale.json', type: 'category', data: { id: 'missing', title: 'Stale', notes: '(External)' } },
+			{ path: 'categories/Stale-notes.txt', contents: 'Old note\n' },
+			{ path: 'categories/Keep.json', type: 'category', data: { id: 'keep', title: 'Keep', notes: 'Same' } },
+			{ path: 'events/Other.json', type: 'event', data: { id: 'missing', title: 'Same ID on another type' } }
+		],
+		args: { down: 'categories', delete: 'categories', down_cmd: getSetupMarkerCommand('completed.txt') }
+	});
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Stale.json')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Stale-notes.txt')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Keep.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events/Other.json')), true);
+	assert.equal(fs.readFileSync(Path.join(result.dir, 'completed.txt'), 'utf8'), fs.realpathSync(result.dir));
+	assert.deepEqual(result.report.requests.filter(req => req.method.startsWith('delete_')), []);
+});
+
+test('down-only delete previews local files without changing them or running down_cmd', t => {
+	const result = runSync(t, {
+		quiet: false,
+		existingSources: [
+			{ path: 'categories/Stale.json', type: 'category', data: { id: 'missing', title: 'Stale' } }
+		],
+		args: { down: 'categories', delete: 'categories', dry: true, down_cmd: getSetupMarkerCommand('completed.txt') }
+	});
+	assert.equal(result.status, 0, result.stderr);
+	assert.match(result.stdout, /Would delete local/);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Stale.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'completed.txt')), false);
+});
+
+test('down-only delete removes an orphan Bucket and all its local content', t => {
+	const result = runSync(t, {
+		includeBuckets: true,
+		existingSources: [
+			{ path: 'buckets/Stale.json', type: 'bucket', data: { id: 'missing', title: 'Stale' },
+				bucketData: { old: true }, bucketFiles: { 'old.txt': 'contents' } }
+		],
+		args: { down: 'buckets', delete: 'buckets' }
+	});
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'buckets/Stale.json')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'buckets/Stale')), false);
+});
+
+test('down-only delete preflights all Bucket content before removing any source', t => {
+	const result = runSync(t, {
+		includeBuckets: true,
+		existingSources: [
+			{ path: 'buckets/First.json', type: 'bucket', data: { id: 'first', title: 'First' }, bucketFiles: {} },
+			{ path: 'buckets/Second.json', type: 'bucket', data: { id: 'second', title: 'Second' },
+				bucketFiles: {}, bucketExtra: 'untracked.txt' }
+		],
+		args: { down: 'buckets', delete: 'buckets' }
+	});
+	assert.equal(result.status, 1);
+	assert.match(result.report.errors[0], /Local delete preflight failed/);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'buckets/First.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'buckets/First')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'buckets/Second.json')), true);
+});
+
+test('down-only delete protects local stock and Marketplace definitions', t => {
+	const result = runSync(t, {
+		existingSources: [
+			{ path: 'categories/Stock.json', type: 'category', data: { id: 'stock', title: 'Stock', stock: false } },
+			{ path: 'categories/Marketplace.json', type: 'category', data: { id: 'marketplace', title: 'Marketplace', marketplace: null } },
+			{ path: 'categories/Custom.json', type: 'category', data: { id: 'custom', title: 'Custom' } }
+		],
+		args: { down: 'categories', delete: 'categories' }
+	});
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Stock.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Marketplace.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Custom.json')), false);
+});
+
+test('down-only delete skips local removals after a sync-state error', t => {
+	const result = runSync(t, {
+		state: { sync: { 'category-old': true } },
+		failAPI: 'update_global_state',
+		existingSources: [
+			{ path: 'categories/Stale.json', type: 'category', data: { id: 'stale', title: 'Stale' } }
+		],
+		args: { down: 'categories', delete: 'categories' }
+	});
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /Delete pass skipped/);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'categories/Stale.json')), true);
+});
+
 test('sync errors exit nonzero even in quiet mode or a dry run', t => {
 	for (const dry of [false, true]) {
 		const result = runSync(t, { missingDir: true, args: { up: 'categories', dry, quiet: true } });

package/test/sync.test.js

@@ -510,6 +510,48 @@ test('sync', async t => {
 			assert.ok(fixtures.category && fixtures.plugin && fixtures.event, 'Resources outside the missing fixture remain');
 			assert.deepEqual(fixtures.syncState, deleteSyncState, 'Up-only delete mode tracks the remaining Category sources');
 		});
+		
+		await check('remove disposable remote Event and Plugin for down-only deletion', async () => {
+			// The local sources and external property files remain in the isolated
+			// sync tree. Delete only these two server fixtures so down-delete has
+			// exactly two local candidates and no unrelated remote mutations.
+			await call('deleteEvent', { id: eventID });
+			await call('deletePlugin', { id: pluginID });
+			const fixtures = await getFixtures();
+			assert.equal(fixtures.event, undefined);
+			assert.equal(fixtures.plugin, undefined);
+			assert.ok(fixtures.category, 'Unrelated Category remains in xyOps');
+			for (const file of [eventFile, eventScriptFile, pluginFile, pluginScriptFile, categoryFile]) {
+				assert.ok(fs.existsSync(file), 'Local fixture remains before down-delete: ' + file);
+			}
+		});
+		
+		await check('dry down-only delete preserves local Event and Plugin files', () => {
+			const output = xy([
+				'sync', syncRoot, '--up', 'false', '--down', 'events,plugins', '--delete', 'events,plugins', '--dry'
+			], { cwd: temp });
+			assert.match(output, /Would delete local event/);
+			assert.match(output, /Would delete local plugin/);
+			for (const file of [eventFile, eventScriptFile, pluginFile, pluginScriptFile, categoryFile]) {
+				assert.ok(fs.existsSync(file), 'Dry run preserves local fixture: ' + file);
+			}
+		});
+		
+		await check('down-only delete removes only missing Event and Plugin files', async () => {
+			const output = xy([
+				'sync', syncRoot, '--up', 'false', '--down', 'events,plugins', '--delete', 'events,plugins'
+			], { cwd: temp });
+			assert.match(output, /Deleting local event/);
+			assert.match(output, /Deleting local plugin/);
+			for (const file of [eventFile, eventScriptFile, pluginFile, pluginScriptFile]) {
+				assert.ok(!fs.existsSync(file), 'Down-delete removes local fixture: ' + file);
+			}
+			assert.ok(fs.existsSync(categoryFile), 'Unrelated local Category remains');
+			const fixtures = await getFixtures();
+			assert.ok(fixtures.category, 'Down-delete preserves unrelated remote Category');
+			assert.equal(fixtures.event, undefined);
+			assert.equal(fixtures.plugin, undefined);
+		});
 	}
 	finally {
 		const cleanupErrors = [];

package/test/tickets.test.js

@@ -23,6 +23,7 @@ test('tickets', async t => {
 	const body = '# Test Ticket\n\n- **Bold item** with `code`\n';
 	let ticketCreated = false;
 	let tagCreated = false;
+	let commentAuthor = '';
 
 	fs.writeFileSync(bodyFile, body);
 	fs.writeFileSync(firstFile, 'First Ticket attachment.\n');
@@ -110,6 +111,8 @@ test('tickets', async t => {
 			const saved = row.changes.filter( change => change.type == 'comment' );
 			assert.equal(saved.length, 1);
 			assert.equal(saved[0].body, comment);
+			// The API key can belong to any user, so use the author saved by xyOps.
+			commentAuthor = saved[0].username || '(Unknown)';
 			assert.equal(row.status, 'draft');
 		});
 
@@ -159,7 +162,7 @@ test('tickets', async t => {
 				'TICKET #' + num, 'Number', '#' + num, 'Ticket ID', id, subject,
 				'TICKET BODY', 'Test Ticket', '• Bold item with code',
 				'TICKET FILES', Path.basename(firstFile), Path.basename(secondFile), 'Download a file',
-				'Comment by admin', 'Investigation update', '• Checked the logs'
+				'Comment by ' + commentAuthor, 'Investigation update', '• Checked the logs'
 			]) assert.ok(out.includes(text), text);
 			if (event) {
 				assert.match(out, /TICKET EVENTS/);