Releasing 1.0.0-beta.0

Releasing 0.25.83

.dockerignore

@@ -0,0 +1,34 @@
+# Git history
+.git/
+.gitignore
+
+# Dependencies — re-installed inside Docker
+node_modules/
+src/apps/cli/node_modules/
+
+# Pre-built CLI output — rebuilt inside Docker
+src/apps/cli/dist/
+
+# Obsidian plugin build outputs
+main.js
+main_org.js
+pouchdb-browser.js
+production/
+
+# Test coverage and reports
+coverage/
+_testdata/
+test/bench-network/bench-results/
+src/apps/cli/testdeno/bench-results/
+
+# Local environment / secrets
+.env
+*.env
+.test.env
+
+# local config files
+*.local
+
+# OS artefacts
+.DS_Store
+Thumbs.db

.eslintignore

@@ -1,3 +0,0 @@
-npm node_modules
-build
-.eslintrc.js.bak

.eslintrc

@@ -1,19 +1,57 @@
 {
     "root": true,
     "parser": "@typescript-eslint/parser",
-    "plugins": ["@typescript-eslint"],
-    "extends": ["eslint:recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended"],
+    "plugins": [
+        "@typescript-eslint",
+        "eslint-plugin-svelte",
+        "eslint-plugin-import"
+    ],
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:@typescript-eslint/recommended"
+    ],
     "parserOptions": {
-        "sourceType": "module"
+        "sourceType": "module",
+        "project": [
+            "tsconfig.json"
+        ]
     },
+    "ignorePatterns": [
+        "**/node_modules/*",
+        "**/jest.config.js",
+        "**/test.ts",
+        "**/tests.ts",
+        "**/**test.ts",
+        "**/**.test.ts",
+        "src/apps/**",
+        "esbuild.*.mjs",
+        "terser.*.mjs"
+    ],
     "rules": {
         "no-unused-vars": "off",
-        "@typescript-eslint/no-unused-vars": ["error", { "args": "none" }],
+        "@typescript-eslint/no-unused-vars": [
+            "error",
+            {
+                "args": "none"
+            }
+        ],
+        "no-unused-labels": "off",
         "@typescript-eslint/ban-ts-comment": "off",
         "no-prototype-builtins": "off",
         "@typescript-eslint/no-empty-function": "off",
         "require-await": "warn",
-        "no-async-promise-executor": "off",
-        "@typescript-eslint/no-explicit-any": "off"
+        "@typescript-eslint/require-await": "warn",
+        "@typescript-eslint/no-misused-promises": "warn",
+        "@typescript-eslint/no-floating-promises": "warn",
+        "no-async-promise-executor": "warn",
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unnecessary-type-assertion": "error",
+        "no-constant-condition": [
+            "error",
+            {
+                "checkLoops": false
+            }
+        ]
     }
 }

.gitattributes

@@ -0,0 +1,24 @@
+# Always checkout shell scripts with LF line endings (never CRLF)
+*.sh text eol=lf
+
+# Standard text files — auto normalize on checkout
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.ini text eol=lf
+*.env text eol=lf
+*.json text eol=lf
+*.ts text eol=lf
+*.js text eol=lf
+*.mjs text eol=lf
+*.css text eol=lf
+
+# Binary files — no line ending conversion
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff2 binary
+*.woff binary
+*.sh text eol=lf

.github/ISSUE_TEMPLATE/issue-report.md

@@ -0,0 +1,84 @@
+---
+name: Issue report
+about: Create a report to help us improve
+title: ''
+labels: 'uncategorised'
+assignees: ''
+
+---
+
+Thank you for taking the time to report this issue!
+Before filling in this form, please read: [How to report an issue](../docs/to_issue_reporting.md).
+
+Issues with sufficient information will be prioritised.
+
+---
+
+## Required
+
+### Abstract
+<!-- Briefly describe the problem in one or two sentences. -->
+
+### Expected behaviour
+<!-- What did you expect to happen? -->
+
+### Actually happened
+<!-- What actually happened? Include any error messages. -->
+
+### Reproducing procedure
+<!-- Step-by-step instructions to reproduce the issue. If you cannot reproduce it reliably, please describe the frequency and any signs you noticed. -->
+
+### Obsidian debug info
+Please provide debug info for **each device involved**. The primary device (where the issue occurred) is required; others are strongly recommended. If your issue involves synchronisation between devices, debug info from relevant devices is very helpful.
+To get it: open the command palette → "Show debug info".
+
+<details>
+<summary>Device 1 (primary)</summary>
+
+```
+<!-- paste here -->
+```
+</details>
+
+<details>
+<summary>Device 2 (if applicable)</summary>
+
+```
+<!-- paste here -->
+```
+</details>
+
+### LiveSync version
+The hatch report (below) includes version information. If you cannot provide the report, please fill in the version here.
+
+- Self-hosted LiveSync version: <!-- e.g. 0.23.0 — find it in Obsidian Settings → Community Plugins -->
+
+### Report and Logs from LiveSync
+Perform a `Generate full report for opening the issue with debug info` command and provide the generated report. This contains detailed information and recent 1000 log lines, which is very helpful for debugging. **PLEASE AMEND THE REPORT TO REMOVE ANY SENSITIVE INFORMATION BEFORE PASTING.**
+If too large to paste here, upload to [Gist](https://gist.github.com/) and share the link.
+
+<details>
+<summary>Report and Logs (primary)</summary>
+
+```
+<!-- paste here or link to Gist -->
+```
+</details>
+
+<details>
+<summary>Report and Logs (if applicable)</summary>
+
+```
+<!-- paste here or link to Gist -->
+```
+</details>
+
+---
+
+## Optional
+
+### Screenshots
+If applicable, please add screenshots to help explain your problem.
+
+### Other information, insights and intuition
+Please provide any additional context or information about the problem.

.github/workflows/cli-deno-tests.yml

@@ -0,0 +1,182 @@
+name: cli-deno-tests
+
+on:
+  push:
+    branches:
+      - main
+      - beta
+    paths:
+      - '.github/workflows/cli-deno-tests.yml'
+      - 'src/apps/cli/**'
+      - 'test/bench-network/**'
+      - 'package.json'
+      - 'package-lock.json'
+  pull_request:
+    paths:
+      - '.github/workflows/cli-deno-tests.yml'
+      - 'src/apps/cli/**'
+      - 'test/bench-network/**'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+    inputs:
+      test_task:
+        description: 'Deno test task to run'
+        type: choice
+        options:
+          - test:ci
+          - test:local
+          - test:e2e-matrix
+        default: test:ci
+      enable_debug:
+        description: 'Enable verbose and debug logging'
+        type: boolean
+        default: false
+      use_coturn:
+        description: 'Enable local coturn container for P2P tests'
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      task_matrix: ${{ steps.select.outputs.task_matrix }}
+    steps:
+      - name: Select task matrix
+        id: select
+        shell: bash
+        run: |
+          set -euo pipefail
+          SELECTED_TASK="${{ github.event_name == 'workflow_dispatch' && inputs.test_task || 'test:ci' }}"
+          echo "[INFO] Selected task set: $SELECTED_TASK"
+
+          case "$SELECTED_TASK" in
+            test:ci)
+              TASK_MATRIX='["test:setup-put-cat","test:mirror","test:daemon","test:push-pull","test:decoupled-vault","test:sync-two-local","test:sync-locked-remote","test:remote-commands","test:e2e-matrix:couchdb-enc0","test:e2e-matrix:couchdb-enc1","test:e2e-matrix:minio-enc0","test:e2e-matrix:minio-enc1"]'
+              ;;
+            test:local)
+              TASK_MATRIX='["test:setup-put-cat","test:mirror","test:daemon"]'
+              ;;
+            test:e2e-matrix)
+              TASK_MATRIX='["test:e2e-matrix:couchdb-enc0","test:e2e-matrix:couchdb-enc1","test:e2e-matrix:minio-enc0","test:e2e-matrix:minio-enc1"]'
+              ;;
+            *)
+              echo "[ERROR] Unknown task set: $SELECTED_TASK" >&2
+              exit 1
+              ;;
+          esac
+
+          echo "task_matrix=$TASK_MATRIX" >> "$GITHUB_OUTPUT"
+
+  test:
+    needs: prepare
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      DENO_DIR: ~/.cache/deno
+    strategy:
+      fail-fast: false
+      matrix:
+        task: ${{ fromJson(needs.prepare.outputs.task_matrix) }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Cache Deno dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/deno
+          key: ${{ runner.os }}-deno-${{ hashFiles('src/apps/cli/testdeno/deno.lock', 'src/apps/cli/testdeno/deno.json') }}
+          restore-keys: |
+            ${{ runner.os }}-deno-
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build CLI
+        working-directory: src/apps/cli
+        run: npm run build
+
+      - name: Create .test.env
+        working-directory: src/apps/cli
+        run: |
+          cat <<EOF > .test.env
+          hostname=http://127.0.0.1:5989/
+          dbname=livesync-test-db-ci
+          username=admin
+          password=testpassword
+          minioEndpoint=http://127.0.0.1:9000
+          accessKey=minioadmin
+          secretKey=minioadmin
+          bucketName=livesync-test-bucket-ci
+          EOF
+
+      - name: Run Deno tests
+        working-directory: src/apps/cli/testdeno
+        env:
+          LIVESYNC_DOCKER_MODE: native
+          LIVESYNC_CLI_RETRY: 3
+          LIVESYNC_CLI_DEBUG: ${{ inputs.enable_debug == true && '1' || '0' }}
+          LIVESYNC_CLI_VERBOSE: ${{ inputs.enable_debug == true && '1' || '0' }}
+          LIVESYNC_USE_COTURN: ${{ inputs.use_coturn == true && '1' || '0' }}
+        run: |
+          TASK="${{ matrix.task }}"
+          echo "[INFO] Running Deno task: $TASK"
+          deno task "$TASK"
+
+      - name: Stop leftover containers
+        if: always()
+        run: |
+          docker stop couchdb-test minio-test relay-test coturn-test >/dev/null 2>&1 || true
+          docker rm couchdb-test minio-test relay-test coturn-test >/dev/null 2>&1 || true
+
+  compose-p2p-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Docker versions
+        run: |
+          docker --version
+          docker compose version
+
+      - name: Run Compose CLI P2P E2E
+        env:
+          CLI_E2E_TASK: test:p2p:ci
+          RELAY: ws://nostr-relay:7777/
+          PEERS_TIMEOUT: '20'
+          SYNC_TIMEOUT: '60'
+          LIVESYNC_USE_COTURN: '0'
+          TURN_SERVERS: none
+          LIVESYNC_P2P_PEERS_RETRY: '1'
+          LIVESYNC_P2P_RELAY_READY_TIMEOUT_MS: '60000'
+          BENCH_LIVESYNC_TEST_TEE: '0'
+        run: docker compose -f test/bench-network/compose.yml run --build --rm bench-runner run-livesync-cli-e2e
+
+      - name: Show Compose diagnostics
+        if: failure()
+        run: |
+          docker compose -f test/bench-network/compose.yml ps
+          docker compose -f test/bench-network/compose.yml logs --no-color couchdb nostr-relay || true
+
+      - name: Stop Compose services
+        if: always()
+        run: docker compose -f test/bench-network/compose.yml down -v --remove-orphans

.github/workflows/cli-docker.yml

@@ -0,0 +1,139 @@
+# Build and push the CLI Docker image to GitHub Container Registry (GHCR).#
+# Image tag format: <manifest-version>-<unix-epoch>-cli
+# Example: 0.25.56-1743500000-cli
+#
+# Stable releases are also tagged with their major-minor version and 'latest'.
+# Pre-releases receive immutable version and SHA-qualified tags only.
+# Image name: ghcr.io/<owner>/livesync-cli
+name: Build and Push CLI Docker Image
+
+on:
+    push:
+        branches:
+            - main
+        tags:
+            - "*.*.*-cli"
+        paths-ignore:
+            - "docs/**"
+            - "*.md"
+            - "images/**"
+            - "assets/**"
+            - "instruction_images/**"
+            - "src/apps/webapp/**"
+            - "src/apps/webpeer/**"
+            - ".github/workflows/release.yml"
+            - ".github/workflows/unit-ci.yml"
+    workflow_dispatch:
+        inputs:
+            dry_run:
+                description: Build only (do not push image to GHCR)
+                required: false
+                type: boolean
+                default: true
+            force:
+                description: Continue to build/push even if CLI E2E fails (workflow_dispatch only)
+                required: false
+                type: boolean
+                default: false
+
+jobs:
+    build-and-push:
+        runs-on: ubuntu-latest
+        timeout-minutes: 90
+        permissions:
+            contents: read
+            packages: write
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Derive image tag
+              id: meta
+              run: |
+                  VERSION=$(jq -r '.version' manifest.json)
+                  MAJOR_MINOR=$(echo "${VERSION}" | cut -d. -f1,2)
+                  SHORT_SHA=$(git rev-parse --short HEAD)
+                  IMAGE="ghcr.io/${{ github.repository_owner }}/livesync-cli"
+
+                  # Build tag list based on the event and git ref
+                  TAGS=""
+                  if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+                      if [[ "${VERSION}" == *-* ]]; then
+                          # Pre-release builds must not advance stable moving tags.
+                          TAGS="${IMAGE}:${VERSION}-cli,${IMAGE}:${VERSION}-sha-${SHORT_SHA}-cli"
+                      else
+                          # Stable release builds
+                          TAGS="${IMAGE}:${VERSION}-cli,${IMAGE}:${MAJOR_MINOR}-cli,${IMAGE}:latest,${IMAGE}:${VERSION}-sha-${SHORT_SHA}-cli"
+                      fi
+                  elif [[ "${{ github.ref }}" == refs/heads/main ]]; then
+                      # Bleeding-edge / nightly builds
+                      TAGS="${IMAGE}:edge"
+                  else
+                      # Other branches / manual run fallback
+                      TAGS="${IMAGE}:${VERSION}-dev-sha-${SHORT_SHA}-cli"
+                  fi
+
+                  # Determine if the image should be pushed
+                  PUSH="true"
+                  if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+                      if [[ "${{ inputs.dry_run }}" == "true" ]]; then
+                          PUSH="false"
+                      fi
+                  fi
+
+                  echo "tags=${TAGS}" >> $GITHUB_OUTPUT
+                  echo "push=${PUSH}" >> $GITHUB_OUTPUT
+
+            - name: Log in to GitHub Container Registry
+              uses: docker/login-action@v3
+              with:
+                  registry: ghcr.io
+                  username: ${{ github.actor }}
+                  password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Set up QEMU
+              uses: docker/setup-qemu-action@v3
+              with:
+                  platforms: arm64
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24.x"
+                  cache: "npm"
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Run CLI E2E (docker)
+              id: e2e
+              continue-on-error: ${{ github.event_name == 'workflow_dispatch' && inputs.force }}
+              working-directory: src/apps/cli
+              env:
+                  CI: true
+              run: npm run test:e2e:docker:all
+
+            - name: Stop test containers (safety net)
+              if: always()
+              working-directory: src/apps/cli
+              run: |
+                  # Keep this as a safety net for future suites/steps that may leave containers running.
+                  bash ./util/couchdb-stop.sh >/dev/null 2>&1 || true
+                  bash ./util/minio-stop.sh >/dev/null 2>&1 || true
+                  bash ./util/p2p-stop.sh >/dev/null 2>&1 || true
+
+            - name: Build and push
+              if: ${{ steps.e2e.outcome == 'success' || (github.event_name == 'workflow_dispatch' && inputs.force) }}
+              uses: docker/build-push-action@v6
+              with:
+                  context: .
+                  file: src/apps/cli/Dockerfile
+                  push: ${{ steps.meta.outputs.push }}
+                  tags: ${{ steps.meta.outputs.tags }}
+                  platforms: linux/amd64,linux/arm64
+                  cache-from: type=gha
+                  cache-to: type=gha,mode=max

.github/workflows/cli-e2e.yml

@@ -0,0 +1,65 @@
+# Run CLI E2E tests
+name: cli-e2e
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: 'CLI E2E suite to run'
+        type: choice
+        options:
+          - two-vaults-matrix
+          - two-vaults-couchdb
+          - two-vaults-minio
+        default: two-vaults-matrix
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run CLI E2E suite
+        working-directory: src/apps/cli
+        env:
+          CI: true
+          TEST_SUITE: ${{ github.event_name == 'workflow_dispatch' && inputs.suite || 'two-vaults-matrix' }}
+        run: |
+          set -euo pipefail
+          echo "[INFO] Running CLI E2E suite: $TEST_SUITE"
+          case "$TEST_SUITE" in
+            two-vaults-matrix)
+              npm run test:e2e:two-vaults:matrix
+              ;;
+            two-vaults-couchdb)
+              REMOTE_TYPE=COUCHDB ENCRYPT=0 npm run test:e2e:two-vaults
+              ;;
+            two-vaults-minio)
+              REMOTE_TYPE=MINIO ENCRYPT=0 npm run test:e2e:two-vaults
+              ;;
+            *)
+              echo "[ERROR] Unknown suite: $TEST_SUITE" >&2
+              exit 1
+              ;;
+          esac
+
+      - name: Stop test containers
+        if: always()
+        working-directory: src/apps/cli
+        run: |
+          bash ./util/couchdb-stop.sh >/dev/null 2>&1 || true
+          bash ./util/minio-stop.sh >/dev/null 2>&1 || true

.github/workflows/cli-p2p-compose-smoke.yml

@@ -0,0 +1,94 @@
+# Run the Compose-packaged CLI P2P smoke benchmark.
+#
+# This workflow is intentionally manual-only. It exercises the local Compose
+# package for CouchDB + Nostr relay + CLI runner, and uploads the benchmark JSON
+# results for inspection without adding benchmark work to pull-request CI.
+name: cli-p2p-compose-smoke
+
+on:
+  workflow_dispatch:
+    inputs:
+      cases:
+        description: 'Comma-separated benchmark cases'
+        required: false
+        default: 'couchdb-baseline,p2p-direct-local'
+      signalling_cases:
+        description: 'Comma-separated signalling-shim P2P benchmark cases'
+        required: false
+        default: 'p2p-signalling-netem-home-wifi'
+      md_files:
+        description: 'Markdown file count'
+        required: false
+        default: '2'
+      bin_files:
+        description: 'Binary file count'
+        required: false
+        default: '1'
+      couchdb_rtt_ms:
+        description: 'Requested CouchDB RTT in milliseconds'
+        required: false
+        default: '20'
+
+permissions:
+  contents: read
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Docker versions
+        run: |
+          docker --version
+          docker compose version
+
+      - name: Run Compose P2P smoke benchmark
+        env:
+          BENCH_CASES: ${{ inputs.cases || 'couchdb-baseline,p2p-direct-local' }}
+          BENCH_MD_FILE_COUNT: ${{ inputs.md_files || '2' }}
+          BENCH_MD_MIN_SIZE_BYTES: '128'
+          BENCH_MD_MAX_SIZE_BYTES: '256'
+          BENCH_BIN_FILE_COUNT: ${{ inputs.bin_files || '1' }}
+          BENCH_BIN_SIZE_BYTES: '512'
+          BENCH_COUCHDB_RTT_MS: ${{ inputs.couchdb_rtt_ms || '20' }}
+          BENCH_SYNC_TIMEOUT: '180'
+          BENCH_PEERS_TIMEOUT: '20'
+          LIVESYNC_P2P_RELAY_READY_TIMEOUT_MS: '60000'
+          BENCH_LIVESYNC_TEST_TEE: '0'
+        run: docker compose -f test/bench-network/compose.yml run --build --rm bench-runner
+
+      - name: Run Compose P2P signalling-shim smoke benchmark
+        env:
+          BENCH_CASES: ${{ inputs.signalling_cases || 'p2p-signalling-netem-home-wifi' }}
+          BENCH_MD_FILE_COUNT: ${{ inputs.md_files || '2' }}
+          BENCH_MD_MIN_SIZE_BYTES: '128'
+          BENCH_MD_MAX_SIZE_BYTES: '256'
+          BENCH_BIN_FILE_COUNT: ${{ inputs.bin_files || '1' }}
+          BENCH_BIN_SIZE_BYTES: '512'
+          BENCH_SYNC_TIMEOUT: '180'
+          BENCH_PEERS_TIMEOUT: '60'
+          LIVESYNC_P2P_RELAY_READY_TIMEOUT_MS: '60000'
+          BENCH_LIVESYNC_TEST_TEE: '0'
+          NETEM_PROFILE: 'home-wifi'
+        run: docker compose -f test/bench-network/compose.yml --profile signalling-shim run --build --rm bench-runner-signalling-shim
+
+      - name: Show Compose diagnostics
+        if: failure()
+        run: |
+          docker compose -f test/bench-network/compose.yml ps
+          docker compose -f test/bench-network/compose.yml --profile signalling-shim logs --no-color couchdb nostr-relay p2p-signalling-shim || true
+
+      - name: Upload benchmark results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-p2p-compose-smoke-results
+          path: test/bench-network/bench-results/**
+          if-no-files-found: warn
+
+      - name: Stop Compose services
+        if: always()
+        run: docker compose -f test/bench-network/compose.yml down -v --remove-orphans

.github/workflows/deploy-pages.yml

@@ -0,0 +1,67 @@
+name: Deploy GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'aggregator.html'
+      - '.github/workflows/deploy-pages.yml'
+  pull_request:
+    paths:
+      - 'aggregator.html'
+      - '.github/workflows/deploy-pages.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Validate and package Pages site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate aggregator
+        run: |
+          test -s aggregator.html
+          grep -Fq '<!DOCTYPE html>' aggregator.html
+          grep -Fq 'obsidian://setuplivesync?settingsQR=' aggregator.html
+          sed -n '/<script>/,/<\/script>/p' aggregator.html | sed '1d;$d' > aggregator.js
+          node --check aggregator.js
+          rm aggregator.js
+
+      - name: Prepare Pages site
+        run: |
+          mkdir -p _site
+          cp aggregator.html _site/aggregator.html
+          touch _site/.nojekyll
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/finalise-release.yml

@@ -0,0 +1,128 @@
+name: Finalise Release Tags
+
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: Release version, for example 0.25.81
+                required: true
+                type: string
+            release_branch:
+                description: Release PR branch. Defaults to the version with dots replaced by underscores.
+                required: false
+                type: string
+            expected_head_sha:
+                description: Full head commit SHA reviewed in the release PR
+                required: true
+                type: string
+            prerelease:
+                description: Mark the GitHub Release as a pre-release
+                required: false
+                type: boolean
+                default: false
+            publish_cli:
+                description: Create the CLI tag and publish its container image
+                required: false
+                type: boolean
+                default: true
+
+jobs:
+    finalise:
+        runs-on: ubuntu-latest
+        environment: release
+        permissions:
+            actions: write
+            contents: write
+        steps:
+            - name: Resolve release branch
+              id: branch
+              env:
+                  VERSION: ${{ inputs.version }}
+                  RELEASE_BRANCH_INPUT: ${{ inputs.release_branch }}
+              run: |
+                  set -euo pipefail
+                  BRANCH="${RELEASE_BRANCH_INPUT}"
+                  if [[ -z "${BRANCH}" ]]; then
+                    BRANCH="${VERSION//./_}"
+                  fi
+                  echo "name=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+            - uses: actions/checkout@v4
+              with:
+                  ref: ${{ steps.branch.outputs.name }}
+                  fetch-depth: 0
+
+            - name: Use Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24.x"
+
+            - name: Validate release head
+              env:
+                  VERSION: ${{ inputs.version }}
+                  EXPECTED_HEAD_SHA: ${{ inputs.expected_head_sha }}
+                  PRERELEASE: ${{ inputs.prerelease }}
+              run: |
+                  set -euo pipefail
+                  ACTUAL_HEAD_SHA="$(git rev-parse HEAD)"
+                  if [[ "${ACTUAL_HEAD_SHA}" != "${EXPECTED_HEAD_SHA}" ]]; then
+                    echo "Release branch head is ${ACTUAL_HEAD_SHA}, expected ${EXPECTED_HEAD_SHA}." >&2
+                    exit 1
+                  fi
+                  if [[ "${VERSION}" == *-* && "${PRERELEASE}" != "true" ]]; then
+                    echo "Version ${VERSION} is a pre-release version, but prerelease was not enabled." >&2
+                    exit 1
+                  fi
+                  node utils/release-notes.mjs validate "${VERSION}"
+
+            - name: Ensure and push release tags
+              env:
+                  VERSION: ${{ inputs.version }}
+                  EXPECTED_HEAD_SHA: ${{ inputs.expected_head_sha }}
+                  PUBLISH_CLI: ${{ inputs.publish_cli }}
+              run: |
+                  set -euo pipefail
+                  git fetch --tags --force
+                  if [[ "${PUBLISH_CLI}" == "true" ]]; then
+                    node utils/release-tags.mjs ensure "${VERSION}" "${EXPECTED_HEAD_SHA}"
+                    git push --atomic origin "refs/tags/${VERSION}" "refs/tags/${VERSION}-cli"
+                  else
+                    node utils/release-tags.mjs ensure "${VERSION}" "${EXPECTED_HEAD_SHA}" --plugin-only
+                    git push origin "refs/tags/${VERSION}"
+                  fi
+
+            - name: Dispatch release workflows
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  VERSION: ${{ inputs.version }}
+                  PRERELEASE: ${{ inputs.prerelease }}
+              run: |
+                  set -euo pipefail
+                  gh workflow run release.yml \
+                    --ref "${VERSION}" \
+                    --field tag="${VERSION}" \
+                    --field draft=true \
+                    --field prerelease="${PRERELEASE}"
+
+            - name: Summarise next steps
+              env:
+                  VERSION: ${{ inputs.version }}
+                  PRERELEASE: ${{ inputs.prerelease }}
+                  PUBLISH_CLI: ${{ inputs.publish_cli }}
+              run: |
+                  {
+                    echo "Ensured the plug-in tag \`${VERSION}\` points to the reviewed release commit."
+                    if [[ "${PUBLISH_CLI}" == "true" ]]; then
+                      echo "The CLI tag \`${VERSION}-cli\` was also created; its tag event starts the container workflow."
+                    else
+                      echo "CLI publication was omitted."
+                    fi
+                    echo ""
+                    echo "Dispatched the plug-in release workflow for \`${VERSION}\`. After approval for the release environment, it creates a draft GitHub Release."
+                    echo ""
+                    if [[ "${PRERELEASE}" == "true" ]]; then
+                      echo "Publish the draft as a pre-release, keep the release pull request in draft, and merge only after BRAT validation succeeds."
+                    else
+                      echo "Publish the draft as the latest stable release, keep the release pull request in draft, and merge only after BRAT validation succeeds."
+                    fi
+                  } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/prepare-release.yml

@@ -0,0 +1,97 @@
+name: Prepare Release PR
+
+on:
+    workflow_dispatch:
+        inputs:
+            version:
+                description: Release version, for example 0.25.81
+                required: true
+                type: string
+            base_branch:
+                description: Base branch for the release PR
+                required: false
+                type: string
+                default: main
+            release_branch:
+                description: Release branch name. Defaults to the version with dots replaced by underscores.
+                required: false
+                type: string
+            release_date:
+                description: Release date in ordinal format. Defaults to the current UTC date.
+                required: false
+                type: string
+            allow_empty_updates:
+                description: Allow an empty Unreleased section
+                required: false
+                type: boolean
+                default: false
+
+jobs:
+    prepare:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  ref: ${{ inputs.base_branch }}
+                  fetch-depth: 0
+
+            - name: Use Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: "24.x"
+                  cache: npm
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Prepare release changes
+              id: prepare
+              env:
+                  VERSION: ${{ inputs.version }}
+                  RELEASE_BRANCH_INPUT: ${{ inputs.release_branch }}
+                  RELEASE_DATE: ${{ inputs.release_date }}
+                  ALLOW_EMPTY_UPDATES: ${{ inputs.allow_empty_updates }}
+              run: |
+                  set -euo pipefail
+                  git config user.name "github-actions[bot]"
+                  git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+                  BRANCH="${RELEASE_BRANCH_INPUT}"
+                  if [[ -z "${BRANCH}" ]]; then
+                    BRANCH="${VERSION//./_}"
+                  fi
+
+                  if git ls-remote --exit-code --heads origin "${BRANCH}" >/dev/null 2>&1; then
+                    echo "Release branch already exists: ${BRANCH}" >&2
+                    exit 1
+                  fi
+
+                  git switch -c "${BRANCH}"
+                  npm version "${VERSION}" --no-git-tag-version --allow-same-version
+                  node utils/release-notes.mjs prepare "${VERSION}"
+
+                  git add package.json package-lock.json manifest.json versions.json updates.md src/apps/cli/package.json src/apps/webpeer/package.json src/apps/webapp/package.json
+                  git diff --cached --check
+                  git commit -m "Releasing ${VERSION}"
+                  git push --set-upstream origin "${BRANCH}"
+
+                  echo "branch=${BRANCH}" >> "$GITHUB_OUTPUT"
+
+            - name: Create draft release PR
+              env:
+                  GH_TOKEN: ${{ github.token }}
+                  VERSION: ${{ inputs.version }}
+                  BASE_BRANCH: ${{ inputs.base_branch }}
+                  RELEASE_BRANCH: ${{ steps.prepare.outputs.branch }}
+              run: |
+                  node utils/release-pr-body.mjs "${VERSION}" "${BASE_BRANCH}" > /tmp/release-pr-body.md
+
+                  gh pr create \
+                    --base "${BASE_BRANCH}" \
+                    --head "${RELEASE_BRANCH}" \
+                    --draft \
+                    --title "Releasing ${VERSION}" \
+                    --body-file /tmp/release-pr-body.md

.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release Obsidian Plugin
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to build
+        required: true
+        type: string
+      draft:
+        description: Create the GitHub Release as a draft
+        required: false
+        type: boolean
+        default: true
+      prerelease:
+        description: Mark the GitHub Release as a pre-release
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        ref: ${{ inputs.tag }}
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24.x'
+    - name: Validate release
+      env:
+        TAG: ${{ inputs.tag }}
+      run: |
+        set -euo pipefail
+        node utils/release-notes.mjs validate "${TAG}"
+        HEAD_SHA="$(git rev-parse HEAD)"
+        TAG_SHA="$(git rev-parse "refs/tags/${TAG}^{commit}")"
+        if [[ "${HEAD_SHA}" != "${TAG_SHA}" ]]; then
+          echo "Checked-out commit is ${HEAD_SHA}, but tag ${TAG} points to ${TAG_SHA}." >&2
+          exit 1
+        fi
+    # Build the plugin
+    - name: Build
+      id: build
+      run: |
+        npm ci
+        npm run build --if-present
+    # Attest
+    - name: Attest Plugin Artifacts
+      uses: actions/attest-build-provenance@v4
+      with:
+          subject-path: |
+              main.js
+              manifest.json
+              styles.css
+    - name: Create Release and Upload Assets
+      uses: softprops/action-gh-release@v2
+      with:
+        files: |
+          main.js
+          manifest.json
+          styles.css
+        name: ${{ inputs.tag }}
+        tag_name: ${{ inputs.tag }}
+        draft: ${{ inputs.draft }}
+        prerelease: ${{ inputs.prerelease }}

.github/workflows/unit-ci.yml

@@ -0,0 +1,211 @@
+# Run Unit test without Harnesses
+name: unit-ci
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - beta
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - 'vite.config.ts'
+      - 'vitest.config*.ts'
+      - 'esbuild.config.mjs'
+      - 'eslint.config.mjs'
+      - 'eslint.config.common.mjs'
+      - 'eslint.community.config.mjs'
+      - 'update-workspaces.mjs'
+      - 'version-bump.mjs'
+      - 'utils/release-*.mjs'
+      - 'utils/release-*.unit.spec.ts'
+      - 'utils/couchdb/**'
+      - 'utils/flyio/**'
+      - 'utils/setup/**'
+      - '.github/workflows/prepare-release.yml'
+      - '.github/workflows/finalise-release.yml'
+      - '.github/workflows/release.yml'
+      - '.github/workflows/unit-ci.yml'
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - 'vite.config.ts'
+      - 'vitest.config*.ts'
+      - 'esbuild.config.mjs'
+      - 'eslint.config.mjs'
+      - 'eslint.config.common.mjs'
+      - 'eslint.community.config.mjs'
+      - 'update-workspaces.mjs'
+      - 'version-bump.mjs'
+      - 'utils/release-*.mjs'
+      - 'utils/release-*.unit.spec.ts'
+      - 'utils/couchdb/**'
+      - 'utils/flyio/**'
+      - 'utils/setup/**'
+      - '.github/workflows/prepare-release.yml'
+      - '.github/workflows/finalise-release.yml'
+      - '.github/workflows/release.yml'
+      - '.github/workflows/unit-ci.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  setup-tools:
+    name: Self-hosted setup tools
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run setup-tool contract tests
+        run: npm run test:setup-tools
+
+      - name: Create CouchDB test configuration
+        run: |
+          cat <<EOF > .test.env
+          hostname=http://127.0.0.1:5989/
+          dbname=livesync-test-db
+          username=admin
+          password=testpassword
+          EOF
+
+      - name: Start CouchDB
+        run: npm run test:docker-couchdb:start
+
+      - name: Provision a versioned LiveSync database
+        run: npx dotenv-cli -e .test.env -- env database=setup-tools-ci retry_count=1 retry_delay_ms=0 ./utils/couchdb/couchdb-init.sh
+
+      - name: Verify the Commonlib database version
+        run: |
+          npx dotenv-cli -e .test.env -- bash -lc 'curl --fail --silent --show-error --user "${username}:${password}" "${hostname}/setup-tools-ci/obsydian_livesync_version" | node --input-type=module -e "import { VER } from \"@vrtmrz/livesync-commonlib/compat/common/types\";let input=\"\";process.stdin.on(\"data\",chunk=>input+=chunk).on(\"end\",()=>{const document=JSON.parse(input);if(document.type!==\"versioninfo\"||document.version!==VER)throw new Error(\"Unexpected LiveSync database version\");})"'
+
+      - name: Stop CouchDB
+        if: always()
+        run: npm run test:docker-couchdb:stop || true
+
+  unit-test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run source checks
+        run: npm run check
+
+      - name: Run unit tests suite with coverage
+        run: npm run test:unit:coverage
+
+      - name: Run real-Obsidian runner contract tests
+        run: npm run test:e2e:obsidian:runner
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: unit-coverage-report
+          path: coverage/**
+
+  integration-test:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Detect LiveSync-owned integration tests
+        id: integration_tests
+        shell: bash
+        run: |
+          git ls-files -- ':(glob)**/*.integration.spec.ts' ':(glob)**/*.integration.test.ts' > "$RUNNER_TEMP/livesync-integration-tests.txt"
+          if [[ -s "$RUNNER_TEMP/livesync-integration-tests.txt" ]]; then
+            echo 'present=true' >> "$GITHUB_OUTPUT"
+          else
+            echo 'present=false' >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Record delegated integration coverage
+        if: ${{ steps.integration_tests.outputs.present != 'true' }}
+        run: echo 'No LiveSync-owned integration tests are present. Commonlib integration tests run in the Commonlib package CI.' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Setup Node.js
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        run: npm ci
+
+      - name: Create environment configuration files
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        run: |
+          cat <<EOF > .env
+          BUILD_MODE=dev
+          PATHS_TEST_INSTALL=
+          EOF
+          cat <<EOF > .test.env
+          hostname=http://127.0.0.1:5989/
+          dbname=livesync-test-db2
+          username=admin
+          password=testpassword
+          minioEndpoint=http://127.0.0.1:9000
+          accessKey=minioadmin
+          secretKey=minioadmin
+          bucketName=livesync-test-bucket
+          EOF
+
+      - name: Start CouchDB container
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        run: npm run test:docker-couchdb:start
+
+      - name: Start MinIO container
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        run: npm run test:docker-s3:start
+
+      - name: Run integration tests
+        if: ${{ steps.integration_tests.outputs.present == 'true' }}
+        run: npm run test:integration
+
+      - name: Stop containers
+        if: ${{ always() && steps.integration_tests.outputs.present == 'true' }}
+        run: |
+          npm run test:docker-couchdb:stop || true
+          npm run test:docker-s3:stop || true

.gitignore

@@ -8,7 +8,29 @@ package-lock.json
 
 # build
 main.js
+main_org.js
+main_org_*.js
 *.js.map
+meta.json
+meta-*.json
+
 
 # obsidian
 data.json
+.vscode
+
+# environment variables
+.env
+
+# local config files
+*.local
+
+cov_profile/**
+
+coverage
+src/apps/cli/dist/*
+src/apps/webapp/playwright-report/
+src/apps/webapp/test-results/
+_testdata/**
+utils/bench/splitResults.csv
+.eslintcache

.prettierignore

@@ -0,0 +1,4 @@
+pouchdb-browser.js
+main_org.js
+main.js
+_types/**

.prettierrc.mjs

@@ -0,0 +1,20 @@
+import { readFileSync } from "fs";
+let localPrettierConfig = {};
+
+try {
+    const localConfig = readFileSync(".prettierrc.local", "utf-8");
+    localPrettierConfig = JSON.parse(localConfig);
+    console.log("Using local Prettier config from .prettierrc.local");
+} catch (e) {
+    // no local config
+}
+const prettierConfig = {
+    trailingComma: "es5",
+    tabWidth: 4,
+    printWidth: 120,
+    semi: true,
+    endOfLine: "lf",
+    ...localPrettierConfig,
+};
+
+export default prettierConfig;

.test.env

@@ -0,0 +1,11 @@
+hostname=http://localhost:5989/
+dbname=livesync-test-db2
+minioEndpoint=http://127.0.0.1:9000
+username=admin
+password=testpassword
+accessKey=minioadmin
+secretKey=minioadmin
+bucketName=livesync-test-bucket
+# ENABLE_DEBUGGER=true
+# PRINT_LIVESYNC_LOGS=true
+# ENABLE_UI=true

AGENTS.md

@@ -0,0 +1,69 @@
+# 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](docs/terms.md) for terminology, vocabulary conventions, and technical definitions.
+2. Read [docs/settings.md](docs/settings.md) (and [docs/settings_ja.md](docs/settings_ja.md)) for UI settings and setting key mappings.
+3. Read [docs/troubleshooting.md](docs/troubleshooting.md) for troubleshooting guidelines and common recovery steps (such as flag files and SCRAM state).
+4. Read [devs.md](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.
+
+5. **User Communication Language**:
+   - Always reply to the user in the language in which they asked the question.
+
+---
+
+## 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**:
+   - Treat `@vrtmrz/livesync-commonlib` as an external, authoritative package. Make Commonlib changes in its repository, validate the packed artefact and downstream LiveSync consumer, and update the exact dependency here. Do not recreate a `src/lib` source mirror or generated `_types` fallback.
+4. **Application Directories**:
+   - The directory [src/apps](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](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:unit:coverage` when unit-test coverage is required.
+   - Run focused integration, CLI E2E, or real Obsidian E2E commands for the boundary being changed. Start only the Docker services required by that command.
+3. **Build**:
+   - Run `npm run build` to compile the production bundle (`main.js`).
+   - Run `npm run dev` for the development watch/build task.

CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+We wish to maintain an open, welcoming, and collaborative environment for all contributors.
+
+## Our Standard
+
+Our core principle is mutual respect. We encourage open discussion, diverse perspectives, and constructive feedback.
+
+## The Limit of Tolerance
+
+To preserve a tolerant and open community, we do not tolerate intolerance. Actions that aim to harass, exclude, or silence others are not welcome. Specifically, we do not accept personal attacks, breaches of privacy, or sustained disruption of discussions. We prioritise protecting the community's capacity for open, peaceful collaboration.
+
+## Resolution
+
+If any issue arises, the project maintainers will resolve it in a fair, minimal, and constructive manner, aiming to restore a cooperative environment. Depending on the nature of the behaviour, actions may range from a simple warning to temporary or permanent suspension of repository access.
+
+## Contact
+
+You can contact the project maintainer via email at `vrtmrz@proton.me` or via Nostr at `npub1azzj0dzw8evwtgyjeucyfz5cs8k0eg7rd0x4qvggcg3s7lx0dmaqv9sfka`.
+
+## Criticism of the Maintainer
+
+To ensure open and transparent governance, criticism of the maintainer will not be deleted as long as it is clearly framed as a constructive objection. However, spamming duplicate issues on the same topic or resorting to personal attacks will result in closure or removal.
+
+## Revisions
+
+This Code of Conduct is maintained by the project maintainers and may be updated to address new challenges. While the final decision rests with the maintainers, we welcome constructive suggestions and feedback through issues or pull requests.

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Self-hosted LiveSync
+
+Thank you for your interest in contributing to Self-hosted LiveSync! We welcome all contributions, including bug reports, feature requests, documentation improvements, translations, and pull requests.
+
+## Getting Started
+
+To set up the development environment, please follow these steps:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/vrtmrz/obsidian-livesync
+   ```
+
+2. Install the package dependencies:
+   ```bash
+   npm ci
+   ```
+
+3. Build the plug-in:
+   ```bash
+   npm run build
+   ```
+
+For a more comprehensive guide on development workflows, testing configurations, and the Commonlib dependency, please refer to [devs.md](devs.md).
+
+## Guidelines for Contributions
+
+### 1. Code Style and Verification
+
+Before submitting a pull request, you must run verification scripts locally to ensure that there are no syntax, type, or linting errors:
+
+- Run type checking and linting:
+  ```bash
+  npm run check
+  ```
+  This also type-checks the maintained CLI and browser applications, and applies the Community directory blocker rules. Run `npm run lint:community` separately to inspect its non-blocking recommendations.
+- Run unit tests:
+  ```bash
+  npm run test:unit
+  ```
+
+If you have the capability and a suitable environment (such as Linux and Docker), running the CLI End-to-End (E2E) tests is also highly appreciated. Instructions are detailed in [devs.md](devs.md). If you cannot run E2E tests locally, please explicitly ask to run the tests on the CI by stating 'Please run CI tests' in your pull request description.
+
+### 2. Documentation and UI Text Style
+
+To maintain consistency across the project, we ask that you follow the established writing style and conventions of the codebase when contributing documentation or user-facing messages:
+
+- **Spelling**: Prioritise region-independent, neutral spelling if a suitable word exists. If there is no such word, please use British English spelling to align with the codebase's style (for example: preferring '-ise' and '-isation' suffixes over '-ize' and '-ization'). However, we do not treat alternative spellings as errors.
+- **Oxford Comma**: Use the serial (Oxford) comma to separate items in lists of three or more (for example: 'settings, snippets, and themes').
+- **Logical Punctuation**: Place punctuation marks outside quotation marks unless they are part of the quoted text itself (for example: write 'dialogue', not 'dialogue,').
+- **No Contractions**: Avoid using contractions in general text or documentation (for example: write "do not" instead of "don't", and "cannot" instead of "can't").
+- **Affirmative Phrasing**: Avoid asking questions using negative forms in user-facing dialogue. Use affirmative questions to prevent translation and interpretation discrepancies.
+- **Specific Words**: Use 'dialogue' for documentation and user-facing messages (use 'dialog' only inside source code). Use the hyphenated form 'plug-in' in user-facing text (use 'plugin' only in configuration settings or technical contexts).
+
+For a detailed list of vocabulary conventions and terms, please refer to [docs/terms.md](docs/terms.md).
+
+### 3. Translations
+
+To add or update translations, please refer to [docs/adding_translations.md](docs/adding_translations.md) for detailed instructions.
+
+### 4. Commonlib changes
+
+Shared synchronisation behaviour is provided by the `@vrtmrz/livesync-commonlib` package. If you wish to change that library, submit a separate pull request to the [livesync-commonlib repository](https://github.com/vrtmrz/livesync-commonlib), validate its packed artefact, then update the locked dependency in this repository. Do not add a source mirror or generated fallback declarations to this repository.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

README.md

@@ -1,93 +1,120 @@
 # Self-hosted LiveSync
+[Japanese docs](./README_ja.md) - [Chinese docs](./README_cn.md).
 
-Sorry for late! [Japanese docs](./README_ja.md) is also coming up.
 
-**Renamed from: obsidian-livesync**
+Self-hosted LiveSync is a community-developed synchronisation plug-in available on all Obsidian-compatible platforms. It leverages robust server solutions such as CouchDB or object storage systems (e.g., MinIO, S3, R2, etc.) to ensure reliable data synchronisation.
 
-Using a self-hosted database, live-sync to multi-devices bidirectionally.
-Runs in Mac, Android, Windows, and iOS. Perhaps available on Linux too.
-Community implementation, not compatible with official "Sync".
+Additionally, it supports peer-to-peer synchronisation using WebRTC, enabling you to synchronise your notes directly between devices without relying on a server. Documentation is available for [Peer-to-Peer Synchronisation](./docs/p2p_sync_updates_2026.md).
 
 ![obsidian_live_sync_demo](https://user-images.githubusercontent.com/45774780/137355323-f57a8b09-abf2-4501-836c-8cb7d2ff24a3.gif)
 
-**It's getting almost stable now, But Please make sure to back your vault up!**
+>[!IMPORTANT]
+> This plug-in is not compatible with the official "Obsidian Sync" and cannot synchronise with it.
 
-Limitations: ~~Folder deletion handling is not completed.~~ **It would work now.**
+## Features
+- Synchronise vaults efficiently with minimal traffic.
+- Handle conflicting modifications effectively.
+  - Automatically merge simple conflicts.
+- Use open-source solutions for the server.
+  - Compatible solutions are supported.
+- Support end-to-end encryption.
+- Synchronise settings, snippets, themes, and plug-ins via [Customisation Sync (Beta)](docs/settings.md#6-customisation-sync-advanced) or [Hidden File Sync](docs/tips/hidden-file-sync.md).
+- Enable WebRTC peer-to-peer synchronisation without requiring a `host` (Experimental).
+  - This feature is still in the experimental stage. Please exercise caution when using it.
+  - WebRTC is a peer-to-peer synchronisation method, so **at least one device must be online to synchronise**.
+  - Instead of keeping your device online as a stable peer, you can use two pseudo-peers:
+    - [livesync-serverpeer](https://github.com/vrtmrz/livesync-serverpeer): A pseudo-client running on the server for receiving and sending data between devices.
+    - [webpeer](https://github.com/vrtmrz/obsidian-livesync/tree/main/src/apps/webpeer): A pseudo-client for receiving and sending data between devices.
+    - A pre-built instance is available at [fancy-syncing.vrtmrz.net/webpeer](https://fancy-syncing.vrtmrz.net/webpeer/) (hosted on the vrtmrz's blog site). This is also peer-to-peer. Feel free to use it.
+  - For more information, refer to the [English explanatory article](https://fancy-syncing.vrtmrz.net/blog/0034-p2p-sync-en.html) or the [Japanese explanatory article](https://fancy-syncing.vrtmrz.net/blog/0034-p2p-sync).
 
-## This plugin enables...
+This plug-in may be particularly useful for researchers, engineers, and developers who need to keep their notes fully self-hosted for security reasons. It is also suitable for anyone seeking the peace of mind that comes with knowing their notes remain entirely private.
 
--   Runs in Windows, Mac, iPad, iPhone, Android, Chromebook
--   Synchronize to Self-hosted Database
--   Replicate to/from other devices bidirectionally near-real-time
--   Resolving synchronizing conflicts in the Obsidian.
--   You can use CouchDB or its compatibles like IBM Cloudant. CouchDB is OSS, and IBM Cloudant has the terms and certificates about security. Your notes are yours.
--   Off-line sync is also available.
--   End-to-End encryption is available (beta).
--   Receive WebClip from [obsidian-livesync-webclip](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf) (End-to-End encryption will not be applicable.)
+>[!IMPORTANT]
+> - Before installing or upgrading this plug-in, please back up your vault.
+> - Do not enable this plug-in alongside another synchronisation solution (including iCloud and Obsidian Sync).
+> - For backups, we also provide a plug-in called [Differential ZIP Backup](https://github.com/vrtmrz/diffzip).
 
-It must be useful for the Researcher, Engineer, Developer who has to keep NDA or something like agreement.
-Especially, in some companies, people have to store all data to their fully controlled host, even End-to-End encryption applied.
+## How to Use
 
-## IMPORTANT NOTICE
+### 3-minute setup - CouchDB on fly.io
 
--   Do not use with other synchronize solutions. Before enabling this plugin, make sure to disable other synchronize solutions, to avoid content corruption or duplication. If you want to synchronize to both backend, sync one by one, please.
-    This includes making your vault on the cloud-controlled folder(e.g., Inside the iCloud folder).
--   This is the synchronization plugin. Not backup solutions. Do not rely on this for backup.
--   When the device's storage has been run out, Database corruption may happen.
--   When editing hidden files or any other invisible files from obsidian, the file wouldn't be kept in the database. (**Or be deleted.**)
+**Recommended for beginners**
 
-## Supplements
+[![LiveSync Setup onto Fly.io SpeedRun 2024 using Google Colab](https://img.youtube.com/vi/7sa_I1832Xc/0.jpg)](https://www.youtube.com/watch?v=7sa_I1832Xc)
 
--   When the file has been deleted, the deletion of the file is replicated to other devices.
--   When the folder became empty by replication, The folder will be deleted in the default setting. But you can change this behaivour. Check the [Settings](docs/settings.md).
--   LiveSync drains many batteries in mobile devices.
--   Mobile Obsidian can not connect to the non-secure(HTTP) or local CA-signed servers, even though the certificate is stored in the device store.
--   There are no 'exclude_folders' like configurations.
+1. [Set up CouchDB on fly.io](docs/setup_flyio.md)
+2. Configure plug-in in [Quick Setup](docs/quick_setup.md)
 
-## How to use
+### Setup workflows
 
-1. Install from Obsidian, or download from this repo's releases, copy `main.js`, `styles.css` and `manifest.json` into `[your-vault]/.obsidian/plugins/`
-2. Get your database. IBM Cloudant is preferred for testing. Or you can use your own server with CouchDB.
-   For more information, refer below:
-    1. [Setup IBM Cloudant](docs/setup_cloudant.md)
-    2. [Setup your CouchDB](docs/setup_own_server.md)
-3. Enter connection information to Plugin's setting dialog. In details, refer [Settings of Self-hosted LiveSync](docs/settings.md)
-4. Enable LiveSync or other Synchronize method as you like.
+Choose a synchronisation method, prepare its server where required, then follow the corresponding client setup:
 
-## Test Server
+1. CouchDB
+   1. Prepare the server:
+      - [Set up your own CouchDB server](docs/setup_own_server.md).
+      - [Set up CouchDB on fly.io](docs/setup_flyio.md).
+   2. Configure the clients by following [CouchDB Quick Setup](docs/quick_setup.md).
+2. Object Storage
+   1. Prepare the server. A maintained MinIO server installation guide is not currently available here, so set up an S3-compatible service or server of your choice.
+   2. Configure the clients by following [Object Storage Setup](docs/setup_object_storage.md).
+3. Peer-to-Peer
+   1. No server setup is required.
+   2. Configure the clients by following [Peer-to-Peer Setup](docs/setup_p2p.md).
 
-Setting up an instance of Cloudant or local CouchDB is a little complicated, so I made the [Tasting server of self-hosted-livesync](https://olstaste.vrtmrz.net/) up. Try free!  
-Note: Please read "Limitations" carefully. Do not send your private vault.
+Each workflow establishes ordinary note synchronisation on the first device, generates the additional-device Setup URI from that working device, and verifies synchronisation in both directions.
 
-## WebClipper is also available.
+> [!TIP]
+> Fly.io is no longer free. Fortunately, we can still use IBM Cloudant despite some limitations. Refer to [Set up IBM Cloudant](docs/setup_cloudant.md).
+> We can also use peer-to-peer synchronisation without a server. Alternatively, cheap object storage like Cloudflare R2 can be used for free.
+> However, most importantly, we can use a server that we trust. Therefore, please set up your own server.
+> CouchDB can also be run on a Raspberry Pi (please be mindful of your server's security).
 
-Available from on Chrome Web Store:[obsidian-livesync-webclip](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf)  
-Repo is here: [obsidian-livesync-webclip](https://github.com/vrtmrz/obsidian-livesync-webclip). (Docs are work in progress.)
 
-# Information in StatusBar
+## Information in the Status Bar
 
-Synchronization status is shown in statusbar.
+Synchronisation status is shown in the status bar with the following icons.
 
+-   Activity Indicator
+    -   📲 A finite remote operation is in progress
+    -   🌐N Approximate remote requests currently in progress
 -   Status
     -   ⏹️ Stopped
-    -   💤 LiveSync is enabled. Waiting for changes.
-    -   ⚡️ Synchronize is now in progress.
-    -   ⚠ Error occurred.
--   ↑ Uploaded pieces
--   ↓ Downloaded pieces
--   ⏳ Count of the pending process  
-If you have deleted or renamed files, please wait until this disappears.
+    -   💤 LiveSync enabled. Waiting for changes
+    -   ⚡️ Synchronisation in progress
+    -   ⚠ An error occurred
+-   Statistical Indicators
+     -   ↑ Uploaded chunks and metadata
+     -   ↓ Downloaded chunks and metadata
+-   Progress Indicators
+     -   📥 Unprocessed transferred items
+     -   📄 Working database operation
+     -   💾 Working write storage processes
+     -   ⏳ Working read storage processes
+     -   🛫 Pending read storage processes
+     -   📬 Batched read storage processes
+     -   ⚙️ Working or pending storage processes for hidden files
+     -   🧩 Waiting chunks
+     -   🔌 Working customisation items (configuration, snippets, and plug-ins)
 
-# More supplements
+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.
 
--   When synchronized, files are compared by their modified times and overwritten by the newer ones once. Then plugin checks the conflicts and if a merge is needed, the dialog will open.
--   Rarely, the file in the database would be broken. The plugin will not write storage when it looks broken, so some old files must be on your device. If you edit the file, it will be cured. But if the file does not exist on any device, can not rescue it. So you can delete these items from the setting dialog.
--   If your database looks corrupted, try "Drop History". Usually, It is the easiest way.
--   To stop the bootup sequence for fixing problems on databases, you can put `redflag.md` on top of your vault.
--   Q: Database is growing, how can I shrink it up?
-    A: each of the docs is saved with their old 100 revisions to detect and resolve confliction. Picture yourself that one device has been off the line for a while, and joined again. The device has to check his note and remote saved note. If exists in revision histories of remote notes even though the device's note is a little different from the latest one, it could be merged safely. Even if that is not in revision histories, we only have to check differences after the revision that both devices commonly have. This is like The git's conflict resolving method. So, We have to make the database again like an enlarged git repo if you want to solve the root of the problem.
--   And more technical Information are in the [Technical Information](docs/tech_info.md)
+## Tips and Troubleshooting
+- If you want a faster and simpler initial replication when setting up subsequent devices, see the [Fast Setup Guide](docs/tips/fast-setup.md).
+- Configure [Hidden File Sync](docs/tips/hidden-file-sync.md) only after ordinary note synchronisation works.
+- If you are having problems getting the plug-in working, see [Tips and Troubleshooting](docs/troubleshooting.md).
 
-# License
+## Acknowledgements
+The project has been in continual progress and harmony thanks to the following:  
+- Many [Contributors](https://github.com/vrtmrz/obsidian-livesync/graphs/contributors).  
+- Many [GitHub Sponsors](https://github.com/sponsors/vrtmrz#sponsors).  
+- JetBrains Community Programs / Support for Open-Source Projects. <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains logo" height="24">  
 
-The source code is licensed MIT.
+May those who have contributed be honoured and remembered for their kindness and generosity.
+
+## Development Guide
+Please refer to the [Development Guide](devs.md) for development setup, testing infrastructure, code conventions, and more.
+
+## License
+
+Licensed under the MIT License.

README_cn.md

@@ -0,0 +1,107 @@
+# Self-hosted LiveSync
+
+Self-hosted LiveSync (自搭建在线同步) 是一个社区实现的在线同步插件。  
+它利用诸如CouchDB或对象存储系统（例如MinIO、S3、R2等）等强大的服务器解决方案，以确保数据同步的可靠性。。兼容所有支持 Obsidian 的平台。
+
+此外，它现在支持使用WebRTC进行点对点同步（实验性功能），使您无需依赖服务器即可直接在设备之间同步笔记。
+
+>[!IMPORTANT]
+>本插件与官方的 "Obsidian Sync" 服务不兼容。
+
+![obsidian_live_sync_demo](https://user-images.githubusercontent.com/45774780/137355323-f57a8b09-abf2-4501-836c-8cb7d2ff24a3.gif)
+
+安装或升级 LiveSync 之前，请备份你的 vault。
+
+## 功能
+
+-   以最少流量高效同步vault
+-   有效处理冲突的修改。
+  - 自动合并简单冲突。
+- 服务端使用开源的解决方案
+  - 支持兼容的解决方案。
+- 支持端到端加密。
+- 同步设置、代码片段、主题和插件，通过 [Customisation Sync (Beta)](docs/settings.md#6-customization-sync-advanced) 或者 [Hidden File Sync](docs/settings.md#7-hidden-files-advanced).
+- 启用 WebRTC 点对点同步，无需指定 `host`（实验性）。
+  - 此功能仍处于试验阶段。请在使用时务必谨慎。
+  - WebRTC 是一种点对点同步方法，因此**至少有一台设备必须在线才能进行同步**。
+  - 与其让您的设备作为稳定的对等节点保持在线，您可以使用两个 pseudo-peers:
+    - [livesync-serverpeer](https://github.com/vrtmrz/livesync-serverpeer): 在服务器上运行的 pseudo-client 用于在设备之间接收和发送数据。
+    - [webpeer](https://github.com/vrtmrz/livesync-commonlib/tree/main/apps/webpeer): 用于在设备之间接收和发送数据的pseudo-client。
+    - 一个预构建的实例现已上线，地址为 [fancy-syncing.vrtmrz.net/webpeer](https://fancy-syncing.vrtmrz.net/webpeer/) (托管于vrtmrz博客网站). 这也是一个点对点的实例。可自由使用。
+  - 欲了解更多信息，请参阅[英文说明文章](https://fancy-syncing.vrtmrz.net/blog/0034-p2p-sync-en.html)或[日文说明文章](https://fancy-syncing.vrtmrz.net/blog/0034-p2p-sync)。
+
+此插件适用于出于安全原因需要将笔记完全自托管的研究人员、工程师或开发人员，以及任何喜欢笔记完全私密所带来的安全感的人。
+
+>[!IMPORTANT]
+> - 在安装或升级此插件之前，请务必备份您的保险库。
+> - 请勿同时启用此插件与其它同步方案（包括iCloud和Obsidian Sync）。
+> - 对于备份，我们还提供了一款名为[Differential ZIP Backup](https://github.com/vrtmrz/diffzip)的插件。
+
+## 如何使用
+
+### 3分钟搞定——在fly.io上部署CouchDB
+
+**推荐初学者第一次使用此方法**
+[![LiveSync Setup onto Fly.io SpeedRun 2024 using Google Colab](https://img.youtube.com/vi/7sa_I1832Xc/0.jpg)](https://www.youtube.com/watch?v=7sa_I1832Xc)
+
+1. [Setup CouchDB on fly.io](docs/setup_flyio.md)
+2. 在 [Quick Setup](docs/quick_setup.md) 中配置插件。
+
+### 手动设置
+
+1. 配置服务器
+   1. [在fly.io上快速搭建CouchDB](docs/setup_flyio.md)
+   2. [自行搭建CouchDB](docs/setup_own_server.md)
+2. 在[快速设置](docs/quick_setup.md)中配置插件
+   
+> [!提示]
+> Fly.io现已不再免费。不过，尽管存在一些问题，我们仍可使用IBM Cloudant。请参考[搭建IBM Cloudant](docs/setup_cloudant.md)。
+> 此外，我们还可以采用点对点同步方式，无需搭建服务器；或者选用价格极低的对象存储——Cloudflare R2可免费使用。
+> 但最重要的是，我们可以选择自己信任的服务器。因此，建议您搭建自有服务器
+> CouchDB可在树莓派上运行。（但请务必注意服务器的安全性）。
+
+
+
+## 状态栏中的信息
+
+同步状态显示在状态栏中，采用以下图标。
+
+-   活动指示器
+    -   📲 网络请求
+-   状态
+    -   ⏹️ 已停止
+    -   💤 LiveSync已启用，正在等待更改
+    -   ⚡️ 同步中
+    -   ⚠ 发生了错误
+-   统计指标
+     -   ↑ 上传的分块与元数据
+     -   ↓ 下载的分块与元数据
+-   进度指示器
+     -   📥 未处理的传输项
+     -   📄 正在进行的数据库操作
+     -   💾 正在进行的写入存储进程
+     -   ⏳ 正在进行的读取存储进程
+     -   🛫 待处理的读取存储进程
+     -   📬 批量处理的读取存储进程
+     -   ⚙️ 正在进行或待处理的隐藏文件存储进程
+     -   🧩 等待中的分块
+     -   🔌 正在进行的自定义项（配置、代码片段和插件）
+
+为避免文件和数据库损坏，请等待所有进度指示器尽可能消失后再关闭 Obsidian（插件也会尝试恢复同步进度）。特别是在您已删除或重命名文件的情况下，请务必遵守此操作。
+
+
+## 使用技巧与故障排除
+如果您在配置插件时遇到问题，请参阅：[Tips and Troubleshooting](docs/troubleshooting.md). 
+
+
+## 致谢
+本项目得以持续顺利推进，离不开以下各方的贡献：  
+- 众多[贡献者](https://github.com/vrtmrz/obsidian-livesync/graphs/contributors)。  
+- 许多[GitHub 赞助人](https://github.com/sponsors/vrtmrz#sponsors)。  
+- JetBrains 社区计划／对开源项目的支持。<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains logo" height="24">  
+
+愿所有作出贡献的人士因其善良与慷慨而受到尊敬与铭记。
+
+## 许可协议
+
+本项目采用 MIT 许可协议授权。

README_es.md

@@ -0,0 +1,93 @@
+<!-- For translation: 20240227r0 -->
+# Self-hosted LiveSync
+[Documentación en inglés](./README_ja.md) - [Documentación en japonés](./README_ja.md) - [Documentación en chino](./README_cn.md).
+
+Self-hosted LiveSync es un plugin de sincronización implementado por la comunidad, disponible en todas las plataformas compatibles con Obsidian y utiliza CouchDB o Almacenamiento de Objetos (por ejemplo, MinIO, S3, R2, etc.) como servidor.
+
+![Demostración de Obsidian Live Sync](https://user-images.githubusercontent.com/45774780/137355323-f57a8b09-abf2-4501-836c-8cb7d2ff24a3.gif)
+
+Nota: Este plugin no puede sincronizarse con el "Obsidian Sync" oficial.
+
+## Características
+
+- Sincroniza bóvedas de manera eficiente con menos tráfico.
+- Buen manejo de modificaciones en conflicto.
+  - Fusión automática para conflictos simples.
+- Uso de soluciones de código abierto para el servidor.
+  - Pueden usarse soluciones compatibles.
+- Soporte de cifrado de extremo a extremo.
+- Sincronización de configuraciones, fragmentos, temas y complementos a través de [Sincronización de personalización \(Beta\)](#customization-sync) o [Sincronización de archivos ocultos](#hiddenfilesync)
+- WebClip de [obsidian-livesync-webclip](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf)
+
+Este plugin puede ser útil para investigadores, ingenieros y desarrolladores que necesitan mantener sus notas totalmente autoalojadas por razones de seguridad, o para aquellos que deseen tener la tranquilidad de saber que sus notas son totalmente privadas.
+
+>[!IMPORTANTE]
+> - Antes de instalar o actualizar este plugin, realice un respaldo de su bóveda.
+> - No active este plugin junto con otra solución de sincronización al mismo tiempo (incluyendo iCloud y Obsidian Sync).
+> - Este es un plugin de sincronización, no una solución de respaldo. No confíe en él para realizar respaldos.
+
+## Cómo usar
+
+### Configuración en 3 minutos - CouchDB en fly.io
+
+**Recomendado para principiantes**
+
+[![Configuración de LiveSync en Fly.io 2024 usando Google Colab](https://img.youtube.com/vi/7sa_I1832Xc/0.jpg)](https://www.youtube.com/watch?v=7sa_I1832Xc)
+
+1. [Configurar CouchDB en fly.io](docs/setup_flyio_es.md)
+2. Configurar el plugin en [Configuración rápida](docs/quick_setup_es.md)
+
+### Configuración manual
+
+1. Configurar el servidor
+   1. [Configurar CouchDB en fly.io](docs/setup_flyio_es.md)
+   2. [Configurar su CouchDB](docs/setup_own_server_es.md)
+2. Configura el plugin en [Configuración rápida](docs/quick_setup_es.md)
+
+> [!CONSEJO]
+> Actualmente, fly.io ya no es gratuito. Afortunadamente, aunque hay algunos problemas, aún podemos usar IBM Cloudant. Aquí está como [Configurar IBM Cloudant](docs/setup_cloudant.md). ¡Se actualizará pronto!
+
+
+## Información en la barra de estado
+
+El estado de sincronización se muestra en la barra de estado con los siguientes iconos.
+
+-   Indicador de actividad
+    -   📲 Solicitud de red
+-   Estado
+    -   ⏹️ Detenido
+    -   💤 LiveSync activado. Esperando cambios
+    -   ⚡️ Sincronización en progreso
+    -   ⚠ Ocurrió un error
+-   Indicador estadístico
+     -   ↑ Chunks y metadatos subidos
+     -   ↓ Chunks y metadatos descargados
+-   Indicador de progreso
+     -   📥 Elementos transferidos sin procesar
+     -   📄 Operación de base de datos en curso
+     -   💾 Procesos de escritura en almacenamiento en curso
+     -   ⏳ Procesos de lectura en almacenamiento en curso
+     -   🛫 Procesos de lectura en almacenamiento pendientes
+     -   📬 Procesos de lectura en almacenamiento por lotes
+     -   ⚙️ Procesos de almacenamiento de archivos ocultos en curso o pendientes
+     -   🧩 Chunks en espera
+     -   🔌 Elementos de personalización en curso (Configuración, fragmentos y plugins)
+
+Para prevenir la corrupción de archivos y bases de datos, antes de detener Obsidian espere hasta que todos los indicadores de progreso hayan desaparecido (el plugin también intentará reanudar, sin embargo). Especialmente en caso de que haya eliminado o renombrado archivos.
+
+
+## Consejos y Solución de Problemas
+Si tienes problemas para hacer funcionar el plugin, consulta: [Consejos y solución de problemas](docs/troubleshooting_es.md).
+
+## Agradecimientos
+
+El proyecto ha progresado y mantenido en armonía gracias a:
+- Muchos [Colaboradores](https://github.com/vrtmrz/obsidian-livesync/graphs/contributors)
+- Muchos [Patrocinadores de GitHub](https://github.com/sponsors/vrtmrz#sponsors)
+- Programas comunitarios de JetBrains / Soporte para Proyectos de Código Abierto <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains logo." height="24">
+
+Que aquellos que han contribuido sean honrados y recordados por su amabilidad y generosidad.
+
+## Licencia
+
+Licenciado bajo la Licencia MIT.

README_ja.md

@@ -1,96 +1,86 @@
+<!-- For translation: 20240227r0 -->
 # Self-hosted LiveSync
+[英語版ドキュメント](./README.md) - [中国語版ドキュメント](./README_cn.md).
 
-**旧): obsidian-livesync**
+Obsidianで利用可能なすべてのプラットフォームで使える、CouchDBをサーバに使用する、コミュニティ版の同期プラグイン
 
-セルフホストしたデータベースを使って、双方向のライブシンクするObsidianのプラグイン。  
-**公式のSyncとは互換性はありません**  
 ![obsidian_live_sync_demo](https://user-images.githubusercontent.com/45774780/137355323-f57a8b09-abf2-4501-836c-8cb7d2ff24a3.gif)
 
-**ほぼ動くようになってきましたが、Vaultのバックアップは確実に取得してください**
-
-[英語版](./README.md)
-
-## こんなことができるプラグインです。
-- Windows, Mac, iPad, iPhone, Android, Chromebookで動く
-- セルフホストしたデータベースに同期して
-- 複数端末で同時にその変更をほぼリアルタイムで配信し
-- さらに、他の端末での変更も別の端末に配信する、双方向リアルタイムなLiveSyncを実現でき、
-- 発生した変更の衝突はその場で解決できます。
-- 同期先のホストにはCouchDBまたはその互換DBaaSのIBM Cloudantをサーバーに使用できます。あなたのデータは、あなたのものです。
-- もちろんLiveではない同期もできます。
-- 万が一のために、サーバーに送る内容を暗号化できます(betaです)。
--  [Webクリッパー](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf) もあります(End-to-End暗号化対象外です)
-
-NDAや類似の契約や義務、倫理を守る必要のある、研究者、設計者、開発者のような方に特にオススメです。  
-特にエンタープライズでは、たとえEnd to Endの暗号化が行われていても、管理下にあるサーバーにのみデータを格納することが求められる場合があります。  
-
-# 重要なお知らせ
-
-- ❌ファイルの重複や破損を避けるため、複数の同期手段を同時に使用しないでください。  
-これは、Vaultをクラウド管理下のフォルダに置くことも含みます。(例えば、iCloudの管理フォルダ内に入れたり)。  
-- ⚠️このプラグインは、端末間でのノートの反映を目的として作成されました。バックアップ等が目的ではありません。そのため、バックアップは必ず別のソリューションで行うようにしてください。
-- ストレージの空き容量が枯渇した場合、データベースが破損することがあります。
-- 隠しファイルやObsidisanが認識できないファイルを編集した場合、そのファイルは削除されることがあります。
+※公式のSyncと同期することはできません。
 
 
-# 補足
+## 機能
+- 高効率・低トラフィックでVault同士を同期
+- 競合解決がいい感じ
+  - 単純な競合なら自動マージします
+- OSSソリューションを同期サーバに使用
+  - 互換ソリューションも使用可能です
+- End-to-End暗号化実装済み
+- 設定・スニペット・テーマ、プラグインの同期が可能
+-  [Webクリッパー](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf) もあります
 
-- レプリケーションなどでファイルがリモートデバイスから削除された場合、受信したデバイスでも、ファイルの削除が反映されます。
-- その際、Self-hosted LiveSyncは、フォルダが空になった際に、フォルダをデフォルトでは残しません。残す場合はオプションから設定してください。
--  LiveSyncはモバイルではバッテリーをかなり消費します。
-- モバイル端末からは、非httpsのエンドポイント、または独自CAが発行した証明書でホストされているhttpsのサーバーには接続できません。
-- 除外フォルダのような設定はありません。
+NDAや類似の契約や義務、倫理を守る必要のある、研究者、設計者、開発者のような方に特にオススメです。
 
 
-# このプラグインの使い方
-
-1. Community Pluginsから、Self-holsted LiveSyncと検索しインストールするか、このリポジトリのReleasesから`main.js`, `manifest.json`, `style.css` をダウンロードしvaultの中の`.obsidian/plugins/obsidian-livesync`に入れて、Obsidianを再起動してください。
-2. サーバーを確保します。IBM Cloudantがお手軽かつ堅牢で便利です。完全にセルフホストする際にはお持ちのサーバーにCouchDBをインストールする必要があります。詳しくは下記を参照してください
-  1. [IBM Cloudantのセットアップ](docs/setup_cloudant_ja.md)
-  2. [独自のCouchDBのセットアップ](docs/setup_own_server_ja.md)
-3. サーバー情報を入力します。初回のみ、Obsidianを再起動することをオススメします。  
-設定内容の詳細は[このプラグインの設定](docs/settings_ja.md)を参照してください。
-
-4. お好きな同期方法を選んで、利用を開始してください。
-
-# テストサーバー
-
-もし、CouchDBをインストールしたり、Cloudantのインスタンスをセットアップしたりするのに気が引ける場合、[Self-hosted LiveSyncのテストサーバー](https://olstaste.vrtmrz.net/)を作りましたので、使ってみてください。
-
-備考: 制限事項をよく確認して使用してください。くれぐれも、本当に使用している自分のVaultを同期しないようにしてください。
-
-# WebClipperあります
-Self-hosted LiveSync用にWebClipperも作りました。Chrome Web Storeからダウンロードできます。
-
-[obsidian-livesync-webclip](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf)
-
-リポジトリはこちらです: [obsidian-livesync-webclip](https://github.com/vrtmrz/obsidian-livesync-webclip)。
-
-相変わらずドキュメントは間に合っていません。
-
-# ステータスバーの情報
-右下のステータスバーに、同期の状態が表示されます
-
-- 同期状態
-  - ⏹️ 同期は停止しています
-  - 💤 同期はLiveSync中で、なにか起こるのを待っています
-  - ⚡️ 同期中です
-  - ⚠ エラーが発生しています
-- ↑ 送信したデータ数
-- ↓ 受信したデータ数
--   ⏳ 保留している処理の数です  
-ファイルを削除したりリネームした場合、この表示が消えるまでお待ちください。
-
-# さらなる補足
-- ファイルは同期された後、タイムスタンプを比較して新しければいったん新しい方で上書きされます。その後、衝突が発生したかによって、マージが行われます。
-- まれにファイルが破損することがあります。破損したファイルに関してはディスクへの反映を試みないため、実際には使用しているデバイスには少し古いファイルが残っていることが多いです。そのファイルを再度更新してもらうと、データベースが更新されて問題なくなるケースがあります。ファイルがどの端末にも存在しない場合は、設定画面から、削除できます。
-- データベースが変。そういうときは、いったんデータベースをDrop Historyのapply and sendで再初期化してみてください。だいたい直ります。
-- データベースの復旧中に再起動した場合など、うまくローカルデータベースを修正できない際には、Vaultのトップに`redflag.md`というファイルを置いてください。起動時のシーケンスがスキップされます。
-- データベースが大きくなってきてるんだけど、小さくできる？→各ノートは、それぞれの古い100リビジョンとともに保存されています。例えば、しばらくオフラインだったあるデバイスが、久しぶりに同期したと想定してみてください。そのとき、そのデバイスは最新とは少し異なるリビジョンを持ってるはずです。その場合でも、リモートのリビジョン履歴にリモートのものが存在した場合、安全にマージできます。もしリビジョン履歴に存在しなかった場合、確認しなければいけない差分も、対象を存在して持っている共通のリビジョン以降のみに絞れます。ちょうどGitのような方法で、衝突を解決している形になるのです。そのため、肥大化したリポジトリの解消と同様に、本質的にデータベースを小さくしたい場合は、データベースの作り直しが必要です。
-- その他の技術的なお話は、[技術的な内容](docs/tech_info_ja.md)に書いてあります。
+>[!IMPORTANT]
+> - インストール・アップデート前には必ずVaultをバックアップしてください
+> - 複数の同期ソリューションを同時に有効にしないでください（これはiCloudや公式のSyncも含みます）
+> - このプラグインは同期プラグインです。バックアップとして使用しないでください
 
 
-# ライセンス
+## このプラグインの使い方
 
-The source code is licensed MIT.
- 
+### 3分セットアップ - CouchDB on fly.io
+
+**はじめての方におすすめ**
+
+[![LiveSync Setup onto Fly.io SpeedRun 2024 using Google Colab](https://img.youtube.com/vi/7sa_I1832Xc/0.jpg)](https://www.youtube.com/watch?v=7sa_I1832Xc)
+
+1. [Fly.ioにCouchDBをセットアップする](docs/setup_flyio.md)
+2. [Quick Setup](docs/quick_setup_ja.md)でプラグインを設定する
+
+
+### Manually Setup
+
+1. サーバのセットアップ
+   1. [Fly.ioにCouchDBをセットアップする](docs/setup_flyio.md)
+   2. [CouchDBをセットアップする](docs/setup_own_server_ja.md)
+2. [Quick Setup](docs/quick_setup_ja.md)でプラグインを設定する
+
+> [!TIP]
+> IBM Cloudantもまだ使用できますが、いくつかの理由で現在はおすすめしていません。[IBM Cloudantのセットアップ](docs/setup_cloudant_ja.md)はまだあります。
+
+## ステータスバーの説明
+
+同期ステータスはステータスバーに、下記のアイコンとともに表示されます
+
+-   アクティビティー
+    -   📲 ネットワーク接続中
+-   同期ステータス
+    -   ⏹️ 停止中
+    -   💤 変更待ち（LiveSync中）
+    -   ⚡️ 同期の進行中
+    -   ⚠ エラー
+-   統計情報
+     -   ↑ アップロードしたチャンクとメタデータ数
+     -   ↓ ダウンロードしたチャンクとメタデータ数
+-   進捗情報
+     -   📥 転送後、未処理の項目数
+     -   📄 稼働中データベース操作数
+     -   💾 稼働中のストレージ書き込み数操作数
+     -   ⏳ 稼働中のストレージ読み込み数操作数
+     -   🛫 待機中のストレージ読み込み数操作数
+     -   ⚙️ 隠しファイルの操作数（待機・稼働中合計）
+     -   🧩 取得待ちを行っているチャンク数
+     -   🔌 設定同期関連の操作数
+
+データベースやファイルの破損を避けるため、Obsidianの終了は進捗情報が表示されなくなるまで待ってください（プラグインも復帰を試みますが）。特にファイルを削除やリネームした場合は気をつけてください。
+
+
+## Tips and Troubleshooting
+- 2台目以降のセットアップ時に、初期同期をより迅速かつ簡単に行うには、[ファストセットアップガイド](docs/tips/fast-setup_ja.md)をご参照ください。
+- 何かこまったら、[Tips and Troubleshooting](docs/troubleshooting.md)をご参照ください。
+
+## License
+
+Licensed under the MIT License.

_tools/bakei18n.ts

@@ -0,0 +1,12 @@
+import { writeFileSync } from "fs";
+import { allMessages } from "../src/common/messages/combinedMessages.dev.ts";
+import path from "path";
+const __dirname = import.meta.dirname;
+const currentPath = __dirname;
+const outDir = path.resolve(currentPath, "../src/common/messages/combinedMessages.prod.ts");
+
+console.log(`Writing to ${outDir}`);
+writeFileSync(
+    outDir,
+    `export const allMessages: Readonly<Record<string, Readonly<Record<string, string>>>> = ${JSON.stringify(allMessages, null, 4)};`
+);

_tools/checkI18nCoverage.ts

@@ -0,0 +1,58 @@
+import { readFile } from "fs/promises";
+import { join, resolve } from "path";
+import { glob } from "tinyglobby";
+import { parse } from "yaml";
+import { objectToDotted } from "./messagelib.ts";
+
+const __dirname = import.meta.dirname;
+const targetDir = resolve(join(__dirname, "../src/common/messagesYAML/"));
+const files = (await glob(`*.yaml`, { expandDirectories: false, absolute: true, cwd: targetDir })).sort();
+
+function flattenMessages(src: Record<string, unknown>) {
+    return Object.fromEntries(
+        Object.entries(objectToDotted(src))
+            .map(([key, value]) => [key.endsWith("._value") ? key.slice(0, -7) : key, value] as const)
+            .filter(([, value]) => typeof value === "string")
+            .sort(([a], [b]) => a.localeCompare(b))
+    ) as Record<string, string>;
+}
+
+const localeData = new Map<string, Record<string, string>>();
+for (const file of files) {
+    const segments = file.split(/[/\\]/);
+    const locale = segments[segments.length - 1]!.replace(/\.yaml$/, "");
+    const content = await readFile(file, "utf-8");
+    localeData.set(locale, flattenMessages(parse(content) ?? {}));
+}
+
+const baseLocale = "en";
+const base = localeData.get(baseLocale);
+if (!base) {
+    throw new Error("en.yaml not found");
+}
+
+const baseKeys = Object.keys(base);
+const report = Object.fromEntries(
+    [...localeData.entries()].map(([locale, data]) => {
+        const keys = new Set(Object.keys(data));
+        const missing = baseKeys.filter((key) => !keys.has(key));
+        const identicalToEnglish = baseKeys.filter(
+            (key) => keys.has(key) && locale !== baseLocale && data[key] === base[key]
+        );
+        const translated = baseKeys.length - missing.length;
+        return [
+            locale,
+            {
+                totalBaseKeys: baseKeys.length,
+                translatedKeys: translated,
+                missingKeys: missing.length,
+                identicalToEnglishCount: identicalToEnglish.length,
+                coverage: `${translated}/${baseKeys.length}`,
+                missing,
+                identicalToEnglish,
+            },
+        ];
+    })
+);
+
+console.log(JSON.stringify(report, null, 2));

_tools/decompileRosetta.ts

@@ -0,0 +1,55 @@
+import { writeFileSync } from "fs";
+
+import { SUPPORTED_I18N_LANGS, type I18N_LANGS } from "../src/common/rosetta";
+import { allMessages } from "../src/common/messages/combinedMessages.dev.ts";
+
+import path from "path";
+const thisFileDir = __dirname;
+const outDir = path.join(thisFileDir, "i18n");
+
+const out = {} as Record<string, { [key: string]: string | undefined }>;
+
+for (const [key, value] of Object.entries(allMessages)) {
+    for (const lang of [...SUPPORTED_I18N_LANGS, "def"]) {
+        if (!out[lang]) out[lang] = {};
+        if (lang in value) {
+            out[lang][key] = value[lang as I18N_LANGS];
+        } else {
+            if (lang === "def") {
+                out[lang][key] = key;
+            } else {
+                out[lang][key] = undefined;
+            }
+        }
+    }
+}
+
+for (const [lang, value] of Object.entries(out)) {
+    const filename = `${lang}.ts`;
+    const escapeString = (prefix: string, key: string, str: string) => {
+        if (str.indexOf("\n") !== -1) {
+            const encoded = JSON.stringify(str);
+            const lineWrapped = encoded.split("\\n").join("\\\n" + prefix);
+
+            return `${prefix}${JSON.stringify(key)}: ${lineWrapped},`;
+        }
+        return `${prefix}${JSON.stringify(key)}: ${JSON.stringify(str)},`;
+    };
+    // const z ="a"  "b" "c";
+    const _stringify = (value: Record<string, string | undefined>) => {
+        let res = "{\n";
+        for (const key of Object.keys(value)) {
+            const v = value[key];
+            if (v) {
+                res += escapeString("", key, v) + "\n";
+            } else {
+                res += escapeString("// ", key, out["def"]?.[key] ?? "") + "\n";
+            }
+        }
+        return res + "\n}";
+    };
+    void writeFileSync(
+        path.join(outDir, filename),
+        `export const PartialMessages ={\n    "${lang}":${_stringify(value)}\n} as const;`
+    );
+}

_tools/decompileRosettaToJson.ts

@@ -0,0 +1,30 @@
+import { writeFileSync } from "fs";
+
+import { allMessages } from "../src/common/messages/combinedMessages.prod.ts";
+const __dirname = import.meta.dirname;
+import path from "path";
+const thisFileDir = __dirname;
+const outDir = path.resolve(thisFileDir, "../src/common/messagesJson");
+
+const out = {} as Record<string, { [key: string]: string | undefined }>;
+
+for (const [key, value] of Object.entries(allMessages)) {
+    //@ts-ignore
+    for (const [lang, langValue] of Object.entries(allMessages[key])) {
+        if (!out[lang]) out[lang] = {};
+        if (lang in value) {
+            out[lang][key] = langValue as string;
+        } else {
+            if (lang === "def") {
+                out[lang][key] = key;
+            } else {
+                out[lang][key] = undefined;
+            }
+        }
+    }
+}
+
+for (const [lang, value] of Object.entries(out)) {
+    const filename = `${lang}.json`;
+    void writeFileSync(path.join(outDir, filename), JSON.stringify(value, null, 4));
+}

_tools/json2yaml.ts

@@ -0,0 +1,27 @@
+// Convert Application convenient Message Resources (JSON) to Human-Editable format (YAML)
+import { readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { stringify } from "yaml";
+import { glob } from "tinyglobby";
+import { dottedToObject } from "./messagelib";
+const __dirname = import.meta.dirname;
+
+const targetDir = resolve(join(__dirname, "../src/common/messagesJson/"));
+console.log(`Target directory: ${targetDir}`);
+const files = await glob(`*.json`, { expandDirectories: false, absolute: true, cwd: targetDir });
+for (const file of files) {
+    const filePath = resolve(file);
+    console.log(`Processing file: ${filePath}`);
+    const content = await readFile(filePath, "utf-8");
+    const jsonDataSrc = JSON.parse(content);
+    const jsonDataD2 = Object.fromEntries(
+        Object.entries(jsonDataSrc).sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
+    );
+    const jsonData = dottedToObject(jsonDataD2);
+    const yamlData = stringify(jsonData, { indent: 2 });
+    const yamlFilePath = filePath.replace(/\.json$/, ".yaml").replace("Json", "YAML");
+    await writeFile(yamlFilePath, yamlData, "utf-8");
+    console.log(`Converted ${filePath} to ${yamlFilePath}`);
+}
+
+// console.dir(files, { depth: 0 });

_tools/messagelib.ts

@@ -0,0 +1,38 @@
+export function objectToDotted(obj: any, prefix = ""): Record<string, any> {
+    return Object.entries(obj).reduce(
+        (acc, [key, value]) => {
+            const newKey = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+                Object.assign(acc, objectToDotted(value, newKey));
+            } else {
+                acc[newKey] = value;
+            }
+            return acc;
+        },
+        {} as Record<string, any>
+    );
+}
+export function dottedToObject(obj: Record<string, any>): Record<string, any> {
+    return Object.entries(obj).reduce(
+        (acc, [key, value]) => {
+            if (key.includes(" ")) {
+                // Return as is.
+                return { ...acc, [key]: value }; // Skip keys with spaces
+            }
+            const keys = key.split(".");
+            keys.reduce((nestedAcc, currKey, index) => {
+                if (currKey in nestedAcc && typeof nestedAcc[currKey] !== "object") {
+                    nestedAcc[currKey] = { _value: nestedAcc[currKey] }; // Convert to object if not already
+                }
+                if (index === keys.length - 1) {
+                    nestedAcc[currKey] = value;
+                } else {
+                    nestedAcc[currKey] = nestedAcc[currKey] || {};
+                }
+                return nestedAcc[currKey];
+            }, acc);
+            return acc;
+        },
+        {} as Record<string, any>
+    );
+}

_tools/yaml2json.ts

@@ -0,0 +1,29 @@
+// Convert Human-Editable format (YAML) to Application convenient Message Resources (JSON)
+
+import { readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { parse } from "yaml";
+import { glob } from "tinyglobby";
+import { objectToDotted } from "./messagelib";
+const __dirname = import.meta.dirname;
+
+const targetDir = resolve(join(__dirname, "../src/common/messagesYAML/"));
+console.log(`Target directory: ${targetDir}`);
+const files = await glob(`*.yaml`, { expandDirectories: false, absolute: true, cwd: targetDir });
+for (const file of files) {
+    const filePath = resolve(file);
+    const content = await readFile(filePath, "utf-8");
+    const jsonDataSrc = parse(content);
+    const jsonDataD2 = objectToDotted(jsonDataSrc);
+    const jsonData = Object.fromEntries(
+        Object.entries(jsonDataD2)
+            .map(([key, value]) => [key.endsWith("._value") ? key.slice(0, -7) : key, value])
+            .sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
+    );
+    const yamlData = JSON.stringify(jsonData, null, 4) + "\n";
+    const yamlFilePath = filePath.replace(/\.yaml$/, ".json").replace("YAML", "Json");
+    await writeFile(yamlFilePath, yamlData, "utf-8");
+    console.log(`Converted ${filePath} to ${yamlFilePath}`);
+}
+
+// console.dir(files, { depth: 0 });

aggregator.html

@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Self-hosted LiveSync Setup QR Aggregator</title>
+    <style>
+        body { font-family: sans-serif; display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100vh; margin: 0; background-color: #f4f4f9; color: #333; }
+        .container { background: white; padding: 2rem; border-radius: 8px; box-shadow: 0 4px 6px rgba(0,0,0,0.1); text-align: center; max-width: 90%; }
+        .progress { margin: 20px 0; font-size: 1.2rem; font-weight: bold; }
+        .status { margin-bottom: 20px; color: #666; }
+        .btn { display: inline-block; padding: 12px 24px; background-color: #7c4dff; color: white; text-decoration: none; border-radius: 4px; font-weight: bold; transition: background-color 0.2s; border: none; cursor: pointer; }
+        .btn:hover { background-color: #651fff; }
+        .btn:disabled { background-color: #ccc; cursor: not-allowed; }
+        .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(40px, 1fr)); gap: 8px; margin: 20px 0; }
+        .tile { width: 40px; height: 40px; border: 2px solid #ddd; border-radius: 4px; display: flex; align-items: center; justify-content: center; font-size: 0.8rem; }
+        .tile.filled { background-color: #7c4dff; color: white; border-color: #7c4dff; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>LiveSync Setup</h1>
+        <div id="app">
+            <p>Checking hash data...</p>
+        </div>
+    </div>
+
+    <script>
+        function updateUI() {
+            const hash = window.location.hash.substring(1);
+            const params = new URLSearchParams(hash);
+            
+            const id = params.get('id');
+            const total = parseInt(params.get('n') || '0');
+            const index = parseInt(params.get('i') || '-1');
+            const data = params.get('d');
+
+            const app = document.getElementById('app');
+
+            if (!id || total <= 0 || index === -1 || !data) {
+                app.innerHTML = '<p class="status">Invalid setup URL. Please scan the QR code correctly.</p>';
+                return;
+            }
+
+            // Get session data
+            const storageKey = 'ls_agg_' + id;
+            let session = JSON.parse(localStorage.getItem(storageKey) || '{}');
+            
+            // Save current data
+            session[index] = data;
+            localStorage.setItem(storageKey, JSON.stringify(session));
+
+            const receivedIndexes = Object.keys(session).map(Number);
+            const count = receivedIndexes.length;
+
+            let html = `
+                <div class="status">Session ID: ${id}</div>
+                <div class="progress">${count} / ${total} Loaded</div>
+                <div class="grid">
+            `;
+
+            for (let i = 0; i < total; i++) {
+                const isFilled = session[i] !== undefined;
+                html += `<div class="tile ${isFilled ? 'filled' : ''}">${i + 1}</div>`;
+            }
+            html += `</div>`;
+
+            if (count === total) {
+                const sortedData = Array.from({length: total}, (_, i) => session[i]).join('');
+                // Use the correct protocol for settings
+                const obsidianUri = `obsidian://setuplivesync?settingsQR=${sortedData}`;
+                
+                html += `
+                    <p>All parts have been collected!</p>
+                    <a href="${obsidianUri}" class="btn">Open Obsidian to complete setup</a>
+                    <p style="margin-top:20px; font-size:0.8rem; color: #999;">Note: If the button does not respond, please ensure you are opening this in a browser that can trigger Obsidian.</p>
+                `;
+            } else {
+                html += `
+                    <p class="status">Please scan the next QR code.</p>
+                    <button class="btn" disabled>Waiting...</button>
+                `;
+            }
+
+            app.innerHTML = html;
+        }
+
+        window.addEventListener('hashchange', updateUI);
+        updateUI();
+    </script>
+</body>
+</html>

devs.md

@@ -0,0 +1,303 @@
+# Self-hosted LiveSync Development Guide
+
+## Project Overview
+
+Self-hosted LiveSync is an Obsidian plugin for synchronising vaults across devices using CouchDB, MinIO/S3, or peer-to-peer WebRTC. The codebase uses a modular architecture with TypeScript, Svelte, and PouchDB.
+
+## Build & Development Workflow
+
+### Environment Setup
+
+#### First-time Setup
+
+```bash
+git clone https://github.com/vrtmrz/obsidian-livesync
+cd obsidian-livesync
+npm ci
+npm run build
+```
+
+#### Branch switching
+
+When switching branches, reinstall dependencies when the lockfile changes.
+
+```bash
+git checkout 0.25.70-patch1 # tag or branch name
+npm ci
+npm run build
+```
+
+### Commands
+
+```bash
+npm run test:unit    # Run unit tests with vitest (or `npm run test:unit:coverage` for coverage)
+npm run check        # TypeScript and svelte type checking
+npm run dev          # Development build with auto-rebuild (uses .env for test vault paths)
+npm run build        # Production build
+npm run buildDev     # Development build (one-time)
+npm run test:integration                 # Run CouchDB-backed integration tests
+npm run test:setup-tools                 # Check provisioning and Setup URI package contracts
+npm run test:e2e:cli:p2p                 # Run canonical P2P validation in Compose
+npm run test:e2e:obsidian:local-suite    # Run the real Obsidian local suite
+```
+
+### Tips
+
+Select the narrowest unit, integration, CLI E2E, or real Obsidian E2E command that owns the behaviour being changed. The obsolete mocked browser Harness has been retired.
+
+### Unreleased change notes
+
+Keep changes that may belong in a future release under `## Unreleased` at the top of `updates.md` when they do not justify an immediate release. Do not add a date to this virtual version. Move relevant entries under the real version and ordinal release date when preparing that release, then leave an empty `## Unreleased` section for subsequent work.
+
+Use this section for durable release-note candidates, including compatibility-relevant internal maintenance, rather than tasks, local diagnostics, or implementation journals. Categorise user-visible behaviour separately from internal changes and testing.
+
+### Auto-copy to test vaults
+
+To facilitate development and testing, the build process can automatically copy the built plugin to specified test vault
+
+- Create `.env` file with `PATHS_TEST_INSTALL` pointing to test vault plug-in directories (`:` separated on Unix, `;` on Windows)
+- Development builds auto-copy to these paths on build whilst `npm run dev` is running (watch mode)
+
+### Testing Infrastructure
+
+- ~~**Deno Tests**: Unit tests for platform-independent code (e.g., `HashManager.test.ts`)~~
+    - This is now obsolete, migrated to vitest.
+- **Vitest**:
+    - **Unit Tests** (`vitest.config.unit.ts`): Unit tests run in Node.js (excluding harnesses and integration tests). Unit tests should be `*.unit.spec.ts` and placed alongside the implementation file (e.g., `ChunkFetcher.unit.spec.ts`). Executed via `npm run test:unit`.
+    - **Integration Tests** (`vitest.config.integration.ts`): Tests run in Node.js against a real CouchDB instance. Integration tests should be `*.integration.spec.ts` or `*.integration.test.ts` and placed alongside the implementation file (e.g., `StreamingFetch.integration.spec.ts`). Executed via `npm run test:integration`.
+        - If you add a feature that interacts with the remote database (e.g., replication changes, custom changes feed parameters, or custom HTTP queries), you strongly expected to write an integration test to verify the behaviour against a real CouchDB server.
+    - **Commonlib Tests**: Commonlib owns unit and package tests for shared RPC, storage, replication, and platform contracts. LiveSync CI verifies the exact packed dependency as a downstream consumer.
+- **CLI E2E** (`src/apps/cli/testdeno/`): Host-independent consumer workflows. The canonical Compose P2P suite covers ordinary two-peer synchronisation, replacement of the current replicator followed by transfer with the same peer, and explicit relay disconnection followed by paused and resumed reconnection. Its lifecycle entry point is included only in the Docker test build and does not add a public CLI command. Run `npm run test:e2e:cli` for the ordinary suite or `npm run test:e2e:cli:p2p` for P2P validation.
+- **Self-hosted setup tools** (`utils/couchdb/`, `utils/setup/`, and `utils/flyio/`): Deno contract tests consume the exact locked Commonlib registry package, verify current CouchDB, Object Storage, and random-room P2P Setup URI defaults and remote profiles, and keep CouchDB administration separate from package-owned LiveSync database-version negotiation. `unit-ci` also provisions a real temporary CouchDB database and verifies its version document against the installed Commonlib package. Run `npm run test:setup-tools` for the local contract gate.
+- **Real Obsidian E2E** (`test/e2e-obsidian/`): Local-first scripts that launch real Obsidian with temporary vaults and the built Self-hosted LiveSync plug-in. Use these for boot-up sequence, vault reflection, RedFlag flows, Fast Setup (Simple Fetch), settings dialogues, restart-sensitive workflows, Object Storage regressions, and other behaviour that depends on Obsidian itself. Run focused scripts such as `npm run test:e2e:obsidian:two-vault-sync`, or use `npm run test:e2e:obsidian:local-suite:services` to run the broader local suite with CouchDB and MinIO fixtures managed by the wrapper.
+
+- **Docker Services**: Service-backed tests use CouchDB and MinIO (S3). Canonical P2P validation owns its relay through the CLI Compose runner:
+
+    ```bash
+    npm run test:docker-all:start  # Start all test services
+    npm run test:integration       # Run the relevant service-backed suite
+    npm run test:docker-all:stop   # Stop services
+    ```
+
+    If some services are not needed, start only required ones (e.g., `test:docker-couchdb:start`).
+    Note that if services are already running, starting script will fail. Please stop them first.
+
+- **Test Structure**:
+    - `test/e2e-obsidian/` - Real Obsidian E2E scripts for local verification
+    - co-located `*.unit.spec.ts` files - Node-based unit tests
+    - co-located `*.integration.spec.ts` files - service-backed integration tests
+    - `src/apps/webapp/obsidianMock.ts` - Webapp-only Obsidian compatibility adapter; it is not an E2E Harness
+
+### Import Path Normalisation
+
+The codebase uses the `@/` alias for source owned by this repository. Commonlib imports use explicit `@vrtmrz/livesync-commonlib` package subpaths. To normalise LiveSync-owned imports and exports, use the following utility script:
+
+```bash
+npm run pretty:importpath
+```
+
+Under the hood, this runs Deno with the script [utilsdeno/normalise-imports.ts](utilsdeno/normalise-imports.ts). You can pass additional flags to this script if required (by running it via Deno directly from the `utilsdeno` directory):
+
+- `--run`: Applies the changes (the script runs in dry-run mode by default).
+- `--all-alias`: Normalises sibling/child relative imports starting with `./` to use aliases.
+
+### Commonlib dependency
+
+Shared synchronisation code is compiled and typed by the `@vrtmrz/livesync-commonlib` package. `npm ci` installs the exact artefact recorded by the lockfile; this repository does not compile Commonlib source or commit fallback declarations.
+
+Changes spanning both repositories must first produce a packed Commonlib artefact which passes its standalone package checks. Install that exact artefact in LiveSync, then run the LiveSync type checks, unit tests, application builds, CLI E2E, and any focused real-Obsidian E2E required by the changed boundary. Replace the temporary artefact reference with the reviewed immutable package version before release.
+
+## Architecture
+
+### Module System
+
+The plugin uses a dynamic module system to reduce coupling and improve maintainability:
+
+- **Service Hub**: Central registry for services using dependency injection
+    - Services are registered, and accessed via `this.services` (in most modules)
+- **Module Loading**: All modules extend `AbstractModule` or `AbstractObsidianModule` (which extends `AbstractModule`). These modules are loaded in main.ts and some modules.
+- **Module Categories** (by directory):
+    - `core/` - Platform-independent core functionality
+    - `coreObsidian/` - Obsidian-specific core (e.g., `ModuleFileAccessObsidian`)
+    - `essential/` - Required modules (e.g., `ModuleMigration`, `ModuleKeyValueDB`)
+    - `features/` - Optional features (e.g., `ModuleLog`, `ModuleObsidianSettings`)
+    - `extras/` - Development/testing tools (e.g., `ModuleDev`, ~~`ModuleIntegratedTest`~~)
+- **Services**: Core services (e.g., `database`, `replicator`, `storageAccess`) are registered in `ServiceHub` and accessed by modules. They provide an extension point for add new behaviour without modifying existing code.
+    - For example, checks before the replication can be added to the `replication.onBeforeReplicate` handler, and the handlers can be return `false` to prevent replication-starting. `vault.isTargetFile` also can be used to prevent processing specific files.
+- **ServiceModule**: A new type of module that directly depends on services.
+
+#### Note on Module vs Service
+
+After v0.25.44 refactoring, the Service will henceforth, as a rule, cease to use setHandler, that is to say, simple lazy binding. - They will be implemented directly in the service. - However, not everything will be middlewarised. Modules that maintain state or make decisions based on the results of multiple handlers are permitted.
+
+Hence, the new feature should be implemented as follows:
+
+- If it is a simple extension point (e.g., adding a check before replication), it should be implemented as a handler in the service (e.g., `replication.onBeforeReplicate`).
+- If it requires maintaining state or making decisions based on multiple handlers, it should be implemented as a serviceModule dependent on the relevant services explicitly.
+- If you have to implement a new feature without much modification, you can extent existing modules, but it is recommended to implement a new module or serviceModule for better maintainability.
+- Refactoring existing modules to services is also always welcome!
+- Please write tests for new features, you will notice that the simple handler approach is quite testable.
+
+### Key Architectural Components
+
+- **LiveSyncLocalDB** (`@vrtmrz/livesync-commonlib/compat/pouchdb/LiveSyncLocalDB`): Local PouchDB database wrapper
+- **Replicators** (`@vrtmrz/livesync-commonlib/compat/replication/*`): CouchDB, Journal, and P2P synchronisation engines
+- **Service Hub** (`src/modules/services/`): Central service registry using dependency injection
+- **Common Library** (`@vrtmrz/livesync-commonlib`): Platform-independent synchronisation logic, shared with the CLI, Webapp, WebPeer, and external tools
+
+Commonlib owns the P2P replicator and Trystero transport lifecycle. Host commands, event handlers, and views must retain the Commonlib service-feature result and resolve its current `replicator` at the point of use. They must not snapshot an instance which can be replaced when settings or the local database change, close Trystero-owned raw peers, or install another Trystero transport generation at the application root.
+
+### Conflict Merge Policy
+
+Markdown conflict auto-merge should behave like a conservative three-way merge. The guiding rule is to merge changes when they touch non-overlapping regions, and to keep a manual conflict when the edits overlap semantically.
+
+When in doubt, prefer the safer outcome: preserve data, keep the conflict visible, and ask the user rather than silently discarding content or choosing one side.
+
+- If one side deletes a line and the other side leaves that same line unchanged, treat it as a safe deletion. The deleted line must not be reintroduced into the merged result.
+- If one side inserts new content in a different region while the other side deletes an unchanged old region, preserve the insertion and the deletion.
+- If one side deletes a line and the other side modifies that same line, keep the conflict for user resolution.
+- If both sides insert different content at the same position, keep both insertions in a deterministic order unless the surrounding deletion context indicates that they are competing replacements.
+- Avoid resolving conflicts by simply choosing the newest revision unless the user has explicitly selected that behaviour.
+
+This policy is intentionally aligned with the conflict checkboxes and compatibility settings: automatic merge should remove avoidable prompts, but it must not silently choose between overlapping user intentions.
+
+### File Structure Conventions
+
+- **Platform-specific code**: Use `.platform.ts` suffix (replaced with `.obsidian.ts` in production builds via esbuild)
+- **Development code**: Use `.dev.ts` suffix (replaced with `.prod.ts` in production)
+- **Path aliases**: `@/*` maps to `src/*`; Commonlib uses package exports rather than a source alias
+
+## Code Conventions
+
+### Internationalisation (i18n)
+
+- **Translation Workflow**:
+    1. Edit the human-readable YAML files in this repository under `src/common/messagesYAML/`
+    2. Run `npm run i18n:bake` to compile YAML → JSON → TypeScript constants
+    3. Use `$t()`, `$msg()` functions for translations
+       You can also use `$f` for formatted messages with Tagged Template Literals.
+- **Usage**:
+    ```typescript
+    $msg("dialog.someKey"); // Typed key with autocomplete
+    $t("Some message"); // Direct translation
+    $f`Hello, ${userName}`; // Formatted message
+    ```
+- **Supported languages**: `def` (English), `de`, `es`, `fr`, `he`, `ja`, `ko`, `ru`, `zh`, `zh-tw`
+
+Commonlib owns the typed English fallback for messages requested by its services. LiveSync owns the multilingual application catalogue and injects its translator into the Obsidian, CLI, and browser service compositions. Adding a Commonlib message therefore requires its canonical English definition in Commonlib; LiveSync may provide translations here, while an untranslated key falls back to Commonlib English. Importing a Commonlib language catalogue is not part of the boundary.
+
+### File Path Handling
+
+- Use tagged types from `types.ts`: `FilePath`, `FilePathWithPrefix`, `DocumentID`
+- Prefix constants: `CHeader` (chunks), `ICHeader`/`ICHeaderEnd` (internal data)
+- Path utilities are supplied by the focused Commonlib compatibility path `@vrtmrz/livesync-commonlib/compat/string_and_binary/path`
+
+### Logging & Debugging
+
+- Use `this._log(msg, LOG_LEVEL_INFO)` in modules (automatically prefixes with module name)
+- Log levels: `LOG_LEVEL_DEBUG`, `LOG_LEVEL_VERBOSE`, `LOG_LEVEL_INFO`, `LOG_LEVEL_NOTICE`, `LOG_LEVEL_URGENT`
+    - LOG_LEVEL_NOTICE and above are reported to the user via Obsidian notices
+    - LOG_LEVEL_DEBUG is for debug only and not shown in default builds
+- Dev mode creates `ls-debug/` folder in `.obsidian/` for debug outputs (e.g., missing translations)
+    - This causes pretty significant performance overhead.
+
+## Common Patterns
+
+### Module Implementation (Now not recommended for new features, use services instead)
+
+```typescript
+export class ModuleExample extends AbstractObsidianModule {
+    async _everyOnloadStart(): Promise<boolean> {
+        /* ... */
+    }
+
+    onBindFunction(core: LiveSyncCore, services: typeof core.services): void {
+        services.appLifecycle.handleOnInitialise(this._everyOnloadStart.bind(this));
+    }
+}
+```
+
+### Settings Management
+
+- Settings are defined by Commonlib (`ObsidianLiveSyncSettings`)
+- Configuration metadata is supplied by the Commonlib settings exports
+- Use `this.services.setting.saveSettingData()` instead of using plugin methods directly
+
+### Database Operations
+
+- Local database operations through `LiveSyncLocalDB` (wraps PouchDB)
+- Document types: `EntryDoc` (files), `EntryLeaf` (chunks), `PluginDataEntry` (plugin sync)
+
+## Important Files
+
+- [main.ts](src/main.ts) - Plugin entry point, module registration
+- [esbuild.config.mjs](esbuild.config.mjs) - Build configuration with platform/dev file replacement
+- [package.json](package.json) - Scripts reference and dependencies
+
+## Pre-release Policy
+
+- Use SemVer beta identifiers such as `1.0.0-beta.0` for immutable integration previews. Increment the beta number when a published preview needs a correction. Reserve `1.0.0-rc.0` for the first feature- and contract-frozen release candidate. Historical `-patchedN` releases remain unchanged in the release history.
+- Publish a pre-release from an immutable reviewed tag, mark its GitHub Release as a pre-release, and do not replace the latest stable release.
+- A plug-in review release may omit the CLI image when the CLI artefact is not part of the required validation. When a pre-release CLI image is published, it receives immutable version and SHA-qualified tags only; it must not advance `latest` or a stable major-minor tag.
+- Keep the release pull request in draft until the exact published plug-in has passed BRAT validation. If validation fails, prepare the next pre-release version rather than moving the existing tag.
+
+## Release Notes
+
+- Keep the top section of `updates.md` as `## Unreleased` during normal development.
+- When opening a feature or fix PR, update `## Unreleased` in the same PR if the change is user-facing.
+- Add only user-facing changes that help users understand what they gain, what has changed, or what they may need to do after updating.
+- Avoid listing purely internal refactors, maintenance chores, generated-file changes, and dependency updates unless they affect users; group and label them when they are included.
+- When preparing a release, replace `## Unreleased` with the target version heading (for example, `## 0.25.81`) and add a fresh empty `## Unreleased` section above it for the next cycle.
+- Review and polish the released section in the release PR before tagging, because the content is embedded into the plug-in and may be reused as the GitHub Release notes.
+
+## Release Workflow
+
+This workflow is for maintainers. Contributors should update `## Unreleased` for user-facing feature or fix PRs, but do not need to run the release workflows.
+The `Finalise Release Tags` and `Release Obsidian Plugin` workflows use the `release` GitHub Environment. Configure Environment protection in the repository settings so tag creation and release publication require maintainer approval.
+
+- Run the `Prepare Release PR` workflow with the target version and selected base branch. It creates the release branch, updates versions, confirms that Commonlib is locked to an immutable package version, moves the `## Unreleased` notes to the target version, commits the release preparation, pushes the branch, and opens a draft release PR. The base branch may already select the target development version; the workflow still runs the version lifecycle so that release-only metadata such as `versions.json` is recorded in the release commit.
+- Do not tag the release branch when the PR is first created. Polish the release PR first, especially `updates.md`.
+- Once the release PR head is fixed, run the `Finalise Release Tags` workflow with its full head commit SHA. It validates the release branch, ensures that the plug-in tag points to that commit, optionally creates the corresponding CLI tag, and dispatches the plug-in release workflow. A CLI tag starts its own container workflow. The finalisation workflow can be retried when existing tags already point to the reviewed commit, but stops if a selected tag points elsewhere.
+- The plug-in publishing workflow is intentionally dispatch-only. Pushing a plug-in tag directly does not publish a GitHub Release; use `Finalise Release Tags`, or dispatch `Release Obsidian Plugin` explicitly for recovery or a pre-release. The CLI Docker workflow retains its documented branch, tag, and manual triggers.
+- Approve the `Release Obsidian Plugin` workflow for the `release` environment, then inspect the generated draft GitHub Release. For a selected CLI publication, confirm the image tags appropriate to a stable or pre-release version.
+- Publish a stable draft as the latest release, or publish a pre-release draft without replacing the latest stable release. In either case, keep the release PR in draft and leave its base branch unchanged until BRAT validation succeeds. Record that state in the PR.
+- Validate the published release through BRAT. Confirm start-up, ordinary bidirectional synchronisation, and any regression scenario relevant to the release.
+- After BRAT validation succeeds, mark the release PR ready and merge it into the selected base branch with a merge commit. This keeps the tagged release commit in that branch's history.
+- If BRAT validation fails, keep the release PR in draft. Do not move published tags; prepare and publish a new patch release instead.
+- For a pre-release, set `prerelease=true` in `Finalise Release Tags`. A hyphenated version is rejected unless that input is enabled.
+
+### Release Cheat Sheet
+
+1. Before starting, add user-facing notes under `## Unreleased` in `updates.md`.
+2. Run `Prepare Release PR` from GitHub Actions.
+    - `version`: the target version, for example `0.25.81`.
+    - `base_branch`: normally `main`, or the reviewed integration branch for an integration preview.
+    - `release_branch`: leave blank to use the default branch name, for example `0_25_81`.
+    - `release_date`: use an ordinal date such as `14th July, 2026`, or leave blank to use the current UTC date.
+    - `allow_empty_updates`: leave disabled unless the release intentionally has no user-facing notes.
+3. Review the generated draft PR.
+    - Polish `updates.md`.
+    - Confirm `package.json`, `manifest.json`, `versions.json`, workspace package versions, and the locked Commonlib package version.
+    - Confirm that `manifest.json` has the intended `minAppVersion`.
+    - Wait for the necessary CI checks.
+4. When the PR head is fixed, run `Finalise Release Tags`.
+    - `version`: the same target version.
+    - `release_branch`: leave blank unless the release branch used a custom name.
+    - `expected_head_sha`: the full head commit SHA reviewed in the release PR.
+    - `prerelease`: enable for a version such as `1.0.0-rc.0`.
+    - `publish_cli`: disable when the reviewed release is plug-in-only.
+5. Approve the `Release Obsidian Plugin` workflow for the `release` environment, then check the generated draft GitHub Release.
+6. If CLI publication was selected, confirm that the CLI tag event published the expected image tags.
+7. Publish the draft as a stable release or pre-release as selected, but keep the release PR in draft and leave its base branch unchanged.
+8. Update the PR state message to describe the published release and state that merging remains on hold until BRAT validation is complete.
+9. Validate the published release through BRAT, including start-up, ordinary bidirectional synchronisation, and any release-specific regression scenario.
+10. After BRAT validation succeeds, mark the release PR ready and merge it into the selected base branch with a merge commit.
+11. If validation fails, leave the PR in draft and prepare a new patch release without moving the published tags.
+
+## Contribution Guidelines
+
+- Follow existing code style and conventions
+- Write integration tests (`*.integration.spec.ts` or `*.integration.test.ts`) when adding or modifying features that interact with the remote database, and ensure that they pass in the CI workflow.
+- Please bump dependencies with care, check artifacts after updates, with diff-tools and only expected changes in the build output (to avoid unexpected vulnerabilities).
+- When adding new features, please consider it has an OSS implementation, and avoid using proprietary services or APIs that may limit usage.
+    - For example, any functionality to connect to a new type of server is expected to either have an OSS implementation available for that server, or to be managed under some responsibilities and/or limitations without disrupting existing functionality, and scope for surveillance reduced by some means (e.g., by client-side encryption, auditing the server ourselves).

docker-compose.traefik.yml

@@ -0,0 +1,45 @@
+# For details and other explanations about this file refer to:
+# https://github.com/vrtmrz/obsidian-livesync/blob/main/docs/setup_own_server.md#traefik
+
+services:
+  couchdb:
+    image: couchdb:latest
+    container_name: obsidian-livesync
+    user: 1000:1000
+    environment:
+      - COUCHDB_USER=username
+      - COUCHDB_PASSWORD=password
+    volumes:
+      - ./data:/opt/couchdb/data
+      - ./local.ini:/opt/couchdb/etc/local.ini
+    # Ports not needed when already passed to Traefik
+    #ports:
+    #  - 5984:5984
+    restart: unless-stopped
+    networks:
+      - proxy
+    labels:
+      - "traefik.enable=true"
+      # The Traefik Network
+      - "traefik.docker.network=proxy"
+      # Don't forget to replace 'obsidian-livesync.example.org' with your own domain
+      - "traefik.http.routers.obsidian-livesync.rule=Host(`obsidian-livesync.example.org`)"
+      # The 'websecure' entryPoint is basically your HTTPS entrypoint. Check the next code snippet if you are encountering problems only; you probably have a working traefik configuration if this is not your first container you are reverse proxying.
+      - "traefik.http.routers.obsidian-livesync.entrypoints=websecure"
+      - "traefik.http.routers.obsidian-livesync.service=obsidian-livesync"
+      - "traefik.http.services.obsidian-livesync.loadbalancer.server.port=5984"
+      - "traefik.http.routers.obsidian-livesync.tls=true"
+      # Replace the string 'letsencrypt' with your own certificate resolver
+      - "traefik.http.routers.obsidian-livesync.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.obsidian-livesync.middlewares=obsidiancors"
+      # The part needed for CORS to work on Traefik 2.x starts here
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolallowmethods=GET,PUT,POST,HEAD,DELETE"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolallowheaders=accept,authorization,content-type,origin,referer"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolalloworiginlist=app://obsidian.md,capacitor://localhost,http://localhost"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolmaxage=3600"
+      - "traefik.http.middlewares.obsidiancors.headers.addvaryheader=true"
+      - "traefik.http.middlewares.obsidiancors.headers.accessControlAllowCredentials=true"
+
+networks:
+  proxy:
+    external: true

docker/.env.example

@@ -0,0 +1,52 @@
+# Self-hosted LiveSync — Environment Variables
+# Copy this file to .env and fill in your values.
+# NEVER commit .env to version control.
+
+# =============================================================================
+# REQUIRED — CouchDB credentials
+# =============================================================================
+
+# Admin username for CouchDB
+COUCHDB_USER=admin
+
+# Admin password — use a strong random password (min 16 chars recommended)
+COUCHDB_PASSWORD=change_me_use_a_strong_password
+
+# Name of the database the Obsidian plugin will use
+COUCHDB_DATABASE=obsidiannotes
+
+# Host port CouchDB is exposed on (default: 5984)
+# For tunnel-only deployments you can set this to 127.0.0.1:5984 to block external access
+COUCHDB_PORT=5984
+
+# =============================================================================
+# PROFILE: caddy  (--profile caddy)
+# =============================================================================
+
+# Your public domain pointing to this server (A record)
+# Example: couchdb.yourdomain.com
+COUCHDB_DOMAIN=couchdb.yourdomain.com
+
+# Email for Let's Encrypt TLS certificate notifications
+ACME_EMAIL=you@yourdomain.com
+
+# =============================================================================
+# PROFILE: tailscale  (--profile tailscale)
+# =============================================================================
+
+# Tailscale OAuth key (not a regular auth key — must be OAuth for persistent use)
+# Generate at: https://login.tailscale.com/admin/settings/oauth
+# Scopes needed: devices:write
+TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Hostname this node will have on your tailnet (becomes <hostname>.<tailnet>.ts.net)
+TS_HOSTNAME=livesync
+
+# =============================================================================
+# PROFILE: cloudflare  (--profile cloudflare)
+# =============================================================================
+
+# Tunnel token from Cloudflare Zero Trust dashboard
+# Create at: https://one.dash.cloudflare.com/ → Networks → Tunnels → Create tunnel
+# Copy the token from the "Install connector" step
+CF_TUNNEL_TOKEN=eyJhIjoixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

docker/README.md

@@ -0,0 +1,349 @@
+# Self-hosted LiveSync — Docker Setup
+
+A fully self-hosted CouchDB stack for the [obsidian-livesync](https://github.com/vrtmrz/obsidian-livesync) plugin.  
+**No fly.io. No IBM Cloudant. No cloud accounts required for basic use.**
+
+> ✅ **Tested on Docker Desktop for Windows (Docker 29.2, Compose v5, WSL2 backend)** — full init, CORS, auth, and idempotent restart verified.
+
+---
+
+## Architecture
+
+```
+Obsidian (desktop / iOS / Android)
+        │  CouchDB Replication Protocol (HTTPS)
+        ▼
+[ Reverse Proxy / Tunnel ]  ◄── Choose ONE profile below
+        │
+        ▼
+[ CouchDB container ]  ◄── The only required service
+        │  initialized once by couchdb-init container
+        ▼
+[ Named Docker Volume ]  ◄── All vault data stored here
+```
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+
+- [Docker Desktop](https://docs.docker.com/desktop/) (Windows/Mac/Linux) or Docker Engine + Compose plugin
+- A machine that Obsidian devices can reach over HTTPS (see profiles below)
+
+### 2. Configure
+
+```bash
+cd docker/
+cp .env.example .env
+# Edit .env — at minimum set COUCHDB_USER and a strong COUCHDB_PASSWORD
+```
+
+### 3. Launch
+
+```bash
+# Default: CouchDB only (LAN / localhost, no TLS)
+docker compose up -d
+
+# With Caddy (public domain + auto Let's Encrypt)
+docker compose --profile caddy up -d
+
+# With Tailscale (no domain needed, private mesh or public Funnel)
+docker compose --profile tailscale up -d
+
+# With Cloudflare Tunnel (Cloudflare account required)
+docker compose --profile cloudflare up -d
+```
+
+### 4. Verify
+
+```bash
+# Should return {"status":"ok"}
+curl -u admin:yourpassword http://localhost:5984/_up
+
+# Check CORS headers
+curl -v -H "Origin: app://obsidian.md" \
+     -u admin:yourpassword \
+     http://localhost:5984/
+```
+
+### 5. Connect Obsidian
+
+In the Obsidian plugin settings (**Self-hosted LiveSync**):
+
+| Field | Value |
+|---|---|
+| URI | `https://your-domain-or-ts-hostname:5984` (or `http://localhost:5984` for LAN-only) |
+| Username | value of `COUCHDB_USER` |
+| Password | value of `COUCHDB_PASSWORD` |
+| Database name | value of `COUCHDB_DATABASE` (default: `obsidiannotes`) |
+| End-to-end passphrase | *your own chosen passphrase — never stored server-side* |
+
+---
+
+## Profile Details
+
+### Default (no profile) — LAN / Localhost only
+
+CouchDB is exposed on `http://localhost:5984` (or LAN IP).  
+**Desktop Obsidian works over HTTP.** Mobile Obsidian requires HTTPS — use a tunnel profile.
+
+### `--profile caddy` — Public Domain + Auto TLS
+
+**Requires**:
+- A domain with an A record pointing to this server's public IP
+- Ports 80 and 443 open in your firewall/router
+
+**Set in `.env`**:
+```
+COUCHDB_DOMAIN=couchdb.yourdomain.com
+ACME_EMAIL=you@example.com
+```
+
+Caddy automatically issues a Let's Encrypt certificate. No manual cert management.
+
+### `--profile tailscale` — No Domain Required ✅ Recommended for privacy
+
+**Requires**:
+- Free [Tailscale account](https://login.tailscale.com/)
+- Install the Tailscale app on all your Obsidian devices
+- Generate an **OAuth key** at: https://login.tailscale.com/admin/settings/oauth  
+  (Scopes: `devices:write`)
+
+**Set in `.env`**:
+```
+TS_AUTHKEY=tskey-auth-...
+TS_HOSTNAME=livesync
+```
+
+**Two sub-modes**:
+- **VPN mode** (default): CouchDB accessible only to devices on your Tailnet at  
+  `https://livesync.<tailnet>.ts.net` — completely private
+- **Funnel mode**: public HTTPS at `https://livesync.<tailnet>.ts.net` — no domain purchase  
+  Enable in your [Tailscale ACL](https://login.tailscale.com/admin/acls):
+  ```json
+  "nodeAttrs": [{"target": ["tag:container"], "attr": ["funnel"]}]
+  ```
+
+> **Note on Windows Docker Desktop**: If `/dev/net/tun` is unavailable, add `TS_USERSPACE=true`  
+> to the tailscale service environment in `docker-compose.yml`.
+
+### `--profile cloudflare` — Cloudflare Tunnel
+
+**Requires**:
+- Free [Cloudflare account](https://www.cloudflare.com/)
+- A domain managed by Cloudflare DNS (can transfer existing domain for free)
+- Cloudflare Zero Trust account (free)
+
+#### Step 1: Create a Cloudflare Tunnel
+
+1. Log in to [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
+2. Navigate to **Networks → Tunnels**
+3. Click **Create a tunnel**
+4. Choose **Cloudflared** as tunnel type
+5. Name your tunnel (e.g., `obsidian-livesync`)
+6. Click **Save tunnel**
+7. **Copy the tunnel token** — it looks like `eyJhIjoiZX...` (very long, ~400 characters)
+
+#### Step 2: Configure Environment
+
+Edit `docker/.env`:
+```env
+CF_TUNNEL_TOKEN=eyJhIjoiZX...   # Paste the full token from Step 1
+COUCHDB_DOMAIN=sync.yourdomain.com   # Must be a domain managed by Cloudflare
+```
+
+#### Step 3: Add Public Hostname Route
+
+🚨 **CRITICAL**: Token-based tunnels ignore the local `cloudflared.yml` config file. All routing is controlled from the dashboard.
+
+Back in the Zero Trust dashboard, **in the same tunnel creation flow** (or edit your tunnel later):
+
+1. Go to the **Public Hostname** tab
+2. Click **Add a public hostname**
+3. Configure:
+   - **Subdomain**: `sync` (or your preferred subdomain)
+   - **Domain**: Select your Cloudflare domain from dropdown
+   - **Type**: `HTTP`
+   - **URL**: `couchdb:5984` ← **Do NOT use `localhost`!**
+
+**Why `couchdb:5984` not `localhost:5984`?**
+- The `cloudflared` container runs inside Docker on the same network as `couchdb`
+- Docker's internal DNS resolves `couchdb` to the correct container
+- Using `localhost` would look inside the `cloudflared` container (nothing there)
+
+4. Under **Additional application settings** (expand):
+   - **No TLS Verify**: Leave **OFF** (CouchDB uses plain HTTP internally, that's fine)
+   - Leave other settings at defaults
+5. Click **Save hostname**
+
+#### Step 4: Start the Stack
+
+```bash
+cd docker/
+docker compose --profile cloudflare up -d
+```
+
+Verify containers are running:
+```bash
+docker ps --filter "name=livesync"
+```
+
+You should see:
+- `livesync-couchdb` — Status: Up (healthy)
+- `livesync-cloudflared` — Status: Up
+- `livesync-init` — Status: Exited (0)
+
+#### Step 5: Test the Connection
+
+```bash
+# Should return 401 Unauthorized (proves CouchDB auth is working)
+curl -I https://sync.yourdomain.com
+
+# Should return {"couchdb":"Welcome",...}
+curl -u admin:yourpassword https://sync.yourdomain.com
+```
+
+If you get **404**, see Troubleshooting below.
+
+#### Step 6: Configure Obsidian Plugin
+
+In Obsidian → Settings → **Self-hosted LiveSync**:
+
+| Field | Value |
+|---|---|
+| URI | `https://sync.yourdomain.com` |
+| Username | value of `COUCHDB_USER` from `.env` |
+| Password | value of `COUCHDB_PASSWORD` from `.env` |
+| Database name | value of `COUCHDB_DATABASE` from `.env` (default: `obsidiannotes`) |
+| End-to-end passphrase | *Choose your own* — never stored server-side |
+
+Under **Remote Database Configuration → Advanced**:
+- Enable: ✅ **Use Request API to avoid inevitable CORS problem**
+  (See "Known Issue" below for why this is critical)
+
+---
+
+#### 🔧 Troubleshooting Cloudflare Tunnel
+
+**Problem: 404 Error / Cloud flare Generic Error Page**
+
+**Diagnosis**:
+```bash
+# Check if cloudflared is running
+docker logs livesync-cloudflared --tail 20
+
+# Look for: "Registered tunnel connection"
+# If you see the connector ID, the tunnel is connected but routing is wrong
+```
+
+**Fix**: The public hostname rule is missing or incorrect.
+
+1. Go to Zero Trust → Networks → Tunnels → your tunnel → **Edit**
+2. Click **Public Hostname** tab
+3. Verify a hostname exists with:
+   - Service Type: `HTTP`
+   - URL: `couchdb:5984` (NOT `localhost:5984`)
+4. If no hostname exists, add it (see Step 3 above)
+5. Wait 30 seconds for changes to propagate, then test again
+
+**Problem: Connection immediately closes / 502 Bad Gateway**
+
+**Diagnosis**: CouchDB is not healthy or not on the same Docker network as cloudflared.
+
+```bash
+docker ps --filter "name=livesync-couchdb"
+# Status should be: Up (healthy)
+
+docker inspect livesync-couchdb -f '{{.NetworkSettings.Networks}}'
+# Should show: livesync-net
+
+docker inspect livesync-cloudflared -f '{{.NetworkSettings.Networks}}'
+# Should also show: livesync-net
+```
+
+**Fix**: If CouchDB is unhealthy, check logs:
+```bash
+docker logs livesync-couchdb --tail 50
+```
+
+**Problem: 524 Timeout Errors During Sync**
+
+**Root cause**: Cloudflare's proxy has a **100-second idle timeout**. CouchDB's replication protocol uses long-polling on the `_changes` feed, which can idle for longer during quiet periods.
+
+**Fix**: Switch to short-polling mode in the Obsidian plugin:
+1. Obsidian → Settings → Self-hosted LiveSync
+2. **Remote Database Configuration → Advanced**
+3. Enable: ✅ **Use Request API to avoid inevitable CORS problem**
+4. Save and restart sync
+
+This keeps all requests under 100 seconds.
+
+**Alternative**: Use Tailscale or Caddy profiles instead — neither has aggressive timeouts.
+
+---
+
+## Data & Backup
+
+All vault data lives in the `couchdb-data` Docker named volume.
+
+```bash
+# Backup
+docker run --rm -v obsidian-livesync_couchdb-data:/data \
+  -v $(pwd)/backup:/backup alpine \
+  tar czf /backup/couchdb-backup-$(date +%Y%m%d).tar.gz -C /data .
+
+# Restore
+docker run --rm -v obsidian-livesync_couchdb-data:/data \
+  -v $(pwd)/backup:/backup alpine \
+  tar xzf /backup/couchdb-backup-20260218.tar.gz -C /data
+```
+
+---
+
+## Security Notes
+
+- CouchDB requires authentication for **all** requests (configured by `livesync.ini`)
+- Enable **End-to-End Encryption** passphrase in the Obsidian plugin — vault data is  
+  encrypted before it ever leaves your device
+- The init container runs once and exits — it has no persistent access
+- Never expose CouchDB's admin interface (`/_utils`) to the public internet;  
+  use a firewall rule or the path-based obfuscation trick from  
+  [self-hosted-livesync-server](https://github.com/vrtmrz/self-hosted-livesync-server)
+
+---
+
+## Useful Commands
+
+```bash
+# View logs
+docker compose logs -f couchdb
+docker compose logs couchdb-init
+
+# Re-run init (e.g. after changing credentials)
+docker compose restart couchdb-init
+
+# Stop without removing data
+docker compose down
+
+# Stop AND remove all data volumes (DESTRUCTIVE)
+docker compose down -v
+
+# Open CouchDB admin UI (Fauxton) in browser
+open http://localhost:5984/_utils
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| Init container keeps restarting | CouchDB not healthy yet — wait 30s, check `docker compose logs couchdb` |
+| `curl: (52) Empty reply` | CouchDB not fully started — the healthcheck should gate this |
+| Mobile can't connect | Needs HTTPS — use tailscale or caddy profile |
+| 524 errors with Cloudflare | Enable "Use Request API" toggle in Obsidian plugin |
+| `Permission denied` on volumes | Run `docker compose down -v` and retry — first-run volume ownership issue |
+| CORS errors in browser | Confirm CouchDB headers: `curl -v -H "Origin: app://obsidian.md" http://localhost:5984/` |
+| CouchDB exits immediately, zero logs (Windows) | **Do not add `:ro`** to the `livesync.ini` volume mount. CouchDB's entrypoint runs `chmod 0644` on all files in `/opt/couchdb/etc` — read-only bind mounts cause a silent EPERM crash on Docker Desktop for Windows (WSL2). The compose file is already correct; do not modify it. |
+| Settings in `livesync.ini` seem ignored | Settings requiring restart (e.g. bind_address) load at start. Runtime-only settings (require_valid_user, enable_cors) are set by the init container via REST API and take effect immediately without restart. |

docker/config/Caddyfile

@@ -0,0 +1,26 @@
+# Caddy config for Self-hosted LiveSync CouchDB
+# =============================================================================
+# IMPORTANT: CouchDB handles CORS itself.
+# Do NOT add CORS headers here — they will conflict with CouchDB's own headers.
+# Do NOT intercept OPTIONS requests.
+# =============================================================================
+
+{
+    # Email used for Let's Encrypt certificate notifications
+    email {$ACME_EMAIL}
+}
+
+{$COUCHDB_DOMAIN} {
+    # Forward all traffic to CouchDB, preserving Host and forwarded-for headers
+    reverse_proxy couchdb:5984 {
+        header_up Host {host}
+        header_up X-Forwarded-For {remote_host}
+        header_up X-Forwarded-Proto {scheme}
+    }
+
+    # Logging
+    log {
+        output stdout
+        level WARN
+    }
+}

docker/config/cloudflared.yml

@@ -0,0 +1,31 @@
+# cloudflared tunnel configuration for Self-hosted LiveSync
+# =============================================================================
+#
+# Prerequisites:
+#   1. Create a tunnel in Cloudflare Zero Trust → Networks → Tunnels
+#   2. Copy the tunnel token to CF_TUNNEL_TOKEN in your .env
+#   3. Add a public hostname in the tunnel config:
+#       Hostname : couchdb.yourdomain.com   (or whatever you set COUCHDB_DOMAIN to)
+#       Service  : http://couchdb:5984
+#
+# Known issue: Cloudflare's 100-second proxy timeout can interrupt CouchDB's
+# long-polling replication change feed, causing 524 errors.
+# MITIGATION: In the Obsidian plugin settings, enable:
+#   "Use Request API to avoid inevitable CORS problem"
+# This switches from long-poll to short-poll mode.
+#
+# =============================================================================
+
+tunnel: ${CF_TUNNEL_ID}
+credentials-file: /etc/cloudflared/credentials.json
+
+ingress:
+  - hostname: ${COUCHDB_DOMAIN}
+    service: http://couchdb:5984
+    originRequest:
+      # Increase timeouts for CouchDB replication streams
+      connectTimeout: 30s
+      keepAliveTimeout: 90s
+      keepAliveConnections: 100
+      noTLSVerify: false
+  - service: http_status:404

docker/config/livesync.ini

@@ -0,0 +1,30 @@
+; CouchDB local configuration for Self-hosted LiveSync
+; This file is volume-mounted into /opt/couchdb/etc/local.d/livesync.ini
+;
+; IMPORTANT: Do NOT set require_valid_user here.
+; CouchDB needs to start without auth to complete its first-run cluster setup
+; (_users, _replicator databases must be created first).
+; The couchdb-init service applies auth lockdown via REST API after first-run.
+
+[couchdb]
+; Max size per document (50MB). Large enough for binary attachments.
+max_document_size = 50000000
+
+[chttpd]
+; Bind on all interfaces.
+bind_address = 0.0.0.0
+port = 5984
+; 4 GB max request (handles very large vaults)
+max_http_request_size = 4294967296
+
+[httpd]
+WWW-Authenticate = Basic realm="couchdb"
+
+[cors]
+; These are the exact app origins Obsidian uses on desktop + mobile
+credentials = true
+origins = app://obsidian.md,capacitor://localhost,http://localhost
+
+[log]
+; Reduce noise in Docker logs — set to "debug" if troubleshooting
+level = warning

docker/config/ts-serve.json

@@ -0,0 +1,19 @@
+{
+    "TCP": {
+        "443": {
+            "HTTPS": true
+        }
+    },
+    "Web": {
+        "${TS_CERT_DOMAIN}:443": {
+            "Handlers": {
+                "/": {
+                    "Proxy": "http://127.0.0.1:5984"
+                }
+            }
+        }
+    },
+    "AllowFunnel": {
+        "${TS_CERT_DOMAIN}:443": true
+    }
+}

docker/docker-compose.yml

@@ -0,0 +1,187 @@
+# Self-hosted LiveSync — Docker Compose
+# =============================================================================
+#  PROFILES
+#  --------
+#  (default)              CouchDB only — LAN/localhost access, no TLS
+#                         Suitable for desktop-only use or testing.
+#
+#  --profile caddy        CouchDB + Caddy reverse proxy
+#                         Auto TLS via Let's Encrypt. Needs public domain + ports 80/443.
+#
+#  --profile tailscale    CouchDB + Tailscale sidecar
+#                         No domain required. HTTPS via *.ts.net PKI.
+#                         Needs a Tailscale account (free tier works).
+#
+#  --profile cloudflare   CouchDB + cloudflared tunnel daemon
+#                         Free public HTTPS via Cloudflare. Needs a CF account + tunnel token.
+#                         NOTE: Enable "Use Request API" in the Obsidian plugin to avoid 524 timeouts.
+#
+#  QUICK START (local test):
+#    cp .env.example .env && edit .env
+#    docker compose up -d
+#    curl -u admin:yourpassword http://localhost:5984/_up
+# =============================================================================
+
+name: obsidian-livesync
+
+services:
+
+  # ---------------------------------------------------------------------------
+  # CouchDB — the only required service
+  # ---------------------------------------------------------------------------
+  couchdb:
+    image: couchdb:latest
+    container_name: livesync-couchdb
+    restart: unless-stopped
+    # NOTE: Do NOT set user: here — the CouchDB entrypoint starts as root to
+    # write docker.ini (from env vars), then drops to uid 5984 automatically.
+    environment:
+      COUCHDB_USER: ${COUCHDB_USER:?Set COUCHDB_USER in .env}
+      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD:?Set COUCHDB_PASSWORD in .env}
+    volumes:
+      - couchdb-data:/opt/couchdb/data
+      # Mount to /opt/couchdb/etc/local.ini (NOT into local.d/).
+      # Do NOT use :ro — the CouchDB entrypoint runs chmod on this file at startup
+      # and will crash with EPERM if the file is read-only. The file is only read
+      # at startup; runtime changes go via the REST API into local.d/docker.ini.
+      - ./config/livesync.ini:/opt/couchdb/etc/local.ini
+    ports:
+      # Exposes CouchDB on the host for LAN/localhost access.
+      # The tunnel profiles (caddy/tailscale/cloudflare) provide HTTPS on top.
+      # You can remove this port mapping once a tunnel profile is in use.
+      - "${COUCHDB_PORT:-5984}:5984"
+    healthcheck:
+      # Test with admin credentials — ensures both CouchDB is up AND auth is ready.
+      # ${COUCHDB_USER} / ${COUCHDB_PASSWORD} are expanded by Docker Compose here.
+      test:
+        - "CMD-SHELL"
+        - "curl -sf -u ${COUCHDB_USER}:${COUCHDB_PASSWORD} http://localhost:5984/_session | grep -q ok || exit 1"
+      interval: 5s
+      timeout: 5s
+      retries: 24
+      start_period: 20s
+    networks:
+      - livesync-net
+
+  # ---------------------------------------------------------------------------
+  # One-shot init container — runs couchdb-init.sh after CouchDB is healthy.
+  # Sets single-node cluster, auth requirements, CORS, size limits, creates DB.
+  # Restarts on failure (e.g. race at first boot) but won't re-run if already done.
+  # ---------------------------------------------------------------------------
+  couchdb-init:
+    image: curlimages/curl:latest
+    container_name: livesync-init
+    restart: on-failure
+    depends_on:
+      couchdb:
+        condition: service_healthy
+    environment:
+      COUCHDB_INTERNAL_URL: http://couchdb:5984
+      COUCHDB_USER: ${COUCHDB_USER}
+      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD}
+      COUCHDB_DATABASE: ${COUCHDB_DATABASE:-obsidiannotes}
+    volumes:
+      - ./scripts/couchdb-init.sh:/couchdb-init.sh:ro
+    entrypoint: ["sh", "/couchdb-init.sh"]
+    networks:
+      - livesync-net
+
+  # ---------------------------------------------------------------------------
+  # PROFILE: caddy — Caddy reverse proxy with automatic Let's Encrypt TLS
+  # Requirements: public domain, ports 80 + 443 open to internet
+  # Usage: docker compose --profile caddy up -d
+  # ---------------------------------------------------------------------------
+  caddy:
+    image: caddy:latest
+    container_name: livesync-caddy
+    profiles: [caddy]
+    restart: unless-stopped
+    depends_on:
+      couchdb:
+        condition: service_healthy
+    environment:
+      COUCHDB_DOMAIN: ${COUCHDB_DOMAIN:?Set COUCHDB_DOMAIN in .env for caddy profile}
+      ACME_EMAIL: ${ACME_EMAIL:?Set ACME_EMAIL in .env for caddy profile}
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./config/Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+    networks:
+      - livesync-net
+
+  # ---------------------------------------------------------------------------
+  # PROFILE: tailscale — Tailscale sidecar for mesh VPN + optional Funnel
+  # Requirements: Tailscale account (free), OAuth key, Funnel enabled in ACL
+  # Usage: docker compose --profile tailscale up -d
+  # The CouchDB port mapping above can be removed for tailscale-only deployments.
+  # ---------------------------------------------------------------------------
+  tailscale:
+    image: tailscale/tailscale:latest
+    container_name: livesync-tailscale
+    profiles: [tailscale]
+    restart: unless-stopped
+    hostname: ${TS_HOSTNAME:-livesync}
+    environment:
+      TS_AUTHKEY: ${TS_AUTHKEY:?Set TS_AUTHKEY in .env for tailscale profile}
+      TS_STATE_DIR: /var/lib/tailscale
+      TS_SERVE_CONFIG: /config/serve.json
+      TS_USERSPACE: "false"
+      TS_ACCEPT_DNS: "false"
+      TS_EXTRA_ARGS: ""
+    volumes:
+      - tailscale-state:/var/lib/tailscale
+      - ./config/ts-serve.json:/config/serve.json:ro
+      - /dev/net/tun:/dev/net/tun
+    cap_add:
+      - NET_ADMIN
+      - SYS_MODULE
+    # Share CouchDB's network namespace so Tailscale can reach it on localhost
+    network_mode: service:couchdb
+    depends_on:
+      - couchdb
+
+  # ---------------------------------------------------------------------------
+  # PROFILE: cloudflare — cloudflared tunnel daemon
+  # Requirements: Cloudflare account, tunnel token from CF Zero Trust dashboard
+  # Usage: docker compose --profile cloudflare up -d
+  # NOTE: Enable "Use Request API" toggle in the Obsidian LiveSync plugin settings
+  #       to avoid Cloudflare's 100-second proxy timeout (524 errors).
+  # ---------------------------------------------------------------------------
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    container_name: livesync-cloudflared
+    profiles: [cloudflare]
+    restart: unless-stopped
+    command: tunnel --no-autoupdate run
+    environment:
+      TUNNEL_TOKEN: ${CF_TUNNEL_TOKEN:?Set CF_TUNNEL_TOKEN in .env for cloudflare profile}
+    volumes:
+      - ./config/cloudflared.yml:/etc/cloudflared/config.yml:ro
+    depends_on:
+      couchdb:
+        condition: service_healthy
+    networks:
+      - livesync-net
+
+# =============================================================================
+# Volumes
+# =============================================================================
+volumes:
+  couchdb-data:
+    driver: local
+  caddy-data:
+    driver: local
+  caddy-config:
+    driver: local
+  tailscale-state:
+    driver: local
+
+# =============================================================================
+# Networks
+# =============================================================================
+networks:
+  livesync-net:
+    driver: bridge

docker/scripts/couchdb-init.sh

@@ -0,0 +1,79 @@
+#!/bin/sh
+# Self-hosted LiveSync — CouchDB Initialization Script
+# Runs once on first startup via the couchdb-init service.
+# Configures single-node cluster, auth, CORS, and size limits.
+
+set -e
+
+hostname="${COUCHDB_INTERNAL_URL:-http://couchdb:5984}"
+username="${COUCHDB_USER:?COUCHDB_USER is required}"
+password="${COUCHDB_PASSWORD:?COUCHDB_PASSWORD is required}"
+node="${COUCHDB_NODE:-_local}"
+
+echo "==> Waiting for CouchDB at ${hostname} ..."
+# _up is publicly accessible (no auth required) — safe pre-auth wait
+until curl -sf "${hostname}/_up" 2>/dev/null | grep -q '"status":"ok"'; do
+    printf '.'
+    sleep 2
+done
+echo ""
+echo "==> CouchDB is up. Initializing..."
+
+# 1. Enable single-node cluster
+curl -sf -X POST "${hostname}/_cluster_setup" \
+    -H "Content-Type: application/json" \
+    -d "{\"action\":\"enable_single_node\",\"username\":\"${username}\",\"password\":\"${password}\",\"bind_address\":\"0.0.0.0\",\"port\":5984,\"singlenode\":true}" \
+    --user "${username}:${password}" && echo "[OK] cluster_setup"
+
+# 2. Require valid user on both http interfaces
+curl -sf -X PUT "${hostname}/_node/${node}/_config/chttpd/require_valid_user" \
+    -H "Content-Type: application/json" -d '"true"' --user "${username}:${password}" && echo "[OK] chttpd/require_valid_user"
+
+curl -sf -X PUT "${hostname}/_node/${node}/_config/chttpd_auth/require_valid_user" \
+    -H "Content-Type: application/json" -d '"true"' --user "${username}:${password}" && echo "[OK] chttpd_auth/require_valid_user"
+
+# 3. HTTP auth challenge header
+curl -sf -X PUT "${hostname}/_node/${node}/_config/httpd/WWW-Authenticate" \
+    -H "Content-Type: application/json" -d '"Basic realm=\"couchdb\""' --user "${username}:${password}" && echo "[OK] httpd/WWW-Authenticate"
+
+# 4. Enable CORS on both http listeners
+curl -sf -X PUT "${hostname}/_node/${node}/_config/httpd/enable_cors" \
+    -H "Content-Type: application/json" -d '"true"' --user "${username}:${password}" && echo "[OK] httpd/enable_cors"
+
+curl -sf -X PUT "${hostname}/_node/${node}/_config/chttpd/enable_cors" \
+    -H "Content-Type: application/json" -d '"true"' --user "${username}:${password}" && echo "[OK] chttpd/enable_cors"
+
+# 5. Increase size limits for large vaults
+curl -sf -X PUT "${hostname}/_node/${node}/_config/chttpd/max_http_request_size" \
+    -H "Content-Type: application/json" -d '"4294967296"' --user "${username}:${password}" && echo "[OK] chttpd/max_http_request_size"
+
+curl -sf -X PUT "${hostname}/_node/${node}/_config/couchdb/max_document_size" \
+    -H "Content-Type: application/json" -d '"50000000"' --user "${username}:${password}" && echo "[OK] couchdb/max_document_size"
+
+# 6. CORS configuration — allow Obsidian app origins
+curl -sf -X PUT "${hostname}/_node/${node}/_config/cors/credentials" \
+    -H "Content-Type: application/json" -d '"true"' --user "${username}:${password}" && echo "[OK] cors/credentials"
+
+curl -sf -X PUT "${hostname}/_node/${node}/_config/cors/origins" \
+    -H "Content-Type: application/json" \
+    -d '"app://obsidian.md,capacitor://localhost,http://localhost"' \
+    --user "${username}:${password}" && echo "[OK] cors/origins"
+
+# 7. Create the vault database if it doesn't exist
+db="${COUCHDB_DATABASE:-obsidiannotes}"
+set +e
+status=$(curl -sf -o /dev/null -w "%{http_code}" --user "${username}:${password}" "${hostname}/${db}" 2>/dev/null)
+curl_exit=$?
+set -e
+
+if [ "$status" = "200" ]; then
+    echo "[OK] database '${db}' already exists"
+else
+    curl -sf -X PUT "${hostname}/${db}" --user "${username}:${password}" && echo "[OK] database '${db}' created" || echo "[WARN] database creation returned non-200 — may already exist"
+fi
+
+echo ""
+echo "==> CouchDB initialization complete!"
+echo "    URL      : ${hostname}"
+echo "    Database : ${db}"
+echo "    Username : ${username}"

docs/adding_translations.md

@@ -0,0 +1,38 @@
+# How to add translations
+
+Self-hosted LiveSync owns its multilingual catalogue. Commonlib supplies only the typed English messages which its services request; the plug-in combines those keys with its application messages and injects the selected translator at each service composition root.
+
+## Getting ready
+
+1. Clone this repository.
+
+    ```sh
+    git clone https://github.com/vrtmrz/obsidian-livesync
+    cd obsidian-livesync
+    npm ci
+    ```
+
+2. Create an `ls-debug` directory below the test Vault's `.obsidian` directory, for example `.obsidian/ls-debug`.
+
+## Add translations for existing messages
+
+1. Edit the human-readable YAML files under `src/common/messagesYAML/`.
+2. Regenerate the JSON and TypeScript resources.
+
+    ```sh
+    npm run i18n:bake
+    ```
+
+3. Build the plug-in in development mode, install it in the test Vault, and run Self-hosted LiveSync.
+4. Review any `missing-translation-yyyy-mm-dd.jsonl` file written below `.obsidian/ls-debug`, and add the required translations to the YAML catalogue.
+5. Bake and build again, then confirm the displayed text and placeholder substitution in the relevant workflow.
+
+Commit the edited YAML and all regenerated JSON and TypeScript resources together.
+
+## Make a message translatable
+
+1. Add its canonical English entry and translations to `src/common/messagesYAML/`.
+2. Replace the source literal with `$msg()` or another existing translation helper, using the English catalogue key as the typed contract.
+3. Run `npm run i18n:bake`, build the plug-in, and verify the affected workflow.
+
+When a new message belongs to Commonlib rather than the application, add its canonical English definition and key type in Commonlib first. Add any available translations to LiveSync when consuming that package; untranslated languages use Commonlib's canonical English fallback.

docs/adr/2026_06_real_obsidian_e2e.md

@@ -0,0 +1,252 @@
+# Architectural Decision Record: Real Obsidian End-to-End Test Runner
+
+## Status
+
+Accepted / Implemented
+
+## Release
+
+Accepted — implemented as the maintained local E2E layer for the 1.0 release preparation.
+
+## Context
+
+When this decision was proposed, the end-to-end tests ran through Vitest browser mode and a mocked Obsidian environment in `test/harness`. This was useful for exercising synchronisation flows without launching Obsidian, but it was no longer a reliable final signal for plug-in behaviour.
+
+The main issues are:
+
+- The harness reimplements a large part of the Obsidian API surface, including vault files, workspace events, settings, and lifecycle behaviour. This mock can drift from real Obsidian behaviour without failing.
+- The tests run inside a browser-style environment, while the desktop plug-in runs inside Obsidian's Electron environment with its own application lifecycle, storage paths, command registry, and event ordering.
+- Several high-value regressions are about integration boundaries: boot-up sequence timing, real vault file reflection, Obsidian command registration, settings persistence, restart prompts, and file watcher behaviour. These are precisely the areas where a mock harness gives weak confidence.
+- Maintaining the harness competes with maintaining the plug-in. Adding behaviour to the plug-in often requires teaching the mock another Obsidian detail before the actual regression can be tested.
+
+The current harness should therefore stop being treated as the primary E2E layer.
+
+## Decision
+
+Introduce a new E2E layer that launches real Obsidian with temporary vaults and the built Self-hosted LiveSync plug-in installed into those vaults.
+
+The long-term test pyramid should be:
+
+1. Unit tests for deterministic operations and serviceFeature boundaries.
+2. Integration tests for CouchDB, Object Storage, P2P services, database operations, and replication protocols.
+3. Real Obsidian E2E tests for boot-up sequence, vault reflection, command registration, settings dialogues, restart scheduling, and user-visible workflows.
+
+Retain the existing browser Harness only as a transitional compatibility layer while the real Obsidian runner reaches parity for critical flows, then remove it. New high-level E2E coverage targets the real runner.
+
+## Non-Goals
+
+- Do not replace unit or integration tests with slow UI tests.
+- Do not keep extending the Obsidian mock to cover new Obsidian APIs unless a short-term compatibility bridge is required.
+- Do not require real Obsidian E2E for every pull request initially. The first CI integration should be opt-in or nightly until stability is proven.
+- Do not test every setting dialogue through UI clicks if the behaviour is already covered by unit or integration tests. Use UI automation only for workflows whose risk is in real Obsidian integration.
+
+## Proposed Architecture
+
+### Runner
+
+Create a dedicated runner under `test/e2e-obsidian/`.
+
+The runner should:
+
+- Create one or more temporary vault directories.
+- Build the plug-in once with `npm run build` or a narrower production build command.
+- Install `main.js`, `manifest.json`, and `styles.css` when present into `.obsidian/plugins/obsidian-livesync/`.
+- Prepare `.obsidian/community-plugins.json` and `.obsidian/plugins/obsidian-livesync/data.json` as needed.
+- Launch Obsidian against the temporary vault.
+- Wait until the plug-in reports readiness through a deterministic probe.
+- Drive assertions through a narrow control channel rather than fragile visual selectors wherever possible.
+- Dispose of Obsidian and temporary vaults after each scenario.
+
+### Obsidian Launch
+
+The preferred desktop target is the installed Obsidian application. The launch mechanism should be platform-specific but hidden behind a small adapter:
+
+- Linux: launch the Obsidian executable with a vault path or Obsidian URI, depending on what is most reliable. If an AppImage is used and FUSE is not available, extract it with `--appimage-extract` and launch the extracted `squashfs-root/obsidian` binary.
+- macOS: launch the app bundle through `open` or the executable inside the bundle.
+- Windows: launch the installed executable or the registered application protocol.
+
+The first implementation can support Linux only if that is the local and CI target. Cross-platform support can be added after the runner contract is stable.
+
+In headless Linux environments, launch through `xvfb-run`, pass Electron flags such as `--no-sandbox` and `--disable-gpu`, and isolate `HOME`, `XDG_CONFIG_HOME`, and `--user-data-dir` per temporary vault.
+
+### Control Channel
+
+The runner needs a stable way to observe readiness and issue test commands. Prefer a test-only plug-in bridge compiled only in test builds or enabled only by an environment variable.
+
+Possible bridge options:
+
+- The official Obsidian CLI, using the installed `obsidian-cli` helper to open vaults, reload the plug-in, run `eval`, and call developer commands.
+- A local HTTP/WebSocket bridge bound to `127.0.0.1` with a random port and token.
+- A file-based bridge in the vault, where Obsidian writes status files and consumes command files.
+- A DevTools protocol bridge if Obsidian exposes a stable debugging port in the test environment.
+
+The first implementation uses Obsidian's CLI for orchestration and readiness checks. The CLI handles vault opening through `obsidian://open?path=...`, enables community plug-ins through `app.plugins.setEnable(true)`, reloads Self-hosted LiveSync through `plugin:reload id=obsidian-livesync`, and verifies that `app.plugins.plugins['obsidian-livesync']` is loaded.
+
+This keeps E2E-only behaviour out of the production plug-in bundle. The runner should not require Self-hosted LiveSync to write marker files or expose a test server merely to prove that Obsidian loaded it.
+
+The DevTools protocol remains useful for diagnostics. Obsidian's CLI exposes developer commands such as `dev:cdp`, `dev:errors`, and `dev:console`, so the runner should prefer the CLI path first and fall back to direct DevTools attachment only if the CLI cannot provide the required signal.
+
+### Test Data and Services
+
+Keep the existing Docker scripts for CouchDB, MinIO, and P2P services. The real Obsidian runner should reuse these service fixtures instead of creating another service orchestration stack.
+
+Each test should use unique database names, bucket prefixes, vault names, and P2P room IDs. This prevents tests from depending on cleanup and makes interrupted runs less harmful.
+
+## Migration Plan
+
+### Phase 0: Discovery
+
+- Confirm how Obsidian can be launched reliably on the local development environment.
+- Confirm whether Obsidian accepts a vault path directly, requires an Obsidian URI, or needs a pre-existing vault registry.
+- Identify where Obsidian stores per-user state in the test environment and decide how to isolate it.
+- Decide whether the first bridge is file-based or HTTP/WebSocket.
+
+Initial discovery on Linux ARM64 found that:
+
+- `Obsidian-1.12.7-arm64.AppImage` requires `libfuse.so.2` for direct AppImage execution.
+- Extracting the AppImage with `--appimage-extract` works without FUSE.
+- Launching the extracted `squashfs-root/obsidian` binary under `xvfb-run` with isolated user data stays alive for the smoke timeout.
+- No missing shared libraries were reported by `ldd` for the extracted binary in the tested environment.
+- Obsidian's CLI is disabled unless the global `obsidian.json` contains `cli: true`.
+- Passing only `.obsidian/community-plugins.json` is not enough to load community plug-ins on Obsidian 1.12. The runner also has to enable the global community plug-in switch through `app.plugins.setEnable(true)`.
+- The reliable launch sequence is: start Obsidian, send `obsidian://open?path=...` through `obsidian-cli`, wait until the vault-side CLI exposes the plug-in catalogue, enable community plug-ins, reload Self-hosted LiveSync, and verify plug-in readiness through `obsidian-cli eval`.
+
+### Phase 1: Smoke Runner
+
+- Add `test/e2e-obsidian/runner` utilities for temporary vault creation, plug-in installation, launch, readiness wait, and cleanup.
+- Add one smoke test:
+    - launch Obsidian with an empty vault,
+    - load Self-hosted LiveSync,
+    - wait for the boot-up sequence to become ready,
+    - read the plug-in version or status through the control channel,
+    - close Obsidian cleanly.
+- Add an npm script such as `test:e2e:obsidian`.
+
+Current implementation status:
+
+- Added `test/e2e-obsidian/runner` helpers for Obsidian discovery, CLI discovery, temporary vault creation, plug-in installation, process launch, CLI execution, and readiness polling.
+- Added `test:e2e:obsidian:discover`, `test:e2e:obsidian:cli-help`, `test:e2e:obsidian:smoke`, `test:e2e:obsidian:vault-reflection`, `test:e2e:obsidian:couchdb-upload`, `test:e2e:obsidian:minio-upload`, `test:e2e:obsidian:startup-scan`, `test:e2e:obsidian:two-vault-sync`, `test:e2e:obsidian:hidden-file-snippet-sync`, `test:e2e:obsidian:customisation-sync`, `test:e2e:obsidian:setting-markdown-export`, `test:e2e:obsidian:local-suite`, `test:e2e:obsidian:local-suite:services`, and `test:e2e:obsidian:install-appimage`.
+- Added `startObsidianLiveSyncSession()` so future workflows can reuse the launch, trusted temporary vault state, vault open, community plug-in reload, and readiness sequence without duplicating smoke runner code.
+- Added CouchDB runner utilities that reuse `.test.env`/process environment values, create unique temporary databases, query uploaded documents directly, and clean up the database unless `E2E_OBSIDIAN_KEEP_COUCHDB=true` is set.
+- Added a manual AppImage installer that downloads Obsidian `1.12.7` for `arm64` or `x86_64`, stores it under `_testdata/obsidian`, and extracts it for FUSE-free execution.
+- Confirmed the smoke runner on Linux ARM64 with the extracted Obsidian `1.12.7` AppImage, `xvfb-run`, and the built Self-hosted LiveSync bundle.
+- Confirmed the runner can enable the Obsidian CLI through isolated `obsidian.json` state, pre-seed the temporary Chromium local storage so the generated vault ID is trusted for community plug-ins, open the temporary vault through `obsidian-cli`, reload Self-hosted LiveSync, and verify readiness through `obsidian-cli eval`.
+- Removed the first test-only ready-marker bridge from the plug-in bundle. The current runner observes readiness from outside the plug-in through Obsidian's own CLI, so normal user vaults do not receive E2E marker files.
+
+Current verification:
+
+- `npm run tsc-check` passes.
+- `npm run build` passes with existing Svelte warnings.
+- `npm run test:e2e:obsidian:discover` finds `_testdata/obsidian/squashfs-root/obsidian` when the extracted AppImage is present.
+- `E2E_OBSIDIAN_SMOKE_TIMEOUT_MS=1000 npm run test:e2e:obsidian:smoke` passes locally.
+- `npm run test:e2e:obsidian:vault-reflection` creates a note through Obsidian's vault API, verifies the reflected file on disk, and reads it back through Obsidian.
+- `npm run test:e2e:obsidian:couchdb-upload` configures a unique CouchDB database, creates a note through Obsidian, commits it into the local database, runs one-shot synchronisation, and verifies that CouchDB contains the metadata document and all referenced chunk documents.
+- `npm run test:e2e:obsidian:minio-upload` configures a unique Object Storage bucket prefix, creates a note through Obsidian, runs one-shot Journal Sync, and verifies through the AWS SDK that objects were written to the S3-compatible bucket.
+- `npm run test:e2e:obsidian:startup-scan` verifies that a file written while Obsidian is stopped is picked up during the next real Obsidian boot and uploaded to CouchDB after one-shot synchronisation.
+- `npm run test:e2e:obsidian:two-vault-sync` verifies two-vault note synchronisation: creation, update, rename, deletion, per-device target-filter differences, and a separate encrypted round-trip with Path Obfuscation enabled. The experimental Markdown conflict automatic merge check is available with `E2E_OBSIDIAN_INCLUDE_MARKDOWN_CONFLICT=true` but is not part of the default local suite.
+- `npm run test:e2e:obsidian:hidden-file-snippet-sync` verifies hidden file synchronisation as a two-vault round-trip: creation, deletion, automatic JSON conflict merging with the merged result propagated by a second synchronisation, manual JSON Resolve dialogue application through Obsidian's UI, and per-device target-pattern differences.
+- `npm run test:e2e:obsidian:customisation-sync` verifies a two-vault Customisation Sync workflow: scan a real snippet CSS file, config JSON file, and sample plug-in fixture into per-file Customisation Sync data, synchronise them through CouchDB, apply them on the second vault, assert the resulting `.obsidian` files, propagate a snippet update, and verify deletion of the source-vault snippet sync data without confusing it with the target vault's own applied copy.
+- `npm run test:e2e:obsidian:setting-markdown-export` verifies that setting Markdown export creates a vault file and omits credentials when credential export is disabled.
+- `npm run test:e2e:obsidian:install-appimage` reuses the existing AppImage and extracted binary when they are already present.
+- `npm run test:e2e:obsidian:local-suite` runs the local verification sequence for the real Obsidian runner after CouchDB, MinIO, and the P2P relay have been started.
+- `npm run test:e2e:obsidian:local-suite:services` stops leftover CouchDB, MinIO, and P2P relay fixtures, starts fresh fixtures, runs the local suite, and stops the fixtures again.
+- `npm run test:e2e:obsidian:local-suite:services` has been verified locally with real Obsidian and all three fixtures. In addition to the core launch and synchronisation scenarios, the maintained suite covers CouchDB, Object Storage, and P2P Setup URI workflows in which the working first device generates the URI imported by the second device.
+
+Known limits:
+
+- The smoke runner currently proves only one-vault launch and plug-in load readiness. Broader workflows are covered by separate real Obsidian scripts, including CouchDB upload, startup scan, two-vault note synchronisation, Hidden File Sync, Customisation Sync, and setting Markdown export.
+- The working path has been validated on Linux ARM64 and on macOS with Obsidian 1.12.7. Windows remains unverified.
+- CI wiring is intentionally not implemented. The runner depends on a licensed desktop application and is treated as a local verification tool.
+
+### Phase 2: First Real Workflow
+
+- Add a one-vault local workflow:
+    - configure a temporary CouchDB database,
+    - create a note in the real vault,
+    - wait for metadata and chunks to be stored,
+    - restart Obsidian,
+    - verify that the plug-in loads and the note remains consistent.
+
+This validates real boot-up, settings persistence, vault file access, database writes, and restart-sensitive state.
+
+Current implementation status:
+
+- Added a pre-CouchDB workflow that creates a note through Obsidian's vault API, confirms the note is reflected as a real vault file, and reads the same note back through Obsidian. This covers the vault reflection part of the Phase 2 path before remote database setup is introduced.
+- Added a first CouchDB-backed upload workflow, modelled after the CLI Deno tests: reuse the standard CouchDB environment variables, create a unique remote database, apply CouchDB settings through the plug-in's setting service, commit the note through the real Obsidian vault path, run one-shot synchronisation, and assert that remote metadata and chunks exist.
+- Added an Object Storage-backed upload workflow against MinIO to exercise Journal Sync and the AWS SDK path from real Obsidian.
+- Added Obsidian-specific workflows for boot-time vault scanning, two-vault note synchronisation, hidden `.obsidian/snippets` file round-tripping, hidden JSON conflict resolution, Customisation Sync application for snippets, config JSON files, and plug-in fixtures, per-device target-filter differences, and setting Markdown export. These scenarios assert against CouchDB documents, vault files, or real Obsidian UI outcomes instead of internal service state.
+
+### Phase 3: Two-Vault Synchronisation
+
+- Launch two Obsidian instances with two temporary vaults.
+- Configure both against the same temporary remote database.
+- Create, modify, rename, and delete notes in one vault.
+- Verify reflection in the other vault.
+- Cover encrypted and non-encrypted configurations separately.
+
+Current implementation status:
+
+- `test:e2e:obsidian:two-vault-sync` covers creation, update, rename, deletion, and per-device target-filter behaviour for a non-encrypted CouchDB configuration. Markdown conflict automatic merging remains an optional check because it needs a dedicated, less timing-sensitive fixture.
+- The same script creates a separate temporary CouchDB database and temporary vault pair for an encrypted two-vault round-trip with Path Obfuscation enabled.
+
+### Phase 4: Harness Retirement
+
+- Mark `test/harness` as deprecated in documentation.
+- Stop adding new tests to `test/suite` unless they are explicitly transitional.
+- Do not mechanically port `test/suite` into real Obsidian E2E. Scenarios that can already be exercised and asserted through the CLI test layer should stay there or move to lower-level integration tests.
+- Prioritise real Obsidian coverage for behaviours that the CLI cannot prove well, especially RedFlag flag-file recovery flows, Fast Setup (Simple Fetch), boot-up sequencing, restart-sensitive initial synchronisation, and user-visible recovery dialogues.
+- Remove the harness only after the new runner covers the critical boot-up and synchronisation workflows.
+
+Current implementation status:
+
+- The mocked Vitest browser suites, their P2P runner, their root-level relay helpers, and the manual `harness-ci` workflow have been removed after maintained suites covered the critical flows.
+- Headless CouchDB and Object Storage combinations, with and without encryption, remain owned by the CLI two-Vault matrix. P2P transport replacement and relay lifecycle remain owned by the CLI Compose E2E suite. Real Obsidian owns the visible CouchDB, Object Storage, and P2P Setup URI workflows, including first-device URI generation, second-device import, and two-way Vault synchronisation.
+- The Obsidian compatibility implementation still needed by the Webapp has moved to `src/apps/webapp/obsidianMock.ts`; it is not a retained browser E2E Harness.
+- Remaining high-value scenarios, including RedFlag and Fast Setup (Simple Fetch) variants, should be added according to their owning integration boundary rather than copied line by line from the retired suite.
+
+## Local Verification Strategy
+
+Real Obsidian E2E is a local verification layer. It should not be wired into the default CI gate.
+
+- Keep the scripts individually runnable for focused local debugging.
+- Provide `test:e2e:obsidian:local-suite` for a broader local pass after the CouchDB, MinIO, and P2P relay fixtures have been started.
+- Provide `test:e2e:obsidian:local-suite:services` for a broader local pass that manages all three fixtures itself.
+- Use `OBSIDIAN_BINARY` when testing against an installed desktop application.
+- Use `test:e2e:obsidian:install-appimage` on Linux when a local AppImage copy is needed, and reuse the extracted `_testdata/obsidian/squashfs-root` directory between local runs.
+- Capture Obsidian logs, plug-in logs, vault snapshots, and service logs manually when investigating failures.
+- Fail fast on launch failures, readiness timeouts, and cleanup failures with clear diagnostics.
+
+## Risks and Mitigations
+
+- **Obsidian licensing and installation**: Keep the runner local-first and capable of using `OBSIDIAN_BINARY`.
+- **Flakiness from UI timing**: Prefer a control channel and service-level probes over visual selectors.
+- **Multiple instances**: Obsidian may not support multiple independent instances cleanly on all platforms. Start with one-instance smoke tests, then validate two-instance behaviour on Linux before expanding scope.
+- **State leakage**: Isolate vault directories, Obsidian user data, remote database names, and bridge tokens per test.
+- **Security of E2E controls**: Keep readiness and control outside the production plug-in bundle. Prefer Obsidian CLI probes over E2E-only plug-in code.
+- **Runtime cost**: Keep real Obsidian E2E out of the default PR gate. Use focused scripts or the local suite when a change touches real Obsidian integration.
+
+## Open Questions
+
+- Which launch mechanism is most reliable for Obsidian on each supported desktop platform?
+- Can two Obsidian instances run with isolated user data at the same time?
+- Do future scenarios need a richer control channel than Obsidian CLI, or can CLI `eval` and developer commands cover the required workflows?
+- Should any future E2E-only plug-in code live in a separate test build, or should the production bundle remain free of E2E controls?
+- Which RedFlag and Fast Setup (Simple Fetch) variants should be added first?
+
+## Initial Implementation Checklist
+
+1. Add an Obsidian launch discovery script that prints the detected executable, version, and launch mode.
+2. Add temporary vault and plug-in installation helpers.
+3. Add CLI-based plug-in readiness polling.
+4. Add `test:e2e:obsidian:smoke` for one-vault plug-in load.
+5. Document required local environment variables, especially `OBSIDIAN_BINARY`.
+6. Port one CouchDB-backed workflow after the smoke test is stable.
+7. Retire the browser Harness after critical workflows have replacement coverage.
+8. Add the local suite script for broader local verification.
+
+## Consequences
+
+- Real Obsidian E2E becomes the source of truth for plug-in lifecycle and vault integration.
+- Unit and integration tests remain the primary fast feedback loops.
+- The old browser Harness has been deleted now that the replacement coverage owns its critical workflows.
+- The project will gain slower but higher-confidence tests for the behaviours most likely to differ between mocks and Obsidian itself.

docs/adr/2026_07_bounded_remote_activity.md

@@ -0,0 +1,129 @@
+# Architectural Decision Record: Bounded Remote Activity
+
+## Status
+
+Accepted
+
+## Context
+
+Self-hosted LiveSync performs remote work through more than one path:
+
+- finite, or bounded, replication starts for manual, event-driven, periodic, and start-up synchronisation;
+- long-running rebuild uploads, standard fetches, and fast fetches;
+- continuous replication keeps a channel open until the application lifecycle stops it; and
+- remote chunk fetching can occur independently of replication, for example while reading history.
+
+The existing API request and response counters do not cover every one of these paths. They therefore cannot, by themselves, provide an accurate remote-work indicator.
+
+Long-running finite operations can also be interrupted by platform lifecycle behaviour. A mobile or desktop display may sleep while an operation is in progress. Changing Obsidian to a hidden or minimised state normally invokes the suspension lifecycle, which closes the active replicator. The existing desktop-only `keepReplicationActiveInBackground` setting deliberately provides a broader, opt-in policy for continuous and periodic replication, and should not be made a prerequisite for completing a finite operation.
+
+Screen wake lock and background execution are related platform effects, but they are not equivalent. A screen wake lock prevents display sleep only while the platform and document visibility permit it. It does not guarantee background execution, prevent operating-system suspension, or override an explicit system sleep action.
+
+## Decision
+
+`ReplicatorService` owns a reactive `boundedRemoteActivityCount` and a `runBoundedRemoteActivity` closure boundary.
+
+The boundary has the following contract:
+
+- increment the count immediately before running a finite remote task;
+- run the task through an optional host-provided activity runner;
+- decrement the count in `finally`, including when the task rejects;
+- allow overlapping tasks, so transitions may be `0 → 1 → 2 → 1 → 0`; and
+- count logical operations, not physical connections, sockets, HTTP requests, queued work, or retry delays outside the bounded task.
+
+`ReplicatorService` also owns a narrower `finiteReplicationActivityCount`. Callers enter it through the typed `runFiniteReplicationActivity` method; diagnostic labels do not determine behaviour. The narrower count describes operations which may still place replicated documents in the local database; it excludes rebuilds, chunk-fetch claims, and other bounded work which cannot satisfy an arbitrary missing-chunk read. It is a delivery-lifecycle capability, not a second Wake Lock policy or a connection counter.
+
+The Obsidian host injects the screen wake-lock manager from the `octagonal-wheels` package in the Fancy Kit monorepo as the activity runner on both mobile and desktop. Unsupported or rejected wake-lock requests remain best effort and do not prevent the remote task from running. The manager is disposed when the plug-in unloads.
+
+Finite replication enters both counts only after readiness checks have succeeded and leaves them after `openReplication(..., continuous: false, ...)` settles. A successful completion has reached the latest sequence in that operation's scope and is therefore an authoritative quiescence boundary for chunk retrieval. A failed operation does not prove latest state, but can no longer deliver documents from that attempt. Failure handling runs afterwards so a mismatch or recovery dialogue does not retain the activity. This includes the direct start-up synchronisation path as well as manual, event-driven, and periodic calls through `ReplicationService`. The unbounded continuous channel does not enter either boundary, but its finite initial pull-only catch-up does; the one-shot parameter fallback chain remains inside that boundary.
+
+Delivery into the local database and application to the Obsidian Vault are deliberately separate lifetimes. A mobile device can have only a short opportunity to obtain remote data, while applying a large downloaded batch to the Vault is durable, offline-capable work which can continue or resume later. The replication-result queue and its recovery snapshot therefore remain outside `boundedRemoteActivityCount`. Finite remote activity ends when the transfer operation settles, even when the `📥` queue still contains documents awaiting Vault application.
+
+This separation also keeps the activity indicators truthful: `📲` describes a finite remote operation and must not remain active solely because local Vault writes are pending. The existing replication-result count continues to describe that local queue. If a future feature offers screen-awake protection while applying downloaded documents, it must use a separately typed local-application activity or power-policy boundary, preserve the current behaviour by default, and avoid incrementing either remote-activity count.
+
+Manual P2P commands which bypass `ReplicationService` enter the broad boundary. Direct P2P pull and push entry points are therefore both protected as finite remote work, covering the Obsidian panes, CLI, and Webapp. A pull or bidirectional synchronisation also enters the narrower finite-replication boundary because it can place documents in the local database. A push-only request remains broad-only: it cannot satisfy a local missing-chunk read and must not present itself as a delivery source. Automatic synchronisation on peer discovery, a pull requested by a remote peer, and a watched pull following a peer progress notification enter both boundaries because each can deliver local documents. A normal P2P peer-selection dialogue represents one broad finite session: it remains inside the boundary while waiting for a peer and while the person may perform repeated synchronisations, then settles when the dialogue closes and any in-flight synchronisation has finished. Closing without synchronising returns a failed result and releases the boundary. The 'Start Sync & Close' action completes its synchronisation before closing. This deliberately protects peer discovery and selection, because display sleep can interrupt discovery or connection establishment and require the person to start detection again. It may therefore retain a Wake Lock longer than the network transfer alone. A transfer performed inside that session temporarily adds a nested activity; the count remains a logical-operation count rather than a connection total.
+
+`ChunkFetcher` enters the broad boundary synchronously when it accepts newly missing chunk identifiers, but it does not increment the finite-replication count. A typed per-identifier claim keeps the broad boundary active through queue waiting, interval throttling, `fetchRemoteChunks`, validation, local persistence, and terminal event delivery. Duplicate requests share the existing claim. Explicit absence, failure, cancellation, or a conservative five-minute period without fetcher-observable progress settles the affected claim. The five-minute value is only a last-resort leak fuse: it prevents a never-settling integration from retaining the per-identifier claim and waiter indefinitely and, once the activity runner has entered the claim task, lets the associated Wake Lock, lifecycle deferral, and indicator finish. It is not an arrival estimate, proof of remote absence, or a transport deadline. This scope is defined in detail by the chunk-arrival-quiescence ADR.
+
+Rebuild operations use the same boundary at their destructive or remote phase:
+
+- remote rebuild covers settings application, remote reset, and both upload passes, but releases before the completion dialogue;
+- rebuild everything covers local and remote reset and both upload passes, but releases before the completion dialogue;
+- standard fetch starts after any user confirmation and covers local reset, both download passes, and automatic reflection resumption; and
+- fast fetch starts after remote-type selection and covers reset, resumable download retries, reflection resumption when requested, and checkpoint removal. A non-CouchDB fallback enters only the standard-fetch boundary.
+
+Rebuilder-owned confirmation before destructive work and completion dialogues remain outside the boundary so a person cannot hold a Wake Lock indefinitely merely by leaving a dialogue open. P2P peer discovery and selection during a rebuild deliberately remain inside the boundary. They occur after destructive work has begun, and releasing protection at that point would both leave a partial rebuild unprotected and allow display sleep to interrupt peer detection, forcing the person to repeat it. The protected selection period is therefore part of the rebuild operation rather than an incidental confirmation dialogue.
+
+The deprecated database-clean-up workflow also places its connection, one-shot replication, balancing, and remote resolution inside one `database-cleanup` boundary after the user's choice. Its preliminary count and choice dialogue remain outside.
+
+On every platform, a visibility change to hidden defers the normal suspension lifecycle while the bounded count is non-zero. When the last bounded operation ends, the deferred suspension runs if the document is still hidden and the existing desktop background-replication setting does not apply. This does not bypass mobile operating-system restrictions: a hidden document loses its Screen Wake Lock, and the operating system may still pause or terminate the application. LiveSync merely avoids aborting the operation itself while it may still be able to finish.
+
+Fetch rebuilds temporarily suspend file watching. Their visibility event still records the observed hidden state and a pending lifecycle suspension while bounded activity is in progress, without committing or processing file events. A hidden application is suspended after the rebuild boundary ends and can therefore resume normally when it becomes visible. If it becomes visible before the boundary ends, the pending suspension is cancelled and no unmatched resume lifecycle is emitted.
+
+If the desktop background setting applies, its existing continuous or periodic policy remains authoritative. When a Desktop LiveSync window becomes visible during bounded activity, the normal continuous-channel teardown and resume sequence is also deferred until that activity ends, so recovery does not abort the finite operation.
+
+The status bar separates the two meanings. `📲` is shown while the bounded remote activity count is non-zero. It therefore reports a finite logical operation, including periods such as P2P peer selection or chunk-fetch queueing when no request is currently crossing the network. An adjacent `🌐N` reports the approximate number of tracked physical-request units currently in progress. The icon values and the physical indicator's 150 ms minimum display time are named constants so their presentation can be revised without changing the activity contract.
+
+Each physical HTTP attempt owns one balanced counter pair. The request counter is incremented immediately before invoking the selected fetch implementation, and the response counter is incremented in `finally`, whether the attempt returns or rejects. A web-fetch failure followed by the native fallback is two physical attempts and therefore contributes two balanced pairs. Callers must not add another pair around `performFetch`, because duplicated or missing increments leave the status indicator permanently active.
+
+Object Storage contributes one approximate unit for each AWS SDK command issued by its adapter, including upload, download, listing, deletion, availability, and usage requests. A download remains active until its response body has been consumed. This boundary is above the request-handler choice, so it covers both the standard SDK handler and Obsidian's internal request API without double counting. SDK-internal retries remain within one reported command. The displayed value is therefore intentionally approximate and is not an exact count of sockets, HTTP exchanges, or bytes transferred.
+
+P2P does not yet contribute to the physical-request count because it does not have a request unit comparable with CouchDB HTTP attempts or Object Storage SDK commands. Its finite operations remain visible through `📲`. A future P2P transfer metric should be added only when it has a stable meaning, rather than being inferred from the broad logical-operation count.
+
+## Ownership
+
+`ReplicatorService` is the shared ownership point because both `ReplicationService` and `ChunkFetcher` already depend on it. It owns the broad activity count and classifies the semantic subset which represents finite replication. Placing either activity state in `ReplicationService` would make chunk fetching depend in the opposite direction and risk a service dependency cycle. Adding another Service Hub service would introduce a wider capability surface without a distinct lifecycle owner.
+
+The platform activity runner remains injected. Common library and headless consumers can omit it while retaining the same bounded activity count and operation semantics.
+
+## Non-Goals
+
+- Do not count continuous replication as a bounded activity.
+- Do not reinterpret the count as an exact number of network connections or HTTP requests.
+- Do not use either diagnostic count for replication completion, throttling, protocol correctness, or power-policy decisions.
+- Do not claim or implement privileged mobile background execution.
+- Do not guarantee protection against operating-system suspension, closing a laptop lid, forced termination, network loss, or a user-initiated sleep action.
+- Do not add a lifecycle timeout which would abort an unusually slow rebuild. A genuinely stalled operation may postpone LiveSync's visibility suspension until it settles, but the platform may still suspend or terminate background work.
+- Do not broaden `keepReplicationActiveInBackground`; it remains an opt-in desktop policy for continuous and periodic operation after finite work has ended.
+- Do not include offline scans, unrelated local storage reflection, or the durable replication-result queue in this boundary. They are offline-capable and require a separate decision if activity reporting or power policy is added later.
+
+## Verification
+
+Before changing the transfer/application separation, add a deterministic regression scenario which leaves downloaded documents queued after finite transfer settles, verifies that remote activity has ended, persists the queued state, and resumes Vault application after suspension or restart. An optional local-application Wake Lock feature requires its own enabled and disabled cases; existing remote-operation E2E is not evidence for that separate policy.
+
+Unit tests cover:
+
+- overlapping bounded activities and their reactive count transitions;
+- count cleanup after rejection;
+- entry into the boundary only after replication readiness succeeds;
+- replication failure handling occurring after the finite activity ends;
+- start-up one-shot replication and continuous start-up's finite pull-only catch-up entering the boundary, while the unbounded live channel does not;
+- start-up readiness failure avoiding the boundary;
+- direct P2P commands entering the boundary;
+- direct P2P pull and push entry points entering the broad boundary, while only pull and bidirectional operations enter the finite-delivery boundary;
+- automatic synchronisation on peer discovery, remote pull requests, and watched peer progress entering the boundary;
+- P2P peer-selection sessions settling on close, including cancellation, repeated synchronisation, and a close during in-flight work;
+- remote chunk fetching remaining inside the shared boundary from synchronous queue acceptance through local persistence and terminal notification;
+- missing-chunk waiters rechecking local storage when observed per-identifier claims and finite replication have settled;
+- the finite-replication count excluding other bounded work;
+- standard, fast, remote, and combined rebuild activity boundaries;
+- Rebuilder-owned confirmation and completion dialogues remaining outside rebuild activity;
+- fallback from fast fetch avoiding a nested activity boundary;
+- fast-fetch reflection resumption and checkpoint removal remaining inside the activity;
+- visibility suspension being deferred while bounded activity is in progress on desktop and mobile;
+- rebuild-time file-watching suspension preserving the deferred lifecycle action;
+- deferred suspension after the final activity ends while the document remains hidden;
+- hidden-to-visible transitions before the final activity avoiding an unmatched resume; and
+- continuous-channel recovery being deferred when a desktop window becomes visible during bounded activity.
+
+Additional tests cover balanced physical-request counters after success and rejection, each Object Storage command boundary, response-body consumption for downloads, the split `📲` and `🌐N` status labels, and a deterministic real-Obsidian CouchDB request held while the physical indicator is observed. The Object Storage integration and real-Obsidian MinIO workflows verify that actual AWS SDK operations advance and rebalance the shared counters.
+
+The exact Fancy Kit screen wake-lock behaviour is covered by its package and Harness tests. A real Obsidian smoke test remains appropriate when changing the platform adapter or lifecycle integration, but is not required for changes confined to the already-tested injected activity-runner contract.
+
+## Consequences
+
+- One finite activity definition drives Wake Lock, lifecycle protection, and status UI without coupling common library code to Obsidian or browser globals.
+- Callers can observe accurate logical activity even in CLI and Webapp hosts which do not inject a Wake Lock implementation.
+- Rebuild operations now retain Wake Lock and lifecycle protection across their longest interruption-sensitive phases without retaining them for Rebuilder-owned pre-operation or completion dialogues. Post-reset P2P discovery and selection remain protected as an intentional part of completing the rebuild.
+- Downloaded documents may remain in the durable Vault-application queue after remote activity has ended, allowing transfer and offline application to follow different mobile lifetimes without presenting local writes as communication.
+- Users can now distinguish the lifetime of a finite remote operation from approximate request activity within it.

docs/adr/2026_07_chunk_arrival_quiescence.md

@@ -0,0 +1,144 @@
+# Architectural Decision Record: Chunk Arrival Quiescence
+
+## Status
+
+Accepted
+
+## Context
+
+A file metadata document refers to one or more content-addressed chunk documents. LiveSync normally writes the chunks before writing the metadata, but those writes are separate database operations and are not replicated as one atomic unit. A local reader can consequently observe metadata before every referenced chunk is locally readable. This is expected when CouchDB on-demand chunk fetching is enabled, and can also occur around conflict resolution, replication event processing, and historical data.
+
+Before this decision, a missing-chunk waiter used a fixed 5-second or 30-second timeout. Its budget included queueing, throttling, network transfer, validation, local persistence, and event delivery. A healthy operation could therefore time out immediately before it delivered the requested chunk. Conversely, when no operation was capable of delivering the chunk, the timer merely delayed the same unavailable result.
+
+Finite replication provides a stronger boundary than elapsed wall-clock time. In the absence of an error, a finite replication does not complete until it has reached the latest sequence in its scope. Once it completes, that replication cannot deliver another chunk. An on-demand fetch is a separate finite delivery path and needs its own per-identifier boundary.
+
+## Decision
+
+Wait only for a delivery lifecycle which is observable when the local miss is handled. Do not guess how long an unobserved producer might take.
+
+Two lifecycle signals are relevant:
+
+- `finiteReplicationActivityCount` records finite replication operations which can still place database documents in the local database; and
+- a `ChunkDeliveryCoordinator` claim records the complete lifetime of an accepted on-demand request for each missing chunk identifier.
+
+The finite replication count is distinct from the broader `boundedRemoteActivityCount`. Rebuilds and other bounded remote work may need Wake Lock and lifecycle protection without being able to satisfy an arbitrary missing-chunk read. A P2P push-only operation is broad for the same reason: it sends documents away but cannot place one in the local database. P2P pull and bidirectional operations are finite-delivery sources. `ReplicatorService` updates the narrower count only through the typed `runFiniteReplicationActivity` boundary; the diagnostic activity label is not used as a behavioural discriminator.
+
+The waiting layer follows these rules:
+
+1. Register the waiter before requesting on-demand delivery.
+2. Dispatch `missingChunks` synchronously when direct fetch is permitted. `ChunkFetcher` must claim accepted identifiers before dispatch returns, closing the scheduling gap without a timer.
+3. If a matching claim or finite replication is active, wait for that observable producer.
+4. A valid chunk arrival resolves the waiter immediately.
+5. An explicit remote-missing result resolves it as missing immediately.
+6. Once every observed producer completes, read the requested identifier from the local database once more, bypassing the cache.
+7. Return the rechecked chunk, or return unavailable. Do not add a fixed grace period after the producer has stopped.
+8. If no producer is observable after synchronous dispatch, return unavailable immediately. There is no operation for a duration to represent.
+
+If new relevant activity starts while the final database recheck is pending, that result is stale. The waiter remains active until the newer producer completes and a current recheck finishes.
+
+A successful finite replication completion is the authoritative ‘latest’ boundary. A failed operation does not prove that the remote lacks the chunk, but it is still terminal for that attempt: it can no longer deliver data. The same local recheck preserves any documents received before the failure, after which normal replication error and retry handling remains responsible for recovery. Missing-chunk code must not misreport that case as an explicit remote absence.
+
+### On-demand fetch boundary
+
+`ChunkFetcher` claims newly requested identifiers synchronously while handling the `missingChunks` event. The claim remains active through:
+
+- queueing and concurrency scheduling;
+- configured interval throttling;
+- entry into the injected bounded-activity runner;
+- `fetchRemoteChunks`;
+- response validation;
+- local database persistence; and
+- fetched or missing event delivery.
+
+The claim settles on every terminal path, including explicit absence, no active replicator, rejection, invalid results, destruction, and cancellation. Its completion Promise is the task passed to the bounded `chunk-fetch` activity, keeping Wake Lock, application lifecycle deferral, the remote-work indicator, and missing-chunk delivery aligned.
+
+### Five-minute leak fuse
+
+An accepted on-demand claim has a separate five-minute inactivity fuse. This is a last-resort leak safety valve, not a chunk-arrival budget or a remote-request timeout.
+
+Its purpose is to prevent a faulty integration, a never-settling Promise, or a stalled transport from retaining logical ownership indefinitely. When it fires, the coordinator releases the per-identifier claim and its waiter. If the bounded activity callback has been entered, resolving the claim also allows the associated Wake Lock, application-lifecycle deferral, and remote-work indicator to be released. `ChunkFetcher` refreshes the fuse only at observable progress points, such as entering the activity boundary, beginning and completing throttling or transfer, and completing persistence.
+
+Five minutes is deliberately a conservative operational limit, not a value derived from a network protocol, a benchmark, or evidence that a missing chunk will arrive within that period. Firing the fuse neither proves remote absence nor makes the underlying request safe to abort. The current `fetchRemoteChunks` contract has no `AbortSignal`, so a physical request may still complete after its logical claim has been released. A future cancellable transport contract should add transport-specific deadlines and explicit cancellation without changing the lifecycle-based wait rule.
+
+### Continuous replication
+
+The unbounded live channel is not a quiescence gate because it has no natural end. Its initial pull-only catch-up is finite, however, and must enter `runFiniteReplicationActivity`. This includes the one-shot parameter fallback chain: every retry remains within the catch-up boundary until it succeeds or stops. If continuous replication later restarts with adjusted parameters, the new initial catch-up enters a new finite boundary.
+
+Once the live channel has begun, a chunk delivered through it still resolves an existing waiter immediately, but the channel itself does not keep a new waiter open. CouchDB on-demand fetching supplies its own per-identifier claim. If a future defect demonstrates a delivery race inside a live batch, that batch lifecycle should be exposed explicitly rather than approximated with another elapsed delay.
+
+## Ownership
+
+`ReplicatorService` owns both the broad bounded-operation count and the narrower finite-replication count. It is the common lifecycle owner for CouchDB, sequential, and P2P replicators.
+
+`LayeredChunkManager` owns one `ChunkDeliveryCoordinator` and supplies it to its arrival layer and `ChunkFetcher`. `ArrivalWaitLayer` owns waiter resolution and the final local database recheck. It depends on the narrow coordinator capability rather than on `ReplicatorService` itself.
+
+`ChunkFetcher` owns per-identifier claims because it knows when each identifier enters its queue and reaches a terminal result.
+
+## Compatibility
+
+- Preserve immediate reads when `waitForDelivery` is false or the deprecated call-site `timeout` is zero or negative.
+- Treat a positive deprecated `timeout` only as source-compatible opt-in to lifecycle waiting. Its numeric value no longer represents an arrival duration.
+- Preserve `preventRemoteRequest`: no on-demand request is dispatched, although an already-active finite replication may satisfy the waiter.
+- Preserve Promise sharing for concurrent reads of the same chunk identifier.
+- Preserve immediate explicit remote-missing results.
+- Do not change which remote types support direct on-demand fetching.
+
+## Historical Evidence and Scope
+
+This decision addresses the lifecycle-race class rather than treating every ‘Load failed’ report as a timeout:
+
+- [Issue #166](https://github.com/vrtmrz/obsidian-livesync/issues/166) contained logs where chunk collection failed shortly before related chunk writes appeared. It is evidence for the timing class, although that issue's hidden-file start-up path was repaired separately and is not claimed as a direct regression test here.
+- The 2021 timing fixes in [commit `39e2eab0`](https://github.com/vrtmrz/obsidian-livesync/commit/39e2eab0238d9c37e3653cdec884cbeed543fc23) and the extended leaf timeout in [commit `9facb577`](https://github.com/vrtmrz/obsidian-livesync/commit/9facb577601d8aceff7df547cd2a6f9357fdaa29) show that elapsed timeout values have historically been used to absorb the same ordering uncertainty. They do not provide a protocol basis for retaining 5-second or 30-second delays.
+- Replication pacing introduced by [commit `8d66c372`](https://github.com/vrtmrz/obsidian-livesync/commit/8d66c372e15c43a2de84a223c6385077b7724eec) and commonlib [commit `051b50c`](https://github.com/vrtmrz/livesync-commonlib/commit/051b50ca38ec4c05a11e8216ac259b4488b825f0) is a direct precedent for preventing replication progress from outrunning chunk collection. The present design expresses that dependency as an explicit lifecycle and completion recheck.
+- [Issue #505](https://github.com/vrtmrz/obsidian-livesync/issues/505) was traced to chunks which were genuinely absent after the former bulk-send option broke the chunks-before-metadata guarantee. Waiting cannot recreate missing data, so this decision does not claim to fix it.
+- [Issue #771](https://github.com/vrtmrz/obsidian-livesync/issues/771) and [Issue #986](https://github.com/vrtmrz/obsidian-livesync/issues/986) contain ambiguous or version-dependent `Load failed` reports. They remain unclaimed until the original writer and database state can be reproduced.
+
+The detailed setting and replicator matrix is recorded in [Chunk Retrieval and Waiting](../design_docs/chunk_retrieval_and_waiting.md).
+
+## Alternatives Rejected
+
+### Increase the fixed timeout constants
+
+Any fixed total duration can still expire immediately before a queued or progressing operation reports its result. Larger values also make genuine failures slower without defining what the system is waiting for.
+
+### Start another grace period after finite completion
+
+A successful finite replication has already reached its latest sequence, and the completion recheck observes documents persisted without a waiter event. Waiting an additional 5 or 30 seconds has no identified producer to wait for and merely retains the historical approximation.
+
+### Observe all bounded remote activity
+
+The broad count includes operations which cannot provide the requested chunk. Using it as the delivery gate lets unrelated work delay a read and makes its completion semantically meaningless. A separate finite-replication count avoids that leak.
+
+### Keep a fallback timer for unobserved delivery
+
+An unobserved producer has no defined start, progress, or completion semantics. A timer would therefore be a guess rather than a safety property. Relevant delivery paths must claim their work synchronously or expose a finite replication boundary; otherwise the read returns unavailable.
+
+### Remove every timer
+
+The arrival wait has no elapsed timer, but an implementation fault can leave a delivery claim unresolved forever. The five-minute inactivity fuse bounds that leaked logical state without being used as a successful delivery condition.
+
+## Verification
+
+Unit tests use deterministic clocks and deferred Promises to cover:
+
+- a finite replication which lasts well beyond the former arrival values;
+- successful finite completion causing a cache-bypassing local database recheck;
+- immediate unavailability when no producer is observable;
+- per-identifier claims covering queueing, throttling, remote fetch, validation, persistence, and event delivery;
+- explicit missing, no-replicator, rejection, invalid response, cancellation, runner rejection, and teardown paths;
+- overlapping claims and finite replications;
+- a runner which never enters the task and a request which never settles;
+- the five-minute fuse being refreshed by observable progress;
+- continuous replication's finite initial catch-up, including its parameter fallback path; and
+- the setting and replicator decision matrix.
+
+Integration-style unit tests exercise `LayeredChunkManager`, `ChunkFetcher`, a memory-backed PouchDB database, and a deferred fake replicator together. A real Obsidian test is not required because the change remains behind the existing database, service, and event boundaries and does not alter platform UI or an adapter contract.
+
+## Consequences
+
+- A healthy finite replication or on-demand request no longer loses a race against an unrelated wall-clock estimate.
+- Successful finite replication completion provides a precise latest boundary for missing-chunk reads.
+- The local recheck closes event-delivery and cache timing gaps without extending the wait after completion.
+- Reads no longer pause for 5 or 30 seconds when no observable operation can deliver the chunk.
+- Relevant producers must expose a lifecycle and must continue to prove cleanup on every exceptional path.
+- The five-minute fuse bounds leaked logical activity, but it neither establishes remote absence nor cancels a physical request.

docs/adr/2026_07_common_library_package_boundary.md

@@ -0,0 +1,345 @@
+# Architectural Decision Record: Package the Common Library Behind Explicit Host Boundaries
+
+## Status
+
+Accepted — the package boundary is implemented, published pre-release artefacts have been verified as exact downstream dependencies, and the Community directory scanner preview confirms the intended source boundary. Each later release candidate still requires immutable artefact and downstream validation.
+
+## Context
+
+Self-hosted LiveSync currently consumes `livesync-commonlib` as the `src/lib` Git submodule. TypeScript, Vite, Vitest, the CLI, Webapp, and WebPeer resolve `@lib/*` directly to the submodule's TypeScript source. The common-library repository has no package manifest, standalone build, export map, or self-contained test command. Its tests and dependency versions are consequently supplied by the Self-hosted LiveSync repository.
+
+Source archives do not populate a Git submodule. Self-hosted LiveSync therefore also commits generated declarations under `_types` and resolves `@lib/*` to those declarations as a fallback. This makes one logical dependency appear in the plug-in repository twice: once as a submodule checkout and once as generated declarations. Release preparation must regenerate and commit the fallback, and repository scanners can report generated lint directives as if they were maintained plug-in source.
+
+The Obsidian community scanner currently inspects repository source beyond the plug-in entry point. Reports include `src/apps/cli`, `src/apps/webapp`, `src/apps/webpeer`, and generated `_types`. Moving the common library from `src/lib` to another source directory or a workspace package inside the Self-hosted LiveSync repository would therefore preserve the scan surface. It could remove the submodule fallback, but it would not create the same dependency boundary as consuming a published npm package.
+
+The common library is already a substantial shared domain layer. At the time of this decision it contains 270 non-test TypeScript or Svelte source files. At Self-hosted LiveSync revision `e114f66fb2b7c6f3fec2d53701f6638d2557e606`, source outside `src/lib` uses 180 distinct raw `@lib/*` specifiers across plug-in, application, and test source. Normalising optional TypeScript source suffixes leaves 140 migration paths. The plug-in contributes most of those imports, but the CLI, Webapp, and WebPeer also depend on the library. Treating every existing deep path as a permanent public API would make future refactoring impractical.
+
+The intended external use is not new:
+
+- [commonlib issue #1](https://github.com/vrtmrz/livesync-commonlib/issues/1) has requested an npm package and an established API since 2022;
+- [Self-hosted LiveSync issue #87](https://github.com/vrtmrz/obsidian-livesync/issues/87) asks for a client with list, get, submit, and delete operations;
+- [commonlib issue #10](https://github.com/vrtmrz/livesync-commonlib/issues/10) asks for an API which lets another application add Markdown files to the CouchDB data model; and
+- [commonlib issue #13](https://github.com/vrtmrz/livesync-commonlib/issues/13) records the integration cost of consuming a Git submodule and compiling its source.
+
+Existing external consumers use custom TypeScript aliases, loaders, and host stubs to reach `DirectFileManipulator` and other deep modules. The present source shape therefore imposes real integration work without supplying a stable contract.
+
+The library is close to being self-contained, but it crosses its boundary in a small number of important places:
+
+- four files depend on Self-hosted LiveSync's event hub or event identifiers;
+- `KeyValueDBService` imports the host's concrete database-opening function;
+- `ObsidianServiceContext` imports the plug-in class and Obsidian types from the parent repository; and
+- `coreEnvFunctions` imports an Obsidian function type even though the module is intended to be host-neutral.
+
+The library also mixes domain logic with host presentation:
+
+- Svelte dialogue mounting depends on Svelte, LiveSync service context, application-lifecycle events, translation, and cancellation policy in one implementation;
+- Obsidian context and setup helpers remain below the common-library directory;
+- browser dialogue shims and LiveSync Svelte components are shipped alongside headless replication code; and
+- the translation implementation statically imports the complete generated catalogue. The generated message modules and JSON catalogues account for approximately 1.5 MB of source and generated data, even when a headless consumer does not require them.
+
+The root `src/index.ts` currently exports only `DirectFileManipulator` and its options. `DirectFileManipulator` is useful evidence for a future SDK, but it is not yet a sufficient stable façade: initialisation starts from its constructor, enumeration remains unfinished, watch ownership and failure semantics are not documented, and conflict and concurrency semantics are not defined as a public guarantee.
+
+The present process model also assumes one main LiveSync instance. Event dispatch, translation state, environment configuration, offline-scan state, worker pools, synchronisation-parameter handlers, diagnostic counters, and some compatibility caches are module-scoped. Some of these are safe process-wide facilities, while others can allow two client instances to influence each other. Publishing a package makes concurrent clients in one process a supported possibility, so this state must be classified rather than carried across accidentally.
+
+## Decision
+
+Maintain `livesync-commonlib` as the authoritative independent repository and publish its compiled output as the scoped, pre-1.0 npm package `@vrtmrz/livesync-commonlib`.
+
+Self-hosted LiveSync, its CLI, Webapp, WebPeer, and external tools will consume the compiled package and declarations through package export maps. They must not compile the common library's source through a path alias. The package lock records the exact resolved artefact used to build a plug-in release.
+
+The common-library repository may become a small workspace if independently useful artefacts emerge, but it does not move into the Fancy Kit repository or the Self-hosted LiveSync plug-in repository. This preserves its domain ownership, existing history, issues, and independent release cadence while making the plug-in repository a package consumer.
+
+The first package release is an infrastructure and compatibility release, not a declaration that every internal service is stable. It exposes:
+
+- a small documented root API;
+- named, task-oriented public subpaths;
+- explicitly marked compatibility subpaths required to migrate current Self-hosted LiveSync imports; and
+- no unrestricted source-directory wildcard as a permanent contract.
+
+Compatibility subpaths may be exported during the migration, but they remain pre-1.0 and are documented as internal. New external integrations should use the high-level client façade rather than reproduce Self-hosted LiveSync's internal Service Hub composition.
+
+### Domain ownership
+
+The common library continues to own behaviour which defines the Self-hosted LiveSync data and synchronisation model:
+
+- document, metadata, chunk, setting, and protocol types;
+- path and identifier encoding;
+- chunk splitting, hashing, compression, encryption, and content reconstruction;
+- PouchDB-facing data access and replication primitives;
+- CouchDB, Object Storage, and P2P replication domain logic;
+- conflict, chunk-delivery, storage-event, and replication managers;
+- platform-neutral storage and service contracts;
+- headless composition; and
+- the future high-level client façade.
+
+The Self-hosted LiveSync repository owns plug-in and product integration:
+
+- `ObsidianServiceContext` and every reference to the plug-in class, `App`, `Plugin`, or Obsidian lifecycle;
+- Setup Wizard components and LiveSync-specific presentation policy;
+- Obsidian menus, notices, settings panes, and dialogue composition;
+- plug-in event wiring which is not part of the replication protocol; and
+- the concrete initialisation of injected environment, translation, storage, key-value database, and UI capabilities.
+
+Browser-only implementations may remain in the common-library repository only when they implement a documented host-neutral contract used by more than one browser consumer. LiveSync-specific Webapp and WebPeer composition remains application code even if it later moves out of the plug-in repository.
+
+Neutral utilities which do not express LiveSync data, storage, replication, or UI policy may move to `octagonal-wheels` after more than one consumer proves the abstraction. Reusable Obsidian adapters may move to `@vrtmrz/obsidian-plugin-kit`. Neither package becomes an owner of LiveSync domain behaviour.
+
+### Dependency inversion
+
+The package must contain no `@/` import and no direct Obsidian import. The current reverse dependencies are removed as follows:
+
+- common protocol and service events live with their common-library contracts;
+- host-only event reactions are registered by Self-hosted LiveSync at its composition root;
+- `KeyValueDBService` receives an `openKeyValueDatabase` factory through constructor or service dependencies;
+- `ObsidianServiceContext` moves to Self-hosted LiveSync;
+- the language getter uses a local function type rather than importing the Obsidian declaration; and
+- browser globals, fetch, crypto, timers, storage, and document access are obtained through explicit host capabilities where behaviour varies by runtime.
+
+Temporary package-level configuration is acceptable where converting every call site in one change would be unsafe, but configuration must be instance-scoped wherever multiple clients can coexist. Importing the package must not patch `HTMLElement`, `SVGElement`, or another global prototype. Webapp compatibility patches belong in Webapp bootstrap code.
+
+Every mutable module-level value is classified as one of:
+
+- immutable or safely shared process infrastructure;
+- an explicitly keyed cache with bounded ownership and disposal; or
+- client state which moves behind an instance-owned service or dependency.
+
+In particular, event subscriptions, translation selection, offline-scan maps and timers, synchronisation-parameter handlers, and database transformation policy must not leak between independent client instances. A high-level client owns an explicit asynchronous disposal path which removes subscriptions, cancels work it owns, and releases its instance state.
+
+### Translation resources
+
+Translation lookup is separated from the application catalogue. Commonlib owns a typed canonical English definition for the messages requested by its services and uses it when a host omits the optional translator capability. This ensures that another consumer receives meaningful English rather than symbolic keys.
+
+Self-hosted LiveSync owns the complete multilingual catalogue, generation tools, selected-language state, and translator implementation. It injects that translator into the Obsidian, CLI, and browser composition roots. Commonlib does not publish `compat/common/i18n`, `compat/common/rosetta`, generated language modules, or JSON catalogues.
+
+The canonical Commonlib key type and English fallback change with Commonlib. LiveSync may add translations for those keys without duplicating every English definition; its translator delegates absent keys to Commonlib's canonical English fallback. A separate language package remains possible only if independent consumers and release cadence later justify it; core must never depend on an application catalogue.
+
+### Svelte dialogue hosting
+
+The present Svelte dialogue implementation is split into three responsibilities:
+
+1. an Obsidian `Modal` host which owns content, title, close, one-shot settlement, and disposal;
+2. a Svelte adapter which mounts and unmounts a component in that host; and
+3. Self-hosted LiveSync policy which supplies service context, reacts to plug-in unload, requires explicit cancellation in selected workflows, translates messages, and styles Setup Wizard content.
+
+Fancy Kit is an appropriate owner for the first responsibility when the contract is useful beyond this migration. The Kit API should be framework-neutral: it accepts a mount callback, exposes typed `resolve`, `cancel`, `close`, and `setTitle` controls, and accepts a disposer returned by the callback. It returns a `Promise<TResult | null>` which settles once, and it owns safe-area, viewport, focus, and Obsidian Modal lifecycle guarantees.
+
+Fancy Kit does not add Svelte to its core dependencies for this migration. Self-hosted LiveSync initially owns the small Svelte adapter which calls Svelte's `mount` and `unmount` through the framework-neutral host. The browser dialogue host also remains outside the Obsidian plug-in kit. If a second Obsidian plug-in needs the same Svelte adapter, it can be promoted to an optional Kit subpath with an optional Svelte peer dependency, or to a separate `@vrtmrz/obsidian-svelte-kit` package. That promotion must preserve the existing `sideEffects: false` and focused-import guarantees for consumers which do not use Svelte.
+
+Self-hosted LiveSync's `openWithExplicitCancel` retry policy, application service context, and Setup Wizard components do not move to Fancy Kit.
+
+Arbitrary component mounting is not added to the neutral `UiInteractions` contract. A component instance is a framework and host integration detail rather than a portable interaction request which a generic driver can serialise or answer. A LiveSync workflow which needs a hosted component defines and receives its own narrow, typed dialogue capability; Self-hosted LiveSync composes that capability from the Kit Modal host and its local Svelte adapter.
+
+### Package artefacts
+
+The common-library package publishes compiled ESM and generated declaration files. Consumers do not receive raw TypeScript as the runtime entry point. The package must provide:
+
+- an explicit `exports` map;
+- declaration maps where they remain useful for debugging;
+- browser and Node entry points where implementations differ;
+- accurate `sideEffects` metadata;
+- explicit runtime, peer, and optional dependencies;
+- no unresolved `@lib/*`, `@/*`, Vite query, or source `.ts` import in published JavaScript or declarations;
+- an `npm pack` contents check; and
+- clean-install consumer fixtures for Node, a browser bundle, and Self-hosted LiveSync.
+
+Svelte source, worker query imports, AWS SDK adapters, PouchDB adapters, and Node-only crypto must not leak through the root entry point. Optional feature subpaths may carry their own heavier dependency surface.
+
+### Platform host entries
+
+Platform-specific host access is explicit rather than inferred. `@vrtmrz/livesync-commonlib/node` supplies Node-only capabilities and `createNodeStorage({ rootPath })`. `@vrtmrz/livesync-commonlib/browser` supplies `createFileSystemAccessStorage({ rootHandle })` for the browser File System Access API. Browser bundles cannot resolve the Node implementation through the browser entry.
+
+Both storage factories receive an existing root from their host. Commonlib does not choose a process directory, present a browser directory picker, request browser permission, or persist a `FileSystemDirectoryHandle`. The CLI owns path selection and configuration. The Webapp owns user activation, permission, handle persistence, and re-authorisation. The adapters own only path containment and storage operations below the injected root.
+
+Here, the browser capability means the browser File System Access API, not Node's `fs` API. The package proof deliberately moves the rooted `IStorageAdapter` implementation first. The Webapp retains its LiveSync-specific `IFileSystemAdapter` composition, file-object cache, Vault semantics, picker flow, and storage-event policy. Those responsibilities can move later only with their own documented contracts; they are not implied by the low-level browser entry point.
+
+A later composition may place the constructed storage contract on a host-specific `ServiceContext` subtype, so services depend only on the injected capability while each platform owns context initialisation. This proof does not add storage or raw platform objects to the base `ServiceContext`: doing so would make an optional application capability mandatory for Obsidian, CLI, Webapp, WebPeer, and test contexts at the same time. A future change should inject the narrow `IStorageAdapter` contract rather than expose `FileSystemDirectoryHandle`, Node `fs`, or environment detection through the shared context.
+
+The paired adapters run against the same contract suite for metadata, text and binary access, append, listing, removal, missing paths, parent creation, empty-root handling, and traversal rejection. Timestamp fidelity remains platform-specific because the File System Access API does not provide the same creation-time and timestamp-setting facilities as Node.
+
+The Node adapter rejects symbolic-link components which it observes in adapter paths before an operation and opens file entries without following the final link where the platform supports that flag. The CLI delegates its Vault reads, writes, discovery, deletion, and atomic rename to this rooted adapter rather than maintaining a second direct `fs` path. This rejects traversal paths and symbolic links which already exist when a remote-derived operation begins, while retaining case-only and cross-directory rename behaviour.
+
+This adapter is not an operating-system filesystem sandbox. The CLI assumes that the host-selected Vault root and its local filesystem are trusted and are not concurrently rewritten by an untrusted local process. A privileged CLI must therefore not use a Vault root which is writable by a less-trusted local actor.
+
+The Node entry also centralises direct Node built-in access needed by trusted headless application code. This is a package and scanner boundary, not an assertion that Node and browser APIs are interchangeable. Cross-platform behaviour belongs in a shared contract with separate implementations, as demonstrated by rooted storage.
+
+### Standard input and output
+
+Commonlib's `context` entry exposes a narrow `StandardIo` contract for command-line composition. It reads UTF-8 standard input, asks one line-oriented question, and writes text or binary chunks to standard output and standard error without adding delimiters. Commonlib's `node` entry supplies `createNodeStandardIo()`, which binds that contract to host-selected Node streams and defaults to the current process streams.
+
+Self-hosted LiveSync constructs the Node implementation at the CLI composition root and places the exact instance on `NodeServiceContext`. `NodeServiceHub` must receive that Context rather than silently constructing one. Command handlers reach input, prompts, and protocol output through the Context, so unit tests can inject memory I/O without replacing process globals. Obsidian and browser Contexts do not acquire a fictitious terminal capability, and the base `ServiceContextContract` remains limited to capabilities required by every composition.
+
+Standard I/O does not own command-line arguments, exit codes, signals, stream lifecycle, log levels, or log persistence. Diagnostic logging remains the responsibility of the existing API and Logger composition. CLI adapters receive a narrow diagnostic callback wired to the service logging API instead of calling `console` directly. A CLI host may render selected logs on standard error, but Logger is not added to `StandardIo` or made mandatory on the base Context.
+
+Commonlib verifies memory injection, split UTF-8 decoding, object-mode rejection, text and binary output, and prompting against injected Node streams. The downstream CLI verifies Context identity and exact injected I/O in unit tests, then runs the built Node artefact through its Deno command E2E.
+
+### Context and result compatibility
+
+`ServiceContextContract` is the minimum host-neutral composition contract. It supplies an event channel and message translator selected by the host. Obsidian and CLI contexts extend the default implementation with their own capabilities; the Webapp currently uses the default implementation. Every Service Hub and every service in one composition must retain the exact Context object supplied by that host.
+
+Compatibility is established through observable results, not only structural TypeScript compatibility. A shared probe verifies event delivery, translation results, and Context identity across the public Service Hub surface. Commonlib separately verifies that default contexts isolate their event channels and translators. Real Obsidian runs the same invariants against the loaded plug-in through `obsidian-cli eval`; the CLI runs its composition contract in unit tests and then exercises the built Node artefact through Deno E2E; and the Webapp composition runs the shared contract directly without depending on its currently stale Playwright workflow.
+
+The same rule applies as more APIs move: define the shared result set first, run the same cases against each implementation, and document platform-specific behaviour outside that result set. Matching method names or return types alone does not establish behavioural compatibility. The contract runner remains test support during this proof rather than becoming a new public package API.
+
+### Barrels and export surfaces
+
+The migration does not prohibit every barrel. A small root entry point or task-oriented subpath entry point is an intentional package contract when it has one documented responsibility, uses explicit named exports, and does not load unrelated implementations or optional dependencies. The root client entry point, a focused RPC entry point, and type-only storage-adapter entry points are examples which may remain after review.
+
+An existing barrel or forwarding façade is removed when the migration provides a clearer import and the barrel:
+
+- aggregates unrelated domains or exposes implementation layout as API;
+- hides a platform, UI framework, worker, database adapter, or another optional dependency;
+- makes side effects or tree-shaking behaviour difficult to determine;
+- merely re-exports another package without adding a LiveSync-owned contract; or
+- exists only to preserve the present `@lib/*` source alias or Service Hub composition.
+
+In particular, the broad `common/types` barrel is retained only as a temporary compatibility path while focused settings, model, protocol, and path contracts are extracted. The `InjectableServices` forwarding barrel is removed in favour of explicit compatibility imports. Forwarding exports for `octagonal-wheels` facilities are removed where consumers can import the owning package directly; mixed modules such as conversion and utility modules are split when this prevents neutral dependencies from being presented as LiveSync-owned API.
+
+Every retained barrel must correspond to an explicit `exports` entry, list named exports rather than use an unrestricted wildcard, and have a packed-consumer or bundle test proving that unrelated optional code is not loaded. Removing a barrel is not sufficient reason to expose every underlying file as a public subpath.
+
+## Migration Plan
+
+### Phase 0: Record and enforce the boundary
+
+- Add a package-boundary check which rejects `@/` and direct Obsidian imports in common-library production source.
+- Record the current Self-hosted LiveSync `@lib/*` import inventory and classify each path as public, compatibility-only, host-owned, or obsolete.
+- Inventory mutable module-level state and add a two-client isolation test before promising a public client API.
+- Add standalone test and type-check configuration to the common-library repository while retaining downstream Self-hosted LiveSync CI.
+- Add a packed-consumer fixture before changing Self-hosted LiveSync resolution.
+
+### Phase 1: Remove host leaks
+
+- Move `ObsidianServiceContext` and `setupObsidian` presentation code to Self-hosted LiveSync.
+- Inject the key-value database factory and host event reactions.
+- Replace the Obsidian language type import with a local contract.
+- Move global DOM compatibility mutation to the browser application bootstrap.
+- Introduce translator injection and detach core imports from the full catalogue.
+- Split the generic dialogue host, Svelte adapter, and LiveSync policy without changing visible behaviour.
+
+### Phase 2: Build the package
+
+- Add the package manifest, compiled ESM build, declarations, export map, and package documentation.
+- Keep the root export deliberately small.
+- Remove accidental and forwarding barrels where focused imports are clearer; retain only reviewed package entry points with explicit named exports.
+- Add temporary compatibility subpaths required by the classified 140-path migration inventory.
+- Test Node, browser, worker, PouchDB, Object Storage, P2P, and headless entry points independently.
+- Verify that installing a core entry does not pull Svelte UI or language catalogue code into a representative bundle.
+
+### Phase 3: Publish and validate a pre-release
+
+- Publish an immutable pre-1.0 version to a pre-release npm dist-tag.
+- Verify its package name, provenance, checksum, export map, and packed files.
+- Run common-library tests against the packed artefact rather than the source checkout.
+- Run downstream Self-hosted LiveSync type checks, unit tests, integration tests, CLI tests, Webapp tests, WebPeer tests, production builds, and focused real-Obsidian E2E against the exact package version.
+- Validate at least one external consumer which currently uses a submodule or custom loader.
+
+### Phase 4: Convert Self-hosted LiveSync
+
+- Replace `@lib/*` source aliases with package imports.
+- Remove the `src/lib` submodule, `_types`, `tsconfig.types.json`, `generate-types.mjs`, and release-workflow steps which regenerate fallback declarations.
+- Move the multilingual catalogue and its generation tooling into Self-hosted LiveSync, while retaining only Commonlib's typed English fallback in the package.
+- Keep application-owned source under `src/apps` until a separate decision moves an application.
+- Run the community scanner's branch or commit preview before releasing the converted plug-in.
+
+### Phase 5: Stabilise the SDK
+
+- Design a high-level asynchronous client around explicit `create`, `list`, `get`, `put`, `delete`, `watch`, and `close` lifecycles.
+- Specify path normalisation, encryption negotiation, conflict handling, conditional writes, deletion, history, and resource disposal before declaring the façade stable.
+- Adapt `DirectFileManipulator` behind that façade or deprecate it; do not treat its current constructor and deep dependencies as the final API.
+- Narrow or remove compatibility-only export paths as Self-hosted LiveSync imports migrate to documented package modules.
+
+## Implementation Proof
+
+The package proof builds Commonlib as one compiled ESM package with a small root, `context`, `settings`, `remote-configurations`, `browser`, `node`, and `rpc` entries, plus only the explicit compatibility exports required by the reviewed downstream inventory. It publishes neither raw TypeScript nor Svelte source, uses no unrestricted export wildcard, and can be installed into a clean consumer, imported in Node, type-checked from declarations, and bundled independently for browser context, browser storage, browser services, and workers. Release validation records and compares the immutable registry version and checksum.
+
+The compatibility inventory is regenerated from the maintained Self-hosted LiveSync consumer. Focused entries replace compatibility imports when their contracts are proven; obsolete paths are removed from the next candidate rather than retained merely because an earlier immutable release contained them. The multilingual `common/i18n` and `common/rosetta` paths have been removed in this way after ownership moved to the host.
+
+The proof found and fixed three boundary defects which source-alias consumption had hidden: compiled JSON imports required explicit output extensions, precompiled Svelte output could not safely be treated as source by the downstream Svelte pipeline, and Vite's default client conditions selected Commonlib's browser worker while building the Node CLI. Packed-consumer regressions cover the first two. The CLI now uses Vite's server conditions and treats every Node built-in reported by Commonlib's Node entry as external; the built CLI is exercised through Deno E2E. Importing root or context also no longer patches DOM prototypes, translator injection prevents the context entry from loading the complete language catalogue, and standard input and protocol output are supplied by the package-owned host contract rather than direct stream access in command handlers.
+
+Self-hosted LiveSync, its CLI, Webapp, WebPeer, plug-in source, and tests compile against that exact registry artefact without `@lib/*`. Focused downstream storage tests pass against the package-owned Node and File System Access API implementations. Commonlib also owns the Trystero implementation and version; the host retains no direct Trystero dependency, preventing two transport generations from entering one application graph. The old `src/lib` Git submodule, generated `_types` fallback, type-generation scripts, and source aliases are removed by the proof branch.
+
+Commonlib's contract and complete suites cover Context results, both platform storage implementations, standard I/O, replication, settings, and package consumption. Self-hosted LiveSync runs the same host-composition result contract for Obsidian, CLI, and browser compositions against the exact packed artefact, followed by its unit, integration, application-build, CLI E2E, and focused real-Obsidian gates.
+
+The package-owned Trystero transport also completes the canonical Compose P2P synchronisation workflow with a local relay and two isolated CLI peers. In real Obsidian, the plug-in starts with one consistent `ObsidianServiceContext`, the representative server-selection and Setup URI Svelte dialogues mount and close through their normal controls, their mobile variants satisfy viewport, safe-area, and touch-target assertions, and the settings pane exposes only the effective deletion controls. These runtime checks complement the package tests without making Webapp maintenance the primary release gate.
+
+The Community directory scanner preview completes with no source-code errors. The former findings attributed to generated `_types`, raw `src/lib` source, Node built-ins, forbidden rule suppressions, unsupported Obsidian APIs, and undescribed directive comments are absent. This confirms that the registry dependency is recognised as a package boundary. The preview identified behaviour-neutral redundant CLI candidate types and Webapp File System Access API assertions; these are corrected in the host source rather than carried as known warnings.
+
+The remaining source warnings belong to application code. Browser dialogue visibility now uses DOM state instead of inline static styling, so the earlier styling warning is absent. Direct diagnostic output was resolved at its existing ownership boundaries: Webapp components use an injected log function backed by `BrowserAPIService`, WebPeer retains output in its Svelte log store, Obsidian modules use the established Logger path, and duplicate console emission was removed from `ModuleLog`. The later Webapp and WebPeer recomposition around maintained Context and serviceFeature APIs should preserve these explicit output paths.
+
+The final Community lint inventory for this boundary has no errors and 126 warnings: 67 sentence-case findings, 58 deprecated-API findings, and one declarative setting-definition suggestion. The sentence-case strings and deprecated interfaces are retained deliberately to avoid an unrelated localisation and host-lifecycle change. Declarative definitions would migrate the complete Obsidian setting tab into the 1.13 settings-search model; that is a separate visible UI project after LiveSync 1.0, not a hidden package-boundary release gate. Revisit each category through focused UI and compatibility work rather than suppressing the rules or treating the warning count as zero.
+
+WebPeer's production build still reports that Vite externalises the guarded Node `crypto` fallback reached through a compatibility path. Browser execution selects `globalThis.crypto`, and the focused root, `context`, and `browser` bundle checks do not include the Node fallback, so this is not a leak in the reviewed public browser entries. Removing the compatibility-build warning requires a focused crypto-capability contract or a platform-specific implementation split and remains part of compatibility-surface narrowing.
+
+The dependency preview also reports `uuid`, but the installed and locked graph resolves PouchDB's UUID dependency to the patched `uuid@11.1.1` through the repository override, and `npm audit` does not report the UUID advisory. The scanner appears to infer the older declared PouchDB range rather than the resolved override, so this warning is treated as a scanner false positive unless a packed-artefact inspection shows otherwise.
+
+The 1.0 dependency review found newly disclosed parser and denial-of-service advisories with compatible fixes. All locked `brace-expansion` generations now use their patched releases, including the production generation reached by Commonlib path matching and the CLI's user-configured ignore patterns. The development-only ESLint and Istanbul `js-yaml` generations likewise use patched releases. The production Markdown parser uses the patched `linkify-it` release to avoid quadratic processing of maliciously structured `mailto:` links, while the development-only JSON Schema toolchain uses the patched `fast-uri` release for unambiguous hostname parsing. A clean install and both complete and production-only `npm audit` checks no longer report these packages.
+
+The remaining audit report is the existing `werift` and `werift-ice` dependency on `ip`, for which npm offers no patched version. The advisory concerns `ip.isPublic()` misclassifying unusual loopback representations. The locked werift implementation uses `ip` for address encoding, decoding, format detection, and loopback filtering, but does not call `isPublic()` or `isPrivate()`. LiveSync reaches werift only through the Node CLI's injected `RTCPeerConnection`; the Obsidian plug-in and browser applications use their platform WebRTC implementation, and the plug-in artefact does not contain werift. The package-level finding is therefore accepted for the 1.0 integration preview as a non-reachable advisory in the reviewed call path, not as a general waiver. Revisit it when werift or `ip` publishes a replacement, or before any change which delegates address trust, routing, or URL access decisions to that dependency.
+
+The local real-Obsidian suite verifies the actual loaded `ObsidianServiceContext`, all 18 services, Vault reflection, CouchDB and Object Storage transfer, remote-activity accounting, CLI-to-Obsidian encrypted synchronisation, startup scanning, two-Vault create, update, delete, ordinary rename, case-only rename, target mismatch, Hidden File Sync, Customisation Sync, setting Markdown export, and two-device CouchDB, Object Storage, and P2P Setup URI workflows. These checks establish observable results and host composition rather than relying on declaration compatibility alone.
+
+The obsolete mocked browser Harness and its `harness-ci` workflow have been removed. Webapp production builds and the direct browser composition contract remain part of the package-boundary proof; future Webapp browser automation is a Webapp-owned workflow rather than a substitute for real Obsidian E2E.
+
+## Scanner and Repository Consequences
+
+Consuming the npm package removes the common-library source and generated `_types` from the plug-in repository's Community directory scan, because package dependencies are treated as dependencies rather than maintained plug-in source. The branch preview confirms this expected boundary.
+
+The change does not hide or resolve warnings in Self-hosted LiveSync-owned source. The scanner will continue to inspect the plug-in, CLI, Webapp, and WebPeer while those applications remain in the repository. Moving those applications to a LiveSync-family application repository may be considered after the package boundary is stable, but it is not part of this decision because the CLI and Webapp still import shared plug-in composition code.
+
+Package extraction also does not resolve release-asset attestation verification, unsupported release assets, declarative settings migration, or other scanner findings which are independent of source ownership.
+
+## Alternatives Rejected
+
+### Move the common library into the Self-hosted LiveSync monorepo
+
+This would permit atomic source changes and remove the Git submodule, but the community scanner already examines non-plug-in application source. A source workspace would remain in scope, and every library directive and platform dependency would be attributed to the plug-in repository. It would also make independent consumers depend on the plug-in repository's release cadence.
+
+### Move the common library into Fancy Kit
+
+Fancy Kit owns reusable framework-neutral interactions, Obsidian adapters, test infrastructure, and neutral utilities. Replication protocols, chunk and metadata formats, PouchDB composition, conflict rules, and LiveSync storage policy are a different domain. Moving them would obscure ownership and make general plug-in tooling carry Self-hosted LiveSync release concerns.
+
+### Publish the current source tree without changing boundaries
+
+This would expose accidental deep imports, global mutations, Svelte and browser code, Node-only modules, and parent-repository imports. Consumers would still need source aliases and bundler-specific behaviour, while maintainers would be unable to distinguish public API from implementation.
+
+### Split every concern into a separate npm package immediately
+
+Core, language, UI, browser, Node, P2P, Object Storage, and SDK packages could make dependency graphs precise, but the present source has not yet proven those release boundaries. Starting with one compiled package and explicit optional subpaths allows measurement without creating a coordinated release matrix. Additional packages remain possible after their contracts and consumers are demonstrated.
+
+## Verification
+
+The package-boundary conversion is ready for acceptance only when:
+
+- common-library production source has no parent-repository or Obsidian dependency;
+- the package builds and tests from a standalone clean checkout;
+- `npm pack` contains only intended compiled artefacts and documentation;
+- packed Node and browser consumers resolve only exported paths;
+- a headless client does not bundle Svelte or the full language catalogue;
+- retained entry-point barrels do not load unrelated optional implementations, and no removed barrel is replaced by unrestricted deep exports;
+- Self-hosted LiveSync verifies its local Svelte adapter and workflow policy through injected tests and a focused composition smoke test;
+- Self-hosted LiveSync no longer has `src/lib`, `_types`, or `@lib/*` source aliases;
+- the Commonlib owner and packed-consumer suites, Self-hosted LiveSync unit and integration tests, Deno CLI E2E, plug-in and application production builds, and focused real-Obsidian E2E pass against the reviewed package artefact;
+- common-library downstream CI records and tests the exact Self-hosted LiveSync ref;
+- a Community directory scanner preview confirms the expected change in source findings; and
+- compatibility exports are explicitly enumerated from a reviewed downstream inventory rather than exposed through a wildcard.
+
+The following are later SDK-stabilisation gates, not blockers for accepting the package boundary:
+
+- two clients with different database, encryption, language, and lifecycle settings can coexist without sharing mutable client state;
+- an external consumer can replace its submodule or custom loader with the documented high-level package API; and
+- if the framework-neutral Modal host is promoted to Fancy Kit, Kit-owned lifecycle, viewport, safe-area, and touch-target guarantees replace duplicated device tests in LiveSync.
+
+## Consequences
+
+- The common library gains an independently consumable and testable artefact while retaining its domain ownership and history.
+- Self-hosted LiveSync release archives no longer need generated fallback declarations for an absent submodule.
+- Community directory scanning distinguishes plug-in source from the reviewed dependency.
+- Changes which span the package and plug-in require coordinated package and downstream validation rather than one atomic source commit.
+- Temporary compatibility exports increase the first package surface, but their pre-1.0 status and explicit classification prevent them from becoming silent permanent contracts.
+- Application translation, Svelte, and platform dependencies become optional composition concerns rather than root-package side effects; Commonlib's small English fallback remains safe by default.
+- Fancy Kit may gain a generally useful typed Obsidian Modal host without acquiring LiveSync policy or a mandatory Svelte dependency.
+
+## Later Open Questions
+
+- Define the minimum conflict and conditional-write guarantees required by the first public high-level client.
+- Continue narrowing the broad model, service-composition, and replication compatibility paths as focused result contracts become available.
+- Confirm whether another Fancy Kit consumer needs the framework-neutral Modal host before it is added to the Kit, or whether LiveSync should pilot the contract first.

docs/adr/2026_07_feature_maturity_for_1_0.md

@@ -0,0 +1,49 @@
+# Feature maturity for 1.0
+
+## Status
+
+Proposed for the 1.0 integration branch.
+
+## Context
+
+Self-hosted LiveSync accumulated several labels such as 'experimental', 'Beta', 'obsolete', and 'sunset' over the 0.x line. Those labels did not consistently describe the current implementation. Some formerly experimental features now have maintained unit, Compose, and real-Obsidian coverage, while some old database-format options remain executable only because existing data must still be opened safely.
+
+Version 1.0 needs to distinguish supported opt-in features from previews and from compatibility paths. Removing a label does not make a network environment reliable, and retaining a setting key does not make it a recommendation.
+
+## Decision
+
+### Supported opt-in features
+
+- Peer-to-Peer Synchronisation is supported. Commonlib owns the transport lifecycle, the Compose suite covers transfer, replacement, disconnect, and reconnect behaviour, and the Obsidian host verifies its current pane boundary. Documentation must describe environmental WebRTC limitations without calling the feature experimental.
+- Hidden File Sync is supported as an advanced, separately initialised feature. It remains disabled during ordinary Setup URI initialisation and has its own two-Vault, conflict, filtering, and notification acceptance workflow.
+- Customisation Sync is supported as an advanced opt-in feature. Its maintained two-Vault real-Obsidian workflow covers snippets, configuration files, and plug-in files, including updates and deletion of source synchronisation data. It remains separate from Hidden File Sync and must not manage the same files concurrently.
+- Data Compression is maintained as an advanced opt-in storage and bandwidth trade-off. It remains disabled by default. The three-repeat CLI and CouchDB benchmark reduced stored chunk data and upload bodies by about 9% for the mixed fixture, but processing and worker-memory costs remained substantial. The [Data Compression specification](../specs_data_compression.md) records the contract, measurements, compatibility behaviour, execution model, and reproduction path for future default-setting decisions.
+- The real-Obsidian E2E runner is maintained release infrastructure rather than an experimental Harness.
+
+### Retained previews
+
+- JWT authentication remains experimental because it depends on specialised CouchDB server configuration and does not yet have a maintained server-backed authentication matrix. The current implementation, Setup URI transport, focused unit coverage, and reported ES512 use justify retaining it.
+- Ignore files remain Beta. They have focused target-filter tests, but nested rules, hidden-file expectations, and open user reports still require review.
+- Automatic newer-file conflict resolution remains Beta and disabled by default because it can deliberately overwrite one side of a conflict.
+- Garbage Collection V3 remains Beta and explicitly initiated. Its algorithm and safety protocol are outside this classification change and require a separate decision.
+
+### Compatibility-only and sunset paths
+
+- E2EE V1 and its dynamic iteration-count setting remain for existing encrypted databases. E2EE V2 is the new-Vault contract.
+- The old IndexedDB adapter remains only with its migration path back to IDB.
+- `xxhash64` is the current hash contract. Other hash algorithms remain available for existing databases and edge-case recovery, not as experimental alternatives for new Vaults.
+- Eden chunks remain accepted at runtime and in transported settings, but are not offered in the settings interface.
+- `doNotUseFixedRevisionForChunks` remains an inert compatibility input. Chunk revisions are always content-derived.
+- The deprecated cleaned-database reconciliation callback remains internal while an old IndexedDB client may still encounter that remote state. It is not a user-selectable maintenance action and is omitted from the settings reference.
+
+### Already removed
+
+The obsolete mocked browser Harness, automatic bulk chunk pre-send, legacy trash toggle, and fixed-revision control have no supported 1.0 UI path. Their compatibility data, where required, remains accepted independently of their removed controls.
+
+## Consequences
+
+- Supported opt-in features retain focused release gates and user documentation.
+- Preview features remain off by default and keep explicit maturity labels.
+- Compatibility-only settings must not silently change existing data formats. New configuration should not expose retired formats merely because their decoders remain available.
+- Commonlib setting types and Setup URI decoding remain broad enough to read existing configurations. Removing those package contracts requires a separately versioned compatibility decision.
+- Deprecated host accessors and Community directory API warnings are a separate refactoring boundary. This decision does not authorise removing broadly used internal access paths.

docs/adr/2026_07_multiple_remote_onboarding.md

@@ -0,0 +1,88 @@
+# Architectural Decision Record: Make Onboarding Profile-Aware
+
+## Status
+
+Accepted — implemented and verified against the locked Commonlib package.
+
+## Context
+
+Self-hosted LiveSync stores multiple remote connections in `remoteConfigurations` and selects the ordinary replication target with `activeConfigurationId`. P2P features have a separate `P2P_ActiveRemoteConfigurationId`. Existing replication implementations still consume the older flat CouchDB, Object Storage, and P2P fields, so selecting a profile projects its connection settings onto those compatibility fields.
+
+The settings pane already creates and edits profiles directly. The Setup Wizard was inconsistent:
+
+- modern Setup URI and QR payloads retained a supplied profile map;
+- legacy imports relied on `SettingService` to migrate flat connection fields into `legacy-*` profiles;
+- manual CouchDB and Object Storage setup wrote only the flat fields and relied on that same migration; and
+- manual P2P setup partly updated the profile map itself.
+
+Legacy migration deliberately runs only when the profile map is empty. If a Vault already had one or more profiles, manually configuring another CouchDB or Object Storage connection changed the flat fields but did not add a profile. The selected stored profile could subsequently project its older values back onto those fields. Fresh P2P onboarding could also finish without a profile when no P2P profile ID existed beforehand.
+
+## Decision
+
+The profile map is authoritative persisted state for every newly configured remote. The compatibility fields remain the runtime projection of a selected profile and the input accepted from an older settings payload.
+
+### Manual onboarding
+
+A successful manual CouchDB, Object Storage, or P2P setup creates or deliberately updates a profile through Commonlib's focused `@vrtmrz/livesync-commonlib/remote-configurations` entry.
+
+- Existing profiles are preserved.
+- A newly created profile receives an opaque generated ID.
+- CouchDB and Object Storage setup select the new profile as the main remote.
+- P2P setup selects the profile through `P2P_ActiveRemoteConfigurationId`.
+- P2P setup also selects it as the main remote when P2P is being configured as the main remote.
+- Configuring P2P alongside another main remote changes only the P2P selection.
+- A known profile ID is supplied only when an existing profile is deliberately being updated; omitting the ID creates another profile.
+
+The onboarding dialogue does not add a naming step. Commonlib proposes a concise type-specific display name and adds a numeric suffix when necessary. The settings pane can rename it later.
+
+### Identity and naming
+
+Profile names are presentation only. They are neither unique identity nor a marker for the selected profile. No entry receives a special `default` ID or name. Opaque IDs establish identity, `activeConfigurationId` establishes the main selection, and `P2P_ActiveRemoteConfigurationId` establishes the P2P selection.
+
+Generated names describe the connection without exposing credentials, for example `CouchDB couch.example`, `S3 notes`, or `P2P team-room`.
+
+### Setup URI and QR import
+
+A modern payload preserves its profile IDs, display names, profile URIs, main selection, and P2P selection. Setup does not rename or recreate those profiles.
+
+A legacy payload containing only flat connection fields remains supported. `SettingService` migrates it into clearly labelled `legacy-couchdb`, `legacy-s3`, or `legacy-p2p` profiles only when no modern profile map exists. This is the only onboarding path which intentionally relies on the compatibility migration.
+
+### Persistence and restart ordering
+
+Profile construction happens before the settings are submitted to the onboarding completion boundary. Existing-device and new-device setup reserve Fetch or Rebuild respectively before enabling and saving the settings. Profile awareness does not change that initialisation ownership or restart ordering.
+
+Commonlib produces an in-memory plaintext profile URI. The standard setting service applies its configured at-rest encryption during persistence.
+
+## Alternatives rejected
+
+### Keep relying on legacy migration
+
+This works only while the profile map is empty. It silently fails to register a newly configured connection once multiple-remote settings are already in use and leaves P2P with a separate implementation.
+
+### Create a special `default` profile
+
+The special meaning would duplicate `activeConfigurationId`, make a user-visible name carry identity, and become ambiguous as soon as the user selects another profile. Selection IDs already express the required state.
+
+### Add profile naming and full list editing to onboarding
+
+That would make the first-run path longer and duplicate the established Remote Databases interface. Automatic descriptive names and later renaming keep this change limited to data integrity and consistent selection.
+
+### Replace the compatibility fields immediately
+
+Replication, diagnostics, and older settings paths still consume the projected fields. Removing them belongs to a broader runtime migration and is not required to make onboarding correctly profile-aware.
+
+## Verification
+
+Commonlib unit tests cover preserving existing profiles, opaque-ID insertion, generated display names, duplicate-name suffixes, main activation, independent P2P selection, and URI serialisation. Its packed-consumer test imports the focused entry point from the generated package.
+
+Self-hosted LiveSync unit tests cover preserving modern Setup URI profiles and their active selection, retaining legacy Setup URI and QR migration, adding CouchDB and Object Storage profiles beside an existing profile, independent P2P selection, fresh P2P selection as both main and P2P remote, and cancellation without mutation.
+
+The real-Obsidian onboarding E2E owns the invitation, dialogue presentation, safe-area and touch-target checks, cancellation, and command reopening. It does not contact a remote or submit credentials. Remote connection correctness remains owned by the CouchDB, Object Storage, P2P, and two-Vault suites. The end-to-end Setup URI and provisioning acceptance workflow remains a separate release gate.
+
+## Consequences
+
+- Manual onboarding and the Remote Databases pane share one Commonlib profile contract.
+- Existing profiles survive reconfiguration, and a newly configured connection becomes explicitly selectable.
+- Modern imports retain user-assigned profile identity and names.
+- Legacy Setup URIs continue to work through an isolated compatibility boundary.
+- Runtime consumers may keep using projected flat fields while the persisted model and new APIs use the 1.0 multiple-remote contract.

docs/adr/2026_07_p2p_transport_lifecycle.md

@@ -0,0 +1,91 @@
+# Architectural Decision Record: P2P Room and Transport Lifecycle
+
+## Status
+
+Accepted — implemented and verified through Commonlib owner tests, the Compose transport suite, and the real-Obsidian setup workflow.
+
+## Context
+
+Self-hosted LiveSync uses Trystero's Nostr strategy for P2P discovery, signalling, and WebRTC transport. Three related resources have different owners and lifetimes:
+
+- a LiveSync P2P service instance owns its commands, RPC sessions, advertisements, and room membership;
+- Trystero owns the underlying WebRTC peers and may share one physical peer across more than one room; and
+- Trystero's Nostr relay manager owns WebSocket clients shared by relay URL.
+
+Closing every `RTCPeerConnection` returned by `room.getPeers()` bypasses Trystero's shared-peer manager. The manager may then retain a stale shared peer and prevent a replacement LiveSync replicator from discovering the same remote peer again.
+
+Room departure and physical transport destruction are not equivalent. `room.leave()` sends the room-leave action, removes that room's actions and callbacks, and detaches its shared-peer binding. Trystero may retain a healthy physical WebRTC peer for later reuse after the last room binding has gone. The retained peer cannot carry actions for the room which has been left.
+
+Relay WebSockets have a separate lifecycle. LiveSync's explicit disconnect operation must close them and prevent automatic reconnection. A later explicit connect must allow reconnection before joining the room again.
+
+## Decision
+
+Normal P2P shutdown delegates physical peer ownership to Trystero:
+
+1. Stop LiveSync broadcast, replication, watch, client, and RPC state.
+2. Leave the active Trystero room through `room.leave()`.
+3. Remove LiveSync's room, advertisement, diagnostic-listener, and active-instance references.
+4. Pause Trystero relay reconnection and close the current relay WebSockets.
+
+LiveSync does not call `close()` on the `RTCPeerConnection` values returned by `room.getPeers()` during normal shutdown or from a peer-leave callback. A peer-leave callback removes LiveSync-owned advertisement and client state only. Trystero remains responsible for deciding whether an underlying shared peer is reusable, stale, or ready for idle destruction.
+
+The explicit disconnect operation therefore has the following contract:
+
+| Resource                          | State after the operation                                                                         |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| LiveSync P2P service and RPC room | Closed immediately.                                                                               |
+| Trystero room membership          | Left; room actions and advertisements are no longer available.                                    |
+| Nostr relay WebSockets            | Closed, with automatic reconnection paused.                                                       |
+| Underlying WebRTC peer            | May remain idle under Trystero ownership for reuse, but cannot carry the departed room's traffic. |
+
+This operation is a logical LiveSync disconnection and a physical signalling-server disconnection. It does not promise that every browser-owned WebRTC object has been destroyed synchronously.
+
+An explicit connect resumes relay reconnection before opening a new room. Settings application and database lifecycle replacement close the current LiveSync replicator, discard it, construct a new instance from the current settings, and open that current instance when the configured policy requires it. Commands, event handlers, and panes resolve the current service-feature result at the point of use rather than retaining an obsolete replicator.
+
+Lifecycle operations on one `LiveSyncTrysteroReplicator` are serialised. A close requested while an open is in progress must leave no orphan room serving, and repeated opens must not create parallel rooms. No fixed delay is inserted between close and open: readiness is determined by the actual lifecycle operation and peer discovery.
+
+Relay sockets retain their Trystero-provided close handlers. LiveSync pauses relay reconnection, closes the sockets, and later resumes reconnection through Trystero's public functions. It does not replace `socket.onclose`, because Trystero uses that handler to retire and recreate shared relay clients correctly.
+
+P2P setup follows the transport's actual ownership model. First-device initialisation resets and scans the local database, but does not attempt to lock, reset, or upload to a non-existent central remote database. Its confirmation dialogues therefore describe preparing this device and do not present the central-server overwrite warnings or remote-configuration option. An additional device performs one explicit peer-selection and finite Fetch pass, then resumes database and Vault reflection. The generic second convergence pass remains reserved for central remote types because repeating it for P2P would ask the user to select the same peer twice.
+
+## Ownership
+
+Commonlib owns the LiveSync-specific P2P service, RPC, command, and lifecycle composition. Trystero owns WebRTC peer creation, sharing, reuse, stale detection, and destruction, as well as relay-client reconstruction. The Self-hosted LiveSync host owns the current Commonlib service-feature result and supplies the platform services used by its current replicator.
+
+Self-hosted LiveSync does not add a separate root Trystero dependency. Tests which must observe relay sockets resolve the exact Trystero generation owned by the locked Commonlib package, avoiding two independent transport singletons in one process.
+
+## Alternatives rejected
+
+### Close every value returned by `room.getPeers()`
+
+This bypasses Trystero's shared-peer manager and can prevent a replacement replicator from rediscovering the same peer.
+
+### Add a fixed close-to-open delay
+
+A timing guess does not repair stale ownership and would make ordinary settings application slower.
+
+### Keep raw close behaviour behind a force command
+
+Changing the command name does not make the lifecycle safe. A force command which cannot reconnect predictably has no reliable operational value.
+
+### Override relay `onclose` to suppress reconnection
+
+This interferes with Trystero's shared relay clients. The public pause and resume functions provide the intended control boundary.
+
+## Verification
+
+Commonlib unit tests prove that normal P2P host closure calls `room.leave()` without directly closing Trystero-owned peer connections. Additional package tests cover the action API, replaceable peer-event subscriptions, multiple RPC transport disposers, serialised open and close operations, local-only first-device initialisation, and one-pass additional-device Fetch.
+
+Self-hosted LiveSync unit tests prove that settings and database replacement leave panes on the current replicator, and that an explicit P2P rebuild bypasses the policy intended for ordinary replication.
+
+The canonical Compose P2P suite uses a real local Nostr relay and WebRTC implementation. It covers ordinary two-peer synchronisation, replacement of the active LiveSync replicator followed by discovery and transfer with the same peer, and explicit relay disconnection followed by paused and resumed reconnection. The lifecycle scenario is exposed only through a Docker test build and an injected CLI command runner; it is not part of the public CLI command surface.
+
+The real-Obsidian P2P Setup URI workflow creates the first device, generates the second-device URI from it, accepts each peer visibly, and verifies a two-way note round-trip through a local relay. A separate focused pane test covers the principal connection control and teardown without requiring a remote peer. Transport replacement and relay-socket lifecycle remain owned by the package and Compose tests rather than being duplicated in Obsidian.
+
+## Consequences
+
+- Replacing a P2P replicator no longer leaves host views or commands bound to an obsolete instance.
+- Explicit signalling-server disconnection has a testable socket-level meaning without claiming immediate destruction of idle WebRTC objects.
+- Settings which change the relay, room, passphrase, or TURN configuration can replace the whole LiveSync room safely.
+- Trystero may reuse healthy peers across room lifecycles, reducing unnecessary renegotiation.
+- Strict physical WebRTC teardown remains unavailable until Trystero exposes a safe ownership-aware operation.

docs/adr/2026_07_release_notes_and_database_compatibility.md

@@ -0,0 +1,103 @@
+# Release notes and database compatibility gates
+
+## Status
+
+Accepted for the 1.0 release line.
+
+## Context
+
+Self-hosted LiveSync historically used several unrelated kinds of version and settings state during start-up.
+
+The plug-in SemVer was converted into a numeric major/minor value and stored in `lastReadUpdates`. The settings dialogue used that value to open the change log automatically, and offered a button which marked the release line as read. Patch versions were intentionally ignored. Pre-release identifiers containing an additional dot did not fit this numeric representation and could be interpreted as a much larger release line.
+
+Separately, the internal database compatibility constant `VER` is recorded in device-local storage under a Vault-scoped key. Crossing this internal version used to set `versionUpFlash` and permanently change several automatic synchronisation settings to `false`. Replication services already reject work while `versionUpFlash` is non-empty, so changing the user's saved choices duplicated the runtime safety gate and required manual reconstruction after acknowledgement.
+
+The remote `obsydian_livesync_version` document also carries the internal database version. It is a protocol and data-compatibility mechanism, not a copy of the plug-in SemVer.
+
+Commonlib's `settingVersion` describes the stored settings shape, while `DEFAULT_SETTINGS` was historically used both to complete missing values in an existing document and to initialise a new Vault. Those operations require different defaults: an existing Vault needs conservative completion, while a genuinely new Vault can use current recommendations without changing an established configuration.
+
+## Decision
+
+### Release notes
+
+- Keep the change-log pane and render the current release history whenever it is opened.
+- Remove automatic unread-version tracking, the acknowledgement button for ordinary release notes, and automatic navigation to the change-log pane.
+- Do not derive data-compatibility behaviour from the plug-in's major, minor, patch, or pre-release identifiers.
+- Retain the saved `lastReadUpdates` field in the settings schema for backwards compatibility, but do not use it in the plug-in. It can be removed through a separately reviewed settings-schema migration if retaining it later becomes burdensome.
+
+### Settings schema and initial settings
+
+- Keep the Commonlib settings schema version independent of the plug-in SemVer and the internal database version `VER`. Increment it only for an ordered change to the stored settings shape.
+- Use Commonlib's conservative schema defaults to complete an existing settings document. Explicit stored values take precedence, and an ordinary migration does not disable or replace the person's synchronisation choices.
+- Use `createNewVaultSettings()` only for a store which has never held Self-hosted LiveSync settings, explicit new-user onboarding, a factory reset, or CLI settings creation. Setup URI, QR, Markdown, and other existing-setting imports retain conservative completion semantics.
+- Apply remote-specific preferred values only when that remote is explicitly selected during setup. Do not infer and merge new recommendations into an existing configuration.
+- Keep settings saved by a future Commonlib schema fail-closed and do not persist an apparent downgrade migration.
+
+The current new-Vault base selects a 50 MB maximum synchronised file size, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. It does not enable synchronisation, encryption, or a remote connection without user action. Chunk revisions are always content-derived; `doNotUseFixedRevisionForChunks` remains only as deprecated compatibility input and is not a recommendation or review setting.
+
+Relative to the conservative existing-setting fallbacks, only Plug-in Sync V2 and the explicit case-insensitive value differ for a new Vault. The 50 MB limit, Rabin–Karp splitter, and E2EE V2 already match the legacy fallback values. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when absent from an existing settings document.
+
+An existing settings document without an explicit `handleFilenameCaseSensitive` choice is normalised to `false` and saved. This preserves the effective case-insensitive branch used by earlier releases when the value was absent, and does not require a review or rebuild. An explicit `true` or `false` choice remains unchanged.
+
+Keep configured-state inference separate from new-Vault initialisation. If an existing legacy document has no `isConfigured` value, repeat the pre-1.0 comparison with the conservative defaults: a default-equivalent document remains unconfigured, while a non-default stored value is evidence that it was configured. Persist that inferred boolean so a migration cannot turn an unconfigured Vault into an irreversible configured state merely because its settings document was non-empty.
+
+### Database compatibility
+
+- Continue to use the internal database version `VER` for changes which require explicit compatibility review. Changing the plug-in SemVer alone does not increment `VER`.
+- Store the last acknowledged internal database version through Commonlib's device-local small-configuration contract under `database-compatibility-version`. Copy the legacy raw local-storage value into that contract once, then remove the legacy key after the copy has completed.
+- Initialise the marker to the current `VER` only when Commonlib identifies a genuinely new Vault with no pending review. A configured existing Vault with a missing or invalid marker requires review instead of being silently accepted.
+- Defer database compatibility evaluation for an existing unconfigured Vault. It cannot replicate, so do not persist a misleading pause or acknowledge its missing marker while onboarding is still pending. Keep the marker absent so a later configured start evaluates the same state before ordinary synchronisation.
+- Treat a missing marker on a configured Vault as an ambiguous device transition. Copying or restoring a Vault, or opening it with a new Obsidian profile, can preserve settings and database files without preserving device-local storage. Do not infer acknowledgement from an empty local database: a recovery operation, partial copy, or remote-first setup can also produce that state. Explain these cases and require an explicit decision in the compatibility dialogue.
+- Derive one structured pause from the acknowledged database version, Commonlib's settings-migration state, and any persisted legacy review message. Persist the generic `versionUpFlash` message without changing any automatic synchronisation setting, because Commonlib already treats that field as a replication gate.
+- Treat non-empty `versionUpFlash` as a runtime replication gate. Standard and one-shot replication must stop before remote work begins.
+- Apply the same ordinary replication policy to P2P pull, push, and peer-requested synchronisation. An explicitly confirmed Fetch or Rebuild may bypass the ordinary policy because it is the operation selected to construct or recover the local state.
+- Present the reason in a dedicated dialogue after the Obsidian layout is ready. The details view is explanatory only and returns to the summary before any decision can be made. The safe default and closing either dialogue keep synchronisation paused. A persistent Notice and a command allow the dialogue to be reopened without using the settings pane.
+- Let the person read focused compatibility details without presenting the whole release history as a safety instruction. The Change Log remains a manually opened release-history pane and contains no compatibility acknowledgement control.
+- Offer an explicit resume action only when every reason is recoverable in the running implementation. An upgrade, a missing or invalid marker on an existing Vault, and a reviewed migration from an older settings schema are resumable after all devices have been updated. A downgrade from a newer acknowledged `VER`, or settings saved by a future schema, cannot be acknowledged by the older installation.
+- On resume, clear `versionUpFlash` and persist that fail-closed change before recording the current `VER` as acknowledged. If saving fails, restore the gate. Reapply settings only after the marker has advanced so that the previously configured synchronisation behaviour can resume without reconstruction.
+- Preserve the original legacy review message as a structured reason when no more specific database or settings-schema reason is available. Escape it before including it in Markdown UI.
+- Continue to reject a remote version document which is newer than the running implementation. That receiver-side check is independent of the local upgrade review.
+
+### Onboarding activation and initialisation
+
+- Keep an unconfigured Vault outside database initialisation, offline scanning, and configured-only checks. Offer setup through the long-lived onboarding Notice and the permanent command instead of opening a competing dialogue automatically.
+- For new-device onboarding, reserve Rebuild before enabling and saving the accepted settings.
+- For an unconfigured existing device, reserve Fetch before enabling and saving imported or manually confirmed settings.
+- Suspend the current runtime after the flag has been written, apply the accepted settings through the scheduler's preparation callback, and request restart only after that callback succeeds.
+- If the flag cannot be written, do not enable the settings. If preparation fails, remove the flag, resume the current runtime, and leave the transition incomplete.
+- Applying compatible settings to an already configured device remains an ordinary edit and does not schedule Fetch automatically.
+
+`isConfigured`, the Fetch and Rebuild flags, and in-memory suspension therefore retain separate meanings. `isConfigured` controls participation in ordinary processing, a flag selects a one-shot operation for the next start, and suspension prevents the old process from observing newly enabled settings before that selected restart.
+
+### Flag-file recovery order
+
+- For a configured Vault, evaluate and persist the compatibility gate after settings load, before Obsidian layout-ready recovery begins. This blocks ordinary and one-shot replication even while the review dialogue has not yet opened. An existing unconfigured Vault follows the deferred rule above instead.
+- Preserve the existing ordered flag-file recovery handlers: SCRAM at priority 5, fetch-all at priority 10, and rebuild-all at priority 20. These files express an explicit recovery instruction and may invoke their focused storage or rebuild service while ordinary replication remains gated.
+- Present the compatibility review at priority 30, after any selected recovery operation. A recovery handler which cancels start-up, keeps SCRAM active, or schedules a restart returns `false`, so the current process does not open a competing compatibility dialogue. If recovery completes and start-up continues, the dialogue opens before normal synchronisation is allowed to resume.
+- Keep database preparation independent of an unanswered compatibility dialogue, because the compatibility gate already blocks replication. Before Config Doctor begins its interactive checks, await the active initial review so that the two update dialogues cannot overlap.
+- Never mark compatibility as acknowledged merely because fetch, rebuild, or local database reset completed. The person must still use the explicit resume action. This keeps destructive recovery intent separate from protocol and settings compatibility acknowledgement.
+
+## Consequences
+
+- Ordinary releases no longer force the settings dialogue to show release notes. Important operational instructions must be clear in the published release notes and any explicit migration notice.
+- SemVer pre-releases such as `1.0.0-rc.0` no longer require a special numeric encoding inside plug-in settings.
+- An internal compatibility change remains fail-closed for replication, but it no longer destroys the person's synchronisation preferences.
+- A new installation has no previous internal-version marker and therefore does not show an upgrade review. Its initial settings and onboarding remain responsible for keeping replication disabled until configuration is complete.
+- An existing unconfigured installation also remains on onboarding without a compatibility warning. Unlike a genuinely new Vault, it does not receive an acknowledgement marker; activation leaves the compatibility decision for its next configured start.
+- A copied or restored configured Vault can show a one-time compatibility review on its new device or profile. This is intentional even when its local database appears empty, because emptiness does not prove how the Vault was produced.
+- A genuinely new Vault receives current recommendations without applying them as fallbacks to an existing configuration. It remains inert until onboarding is accepted.
+- Accepted new-device and existing-device setup cannot enable ordinary processing before the selected Rebuild or Fetch has been reserved.
+- An older installation cannot dismiss evidence that a newer implementation or settings schema has already been used on the device.
+- The Obsidian-specific dialogue depends only on a host-neutral compatibility result and the injected confirmation capability. Commonlib remains responsible for settings migration, device-local storage, and the replication gate.
+- A future incompatible database change must increment `VER`, provide an actionable review message, verify the remote version negotiation, and test both the pending and acknowledged states. A major SemVer increase without those changes has no database-compatibility effect.
+
+## Verification
+
+- Unit tests verify new-Vault initialisation, upgrades, missing and invalid markers, downgrades, future settings schemas, legacy marker migration, acknowledgement ordering, and save-failure recovery while retaining automatic synchronisation choices.
+- Commonlib package tests verify conservative stored-setting completion, independently mutable new-Vault settings, legacy file-name case normalisation, future-schema protection, and the focused settings entry from a clean consumer.
+- Host unit tests verify new-Vault factory use, conservative import paths, the unconfigured start-up gate, deferred compatibility evaluation and later re-evaluation, flag-before-settings ordering, rollback when the flag cannot be reserved, ordinary configured edits, and compatibility acknowledgement persistence.
+- Unit tests verify that a pending review is honoured by the packaged Commonlib replication service before remote activity begins.
+- Unit and Compose tests verify that ordinary P2P replication observes the policy, explicit P2P rebuild uses the setup bypass, and replacement leaves host actions on the current replicator.
+- A real-Obsidian settings test verifies the dedicated summary and details dialogues, captures representative screenshots, confirms that the acknowledged internal version advances only after explicit resume, and confirms that the Change Log contains no acknowledgement control.
+- The real-Obsidian CouchDB workflow starts from configured plug-in data without a device-local marker, verifies the copied-or-restored Vault explanation, resumes through the actual dialogue, and then completes remote metadata, chunk, and activity checks. The two-Vault workflow performs the same review once per isolated Vault before reusing the acknowledged device state for later process launches.
+- Unit tests fix the layout-ready priority after the three flag-file recovery priorities, so a recovery which stops start-up cannot race the compatibility dialogue.

docs/datastructure.md

@@ -0,0 +1,169 @@
+# Data Structures of Self-Hosted LiveSync
+
+## Overview
+
+Self-hosted LiveSync uses the following types of documents:
+
+- Metadata
+    - Legacy Metadata
+    - Binary Metadata
+    - Plain Metadata
+- Chunk
+- Versioning
+- Synchronise Information
+- Synchronise Parameters
+- Milestone Information
+
+## Description of Each Data Structure
+
+All documents inherit from the `DatabaseEntry` interface. This is necessary for conflict resolution and deletion flags.
+
+```ts
+export interface DatabaseEntry {
+    _id: DocumentID;
+    _rev?: string;
+    _deleted?: boolean;
+}
+```
+
+### Versioning Document
+
+This document stores version information for Self-hosted LiveSync.
+The ID is fixed as `obsydian_livesync_version` [VERSIONING_DOCID]. Yes, the typo has become a curse.
+When Self-hosted LiveSync detects changes to this document via Replication, it reads the version information and checks compatibility.
+This internal database version is independent of the plug-in's SemVer version. The last version explicitly acknowledged on a device is stored through Commonlib's device-local configuration contract. When that version differs, or when a settings migration requires review, Self-hosted LiveSync presents a dedicated compatibility dialogue and blocks replication without changing the user's automatic synchronisation choices. A supported upgrade can resume only after explicit review. A downgrade from a newer acknowledged database version, or settings written by a future schema, remains blocked until a compatible plug-in is installed.
+Please refer to negotiation.ts.
+
+### Synchronise Information Document
+
+This document stores information that should be verified in synchronisation settings.
+The ID is fixed as `syncinfo` [SYNCINFO_ID].
+The information stored in this document is only the conditions necessary for synchronisation to succeed, and as of v0.25.43, only a random string is stored.
+This document is only used during rebuilds from the settings screen for CouchDB-based synchronisation, making it like an appendix. It may be removed in the future.
+
+### Synchronise Parameters Document
+
+This document stores synchronisation parameters.
+Synchronisation parameters include the protocol version and salt used for encryption, but do not include chunking settings.
+
+The ID is fixed as `_local/obsidian_livesync_sync_parameters` [DOCID_SYNC_PARAMETERS] or `_obsidian_livesync_journal_sync_parameters.json` [DOCID_JOURNAL_SYNC_PARAMETERS].
+
+This document exists only on the remote and not locally.
+This document stores the following information.
+It is read each time before connecting and is used to verify that E2EE settings match.
+This mismatch cannot be ignored and synchronisation will be stopped.
+
+```ts
+export interface SyncParameters extends DatabaseEntry {
+    _id: typeof DOCID_SYNC_PARAMETERS;
+    type: (typeof EntryTypes)["SYNC_PARAMETERS"];
+    protocolVersion: ProtocolVersion;
+    pbkdf2salt: string;
+}
+```
+
+#### protocolVersion
+
+This field indicates the protocol version used by the remote. Mostly, this value should be `2` (ProtocolVersions.ADVANCED_E2EE), which indicates safer E2EE support.
+
+#### pbkdf2salt
+
+This field stores the salt used for PBKDF2 key derivation on the remote. This salt and the passphrase provides E2EE encryption keys.
+
+### Milestone Information Document
+
+This document stores information about how the remote accepts and recognises clients.
+The ID is fixed as `_local/obsidian_livesync_milestone` [MILESTONE_DOCID].
+This document exists only on the remote and not locally.
+This document is used to indicate synchronisation progress and includes the version range of accepted chunks for each node and adjustment values for each node.
+Tweak Mismatched is determined based on the information in this document.
+
+For details, please refer to LiveSyncReplicator.ts, LiveSyncJournalReplicator.ts, and LiveSyncDBFunctions.ts.
+
+```ts
+export interface EntryMilestoneInfo extends DatabaseEntry {
+    _id: typeof MILESTONE_DOCID;
+    type: EntryTypes["MILESTONE_INFO"];
+    created: number;
+    accepted_nodes: string[];
+    node_info: { [key: NodeKey]: NodeData };
+    locked: boolean;
+    cleaned?: boolean;
+    node_chunk_info: { [key: NodeKey]: ChunkVersionRange };
+    tweak_values: { [key: NodeKey]: TweakValues };
+}
+```
+
+### locked
+
+If the remote has been requested to lock out from any client, this is set to true.
+When set to true, clients will stop synchronisation unless they are included in accepted_nodes.
+
+### cleaned
+
+If the remote has been cleaned up from any client, this is set to true.
+In this case, clients will stop synchronisation as they need to rebuild again.
+
+### Metadata Document
+
+Metadata documents store metadata for Obsidian notes.
+
+```ts
+export interface MetadataDocument extends DatabaseEntry {
+    _id: DocumentID;
+    ctime: number;
+    mtime: number;
+    size: number;
+    deleted?: boolean;
+    eden: Record<string, EdenChunk>; // Obsolete
+    path: FilePathWithPrefix;
+    children: string[];
+    type: EntryTypes["NOTE_LEGACY" | "NOTE_BINARY" | "NOTE_PLAIN"];
+}
+```
+
+### type
+
+This field indicates the type of Metadata document.
+By convention, Self-hosted LiveSync does not save the mime type of the file, but distinguishes them with this field. Please note this.
+Possible values are as follows:
+
+- NOTE_LEGACY: Legacy metadata document
+    - Please do not use
+- NOTE_BINARY: Binary metadata document (newnote)
+- NOTE_PLAIN: Plain metadata document (plain)
+
+#### children
+
+This field stores an array of Chunk Document IDs.
+
+#### \_id, path
+
+\_id is generated based on the path of the Obsidian note.
+
+- If the path starts with `_`, it is converted to `/_` for convenience.
+- If Case Sensitive is disabled, it is converted to lowercase.
+
+When Obfuscation is enabled, the path field contains `f:{obfuscated path}`.
+The path field stores the path as is. However, when Obfuscation is enabled, the obfuscated path is stored.
+
+When Property Encryption is enabled, the path field stores all properties including children, mtime, ctime, and size in an encrypted state. Please refer to encryption.ts.
+
+### Chunk Document
+
+```ts
+export type EntryLeaf = DatabaseEntry & {
+    _id: DocumentID;
+    type: EntryTypes["CHUNK"];
+    data: string;
+};
+```
+
+Chunk documents store parts of note content.
+
+- The type field is always `[CHUNK]`, `leaf`.
+- The data field stores the chunk content.
+- The \_id field is generated based on a hash of the content and the passphrase.
+
+Hash functions used include xxHash and SHA-1, depending on settings.
+Chunking methods used include Contextual Chunking and Rabin-Karp Chunking, depending on settings.

docs/design_docs/chunk_aggregation_by_prefix.md

@@ -0,0 +1,122 @@
+# [WITHDRAWN] Chunk Aggregation by Prefix 
+
+## Goal
+
+To address the "document explosion" and storage bloat issues caused by the current chunking mechanism, while preserving the benefits of content-addressable storage and efficient delta synchronisation. This design aims to significantly reduce the number of documents in the database and simplify Garbage Collection (GC).
+
+## Motivation
+
+Our current synchronisation solution splits files into content-defined chunks, with each chunk stored as a separate document in CouchDB, identified by its hash. This architecture effectively leverages CouchDB's replication for automatic deduplication and efficient transfer.
+
+However, this approach faces significant challenges as the number of files and edits increases:
+1.  **Document Explosion:** A large vault can generate millions of chunk documents, severely degrading CouchDB's performance, particularly during view building and replication.
+2.  **Storage Bloat & GC Difficulty:** Obsolete chunks generated during edits are difficult to identify and remove. Since CouchDB's deletion (`_deleted: true`) is a soft delete, and compaction is a heavy, space-intensive operation, unused chunks perpetually consume storage, making GC impractical for many users.
+3.  **The "Eden" Problem:** A previous attempt, "Keep newborn chunks in Eden", aimed to mitigate this by embedding volatile chunks within the parent document. While it reduced the number of standalone chunks, it introduced a new issue: the parent document's history (`_revs_info`) became excessively large, causing its own form of database bloat and making compaction equally necessary but difficult to manage.
+
+This new design addresses the root cause—the sheer number of documents—by aggregating chunks into sets.
+
+## Prerequisites
+
+- The new implementation must maintain the core benefit of deduplication to ensure efficient synchronisation.
+- The solution must not introduce a single point of bottleneck and should handle concurrent writes from multiple clients gracefully.
+- The system must provide a clear and feasible strategy for Garbage Collection.
+- The design should be forward-compatible, allowing for a smooth migration path for existing users.
+
+## Outlined Methods and Implementation Plans
+
+### Abstract
+
+This design introduces a two-tiered document structure to manage chunks: **Index Documents** and **Data Documents**. Chunks are no longer stored as individual documents. Instead, they are grouped into `Data Documents` based on a common hash prefix. The existence and location of each chunk are tracked by `Index Documents`, which are also grouped by the same prefix. This approach dramatically reduces the total document count.
+
+### Detailed Implementation
+
+**1. Document Structure:**
+
+-   **Index Document:** Maps chunk hashes to their corresponding Data Document ID. Identified by a prefix of the chunk hash.
+    -   `_id`: `idx:{prefix}` (e.g., `idx:a9f1b`)
+    -   Content:
+        ```json
+        {
+            "_id": "idx:a9f1b",
+            "_rev": "...",
+            "chunks": {
+                "a9f1b12...": "dat:a9f1b-001",
+                "a9f1b34...": "dat:a9f1b-001",
+                "a9f1b56...": "dat:a9f1b-002"
+            }
+        }
+        ```
+-   **Data Document:** Contains the actual chunk data as base64-encoded strings. Identified by a prefix and a sequential number.
+    -   `_id`: `dat:{prefix}-{sequence}` (e.g., `dat:a9f1b-001`)
+    -   Content:
+        ```json
+        {
+            "_id": "dat:a9f1b-001",
+            "_rev": "...",
+            "chunks": {
+                "a9f1b12...": "...", // base64 data
+                "a9f1b34...": "..."  // base64 data
+            }
+        }
+        ```
+
+**2. Configuration:**
+
+-   `chunk_prefix_length`: The number of characters from the start of a chunk hash to use as a prefix (e.g., `5`). This determines the granularity of aggregation.
+-   `data_doc_size_limit`: The maximum size for a single Data Document to prevent it from becoming too large (e.g., 1MB). When this limit is reached, a new Data Document with an incremented sequence number is created.
+
+**3. Write/Save Operation Flow:**
+
+When a client creates new chunks:
+1.  For each new chunk, determine its hash prefix.
+2.  Read the corresponding `Index Document` (e.g., `idx:a9f1b`).
+3.  From the index, determine which of the new chunks already exist in the database.
+4.  For the **truly new chunks only**:
+    a. Read the last `Data Document` for that prefix (e.g., `dat:a9f1b-005`).
+    b. If it is nearing its size limit, create a new one (`dat:a9f1b-006`).
+    c. Add the new chunk data to the Data Document and save it.
+5.  Update the `Index Document` with the locations of the newly added chunks.
+
+**4. Handling Write Conflicts:**
+
+Concurrent writes to the same `Index Document` or `Data Document` from multiple clients will cause conflicts (409 Conflict). This is expected and must be handled gracefully. Since additions are incremental, the client application must implement a **retry-and-merge loop**:
+1.  Attempt to save the document.
+2.  On a conflict, re-fetch the latest version of the document from the server.
+3.  Merge its own changes into the latest version.
+4.  Attempt to save again.
+5.  Repeat until successful or a retry limit is reached.
+
+**5. Garbage Collection (GC):**
+
+GC becomes a manageable, periodic batch process:
+1.  Scan all file metadata documents to build a master set of all *currently referenced* chunk hashes.
+2.  Iterate through all `Index Documents`. For each chunk listed:
+    a. If the chunk hash is not in the master reference set, it is garbage.
+    b. Remove the garbage entry from the `Index Document`.
+    c. Remove the corresponding data from its `Data Document`.
+3.  If a `Data Document` becomes empty after this process, it can be deleted.
+
+## Test Strategy
+
+1.  **Unit Tests:** Implement tests for the conflict resolution logic (retry-and-merge loop) to ensure robustness.
+2.  **Integration Tests:**
+    -   Verify that concurrent writes from multiple simulated clients result in a consistent, merged state without data loss.
+    -   Run a full synchronisation scenario and confirm the resulting database has a significantly lower document count compared to the previous implementation.
+3.  **GC Test:** Simulate a scenario where files are deleted, run the GC process, and verify that orphaned chunks are correctly removed from both Index and Data documents, and that storage is reclaimed after compaction.
+4.  **Migration Test:** Develop and test a "rebuild" process for existing users, which migrates their chunk data into the new aggregated structure.
+
+## Documentation Strategy
+
+-   This design document will be published to explain the new architecture.
+-   The configuration options (`chunk_prefix_length`, etc.) will be documented for advanced users.
+-   A guide for the migration/rebuild process will be provided.
+
+## Future Work
+
+The separation of index and data opens up a powerful possibility. While this design initially implements both within CouchDB, the `Data Documents` could be offloaded to a dedicated object storage service such as **S3, MinIO, or Cloudflare R2**.
+
+In such a hybrid model, CouchDB would handle only the lightweight `Index Documents` and file metadata, serving as a high-speed synchronisation and coordination layer. The bulky chunk data would reside in a more cost-effective and scalable blob store. This would represent the ultimate evolution of this architecture, combining the best of both worlds.
+
+## Consideration and Conclusion
+
+This design directly addresses the scalability limitations of the original chunk-per-document model. By aggregating chunks into sets, it significantly reduces the document count, which in turn improves database performance and makes maintenance feasible. The explicit handling of write conflicts and a clear strategy for garbage collection make this a robust and sustainable long-term solution. It effectively resolves the problems identified in previous approaches, including the "Eden" experiment, by tackling the root cause of database bloat. This architecture provides a solid foundation for future growth and scalability.

docs/design_docs/chunk_retrieval_and_waiting.md

@@ -0,0 +1,118 @@
+# Chunk Retrieval and Waiting
+
+## Purpose
+
+This document records how LiveSync retrieves chunks after file metadata has been found, which operation provides each terminal condition, and what the remaining time value means. It is an implementation specification for developers; it is not a user configuration guide.
+
+The architectural decision and historical rationale are in [Chunk Arrival Quiescence](../adr/2026_07_chunk_arrival_quiescence.md).
+
+## Invariants and Sources of Apparent Reordering
+
+A normal local save creates and persists the chunks before it writes the metadata document which refers to them. LiveSync must preserve this invariant: publishing metadata first can expose a reference which no client can satisfy.
+
+This ordering is not an atomic transaction across documents. A reader may still see metadata before a referenced chunk for these reasons:
+
+- CouchDB replication transfers individual documents and does not expose the chunk and metadata writes as one atomic unit.
+- With `readChunksOnline` enabled, CouchDB pull replication deliberately excludes chunk documents. Seeing metadata first is then the intended design, and the chunk is fetched by identifier.
+- A winning metadata conflict revision may refer to chunks created by another revision or client which have not yet reached the local database.
+- Replication persists documents before every downstream change callback and file-reflection task has necessarily observed them.
+- Historical versions and removed transfer modes may have produced data which did not preserve the normal ordering invariant.
+
+Waiting may resolve temporary visibility and processing gaps only when a known operation can still deliver the chunk. It cannot repair a chunk which is absent from every available source.
+
+## Retrieval Capabilities
+
+Direct on-demand fetch is currently available only for CouchDB when `useOnlyLocalChunk` is false. This capability deliberately does not depend on `readChunksOnline`:
+
+- when `readChunksOnline` is true, direct fetch is the normal way to obtain a chunk omitted from pull replication; and
+- when `readChunksOnline` is false, direct fetch remains a recovery path if a normally replicated chunk is locally absent.
+
+MinIO's sequential replicator and P2P do not implement direct `fetchRemoteChunks` delivery through this path. Their chunks must arrive through a finite replication operation. A P2P pull or bidirectional synchronisation is such a producer. A push-only P2P request remains broad remote activity for Wake Lock and lifecycle reporting, but it is deliberately excluded from `finiteReplicationActivityCount` because it cannot deliver a local document.
+
+`waitForReady` is a call-site policy, not a persisted user setting. `true` permits waiting for an already-observable producer. `false` normally requests an immediate local result, except that CouchDB on-demand delivery still waits for the claim which synchronous dispatch creates.
+
+## Policy Matrix
+
+The matrix selects whether lifecycle waiting is permitted and whether the waiter may dispatch a direct request. It does not assign elapsed arrival budgets.
+
+| Remote  | `waitForReady` | `useOnlyLocalChunk` | Direct fetch | Wait for observed producer | Intended behaviour                                                                      |
+| ------- | -------------: | ------------------: | -----------: | -------------------------: | --------------------------------------------------------------------------------------- |
+| CouchDB |        `false` |             `false` |          Yes |                        Yes | Dispatch on-demand fetch and finish at its per-identifier claim boundary.               |
+| CouchDB |         `true` |             `false` |          Yes |                        Yes | Accept an active finite replication or dispatch direct fetch.                           |
+| CouchDB |        `false` |              `true` |           No |                         No | Return immediately after the local miss.                                                |
+| CouchDB |         `true` |              `true` |           No |                        Yes | Wait for an already-active finite replication; otherwise return unavailable.            |
+| MinIO   |        `false` |              Either |           No |                         No | Return immediately after the local miss.                                                |
+| MinIO   |         `true` |              Either |           No |                        Yes | Wait for an already-active finite sequential replication; otherwise return unavailable. |
+| P2P     |        `false` |              Either |           No |                         No | Return immediately after the local miss.                                                |
+| P2P     |         `true` |              Either |           No |                        Yes | Wait for an already-active finite P2P replication; otherwise return unavailable.        |
+
+For CouchDB, `readChunksOnline` changes what normal replication includes, not the direct-fetch capability or this matrix:
+
+| `readChunksOnline` | CouchDB pull contains chunks | Role of direct fetch                                                     |
+| -----------------: | ---------------------------: | ------------------------------------------------------------------------ |
+|             `true` |                           No | Primary chunk delivery after metadata arrives.                           |
+|            `false` |                          Yes | Recovery fallback for a chunk which is unexpectedly unavailable locally. |
+
+`concurrencyOfReadChunksOnline` and `minimumIntervalOfReadChunksOnline` affect only the scheduling of CouchDB on-demand requests. They do not change whether a request may be dispatched or which lifecycle a reader observes. Accepted identifiers remain claimed while they wait for a concurrency slot and while the configured interval is applied. A minimum interval of five minutes or more is an exceptional value: the inactivity fuse may release the logical claim before that deliberate pause completes. This safety precedence does not abort the delayed physical request.
+
+## Wait State Machine
+
+1. Read the cache and local database.
+2. If every requested chunk is present, return it without entering a wait.
+3. Register one shared waiter per missing identifier.
+4. If policy permits direct fetch, emit `missingChunks`. `ChunkFetcher` synchronously creates the per-identifier claim before the event dispatch returns.
+5. Observe both the matching claim and `finiteReplicationActivityCount`.
+6. Resolve immediately if a valid chunk or explicit remote-missing event arrives.
+7. If an observed producer remains active, do not charge elapsed time against an arrival budget.
+8. When all observed producers end, bypass the cache and read the identifiers from the local database once.
+9. Return the rechecked chunk, or return unavailable. Do not add another fixed grace after the authoritative boundary.
+10. If no producer is observable after synchronous dispatch, return unavailable immediately.
+
+If new relevant activity starts while the final database recheck is pending, that result becomes stale. The waiter remains active until the newer producer completes and a current recheck finishes.
+
+## Meaning of Finite Replication Completion
+
+Finite replication enters the typed `runFiniteReplicationActivity` boundary and is represented by the narrower `finiteReplicationActivityCount`. The optional `replication` label remains diagnostic and does not control this behaviour.
+
+For a successful finite operation, completion means that its replicator has reached the latest sequence in the operation's scope and processed its replication change callbacks. No more database documents can arrive from that operation. This is the primary semantic cutoff.
+
+If the operation fails, it has not proved remote absence or latest state. It has nevertheless stopped being a producer. The waiting layer rechecks documents which may have arrived before the failure and then returns unavailable; the replication error and retry workflow owns further recovery.
+
+Overlapping finite replications keep the count above zero until the final operation settles. The local recheck therefore occurs only after every observed finite producer is quiescent.
+
+The continuous live channel is intentionally excluded because it has no completion boundary and would otherwise make a chunk read unbounded. The pull-only catch-up run before opening that channel is finite and enters the same typed boundary. Its one-shot batch-size fallback remains inside that boundary. A live-channel fallback starts another continuous attempt and therefore another bounded initial catch-up.
+
+## Meaning of an On-demand Claim
+
+An accepted identifier remains claimed from synchronous queue acceptance through throttling, physical fetch, validation, local persistence, and terminal event delivery. The claim is identifier-scoped because a global remote-work count cannot say whether unrelated work can provide this chunk.
+
+The claim finishes when the fetcher has recorded an outcome for the identifier. A transport error, missing active replicator, or invalid result releases the claim without emitting an explicit remote-missing result unless the remote actually supplied that information.
+
+## Meaning of the Five-minute Value
+
+The five-minute value is an inactivity leak fuse for an accepted on-demand claim. It is the only elapsed duration in this state machine, and it is not a normal terminal condition.
+
+The fuse bounds retention if a faulty activity runner never enters its task, a Promise never settles, or a transport stops making observable progress. It prevents the per-identifier claim and waiter from remaining live forever. Once the bounded activity callback has entered, releasing the claim also allows Wake Lock, application-lifecycle deferral, and the remote-work indicator associated with that callback to finish. Observable progress rearms the fuse.
+
+Five minutes is a conservative operational ceiling rather than a measured chunk-arrival expectation. It must not be used to infer that the remote lacks a chunk, and it does not abort the physical request. `fetchRemoteChunks` does not yet accept an `AbortSignal`, so the request may complete after the logical state has been released. Transport cancellation and transport-specific deadlines are separate future work.
+
+The old 5-second and 30-second constants remain exported for source compatibility only. A positive deprecated `ChunkReadOptions.timeout` opts into lifecycle waiting, but its numeric value is ignored. Zero or a negative value still requests an immediate result. New code uses `waitForDelivery` explicitly.
+
+## Test Obligations
+
+Changes to this behaviour must keep automated coverage for:
+
+- chunks-before-metadata save ordering;
+- every row in the retrieval policy matrix;
+- a finite replication which remains active well beyond the former 5-second and 30-second values;
+- successful completion with the chunk already persisted but no arrival event delivered;
+- immediate unavailability when no producer is observable;
+- overlapping finite operations and overlapping per-identifier claims;
+- activity restarting while a local recheck is pending;
+- direct fetch queueing, throttling, persistence, and terminal notification;
+- explicit remote absence versus transport or replicator failure;
+- runner rejection, cancellation, teardown, and an operation which never enters its task;
+- leak-fuse refresh at observable progress points; and
+- continuous replication's finite initial catch-up and parameter fallback.
+
+The service, database, and event boundaries are testable with memory-backed PouchDB and injected activity sources. A real Obsidian test is required only when a change crosses into the platform adapter, application lifecycle, or visible UI rather than for this retrieval state machine alone.

docs/design_docs/intention_of_chunks.md

@@ -0,0 +1,127 @@
+# [WIP] The design intent explanation for using metadata and chunks
+
+## Abstract
+
+## Goal
+
+- To explain the following:
+  - What metadata and chunks are
+  - The design intent of using metadata and chunks
+
+## Background and Motivation
+
+We are using PouchDB and CouchDB for storing files and synchronising them. PouchDB is a JavaScript database that stores data on the device (browser, and of course, Obsidian), while CouchDB is a NoSQL database that stores data on the server. The two databases can be synchronised to keep data consistent across devices via the CouchDB replication protocol. This is a powerful and flexible way to store and synchronise data, including conflict management, but it is not well suited for files. Therefore, we needed to manage how to store files and synchronise them.
+
+## Terminology
+
+- Password:
+  - A string used to authenticate the user.
+
+- Passphrase:
+  - A string used to encrypt and decrypt data.
+  - This is not a password.
+
+- Encrypt:
+  - To convert data into a format that is unreadable to anyone.
+  - Can be decrypted by the user who has the passphrase.
+  - Should be 1:n, containing random data to ensure that even the same data, when encrypted, results in different outputs.
+
+- Obfuscate:
+  - To convert data into a format that is not easily readable.
+  - Can be decrypted by the user who has the passphrase.
+  - Should be 1:1, containing no random data, and the same data is always obfuscated to the same result. It is necessarily unreadable.
+
+- Hash:
+  - To convert data into a fixed-length string that is not easily readable.
+  - Cannot be decrypted.
+  - Should be 1:1, containing no random data, and the same data is always hashed to the same result.
+
+## Designs
+
+### Principles
+
+- To synchronise and handle conflicts, we should keep the history of modifications.
+- No data should be lost. Even though some extra data may be stored, it should be removed later, safely.
+- Each stored data item should be as small as possible to transfer efficiently, but not so small as to be inefficient.
+- Any type of file should be supported, including binary files.
+- Encryption should be supported efficiently.
+- This method should not depart too far from the PouchDB/CouchDB philosophy. It needs to leave room for other `remote`s, to benefit from custom replicators.
+
+As a result, we have adopted the following design.
+
+- Files are stored as one metadata entry and multiple chunks.
+- Chunks are content-addressable, and the metadata contains the ids of the chunks.
+- Chunks may be referenced from multiple metadata entries. They should be efficiently managed to avoid redundancy.
+
+### Metadata Design
+
+The metadata contains the following information:
+
+| Field    | Type                 | Description                  | Note                                                                                                  |
+| -------- | -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| _id      | string               | The id of the metadata       | It is created from the file path                                                                      |
+| _rev     | string               | The revision of the metadata | It is created by PouchDB                                                                              |
+| children | [string]             | The ids of the chunks        |                                                                                                       |
+| path     | string               | The path of the file         | If Obfuscate path has been enabled, it has been encrypted                                             |
+| size     | number               | The size of the metadata     | Not respected; for troubleshooting                                                                    |
+| ctime    | string               | The creation timestamp       | This is not used to compare files, but when writing to storage, it will be used                       |
+| mtime    | string               | The modification timestamp   | This will be used to compare files, and will be written to storage                                    |
+| type     | `plain` \| `newnote` | The type of the file         | Children of type `plain` will not be base64 encoded, while `newnote` will be                          |
+| e_       | boolean              | The file is encrypted        | Encryption is processed during transfer to the remote. In local storage, this property does not exist |
+
+#### Decision Rule for `_id` of Metadata
+
+```ts
+// Note: This is pseudo code.
+let _id = PATH;
+if (!HANDLE_FILES_AS_CASE_SENSITIVE) {
+  _id = _id.toLowerCase();
+}
+if (_id.startsWith("_")) {
+  _id = "/" + _id;
+}
+if (OBFUSCATE_PATH) {
+  _id = `f:${OBFUSCATE_PATH(_id, E2EE_PASSPHRASE)}`;
+}
+return _id;
+```
+
+#### Expected Questions
+
+- Why do we need to handle files as case-sensitive?
+  - Some filesystems are case-sensitive, while others are not. For example, Windows is not case-sensitive, while Linux is. Therefore, we need to handle files as case-sensitive to manage conflicts.
+  - The trade-off is that you will not be able to manage files with different cases, so this can be disabled if you only have case-sensitive terminals.
+- Why obfuscate the path?
+  - E2EE only encrypts the content of the file, not metadata. Hence, E2EE alone is not enough to protect the vault completely. The path is also part of the metadata, so it should be obfuscated. This is a trade-off between security and performance. However, if you title a note with sensitive information, you should obfuscate the path.
+- What is `f:`?
+  - It is a prefix to indicate that the path is obfuscated. It is used to distinguish between normal paths and obfuscated paths. Due to file enumeration, Self-hosted LiveSync should scan the files to find the metadata, excluding chunks and other information.
+  - Why does an unobfuscated path not start with `f:`?
+  - For compatibility. Self-hosted LiveSync, by its nature, must also be able to handle files created with newer versions as far as possible.
+
+### Chunk Design
+
+#### Chunk Structure
+
+The chunk contains the following information:
+
+| Field | Type         | Description               | Note                                                                                                  |
+| ----- | ------------ | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| _id   | `h:{string}` | The id of the chunk       | It is created from the hash of the chunk content                                                      |
+| _rev  | string       | The revision of the chunk | It is created by PouchDB                                                                              |
+| data  | string       | The content of the chunk  |                                                                                                       |
+| type  | `leaf`       | Fixed                     |                                                                                                       |
+| e_    | boolean      | The chunk is encrypted    | Encryption is processed during transfer to the remote. In local storage, this property does not exist |
+
+**SORRY, TO BE WRITTEN, BUT WE HAVE IMPLEMENTED `v2`, WHICH REQUIRES MORE INFORMATION.**
+
+### How they are unified
+
+## Deduplication and Optimisation
+
+## Synchronisation Strategy
+
+## Performance Considerations
+
+## Security and Privacy
+
+## Edge Cases

docs/design_docs/tired_chunk_pack.md

@@ -0,0 +1,117 @@
+# [IN DESIGN] Tiered Chunk Storage with Live Compaction
+
+** VERY IMPORTANT NOTE: This design must be used with the new journal synchronisation method. Otherwise, we risk introducing the bloat of changes from hot-pack into the Bucket. (CouchDB/PouchDB can synchronise only the most recent changes, or resolve conflicts.) Previous Journal Sync **IS NOT**. Please proceed with caution. **
+
+## Goal
+
+To establish a highly efficient, robust, and scalable synchronisation architecture by introducing a tiered storage system inspired by Log-Structured Merge-Trees (LSM-Trees). This design aims to address the challenges of real-time synchronisation, specifically the massive generation of transient data, while minimising storage bloat and ensuring high performance.
+
+## Motivation
+
+Our previous designs, including "Chunk Aggregation by Prefix", successfully addressed the "document explosion" problem. However, the introduction of real-time editor synchronisation exposed a new, critical challenge: the constant generation of short-lived "garbage" chunks during user input. This "garbage storm" places immense pressure on storage, I/O, and the Garbage Collection (GC) process.
+
+A simple aggregation strategy is insufficient because it treats all data equally, mixing valuable, stable chunks with transient, garbage chunks in permanent storage. This leads to storage bloat and inefficient compaction. We require a system that can intelligently distinguish between "hot" (volatile) and "cold" (stable) data, processing them in the most efficient manner possible.
+
+## Outlined Methods and Implementation Plans
+
+### Abstract
+
+This design implements a two-tiered storage system within CouchDB.
+1.  **Level 0 – Hot Storage:** A set of "Hot-Packs", one for each active client. These act as fast, append-only logs for all newly created chunks. They serve as a temporary staging area, absorbing the "garbage storm" of real-time editing.
+2.  **Level 1 – Cold Storage:** The permanent, immutable storage for stable chunks, consisting of **Index Documents** for fast lookups and **Data Documents (Cold-Packs)** for storing chunk data.
+
+A background "Compaction" process continuously promotes stable chunks from Hot Storage to Cold Storage, while automatically discarding garbage. This keeps the permanent storage clean and highly optimised.
+
+### Detailed Implementation
+
+**1. Document Structure:**
+
+-   **Hot-Pack Document (Level 0):** A per-client, append-only log.
+  -   `_id`: `hotpack:{client_id}` (`client_id` could be the same as the `deviceNodeID` used in the `accepted_nodes` in MILESTONE_DOC; enables database 'lockout' for safe synchronisation)
+  -   Content: A log of chunk creation events.
+    ```json
+    {
+      "_id": "hotpack:a9f1b12...",
+      "_rev": "...",
+      "log": [
+      { "hash": "abc...", "data": "...", "ts": ..., "file_id": "file1" },
+      { "hash": "def...", "data": "...", "ts": ..., "file_id": "file2" }
+      ]
+    }
+    ```
+
+-   **Index Document (Level 1):** A fast, prefix-based lookup table for stable chunks.
+  -   `_id`: `idx:{prefix}` (e.g., `idx:a9f1b`)
+  -   Content: Maps a chunk hash to the ID of the Cold-Pack it resides in.
+    ```json
+    {
+      "_id": "idx:a9f1b",
+      "chunks": { "a9f1b12...": "dat:1678886400" }
+    }
+    ```
+
+-   **Cold-Pack Document (Level 1):** An immutable data block created by the compaction process.
+  -   `_id`: `dat:{timestamp_or_uuid}` (e.g., `dat:1678886400123`)
+  -   Content: A collection of stable chunks.
+    ```json
+    {
+      "_id": "dat:1678886400123",
+      "chunks": { "a9f1b12...": "...", "c3d4e5f...": "..." }
+    }
+    ```
+
+-   **Hot-Pack List Document:** A central registry of all active Hot-Packs. This might be a computed document that clients maintain in memory on startup.
+  -   `_id`: `hotpack_list`
+  -   Content: `{"active_clients": ["hotpack:a9f1b12...", "hotpack:c3d4e5f..."]}`
+
+**2. Write/Save Operation Flow (Real-time Editing):**
+
+1.  A client generates a new chunk.
+2.  It **immediately appends** the chunk object (`{hash, data, ts, file_id}`) to its **own** Hot-Pack document's `log` array within its local PouchDB. This operation is extremely fast.
+3.  The PouchDB synchronisation process replicates this change to the remote CouchDB and other clients in the background. No other Hot-Packs are consulted during this write operation.
+
+**3. Read/Load Operation Flow:**
+
+To find a chunk's data:
+1.  The client first consults its in-memory list of active Hot-Pack IDs (see section 5).
+2.  It searches for the chunk hash in all **Hot-Pack documents**, starting from its own, then others. It reads them in reverse log order (newest first).
+3.  If not found, it consults the appropriate **Index Document (`idx:...`)** to get the ID of the Cold-Pack.
+4.  It then reads the chunk data from the corresponding **Cold-Pack document (`dat:...`)**.
+
+**4. Compaction & Promotion Process (The "GC"):**
+
+This is a background task run periodically by clients, or triggered when the number of unprocessed log entries exceeds a threshold (to maintain the ability to synchronise with the remote database, which has a limited document size).
+1.  The client takes its own Hot-Pack (`hotpack:{client_id}`) and scans its `log` array from the beginning (oldest first).
+2.  For each chunk in the log, it checks if the chunk is still referenced in the latest revision of any file.
+  -   **If not referenced (Garbage):** The log entry is simply discarded.
+  -   **If referenced (Stable):** The chunk is added to a "promotion batch".
+3.  After scanning a certain number of log entries, the client takes the "promotion batch".
+4.  It creates one or more new, immutable **Cold-Pack (`dat:...`)** documents to store the chunk data from the batch.
+5.  It updates the corresponding **Index (`idx:...`)** documents to point to the new Cold-Pack(s).
+6.  Once the promotion is successfully saved to the database, it **removes the processed entries from its Hot-Pack's `log` array**. This is a critical step to prevent reprocessing and keep the Hot-Pack small.
+
+**5. Hot-Pack List Management:**
+
+To know which Hot-Packs to read, clients will:
+1.  On startup, load the `hotpack_list` document into memory.
+2.  Use PouchDB's live `changes` feed to monitor the creation of new `hotpack:*` documents.
+3.  Upon detecting an unknown Hot-Pack, the client updates its in-memory list and attempts to update the central `hotpack_list` document (on a best-effort basis, with conflict resolution).
+
+## Planned Test Strategy
+
+1.  **Unit Tests:** Test the Compaction/Promotion logic extensively. Ensure garbage is correctly identified and stable chunks are promoted correctly.
+2.  **Integration Tests:** Simulate a multi-client real-time editing session.
+  -   Verify that writes are fast and responsive.
+  -   Confirm that transient garbage chunks do not pollute the Cold Storage.
+  -   Confirm that after a period of inactivity, compaction runs and the Hot-Packs shrink.
+3.  **Stress Tests:** Simulate many clients joining and leaving to test the robustness of the `hotpack_list` management.
+
+## Documentation Strategy
+
+-   This design document will serve as the core architectural reference.
+-   The roles of each document type (Hot-Pack, Index, Cold-Pack, List) will be clearly explained for future developers.
+-   The logic of the Compaction/Promotion process will be detailed.
+
+## Consideration and Conclusion
+
+This tiered storage design is a direct evolution, born from the lessons of previous architectures. It embraces the ephemeral nature of data in real-time applications. By creating a "staging area" (Hot-Packs) for volatile data, it protects the integrity and performance of the permanent "cold" storage. The Compaction process acts as a self-cleaning mechanism, ensuring that only valuable, stable data is retained long-term. This is not just an optimisation; it is a fundamental shift that enables robust, high-performance, and scalable real-time synchronisation on top of CouchDB.

docs/design_docs/tired_chunk_pack_bucket.md

@@ -0,0 +1,97 @@
+# [IN DESIGN] Tiered Chunk Storage for Bucket Sync
+
+## Goal
+
+To evolve the "Journal Sync" mechanism by integrating the Tiered Storage architecture. This design aims to drastically reduce the size and number of sync packs, minimise storage consumption on the backend bucket, and establish a clear, efficient process for Garbage Collection, all while remaining protocol-agnostic.
+
+## Motivation
+
+The original "Journal Sync" liberates us from CouchDB's protocol, but it still packages and transfers entire document changes, including bulky and often transient chunk data. In a real-time or frequent-editing scenario, this results in:
+1.  **Bloated Sync Packs:** Packs become large with redundant or short-lived chunk data, increasing upload and download times.
+2.  **Inefficient Storage:** The backend bucket stores numerous packs containing overlapping and obsolete chunk data, wasting space.
+3.  **Impractical Garbage Collection:** Identifying and purging obsolete *chunk data* from within the pack-based journal history is extremely difficult.
+
+This new design addresses these problems by fundamentally changing *what* is synchronised in the journal packs. We will synchronise lightweight metadata and logs, while handling bulk data separately.
+
+## Outlined methods and implementation plans
+
+### Abstract
+
+This design adapts the Tiered Storage model for a bucket-based backend. The backend bucket is partitioned into distinct areas for different data types. The "Journal Sync" process is now responsible for synchronising only the "hot" volatile data and lightweight metadata. A separate, asynchronous "Compaction" process, which can be run by any client, is responsible for migrating stable data into permanent, deduplicated "cold" storage.
+
+### Detailed Implementation
+
+**1. Bucket Structure:**
+
+The backend bucket will have four distinct logical areas (prefixes):
+-   `packs/`: For "Journal Sync" packs, containing the journal of metadata and Hot-Log changes.
+-   `hot_logs/`: A dedicated area for each client's "Hot-Log," containing newly created, volatile chunks.
+-   `indices/`: For prefix-based Index files, mapping chunk hashes to their permanent location in Cold Storage.
+-   `cold_chunks/`: For deduplicated, stable chunk data, stored by content hash.
+
+**2. Data Structures (Client-side PouchDB & Backend Bucket):**
+
+-   **Client Metadata:** Standard file metadata documents, kept in the client's PouchDB.
+-   **Hot-Log (in `hot_logs/`):** A per-client, append-only log file on the bucket.
+    -   Path: `hot_logs/{client_id}.jsonlog`
+    -   Content: A sequence of JSON objects, one per line, representing chunk creation events. `{"hash": "...", "data": "...", "ts": ..., "file_id": "..."}`
+
+-   **Index File (in `indices/`):** A JSON file for a given hash prefix.
+    -   Path: `indices/{prefix}.json`
+    -   Content: Maps a chunk hash to its content hash (which is its key in `cold_chunks/`). `{"hash_abc...": true, "hash_def...": true}`
+
+-   **Cold Chunk (in `cold_chunks/`):** The raw, immutable, deduplicated chunk data.
+    -   Path: `cold_chunks/{chunk_hash}`
+
+**3. "Journal Sync" - Send/Receive Operation (Not Live):**
+
+This process is now extremely lightweight.
+1.  **Send:**
+    a. The client takes all newly generated chunks and **appends them to its own Hot-Log file (`hot_logs/{client_id}.jsonlog`)** on the bucket.
+    b. The client updates its local file metadata in PouchDB.
+    c. It then creates a "Journal Sync" pack containing **only the PouchDB journal of the file metadata changes.** This pack is very small as it contains no chunk data.
+    d. The pack is uploaded to `packs/`.
+
+2.  **Receive:**
+    a. The client downloads new packs from `packs/` and applies the metadata journal to its local PouchDB.
+    b. It downloads the latest versions of all **other clients' Hot-Log files** from `hot_logs/`.
+    c. Now the client has a complete, up-to-date view of all metadata and all "hot" chunks.
+
+**4. Read/Load Operation Flow:**
+
+To find a chunk's data:
+1.  The client searches for the chunk hash in its local copy of all **Hot-Logs**.
+2.  If not found, it downloads and consults the appropriate **Index file (`indices/{prefix}.json`)**.
+3.  If the index confirms existence, it downloads the data from **`cold_chunks/{chunk_hash}`**.
+
+**5. Compaction & Promotion Process (Asynchronous "GC"):**
+
+This is a deliberate, offline-capable process that any client can choose to run.
+1.  The client "leases" its own Hot-Log for compaction.
+2.  It reads its entire `hot_logs/{client_id}.jsonlog`.
+3.  For each chunk in the log, it checks if the chunk is referenced in the *current, latest state* of the file metadata.
+    -   **If not referenced (Garbage):** The log entry is discarded.
+    -   **If referenced (Stable):** The chunk is added to a "promotion batch."
+4.  For each chunk in the promotion batch:
+    a. It checks the corresponding `indices/{prefix}.json` to see if the chunk already exists in Cold Storage.
+    b. If it does not exist, it **uploads the chunk data to `cold_chunks/{chunk_hash}`** and updates the `indices/{prefix}.json` file.
+5.  Once the entire Hot-Log has been processed, the client **deletes its `hot_logs/{client_id}.jsonlog` file** (or truncates it to empty), effectively completing the cycle.
+
+## Test strategy
+
+1.  **Component Tests:** Test the Compaction process independently. Ensure it correctly identifies stable versus garbage chunks and populates the `cold_chunks/` and `indices/` areas correctly.
+2.  **Integration Tests:**
+    -   Simulate a multi-client sync cycle. Verify that sync packs in `packs/` are small.
+    -   Confirm that `hot_logs/` are correctly created and updated.
+    -   Run the Compaction process and verify that data migrates correctly to cold storage and the hot log is cleared.
+3.  **Conflict Tests:** Simulate two clients trying to compact the same index file simultaneously and ensure the outcome is consistent (for example, via a locking mechanism or last-write-wins).
+
+## Documentation strategy
+
+-   This design document will be the primary reference for the bucket-based architecture.
+-   The structure of the backend bucket (`packs/`, `hot_logs/`, etc.) will be clearly defined.
+-   A detailed description of how to run the Compaction process will be provided to users.
+
+## Consideration and Conclusion
+
+By applying the Tiered Storage model to "Journal Sync", we transform it into a remarkably efficient system. The synchronisation of everyday changes becomes extremely fast and lightweight, as only metadata journals are exchanged. The heavy lifting of data deduplication and permanent storage is offloaded to a separate, asynchronous Compaction process. This clear separation of concerns makes the system highly scalable, minimises storage costs, and finally provides a practical, robust solution for Garbage Collection in a protocol-agnostic, bucket-based environment.

docs/design_docs_of_journalsync.md

@@ -0,0 +1,50 @@
+## The design document of the journal sync
+
+Original title: Synchronise without CouchDB 
+
+### Goal
+- Synchronise vaults without CouchDB 
+
+### Motivation 
+- Serving CouchDB is not pretty easy. 
+- Full spec DBaaS (Paid IBM Cloudant) is a bit expensive and lacking of alternatives. 
+- Securing alternatives, from just one protocol.
+
+### Prerequisite
+- We should have multiple implementations of the server software. 
+- We should also be able to use SaaS, with a choice of options.
+	- We should require them a reasonable sense of cost, ideally free of charge for trials. 
+- We should be able to serve some instance of the server software, as OSS — with transparency, availability of auditing, and the fact that they actually took place.
+
+### Methods and implementations
+
+Ordinarily, local pouchDB and the remote CouchDB are synchronised by sending each missing document through several conversations in their replication protocol. However, to achieve this plan, we cannot rely on CouchDB and its protocols. This limitation is so harsh. However, Overcoming this means gaining new possibilities. After some trials, It was concluded that synchronisation could be completed even if the actions that could be performed were limited to uploading, downloading, and retrieving the list. This means we can use any old-fashioned WebDAV server, and sophisticated 'object storages' such as Self-hosted MinIO, S3, and R2, or any we like. This is realised by sharing and complementing the differences of the journal by each client. Therefore, The focus is therefore on how to identify which are the differences and send them without dynamic communication.
+
+All clients manage their data in PouchDB. I know this is probably known information, but it has its own journal. 
+
+First, all clients should record to what point in the journal they sent themselves last time. The client then packs from the previous point to the latest when sending and also updates their record. This pack is uploaded to the server with the name starting with the timestamp of its creation. This is the send operation. 
+
+Conversely, when receiving, the packs uploaded to the server that have not yet been received are received in order. This is easy as their names are in date order. When the process is successfully completed, the names of the files received are recorded. The journals from this pack are then reflected in their own database. Conflict resolution is left to PouchDB, so the client only needs to do the work of applying any differences. And here is the key: the client records the ID and revision of the document that was in the journal and applied.
+
+This key works when creating a pack. When creating a pack, the client omits this 'document recorded as received and used'. This is because received and applied means that it has already been sent by another client and exists on the server. This ensures that unnecessary transmissions do not take place.
+
+Synchronisation is then always started by receiving. This is a little trick to avoid including unnecessary documents in the pack.
+
+These behaviours allow clients to voluntarily send and receive only the missing parts of the journal that are not stored on the server, without having to communicate with each other, and still keep a single, consistent journal on the server.
+
+Source codes actually implemented this is already committed into the repository. 
+
+### Test strategy
+
+This implementation replaces the synchronisation performed by CouchDB. Therefore, testing was simply done by comparing the same changes to the same vault, replicated in CouchDB, with those done by this implementation.
+
+### Documentation strategy
+
+- Documentation should be done in a quick setup, at least.
+- As several server implementations can be selected, the description is omitted with regard to specific configuration values.
+- A MinIO set-up might be nice to have. However, it is not considered essential.
+- It would be a good opportunity to also publish these design documents.
+
+### Consideration and Conclusion
+
+This design offers a novel approach to journal synchronisation without relying on CouchDB. It leverages PouchDB's journaling capabilities and leverages simple server-side storage for efficient data exchange. Hence, the new design could be said to have gotten a broader outlook.

docs/design_docs_of_journalsync_2nd.md

@@ -0,0 +1,94 @@
+## The design document of the Journal Replicator 2nd Edition
+
+### Goal
+- Build a robust and memory-efficient replication foundation that decouples the physical storage layer by leveraging the Web Streams API.
+- Maintain strict compliance with the data consistency and replication protocols of CouchDB/PouchDB.
+- Introduce the `IJournalStorage` abstraction to ensure easy extensibility. This allows the core to seamlessly interact with Object Storages (MinIO, S3, R2, etc.) while opening the door for entirely new Storage Engines and Mocks for testing.
+
+### Motivation
+- The original Journal Replicator used a custom queue mechanism called `Trench` to manage backpressure, which had limitations regarding memory efficiency when dealing with a massive number of files.
+- The storage operation logic was tightly coupled with `JournalSyncAbstract`, making it difficult to swap out the physical storage layer (e.g., S3 and WebDAV).
+- The transfer of revision trees (`_revisions`) conforming to PouchDB's replication protocol was implicitly managed. There was a need for a stricter, more deterministic application of document histories.
+
+### Differences from v1 (Original)
+
+The overall architecture and mechanisms have been drastically modernised from the first version. Here are the key differences:
+
+| Feature / Mechanism | v1 (Original) | v2 (2nd Edition) | Key Benefits in v2 |
+| :--- | :--- | :--- | :--- |
+| **Backpressure / Queueing** | Custom `Trench` mechanism | Native **Web Streams API** | Prevents memory exhaustion during massive transfers; extremely stable sustained throughput. |
+| **Storage Architecture** | Tightly coupled in `JournalSyncAbstract` | Abstracted via **`IJournalStorage`** | Easy to plug in new Storage Engines (WebDAV, etc.) and testing Mocks without altering the core logic. |
+| **Document Application** | Sometimes evaluated as new local edits | Strict `bulkDocs` with **`new_edits: false`** | Drastically faster insertions; prevents redundant conflict branches and "echo" network traffic. |
+
+#### Class Structure Changes (Diff from v1)
+
+Looking at the Git diff from the `main` branch, the class structure has undergone a significant refactoring to achieve the aforementioned decoupling:
+
+- **`JournalSyncAbstract.ts` -> `JournalSyncCore.ts`**: The core logic was renamed. Instead of being an abstract base class for specific storages, it is now a concrete core class that manages the Web Streams API pipelines.
+- **`JournalSyncMinio.ts` -> `MinioStorageAdapter.ts`**: The MinIO-specific implementation was decoupled from the core logic and converted into a dedicated storage adapter.
+- **`IJournalStorage` (New)**: Introduced in `JournalStorageAdapter.ts` to define the interface that all storage adapters must implement.
+
+### Methods and implementations
+
+#### Pipeline Construction using Web Streams API
+We replaced `Trench` with standard Web Streams APIs (`ReadableStream`, `TransformStream`, and `WritableStream`) to build the sending and receiving pipelines.
+- **Sending Pipeline**: Reads documents from the PouchDB changes stream, passes them through a compression `TransformStream`, and pipes them to an upload `WritableStream`. This enables automatic backpressure, keeping memory consumption stable even during large-scale synchronisation.
+- **Receiving Pipeline**: Processes storage file listing, downloading/decompression, and bulk application to PouchDB in a streamlined manner.
+
+#### Decoupling the Physical Layer via IJournalStorage
+To detach the storage operations from the core synchronisation logic (`JournalSyncCore`), we introduced the `IJournalStorage` interface.
+This ensures extensibility not only to Object Storages (MinIO, S3, R2, etc., handled via `MinioStorageAdapter` and Connection Strings) but also to entirely new Storage Engines (e.g., WebDAV, Google Drive) and Mocks for testing. When adding a new backend, developers only need to add an Adapter that implements this interface, without modifying the core replicator.
+
+```mermaid
+classDiagram
+    class LiveSyncAbstractReplicator {
+        <<abstract>>
+    }
+    class LiveSyncJournalReplicator {
+        +setupJournalSyncClient()
+    }
+    class JournalSyncCore {
+        -IJournalStorage storage
+        +sendLocalJournal()
+        +receiveRemoteJournal()
+    }
+    class IJournalStorage {
+        <<interface>>
+        +upload()
+        +download()
+    }
+    class MinioStorageAdapter {
+        +upload()
+        +download()
+    }
+
+    LiveSyncAbstractReplicator <|-- LiveSyncJournalReplicator : Extends
+    LiveSyncJournalReplicator *-- JournalSyncCore : Instantiates & delegates
+    LiveSyncJournalReplicator ..> MinioStorageAdapter : Creates
+    JournalSyncCore --> IJournalStorage : Uses for backend I/O
+    IJournalStorage <|.. MinioStorageAdapter : Implements
+```
+
+#### Strict Application of PouchDB Replication Protocols
+To synchronise precisely according to the CouchDB/PouchDB protocol, the following steps were optimised:
+1. **Transferring History**: Using `bulkGet({ revs: true })`, the replicator transfers not only the latest revision of a document but its entire history tree (`_revisions`) alongside the deletion flag (`_deleted`).
+2. **Applying History**: On the receiving end, the replicator uses `revsDiff` to identify which incoming revisions are missing locally. It then applies them using `bulkDocs(saveDocs, { new_edits: false })`.
+By specifying `new_edits: false`, PouchDB integrates the received history exactly as it is without treating them as new local edits. This prevents unexpected conflicts and redundant branching of the revision tree.
+
+
+### Performance and Speed Characteristics
+
+By migrating from the previous `Trench` architecture to the Web Streams API and strict PouchDB protocol compliance, the replication speed characteristics have changed in the following ways:
+
+1. **On-Demand Generation and Consistent Throughput**:
+   In the previous `Trench` architecture, the system would eagerly generate or download all 'Changes' in bulk before processing them. This batch processing became a significant bottleneck and caused massive memory spikes (Even though, some of them have been stored into the idb temporally). The Web Streams API fundamentally shifts this to **on-demand (lazy) generation**. Data is pulled and processed only as much as the next pipeline stage (Compress -> Upload/Write) can handle. While this on-demand approach might appear slightly slower in terms of peak burst speed compared to in-memory batching, it completely eliminates the 'create-everything-at-once' bottleneck. This makes the **sustained throughput far more stable** and prevents out-of-memory crashes on mobile devices.
+
+2. **Faster Receive-Side Application (`new_edits: false`)**:
+   In the previous version, incoming documents were sometimes evaluated as new local edits. By utilising PouchDB's `bulkDocs({ new_edits: false })` alongside the proper `_revisions` tree, we bypass unnecessary conflict generation and local revision hashing. This drastically **speeds up the document insertion process** on the receiving end.
+
+3. **Optimised Network Traffic**:
+   Because conflicts are resolved deterministically and revision trees are replicated exactly as they exist, the system avoids generating 'echoes' (redundant synchronisations triggered by a device misunderstanding a history tree). This reduces unnecessary background traffic significantly.
+
+### Consideration and Conclusion
+The Journal Replicator 2nd Edition achieves robust and scalable storage synchronisation through enhanced memory efficiency (via Web Streams), decoupled extensibility (via IJournalStorage), and strict protocol compliance (via `new_edits: false`).
+Moving forward, this foundation will make it much easier to officially support a wider variety of backend storages.

docs/design_docs_of_keep_newborn_chunks.md

@@ -0,0 +1,106 @@
+# Keep newborn chunks in Eden
+
+Notice: deprecated. please refer to the result section of this document.
+
+## Goal
+
+Reduce the number of chunks which in volatile, and reduce the usage of storage of the remote database in middle or long term.
+
+## Motivation
+
+- In the current implementation, Self-hosted LiveSync splits documents into metadata and multiple chunks. In particular, chunks are split so that they do not exceed a certain length.
+    - This is to optimise the transfer and take advantage of the properties of CouchDB. This also complies with the restriction of IBM Cloudant on the size of a single document.
+- However, creating chunks halfway through each editing operation increases the number of unnecessary chunks.
+    - Chunks are shared by several documents. For this reason, it is not clear whether these chunks are needed or not unless all revisions of all documents are checked. This makes it difficult to remove unnecessary data.
+    - On the other hand, chunks are done in units that can be neatly divided as markdown to ensure relatively accurate de-duplication, even if they are created simultaneously on multiple terminals. Therefore, it is unlikely that the data in the editing process will be reused.
+        - For this reason, we have made features such as Batch save available, but they are not a fundamental solution.
+        - As a result, there is a large amount of data that cannot be erased and is probably unused. Therefore, `Fetch chunks on demand` is currently performed for optimal communication.
+    - If the generation of unnecessary chunks is sufficiently reduced, this function will become unnecessary.
+- The problem is that this unnecessary chunking slows down both local and remote operations.
+
+## Prerequisite
+
+- The implementation must be able to control the size of the document appropriately so that it does not become non-transferable (1).
+- The implementation must be such that data corruption can be avoided even if forward compatibility is not maintained; due to the nature of Self-hosted LiveSync, backward version connexions are expected.
+- Viewed as a feature:
+    - This feature should be disabled for migration users.
+    - This feature should be enabled for new users and after rebuilds of migrated users.
+        - Therefore, back into the implementation view, Ideally, the implementation should be such that data recovery can be achieved by immediately upgrading after replication.
+
+## Outlined methods and implementation plans
+
+### Abstract
+
+To store and transfer only stable chunks independently and share them from multiple documents after stabilisation, new chunks, i.e. chunks that are considered non-stable, are modified to be stored in the document and transferred with the document. In this case, care should be taken not to exceed prerequisite (1).
+
+If this is achieved, the non-leaf document will not be transferred, and even if it is, the chunk will be stored in the document, so that the size can be reduced by the compaction.
+
+Details are given below.
+
+1. The document will henceforth have the property eden.
+    ```typescript
+    // Paritally Type
+    type EntryWithEden = {
+        eden: {
+            [key: DocumentID]: {
+                data: string;
+                epoch: number; // The document revision which this chunk has been born.
+            };
+        };
+    };
+    ```
+2. The following configuration items are added:
+   Note: These configurations should be shared as `Tweaks value` between each client.
+    - useEden : boolean
+    - Max chunks in eden : number
+    - Max Total chunk lengths in eden: number
+    - Max age while in eden: number
+3. In the document saving operation, chunks are added to Eden within each document, having the revision number of the existing document. And if some chunks in eden are not used in the operating revision, they would be removed.
+   Then after being so chosen, a few chunks are also chosen to be graduated as an independent `chunk` in following rules, and they would be left the eden:
+    - Those that have already been confirmed to exist as independent chunks.
+        - This confirmation of existence may ideally be determined by a fast first-order determination, e.g. by a Bloom filter.
+    - Those whose length exceeds the configured maximum length.
+    - Those have aged over the configured value, since epoch at the operating revision.
+    - Those whose total length, when added up when they are arranged in reverse order of the revision in which they were generated, is after the point at which they exceed the max length in the configuration. Or, those after the configured maximum items.
+4. In the document loading operation, chunks are firstly read from these eden.
+5. In End-to-End Encryption, property `eden` of documents will also be encrypted.
+
+### Note
+
+- When this feature has been enabled, forward compatibility is temporarily lost. However, it is detected as missing chunks, and this data is not reflected in the storage in the old version. Therefore, no data loss will occur.
+
+## Test strategy
+
+1. Confirm that synchronisation with the previous version is possible with this feature disabled.
+2. With this feature enabled, connect from the previous version and confirm that errors are detected in the previous version but the files are not corrupted.
+3. Ensure that the two versions with this feature enabled can withstand normal use.
+
+## Documentation strategy
+
+- This document is published, and will be referred from the release note.
+- Indeed, we lack a fulfilled configuration table. Efforts will be made and, if they can be produced, this document will then be referenced. But not required while in the experimental or beta feature.
+    - However, this might be an essential feature. Further efforts are desired.
+
+## Results from actual operation
+
+After implementing this feature, we have been using it for a while. The following results were obtained.
+
+- Drawbacks were thought not to be a problem, but they were actually a problem:
+    - A document with `Eden` has a quite larger history compared to a document without `Eden`.
+        - Self-hosted LiveSync does not perform compaction aggressively, which results in the remote database becoming partially bloated.
+        - Compaction of the Remote Database (CouchDB) requires the same amount of free space as the size of the database. Therefore, it is not possible to perform compaction on a remote database if we reached to the maximum size of the database. It means that when we detect it, it is too late.
+    - We have mentioned that `We need compaction` in previous sections. However, but it was so hard to be determined whether the compaction is required or not, until the database is bloated. (Of course, it requires some time to compact the database, and, literally, some document loses its history. It is not a good idea to perform frequently and meaninglessly. We need manual decision, but indeed difficult to normal users).
+
+### Consideration and Conclusion
+
+This feature results in two aspects:
+
+- For the users who are familiar with the CouchDB, this feature is a bit useful. They can watch and handle the database by themselves.
+- For the users who are not familiar with the CouchDB, i.e., normal users, this feature is not so useful, either. They are not familiar with the database, and they do not know how to handle it. Therefore, they cannot decide whether the compaction is required or not.
+
+Hence, this feature would be kept as an experimental feature, but it is not enabled by default. In addition to that, it is marked as deprecated. Detailed notice will be noisy for the users who are not familiar with the CouchDB. Details would be kept in this document, for the future.
+It is not recommended to use this feature, unless the person who is familiar with the CouchDB and the database management.
+
+Vorotamoroz has written this document. Bias: I am the first author of this plug-in, familiar with the CouchDB.
+
+Research and development has been frozen on 2025-04-11. But, bugs will be fixed if they are found. Please feel free to report them.

docs/design_docs_of_remote_configurations.md

@@ -0,0 +1,206 @@
+# The design document of remote configuration management
+
+## Goal
+
+- Allow us to manage multiple remote connections in a single vault.
+- Keep the existing synchronisation implementations working without requiring a large rewrite.
+- Provide a safe migration path from the previous single-remote configuration model.
+- Allow connections to be imported and exported in a compact and reusable format.
+
+## Motivation
+
+Historically, Self-hosted LiveSync stored one effective remote configuration directly in the main settings. This was simple, but it had several limitations.
+
+- We could only keep one CouchDB, one bucket, or one Peer-to-Peer target as the effective configuration at a time.
+- Switching between same-type-remotes required manually rewriting the active settings.
+- Setup URI, QR code, CLI setup, and similar entry points all restored settings differently, which made migration logic easy to miss.
+- The internal settings shape had gradually become a mix of user-facing settings, transport-specific credentials, and compatibility-oriented values.
+
+Once multiple remotes of the same type became desirable, the previous model no longer scaled well enough. We therefore needed a structure that could store many remotes, still expose one effective remote to the replication logic, and keep migration and import behaviour consistent.
+
+## Prerequisite
+
+- Existing synchronisation features must continue to read an effective remote configuration from the current settings.
+- Existing vaults must continue to work without requiring manual reconfiguration.
+- Setup URI, QR code, CLI setup, protocol handlers, and other imported settings must be normalised in the same way.
+- Import and export must be compact enough to be shared easily.
+- We must be explicit that exported connection strings may contain credentials or secrets.
+
+## Outlined methods and implementation plans
+
+### Abstract
+
+The current settings now have two layers for remote configuration.
+
+1. A stored collection of named remotes.
+2. One active remote projected into the legacy flat settings fields.
+
+This means the replication and database layers can continue to read the effective remote from the existing settings fields, while the settings dialogue and migration logic can manage many stored remotes.
+
+In short, the list is the source of truth for saved remotes, and the legacy fields remain the runtime compatibility layer.
+
+### Data model
+
+The main settings now contain the following properties.
+
+```typescript
+type RemoteConfiguration = {
+    id: string;
+    name: string;
+    uri: string;
+    isEncrypted: boolean;
+};
+
+type RemoteConfigurations = {
+    remoteConfigurations: Record<string, RemoteConfiguration>;
+    activeConfigurationId: string;
+};
+```
+
+Each entry stores a connection string in `uri`.
+
+- `sls+http://` or `sls+https://` for CouchDB-compatible remotes
+- `sls+s3://` for bucket-style remotes
+- `sls+p2p://` for Peer-to-Peer remotes
+
+This structure allows multiple remotes of the same type to be stored without adding a large number of duplicated settings fields.
+
+### Runtime compatibility
+
+The replication logic still reads the effective remote from legacy flat settings such as the following.
+
+- `remoteType`
+- `couchDB_URI`, `couchDB_USER`, `couchDB_PASSWORD`, `couchDB_DBNAME`
+- `endpoint`, `bucket`, `accessKey`, `secretKey`, and related bucket fields
+- `P2P_roomID`, `P2P_passphrase`, and related Peer-to-Peer fields
+
+When a remote is activated, its connection string is parsed and projected into these legacy fields. Therefore, existing services do not need to know whether the remote came from an old vault, a Setup URI, or the new remote list.
+
+This projection is intentionally one-way at runtime. The stored remote list is the persistent catalogue, while the flat fields describe the remote currently in use.
+
+### Connection string format
+
+The connection string is the transport-neutral storage format for a remote entry.
+
+Benefits:
+
+- It is compact enough for clipboard-based workflows.
+- It can be used for import and export in the settings dialogue.
+- It avoids introducing a separate serialisation format only for the remote list.
+- It can be parsed into the legacy settings shape whenever the active remote changes.
+
+This is not equivalent to Setup URI.
+
+- Setup URI represents a broader settings transfer workflow.
+- A remote connection string represents one remote only.
+
+### Import and export
+
+The settings dialogue now supports the following workflows.
+
+- Add connection: create a new remote by using the remote setup dialogues.
+- Import connection: paste a connection string, validate it, and save it as a named remote.
+- Export: copy a stored remote connection string to the clipboard.
+
+Import normalises the string by parsing and serialising it again before saving. This ensures that equivalent but differently formatted URIs are saved in a canonical form.
+
+Export is intentionally simple. It copies the connection string itself, because this is the most direct representation of one remote entry.
+
+### Security note
+
+Connection strings may include credentials, secrets, JWT-related values, or Peer-to-Peer passphrases.
+
+Therefore:
+
+- Export is a deliberate clipboard operation.
+- Import trusts the supplied connection string as-is after parsing.
+- We should regard exported connection strings as sensitive information, much like Setup URI or a credentials-bearing configuration file.
+
+The `isEncrypted` field is currently reserved for future expansion. At present, the connection string itself is stored plainly inside the settings data, in the same sense that the effective runtime configuration can contain usable remote credentials.
+
+### Migration strategy
+
+Older vaults store only one effective remote in the flat settings fields. The migration creates a first remote list from those values.
+
+Rules:
+
+- If no remote list exists and the legacy fields contain a CouchDB configuration, create `legacy-couchdb`.
+- If no remote list exists and the legacy fields contain a bucket configuration, create `legacy-s3`.
+- If no remote list exists and the legacy fields contain a Peer-to-Peer configuration, create `legacy-p2p`.
+- If more than one legacy remote is populated, create all possible entries and select the active one according to `remoteType`.
+
+This migration is intentionally additive. It does not remove the flat fields because they remain necessary as the active runtime projection.
+
+### Normalisation and application paths
+
+One important design lesson from this work is that migration cannot rely only on loading `data.json`.
+
+Settings may enter the system from several routes:
+
+- normal settings load
+- Setup URI
+- QR code
+- protocol handler
+- CLI setup
+- Peer-to-Peer remote configuration retrieval
+- red flag based remote adjustment
+- settings markdown import
+
+To keep behaviour consistent, normalisation is centralised in the settings service.
+
+- `adjustSettings` is responsible for in-place normalisation and migration of a settings object.
+- `applyExternalSettings` is responsible for applying imported or externally supplied settings after passing them through the same normalisation flow.
+
+This ensures that imported settings can migrate to the current remote list model even if they never passed through the ordinary `loadSettings` path.
+
+### Why not store only the remote list
+
+It would be possible to let all consumers parse the active remote every time and stop using the flat fields entirely. However, this would require broader changes across replication, diagnostics, and compatibility layers.
+
+The current design keeps the change set limited.
+
+- The remote list improves storage and UX.
+- The flat fields preserve compatibility and reduce migration risk.
+
+This is a pragmatic transitional architecture, not an accidental duplication.
+
+## Test strategy
+
+The feature should be tested from four viewpoints.
+
+1. Migration from old settings.
+   - A vault with only legacy flat remote settings should gain a remote list automatically.
+   - The correct active remote should be selected according to `remoteType`.
+
+2. Runtime activation.
+   - Activating a stored remote should correctly project its values into the effective flat settings.
+
+3. External import paths.
+   - Setup URI, QR code, CLI setup, Peer-to-Peer remote config, red flag adjustment, and settings markdown import should all pass through the same normalisation path.
+
+4. Import and export.
+   - Imported connection strings should be parsed, canonicalised, named, and stored correctly.
+   - Export should copy the exact saved connection string.
+
+## Documentation strategy
+
+- This document explains the design and compatibility model of remote configuration management.
+- User-facing setup documents should explain only how to add, import, export, and activate remotes.
+- Release notes may refer to this document when changes in remote handling are significant.
+
+## Outlook
+
+Import/export configuration strings should also be encrypted in the future, but this is a separate feature that can be added on top of the current design.
+
+## Consideration and conclusion
+
+The remote configuration list solves the practical need to manage multiple remotes without forcing the whole codebase to abandon the previous effective-settings model at once.
+
+Its core idea is modest but effective.
+
+- Store named remotes as connection strings.
+- Select one active remote.
+- Project it into the legacy settings for runtime use.
+- Normalise every imported settings object through the same path.
+
+This keeps the implementation understandable and migration-friendly. It also opens the door for future work, such as encrypted per-remote storage, richer remote metadata, or remote-scoped options, without forcing another large redesign of how remotes are represented.

docs/design_docs_of_sharing_tweak_value.md

@@ -0,0 +1,55 @@
+# Sharing `Tweak values`
+
+NOTE: This is the planned feature design document. This is planned, but not be implemented now (v0.23.3). This has not reached the design freeze and will be added to from time to time.
+
+## Goal
+
+Share `Tweak values` between clients to match the chunk lengths, and match per-server configurations for better performance.
+
+## Motivation
+
+- In the current implementation, Self-hosted LiveSync splits documents into metadata and multiple chunks. In particular, chunks are split so that they do not exceed a certain length.
+    - This is to optimise the transfer and take advantage of the properties of CouchDB. This also complies with the restriction of IBM Cloudant on the size of a single document.
+- The length of this chunk is adjusted according to a configured factor. Therefore, if this is inconsistent between clients, de-duplication will not work. This is because, in fact, they point to the same content in total, but are split in different places. This results in unnecessary transfers or storage consumption.
+- The same applies to hash algorithms.
+- There are more configurations which `preferred to be matched`, even if it is not required. such as the maximum size of files to be handled and the interval between requests to the remote database, unless there are specific circumstances.
+- To avoid the tragedy of "Too many toggles", "Unexpected transfer amount", or "Poor performance" at once, the plug-in should know these problems or potential problems and be able to let us know.
+
+## Prerequisite
+- We must be informed of a discrepancy in a configured value that is required to be absolutely consistent and be able to make a decision on the spot.
+- We should be able to see on the configuration dialogue, that there is a discrepancy between configured values that should be matched, and it should be possible to adjust them to a specific one of them (or default).
+- We must not be exposed to unexpected; such as leaking credentials or their secrets.
+
+## Outlined methods and implementation plans
+### Abstract
+- In the current implementation, each client checks the remote database for the existence of their node information, to detect whether the remote database accepts them.
+  - This is what 'Lock' is all about.
+- To achieve this feature, the client will also send each configuration value. However, the configuration contains credentials and/or secret values. Hence we cannot send all of them.
+  - With a favourable prediction, Self-hosted LiveSync will continue to increase in feature. Each time this happens, the number of configuration values to be kept secret will also increase. Therefore, they must be handled by an allow-list.
+  - This allow-listed configuration are the `Tweak values`.
+- If the plug-in detects mismatched `Tweak values` on checking the remote database, the plug-in will ask us to decide which is win (Mine, or theirs).
+- Node information is one of the documents. Therefore, it will be replicated and saved locally. While showing dialogue, show the notice on each `Match preferred` configuration.
+
+## Note
+This feature should be mostly harmless. We will not be able to disable this.
+
+## Test strategy
+
+A: During synchronisation.
+1. No message shall be displayed with all settings matched.
+2. Message shall be displayed when there are mismatched, required match items. 
+   1. The setting values can be changed according to the message.
+   2. The message can be ignored.
+3. The message shall not be displayed even if there are mismatched items which is recommended to be matched.
+
+B: On the setting dialogue.
+1. All mismatched items shall be highlighted in some way.
+
+## Documentation strategy
+
+- This document is published, and will be referred from the release note.
+- Indeed, we lack a fulfilled configuration table. Efforts will be made and, if they can be produced, this document will then be referenced. But not required while in the experimental or beta feature.
+    - However, this might be an essential feature. Further efforts are desired.
+
+### Consideration and Conclusion
+To be described after implemented, tested, and, released.

docs/p2p_sync_updates_2026.md

@@ -0,0 +1,62 @@
+# User Guide: Peer-to-Peer Synchronisation (2026 Edition)
+
+Peer-to-Peer (P2P) synchronisation has evolved significantly. This guide covers the essential setup and the new features introduced in the 2026 updates.
+
+## 1. Core Concept: Server-less Freedom
+P2P synchronisation allows your devices to talk directly to each other using WebRTC. A central server is not required for data storage, ensuring maximum privacy and "freedom."
+
+## 2. Setting Up via P2P Status Pane
+You no longer need to navigate through complex menus. Simply open the **P2P Status** (via the ribbon icon or command palette) and click the **⚙ (Cog)** icon.
+
+This opens the **P2P Setup** dialogue where you can configure the essentials:
+- **Room ID:** A unique identifier for your synchronisation group.
+- **Passphrase:** Your encryption key. Ensure all your devices use the exact same passphrase. 
+- **Device Name:** A recognisable name for the current device (e.g., `iphone-16`).
+
+Once you have saved the settings, return to the **P2P Status Pane** and click the **Connect** button to join the network.
+
+*Tip: You can also toggle **Auto Connect** in the setup dialogue to automatically join the network whenever Obsidian starts.*
+
+## 3. Real-time Control
+The status pane in the right sidebar provides granular control over your synchronisation:
+
+- **Active P2P Remote (new):** P2P now has its own active remote selection, separate from the normal active remote for database replication. Use the combo box next to the cog icon to choose which P2P remote configuration is active for P2P features.
+- **Create P2P Remote (new):** Use the **+** button to open the P2P setup dialogue and create a dedicated P2P remote configuration. This is recommended when no P2P active remote has been selected yet.
+- **Selection required (new):** If no P2P active remote is selected, the pane asks for selection before P2P target-related changes are saved.
+
+- **Signalling Status:** Shows if you are connected to the relay (🟢 Online).
+- **Live-push (Broadcast):** Toggle "Broadcast changes" to notify other peers whenever you make an edit.
+- **Replicate now (🔄):** Start immediate bidirectional replication with a visible peer (Pull, then Push).
+- **Watch (🔔/🔕):** Enable "Watch" on specific peers to automatically pull changes when they broadcast. This creates a "LiveSync-like" experience.
+- **Sync target (🔗/⛓️‍💥):** Mark specific peers as **sync targets**. Peers marked here will be included when you run the **"P2P: Sync with targets"** command (see section 5). Click the button next to a peer to toggle it on (🔗, highlighted) or off (⛓️‍💥). This setting is persisted in your configuration.
+
+## 4. Replication Dialogue
+If you want to synchronise with a specific peer manually, use the **Replication** command or button. This opens the **Replication Dialogue** listing available devices.
+
+Inside the dialogue, the **Server Status** card at the top confirms you are still connected while performing the sync.
+The status card now shows a stable **Room ID suffix** above **Peer ID**. The Room ID suffix is better for identifying your P2P group, while Peer ID may change between connections.
+
+Two actions are available per peer:
+
+- **Sync** — Starts a bidirectional synchronisation (Pull then Push) and keeps the dialogue open so you can monitor progress or sync with additional peers.
+- **Start Sync & Close** — Runs the same bidirectional synchronisation, waits for it to settle, then closes the dialogue. After a successful synchronisation, it also closes the signalling connection.
+
+On supported mobile and desktop devices, LiveSync keeps the screen awake while this peer-selection dialogue is open and while its synchronisations finish. This is intentional: display sleep can interrupt peer discovery or connection establishment and require detection to start again. Wake Lock support remains best effort, does not keep a hidden application running in the background, and does not override operating-system sleep or suspension.
+
+During a P2P rebuild, peer discovery and selection remain protected after the rebuild has started. Keep Obsidian visible until a peer is selected and the transfer finishes, because mobile platform restrictions can still pause or terminate a hidden application.
+
+## 5. Syncing with Registered Targets via Command Palette
+
+You can now trigger a synchronisation with all your pre-registered target peers in one step, without opening any UI.
+
+1. Open the **Command Palette** (`Ctrl/Cmd + P`).
+2. Run **"P2P: Sync with targets"**.
+
+This command synchronises with every peer whose **SYNC** toggle is enabled in the **Detected Peers** list. If no targets are registered, or if the P2P server is not running, the command will notify you accordingly.
+
+*Tip: Pair this command with a hotkey for a quick, keyboard-driven sync workflow.*
+
+## 6. Technical Improvements in 2026
+- **Decoupled Architecture:** The UI is now strictly separated from the core logic, making the plug-in more stable across different platforms (Mobile, Desktop, and Web).
+- **Svelte 5 UI:** The interface has been rebuilt for better responsiveness and clearer status indicators.
+- **Security:** All data remains end-to-end encrypted. Even the signalling relay never sees your actual notes.

docs/quick_setup.md

@@ -0,0 +1,105 @@
+# Quick setup
+
+[Japanese docs](./quick_setup_ja.md) - [Chinese docs](./quick_setup_cn.md).
+
+This guide establishes ordinary note synchronisation on the first device and then adds another device. Optional features are configured only after this basic path works.
+
+Before starting:
+
+- back up every Vault involved;
+- disable Obsidian Sync, iCloud synchronisation, and any other service which writes to the same Vault;
+- prepare the remote service and a Setup URI; and
+- keep the Setup URI and its passphrase separate from each other.
+
+This walkthrough covers the recommended provisioned CouchDB path. Follow [Set up a CouchDB server](./setup_own_server.md) to prepare the server and Setup URI.
+
+## What a Setup URI contains
+
+A Setup URI starts with `obsidian://setuplivesync?settings=`. It contains encrypted connection settings, including credentials, and must be protected even though it is encrypted.
+
+The Setup URI passphrase decrypts the URI. It is different from the Vault encryption passphrase which protects synchronised data. Store both securely, and do not send the Setup URI and its passphrase through the same channel.
+
+## Set up the first device
+
+Use this path only when the remote database is new, or when this device is intentionally the source of truth for a full server rebuild.
+
+1. Install and enable Self-hosted LiveSync in the intended Vault.
+2. Select the `Welcome to Self-hosted LiveSync` Notice to open onboarding.
+3. Select `I am setting this up for the first time`, then confirm that you want to set up a new synchronisation.
+4. On `Connection Method`, select `Use a Setup URI (Recommended)`.
+5. Paste the Setup URI, enter its Setup URI passphrase, and select `Test Settings and Continue`.
+
+   ![Encrypted Setup URI and masked passphrase](../images/quick-setup/guide-quick-setup-first-setup-uri.png)
+
+6. Review `Setup Complete: Preparing to Initialise Server`, then select `Restart and Initialise Server`.
+
+   ![First-device server initialisation confirmation](../images/quick-setup/guide-quick-setup-first-initialise.png)
+
+7. Read the final overwrite warning carefully. Select `I Understand, Overwrite Server` only after checking that backups exist and that replacing the remote data is intended.
+
+   ![Final server overwrite warning](../images/quick-setup/guide-quick-setup-first-rebuild-confirmation.png)
+
+8. A newly provisioned database may show `Fetch Remote Configuration Failed` because it does not contain a saved preferred configuration yet. If this is a genuinely new setup, select `Skip and proceed`. Otherwise, stop and investigate before continuing.
+
+   ![Expected missing remote configuration choice for a new database](../images/quick-setup/guide-quick-setup-missing-remote-configuration.png)
+
+9. Acknowledge `All optional features are disabled`. Optional features remain off until the ordinary synchronisation path has been verified.
+10. Allow initialisation and any requested restart to finish. Keep Obsidian open until the LiveSync progress indicators have cleared.
+
+Create an ordinary test note and allow it to upload before adding another device.
+
+## Create a Setup URI for another device
+
+Generate the additional-device Setup URI from the working first device. This captures the settings which that device is actually using, rather than asking another device to reuse the bootstrap URI produced during server provisioning.
+
+1. Open the Obsidian command palette on the first device.
+2. Run `Self-hosted LiveSync: Copy settings as a new Setup URI`.
+3. Enter a new passphrase which will protect this Setup URI, then select `OK`.
+
+   ![Masked passphrase for a new additional-device Setup URI](../images/quick-setup/guide-quick-setup-copy-setup-uri-passphrase.png)
+
+4. Copy the resulting Setup URI, then select `OK`.
+
+   ![Setup URI generated by the working first device](../images/quick-setup/guide-quick-setup-copy-setup-uri-result.png)
+
+Store the new Setup URI and its passphrase separately. The URI is encrypted, but it contains credentials and Vault settings, so continue to protect it.
+
+## Add another device
+
+Start with a new or separately backed-up Vault. Do not use a production Vault containing unsynchronised notes unless you have reviewed the [Fast Setup choices](./tips/fast-setup.md).
+
+1. Install and enable Self-hosted LiveSync.
+2. Open onboarding from the `Welcome to Self-hosted LiveSync` Notice.
+3. Select `I am adding a device to an existing synchronisation setup`, then confirm that you want to add the device.
+4. On `Device Setup Method`, select `Use a Setup URI (Recommended)`.
+5. Paste the new Setup URI generated by the first device, enter its Setup URI passphrase, and select `Test Settings and Continue`.
+6. Review `Setup Complete: Preparing to Fetch Synchronisation Data`, then select `Restart and Fetch Data`.
+
+   ![Additional-device Fetch confirmation](../images/quick-setup/guide-quick-setup-second-fetch.png)
+
+7. For a new or empty Vault, select `Overwrite all with remote files`. For a Vault with local work, stop and choose the appropriate strategy from the [Fast Setup guide](./tips/fast-setup.md).
+
+   ![Fast Setup data retrieval choices](../images/quick-setup/guide-quick-setup-retrieval-method.png)
+
+8. When asked how to handle extra local files, the conservative choice is `Keep local files even if not on remote`. Select the delete option only when the local Vault is disposable and an exact remote copy is intended.
+
+   ![Additional-device local file policy](../images/quick-setup/guide-quick-setup-local-file-policy.png)
+
+9. Allow retrieval, file reflection, and any requested restart to finish. Keep Obsidian open until the LiveSync progress indicators have cleared.
+
+Confirm that the ordinary test note from the first device appears unchanged. Then edit or create a second ordinary note on the new device, and confirm that it reaches the first device.
+
+![Ordinary note received through the provisioned Setup URI](../images/quick-setup/guide-quick-setup-synchronised-note.png)
+
+## After ordinary synchronisation works
+
+Add optional features separately so that their ownership and initialisation direction are explicit:
+
+- [Hidden File Sync](./tips/hidden-file-sync.md) for selected hidden files and folders; or
+- [Customisation Sync](./settings.md#6-customisation-sync-advanced) for managed Obsidian customisations.
+
+Do not enable both features for the same files.
+
+## Manual configuration
+
+If a Setup URI is unavailable, choose `Enter the server information manually` during onboarding. Manual configuration is an advanced path: verify the connection, encryption, remote profile, and synchronisation preset before initialising either side. After the first device works, use `Copy settings as a new Setup URI` from the command palette to add later devices through the recommended path.

docs/quick_setup_cn.md

@@ -0,0 +1,93 @@
+# 快速配置 (Quick setup)
+
+该插件有较多配置项, 可以应对不同的情况. 不过, 实际使用的设置并不多. 因此, 我们采用了 "设置向导 (The Setup wizard)" 来简化初始设置.
+
+Note: 建议使用 `Copy setup URI` and `Open setup URI` 来设置后续设备.
+
+## 设置向导 (The Setup wizard)
+
+在设置对话框中打开 `🧙‍♂️ Setup wizard`. 如果之前未配置插件, 则会自动打开该页面.
+
+![quick_setup_1](../images/quick_setup_1.png)
+
+- 放弃现有配置并进行设置  
+如果您先前有过任何设置, 此按钮允许您在设置前放弃所有更改.
+
+- 保留现有配置和设置  
+快速重新配置. 请注意, 在向导模式下, 您无法看到所有已经配置过的配置项.
+
+在上述选项中按下 `Next`, 配置对话框将进入向导模式 (wizard mode).
+
+### 向导模式 (Wizard mode)
+
+![quick_setup_2](../images/quick_setup_2.png)
+
+接下来将介绍如何逐步使用向导模式.
+
+## 配置远程数据库
+
+### 开始配置远程数据库
+
+输入已部署好的数据库的信息.  
+
+![quick_setup_3](../images/quick_setup_3.png)
+
+#### 测试数据库连接并检查数据库配置
+
+我们可以检查数据库的连接性和数据库设置.
+
+![quick_setup_5](../images/quick_setup_5.png)
+
+#### 测试数据库连接
+
+检查是否能成功连接数据库. 如果连接失败, 可能是多种原因导致的, 但请先点击 `Check database configuration` 来检查数据库配置是否有问题.
+
+#### 检查数据库配置
+
+检查数据库设置并修复问题.
+
+![quick_setup_6](../images/quick_setup_6.png)
+
+Config check 的显示内容可能因不同连接而异. 在上图情况下, 按下所有三个修复按钮.
+如果修复按钮消失, 全部变为复选标记, 则表示修复完成.
+
+### 加密配置
+
+![quick_setup_4](../images/quick_setup_4.png)
+
+为您的数据库加密, 以防数据库意外曝光; 启用端到端加密后, 笔记内容在离开设备时就会被加密. 我们强烈建议启用该功能. `路径混淆 (Path Obfuscation)` 还能混淆文件名. 现已稳定并推荐使用.
+加密基于 256 位 AES-GCM.
+如果你在一个封闭的网络中, 而且很明显第三方不会访问你的文件, 则可以禁用这些设置.
+
+![quick_setup_7](../images/quick_setup_7.png)
+
+#### Next
+
+转到同步设置.
+
+#### 放弃现有数据库并继续
+
+清除远程数据库的内容, 然后转到同步设置.
+
+### 同步设置
+
+最后, 选择一个同步预设完成向导.
+
+![quick_setup_9_1](../images/quick_setup_9_1.png)
+
+选择我们要使用的任何同步方法, 然后 `Apply` 初始化并按要求建立本地和远程数据库. 如果显示 `All done!`, 我们就完成了. `Copy setup URI` 将自动打开，并要求我们输入密码以加密 `Setup URI`.
+
+![quick_setup_10](../images/quick_setup_10.png)
+
+根据需要设置密码。.
+设置 URI (Setup URI) 将被复制到剪贴板, 然后您可以通过某种方式将其传输到第二个及后续设备.
+
+## 如何设置第二单元和后续单元 (the second and subsequent units)
+
+在第一台设备上安装 Self-hosted LiveSync 后, 从命令面板上选择 `Open setup URI`, 然后输入您传输的设置 URI (Setup URI). 然后输入密码，安装向导就会打开.
+在弹窗中选择以下内容.
+
+- `Importing LiveSync's conf, OK?` 选择 `Yes`
+- `How would you like to set it up?`. 选择 `Set it up as secondary or subsequent device`
+
+然后, 配置将生效并开始复制. 您的文件很快就会同步! 您可能需要关闭设置对话框并重新打开, 才能看到设置字段正确填充, 但它们都将设置好.

docs/quick_setup_ja.md

@@ -0,0 +1,93 @@
+# Quick setup
+このプラグインには、いろいろな状況に対応するための非常に多くの設定オプションがあります。しかし、実際に使用する設定項目はそれほど多くはありません。そこで、初期設定を簡略化するために、「セットアップウィザード」を実装しています。  
+※なお、次のデバイスからは、`現在の設定をセットアップURIにコピー`と`セットアップURIで接続`を使ってセットアップしてください。
+
+
+## Wizardの使い方
+`🧙‍♂️ Setup wizard` から開きます。もしセットアップされていなかったり、同期設定が何も有効になっていない場合はデフォルトで開いています。
+
+![](../images/quick_setup_1.png)
+
+### Discard the existing configuration and set up
+今設定されている内容をいったん全部消してから、ウィザードを始めます。
+
+### Do not discard the existing configuration and set up
+今の設定を消さずにウィザードを開始します。  
+たとえ設定されていたとしても、ウィザードモードではすべての設定を見ることができません。
+
+いずれかのNextを押すと、設定画面がウィザードモードになります。
+
+### Wizardモード
+
+![](../images/quick_setup_2.png)
+
+順番に設定を行っていきます。
+
+## Remote Database configuration
+
+### Remote databaseの設定
+セットアップしたデータベースの情報を入力していきます。
+
+![](../images/quick_setup_3.png)
+
+これらはデータベースをセットアップした際に決めた情報です。
+
+### Test database connectionとCheck database configuration
+ここで、データベースへの接続状況と、データベース設定を確認します。  
+![](../images/quick_setup_5.png)  
+
+#### Test Database Connection
+データベースに接続できるか自体を確認します。失敗する場合はいくつか理由がありますが、一度Check database configurationを行ってそちらでも失敗するか確認してください。
+
+#### Check database configuration
+データベースの設定を確認し、不備がある場合はその場で修正します。
+
+![](../images/quick_setup_6.png)
+
+この項目は接続先によって異なる場合があります。上記の場合、みっつのFixボタンを順にすべて押してください。  
+Fixボタンがなくなり、すべてチェックマークになれば完了です。
+
+### 機密性設定
+
+![](../images/quick_setup_4.png)
+
+意図しないデータベースの暴露に備えて、End to End Encryptionを有効にします。この項目を有効にした場合、デバイスを出る瞬間にノートの内容が暗号化されます。`Path Obfuscation`を有効にすると、ファイル名も難読化されます。現在は安定しているため、こちらも推奨されます。  
+暗号化には256bitのAES-GCMを採用しています。  
+これらの設定は、あなたが閉じたネットワークの内側にいて、かつ第三者からアクセスされない事が明確な場合には無効にできます。
+
+
+![](../images/quick_setup_7.png)
+
+### Next 
+次へ進みます
+
+### Discard exist database and proceed
+すでにRemote databaseがある場合、Remote databaseの内容を破棄してから次へ進みます
+
+
+## Sync Settings
+最後に同期方法の設定を行います。
+
+![](../images/quick_setup_9_1.png)
+
+Presetsから、いずれかの同期方法を選び`Apply`を行うと、必要に応じてローカル・リモートのデータベースを初期化・構築します。  
+「All done!」（日本語環境では「完了！」）と表示されれば完了です。自動的に、「現在の設定をセットアップURIにコピー」のダイアログが開き、Setup URIを暗号化するためのパスフレーズを求められます（このパスフレーズはSetup URIを暗号化するためのもので、Vault自体の暗号化キーではありません）。  
+パスフレーズを入力すると、クリップボードにSetup URIが保存されますので、これを2台目以降のデバイスに何らかの方法で転送してください。
+
+![](../images/quick_setup_10.png)
+
+お好みのパスフレーズを設定してください。  
+クリップボードにSetup URIが保存されますので、これを2台目以降のデバイスに何らかの方法で転送してください。
+
+# 2台目以降の設定方法
+2台目の端末にSelf-hosted LiveSyncをインストールしたあと、コマンドパレットから`Use the copied setup URI (Formerly Open setup URI)`を選択し、転送したsetup URIを入力します。その後、パスフレーズを入力するとセットアップ用のウィザードが開きます。  
+下記のように答えてください。
+
+- `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) をご参照ください。

docs/review_harness.md

@@ -0,0 +1,67 @@
+# Review Harness
+
+The Review Harness is an opt-in, real-device review tool for Self-hosted LiveSync maintainers. It replaces the disabled legacy Test Pane with fixed, auditable scenarios, a device-local one-shot continuation, and a Markdown report which can be pasted into a pull request.
+
+It supplies supporting evidence rather than a release gate by itself. Unit, integration, Compose, CLI E2E, and real-Obsidian E2E remain authoritative for the boundaries they own.
+
+## Enabling the Harness
+
+1. Use a dedicated test Vault.
+2. Enable **Power users → Enable Developers' Debug Tools**.
+3. Restart Obsidian.
+4. Run **Self-hosted LiveSync: Open review harness** from the command palette.
+
+The command and view are registered only when developer tools are enabled. Disabling the setting and restarting removes the entry point from an ordinary user session.
+
+## Scenarios and access
+
+| Scenario | Mode | Access | Purpose |
+| --- | --- | --- | --- |
+| Settings lifecycle | Automatic | Read-only | Exposes the seven synchronisation choices as typed observations and, for a genuinely new Vault, compares the selected recommendations with Commonlib's new-Vault contract. Existing-Vault setting preservation remains an automated migration and `settings-ui` E2E responsibility. |
+| Compatibility review boundary | Guided | Device-local state | Observes the current dedicated compatibility controller and opens its actual review action. The Harness does not restore Change Log acknowledgement, `lastReadUpdates`, or a separate manual Pass or Fail result. |
+| P2P composition | Automatic | Read-only | Confirms that the live P2P result resolves one replicator bound to the active Obsidian services. Peer discovery, replacement, reconnection, and transfer remain unit, CLI, and Compose E2E responsibilities. |
+| Vault fixture round trip | Automatic, explicit | Dedicated Vault fixtures | After explicit confirmation, creates, reads, modifies, renames, and removes one owned fixture tree. General Vault reflection remains covered by its separate real-Obsidian E2E workflow. |
+
+**Automatic** runs only the two read-only local observations. **Full review** also starts the guided compatibility observation and asks before the Vault fixture scenario writes anything. A scenario can also be run individually.
+
+These observations deliberately do not repeat stronger automated workflows. They exist to record which contracts the current real-device composition exposes while a maintainer reviews an immutable artefact.
+
+### Vault fixture boundary
+
+The Vault scenario owns only `__self-hosted-livesync-review-harness__`. It refuses to run if that path already exists, so it cannot assume ownership of a user's existing file or folder. Once it creates the root, it removes the complete owned tree from a `finally` block whether the round trip passes or fails.
+
+The Harness accepts no path, command, code, remote configuration, or credential through plug-in data or its continuation state. New write scenarios must use a distinct fixed fixture root, describe their side effects in the interface, require confirmation, and clean up in `finally`.
+
+## Restart continuation
+
+The restart action writes a small device-local record under `review-harness-v1`, then asks Obsidian to reload. The record permits only:
+
+- the fixed `compatibility-review` scenario;
+- the fixed `awaiting-restart` stage;
+- a canonical ISO request time; and
+- a request identifier derived exactly as `compatibility-review-<request time>`.
+
+On the next settings load, the Harness deletes the record before parsing and acting on it. A valid record reopens the Harness after layout is ready and leaves the compatibility observation waiting for the reviewer. Invalid state is removed and reported as a failed continuation. The record is not stored in `data.json`, copied through a Setup URI, or synchronised to another device.
+
+The compatibility controller does not require an Obsidian restart to acknowledge a pause. This continuation belongs to the review tool and proves its one-shot reload boundary; it is not a second compatibility lifecycle.
+
+## Reports and privacy
+
+**Copy Markdown report** includes:
+
+- the plug-in and Obsidian versions;
+- the platform, user agent, and viewport;
+- each scenario's status and bounded summary; and
+- a bounded event transcript.
+
+The formatter has no inputs for Vault identifiers, paths, file names, file contents, remote configuration, or secrets. The report is copied locally and is never transmitted by the plug-in. Review the environment information before posting it because a user agent and viewport may identify a device or operating system.
+
+Unexpected runtime errors are written to the local LiveSync log, while copied reports retain only a generic failure summary. This prevents an adapter error from copying a local path or file name into a pull request by accident.
+
+## Automated real-Obsidian coverage
+
+External automation drives the stable `data-testid` attributes beginning with `review-harness-`. The dedicated workflow checks only Harness-owned behaviour: debug-only registration, consume-before-use continuation handling, fixed Vault fixture clean-up, report privacy, and mobile layout.
+
+Compatibility dialogue behaviour and persistence belong to `test:e2e:obsidian:settings-ui`. Real P2P transport belongs to the Compose P2P suite. General Vault reflection belongs to `test:e2e:obsidian:vault-reflection`. Keeping those responsibilities separate prevents the review tool from becoming a second, weaker copy of the acceptance suite.
+
+The mobile checks use `app.emulateMobile(true)`, a representative viewport, and safe-area and touch-target assertions. They do not claim to reproduce native operating-system overlays.

docs/settings_ja.md

@@ -1,53 +1,137 @@
+注意：少し内容が古くなっています。
+
 # このプラグインの設定項目
 
 ## Remote Database Configurations
-同期先のデータベース設定を行います。何らかの同期が有効になっている場合は編集できないため、同期を解除してから行ってください。
+同期先のデータベース設定（Remote Server）を行います。
 
-### URI
-CouchDBのURIを入力します。Cloudantの場合は「External Endpoint(preferred)」になります。  
-**スラッシュで終わってはいけません。**  
-こちらにデータベース名を含めてもかまいません。
+現在のバージョンでは、複数のリモート接続設定（接続プロファイル）を登録・管理し、切り替えて使用することが可能です（「Remote Databases」リスト）。
 
-### Username 
-ユーザー名を入力します。このユーザーは管理者権限があることが望ましいです。
+- **➕ 新規接続を追加 (Add new connection)**: 新しい接続設定を作成し、各セットアップダイアログを起動します。
+- **📥 接続をインポート (Import connection)**: 接続文字列（`sls+https://...`、`sls+s3://...`、`sls+p2p://...`など）を貼り付けてインポートします。
+- **🔧 設定 (Configure)**: セットアップダイアログを開き、選択した接続プロファイルの設定を編集します。
+- **✅ 有効化 (Activate)**: 選択したプロファイルをアクティブな同期先として有効化します。
+- **🗑️ 削除 (Delete)**: 接続プロファイルを一覧から削除します。
 
-### Password
-パスワードを入力します。
+これらの接続プロファイルを追加・編集する際、選択したデータベースの種類（CouchDB、S3互換オブジェクトストレージ、P2Pなど）に応じたセットアップダイアログが開きます。
 
-### Database Name
-同期するデータベース名を入力します。  
-⚠️存在しない場合は、テストや接続を行った際、自動的に作成されます[^1]。
-[^1]:権限がない場合は自動作成には失敗します。 
+何らかの同期が有効になっている場合は編集できないため、同期を解除してから行ってください。
 
-### Test Database connection
-上記の設定でデータベースに接続できるか確認します。
+### CouchDB の設定
+CouchDBの各設定項目は、接続プロファイルを追加 (➕) または設定 (🔧) する際に開く **CouchDB セットアップダイアログ** 内で設定します。
 
-## Local Database Configurations
-端末内に作成されるデータベースの設定です。
+#### URI
+設定キー: couchDB_URI
 
-### Batch database update
-データベースの更新を以下の事象が発生するまで遅延させます。
-- レプリケーションが発生する
-- 他のファイルを開く
-- ウィンドウの表示状態を変更する
-- ファイルの修正以外のファイル関連イベント
-このオプションはLiveSyncと同時には使用できません。
+CouchDBの接続先URIです。ダイアログ内では **URL** と表記されます。Cloudantの場合は「External Endpoint (preferred)」になります。
+注意: Obsidian Mobileではセキュア接続 (HTTPS) のみが使用可能です。また、末尾にスラッシュ（`/`）を付けてはいけません。
 
-### Auto Garbage Collection delay
-Self-hosted LiveSyncはノートの変更時、ノートをmarkdownの構造を鑑みてチャンクに分割し、ファイルの情報と更新があったチャンクのみ保存していきます。この際、古いチャンクの削除は行いません。  
-そのため、使わなくなったチャンクをどこかのタイミングで消去する必要があります。  
-ただし、このチャンクはチャンクの内容から作成されるため、同一の内容からは同一のチャンクが作成され、同じノートだけではなく、すべてのノートから共有されます。これによってデータベースの使用容量とデバイス‐サーバー間での転送量を削減しています。  
-執筆を繰り返す上で、元の文書に戻したりすることもあるため、一概に「すぐに不要になる」とは言い切れません。そこで、プラグインはObsidianを開いたまま操作しなくなってからこの設定値秒後、まとめて使用していないチャンクを削除します。  
-この処理をGarbage Collectionと呼んでいます。  
-この作業はすべてのファイル変更の反映を停止して一気に行う必要があります。そのため、一時的にObsidianの動作がかなり重くなります。
+#### Username
+設定キー: couchDB_USER
+
+CouchDBのログインユーザー名です。ダイアログ内では **Username** と表記されます。このユーザーには管理者権限があることが望ましいです。
+
+#### Password
+設定キー: couchDB_PASSWORD
+
+CouchDBのログインパスワードです。ダイアログ内では **Password** と表記されます。
+
+#### Database Name
+設定キー: couchDB_DBNAME
+
+同期先のデータベース名です。ダイアログ内では **Database Name** と表記されます。
+注意: データベース名には大文字、スペース、および一部の特殊文字（`_$()+/-` 以外）は使用できません。また、アンダースコア（`_`）から始めることはできません。存在しない場合は、接続テスト時または設定適用時に自動作成されます（作成権限が必要です）。
+
+#### CORS回避のためにRequest APIを使用する
+設定キー: useRequestAPI
+
+この項目はセットアップダイアログ内では **Use Internal API** と表記されます。有効な場合、不可避なCORS問題を回避するためにObsidianの内部Request APIを使用します。これはWeb標準に準拠していない回避策であり、すべての環境での動作を保証するものではありません。安全性が低下する可能性がある点にご注意ください。将来のObsidianのアップデートによって動作しなくなる可能性があります。
+
+#### カスタムヘッダー
+設定キー: couchDB_CustomHeaders
+
+CouchDBサーバーに送信するすべてのリクエストに含めるカスタムHTTPヘッダーを設定します。ダイアログ内では **Custom Headers** と表記されます。`ヘッダー名: 値` の形式で、1行に1つずつ入力してください。
+
+#### JWT認証の使用 (実験的機能)
+設定キー: useJWT
+
+CouchDBでのJSON Web Token (JWT) 認証を有効にします。ダイアログ内では **Use JWT Authentication** と表記されます。十分に検証されていない実験的機能であるため、ご注意ください。
+
+#### JWTアルゴリズム
+設定キー: jwtAlgorithm
+
+JWTの署名に使用するアルゴリズムを選択します。ダイアログ内では **JWT Algorithm** と表記されます。対応アルゴリズム: `HS256`, `HS512`, `ES256`, `ES512`
+
+#### JWT有効期限 (分)
+設定キー: jwtExpDuration
+
+トークンの有効期限を分単位で指定します。ダイアログ内では **JWT Expiration Duration (minutes)** と表記されます。`0` を指定すると有効期限は無効になります。
+
+#### JWTキー
+設定キー: jwtKey
+
+JWTの署名に使用する秘密鍵またはプライベートキーを指定します。ダイアログ内では **JWT Key** と表記されます。`HS256/HS512` の場合は共通鍵を、`ES256/ES512` の場合は pkcs8 PEM形式の秘密鍵を入力してください。
+
+#### JWTキーID (kid)
+設定キー: jwtKid
+
+JWTヘッダーに含めるキーIDを指定します。ダイアログ内では **JWT Key ID (kid)** と表記されます。
+
+#### JWTサブジェクト (sub)
+設定キー: jwtSub
+
+JWTのサブジェクト (CouchDBユーザー名) を指定します。ダイアログ内では **JWT Subject (sub)** と表記されます。 
+
+### Object Storage (Minio, S3, R2) の設定
+Object Storageの各設定項目は、接続プロファイルを追加 (➕) または設定 (🔧) する際に開く **S3/MinIO/R2 セットアップダイアログ** 内で設定します。
+
+#### エンドポイントURL
+設定キー: endpoint
+
+S3互換ストレージのエンドポイントURLです。ダイアログ内では **Endpoint URL** と表記されます。
+注意: Obsidian Mobileではセキュア接続 (HTTPS) のみが使用可能です。
+
+#### アクセスキー ID
+設定キー: accessKey
+
+認証に使用するアクセスキーIDです。ダイアログ内では **Access Key ID** と表記されます。
+
+#### シークレットアクセスキー
+設定キー: secretKey
+
+認証に使用するシークレットアクセスキーです。ダイアログ内では **Secret Access Key** と表記されます。
+
+#### リージョン
+設定キー: region
+
+ストレージのリージョンを指定します（例: `us-east-1`、Cloudflare R2の場合は `auto`）。ダイアログ内では **Region** と表記されます。
+
+#### バケット名
+設定キー: bucket
+
+同期データを保存するバケット名です。ダイアログ内では **Bucket Name** と表記されます。
+
+#### カスタムHTTPハンドラーを使用する
+設定キー: useCustomRequestHandler
+
+この項目はセットアップダイアログ内では **Use internal API** と表記されます。オブジェクトストレージがCORSをサポートしていない場合に有効にします。Obsidianの内部APIを使用してS3サーバーと通信することでCORS制約を回避します。Web標準には準拠していないため、将来のObsidianのアップデートによって動作しなくなる可能性があります。
+
+#### バケット内のファイルプレフィックス
+設定キー: bucketPrefix
+
+この項目はセットアップダイアログ内では **Folder Prefix** と表記されます。実質的なディレクトリ指定です。末尾は `/` である必要があります（例：`vault-name/`）。バケットのルートに保存する場合は空欄のままにしてください。
+
+#### forcePathStyleを有効にする
+設定キー: forcePathStyle
+
+この項目はセットアップダイアログ内では **Use Path-Style Access** と表記されます。有効な場合、バケット操作でforcePathStyleオプションを使用します。
+
+#### カスタムヘッダー
+設定キー: bucketCustomHeaders
+
+オブジェクトストレージバケットに送信するすべてのリクエストに含めるカスタムHTTPヘッダーを設定します。ダイアログ内では **Custom Headers** と表記されます。`ヘッダー名: 値` の形式で、1行に1つずつ入力してください。
 
 
-Obsidianでのファイル操作が終わってから指定秒数が経過した際に実行されます。  
-デフォルト値は300秒です。  
-※ごく初期は30秒でした。初期から使用されている方は、是非300秒ぐらいまで伸ばしてください。ストレスが違います。
-
-### Manual Garbage Collect
-上記のGarbage Collectionを手動で行います。
 
 ### End to End Encryption
 データベースを暗号化します。この効果はデータベースに格納されるデータに限られ、ディスク上のファイルは平文のままです。  
@@ -56,12 +140,25 @@ Obsidianでのファイル操作が終わってから指定秒数が経過した
 ### Passphrase
 暗号化を行う際に使用するパスフレーズです。充分に長いものを使用してください。
 
+### パスの難読化
+設定キー: usePathObfuscation
+
+ダイアログ内では **Obfuscate Properties** と表記されます。有効な場合、リモートサーバー上でのファイルパスやフォルダ名を難読化（暗号化）します。これによりプライバシーが向上しますが、パフォーマンスがわずかに低下する可能性があります。
+
+### 暗号化アルゴリズム
+設定キー: E2EEAlgorithm
+
+ダイアログ内では **Encryption Algorithm** と表記されます。エンドツーエンド暗号化に使用する暗号化アルゴリズムのバージョンを選択します。
+- `v2` (V2: AES-256-GCM With HKDF): 推奨されるデフォルトのバージョンです。
+- `forceV1` または `""` (V1: Legacy): レガシーな暗号化バージョンです。古いバージョンで暗号化された既存の保管庫（Vault）を同期する場合にのみ使用してください。
+
 ### Apply
 End to End 暗号化を行うに当たって、異なるパスフレーズで暗号化された同一の内容を入手されることは避けるべきです。また、Self-hosted LiveSyncはコンテンツのcrc32を重複回避に使用しているため、その点でも攻撃が有効になってしまいます。
 
 そのため、End to End 暗号化を有効にする際には、ローカル、リモートすべてのデータベースをいったん破棄し、新しいパスフレーズで暗号化された内容のみを、改めて同期し直します。
 
-有効化するには、一番体力のある端末からApply and sendを行い、他の端末でApply and receiveを行います。
+有効化するには、一番体力のある端末からApply and sendを行います。
+既に存在するリモートと同期する場合は、設定してJust applyを行ってください。
 
 - Apply and send   
 1. ローカルのデータベースを初期化しパスフレーズを設定（またはクリア）します。その後、すべてのファイルをもう一度データベースに登録します。
@@ -76,10 +173,82 @@ End to End 暗号化を行うに当たって、異なるパスフレーズで暗
 3. すべて受信して、復号します。
 
 どちらのオペレーションも、実行するとすべての同期設定が無効化されます。  
-**また、パスフレーズのチェックは、実際に復号するまで行いません。そのため、パスフレーズを間違えて設定し、Apply and receiveで同期を行うと、大量のエラーが発生します。これは仕様です。**
+
+
+
+
+### Test Database connection
+上記の設定でデータベースに接続できるか確認します。
+
+### Check database configuration
+ここから直接CouchDBの設定を確認・変更できます。
+
+### Peer-to-Peer (P2P) 同期の設定
+
+#### P2P同期を有効にする
+設定キー: P2P_Enabled
+
+WebRTCを介したデバイス間での直接的なP2P同期を有効にします。ダイアログ内では **Enabled** と表記されます。
+
+#### リレーサーバーのURL
+設定キー: P2P_relays
+
+WebRTCによるP2P接続を仲介・調整するためのWebSocketリレーサーバーのURLを指定します。ダイアログ内では **Relay URL** と表記されます。複数のURLを指定する場合はカンマで区切ります。ダイアログ内のボタンをクリックすると、デフォルトのリレーサーバーを設定できます。
+
+#### グループID
+設定キー: P2P_roomID
+
+同期するデバイス群を識別するためのルームIDまたはグループIDを指定します。ダイアログ内では **Group ID** と表記されます。同期させたいすべてのデバイスで同じグループIDを指定する必要があります。任意のカスタム文字列を入力するか、ランダム生成ボタンで生成できます。
+
+#### パスフレーズ
+設定キー: P2P_passphrase
+
+P2P通信の認証および暗号化に使用するパスワード（パスフレーズ）を指定します。ダイアログ内では **Passphrase** と表記されます。同期するすべてのデバイスで同じパスフレーズを指定する必要があります。
+
+#### デバイス名
+設定キー: P2P_DevicePeerName
+
+P2Pネットワーク上でこのデバイスを識別するための名前を指定します。ダイアログ内では **Device Peer ID** と表記されます。グループ内のデバイス間で重複しない一意の値を設定してください。
+
+#### 起動時のP2P自動接続開始
+設定キー: P2P_AutoStart
+
+有効な場合、プラグインの起動時に自動的にP2P接続を開始します。ダイアログ内では **Auto Start P2P Connection** と表記されます。
+
+#### 接続済みピアへの変更の自動ブロードキャスト
+設定キー: P2P_AutoBroadcast
+
+有効な場合、ローカルでの変更が接続済みのピアに自動的にブロードキャストされます。ダイアログ内では **Auto Broadcast Changes** と表記されます。通知されたピアは変更の取得を開始します。
+
+#### TURNサーバーのURL (カンマ区切り)
+設定キー: P2P_turnServers
+
+ダイアログ内では **TURN Server URLs (comma-separated)** と表記されます。厳しいNATやファイアウォールがある環境で、WebRTCの直接接続が確立できない場合にP2P接続を中継するためのTURN/STUNサーバーのURLをカンマ区切りで指定します。通常は空欄のままで問題ありません。
+
+#### TURNユーザー名
+設定キー: P2P_turnUsername
+
+TURNサーバーでの認証に使用するユーザー名を設定します。ダイアログ内では **TURN Username** と表記されます。
+
+#### TURNパスワード
+設定キー: P2P_turnCredential
+
+TURNサーバーでの認証に使用するパスワード（クレデンシャル）を設定します。ダイアログ内では **TURN Credential** と表記されます。
+
+## Local Database Configurations
+端末内に作成されるデータベースの設定です。
+
+### Batch database update
+データベースの更新を以下の事象が発生するまで遅延させます。
+- レプリケーションが発生する
+- 他のファイルを開く
+- ウィンドウの表示状態を変更する
+- ファイルの修正以外のファイル関連イベント
+このオプションはLiveSyncと同時には使用できません。
 
 ### minimum chunk size と LongLine threshold
-チャンクの分割についての設定です。  
+チャンクの分割についての設定です。※現在これらの項目はUIから直接設定することはできません（デフォルト値で自動処理されます）。
+
 Self-hosted LiveSyncは一つのチャンクのサイズを最低minimum chunk size文字確保した上で、できるだけ効率的に同期できるよう、ノートを分割してチャンクを作成します。  
 これは、同期を行う際に、一定の文字数で分割した場合、先頭の方を編集すると、その後の分割位置がすべてずれ、結果としてほぼまるごとのファイルのファイル送受信を行うことになっていた問題を避けるために実装されました。  
 具体的には、先頭から順に直近の下記の箇所を検索し、一番長く切れたものを一つのチャンクとします。
@@ -96,6 +265,11 @@ Self-hosted LiveSyncは一つのチャンクのサイズを最低minimum chunk s
 改行文字と#を除き、すべて●に置換しても、アルゴリズムは有効に働きます。  
 デフォルトは20文字と、250文字です。
 
+### チャンクスプリッター
+設定キー: chunkSplitterVersion
+
+チャンク分割アルゴリズムを選択します。V3が最も効率的です。問題が発生した場合はDefaultまたはLegacyに設定してください。
+
 ## General Settings
 一般的な設定です。
 
@@ -105,18 +279,35 @@ Self-hosted LiveSyncは一つのチャンクのサイズを最低minimum chunk s
 ### Vervose log
 詳細なログをログに出力します。
 
+### ファイル警告バナーの代わりにステータスアイコンを表示
+設定キー: hideFileWarningNotice
+
+有効な場合、ファイル警告バナーの代わりにステータス表示内に ⛔ アイコンが表示されます（詳細情報は非表示になります）。
+
+### ネットワーク警告のスタイル
+設定キー: networkWarningStyle
+
+同期サーバーに接続できない場合のネットワークエラーの表示方法。
+
 ## 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
+
+イベント時の自動同期の最小間隔（ミリ秒）。
 
 ### Sync on Save
 ファイルが保存されたときに同期を行います。  
@@ -142,6 +333,35 @@ Self-hosted LiveSyncは通常、フォルダ内のファイルがすべて削除
 ### Use newer file if conflicted (beta)
 競合が発生したとき、常に新しいファイルを使用して競合を自動的に解決します。
 
+
+### Experimental.
+### Sync hidden files
+
+隠しファイルを同期します
+
+- Scan hidden files before replication.
+このオプション有効にすると、レプリケーションを実行する前に隠しファイルをスキャンします。
+
+- Scan hidden files periodicaly.
+このオプションを有効にすると、n秒おきに隠しファイルをスキャンします。
+
+#### 非表示ファイルの変更通知を抑制
+設定キー: suppressNotifyHiddenFilesChange
+
+有効な場合、非表示ファイルの変更に関する通知を抑制します。
+
+隠しファイルは能動的に検出されないため、スキャンが必要です。
+スキャンでは、ファイルと共にファイルの変更時刻を保存します。もしファイルが消された場合は、その事実も保存します。このファイルを記録したエントリーがレプリケーションされた際、ストレージよりも新しい場合はストレージに反映されます。
+
+そのため、端末のクロックは時刻合わせされている必要があります。ファイルが隠しフォルダに生成された場合でも、もし変更時刻が古いと判断された場合はスキップされるかキャンセル（つまり、削除）されます。
+
+
+Each scan stores the file with their modification time. And if the file has been disappeared, the fact is also stored. Then, When the entry of the hidden file has been replicated, it will be reflected in the storage if the entry is newer than storage.
+
+Therefore, the clock must be adjusted. If the modification time is old, the changeset will be skipped or cancelled (It means, **deleted**), even if the file spawned in a hidden folder.
+
+
+
 ### Advanced settings
 Self-hosted LiveSyncはPouchDBを使用し、リモートと[このプロトコル](https://docs.couchdb.org/en/stable/replication/protocol.html)で同期しています。  
 そのため、全てのノートなどはデータベースが許容するペイロードサイズやドキュメントサイズに併せてチャンクに分割されています。
@@ -160,6 +380,45 @@ Self-hosted LiveSyncはPouchDBを使用し、リモートと[このプロトコ
 ### Batch limit
 一度に処理するBatchの数です。デフォルトは40です。
 
+### 1回のリクエストで送信するチャンクの最大サイズ
+設定キー: sendChunksBulkMaxSize
+
+メガバイト（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
@@ -179,8 +438,8 @@ Self-hosted LiveSyncはPouchDBを使用し、リモートと[このプロトコ
 ![CorruptedData](../images/lock_pattern1.png)  
 データベースがロックされていて、端末が「解決済み」とマークされていない場合、警告が表示されます。  
 他のデバイスで、End to End暗号化を有効にしたか、Drop Historyを行った等、他の端末がそのまま同期を行ってはいない状態に陥った場合表示されます。  
-暗号化を有効化した場合は、パスフレーズを設定してApply and recieve、Drop Historyを行った場合は、Drop and recieveを行うと自動的に解除されます。  
-手動でこのロックを解除する場合は「mark this device as resolved」をクリックしてください。
+暗号化を有効化した場合は、パスフレーズを設定して「このデバイスの同期状態をリセット」、または「このデバイスのファイルでサーバーデータを上書き」を行うと自動的に解除されます。  
+手動でこのロックを解除する場合は「I've made a backup, mark this device 'resolved'」をクリックしてください。
 
 - パターン２  
 ![CorruptedData](../images/lock_pattern2.png)  
@@ -191,42 +450,52 @@ Self-hosted LiveSyncはPouchDBを使用し、リモートと[このプロトコ
 ### Verify and repair all files
 Vault内のファイルを全て読み込み直し、もし差分があったり、データベースから正常に読み込めなかったものに関して、データベースに反映します。
 
-### Sanity check
-ローカルデータベースに保存されている全てのファイルが正しくチャンクを持っていることを確認します。
-
-### Drop history
-データベースに記録されている履歴を削除し、データベースを初期化します。  
-新しい端末や新しいVaultへの同期にやたらと時間がかかったり、データベースサイズが肥大化したりしてきた際に使用してください。  
-備考:CouchDBは、データを削除する際、衝突の解決のために、削除した痕跡を保存します。そのため、Garbage Collectしていたとしても、データは必ず増え続けます。  
-パスフレーズ設定と同様に、完全に同期されているのであれば、データを失う可能性は低いです。  
-また、同様にデータベースのロック等の処理も行われます。
-
-- Drop and send
-デバイスとリモートのデータベースを破棄し、ロックしてからデバイスのファイルでデータベースを構築後、リモートに上書きします。
-- Drop and receive
-デバイスのデータベースを破棄した後、リモートから、操作しているデバイスに関してロックを解除し、データを受信して再構築します。
+- このデバイスの同期状態をリセット (Reset Synchronisation on This Device)
+ローカルのデータベースを破棄し、リモートのデータから再構築します。
+- このデバイスのファイルでサーバーデータを上書き (Overwrite Server Data with This Device's Files)
+ローカルおよびリモートのデータベースをこのデバイス上のファイルで再構築（上書き）します。
 
 ### Lock remote database
 リモートのデータベースをロックし、他の端末で同期を行おうとしてもエラーとともに同期がキャンセルされるように設定します。これは、データベースの再構築を行った場合、自動的に設定されるものと同じものです。
 
 万が一同期に不具合が発生していて、使用しているデバイスのデータ＋サーバーのデータを保護する場合などに、緊急避難的に使用してください。
 
-### Suspend file watching
-ファイルの更新の監視を止めます。
+### Scram スイッチ (Scram Switches)
+データベースの破損や予期しないデータ喪失を防ぐために、同期処理を緊急停止するためのスイッチです。重大な設定不一致や同期エラーが発生した場合、プラグインは自動的に Scram 状態に移行し、同期動作を一時停止することがあります。
 
+#### ファイルの更新監視を一時停止 (Suspend file watching)
+設定キー: suspendFileWatching
 
-これ以降の操作は、暗号化設定のApplyや、Drop Historyで行われる処理を手動で行うためのオプションです。
+ローカルファイル変更の監視と検知を停止します。
 
-あまり使用することはありませんがいざというときに使用します。
+#### データベース反映を一時停止 (Suspend database reflecting)
+設定キー: suspendParseReplicationResult
 
-### reset remote database
-リモートのデータベースを破棄します。
+データベースでの変更をストレージファイル（Vault内のファイル）へ書き戻す処理を停止します。
 
-### reset local database
-ローカルのデータベースを破棄します。
+### 互換性（メタデータ）(Compatibility (Metadata))
 
-### initialize local database again
-デバイスのデータベースを破棄し、実ファイルから再度データベースを構築します。
+#### 削除済みファイルのメタデータを保持しない (Do not keep metadata of deleted files.)
+設定キー: deleteMetadataOfDeletedFiles
+
+ファイルを削除した際に、そのファイルの同期履歴メタデータも即座にデータベースから削除し、保持しないようにします。
+
+#### 削除済みデータのメタデータをクリーンナップする (Delete old metadata of deleted files on start-up)
+設定キー: automaticallyDeleteMetadataOfDeletedFiles
+
+ファイルを削除した際のメタデータを保持する期間（日数）を設定します。指定した日数を経過した古い削除済みファイルのメタデータは、プラグイン起動時にデータベースから自動的に削除（クリーンナップ）されます。`0` を指定すると自動削除は無効になります。
+
+### 破損している可能性があるファイルも処理する
+設定キー: processSizeMismatchedFiles
+
+サイズ不一致のあるファイルを処理します。特定のAPIや外部連携によって作成されたファイルを同期する際に役立ちます。
+
+### Remediation
+
+#### イベント反映時の最大ファイル更新日時
+設定キー: maxMTimeForReflectEvents
+
+この値（Unixエポックからの秒数）より新しい更新日時を持つファイルについては、イベントの反映を無視します。0を指定すると制限が無効になります。
 
 ### Corrupted data
 ![CorruptedData](../images/corrupted_data.png)

docs/setup_cloudant.md

@@ -13,7 +13,7 @@ In these instructions, create IBM Cloudant Instance for trial.
 1. You can choose "Lite plan" for free.  
    ![step 3](../instruction_images/cloudant_3.png)
 
-1. Select Multitenant(it's the default) and the region as you like.  
+1. Select Multitenant (it is the default) and the region as you like.  
    ![step 4](../instruction_images/cloudant_4.png)
 
 1. Be sure to select "IAM and Legacy credentials" for "Authentication Method".  
@@ -28,20 +28,20 @@ In these instructions, create IBM Cloudant Instance for trial.
 1. When all of the above steps have been done, open "Resource list" on the left pane. you can see the Cloudant instance in the "Service and software". Click it.  
    ![step 8](../instruction_images/cloudant_8.png)
 
-1. In resource details, there's information to connect from Self-hosted LiveSync.  
-   Copy the "External Endpoint(preferred)" address. <sup>(\*1)</sup>. We use this address later, with the database name.  
+1. In resource details, there is information to connect from Self-hosted LiveSync.  
+   Copy the "External Endpoint (preferred)" address. <sup>(\*1)</sup>. We use this address later, with the database name.  
    ![step 9](../instruction_images/cloudant_9.png)
 
 ## Database setup
 
 1.  Hit the "Launch Dashboard" button, Cloudant dashboard will be shown.  
-    Yes, it's almost CouchDB's fauxton.  
+    Yes, it is almost CouchDB's fauxton.  
     ![step 1](../instruction_images/couchdb_1.png)
 
 1.  First, you have to enable the CORS option.  
     Hit the Account menu and open the "CORS" tab.  
     Initially, "Origin Domains" is set to "Restrict to specific domains"., so set to "All domains(\*)"  
-    _NOTE: of course We want to set "app://obsidian.md" but it's not acceptable on Cloudant._
+    _NOTE: of course We want to set "app://obsidian.md" but it is not acceptable on Cloudant._
     ![step 2](../instruction_images/couchdb_2.png)
 
 1.  Next, Open the "Databases" tab and hit the "Create Database" button.  
@@ -55,10 +55,10 @@ In these instructions, create IBM Cloudant Instance for trial.
 
 ### Credentials Setup
 
-1.  Back into IBM Cloud, Open the "Service credentials". You'll get an empty list, hit the "New credential" button.  
+1.  Back into IBM Cloud, Open the "Service credentials". You will get an empty list, hit the "New credential" button.  
     ![step 1](../instruction_images/credentials_1.png)
 
-1.  The dialog to create a credential will be shown.  
+1.  The dialogue to create a credential will be shown.  
     type any name or leave it default, hit the "Add" button.  
     ![step 2](../instruction_images/credentials_2.png)  
     _NOTE: This "name" is not related to your username that uses in Self-hosted LiveSync._
@@ -68,14 +68,14 @@ In these instructions, create IBM Cloudant Instance for trial.
     ![step 3](../instruction_images/credentials_3.png)  
     The username and password pair is inside this JSON.  
     "username" and "password" are so.  
-    follow the figure, it's  
+    follow the figure, it is  
     "apikey-v2-2unu15184f7o8emr90xlqgkm2ncwhbltml6tgnjl9sd5"<sup>(\*3)</sup> and "c2c11651d75497fa3d3c486e4c8bdf27"<sup>(\*4)</sup>
 
-## Self-hosted LiveSync setting
+## Self-hosted LiveSync settings
 
 ![Setting](../images/remote_db_setting.png)
 
-The Setting should be as below:
+The settings should be as follows:
 
 | Items         | Value | example                                                           |
 | ------------- | ----- | ----------------------------------------------------------------- |

docs/setup_flyio.md

@@ -0,0 +1,252 @@
+<!-- For translation: 20240209r0 -->
+# Setup CouchDB on fly.io
+
+This is how to configure fly.io and CouchDB on it for Self-hosted LiveSync.
+
+> [!WARNING]
+> It is **your** instance. In Obsidian, we have files locally. Hence, do not hesitate to destroy the remote database if you feel something have got weird. We can launch and switch to the new CouchDB instance anytime[^1].
+> 
+[^1]: Actually, I am always building the database for reproduction of the issue like so.
+
+> [!NOTE] 
+> **What and why is the Fly.io?**  
+> At some point, we started to experience problems related to our IBM Cloudant account. At the same time, Self-hosted LiveSync started to improve its functionality, requiring CouchDB in a more natural state to use all its features.
+>
+> Then we found Fly.io. Fly.io is the PaaS Platform, which can be useable for a very reasonable price. It generally falls within the `Free Allowances` range in most cases.
+
+## Required materials
+
+- A valid credit or debit card.
+
+## Setup CouchDB instance
+
+### A. Very automated setup
+
+[![LiveSync Setup onto Fly.io SpeedRun 2024 using Google Colab](https://img.youtube.com/vi/7sa_I1832Xc/0.jpg)](https://www.youtube.com/watch?v=7sa_I1832Xc)
+
+1. Open [setup-flyio-on-the-fly-v2.ipynb](../setup-flyio-on-the-fly-v2.ipynb).
+2. Press the `Open in Colab` button.
+3. Choose a region and run all blocks (Refer to video).
+   1. If you do not have the account yet, the sign-up page will be shown, please follow the instructions. The [Official document is here](https://fly.io/docs/hands-on/sign-up/).
+4. Copy the Setup-URI and Use it in the Obsidian.
+5. You have been synchronised. Use the Setup-URI in subsequent devices.
+
+Steps 4 and 5 are detailed in the [Quick Setup](./quick_setup.md#1-using-setup-uris).
+
+> [!NOTE]
+> Your automatically configured configurations will be shown on the result in the Colab note like below, and **it will not be saved**. Please make a note of it somewhere.
+> ```
+> -- YOUR CONFIGURATION --
+> URL     : https://billowing-dawn-6619.fly.dev
+> username: billowing-cherry-22580
+> password: misty-dew-13571
+> region  : nrt
+> ```
+
+### B. Scripted Setup
+
+Please refer to the document of [deploy-server.sh](../utils/readme.md#deploy-serversh).
+
+### C. Manual Setup
+
+| Used in the text | Meaning and where to use    | Memo                                                                     |
+| ---------------- | --------------------------- | ------------------------------------------------------------------------ |
+| campanella       | Username                    | It is less likely to fail if it consists only of letters and numbers.    |
+| dfusiuada9suy    | Password                    |                                                                          |
+| nrt              | Region to make the instance | We can use any [region](https://fly.io/docs/reference/regions/) near us. |
+
+#### 1. Install flyctl
+
+- Mac or Linux
+
+```sh
+$ curl -L https://fly.io/install.sh | sh
+```
+
+- Windows
+
+```powershell
+$ iwr https://fly.io/install.ps1 -useb | iex
+```
+
+#### 2. Sign up or Sign in to fly.io
+
+- Sign up
+
+```bash
+$ fly auth signup
+```
+
+- Sign in
+
+```bash
+$ fly auth login
+```
+
+For more information, please refer to [Sign up](https://fly.io/docs/hands-on/sign-up/) and [Sign in](https://fly.io/docs/hands-on/sign-in/).
+
+#### 3. Make a configuration file
+
+1. Make `fly.toml` from template `fly.template.toml`.  
+   We can simply copy and rename the file. The template is on [utils/flyio/fly.template.toml](../utils/flyio/fly.template.toml)
+2. Decide the instance name, initialize the App, and set credentials.
+
+>[!TIP]
+> - The name `billowing-dawn-6619` is randomly decided name, and it will be a part of the CouchDB URL. It should be globally unique. Therefore, it is recommended to use something random for this name.
+> - Explicit naming is very good for humans. However, we do not often get the chance to actually enter this manually (have designed so). This database may contain important information for you. The needle should be hidden in the haystack.
+
+
+```bash
+$ fly launch --name=billowing-dawn-6619 --env="COUCHDB_USER=campanella" --copy-config=true --detach --no-deploy --region nrt --yes
+$ fly secrets set COUCHDB_PASSWORD=dfusiuada9suy
+```
+
+#### 4. Deploy
+
+```
+$ flyctl deploy 
+An existing fly.toml file was found
+Using build strategies '[the "couchdb:latest" docker image]'. Remove [build] from fly.toml to force a rescan
+Creating app in /home/vorotamoroz/dev/obsidian-livesync/utils/flyio
+We're about to launch your app on Fly.io. Here's what you're getting:
+
+Organization: vorotamoroz              (fly launch defaults to the personal org)
+Name:         billowing-dawn-6619     (specified on the command line)
+Region:       Tokyo, Japan             (specified on the command line)
+App Machines: shared-cpu-1x, 256MB RAM (specified on the command line)
+Postgres:     <none>                   (not requested)
+Redis:        <none>                   (not requested)
+
+Created app 'billowing-dawn-6619' in organization 'personal'
+Admin URL: https://fly.io/apps/billowing-dawn-6619
+Hostname: billowing-dawn-6619.fly.dev
+Wrote config file fly.toml
+Validating /home/vorotamoroz/dev/obsidian-livesync/utils/flyio/fly.toml
+Platform: machines
+✓ Configuration is valid
+Your app is ready! Deploy with `flyctl deploy`
+Secrets are staged for the first deployment
+==> Verifying app config
+Validating /home/vorotamoroz/dev/obsidian-livesync/utils/flyio/fly.toml
+Platform: machines
+✓ Configuration is valid
+--> Verified app config
+==> Building image
+Searching for image 'couchdb:latest' remotely...
+image found: img_ox20prk63084j1zq
+
+Watch your deployment at https://fly.io/apps/billowing-dawn-6619/monitoring
+
+Provisioning ips for billowing-dawn-6619
+  Dedicated ipv6: 2a09:8280:1::37:fde9
+  Shared ipv4: 66.241.124.163
+  Add a dedicated ipv4 with: fly ips allocate-v4
+
+Creating a 1 GB volume named 'couchdata' for process group 'app'. Use 'fly vol extend' to increase its size
+This deployment will:
+ * create 1 "app" machine
+
+No machines in group app, launching a new machine
+
+WARNING The app is not listening on the expected address and will not be reachable by fly-proxy.
+You can fix this by configuring your app to listen on the following addresses:
+  - 0.0.0.0:5984
+Found these processes inside the machine with open listening sockets:
+  PROCESS        | ADDRESSES                             
+-----------------*---------------------------------------
+  /.fly/hallpass | [fdaa:0:73b9:a7b:22e:3851:7f28:2]:22  
+
+Finished launching new machines
+
+NOTE: The machines for [app] have services with 'auto_stop_machines = true' that will be stopped when idling
+
+-------
+Checking DNS configuration for billowing-dawn-6619.fly.dev
+
+Visit your newly deployed app at https://billowing-dawn-6619.fly.dev/
+```
+
+#### 5. Apply CouchDB configuration
+
+After the initial setup, CouchDB needs some more customisations to be used from Self-hosted LiveSync. It can be configured in browsers or by HTTP-REST APIs.
+
+This section is set up using the REST API.
+
+1. Prepare environment variables.
+
+- Mac or Linux:
+
+```bash
+export couchHost=https://billowing-dawn-6619.fly.dev
+export couchUser=campanella
+export couchPwd=dfusiuada9suy
+```
+
+- Windows
+
+```powershell
+set couchHost https://billowing-dawn-6619.fly.dev
+set couchUser campanella
+set couchPwd dfusiuada9suy
+$creds = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("${couchUser}:${couchPwd}"))
+```
+
+2. Perform cluster setup
+
+- Mac or Linux
+
+```bash
+curl -X POST "${couchHost}/_cluster_setup" -H "Content-Type: application/json" -d "{\"action\":\"enable_single_node\",\"username\":\"${couchUser}\",\"password\":\"${couchPwd}\",\"bind_address\":\"0.0.0.0\",\"port\":5984,\"singlenode\":true}"  --user "${couchUser}:${couchPwd}"
+```
+
+- Windows
+
+```powershell
+iwr -UseBasicParsing -Method 'POST' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds } "${couchHost}/_cluster_setup" -Body "{""action"":""enable_single_node"",""username"":""${couchUser}"",""password"":""${couchPwd}"",""bind_address"":""0.0.0.0"",""port"":5984,""singlenode"":true}"
+```
+
+Note: if the response code is not 200. We have to retry the request once again.
+If you run the request several times and it does not result in 200, something is wrong. Please report it.
+
+3. Configure parameters
+
+- Mac or Linux
+
+```bash
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/chttpd/require_valid_user" -H "Content-Type: application/json" -d '"true"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/chttpd_auth/require_valid_user" -H "Content-Type: application/json" -d '"true"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/httpd/WWW-Authenticate" -H "Content-Type: application/json" -d '"Basic realm=\"couchdb\""' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/httpd/enable_cors" -H "Content-Type: application/json" -d '"true"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/chttpd/enable_cors" -H "Content-Type: application/json" -d '"true"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/chttpd/max_http_request_size" -H "Content-Type: application/json" -d '"4294967296"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/couchdb/max_document_size" -H "Content-Type: application/json" -d '"50000000"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/cors/credentials" -H "Content-Type: application/json" -d '"true"' --user "${couchUser}:${couchPwd}"
+curl -X PUT "${couchHost}/_node/nonode@nohost/_config/cors/origins" -H "Content-Type: application/json" -d '"app://obsidian.md,capacitor://localhost,http://localhost"' --user "${couchUser}:${couchPwd}"
+```
+
+- Windows
+
+```powershell
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/chttpd/require_valid_user" -Body  '"true"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/chttpd_auth/require_valid_user" -Body  '"true"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/httpd/WWW-Authenticate" -Body  '"Basic realm=\"couchdb\""'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/httpd/enable_cors" -Body  '"true"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/chttpd/enable_cors" -Body  '"true"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/chttpd/max_http_request_size" -Body  '"4294967296"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/couchdb/max_document_size" -Body  '"50000000"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/cors/credentials" -Body  '"true"'
+iwr -UseBasicParsing -Method 'PUT' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds }  "${couchHost}/_node/nonode@nohost/_config/cors/origins" -Body  '"app://obsidian.md,capacitor://localhost,http://localhost"'
+```
+
+Note: Each of these should also be repeated until finished in 200.
+
+#### 6. Use it from Self-hosted LiveSync
+
+Now the CouchDB is ready to use from Self-hosted LiveSync. We can use `https://billowing-dawn-6619.fly.dev` in URI, `campanella` in `Username` and `dfusiuada9suy` in `Password` on Self-hosted LiveSync. The `Database name` could be anything you want.
+Please refer to the [Minimal Setup of the Quick Setup](./quick_setup.md#2-minimal-setup).
+
+## Delete the Instance
+
+If you want to delete the CouchDB instance, you can do that in [fly.io Dashboard](https://fly.io/dashboard/personal)
+
+If you have done with [B. Scripted Setup](#b-scripted-setup), we can use [delete-server.sh](../utils/readme.md#delete-serversh).

docs/setup_object_storage.md

@@ -0,0 +1,108 @@
+# Set up Object Storage
+
+This guide establishes Object Storage synchronisation on a first device, generates an additional-device Setup URI from that working device, and verifies synchronisation in both directions.
+
+Object Storage uses the S3-compatible API. Prepare the following before starting:
+
+- an HTTPS endpoint reachable by every device;
+- an access key and secret key with access to the selected bucket;
+- a bucket name and region;
+- a unique bucket prefix when the bucket is shared; and
+- separate passphrases for Vault encryption and Setup URI encryption.
+
+Back up every Vault involved, and do not use Obsidian Sync, iCloud synchronisation, or another synchronisation service on the same Vault.
+
+## Generate the bootstrap Setup URI
+
+The public generator applies the Object Storage preset and records the connection as the selected remote profile. Run it from a trusted terminal:
+
+```sh
+export remote_type=s3
+export endpoint=https://objects.example.com
+export access_key=<ACCESS KEY>
+export secret_key=<SECRET KEY>
+export bucket=vault-data
+export region=auto
+export bucket_prefix=my-vault
+export passphrase=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export uri_passphrase=<A SEPARATE SETUP URI PASSPHRASE>
+deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
+```
+
+For providers which require them, set `force_path_style`, `use_custom_request_handler`, or `bucket_custom_headers` as described in the [setup utility reference](../utils/readme.md#object-storage).
+
+Store the generated Setup URI and Setup URI passphrase separately. The URI is encrypted, but it contains the Object Storage credentials.
+
+## Set up the first device
+
+Use a new bucket prefix, or a prefix whose contents you deliberately intend to replace.
+
+1. Install and enable Self-hosted LiveSync in the intended Vault.
+2. Open onboarding from the `Welcome to Self-hosted LiveSync` Notice.
+3. Select `I am setting this up for the first time`, then choose the recommended Setup URI method.
+4. Paste the bootstrap Setup URI, enter its passphrase, and select `Test Settings and Continue`.
+
+    ![Object Storage Setup URI on the first device](../images/object-storage-setup/guide-object-storage-setup-first-setup-uri.png)
+
+5. Select `Restart and Initialise Server`, then read and accept the final overwrite confirmation only when this Vault is the intended source of truth.
+
+    ![Object Storage first-device initialisation](../images/object-storage-setup/guide-object-storage-setup-first-initialise.png)
+
+    ![Final Object Storage overwrite confirmation](../images/object-storage-setup/guide-object-storage-setup-first-rebuild-confirmation.png)
+
+6. A new prefix may show `Fetch Remote Configuration Failed` because it has no saved configuration. Select `Skip and proceed` only for a genuinely new prefix. Otherwise, stop and check the endpoint, credentials, bucket, and prefix.
+
+    ![Expected missing remote configuration for a new Object Storage prefix](../images/object-storage-setup/guide-object-storage-setup-missing-remote-configuration.png)
+
+7. Keep optional features disabled until ordinary note synchronisation works.
+8. Create an ordinary test note, and keep Obsidian open until the LiveSync progress indicators have cleared.
+
+## Generate the second-device Setup URI
+
+Generate a fresh Setup URI from the working first device:
+
+1. Run `Self-hosted LiveSync: Copy settings as a new Setup URI` from the command palette.
+2. Enter a new Setup URI passphrase.
+
+    ![Masked passphrase for the additional-device Object Storage Setup URI](../images/object-storage-setup/guide-object-storage-setup-copy-setup-uri-passphrase.png)
+
+3. Copy the resulting URI.
+
+    ![Object Storage Setup URI generated by the working first device](../images/object-storage-setup/guide-object-storage-setup-copy-setup-uri-result.png)
+
+Store this URI and its passphrase separately.
+
+## Add another device
+
+Start with a new or separately backed-up Vault.
+
+1. Install and enable Self-hosted LiveSync.
+2. Open onboarding, select `I am adding a device to an existing synchronisation setup`, and choose the recommended Setup URI method.
+3. Enter the URI generated by the first device and its passphrase.
+
+    ![First-device Object Storage Setup URI entered on the second device](../images/object-storage-setup/guide-object-storage-setup-second-setup-uri.png)
+
+4. Select `Restart and Fetch Data`.
+
+    ![Object Storage Fetch confirmation on the second device](../images/object-storage-setup/guide-object-storage-setup-second-fetch.png)
+
+5. For a new or empty Vault, choose `Overwrite all with remote files`, then `Keep local files even if not on remote`. Review the [Fast Setup guide](./tips/fast-setup.md) before choosing a different policy for a Vault containing local work.
+
+    ![Object Storage retrieval method](../images/object-storage-setup/guide-object-storage-setup-retrieval-method.png)
+
+    ![Object Storage local-file policy](../images/object-storage-setup/guide-object-storage-setup-local-file-policy.png)
+
+6. Keep Obsidian open until retrieval and file reflection finish.
+
+Confirm that the first device's test note appears unchanged. Create a second ordinary note on the new device, wait for its journal synchronisation to finish, and confirm that it reaches the first device. Configure optional features only after this two-way check passes.
+
+![First-device note received by the second Object Storage device](../images/object-storage-setup/guide-object-storage-setup-first-to-second.png)
+
+![Second-device note received by the first Object Storage device](../images/object-storage-setup/guide-object-storage-setup-second-to-first.png)
+
+## Safety notes
+
+- Treat the endpoint, bucket, prefix, access key, secret key, Vault passphrase, Setup URI, and Setup URI passphrase as sensitive.
+- Use a distinct prefix per synchronisation set unless shared data is explicitly intended.
+- Do not select first-device initialisation against an existing prefix unless replacing its contents is deliberate.
+- Object Storage is not a Vault backup. Keep independent backups and test restoration separately.

docs/setup_own_server.md

@@ -1,88 +1,212 @@
-# Setup CouchDB to your server
+# Setup a CouchDB server
 
+## Table of Contents
 
-## Install CouchDB and access from PC or Mac
+- [Setup a CouchDB server](#setup-a-couchdb-server)
+  - [Table of Contents](#table-of-contents)
+  - [1. Prepare CouchDB](#1-prepare-couchdb)
+    - [A. Using Docker](#a-using-docker)
+      - [1. Prepare](#1-prepare)
+      - [2. Run docker container](#2-run-docker-container)
+    - [B. Using Docker Compose](#b-using-docker-compose)
+      - [1. Prepare](#1-prepare-1)
+      - [2. Creating Compose file](#2-create-a-docker-composeyml-file-with-the-following-added-to-it)
+      - [3. Boot check](#3-run-the-docker-compose-file-to-boot-check)
+      - [4. Starting Docker Compose in background](#4-run-the-docker-compose-file-in-the-background)
+    - [C. Install CouchDB directly](#c-install-couchdb-directly)
+  - [2. Run couchdb-init.sh for initialise](#2-run-couchdb-initsh-for-initialise)
+  - [3. Expose CouchDB to the Internet](#3-expose-couchdb-to-the-internet)
+  - [4. Client Setup](#4-client-setup)
+    - [1. Generate the setup URI on a desktop device or server](#1-generate-the-setup-uri-on-a-desktop-device-or-server)
+    - [2. Setup Self-hosted LiveSync to Obsidian](#2-setup-self-hosted-livesync-to-obsidian)
+  - [Manual setup information](#manual-setup-information)
+    - [Setting up your domain](#setting-up-your-domain)
+  - [Reverse Proxies](#reverse-proxies)
+    - [Traefik](#traefik)
+    - [Nginx](#nginx)
+---
 
-The easiest way to set up the CouchDB is using the [docker image]((https://hub.docker.com/_/couchdb)).
+## 1. Prepare CouchDB
+### A. Using Docker
 
-But some additional configurations are required in `local.ini` to use from Self-hosted LiveSync, like below:
+#### 1. Prepare
+```bash
 
-```
-[couchdb]
-single_node=true
+# Adding environment variables.
+export hostname=http://localhost:5984
+export username=goojdasjdas     #Please change as you like.
+export password=kpkdasdosakpdsa #Please change as you like
 
-[chttpd]
-require_valid_user = true
-
-[chttpd_auth]
-require_valid_user = true
-authentication_redirect = /_utils/session.html
-
-[httpd]
-WWW-Authenticate = Basic realm="couchdb"
-enable_cors = true
-
-[cors]
-origins = app://obsidian.md,capacitor://localhost,http://localhost
-credentials = true
-headers = accept, authorization, content-type, origin, referer
-methods = GET, PUT, POST, HEAD, DELETE
-max_age = 3600
+# Creating the save data & configuration directories.
+mkdir couchdb-data
+mkdir couchdb-etc
 ```
 
-Make `local.ini` and run with docker run like this, you can launch the CouchDB.
+#### 2. Run docker container
+1. Boot Check.
 ```
-$ docker run --rm -it -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password -v .local.ini:/opt/couchdb/etc/local.ini -p 5984:5984 couchdb
+$ docker run --name couchdb-for-ols --rm -it -e COUCHDB_USER=${username} -e COUCHDB_PASSWORD=${password} -v ${PWD}/couchdb-data:/opt/couchdb/data -v ${PWD}/couchdb-etc:/opt/couchdb/etc/local.d -p 5984:5984 couchdb
 ```
-Note: At this time, the file owner of local.ini became 5984:5984. It's the limitation docker image. please change the owner before editing local.ini again.
+> [!WARNING]
+> If your container threw an error or exited unexpectedly, please check the permission of couchdb-data, and couchdb-etc.  
+> Once CouchDB starts, these directories will be owned by uid:`5984`. Please chown it for that uid again.
 
-If you could confirm that Self-hosted LiveSync can sync with the server, launch docker image as background as you like.
-
-example)
+2. Enable it in the background
 ```
-$ docker run -d --restart always -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password -v .local.ini:/opt/couchdb/etc/local.ini -p 5984:5984 couchdb
+$ docker run --name couchdb-for-ols -d --restart always -e COUCHDB_USER=${username} -e COUCHDB_PASSWORD=${password} -v ${PWD}/couchdb-data:/opt/couchdb/data -v ${PWD}/couchdb-etc:/opt/couchdb/etc/local.d -p 5984:5984 couchdb
 ```
 
-## Access from mobile device
-If you want to access Self-hosted LiveSync from mobile devices, you need a valid SSL certificate.
+Congrats, move on to [step 2](#2-run-couchdb-initsh-for-initialise)
+### B. Using Docker Compose
 
-### Testing from mobile
-In the testing phase, [localhost.run](http://localhost.run/) or something like services is very useful.
+#### 1. Prepare
 
-example on using localhost.run)
 ```
-$ ssh -R 80:localhost:5984 nokey@localhost.run
-Warning: Permanently added the RSA host key for IP address '35.171.254.69' to the list of known hosts.
+# Creating the save data & configuration directories.
+mkdir couchdb-data
+mkdir couchdb-etc
 
-===============================================================================
-Welcome to localhost.run!
-
-Follow your favourite reverse tunnel at [https://twitter.com/localhost_run].
-
-**You need a SSH key to access this service.**
-If you get a permission denied follow Gitlab's most excellent howto:
-https://docs.gitlab.com/ee/ssh/
-*Only rsa and ed25519 keys are supported*
-
-To set up and manage custom domains go to https://admin.localhost.run/
-
-More details on custom domains (and how to enable subdomains of your custom
-domain) at https://localhost.run/docs/custom-domains
-
-To explore using localhost.run visit the documentation site:
-https://localhost.run/docs/
-
-===============================================================================
-
-
-** your connection id is xxxxxxxxxxxxxxxxxxxxxxxxxxxx, please mention it if you send me a message about an issue. **
-
-xxxxxxxx.localhost.run tunneled with tls termination, https://xxxxxxxx.localhost.run
-Connection to localhost.run closed by remote host.
-Connection to localhost.run closed.
+# Changing perms to user 5984.
+chown -R 5984:5984 ./couchdb-data
+chown -R 5984:5984 ./couchdb-etc
 ```
 
-https://xxxxxxxx.localhost.run is the temporary server address.
+#### 2. Create a `docker-compose.yml` file with the following added to it
+```
+services:
+  couchdb:
+    image: couchdb:latest
+    container_name: couchdb-for-ols
+    user: 5984:5984
+    environment:
+      - COUCHDB_USER=<INSERT USERNAME HERE>  #Please change as you like.
+      - COUCHDB_PASSWORD=<INSERT PASSWORD HERE> #Please change as you like.
+    volumes:
+      - ./couchdb-data:/opt/couchdb/data
+      - ./couchdb-etc:/opt/couchdb/etc/local.d
+    ports:
+      - 5984:5984
+    restart: unless-stopped
+```
+
+#### 3. Run the Docker Compose file to boot check
+
+```
+docker compose up
+# Or if using the old version
+docker-compose up
+```
+> [!WARNING]
+> If your container threw an error or exited unexpectedly, please check the permission of couchdb-data, and couchdb-etc.  
+> Once CouchDB starts, these directories will be owned by uid:`5984`. Please chown it for that uid again.
+
+#### 4. Run the Docker Compose file in the background
+If all went well and didn't throw any errors, `CTRL+C` out of it, and then run this command
+```
+docker compose up -d
+# Or if using the old version
+docker-compose up -d
+```
+
+Congrats, move on to [step 2](#2-run-couchdb-initsh-for-initialise)
+
+
+### C. Install CouchDB directly
+Please refer to the [official document](https://docs.couchdb.org/en/stable/install/index.html). However, we do not have to configure it fully. Just the administrator needs to be configured.
+
+## 2. Run couchdb-init.sh for initialise
+
+Deno 2 is required. Export the CouchDB connection and database details, then run the provisioning wrapper:
+
+```
+export hostname=http://localhost:5984
+export username=<INSERT USERNAME HERE>
+export password=<INSERT PASSWORD HERE>
+export database=obsidiannotes
+curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash
+```
+
+If it results like the following:
+```
+CouchDB provisioning completed.
+```
+
+The wrapper runs the exact registry-pinned Commonlib consumer. When `database` is supplied, it creates the database and initialises its LiveSync database-version document through Commonlib. Without `database`, it configures only the CouchDB server.
+
+If you are using Docker Compose and the above command does not work or displays `ERROR: Hostname missing`, you can try running the following command, replacing the placeholders with your own values:
+```
+curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | hostname=http://<YOUR SERVER IP>:5984 username=<INSERT USERNAME HERE> password=<INSERT PASSWORD HERE> database=obsidiannotes bash
+```
+
+## 3. Expose CouchDB to the Internet
+
+- You can skip this instruction if you using only in intranet and only with desktop devices.
+  - For mobile devices, Obsidian requires a valid SSL certificate. Usually, it needs exposing the internet.
+
+Whatever solutions we can use. For simplicity, the following sample uses Cloudflare Zero Trust for testing.
+
+```
+cloudflared tunnel --url http://localhost:5984
+```
+
+You will then get the following output:
+
+```
+2024-02-14T10:35:25Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
+2024-02-14T10:35:25Z INF Requesting new quick Tunnel on trycloudflare.com...
+2024-02-14T10:35:26Z INF +--------------------------------------------------------------------------------------------+
+2024-02-14T10:35:26Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
+2024-02-14T10:35:26Z INF |  https://tiles-photograph-routine-groundwater.trycloudflare.com                            |
+2024-02-14T10:35:26Z INF +--------------------------------------------------------------------------------------------+
+  :
+  :
+  :
+```
+Now `https://tiles-photograph-routine-groundwater.trycloudflare.com` is our server. Make it into the background once, please.
+
+
+## 4. Client Setup
+> [!TIP]
+> Now manual configuration is not recommended for some reasons. However, if you want to do so, please use `Setup wizard`. The recommended extra configurations will be also set.
+
+### 1. Generate the setup URI on a desktop device or server
+```bash
+export hostname=https://tiles-photograph-routine-groundwater.trycloudflare.com
+export database=obsidiannotes
+export username=johndoe
+export password=<INSERT THE COUCHDB PASSWORD>
+export passphrase=<INSERT A STRONG VAULT ENCRYPTION PASSPHRASE>
+export uri_passphrase=<INSERT A SEPARATE SETUP URI PASSPHRASE> # Optional
+deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
+```
+
+> [!TIP]
+> `passphrase` protects the synchronised Vault data with end-to-end encryption. `uri_passphrase` protects only the Setup URI. Use different values, store both securely, and do not send the Setup URI and its passphrase through the same channel.
+>
+> If `uri_passphrase` is omitted, the generator creates a cryptographically random value and prints it once.
+
+The generator consumes the exact registry-pinned Commonlib release used by the provisioning utility. It creates a configured CouchDB remote profile, applies the current new-Vault defaults, and encodes them with Commonlib's Setup URI contract.
+
+You will then get the following output:
+
+```bash
+Generated couchdb Setup URI.
+Your passphrase for the Setup URI is: H7vX...a-random-32-character-value
+This passphrase is never shown again, so store it safely.
+obsidian://setuplivesync?settings=%5B%22tm2DpsOE74nJAryprZO2M93wF%2Fvg.......4b26ed33230729%22%5D
+```
+
+Store the Setup URI and its passphrase separately.
+
+### 2. Setup Self-hosted LiveSync to Obsidian
+
+Follow [Quick setup](./quick_setup.md#set-up-the-first-device) for the first device. It covers the current onboarding Notice, Setup URI import, server initialisation, and the safety prompts shown for a newly provisioned database.
+
+After ordinary note synchronisation works, [generate a new Setup URI on that first device](./quick_setup.md#create-a-setup-uri-for-another-device), then follow [Add another device](./quick_setup.md#add-another-device). Do not make the second device depend on retaining the provisioning-time bootstrap URI. Configure optional features only after the normal path is verified; [Hidden File Sync has its own guide](./tips/hidden-file-sync.md).
+
+---
+
+## Manual setup information
 
 ### Setting up your domain
 
@@ -90,6 +214,176 @@ Set the A record of your domain to point to your server, and host reverse proxy
 Note: Mounting CouchDB on the top directory is not recommended.  
 Using Caddy is a handy way to serve the server with SSL automatically.
 
-I have published [docker-compose.yml and ini files](https://github.com/vrtmrz/self-hosted-livesync-server) that launches Caddy and CouchDB at once. Please try it out.
+I have published [docker-compose.yml and ini files](https://github.com/vrtmrz/self-hosted-livesync-server) that launch Caddy and CouchDB at once. If you are using Traefik you can check the [Reverse Proxies](#reverse-proxies) section below.
 
-And, be sure to check the server log and be careful of malicious access.
+And, be sure to check the server log and be careful of malicious access.
+
+
+## Reverse Proxies
+
+### Traefik
+
+If you are using Traefik, this [docker-compose.yml](https://github.com/vrtmrz/obsidian-livesync/blob/main/docker-compose.traefik.yml) file (also pasted below) has all the right CORS parameters set. It assumes you have an external network called `proxy`.
+
+```yaml
+services:
+  couchdb:
+    image: couchdb:latest
+    container_name: obsidian-livesync
+    user: 1000:1000
+    environment:
+      - COUCHDB_USER=username
+      - COUCHDB_PASSWORD=password
+    volumes:
+      - ./data:/opt/couchdb/data
+      - ./local.ini:/opt/couchdb/etc/local.ini
+    # Ports not needed when already passed to Traefik
+    #ports:
+    #  - 5984:5984
+    restart: unless-stopped
+    networks:
+      - proxy
+    labels:
+      - "traefik.enable=true"
+      # The Traefik Network
+      - "traefik.docker.network=proxy"
+      # Don't forget to replace 'obsidian-livesync.example.org' with your own domain
+      - "traefik.http.routers.obsidian-livesync.rule=Host(`obsidian-livesync.example.org`)"
+      # The 'websecure' entryPoint is basically your HTTPS entrypoint. Check the next code snippet if you are encountering problems only; you probably have a working traefik configuration if this is not your first container you are reverse proxying.
+      - "traefik.http.routers.obsidian-livesync.entrypoints=websecure"
+      - "traefik.http.routers.obsidian-livesync.service=obsidian-livesync"
+      - "traefik.http.services.obsidian-livesync.loadbalancer.server.port=5984"
+      - "traefik.http.routers.obsidian-livesync.tls=true"
+      # Replace the string 'letsencrypt' with your own certificate resolver
+      - "traefik.http.routers.obsidian-livesync.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.obsidian-livesync.middlewares=obsidiancors"
+      # The part needed for CORS to work on Traefik 2.x starts here
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolallowmethods=GET,PUT,POST,HEAD,DELETE"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolallowheaders=accept,authorization,content-type,origin,referer"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolalloworiginlist=app://obsidian.md,capacitor://localhost,http://localhost"
+      - "traefik.http.middlewares.obsidiancors.headers.accesscontrolmaxage=3600"
+      - "traefik.http.middlewares.obsidiancors.headers.addvaryheader=true"
+      - "traefik.http.middlewares.obsidiancors.headers.accessControlAllowCredentials=true"
+
+networks:
+  proxy:
+    external: true
+```
+
+Partial `traefik.yml` config file mentioned in above:
+```yml
+...
+
+entryPoints:
+  web:
+    address: ":80"
+    http:
+      redirections:
+        entryPoint:
+          to: "websecure"
+          scheme: "https"
+  websecure:
+    address: ":443"
+
+...
+```
+
+### Nginx
+
+When configuring nginx as a reverse-proxy for CouchDB, note the common mistakes:
+
+1. If fast fetch progress stalls and seems to freeze indefinitely, make sure you disabled `proxy_buffering`:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5984;
+    proxy_buffering off;
+    ...
+}
+```
+
+2. If you get the "413 Entity too large" error, increase the `client_max_body_size`:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:5984;
+    client_max_body_size 50M; # Tweak the value to your needs
+    ...
+}
+```
+
+
+3. If you get the "404 Database not found" error, make sure you placed CouchDB at the root location (recommended):
+
+```nginx
+server {
+    server_name couchdb.domain.com
+
+    location / {
+        proxy_pass http://127.0.0.1:5984;
+        ...
+    }
+}
+```
+
+It is possible to place CouchDB into the subdirectory, however, the config should be modified respectively:
+
+```nginx
+
+server {
+    server_name domain.com
+
+    location /couchdb {
+        rewrite ^ $request_uri;
+        rewrite ^/couchdb/(.*) /$1 break;
+        
+        proxy_pass http://127.0.0.1:5984$uri;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        ... 
+    }
+    location /_session {
+        proxy_pass http://127.0.0.1:5984/_session;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        ...
+    }
+}
+```
+
+4. If you added custom HTTP headers in database connection advanced settings, make sure to update both nginx and CouchDB configurations:
+
+Nginx:
+```nginx
+location / {
+    set $pass 1; 
+    
+    # Example of handling custom HTTP header
+    if ($http_x_custom_header != 'foo'){ 
+        set $pass 0; 
+    } 
+
+    # Important: OPTIONS requests don't carry headers, so they should always be proxied to the CouchDB
+    if ($request_method = 'OPTIONS') { 
+        set $pass 1; 
+    } 
+
+    if ($pass = 0) { 
+        return 403; 
+    } 
+
+    proxy_pass http://127.0.0.1:5984;
+    ...
+}
+```
+
+couchdb-etc/docker.ini:
+```ini
+...
+[cors]
+credentials = true
+origins = app://obsidian.md,capacitor://localhost,http://localhost
+
+;Make sure to add your custom header to the list so CORS won't break
+headers = accept, authorization, content-type, origin, referer, x-custom-header
+```

docs/setup_own_server_cn.md

@@ -0,0 +1,152 @@
+# 在你自己的服务器上设置 CouchDB
+
+## 目录
+- [配置 CouchDB](#配置-CouchDB)
+- [运行 CouchDB](#运行-CouchDB)
+  - [Docker CLI](#docker-cli)
+  - [Docker Compose](#docker-compose)
+- [创建数据库](#创建数据库)
+- [从移动设备访问](#从移动设备访问)
+  - [移动设备测试](#移动设备测试)
+  - [设置你的域名](#设置你的域名)
+---
+
+> 注：提供了 [docker-compose.yml 和 ini 文件](https://github.com/vrtmrz/self-hosted-livesync-server) 可以同时启动 Caddy 和 CouchDB。推荐直接使用该 docker-compose 配置进行搭建。（若使用，请查阅链接中的文档，而不是这个文档）
+
+## 配置 CouchDB
+
+设置 CouchDB 的最简单方法是使用 [CouchDB docker image]((https://hub.docker.com/_/couchdb)).
+
+需要修改一些 `local.ini` 中的配置，以让它可以用于 Self-hosted LiveSync，如下：
+
+```
+[couchdb]
+single_node=true
+max_document_size = 50000000
+
+[chttpd]
+require_valid_user = true
+max_http_request_size = 4294967296
+
+[chttpd_auth]
+require_valid_user = true
+authentication_redirect = /_utils/session.html
+
+[httpd]
+WWW-Authenticate = Basic realm="couchdb"
+enable_cors = true
+
+[cors]
+origins = app://obsidian.md,capacitor://localhost,http://localhost
+credentials = true
+headers = accept, authorization, content-type, origin, referer
+methods = GET, PUT, POST, HEAD, DELETE
+max_age = 3600
+```
+
+## 运行 CouchDB
+
+### Docker CLI
+
+你可以通过指定 `local.ini` 配置运行 CouchDB:
+
+```
+$ docker run --rm -it -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password -v /path/to/local.ini:/opt/couchdb/etc/local.ini -p 5984:5984 couchdb
+```
+*记得将上述命令中的 local.ini 挂载路径替换成实际的存放路径*
+
+后台运行:
+```
+$ docker run -d --restart always -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password -v /path/to/local.ini:/opt/couchdb/etc/local.ini -p 5984:5984 couchdb
+```
+*记得将上述命令中的 local.ini 挂载路径替换成实际的存放路径*
+
+### Docker Compose
+创建一个文件夹, 将你的 `local.ini` 放在文件夹内, 然后在文件夹内创建 `docker-compose.yml`. 请确保对 `local.ini` 有读写权限并且确保在容器运行后能创建 `data` 文件夹. 文件夹结构大概如下:
+```
+obsidian-livesync
+├── docker-compose.yml
+└── local.ini
+```
+
+可以参照以下内容编辑 `docker-compose.yml`:
+```yaml
+services:
+  couchdb:
+    image: couchdb
+    container_name: obsidian-livesync
+    user: 1000:1000
+    environment:
+      - COUCHDB_USER=admin
+      - COUCHDB_PASSWORD=password
+    volumes:
+      - ./data:/opt/couchdb/data
+      - ./local.ini:/opt/couchdb/etc/local.ini
+    ports:
+      - 5984:5984
+    restart: unless-stopped
+```
+
+最后, 创建并启动容器:
+```
+# -d will launch detached so the container runs in background
+docker-compose up -d
+```
+
+## 创建数据库
+
+CouchDB 部署成功后, 需要手动创建一个数据库, 方便插件连接并同步.
+
+1. 访问 `http://localhost:5984/_utils`, 输入帐号密码后进入管理页面
+2. 点击 Create Database, 然后根据个人喜好创建数据库
+
+## 从移动设备访问
+如果你想要从移动设备访问 Self-hosted LiveSync，你需要一个合法的 SSL 证书。
+
+### 移动设备测试
+测试时，[localhost.run](http://localhost.run/) 这一类的反向隧道服务很实用。（非必须，只是用于终端设备不方便 ssh 的时候的备选方案）
+
+```
+$ ssh -R 80:localhost:5984 nokey@localhost.run
+Warning: Permanently added the RSA host key for IP address '35.171.254.69' to the list of known hosts.
+
+===============================================================================
+Welcome to localhost.run!
+
+Follow your favourite reverse tunnel at [https://twitter.com/localhost_run].
+
+**You need a SSH key to access this service.**
+If you get a permission denied follow Gitlab's most excellent howto:
+https://docs.gitlab.com/ee/ssh/
+*Only rsa and ed25519 keys are supported*
+
+To set up and manage custom domains go to https://admin.localhost.run/
+
+More details on custom domains (and how to enable subdomains of your custom
+domain) at https://localhost.run/docs/custom-domains
+
+To explore using localhost.run visit the documentation site:
+https://localhost.run/docs/
+
+===============================================================================
+
+
+** your connection id is xxxxxxxxxxxxxxxxxxxxxxxxxxxx, please mention it if you send me a message about an issue. **
+
+xxxxxxxx.localhost.run tunneled with tls termination, https://xxxxxxxx.localhost.run
+Connection to localhost.run closed by remote host.
+Connection to localhost.run closed.
+```
+
+https://xxxxxxxx.localhost.run 即为临时服务器地址。
+
+### 设置你的域名
+
+设置一个指向你服务器的 A 记录，并根据需要设置反向代理。
+
+Note: 不推荐将 CouchDB 挂载到根目录  
+可以使用 Caddy 很方便的给服务器加上 SSL 功能
+
+提供了 [docker-compose.yml 和 ini 文件](https://github.com/vrtmrz/self-hosted-livesync-server) 可以同时启动 Caddy 和 CouchDB。
+
+注意检查服务器日志，当心恶意访问。

docs/setup_own_server_ja.md

@@ -8,9 +8,11 @@ CouchDBを構築するには、[Dockerのイメージ](https://hub.docker.com/_/
 ```
 [couchdb]
 single_node=true
+max_document_size = 50000000
 
 [chttpd]
 require_valid_user = true
+max_http_request_size = 4294967296
 
 [chttpd_auth]
 require_valid_user = true

docs/setup_p2p.md

@@ -0,0 +1,121 @@
+# Set up peer-to-peer synchronisation
+
+This guide establishes a peer-to-peer synchronisation set, generates the second-device Setup URI on the working first device, and verifies synchronisation in both directions with explicit peer approval.
+
+Peer-to-peer synchronisation has no central copy of the Vault. At least one device containing the required data must be online when another device fetches it. A Nostr-compatible signalling relay helps devices discover each other, while the Vault data travels through the peer connection.
+
+Before starting:
+
+- back up both Vaults;
+- prepare a signalling relay reachable by both devices;
+- ensure the networks permit a WebRTC connection, or review the [P2P troubleshooting guidance](./tips/p2p-sync-tips.md);
+- disable every other synchronisation service for these Vaults; and
+- keep both devices awake and Obsidian open during the initial transfer.
+
+## Generate the bootstrap Setup URI
+
+Run the public generator from a trusted terminal. Supply your own relay for a controlled self-hosted setup:
+
+```sh
+export remote_type=p2p
+export p2p_relays=wss://relay.example.com
+export p2p_room_id=<A PRIVATE ROOM ID> # Optional; generated when omitted
+export p2p_passphrase=<A PRIVATE P2P PASSPHRASE> # Optional; generated when omitted
+export passphrase=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export uri_passphrase=<A SEPARATE SETUP URI PASSPHRASE>
+deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
+```
+
+The generated Setup URI contains the encrypted room, relay, and Vault settings. It deliberately omits the device-specific peer name. Store the URI and its passphrase separately.
+
+## Set up the first device
+
+1. Install and enable Self-hosted LiveSync in the intended Vault.
+2. Open onboarding from the `Welcome to Self-hosted LiveSync` Notice.
+3. Select `I am setting this up for the first time`, then choose the recommended Setup URI method.
+4. Paste the bootstrap Setup URI, enter its passphrase, and select `Test Settings and Continue`.
+
+    ![P2P Setup URI on the first device](../images/p2p-setup/guide-p2p-setup-first-setup-uri.png)
+
+5. Complete the first-device initialisation and final confirmation. This initialises the local LiveSync database; P2P has no central remote database to erase.
+
+    ![P2P local initialisation on the first device](../images/p2p-setup/guide-p2p-setup-first-initialise.png)
+
+    ![P2P local database confirmation on the first device](../images/p2p-setup/guide-p2p-setup-first-rebuild-confirmation.png)
+
+6. Keep optional features disabled until ordinary note synchronisation works.
+7. Open `Self-hosted LiveSync: Open P2P Replicator` from the command palette. Select `Open connection` if signalling is disconnected.
+
+    ![First P2P device connected to the signalling relay](../images/p2p-setup/guide-p2p-setup-first-device-connected.png)
+
+8. Create an ordinary test note and wait for the local LiveSync progress indicators to clear.
+
+## Generate the second-device Setup URI
+
+On the working first device:
+
+1. Run `Self-hosted LiveSync: Copy settings as a new Setup URI` from the command palette.
+2. Enter a new Setup URI passphrase.
+
+    ![Masked passphrase for the additional-device P2P Setup URI](../images/p2p-setup/guide-p2p-setup-copy-setup-uri-passphrase.png)
+
+3. Copy the resulting URI.
+
+    ![P2P Setup URI generated by the working first device](../images/p2p-setup/guide-p2p-setup-copy-setup-uri-result.png)
+
+Keep the first device online. Store the new URI and its passphrase separately.
+
+## Add the second device
+
+1. Install and enable Self-hosted LiveSync in a new or separately backed-up Vault.
+2. Open onboarding, select `I am adding a device to an existing synchronisation setup`, and choose the recommended Setup URI method.
+3. Enter the Setup URI generated by the first device and its passphrase.
+
+    ![First-device P2P Setup URI entered on the second device](../images/p2p-setup/guide-p2p-setup-second-setup-uri.png)
+
+4. Select `Restart and Fetch Data`.
+
+    ![P2P Fetch confirmation on the second device](../images/p2p-setup/guide-p2p-setup-second-fetch.png)
+
+5. For a new or empty Vault, choose `Overwrite all with remote files`, then `Keep local files even if not on remote`. Review the [Fast Setup guide](./tips/fast-setup.md) before using a Vault which contains local work.
+
+    ![P2P retrieval method](../images/p2p-setup/guide-p2p-setup-retrieval-method.png)
+
+    ![P2P local-file policy](../images/p2p-setup/guide-p2p-setup-local-file-policy.png)
+
+6. In `P2P Rebuild`, confirm that the expected first-device name is shown, then select `Sync`.
+
+    ![Selecting the first device for P2P Rebuild](../images/p2p-setup/guide-p2p-setup-select-first-device.png)
+
+7. On the first device, verify the requesting device name and select `Accept`. Use `Accept Temporarily` instead when approval should last only for this Obsidian session.
+
+    ![Explicit P2P connection request on the first device](../images/p2p-setup/guide-p2p-setup-connection-request-1.png)
+
+8. Keep both devices open until the test note appears on the second device.
+
+    ![First-device note received by the second P2P device](../images/p2p-setup/guide-p2p-setup-first-to-second.png)
+
+## Verify the return journey
+
+Create a second ordinary note on the second device. With automatic broadcast disabled, start the next finite synchronisation explicitly:
+
+1. Open the P2P Replicator pane on both devices.
+2. If the previous finite peer connection no longer appears, select `Disconnect` and then `Open connection` on the first device, followed by the second device. The device which joins last is advertised to devices already in the room.
+3. On the first device, select `Refresh`, verify the second-device name, then select `Replicate now`.
+4. On the second device, verify the requesting first-device name and select `Accept` or `Accept Temporarily`.
+
+    ![Explicit return-journey connection request on the second device](../images/p2p-setup/guide-p2p-setup-connection-request-2.png)
+
+5. Confirm that the second-device note appears unchanged on the first device.
+
+    ![Second-device note received by the first P2P device](../images/p2p-setup/guide-p2p-setup-second-to-first.png)
+
+The two devices are now proven to share the same room, encryption settings, and data format in both directions. Configure automatic start, automatic broadcast, or optional features separately after this manual path works.
+
+## If a peer does not appear
+
+- Confirm that both panes show `Connected` and the same Room ID suffix.
+- Select `Refresh` after the other device joins.
+- Reconnect the device which should be discovered last.
+- Check that the Setup URI came from the working first device and that neither device copied a peer name manually.
+- Check relay reachability, WebRTC restrictions, VPNs, and TURN considerations in [Peer-to-Peer Synchronisation Tips](./tips/p2p-sync-tips.md).

docs/specs_data_compression.md

@@ -0,0 +1,116 @@
+# Data Compression specification
+
+## Status and decision for 1.0
+
+Data Compression is a maintained, advanced opt-in feature for CouchDB-compatible remote databases. It remains disabled by default in the 1.0 line.
+
+The feature provides a modest, measurable reduction in mixed-workload storage and transfer volume. Its value depends heavily on the chunk contents, while the current implementation adds substantial processing and worker-memory costs. Users with slow, metered, or storage-constrained connections may still find that trade-off worthwhile.
+
+## Stored-data behaviour
+
+The `enableCompression` setting affects chunk documents written through the CouchDB remote connection. It does not compress the local database, and it is separate from the journal format used by Object Storage synchronisation.
+
+For each document containing string `data`, the writer:
+
+1. detects canonical Base64 and decodes it to bytes, or encodes text as UTF-8;
+2. applies raw DEFLATE through fflate at level 8;
+3. encodes the result as Base64 and adds the LiveSync compressed-data marker; and
+4. stores the compressed representation only when its string representation is shorter than the original.
+
+Already compressed data and data which does not become smaller are therefore retained unchanged. Readers always recognise and expand the compressed-data marker, including when their own `enableCompression` setting is off. Compressed and uncompressed chunks can coexist in the same remote database.
+
+When E2EE is enabled, compression is applied before E2EE V2 encryption. The encrypted remote representation does not expose the compression marker.
+
+Changing the setting does not require a rebuild for compatibility: new writes adopt the selected policy, while existing chunks remain readable. All devices are still asked to agree on the remote tweak value so that future writes use one consistent policy. A deliberate remote rebuild can normalise existing storage, but it is optional rather than a prerequisite for synchronisation.
+
+## Execution model
+
+The compression and decompression algorithms are not executed synchronously on Obsidian's UI thread. Browser builds call fflate's asynchronous `deflate` and `inflate` APIs, which create a Web Worker for an operation and terminate it after the callback. The CLI uses the corresponding Node worker-thread path.
+
+The PouchDB transform hook, Base64 detection and conversion, UTF-8 conversion, worker creation, result conversion, and document mutation still run in the calling JavaScript context. The current implementation also creates a separate fflate worker for each attempted chunk rather than reusing LiveSync's persistent splitting and encryption worker pool. `transform-pouch` applies the incoming transform to a bulk batch with `Promise.all`, so a batch can start many of these workers concurrently. It can therefore consume significant total CPU and memory, and worker churn may still affect responsiveness or mobile process limits even though the DEFLATE calculation itself is off the UI thread.
+
+The current benchmark measures the Node CLI process. It does not establish Obsidian UI event-loop latency, Electron renderer responsiveness, mobile WebView memory behaviour, battery use, thermal throttling, or platform watchdog thresholds. Those remain real-runtime validation gaps.
+
+## Reproducible benchmark
+
+The benchmark is implemented under `src/apps/cli/testdeno` and packaged by `test/bench-network`. It uses the real CLI mirror and synchronisation path, Commonlib 0.1.0-rc.4, CouchDB 3.5.0, the V3 Rabin–Karp splitter, optional Data Compression, and E2EE V2. It runs each of these conditions three times in rotating order:
+
+- E2EE off, compression off;
+- E2EE off, compression on;
+- E2EE on, compression off; and
+- E2EE on, compression on.
+
+The 623,553-byte deterministic fixture contains three Markdown files, two generated JPEG files, two repository PNG files, two JSON files, two TypeScript files, one gzip file, and one high-entropy binary file. Every run materialises and byte-compares all 13 files after synchronisation.
+
+Run it from the repository root:
+
+```bash
+BENCH_COMMAND=compression \
+BENCH_COMPRESSION_REPEAT_COUNT=3 \
+BENCH_COUCHDB_RTT_MS=1 \
+docker compose -f test/bench-network/compose.yml run --build --rm bench-runner
+```
+
+The latest local three-repeat result was generated on 21st July, 2026. The percentages below compare medians with compression off and on.
+
+| Measurement                                      | E2EE off | E2EE on |
+| ------------------------------------------------ | -------: | ------: |
+| Stored chunk-data reduction                      |    9.12% |   9.01% |
+| CouchDB external-size reduction                  |    9.03% |   8.92% |
+| CouchDB file-size reduction                      |    2.57% |   7.62% |
+| Upload request-body reduction                    |    8.58% |   8.61% |
+| Complete materialisation response-body reduction |    6.56% |   4.84% |
+| Upload wall-time increase                        |  197.10% | 199.29% |
+| Upload CPU-time increase                         |  650.43% | 581.54% |
+| Complete materialisation wall-time increase      |   19.58% |  19.75% |
+| Complete materialisation CPU-time increase       |   45.11% |  43.98% |
+
+With E2EE on, median upload wall time rose from 1.49 seconds to 4.45 seconds, CPU time rose from 1.30 seconds to 8.86 seconds, and upload maximum resident memory rose from about 160 MiB to 403 MiB. The full materialisation workflow starts a CLI process for each file and produced a much higher compressed-path peak of about 983 MiB; treat that figure as evidence about the current CLI workflow rather than a browser decompression lower bound.
+
+The E2EE upload saved 99,034 decoded HTTP body bytes while adding about 2.96 seconds of local processing wall time. A simple serial-transfer estimate puts the wall-time break-even near 0.27 Mbit/s. This estimate excludes headers, contention, request overlap, radio energy, data charges, and server behaviour. The benchmark does not emulate a bandwidth-limited mobile link, so transfer-volume reduction may still be valuable where elapsed time is not the only cost.
+
+## Results by file kind
+
+The E2EE stored chunk-data reductions were:
+
+| Fixture kind        | Reduction |
+| ------------------- | --------: |
+| Markdown            |    16.30% |
+| JPEG                |     4.72% |
+| PNG                 |     6.16% |
+| JSON                |    72.80% |
+| TypeScript          |    74.11% |
+| gzip                |        0% |
+| high-entropy binary |        0% |
+
+These results describe payload and chunk characteristics, not a reliable file-extension policy. The JSON and TypeScript fixtures were repetitive and mapped to relatively large chunks. The Markdown files were split into 151 referenced chunks, so small-chunk overhead and limited repetition windows reduced their benefit. JPEG, PNG, and gzip inputs had already undergone format-level compression, while the deterministic binary input was intentionally difficult to compress.
+
+The remote transform sees a content-addressed chunk, not a trustworthy original file type. A chunk can also be deduplicated across files with different extensions. Enabling compression only for selected extensions would therefore either require carrying new provenance into the chunk format or make the representation depend on whichever file first produced a shared chunk. Neither is suitable for the 1.0 format.
+
+## Follow-up optimisation candidates
+
+The first optimisation should remove unbounded per-chunk worker creation:
+
+1. add compression and decompression tasks to a reusable worker pool;
+2. run synchronous fflate inside those workers so that it does not create a nested worker for each task;
+3. put a bounded scheduler or semaphore before dispatch, rather than submitting the complete `Promise.all` batch at once;
+4. transfer derived input and output `ArrayBuffer` objects explicitly in each `postMessage` transfer list; and
+5. decide that a result is not smaller inside the worker, so an unhelpful compressed buffer does not need to be returned.
+
+LiveSync's current `bgWorker` is a useful starting point because it creates a fixed pool of approximately half the reported hardware concurrency and selects workers in round-robin order. It is not sufficient unchanged: its `processing` count does not control selection, and it does not limit the number of tasks posted to each worker. Its foreground modules also form a circular dependency: `bgWorker.ts` imports the splitting and encryption adapters, while those adapters import task dispatch and removal from `bgWorker.ts`. Compression must not add another branch to that cycle.
+
+Before adding compression, the Worker code should be separated into a dependency-bottom pool, task registry, scheduler, and transfer transport, with splitting, encryption, and compression implemented as task adapters above it. The shared scheduler should own concurrency limits, cancellation, crash propagation, fairness, and task clean-up. Compression then needs either a separate bounded lane or scheduling which prevents a long level-8 task from starving splitting and encryption work.
+
+The `TransformStream` currently used by `bgWorker.splitting` is local to the calling context; it is not transferred to the Worker. Moving a stream endpoint across contexts could provide real end-to-end back-pressure, but it is not the first memory optimisation for Data Compression. The [Streams Standard transfer algorithm](https://streams.spec.whatwg.org/#transferable-streams) transfers the stream endpoint and posts each chunk through an internal `MessagePort` with an empty transfer list. Binary chunks can therefore still be cloned. Explicitly transferring each `ArrayBuffer` is the clearer zero-copy boundary for independent chunk tasks.
+
+Cross-context transferable streams also cannot yet be required by the supported mobile baseline. WebKit lists `ReadableStream`, `WritableStream`, and `TransformStream` transfer via `postMessage()` as a [Safari 27 beta addition](https://webkit.org/blog/17967/news-from-wwdc26-webkit-in-safari-27-beta/#readablestream-improvements). A future general `bgWorker` redesign may use transferable streams behind capability detection, particularly where back-pressure matters more than copying, but it needs a message-based fallback.
+
+After bounding worker use, adaptive per-chunk compression can reduce unnecessary work without depending on the source filename:
+
+1. skip very small chunks where the marker and worker start-up dominate;
+2. sample decoded bytes and estimate entropy or repetition before starting level-8 DEFLATE;
+3. require both a minimum byte saving and a minimum percentage saving;
+4. compare lower DEFLATE levels against level 8; and
+5. replace one-worker-per-chunk operation with a bounded, persistent compression worker pool and back-pressure.
+
+Any optimisation must preserve the current wire contract: content may remain uncompressed, the compressed marker must stay readable, compression must precede E2EE, and mixed representations must interoperate. It should be evaluated with the same four-condition benchmark, a bandwidth-shaped case, UI event-loop latency, and at least one real mobile Obsidian run before reconsidering the default.

docs/tech_info.md

@@ -1,16 +1,16 @@
 # Designed architecture
 
-## How does this plugin synchronize.
+## How does this plug-in synchronise.
 
-![Synchronization](../images/1.png)
+![Synchronisation](../images/1.png)
 
 1. When notes are created or modified, Obsidian raises some events. Self-hosted LiveSync catches these events and reflects changes into Local PouchDB.
 2. PouchDB automatically or manually replicates changes to remote CouchDB.
 3. Another device is watching remote CouchDB's changes, so retrieve new changes.
 4. Self-hosted LiveSync reflects replicated changeset into Obsidian's vault.
 
-Note: The figure is drawn as single-directional, between two devices. But everything occurs bi-directionally between many devices at once in real.
+Note: The figure is drawn as single-directional, between two devices for demonstration purposes. Everything actually occurs bi-directionally between many devices at the same time.
 
-## Techniques to keep bandwidth low.
+## Techniques to keep bandwidth consumption low.
 
 ![dedupe](../images/2.png)

docs/tech_info_cn.md

@@ -0,0 +1,16 @@
+# 架构设计
+
+## 这个插件是怎么实现同步的.
+
+![Synchronisation](../images/1.png)
+
+1. 当笔记创建或修改时，Obsidian会触发事件。Self-hosted LiveSync捕获这些事件，并将变更同步至本地PouchDB
+2. PouchDB通过自动或手动方式将变更同步至远程CouchDB
+3. 其他设备监听远程CouchDB的变更，从而获取最新更新
+4. Self-hosted LiveSync 将同步的变更集反映到Obsidian存储库中。
+
+注：图示为简化演示，仅展示两个设备间的单向同步。实际为多设备间同时进行的双向同步。
+
+## 降低带宽消耗的技术方案。
+
+![dedupe](../images/2.png)

docs/tech_info_ja.md

@@ -2,7 +2,7 @@
 
 ## 同期
 
-![Synchronization](../images/1.png)
+![Synchronisation](../images/1.png)
 
 1. ノートが更新された際、Obsidianがイベントを発報します。Obsidian-LiveSyncはそれをハンドリングして、ローカルのPouchDBに変更を反映します。
 2. PouchDBは、リモートのCouchDBに差分をレプリケーションします。

docs/terms.md

@@ -0,0 +1,102 @@
+# Notes on Terminology, Spelling, Vocabulary Conventions
+
+## Spelling and Vocabulary conventions
+
+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.
+
+3. We use `dialogue` in documentation for consistency. While `dialog` may appear in source code, particularly in class names, method names, and attributes (following technical conventions in No. 2), we consistently use `dialogue` for user-facing messages and general documentation text. This approach balances No. 1 with No. 2.
+
+4. Contractions are not used. For example, "do not" instead of "don't", "cannot" instead of "can't", etc., especially `'d`.
+   - We may encounter difficulties with tenses.
+
+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
+    - A database maintenance procedure that discards old historical document revisions to shrink the remote database size.
+- Custom HTTP Handler / Use Internal API (CORS Bypass Settings)
+    - Settings used to bypass CORS restrictions by routing requests through Obsidian's native request APIs. There are two distinct settings under the hood depending on the remote server type:
+        - **For S3-compatible Object Storage (useCustomRequestHandler)**: Labeled as **"Use Custom HTTP Handler"** in the standard settings tab, **"Use internal API"** in the Svelte-based Setup Wizard dialogue, and represented as `useProxy` in the Setup URI's query parameters due to an unfortunate misunderstanding during development.
+        - **For CouchDB (useRequestAPI)**: Labeled as **"Use Request API to avoid `inevitable` CORS problem"** in the standard settings tab, **"Use Internal API"** in the Svelte-based Setup Wizard dialogue, and represented as `useRequestAPI` in the Setup URI's query parameters.
+- Customisation Sync
+    - The feature that synchronises settings, snippets, themes, and plug-ins. Write with an "s" in documentation (`Customisation`), though technical configurations and links may use `customization`.
+- Database Adapter (IDB vs. IndexedDB)
+    - The local database storage interface used by PouchDB. The `IDB` adapter is recommended since the older `IndexedDB` adapter is obsolete and known to cause memory leaks in `LiveSync` mode. Users can switch between these adapters without a full database rebuild, although a local data migration and an Obsidian restart are required.
+- Database Suffix (additionalSuffixOfDatabaseName)
+    - A unique suffix appended to the database name to allow synchronising multiple vaults with the same name on the same remote server.
+- E2EE Algorithm
+    - 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.
+- Metadata (File metadata)
+    - A database document that stores properties of a file, including its filename, path, size, modification time, and references (hashes) of the chunks that comprise the file's content. Conflict state is carried by the surrounding PouchDB/CouchDB revision metadata rather than by a separate history field inside the file metadata document. In Self-hosted LiveSync, file 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
+    - A maintenance operation (formerly known as `Rebuild everything`) that discards the remote database and reconstructs it by uploading all current local files as a fresh database, overwriting any remote changes.
+- Path Obfuscation
+    - A privacy option that encrypts file paths and folder names on the remote server.
+- plug-in
+    - We use the hyphenated form `plug-in` in user-facing messages and general documentation, while `plugin` may appear in codebase files, configuration settings, or technical contexts.
+- Relay Server (P2P relays)
+    - A WebSocket-based coordination server used to establish direct WebRTC peer-to-peer connections. The default relay is provided by the plug-in author.
+- Remediation (maxMTimeForReflectEvents)
+    - A recovery setting that restricts the propagation of changes from the database to local storage, ignoring any file events (such as accidental mass deletions) that occurred after a specified date and time.
+- Reset Synchronisation on This Device
+    - A maintenance operation (formerly known as `Fetch everything`) that discards the local database and reconstructs it by downloading all data from the remote server.
+- Scram (Scram Switches)
+    - Emergency controls in the settings that allow users to suspend file watching or database writes to prevent corruption.
+- Segmenter (Segmented-splitter)
+    - A chunking method that divides files on semantic boundaries (such as paragraphs or sections) rather than arbitrary byte boundaries.
+- Self-hosted LiveSync
+    - The name of this plug-in. `Self-hosted` is one word.
+- Setting Doctor (Config Doctor)
+    - 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)
+    - A server type (Traversal Using Relays around NAT) used as a fallback to relay traffic when direct WebRTC peer-to-peer connection is blocked by strict NAT or firewalls.
+- Update Thinning (Batch database update)
+    - An optimisation that groups multiple local file edits together over a short delay before committing them to the local database, reducing the number of database write operations.
+- WebRTC P2P (Peer-to-Peer)
+    - A synchronisation method enabling direct communication between devices without a central server database.

docs/tips/fast-setup.md

@@ -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.

docs/tips/fast-setup_ja.md

@@ -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. 処理が完了すると、プラグインは通常の動作状態へ復帰します。

docs/tips/hidden-file-sync.md

@@ -0,0 +1,70 @@
+# Hidden File Sync
+
+Hidden File Sync is an advanced, optional feature for synchronising hidden files and folders, including selected content below `.obsidian`. It is separate from ordinary note synchronisation and is deliberately left disabled during Rebuild and Fetch setup operations.
+
+Enable it only after ordinary notes synchronise correctly in both directions on every device.
+
+> [!WARNING]
+> Hidden files can control active Obsidian settings, themes, snippets, and plug-ins. Back up every Vault before enabling this feature. Do not use Hidden File Sync and Customisation Sync to manage the same files.
+
+## Choose the initial source
+
+Enabling Hidden File Sync requires an initialisation direction:
+
+- `Merge` compares the local and remote hidden-file state without declaring either side authoritative. Use this when both sides contain changes which must be retained, and review any conflicts.
+- `Fetch` treats the remote hidden-file state as authoritative and applies it locally. Use this on an additional device after the desired files have been uploaded.
+- `Overwrite` treats this device's hidden files as authoritative and writes them to the remote database. Use this first on the device whose hidden files you intend to distribute.
+
+`Fetch` and `Overwrite` can replace files on one side. Check the direction and the backup before continuing.
+
+## Review the file selection
+
+1. Open Self-hosted LiveSync settings.
+2. Open `Setup`, find `Enable extra and advanced features`, and enable `Advanced features`.
+
+   ![Advanced features enabled](../../images/hidden-file-sync/guide-hidden-file-advanced-features.png)
+
+3. Open `Selector`, then review the `Hidden Files` section.
+4. Use `Target patterns` to limit the feature to the hidden files you intend to synchronise. An empty target list includes every otherwise eligible hidden file.
+5. Review `Ignore patterns`. The default excludes `node_modules`, `.git`, and Self-hosted LiveSync's own plug-in data. `Add default patterns` offers a `Cross-platform` set which also excludes Obsidian workspace files.
+
+   ![Hidden File target and ignore selectors](../../images/hidden-file-sync/guide-hidden-file-selector.png)
+
+Prefer a narrow target list. Device-specific workspace state and another plug-in's credentials are usually poor candidates for cross-device synchronisation.
+
+Target patterns also control directory traversal. A pattern must therefore match each parent directory as well as the intended files. For example, the following pattern admits the `.obsidian` parent and only its `snippets` subtree:
+
+```text
+^\.obsidian(?:$|/snippets(?:/|$))
+```
+
+A pattern containing only `snippets` does not admit the `.obsidian` parent, so the scan cannot reach that directory.
+
+## Enable the first device
+
+1. Open `Sync Settings`, then find the advanced `Hidden Files` section.
+
+   ![Hidden File Sync initialisation choices](../../images/hidden-file-sync/guide-hidden-file-enable.png)
+
+2. Under `Enable Hidden File Sync`, select the initialisation direction chosen above.
+3. Keep Obsidian open while the initial scan and synchronisation finish.
+4. Restart Obsidian when the completion Notice recommends it.
+5. Confirm that the expected hidden files, and only those files, are present in the remote synchronisation state.
+
+For the common source-of-truth rollout, select `Overwrite` on the authoritative device first.
+
+## Enable each additional device
+
+Hidden File Sync must be enabled independently after ordinary setup on each device.
+
+1. Back up the additional device's Vault.
+2. Apply the same target and ignore patterns.
+3. Select `Fetch` if the remote hidden files are authoritative. Select `Merge` only when local hidden-file changes must also be retained.
+4. Wait for the initial scan and file application to finish, then restart Obsidian if requested.
+5. Verify representative files before enabling the feature on the next device.
+
+If you later run Rebuild or Fetch as a recovery operation, expect optional features to be disabled again. Complete ordinary recovery first, then repeat this guide deliberately.
+
+## Related settings
+
+The [settings reference](../settings.md#7-hidden-files-advanced) describes periodic scanning, scanning before replication, notification suppression, selectors, and overwrite patterns. Change those controls only after the basic Hidden File Sync path is working.

docs/tips/jwt-on-couchdb.md

@@ -0,0 +1,81 @@
+---
+title: "JWT Authentication on CouchDB"
+livesync-version: 0.25.24
+tags:
+    - tips
+    - CouchDB
+    - JWT
+authors:
+    - vorotamoroz
+---
+
+# JWT Authentication on CouchDB
+
+When using CouchDB as a backend for Self-hosted LiveSync, it is possible to enhance security by employing JWT (JSON Web Token) Authentication. In particular, using asymmetric keys (ES256 and ES512) provides greater security against token interception.
+
+## Setting up JWT Authentication (Asymmetrical Key Example)
+
+### 1. Generate a key pair
+
+We can use `openssl` to generate an EC key pair as follows:
+
+```bash
+# Generate private key
+# ES512 for secp521r1 curve, we can also use ES256 for prime256v1 curve
+openssl ecparam -name secp521r1 -genkey -noout | openssl pkcs8 -topk8 -inform PEM -nocrypt -out private_key.pem
+# openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -inform PEM -nocrypt -out private_key.pem
+# Generate public key in SPKI format
+openssl ec -in private_key.pem -pubout -outform PEM -out public_key.pem
+```
+
+> [!TIP]
+> A key generator will be provided again in a future version of the user interface.
+
+### 2. Configure CouchDB to accept JWT tokens
+
+The following configuration is required:
+
+| Key                            | Value                                     | Note                                                                                                                                                                                                                  |
+| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| chttpd/authentication_handlers | {chttpd_auth, jwt_authentication_handler} | In total, it may be `{chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}`, or something similar.                                   |
+| jwt_auth/required_claims       | "exp"                                     |                                                                                                                                                                                                                       |
+| jwt_keys/ec:your_key_id        | Your public key in PEM (SPKI) format      | Replace `your_key_id` with your actual key ID. You can decide as you like. Note that you can add multiple keys if needed. If you want to use HSxxx, you should set `jwt_keys/hmac:your_key_id` with your HMAC secret. |
+
+
+Note: When configuring CouchDB via web interface (Fauxton), new-lines on the public key should be replaced with `\n` for header and footer lines (So wired, but true I have tested). as follows:
+```
+-----BEGIN PUBLIC KEY-----
+\nMIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBq0irb/+K0Qzo7ayIHj0Xtthcntjz
+r665J5UYdEQMiTtku5rnp95RuN97uA2pPOJOacMBAoiVUnZ1pqEBz9xH9yoAixji
+Ju...........................................................gTt
+/xtqrJRwrEy986oRZRQ=
+\n-----END PUBLIC KEY-----
+```
+
+For detailed information, please refer to the [CouchDB JWT Authentication Documentation](https://docs.couchdb.org/en/stable/api/server/authn.html#jwt-authentication).
+
+### 3. Configure Self-hosted LiveSync to use JWT Authentication
+
+| Setting                 | Description                                                                                                                                           |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Use JWT Authentication  | Enable this option to use JWT Authentication.                                                                                                         |
+| JWT Algorithm           | Select the JWT signing algorithm (e.g., ES256, ES512) that matches your key pair.                                                                     |
+| JWT Key                 | Paste your private key in PEM (pkcs8) format.                                                                                                         |
+| JWT Expiration Duration | Set the token expiration time in minutes. Locally cached tokens are also invalidated after this duration.                                             |
+| JWT Key ID (kid)        | Enter the key ID that you used when configuring CouchDB, i.e., the one that replaced `your_key_id`.                                                   |
+| JWT Subject (sub)       | Set your user ID; this overrides the original `Username` setting. If you have detected access with `Username`, you have failed to authorise with JWT. |
+
+> [!IMPORTANT]
+> Self-hosted LiveSync requests to CouchDB treat the user as `_admin`. If you want to restrict access, configure `jwt_auth/roles_claim_name` to a custom claim name. (Self-hosted LiveSync always sets `_couchdb.roles` with the value `["_admin"]`).
+
+### 4. Test the configuration
+
+Just try to `Test Settings and Continue` in the remote setup dialogue. If you have successfully authenticated, you are all set.
+
+## Additional Notes
+
+This feature is still experimental. Please ensure to test thoroughly in your environment before deploying to production.
+
+However, we think that this is a great step towards enhancing security when using CouchDB with Self-hosted LiveSync. We shall enable this setting by default in future releases.
+
+We would love to hear your feedback and any issues you encounter.

docs/tips/p2p-sync-tips.md

@@ -0,0 +1,31 @@
+---
+title: "Peer-to-Peer Synchronisation Tips"
+livesync-version: 0.25.24
+tags:
+    - tips
+    - p2p
+authors:
+    - vorotamoroz
+---
+
+# Peer-to-Peer Synchronisation Tips
+
+For the complete first-device, Setup URI, second-device, and two-way verification procedure, see [Set up peer-to-peer synchronisation](../setup_p2p.md).
+
+> [!IMPORTANT]
+> Peer-to-peer synchronisation is a supported opt-in feature. WebRTC connectivity still depends on the networks, relays, and optional TURN servers available to every device, so a working connection cannot be guaranteed in every environment.
+
+## Difficulties with Peer-to-Peer Synchronisation
+
+It is often the case that peer-to-peer connections do not function correctly, for instance, when using mobile data services.
+In such circumstances, we recommend connecting all devices to a single Virtual Private Network (VPN). It is advisable to select a service, such as Tailscale, which facilitates direct communication between peers wherever possible.
+Should one be in an environment where even Tailscale is unable to connect, or where it cannot be lawfully installed, please continue reading.
+
+## A More Detailed Explanation
+
+The failure of a Peer-to-Peer connection via WebRTC can be attributed to several factors. These may include an unsuccessful UDP hole-punching attempt, or an intermediary gateway intentionally terminating the connection. Troubleshooting this matter is not a simple undertaking. Furthermore, and rather unfortunately, gateway administrators are typically aware of this type of network behaviour. Whilst a legitimate purpose for such traffic can be cited, such as for web conferencing, this is often insufficient to prevent it from being blocked.
+
+This situation, however, is the primary reason that our project does not provide a TURN server. Although it is said that a TURN server within WebRTC does not decrypt communications, the project holds the view that the risk of a malicious party impersonating a TURN server must be avoided. Consequently, configuring a TURN server for relay communication is not currently possible through the user interface. Furthermore, there is no official project TURN server, which is to say, one that could be monitored by a third party.
+
+We request that you provide your own server, using your own Fully Qualified Domain Name (FQDN), and subsequently enter its details into the advanced settings.
+For testing purposes, Cloudflare's Real-Time TURN Service is exceedingly convenient and offers a generous amount of free data. However, it must be noted that because it is a well-known destination, such traffic is highly conspicuous. There is also a significant possibility that it may be blocked by default. We advise proceeding with caution.

docs/to_issue_reporting.md

@@ -0,0 +1,145 @@
+# How to report an issue
+
+Thank you for helping improve Self-hosted LiveSync!
+
+This document explains how to collect the information needed for an issue report. Issues with sufficient information will be prioritised.
+
+---
+
+## Filled example
+
+Here is an example of a well-filled report for reference.
+
+### Abstract
+
+The synchronisation hung up immediately after connecting.
+
+### Expected behaviour
+
+- Synchronisation ends with the message `Replication completed`
+- Everything synchronised
+
+### Actually happened
+
+- Synchronisation was cancelled with the message `TypeError: Failed to fetch` (visible in the plug-in log around lines 10–12)
+- No files synchronised
+
+### Reproducing procedure
+
+1. Configure LiveSync with the settings shown in the attached report.
+2. Click the sync button on the ribbon.
+3. Synchronisation begins.
+4. About two or three seconds later, the error `TypeError: Failed to fetch` appears.
+5. Replication stops. No files synchronised.
+
+### Obsidian debug info (Device 1 — Windows desktop)
+
+```
+SYSTEM INFO:
+	Obsidian version: v1.2.8
+	Installer version: v1.1.15
+	Operating system: Windows 10 Pro 10.0.19044
+	Login status: logged in
+	Catalyst license: supporter
+	Insider build toggle: off
+	Community theme: Minimal v6.1.11
+	Snippets enabled: 3
+	Restricted mode: off
+	Plugins installed: 35
+	Plugins enabled: 11
+		1: Self-hosted LiveSync v0.19.4
+		...
+```
+
+### Report from LiveSync
+
+```
+----remote config----
+cors:
+  credentials: "true"
+  ...
+---- Plug-in config ---
+couchDB_URI: self-hosted
+couchDB_USER: 𝑅𝐸𝐷𝐴𝐶𝑇𝐸𝐷
+...
+```
+
+### Plug-in log
+
+```
+2023/5/24 10:50:33->HTTP:GET to:/ -> failed
+2023/5/24 10:50:33->TypeError:Failed to fetch
+2023/5/24 10:50:33->could not connect to https://example.com/ : your vault
+(TypeError:Failed to fetch)
+```
+
+---
+
+## How to collect each piece of information
+
+### Obsidian debug info
+
+Open the command palette (`Ctrl/Cmd + P`) and run **"Show debug info"**. Copy the output and paste it into the issue.
+
+If multiple devices are involved in the problem (e.g., sync between a phone and a desktop), please provide the debug info for each device. The device where the issue occurred is required; information from other devices is strongly recommended.
+
+### Report from LiveSync (hatch report)
+
+1. Open LiveSync settings.
+2. Go to the **Hatch** pane.
+3. Press the **Make report** button.
+
+The report will be copied to your clipboard. It contains your LiveSync configuration and the remote server configuration, with credentials automatically redacted.
+
+**Tip:** For large reports, consider uploading to [GitHub Gist](https://gist.github.com/) and sharing the link instead of pasting directly into the issue. This makes it easier to manage, and if you accidentally leave sensitive data in, a Gist can be deleted.
+
+If you paste directly, wrap it in a `<details>` tag to keep the issue readable:
+
+```
+<details>
+<summary>Report from hatch</summary>
+
+```
+----remote config----
+  :
+```
+</details>
+```
+
+### Plug-in log
+
+The plug-in log is volatile by default (not saved to disk) and shown only in the log dialogue, which can be opened by tapping the **document box icon** in the ribbon.
+
+#### Enable verbose log
+
+Before reproducing the issue, enable **Verbose Log** in LiveSync's **General Settings** pane. Without this, many diagnostic messages will be suppressed.
+
+#### Persist the log to a file (optional)
+
+If you need to capture a log across a restart, enable **"Write logs into the file"** in General Settings. Note that log files may contain sensitive information — use this option only for troubleshooting, and disable it afterwards.
+
+As with the hatch report, consider uploading large logs to [GitHub Gist](https://gist.github.com/).
+
+### Network log (for connection-related issues only)
+
+If the issue is related to network connectivity (e.g., cannot connect to the server, authentication errors), a network log captured from browser DevTools can be very helpful. You do not need to include this for non-connection issues.
+
+#### Opening DevTools
+
+| Platform | Shortcut |
+|----------|----------|
+| Windows / Linux | `Ctrl + Shift + I` |
+| macOS | `Cmd + Shift + I` |
+| Android | Use [Chrome remote debugging](https://developer.chrome.com/docs/devtools/remote-debugging/) |
+| iOS | Use [Safari Web Inspector](https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios) on a Mac |
+
+#### What to capture
+
+1. Open the **Network** pane in DevTools.
+2. Reproduce the issue.
+3. Look for requests marked in red.
+4. Capture screenshots of the **Headers**, **Payload**, and **Response** tabs for those requests.
+
+**Important — redact before sharing:**
+- Headers: conceal the request URL path, Remote Address, `authority`, and `authorisation` values.
+- Payload / Response: the `_id` field contains your file paths — redact if needed.

docs/troubleshooting.md

@@ -0,0 +1,454 @@
+# Tips and Troubleshooting
+- [Tips and Troubleshooting](#tips-and-troubleshooting)
+  - [Tips](#tips)
+    - [CORS avoidance](#cors-avoidance)
+    - [CORS configuration with reverse proxy](#cors-configuration-with-reverse-proxy)
+      - [Nginx](#nginx)
+      - [Nginx and subdirectory](#nginx-and-subdirectory)
+      - [Caddy](#caddy)
+      - [Caddy and subdirectory](#caddy-and-subdirectory)
+      - [Apache](#apache)
+    - [Show all setting panes](#show-all-setting-panes)
+    - [How to resolve `Tweaks Mismatched of Changed`](#how-to-resolve-tweaks-mismatched-of-changed)
+  - [Notable bugs and fixes](#notable-bugs-and-fixes)
+    - [Binary files get bigger on iOS](#binary-files-get-bigger-on-ios)
+    - [Some setting name has been changed](#some-setting-name-has-been-changed)
+  - [Questions and Answers](#questions-and-answers)
+    - [How should I share the settings between multiple devices?](#how-should-i-share-the-settings-between-multiple-devices)
+    - [What should I enter for the passphrase of Setup-URI?](#what-should-i-enter-for-the-passphrase-of-setup-uri)
+    - [Why the settings of Self-hosted LiveSync itself is disabled in default?](#why-the-settings-of-self-hosted-livesync-itself-is-disabled-in-default)
+    - [The plug-in says `something went wrong`.](#the-plug-in-says-something-went-wrong)
+    - [A large number of files were deleted, and were synchronised!](#a-large-number-of-files-were-deleted-and-were-synchronised)
+    - [Why `Use an old adapter for compatibility` is somehow enabled in my vault?](#why-use-an-old-adapter-for-compatibility-is-somehow-enabled-in-my-vault)
+    - [ZIP (or any extensions) files were not synchronised. Why?](#zip-or-any-extensions-files-were-not-synchronised-why)
+    - [I hope to report the issue, but you said you needs `Report`. How to make it?](#i-hope-to-report-the-issue-but-you-said-you-needs-report-how-to-make-it)
+    - [Where can I check the log?](#where-can-i-check-the-log)
+    - [Why are the logs volatile and ephemeral?](#why-are-the-logs-volatile-and-ephemeral)
+    - [Some network logs are not written into the file.](#some-network-logs-are-not-written-into-the-file)
+    - [If a file were deleted or trimmed, the capacity of the database should be reduced, right?](#if-a-file-were-deleted-or-trimmed-the-capacity-of-the-database-should-be-reduced-right)
+    - [How to launch the DevTools](#how-to-launch-the-devtools)
+      - [On Desktop Devices](#on-desktop-devices)
+      - [On Android](#on-android)
+      - [On iOS, iPadOS devices](#on-ios-ipados-devices)
+    - [How can I use the DevTools?](#how-can-i-use-the-devtools)
+      - [Checking the network log](#checking-the-network-log)
+  - [Troubleshooting](#troubleshooting)
+    - [While using Cloudflare Tunnels, often Obsidian API fallback and `524` error occurs.](#while-using-cloudflare-tunnels-often-obsidian-api-fallback-and-524-error-occurs)
+    - [On the mobile device, cannot synchronise on the local network!](#on-the-mobile-device-cannot-synchronise-on-the-local-network)
+    - [I think that something bad happening on the vault...](#i-think-that-something-bad-happening-on-the-vault)
+    - [Flag Files](#flag-files)
+    - [Old tips](#old-tips)
+
+<!-- - -->
+
+## Tips
+
+### CORS avoidance
+
+If we are unable to configure CORS properly for any reason (for example, if we cannot configure non-administered network devices), we may choose to ignore CORS.
+To use the Obsidian API (also known as the Non-Native API) to bypass CORS, we can enable the toggle ``Use Request API to avoid `inevitable` CORS problem``.
+
+<!-- Add **Long explanation of CORS** here for integrity -->
+
+### CORS configuration with reverse proxy
+
+- IMPORTANT: CouchDB handles CORS by itself. Do not process CORS on the reverse
+  proxy.
+    - Do not process `Option` requests on the reverse proxy!
+    - Make sure `host` and `X-Forwarded-For` headers are forwarded to the CouchDB.
+    - If you are using a subdirectory, make sure to handle it properly. More
+      detailed information is in the
+      [CouchDB documentation](https://docs.couchdb.org/en/stable/best-practices/reverse-proxies.html).
+
+Minimal configurations are as follows:
+
+#### Nginx
+
+```nginx
+location / {
+    proxy_pass http://localhost:5984;
+    proxy_redirect off;
+    proxy_buffering off;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+#### Nginx and subdirectory
+
+```nginx
+location /couchdb {
+    rewrite ^ $request_uri;
+    rewrite ^/couchdb/(.*) /$1 break;
+    proxy_pass http://localhost:5984$uri;
+    proxy_redirect off;
+    proxy_buffering off;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+
+location /_session {
+    proxy_pass http://localhost:5984/_session;
+    proxy_redirect off;
+    proxy_buffering off;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+#### Caddy
+
+```caddyfile
+domain.com {
+   reverse_proxy localhost:5984
+}
+```
+
+#### Caddy and subdirectory
+
+```caddyfile
+domain.com {
+    reverse_proxy /couchdb/* localhost:5984
+    reverse_proxy /_session/* localhost:5984/_session
+}
+```
+
+#### Apache
+
+Sorry, Apache is not recommended for CouchDB. Omit the configuration from here.
+Please refer to the
+[Official documentation](https://docs.couchdb.org/en/stable/best-practices/reverse-proxies.html#reverse-proxying-with-apache-http-server).
+
+### Show all setting panes
+
+Full pane is not shown by default. To show all panes, please toggle all in
+`🧙‍♂️ Wizard` -> `Enable extra and advanced features`.
+
+For your information, the all panes are as follows:
+![All Panes](all_toggles.png)
+
+### How to resolve `Tweaks Mismatched of Changed`
+
+(Since v0.23.17)
+
+If you have changed some configurations or tweaks which should be unified
+between the devices, you will be asked how to reflect (or not) other devices at
+the next synchronisation. It also occurs on the device itself, where changes are
+made, to prevent unexpected configuration changes from unwanted propagation.\
+(We may thank this behaviour if we have synchronised or backed up and restored
+Self-hosted LiveSync. At least, for me so).
+
+Following dialogue will be shown: ![Dialogue](tweak_mismatch_dialogue.png)
+
+- If we want to propagate the setting of the device, we should choose
+  `Update with mine`.
+- On other devices, we should choose `Use configured` to accept and use the
+  configured configuration.
+- `Dismiss` can postpone a decision. However, we cannot synchronise until we
+  have decided.
+
+Rest assured that in most cases we can choose `Use configured`. (Unless you are
+certain that you have not changed the configuration).
+
+If we see it for the first time, it reflects the settings of the device that has
+been synchronised with the remote for the first time since the upgrade.
+Probably, we can accept that.
+
+<!-- Add here -->
+
+## Notable bugs and fixes
+
+### Binary files get bigger on iOS
+
+- Reported at: v0.20.x
+- Fixed at: v0.21.2 (Fixed but not reviewed)
+- Required action: larger files will not be fixed automatically, please perform
+  `Verify and repair all files`. If our local database and storage are not
+  matched, we will be asked to apply which one.
+
+### Some setting name has been changed
+
+- Fixed at: v0.22.6
+
+| Previous name                | New name                                 |
+| ---------------------------- | ---------------------------------------- |
+| Open setup URI               | Use the copied setup URI                 |
+| Copy setup URI               | Copy current settings as a new setup URI |
+| Setup Wizard                 | Minimal Setup                            |
+| Check database configuration | Check and Fix database configuration     |
+
+## Questions and Answers
+
+### How should I share the settings between multiple devices?
+
+- Device setup:
+    - Using `Setup URI` is the most straightforward way.
+- Setting changes during use:
+    - Use `Sync settings via Markdown files` on the `🔄️ Sync settings` pane.
+
+### What should I enter for the passphrase of Setup-URI?
+
+- Anything you like is OK. However, the recommendation is as follows:
+    - Include the vault (group) information.
+    - Include the date of operation.
+    - Anything random for your security.
+    - For example, `MyVault-20240901-r4nd0mStr1ng`.
+- Why?
+    - The Setup-URI is encoded; that means it cannot indicate the actual settings. Hence, if you use the same passphrase for multiple vaults, you may accidentally mix up vaults.
+
+### Why the settings of Self-hosted LiveSync itself is disabled in default?
+
+Basically, if we configure all `additionalSuffixOfDatabaseName` the same, we can synchronise this file between multiple devices.
+(`additionalSuffixOfDatabaseName` should be unique in each device, not in the synchronised vaults).
+However, if we synchronise the settings of Self-hosted LiveSync itself, we may encounter some unexpected behaviours.
+For example, if a setting that 'let Self-hosted LiveSync setting be excluded' is synced, it is very unlikely that things will recover automatically after this, and there is little chance we will even notice this. Even if we change our minds and change the settings back on other devices. It could get even worse if incompatible changes are automatically reflected; everything will break.
+
+### The plug-in says `something went wrong`.
+
+There are many cases where this is really unclear. One possibility is that the chunk fetch did not go well.
+
+1. Restarting Obsidian sometimes helps (fetch-order problem).
+2. If actually there are no chunks, please perform `Recreate missing chunks for all files` on the `🧰 Hatch` pane at the other devices. And synchronise again. (also restart Obsidian may effect).
+3. If the problem persists, please perform `Verify and repair all files` on the `🧰 Hatch` pane. If our local database and storage are not matched, we will be asked to apply which one.
+
+### A large number of files were deleted, and were synchronised!
+
+1. Backup everything important.
+    - Your local vault.
+    - Your CouchDB database (this can be done by replicating to another database).
+2. Prepare the empty vault
+3. Place `redflag.md` at the top of the vault.
+4. Apply the settings **BUT DO NOT PROCEED TO RESTORE YET**.
+     - You can use `Setup URI`, QR Code, or manually apply the settings.
+5. Set `Maximum file modification time for reflected file events` in `Remediation` on the `🩹 Patches` pane.
+    - If you know when the files were deleted, set the time a bit before that.
+    - If not, bisecting may help us.
+6. Delete `redflag.md`.
+7. Perform `Reset Synchronisation on This Device` on the `🎛️ Maintenance` pane.
+
+This mode is very fragile. Please be careful.
+
+### Why `Use an old adapter for compatibility` is somehow enabled in my vault?
+
+Because you are a compassionate and experienced user. Before v0.17.16, we used
+an old adapter for the local database. At that time, current default adapter has
+not been stable. The new adapter has better performance and has a new feature
+like purging. Therefore, we should use new adapters and current default is so.
+
+However, when switching from an old adapter to a new adapter, some converting or
+local database rebuilding is required, and it takes some time. It was a long
+time ago now, but we once inconvenienced everyone in a hurry when we changed the
+format of our database. For these reasons, this toggle is automatically on if we
+have upgraded from vault which using an old adapter.
+
+When you overwrite server data with this device's files or reset synchronisation on this device again, you will be asked to
+switch this.
+
+Therefore, experienced users (especially those stable enough not to have to
+overwrite server data) may have this toggle enabled in their Vault. Please
+disable it when you have enough time.
+
+### ZIP (or any extensions) files were not synchronised. Why?
+
+It depends on Obsidian detects. May toggling `Detect all extensions` of
+`File and links` (setting of Obsidian) will help us.
+
+### I hope to report the issue, but you said you needs `Report`. How to make it?
+
+We can copy the report to the clipboard, by performing 
+`Generate full report for opening the issue with debug info` command!
+
+### Where can I check the log?
+
+We can launch the log pane by `Show log` on the command palette. And if you have
+troubled something, please enable the `Verbose Log` on the `General Setting`
+pane.
+`Generate full report for opening the issue with debug info` command also contains 
+the recent 1000 log lines, which is very helpful for debugging. Full-report is 
+already set to the verbose level, so it contains all the logs without enabling the 
+`Verbose Log` toggle.
+
+Let me note that please be sure to remove any sensitive information before sharing the report.
+
+However, the logs would not be kept so long and cleared when restarted. If you
+want to check the logs, please enable `Write logs into the file` temporarily.
+
+![ScreenShot](../images/write_logs_into_the_file.png)
+
+> [!IMPORTANT]
+>
+> - Writing logs into the file will impact the performance.
+> - Please make sure that you have erased all your confidential information
+>   before reporting issue.
+
+### Why are the logs volatile and ephemeral?
+
+To avoid unexpected exposure to our confidential things.
+
+### Some network logs are not written into the file.
+
+Especially the CORS error will be reported as a general error to the plug-in for
+security reasons. So we cannot detect and log it. We are only able to
+investigate them by [Checking the network log](#checking-the-network-log).
+
+### If a file were deleted or trimmed, the capacity of the database should be reduced, right?
+
+No, even though if files were deleted, chunks were not deleted. Self-hosted
+LiveSync splits the files into multiple chunks and transfers only newly created.
+This behaviour enables us to less traffic. And, the chunks will be shared
+between the files to reduce the total usage of the database.
+
+And one more thing, we can handle the conflicts on any device even though it has
+happened on other devices. This means that conflicts will happen in the past,
+after the time we have synchronised. Hence we cannot collect and delete the
+unused chunks even though if we are not currently referenced.
+
+To shrink the database size, `Overwrite Server Data with This Device's Files` is the only reliable and effective way.
+But do not worry, if we have synchronised well. We have the actual and real
+files. Only it takes a bit of time and traffic.
+
+### How to launch the DevTools
+
+#### On Desktop Devices
+
+We can launch the DevTools by pressing `ctrl`+`shift`+`i` (`Command`+`shift`+`i` on Mac).
+
+#### On Android
+
+Please refer to [Remote debug Android devices](https://developer.chrome.com/docs/devtools/remote-debugging/).
+Once the DevTools have been launched, everything operates the same as on a PC.
+
+#### On iOS, iPadOS devices
+
+If we have a Mac, we can inspect from Safari on the Mac. Please refer to [Inspecting iOS and iPadOS](https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios).
+
+### How can I use the DevTools?
+
+#### Checking the network log
+
+1. Open the network pane.
+2. Find the requests marked in red.\
+   ![Errored](../images/devtools1.png)
+3. Capture the `Headers`, `Payload`, and, `Response`. **Please be sure to keep
+   important information confidential**. If the `Response` contains secrets, you
+   can omitted that. Note: Headers contains a some credentials. **The path of
+   the request URL, Remote Address, authority, and authorization must be
+   concealed.**\
+   ![Concealed sample](../images/devtools2.png)
+
+## Troubleshooting
+
+<!-- Add here -->
+
+### While using Cloudflare Tunnels, often Obsidian API fallback and `524` error occurs.
+
+A `524` error occurs when the request to the server is not completed within a
+`specified time`. This is a timeout error from Cloudflare. From the reported
+issue, it seems to be 100 seconds. (#627).
+
+Therefore, this error returns from Cloudflare, not from the server. Hence, the
+result contains no CORS field. It means that this response makes the Obsidian
+API fallback.
+
+However, even if the Obsidian API fallback occurs, the request is still not
+completed within the `specified time`, 100 seconds.
+
+To solve this issue, we need to configure the timeout settings.
+
+Please enable the toggle in `💪 Power users` -> `CouchDB Connection Tweak` ->
+`Use timeouts instead of heartbeats`.
+
+### On the mobile device, cannot synchronise on the local network!
+
+Obsidian mobile is not able to connect to the non-secure end-point, such as
+starting with `http://`. Make sure your URI of CouchDB. Also not able to use a
+self-signed certificate.
+
+### I think that something bad happening on the vault...
+
+Place the [flag file](#flag-files) on top of the vault, and restart Obsidian. The most simple
+way is to create a new note and rename it to `redflag`. Of course, we can put it
+without Obsidian.
+
+For example, if there is `redflag.md`, Self-hosted LiveSync suspends all database and storage
+processes.
+
+### Scram State and Flag Files (SCRAM Warning Loop)
+
+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.
+
+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.
+
+#### 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 (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. (This mechanism is especially useful on mobile devices to force cancellation if the database rebuilding fails). These files are not subject to synchronisation.
+
+Flag-file recovery is handled before the compatibility-review dialogue. `redflag.md` keeps start-up stopped, while a cancelled recovery or one which schedules a restart also prevents a second dialogue from competing with it in that process. When fetch-all or rebuild-all completes and start-up continues, Self-hosted LiveSync can still ask for compatibility review before ordinary synchronisation resumes. Completing a recovery does not automatically acknowledge a database or settings version; use the explicit resume action after reviewing the explanation.
+
+#### How to Resolve the Scram Loop
+
+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
+
+- Rarely, a file in the database could be corrupted. The plug-in will not write
+  to local storage when a file looks corrupted. If a local version of the file
+  is on your device, the corruption could be fixed by editing the local file and
+  synchronising it. But if the file does not exist on any of your devices, then
+  it can not be rescued. In this case, you can delete these items from the
+  settings dialogue.
+- To stop the boot-up sequence (eg. for fixing problems on databases), you can
+  put a `redflag.md` file (or directory) at the root of your vault. Tip for iOS:
+  a redflag directory can be created at the root of the vault using the File
+  application.
+- Also, with `redflag2.md` placed, we can automatically overwrite server data with this device's files during the boot-up sequence. With `redflag3.md`, we
+  can discard only the local database and reset synchronisation on this device.
+- Q: The database is growing, how can I shrink it down? A: each of the docs is
+  saved with their past 100 revisions for detecting and resolving conflicts.
+  Picturing that one device has been offline for a while, and comes online
+  again. The device has to compare its notes with the remotely saved ones. If
+  there exists a historic revision in which the note used to be identical, it
+  could be updated safely (like git fast-forward). Even if that is not in
+  revision histories, we only have to check the differences after the revision
+  that both devices commonly have. This is like git's conflict-resolving method.
+  So, We have to make the database again like an enlarged git repo if you want
+  to solve the root of the problem.
+- And more technical Information is in the [Technical Information](tech_info.md)
+- If you want to synchronise files without obsidian, you can use
+  [filesystem-livesync](https://github.com/vrtmrz/filesystem-livesync).
+- WebClipper is also available on Chrome Web
+  Store:[obsidian-livesync-webclip](https://chrome.google.com/webstore/detail/obsidian-livesync-webclip/jfpaflmpckblieefkegjncjoceapakdf)
+
+Repo is here:
+[obsidian-livesync-webclip](https://github.com/vrtmrz/obsidian-livesync-webclip).
+(Docs are a work in progress.)

esbuild.config.mjs

@@ -1,37 +1,226 @@
+//@ts-check
+
 import esbuild from "esbuild";
 import process from "process";
-import builtins from "builtin-modules";
 import sveltePlugin from "esbuild-svelte";
-import sveltePreprocess from "svelte-preprocess";
+import { sveltePreprocess } from "svelte-preprocess";
+import fs from "node:fs";
+// import terser from "terser";
+import { minify } from "terser";
+import inlineWorkerPlugin from "esbuild-plugin-inline-worker";
+import { terserOption } from "./terser.config.mjs";
+import path from "node:path";
 
-const banner = `/*
-THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
-if you want to view the source, please visit the github repository of this plugin
-*/
-`;
+const prod = process.argv[2] === "production" || process.env?.BUILD_MODE === "production";
+const keepTest = true; //!prod;
 
-const prod = process.argv[2] === "production";
+const manifestJson = JSON.parse(fs.readFileSync("./manifest.json") + "");
+const packageJson = JSON.parse(fs.readFileSync("./package.json") + "");
+const updateInfo = JSON.stringify(fs.readFileSync("./updates.md") + "");
 
-esbuild
-    .build({
-        banner: {
-            js: banner,
+const PATHS_TEST_INSTALL = process.env?.PATHS_TEST_INSTALL || "";
+const PATH_TEST_INSTALL = PATHS_TEST_INSTALL.split(path.delimiter)
+    .map((p) => p.trim())
+    .filter((p) => p.length);
+if (PATH_TEST_INSTALL) {
+    console.log(`Built files will be copied to ${PATH_TEST_INSTALL}`);
+} else {
+    console.log(
+        "Development build: You can install the plug-in to Obsidian for testing by exporting the PATHS_TEST_INSTALL environment variable with the paths to your vault plugins directories separated by your system path delimiter (':' on Unix, ';' on Windows)."
+    );
+}
+
+const moduleAliasPlugin = {
+    name: "module-alias",
+    setup(build) {
+        build.onResolve({ filter: /.(dev)(.ts|)$/ }, (args) => {
+            // console.log(args.path);
+            if (prod) {
+                let prodTs = args.path.replace(".dev", ".prod");
+                const statFile = prodTs.endsWith(".ts") ? prodTs : prodTs + ".ts";
+                const realPath = path.join(args.resolveDir, statFile);
+                console.log(`Checking ${statFile}`);
+                if (fs.existsSync(realPath)) {
+                    console.log(`Replaced ${args.path} with ${prodTs}`);
+                    return {
+                        path: realPath,
+                        namespace: "file",
+                    };
+                }
+            }
+            return null;
+        });
+        build.onResolve({ filter: /.(platform)(.ts|)$/ }, (args) => {
+            // console.log(args.path);
+            if (prod) {
+                let prodTs = args.path.replace(".platform", ".obsidian");
+                const statFile = prodTs.endsWith(".ts") ? prodTs : prodTs + ".ts";
+                const realPath = path.join(args.resolveDir, statFile);
+                console.log(`Checking ${statFile}`);
+                if (fs.existsSync(realPath)) {
+                    console.log(`Replaced ${args.path} with ${prodTs}`);
+                    return {
+                        path: realPath,
+                        namespace: "file",
+                    };
+                }
+            }
+            return null;
+        });
+    },
+};
+
+const removePragmaCommentsPlugin = {
+    name: "remove-pragma-comments",
+    setup(build) {
+        const sourceRoot = `${path.resolve("src")}${path.sep}`;
+        // Filter target extensions (e.g., JavaScript and TypeScript)
+        build.onLoad({ filter: /\.[jt]s?$/ }, async (args) => {
+            // Dependencies are already compiled and may contain comment-like text inside strings.
+            // Only maintained plug-in source needs its local suppression directives removed.
+            if (!args.path.startsWith(sourceRoot)) return;
+            const source = await fs.promises.readFile(args.path, "utf8");
+
+            // Regex targeting both single-line and multi-line comments
+            // This regex looks for:
+            // - /* eslint ... */ (multi-line)
+            // const esLintPragmaRegexBlock = /\/\*[\s\S]*?eslint[\s\S]*?\*\/|([^\\:]|^)\/\/.*eslint.*$/gm;
+            // - // eslint-disable-next-line
+            let cleanedSource = source;
+            const tsIgnoreRegex = /\/\*\s*@ts-ignore\s*\*\/|([^\\:]|^)\/\/.*?@ts-ignore.*$/gm;
+            const esLintPragmaRegexLine = /([^\\:]|^)\/\/.*?eslint-.*$/gm;
+            const exps = [tsIgnoreRegex, esLintPragmaRegexLine];
+            for (const exp of exps) {
+                cleanedSource = cleanedSource.replace(exp, "$1");
+            }
+
+            return {
+                contents: cleanedSource,
+                loader: args.path.endsWith("ts") ? "ts" : "js",
+            };
+        });
+    },
+};
+
+/** @type esbuild.Plugin[] */
+const plugins = [
+    {
+        name: "my-plugin",
+        setup(build) {
+            let count = 0;
+            build.onEnd(async (result) => {
+                if (count++ === 0) {
+                    console.log("first build:");
+                    if (prod) {
+                        console.log("MetaFile:");
+                        if (result.metafile) {
+                            fs.writeFileSync("meta.json", JSON.stringify(result.metafile));
+                            let text = await esbuild.analyzeMetafile(result.metafile, {
+                                verbose: true,
+                            });
+                            // console.log(text);
+                        }
+                    }
+                } else {
+                    console.log("subsequent build:");
+                }
+                const filename = `meta-${prod ? "prod" : "dev"}.json`;
+                await fs.promises.writeFile(filename, JSON.stringify(result.metafile, null, 2));
+                if (prod) {
+                    console.log("Performing terser");
+                    const src = fs.readFileSync("./main_org.js").toString();
+                    // @ts-ignore
+                    const ret = await minify(src, terserOption);
+                    if (ret && ret.code) {
+                        fs.writeFileSync("./main.js", ret.code);
+                    }
+                    console.log("Finished terser");
+                } else {
+                    fs.copyFileSync("./main_org.js", "./main.js");
+                }
+                if (PATH_TEST_INSTALL) {
+                    for (const installPath of PATH_TEST_INSTALL) {
+                        const realPath = path.resolve(installPath);
+                        console.log(`Copying built files to ${realPath}`);
+                        if (!fs.existsSync(realPath)) {
+                            console.warn(`Test install path ${installPath} does not exist`);
+                            continue;
+                        }
+                        const manifestX = JSON.parse(fs.readFileSync("./manifest.json") + "");
+                        manifestX.version = manifestJson.version + "." + Date.now();
+                        fs.writeFileSync(path.join(installPath, "manifest.json"), JSON.stringify(manifestX, null, 2));
+                        fs.copyFileSync("./main.js", path.join(installPath, "main.js"));
+                        fs.copyFileSync("./styles.css", path.join(installPath, "styles.css"));
+                    }
+                }
+            });
         },
-        entryPoints: ["src/main.ts"],
-        bundle: true,
-        external: ["obsidian", "electron", ...builtins],
-        format: "cjs",
-        watch: !prod,
-        target: "es2015",
-        logLevel: "info",
-        sourcemap: prod ? false : "inline",
-        treeShaking: true,
-        plugins: [
-            sveltePlugin({
-                preprocess: sveltePreprocess(),
-                compilerOptions: { css: true },
-            }),
-        ],
-        outfile: "main.js",
-    })
-    .catch(() => process.exit(1));
+    },
+];
+
+const externals = [
+    "obsidian",
+    "electron",
+    "crypto",
+    "@codemirror/autocomplete",
+    "@codemirror/collab",
+    "@codemirror/commands",
+    "@codemirror/language",
+    "@codemirror/lint",
+    "@codemirror/search",
+    "@codemirror/state",
+    "@codemirror/view",
+    "@lezer/common",
+    "@lezer/highlight",
+    "@lezer/lr",
+];
+const context = await esbuild.context({
+    banner: {
+        js: "// Leave it all to terser",
+    },
+    entryPoints: ["src/main.ts"],
+    bundle: true,
+    define: {
+        MANIFEST_VERSION: `"${manifestJson.version}"`,
+        PACKAGE_VERSION: `"${packageJson.version}"`,
+        UPDATE_INFO: `${updateInfo}`,
+        global: "window",
+    },
+    external: externals,
+    // minifyWhitespace: true,
+    format: "cjs",
+    target: "es2018",
+    logLevel: "info",
+    platform: "browser",
+    metafile: true,
+    sourcemap: prod ? false : "inline",
+    treeShaking: false,
+    outfile: "main_org.js",
+    mainFields: ["browser", "module", "main"],
+    minifyWhitespace: false,
+    minifySyntax: false,
+    minifyIdentifiers: false,
+    minify: false,
+    dropLabels: prod && !keepTest ? ["TEST", "DEV"] : [],
+    // keepNames: true,
+    plugins: [
+        moduleAliasPlugin,
+        inlineWorkerPlugin({
+            external: externals,
+            treeShaking: true,
+        }),
+        sveltePlugin({
+            preprocess: sveltePreprocess(),
+            compilerOptions: { css: "injected", preserveComments: false },
+        }),
+        removePragmaCommentsPlugin,
+        ...plugins,
+    ],
+});
+
+if (prod) {
+    await context.rebuild();
+    process.exit(0);
+} else {
+    await context.watch();
+}

eslint.community.config.mjs

@@ -0,0 +1,79 @@
+import obsidianmd from "eslint-plugin-obsidianmd";
+import globals from "globals";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+export default defineConfig(
+    globalIgnores([
+        "node_modules",
+        "**/dist",
+        "build",
+        "coverage",
+        "main.js",
+        "main_org.js",
+        "pouchdb-browser.js",
+        "package.json",
+        "package-lock.json",
+        "versions.json",
+        // Svelte is covered by the project lint and svelte-check; the directory report currently analyses TypeScript.
+        "**/*.svelte",
+        "**/svelte.config.js",
+        "**/*.unit.spec.ts",
+        "**/test/**",
+        "src/apps/_test/**",
+        "src/apps/cli/testdeno/**",
+    ]),
+    {
+        languageOptions: {
+            globals: {
+                ...globals.browser,
+                ...globals.node,
+                MANIFEST_VERSION: "readonly",
+                PACKAGE_VERSION: "readonly",
+                UPDATE_INFO: "readonly",
+                hostPlatform: "readonly",
+            },
+            parserOptions: {
+                project: [
+                    "./tsconfig.json",
+                    "./src/apps/browser/tsconfig.json",
+                    "./src/apps/cli/tsconfig.json",
+                    "./src/apps/webapp/tsconfig.json",
+                    "./src/apps/webpeer/tsconfig.app.json",
+                    "./src/apps/webpeer/tsconfig.node.json",
+                ],
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+    },
+    ...obsidianmd.configs.recommended,
+    {
+        rules: {
+            // The directory review reports console usage as guidance rather than a release blocker.
+            "obsidianmd/rule-custom-message": "off",
+            "no-console": "warn",
+            "obsidianmd/no-unsupported-api": "error",
+            // Keep legacy type-safety debt visible while reserving errors for directory-review blockers.
+            "@typescript-eslint/no-unsafe-argument": "warn",
+            "@typescript-eslint/no-unsafe-assignment": "warn",
+            "@typescript-eslint/no-unsafe-call": "warn",
+            "@typescript-eslint/no-unsafe-member-access": "warn",
+            "@typescript-eslint/no-unsafe-return": "warn",
+            "@typescript-eslint/no-base-to-string": "warn",
+            "@typescript-eslint/no-redundant-type-constituents": "warn",
+            "@typescript-eslint/no-unnecessary-type-assertion": "warn",
+        },
+    },
+    {
+        files: ["src/apps/**/*.{ts,js,mjs}"],
+        rules: {
+            // These applications are inspected by the directory review but accept external command and file data.
+            "@typescript-eslint/restrict-template-expressions": "warn",
+        },
+    },
+    {
+        files: ["src/apps/browser/**/*.ts", "src/apps/webapp/**/*.ts"],
+        rules: {
+            "obsidianmd/prefer-active-doc": "off",
+        },
+    }
+);

eslint.config.common.mjs

@@ -0,0 +1,142 @@
+const restrictedGlobalsOptions = [
+    {
+        name: "app",
+        message: "Avoid using the global app object. Instead use the reference provided by your plugin instance.",
+    },
+    "warn",
+    {
+        name: "fetch",
+        message: "Use the built-in `requestUrl` function instead of `fetch` for network requests in Obsidian.",
+    },
+    {
+        name: "localStorage",
+        message:
+            "Prefer `App#saveLocalStorage` / `App#loadLocalStorage` functions to write / read localStorage data that's unique to a vault.",
+    },
+];
+const restrictedImportsOptions = [
+    {
+        name: "axios",
+        message: "Use the built-in `requestUrl` function instead of `axios`.",
+    },
+    {
+        name: "superagent",
+        message: "Use the built-in `requestUrl` function instead of `superagent`.",
+    },
+    {
+        name: "got",
+        message: "Use the built-in `requestUrl` function instead of `got`.",
+    },
+    {
+        name: "ofetch",
+        message: "Use the built-in `requestUrl` function instead of `ofetch`.",
+    },
+    {
+        name: "ky",
+        message: "Use the built-in `requestUrl` function instead of `ky`.",
+    },
+    {
+        name: "node-fetch",
+        message: "Use the built-in `requestUrl` function instead of `node-fetch`.",
+    },
+    {
+        name: "moment",
+        message: "The 'moment' package is bundled with Obsidian. Please import it from 'obsidian' instead.",
+    },
+];
+
+const warnWhileDev = "off";
+
+/**
+ * @type {import("eslint").Linter.RulesRecord}
+ */
+export const baseRules = {
+    // -- Base rules (turned off in favour of TS specific versions or explicitly disabled).
+    "no-unused-vars": "off",
+    "no-unused-labels": "off",
+    "no-prototype-builtins": "off",
+    "require-await": "off",
+    // -- TypeScript specific rules (Gradual adoption of stricter rules, currently set to 'warn' for a while).
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-redundant-type-constituents": "warn",
+    // -- TypeScript specific rules
+    //  @typescript-eslint/no-unsafe-* rules and @typescript-eslint/no-explicit-any:
+    //  This project contains a lot of library-sh code where the use of `any` is often necessary and justified.
+    //  Rules is now set to 'off' for a while.
+    "@typescript-eslint/no-unsafe-argument": "off",
+    "@typescript-eslint/no-unsafe-call": "off",
+    "@typescript-eslint/no-unsafe-member-access": "off",
+    "@typescript-eslint/no-unsafe-return": "off",
+    "@typescript-eslint/no-unsafe-assignment": "off",
+    // -- Reasonable rules.
+    "@typescript-eslint/no-deprecated": warnWhileDev,
+    "@typescript-eslint/no-unused-vars": ["error", { args: "none" }],
+    "@typescript-eslint/ban-ts-comment": "off",
+    "@typescript-eslint/no-empty-function": "off",
+    "@typescript-eslint/require-await": "error",
+    "@typescript-eslint/no-misused-promises": "error",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-unnecessary-type-assertion": "error",
+
+    // -- General rules
+    "no-async-promise-executor": warnWhileDev,
+    "no-constant-condition": ["error", { checkLoops: false }],
+    // -- Disabled rules
+    // no-undef: This option breaks the global declarations for the library files and is not worth the effort to fix at this time.
+    "no-undef": "off",
+};
+
+/**
+ * @type {import("eslint").Linter.RulesRecord}
+ */
+export const obsidianRules = {
+    // -- Obsidian rules
+    // Runtime fallbacks must use requireApiVersion guards recognised by the official rule.
+    "obsidianmd/no-unsupported-api": "error",
+
+    // -- Plugin specific overrides
+    "obsidianmd/rule-custom-message": "off",
+    "obsidianmd/ui/sentence-case": "off",
+    "obsidianmd/no-plugin-as-component": "warn",
+
+    // -- Temporary overrides for migration
+    "obsidianmd/no-static-styles-assignment": "off",
+};
+/**
+ * @type {(base:string) => import("eslint").Linter.RulesRecord}
+ */
+export const ImportAliasRules = (base) => ({
+    "@dword-design/import-alias/prefer-alias": [
+        "error",
+        {
+            aliasForSubpaths: true,
+            alias: {
+                "@": `${base}/src`,
+            },
+        },
+    ],
+});
+/**
+ * @type {import("eslint").Linter.RulesRecord}
+ */
+export const CommunityReviewRecommendedRules = {
+    "no-unused-vars": "off",
+    "no-prototype-bultins": "off",
+    "no-self-compare": "warn",
+    "no-eval": "error",
+    "no-implied-eval": "error",
+    "prefer-const": "off",
+    "no-implicit-globals": "error",
+    "no-console": "off", // overridden by obsidianmd/rule-custom-message
+    "no-restricted-globals": ["error", ...restrictedGlobalsOptions],
+    "no-restricted-imports": ["error", ...restrictedImportsOptions],
+    "no-alert": "error",
+    "no-undef": "error",
+    "@typescript-eslint/ban-ts-comment": "off",
+    "@typescript-eslint/no-deprecated": "error",
+    "@typescript-eslint/no-unused-vars": ["warn", { args: "none" }],
+    "@typescript-eslint/require-await": "off",
+    "@typescript-eslint/no-explicit-any": ["error", { fixToUnknown: true }],
+    // "import/no-nodejs-modules": "off",
+    // "import/no-extraneous-dependencies": "error",
+};

eslint.config.mjs

@@ -0,0 +1,121 @@
+import tsParser from "@typescript-eslint/parser";
+import obsidianmd from "eslint-plugin-obsidianmd";
+import globals from "globals";
+import { defineConfig, globalIgnores } from "eslint/config";
+import * as sveltePlugin from "eslint-plugin-svelte";
+import svelteParser from "svelte-eslint-parser";
+import importAlias from "@dword-design/eslint-plugin-import-alias";
+import { baseRules, ImportAliasRules, obsidianRules } from "./eslint.config.common.mjs";
+const warnWhileDev = "off"; // Change to "warn" to enable warnings for rules that are currently disabled.
+const lintProjects = [
+    "./tsconfig.json",
+    "./src/apps/browser/tsconfig.json",
+    "./src/apps/cli/tsconfig.json",
+    "./src/apps/webapp/tsconfig.json",
+    "./src/apps/webpeer/tsconfig.app.json",
+    "./src/apps/webpeer/tsconfig.node.json",
+];
+export default defineConfig([
+    globalIgnores([
+        // Build outputs and legacy files
+        "**/build",
+        "**/dist/**",
+        "coverage",
+        "**/main.js",
+        "main_org.js",
+        "pouchdb-browser.js",
+        "version-bump.mjs",
+        "package.json",
+        "**/*.json",
+        "**/.eslintrc.js.bak",
+        // Files from linked dependencies (those files should not exist for most people).
+        "modules/octagonal-wheels/dist",
+
+        // Sub-project tooling with its own environment
+        "utils",
+
+        // Config files and build scripts
+        "**/jest.config.js",
+        "**/rollup.config.js",
+        "**/esbuild.config.mjs",
+        "**/terser.*.mjs",
+        ".prettierrc.*.mjs",
+        ".prettierrc.mjs",
+        "*.config.mjs",
+        "vite.*",
+        "vitest.*",
+        // Testing files (Simplified patterns)
+        "test/**",
+        "**/test/**",
+        "src/apps/_test/**",
+        "src/apps/cli/testdeno/**",
+        "**/*.test.ts",
+        "**/*.unit.spec.ts",
+        "**/test.ts",
+        "**/tests.ts",
+    ]),
+    ...sveltePlugin.configs["flat/base"],
+    ...obsidianmd.configs.recommended,
+    importAlias.configs.recommended,
+    {
+        files: ["**/*.ts"],
+        languageOptions: {
+            globals: { ...globals.browser, PouchDB: "readonly" },
+            parser: tsParser,
+            parserOptions: {
+                project: lintProjects,
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+        linterOptions: {
+            reportUnusedDisableDirectives: false,
+        },
+        rules: {
+            ...baseRules,
+            ...obsidianRules,
+            // -- Project specific rules
+            ...ImportAliasRules("."),
+        },
+    },
+    {
+        files: ["**/*.svelte"],
+        languageOptions: {
+            globals: { ...globals.browser, PouchDB: "readonly" },
+            parser: svelteParser,
+            parserOptions: {
+                parser: tsParser,
+                project: lintProjects,
+                tsconfigRootDir: import.meta.dirname,
+                extraFileExtensions: [".svelte"],
+            },
+        },
+        rules: {
+            // no-unused-vars:
+            // Svelte template's declarations have a lot of false positives and the rule is not worth the effort to fix at this time.
+            // it may improve in the future with some options as like   ["error", { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }],]
+            "no-unused-vars": "off",
+            ...obsidianRules,
+            "obsidianmd/no-plugin-as-component": "off",
+            ...ImportAliasRules("."),
+        },
+    },
+    {
+        files: ["src/apps/**/*.ts"],
+        rules: {
+            // Platform adapters implement asynchronous contracts even when a local operation is synchronous.
+            "@typescript-eslint/require-await": "off",
+            // Keep existing application code visible without making gradual type tightening a release blocker.
+            "@typescript-eslint/no-base-to-string": "warn",
+            "@typescript-eslint/no-unnecessary-type-assertion": "warn",
+            "@typescript-eslint/restrict-template-expressions": "warn",
+        },
+    },
+    {
+        files: ["src/apps/browser/**/*.{ts,svelte}", "src/apps/webapp/**/*.ts"],
+        rules: {
+            // Browser applications use the DOM rather than Obsidian's DOM extensions.
+            "obsidianmd/prefer-create-el": "off",
+            "obsidianmd/prefer-active-doc": "off",
+        },
+    },
+]);

example.env

@@ -0,0 +1 @@
+PATHS_TEST_INSTALL=your-vault-plugin-path:and-another-path