@rockysoft/opencode-hybrid-workflow 0.3.2-beta.1 → 0.3.2-beta.3

package/README.md

@@ -1,252 +1,167 @@
 # OpenCode Hybrid Workflow
 
-One OpenCode 2 package for premium planning/design/reviews, implementation
-checkpoints, specialist instructions and reviewer usage/cost cards in the sidebar.
-No dashboard process, trial launcher or project-local plugin folder is required.
+Let your strongest models plan, design and review. Let your implementation model build.
 
-**Public beta:** Windows and Linux checks pass. macOS support is implemented,
-but a real Mac installation/UI run is still pending. Requires **OpenCode 2**
-(tested with 2.2.5), Node.js 22+, Git and Python 3. OpenCode 1 is not supported.
+One plugin. One or two reviewers. Configure everything inside OpenCode.
 
-## Install once
+**Requirements:** OpenCode 2, Node.js 22+, Git and Python 3. Windows and Linux; experimental macOS support.
 
-In your terminal, with OpenCode 2 installed:
+## 1. Install
 
 ```sh
 opencode plugin add @rockysoft/opencode-hybrid-workflow@beta
 ```
 
-Then open OpenCode in any project and complete **Hybrid setup**. Configure
-providers, reviewers and optional tools inside OpenCode. Existing running
-sessions are not restarted; reopen OpenCode when ready to load the plugin.
+![Install the plugin from npm](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/01-install.png)
 
-To update the beta later:
+Open `opencode` in your project. The setup wizard opens automatically.
 
-```sh
-opencode plugin update @rockysoft/opencode-hybrid-workflow@beta
-```
+## 2. Choose your reviewers
 
-These commands use OpenCode's global package plugin manager. No separate npm
-global install or `opencode-hybrid init` is needed for a new installation.
-If you used a previous local/archive build, remove its plugin entries from
-both `opencode.json` and `cli.json` before adding the npm package, preserving
-`hybrid/config.json`, managed instructions and runtime history. Do not load the
-local and npm builds together.
-
-## Set up inside OpenCode
-
-Once the plugin is installed, open OpenCode normally in any project. On first
-launch, **Hybrid setup** opens automatically. Choose one or two reviewers, their
-OpenCode-connected providers or external CLIs, models, reasoning effort and the
-planning/design lead, then save. The plugin installs its managed agents, rules
-and design skills globally. Canceling the wizard does not save reviewer choices.
-
-Later, click **Hybrid Workflow settings** on the home screen or session sidebar,
-or select it in OpenCode's command palette. `/hybrid` opens the same menu.
-There is no separate configuration terminal or dashboard to launch.
-
-The menu includes:
-
-- **Reviewers and design lead**: one or two reviewers; any enabled tool-capable
-  OpenCode provider/model, or the optional Codex/Claude CLI adapters.
-- **Connect provider** and **Implementation model**: open OpenCode's own menus.
-- **Reviewer browser**: enable an existing browser, or install managed Playwright
-  MCP and Firefox with one confirmation. Each reviewer gets an isolated browser.
-- **Tools and dependencies**: install managed pnpm for verification; enable the
-  official Context7 documentation MCP while preserving an existing configuration.
-- **Run diagnostics**: inspect prerequisites, reviewer configuration/logins,
-  design skills and an actual browser launch without spending model tokens.
-
-Settings apply globally. New tasks pick up saved reviewers; active tasks retain
-their assignments and history. Changing the installed plugin version still needs
-a normal OpenCode restart. Installing an implementation MCP may also require a
-restart if the host does not reload its MCP configuration.
-
-The same npm installation works on Windows, macOS and Linux. `configure`,
-`doctor` and `browser` CLI commands are optional automation/support tools,
-not the routine setup workflow. Publishing on npm does not imply inclusion
-in a curated OpenCode marketplace.
-
-OpenCode's plugin manager does not put `opencode-hybrid` on your terminal PATH.
-For the optional CLI examples below, replace `opencode-hybrid` with
-`npx --package @rockysoft/opencode-hybrid-workflow@beta opencode-hybrid`, or
-install the package globally if you specifically want its standalone CLI.
-Routine setup and diagnostics remain available inside OpenCode.
-
-Machine prerequisites are OpenCode 2, Node 22+, Git and Python 3 for design
-research. pnpm and browser support have installers in the menu. External CLI
-choices require that CLI and its official account sign-in. Provider credentials
-remain with OpenCode or the official CLI; the plugin never copies them.
-
-Ask normally. The package supplies workflow instructions and tool gates. Specialist
-agents inherit the implementation model. New UI/UX decisions go to the configured
-design lead and reviewers; existing/supplied patterns can be implemented faithfully. Existing-app
-visual redesigns skip unrelated architecture planning. New applications and
-substantive architecture changes receive premium planning first. Premium planners
-own material structural choices; native fullstack-architect gathers facts/options,
-and implementation specialists follow the approved plan. New material choices
-return to planning before dependent edits. Subsequent
-reviews focus on actual corrections and affected dependencies. Approval requires
-all configured current-artifact reports, at least one pass, and no open medium/high/critical
-findings. There are no artificial line, screenshot, correction or call quotas.
-
-The sidebar follows the current project, shows input/output/cache tokens and USD
-API-equivalent costs when a known model rate is available. Unknown pricing is
-unavailable, not zero. Clear totals changes only the display baseline; reports,
-findings and approvals remain intact. No fixed local port or HTTP service is used.
-
-## Configuration
-
-Both CLI and OpenCode-provider reviewers can independently inspect the running
-app with Playwright. Configure this through **Hybrid Workflow settings > Reviewer
-browser**. Installing browser support downloads a pinned Playwright MCP package
-and Firefox into plugin-managed tooling, then enables isolated headless sessions.
-The existing implementation MCP entry is preserved. Existing browser commands can
-also be enabled without downloading replacements.
-
-Advanced settings live in `reviewBrowser` in `hybrid/config.json`: `command`,
-`browser` (chrome/msedge/firefox/webkit), and `headless`. The CLI browser commands
-remain available for scripted administration.
-
-All reviewer adapters can navigate, inspect DOM, resize, click,
-fill test forms, evaluate page JavaScript, inspect console/network information,
-and capture screenshots. Output goes to that review's `browser-artifacts`; tool
-names are logged in `actions.jsonl`. This is not desktop control or the user's
-signed-in browser. Source edits, server startup, local-file upload and arbitrary
-host-code execution remain unavailable; Codex retains read-only shell inspection
-of evidence, while Claude uses its read tools. Browser interactions can still mutate application
-data: use a disposable test environment and synthetic data. Reviewers are told
-to inspect relevant states directly and distinguish live observations from the
-frozen source artifact. Supply the actual app URL in checkpoint checks and keep
-the development/test server running. Browser access does not authorize a reviewer
-to start/restart the app server.
-
-OpenCode-provider reviewers use the internal `hybrid_browser` tool for the same
-isolated Playwright access. Each call has its own browser process, started only
-when needed and closed before the review completes. Browser sessions are never
-shared between reviewers or inherited from the implementation agent. Vision-capable
-models receive actual image pixels; text-only models cannot approve visual evidence.
-
-`opencode-hybrid config` prints the configuration location, normally
-`~/.config/opencode/hybrid/config.json`. `OPENCODE_CONFIG_DIR`,
-`OPENCODE_HYBRID_CONFIG` can choose another user-owned location from your launcher.
-Plugin `options.configFile` must match that trusted location; a project cannot
-redirect reviewer executable settings to its own file. The installer supports
-`--config-dir PATH` for a separate profile.
-Do not put credentials in this file; OpenCode or the selected official CLI owns authentication.
-
-`opencode-hybrid configure` opens an interactive selector: choose one or two
-reviewers, OpenCode provider or external CLI for each, model, supported variant/CLI effort, and the
-planning/design lead. Either slot can use any supported adapter, including two
-OpenCode models, two CLI models, or one of each. `opencode-hybrid models` lists the
-enabled tool-capable models from your OpenCode provider catalog. Any enabled
-provider is eligible; Copilot is an ordinary catalog provider, not a special adapter. No local model
-server, GPU setup, Strata launcher or model download is managed by this package.
-
-Noninteractive examples (use actual IDs returned by `models`):
+Select **one** reviewer or **two** for independent planning and review.
 
-```sh
-opencode-hybrid configure --reviewer1 codex-cli:gpt-6-astra --reviewer2 claude-cli:opus --variant1 high --variant2 high
-opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 none
-opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 claude-cli:opus --variant1 SUPPORTED_VARIANT
-```
+![Choose one or two reviewers](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/02-reviewers.png)
 
-```json
-{
-  "version": 1,
-  "reviewers": {
-    "astra": { "adapter": "codex-cli", "model": "gpt-6-astra", "effort": "high", "executable": "codex" },
-    "opus": { "adapter": "claude-cli", "model": "opus", "effort": "high", "executable": "claude" }
-  },
-  "verification": { "executable": "pnpm", "timeoutMs": 0 },
-  "reviewTimeoutMs": 0
-}
-```
+## 3. Pick a connection, model and effort
+
+Use any connected OpenCode provider, or your Codex/Claude CLI login. Each reviewer can use a different connection.
+
+![Choose a reviewer connection](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/03-connection.png)
+
+<details>
+<summary><strong>OpenCode provider — see every step</strong></summary>
+
+**Choose your provider.**
+
+![Choose a connected provider](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/04-provider.png)
+
+**Choose a model.** Type to search. Models shown depend on your connections.
+
+![Choose a reviewer model](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/05-model.png)
+
+**Choose reasoning effort.** Options come from the selected model.
+
+![Choose reasoning effort](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/06-effort.png)
+
+Repeat for reviewer 2 if enabled.
+
+</details>
+
+<details>
+<summary><strong>External CLI — see every step</strong></summary>
+
+**Choose Codex CLI or Claude Code CLI.** Install and sign into that CLI first.
+
+![Choose the external CLI](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/18-cli.png)
+
+**Select a model by name.** Models and effort levels come from your installed CLI. Custom IDs are an advanced option.
+
+![Select a CLI model by name](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/19-cli-model.png)
+
+Claude Code shows its own model list:
+
+![Select a Claude model by name](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/21-claude-model.png)
+
+**Choose effort.** Use a level supported by that CLI and model.
+
+![Choose CLI reasoning effort](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/20-cli-effort.png)
+
+</details>
+
+<details>
+<summary><strong>Need to connect a provider?</strong></summary>
+
+Cancel the wizard, choose **Connect provider**, and complete OpenCode's sign-in flow. Then reopen **Complete setup**.
+
+![Connect a provider through OpenCode](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/15-connect-provider.png)
+
+</details>
+
+## 4. Choose the lead and save
+
+With two reviewers, choose who leads planning and design.
+
+![Choose the planning and design lead](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/07-design-lead.png)
+
+Confirm your choices. They apply across projects; active tasks keep their assigned reviewers.
 
-`astra` and `opus` are stable storage-slot IDs, not provider restrictions. Set the
-second slot to `null` for one reviewer. An OpenCode slot has
-`{"adapter":"opencode","providerID":"...","model":"...","variant":"..."}`;
-omit `variant` for the provider default. There is no invented universal effort
-mapping. `designAuthor` selects `astra` or `opus`; default is the last enabled slot.
-Legacy defaults remain Codex/Astra and Claude/Opus, both high effort; first-run
-setup asks for explicit choices and initially highlights OpenCode providers.
-
-Native reviewers run in read-only OpenCode child sessions with only frozen
-evidence, public-documentation tools and the optional isolated browser. They cannot edit source, delegate or
-recursively start checkpoints. Image reviews require an image-capable model.
-Unknown/disabled models, unsupported variants and invalid reports fail explicitly;
-there is no provider fallback. Provider context limits still apply.
-
-Reviewer assignments are pinned for an active task; changing defaults affects
-the next task without restarting OpenCode. Existing findings are retained. One
-reviewer must pass with no medium-or-higher findings; it does not claim independent
-cross-model agreement. With two, both reports must complete and neither may have
-an unresolved medium-or-higher finding. Low/info suggestions do not block a pass.
-
-Installation merges plugin entries into `opencode.json` and `cli.json`, installs
-nine specialist definitions and the three design skills, and adds a managed rules
-file. Existing custom agent/skill files are preserved and reported. Other settings,
-permissions and implementation-model choices are retained. JSONC is accepted;
-comments are removed from the rewritten file, with an exact original backup.
-Updates replace only unchanged package-managed instruction files. It does not
-import personal project memories or modify Claude/Codex global rules.
-
-## Storage and existing sessions
-
-New state lives outside both the package and project: Windows uses
-`%LOCALAPPDATA%/opencode-hybrid/runtime`, other platforms use
-`$XDG_DATA_HOME/opencode-hybrid/runtime` or `~/.local/share/opencode-hybrid/runtime`.
-Projects are isolated by canonical path. Checkpoints are project-scoped; concurrent
-conversations editing the same project must coordinate against the same gate.
-Opening a subfolder of a Git repository asks you to open its root.
-
-To retain a trial project's exact existing history without copying/resetting it:
+![Save the reviewer setup](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/08-save.png)
+
+## 5. Choose who builds
+
+Open **Implementation model** and select your coding model. It follows the approved plan and design.
+
+![Choose the implementation model](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/17-implementation.png)
+
+## 6. Start working
+
+Ask OpenCode for your feature or redesign. Reviewers handle planning and new design decisions; the implementation model builds and addresses review findings.
+
+Continue when at least one reviewer passes and no reviewer has unresolved medium, high or critical findings.
+
+Type **`/hybrid`** or click **Hybrid Workflow settings** whenever you want to change the setup.
+
+![Hybrid Workflow settings](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/09-settings.png)
+
+<details>
+<summary><strong>Reopen settings with /hybrid</strong></summary>
+
+![Open settings from the command prompt](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/16-reopen.png)
+
+</details>
+
+## Optional tools
+
+<details>
+<summary><strong>Let reviewers inspect your app in a browser</strong></summary>
+
+Choose **Reviewer browser → Install browser support**.
+
+![Reviewer browser options](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/10-browser.png)
+
+Confirm installation of Playwright and Firefox.
+
+![Confirm browser installation](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/11-browser-confirm.png)
+
+Each reviewer gets an isolated browser. Run your app and provide its URL; use test data.
+
+![Browser support installed](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/12-browser-ready.png)
+
+</details>
+
+<details>
+<summary><strong>Install pnpm or enable Context7 documentation</strong></summary>
+
+Open **Tools and dependencies** and select what you need.
+
+![Tools and dependencies](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/13-tools.png)
+
+</details>
+
+<details>
+<summary><strong>Check your setup</strong></summary>
+
+Choose **Run diagnostics**. Select any row for details. This does not call a model.
+
+![Setup diagnostics](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/images/14-diagnostics.png)
+
+</details>
+
+## Usage and updates
+
+The sidebar shows reviewer input, output, cache tokens and costs at known API rates. These are not subscription charges. **Clear totals** resets the display, not review history.
 
 ```sh
-opencode-hybrid init --legacy-config /path/to/old/config.json --project /path/to/project
+opencode plugin update @rockysoft/opencode-hybrid-workflow@beta
 ```
 
-Only that project receives a runtime override; new projects use portable storage.
-OpenCode conversation history is separate. Sessions created under an isolated
-`XDG_DATA_HOME` remain in that profile; installation does not move them. Existing
-trial profiles stay usable. Restart OpenCode to load changed modules; installation
-does not interrupt running sessions or restart model servers.
-
-## Validation and current limits
-
-The package targets Windows, macOS (Apple Silicon and Intel), and Linux. The same
-in-app setup is used on each platform; do not copy Windows executable paths or
-account credentials onto a Mac. On macOS it detects standard Homebrew locations,
-uses `python3`, and stores settings under `~/.config/opencode` and runtime data
-under `~/.local/share/opencode-hybrid` (or your XDG overrides). Browser and pnpm
-installers download the appropriate native platform binaries.
-
-macOS checkpoint exclusion uses a kernel-held advisory lock through Python 3,
-which is already a prerequisite for design research. The lock is released when
-the parent exits; the persistent `.mutex` file is normal and must not be deleted.
-Interrupted operation history and live-worker guards remain intact. This avoids
-stale Unix socket cleanup and macOS socket pathname-length problems.
-
-Validation: Windows and Linux execute the suite locally, including real POSIX
-crash/concurrency tests for the macOS lock adapter. Actual macOS execution is not
-yet verified here. `.github/workflows/compatibility.yml` is ready to run both
-Apple Silicon (`macos-15`) and Intel (`macos-15-intel`) tests plus actual OpenCode
-host integration once this package is placed in its own GitHub repository.
-It has not been pushed or run on hosted Mac runners. A Mac installation can also
-use **Hybrid Workflow settings > Run diagnostics** for prerequisite/browser checks.
-
-OpenCode 2 plugin hooks are checked at activation; patch versions are not pinned.
-
-Run `npm test` in the source checkout for the controller, installer, isolation,
-evidence, process lifecycle and sidebar tests. Installation/host tests make no
-model calls. Passing these tests does not guarantee model compliance or visual
-quality. Third-party attribution is in `THIRD_PARTY_NOTICES.md`.
-
-Package development uses `npm install --legacy-peer-deps`, then `npm run build`.
-`npm pack` builds automatically. The archive contains a compiled Solid/OpenTUI
-sidebar because the host does not compile JSX inside `node_modules`; host runtime
-imports stay external. End users do not need Babel or a separate sidebar process.
-
-The original plugin code is MIT-licensed; bundled skills retain their own
-licenses as listed in `THIRD_PARTY_NOTICES.md`. Authenticate providers on each
-machine rather than copying account credentials.
+Reopen OpenCode after updating.
+
+<details>
+<summary><strong>Moving from a local/archive installation</strong></summary>
+
+Remove the old plugin entries from `opencode.json` and `cli.json` before adding the npm package. Keep `hybrid/config.json` and runtime data to preserve settings and history.
+
+</details>
+
+[Advanced configuration](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/docs/configuration.md) · [MIT license](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/LICENSE) · [Third-party notices](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.3/THIRD_PARTY_NOTICES.md)

package/core/workers.mjs

@@ -29,7 +29,7 @@ export function workerArgs(who, config, folder, images = [], browser = null) {
     // implementation must be explicit too. Without it shell reads are denied.
     ...(process.platform === 'win32' ? ['-c', 'windows.sandbox="elevated"'] : []),
     '-c', 'approval_policy="never"',
-    '-c', `model_reasoning_effort="${lane.effort??'high'}"`, '-c', 'web_search="live"',
+    ...(lane.effort==='default'?[]:['-c', `model_reasoning_effort="${lane.effort??'high'}"`]), '-c', 'web_search="live"',
     ...(browser ? ['-c',`mcp_servers.review_browser.command=${JSON.stringify(browser.command)}`,
       '-c',`mcp_servers.review_browser.args=${JSON.stringify(browser.args)}`,
       '-c','mcp_servers.review_browser.startup_timeout_sec=60',
@@ -41,7 +41,7 @@ export function workerArgs(who, config, folder, images = [], browser = null) {
   return ['-p', ...(browser?['--setting-sources','','--disable-slash-commands','--settings','{"disableAllHooks":true,"enabledPlugins":{}}']:['--safe-mode']), '--restricted', '--strict-mcp-config', '--mcp-config', JSON.stringify({mcpServers:browser?{review_browser:browser}:{}}),
     '--no-chrome', '--no-session-persistence', '--permission-mode', 'dontAsk', '--permission-prompts', 'none',
     '--tools', 'Read,Glob,Grep,WebSearch,WebFetch', '--allowedTools', ['Read','Glob','Grep','WebSearch','WebFetch',...(browser?browserTools.map(name=>'mcp__review_browser__'+name):[])].join(','),
-    '--model', lane.model, '--effort', lane.effort??'high', '--output-format', 'stream-json', '--verbose',
+    '--model', lane.model, ...(lane.effort==='default'?[]:['--effort',lane.effort??'high']), '--output-format', 'stream-json', '--verbose',
     '--json-schema', JSON.stringify(resultSchema)];
 }
 

package/docs/configuration.md

@@ -0,0 +1,134 @@
+# Configuration reference
+
+Use Hybrid Workflow settings inside OpenCode for routine setup. These details are for advanced configuration and migration.
+
+For terminal commands below, use `npx --package @rockysoft/opencode-hybrid-workflow@beta opencode-hybrid` in place of `opencode-hybrid` unless you installed the standalone CLI globally.
+
+## Configuration
+
+Both CLI and OpenCode-provider reviewers can independently inspect the running
+app with Playwright. Configure this through **Hybrid Workflow settings > Reviewer
+browser**. Installing browser support downloads a pinned Playwright MCP package
+and Firefox into plugin-managed tooling, then enables isolated headless sessions.
+The existing implementation MCP entry is preserved. Existing browser commands can
+also be enabled without downloading replacements.
+
+Advanced settings live in `reviewBrowser` in `hybrid/config.json`: `command`,
+`browser` (chrome/msedge/firefox/webkit), and `headless`. The CLI browser commands
+remain available for scripted administration.
+
+All reviewer adapters can navigate, inspect DOM, resize, click,
+fill test forms, evaluate page JavaScript, inspect console/network information,
+and capture screenshots. Output goes to that review's `browser-artifacts`; tool
+names are logged in `actions.jsonl`. This is not desktop control or the user's
+signed-in browser. Source edits, server startup, local-file upload and arbitrary
+host-code execution remain unavailable; Codex retains read-only shell inspection
+of evidence, while Claude uses its read tools. Browser interactions can still mutate application
+data: use a disposable test environment and synthetic data. Reviewers are told
+to inspect relevant states directly and distinguish live observations from the
+frozen source artifact. Supply the actual app URL in checkpoint checks and keep
+the development/test server running. Browser access does not authorize a reviewer
+to start/restart the app server.
+
+OpenCode-provider reviewers use the internal `hybrid_browser` tool for the same
+isolated Playwright access. Each call has its own browser process, started only
+when needed and closed before the review completes. Browser sessions are never
+shared between reviewers or inherited from the implementation agent. Vision-capable
+models receive actual image pixels; text-only models cannot approve visual evidence.
+
+`opencode-hybrid config` prints the configuration location, normally
+`~/.config/opencode/hybrid/config.json`. `OPENCODE_CONFIG_DIR`,
+`OPENCODE_HYBRID_CONFIG` can choose another user-owned location from your launcher.
+Plugin `options.configFile` must match that trusted location; a project cannot
+redirect reviewer executable settings to its own file. The installer supports
+`--config-dir PATH` for a separate profile.
+Do not put credentials in this file; OpenCode or the selected official CLI owns authentication.
+
+`opencode-hybrid configure` opens an interactive selector: choose one or two
+reviewers, OpenCode provider or external CLI for each, model, supported variant/CLI effort, and the
+planning/design lead. Either slot can use any supported adapter, including two
+OpenCode models, two CLI models, or one of each. `opencode-hybrid models` lists the
+enabled tool-capable models from your OpenCode provider catalog. Any enabled
+provider is eligible; Copilot is an ordinary catalog provider, not a special adapter. No local model
+server, GPU setup, Strata launcher or model download is managed by this package.
+
+Noninteractive examples (use actual IDs returned by `models`):
+
+```sh
+opencode-hybrid configure --reviewer1 codex-cli:gpt-6-astra --reviewer2 claude-cli:opus --variant1 high --variant2 high
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 none
+opencode-hybrid configure --reviewer1 opencode:PROVIDER/MODEL --reviewer2 claude-cli:opus --variant1 SUPPORTED_VARIANT
+```
+
+```json
+{
+  "version": 1,
+  "reviewers": {
+    "astra": { "adapter": "codex-cli", "model": "gpt-6-astra", "effort": "high", "executable": "codex" },
+    "opus": { "adapter": "claude-cli", "model": "opus", "effort": "high", "executable": "claude" }
+  },
+  "verification": { "executable": "pnpm", "timeoutMs": 0 },
+  "reviewTimeoutMs": 0
+}
+```
+
+`astra` and `opus` are stable storage-slot IDs, not provider restrictions. Set the
+second slot to `null` for one reviewer. An OpenCode slot has
+`{"adapter":"opencode","providerID":"...","model":"...","variant":"..."}`;
+omit `variant` for the provider default. There is no invented universal effort
+mapping. `designAuthor` selects `astra` or `opus`; default is the last enabled slot.
+Legacy defaults remain Codex/Astra and Claude/Opus, both high effort; first-run
+setup asks for explicit choices and initially highlights OpenCode providers.
+
+Native reviewers run in read-only OpenCode child sessions with only frozen
+evidence, public-documentation tools and the optional isolated browser. They cannot edit source, delegate or
+recursively start checkpoints. Image reviews require an image-capable model.
+Unknown/disabled models, unsupported variants and invalid reports fail explicitly;
+there is no provider fallback. Provider context limits still apply.
+
+Reviewer assignments are pinned for an active task; changing defaults affects
+the next task without restarting OpenCode. Existing findings are retained. One
+reviewer must pass with no medium-or-higher findings; it does not claim independent
+cross-model agreement. With two, both reports must complete and neither may have
+an unresolved medium-or-higher finding. Low/info suggestions do not block a pass.
+
+Installation merges plugin entries into `opencode.json` and `cli.json`, installs
+nine specialist definitions and the three design skills, and adds a managed rules
+file. Existing custom agent/skill files are preserved and reported. Other settings,
+permissions and implementation-model choices are retained. JSONC is accepted;
+comments are removed from the rewritten file, with an exact original backup.
+Updates replace only unchanged package-managed instruction files. It does not
+import personal project memories or modify Claude/Codex global rules.
+
+## Storage and existing sessions
+
+New state lives outside both the package and project: Windows uses
+`%LOCALAPPDATA%/opencode-hybrid/runtime`, other platforms use
+`$XDG_DATA_HOME/opencode-hybrid/runtime` or `~/.local/share/opencode-hybrid/runtime`.
+Projects are isolated by canonical path. Checkpoints are project-scoped; concurrent
+conversations editing the same project must coordinate against the same gate.
+Opening a subfolder of a Git repository asks you to open its root.
+
+To retain a trial project's exact existing history without copying/resetting it:
+
+```sh
+opencode-hybrid init --legacy-config /path/to/old/config.json --project /path/to/project
+```
+
+Only that project receives a runtime override; new projects use portable storage.
+OpenCode conversation history is separate. Sessions created under an isolated
+`XDG_DATA_HOME` remain in that profile; installation does not move them. Existing
+trial profiles stay usable. Restart OpenCode to load changed modules; installation
+does not interrupt running sessions or restart model servers.
+
+## Troubleshooting
+
+Use **Hybrid Workflow settings > Run diagnostics** to check prerequisites,
+reviewer connections, design skills and browser access. Sign in to each provider
+on the machine where you use OpenCode. Reopen OpenCode after a plugin update.
+
+## License
+
+The original plugin code is MIT-licensed; bundled skills retain their own
+licenses as listed in `THIRD_PARTY_NOTICES.md`. Authenticate providers on each
+machine rather than copying account credentials.

package/lib/cli-models.mjs

@@ -0,0 +1,77 @@
+import {spawn,spawnSync} from 'node:child_process';
+import {mkdtempSync,rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import {commandSpec,nativeCodex} from './commands.mjs';
+import {workerEnvironment} from '../core/workers.mjs';
+
+// Only initialize and inspect catalogs. Never start a thread, send a user
+// message, read credentials, or return account metadata from CLI responses.
+export function normalizeCLIModels(adapter,rows){
+ if(!Array.isArray(rows))throw Error('The CLI did not return a model catalog. Update the CLI and retry.');
+ const seen=new Set();
+ return rows.filter(m=>m&&!m.hidden).map(m=>{
+  const codex=adapter==='codex-cli';
+  const id=codex?(m.model??m.id):(m.value==='default'?m.resolvedModel:m.value);
+  const efforts=codex?m.supportedReasoningEfforts?.map(e=>e.reasoningEffort):m.supportedEffortLevels;
+  return {id,name:codex?(m.displayName??id):(m.displayName??id),description:typeof m.description==='string'?m.description:'',
+   efforts:[...new Set((efforts??[]).filter(e=>typeof e==='string'&&/^[a-zA-Z0-9_-]+$/.test(e)))],
+   ...(codex&&typeof m.defaultReasoningEffort==='string'?{defaultEffort:m.defaultReasoningEffort}:{}),isDefault:codex?!!m.isDefault:m.value==='default'};
+ }).filter(m=>typeof m.id==='string'&&m.id.trim()&&!seen.has(m.id)&&seen.add(m.id));
+}
+
+export async function discoverCLIModels(adapter,{executable,signal,timeoutMs=30000}={}){
+ if(!['codex-cli','claude-cli'].includes(adapter))throw Error('Unknown CLI connection.');
+ if(signal?.aborted)throw Error('Model discovery cancelled.');
+ const codex=adapter==='codex-cli';
+ const spec=commandSpec(codex?nativeCodex(executable??'codex'):(executable??'claude'));
+ const folder=mkdtempSync(path.join(tmpdir(),'hybrid-models-'));
+ const args=codex?['app-server','-c','model_provider="openai"','--listen','stdio://']:['-p','--safe-mode','--restricted','--strict-mcp-config','--mcp-config','{"mcpServers":{}}','--no-chrome','--no-session-persistence','--tools','','--input-format','stream-json','--output-format','stream-json','--verbose'];
+ try{return await new Promise((resolve,reject)=>{
+  const child=spawn(spec.executable,[...spec.args,...args],{cwd:folder,env:workerEnvironment(),shell:false,windowsHide:true,detached:process.platform!=='win32',stdio:['pipe','pipe','pipe']});
+  let done=false,buffer='',rows=[],nextId=2,expected=1,timer;const cursors=new Set();
+  const finish=(error,value)=>{
+   if(done)return;done=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);
+   child.stdin.destroy();child.stdout.destroy();child.stderr.destroy();
+   if(child.pid&&child.exitCode===null){
+    if(process.platform==='win32')spawnSync(path.join(process.env.SystemRoot??'C:/Windows','System32/taskkill.exe'),['/PID',String(child.pid),'/T','/F'],{windowsHide:true,timeout:5000,stdio:'ignore'});
+    else try{process.kill(-child.pid,'SIGKILL');}catch{child.kill('SIGKILL');}
+   }
+   child.unref();error?reject(error):resolve(value);
+  };
+  const abort=()=>finish(Error('Model discovery cancelled.'));
+  const send=value=>{if(!done)child.stdin.write(JSON.stringify(value)+'\n');};
+  const list=cursor=>{expected=nextId++;send({id:expected,method:'model/list',params:{includeHidden:false,...(cursor?{cursor}:{})}});};
+  child.on('error',()=>finish(Error('Could not start the CLI. Check its installation and retry.')));
+  child.stdin.on('error',()=>finish(Error('The CLI closed model discovery. Update the CLI and retry.')));
+  child.on('close',()=>finish(Error('The CLI exited without a model catalog. Check its installation and login.')));
+  child.stderr.resume();
+  child.stdout.setEncoding('utf8');child.stdout.on('data',chunk=>{
+   buffer+=chunk;
+   if(buffer.length>8*1024*1024)return finish(Error('The CLI returned an invalid model response.'));
+   let pos;while(!done&&(pos=buffer.indexOf('\n'))>=0){
+    const line=buffer.slice(0,pos);buffer=buffer.slice(pos+1);let message;try{message=JSON.parse(line);}catch{continue;}
+    try{
+     if(codex){
+      if(message.id!==expected)continue;
+      if(message.error)throw Error('Codex could not list models. Check its login/version and retry.');
+      if(expected===1){send({method:'initialized',params:{}});list();continue;}
+      if(!Array.isArray(message.result?.data))throw Error('Codex returned an invalid model catalog.');
+      rows.push(...message.result.data);
+      const cursor=message.result.nextCursor;
+      if(cursor){if(cursors.has(cursor))throw Error('Codex repeated a model catalog page.');cursors.add(cursor);list(cursor);continue;}
+     }else{
+      if(message.type!=='control_response'||message.response?.request_id!=='hybrid-models')continue;
+      if(message.response.subtype!=='success')throw Error('Claude could not list models. Check its login/version and retry.');
+      rows=message.response.response?.models;
+     }
+     const models=normalizeCLIModels(adapter,rows);if(!models.length)throw Error('No models were returned. Check the CLI login and retry.');
+     finish(null,{models,source:codex?'Codex CLI catalog':'Claude Code CLI catalog'});
+    }catch(error){finish(error);}
+   }
+  });
+  timer=setTimeout(()=>finish(Error('Loading CLI models timed out. Check the CLI login and retry.')),timeoutMs);
+  signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted){abort();return;}
+  send(codex?{id:1,method:'initialize',params:{clientInfo:{name:'opencode_hybrid',title:'Hybrid model picker',version:'1.0.0'}}}:{type:'control_request',request_id:'hybrid-models',request:{subtype:'initialize',hooks:{}}});
+ });}finally{rmSync(folder,{recursive:true,force:true});}
+}

package/lib/select-reviewers.mjs

@@ -1,6 +1,7 @@
 import {spawnSync} from 'node:child_process';
 import {createInterface} from 'node:readline/promises';
 import {commandSpec,nativeCodex} from './commands.mjs';
+import {discoverCLIModels} from './cli-models.mjs';
 
 export function modelCatalog(directory=process.cwd()) {
   const spec=commandSpec('opencode');
@@ -45,10 +46,16 @@ export async function selectInteractively(config) {
         const variant=await menu('Reasoning variant',[{label:'Provider default',value:undefined},...(model.variants??[]).map(v=>({label:v.id,value:v.id}))]);
         reviewers[who]=selection(`opencode:${provider}/${model.id}`,{catalog,variant});
       }else {
-        const old=config.reviewers?.[who],fallback=adapter==='codex-cli'?'gpt-6-astra':'opus';
-        const model=(await rl.question(`Model [${old?.adapter===adapter?old.model:fallback}]: `)).trim()||(old?.adapter===adapter?old.model:fallback);
-        const effort=(await rl.question('Effort [high]: ')).trim()||'high';
-        if(!/^[a-zA-Z0-9_-]+$/.test(effort))throw Error('Invalid effort.');
+        const old=config.reviewers?.[who];let models=[];
+        try{({models}=await discoverCLIModels(adapter,{executable:old?.adapter===adapter?old.executable:undefined}));}
+        catch(error){console.log(error.message);}
+        const items=models.map(m=>({label:m.name,value:m.id}));
+        if(old?.adapter===adapter&&!models.some(m=>m.id===old.model))items.push({label:`Keep current model (${old.model})`,value:old.model});
+        items.push({label:'Enter custom model ID (advanced)',value:'__custom'});
+        let model=await menu('CLI model',items);
+        if(model==='__custom'){model=(await rl.question('Exact model ID or CLI alias: ')).trim();if(!model)throw Error('Model is required.');}
+        const chosen=models.find(m=>m.id===model);
+        const effort=await menu('Reasoning effort',[{label:'CLI default',value:'default'},...(chosen?.efforts??['low','medium','high','xhigh','max']).map(v=>({label:v,value:v}))]);
         reviewers[who]=selection(`${adapter}:${model}`,{previous:old??{},variant:effort});
       }
     }

package/lib/settings-rpc.mjs

@@ -2,6 +2,7 @@
 const object={type:'object',additionalProperties:true};
 export const SettingsRPC={id:'hybrid.settings',methods:{
   get:{input:{type:'object',additionalProperties:false},output:object},
+  cliModels:{input:{type:'object',additionalProperties:false,properties:{adapter:{enum:['codex-cli','claude-cli']},who:{enum:['astra','opus']}},required:['adapter','who']},output:object},
   save:{input:{type:'object',additionalProperties:false,properties:{revision:{type:'string'},reviewers:object,designAuthor:{enum:['astra','opus']}},required:['revision','reviewers','designAuthor']},output:object},
   browser:{input:{type:'object',additionalProperties:false,properties:{action:{enum:['enable','disable','install']}},required:['action']},output:object},
   diagnostics:{input:{type:'object',additionalProperties:false},output:object},

package/lib/settings-service.mjs

@@ -8,6 +8,7 @@ import {commandSpec} from './commands.mjs';
 import {runProcess,requireSubscription} from '../core/workers.mjs';
 import {NativeBrowser} from './native-browser.mjs';
 import {SettingsRPC} from './settings-rpc.mjs';
+import {discoverCLIModels} from './cli-models.mjs';
 const writes=new Set();
 const unwrap=x=>x?.data??x;
 export function revision(file){return createHash('sha256').update(existsSync(file)?readFileSync(file):'missing').digest('hex');}
@@ -73,6 +74,11 @@ export function createSettingsService(ctx,options={}){
   return folder;
  }
  return {get,diagnostics,
+  cliModels:(input,context={})=>{
+   if(!['astra','opus'].includes(input.who)||!['codex-cli','claude-cli'].includes(input.adapter))throw Error('Unknown reviewer connection.');
+   const previous=load().reviewers?.[input.who];
+   return discoverCLIModels(input.adapter,{executable:previous?.adapter===input.adapter?previous.executable:undefined,signal:context.signal});
+  },
   save:input=>exclusive(async()=>{
    if(input.revision!==revision(file))throw Error('Settings changed in another window. Reopen settings and try again.');
    const patch=validateChoices(input,await catalog(),load());

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@rockysoft/opencode-hybrid-workflow",
-  "version": "0.3.2-beta.1",
+  "version": "0.3.2-beta.3",
   "description": "Portable configurable-reviewer planning, design, implementation checkpoints and usage sidebar for OpenCode 2",
   "type": "module",
   "license": "MIT",
   "author": "RockySoft",
-  "keywords": ["opencode", "opencode-plugin", "agents", "code-review", "workflow"],
-  "publishConfig": { "access": "public", "tag": "beta" },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "agents",
+    "code-review",
+    "workflow"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
   "exports": {
     ".": "./index.js",
     "./tui": "./tui.js"
@@ -24,7 +33,8 @@
     "assets/",
     "README.md",
     "THIRD_PARTY_NOTICES.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/"
   ],
   "engines": {
     "node": ">=22"

package/sidebar/settings.mjs

@@ -25,8 +25,25 @@ export function createSettingsUI(context,onSaved=()=>{}){
    return {adapter:'opencode',providerID:provider,model,...(variant==='__default'?{}:{variant})};
   }
   const adapter=await select('External CLI',[{title:'Codex CLI',value:'codex-cli'},{title:'Claude Code CLI',value:'claude-cli'}],current?.adapter);if(!adapter)return;
-  const model=await context.ui.dialog.prompt({title:'CLI model',placeholder:current?.adapter===adapter?current.model:adapter==='codex-cli'?'gpt-6-astra':'opus',value:current?.adapter===adapter?current.model:adapter==='codex-cli'?'gpt-6-astra':'opus'});if(!model?.trim())return;
-  const effort=await select('CLI reasoning effort',['low','medium','high','xhigh','max'].map(v=>({title:v,value:v})),current?.effort??'high');if(!effort)return;
+  let catalog;
+  while(!catalog){
+   context.ui.toast.show({message:'Loading models from '+(adapter==='codex-cli'?'Codex':'Claude Code')+'…',variant:'info'});
+   try{catalog=await invoke('cliModels',{adapter,who});}
+   catch(error){
+    const action=await select('Could not load CLI models',[{title:'Retry',value:'retry',description:error.message},{title:'Enter custom model ID (advanced)',value:'custom'},{title:'Back to connections',value:'back'}]);
+    if(action==='retry')continue;if(action==='back')return reviewer(who,state,current);if(action!=='custom')return;catalog={models:[]};
+   }
+  }
+  const existing=current?.adapter===adapter?current.model:undefined;
+  const options=catalog.models.map(m=>({title:m.name,value:m.id,description:m.description||m.id}));
+  if(existing&&!catalog.models.some(m=>m.id===existing))options.push({title:'Keep current model',value:existing,description:existing+' · not in current CLI catalog'});
+  options.push({title:'Enter custom model ID (advanced)',value:'__custom'});
+  let model=await select('CLI model',options,existing??catalog.models.find(m=>m.isDefault)?.id);if(!model)return;
+  if(model==='__custom')model=await context.ui.dialog.prompt({title:'Custom model ID',placeholder:'Exact model ID or CLI alias',value:existing??''});if(!model?.trim())return;
+  const chosen=catalog.models.find(m=>m.id===model);
+  const efforts=chosen?.efforts??['low','medium','high','xhigh','max'];
+  const preferred=current?.adapter===adapter&&(current.effort==='default'||efforts.includes(current.effort))?current.effort:efforts.includes('high')?'high':'default';
+  const effort=await select('CLI reasoning effort',[{title:'CLI default',value:'default'},...efforts.map(v=>({title:v,value:v}))],preferred);if(!effort)return;
   return {adapter,model:model.trim(),effort};
  }
  async function wizard(state){