dsh-bailinghub 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 - 2026-09-01
+
+- Add `/bailinghub doctor` for credential-safe host-contract, configuration, SDK, authorization,
+  and workspace diagnostics before a business turn starts.
+- Add real lifecycle coverage for DeepSeek Harness `0.1.1-rc.2` and enforce it in Ubuntu,
+  Windows, and tagged publication workflows.
+- Make `connectionName` a user-controlled local selector while the business authorization page
+  owns login, account switching, tenant selection, and the trusted identity result.
+- Reconcile same-binding connections by trusted `on_behalf_of`: replace an older same-identity
+  connection, keep different identities independent, and surface cleanup-required authorization
+  as a successful login with an explicit no-reauthorize warning.
+- Preserve an existing alias and Session when same-alias authorization returns a different trusted
+  identity; allocate and select a non-conflicting local alias for the new identity.
+- Add user-only `/bailinghub connections list|add|use|remove` lifecycle commands with quoted-name
+  parsing, new-session-only selection, existing-session pinning, and revoke-before-remove safety.
+- Restore the SDK registry's current connection before the first new session or user command after
+  restart, with validated public metadata and a non-blocking bootstrap-field fallback.
+- Reconcile defaults after connection removal: adopt a remaining current profile, become
+  unconfigured after the last removal, and preserve successful removal across registry refresh
+  failures without disturbing a valid non-current default.
+- Pin the stable public `bailinghub-mcp-server@0.3.0` SDK, including Windows CurrentUser DPAPI
+  credential storage for Agent Session connections.
+
 ## 0.2.0 - 2026-08-26
 
 - Add the native Cordis Agent Client adapter that keeps reasoning and orchestration in local DSH

package/PRIVACY.md

@@ -10,14 +10,19 @@ using personal, confidential, or regulated data.
 Do not include tokens, private URLs, personal information, or production payloads in public
 issues, screenshots, or compatibility reports.
 
-## Native Agent Client 0.2.0
+## Native Agent Client 0.3.0
 
-The native 0.2.0 plugin sends each direct human user turn to BailingHub Core and receives
+The native 0.3.0 plugin sends each direct human user turn to BailingHub Core and receives
 model-visible instructions, memory, reference-only knowledge, governance, and active tool schemas.
 Business tool arguments and governed results cross the same boundary. At completion it sends only
 the hash-aliased assistant message id, visible final text, legal status, optional model/runtime
 labels, and numeric public usage. It ignores `assistant/chunk` and never uploads hidden reasoning.
 
 Browser authorization, refresh, and credential storage remain SDK-owned; this adapter stores no
-BailingHub credential. Review DSH, model-provider, BailingHub, and business-system retention
-boundaries before enabling the plugin.
+BailingHub credential. The SDK uses macOS Keychain, Windows CurrentUser DPAPI, or an explicitly
+enabled isolated mode-0600 POSIX file store. Review DSH, model-provider, BailingHub, and
+business-system retention boundaries before enabling the plugin.
+
+The multi-connection registry contains public connection name, Hub URL, client app id, workspace,
+timestamps, and current-selection state. It does not contain access tokens, refresh tokens, model
+keys, business cookies, prompts, tool arguments, or business results.

package/README.md

@@ -2,17 +2,32 @@
 
 [简体中文](docs/README.zh-CN.md) | English
 
-Use a local DeepSeek Harness Agent to discover and invoke business capabilities governed by a
-self-hosted BailingHub. Reasoning and tool orchestration stay in DSH; BailingHub retains trusted
-identity, runtime context, capability trimming, approval, invocation recovery, and audit.
+Use your local DeepSeek Harness Agent to operate the admin side of an online store, SaaS product,
+or other business system through BailingHub. Ask it to look up data, update records, or run other
+actions available to the connected account. The existing business identity, permissions, and
+approval rules still apply, and BailingHub keeps the authorization and action trail.
+
+For example, depending on what the connected business system has exposed, you can ask the local
+Agent to:
+
+- find an order, customer, product, or employee record;
+- update an allowed field or business status;
+- run another permitted admin action;
+- return the result while BailingHub records the corresponding tool steps.
+
+Reasoning and tool orchestration stay in DSH. BailingHub supplies the authorized business context,
+available capabilities, approval state, invocation recovery, and audit records required for the
+local Agent to act safely.
 
 This is an independent community integration. It is not developed, certified, endorsed, or
 recommended by DeepSeek.
 
-> **Current stable line:** `dsh-bailinghub@0.2.0` uses the native Agent Client flow documented
+> **Current stable line:** `dsh-bailinghub@0.3.0` uses the native Agent Client flow documented
 > below. Public `0.1.1` remains available only as the explicit static MCP compatibility path.
 
-## How the 0.2 Agent Client fits together
+For the shortest end-user path, follow the [three-minute getting started guide](docs/GETTING_STARTED.md).
+
+## How the 0.3 Agent Client fits together
 
 ```text
 DeepSeek Harness local Agent
@@ -27,7 +42,7 @@ The packages have separate responsibilities:
 - **BailingHub Core** owns Agent Auth, trusted business identity, runtime context, knowledge and
   memory projection, capability governance, approvals, invocation state, and audit records.
 - **`bailinghub-mcp-server/sdk`** owns browser login, PKCE, credential storage, refresh,
-  Hub/client/workspace connection isolation, and HTTP DTO mapping.
+  Hub/client/workspace connection selection, and HTTP DTO mapping.
 - **`dsh-bailinghub`** owns only DSH session, prompt, command, and dynamic-tool lifecycle
   integration. It does not store credentials or call a business API directly.
 
@@ -43,27 +58,29 @@ The deployer and business integrator must prepare these public identifiers in Ba
 2. A public Agent Client application id (`clientAppId`).
 3. At least one authorized workspace. In Agent Client v1, the workspace id is the BailingHub
    route id.
-4. A business authorization page and governed ACC/Tool Provider integration behind that route.
+4. One stable, account- and tenant-neutral business authorization entry configured on the Hub
+   Client App, plus a governed ACC/Tool Provider integration behind that route. The business page
+   must handle sign-in, account switching, and tenant selection before it approves the request.
 
 The end user does **not** enter a business API URL, business login credential, Tool Provider
 signing secret, BailingHub Client Token, or model-provider key into this plugin.
 
-## Install the 0.2 line
+## Install the 0.3 line
 
 Prerequisites:
 
 - Node.js `22.19.0+` or `24+`;
-- `pnpm` and DeepSeek Harness `0.1.0-rc.7`;
+- `pnpm` and a DeepSeek Harness release listed in the compatibility matrix;
 - the BailingHub preparation above.
 
 Install the exact stable version into the DSH Web profile:
 
 ```bash
-npm install --global pnpm @deepseek-ai/dsh@0.1.0-rc.7
-dsh plugin --profile web add dsh-bailinghub@0.2.0
+npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile web add dsh-bailinghub@0.3.0
 ```
 
-`dsh-bailinghub@0.2.0` installs its exact compatible `bailinghub-mcp-server@0.2.0` dependency
+`dsh-bailinghub@0.3.0` installs its exact compatible `bailinghub-mcp-server@0.3.0` dependency
 automatically. DSH users should not separately guess or install an SDK version.
 
 ## Configure one Hub connection
@@ -75,7 +92,7 @@ The native plugin has exactly four host configuration fields:
 | `hubUrl` | `BAILINGHUB_HUB_URL` | Public HTTPS URL of the developer's own BailingHub | No |
 | `clientAppId` | `BAILINGHUB_CLIENT_APP_ID` | Public Agent Client application id registered in that Hub | No |
 | `workspace` | `BAILINGHUB_WORKSPACE` | Initial authorized workspace/route id | No |
-| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | Local alias for this isolated SDK connection | No |
+| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | User-selected local connection label | No |
 
 Example placeholders:
 
@@ -87,7 +104,9 @@ export BAILINGHUB_CONNECTION_NAME='default'
 ```
 
 The same four fields may be supplied through the DSH plugin settings surface. Do not add tokens,
-authorization URLs, business domains, or credentials to the Cordis patch.
+authorization URLs, business domains, or credentials to the Cordis patch. The Hub resolves the
+Client App to its single business authorization entry. `connectionName` is only a user-controlled
+local selector; it is not an account, tenant, or identity claim.
 
 Inspect the composed profile before starting it:
 
@@ -102,19 +121,26 @@ In DSH, run:
 
 ```text
 /bailinghub login
+/bailinghub doctor
 /bailinghub status
 /bailinghub workspaces
 ```
 
-`login` opens the system browser. The business-side authorization page confirms the signed-in
-business identity and requested workspace, then returns to a random loopback callback protected
-by `state` and PKCE S256. Access and refresh tokens remain in SDK-owned secure storage and are
-never written to the plugin configuration or printed by the command.
+`login` opens the system browser at the single business authorization entry configured by the Hub
+operator. That business page owns sign-in, account switching, and tenant selection, confirms the
+resulting business identity and requested workspace, then returns to a random loopback callback
+protected by `state` and PKCE S256. Access and refresh tokens remain in SDK-owned secure storage
+and are never written to the plugin configuration or printed by the command.
 
 Useful commands:
 
 | Command | Purpose |
 | --- | --- |
+| `/bailinghub doctor` | Check host APIs, public configuration, SDK resolution, authorization, and workspace reachability without printing credentials |
+| `/bailinghub connections list` | List local public connection metadata and authorization state without tokens |
+| `/bailinghub connections add <name> <hub-url> <client-app-id> <workspace>` | Create and select another local connection instance for new sessions; the public binding may match an existing instance |
+| `/bailinghub connections use <name-or-key>` | Select a registered connection for new sessions only |
+| `/bailinghub connections remove <name-or-key>` | Remotely revoke its Agent Session, then remove its local credential and metadata |
 | `/bailinghub login` | Authorize the configured Hub/client/workspace in the browser |
 | `/bailinghub status` | Inspect the selected connection without printing credentials |
 | `/bailinghub workspaces` | List workspaces allowed by the current business authorization |
@@ -122,12 +148,37 @@ Useful commands:
 | `/bailinghub sync` | Retry a pending visible completion record without repeating a tool call |
 | `/bailinghub logout` | Revoke and remove the selected Agent Session |
 
-The standard v1 login requests only the configured workspace. `use` succeeds only when the
-current Agent Session explicitly contains the target workspace; it is not permission to switch to
-an arbitrary Hub route. The current command set always operates on this plugin instance's four
-configured fields; it does not accept a connection selector. For another Hub or route, use a
-second DSH profile/plugin instance, or edit those fields and reload the profile, set a different
-`connectionName`, and complete browser authorization again.
+The four plugin fields are the bootstrap connection. Additional connections can be registered with
+`connections add`; the BailingHub console's Agent Client page can generate the same secret-free
+command. On restart, the adapter reads the SDK registry before the first new Agent session or user
+command and adopts its current connection's public metadata; a missing or unavailable registry
+safely falls back to the four bootstrap fields. Quote a connection name when it contains spaces.
+After `connections use`, run `/bailinghub login` if that binding is not authorized yet.
+
+Connection selection is a user-only slash command and is never exposed as a model tool. It affects
+only Agent sessions created afterward; existing sessions remain pinned to their original
+connection and workspace. `/bailinghub use <workspace>` remains a different operation: it succeeds
+only when the current Agent Session already authorizes that workspace.
+
+After removing the selected connection, the adapter reads the SDK registry and adopts the remaining
+current connection for new sessions, including connections without an alias. Removing the final
+connection leaves the adapter explicitly unconfigured. A failed post-remove registry read never
+turns a successful removal into an error; removing a non-current connection also preserves the
+still-valid default when that refresh is unavailable.
+
+For the same `Hub + clientAppId + workspace` public binding, browser authorization determines the
+identity from the business page and its trusted `on_behalf_of` result. If that identity is already
+authorized under another local connection name, the SDK replaces the older local connection and
+revokes its old Agent Session. A different trusted identity remains an independent connection.
+If login starts from a `connectionName` that already belongs to another identity, the SDK keeps
+that original alias and Session, gives the newly authorized identity an available local alias such
+as `default-2`, and selects the new alias for future sessions. Use `connections list` to see both
+and `connections use <name-or-key>` to switch explicitly.
+If login returns `cleanupRequired: true`, the newly selected connection is still authorized, but
+one or more existing same-binding connections need explicit cleanup. Their identity may still be
+unconfirmed when inspection was deferred. Do not authorize again; inspect
+`connections list` and retry `/bailinghub connections remove <name-or-key>` for the reported old
+entry.
 
 For the first acceptance check, start a new DSH conversation and perform one read-only request,
 then one permitted mutation. Confirm the same conversation, run, visible final answer, and tool
@@ -139,10 +190,11 @@ current-turn dynamic schemas. Use native tool mode for governed business actions
 
 ## Security and privacy boundary
 
-- The model cannot choose a Hub URL, workspace, identity, credential, approval result, or
-  capability revision through tool arguments.
-- The SDK stores credentials in macOS Keychain. Linux and other POSIX systems require an explicit
-  secure file-store opt-in; Windows Agent Session storage is not supported in 0.2.0.
+- The model cannot choose a Hub URL, workspace, local connection, business identity, credential,
+  approval result, or capability revision through tool arguments.
+- The SDK stores credentials in macOS Keychain. On Windows it protects credential files under
+  LocalAppData with CurrentUser DPAPI; unavailable Windows PowerShell or DPAPI fails closed without
+  a plaintext fallback. Linux and other POSIX systems require an explicit secure file-store opt-in.
 - BailingHub revalidates identity, scope, approval, idempotency, and invocation state on every
   governed call. The downstream business system still performs final authorization.
 - The adapter sends visible user input, governed tool arguments/results, and the visible final
@@ -176,13 +228,13 @@ mcp__bailinghub__get_governed_job
 mcp__bailinghub__wait_for_governed_job
 ```
 
-The 0.2 Agent Client does not automatically consume or migrate the 0.1 Client Token. Keep versions
-explicit and follow the [0.1-to-0.2 migration boundary](docs/MIGRATION_VNEXT.md) when testing or
+The 0.3 Agent Client does not automatically consume or migrate the 0.1 Client Token. Keep versions
+explicit and follow the [0.1-to-0.3 migration boundary](docs/MIGRATION_VNEXT.md) when testing or
 rolling back.
 
 ## Compatibility and feedback
 
-Version 0.2.0 is verified only against the versions listed in
+Version 0.3.0 is verified only against the versions listed in
 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). DeepSeek Harness remains a developer preview, so
 every Harness release requires a new native lifecycle smoke test.
 

package/SECURITY.md

@@ -19,15 +19,33 @@ configuration and are never model tool arguments.
 
 Non-loopback HTTP is denied by default. Do not enable insecure HTTP on an untrusted network.
 
-## Native 0.2.0 boundary
+## Native 0.3.0 boundary
 
-The native 0.2.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
+The native 0.3.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
 `connectionName`. The generic SDK owns browser authorization, refresh, and secure credential
-storage; business endpoints and final authorization remain Core/business-system concerns.
+storage; business endpoints and final authorization remain Core/business-system concerns. The
+Hub Client App owns one business authorization entry. That business page, not the plugin or model,
+handles login, account switching, tenant selection, and the trusted `on_behalf_of` identity.
+
+The multi-connection registry stores only public Hub/client/workspace metadata. `connectionName`
+is a user-only local selector, not an identity claim. After browser
+authorization, the SDK replaces an older same-binding connection only when the trusted
+`on_behalf_of` matches; different trusted identities remain isolated. A same-alias authorization
+for a different identity preserves the original alias and Session and assigns the new identity a
+non-conflicting local alias. If inspection or old-Session revocation is uncertain, the new
+connection stays authorized and explicit cleanup is required.
+Connection add/use/remove are user slash commands, not model tools. Removing an authorized
+connection is remote-revoke-first and keeps the local credential if revocation fails, so it cannot
+falsely report a complete logout.
 
 Tools are Agent/run scoped. Message ids are replaced by Core-safe hash aliases, invocation ids are
 stable 64-character digests, and an `accepted_unknown` outcome must resume that exact invocation
 instead of creating a replacement. Completion retries are bounded and reuse one frozen,
-visible-only payload. Version 0.2.0 installs `bailinghub-mcp-server@0.2.0` as an exact ordinary
+visible-only payload. Version 0.3.0 installs `bailinghub-mcp-server@0.3.0` as an exact ordinary
 dependency and resolves its `./sdk` export. It does not depend on ambient modules, an optional
 peer, a range, a dist-tag, or a local path. Public `0.1.1` does not provide that facade.
+
+Agent Session credentials use macOS Keychain or Windows CurrentUser DPAPI-protected files under
+LocalAppData. Windows PowerShell or DPAPI unavailability fails closed without a plaintext fallback.
+Linux and other POSIX hosts must explicitly enable the SDK's isolated mode-0600 file store. The
+plugin never receives the credential value and never writes one into Cordis configuration.

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,7 +1,8 @@
 # Agent Client Host Adapter Contract
 
-Status: public native Agent Client contract for `dsh-bailinghub@0.2.0`. This contract is not part
-of the legacy public `0.1.x` line.
+Status: public native Agent Client contract for `dsh-bailinghub@0.3.0`. This contract is not part
+of the legacy public `0.1.x` line. The multi-connection lifecycle described below is stable with
+BailingHub Core `0.5.1` and `bailinghub-mcp-server@0.3.0`.
 
 ## Host Configuration
 
@@ -14,9 +15,12 @@ workspace
 connectionName
 ```
 
-`hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace.
-`connectionName` is a local SDK alias. No business endpoint, authorization endpoint, token, secret,
-or business credential belongs in this config.
+`hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace binding.
+`connectionName` selects one local SDK connection instance, but it is not an account, tenant, or
+identity claim. The Hub Client App resolves to one stable business authorization endpoint; no
+business endpoint, authorization endpoint, token, secret, or business credential belongs in this
+config. The business authorization page owns sign-in, account switching, tenant selection, and
+the trusted identity ultimately represented by `on_behalf_of`.
 
 ## Injectable Transport Seam
 
@@ -24,6 +28,11 @@ The default transport is lazily created from `bailinghub-mcp-server/sdk`. Tests
 adapters may inject an object with all methods below:
 
 ```js
+connectionsList({})
+connectionsAdd({ connectionName, hubUrl, clientAppId, workspace })
+connectionsUse(connectionNameOrKey)
+connectionsRemove(connectionNameOrKey)
+
 login({ hubUrl, clientAppId, workspace, route, connectionName })
 status({ connectionName })
 logout({ connectionName })
@@ -56,6 +65,30 @@ The adapter may pass a second host metadata argument (`workspace`, `connectionNa
 `AbortSignal`) to turn/tool methods. The framework-neutral SDK DTO is always the first argument;
 an SDK implementation that does not consume host metadata may ignore it.
 
+## Browser Identity and Local Reconciliation
+
+`/bailinghub login` always starts from the selected Hub/client/workspace binding. The plugin does
+not accept or derive a business URL, account id, tenant id, or identity selector. Core redirects
+to the single authorization endpoint configured for that Client App, and the business page
+performs any login, account switching, or tenant selection required before it approves the
+authorization.
+
+The SDK may stage more than one named local instance for the same public binding while browser
+authorization is in progress. After authorization it compares the trusted Session
+`on_behalf_of`, never the local `connectionName`:
+
+- the same identity replaces the older local connection and revokes its old Agent Session;
+- a different identity remains a separate named connection; when login was launched from an alias
+  already owned by the old identity, the SDK preserves that alias and Session, allocates an
+  available alias such as `default-2` to the new identity, and makes the new connection current;
+- an uncertain identity inspection or failed old-Session revoke keeps the new Session authorized
+  and returns `cleanupRequired: true` with cleanup metadata.
+
+The adapter reports that last result as successful authorization plus a visible warning. It tells
+the user not to authorize again and to retry explicit cleanup with the user-only connection
+lifecycle commands. It does not turn the result into a failed login or let the model perform
+cleanup.
+
 ## Core HTTP Mapping
 
 The SDK, not this adapter, maps those DTOs to:
@@ -97,9 +130,9 @@ object-rooted input schema, and complete governance metadata (`scope`, `risk`,
 Both revision fields are required lowercase 64-character SHA-256 values; shorter labels or
 uppercase digests fail closed.
 
-## Verified DSH rc.7 Lifecycle
+## Verified DSH Lifecycles
 
-DSH `0.1.0-rc.7` claims inbox messages before assembling the current step:
+DSH `0.1.0-rc.7` and `0.1.1-rc.2` claim inbox messages before assembling the current step:
 
 ```text
 agent/inbox/claimed
@@ -160,9 +193,38 @@ same bounded recovery state when known locally, and never creates a replacement
 
 ## Session and Completion State
 
-Connection name, workspace, conversation alias, Core run, active definitions, and completion
-state are isolated per DSH Agent/session. A workspace switch affects future sessions and is
-rejected while any Core run is active/completing or has an unsynchronized completion payload.
+Connection selector, workspace, conversation alias, Core run, active definitions, and completion
+state are isolated per DSH Agent/session. Named connections for different trusted identities own
+separate SDK credentials and Agent Sessions. Same-binding connections that resolve to the same
+trusted identity are reconciled to one local survivor after authorization. A workspace switch
+preserves the selected connection instance and affects future sessions; it is rejected while any
+Core run is active/completing or has an unsynchronized completion payload.
+
+After a same-alias login resolves to a different trusted identity, the SDK-returned replacement
+alias becomes the adapter default for new sessions. The retained old alias and the new alias both
+remain visible through `connections list` and user-selectable through `connections use`; existing
+DSH sessions remain pinned as described below.
+
+Multi-connection add/use/remove is exposed only through the `/bailinghub connections` user
+command. It is never registered as a model tool. Selecting a connection changes defaults for new
+Agent sessions only; existing states keep their captured connection and workspace. Removing a
+connection is rejected while any run is active or has an unsynchronized completion. The SDK then
+revokes only that instance's remote Agent Session before removing its local credentials and
+registry metadata; a revoke failure preserves both. Repeating add with the same name and public
+binding selects the existing instance; reusing a name for different public metadata fails.
+`connectionName` remains a local user selector and never becomes a trusted identity claim.
+
+After a successful remove, the adapter reads the registry again. A valid remaining
+`currentConnectionKey` replaces all four public defaults for future sessions, using the key itself
+when the profile has no alias; no remaining connection sets the adapter to unconfigured. A refresh
+failure does not change the successful remove result. It makes a removed default unavailable, but
+does not invalidate an unchanged non-current default. Existing session state is never rewritten.
+
+The four static adapter fields bootstrap SDK construction only. Before the first new Agent session
+or user command after process start, the adapter reads `connectionsList()` and adopts the public
+metadata matching `currentConnectionKey`. Invalid, missing, or unavailable registry data leaves the
+bootstrap defaults in place and must not remove or block unrelated host tools. The lookup is not a
+model tool, and restoring or later selecting a default never mutates an already-created session.
 
 The completion request is restricted to:
 
@@ -183,8 +245,8 @@ the first attempt and reused unchanged for up to three automatic attempts. A fai
 remains pending in its original run; `/bailinghub sync` starts another bounded attempt batch with
 that same id and payload.
 
-DSH `0.1.0-rc.7` reports disjoint camelCase buckets (`inputTokens`, `cacheReadTokens`, optional
-`cacheWriteTokens`, and `outputTokens`) on each durable `assistant/message`. The adapter sums them
+The verified DSH releases report disjoint camelCase buckets (`inputTokens`, `cacheReadTokens`,
+optional `cacheWriteTokens`, and `outputTokens`) on each durable `assistant/message`. The adapter sums them
 across model steps, exposes total input as Core `input_tokens`, cache reads as the
 `cached_input_tokens` subset, and derives `total_tokens` without adding `reasoningTokens` a second
 time. Unknown, non-finite, and negative metrics are discarded; only the Core public usage

package/docs/COMPATIBILITY.md

@@ -1,38 +1,43 @@
 # Compatibility
 
-## Native Agent Client 0.2.0
+## Native Agent Client 0.3.0
 
 | Component | Verified version |
 | --- | --- |
-| DeepSeek Harness / Cordis lifecycle | `0.1.0-rc.7` |
+| DeepSeek Harness / Cordis lifecycle | `0.1.0-rc.7`; `0.1.1-rc.2` |
 | Node.js | `22.19.0+` or `24+` |
 | DSH tool presentation | Native Tool Mode |
-| Generic Agent Client SDK | `bailinghub-mcp-server@0.2.0` via `./sdk` |
-| BailingHub Core | `bailinghub@0.5.0`; Agent Auth v1 + Agent Client Runtime v1 |
+| Generic Agent Client SDK | `bailinghub-mcp-server@0.3.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.5.1`; Agent Auth v1 + Agent Client Runtime v1 |
 | BailingHub turn context | `bailing.agent-turn-context.v1` |
 | BailingHub capability search | `bailing.agent-capability-search.v1` |
 | BailingHub governed invocation | `bailing.agent-tool-invocation.v1` |
 | BailingHub run completion | `bailing.agent-run-completion.v1` |
 
-Version 0.2.0 declares `bailinghub-mcp-server@0.2.0` as an exact ordinary dependency. A clean DSH
+Version 0.3.0 declares `bailinghub-mcp-server@0.3.0` as an exact ordinary dependency. A clean DSH
 profile must work after installing only the plugin; ambient `node_modules`, peer/optional
 dependencies, dist-tags, ranges, and local `file:` paths are outside the supported contract.
-Compatibility with Core 0.5.0 includes migrations 055/056 and the live Agent Auth/Runtime
+Compatibility with Core 0.5.1 includes the live Agent Auth/Runtime
 contracts from that release.
 
 DeepSeek Harness remains a developer preview. Every Harness version change requires a new smoke
 against its real Cordis lifecycle, prompt waterfall, ToolRuntime, commands, durable session events,
 and Web profile installation before this table can change.
 
+`/bailinghub doctor` validates the required host API shape at runtime and reports the releases for
+which that shape has been exercised. This is a diagnostic check, not a substitute for the live
+browser authorization, read/write, approval/recovery, trajectory, and revocation gates below.
+
 ### Tool-mode and operating-system boundaries
 
 - Native Tool Mode is required. DSH Code Mode is deliberately degraded because it cannot safely
-  present the current-turn dynamic business schemas in 0.2.0.
+  present the current-turn dynamic business schemas in 0.3.0.
 - macOS Agent Session credentials use Keychain.
 - Linux and other POSIX systems require the SDK's explicit secure file-store opt-in; the file must
   remain owned by the current user with mode `0600`.
-- Windows Agent Session credential storage is not supported by 0.2.0. Do not describe
-  Client Token compatibility as native Agent Session support.
+- Windows Agent Session credentials use CurrentUser DPAPI. Native package installation, SDK
+  resolution, and host lifecycle are Windows CI gates; each deployment must still accept its own
+  live browser and business authorization flow.
 - Non-loopback Hub connections require HTTPS. Loopback HTTP is for local development only.
 
 ### Host configuration contract
@@ -50,6 +55,16 @@ In Agent Client v1, `workspace` is the BailingHub route id. Business endpoints,
 URLs, Client Tokens, Tool Provider signing secrets, business credentials, and model-provider keys
 are not DSH plugin configuration.
 
+The public binding is the normalized Hub URL, client app id, and workspace tuple.
+`connectionName` is a user-controlled local selector, not an identity claim. The Hub Client App
+supplies one stable business authorization entry, and the business page
+handles login, account switching, and tenant selection. After authorization, the SDK compares the
+trusted `on_behalf_of` within the same public binding: the same identity replaces the older local
+connection, while different identities remain independent. When a same-alias login returns a
+different identity, the old alias and Session remain intact and the new identity receives a
+non-conflicting alias that becomes current. A cleanup-required result keeps the new connection
+authorized and must be resolved explicitly without another authorization attempt.
+
 ## Public legacy 0.1.x
 
 | Component | Published version |
@@ -65,7 +80,7 @@ Public `dsh-bailinghub@0.1.1` remains a configuration-only bundle. It starts the
 operator-configured Hub URL, route-scoped Client Token, and route. It does not establish an Agent
 Session, receive a dynamic capability catalog, or move orchestration into local DSH.
 
-The 0.2 line must not mutate the published 0.1 package or reinterpret its configuration. A new
+The 0.3 line must not mutate the published 0.1 package or reinterpret its configuration. A new
 BailingHub Core release is compatible only after a separate clean legacy profile proves that the
 0.1.1 `/run` and `/jobs/{job_id}` flow still works.
 
@@ -73,8 +88,9 @@ BailingHub Core release is compatible only after a separate clean legacy profile
 
 Compatibility requires independent evidence for both paths:
 
-1. Native 0.2: clean install of only the exact plugin package, browser authorization, workspace
-   discovery, read, permitted mutation, approval/resume, visible completion, and Hub trajectory.
+1. Native 0.3: clean install of only the exact plugin package, browser authorization, workspace
+   discovery, same-identity replacement, different-identity isolation, read, permitted mutation,
+   approval/resume, visible completion, and Hub trajectory.
 2. Legacy 0.1.1: clean static profile, fixed Client Token route, one submit, and same-job follow-up
    through the unchanged public Client API.
 

package/docs/GETTING_STARTED.md

@@ -0,0 +1,92 @@
+# Get started in three minutes
+
+This guide is for someone whose organization has already connected a business system to
+BailingHub. If that integration does not exist yet, the BailingHub administrator and business
+developer must prepare it before an end user installs this plugin.
+
+## What to ask your administrator for
+
+Ask for these four public connection values:
+
+```text
+Hub URL
+Client App ID
+Workspace
+Connection Name
+```
+
+They identify the BailingHub application and starting workspace. They are not credentials. Do not
+ask the administrator to send you a Client Token, Tool Provider secret, business password, model
+API key, authorization code, browser session cookie, business URL, or tenant-specific login URL.
+
+## 1. Install the plugin
+
+Install the exact public version into the DSH Web profile:
+
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.3.0
+```
+
+The plugin installs the matching BailingHub SDK automatically.
+
+## 2. Enter the four connection values
+
+Use the DSH plugin settings page or these environment names:
+
+```bash
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='employee_assistant'
+export BAILINGHUB_CONNECTION_NAME='default'
+```
+
+The values above are placeholders. Use the public values from your own BailingHub administrator.
+Never paste credentials into the Cordis patch or a chat message.
+
+## 3. Authorize in the browser
+
+Start DSH and run:
+
+```text
+/bailinghub login
+/bailinghub status
+/bailinghub workspaces
+```
+
+`login` opens the one business-side authorization entry configured for the Client App. Sign in or
+switch account there, select a tenant there when the business system asks, and check the resulting
+business identity and requested workspace before approving. Authorization uses the business
+system's own login; it does not send the business password or business URL to the plugin.
+
+`Connection Name` is only a local selector. If the same trusted business identity authorizes the
+same Hub/client/workspace binding again, the SDK replaces the older local connection. A different
+trusted identity remains separate. When the selected name already belongs to the old identity,
+the SDK preserves it and assigns the new identity an available alias such as `default-2`; the new
+alias becomes current. Run `/bailinghub connections list` to see both and
+`/bailinghub connections use <name-or-key>` to switch. If login says cleanup is required, the new
+connection is already authorized, but an existing connection may still need inspection or
+removal: do not authorize again; list connections and remove the reported old entry.
+
+## 4. Try one safe business request
+
+Start a new conversation and ask for one read-only action that the connected system exposes, for
+example:
+
+```text
+Find the demonstration employee EMP-001 and summarize the visible fields.
+```
+
+Then try one reversible permitted update in a dedicated development workspace. The exact requests
+depend on the capabilities your business system has exposed. An operation that requires approval
+must continue through the existing approval flow; an operation outside the current identity's
+permissions must remain unavailable.
+
+## 5. Confirm the result in BailingHub
+
+The BailingHub console should show the same visible conversation, Agent Run, governed tool calls,
+approval state, and final result. Do not treat a successful installation alone as proof that a
+business action ran.
+
+If setup fails, include the DSH version, plugin version, operating system, the command that failed,
+and redacted error text in a GitHub Issue. Never attach tokens, private URLs, personal information,
+authorization codes, or production payloads.