dsh-modellix 0.1.0 → 0.2.0

package/docs/en-US/USER_GUIDE.md

@@ -2,32 +2,17 @@
 
 # dsh-modellix User Guide
 
-This guide is for Harness users who install and use `dsh-modellix`. `README.md` is the default English entry, a complete Chinese edition is available alongside it, and plugin UI text follows the current Harness locale.
+This guide describes the current `0.2.0` experience. Media creation is chat-first; there is no standalone Design tab. The right-side **Modellix Design** panel is a session-scoped result workspace.
 
-`dsh-modellix` uses one Modellix API Key for three independently controlled capabilities:
-
-| Capability | Entry point | Purpose |
-| --- | --- | --- |
-| Design | The Design view in Harness | Select an image, video, or audio model, use a prompt, parameter form, or natural-language adjustment, and review results |
-| LLM | The Harness model selector and Modellix settings | Synchronize the live Modellix model catalog and switch models quickly |
-| Web | Native Harness Web Tools | Run `web_search` and `web_fetch` through the Modellix provider |
-
-## Installation and verification
+## 1. Install and verify
 
 ### Requirements
 
 - DeepSeek Harness `0.1.1-rc.2`
-- Published-package runtime: Node.js `^22.19.0 || >=24.0.0`
-- Source development and release verification: Node.js `24.18.1` and pnpm `11.24.0` (see `.nvmrc` and `packageManager`)
-- A valid [Modellix API Key](https://docs.modellix.ai/get-started)
-
-The Bundle contains its own Harness integration. `modellix-cli` is neither installed nor invoked as a runtime dependency.
+- Node.js `^22.19.0 || >=24.0.0`
+- A valid Modellix API Key
 
-Harness and this plugin currently use prerelease interfaces. Before upgrading Harness, inspect the plugin version, peer dependencies, and repository changelog.
-
-### Install the published package
-
-The examples below use the `web` profile. Replace that name consistently if your profile differs:
+Install the package into the Harness Web profile:
 
 ```sh
 dsh plugin --profile web add dsh-modellix
@@ -35,469 +20,297 @@ dsh --profile web --dump-config
 dsh --profile web
 ```
 
-Inspect `--dump-config` and confirm that it contains:
-
-- the `dsh-modellix` Bundle configuration layer;
-- a plugin row whose id is `modellix`;
-- Web configuration that selects the `modellix` Search/Fetch provider and enables the native Harness Search/Fetch tools.
-
-After installing or updating the Client Bundle, restart the corresponding Harness Web profile. Refreshing the browser alone does not load a new Bundle.
+The dumped configuration should contain the `dsh-modellix` Bundle and plugin id `modellix`. Restart the running profile after installing or updating a Client bundle.
 
-### Install a tarball built from source
-
-Build only from trusted source:
+To use a local package artifact:
 
 ```sh
 pnpm install --frozen-lockfile
 pnpm run verify:release:static
 pnpm pack
-dsh plugin --profile web add ./dsh-modellix-0.1.0.tgz
-```
-
-`pnpm run check` includes environment verification, type checking, lint, the complete unit/contract suite, global hard coverage thresholds, and file-specific regression floors for the Host runtime and Design parameter planner. `verify:release:static` also performs the production dependency audit, build, exact artifact verification, an isolated Node 24 tarball installation, and a mandatory Node.js `^22.19.0` tarball runtime smoke. It does not replace real-browser and real API/Agent acceptance. Installing TypeScript source directly from Git requires the install phase to create `lib/`. Without a verified `prepare` flow, use the published package or a prebuilt tarball.
-
-### Complete release evidence gate
-
-Before an actual release, commit the final code, documentation, and screenshots and keep the worktree clean. Create the following two Secret-free JSON files outside the repository. Each must be under 32 KiB, target the current package name/version and lowercase 40-character HEAD, and use a canonical UTC ISO-8601 `completedAt` no more than 72 hours old.
-
-Browser evidence must attest onboarding, settings, Design, LLM, Web, 401 Credential recovery, accessibility, themes, and viewport acceptance:
-
-```json
-{
-  "version": 1,
-  "kind": "browser",
-  "status": "passed",
-  "package": { "name": "dsh-modellix", "version": "0.1.0" },
-  "commit": "<current-40-character-lowercase-git-head>",
-  "completedAt": "<canonical-utc-iso-8601>",
-  "checks": {
-    "onboarding": "passed",
-    "settings": "passed",
-    "design": "passed",
-    "llm": "passed",
-    "web": "passed",
-    "401": "passed",
-    "a11y": "passed",
-    "theme": "passed",
-    "viewports": "passed"
-  }
-}
-```
-
-Real API/Agent evidence must cover catalogs, parameter planning, image, video, audio, the LLM Agent, and Web. An operator must explicitly trigger every real billed call. The Boolean field records only that authorization; never include a Key, Authorization header, Credential, request header, or other Secret in evidence:
-
-```json
-{
-  "version": 1,
-  "kind": "api-agent",
-  "status": "passed",
-  "package": { "name": "dsh-modellix", "version": "0.1.0" },
-  "commit": "<current-40-character-lowercase-git-head>",
-  "completedAt": "<canonical-utc-iso-8601>",
-  "checks": {
-    "catalogs": "passed",
-    "planner": "passed",
-    "image": "passed",
-    "video": "passed",
-    "audio": "passed",
-    "llm-agent": "passed",
-    "web": "passed"
-  },
-  "billedCallsExplicitlyAuthorized": true
-}
-```
-
-For a live run, first complete one Modellix-backed DSH Agent turn in an isolated Web profile. Have the acceptance process provide `MODELLIX_API_KEY` directly from a controlled source, set `MODELLIX_ALLOW_BILLED_E2E=1`, `MODELLIX_REAL_AGENT_ATTESTED=1`, and absolute outside-repository paths in `MODELLIX_REAL_E2E_OUTPUT_DIR` and `MODELLIX_API_AGENT_E2E_EVIDENCE_FILE`, then run `pnpm run test:real:modellix`. The runner uses no Mock transport: it performs live catalogs and Schema planning, submits one image/video/audio POST each, uses bounded task reads, calls real Web Search/Fetch, saves downloaded media for independent decoding checks, and writes Secret-free evidence. It does not accept a Key on the command line.
-
-Run the complete gate with absolute paths:
-
-```sh
-MODELLIX_BROWSER_EVIDENCE_FILE=/absolute/path/browser-evidence.json \
-MODELLIX_API_AGENT_E2E_EVIDENCE_FILE=/absolute/path/api-agent-evidence.json \
-pnpm run verify:release
+dsh plugin --profile web add ./dsh-modellix-0.2.0.tgz
 ```
 
-The gate does not execute or retry billed calls. It fails for a missing, failed, or unknown fixed check; in-repository or stale evidence; package/commit mismatch; unavailable Node 22; or a dirty worktree. Node 22 is discovered from NVM or can be supplied by absolute `MODELLIX_NODE22_BINARY`; it is never silently skipped.
-
-## First-time setup
+See [LOCAL_USAGE.md](LOCAL_USAGE.md) for isolated-profile setup and update commands.
 
-When the plugin has no usable Credential and setup has not been deferred, the Harness Web UI displays the “Connect Modellix” dialog.
+## 2. Connect Modellix
 
-![Chinese-language Modellix first-time setup dialog with an empty API Key field and Design, LLM, and Web switches enabled](../assets/onboarding-defaults.webp)
+### First-time flow
 
-### Standard flow
+1. Open the Harness Web UI.
+2. In **Connect Modellix**, enter a valid API Key.
+3. Keep Design, LLM, and Web enabled unless your environment intentionally disables one capability.
+4. Select **Save and enable**.
+5. Open Settings → Modellix and verify that the Credential source/status and LLM catalog are healthy.
 
-1. Enter the Key in the “Modellix API Key” field. The field is masked by default.
-2. Review the Design, LLM, and Web feature switches. All three are on by default on a fresh installation.
-3. Select “Save and enable.” The plugin stores the Key through the Harness Credential boundary before it stores non-secret settings.
-4. After a successful save, the draft is cleared. The UI shows only configured status and source; it never reveals the stored Key.
+The stored Key is write-only. After save, the UI displays status and source but never returns the Key to the Client.
 
-Use the “Show API Key / Hide API Key” button to inspect only the current unsaved draft. The button cannot read a stored Credential.
+Select **Configure later** only when you want to postpone setup. The plugin remains unavailable and asks again on the next explicit use of an enabled Modellix capability.
 
-### Configure later
+### Environment Credential
 
-Selecting “Configure later” stores the current feature switches and closes this onboarding request. It does not create a Credential or mark any Modellix capability as Ready.
+You can supply `MODELLIX_API_KEY` in the Harness launch environment. The settings UI reports an environment source but cannot display, replace, or remove it. Update the external secret and restart Harness.
 
-- You can configure the Key directly from Modellix settings at any time.
-- The next explicit use of an enabled Modellix capability that needs a Credential creates a new recovery request and prompts again.
-- A single recovery request displays only one Credential dialog; concurrent 401 responses do not stack dialogs.
+### Secret handling
 
-A mandatory Credential dialog cannot close implicitly through Escape or the backdrop, but “Configure later” remains visible and keyboard accessible.
+Never place a real Key in:
 
-## Credential sources and security
+- a repository, patch, fixture, document, or screenshot;
+- a command argument, URL, query, hash, or browser storage;
+- Client state, DOM/ARIA, logs, Console, toast, telemetry, HAR, recording, or snapshot.
 
-### Two sources
+## 3. Understand the current interface
 
-| Source | Configuration | Can the UI replace/remove it? | How to update it |
-| --- | --- | --- | --- |
-| Local Harness Credential | Enter during first-time setup or in Modellix settings | Depends on whether the Credential store is writable; normally yes | Select “Replace API Key” or “Remove API Key” in settings |
-| Environment variable | Provide `MODELLIX_API_KEY` in the Harness launch environment | No; it is read-only in the UI | Update the external launch environment or secret manager, then restart Harness |
+![English Modellix settings with a configured Credential and live model catalog](../assets/settings-ready-en.webp)
 
-If a usable environment Credential already exists, first-time setup normally does not ask for another Key. If that environment Key receives an explicit 401, the UI explains that it cannot be overridden. Update the launch environment and restart Harness.
+The plugin adds:
 
-Do not write a Key value directly into documentation, shell history, or launch arguments. Use the operating system, service manager, or a controlled Secret mechanism to inject `MODELLIX_API_KEY` into the Harness process.
+- a Modellix section in Settings;
+- a **Modellix Design** launcher at the far right of the session header;
+- chat result cards for media generation/result tools;
+- Modellix models in the Harness model selector;
+- explicit Modellix Web tools available to the Agent.
 
-### Security boundary
+It does not add a standalone Design tab.
 
-- A stored Key is resolved only inside the Harness Host Credential boundary; the Client never reads its bytes.
-- An unsaved draft exists only in the current form state and is cleared on save, cancel, “Configure later,” or component unmount.
-- After save, the Credential value never returns to the Client or enters a URL, query, hash, settings document, Design task record, prompt, model context, Tool argument, user-facing diagnostic, DOM, ARIA, log, or screenshot.
-- Public model Schema requests carry no Authorization. Authenticated requests are limited to fixed Modellix HTTPS origins.
-- Design revalidates the exact Modellix endpoint from the Schema and rejects cross-origin redirects.
-- Persisted Design records contain only request/task identifiers, model, state, and result URLs—not the Key or prompt.
+### Right-side panel
 
-Screenshots and issue reports must never contain a real Key, Network request details, HAR, Credential files, sensitive Console context, or persistent recordings of a real-Secret flow.
+- Desktop width is fixed at 360 px so its internal card layout does not compress during the open/close transition.
+- At 560 px and below it becomes a full-width panel.
+- Results and every card are expanded by default.
+- Select **Results** to collapse the whole list; select a card header to collapse only that card.
+- Select X to close. Keyboard focus returns to the launcher.
+- The advanced exact-parameter editor remains in the implementation but its entry is hidden for `0.2.0`.
 
-## Modellix settings
+## 4. Create media by chatting
 
-![Chinese-language Modellix settings showing a verified Credential, three feature switches, and LLM catalog status](../assets/settings-ready.webp)
+Ordinary users should describe the desired work in natural language. The Agent selects tools and models according to the conversation.
 
-The settings page has three primary cards.
+### New text-to-image request
 
-### API Key
+Example:
 
-The status area shows both Credential source and verification state:
+> Create a polished 16:9 architectural hero image: a glass botanical research pavilion floating above a dawn cloud sea, connected to an observation bridge, restrained lapis-blue and warm-gold tones, realistic premium materials, no people, no text, no logo, no watermark.
 
-- “Not configured”: no usable Key exists;
-- “Configured in the local Credential store”: a local Credential is the source;
-- “Configured by a read-only environment variable”: `MODELLIX_API_KEY` is the source;
-- “Waiting for verification / Verified / Invalid Key”: the current verification state.
-
-For a writable local Credential, settings always retains a “Configure/Replace API Key” action. A configured local Credential also has “Remove API Key.” After removal, an enabled capability requests configuration on its next explicit call.
-
-An environment-sourced Key cannot be replaced or removed in the UI.
-
-### Feature switches
+If the user names a model or exact fields, the Agent still checks the live Schema before submission.
 
-Design, LLM, and Web can be toggled independently. You must select “Save changes” before an edit takes effect:
+### Continue from the previous work
 
-- With Design off, the Design view retains an explanation but cannot select models or submit generations.
-- With LLM off, the plugin no longer maintains the Modellix LLM catalog and manual refresh is unavailable.
-- With Web off, the Modellix Web provider is unavailable.
+Example:
 
-Disabling a feature does not delete existing upstream tasks, account data, or an external Key.
+> Turn the image just completed in this conversation into a five-second cinematic video. Slowly push the camera forward and preserve the composition and palette.
 
-### LLM model catalog
+The Agent treats references to the previous/current work, a conversation attachment, or a prior Modellix URL as source-dependent. It should select an edit or transformation model and place the latest relevant URL into that model's declared media input field. It must not silently replace the request with a new text-to-image or text-to-video task.
 
-This card shows catalog health, available model count, and last refresh time. Manual refresh is available only when LLM is enabled and a Credential is configured.
+### Use a local file or attachment
 
-A catalog refresh failure does not create a static replacement list or misreport a 402, 429, network failure, or 5xx as an invalid Key.
+When the live Schema needs an HTTP(S) media URL, the Agent can call `modellix_media_upload_file` for:
 
-## Design: image, video, and audio generation
+- a current-session attachment; or
+- a regular, non-symlink file inside the session workspace.
 
-### Left/right layout
+An upload is not automatically replayed if the outcome is unknown.
 
-![Chinese-language Modellix Design desktop layout with model, prompt, and parameters on the left and generation results on the right](../assets/design-desktop.webp)
+### Generate voice
 
-Design uses a “conversation and parameters on the left, results on the right” two-column layout on desktop:
+Example:
 
-- The left workspace contains model search and filters, model selection, the primary prompt, Schema parameters, the natural-language parameter assistant, and the single primary media-generation action.
-- The right results pane contains task states, media previews, expiry, download actions, and diagnostics.
+> Generate this English voiceover with a professional narrator, calm emotion, MP3 at 44.1 kHz: “From one idea to images, video, and sound, Modellix Design keeps creation flowing naturally in the conversation.”
 
-When the Design container is `992px` wide or narrower—for example, because the Harness sidebar reduces the available slot—the columns become one: the workspace comes first and Results follows. A viewport fallback also stacks the layout at `768px` and below. Content scrolls vertically, so horizontal scrolling is not required to reach a key action.
+The Agent must use a Schema-published voice and parameter format instead of translating or guessing enum values.
 
-### Select a model
-
-Design uses the current Modellix catalog instead of a static list assumed to remain valid forever.
-
-1. Search by model name, provider, or model id.
-2. Filter by All types, Image, Video, or Audio.
-3. Select a target in the model list. Models marked featured by the catalog have a star.
-4. Select “Refresh models” when you need the latest catalog. If live refresh fails while a cached result remains usable, the UI explicitly states that it is showing the most recent result.
-
-The plugin first restores the most recently selected model if it remains available. Otherwise, it chooses a preferred available model from the current catalog. Select again if a model is removed or becomes unavailable.
-
-### Schema parameters and defaults
-
-After model selection, the plugin reads its public `api_schema` and turns supported structures into a form:
-
-| Schema information | UI behavior |
-| --- | --- |
-| Primary prompt field | A required multiline prompt field |
-| `default` | Materialized into the draft and submitted unless the user overrides it |
-| `required` | Marked required; a missing value prevents generation |
-| `enum` | Select control |
-| `boolean` | Switch |
-| `number` / `integer` | Numeric input with minimum, maximum, and step constraints |
-| String | Single-line or multiline text input with length constraints |
-| Array or object | JSON editor with separate syntax-error and Schema-constraint messages |
-| An unsupported structure that cannot be interpreted safely | The field is disabled or the model cannot submit, with an explanation |
+## 5. Media tools and routing
 
-Optional parameters are collapsed under “Advanced parameters” by default. The Schema is an invocation contract, not a hint: Design rereads and compares it before generation. If the model definition changed, the old draft is rejected; refresh and confirm parameters again.
-
-### Three editing methods
-
-#### 1. Enter only a prompt
-
-For a model such as GPT Image 2 whose public Schema supplies the other defaults, the common path is:
-
-1. Select the model.
-2. Enter a prompt.
-3. Review the default parameters.
-4. Select “Confirm and generate.”
-
-The live model Schema always determines actual required fields. This guide does not assume that every model needs only a prompt.
-
-#### 2. Edit exact parameters
-
-Directly edit dimensions, aspect ratio, duration, count, format, or other model-advertised parameters. User values override defaults; the plugin does not send arbitrary fields absent from the Schema.
-
-If JSON cannot be parsed, the UI reports a JSON syntax error. If JSON parses but fails the current field constraints, it reports a parameter constraint error. Any invalid field or missing required field disables generation.
-
-#### 3. Adjust parameters in natural language
-
-Under “Adjust parameters by chat,” enter an instruction such as “make it 16:9, eight seconds, and more cinematic,” then select “Propose parameter changes.”
-
-This action:
-
-- uses the same Modellix Key with the fixed `openai/gpt-5.6-luna` model;
-- may incur separate LLM usage;
-- can change only parameters declared by the current Schema;
-- returns a summary, before-and-after field changes, and any conflicts;
-- neither applies changes nor starts media generation automatically.
-
-![Chinese-language Design parameter proposal showing before-and-after changes with Apply and Reject actions](../assets/design-proposal.webp)
-
-After review, select “Apply changes” or “Reject.” Resolve conflicts first. If parameters or the Schema changed after proposal creation, the stale proposal is rejected; create another proposal.
-
-### Worked Design example: a premium cliffside library
+| Tool | Purpose | Important behavior |
+| --- | --- | --- |
+| `modellix_media_list` | Search the live image/video/audio model catalog | Read-only; use when no compatible model is already known |
+| `modellix_media_schema` | Read the live API Schema for a model slug | Returns field paths, required state, options, and an IR contract hash |
+| `modellix_media_prepare` | Convert a natural-language adjustment into a reviewable Schema patch | Does not generate media; requires confirmation before applying |
+| `modellix_media_upload_file` | Upload a valid attachment/workspace file and return a URL | One-shot; unknown outcome is not replayed |
+| `modellix_media_generate` | Submit one Schema-validated generation | Submission is not automatically retried |
+| `modellix_media_get_result` | Read the current task result | Agent checks at most once in the submit turn; Client watcher owns continued status |
 
-Use this as a reproducible image-generation pattern, while treating the selected model's live Schema as authoritative:
+The Agent routing context is injected only while Design is enabled. Disabling Design removes these tools from model visibility.
 
-| Input | Example value |
-| --- | --- |
-| Model | `openai/gpt-image-2`, only when it is currently listed as available and its live Schema exposes the fields below |
-| Prompt used in acceptance | `A premium editorial architectural photograph of a quiet cliffside library above a misty alpine lake at blue hour, carved pale stone arches, warm amber reading lamps, one thoughtful reader, subtle greenery, natural reflections, cinematic but realistic lighting, restrained navy and ivory palette, precise composition, no text, no logo.` |
-| `quality` | `high` |
-| `size` | `1536x1024` |
+## 6. Result cards and status
 
-1. Select the available image model and wait for its parameters and defaults to load.
-2. Enter the prompt. Set `quality` to `high` and `size` to `1536x1024`; leave every unrelated field at the current Schema default.
-3. Either edit those controls directly, or enter “Set quality to high and size to 1536x1024” in the parameter assistant. The assistant returns a reviewable two-field proposal; it does not generate the image.
-4. Review the proposal and form, apply the changes if needed, and confirm model, output count, balance, and account-side pricing.
-5. Select “Confirm and generate” once, then follow the task in the right results pane.
+![A completed real image displayed directly in the English chat history](../assets/chat-media-generation-en.webp)
 
-The parameter proposal may incur separate LLM usage. The final media request is also potentially billed and is submitted exactly once; the plugin does not automatically retry it. If the live Schema does not expose `quality`, `size`, or either example value, do not add or force them—use only the controls and values advertised by that model.
+### Running
 
-The 2026-08-26 real acceptance run used controlled credentials without exposing them to the browser. It completed the high-quality `openai/gpt-image-2` Design flow shown below, a 6-second 768P `minimax/hailuo-2.3-t2v` task, an `alibaba/qwen-audio-3.0-tts-plus` narration, a Modellix-backed DSH Agent turn, real Web Search/Fetch calls, and a separate native `deepseek-official` DSH Agent baseline. The downloaded video decoded as H.264 at 1366×768 and 5.875 seconds; the narration decoded as mono MP3 at 22.05 kHz and 7.94 seconds. Release evidence remains outside the repository and contains no Secret.
+The chat card shows only its header/status and model. Preview and JSON are hidden because no successful resource exists yet. The assistant's ordinary response says the submission was accepted and points to the live card/panel; it does not embed a stale “running” state.
 
-### Confirmation and one-shot billed submission
+### Succeeded
 
-“Confirm and generate” starts the actual media generation and may incur a charge. Before submitting, confirm that:
+The existing card updates in place and exposes:
 
-- the model is correct;
-- the prompt and every required field are complete;
-- no parameter has a syntax or constraint error;
-- the account balance, pricing rules, and expected output count are acceptable.
+- **Preview** and **JSON** tabs;
+- image enlargement, video playback, or audio playback;
+- **Add URL to chat**;
+- **Download**.
 
-Each click performs one billed POST. The plugin never retries that POST automatically and never follows a cross-origin redirect. Task status reads are separate read-only operations with bounded safe retries for transient failures.
+The corresponding one-shot result query is suppressed when the generation card already owns the same job. This prevents two identical cards.
 
-If the connection ends during submission and the plugin cannot know whether upstream accepted the request, it records “Submission outcome unknown.” This is a replay fence, not proof of failure. Check the right pane or Modellix-side records before deciding whether to start a new generation manually.
+### Failed
 
-### Results, previews, and expiry
+The card remains concise and shows the failure state/diagnostic. Preview and JSON are not presented as if a successful resource existed.
 
-![Chinese-language Design results pane showing the image created during real acceptance, its expiry, and download action](../assets/design-results-media.webp)
+### Session ownership
 
-When you reopen Design or enter a new Harness session, the results pane reloads Host-persisted records, so unexpired resources remain available. Results are sorted by most recent update. The UI shows at most the latest 1,000 current persisted records, grouped as:
+Every new task records the Harness session id. Chat cards and the drawer read the same session controller, so:
 
-- Running: submitted, queued, or in-progress tasks;
-- Succeeded: successful tasks with an available resource;
-- Diagnostics: failed, canceled, unknown-submission, expired, or refresh-blocked tasks.
+- the left/chat status and right/drawer status converge to the same task snapshot;
+- a task created in another conversation is not shown;
+- reopening/remounting the layout does not destroy the background watcher;
+- legacy records without a session id remain readable for compatibility but are not injected into a new conversation.
 
-Images have a thumbnail and full-image viewer. Video and audio use native browser playback controls. Every available resource has a download action. External links open with no-referrer safety attributes.
+### Expiry and storage
 
-Result URLs are upstream Modellix resources:
+The plugin stores replay identifiers, task state, resource URLs, and timestamps. It does not store prompts, API Keys, or media copies in the task WAL. If the upstream result has no expiry, the UI applies a seven-day local display limit.
 
-- An upstream resource or task expiry takes precedence when present.
-- If upstream provides no expiry, the plugin uses a seven-day local display limit from completion or the last update.
-- After expiry, the resource is no longer presented as available.
-- The local limit does not renew, proxy, or permanently store the upstream file.
+## 7. Use the Modellix Design panel
 
-After replacing an API Key, a running task owned by an earlier Credential epoch may no longer refresh, while its existing non-secret record can still show the appropriate diagnostic.
+![The English right-side panel showing image, video, and audio results from one session](../assets/design-results-drawer-en.webp)
 
-## LLM: synchronize and switch models
+1. Select **Modellix Design** in the conversation header.
+2. Confirm that the result count matches the current session.
+3. Collapse or expand the Results section.
+4. Collapse or expand a card from its header.
+5. Switch between Preview and JSON for a successful card.
+6. Select **Add URL to chat** to continue editing or transforming that resource.
+7. Select **Download** to open the upstream file.
+8. Select X to close the panel.
 
-LLM reuses the same Key and does not require a separate Credential per model.
+## 8. Preview media
 
-1. In Modellix settings, confirm that LLM is enabled and the Credential is usable.
-2. Review “LLM model catalog” status and select “Refresh LLM models” when needed.
-3. Open the native Harness model selector.
-4. Select a target from the current catalog under the Modellix provider.
-5. The new model applies from the next model call.
+![A real five-second image-to-video result playing in chat and in the session panel](../assets/media-players-en.webp)
 
-Switching models does not replay an earlier call. Each new Harness model call may incur Modellix usage, and the provider retry limit remains `0`. If the desired model is missing, refresh the catalog in settings instead of typing an unverified model id.
+### Images
 
-![English-language Harness model selector expanded to the Modellix provider with multiple LLM models synchronized from the live catalog](../assets/llm-model-selector.webp)
+Select the image to open an enlarged dialog. Focus enters the dialog, Tab stays inside, Escape closes it, and focus returns to the image trigger.
 
-The plugin safely merges the live catalog into the Harness `llm-pi-ai` route while preserving unknown fields and user model metadata it does not own. The protocol configuration is:
+### Video
 
-- provider id: `modellix`;
-- OpenAI Completions-compatible protocol;
-- base URL: `https://llm.modellix.ai/v1`;
-- default input: text;
-- plugin-layer automatic retries: `0`.
+The native player supports playback, seek, volume/mute, fullscreen, and the browser's media menu. A completed result should load metadata and advance current time after Play.
 
-When the catalog is unavailable, its status is error or unavailable. The plugin does not guess model ids or build a static fallback catalog. LLM calls may be billed under Modellix account rules.
+### Audio
 
-## Web: native search and fetch
+The native audio player supports playback, seek, volume/mute, and the browser's media menu. A completed result should load duration and advance current time after Play.
 
-When Web is enabled and a Credential is usable, the plugin registers:
+## 9. Use Modellix LLM models
 
-- the Modellix Search provider for native `web_search`;
-- the Modellix Fetch provider for native `web_fetch`.
+![The English Harness model selector populated from the live Modellix catalog](../assets/llm-model-selector-en.webp)
 
-It does not create duplicate custom tools. Harness continues to own tool arguments, presentation, and lifecycle; the Bundle only selects the `modellix` provider.
+1. Keep LLM enabled in Modellix settings.
+2. Check catalog status/count or select **Refresh** if needed.
+3. Open the Harness model selector.
+4. Choose a model in the Modellix group.
+5. Send the next Agent turn.
 
-![English-language Harness conversation showing native web_search and web_fetch completed by the Modellix provider for a Chinese public-documentation request](../assets/web-tools.webp)
+The provider endpoint is OpenAI-compatible. Provider retries are `0`; unavailable catalog data does not produce fake model entries.
 
-For a typical flow, ask Harness to search a public topic, inspect the native `web_search` sources, and then fetch only the result you need with `web_fetch`. The provider is unavailable when Web is disabled, the Key is removed, or the Key is explicitly invalid. Web requests may incur Modellix usage. The provider does not automatically retry a request; when a potentially billed Fetch outcome is unknown, inspect the Harness transcript or Modellix-side record before manually repeating it. Do not put Secrets, private data, or content that should not be sent to a third party in a query or target page.
+## 10. Automatic Web Search and Fetch
 
-## States, errors, and recovery
+![An English Agent turn automatically using Modellix Search and Fetch for official documentation](../assets/web-tools-auto-en.webp)
 
-| State or error | Meaning | Recommended action |
-| --- | --- | --- |
-| Missing API Key | An enabled capability has no usable Credential | Configure it in recovery or Modellix settings, or choose Configure later |
-| HTTP 401 / invalid Key | Modellix explicitly rejected the Credential | Replace a local Key; update `MODELLIX_API_KEY` and restart Harness for an environment source |
-| HTTP 402 | Billing is unavailable or blocked | Check balance and billing; do not replace an otherwise valid Key to hide the issue |
-| HTTP 429 | The request was rate limited | Wait as instructed and retry manually; a billed submission is not replayed automatically |
-| Offline or DNS/connection failure | Harness Host cannot currently reach Modellix | Check network, proxy, and fixed HTTPS origins, then retry manually |
-| Timeout | The request did not complete within its bound | Retry reads later; for an unknown billed submission, check records first |
-| 5xx | Modellix is temporarily unavailable | Retry manually later; the Key is not marked invalid |
-| Policy blocked | Account or environment policy rejects the operation | Check Harness and Modellix account policy |
-| Schema unavailable/unsupported | The model contract cannot be interpreted safely | Refresh or select another model; do not bypass validation |
-| Schema changed | A pre-submit reread found an old draft contract | Reselect/refresh the model and confirm parameters again |
-| Submission outcome unknown | The billed POST outcome cannot be determined | Check Results or Modellix-side records before another billed action |
-| Resource expired | The upstream URL or local display period ended | The plugin cannot renew it; generate again if needed |
-| LLM catalog unavailable | Catalog read or materialization failed | Check switch, Key, network, and policy, then refresh manually |
-| Credential changed | The task belongs to an earlier Credential epoch | The old running task may not refresh; inspect diagnostics and do not auto-resubmit |
+Ask the question normally. For example:
 
-### Credential recovery flow
+> Verify the official Modellix page for alibaba/wan2.7-videoedit. Give its title, one required parameter and what it means, with a source. Do not answer from memory.
 
-1. Only an explicit 401 marks the Key invalid and creates a recovery request. Concurrent 401 responses are coalesced into one Credential dialog.
-2. If a local Key editor is already open, it upgrades in place to mandatory recovery wording. If an ordinary plugin dialog such as Remove API Key or the full-image viewer is open, recovery waits until that dialog closes instead of stacking a second modal.
-3. For a writable local Credential, enter a replacement and save it. The stored Key remains write-only, and the plugin does not replay the failed or billed operation; retry the intended capability explicitly after recovery.
-4. For an environment source, update `MODELLIX_API_KEY` outside Harness and restart the profile because the UI cannot replace it.
-5. “Configure later” dismisses only the current request. A timer does not repeatedly steal focus; another prompt appears only after a later explicit capability call still needs a Credential.
+Expected flow:
 
-A 402, 429, offline failure, timeout, or 5xx remains distinct and does not open invalid-Key recovery.
+1. Agent automatically calls `modellix_web_search`.
+2. When full-page content is needed, Agent calls `modellix_web_fetch`.
+3. The answer cites the fetched/source pages.
 
-![Chinese-language Modellix recovery dialog after an invalid API Key with an empty field and Configure later action](../assets/credential-recovery.webp)
+The user should not need to say “use search” or “use fetch.” If the user explicitly says not to browse, the Agent does not call them. The routing context also prevents duplicate calls to both the explicit tools and native provider tools for the same operation.
 
-## Accessibility, keyboard, and responsive behavior
+## 11. Settings and errors
 
-### Keyboard interaction
+### Feature switches
 
-- When a Credential dialog opens, initial focus moves to the API Key field.
-- `Tab` and `Shift+Tab` wrap inside the dialog while background content is inert.
-- Show/Hide Key is a native button with a dynamic accessible name and `aria-pressed` state.
-- Enter in the Key field can save. During save, the button retains action text, is marked busy, and blocks duplicate submission.
-- Ordinary confirmation dialogs support Escape. A mandatory Credential gate does not close implicitly with Escape, but Configure later remains focusable.
-- When a dialog closes, focus returns to the trigger or a reasonable primary-content location.
+- **Design:** controls media tools, chat result views, and the result panel.
+- **LLM:** controls live Modellix model materialization.
+- **Web:** controls Modellix Search/Fetch providers and explicit tools.
 
-Fields use real labels; help and errors are linked through stable relationships, and invalid fields expose `aria-invalid`. Asynchronous progress and result changes use polite live regions without treating an entire interactive region as an alert.
+### Credential status
 
-### Display and touch
+Only HTTP 401 is an invalid Credential. Other cases remain distinct:
 
-- Design has two columns when its container is wider than `992px`; narrower host slots use one column, with a viewport fallback at `768px`.
-- Below `560px`, model tools and action buttons stack and fill available width.
-- The layout targets `320 CSS px` and 200% text zoom. Long URLs, environment variable names, and Chinese/English copy can wrap.
-- In coarse-pointer environments, inputs, selects, disclosure summaries, links, and action buttons provide at least a 48px target.
-- Harness semantic tokens adapt the UI to light, dark, and Windows forced-colors modes.
-- `prefers-reduced-motion: reduce` disables unnecessary animation and transitions.
+| State | Meaning / next step |
+| --- | --- |
+| 402 | Check account status in Modellix |
+| 429 | Wait for the rate limit window |
+| Offline/timeout | Restore connectivity; do not assume the Key is invalid |
+| 5xx | Service error; retry only when the operation is safe |
+| Unknown generation/upload result | Inspect the task/transcript/Modellix record before any manual repeat |
 
-![English-language Modellix Design in a single-column layout at 320 pixels with the workspace above Results](../assets/design-mobile-en.webp)
+Concurrent 401 responses open only one Credential dialog. Settings always retains a replace-Key action where the Credential is writable.
 
-## Cost and security checklist
+Routine UI operations do not show a payment warning. Users with a required Modellix Key can review consumption and details in Modellix.
 
-Distinguish reads from actions that may incur usage:
+## 12. Accessibility and responsive checks
 
-| Action | May incur Modellix usage? | Plugin retry behavior |
-| --- | --- | --- |
-| Save/validate Key, read catalogs, or read public Schema | Normally a read or validation action; current Modellix rules apply | Runs inside the safe boundary and never mixes in a billed generation submission |
-| Design natural-language parameter proposal | Yes; it calls a fixed LLM | The model call is not retried automatically |
-| Design “Confirm and generate” | Yes; media generation | Exactly one billed POST, no automatic retry |
-| Design task status read | Normally read-only | Transient failures may use bounded retries |
-| A Modellix LLM call in Harness | Yes | Provider retry limit is `0` |
-| `web_search` / `web_fetch` | Possibly | A user or agent should not automatically repeat a sensitive operation after an unknown outcome |
+- Dialogs have visible titles, dialog semantics, initial focus, focus trap, background inertness, and focus restoration.
+- The required Credential gate cannot disappear through Escape/backdrop/X; **Configure later** is always keyboard reachable.
+- Inputs use real labels and linked help/error text.
+- Busy and invalid states are exposed through ARIA.
+- Result tabs support Arrow/Home/End behavior.
+- Pointer targets are at least 24×24 CSS px and expand to 48×48 for coarse pointers.
+- Light, dark, forced-colors, reduced-motion, 320/560/768/1440 widths, and 200% text scaling are supported.
 
-Before every generation, review model, parameters, count, and account-side pricing. Prefer no-cost read APIs during real validation. An operator must explicitly trigger any billed E2E call.
+## 13. Troubleshooting
 
-Use only an empty Key or an explicitly fake Key in security reports and documentation screenshots. Do not rely on blurring a captured real Secret later. If a real Key is ever captured, discard the image and rotate the Key under the incident process.
+### Modellix Design is missing
 
-## Troubleshooting
+Confirm Design is enabled, inspect `dsh --profile web --dump-config`, and fully restart the profile after a plugin update.
 
-### The first-time setup dialog did not appear
+### The Agent does not use Web automatically
 
-- A local or environment Credential may already exist; inspect Modellix settings.
-- You may have selected Configure later. Configure directly in settings, or explicitly open an enabled Modellix capability to create a new recovery request.
-- If settings itself failed to load, use Retry in the dialog and inspect the Harness Host connection.
+Confirm Web is enabled and the current Agent session contains the `Web routing` context. The explicit tools should appear as `modellix_web_search` and `modellix_web_fetch`.
 
-### Design has no models
+### A model Schema is reported as unavailable
 
-1. Confirm that the Design switch was saved as enabled.
-2. Confirm that a Credential is configured and not in 401 invalid state.
-3. Select “Refresh models.”
-4. Check Host network access to Modellix over HTTPS.
-5. If the catalog works but one model cannot submit, its Schema may not be supported; select another model.
+Refresh the live media catalog, verify the exact model slug returned by `modellix_media_list`, and read `modellix_media_schema` again. The parser supports documented OpenAPI layouts and bounded shared references; it blocks unsafe or unsupported contracts instead of guessing.
 
-### “Confirm and generate” is unavailable
+### A task never updates
 
-Check for a missing Key, disabled Design, unavailable model, empty required field, JSON syntax error, Schema constraint violation, or a blocking unsupported Schema structure. The UI displays a nearby reason while the action is unavailable.
+Keep the conversation open long enough for the Client watcher, verify the Credential epoch has not changed, and inspect the right panel. Do not submit a replacement merely because an immutable assistant sentence looks old; current status belongs to the card/panel.
 
-### A parameter proposal cannot be applied
+### Two cards represent one task
 
-- Resolve conflicts shown in the proposal card first.
-- If you edited parameters after creating the proposal, reject the old proposal and create another.
-- If the Schema or model changed, refresh and enter the instruction again.
+This is not expected in `0.2.0`. Capture the two job ids and tool call ids without Secrets. The generation card should win the per-session task claim, and the matching result-query card should be suppressed.
 
-### A task stays Running or enters Diagnostics
+### Results from another conversation appear
 
-- A 429, network failure, or 5xx lets safe read-only polling continue later, with a diagnostic in the UI.
-- Repeated read failures can reach the polling bound; after connectivity returns, reopen or refresh the view.
-- Replacing the Key can stop refresh for a task from an older Credential epoch.
-- Do not click the billed generation action again merely because the page did not update immediately.
+This is not expected for new `0.2.0` tasks. Record the affected session/task ids and report it as a session-isolation defect.
 
-### A completed result is missing
+### Media cannot play
 
-Check whether the task is under Diagnostics, whether the resource expired, and whether the upstream URL remains available. The plugin stores no media copy and cannot recover an expired resource.
+Confirm the result is Succeeded, the upstream URL has not expired, and the browser can reach the file origin. Failed or running tasks intentionally have no player.
 
-### An LLM model is absent from the selector
+## 14. Screenshot catalog
 
-Confirm the LLM switch and Key, inspect catalog health in settings, and refresh manually. After successful materialization, reopen the Harness model selector. There is no fabricated fallback catalog after a catalog failure.
+All twelve official captures are 1920×1080 and come from real English or Chinese UI sessions:
 
-### Web Tools are unavailable
+| English screenshot | What it proves |
+| --- | --- |
+| `settings-ready-en.webp` | Write-only Credential status, enabled services, live catalog |
+| `chat-media-generation-en.webp` | One completed image card in chat |
+| `design-results-drawer-en.webp` | Session-scoped image/video/audio result list |
+| `media-players-en.webp` | Real video/audio preview controls |
+| `llm-model-selector-en.webp` | Live Modellix models in Harness |
+| `web-tools-auto-en.webp` | Automatic explicit Search and Fetch |
 
-Confirm that the Web switch was saved, the Credential is usable, and `dsh --profile web --dump-config` selects `modellix` for Search/Fetch. Restart the profile after updating the Bundle.
+No screenshot contains a real Key, Network request, HAR, Console output, Credential file, cookie, or browser storage.
 
-### An environment Key cannot be changed in the UI
+## 15. Acceptance and release
 
-This is expected. The environment source is read-only. Update `MODELLIX_API_KEY` in the external Harness launch environment or secret manager, then restart Harness.
+Use [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) for the step-by-step manual acceptance and evidence requirements. The Chinese equivalent is [../zh-CN/RELEASE_CHECKLIST.md](../zh-CN/RELEASE_CHECKLIST.md).
 
-## Uninstallation
+## 16. Uninstall
 
-1. For a local writable Credential, select “Remove API Key” in Modellix settings first.
-2. For an environment source, revoke `MODELLIX_API_KEY` in the external launch environment or secret manager.
-3. Remove the plugin from the target profile and inspect the configuration:
+Remove a writable local Key in Modellix settings, or revoke an environment Key externally. Then:
 
 ```sh
 dsh plugin --profile web remove dsh-modellix
@@ -505,42 +318,11 @@ dsh --profile web --dump-config
 dsh --profile web
 ```
 
-4. Confirm that `--dump-config` no longer contains the `dsh-modellix` Bundle layer or `modellix` plugin row.
-
-Uninstallation does not promise to delete upstream Modellix tasks, external environment variables, or every piece of persisted Harness data. If your organization requires complete cleanup, inspect Credential storage, Harness profile data, and Modellix account records separately.
-
-## Current limitations
-
-- The natural-language parameter assistant modifies only fields declared by the current Schema; it does not run an open-ended agent workflow.
-- There is no upstream cancellation API, and the UI has no generation cancellation button.
-- Results are upstream URLs plus task metadata, not a permanent local media library.
-- An unsupported complex Schema blocks submission instead of guessing or silently dropping constraints.
-- LLM depends on the live catalog and provides no fabricated model when the catalog is unavailable.
-- Web uses the native Harness Tool seam; the plugin has no duplicate custom Tool UI.
-
-## Included screenshots and safe-capture checklist
-
-These images were captured in an isolated acceptance profile and checked for Secrets. Most plugin copy is Chinese; `design-mobile-en.webp` and `llm-model-selector.webp` use English Harness chrome, while `web-tools.webp` uses English Harness chrome around a Chinese public-documentation request and response. Both guides reuse the same safe set with language-appropriate alt text:
-
-| Suggested file | Alt text | Capture focus |
-| --- | --- | --- |
-| `docs/assets/onboarding-defaults.webp` | Chinese-language Modellix first-time setup dialog with an empty API Key field and Design, LLM, and Web switches enabled | Empty password field, three default switches, Configure later and Save actions |
-| `docs/assets/settings-ready.webp` | Chinese-language Modellix settings showing a verified Credential, three feature switches, and LLM catalog status | Show configured status only, never the Key |
-| `docs/assets/design-desktop.webp` | Chinese-language Modellix Design desktop layout with model, prompt, and parameters on the left and generation results on the right | 1440px, generic prompt, non-sensitive result |
-| `docs/assets/design-proposal.webp` | Chinese-language Design parameter proposal showing before-and-after changes with Apply and Reject actions | No personal data; make clear that a proposal does not generate automatically |
-| `docs/assets/design-results-media.webp` | Chinese-language Design results pane showing the image created during real acceptance, its expiry, and download action | The image uses a public test prompt; video and audio passed separate real API acceptance and are not mixed into this screenshot |
-| `docs/assets/design-mobile-en.webp` | English-language Modellix Design in a single-column layout at 320 pixels with the workspace above Results | 320px, longest English copy, no clipped key action, and visible English localization |
-| `docs/assets/credential-recovery.webp` | Chinese-language Modellix recovery dialog after an invalid API Key with an empty field and Configure later action | Simulated 401 only; never show a real Key |
-| `docs/assets/llm-model-selector.webp` | English-language Harness model selector expanded to the Modellix provider with models synchronized from the live catalog | Show only public model names, with no account or call content |
-| `docs/assets/web-tools.webp` | English-language Harness conversation showing native web_search and web_fetch completed for a Chinese public-documentation request | Use public documentation; do not show private URLs, Cookies, or request details |
-
-These screenshots show only an empty Key, an explicitly fake Key, public model names, public URLs, and generic test prompts. The real Key was read directly by the acceptance process and never entered the browser, screenshots, Network/HAR, Console, Credential files, or persistent recordings. Future screenshot updates must preserve the same rule.
+Uninstallation does not delete upstream tasks, external environment variables, or every Harness profile artifact.
 
 ## References
 
-- [English README](../../README.md)
-- [Chinese README](../../README.zh-CN.md)
+- [README](../../README.md)
 - [Modellix getting started](https://docs.modellix.ai/get-started)
-- [Modellix LLM overview](https://docs.modellix.ai/llm/overview)
-- [Modellix GPT Image 2 example](https://www.modellix.ai/zh_CN/models/openai/gpt-image-2)
+- [Modellix model catalog](https://www.modellix.ai/models)
 - [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)