@cesarus777/opencode-cgp 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.1 — 2026-10-29
+
+- Install the standalone dashboard's pinned OpenTUI renderer automatically with CGP, including its native platform library. Keep renderer loading lazy so server and offline commands still work on Bun >=1.1.34; the dashboard requires Bun >=1.3.0.
+- Clarify CLI launch instructions and add command-specific help with examples.
+
 ## 0.3.0 — 2026-10-28
 
 Changes since 0.2.5:

package/README.md

@@ -41,10 +41,10 @@ Global configuration is `~/.config/opencode/opencode.jsonc` (or the OpenCode con
 
 Restart/reload OpenCode and look for `context-guard: observe; diagnostics ...`. Observe mode records policy decisions and never requests compaction; OpenCode's own automatic compaction remains active. Inspect diagnostics first, then set `mode` to `enforce` to admit native compaction at runtime step boundaries. The complete [example](examples/opencode.jsonc) includes model, role, and agent policies. **Last matching rule wins**; selectors within a rule are ANDed.
 
-Pin the exact published version in the existing entry's `package` field or use the manager. Version `0.3.0` adds a standalone terminal dashboard, offline model analytics across retained sessions, and context charts that preserve bar height and reuse the latest column during pauses. See the [changelog](CHANGELOG.md).
+Pin the exact published version in the existing entry's `package` field or use the manager. Version `0.3.1` installs the standalone dashboard renderer automatically and adds clearer command help. Version `0.3.0` introduced the standalone dashboard, offline model analytics and paused context chart fixes. See the [changelog](CHANGELOG.md).
 
 ```sh
-opencode plugin add @cesarus777/opencode-cgp@0.3.0
+opencode plugin add @cesarus777/opencode-cgp@0.3.1
 ```
 
 Manage the configured target with the [official V2 CLI](https://dev.opencode.ai/v2/docs/plugins):
@@ -82,9 +82,32 @@ Use `{"plugins":[{"package":"/absolute/path/to/opencode-cgp","options":{"mode":"
 
 If loading fails, run `opencode plugin list` and `opencode plugin check`, confirm V2 2.0.29 and the correct configuration scope, and inspect OpenCode's startup logs. A missing `@opencode/plugin` or client module indicates an incomplete package installation: remove/re-add the configured package using the manager. TUI-only missing `solid-js`/OpenTUI modules usually indicate an unsupported host or loading the TUI outside its host runtime. These optional peers are supplied by the native TUI and must share its runtime instances; do not bundle private renderer copies. Standalone renderer tests need the pinned peers and public runtime preload described in [testing](docs/testing.md). Never reset persisted safety state merely to fix loading. For remote clients, check both client installation and server registration in the session's owning location.
 
+## Run after installation
+
+From your project directory, start OpenCode:
+
+```sh
+opencode
+```
+
+Inside OpenCode, enter `/context-guard` to open the Context Guard panel. The plugin loads automatically with OpenCode after registration; there is no separate plugin process to start. Observe mode is the default. Press **c** in the panel for history charts, or **q** to close it.
+
+The installed diagnostic command is **`context-guard`** (Bun required):
+
+```sh
+context-guard --help
+context-guard dashboard tui --help
+context-guard models --help
+context-guard metrics --help
+context-guard charts --help
+context-guard help journal
+```
+
+Each command's help explains its inputs and shows an example. In a source checkout, use `bun run inspect` in place of `context-guard`, for example `bun run inspect charts --help`. OpenCode's plugin manager installs the plugin for the host; if `context-guard` is absent from your shell's PATH, you can still use the native panel. To expose the CLI separately, install the same package with your package manager, for example `npm install -g @cesarus777/opencode-cgp@0.3.1`.
+
 ## Standalone terminal dashboard
 
-Run the dashboard with OpenCode's native TUI closed. The server must already be running, with Context Guard registered in the owning location. The standalone command requires **Bun >=1.3.0** and the optional **`@opentui/core@0.5.17`** peer; server imports and existing diagnostic commands retain Bun >=1.1.34 support. Solid and the native TUI plugin are unnecessary for this command.
+Run the dashboard with OpenCode's native TUI closed. The server must already be running, with Context Guard registered in the owning location. The standalone command requires **Bun >=1.3.0**. The package automatically installs **`@opentui/core@0.5.17`** and its platform renderer; no separate OpenTUI install is needed. Keep optional dependencies enabled so OpenTUI's native platform library is installed. Server imports and existing diagnostic commands retain Bun >=1.1.34 support. Solid and the native TUI plugin are unnecessary for this command.
 
 For an unreleased checkout:
 
@@ -95,10 +118,10 @@ bun dist/cli.js dashboard tui
 bun dist/cli.js dashboard tui --server https://server.example --directory /server/project
 ```
 
-For a packed artifact, install the tarball and renderer together into a separate client directory, then launch with Bun >=1.3.0:
+For a packed artifact, install the tarball into a separate client directory, then launch with Bun >=1.3.0:
 
 ```sh
-npm install /absolute/path/cesarus777-opencode-cgp-0.3.0.tgz @opentui/core@0.5.17
+npm install /absolute/path/cesarus777-opencode-cgp-0.3.1.tgz
 bun node_modules/.bin/context-guard dashboard tui
 ```
 

package/dist/cli.js

@@ -663,19 +663,40 @@ async function loadTerminalRenderer() {
   try {
     return await import("@opentui/core");
   } catch {
-    throw new Error("Terminal renderer unavailable; install @opentui/core@0.5.17 beside @cesarus777/opencode-cgp using Bun >=1.3.0");
-  }
-}
-var dashboardHelp = `Usage: context-guard dashboard tui [--server URL] [--directory PATH]
-Read-only standalone terminal dashboard; never starts an OpenCode server.
-Requires an interactive terminal, Bun >=1.3.0 and @opentui/core@0.5.17.
-Install the renderer beside this package: npm install @opentui/core@0.5.17
-Local discovery defaults to the current directory.
-An explicit server requires --directory with an owning absolute server path.
-Remote authentication: CONTEXT_GUARD_PASSWORD and optional CONTEXT_GUARD_USERNAME
-(default opencode). Credentials must never be supplied in the URL.
-Keys: 1 overview, 2 detail, 3 history, arrows/j/k move, / search, f filters,
-l location, w history window, r refresh, ? help, Escape back, q/Ctrl+C quit.`;
+    throw new Error("Terminal renderer unavailable; reinstall @cesarus777/opencode-cgp with optional dependencies enabled for its platform renderer, using Bun >=1.3.0");
+  }
+}
+var dashboardHelp = `Usage: context-guard dashboard tui [options]
+Open a read-only live terminal dashboard for an existing OpenCode server.
+
+Start here
+  1. Keep an OpenCode server running with Context Guard registered.
+  2. Close OpenCode's native TUI before opening the standalone dashboard.
+  3. In the owning project directory, run: context-guard dashboard tui
+
+Options
+  --directory PATH   Owning project directory (local default: current directory)
+  --server URL       Connect to an explicit server; requires --directory with
+                     an absolute server-side project path. Use HTTPS except
+                     on loopback. Credentials in URLs are rejected.
+  -h, --help         Show this help
+
+Examples
+  context-guard dashboard tui
+  context-guard dashboard tui --directory /absolute/project
+  context-guard dashboard tui --server https://server.example --directory /server/project
+
+Requirements
+  Interactive terminal and Bun >=1.3.0. The OpenTUI renderer is installed
+  automatically with CGP. This command never starts a server.
+
+Authentication (explicit servers)
+  CONTEXT_GUARD_PASSWORD   Server password
+  CONTEXT_GUARD_USERNAME   Server username (default: opencode)
+
+Keys
+  1/2/3 overview/detail/history; arrows or j/k move; / search; f filters;
+  l location; w history window; r refresh; ? help; q or Ctrl+C quit.`;
 var init_command = () => {
 };
 
@@ -2793,7 +2814,7 @@ import { isAbsolute as isAbsolute4, resolve as resolve2 } from "path";
 async function inspectModels(args) {
   const directory = args[0];
   if (!directory || !isAbsolute4(directory))
-    throw new Error("Usage: inspect models /absolute/history-directory [--model ID] [--agent NAME] [--from ISO-or-ms] [--to ISO-or-ms] [--csv | --json]");
+    throw new Error("Use context-guard models --help for usage and examples; the history directory must be an absolute path");
   const values = new Map;
   let csv = false, json = false;
   for (let i = 1;i < args.length; i++) {
@@ -3592,9 +3613,124 @@ async function readJournal(path, maxBytes = 16 * 1024 * 1024) {
   return records;
 }
 
+// src/clihelp.ts
+var mainHelp = `Context Guard \u2014 context monitoring for OpenCode V2
+
+Start here
+  In your project, run: opencode
+  Inside OpenCode, enter: /context-guard
+  The plugin loads with OpenCode; observe mode is the default.
+
+Usage: context-guard <command> [options]
+       context-guard <journal.jsonl> [--history | --json]
+
+Commands
+  dashboard tui   Open the standalone live terminal dashboard
+  models          Compare models across retained history
+  metrics         Export retained performance records as JSON or CSV
+  charts          Generate an interactive HTML report
+  <journal.jsonl> Inspect diagnostic session records
+
+Examples
+  context-guard dashboard tui
+  context-guard models /absolute/history-directory
+  context-guard charts /absolute/history-directory --output report.html
+  context-guard /absolute/events.jsonl --history
+
+Help
+  context-guard <command> --help   Show options and examples
+  context-guard help journal      Explain diagnostic inspection
+  -h, --help                     Show help
+
+Requires Bun >=1.1.34; the standalone dashboard requires Bun >=1.3.0.
+From a source checkout, replace context-guard with bun run inspect.`;
+var filterOptions = `  --agent NAME       Filter by exact agent name
+  --model PROVIDER/MODEL
+                     Filter by exact model ID
+  --from ISO-or-ms    Start time: ISO timestamp or Unix milliseconds
+  --to ISO-or-ms      End time: ISO timestamp or Unix milliseconds`;
+var historyOptions = `  --session ID       Filter by session
+${filterOptions}`;
+var historyPath = `Use the owning location's history.path directory, not its diagnostic JSONL
+file. By default it is a location-hashed directory under
+\$XDG_STATE_HOME/opencode-context-guard (or ~/.local/state/opencode-context-guard).
+A custom telemetry.path does not change the history directory.`;
+var commandHelp = {
+  models: `Usage: context-guard models <history-directory> [options]
+Compare model throughput and time to first token across retained sessions.
+The history directory must be an absolute path. Output defaults to JSON.
+
+Options
+${filterOptions}
+  --csv              Export CSV; coverage metadata goes to stderr
+  --json             Export JSON (default); cannot combine with --csv
+  -h, --help         Show this help
+
+Example
+  context-guard models /absolute/history-directory --agent build --csv
+
+${historyPath}`,
+  metrics: `Usage: context-guard metrics <history-directory> [options]
+Read retained performance records. Output defaults to JSON.
+
+Options
+${historyOptions}
+  --csv              Export CSV; coverage metadata goes to stderr
+  --chart FILE.html  Generate an HTML report instead (see charts --help)
+  -h, --help         Show this help
+
+Example
+  context-guard metrics /absolute/history-directory --csv > metrics.csv
+
+${historyPath}`,
+  charts: `Usage: context-guard charts <history-directory> [options]
+Generate a self-contained interactive HTML report, then open it in a browser.
+
+Options
+${historyOptions}
+  --output FILE.html Write the report (default: context-guard-charts.html)
+  --max-points N     Points per series: 16\u20135000 (default: 1000)
+  --max-sessions N   Session instances: 1\u20131024 (default: 128)
+  --force            Overwrite an existing report
+  -h, --help         Show this help
+
+Example
+  context-guard charts /absolute/history-directory --output report.html
+
+${historyPath}`,
+  journal: `Usage: context-guard <journal.jsonl> [options]
+Inspect the diagnostic journal reported in OpenCode's Context Guard startup log.
+By default, print the latest retained record for each session, one JSON per line.
+
+Options
+  --json             Print latest session records as a JSON array
+  --history          Print all retained journal records as a JSON array
+  -h, --help         Show this help
+
+Example
+  context-guard /absolute/path/from/startup.jsonl --history
+
+This reads a diagnostic file, not a performance history directory.`
+};
+
 // src/cli.ts
 var args = process.argv.slice(2);
-if (args[0] === "dashboard") {
+var helpRequested = args.some((arg) => arg === "--help" || arg === "-h");
+var helpTopic = args[0] === "help" ? args[1] : args[0];
+if (!args[0] || args[0] === "help" || helpRequested || args.length === 1 && (args[0] === "dashboard" || Object.hasOwn(commandHelp, args[0]))) {
+  if (helpTopic === "dashboard") {
+    const { dashboardHelp: dashboardHelp2 } = await Promise.resolve().then(() => (init_command(), exports_command));
+    console.log(dashboardHelp2);
+  } else if (helpTopic && Object.hasOwn(commandHelp, helpTopic)) {
+    console.log(commandHelp[helpTopic]);
+  } else if (args[0] === "help" && helpTopic) {
+    console.error(`Unknown help topic. Use context-guard --help for commands.`);
+    process.exitCode = 1;
+  } else if (helpRequested && helpTopic && !helpTopic.startsWith("-")) {
+    console.log(commandHelp.journal);
+  } else
+    console.log(mainHelp);
+} else if (args[0] === "dashboard") {
   const { parseDashboardArgs: parseDashboardArgs2, dashboardHelp: dashboardHelp2, checkTerminalRuntime: checkTerminalRuntime2 } = await Promise.resolve().then(() => (init_command(), exports_command));
   try {
     const options = parseDashboardArgs2(args.slice(1), process.cwd(), process.env);
@@ -3611,15 +3747,13 @@ if (args[0] === "dashboard") {
     console.error(safe ? message : "Dashboard startup failed; check server, owning directory, authentication and renderer installation");
     process.exitCode = 1;
   }
-} else if (!args[0] || args.includes("--help")) {
-  console.log("Usage: bun run inspect /absolute/path/to/journal.jsonl [--history] [--json]\nThe ready log reports the location-specific journal path.\nMetrics: inspect metrics /absolute/history-directory [--session ID] [--from ISO-or-ms] [--to ISO-or-ms] [--csv]\nModels: inspect models /absolute/history-directory [--model provider/model] [--agent NAME] [--from ISO-or-ms] [--to ISO-or-ms] [--csv | --json]\nCharts: inspect charts /absolute/history-directory --output report.html [--session ID] [--agent NAME] [--model provider/model] [--from ISO-or-ms] [--to ISO-or-ms] [--max-points 1000] [--force]");
 } else if (args[0] === "models") {
   const { inspectModels: inspectModels2 } = await Promise.resolve().then(() => (init_modelcli(), exports_modelcli));
   await inspectModels2(args.slice(1));
 } else if (args[0] === "metrics" || args[0] === "charts") {
   const directory = args[1];
   if (!directory || directory.startsWith("--"))
-    throw new Error("Usage: inspect metrics /absolute/history-directory [--session ID] [--from ISO-or-ms] [--to ISO-or-ms] [--csv]");
+    throw new Error(`Use context-guard ${args[0]} --help for usage and examples`);
   const option = (name) => {
     const index = args.indexOf(name);
     if (index < 0)

package/dist/types/clihelp.d.ts

@@ -0,0 +1,2 @@
+export declare const mainHelp = "Context Guard \u2014 context monitoring for OpenCode V2\n\nStart here\n  In your project, run: opencode\n  Inside OpenCode, enter: /context-guard\n  The plugin loads with OpenCode; observe mode is the default.\n\nUsage: context-guard <command> [options]\n       context-guard <journal.jsonl> [--history | --json]\n\nCommands\n  dashboard tui   Open the standalone live terminal dashboard\n  models          Compare models across retained history\n  metrics         Export retained performance records as JSON or CSV\n  charts          Generate an interactive HTML report\n  <journal.jsonl> Inspect diagnostic session records\n\nExamples\n  context-guard dashboard tui\n  context-guard models /absolute/history-directory\n  context-guard charts /absolute/history-directory --output report.html\n  context-guard /absolute/events.jsonl --history\n\nHelp\n  context-guard <command> --help   Show options and examples\n  context-guard help journal      Explain diagnostic inspection\n  -h, --help                     Show help\n\nRequires Bun >=1.1.34; the standalone dashboard requires Bun >=1.3.0.\nFrom a source checkout, replace context-guard with bun run inspect.";
+export declare const commandHelp: Readonly<Record<string, string>>;

package/dist/types/dashboard/command.d.ts

@@ -1,5 +1,5 @@
 import type { DashboardConnectionOptions } from "./connection.js";
-export declare const dashboardHelp = "Usage: context-guard dashboard tui [--server URL] [--directory PATH]\nRead-only standalone terminal dashboard; never starts an OpenCode server.\nRequires an interactive terminal, Bun >=1.3.0 and @opentui/core@0.5.17.\nInstall the renderer beside this package: npm install @opentui/core@0.5.17\nLocal discovery defaults to the current directory.\nAn explicit server requires --directory with an owning absolute server path.\nRemote authentication: CONTEXT_GUARD_PASSWORD and optional CONTEXT_GUARD_USERNAME\n(default opencode). Credentials must never be supplied in the URL.\nKeys: 1 overview, 2 detail, 3 history, arrows/j/k move, / search, f filters,\nl location, w history window, r refresh, ? help, Escape back, q/Ctrl+C quit.";
+export declare const dashboardHelp = "Usage: context-guard dashboard tui [options]\nOpen a read-only live terminal dashboard for an existing OpenCode server.\n\nStart here\n  1. Keep an OpenCode server running with Context Guard registered.\n  2. Close OpenCode's native TUI before opening the standalone dashboard.\n  3. In the owning project directory, run: context-guard dashboard tui\n\nOptions\n  --directory PATH   Owning project directory (local default: current directory)\n  --server URL       Connect to an explicit server; requires --directory with\n                     an absolute server-side project path. Use HTTPS except\n                     on loopback. Credentials in URLs are rejected.\n  -h, --help         Show this help\n\nExamples\n  context-guard dashboard tui\n  context-guard dashboard tui --directory /absolute/project\n  context-guard dashboard tui --server https://server.example --directory /server/project\n\nRequirements\n  Interactive terminal and Bun >=1.3.0. The OpenTUI renderer is installed\n  automatically with CGP. This command never starts a server.\n\nAuthentication (explicit servers)\n  CONTEXT_GUARD_PASSWORD   Server password\n  CONTEXT_GUARD_USERNAME   Server username (default: opencode)\n\nKeys\n  1/2/3 overview/detail/history; arrows or j/k move; / search; f filters;\n  l location; w history window; r refresh; ? help; q or Ctrl+C quit.";
 export declare function parseDashboardArgs(args: readonly string[], cwd: string, env: Readonly<Record<string, string | undefined>>): DashboardConnectionOptions | "help";
 export declare function checkTerminalRuntime(version: string, interactive: boolean): void;
 export declare function loadTerminalRenderer(): Promise<typeof import("@opentui/core")>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cesarus777/opencode-cgp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": {
@@ -50,6 +50,7 @@
     "test:dashboard-terminal": "bun scripts/dashboard-terminal-live.ts"
   },
   "dependencies": {
+    "@opentui/core": "0.5.17",
     "@opencode/plugin": "2.0.29",
     "@opencode/client": "2.0.29"
   },
@@ -58,7 +59,6 @@
     "typescript": "5.9.3",
     "prettier": "3.6.2",
     "solid-js": "1.9.15",
-    "@opentui/core": "0.5.17",
     "@opentui/solid": "0.5.17",
     "@opencode/theme": "2.0.29"
   },
@@ -67,16 +67,12 @@
   },
   "peerDependencies": {
     "solid-js": ">=1.9.0",
-    "@opentui/core": ">=0.5.17",
     "@opentui/solid": ">=0.5.17"
   },
   "peerDependenciesMeta": {
     "solid-js": {
       "optional": true
     },
-    "@opentui/core": {
-      "optional": true
-    },
     "@opentui/solid": {
       "optional": true
     }