# Where files live

Everything gezel knows lives in one folder — the **gezel home** — as plain files. On macOS and Linux that's `~/.gezel` in your home directory (a machine-wide service uses a system location instead; Settings shows the active path).

```
~/.gezel/
  config.json         provider choice, default model, the current Meester
                      (API keys go to your system keychain, not here)
  gezels/
    {gezel}/
      gezel.md        name, role, model choice
      about.md        that crew member's character
      poppetje.json   the carved-figure look
      sessions/       chat threads, one file each
      memories/       daily notes + lessons
  projects/
    {project}/
      project.json    name, working folder, crew settings
      documents/      About + Mission Objectives
      index/          the project's search index: summaries, descriptions,
                      reviews (rebuildable; kept here, not in your folder)
      artifacts/      everything Gezel produces
        shadow/       machine-made markdown twins of workspace documents,
                      pictures, and recordings (rebuilt automatically —
                      safe to delete, not a place to put your own files)
  documents/          the shared library
  memories/           what Gezel has learned about you ("About you"),
                      shared by the whole crew
  ambient/            ambient dashboard images (dated PNGs + latest.png),
                      made to be shown as wallpaper or lock screen
  integrations/
    office/           Word/Excel/PowerPoint: the add-in manifests, and the
                      certificate the Office pane is served with (its private
                      keys stay here, readable only by you)
    libreoffice/      the LibreOffice extension's connection token
    vscode/, codex/…  the other Integrations setups
  history.jsonl       the audit log
  logs/               service logs (rolling)
```

## Folders you add

A folder you add to gezel — Pictures, Documents, a code repository — stays where it is. Gezel reads it in place and writes nothing into it: the search index, photo descriptions and summaries for that folder live under `projects/{project}/` in the gezel home. A file in your folder changes only when you apply a change you approved. Earlier versions kept the index in a hidden `.gezel` folder inside yours; gezel moves it out the first time it starts.

## What you can safely do

- **Read anything.** It's your data; nothing breaks by looking.
- **Back up or sync the whole folder.** Copying the folder copies everything Gezel keeps.
- **Edit with care.** Character files (`about.md`) and documents are meant to be edited — from the app or any text editor. For structured files (`config.json`, thread files), prefer the app so nothing gets malformed.

A few subfolders are machinery rather than your data — `runtime/`, `service/`, `bin/`, `index/`, `logs/` hold the service's own working state and rebuildable caches. Leave those to gezel; deleting them is at worst an inconvenience, never data loss. The `ambient/` folder is regenerated too — point your wallpaper or lock-screen slideshow at it freely, but don't store your own images there.
