@narumitw/pi-sync 0.49.14 → 0.50.0

package/README.md

@@ -2,19 +2,18 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-sync)](https://www.npmjs.com/package/@narumitw/pi-sync) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-Sync selected Pi settings and content across machines through Git, WebDAV, Cloudflare R2, or another S3-compatible store.
-
-Reusable storage connections hold credentials, while named sync setups define the exact remote path, included content, and automatic-sync behavior.
+Pi Sync synchronizes selected Pi settings and content across machines through Git, WebDAV, Cloudflare R2, or another S3-compatible store.
+Reusable storage connections hold credentials, while named sync setups define exactly what to sync, where to store it, and whether to sync automatically.
 
 ## ✨ Features
 
-- Manages Git, WebDAV, Cloudflare R2, and general S3-compatible backends through `/sync`.
-- Separates reusable storage connections from named sync setups and exact reviewed remote paths.
-- Selects Pi roots, safe agent-relative paths, and the privacy-sensitive sessions root through one ordered include list.
+- Manages Git, WebDAV, Cloudflare R2, and general S3-compatible storage through `/sync`.
+- Separates reusable storage connections from named setups with exact reviewed remote paths.
+- Uses one ordered list for Pi roots, safe agent-relative paths, and privacy-sensitive sessions.
 - Protects changes with immutable snapshots, secret scanning, locks, conflict checks, pull backups, transactional apply, and recovery journals.
-- Keeps snapshot selection portable and credential-free across environments.
+- Keeps snapshot selection portable and free of credentials.
 - Writes settings atomically, preserves unknown fields, rejects stale edits, and fails closed on unsafe configuration.
-- Loads a generated split runtime while preserving lazy UI and backend chunks.
+- Loads a generated split runtime with lazy UI and backend chunks.
 
 ## 📦 Install
 
@@ -35,56 +34,78 @@ npm --workspace @narumitw/pi-sync run build
 pi -e ./packages/pi-sync
 ```
 
-The package declares `dist/index.ts`, so the build command must finish before Pi loads the local package directory.
+The package declares `dist/index.ts`, so an unbuilt checkout must run the build before Pi loads the package directory.
 
-An unbuilt checkout still declares `dist/index.ts`, but the generated entrypoint and chunks do not exist until the build completes.
+Extensions run with Pi's permissions, so install only packages from sources you trust.
 
 ## 🚀 Quick start
 
-Run `/sync`, choose **Set up sync**, and review the storage connection, exact remote path, included content, automatic-sync choice, and masked credentials before saving.
+Run `/sync` and choose **Set up sync**.
+Name the setup once; its first storage connection uses the same name.
+Input prompts show examples or an explicit default that you can accept by submitting an empty value; cancelling never accepts a default.
+Remote URLs, endpoints, usernames, and credentials require your own values, not the displayed examples.
+All new setups default to storage path `./`: the Git repository root, the WebDAV collection URL, or the selected R2/S3 bucket root.
+Git also suggests branch `main`.
+Use different folders or prefixes for independent setups sharing a WebDAV collection or bucket; existing settings and paths are unchanged.
+If another configured setup already uses the chosen location, setup asks for a different path before the content selection and review; Git requires a different branch, even when the directory differs.
+Every new setup asks for included content and automatic sync; automatic sync is off unless you enable it. Recommended includes nine Pi roots; Minimal includes `settings.json` and `AGENTS.md`. Sessions stay off unless explicitly included with a privacy acknowledgement.
+Before saving, scroll through the exact destination, every included path, automatic-sync choice, and hidden-credential summary. R2/S3 always asks for an existing bucket; an example bucket name is not a default.
+
+Invalid fields ask for a correction without restarting setup. A temporary local save failure keeps the review for another Save; changed settings require reopening and reviewing the current values. Saving only changes local settings, not remote data. A connection saved through **Add a new storage connection…** remains saved if you later cancel the setup.
+
 Buckets and remote repositories must already exist.
 Git uses existing non-interactive SSH or credential-helper configuration and never stores Git credentials.
+It owns the entire selected branch: use an empty repository or a new branch if `main` already contains unrelated content.
+At `./`, Git stores `manifest.json` and `files/` at the repository root; it does not modify your local working tree.
+WebDAV and R2/S3 store `latest.json`, `history.json`, and `snapshots/` directly under their selected root, not under a literal `./` prefix.
 
 ## 🧭 Manager, conflicts, and recovery
 
-The manager shows local state without contacting remote storage:
+The `/sync` manager shows local state without contacting remote storage:
 
 ```text
 Current sync setup: home
 Storage: Cloudflare R2 · r2 · personal-pi
 Included: 5 built-in groups · 0 extra files · Sessions off
-Automatic sync: On
+Automatic sync: On (startup check; shutdown pushes selected content if sessions included)
 Remote status: Not checked
 ```
 
 Primary actions include **Sync now**, **Switch sync setup**, **Status & changes**, **Settings**, and **More…**.
-When pi-sync has already detected a synced-content-list mismatch, the manager instead shows **Sync status: Review needed**, puts **Review synced content (recommended)** first, and keeps **Sync now** visibly unavailable until the choice is reviewed.
-Opening the manager still performs no new remote request.
-The standard manager also owns setup and connection lists/details plus history and recovery.
-Secondary screens provide **Back**; Escape goes back and Ctrl+C closes the flow.
-Specialized operation and masked-credential prompts show the effective cancellation bindings and retain Ctrl+C as a hard-cancel input when Back is remapped.
-Destructive, credential-bearing, and externally visible operations retain exact specialized previews and confirmations.
+
+After Pi Sync detects an included-content mismatch, the manager shows **Sync status: Review needed** and puts **Review synced content (recommended)** first.
+**Sync now** remains unavailable until you review the mismatch.
+Opening the manager does not make another remote request.
+Under **More…**, **Storage connections** holds reusable server addresses and sign-in details; **Sync setups** holds content, destination, and automatic-sync choices. **Edit storage location…** changes only bucket, branch, or path, not the connection or included content. Use **Settings** for the current setup's content and automatic sync; make another setup current before changing those settings.
+
+**More… → Check setup** (also `/sync doctor`) reports configuration and backend-specific access checks. S3/R2 performs a read-only request: success does not prove write access or snapshot validity, and an ambiguous 404 does not prove a bucket is missing. Check the indicated credentials, address, bucket, or path before retrying. Git checks remote reads and the local cache, not write access. WebDAV uses an isolated write/cleanup probe and repairs the active snapshot's history entry if missing. The existing **History & recovery** route remains available.
+
+On secondary menus, **Back** and Escape return to the previous screen. In setup inputs and save reviews, cancellation (including Ctrl+C) discards the current unsaved draft and returns to its owning menu. Session replacement or shutdown closes the owning flow.
+Specialized operation and masked-credential prompts show the effective cancellation bindings and keep Ctrl+C as a hard-cancel input when Back is remapped.
+Destructive, credential-bearing, and externally visible operations show exact previews and confirmations.
 
 ### Restore sync access
 
-When an operation is currently running, the manager shows its command and process ID, keeps sync and settings changes unavailable, and puts **Refresh operation status** first.
-When lock metadata is still protected by an active guard, the manager explains that another pi-sync process may be starting or finishing and asks the user to wait before refreshing.
+While an operation is running, the manager shows its command and process ID, disables sync and settings changes, and puts **Refresh operation status** first.
+When an active guard still protects lock metadata, the manager asks you to wait because another Pi Sync process may be starting or finishing.
 It never offers lock removal while an owner or guard may still be active.
 
-When a previous operation appears to have stopped without releasing its local lock, the manager shows **Sync paused** and puts **Restore sync access… (recommended)** first instead of hiding recovery inside **History & recovery…**.
-Unreadable metadata receives a stronger warning because pi-sync cannot verify who owns it.
-Close every other Pi session that may still be syncing, review the local-lock-only confirmation, then choose **Remove local lock and continue**.
-The guarded recovery path rechecks metadata and ownership before removal, changes no settings, local files, sync state, or remote data, and returns directly to the normal manager when access is restored.
+If a stopped operation leaves its local lock behind, the manager shows **Sync paused** and puts **Restore sync access… (recommended)** first.
+Unreadable metadata receives a stronger warning because Pi Sync cannot verify its owner.
+Close every other Pi session that may still be syncing, review the local-lock-only confirmation, and choose **Remove local lock and continue**.
+Before removal, the guarded recovery path rechecks metadata and ownership.
+
+Successful recovery changes no settings, local files, sync state, or remote data and returns to the normal manager.
 Cancellation leaves the lock unchanged.
-If ownership changes or a guard is still expiring, pi-sync refuses removal and keeps actionable status available for refresh or retry.
-The deterministic fallback remains `/sync unlock --stale` after the same no-other-sync verification.
+If ownership changes or a guard is still expiring, Pi Sync refuses removal and keeps refresh or retry available.
+After the same no-other-sync verification, `/sync unlock --stale` provides a deterministic fallback.
 
 ### Resolve conflicts in the manager
 
-When **Sync now**, **Pull from remote…**, or **Push to remote…** finds changes that require a human direction choice, the manager opens **Resolve sync conflict** instead of ending at a command-only error.
-The flow names the current sync setup and explains whether local content, remote content, or the included-content policy changed.
+When **Sync now**, **Pull from remote…**, or **Push to remote…** requires a direction choice, the manager opens **Resolve sync conflict**.
+The flow names the current setup and explains whether local content, remote content, or the included-content policy changed.
 
-An explicit remote content-list mismatch now opens **Synced content differs** inside the same manager flow.
+An explicit remote content-list mismatch opens **Synced content differs** in the same manager flow.
 Nothing changes until you choose an action.
 Choose **Review all paths (recommended)** first to compare exact remote-only paths, device-only paths, and both ordered lists.
 If membership matches but order differs, the review says that only ordering differs.
@@ -96,13 +117,12 @@ Then choose one action:
 - **Keep this device's content list and update remote…** opens the existing `push --force` preparation and exact confirmation without `--yes`.
   Cancelling preparation or confirmation returns to the content-list choice without changing remote data.
 - **Cancel** returns to the manager without changing settings, files, remote data, or sync state.
-- **Later** appears when automatic startup sync detected the mismatch and returns immediately to the Pi editor without changing anything.
 
 Choose **Review differences (recommended)** in an ordinary file-direction conflict to inspect the exact affected paths without changing local files, remote data, or sync state.
 Then choose one reviewed direction:
 
 - **Keep local content and replace remote…** uses the existing forced-push path.
-  It scans managed local files for secrets, shows the exact remote publication effect, re-reads a changed remote head, and asks again if the reviewed plan changed.
+  It applies the [secret-scan setting](./docs/settings.md#secret-scanning), shows the exact remote publication effect, re-reads a changed remote head, and asks again if the reviewed plan changed.
 - **Use remote content and replace local…** uses the existing forced-pull path.
   It shows exact local writes and deletions, protects the live session, and creates a local backup before applying.
 - First sync uses **Use local as initial source…** and **Use remote as initial source…** labels.
@@ -111,77 +131,51 @@ Then choose one reviewed direction:
 Cancelling a preparation or confirmation returns to conflict resolution with no side effects.
 Back returns to the sync manager, and Ctrl+C closes the complete flow.
 
-When automatic startup sync detects an explicit content-list mismatch in TUI mode, it opens **Synced content differs** once for that session instead of ending at a warning.
-Choosing **Later** or closing the flow leaves a compact **Pi Sync needs review** widget above the editor and a **review needed** footer status.
-The attention state is in memory only, contains no credentials or file contents, and is revalidated before any settings or remote mutation.
-It clears after verified resolution, invalidation, session replacement, or shutdown.
+Startup checks never open a dialog. Detected changes leave a compact hint above the editor; open `/sync` when ready. An included-content mismatch puts **Review synced content (recommended)** in the manager, where a fresh review verifies the remote snapshot before offering changes.
+Check results are advisory observations against the last sync baseline, not proof of a file conflict or current equality. Opening the manager uses local information and shows when the check completed; it does not contact remote storage. Transfer actions recheck current content.
+Attention stays in memory and is invalidated by relevant settings/state changes or a foreground transfer's commit boundary, and cleared on session replacement or shutdown. Cancelling a review or a failure before commit preserves a still-valid hint.
 
 Interactive TUI `/sync sync`, `/sync pull`, and `/sync push` routes without `--yes` open the same review flow when they detect the mismatch.
 Explicit `--yes` routes remain non-interactive and report exact remote-only, device-only, or order-only guidance while leaving visible attention for later review.
 Shutdown automatic sync never opens a dialog because Pi is exiting.
-RPC startup and direct routes remain read-only and notification-based, while print and JSON modes remain unsupported for `/sync` because their UI output is not observable.
+RPC startup check results use nonblocking notifications; included-content review remains read-only.
+Print and JSON modes do not support `/sync` because UI output is not observable there.
 
 ## ⚙️ Settings
 
-The canonical private user file is:
+Run `/sync` → **Set up sync** to create the canonical private user file at `<getAgentDir()>/pi-sync.json` (normally `~/.pi/agent/pi-sync.json`).
+Use **Settings** to manage an existing setup.
+Missing settings stay unconfigured without creating files or locks.
 
-```text
-~/.pi/agent/pi-sync.json
-```
+### Background startup checks
+
+With **Automatic sync** enabled, session startup schedules a background check instead of waiting for a transfer. Pi remains usable while Git, WebDAV, R2, or S3 checks local hashes and remote metadata. Unchanged results are quiet; changes or failures provide `/sync` guidance without opening a dialog. Use **Sync now** to start a reviewed transfer, or `/sync status` to retry a check. Foreground `/sync` cancels and drains the background check before starting.
+
+Checks run once per session start, including `/reload`, new, resumed, and forked sessions, in TUI and RPC only. Print/JSON skip startup checks. There is no polling or automatic check retry loop. The overall deadline is 30 seconds, followed by underlying cleanup where needed; Git process termination and temporary-ref cleanup can take additional time. Git checks can still fetch objects and update the extension's private bare cache, but never push, apply managed files, update the sync baseline, or reload Pi.
 
-Pi's configured agent directory replaces `~/.pi/agent` when applicable.
-Missing settings load as unconfigured without creating an agent directory, file, temporary, or lock.
-An explicit setup creates the file atomically.
-On POSIX, pi-sync creates and replaces it with mode `0600`.
-Pi-sync processes coordinate settings access through `pi-sync.json.mutation-lock`; lock-unaware editors are outside that serialization boundary and should not save the file while a pi-sync settings operation is running.
-Credentials stay in this canonical private file and are never shown in menus, reviews, status, notifications, errors, logs, or completion metadata.
+**Compatibility change:** the existing `sync.automatic` boolean and Off default are unchanged, but On no longer performs startup push/pull. Startup is not guaranteed to use the latest remote content. Local transaction recovery remains an awaited safety barrier and can restore interrupted file changes before use; existing legacy settings-file initialization is also retained.
 
-An existing private `pi-sync.local.json` containing a valid version 3 document is copied byte-for-byte to `pi-sync.json`; the old file remains as a recovery copy.
-If both paths exist, `pi-sync.json` wins and the other path remains untouched.
+Shutdown behavior is unchanged: when **Automatic sync** is On and sessions are included, pi-sync can automatically push the selected content, not only session files. This also applies to headless modes; shutdown never opens a dialog, and `/reload` skips this push. Turning the setting Off disables both future startup checks and automatic shutdown pushes.
 
-### Complete version 3 example
+**Settings → Skip secret scan (all setups)** defaults to **Off**; enable it only after reviewing the destination and selected content because it disables push scanning for every setup.
+See [Secret scanning](./docs/settings.md#secret-scanning) for the setting and diagnostic behavior.
+
+A minimal Git setup uses an existing private remote and keeps automatic sync off:
 
 ```json
 {
   "version": 3,
   "activeSyncSetup": "home",
   "onSwitch": "ask-before-pull",
+  "skipSecretScan": false,
   "storageConnections": {
-    "r2": {
-      "type": "s3",
-      "endpoint": "https://example.r2.cloudflarestorage.com",
-      "region": "auto",
-      "credentials": {
-        "accessKeyId": "<access-key-id>",
-        "secretAccessKey": "<secret-access-key>"
-      }
-    },
     "github": {
       "type": "git",
       "remote": "git@github.com:owner/private-pi-sync.git"
-    },
-    "nextcloud": {
-      "type": "webdav",
-      "url": "https://cloud.example.com/remote.php/dav/files/user",
-      "credentials": {
-        "username": "user",
-        "password": "<app-password>"
-      }
     }
   },
   "syncSetups": {
     "home": {
-      "storage": {
-        "connection": "r2",
-        "bucket": "personal-pi",
-        "path": "pi-sync/home"
-      },
-      "sync": {
-        "include": ["settings.json", "AGENTS.md", "skills", "prompts", "themes"],
-        "automatic": true
-      }
-    },
-    "git-backup": {
       "storage": {
         "connection": "github",
         "branch": "pi-sync/home",
@@ -191,136 +185,53 @@ If both paths exist, `pi-sync.json` wins and the other path remains untouched.
         "include": ["settings.json", "AGENTS.md"],
         "automatic": false
       }
-    },
-    "webdav-backup": {
-      "storage": {
-        "connection": "nextcloud",
-        "path": "pi-sync/home"
-      },
-      "sync": {
-        "include": ["settings.json", "sessions"],
-        "automatic": false
-      }
     }
   }
 }
 ```
 
-Cloudflare R2 is persisted as `"type": "s3"`; R2 is a setup preset, not another schema type.
-Temporary S3 credentials may additionally include `credentials.sessionToken`.
-
-### Required backend shapes
-
-- **S3/R2 connection:** `type`, `endpoint`, `region`, and `credentials.accessKeyId` / `credentials.secretAccessKey`.
-- **S3/R2 setup storage:** `connection`, `bucket`, and complete relative `path`; `branch` is rejected.
-- **Git connection:** `type` and a credential-free SSH or HTTPS `remote`.
-- **Git setup storage:** `connection`, `branch`, and complete repository `path`; `bucket` is rejected.
-- **WebDAV connection:** `type`, HTTPS `url`, and `credentials.username` / `credentials.password`.
-- **WebDAV setup storage:** `connection` and complete relative `path`; `bucket` and `branch` are rejected.
-
-Every setup requires `sync.include` and explicit `sync.automatic`.
-`activeSyncSetup` must reference an own-property setup when any setups exist and must be absent when the setup catalog is empty.
-A referenced connection cannot be removed.
-The current setup must be switched before removal.
-Two setups cannot resolve to the same normalized backend location.
-
-`onSwitch` accepts:
-
-- `ask-before-pull` — switch, then ask in TUI whether to start a reviewed pull;
-- `pull-after-switch` — require observable UI and start the normal reviewed pull;
-- `switch-only` — switch without reading or applying remote content.
-
-### Included content
-
-`sync.include` is ordered and duplicate-free.
-Supported Pi roots are:
-
-```text
-settings.json, keybindings.json, models.json, AGENTS.md, APPEND_SYSTEM.md,
-skills, prompts, themes, extensions, sessions
-```
-
-Safe agent-relative custom files or directories may also be included.
-Absolute paths, `..`, backslashes, controls, denied secret/settings paths, duplicate case variants, and ambiguous nested paths under reserved roots are rejected.
-
-An empty array is valid.
-It means no useful transfer is selected: **Sync now** reports the condition and does not claim that the setup is up to date.
-Unselected content remains unmanaged locally and is preserved when republishing existing remote snapshots.
-
-The Included Content editor is a standard bounded multi-select backed by one in-memory draft.
-Toggles never write settings.
-**Add custom path…** accepts a safe agent-relative file or directory even when it does not exist locally yet, allowing a new environment to select content that exists only in the remote snapshot.
-Leaving the editor opens an exact Include/Exclude review with **Save changes**, **Discard changes**, and **Continue editing**; only reviewed Save publishes, while Continue preserves the draft and Discard/cancellation preserves the settings bytes.
-RPC remains a read-only summary with the manual `sync.include` path.
-
-Every new snapshot stores the normalized included-content selection separately from the files that happened to exist.
-This preserves selected-but-missing paths without syncing `pi-sync.json`, storage credentials, automatic-sync preferences, or setup names.
-**Settings → Compare synced content** opens the same review-first flow as a manager operation when local and remote lists differ.
-Adoption revalidates the remote head, immutable snapshot, reviewed storage coordinates, and local include list before one atomic settings update.
-The saved state changes only `sync.include`, preserves unknown settings fields, and never pulls files or writes sync state.
-Its explicit Continue action starts a fresh **Sync now** route, while **Done** leaves the reviewed settings change saved without implying a file operation.
-Keeping this device's list opens the reviewed force-push path and explicitly replaces the remote policy while preserving eligible unmanaged remote files.
-
-Automatic sync and pull, including forced pull, pause on an explicit remote-policy difference rather than silently expanding local scope.
-Status reports matches and exact local-only/remote-only paths.
-Old snapshots remain readable.
-Because they have no authoritative selection, pi-sync offers only a clearly labeled read-only partial discovery from safe remote file roots; selected-but-missing and preserved-unmanaged intent cannot be reconstructed.
-Use **Add custom path…** for any needed path.
-
-Adding `sessions` requires a privacy acknowledgement in interactive flows.
-Session JSONL can contain prompts, tool output, file paths, images, and secrets.
-Automatic apply protects the currently open session file; restart Pi or resume a pulled session to use newly synchronized conversations.
-
-### Unsupported old settings and recovery
-
-Version 1, version 2, and non-empty unversioned documents are intentionally unsupported by this breaking schema reset. pi-sync does **not** migrate, partially interpret, downgrade, or overwrite them.
-Automatic sync pauses and reports an actionable version 3 error without displaying secrets.
-
-Recovery:
-
-1. retain the old file byte-for-byte;
-2. move it aside manually;
-3. create a new version 3 document or run the setup manager;
-4. run `/sync doctor`, inspect the exact storage path, and review the first pull or push;
-5. restore the retained file and a compatible older package only if rolling back.
-
+Setup saves are atomic and private (`0600` on POSIX), preserve unknown fields, and coordinate across pi-sync processes.
+Do not save from a lock-unaware editor during a pi-sync settings operation.
 Malformed, invalid, unsupported, symlinked, or concurrently changed documents remain untouched.
-Failed UI saves keep the previous file and displayed/effective state.
+Version 1, version 2, and non-empty unversioned settings require manual recovery rather than automatic migration.
 
-## 💬 Commands
+Adding `sessions` can upload prompts, tool output, paths, images, and secrets; interactive flows require a privacy acknowledgement.
+Startup checks report included-content differences without changing anything. Transfers retain their existing included-content policy checks instead of silently expanding local scope.
 
-The menu is preferred, while deterministic routes remain available:
+Read the [settings reference](./docs/settings.md) for complete S3/R2, Git, and WebDAV examples, backend fields, included-content rules, legacy paths, and recovery steps.
 
-```text
-/sync help
-/sync use <setup>
-/sync init
-/sync config [--setup <name>]
-/sync files [--setup <name>]
-/sync status [--setup <name>]
-/sync diff [--setup <name>]
-/sync doctor [--setup <name>]
-/sync push [--setup <name>]
-/sync pull [--setup <name>]
-/sync sync [--setup <name>]
-/sync history [--setup <name>]
-/sync rollback <snapshot-id> [--setup <name>]
-/sync migrate-state [--yes]
-/sync unlock --stale
-```
-
-- `--setup <name>` addresses a setup without switching it.
-- `--yes` / `-y` skips a direct route's confirmation.
-- `--force` accepts a reviewed content conflict but never disables backend concurrency protection.
-- `--stale` requests guarded stale-lock recovery.
-
-The former version 2 setup-addressing flag is rejected.
-Unknown flags, unknown commands, trailing values, and missing setup/snapshot values are rejected.
-Completion includes known setup names and preserves preceding command tokens.
+## 💬 Commands
 
-TUI mode uses standard manager, settings, resource, and included-content screens plus specialized secret, wizard, confirmation, and commit-aware loader components.
-RPC uses Pi's supported dialog/notification protocol and does not gain settings mutation.
-Print and JSON modes never enter TUI-only screens; unsupported interactive routes reject or remain protocol-safe rather than relying on no-op output.
+| Command | Purpose |
+| --- | --- |
+| `/sync` | Set up storage, manage synced content, and review sync operations or recovery. |
+| `/sync help` | Show command usage. |
+| `/sync use <setup>` | Switch the active local sync setup, following its switch policy. |
+| `/sync init` | Create a local configuration template. |
+| `/sync config` | Show resolved configuration. |
+| `/sync files` | List included local files. |
+| `/sync status` | Compare local and remote snapshot state. |
+| `/sync diff` | Show local and remote differences. |
+| `/sync doctor` | Check configuration, connectivity, and backend safety. |
+| `/sync push` | Publish local content to remote storage. |
+| `/sync pull` | Back up local content, then apply the remote snapshot. |
+| `/sync sync` | Choose a safe sync direction or require conflict review. |
+| `/sync history` | Browse remote snapshots and review a rollback. |
+| `/sync rollback <snapshot-id>` | Back up local content, apply a historical snapshot, and republish it remotely. |
+| `/sync migrate-state` | Migrate the legacy local state directory. |
+| `/sync unlock --stale` | Recover an abandoned local lock after guarded ownership checks. |
+
+All routes support TUI and RPC; RPC settings and included-content screens are read-only.
+Print and JSON modes reject `/sync`.
+Unknown commands or flags, trailing values, and missing setup/snapshot values are rejected, including the former version 2 setup-addressing flag.
+
+- `--setup <name>` targets a setup without switching it on `config`, `files`, `status`, `diff`, `doctor`, `push`, `pull`, `sync`, `history`, and `rollback`.
+- `--yes` (alias: `-y`) skips confirmation on `push`, `pull`, `sync`, `rollback`, and `migrate-state`; use only after reviewing the affected content.
+- `--force` lets `push` or `pull` accept content conflicts without disabling backend concurrency protection. It is also accepted by `sync`, which still requires a direction choice for divergent content, and by `rollback`, where it has no additional effect.
+- `--stale` is accepted only by `unlock` and is required to remove a stale lock.
+
+Push and rollback publish data externally; pull and rollback can replace or delete local managed files.
+Review [Settings](#-settings) for included-content privacy and [Manager, conflicts, and recovery](#-manager-conflicts-and-recovery) before forcing a direction, skipping confirmation, or removing a lock.
 
 ## 🔄 Backend and recovery model
 
@@ -337,7 +248,7 @@ The private bare cache under `<agent-dir>/pi-sync/git/` is rebuildable.
 
 WebDAV requires HTTPS except loopback tests.
 URL credentials, query strings, fragments, unsafe redirects, weak/missing ETags, and ignored conditional headers fail closed.
-`/sync doctor` verifies collection and conditional-write behavior with an isolated probe.
+`/sync doctor` verifies collection and conditional-write behavior with an isolated probe, then repairs a missing active-snapshot history entry.
 
 S3/R2 stages immutable bundles, rechecks the visible head before publication, and verifies afterward.
 Unlike Git/WebDAV, generic S3 does not provide an atomic compare-and-swap for `latest.json`; status review remains important for simultaneous writers.
@@ -357,7 +268,7 @@ Preserve both roots before manual recovery; with every Pi process closed and no
 ## 🔒 Security and privacy
 
 - Canonical, legacy, temporary, and recovery settings paths are denied from snapshots; both `pi-sync/` and `.pisync/` state roots are permanently denied.
-- Push scans managed local content for common secret patterns.
+- Push scans managed local content for common secret patterns unless the user explicitly enables **Skip secret scan**; `/sync doctor` always retains the diagnostic scan.
 - Remote snapshot references, checksums, paths, manifests, response sizes, and publication revisions are validated.
 - Symlink parents, path escapes, duplicate paths, and unsafe file/directory replacement fail before local mutation.
 - Live locks block mutation; stale recovery rechecks process and guard ownership.
@@ -365,59 +276,41 @@ Preserve both roots before manual recovery; with every Pi process closed and no
   Publication/apply commit boundaries finish with bounded signals and report ambiguous outcomes explicitly.
 - Terminal-bound names, paths, metadata, and errors are control-character sanitized.
 
-## ♿ Conditional terminal accessibility smoke
+## ♿ Terminal accessibility
 
-Pi exposes terminal components rather than a semantic/ARIA tree.
-Release validation checks textual state, keyboard operation, Escape/Back, control escaping, and narrow rendering.
-Critical meaning appears in text such as `(current)`, `Review needed`, `Later`, `Warning`, `Invalid`, `Saved`, `Cancelled`, and `Applied`; color is supplementary.
-The attention widget is informational and does not pretend to be a clickable control.
+Pi exposes terminal components rather than a semantic or ARIA tree.
+Release checks cover textual state, keyboard operation, Escape and Back behavior, control escaping, and narrow rendering.
+Critical meaning appears in text such as `(current)`, `Review needed`, `No startup transfer`, `Warning`, `Invalid`, `Saved`, `Cancelled`, and `Applied`.
+Color is supplementary, and the attention widget is informational rather than interactive.
 
 ## 🗂️ Package layout
 
 ```text
 packages/pi-sync/
-├── dist/                    # Generated split TypeScript runtime loaded through Pi's Jiti loader
-├── scripts/
-│   └── build-runtime.mjs    # Deterministic bundler and eager-boundary validator
 ├── src/
-│   ├── index.ts
-│   ├── sync-extension.ts      # Lightweight Pi entry runtime and cached lazy loaders
-│   ├── sync.ts                # Compatibility barrel for package-local helpers
-│   ├── sync-errors.ts         # Lightweight setup/decision error contracts
-│   ├── config.ts
-│   ├── config-file.ts
-│   ├── state-directory.ts
-│   ├── settings-management.ts
-│   ├── manager-ui.ts
-│   ├── manager-state.ts
-│   ├── manager-recovery.ts
-│   ├── operation-availability.ts
-│   ├── manager-attention.ts
-│   ├── sync-attention.ts
-│   ├── storage-connections-ui.ts
-│   ├── sync-setups-ui.ts
-│   ├── file-selection.ts
-│   ├── remote-selection-ui.ts
-│   ├── remote-snapshot.ts
-│   ├── sync-operations.ts
-│   ├── sync-backend.ts
-│   ├── backend-factory.ts      # lazy selected-backend loader
-│   ├── s3-backend.ts
-│   ├── webdav-backend.ts
-│   ├── git-backend.ts
-│   ├── snapshot-paths.ts      # Eager recovery-safe session path helpers
-│   ├── snapshot.ts            # Loaded only for snapshot operations/session push
-│   └── *.ts
-├── test/
-├── README.md
-├── LICENSE
-└── package.json
+│   ├── index.ts                       # Thin Pi entrypoint
+│   ├── sync-extension.ts              # Registration and session lifecycle ownership
+│   ├── commands/                      # Parsing, execution, and attention dispatch
+│   ├── settings/                      # Schema, validation, resolution, and persistence
+│   ├── sync/                          # Queries, mutations, policy, and lazy loaders
+│   ├── snapshot/                      # Collection, session paths, apply, and recovery
+│   ├── backends/                      # Contract and Git, S3, and WebDAV transports
+│   ├── state/                         # Sync-state persistence, locks, and migration
+│   └── ui/                            # Manager, settings, reviews, and setup flows
+├── dist/                              # Generated Jiti runtime
+├── scripts/build-runtime.mjs          # Runtime builder
+├── docs/                              # Published reference documentation
+└── test/                              # Behavior and lifecycle coverage
 ```
 
+The generated runtime is built from `src/index.ts` and does not import back into `src`.
+Internal modules use direct imports from their owners; `src/sync.ts` and `src/types.ts` retain compatibility exports.
+Backend transports do not depend on UI, and first-use operation and setup implementations remain lazy.
+
 ## 🔎 Keywords
 
 Pi extension, Pi coding agent, settings sync, Git, WebDAV, Nextcloud, Cloudflare R2, S3-compatible storage, storage connections, sync setups, snapshot sync, dotfiles sync.
 
 ## 📄 License
 
-MIT
+[MIT](./LICENSE)

package/dist/chunks/chunk-2B2ELUF5.ts

@@ -0,0 +1,29 @@
+// @generated by scripts/build-runtime.mjs; do not edit.
+// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
+
+// src/sync/sync-errors.ts
+var SetupPullRequiresUiError = class extends Error {
+};
+var SyncDecisionRequiredError = class extends Error {
+  decision;
+  constructor(decision) {
+    super(decision.directMessage);
+    this.name = "SyncDecisionRequiredError";
+    this.decision = decision;
+  }
+};
+function isSyncDecisionRequiredError(error) {
+  return error instanceof SyncDecisionRequiredError;
+}
+function errorMessage(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");
+}
+
+export {
+  SetupPullRequiresUiError,
+  SyncDecisionRequiredError,
+  isSyncDecisionRequiredError,
+  errorMessage
+};
+//# sourceMappingURL=chunk-2B2ELUF5.ts.map

package/dist/chunks/chunk-2B2ELUF5.ts.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sync/sync-errors.ts"],
+  "sourcesContent": ["import type { SyncDecision } from \"./sync-decision.js\";\n\nexport class SetupPullRequiresUiError extends Error {}\n\nexport class SyncDecisionRequiredError extends Error {\n\treadonly decision: SyncDecision;\n\n\tconstructor(decision: SyncDecision) {\n\t\tsuper(decision.directMessage);\n\t\tthis.name = \"SyncDecisionRequiredError\";\n\t\tthis.decision = decision;\n\t}\n}\n\nexport function isSyncDecisionRequiredError(error: unknown): error is SyncDecisionRequiredError {\n\treturn error instanceof SyncDecisionRequiredError;\n}\n\nexport function errorMessage(error: unknown) {\n\tconst message = error instanceof Error ? error.message : String(error);\n\t// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.\n\treturn message.replace(/[\\u0000-\\u001f\\u007f-\\u009f]/gu, \"?\");\n}\n"],
+  "mappings": ";;;;AAEO,IAAM,2BAAN,cAAuC,MAAM;AAAC;AAE9C,IAAM,4BAAN,cAAwC,MAAM;AAAA,EAC3C;AAAA,EAET,YAAY,UAAwB;AACnC,UAAM,SAAS,aAAa;AAC5B,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EACjB;AACD;AAEO,SAAS,4BAA4B,OAAoD;AAC/F,SAAO,iBAAiB;AACzB;AAEO,SAAS,aAAa,OAAgB;AAC5C,QAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAErE,SAAO,QAAQ,QAAQ,kCAAkC,GAAG;AAC7D;",
+  "names": []
+}