> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files as truth

> Why KiwiFS uses plain markdown files as the source of truth.

In KiwiFS, every page is a **plain markdown file** with optional YAML frontmatter. There is no database, no proprietary format, no schema migration. The filesystem *is* the database.

## Why files?

* **Universal** — every language, tool, and agent can read and write files.
* **Durable** — files outlast databases, SaaS tools, and proprietary formats.
* **Diffable** — git gives you full history, blame, and merge for free.
* **Inspectable** — `cat`, `grep`, `find`, `tree` work out of the box.
* **Portable** — copy the directory to move your knowledge anywhere.

## Frontmatter as structured data

Each file can include YAML frontmatter for structured metadata:

```markdown theme={null}
---
title: Authentication
status: verified
tags: [security, oauth]
author: agent:docs-writer
updated: 2026-04-25
---

# Authentication

OAuth2 + JWT based authentication system...
```

KiwiFS indexes this frontmatter into SQLite, making it queryable via [DQL](/concepts/dql) and the [metadata API](/api/metadata).

## The `.kiwi/` directory

KiwiFS stores its configuration and internal data in a `.kiwi/` directory at the root of your knowledge base:

<Tree>
  <Tree.Folder name="knowledge" defaultOpen>
    <Tree.Folder name=".kiwi" defaultOpen>
      <Tree.File name="config.toml" />

      <Tree.Folder name="comments" />

      <Tree.File name="playbook.md" />

      <Tree.File name="SCHEMA.md" />

      <Tree.Folder name="schemas">
        <Tree.File name="runbook.json" />
      </Tree.Folder>

      <Tree.Folder name="templates">
        <Tree.File name="concept.md" />

        <Tree.File name="runbook.md" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.File name="index.md" />

    <Tree.Folder name="pages" defaultOpen>
      <Tree.File name="getting-started.md" />
    </Tree.Folder>

    <Tree.Folder name="episodes">
      <Tree.File name="example-episode.md" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## Git versioning

When `versioning = "git"` (the default), every write — via REST, MCP, NFS, or filesystem — creates a git commit. The commit author is set from the `X-Actor` header or MCP `actor` parameter.

```bash theme={null}
$ git log --oneline
e4f5g6h agent:docs-writer update concepts/auth.md
a1b2c3d agent:importer    create concepts/auth.md
```

This gives you:

* **Full history** for every page
* **Blame** to trace which agent wrote which line
* **Diff** between any two versions
* **Rollback** to any previous state

## Implications

Because files are the source of truth:

1. **Backup** is `git push` or `rsync`.
2. **Import** adds files; **export** reads them.
3. **Migration** is copying a directory.
4. **Multiple tools** can operate on the same knowledge base (KiwiFS, git, editors, scripts).
5. **No vendor lock-in** — if you stop using KiwiFS, your markdown files remain.