claire/INFRA.md

# Claire — infrastructure

## Storage

Each developer machine has its own SQLite DB:

```
~/.local/share/claire/claire.db     · WAL-mode SQLite, single-writer
~/.config/claire/claire.toml        · machine_id, groups, (future) peer list
```

`machine_id` is a uuid4 generated on first `claire init` and persisted in `claire.toml`. It's stamped onto every event Claire emits and never changes — even if the user's hostname or username changes, the machine identity is stable.

## Hosts (Push A)

Claire runs locally on each developer machine. There is no central state host in Push A. The DB is single-writer per machine; the `events` table is the substrate for the future Push B sync layer.

## Hosts (Push B, planned)

`claire.toml.peers` becomes active — each Claire instance pulls events from the others. The protocol is:

```
GET  http://<peer>:8765/api/sync/events?since=<hlc>   → batch of events newer than <hlc>
POST http://<peer>:8765/api/sync/events               → push local events (idempotent)
```

No central coordinator; every peer is a peer. The default port `8765` matches the `claire web` default (the sync endpoints are routes on the same FastAPI app).

## rclaude dependency

Claire requires `rclaude` to be on `$PATH`. Install:

```sh
git clone http://forge.black.lan/lilith/session-tools.git ~/Code/@scripts/session-tools
~/Code/@scripts/session-tools/install.sh
```

Claire verifies `rclaude --version` succeeds at startup and errors with a clear message if not.

## Logging

Structured JSON to stderr via stdlib `logging`. Level controlled by `CLAIRE_LOG_LEVEL` (default `INFO`). No log file in Push A — `journalctl --user` or stdout redirect is the answer if a user wants persistence.