# Software updates and lifecycle

## Owner transparency

Updates are an **operator** concern. The salon owner does **not** participate in or see software updates under normal operation.

## When

| Trigger | Default |
|---------|---------|
| Scheduled host job (`upgrade.sh`) | **ON by default** at install |
| Manual `./scripts/upgrade.sh` | Always available to operator |
| Owner chat | Does **not** drive platform upgrades |

## How

Host `upgrade.sh` is the parent orchestrator:

1. Snapshot via `nemohermes <name> snapshot create` when available  
2. Record release pins; optional volume backup  
3. Fetch product release (git tag / image digests)  
4. Non-interactive only — no Hermes interactive update/setup wizards  
5. Compose pull/build/recreate **preserving volumes**  
6. Run migrations if state schema changed  
7. Re-apply policy via `openshell` / `nemohermes policy-*`  
8. Re-assert inference/aux via `nemohermes inference set` / config set from `.env`  
9. Gateway restart if required by platform matrix  
10. Doctor; write **operator-only** upgrade journal  

## Suppress Hermes interactive update

| Risk | Mitigation |
|------|------------|
| Interactive `hermes update` | Never invoked; versions pinned by product release |
| Startup config wizards | Config pre-written; non-interactive entrypoint |
| Agent-triggered host upgrade | No tools for that; no docker.sock for owner agent |
| Concurrent sealed config writes | Serialize; honor shields/busy; retry |

## Update content vectors

| # | Vector | Upgrade action |
|---|--------|----------------|
| 1 | This product git repo | Fetch/checkout release tag |
| 2 | Host scripts | Replace from release |
| 3 | Docs | Replace |
| 4 | Compose files | Replace + recreate |
| 5 | Product images (if published) | Pull digests |
| 6 | NemoClaw CLI pin | Host install to pin |
| 7 | OpenShell CLI/gateway pin | Host/bootstrap |
| 8 | Sandbox / Hermes agent image | Rebuild/recreate as required |
| 9–10 | Hermes runtime + NemoClaw integration | With image |
| 11 | Lumina skills | Sync into sandbox |
| 12 | Default identity templates | Merge; never clobber owner name/profile |
| 13–14 | Owner memory / Hermes session state | Persist + migrate |
| 15 | Managed config.yaml / placeholders | Regenerate via sealed host commands |
| 16 | OpenShell provider secrets | Persist |
| 17–18 | Policy base/overlays/presets | Merge + apply |
| 19 | Square remote MCP registration | Re-assert + health |
| 20 | QBO local MCP package pin | Upgrade process + restart |
| 21 | Vagaro webhook service | Replace |
| 22–23 | Channels + allowlists | Rebuild if matrix requires; persist allowlists |
| 24–25 | Inference main + aux slots | inference set / config from `.env` |
| 26 | Dashboard/API forwards | Re-bind |
| 27 | Fixtures | Replace; not live connections |
| 28 | Migrations | Run by version |
| 29 | Auto-update timer unit | Enabled by default |
| 30 | Host Docker Engine | Separate documented path |

## Instrumentation

Operator-only events under `state/upgrade/`: `upgrade.started|step|migration|policy|service|doctor|finished|failed`.

## Rollback

Previous pins + volumes; `upgrade.sh --rollback`; doctor.