# Logs

Logs record every mutation that happens in SUNWÆE — every create, update, delete, and list command writes an entry automatically. You don't interact with logs directly; they accumulate in the background and let you audit what happened and when.

## Storage

Logs are append-only JSON Lines files, organised by date:

```
~/sunwaee/workspaces/
└── personal/
    └── logs/
        └── 2026/
            └── 03/
                └── 10/
                    └── logs.jsonl    ← one JSON object per line
```

Each entry has a unique `id` (UUID), a timestamp, the caller (`human`, `api`, or `sun`), the workspace, module, operation, and optionally the affected item's id and title.

## Commands

### `logs list`

List log entries. Defaults to today's logs across all workspaces.

```
sunwaee logs list
sunwaee logs list --workspace personal
sunwaee logs list --date 2026-03-10
sunwaee logs list --month 2026-03
sunwaee logs list --all
sunwaee logs list --module notes
sunwaee logs list --operation create
sunwaee logs list --caller sun
sunwaee logs list --query "meeting notes"
sunwaee logs list --limit 20
```

Only one of `--date`, `--month`, or `--all` can be used at a time. Results are sorted newest first.

### `logs read <id>`

Show the full detail of a single log entry, including any stored `args`. Accepts a full id or any unambiguous prefix.

```
sunwaee logs read a1b2c3d4
sunwaee logs read a1b2c3d4-ef56-...
```

## Log entry fields

| Field        | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `id`         | Unique UUID for this entry                                 |
| `timestamp`  | ISO 8601 UTC timestamp                                     |
| `caller`     | Who triggered it: `human`, `api`, or `sun`                 |
| `workspace`  | Workspace the action occurred in                           |
| `module`     | Module: `notes`, `tasks`, `workspaces`, `projects`, `logs` |
| `operation`  | Action: `create`, `update`, `delete`, `list`, …            |
| `ok`         | Whether the operation succeeded                            |
| `item_id`    | Id of the affected item (when applicable)                  |
| `item_title` | Title of the affected item (when applicable)               |
| `args`       | Extra context stored by list/search operations             |
