ToussaintKnight · ToussaintKnight · Jul 12, 2026 · Jul 12, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -1,6 +1,7 @@
 * text=auto
 *.sh text eol=lf
 *.mjs text eol=lf
+*.json text eol=lf
 *.md text eol=lf
 *.yml text eol=lf
 *.yaml text eol=lf

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,8 +16,8 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
-      - run: npm test
+      - run: npm run check
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,15 @@
 # Changelog
 
+**English** | [简体中文](CHANGELOG.zh-CN.md)
+
 All notable changes are documented here.
 
 ## Unreleased
 
+- Rewrite the README around user pain, executable proof, and ecosystem positioning.
+- Add paired English/Simplified Chinese README, trust, demo, roadmap, and architecture documents.
+- Add a repository-native sensitive-information gate to local checks and CI.
+- Upgrade GitHub Actions runtimes to their current Node 24-based major versions.
 - Detect and quarantine abort events that are semantically closed but incompatible with Codex desktop projection.
 - Repair interrupted turns with Codex-native completion metadata while preserving an explicit non-fabricated tool-output placeholder.
 - Publish the current synchronization result in the same device report instead of reporting the previous run.

diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
@@ -0,0 +1,24 @@
+# 更新日志
+
+[English](CHANGELOG.md) | **简体中文**
+
+所有重要变更都记录在此。
+
+## 未发布
+
+- 围绕用户痛点、可执行证据与生态定位重写 README。
+- 添加成对的英文/简体中文 README、信任、演示、路线图和架构文档。
+- 将仓库原生敏感信息 gate 加入本地检查与 CI。
+- 将 GitHub Actions runtime 升级到当前基于 Node 24 的主版本。
+- 检测并隔离语义上已关闭、但不兼容 Codex 桌面投影的 abort 事件。
+- 使用 Codex 原生完成元数据修复中断回合，同时保留明确且不虚构原始结果的工具输出占位符。
+- 在同一份设备报告中发布当前同步结果，不再落后一轮。
+
+## 0.1.0 - 2026-07-12
+
+- 初始私有仓库基线。
+- 使用每设备 head 与 canonical 提升机制同步已选择会话。
+- 用户 Skill 三方同步与冲突保留。
+- 文件夹与私有 Git transport。
+- Windows/macOS bootstrap、调度、维护、健康报告和恢复命令。
+- 跨平台端到端测试套件。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,19 +1,21 @@
 # Contributing
 
+**English** | [简体中文](CONTRIBUTING.zh-CN.md)
+
 ## Development setup
 
 Install Node.js 22 or newer. The test suite has no third-party runtime dependencies.
 
 ```sh
-npm test
+npm run check
 ```
 
 ## Change workflow
 
 1. Open an issue describing the user impact, reproduction, and safety boundary.
 2. Create a focused branch from the default branch.
 3. Add or update a deterministic test before changing synchronization behavior.
-4. Run `npm test` on the platforms affected by the change.
+4. Run `npm run check` on the platforms affected by the change.
 5. Open a pull request and complete the privacy checklist.
 
 ## Safety invariants
@@ -30,6 +32,8 @@ Changes must preserve these rules:
 
 Use synthetic IDs, paths, conversations, and device names in tests and documentation. Do not contribute real vault data, local reports, IP addresses, usernames, or screenshots containing private task content.
 
+The repository-native privacy gate rejects forbidden state files, credential shapes, private home paths, device IDs, and non-example email addresses. Treat a finding as a release blocker, not as a warning to ignore.
+
 ## Pull requests
 
 Keep changes scoped and describe root cause, user impact, validation, and rollback. A maintainer may request cross-platform evidence for filesystem, scheduler, or SQLite changes.
diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md
@@ -0,0 +1,39 @@
+# 贡献指南
+
+[English](CONTRIBUTING.md) | **简体中文**
+
+## 开发环境
+
+安装 Node.js 22 或更高版本。测试套件没有第三方运行时依赖。
+
+```sh
+npm run check
+```
+
+## 变更流程
+
+1. 创建 Issue，描述用户影响、复现方式和安全边界。
+2. 从默认分支创建范围明确的分支。
+3. 修改同步行为前，先添加或更新确定性测试。
+4. 在受影响的平台运行 `npm run check`。
+5. 创建 Pull Request，并完成隐私检查清单。
+
+## 安全约束
+
+所有变更必须保留以下规则：
+
+- 不得复制身份验证信息或完整 Codex 数据库；
+- 不得发布活动回合或语义不完整回合；
+- 不得静默合并分叉的会话历史；
+- 不得静默覆盖同时发生的 Skill 编辑；
+- 不得自动传播删除；
+- 不得强制重置或强制推送 Git transport；
+- 所有修复操作都必须可从本地备份恢复。
+
+测试和文档必须使用合成 ID、路径、会话与设备名。不要贡献真实 vault 数据、本地报告、IP 地址、用户名或包含私有任务内容的截图。
+
+仓库原生隐私 gate 会拒绝禁止的状态文件、凭据形态、私人 home 路径、设备 ID 与非示例邮箱。任何命中都应视为 release blocker，而不是可忽略警告。
+
+## Pull Request
+
+保持变更范围明确，并说明根因、用户影响、验证方式和回滚方法。对于文件系统、调度器或 SQLite 变更，维护者可能要求跨平台证据。
diff --git a/README.md b/README.md
@@ -1,47 +1,48 @@
 # Codex Sync2
 
-Sync selected local Codex conversations and personal skills across Windows and macOS without copying credentials, entire databases, or unfinished conversation turns.
+**English** | [简体中文](README.zh-CN.md)
 
-Sync2 is for people who use Codex on more than one computer and want a controlled, inspectable alternative to copying the whole `~/.codex` directory.
+Codex task history lives on one machine. **Codex Sync2 gives multi-device Codex users a recoverable synchronization layer for selected tasks and personal skills—without copying credentials, live databases, or unfinished turns.**
+
+Built for developers who move between Windows and macOS and need the same trusted Codex context on every device.
 
 ```text
-Codex device A ─┐
-                ├─ trusted private vault ─ stable conversation snapshots
-Codex device B ─┤                         └ user-defined skills
-Codex device C ─┘
-```
+$ sync2 conversation select current
+Selected: Example task
 
-> Privacy first: the vault contains plaintext conversation text and skill source. Use trusted encrypted storage or a private Git repository. Sync2 deliberately excludes authentication, full databases, logs, caches, attachments, and system/plugin skills.
+$ sync2 sync
+conversationsPushed: 1   conversationConflicts: 0
+
+$ sync2 doctor
+ok: true
+```
 
-## What it does
+## Why Sync2 exists
 
-- Synchronizes only explicitly selected Codex tasks.
-- Publishes only complete JSONL records and stable, closed turns.
-- Keeps independent device heads and promotes a canonical history only when heads have a byte-prefix relationship.
-- Quarantines incomplete or divergent history instead of inventing a merge.
-- Synchronizes user skill collections with three-way hashes and preserved conflict copies.
-- Supports Syncthing/shared-folder and private-Git transports.
-- Updates Codex's local thread indexes without copying another device's SQLite database.
-- Provides maintenance mode, recovery backups, health reports, and schedulers for Windows and macOS.
+Copying `~/.codex` is unsafe: it mixes credentials, device identity, live SQLite state, caches, and partially written turns. Generic file synchronization does not understand which Codex events form a complete conversation.
 
-## Requirements
+Sync2 adds that missing semantic layer:
 
-- Node.js 22 or newer
-- Codex initialized at least once on each device
-- A trusted shared folder, or a checked-out **private** Git repository
-- Syncthing only when using project-folder automation or Syncthing transport
+- select only the tasks worth carrying between devices;
+- publish only complete JSONL and stable, closed turns;
+- keep independent device heads and promote a canonical history only when they are byte-prefix compatible;
+- quarantine incomplete or divergent history instead of inventing a merge;
+- synchronize personal skill collections with three-way hashes and preserved conflict copies;
+- update local Codex indexes without copying another device's database.
 
 ## Quick start
 
-Install the repository as a Codex skill:
+Requirements: Node.js 22+, Codex initialized once on each device, and a trusted shared folder or checked-out private Git vault.
+
+Install as a Codex skill:
 
 ```sh
-git clone <private-repository-url> codex-sync2
+git clone <repository-url> codex-sync2
 mkdir -p "$HOME/.codex/skills/sync2"
 cp -R codex-sync2/. "$HOME/.codex/skills/sync2/"
 ```
 
-Initialize one device against an existing trusted vault:
+Initialize one device:
 
 ```sh
 node "$HOME/.codex/skills/sync2/scripts/sync2.mjs" init \
@@ -50,41 +51,35 @@ node "$HOME/.codex/skills/sync2/scripts/sync2.mjs" init \
   --device mac-main
 ```
 
-In a Codex task, invoke:
-
-```text
-$sync2 current
-```
-
-Only selected tasks are exported. Run `$sync2 doctor` before enabling automatic scheduling.
-
-Windows and macOS bootstrap commands are documented in [references/deployment.md](references/deployment.md).
+Then invoke `$sync2 current` inside the Codex task you want to preserve. Run `$sync2 doctor` before enabling automatic scheduling.
 
-## Safety model
+Windows and macOS cold-start commands are in the [deployment guide](references/deployment.md).
 
-Sync2 treats rollout JSONL as append-only. A snapshot is publishable only when:
+> **Security note:** the operational vault stores selected conversation text and user skill source in plaintext. Sync2 never copies credentials or complete Codex databases. Use only storage and peers you trust; see [Security and privacy](SECURITY.md).
 
-1. every line is valid JSON;
-2. every tool/function call has a matching output;
-3. every older turn is completed or natively interrupted;
-4. the active turn is excluded;
-5. the result is a byte-prefix-compatible device head.
+## How it works
 
-If any rule fails, Sync2 preserves the data and reports the problem. It does not silently choose, truncate, or fabricate history.
-
-See [references/protocol.md](references/protocol.md) for reconciliation and recovery details.
+```mermaid
+flowchart LR
+  A["Device A stable head"] --> V["Syntax + semantic + projection validation"]
+  B["Device B stable head"] --> V
+  C["Device C stable head"] --> V
+  V -->|"all heads share a byte-prefix history"| K["Canonical conversation"]
+  V -->|"divergence or incomplete event"| Q["Preserved quarantine / conflict"]
+  K --> I["Import JSONL + update local indexes"]
+```
 
-## Verification
+Syncthing or private Git transports bytes. Sync2 decides which bytes are a safe Codex conversation. Read the [architecture](docs/architecture.md) and [protocol](references/protocol.md) for the invariants.
 
-Run the deterministic end-to-end suite:
+## Evidence that it works
 
 ```sh
-npm test
+npm run check
 ```
 
-The suite covers folder and Git transports, conversation import, interrupted-event repair, stable active checkpoints, conflict preservation, maintenance mode, Windows extended paths, desktop catalog updates, device reports, and skill reconciliation.
+The deterministic suite runs 65 checks across folder and Git transports, interrupted-event recovery, legacy abort repair, stable active checkpoints, conflict preservation, Windows extended paths, desktop catalog updates, maintenance mode, device reports, and skill reconciliation.
 
-CI runs the suite on Windows, macOS, and Linux with Node.js 22.
+GitHub Actions runs the same privacy gate and tests on Windows, macOS, and Linux with Node.js 22. The fixtures use isolated temporary Codex homes and synthetic conversations; they never read the user's real vault.
 
 ## Data boundaries
 
@@ -97,7 +92,7 @@ Included:
 
 Excluded:
 
-- `auth.json`, tokens, API keys, installation/device credentials;
+- `auth.json`, tokens, API keys, installation and device credentials;
 - `config.toml`, complete SQLite/WAL databases, logs, caches, and models;
 - attachments and generated images;
 - system and plugin-managed skill caches;
@@ -106,21 +101,26 @@ Excluded:
 ## Limitations
 
 - Conversation attachments are not copied.
-- Continuing the same task independently on disconnected devices creates an explicit conflict that requires a human choice.
-- Vault contents are not encrypted by Sync2 itself.
+- Independently continuing the same task while devices are disconnected creates an explicit conflict requiring a human choice.
+- Sync2 does not encrypt the vault itself.
 - Older Sync2 clients do not understand maintenance mode; disable their schedulers before a fleet upgrade.
-- Codex storage formats may evolve, so run `doctor` and the test suite after Codex upgrades.
+- Codex storage formats may evolve; run `doctor` and the test suite after Codex upgrades.
 
 ## Documentation
 
+- [Demonstration](docs/demo.md)
+- [Architecture](docs/architecture.md)
 - [Usage guide](references/usage.md)
 - [Deployment and cold start](references/deployment.md)
 - [Protocol and recovery](references/protocol.md)
-- [Demonstration](docs/demo.md)
 - [Roadmap](docs/roadmap.md)
 - [Security policy](SECURITY.md)
 - [Contributing](CONTRIBUTING.md)
 
+## Project status
+
+Sync2 is an early, tested engineering project. The current release is intended for users comfortable inspecting local files, backups, and synchronization health. Safety and recoverability take priority over automatic conflict resolution.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).