dsh-modellix 0.1.1 → 0.2.1

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.1` 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.
+- DeepSeek Harness `0.1.2-alpha.4` (latest supported); `0.1.1-rc.2` remains supported
+- 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,466 +20,301 @@ 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.1.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.1" },
-  "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"
-  }
-}
+dsh plugin --profile web add ./dsh-modellix-0.2.1.tgz
 ```
 
-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.1" },
-  "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
-```
-
-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
-
-When the plugin has no usable Credential and setup has not been deferred, the Harness Web UI displays the “Connect Modellix” dialog.
-
-
-### Standard flow
-
-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.
-
-Use the “Show API Key / Hide API Key” button to inspect only the current unsaved draft. The button cannot read a stored Credential.
-
-### Configure later
-
-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 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.
-
-A mandatory Credential dialog cannot close implicitly through Escape or the backdrop, but “Configure later” remains visible and keyboard accessible.
-
-## Credential sources and security
+See [LOCAL_USAGE.md](LOCAL_USAGE.md) for isolated-profile setup and update commands.
 
-### Two sources
+## 2. Connect Modellix
 
-| 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 |
+### First-time flow
 
-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.
+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.
 
-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.
+The stored Key is write-only. After save, the UI displays status and source but never returns the Key to the Client.
 
-### Security boundary
+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.
 
-- 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.
+### Environment Credential
 
-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.
+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.
 
-## Modellix settings
+### Secret handling
 
-![English Modellix settings in a real Harness session showing a verified local Credential, three feature switches, and the live LLM catalog](../assets/settings-ready-en.webp)
+Never place a real Key in:
 
-The settings page has three primary cards.
+- 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.
 
-### API Key
+## 3. Understand the current interface
 
-The status area shows both Credential source and verification state:
+![English Modellix settings with a configured Credential and live model catalog](../assets/settings-ready-en.webp)
 
-- “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.
+The plugin adds:
 
-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.
+- 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.
 
-An environment-sourced Key cannot be replaced or removed in the UI.
+It does not add a standalone Design tab.
 
-### Feature switches
-
-Design, LLM, and Web can be toggled independently. You must select “Save changes” before an edit takes effect:
-
-- 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.
-
-Disabling a feature does not delete existing upstream tasks, account data, or an external Key.
+### Right-side panel
 
-### LLM model catalog
+- 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.1`.
 
-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.
+## 4. Create media by chatting
 
-A catalog refresh failure does not create a static replacement list or misreport a 402, 429, network failure, or 5xx as an invalid Key.
+Ordinary users should describe the desired work in natural language. The Agent selects tools and models according to the conversation.
 
-## Design: image, video, and audio generation
+### New text-to-image request
 
-### Left/right layout
+Example:
 
-![English Modellix Design desktop layout in a real Harness session, with live model parameters on the left and results on the right](../assets/design-desktop-en.webp)
+> 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.
 
-Design uses a “conversation and parameters on the left, results on the right” two-column layout on desktop:
+If the user names a model or exact fields, the Agent still checks the live Schema before submission.
 
-- 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.
+### Continue from the previous work
 
-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.
+Example:
 
-### Select a model
+> 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.
 
-Design uses the current Modellix catalog instead of a static list assumed to remain valid forever.
+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.
 
-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.
+### Use a local file or attachment
 
-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 |
+When the live Schema needs an HTTP(S) media URL, the Agent can call `modellix_media_upload_file` for:
 
-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.
+- a current-session attachment; or
+- a regular, non-symlink file inside the session workspace.
 
-### Three editing methods
+An upload is not automatically replayed if the outcome is unknown.
 
-#### 1. Enter only a prompt
+### Generate voice
 
-For a model such as GPT Image 2 whose public Schema supplies the other defaults, the common path is:
+Example:
 
-1. Select the model.
-2. Enter a prompt.
-3. Review the default parameters.
-4. Select “Confirm and generate.”
+> 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.”
 
-The live model Schema always determines actual required fields. This guide does not assume that every model needs only a prompt.
+The Agent must use a Schema-published voice and parameter format instead of translating or guessing enum values.
 
-#### 2. Edit exact parameters
+## 5. Media tools and routing
 
-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:
+| 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 |
 
-- 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.
+The Agent routing context is injected only while Design is enabled. Disabling Design removes these tools from model visibility.
 
-![English real Design parameter proposal showing Schema-valid before-and-after values with Apply and Reject actions](../assets/design-proposal-en.webp)
+## 6. Result cards and status
 
-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.
+![A completed real image displayed directly in the English chat history](../assets/chat-media-generation-en.webp)
 
-### Worked Design example: a premium cliffside library
+### Running
 
-Use this as a reproducible image-generation pattern, while treating the selected model's live Schema as authoritative:
+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.
 
-| 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` |
+### Succeeded
 
-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.
+The existing card updates in place and exposes:
 
-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.
+- **Preview** and **JSON** tabs;
+- image enlargement, video playback, or audio playback;
+- **Add URL to chat**;
+- **Download**.
 
-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 corresponding one-shot result query is suppressed when the generation card already owns the same job. This prevents two identical cards.
 
-### Confirmation and one-shot billed submission
+### Failed
 
-“Confirm and generate” starts the actual media generation and may incur a charge. Before submitting, confirm that:
+The card remains concise and shows the failure state/diagnostic. Preview and JSON are not presented as if a successful resource existed.
 
-- 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.
+### Session ownership
 
-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.
+Every new task records the Harness session id. Chat cards and the drawer read the same session controller, so:
 
-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.
+- 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.
 
-### Results, previews, and expiry
+### Expiry and storage
 
-![English Design results pane showing the real 1536 by 1024 image, its expiry, enlargement, and download actions](../assets/design-results-media-en.webp)
+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.
 
-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:
+## 7. Use the Modellix Design panel
 
-- 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 English right-side panel showing image, video, and audio results from one session](../assets/design-results-drawer-en.webp)
 
-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.
+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.
 
-Result URLs are upstream Modellix resources:
+## 8. Preview media
 
-- 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.
+![A real five-second image-to-video result playing in chat and in the session panel](../assets/media-players-en.webp)
 
-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.
+### Images
 
-## LLM: synchronize and switch models
+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.
 
-LLM reuses the same Key and does not require a separate Credential per model.
+### Video
 
-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.
+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.
 
-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.
+### Audio
 
-![English Harness model selector expanded to the Modellix provider with models synchronized from the live catalog](../assets/llm-model-selector-en.webp)
+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.
 
-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:
+## 9. Use Modellix LLM models
 
-- provider id: `modellix`;
-- OpenAI Completions-compatible protocol;
-- base URL: `https://llm.modellix.ai/v1`;
-- default input: text;
-- plugin-layer automatic retries: `0`.
+![The English Harness model selector populated from the live Modellix catalog](../assets/llm-model-selector-en.webp)
 
-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.
+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.
 
-## Web: native search and fetch
+The provider endpoint is OpenAI-compatible. Provider retries are `0`; unavailable catalog data does not produce fake model entries.
 
-When Web is enabled and a Credential is usable, the plugin registers:
+## 10. Automatic Web Search and Fetch
 
-- the Modellix Search provider for native `web_search`;
-- the Modellix Fetch provider for native `web_fetch`.
+![An English Agent turn automatically using Modellix Search and Fetch for official documentation](../assets/web-tools-auto-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.
+Ask the question normally. For example:
 
-![English Harness chrome showing real Modellix Search and Fetch results for public official documentation](../assets/web-tools-en.webp)
+> 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.
 
-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.
+Expected flow:
 
-## States, errors, and 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.
 
-| 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 |
+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. When Modellix Web is enabled, its routing context prevents duplicate calls to both tool families for the same operation. When it is disabled, the two explicit Modellix tools and that routing context are removed; the profile's native `web_search` / `web_fetch` tools and providers remain available for automatic fallback.
 
-### Credential recovery flow
+## 11. Settings and errors
 
-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.
-
-A 402, 429, offline failure, timeout, or 5xx remains distinct and does not open invalid-Key recovery.
+### Feature switches
 
+- **Design:** controls media tools, chat result views, and the result panel.
+- **LLM:** controls live Modellix model materialization.
+- **Web:** controls only the explicit Modellix Search/Fetch tools and Modellix-first routing. It does not change Harness-native Web tools or providers.
 
-## Accessibility, keyboard, and responsive behavior
+The three switches are independent. Saving one service change does not register, unregister, or reconfigure either of the other two services.
 
-### Keyboard interaction
+### Credential status
 
-- 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.
+Only HTTP 401 is an invalid Credential. Other cases remain distinct:
 
-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.
+| 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 |
 
-### Display and touch
+Concurrent 401 responses open only one Credential dialog. Settings always retains a replace-Key action where the Credential is writable.
 
-- 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.
+Routine UI operations do not show a payment warning. Users with a required Modellix Key can review consumption and details in Modellix.
 
+## 12. Accessibility and responsive checks
 
-## Cost and security checklist
+- 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.
 
-Distinguish reads from actions that may incur usage:
+## 13. Troubleshooting
 
-| 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 |
+### Modellix Design is missing
 
-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.
+Confirm Design is enabled, inspect `dsh --profile web --dump-config`, and fully restart the profile after a plugin update.
 
-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.
+### The Agent does not use Web automatically
 
-## Troubleshooting
+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`.
 
-### The first-time setup dialog did not appear
+If Web is intentionally disabled, neither explicit tool should appear and the session should not contain Modellix `Web routing`; native `web_search` / `web_fetch` behavior continues according to the active Harness profile.
 
-- 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.
+### A model Schema is reported as unavailable
 
-### Design has no models
+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.
 
-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.
+### A task never updates
 
-### “Confirm and generate” 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.
 
-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.
+### Two cards represent one task
 
-### A parameter proposal cannot be applied
+This is not expected in `0.2.1`. 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.
 
-- 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.
+### Results from another conversation appear
 
-### A task stays Running or enters Diagnostics
+This is not expected for new `0.2.1` tasks. Record the affected session/task ids and report it as a session-isolation defect.
 
-- 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.
+### Media cannot play
 
-### A completed result is missing
+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.
 
-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.
+## 14. Screenshot catalog
 
-### An LLM model is absent from the selector
+All twelve official captures are 1920×1080 and come from real English or Chinese UI sessions:
 
-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.
-
-### 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
@@ -502,39 +322,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 six English images were captured full-screen at 1920×889 from the real configured Harness profile and checked for Secrets. The Chinese guide uses a separate six-image Chinese set of the same workflows. The live session exercised the real Modellix catalog, parameter assistant, `gpt-image-2`, LLM, Search, and Fetch:
-
-| Suggested file | Alt text | Capture focus |
-| --- | --- | --- |
-| `docs/assets/settings-ready-en.webp` | English Modellix settings with a verified Credential and live LLM catalog | Shows status and source only, never the stored Key |
-| `docs/assets/design-desktop-en.webp` | English Modellix Design two-pane workspace using the live `gpt-image-2` Schema | Full-screen desktop layout and public model names |
-| `docs/assets/design-proposal-en.webp` | English real parameter proposal with Reject and Apply actions | A billed LLM proposal that does not submit media |
-| `docs/assets/design-results-media-en.webp` | English result pane with the real 1536×1024 acceptance image | One billed image POST, visible expiry, enlargement, and download actions |
-| `docs/assets/llm-model-selector-en.webp` | English Harness model selector populated from the live Modellix catalog | Public model names only |
-| `docs/assets/web-tools-en.webp` | English Harness chrome with real Modellix Search and Fetch results | Public official documentation only; no request internals |
-
-The Credential was already stored write-only in the local Harness service. The capture process never read it or opened a request inspector, and no Key, Network/HAR, Console, Credential file, Cookie, or private URL appears in these screenshots. 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)