sync-notes

intent

sync-notes orchestrates bidirectional sync between a local Obsidian vault and a Cloudflare R2 bucket via rclone's crypt remote, encrypting data end-to-end. triggered by /sync-notes prefix, it translates natural-language intent (setup, init, status, download, upload, or default bisync) into bash subcommands. use this when the user needs to push local notes to the cloud, pull remote notes locally, establish initial baseline, configure credentials, or check sync status.

inputs

Environment variables (required):

• CLOUD_NOTES_PATH: absolute path to the local notes directory. skill aborts with clear error if unset, missing, or not a directory.

External connections:

• Cloudflare R2 bucket: S3-compatible storage. requires ACCESS_KEY_ID, SECRET_ACCESS_KEY, ACCOUNT_ID, and bucket name. stored in config/rclone.conf after setup wizard.
• rclone binary: must be installed and in $PATH. skill checks for presence.
• bash: required to run scripts/sync.sh and scripts/setup.sh.

Configuration files (created and maintained by setup wizard):

• config/rclone.conf: native rclone format with two remotes (r2-raw for raw S3, notes for crypt overlay). gitignored. created with chmod 600. template at config/rclone.conf.example.
• config/.env: non-rclone settings (RCLONE_REMOTE, BACKUP_KEEP, RCLONE_EXTRA_FLAGS). gitignored. created with chmod 600. template at config/.env.example.

State and logs:

• state/bisync/: rclone bisync workdir (listings, lock files). created by rclone on first init.
• logs/sync.log: rolling append-only log of all invocations.
• logs/<UTC-timestamp>.log: per-run rclone output (created each invocation).

Backups:

• backups/latest/: single rolling mirror of local notes directory created before any write operation. previous backup is replaced (not retained). user can manually copy to backups/manual-<UTC>/ before risky operations.

procedure

1. Receive user message starting with /sync-notes.

   • Input: raw user message (e.g., /sync-notes download ideas).
   • Output: confirmed subcommand and arguments to pass to sync.sh.

2. Parse natural-language intent from the suffix (everything after /sync-notes).

   • Input: suffix string (may be empty, in Chinese or English).
   • Extract subcommand using the classifier in "decision points" below.
   • Output: subcommand name (setup, init, bisync, download, upload, status) and glob pattern (if applicable).

3. For download and upload subcommands, convert natural-language target into glob pattern.

   • Input: user intent text (e.g., "ideas 目录" or "welcome").
   • Apply glob rules: bare keyword becomes **keyword**; directory becomes dirname/**; paths with wildcards pass through unchanged; filenames without extension match <name> and <name>.md.
   • Output: glob string (e.g., **ideas** or ideas/** or **welcome**).

4. Validate environment before execution.

   • Input: CLOUD_NOTES_PATH environment variable.
   • Check that CLOUD_NOTES_PATH is set, exists, and is a readable directory.
   • Check that rclone and bash are in $PATH.
   • Output: pass or abort with user-facing error message.

5. Execute the appropriate sync.sh subcommand.

   • Input: subcommand name, glob (if needed), optional --dry-run flag.
   • Run scripts/sync.sh <subcommand> [<glob>] [--dry-run] from the skill root (derived from script location).
   • rclone uses config at config/rclone.conf and crypt remote named in config/.env.
   • Output: exit code, stdout/stderr from rclone, log files written to logs/.

6. Capture and parse rclone output.

   • Input: rclone stdout/stderr from step 5.
   • For bisync, download, upload: scan for conflict files matching *.conflict*.
   • For all subcommands: extract key metrics (files transferred, bytes, duration, errors).
   • Output: structured result (conflict list, counts, timestamps, error messages if any).

7. Report results to user.

   • Input: parsed rclone output and conflict list from step 6.
   • If conflicts found: surface the list verbatim and ask which side to keep (do not auto-resolve).
   • If errors: show error messages and suggest remediation.
   • If success: confirm files transferred, backup location, and when next sync is safe.
   • Output: user-facing message (text, not machine-readable).

decision points

After parsing the suffix, classify intent:

• If suffix is empty or whitespace only: run bisync (default bidirectional sync).
• If suffix contains setup, 配置, wizard: run setup (configuration wizard). user must complete this before first sync.
• If suffix contains init, 初始化, baseline: run init (establish bisync baseline). refuse if baseline already exists unless user passes --force.
• If suffix contains status, 状态, 信息: run status (print config, last-sync time, conflicts, backup state).
• If suffix contains download intent (下载, 拉, pull, download, get, 取回):
  • Extract target token(s) after the intent keyword.
  • Convert to glob pattern using glob rules.
  • If user said "试" or "dry" anywhere, run with --dry-run only (show matches, do not transfer).
  • Otherwise run for real (transfer files). back up local notes first.
  • If glob is ambiguous or matches many files, prompt user to confirm with --dry-run result first.
• If suffix contains upload intent (上传, 推, push, upload, send):
  • Extract target token(s) after the intent keyword.
  • Convert to glob pattern using glob rules.
  • Run sync.sh upload '<glob>' immediately (no --dry-run unless user explicitly asked).
  • Backup not needed (remote is authoritative); local snapshot not created for upload-only.
• If suffix does not match any above: ask user to clarify intent. do not guess or default to bisync.

Before bisync, download, or init (any write-side op):

• Run status first to check for unresolved conflicts.
• If conflicts exist: abort and ask user which side to keep. do not proceed until conflicts are resolved or user says "force".
• If status reports backup state is missing or corrupted, warn user before overwriting.

On network or auth errors:

• If rclone reports "AccessDenied" or "InvalidAccessKeyId": credentials in rclone.conf are wrong. ask user to re-run /sync-notes setup.
• If rclone reports rate-limiting or timeout: retry after user-specified delay (suggest exponential backoff). do not auto-retry without user consent.
• If rclone reports "connection refused" on R2 endpoint: check that endpoint URL in rclone.conf is correct and Cloudflare infrastructure is reachable.

On glob match edge cases:

• If glob pattern matches zero files: report this to user and suggest alternative patterns.
• If glob matches are in the hundreds (or more): show a sample and ask user to confirm before proceeding.

On conflict handling:

• rclone bisync writes conflict markers; script scans for *.conflict* files after each run.
• If any conflicts found: exit non-zero, list them, and ask user to choose "local" or "remote" for each (or delete manually).
• Do not auto-resolve by last-modified time or other heuristics.

On secret handling:

• If user pastes R2 credentials or crypt password into chat: immediately acknowledge, move to config/rclone.conf or config/.env, remove from visible context, and remind user that secrets are stored locally with chmod 600.

output contract

On success (all subcommands):

• Exit code: 0.
• New log file created at logs/<UTC-timestamp>.log containing rclone output.
• Entry appended to logs/sync.log with timestamp, subcommand, and summary (files transferred, duration, status).
• For bisync or download: local snapshot created at backups/latest/ (replaces previous).
• For bisync or download with conflicts: exit code becomes non-zero; conflict file list written to stdout/stderr and logged.
• Data format: plain text log lines, one per invocation. rclone output in per-run files is in rclone's native text format (or JSON if rclone is invoked with --progress=json).

On conflict (bisync, download, or init with existing baseline):

• Exit code: non-zero.
• List of *.conflict* files output to stdout (one per line, with full path).
• User must manually resolve (delete, edit, or choose side) and run status/sync again.

On configuration error (missing rclone.conf, invalid .env, unset CLOUD_NOTES_PATH):

• Exit code: non-zero.
• Error message to stderr: clear explanation of what is missing or broken.
• Suggestion: "run /sync-notes setup to create config" or "set CLOUD_NOTES_PATH=/path/to/notes".

On network or rclone error:

• Exit code: non-zero.
• Error output from rclone captured in logs/<UTC-timestamp>.log.
• Summary message to user: rclone error code + human-readable suggestion (e.g., "check credentials", "retry later").

Status subcommand output:

• Config validity: "✓ rclone.conf found and readable" or "✗ rclone.conf missing".
• Last sync: timestamp of most recent entry in logs/sync.log.
• Conflicts: list of *.conflict* files if any; else "none".
• Backup: path to backups/latest/ and timestamp of last write.

outcome signal

• User knows the skill worked when:
  • For bisync: user receives confirmation message showing count of files synced, direction (push/pull/both), and timestamp. if conflicts, conflict list appears.
  • For download or upload: user sees count of files transferred and size in bytes. if --dry-run, user sees count of files that would be transferred without actually moving data.
  • For init: user sees "baseline established" or "bisync lockfile created at state/bisync/.../".
  • For setup: user sees "config written to config/rclone.conf and config/.env with secure permissions (mode 600)".
  • For status: user sees formatted output with current config state, last sync time, and any pending conflicts.
  • No conflicts reported, or if conflicts exist, user receives numbered list asking for resolution choice.
  • New log file appears at logs/<UTC-timestamp>.log and logs/sync.log has been appended.
  • Local backup exists at backups/latest/ (viewable with ls -la) after any write operation.
  • Chat message tone is matter-of-fact: "synced 42 files in 3.2s" not "successfully synced your precious notes".