update docs

2026-06-06 14:32:58 +00:00 · 2026-06-05 03:05:13 +09:00
parent 1b44ab9f2b
commit 31050c9cb8
11 changed files with 343 additions and 40 deletions
@@ -0,0 +1,65 @@
+# AI Coding Assistant Instructions (AGENTS.md)
+
+When working on this repository (writing code, comments, documentation, or commits), you MUST follow these guidelines to maintain consistency.
+
+## Required Reference Files
+
+Before making changes to documentation, user-facing text, or settings:
+1. Read [docs/terms.md](file:///Users/vorotamoroz/dev/js/obsidian-livesync/docs/terms.md) for terminology, vocabulary conventions, and technical definitions.
+2. Read [docs/settings.md](file:///Users/vorotamoroz/dev/js/obsidian-livesync/docs/settings.md) (and [docs/settings_ja.md](file:///Users/vorotamoroz/dev/js/obsidian-livesync/docs/settings_ja.md)) for UI settings and setting key mappings.
+3. Read [docs/troubleshooting.md](file:///Users/vorotamoroz/dev/js/obsidian-livesync/docs/troubleshooting.md) for troubleshooting guidelines and common recovery steps (such as flag files and SCRAM state).
+4. Read [devs.md](file:///Users/vorotamoroz/dev/js/obsidian-livesync/devs.md) for development workflows, module architecture, and testing infrastructure.
+
+---
+
+## Documentation and User-Facing Text Rules
+
+Always adhere to the following stylistic and spelling rules:
+
+1. **British English Spelling**:
+   - Write all documentation and user-facing messages in British English. If in doubt, the BBC News Styleguide may be useful as a reference.
+   - **Traditional Spelling (Trad-spelling)**: Use `-ise` and `-isation` suffixes instead of `-ize` and `-ization` (for example: 'initialisation', 'synchronisation', and 'organisation').
+   - **Oxford Comma**: Use the serial (Oxford) comma to separate items in lists of three or more (for example: 'settings, snippets, and themes' instead of 'settings, snippets and themes').
+   - **Logical Punctuation**: Place punctuation marks (such as commas and full stops) outside quotation marks unless they are part of the quoted text itself (for example: write 'dialogue', not 'dialogue,').
+
+2. **No Contractions**:
+   - Do not use contractions in general text or documentation (for example: write "do not" instead of "don't", "cannot" instead of "can't", and "is not" instead of "isn't").
+
+3. **Quotation Style**:
+   - Prefer single quotation marks (`'`) over double quotation marks (`"`) in general documentation text, unless the context requires double quotes (for example, inside JSON code blocks).
+
+4. **Specific Terminology and Spelling**:
+   - Use **'dialogue'** in documentation, user-facing messages, and general text. Use **'dialog'** only inside source code (e.g. class names, methods).
+   - Use the hyphenated form **'plug-in'** in user-facing text. Use **'plugin'** only in codebase files, configuration settings, or technical contexts.
+
+---
+
+## Technical & Architecture Rules
+
+1. **Database Structure**:
+   - Remember that Self-hosted LiveSync splits files into **Metadata** (file properties, size, paths) and **Chunks** (actual content). Do not store raw content in the metadata document directly.
+2. **Setup and Recovery**:
+   - **Fast Setup (Simple Fetch)** is the preferred flow for initial replication on secondary devices. It utilises stream-based replication for high speed and delays local file reflection to suppress temporary synchronisation warnings.
+   - **Flag files** (such as `redflag.md`, `redflag2.md`, and `redflag3.md`) at the root of the vault control the boot-up sequence and trigger automated fetch/rebuild tasks.
+3. **Subrepositories**:
+   - The directory [src/lib](file:///Users/vorotamoroz/dev/js/obsidian-livesync/src/lib) is a subrepository (Git submodule) pointing to the shared library `livesync-commonlib`. Do not make modifications inside this directory without careful consideration, as changes affect the shared library.
+4. **Application Directories**:
+   - The directory [src/apps](file:///Users/vorotamoroz/dev/js/obsidian-livesync/src/apps) contains independent application modules:
+     - `cli`: A Command Line Interface application. Tests specifically for the CLI (both unit and End-to-End tests) are located and executed within [src/apps/cli](file:///Users/vorotamoroz/dev/js/obsidian-livesync/src/apps/cli) using its local `package.json` scripts.
+     - `webapp`: A Web-based application.
+     - `webpeer`: A Web-based peer utility.
+
+---
+
+## Development & Verification Commands
+
+Before submitting code, you should run verification scripts locally to ensure correct syntax and function.
+
+1. **Lint and Type Checking**:
+   - Run `npm run check` to perform code verification. This runs type-checking (`tsc-check`), ESLint (`lint`), and Svelte checks (`svelte-check`).
+2. **Unit Tests**:
+   - Run `npm run test:unit` to execute fast local unit tests.
+   - Run `npm run test` or `npm run test:full` for full testing suites (including dockerised services).
+3. **Build**:
+   - Run `npm run build` to compile the production bundle (`main.js`).
+   - Run `npm run dev` for the development watch/build task.
@@ -87,7 +87,8 @@ Synchronisation status is shown in the status bar with the following icons.
 To prevent file and database corruption, please avoid closing Obsidian until all progress indicators have disappeared as much as possible (although the plug-in will attempt to resume if interrupted). This is especially important if you have deleted or renamed files.

 ## Tips and Troubleshooting
-If you are having problems getting the plug-in working, see [Tips and Troubleshooting](docs/troubleshooting.md).
+- If you want a faster and simpler initial replication when setting up subsequent devices, see the [Fast Setup Guide](docs/tips/fast-setup.md).
+- If you are having problems getting the plug-in working, see [Tips and Troubleshooting](docs/troubleshooting.md).

 ## Acknowledgements
 The project has been in continual progress and harmony thanks to the following:  
@@ -78,7 +78,8 @@ NDAや類似の契約や義務、倫理を守る必要のある、研究者、


 ## Tips and Troubleshooting
-何かこまったら、[Tips and Troubleshooting](docs/troubleshooting.md)をご参照ください。
+- 2台目以降のセットアップ時に、初期同期をより迅速かつ簡単に行うには、[ファストセットアップガイド](docs/tips/fast-setup_ja.md)をご参照ください。
+- 何かこまったら、[Tips and Troubleshooting](docs/troubleshooting.md)をご参照ください。

 ## License

@@ -127,3 +127,7 @@ And, please copy the setup URI by running the "Copy settings as a new setup URI"
 After installing Self-hosted LiveSync on the first device, we should have a setup URI. **The first choice is to use it**. Please share it with the device you want to setup.

 It is completely same as [Using setup URIs on the first device](#1-using-setup-uris). Please refer it.
+
+> [!TIP]
+> **Fast Setup (Simple Fetch)**
+> In recent versions, when you import a Setup URI or trigger a Fetch All, the plug-in boots in scheduled fetch mode and runs a simplified **Fast Setup** process. This allows you to choose your sync strategy with a single dialogue and performs initial synchronisation in one step. Refer to the [Fast Setup Guide](./tips/fast-setup.md) for more details.
@@ -86,4 +86,8 @@ Presetsから、いずれかの同期方法を選び`Apply`を行うと、必要
 - `Importing LiveSync's conf, OK?` に `Yes`
 - `How would you like to set it up?` に `Set it up as secondary or subsequent device`

-これで設定が反映され、レプリケーションが開始されます。
+これで設定が反映され、レプリケーションが開始されます。
+
+> [!TIP]
+> **ファストセットアップ (Fast Setup)**
+> 近年のバージョンでは、セットアップURIの読み込みやデータの全取得（Fetch All）を実行した際、より簡単に同期戦略を選択して即座に初期同期を完了できる **ファストセットアップ (Simple Fetch)** フローが利用できます。詳細は [ファストセットアップガイド](./tips/fast-setup_ja.md) をご参照ください。
@@ -446,6 +446,12 @@ Apply preset configuration

 Setting key: syncMode

+The trigger mechanism for synchronisation.
+- **LiveSync** (`LIVESYNC`): Real-time, continuous, bidirectional synchronisation.
+  Note: This requires a CouchDB or WebRTC P2P remote server. It is not supported for S3-compatible Object Storage.
+- **Periodic Sync** (`PERIODIC`): Synchronisation is performed at regular intervals specified by the **Periodic Sync interval** setting.
+- **On Events** (`ONEVENTS`): Synchronisation is triggered by specific events (such as save, file open, or startup) configured via the toggles below.
+
 #### Periodic Sync interval

 Setting key: periodicReplicationInterval
@@ -648,14 +654,18 @@ Warning! This will have a serious impact on performance. And the logs will not b

 ### 2. Scram Switches

+Emergency controls to suspend synchronisation processes in order to prevent database corruption. If a critical mismatch or sync error occurs, the plug-in may automatically enter a Scram state and suspend operations.
+
 #### Suspend file watching

 Setting key: suspendFileWatching
-Stop watching for file changes.
+
+Stop watching for local file changes.

 #### Suspend database reflecting

 Setting key: suspendParseReplicationResult
+
 Stop reflecting database changes to storage files.

 ### 3. Recovery and Repair
@@ -247,7 +247,8 @@ TURNサーバーでの認証に使用するパスワード（クレデンシャ
 このオプションはLiveSyncと同時には使用できません。

 ### minimum chunk size と LongLine threshold
-チャンクの分割についての設定です。  
+チャンクの分割についての設定です。※現在これらの項目はUIから直接設定することはできません（デフォルト値で自動処理されます）。
+
 Self-hosted LiveSyncは一つのチャンクのサイズを最低minimum chunk size文字確保した上で、できるだけ効率的に同期できるよう、ノートを分割してチャンクを作成します。  
 これは、同期を行う際に、一定の文字数で分割した場合、先頭の方を編集すると、その後の分割位置がすべてずれ、結果としてほぼまるごとのファイルのファイル送受信を行うことになっていた問題を避けるために実装されました。  
 具体的には、先頭から順に直近の下記の箇所を検索し、一番長く切れたものを一つのチャンクとします。
@@ -291,15 +292,17 @@ Self-hosted LiveSyncは一つのチャンクのサイズを最低minimum chunk s
 ## Sync setting
 同期に関する設定です。

-### LiveSync
-LiveSyncを行います。
-他の同期方法では、同期の順序が「バージョン確認を行い、ロックが行われていないか確認した後、リモートの変更を受信した後、デバイスの変更を送信する」という挙動になります。
+### 同期モード (Sync Mode)
+設定キー: syncMode

-### Periodic Sync
-定期的に同期を行います。
+同期処理を実行するトリガーとなる条件を設定します。
+- **LiveSync** (`LIVESYNC`): リアルタイムかつ継続的な双方向同期を行います。
+  注意: このモードには CouchDB または WebRTC P2P リモートサーバーが必要です。S3互換オブジェクトストレージではサポートされていません。
+- **Periodic Sync** (`PERIODIC`): **Periodic Sync Interval** で指定した一定の間隔ごとに同期処理を実行します。
+- **On Events** (`ONEVENTS`): ファイルの保存、ファイルを開く、起動時など、特定のイベントが発生した際に同期をトリガーします（詳細は下部の設定スイッチで制御します）。

 ### Periodic Sync Interval
-定期的に同期を行う場合の間隔です。
+定期的に同期を行う場合の間隔（秒単位）です。

 ### 同期の最小間隔
 設定キー: syncMinimumInterval
@@ -382,6 +385,40 @@ Self-hosted LiveSyncはPouchDBを使用し、リモートと[このプロトコ

 メガバイト（MB）単位で指定します。

+## Customisation Sync (カスタマイズ同期)
+プラグイン、ホットキー、テーマ、スニペットなどのObsidianのカスタマイズ設定を同期する機能です（以前は **Plugin Sync** と呼ばれていました）。
+
+### デバイス名 (Device name)
+設定キー: deviceAndVaultName
+
+同期するすべてのデバイス間で一意となるデバイス名です。この設定を編集するには、一度カスタマイズ同期を無効にする必要があります。
+
+### ファイル保存ごとのカスタマイズ同期 (Per-file-saved customisation sync)
+設定キー: usePluginSyncV2
+
+有効な場合、ファイルごとの効率的なカスタマイズ同期が使用されます。有効にする際には簡単な移行作業が必要であり、すべてのデバイスを v0.23.18 以降にアップデートする必要があります。この機能を有効にすると、古いバージョンとの互換性が失われます。
+
+### カスタマイズ同期を有効にする (Enable customisation sync)
+設定キー: usePluginSync
+
+テーマ、スニペット、ホットキー、プラグイン設定などの同期を有効にします。
+注意: 安全上の理由から、この機能を使用するにはエンドツーエンド暗号化（End-to-End Encryption）が有効になっている必要があります。
+
+### カスタマイズの自動スキャン (Scan customisation automatically)
+設定キー: autoSweepPlugins
+
+レプリケーション（同期処理）を実行する前に、カスタマイズ設定の変更をスキャンします。
+
+### 定期的なカスタマイズのスキャン (Scan customisation periodically)
+設定キー: autoSweepPluginsPeriodic
+
+1分ごとにカスタマイズ設定の変更を定期的にスキャンします。
+
+### カスタマイズ更新の通知 (Notify customised)
+設定キー: notifyPluginOrSettingUpdated
+
+他のデバイスで新しくカスタマイズ設定が更新されたときに通知を表示します。
+
 ## Miscellaneous
 その他の設定です
 ### Show status inside editor
@@ -423,8 +460,30 @@ Vault内のファイルを全て読み込み直し、もし差分があったり

 万が一同期に不具合が発生していて、使用しているデバイスのデータ＋サーバーのデータを保護する場合などに、緊急避難的に使用してください。

-### Suspend file watching
-ファイルの更新の監視を止めます。
+### Scram スイッチ (Scram Switches)
+データベースの破損や予期しないデータ喪失を防ぐために、同期処理を緊急停止するためのスイッチです。重大な設定不一致や同期エラーが発生した場合、プラグインは自動的に Scram 状態に移行し、同期動作を一時停止することがあります。
+
+#### ファイルの更新監視を一時停止 (Suspend file watching)
+設定キー: suspendFileWatching
+
+ローカルファイル変更の監視と検知を停止します。
+
+#### データベース反映を一時停止 (Suspend database reflecting)
+設定キー: suspendParseReplicationResult
+
+データベースでの変更をストレージファイル（Vault内のファイル）へ書き戻す処理を停止します。
+
+### 互換性（メタデータ）(Compatibility (Metadata))
+
+#### 削除済みファイルのメタデータを保持しない (Do not keep metadata of deleted files.)
+設定キー: deleteMetadataOfDeletedFiles
+
+ファイルを削除した際に、そのファイルの同期履歴メタデータも即座にデータベースから削除し、保持しないようにします。
+
+#### 削除済みデータのメタデータをクリーンナップする (Delete old metadata of deleted files on start-up)
+設定キー: automaticallyDeleteMetadataOfDeletedFiles
+
+ファイルを削除した際のメタデータを保持する期間（日数）を設定します。指定した日数を経過した古い削除済みファイルのメタデータは、プラグイン起動時にデータベースから自動的に削除（クリーンナップ）されます。`0` を指定すると自動削除は無効になります。

 ### 破損している可能性があるファイルも処理する
 設定キー: processSizeMismatchedFiles
@@ -2,7 +2,13 @@

 ## Spelling and Vocabulary conventions

-1. Almost all of the english words are written in British English. For example, "organisation" instead of "organization", "synchronisation" instead of "synchronization", etc. This convention originated from the author's personal preference but is now maintained for consistency.
+All guidelines and conventions listed below are disclosed and maintained solely for the sake of documentation `consistency`.
+
+1. Almost all of the English words are written in British English. This convention originated from the author's personal preference.
+   - **Traditional Spelling (Trad-spelling)**: We prefer traditional British English spellings. In particular, we use `-ise` and `-isation` suffixes rather than the Oxford spelling `-ize` and `-ization` (for example, 'initialisation', 'synchronisation', and 'organisation').
+   - **Oxford Comma**: We use the serial (Oxford) comma to separate items in lists of three or more (for example, 'settings, snippets, and themes' instead of 'settings, snippets and themes').
+   - **Logical Punctuation**: We place punctuation marks (such as commas and full stops) outside quotation marks, unless the punctuation mark is part of the quoted text itself. For example, we write 'dialogue', not 'dialogue,'.
+   - **BBC News Styleguide**: If in wonder, the BBC News Styleguide may be useful as a reference.

 2. Idiomatic terms, such as those used in HTML, CSS, and JavaScript, are usually aligned with the language used in the technology. For example, "color" instead of "colour", "program" instead of "programme", etc. Especially, terms which are used for attributes, properties, and methods are notable.

@@ -14,8 +20,14 @@
 5. However, try using affirmative forms, `Discard` instead of `Do not keep`, `Continue` instead of `Do not stop`, etc.
    - Some languages, such as Japanese, have a different meaning for `yes` and `no` between affirmative and negative questions.

+6. Single quotation marks (`'`) are preferred over double quotation marks (`"`) in general documentation text, unless the context requires double quotes (for example, inside JSON code blocks).
+
 ### Terminology

+- Boot-up sequence (boot-sequence)
+    - The initialisation process of the plug-in when Obsidian starts. It starts with the loading of the plug-in, setting up core services, loading saved settings, and opening the local database. Once the layout is ready, the plug-in checks for the presence of flag files, runs configuration diagnostics, connects to the remote database, and begins file watching. The sequence finishes once the plug-in is fully ready and operational.
+- Broken files (Size mismatch)
+    - A state where a file's metadata and the actual content stored in its chunks do not match, causing file retrieval or synchronisation failures. These mismatches can be detected and resolved by running validation tools such as `Verify and repair all files` on the Hatch pane.
 - Chunk / Chunks
    - Divided units of data stored in the database or object storage to facilitate efficient synchronisation.
 - Compaction
@@ -34,20 +46,26 @@
    - The cryptographic algorithm version used for end-to-end encryption. All devices in the synchronisation group must be configured with a compatible version (such as `V2` or `V1`).
 - Eden (Eden Chunks)
    - A performance optimisation where newly created chunks are held within the document until they stabilise, before graduating to independent chunks.
+- Fast Setup (Simple Fetch)
+    - A simplified, automated initial synchronisation flow triggered when setting up subsequent devices or recovering a database. It bypasses the detailed step-by-step setup wizard dialogues, prompting the user with high-level data processing decisions and completing the initial download and local file scan in one continuous process.
 - Flag files (redflag.md, redflag2.md, redflag3.md)
    - Special Markdown files (or directories) placed at the root of the vault to stop the boot-up sequence or trigger recovery tasks. For instance, `redflag.md` suspends all processes, while `redflag2.md` (`flag_rebuild.md`) triggers a full database rebuild and `redflag3.md` (`flag_fetch.md`) discards the local database to fetch it again from the remote.
 - Garbage Collection (GC)
    - The process of identifying and purging unreferenced chunks (unused data) from local and remote databases to reclaim storage space.
+- Hatch (Hatch pane)
+    - A dedicated troubleshooting and maintenance section in the plug-in settings, typically hidden behind a warning-labeled collapsible panel to prevent accidental misconfiguration. It contains diagnostic utilities, database reset controls, status reports, and advanced edge-case patches.
 - Hidden File Sync
    - The feature that synchronises files located in hidden directories (like `.obsidian`).
+- JWT Authentication
+    - An experimental authentication option for CouchDB allowing secure token-based authentication instead of standard credentials. It requires a configured private key/secret, algorithm, expiration duration, subject, and key ID.
 - LiveSync
    - A very confusing term.
        - As a shortened form of `Self-hosted LiveSync`.
        - As the name of a synchronisation mode. This should be changed to `Continuous`, in contrast to `Periodic`.
 - livesync-serverpeer / webpeer
    - Pseudo-clients that assist in WebRTC peer-to-peer communication.
- JWT Authentication
-    - An experimental authentication option for CouchDB allowing secure token-based authentication instead of standard credentials. It requires a configured private key/secret, algorithm, expiration duration, subject, and key ID.
+- Metadata (File metadata)
+    - A database document that stores properties of a file, including its filename, path, size, modification time, conflict history, and references (hashes) of the chunks that comprise the file's content. In Self-hosted LiveSync, metadata is stored separately from the actual file content to enable efficient synchronisation and versioning.
 - OneShot Sync
    - A single, immediate bidirectional synchronisation (pull then push) triggered on demand or on specific events, as opposed to continuous (live) replication.
 - Overwrite Server Data with This Device's Files
@@ -72,6 +90,8 @@
    - A diagnostic utility that checks for mismatches or suboptimal configurations, presenting users with ideal values and recommendation reasons to easily resolve issues during migration, configuration import, or general troubleshooting.
 - Setup URI
    - An encrypted representation of the plug-in's settings containing server configuration, which allows users to clone their configuration across devices securely using a passphrase.
+- Streaming replication (Stream-based replication)
+    - A data transfer method that downloads database documents as a continuous stream of events. It is significantly faster than traditional chunk-by-chunk HTTP requests and is used during Fast Setup to retrieve remote metadata quickly.
 - Sync Mode
    - The replication trigger mechanism. Users can select from `On Events` (synchronising on local file changes), `Periodic and Events` (synchronising at fixed intervals as well as on events), or `LiveSync` (continuous, real-time synchronisation).
 - TURN Server (WebRTC P2P)
@@ -0,0 +1,65 @@
+# Fast Setup (Simple Fetch)
+
+Fast Setup is a streamlined, user-friendly data retrieval and initialisation flow designed to simplify setting up secondary devices or recovering databases. 
+
+Instead of guiding the user through the detailed multi-step setup wizard dialogues, Fast Setup prompts the user with high-level sync decisions and automates database download and local storage scanning in one continuous process.
+
+---
+
+## How It Works
+
+When you import a **Setup URI** on a secondary device, or when a **Fetch All** operation is triggered (such as by placing a `redflag3.md` / `flag_fetch.md` flag file at the root of the vault), the plug-in schedules remote data retrieval.
+
+On the next startup, the plug-in boots in scheduled fetch mode and opens a simplified dialogue: **"Data retrieval scheduled"**.
+
+---
+
+## Technical Characteristics
+
+Fast Setup leverages several backend optimisations to make the retrieval fast, safe, and clean:
+
+1. **Stream-based Replication for Speed**
+   - It fetches all remote metadata via stream reception, which is significantly faster than traditional chunk-by-chunk retrieval.
+2. **Delayed File Reflection to Prevent Corrupted Warnings**
+   - By suspending file reflection during the download phase, it prevents the plug-in from raising temporary or false "corrupted data synchronisation" or "size mismatch" warnings that can occur during the chunk download process.
+3. **Time-Based Comparison is Generally Sufficient**
+   - Since the vault is entering a fresh synchronisation or recovery state, comparing files based on their modification timestamps (newer-wins) is highly reliable and sufficient to reconcile files without needing complex manual conflict resolution.
+
+---
+
+## Step-by-Step Guide
+
+### Step 1: Choose Data Processing Method
+You will be prompted to choose how the retrieved remote data will interact with your existing local files:
+
+1. **Compare time and take newer (newer-wins)**
+   - Compares the modified time of files and accepts the newer version.
+   - **Recommended if:** You have been using Self-hosted LiveSync and have made changes on multiple devices that you want to merge.
+2. **Overwrite all with remote files (remote-wins)**
+   - Remote data is treated as the source of truth.
+   - **Recommended if:** You are setting up a brand new device with an empty or clean vault.
+   - *Warning: This will overwrite local files with remote files. Please ensure you have a backup of your local vault before proceeding.*
+3. **Use the detailed flow (legacy)**
+   - Switches back to the detailed, traditional setup wizard dialogues.
+   - **Recommended if:** You want full control over the step-by-step database setup options.
+
+### Step 2: Configure Conflict & Deletion Rules
+Depending on your choice in Step 1, you will configure how to handle mismatches:
+
+#### If you chose "Compare time and take newer":
+- **Delete local files if they were deleted on remote**
+  - Keeps your local vault clean by removing files that have already been deleted on other devices.
+- **Recreate remote files even if they were deleted on remote**
+  - Preserves local files and uploads them back to the remote database, even if they were deleted on other devices.
+
+#### If you chose "Overwrite all with remote files":
+- **Delete local files if not on remote**
+  - Removes local-only files so that your local vault matches the remote database exactly.
+- **Keep local files even if not on remote**
+  - Retains all existing local-only files, although this may result in duplicates that you will need to clean up manually after synchronisation.
+
+### Step 3: Automated Synchronisation
+Once you confirm your choices:
+1. The plug-in performs a fast download of the remote database (`fetchLocalDBFast`).
+2. It automatically runs a full scan (`synchroniseAllFilesBetweenDBandStorage`) in the foreground to reflect database changes in your local vault files immediately.
+3. The plug-in finalises the process and resumes normal operational status.
@@ -0,0 +1,66 @@
+# ファストセットアップ (Fast Setup / Simple Fetch)
+
+ファストセットアップは、2台目以降のデバイスのセットアップやデータベース再構築時のデータ取得・初期化処理を、直感的かつ迅速に行うための簡略化された同期フローです。
+
+従来のセットアップウィザードにおける複数の詳細なステップを踏むことなく、同期の基本方針を選択するだけで、データベースのダウンロードとローカルファイルのスキャン・反映を一連のプロセスとして自動的に実行します。
+
+---
+
+## 仕組み
+
+2台目以降のデバイスで **セットアップURI** をインポートした場合や、手動でデータの再フェッチ（Vaultルートに `redflag3.md` / `flag_fetch.md` を配置する等）が予約された場合、プラグインはリモートデータベースからのデータ取得スケジュールを設定します。
+
+その後の起動時、プラグインはデータフェッチ予約モードで立ち上がり、**「Data retrieval scheduled（データ取得のスケジュール）」** という簡略化されたダイアログを表示します。
+
+---
+
+## 技術的な特徴
+
+ファストセットアップは、高速かつ安全でクリーンな処理を実現するために、以下の最適化を行っています。
+
+1. **高速なストリーム受信**
+   - 全データを取得しますが、ストリーム受信によるレプリケーションを使用するため、処理が非常に高速です。
+2. **ストレージ反映の遅延による不要な警告の抑制**
+   - データのダウンロード中にローカルファイル（ストレージ）への書き出し（反映）処理をあえて遅延させることで、同期途中で発生しがちな「破損データ同期」や「サイズ不一致」などの一時的なエラー警告を抑え込みます。
+   - すべてのデータダウンロードが完了した後に一括してストレージへ書き出すため、不必要な警告画面でユーザーを混乱させません。
+3. **時刻ベース比較の妥当性**
+   - 初期セットアップやリカバリーの段階（この状態に移行した直後）においては、概ねファイル更新時刻（タイムスタンプ）ベースでの単純比較を行うことで、十分かつ妥当な同期結果を得ることができます。これにより複雑な競合解決の手間を省きます。
+
+---
+
+## 設定手順
+
+### ステップ 1: データの反映方法の選択
+取得したリモートデータを、既存のローカルファイルとどのように統合するかを選択します。
+
+1. **Compare time and take newer (newer-wins)**
+   - ファイルの更新日時を比較し、より新しい方を採用します。
+   - **推奨されるケース:** すでに Self-hosted LiveSync を使用しており、複数のデバイスで編集した変更内容をタイムスタンプに基づいて統合したい場合。
+2. **Overwrite all with remote files (remote-wins)**
+   - リモートデータベースの内容を正（Source of Truth）として扱います。
+   - **推奨されるケース:** まったく新しいデバイスをセットアップする場合（空のVaultなど）。
+   - *警告: ローカルにあるすべてのファイルがリモートの内容で上書きされます。重要なデータがある場合は、事前にバックアップを取得してください。*
+3. **Use the detailed flow (legacy)**
+   - 従来の詳細なセットアップウィザードダイアログに戻ります。
+   - **推奨されるケース:** データベースの構成オプションをステップバイステップで細かく制御・確認したい場合。
+
+### ステップ 2: 競合および削除ルールの構成
+ステップ 1 での選択内容に応じて、ローカルとリモートの不一致をどう処理するかを設定します。
+
+#### 「Compare time and take newer」を選択した場合:
+- **Delete local files if they were deleted on remote**
+  - 他のデバイスで削除済みのファイルをローカルからも削除し、Vaultを同期・クリーンな状態に保ちます。
+- **Recreate remote files even if they were deleted on remote**
+  - 他のデバイスで削除されたファイルであっても、ローカルファイルを維持し、リモートデータベースに再度アップロードします。
+
+#### 「Overwrite all with remote files」を選択した場合:
+- **Delete local files if not on remote**
+  - リモートに存在しないローカル専用ファイルを削除し、ローカルのVaultをリモートデータベースと完全に一致させます。
+- **Keep local files even if not on remote**
+  - リモートに存在しないローカルファイルをそのまま残します。ただし、同期後に重複ファイルが発生する可能性があるため、その場合は手動でクリーンアップを行ってください。
+
+### ステップ 3: 自動同期の実行
+選択を確定すると、以下の処理が順次実行されます。
+1. リモートデータベースの高速ダウンロードを実行します (`fetchLocalDBFast`)。
+2. ローカルファイルへの変更反映のため、フォアグラウンドでフルスキャン (`synchroniseAllFilesBetweenDBandStorage`) を自動的に実行します。
+3. 処理が完了すると、プラグインは通常の動作状態へ復帰します。
@@ -373,41 +373,49 @@ without Obsidian.
 For example, if there is `redflag.md`, Self-hosted LiveSync suspends all database and storage
 processes.

-### Flag Files
+### Scram State and Flag Files (SCRAM Warning Loop)

-The flag file is a simple Markdown file designed to prevent storage events and database events in self-hosted LiveSync.
-Its very existence is significant; it may be left blank, or it may contain text; either is acceptable.
+The plug-in uses a **Scram state** (emergency suspension of all synchronisation processes) to prevent database corruption when severe errors or conflicts are detected. This state is often triggered or persisted by **flag files** placed at the root of the vault.

-This file is in Markdown format so that it can be placed in the Vault externally, even if Obsidian fails to launch.
+If you encounter a warning saying **"Scram detected, all sync operations are suspended per SCRAM"** or get caught in an infinite loop where the warning persists even after clicking "Resume", it is likely due to a flag file in your vault.

-There are some options to use `redflag.md`.
+#### Flag Files
+
+A flag file is a simple Markdown file located at the root of your vault. Its very existence is significant; it may be left blank or contain any text. These files are used so they can be easily placed or deleted from outside Obsidian (e.g., when Obsidian fails to launch).

 | Filename      | Human-Friendly Name | Description                                                                             |
 | ------------- | ------------------- | --------------------------------------------------------------------------------------- |
-| `redflag.md`  | -                   | Suspends all processes.                                                                 |
+| `redflag.md`  | -                   | Suspends all processes (activates Scram).                                               |
 | `redflag2.md` | `flag_rebuild.md`   | Suspends all processes, and overwrites server data with this device's files.           |
 | `redflag3.md` | `flag_fetch.md`     | Suspends all processes, discards the local database, and resets synchronisation on this device. |

-When resetting synchronisation on this device or overwriting server data, restarting Obsidian
-is performed once for safety reasons. At that time, Self-hosted LiveSync uses
-these files to determine whether the process should be carried out. (The use of
-normal markdown files is a trick to externally force cancellation in the event
-of faults in the overwrite or reset function itself, especially on mobile
-devices). This mechanism is also used for set-up. And just for information,
-these files are also not subject to synchronisation.
+When resetting synchronisation on this device or overwriting server data, restarting Obsidian is performed once for safety reasons. At that time, Self-hosted LiveSync uses these files to determine whether the process should be carried out. (This mechanism is especially useful on mobile devices to force cancellation if the database rebuilding fails). These files are not subject to synchronisation.

-However, occasionally the deletion of files may fail. This should generally work
-normally after restarting Obsidian. (As far as I can observe).
+#### How to Resolve the Scram Loop

->[!IMPORTANT]
-> When a flag file is detected, all synchronisation is disabled, and `Suspend file watching` and
-> `Suspend database reflecting` are enabled automatically. Therefore, please follow the steps below to
-> resolve the issue.
-> 1. Delete the flag file.
-> 2. Shutdown Obsidian.
-> 3. Check your vault folder and ensure it is no longer there.
-> 4. Launch Obsidian.
-> 5. Disable `Suspend file watching` and `Suspend database reflecting` in the settings dialogue (if you have not been asked).
+If you cannot disable Scram, please follow these steps:
+1. Close Obsidian completely.
+2. Open your system's file manager and check the root directory of your vault.
+3. Locate and delete any flag files (such as `redflag.md`, `redflag2.md`, or `redflag3.md`).
+4. Launch Obsidian.
+5. Go to the settings dialogue -> **Hatch** -> **Scram Switches**, and manually toggle **Suspend file watching** and **Suspend database reflecting** to `false` (disabled) if they have not been reset automatically.
+
+> [!TIP]
+> This is the reason why flag files are standard `.md` files: it allows you to manage them externally. On mobile devices, you can use system file manager applications (such as the native **Files** app on iOS/iPadOS or **Files by Google** on Android) to find and delete these files to resolve a lock, or conversely, create/place a new `redflag.md` file (or directory) at the root of your vault to force-suspend synchronisation and stop Obsidian's boot-up sequence if you need to fix a database issue.
+
+### JWT Authentication Errors
+
+#### DataError when configuring JWT authentication
+
+If you encounter a `DataError:` with no additional information in the logs when configuring JWT authentication, this usually indicates a private key formatting issue.
+
+Self-hosted LiveSync requires the private key (for ES256/ES512 algorithms) to be in the **PKCS#8 PEM** format. Standard SEC1 EC private keys (which begin with `-----BEGIN EC PRIVATE KEY-----`) will trigger this error.
+
+To resolve this, convert your private key to PKCS#8 format using the following `openssl` command:
+```bash
+openssl pkcs8 -topk8 -inform PEM -nocrypt -in private.key -out pkcs8.key
+```
+Then paste the contents of `pkcs8.key` (which begins with `-----BEGIN PRIVATE KEY-----`) into the JWT Key field.

 ### Old tips