Markdown File Sync

Kitae can mirror your training log to a folder you choose. Each workout becomes one Markdown file with YAML frontmatter, and edits you make in that folder come back into the app.

The feature is entirely optional. With it off, Kitae works exactly as before.

Why files

Tools and agents get replaced. Plain text on disk outlives them.

• The folder is yours. Open it in Finder or the Files app right now. There is no proprietary database and no sync layer you can’t inspect.
• Markdown is the substrate of the LLM era. Drop the folder into Claude, Cursor, or an Obsidian vault and everything is readable as-is — no export step.
• No Kitae servers. Files go where you put them. If that place happens to be iCloud Drive, Apple syncs it; Kitae contains no iCloud-specific code at all.

Choosing a folder

Settings → Markdown File Sync → Choose Sync Folder.

Any folder works:

Location	What you get
iCloud Drive	Shared across your devices automatically
An Obsidian vault	Workouts appear alongside your notes, with Properties filled in
On My iPhone	Purely local, nothing leaves the device
Dropbox / Google Drive / Syncthing	Whatever that service already does

Before the first sync, Kitae shows you exactly what will happen — how many files it will write, how many records it will import, and whether anything conflicts. Nothing in your folder changes until you confirm.

Layout

YourFolder/
├── 2026/
│   └── 07/
│       ├── 24/
│       │   └── 2026-07-24.md
│       └── 26/
│           ├── 2026-07-26.md
│           └── 2026-07-26-2.md   ← second session that day
├── 2025/
│   └── 12/
│       └── 30/
│           └── 2025-12-30.md
└── .kitae/
    └── tombstones.json           ← records you deleted, so they don't come back

Directories are split by year / month / day, and the date stays in the filename too. 26.md would tell you nothing in an Obsidian tab or a link, so each file is self-describing on its own.

If you rename a file yourself, Kitae keeps your name and never renames it back.

File format

---
id: "550E8400-E29B-41D4-A716-446655440000"
date: "2026-07-26"
created_at: "2026-07-26T09:30:00+09:00"
exercises:
  - Chest Press
  - Lat Pulldown
total_volume: 4820
set_count: 12
---

## 2026-07-26 トレーニング記録

### Chest Press
- W 1: 25kg × 15 reps
- Set 1: 50kg × 8 reps (RPE 9.5)
推定1RM: 63.3kg
総ボリューム: 400kg

### メモ
Good session.

Notes on the format:

• All frontmatter fields are flat — no nesting — so Obsidian’s Properties view renders them cleanly.
• exercises, total_volume, set_count, 推定1RM and 総ボリューム are derived. Kitae writes them for Dataview queries but ignores them when reading; edit the set lines instead.
• id is what ties a file to a record. A file you write by hand doesn’t need one — Kitae assigns it on import.
• Frontmatter keys Kitae doesn’t recognise (your own tags:, for example) are preserved untouched.

Writing a session by hand

Drop a Markdown file with no id into the folder and Kitae imports it as a new record. This is the file-based version of the paste-in-plan flow: ask Claude for tomorrow’s session, save it into the folder, and it shows up in the app.

Exercise names must exactly match the ones in your exercise library. A file with an unknown exercise is skipped and reported — the rest of the sync still runs.

Conflicts

Kitae never merges automatically. If the same workout changed in both the app and the file since they last agreed, it stops and asks which one you want. Both versions stay intact until you choose.

Duplicate files pointing at the same record — Obsidian’s ⌘D, for instance — are also reported rather than silently resolved.

Deleting

Delete records in the app. Deleting only the file restores it on the next sync, and Kitae tells you it did so. When you delete a record in the app, its file is removed and a marker is written to .kitae/tombstones.json so other devices don’t resurrect it.

When sync runs

• Shortly after you stop editing
• The moment the app goes to the background
• When you bring the app back to the foreground
• Whenever you tap Sync Now

If Kitae finds the folder completely empty but has synced records before, it stops instead of rewriting your history — usually that means iCloud hasn’t finished downloading, or the wrong folder is selected.

Body composition

If Include body composition in copies is on, Kitae appends the Apple Health section to each file. The values are captured once, at the moment the file is written, and are not re-read afterwards — Health data can change retroactively, and a workout log should record what was true that day.