@volter-ai-dev/supercode-ui 0.1.70 → 0.1.72

package/README.md

@@ -1,5 +1,12 @@
 # `@volter-ai-dev/supercode-ui`
 
+Repository reference: [UI inventory](../../docs/reference/ui.md) ·
+[feature inventory](../../docs/reference/features.md) ·
+[ideal Storybook first](../../docs/contributing/ui-development.md).
+These repository guides describe current coverage and proposed components; the API below
+describes this package. Workflow and orchestration currently have session-level provenance,
+but no dedicated board, job, run, or routing components.
+
 `supercode-ui` is the composable default interface for Supercode's glue workflows: inspect a
 native coding-agent session, continue it safely, switch harnesses, answer requests, hand it to a
 terminal, and export it back without hiding fidelity or residue.
@@ -9,6 +16,34 @@ The package does not inject iframes, open sockets, read native session files, pe
 or assume Lucarne. A host supplies bounded public state and receives typed intents. This lets a
 browser widget, editor panel, desktop app, or ordinary page share one capability-honest UI.
 
+## Compose a host layout with shared behavior
+
+`MessengerProvider` owns shared navigation and conversation state. Put
+`MessengerSessions` in a persistent sidebar and `MessengerContent` beside it; the
+content retains the complete messenger's actions, receipts, recovery, settings,
+and child-session inspector. `useMessenger()` exposes navigation to host controls.
+
+```jsx
+<MessengerProvider state={state} adapter={adapter} initialView="new">
+  <aside className="scui-root"><MessengerSessions /></aside>
+  <section className="scui-root">
+    <MessengerContent showBack={false} starter={{
+      variant: 'starter', environmentLabel: 'This workspace',
+      suggestions: ['Explain this workspace', 'Fix the failing test'],
+      initialDraft: storedNewDraft, onDraftChange: saveNewDraft,
+    }} />
+  </section>
+</MessengerProvider>
+```
+
+Import these from `/preact` or `/react` (or their `/messenger` subpath).
+The host supplies layout sizing. The optional centered starter uses the same
+harness readiness, attachments, execution modes, and submission logic as the
+complete messenger. Its persisted draft is separate from `state.savedDraft`,
+which belongs to the attached conversation. An asynchronous start must settle
+successfully before the starter clears its draft; merely becoming busy or
+allocating a new runtime is insufficient.
+
 ## Storybook is the component contract
 
 The package's complete development, documentation, and acceptance surface lives in Storybook:
@@ -23,7 +58,8 @@ Stories import the same built public artifacts that consumers install. They cove
 harness identity, loading phase, transcript primitive, native request, tool lifecycle, long plan,
 session inventory, composer/continuation state, receipt, narrow messenger layout, and modular
 override seam. Chromium interaction and axe accessibility tests run every story in both light and
-dark consumer themes. The static Storybook build is part of the repository SDK gate.
+dark consumer themes. The static build is available through `build:storybook`; see the
+[validation guide](../../docs/contributing/validation.md) for current automation.
 
 The older browser fixture remains a low-level embed smoke test; it is not a parallel design system.
 New component behavior and hard-to-reach states belong in Storybook first.
@@ -336,3 +372,27 @@ honest unavailable-preview state rather than a broken thumbnail or deceptive act
 An embedding product such as Vibewaiting should therefore be small: Lucarne owns its iframe and
 launcher lifecycle, Supercode owns this UI and the controller semantics, and Vibewaiting only
 bridges state/intents plus host-specific theme and persistence policy.
+
+## Native supervision (0.1.72)
+
+Independent workflow, job/run, configuration inventory and approval compositions
+are available from `./preact/supervision` and `./react/supervision`. Their bounded
+projections and native host adapters live in `./supervision`. These do not need
+a conversation controller. A host supplies source scopes and native SDK clients.
+
+`createSupervisionHost` binds job discovery, profile-scoped run history and
+confirmed pause, resume, run requests and deletion for Hermes, OpenClaw and the orchestrator. `createSourceInventoryHost`
+reads profiles, channels, routes, triggers, skills and memory; it does not turn
+instance-wide native readers into per-profile readers. `createApprovalHost`
+requires the existing native connection and session, re-reads a pending choice,
+and requires a matching decision receipt. Configuration inventories are read-only. `JobControls` requires explicit host capabilities and keeps run-request receipts distinct from completed runs.
+
+The public parts include `JobList`, `OrchestrationJobs`, `SourceInspector` and
+`ApprovalInbox`; see the source inventory and supervision parts stories. Native
+unknowns, discovery failures and delivery failures remain distinct states.
+
+Validation: package build, TypeScript checks and 49 headless tests pass, including
+colliding job IDs across orchestrator profiles and confirmation of a paused job.
+Workbench separately exercised these components in normal Chrome and native job
+creation/history/pause against a disposable orchestrator home. This does not claim
+full scheduling migration, write editors, or live permission round-trip coverage.