@osovv/vv-opencode 1.2.11 → 1.3.0

package/dist/tui/analytics/indicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indicator.js","sourceRoot":"","sources":["../../../src/tui/analytics/indicator.tsx"],"names":[],"mappings":";AA0BA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAoBxE,MAAM,oBAAoB,GAA0B;IAClD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC;YACvC,KAAK,EAAE,WAAW;YAClB,YAAY,EAAE,IAAI;YAClB,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS;SAC9B,CAAC,CAAC;QACH,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvD,CAAC;IACD,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,eAAM,KAAK,EAAE,EAAE,KAAK,EAAE,YAAG,KAAK,CAAC,IAAI,GAAQ;CAC3E,CAAC;AAEF,oCAAoC;AACpC,2FAA2F;AAC3F,MAAM,UAAU,0BAA0B;IAIxC,IAAI,KAAK,GAAoB;QAC3B,KAAK,EAAE,CAAC;QACR,aAAa,EAAE,CAAC;QAChB,SAAS,EAAE,CAAC;QACZ,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,CAAC;KACT,CAAC;IACF,OAAO;QACL,SAAS,CAAC,IAAoB;YAC5B,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;gBAAE,OAAO;YACxC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAGhC,CAAC;YACF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAChD,KAAK,GAAG;gBACN,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC;gBACtB,aAAa,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzE,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS;gBACtC,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,UAAU;gBACzC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;aAC3C,CAAC;QACJ,CAAC;QACD,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,cAAc,CAAC,KAAsB;IACnD,IAAI,KAAK,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3E,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED,6EAA6E;AAC7E,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC;AACD,kCAAkC;AAElC,iCAAiC;AACjC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,GAAiB,EACjB,OAAuB,EACvB,eAAsC,oBAAoB;IAE1D,IAAI,OAAO,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO;IACvC,IAAI,CAAC,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAAE,OAAO;IAE/C,MAAM,WAAW,GAAG,0BAA0B,EAAE,CAAC;IACjD,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,EAAE;QACjE,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClD,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAErC,IAAI,CAAC;QACH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;YACjB,KAAK,EAAE;gBACL,oBAAoB,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;oBACpC,IAAI,KAAK,CAAC,UAAU,KAAK,gBAAgB,CAAC,GAAG,CAAC;wBAAE,OAAO,SAAS,CAAC;oBACjE,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC;oBAChD,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;wBAAE,OAAO,SAAS,CAAC;oBAC7C,OAAO,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;gBACrE,CAAC;aACF;SACF,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,SAAS,gBAAgB,CAAC,GAAiB;IACzC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;IAChC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;QAClD,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC;QAC1C,OAAO,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,0DAA0D;AAC1D,SAAS,SAAS,CAAC,GAAiB,EAAE,IAA4B;IAChE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;IAChC,MAAM,IAAI,GACR,IAAI,KAAK,OAAO;QACd,CAAC,CAAC,KAAK,CAAC,OAAO;QACf,CAAC,CAAC,IAAI,KAAK,QAAQ;YACjB,CAAC,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,IAAI,KAAK,KAAK;gBACd,CAAC,CAAC,KAAK,CAAC,KAAK;gBACb,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IAC1B,OAAO,QAAQ,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC;AAC5D,CAAC"}

package/dist/tui/branding/footer.d.ts

@@ -0,0 +1,14 @@
+import type { JSX } from "@opentui/solid";
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+export type BrandingDependencies = {
+    /** Renders the label node; defaults to the muted span. */
+    renderLabel: (text: string, color: string) => JSX.Element;
+};
+/** The rendered label, e.g. "vvoc v1.2.11". */
+export declare function brandingFooterLabel(): string;
+/**
+ * Registers the branding footer in the "sidebar_footer" host slot.
+ * Always on (independent of analytics config); returns silently when the slot
+ * API is unavailable or registration fails.
+ */
+export declare function registerBrandingFooter(api: TuiPluginApi, dependencies?: BrandingDependencies): void;

package/dist/tui/branding/footer.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "@opentui/solid/jsx-runtime";
+import { getPackageVersionSync } from "../../lib/package.js";
+const DEFAULT_DEPENDENCIES = {
+    renderLabel: (text, color) => _jsx("span", { style: { color }, children: text }),
+};
+/** The rendered label, e.g. "vvoc v1.2.11". */
+export function brandingFooterLabel() {
+    return `vvoc v${getPackageVersionSync()}`;
+}
+// START_BLOCK_REGISTER_BRANDING_FOOTER
+/**
+ * Registers the branding footer in the "sidebar_footer" host slot.
+ * Always on (independent of analytics config); returns silently when the slot
+ * API is unavailable or registration fails.
+ */
+export function registerBrandingFooter(api, dependencies = DEFAULT_DEPENDENCIES) {
+    if (typeof api.slots?.register !== "function")
+        return;
+    try {
+        api.slots.register({
+            slots: {
+                sidebar_footer: () => {
+                    const muted = api.theme.current.textMuted;
+                    const color = `rgba(${muted.r}, ${muted.g}, ${muted.b}, ${muted.a})`;
+                    return dependencies.renderLabel(brandingFooterLabel(), color);
+                },
+            },
+        });
+    }
+    catch {
+        // Fail-soft: no footer for this session.
+    }
+}
+//# sourceMappingURL=footer.js.map

package/dist/tui/branding/footer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"footer.js","sourceRoot":"","sources":["../../../src/tui/branding/footer.tsx"],"names":[],"mappings":";AAuBA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,MAAM,oBAAoB,GAAyB;IACjD,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,eAAM,KAAK,EAAE,EAAE,KAAK,EAAE,YAAG,IAAI,GAAQ;CACpE,CAAC;AAEF,+CAA+C;AAC/C,MAAM,UAAU,mBAAmB;IACjC,OAAO,SAAS,qBAAqB,EAAE,EAAE,CAAC;AAC5C,CAAC;AAED,uCAAuC;AACvC;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAiB,EACjB,eAAqC,oBAAoB;IAEzD,IAAI,OAAO,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,UAAU;QAAE,OAAO;IACtD,IAAI,CAAC;QACH,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;YACjB,KAAK,EAAE;gBACL,cAAc,EAAE,GAAG,EAAE;oBACnB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;oBAC1C,MAAM,KAAK,GAAG,QAAQ,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC;oBACrE,OAAO,YAAY,CAAC,WAAW,CAAC,mBAAmB,EAAE,EAAE,KAAK,CAAC,CAAC;gBAChE,CAAC;aACF;SACF,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;AACH,CAAC"}

package/dist/tui.js

@@ -1,27 +1,45 @@
 // FILE: src/tui.tsx
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Publish the default @osovv/vv-opencode/tui module containing the managed context inspector.
+//   PURPOSE: Publish the default @osovv/vv-opencode/tui module containing the managed context inspector, analytics indicator, and branding footer.
 //   SCOPE: Stable TUI package entrypoint and module identity only.
-//   DEPENDS: [@opencode-ai/plugin/tui, src/tui/context/plugin.ts]
-//   LINKS: [M-PLUGIN-CONTEXT-TUI, V-M-PLUGIN-CONTEXT-TUI]
+//   DEPENDS: [@opencode-ai/plugin/tui, @opencode-ai/plugin, src/tui/context/plugin.ts, src/tui/analytics/indicator.tsx, src/tui/branding/footer.tsx]
+//   LINKS: [M-PLUGIN-CONTEXT-TUI, M-TUI-ANALYTICS-INDICATOR, M-TUI-BRANDING-FOOTER, V-M-PLUGIN-CONTEXT-TUI]
 //   ROLE: BARREL
 //   MAP_MODE: SUMMARY
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   default - OpenCode TUI plugin module registering the /context inspector.
+//   default - OpenCode TUI plugin module registering /context, the analytics indicator, and the branding footer.
 //   ContextTuiPlugin - Named TUI plugin factory for direct consumers and tests.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [C-CONTEXT-TUI-PLUGIN - Added the public TUI package subpath.]
+//   LAST_CHANGE: [2026-08-19-cache-hit-rate-analytics - Registered the live cache indicator and vvoc version footer alongside /context.]
 // END_CHANGE_SUMMARY
 import { ContextTuiPlugin } from "./tui/context/plugin.js";
+import { registerAnalyticsIndicator } from "./tui/analytics/indicator.js";
+import { registerBrandingFooter } from "./tui/branding/footer.js";
 export { ContextTuiPlugin };
+// START_BLOCK_TUI_MODULE
 const plugin = {
     id: "vvoc-context",
-    tui: ContextTuiPlugin,
+    tui: async (api, options, meta) => {
+        await ContextTuiPlugin(api, options, meta);
+        try {
+            await registerAnalyticsIndicator(api, options);
+        }
+        catch {
+            // Fail-soft: indicator unavailable for this session.
+        }
+        try {
+            registerBrandingFooter(api);
+        }
+        catch {
+            // Fail-soft: footer unavailable for this session.
+        }
+    },
 };
+// END_BLOCK_TUI_MODULE
 export default plugin;
 //# sourceMappingURL=tui.js.map

package/dist/tui.js.map

@@ -1 +1 @@
-{"version":3,"file":"tui.js","sourceRoot":"","sources":["../src/tui.tsx"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,iBAAiB;AACjB,wBAAwB;AACxB,yGAAyG;AACzG,mEAAmE;AACnE,kEAAkE;AAClE,0DAA0D;AAC1D,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,6EAA6E;AAC7E,gFAAgF;AAChF,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,gFAAgF;AAChF,qBAAqB;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,MAAM,MAAM,GAAqC;IAC/C,EAAE,EAAE,cAAc;IAClB,GAAG,EAAE,gBAAgB;CACtB,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"tui.js","sourceRoot":"","sources":["../src/tui.tsx"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,iBAAiB;AACjB,wBAAwB;AACxB,mJAAmJ;AACnJ,mEAAmE;AACnE,qJAAqJ;AACrJ,4GAA4G;AAC5G,iBAAiB;AACjB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,iHAAiH;AACjH,gFAAgF;AAChF,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,yIAAyI;AACzI,qBAAqB;AAGrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,yBAAyB;AACzB,MAAM,MAAM,GAAqC;IAC/C,EAAE,EAAE,cAAc;IAClB,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAChC,MAAM,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,0BAA0B,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;QACD,IAAI,CAAC;YACH,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;IACH,CAAC;CACF,CAAC;AACF,uBAAuB;AAEvB,eAAe,MAAM,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vv-opencode",
-  "version": "1.2.11",
+  "version": "1.3.0",
   "description": "A curated, opinionated set of OpenCode plugins for spec-first, review-driven, safer agentic development.",
   "type": "module",
   "main": "./dist/index.js",
@@ -77,6 +77,10 @@
     "./plugins/tool-history-compaction": {
       "types": "./dist/plugins/tool-history-compaction/index.d.ts",
       "import": "./dist/plugins/tool-history-compaction/index.js"
+    },
+    "./plugins/analytics": {
+      "types": "./dist/plugins/analytics/index.d.ts",
+      "import": "./dist/plugins/analytics/index.js"
     }
   },
   "scripts": {
@@ -89,7 +93,7 @@
     "grace:check": "bun scripts/check-grace-markup.ts",
     "test": "bun test",
     "check": "bun run typecheck && bun run lint && bun run fmt:check && bun run grace:check && bun test",
-    "pack:check": "bun run build && bun -e \"const root = await import('./dist/index.js'); if (!('GuardianPlugin' in root)) throw new Error('dist root export missing GuardianPlugin'); if (!('HashlineEditPlugin' in root)) throw new Error('dist root export missing HashlineEditPlugin'); if (!('ModelRolesPlugin' in root)) throw new Error('dist root export missing ModelRolesPlugin'); if (!('SystemContextInjectionPlugin' in root)) throw new Error('dist root export missing SystemContextInjectionPlugin'); if (!('WorkflowPlugin' in root)) throw new Error('dist root export missing WorkflowPlugin'); if (!('SecretsRedactionPlugin' in root)) throw new Error('dist root export missing SecretsRedactionPlugin'); if (!('WebToolsPlugin' in root)) throw new Error('dist root export missing WebToolsPlugin'); const tui = await import('./dist/tui.js'); if (!tui.default || typeof tui.default.tui !== 'function') throw new Error('dist TUI export missing default tui module'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/hashline-edit/index.js'); await import('./dist/plugins/model-roles/index.js'); await import('./dist/plugins/system-context-injection/index.js'); await import('./dist/plugins/workflow/index.js'); await import('./dist/plugins/secrets-redaction/index.js'); await import('./dist/plugins/web-tools/index.js')\" && npm pack --dry-run",
+    "pack:check": "bun run build && bun -e \"const root = await import('./dist/index.js'); if (!('GuardianPlugin' in root)) throw new Error('dist root export missing GuardianPlugin'); if (!('HashlineEditPlugin' in root)) throw new Error('dist root export missing HashlineEditPlugin'); if (!('ModelRolesPlugin' in root)) throw new Error('dist root export missing ModelRolesPlugin'); if (!('SystemContextInjectionPlugin' in root)) throw new Error('dist root export missing SystemContextInjectionPlugin'); if (!('WorkflowPlugin' in root)) throw new Error('dist root export missing WorkflowPlugin'); if (!('SecretsRedactionPlugin' in root)) throw new Error('dist root export missing SecretsRedactionPlugin'); if (!('WebToolsPlugin' in root)) throw new Error('dist root export missing WebToolsPlugin'); if (!('AnalyticsPlugin' in root)) throw new Error('dist root export missing AnalyticsPlugin'); const tui = await import('./dist/tui.js'); if (!tui.default || typeof tui.default.tui !== 'function') throw new Error('dist TUI export missing default tui module'); await import('./dist/plugins/guardian/index.js'); await import('./dist/plugins/hashline-edit/index.js'); await import('./dist/plugins/model-roles/index.js'); await import('./dist/plugins/system-context-injection/index.js'); await import('./dist/plugins/workflow/index.js'); await import('./dist/plugins/secrets-redaction/index.js'); await import('./dist/plugins/web-tools/index.js'); await import('./dist/plugins/analytics/index.js')\" && npm pack --dry-run",
     "tui:local": "bun scripts/tui-local.ts",
     "release:check": "bun scripts/release-check.ts",
     "release:bump": "bun scripts/release-bump.ts",

package/schemas/vvoc/v3.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@1.2.11/schemas/vvoc/v3.json",
+  "$id": "https://cdn.jsdelivr.net/npm/@osovv/vv-opencode@1.3.0/schemas/vvoc/v3.json",
   "title": "vvoc config",
   "description": "Canonical vvoc configuration document.",
   "type": "object",

package/templates/skills/vvoc-usage-analytics/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: vvoc-usage-analytics
+description: Use when the user asks about token usage, cache hit rate, cache efficiency, model or provider consumption, session costs, or whether a vvoc release or OpenCode upgrade changed caching behavior. Runs read-only analysis over vvoc analytics (CLI and JSONL) and historical opencode.db data, then reports findings without modifying anything.
+---
+
+<skill>
+<identity>
+You are the vvoc-usage-analytics skill. You turn usage questions into evidence-based answers. You know the three data sources, their coverage boundaries, and the exact metric definitions, and you never guess a number you did not read from a source. You are an analyst, not a fixer: you report findings and leave changes to the user.
+</identity>
+
+<scope>
+<rule>OpenCode's database is strictly read-only: always connect with a `?mode=ro` URI (see references/opencode-db-queries.md). Never run UPDATE/INSERT/DELETE/DDL against it, even diagnostically.</rule>
+<rule>Never modify, delete, truncate, or "repair" analytics JSONL files, and never suggest doing so as a fix.</rule>
+<rule>Read-only also means no config changes: do not toggle plugins, rewrite vvoc.json, or restart anything unless the user explicitly asks for that as a separate task.</rule>
+<rule>Report findings only. Recommendations are fine; silent "fixes" to telemetry or config are out of scope.</rule>
+<rule>If a source is unavailable (no db file, empty JSONL, sqlite3 missing), say so explicitly and continue with the sources that exist instead of implying there was no usage.</rule>
+</scope>
+
+<data_sources>
+<source name="vvoc CLI" precedence="1">
+Prefer `vvoc analytics cache-hit-rate` for anything it can answer. It already dedupes, filters, groups, and formats:
+- Trend: `vvoc analytics cache-hit-rate --group-by day|week|month --since 30d`
+- Compare vvoc releases: `--group-by vvoc --since 30d`
+- Compare OpenCode versions: `--group-by opencode --since 30d`
+- Per session / model / provider / project: `--group-by session|model|provider|project`
+- Filters and output: `--since`/`--until` accept `Nd`/`Nw`/`Nm` or `YYYY-MM-DD`; `--project` is a case-insensitive substring; `--order steps|hit-rate|date`; `--limit N`; `--json` for machine-readable rows.
+Note: CLI coverage starts when the analytics plugin first ran (JSONL start date), and only steps after an OpenCode restart are recorded.
+</source>
+<source name="analytics JSONL" precedence="2">
+Use the raw monthly files `$XDG_DATA_HOME/vvoc/analytics/usage-YYYY-MM.jsonl` when the question needs something the CLI does not compute (unusual groupings, per-agent or per-message drill-downs, exact record inspection). Lines are JSON objects: `kind` is `usage` (one per step-finish part, dedupe by `partID` keeping the last) or `session` (dedupe by `sessionID`). jq, python, or bun one-liners are all fine — reading only.
+</source>
+<source name="opencode.db history" precedence="3">
+Use OpenCode's own SQLite database for history that predates the plugin and for per-session cost aggregates: `~/.local/share/opencode/opencode.db` (override via $OPENCODE_DATA_HOME when the user has one). It holds months of step-finish parts with tokens, session cost/token totals, and `session.version` = the OpenCode version. Always read it with the validated snippets in references/opencode-db-queries.md (`?mode=ro` URI). This is the only source that can answer "how did caching look before vvoc analytics existed" and "what did sessions cost".
+</source>
+</data_sources>
+
+<workflow>
+<step>Clarify the question into: metric(s), grouping, and time range. If the user's ask is vague ("is my cache ok?"), default to hit rate grouped by day for the last 14 days plus coverage, then offer deeper cuts.</step>
+<step>Pick the narrowest source that can answer it: CLI first; JSONL only for cuts the CLI lacks; opencode.db only for pre-plugin history or cost-per-session questions. State which source you are using and why.</step>
+<step>Run the query read-only. For db queries, use the reference snippets; adapt only filters (WHERE/LIMIT), not the hit-rate formula.</step>
+<step>Sanity-check coverage before answering: how many steps does the range contain, what share is cache-eligible (coverage), and where does each source's data begin. A hit rate over 12 steps means more than one over 12,000.</step>
+<step>Present findings as a compact table plus 2-4 sentences of interpretation. Every answer names its data source and time range. When mixing sources, state the JSONL start boundary explicitly so the user knows which numbers come from where.</step>
+<step>Offer the natural follow-up cut (by model, by session, before/after a date) instead of running all of them unasked.</step>
+</workflow>
+
+<metric_definitions>
+<metric name="cache hit rate">Token-weighted: `cacheRead / (cacheRead + cacheWrite + input)` summed over cache-eligible steps. A step is cache-eligible when `cacheRead + cacheWrite > 0`. Identical to the CLI and the SQL reference — do not invent per-step averaging.</metric>
+<metric name="coverage">`eligibleSteps / steps`. Low coverage means the provider rarely reports cache tokens; say that, do not hide it behind a hit rate.</metric>
+<metric name="n/a">Groups with zero eligible steps have no hit rate. Report `n/a` — never `0%` — and show coverage so "provider does not report cache" stays distinguishable from "cache misses".</metric>
+</metric_definitions>
+
+<output_discipline>
+<rule>Tables over prose for any comparison; columns in the CLI's spirit (GROUP, STEPS, COVERAGE, HIT-RATE, CACHE-READ, CACHE-WRITE, FRESH-IN or their subset).</rule>
+<rule>Every number carries its source (CLI / JSONL / opencode.db) and time range.</rule>
+<rule>State validation context for db queries: snippets were validated against OpenCode 1.18.x; if columns error out, report the schema mismatch instead of improvising SQL guesses.</rule>
+<rule>Interpretation stays factual: rising/falling hit rate, coverage share, outliers. Avoid unfounded causal claims; a vvoc version bump and a project switch can co-occur.</rule>
+</output_discipline>
+</skill>

package/templates/skills/vvoc-usage-analytics/references/opencode-db-queries.md

@@ -0,0 +1,113 @@
+# opencode.db read-only queries
+
+Validated against OpenCode **1.18.x** on a real 5.7 GB database (2026-08). If a column
+errors out after an OpenCode upgrade, report the schema mismatch — do not improvise
+guesses about the new schema.
+
+## Connection — always read-only
+
+OpenCode keeps this database open (WAL). Concurrent readers are fine; writers are not.
+
+```bash
+sqlite3 "file:$HOME/.local/share/opencode/opencode.db?mode=ro" "SELECT ..."
+```
+
+No `sqlite3` CLI? Use bun:sqlite read-only:
+
+```ts
+import { Database } from "bun:sqlite";
+const db = new Database(`${process.env.HOME}/.local/share/opencode/opencode.db`, { readonly: true });
+```
+
+Respect `$XDG_DATA_HOME`/`$OPENCODE_DATA_HOME` if the user has a custom data dir
+(check the effective OpenCode config before assuming the default path).
+
+## Schema orientation
+
+- `session` — one row per session. `version` is the **OpenCode version** that created
+  it. Cost/token aggregate columns: `cost`, `tokens_input`, `tokens_output`,
+  `tokens_reasoning`, `tokens_cache_read`, `tokens_cache_write`. `time_created` is
+  epoch **milliseconds**.
+- `message` — one row per message; `data` JSON carries `role`, `providerID`,
+  `modelID`, `agent`, `cost`, `tokens` for assistant messages.
+- `part` — one row per message part; `data` JSON with `type: "step-finish"` carries
+  final per-step tokens: `tokens.input`, `tokens.output`, `tokens.reasoning`,
+  `tokens.cache.read`, `tokens.cache.write`.
+
+## Hit-rate formula (must match the vvoc CLI)
+
+`cacheRead / (cacheRead + cacheWrite + input)` **summed over cache-eligible steps**
+( eligible := cache.read + cache.write > 0 ), token-weighted. `NULLIF` guards the
+division; NULL hit rate means "no eligible steps" → report `n/a`, not 0%.
+
+## (a) Cache hit rate by OpenCode version
+
+```sql
+SELECT s.version AS opencode,
+       COUNT(*) AS steps,
+       SUM(CASE WHEN json_extract(p.data,'$.tokens.cache.read')
+                 + json_extract(p.data,'$.tokens.cache.write') > 0
+            THEN 1 ELSE 0 END) AS eligible,
+       ROUND(100.0 * SUM(json_extract(p.data,'$.tokens.cache.read')) /
+             NULLIF(SUM(json_extract(p.data,'$.tokens.cache.read')
+                      + json_extract(p.data,'$.tokens.cache.write')
+                      + json_extract(p.data,'$.tokens.input')), 0), 1) AS hit_pct
+FROM part p JOIN session s ON s.id = p.session_id
+WHERE json_extract(p.data,'$.type') = 'step-finish'
+GROUP BY s.version
+ORDER BY MIN(s.time_created) DESC;
+```
+
+## (b) Cache hit rate by month
+
+```sql
+SELECT strftime('%Y-%m', p.time_created/1000, 'unixepoch') AS month,
+       COUNT(*) AS steps,
+       ROUND(100.0 * SUM(json_extract(p.data,'$.tokens.cache.read')) /
+             NULLIF(SUM(json_extract(p.data,'$.tokens.cache.read')
+                      + json_extract(p.data,'$.tokens.cache.write')
+                      + json_extract(p.data,'$.tokens.input')), 0), 1) AS hit_pct
+FROM part p
+WHERE json_extract(p.data,'$.type') = 'step-finish'
+GROUP BY month
+ORDER BY month DESC;
+```
+
+## (c) Recent sessions: cost and token totals
+
+Straight from the session table — no JSON extraction needed:
+
+```sql
+SELECT substr(s.id, 1, 8) AS session,
+       s.title,
+       s.version AS opencode,
+       ROUND(s.cost, 3) AS cost,
+       s.tokens_cache_read  AS cache_read,
+       s.tokens_cache_write AS cache_write,
+       s.tokens_input       AS fresh_in,
+       datetime(s.time_created/1000, 'unixepoch') AS started
+FROM session s
+ORDER BY s.time_created DESC
+LIMIT 20;
+```
+
+Caveat: `cost` is what OpenCode recorded (often `0` for subscription/zai providers);
+say "recorded cost" in findings, do not treat 0 as free.
+
+## (d) Step-finish counts by provider/model
+
+Model attribution lives on the message, so join through it:
+
+```sql
+SELECT json_extract(m.data,'$.providerID') AS provider,
+       json_extract(m.data,'$.modelID')    AS model,
+       COUNT(*) AS steps
+FROM part p JOIN message m ON m.id = p.message_id
+WHERE json_extract(p.data,'$.type') = 'step-finish'
+GROUP BY provider, model
+ORDER BY steps DESC;
+```
+
+To get hit rate per model instead of counts, wrap snippet (a)'s `SUM/NULLIF`
+expression in the same query but group by `json_extract(m.data,'$.providerID') ||
+'/' || json_extract(m.data,'$.modelID')`.