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 whyEvery 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-5d8a1b3c4e6ftitle: Morning runparent: [[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, , 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 Octmood: 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.