@pixlcore/xycli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# xyCLI Changelog
+
+## Version v1.0.0
+
+> September 20, 2026
+
+- Initial release!

package/README.md

@@ -26,6 +26,7 @@ Browse the [screenshot gallery](docs/screenshots.md) for more views, or jump to
 - [Configuration](#configuration)
 - [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)
 - [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)
@@ -483,7 +484,7 @@ cd xyops-automation
 xy sync setup events plugins categories --file_props script,params.script
 ```
 
-Setup creates one file per definition and can extract scripts into adjacent source files. You choose how to organize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
+Setup creates one file per definition and can extract scripts into adjacent source files. Events and workflows are automatically grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
 
 Preview a push or pull, then apply the direction you want:
 
@@ -499,6 +500,8 @@ Sync supports Alerts, API Keys, Categories, Channels, Events and workflows, Grou
 
 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`.
 
+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.
+
 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).
@@ -540,4 +543,4 @@ xy api runEvent --id EVENT_ID --params.example VALUE --dry
 xy api updateEvent --json @./request.json --dry
 ```
 
-The examples with `--dry` display the request without calling the API. Many resource views also accept `--format json` to display their data as JSON. See the [xyOps API Reference](https://docs.xyops.io/api), [API command](docs/help.md#api), and [documentation command](docs/help.md#doc) for more.
+The examples with `--dry` display the request without calling the API. Many resource views also accept `--format json` to display their data as JSON. See the [xyOps API Reference](https://docs.xyops.io/#Docs/api), [API command](docs/help.md#api), and [documentation command](docs/help.md#doc) for more.

package/docs/help.md

@@ -231,7 +231,7 @@ xy sync ./ --up events,plugins --delete events
 
 **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.
 
-**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 or deletions begin.
+**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.
 
 **Completion commands and notifications**
 
@@ -250,7 +250,7 @@ xy sync ./ --up events,plugins \
 
 Completion commands run in a local shell in the first base directory. Deletions alone do not trigger them. 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.
+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.
 
 Sync warnings and errors exit with status `1`, including warnings or errors during dry runs and completion-command errors. Completion commands and notifications can finish before the process exits. Runs with no warnings or errors exit with status `0`. Scan warnings stop the run before updates and can trigger notifications.
 
@@ -281,6 +281,9 @@ Export existing xyOps definitions into a starter sync tree in the current direct
 ```sh
 xy sync setup events plugins categories --dry
 xy sync setup events plugins categories --file_props script,params.script
+xy sync setup events --file_props params.script --default_ext ps1
+xy sync setup events plugins --new
+xy sync setup events --new --down_cmd "./commit-downloads.sh"
 xy sync setup all
 xy sync setup all --stock --marketplace
 xy sync setup events plugins --force
@@ -289,17 +292,25 @@ xy sync --setup events,plugins --file_props script,params.script
 
 Choose one or more resource types separated by spaces, or use `all`. Supported types are the same as for `xy sync`. The `--setup TYPES` form also accepts a comma-separated list.
 
-Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Both are synced with `--up events` or `--down events`.
+Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Events and workflows are grouped into subfolders using their Category title as a slug. Both are synced with `--up events` or `--down events`. Setup stops before writing if an Event or workflow selected for export refers to a missing Category.
 
 - `--file_props PATHS` extracts string properties into adjacent files.
+- `--default_ext EXT` sets the fallback neighbor extension instead of `txt`.
+- `--new` writes only remote definitions not already represented locally.
+- `--down_cmd COMMAND` runs after setup writes one or more definitions.
+- `--cmd_timeout SECONDS` changes the command timeout from 30 seconds.
 - `--stock` includes stock objects, which are omitted by default.
 - `--marketplace` includes Marketplace objects, which are omitted by default.
 - `--force` allows generated files to overwrite existing destinations.
 - `--dry` previews the layout without creating directories or writing files.
 
-For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically.
+For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically. Setup chooses extensions from executable commands, shebangs, and JSON content when possible. Use `--default_ext ps1` (or `--default_ext .ps1`) to replace the `.txt` fallback for properties whose type cannot be detected. The override does not replace an extension that setup successfully detects.
 
-Without `--force`, setup stops when an output file already exists. Files written before an error are not rolled back. Ensure object titles produce distinct filename slugs, especially when using `--force`, and back up any local edits before rerunning setup. For a delete-mode inventory, verify that every object eligible for deletion that you intend to keep has a source file. Stock and Marketplace objects are protected from deletion and may be omitted.
+Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
+
+An explicitly supplied `--down_cmd` runs from the current setup directory after at least one definition is written. It does not run when `--new` finds nothing or during a dry run. Saved sync completion commands are not inherited by setup.
+
+Without `--force`, ordinary setup stops when an output file already exists. Files written before an error are not rolled back. Ensure object titles produce distinct filename slugs, especially when using `--force`, and back up any local edits before rerunning setup. For a delete-mode inventory, verify that every object eligible for deletion that you intend to keep has a source file. Stock and Marketplace objects are protected from deletion and may be omitted.
 
 ## api
 

package/docs/sync.md

@@ -113,18 +113,20 @@ xyops-automation/
     categories/
         Backups.json
     events/
-        Nightly-Backup.json
-        Nightly-Backup-params.script.sh
+        Operations/
+            Nightly-Backup.json
+            Nightly-Backup-params.script.sh
     plugins/
         Custom-Runner.json
         Custom-Runner-script.js
     workflows/
-        Release-Pipeline.json
+        Deployments/
+            Release-Pipeline.json
 ```
 
-Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`. Both participate in normal sync through the `events` selection.
+Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`, then grouped into subfolders using their Category titles. Both participate in normal sync through the `events` selection.
 
-Filenames come from each definition's title: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, `Nightly Backup` becomes `Nightly-Backup.json`. Different titles can produce the same filename, so review the preview for collisions.
+Folder and filenames come from Category and definition titles: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, the Event `Nightly Backup` in the `Operations` Category becomes `events/Operations/Nightly-Backup.json`. Different titles can produce the same path, so review the preview for collisions. Setup stops before writing anything if an Event or workflow selected for export refers to a Category that is not present in xyOps.
 
 ### 4. Review and version the tree
 
@@ -159,6 +161,17 @@ xy sync setup events plugins --force
 
 `--force` allows generated JSON and external files to be overwritten. It does not clean up old filenames, solve filename collisions, or preserve your local edits. Export into a fresh directory when adding newly created objects, then move their reviewed files into the existing tree. 
 
+To add only definitions that are new to an existing sync tree, run setup from the tree's root with `--new`:
+
+```sh
+xy sync setup events plugins categories --new --file_props script,params.script --dry
+xy sync setup events plugins categories --new --file_props script,params.script
+```
+
+New-only setup scans the current directory recursively and indexes existing XYPDF sources by item type and exact ID. Renamed files and custom folders are preserved. Remote definitions not found in that index are written to setup's normal type and Category folders; existing definitions are skipped without being rewritten. Malformed, duplicate, unsupported, or locally orphaned sources stop the operation before new files are written. `--new` cannot be combined with `--force`.
+
+This is an additive local export. It does not create definitions in xyOps, and ordinary upsync or downsync still updates only definitions that already exist on both sides.
+
 Alternatively, you can export single objects at a time:
 
 ```sh
@@ -232,6 +245,8 @@ This extracts the selected content, if found, and moves it to a neighboring file
 
 The general naming pattern is **`BASENAME-PROPERTY.EXT`**, in the same directory as `BASENAME.json`. Dot paths such as `params.script` identify nested properties. Setup chooses an extension from the executable command or a script's shebang when possible, falling back to JSON-looking content or `.txt`. Normal sync accepts your chosen extension.
 
+Use `--default_ext EXT` to replace the `.txt` fallback when setup cannot detect a type. For example, `--default_ext ps1` and `--default_ext .ps1` both produce `.ps1` neighbors. Detected interpreter and JSON extensions still take precedence. The fallback applies to every undetected property selected by that setup command, so group properties with the same expected file type or run setup separately when needed.
+
 External properties are detected automatically when sync runs; you do not need to repeat `--file_props`. The neighbor's text replaces that property in the local definition before comparison and before an upload. A pull writes the latest value into the existing neighbor file.
 
 You can use this for other string properties too, such as `body` or `notes`. Keep only one neighbor file per unique property path. A neighbor must resolve to a valid property path, and multiple matching neighbors are not treated as alternative versions.
@@ -393,12 +408,16 @@ At least one direction must be enabled. The command is a single run, not a backg
 | `xy sync setup TYPES...` | Export the selected types to the current directory. Separate type names with spaces, or use `all`. |
 | `--setup TYPES` | Alternative setup syntax, accepting comma-separated type names. For example, `xy sync --setup events,plugins`. |
 | `--file_props PATHS` | Extract string properties into adjacent neighbor files. Accepts comma-separated dot paths or a JSON array. |
+| `--default_ext EXT` | Use this extension instead of `txt` when a neighbor's type cannot be detected. A leading dot is optional. |
+| `--new` | Export only remote definitions whose type and ID are not already present in the current local tree. |
+| `--down_cmd COMMAND` | Run a local shell command after setup writes one or more definitions. |
+| `--cmd_timeout SECONDS` | Set the setup completion-command timeout in seconds. The default is `30`. |
 | `--stock` | Include stock definitions that ships wit xyOps (e.g. "Shell Plugin"), which setup normally omits. |
 | `--marketplace` | Include Marketplace Plugins, which setup normally omits. |
 | `--force` | Allow generated files to overwrite existing destinations. |
 | `--dry` | Preview setup's output without creating folders or files. |
 
-Workflow defaults in the `sync` configuration object are not used by setup. Pass setup choices explicitly on the command line. The common `lock_file` setting still applies so setup cannot overlap another sync operation for the same instance.
+Workflow defaults in the `sync` configuration object are not used by setup. Pass setup choices explicitly on the command line. An explicitly supplied `down_cmd` runs from the current setup directory only after real files are written, so it does not run during a dry run or when `--new` finds nothing. The common `lock_file` setting still applies so setup cannot overlap another sync operation for the same instance.
 
 ## Two-way sync and modification times
 
@@ -472,7 +491,9 @@ Inspect the entire deletion list and confirm that the directory and remote inven
 xy sync ./ --up events,plugins,categories --down false --delete events
 ```
 
-Deleting an Event does not automatically remove its dependencies. Remote API rules still apply, including restrictions on active jobs and references. Successful earlier updates or deletions are not rolled back if a later deletion fails.
+Deleting an Event does not automatically remove its dependencies. Remote API rules still apply, including restrictions on active jobs and references.
+
+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.
 
 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.
 
@@ -499,6 +520,7 @@ xy sync ./ --down events,plugins --down_cmd "./commit-downloads.sh" --cmd_timeou
 
 - `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.
+- 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.
 - A completion command can run after partial success even if another item failed. It is not proof that the whole run succeeded.
@@ -896,7 +918,7 @@ Repository concurrency controls these workflow runs. Coordinate all writers to t
 | 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 | It requires at least one successful download. A no-op, dry run, scan failure, or deletion alone does not trigger it. |
+| `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. |
 | 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 and collected reports. Remove it to investigate and configure notifications. |

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

@@ -0,0 +1,262 @@
+# Two-Way Git Sync Tutorial
+
+> [!IMPORTANT]
+> Some of the features used in this tutorial require xyCLI v1.0.2 or newer.
+
+This tutorial sets up one persistent Git checkout as the bridge between xyOps and a shared repository. Team members can edit and push Event files through Git, while changes made in the xyOps web interface are downloaded, committed, and pushed back to the repository.
+
+The finished workflow looks like this:
+
+```text
+Developers <-> Git repository <-> Dedicated sync checkout <-> xyOps
+```
+
+One machine and operating-system account should own the dedicated sync checkout. That machine can be an xyOps worker running xySat, but xySat is not required. Cron, another scheduler, or a manually launched script works too.
+
+This tutorial manages Events and workflows. You can expand the commands to other [supported resource types](sync.md#supported-resources-and-requirements) after the Event flow is working.
+
+## Before you begin
+
+You will need:
+
+- xyCLI installed and connected to xyOps.
+- A dedicated Git repository and a persistent clone on the sync machine.
+- A xyOps API Key that can read and edit Events and update the global sync state.
+- Git credentials that allow the sync account to pull and push without an interactive prompt.
+- A configured Git author name and email for automated commits.
+- Accurate clocks on the sync machine and the xyOps conductor, preferably synchronized through NTP.
+- The `flock` command on the scheduler host if you plan to use cron.
+
+Two-way sync is experimental. When the local and remote definitions differ, xyCLI compares the xyOps modification timestamp with the newest modification time among the local JSON file and its external property files. The newer side wins, and equal timestamps favor the local copy.
+
+Do not periodically replace the dedicated checkout with a fresh clone. Git checkout operations can change filesystem timestamps, which are part of two-way conflict resolution.
+
+## 1. Prepare the dedicated checkout
+
+Clone the repository into a permanent location. Replace the example URL and path with your own:
+
+```sh
+git clone git@github.com:YOUR_ORG/xyops-automation.git /srv/xyops-automation
+cd /srv/xyops-automation
+```
+
+Configure the identity used for commits created by sync:
+
+```sh
+git config user.name "xyOps Sync"
+git config user.email "xyops-sync@example.com"
+```
+
+Run all remaining setup commands as the same operating-system account that will run the scheduled job. Configure xyCLI for that account if you have not already done so:
+
+```sh
+xy config --base_url https://xyops.example.com --api_key YOUR_API_KEY
+xy dashboard
+```
+
+The dashboard command verifies the connection. Keep the API Key and Git credentials out of the repository.
+
+## 2. Export the initial Event tree
+
+Preview the initial setup from the repository root:
+
+```sh
+cd /srv/xyops-automation
+xy sync setup events --file_props script,params.script --default_ext ps1 --dry
+```
+
+The `events` selection includes both Events and workflows. Setup places workflows in their own `workflows/` directory, then groups Events and workflows into subfolders named after their Categories.
+
+`--file_props script,params.script` extracts common Plugin and Event script properties into neighboring files. If your Plugin uses another property, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
+
+The optional `--default_ext ps1` uses `.ps1` when setup cannot detect a neighbor file's language from an executable command, shebang, or JSON content. Remove it or choose another extension if PowerShell is not the appropriate fallback for your repository.
+
+When the preview looks correct, write the files:
+
+```sh
+xy sync setup events --file_props script,params.script --default_ext ps1
+```
+
+Review the generated files before publishing them. Definitions can contain scripts, request headers, and other sensitive configuration.
+
+```sh
+git status --short
+find events workflows -type f -print 2>/dev/null
+```
+
+Commit and push the initial tree:
+
+```sh
+git add --all
+git commit -m "Add xyOps Event definitions"
+git push -u origin HEAD
+```
+
+Setup is only responsible for creating the local source files. Normal sync identifies each definition by its resource type and exact ID inside the JSON, so you may reorganize or rename the generated files afterward.
+
+## 3. Preview two-way sync
+
+Run a dry pass before enabling automation:
+
+```sh
+xy sync . --up events --down events --delete false --dry
+```
+
+This considers both directions for every local Event and workflow source:
+
+- A newer local file is uploaded to its existing xyOps definition.
+- 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 safely. Delete an item deliberately on both sides, and keep deletion disabled in the scheduled command.
+
+Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
+
+## 4. Create the scheduled sync script
+
+Save the following script as `/usr/local/sbin/xyops-git-sync`. Adjust `PATH`, `REPO_DIR`, `XY_BIN`, the extracted property list, and the fallback extension for your environment.
+
+```sh
+#!/bin/sh
+set -eu
+
+# Cron and xySat jobs often receive a minimal environment. Include the
+# directories containing Node.js, xyCLI, Git, and standard system tools.
+PATH="/usr/local/bin:/usr/bin:/bin"
+export PATH
+
+REPO_DIR="/srv/xyops-automation"
+XY_BIN="/usr/local/bin/xy"
+
+cd "$REPO_DIR"
+
+# This should be a dedicated automated checkout. Stop instead of accidentally
+# committing an operator's unfinished work or leftovers from a failed run.
+if [ -n "$(git status --porcelain)" ]; then
+	echo "The sync checkout has uncommitted changes. Resolve them before retrying."
+	exit 1
+fi
+
+# Bring in changes pushed by contributors. The extra push retries a commit
+# that may have succeeded during an earlier run whose network push then failed.
+git pull --quiet --ff-only
+git push --quiet
+
+# xyCLI runs this only after it writes local definitions.
+GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
+
+# Sync changes to existing local definitions in both directions. If this
+# command fails, set -e stops the script before the setup pass.
+"$XY_BIN" sync . \
+	--up events \
+	--down events \
+	--delete false \
+	--down_cmd "$GIT_DOWN_CMD" \
+	--cmd_timeout 120
+
+# Discover definitions created in xyOps since the initial setup. Existing
+# sources are identified by type and ID, regardless of their paths or names.
+# The setup completion command runs only when new files were actually written.
+"$XY_BIN" sync setup events \
+	--new \
+	--file_props script,params.script \
+	--default_ext ps1 \
+	--down_cmd "$GIT_DOWN_CMD" \
+	--cmd_timeout 120
+```
+
+Make the script executable:
+
+```sh
+chmod 755 /usr/local/sbin/xyops-git-sync
+```
+
+Run it manually as the eventual scheduler account before installing a schedule:
+
+```sh
+/usr/local/sbin/xyops-git-sync
+```
+
+The script intentionally does not implement its own outer lock. A cron caller will use `flock` to protect the complete pull, normal sync, and new-definition setup sequence. When xyOps schedules the script through xySat, the Event's job concurrency setting provides this protection instead. xyCLI's built-in lock still protects each individual sync command.
+
+The two uses of `--down_cmd` are deliberately identical:
+
+- Ordinary sync runs it only after at least one existing definition is successfully downloaded.
+- `sync setup --new` runs it only after at least one new local definition is written.
+- A no-op or dry run does not create a commit or push.
+
+The command stages the entire dedicated repository with `git add --all`. Do not use this script in a checkout containing unrelated work. If your repository contains other material, narrow the Git paths in `GIT_DOWN_CMD`.
+
+## 5. Schedule the script with cron
+
+Open the crontab for the sync account:
+
+```sh
+crontab -e
+```
+
+Locate `flock` and adjust the path in the cron entry if necessary:
+
+```sh
+command -v flock
+```
+
+Run the script every minute, with `flock` outside the script:
+
+```cron
+* * * * * /usr/bin/flock --nonblock --conflict-exit-code 0 /tmp/xyops-git-sync.lock /usr/local/sbin/xyops-git-sync >/dev/null
+```
+
+Cron normally emails job output when local mail delivery is configured. This entry discards routine standard output so successful runs remain silent, but leaves standard error alone so failures can still trigger mail. The xyCLI commands deliberately omit `--quiet`, because that option can suppress collected sync warnings and error reports along with routine output.
+
+To keep successful output in a log instead, replace `>/dev/null` with an append redirect to a file that the sync account can write. Do not place that log inside the Git repository because the completion command stages the whole tree.
+
+`--nonblock` makes an overlapping invocation exit immediately instead of waiting. `--conflict-exit-code 0` treats that expected skip as a successful scheduler run, while an executed sync script still returns its own exit status. The operating system releases the advisory lock automatically when `flock` exits, including when the sync script fails. The `/tmp/xyops-git-sync.lock` file may remain afterward, which is normal and does not mean the lock is still held. See the [`flock` manual](https://man7.org/linux/man-pages/man1/flock.1.html) for details.
+
+## 6. Or schedule it through xySat
+
+On a machine running xySat, create an Event using the Shell Plugin and target only the dedicated sync worker. Give it a recurring one-minute schedule and use this script body:
+
+```sh
+/usr/local/sbin/xyops-git-sync
+```
+
+Keep the Event's [job concurrency setting](https://docs.xyops.io/#Docs/limits/max-jobs-limit) at `1`, which is the default. xyOps will then prevent a second copy of the Event from running while the first job is still active, so this invocation does not need `flock`.
+
+The xySat service account must be able to execute the script, read and write the repository, run Node.js and xyCLI, access that account's xyCLI configuration, and use the Git credentials. Test the Event manually before enabling its schedule.
+
+Schedule only one copy of this workflow, and do not run both cron and xySat for the same checkout.
+
+## 7. Understand the daily workflow
+
+After setup, contributors work through Git as usual:
+
+```sh
+git pull
+# Edit Event JSON or neighboring script files.
+git add --all
+git commit -m "Update nightly report"
+git push
+```
+
+The next scheduled pass pulls the commit and uploads newer local definitions to xyOps. If someone edits an existing Event in the xyOps web interface, the next pass downloads the newer definition, and `--down_cmd` commits and pushes the changed files.
+
+When someone creates a new Event in xyOps, the ordinary sync pass does not know where to create its local source. The following `sync setup events --new` pass discovers it, creates the suggested files in its Category folder, then commits and pushes them through its own `--down_cmd`.
+
+`--new` is additive. It does not overwrite existing sources, and it matches existing definitions by type and exact ID rather than filename. This preserves renamed files and custom folder layouts.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `git pull --ff-only` fails | The sync clone and remote branch have diverged, or the working tree changed. Resolve the Git state manually. Do not force-reset the automated checkout without reviewing its commits. |
+| `git push` prompts or fails under cron or xySat | Configure noninteractive SSH or HTTPS credentials for the scheduler account and confirm the branch allows that account to push. |
+| Git reports an unknown author | Set `user.name` and `user.email` in the dedicated clone for the scheduler account. |
+| The wrong side wins a two-way conflict | Check NTP, the xyOps conductor clock, and the modification times of the JSON and neighboring files. A checkout, restore, or file copy can refresh local timestamps. |
+| A new Event is not exported | Confirm `sync setup events --new` runs from the repository root and that the API Key can see the Event. Add the correct property path if its script is stored somewhere other than `params.script`. |
+| A new Git file is not created in xyOps | Ordinary sync updates definitions that already exist on both sides. Create or import the definition into xyOps first, then let sync manage subsequent changes. |
+| A deleted item reappears or causes an error | Two-way deletion is not supported. Remove the local source and the xyOps definition deliberately as one coordinated operation. |
+| A cron run is skipped | Another cron invocation may hold the `flock` lock. The lock file itself may remain when no lock is held, so check for a running sync process rather than treating the file as stale. |
+| A completion command times out | Increase `--cmd_timeout`, investigate Git network latency, and confirm that Git cannot wait for interactive input. |
+
+For the complete behavior and option reference, see the [Filesystem Sync Guide](sync.md) and the [`sync` command reference](help.md#sync).