From 8c433143ac973a3a67be7a6adcdd64b5f19fa0ed Mon Sep 17 00:00:00 2001
From: Ty <tybala@outlook.com>
Date: Mon, 27 Jul 2026 16:07:29 +0000
Subject: [PATCH] docs: software updates lifecycle

---
 design/updates-lifecycle.md | 75 +++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 design/updates-lifecycle.md

diff --git a/design/updates-lifecycle.md b/design/updates-lifecycle.md
new file mode 100644
index 0000000..4a04812
--- /dev/null
+++ b/design/updates-lifecycle.md
@@ -0,0 +1,75 @@
+# 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.