@cesarus777/opencode-cgp 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 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:
+
+- Add `context-guard dashboard tui` with a root/child session overview, complete snapshot details, retained performance history, search, filters and explicit location selection. Connections recover from interruptions and retain labeled stale values.
+- Add `context-guard models /absolute/history-directory` to compare models across retained sessions. JSON/CSV exports include duration-weighted request TPS, TTFT mean/median/p95, eligibility counts, deduplication and coverage. Filter by exact model/agent and completion-time range.
+- Export harness-independent `aggregateModels` through the core package entry.
+- Correct context chart threshold rendering and stale colors. Held bars preserve the preceding measurement's fractional height. Pauses temporarily mute the latest column; repeated unchanged/held observations reuse it instead of consuming history space.
+
+The standalone terminal command requires Bun >=1.3.0 and the optional `@opentui/core@0.5.17` renderer. Server/core and offline diagnostic/analytics commands retain Bun >=1.1.34 support. OpenCode SDK dependencies remain pinned at 2.0.29; local synthetic-provider validation also covers OpenCode 2.1.2.
+
+Model analytics uses the bounded retained archive (default seven days / 64 MiB), not permanent history. Its Models screen, analytics RPC and durable request ledger remain planned. The browser dashboard remains planned. Genuine-provider timing and cross-machine terminal validation remain unverified.

package/README.md

@@ -6,11 +6,11 @@ Targets **`@opencode/plugin@2.0.29`**. The published SDK, official documentation
 
 ## Install
 
-The intended npm distribution is **`@cesarus777/opencode-cgp`**. It becomes available after this repository's first publication. The unscoped `opencode-context-guard` name belongs to another project; do not install it expecting this plugin.
+The npm package is **`@cesarus777/opencode-cgp`**. The unscoped `opencode-context-guard` name belongs to another project; do not install it expecting this plugin.
 
 Minimum supported host: **OpenCode V2 2.0.29**. Versions 2.0.29 and 2.1.2 have been tested locally with a synthetic provider; V1 is unsupported.
 
-After this project's first publication, register the global package through the native manager:
+Register the global package through the native manager:
 
 ```sh
 opencode plugin add @cesarus777/opencode-cgp@latest
@@ -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.2.5` keeps the context chart continuous through pauses, retains its history between sidebar and panel, and shows confirmed compaction drops. It also adds local OpenCode 2.1.2 validation.
+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.2.1
+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):
@@ -64,7 +64,7 @@ For development or unreleased Git revisions, V2 supports npm-compatible Git targ
 opencode plugin add 'github:cesarus777/opencode-cgp#master'
 ```
 
-Replace `master` with a version tag or full commit hash to pin a revision. Git installs require Bun and development dependencies to run `prepare`; unlike npm artifacts they build from source. Prefer an exact published prerelease such as `@cesarus777/opencode-cgp@0.2.0-beta.1` after publication. Git preparation has not been verified with the real plugin manager; use a built local checkout if it fails.
+Replace `master` with a version tag or full commit hash to pin a revision. Git installs require Bun and development dependencies to run `prepare`; unlike npm artifacts they build from source. Prefer an exact published npm version for reproducible installs. Git preparation has not been verified with the real plugin manager; use a built local checkout if it fails.
 
 Contributors can build and register a checkout without publishing:
 
@@ -82,6 +82,55 @@ 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**. 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:
+
+```sh
+bun install --frozen-lockfile
+bun run build
+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 into a separate client directory, then launch with Bun >=1.3.0:
+
+```sh
+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.
+
+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).
+
 ## Thresholds
 
 | Type        | Example  | Trigger                                    |
@@ -104,6 +153,8 @@ 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).
+
 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).
 
 ## Inspect