docs(aw-sync): document the working sync path; drop stale limitations

[TimeToBuildBob]

Fixes #690.

#685 is parked for v0.14.0, so writing this README "after the daemon switch" would ship a release that still recommends the no-op. This is the interim note the issue asked for.

What changed

• Usage leads with aw-sync sync (the path that actually pulls and pushes) and aw-sync status.
• aw-sync / aw-sync daemon is marked broken for mixed/Android layouts (aw-sync: daemon (the default subcommand) never pulls — two incompatible sync-folder layouts #682), not recommended.
• Setup says share the folder before running aw-sync, and shows {hostname}/{device_id}/test.db.
• FAQ: drop "Android unsupported" and "window/afk by default". Android is supported via the official app; default is all buckets (SyncSpec.buckets: None).

Not in this PR

• The daemon layout switch itself (fix(aw-sync): make default daemon use host-layout pull/push #685, parked).
• Rewriting the advanced testing scripts.

[TimeToBuildBob]

Review guide (auto-posted)

Structured warm-up for reviewers — what changed, what to run, where to look.

Key files

• aw-sync/README.md (+32/-23, Δ55)

Suggested verification

• Run the repo's usual CI-equivalent checks locally

Known risks / watch points

• No automatic high-risk tags; use file list + diff for judgment.

Suggested review focus

• Confirm behavior matches the PR description acceptance criteria.
• Skim the largest diffs first (listed above).
• If CI is green, spot-check the highest-risk paths called out here.

Generated by scripts/github/pr-warmup-review-guide.py for #701.

[ErikBjare]

@TimeToBuildBob Accurate for the parked-#685 state — leads with aw-sync sync, daemon marked broken with the mechanism and #682 linked, Android claim fixed, folder-sharing-first and the 3-level layout documented. Merge on green.

One word of precision, non-blocking: "Other devices cannot see that file" overstates it — a peer running the same bare daemon can (pure-daemon meshes did see each other; that is why the layout split went unnoticed). Precise form: "aw-sync sync and the Android app cannot see that file." Since #690 was about the README saying things that are not true, worth getting exactly right.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.92%. Comparing base (656f3c9) to head (7e0e58e).
⚠️ Report is 115 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #701      +/-   ##
==========================================
+ Coverage   70.81%   79.92%   +9.10%     
==========================================
  Files          51       72      +21     
  Lines        2916     6823    +3907     
==========================================
+ Hits         2065     5453    +3388     
- Misses        851     1370     +519     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[TimeToBuildBob]

🤖 AI code review

This PR updates aw-sync/README.md to document the current sync behavior: it leads with the one-shot aw-sync sync command, marks the daemon as not pulling from the 3-level layout, adds setup instructions to share the sync directory first, and revises the FAQ to state Android is supported and all buckets are synced by default. It also updates the running-from-source example to use cargo run --bin aw-sync -- sync.

Safe to merge — no P0/P1 findings

Confidence 5/5

✅ No thread-worthy findings. Advisory notes follow; they are retained without opening review threads.

1 advisory finding (summary-only, not scored)

These P2 guard, heuristic, trade-off, or documentation claims are retained for judgment without opening review threads.

⚠️ P2 medium — aw-sync/README.md:43

The README's new usage section says aw-sync sync "Pull every 3-level peer and push this device, then exit", but the later bullet on line 43 says bare aw-sync sync (no extra flags) is the 3-level path and always does both a pull and a push. However, the same bullet also says that passing --mode / --buckets / --start-date / --sync-db switches to sync_run, which uses the two-level layout. The README does not clarify that --mode is a flag that, when passed alone, switches to the two-level path, so a user following the documented --mode option (e.g., aw-sync sync --mode push) would be on the two-level path and would not see Android peers, contradicting the earlier claim that aw-sync sync pulls 3-level peers. This is a documentation inconsistency that could mislead users into thinking --mode works with the 3-level path.

Clarify that `aw-sync sync --mode` (or any of the listed flags) uses the two-level layout, and only bare `aw-sync sync` uses the 3-level path. For example: "Bare `aw-sync sync` (no extra flags) is the 3-level path and always does both a pull and a push. Adding `--mode`, `--buckets`, `--start-date`, or `--sync-db` switches to `sync_run`, which uses the two-level layout and will not see Android or bare-`aw-sync sync` peers."

_{How this was verified: Read the full README lines 17-43; the usage block at line 20-21 says aw-sync sync pulls 3-level peers, but line 43 says adding --mode switches to two-level. The PR description also states that --mode with no other options is enough to opt into the per-bucket sync path.}

Files changed (1) — the diff as I read it

• aw-sync/README.md — Rewrites usage, setup, and FAQ sections to describe the working sync path and the daemon's two-level layout limitation.

Previous review passes

commit	score	findings	engine	when
2448184b4fca	5/5	0	llm	2026-09-16 09:49 UTC

_{Reviewed 7e0e58eb096f · openrouter/deepseek/deepseek-v4-flash-0731 · llm engine · 18s · about this reviewer}

_{Maintainer commands}

_{@TimeToBuildBob review (own line) — fresh review · @TimeToBuildBob fix — a worker acts on the findings. Once per comment; 👀 = received.}

[TimeToBuildBob]

Pushed two README precision fixes:

• 2448184: "Other devices cannot see that file" → "aw-sync sync and the Android app cannot see that file."
• 7e0e58e: dropped the --mode/--buckets examples from the working-path block. Those flags still go through sync_run (2-level), so they cannot talk to Android / bare aw-sync sync peers.

CI is green on 7e0e58e (Build + Lint). I don't have merge rights on ActivityWatch/aw-server-rust (pull-only) — needs your click.

[greptile-apps]

Confidence Score: 4/5

The PR should not merge until the README stops recommending advanced one-shot variants as compatible with Android and other three-level peers.

Findings

1.  Advanced sync uses wrong layout ▶

Summary

This documentation update redirects users from the currently incompatible daemon layout to one-shot synchronization, describes the shared-folder structure, and updates Android and bucket-default guidance.

• Recommends aw-sync sync and aw-sync status.
• Explains the two-level daemon and three-level Android/legacy layouts.
• Removes stale Android and window/AFK-only limitations.
• Incorrectly treats advanced aw-sync sync variants as using the working three-level path, although they still use the two-level implementation.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[aw-sync sync] --> B{Advanced option supplied?}
  B -->|No| C[Legacy pull_all and push]
  C --> D["3-level: hostname/device_id/test.db"]
  B -->|Yes| E[sync_run]
  F[aw-sync daemon] --> E
  E --> G["2-level: device_id/test.db"]
  D -. layouts are mutually invisible .- G

Loading

_{Reviews (1) · Last reviewed commit: "docs(aw-sync): document the working sync..."}

[TimeToBuildBob]

Post-merge check on this mention: the PR was merged at 09:04Z (merge commit 7636fcd2) and #690 closed with it.

The precision note from 2026-09-16 landed in 2448184 ("aw-sync sync and the Android app cannot see that file") and 7e0e58e; the merged README now scopes --mode / --buckets / --start-date / --sync-db to the two-level sync_run path, so they are no longer presented as Android-compatible.

Docs-only change — nothing to deploy or bump. No further action from me on #701; the remaining aw-sync items are tracked separately (#685 parked, #682 / #688 / #692 / #693 / #696).