docs: add Vietnamese translations for README and CHANGELOG

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+<p align="center">
+  <a href="CHANGELOG.vi.md">Tiếng Việt</a>
+</p>
+
 ## Unreleased
 
 ### Distro Support

CHANGELOG.vi.md

@@ -0,0 +1,180 @@
+# Nhật ký thay đổi (Changelog)
+
+<p align="center">
+  <a href="CHANGELOG.md">English</a>
+</p>
+
+## Chưa phát hành (Unreleased)
+
+### Hỗ trợ Bản phân phối (Distro Support)
+
+- **Bảng hỗ trợ Distro**: README hiện đã liệt kê các distro hỗ trợ tốt (Ubuntu, Debian, Mint, Pop!_OS, elementary, Zorin, Neon, Fedora, RHEL, CentOS, Arch, Manjaro), có thể hỗ trợ (openSUSE, Solus, Void), và chưa hỗ trợ (NixOS, Alpine, Gentoo).
+- **libwayland-dev** được thêm vào install.sh cho tất cả các họ distro (trước đây bị thiếu — gây lỗi biên dịch trên các hệ thống chỉ có X11 như Linux Mint).
+- **libwayland-client0** được thêm vào các gói phụ thuộc runtime (trước đây bị thiếu — gây lỗi "cannot open shared object file" trên Mint).
+- **Sửa lỗi chính tả cấu hình**: `mặt khẩu` → `mật khẩu` trong cấu hình mặc định và README.
+
+### Tài liệu hướng dẫn (Documentation)
+
+- Thêm mục **Roadmap** vào README (v0.1.8: Giao thức Wayland IM, AT-SPI2 hướng sự kiện; v0.1.9: CI, Flatpak).
+- Loại bỏ **RELEASE_CHECKLIST.md** (quy trình phát hành hiện được ghi nhận trong nội dung các commit phát hành).
+
+---
+
+## v0.1.7 (01-07-2026)
+
+### Tự động nhận diện mật khẩu (Password Auto-Detection)
+
+- **Tích hợp AT-SPI2 D-Bus**: Truy vấn `org.a11y.atspi.Accessible.GetRole` trên a11y bus (không phải session bus) để phát hiện các trường mật khẩu. Hoạt động trên các hộp thoại mật khẩu GUI và các ứng dụng có bật hỗ trợ tiếp cận (a11y).
+- **Phát hiện sudo qua cây tiến trình**: Quét `pstree` để tìm các tiến trình `sudo`/`passwd` — tự động tắt tiếng Việt khi có yêu cầu sudo xuất hiện trong terminal.
+- **Dự phòng tiêu đề cửa sổ**: Các cửa sổ có tiêu đề chứa "password", "sudo", "mật khẩu" sẽ tự động chuyển sang chế độ gõ tiếng Anh.
+- **Dự phòng lớp cửa sổ (Window class)**: Nhận diện các hộp thoại mật khẩu phổ biến (pinentry, polkit, kwallet) thông qua danh sách ứng dụng `password_apps` trong cấu hình.
+- **Kiểm tra định kỳ**: Đánh giá lại trạng thái trường mật khẩu sau mỗi 30 phím gõ (giúp phát hiện kịp thời các prompt nhập mật khẩu xuất hiện trong terminal).
+
+### Phương thức gõ Telex (Telex Input Method)
+
+- **Hỗ trợ đầy đủ Telex**: Cả hai phương thức gõ VNI và Telex hiện đã được hỗ trợ toàn diện. Chuyển đổi nhanh qua Ctrl+Shift hoặc menu khay hệ thống "Input Method > Telex / VNI".
+- **Tệp lưu phương thức gõ** (`~/.config/vietc/method`): Tiến trình nền (daemon) ghi phương thức gõ hiện tại; khay hệ thống đọc tệp này để hiển thị icon tương ứng.
+- **Biểu tượng khay hệ thống**: Màu đỏ "VN" cho VNI, màu xanh dương "TLX" cho Telex, màu xám "EN" cho chế độ tiếng Anh.
+- **Cấu hình**: Phím nóng `toggle_method_key = "shift"` dùng để thiết lập tổ hợp phím đổi phương thức gõ.
+
+### Hỗ trợ GNOME/Wayland (GNOME/Wayland Support)
+
+- **Tích hợp D-Bus của GNOME Shell**: Truy vấn `org.gnome.Shell.Eval` để lấy thông tin về lớp cửa sổ (window class), ID, tiêu đề và PID của ứng dụng đang hoạt động — giải pháp thay thế hoàn hảo trên Wayland GNOME nơi xdotool/xprop không khả dụng.
+- **Chuỗi nhận diện cửa sổ**: GNOME Shell D-Bus → xprop → wlrctl → xdotool → wmctrl → /proc — hoạt động ổn định trên mọi môi trường máy tính.
+- **Nhận diện Compositor**: Tự động phát hiện GNOME/Mutter qua `pgrep gnome-shell` và `XDG_CURRENT_DESKTOP`.
+- **Thư viện phụ thuộc**: Sử dụng thư viện `dbus` (0.9) để giao tiếp với AT-SPI2 và GNOME Shell D-Bus.
+
+### Chiếm quyền bàn phím an toàn (Keyboard Grab Safety)
+
+- **Sử dụng sigaction không có SA_RESTART**: Tổ hợp Ctrl+C và tín hiệu SIGTERM hiện đã có thể ngắt lệnh đọc evdev đang bị chặn, giải phóng quyền chiếm giữ bàn phím trước khi thoát.
+- **Tự động tải uinput**: Bộ giả lập sẽ tự chạy lệnh `modprobe uinput` trước khi mở `/dev/uinput`.
+- **Xử lý EINTR**: Bắt các cuộc gọi hệ thống bị ngắt quãng và tiến hành kiểm tra lại cờ tín hiệu hệ thống.
+- **Thời gian chờ an toàn 30 giây**: Tự động giải phóng quyền chiếm giữ bàn phím nếu không nhận được sự kiện nào sau 30 giây (tránh việc người dùng bị khóa bàn phím vĩnh viễn khi bộ gõ gặp sự cố).
+
+### Clipboard & Giả lập nhập liệu (Clipboard & Injection)
+
+- **Tối ưu hóa `wl-copy --paste-once`**: Giữ tiến trình clipboard hoạt động cho đến khi thao tác dán được thực hiện xong, loại bỏ hoàn toàn độ trễ từ 300-900ms trên môi trường Wayland/GNOME.
+- **Tắt log SelectionRequest trên X11**: Loại bỏ hoàn toàn các dòng log rác liên quan đến clipboard trong terminal.
+- **Ưu tiên uinput**: Giả lập qua uinput luôn được ưu tiên hơn so với giả lập qua X11 XTest.
+
+### Thay đổi cấu hình (Config Changes)
+
+- **Mặc định tắt tính năng tự động khôi phục từ tiếng Anh (auto-restore)**: Tránh việc lặp hoặc mất dấu trên các từ tiếng Việt hợp lệ. Người dùng có thể kích hoạt lại nếu muốn bằng cách đặt `[auto_restore] enabled = true`.
+
+### Cải tiến dòng lệnh (CLI Enhancements)
+
+- **Chuyển tiếp ký tự**: Tất cả các ký tự đều hiển thị trên đầu ra (thay vì chỉ hiển thị các sự kiện chuyển đổi của bộ xử lý Bamboo).
+- **Màn hình hiển thị**: Các phím xóa ngược (backspace) được áp dụng trực quan để mang lại trải nghiệm giống thực tế nhất.
+- **Đặt lại trạng thái**: Mỗi dòng nhập mới sẽ bắt đầu với trạng thái bộ xử lý hoàn toàn sạch.
+- **Lệnh mới**: Thêm các lệnh hỗ trợ `:help`, `:status`, `:vi`, `:en`, `:ar on|off`, `:macros`, `:macro add/rm/clear`, `:events`.
+
+### Sửa lỗi (Bug Fixes)
+
+- **Lỗi lặp dấu cách khi bật/tắt bằng Ctrl+Space**: Chuyển tiếp phím thô hiện đã kiểm tra trạng thái hoạt động của bộ gõ.
+- **Khóa một phiên chạy (Single-instance lock)**: Ghi PID vào tệp khóa; tự động phát hiện và dọn dẹp các tệp khóa cũ khi daemon tắt không bình thường.
+- **Dự phòng xprop/wmctrl**: Nhận diện cửa sổ vẫn hoạt động tốt ngay cả khi hệ thống không cài đặt `xdotool`.
+- **Kết nối AT-SPI2 a11y bus**: Sửa lỗi kết nối nhầm vào session bus; hiện đã kết nối chính xác vào a11y bus riêng biệt.
+- **Đặt lại trạng thái bộ xử lý giữa các dòng nhập trong CLI**.
+
+---
+
+## v0.1.6 (29-06-2026)
+
+### Ưu tiên giả lập uinput (uinput-First Injection)
+
+- **Đảo ngược độ ưu tiên giả lập**: Giả lập qua uinput (`/dev/uinput`) trở thành phương thức giả lập nhập liệu chính trên X11, trong khi XTest chỉ đóng vai trò dự phòng.
+- **Sửa mã phím (keycode) X11 XTest**: Áp dụng độ lệch (offset) +8 cho tất cả các mã phím evdev để đảm bảo tương thích với XTest.
+- **Sửa lỗi xóa ngược trong `paste_via_clipboard()`**: Khắc phục lỗi gửi nhầm mã phím 14 (tương ứng với số "5") thành mã phím 22 (phím Backspace).
+
+### Nhận diện chuyển đổi cửa sổ (Window-Switch Detection)
+
+- **Xác thực ID cửa sổ trên mỗi phím gõ**: Loại bỏ khoảng thời gian bảo vệ 100ms — nhận diện ngay cả khi chuyển cửa sổ cực nhanh dưới 100ms.
+
+### Phương thức nhập liệu (Input Method)
+
+- **Tạm ẩn Telex trên khay hệ thống**: Hiển thị màu xám đi kèm ghi chú "(phiên bản tiếp theo)". Chỉ có phương thức gõ VNI hoạt động ở bản này.
+- **Đổi phương thức gõ mặc định** thành `"vni"`.
+
+### Đóng gói (Packaging)
+
+- **Gỡ bỏ Flatpak và AppImage**: Hiện tại chỉ duy trì và phân phối gói cài đặt `.deb`.
+- **Cải tiến postinst**: Tự động dọn dẹp tệp tin cũ và cấu hình lỗi thời; hiển thị thông báo yêu cầu đăng xuất để áp dụng thay đổi.
+
+---
+
+## v0.1.5 (29-06-2026)
+
+### Đặt lại bộ gõ khi chuyển cửa sổ (Window-Switch Engine Reset)
+
+- **Đặt lại trạng thái bộ gõ khi chuyển cửa sổ**: Khi Alt+Tab giữa các ứng dụng, bộ đệm ký tự của bộ gõ sẽ được xóa sạch. Tránh tình trạng ký tự gõ ở ứng dụng cũ áp dụng quy tắc gõ dấu sang ứng dụng mới gây lỗi hiển thị.
+- **Bỏ tính năng ghi nhận `last_key_time` cho phím điều hướng/bổ trợ**: Các phím bổ trợ đơn thuần (Alt, Ctrl, Shift) không còn làm mới bộ đếm thời gian, giúp việc kiểm tra cửa sổ bằng xprop kích hoạt chính xác sau khi chuyển đổi ứng dụng.
+
+### Nhận diện cửa sổ hoạt động (Active Window Detection)
+
+- **Dự phòng xprop**: Thử gọi `xdotool` trước, sau đó tự động chuyển sang `xprop -root _NET_ACTIVE_WINDOW` (có sẵn trong `x11-utils`). Hoạt động ổn định dưới quyền sudo kể cả khi không cài `xdotool`.
+
+### Dọn dẹp mã nguồn (Code Cleanup)
+
+- **Gỡ bỏ khoảng 400 dòng mã không an toàn (unsafe) không sử dụng**: Xóa toàn bộ khối quản lý chia sẻ trạng thái clipboard X11. Loại bỏ hoàn toàn các cảnh báo `#[warn(dead_code)]` và `#[warn(static_mut_refs)]`.
+- **Xóa mã chết trong bộ gõ**: Loại bỏ các phương thức không dùng đến trong bộ xử lý `BambooEngine` và `InputMethodRules`.
+- **Ghi nhật ký vận hành**: Gỡ bỏ các lệnh `eprintln!` in thông tin theo từng phím gõ trong vòng lặp evdev và luồng dán uinput. Chỉ giữ lại các bản ghi quan trọng (khởi động, lỗi, chuyển cửa sổ) ghi ra stderr và tệp log.
+
+### Biên dịch Flatpak & Khay hệ thống (Flatpak Build & System Tray)
+
+- **Tích hợp khay hệ thống** (`vietc-tray` viết bằng thư viện ksni/DBus) vào trong gói cài đặt Flatpak. Khay hệ thống sẽ tự khởi chạy daemon và hiển thị trạng thái hiện tại.
+- **Lối tắt Menu ứng dụng**: Bộ gõ hiển thị đầy đủ khi tìm kiếm từ khóa **"Viet+"** trên khay hệ thống.
+- **Bỏ hộp thoại mật khẩu khi chạy Flatpak**: Skip sudo khi ứng dụng chạy trong Flatpak do Flatpak đã có sẵn quyền truy cập thiết bị thông qua cờ `--device=all`.
+
+### Nhận diện cửa sổ hoạt động (Sửa lỗi cho Flatpak)
+
+- **Tự động gọi thư viện hệ thống X11** `libX11.so.6` thông qua `dlopen`: Đóng vai trò là phương án dự phòng thứ ba. Giải pháp này giúp nhận diện cửa sổ hoạt động bình thường bên trong sandbox Flatpak nơi `xdotool`/`xprop` bị chặn quyền truy cập.
+
+### Chế độ mặc định (Default Mode)
+
+- **Mặc định bật bộ gõ**: `start_enabled` hiện mặc định là `true` — chế độ tiếng Việt sẽ kích hoạt ngay khi mở ứng dụng.
+
+---
+
+## v0.1.4 (28-06-2026)
+
+### Đóng gói Flatpak (Flatpak Packaging)
+
+- Cung cấp đầy đủ các thành phần đóng gói Flatpak bao gồm daemon, CLI, khay hệ thống, uinputd, và kịch bản khởi chạy.
+
+### Tài liệu hướng dẫn (Documentation)
+
+- Cập nhật README chi tiết về hướng dẫn cài đặt và biên dịch ứng dụng thông qua Flatpak.
+
+### Clipboard & Giả lập nhập liệu (Clipboard & Injection)
+
+- Khắc phục triệt để lỗi tranh chấp clipboard khi giả lập ký tự Unicode tiếng Việt.
+- Thiết lập quy trình tự động đóng gói `.deb` và `.AppImage` trên mỗi lượt đẩy mã nguồn lên GitHub thông qua GitHub Actions.
+
+### Kiểm thử (Tests)
+
+- Hoàn thành **106 bài kiểm thử** đạt yêu cầu (72 bài cho nhân bộ gõ, 16 cho dòng lệnh CLI, 12 cho giao thức, 5 cho tính năng tự động phục hồi và 1 cho quy tắc đặt dấu thanh).
+
+---
+
+## v0.1.3 (26-06-2026)
+
+- Sửa lỗi cụm nguyên âm `ua-horn`, lưu và khôi phục ngữ cảnh clipboard, tối ưu hóa các phím chức năng điều khiển.
+
+---
+
+## v0.1.2 (26-06-2026)
+
+- Chuyển tiếp phím gốc khi xóa đệm, tự động khôi phục từ tiếng Anh gõ nhầm.
+- Sửa quy tắc dấu cho các cụm `qu`/`gi`/`uê`/`uơ`, bỏ lặp phím tự động, tối ưu hóa phím Enter.
+
+---
+
+## v0.1.1 (26-06-2026)
+
+- Khắc phục lỗi nuốt phím Telex khi gõ dấu, duy trì kết nối X11 liên tục.
+
+---
+
+## v0.1.0 (26-06-2026)
+
+- Bản phát hành đầu tiên — chuyển đổi từ bamboo engine, bắt phím evdev, giả lập uinput.

README.md

@@ -18,6 +18,10 @@
   <sub>Zero underline &bull; No pre-edit buffer &bull; Backspace-Replay sync &bull; Built in Rust</sub>
 </p>
 
+<p align="center">
+  <a href="README.vi.md">Tiếng Việt</a>
+</p>
+
 ---
 
 ## What is Viet+?

README.vi.md

@@ -0,0 +1,287 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/Nền_tảng-Linux-blue?style=for-the-badge" alt="Platform">
+  <img src="https://img.shields.io/badge/Ngôn_ngữ-Rust-orange?style=for-the-badge" alt="Rust">
+  <img src="https://img.shields.io/badge/Giấy_phép-MIT-green?style=for-the-badge" alt="License">
+  <img src="https://img.shields.io/badge/Phiên_bản-0.1.7-purple?style=for-the-badge" alt="Version">
+  <img src="https://img.shields.io/badge/Kiểm_thử-108_đạt-brightgreen?style=for-the-badge" alt="Tests">
+  <img src="https://img.shields.io/badge/Event_Sourcing-✓-blueviolet?style=for-the-badge" alt="Event Sourcing">
+</p>
+
+<h1 align="center">
+  <br>
+  Viet+
+  <br>
+</h1>
+
+<p align="center">
+  <b>Bộ gõ tiếng Việt cho Linux</b><br>
+  <sub>Không gạch chân &bull; Không bộ đệm pre-edit &bull; Đồng bộ Backspace-Replay &bull; Viết bằng Rust</sub>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a>
+</p>
+
+---
+
+## Viet+ là gì?
+
+Viet+ là một bộ gõ tiếng Việt dành cho Linux sử dụng hướng tiếp cận hoàn toàn khác biệt so với tất cả các bộ gõ khác: **Gõ trực tiếp (Direct Input)**.
+
+Hầu hết các bộ gõ tiếng Việt hiện nay sử dụng **bộ đệm pre-edit** — khi gõ, các ký tự sẽ nằm trong một bộ đệm tạm thời với dấu gạch chân bên dưới, và chỉ thực sự được gửi đi khi bạn hoàn thành từ đó. Điều này gây ra lỗi lặp từ, xao nhãng bởi dấu gạch chân, lỗi sao chép/dán, và mất đồng bộ giữa bộ gõ với nội dung hiển thị trên màn hình.
+
+Viet+ loại bỏ hoàn toàn những nhược điểm trên. Các phím gõ được **chuyển đổi ngay lập tức sang Unicode** — những gì bạn gõ là những gì bạn thấy. Không bộ đệm tạm thời. Không gạch chân. Không lặp chữ.
+
+---
+
+## Tính năng nổi bật
+
+| Tính năng | Nguyên lý hoạt động |
+|-----------|---------------------|
+| **Gõ trực tiếp** | Không dùng bộ đệm pre-edit. Ký tự được hiển thị ngay lập tức thông qua cơ chế giả lập bàn phím uinput |
+| **VNI & Telex** | Hỗ trợ đầy đủ cả hai phương thức gõ, chuyển đổi nhanh bằng phím nóng Ctrl+Shift |
+| **Bamboo Engine** | Sử dụng mô hình biến đổi Bamboo — ghép âm, bỏ dấu, đặt dấu và xóa dấu linh hoạt |
+| **Ghép âm thông minh** | Hỗ trợ tự động thêm râu/mũ như `uo→ươ` (có hỗ trợ xóa ngược), tự động đặt dấu móc `ua→ưa` |
+| **Gõ tắt (Macro)** | Hỗ trợ mở rộng viết tắt như `ko → không`, `dc → được`, và cho phép tự định nghĩa |
+| **Giữ nguyên hoa/thường** | Bảo toàn định dạng viết hoa như `Tieengs → Tiếng`, `TIEENGS → TIẾNG` |
+| **Nhớ trạng thái theo ứng dụng** | Tự động nhớ trạng thái gõ Anh/Việt cho từng ứng dụng riêng biệt, lưu trữ tại `overrides.toml` |
+| **Tải lại cấu hình nóng** | Các thay đổi trong tệp cấu hình được áp dụng ngay lập tức mà không cần khởi động lại bộ gõ |
+| **Đặt lại khi chuyển cửa sổ** | Tự động xóa bộ đệm của bộ gõ khi nhấn Alt+Tab chuyển ứng dụng |
+| **Độ ưu tiên CPU cao** | Được gán cố định vào các nhân P-core (0-3) và mức ưu tiên nice(-10) để giảm tối đa độ trễ |
+| **Giả lập uinput** | Sử dụng `/dev/uinput` giúp hoạt động ổn định trên cả X11 và Wayland |
+| **Hỗ trợ Terminal** | ✅ Hoạt động mượt mà trên tất cả các terminal phổ biến: kitty, alacritty, gnome-terminal, konsole, foot, wezterm, st, urxvt, xterm |
+| **Tự động nhận diện mật khẩu** | 4 lớp bảo vệ: AT-SPI2 → tiến trình sudo → tiêu đề cửa sổ → lớp (class) cửa sổ |
+| **Biểu tượng khay hệ thống** | Hiển thị trạng thái hiện tại: Đỏ (VN) / Xanh dương (TLX) / Xám (EN) |
+| **GNOME/Wayland** | Tích hợp sâu thông qua cơ chế D-Bus của GNOME Shell |
+
+---
+
+## Phương thức gõ
+
+Viet+ hỗ trợ đầy đủ hai phương thức gõ **VNI** và **Telex**. Bạn có thể chuyển đổi qua lại bằng phím tắt **Ctrl+LeftShift** hoặc qua menu khay hệ thống.
+
+### VNI
+
+| Phím gõ | Kết quả | Ví dụ |
+|---------|---------|-------|
+| `1` | á (sắc) | `a1` → `á` |
+| `2` | à (huyền) | `a2` → `à` |
+| `3` | ả (hỏi) | `a3` → `ả` |
+| `4` | ã (ngã) | `a4` → `ã` |
+| `5` | ạ (nặng) | `a5` → `ạ` |
+| `6` | â/ê/ô | `a6→â`, `e6→ê`, `o6→ô` |
+| `7` | ơ/ư | `o7→ơ`, `u7→ư` |
+| `8` | ă | `a8→ă` |
+| `9` | đ | `d9→đ` |
+
+### Telex
+
+| Phím gõ | Kết quả | Ví dụ |
+|---------|---------|-------|
+| `s` | á (sắc) | `as→á` |
+| `f` | à (huyền) | `af→à` |
+| `r` | ả (hỏi) | `ar→ả` |
+| `x` | ã (ngã) | `ax→ã` |
+| `j` | ạ (nặng) | `aj→ạ` |
+| `aa` | â | `aa→â` |
+| `ee` | ê | `ee→ê` |
+| `oo` | ô | `oo→ô` |
+| `ow` | ơ | `ow→ơ` |
+| `aw` | ă | `aw→ă` |
+| `uw` | ư | `uw→ư` |
+| `dd` | đ | `dd→đ` |
+| `w` | ươ | `chuongw→chương` |
+
+---
+
+## Phím tắt mặc định
+
+| Tổ hợp phím | Hành động |
+|-------------|-----------|
+| **Ctrl+Space** | Bật/Tắt bộ gõ tiếng Việt |
+| **Ctrl+LeftShift** | Chuyển đổi giữa VNI ↔ Telex |
+
+---
+
+## Tự động nhận diện mật khẩu
+
+Viet+ tích hợp hệ thống nhận diện mật khẩu 4 lớp tự động. Khi phát hiện trường nhập mật khẩu, bộ gõ tiếng Việt sẽ tự động tạm thời tắt để tránh lỗi gõ ký tự đặc biệt:
+
+| Lớp nhận diện | Phương pháp | Đối tượng phát hiện |
+|---------------|-------------|---------------------|
+| 1 | AT-SPI2 D-Bus (kiểm tra thuộc tính a11y) | Các trường mật khẩu trong các ứng dụng có hỗ trợ a11y |
+| 2 | Cây tiến trình (pstree) | Tiến trình `sudo` / `passwd` chạy trong terminal |
+| 3 | Từ khóa tiêu đề cửa sổ | Cửa sổ có tiêu đề chứa các từ khóa như `password`, `sudo`, `mật khẩu` |
+| 4 | Lớp cửa sổ (Window class) | Các hộp thoại bảo mật như pinentry, polkit, kwallet |
+
+---
+
+## Khả năng hỗ trợ Distro
+
+| Mức độ | Bản phân phối (Distro) | Cách cài đặt | Trạng thái |
+|--------|------------------------|--------------|------------|
+| ✅ **Hỗ trợ tốt** | Ubuntu, Debian, Linux Mint, Pop!_OS, elementary OS, Zorin, Neon | Trình quản lý `apt` (tự động nhận diện) | Đã kiểm thử, cài đặt bằng một câu lệnh |
+| ✅ **Hỗ trợ tốt** | Fedora, RHEL, CentOS | Trình quản lý `dnf` (tự động nhận diện) | Đã kiểm thử, cài đặt bằng một câu lệnh |
+| ✅ **Hỗ trợ tốt** | Arch, Manjaro | Trình quản lý `pacman` (tự động nhận diện) | Đã kiểm thử, cài đặt bằng một câu lệnh |
+| ⚠️ **Có thể hỗ trợ** | openSUSE, Solus, Void | Trình quản lý `zypper`/`eopkg`/`xbps` (thủ công) | Tên gói phụ thuộc có thể khác biệt; chạy install.sh và tự cài thủ công các gói thiếu nếu lỗi |
+| ❌ **Chưa hỗ trợ** | NixOS, Alpine, Gentoo, các hệ thống khác | N/A | Không có sẵn trong quản lý gói — cần cài gói phụ thuộc thủ công rồi chạy `cargo build --release` |
+
+> **⚠️ Lưu ý về biểu tượng khay hệ thống:** Môi trường GNOME (Ubuntu) và Cinnamon (Mint) cần có phần mềm theo dõi StatusNotifier để hiển thị khay hệ thống:
+> - Ubuntu: `sudo apt install gnome-shell-extension-appindicator`
+> - Mint: Đã được tích hợp sẵn, hoạt động ngay sau khi cài đặt
+
+---
+
+## Cài đặt
+
+### Cài đặt nhanh bằng một câu lệnh
+
+Áp dụng cho tất cả các distro được đánh dấu ✅ **Hỗ trợ tốt** ở trên. Kịch bản cài đặt sẽ tự động nhận diện trình quản lý gói của hệ thống:
+
+**Từ GitHub (khuyên dùng):**
+```bash
+git clone https://github.com/vndangkhoa/vietc.git /tmp/vietc \
+  && cd /tmp/vietc && sudo ./install.sh
+```
+
+**Từ Forgejo (máy chủ riêng):**
+```bash
+git clone https://git.khoavo.myds.me/vndangkhoa/vietc.git /tmp/vietc \
+  && cd /tmp/vietc && sudo ./install.sh
+```
+
+Kịch bản sẽ tự động cài các thư viện phụ thuộc, biên dịch mã nguồn, cài đặt chương trình vào `/usr/bin/`, thiết lập phân quyền cho uinput qua udev rules, và thêm người dùng hiện tại vào nhóm `input`.
+
+**Sau khi cài đặt:** Đăng xuất (Log out) và đăng nhập lại hệ thống, sau đó khởi chạy ứng dụng `vietc-tray` từ menu ứng dụng.
+
+### Gỡ cài đặt nhanh bằng một câu lệnh
+
+**Từ GitHub:**
+```bash
+curl -sSL https://raw.githubusercontent.com/vndangkhoa/vietc/main/uninstall.sh | sudo bash
+```
+
+**Từ Forgejo:**
+```bash
+curl -sSL https://git.khoavo.myds.me/vndangkhoa/vietc/raw/branch/main/uninstall.sh | sudo bash
+```
+
+### Biên dịch & Chạy thủ công
+
+```bash
+# Cài đặt các thư viện phụ thuộc
+sudo apt install git curl build-essential pkg-config \
+  libx11-dev libxtst-dev libevdev-dev libdbus-1-dev libwayland-dev wl-clipboard
+
+# Kích hoạt tính năng hỗ trợ tiếp cận (Ubuntu Wayland — dùng cho nhận diện mật khẩu)
+gsettings set org.gnome.desktop.a11y.applications screen-reader-enabled true
+
+# Biên dịch mã nguồn
+git clone https://github.com/vndangkhoa/vietc.git
+cd vietc
+cargo build --release
+
+# Chạy (Hệ điều hành Mint — không cần quyền sudo cho uinput)
+./target/release/vietc
+
+# Chạy (Hệ điều hành Ubuntu — cần quyền sudo để bắt sự kiện bàn phím)
+sudo ./target/release/vietc
+```
+
+---
+
+## Cấu hình
+
+Tệp cấu hình đặt tại: `~/.config/vietc/config.toml` hoặc `./vietc.toml`
+
+```toml
+input_method = "vni"            # "vni" hoặc "telex"
+toggle_key = "space"            # Ctrl+Space để bật/tắt gõ tiếng Việt
+toggle_method_key = "shift"     # Ctrl+Shift để chuyển đổi VNI/Telex
+start_enabled = true            # Mặc định bật tiếng Việt khi khởi động
+grab = true                     # Độc chiếm bàn phím (evdev)
+
+[auto_restore]
+enabled = false                 # Tự động hoàn tác từ tiếng Anh gõ nhầm (mặc định tắt)
+trigger_keys = ["space", "escape"]
+
+[password_detection]
+enabled = true
+check_atspi2 = true
+check_window_title = true
+title_keywords = ["password", "passphrase", "secret", "mật khẩu", "sudo"]
+password_apps = ["pinentry", "pinentry-gtk-2", "pinentry-qt",
+  "lxqt-sudo", "kdesudo", "gksudo",
+  "polkit-gnome-authentication-agent-1",
+  "kwallet", "gnome-keyring", "ssh-askpass"]
+
+[app_state]
+enabled = true
+english_apps = ["code", "vim"]
+vietnamese_apps = ["telegram", "discord", "firefox"]
+bypass_apps = ["steam"]
+terminal_apps = ["kitty", "alacritty", "gnome-terminal", "konsole", "foot",
+  "wezterm", "st", "urxvt", "xterm"]
+terminal_input_method = "vni"   # Tự động chuyển sang VNI khi chạy trong terminal
+
+[macros]
+ko = "không"
+dc = "được"
+vs = "với"
+```
+
+### Sử dụng trong Terminal
+
+Viet+ hoạt động cực kỳ mượt mà trong các môi trường terminal. Khi bạn sử dụng một terminal (ví dụ: gnome-terminal, kitty), bộ gõ tiếng Việt sẽ tự động áp dụng phương thức gõ được thiết lập tại cấu hình `terminal_input_method` trong mục `[app_state]`.
+
+Các terminal được hỗ trợ sẵn: `kitty`, `alacritty`, `gnome-terminal`, `konsole`, `foot`, `wezterm`, `st`, `urxvt`, `xterm`
+
+Gõ tiếng Việt trực tiếp — không có thanh gạch chân khó chịu, không lặp từ. Chỉ cần gõ phím số VNI hoặc phím chữ Telex và ký tự Unicode sẽ xuất hiện ngay lập tức!
+
+---
+
+## Kiến trúc hệ thống
+
+```
+vietc/
+├── engine/                  # Bộ xử lý chuyển đổi chữ tiếng Việt (chuyển đổi từ bamboo-core)
+├── protocol/                # Thư viện bắt và giả lập sự kiện bàn phím
+│   ├── uinput_monitor.rs    # Giả lập qua /dev/uinput (chính)
+│   ├── x11_inject.rs        # Giả lập qua XTest (dự phòng)
+│   ├── x11_capture.rs       # Bắt phím qua XRecord
+│   └── wayland_im.rs        # Giao thức Wayland IM (đang phát triển)
+├── daemon/                  # Tiến trình nền chính điều khiển bộ gõ
+│   ├── main.rs              # Vòng lặp sự kiện, chiếm quyền bàn phím, xử lý tín hiệu
+│   ├── config.rs            # Tải tệp cấu hình TOML + tự động cập nhật cấu hình nóng
+│   ├── app_state.rs         # Quản lý bộ nhớ trạng thái theo ứng dụng + nhận diện mật khẩu
+│   ├── password_detector.rs # Nhận diện trường mật khẩu qua AT-SPI2 D-Bus
+│   └── display.rs           # Nhận diện máy chủ đồ họa X11/Wayland/Compositor
+├── ui/                      # Biểu tượng khay hệ thống (sử dụng ksni)
+│   └── tray.rs              # Khay hiển thị chế độ VN/TLX/EN
+├── cli/                     # Công cụ dòng lệnh kiểm thử bộ xử lý tiếng Việt
+└── uinputd/                 # Tiến trình đặc quyền quản lý socket uinput
+```
+
+---
+
+## Lộ trình phát triển
+
+### Phiên bản v0.1.8
+- Hỗ trợ giao thức nhập liệu Wayland (`zwp_input_method_v2`) — loại bỏ việc dùng clipboard và tranh chấp Backspace, khắc phục triệt để lỗi mất khoảng trắng.
+- Cơ chế giám sát tiêu điểm AT-SPI2 hướng sự kiện (đăng ký nhận sự kiện tiêu điểm từ a11y thay vì liên tục truy vấn).
+
+### Phiên bản v0.1.9
+- Tự động hóa việc đóng gói tệp tin `.deb` bằng GitHub Actions CI.
+- Khôi phục hỗ trợ Flatpak cho các hệ điều hành bất biến (immutable distros).
+
+---
+
+## Giấy phép sử dụng
+
+Giấy phép MIT — xem chi tiết tại tệp tin [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <sub>Được phát triển với tình yêu dành cho cộng đồng Linux Việt Nam</sub>
+</p>