# 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.