# Grix Update Contract

This document defines the minimal execution contract for `grix-update`, ensuring consistency when integrating with scheduled tasks, heartbeat reminders, or other maintenance flows.

## Goal

`grix-update` only does these 5 things:

1. Confirm whether the plugin exists
2. Confirm whether the current installation method supports automatic updates
3. Check whether a new version is available
4. Execute the upgrade when needed
5. Complete validation, restart, and result notification after upgrade

## Command Ladder

Use these official commands in order:

```bash
openclaw plugins info grix --json
openclaw plugins update grix --dry-run
openclaw plugins update grix
openclaw plugins doctor
openclaw gateway restart
openclaw health
```

Rules:

1. Run `info` first, then `dry-run`; do not skip steps.
2. If `dry-run` does not show an available update, do not execute the actual upgrade.
3. After the actual upgrade, do not skip `doctor`.
4. When restart is allowed, `doctor` must be followed by `gateway restart` and `health`.

## Mode Definitions

### `check-only`

Purpose: Only check, do not upgrade.

Convergence:

1. No new version: `no_update`
2. New version available: `update_available`
3. Plugin does not exist or installation method not supported: `failed` / `unsupported`

### `apply-update`

Purpose: Execute the upgrade directly.

Convergence:

1. Upgrade and acceptance successful: `updated`
2. Any step fails: `failed`

### `check-and-apply`

Purpose: Default mode for automation.

Convergence:

1. No new version: `no_update`
2. New version available and upgrade successful: `updated`
3. Any step fails: `failed`
4. Installation method not supported: `unsupported`

## Return Value Semantics

The results should be understood as these business states:

1. `no_update`
   - Checked, no upgradable version available
2. `update_available`
   - Checked, found an upgradable version, but did not execute the upgrade this time
3. `updated`
   - Upgrade completed, and post-upgrade checks passed
4. `failed`
   - Failed at some step during check, upgrade, restart, or acceptance
5. `unsupported`
   - Current installation method does not support automatic updates

## Failure Point Naming

When failed, the failure point should be fixed to these steps:

1. `plugins_info`
2. `plugins_update_dry_run`
3. `plugins_update`
4. `plugins_doctor`
5. `gateway_restart`
6. `health`

This makes it easier to do statistics and alerting when integrating with automation later.

## Notification Contract

`notify_on` only allows these 3 values:

1. `never`
2. `failure`
3. `always`

Default: `failure`

Supplementary notes:

1. `main_agent` is primarily used to select which local agent is responsible for executing maintenance tasks, e.g., `--agent <main_agent>` in cron.
2. `main_agent` itself is not a directly deliverable Grix message target; if there is no explicit notification session, just return the result and let the upper-level task or cron records handle notification.
3. Cron defaults to `notify_on=never`; do not guess an additional notification path inside the skill.

Recommended notification copy should be kept to one sentence:

1. Success: `Grix plugin upgrade completed, current checks are normal.`
2. No update: `Grix plugin checked, no new version available.`
3. Failure: `Grix plugin auto-update failed, stuck at <step>.`
4. Not supported: `Grix is not installed in an auto-updatable way; switch to npm install before enabling auto-update.`

## Automation Recommendations

Recommended for scheduled tasks to use directly:

```json
{
  "mode": "check-and-apply",
  "plugin_id": "grix",
  "notify_on": "never",
  "main_agent": "main",
  "allow_restart": true
}
```

Recommended frequency:

1. Once per day
2. Or once every 6 hours

Default behavior:

1. No update: silently end
2. Update successful: silently end
3. Update failed: retain the failure result in cron run records for the maintainer or upper-level task to handle uniformly

## Prohibited Actions

1. Do not trigger upgrades during egg install private chats
2. Do not directly modify the plugin directory
3. Do not manually overwrite npm package files
4. Do not write bypass logic to accommodate old installation methods
5. Do not perform consecutive retries after a single failure