Skip to content

Folder format

Your folder (~/Kaizendex by default) holds all your data as plain files, and the live database in its hidden .kaizendex folder (on a cloud or network drive, the database stays in the app data, ~/.kaizendex/app-data). The files are the database’s mirror, kept in step both ways. See Your folder.

Only the desktop app makes and writes this folder. A browser on the same computer links to the desktop app and writes nothing itself. A browser without the desktop app has no folder: Export gives you the same layout as a ZIP.

The layout

~/Kaizendex/
AGENTS.md the map for agents and people (CLAUDE.md points here)
CLAUDE.md
kaizendex.sqlite a read-only copy of the database
Collections/ one folder per collection
Notes/ plain notes; the app makes it on first start
Health.md
Running plan.md parent: [[Notes/Health]]
Dashboards/ one entry per dashboard; the app makes it on first start
Overview.md the starter dashboard, the first tab of the Home hub
Fitness.md its Dashboard property: tiles of chart and view blocks
Workouts/
_collection.json properties, views (its tabs), card designs, its settings
_schema.md properties, types and tag options, in plain words
Morning run.md one entry
Diary/ a collection set to No AI: locked files
2026-10-08 77ab12cd.md.enc
Skills/
weekly-review/SKILL.md an entry with its own files is a folder
Attachments/
2026-10/run-route.png every photo and file, once, by month
Settings/
sidebar.json the sidebar's five sections: order, hidden ones, removed rows
Hubs/
Home.json one hub: name, icon, tabs and quick options
theme.json
settings.json
Automations/ automations, as .json and .ts files
Design/ designs, as .json, .html, .css and .ts files
Chats/
Coach/2026-10-15 weekly review.md
_inbox/ drop a CSV or markdown files here to import them
.kaizendex/ hidden
main.sqlite the live database: never edit it while the app is open
locked.sqlite locked items, encrypted
vectors.sqlite search by meaning
manifest.json ids, versions, what the app last wrote
problems.md edits the app could not apply, and why

Every file

File Format Who writes it You may edit it
AGENTS.md, CLAUDE.md markdown the app yes: the app rewrites only its own unchanged copy, so your edits stay
kaizendex.sqlite SQLite the app, within seconds of a change no: read only; the app replaces it if changed
Collections/<Collection>/<Entry>.md markdown with frontmatter the app yes
<Entry>.md.enc encrypted the app no: open it in Kaizendex
_collection.json JSON the app yes, checked like a change in the app; a change to Where or the AI setting waits for your OK in the app
_schema.md markdown the app no: it describes the collection
Attachments/<month>/<file> the file itself the app yes
Settings/*.json JSON the app yes, checked
Settings/Hubs/<Hub>.json JSON the app yes, checked
Settings/Automations/ .json, .ts the app yes; a changed automation stays off until you approve it in the app
Settings/Design/ .json, .html, .css, .ts the app yes, checked; your edit waits for “Use it” in the app
Chats/<Agent>/<chat>.md markdown the app not decided
_inbox/ CSV or markdown you or an agent yes: drop files in; each is imported once, then moved to _inbox/imported/
.kaizendex/main.sqlite, locked.sqlite, vectors.sqlite SQLite the engine no: never while the app is open; use the files or kzx
.kaizendex/manifest.json JSON the app no
.kaizendex/problems.md markdown the app no: fix the file it names

Design files. A design is up to three files with one name. star.json holds its settings, star.html the skin’s markup and star.css its CSS. Each text file starts with one line the app writes, such as /* kaizendex design star · contract 1 */; the app removes exactly that line when it reads the file, so your text comes back as you wrote it. An edit to any of the three is checked like a change in the app: a design that breaks a rule is not used, and problems.md names the line. A .css or .html file with no .json beside it is listed in problems.md until you add one.

Read-only folder. In Settings → Folder, a checkbox (off by default). When it is ticked, the app keeps writing these files but ignores edits made in them. See When you or an AI edit the folder.

An entry file

Values sit in the frontmatter (the lines between ---). The Block page text sits below it.

---
id: 01929c4e-7b2a-7c31-9f2e-5d8a1b3c4e6f
title: Morning run
parent: [[Notes/Running plan]]
distance: 5.2
---
Easy pace along the river. Knee was fine. Ran with [[People/Jonas]].
Part Rule
id written by the app; a new file without one becomes a new entry, and the app adds its id; two files with the same id (for example a cloud drive’s conflict copy) are a conflict copy, not a second entry
parent the entry this one sits inside, as a link; change it to move the entry in the tree
Links [[Collection/Entry]], relative to Collections/; Parent, Relations and mentions all use this form. A mention that shows other words is [[Collection/Entry|words]]; a link to a collection is [[Collection]]. Entry is the file name, so a clash suffix is part of it ([[Notes/Ideas 7f3a|Ideas]])
Relations shown in both files: the task has project: [[Projects/Launch]], and Launch lists its tasks
Photos ![[Attachments/2026-10/run-route.png]], the photo’s place in the folder. A picture with its own name shows it after a bar: ![[Attachments/2026-10/run-route.png|my route]]. A locked photo is linked by its .enc copy. A picture with a caption keeps the app’s link, ![caption](kzx://attachment/<id> "name"), because markdown apps have no captions. A link that names no photo in Kaizendex stays plain text and is listed under Fix these
File name the entry’s title; on a clash, a short id is added (Ideas 7f3a.md)

Block pages and Dashboards

Block page and Dashboard properties sit below the frontmatter, one section each. Markdown apps hide the marker lines. What each type holds is on Block pages and dashboards.

The entry has The body
one Block page and no Dashboard plain markdown, with no marker
several Block pages each one starts with <!-- document: Liked today -->
a Dashboard it starts with <!-- grid: Today -->; each tile starts with <!-- tile: x=1 y=1 w=6 h=4 -->, followed by its block

In a tile marker, x is the column the tile starts in (1 to 12) and y is its row. w is its width in columns and h is its height.

Block In the file
Writing and media blocks plain markdown: ## Heading, - [ ] task, ![[Attachments/2026-10/run-route.png]]
Chart, View, Entry and HTML blocks a fenced code block whose language is kzx-chart, kzx-view, kzx-entry or kzx-html, holding the block’s settings as JSON
Columns (Block page only) the marker lines <!-- columns -->, <!-- column --> before each column, and <!-- /columns -->

Obsidian and other markdown apps show a data block as code, so nothing is lost.

A diary day with two Block pages and a Dashboard

The Diary day “28 Oct” has two Block pages and a Dashboard called “Today”. Both charts use the filter “this entry’s date”, so they show 28 Oct only. This is the file with Diary set to Any AI. A locked file holds the same text, encrypted.

---
title: 28 Oct
mood: 7
---
<!-- document: Liked today -->
Long run before work.
<!-- columns -->
<!-- column -->
![[Attachments/2026-10/river.jpg]]
<!-- column -->
Cold, but the light was great.
<!-- /columns -->
<!-- document: Didn't like -->
Too many meetings.
<!-- grid: Today -->
<!-- tile: x=1 y=1 w=6 h=4 -->
```kzx-chart
{ "version": 1, "kind": "bar", "collection": "Steps", "dateFilter": "thisEntry" }
```
<!-- tile: x=7 y=1 w=6 h=4 -->
```kzx-chart
{ "version": 1, "kind": "line", "collection": "Sleep", "dateFilter": "thisEntry" }
```

A dashboard

A dashboard is an entry in Dashboards. Its one Dashboard property is called “Dashboard”.

---
title: Fitness
---
<!-- grid: Dashboard -->
<!-- tile: x=1 y=1 w=8 h=4 -->
```kzx-chart
{ "version": 1, "kind": "line", "collection": "Workouts" }
```
<!-- tile: x=9 y=1 w=4 h=4 -->
```kzx-entry
{ "version": 1, "entry": "Notes/Running plan" }
```
<!-- tile: x=1 y=5 w=12 h=6 -->
```kzx-view
{ "version": 1, "kind": "table", "collection": "Workouts" }
```

Renaming a Block page or Dashboard property rewrites its markers. A missing or broken marker goes to problems.md. No text is lost.

A hub file

A hub is a tab bar of its own, with a name and an icon, in the sidebar. It holds no data, so it is a setting: one file in Settings/Hubs/, named after the hub. The app makes Home.json on first start.

Part Holds
Name and icon the hub’s name, its icon, and what shows: icon and name · icon only · name only
Tabs the tabs, in order. A tab points to an entry (a dashboard, a note, any entry), holds a view that lives in this hub, or points to a view that lives in another tab bar. A tab that points to an entry also holds its Show: one property (such as the Dashboard property) or the whole entry page.
Quick options the choices at the top of the hub’s + menu

This is the Home hub with the tabs Overview · Fitness · This week's tasks · Health log. The first two tabs point to dashboards. The other two hold views that live in this hub.

{
"version": 1,
"name": "Home",
"icon": "house",
"show": "both",
"tabs": [
{ "entry": "Dashboards/Overview" },
{ "entry": "Dashboards/Fitness" },
{ "view": { "name": "This week's tasks", "kind": "board", "collection": "Tasks" } },
{ "view": { "name": "Health log", "kind": "feed", "globalCollection": "Health log" } }
],
"quickOptions": [
{ "new": "entry", "collection": "Dashboards" },
{ "new": "view" },
{ "new": "globalView" }
]
}
  • A view made in a hub lives in the hub file. It does not show up in the collection’s own tabs.
  • Deleting a hub, or a tab, never deletes an entry. If an entry or a view that a tab points to is deleted, the tab goes away too.
  • A collection’s own tab bar stays in its _collection.json: its views, the tabs from other places (with the ↗ mark) and its quick options. The same file holds One entry is called, Several are called, Show in a tab and Show in a block.

The sidebar file

Settings/sidebar.json holds only pointers. Removing a row never deletes the thing.

Part Holds
The five sections Views, Hubs, Chats, Favorites and Collections, in your order (sections); a section left out is hidden
Hidden parts the parts you hid
Removed rows the rows you took out of the sidebar
Favorites what you starred: entries, collections, global collections, hubs

On first start, the sidebar shows Hubs → Home, Favorites (empty), and Collections → Notes and Dashboards, one button each. A collection row never lists its entries. An entry row (in Favorites or a hub) opens into the entries inside it.

Locked files

A collection or entry set to anything but Any AI, or Hidden, is written as .md.enc files. The name is the date and a short id, never the title, because a title can give away private facts. Locked collections are also left out of kaizendex.sqlite.

The folder choice

Choice What the collection’s folder holds
In the folder (default) _collection.json, _schema.md and one file per entry (plain or locked)
Database only _collection.json and _schema.md; the rows are in kaizendex.sqlite
Not in the folder nothing

The read-only database copy

kaizendex.sqlite holds the real tables plus friendly views for SQL:

View Columns
one per collection, named like it ("Workouts") Title, Entry date and one column per property
links from, to, kind (parent, relation, mention)

It is refreshed within seconds, at most once a minute inside a cloud-drive folder, and swapped in whole, so a reader never sees half a file.

What the folder never holds

Sign-in tokens, API keys, device keys and the locked key. They stay in your computer’s keychain.