> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# History

> Local audit history for button creates, edits, installs, updates, and rollbacks.

`history.json` is the local audit log for a Buttons workspace.

It records two kinds of changes:

* command-driven changes, like `buttons create`, `buttons install`, `buttons update`, `buttons delete`, and rollback
* file-hook changes, like editing `button.json`, `main.sh`, `AGENT.md`, `drawer.json`, `buttons.json`, or `buttons-lock.json` directly

```text theme={null}
.buttons/
  buttons.json
  buttons-lock.json
  history.json
  buttons/
  drawers/
```

## Event shape

```json theme={null}
{
  "schema_version": 1,
  "events": [
    {
      "at": "2026-06-28T18:42:10Z",
      "action": "install",
      "target": "button:slack-sync",
      "source": "git+https://github.com/autonoco/autono-buttons@main",
      "from_version": null,
      "to_version": "1.2.4",
      "from_hash": null,
      "to_hash": "sha256:4f8c...",
      "status": "ok"
    }
  ]
}
```

## Actions

History should record:

| Action           | Cause                                                     |
| ---------------- | --------------------------------------------------------- |
| `create`         | A button or drawer is created.                            |
| `edit`           | A tracked button, drawer, manifest, or lock file changes. |
| `delete`         | A button or drawer is removed.                            |
| `install`        | A registry or source installs a button.                   |
| `update`         | An installed button resolves to a newer version/hash.     |
| `rollback`       | A button is restored to an earlier locked version.        |
| `resolve_failed` | Registry/source resolution fails.                         |

## File-hook tracking

Commands should write explicit history events when they mutate state. File hooks should catch manual edits and agent edits that happen outside a Buttons command.

The watcher should track:

```text theme={null}
.buttons/buttons.json
.buttons/buttons-lock.json
.buttons/buttons/*/button.json
.buttons/buttons/*/main.*
.buttons/buttons/*/AGENT.md
.buttons/drawers/*/drawer.json
```

The watcher should ignore runtime and secret-bearing files:

```text theme={null}
.buttons/history.json
.buttons/buttons/*/pressed/**
.buttons/drawers/*/pressed/**
.buttons/batteries.json
.buttons/webhook.json
.buttons/idempotency/**
.buttons/queues/**
```

For each file-hook event, Buttons can compute a before/after content hash and append one debounced `edit` event.

## Commit policy

Commit:

* `.buttons/buttons.json`
* `.buttons/buttons-lock.json`
* authored button and drawer files

Do not commit:

* `.buttons/history.json`
* pressed run history
* batteries or webhook config

The lock file gives the team shared reproducibility. `history.json` gives each machine local auditability.

## Related

* [Registry](/concepts/registry)
* [Hook triggers](/buttons/hook)
* [Folder structure](/concepts/folder-structure)