nordz0r · Nov 11, 2026 · Nov 7, 2026
diff --git a/skills/ocx/.upstream-revision b/skills/ocx/.upstream-revision
@@ -1 +1 @@
-684ad75d254ae96a9971387d09ae428b96ada9c2
+36aa9e8f7933807dc2c873bb93051c7c9c00f4e6
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
@@ -30,8 +30,8 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | [accounts](01_surface_accounts.md) | 42 |
 | [agents-routing](01_surface_agents-routing.md) | 68 |
 | [integrations](01_surface_integrations.md) | 41 |
-| [observe-system](01_surface_observe-system.md) | 98 |
-| [access-remote](01_surface_access-remote.md) | 33 |
+| [observe-system](01_surface_observe-system.md) | 99 |
+| [access-remote](01_surface_access-remote.md) | 34 |
 | [lab](01_surface_lab.md) | 21 |
 
 ## Read-only capabilities
@@ -127,6 +127,10 @@ Original invocation order. These headings preserve links to the previous single-
 
 [State-changing task](01_surface_access-remote.md#ocx-connect-rotate)
 
+### `ocx update`
+
+[State-changing task](01_surface_observe-system.md#ocx-update)
+
 ### `ocx capabilities`
 
 [Read-oriented task](01_surface_lifecycle.md#ocx-capabilities)
@@ -1363,6 +1367,10 @@ Original invocation order. These headings preserve links to the previous single-
 
 [Read-oriented task](01_surface_observe-system.md#ocx-companion-timeline)
 
+### `ocx disconnect`
+
+[State-changing task](01_surface_access-remote.md#ocx-disconnect)
+
 ### `ocx hub disable`
 
 [State-changing task](01_surface_access-remote.md#ocx-hub-disable)
@@ -1517,6 +1525,6 @@ Original invocation order. These headings preserve links to the previous single-
 
 ## Counts
 
-- declared capabilities: 367
-- of those, state-changing: 225
+- declared capabilities: 369
+- of those, state-changing: 227
 - head-resolved invocations: 2
diff --git a/skills/ocx/references/01_surface_access-remote.md b/skills/ocx/references/01_surface_access-remote.md
@@ -8,7 +8,7 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 33.
+Declared capabilities: 34.
 
 ### `ocx link probe`
 
@@ -326,6 +326,26 @@ State-changing: yes. JSON mode: `payload`.
 - A bare invocation reads and never writes.
 - A setting flag changes the operator's config; run it only when the operator asks for that change.
 
+### `ocx disconnect`
+
+Usage: `ocx disconnect [--keep-catalog] [--json] | ocx disconnect --orphaned-token --yes [--json]`
+
+Disconnect a client or preserve orphaned token files for recovery.
+
+State-changing: yes. JSON mode: `payload`.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--keep-catalog` | boolean | Keep the connected client's catalog during ordinary disconnect. |
+| `--orphaned-token` | boolean | Preserve unowned service-token files in a private backup when disconnected. |
+| `--yes` | boolean | Explicitly confirm orphan-token recovery; requires --orphaned-token. |
+| `--json` | boolean | Emit the local result and backup location as JSON. |
+
+- Orphan recovery requires a disconnected durable state, no pending connect or disconnect, no Hub or admission-secret use, no installed or unverified service, and verified absence of a client runtime. It preserves rather than deletes token files and does not establish their ownership.
+- If refused, inspect the bind, API keys, token environment and service status; manage a Hub secret through its service. Stop OpenCodex and move saved files back only when their original names are absent. Never print their contents.
+
 ### `ocx hub disable`
 
 Usage: `ocx hub disable [--revoke-clients --client-key <id> ...] [--json]`

diff --git a/skills/ocx/references/01_surface_lifecycle.md b/skills/ocx/references/01_surface_lifecycle.md
@@ -77,32 +77,38 @@ Drives no management route.
 | Flag | Value | Meaning |
 |---|---|---|
 | `--json` | boolean | Emit the full capability table as JSON. |
+| `--contracts` | boolean | List supported versioned contracts. |
 | `--mutating-only` | boolean | Restrict output to capabilities that mutate state. |
 | `--route` | string | Show which capabilities drive a management route. |
 
 - Start here when driving ocx programmatically: it is the declared surface index, not a complete verb list.
 
 ### `ocx sync`
 
-Usage: `ocx sync [--expect-link <linkId> | --expect-hub-key <apiKeyId>] [--restart-codex] [--restart-app-server-only]`
+Usage: `ocx sync [--expect-link <linkId> | --expect-hub-key <apiKeyId>] [--local-only] [--json] [--restart-codex] [--restart-app-server-only]`
 
 Synchronize client catalogs, including Aside profiles through the running server's mutation owner.
 
-State-changing: yes. JSON mode: `none`.
+State-changing: yes. JSON mode: `payload`.
 
 | Method | Route |
 |---|---|
 | POST | `/api/client-integrations/aside/sync` |
 
 | Flag | Value | Meaning |
 |---|---|---|
+| `--local-only` | boolean | Do not fan out the Home sync to linked Children. |
+| `--json` | boolean | Emit the sync fan-out result as JSON. |
 | `--restart-codex` | boolean | Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog, cache, or changed configuration write, on macOS, Linux and Windows. |
 | `--restart-app-server-only` | boolean | Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given. |
 | `--restart-desktop-app` | boolean | Deprecated alias of --restart-codex. |
 | `--expect-link` | string | Sync only when this machine is a connected Remote Link Child of this link id; otherwise exit 5 with nothing changed. |
 | `--expect-hub-key` | string | Sync only when this machine is a hub client connected with this API key id; otherwise exit 5 with nothing changed. |
 
 - The Aside refresh uses the live server; other catalog synchronization also performs local work.
+- An update in flight or an unavailable update/sync mutex refuses without changes: update-in-flight, exit 7. Another sync reports sync-in-progress, exit 1.
+- A current Home catalog fans out to linked Children. Fan-out never requests a Codex app or app-server restart on a Child; use GOAT or ocx sync --restart-codex there. Applying changed Home settings may restart the Child's own OpenCodex client runtime.
+- After a successful Home sync, a connected Child skipped during fan-out, a failed or timed-out Child, or an unreadable link store yields partial exit 6. Skipped connected Children include an actionable hint; update an outdated ocx through its owning installer, with the Desktop tray as an option for Desktop installs. Intentional skips, including client-initiated links and --local-only, keep their existing exit behavior.
 - --expect-link/--expect-hub-key are checked under the lock that selects the sync path. A mismatch writes nothing, never falls back to local providers, exits 5, and ends stderr with {"phase":"child_link_mismatch"|"hub_client_mismatch","reason":...}; reasons are disconnected, invalid_state, disconnect_pending, pending_operation, hub_client, link_client, other_link and other_key. Usage errors exit 2.
 
 ### `ocx stop`

diff --git a/skills/ocx/references/01_surface_observe-system.md b/skills/ocx/references/01_surface_observe-system.md
@@ -8,7 +8,27 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 98.
+Declared capabilities: 99.
+
+### `ocx update`
+
+Plan or apply an OpenCodex update.
+
+State-changing: yes. JSON mode: `envelope`.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--plan` | boolean | Preview an orchestrated update with --json. |
+| `--yes` | boolean | Apply an orchestrated update with --json. |
+| `--json` | boolean | Emit a versioned plan or result. |
+| `--tag` | string | Select latest or preview for the legacy update or plan. |
+| `--version` | string | Select an exact version for a plan or apply. |
+| `--expect-plan` | string | Require the apply plan to match this planToken. |
+| `--not-after` | string | Refuse mutation after this Unix millisecond deadline. |
+
+- Orchestrated exit codes: 0 verified or up-to-date; 10 refused; 11 previous version verified; 12 uncertain; 64 usage.
 
 ### `ocx companion`
 
@@ -417,7 +437,8 @@ Drives no management route.
 | `--request-id` | string | Optional stable retry key. |
 | `--json` | boolean | Emit the public job status. |
 
-- Local counterpart of POST /api/codex/cli-update/apply: invokes the same durable job owner with --yes confirmation; HTTP admission separately requires a trusted loopback GUI session.
+- Local counterpart of POST /api/codex/cli-update/apply: invokes the same durable job owner with --yes confirmation; HTTP admission separately requires a current paired dashboard session on trusted loopback ingress, matching origin, CSRF and confirmed: true.
+- Standalone HTTP pairing requires the configured literal 127.0.0.1 or ::1 origin; localhost aliases, wildcard binds and connected-client roles use the local CLI --yes path instead.
 - Admission is stored under the protected current-user config root before the installer can run.
 - Exit 0 requires an applied job; refused, not_applied, ambiguous and pending duplicate jobs exit 1, including with --json.
 - Only POSIX npm-global managed installs are currently supported; Windows, shims and other managers remain refused.

diff --git a/skills/ocx/references/01_surface_providers-models.md b/skills/ocx/references/01_surface_providers-models.md
@@ -385,7 +385,7 @@ Drives no management route.
 
 Usage: `ocx models list [--provider <name>] [--json]`
 
-List static configured models locally.
+List local configured and router-known models.
 
 State-changing: no. JSON mode: `envelope`.
 
@@ -394,9 +394,9 @@ Drives no management route.
 | Flag | Value | Meaning |
 |---|---|---|
 | `--provider` | string | Limit to a configured provider. |
-| `--json` | boolean | Emit models and the static-catalog note. |
+| `--json` | boolean | Emit models and the local-catalog note. |
 
-- A bare models invocation is equivalent. Reads local config, never the live catalog; use models live for runtime discovery.
+- A bare models invocation is equivalent. Includes saved IDs, registry seeds, custom models and this process's discovery cache; use models live for the running catalog.
 
 ### `ocx models add`
 

diff --git a/skills/ocx/references/04_failure_semantics.md b/skills/ocx/references/04_failure_semantics.md
@@ -14,6 +14,8 @@ exit contract. Its common mappings and the main exceptions are:
 | 64 | usage validation in `capabilities`, `ready`, `resolve` | fix arguments; no discovery/request for invalid input |
 | 4 | HTTP 404 — the named account, provider, key, or route does not exist | no |
 | 5 | HTTP 409 — conflict; a lock is held or state moved under you | inspect first; stale baselines require review |
+| 6 | `ocx sync` completed the Home step but a Child failed or timed out, or the link store was unreadable | inspect the fan-out result |
+| 7 | reserved for an update in flight during sync | wait for the update, then retry |
 | 1 | everything else: transport failure, 5xx, unexpected errors | depends on `reason` |
 
 Two consequences worth internalizing:

diff --git a/skills/ocx/references/05_remote_hub.md b/skills/ocx/references/05_remote_hub.md
@@ -321,6 +321,12 @@ To sync only while that reading still holds, pass what you read back to sync:
 relinked in between, the sync changes nothing and exits 5 with a JSON `phase` line on stderr
 ([04_failure_semantics.md](04_failure_semantics.md#a-pinned-sync-that-refuses-exit-5)).
 
+On the Home, `ocx sync` fans out only after it commits a current catalog. Use `--local-only`
+to suppress propagation and `--json` to inspect Home and Child results. Fan-out never asks a Child
+to restart a Codex app or app-server; use GOAT or `ocx sync --restart-codex` on that Child. Its
+pinned sync can still restart its own OpenCodex client runtime after applying changed Home settings.
+A Child sync already running can continue after the Home times out its local SSH process.
+
 ## Key rotation is a two-step commit
 
 Starting a rotation issues the new key while **the old key stays valid**. The dashboard
@@ -364,6 +370,16 @@ It ends a browser session; it does not disconnect a client or revoke a key.
 
 ### When `disconnect` refuses, that is the safety property
 
+When the operator has explicitly authorized recovery of a disconnected installation with a
+leftover token, `ocx disconnect --orphaned-token --yes` preserves the service-token files in a
+private backup. It refuses pending or connected client state, a Hub, admission-token use,
+installed or unverified service definitions, and live or unverified client runtimes. Inspect the
+bind, API keys, token environment and `ocx service status`; manage a Hub credential through the
+Hub service. It does not prove the tokens belonged to a link or restore lost connection settings.
+Report the printed backup location; to restore, stop OpenCodex and move the saved files back only
+if their original names are absent. Never read or print their contents. Do not add `--yes` without
+the operator's explicit authorization.
+
 Do not work around these. Each one means unwinding would damage state that
 `disconnect` cannot prove is safe to touch.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		684ad75d254ae96a9971387d09ae428b96ada9c2
		36aa9e8f7933807dc2c873bb93051c7c9c00f4e6