@narumitw/pi-sync 0.49.13 → 0.49.15

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,19 +34,21 @@ 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**.
+Before saving, review the storage connection, exact remote path, included content, automatic-sync choice, and masked credentials.
+
 Buckets and remote repositories must already exist.
 Git uses existing non-interactive SSH or credential-helper configuration and never stores Git credentials.
 
 ## 🧭 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
@@ -58,33 +59,38 @@ 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.
+The manager also provides setup and connection details, history, and recovery.
+
+On secondary screens, **Back** and Escape return to the previous screen, while Ctrl+C closes the 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.
@@ -102,7 +108,7 @@ Choose **Review differences (recommended)** in an ordinary file-direction confli
 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.
@@ -119,69 +125,33 @@ It clears after verified resolution, invalidation, session replacement, or shutd
 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 mismatch review remains read-only and notification-based.
+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.
+**Settings → Skip secret scan** 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.
 
-```text
-~/.pi/agent/pi-sync.json
-```
-
-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.
-
-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.
-
-### Complete version 3 example
+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 +161,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.
-
-## 💬 Commands
-
-The menu is preferred, while deterministic routes remain available:
+Version 1, version 2, and non-empty unversioned settings require manual recovery rather than automatic migration.
 
-```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
-```
+Adding `sessions` can upload prompts, tool output, paths, images, and secrets; interactive flows require a privacy acknowledgement.
+Automatic sync and pull pause when the remote included-content policy differs instead of silently expanding local scope.
 
-- `--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.
+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.
 
-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
 
@@ -357,7 +244,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 +252,32 @@ 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`, `Later`, `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
+├── src/                               # Backends, settings, snapshots, and recovery modules
+│   ├── index.ts                       # Thin Pi entrypoint
+│   └── sync-extension.ts              # Sync lifecycle and lazy loading
+├── 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`.
+
 ## 🔎 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-LONPFFNP.ts → chunk-44LPGQTI.ts}

@@ -3,15 +3,15 @@
 import {
   runCancellableOperation,
   showRemoteSelectionReview
-} from "./chunk-5WJNWFTG.ts";
+} from "./chunk-ARN2672F.ts";
 import {
   errorMessage,
   safeTerminalText
-} from "./chunk-W64NEHXT.ts";
+} from "./chunk-C7LXZ3UH.ts";
 import {
   loadConfig,
   syncConfigReviewIdentity
-} from "./chunk-APZVBSM6.ts";
+} from "./chunk-5T442OP3.ts";
 
 // src/sync-resolution-ui.ts
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
@@ -210,4 +210,4 @@ async function dispatchManagerResult(ctx, initialResult, origin, runRoute, signa
 export {
   dispatchManagerResult
 };
-//# sourceMappingURL=chunk-LONPFFNP.ts.map
+//# sourceMappingURL=chunk-44LPGQTI.ts.map

package/dist/chunks/{chunk-FR6CVXAL.ts → chunk-5LZALPCD.ts}

@@ -2,10 +2,10 @@
 // @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
 import {
   safeTerminalText
-} from "./chunk-W64NEHXT.ts";
+} from "./chunk-C7LXZ3UH.ts";
 import {
   syncConfigReviewFingerprint
-} from "./chunk-APZVBSM6.ts";
+} from "./chunk-5T442OP3.ts";
 import {
   inspectRemoteSelection,
   remoteSelectionMismatch,
@@ -17,7 +17,7 @@ import {
 var createSyncBackend = async (config) => {
   switch (config.backend.type) {
     case "s3": {
-      const { S3SyncBackend } = await import("./s3-backend-3QZGO2EF.ts");
+      const { S3SyncBackend } = await import("./s3-backend-552LXHE4.ts");
       return new S3SyncBackend(config.backend);
     }
     case "webdav": {
@@ -78,4 +78,4 @@ export {
   requireCompatibleRemoteSelection,
   formatRemoteSelectionStatus
 };
-//# sourceMappingURL=chunk-FR6CVXAL.ts.map
+//# sourceMappingURL=chunk-5LZALPCD.ts.map

package/dist/chunks/{chunk-APZVBSM6.ts → chunk-5T442OP3.ts}

@@ -589,7 +589,14 @@ async function loadConfig(setupName) {
       `Invalid pi-sync settings: sync setup \u201C${selectedName}\u201D references missing storage connection \u201C${connectionName}\u201D.`
     );
   }
-  return resolveSyncConfig(selectedName, setup, connectionName, connection, settings.onSwitch);
+  return resolveSyncConfig(
+    selectedName,
+    setup,
+    connectionName,
+    connection,
+    settings.onSwitch,
+    settings.skipSecretScan ?? false
+  );
 }
 async function loadPartialConfig(setupName) {
   const config = await loadConfig(setupName);
@@ -603,12 +610,12 @@ async function loadPartialConfig(setupName) {
 }
 function syncSetupStorageReview(setupName, setup, connectionName, connection) {
   return storageReviewFromConfig(
-    resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH)
+    resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false)
   );
 }
 function syncSetupReviewIdentity(setupName, setup, connectionName, connection) {
   return syncConfigReviewIdentity(
-    resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH)
+    resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false)
   );
 }
 function syncConfigReviewIdentity(config) {
@@ -646,7 +653,7 @@ function normalizeOnSwitch(value) {
     'Invalid pi-sync settings: onSwitch must be "ask-before-pull", "pull-after-switch", or "switch-only".'
   );
 }
-function resolveSyncConfig(setupName, setup, connectionName, connection, onSwitch) {
+function resolveSyncConfig(setupName, setup, connectionName, connection, onSwitch, skipSecretScan) {
   const storagePath = normalizeStoragePath(setup.storage.path);
   const namespace = storagePath.slice(storagePath.lastIndexOf("/") + 1);
   const include = normalizeSyncInclude(setup.sync.include);
@@ -657,7 +664,8 @@ function resolveSyncConfig(setupName, setup, connectionName, connection, onSwitc
     snapshotIdentity: namespace,
     include,
     automatic: setup.sync.automatic,
-    onSwitch
+    onSwitch,
+    skipSecretScan
   };
   if (connection.type === "git") {
     return {
@@ -744,6 +752,9 @@ function validateSettingsDocument(value) {
     "top level"
   );
   normalizeOnSwitch(value.onSwitch);
+  if (value.skipSecretScan !== void 0 && typeof value.skipSecretScan !== "boolean") {
+    throw new Error("Invalid pi-sync settings: skipSecretScan must be boolean.");
+  }
   const storageConnections = requireNamedObjectMap(
     value.storageConnections,
     "storageConnections",
@@ -1123,6 +1134,7 @@ function localConfigTemplate() {
   return {
     version: 3,
     onSwitch: DEFAULT_ON_SWITCH,
+    skipSecretScan: false,
     storageConnections: {},
     syncSetups: {}
   };
@@ -1235,4 +1247,4 @@ export {
   syncSessionsWarnings,
   isCloudflareR2Endpoint
 };
-//# sourceMappingURL=chunk-APZVBSM6.ts.map
+//# sourceMappingURL=chunk-5T442OP3.ts.map