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

package/README.md

@@ -1,252 +1,163 @@
 # 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.2/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.2/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.2/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.2/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.2/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.2/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.2/docs/images/18-cli.png)
+
+**Enter the model ID.**
+
+![Enter a CLI model ID](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.2/docs/images/19-cli-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.2/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.2/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.2/docs/images/07-design-lead.png)
+
+Confirm your choices. They apply across projects; active tasks keep their assigned reviewers.
+
+![Save the reviewer setup](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.2/docs/images/08-save.png)
 
-`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:
+## 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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/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.2/docs/configuration.md) · [MIT license](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.2/LICENSE) · [Third-party notices](https://cdn.jsdelivr.net/npm/@rockysoft/opencode-hybrid-workflow@0.3.2-beta.2/THIRD_PARTY_NOTICES.md)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rockysoft/opencode-hybrid-workflow",
-  "version": "0.3.2-beta.1",
+  "version": "0.3.2-beta.2",
   "description": "Portable configurable-reviewer planning, design, implementation checkpoints and usage sidebar for OpenCode 2",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,8 @@
     "assets/",
     "README.md",
     "THIRD_PARTY_NOTICES.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/"
   ],
   "engines": {
     "node": ">=22"