diff --git a/README.md b/README.md
index 2a281480..4f8f90dd 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
- English | 繁體中文
+ English | Traditional Chinese
@@ -17,9 +17,9 @@
- 
- 
- 
+ 
+ 
+ 
@@ -29,9 +29,10 @@
Product Preview •
Key Features •
- Developer Quick Start •
OSS Boundaries •
- Contributing
+ Developer Quick Start •
+ Contributing •
+ Community & Social
---
@@ -43,13 +44,13 @@ contributions. This repository provides one public local source-build and
package-verification path; it does not publish official signed installers,
mobile store builds, auto-updates, or hosted services.
-| Surface | Current OSS scope |
-| ------------ | -------------------------------------------------------------- |
-| Desktop | macOS and Windows application runtime |
-| Mobile | iOS and Android application runtime |
-| Linux | Local source-build and package verification only |
-| Network | Foreground sync over the same LAN |
-| Distribution | Community source builds and locally produced packages/binaries |
+| Surface | Current OSS scope |
+| --------------- | -------------------------------------------------------------- |
+| 💻 Desktop | macOS and Windows application runtime |
+| 📱 Mobile | iOS and Android application runtime |
+| 🐧 Linux | Local source-build and package verification only |
+| 🌐 Network | Foreground sync over the same LAN |
+| 📦 Distribution | Community source builds and locally produced packages/binaries |
## 📸 Product Preview
@@ -79,24 +80,17 @@ mobile store builds, auto-updates, or hosted services.
> **Local-LAN Open-Source Core**
>
> - Foreground automatic sync works without sign-in or an account service.
-> - The upload set comes only from the mobile photo-library scan and local
-> pending queue; there is no manual file-selection fallback.
+> - The upload set comes only from the mobile photo-library scan and local pending queue; there is no manual file-selection fallback.
> - The queue is read-only, and each phone uploads one file at a time.
-> - Missing non-OSS modules or account-service state do not block foreground LAN
-> pairing and sync.
+> - Missing non-OSS modules or account-service state do not block foreground LAN pairing and sync.
> [!WARNING]
> **Not Included In This Repository**
>
-> - Remote access, cloud relay, tunnel credentials, official accounts, and silent
-> background continuation are unavailable and remain disabled.
-> - Official signing, notarization, mobile store distribution, package upload,
-> and auto-update infrastructure are not provided.
-> - The source package does not redistribute Apple Bonjour for Windows. It uses
-> a locally installed/configured Bonjour runtime when available, otherwise the
-> zeroconf-compatible fallback.
-> - Linux remains a local build and package-verification target, not a supported
-> desktop user surface.
+> - Remote access, cloud relay, tunnel credentials, official accounts, and silent background continuation are unavailable and remain disabled.
+> - Official signing, notarization, mobile store distribution, package upload, and auto-update infrastructure are not provided.
+> - The source package does not redistribute Apple Bonjour for Windows. It uses a locally installed/configured Bonjour runtime when available, otherwise the zeroconf-compatible fallback.
+> - Linux remains a local build and package-verification target, not a supported desktop user surface.
## 🚀 Developer Quick Start
@@ -104,6 +98,9 @@ This is a contributor workflow, not an end-user installer. See the
[release playbook](./docs/release/release-playbook.md) for local package builds
and platform-specific verification.
+
+💻 Setup & Start Commands
+
```bash
# 1. Enable the repository's pinned pnpm version and install dependencies
corepack enable
@@ -117,10 +114,15 @@ pnpm --filter @lynavo-drive/design-tokens build
pnpm dev:desktop
```
+
+
The Electron window opens automatically, and the desktop app starts the sidecar.
To run a mobile client, keep the desktop running and use another terminal:
+
+📱 Mobile Development Commands
+
```bash
# Start Metro
pnpm dev:mobile
@@ -131,6 +133,8 @@ pnpm --filter @lynavo-drive/mobile ios
pnpm dev:mobile:android
```
+
+
Platform prerequisites still apply: iOS requires macOS, Xcode, and CocoaPods;
Android requires Android Studio plus the Android SDK/NDK.
@@ -147,23 +151,23 @@ Pair the applications:
🔍 View Troubleshooting Guide & Common FAQs
-### 1. The mobile app cannot find my desktop client (mDNS discovery failure)
+### 📡 1. The mobile app cannot find my desktop client (mDNS discovery failure)
- **Check Network**: Ensure both mobile and desktop are on the same local LAN.
- **Windows Firewall**: Verify that Windows Defender Firewall allows incoming traffic for ports `39593` (TCP/LMUP file transport) and `39594` (HTTP API).
- **Bonjour Runtime**: The OSS build doesn't redistribute Apple Bonjour. Ensure Bonjour is installed on Windows, or rely on the zeroconf-compatible fallback.
-### 2. Why are some of my iCloud photos stuck/not transferring?
+### ☁️ 2. Why are some of my iCloud photos stuck/not transferring?
- Photos marked with `iCloud` must be exported from the Apple Photos cloud repository before transfer.
- While in `cloud_downloading` or `preparing` states, the phone is downloading the high-res original asset to local storage. Transfer begins automatically once complete.
-### 3. Can I manually select which photos/videos to sync?
+### 📸 3. Can I manually select which photos/videos to sync?
- No. Automatic upload is driven by the mobile photo-library scan and strictly
read-only pending queue. Checkbox picking is not part of the OSS workflow.
-### 4. What happens when the desktop sleeps or connection drops?
+### 💤 4. What happens when the desktop sleeps or connection drops?
- LAN transfers will interrupt. With the mobile app in the foreground, the
unfinished queue continues after the desktop wakes and LAN connectivity is
@@ -173,40 +177,64 @@ Pair the applications:
-## 🛠️ Tech Stack
-
-| Layer | Technology |
-| -------------- | ---------------------------------------------------------- |
-| Monorepo | pnpm 10 + turborepo 2.8 |
-| Desktop | Electron 41 + electron-vite 5 + electron-builder 26 |
-| Desktop UI | React 18.3 + zustand 5 + Tailwind CSS v4 |
-| Mobile | React Native 0.84.1 + React 19 (iOS / Android) |
-| iOS Native | Swift `SyncEngine` + BGTask + PhotoKit + Network.framework |
-| Android Native | Kotlin bridge + NativeSyncEngine / MediaStore / NsdManager |
-| Sidecar | Go 1.25.6 + SQLite + WebSocket |
-| Shared | `@lynavo-drive/contracts` + `@lynavo-drive/design-tokens` |
-| Test | vitest 4.1 + jest + `go test` |
-
## 🏗️ Architecture Overview
-```text
-Mobile (RN UI on iOS / Android)
- ├── iOS: Swift SyncEngine
- └── Android: Kotlin NativeSyncEngine
- ├── Bonjour/mDNS discover
- ├── LMUP/TCP :39593
- └── Presence/HTTP :39594
- │
- ▼
-Desktop (Electron + Go sidecar, macOS / Windows)
- ├── Electron: UI shell, window, bridge, sidecar lifecycle
- ├── Sidecar HTTP API / WebSocket
- ├── LMUP file receiver
- ├── SQLite
- └── Filesystem / shared directory detection
+```mermaid
+flowchart TD
+ subgraph Mobile["📱 Mobile Client (iOS / Android)"]
+ RN["React Native UI"]
+ subgraph SE["Native Sync Engine"]
+ iOS["iOS (Swift)"]
+ Android["Android (Kotlin)"]
+ end
+ end
+
+ subgraph Desktop["💻 Desktop App (macOS / Windows)"]
+ Electron["Electron Shell (React 18 UI)"]
+ Preload["Preload Bridge"]
+ subgraph Sidecar["Go Sidecar"]
+ HTTP["HTTP API & WebSockets (Port 39594)"]
+ LMUP["LMUP Receiver (Port 39593)"]
+ DB[("SQLite DB")]
+ FS["Filesystem Shared Dirs"]
+ end
+ end
+
+ %% Communication Links
+ RN <--> Preload
+ Preload <--> Electron
+ Electron <--> HTTP
+
+ %% Network Sync Channels
+ SE -- "mDNS Discovery / Pairing" --> HTTP
+ SE -- "Presence & Metadata (HTTP/WS)" --> HTTP
+ SE -- "Incremental Media Sync (LMUP/TCP)" --> LMUP
+
+ classDef mobile fill:#fff0f5,stroke:#db7093,stroke-width:1px;
+ classDef desktop fill:#f0f8ff,stroke:#4682b4,stroke-width:1px;
+ classDef sidecar fill:#f5fffa,stroke:#2e8b57,stroke-width:1px;
+ class Mobile,RN,SE,iOS,Android mobile;
+ class Desktop,Electron,Preload desktop;
+ class Sidecar,HTTP,LMUP,DB,FS sidecar;
```
-## ⚙️ Prerequisites
+## 🔧 Technical Infrastructure
+
+### 🛠️ Tech Stack
+
+| Layer | Technology |
+| ----------------- | ---------------------------------------------------------- |
+| 📦 Monorepo | pnpm 10 + turborepo 2.8 |
+| 💻 Desktop | Electron 41 + electron-vite 5 + electron-builder 26 |
+| 🎨 Desktop UI | React 18.3 + zustand 5 + Tailwind CSS v4 |
+| 📱 Mobile | React Native 0.84.1 + React 19 (iOS / Android) |
+| 🍎 iOS Native | Swift `SyncEngine` + BGTask + PhotoKit + Network.framework |
+| 🤖 Android Native | Kotlin bridge + NativeSyncEngine / MediaStore / NsdManager |
+| ⚡ Sidecar | Go 1.25.6 + SQLite + WebSocket |
+| 🔗 Shared | `@lynavo-drive/contracts` + `@lynavo-drive/design-tokens` |
+| 🧪 Test | vitest 4.1 + jest + `go test` |
+
+### ⚙️ Prerequisites
- **macOS or Windows** (desktop currently supports macOS / Windows; Linux is
only for local build / package verification; iOS builds still require macOS +
@@ -223,7 +251,7 @@ Desktop (Electron + Go sidecar, macOS / Windows)
-## 💻 Common Commands
+### 💻 Common Commands
🛠️ View Developer Command Reference
@@ -256,7 +284,7 @@ pnpm check
-## 📦 OSS Build & Package Verification
+### 📦 OSS Build & Package Verification
This OSS repository keeps contributor-local source-build paths and
GitHub-hosted, secret-free unsigned build/package verification. Hosted outputs
@@ -305,7 +333,7 @@ OSS build-verification outputs and include SHA-256 checksums; see the
[release playbook](./docs/release/release-playbook.md) for the exact asset list,
warnings, and maintainer procedure.
-## 📁 Project Structure
+### 📁 Project Structure
📂 View Directory Structure Map
@@ -351,21 +379,21 @@ lynavo-drive/
## 📄 Documentation Reference
-- Development constraints and operating rules: [`AGENTS.md`](./AGENTS.md)
-- System overview: [`docs/architecture/system-overview.md`](./docs/architecture/system-overview.md)
-- Sync state machine: [`docs/architecture/sync-state-machine.md`](./docs/architecture/sync-state-machine.md)
-- Data model and statistics semantics: [`docs/architecture/data-model.md`](./docs/architecture/data-model.md)
-- Troubleshooting guide: [`docs/operations/troubleshooting.md`](./docs/operations/troubleshooting.md)
-- Mobile diagnostics package: [`docs/operations/mobile-diagnostics.md`](./docs/operations/mobile-diagnostics.md)
-- Sidecar runbook: [`docs/operations/sidecar-runbook.md`](./docs/operations/sidecar-runbook.md)
-- Product constraints, OSS boundaries, and non-goals: [`docs/product/constraints.md`](./docs/product/constraints.md)
-- OSS build verification playbook: [`docs/release/release-playbook.md`](./docs/release/release-playbook.md)
-- OSS verification matrix: [`docs/testing/oss-verification-matrix.md`](./docs/testing/oss-verification-matrix.md)
-- Security policy: [`SECURITY.md`](./SECURITY.md)
-- Privacy notice: [`PRIVACY.md`](./PRIVACY.md)
-- Contributing guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
-- Code of conduct: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
-- Third-party notices: [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)
+- ⚙️ Development constraints and operating rules: [`AGENTS.md`](./AGENTS.md)
+- 📘 System overview: [`docs/architecture/system-overview.md`](./docs/architecture/system-overview.md)
+- 🔄 Sync state machine: [`docs/architecture/sync-state-machine.md`](./docs/architecture/sync-state-machine.md)
+- 📊 Data model and statistics semantics: [`docs/architecture/data-model.md`](./docs/architecture/data-model.md)
+- 🔧 Troubleshooting guide: [`docs/operations/troubleshooting.md`](./docs/operations/troubleshooting.md)
+- 📱 Mobile diagnostics package: [`docs/operations/mobile-diagnostics.md`](./docs/operations/mobile-diagnostics.md)
+- ⚡ Sidecar runbook: [`docs/operations/sidecar-runbook.md`](./docs/operations/sidecar-runbook.md)
+- 🛡️ Product constraints, OSS boundaries, and non-goals: [`docs/product/constraints.md`](./docs/product/constraints.md)
+- 📦 OSS build verification playbook: [`docs/release/release-playbook.md`](./docs/release/release-playbook.md)
+- 🔬 OSS verification matrix: [`docs/testing/oss-verification-matrix.md`](./docs/testing/oss-verification-matrix.md)
+- 🔒 Security policy: [`SECURITY.md`](./SECURITY.md)
+- 🕵️ Privacy notice: [`PRIVACY.md`](./PRIVACY.md)
+- 🤝 Contributing guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md)
+- 📜 Code of conduct: [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
+- 📄 Third-party notices: [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)
## 💡 Contributing
@@ -374,12 +402,18 @@ Community contributions are welcome. To get started:
1. **Fork the Repository**: Create a personal fork and clone it locally.
2. **Set Up the Workspace**: Follow the [Developer Quick Start](#-developer-quick-start) and install the toolchain required by the platform you plan to change.
3. **Verify Your Change**: Run focused tests first, then the applicable repository checks before submitting a pull request:
- ```bash
- pnpm test
- pnpm typecheck
- pnpm format:check
- pnpm gate:release
- ```
+
+
+⚙️ Verification Commands
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm format:check
+pnpm gate:release
+```
+
+
For detailed coding standards, project layouts, and process rules, check out our [Contributing Guidelines](./CONTRIBUTING.md) and [Code of Conduct](./CODE_OF_CONDUCT.md).
@@ -388,6 +422,12 @@ For detailed coding standards, project layouts, and process rules, check out our
- [Request a feature](https://github.com/lynavo/lynavo-drive/issues/new?labels=enhancement)
- [Report a vulnerability privately](https://github.com/lynavo/lynavo-drive/security/advisories/new) instead of posting exploitable details in a public issue.
-## ⚖️ License
+## 🌐 Community & Social
+
+Follow project news and updates across these channels:
-MIT. See [`LICENSE`](./LICENSE).
+- [](https://x.com/founder_im63606) — [@founder_im63606](https://x.com/founder_im63606)
+- [](https://mastodon.social/@ViviDrop) — [@ViviDrop](https://mastodon.social/@ViviDrop)
+- [](https://bsky.app/profile/vividrop.bsky.social) — [@vividrop.bsky.social](https://bsky.app/profile/vividrop.bsky.social)
+- [](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/) — [Lynavo](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/)
+- [](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ) — [YouTube Channel](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ)
diff --git a/README.zh-Hant.md b/README.zh-Hant.md
index 3151f4b6..11857fff 100644
--- a/README.zh-Hant.md
+++ b/README.zh-Hant.md
@@ -17,8 +17,9 @@
- 
-
+
+
+
@@ -28,9 +29,10 @@
產品預覽 •
主要功能 •
- 開發者快速開始 •
開源邊界 •
- 參與貢獻
+ 開發者快速開始 •
+ 參與貢獻 •
+ 社群與社群媒體
---
@@ -39,13 +41,13 @@
Lynavo Drive 已完成主要功能，並開放社群從原始碼建置與參與貢獻。本儲存庫只提供一套公開的本機原始碼建置與套件驗證流程；不發布官方簽署的安裝程式、行動應用程式商店版本、自動更新或託管服務。
-| 使用範圍 | 目前的開源版本支援範圍 |
-| -------- | -------------------------------------------------- |
-| 桌面端 | macOS 與 Windows 應用程式執行環境 |
-| 行動端 | iOS 與 Android 應用程式執行環境 |
-| Linux | 僅供本機原始碼建置與套件驗證 |
-| 網路 | 同一區域網路中的前景同步 |
-| 發布方式 | 社群原始碼建置，以及在本機產生的套件／二進位執行檔 |
+| 使用範圍 | 目前的開源版本支援範圍 |
+| ----------- | -------------------------------------------------- |
+| 💻 桌面端 | macOS 與 Windows 應用程式執行環境 |
+| 📱 行動端 | iOS 與 Android 應用程式執行環境 |
+| 🐧 Linux | 僅供本機原始碼建置與套件驗證 |
+| 🌐 網路 | 同一區域網路中的前景同步 |
+| 📦 發布方式 | 社群原始碼建置，以及在本機產生的套件／二進位執行檔 |
## 📸 產品預覽
@@ -84,6 +86,9 @@ Lynavo Drive 已完成主要功能，並開放社群從原始碼建置與參與
這是提供給貢獻者的開發流程，不是一般使用者安裝程式。本機套件建置與各平台驗證方式請參閱[發布手冊](./docs/release/release-playbook.md)。
+
+💻 安裝與啟動指令
+
```bash
# 1. 啟用儲存庫指定的 pnpm 版本並安裝相依套件
corepack enable
@@ -97,10 +102,15 @@ pnpm --filter @lynavo-drive/design-tokens build
pnpm dev:desktop
```
+
+
Electron 視窗會自動開啟，桌面端應用程式會啟動側車服務 (Sidecar)。
若要執行行動端，請保持桌面端運作，並開啟另一個終端機：
+
+📱 行動端開發指令
+
```bash
# 啟動 Metro
pnpm dev:mobile
@@ -111,6 +121,8 @@ pnpm --filter @lynavo-drive/mobile ios
pnpm dev:mobile:android
```
+
+
仍需準備各平台開發工具：iOS 需要 macOS、Xcode 與 CocoaPods；Android 需要 Android Studio 及 Android SDK／NDK。
配對應用程式：
@@ -125,22 +137,22 @@ pnpm dev:mobile:android
🔍 檢視疑難排解指南與常見問題
-### 1. 行動端應用程式找不到我的桌面裝置（mDNS 裝置探索失敗）
+### 📡 1. 行動端應用程式找不到我的桌面裝置（mDNS 裝置探索失敗）
- **檢查網路**：確保行動端和桌面端皆處於同一個區域網路 (LAN)。
- **Windows 防火牆**：驗證 Windows Defender 防火牆是否允許連接埠 `39593` (TCP/LMUP 檔案傳輸) 和 `39594` (HTTP API) 的連入流量。
- **Bonjour 執行環境**：開源建置版本不重新散布 Apple Bonjour。請確認 Windows 已安裝 Bonjour，否則使用相容於 zeroconf 的備援方案。
-### 2. 為什麼我的一些 iCloud 照片卡住 / 無法傳輸？
+### ☁️ 2. 為什麼我的一些 iCloud 照片卡住 / 無法傳輸？
- 標記為 `iCloud` 的照片在傳輸前，必須先從 Apple Photos 雲端儲存庫中匯出。
- 在 `cloud_downloading` 或 `preparing` 狀態下，手機正在將高解析度的原始內容下載至本機儲存空間。下載完成後會自動開始傳輸。
-### 3. 我可以手動選擇要同步哪些照片 / 影片嗎？
+### 📸 3. 我可以手動選擇要同步哪些照片 / 影片嗎？
- 不行。自動上傳由行動端相簿掃描及嚴格唯讀的待處理佇列驅動，開源流程不提供核取方塊選取功能。
-### 4. 當桌面端進入睡眠狀態或連線中斷時會發生什麼事？
+### 💤 4. 當桌面端進入睡眠狀態或連線中斷時會發生什麼事？
- 區域網路傳輸會中斷。當行動應用程式位於前景時，桌面端喚醒並恢復區域網路連線後，會繼續處理未完成的佇列。
- 開源執行環境不提供靜默背景續傳。
@@ -148,40 +160,64 @@ pnpm dev:mobile:android
-## 🛠️ 技術架構
-
-| 層級 | 技術 |
-| ------------------ | ---------------------------------------------------------- |
-| Monorepo | pnpm 10 + turborepo 2.8 |
-| 桌面端 | Electron 41 + electron-vite 5 + electron-builder 26 |
-| 桌面端 UI | React 18.3 + zustand 5 + Tailwind CSS v4 |
-| 行動端 | React Native 0.84.1 + React 19 (iOS / Android) |
-| iOS 原生 | Swift `SyncEngine` + BGTask + PhotoKit + Network.framework |
-| Android 原生 | Kotlin 橋接 + NativeSyncEngine / MediaStore / NsdManager |
-| 側車服務 (Sidecar) | Go 1.25.6 + SQLite + WebSocket |
-| 共用套件 | `@lynavo-drive/contracts` + `@lynavo-drive/design-tokens` |
-| 測試 | vitest 4.1 + jest + `go test` |
-
## 🏗️ 架構概覽
-```text
-Mobile (RN UI on iOS / Android)
- ├── iOS: Swift SyncEngine
- └── Android: Kotlin NativeSyncEngine
- ├── Bonjour/mDNS discover
- ├── LMUP/TCP :39593
- └── Presence/HTTP :39594
- │
- ▼
-Desktop (Electron + Go sidecar, macOS / Windows)
- ├── Electron: UI shell, window, bridge, sidecar lifecycle
- ├── Sidecar HTTP API / WebSocket
- ├── LMUP file receiver
- ├── SQLite
- └── Filesystem / shared directory detection
+```mermaid
+flowchart TD
+ subgraph Mobile["📱 行動端 (iOS / Android)"]
+ RN["React Native UI"]
+ subgraph SE["原生同步引擎"]
+ iOS["iOS (Swift)"]
+ Android["Android (Kotlin)"]
+ end
+ end
+
+ subgraph Desktop["💻 桌面端 (macOS / Windows)"]
+ Electron["Electron 外殼 (React 18 UI)"]
+ Preload["預載橋接 (Preload Bridge)"]
+ subgraph Sidecar["Go 側車服務 (Sidecar)"]
+ HTTP["HTTP API 與 WebSocket (連接埠 39594)"]
+ LMUP["LMUP 接收器 (連接埠 39593)"]
+ DB[("SQLite 資料庫")]
+ FS["檔案系統共用目錄"]
+ end
+ end
+
+ %% Communication Links
+ RN <--> Preload
+ Preload <--> Electron
+ Electron <--> HTTP
+
+ %% Network Sync Channels
+ SE -- "mDNS 探索 / 配對" --> HTTP
+ SE -- "在線狀態與元資料 (HTTP/WS)" --> HTTP
+ SE -- "增量媒體同步 (LMUP/TCP)" --> LMUP
+
+ classDef mobile fill:#fff0f5,stroke:#db7093,stroke-width:1px;
+ classDef desktop fill:#f0f8ff,stroke:#4682b4,stroke-width:1px;
+ classDef sidecar fill:#f5fffa,stroke:#2e8b57,stroke-width:1px;
+ class Mobile,RN,SE,iOS,Android mobile;
+ class Desktop,Electron,Preload desktop;
+ class Sidecar,HTTP,LMUP,DB,FS sidecar;
```
-## ⚙️ 系統需求
+## 🔧 技術基礎設施
+
+### 🛠️ 技術架構
+
+| 層級 | 技術 |
+| --------------------- | ---------------------------------------------------------- |
+| 📦 Monorepo | pnpm 10 + turborepo 2.8 |
+| 💻 桌面端 | Electron 41 + electron-vite 5 + electron-builder 26 |
+| 🎨 桌面端 UI | React 18.3 + zustand 5 + Tailwind CSS v4 |
+| 📱 行動端 | React Native 0.84.1 + React 19 (iOS / Android) |
+| 🍎 iOS 原生 | Swift `SyncEngine` + BGTask + PhotoKit + Network.framework |
+| 🤖 Android 原生 | Kotlin 橋接 + NativeSyncEngine / MediaStore / NsdManager |
+| ⚡ 側車服務 (Sidecar) | Go 1.25.6 + SQLite + WebSocket |
+| 🔗 共用套件 | `@lynavo-drive/contracts` + `@lynavo-drive/design-tokens` |
+| 🧪 測試 | vitest 4.1 + jest + `go test` |
+
+### ⚙️ 系統需求
- **macOS 或 Windows**（桌面端目前支援 macOS / Windows；Linux 僅用於本機建置 / 套件驗證；iOS 建置仍需要 macOS + Xcode）
- **Node.js** >= 22.12.0
@@ -196,7 +232,7 @@ Desktop (Electron + Go sidecar, macOS / Windows)
-## 💻 常用指令
+### 💻 常用指令
🛠️ 檢視開發者指令參考
@@ -229,9 +265,9 @@ pnpm check
-## 📦 開源版本建置與套件驗證
+### 📦 開源版本建置與套件驗證
-此開源儲存庫保留本機原始碼建置與套件驗證流程。
+此開源儲存庫保留本機原始碼建置與套件驗證流程，以及在 GitHub 上執行、無需儲存庫秘密金鑰 (Secret-free) 的未簽署建置與套件驗證。託管的建置輸出僅為驗證產物，並非官方簽署的發布版本。Linux 僅用於本機驗證，並非支援的桌面端使用者平台。
🔬 檢視驗證與建置管道
@@ -260,9 +296,13 @@ pnpm --filter @lynavo-drive/desktop package:linux -- --arch=arm64
-`release` 設定檔只會注入 `LYNAVO_RELEASE_CHANNEL` 與本機建置設定，並只選擇本機建置 / 套件指令。
+`release` 設定檔只會注入 `LYNAVO_RELEASE_CHANNEL` 與本機建置設定，並只選擇本機建置／套件指令。
+
+GitHub 裝載的工作流程 (Workflows) 可能在無儲存庫秘密金鑰的情況下，使用公開的原始碼調用這些指令。第三方或外部建置服務、程式碼簽署、公證、商店上傳、自動更新以及私有發布基礎設施皆在此開源基準之外。
-## 📁 專案結構
+`OSS Draft Release` 工作流程接受符合 `vX.Y.Z` 的穩定標籤 (Tags)，從該標籤提交重建完整的驗證組套，並建立或更新 GitHub 草稿版本 (Draft Release)。手動派發僅限建置。發布的檔案為未簽署的開源建置驗證輸出，並包含 SHA-256 校驗和；有關確切的資產清單、警示和維護者程序，請參閱[發布手冊](./docs/release/release-playbook.md)。
+
+### 📁 專案結構
📂 檢視目錄結構圖
@@ -305,21 +345,21 @@ lynavo-drive/
## 📄 文件參考
-- 開發限制與營運規則：[`AGENTS.md`](./AGENTS.md)
-- 系統概覽：[`docs/architecture/system-overview.md`](./docs/architecture/system-overview.md)
-- 同步狀態機：[`docs/architecture/sync-state-machine.md`](./docs/architecture/sync-state-machine.md)
-- 資料模型與統計語義：[`docs/architecture/data-model.md`](./docs/architecture/data-model.md)
-- 疑難排解指南：[`docs/operations/troubleshooting.md`](./docs/operations/troubleshooting.md)
-- 行動端診斷套件：[`docs/operations/mobile-diagnostics.md`](./docs/operations/mobile-diagnostics.md)
-- 側車服務 (Sidecar) 運作手冊：[`docs/operations/sidecar-runbook.md`](./docs/operations/sidecar-runbook.md)
-- 產品限制、開源邊界與非目標：[`docs/product/constraints.md`](./docs/product/constraints.md)
-- 開源版本建置驗證手冊：[`docs/release/release-playbook.md`](./docs/release/release-playbook.md)
-- 開源驗證矩陣：[`docs/testing/oss-verification-matrix.md`](./docs/testing/oss-verification-matrix.md)
-- 安全性政策：[`SECURITY.md`](./SECURITY.md)
-- 隱私權聲明：[`PRIVACY.md`](./PRIVACY.md)
-- 貢獻指南：[`CONTRIBUTING.md`](./CONTRIBUTING.md)
-- 行為準則：[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
-- 第三方聲明：[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)
+- ⚙️ 開發限制與營運規則：[`AGENTS.md`](./AGENTS.md)
+- 📘 系統概覽：[`docs/architecture/system-overview.md`](./docs/architecture/system-overview.md)
+- 🔄 同步狀態機：[`docs/architecture/sync-state-machine.md`](./docs/architecture/sync-state-machine.md)
+- 📊 資料模型與統計語義：[`docs/architecture/data-model.md`](./docs/architecture/data-model.md)
+- 🔧 疑難排解指南：[`docs/operations/troubleshooting.md`](./docs/operations/troubleshooting.md)
+- 📱 行動端診斷套件：[`docs/operations/mobile-diagnostics.md`](./docs/operations/mobile-diagnostics.md)
+- ⚡ 側車服務 (Sidecar) 運作手冊：[`docs/operations/sidecar-runbook.md`](./docs/operations/sidecar-runbook.md)
+- 🛡️ 產品限制、開源邊界與非目標：[`docs/product/constraints.md`](./docs/product/constraints.md)
+- 📦 開源版本建置驗證手冊：[`docs/release/release-playbook.md`](./docs/release/release-playbook.md)
+- 🔬 開源驗證矩陣：[`docs/testing/oss-verification-matrix.md`](./docs/testing/oss-verification-matrix.md)
+- 🔒 安全性政策：[`SECURITY.md`](./SECURITY.md)
+- 🕵️ 隱私權聲明：[`PRIVACY.md`](./PRIVACY.md)
+- 🤝 貢獻指南：[`CONTRIBUTING.md`](./CONTRIBUTING.md)
+- 📜 行為準則：[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
+- 📄 第三方聲明：[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md)
## 💡 參與貢獻
@@ -328,12 +368,18 @@ lynavo-drive/
1. **Fork 本儲存庫**：建立個人 Fork 並複製到本機。
2. **設定開發工作區**：依照[開發者快速開始](#-開發者快速開始)，安裝預計修改平台所需的開發工具。
3. **驗證變更**：先執行聚焦測試，再於提交 pull request 前執行適用的儲存庫檢查：
- ```bash
- pnpm test
- pnpm typecheck
- pnpm format:check
- pnpm gate:release
- ```
+
+
+⚙️ 驗證指令
+
+```bash
+pnpm test
+pnpm typecheck
+pnpm format:check
+pnpm gate:release
+```
+
+
詳細的程式撰寫規範、專案結構與開發流程，請參閱[貢獻指南](./CONTRIBUTING.md)及[行為準則](./CODE_OF_CONDUCT.md)。
@@ -342,6 +388,12 @@ lynavo-drive/
- [提出功能建議](https://github.com/lynavo/lynavo-drive/issues/new?labels=enhancement)
- [私下回報安全漏洞](https://github.com/lynavo/lynavo-drive/security/advisories/new)，請勿在公開 issue 張貼可被利用的漏洞細節。
-## ⚖️ 授權條款
+## 🌐 社群與社群媒體
+
+透過以下管道追蹤專案消息與最新動態：
-MIT。請參閱 [`LICENSE`](./LICENSE)。
+- [](https://x.com/founder_im63606) — [@founder_im63606](https://x.com/founder_im63606)
+- [](https://mastodon.social/@ViviDrop) — [@ViviDrop](https://mastodon.social/@ViviDrop)
+- [](https://bsky.app/profile/vividrop.bsky.social) — [@vividrop.bsky.social](https://bsky.app/profile/vividrop.bsky.social)
+- [](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/) — [Lynavo](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/)
+- [](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ) — [YouTube 頻道](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ)
diff --git a/docs/superpowers/plans/2026-07-16-readme-beautification.md b/docs/superpowers/plans/2026-07-16-readme-beautification.md
new file mode 100644
index 00000000..0607d6b0
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-16-readme-beautification.md
@@ -0,0 +1,95 @@
+# README Beautification Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Beautify and modernize the main README.md and the Traditional Chinese translation README.zh-Hant.md.
+
+**Architecture:** Update files directly in the repository. Use uniform flat-square badges, GitHub-specific markdown Alert formats, collapsible `` blocks for verbose sections, and replace ASCII diagrams with high-fidelity Mermaid.js flowcharts.
+
+**Tech Stack:** Markdown, Mermaid.js, Prettier.
+
+---
+
+### Task 1: Beautify English README
+
+**Files:**
+
+- Modify: `README.md`
+
+- [ ] **Step 1: Apply markdown upgrades to README.md**
+
+ Modify the `README.md` file using the following improvements:
+ - Center-align the top branding: Banner, logo, title, description, and badges.
+ - Upgrade badges to a uniform flat-square style.
+ - Wrap the "Project Status" table in a clean description.
+ - Render the visual diagram using a styled Mermaid flowchart showing the connection ports `39593` (LMUP/TCP) and `39594` (HTTP API).
+ - Use GitHub-style `[!IMPORTANT]` and `[!WARNING]` alerts to emphasize OSS boundaries.
+ - Group technical environment/setup commands under a single `🔧 Technical Infrastructure` heading.
+ - Wrap the project directory structure map and development command references inside collapsible `` blocks.
+ - Add flat-square brand shields for each connection/channel under `## 🌐 Community & Social`.
+ - Ensure the `## ⚖️ License` section is completely removed.
+ - Add Emoji icons to the "Project Status" table (Surface column), "Tech Stack" table (Layer column), Documentation Reference list, and FAQs headings as outlined in the design spec.
+ - Keep the entire document strictly in English.
+
+- [ ] **Step 2: Run formatting checks on the main README**
+
+ Run: `pnpm format:check`
+ Expected: Return success or format command pass.
+
+- [ ] **Step 3: Commit the main README changes**
+
+ Run:
+
+ ```bash
+ git add README.md
+ git commit -m "docs: beautify and modernize main README.md with community shields and emoji icons"
+ ```
+
+---
+
+### Task 2: Beautify Traditional Chinese README
+
+**Files:**
+
+- Modify: `README.zh-Hant.md`
+
+- [ ] **Step 1: Apply markdown upgrades to README.zh-Hant.md**
+
+ Modify the `README.zh-Hant.md` file using the exact same structural layout, Mermaid flowchart, collapsible `` components, and Alert blocks as Task 1, translating any newly added English labels (like "Technical Infrastructure" and section names) into Traditional Chinese.
+ - Add flat-square brand shields for each connection/channel under `## 🌐 社群與社群媒體`.
+ - Ensure the `## ⚖️ 授權條款` section is completely removed.
+ - Add Emoji icons to the "Project Status" table, "Tech Stack" table, Documentation Reference list, and FAQs headings matching the English layout (with appropriate Traditional Chinese localizations).
+ - Keep the entire document strictly in Traditional Chinese.
+
+- [ ] **Step 2: Run formatting checks on the Traditional Chinese README**
+
+ Run: `pnpm format:check`
+ Expected: Return success or format command pass.
+
+- [ ] **Step 3: Commit the Traditional Chinese README changes**
+
+ Run:
+
+ ```bash
+ git add README.zh-Hant.md
+ git commit -m "docs: beautify and synchronize Traditional Chinese README with community shields and emoji icons"
+ ```
+
+---
+
+### Task 3: Full Validation & Verification
+
+**Files:**
+
+- Validate: `README.md`
+- Validate: `README.zh-Hant.md`
+
+- [ ] **Step 1: Check format validation for all modified files**
+
+ Run: `pnpm format:check`
+ Expected: PASS
+
+- [ ] **Step 2: Verify git status is clean**
+
+ Run: `git status`
+ Expected: Working tree clean (all changes committed).
diff --git a/docs/superpowers/specs/2026-07-16-readme-beautification-design.md b/docs/superpowers/specs/2026-07-16-readme-beautification-design.md
new file mode 100644
index 00000000..eac3c8ff
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-16-readme-beautification-design.md
@@ -0,0 +1,127 @@
+# README Beautification & Modernization Spec
+
+This document outlines the design and plan for beautifying `README.md` and `README.zh-Hant.md` to present a modern, premium layout, clear technical information, and a high-fidelity Mermaid.js architecture diagram.
+
+## Goals
+
+1. **Modern Layout**: Enhance typography, use uniform badges, and structure sections using clear visual hierarchies.
+2. **Interactive Diagrams**: Replace the text-based ASCII diagram with a dynamic Mermaid.js flowchart mapping mobile-desktop relationships and communications.
+3. **Structured Collapse**: Wrap long logs, folder structures, and developer commands in `` blocks to keep the page clean and scannable.
+4. **Bilingual Sync**: Fully align `README.md` (English) and `README.zh-Hant.md` (Traditional Chinese) in terms of structure and updates.
+
+## Technical Details
+
+### 1. Badges & Header
+
+- Align the headers, logos, and badges at the top center.
+- Use uniform flat-square style shields for all badges:
+ - OSS Release Gate: `https://github.com/lynavo/lynavo-drive/actions/workflows/oss-release-gate.yml/badge.svg`
+ - Node.js: `>= 22.12.0` (green/blue logo)
+ - Go: `>= 1.25.6` (00ADD8 logo)
+ - Platform: macOS | Windows (lightgrey)
+ - Mobile: iOS | Android (lightgrey)
+ - License: MIT (green)
+
+### 2. Architecture Diagram (Mermaid)
+
+Replace ASCII with:
+
+```mermaid
+flowchart TD
+ subgraph Mobile["📱 Mobile Client (iOS / Android)"]
+ RN["React Native UI"]
+ subgraph SE["Native Sync Engine"]
+ iOS["iOS (Swift)"]
+ Android["Android (Kotlin)"]
+ end
+ end
+
+ subgraph Desktop["💻 Desktop App (macOS / Windows)"]
+ Electron["Electron Shell (React 18 UI)"]
+ Preload["Preload Bridge"]
+ subgraph Sidecar["Go Sidecar"]
+ HTTP["HTTP API & WebSockets (Port 39594)"]
+ LMUP["LMUP Receiver (Port 39593)"]
+ DB[("SQLite DB")]
+ FS["Filesystem Shared Dirs"]
+ end
+ end
+
+ %% Communication Links
+ RN <--> Preload
+ Preload <--> Electron
+ Electron <--> HTTP
+
+ %% Network Sync Channels
+ SE -- "mDNS Discovery / Pairing" --> HTTP
+ SE -- "Presence & Metadata (HTTP/WS)" --> HTTP
+ SE -- "Incremental Media Sync (LMUP/TCP)" --> LMUP
+
+ classDef mobile fill:#fff0f5,stroke:#db7093,stroke-width:1px;
+ classDef desktop fill:#f0f8ff,stroke:#4682b4,stroke-width:1px;
+ classDef sidecar fill:#f5fffa,stroke:#2e8b57,stroke-width:1px;
+ class Mobile,RN,SE,iOS,Android mobile;
+ class Desktop,Electron,Preload desktop;
+ class Sidecar,HTTP,LMUP,DB,FS sidecar;
+```
+
+### 3. OSS Boundaries
+
+Format the open-source gates using GitHub Alerts:
+
+- `[!IMPORTANT]` for Local-LAN open-source core details.
+- `[!WARNING]` for out-of-scope non-OSS boundaries (such as remote connection, cloud relay, store distribution, etc.).
+
+### 4. Technical Infrastructure Section
+
+Group the following sub-headings under a single unified section:
+
+- **Prerequisites**
+- **Tech Stack**
+- **Common Commands**
+- **Project Structure**
+- **OSS Build & Package Verification**
+ Fold long listings (like commands, package verification, folder map) inside `` blocks.
+
+### 5. Community & Social Shields
+
+- Replace text links in the "Community & Social" (or "社群與社群媒體") section with modern flat-square brand badges:
+ - X: `[](https://x.com/founder_im63606)`
+ - Mastodon: `[](https://mastodon.social/@ViviDrop)`
+ - Bluesky: `[](https://bsky.app/profile/vividrop.bsky.social)`
+ - LinkedIn: `[](https://www.linkedin.com/in/lynavo-lynavo-1273322b6/)`
+ - YouTube: `[](https://www.youtube.com/channel/UCMcYmWmPMzQ5N8bHFffnldQ)`
+
+### 6. Emoji Icons Enhancements
+
+Add clear visual Emoji icons to:
+
+- **Project Status Table (Surface column)**:
+ - `💻 Desktop` / `💻 桌面端`
+ - `📱 Mobile` / `📱 行動端`
+ - `🐧 Linux` / `🐧 Linux`
+ - `🌐 Network` / `🌐 網路`
+ - `📦 Distribution` / `📦 發布方式`
+- **Tech Stack Table (Layer column)**:
+ - `📦 Monorepo`
+ - `💻 Desktop`
+ - `🎨 Desktop UI`
+ - `📱 Mobile`
+ - `🍎 iOS Native`
+ - `🤖 Android Native`
+ - `⚡ Sidecar` / `⚡ 側車服務 (Sidecar)`
+ - `🔗 Shared` / `🔗 共用套件`
+ - `🧪 Test` / `🧪 測試`
+- **Documentation Reference List**: Add document type icons (e.g. `⚙️`, `📘`, `🔄`, `📊`, `🔧`, `📱`, `⚡`, `🛡️`, `📦`, `🔬`, `🔒`, `🕵️`, `🤝`, `📜`, `📄`) before the descriptions.
+- **FAQs & Troubleshooting H3 Headings**: Add category/topic icons (e.g. `📡`, `☁️`, `📸`, `💤`) to the questions.
+
+### 7. License Removal
+
+- Note that the "License" and "授權條款" sections have been explicitly removed.
+
+## Execution Checklist
+
+- [ ] Update `README.md` (English only, no Chinese) to add community shields, table/list/FAQ emoji icons, and ensure no License section.
+- [ ] Update `README.zh-Hant.md` (Traditional Chinese only) to add community shields, table/list/FAQ emoji icons, and ensure no License section.
+- [ ] Verify formatting and markdown structure in both files.
+- [ ] Run `pnpm format:check` to ensure no linting/formatting regression.