@cesarus777/opencode-cgp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0 — 2026-10-29
+
+- Add a Models screen to the standalone terminal dashboard: aggregate charts and statistics across retained root, child and archived sessions, exact agent filtering, model sorting, time windows, bucket inspection and paginated request details.
+- Add the read-only, location-scoped `context-guard.analytics.v1` RPC with bounded scans, short-lived snapshots and pagination independent of aggregate totals. Older servers preserve existing dashboard screens and report Models as unsupported.
+
+- Preserve history graph indentation in the standalone dashboard so axes, gap markers and filled columns stay aligned.
+- Keep all model statistics accessible in narrow terminals, scrolling through wrapped rows before advancing model selection.
+- Clarify that the dashboard can run in a separate terminal while working in OpenCode; closing the native TUI was a test setup condition.
+
+## 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,34 @@ 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 in a separate terminal tab, window or pane while continuing to work in OpenCode. Both clients connect to the same running server, with Context Guard registered in the owning location. Launch `context-guard dashboard tui` from the same project directory, or select the server and directory explicitly. Each full-screen TUI needs its own terminal. 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.
+
+The dashboard reads live updates without controlling OpenCode's sessions or server lifecycle. Concurrent dashboard/native-client PTYs pass local synthetic-provider validation on OpenCode 2.0.29 and 2.1.2; quitting the dashboard leaves the native client running.
 
 For an unreleased checkout:
 
@@ -95,16 +120,20 @@ 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
 ```
 
 Local discovery uses the current directory by default. An explicit server requires an absolute **server-side** `--directory`; it is passed unchanged. Set `CONTEXT_GUARD_PASSWORD` and optional `CONTEXT_GUARD_USERNAME` (default `opencode`) in the environment for remote authentication. Use HTTPS except on loopback. Credentials in URLs are rejected.
 
-Use `1` overview, `2` detail, `3` history, arrows or `j/k` to navigate, `/` to search, `f` for exact agent/model filters, `l` for location, `r` to refresh, and `?` for help. History uses Left/Right for six metrics, `w` for 5m/1h/24h/7d, and `[`/`]` to inspect exact samples or requests. Detail scrolls through full IDs and every exposed snapshot field. Editors take precedence over shortcuts; Enter applies and Escape cancels. Quit with `q` or Ctrl+C.
+Use `1` overview, `2` detail, `3` history, `4` models, arrows or `j/k` to navigate, `/` to search sessions, `f` for exact agent/model filters, `l` for location, `r` to refresh, and `?` for help. History uses Left/Right for six metrics, `w` for 5m/1h/24h/7d, and `[`/`]` to inspect exact samples or requests. Detail scrolls through full IDs and every exposed snapshot field. Editors take precedence over shortcuts; Enter applies and Escape cancels. Quit with `q` or Ctrl+C.
+
+For **aggregate statistics and charts for a model**, press **4**, select its full `provider/model` identity and press **Enter**. This combines completed requests from root, child and archived sessions in the owning location; no live session selection is needed. **Left/Right** selects weighted request TPS, TTFT median/p95, completed requests or reported output. **w** selects the time window, **[ / ]** inspects a bucket, **f** filters by agent, **d** toggles request details, and **n/p** pages models or requests. **s** cycles model-list sorting and **Escape** returns to the list. Existing inventory model filters seed model selection; session search does not restrict these aggregates.
+
+Models refreshes while visible using the dashboard's 30-second refresh interval; **r** requests a refresh (the server's archive cache lasts up to 30 seconds). Range totals precede pagination and chart reduction. Weighted request TPS divides reported output by summed matched request durations, including TTFT; concurrent durations add, so this measures request performance rather than fleet output per wall-clock second. In-flight requests appear after stream completion, which does not establish task success. TTFT is observed/approximate. Empty or ineligible buckets stay blank and partial coverage remains labeled. See [model analytics](docs/configuration.md#terminal-model-analytics) for server requirements and limits.
 
 The location editor's Tab key cycles up to four remembered owning directories; this is not server-wide discovery. History shows bounded retention, partial/downsampled data and gaps. Unknown measurements stay unknown, while stale occupancy remains labeled and pressure becomes unknown. Browser delivery is a later milestone. See [terminal validation and dependency sizes](docs/validation/dashboard-terminal-2026-10-28.md).
 
@@ -130,7 +159,7 @@ Enabling Context Guard after work has already started also shows the last report
 
 Per-session live TPS, average model throughput, average session throughput and observed TTFT appear in the selected session and child rows. Live TPS and TTFT use `~` to mark estimates; completed rates use provider totals. Configurable local history defaults to seven days with a 64 MiB total cap, independently of diagnostic telemetry. See [metric definitions and history exports](docs/configuration.md#live-performance-and-retained-history).
 
-Compare models across retained sessions with `bun run inspect models /absolute/history-directory --model provider/model` (installed: `context-guard models ...`). JSON/CSV summaries include weighted request TPS, TTFT mean/median/p95, eligibility counts and coverage limits. Use `--from`, `--to` and `--agent` to scope the analysis. This offline command precedes the planned TUI Models screen; see [analytics definitions](docs/configuration.md#offline-model-analytics).
+Compare models across retained sessions with `bun run inspect models /absolute/history-directory --model provider/model` (installed: `context-guard models ...`). JSON/CSV summaries include weighted request TPS, TTFT mean/median/p95, eligibility counts and coverage limits. Use `--from`, `--to` and `--agent` to scope the analysis. The standalone dashboard's Models screen shares these definitions; see [analytics definitions](docs/configuration.md#offline-model-analytics).
 
 Press **c** in the Context Guard panel for retained-history terminal charts. View one metric at a time with **Left / Right**, change the time window with **[ / ]**, and select an agent instance with **Up / Down**. Press **c** to return or **q** to close the panel; controls stay visible below the scrollable content. Generate a self-contained interactive browser report with `bun run charts /absolute/history-directory --output report.html`. It includes filters, UTC timestamp tooltips, request statistics and SVG export. Installed packages expose the same command as `context-guard charts ...` (Bun required). See [chart controls and limits](docs/configuration.md#performance-charts).