When you or an AI edit the folder
When you or an AI app edit a file in your folder, Kaizendex reads the change back in. It checks it with the same rules as a tap, merges it, and logs it, so you can undo it.
What works today
The desktop app reads your edits back from its first build. kzx sync does the same when the
app is closed.
- It notices fast. The app watches the folder and also scans it now and then, in case it missed an event. On a real account, an edit in a file showed in the open window in under half a second, with no reload.
- Every edit is logged as the folder. History shows “Folder” and the file’s path, and Undo takes it back.
- Fields merge one by one. The app compares the file with the last version both sides agreed on. If only the file changed a field, the file wins. If both changed it, the later edit wins. Block page text merges word by word.
- No common version, no merge. The file’s text is saved in
.kaizendex/conflicts/and listed in.kaizendex/problems.md. The database keeps its version. Picking a version in the app comes later. - One bad value blocks the whole file. Nothing from that file is applied, and the app does not write over it until you fix it.
- A cloud drive’s conflict copy is listed, never applied.
- A protected setting (the AI choice, Hidden, the folder choice) changed in
_collection.jsonis refused, written back and listed. So are a collection’s AI instructions. - A file with no
title:takes its file name as the title. - Read only in the file: children and the other side of a relation. Formulas are not in the file; the app works them out.
- A file whose entry is in the Trash is listed, not restored. Restore it in the app.
Tested hard: 300 random rounds of app edits, file edits, moves, renames, crashes in the middle of a write and conflict copies. Every word arrived once. No entry was lost or doubled.
Not built yet: the Delete and Keep card for many deletes (today the deletes wait and are
listed in problems.md and kzx status), Settings → Folder, the _inbox/ folder, kzx import,
and design files that wait for Use it.
What happens when you change a file
| You do this in the folder | The app does this |
|---|---|
Change a value (distance: 5.2 to 5.4) |
Saves the new value. Undo puts 5.2 back. |
| Change the text under the values | Merges it word by word into the entry’s Block page. |
Change a tile line (<!-- tile: x=1 y=1 w=6 h=4 -->) |
Moves or resizes that tile in the Dashboard property. |
Change the parent: line |
Moves the entry in the tree. Refuses a loop. |
Add a [[link]] in the text |
Adds the mention. A link that names no entry or collection stays plain text and is listed in problems.md. |
| Rename the file | Keeps it the same entry. The app knows each file by its id. |
| Move the file to another collection’s folder | Moves the entry to that collection. Values that do not fit go on the “Fix these” list. |
| Add a new file with no id | Makes a new entry and writes its id into the file. The file keeps its name. |
| Delete a file | Moves the entry to the Trash. Undo brings it back. |
| Delete many files at once | Pauses. Every device shows a card, such as “A device wants to delete 312 entries”, with Delete and Keep. Nothing moves to the Trash until you pick. |
| Let a cloud drive make a file “online only” | Nothing. A file the drive moved off your disk is not a delete. |
Change _collection.json or a file in Settings/ |
Checks and saves it like any setting. A protected change, such as Where or the AI choice, waits for your OK in the app. |
Change a design file in Settings/Design/ |
Waits until you press Use it in the app. |
Privacy settings wait for your OK
Some settings protect your privacy: Where a collection lives, what AI may read, Hidden, sharing. A change to one of them is a change only you can make. A file edit cannot make it on its own.
Example: your Workouts collection is set to This device only. An AI app opens
Collections/Workouts/_collection.json and changes Where to Cloud Sync. The app does not
apply it. It shows “This change needs your OK in the app”, and Workouts stays on this
device. You open the app, check the change, and approve it with Face ID, a fingerprint, Windows
Hello or your computer password. Only then does Workouts go to Cloud Sync.
When the app and a file change the same entry
Example: Claude Code changes “Morning run” from 5.2 km to 5.4 km. At the same time you type a note into the same entry in the app. Both changes survive:
- Different fields both keep their new value.
- The same field takes the later edit. The other value stays in history.
- Text merges word by word, so nobody loses words.
To merge, the app needs the last version that both sides started from. Sometimes it has none, for example when a file comes back from an old backup. Then it never merges in silence. It keeps both versions as a conflict on that entry, and you pick one. The same goes for a cloud drive’s conflict copy. See When the folder is in a cloud drive.
Many deletes at once
A delete from the folder moves one entry to the Trash, with Undo. When many files are gone at once, the app pauses instead. Every device shows a card:
A device wants to delete 312 entries. Delete · Keep
Delete moves them to the Trash. Keep keeps them, and the app writes their files again. Your own deletes in the app never pause: they have Undo, as always.
Read-only folder
Want the files only as a copy, to read, search or keep in Git? In Settings → Folder, select the Read-only folder checkbox. It is off by default.
With it on, Kaizendex keeps writing the folder, but it ignores edits made in it. Example: Claude
Code changes distance: 5.2 to 5.4 in Morning run.md. Your data keeps 5.2.
The switch is also kept in .kaizendex/settings.json ({ "readOnly": true }), so kzx follows it
when the app is closed.
Nothing is lost in silence
An edit that breaks a rule, for example a word where a number belongs, is not applied. It
stays in the file and goes on a list in three places: .kaizendex/problems.md,
Settings → Folder → Fix these, and the kzx status command.
Bulk edits: the inbox
To change many entries at once, drop a CSV (one row per entry) or a batch of markdown files
into _inbox/, or run kzx import. A row with an id changes that entry. A row with no id
makes a new one. The whole import is one step you can undo. Rows it cannot apply are left
out and listed; the good rows still go in.
- Which collection: a
collectioncolumn, else the folder you drop the file in (_inbox/Runs/), else a file named like the collection (Runs.csv). Withkzx import, use--collection Runs. - The columns are the keys of the collection’s
_schema.md:title,date,parent,iconand the property names. A Block page property’s column holds its text. - An empty cell keeps the value it had. Tags, relations and files are lists:
Easy; Long. - Excel’s
;files work, as do tab-separated ones. - See it first:
kzx import runs.csv --dry-runsays how many entries it would add and change, and which rows it would leave out, and changes nothing.
Example: you drop Runs.csv with 200 rows into _inbox/. Two seconds after the file stops
changing, the app adds 198 runs and moves the file to _inbox/imported/. Two rows had a word
where a number belongs: they are listed in Runs.csv.report.md beside it, in
.kaizendex/problems.md and in Settings → Folder. One Undo there takes all 198 back.
With Read-only folder on, files in _inbox/ wait and are listed; kzx import still works.
The inbox writes only where you could edit a file: a collection whose entries are in the folder
as files (not private, Hidden, Database only or Not in the folder), and entries that are not
private or Hidden. While the app owns the folder, kzx import copies your file into _inbox/
and hands the app a request signed with a key kept outside the folder (in the app’s data
folder), so a synced or written file in the folder can never make the app read other files.
Where this works
The same engine keeps files and database in step in the desktop app and in kzx (even when
the app is closed). A browser on the same computer
links to the desktop app, so its changes
reach the folder too. A browser on a computer without the desktop app, and phones, have no
live folder.
Files set to locked are encrypted, so AI apps cannot read or edit them.