bros-harness 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.6 - 2026-06-03
+
+- Corrected OpenCode installation guidance to use `opencode plugin bros-harness` as the primary package installer flow before manual config snippets.
+
 ## 0.1.5 - 2026-06-03
 
 - Added flexible feature-branch Git permission patterns for BROS executor agents with explicit approval-packet requirements.

package/README.md

@@ -79,17 +79,22 @@ The point is not ceremony for ceremony’s sake. The point is to keep useful pre
 
 ## Installation
 
-BROS Harness is OpenCode-first. The primary install path is the package plugin snippet:
+BROS Harness is OpenCode-first. Use the full installation guide:
 
-For LLM: Install BROS Harness into OpenCode using the self-contained native agent guide at [`docs/native-opencode-agent-installation.md`](docs/native-opencode-agent-installation.md); detect OpenCode first, check npm dist-tags before `bros-harness@latest`, prefer pinned `bros-harness@0.1.4` when latest is stale, avoid secrets/provider/MCP/global mutations, verify agents, and remind the user to restart OpenCode.
+[`docs/installation.md`](docs/installation.md)
 
-```json
-{
-  "plugin": ["bros-harness"]
-}
+Quick project install:
+
+```bash
+opencode plugin bros-harness
 ```
 
-After adding the plugin entry through your normal OpenCode configuration workflow, restart OpenCode so startup configuration is reloaded.
+Restart OpenCode, then verify:
+
+```bash
+opencode agent list
+opencode run --agent mighty-bro "hello"
+```
 
 Optional read-only CLI checks:
 
@@ -102,7 +107,10 @@ bros list-assets
 For AI-assisted setup, use a narrow prompt:
 
 ```text
-Add BROS Harness to OpenCode using only the package plugin snippet { "plugin": ["bros-harness"] }. Do not install dependencies, publish packages, edit provider settings, add MCP servers, change permissions, configure telemetry, validate secrets, or overwrite existing config. If a config already exists, merge only the plugin entry, show the diff, and ask before writing. Tell the human to restart OpenCode after the approved edit.
+Install BROS Harness into OpenCode by following docs/installation.md as the source of truth.
+Do not only paste JSON into opencode.jsonc; use OpenCode's plugin installer unless the guide's fallback applies.
+Do not edit providers, MCP, permissions, telemetry, secrets, npm publishing, or npm dist-tags.
+Restart OpenCode and verify BROS agents after installation.
 ```
 
 The CLI can print similar guidance:
@@ -173,7 +181,6 @@ Before proposing changes, check:
 Useful references:
 
 - [`docs/installation.md`](docs/installation.md)
-- [`docs/native-opencode-agent-installation.md`](docs/native-opencode-agent-installation.md)
 - [`docs/integrations/opencode.md`](docs/integrations/opencode.md)
 - [`docs/security.md`](docs/security.md)
 - [`CONTRIBUTING.md`](CONTRIBUTING.md)

package/bin/bros.mjs

@@ -9,10 +9,10 @@ const manifestPath = join(packageRoot, "assets", "manifest.json");
 
 const commands = [
   ["help", "Show available BROS Harness commands."],
-  ["snippet", "Print the package-first OpenCode plugin snippet."],
+  ["snippet", "Print OpenCode installer commands and resulting plugin entry."],
   ["doctor", "Validate package asset directories and manifest shape without mutation."],
   ["list-assets", "Summarize packaged OpenCode agent, command, skill, doc, and template counts."],
-  ["agent-install-prompt", "Print a safe prompt an AI agent can follow to add the plugin snippet."]
+  ["agent-install-prompt", "Print a safe prompt an AI agent can follow to install the plugin."]
 ];
 
 const requiredPaths = [
@@ -39,8 +39,27 @@ function printHelp() {
   console.log("All commands are read-only. This CLI does not edit live OpenCode config.");
 }
 
-function printSnippet() {
-  console.log(JSON.stringify({ plugin: ["bros-harness"] }, null, 2));
+async function getPackageVersion() {
+  const packageJson = await readJson(join(packageRoot, "package.json"));
+  return packageJson.version || "latest";
+}
+
+async function printSnippet() {
+  const version = await getPackageVersion();
+  console.log(`Recommended OpenCode installer command:
+opencode plugin bros-harness
+
+Global OpenCode config:
+opencode plugin bros-harness --global
+
+Pinned current package when cache or latest resolution is suspect:
+opencode plugin bros-harness@${version} --force
+
+Full guide:
+docs/installation.md
+
+Resulting config entry:
+${JSON.stringify({ plugin: ["bros-harness"] }, null, 2)}`);
 }
 
 async function readJson(path) {
@@ -85,8 +104,8 @@ async function listAssets() {
   console.log(`Templates: ${counts.templates?.imported ?? "unknown"}`);
 }
 
-function printAgentInstallPrompt() {
-  console.log(`Add BROS Harness to OpenCode using the package plugin snippet only.\n\nConstraints:\n- Do not install dependencies unless the human explicitly approves it.\n- Do not publish packages.\n- Do not edit provider, MCP, permission, telemetry, secret, or credential settings.\n- Do not overwrite existing config. Merge only the plugin entry if OpenCode config exists.\n- If unsure, show the diff and ask.\n\nSnippet to add:\n{\n  "plugin": ["bros-harness"]\n}\n\nAfter editing OpenCode config, tell the human to restart OpenCode because config is loaded at startup.`);
+async function printAgentInstallPrompt() {
+  console.log(`Install BROS Harness into OpenCode by following docs/installation.md as the source of truth.\nDo not only paste JSON into opencode.jsonc; use OpenCode's plugin installer unless the guide's fallback applies.\nDo not edit providers, MCP, permissions, telemetry, secrets, npm publishing, or npm dist-tags.\nRestart OpenCode and verify BROS agents after installation.`);
 }
 
 const command = process.argv[2] ?? "help";
@@ -99,7 +118,7 @@ try {
       printHelp();
       break;
     case "snippet":
-      printSnippet();
+      await printSnippet();
       break;
     case "doctor":
       await doctor();
@@ -108,7 +127,7 @@ try {
       await listAssets();
       break;
     case "agent-install-prompt":
-      printAgentInstallPrompt();
+      await printAgentInstallPrompt();
       break;
     default:
       console.error(`Unknown command: ${command}`);

package/docs/installation.md

@@ -1,10 +1,55 @@
-# Installation
+# Installation Guide
 
-BROS Harness is structured as a package-first OpenCode plugin. The primary configuration path is the package snippet, not copying local development folders.
+This is the source of truth for installing BROS Harness into OpenCode.
 
-## For humans
+BROS Harness is a package-first OpenCode plugin. The primary installation path is OpenCode's own plugin installer. Do not rely on only pasting `{"plugin":["bros-harness"]}` into `opencode.jsonc`: that config entry does not guarantee OpenCode has installed or cached the npm package it must load.
 
-Add the plugin package to OpenCode config:
+## Prerequisites
+
+Confirm the local tools are available:
+
+```bash
+opencode --version
+opencode plugin --help
+npm --version
+node --version
+```
+
+Check the published package metadata:
+
+```bash
+npm view bros-harness dist-tags version --json
+```
+
+As of this release, the validated published package is `bros-harness@0.1.6` and the expected `latest` dist-tag is `0.1.6`.
+
+## Install
+
+For the current project config, run:
+
+```bash
+opencode plugin bros-harness
+```
+
+For global OpenCode config, run this only when you want BROS Harness in every OpenCode workspace:
+
+```bash
+opencode plugin bros-harness --global
+```
+
+If OpenCode has a stale cached package, or if npm metadata shows a stale `latest` dist-tag, pin the validated package and replace the existing plugin entry:
+
+```bash
+opencode plugin bros-harness@0.1.6 --force
+```
+
+For global scope with the pinned package, add `--global`:
+
+```bash
+opencode plugin bros-harness@0.1.6 --force --global
+```
+
+The installer makes the package available to OpenCode and writes a config entry like this:
 
 ```json
 {
@@ -12,50 +57,112 @@ Add the plugin package to OpenCode config:
 }
 ```
 
-Restart OpenCode after editing config. The running session keeps the config it loaded at startup.
+## Restart
+
+Fully quit and restart OpenCode after installing or changing plugin config. OpenCode loads plugins at startup, so an already-running session can keep using stale config.
+
+## Verify
+
+After restart, verify that BROS agents are visible:
+
+```bash
+opencode agent list
+```
+
+Expected BROS agents include:
 
-Optional read-only checks after the package is available:
+- `mighty-bro`
+- `bro-build`
+- `bro-test`
+- `bro-shield`
+- `bro-docs`
+- `bro-ops`
+- `bro-design`
+- `bro-ui`
+- `bro-explore`
+
+Run a minimal smoke test:
 
 ```bash
-bros snippet
-bros doctor
-bros list-assets
+opencode run --agent mighty-bro "hello"
+```
+
+If BROS commands are available in the active session, `/bros-status` can also be used after restart.
+
+## Troubleshooting
+
+If `opencode agent list` does not show `mighty-bro` or the `bro-*` agents, do not keep editing JSON. Check these causes first:
+
+- OpenCode was not restarted after the plugin install.
+- The plugin was installed in project scope but OpenCode was started from another project.
+- The plugin was installed globally only in a different user or config home.
+- OpenCode cached a stale package version.
+- The config contains a manual plugin entry but OpenCode never installed the package.
+
+Use the pinned installer to repair stale package resolution:
+
+```bash
+opencode plugin bros-harness@0.1.6 --force
+```
+
+Then restart OpenCode and run verification again.
+
+## Manual Config Fallback
+
+Manual config editing is a fallback, not the recommended installation path. Use it only when the package is already resolvable by OpenCode or when using a local development path.
+
+For package config, merge only the plugin entry:
+
+```json
+{
+  "plugin": ["bros-harness"]
+}
 ```
 
-## For AI agents
+For local repository smoke tests, use an absolute file URL:
 
-For a complete native OpenCode setup flow, use the self-contained agent guide: [`native-opencode-agent-installation.md`](native-opencode-agent-installation.md).
+```json
+{
+  "plugin": ["file:///absolute/path/to/bros/src/plugin.mjs"]
+}
+```
 
-Use a bounded instruction:
+After any manual config edit, fully restart OpenCode and verify with `opencode agent list`.
+
+## AI Agent Prompt
+
+Use this prompt when asking an AI coding agent to install BROS Harness:
 
 ```text
-Configure BROS Harness with { "plugin": ["bros-harness"] }. Do not install dependencies, publish, mutate provider/MCP/permission/telemetry/secret settings, or overwrite existing config files. Merge only the plugin entry if approved, show the proposed diff, and remind the human to restart OpenCode.
+Install BROS Harness into OpenCode by following docs/installation.md as the source of truth.
+First check opencode --version, opencode plugin --help, npm --version, node --version,
+and npm view bros-harness dist-tags version --json.
+Ask whether to use project scope or global scope.
+After approval, use opencode plugin bros-harness for project scope or
+opencode plugin bros-harness --global for global scope.
+If latest resolution or cache state is suspect, use bros-harness@0.1.6 --force
+in the same approved scope.
+Do not run npm install, publish packages, mutate npm dist-tags, edit providers,
+MCP servers, permissions, telemetry, secrets, or credentials.
+If manual config editing is explicitly requested, merge only the plugin entry
+and show the diff before writing.
+Tell the human to fully restart OpenCode, then verify with opencode agent list
+and opencode run --agent mighty-bro "hello".
 ```
 
-The package helper can print this prompt:
+The package helper prints a short reference prompt:
 
 ```bash
 bros agent-install-prompt
 ```
 
-## What the plugin changes
-
-- Uses OpenCode's in-memory `config(cfg)` hook at startup.
-- Adds package-relative BROS skills to `skills.paths` only when the existing field shape is schema-compatible.
-- Adds packaged BROS command prompt entries to `command` without replacing existing command keys.
+## Runtime Behavior
 
-## What the plugin does not change
+On startup, the plugin uses OpenCode's in-memory `config(cfg)` hook only. It adds package-relative BROS skills, packaged BROS agents, and packaged BROS commands without replacing existing keys.
 
-- No providers.
-- No MCP servers.
-- No permission changes.
-- No telemetry.
-- No secrets or credential validation.
-- No provider, MCP, permission, telemetry, or secret registration.
-- No filesystem writes.
-- No live user config file mutation; `opencode.json`, `.opencode/`, and global config files are not written by the package plugin.
+The runtime plugin does not write user config files, install dependencies, publish packages, register providers, add MCP servers, change permissions, configure telemetry, or read, validate, or write secrets.
 
-## Local contributor checks
+## Contributor Checks
 
 For repository development only:
 
@@ -64,5 +171,4 @@ npm run validate
 node bin/bros.mjs doctor
 ```
 
-Publishing and dependency installation remain separate gated actions.
-Asset import is maintainer-only source maintenance for repository asset refreshes, not part of package installation. Package users should rely on the plugin snippet and read-only CLI helpers above; import tooling is not exposed as an installed package command.
+Publishing, dependency installation, and asset import remain separate maintainer-gated actions. Package users should rely on OpenCode's plugin installer and the read-only CLI helpers above.

package/docs/integrations/opencode.md

@@ -2,9 +2,27 @@
 
 OpenCode is the primary integration target for BROS Harness.
 
-## Package snippet
+## Package Installer
 
-Use the package plugin entry:
+Use the complete installation guide as the source of truth:
+
+[`../installation.md`](../installation.md)
+
+OpenCode's plugin installer makes the npm package available to OpenCode and updates config in the selected scope.
+
+Project scope:
+
+```bash
+opencode plugin bros-harness
+```
+
+Global scope:
+
+```bash
+opencode plugin bros-harness --global
+```
+
+The resulting config entry is:
 
 ```json
 {
@@ -12,7 +30,7 @@ Use the package plugin entry:
 }
 ```
 
-This is the preferred path for users and agents. Local path examples are contributor-only.
+This is the preferred path for users and agents. Adding the JSON entry manually is only enough when the package is already resolvable by OpenCode. Local path examples are contributor-only.
 
 ## Packaged assets
 
@@ -30,7 +48,7 @@ This runtime hook changes only the merged config object OpenCode passes to the p
 
 ## Safe agent workflow
 
-For end-to-end native OpenCode detection, npm version selection, plugin installation, verification, troubleshooting, and restart guidance, see [`../native-opencode-agent-installation.md`](../native-opencode-agent-installation.md).
+For end-to-end native OpenCode detection, npm version selection, plugin installation, verification, troubleshooting, and restart guidance, see [`../installation.md`](../installation.md).
 
 Agents should use:
 
@@ -38,4 +56,4 @@ Agents should use:
 bros agent-install-prompt
 ```
 
-The prompt instructs agents to merge only `plugin: ["bros-harness"]`, avoid sensitive config surfaces, and ask before writing.
+The prompt instructs agents to follow the installation guide, run OpenCode's plugin installer after approval, restart OpenCode, and verify that BROS agents are visible.

package/docs/native-opencode-agent-installation.md

@@ -1,205 +1,16 @@
 # Native OpenCode Agent Installation Guide
 
-## Purpose
+This page is retained for older links.
 
-This guide gives LLMs and automation agents a bounded, end-to-end path for installing BROS Harness into a native OpenCode environment. It is intended for agents that need to detect OpenCode, choose a safe npm package version, guide the plugin configuration, verify the result, and tell the user when a restart is required.
+Use the complete installation guide as the source of truth:
 
-Use this guide only for OpenCode installation support. Do not use it to publish packages, mutate npm dist-tags, edit provider settings, add MCP servers, inspect secrets, or broaden OpenCode permissions.
+[`installation.md`](installation.md)
 
-## Target audience
-
-- LLMs and coding agents helping a user install BROS Harness into OpenCode.
-- Maintainers validating installation instructions without changing global user configuration.
-- Users who want a safe checklist for native OpenCode setup.
-
-## Safety boundaries
-
-Agents must follow these limits:
-
-- Do not read `.env` files, tokens, credentials, provider keys, or secret stores.
-- Do not print secret values if encountered. Report only the path, line number, variable name, or redacted value.
-- Do not edit provider, MCP, permission, telemetry, credential, or secret settings.
-- Do not publish npm packages.
-- Do not change npm dist-tags unless the maintainer explicitly approves that registry mutation.
-- Do not mutate global OpenCode config automatically. If a config edit is needed, show the proposed diff and ask the user before writing.
-- Do not overwrite an existing OpenCode config. Merge only the BROS Harness plugin entry.
-
-## Detect OpenCode and local tooling
-
-Run only safe read-only detection commands unless the user approves a write.
-
-```bash
-opencode --version
-npm --version
-node --version
-npm view bros-harness dist-tags version --json
-```
-
-If `opencode --version` fails, stop and ask the user to install or expose OpenCode on `PATH` before proceeding. If `npm --version` fails, ask the user which package manager they want to use and avoid guessing.
-
-Be aware of likely OpenCode config locations, but do not edit them without user approval:
-
-- Repository-local `opencode.json` or `opencode.jsonc`.
-- Repository-local `.opencode/` configuration files.
-- User-level OpenCode config under the platform's normal config directory, such as `~/.config/opencode/` on Linux.
-
-When inspecting config, avoid files that may contain secrets. If the user asks for edits, propose the smallest plugin-only change.
-
-## Choose the package version
-
-The normal package plugin reference is:
-
-```json
-{
-  "plugin": ["bros-harness"]
-}
-```
-
-However, OpenCode or npm may resolve `bros-harness@latest`, and the `latest` dist-tag can be stale. The known-good version from prior validation is `bros-harness@0.1.4`.
-
-Use this version-selection rule:
-
-1. Check npm metadata first:
-
-   ```bash
-   npm view bros-harness dist-tags version --json
-   ```
-
-2. If `latest` points to the expected current known-good version, use `bros-harness@latest` or the bare plugin package name.
-3. If `latest` is stale, ambiguous, or OpenCode appears to cache an older package, prefer the pinned known-good package reference: `bros-harness@0.1.4`.
-4. If a newer known-good version is explicitly approved, replace `0.1.4` with `<known-good-version>` and document why it is trusted.
-
-## Recommended install flow
-
-1. Confirm OpenCode is available:
-
-   ```bash
-   opencode --version
-   ```
-
-2. Confirm npm can resolve the package metadata:
-
-   ```bash
-   npm view bros-harness dist-tags version --json
-   ```
-
-3. Ask the user which OpenCode config scope they want to update if more than one config path is possible.
-
-4. Propose one of these plugin entries.
-
-   Use the normal latest-resolving entry only when npm metadata is healthy:
-
-   ```json
-   {
-     "plugin": ["bros-harness"]
-   }
-   ```
-
-   Use a pinned package when `latest` is stale or cache behavior is suspect:
-
-   ```json
-   {
-     "plugin": ["bros-harness@0.1.4"]
-   }
-   ```
-
-   For future maintained releases, the pinned form may become:
-
-   ```json
-   {
-     "plugin": ["bros-harness@<known-good-version>"]
-   }
-   ```
-
-5. Show the proposed config diff. The only intended change is adding or merging the BROS Harness plugin entry.
-
-6. Ask the user before writing the config.
-
-7. After the approved edit, tell the user to restart OpenCode. The plugin is loaded at OpenCode startup, so the running session may not see the new package until restart.
-
-## Commands agents may run
-
-Read-only detection and verification commands are safe when the user permits local command execution:
-
-```bash
-opencode --version
-npm --version
-node --version
-npm view bros-harness dist-tags version --json
-opencode agent list
-opencode run --agent mighty-bro "hello"
-```
-
-If BROS commands are available after restart, this may also be used:
-
-```text
-/bros-status
-```
-
-Do not run install, publish, or registry mutation commands unless the user explicitly approves the exact action.
-
-## Verification
-
-After the config edit and OpenCode restart, verify that BROS agents are visible:
-
-```bash
-opencode agent list
-```
-
-Then run a minimal smoke test:
-
-```bash
-opencode run --agent mighty-bro "hello"
-```
-
-If the OpenCode command interface supports slash commands in the active session, check BROS status:
-
-```text
-/bros-status
-```
-
-Expected result: packaged BROS agents and commands are available after restart. If the agent list does not include BROS agents, troubleshoot package version resolution and restart state first.
-
-## Troubleshooting stale `latest` resolution
-
-Check package metadata:
-
-```bash
-npm view bros-harness dist-tags version --json
-```
-
-If `latest` is stale or OpenCode appears to cache an older package:
-
-1. Switch the plugin entry from the bare package name to a pinned package reference:
-
-   ```json
-   {
-     "plugin": ["bros-harness@0.1.4"]
-   }
-   ```
-
-2. Restart OpenCode.
-3. Re-run verification:
-
-   ```bash
-   opencode agent list
-   opencode run --agent mighty-bro "hello"
-   ```
-
-Maintainers may repair a stale npm `latest` dist-tag only with explicit release approval:
-
-```bash
-npm dist-tag add bros-harness@<version> latest
-```
-
-That command mutates the public npm registry. Agents must not run it unless the maintainer explicitly authorizes the exact package version and registry action.
-
-## Restart requirement
-
-OpenCode loads package plugins during startup. After adding or changing the BROS Harness plugin entry, restart OpenCode before verification. If verification fails immediately after editing config, restart first before changing anything else.
-
-## Minimal prompt for an agent
+Agent prompt reference:
 
 ```text
-Install BROS Harness into native OpenCode using docs/native-opencode-agent-installation.md. Detect OpenCode with opencode --version, check npm metadata with npm view bros-harness dist-tags version --json, use bros-harness@latest only when the latest dist-tag is healthy, otherwise use pinned bros-harness@0.1.4 or an explicitly approved <known-good-version>. Merge only the plugin entry, do not edit providers/MCP/permissions/telemetry/secrets, do not publish or mutate npm dist-tags, show the diff before writing, verify with opencode agent list and opencode run --agent mighty-bro "hello", and tell the user to restart OpenCode.
+Install BROS Harness into OpenCode by following docs/installation.md as the source of truth.
+Do not only paste JSON into opencode.jsonc; use OpenCode's plugin installer unless the guide's fallback applies.
+Do not edit providers, MCP, permissions, telemetry, secrets, npm publishing, or npm dist-tags.
+Restart OpenCode and verify BROS agents after installation.
 ```

package/examples/opencode/README.md

@@ -1,6 +1,20 @@
 # OpenCode Example
 
-The package-first example uses the BROS Harness plugin snippet:
+Use the complete installation guide as the source of truth: [`../../docs/installation.md`](../../docs/installation.md).
+
+Quick project install:
+
+```bash
+opencode plugin bros-harness
+```
+
+Use global scope when requested:
+
+```bash
+opencode plugin bros-harness --global
+```
+
+The installer writes a config entry like this:
 
 ```json
 {
@@ -8,4 +22,4 @@ The package-first example uses the BROS Harness plugin snippet:
 }
 ```
 
-This example does not include provider keys, private endpoints, MCP servers, permissions, telemetry, credentials, or local absolute paths. Restart OpenCode after applying an approved config change.
+This example does not include provider keys, private endpoints, MCP servers, permissions, telemetry, credentials, or local absolute paths. Restart OpenCode after installation or any approved config change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bros-harness",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Package-first OpenCode plugin for disciplined BROS agent harness assets.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "bros": "./bin/bros.mjs"
+    "bros": "bin/bros.mjs"
   },
   "files": [
     "assets/",