nexus/docs/audits/2026-07-30/openclaw-attach-adopt/STRUCTURAL_PROOF_PREFLIGHT.md

OpenClaw Attach & Adopt — structural proof preflight

Product surface and direction

• Surface: operational product UI.
• Visual authority: the existing authenticated Nexus dashboard and docs/NEXUS_DESIGN_SYSTEM.md.
• Concept sentence: Nexus exposes one calm, evidence-bound operator path from discovering an OpenClaw Gateway to inspecting it read-only and deliberately enabling management.
• Entry mode: task-first.
• Product-surface restraint: setup, conflict, failure, and destructive states use plain glass surfaces and semantic status color; the blue-violet gradient remains reserved for the active step and primary action.
• Imagery: not applicable. Diagrams, photographs, or generated media would not improve this trust-sensitive operational task.

Bounded first journeys

Gateway setup

1. Entry: owner opens Settings and sees the current setup state.
2. Primary action: discover bounded candidates or enter an explicit endpoint.
3. Proof: probe shows endpoint, transport trust, version, protocol, and capability status without changing OpenClaw.
4. Commit: attach requests read-only pairing; adopt stores only the connection profile and inventory fingerprint.
5. Recovery: failed probe, pairing-required, incompatible client identity, version mismatch, and disconnect each keep a local recovery action.
6. Privilege change: management scope elevation is a separate owner action.

Agent configuration

1. Entry: select a live file returned by OpenClaw.
2. Primary action: edit an allowed bootstrap file.
3. Proof: visible saved hash and current file metadata.
4. Conflict: a stale expected hash blocks the write and offers reload.
5. Success: Nexus reports only verified read-back, not unproven hot reload.
6. Custom workspace documents remain visibly read-only.

Cron management

1. Entry: inspect a real OpenClaw job and its current resource hash.
2. Primary action: create, edit, enable/disable, run, or delete.
3. Proof: mutations show queued/committed state and refreshed Gateway data.
4. Recovery: hash conflict reloads the current job; failed or uncertain operations never claim success.
5. High-risk command/on-exit payloads stay unavailable unless local policy is explicitly enabled.

Section grammar

Surface section	Role	Narrow transformation	State responsibility
Setup progress	Orient	Horizontal steps become a concise ordered list	Current step, completed steps, blocked reason
Candidate/probe panel	Act	Controls stack in semantic order	Idle, loading, empty, invalid, probe failure
Trust evidence	Prove	Definition list remains in source order	Endpoint, TLS pin, version, protocol, scopes
Inventory	Prove	Counts become a two-column grid	Fresh, stale, partial, unavailable
Management gate	Act	Confirmation follows consequences	Read-only, pairing, enabled, forbidden
Agent file navigation	Orient/Act	Wrapping tabs with current-file context	Loading, missing, readonly, dirty
Agent editor	Act/Recover	Header actions stack above editor	Saving, verified, conflict, error
Cron job list/detail	Compare/Act	List precedes selected detail	Loading, empty, disabled, stale, error
Mutation dialogs	Act/Recover	One-column consequence-first layout	Pending, failed, committed, focus return

State and copy truth table

State	Visible fact	Allowed action	Forbidden claim	Recovery/focus
Unconfigured	No active OpenClaw profile	Discover, enter endpoint	Connected/imported	Candidate action
Probing	Endpoint is being inspected read-only	Cancel/await	Paired/adopted	Probe status
Client identity blocked	OpenClaw lacks an approved Nexus identity	Review requirement	Gateway failure or bad secret	Compatibility explanation
Pairing required	Exact current request ID	Verify after external approval	Approved/connected	Verify button
Inspectable	Read-only inventory is current	Adopt	Management enabled	Adopt button
Adopted read-only	OpenClaw is authoritative; writes blocked	Request management	Editable	Management action
Scope upgrade pending	Wider scopes require approval	Verify	Admin granted	Pairing request
Management enabled	Local gate and Gateway scopes both allow mutation	Supported mutations	Universal admin capability	Relevant first action
Stale agent file	Current Gateway hash differs	Reload	Saved/overwritten	Reload file
Cron run queued	OpenClaw returned a run ID	Open Run Control	Executed successfully	Run detail
Mutation uncertain	Terminal outcome is not known	Refresh/investigate	Retried or successful	Recovery action

Responsive and accessibility proof targets

• Required widths: 375, 768, 1024, 1440, and 1920 CSS pixels.
• First actions and dialog actions remain fully visible with the authenticated 62px topbar and overlay sidebar contract.
• All dialogs use semantic controls, initial focus, Escape, focus containment, and focus restoration.
• Status changes use role=status or aria-live; failures use role=alert.
• No trust-bearing endpoint, fingerprint, job ID, run ID, or hash is truncated without a full accessible value.
• Long Gateway errors, IDs, German labels, and delivery destinations wrap without document-level horizontal overflow.

Proof boundary

Automated tests and a controlled mock can establish contract and UI behavior. Only a separately authorized read-only live check against Bao's Gateway can establish inventory parity. Live mutation, pairing approval, OpenClaw patching, deployment, and any access to Maxi-owned resources are outside this implementation checkpoint.