# File locations Four roots hold everything: the config repo, the state directory, shared data, and a few places elsewhere on the machine. One module resolves all of them, so nothing else in the tool reads `HOME` or the XDG variables. ## The config repo Everything here is committed. The repo is an ordinary git repository, and `niwa init` runs `git init` in it. ```tree label: ~/.config/niwa init.luau — the entry point: requires each module, then calls niwa.host() .luaurc — strict mode, and the @niwa and @self aliases niwa.lock — the resolved versions, committed on purpose modules/cli.luau modules/apps.luau modules/shell.luau modules/dev.luau modules/desktop.luau modules/system.luau modules/services.luau modules/inbox.luau — where an ambiguous proposal lands, permanently hosts/.luau — this machine only, loaded last files/ — sources for niwa.file and niwa.link, named @self/files/… secrets/.age — one sealed secret per file secrets/seal-key.age — the passphrase-protected key escrow state/.toml — one stamp per machine, written after every apply ``` The secrets are committed because they are ciphertext. The key that opens them is not in the repo: it lives in the state directory, and `niwa seal-key backup` escrows a passphrase-protected copy at `secrets/seal-key.age`. `state/` is the only directory niwa writes into the repo by itself. Stamps dirty the tree after every apply by design, so the dirtiness check that guards `apply --yes` excludes them. ## The state directory None of this is committed, and none of it crosses to another machine. ```tree label: ~/.local/state/niwa journal.json — acknowledgements, the apply entries, and the declined list archive// — displaced bytes, one file per distinct content apply.lock — the exclusive lock: one apply at a time seal.key — this machine's sealing key machine-id — the fallback identifier, when the hardware will not give one tags — this machine's tags, written by niwa tag baseline.json — the drift baseline the watcher's survey learns from digest.json — the weekly upstream digest cache/ — prefetched release downloads run.log — the full output of the commands niwa runs ``` The journal stays local because the archives beside it hold your bytes. Archives are pruned past ninety days. `niwa uninstall` leaves this directory alone unless you add `--purge`. Every verb that writes takes `apply.lock`: `apply`, `undo`, `pull`, `add`, `update` and `uninstall`. A plain `check` takes it when it can, so it cannot save a snapshot over a running apply. `plan` never takes it, and neither does the watcher's `check --notify`, so a survey can never block an apply. ## Shared data ```tree label: ~/.local/share niwa/types/init.luau — the type definitions your editor reads niwa/modules// — shared modules resolved by niwa.use mise/installs/ — where mise puts the toolchains you declare ``` `niwa init` writes the types and `niwa uninstall` removes them. A shared module is stored under the hash the lockfile pins, so two machines resolving the same `niwa.use` line read the same bytes. ## Elsewhere on the machine | Path | What is there | | --- | --- | | `~/.local/bin/niwa` | the binary, where the installer puts it | | `$ZDOTDIR/.zshrc`, or `~/.zshrc` | one PATH line, carrying the comment that lets `uninstall` remove exactly it | | `~/Library/LaunchAgents/rs.niwa.watcher.plist` | the watcher's launchd job | | `~/Library/LaunchAgents/