Reorganise Documentation for a Developer Tool

Problem/Feature Description

A small team built an internal tool called syncflow — a CLI for syncing files between environments. Over the past year, several team members have each added documentation pages in an ad-hoc way. The result is a folder of Markdown files that are hard to navigate: some pages mix step-by-step instructions with conceptual background, some reference docs include lengthy explanations of when to use each option, and it's unclear which pages are for beginners versus experienced users.

The team wants the documentation restructured into a coherent system that is easy to navigate. A reader coming to any page should be able to find the information they need quickly, and should be able to find related pages without having to search. The team has agreed it is time to bring the docs up to a professional standard.

The existing documentation files are provided below. Your job is to produce a reorganised documentation set.

Output Specification

Produce the reorganised documentation as individual Markdown files in an output/ subdirectory. Each file should be a single documentation type. Name the files descriptively (e.g., output/tutorial-first-sync.md, output/how-to-schedule-jobs.md, output/reference-cli-flags.md, output/explanation-sync-model.md).

Also produce a file named output/index.md that lists all the pages with a one-sentence description of each and its documentation type.

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: inputs/page-a.md ===============

Getting started with syncflow

syncflow uses a concept called a "workspace" to track which files belong to a sync job. A workspace is a directory on your machine that syncflow monitors.

syncflow supports three sync modes: mirror, merge, and delta. Mirror mode overwrites the destination with the source. Merge mode combines files from both sides. Delta mode only transfers files that have changed since the last sync.

To install syncflow, run: npm install -g syncflow

After installing, create your first workspace:

1. Open your terminal
2. Run syncflow init my-workspace
3. You should see: Workspace 'my-workspace' created successfully
4. Add a file: echo "hello" > my-workspace/test.txt
5. Run syncflow sync my-workspace to perform your first sync
6. You should see output like: Synced 1 file(s) in 0.3s

syncflow uses a TOML configuration file called .syncflow.toml. The mode key controls which sync mode is used. Valid values are mirror, merge, delta. The default is mirror. The exclude key accepts a list of glob patterns for files to ignore. The retry key sets the number of retry attempts on failure (integer, default: 3).

=============== FILE: inputs/page-b.md ===============

Scheduling sync jobs with cron

This page explains how to use cron to run syncflow on a schedule. It assumes you have syncflow installed and a workspace already configured.

Why scheduled syncs matter: in distributed teams, keeping environments in sync manually is error-prone. Automated scheduling ensures consistency without relying on developers remembering to run syncs manually. This is especially important during deployment windows when configuration drift can cause hard-to-debug failures.

Goal: set up syncflow to run automatically every hour.

Prerequisites:

• syncflow installed and working
• An existing workspace named prod-config
• Access to edit your crontab

Steps:

1. Open your crontab: crontab -e
2. Add the following line: 0 * * * * syncflow sync prod-config
3. Save and close the editor
4. Verify the job was added: crontab -l — you should see your new entry
5. To test immediately without waiting: syncflow sync prod-config --dry-run

You can also use systemd timers as an alternative to cron on Linux systems. The approach differs but achieves the same outcome.

=============== FILE: inputs/page-c.md ===============

Understanding how syncflow resolves conflicts

When two sides of a sync have both modified the same file, syncflow has to decide what to do. This page explains the reasoning behind syncflow's conflict resolution design.

The core problem: unlike version control systems, syncflow doesn't track history — it only knows the current state of files and their last-modified timestamps. This means it can't do a three-way merge. Instead, it has to choose a strategy.

The three sync modes represent three different philosophies about how to handle this:

Mirror treats the source as authoritative. Any conflict is resolved in favour of the source. This is predictable and safe for one-directional workflows (e.g., deploying config from a central store to multiple machines), but dangerous if the destination also has legitimate changes.

Merge tries to keep both sides' changes by preserving the newer file. This works well when files are independent, but can silently lose data when two writers modify the same file with the same timestamp.

Delta is designed for efficiency, not correctness — it skips files that appear unchanged to minimise transfer time. The trade-off is that it can miss changes if the clock on one machine is skewed.

These trade-offs explain why syncflow requires users to choose a mode explicitly rather than picking one automatically: the right choice depends on the deployment context, not on a general heuristic.

=============== FILE: inputs/page-d.md ===============

CLI flags

--dry-run (boolean, default: false) Runs the sync operation without making any changes. Prints the list of files that would be transferred. Example: syncflow sync my-workspace --dry-run

--verbose (boolean, default: false) Prints detailed transfer logs including file sizes and transfer speeds. Example: syncflow sync my-workspace --verbose

--mode (string, default: inherited from .syncflow.toml) Overrides the sync mode for this invocation. Valid values: mirror, merge, delta. Example: syncflow sync my-workspace --mode=delta

--retry (integer, default: 3) Number of times to retry a failed file transfer before giving up. Set to 0 to disable retries. Example: syncflow sync my-workspace --retry=5

--exclude (string, repeatable) Glob pattern for files to exclude from this sync. Can be specified multiple times. Example: syncflow sync my-workspace --exclude="*.log" --exclude="tmp/*"

To understand when to use --dry-run versus just reading the logs, think of --dry-run as a preview mode. It's useful when you're making a significant configuration change and want to verify what will happen before committing. Understanding dry-run is important because syncflow operations can't be undone — there's no undo command.