docs: refresh Artemis development and design guides

packages/artemis-client/DESIGN.md

@@ -1,5 +1,10 @@
 # Artemis Thin Client Design
 
+This document describes the remote SDK, not the web console's visual design.
+The shared runtime and UI boundaries are documented in the repository's
+[DESIGN.md](../../DESIGN.md). Current behavior below includes the 2.0 exploration
+adapter; versioned remote endpoints remain a protocol evolution proposal.
+
 ## Goals
 
 Developer machines install only a small remote SDK, while the host connected to
@@ -34,9 +39,36 @@ session database, the client reconstructs its state from `queue` and
 Experimental parameters live in `options`. Older servers ignore unknown fields,
 while newer servers can consume them without requiring an immediate SDK release.
 
-## Phase 2: Stable Remote API
+### Guided exploration in 2.0
 
-The server should expose versioned endpoints dedicated to remote clients:
+`ArtemisClient.exploration()` uses the existing `/api/explorations` API shared
+with the web workspace and MCP. It supports read-only list/get/case queries,
+session lifecycle and messages, manual demonstrations, immutable case versions,
+generation, reruns, and batch-draft creation. It adds no scheduler or local agent.
+
+Mutations require a stable `request_id`, except pause/stop. Reusing a request ID
+must not repeat the business operation. Read operations reject mutation fields;
+creating a batch draft does not start it. Case generation returns a job whose
+state is read from the exploration session, rather than blocking the client for
+the entire model call.
+
+Execution status, test verdict, case generation, and rerun results are separate.
+`TaskResult.succeeded` currently reflects execution status only; it does not
+prove that the test passed. Consumers must inspect the server's effective test
+result and evidence, including `runs[].test_result` for exploration, and retain
+unknown response fields through `raw`. A client polling timeout does not cancel
+the server task; stopping it is a separate explicit operation.
+
+The host owns source metadata, demonstration recording scope, execution budgets,
+model retries, final acceptance, and artifact persistence. The client passes the
+requested settings through the shared API and never reconstructs missing PC
+evidence from Android screenshots or restarts a case after a request failure.
+
+## Phase 2: Proposed stable remote API
+
+The following endpoints are an evolution proposal, not the current submission
+API. Do not replace the working compatibility adapter with these routes until
+the host implements and advertises them:
 
 ```text
 POST   /api/v1/tasks
@@ -48,8 +80,9 @@ GET    /api/v1/devices
 GET    /api/v1/capabilities
 ```
 
-The administration API and remote SDK API should remain separate. The remote API
-uses a consistent error envelope:
+A future remote surface can separate administration access from task access
+while delegating to the same backend services and scheduler. The proposed error
+envelope is:
 
 ```json
 {
@@ -66,7 +99,7 @@ uses a consistent error envelope:
 1. `/api/v1` may add optional request and response fields, but must not change existing field semantics.
 2. The client ignores unknown response fields and preserves the original response in each model's `raw` attribute.
 3. Every new request field must have a server-side default.
-4. The SDK checks `/api/v1/capabilities` before using a new feature.
+4. `capabilities()` probes `/api/v1/capabilities` and falls back to the known baseline on 404; future feature gating must not pretend that this fallback advertises new host features.
 5. Breaking changes ship under `/api/v2`; they are never applied in place.
 6. The SDK and server follow semantic versioning independently.