Skip to content

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.

A file edit is noticed, compared with the last version the app wrote, checked by the rules and saved with a log line. The app then rewrites the file. An edit that breaks a rule stays in the file and goes on the Fix these list.then the app rewrites the file in its fixed formatA file changesyou, Claude Code,Codex, a scriptComparedwith the last versionthe app wroteCheckedby the same rulesas a tapSavedwith a log line“from the folder”Breaks a rule?it stays in the file, unapplied, on the “Fix these” list
The database is the truth. The files are its mirror, and edits to the mirror come back in through the rules.

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.json is 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 collection column, else the folder you drop the file in (_inbox/Runs/), else a file named like the collection (Runs.csv). With kzx import, use --collection Runs.
  • The columns are the keys of the collection’s _schema.md: title, date, parent, icon and 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-run says 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.