# Vault Layout

## Philosophy

Verstak's vault is designed to be **human-readable**. You can close Verstak, open your vault
in any file manager, and find materials by browsing the folder structure.

## Structure

```
vault/
  .verstak/              # App data — not user-facing
    vault.db
    backups/
    thumbnails/
    cache/
    sync/
    trash/
    history/

  Проекты/               # User-created workspace nodes
    Рабочие/
      Разработка серверной/
        Overview.md
        Documents/
        Notes/
        Files/
    Archive/

  Клиенты/
    ИТ-Вектор/
      Projects/
        LMS/
          Overview.md
          Documents/
          Contracts/
```

## Rules

1. **Every Node has a folder** — the folder name matches the node title (sanitized).
2. **Nesting reflects parent-child relationships** — if Node A is parent of Node B,
   B's folder is inside A's folder.
3. **Safe names** — folder names preserve Cyrillic, spaces, and readable characters.
   Illegal filename chars (`/\:*?"<>|`) are replaced. Control chars are removed.
4. **Uniqueness** — if a folder already exists, a numeric suffix is added:
   `Project`, `Project (2)`, `Project (3)`
5. **No UUIDs in user paths** — UUIDs are stored in the database and in `.verstak/`,
   never in the user-visible folder tree.
6. **Template default files** — templates may create default files like `Overview.md`
   inside the node folder.
7. **Archive/Delete** — archiving sets `archived = true` but doesn't move the folder.
   Deletion moves the folder to `.verstak/trash/`.

## `.verstak/` directory

Contains all application internal data:

- `vault.db` — SQLite database
- `backups/` — automatic vault backups
- `thumbnails/` — generated thumbnails
- `cache/` — temporary cache
- `sync/` — sync state and blobs
- `trash/` — moved here on deletion
- `history/` — file version history

## Migration

Existing vaults can be migrated with the `MigrateVaultLayout()` command,
which computes `fs_path` for every node based on the parent-child tree
and creates the corresponding folders on disk.