feat: ship agent-first mission control v0.2.57

2026-07-31 22:39:47 +02:00
parent 3bc7622977
commit f5552218bc
535 changed files with 95242 additions and 8791 deletions
@@ -0,0 +1,100 @@
+# 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.