mark-twin 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39f52a8341611b4a17bbeaffae64e21e7ffc2123f1b766df494eb422db697cb6
-  data.tar.gz: 224e40d39832efc3542c1c3de00e4c6fe30d01c72ca4f84ff5bc9868f15cedd3
+  metadata.gz: 5bae405ea7916f59395530f5372cd3bde2aa4ff742ca4cf08142ca16be5c7cd9
+  data.tar.gz: b05b48d23901e7c6c2fd313ecc0f8ef2dbf172ab77ef38b5575088031dc186da
 SHA512:
-  metadata.gz: 8f217e753b18810cad48b2e6c2f3360a3cc84e4f6449dd14f9f62aae4243b55d44a4d2b8321a8f60228c4ca696e97106f9cdca1e6a54f404436af284130609dd
-  data.tar.gz: 301088d4bd68082461e9e8d0730d1c921336256e8fe3f3a755f918c6e189fc4238fc4bd7c3f7e4e8879474f9736ef4272a5117ce8b3b97316983031e0656201b
+  metadata.gz: 3d10977e33311149b1d90486c553cf6ce773c9c2927a081f3e264dcb9a8d0c97be61bb62883b070cb739ab66aa710d2d359b95db33018f8463bd0ac9987c0a95
+  data.tar.gz: ec1eecdf09d77e1c0ef6480edeb889c9d737b87cbd9eda5a9e83e210ca5fc2eeee85d06f86ccb65e81040197a8a4402001eeb79bda60710f44c77cd7e2e16c26

data/ARCHITECTURE.md

@@ -19,6 +19,11 @@ sync-files (.md)
       └──▶  Picker    fzf + apex preview, returns selected Program
                           │
                           ▼
+                          │
+                          ▼
+                    Conflict   paired dry-runs → files --update would hold
+                          │     back → content compare → ask once, or abort
+                          ▼
                        Sync   rsync (or render) per Job, mount check, Cmd hook
 ```
 
@@ -27,10 +32,14 @@ sync-files (.md)
 ```
 lib/twin/
   version.rb
+  remote.rb     ssh targets: detection, reachability, batched stat, mkdir
   template.rb   {{token}} substitution + render-file helper
   config.rb     ~/.config/twin/config.yaml loader; host table → var_map
   scanner.rb    Job, Program structs; grubber + template + stat → grouped Programs
   sync.rb       rsync / render execution, mount check, post-sync hook
+  conflict.rb   target-side changes: detection via paired dry-runs, diffs
+  journal.rb    append-only sync journal (~/.local/state/twin/log.jsonl)
+  add.rb        `twin add` — interactive scaffolding of new sync entries
   picker.rb     fzf wrapper with apex preview
   cli.rb        subcommand dispatcher
 
@@ -43,13 +52,18 @@ test/test_pure.rb
 **Job** — one YAML block:
 
 ```
-program, path, description, active, excludes, label, source, target, cmd,
+program, path, description, active, excludes, owned, label, source, target, cmd,
 delete, render, render_outdated, target_path_field, sync_file,
 source_exists, target_exists, source_mtime, target_mtime, conflict
 ```
 
-`Job#status` → one of `disabled / both_missing / missing_source / missing_target /
-target_newer / in_sync / source_newer`. Render jobs derive status from content
+`excludes` and `owned` both become `--exclude` (via `Job#all_excludes`); they
+are kept apart so `status` can report intent. `conflict` is the coarse mtime
+flag used by `status` only — conflict *resolution* ignores it and asks rsync
+directly, because a directory's mtime says nothing about edits inside it.
+
+`Job#status` → one of `disabled / unreachable / both_missing / missing_source /
+missing_target / target_newer / in_sync / source_newer`. Render jobs derive status from content
 (`render_outdated`), not mtime; non-render jobs ignore those fields.
 `Job#target_path` joins `target` with `target_path_field || path`.
 
@@ -62,6 +76,22 @@ name, jobs
 `Program#status` aggregates jobs (worst state wins). Selection in the picker
 operates on Programs, not individual Jobs.
 
+**Job order is part of the contract.** Jobs of a Program run in the order their
+YAML blocks appear in the sync-file. Sync-files rely on this — a `Cmd` that
+restarts a service belongs in the last block, so it fires after every path is in
+place. Reorder the jobs and a deploy restarts against half-written state,
+without any error to show for it.
+
+The order is guaranteed at both ends of the pipeline, not merely observed:
+
+- grubber emits records in document order — first block, first record — for all
+  three output formats, pinned by its own `TestBlockOrderFollowsDocument`
+  across `Extract` and `StreamJSONL`.
+- twin preserves it through `filter_map` and `group_by` (insertion order per
+  key), pinned by `test_job_order_follows_document_order`.
+
+Neither side may quietly sort.
+
 ## Configuration
 
 `~/.config/twin/config.yaml`:
@@ -151,17 +181,60 @@ File argument resolution (`twin <arg>` and `--file=<arg>`):
 Unknown options (anything starting with `-` that isn't `--help`) print an
 error pointing at `twin --help` and exit 1.
 
+`twin sync` returns exit 1 when any job failed. `--quiet` suppresses output
+for successful no-op jobs (conflicts, errors and real transfers still print);
+`--skip-unavailable` skips unmounted/unreachable targets instead of aborting.
+The combination is the unattended-run mode (launchd/cron).
+
+Every non-dry-run job lands in the journal (`Journal.record`): one JSON line
+in `~/.local/state/twin/log.jsonl` (`TWIN_STATE_DIR` overrides the directory)
+with timestamp, program, path, target, `ok`, `changed`, and a truncated error
+line on failure. `twin log [-n N] [--json]` reads it back. Journal write
+failures warn once and never break a sync.
+
+`twin add <path>` (`add.rb`) scaffolds a new entry: it matches the expanded
+path against the token-substituted `Source:` frontmatter of every sync-file
+(files with no or foreign roots drop out), computes `Path:` relative to the
+chosen root, suggests excludes from a fixed list of generated/heavy dirs found
+in the source (`SUGGEST_EXCLUDES`), rejects paths the file already has a
+block for, and appends heading + prose stub + YAML block. With no covering
+sync-file it can create one (frontmatter from prompts). The pure helpers
+(`frontmatter`, `candidates`, `relative_path`, `suggest_excludes`,
+`build_block`) are unit-tested; the prompt flow reads plain stdin, so it is
+scriptable by piping answers.
+
 `twin doctor` checks required tools (grubber, rsync, fzf), optional renderers
 (apex, glow, bat), templating (host/target resolve, every `{{token}}` resolves),
 and whether all configured sync targets are mounted. Exits 1 if any required
 check fails.
 
+## Remote targets
+
+`Target: user@host:/path` (rsync notation; colon before the first slash) makes
+a job remote — `Job#remote?`. Sources stay local, twin pushes.
+
+- **Stat**: remote paths can't be `File.stat`ed, so `build_job` leaves them
+  "missing" and `Scanner.fill_remote_stats` fills them in afterwards — one
+  `ssh` round-trip per host for all its paths (`Remote.stat_paths`: paths over
+  stdin, `path\tepoch` back; BSD `stat -f %m` with GNU `stat -c %Y` fallback).
+  A failed ssh sets `target_unreachable` → status `:unreachable`; the scan
+  itself never fails on a dead host.
+- **Reachability** replaces the mount check (`Remote.reachable?`,
+  `ssh -o BatchMode=yes … true` — key auth only, never prompts).
+- **rsync** needs no changes: the target string is already in its remote
+  syntax. Parent directories are created via `ssh host mkdir -p` first.
+- **`Cmd`** still runs locally (`sh -c`); acting on the server means writing
+  an `ssh host '…'` command in the sync-file.
+- **`Render: true` + remote raises** at scan time — render reads/writes target
+  content, which twin only does on local (mounted) paths.
+
 ## Sync
 
 Before syncing:
 
-1. **Mount check** — every unique target root must be a mount point
-   (`File.stat.dev != parent.dev`). Aborts if unmounted.
+1. **Mount check** — every unique local target root must be a mount point
+   (`File.stat.dev != parent.dev`); remote targets must be ssh-reachable.
+   Aborts otherwise.
 2. **Conflict warning** — emits stderr listing jobs where the target is
    newer than the source. Continues anyway (`rsync --update` skips them).
 
@@ -171,7 +244,13 @@ Then per Job, **rsync path** (non-render):
 rsync -av --itemize-changes --update [--delete] [--exclude=...]* src/ tgt/
 ```
 
-`--delete` is added when the Job has `delete: true` (from `Delete: true`).
+`--delete` is added when the Job has `delete: true` (from `Delete: true`),
+together with `--backup --backup-dir=<target>/.twin-backup/<run-stamp>` —
+deleted and overwritten files are moved aside, not destroyed. The stamp is
+per-process, so one run shares a backup dir; rsync only creates it when it
+actually backs something up. `--exclude=.twin-backup/` protects the backup
+dir from a `Path: "."` sync deleting it. For remote targets the backup dir
+is the path part of the target (it lives on the receiving side).
 `--itemize-changes` makes change detection deterministic: `Sync.transferred?`
 matches itemize lines (`/\A[<>ch*][fdLDS]/` — `>f…`, `cd…`, `*deleting`),
 covering files, directories and deletions, with no scraping of rsync's prose.

data/README.md

@@ -4,26 +4,56 @@
 [![Tests](https://github.com/rhsev/mark-twin/actions/workflows/test.yml/badge.svg)](https://github.com/rhsev/mark-twin/actions/workflows/test.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Sync configuration folders between two Macs from self-documenting Markdown files.
+Sync configuration between machines, from Markdown files that explain
+themselves.
 
-Sync entries are defined in Markdown files with YAML blocks — human-readable,
-self-documenting, and queryable via [grubber](https://github.com/rhsev/grubber).
-Selection is interactive via [fzf](https://github.com/junegunn/fzf), with a
-Markdown preview rendered by [apex](https://github.com/ttscoff/apex) and
-optional post-sync actions on the target via [mi.lan](https://github.com/rhsev/mi.lan).
+A sync-file is a normal Markdown document. The prose explains it to you — and
+to whatever assistant you point at the file later. The fenced YAML blocks are
+what twin acts on:
 
-## Why?
+````markdown
+---
+Active: 1
+Source: /Users/admin
+Target: admin@macbook:/Users/admin
+---
+
+## Fish Shell
+
+Shell config, including completions and abbreviations. `local.fish` stays
+machine-specific — the laptop keeps its own.
 
-Sync-definitions in Markdown + YAML are three things at once:
+```yaml
+Program: Fish Shell
+Path: .config/fish
+Description: Fish Shell configuration
+Own: conf.d/local.fish
+```
+````
 
-- **Human-readable.** Plain Markdown, no twin-specific syntax to learn. The
-  Markdown frame documents *why* a path is synced, not just what, so you can
-  read your own sync-files in a year and still understand them.
-- **Machine-readable.** The YAML blocks are queryable via grubber, so any tool
-  (twin, but also future ones) can act on the same source of truth.
-- **AI-writable.** LLMs handle Markdown + YAML well. You can ask an assistant to
-  add new entries or refactor existing ones, and the result stays valid for both
-  humans and grubber.
+`twin` then shows you what differs and syncs what you pick. Under the
+hood it is `rsync`; the point is the file above, which still tells you in a
+year *why* a path is synced, not just that it is.
+
+That is the whole idea, and for most entries it stays exactly that small. The
+rest of this README is long because twin does handle the awkward cases — files
+the other machine owns, both sides changed since last time, paths that differ
+per host — not because you need any of them on day one. Skip what you don't
+need.
+
+## Why Markdown
+
+- **You can read it later.** The reason a path is synced lives next to the
+  path, in prose, not in a comment you stopped writing after the third entry.
+- **Machines can read it too.** The YAML blocks are extracted by
+  [grubber](https://github.com/rhsev/grubber), so the same file can feed other
+  tools, not just twin.
+- **It stays editable by hand.** No generated state, no database. Add a block
+  in your editor and twin picks it up.
+- **And yes, ask your AI to write them.** Markdown with YAML blocks is exactly
+  what language models are good at. Show one an existing sync-file, describe
+  the next entry, and what comes back is valid for grubber and still readable
+  by you — which is the whole bargain of this format.
 
 ## Screenshots
 
@@ -37,22 +67,21 @@ compact preview of the relevant sync-file section, rendered by apex:
 
 ![Stage 2 — Fish Shell paths with apex preview](https://raw.githubusercontent.com/rhsev/mark-twin/main/docs/stage_2_fish.png)
 
-## Installation
-
-### 1. Install grubber
-
-twin parses sync-files via [grubber](https://github.com/rhsev/grubber), a
-small Go binary. Download the latest release for your platform from
-[github.com/rhsev/grubber/releases](https://github.com/rhsev/grubber/releases)
-and put it somewhere in your `PATH` (e.g. `/usr/local/bin/grubber`).
-
-### 2. Install twin
+## Install
 
 ```bash
 gem install mark-twin
+brew install fzf
 ```
 
-Or from source:
+Plus [grubber](https://github.com/rhsev/grubber/releases), a small Go binary —
+download it and put it in your `PATH`. `rsync` ships with macOS.
+
+Optional: one of `apex`, `glow` or `bat` for the preview pane (tried in that
+order, `cat` if none are present). `twin doctor` reports what it found.
+
+<details>
+<summary>From source</summary>
 
 ```bash
 git clone https://github.com/rhsev/mark-twin.git
@@ -60,146 +89,235 @@ cd mark-twin
 gem build mark-twin.gemspec
 gem install ./mark-twin-*.gem
 ```
+</details>
 
-### 3. Other tools
-
-Also required in `PATH`: `rsync` (preinstalled on macOS), `fzf`
-(`brew install fzf`). For the stage-2 preview, one of `apex`, `glow`,
-or `bat` is recommended (falls back in that order; `cat` if none are
-present).
+## Getting started
 
-## Quickstart
+**1. Decide where the other side lives.** `Target:` takes either form, and
+neither is the special case:
 
-Twin assumes the target machine is reachable as a mounted volume (typically
-via SMB or NFS). The mount check is enforced before any sync.
+```yaml
+Target: admin@macbook:/Users/admin              # over ssh
+Target: /Volumes/macbook/Users/admin            # a mounted volume (SMB, NFS, …)
+```
 
-1. **Pick a directory for sync-files** (anywhere; this example uses `~/Sync`):
+Over ssh you need key-based login — twin runs `ssh -o BatchMode=yes` and never
+prompts for a password, so set up `ssh-copy-id macbook` first. A mounted volume
+needs no keys but has to be mounted; twin checks before every sync. The
+[comparison below](#mounted-volume-or-ssh) covers the two differences that
+actually matter.
 
-   ```bash
-   mkdir -p ~/Sync
-   ```
+**2. Point twin at a folder for sync-files**, in `~/.config/twin/config.yaml`:
 
-2. **Create the config** at `~/.config/twin/config.yaml`:
+```yaml
+sync_dir: ~/Sync
 
-   ```yaml
-   sync_dir: ~/Sync
-   global_excludes:
-     - .DS_Store
-     - .git/
-   ```
+global_excludes:
+  - .DS_Store
+  - .git/
+```
 
-3. **Drop a sync-file** into `~/Sync`. The simplest starting point is to copy
-   one of the [examples](examples/) and adapt the frontmatter:
+**3. Write a sync-file**, or start from one of the [examples](examples/):
 
-   ```bash
-   cp examples/home.md ~/Sync/
-   $EDITOR ~/Sync/home.md   # edit Source: and Target:
-   ```
+```bash
+mkdir -p ~/Sync
+cp examples/home.md ~/Sync/
+$EDITOR ~/Sync/home.md      # adjust Source: and Target:
+```
 
-4. **Run twin**:
+`twin add ~/.config/fish` does the same interactively, if you prefer prompts to
+an editor — it finds the matching sync-file, derives the relative path,
+suggests excludes for what it sees in the directory, and appends a block with a
+prose stub.
 
-   ```bash
-   twin
-   ```
+**4. Look before you leap:**
 
-   Pick a program, then the paths to sync, hit Enter.
+```bash
+twin status              # what differs
+twin sync --dry-run      # what a sync would do, without doing it
+twin                     # interactive: pick a program, pick paths, Enter
+```
 
-## Usage
+That is the whole loop. Everything below is detail you can come back for.
 
-Twin has two modes: an **interactive interface** (default — see screenshots
-above) and **CLI commands** for status checks and batch sync.
+## Everyday commands
 
 ```bash
-twin                         # TUI — all programs across all sync-files
-twin home.md                 # TUI — one sync-file in sync_dir (by name)
-twin /abs/path/to/file.md    # TUI — any sync-file by absolute path
-twin ./relative/dir/         # TUI — all sync-files in a directory
+twin                         # picker — all programs across all sync-files
+twin home.md                 # picker — one sync-file in sync_dir (by name)
+twin ./some/dir/             # picker — all sync-files in a directory
 twin list                    # plain listing
 twin status                  # listing with source/target mtimes
 twin sync -p grubber         # sync one program by name pattern
 twin sync --file=repos       # sync all programs from a sync-file
 twin sync --dry-run          # preview without writing
-twin doctor                  # check tools, renderers, and sync targets
+twin log                     # recent journal entries (-n N, --json)
+twin doctor                  # check tools, renderers, and targets
 twin --help                  # show usage
 ```
 
-File argument resolution:
-
-- bare name (no `/`)  → looked up by substring in `sync_dir`
-- contains `/`        → resolved as path (absolute or relative); file or directory both work
-
-## Configuration
+A file argument without `/` is matched by substring against sync-file names in
+`sync_dir`; anything containing `/` is treated as a path, file or directory.
 
-`~/.config/twin/config.yaml`:
+Every job is journaled to `~/.local/state/twin/log.jsonl` — one JSON line with
+timestamp, program, path and outcome. `twin sync` exits non-zero if any job
+failed.
 
-```yaml
-sync_dir: /path/to/sync-files
+## Sync-files
 
-global_excludes:
-  - .DS_Store
-  - .git/
+One Markdown file per relationship. Frontmatter sets it up, YAML blocks define
+the individual paths. Frontmatter fields are merged into every block, so
+`Source:`/`Target:` are usually written once at the top — but a block may
+override them, which is how one file can serve several destinations.
 
-# Optional preview rendering (apex):
-# apex_theme: default
-# apex_width: 80
-# apex_code_highlight: monokai
-# apex_code_highlight_theme: dark
-```
+Blocks sharing a `Program` are grouped: they are selected together, synced
+together, and **run in the order they appear in the file**.
 
-Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`, `TWIN_HOST` (which host
-twin runs as — lets one config serve both machines).
+### Field reference
 
-## Sync-files
+Field names are capitalised English. An unknown key is ignored silently and a
+missing `Active` counts as `0`, so a typo shows up as an entry that never syncs
+rather than as an error.
 
-Each Markdown file represents one sync relationship. Frontmatter defines the
-relationship (Source/Target); YAML blocks define individual paths.
+| Field | Where | Meaning |
+|---|---|---|
+| `Program` | block | Group name; blocks sharing it sync together |
+| `Path` | block | Path relative to `Source` (file or directory) |
+| `Source` | either | Absolute base path on this machine |
+| `Target` | either | Absolute base path, or `user@host:/path` for ssh |
+| `Target-Path` | block | Path under `Target`, when it differs from `Path` |
+| `Active` | either | `1` syncs, `0` skips. Default `0` |
+| `Description` | block | Shown in listings and the picker |
+| `Label` | either | Free-text grouping, filterable via `--label` |
+| `Exclude` | block | Comma-separated paths that are not part of the sync |
+| `Own` | block | Comma-separated paths the **target** owns |
+| `Delete` | block | `true` mirrors deletions, with backups |
+| `Cmd` | block | Shell command, run only when bytes actually moved |
+| `Render` | block | `true` substitutes `{{tokens}}` instead of copying |
+
+### Exclude or Own?
+
+Both keep rsync away from a path and both take a comma-separated list
+(`Exclude: *.log, __pycache__/`). What differs is the meaning, and `twin status`
+reports them apart:
+
+- **`Exclude:`** — not part of this sync at all. Build artefacts, logs, caches,
+  `.git/`, a test script with no business on the other machine.
+- **`Own:`** — inside the sync scope, but the **target** owns it.
+  Machine-specific configuration the source must never clobber:
+  `conf.d/local.fish`, `lazy-lock.json`, a per-host credentials file.
+
+The distinction is documentation, not mechanism. Six months on, `Own:` still
+says "deliberate, the other machine maintains this", where the same entry sitting
+in `Exclude:` between `*.dwarf` and `.DS_Store` reads like noise you once
+filtered out.
+
+### Cmd: doing something after a sync
+
+`Cmd` runs a shell command once rsync has actually transferred bytes — a no-op
+sync runs nothing. Typically a `curl` to a local automation endpoint like
+[mi.lan](https://github.com/rhsev/mi.lan), or an `ssh host '…'` for remote
+targets (`Cmd` always runs locally).
+
+It belongs to a block rather than to the program, which is what you want when
+different paths need different follow-ups — reload nginx after its config,
+re-link binaries after `bin/`. For a **restart**, put the command in the
+**last** block: jobs run in file order, so a restart placed earlier brings the
+service back before the remaining paths are written. The same command repeated
+across blocks restarts repeatedly, for the same reason. One command, last block.
+
+### Delete: mirroring removals
+
+`Delete: true` adds `--delete`, so files removed from the source disappear on
+the target too. Deleted and overwritten files are moved to
+`<target>/.twin-backup/<timestamp>/` rather than destroyed — a safety net worth
+pruning occasionally. It applies to `Delete` jobs only.
+
+## Mounted volume or ssh
+
+Both are first-class. `twin status`, the picker, `Exclude`/`Own`, `Delete` and
+`Cmd` behave identically; remote paths are stat'ed in a single ssh round-trip
+per host, and an unreachable host shows as `?` instead of failing the scan.
+
+Two differences are real:
+
+|  | mounted volume | ssh |
+|---|---|---|
+| Setup | volume must be mounted | ssh key (`ssh-copy-id`) |
+| Before syncing | mount check | reachability check |
+| `Render: true` | supported | **not** supported |
 
-See [examples/home.md](examples/home.md) and [examples/repos.md](examples/repos.md)
-for ready-to-adapt templates.
+`Render` needs to read and write file contents on the target, which twin only
+does locally. Keep rendered files on mounted targets, or render locally and sync
+the result.
 
-Minimal example:
+Syncing is push-only in both cases: `Source:` is always this machine.
 
-````markdown
+```markdown
 ---
 Active: 1
-Label: mac-mini → macbook
-Source: /Users/admin
-Target: /Volumes/macbook/Users/admin
+Label: mini → server
+Source: /Volumes/lightning/Git/Website
+Target: ralf@server:/srv/www
 ---
+```
 
-## Fish Shell
+## When the target has changed too
 
-Configuration for the fish shell, including completions and abbreviations.
+A sync has a direction: the source wins. But targets get edited — a quick fix
+made on the server at midnight, a config tweaked where it runs. Twin looks for
+that before it moves the first byte, and asks once for the whole program:
 
-```yaml
-Program: Fish Shell
-Path: .config/fish
-Description: Fish Shell configuration
-Exclude: conf.d/local.fish
 ```
-````
+target has changed since the last sync — 1 file(s) differ:
+  ! app/code.rb (target 2h newer)
+syncing would replace them with the source version.
+
+overwrite these on the target and sync? [y]es / [d]iff / [n]o (abort)
+```
+
+`d` prints a unified diff per file, then asks again. `n` aborts the entire
+program — nothing is written, so you never end up with half a deploy applied.
+
+Two properties make this bearable day to day:
+
+- **Content, not timestamps.** A file that is merely newer on the target with
+  identical bytes is not a conflict and does not ask. Sync a tree in both
+  directions and you collect dozens of those; a prompt that fires on them gets
+  answered without being read.
+- **Directory mtimes are ignored.** Editing a file in place leaves its
+  directory's mtime untouched, and `rsync -a` equalises those anyway. Twin asks
+  rsync what it would actually transfer instead of guessing from a directory.
 
-Frontmatter fields (`Active`, `Label`, `Source`, `Target`) are merged into
-every block by grubber. Multiple blocks can share the same `Program` — twin
-groups them and treats the program as the unit of selection.
+`twin status` is still mtime-based and cannot see an in-place edit. It is the
+cheap overview; `twin sync` is what decides.
 
-The optional `Cmd` field runs an arbitrary shell command after a successful
-sync — typically a `curl` to a local automation endpoint like
-[mi.lan](https://github.com/rhsev/mi.lan) to reload a program, restart a
-service, or notify another machine. The command only runs when rsync actually
-transferred bytes; no-op syncs skip it. See the Helix entry in
-[examples/home.md](examples/home.md).
+## Automation
 
-The optional `Delete: true` field adds `--delete` to the rsync invocation,
-so files removed from the source are also removed on the target. Useful for
-directory syncs where the target should mirror the source exactly.
+For a scheduled run (launchd, cron):
+
+```bash
+twin sync --quiet --skip-unavailable --skip-conflicts
+```
+
+- `--quiet` — only conflicts, errors and jobs that changed something. A no-op
+  run is silent.
+- `--skip-unavailable` — a laptop that isn't docked is skipped, not an error.
+- `--skip-conflicts` — leave target-side changes alone and sync the rest.
+  Use `--force` instead to overwrite them.
+
+Without a terminal and without one of those two flags, a real conflict aborts
+the run with exit code 1 rather than picking an answer for you. Output and a
+non-zero exit therefore mean something genuinely needs attention — which is
+what launchd's logging wants. The journal records every job regardless.
 
 ## Templating
 
-Some configs differ per machine — a LaunchAgent plist that points at
-`/Volumes/lightning/…` on one Mac and `/Users/ralf/…` on another, a
-`settings.json` with a device-specific id. Those used to fall out of twin and
-get hand-maintained. Templating folds them back into one source of truth.
+*Skip this until you hit the problem it solves.*
+
+Some configs differ per machine — a LaunchAgent plist pointing at
+`/Volumes/lightning/…` on one Mac and `/Users/ralf/…` on another. Those used to
+fall out of twin and get hand-maintained.
 
 Define a host table in `~/.config/twin/config.yaml`:
 
@@ -230,9 +348,8 @@ The distinction matters: a file *written* to the mount (`/Volumes/ralf/…`) but
 
 `Render: true` turns a block from copy into *render*: twin reads the source as a
 template, substitutes `{{…}}` in its **content**, and writes the result only if
-it differs from the current target (so a `Cmd` hook fires only on a real change).
-`Target-Path:` overrides the target-side relative path when it differs from the
-source layout:
+it differs from the current target, so a `Cmd` hook fires only on a real change.
+`Target-Path:` overrides the target-side relative path:
 
 ````markdown
 ## LiveSync LaunchAgent
@@ -248,15 +365,35 @@ Cmd: curl -s http://mi.lan/livesync-reload
 ```
 ````
 
-`twin doctor` checks that every `{{token}}` across your sync-files resolves, and
-`twin status` compares rendered output by content (not mtime). Without a `hosts`
-table, templating is inert and literal-path sync-files behave exactly as before.
+`twin doctor` checks that every `{{token}}` resolves, and `twin status` compares
+rendered output by content rather than mtime. Without a `hosts` table,
+templating is inert and literal-path sync-files behave exactly as before.
+
+## Configuration
+
+`~/.config/twin/config.yaml`:
+
+```yaml
+sync_dir: /path/to/sync-files
+
+global_excludes:
+  - .DS_Store
+  - .git/
+
+# Optional preview rendering (apex):
+# apex_theme: default
+# apex_width: 80
+# apex_code_highlight: monokai
+# apex_code_highlight_theme: dark
+```
+
+Environment overrides: `TWIN_SYNC_DIR`, `TWIN_CONFIG`, `TWIN_HOST` (which host
+twin runs as — lets one config serve both machines).
 
 ## Design
 
-Sync instructions and context in one place — the same Markdown file holds
-both the `Path:` directives and the prose explaining them. No TUI framework:
-`fzf` does the interactive part, `apex` the rendering.
+Sync instructions and their context in one place. No TUI framework: `fzf` does
+the interactive part, `apex` the rendering, `rsync` the work.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for the data model and internals.
 
@@ -265,3 +402,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the data model and internals.
 ```bash
 rake test
 ```
+
+---
+
+*Part of a family of plain-text tools — the [profile page](https://github.com/rhsev) has the map.*